Oh My OpenCode 落地使用操作手册
Oh My OpenCode 是一款为 OpenCode 提供增强功能的插件,赋予其类似 Claude Code 的 Agent 协调能力、异步子 Agent 执行、多模型编排等高级特性。本手册旨在帮助开发团队快速理解、安装、配置并落地使用 Oh My OpenCode,提升 AI 辅助编程效率。手册涵盖环境准备、安装部署、核心功能使用、多 Agent 配置、最佳实践及常见问题解答,适用于从零基础入门到团队规模化应用的全流程指导。
第一章 概述与前置准备
1.1 什么是 Oh My OpenCode
Oh My OpenCode 是一个 OpenCode 插件,旨在:
- 提供多 Agent 编排与异步执行能力
- 内置经过策划的 MCPs、工具和模型
- 最大限度提升 OpenCode 的实际生产力
- 与 Claude Code 保持兼容并扩展原能力
通过该插件,OpenCode 不再只是单一会话助手,而能同时驱动多个智能 Agent 与工具协同工作。
1.2 前置要求
在开始安装前,请确保满足以下条件:
| 要求项 | 说明 |
|---|---|
| OpenCode | 已安装 OpenCode(建议版本 1.0.150+) |
| Node.js/Bun | 已安装 Node.js 或 Bun 运行环境 |
| 模型订阅 | 至少准备以下之一:Claude Pro/Max、ChatGPT Plus/Pro、Gemini 订阅 |
| 终端模拟器 | 推荐使用 WezTerm、Alacritty、Windows Terminal 等 |
1.3 检查 OpenCode 版本
opencode --version
确保输出版本号,建议使用较新版本。
第二章 安装与配置
2.1 安装 Oh My OpenCode
推荐方式 - 交互式安装:
bunx oh-my-opencode install
如果系统没有 bunx,可使用 npx:
npx oh-my-opencode install
非交互式安装(适合自动化脚本):
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=yes --gemini=yes
参数说明:
--claude: 启用 Claude 支持--chatgpt: 启用 ChatGPT 支持--gemini: 启用 Gemini 支持
注意:Ubuntu/Debian 用户如果通过 Snap 安装 Bun,可能遇到
bunx: script not found错误,建议使用 npx 或重新安装 Bun。
2.2 验证安装
检查配置文件是否已添加插件:
cat ~/.config/opencode/opencode.json
确认其中包含 oh-my-opencode 插件标识。
2.3 配置 Provider
方式一:交互式配置
opencode
# 在 OpenCode 中执行
/connect
按提示选择 Provider 并完成授权。
方式二:手动配置 API 密钥
编辑配置文件 ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}
第三章 多 Agent 配置与使用
3.1 Agent 配置文件
Oh My OpenCode 的核心优势在于多 Agent 编排。配置文件位于:
~/.config/opencode/oh-my-opencode.json
3.2 完整 Agent 配置示例
{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
"agents": {
"Sisyphus": {
"model": "axonhub-anthropic/claude-opus-4-5-20251101",
"comment": "主协调者 - 使用最强的 Opus 4.5 模型"
},
"librarian": {
"model": "axonhub-anthropic/claude-sonnet-4-5-20250929",
"comment": "文档查找和代码库分析 - 使用 Sonnet 4.5"
},
"explore": {
"model": "axonhub-anthropic/claude-haiku-4-5-20251001",
"comment": "快速代码库探索 - 使用快速的 Haiku 4.5"
},
"oracle": {
"model": "axonhub-anthropic/claude-opus-4-1-20250805",
"comment": "架构设计和代码审查 - 使用 Opus 4.1"
},
"frontend-ui-ux-engineer": {
"model": "axonhub-anthropic/claude-sonnet-4-5-20250929",
"comment": "前端开发 - 使用 Sonnet 4.5"
},
"document-writer": {
"model": "axonhub-anthropic/claude-3-7-sonnet-20250219",
"comment": "技术文档撰写 - 使用 Sonnet 3.7"
},
"multimodal-looker": {
"model": "axonhub-anthropic/claude-3-7-sonnet-20250219",
"comment": "视觉内容分析 - 使用 Sonnet 3.7"
}
}
}
3.3 Agent 角色说明
| Agent 名称 | 职责 | 推荐模型 |
|---|---|---|
| Sisyphus | 主协调者,负责任务分配和整体协调 | Claude Opus 4.5 |
| librarian | 文档查找、代码库分析 | Claude Sonnet 4.5 |
| explore | 快速代码库探索、文件搜索 | Claude Haiku 4.5 |
| oracle | 架构设计、代码审查 | Claude Opus 4.1 |
| frontend-ui-ux-engineer | 前端开发、UI/UX 实现 | Claude Sonnet 4.5 |
| document-writer | 技术文档撰写 | Claude Sonnet 3.7 |
| multimodal-looker | 视觉内容分析、图片理解 | Claude Sonnet 3.7 |
第四章 核心功能使用
4.1 启动与基础操作
启动 OpenCode:
# 进入项目目录
cd /path/to/your/project
# 启动 OpenCode
opencode
基础操作:
| 操作 | 命令/快捷键 | 说明 |
|---|---|---|
| 发送消息 | Enter | 发送输入给 AI |
| 换行输入 | Shift+Enter / Ctrl+Enter | 插入换行 |
| 引用文件 | @文件名 | 模糊搜索并引用文件 |
| 执行命令 | !命令 | 执行 Shell 命令 |
4.2 Plan 与 Build 模式
OpenCode 提供两种核心工作模式:
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Plan | 只读模式,仅分析规划 | 代码审查、需求规划、方案设计 |
| Build | 完整操作权限,可修改文件 | 实际开发、编写代码、修复 bug |
切换方式: 按 Tab 键切换模式
使用示例:
# Plan 模式 - 规划方案
实现一个用户删除功能,要求软删除,并提供恢复界面
# Build 模式 - 执行实现
按照刚才的计划开始实现
4.3 常用内置命令
| 命令 | 快捷键 | 功能 |
|---|---|---|
/connect |
- | 连接/切换 LLM Provider |
/init |
- | 初始化项目,生成 AGENTS.md |
/undo |
Ctrl+Z | 撤销上一个操作 |
/redo |
Ctrl+Y | 重做已撤销的操作 |
/models |
- | 查看可用模型列表 |
/clear |
Ctrl+L | 清空终端界面 |
/exit |
Ctrl+D | 退出 OpenCode |
4.4 项目初始化
首次使用新项目时,执行初始化:
opencode
# 在 OpenCode 中执行
/init
此命令会:
- 自动分析项目结构
- 生成
AGENTS.md文件 - 建议将
AGENTS.md提交到 Git 仓库
第五章 高级配置
5.1 完整配置文件示例
{
"$schema": "https://opencode.ai/config.json",
"theme": "tokyonight",
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5",
"autoupdate": true,
"tui": {
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto"
},
"server": {
"port": 4096,
"hostname": "0.0.0.0",
"mdns": true
},
"permission": {
"edit": "allow",
"bash": "ask"
},
"compaction": {
"auto": true,
"prune": true
},
"instructions": [
"CONTRIBUTING.md",
"docs/guidelines.md"
]
}
5.2 环境变量配置
使用环境变量保护敏感信息:
{
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}
5.3 本地模型配置(Ollama)
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"llama2": {
"name": "Llama 2"
},
"codellama": {
"name": "Code Llama"
}
}
}
}
}
第六章 团队落地最佳实践
6.1 项目规范化
创建 AGENTS.md
- 每个项目根目录包含
AGENTS.md - 描述项目架构、技术栈、编码规范
- 提交到版本控制
- 每个项目根目录包含
统一配置管理
- 团队共享基础配置文件
- 使用环境变量管理个人密钥
- 版本控制共享配置模板
6.2 Agent 分工策略
大型任务处理流程:
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Sisyphus │───→│ librarian │───→│ explore │
│ (任务协调) │ │ (代码分析) │ │ (快速探索) │
└─────────────┘ └─────────────┘ └─────────────┘
│
↓
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ oracle │ │ frontend- │ │ document- │
│ (架构审查) │ │ ui-ux- │ │ writer │
│ │ │ engineer │ │ (文档生成) │
└─────────────┘ │ (前端开发) │ └─────────────┘
└─────────────┘
6.3 工作流建议
| 场景 | 推荐模式 | Agent | 操作步骤 |
|---|---|---|---|
| 新功能开发 | Build | Sisyphus + 专业 Agent | Plan 规划 → Build 实现 |
| 代码审查 | Plan | oracle | 只读分析,输出报告 |
| Bug 修复 | Build | explore + Sisyphus | 定位问题 → 修复验证 |
| 文档编写 | Build | document-writer | 自动生成 + 人工审核 |
| 代码重构 | Plan/Build | oracle + librarian | 分析影响 → 执行重构 |
6.4 安全与权限管理
{
"permission": {
"edit": "allow",
"bash": "ask"
}
}
- edit:
allow允许 AI 编辑文件,ask每次询问 - bash:
ask执行命令前确认,allow自动执行
第七章 常见问题与解决方案
7.1 安装问题
| 问题 | 解决方案 |
|---|---|
bunx: script not found |
使用 npx 替代,或重新安装 Bun |
| 安装后插件未生效 | 检查 ~/.config/opencode/opencode.json |
| Provider 连接失败 | 检查 API 密钥和网络连接 |
7.2 使用问题
| 问题 | 解决方案 |
|---|---|
| Agent 未按预期工作 | 检查 oh-my-opencode.json 配置 |
| 模型响应慢 | 切换至轻量级模型(Haiku) |
| 上下文过长 | 启用 compaction.auto: true |
| 工具调用失败 | 检查本地模型上下文长度设置 |
7.3 性能优化
启用自动压缩
JSON"compaction": { "auto": true, "prune": true }合理选择模型
- 简单任务:使用 Haiku 系列
- 复杂任务:使用 Opus 系列
- 日常开发:使用 Sonnet 系列
定期清理会话
- 使用
/clear清理界面 - 长时间会话建议重启
- 使用
第八章 附录
8.1 配置文件优先级
| 优先级 | 位置 | 说明 |
|---|---|---|
| 1 | .well-known/opencode |
远程组织配置 |
| 2 | ~/.config/opencode/opencode.json |
全局用户配置 |
| 3 | OPENCODE_CONFIG 环境变量 |
自定义配置路径 |
| 4 | 项目根目录 opencode.json |
项目专属配置 |
| 5 | .opencode 目录 |
Agent、命令配置 |
| 6 | OPENCODE_CONFIG_CONTENT |
运行时临时配置 |
8.2 参考资源
- OpenCode 官方文档: https://opencode.ai/docs
- GitHub 仓库: https://github.com/anomalyco/opencode
- Oh My OpenCode 项目: https://github.com/code-yeongyu/oh-my-opencode
8.3 快速参考卡
# 安装
bunx oh-my-opencode install
# 启动
opencode
# 连接 Provider
/connect
# 初始化项目
/init
# 切换 Plan/Build 模式
Tab
# 撤销/重做
/undo 或 Ctrl+Z
/redo 或 Ctrl+Y
# 引用文件
@文件名
# 执行命令
!命令