市面上绝大多数AI代码助手只是封装一层模型对话接口，只能完成单行补全、简单问答，无法自主完成跨文件重构、批量测试、命令执行等完整工程任务。而OpenAI Codex是一套成熟本地软件工程Agent运行时，依靠分层源码设计、工具调度、沙箱安全、会话持久化能力，实现自主闭环工作流。本文基于codex-main源码仓库逐层拆解模块职责、核心循环逻辑与安全扩展机制，附带可复用代码片段，读懂这套架构能大幅降低自研编码Agent的踩坑成本。

企业多模型调度场景中，可借助统一调度层（如TreeRouter等平台）对Codex、Claude Code等编码模型请求进行分发，实现任务路由与接入统一管理。

一、Codex整体工程分层：Monorepo仓库结构

Codex采用多语言单仓库设计，顶层分为npm启动层、Rust核心工作区、SDK扩展层，核心能力全部沉淀在codex-rs目录：

codex-main/
 ├── codex-cli/          # Node入口包装器
 │   └── bin/codex.js    # 跨平台二进制分发脚本
 ├── codex-rs/           # Rust核心工作区
 │   ├── cli/            # 顶层命令解析
 │   ├── tui/            # 交互式终端界面
 │   ├── exec/           # 无交互CI执行入口
 │   ├── core/           # Agent核心会话循环
 │   ├── protocol/       # Op/Event事件协议定义
 │   ├── app-server/     # IDE/桌面端服务
 │   ├── tools/          # 工具路由与执行逻辑
 │   ├── sandboxing/     # 跨平台沙箱隔离
 │   └── mcp-server/     # 外部资源协议服务
 └── sdk/                # Python/TS对外开发SDK

npm包仅做平台适配分发，不承载任何Agent推理逻辑，简化启动脚本如下：

const targetMap = {
  "darwin-arm64": "aarch64-apple-darwin",
  "linux-x64": "x86_64-unknown-linux-musl",
  "win32-x64": "x86_64-pc-windows-msvc",
};

const key = `${process.platform}-${process.arch}`;
const binaryPath = `vendor/${targetMap[key]}/bin/codex`;

spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" });

这种设计兼顾npm生态便捷性与Rust高性能原生运行能力，同时统一处理不同操作系统沙箱差异。

二、核心会话模型：Thread / Session / Turn三级抽象

Codex摒弃传统单次对话逻辑，采用三层状态隔离解决长任务中断、恢复、分支需求：

  1. Thread：长期任务会话，存储完整历史与配置快照
  2. Session：单次运行上下文，持有模型客户端、权限策略、工作目录
  3. Turn：最小执行单元，一轮「模型推理→工具调用→结果回灌」闭环

整个交互基于提交队列+事件队列异步通信：

enum Op {
    UserTurn { input: Vec<UserInput> },
    Interrupt,
    ConfigureSession,
}

enum EventMsg {
    TurnStarted,
    AgentMessageDelta,
    ExecCommandBegin,
    ApplyPatchApprovalRequest,
    TurnCompleted,
    Error,
}

客户端提交操作，Agent持续推送事件，TUI、CI脚本、IDE服务可独立消费同一套事件流。

三、灵魂：run_turn Agent主循环

codex-rs/core/src/session/turn.rs是整套系统核心，每轮Turn标准化执行流程：

async fn run_turn(input: Vec<TurnInput>) -> Result<Option<String>> {
    let mut client_session = model_client.new_session();

    run_pre_sampling_compact_if_needed().await?;
    record_context_and_inputs(input).await?;

    loop {
        let request_input = history.for_prompt();
        let output = run_sampling_request(&mut client_session, request_input).await?;

        if output.needs_tool_follow_up {
            execute_tools_and_record_outputs(output.tool_calls).await?;
            continue;
        }

        if has_pending_input().await { continue; }

        return Ok(output.last_agent_message);
    }
}

核心逻辑是一个不断循环的执行闭环： 模型生成 → 工具调用 → 执行结果回灌 → 再次推理，直到完成任务。

四、工具调度与并行执行机制

ToolRouter负责解析FunctionCall，并映射系统工具执行：

async fn dispatch_tool(call: ToolCall) {
    let supports_parallel = router.tool_supports_parallel(&call);

    if supports_parallel {
        let _guard = parallel_execution.read().await;
        router.dispatch(call).await;
    } else {
        let _guard = parallel_execution.write().await;
        router.dispatch(call).await;
    }
}
  • 只读工具：允许并行执行
  • 写入类操作：强制串行锁

避免文件竞争、shell冲突、日志爆炸等问题。

五、安全体系：沙箱 + 审批 + 权限控制

Codex在工程执行层面采用三重防护：

  1. 跨平台沙箱（Linux / macOS / Windows）
  2. 审批策略（approval_policy）
  3. 路径级权限控制

补丁安全逻辑：

function assess_patch_safety(action, policy, sandbox) {
    if (action.only_writes_allowed_paths()) return "AutoApprove";
    if (policy.allows_user_approval()) return "AskUser";
    return "Reject";
}

默认仅允许操作工作目录，系统级文件一律禁止。

六、扩展生态：AGENTS.md / MCP / Skills

AGENTS.md规则注入

- 修改代码后执行format
- core模块必须补测试
- 禁止修改生成文件

MCP协议

[mcp_servers.local_docs]
command = "node"
args = ["./mcp-docs-server.js"]

用于对接数据库、知识库、内部系统。

七、源码阅读路径

  1. codex-cli入口
  2. cli/main.rs命令系统
  3. protocol事件定义
  4. core/turn.rs核心循环
  5. tools + sandbox执行层

八、总结

Codex本质不是“聊天模型封装”，而是一套完整的工程Agent运行时系统：

  • 分层会话管理（Thread / Session / Turn）
  • 工具执行闭环（ToolRouter）
  • 沙箱安全隔离
  • 可扩展协议体系（MCP）

这种架构的价值在于，它把大模型从“回答问题工具”升级为“可控的软件工程执行体”。 对于企业级AI工程系统来说，这类设计比单纯模型调用更关键，也更接近真正的生产系统形态。