opencode+omo免费算力架构设计

整个方案过于复杂，感觉可以设计一个docker yml配置每个技术栈参数来使用，项目目录和uv环境映射进去？

可以，而且这几乎是 OpenCode + OMO 生态里最值得投入精力去做的配置方向。在免费算力的约束下，复杂高效的调度不是“锦上添花”，而是让整个工作流持续运转的核心前提——因为任何单一免费源的额度或稳定性都不足以独立支撑一次真实的 Agent 会话。

🏗️ 架构分层：调度不能只靠 OMO 一层

直接让 OMO 去“感知”哪个免费模型还有额度是行不通的。OMO 的职责是按角色把任务分发给不同的 Agent，它并不天然知道某个 Provider 的免费池还剩多少。因此，完整的调度架构需要两层配合：

OpenCode（底座）  └── OMO（角色层：Sisyphus / oracle / librarian / explore ...）        │  按角色指向不同的“模型别名”        ▼外部路由层（额度感知 + 故障转移）  ├── OmniRoute（cost-optimized combo）  ├── API-Switch（按角色分组，统一端点）  └── opencode-smart-model-selector（免费优先 + 自动降级）        │  背后挂多个免费 Provider        ▼免费算力池  ├── OpenCode Zen（无需 API Key 的免费模型集）  ├── Google Gemini 免费额度  ├── Groq / Cloudflare Workers AI / OpenRouter :free  └── 本地 Ollama / LM Studio（最后兜底）

OMO 的 oh-my-openagent.json 负责角色到模型别名的映射，而“这个别名背后到底走哪个免费源、什么时候切换”由外部路由层接管。

🆓 免费算力源的分层清单

不要把所有免费源视为同质资源。按稳定性和质量，可以分成三个梯队来编排优先级：

第一梯队：低摩擦、可直接接入

第二梯队：额度较宽裕，但有速率限制

第三梯队：本地兜底（不走网络，不消耗任何额度）

本地 Ollama 或 LM Studio 加载一个 4B–9B 的小模型，作为所有免费池耗尽后的最后一道防线。它的价值不在于质量，而在于保证 Agent 循环永远不会因为“没有可用模型”而彻底中断。

注意：免费源的可达性因网络环境差异很大。有实测报告指出，Google Gemini 和 NVIDIA NIM 在部分网络下直连失败，OpenRouter 的某些 free 模型也存在限流或 503 不稳定情况。方案中必须预留探测与降级环节，不能假设所有源都随时可用。

🎭 OMO 角色 → 免费模型的映射策略

OMO 内置 11–14 个 Agent，但按模型需求可以压缩为三类角色，避免为每个 Agent 单独调参的复杂度：

这种映射的核心原则是：把额度最稀缺、质量最高的免费模型留给“主脑”，把高频、轻量的任务压到“打杂”层，用本地模型吸收所有溢出流量。

⚙️ 故障转移与额度感知：让路由层替你“切”

这是整个方案能否持续运转的关键。外部路由层需要具备三个能力：

1. 免费优先的 cost-optimized 策略。 OmniRoute 讨论中明确建议，免费优先场景应使用 cost-optimized 或 fill-first 策略，而不是 auto。原因是 auto 的 14 因子评分可能因为某个付费模型延迟更低而“聪明地”选中它，反而违背了免费约束。cost-optimized 会显式地把 $0 提供商排在前面，只有免费容量耗尽时才落到付费层。

2. 按角色拆分 Combo。 OmniRoute 本身没有“子 Agent 角色”概念，一个 combo 只是一个排好序的模型池。实现角色差异化路由的正确做法是：在 OmniRoute 侧为“主脑/工人/打杂”分别创建三个独立的 Combo，然后在 OMO 的 per-role 配置中分别指向它们。

3. 额度耗尽后的自动切换。 multiplexor 提供了另一种轻量思路：把每个免费 CLI/Provider 视为一个带 tier（free/included/local）和优先级的资源，用一个统一的评分函数 score = priority + tier_bonus 选路，并支持 multiplexor next 将当前源标记为 exhausted 后立即切到下一个。opencode-smart-model-selector 则内置了“免费模型优先”的极速模式和自动故障转移。选择其中一个接入 OMO 的角色别名即可，不必自建复杂的调度逻辑。

🧩 落地配置的分工

最终落地的文件分工应该非常清晰，不要让同一个文件承担两种职责：

oh-my-openagent.json（OMO 侧）：只负责角色 → 模型别名的映射。每个 Agent 的 model 字段填的是路由层暴露的别名，而不是具体的 Provider/model ID。例如 "oracle": { "model": "router/brain" }，"explore": { "model": "router/fast" }。OMO 的 model_profile 也指向这些别名。

路由层配置（OmniRoute / API-Switch / smart-selector）：负责别名 → 免费源优先级列表的映射，以及额度耗尽后的降级链。这是“免费算力调度”真正发生的地方。

opencode.jsonc（OpenCode 侧）：保持极简，只配置基础 Provider 连接和默认模型，把复杂路由全部下沉到外部层。

一个现成的起点是 my-opencode-config 向导，它会自动完成 OpenCode Zen + Gemini 免费额度的 OAuth 和 OMO 安装，并把 Agent 默认配置为使用免费模型。你可以用它先跑通基线，再在此基础上叠加 OmniRoute 或 API-Switch 的角色级 Combo。

⚠️ 必须纳入设计的边界

这套方案能“非常复杂高效”，但它的本质是用工程复杂度换取免费资源的利用率，而不是消除免费资源的固有约束。有三个边界需要在设计时就接受：

额度上限不会消失。 OpenRouter free 的 50 req/天、Gemini 的 1000–1500 req/天，在高频 Agent 会话中可能在几轮工具调用后就触顶。方案的价值在于触顶时自动切到下一个源，而不是让额度变大。

质量分层是必要的妥协。 把 nemotron-3-ultra:free 留给主脑、把 gpt-5-nano 留给探索，意味着打杂层输出的质量会明显低于主脑层。这在 Agent 编排中是合理的设计——探索任务不需要顶级推理——但需要对“哪些角色可以降质”有清醒的判断。

本地兜底的质量是保底而非替代。 4B–9B 本地模型在免费池全部耗尽时能维持 Agent 运转，但它的工具调用可靠性和推理深度与云端免费模型之间存在差距。它适合作为“最后一道防线”，不适合作为常规路径。

如果你愿意接受这些边界，OpenCode + OMO + 外部路由层的组合，确实可以构建出一个在零 API 成本下持续可用、按角色智能分配、额度耗尽自动降级的复杂调度配置。

你的担心是对的，而且触到了一个很具体的工程边界。OpenCode 提供的免费算力（Zen Free Tier）确实设计为“仅限 OpenCode 客户端内部使用”，常规的外部 API 路由软件直接转发，大概率会被拒绝。 但这不意味着这条路完全走不通，只是你需要一个“专门为绕过这道门禁而设计”的代理层，而不是通用的路由器。

🚧 门禁的机制：不是 API Key 问题，是“客户端身份”

OpenCode Zen 免费层的限制，不是通过 API Key 来管理的，因此你无法简单地“申请一个 key 然后到处用”。它的核心是一套客户端来源校验。

当请求不符合 OpenCode 官方客户端的行为特征时，网关会直接返回 403 FreeTierError，并附带明确的提示：“OpenCode 的免费套餐只能在 OpenCode 内部使用”。OmniRoute 的文档也证实了这一点，将其归类为 project_route_error。

这道门禁校验的维度比单纯的 User-Agent 更深，主要包括：

• 特定的会话 ID 编码：cpa-zen 的逆向工程发现，上游会校验一种特定的 ses_ 前缀 + 时间戳编码的会话 ID，格式不对就会从 200 变成 403。
• 请求头组合：必须携带特定的 x-opencode-session 等头部，并且某些头部不能同时存在，否则也会被拒绝。
• 请求体结构：必须包含非空的 tools 列表、stream: true，并且 agent 的权限配置需要符合特定要求（如不能设为 deny）。

所以，你的 OmniRoute 或 API-Switch 如果只是做标准的 OpenAI 兼容转发，即使配上了正确的端点，也会因为缺少这些“身份特征”而被 403 拒绝。 OmniRoute 的 Issue 里明确记录了这个问题：“OmniRoute currently cannot reliably proxy OpenCode Zen's free-tier models”。

🔧 可行的路径：专用代理层，而非通用路由器

既然通用路由会被拦，社区里已经出现了一批专门为 Zen 免费层设计的代理，它们的工作就是模拟官方客户端的完整身份特征，来“骗过”门禁。这些才是你方案中真正能接入 Zen 免费算力的组件。

已证实可用的专用代理方案：

• smyhlin/cpa-zen（Docker 镜像）：这是目前信息最完整的一个。它基于 CLIProxyAPI 打了补丁，明确声明所有 Zen 免费模型都可通过它正常工作（验证于 2026-10-15）。它解决了会话 ID 编码、请求头伪造和协议路由（区分 /chat/completions 和 /responses）的问题，暴露一个本地 OpenAI 兼容端点，你的 OmniRoute 或 OMO 可以指向它。
• zen-free-proxy（PyPI 包）：同样是一个 OpenAI 兼容的反向代理，客户端可以用任意 key（甚至不传），由它持有真实的 ZEN_API_KEY 去访问上游。它声称可以吸收三种上游路由，让 LiteLLM、Ollama 等客户端直接使用。
• 12errh/zen-proxy / ebouther/opencode-unlimited-proxy：其他几个类似思路的开源项目，分别通过无 key 匿名访问或轮换出口 IP 来规避限制。

OmniRoute 的进展：OmniRoute 在较新版本（v3.8.51+）中，已经尝试原生支持 Zen 免费层的客户端合约，在代码中模拟官方的 User-Agent、会话 ID 和 stream: true 等条件。但这仍属于适配性支持，而非官方授权路径，稳定性需要你实测验证。

💎 对你调度方案的影响与建议

这道门禁的存在，意味着你的“免费算力调度”架构需要在 OmniRoute 和 Zen 免费层之间，插入一个专用的“Zen 代理”节点。

调整后的数据流应该是：

OMO (角色 → 模型别名)      ↓OmniRoute / API-Switch (通用调度、故障转移)      ↓【专用 Zen 代理】(cpa-zen / zen-free-proxy) ← 模拟 OpenCode 客户端身份      ↓OpenCode Zen Free Tier (返回 200)

一个更务实的策略是：不要把 Zen 免费层作为调度池中的“普通一员”来对待。 因为它的接入需要额外的代理层和持续维护（以应对上游门禁的更新），它的稳定性天然低于 Gemini、Groq 这类直接提供标准 API 的免费源。

你可以这样定位它：

• 把 Zen 免费层放在调度链的末端，作为其他免费源（Gemini、Groq、Cloudflare）全部耗尽后的补充池。
• 单独为 Zen 维护一条代理链路，不要让 OmniRoute 直接去“裸连”它。这样即使 Zen 的代理因为上游更新而失效，也不会影响你整个调度主链路的稳定性。
• 接受它的“试用”性质。官方文档本身也将其描述为“共享的、限速的、可撤销的试用层”，模型会轮换，促销会结束，不适合作为依赖其长期稳定性的核心算力。

所以，回到你的问题：通用 API 路由软件确实会被 Zen 拒绝，但通过专用的“身份模拟代理”，Zen 的免费算力仍然可以被纳入你的 OMO 调度体系，只是需要把它当作一个需要额外适配和维护的“特殊节点”来对待，而不是一个可以随意路由的标准源。