𝐗𝐀𝐈

Codex Manual

接入 XAI Router

如果你希望把 Codex 纳入统一 API、账号、额度和模型治理，使用 XAI Router 会更容易维护。

基础配置

在 ~/.codex/config.toml 中加入：

model_provider = "xai"
model = "gpt-5.6-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[features]
api_key_model_discovery = true

[model_providers.xai]
name = "xai"
base_url = "https://api.xairouter.com"
model_catalog_url = "https://api.xairouter.com/models"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"
supports_websockets = false
http_headers = { "x-codex-routing-hint" = "model=gpt-5.6-sol" }

设置 Key：

export XAI_API_KEY="sk-Xvs..."
codex

PowerShell：

$env:XAI_API_KEY="sk-Xvs..."
codex

原生模型目录

请使用支持远程模型发现的 Codex CLI 或 Codex App，按上面的示例同时配置 api_key_model_discovery = true 和 model_catalog_url。使用远程模型目录时，移除已有的 model_catalog_json 静态目录配置。

设置好 XAI_API_KEY 后，重启客户端。在 CLI 中运行 /model，或在 App 中打开模型选择器，即可选择可用模型及其支持的推理等级。

HTTP、WebSocket 与路由提示

当前 Codex 自定义 Provider 使用 Responses 协议：

wire_api = "responses"

上面的默认配置显式使用 HTTP。如果希望开启 Responses WebSocket，只需改成：

supports_websockets = true

x-codex-routing-hint 是上游路由提示，不代替请求体里的 model。由于 XAI Router 使用自定义 API Key，Codex 不会为这类 Provider 自动生成该请求头，因此配置里先放一个静态值；Router 在转发前会把已存在的提示同步成最终映射后的模型和当前请求的服务等级。使用 codex --model ... 或 /model 切换模型时，不需要手动修改这个静态种子值。

原生协议、工作区与文件

启用远程模型目录后，客户端会按上游账号的模型能力选择 Responses Lite；HTTP 和 WebSocket 均保留这一选择。可选模型以该账号返回的目录为准。

使用 Codex → Router → codex-cloud 时，将上游 Key 的 provider_type 设置为 codex。codex-cloud 会为使用官方 ChatGPT 后端的账号自动解析工作区路由，并将 Responses、Compact 和 Responses WebSocket 请求发送到该账号对应的后端。客户端继续使用本文的 Router 地址。

支持原生文件协议的客户端或集成可按以下流程上传附件：

  1. 向 Router 的 POST /files（也支持 /v1/files）发送 JSON：file_name、file_size（字节数，最多 512 MiB）、use_case: "codex"。可通过 codex_model 指定后续使用的模型，上传请求保持相同的会话标识。
  2. 将文件内容直接 PUT 到返回的 upload_url，设置 x-ms-blob-type: BlockBlob。API Key 仅用于 Router 请求；签名上传地址自身包含上传凭据。
  3. 使用返回的完整 file_id 调用 POST /files/{file_id}/uploaded，提交 {}。若注册结果包含 pdf_c2pa_reservation: true，则提交 {"pdf_c2pa_create_request": 原始注册请求}。返回 status: "retry" 时继续确认，直到 status: "success"。
  4. 在后续 Responses 或图片编辑请求的 file_id 字段中使用这个完整 ID；需要文件 URI 的字段使用 sediment://{file_id}。HTTP、WebSocket 和 WebSocket 中途追加输入均由 Router 保持上传账号绑定。

同一请求中的多个文件应在同一会话、同一模型路由下上传，并使用同一用户的 API Key。保留 Router 返回的文件 ID；更换上游账号或 Provider 配置后重新上传。文件上传能力还取决于客户端开放的功能与登录方式；API Key 模式下按客户端支持的附件入口使用。

继续阅读

上一章 配置与登录