00. 总览：Codex 智能体的运行时分层¶
Codex 智能体是一个本地任务运行时，而不是一次性的大模型调用封装。用户输入进入会话后，系统会维护运行状态，构造模型上下文，接收模型流式输出，执行模型提出的工具调用，再把工具结果写回下一次模型输入。这个过程持续到本轮任务没有后续工具调用、没有待处理输入，并且运行时完成状态收束。
文中保留少量源码和协议名。线程（Thread）表示长期会话，轮次（Turn）表示一次用户任务，条目（Item）表示轮次内的结构化记录，轮次上下文（Turn Context）表示本轮固定的执行现场，持久化记录（rollout）表示用于恢复和分叉的历史材料。
这种结构将模型放在决策层，将本地运行时放在执行层。模型负责生成文本、推理和工具请求；本地运行时负责判断工具是否可用、参数是否合法、权限是否允许、是否需要审批、是否进入沙箱、执行结果如何记录。Codex 的安全边界建立在本地执行层，而不是建立在提示词中的自我约束。
运行主线¶
Codex 的核心流程围绕轮次循环展开：
一次用户轮次可以包含多次模型请求。模型第一次可能请求运行测试，测试输出回到上下文后，模型第二次再决定读取文件；文件内容返回后，模型第三次再生成 patch。所有这些步骤仍属于同一个用户任务。
这条主线也是区分各层职责的标准。入口层不解释模型输出，模型层不执行本地命令，工具层不决定会话是否结束，权限层不生成用户可见总结，状态层不改变模型决策。每一层只处理自己的输入和输出，再把结构化结果交给下一层。
一个 shell 工具调用会跨越多层：模型层产生工具调用，工具层解析调用，权限层决定是否允许执行，状态层发出命令开始和输出事件，上下文层把命令结果写回历史，模型层再基于这个结果继续采样。这个跨层往返是 Codex 智能体与普通聊天机器人的本质差异。
入口层¶
入口层包括 TUI、codex exec、app-server 和 CLI 分发。不同入口的职责主要是输入收集和结果展示。TUI 面向交互，exec 面向非交互终端任务，app-server 面向协议客户端。它们最终会收敛到同一套会话协议和核心运行时。
入口层不复制智能体循环。工具执行、权限判断、上下文构造、模型采样、事件持久化都在统一运行时中完成。因此同一个功能在 TUI 和 exec 下具有一致行为。
会话层¶
Codex 对外使用 Thread、Turn、Item 描述会话。
Thread 表示长期会话，承载工作目录、模型配置、权限配置、历史和持久化信息。Turn 表示一次用户任务，从输入开始，到完成、失败或中断结束。Item 表示轮次内发生的结构化事件，例如用户消息、助手文本、命令执行、补丁、差异、错误和权限请求。
这套结构使客户端能够稳定展示任务过程，也使历史能够被回放、恢复和分叉。
会话层还承担边界翻译。客户端看到的是“某个轮次里出现了一个命令条目”，运行时内部看到的是“模型生成了 shell 工具调用、本地处理器正在执行、stdout 正在流式返回”。Item 将这些内部状态压成协议可理解的记录，使不同客户端不需要依赖核心内部实现。
运行时层¶
进入核心运行时后，Session 持有会话状态并按队列处理操作。用户输入、审批响应、中断、压缩、回滚、关闭都通过同一条队列进入。队列化处理保证活跃轮次、待处理输入、历史、审批状态和事件输出保持顺序一致。
普通用户任务由普通任务承载。任务负责启动轮次、进入模型与工具循环，并在结束时汇总 token 用量、差异、待处理输入、长期记忆指标和完成状态。
Turn Context 固定本轮任务的运行现场，包括当前目录、模型、模型提供方、权限、沙箱、网络策略、环境、可用工具、技能、动态工具和输出格式。模型上下文和工具执行都基于同一份现场。
模型层¶
模型层处理流式响应。模型可能流式输出文本、reasoning、工具调用参数、完成事件和用量信息。文本事件用于展示和记录，工具调用会转交本地工具系统，用量会更新统计。单次模型响应完成只表示一次采样结束，不代表整个轮次完成。
模型层还负责处理传输细节，包括 HTTP Responses API、WebSocket、重试和降级。传输机制不会改变智能体语义；无论底层通道如何，模型事件最终都要转成运行时可处理的结构化结果。
工具层¶
工具层连接模型请求和本地执行。模型只能看到工具规范并生成工具调用，本地处理器才真正执行动作。shell、补丁、计划、MCP、动态工具、权限请求等都遵循同一边界。
工具执行结果会写回历史，成为下一次模型采样的输入。工具输出不是附属日志，而是模型继续判断的事实来源。
上下文层¶
模型输入由历史、当前用户输入、工具结果、项目规则、用户指令、权限说明、环境信息、技能、插件、MCP 工具、动态工具、压缩摘要和长期记忆共同构成。
上下文系统不会每轮重复注入所有信息。首次真实轮次会建立完整上下文基线，后续轮次主要注入变化。长会话通过压缩历史，恢复/分叉通过持久化记录恢复模型现场。
上下文层同时承担过滤和归一化。不是所有客户端可见事件都会原样进入模型，也不是所有本地信息都应该进入提示词。历史需要保留工具调用与工具输出的因果关系，上下文差异需要保留配置变化，压缩需要保留任务继续所需事实，长期记忆需要避免被外部上下文污染。
权限层¶
权限层由权限配置、审批策略、沙箱、执行策略（ExecPolicy，主要评估命令风险）和守护复核（guardian，用于部分自动审批场景）等机制组成。权限配置定义能力边界，审批策略定义交互策略，沙箱落实执行隔离，守护复核在部分场景下承担自动审批判断。
模型可见的权限说明用于引导模型减少无效请求。本地运行时的权限检查才是实际边界。模型提出的命令、patch、MCP 调用和权限请求都必须经过本地判断。
状态层¶
Codex 运行中持续产生事件。客户端通过事件展示模型输出、工具状态、差异、审批请求、token 用量和轮次完成状态。
关键历史同时写入持久化记录。Thread 可以恢复，历史可以回放，旧会话可以分叉，长期记忆后台任务可以从历史中提炼稳定信息。事件和持久化使 Codex 从一次性调用变成可管理的长期智能体会话。
状态层的事件不是普通日志。日志描述“发生过什么”，事件还要支持客户端实时 UI、exec 输出、协议兼容和历史重建。一个事件是否需要持久化，取决于它是否影响后续恢复、上下文重建或客户端状态回放。