夜雨聆风从工具选型到 Agent 分工、Category 路由与 Fallback 链设计
文章定位 这不是一篇“装插件教程”，而是一次 AI 编程工作台的工程化配置复盘：为什么选 OpenCode、怎么用 Oh My OpenAgent 做多智能体编排、如何避免模型浪费和不可用风险 |
目录速览
• 一、为什么选择 OpenCode，而不是 Claude Code、Codex？
• 二、Oh My OpenAgent 解决的不是“有没有模型”，而是“怎么调度模型”
• 三、核心架构：OpenCode 是底座，Oh My OpenAgent 是调度层
• 四、安装与诊断：别装完就以为能用
• 五、Agent 不是越多越好，关键是分工要清楚
• 六、Category 调度：真正决定体验的是这层映射
• 七、国内用户推荐：优先考虑一个 Provider 覆盖多模型
• 八、Fallback 链设计：不要只配主模型
• 九、常见踩坑与排查清单
• 十、最后的配置建议
一、为什么选择 OpenCode，而不是 Claude Code、Codex？
在开始讲 Oh My OpenAgent 之前，有个问题要先说清楚：为什么这套方案基于 OpenCode，而不是直接用 Claude Code 或 Codex？
这不是因为 Claude Code 或 Codex 不好。恰恰相反，它们都是当前 AI 编程工具里非常重要的代表。Claude Code 官方定位为能够读取代码库、跨文件修改、运行测试并交付代码结果的 agentic coding system；Codex CLI 是 OpenAI 的本地终端 coding agent，能够读取、修改并运行当前目录下的代码，并且是开源、Rust 实现。
但这次真正要解决的，不是“找一个最强的 AI 编程助手”，而是“搭建一套可配置、可替换、可扩展、适合长期使用的 AI 编程工作台”。从这个目标看，OpenCode 更合适。
OpenCode 的价值不是绑定某一个模型，而是把模型当作可插拔资源管理。官方说明中，OpenCode 是 open source AI coding agent，支持免费模型，也可以连接 Claude、GPT、Gemini 等不同模型；它还支持多个 provider、本地模型、Agents 和插件扩展。
我的判断：个人快速写代码，Claude Code 和 Codex 都值得用；但如果目标是多模型、多 Agent、多 Provider、多 Fallback 的工程化配置，OpenCode 更适合作为底座。 |
这对国内用户尤其重要。实际使用时，经常会遇到模型访问不稳定、订阅能力重叠、中文体验差异、成本不可控、团队需要统一配置等问题。如果工具强绑定某一家模型厂商，后续空间会受限。
所以，本文不是要证明 OpenCode 比 Claude Code 或 Codex 更强，而是要说明：当 AI 编程从单点工具升级为工程化工作流时，OpenCode 提供了更开放的组合空间。
二、Oh My OpenAgent 解决的不是“有没有模型”，而是“怎么调度模型”
很多人用 AI 编程工具时，习惯性问一个问题：哪个模型最强？但在真实开发场景里，这个问题并不准确。
开发任务不是一种任务。复杂系统设计需要深度推理，报错定位需要快速搜索，文档整理需要低成本摘要，截图分析又要求模型具备图像输入能力。
如果所有任务都交给一个顶级模型，结果通常是成本高、速度慢，而且稳定性未必更好。
一句话理解 Oh My OpenAgent 不是简单帮 OpenCode 接入更多模型，而是让不同任务进入不同 Agent，再由不同 Agent 调用合适模型。 |
三、核心架构：OpenCode 是底座，Oh My OpenAgent 是调度层
OpenCode 本身负责编辑器、会话、模型调用、工具执行等基础能力。Oh My OpenAgent 则负责更上层的智能体编排。
~/.config/opencode/├── opencode.json # OpenCode 全局配置：provider、默认模型、插件列表└── oh-my-openagent.json # OmO 插件配置：agent 模型映射、fallback 链、category 路由项目目录/├── opencode.json # 项目级 OpenCode 配置└── .opencode/└── oh-my-openagent.json # 项目级 OmO 配置，优先级高于全局配置 |
这里有个关键点：项目级配置优先级高于全局配置。所以，如果某个项目需要特定模型组合，可以单独在项目目录里放一份 .opencode/oh-my-openagent.json，不要把所有策略都堆到全局。
实践建议 一个前端项目可以偏向视觉工程和快速修改；一个后端复杂系统可以偏向深度推理和架构分析；一个文档项目则可以把 writing 类任务交给中文能力更强、成本更低的模型。 |
四、安装与诊断：别装完就以为能用
官方推荐安装方式很简单，但安装完成不等于真正可用。很多人装完后发现后台 Agent 没反应，或者 ultrawork 一跑，几个 Agent 全部返回空。
bunx oh-my-openagent installbunx oh-my-openagent doctor |
这通常不是插件坏了，而是模型所在 provider 没有认证。也就是说，配置里写了 deepseek/deepseek-v4-pro，但环境里没有 DEEPSEEK_API_KEY；或者配置了 Claude、OpenAI、Kimi、火山引擎模型，但对应 API Key、OAuth 或订阅状态没有打通。
opencode --versionbun --versionnode --versioncat ~/.config/opencode/opencode.json | grep oh-my |
判断标准 不要先怀疑 Agent，不要先重装插件。先确认 provider 是否认证、模型是否在 models 中声明、API Key 是否能被 OpenCode 读取。 |
五、Agent 不是越多越好，关键是分工要清楚
Oh My OpenAgent 的 Agent 体系很丰富，常见包括 Sisyphus、Hephaestus、Oracle、Prometheus、Librarian、Explore、Multimodal Looker、Momus、Atlas 等。
Agent | 角色 | 模型选择重点 |
Sisyphus | 主指挥官：任务分解、调度、推进 | 强推理、长上下文、指令遵循 |
Hephaestus | 深度执行者：独立完成复杂开发任务 | 代码生成质量、自主执行能力 |
Oracle | 架构和调试专家：根因分析 | 严谨推理、系统级分析 |
Prometheus | 规划师：需求澄清和方案设计 | 结构化思维、需求理解 |
Librarian | 文档和代码检索专家 | 速度优先、低成本 |
Explore | 快速搜索专家 | 响应快，不需要顶级推理 |
Multimodal Looker | 多模态分析专家 | 必须支持图像输入 |
最容易犯的错误，是给所有 Agent 配同一个强模型。比如全部使用 Claude Opus、Kimi K2 或 GPT-5.5。看起来很豪华，实际并不划算。
强推理任务用强模型，检索类任务用快模型，兜底任务用免费或低成本模型。 |
六、Category 调度：真正决定体验的是这层映射
Sisyphus 在调度子任务时，选择的很多时候不是具体模型，而是任务类别，例如 ultrabrain、deep、quick、writing、visual-engineering、unspecified-high、unspecified-low。
"categories": {"ultrabrain": {"model": "volcengine-plan/kimi-k2.6"},"quick": {"model": "volcengine-plan/minimax-m2.7"},"writing": {"model": "volcengine-plan/glm-5.1"}} |
Category | 推荐模型类型 | 典型任务 |
ultrabrain / deep | 强推理模型 | 系统设计、复杂改造、算法实现 |
quick / unspecified-low | 速度型模型 | 配置修改、简单 bug、格式修正 |
writing | 中文强模型 | README、公众号、技术文档 |
visual-engineering | 推理与前端理解均衡 | 组件开发、UI/UX、样式调整 |
配置重点 Category 配得好，系统会自然变得聪明又省钱；Category 配得差，就会出现小任务调用大模型、大任务调用弱模型的问题。 |
七、国内用户推荐：优先考虑一个 Provider 覆盖多模型
如果在国内环境使用，我更推荐优先考虑能覆盖多模型的 OpenAI-compatible provider。原因很现实：配置统一、认证统一，模型组合也更丰富。
一个 provider 里可以同时放强推理模型、代码模型、多模态模型和低成本快速模型，这样 fallback 链更稳定，也不用在多个 provider 之间频繁处理认证问题。
任务类型 | 推荐分配 |
主指挥官 Sisyphus | Kimi K2.6 / Claude Opus / GPT-5.5 等强推理模型 |
架构调试 Oracle | GLM 5.1 / Kimi K2.6 / DeepSeek Pro |
深度执行 Hephaestus | 代码专用模型，如 Doubao Code / Codex 系列 |
检索与快速定位 | MiniMax M2.7 / DeepSeek Flash / Haiku |
写作任务 | GLM 5.1 / Kimi / Claude Sonnet |
多模态分析 | 必须选择支持 image input 的模型 |
现实判断 这套配置思路未必是理论最强，但更适合日常使用：稳定、可控、成本不过分。 |
八、Fallback 链设计：不要只配主模型
很多配置只写主模型。这在简单场景可以用，但一旦模型限流、欠费或临时不可用，Agent 就可能直接失败。
{"model": "volcengine-plan/kimi-k2.6","fallback_models": [{ "model": "volcengine-plan/glm-5.1" },{ "model": "volcengine-plan/doubao-seed-2.0-pro" }]} |
Fallback 链有三个原则：同族优先、逐步降级、多模态对齐。
同族优先，是为了减少认证失败概率；逐步降级，是为了从强推理到中等推理，再到速度型或免费兜底；多模态对齐，是为了避免主模型支持图像、fallback 却处理不了图片。
不要这样配 不要把 Multimodal Looker 的 fallback 直接配置成不支持图像输入的免费模型。表面上有兜底，实际关键场景还是不可用。 |
九、常见踩坑与排查清单
问题 | 常见原因 | 处理建议 |
后台 Agent 全部返回空 | provider 没认证，API Key 或 OAuth 未完成 | 先检查 API Key，不要先重装插件 |
Doctor 提示 unknown model | 自定义 provider 的模型未在内置列表 | 确认 OpenCode 是否能识别 provider 和 models 声明 |
macOS 桌面端读不到环境变量 | 从 Dock 启动不继承 shell 环境变量 | 从终端启动或使用 launchctl setenv |
多模态任务失败 | fallback 模型不支持 image input | 主模型与 fallback 都要声明 image 输入 |
免费模型效果不稳定 | 速率低、上下文小、推理弱 | 只放在 fallback 最后一环 |
# 检查环境变量for key in DEEPSEEK_API_KEY OPENCODE_API_KEY ANTHROPIC_API_KEY OPENAI_API_KEY; doval=$(printenv "$key" 2>/dev/null)if [ -n "$val" ]; then echo "$key: OK"; else echo "$key: MISSING"; fidone |
十、最后的配置建议
如果只给一个可落地建议，我会这样配：
主指挥官：强推理模型深度开发：代码模型架构调试：强推理模型文档检索：低成本快模型快速搜索：低成本快模型写作任务：中文强模型多模态任务：明确支持图像输入的模型Fallback：同 provider 优先，最后放免费兜底 |
不要追求配置看起来高级。真正好的配置，是每天用起来稳定、不乱花钱、失败时能自动降级，而且不同任务响应速度符合预期。
对个人开发者来说，最重要的是控制成本和稳定性；对企业或团队来说，更重要的是可治理、可追踪和可替换。
Oh My OpenAgent 不是一个“装上就变强”的插件，而是一套需要认真配置的 AI 编程调度系统。配置好了，它能明显提升 OpenCode 的上限；配置不好，它只会让问题变复杂。 |
我的建议是从小开始：先配置 deep、quick、writing 三类任务，再逐步扩展到多 Agent、多 provider、多 fallback 链。先让系统跑稳，再谈复杂编排。
