SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场codex-app-server

codex-app-server

编程与开发

查看项目

更新于 10-15 10:34

技能介绍

用途

Codex App Server 是 Codex 用于驱动富客户端（如 IDE 扩展和合作方集成）的、对客户端友好的 JSON-RPC 接口。它把 Codex 线程作为持久运行时会话托管在双向协议之后，并将较低层的 harness 活动转换为可直接用于 UI 的 thread、turn、item、delta 和 approval 事件。客户端因此可以在不同界面之间复用同一套 Codex harness，而无需重新实现智能体循环。

当需要认证、会话历史、审批、流式智能体事件、技能、应用/连接器、MCP 状态或配置/认证流程时，它是首选的集成面。如果任务是一次性自动化、批处理或 CI，则应优先使用 Codex SDK，而不是 App Server。

核心心智模型

  • 传输层为 JSON-RPC 2.0，线上省略 jsonrpc 头。
  • 默认传输为 stdio，使用换行分隔的 JSON 消息。
  • WebSocket 传输通过 --listen ws://IP:PORT 启用，但属于实验性且不受支持；除非官方文档另有说明，否则应使用回环地址或经 SSH 转发的监听器。
  • 工作发生在持久线程（thread）中，线程由轮次（turn）组成，轮次由条目（item）组成。
  • 条目在轮次期间流式传输，并以最终状态事件完成。
  • 服务器可以向客户端请求审批；客户端必须响应。
  • 某些方法和字段需要 initialize.params.capabilities.experimentalApi = true；除非调用方明确选择启用，否则不要在稳定客户端中使用它们。

实现默认约定

  • 不要构建并行的智能体循环；直接使用 App Server 原语。
  • 不要仅为运行无人值守任务而使用 App Server；自动化和 CI 优先使用 Codex SDK。
  • 尽可能在同一线程内保持模型/工具/运行时设置稳定。
  • 持久化 threadId 并恢复线程，而不是重建上下文。
  • 对客户端发送的任何工具列表，优先采用确定性排序。
  • 通过 initialize.params.clientInfo.name 标识客户端；企业集成可能需要 OpenAI 识别该客户端名称以用于合规日志。
  • 将生成的 TypeScript 和 JSON Schema 输出视为特定于生成本地 Codex 二进制文件的版本。
  • 在 WebSocket 模式下，在将任何内容暴露到回环之外前先配置认证；优先使用令牌文件而非命令行 bearer 令牌。

使用方式

本地探测工作流

当需要已安装构建特有的协议面、方法名、请求模式或运行时可发现状态时，使用本地 Codex 二进制文件。

首选本地探测方式：

  • python3 scripts/probe_app_server.py，用于合并的本地 schema 与运行时摘要
  • codex app-server generate-json-schema --out <dir>，用于精确的本地 JSON Schema 包
  • codex app-server generate-ts --out <dir>，用于生成的本地 TypeScript 协议绑定
  • 使用 codex app-server 的实时 stdio 会话，用于握手和请求/响应探测

在 initialize + initialized 之后有用的实时请求：

  • account/read
  • model/list
  • thread/list
  • thread/start
  • thread/resume
  • thread/read
  • turn/start
  • turn/steer
  • turn/interrupt
  • command/exec
  • config/read
  • mcpServerStatus/list
  • plugin/list
  • skills/list
  • app/list
  • experimentalFeature/list
  • config/mcpServer/reload

使用本地探测来了解：

  • 已安装二进制文件实际支持什么
  • 该构建的精确请求和响应形状
  • 运行时可见的 MCP 服务器、技能、模型、应用/连接器、插件、账户、配置层和实验性功能

使用官方文档 MCP 来了解：

  • 最新记录的行为
  • 集成指南和语义
  • 当前官方建议和兼容性指南

使用 MCP 的场景

  • 传输行为和支持的模式
  • WebSocket 认证、健康探测、背压和重试指南
  • thread、turn 和 item 生命周期细节
  • 审批请求负载和可用决策
  • 动态工具和实验性 API 行为
  • auth/account、速率限制、配置、插件、应用、技能、文件系统和命令执行方法
  • 配置键、认证行为和集成面变更
  • 用户表述为最新、当前、精确或最新的任何内容

参考策略

  • 当需要 App Server 是什么以及为何存在的概念模型时，从本文件加上 references/unlocking-the-codex-harness-high-level.md 开始。
  • 当问题涉及本地安装的 Codex 二进制文件的精确行为时，先运行 scripts/probe_app_server.py 或直接探测本地 app server，再根据文档进行泛化。
  • 对于已安装二进制文件之外的精确当前产品行为，在回答前通过 MCP（openaiDeveloperDocs）获取官方文档。
  • 如果文档在架构或动机方面较薄弱，使用本地概念参考在高层次解释系统，但不要覆盖官方协议细节。
  • 如果任务涉及自动化、作业或 CI，在推荐 App Server 之前先查看当前 Codex SDK 文档。

主要参考

  • 本地高层架构参考：references/unlocking-the-codex-harness-high-level.md
  • 本地探测脚本：scripts/probe_app_server.py
  • 通过 MCP 的官方文档（openaiDeveloperDocs）
  • 实时上游 README（快照的最新来源）：https://raw.githubusercontent.com/openai/codex/refs/heads/main/codex-rs/app-server/README.md
  • App Server 文档：https://developers.openai.com/codex/app-server/
  • CLI 参考：https://developers.openai.com/codex/cli/reference/#codex-app-server

归档快照

本地 README 快照不属于活动参考路径。仅作归档辅助：references/openai-codex-app-server-readme-reference.md。保留它用于离线阅读或历史比较，不作为事实来源决策依据。

限制

  • WebSocket 传输为实验性且不受支持。
  • 部分方法和字段需要 experimentalApi 能力标志，稳定客户端不应默认使用。
  • 生成的 TypeScript 和 JSON Schema 输出与生成本地 Codex 二进制文件的版本绑定。
  • 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。