codex-offload

name	codex-offload
description	任务分流：Claude token 贵、Codex 用量便宜。接到"执行型"任务（批量改文件、翻译、长文/样板代码/测试生成、格式转换、数据清洗、生成图片、大输出侦查、联网调研）时，先读本 skill 判断能否外包给 codex exec，Claude 只负责拆解、写工单和验收；Claude 卡壳 2 次的难题也可丢给 Codex 换视角。用户说"用 codex"、"省 token"、"外包给 codex"或 /codex-offload 时也使用。以下任务不外包、由 Claude 照常亲自执行（不是禁令）：需要会话上下文或记忆的任务、架构决策、对外发送类操作、几分钟就能干完的小活。

Codex 分流（codex-offload）

分工原则

• Claude（贵，聪明）：理解需求、拆解任务、写工单、验收结果、处理失败。
• Codex（便宜，能干活）：执行规格明确、可验收的具体工作。

一句话判断标准：能写成一段"给外包工程师的自包含工单"，且验收成本远低于亲自做的成本，就外包。

判断清单

外包给 Codex 执行

任务类型	例子
批量机械操作	几十个文件批量重命名/改格式/加 header
翻译	长文翻译、多文件文档汉化/英化管线
长内容生成	规格明确的文档初稿、README、测试用例、样板代码
格式转换	HTML→Markdown、JSON→CSV、数据清洗
图片生成	插图/信息图走 Codex 内置 image_gen（对图内文字和数字的准确率高）
独立代码任务	边界清晰的单函数/单模块实现、明确 spec 的 bug 修复
大文件消化	读一堆长文件只要结论/摘要
大输出侦查命令	find/grep -r/翻长日志/依赖树等会刷爆上下文的探查，只回传蒸馏结论
联网调研	GitHub/网页资料搜集（--enable web_search），工单里要求只报告经核实的事实并附来源
领域 CLI 批量任务	两侧都装了同类 skill 的领域（如办公套件 CLI），规格明确的批量任务照常外包
卡壳换脑	Claude 自己试了 2 次没解决的 bug/难题，丢给 Codex 换个视角；工单写明已试方案和失败现象

不外包，由 Claude 亲自执行

注意：这一节是分工归属（谁来做），不是禁令。下列任务照常执行，只是不交给 Codex。

情形	原因
需要会话上下文/用户记忆的任务	Codex 无状态，补全上下文的成本比省下的还高
模糊需求、架构决策、方案权衡	需要判断力，正是 Claude token 贵的价值所在
小任务（预计几次工具调用内完成）	写工单 + 验收的开销 > 直接做
破坏性/对外操作（删数据、发消息、部署）	必须 Claude 亲自控制
Codex 连续失败 2 次的任务	别再耗了，接手自己做

混合任务拆开：比如"抓取网页→翻译→入库"，可以整体外包，也可以只外包其中几段；按上表逐段判断。

Skill 对齐：Claude Code 与 Codex 的 skill 格式通用。发现 Codex 缺某个 skill 时，ln -s ~/.claude/skills/<name> ~/.codex/skills/<name> 补齐后照常外包（symlink 可被识别），不要因为缺 skill 把任务留下；临时场景也可直接把操作知识内联进工单。

调用方式

基础模板（非交互，跑完返回）：

codex exec --skip-git-repo-check -C <工作目录> -s <沙箱级别> \
  -o /tmp/codex-last-msg.md \
  "<工单>" </dev/null 2>/dev/null

三个必躲的坑：

1. stdin 必须关闭：codex exec 总是读 stdin 并与位置参数拼接，stdin 未关闭会永久挂起（症状：零输出、零 CPU）。命令末尾必须 </dev/null；2>/dev/null 滤掉 stderr 上的思考噪音。
2. 沙箱默认断网：需要 shell 联网的任务必须加 -c sandbox_workspace_write.network_access=true，否则 curl 等全部失败；纯搜索用 --enable web_search 即可，不依赖 shell 联网。
3. 长工单走文件：超过一屏就写进文件用 stdin 传：codex exec ... - < /tmp/task.md（- 表示从 stdin 读工单，此时不加 </dev/null），避免引号转义地狱。

常用参数与运行方式：

• 沙箱级别：只读分析 read-only；改文件 workspace-write（只能写 -C 目录，另加目录用 --add-dir）。不用 danger-full-access。
• 结果取回：最终答复写入 -o 指定的文件，文本生成类任务从这里取。
• 默认后台：除非明显是一两分钟的小活，一律后台运行，Claude 同时干别的，完成后再验收。
• 并行：多个独立子任务可同时起多个 codex exec。
• 续对话：codex exec resume --last "<补充指令>" </dev/null 在上一会话追加要求，不用重写上下文。
• 模型档位：默认不加 -m；超机械的大批量任务可指定更便宜的快速档模型，并用 --config model_reasoning_effort 调低推理档位。

工单（prompt）编写要求

Codex 看不到 Claude 的对话上下文，工单必须自包含，且像下单而不是聊天（operator 风格）：

1. 块状结构：长工单用 <task>、<context>、<constraints>、<output_format> 组织，紧凑命令式。
2. 绝对路径：所有输入/输出文件写全路径。
3. 完整背景：相关背景写进工单，不引用"上面说的"。
4. 验收标准：写明"完成的定义"，方便它自查、也方便验收。
5. 输出契约：限定回传格式和篇幅（如"最多 30 行：结论 + 证据 + 建议"）——Claude 读回也花钱，要它蒸馏，不要它倾倒。
6. 真实性约束（调研类必写）：只报告经核实的事实并附来源/URL，明说"找不到就写找不到，不要凭记忆编造"。
7. 禁止事项：不许动哪些文件、不许联网等（如适用）。

验收（必做）

Codex 跑完后必须验收，但要便宜地验：

• 文件操作类：ls / wc -l / grep 抽查关键点，不要整文件读回来。
• 代码类：跑测试或类型检查，看退出码。
• 内容生成类：读开头 + 随机抽一段 + 检查结构完整性。
• 翻译/本地化类：用正则抽查目标语言字符残留（如英文文档 grep -P "[\x{4e00}-\x{9fff}]"）；工单里"代码块不翻译"要限定为"命令和语法不翻译"，注释、示意图、示例文字仍需翻译。
• 调研/信息类：抽查关键事实真伪（如用 GitHub API 核对 repo 是否存在、star 数是否属实）——编造是外包调研的头号风险。
• 验收不过：把具体问题写成补充指令，codex exec resume --last 修一次；再不过就 Claude 接手。

智能触发（可选增强）

本 skill 的 description 常驻上下文属于"软触发"。仓库另附一个 UserPromptSubmit hook（hooks/codex-offload-nudge.py）：本地零 token 关键词预判，用户消息命中可外包特征时才向模型注入分流提醒，未命中完全静默。安装方式见仓库 README。

备用执行器

Codex 额度用尽（报 quota/429 类错误）时，可换用其他无头 CLI 兜底（如 kimi -y -p "<工单>"、gemini -p "<工单>"），工单原样复用。