新年来分享我的oh-my-opencode配置和学习心得 - 开发调优
用opencode也一两个月了，眼看着oh-my-opencode越发完善，很多设计理念都让我感到十分精妙， 让最合适的模型去做最合适的agent，让每个agent配置对应不同的任务 ，各司其职的感觉不仅让我想起电台头的歌曲 Everything In Its Right Place （虽然歌名和实际表达的意思正好相反）。
由于oh-my-opencode更新很频繁，github上readme很多时候更新不及时，也不够详细，这里就简单介绍一下最新版的agents集群架构。
简单来说就是oh-my-opencode通过把写代码，甚至是任何可以AI操作的电脑任务拆解成几个部分：规划、查阅、执行，具体的agent带着prompt、skills等上下文各司其职，团队分工合作完成复杂任务，多说无益我们看这个简化版的架构图：
我们大致可以拆成四个部分来看这张图：
a.编排器与调度器
- Sisyphus （主控 & 总工程师）
- 西西弗斯主agent，绝大多数时候都是和用户对话的agent和所有任务的入口
- 总规划编排调度，可以调用其他subagent，必要时还可以临时创建特定任务的agent
- 非常简单的任务也会自己直接阅读/写代码，有时其他agent职责没有覆盖/完成的也会自己上手
- Atlas （调度器 & 计划执行器）
- 阅读Sisyphus或者Prometheus的 plan ，逐条执行 ToDo
- 主要功能是调用其他 subagent ，分配具体任务
- 简单问题也会自己直接执行读写文件
b.计划与验证
- Prometheus （战略规划师）
- 生成 plan 给Atlas，一般由Sisyphus调用，如果用户对任务有详细的认知和描述可以手动切换直接与Prometheus对话，这样会更精确执行用户的目标
- 可能会询问用户问题来澄清需求
- Metis （预分析规划顾问）
- Prometheus的分析顾问，制定 plan 之前的风险分析和方案探索
- 挖隐含需求、补上下文、避免过度设计
- Momus （战略审查师）
- 作为Prometheus的审稿人对 plan 审查与结果验证
c.检索与顾问
- Oracle （架构/调试顾问）
- 当其他agent（Atlas/Sisyphus等）有疑问的时候调用Oracle解决局部难点
- 一般是解释代码给出建议，做头脑风暴、审阅
- Librarian （检索专家）
- grep文档、API、README、GitHub代码
- 当其他agent需要外部信息的时候调用它
- Explore （代码库探索）
- 做结构化的语义grep，告诉其它agent某段逻辑、风格
- 当其他agent需要本地文档信息的时候调用它
- multimodal‑looker （多模态分析师）
- 查看PDF、图片、截图等内容
d.执行器
- Hephaestus （长周期执行器）
- 利用codex系列长期工作的特性执行那些需要几十分钟起步的任务
- 循环跑读、写代码、运行、检查结果的循环
- 由Sisyphus或Atlas调用
- Sisyphus‑Junior （单任务执行器）
- 由用户创建或者Sisyphus临时生成的特定任务执行器
- 专注于某一种任务的执行，可以读写代码
- 用户可以手动在categories字段创建（见下文的json配置）
*注：除了上面两个，Sisyphus和Atlas本身也可以读写文件，任务简单的时候也能直接修改代码，在早期版本中，Sisyphus会倾向于自己修改代码或者调用opencode的build agent修改代码，现在更加完善了
看完上面的每个agent分析，是不是发觉这个agents集群是一个精妙的系统，agent之间可以互相调用，可以返回各种信息，需要时还可以创建新的agent新的skill和其他约束最终高质量的交付。就这种各司其职的，让每个agent和模型做最适合自己的事情就像是拆解了一台精妙仪器一样。
在下一节的jsonc代码里我会列出每个agent最适合的模型
佬友佬友，你讲了这么多，我似懂非懂了，那有没有一键使用的模板呢
有的，兄弟有的
理解了上面的原理后，下面这份模板你就可以拿走改改变成最适合自己的了
首先在你的机器上找到.config/opencode 路径（win上是 %USERPROFILE%\.config\opencode ），安装并运行oh-my-opencode（如果没有安装可以在opencode里的build模式里直接给AI说我要安装oh-my-opencode，把github链接甩过去他就会安装了）之后就会有一个 oh-my-opencode.json 文件，我们可以把这个json改成jsonc文件（这样兼容性更好，支持批注和更多语法），然后按照我下面的参考进行配置。
我自己在用的配置如下，其中fallback链是结合代码和作者的推荐给出的推荐模型顺序，优先选择上面靠前的模型，意味着这个模型更适合这个任务，当然没有相关模型的订阅也可以顺次换成其他推荐的模型。写的模型是我正在用的，因为我没有官方的claude订阅（用的第三方API），所以用GPT代替了一部分claude模型（OpenAI订阅真的量大管饱啊），你们也可以根据自己的订阅来切换不同的模型。
{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
//2026-02-28
//"disabled_agents": ["oracle", "multimodal-looker"],//来禁用某个特定代理
"runtime_fallback": {
"enabled": true,
"retry_on_errors": [400, 429, 500, 503, 529],
"max_fallback_attempts": 3,
"cooldown_seconds": 60, // 回退冷却时间，防止短时间反复尝试已故障的模型
"timeout_seconds": 60, // 单个请求超时时间（秒），超过则视为失败并触发回退，默认30
"notify_on_fallback": true
},
"agents": {
// ======================
// 1. 编排规划与验证系列
// ======================
"sisyphus": {
// 主编排器：委托任务编排分配、TODO、后台并行、动态组合技能，调用subagent
// fallback：claude-opus-4-6 → kimi-k2.5 → glm-4.7 → gpt-5.3-codex → gemini-3-pro
"model": "claude/claude-opus-4-6",
"temperature": 0.1,
"fallback_models": [
"kimi-for-coding/k2p5",
"zai-coding-plan/glm-4.7",
"openai/gpt-5.3-codex",
"google/gemini-3-pro-preview"
]
},
"atlas": {
// 高级编排器：全生命周期管理，任务路由，基于skills调度，全局会话级别的编排器，一般由内部逻辑/hook唤起
// fallback：claude-sonnet-4-5 → kimi-k2.5 → gpt-5.2 → gemini-3-pro
"model": "openai/gpt-5.2",
"temperature": 0.1,
"fallback_models": [
"anthropic/claude-sonnet-4-5",
"kimi-for-coding/k2p5",
"google/gemini-3-pro-preview"
]
},
"prometheus": {
// 战略规划：澄清需求、验证计划、复杂任务分解，推荐内部plan而不是和用户直接交互
// fallback：claude-opus-4-6 → kimi-k2.5 → gpt-5.2
"model": "claude/claude-opus-4-6",
"temperature": 0.1,
"fallback_models": ["kimi-for-coding/k2p5", "openai/gpt-5.2"]
},
"metis": {
// 预分析规划顾问：正式plan/执行前进行问题理解、风险与上下文分析，温度略高，探索更多方案
// fallback：claude-opus-4-6 → kimi-k2.5 → gpt-5.2-high
"model": "anthropic/claude-opus-4-6",
"temperature": 0.3,
"variant": "max",
"fallback_models": ["kimi-for-coding/k2p5", "openai/gpt-5.2"]
},
"momus": {
// 计划与结果验证：对计划/方案进行合理性检查和评审
// gpt-5.2 → claude-opus-4-6 → gemini-3-pro
"model": "openai/gpt-5.2",
"temperature": 0.1,
"variant": "medium",
"fallback_models": [
"anthropic/claude-opus-4-6",
"google/gemini-3-pro-preview"
]
},
// ======================
// 2. 执行系
// ======================
"hephaestus": {
// 深度自主工作专用，长周期，深度任务
// 只推荐OpenAI codex模型，如果没有codex则不会使用这个agent
"model": "openai/gpt-5.3-codex",
"temperature": 0.1,
"fallback_models": ["openai/gpt-5.2-codex"]
},
// ======================
// 3. 顾问与检索系
// ======================
"oracle": {
// 咨询/调试/架构专家：代码审查、复杂问题拆解，交互式问答
// fallback：gpt-5.2-high → gemini-3-pro → claude-opus-4-6
"model": "openai/gpt-5.2",
"temperature": 0.1,
"variant": "high",
"fallback_models": [
"google/gemini-3-pro-preview",
"anthropic/claude-opus-4-6"
]
},
"librarian": {
// 文档/仓库检索专家：文档/README/API 手册/GitHub 仓库搜索，大量输入，需要快速便宜长上下文的模型
// fallback：glm-4.7 → gpt-5.3-codex-spark → gemini-3-flash
"model": "zai-coding-plan/glm-4.7",
"fallback_models": [
"zai-coding-plan/glm-4.7",
"openai/gpt-5.3-codex-spark",
"gemini/gemini-3-flash-preview"
]
},
"explore": {
// 快速代码库探索:grep（上下文感知搜索）
// fallback：gpt-5.3-codex-spark → grok-code-fast-1 → claude-haiku-4-5 → gpt-5-mini → gpt-5-nano
"model": "openai/gpt-5.3-codex-spark",
"fallback_models": [
"github-copilot/grok-code-fast-1",
"anthropic/claude-haiku-4-5",
"openai/gpt-5-mini",
"openai/gpt-5-nano"
]
},
"multimodal-looker": {
// 多模态分析：PDF/图片分析，多模态好的模型
// fallback：gemini-3-flash → kimi-k2.5
"model": "gemini/gemini-3-pro-preview",
"fallback_models": [
"gemini/gemini-3-flash-preview",
"kimi-for-coding/k2p5"
]
}
},
"categories": {
// 快速小活：haiku / gemini-flash / nano
"quick": { "model": "openai/gpt-5.3-codex-spark", "temperature": 0.1 },
// 深度执行：codex / opus / gemini-pro
"deep": {
"model": "openai/gpt-5.3-codex",
"variant": "medium",
"temperature": 0.1
},
// 超大脑：codex xhigh（更激进）
"ultrabrain": {
"model": "openai/gpt-5.3-codex",
"variant": "xhigh",
"temperature": 0.1
},
// 视觉/前端/GUI：gemini-pro-high / glm-5 / opus
"visual-engineering": {
"model": "google/gemini-3-pro-preview",
"temperature": 0.1
},
// 文本/写作：glm4.7 / k2.5 / gemini-flash / sonnet
"writing": { "model": "gemini/gemini-3-pro-preview", "temperature": 0.2 },
// 未指定低/高档位
"unspecified-low": {
"model": "claude/claude-sonnet-4-5",
"temperature": 0.1
},
"unspecified-high": {
"model": "claude/claude-opus-4-6",
"variant": "max",
"temperature": 0.1
}
}
}其中categories部分也是看自己的需求添加即可
上面模型前面的供应商是 opencode.jsonc 里的provider，模型是模型的调用名字，假如说我在全局opencode配置里加了
"new-api": {
"npm": "@ai-sdk/openai",
"name": "New API (OpenAI Responses)",
"options": {
"baseURL": "https://newapi.example.com/v1",
"apiKey": "sk-123456789"
},
"models": {
"gpt-5.2": { "name": "gpt-5.2 (New API)" },
"gpt-5.3-codex": { "name": "gpt-5.3 codex (New API)" }
}
},那我在 oh-my-opencode.jsonc 里就写 new-api/gpt-5.3-codex 即可
大部分模型都是可以按照fallback列表配置的，有推荐列表前面的模型对应的订阅就优先选择它，后面的也不是不能用，总体上丰俭由人，根据自己手里的渠道选择
值得注意的是，谷歌宣布从3月10号下架Gemini 3.0 Pro，建议替换成3.1 Pro
一些模型选择的思路： codex是那种说什么就做什么的模型，绝不多做，也不发挥主观能动性给你代码优化，而opus就更喜欢帮你优化代码，有更多主观能动性（GPT 5.2/5.3 codex对比opus4.5/4.6），所以codex就更适合做写代码的，opus更适合给codex布置任务、监工。又比如codex-spark是非常快的那种，就适合做大量grep的任务，Gemini多模态明显是御三家里最好的，所以就拿来多模态这样子。还有一些思路，比如说西西弗斯和阿特拉斯用不同家的模型互补，普罗米修斯和其他审阅plan的模型也不一样这样才能集思广益。
2.28修改：在上面配置里添加了 佬友加的fallback 配置，具体解释：
"runtime_fallback": { // 全局回退策略
"enabled": true, // 打开回退，默认是关闭（不写的话）
"retry_on_errors": [ // 哪些报错会回退
400, // Bad Request（部分 provider 的临时无效请求，可重试）
429, // Rate Limit / 频率限制 / 配额用尽（最常见触发场景）
500, // Internal Server Error（服务器内部错误）
503, // Service Unavailable（服务暂时不可用）
529 // 部分提供商（如 Gemini、中转服务）的过载/临时错误
],
"max_fallback_attempts": 5, // 单个请求允许的最大回退尝试次数（包含原始模型），默认为3
"cooldown_seconds": 60, // 模型回退后进入冷却的时间（秒），防止短时间内反复尝试同一个已故障的模型
"timeout_seconds": 30, // 单个请求超时时间（秒），超过则视为失败并触发回退，默认30
"notify_on_fallback": true // 发生模型切换时，是否弹出桌面通知告知用户（推荐开启，方便知道发生了回退）
},