---
title: "入门"
description: "汇总 OpenCode 入门路径，按 CLI、TUI、分享和 IDE 入口建立第一条可运行闭环。"
verifiedAt: "2026-05-09"
---

OpenCode 入门不是把所有安装命令背一遍，而是在一台真实开发机器上跑通第一条安全闭环：能启动、能连接模型、能读项目、能受控修改、能撤销、知道下一步该配置什么。

<img
  src="/images/opencode/tui-screenshot.png"
  alt="使用 opencode 主题的 OpenCode TUI"
  width="1824"
  height="1488"
  loading="eager"
/>

> [!NOTE]
> **这一篇用 15 分钟换什么**：不是“装上就算完”，而是拿到一条可复现的第一天路径。跑完以后，你应该能在真实 Git 仓库里让 OpenCode 完成一次只读分析和一次限定范围的低风险修改。

## 先跑通安全闭环

第一次使用 OpenCode，不要先研究 plugin、MCP、LSP 或团队治理。先按下面顺序确认基础能力。

```mermaid
flowchart LR
    Terminal["现代终端"] --> Install["安装 opencode"]
    Install --> Provider["连接 provider"]
    Provider --> Project["进入真实 Git 仓库"]
    Project --> Init["/init 生成 AGENTS.md 初稿"]
    Init --> ReadOnly["第一轮只读分析"]
    ReadOnly --> WriteSmall["第一轮限定写入"]
    WriteSmall --> Undo["确认 /undo 和 /redo"]
    Undo --> Next["进入个性化配置"]

    style Terminal fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style ReadOnly fill:#dcfce7,stroke:#22c55e
    style WriteSmall fill:#fef3c7,stroke:#f59e0b
    style Undo fill:#fee2e2,stroke:#ef4444
```

这条路径故意保守。Coding agent 会读取文件、修改文件、运行命令和调用外部模型。先证明它能被约束，再扩大任务范围。

## 1. 准备终端和模型密钥

要在终端里使用 OpenCode，你至少需要两样东西：

- **现代终端**：TUI 显示、快捷键、拖放图片、交互输入都依赖终端能力。
- **LLM provider API key**：OpenCode 是 agent 运行时，推理仍由模型 provider 提供。

官方文档列出的现代终端包括 WezTerm、Alacritty、Ghostty 和 Kitty。macOS 或 Linux 用户如果已经在用 Ghostty、WezTerm 或 iTerm2，通常可以直接开始。

> [!IMPORTANT]
> **密钥只进入凭据系统，不进入项目文件**：第一次上手用 `/connect` 或 `opencode auth login` 连接 provider。项目里的 `AGENTS.md`、rules、commands 和配置文件只写工作流约束，不写真实 API key。

## 2. 安装 OpenCode

官方最直接的安装方式是安装脚本：

```bash
curl -fsSL https://opencode.ai/install | bash
```

如果你偏好包管理器，可以选更符合当前机器的方式。

- **macOS / Linux**：`brew install anomalyco/tap/opencode` 或安装脚本。
- **Node.js 环境**：`npm install -g opencode-ai`。
- **Windows**：优先 WSL，再考虑 Chocolatey、Scoop、npm、Mise、Docker 或 release binary。
- **Arch Linux**：`sudo pacman -S opencode` 或 AUR 的 `opencode-bin`。

Homebrew 用户优先使用 OpenCode 官方 tap：

```bash
brew install anomalyco/tap/opencode
```

Node.js 用户最常用 npm：

```bash
npm install -g opencode-ai
```

Windows 可以直接装，但 coding agent 对 shell、Git、语言工具链和文件权限依赖很重。第一次学习建议用 WSL，这样更接近多数开源项目默认假设的 Linux 开发环境。

安装后先验证命令，不要马上进入项目改代码：

```bash
opencode --help
```

如果命令找不到，先查 PATH 和安装位置：

```bash
which opencode
echo $PATH
```

## 3. 连接模型 provider

启动 TUI 后输入：

```txt
/connect
```

第一次可以选择 OpenCode Zen，按照页面提示前往 `opencode.ai/auth` 登录、添加账单信息并复制 API key。OpenCode 也支持其他 provider，后续可以在 provider 目录里选择。

如果你更喜欢 CLI 管理凭据，也可以使用：

```bash
opencode auth login
opencode auth list
```

两种方式的区别很简单：

- `/connect` 适合第一次在 TUI 里跑通。
- `opencode auth login` 适合在终端里管理和复查 provider 凭据。
- `.env` 或环境变量适合已经有统一凭据管理的人。

> [!WARNING]
> **不要把 provider 连接失败当成 OpenCode 坏了**：先确认 API key、账单状态、网络代理、provider 可用性，再排查 OpenCode 配置。

## 4. 在真实项目里初始化

配置好 provider 后，进入你真正要处理的项目目录。

```bash
cd /path/to/project
opencode
```

然后运行：

```txt
/init
```

OpenCode 会分析项目并生成项目根目录的 `AGENTS.md` 初稿。这个文件应该提交到 Git，因为它是团队共享项目上下文的入口，适合写项目结构、包管理器、测试命令、编码约定、禁止修改范围和发布边界。

> [!IMPORTANT]
> **`/init` 不是最终规范**：它生成的是初稿。提交前必须人工检查，尤其是测试命令、部署命令、敏感目录、生成物目录和“哪些文件不能改”。

## 5. 第一轮只做只读任务

第一次任务不要让 OpenCode 改文件。先验证它能不能正确理解仓库。

```txt
先快速阅读这个仓库的目录结构，不要修改文件。
请按这四点输出：
1. 项目的技术栈和入口文件。
2. 主要模块分别做什么。
3. 你会优先阅读哪些文件来理解项目。
4. 你现在还不确定、需要我确认的问题。
```

这条提示词同时做三件事：

- 限制动作：明确“不要修改文件”。
- 验证上下文：看它是否真的读到了项目结构。
- 暴露不确定性：要求它说出不知道的地方。

需要引用具体文件时，按 `@` 模糊搜索文件：

```txt
How is authentication handled in @packages/functions/src/api/index.ts
```

如果第一轮只读任务就开始改文件，先停下来检查模式、提示词和权限，不要继续扩大任务范围。

## 6. 第一轮写入只改单文件

只读任务稳定后，再做一个低风险写入。优先选择 README、文档或测试说明，不要上来重构核心模块。

```txt
只修改 README.md 中的安装说明，把命令整理成 macOS、Linux、Windows 三段。
不要修改其他文件。
改完后先解释 diff，再告诉我建议运行什么检查命令。
```

合格结果应该满足四点：

- 只改你指定的文件。
- 能解释具体 diff。
- 能给出合理的验证命令。
- 不会自作主张 commit、push 或部署。

如果任务稍复杂，先按 **Tab** 切到 Plan mode，让 OpenCode 只给计划；计划确认后再按 **Tab** 回到 Build mode 执行。这个动作比“事后回滚一堆无关文件”成本低得多。

## 7. 会撤销，才算能继续

OpenCode 支持撤销和重做当前会话产生的修改：

```txt
/undo
```

```txt
/redo
```

第一次低风险写入后，至少确认你知道这两个命令的用途。真正进入大范围修改前，还要配合 Git diff 查看文件边界。

> [!TIP]
> **能撤销不等于可以随便改**：`/undo` 适合修正当前会话里的不满意结果。涉及数据库迁移、外部服务、发布部署、删除文件和批量格式化时，仍然要先看计划和影响范围。

## 8. 分享默认手动触发

OpenCode 会话可以通过 `/share` 生成分享链接：

```txt
/share
```

对话默认不会自动分享。分享前要确认当前会话里没有密钥、账号、客户数据、内部路径、未公开仓库信息或商业策略。敏感项目宁愿不分享，也不要事后补救。

## 9. 继续做个性化配置

跑通第一轮以后，再进入个性化配置：

- 主题和 keybinds：让 TUI 更顺手。
- rules 和 `AGENTS.md`：沉淀项目规则。
- commands：把重复提示词变成 slash command。
- formatters：把格式化交给确定性工具。
- agents、skills、plugins、MCP：把复杂能力拆到更清晰的边界里。

不要把这些配置一次性全开。每次只加一种能力，并用真实任务验证它是否减少了重复沟通或降低了出错概率。

## 接下来去哪

<Cards>
  <Card title="CLI 入口" description="查 `run`、`auth`、`serve`、`mcp`、`session`、`plugin` 等命令边界。" href="/docs/opencode/official/00-getting-started/cli" />
  <Card title="TUI 工作流" description="学习 `@` 文件引用、shell 命令、模式切换、会话管理和快捷键。" href="/docs/opencode/official/00-getting-started/tui" />
  <Card title="OpenCode Zen" description="第一次不知道选什么模型时，先理解 Zen 的 provider、模型 ID 和计费边界。" href="/docs/opencode/official/08-platform/zen" />
  <Card title="Rules" description="把项目约束写进 `AGENTS.md` 和 rules，避免每次从零提醒 agent。" href="/docs/opencode/official/02-agents-skills/rules" />
</Cards>

## 官方资料

- OpenCode 入门：[https://opencode.ai/docs](https://opencode.ai/docs)
- OpenCode CLI：[https://opencode.ai/docs/cli](https://opencode.ai/docs/cli)
- Windows / WSL：[https://opencode.ai/docs/windows-wsl](https://opencode.ai/docs/windows-wsl)
- OpenCode Zen：[https://opencode.ai/docs/zen](https://opencode.ai/docs/zen)
