01. 一次请求的完整旅程¶
一次 Codex 请求从客户端输入开始，经过会话协议、会话队列、轮次上下文、模型流、工具执行、权限系统、事件记录和持久化收束。这个过程不是单次模型调用，而是一段可观察、可中断、可恢复的本地任务执行。
线程创建与恢复¶
客户端提交任务前会进入一段线程（Thread，表示可持续的智能体会话）。线程承载工作目录、模型/模型提供方、权限配置、来源、历史、持久化位置和动态工具等信息。
创建或恢复线程后，客户端获得的是会话容器，而不是模型回答。后续用户任务通过 turn/start 进入这段会话。这个分离使 Codex 能够在同一段会话中持续工作，也使恢复和分叉成为运行时能力的一部分。
线程创建阶段还会决定会话是否持久化、是否允许长期记忆、是否携带动态工具、是否需要从既有持久化记录恢复历史。恢复会话时，运行时需要重建的不只是消息列表，还包括压缩后的替换历史、上下文基线、线程记忆模式和工具定义。线程因此是后续所有轮次的状态根。
轮次启动标准化¶
turn/start 请求包含用户输入和本轮覆盖配置。输入可以是文本、图片、本地图片或结构化条目；覆盖配置可以包括当前目录、模型、输出结构、权限、环境变量和协作模式。
app-server 在请求进入核心前完成标准化。它校验线程是否存在、输入是否有效、权限参数是否冲突、覆盖配置是否合法。用户输入和本轮配置一起提交给会话，避免出现输入已进入队列但运行现场尚未更新的状态错位。
标准化还会把不同入口的输入形态压成统一表示。终端界面输入、一次性执行参数、外部客户端传入的结构化条目，最终都要变成核心可处理的用户输入和轮次设置更新。这个转换让后续会话不需要区分输入来自哪个客户端。
会话队列接管¶
标准化后的请求进入会话队列。会话按顺序处理用户输入、审批响应、中断、压缩、回滚和关闭等操作。队列化保证会话状态按因果顺序变化。
普通用户输入会创建新的轮次上下文并启动普通任务。若当前已有活跃轮次，会话会尝试把新输入作为待处理输入注入当前任务，使运行中的智能体能够接收用户追加约束。
队列接管后，turn/start 的同步返回通常只表示任务已被接受或已经进入运行状态。真正的进度通过事件流返回。客户端因此不会等待一次请求响应承载整个智能体结果，而是持续消费通知。
轮次上下文固定执行现场¶
轮次上下文（Turn Context）固定本轮任务的运行规则。它包含当前目录、模型、模型提供方、权限边界、审批策略、沙箱和网络策略、工具配置、技能、动态工具、环境变量策略和输出格式。
模型上下文和工具执行都基于这份现场。模型会看到当前权限和环境说明，工具运行时则按相同规则判断命令、patch 和外部调用能否执行。
模型上下文构造¶
普通任务进入轮次运行后，系统构造模型输入。模型上下文由当前用户输入、历史、工具结果、项目规则、用户指令、权限说明、环境信息、可用工具、必要技能、插件、长期记忆和压缩摘要组成。
上下文构造具有增量特征。首次真实轮次注入完整规则，后续轮次主要注入变化。长会话通过压缩旧历史，恢复会话通过持久化记录重建模型现场。
上下文构造会同时更新历史和持久化记录。模型看到的并不是临时字符串，而是一组可恢复的结构化条目。后续恢复/分叉依赖这些条目重建“模型当时基于什么规则和事实做判断”。
模型流式采样¶
模型请求以流式形式返回。普通文本和 reasoning 会转成客户端可见增量，同时写入历史。完整响应条目会成为后续恢复和采样的材料。用量信息会更新 token 统计。
模型也可能返回工具调用。工具调用表示模型提出本地动作请求。此时运行时进入工具执行链路，而不是直接结束本轮采样。
采样期间运行时同时维护三个输出面。客户端面接收实时增量；历史面等待完整条目后记录可恢复结构；执行面在工具调用完整后启动本地工具。三者共享同一条模型事件流，但落点不同。
工具调用与权限检查¶
工具调用被本地运行时解析为具体工具调用。处理器校验参数和工具语义，随后进入权限系统。
权限系统根据权限配置、审批策略、沙箱、命令风险、补丁路径和外部工具状态判断动作结果。结果可能是直接执行、发起用户审批、交给守护复核、拒绝，或者在沙箱失败后请求升级重试。
模型不能绕过这一步。模型生成的工具调用只是动作意图，本地运行时才决定动作是否落地。
审批请求也通过事件流进入客户端。用户批准或拒绝后，审批响应再次进入 Session 队列。这样审批结果与其他会话操作保持顺序一致，不会在工具执行链路之外直接改状态。
工具结果回填¶
工具执行完成后，结果会被写回历史。shell 返回 stdout、stderr、退出码和错误；patch 返回应用结果和差异；MCP 返回外部工具数据或错误；权限请求返回批准或拒绝结果。
这些结果同时进入事件流，供客户端展示。下一次模型采样会读取工具结果，因此模型后续决策基于真实执行反馈，而不是基于推测。
回填结果保持调用和输出的对应关系。模型下一次看到的是“某个工具调用的 output”，而不是一段无来源日志。这使模型能够区分多个连续工具调用的结果，避免把一个命令的输出误认为另一个命令的反馈。
多轮采样循环¶
工具结果需要模型继续处理时，轮次运行会再次请求模型。一轮任务通常形成多次采样：
待处理输入会在合适时机并入下一次采样。用户运行中追加的限制与最新工具结果一起进入模型上下文，影响后续动作。
轮次完成收束¶
轮次完成（TurnComplete）是运行时收尾结果。模型输出最终说明后，运行时仍需确认没有未完成工具、没有待后续的工具结果、没有待处理输入，且模型流和状态记录已经收束。
收尾阶段会记录最终助手输出，更新 token 用量、差异、长期记忆指标和活跃轮次状态，发出轮次完成事件，并把关键历史写入持久化记录。
持久化结果¶
一次请求的完整结果包括最终文本、中间工具调用、工具输出、差异、审批记录、错误、token 用量、轮次状态和可恢复历史。持久化记录支持恢复、分叉、历史回放和长期记忆后台提炼。
Codex 请求因此表现为一段受控任务执行：模型负责选择下一步，本地运行时负责执行边界，工具结果提供真实反馈，事件和持久化保证过程可见且可恢复。