OpenCode + Oh-My-OpenCode 实战教程：从零搭建你的AI编程团队

📚 分类: AI编程工具 / 终端开发环境 ⏱️ 预计耗时: 30-45 分钟 🎯 难度: 入门 🔧 环境要求: Windows (推荐WSL)、macOS 或 Linux 🌐 原文来源: OpenCode 官方文档 | Oh-My-OpenCode GitHub 仓库

你将学到什么

完成本教程后，你将能够：

[ ] 在终端中安装并配置 OpenCode（一个开源的AI编程助手）
[ ] 连接主流AI模型（如Claude、GPT、Gemini）并切换使用
[ ] 安装并配置 Oh-My-OpenCode 插件，将单个AI助手升级为多Agent协作团队
[ ] 使用“ultrawork”关键词让多个AI Agent并行处理复杂开发任务
[ ] 理解并自定义 Agent 配置文件，控制每个Agent使用的模型

最终效果

你将拥有一个完整的终端AI开发环境：启动 opencode 后，你可以像聊天一样输入需求，系统会自动将任务拆解、分配给不同的专业AI Agent（如架构师、编码员、审查员）并行执行，最终交付完整的代码实现。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求版本	验证命令
Node.js	≥ 18.0	`node -v`
npm / Bun	最新稳定版	`npm -v` 或 `bun -v`
Git	≥ 2.30	`git --version`

1. 安装 Bun（推荐，用于安装Oh-My-OpenCode）

Oh-My-OpenCode 的安装脚本依赖 Bun，因此建议优先安装。如果你还没有 Bun，请按以下命令安装：

bash

# Windows PowerShell（管理员模式）
powershell -c "irm bun.sh/install.ps1|iex"

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

✅ 验证：执行 bun -v，应输出版本号（如 1.2.3）。

💡 提示：如果你更习惯用 npm，也可以用 npm install -g bun 安装，但官方推荐使用上面的脚本安装方式。

第 1 步：安装 OpenCode

🎯 目标：在你的系统上安装 OpenCode，并验证它能正常启动。

📝 操作：

方式一：WSL（Windows用户强烈推荐）

bash

# 1. 确保已安装 WSL（在 PowerShell 管理员模式下执行一次）
wsl --install

# 2. 进入 WSL 终端
wsl

# 3. 一键安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

方式二：npm 直接安装（所有系统通用）

bash

$ npm install -g opencode-ai

方式三：包管理器安装

bash

# Chocolatey (Windows)
$ choco install opencode

# Scoop (Windows)
$ scoop install opencode

# macOS Homebrew
$ brew install opencode

✅ 验证：

bash

$ opencode --version
# 预期输出：v1.x.x（具体版本号）

⚠️ 常见错误：

command not found：说明安装路径未加入 PATH。尝试重新打开终端，或手动添加 ~/.npm-global/bin 到 PATH。
Permission denied（Mac/Linux）：在命令前加 sudo，或使用 npm install -g 时加上 --unsafe-perm 参数。

第 2 步：配置 API Key（连接AI模型）

🎯 目标：设置至少一个AI提供商的API密钥，让OpenCode能调用AI模型。

📝 操作：

OpenCode 支持75+模型提供商，你只需要配置其中一个即可开始使用。以下是最常用的三种：

方式一：设置环境变量（推荐）

bash

# 在终端中设置（临时生效，关闭终端后失效）
$ export ANTHROPIC_API_KEY="sk-ant-你的密钥"    // 使用 Claude（推荐）
# 或
$ export OPENAI_API_KEY="sk-你的密钥"          // 使用 GPT
# 或
$ export GEMINI_API_KEY="你的密钥"             // 使用 Gemini

方式二：永久保存（通过配置文件）

创建或编辑 ~/.config/opencode/opencode.json：

json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",       // 默认主模型
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-你的密钥"               // 替换为你的密钥
    }
  }
}

方式三：在OpenCode TUI内交互式配置

启动 OpenCode 后，输入 /connect 命令，按照提示选择提供商并输入密钥。

✅ 验证：

bash

$ opencode
# 启动后，输入任意问题，如 "Hello"，如果AI正常回答，说明配置成功。

🤔 为什么要这样做？ API Key 是AI服务的“门票”。OpenCode 本身是免费的，但调用 Claude、GPT 等模型需要各自的API Key，按使用量计费。建议先注册一个免费额度较多的提供商（如 Anthropic 提供 $5 免费额度）进行测试。

第 3 步：快速上手——第一次对话

🎯 目标：启动 OpenCode 并完成第一次AI辅助编程。

📝 操作：

bash

# 进入你的项目目录
$ cd /path/to/your/project

# 启动 OpenCode
$ opencode

你会看到一个终端界面（TUI），直接输入问题即可：

> 帮我看看这个项目的结构
> 给 src/utils.ts 添加一个防抖函数
> 修复 index.ts 第 42 行的类型错误

切换模式：按 Tab 键在两种模式间切换：

模式	说明
Build	完整工具访问权限，可以编辑文件、执行命令
Plan	仅分析和规划，不做任何修改（适合先确认方案）

✅ 验证：输入 > 这个目录下有哪些文件？，OpenCode 应该能列出当前目录的文件列表。

💡 提示：如果界面卡住，按 Ctrl+C 中断当前操作，重新输入。

第 4 步：初始化项目规则文件（AGENTS.md）

🎯 目标：让AI了解你的项目技术栈和编码规范，提高代码生成质量。

📝 操作：

在 OpenCode TUI 中输入：

/init

OpenCode 会自动扫描项目结构，生成 AGENTS.md 文件。

你也可以手动创建或编辑该文件：

markdown

# 项目规则

## 技术栈
- TypeScript + React + Vite
- Tailwind CSS 样式
- Vitest 测试框架

## 代码规范
- 使用函数式组件
- 所有组件必须有 TypeScript 类型定义
- 遵循 ESLint 规则

## 构建命令
- `npm run dev` - 开发服务器
- `npm run build` - 生产构建
- `npm test` - 运行测试

✅ 验证：再次向 OpenCode 提问代码相关问题时，它会参考 AGENTS.md 中的规则生成更符合项目风格的代码。

🤔 为什么要这样做？ AGENTS.md 相当于给AI的“项目说明书”。没有它，AI可能生成与你项目不兼容的代码（比如用 class 组件而不是函数式组件）。有了它，AI会按照你的项目规范输出。

第 5 步：安装 Oh-My-OpenCode 插件

🎯 目标：安装 Oh-My-OpenCode（OMO），将单个AI助手升级为多Agent协作团队。

📝 操作：

方式一：自动安装（推荐，让AI帮你完成）

将以下提示词复制粘贴到你的AI助手（如 Claude、ChatGPT）中：

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

AI会自动读取安装指南并完成所有配置。

方式二：手动交互式安装

bash

# 交互式安装（推荐）
$ bunx oh-my-opencode install

# 或非交互式安装（指定使用哪些AI服务）
$ bunx oh-my-opencode install --no-tui --claude=yes --openai=no --gemini=no

安装过程中会提示你选择拥有的AI订阅/服务（Claude Pro/Max、OpenAI/ChatGPT、Gemini等），根据实际情况选择。

✅ 验证：

bash

$ bunx oh-my-opencode doctor
# 如果输出类似 "All checks passed"，说明安装成功。

⚠️ 常见错误：

bunx: command not found：说明 Bun 未安装。回到“前置准备”安装 Bun。
安装过程卡住：检查网络连接，可能需要配置代理。国内用户建议使用方式一（让AI自动安装）。

第 6 步：初始化 Agent 模型配置

🎯 目标：配置各个Agent使用的AI模型，否则Agent系统无法正常工作。

📝 操作：

方式一：在OpenCode TUI中运行（推荐）

启动 OpenCode 后输入：

/init-deep

这会自动生成分层 AGENTS.md 文件，并初始化Agent配置。

方式二：手动编辑配置文件

配置文件位置（按优先级）：

项目配置：.opencode/oh-my-opencode.json
用户配置：
- Windows: %APPDATA%\opencode\oh-my-opencode.json
- Mac/Linux: ~/.config/opencode/oh-my-opencode.json

配置文件使用 JSONC 格式（支持注释和尾逗号）：

jsonc

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json",

  // 自定义 Agent 模型
  "agents": {
    "sisyphus": {
      "model": "anthropic/claude-opus-4-7"       // 主编排Agent，推荐最强模型
    },
    "oracle": {
      "model": "openai/gpt-5.4",
      "variant": "high"
    },
    "librarian": {
      "model": "google/gemini-3-flash"           // 搜索Agent，可用轻量模型
    }
  },

  // 自定义任务类别模型
  "categories": {
    "visual-engineering": {
      "model": "google/gemini-3.1-pro",
      "variant": "high"
    },
    "quick": {
      "model": "openai/gpt-5-nano"               // 简单任务用轻量模型
    }
  }
}

✅ 验证：配置完成后，重启 OpenCode，输入任意复杂问题（如“帮我重构这个模块”），如果看到多个Agent轮流工作，说明配置成功。

⚠️ 重要提示：

如果没有 Claude 订阅，Sisyphus Agent 可能无法正常工作。需要在配置中手动指定 Sisyphus 使用 OpenAI 模型。
官方强烈建议至少拥有 Claude Pro/Max 订阅以获得最佳体验。

第 7 步：实战——用“ultrawork”完成复杂任务

🎯 目标：使用 ultrawork 关键词让多Agent协作完成一个开发任务。

📝 操作：

在 OpenCode TUI 中输入以下提示（以“为 Express 项目添加 JWT 认证”为例）：

ultrawork 帮我为这个 Express 项目添加 JWT 认证，
包括登录、注册、token 刷新中间件。
要求：
1. 使用 jsonwebtoken 库
2. 遵循项目现有的错误处理模式
3. 添加单元测试

Oh-My-OpenCode 会自动：

Sisyphus（主编排者）分析任务，拆分为4个子任务
Explore（代码搜索Agent）并行搜索现有的认证实现和错误处理模式
Librarian（资源搜索Agent）搜索 JWT 安全最佳实践
Sisyphus-Junior（执行Agent）们并行实现各个模块
Oracle（审查Agent）审查最终实现
全部完成后交付结果

日常使用技巧：

场景	提示示例
简单任务	`帮我修复 auth.ts 的类型错误`
复杂任务	`ultrawork 重构整个用户模块，拆分为 service/controller/model 三层`
需要外部知识	`ultrawork 查找 Stripe API 最新的订阅管理方式并实现`
代码审查	`/review-work`

✅ 验证：任务完成后，检查项目目录，应该能看到新增或修改的文件（如 auth.js、auth.test.js 等）。

💡 提示：如果任务中途失败，可以输入 /handoff 创建上下文摘要，在新会话中继续工作。

进阶技巧（可选）

掌握基础后，你可以尝试：

自定义 Skills（技能包）：在 .opencode/skills/ 目录下创建领域专业知识包，如 git-master（Git专家）、playwright（浏览器自动化）等。
使用 Ralph Loop 自迭代开发：输入 /ralph-loop 后，AI 会持续执行任务直到完成，适合需要反复调试的场景。
多会话管理：OpenCode 支持保存和管理多个对话会话，按 Ctrl+S 保存当前会话，Ctrl+O 打开历史会话。

常见问题 (FAQ)

Q1: Windows 上必须用 WSL 吗？A: 不是必须，但强烈推荐。WSL 提供更好的文件系统性能和完整的终端支持。直接用 npm 安装也能运行，但某些高级功能（如 LSP）在 WSL 下更稳定。

Q2: 需要哪些 API Key？A: 至少需要一个 AI 提供商的 API Key。推荐 Anthropic Claude（Sisyphus 默认使用），也可以用 OpenAI GPT 系列。Oh-My-OpenCode 的某些 Agent 可以使用不同模型，按需配置。

Q3: Oh-My-OpenCode 收费吗？A: Oh-My-OpenCode 本身是开源免费的。但使用的 AI 模型（如 Claude、GPT）需要各自的 API Key，按模型提供商的定价计费。

Q4: 任务执行到一半失败了怎么办？A: Oh-My-OpenCode 支持会话恢复。使用 /handoff 创建上下文摘要，在新会话中继续工作。也可以直接重新输入提示词，AI 会从上次中断处继续。

Q5: 如何切换模型？A: 在 OpenCode TUI 中输入 /model <提供商>/<模型>，如 /model openai/gpt-5。也可以在 opencode.json 中修改 model 字段。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

OpenCode 安装与配置：通过多种方式安装，并连接AI模型提供商
项目规则文件：通过 AGENTS.md 让AI了解你的项目规范
Oh-My-OpenCode 插件：将单个AI助手升级为11个专业Agent的协作团队
ultrawork 实战：使用魔法关键词让多个Agent并行处理复杂任务
配置文件自定义：控制每个Agent使用的模型，实现“强弱搭配”

OpenCode + Oh-My-OpenCode 实战教程：从零搭建你的AI编程团队 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 安装 Bun（推荐，用于安装Oh-My-OpenCode） ​

第 1 步：安装 OpenCode ​

第 2 步：配置 API Key（连接AI模型） ​

第 3 步：快速上手——第一次对话 ​

第 4 步：初始化项目规则文件（AGENTS.md） ​

第 5 步：安装 Oh-My-OpenCode 插件 ​

第 6 步：初始化 Agent 模型配置 ​

第 7 步：实战——用“ultrawork”完成复杂任务 ​

进阶技巧（可选） ​

常见问题 (FAQ) ​

总结 ​

OpenCode + Oh-My-OpenCode 实战教程：从零搭建你的AI编程团队

你将学到什么

最终效果

前置准备

1. 安装 Bun（推荐，用于安装Oh-My-OpenCode）

第 1 步：安装 OpenCode

第 2 步：配置 API Key（连接AI模型）

第 3 步：快速上手——第一次对话

第 4 步：初始化项目规则文件（AGENTS.md）

第 5 步：安装 Oh-My-OpenCode 插件

第 6 步：初始化 Agent 模型配置

第 7 步：实战——用“ultrawork”完成复杂任务

进阶技巧（可选）

常见问题 (FAQ)

总结