App Server 协议入门

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

This page has not been translated into English yet. The original Chinese version is shown below.

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。