从零开始学 OpenCode：10 分钟在终端里跑起你的 AI 编程助手

你打开终端，面对那个闪烁的光标，脑子里想的还是一行一行敲命令吗？

过去半年，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%**。

标准操作流程：

1. 启动与规划：在终端输入需求后，默认进入 Plan 模式。AI 会分析文件，提出修改建议。
2. 确认与修正：如果发现 AI 理解有误，继续对话修正，直到 Plan 完美。
3. 模式切换：确认计划无误后，按 Tab 键 切换至 Build 模式。
4. 代码落地：AI 开始执行代码编写和文件修改。

七、上手案例：完整走一遍

假设你有一个 Express 项目，想给用户注册接口加上邮箱格式校验。

Step 1：启动 OpenCode

cd my-express-project
opencode

Step 2：提出需求（Plan 模式）

> 给用户注册接口 /api/register 加上邮箱格式校验，要求：
  1. 校验邮箱格式是否合法
  2. 校验失败返回 400 错误
  3. 给出清晰的错误提示

OpenCode 会读取你的代码、分析现有结构，输出一份 Plan：

## 实施计划

### 涉及文件
- src/routes/auth.js - 需要添加邮箱校验逻辑
- src/utils/validator.js - 需要新增邮箱校验函数

### 具体改动
1. 在 validator.js 中新增 validateEmail 函数
2. 在 auth.js 的 /register 路由中调用该函数
3. 校验失败时返回 400 及错误信息

### 风险评估
- 低风险：纯新增逻辑，不影响现有功能

Step 3：确认并执行

确认 Plan 无误后，按 Tab 键 切换到 Build 模式。OpenCode 会自动修改文件、写入代码。

Step 4：验证

你可以让 OpenCode 继续帮你运行测试或手动检查改动。

八、常用命令速查

Slash 命令（在 TUI 中输入）

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 接入外部工具

你的开发环境，现在是谁在控制？

霍格沃兹测试开发学社，是一个专注软件测试、自动化测试、人工智能测试与测试开发的技术交流社区