TIL of linhan.dev
← All posts

用 Portkey 给 Codex 接上多 API 自动切换

linhan.devEdit

跑 Codex 或 agent 长任务时，单个 API 很容易碰到限流、临时故障、服务不可用。任务一停，你就得自己处理：等恢复，或手动换 API，再继续跑。

如果你手里有多个可用 API，可以把它们接到 Portkey。Codex 只连 Portkey。某个 API 请求失败时，Portkey 会按配置换下一个再试，减少你手动切换上游的次数，长任务更少中途停住。

就算暂时只有一个 API，也建议在 Portkey 里配重试。限流和短时 5xx 很常见，不加重试，稳定性会差很多。

Portkey 是什么

Portkey 是 Codex 和上游 API 之间的一层中转。

┌─────────┐
│  Codex  │
└────┬────┘
     │
     v
┌─────────┐
│ Portkey │
└────┬────┘
     │
     ├──────────────┬──────────────┐
     v              v              v
┌─────────┐   ┌─────────┐   ┌─────────┐
│  API 1  │   │  API 2  │   │  API 3  │
└─────────┘   └─────────┘   └─────────┘

Codex 不再直接连各个中转站。Portkey 按顺序使用上游：当前 API 失败，并且错误码在你设定的范围内，就换下一个。它做的是失败后自动切换，不是按权重分流量。

前提有两条：上游要支持 Codex 用的 responses 接口；Codex 里填的模型名，上游也要认。这份 config 还要绑到你实际在用的 Portkey key 上，否则 Codex 连了 Portkey，也不会走到这套切换逻辑。

Portkey 配置

把下面这份配置放进 Portkey（Configs 页面新建），把地址和 key 换成你自己的。custom_host 要带上 /v1。

{
  "strategy": {
    "mode": "fallback",
    "on_status_codes": [429, 500, 502, 503, 504]
  },
  "targets": [
    {
      "provider": "openai",
      "custom_host": "https://api1.example.com/v1",
      "api_key": "sk-xxx",
      "retry": {
        "attempts": 3
      }
    },
    {
      "provider": "openai",
      "custom_host": "https://api2.example.com/v1",
      "api_key": "sk-xxx",
      "retry": {
        "attempts": 3
      }
    },
    {
      "provider": "openai",
      "custom_host": "https://api3.example.com/v1",
      "api_key": "sk-xxx",
      "retry": {
        "attempts": 3
      }
    }
  ]
}

这套配置做两件事：

  1. 单个 API 先重试。当前上游失败时，先按 attempts 重试。
  2. 还不行再切下一个。按 targets 的顺序往下试。

把 Config 绑到 Portkey Key

Codex 只会发 Authorization: Bearer <key>，不会带 x-portkey-config。所以要把上面的 Config 设成这个 key 的默认配置，请求才会自动走 fallback。

  1. 在 Portkey 控制台打开 Configs，新建并保存上面的 JSON，记下 Config ID（或名称）。
  2. 打开 API Keys，创建或编辑你要用的 key。
  3. 在 key 设置里把 Default Config 选成刚才那份 Config，保存。
  4. Codex 里 env_key 对应的环境变量，填的就是这个 key。

之后只要用这个 key 访问 https://api.portkey.ai/v1，Portkey 会自动套用 fallback 和重试，不用在 Codex 里再配自定义 header。

Codex 配置

改 ~/.codex/config.toml。Portkey 支持标准 auth header，所以直接用环境变量传 key。

model_provider = "OpenAI"
model = "gpt-5.5"
model_reasoning_effort = "high"

[model_providers.OpenAI]
name = "OpenAI"
wire_api = "responses"
base_url = "https://api.portkey.ai/v1"
env_key = "PORTKEY_GPT_API_KEY"

export PORTKEY_GPT_API_KEY="xxxxxxxx"

base_url 指到 Portkey，wire_api 填 responses，env_key 指向存放 Portkey key 的环境变量。model 换成你实际上游支持的模型名。这个 key 必须已经绑好 Default Config。

配完之后，Codex 侧只维护一个 provider。API 的重试和自动切换，交给 Portkey 处理。

在线参考文档

Portkey

Codex