
>**核心功能**：通过 Cloudflare AI Gateway 代理 Anthropic (Claude) 等模型请求，实现**统一鉴权、请求缓存、用量分析**及**速率限制**。
**适用场景**：企业级部署、多团队共享 API 额度、需要审计日志或降低延迟的场景。
**支持模型**：主要支持通过 Gateway 转发的 Anthropic Claude 系列模型。


----

## 🏗️ 一、架构与原理


Cloudflare AI Gateway 充当了 OpenClaw 与大模型提供商（如 Anthropic）之间的**智能中间层**。
![image.png](https://developer.qcloudimg.com/http-save/yehe-2276240/f93544129fee0ad49ca89fa0661ea25e.png)

- **Provider ID**: `cloudflare-ai-gateway`

- **基础 URL 格式**: `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic`

- **默认模型**: `cloudflare-ai-gateway/claude-sonnet-4-5` (需在 Gateway 中映射)


>💡 **核心价值**：
1. **缓存加速**：自动缓存重复提示词，降低 Token 成本。
2. **安全隔离**：OpenClaw 只需持有 Gateway Key，无需暴露原始 Anthropic API Key。
3. **可观测性**：在 Cloudflare Dashboard 查看完整的请求日志和用量统计。


----

## 🔑 二、前置准备


在配置 OpenClaw 之前，请确保你已完成以下 Cloudflare 侧的设置：


1. **创建 AI Gateway**：登录 Cloudflare Dashboard -> AI -> Gateway -> Create Gateway。

2. **获取凭证**：
	- **Account ID** (`CF_ACCOUNT_ID`)
	- **Gateway ID** (`CF_GATEWAY_ID`)
	- **API Token** (`CLOUDFLARE_AI_GATEWAY_API_KEY`)：需拥有 `AI Gateway:Edit` 权限。

3. **配置上游认证**：
	- 在 Gateway 设置中，填入你的 **Anthropic API Key**。
	- 注意：OpenClaw 发送请求给 Gateway 时使用的是 Cloudflare 的 Key，但 Gateway 转发给 Anthropic 时需要它自己配置的 Key。

4. **模型映射**：确保在 Gateway 中启用了所需的 Claude 模型（如 `claude-sonnet-4-5`）。


----

## 🚀 三、快速开始 (CLI 配置)


### 方式 A：交互式配置 (推荐)


运行 Onboarding 向导，选择 Cloudflare AI Gateway 选项：

```
openclaw onboard --auth-choice cloudflare-ai-gateway-api-key
```
按提示输入 Account ID, Gateway ID 和 API Key。

### 方式 B：非交互式配置 (适合 CI/CD 或脚本)


```
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
```
### 配置文件验证 (`openclaw.json`)


配置完成后，检查 `env` 和 `agents` 部分：

```
{
  "env": {
    // 这是访问 Cloudflare Gateway 的密钥，而非 Anthropic 原始密钥
    "CLOUDFLARE_AI_GATEWAY_API_KEY": "v1-..." 
  },
  "agents": {
    "defaults": {
      "model": {
        // 格式：cloudflare-ai-gateway/<gateway-model-name>
        "primary": "cloudflare-ai-gateway/claude-sonnet-4-5"
      }
    }
  }
}
```


----

## 🔐 四、高级配置：网关级鉴权


如果你在 Cloudflare AI Gateway 上启用了额外的**入口鉴权**（即要求调用 Gateway 的客户端也提供 Token），需要添加自定义 Header。

### 配置自定义 Header


在 `models.providers` 中添加 `cf-aig-authorization`：

```
{
  "models": {
    "providers": {
      "cloudflare-ai-gateway": {
        "headers": {
          // 格式：Bearer <你的网关访问令牌>
          "cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>"
        }
      }
    }
  }
}
```
>**注意**：这与 `CLOUDFLARE_AI_GATEWAY_API_KEY` 是两层不同的鉴权。
- `CLOUDFLARE_AI_GATEWAY_API_KEY` (环境变量): 用于 OpenClaw 识别 Provider 并构建基础请求。
- `cf-aig-authorization` (Header): 用于通过 Gateway 设置的额外防火墙规则。


----

## ⚙️ 五、环境变量与守护进程注意事项


如果 OpenClaw Gateway 作为系统服务运行（如 macOS 的 `launchd` 或 Linux 的 `systemd`），它可能无法读取用户 Shell 中的环境变量。

### 解决方案


1. **使用 `.env` 文件** (推荐)：
	将密钥写入 OpenClaw 的配置目录：
	```
	echo "CLOUDFLARE_AI_GATEWAY_API_KEY=v1-..." >> ~/.openclaw/.env
	```

2. **配置 Shell 环境**：
	在 `openclaw.json` 中指定 `env.shellEnv`，或在服务配置文件中显式加载环境变量。

3. **验证生效**：
	重启 Gateway 后，运行以下命令确认模型状态：
	```
	openclaw models status
	```


----

## 📊 六、常用模型映射参考


在 OpenClaw 中引用模型时，前缀必须是 `cloudflare-ai-gateway/`，后缀需与你在 Cloudflare Dashboard 中配置的模型名称一致。


|Cloudflare模型名称|OpenClaw配置ID|对应上游模型|
|:-:|:-:|:-:|
|`claude-sonnet-4-5`|`cloudflare-ai-gateway/claude-sonnet-4-5`|Claude Sonnet 4.5|
|`claude-opus-4`|`cloudflare-ai-gateway/claude-opus-4`|Claude Opus 4|
|`claude-haiku-4`|`cloudflare-ai-gateway/claude-haiku-4`|Claude Haiku 4|

>💡 **提示**：你可以在 Cloudflare Dashboard 的 "Models" 页面自定义模型名称，然后在 OpenClaw 中对应修改。


----

## 🛠️ 七、故障排查


|问题|可能原因|解决方案|
|:-:|:-:|:-:|
|**401 Unauthorized**|Gateway API Key 错误或过期|检查 `CLOUDFLARE_AI_GATEWAY_API_KEY` 环境变量；在 CF Dashboard 重新生成 Token。|
|**403 Forbidden**|缺少 `cf-aig-authorization` 或 IP 被拒|检查是否需要在 config 中添加自定义 Header；检查 CF Firewall 规则。|
|**Model not found**|模型名称不匹配|确认 OpenClaw 中的模型后缀与 CF Dashboard 中完全一致（区分大小写）。|
|**Upstream Error**|Gateway 配置的 Anthropic Key 无效|登录 CF Dashboard -> AI Gateway -> Providers，检查上游 Anthropic Key 是否正确。|
|**Cache Miss**|未命中缓存|检查 Prompt 是否完全一致；确认 Gateway 中已启用 Cache 功能。|


----

## 💡 八、最佳实践


1. **密钥管理**：永远不要在代码库中硬编码 `CLOUDFLARE_AI_GATEWAY_API_KEY`，务必使用环境变量或加密的 `.env` 文件。

2. **利用缓存**：在 Cloudflare Dashboard 中针对 System Prompt 开启缓存，可显著降低重复任务的 Token 消耗。

3. **监控告警**：利用 Cloudflare 的分析面板设置用量告警，防止异常流量导致费用激增。

4. **灰度发布**：通过在 Gateway 层调整流量权重，可以无缝切换底层模型（如从 Sonnet 切换到 Opus），而无需修改 OpenClaw 代码。


通过 Cloudflare AI Gateway，OpenClaw 能够获得企业级的稳定性与可观测性，是构建生产级 AI 应用的理想选择。🛡️📈

核心功能：通过 Cloudflare AI Gateway 代理 Anthropic (Claude) 等模型请求，实现统一鉴权、请求缓存、用量分析及速率限制。

OpenClaw 集成 Cloudflare AI Gateway 指南

通过 Cloudflare AI Gateway 代理 Anthropic (Claude) 等模型请求，实现统一鉴权、请求缓存、用量分析及速率限制。

云计算

人工智能

网络与通信

Cloudflare AI Gateway代理Anthropic Claude模型，提供统一鉴权、请求缓存和用量分析功能。支持企业级部署，降低延迟并提升安全性。配置简单，通过Account ID、Gateway ID和API Key即可快速接入。内置故障排查工具，优化AI应用性能，是生产环境理想选择。

密钥管理

防火墙

Linux

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

OpenClaw 集成 Cloudflare AI Gateway 指南-腾讯云开发者社区-腾讯云

OpenClaw 集成 Cloudflare AI Gateway 指南

OpenClaw 集成 Cloudflare AI Gateway 指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐