Pre

OMC - 01 用 19 个 Agent 打造你的 Claude Code“工程团队”：oh-my-claudecode 深度解析与实战指南

OMC - 02 五分钟起步，走向多智能体协作：深入解析 oh-my-claudecode 快速开始与架构设计

OMC - 03 从 0 到高效：Oh My ClaudeCode 安装与实践全指南

OMC - 04 用好 Oh-My-ClaudeCode 的 30 个会话技能：从“帮我写点代码”到端到端自动交付

OMC - 05 从单人到多 Agent：Oh-my-claudecode 的插件架构解析

OMC - 06 从“大模型管家”到“十九人专家团队”：oh-my-claudecode 的多 Agent 工程实践

OMC - 07 把「选模型」当成一门工程学：oh-my-claudecode 的三层模型路由实践

OMC - 08 在多 Agent 时代，如何优雅地「分工协作」：oh-my-claudecode 委托分类体系深度解读

OMC - 09 oh-my-claudecode 的多 Agent 编排实战

OMC - 10 从创意到“免看管生产力”：深入解析 Oh-My-ClaudeCode 的 Autopilot 与 Ralph 模式

---

在多模型协同时代，单一 LLM 的视角越来越难以满足复杂工程场景的需求。
Claude-Codex-Gemini（CCG）合成机制，提供了一种轻量级但结构严谨的跨供应商协同方式：由 Claude 负责编排，通过统一的 omc ask 命令并行调用 Codex 与 Gemini，再对多方意见做结构化合成与裁决。

面向对象主要包括三类读者：

• 需要多模型交叉验证代码与架构决策的工程师和架构师
• 希望理解多模型编排模式的研究者与工具开发者
• 在本地或企业环境中落地 AI 工程工具链的实践者

下文将从整体架构、CLI 路由层、外部顾问脚本、三阶段编排协议、降级机制以及与互操作模式的关系几个方面，系统拆解 CCG 的设计与实现，并给出具体使用场景与实践建议。

---

一、为什么需要 CCG：多视角、低开销的跨模型“咨询室”

在工程实践里，常见的需求包括：

• 希望 Codex 从“编译器+工程师”视角检查架构、复杂逻辑与测试策略
• 希望 Gemini 从“产品+用户体验”视角审视接口设计、文档与易用性
• 希望有人能站在更高一层的位置，把两边的意见做出有理由的取舍与合成

CCG 的核心目标可以概括为三点：

• 利用不同模型的偏好与长板，形成互补视角
• 保持单次调用无状态，无需 tmux、持久会话与复杂状态管理
• 提供统一 CLI 入口与可审计的产物文件，方便调试、追踪与持续集成

因此，CCG 更像是一次性的“多模型会诊”：在秒级时间内完成分解、并行咨询和合成决策，非常适合代码审查、方案评估、接口设计讨论等场景。

---

二、整体架构：分解、分发、合成的三阶段流水线

2.1 三阶段流程总览

CCG 的流水线可以抽象为三个阶段：

1. 分解（Decompose）：Claude 将用户请求拆解为两个互补的顾问提示词，并提前制定合成策略。
2. 分发（Distribute）：通过统一的 omc ask CLI，分别调用 Codex 与 Gemini 的 CLI 工具，作为外部“顾问”。
3. 合成（Synthesize）：从磁盘读取两份产物文件，Claude 进行对比分析，输出统一且可执行的结果。

这三个阶段通过以下几个关键组件串联起来：

• 统一入口：omc ask 命令
• 提供商路由与参数解析：ask.ts 中的 askCommand() 和 parseAskArgs()
• 外部顾问脚本：scripts/run-provider-advisor.js
• 产物存储目录：.omc/artifacts/ask/*.md

可以把 Claude 看作主治医生，通过 omc ask 把同一病例发给 Codex（偏工程）、Gemini（偏体验），再综合两位会诊医生的报告给出最后方案。

2.2 基于产物文件而非 stdout 的设计

一个重要设计是：合成并不是直接读取 CLI 的 stdout，而是基于 .omc/artifacts/ask/codex-*.md、gemini-*.md 这类结构化 Markdown 产物文件来完成。
每个产物包含：

• 原始任务描述
• 最终提示词（包括 Agent 提示词注入后的完整内容）
• 原始模型输出
• 退出码与摘要行
• 建议的后续操作项

这种设计的好处包括：

• 避免 stdout 被截断或多进程交错导致的混乱
• 能以统一结构落地到版本库、CI 报表或审计系统
• 方便后续做二次分析、可视化与统计

---

三、omc ask：统一 CLI 路由层的设计与实现

3.1 命令签名与提供商枚举

omc ask 是整个 CCG 的“正门”，支持三类 provider：claude、codex、gemini。
在 TypeScript 中，提供商集合被定义为编译期常量元组：

const ASK_PROVIDERS = ['claude', 'codex', 'gemini'] as const;
export type AskProvider = (typeof ASK_PROVIDERS)[number];

CLI 层在 src/cli/index.ts 中注册 ask 命令，并将具体逻辑委托给 askCommand()。

3.2 参数解析与 Agent 提示词注入

parseAskArgs() 支持三种调用风格：

调用模式	示例	用例
位置参数	omc ask codex "review this PR"	快速的单次查询
显式提示词	omc ask gemini --prompt "suggest UX improvements"	包含特殊字符的复杂提示词
Agent 提示词	omc ask codex --agent-prompt architect "evaluate..."	以特定角色进行分析

其中，--agent-prompt 会触发 resolveAgentPromptContent()：从 agents 目录（或项目作用域的 .codex/prompts/）中读取对应的 .md 文件，将整段 Agent 人设拼接到用户提示之前。
角色名称需要符合 ^[a-z][a-z0-9-]*$ 的严格正则，以避免路径遍历等安全问题。

这种机制带来的好处是：

• 可以将“架构师”、“安全审计员”、“文档工程师”等不同角色预设为 Agent
• CCG 为每个外部顾问选择不同的 Agent 组合，让 Codex/Gemini 从不同视角出发进行分析
• 使用者无需反复手写复杂 prompt，只需通过 CLI 选用对应角色即可

3.3 安全门控：控制外部 LLM 是否可用

在调用非 Claude 提供商之前，askCommand() 会检查 isExternalLLMDisabled()。
当配置中开启 disableExternalLLM 策略时：

• 只允许 claude 提供商
• 对 codex、gemini 请求直接拒绝并返回清晰错误信息

这个设计使得企业环境可以在不修改技能配置的前提下，一键切断外部云端模型，只保留自家或专有部署的 Claude，从而满足合规与数据安全要求。

---

四、run-provider-advisor.js：外部顾问适配与隔离

4.1 脚本角色：唯一转换层

真正调用各家 CLI 的逻辑集中在 scripts/run-provider-advisor.js 中，它由 askCommand() 以子进程方式调起。
它是统一接口和异构 CLI 之间的唯一转换层，负责：

• 构建不同 provider 所需的 CLI 参数
• 处理长、多行 prompt 的传输方式
• 剥离敏感环境变量，隔离会话状态
• 探测二进制可用性并生成 Markdown 产物

4.2 提供商特定参数构建

buildProviderArgs() 根据不同提供商生成对应的二进制与参数组合：

提供商	二进制文件	CLI 参数	备注
Claude	claude	-p	简单打印模式
Codex	codex	exec --dangerously-bypass-approvals-and-sandbox	非交互式执行需绕过审批与沙箱
Gemini	gemini	-p --yolo	--yolo 用于跳过交互式确认

对开发者来说，这意味着使用 omc ask 时不需要记住各家 CLI 的细节；所有模型调用都走一条统一路径，由脚本负责适配。

4.3 长提示词与 stdin 管道

对于长度超过 500 字符或包含换行符的提示词，脚本会判断应通过 stdin 传递，而非作为命令行参数。
这是为了避免：

• 命令行长度限制
• Shell 转义问题，尤其是在 Windows 平台上

该判断逻辑集中在 shouldPipePromptViaStdin() 中，对 Codex 和 Gemini 尤其关键，可显著减少因为参数转义导致的奇怪故障。

4.4 环境变量剥离与会话隔离

为了防止外部顾问探测到当前正在运行的 Claude Code 会话，从而触发递归调用或污染会话状态，buildProviderEnv() 会在启动前清理部分环境变量：

• 所有提供商统一剥离：CLAUDECODE、CLAUDE_SESSION_ID、CLAUDECODE_SESSION_ID、CLAUDE_CODE_ENTRYPOINT
• 对 Codex 额外剥离：RUST_LOG、RUST_BACKTRACE、RUST_LIB_BACKTRACE

这样，每一次顾问调用都在“干净”的环境中执行，避免不同工具之间产生隐性耦合。

4.5 二进制探测与 Markdown 产物写入

执行前，ensureBinary() 会通过执行 <binary> --version 来确认可用性，在 Windows 上若失败则回退到 where 命令。
执行后，writeArtifact() 负责将结果写入 .omc/artifacts/ask/<provider-*.md>：

• 包含任务描述、最终 prompt、输出内容、退出码、摘要与后续建议
• 文件名通过 slugify() 对任务内容进行 URL 安全截断生成

这种 Markdown 产物化机制，既方便人类阅读，也方便上层技能进行解析与合成。

---

五、CCG 编排协议：从请求分解到结果合成

CCG 技能处在最高的 Level-5 层级，通过 /oh-my-claudecode:ccg 调用时遵循严格的执行协议。

5.1 阶段一：请求分解

Claude 在接收到用户请求后会完成三件事：

• 生成 Codex 顾问提示：偏重架构设计、正确性、后端逻辑、风险分析与测试策略
• 生成 Gemini 顾问提示：偏重 UX、内容清晰度、边缘情况可用性与文档完善度
• 制定合成计划：提前思考如果两者出现冲突，应如何权衡、优先哪类因素、需要哪些补充信息

对比普通“多模型调用”，这里的关键区别是：提示不是简单复用同一个文本，而是刻意拉开侧重点，让两个顾问形成“互补视差”。

5.2 阶段二：并行分发

由于 Claude Code 技能体系不支持在一个技能内部再调用另一个技能，因此分发阶段必须通过 Bash 直接执行 CLI：

omc ask codex  "<codex_prompt>"
omc ask gemini "<gemini_prompt>"

这两条命令可以在脚本层面并行执行，也可以由调度器进行并发管理，其产物会分别落在 .omc/artifacts/ask/ 下，对后续合成透明。

5.3 阶段三：结果合成

Claude 从 .omc/artifacts/ask/ 中读取最新的 Codex 与 Gemini 产物，按照统一结构生成最终回应：

1. 共识建议：列出两位顾问一致认可的部分
2. 冲突建议：指出分歧点，并附上对各自观点的分析
3. 最终选定方向：给出裁决及理由，例如优先稳定性还是优先用户体验
4. 行动清单：转化为清晰、可执行的 TODO 项

这样的输出结构非常适合落地到工程实践中：

• 可以直接作为 PR 审查意见附在评论里
• 可以转换为 issue 或任务列表
• 可以作为技术决策记录存档

---

六、优雅降级：在各种异常条件下仍然可用

真实世界环境中，外部提供商不可用、CLI 缺失、策略禁用等情况非常常见。CCG 提前设计了一整套降级与回退机制。

6.1 场景矩阵与行为

CCG 的行为逻辑大致如下：

场景	行为说明
两个提供商均可用	完整三模型合成与冲突解决
一个提供商不可用	使用可用提供商 + Claude 合成，并标注缺失视角
两个提供商均不可用	仅 Claude 作答，并说明外部顾问不可用
提供商二进制缺失	ensureBinary() 预先退出并输出诊断信息
外部 LLM 被禁用	isExternalLLMDisabled() 在解析阶段拒绝非 Claude 调用

通过这套机制，调用方不需要为每种故障额外写条件分支，只要依赖 CCG 的统一行为即可。

6.2 对工程实践的意义

对工程实践者来说，这种降级能力可以：

• 直接嵌入 CI/CD：即便某个云服务短暂故障，也能保证流水线有降级结果而非整体崩溃
• 满足合规要求：在某些环境中可一键关闭外部 LLM，只保留 Claude 结果
• 简化运维负担：问题通常可通过产物与日志快速定位到二进制缺失、策略配置或网络问题

---

七、与互操作模式的关系：轻量 CCG vs 重量 Interop

CCG 并不是跨供应商协作的唯一模式，它与“互操作模式”（Interop）共同构成了 oh-my-claudecode 的跨模型工具箱。

7.1 互操作模式概览

互操作模式（src/cli/interop.ts）会启动一个持久化的 tmux 布局：

• 左侧是 Claude Code
• 右侧是 Codex CLI
• 中间通过 .omc/state/interop/ 下的共享状态与任务队列进行对话

共享状态由 shared-state.ts 管理，用于实现：

• 任务传递和消息队列
• 产物交接
• 长时间运行的协作会话

互操作模式通过环境变量 OMX_OMC_INTEROP_ENABLED、OMX_OMC_INTEROP_MODE、OMC_INTEROP_TOOLS_ENABLED 控制，支持 off、observe、active 等模式，以适应不同程度的自动化。

7.2 关键维度对比

维度	CCG 合成	互操作模式
会话生命周期	无状态，单次调用	持久化，长时间运行
提供商数量	Claude + Codex + Gemini（3 个）	Claude + Codex（2 个）
通信方式	基于文件的 Markdown 产物	双向任务队列 + 共享状态文件
运行时要求	仅需 Bash 工具，无 tmux 依赖	需要 tmux 与 MCP 工具
时间开销	秒级，适合即取即用	分钟级，会话搭建与持续协作
典型场景	快速交叉验证、多视角评审、一次性咨询	协作开发、长流程任务、持续交互式会话

如果把互操作模式比作长期项目中的“跨团队项目群会议”，那么 CCG 更像是为单一问题开的一次“专家会诊”，省去了长时间管理会话和状态的成本。

---

八、实践场景与使用示例

8.1 多视角代码评审

典型工作流：

1. 开发者对某个 PR 运行 CCG，请 Codex 从架构完整性和边界情况角度检查实现，请 Gemini 从可读性、文档与 API 设计易用性角度进行评审。
2. Claude 汇总输出：
   • 共识问题（例如：某模块耦合度过高、缺少关键单元测试）
   • 分歧点（例如：Codex 更偏向性能，Gemini 更偏向可读性）
   • 建议的取舍与行动清单

通过这种方式，可以在一次命令调用内获得多视角、高质量的评审意见，适合作为代码评审自动化的一部分。

8.2 前后端融合与接口设计

当接口改动同时涉及后端 API、数据模型和前端展示逻辑时，可以这样使用 CCG：

• 对 Codex 的提示词：聚焦接口稳定性、兼容性与后端数据流
• 对 Gemini 的提示词：聚焦错误信息可读性、表单交互友好性以及文档是否易于前端开发者理解

Claude 在合成时可以明确告诉你：

• 哪些改动对后端风险较大，需要增加回滚方案或灰度发布策略
• 哪些改动从用户体验和协作角度有明显提升，值得优先推进

8.3 方案选择与交叉验证

对于一个重要技术决策，例如“是否切换 ORM 框架”或“是否引入新的缓存层”，可以使用 CCG 做一次交叉验证：

• Codex 偏向分析实现复杂度、性能与迁移风险
• Gemini 偏向分析团队学习成本、文档生态与错误诊断体验

最终由 Claude 形成决策建议，包括推荐方向、风险列表、试点策略和监控指标等。

8.4 何时不该用 CCG

尽管 CCG 很强大，但在以下情况下，互操作模式或其他方案更适合：

• 需要长时间、多轮的交互式协作，例如持续重构一个复杂代码库
• 需要频繁在两个模型之间来回“传球”，而不是一次性获取意见
• 需要在会话中维护大量共享状态与中间产物

此类场景更适合持久 tmux + 共享状态的互操作模式，将 CCG 视为补充而非替代。

---

九、设计启示与落地建议

从 CCG 的设计中，可以总结出几条对通用 AI 工程系统有价值的经验：

• 明确的三阶段协议：分解、分发、合成，让多模型协作变得可测试、可扩展。
• 统一 CLI 抽象层：把提供商差异集中到一个脚本处理，降低调用方心智负担。
• 产物优先：优先依赖结构化文件而非 stdout，为审计、CI、二次分析提供基础。
• 安全与隔离优先：通过策略门控与环境变量剥离，保障会话独立与合规性。
• 降级策略内建：把“异常情况”当作常态来设计，使得系统在不完美环境中依旧可用。

对有意构建多模型协作系统的团队来说，可以借鉴的落地方向包括：

• 在自家工具链中实现类似的 omc ask 抽象，把不同 LLM 的调用统一封装
• 采用产物化设计，用 Markdown 或 JSON 存储所有模型输出
• 设计一套轻量级合成协议，在多模型意见中明确“谁说了什么、为什么这么说、要怎么做”

通过这类实践，可以在保持系统复杂度可控的前提下，真正发挥多模型协作的威力。