OpenCode
免费从入门到精通

1. OpenCode 简介与核心特性

1.1 什么是 OpenCode?

OpenCode 是一个开源的 AI 编码助手（Coding Agent），专为终端环境设计。它不像传统的图形界面软件，而是通过 命令行交互界面（TUI） 直接“住”在你的终端里，让 AI 编程能力无缝融入你的开发工作流。

1.2 核心特性

1.3 客户端形态

本教程重点 ：以 Terminal（CLI/TUI） 形态为主线，因为它是最灵活、功能最完整的使用方式。

2. 环境准备（必读）

在安装 OpenCode 之前，你需要确保系统已安装必要的运行环境。

2.1 检查是否已有环境

对于 Windows 用户（PowerShell）：

node -v
npm -v

对于 Mac 用户（Bash/Zsh）：

node -v
npm -v

2.2 安装 Node.js

OpenCode 依赖 Node.js 运行环境（建议 18 及以上版本）。

• Windows : 访问 Node.js 官网 下载 LTS 版本安装。
• Mac : 使用 brew install node 或 nvm 安装。

2.3 关于包管理器

安装 Node.js 后会自动获得 npm 。你也可以选择安装其他包管理器：

• Bun ：新一代高性能 JavaScript 运行时（可选）

但在本教程中，我们统一使用最通用的 npm 。

3. 快速开始（5 分钟上手）

场景 ：在终端中完成安装、配置并运行第一个 AI 编程任务。

第一步：安装 OpenCode

npm install -g opencode-ai

第二步：连接模型（推荐使用向导）

启动 OpenCode（在任意目录都可以）：

opencode

在 TUI 界面中输入：

/connect

按照界面提示选择提供商并完成认证。官方推荐新手使用 OpenCode Zen 。

第三步：创建测试项目

mkdir opencode-demo
cd opencode-demo
echo "console.log('Hello OpenCode')" > index.js
opencode

第四步：初始化项目

/init

OpenCode 会分析你的项目结构，并在根目录创建 AGENTS.md 。

第五步：完成第一个任务

在输入框中输入以下提示词：

请帮我创建一个名为 hello.js 的文件，内容是输出当前时间的 Hello World 程序。

观察工作流：

1. OpenCode 进入 Plan Mode ，告诉你它打算做什么
2. 你可以按 Tab 键切换到 Build Mode
3. 确认后，OpenCode 会创建文件并写入代码
4. 去文件夹查看， hello.js 应该已经生成了！

4. 详细安装指南（多平台多方式）

除了 npm 安装外，OpenCode 还提供了多种便捷的安装方式。

4.1 Windows 安装方式

• 方式 1：npm（推荐新手） ： npm install -g opencode-ai
• 方式 2：桌面应用（Beta） ：访问 OpenCode 官网下载 .exe 安装包。
• 方式 3：二进制文件 ：从 GitHub Releases 下载 opencode-windows-amd64.exe 并放入 PATH。

4.2 Mac 安装方式

• 方式 1：Homebrew（推荐） ： brew install opencode
• 方式 2：npm ： npm install -g opencode-ai
• 方式 3：安装脚本 ： curl -fsSL https://opencode.ai/install | bash
• 方式 4：桌面应用（Beta） ：下载 .dmg 安装包。

4.4 选择建议

3. 快速开始（5 分钟上手）

场景 ：在终端中完成安装、配置并运行第一个 AI 编程任务。

第一步：安装 OpenCode

npm install -g opencode-ai

第二步：连接模型（推荐使用向导）

启动 OpenCode（在任意目录都可以）：

opencode

在 TUI 界面中输入：

/connect

按照界面提示选择提供商并完成认证。官方推荐新手使用 OpenCode Zen 。

第三步：创建测试项目

mkdir opencode-demo
cd opencode-demo
echo "console.log('Hello OpenCode')" > index.js
opencode

第四步：初始化项目

/init

OpenCode 会分析你的项目结构，并在根目录创建 AGENTS.md 。

第五步：完成第一个任务

在输入框中输入以下提示词：

请帮我创建一个名为 hello.js 的文件，内容是输出当前时间的 Hello World 程序。

观察工作流：

1. OpenCode 进入 Plan Mode ，告诉你它打算做什么
2. 你可以按 Tab 键切换到 Build Mode
3. 确认后，OpenCode 会创建文件并写入代码
4. 去文件夹查看， hello.js 应该已经生成了！

4. 详细安装指南

5. 配置详解

5.1 两种配置方式

方式 A：交互式向导（推荐新手）

在 TUI 中使用 /connect ，或在命令行使用 opencode auth login 。这会启动一个交互式向导，让你选择提供商并保存凭据。

方式 B：手动配置（适合高级用户）

使用环境变量 （最灵活的方式）

Windows 设置： 临时设置用 $env:OPENAI_API_KEY="sk-..." ，永久设置需在“系统环境变量”中添加。

Mac 设置： 在 ~/.zshrc 中添加 export OPENAI_API_KEY="sk-..." 。

5.2 配置文件 opencode.json

配置文件结构示例：

{
  "providers": {
    "openai": { "apiKey": "sk-..." },
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "agents": {
    "coder": { 
      "model": "gpt-4-turbo",
      "temperature": 0.1
    }
  },
  "shell": {
    "path": "/bin/zsh",
    "args": ["-l"]
  },
  "mcpServers": {
    "my-tool": { "type": "stdio", "command": "path/to/tool" }
  },
  "autoCompact": true
}

核心配置项说明

• providers ：配置各 AI 提供商的 API 密钥。
• agents ：定义不同代理（如 coder, task）使用的默认模型和参数。
• shell ：自定义 bash 工具使用的 Shell 类型及启动参数。
• mcpServers ：配置 MCP 服务器以扩展外部工具能力。
• autoCompact ：是否自动压缩上下文（默认 true ），防止 Token 溢出。

5.3 日志与数据目录

提高日志级别： opencode --log-level DEBUG

6. 基础使用

6.1 启动 TUI

cd /path/to/your/project
opencode

6.2 核心概念：Plan vs Build 模式

OpenCode 的核心安全机制是"先计划，后执行"。

6.3 项目初始化

首次使用时应运行 /init 。这会分析项目结构，并在根目录创建 AGENTS.md 。

6.4 常用命令

6.5 新手建议

• 先从“只读任务”开始 ：例如问项目架构、文件作用。
• 尝试简单的修改 ：如添加一段注释或一个小功能。
• 复杂任务先要计划 ：先看计划再切换到 Build 模式。

7. 高效交互技巧

7.1 引用文件 (@)

使用 @ 可以精确引用文件，让 AI "看准文件再回答"。

请解释 @src/server/index.ts 中的路由配置逻辑

多文件引用：

对比 @src/auth.ts 和 @src/utils/validate.ts 的输入验证方式，哪个更安全？

7.2 执行命令 (!)

使用 ! 可以执行 Shell 命令，并将输出传递给 AI 分析。

!npm test
请分析上面的测试失败原因

Windows 示例： !dir ，Mac 示例： !ls -lh 。

7.3 新手最稳提示词模板

请先不要修改任何文件。
1）你需要先阅读哪些文件才能理解这个需求？
2）根据这些文件，给出 2-3 个解决方案，并说明利弊
3）给出你推荐的最小改动方案（包含会改哪些文件）

先给我一个逐步计划（不要改文件）：
- 涉及哪些文件
- 每一步做什么
- 如何验证
我确认后你再开始修改。

请用 3 个步骤重构 @src/legacy.js：
第 1 步：只提取重复代码为函数，不改逻辑
第 2 步：改善命名和注释
第 3 步：优化性能
每完成一步，等我确认后再继续下一步。

8. 非交互式使用

OpenCode 支持在命令行中"跑一次就退出"，非常适合脚本化和自动化。

for file in *.py; do
  opencode -q "分析 $file 代码质量" > "${file}_report.txt"
done

9. 进阶定制

当你已经熟练掌握基础用法后，可以通过自定义命令、代理和工作流来打造专属的 AI 助手。

9.1 自定义命令 (Commands)

自定义命令是"可复用的提示词模板"。

创建示例

文件： refactor.md

---
description: "代码质量优化助手"
---

请分析当前正在讨论的文件，并进行代码重构优化：

1. 识别代码异味和潜在问题
2. 提取重复代码，提高复用性
3. 改善变量和函数命名
4. 优化代码结构和逻辑
5. 添加必要的注释和文档
6. 确保重构后行为保持一致

请先给出优化建议和改动计划，等我确认后再执行。

使用方法

1. 在 TUI 中正常与 AI 讨论某个文件的代码
2. 当需要优化重构时，直接输入 /refactor
3. AI 会自动分析当前上下文中的文件并给出重构方案
4. 确认方案后，AI 将执行优化

存储位置

9.2 自定义代理 (Agents)

代理是专门化的 AI 角色，拥有自己的指令和配置。

存储位置

示例 1：任务规划代理

文件： task-planner.md

---
name: task-planner
description: 将功能需求分解为可执行的任务清单
---

# 任务规划代理

你是一名技术项目经理和软件架构师。

## 核心职责
- 深入分析功能需求
- 识别需要创建或修改的所有文件
- 将工作分解为逻辑清晰的步骤
- 评估每个步骤的风险和依赖关系

## 输出格式
以 Markdown 列表形式提供：
1. 任务清单
2. 文件清单
3. 实施顺序建议
4. 风险提示

示例 2：编码实现代理

文件： coder-impl.md

---
name: coder-impl
description: 根据任务规划实现代码
---

# 编码实现代理

你是一名资深软件工程师。

## 实现指南
- 严格遵循任务规划代理的计划
- 保持与项目现有代码风格一致
- 编写清晰、自解释的代码
- 添加必要的错误处理和边界检查
- 遵循 SOLID 原则和最佳实践

## 代码规范
- 变量命名：驼峰式（camelCase）
- 函数命名：动词开头
- 注释：关键逻辑必须注释
- 测试：关键函数需要单元测试

查看可用代理

opencode agent list

9.3 工作流 (Workflows)

工作流将多个代理串联成自动化流水线。

存储位置

示例：功能开发工作流

文件： feature-dev.json

{
  "$schema": "https://opencode.ai/workflow.json",
  "name": "feature-dev",
  "description": "完整的功能开发流水线",
  "agents": [
    {
      "name": "task-planner",
      "waitForCompletion": true,
      "stopOnFailure": true
    },
    {
      "name": "coder-impl",
      "waitForCompletion": true,
      "stopOnFailure": true
    }
  ]
}

运行工作流

在 TUI 中：

使用 feature-dev 工作流为我们的个人网站设计一个首页 /index 页面

OpenCode 会：

1. 先调用 task-planner 规划任务
2. 等待你确认计划
3. 再调用 coder-impl 实现代码

10. MCP 集成

MCP（Model Context Protocol） 是一个协议，允许 OpenCode 通过与外部工具交互来扩展能力。

10.1 MCP 命令

# 添加 MCP 服务器
opencode mcp add

# 查看已安装列表
opencode mcp list

# OAuth 认证
opencode mcp auth <server-name>

10.2 配置 MCP 服务器

推荐方式：使用命令行（而非手动编辑配置文件）

opencode mcp add

按提示选择或输入 MCP 服务器信息。

备选方式：手动编辑 opencode.json

{
  "mcp": {
    "my-database-tool": {
      "type": "stdio",
      "command": "/path/to/database-mcp",
      "env": [],
      "args": []
    }
  }
}

10.3 使用示例

11. 最佳实践与避坑

11.1 Windows 用户必看

• 路径分隔符问题 ：虽然 OpenCode 尽量兼容，但 AI 有时会混淆 / 和 \ 。 建议： 在对话中尽量只给文件名（如 src/index.js ），OpenCode 内部会自动处理路径格式。
• PowerShell 执行策略 ：如果运行 opencode 报错"禁止运行脚本"：

  # 以管理员身份运行 PowerShell
  Set-ExecutionPolicy RemoteSigned
  # 选择 Y 确认

• 权限问题 ：OpenCode 修改文件需要相应权限。建议避免在 C:\Program Files 或系统目录下操作，将项目放在用户目录下（如 d:\Projects ）。
• 终端选择 ：推荐使用 Windows Terminal 或 VS Code 内置终端，而非老旧的 cmd.exe 。

11.2 Mac 用户建议

• Shell 配置 ：确保在 ~/.bashrc 或 ~/.zshrc 中正确配置环境变量：

  export OPENAI_API_KEY="sk-..."
  export ANTHROPIC_API_KEY="sk-ant-..."

• 权限问题 ：如果遇到权限错误，检查文件所有者：

  # 修改文件所有者（如果需要）
  sudo chown -R $USER:$USER /path/to/project

11.3 通用最佳实践

git checkout -b backup-before-opencode
git add .
git commit -m "Backup before OpenCode refactor"

12. 常见问题解答 (FAQ)

project-root/
  .opencode/
    commands/
      review.md
    agents/
      team-coder.md

13. 附录：OpenCode vs Claude Code 深度对比

14. 参考资料与来源索引

官方资源

• OpenCode 官网
• OpenCode GitHub 仓库
• OpenCode 文档
• OpenCode 下载页