1. 独创的 Plan/Build 双模式#

OpenCode 最大的创新在于将编程任务分解为”规划”与”构建”两个阶段：

• Plan 模式（架构师视角）：只分析不修改，扫描代码库、分析依赖关系，输出详细的实施计划
• Build 模式（工程师视角）：基于确认的计划执行具体代码编写、文件修改、测试运行

这种”先想后做”的工作流，完美契合高级工程师的思维模式，避免了 AI 盲目改代码导致的问题。

2. 多模型自由切换#

支持 75+ 种大语言模型，包括但不限于：

• OpenAI 系列：GPT-4o、o3-mini 等
• Anthropic 系列：Claude 3.5 Sonnet、Claude 3.7 Sonnet 等
• Google 系列：Gemini 2.0 Pro、Gemini 2.5 Flash 等
• 国产模型：DeepSeek-V4、GLM-5.1、MiniMax M2.7 等
• 本地模型：通过 Ollama、LM Studio 运行本地模型

3. 内置免费模型#

OpenCode 提供官方精选的 Zen 模型集合，包含多个免费模型，无需 API Key 即可直接使用，真正做到零成本上手。

4. 上下文感知能力#

通过 /init 命令自动分析项目结构，生成 AGENTS.md 文件，让 AI 深入理解项目架构、编码规范和依赖关系。

5. 内置 LSP 支持#

深度集成 Language Server Protocol（语言服务器协议，LSP ），提供实时诊断、代码跳转、悬停提示、多语言智能支持，让 AI 不仅”读”文本，更能”理解”代码的语法结构。

6. MCP 服务器支持#

支持 Model Context Protocol，可连接外部数据源和工具（如数据库、文档检索、搜索等），无限扩展能力边界。

3.1 前置要求#

• Node.js：确保已安装 Node.js（建议 18+ 版本）
• npm：Node.js 包管理器，用于安装 OpenCode
• Git：用于项目版本控制

3.2 安装方法#

1
sudo apt install node npm  # Debian系
2
paru -S node npm           # Fedora系
3
paru -S node npm           # Arch Linux

安装 OpenCode#

1
npm install -g opencode-ai

1
opencode --version

4.1 启动 OpenCode#

打开终端，输入以下命令启动 OpenCode：

1
opencode

看到如下界面，说明 OpenCode 已成功启动：

4.2 配置 AI 模型#

1
/models

1
opencode auth login

1
/connect

1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "provider": {
4
    "myprovider": {
5
      "npm": "@ai-sdk/openai-compatible",
6
      "name": "Custom Provider",
7
      "options": {
8
        "baseURL": "https://api.example.com/v1",
9
        "headers": {
10
          "Authorization": "Bearer your_api_key"
11
        }
12
      },
13
      "models": {
14
        "model-name": {
15
          "name": "alias-name"
16
        }
17
      }
18
    }
19
  }
20
}

4.3 项目初始化#

在项目目录内运行：

1
/init

OpenCode 将：

• 扫描当前目录的代码结构
• 创建 .opencode/ 配置目录
• 生成 AGENTS.md 文件（记录项目信息、编码规范、架构说明）

建议：将 AGENTS.md 提交到 Git 仓库，帮助团队成员共享 AI 上下文。

5.1 Plan 模式与 Build 模式#

OpenCode 通过 Tab 键 在两种模式间切换，右下角会显示当前模式指示器。

使用流程：

1. 按 Tab 切换到 Plan 模式
2. 描述你的需求，获取详细实施计划
3. 审阅计划，补充细节或调整方向
4. 按 Tab 切换回 Build 模式
5. 让 OpenCode 执行代码变更

5.2 常用交互命令#

在 TUI 界面中，以 / 开头的斜杠命令是主要交互方式：

5.3 内置工具集#

OpenCode 的 AI Agent 通过以下工具操作代码库：

工具权限可在 opencode.json 中设置为 allow（允许）、deny（拒绝）或 ask（询问确认）。

6.1 创建项目并生成代码#

场景：快速创建一个 Express.js API 服务

1
# 步骤 1：创建项目目录
2
mkdir my-api && cd my-api
3
npm init -y
4

5
# 步骤 2：启动 OpenCode
6
opencode
7

8
# 步骤 3：初始化项目（生成 AGENTS.md 文件）
9
/init
10

11
# 步骤 4：描述需求
12
创建一个 Express.js 服务，支持 /hello 路由返回 JSON { message: 'Hello World' }，并添加 README 文档。

OpenCode 将自动：

1. 安装 Express 依赖
2. 创建 index.js 服务器代码
3. 配置路由处理
4. 生成项目 README

脚本化执行：

1
opencode -p "创建一个 React + TypeScript 项目，配置 Tailwind CSS"

6.2 解释与分析现有代码#

场景：理解复杂代码逻辑

1
# 引用文件并提问
2
文件 @src/auth.js 包含哪些功能？请解释其中的认证逻辑。
3

4
# 询问多个文件的关系
5
@src/services 目录下的各个模块是如何协作的？

使用 @ 符号引用项目中的文件或目录路径，OpenCode 会自动读取并分析。

6.3 代码重构与优化#

场景：重构登录模块

1
# 步骤 1：按 Tab 进入 Plan 模式
2

3
# 步骤 2：描述重构需求
4
重构 src/components/Login.tsx 组件：
5
1. 将表单逻辑提取为自定义 Hook
6
2. 添加更完善的错误处理
7
3. 优化性能，减少不必要的重渲染
8

9
# 步骤 3：审阅生成的计划
10

11
# 步骤 4：按 Tab 切换到 Build 模式，确认执行
12
听起来不错！请继续进行更改。

自定义命令#

在 ~/.config/opencode/commands/ 目录创建 Markdown 文件：

1
mkdir -p ~/.config/opencode/commands/
2
cat > ~/.config/opencode/commands/prime-context.md << 'EOF'
3
请在每次回复前：
4
1. 检查项目的 coding style
5
2. 确保所有修改都有对应的测试覆盖
6
3. 遵循 TypeScript 严格模式
7
EOF

MCP 服务器配置#

通过 MCP 连接外部工具，在 opencode.json 中添加：

1
{
2
  "mcpServers": {
3
    "github": {
4
      "command": "npx",
5
      "args": ["-y", "@modelcontextprotocol/server-github"],
6
      "env": {
7
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token"
8
      }
9
    }
10
  }
11
}

多会话协作#

同时开启多个 Agent 处理不同任务：

1
/sessions          # 查看所有会话
2
/resume <id>       # 切换到指定会话

IDE 集成#

在 VS Code 中搜索安装 OpenCode 扩展，即可获得与终端版一致的 AI 辅助体验。

oh-my-opencode 扩展#

oh-my-opencode 是一个强大的多智能体扩展：

• Sisyphus 主智能体：持续执行复杂任务直至完成
• 专业子智能体：Oracle（分析）、Librarian（文档）、Frontend Engineer（前端）等
• 多模型调度：自动分配任务给最适合的模型
• 关键词触发：在提示中加入 ultrawork 激活完整自动化模式

1. 给 AI 充足的上下文#

像指导团队中的初级开发者一样，提供：

• 清晰的需求描述
• 相关的代码示例
• 期望的输入/输出
• 约束条件和边界情况

2. 善用 Plan 模式做复杂任务#

对于涉及多文件修改的复杂需求，务必先使用 Plan 模式生成方案，确认后再切换到 Build 模式执行。这能大幅降低出错概率。

3. 定期压缩对话#

长对话会消耗大量 Token，定期使用 /compact 压缩历史，保持高效且低成本。

4. 版本控制敏感配置#

1
# 将 API Key 配置文件加入 .gitignore
2
echo "opencode.json" >> .gitignore
3

4
# AGENTS.md 可以提交到 Git
5
git add AGENTS.md
6
git commit -m "docs: add AI assistant context guide"

5. 保持 OpenCode 更新#

1
npm update -g opencode-ai

6. 图片输入#

OpenCode 支持将图片拖放到终端中作为输入，可用于：

• 参考 UI 设计稿生成代码
• 分析错误截图
• 解释流程图或架构图

快速开始清单#

1
# 1. 安装
2
npm install -g opencode-ai
3

4
# 2. 验证
5
opencode --version
6

7
# 3. 进入项目目录
8
cd your-project
9

10
# 4. 启动
11
opencode
12

13
# 5. 初始化项目（生成 AGENTS.md 文件）
14
/init
15

16
# 6. 开始对话！