1. Oh My Opencode 多 agent 编排到底解决什么问题如果你最近在折腾 OpenCode大概率会刷到 Oh My Opencode 这个名字。简单说它是一个跑在 OpenCode 之上的多模型代理编排框架你不再只跟一个通用助手对话而是把任务按类型分派给不同的专职 agent——规划、审查、搜索、写前端、做架构决策各管一摊。它解决的问题很具体单个模型再强也不可能同时擅长深度推理、快速 grep、UI 设计和文档检索硬塞给一个模型只会又慢又贵。Oh My Opencode 适合谁我观察下来有三类人最受益。第一类是手里项目开始变大、单文件改动已经理不清依赖关系的开发者第二类是经常做重构、迁移、线上变更需要留下完整决策记录的人第三类是想把多个模型能力拼起来用、又不想自己写调度逻辑的人。它的核心思路是分层规划层由你和 Prometheus 一起把需求聊清楚执行层由 Atlas 这类编排器把计划拆成待办工作层再交给 Sisyphus-Junior、Oracle、Explore 这些专业 agent 去落地。但多 agent 一跑起来第一个卡点往往不是编排逻辑而是模型通道。每个 agent 背后挂着不同厂商的模型你要分别配 key、分别处理限流、分别记模型名配置一多就容易乱。这篇就按「先讲清各 agent 职责和常用命令再给一套统一 Key 接入的配置骨架」的顺序来写配置片段可以直接复制验证命令也逐条给到目标是让你把 agent 调用链路先跑通再谈调优。2. 各 agent 职责分工与高频命令速查在动手配之前先把「谁干什么」理清楚不然配置里写错 agent 名会排查很久。Oh My Opencode 的 agent 大致分四层我按实际使用频率排一下。核心智能体里Sisyphus 是默认编排器负责计划、委派和并行执行走的是待办驱动的工作流Hephaestus 是目标导向的自主执行者行动前会先做彻底研究适合端到端任务Oracle 只读咨询专做架构决策、代码审查和调试Librarian 负责多代码库分析和文档查询Explore 是快速代码库探索和上下文 grepMultimodal-Looker 处理 PDF、图片、图表这类视觉内容。计划智能体里Prometheus 是采访式规划师通过迭代提问产出详细计划Metis 在计划前做顾问分析识别隐藏意图和歧义Momus 是计划审查员按清晰性、可验证性和完整性来验证计划。编排智能体里Atlas 是待办列表编排器系统化执行计划任务Sisyphus-Junior 是类别触发的执行器模型根据任务类别自动选择。内置类别这块很关键它决定了 task 委派时用哪个模型visual-engineering 走 Gemini 3 Pro 做前端 UIultrabrain 走 GPT-5.3 Codex 做深度逻辑推理deep 也是 GPT-5.3 Codex 但推理档位不同artistry 走 Gemini 3 Pro 做高创造性任务quick 走 Claude Haiku 4.5 处理琐碎改动writing 走 Kimi K2P5 做文档技术写作。常用命令我整理成一张表日常高频的就这些命令作用备注/agents切换 agent配合 Tab 键选 Hephaestus 等/connect快速添加 API 密钥、切换模型提供商首次接入用得上/models查看所有已连接可用模型并一键切换排查模型是否挂上/init扫描项目生成 AGENTS.md新项目第一步/compact压缩总结当前会话减少视觉干扰/handoff生成背景摘要便于新 session 继续跨会话接续/new清空上下文开新会话换任务时用/sessions切换 session多任务并行/start-work基于 plan 开始工作Prometheus 计划后执行/refactor智能重构带 LSP、AST-grep、TDD 验证重构场景/review基于 git diff 审查当前改动提交前自查/undo /redo撤销/重做最后操作需 Git 仓库/share分享当前会话生成链接协作排查两种模式的区别也顺带说清Hephaestus 模式适合复杂架构推理、跨领域知识综合你切到它之后它自己规划执行Sisyphus ulwultrawork模式适合「你犯懒了、不想写详细需求」的场景输入 ulw 或 ultrawork 后 agent 自己搜索代码库、研究模式、实现功能、诊断验证一直干到完成。对大多数人来说Sisyphus 里用 ulw 是默认路径覆盖九成复杂任务只有你特别需要 GPT-5.3 Codex 的推理风格时再切 Hephaestus。3. TaoToken 统一 Key 接入的前置准备多 agent 编排最烦的就是模型通道分散。Oh My Opencode 里每个 agent 背后可能是不同厂商的模型如果每个都单独配 keysettings.json 会变成一锅粥而且某个厂商限流时你很难快速切换。TaoToken 在这里的角色就是统一入口你拿一个 Key通过它的 API 通道去访问不同模型配置里只维护一份鉴权和 base_urlagent 换模型时改模型名就行不用动鉴权部分。前置准备其实就三步。第一步去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号这一步不用展开按页面提示走就行。第二步进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 API Key建议按用途分 Key比如编排用一个、实验用一个方便后面排查是哪个环节出的问题。第三步把 API 地址记下来https://taotoken.net/api注意这个地址不带任何查询参数配置里 base_url 就填它。这里有个容易踩的坑很多人把 base_url 写成带 /v1 或带具体路径的形式结果请求 404。正确做法是 base_url 只到域名加 /api具体路径由客户端自己拼。另外 Key 不要硬编码进会提交到 Git 的文件里用环境变量或者本地不纳入版本管理的配置文件。如果你后面要长期跑编码任务、Agent 常驻可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite它更适合这种持续调用的场景只是临时验证模型通不通用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 更快。4. settings.json 与 config.toml 配置骨架下面给的是骨架不是完整可运行项目你要按自己实际用的 agent 和模型名替换占位符。先看 settings.json它主要管 OpenCode 层面的 provider 和模型映射{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { claude-opus-4-6: { name: claude-opus-4-6 }, claude-sonnet-4-5: { name: claude-sonnet-4-5 }, claude-haiku-4-5: { name: claude-haiku-4-5 }, gpt-5.3-codex: { name: gpt-5.3-codex }, gemini-3-pro: { name: gemini-3-pro }, kimi-k2p5: { name: kimi-k2p5 } } } }, defaultProvider: taotoken }这里 apiKey 用 ${TAOTOKEN_API_KEY} 引用环境变量别直接写明文。models 里列的是你实际会委派到的模型按 agent 需要增删。注意模型名要和 TaoToken 侧支持的名称一致写错了不会报「模型不存在」而是直接请求失败排查时容易误判成网络问题。再看 config.toml它管 agent 到模型的映射和类别默认值[orchestration] default_agent Sisyphus planner Prometheus reviewer Momus advisor Metis [agents.Sisyphus] model claude-opus-4-6 provider taotoken [agents.Hephaestus] model gpt-5.3-codex provider taotoken [agents.Oracle] model gpt-5.3-codex provider taotoken readonly true [agents.Explore] model claude-haiku-4-5 provider taotoken [agents.Librarian] model claude-sonnet-4-5 provider taotoken [categories.visual-engineering] model gemini-3-pro [categories.ultrabrain] model gpt-5.3-codex [categories.quick] model claude-haiku-4-5 [categories.writing] model kimi-k2p5两个文件的分工要记牢settings.json 定义「有哪些 provider 和模型可用」config.toml 定义「哪个 agent 用哪个模型」。改模型时优先动 config.toml别去 settings.json 里翻。如果你把 provider 写成 taotoken 但 settings.json 里没定义这个 provider启动时会直接报 provider 未找到这是最常见的配置错误之一。5. 逐条验证从 Key 到 agent 调用链路配完别急着跑复杂任务按下面顺序逐条验证出问题能快速定位到哪一层。第一步验证 Key 和环境变量是否生效echo $TAOTOKEN_API_KEY | head -c 8能打印出前 8 位说明环境变量挂上了。如果为空检查你的 shell 配置文件有没有 source或者是不是在错误的终端会话里。第二步直接打一次 API确认通道通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ | head -c 300返回模型列表就说明 Key 和 base_url 都对。如果返回 401是 Key 问题返回 404多半是 base_url 写错检查是不是多写了路径。第三步启动 OpenCode 后用 /models 看模型有没有挂上opencode # 进入后输入 /models列表里能看到你在 settings.json 里定义的模型名说明 provider 配置被正确加载。看不到就回去检查 JSON 语法逗号、引号错一个都会静默失败。第四步用 /agents 切到 Explore 做一次轻量调用验证 agent 到模型的映射/agents # 选择 Explore然后输入一个简单任务 grep 一下项目里所有 TODO 注释Explore 走的是 Haiku 这类快模型响应应该很快。如果这里报模型不可用说明 config.toml 里 Explore 的 model 名和 settings.json 里定义的对不上。第五步跑一次完整编排链路验证 Prometheus 到 Atlas 到子 agent 的委派plan 给现有项目加一个健康检查接口 # Prometheus 会开始提问回答完生成计划 /start-work计划生成在 .sisyphus/plans/ 下/start-work 后 Atlas 接管任务分发到具体子 agent。这一步能跑通说明整条链路都通了。如果卡在某一步看是规划阶段没出计划还是执行阶段某个 agent 报模型错误对应回去查那一层的配置。6. 本篇常见错误排查配置阶段最高频的错误是 provider 名不一致。settings.json 里定义的是 taotokenconfig.toml 里写成 taotoken 或别的名字启动就报 provider 未找到。统一用一个小写单词别中途改。第二个是 base_url 多写路径。有人习惯性写成 https://taotoken.net/api/v1结果请求拼成 /api/v1/v1/... 直接 404。记住 base_url 只到 /api。第三个是模型名拼写。claude-opus-4-6 写成 claude-opus-4.6 或者 claude-4-opus请求会失败但报错信息不一定直观。建议从 /models 返回的列表里复制名称别手打。第四个是环境变量没生效。你在 .zshrc 里加了 export但当前终端是之前开的没重新 sourceecho 出来是空的。新开一个终端或者 source 一下配置文件。第五个是 agent 映射漏配。config.toml 里只配了 Sisyphus但任务委派到了 ExploreExplore 没有 model 定义就会回退到默认或者直接失败。把你会用到的 agent 都显式配上别依赖隐式回退。第六个是 readonly agent 被写了。Oracle 这类只读咨询 agent如果你在配置里没标 readonly它可能会尝试改文件行为不符合预期。按上面骨架里那样显式标 readonly true。排查顺序建议从下往上先 curl 验证 Key 和通道再 /models 验证 provider 加载再 /agents 验证单个 agent最后跑完整编排。哪一层断了就停在哪一层查别一上来就跑复杂任务那样报错信息会混在一起很难定位。如果你在接入过程中卡在鉴权或配置加载优先去看 API Keys 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 核对 Key 状态再对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 检查参数格式。长期跑编码和 Agent 常驻任务的话Coding Plan 那条通道更省心只是验证某个模型通不通模型对话页点一下最快。配置这东西跑通一次之后就是复制粘贴真正花时间的是第一次把链路理顺。