三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

OpenClaw集成Cloudflare AI Gateway：构建稳定可控的AI智能体调用链路

发布时间：2026/8/16 12:57:49 三亩地 编程学习日记
OpenClaw集成Cloudflare AI Gateway：构建稳定可控的AI智能体调用链路

1. 项目概述：为什么要把OpenClaw和Cloudflare AI Gateway绑在一起？

如果你最近在折腾本地AI智能体，尤其是OpenClaw这个项目，那你大概率已经体验过它的强大和……偶尔的“调皮”。OpenClaw，这个被社区戏称为“小龙虾”的开源AI智能体框架，确实能帮你自动化处理很多事情，从客服问答到工作流编排。但当你把它部署到生产环境，或者希望多个团队成员稳定使用时，几个头疼的问题就冒出来了：大模型API的调用费用怎么精细控制？不同模型（比如GPT-4、Claude、本地Ollama里的Llama）的切换和管理太麻烦？还有，API的响应速度和稳定性，是不是总让你心里没底？

这时候，Cloudflare AI Gateway就该登场了。它不是一个新模型，而是一个智能的“流量调度中心”和“守门员”。简单说，你可以把所有对大模型API（无论是OpenAI、Anthropic，还是你自建的Ollama）的请求，都先发送到Cloudflare AI Gateway。由它来统一处理鉴权、限流、缓存、负载均衡，甚至帮你做日志分析和成本控制。对于OpenClaw这类需要频繁、稳定调用多种AI服务的应用来说，这简直是“雪中送炭”。

我自己的团队在把一个客服自动化项目从测试环境搬到线上时，就深刻体会到了直接裸连API的痛。突发流量导致账单激增、某个模型服务商临时抽风导致整个流程中断……这些问题，在集成了Cloudflare AI Gateway之后，都得到了显著的缓解。所以，这篇指南就是把我趟过的路、踩过的坑，以及最终跑通的配置，毫无保留地分享给你。无论你是个人开发者想优化自己的AI工作流，还是团队负责人需要为项目提供一个更可靠的后端，这篇内容都能给你一个清晰的路线图。

2. 核心组件解析：OpenClaw的架构与Cloudflare AI Gateway的定位

在动手连接两者之前，我们必须先搞清楚它们各自是干什么的，以及为什么它们能“对上眼”。这能帮你避免很多配置时的迷惑。

2.1 OpenClaw：你的本地AI智能体“大脑”

OpenClaw本质上是一个运行在你本地环境（可以是你的笔记本电脑，也可以是服务器）的应用程序。它的核心工作不是自己生成答案，而是作为一个“调度中心”和“逻辑处理器”。

  1. 接收指令：你通过网页界面、飞书/微信机器人、或者API，给OpenClaw发送一个任务，比如“帮我总结一下这份文档”。
  2. 规划与调用：OpenClaw内部有一个“大脑”（通常是它内置的一个轻量级模型，或者你配置的某个核心模型），它会分析这个任务，并将其拆解成一系列步骤。例如，它可能决定先调用一个文本理解模型来读取文档，再调用一个总结模型来生成摘要。
  3. 执行与整合：拆解后的每一步，往往都需要调用一个外部的“大模型API”来完成。OpenClaw会按照规划，依次向这些API发送请求，拿到结果，最后把各个结果整合成一个完整的回复返回给你。

所以，OpenClaw严重依赖外部大模型API。它本身的配置文件中，最关键的部分就是告诉它：去哪里找这些API（base_url），用什么密钥（api_key），以及默认用哪个模型（default_model）。

2.2 Cloudflare AI Gateway：所有AI API流量的“智能网关”

Cloudflare AI Gateway是Cloudflare提供的一项托管服务。你可以把它想象成你家路由器的一个高级功能：所有设备上网都要经过路由器，路由器可以设置家长控制、流量统计、访客网络等等。

  1. 统一入口：你不再让OpenClaw直接去敲OpenAI、Anthropic、Ollama的门。而是在Cloudflare上创建一个AI Gateway，获得一个专属的网关地址（比如https://gateway.ai.cloudflare.com/v1/YOUR_ACCOUNT_ID/YOUR_GATEWAY_NAME）。然后，你让OpenClaw把所有请求都发到这个地址。
  2. 路由与转发：AI Gateway内部配置了“上游”（Upstream）。你可以在网关的设置里，预先填好OpenAI、Anthropic等服务的真实API地址和密钥。当请求到达网关时，网关会根据请求内容（比如请求头里的模型名称）自动将其转发到正确的上游服务商。
  3. 增值功能：这是核心价值所在。在转发过程中，网关可以帮你做很多事：
    • 鉴权与密钥管理：你只需要在Cloudflare上保管一份密钥，OpenClaw的配置里可以不用写任何敏感密钥，安全性更高。
    • 限流与缓存：可以为不同模型或用户设置每秒请求数（RPS）限制，防止意外刷爆账单。对于重复的请求，可以返回缓存结果，极大提升速度并节省成本。
    • 日志与分析：所有经过网关的请求都会被记录，你可以清晰看到每个模型的使用量、延迟、花费情况，方便做成本核算和性能优化。
    • 负载均衡与容灾：如果你配置了多个同类型的上游（比如两个不同的Ollama实例），网关可以在它们之间做负载均衡；如果一个挂了，可以自动切换到另一个。

两者的结合点就在于：将OpenClaw配置中的base_url，从各个模型服务商的原始地址，统一改为你的Cloudflare AI Gateway地址。同时，将api_key设置为Cloudflare生成的令牌。这样，OpenClaw发出的所有请求，都将先经过Gateway的“加工”和“调度”，再抵达最终目的地。

3. 环境准备与前置条件检查

在开始写配置代码之前，我们需要确保两边的基础设施都是就绪的。这就像接水管，得先确认水源和水龙头都没问题。

3.1 Cloudflare AI Gateway 侧准备

  1. 拥有一个Cloudflare账户：如果你没有，去Cloudflare官网注册一个。免费套餐就包含了AI Gateway的基本功能，对于个人和小型项目起步完全足够。
  2. 创建你的AI Gateway：
    • 登录Cloudflare Dashboard，侧边栏找到Workers & Pages->AI Gateway。
    • 点击Create Gateway。
    • 给你的网关起个名字，比如my-openclaw-gateway。这个名字会出现在你的网关URL里。
    • 创建完成后，记下你的网关URL，格式是https://gateway.ai.cloudflare.com/v1/ACCOUNT_ID/GATEWAY_NAME。这个地址就是我们后续要配置到OpenClaw里的。
  3. 添加上游（Upstream）：这是最关键的一步，告诉网关你的请求最终要发到哪里。
    • 在网关详情页，找到Upstreams选项卡，点击Add upstream。
    • 对于OpenAI/Azure OpenAI：选择供应商为“OpenAI”，然后填入你的OpenAI API密钥。你可以在这里创建多个上游，对应不同的API密钥（比如一个用于GPT-4，一个用于GPT-3.5以控制成本）。
    • 对于Anthropic Claude：选择供应商为“Anthropic”，填入对应的API密钥。
    • 对于本地Ollama：这是社区问得最多的。选择供应商为“Custom”。在Base URL里填入你Ollama服务的地址，例如http://localhost:11434（如果OpenClaw和Ollama在同一台机器）或http://YOUR_SERVER_IP:11434。注意：由于Cloudflare Gateway是云端服务，它默认无法直接访问你本地网络的localhost。你有两个选择：
      • 方案A（推荐用于生产）：使用Cloudflare Tunnel。在你的Ollama服务器上安装cloudflared，创建一个隧道，将本地11434端口暴露给Cloudflare网络，获得一个固定的*.trycloudflare.com域名。将这个域名填入Custom Upstream的Base URL。
      • 方案B（快速测试）：如果你的测试环境有公网IP，且Ollama端口（11434）暴露在公网（强烈不建议，极不安全），可以直接填入公网IP。生产环境切勿如此。
    • 模型名称映射：在添加每个上游时，你可以指定这个上游处理哪些模型的请求。例如，你可以设置一个上游专门处理gpt-4*的请求，另一个处理gpt-3.5-turbo*。对于自定义的Ollama，你需要填写你的模型名，如llama3.2:latest。
  4. 创建网关令牌（Gateway Token）：
    • 在网关详情页，找到Authentication选项卡。
    • 点击Create Gateway Token。这个令牌相当于访问你这个网关的密码。
    • 创建后，立即复制并妥善保存，因为它只显示一次。这个令牌将作为OpenClaw配置中的api_key。

3.2 OpenClaw 侧准备

  1. 一个已经成功安装并可以启动的OpenClaw实例。无论你是通过Docker部署，还是在Ubuntu/Mac上直接安装，请确保它最基本的运行是没问题的。你可以参考热词里的“ubuntu极速部署openclaw完全指南”或“docker部署openclaw”来完成这一步。
  2. 找到OpenClaw的配置文件。OpenClaw的核心配置通常在一个叫config.yaml或settings.yaml的文件里，具体位置取决于你的安装方式。Docker部署的可能在挂载的卷里，直接安装的可能在~/.openclaw/或项目根目录下。
  3. 理解OpenClaw的模型配置块。配置文件里会有一个models或llm的配置部分，里面定义了OpenClaw可以使用的各个模型及其参数。我们的改造将主要集中在这里。

注意：在进行以下操作前，强烈建议备份你的原始配置文件。一次只修改一个模型配置进行测试，避免全部改乱导致服务无法启动。

4. 集成配置实战：一步步改造OpenClaw配置

现在，我们进入最核心的实操环节。我将以最常见的场景为例：让OpenClaw通过Cloudflare AI Gateway来调用OpenAI的GPT-4和本地Ollama的Llama 3.2模型。

假设我们原始的OpenClaw配置中，模型部分是这样的：

# 原始 config.yaml 片段 models: openai-gpt-4: model: gpt-4-turbo-preview api_key: sk-your-real-openai-key-here # 敏感信息暴露在配置文件中 base_url: https://api.openai.com/v1 max_tokens: 4096 local-llama: model: llama3.2:latest base_url: http://localhost:11434/v1 # 直接指向本地Ollama # 通常Ollama不需要api_key

我们的目标是将其改造为全部通过Cloudflare AI Gateway。假设你的网关信息如下：

  • 网关URL:https://gateway.ai.cloudflare.com/v1/abcd1234/my-openclaw-gateway
  • 网关令牌:CF_xxxxxxxxxxxx

4.1 第一步：配置OpenAI模型通过网关

修改openai-gpt-4的配置：

models: openai-gpt-4: model: gpt-4-turbo-preview # 这个模型名称必须与你在Cloudflare Gateway中设置的模型映射一致 api_key: CF_xxxxxxxxxxxx # 替换为你的Cloudflare网关令牌，不再是OpenAI的密钥 base_url: https://gateway.ai.cloudflare.com/v1/abcd1234/my-openclaw-gateway # 替换为你的网关地址 max_tokens: 4096

关键点解释：

  • api_key：现在填的是Cloudflare的网关令牌。你的真实OpenAI密钥已经安全地保存在Cloudflare后台的上游配置里了。
  • base_url：从OpenAI的官方端点，改成了你的统一网关入口。
  • model：名称保持不变。当请求到达网关时，网关会根据这个模型名gpt-4-turbo-preview，去查找配置中哪个上游负责处理该模型，然后使用该上游的密钥转发到真实的OpenAI API。

4.2 第二步：配置本地Ollama模型通过网关（使用Cloudflare Tunnel）

这是难点，也是价值最大的地方。我们需要让云端的Gateway能访问到本地的Ollama。

首先，在Ollama服务器上设置Cloudflare Tunnel：

  1. 安装cloudflared（以Linux为例）：
    wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb sudo dpkg -i cloudflared-linux-amd64.deb
  2. 登录并创建隧道：
    cloudflared tunnel login # 会打开浏览器，授权你的Cloudflare账户 cloudflared tunnel create ollama-tunnel # 创建名为ollama-tunnel的隧道
    执行后会生成一个隧道UUID和一个证书文件（xxx.json），记下UUID。
  3. 创建配置文件~/.cloudflared/config.yml：
    tunnel: <你的隧道UUID> credentials-file: /home/your_user/.cloudflared/<UUID>.json ingress: - hostname: ollama.your-domain.com # 如果你想用自定义域名，需要先在Cloudflare DNS设置好 service: http://localhost:11434 - service: http_status:404
    如果不用自定义域名，Cloudflare会分配一个随机的*.trycloudflare.com域名，你可以在下一步的DNS记录中看到。
  4. 在Cloudflare Dashboard的Networks->Tunnels页面，找到你创建的隧道，配置Public Hostname，将子域名（如ollama）指向本地http://localhost:11434。
  5. 启动隧道：
    cloudflared tunnel run ollama-tunnel
    成功后，你会获得一个可公网访问的URL，例如https://ollama-tunnel-xyz.trycloudflare.com。这个URL就是你的Ollama服务对Cloudflare网络暴露的地址。

然后，在Cloudflare AI Gateway中添加Custom Upstream：

  • 供应商：Custom
  • Base URL:https://ollama-tunnel-xyz.trycloudflare.com（填写你上一步获得的隧道URL）
  • 模型：填写你的Ollama模型名，例如llama3.2:latest。这里有个巨坑：Ollama的API路径是/api/chat，但OpenAI格式的请求路径是/v1/chat/completions。幸运的是，Cloudflare AI Gateway和OpenClaw的Ollama配置通常都做了兼容性处理。确保你的Base URL指向的是Ollama服务的根路径（带端口号），网关和OpenClaw会帮你补全正确的路径。

最后，修改OpenClaw配置：

models: local-llama: model: llama3.2:latest # 必须与Gateway中配置的模型名完全一致 api_key: CF_xxxxxxxxxxxx # 同样使用Cloudflare网关令牌 base_url: https://gateway.ai.cloudflare.com/v1/abcd1234/my-openclaw-gateway # 同一个网关地址 # 注意：这里移除了直接指向localhost的base_url

4.3 第三步：重启OpenClaw并测试

保存配置文件，重启你的OpenClaw服务。

  1. 基础连通性测试：在OpenClaw的Web界面或通过其API，尝试使用openai-gpt-4模型进行一个简单对话。观察日志或Cloudflare Gateway的Analytics面板，看是否有请求经过。
  2. Ollama网关测试：尝试使用local-llama模型。这是最可能出错的地方。
    • 如果报错400或404：检查Cloudflare Tunnel的日志，确认隧道是否正常运行，Ollama服务在本地localhost:11434是否可访问。同时检查Gateway中Custom Upstream的Base URL是否正确（是否多了或少了下划线）。
    • 如果报错“模型未找到”：检查Gateway中为该上游配置的模型名称，是否与OpenClaw配置中的model字段一字不差。大小写、冒号后的版本号都要一致。
  3. 验证网关功能：在Cloudflare AI Gateway的Analytics页面，你应该能看到来自不同模型的请求日志，包括延迟、令牌用量等信息。这证明集成成功了。

5. 高级配置与故障排查：解决那些“坑爹”的问题

按照上面的步骤，大部分情况下应该能跑通。但真实环境总是更复杂，下面是我遇到过的几个典型问题及解决方案。

5.1 模型名称映射与请求格式冲突

问题描述：OpenClaw向网关发送请求时，其请求体是标准的OpenAI API格式。但你的上游可能是Anthropic Claude或自定义的Ollama，它们期待的请求格式可能不同。

根因分析：Cloudflare AI Gateway在设计上主要优先兼容OpenAI API格式。对于Anthropic，网关会自动进行格式转换。但对于Custom Upstream（如Ollama），它默认假设你的上游服务也兼容OpenAI API格式。如果你的Ollama部署没有开启或兼容OpenAI格式的API端点（/v1/chat/completions），就会失败。

解决方案：

  1. 确保Ollama启用兼容模式：启动Ollama时，确保它支持OpenAI格式的API。较新版本的Ollama默认支持。你可以通过访问http://localhost:11434/v1/chat/completions（注意是/v1路径）来测试。如果返回404，可能需要检查Ollama版本或配置。
  2. 在Gateway中利用“请求转换”功能（Beta）：Cloudflare AI Gateway提供了高级的请求/响应转换能力。你可以在网关的Settings->Transform Rules中，为特定的模型（如llama3.2:latest）编写一段简单的JavaScript代码，将进来的OpenAI格式请求，转换成你的上游服务期待的格式。这需要一些JavaScript和API知识，但提供了最大的灵活性。
  3. 使用社区中间件：如果网关转换太复杂，可以考虑在OpenClaw和Gateway之间，或者Gateway和Ollama之间，部署一个轻量的代理服务（比如用Python Flask写的简单转换器），专门做协议适配。但这增加了架构复杂度。

5.2 网关缓存导致“幻觉”或旧数据

问题描述：开启了网关的缓存功能后，发现OpenClaw的回复有时候是旧的、过时的，或者对于不同用户的相同问题给出了完全一样的答案（这在不该共享缓存的场景下是问题）。

排查过程：

  1. 首先确认是否在Gateway设置中开启了缓存（Caching）。
  2. 检查OpenClaw发出的请求头。默认情况下，网关可能根据请求URL和部分头部（如model）来生成缓存键。如果两个用户的请求完全一样，就会命中缓存。
  3. 查看网关的缓存规则设置，默认的缓存时间（TTL）是多长。

解决方案：

  1. 为不同用户/会话添加缓存隔离：在OpenClaw发出请求时，在HTTP请求头中添加一个自定义头部，例如X-User-ID: user123。然后在Cloudflare Gateway的缓存规则设置中，配置将X-User-ID头部也纳入缓存键（Cache Key）的计算。这样，不同用户的请求就不会共享缓存了。
  2. 调整或关闭缓存：对于需要实时性、创造性的对话场景，可以考虑将缓存TTL设得非常短（如1秒），或者直接关闭该模型的缓存功能。在Gateway的Upstream配置或模型设置中，可以针对特定模型调整缓存策略。
  3. 使用动态查询参数：如果无法控制请求头，可以在请求URL末尾添加一个随机参数（如?t=timestamp），但这可能会影响网关的其他功能（如日志聚合），需谨慎使用。

5.3 性能与延迟监控

集成后，监控变得尤为重要。Cloudflare AI Gateway自带的Analytics面板非常有用。

  1. 关注P99延迟：不要只看平均延迟。如果P99延迟（最慢的1%请求的延迟）很高，说明有少量请求卡住了，会影响用户体验。可以对比直接调用API和通过网关调用的延迟差异。通常网关会增加10-50ms的 overhead，这在可接受范围内。如果超过100ms，需要检查网络链路或网关所在区域。
  2. 设置告警：在Cloudflare Dashboard中，可以为你的网关设置告警。例如，当错误率超过1%，或P95延迟超过2秒时，发送邮件或Slack通知。这能让你在用户大量投诉前发现问题。
  3. 成本分析：利用Gateway的日志，你可以清晰地看到每个模型消耗的令牌数。结合各模型供应商的定价，可以更准确地预测和控制成本。这是直接裸连API难以做到的精细化运营。

5.4 处理“openclaw llamap svr operator(): got exception”类错误

这个错误信息看起来像是OpenClaw内部处理LLM响应时抛出的异常。集成网关后，这类错误可能被放大，因为错误来源可能是网关、上游服务或者网络。

排查链路：

  1. 查看OpenClaw应用日志：找到最详细的错误堆栈，看异常是在哪个阶段抛出的。
  2. 查看Cloudflare Gateway Analytics：进入请求日志，找到对应失败请求的条目。Gateway会记录它转发请求后的上游HTTP状态码。如果上游返回了4xx或5xx错误，Gateway通常会把这个错误信息透传给OpenClaw。
    • 如果状态码是400，通常是请求格式不对，参考5.1节。
    • 如果状态码是429，是触发了限流，需要检查Gateway或上游服务的速率限制设置。
    • 如果状态码是5xx，是上游服务（如Ollama）内部错误，需要去检查Ollama服务器的日志和资源（内存、GPU）使用情况。
  3. 检查Cloudflare Tunnel日志：如果用的是Tunnel连接Ollama，运行cloudflared tunnel info <tunnel-name>或直接查看其运行输出，确认隧道连接是否稳定。
  4. 简化测试：用最简单的curl命令，绕过OpenClaw，直接向你的Cloudflare Gateway地址发送一个标准OpenAI格式的请求，看是否能得到正常响应。这能帮你快速定位问题是出在OpenClaw配置，还是网关/上游服务。

6. 生产环境部署建议与安全考量

当你完成测试，准备将这套集成方案用于实际业务时，以下几点能让你走得更稳。

  1. 密钥与令牌管理：

    • 永远不要将Cloudflare网关令牌或任何API密钥硬编码在配置文件并提交到代码仓库。使用环境变量或密钥管理服务（如Vault）。
    • 在OpenClaw的Docker部署中，可以通过-e参数传入环境变量，在配置文件中用{{ env("GATEWAY_TOKEN") }}这样的模板语法引用。
    • 定期轮换（Rotate）你的网关令牌和上游API密钥。

  2. 高可用与灾备：

    • 多地域部署：如果你的用户分布在全球，可以考虑在Cloudflare上创建多个AI Gateway，并配置DNS根据用户地理位置解析到不同的网关，减少延迟。
    • 上游冗余：对于关键模型（如GPT-4），在Gateway中配置多个使用不同API密钥的上游。Gateway可以在它们之间进行负载均衡和故障转移。
    • Ollama集群：对于自托管模型，可以通过Tunnel将多个Ollama实例暴露，并在Gateway中配置为一个上游组（Upstream Group），实现简单的负载均衡。

  3. 网络与安全：

    • 限制网关访问：在Cloudflare Gateway的设置中，可以配置IP访问规则，只允许你的OpenClaw服务器所在的IP地址向网关发起请求，防止令牌泄露后被滥用。
    • 保护Tunnel：Cloudflare Tunnel创建的连接默认是加密且安全的。确保运行cloudflared的服务器的系统安全，避免隧道被恶意控制。
    • 监控与审计：开启Gateway的详细日志，并定期审计。关注异常的请求模式，比如来自某个IP的突发大量请求，可能是攻击或配置错误。

  4. 成本控制：

    • 设置用量限制：在Gateway中，为每个模型或每个上游设置严格的每分钟/每天请求次数或令牌数限制。这是防止测试代码循环出错或遭遇攻击导致账单爆炸的最有效手段。
    • 利用缓存：对于重复性高、实时性要求不高的查询（如知识库问答），合理设置缓存可以节省大量费用。

把OpenClaw和Cloudflare AI Gateway集成，初期会多花一些配置和调试的时间，但换来的是一套更可控、可观测、可扩展的AI调用基础设施。它把复杂的运维问题（密钥管理、限流、容灾、监控）交给了专业的云服务，让你能更专注于OpenClaw智能体本身的业务逻辑开发。当你看到Gateway面板上清晰的图表，再也不用担心半夜被账单警报吵醒时，你会觉得这些投入是值得的。

编程学习 学习日记 实战经验
← 返回列表