接入 Codex 使用指南

0. 一句话结论

平台已实现 OpenAI Responses API 端点 POST /v1/responses,且实现时明确按 Codex 需求设计(流式 SSE 事件序列、function 工具调用、store:false 无状态兼容)。 因此 Codex CLI 有两种接入方式:

1. 直连(推荐):在 ~/.codex/config.toml 里配置 wire_api = "responses",直接走 /v1/responses;
2. cc-switch:用图形化工具一键切换 Codex / Claude Code 等的 provider。

两种方式计费完全一致(同一套预扣→路由→结算→账本管线)。

1. 前置条件

2. 平台侧能力与边界(/v1/responses)

• 端点:POST https://routeall.ai/v1/responses
• 鉴权:Authorization: Bearer sk-ra-...

2.1 支持(Codex 兼容)

2.2 边界(无状态文本子集)

2.3 计费与错误

• 计费:与 /v1/chat/completions 完全同一管线,实测 charge 平价;响应头 X-RouteAll-Charge-Credit 为零售计费额(非成本)。
• 错误信封:{ "error": { "message", "type", "code", "param" } };HTTP 状态:401(无/错 key)、402(余额不足)、429(限流)、400(参数畸形)、503(上游全挂)。

3. 方式一:Codex CLI 直连(Responses API,推荐)

3.1 配置 ~/.codex/config.toml

model = "deepseek-v4-pro"           # 默认模型,换成广场里的规范名
model_provider = "routeall"

[model_providers.routeall]
name = "RouteAll"
base_url = "https://routeall.ai/v1" # 平台 OpenAI 兼容 base URL(不带 /responses)
env_key = "ROUTEALL_API_KEY"
wire_api = "responses"              # responses = 走 /v1/responses(推荐)

3.2 设置环境变量

# Linux / macOS
export ROUTEALL_API_KEY="sk-ra-你的KEY"

# Windows PowerShell
# $env:ROUTEALL_API_KEY = "sk-ra-你的KEY"

3.3 启动

codex

3.4 临时切换模型

codex --model Codex-haiku-4-5 "重构一下这个模块"
codex --model deepseek-v4-flash "解释这段正则"

3.5 关于 wire_api

备注:网关 api. 子域当前未对外启用(服务器 PUBLIC_API_DOMAIN=api.localhost 内部);/v1/* 由主站 routeall.ai 直接提供服务,故 base_url 用 https://routeall.ai/v1。

4. 方式二:cc-switch(图形化一键切换)

cc-switch 是开源供应商切换工具(farion1231/cc-switch),可管理 Codex / Claude Code / OpenCode / Gemini 等的 provider 配置并一键切换。

4.1 安装

GitHub farion1231/cc-switch → Releases 下载对应系统安装包(Windows / macOS / Linux)。

4.2 新增供应商

1. 打开 cc-switch,切到 Codex 标签页 →「新增供应商」;
2. 填写:
   • 供应商名称:RouteAll(随意)
   • API Host / Base URL:https://routeall.ai/v1
   • API Key:sk-ra-你的KEY
   • 模型列表:平台规范模型名(如 deepseek-v4-pro、Codex-haiku-4-5,可多行)
3. 保存。

4.3 应用切换

选中 RouteAll →「切换 / 启用」。cc-switch 会把 provider 配置写入 ~/.codex/config.toml(等价于方式一的配置),之后正常 codex 启动即可。

注:cc-switch 部分版本会把 Codex 的协议改写为 /v1/chat/completions(即 wire_api = "chat")。平台两条路都通(B15 已修复工具型客户端走 chat 的 400);若你的版本支持选协议,选 Responses 更贴合原生。

5. 验证

5.1 拉取可用模型列表(以列表为准,不要猜模型名)

curl https://routeall.ai/v1/models \
  -H "Authorization: Bearer sk-ra-你的KEY"
# 或公开目录(免鉴权,只列有渠道的模型)
curl https://routeall.ai/v1/public/models

5.2 非流式(先验证链路通不通)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "你好,请用一句话介绍你自己",
    "max_output_tokens": 200
  }'

成功返回 Responses 格式(output[].content[].output_text + output_text + usage)。

5.3 流式(Codex 实际形态)

curl -N https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "讲个简短的笑话",
    "stream": true
  }'

事件顺序:response.created → output_item.added → output_text.delta ×N → output_item.done → response.completed。

5.4 工具调用(agentic loop 形态)

curl https://routeall.ai/v1/responses \
  -H "Authorization: Bearer sk-ra-你的KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": [{"role": "user", "content": "帮我算 17*23"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "calculator",
        "description": "执行四则运算",
        "parameters": {
          "type": "object",
          "properties": { "expr": { "type": "string" } }
        }
      }
    }],
    "tool_choice": "auto"
  }'

output 会包含 type: "function_call" 项(call_id / name / arguments),随后可再发 function_call_output 项回灌结果继续多轮。

6. 排错

7. 计费与安全提示

• 计费口径:模型官方价 × 用户组倍率;流式按真实 usage 结算;缓存命中按全价收(B12 策略,缓存价差归平台,客户 charge 不降)。
• 计费可见性:响应头 X-RouteAll-Charge-Credit(零售额);cost/margin 永不进用户侧响应(INV-8)。
• Key 安全:sk-ra- 只存 sha256、后台不可见;绝不要嵌进客户端 / 仓库。
• 建议先拿小模型(curl 验证)跑通链路,再切 Codex / 长任务。