1. 两个工具同台时，最容易踩的坑是什么
Claude Code 和 Codex 放在同一个项目里用，很多人第一反应是"两个都开着，谁有空谁干活"。我一开始也这么想，结果第一周就翻车了：Codex 改完一个文件，Claude Code 紧接着又基于旧版本改了一遍，两边互相覆盖，最后 git diff 里一堆莫名其妙的回退。更隐蔽的问题是——"允许结束"和"可以提交"是两码事，而绝大多数人把前者当成了后者。
这个标题里的关键词其实点得很准：Stop hook、ALLOW、codex-plugin-cc。这几个词凑在一起，说的就是一套"让两个 agent 协同工作、并且在收尾阶段做二次校验"的机制。如果你只是把 Claude Code 和 Codex 当成两个独立的命令行工具轮流用，那确实不需要什么分工；但一旦你想让它们在一个仓库里接力干活，就必须回答三个问题：谁负责写、谁负责审、什么时候才算真正可以提交。
我写这篇东西的出发点很简单：网上关于 Claude Code 安装、Codex 安装、ccswitch配置、codex接入deepseek这类教程已经很多了，但几乎没人讲清楚"两个 agent 同时存在时，边界怎么划"。而边界划不清，轻则重复劳动，重则把好好的代码改烂。所以下面我会从整体设计思路讲起，再拆到 Stop hook 和 ALLOW 的具体实现，最后给一份可以直接抄的排查清单。
适合谁看：已经在用 Claude Code 或 Codex 中至少一个、准备把两个都接进日常工作流的开发者；对 hook 机制、agent 协作、提交前校验感兴趣的人；以及被"两个 AI 互相打架"折磨过的同行。小白也能看，我会把每个概念用生活化的方式讲一遍。
2. 整体设计思路：为什么不是"谁快谁上"
2.1 把两个 agent 当成两种角色，而不是两个工人
我踩过的最大的坑，就是一开始把 Claude Code 和 Codex 当成两个可以互换的"工人"。实际上它们的强项不一样，硬要它们做同一件事，只会互相干扰。
我的做法是给它们分配角色，而不是分配任务：
- Claude Code 当"主笔"：负责理解需求、跨文件改动、写新逻辑、跑测试。它的上下文管理比较适合长链条的推理，尤其是需要读多个文件才能决定怎么改的场景。
- Codex 当"审稿人"：负责在改动完成后做一遍独立复核，重点看边界条件、错误处理、有没有引入回归。它不需要知道全部上下文，只需要看 diff。
这个分工背后的逻辑是：写代码和审代码需要的心智模式不同。让同一个 agent 既写又审，它很容易陷入"我刚写的肯定没问题"的确认偏误。换一个 agent 来看，相当于强制换了个视角。
注意：这里说的"审"不是让 Codex 重写一遍，而是让它只输出意见，不改文件。一旦让它也动手改，两个 agent 就会开始互相覆盖。
2.2 为什么必须有一个"收尾闸门"
分工定好了，下一个问题是：什么时候算干完？
很多人默认"agent 说完成了就是完成了"。但 agent 的"完成"通常只意味着"我这一轮没有更多要做的了"，它不等于"代码可以提交"。这两者之间的差距，就是标题里说的——别把"允许结束"当成"可以提交"。
我举个真实例子。有一次 Claude Code 改完一个函数，跑了一遍测试全绿，然后它输出"任务完成"。我顺手就 commit 了。结果第二天 CI 挂了，原因是它改的那个函数被另一个模块以不同的参数调用，而那个调用点它没看到。测试之所以绿，是因为那个调用路径没有覆盖到。
如果当时有一个"收尾闸门"——在 agent 说完成之后、commit 之前，强制跑一遍额外的校验——这个问题当场就能发现。这个闸门，就是 Stop hook 要干的事。
2.3 Stop hook 和 ALLOW 在整条链路里的位置
把整条链路画出来大概是这样：
- 你给 Claude Code 一个任务
- Claude Code 改代码、跑测试
- Claude Code 认为做完了，准备"停止"
- Stop hook 触发——这是闸门
- hook 里调用 Codex 做独立复核
- Codex 返回结论：
ALLOW或DENY - 只有拿到
ALLOW，才允许进入 commit 流程
关键在第 6 步。ALLOW是一个明确的信号，意思是"我复核过了，可以放行"。没有这个信号，agent 的"我完成了"就只是一个请求结束的动作，而不是授权提交的动作。
这个区分听起来很绕，但用生活类比就清楚了：员工说"我做完了"（请求结束），和主管签字说"可以发布"（授权提交），是两件事。Stop hook 就是那个主管签字的环节。
2.4 codex-plugin-cc 扮演什么角色
codex-plugin-cc这个名字里的cc大概率指 Claude Code。它的作用是把 Codex 包装成一个可以被 Claude Code 的 hook 调用的插件——也就是说，让 Claude Code 在 Stop 阶段能"喊一声"Codex，把当前 diff 递过去，拿回一个结论。
没有这个插件，你就得自己写脚本去调 Codex 的接口，还要处理输出解析、超时、错误码。有了它，这部分胶水代码就省了。但要注意，插件只是通道，真正的判断逻辑（什么情况返回 ALLOW、什么情况返回 DENY）还是得你自己定。
3. 核心细节解析：Stop hook 到底怎么写才靠谱
3.1 Stop hook 的触发时机和输入
Stop hook 在 agent 准备结束当前回合时触发。它拿到的输入通常包括：当前工作目录、这一轮改动的文件列表、以及 agent 自己认为的"完成状态"。
这里有个容易忽略的点：hook 拿到的 diff 可能不完整。如果 agent 在多个回合里分批改文件，Stop hook 每次触发时看到的只是"到目前为止"的状态。所以我的做法是，在 hook 里先做一次git diff或git status，拿到真实的、完整的改动集，而不是信任 agent 传过来的列表。
# 在 hook 脚本开头先固化当前改动快照 git add -A git diff --cached --stat > /tmp/cc_stop_diff_stat.txt git diff --cached > /tmp/cc_stop_diff.patch为什么要git add -A再 diff？因为未跟踪的新文件不会出现在普通git diff里，而 agent 经常新建文件。用--cached能把这些都纳入进来。这一步做完，后面 Codex 复核的就是一份完整的、可复现的改动。
3.2 ALLOW 的判定标准要写死，不能靠感觉
ALLOW不能是"Codex 觉得还行"这种模糊判断。我建议把它拆成几个硬性条件，全部满足才返回 ALLOW：
| 条件 | 检查方式 | 不满足时的动作 |
|---|---|---|
| 改动文件数在预期范围内 | 对比 diff stat 和任务描述 | 返回 DENY，提示范围异常 |
| 没有删除关键文件 | 检查 diff 中的删除操作 | 返回 DENY，人工确认 |
| 测试全部通过 | 跑项目测试命令 | 返回 DENY，附失败用例 |
| 没有引入新的 TODO/FIXME | grep diff 内容 | 返回 DENY 或警告 |
| Codex 复核无高危意见 | 解析 Codex 输出 | 返回 DENY，附意见 |
这张表是我实际用下来比较稳的一套。你可以按项目情况增删，但核心思路是：ALLOW 必须由一组可验证的条件共同决定，而不是单一信号。
提示：条件不要设太多，超过 6 条之后维护成本会陡增，而且容易因为某条误报导致整个流程卡死。我一般控制在 4 到 5 条。
3.3 把 Codex 的复核结果结构化
Codex 返回的是自然语言，直接拿来做判断很容易出错。我的做法是在 prompt 里强制它输出一个固定格式，比如最后一行必须是VERDICT: ALLOW或VERDICT: DENY，然后 hook 脚本只解析这一行。
import re def parse_verdict(codex_output: str) -> str: match = re.search(r"VERDICT:\s*(ALLOW|DENY)", codex_output) if not match: # 解析不到就当作 DENY，宁可拦下也不要放过 return "DENY" return match.group(1)这里有个经验：解析失败一律按 DENY 处理。我见过有人图省事，解析不到就默认放行，结果 Codex 因为超时没输出完整内容，改动就这么溜过去了。宁可多拦几次，也不要漏放一次。
3.4 超时和失败的处理策略
Codex 调用可能超时、可能报错、可能返回空。这些情况怎么处理，直接决定了这套机制是"帮手"还是"绊脚石"。
我的策略分三档：
- 超时（比如 60 秒没返回）：返回 DENY，但在提示里说明是超时，让人工决定是否重试。
- 报错（网络、鉴权等）：返回 DENY，并记录错误日志。不要自动重试超过一次，否则容易卡住整个流程。
- 返回空或格式不对：返回 DENY，把原始输出打到日志里方便排查。
有人会问，这样岂不是经常被拦？确实会。但被拦的成本是"多看一眼"，漏放的成本是"线上出问题"。这笔账怎么算都划算。
4. 实操过程：从零搭一套可用的协作流程
4.1 环境准备和基础配置
先把两个工具都装好、能各自跑通，再谈协作。这一步别跳。
Claude Code 的安装按官方文档走就行，Windows、macOS、Ubuntu 都有对应方式。装完之后确认claude命令能在终端里跑起来。Codex 同理，装完确认codex命令可用。
如果你要用ccswitch之类的工具做多环境切换，建议先把单个环境跑通再上切换器。我见过不少人一上来就配切换，结果两个环境互相污染，排查半天发现是配置串了。
注意：涉及本地模型接入（比如
claude code 调用 lmstudio 的本地模型）时，先单独验证模型能正常响应，再接入协作流程。模型本身不稳定的话，后面所有判断都不可信。
4.2 配置 Stop hook 的完整步骤
第一步，找到 Claude Code 的 hook 配置位置。通常在项目根目录或用户配置目录下的配置文件里。不同版本位置可能不同，以你本地实际为准。
第二步，注册 Stop hook，指向你的脚本：
{ "hooks": { "Stop": [ { "command": "bash /path/to/your/stop_hook.sh", "timeout": 120 } ] } }timeout给足，因为里面要调 Codex，60 秒往往不够。
第三步，写 hook 脚本。核心逻辑就是前面说的：固化 diff、调 Codex、解析 VERDICT、决定放行还是拦截。
#!/bin/bash set -e # 1. 固化改动 git add -A git diff --cached > /tmp/cc_stop_diff.patch # 2. 调 Codex 复核 codex review --input /tmp/cc_stop_diff.patch > /tmp/codex_verdict.txt 2>&1 || true # 3. 解析结论 VERDICT=$(grep -oE "VERDICT: (ALLOW|DENY)" /tmp/codex_verdict.txt | tail -1 | awk '{print $2}') if [ "$VERDICT" != "ALLOW" ]; then echo "Stop hook 拦截：未获得 ALLOW，禁止提交" echo "Codex 输出：" cat /tmp/codex_verdict.txt exit 1 fi echo "Stop hook 放行：获得 ALLOW" exit 0第四步，测试。故意改一个有明显问题的文件，看 hook 是否拦截；再改一个正常的，看是否放行。这一步一定要做，不然你不知道 hook 到底有没有生效。
4.3 让 Codex 复核更准的 prompt 设计
Codex 复核的质量，八成取决于你怎么问它。我试过很多版本，最后稳定下来的 prompt 结构是这样的：
- 先说明角色："你是一个独立的代码复核者，只输出意见，不修改文件。"
- 再给上下文："以下是本次改动的完整 diff。"
- 明确检查项："重点检查边界条件、错误处理、是否有回归风险。"
- 强制输出格式："最后一行必须是 VERDICT: ALLOW 或 VERDICT: DENY。"
关键是最后一条。没有强制格式，Codex 会给你一大段分析，你还得自己判断它到底同不同意。有了固定格式，脚本才能可靠解析。
4.4 参数选择：超时、重试、日志
几个我调过的参数，供参考：
| 参数 | 我的取值 | 理由 |
|---|---|---|
| hook 超时 | 120 秒 | 给 Codex 留足推理时间 |
| Codex 调用超时 | 90 秒 | 超过基本是卡住了 |
| 自动重试次数 | 1 次 | 再多容易拖垮流程 |
| 日志保留 | 最近 20 次 | 方便回溯，又不占空间 |
这些不是标准答案，你得按自己项目的规模和 Codex 的响应速度调。小项目可以更激进，大项目建议更保守。
5. 常见问题与排查技巧实录
5.1 两个 agent 互相覆盖怎么办
这是最高频的问题。表现是：Claude Code 改完，Codex 又改回去，或者反过来。
根因通常是两个 agent 都能写文件。解决办法很简单：只让一个 agent 有写权限。在我的流程里，Codex 只读 diff、只输出意见，绝不碰文件。如果你用的是codex-plugin-cc，检查它的配置里有没有把写权限关掉。
如果已经发生了覆盖，用git reflog找回之前的版本，别慌。
5.2 Stop hook 不触发或触发多次
不触发的原因可能是配置路径不对、脚本没有执行权限、或者 hook 名称写错。先手动跑一遍脚本，确认脚本本身没问题，再查配置。
触发多次通常是因为 agent 在多个回合里反复"准备结束"。我的处理方式是在脚本里加一个锁文件，同一轮改动只复核一次：
LOCK=/tmp/cc_stop_hook.lock if [ -f "$LOCK" ]; then exit 0 fi touch "$LOCK" trap "rm -f $LOCK" EXIT5.3 Codex 返回格式不稳定
有时候 Codex 会把VERDICT: ALLOW写成Verdict: allow或者加一堆前后缀。我的做法是在解析时做大小写归一化，并且用正则宽松匹配：
match = re.search(r"verdict\s*:\s*(allow|deny)", output, re.IGNORECASE)还是解析不到，就按 DENY 处理。别为了"让它通过"去放宽解析规则，那等于自己拆掉闸门。
5.4 常见问题速查表
| 现象 | 可能原因 | 排查动作 |
|---|---|---|
| hook 完全不执行 | 配置路径错/无执行权限 | 手动跑脚本，检查配置 |
| 一直返回 DENY | Codex 超时或格式不对 | 看日志，确认 Codex 输出 |
| 改动被覆盖 | 两个 agent 都有写权限 | 关掉 Codex 的写权限 |
| 提交被拦但看不出原因 | 日志没保留 | 打开日志，看 Codex 原始输出 |
| 流程卡死 | 重试次数过多 | 限制重试为 1 次 |
5.5 几条踩坑心得
第一，别在 hook 里做太重的操作。我一开始在 hook 里跑了完整测试套件，结果每次 Stop 都要等好几分钟，体验极差。后来改成只跑和改动相关的测试，快了很多。
第二，ALLOW 的日志一定要留。出了问题时，你需要知道当时 Codex 到底说了什么。没有日志，等于没有证据。
第三，定期回顾被拦的记录。如果某个条件总是误报，说明它设得不合理，该调就调。闸门是为了拦真问题，不是为了刷存在感。
第四，别把 hook 当成万能保险。它只能拦住它能检查到的问题。真正的质量还是靠测试覆盖和代码评审。hook 是最后一道网，不是唯一一道。
6. 这套机制还能怎么扩展
跑顺之后，我做了几个小扩展，效果不错。
一个是把 Codex 的复核意见自动贴到 commit message 的草稿里，这样提交时能一眼看到复核结论，省得再去翻日志。另一个是给 DENY 的情况加一个快捷重试命令，人工确认没问题后一键放行，不用重新走一遍流程。
还有一个方向是按改动类型分级。比如只改文档的 diff，可以跳过 Codex 复核直接放行；改核心逻辑的，则强制复核。这样能省下不少时间，又不牺牲关键路径的安全性。
我个人在实际操作中的体会是：这套东西的价值不在于"多智能"，而在于把"我觉得可以了"变成"有据可查地可以了"。agent 再强，也需要一个明确的收尾信号。Stop hook 加 ALLOW，就是给这个信号一个落地的位置。你要是也在两个 agent 之间来回折腾，不妨先把这道闸门搭起来，很多混乱会自己消失。
