03. 入口层如何进入核心¶

Codex 的入口包括 CLI、终端界面、codex exec、app-server 和外部客户端。入口形态不同，但智能体运行逻辑收敛到同一套核心运行时。入口层负责输入收集和结果展示，协议层负责标准化请求，核心运行时负责会话状态、模型采样、工具执行、权限控制和持久化。

CLI / 终端界面 / 一次性执行 / 外部客户端
  -> app-server 协议
  -> 线程 / 轮次
  -> 会话
  -> 普通任务
  -> 轮次运行

CLI 分发¶

CLI 是进程启动和子命令分发层。无子命令时进入终端界面，codex exec 进入非交互执行，codex app-server 启动协议服务，其他子命令处理沙箱、MCP 服务端、恢复、分叉等专门场景。

CLI 不实现智能体循环。它将进程引导到相应入口，然后由入口层和 app-server 协议继续推进任务。

这种分发方式使 CLI 不承担长期状态管理。无论用户最终进入终端界面、一次性执行还是 app-server，模型上下文、工具执行、权限审批和持久化都不会在 CLI 层分叉。

终端界面提供交互式体验。用户可以输入任务、查看模型流式输出、观察命令状态、审批权限请求、中断任务和追加输入。

终端界面作为 app-server 客户端工作。它创建或恢复线程，提交轮次，消费通知，并把事件转换成界面状态。模型采样、工具执行、权限判断和历史持久化仍由核心运行时负责。

这种设计使终端界面不需要复制核心内部状态机，也使其他客户端能够复用同一套事件协议。

终端界面的交互能力主要来自通知。命令输出、审批请求、差异更新、轮次完成都不是终端界面主动轮询核心内部状态得到的，而是协议事件驱动的界面更新。用户在终端界面中追加输入或中断任务，也会重新变成协议请求进入会话队列。

codex exec 面向一次性或脚本化任务。它启动进程内 app-server，创建或恢复线程，提交一个轮次，然后消费通知直到任务结束。

一次性执行与终端界面的差异在展示方式。终端界面将事件渲染成交互界面，一次性执行将事件打印成人类可读输出或 JSONL。两者中间都使用同一套线程、轮次、会话和工具系统。

一次性执行因此适合脚本化使用，但它仍然保留智能体的核心能力。审批、沙箱、工具输出、token 用量和最终轮次状态都通过同一通知流处理。非交互入口不会降低运行时约束。

app-server 将外部请求转换为核心操作。它接收 JSON-RPC 请求，校验参数，合并配置，处理线程启动、恢复和分叉，并把用户输入、审批响应、回滚、压缩等动作提交给会话。

turn/start 请求可能包含文本、图片、当前目录覆盖、模型覆盖、输出结构、权限覆盖和环境变量。app-server 在进入核心前完成标准化，保证本轮输入与本轮配置同时生效。

app-server 还将核心事件转换成客户端通知。客户端使用 turn/started、item/completed、turn/diff/updated、turn/completed 等事件观察任务进度。

协议边界还承担兼容和演进职责。外部载荷可以随 API 版本扩展，核心运行时仍接收统一后的操作。新增轮次参数、通知字段或线程元信息时，这一层负责把外部传输形态与内部运行结构分开。

请求进入核心后，入口差异基本消失。线程管理器创建或恢复会话，会话接收操作并启动普通任务，普通任务进入轮次运行，模型与工具开始交替。

功能变更的归属由边界决定。界面布局、快捷键和输出格式属于入口层；协议载荷和通知属于 app-server 层；上下文、工具、权限、长期记忆、模型流和状态恢复属于核心运行时。

这种收敛结构保证不同入口具有一致智能体行为，同时允许入口层各自优化交互体验。

入口层的统一也降低了功能扩展成本。新增工具、权限策略、长期记忆行为或模型提供方时，主要接入核心和协议层；终端界面与一次性执行通过事件和结果自然获得新能力，除非展示形态需要额外适配。