---
title: "02 · 安装、连接模型与第一次运行"
description: "从安装 OpenCode 到连接 provider、启动 TUI，并完成第一轮只读和低风险写入。"
verifiedAt: "2026-05-09"
---

第一次使用 OpenCode，不要急着让它重构项目。它进入真实仓库后会读文件、改文件、跑命令、调外部模型——任何一项失控都可能毁掉一上午的工作。所以你的目标只有一个：确认这台机器上的 OpenCode 能被你约束住，并完成一轮可控任务。

> [!NOTE]
> **这一篇用 15 分钟换什么**：不是“装上就算完”，而是拿到一个可复现的上手闭环。命令能跑、provider 能连、项目能读、改动能控、失败能定位，才算真正完成第一次运行。

## 先给结论：第一天只跑安全闭环

第一天不要研究所有配置，也不要把 MCP、Plugin、Agent、Skill 一次性全开。先跑完这条链路：

```mermaid
flowchart LR
  Terminal["现代终端"] --> Install["安装 opencode"]
  Install --> Check["opencode --help"]
  Check --> Provider["/connect 或 auth login"]
  Provider --> Project["进入真实 Git 仓库"]
  Project --> Init["/init 生成 AGENTS.md 初稿"]
  Init --> Read["只读解释项目"]
  Read --> Write["限定单文件写入"]
  Write --> Review["检查 diff / 撤销能力"]

  style Check fill:#dbeafe,stroke:#3b82f6
  style Read fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Write fill:#fef3c7,stroke:#f59e0b
  style Review fill:#fee2e2,stroke:#ef4444
```

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

## 1. 安装前先准备两样东西

OpenCode 是 coding agent（编码代理），不是普通聊天网页。它会进入你的终端、读取项目文件、调用模型供应商、执行 shell 命令。安装前至少准备：

- **现代终端**：OpenCode 默认在终端里跑出一套 TUI（terminal UI，文本界面），需要终端支持高色彩、鼠标捕获、复杂字符布局，普通系统自带终端常会错位。官方推荐 WezTerm、Alacritty、Ghostty、Kitty，任选一个。
- **模型供应商 API key**：OpenCode 自己**不内置模型**，每次提问都要发给你选的 provider（Anthropic、OpenAI、Google、xAI 等）的 API；离线不能用，必须先有可用的 key。

> [!IMPORTANT]
> 密钥只进入 OpenCode 的凭据系统，不写进项目文件、不进 Git。第一次连接 provider 用 `/connect` 或 `opencode auth login`。项目配置里只写"用哪个 provider 哪个 model"的策略，不写真实 API key——一旦写进项目文件，下一次 `git commit` 很可能把它推上公开仓。

## 2. 安装 OpenCode

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

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

macOS / Linux 用户也可以用官方 Homebrew tap，比官方 brew formula 更新更快：

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

如果你已经装了 Node.js，可以用 npm 全局安装：

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

Windows 可以直接装（官方还提供 chocolatey、scoop、mise、docker 多种选择，详见 [Windows 使用说明](/docs/opencode/official/08-platform/windows-wsl)），但 coding agent 重度依赖 shell、Git、语言工具链、文件系统和权限——多数开源项目默认假设的是 Linux 开发环境，Windows native 容易在路径分隔符、行尾符、权限模型上踩坑。**第一次学习强烈建议优先装 WSL 再装 OpenCode**，比一边学新工具一边修 Windows 兼容问题省心得多。

## 3. 先验证命令，不要直接改项目

安装后先查帮助或版本：

```bash
opencode --help
opencode --version
```

如果命令不存在，先检查 PATH，不要马上换安装方式：

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

常见原因通常是 shell 没刷新、Node 全局 bin 不在 PATH、Homebrew 路径没加载，或者终端开的是旧 session。

> [!TIP]
> 先排环境，再排 OpenCode。安装失败很多时候不是 OpenCode 本身坏了，而是当前 shell 找不到新装的可执行文件。

## 4. 连接模型 provider

连接 provider 有两条路径，新手任选一条：

**路径 A：先在 OS 终端用 CLI 配（推荐）**

```bash
opencode auth login    # 走交互向导：选 provider、粘贴 API key、保存到本机
opencode auth list     # 验证已保存的 provider
```

`auth login` 在你的普通 shell（zsh / bash / PowerShell）里跑，跑完就退出。这是新手最稳的方式——不必先理解 TUI。

**路径 B：先启动 TUI 再用 `/connect`**

```bash
cd /path/to/project    # 进入任意项目目录
opencode               # 启动 OpenCode TUI（界面进入"已切换"的全屏交互模式）
```

进入 TUI 后，在输入框里直接打：

```text
/connect
```

OpenCode 会弹出 provider 选择菜单，引导你完成认证。

---

两条路径分工：

- `auth login`（OS shell）：第一次配凭据 + 后续 `auth list` 复查 + 自动化 / CI 场景。
- `/connect`（TUI 里）：已经在用 OpenCode 时随时加 provider，不用退出会话。
- 环境变量或 `.env`：已经有统一凭据管理（如 1Password CLI、direnv、内部 secret manager）的人。
- 项目配置 `opencode.json`：只写团队模型策略，**绝对不写真实 API key**。

如果 provider 连接失败，先查 API key、账单状态、网络代理、provider 可用性和模型权限，不要直接认定 OpenCode 坏了。

## 5. 进入真实 Git 仓库

不要在桌面空目录里测试。OpenCode 是 coding agent，最小验证应该发生在真实项目里。

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

也可以直接指定项目路径：

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

第一次进入项目后，运行：

```text
/init
```

`/init` 会分析项目并生成 `AGENTS.md` 初稿。它适合写项目结构、编码约定、测试命令、常见边界和禁止修改范围。

> [!WARNING]
> `/init` 生成的是初稿，不是最终规范。提交前要人工看一遍，尤其是包管理器、测试命令、部署命令、生成物目录和敏感目录。

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

第一次任务不要让 OpenCode 改文件。先验证它能不能正确读项目。

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

这条提示词同时做三件事：明确“不要修改文件”，验证它是否读到真实目录结构，并要求它暴露不确定性。

如果它第一轮就开始改文件，先停下来检查模式、提示词和权限，不要继续进入复杂任务。

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

只读任务稳定后，再做一个低风险写入。不要选“重构整个项目”，选 README、文档或测试说明这类单文件任务。

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

合格结果应该满足四点：

- 只改你指定的一个文件。
- 能说明为什么这样改。
- 会建议合理的检查命令。
- 不会自作主张 commit、push 或部署。

如果 OpenCode 改了无关文件，先让它解释 diff，不要直接继续下一轮。必要时用 Git 回滚当前文件，再收紧权限或提示词。

## 8. 知道怎么撤销，才继续扩大任务

OpenCode 支持撤销和重做**当前会话产生的本地文件修改**：

```text
/undo
```

```text
/redo
```

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

> [!CAUTION]
> `/undo` 只能撤回当前会话改过的本地文件 + 重新显示你上一条 prompt——它**不会**回滚已经 `git commit` / `git push` 的内容、不会撤销已经跑过的数据库迁移、不会撤销已经发出的外部服务调用。所以"能撤销"≠ 可以随便改：数据库迁移、外部服务、发布部署、删除文件和批量格式化，都要先看计划和影响范围。

## 9. `run` 先用于只读检查

OpenCode 也支持非交互任务：

```bash
opencode run "Explain the structure of this repository. Do not edit files."
```

`run` 适合脚本、简单自动化或 CI 里的只读检查。第一次上手仍建议先用 TUI，因为 TUI 更容易观察模型行为、工具调用、权限提示和上下文压缩。

`run` 命令有一个 `--dangerously-skip-permissions` flag——它会自动批准所有非显式拒绝的权限请求（官方原文："dangerous!"）。第一次学习时**永远不要**用这个 flag，哪怕只是想"跑得快一点"。没有权限提示的 agent 在真实仓库里就是无监督，删错文件、跑坏数据库都来不及看见。

## 10. 常见卡点按层级排

- `opencode` 找不到：查 `which opencode`、PATH、终端是否重开。
- TUI 显示异常：换现代终端，检查字体、快捷键和终端能力。
- provider 连接失败：查 API key、账单、网络、代理、provider 权限。
- 读不到项目：确认当前目录、Git 仓库、文件权限和忽略规则。
- 一上来乱改文件：收紧提示词、模式和 permission。
- Windows 路径或 shell 异常：优先切到 WSL 环境再试。

排障顺序不要反过来。先确认本机命令、路径、provider，再看 OpenCode 配置。

## 本章自检

过关前先回答这些问题：

- 第一次启动 OpenCode 前，需要准备哪两类东西？
- 为什么第一轮任务应该只读，而不是直接让它改代码？
- `/connect`、`opencode auth login`、项目配置分别适合什么场景？
- 第一轮低风险写入为什么只改单文件？
- 如果它改了无关文件，你应该先看什么？

过关标准：你能在一个真实 Git 仓库里启动 OpenCode，连接 provider，让它只读解释项目结构，再完成一个限定单文件的低风险修改。

## 接下来去哪

<Cards>
  <Card title="终端 TUI 工作流" description="继续学习 `@` 文件引用、`!` shell 命令、`/` 斜杠命令和会话控制。" href="/docs/opencode/understanding/03-terminal-workflow" />
  <Card title="CLI 入口" description="查 `run`、`auth`、`models`、`serve`、`mcp` 等命令的边界。" href="/docs/opencode/official/00-getting-started/cli" />
  <Card title="入门官方整理" description="回到官方路径版，按安装、provider、初始化、低风险写入完整复查。" href="/docs/opencode/official/00-getting-started" />
  <Card title="配置与规则" description="跑通第一轮后，再把项目约束沉淀到 rules、commands 和 AGENTS.md。" href="/docs/opencode/understanding/04-config-rules-commands" />
</Cards>

## 官方资料

- OpenCode 入门：[https://opencode.ai/docs](https://opencode.ai/docs)
- OpenCode CLI：[https://opencode.ai/docs/cli](https://opencode.ai/docs/cli)
- Windows 使用说明：[https://opencode.ai/docs/windows-wsl](https://opencode.ai/docs/windows-wsl)
- 配置说明：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
