AI实践 - 插件之Codex委派任务给Claude篇

Codex 可以指派任务给Claude吗？

答案是肯定的

应用背景

对于codex plus用户自从模型升级到5.6后，token的消费量激增，特别是sol模型token消耗速度肉眼可见！每天高频查看剩余额度，精打细算，焦虑不已。现在gpt低价区又不多很多地区还是有使用门槛，又舍不得再开一个会员，那有没有可以高效节约gpt token的方法呢？当然有！deepseek 价格便宜又可以按量计费，当之无愧是国内coding之光。目前deepseek-v4-pro 最新版能力大幅提升，还是值得一用的！

整体思路

flowchart LR A[Codex] -->|派发任务| B[Claude Code CLI] B -->|执行任务<br/>DeepSeek 模型| C[执行结果] C -->|返回执行结果| A A -->|最终验证| D[验证结果]

设计方案

文档信息

  • 插件：claude-cli-delegate
  • 对应版本：0.1.1
  • 状态：已实现
  • 更新日期：2026-08-14

1. 背景与目标

Codex 擅长理解用户意图、读取图片、检查代码差异和完成最终验收；本地 Claude CLI 则可以作为独立的编码工作单元，使用 DeepSeek、Kimi 或其他 Anthropic 兼容模型执行具体任务。

本插件要解决的核心问题不是简单启动一个 CLI，而是建立一条可配置、可约束、可复核的委派链路：

  1. 每个项目可以独立决定是否允许 Claude 参与。
  2. 厂商、模型、工具、编辑权限、超时和预算都可以配置。
  3. API 密钥不写入仓库，只从宿主环境读取。
  4. Claude 无法识别图片时，由 Codex 提供经过确认的文字上下文。
  5. Claude 只是执行者，Codex 始终保留差异审查和最终验收责任。
  6. 插件可以通过个人 Marketplace 安装、升级和迁移。

2. 非目标

当前版本不试图实现：

  • 用 Claude 替换 Codex 的主任务决策权；
  • 将图片二进制直接发送给不支持视觉输入的后端模型；
  • 在同一工作区提供并发委派锁；
  • 提供运行中任务的手动取消工具；
  • 失败后自动回滚 Claude 已产生的修改；
  • 自动重试、跨厂商回退或自动选择最便宜的模型；
  • 对任意子进程输出提供完整的敏感信息检测与脱敏。

这些能力可以后续演进，但不能被视为当前安全边界的一部分。

3. 总体架构

插件采用 Hook、Skill、MCP 三层结构，各层只承担一种主要职责。

flowchart LR U["用户任务"] --> H["UserPromptSubmit Hook"] H --> C["读取项目策略"] C -->|"禁用或本轮排除"| X["Codex 自行处理"] C -->|"允许委派"| S["delegate-to-claude-cli Skill"] S --> M["claude_cli_delegate MCP"] M --> P["解析项目配置与机器厂商配置"] P --> E["构造受限子进程环境"] E --> CLI["Claude CLI"] CLI --> API["DeepSeek / Kimi / 自定义厂商"] CLI --> R["结构化执行结果与 Git 状态"] R --> V["Codex 检查真实 diff 并验证"] V --> U

3.1 Hook：任务入口与策略注入

UserPromptSubmit Hook 在每次用户提交任务时读取项目根目录的 .codex/claude-delegate.json。

它负责：

  • 识别开启、关闭和状态查询命令；
  • 在 explicit 模式下判断用户是否明确要求 Claude；
  • 在 auto 模式下允许 Codex自行决定是否委派；
  • 识别“本次不要使用 Claude”等单次排除表达；
  • 将本轮厂商、模型和编辑权限作为附加上下文注入 Codex；
  • 配置缺失、禁用或损坏时阻止绕过项目策略。

Hook 不直接运行 Claude，因此不会把自然语言识别、进程生命周期和代码验收混在同一个脚本中。

开启和关闭属于持久化控制操作：Hook 会创建或更新 .codex/claude-delegate.json 的 enabled 字段，并保留已有的厂商、模型、输出权限和超时设置。状态查询只读取配置。这里的“回写”与单次任务覆盖不同，后者永远不会修改配置文件。

3.2 Skill：委派工作流

delegate-to-claude-cli Skill 规定 Codex 应如何使用 MCP：

  1. 必要时查询当前委派状态。
  2. 先理解仓库和任务，再构造一个有边界的 Claude 子任务。
  3. 将相关源码背景、约束和验收条件传给 Claude。
  4. 图片由 Codex 识别后转换为 imageContext。
  5. Claude 返回后检查真实 Git diff，而不是采信其自述。
  6. 运行与改动风险相称的验证，并说明尚未覆盖的运行环境。

Skill 是行为规范，不持有密钥，也不直接管理子进程。

3.3 MCP：确定性执行层

本地 stdio MCP 暴露两个工具：

工具 作用 副作用
claude_get_status 返回项目开关、模式、厂商、模型、权限及密钥是否已配置 只读，不返回密钥值
claude_delegate_task 根据有效策略运行一次 Claude CLI 任务 可能修改项目文件

MCP 负责配置校验、厂商路由、Claude CLI 定位、进程环境构造、超时控制、输出解析和 Git 状态采集。它不负责最终代码验收。

4. 配置模型

4.1 项目级配置

配置文件位于 Git 根目录：.codex/claude-delegate.json。

{
  "schemaVersion": 1,
  "enabled": true,
  "delegationMode": "explicit",
  "provider": "deepseek",
  "model": "deepseek-v4-flash",
  "allowEdits": true,
  "allowedTools": ["Read", "Glob", "Grep", "LS", "Edit", "Bash"],
  "timeoutSeconds": 300,
  "maxBudgetUsd": 2
}
字段 说明
schemaVersion 当前只接受 1，为后续配置迁移保留版本边界
enabled 项目总开关；缺失配置或值为 false 时拒绝委派
delegationMode explicit 仅响应明确委派；auto 允许 Codex 判断
provider 厂商名，大小写不敏感，并归一化空格、下划线和连字符
model 原样传给 Claude CLI 的 --model
allowEdits 项目授予的最大编辑权限
allowedTools Claude 可见且允许使用的工具规则
timeoutSeconds 单次任务的最大运行时间，范围为 1 至 1800 秒
maxBudgetUsd 可选，传给 Claude CLI 的单次预算上限

allowedTools 是显式允许规则列表，同时支持普通工具名和细粒度规则，例如 Bash(git diff *)。当前可配置的工具基类为 Read、Glob、Grep、LS、Edit、Write 和 Bash；默认配置不包含 Write，但项目可以在允许编辑时显式加入。规则必须符合 工具名 或 工具名(单层匹配表达式)，不接受未知工具、嵌套括号或换行。

4.2 单次任务覆盖

MCP 调用可以临时指定 provider、model、allowEdits 和 timeoutSeconds，但遵循以下规则：

  • provider 和 model 可以为本次任务覆盖项目默认值；
  • allowEdits 只能从允许编辑收紧为只读，不能从只读提升为可写；
  • timeoutSeconds 取任务请求值与项目上限中的较小值；
  • 单次覆盖不回写项目配置。

单次指定的厂商仍须是内置厂商或机器级 providers.json 中已定义的厂商；覆盖参数不能绕过厂商信任边界。

因此优先级不是简单的“任务覆盖一切”，而是：

单次任务选择 provider/model
> 项目默认 provider/model

项目权限上限
> 单次任务收紧后的有效权限

4.3 机器级厂商配置

自定义 Anthropic 兼容厂商只能在机器本地配置：

  • Windows：%LOCALAPPDATA%\Codex\plugins\claude-cli-delegate\providers.json
  • macOS/Linux：~/.codex/plugins/claude-cli-delegate/providers.json
  • 可通过 CLAUDE_DELEGATE_PROVIDER_CONFIG 指定其他位置
{
  "providers": {
    "company-gateway": {
      "baseUrl": "https://llm.example.com/anthropic",
      "apiKeyEnv": "COMPANY_LLM_API_KEY"
    }
  }
}

项目只能选择机器上已定义的厂商，不能在仓库内指定任意端点和环境变量名。这样可以防止不可信仓库把本机密钥重定向到攻击者控制的地址。

自定义端点必须使用 HTTPS，且不能覆盖内置厂商。

5. 厂商与模型路由

内置路由如下：

归一化厂商 可接受别名 API 密钥环境变量 Anthropic 兼容地址
deepseek DeepSeek、deep-seek DEEPSEEK_API_KEY https://api.deepseek.com/anthropic
kimi Kimi、moonshot KIMI_API_KEY https://api.kimi.com/coding

模型名不在插件中做二次映射。例如项目配置 deepseek-v4-flash，MCP 就将该字符串原样传给 claude --model。模型是否存在、是否支持工具调用和上下文长度，由相应厂商的兼容层决定。

6. 权限与密钥边界

6.1 项目策略是权限上限

  • 缺少配置或 enabled: false 时，MCP 拒绝执行。
  • allowEdits: false 时，Edit 和 Write 会被拒绝或从有效工具集中移除。
  • 单次调用不能增加项目未授予的编辑权限。
  • 工具规则既传给 Claude CLI 的可见工具集合，也传给允许工具参数。
  • Bash 是否宽泛取决于项目配置；需要更小权限时应使用细粒度规则。

执行时，插件从每条规则提取工具基类并传给 --tools，再把完整规则传给 --allowed-tools。例如 Bash(git diff *) 会让 Bash 工具可见，但允许范围仍由完整规则约束。allowedTools 不会自动补充未列出的工具。

allowEdits: true 对应 Claude CLI 的 acceptEdits permission mode；allowEdits: false 对应 dontAsk，同时强制移除 Edit 和 Write。只读边界主要由工具集合保证，permission mode 负责决定 Claude CLI 遇到操作时的交互策略。

6.2 密钥只进入选中的子进程路由

MCP 从厂商配置指定的环境变量读取密钥，然后为本次 Claude 子进程设置：

  • ANTHROPIC_API_KEY
  • ANTHROPIC_AUTH_TOKEN
  • ANTHROPIC_BASE_URL
  • ANTHROPIC_MODEL

构造子进程环境前，会先删除继承环境中的上述四个 ANTHROPIC_* 路由变量，再注入当前厂商值，避免 DeepSeek、Kimi 或其他厂商之间串用路由和密钥。

插件不会把密钥值写入项目配置、提示文本或结构化工具结果。需要注意：当前实现以父进程环境副本为基础，并非最小化环境沙箱；其他无关环境变量仍可能被子进程继承。

6.3 自定义厂商的信任边界

机器级 providers.json 属于本机管理员信任范围。项目配置无权修改它，也无权覆盖内置厂商。迁移到新电脑时，项目配置可以随 Git 迁移，但机器厂商配置和环境变量必须单独配置。

7. 图片上下文桥接

当 DeepSeek 等后端不能直接识别用户图片时，插件不尝试伪造多模态能力，而是采用文本桥接：

  1. Codex 使用自身视觉能力查看图片。
  2. Codex提取与任务直接相关的可见事实，例如位置、文字、颜色和目标元素。
  3. 通过 imageContext 传给 claude_delegate_task。
  4. MCP 在提示中明确说明该内容是 Codex 提供的权威视觉描述，Claude 并未直接看到原图。
  5. Claude 修改后，Codex 根据原图再次核对结果。

这种设计保留了责任来源，避免 Claude 将转述内容误称为直接视觉观察。

8. 执行流程与返回结果

MCP 使用以下关键参数启动 Claude CLI：

  • --bare
  • --print
  • --no-session-persistence
  • --output-format json
  • --model <有效模型>
  • --permission-mode acceptEdits 或 dontAsk
  • --tools <工具基类>
  • --allowed-tools <工具规则>
  • 可选 --max-budget-usd

maxBudgetUsd 是一次 Claude CLI 调用的预算上限，由 Claude CLI 自身执行和计量。插件不做跨任务累计，也不会自行估算第三方厂商价格；未配置时不传该参数。

Claude 可执行文件按以下顺序查找：

  1. CLAUDE_CLI_PATH
  2. Windows 下的 %USERPROFILE%\.local\bin\claude.exe
  3. 系统 PATH 中的 claude

执行结果包含：

  • success、exitCode、timedOut 和 durationMs；
  • 实际厂商、模型、权限、工具和超时；
  • Claude 的最终文本及有限元数据；
  • stderrTail，最多保留尾部 4000 个字符；
  • 执行前后的 git status --short；
  • 执行后的 git diff --stat。

这些字段用于帮助 Codex定位变化和失败，不构成验收结论。

典型返回结构如下，字段值仅为示意：

{
  "success": true,
  "provider": "deepseek",
  "model": "deepseek-v4-flash",
  "allowEdits": true,
  "allowedTools": ["Read", "Grep", "Edit", "Bash(git diff *)"],
  "timeoutSeconds": 300,
  "timedOut": false,
  "exitCode": 0,
  "durationMs": 84210,
  "response": "已完成修改并运行静态检查。",
  "stderrTail": "",
  "gitStatusBefore": " M pages/example/example.uvue",
  "gitStatusAfter": " M pages/example/example.uvue",
  "gitDiffStat": "pages/example/example.uvue | 4 ++--"
}

9. 失败处理

当前实现采用明确失败、保留现场的策略：

场景 当前行为
项目未配置或已关闭 返回错误，不启动 Claude
配置字段无效 返回具体字段错误，不尝试猜测或降级
厂商未配置 指出机器级厂商配置路径
API 密钥缺失 指出缺少的环境变量名，不输出密钥值
Claude CLI 未安装 提示安装或设置 CLAUDE_CLI_PATH
超时 终止子进程并标记 timedOut
Claude 非零退出 返回失败、退出码和 stderrTail
JSON 结果解析失败 保留原始 stdout 文本作为响应
Claude 部分修改后失败 保留工作区现场，交由 Codex 和用户审查，不自动回滚

当前没有自动重试或厂商回退，以避免重复计费、重复修改和掩盖真实失败原因。

10. 验收闭环

Claude 的最终回答只是一份工作报告。Codex 必须继续执行：

  1. 对比 MCP 返回的 Git 前后状态。
  2. 读取真实 git diff，检查具体代码而不是只看 diff stat。
  3. 确认没有覆盖用户原有的未提交修改。
  4. 根据风险运行语法检查、单元测试、构建或页面验证。
  5. 明确区分静态检查与 HBuilderX、真机、浏览器、WebGL、实时 API、部署等尚未执行的验证。
  6. 必要时修正 Claude 的小问题，再向用户报告最终结果。

这条闭环是插件设计的核心：委派执行不等于委派责任。

11. 安装、迁移与升级

插件作为完整 Codex Plugin 发布，包含：

  • .codex-plugin/plugin.json
  • hooks/hooks.json
  • skills/
  • .mcp.json
  • mcp/ 和 scripts/
  • 测试与使用文档

个人 Marketplace 元数据位于仓库的 .agents/plugins/marketplace.json。典型安装流程为：

codex plugin marketplace add bkvito/codex-personal-plugins
codex plugin add claude-cli-delegate@personal

安装或升级后需要：

  1. 新建 Codex 任务，使 Skill、MCP 和 Hook 按新版本重新加载。
  2. 在 /plugins 中确认插件已启用。
  3. 在 /hooks 中审核并信任 UserPromptSubmit Hook。
  4. 确认 Node.js、Claude CLI 和所选厂商密钥已配置。

跨电脑迁移时，可随仓库迁移 .codex/claude-delegate.json；API 密钥、CLAUDE_CLI_PATH 和机器级 providers.json 需要在目标电脑重新配置。

12. 测试策略

插件测试覆盖以下核心契约：

  • 厂商别名归一化和模型名保留；
  • 配置 schema 与工具规则校验；
  • allowEdits 不可越权提升；
  • 单次超时不可超过项目上限；
  • 状态查询不泄漏密钥值；
  • 关闭项目时不强制解析机器级厂商；
  • Hook 在 explicit 模式下只对明确请求注入委派上下文；
  • 单次“不要使用 Claude”可以排除委派；
  • MCP 初始化、工具枚举和插件配置可被 Codex 正确加载；
  • 真实 DeepSeek 只读冒烟调用不会改变工作区。

插件校验还应包括 Skill 校验、Plugin manifest 校验、JSON UTF-8 解析和 git diff --check。

13. 已知限制与后续方向

已知限制

  • 没有同一工作区的并发委派锁，多任务同时修改时仍需上层协调。
  • 没有独立的 cancel MCP 工具，只能依靠超时终止。
  • 超时终止主要面向 Claude 直接子进程，不承诺清理所有可能派生的进程树。
  • stderrTail 只做长度截断，没有通用秘密扫描与脱敏。
  • 子进程继承父进程的大部分环境变量，并非最小环境沙箱。
  • MCP 只记录执行前后的 Git 状态，没有为用户未提交内容创建独立快照或 stash；并发修改和同文件交叉编辑仍需 Codex 识别。
  • 厂商兼容性、模型工具调用能力和成本统计依赖第三方接口。
  • 图片只通过 Codex 文字描述传递，描述质量仍需 Codex 负责。
  • Hook 的自然语言匹配是有限规则，不是完整意图分类器。

可选演进

  • 增加任务 ID、并发锁和显式取消能力；
  • 增加敏感输出过滤和最小化子进程环境；
  • 增加厂商健康检查、受限重试与人工确认后的回退；
  • 增加审计记录，保存厂商、模型、耗时、成本和 diff 摘要，但不保存密钥或完整源码；
  • 增加 schemaVersion 迁移工具；
  • 为高风险文件、外部网络访问和破坏性 Bash 命令增加更细的项目策略。

14. 设计结论

claude-cli-delegate 的本质是一个受项目策略约束的外部编码执行器适配层。Plugin 解决安装和迁移，Hook 解决每轮任务是否允许进入委派流程，Skill 解决 Codex 如何正确使用能力，MCP 解决可验证的本地执行。

三层分工使厂商和模型可以动态切换，同时把密钥、权限和最终验收留在明确的边界内。最重要的原则始终是：Claude 可以完成具体工作，但 Codex 必须理解、检查并为最终结果负责。

posted @ 2026-08-14 14:10  南宫影  阅读(14)  评论(0)    收藏  举报