AI Research 技术调研

Codex CLI (OpenAI)：Rust 单体仓库 + 官方设计文档站双源 agent harness

27分钟阅读

Codex CLI (OpenAI)

一句话定位

Codex CLI 是 OpenAI 的官方编码 agent harness：真正的实现是 Rust 单体仓库 codex-rs/（codex-cli/ 只是发行用的 npm 薄壳），配一个信息量远超仓库内 docs/ stub 的官方设计文档站 developers.openai.com/codex/*；工程上以极细粒度的 crate 拆分著称——工具、记忆、多 agent、沙箱、安全审查各自独立成 crate，并罕见地在 OSS harness 里自带一个 LLM 审查官（“Guardian”）和一套本地化、明确声明”never uploaded”的 trace/reduce 可观测系统。

核心架构总览

仓库为 monorepo，clone 于 2026-07-07，精确 commit 8268cbfb0e5f39cb4efff928264fe8f29ddacafb（作者提交时间 2026-07-06 10:27:39 -0700，日更新的活跃仓库）。

codex/ (monorepo)
├── codex-rs/           — 真正的实现所在地
│   ├── core/           — agent 核心：tasks/、session/、tools/、context/、
│   │                      compact*.rs、guardian/、safety.rs、skills.rs、plugins/、agent/
│   ├── codex-mcp/      — MCP 客户端聚合层（connection_manager.rs、rmcp_client.rs）
│   ├── memories/       — 长期记忆两阶段流水线（独立 crate 家族）
│   ├── rollout/        — 会话/轨迹持久化（SQLite 索引、压缩、搜索、resume/fork）
│   ├── rollout-trace/  — 本地 trace/reduce 可观测系统
│   ├── otel/           — OpenTelemetry 指标/trace 导出
│   ├── sandboxing/     — 跨平台沙箱抽象（Seatbelt/bwrap+Landlock/Windows）
│   ├── exec-server/    — Noise 协议加密的远程执行 crate
│   ├── app-server/     — JSON-RPC 2.0 控制协议（thread/turn 生命周期）
│   ├── models-manager/ — 模型清单/切换
│   ├── code-mode*/     — 嵌套 JS 工具执行运行时（本次未深读，见文末）
│   ├── chatgpt/、cloud-tasks*/、connectors.rs — Apps/连接器生态（本次未深读）
│   ├── keyring-store/、secrets/ — 密钥相关 crate（本次未深读）
│   └── execpolicy/、execpolicy-legacy/ — 命令允许/拒绝规则引擎（本次未深读）
├── codex-cli/          — npm 发行薄壳（bin/、package.json），承载编译好的 Rust 二进制
├── sdk/                — TypeScript/Python SDK，通过 JSON-RPC 对接本地 `codex app-server`
├── docs/                — 仓库内 docs 多为 3 行 stub，指向下面的官方文档站
└── AGENTS.md            — 仓库根的贡献者规范，同时充当架构文档（crate 边界、
                            "no history rewrite"、context 注入必须走 ContextualUserFragment 等硬约束）

一手信息源的特殊结构：官方文档站 developers.openai.com/codex/* 是一等设计文档 （subagents、plugins、skills、memories、permissions、hooks、sandboxing、app-server 协议、SDK 均有详细页面），信息密度远超仓库内 docs/ 的 stub，本次已用 CloakBrowser 抓取 11 篇存档于 key-files/。以下各节的论断同时引用源码文件路径与 这些文档页面。

Agent Loop（主循环 / 何时继续何时停）

双层循环结构：

  • 外层：core/src/tasks/regular.rs（RegularTask::run）——“只要还有 pending input 就继续跑”的驱动循环；core/src/tasks/mod.rs 定义 SessionTask trait、 Session::spawn_task/start_task，负责 turn 生命周期、abort 处理、以及 analytics_events_client.track_turn_profile/track_turn_token_usage 的 token 用量遥测发射。
  • 内层：core/src/session/turn.rs::run_turn()（全文件 2405 行）——真正的 agent 单轮循环：采样请求 → 工具调用或产出消息 → 继续/停止判定，pre-turn 与 mid-turn 两处都会触发 auto-compact（run_pre_sampling_compact 等），并与 hook 系统深度耦合（Stop hook 可以注入 developer message 强制继续，而非简单 拦截）。build_prompt() 在此文件内组装最终发往模型的 Prompt 结构。
  • core/src/tasks/lifecycle.rs 负责 turn start/stop/abort/error 的生命周期 hook 发射。
  • 支持”steering”：用户消息可以在 turn 进行中到达并被 pending-input 排队机制 接纳，而不必等当前 turn 完全结束。

未验证细节：run_turn 中断层调用关系（何时触发 remote compact vs local compact）仅读到函数入口与触发点，未逐行跟踪全部分支。

记忆与上下文管理（压缩、长期记忆、会话持久化）

三层结构，是本次调研中信息密度最高的维度：

  1. Turn 内历史：core/src/context_manager/history.rs/normalize.rs/ updates.rs ——append-only、增量构建的对话历史，AGENTS.md 明确写死 “No history rewrite - the context must be built up incrementally” 的 硬约束。
  2. 压缩（compaction）：core/src/compact.rs、compact_remote.rs、 compact_remote_v2.rs、compact_token_budget.rs ——本地/模型侧远程/ 远程 v2/token-budget 限定四种变体，分别在 session/turn.rs 的 pre-turn 和 turn 内循环触发；session/context_window.rs、token_budget.rs、 rollout_budget.rs 做 token 窗口记账（“距压缩还剩多少 token”提示）。
  3. 会话持久化：rollout/src/ ——RolloutRecorder、state_db.rs （SQLite 索引）、compression.rs、list.rs（线程列表/resume）、 search.rs（全文搜索），是 thread/resume、thread/fork（app-server 协议）的底层支撑。
  4. 长期记忆流水线（memories/ crate 家族，默认关闭，需 [features] memories = true opt-in；EEA/英国/瑞士因监管要求强制显式 opt-in）——两阶段设计（memories/README.md 存档于 key-files/memories_README.md）：
    • Phase 1（逐 rollout 抽取）：异步后台任务从状态库认领可处理的空闲 rollout，逐个送模型抽取，期望结构化输出（raw_memory、 rollout_summary、可选 rollout_slug），做密钥脱敏后入库；有限并发 + lease/claim 防重复认领，失败走退避重试。Prompt 模板存档于 key-files/memories_stage_one_system.md。
    • Phase 2（全局整合）：单一全局锁；按 usage_count/recency 加载有限 数量的 Phase 1 输出；把文件系统产物（raw_memories.md、 rollout_summaries/）同步进一个带 git baseline（~/.codex/memories/.git） 的工作区，算出 phase2_workspace_diff.md；随后启动一个内部整合 sub-agent（无审批、无网络、仅限本地写入、collab 关闭以防递归委派） 改写更高层的 MEMORY.md/memory_summary.md/skills/；成功后重置 git baseline。Prompt 模板存档于 key-files/memories_consolidation.md。
    • 读路径：memories/read/ 把已有记忆作为 developer instruction 注入， 解析记忆引用，记录读用量遥测；模型可见工具在 ext/memories/ （tools/list.rs、search.rs、read.rs、ad_hoc_note.rs）。
    • 配置项：memories.generate_memories、memories.use_memories、 memories.disable_on_external_context、 memories.min_rate_limit_remaining_percent、memories.extract_model、 memories.consolidation_model。
    • 文档中提到 codex/memories/chronicle（“帮 Codex 从你的屏幕恢复最近工作 上下文”，疑似截屏关联功能）未抓取验证，标注存疑。

工具体系（定义/调用协议/注册/权限）

  • 调度层：core/src/tools/router.rs（ToolRouter、 ToolCall::build_tool_call，把 ResponseItem::FunctionCall/ CustomToolCall/ToolSearchCall 解析成可分发的 ToolCall；已存档于 key-files/tools_router.rs）+ core/src/tools/registry.rs（注册、暴露 规则、并发调用支持标志，含 registry_tests.rs）+ core/src/tools/orchestrator.rs/parallel.rs（ToolCallRuntime，并发 工具执行）。
  • 决策哪些工具对模型可见：core/src/tools/spec_plan.rs::build_tool_router ——按 feature flag、tool_suggest、apps_enabled 逐 turn 决定。
  • 内置工具 handler（core/src/tools/handlers/，约 30 个文件）： shell/、apply_patch.rs（+ .lark 语法）、unified_exec/、mcp.rs、 mcp_resource.rs、plan.rs（update_plan 工具）、 multi_agents_v2/（子 agent 工具族）、agent_jobs.rs/ agent_jobs_spec.rs（CSV 批量 fan-out）、request_permissions.rs、 request_user_input.rs、tool_search.rs、view_image.rs、 get_context_remaining.rs、new_context_window.rs、sleep.rs、 wait_for_environment.rs。
  • 实际 OS 执行层（与调度层分离）：core/src/tools/runtimes/ （shell/、apply_patch.rs、unified_exec.rs）。
  • MCP 聚合：codex-mcp/src/connection_manager.rs （McpConnectionManager：持有各 MCP server 名下的异步 RMCP 客户端，跨 server 聚合 tools/resources、路由调用、tool_is_model_visible 可见性 过滤——AGENTS.md 明确要求新增能力应扩展这个抽象而非在调用点直接插入代码）； rmcp_client.rs、elicitation.rs、auth_elicitation.rs 处理 MCP OAuth/elicitation 流程。
  • 未深读：code-mode/code-mode-host/code-mode-protocol（嵌套 JS 代码 执行工具运行时，仅在顶层目录列表中见到）。

Prompt 设计（系统提示结构、动态组装）

  • 按模型/模型族的基础系统提示文件：core/gpt_5_2_prompt.md、 gpt_5_1_prompt.md、gpt_5_codex_prompt.md、 gpt-5.2-codex_prompt.md、gpt-5.1-codex-max_prompt.md、 prompt_with_apply_patch_instructions.md（均按当前激活模型选择/渲染， 已存档 4 份于 key-files/prompt_gpt_5_1.md、prompt_gpt_5_2.md、 prompt_gpt_5_2_codex.md、prompt_gpt_5_codex.md）。文件体量差异明显： 通用 gpt_5_x 系列约 300 行级别，-codex 后缀变体明显更精简（约 80 行 级别），提示这些”-codex”模型把更多 harness 侧行为内化进了模型本身。
  • 动态上下文片段注入：core/src/context/（约 35 个文件），每个实现 ContextualUserFragment trait（AGENTS.md 明文要求：“All injected fragments must be defined as structs in core/context and implement ContextualUserFragment trait”）：apps_instructions.rs、 available_plugins_instructions.rs、available_skills_instructions.rs、 collaboration_mode_instructions.rs、current_time_reminder.rs、 environment_context.rs、personality_spec_instructions.rs、 permissions_instructions.rs、subagent_notification.rs、 token_budget_context.rs、turn_aborted.rs、user_instructions.rs 等。
  • 最终组装函数：core/src/session/turn.rs::build_prompt()——产出发往 模型的 Prompt 结构（input、tools、base_instructions、 output_schema）。
  • 其他任务专用模板（未深读，仅记录路径）： prompts/templates/compact/prompt.md、 prompts/templates/realtime/backend_prompt.md、 core/templates/collab/experimental_prompt.md、 models-manager/prompt.md、tui/prompt_for_init_command.md。
  • core/src/agents_md.rs/agents_md_manager.rs——负责发现/合并仓库自带的 AGENTS.md（用户项目里的指令文件，与 harness 自己的贡献者规范文件同名但 不是同一个东西）。

Router / 编排（任务分解、多 agent、子 agent）

  • v2 子 agent 工具面（当前主用）：core/src/tools/handlers/multi_agents_v2/ ——spawn.rs（spawn_agent 工具，已存档）、send_message.rs、 wait.rs、interrupt_agent.rs、list_agents.rs、followup_task.rs、 message_tool.rs（mod 文件已存档于 key-files/multi_agents_v2.rs）。
  • v1（legacy）：multi_agents.rs、multi_agents_common.rs，仍与 v2 并存，由 MultiAgentVersion 枚举决定当前生效版本。
  • Agent 控制层：core/src/agent/ ——control.rs/control_tests.rs （spawn/fork 控制，SpawnAgentForkMode）、registry.rs（活跃 agent 线程注册表）、role.rs（角色应用）、agent_resolver.rs、status.rs、 builtins/（awaiter.toml、explorer.toml 内置角色定义）。
  • 批量 fan-out：core/src/tools/handlers/agent_jobs.rs/ agent_jobs_spec.rs（spawn_agents_on_csv/report_agent_job_result， 按文档标注为 experimental，后端为 sqlite_home）——CSV 逐行转子 agent 的 批处理 fan-out。
  • 官方文档（doc_subagents.md）核实的具体约束：内置 agent 角色为 default/worker/explorer；自定义 agent 是独立 TOML 文件，放在 ~/.codex/agents/（个人）或 .codex/agents/（项目），必填字段 name/description/developer_instructions；全局上限 agents.max_threads（默认 6）、agents.max_depth（默认 1——刻意浅化以 限制 fan-out 的成本/延迟爆炸）、agents.job_max_runtime_seconds；子 agent 继承父线程的实际生效沙箱/审批覆盖，即便自定义 agent 文件里 写了不同默认值；非活跃子线程发出的审批请求可以带来源线程标签浮现给用户， 非交互流程下需要新审批的动作会直接失败（不会静默降级放行）。
  • trace 关联：rollout-trace/README.md 记载 multi-agent-v2 子线程共享 同一根 trace writer/bundle——spawn/task/result/close 工具调用在归约后的 trace 图里变成 InteractionEdge。

Skill / 插件体系

  • Skill 加载：core/src/skills.rs（core 内的扫描入口）+ core-skills/src/injection/（session/turn.rs 中引用为 codex_core_skills::injection::InjectedHostSkillPrompts，负责 turn 构建期的 skill prompt 注入）+ core/src/mcp_skill_dependencies.rs （skill 可声明 MCP 工具依赖，agents/openai.yaml 里 dependencies.tools[].type = "mcp"，触发自动安装提示）。
  • 官方文档（doc_skills.md）核实的规格：skill = 目录，必须含 SKILL.md（name+description frontmatter），可选 scripts/、references/、assets/、agents/openai.yaml；构建在 开放 agent-skills 标准（agentskills.io）之上——与 Claude 的 skill 同属一个规范家族。渐进式披露：初始只加载 name+description+path， 完整 SKILL.md 仅在被选中时加载；初始 skill 列表预算为上下文窗口的 ≤2% 或 8000 字符（取较严格者），超预算时先缩短描述、再省略部分 skill。两种调用方式：显式（$skill-name 或 /skills）或隐式（描述 匹配）。作用域与优先级：REPO（$CWD/.agents/skills、父目录、仓库根） → USER（$HOME/.agents/skills）→ ADMIN（/etc/codex/skills）→ SYSTEM（内置，如 skill-creator）；跨作用域同名 skill 不合并，各自 作为独立可选条目出现。config.toml 中的 [[skills.config]] 可按路径 禁用某 skill 而不删除。agents/openai.yaml 可选元数据： interface.*（展示名/图标/提示）、 policy.allow_implicit_invocation（默认 true）、dependencies.tools。
  • 插件：core/src/plugins/——discoverable.rs、injection.rs、 mentions.rs（plugin:// mention 解析）、render.rs、mod.rs； core-plugins crate 的 RecommendedPluginCandidatesInput 用于 session/turn.rs::built_tools() 的工具推荐/插件发现流程。文档 （doc_plugins.md）确认：插件打包 skills + app 连接器映射 + MCP server 配置 + 展示资源，经市场源（基于仓库）分发；安装方式为 Codex app 内 “Plugins” 页或 CLI /plugins；config.toml 里逐插件 enabled = false 可禁用而不卸载。插件自带 hooks 默认在插件根目录 hooks/hooks.json，可被 .codex-plugin/plugin.json 清单的 hooks 字段覆盖；hook 命令拿到 PLUGIN_ROOT/PLUGIN_DATA 环境变量，同时也 设置 CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA（与 Claude Code 插件 hook 生态的显式互操作细节）。
  • Skill 与 Plugin 的关系：skill 是创作格式，plugin 是可分发的安装 单元（一个 plugin 可打包 ≥1 个 skill + apps + MCP servers）。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

  • 没有 RL/权重微调闭环，没有 eval 门控的代码自动合并，源码中也未发现 harness 在运行时修改自身源码或提示词的证据。“自进化”完全停留在 用户记忆/skill 库层面，不涉及模型权重或 harness 代码本身。
  • Memory Phase 2 整合（见”记忆”节）本身构成一种温和的自我改进状态： 内部 sub-agent 定期基于累积会话证据改写 MEMORY.md/skills/。
  • Record & Replay（文档 doc_record_replay.md，仅 macOS，需 Computer Use）：用户通过屏幕/操作录制演示一个工作流；Codex 检查录制内容并起草一个 可复用 Skill（何时使用、输入、步骤、验证方式）——这是本 harness 里最接近 “从演示自主生成能力”的机制。
  • 文档导航中出现 codex/learn/best-practices、“Build an Agent Improvement Loop with Traces, Evals, and Codex” 等 cookbook 链接，但这些是给用户 自建 eval 闭环的外部指导，不是内置于 harness 本体的能力，未抓取验证。

可观测性（日志 / trace 格式）

  • 标准遥测：otel/src/——provider.rs、otlp.rs（OpenTelemetry OTLP 导出）、metrics/、events/、trace_context.rs、targets.rs； TurnProfileFact/TurnTokenUsageFact 逐 turn 追踪（tasks/mod.rs 中的 analytics_events_client.track_turn_profile/track_turn_token_usage）。
  • 本地专有 trace 系统：rollout-trace/ crate（README 全文存档于 key-files/rollout_trace_README.md）——本地专用、opt-in，文档原话 明确”not telemetry”（从不上传，只在设置环境变量 CODEX_ROLLOUT_TRACE_ROOT 时才写入）。设计理念”observe first, interpret later”：热路径只写原始有序事件（trace.jsonl）+ payload 引用 （payloads/*.json）+ manifest.json；一个离线确定性归约器 （replay_bundle，通过 codex debug trace-reduce <bundle> 调用）把 这些原始数据转换成带 ConversationItem/ToolCall/CodeCell/ TerminalOperation/InferenceCall/Compaction/InteractionEdge 节点的语义图 state.json。multi-agent-v2 的子线程共享根 bundle，因此 整棵 agent 树可归约进同一张图。归约器不变量：严格 seq 顺序、 payload-before-event、单次 replay 内 ID 稳定、运行时 payload 被当作 “证据而非模型确实看到相同字节的证明”。
  • codex debug trace-reduce——归约器的 CLI 入口。
  • app-server 协议（文档 doc_app_server.md，源码在 codex-rs/app-server/）本身也是一个结构化的可观测/控制面：JSON-RPC 2.0 over stdio/websocket/unix-socket；thread/start|resume|fork、 turn/start|steer|interrupt，流式通知 item/started、item/completed、item/agentMessage/delta、 turn/completed、thread/archived；版本化 schema 生成 （codex app-server generate-ts --out ./schemas、 generate-json-schema）；WebSocket 传输支持能力令牌或签名 bearer token 鉴权；入站队列有界，过载时返回 JSON-RPC 错误 -32001。

安全与权限（审批门、密钥管理）

  • 静态预检：core/src/safety.rs（全文件存档）—— assess_patch_safety()：对 apply_patch 调用做执行前静态检查，产出 SafetyCheck::{AutoApprove, AskUser, Reject}，判断依据是补丁是否完全 局限于沙箱可写路径、当前 AskForApproval 策略、以及 PermissionProfile 变体（Disabled/External/Managed）；同时防范从可写根目录发起的 硬链接逃逸。
  • 审批策略：protocol/src/protocol.rs 中 enum AskForApproval { UnlessTrusted, OnRequest (default), Granular(...), Never } （通过 grep 确认变体存在，行号约 901）。
  • “Guardian” LLM 自动审查代理（core/src/guardian/，mod.rs + policy.md 全文存档）——这是本次调研发现的最独特安全机制：
    • mod.rs 文档注释描述流程：重建一个保留用户意图与近期上下文的精简 transcript → 发给专用 guardian 审查会话要求严格 JSON 判定 → 超时/执行失败/输出畸形一律 fail closed → 应用明确的允许/拒绝结果。
    • GuardianAssessment { risk_level, user_authorization, outcome, rationale }； 超时 GUARDIAN_REVIEW_TIMEOUT = 90s；熔断器 （MAX_CONSECUTIVE_GUARDIAN_DENIALS_PER_TURN = 3、 MAX_RECENT_AUTO_REVIEW_DENIALS_PER_TURN = 10，50 次动作滑动窗口） 防止对审查器的连续轰炸。
    • policy.md（逐字存档于 key-files/guardian_policy.md，文档中标注 “企业可用 guardian_policy_config 替换其中的租户专属部分”）定义了 风险分类法：Data Exfiltration、Credential Probing、Persistent Security Weakening、Destructive Actions、Low-Risk Actions，每类附带明确的 允许/拒绝规则与实例（例如”即使 user_authorization = high 也要拒绝泄露密钥的动作”；“向已验证的 feature 分支强制推送 = medium 风险；向受保护/默认分支强制推送 = high/critical”）。
    • 通过 approvals_reviewer = "auto_review" 启用（仅在审批策略为交互式， 如 on-request 或 granular 时生效）；在 Codex app 中以 Reviewing/Approved/Denied/Aborted/Timed out 状态呈现。
  • 权限配置（文档 doc_approvals_security.md/doc_permissions.md）： [permissions.<name>] 定义文件系统规则（:root、:minimal、 :workspace_roots、精确路径、带 glob_scan_max_depth 的拒绝 glob 预 展开上限）与网络规则（enabled、domains 允许/拒绝列表，支持精确/ *./**./全局 * 通配，deny 始终优先，DNS-rebinding 防护通过尽力 而为的解析分类，allow_local_binding 默认 false，Unix socket 白名单，dangerously_allow_non_loopback_proxy/ dangerously_allow_all_unix_sockets 逃生舱）；即使在 workspace-write 下，<root>/.git、<root>/.agents、<root>/.codex 始终只读（递归 生效，含解析 gitdir: 指针文件）；文档给出常见组合表（Auto = workspace-write + on-request；只读浏览；只读非交互 CI --sandbox read-only --ask-for-approval never；workspace-write + 仅对不受信提示；Auto-review 模式；--yolo/ --dangerously-bypass-approvals-and-sandbox 全绕过，文档明确标注 “Elevated Risk… not recommended”）。网页搜索默认走 OpenAI 维护的 缓存索引（web_search = "cached"），专门用来降低来自实时网页的 prompt injection 暴露面；--yolo 会切回实时搜索；也可完全禁用。
  • 密钥/凭证：未发现独立的”密钥管理”子系统，仅有 MCP server 认证 （bearer_token_env_var、codex mcp login 走 OAuth，keyring 后端存储， 见 codex-rs/keyring-store/）和 hook/插件的哈希信任评审（见下）； secrets/ crate 存在于目录列表但本次未深读，无法给出更完整结论。
  • Hooks（文档 doc_hooks.md；源码 core/src/hook_runtime.rs，session/turn.rs 中多处引用 inspect_pending_input、record_pending_input、 run_pending_session_start_hooks、run_turn_stop_hooks、 run_legacy_after_agent_hook）：确定性脚本注入点覆盖 PreToolUse、PermissionRequest、PostToolUse、PreCompact、 PostCompact、UserPromptSubmit、SubagentStop、Stop（turn 级）以及 SessionStart、SubagentStart（线程/子 agent 级）；配置来自 hooks.json 或内联 [hooks] TOML；matcher 是对事件名的正则； 非托管 hook 必须先经用户按哈希显式信任（/hooks CLI 命令）才能 执行；企业侧 requirements.toml 可注入”托管”hook，预先受信且不可禁用， allow_managed_hooks_only = true 可压制所有非托管来源。与 Claude Code 的 hook 系统共享 hook 形状，甚至共用环境变量别名 （CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA）以实现互操作。

沙箱与执行隔离

  • 跨平台沙箱抽象：sandboxing/src/：
    • macOS：seatbelt.rs + seatbelt_base_policy.sbpl + seatbelt_network_policy.sbpl + restricted_read_only_platform_defaults.sbpl（已存档验证为真实的 Apple Seatbelt SBPL 语法，(deny default) 闭合默认策略，注释中 明确引用了 Chromium 沙箱策略作为建模来源）。
    • Linux：bwrap.rs/landlock.rs，经 linux-sandbox/ crate （bundled_bwrap.rs、bazel_bwrap.rs）；另有 bwrap/ crate 自行 vendor/构建 bubblewrap（build.rs、config.h）。
    • Windows：windows.rs（原生 Windows 沙箱）。
    • manager.rs（get_platform_sandbox、SandboxType 分发）、 policy_transforms.rs、denial.rs。
  • fail-closed 强制：文档明确”若目标平台沙箱无法强制执行所选策略， Codex 拒绝运行该命令而不是静默无沙箱运行”（macOS）；Linux 用 bwrap+seccomp，Landlock 作为兼容性回退；Windows 分 elevated （专用低权限沙箱用户 + 防火墙）与 unelevated（更弱，遇到不支持的 分裂策略直接拒绝）。
  • 远程执行 crate：exec-server/——独立协议：client/、server/、 noise_channel.rs/relay_noise_tests.rs（Noise 协议加密通道）、 remote_process.rs/remote_file_system.rs/remote.rs、 process_sandbox.rs、websocket_pong_watchdog.rs——让 Codex 可以在 与 agent 核心不同的远程/异构 OS 环境中执行（AGENTS.md 中提及 “foreign app/exec OSes”、TestCodexBuilder::build_with_auto_env()）。
  • CLI 调试工具：codex sandbox {macos,linux,windows}（别名 codex debug）可干跑某命令在当前沙箱策略下会被允许什么， --log-denials；codex sandbox seatbelt/codex sandbox landlock 别名在文档中确认。
  • 未深读：Windows 原生沙箱内部实现细节（windows-sandbox-rs/），仅通过 文档了解，未读源码。

与模型的协同设计

  • 按模型/模型族的独立系统提示文件（见”Prompt 设计”节）本身就是最直接 的模型协同设计证据：-codex 后缀模型的 harness 侧提示明显更精简，暗示 这些模型把更多 agentic 行为内化在权重里。
  • models-manager/ crate + models-manager/prompt.md——动态模型 清单/选择/切换，SharedModelsManager 贯穿 core/src/session/。
  • client.rs/client_common.rs（core/src/）——ModelClientSession、 Prompt 结构（input、tools、parallel_tool_calls、 base_instructions、output_schema），是真正发往模型的线上数据形状， 在 session/turn.rs::build_prompt() 里逐次采样请求构建一次。
  • apply_patch 是显式的 freeform（非 JSON 包装）工具——gpt_5_2_prompt.md 第 118 行原文：“This is a FREEFORM tool, so do not wrap the patch in JSON”，这是针对模型输出格式的专门适配。配套 codex-rs/core/src/tools/handlers/apply_patch.lark——一个真实的 Lark 语法文件，用于解析模型输出的补丁格式，即自定义非 JSON 语法与模型输出 格式的联合设计。
  • Reasoning-effort 是一等公民：turn_context.effective_reasoning_effort_for_tracing()、 自定义 agent TOML 中的 model_reasoning_effort 贯穿 turn/session 代码， 确认这是与通用”temperature”旋钮不同的、reasoning-effort 感知的协同设计。

轨迹利用（session/trajectory 是否反哺训练/评测）

  • Rollout（rollout/ crate）把每个会话持久化为可 resume/fork/全文搜索的 磁盘轨迹（SESSIONS_SUBDIR/ARCHIVED_SESSIONS_SUBDIR 常量暗示落盘于 ~/.codex/sessions），用于 thread/resume、thread/fork、 search_rollout_matches，也是 Memories Phase 1 流水线的直接输入 （每个符合条件的空闲 rollout 被摘要为一条记忆）。
  • rollout-trace 明确声明本地专用、从不上传——文档原话”Rollout tracing is not telemetry… Codex does not upload or report these traces.” 这直接回答了”轨迹是否自动反哺训练/评测”的问题：在这个 OSS 仓库范围内 没有发现自动上传轨迹供 OpenAI 训练/评测流水线使用的证据。发现的轨迹 自动复用只有三处：(a) 本地可恢复性；(b) 本地记忆生成（Phase 1/2，完全 本地、用户可控、脱敏、opt-in）；(c) 本地调试 trace-replay （codex debug trace-reduce）。分析事件 （codex-analytics crate 中的 analytics_events_client.track_turn_profile/track_turn_token_usage/ track_app_mentioned/track_plugin_used）确实上报结构化的用量事实 （token 计数、工具调用计数、feature flag），但这些是指标/遥测，不是 原始轨迹内容——没有发现任何上传完整对话轨迹用于模型训练的代码路径。 （告诫：这仅是基于 OSS 代码的推断；OpenAI 对提交给其 API 的数据在服务端 的处理方式超出本仓库范围，无法从源码验证。）

与同类 harness 的关键差异（1-3 条）

  1. “Guardian” LLM 自动审查代理是本次调研中独一份——不是简单的规则型 审批门，而是一个带完整风险分类政策文档（guardian/policy.md）、 fail-closed 语义、熔断器的专用审查 sub-agent，企业还可替换租户专属 政策段落。
  2. **长期记忆的两阶段设计（per-rollout 抽取 + 全局整合 sub-agent + git baseline diff）**在深度上明显超过一般 harness 的”简单摘要写入 memory 文件”模式，且默认关闭、EEA 强制 opt-in 体现了合规导向。
  3. rollout-trace 明确以文档形式声明”never uploaded”，这种把隐私承诺 写进架构文档而非仅写进隐私政策的做法，在同类 harness 里较少见； 与之相对，Memories/Guardian/Hooks 等能力本身又相当激进（模型自动 审查其他调用、模型自我改写记忆），形成”强能力 + 强本地化承诺”并存的 设计取向。更完整的跨 harness 对比留待 synthesis 阶段。

原始源码定位

  • repo: https://github.com/openai/codex
  • commit/version analyzed: 8268cbfb0e5f39cb4efff928264fe8f29ddacafb（2026-07-06 提交，2026-07-07 clone/分析）
  • 关键文件列表（相对 codex-rs/ 仓库根，除非另有说明）：
    • core/src/tasks/mod.rs、core/src/tasks/regular.rs、core/src/tasks/lifecycle.rs
    • core/src/session/turn.rs、core/src/session/turn_context.rs、core/src/session/step_context.rs
    • core/src/tools/router.rs、core/src/tools/registry.rs、core/src/tools/orchestrator.rs、core/src/tools/parallel.rs、core/src/tools/spec_plan.rs
    • core/src/tools/handlers/（约 30 个文件，含 multi_agents_v2/、agent_jobs.rs、apply_patch.rs/.lark）
    • core/src/tools/runtimes/
    • codex-mcp/src/connection_manager.rs、rmcp_client.rs、elicitation.rs、auth_elicitation.rs
    • core/gpt_5_2_prompt.md、gpt_5_1_prompt.md、gpt_5_codex_prompt.md、gpt-5.1-codex-max_prompt.md、gpt-5.2-codex_prompt.md
    • core/src/context/（约 35 个文件）
    • core/src/compact.rs、compact_remote.rs、compact_remote_v2.rs、compact_token_budget.rs
    • core/src/context_manager/history.rs、normalize.rs、updates.rs
    • rollout/src/（state_db.rs、compression.rs、list.rs、search.rs）
    • memories/README.md、memories/write/templates/memories/stage_one_system.md、consolidation.md、memories/read/、ext/memories/
    • core/src/agent/（control.rs、registry.rs、role.rs、agent_resolver.rs、status.rs、builtins/）
    • core/src/tools/handlers/multi_agents_v2/、multi_agents.rs、multi_agents_common.rs
    • core/src/skills.rs、core-skills/src/injection/、core/src/mcp_skill_dependencies.rs
    • core/src/plugins/（discoverable.rs、injection.rs、mentions.rs、render.rs）
    • otel/src/、rollout-trace/（README.md）
    • core/src/guardian/（mod.rs、policy.md）、core/src/safety.rs、protocol/src/protocol.rs
    • sandboxing/src/（seatbelt.rs、*.sbpl、bwrap.rs、landlock.rs、windows.rs、manager.rs）
    • exec-server/（client/、server/、noise_channel.rs）
    • app-server/（JSON-RPC 协议实现）
    • models-manager/、client.rs、client_common.rs
    • AGENTS.md（仓库根）

一手源存档（sources/）

/Users/zhao/projects/self-wiki/ai-research/sources/harness/codex-cli/：

  • NOTES.md — 调研笔记全文（本 dossier 的直接依据）
  • key-files/doc_app_server.md — 官方文档：app-server JSON-RPC 协议
  • key-files/doc_approvals_security.md — 官方文档：审批与安全
  • key-files/doc_hooks.md — 官方文档：hooks 系统
  • key-files/doc_mcp.md — 官方文档：MCP
  • key-files/doc_memories.md — 官方文档：memories 概览
  • key-files/doc_permissions.md — 官方文档：权限配置
  • key-files/doc_plugins.md — 官方文档：插件
  • key-files/doc_record_replay.md — 官方文档：Record & Replay
  • key-files/doc_sdk.md — 官方文档：SDK
  • key-files/doc_skills.md — 官方文档：skills
  • key-files/doc_subagents.md — 官方文档：subagents
  • key-files/guardian_mod.rs — core/src/guardian/mod.rs 源码
  • key-files/guardian_policy.md — core/src/guardian/policy.md（默认审查政策原文）
  • key-files/memories_README.md — memories/README.md
  • key-files/memories_consolidation.md — Phase 2 整合 prompt 模板
  • key-files/memories_stage_one_system.md — Phase 1 抽取 prompt 模板
  • key-files/multi_agents_v2.rs — tools/handlers/multi_agents_v2/mod.rs
  • key-files/multi_agents_v2_spawn.rs — tools/handlers/multi_agents_v2/spawn.rs
  • key-files/prompt_gpt_5_1.md、prompt_gpt_5_2.md、prompt_gpt_5_2_codex.md、prompt_gpt_5_codex.md — 各模型基础系统提示
  • key-files/rollout_trace_README.md — rollout-trace/README.md
  • key-files/safety.rs — core/src/safety.rs
  • key-files/seatbelt_base_policy.sbpl — macOS Seatbelt 基础策略
  • key-files/session_turn.rs — core/src/session/turn.rs（2405 行全文）
  • key-files/tasks_mod.rs — core/src/tasks/mod.rs
  • key-files/tasks_regular.rs — core/src/tasks/regular.rs
  • key-files/tools_router.rs — core/src/tools/router.rs

关系图谱

反向链接