RealRelay.ai
编码智能体

Codex CLI 接入指南

通过 OpenAI Responses 端点把 OpenAI Codex CLI 接入 RealRelay.ai：安装、在 config.toml 中添加自定义模型提供商、检查连接并选择模型。

创建 API 密钥浏览目录
协议
OpenAI Responses
基础地址
https://www.realrelay.ai/v1
官方文档
learn.chatgpt.com
已对照工具官方文档核对
2026-10
实验性. 尚未在 RealRelay.ai 上端到端跑通。步骤依据该工具的官方文档；如果某一步失败，请带上错误信息联系支持。

概览

Codex CLI 是 OpenAI 推出的终端编码智能体。它在你的代码仓库中工作，在你授予的权限范围内编辑文件、运行命令。Codex 只支持 OpenAI Responses 协议，因此接入的是 RealRelay.ai 的 /v1/responses 端点。

  • 一个从控制台的 API 密钥页面获取的 API 密钥。

  • 基础地址带 /v1。Codex 会在后面拼上 /responses。

  • 一个 RealRelay.ai 在 Responses 上提供的模型 ID，例如 openai/gpt-5.3-codex。目录中的大多数模型只支持 Chat Completions，无法在 Codex 中使用。

本指南为实验性。RealRelay.ai 不提供 Codex 模型目录，所以 Codex 会以回退元数据运行所有 RealRelay.ai 模型，并为此打印一条警告。上下文窗口需要你自己设置，依赖目录元数据的功能，表现可能与 OpenAI 自家服务不同。

安装

任选一种 OpenAI 提供的安装方式。在 Windows 上请使用 npm；OpenAI 的 Codex 页面也列出了独立的 PowerShell 安装程序。

macOS · Linux
curl -fsSL https://chatgpt.com/codex/install.sh | shcodex --version
Homebrew
brew install --cask codexcodex --version
npm
npm install -g @openai/codexcodex --version

如果 codex --version 输出了版本号，说明安装成功。使用自定义提供商时，无需登录 ChatGPT。

配置

  1. 1

    添加提供商

    打开 ~/.codex/config.toml（Windows 上为 %USERPROFILE%\.codex\config.toml），合并进下面这几行。如果文件里已经设置了 model 或 model_provider，请替换原有的行，不要再加一份。

    ~/.codex/config.toml
    1# Top-level keys first: anything below a [table] header belongs to that table.2model = "openai/gpt-5.3-codex"3model_provider = "realrelay"4web_search = "disabled"5# Codex has no built-in metadata for RealRelay.ai model IDs. Set these to the6# limits on the model's catalog page.7model_context_window = 4000008model_auto_compact_token_limit = 300000910[model_providers.realrelay]11name = "RealRelay.ai"12base_url = "https://www.realrelay.ai/v1"13wire_api = "responses"14env_key = "REALRELAY_API_KEY"
  2. 2

    把密钥放进环境变量

    Codex 从 env_key 指定的变量中读取密钥。把 sk-*** 替换成你的密钥。

    ~/.zshrc · ~/.bashrc
    export REALRELAY_API_KEY="sk-***"

    运行 source ~/.zshrc，或者新开一个终端。

    Windows PowerShell
    [Environment]::SetEnvironmentVariable("REALRELAY_API_KEY", "sk-***", "User")

    完成后关闭并重新打开终端。

  • model、model_provider 和 web_search 必须写在第一个 [table] 表头之前。写在表头之后的键属于那张表，Codex 会忽略它，而且不报错。

  • 提供商需要有自己的 ID。openai、ollama 和 lmstudio 是保留名，所以示例使用 realrelay。

  • wire_api = "responses" 是当前 Codex 唯一接受的值。旧指南里使用 "chat" 的写法已经失效。

  • web_search = "disabled" 会移除 Codex 的网页搜索工具，OpenAI 建议在首次测试网关时这样做。

  • 不要把密钥写进 config.toml。Codex 桌面应用看不到只在终端里 export 的变量。

验证

  1. 1

    直接调用端点

    在已设置密钥的终端里运行这条命令。如果返回的 JSON 包含 "object": "response"，说明地址、密钥和模型在 Responses 上都没问题。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/responses" \2  -H "Authorization: Bearer $REALRELAY_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model": "openai/gpt-5.3-codex", "input": "Reply with OK"}'
  2. 2

    运行诊断

    codex doctor 会检查配置。auth 一行应显示你的变量为 (present)，推理 URL 应可访问。探测返回 HTTP 404 或 401 是正常的，这说明 TLS 和路由都通了。

    Terminal
    codex doctor | grep -E 'auth|reachab'
  3. 3

    发送第一条消息

    在项目中启动 Codex 并运行 /status。它应显示 realrelay 提供商和你的模型。然后发送测试提示词，回复应为 gateway-ok。该请求也会出现在控制台的用量日志中。

    Codex CLI
    1cd /path/to/your/project2codex3/status4Reply with exactly: gateway-ok

模型

/model 选择器列出的是 Codex 自带目录中的模型，所以 RealRelay.ai 的模型 ID 通常不会出现在那里。要切换模型，请修改 config.toml 中的 model，或者用 -m 启动 Codex，只对本次会话生效：

Terminal
codex -m openai/gpt-5.3-codex

只有在 /v1/responses 上提供的模型能在 Codex 中使用：openai/gpt-5.3-codex、openai/*-pro 系列模型，以及 xai/grok-* 文本模型。当前列表见选择模型。普通的 openai/gpt-5.x、Claude、GLM、Kimi 及其他系列只支持 Chat Completions。

由于 Codex 没有这些 ID 的元数据，请把 model_context_window 设为模型目录页上标注的窗口大小，并让 model_auto_compact_token_limit 低于它。示例中的数值适用于 openai/gpt-5.3-codex（400,000 token）。

故障排查

  • “wire_api = "chat" is no longer supported”。配置来自旧版指南。请设置 wire_api = "responses"。

  • codex doctor 提示缺少 auth 环境变量。终端是在你添加密钥之前打开的。运行 source ~/.zshrc 或新开一个终端。如果是桌面应用，请把变量设置在应用能看到的地方，然后重启应用。

  • 401“Invalid token”。密钥有误或已被删除。从控制台重新复制。

  • “Model metadata for … not found. Defaulting to fallback metadata”。使用 RealRelay.ai 时这是预期行为，因为它没有 Codex 目录。请求照常可用；按“模型”一节所示设置上下文窗口即可。

  • 第一条消息就报出与模型相关的错误。该模型不在 Responses 上提供，或者 ID 拼错了。从“模型”一节的列表中选一个，并原样复制 ID。

  • 你设置的提供商或模型没有生效。/status 显示的是别的内容。检查顶层键是否位于 [model_providers.realrelay] 之上，并确认没有 profile 覆盖它们。

  • curl 正常，但 Codex 报“TLS handshake or certificate validation failed”。当 Codex 内置的证书库还没有收录签发本站证书的根证书时，就可能出现这种情况。让 Codex 改用系统证书，新开一个终端，再运行一次 codex doctor。更新 Codex 也可能解决问题。

    ~/.zshrc (macOS)
    export SSL_CERT_FILE=/etc/ssl/cert.pem
    ~/.bashrc (Debian · Ubuntu)
    export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt