我把 Codex 和 Claude Code 拆开看：Agent 到底是怎么干活的？

公众号封面：拆开看 Codex 和 Claude Code

最近我同时在用 Codex 和 Claude Code 做真实项目，越用越觉得：它们表面上都叫 Coding Agent，但其实不是同一种工具。

很多人会问：

Codex 和 Claude Code，到底谁更强？

这个问题当然可以聊，但我觉得更有意思的问题是：

它们到底是怎么干活的？为什么用起来体感不一样？

如果只记一个结论，我会这么说：

Codex 更像一个透明的本地 Agent Runtime：会话、工具、沙箱、patch、安全检查，都能在公开源码里顺着看下去。
Claude Code 更像一个产品化很完整的终端同事：记忆、权限模式、hooks、subagents、SDK 控制面，都围绕长期协作在打磨。

所以这篇不做“谁吊打谁”的评测。我想把它们拆开看一遍，再给两个真实场景：怎么用 Codex 学 React 源码，以及怎么让 Codex 做计划、再调用 Claude Code 去实现。

Agent 不是模型，是闭环

很多人以为 Agent 的核心是“大模型会调用工具”。

这句话没错，但只说了一半。

模型只是决定“下一步想做什么”。真正把事情落到项目里的，是模型外面那套运行时：工具怎么注册，命令怎么执行，权限怎么拦，文件怎么改，历史怎么压缩，最后怎么验收。

Codex 和 Claude Code 的 Agent 实现差异结构图

一个 Coding Agent 能不能在真实项目里干活，关键不只是模型聪不聪明，而是这个闭环稳不稳：

text

读上下文 -> 想下一步 -> 调工具 -> 拿结果 -> 更新历史 -> 验证 -> 继续

这也是 Codex 和 Claude Code 差异最大的地方。

Agent Runtime Loop 概念配图

资料边界先说清楚

Codex CLI 的核心实现是公开源码。我本地参考的是 OpenAI Codex 仓库 2026-04-27 的提交：b985768dc11446c60e092af510b75e5e8863e514。

Claude Code 不一样。Anthropic 官方仓库公开了 README、插件、命令、示例和 npm wrapper，但核心 CLI 以内置原生 binary 分发，并没有完整公开内核源码。所以对 Claude Code 的分析，主要来自官方文档、npm 包结构、Claude Agent SDK 类型定义，以及官方仓库公开内容。

换句话说：

Codex：可以做源码级分析。
Claude Code：更适合做公开接口、产品架构和使用方式分析。

这个差异本身，就已经很说明两者气质了。

Codex：把 Runtime 摊开给你看

Codex 的公开源码里，最值得看的不是外层 npm 包，而是 codex-rs/core。

它的主循环大概是这样：

text

Session
  |
  +-- run_turn()
        |
        +-- 读取项目说明 / 插件 / skills / MCP
        +-- 构造 prompt 和工具列表
        +-- 请求模型
        +-- 模型返回工具调用
        |       |
        |       +-- ToolRouter 解析调用
        |       +-- ToolRegistry 找 handler
        |       +-- ToolOrchestrator 做权限、沙箱、重试
        |       +-- 工具结果写回 history
        |       +-- 继续下一轮
        |
        +-- 模型返回最终回答
                |
                +-- stop hook
                +-- 输出总结

源码里能看到对应位置：

session/turn.rs：本轮 Agent loop。
tools/router.rs：把模型输出解析成内部工具调用。
tools/registry.rs：注册工具 handler。
tools/orchestrator.rs：处理 approval、sandbox、retry。
apply_patch.rs 和 safety.rs：处理文件修改和安全检查。
agents_md.rs：读取项目说明。
compact.rs：长上下文压缩。
agent/control.rs：子 Agent 管理。

我最喜欢 Codex 的一点是：工具不是简单执行，而是先被治理。

比如模型想跑一个 shell 命令，Codex 不会直接 spawn。它要先判断：这个命令是否会修改环境，当前权限是否允许，要不要用户确认，应该在哪个 sandbox 里跑，失败后能不能申请升级重试。

所以你用 Codex 时，会感觉它比较“工程师”。

它会读项目约定，倾向于小步 patch，改完跑测试，最后汇报 diff 和验证结果。它不像一个随口发挥的聊天机器人，更像一个有边界、有流程的本地执行器。

这种克制不是性格，是实现带来的。

Claude Code：把协作体验做厚

Claude Code 的核心内核不是完整开源，所以不能像 Codex 那样逐行追 run_turn。

但从 CLI、文档和 Agent SDK 看，它的重点很明显：它在把 Agent 做成一个长期可用的终端产品。

Claude Agent SDK 的 query({ prompt, options }) 返回的不是一个最终字符串，而是一个流式 Query。也就是说，宿主可以持续接收 system init、assistant message、tool use、tool result、hook event、final result。

它暴露出来的控制面也很完整：

text

tools               控制可用内置工具
allowedTools        自动允许哪些工具
disallowedTools     禁止哪些工具
canUseTool          每次工具调用前由宿主决策
permissionMode      default / plan / acceptEdits / dontAsk / auto / bypassPermissions
hooks               PreToolUse / PostToolUse / Stop / Compact / ConfigChange...
mcpServers          接入外部工具
agents              程序化定义子 Agent
sessionStore        会话持久化到外部存储
settingSources      控制 user/project/local 配置来源
systemPrompt        控制系统提示词

这里的重点不是“内部怎么 dispatch 工具”，而是“作为一个产品，它允许你怎么接管 Agent”。

Claude Code 的记忆体系也更外显。它以 CLAUDE.md 为入口，配合 settings、skills、hooks、subagents。你还可以用 @ import 其他 Markdown 文件。

如果你的仓库已经有 Codex 用的 AGENTS.md，可以写一个 CLAUDE.md：

@AGENTS.md

## Claude Code

- 大重构前先进入 plan mode。
- 大范围排查时优先使用 subagents。
- 长会话中定期查看 /context，并在阶段切换时 /compact。

这样 Codex 和 Claude Code 就能共享同一套项目约定，而不是各读各的规则。

体感差异从哪来

如果压缩成一句话：

Codex 更像“把 Agent Runtime 开源给工程师看”；Claude Code 更像“把 Agent 产品打磨给工程师用”。

更具体一点：

维度	Codex	Claude Code
核心可见性	核心 Rust 源码公开	核心 CLI binary 未完整开源
项目说明	`AGENTS.md`	`CLAUDE.md`，可 import `AGENTS.md`
工具执行	Router + Registry + Orchestrator	SDK 暴露工具、权限、hook 控制面
文件修改	patch + safety check 味道很重	Read/Edit/Write + permission mode + checkpoint
权限模型	approval、sandbox、retry 在源码里很清晰	`default`、`plan`、`acceptEdits`、`dontAsk`、`auto` 等模式更产品化
长上下文	compact 作为 history replacement	`/context`、`/compact`、memory、session 管理更外显
子 Agent	更像受控线程树	更像上下文隔离的角色化同事

所以同样一句任务，两者给人的感觉不一样。

你让 Codex 修一个测试失败，它通常会走：

text

读约定 -> 找测试 -> 定位代码 -> patch -> 跑验证 -> 总结

你让 Claude Code 做一个复杂需求，它更容易走：

text

读记忆 -> 进入计划 -> 调子 Agent 分析 -> 汇总方案 -> 执行 -> 继续协作

不是谁更高级，而是默认姿势不同。

一个先把执行链路管好，一个先把协作体验做顺。

怎么用才高效

Codex 最怕你给它一句虚的：

帮我优化一下登录模块。

这句话太宽了。它能答，但不一定能干得漂亮。

更好的方式是把任务写成工程合同：

text

修复 src/auth/session.ts 的 token refresh 重复请求问题。
不改变公开 API。
先读相关测试和调用方，改动保持最小。
完成后运行 pnpm test auth。
最后说明改了什么、验证了什么、还有什么风险。

如果项目长期使用 Codex，AGENTS.md 要写得像能执行的规则，而不是口号。

## Build and test

- Frontend changes: run pnpm lint and pnpm test.
- API changes: run pnpm test:api.

## Editing rules

- Do not rewrite unrelated files.
- Keep public API changes documented.
- Final response must include changed files and verification result.

Claude Code 则值得你认真维护 CLAUDE.md，尤其是长期项目。常用节奏可以是：

想方案：plan
小改动：acceptEdits
敏感任务：default
脚本化调用：dontAsk + 明确 allow rules
临时容器或隔离环境：再考虑 bypassPermissions

别一上来就追求“全自动”。Agent 真正的效率不是永远不问你，而是在正确边界内少问你。

场景一：用 Codex 学 React 源码

讲工具如果只停在“能读代码、能改代码”，其实没什么意思。

真实场景里，我觉得 Codex 特别适合做一件事：带着你读大型源码库。

比如你想学 React 源码，最容易踩的坑是第一句就问：

帮我学习 React 源码。

这句话太大了。Codex 会努力回答，但很容易变成一篇“React 架构综述”。读完感觉懂了，第二天打开源码还是不知道从哪下手。

更好的方式，是把 Codex 当成源码阅读搭子，而不是百科全书。

第一步，先让它画地图。

text

我想用 Codex 学 React 源码。请只阅读，不修改 React 仓库源码。
先读 README、package.json、scripts、packages/ 目录结构。
帮我整理一份学习路线：ReactElement、Hooks、Reconciler、Scheduler、ReactDOM 分别从哪些文件开始读。
输出成 Markdown 笔记，包含关键文件、建议阅读顺序、每一段源码要回答的问题。

这一步不要追求“讲透 React”。你只需要它把仓库入口、包结构、关键文件先摊开。

第二步，只追一条链路。

比如先追 useState：

text

这次只追踪 useState。
请从公开 API 入口开始，沿着 dispatcher、mountState/updateState、dispatchSetState、scheduleUpdateOnFiber 读代码。
不要泛泛解释，给我四样东西：
1. 关键文件
2. 关键函数
3. 调用链
4. 我应该在哪些位置打断点

这个颗粒度刚好。Codex 可以边读源码边校正判断，你也不会被一整套架构淹没。

第三步，用测试反推行为。

React 这种项目，直接读实现很容易晕。更稳的读法是先读测试：

text

请用 rg 找到 React 源码里和 Scheduler 优先级相关的测试。
先从测试理解行为，再反推实现。
最后按“行为 -> 测试文件 -> 实现文件 -> 我还有哪些问题”的格式整理。
只写学习笔记，不修改源码。

第四步，把笔记沉淀下来。

text

请把这次 React 源码阅读结果写到 04-knowledge/notes/react-source/use-state.md。
保留关键调用链和我下一次应该继续追的问题。
不要修改 React 仓库源码。

这样你不是“和 AI 聊过一次 React”，而是在建立自己的源码索引。下一次继续读 reconciler、scheduler、commit phase，Codex 可以沿着这些笔记继续，而不是每次重开一局。

这个场景里，Codex 的价值很明确：

它能真的进入本地源码库，而不是凭记忆讲 React。
它擅长用搜索和测试把解释落到文件、函数、调用链上。
它可以把学习过程沉淀成 Markdown，变成你的长期知识库。

我现在用 Codex 学大型项目时，基本不会问“这个项目怎么实现的”。我会问：

这次只追一条链路。请读代码、找测试、画调用链、留下问题。

场景二：Codex 做计划，Claude Code 去实现

这个玩法更有意思。

有些任务我不想直接让一个 Agent 从头干到尾。因为计划和实现其实是两种工作。

计划阶段需要克制：读上下文、拆边界、判断风险、定验收标准。

实现阶段需要推进：改文件、跑测试、处理细节、把活做完。

所以可以让 Codex 负责前后两头，让 Claude Code 负责中间执行。

流程像这样：

text

你
  |
  v
Codex：读上下文，拆任务，写 implementation brief
  |
  v
.agent/tasks/xxx.md
  |
  v
Codex 调用 claude -p，把 brief 交给 Claude Code
  |
  v
Claude Code：按边界实现，输出修改说明和验证结果
  |
  v
Codex：读 git diff，复跑测试，做最终验收

这里没有神秘集成。本质上是：Codex 可以执行本地 shell，而 Claude Code 提供了非交互模式 claude -p。于是 Codex 可以像调用测试命令一样调用 Claude Code。

使用前提也要说清楚：本机需要已经安装并登录 Claude Code CLI，当前仓库是你信任的目录，并且任务最好在独立分支或 worktree 里跑。

第一步，让 Codex 先写任务 brief。

text

请先不要改代码。
阅读当前仓库约定、相关实现和测试后，为“修复登录 token refresh 重复请求”写一份 implementation brief。

brief 保存到 .agent/tasks/login-refresh.md，必须包含：
1. 目标
2. 允许修改的文件范围
3. 明确不做什么
4. 建议实现步骤
5. 验证命令
6. Claude Code 完成后必须返回的报告格式

这个 brief 不是漂亮文档，而是给下一个 Agent 的任务协议。

建议写得越具体越好：

# Task: Fix duplicate token refresh

## Goal

Prevent concurrent token refresh requests from creating duplicate network calls.

## Allowed files

- src/auth/session.ts
- src/auth/session.test.ts

## Out of scope

- Do not change public auth API.
- Do not rewrite login flow.
- Do not touch unrelated files.

## Verification

- pnpm test auth
- pnpm lint

## Final report format

- Changed files
- What changed
- Verification result
- Remaining risk

第二步，让 Codex 调 Claude Code 实现。

bash

claude -p \
  --permission-mode acceptEdits \
  --allowedTools "Read,Edit,MultiEdit,Bash(pnpm test *),Bash(pnpm lint),Bash(git diff *)" \
  "$(cat .agent/tasks/login-refresh.md)"

这里有三个关键点：

-p 是非交互模式，Claude Code 会执行任务并把结果打印出来。
--permission-mode acceptEdits 允许编辑文件，但不是无限制执行所有东西。
--allowedTools 用来收窄工具边界。可以允许读文件、编辑文件、跑指定测试、看 git diff，但不要随手给它所有 Bash 权限。

如果你想让 Codex 更容易解析 Claude Code 的返回，也可以加：

bash

--output-format json

第三步，让 Codex 回来验收。

text

Claude Code 已经执行完。
请你现在读取 git diff，检查是否遵守 brief 的文件范围。
然后运行 brief 里的验证命令。
最后给我一份验收结论：通过、需要返工，还是需要我人工决策。

这一步是整个流程里最值钱的地方。

因为 Codex 不是盲目信任 Claude Code 的总结，而是重新站在 reviewer 的位置看 diff、跑测试、判断风险。

这个玩法要高效，关键有五个：

任务 brief 要小，不要一次扔一个大重构。
写清楚允许修改的文件，避免 Agent 顺手多改。
命令权限要窄，日常任务优先 acceptEdits，不要随便 bypassPermissions。
最好开独立分支或 worktree。
Codex 必须做最终验收。

这个组合的重点不是“多叫一个 Agent 显得高级”，而是让两个 Agent 各自做擅长的事：

Codex：拆任务、定边界、调用工具、验收结果。
Claude Code：在清晰 brief 里持续实现。

这样用起来才会真的顺。

把仓库变成协作中心

如果同时用 Codex 和 Claude Code，我建议把仓库本身变成 Agent 协作的中心。

text

AGENTS.md              给 Codex 和其他 Agent 的通用规则
CLAUDE.md              Claude Code 入口，import AGENTS.md
.agent/tasks/          单次任务 brief
.claude/agents/        Claude Code 子 Agent 定义
99-agent/handoff.md    跨工具、跨设备、跨会话交接

handoff.md 可以固定成这样：

# Agent Handoff

## Current goal

## Completed

## Changed files

## Verification

## Next step

这比每次在聊天框里重新解释项目背景强太多。更重要的是，它让 Agent 的上下文不只存在聊天记录里，而是沉淀在仓库里。

最后

如果只看表面，Codex 和 Claude Code 都是“能读代码、能改文件、能跑命令”的 Coding Agent。

但往实现里看，差异很明显。

Codex 把 Agent Runtime 里的工程骨架摊开了：session、turn、tool、sandbox、patch、compact、subagent 都能在源码里找到位置。

Claude Code 把 Agent 产品里的协作体验做厚了：memory、permission mode、hooks、subagents、settings、SDK、session store 都围绕长期使用展开。

所以选哪个，别只问“哪个更聪明”。

更应该问：

我现在需要的是一个透明、克制、可验证的本地工程执行器，还是一个有记忆、会分工、产品化更强的终端同事？

当然，还有第三个答案：

我可以让 Codex 负责想清楚和验收，让 Claude Code 负责在中间把活干完。

这可能才是最有意思的地方。

Agent 不一定非要单打独斗。真正高效的用法，是让它们在同一个仓库、同一套规则、同一份任务 brief 里协作。

你负责判断方向。

Codex 负责把边界画清楚。

Claude Code 负责往前推。

最后再让 Codex 回来验收。

这个闭环跑顺了，Agent 才不只是“会聊天的工具”，而是开始有一点工程协作的样子。

资料与源码坐标

OpenAI Codex 仓库：https://github.com/openai/codex
Codex CLI 文档：https://developers.openai.com/codex/cli
Codex AGENTS.md 文档：https://developers.openai.com/codex/guides/agents-md
Codex sandbox 文档：https://developers.openai.com/codex/concepts/sandboxing
Codex subagents 文档：https://developers.openai.com/codex/subagents
Claude Code 仓库：https://github.com/anthropics/claude-code
Claude Code CLI reference：https://code.claude.com/docs/en/cli-reference
Claude Code permission modes：https://code.claude.com/docs/en/permission-modes
Claude Code tools reference：https://code.claude.com/docs/en/tools-reference
Claude Code memory 文档：https://code.claude.com/docs/en/memory
Claude Code settings 文档：https://code.claude.com/docs/en/settings
Claude Code hooks 文档：https://code.claude.com/docs/en/hooks
Claude Agent SDK loop 文档：https://code.claude.com/docs/en/agent-sdk/agent-loop
Claude Agent SDK subagents 文档：https://code.claude.com/docs/en/agent-sdk/subagents

本文参考版本：

openai/codex：b985768dc11446c60e092af510b75e5e8863e514
anthropics/claude-code：158620419486e3d2d696351d5a71fbd6b8f58653
anthropics/claude-agent-sdk-typescript：49b6b0e8271a8677f678f121f94b059d25789867
@anthropic-ai/claude-code@2.1.121
@anthropic-ai/claude-agent-sdk@0.2.121

我把 Codex 和 Claude Code 拆开看：Agent 到底是怎么干活的？ ​

Agent 不是模型，是闭环 ​

资料边界先说清楚 ​

Codex：把 Runtime 摊开给你看 ​

Claude Code：把协作体验做厚 ​

体感差异从哪来 ​

怎么用才高效 ​

场景一：用 Codex 学 React 源码 ​

场景二：Codex 做计划，Claude Code 去实现 ​

把仓库变成协作中心 ​

最后 ​

资料与源码坐标 ​

我把 Codex 和 Claude Code 拆开看：Agent 到底是怎么干活的？

Agent 不是模型，是闭环

资料边界先说清楚

Codex：把 Runtime 摊开给你看

Claude Code：把协作体验做厚

体感差异从哪来

怎么用才高效

场景一：用 Codex 学 React 源码

场景二：Codex 做计划，Claude Code 去实现

把仓库变成协作中心

最后

资料与源码坐标