codex 学习笔记

Appearance

非交互模式 — 概念 ​

Exec 模式架构 ​

Exec 模式是 Codex 的非交互执行引擎（exec/src/lib.rs，约 1975 行），与 TUI 模式共享核心层但使用完全不同的交互模型：

Exec 与 TUI 的核心架构差异：

维度TUI 模式Exec 模式
入口tui::run_main()exec::run_main()
事件循环持续运行，等待用户输入单 turn 执行完毕即退出
输出方式Ratatui 即时渲染JSON/文本流式输出
交互请求弹出对话框，等待用户自动拒绝/自动处理
会话管理支持恢复、分叉支持恢复（--resume）
适用场景交互式编程CI/CD、自动化脚本

Exec 模式的 run_main() 执行流程：

  1. 解析 CLI 参数：Cli struct 包含 prompt、model、config 覆盖等
  2. 加载配置：强制登录认证，初始化 CloudConfigBundle
  3. 启动 App Server：创建 in-process app-server client（与 TUI 共享同一协议）
  4. 解析 prompt：从命令行参数或 stdin 获取用户指令
  5. 启动/恢复线程：InitialOperation::UserTurn 开始新 turn 或 --resume 恢复
  6. 运行事件循环：EventProcessor 处理所有事件直到 turn 完成
  7. 输出结果：通过 EventProcessorWithJsonOutput 格式化为 JSON 或文本

Ephemeral 执行 ​

Ephemeral 模式提供临时的执行环境，执行完毕即清理：

Ephemeral 的关键特征：

  • 临时性：执行环境在任务完成后自动清理，不保留状态
  • 隔离性：每次执行在独立的沙箱环境中运行
  • 无状态：不依赖之前的执行状态（除非显式 --resume）
  • 自动化友好：适合 CI/CD 管道和批量任务处理

ThreadConfigSnapshot 中的 ephemeral 字段标识当前线程是否为临时模式：

rust
pub struct ThreadConfigSnapshot {
    pub ephemeral: bool,
    // ... 其他配置字段
}

输出格式 ​

Exec 模式支持两种输出格式，通过 EventProcessorWithJsonOutput 处理：

JSON 输出模式（--experimental-json） ​

每行一个 JSON 对象，包含不同的事件类型：

事件类型说明
TurnStartedEventTurn 开始，包含 thread ID
AgentMessageItem代理的文本消息
CommandExecutionItem命令执行（命令 + stdout/stderr）
FileChangeItem文件修改（路径 + 变更内容）
McpToolCallItemMCP 工具调用
ReasoningItem推理过程
TurnCompletedEventTurn 完成，包含 Usage 统计
TurnFailedEventTurn 失败，包含错误信息

文本输出模式（默认） ​

人类可读的彩色文本输出，包含：

  • 代理消息（纯文本）
  • 命令执行结果（命令 + 输出）
  • 文件修改摘要（修改的文件列表）
  • 最终结果摘要

自动化安全策略 ​

Exec 模式下的安全策略需要特别考虑，因为无法进行实时用户交互：

自动化安全的关键设计：

  1. 自动拒绝：所有 ServerRequest（审批、用户输入、MCP elicitation）在 exec 模式下自动拒绝。这确保了在没有人类监督的情况下，代理不会执行高风险操作。

  2. ExecPolicy 配置：通过 ExecPolicy 预定义允许的命令集合（Decision::Allow），避免需要审批的命令。

  3. 沙箱策略：使用更严格的 Sandbox 配置，限制文件系统和网络访问范围。

  4. 输出 Schema：output_schema_path 参数支持指定 JSON Schema，约束代理输出的结构。

相关概念 ​

反向链接

出链