通过 JSON-RPC 和 Codex 应用服务器控制 Codex

免费领取国家顶级域名（.cn/.中国）

欢迎加入国家域名信源站点导航

站点智能：AI搭建 AI辅助运营独立站，把生意做到全世界

你听说过 Codex 应用服务器吗？

无需通过命令行界面与 Codex 交互，Codex 应用服务器允许你通过 JSON-RPC 控制 Codex 代理。

换句话说，你可以在 Codex 之上构建自己的图形用户界面、文本用户界面、任务队列或编排层。

本文侧重于保持快节奏，因此如果你正在寻找精确的协议细节和规范，请参考官方自述文件：
https://github.com/openai/codex/blob/main/codex-rs/app-server/README.md

启动 Codex 应用服务器非常简单，只需运行：

codex app-server

就是这样。

服务器将开始监听标准输入。接下来，你只需发送遵循协议的 JSON 请求（技术上是 JSONL，因此每个请求必须位于单行）。

这使得你的应用程序能够通过 Codex 应用服务器以编程方式启动和控制 Codex 代理。

对话流程

典型的交互如下所示：

1. 发送初始化请求以初始化服务器。
2. 使用 thread/start 启动代理对话。
3. 使用 turn/start 向代理分配任务。
4. 等待直到收到 turn/completed。
5. 重复步骤 3–4，直到任务完成。
6. 完成。

理解线程和轮次

当我刚开始学习该协议时，我发现很难想象线程和轮次之间的关系。

下面的例子帮助我彻底理解了这一点：

线程
├── 轮次 1
│   用户：
│     “请调查这个问题。”
│
│   代理：
│     - 搜索代码库
│     - 读取相关文件
│     - 识别根本原因
│
│   turn/completed
│
├── 轮次 2
│   用户：
│     “请修复它。”
│
│   代理：
│     - 编辑文件
│     - 运行测试
│
│   turn/completed
│
├── 轮次 3
│   用户：
│     “创建一个拉取请求。”
│
│   代理：
│     - 提交更改
│     - 推送到 Git
│     - 创建拉取请求
│
│   turn/completed
│
└── 线程结束

Thread（线程）大致相当于一个 Codex 命令行会话，而 Turn（轮次）代表用户与代理之间的一次单独交换。

动手实践

默认情况下，Codex 应用服务器通过标准输入接受 JSON-RPC 消息。

如果你将以下 JSON 复制并粘贴到正在运行的服务器中（在将其转换为单行 JSONL 消息后），你将能够与持久的 Codex 代理进行交互。

{
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "tutorial",
      "title": "Tutorial Client"
    }
  }
}