官方开源的本地编程 Agent

产品定位：本地终端里的 OpenAI 编程 Agent

README 开宗明义：Codex CLI is a coding agent from OpenAI that runs locally on your computer.

安装路径三条：官方 install.sh / npm i -g @openai/codex（codex-cli/package.json）/ Homebrew cask。登录优先 ChatGPT 套餐，也可 API Key。

Rust 工作区地图：126 个 crate，心脏叫 core

根 AGENTS.md 规定：crate 名带 codex- 前缀；抵制继续往 core 塞东西——因为 core 已经太胖。

flowchart TB
      CLI["cli · Multitool"] --> TUI["tui"]
      CLI --> EXEC["exec"]
      CLI --> CORE["core · Session/turn"]
      TUI --> CORE
      EXEC --> CORE
      CORE --> TOOLS["tools · ToolSpec"]
      CORE --> HAND["core/tools/handlers"]
      CORE --> PROTO["protocol"]
      HAND --> SB["sandboxing"]
      SB --> MAC["MacosSeatbelt"]
      SB --> LIN["LinuxSeccomp/Landlock"]
      SB --> WIN["WindowsRestrictedToken"]
      CORE --> ROLL["rollout · sessions"]
      CLI --> APPS["app-server*"]
    

• core/ ~11MB：会话、turn、压缩、工具编排
• tui/ ~14MB：交互面（模块拆分规矩极严）
• cli/：多工具入口
• apply-patch/、linux-sandbox/、login/、rollout/…

Multitool CLI：默认进 TUI，子命令覆盖人生大事

cli/src/main.rs：无子命令时参数转发给交互 TUI；有子命令则走 Subcommand（约 122–211 行）。

Thread · Session · submit

CodexThread::submit（codex_thread.rs:225）把用户操作变成 Op；Session 侧 submit（session/mod.rs:793）进入任务系统。

常规对话任务是 RegularTask（tasks/regular.rs）：发 TurnStarted → 吃掉 startup prewarm → 循环调用 run_turn，直到没有 pending input。

外层 loop 吃的是「用户又插话了」；内层 run_turn 的 loop 吃的是「模型还要工具」。

run_turn：2741 行文件里的那颗心脏

入口：session/turn.rs:153 的 run_turn。文件头注释写清：若模型只要助手消息，记历史后本 turn 完成；若要工具，就继续。

sequenceDiagram
      participant RT as RegularTask
      participant Turn as run_turn
      participant Model as ModelClient
      participant Tools as ToolHandlers
      RT->>Turn: run_turn(input)
      Turn->>Turn: compact / MCP / step_context
      loop sampling_cycle
        Turn->>Model: run_sampling_request
        Model-->>Turn: assistant + tool calls
        Turn->>Tools: dispatch + sandbox + approval
        Tools-->>Turn: observations
      end
      Turn-->>RT: last_agent_message
    

压缩与上下文纪律：写进 AGENTS.md 的工程宪法

根 AGENTS.md:91-100 六条，比任何博客都硬：

1. 禁止改写历史（只增量）
2. 少动前缀，保护 prompt cache
3. 注入项必须有界 + 硬顶
4. 单条不超过 10K tokens
5. >1k tokens 的新条目按 P0 人工审
6. 片段必须是 core/context 里实现 ContextualUserFragment 的结构体

run_turn 开头就跑 run_pre_sampling_compact；另有 remote compact / inline auto compact 家族文件（compact*.rs）。

工具图鉴：Responses API 形状的 ToolSpec

tools/src/tool_spec.rs：Function / Namespace / ToolSearch / WebSearch / Freeform。

核心 handlers（core/src/tools/handlers/mod.rs）包括：

• ShellCommandHandler / ExecCommandHandler（unified_exec）+ WriteStdin
• ApplyPatchHandler
• ViewImageHandler
• PlanHandler、RequestUserInput、RequestPermissions
• MCP + resource 读写、multi_agents、tool_search、plugins…

这与 Claude Code「40+ 细分工具」不同：Codex 更接近 shell 万能胶 + 结构化补丁，再加托管 web_search。

apply_patch：独立 crate + arg0 自调用

codex-apply-patch 解析 patch 语法；进程可通过 argv0=apply_patch（或拼写错误的 applypatch）进入（arg0/src/lib.rs:20-21,98-99）。UNIX 下甚至会在临时目录放 symlink，让 PATH 里能直接敲到。

补丁不是「再开一个 Node 脚本」，而是 同一二进制的第二人格——和 linux-sandbox 的 arg0 技巧同一家族。

三平台沙箱：Seatbelt · Seccomp/Landlock · Windows Token

sandboxing/src/manager.rs:35-40：

pub enum SandboxType {
    None,
    MacosSeatbelt,
    LinuxSeccomp,
    WindowsRestrictedToken,
}

Linux 侧 linux-sandbox 用 landlock ruleset 限制可写根；另有 bwrap 路径。权限画像在 protocol/src/permissions.rs（FileSystemSandboxPolicy / NetworkSandboxPolicy）。

AskForApproval：四档人在回路

protocol/src/protocol.rs:908-931：

默认 OnRequest。非交互 exec 场景常配更激进策略 + 沙箱，而不是把人绑在终端前。

AGENTS.md：从仓库根走到 cwd 的说明书串联

core/src/agents_md.rs：默认文件名 AGENTS.md，本地覆盖 AGENTS.override.md；向上找 project root markers（默认 .git），再向下拼到 cwd。

这本账有三个反直觉的地方

同一目录下谁赢：override 是「替换」不是「合并」

每个目录按 candidate_filenames（agents_md.rs:234-248）的顺序探测， 命中第一个就 return（:220-227）：

names.push("AGENTS.override.md");   // 先
names.push("AGENTS.md");
for candidate in &config.project_doc_fallback_filenames { ... }  // 用户可配的后备名

所以「override」的准确语义是：同目录内 AGENTS.override.md 会让 AGENTS.md 完全失效—— 不是合并、不是追加。但不影响其它目录，链上别的层照常参与。

分隔符只出现一次，别记错

// The project-doc marker tells the model where workspace-scoped
// instructions begin, so it is only needed on the transition
// from user or internal instructions to project instructions.
let separator = if is_project && !previous_was_project { AGENTS_MD_SEPARATOR } else { "\n\n" };

还有一处容易漏：LoadedAgentsMd::text() 有两套出口——多环境（本地 + 远端 exec-server 同时在场）时切到 environment_labeled_text()，因为此时「这条规则属于哪台机器」变成必须表达的信息；单环境才走 legacy_text()。

Skills · Plugins · Hooks

run_turn 在采样前 build_skills_and_plugins；工具路径跑 pre/post tool hooks（registry 里 run_pre_tool_use_hooks）。插件可安装/列举（handlers 里 request_plugin_install / list_available_plugins_to_install）。官方用户文档在 developers.openai.com，仓库 docs/skills.md 只是跳转。

子 Agent：注册表限流 + nickname

agent/registry.rs 在同一用户会话内限制子 agent（thread）数量，并维护 nickname（还可 “the 2nd” 后缀）。spawn depth 有上限检查（exceeds_thread_spawn_depth_limit）。

TUI 与 Exec：一个心脏，两张脸

交互默认 TUI（OpenTUI 风格约束见 AGENTS.md）；codex exec 走非交互（docs/exec.md 外链）。ModeKind 含 Plan / Default（config_types.rs:630）。

App-server · MCP：给编辑器的插座

一簇 app-server* crate 把协议暴露给 IDE/桌面；CLI 也可 mcp-server 把自己当 MCP。这是 Codex 与「纯终端玩具」分道扬镳的地方——协议面一等公民。

认证：ChatGPT · Device Code · API Key

login/：PKCE/OAuth、device code（device_code_auth.rs）、环境变量遥测（是否存在 OPENAI_API_KEY / CODEX_API_KEY）。商业上把 CLI 接到 ChatGPT 套餐，是和 Claude Code 订阅叙事对称的一手。

三方对照：Claude Code · OpenCode · Codex

flowchart TB
      Q["你要什么？"] --> A["官方闭源极致体验"]
      Q --> B["开源多客户端厨房"]
      Q --> C["官方开源 + OS 沙箱"]
      A --> CC["Claude Code"]
      B --> OC["OpenCode"]
      C --> CX["Codex CLI"]
    

场景 A：交互会话里执行 rm -rf build

sequenceDiagram
    participant M as 模型
    participant SH as handlers/shell.rs
    participant OR as ToolOrchestrator
    participant U as 用户
    participant SB as Seatbelt
    M->>SH: shell { command: ["rm","-rf","build"] }
    Note over SH: :108-120 规范化 additional permissions
    Note over SH: :122-138 抬权守卫（本例没抬权，放行）
    Note over SH: :140-156 intercept_apply_patch → 不是补丁，继续
    SH->>OR: ShellRequest
    OR->>OR: default_exec_approval_requirement
OnRequest × Restricted → NeedsApproval
    OR->>U: 审批请求
    U-->>OR: ApprovedForSession
    Note over OR: with_cached_approval :71 按 key 记住
    OR->>SB: SandboxAttempt（NoOverride）
    SB-->>OR: 成功 / 拒绝
    Note over OR: 若拒绝且可升级 → escalated retry，不再问人
    

场景 B：上下文将爆窗时的 mid-turn 压缩

模型刚返回一批工具调用，needs_follow_up = true，同时 token_limit_reached = true。 于是 turn.rs:419：

let should_roll_over = needs_follow_up
    && (sess.take_new_context_window_request().await || token_limit_reached);

进入 run_auto_compact(CompactionPhase::MidTurn)，注入策略 BeforeLastUserMessage，压缩后 can_drain_pending_input = !model_needs_follow_up，然后 continue。

顺带对照：Part II 讲过还有 pre-turn 压缩（run_pre_sampling_compact @983）和 previous-model inline 压缩（maybe_run_previous_model_inline_compact @1051，换模型或 comp_hash 变了时用旧模型做兼容压缩）。 三种压缩，三个时机。

场景 C：stop hook 要求续跑

模型说完了，不再要工具，needs_follow_up = false。按常规该 break——但 turn.rs:461-510 还要过一关：

用上面的 LAB 03 把 should_block 打开、有 continuation prompt 关掉，就能看到这一格。

场景 D：CI 里跑 codex exec