---
title: "通过 Cloudflare AI Gateway 连接模型服务"
summary: "官方主路径是 ~/.codex/cloudflare-aig.config.toml 加 [model_providers.cloudflare-ai-gateway]，wire_api = responses，env_key = CLOUDFLARE_API_KEY。base_url 不展开环境变量，账号 ID 和网关 slug 要写死。"
category: config
level: intermediate
surfaces: [cli, app]
tags: ["model_providers", "Cloudflare", "wire_api", "profile"]
canonical: /tips/cloudflare-aig-codex-gateway/
---

# 通过 Cloudflare AI Gateway 连接模型服务

官方主路径是 ~/.codex/cloudflare-aig.config.toml 加 [model_providers.cloudflare-ai-gateway]，wire_api = responses，env_key = CLOUDFLARE_API_KEY。base_url 不展开环境变量，账号 ID 和网关 slug 要写死。

Cloudflare AI Gateway 官方 Codex 网关：profile 写 [model_providers.cloudflare-ai-gateway]，base_url 是 https://gateway.ai.cloudflare.com/v1/ACCOUNT_ID/GATEWAY_ID/openai，env_key 读 CLOUDFLARE_API_KEY。

这是换 Codex **使用的模型**，不是添加 MCP 服务。请求打到 AI Gateway 的 OpenAI 入口，用 Cloudflare API token 走 Unified Billing，不要塞 OpenAI 密钥。自定义供应商只讲 Responses：只能用支持 Responses 的 OpenAI 模型（官方示例 `gpt-5.5`）。Anthropic / Google 不会走这套请求格式，配了也不通。

官方把供应商表写进 **profile 文件**（用户层 `$CODEX_HOME`，不是项目 `.codex`）：

```toml
# ~/.codex/cloudflare-aig.config.toml
model_provider = "cloudflare-ai-gateway"
model = "gpt-5.5"
model_reasoning_effort = "medium"

[model_providers.cloudflare-ai-gateway]
name = "Cloudflare AI Gateway"
base_url = "https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/default/openai"
env_key = "CLOUDFLARE_API_KEY"
wire_api = "responses"
```

`YOUR_ACCOUNT_ID` 用 `wrangler whoami` 的账号 ID 替换。网关 slug 可以是 `default`，或你仪表盘里的另一个 slug。**Codex 不会在 `base_url` 里展开环境变量**，不要抄 Pi 那种把 `CLOUDFLARE_ACCOUNT_ID` 塞进 URL 的写法。只有 `CLOUDFLARE_API_KEY` 从环境读。

`env_key` 是变量**名**。值是带 `AI Gateway` 权限的 Cloudflare API token（`wrangler auth token`），不是 OpenAI key。必须出现在**启动 Codex 的那个进程**里。从已经 `export CLOUDFLARE_API_KEY` 的终端启动；Dock 打开的桌面不会读你刚改的 zshrc。先为账号充值 Unified Billing 额度。

```bash
codex --profile cloudflare-aig
```

0.134 起不要再写 `[profiles.cloudflare-aig]`。profile 名跟文件名 `cloudflare-aig.config.toml` 对齐。供应商表也可以放进用户 `~/.codex/config.toml`，但不要写进项目 `.codex/config.toml`：项目文件无法修改 `model_provider` / `model_providers`。

网关若开了 Cloudflare Access，官方改走自定义域名和 `auth` 命令，**替换** `env_key`，避免重复配置：

```toml
[model_providers.cloudflare-ai-gateway]
name = "Cloudflare AI Gateway"
base_url = "https://ai-gateway.example.com/openai"
wire_api = "responses"

[model_providers.cloudflare-ai-gateway.auth]
command = "cloudflared"
args = ["access", "login", "--no-verbose", "https://ai-gateway.example.com"]
timeout_ms = 30000
refresh_interval_ms = 0
```

Learn 写明 `auth` 不要和 `env_key` / `experimental_bearer_token` / `requires_openai_auth` 叠。第一次请求会弹身份登录。把 `ai-gateway.example.com` 换成你的自定义域。

配置说明：

- 不要把这张表当成 `plugin marketplace add cloudflare/skills` 或 `mcp add cloudflare --url https://mcp.cloudflare.com/mcp`。那是管 Workers / 平台 MCP，不是换模型。
- Pi 会自己拼账号 ID；Claude 走另一套 base URL。
- 不要写 `base_url` 到 `/compat`。Codex 要 `/openai` 加 `wire_api = "responses"`。
- 不要写 `wire_api = "chat"`。
- 不要覆盖内置 ID `openai`、`ollama`、`lmstudio`。`cloudflare-ai-gateway` 是新 ID，可以。
- 不要把密钥写进 `http_headers`。

改完新开会话。`codex --profile cloudflare-aig` 启动后，发送一条简短请求验证连接。用量看 Cloudflare 仪表盘 AI Gateway → Logs。

## 来源

- [Cloudflare · OpenAI Codex](https://developers.cloudflare.com/ai-gateway/integrations/coding-agents/openai-codex/)
- [Cloudflare · Coding agents](https://developers.cloudflare.com/ai-gateway/integrations/coding-agents/)
- [Cloudflare · Unified Billing](https://developers.cloudflare.com/ai-gateway/features/unified-billing/)