Codex CLI 端到端生命周期

weixin_42202697

374人浏览 · 2026-07-17 17:33:19

weixin_42202697 · 2026-07-17 17:33:19 发布

从进程启动、提示词组装到工具执行与回合完成

摘要：本文深入解析了 Codex CLI Agent 的完整架构与工作流程。从进程启动到用户交互，从提示词组装到工具执行，系统通过分层设计实现高效协作：TUI 负责前端交互，App Server 处理协议转换，Core 管理上下文与循环控制，模型进行决策，工具运行时负责执行。文章详细阐述了用户输入如何转化为 Turn、提示词的分层结构、模型与工具的交互闭环、流式事件传递机制等关键环节，并揭示了"一个用户回合包含多次模型请求"的核心设计理念。

本文面向希望理解 Codex CLI 智能代理（Agent）架构的研发人员、技术负责人和 AI 应用开发者。阅读本文不要求了解 Rust，也不要求预先了解 Agent、MCP 或 Responses API。

分析基线：openai/codex 仓库 main@cbc83d961e。本文聚焦交互式 codex TUI 主路径；codex exec、IDE 和桌面端前端不同，但会复用大量 App Server、Core Session、模型请求和工具执行机制。

一页结论

理解 Codex CLI，只需先记住四件事：

TUI 不是直接调用 Agent Core。 TUI 是终端中的交互界面；当前 TUI 首先连接一个内嵌、本地守护或远程 App Server（应用服务层），再通过 JSON-RPC 请求驱动 Core（Agent 核心运行时）。
一个用户回合通常包含多次模型请求。 模型提出工具调用，Codex 执行工具并把结果放回历史，再次请求模型，直到模型给出最终回答。
提示词不是一个拼接后的大字符串。 请求由 Base Instructions（基础行为指令）、多角色消息历史、环境与项目上下文、工具 schema（工具参数的机器可读说明）、推理参数和输出约束共同组成。
真正的模型推理发生在模型服务端。 本地 Codex 负责上下文、工具、权限、沙箱、事件流和循环控制，不负责实现模型内部的逐 token 思考。

用一句话概括：

Codex CLI 是一个事件驱动的 Agent Runtime（智能代理运行时）：前端负责交互，App Server 负责协议和线程，Core 负责上下文与循环，模型负责决策，工具运行时负责执行。

阅读前先理解四个概念

下面四个词贯穿全文，也最容易混淆：

概念	通俗理解	在 Codex 中的含义
Thread	一份可以继续打开的聊天档案	持久化的 Agent 会话，可以包含很多次用户任务
Turn	用户交给 Agent 的一次完整任务	从接收一次用户目标开始，到最终回答、失败或中断为止
Sampling Request	Codex 向模型“问一次”	一次完整的模型生成请求，模型可能回答文本，也可能要求调用工具
Tool Call	模型要求 Codex“做一次事”	例如搜索代码、运行命令、修改文件或调用 MCP 服务

它们的关系是：

因此，“一轮用户对话”不等于“一次模型请求”。一个 Turn 内部可能反复进行多次模型请求和工具调用。

常见缩写速查

缩写	全称	简单解释
CLI	Command-Line Interface	在终端中通过命令使用的软件界面
TUI	Terminal User Interface	在终端里绘制的交互界面，如输入框、对话和弹窗
RPC	Remote Procedure Call	像调用本地函数一样请求另一个进程或服务做事
JSON-RPC	JSON Remote Procedure Call	使用 JSON 表达方法名、参数、结果和错误的 RPC 协议
API	Application Programming Interface	软件模块或服务对外提供的调用接口
MCP	Model Context Protocol	让模型客户端发现和调用外部工具、资源或应用的协议
SSE	Server-Sent Events	服务端通过一个 HTTP 连接持续向客户端推送事件
WebSocket	WebSocket Protocol	客户端和服务端可以持续双向通信的长连接协议
cwd	Current Working Directory	当前工作目录，决定命令和项目指令从哪里开始生效

1. 总体架构

各层职责

层	主要职责
CLI	解析命令行参数、配置覆盖和子命令
TUI	输入、流式展示、审批交互、会话切换
App Server Client	在进程内、本地 Daemon 或远程服务之间建立统一客户端接口
App Server	JSON-RPC、Thread/Turn API、Core 事件到客户端通知的转换
ThreadManager	创建、恢复、分叉和管理 Agent Thread
Core Session	Turn 生命周期、上下文历史、模型循环、工具调用和持久化
Model Client	构造 Responses API（模型响应接口）请求、流式传输、重试和路由状态
Tool Runtime	工具发现、参数路由、Hook、审批、沙箱和执行

2. 从启动 Codex 到出现输入框

启动期间主要完成以下工作：

解析 --model、--sandbox、--approval-policy、-c 配置覆盖和 Profile。
加载用户配置、项目配置、托管配置及组织约束。
确认认证方式、模型和 Provider（模型服务提供方）。
初始化环境、SQLite 状态库、日志、遥测、插件和 MCP。
选择 App Server：
- Embedded：App Server 与 TUI 运行在同一进程。
- Local Daemon：连接本机持久化 App Server。
- Remote：连接远程 App Server 和工作区。
发送 thread/start，由 ThreadManager 创建 Core Session。
Core Session 建立 Submission channel（任务提交通道）、Event channel（事件通道）、Conversation history（会话历史）、Model client、Tool runtime、Approval state 和 Rollout（运行记录）持久化。

3. 用户输入如何变成一个 Turn

用户按下 Enter 后，TUI 不会立即把一个纯字符串发给模型。

结构化后的输入可能包含：

[
  UserInput::Image(...),
  UserInput::LocalImage(...),
  UserInput::Text(...),
  UserInput::Skill { name, path },
  UserInput::Mention { name, path }
]

不同输入项的作用并不相同：

Text、Image、LocalImage 会成为真正的模型消息内容。
Skill、Mention 主要是结构化选择信号，Core 会据此读取 Skill 正文、注入插件说明或启用 App/MCP 能力。
!command 进入本地 Shell 特殊路径，而不是普通模型提示词路径。
TUI 还会附带 cwd、权限配置、模型、reasoning effort、collaboration mode、personality 和输出 schema。

`turn/start` 与 `turn/steer`

当前没有活动 Turn：发送 turn/start，创建一个新的用户回合。
当前模型仍在工作：优先发送 turn/steer，把新输入加入当前回合。
如果 steer 时服务端发现活动 Turn 已结束，TUI 会回退到 turn/start。

App Server 收到 TurnStartParams 后，将公开 API 输入映射为 Core 的：

Op::UserInput {
  items,
  final_output_json_schema,
  responsesapi_client_metadata,
  additional_context,
  thread_settings
}

Op::UserInput 被放入 Session 的 submission channel，由长期运行的 submission_loop 消费。

4. Core 如何启动 Agent 回合

Core 处理 Op::UserInput 时，大致执行：

Op::UserInput
  → 应用本 Turn 的模型、权限和模式覆盖
  → 创建 TurnContext
  → 尝试作为 steer 输入交给活动 Turn
  → 如果没有活动 Turn，创建 RegularTask
  → 发出 TurnStarted
  → 进入 run_turn

TurnContext 是本次回合的稳定配置快照，也就是一份保证本 Turn 内关键设置一致的“现场记录”，包含：

Turn ID、Thread ID
模型和 Provider
reasoning effort（推理投入等级）、reasoning summary（可展示的推理摘要）
cwd 和环境选择
文件系统、网络和沙箱权限
approval policy
collaboration mode、personality
MCP、Skill、Plugin 快照
输出 JSON Schema（对最终结构化结果的格式约束）
扩展和遥测状态

5. 提示词处理：模型到底看到了什么

Codex 发给模型的不是一个简单字符串，而是一个结构化请求：

ResponsesApiRequest {
  model,
  instructions,
  input: [
    developer messages,
    contextual user messages,
    actual user messages,
    prior assistant messages,
    reasoning items,
    tool calls,
    tool outputs,
    compaction items
  ],
  tools,
  tool_choice: "auto",
  parallel_tool_calls,
  reasoning,
  text / output_schema,
  stream: true,
  prompt_cache_key
}

5.1 模型可见内容分层

层级	在线路中的位置	典型内容
Base Instructions	顶层 `instructions`	模型自带 Agent 指令或 `config.base_instructions`
Developer Context	`input` 中的 developer message	权限、开发者指令、协作模式、Personality、模型切换、技能目录、插件提示、Token Budget
Contextual User Context	带标记的 user message	`AGENTS.md`、环境、cwd、日期、时区、文件系统权限、网络状态、多 Agent 模式
Turn-specific Injection	developer/user message	被选中的 Skill 正文、插件能力、Hook 附加上下文
Actual User Input	user message	用户本次输入的文本和图片
Conversation History	`input`	之前的用户消息、助手消息、reasoning、工具调用和工具结果
Tool Definitions	`tools`	Shell、Patch、MCP、搜索、图片、多 Agent、动态工具等 schema
Reasoning Controls	`reasoning`	reasoning effort、summary、context
Output Controls	`text`	verbosity、文本格式和最终 JSON Schema

Base Instructions 的选择优先级为：

config.base_instructions
    ↓ 如果没有
恢复历史中保存的 base_instructions
    ↓ 如果没有
当前模型自带的 model instructions

普通 Responses API 请求会把 Base Instructions 放入顶层 instructions。使用 Responses Lite 时，代码会把 Base Instructions 和工具定义转换为前置 developer items。

5.2 初始上下文包含什么

第一个真实用户 Turn 会建立完整模型上下文，主要包括：

Developer 侧
  ├─ 模型切换指令
  ├─ 权限与审批说明
  ├─ config.developer_instructions
  ├─ Collaboration Mode 指令
  ├─ Realtime 状态
  ├─ Personality 指令
  ├─ 可用 Skill 目录
  ├─ Plugin / Extension 上下文
  └─ Token Budget 指令

Contextual User 侧
  ├─ AGENTS.md
  ├─ cwd / workspace roots
  ├─ 当前日期与时区
  ├─ 文件系统权限
  ├─ 网络状态
  ├─ App / Connector 状态
  └─ Multi-agent Mode

这些动态片段统一通过 ContextualUserFragment 或扩展贡献接口构造，带有可识别的边界标记，以便历史恢复、过滤和增量更新。

5.3 `AGENTS.md` 如何进入上下文

Core 会：

从项目根目录向当前 cwd 搜索。
读取路径上所有适用的 AGENTS.md。
按“项目根 → 当前目录”拼接。
遵守最大字节预算，对过长内容截断。
包装为带明确边界的 contextual-user fragment。

模型看到的形式类似：

# AGENTS.md instructions for /path

<INSTRUCTIONS>
...
</INSTRUCTIONS>

AGENTS.md 不属于 Base Instructions；它作为项目和目录范围的用户级上下文进入历史。

5.4 Skill 和 Plugin 如何注入

Skill 分成两层：

初始上下文只放可用 Skill 的目录、名称和使用说明。
用户明确选择或提及某个 Skill 后，Core 才读取相应 SKILL.md 正文并注入当前 Turn。

Plugin mention 会生成当前插件能力提示，包括：

可使用的 MCP Server
已启用的 App/Connector
Skill 前缀或关联能力

这种按需注入避免把所有 Skill 和 Plugin 正文永久塞入上下文。

5.5 Hooks 对提示词的影响

Hooks 可以在多个位置影响模型上下文：

输入前：检查用户输入、阻止输入或增加上下文。
工具前：阻止工具调用或修改工具参数。
工具后：阻止工具结果、替换模型可见结果或附加反馈。
停止前：要求 Agent 继续，并向历史注入 continuation prompt。
Agent 完成后：执行兼容的 after-agent 行为。

5.6 为什么每轮不重发全部动态上下文

ContextManager 保存增量历史：

首个真实 Turn 注入完整初始上下文。
后续 Turn 对比 TurnContextItem 和 WorldStateSnapshot，只注入变化。
cwd、权限、网络、模式、AGENTS 或 App 状态发生变化时，生成对应 diff。
普通消息和工具结果只向历史末尾追加，有利于模型 prompt cache（提示词前缀缓存）。
显式 compact、自动 compact、rollback 等操作属于受控的历史替换路径。

当上下文接近模型限制时，Codex 会压缩旧历史，并重新建立必要的初始上下文和 World State 基线。

6. “思考”阶段发生在哪里

本地仓库中没有一个独立的“思考引擎”。真正的模型推理发生在远端模型服务：

Codex 本地负责：

设置 reasoning effort。
请求 reasoning summary。
处理服务端返回的 reasoning、summary 和加密 reasoning 内容。
将允许展示的推理摘要流式发送给 TUI。
根据模型返回的 tool call 触发工具执行。
管理重试、上下文窗口和后续采样。

因此，架构上可以观察“推理请求”和“推理事件”，但无法从该仓库还原模型内部逐 token 的真实思维过程。

7. 模型采样与工具执行闭环

工具执行管线

模型 Tool Call
  → ToolRouter 解析
  → Registry 查找 Handler
  → ToolStarted 生命周期事件
  → PreToolUse Hook
  → 审批策略
  → 沙箱及文件系统/网络权限
  → Handler 执行
  → PostToolUse Hook
  → ToolCompleted 生命周期事件
  → FunctionCallOutput
  → 写入 ContextManager
  → 下一次模型请求

工具来源可能包括：

内置 Shell、Patch、文件和图片工具
MCP Server 工具
Web Search 和 Image Generation
Plugin/Connector 工具
Extension 工具
Dynamic Tool
多 Agent 工具

模型只会看到当前 Step 中 ToolRouter 公开的工具 schema。模型返回的工具名、参数和 call_id（工具调用唯一编号）会被转换成 ToolInvocation（一次待执行工具调用的内部对象），交给对应 Handler（具体处理程序）。

并行执行

支持并行的工具共享读锁，可以同时运行。
不支持并行的工具持有写锁，会与其他工具串行执行。
工具调用按响应顺序收集结果，并将 FunctionCallOutput 写回历史。

审批与沙箱

需要审批的命令或补丁会：

在活动 Turn 中注册等待通道。
Core 发出 Approval Request 事件。
App Server 把事件转换为客户端请求。
TUI 显示审批界面。
用户决定被转换为 ExecApproval 或 PatchApproval。
原工具调用恢复执行、拒绝或终止。

审批通过不意味着绕过沙箱；工具仍要遵守本 Turn 的文件系统、网络和命令执行策略。

8. 为什么一个用户回合会请求模型多次

假设用户输入：

修复登录失败的问题并运行测试

内部过程可能是：

模型请求 1
  → 模型返回 exec_command("rg ...")

工具执行 1
  → 搜索源码
  → 搜索结果写入历史

模型请求 2
  → 模型返回 apply_patch(...)

工具执行 2
  → 检查权限 / 必要时审批
  → 修改文件
  → Patch 结果写入历史

模型请求 3
  → 模型返回 exec_command("just test -p ...")

工具执行 3
  → 运行测试
  → 测试结果写入历史

模型请求 4
  → 模型返回最终助手消息
  → TurnComplete

所以，从用户视角看是“一轮对话”，从 Runtime 视角看则是：

一个 User Turn
  = 一次或多次模型采样
  + 零次或多次工具执行
  + 零次或多次工具结果回灌
  + 一个最终 TurnComplete

9. 流式事件如何回到 TUI

模型与工具运行期间，Core 会持续产生事件：

TurnStarted
ItemStarted
AgentMessageDelta
ReasoningSummaryDelta
CommandExecutionOutputDelta
FileChangeOutputDelta
ItemCompleted
TokenCount
TurnDiff
TurnComplete

App Server 将 Core 事件映射成公开通知：

Core EventMsg
  → App Server bespoke event handling
  → ServerNotification
  → AppServerClient event stream
  → TUI thread event buffer
  → ChatWidget
  → 终端渲染

这种设计允许同一 Core Session 被不同客户端或远程传输方式消费。

10. Turn 何时结束

一个正常 Turn 结束需要满足：

当前模型响应不再要求后续调用。
没有仍在执行的工具。
没有等待处理的 steer 或 mailbox 输入。
Stop Hook 没有要求继续。
没有中断或终止错误。

完成后 Core 会：

计算本 Turn 的 Token 使用量。
生成 Turn diff。
执行 Turn Stop 生命周期扩展。
保存 rollout。
发出 TurnCompleteEvent。
清理活动 Turn、审批和运行状态。

App Server 将其转换成 TurnCompletedNotification，TUI 随后完成流式内容、关闭运行状态并恢复 Composer。

11. 异常与特殊分支

用户中断

用户按下中断快捷键后，TUI 发送 turn/interrupt。Core 取消模型流和工具任务、清理等待中的审批，并发出 TurnAborted。

模型请求失败

可重试错误会沿用当前 ModelClientSession 进行重试，以复用 WebSocket 和 sticky routing 状态。不可重试错误会生成 Error 事件并结束当前 Turn，但通常不会销毁整个 Thread。

上下文窗口不足

如果模型仍需继续而上下文接近上限，Core 会执行自动 compaction，然后带着压缩历史继续当前 Turn。

用户在执行中追加输入

追加输入通过 turn/steer 进入当前活动 Turn。Core 通常会在当前采样边界处理 pending input，而不是修改已经发出的模型请求。

12. 关键设计原则

前端与 Agent Runtime 解耦

TUI、Daemon 和远程客户端都通过 App Server 协议与 Core 协作，降低 UI 与 Agent 实现的耦合。

历史增量构建

正常路径持续追加消息和工具结果，动态上下文只记录变化，减少重复 Token，并降低 prompt cache miss（提示词缓存未命中）。

模型决策与本地执行分离

模型决定“调用什么工具”，Codex 决定“工具是否可见、是否允许、在哪个沙箱执行、结果如何进入历史”。

工具结果也是上下文

工具输出不是简单日志，而是下一次模型采样的重要输入，因此需要截断、结构化、持久化和安全过滤。

每个 Step 使用一致快照

同一次模型请求中的环境状态、公开工具和工具执行使用相同的 StepContext，避免模型看到的能力与实际执行能力不一致。

13. 核心源码索引

主题	源码位置
CLI 启动和分派	`codex-rs/cli/src/main.rs:956`
TUI 初始化及 App Server 启动	`codex-rs/tui/src/lib.rs:849`
Startup Thread 创建	`codex-rs/tui/src/app.rs:631`
Composer 输入结构化	`codex-rs/tui/src/chatwidget/input_submission.rs:98`
`turn/start` 与 `turn/steer` 路由	`codex-rs/tui/src/app/thread_routing.rs:511`
App Server 映射到 `Op::UserInput`	`codex-rs/app-server/src/request_processors/turn_processor.rs:462`
Core submission loop	`codex-rs/core/src/session/handlers.rs:712`
Agent 主循环	`codex-rs/core/src/session/turn.rs:144`
初始与增量上下文	`codex-rs/core/src/session/mod.rs:3159`
Prompt 数据结构	`codex-rs/core/src/client_common.rs:18`
Responses API 请求组装	`codex-rs/core/src/client.rs:824`
Context fragment 规范	`codex-rs/context-fragments/src/fragment.rs:46`
模型输出与 Tool Call 识别	`codex-rs/core/src/stream_events_utils.rs:319`
工具路由	`codex-rs/core/src/tools/router.rs:210`
并行工具运行时	`codex-rs/core/src/tools/parallel.rs:42`
Turn 完成	`codex-rs/core/src/tasks/mod.rs:568`
App Server 完成通知	`codex-rs/app-server/src/bespoke_event_handling.rs:1257`
TUI 完成处理	`codex-rs/tui/src/chatwidget/protocol.rs:235`

14. 术语表

会话与生命周期

术语	通俗解释
Agent	能读取上下文、调用工具并循环完成任务的智能代理；不只是一次文本生成
Agent Runtime	承载 Agent 的运行系统，负责上下文、工具、安全、事件和生命周期
Thread	一份可恢复的会话档案，包含多次用户任务和完整历史
Turn	一次用户任务的完整执行过程，以用户目标开始，以完成、失败或中断结束
Sampling Request	Codex 向模型发出的一次生成请求；一个 Turn 可以包含很多次 Sampling Request
Step	一次模型采样及其紧邻工具执行所使用的请求阶段
Session	Core 中承载 Thread 运行状态的对象；在本文主路径中可理解为“已加载并正在运行的 Thread”
Steer	在 Agent 尚未完成当前 Turn 时追加或修正输入，而不是另起一个独立 Turn
Mailbox	Agent 之间或运行期间暂存待处理消息的队列；Core 会在合适的采样边界接收它们

模型与提示词

术语	通俗解释
Prompt	交给模型的全部输入，不仅是用户输入的一句话，还包括指令、历史、环境和工具
Base Instructions	整个请求最基础的模型行为指令，通常来自模型默认指令或配置覆盖
Developer Message	由系统或应用提供的行为约束，例如权限、模式和开发者指令
User Message	用户输入或以用户角色注入的项目、环境上下文
Context	模型本次能够看到的信息总和，包括历史、指令、工具结果和环境信息
Context Window	模型一次最多能处理的上下文容量；历史过长时需要压缩或开启新窗口
Token	模型处理文本时使用的基本计量单位；一个汉字或单词可能对应一个或多个 Token
Reasoning Effort	请求模型投入多少推理计算的配置，不等同于直接展示完整思维过程
Reasoning Summary	模型允许客户端展示的推理摘要，不等同于模型内部全部推理内容
Prompt Cache	服务端复用相同提示词前缀计算结果的机制；频繁改写历史可能降低命中率
Responses API	Codex 用来发送结构化输入、工具和推理配置并接收流式结果的模型 API
Output Schema	对最终模型输出结构的约束，例如要求返回符合指定 JSON Schema 的对象

上下文管理

术语	通俗解释
ContextManager	保存模型可见历史、Token 使用信息和动态上下文基线的组件
World State	cwd、AGENTS、环境、App、插件等可能随时间变化的模型可见状态集合
Snapshot	某个时刻状态的完整快照，用于和后续状态比较
Diff	两次状态之间的变化部分；只注入 Diff 可以避免重复发送完整上下文
ContextualUserFragment	带明确边界标记的用户级上下文片段，例如 AGENTS 或环境信息
TurnContext	一个 Turn 内相对稳定的配置快照，例如模型、权限、cwd 和模式
StepContext	某次模型请求及后续工具调用共享的动态状态快照，确保“模型看到的工具”和“实际执行的工具”一致
Compact / Compaction	把较长历史压缩成更短的替代上下文，为后续模型请求腾出空间
Rollout	Thread 的持久化记录，保存消息、事件、上下文状态和恢复所需信息

工具与安全

术语	通俗解释
Tool	Codex 能替模型执行的能力，例如搜索、运行命令、修改文件或访问外部服务
Tool Schema	描述工具名称、参数和返回形式的机器可读说明，模型据此决定如何调用
Tool Call	模型返回的结构化执行请求，通常包含工具名、参数和 `call_id`
Tool Output	工具执行结果；会写回历史，供下一次模型采样继续判断
`call_id`	一次工具调用的唯一标识，用于把调用与对应结果、审批和事件匹配起来
ToolRouter	根据工具名和调用类型找到具体执行器的路由组件
Registry	保存“有哪些工具以及由谁执行”的注册表
Handler	某种工具的具体处理程序，例如 Shell Handler 或 MCP Handler
Hook	在输入、工具执行或 Turn 完成等生命周期节点运行的拦截器，可检查、修改、阻止或追加上下文
Approval	高风险操作执行前的人类或自动审查决定
Approval Policy	决定哪些操作需要审批、哪些可以直接执行的策略
Sandbox	限制进程可访问文件、网络和系统资源的隔离环境；用于降低工具执行风险
Exec Policy	对命令执行进行分类、允许、拒绝或要求审批的规则集合

扩展能力

术语	通俗解释
Skill	一套可复用的任务说明和工作流，通常由 `SKILL.md` 定义，明确选择后按需注入
Plugin	可安装的能力包，可以包含 Skill、工具、MCP 配置、Hook 和其他资源
MCP	Model Context Protocol；连接外部工具、资源或应用的标准协议
MCP Server	通过 MCP 对外提供工具或资源的服务进程
App / Connector	连接外部应用或私有数据源的能力，例如代码托管、文档或协作系统
Extension	Core 内部的扩展接口，可贡献上下文、工具、Turn Item 或生命周期行为
Collaboration Mode	一组影响模型、推理强度和开发者指令的协作模式配置
Personality	调整助手表达风格的配置；是否生效取决于模型和功能开关

进程与通信

术语	通俗解释
App Server	位于客户端与 Core 之间的应用服务层，提供 Thread/Turn JSON-RPC API 并转换事件
Embedded App Server	与 TUI 运行在同一进程中的 App Server
Daemon	在后台持续运行的服务进程；CLI 可以连接已有的本地 App Server Daemon
JSON-RPC	用 JSON 表示请求方法、参数、结果和错误的远程调用协议
Event Stream	服务端持续推送 Turn、文本增量、工具状态和完成通知的事件流
SSE	基于 HTTP 的单向服务端事件流
WebSocket	支持客户端和服务端持续双向通信的长连接协议

15. 30 秒分享版

Codex CLI 启动后，先加载配置、认证和环境，然后通过内嵌或远程 App Server 创建 Agent Thread。用户输入会被 TUI 结构化成文本、图片、Skill 和 App mention，再通过 turn/start 发送给 Core。Core 把模型指令、AGENTS、环境、权限、历史和工具 schema 组装成 Responses API 请求。模型如果返回工具调用，Codex 会经过 Hook、审批和沙箱执行工具，把结果写回上下文后再次请求模型。这个循环持续到模型返回最终回答，随后 Core 发出 TurnComplete，经 App Server 转成通知，由 TUI 完成渲染。一个用户回合因此可能包含多次模型请求和多次工具执行。

参考

Codex 官方文档：https://developers.openai.com/codex
Codex 开源仓库：https://github.com/openai/codex
本文实现细节以文首标注的源码提交为准。

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

weixin_42202697

@weixin_42202697

已为社区贡献1条内容

Codex CLI 端到端生命周期

weixin_42202697

从进程启动、提示词组装到工具执行与回合完成

一页结论

阅读前先理解四个概念

常见缩写速查

1. 总体架构

各层职责

2. 从启动 Codex 到出现输入框

3. 用户输入如何变成一个 Turn

turn/start 与 turn/steer

4. Core 如何启动 Agent 回合

5. 提示词处理：模型到底看到了什么

5.1 模型可见内容分层

5.2 初始上下文包含什么

5.3 AGENTS.md 如何进入上下文

5.4 Skill 和 Plugin 如何注入

5.5 Hooks 对提示词的影响

5.6 为什么每轮不重发全部动态上下文

6. “思考”阶段发生在哪里

7. 模型采样与工具执行闭环

工具执行管线

并行执行

审批与沙箱

8. 为什么一个用户回合会请求模型多次

9. 流式事件如何回到 TUI

10. Turn 何时结束

11. 异常与特殊分支

用户中断

模型请求失败

上下文窗口不足

用户在执行中追加输入

12. 关键设计原则

前端与 Agent Runtime 解耦

历史增量构建

模型决策与本地执行分离

工具结果也是上下文

每个 Step 使用一致快照

13. 核心源码索引

14. 术语表

会话与生命周期

模型与提示词

上下文管理

工具与安全

扩展能力

进程与通信

15. 30 秒分享版

参考

所有评论(0)

温馨提示：您尚未绑定手机号

weixin_42202697

`turn/start` 与 `turn/steer`

5.3 `AGENTS.md` 如何进入上下文