第二章：快速上手 —— 安装、连接模型与初始化项目

这章按 2026 年官方文档整理成最稳妥的一条路线： 安装 OpenCode → 运行 `/connect` → 选择模型 → 进入项目后执行 `/init`。

1. 安装前准备

• 一款现代终端，例如 WezTerm、Ghostty、Kitty、Alacritty。
• 至少一个可用的 LLM 提供商账号或 API Key。新手可先从 OpenCode Zen 开始。
• Windows 用户可以原生安装，但官方仍然建议优先使用 WSL 获取更完整体验。

2. 安装 OpenCode

最简单的方法仍然是官方安装脚本：

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

包管理器安装

# Node.js 生态
npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai
yarn global add opencode-ai

# macOS / Linux（官方推荐保持最新）
brew install anomalyco/tap/opencode

# Arch Linux
sudo pacman -S opencode
paru -S opencode-bin

Windows 安装

choco install opencode
scoop install opencode
npm install -g opencode-ai
mise use -g github:anomalyco/opencode

Docker 与桌面版

docker run -it --rm ghcr.io/anomalyco/opencode

除了终端版，OpenCode 现在也提供桌面版 Beta 和 VS Code、Cursor、Zed、Windsurf、VSCodium 扩展入口。如果你不想从纯终端开始，可以直接走桌面版或 IDE 路线。

3. 第一次启动：连接模型

安装完成后先运行 opencode 进入 TUI，然后执行 /connect。

opencode
/connect

1. 在列表中选择提供商，例如 OpenCode Zen、DeepSeek、OpenAI、Anthropic。
2. 按提示登录或粘贴 API Key。
3. 连接成功后执行 /models 查看当前可用模型。
4. 选择一个默认模型，开始你的第一轮对话。

这里要特别注意：新版 OpenCode 已经把 /models 作为选择模型的重要入口。很多旧教程只讲“填完 Key 就好了”，但实际上最好立刻确认当前默认模型是否正确。

4. 初始化你的项目

连接好模型后，进入你想操作的代码仓库：

cd /path/to/project
opencode
/init

/init 会分析项目并在根目录生成 AGENTS.md。 这是 OpenCode 理解项目结构、编码规范和团队约束的关键入口，建议提交到 Git。

5. 第一次高质量提问

OpenCode 最擅长的不是“随便生成一段代码”，而是根据上下文直接执行任务。你可以从下面两类提问开始：

直接修改

给 @src/settings.ts 增加登录校验。
参考 @src/notes.ts 里已有的权限处理逻辑，
改完后运行测试并告诉我结果。

先规划再执行

先切到 plan agent。
我想给后台增加“最近删除”页面。
请先给我一个分步骤的实现计划，
确认后我再让你开始改代码。

在 TUI 里按 Tab 可以在 build agent 和 plan agent 之间切换。build 负责真正修改文件，plan 负责只读分析和规划。

6. 常见坑位

• 只安装，不连模型：装完命令只是第一步，没有 Key 或订阅依然无法干活。
• 没有执行 `/models`：连接 provider 后，如果默认模型不合适，体验会明显下降。
• 跳过 `/init`：项目级上下文不足时，OpenCode 更容易给出泛化建议。
• Windows 终端体验差：原生可用，但复杂项目通常还是 WSL 更稳。