跳到正文
RunAPI 开发者文档
EN 中文
开发者资源
开发者资源

Codex App

在 Codex App 中将 RunAPI 配置为模型提供方，选择支持 Responses 的模型并验证连接。

查看 Markdown

概览

Codex 可在 Windows 和 macOS 的 ChatGPT desktop app 中使用。本指南将本地 Codex App 指向 RunAPI 的 OpenAI-compatible Responses endpoint，选择 RunAPI 模型并验证连接。

这项配置会改变生成回复和代码时使用的模型提供方，不会添加 RunAPI tools。Hosted MCP 是另一项集成，有独立的客户端与身份验证要求。

开始前准备

  • 安装当前版本的 ChatGPT desktop app，登录并至少打开一次 Codex。
  • 按照身份验证指南创建专用的标准 RunAPI API key。不要将 key 提交到代码仓库。
  • 从模型目录复制支持 Responses API 的模型准确 identifier。

以下步骤配置的是读取用户级配置的本地 Codex 客户端，不会配置托管的 Codex cloud task。

保存 API key

Desktop app 可能不会继承 shell 环境变量。创建或编辑 ~/.codex/.env，将 key 单独写在一行：

DOTENV 
export RUNAPI_API_KEY=YOUR_RUNAPI_API_KEY

让该文件始终位于代码仓库之外。在 macOS 和 Linux 上，将它限制为仅当前用户可读写：

SHELL 
chmod 600 ~/.codex/.env

配置 RunAPI

打开用户级 ~/.codex/config.toml。将以下值合并到现有文件中；不要覆盖无关设置，也不要重复已有的顶层 key：

TOML 
model = "YOUR_RUNAPI_MODEL_ID"
model_provider = "runapi"

[model_providers.runapi]
name = "RunAPI"
base_url = "https://runapi.ai/v1"
env_key = "RUNAPI_API_KEY"
wire_api = "responses"

模型提供方和身份验证设置必须放在用户级配置中。Codex 会忽略项目 .codex/config.toml 里的 model_provider 和 model_providers。TOML 只保存环境变量名称；API key 仍留在 ~/.codex/.env。

base_url 是 API 根地址，不是具体 operation URL。设置 wire_api = "responses" 后，Codex 会发送 POST /v1/responses。模型提供方 contract 请查看 OpenAI 的 custom model provider 配置。

选择模型

将 YOUR_RUNAPI_MODEL_ID 替换为从模型目录复制的准确 identifier。请选择提供 Responses API 的模型；仅支持 Chat Completions 不足以使用这份配置。

修改 model 后，请完全重启 app 并新建 task。已有 task 可能继续使用创建时的模型和提供方。

重启并验证

  1. 完全退出并重新打开 ChatGPT desktop app。
  2. 打开 Codex，在一个代码仓库中创建新 task。
  3. 发送一条短 prompt，例如 用一句话描述这个仓库。
  4. 确认 Codex 正常返回，并且 RunAPI 记录了所选模型的 POST /v1/responses 请求。

首次验证应保持简短，以便将配置错误与具体任务行为区分开。

添加 RunAPI tools

上面的模型提供方配置会让 Codex 通过 RunAPI 进行推理。MCP 是另一项能力：它可以让受支持的客户端调用 RunAPI tools，完成模型发现、账户信息查询和受支持的 task 工作流。

Hosted MCP 指南说明了当前支持的客户端与身份验证要求。Codex 专用的 Hosted MCP 身份验证尚未完成验证，因此本页不提供 Codex MCP 配置步骤。不要用 MCP server 配置替换模型提供方配置；两种集成解决的问题不同。

排查问题

  • Codex 仍在使用之前的提供方： 确认文件是 ~/.codex/config.toml，删除重复的 model 或 model_provider key，完全重启 app，并创建新 task。
  • 提示缺少 RUNAPI_API_KEY： 确认 key 位于 ~/.codex/.env，而不是只存在于终端 profile，然后重启 app。
  • 身份验证失败： 通过身份验证指南创建或轮换标准 key。不要将 key 粘贴到 config.toml 或支持日志中。
  • 请求返回 404： 将 base_url 设置为 https://runapi.ai/v1，而不是 https://runapi.ai/v1/responses。
  • 模型不可用或拒绝某个字段： 重新复制准确 identifier，并确认该模型支持 Responses API 和所需能力。
  • Codex 选择了其他模型： 检查 trusted project 的 .codex/config.toml 中是否存在 model override。项目配置可以选择模型，但不能替换用户级模型提供方。
  • CLI 可用但 app 失败： 检查 ~/.codex/.env，然后完全重启 app。GUI application 可能无法读取仅由 shell 导出的变量。
  • Cloud task 没有使用 RunAPI： 这份本地配置只适用于本地 Codex 客户端；托管的 cloud task 不会读取你电脑上的文件。

移除 RunAPI

  1. 从 ~/.codex/config.toml 删除 RunAPI 的 model、model_provider 和 [model_providers.runapi] 值，或恢复之前使用的提供方配置。
  2. 如果其他本地工具不再使用 RUNAPI_API_KEY，请从 ~/.codex/.env 删除它。
  3. 完全重启 app，并创建新 task。
  4. 不再需要专用 key 时，在 RunAPI 中撤销它。

下一步

通用协议行为请查看 LLM API 快速开始，准确的请求和响应字段请查看 Responses API 参考。还可继续查看模型目录、身份验证指南或 Hosted MCP。