App Server Protocol 定义了外部客户端（如 IDE 插件）与 Codex 代理的 JSON-RPC 2.0 通信标准。

为什么需要 App Server Protocol

Codex 支持多种界面（TUI、Exec、IDE 插件、SDK），这些界面需要以统一的方式与核心代理运行时通信。App Server Protocol 定义了标准化的 JSON-RPC 请求/响应/通知格式，使得任何客户端都能通过同一协议与 Codex 交互。

该协议还支持多种传输层（stdio、Unix socket、TCP/WebSocket），客户端可以选择嵌入式（同进程）或远程（守护进程/网络）连接方式，灵活适应不同部署场景。

核心原理

1. JSON-RPC 2.0：所有请求和响应遵循 JSON-RPC 2.0 规范，ClientRequest 枚举通过宏生成 60+ 个强类型变体
2. 序列化作用域：ClientRequestSerializationScope 控制请求的并发执行范围（Global/Thread/Process 等），避免资源竞争
3. 双向通信：客户端发送请求（ClientRequest），服务器推送通知（ServerNotification），支持实时事件流
4. 多传输层：支持 stdio（嵌入式）、Unix socket（本地守护进程）、TCP/WS（远程）三种传输方式

在源码中的实现

• codex-rs/app-server-protocol/src/protocol/common.rs — ClientRequest 枚举（60+ 变体）、AuthMode、ClientRequestSerializationScope
• codex-rs/app-server/src/lib.rs — MessageProcessor（请求路由）、OutgoingMessageSender（通知推送）
• codex-rs/app-server/src/transport/ — 传输层实现（stdio/socket/TCP）
• codex-rs/app-server/src/in_process.rs — 嵌入式模式（同进程直接调用）

相关概念

• Backend Client
• Agent Loop
• MCP
• Ephemeral