02 · 安装、连接模型与第一次运行

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

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

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

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。

2. 安装 OpenCode

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

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

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

brew install anomalyco/tap/opencode

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

npm install -g opencode-ai

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

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

安装后先查帮助或版本：

opencode --help
opencode --version

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

which opencode
echo $PATH

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

4. 连接模型 provider

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

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

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

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

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

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

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

/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，最小验证应该发生在真实项目里。

cd /path/to/project
opencode

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

opencode /path/to/project

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

/init

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

6. 第一轮只做只读任务

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

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

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

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

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

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

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

合格结果应该满足四点：

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

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

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

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

/undo

/redo

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

9. run 先用于只读检查

OpenCode 也支持非交互任务：

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，让它只读解释项目结构，再完成一个限定单文件的低风险修改。

接下来去哪

官方资料

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