codex 学习笔记

Appearance

应用服务器协议 — 概念 ​

App Server 协议设计 ​

App Server Protocol 是 Codex 的核心通信协议，基于 JSON-RPC 2.0，定义了外部客户端与代理运行时之间的所有交互：

App Server 的模块组织（app-server/src/lib.rs）：

模块职责
transport传输层（stdio/socket/TCP）
message_processorJSON-RPC 消息处理和路由
request_processors各类请求的处理器
thread_state线程（会话）状态管理
config_manager配置的动态管理
in_process嵌入式模式（同进程通信）
outgoing_message服务器推送的通知
command_exec命令执行管理
fuzzy_file_search模糊文件搜索
fs_watch文件系统监控
mcp_refreshMCP 配置热更新
dynamic_tools动态工具管理
extensions扩展管理
models模型信息管理
skills_watcher技能文件监控

Backend Client 后端客户端 ​

Backend Client（core/src/client.rs，2254 行）管理 Codex 与 LLM 后端的连接：

Backend Client 的两层设计：

层次类型生命周期核心方法
会话级ModelClient整个会话new_session(), compact_conversation_history()
Turn 级ModelClientSession单个 turnstream(), prewarm_websocket()
rust
pub struct ModelClient {
    state: Arc<ModelClientState>,
    prompt_cache_key_override: Option<String>,
}

pub struct ModelClientSession {
    client: ModelClient,
    websocket_session: Option<...>,
    turn_state: Arc<OnceLock<String>>,
}

ModelClientState 内部字段：

字段说明
session_id会话唯一标识
thread_id线程标识
provider: SharedModelProvider模型提供商抽象
session_source会话来源（CLI/TUI/SDK）
cached_websocket_sessionWebSocket 连接缓存
disable_websockets禁用 WebSocket（降级到 HTTP）
enable_request_compression请求压缩
include_timing_metrics包含性能指标

传输优先级：优先 WebSocket（支持增量 delta，减少重复数据传输），降级到 HTTP SSE。

消息格式与传输 ​

App Server Protocol 基于 JSON-RPC 2.0，通过宏生成 60+ 个 ClientRequest 变体：

ClientRequestSerializationScope 定义了请求的序列化作用域，控制并发和资源访问：

作用域说明
Global(&str)全局操作（配置、认证）
GlobalSharedRead(&str)全局共享读操作
Thread { thread_id }线程级操作（提交、事件）
ThreadPath { path }线程路径操作
CommandExecProcess命令执行进程
Process进程级操作
FuzzyFileSearchSession文件搜索会话
FsWatch文件系统监控
McpOauthMCP OAuth 认证

认证模式 AuthMode：

模式说明
ApiKeyAPI Key 认证
ChatgptChatGPT 登录
ChatgptAuthTokensChatGPT 认证令牌
AgentIdentity代理身份认证

会话管理 ​

App Server 管理多个并发会话（线程）的生命周期：

会话管理涉及：

  • thread_state — 线程的状态存储和生命周期
  • config_manager — 线程级配置的动态管理
  • in_process — 嵌入式模式下直接调用（无序列化开销）
  • outgoing_message — 通过 OutgoingMessageSender 推送事件通知

相关概念 ​

反向链接

出链