App Server 协议入门

了解 Thread、Turn、Item，完成连接初始化，并生成与当前 CLI 版本匹配的协议 Schema。

App Server 用于构建完整的 Codex 客户端，例如需要认证、对话历史、审批与流式进展的产品。只做后台编码任务或 CI 时，优先考虑 SDK。官方迁移页将 app-server 命令标为实验性，不支持生产工作负载；应按当前版本的协议与支持范围评估。

协议对象

Thread 保存一段对话，包含多个 turn。
Turn 对应一次用户请求以及随后执行的工作。
Item 是输入输出的单位，例如消息、命令、文件修改或工具调用。

协议采用双向 JSON-RPC 2.0 消息，但线上消息省略 "jsonrpc":"2.0" 头。请求有 method、params 和 id；响应按相同 ID 返回 result 或 error；通知没有 ID。

先使用本地 stdio

codex app-server

默认是以换行分隔 JSON 的 stdio 传输，等价于 --listen stdio://。连接后先发送 initialize，随后发送 initialized 通知，再创建 thread 和 turn，并持续读取事件。

初始化请求需要描述客户端，官方示例结构为：

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "my_product",
      "title": "My Product",
      "version": "0.1.0"
    }
  }
}

创建 thread 的响应会返回线程 ID；发起 turn/start 时传这个 ID 以及输入内容。不要把本地示例中的假 ID 当作可复用的服务端标识。

生成匹配版本的类型

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

输出对应执行命令的 Codex 版本。升级运行时后应重新对照生成的 Schema；需要实验字段或方法时，官方说明可添加 --experimental。

WebSocket 与远程连接

本机实验连接可以分别运行：

codex app-server --listen ws://127.0.0.1:4500
codex --remote ws://127.0.0.1:4500

WebSocket transport 是实验性且不支持生产工作负载。非本机访问前应配置认证并放在 TLS 后；plain ws 只适合 localhost 或 SSH 转发。服务端可通过 --ws-auth capability-token --ws-token-file /absolute/path 配置令牌，客户端使用 --remote-auth-token-env 从环境变量取 token。

--listen 控制客户端如何接入 App Server；--code-mode-host 控制 App Server 向外连接哪个 Code Mode host，二者方向不同。同一个 App Server 进程的线程共享选定的 Code Mode host。