你打开终端，面对那个闪烁的光标，脑子里想的还是一行一行敲命令吗？
过去半年，AI 编程工具这个赛道的变化速度，快得让人有点跟不上。OpenCode 在 GitHub 上已经积累了超过 17 万颗星，月活用户达到 750 万。这个数字说明了一件事：开发者对“被锁住”这件事，比想象中更敏感。
但很多人装完 OpenCode 之后，面对 TUI 界面不知道该做什么。API Key 不知道放哪，模型不知道怎么切，Plan 和 Build 两种模式搞不清楚什么时候用。
这篇文章不讲概念，讲步骤。
一、OpenCode 到底是什么
先搞清楚 OpenCode 到底是什么。
它不是一个“聊天窗口” 。ChatGPT 是你问一句它答一句，代码你自己复制粘贴。OpenCode 是一个 AI 编程 Agent——它能理解你的项目结构、读取文件、规划修改方案、执行命令、审查差异，然后把整个改动直接写进你的代码库。
核心差异有三点：
模型中立：OpenCode 不绑定任何一家模型厂商。你可以用 Claude、GPT、Gemini、DeepSeek，也可以用 Ollama 跑本地模型。支持 75 种以上的 AI 模型提供商。
终端优先：OpenCode 运行在终端里，不需要打开重型 IDE。启动快、资源低，适合远程开发和服务器端调试。
本地优先：代码、对话历史、文件操作默认全部存储在本地，不上传云端。支持完全离线部署。
本质上，OpenCode 解决的是一个老问题：你脑子里的想法，怎么最快变成代码。
二、安装 OpenCode：四种方式，选一个就行
OpenCode 依赖 Node.js 环境，版本需要 18 及以上。先确认一下：
node -v
如果版本过低，去 Node.js 官网下载 18.x 或更高版本。
方式一：一键安装脚本（最推荐新手）
这是官方最推荐的入门方式：
curl -fsSL https://opencode.ai/install | bash
脚本会自动检测操作系统和架构（Linux/macOS 的 x64 和 arm64 都支持），下载对应二进制文件并自动配置 PATH。
方式二：npm 全局安装（最常用）
如果你已经有 Node.js 环境，这是最顺手的方式：
npm install -g opencode-ai
安装完成后验证：
opencode --version
出现版本号即表示安装成功。
方式三：包管理器安装
macOS/Linux 用 Homebrew：
brew install sst/tap/opencode
Windows 用 Scoop：
scoop install opencode
方式四：Windows WSL（最稳定）
Windows 用户如果遇到兼容性问题，推荐在 WSL 环境中运行：
PowerShell 管理员模式
wsl --install
进入 WSL
wsl
一键安装
curl -fsSL https://opencode.ai/install | bash
三、配置 AI 模型：最关键的一步
OpenCode 本身是免费的，但你需要自己准备一个 AI 模型的 API Key。
方式一：环境变量（最快上手）
Anthropic Claude
export ANTHROPIC_API_KEY=your-key-here
OpenAI
export OPENAI_API_KEY=your-key-here
Google Gemini
export GEMINI_API_KEY=your-key-here
Windows PowerShell：
$env:ANTHROPIC_API_KEY = "your-key-here"
方式二：配置文件（推荐，更灵活）
在项目根目录或 ~/.config/opencode/ 下创建 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"myprovider": {
"npm": "@ai-sdk/openai-compatible",
"name": "My Provider",
"options": {
"baseURL": "https://your-api-endpoint/v1",
"headers": {
"Authorization": "Bearer your_api_key"
}
},
"models": {
"your-model": {
"name": "Model Name"
}
}
}
}
}
方式三：交互式配置（最简单）
启动 OpenCode 后，在 TUI 界面中使用 /connect 命令，按照提示交互式配置。
四、启动 OpenCode：进入你的项目
进入你的项目目录，启动 OpenCode：
cd /path/to/your/project
opencode
启动后你会看到 TUI（终端交互界面），直接输入问题即可开始对话：
帮我看看这个项目的结构
给 src/utils.ts 添加一个防抖函数
修复 index.ts 第 42 行的类型错误
五、Plan 与 Build：先想清楚，再动手
这是 OpenCode 最核心的设计。
大多数 AI 编程工具（比如 Cursor 或 GitHub Copilot）的工作方式是：你提需求，它直接生成代码。问题是，直接生成的代码经常有逻辑偏差。
OpenCode 解决这个问题的方式很简单——把工作拆成两个阶段：
Plan 模式（架构师视角）
AI 只做分析和规划，不修改任何文件。它会读取代码库、分析依赖关系、评估改动风险，然后输出一份结构化的 Markdown 方案。你可以把它理解成架构师出图纸——图纸没确认之前，不动一砖一瓦。
Build 模式（工程师视角）
基于 Plan 阶段确定的路径，执行具体的代码编写与文件修改。AI 生成 Diff 并写入文件。
怎么切换？
按 Tab 键 在两种模式间切换。
为什么推荐“先 Plan 后 Build”？
根据社区测试，采用“先 Plan 后 Build”策略的复杂重构任务，代码一次性通过率提升了约 40%。
标准操作流程：
启动与规划：在终端输入需求后，默认进入 Plan 模式。AI 会分析文件，提出修改建议。
确认与修正：如果发现 AI 理解有误，继续对话修正，直到 Plan 完美。
模式切换：确认计划无误后，按 Tab 键 切换至 Build 模式。
代码落地：AI 开始执行代码编写和文件修改。
六、上手案例：完整走一遍
假设你有一个 Express 项目，想给用户注册接口加上邮箱格式校验。
Step 1：启动 OpenCode
cd my-express-project
opencode
Step 2：提出需求（Plan 模式）
给用户注册接口 /api/register 加上邮箱格式校验，要求：
- 校验邮箱格式是否合法
- 校验失败返回 400 错误
- 给出清晰的错误提示
OpenCode 会读取你的代码、分析现有结构，输出一份 Plan：
实施计划
涉及文件
- src/routes/auth.js - 需要添加邮箱校验逻辑
- src/utils/validator.js - 需要新增邮箱校验函数
具体改动
- 在 validator.js 中新增 validateEmail 函数
- 在 auth.js 的 /register 路由中调用该函数
- 校验失败时返回 400 及错误信息
风险评估
- 低风险：纯新增逻辑，不影响现有功能
Step 3：确认并执行
确认 Plan 无误后，按 Tab 键 切换到 Build 模式。OpenCode 会自动修改文件、写入代码。
Step 4：验证
你可以让 OpenCode 继续帮你运行测试或手动检查改动。
七、常用命令速查
Slash 命令（在 TUI 中输入）
命令
功能
/init
初始化项目配置，生成 AGENTS.md
/add
添加文件到上下文（支持通配符 *.ts）
/compact
压缩上下文历史，释放 Token
/undo
撤销上一步操作
/web
联网搜索
/review
代码审查
/connect
配置 AI 提供商
/help
查看帮助
/models
切换模型
CLI 命令（在终端中输入）
非交互模式执行任务
opencode run "解释 JavaScript 闭包"
指定模型和文件
opencode run -m anthropic/claude-3.5-sonnet -f main.go "优化这段 Go 代码"
查看版本
opencode -v
八、常见问题
Q：OpenCode 收费吗？
工具本身完全免费（MIT 协议）。你只需要为自己的 API 调用付费。
Q：Windows 用户推荐哪种安装方式？
最稳定的是通过 WSL 安装。如果不想用 WSL，也可以用 npm 或 Scoop。
Q：OpenCode 支持本地模型吗？
支持。你可以通过 Ollama 部署本地模型，然后在 opencode.json 中配置接入。
Q：Plan 和 Build 模式有什么区别？
Plan 模式只分析和规划，不修改任何文件；Build 模式执行具体的代码编写和文件修改。按 Tab 键 切换。
九、下一步
到这里，你已经完成了 OpenCode 从零到一的全部流程：
✅ 了解了 OpenCode 是什么
✅ 完成了安装
✅ 配置了 AI 模型
✅ 学会了 Plan / Build 双模式
✅ 走完了一个完整的上手案例
下一步可以探索：
/init 命令：让 OpenCode 深度理解你的项目结构
Oh-My-OpenCode 插件：把 OpenCode 升级成多 Agent 协作系统
MCP 扩展：通过 Model Context Protocol 接入外部工具
你的开发环境，现在是谁在控制？
