第 5 篇：Claude Code 与 Codex 可观测性设计拆解

栏目 AgentObservability；专栏 Agent 观测；标签 Agent、可观测性、Claude Code、Codex、Coding Agent

文章目标#

Coding Agent 的一次任务，不是“用户发出 Prompt，模型返回答案”这么简单。一个典型的代码修复任务通常包含：

1
用户目标
2
→ 上下文组装
3
→ 模型流式响应
4
→ Tool Call
5
→ 权限审批
6
→ Shell / 文件操作
7
→ Tool Result 回填
8
→ 测试与环境验证
9
→ 上下文压缩
10
→ 断线恢复或 Session Resume
11
→ 最终结果

这条链横跨本地 CLI、模型 Provider、文件系统、Shell 子进程、MCP Server、权限系统和远程遥测后端。任何一个环节出现断点，都可能造成三类问题：

无法恢复：进程退出后不知道任务做到哪一步；
无法诊断：只能看到最终失败，看不到最早异常；
无法审计：不知道谁批准了哪个工具、修改了哪些文件、产生了什么副作用。

本文基于截至 2026 年 8 月 5 日的官方文档、官方开源仓库固定快照、可验证 CLI 行为，以及明确标注为非官方的社区解析，对比 Claude Code 与 Codex CLI 如何组织：

本地 Session Record；
Message、Turn 与 Parent 关系；
模型请求和流式事件；
Tool Call、Tool Result、Shell 与文件变更；
Permission、Approval 与 Sandbox；
MCP 活动；
Context Compaction、Fork 与 Resume；
OpenTelemetry Metrics、Events/Logs 与 Trace；
Retry、Fallback、Usage 与成本缺失；
后续评测、事故复盘和运行重建接口。

本文不比较两者的代码能力，也不尝试记录或推断隐藏 Chain-of-Thought。分析对象仅限于：

用户可观察、系统可持久化、运行时可导出、能够参与因果重建的事实。

贯穿全文的统一案例是：

用户要求 Coding Agent 修复 orders/discount.py 中的边界条件错误，只允许修改 orders/ 和 tests/orders/，不得修改 payments/；Agent 需要读取仓库、搜索代码、修改文件、运行测试，并输出最终 Diff。

1. 分析方法与证据边界#

1.1 官方文档#

官方文档用于确定公开支持的行为和兼容性边界。

Claude Code 官方 Session 文档明确说明：

Session 是绑定项目目录的本地保存会话；
Session 会持续写入本地 Transcript；
--continue、--resume、--from-pr 和 /resume 可以继续会话；
Resume 会恢复对话历史，包括 Tool Call 与 Tool Result；
/compact 会使用摘要替换历史；
Transcript 默认位于 ~/.claude/projects/<project>/<session-id>.jsonl；
每行是 Message、Tool Use 或 Metadata 等 JSON 对象；
Transcript Entry 格式属于 Claude Code 内部格式，可能随版本变化；
官方建议面向自动化优先使用 /export、claude -p --output-format json|stream-json、Hooks 或 Agent SDK，而不是把内部 JSONL 当成稳定公共 Schema。¹

Claude Code 官方 Monitoring 文档明确说明：

OpenTelemetry Export 是 Opt-in；
Metrics、Events/Logs 与 Trace 是三条不同信号管线；
Trace 目前为 Beta，默认关闭；
prompt.id 用于关联同一次 Prompt 触发的 Event；
message.uuid、request_id、client_request_id 和 tool_use_id 可与 Transcript 或 Span 对齐；
event.sequence 用于 Session 内事件排序；
用户 Prompt、Assistant Response、Tool Arguments、Tool Content 和原始 API Body 默认不会全部导出，需要独立开关显式开启；
Cost Metric 是近似值，正式计费应以 Provider Billing 为准。²

Codex 官方 CLI 文档与配置文档明确说明：

codex resume 可以恢复交互式 Session；
codex exec resume 可以恢复非交互式 Session；
codex exec --ephemeral 不写入本地 Session Rollout；
codex exec --json 输出换行分隔的 JSON Event；
approval_policy 控制何时暂停审批；
sandbox_mode 控制 Shell 命令的文件系统与网络边界；
OTel 默认关闭，开启后可以导出 API Request、SSE/WebSocket Event、Prompt、Tool Decision 和 Tool Result；
otel.log_user_prompt=false 是默认值；
当前配置同时提供 Log、Metric 与 Trace Exporter。³⁴⁵

官方文档的优点是稳定、面向用户；不足是通常不会披露所有内部字段和异常分支。

1.2 开源代码和公开仓库#

Codex CLI 的核心实现公开在 openai/codex。本文固定引用：

1
openai/codex
2
commit: f2d825533c9423728f319a6dbcbb31c21768aa69
3
date: 2026-08-05

固定 Commit 很重要。直接引用 main 会让文章中的类型和字段随着仓库更新而漂移。

官方源码可以补足文档没有展开的四类细节。

第一类：本地 Rollout 持久化#

RolloutRecorder 的模块注释直接说明，它将 Codex Session Rollout 持久化为 JSONL，使 Session 能够在以后被检查或恢复。当前参数中可以看到：

1
session_id
2
conversation_id / ThreadId
3
forked_from_id
4
parent_thread_id
5
SessionSource
6
ThreadSource
7
BaseInstructions
8
DynamicTools
9
SelectedCapabilityRoots
10
MultiAgentVersion
11
ThreadHistoryMode
12
HistoryPosition
13
InitialWindowId

Recorder 还区分：

1
Create
2
Resume

并通过后台 Writer Task 处理：

1
AddItems
2
Persist
3
Flush
4
Shutdown

这说明 Codex 的本地记录不是普通调试日志，而是 Thread Listing、Resume、Fork、History 和状态发现的一部分。⁶

第二类：结构化 Exec Event#

Codex TypeScript SDK 和 Rust exec_events.rs 公开了非交互模式的顶层 Event：

1
thread.started
2
turn.started
3
turn.completed
4
turn.failed
5
item.started
6
item.updated
7
item.completed
8
error

其中 thread.started.thread_id 可用于以后恢复 Thread；turn.completed 带 Token Usage；Item 有独立 ID 和生命周期。⁷⁸

第三类：Tool、Shell、文件和 MCP Item#

当前公开 Item 类型包括：

1
agent_message
2
reasoning
3
command_execution
4
file_change
5
mcp_tool_call
6
collab_tool_call
7
web_search
8
todo_list
9
error

Command Item 可以表达：

1
command
2
aggregated_output
3
exit_code
4
status

File Change Item 可以表达：

1
path
2
add / delete / update
3
patch status

MCP Item 可以表达：

1
server
2
tool
3
arguments
4
result
5
error
6
status

这套结构比“输出一段 CLI 文本”更适合 CI、评测和任务重建。⁹⁸

第四类：OTel 与审批实现#

codex-otel 官方 Crate 同时提供：

Log、Trace、Metric Exporter；
Session-scoped Business Event；
Trace Context Helper；
显式 Shutdown / Flush；
可配置 Span Attribute 与 W3C tracestate。¹⁰

SessionTelemetry 当前记录：

1
codex.conversation_starts
2
codex.startup_phase
3
codex.turn_ttft
4
codex.api_request
5
codex.sse_event
6
codex.websocket_connect
7
codex.websocket_request
8
codex.websocket_event
9
codex.user_prompt
10
codex.tool_decision
11
codex.sandbox_outcome
12
codex.tool_result

Approval 实现则把决策来源区分为：

1
Hook / Config
2
Guardian / Automated Reviewer
3
User

并将 Shell、Exec Command 和 Apply Patch 作为不同 Approval Action。¹¹¹²

开源代码能解释当前实现，但仍不是永久公共数据合同。文章中的源码字段必须带 Commit。

1.3 可验证运行行为#

“可验证运行行为”指不依赖内部源码，用户可以在受控环境中亲自复现的现象。

Claude Code 可以验证：

1
# 查看本地 Transcript
2
ls ~/.claude/projects/<project>/
3

4
# 恢复最近会话
5
claude --continue
6

7
# 按 Session ID 恢复
8
claude --resume <session-id>
9

10
# 结构化非交互输出
11
claude -p --output-format stream-json "inspect this repository"
12

13
# 查看上下文
14
/context
15

16
# 执行压缩
17
/compact
18

19
# 导出可读 Transcript
20
/export

Codex 可以验证：

1
# 恢复交互式 Session
2
codex resume <session-id>
3

4
# 非交互式 JSONL Event
5
codex exec --json "inspect the failing test"
6

7
# 不持久化 Rollout
8
codex exec --ephemeral "summarize this repository"
9

10
# 设置 Sandbox
11
codex exec --sandbox workspace-write "fix the bug"
12

13
# 恢复非交互式 Session
14
codex exec resume <session-id> "continue and run tests"

可验证行为能确认：

文件是否真实落盘；
Session 是否能恢复；
JSONL Event 是否能被机器消费；
Permission 和 Sandbox 是否改变实际工具行为；
OTel 后端是否收到 Event、Metric 和 Span。

它不能直接证明某个闭源内部函数如何实现。

1.4 社区源码解析#

Claude Code 没有公开完整产品源码，因此社区解析具有一定参考价值，但必须降低证据等级。

本文参考 Windy3f3f3f3f/how-claude-code-works 的固定 Commit：

1
4a1fe85d3dc6956b47318645280b16d541847ecd

该仓库把 Claude Code 可观测性概括为四层：

1
Metric
2
Event
3
Trace
4
Transcript

并讨论：

Prompt Event 使用 ID 做离散关联；
Trace 使用 Parent-child 表达因果和时延；
Metric 应避免 Prompt 级高基数 ID；
Transcript 使用 Message Parent 支撑连续性；
Compaction 后需要区分物理历史和逻辑历史。¹³

这些结论与当前官方 Monitoring 文档的大方向一致，但社区仓库中的：

内部函数名；
文件路径；
私有状态字段；
某个版本的逻辑 Parent 字段；

都不能被写成长期稳定接口。

社区解析适合用于：

提出验证假设；
理解设计意图；
定位当前版本的实现线索；
提炼可复用架构模式。

不适合用于：

承诺未来兼容性；
作为官方安全合同；
建立无版本号的生产解析器。

1.5 事实、实现推断和设计推测分开标记#

本文使用以下证据层级：

标记	说明	可以得出的结论
[官方文档]	产品公开文档	公共行为、配置和兼容性边界
[官方源码]	官方仓库固定 Commit	当前实现和类型结构
[可验证行为]	用户可以复现实验	实际可观察现象
[社区解析]	非官方固定快照	实现线索和待验证假设
[工程推断]	基于前述证据的抽象	可复用设计建议，不是产品事实

判断优先级要根据问题类型选择：

1
问“官方支持什么”      → 官方文档
2
问“当前源码怎么做”    → 固定 Commit 官方源码
3
问“我的版本实际怎样”  → 可验证实验
4
问“闭源内部可能怎样”  → 社区解析 + 明确边界
5
问“我们应该怎样设计”  → 工程推断

特别要避免下面三种写法。

错误写法一：把社区字段写成官方合同#

1
Claude Code 永远使用字段 X 维护逻辑 Parent。

更准确：

1
某社区快照观察到字段 X；官方只承诺 Transcript 可恢复，
2
且明确声明内部 Entry 格式会变化。

错误写法二：把 Codex 源码实现写成稳定 JSON Schema#

1
Rollout 永远包含这些枚举和字段。

更准确：

1
在 commit f2d825... 中，RolloutRecorder 和 Exec Event 使用这些类型；
2
生产解析器仍需锁定 Codex 版本并做兼容性测试。

错误写法三：把设计推断写成产品行为#

1
出现恢复成功，说明系统切换了 Fallback Model。

更准确：

1
只有 Provider / Model Route 字段确实变化时，才能确认 Model Fallback；
2
网络重试、非流式降级和模型切换不是同一概念。

2. Coding Agent 为什么需要本地运行记录#

Coding Agent 四层记录架构

2.1 CLI 生命周期与远程服务不同#

传统服务通常是长生命周期进程：

1
请求进入
2
→ 执行
3
→ Exporter 批量导出
4
→ 进程继续运行

CLI Agent 随时可能因为以下原因退出：

1
Ctrl+C
2
Terminal 关闭
3
SSH 断开
4
系统休眠
5
进程崩溃
6
CLI 升级
7
Shell 子进程卡死
8
网络断开
9
机器重启

如果系统只依赖远程 OTel：

未 Flush 的 Span 可能丢失；
最后一段 Tool Result 可能未导出；
Trace 可能被采样；
远程 Backend 可能不可用；
OTel 本身不保存完整恢复上下文。

本地 Session Record 解决的是：

1
上次做到哪里
2
哪些消息已经存在
3
模型已经发起哪些 Tool Call
4
哪些 Tool Result 已经回填
5
Context 是否经过压缩
6
当前 Thread / Session 是什么
7
恢复时从哪里继续

远程 Telemetry 解决的是：

1
哪一步失败
2
哪一步最慢
3
Retry 是否放大
4
谁批准了工具
5
成本和 Token 如何变化
6
哪些版本发生回归

二者的可靠性目标不同。

2.2 任务恢复依赖本地状态#

一次代码修复任务可能经历：

1
Turn 1：理解问题
2
Turn 2：搜索代码
3
Turn 3：读取文件
4
Turn 4：修改文件
5
Turn 5：运行测试
6
Turn 6：处理测试失败
7
Turn 7：再次修改
8
Turn 8：最终验证

恢复至少要知道：

Conversation / Thread ID；
Message 或 Item 历史；
Tool Call 与 Tool Result；
当前模型或 Agent 配置；
Context Compaction 结果；
Pending Approval；
Pending Tool；
已完成副作用；
工作目录和环境 Revision。

Claude Code 官方文档说明 Resume 会恢复完整对话历史、Tool Call 与 Result，并尝试恢复模型、Agent、Permission Mode、Active Goal 和部分 Scheduled Task；但不是所有启动参数都会自动恢复，例如某些 MCP、Settings、Plugin、Fallback Model 和附加目录需要再次传入。¹

这说明：

Session Resume 不是进程内内存快照，而是基于已持久化状态重新构建运行环境。

Codex 的 RolloutRecorder 同样把 Create 与 Resume 分开，并保存 Thread、Parent、Fork、Instructions、Tools 和 History Mode 等元数据。⁶

2.3 文件和 Shell 操作需要完整审计#

Coding Agent 会产生真实环境副作用。仅记录：

1
{
2
  "tool_name": "shell",
3
  "success": true
4
}

没有足够诊断价值。

Shell 至少需要：

1
command_id
2
command_hash
3
cwd
4
environment_id
5
sandbox_policy
6
approval_request_id
7
approval_decision
8
start_time
9
duration
10
exit_code
11
stdout_ref
12
stderr_ref
13
cancelled
14
timed_out

文件操作至少需要：

1
tool_call_id
2
target_path_hash
3
path_class
4
state_before
5
state_after
6
diff_ref
7
patch_status
8
added_lines
9
deleted_lines
10
forbidden_scope_touched
11
rollback_point

还要区分：

1
工具执行成功
2
≠
3
业务结果成功

例如：

1
pytest 进程正常启动并返回 exit_code=1

表示 Shell Runtime 正常，但测试业务 Outcome 失败。

本地 Session Record 可以保存较完整的 Command 和 Result。远程 OTel 更适合默认保存：

Tool Name；
Duration；
Exit / Success；
Input / Output 长度；
Call ID；
Error Category；
Artifact Reference。

完整代码、命令和输出应进入受控本地文件或 Artifact Store。

2.4 本地记录与远程 Telemetry 的职责分离#

Coding Agent 的运行证据可以拆成四层。

1
flowchart TB
2
    U[用户任务] --> A[Agent Loop]
3
    A --> M[模型请求]
4
    A --> T[工具 / Shell / MCP]
5
    T --> E[文件系统与外部环境]
6
    E --> O[环境 Outcome]
7

8
    subgraph L1[第一层：Local Session Record]
9
        S1[Message / Turn / Item]
10
        S2[Tool Call / Tool Result]
11
        S3[Checkpoint / Compaction / Resume]
12
        S4[Artifact Reference]
13
    end
14

15
    subgraph L2[第二层：Event / Log]
16
        E1[Prompt]
17
        E2[API / Stream]
18
        E3[Approval / Sandbox]
19
        E4[MCP / Error / Retry]
20
    end
21

22
    subgraph L3[第三层：Distributed Trace]
23
        R1[Interaction / Workflow]
24
        R2[Generation / LLM]
25
        R3[Tool / Wait / Execution]
26
        R4[Handoff / Guardrail / Custom]
27
    end
28

29
    subgraph L4[第四层：Metric]
30
        K1[Token / Cost]
31
        K2[Latency / TTFT]
32
        K3[Success / Failure]
33
        K4[Tool / Retry Count]
34
    end
35

36
    A -.恢复与重建.-> L1
37
    A -.离散审计.-> L2
38
    A -.因果与关键路径.-> L3
39
    A -.趋势与 SLO.-> L4

四层的职责如下。

层	数据结构	主要问题	是否适合完整内容
Session Record	顺序 Journal / JSONL / State DB	如何 Resume、Fork 和恢复上下文	相对完整，但高度敏感
Event / Log	离散结构化记录	某件事何时发生、由谁触发	默认记录 Shape
Trace	Parent-child Span	哪一步导致哪一步、哪里最慢	大内容应引用 Artifact
Metric	低基数时间序列	整体成功率、成本和延迟是否异常	不适合高基数 ID 和原文

一个成熟的设计不应把四层合并成一份“万能日志”。

3. Claude Code 的观测层次#

Claude Code 从 Session Record 到 Trace 的映射

3.1 Session Record#

[官方文档] Claude Code 将 CLI Session 持续保存为本地 Transcript：

1
~/.claude/projects/<project>/<session-id>.jsonl

每行是一个 JSON 对象，可能对应：

1
Message
2
Tool Use
3
Tool Result
4
Metadata

官方同时明确警告：

1
Entry Format 是内部格式，会跨版本变化。

因此建议两种使用方式。

面向普通自动化#

优先使用稳定接口：

1
/export
2
claude -p --output-format json
3
claude -p --output-format stream-json
4
Hook transcript_path
5
Agent SDK

面向故障取证和版本锁定分析#

可以直接解析 JSONL，但必须同时保存：

1
claude_code_version
2
session_id
3
source_path
4
source_file_hash
5
transcript_schema_fingerprint
6
ingestion_time
7
parser_version

不应编写“永远适用”的无版本解析器。

3.2 Message 与 Parent 关系#

Claude Code 当前公开了两类关系。

Message Chain#

Transcript 内的 Message 使用 Message UUID 和 Parent 关系维持对话连续性：

1
message.uuid
2
parentUuid

官方 Monitoring 文档说明：

user_prompt.message.uuid 可以指向持久化的 User Message；
assistant_response.message.uuid 指向本次响应最后一个 Transcript Entry；
下一轮从该 Entry 的 parentUuid 继续；
一次 API Response 可能按 Content Block 保存成多个 Entry。²

Trace Parent#

Trace 使用：

1
trace_id
2
span_id
3
parent_span_id

表达运行时因果与嵌套。

二者不能混用：

1
Message Parent：对话从哪里继续
2
Span Parent：哪个操作触发了哪个操作

一条 Message 可以对应多个 Span；一个模型请求也可能落成多个 Transcript Entry。

3.3 Model Request#

Claude Code 的 Model Request 至少出现在三层。

Transcript#

Assistant Entry 可以保留：

Content Block；
Usage；
Request ID；
Tool Use；
Message Parent。

Event#

当前官方 Event 包含：

1
claude_code.api_request
2
claude_code.api_error
3
claude_code.api_refusal
4
claude_code.assistant_response
5
claude_code.api_retries_exhausted

关键关联字段：

1
request_id
2
client_request_id
3
message.uuid
4
prompt.id
5
event.sequence
6
query_source

request_id 来自服务端响应。
client_request_id 是客户端生成的 x-client-request-id，即使 Timeout 没有服务端 Request ID，也可以关联 Request 与 Failure；第三方 Provider 和某些非流式 Fallback 场景可能缺失。²

Trace#

当前 Span：

1
claude_code.llm_request

可以记录：

1
model
2
gen_ai.system
3
gen_ai.request.model
4
query_source
5
agent_id
6
parent_agent_id
7
duration_ms
8
ttft_ms
9
input_tokens
10
output_tokens
11
cache_read_tokens
12
cache_creation_tokens
13
request_id
14
client_request_id
15
attempt
16
success
17
status_code
18
error
19
response.has_tool_call
20
stop_reason
21
gen_ai.response.finish_reasons

每次 Retry Attempt 还可以作为：

1
gen_ai.request.attempt

Span Event 保存 attempt 和 client_request_id。²

`query_source` 的价值#

同一 Session 中并非所有模型请求都来自主对话：

1
repl_main_thread
2
compact
3
subagent
4
workflow
5
session title generation

不记录 query_source，就会把 Compaction Token、子 Agent Token 和主任务 Token 混在一起。

3.4 Tool Call 与 Tool Result#

Claude Code 使用：

1
tool_use_id

作为 Tool 生命周期的核心关联键。

1
模型 tool_use block
2
      │
3
      ├── tool_decision Event
4
      ├── Hook Payload
5
      ├── claude_code.tool Span
6
      ├── tool.execution Span
7
      └── tool_result Event

官方还把同一值映射为：

1
gen_ai.tool.call.id

以对齐 OpenTelemetry GenAI 语义。²

Tool Result Event#

当前可以表达：

1
tool_name
2
tool_use_id
3
success
4
duration_ms
5
error_type
6
decision_type
7
result_tokens / size
8
MCP scope

需要牢记：

1
Rejected Tool Call 不产生 tool_result

拒绝应从 tool_decision 查询。
因此：

1
没有 tool_result

不能直接解释成：

1
工具执行失败。

它还可能表示：

1
执行前被拒绝
2
Session 中断
3
Event 丢失

3.5 Permission 与 Approval#

Claude Code 当前 Trace Hierarchy 把 Tool 分成：

1
claude_code.tool
2
├── claude_code.tool.blocked_on_user
3
└── claude_code.tool.execution

其中：

Parent Tool Span 记录总墙钟时间；
blocked_on_user 记录等待权限的时间；
tool.execution 记录工具本体执行时间。²

这解决了一个常见误判：

1
工具总耗时 45 秒

实际可能是：

1
等待用户批准：44.8 秒
2
工具执行：0.2 秒

tool_decision Event 还记录：

1
decision = accept | reject
2
source

Decision Source 可以来自：

1
config
2
hook
3
user_permanent
4
user_temporary
5
user_abort
6
user_reject

对企业审计而言，关键问题不是“工具最终运行了吗”，还包括：

1
谁作出授权
2
授权来自什么策略
3
是否是永久授权
4
是否被 Hook 阻断
5
是否等待了用户

3.6 MCP Event#

Claude Code 当前提供：

1
claude_code.mcp_server_connection

用于表示 MCP Server 的：

1
connected
2
failed
3
disconnected

可观测属性包括：

1
transport_type
2
server_scope
3
duration_ms
4
error_code
5
plugin context

MCP Tool Call 不需要另建一套完全不同的生命周期，而是继续复用：

1
tool_use_id
2
tool_decision
3
tool_result
4
claude_code.tool

这形成两条互补链：

1
MCP Connection Event：Server 是否可用
2
MCP Tool Lifecycle：具体调用是否成功

如果只记录 Connection：

1
connected = true

仍无法判断某次 Tool Call 是否 Timeout。
如果只记录 Tool Call，也无法知道失败是否来自 Connection 重建。

3.7 Metrics、Events 与 Trace#

Claude Code 的三类 OTel 信号有明确分工。

Metrics#

适合回答：

1
Session 数量
2
Token 用量
3
Cache Token
4
近似成本
5
修改代码行数
6
Commit / PR 数量
7
审批决策数量
8
活跃时间

Metric 使用低基数 Attribute 做聚合。

prompt.id 被明确排除在 Metric 外，因为每个 Prompt 都唯一，会产生无界时间序列。²

Events / Logs#

适合回答：

1
某个 Prompt 触发了哪些 API Request
2
某个工具由谁批准
3
某次 MCP Connection 为什么失败
4
某次 Compaction 是否成功
5
某次请求是否耗尽 Retry

关键字段：

1
session.id
2
prompt.id
3
message.uuid
4
request_id
5
client_request_id
6
tool_use_id
7
event.sequence

Trace#

当前根 Span：

1
claude_code.interaction

每个 User Prompt 启动一个 Root：

1
claude_code.interaction
2
├── claude_code.llm_request
3
├── claude_code.hook
4
└── claude_code.tool
5
    ├── claude_code.tool.blocked_on_user
6
    ├── claude_code.tool.execution
7
    └── subagent llm_request / tool spans

Agent SDK 和 claude -p 可以从环境中的 TRACEPARENT 继承上游 Context；Bash 和 PowerShell 子进程也可以继承当前 Tool Span 的 W3C Trace Context。²

Compaction Event#

当前官方 Event：

1
claude_code.compaction

可以记录：

1
trigger = auto | manual
2
success
3
duration_ms
4
pre_tokens
5
post_tokens
6
error
7
precompute_reuse

它能说明“发生了压缩”，但并不自动证明硬约束被正确保留。任务 Contract 仍需要独立校验。

4. Claude Code 的任务连续性#

4.1 Session 与 Prompt 关联#

Claude Code 至少存在四个重要粒度。

ID	粒度	用途
`session.id`	整个 CLI Session	Resume、用户归属、跨 Prompt 聚合
`prompt.id`	一次用户 Prompt	关联本次 Prompt 触发的 Event
`message.uuid`	一条 Transcript Message	Event 与本地 Message 对齐
`request_id` / `client_request_id`	一次模型 Request / Attempt	网络请求关联与错误定位

一次 Prompt 可能触发：

1
多个 Model Request
2
多个 Tool Call
3
多个 Tool Result
4
多个子 Agent Span
5
一次或多次 Compaction / Hook

因此：

1
prompt.id

不是模型 Request ID，也不是 Message Parent。

4.2 Tool Result 如何指向发起消息#

Tool Result 至少通过三条边关联。

Tool 边#

1
tool_use_id

关联：

1
模型 Tool Use
2
Tool Decision
3
Hook
4
Tool Span
5
Tool Result

Message 边#

Tool Result 回填后形成新的 Message Entry，并通过：

1
message.uuid
2
parentUuid

继续对话链。

Trace 边#

Tool Span 通过：

1
parent_span_id

挂在触发它的 Interaction 或 Agent Tool 下。

因此一个完整查询应回答：

1
哪个模型响应生成 Tool Call
2
哪个 Tool Use 被批准
3
工具是否执行
4
Tool Result 写入哪条 Message
5
下一次模型请求是否包含该结果

4.3 Compaction 前后的逻辑父节点#

Compaction 后存在两套历史。

物理上下文#

模型当前实际收到：

1
Summary
2
最近消息
3
最近读取文件
4
保留的 Tool Result

逻辑历史#

任务真实发生过：

1
早期 User Constraint
2
全部工具动作
3
环境副作用
4
审批记录
5
失败与 Retry

如果系统只保存 Summary，会出现：

1
物理上下文可继续
2
但逻辑历史不可审计

官方保证 /compact 会用摘要替换历史；官方没有承诺内部 JSONL 中某个固定字段永远表示逻辑 Parent。¹

推荐在企业采集层生成稳定对象：

1
{
2
  "compaction_id": "cmp_04",
3
  "summary_message_id": "msg_88",
4
  "derived_from_message_ids": ["msg_01", "msg_02", "msg_87"],
5
  "previous_logical_tail_id": "msg_87",
6
  "pre_tokens": 124000,
7
  "post_tokens": 18600,
8
  "task_contract_hash_before": "sha256:...",
9
  "task_contract_hash_after": "sha256:...",
10
  "dropped_manifest_ref": "artifact://compaction/cmp_04"
11
}

这样既不依赖某个私有字段，又能保留逻辑连续性。

4.4 Resume 后如何恢复任务#

Claude Code Resume 会恢复：

完整对话历史；
Tool Call 与 Tool Result；
可用时恢复原模型；
原 Agent 的 System Prompt、Tool Restriction 和 Model；
部分 Permission Mode；
Active Goal；
未过期 Scheduled Task。¹

但以下状态可能不会自动恢复：

1
某些 --mcp-config
2
某些 --settings
3
--plugin-dir
4
--fallback-model
5
--add-dir
6
中途 /add-dir
7
后台 Bash
8
后台 Monitor Task
9
已退休或不再允许的 Model
10
不允许自动恢复的高风险 Permission Mode

因此 Resume 应分成两步。

第一步：恢复 Session State#

1
Conversation
2
Tool History
3
Compaction Summary
4
Agent Identity
5
Goal

第二步：验证 Runtime State#

1
当前工作目录是否一致
2
Git HEAD 是否一致
3
未提交文件是否一致
4
Tool Schema 是否一致
5
MCP Server 是否仍可用
6
Permission 是否仍合法
7
已完成副作用是否存在

Resume 成功不等于环境一致。

4.5 本地 JSONL 如何重建完整执行链#

官方建议优先使用稳定接口。
在版本锁定的诊断场景，可以用下面的映射重建。

Session Record 到 Trace 的映射表#

Session / Event 对象	关联键	Trace / Span 对象	能回答的问题
User Message	`message.uuid`	`claude_code.interaction`	哪条用户输入启动本轮
Prompt Event Group	`prompt.id`	Root 下的 API / Tool Event	一次 Prompt 触发了哪些动作
Assistant Entry	`requestId`	`claude_code.llm_request`	哪个 API Response 生成该消息
Client Attempt	`client_request_id`	`gen_ai.request.attempt`	Timeout 等无 Server ID 的失败
Tool Use Block	`tool_use_id`	`claude_code.tool`	模型发起了哪个工具
Tool Decision	`tool_use_id`	`tool.blocked_on_user`	谁批准或拒绝
Tool Result	`tool_use_id`	`tool.execution`	是否执行、耗时和错误
Message Tail	`message.uuid` / `parentUuid`	下一次 Interaction	下一轮从哪里继续
Compaction Event	`session.id` + sequence + time	Compaction Model Request	何时压缩、Token 如何变化
MCP Connection	`session.id` + server scope	MCP Event / Tool Span	Server 是否连接与重连

重建流程#

1
1. 读取 Transcript JSONL
2
2. 按 uuid / parentUuid 建立 Message Graph
3
3. 读取 Event，按 event.sequence 排序
4
4. 按 prompt.id 形成 Prompt Event Group
5
5. 按 request_id / client_request_id 关联模型请求
6
6. 按 tool_use_id 关联 Tool Decision、Execution、Result 和 Hook
7
7. 按 trace_id / span_id 建立 Span Tree
8
8. 关联 Git Diff、Shell Output 和 Environment Snapshot
9
9. 运行 Outcome Verifier

不要只靠时间邻近 Join#

错误策略：

1
离得最近的 tool_result 属于前一个 model response。

并发工具和子 Agent 会让这种 Join 立即失效。

优先级应是：

1
稳定 ID
2
→ Parent Relation
3
→ Sequence
4
→ 时间窗口

5. Codex CLI 的观测结构#

Codex CLI 的观测结构

5.1 Session 与任务状态#

Codex 将本地 Session 持久化为 Rollout JSONL。当前官方源码显示：

1
SESSIONS_SUBDIR = sessions
2
ARCHIVED_SESSIONS_SUBDIR = archived_sessions

并围绕 Rollout 提供：

1
Thread List
2
Search
3
Archive
4
Session Index
5
State DB
6
Compression
7
History
8
Resume
9
Fork / Parent Thread

RolloutRecorderParams 分为：

1
Create { ... }
2
Resume { path }

这说明 Session 创建和恢复是明确的两条初始化路径。⁶

后台 Writer#

Recorder 通过 Channel 向后台 Writer 发送：

1
AddItems
2
Persist
3
Flush
4
Shutdown

这有两个工程含义。

第一，CLI 退出前需要显式 Flush，才能确定最后的 Rollout Item 已落盘。

第二，Writer Task 本身也需要可观测状态，例如：

1
terminal_failure
2
queue_depth
3
flush_latency
4
last_persisted_ordinal

否则用户看到的是“任务完成”，但 Session 尾部可能没有真正持久化。

Thread 与 Session#

Codex TypeScript SDK 把：

1
Thread

定义为一个可包含多个连续 Turn 的对话对象。thread.started 返回 thread_id，后续 run() 或 runStreamed() 可以继续使用同一 Thread。⁷¹⁴

5.2 模型流式事件#

Codex 至少有三种结构化流。

Provider / Runtime Stream#

OTel 中可以看到：

1
codex.sse_event
2
codex.websocket_request
3
codex.websocket_event

用于记录模型协议层的 Event Kind、Duration、Success 和 Error。

`codex exec --json`#

面向脚本和 CI，输出：

1
thread.started
2
turn.started
3
item.started
4
item.updated
5
item.completed
6
turn.completed
7
turn.failed
8
error

其中：

1
thread.started.thread_id

可用于恢复 Thread；turn.completed.usage 包含 Input、Cached Input、Cache Write、Output 和 Reasoning Token。³⁷

Local Rollout JSONL#

面向 Session Persistence 和 Resume，生命周期长于当前 stdout Stream。

三者分别回答：

1
Provider Stream：底层传输发生了什么
2
Exec JSONL：当前自动化客户端收到了什么
3
Rollout JSONL：以后恢复需要什么

它们不能互相替代。

5.3 Shell 命令#

当前 Exec Item：

1
command_execution

可以记录：

1
id
2
command
3
aggregated_output
4
exit_code
5
status

Status 当前包含：

1
in_progress
2
completed
3
failed
4
declined

这使消费者可以观察：

1
item.started
2
→ item.updated
3
→ item.completed

而不是只能等待最终大段文本。⁸

企业观测层建议补充：

1
cwd
2
environment_id
3
sandbox_profile
4
approval_request_id
5
command_hash
6
stdout_ref
7
stderr_ref
8
timeout_ms
9
signal
10
side_effect_class

Shell Success 与业务成功分开#

1
pytest 返回 exit_code=1

应该解释为：

1
Command Execution 已完成
2
Test Outcome 失败

而不是网络或进程创建失败。

5.4 文件读取与补丁修改#

当前 Exec Item：

1
file_change

记录：

1
id
2
changes[]
3
path
4
kind = add | delete | update
5
status

文件读取可能通过 Shell、Function Tool 或 MCP 完成，具体载体不一定统一。企业层应归一化为：

1
artifact_id
2
path_hash
3
path_class
4
content_hash_before
5
content_hash_after
6
diff_ref
7
patch_status
8
allowed_scope
9
forbidden_scope_violation

为什么必须有 Environment Diff#

Item 告诉你“Agent 认为应用了 Patch”。
Environment Diff 才能证明：

1
哪个文件真的发生变化
2
是否出现额外改动
3
是否修改了禁止目录
4
是否能回滚

5.5 Tool Approval#

Codex 当前配置支持：

1
approval_policy =
2
  untrusted
3
  on-request
4
  never
5
  granular

Granular Policy 可以分别控制：

1
sandbox_approval
2
rules
3
mcp_elicitations
4
request_permissions
5
skill_approval

审批者可以是：

1
user
2
auto_review

当前源码进一步区分决策来源：

1
Hook
2
Automated Reviewer
3
User

并为以下 Action 构建 Approval Payload：

1
Shell
2
ExecCommand
3
ApplyPatch

Approval Result 可能是：

1
Approved
2
Denied
3
TimedOut
4
Abort
5
NetworkPolicyAmendment

这说明 Codex 的 Approval 不是一个布尔值，而是策略、审查者、Action 和结果的组合。⁴¹²

5.6 Sandbox 与权限模式#

Codex 当前公开 Sandbox Mode：

1
read-only
2
workspace-write
3
danger-full-access

workspace-write 还可以配置：

1
writable_roots
2
network_access
3
tmp exclusions

新权限 Profile 可以进一步表达目录级：

1
read
2
write
3
deny

Sandbox 与 Approval 解决不同问题。

1
Approval：
2
逻辑上是否允许尝试该动作
3

4
Sandbox：
5
操作系统和 Runtime 实际允许做到什么程度

用户批准一条命令，并不代表 Sandbox 一定允许它访问任意路径或网络。

Codex OTel 当前还提供：

1
codex.sandbox_outcome

可以记录：

1
tool_name
2
call_id
3
outcome
4
initial_duration_ms
5
escalated_duration_ms

这使系统可以区分：

1
工具自身失败
2
Sandbox 拒绝
3
发生权限升级
4
升级后成功
5
升级后仍失败

5.7 OpenTelemetry 导出#

Codex OTel 默认关闭。

基本配置：

1
[otel]
2
environment = "staging"
3
exporter = "otlp-http"
4
log_user_prompt = false

当前配置还允许：

1
otel.metrics_exporter
2
otel.trace_exporter
3
OTLP HTTP / gRPC
4
Headers
5
TLS CA
6
Client Certificate
7
Private Key
8
Span Attributes
9
W3C tracestate

Logs / Events#

当前文档列出：

1
codex.conversation_starts
2
codex.api_request
3
codex.sse_event
4
codex.websocket_request
5
codex.websocket_event
6
codex.user_prompt
7
codex.tool_decision
8
codex.tool_result

Metrics#

当前公开 Metric 包括：

1
API Request Count / Duration
2
SSE Event Count / Duration
3
WebSocket Request Count / Duration
4
WebSocket Event Count / Duration
5
Tool Call Count / Duration
6
Turn TTFT
7
Startup Phase

默认 Metadata Tag 包含：

1
auth_mode
2
originator
3
session_source
4
model
5
app.version

Trace#

codex-otel 提供独立 Trace Exporter、tracing_subscriber Layer 和 W3C Trace Context Helper。Session Event 可以同时写入 Log 与 Trace，但：

1
Codex Rollout
2
≠
3
OTel Trace

Rollout 用于恢复 Thread；Trace 用于关联运行和时延。

内容边界#

log_user_prompt=false 时，Prompt 内容被 Redact。
源码中 Tool Result 的 Log 路径可能包含更详细 Output，而 Trace 路径更偏向：

1
arguments_length
2
output_length
3
output_line_count
4
success
5
tool_origin

因此生产部署仍要在 Collector 做二次 Redaction。⁵¹¹

6. OpenAI Agents SDK 的 Trace 模型#

OpenAI Agents SDK 是独立的通用 Agent SDK。它可以帮助理解公开的 Agent Trace 抽象，但不能直接等同于 Codex CLI 的本地 Rollout 或内部 Span Schema。

当前 Python SDK 默认 Trace 层级包括：

1
Trace
2
└── Task Span
3
    └── Turn Span
4
        └── Agent Span
5
            ├── Generation Span
6
            ├── Function Span
7
            ├── Guardrail Span
8
            ├── Handoff Span
9
            └── Custom Span

Trace 默认开启；可以关闭、替换 Processor 或添加额外 Processor。当前 Trace Context 通过 Python contextvar 传播；Batch Processor 在后台导出，短生命周期或需要立即可见时可以显式 Flush。¹⁵

6.1 Workflow Trace#

Trace 表示一个端到端 Workflow。

核心字段：

1
workflow_name
2
trace_id
3
group_id
4
metadata
5
disabled

group_id 可以将同一 Conversation 下的多个 Trace 关联，例如：

1
group_id = coding-session-42

一个 Workflow 可以包含多次 Runner.run()：

1
with trace("Fix repository issue", group_id="session-42"):
2
    diagnosis = await Runner.run(diagnosis_agent, issue)
3
    result = await Runner.run(fix_agent, diagnosis.final_output)

Workflow Trace 比单次模型请求更接近业务 Task。

6.2 Agent Span#

Agent Span 表示某个 Agent 的执行。

可以记录：

1
name
2
tools
3
handoffs
4
output_type

Coding 场景可以有：

1
Main Coding Agent
2
Test Agent
3
Review Agent
4
Documentation Agent

Agent Span 是“哪个 Agent 获得控制权”的边界，内部仍可包含多个 Generation 和 Function。

6.3 Generation Span#

Generation Span 表示一次模型生成。

通常包含：

1
input
2
output
3
model
4
model_config
5
usage

输入输出可能含：

用户 Prompt；
代码；
Tool Result；
私有仓库内容。

Agents SDK 当前默认可能采集敏感 Input / Output，可以通过：

1
RunConfig.trace_include_sensitive_data
2
OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA

关闭。¹⁵

这与 Claude Code 和 Codex CLI 的远程 OTel 默认更克制形成差异：使用通用 SDK 时，开发者必须主动确认敏感数据策略。

6.4 Function Tool Span#

Function Span 表示一次函数工具调用：

1
name
2
input
3
output
4
error
5
duration

它适合通用 Tool，但 Coding Agent 往往还需要扩展：

1
approval.wait
2
sandbox
3
shell process
4
file diff
5
artifact
6
state before / after
7
idempotency

因此 Function Span 是工具观测的骨架，不是完整 Coding Agent Audit Model。

6.5 Handoff Span#

Handoff Span 记录：

1
from_agent
2
to_agent

Handoff 表示控制权发生变化，不应被当成普通 Function Call。

它会影响：

1
当前 Agent
2
Instruction
3
Tool Set
4
Guardrail
5
任务责任
6
后续 Parent Span

OpenAI Agents SDK 的 Handoff 还支持 Input Filter 和 Conversation History Mapper，因此观测层最好记录 Handoff 前后传递了哪些上下文类别，而不是只记目标 Agent 名。¹⁶

6.6 Guardrail Span#

Guardrail Span 记录：

1
guardrail name
2
triggered
3
duration

Coding 场景可以用于：

1
禁止修改 payments/
2
阻止危险 Shell
3
检测 Secret 外发
4
校验 Tool Arguments
5
检查最终 Diff

Guardrail 与 Sandbox 不同：

1
Guardrail：应用级策略和语义验证
2
Sandbox：操作系统级执行隔离

Tool Guardrail、Agent Input Guardrail 和 Output Guardrail 的执行边界也不同，不能只用一个统一 blocked=true。¹⁷

6.7 Custom Span#

custom_span() 用于 SDK 未预定义的操作：

1
context.compaction
2
checkpoint.persist
3
approval.wait
4
git.diff.verify
5
artifact.upload
6
environment.restore

自定义 Span 应同时定义：

1
namespace
2
schema_version
3
owner
4
data_classification
5
cardinality_policy

否则不同团队会产生：

1
approval_time
2
permission_wait
3
wait_for_user
4
human_block

四套语义相同却无法统一查询的字段。

7. 网络故障与恢复记录#

7.1 Stream Disconnect#

Stream Disconnect 至少要区分发生阶段：

1
before_first_event
2
during_text_delta
3
during_tool_name
4
during_tool_arguments
5
after_complete_tool_call
6
after_finish_reason
7
before_usage

Claude Code 可以结合：

1
client_request_id
2
request_id
3
api_error
4
llm_request Span
5
gen_ai.request.attempt

定位。

Codex 可以结合：

1
codex.api_request
2
codex.sse_event
3
codex.websocket_event
4
attempt
5
request_id
6
Thread Event

定位。

统一故障快照建议：

1
{
2
  "stream_phase": "during_tool_arguments",
3
  "attempt_id": "att_02",
4
  "received_event_count": 47,
5
  "last_sequence": 46,
6
  "partial_text_bytes": 1820,
7
  "complete_tool_call_ids": [],
8
  "incomplete_tool_call_ids": ["call_17"],
9
  "finish_received": false,
10
  "usage_received": false
11
}

如果 Tool Arguments 不完整，不应执行工具。

7.2 Retry Attempt#

Claude Code 当前有两种 Retry 证据。

Trace#

每次 Attempt 可以记录为：

1
gen_ai.request.attempt

Span Event。

Event#

当一次 API Request 经多次尝试仍失败时，产生：

1
claude_code.api_retries_exhausted

记录：

1
total_attempts
2
total_retry_duration_ms
3
final_error
4
status_code

Codex 的：

1
codex.api_request

记录：

1
attempt
2
status
3
success
4
duration
5
error
6
request_id
7
recovery_mode
8
recovery_phase

企业归一化模型应区分：

1
operation_id    逻辑模型操作
2
attempt_id      物理请求
3
request_id      Provider 请求
4
retry_reason
5
backoff_ms
6
recovery_status

最终成功不能删除中间失败。

7.3 Model Fallback#

需要严格区分：

1
Transport Retry
2
Transport Fallback
3
Endpoint Fallback
4
Model Fallback

Claude Code 官方文档提到某些 Retry 可能经过非流式 Fallback，此时 client_request_id 可能缺失。
这不等于模型发生变化。

Codex 也不能仅凭“第二次请求成功”就推断切换模型。

只有观察到：

1
from_provider / model
2
to_provider / model
3
route policy
4
fallback reason

才能确认 Model Fallback。

推荐字段：

1
{
2
  "fallback_id": "fb_03",
3
  "type": "model",
4
  "from_provider": "provider-a",
5
  "from_model": "model-a",
6
  "to_provider": "provider-b",
7
  "to_model": "model-b",
8
  "reason": "capacity",
9
  "policy_version": "router-v5"
10
}

7.4 Tool Execution 中断#

Tool Execution 中断需要回答五个问题：

1
工具是否开始
2
副作用是否发生
3
结果是否产生
4
结果是否持久化
5
结果是否回填模型

Claude Code 可联合：

1
tool_use_id
2
tool_decision
3
tool_result
4
tool.execution Span
5
Transcript

Codex 可联合：

1
call_id
2
tool_decision
3
sandbox_outcome
4
tool_result
5
Rollout Item

典型危险窗口：

1
工具已经创建 PR
2
→ 网络或进程在返回 Result 前中断
3
→ Session Resume
4
→ Agent 重新执行 create_pr

此时远端 Outcome 是 Unknown，不能盲目重试。

7.5 Resume 后避免重复副作用#

Session Resume 只能恢复“Agent 认为发生了什么”，不能自动提供外部系统的 Exactly-once。

写工具必须使用：

1
operation_id
2
attempt_id
3
idempotency_key
4
arguments_hash
5
target_resource
6
execution_status
7
result_ref
8
state_after_version

恢复算法：

1
def resume_side_effect(operation_id: str):
2
    record = ledger.get(operation_id)
3

4
    if record.status == "succeeded":
5
        return reuse(record.result_ref)
6

7
    if record.status == "unknown":
8
        remote = query_remote_state(record)
9
        if remote.confirmed:
10
            return persist_and_reuse(remote.result)
11
        return require_human_review(record)
12

13
    if record.status == "not_started":
14
        return execute_new_attempt(record)
15

16
    raise UnsafeResumeState(record.status)

对以下操作尤其重要：

1
create_pull_request
2
git_push
3
send_message
4
database_update
5
deployment
6
payment

7.6 Usage 和成本缺失如何处理#

Usage 可能因为：

1
Stream 在 Usage 前断开
2
Provider 未返回 Usage
3
第三方 Provider Schema 不一致
4
Exporter 未 Flush
5
Trace 被采样
6
Session 尾部未持久化

而缺失。

正确表示：

1
usage_status = missing
2
cost_status = missing | estimated | reconciled

错误表示：

1
input_tokens = 0
2
output_tokens = 0
3
cost = 0

建议保存：

1
usage_source
2
usage_complete
3
provider_request_id
4
estimated_input_tokens
5
estimated_output_tokens
6
billing_reconciliation_status
7
official_billing_cost

数据来源优先级可以是：

1
Provider Response Usage
2
→ Provider Billing / Usage API
3
→ 本地 Tokenizer 估算
4
→ Missing

不同来源不能混成同一种精度。

8. Claude Code 与 Codex 的关键设计差异#

Claude Code 与 Codex CLI 可观测性对照

8.1 本地 Session Record 优先还是平台 Trace 优先#

两者都不是“平台 Trace 优先、没有本地状态”。

Claude Code#

本地 Transcript 是用户直接可用的 Session 连续性底座。
OTel Trace 是可选 Beta 能力，主要服务组织级诊断。

Codex CLI#

本地 Rollout 是 Thread、Resume、Fork、Search 和 State DB 的底座。
Exec JSONL 是自动化接口，OTel 是组织级观测接口。

OpenAI Agents SDK#

平台 Trace 是 SDK 的工作流观测能力，但它不替代 Codex CLI 的 Rollout。

结论：

1
恢复状态 → Local Session Record
2
实时自动化 → JSON / JSONL Event Stream
3
组织监控 → OTel
4
通用 Agent 工作流 → Agents SDK Trace

8.2 Session Record 与 Distributed Trace 的关系#

维度	Session Record	Distributed Trace
目标	Resume、Fork、恢复上下文	因果、时延、错误传播
结构	Journal / Message / Item	Trace / Span / Event
生命周期	跨 CLI 重启	一次 Prompt、Turn 或 Workflow
Parent	Message / Thread Parent	Span Parent / Link
内容	可较完整	默认应最小化
采样	通常不做普通 Trace 采样	可以 Head / Tail Sampling
大对象	可以内嵌或引用	应优先引用 Artifact
稳定性	产品内部格式	OTel 外壳更标准
风险	源码、Prompt、命令落盘	远程传输和后端访问风险

正确架构是：

1
共享 ID
2
而不是复制所有内容

8.3 任务恢复能力#

Claude Code#

公开能力包括：

1
continue
2
resume
3
from-pr
4
branch / fork
5
compact
6
clear 后恢复
7
checkpoint rewind
8
结构化非交互 Resume

恢复边界包括：

某些启动配置需要重新提供；
工作区可能已变化；
同一 Session 被两个 Terminal 恢复时，消息会交错写入同一 Transcript；
Fork 才能稳定隔离并行分支。¹

Codex#

公开能力包括：

1
codex resume
2
codex exec resume
3
codex fork
4
Rollout JSONL
5
Thread ID
6
Parent / Fork Metadata
7
State DB
8
Archive / Search
9
--ephemeral

两者都需要额外验证：

1
Git Revision
2
Workspace Diff
3
Tool Schema
4
MCP Capability
5
Permission
6
Pending Side Effect

8.4 权限、Sandbox 和审批模型#

Claude Code#

主要对象：

1
Permission Mode
2
Tool Decision
3
Decision Source
4
Hook
5
blocked_on_user
6
tool.execution

Codex#

主要对象：

1
approval_policy
2
approvals_reviewer
3
granular approval
4
Sandbox / Permission Profile
5
tool_decision
6
sandbox_outcome
7
Guardian / User / Hook

共同原则：

1
授权 ≠ Sandbox
2
等待 ≠ 执行
3
拒绝 ≠ 技术故障
4
参数修改必须可追溯

8.5 Metrics、Events 和 Trace 的覆盖范围#

能力	Claude Code	Codex CLI
本地 Session	Transcript JSONL	Rollout JSONL + State DB / Index
自动化流	JSON / stream-json	`exec --json` JSONL
Event / Log	Prompt、API、Tool、Approval、MCP、Compaction、Retry	Conversation、API、SSE/WS、Prompt、Tool、Sandbox
Metric	Session、Token、Cost、代码、审批、活跃时间	API、SSE/WS、Tool、TTFT、Startup
Trace	Interaction、LLM、Tool、Wait、Execution、Hook、Subagent	Trace Exporter + tracing Event / Span
Request Attempt	Attempt Span Event + Exhausted Event	`codex.api_request.attempt`
Tool 主键	`tool_use_id`	`call_id` / Item ID
内容默认	远程内容默认克制	Prompt 默认 Redact，Tool Log 需二次治理
成本	近似 Cost Metric	Usage/Metric 为底层，企业自行计价
源码开放	产品闭源	核心 CLI 和 SDK 开源

8.6 评测数据接口#

Claude Code 可以从：

1
Transcript
2
claude -p JSON / stream-json
3
OTel Event
4
Trace
5
Hook Payload
6
Git Diff
7
Environment Snapshot

构造评测样本。

Codex 可以从：

1
Rollout JSONL
2
exec JSONL
3
TypeScript / Python SDK Event
4
OTel Event / Metric / Trace
5
Command Item
6
File Change Item
7
MCP Item
8
Sandbox Outcome
9
Environment Snapshot

构造评测样本。

但原始运行日志不是现成 Benchmark。仍需：

1
重建 Task
2
冻结初始环境
3
构造 Ground Truth
4
去除内部和未来信息
5
脱敏
6
去重
7
版本化
8
防止训练 / 测试污染

8.7 用户内容默认采集策略#

Claude Code 远程 OTel#

默认不完整导出：

1
User Prompt
2
Assistant Response
3
Tool Arguments
4
Tool Input / Output
5
Raw API Body

可以用独立开关开启：

1
OTEL_LOG_USER_PROMPTS
2
OTEL_LOG_ASSISTANT_RESPONSES
3
OTEL_LOG_TOOL_DETAILS
4
OTEL_LOG_TOOL_CONTENT
5
OTEL_LOG_RAW_API_BODIES

开启后可能包含完整历史、代码、命令和文件内容，必须在 Collector 和 Backend 做 Redaction、RBAC 和 Retention。²

Codex 远程 OTel#

默认：

1
otel.log_user_prompt = false

Prompt 记录长度而非原文。
Tool Result 的具体内容边界要按当前版本检查；官方源码显示 Log 和 Trace 可能采用不同字段粒度，因此不能只凭配置名假设“所有 Tool Output 都安全”。⁵¹¹

本地记录#

两者本地 Session 都可能包含：

1
Prompt
2
模型回答
3
Shell 命令
4
文件路径
5
Tool Output
6
仓库代码
7
MCP Result

所以：

1
未导出到 OTel
2
≠
3
未被持久化

Claude Code 与 Codex 观测模型总对照表#

对照维度	Claude Code	Codex CLI	可复用结论
本地记录	Project Transcript JSONL	Rollout JSONL + State DB	本地记录是 Resume 底座
Schema 稳定性	官方明确为内部格式	源码可见但仍属实现	解析器必须版本化
会话主键	`session.id`	Thread / Session ID	建立跨平台归一化 ID
Prompt / Turn	`prompt.id`	Turn Event	不等于 Model Request
Message / Item	`message.uuid`	Item ID	对话链与执行链分开
模型请求	`request_id`、`client_request_id`	Attempt、Request ID、SSE/WS	保留物理 Attempt
工具主键	`tool_use_id`	`call_id` / Item ID	Tool 生命周期必须稳定关联
权限	Tool Decision + Hook + Wait Span	Approval Policy + Reviewer	记录来源、等待和参数 Diff
Sandbox	Permission / Runtime / Hook	Sandbox Mode / Permission Profile	授权与执行隔离分开
MCP	Connection Event + Tool Lifecycle	MCP Item + Tool Result	连接与调用分层
Metric	Token、Cost、代码、Session	API、SSE/WS、Tool、TTFT	低基数聚合
Trace	Beta Interaction Tree	OTel Trace Export + tracing	Session Record 不等于 Trace
自动化输出	JSON / stream-json	Exec JSONL	适合作为评测采集接口
Prompt 默认	Redacted	Redacted	内容显式 Opt-in
Resume 风险	环境变化、并发恢复	环境变化、Rollout 尾部	Exactly-once 需 Ledger

9. 可复用的设计模式#

9.1 本地完整记录，远端按需导出#

推荐结构：

1
Local Session Journal
2
├── Message / Turn / Item
3
├── Tool Call / Result
4
├── Compaction / Checkpoint
5
├── Environment Revision
6
└── Artifact Reference
7

8
Remote OTel
9
├── Low-cardinality Metric
10
├── Structured Event
11
└── Trace Span

治理建议：

本地和远程 Retention 分开；
原文和代码默认留在本地或受控 Artifact；
OTel 默认只传 Shape、Hash、状态和 ID；
高风险字段在应用内先脱敏；
Collector 再做第二次 Redaction；
Backend 使用 RBAC 与访问审计。

9.2 Metric 与高基数 Trace 分离#

适合 Metric Label：

1
service
2
environment
3
provider
4
model
5
task_type
6
tool_category
7
success
8
error_type
9
agent_version
10
prompt_version

不适合 Metric Label：

1
session_id
2
prompt_id
3
trace_id
4
tool_call_id
5
user_id
6
raw_file_path
7
raw_prompt
8
full_command

这些字段应留在 Trace、Event、Log 或数据仓库。

9.3 Prompt、Tool 和 Artifact 使用稳定 ID 关联#

推荐跨产品统一字段：

1
{
2
  "session_id": "sess_42",
3
  "task_id": "task_fix_discount",
4
  "turn_id": "turn_07",
5
  "prompt_id": "prompt_17",
6
  "message_id": "msg_88",
7
  "model_operation_id": "modelop_03",
8
  "attempt_id": "att_02",
9
  "provider_request_id": "req_903",
10
  "tool_call_id": "tool_21",
11
  "artifact_id": "diff_01",
12
  "checkpoint_id": "cp_09",
13
  "evaluation_id": "eval_02"
14
}

同时保留产品原始 ID：

1
claude.prompt.id
2
claude.message.uuid
3
claude.tool_use_id
4
codex.thread_id
5
codex.item_id
6
codex.call_id

归一化 ID 用于跨平台分析，原始 ID 用于回到产品事实。

9.4 Compaction 后保留逻辑父节点#

至少保存：

1
compaction_id
2
summary_id
3
derived_from_ids
4
previous_logical_tail_id
5
retained_constraints
6
dropped_manifest_ref
7
checkpoint_id
8
pre_tokens
9
post_tokens

Compaction 不是普通文本压缩，而是状态转换。

硬约束应单独形成 Task Contract：

1
{
2
  "goal": "修复折扣计算",
3
  "must": ["相关测试通过"],
4
  "must_not": ["修改 payments/"],
5
  "allowed_scope": ["orders/**", "tests/orders/**"]
6
}

压缩后重新验证 Contract，而不是只比较摘要语义相似度。

9.5 审批等待时间独立建模#

9.6 Retry 与 Tool Side Effect 分离#

模型网络 Retry：

1
model.operation
2
├── attempt 1
3
├── backoff
4
└── attempt 2

工具副作用：

1
tool.operation
2
├── approval
3
├── execution
4
├── side_effect
5
└── result_delivery

模型 Retry 通常不产生外部业务副作用。
工具 Replay 可能重复写入。

只有满足：

1
idempotency_key
2
execution_ledger
3
known_remote_outcome

时，写工具才适合自动重放。

10. 重建一次 Coding Agent 任务#

一次 Coding Agent 任务的执行链重建

下面给出一个基于官方公开对象构造的完整示例。
它不是某个真实用户 Session，而是一份可复现实验设计。

10.1 用户任务#

用户输入：

1
修复 orders/discount.py 的边界条件错误。
2
只允许修改 orders/ 和 tests/orders/。
3
不得修改 payments/。
4
运行 tests/orders/test_discount.py。
5
最终输出 Git Diff 和测试结果。

统一任务对象：

1
{
2
  "session_id": "sess_42",
3
  "task_id": "task_discount_bug",
4
  "turn_id": "turn_01",
5
  "task_contract": {
6
    "goal": "fix discount boundary condition",
7
    "allowed_paths": ["orders/**", "tests/orders/**"],
8
    "forbidden_paths": ["payments/**"],
9
    "required_checks": ["pytest tests/orders/test_discount.py"]
10
  }
11
}

Claude Code Event 可以表现为：

1
{
2
  "event.name": "claude_code.user_prompt",
3
  "session.id": "sess_42",
4
  "prompt.id": "prompt_17",
5
  "message.uuid": "msg_u_001",
6
  "prompt_length": 143
7
}

Codex Exec Event 可以表现为：

1
{
2
  "type": "thread.started",
3
  "thread_id": "thread_42"
4
}

随后：

1
{
2
  "type": "turn.started"
3
}

10.2 模型请求#

第一次逻辑模型操作：

1
{
2
  "model_operation_id": "modelop_01",
3
  "attempt_id": "att_01",
4
  "provider": "provider-a",
5
  "request_model": "coding-model",
6
  "prompt_version": "planner-v4",
7
  "tool_schema_set_hash": "sha256:tools",
8
  "request_id": "req_901",
9
  "stop_reason": "tool_call",
10
  "status": "completed"
11
}

模型生成：

1
search_code("calculate_discount")
2
read_file("orders/discount.py")

Claude Code 用：

1
tool_use_id

标识调用。
Codex Exec Item 用：

1
item.id / call_id

标识调用生命周期。

10.3 仓库读取#

搜索：

1
rg -n "calculate_discount|discount_rate" orders tests/orders

读取：

1
orders/discount.py
2
tests/orders/test_discount.py

统一 Tool Record：

1
{
2
  "tool_call_id": "call_read_01",
3
  "tool_name": "read_file",
4
  "arguments_hash": "sha256:args",
5
  "path_class": "workspace_file",
6
  "path_hash": "sha256:path",
7
  "approval_required": false,
8
  "execution_status": "completed",
9
  "result_ref": "artifact://tool-result/read_01",
10
  "result_size_bytes": 4821,
11
  "injected_into_model_operation": "modelop_02"
12
}

10.4 Shell 与搜索#

Codex Exec JSONL 可以产生：

1
{
2
  "type": "item.started",
3
  "item": {
4
    "id": "cmd_01",
5
    "type": "command_execution",
6
    "command": "pytest -q tests/orders/test_discount.py",
7
    "aggregated_output": "",
8
    "status": "in_progress"
9
  }
10
}

完成后：

1
{
2
  "type": "item.completed",
3
  "item": {
4
    "id": "cmd_01",
5
    "type": "command_execution",
6
    "command": "pytest -q tests/orders/test_discount.py",
7
    "aggregated_output": "1 failed, 17 passed",
8
    "exit_code": 1,
9
    "status": "failed"
10
  }
11
}

这里的语义是：

1
Command 已运行
2
Test Outcome 失败

不是网络错误。

10.5 文件修改#

模型生成：

1
edit_file(
2
  path = "orders/discount.py",
3
  patch = "..."
4
)

Approval：

1
{
2
  "approval_request_id": "apr_01",
3
  "tool_call_id": "call_edit_01",
4
  "action_type": "apply_patch",
5
  "reviewer": "user",
6
  "decision": "approved",
7
  "wait_ms": 4210
8
}

Sandbox：

1
{
2
  "mode": "workspace-write",
3
  "allowed_roots": ["orders", "tests/orders"],
4
  "network_access": false
5
}

环境变化：

1
{
2
  "artifact_id": "diff_01",
3
  "state_before": "git:abc123:clean",
4
  "state_after": "git:abc123:modified",
5
  "modified_paths": ["orders/discount.py"],
6
  "forbidden_paths_modified": [],
7
  "diff_ref": "artifact://git-diff/diff_01"
8
}

10.6 测试失败#

第二次测试：

1
test_discount_zero_quantity FAILED

Trace / Event 应保留：

1
tool execution = completed
2
exit_code = 1
3
business outcome = tests_failed
4
agent progress = partial

模型分析后发现第一版 Patch 只修复了折扣上界，没有处理：

1
quantity = 0

这类失败是正常迭代，不应统一计为 Tool Runtime Error。

10.7 网络重试#

第三次模型请求发生 Stream Disconnect。

1
modelop_03
2
├── att_01
3
│   ├── client_request_id = creq_03a
4
│   ├── stream_phase = text_delta
5
│   ├── partial_output_bytes = 630
6
│   └── error = stream_disconnected
7
├── backoff = 1200ms
8
└── att_02
9
    ├── request_id = req_903
10
    ├── usage_complete = true
11
    └── status = completed

如果传输从流式切换为非流式：

1
transport_fallback = true

只有实际 Model / Provider 变化时，才记录：

1
model_fallback = true

10.8 最终结果与环境 Diff#

最终测试：

1
18 passed

Outcome Verifier：

1
{
2
  "evaluation_id": "eval_01",
3
  "task_status": "success",
4
  "tests_passed": true,
5
  "modified_paths": [
6
    "orders/discount.py",
7
    "tests/orders/test_discount.py"
8
  ],
9
  "forbidden_paths_modified": [],
10
  "unexpected_side_effects": false,
11
  "final_diff_ref": "artifact://git-diff/final",
12
  "usage_status": "complete"
13
}

执行链 Mermaid 重建图#

1
sequenceDiagram
2
    autonumber
3
    participant U as User
4
    participant C as Coding Agent
5
    participant M as Model Provider
6
    participant R as Repo / Search
7
    participant S as Shell / Sandbox
8
    participant J as Session Journal
9
    participant O as OTel Backend
10

11
    U->>C: 修复折扣边界错误 + 作用域约束
12
    C->>J: append user message / turn
13
    C->>O: user_prompt / interaction
14

15
    C->>M: modelop_01
16
    M-->>C: Tool Calls: search_code, read_file
17
    C->>R: search / read
18
    R-->>C: code and test files
19
    C->>J: append tool results
20
    C->>O: tool spans / events
21

22
    C->>S: pytest
23
    S-->>C: 1 failed, 17 passed
24
    C->>M: modelop_02 + test result
25
    M-->>C: edit_file patch
26
    C->>O: approval.wait
27
    U-->>C: approve
28
    C->>S: apply patch
29
    S-->>C: diff_01
30
    C->>J: append file change
31

32
    C->>S: pytest
33
    S-->>C: zero_quantity still failed
34
    C->>M: modelop_03 attempt 1
35
    M--xC: Stream disconnect
36
    C->>O: attempt failure + backoff
37
    C->>M: modelop_03 attempt 2
38
    M-->>C: second patch
39
    C->>S: apply patch + pytest
40
    S-->>C: 18 passed
41

42
    C->>J: persist final state
43
    C->>O: final spans / usage
44
    C-->>U: Result + Git Diff

统一时间线#

时间	层	对象	关键 ID	结果
10:00:00	Session	User Message	`msg_u_001`	Task 进入
10:00:01	Event	User Prompt	`prompt_17`	本轮开始
10:00:02	Trace	Model Request	`modelop_01`	生成 Search / Read
10:00:05	Tool	Search / Read	`call_read_01`	成功
10:00:10	Tool	Pytest	`cmd_01`	1 Failed
10:00:16	Approval	Edit	`apr_01`	等待 4.2 秒后批准
10:00:18	Artifact	Git Diff	`diff_01`	修改订单模块
10:00:24	Tool	Pytest	`cmd_02`	仍失败
10:00:27	Network	Model Attempt	`att_01`	Stream Disconnect
10:00:29	Network	Retry Attempt	`att_02`	成功
10:00:35	Tool	Edit	`call_edit_02`	第二次修复
10:00:42	Tool	Pytest	`cmd_03`	18 Passed
10:00:44	Outcome	Environment Verify	`eval_01`	Success

重建程序骨架#

1
def reconstruct_run(
2
    session_rows,
3
    events,
4
    spans,
5
    artifacts,
6
    state_snapshots,
7
):
8
    messages = index_by(session_rows, "message_id")
9
    events_by_prompt = group_by(events, "prompt_id")
10
    events_by_request = group_by_any(
11
        events,
12
        ["request_id", "client_request_id"],
13
    )
14
    events_by_tool = group_by_any(
15
        events,
16
        ["tool_use_id", "call_id"],
17
    )
18
    spans_by_id = index_by(spans, "span_id")
19

20
    graph = build_message_or_item_graph(messages)
21

22
    attach_prompt_groups(
23
        graph,
24
        events_by_prompt,
25
    )
26

27
    attach_model_operations(
28
        graph,
29
        events_by_request,
30
        spans_by_id,
31
    )
32

33
    attach_tool_lifecycle(
34
        graph,
35
        events_by_tool,
36
        spans_by_id,
37
    )
38

39
    attach_artifacts(
40
        graph,
41
        artifacts,
42
        state_snapshots,
43
    )
44

45
    verify_task_contract(graph)
46
    derive_environment_outcome(graph)
47

48
    return graph

重建系统的 Join 优先级应为：

1
稳定 ID
2
→ Parent / Link
3
→ Event Sequence
4
→ 时间窗口

本篇产物#

本文已将四项产物直接嵌入对应章节：

Claude Code 与 Codex 观测模型对照表：第 8.7 节；
Coding Agent 四层记录架构图：第 2.4 节 Mermaid；
Session Record 到 Trace 的映射表：第 4.5 节；
一次 Coding Agent 任务的执行链重建示例：第 10 节。

结语#

Claude Code 与 Codex 的实现开放程度、字段命名和产品结构不同，但它们面对的是同一组工程问题：

1
如何保存本地连续性
2
如何表达 Prompt / Turn
3
如何关联模型和工具
4
如何记录审批和 Sandbox
5
如何从网络失败中恢复
6
如何避免重复副作用
7
如何将本地事实映射到远程 Trace
8
如何在不默认泄露内容的前提下做组织级监控

最值得复用的不是某个产品当前版本的私有字段，而是六条稳定原则。

第一，本地 Session Record 与远程 Telemetry 分工#

1
Session Record：Resume、Fork、上下文恢复
2
OTel：监控、审计、因果和 SLO

第二，Message Parent 与 Span Parent 分开#

1
Message Parent：对话连续性
2
Span Parent：运行因果关系

第三，所有关键对象使用稳定 ID#

1
Prompt
2
Request
3
Attempt
4
Tool Call
5
Artifact
6
Checkpoint
7
Evaluation

第四，Metric 拒绝高基数和原始内容#

高基数 ID 留在 Event / Trace；代码、Prompt 和 Tool Output 进入受控 Artifact。

第五，Approval、Execution 与 Side Effect 分开#

等待用户、工具运行和环境变化不是同一段时间，也不是同一种责任。

第六，Resume 不等于 Exactly-once#

Session 能恢复对话，不代表写工具可以安全重放。外部副作用仍需：

1
Idempotency Key
2
Execution Ledger
3
State Query
4
Compensation
5
Human Review

一个真正可运营的 Coding Agent 观测系统，最终应该能够回答：

1
用户的任务从哪条消息开始
2
经过了哪些模型请求和 Attempt
3
调用了哪些工具
4
谁批准了写操作
5
Shell 和文件环境发生了什么变化
6
网络中断后如何恢复
7
是否发生重复副作用
8
最终 Outcome 是否被环境验证
9
这条链能否安全重放并转成评测样本

当这些问题都有结构化证据时，本地 Session、JSON Event Stream、OpenTelemetry Trace 和环境 Artifact 才真正构成完整的 Coding Agent 运行记录。

文章目标#

1. 分析方法与证据边界#

1.1 官方文档#

1.2 开源代码和公开仓库#

第一类：本地 Rollout 持久化#

第二类：结构化 Exec Event#

第三类：Tool、Shell、文件和 MCP Item#

第四类：OTel 与审批实现#

1.3 可验证运行行为#

1.4 社区源码解析#

1.5 事实、实现推断和设计推测分开标记#

错误写法一：把社区字段写成官方合同#

错误写法二：把 Codex 源码实现写成稳定 JSON Schema#

错误写法三：把设计推断写成产品行为#

2. Coding Agent 为什么需要本地运行记录#

2.1 CLI 生命周期与远程服务不同#

2.2 任务恢复依赖本地状态#

2.3 文件和 Shell 操作需要完整审计#

2.4 本地记录与远程 Telemetry 的职责分离#

3. Claude Code 的观测层次#

3.1 Session Record#

面向普通自动化#

面向故障取证和版本锁定分析#

3.2 Message 与 Parent 关系#

Message Chain#

Trace Parent#

3.3 Model Request#

Transcript#

Event#

Trace#

query_source 的价值#

3.4 Tool Call 与 Tool Result#

Tool Result Event#

3.5 Permission 与 Approval#

3.6 MCP Event#

3.7 Metrics、Events 与 Trace#

Metrics#

Events / Logs#

Trace#

Compaction Event#

4. Claude Code 的任务连续性#

4.1 Session 与 Prompt 关联#

4.2 Tool Result 如何指向发起消息#

Tool 边#

Message 边#

Trace 边#

4.3 Compaction 前后的逻辑父节点#

物理上下文#

逻辑历史#

4.4 Resume 后如何恢复任务#

第一步：恢复 Session State#

第二步：验证 Runtime State#

4.5 本地 JSONL 如何重建完整执行链#

Session Record 到 Trace 的映射表#

重建流程#

不要只靠时间邻近 Join#

5. Codex CLI 的观测结构#

5.1 Session 与任务状态#

后台 Writer#

Thread 与 Session#

5.2 模型流式事件#

Provider / Runtime Stream#

codex exec --json#

Local Rollout JSONL#

5.3 Shell 命令#

Shell Success 与业务成功分开#

5.4 文件读取与补丁修改#

为什么必须有 Environment Diff#

5.5 Tool Approval#

推荐统一字段#

5.6 Sandbox 与权限模式#

5.7 OpenTelemetry 导出#

Logs / Events#

Metrics#

Trace#

内容边界#

6. OpenAI Agents SDK 的 Trace 模型#

6.1 Workflow Trace#

6.2 Agent Span#

6.3 Generation Span#

`query_source` 的价值#

`codex exec --json`#