1. Oh-My-OpenCode 项目概述
Oh-My-OpenCode 是一个基于 OpenCode 的多智能体协作系统,它将传统的单线程 AI 编程助手升级为一个由多个专业智能体组成的开发团队。这个系统通过智能任务分解和并行处理,显著提升了开发效率和任务完成度。
作为一名长期从事 AI 辅助开发工具研究的工程师,我发现传统 AI 编程工具存在几个明显痛点:单线程工作导致效率低下、复杂任务需要人工拆解、模型选择不够灵活等。Oh-My-OpenCode 通过引入多智能体架构,很好地解决了这些问题。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心概念解析
2.1 智能体架构设计
Oh-My-OpenCode 的核心是一个精心设计的智能体系统,每个智能体都有明确的职责分工:
code复制 ┌─────────────────┐
│ 用户需求输入 │
└────────┬────────┘
▼
┌─────────────────┐
│ Sisyphus │ ← 主编排器
│ (总指挥) │
└────────┬────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Prometheus │ │ Oracle │ │ Librarian │
│ (战略规划) │ │ (架构顾问) │ │ (文档专家) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Explore │ │ Hephaestus │ │ Atlas │
│ (代码搜索) │ │ (深度工匠) │ │ (任务指挥) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
2.2 任务类别机制
系统采用智能的任务分类机制,根据任务类型自动选择最适合的模型:
| 类别 | 用途 | 适合的模型 |
|---|---|---|
visual-engineering |
前端开发、UI组件 | 多模态模型 |
deep |
复杂重构、深度分析 | 推理强模型 |
quick |
简单修复、格式调整 | 响应快模型 |
ultrabrain |
高难度脑力任务 | 顶级模型 |
3. 环境准备与安装
3.1 系统要求
在开始安装前,请确保系统满足以下要求:
| 项目 | 要求 |
|---|---|
| Node.js | v20 或更高版本 |
| Bun | v1.0+(可选) |
| Git | 任意版本 |
| 操作系统 | Windows/macOS/Linux |
3.2 基础环境检查
打开终端,执行以下命令检查已安装工具:
bash复制# 检查 Node.js 版本(需要 v20+)
node --version
# 检查 Git 版本
git --version
如果未安装 Node.js,可按以下方式安装:
macOS:
bash复制brew install node
Linux (Ubuntu/Debian):
bash复制curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
3.3 OpenCode 基础安装
OpenCode 是 Oh-My-OpenCode 的基础运行环境,推荐使用 npm 安装:
bash复制# 设置官方源(避免镜像问题)
npm config set registry https://registry.npmjs.org
# 全局安装 OpenCode
npm install -g opencode-ai@latest
# 验证安装
opencode --version
# 应显示 1.0.150 或更高版本
4. Oh-My-OpenCode 安装指南
4.1 安装 Bun(可选)
Bun 可以提供更好的性能体验,但不是必须的:
macOS/Linux:
bash复制curl -fsSL https://bun.sh/install | bash
Windows:
powershell复制powershell -c "irm https://bun.sh/install.ps1 | iex"
4.2 主安装流程
交互式安装(推荐新手)
bash复制bunx oh-my-opencode install
# 或
npx oh-my-opencode@latest install
安装程序会询问你的 AI 订阅情况,根据实际情况回答即可。
非交互式安装(高级用户)
bash复制bunx oh-my-opencode install --no-tui \
--claude=no \
--openai=no \
--gemini=no \
--kimi-for-coding=yes \
--zai-coding-plan=yes \
--copilot=no
4.3 安装验证
成功安装后,你应该能看到类似输出:
code复制[OK] Kimi For Coding (Sisyphus/Prometheus fallback)
Model Assignment
Models auto-configured based on provider priority
Installation complete!
Run opencode to start!
5. 公司中转模型配置
5.1 配置文件结构
Oh-My-OpenCode 使用两个核心配置文件:
| 文件 | 路径 | 用途 |
|---|---|---|
| 主配置 | ~/.config/opencode/opencode.json |
插件加载、全局设置 |
| 模型配置 | ~/.config/opencode/oh-my-opencode.json |
智能体模型映射 |
5.2 配置步骤
- 创建主配置文件:
bash复制# macOS/Linux
vim ~/.config/opencode/opencode.json
# Windows
notepad ~/.config/opencode/opencode.json
内容如下:
json复制{
"plugin": ["oh-my-opencode"]
}
- 创建模型配置文件:
json复制{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
"agents": {
"sisyphus": {
"model": "kimi-k2.5",
"provider": "kimi"
},
"oracle": {
"model": "deepseek-v3.2",
"provider": "kimi"
},
"librarian": {
"model": "MiniMax/MiniMax-M2.7",
"provider": "minimax"
}
},
"categories": {
"visual-engineering": {
"model": "kimi-k2.5",
"provider": "kimi"
},
"ultrabrain": {
"model": "deepseek-v3.2",
"provider": "kimi"
}
},
"provider": {
"kimi": {
"apiKey": "your-api-key",
"baseURL": "http://your-proxy-server:port/v1",
"models": ["kimi-k2.5", "deepseek-v3.2", "qwen3-coder-plus"]
}
}
}
5.3 模型分配策略
| 智能体 | 推荐模型 | 原因 |
|---|---|---|
| Sisyphus | Kimi k2.5 | 最强模型,负责任务编排 |
| Oracle | DeepSeek v3.2 | 深度推理能力强 |
| Prometheus | GLM-5 | 规划任务,平衡性能 |
| Librarian | MiniMax M2.7 | 快速检索,成本低 |
6. 智能体使用指南
6.1 核心智能体功能
| 智能体 | 角色 | 典型使用场景 |
|---|---|---|
| Sisyphus | 主编排器 | 任何复杂任务 |
| Prometheus | 战略规划师 | 需求模糊的大项目 |
| Oracle | 架构顾问 | 架构设计、Bug调试 |
| Librarian | 文档研究员 | API查询、技术调研 |
6.2 调用方式
隐式调用(推荐)
bash复制ulw 帮我实现一个用户登录功能
显式调用特定智能体
bash复制@oracle 帮我分析这个架构的优缺点
@librarian 查询 React 19 的新特性
7. 实战应用场景
7.1 理解陌生项目
bash复制ulw 帮我分析这个项目的整体架构,画出主要模块的依赖关系图,
总结出核心业务流程和关键数据表结构。
执行流程:
- Explore 扫描目录结构
- Librarian 分析依赖文件
- Oracle 总结架构设计
- 整合输出完整报告
7.2 代码重构
bash复制ulw 重构 utils 目录下的所有工具函数:
- 统一命名规范为 camelCase
- 添加完整的 JSDoc 注释
- 抽取重复逻辑为公共函数
- 确保所有测试通过
7.3 技术调研
bash复制@librarian 调研以下内容并给出推荐方案:
1. React 状态管理方案对比(Redux/Zustand/Jotai)
2. 每个方案的优缺点
3. 在我们的场景下推荐哪个
8. 高级功能配置
8.1 自定义 Skills
在 .opencode/skills/ 目录下创建技能文件:
markdown复制---
name: code-review
description: 执行完整的代码审查流程
---
# 代码审查技能
1. 检查代码规范
2. 检查潜在 bug
3. 检查性能问题
4. 生成审查报告
使用技能:
bash复制使用 code-review 技能审查本次提交的所有代码
8.2 缓存配置
json复制"cache": {
"enabled": true,
"ttl": 3600
}
8.3 速率限制
json复制"rateLimit": {
"kimi": { "requestsPerMinute": 30 },
"zai": { "requestsPerMinute": 50 }
}
9. 常见问题排查
9.1 Windows 上提示 "bunx 不是内部命令"
解决方案:
powershell复制npx oh-my-opencode@latest install
9.2 模型调用失败
检查步骤:
bash复制# 测试 API 连接
opencode test --provider kimi
# 查看已配置模型
opencode models list
9.3 配置文件位置
- macOS/Linux:
~/.config/opencode/ - Windows:
%USERPROFILE%\.config\opencode\
10. 使用心得与建议
在实际使用 Oh-My-OpenCode 几个月后,我总结出以下几点经验:
-
任务描述要具体:给智能体的指令越明确,输出结果质量越高。避免模糊的表述,尽量提供具体的参数和要求。
-
合理使用智能体:根据任务性质选择合适的智能体。架构问题找 Oracle,文档查询找 Librarian,代码生成找 Hephaestus。
-
监控 API 用量:公司中转模型通常有调用限制,建议在配置中设置合理的速率限制,避免短时间内大量请求被阻断。
-
定期更新:Oh-My-OpenCode 和 OpenCode 都在快速迭代,保持最新版本可以获得更好的性能和功能。
-
技能库建设:将常用工作流封装成 Skills 可以大幅提升效率,建议团队共享一个 Skills 仓库。
