当前位置：首页 > news >正文

OpenClaw真相：大模型API统一网关的原理与手写实践

news 2026/6/22 8:19:48

1. OpenClaw 是什么：一个被误读的“API 聚合器”真相

很多人第一次看到 “OpenClaw API 配置教程，支持 Claude、Gemini、GPT5.4 等模型” 这个标题，第一反应是：“哇，又一个能一键调用所有大模型的开源神器？”——然后兴冲冲去 GitHub 搜openclaw，结果发现：根本搜不到官方仓库；再翻 PyPI，没有openclaw包；查 npm，也没有openclaw模块。更奇怪的是，所有热词里反复出现openclaw 安装、openclaw 命令、openclaw : 无法将“openclaw”项识别为 cmdlet…，但没人贴出openclaw --version的成功截图。

这不是你的问题，是整个搜索生态的集体错位。我花了三天时间，把所有带openclaw的 GitHub Issue、Discord 讨论、Reddit 帖子、中文技术论坛发帖全部扒了一遍，结论很明确：OpenClaw 并不是一个真实存在的、可独立安装部署的开源项目。它是一个在社区传播中被不断拼接、误传、泛化的概念性代号，其真实内核，其实是Codex（或类似前端框架）+ 自建 API 中转服务 + 第三方模型厂商 SDK 的组合实践。

为什么会出现这种现象？根源在于当前大模型调用链路的“三重断层”：

第一层断层：模型厂商的接入门槛高
Claude 的 Anthropic API 需要申请并通过审核，Gemini 的 Google AI Studio 需绑定 Google Cloud 项目并开启计费，GPT-5.4（注意：截至 2024 年底，OpenAI 官方从未发布过 GPT-5.4 版本，此为社区对某次内部测试代号的误传，实际指向的是 GPT-4o 或 GPT-4 Turbo 的某个 fine-tuned 变体）则需通过 Azure OpenAI 或官方 API 密钥。普通开发者面对的是分散的控制台、不一致的鉴权方式、完全不同的请求体结构。
第二层断层：前端应用与后端 API 的协议鸿沟
Codex、Cursor、Continue.dev 等 IDE 插件或本地 LLM 工具，期望接收统一格式的/v1/chat/completions请求，但 Anthropic 的 endpoint 是/v1/messages，Google 的是/v1beta/models/gemini-pro:generateContent，而 OpenAI 兼容接口（如 Ollama、LiteLLM）又要求model字段必须是claude-3-haiku-20240307这类硬编码字符串。直接对接，等于每接入一个模型就要重写一次适配逻辑。
第三层断层：错误信息的不可追溯性
热搜词里高频出现的api error: the model has reached its context window limit.、claude's response exceeded the 32000 output token maximum.、402 insufficient balance，这些错误都来自不同厂商的底层响应，但前端只显示一串 JSON，开发者根本分不清是自己 prompt 写错了、token 计算崩了，还是账户真没钱了。没有统一的错误归因层，调试就是盲人摸象。

所以，“OpenClaw” 实际上是一套隐性共识下的工程模式：它不是某个.exe或npm install openclaw就能跑起来的东西，而是指代一种“用轻量级 Node.js/Python 服务做协议翻译 + 统一鉴权 + 错误标准化 + 限流熔断”的架构范式。你看到的所谓“OpenClaw 配置”，99% 是在配置这个中转服务的config.yaml；你执行的所谓“OpenClaw 命令”，本质是node server.js或uvicorn main:app --reload；你遇到的“无法识别 openclaw”，是因为你试图在终端里敲一个根本不存在的 CLI 工具。

提示：如果你现在正对着终端输入openclaw --help并等待回显，请立刻停下。这不是你环境没配好，而是你找错了对象。真正的起点，是理解“API 中转层”为何必要，以及它该长什么样。

这也解释了为什么所有“openclaw 教程”都语焉不详——因为没人能给出一个通用安装包，每个人部署的，都是根据自己业务需求定制的中转服务。接下来，我会带你从零手写一个真正可用、可调试、可扩展的 OpenClaw 核心骨架，它不叫 OpenClaw，但它解决所有 OpenClaw 想解决的问题。

2. 从零构建 OpenClaw 核心：一个 120 行的 Python 中转服务

既然 OpenClaw 不是现成轮子，我们就造一个。目标很明确：让 Codex、VS Code 的 Continue 插件、甚至 curl 命令，都能用同一套 OpenAI 兼容格式，无缝调用 Claude、Gemini、GPT-4o。不追求大而全，先跑通最核心的/v1/chat/completions路由。

我选 Python + FastAPI，原因很实在：

FastAPI 的自动文档（Swagger UI）对调试 API 极其友好，你改完代码刷新页面就能看到实时请求示例；
httpx库对异步 HTTP 调用支持成熟，能轻松处理 Anthropic 的流式响应和 Gemini 的长响应；
生态里有现成的litellm（虽不直接用它，但它的源码是极佳参考），避免重复造轮子。

下面是你需要创建的main.py文件，全文 120 行，无任何第三方框架黑盒，每一行都可控、可 debug：

# main.py from fastapi import FastAPI, Request, HTTPException, status from fastapi.responses import StreamingResponse, JSONResponse import httpx import json import os from typing import Dict, Any, List, Optional app = FastAPI(title="OpenClaw Core", version="0.1") # 从环境变量读取密钥 —— 这是唯一需要你手动配置的地方 ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY", "") GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "") OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "") # 用于 GPT-4o，可选 # 模型映射表：把 OpenAI 风格的 model 名，映射到各厂商的真实 endpoint 和参数 MODEL_MAP = { "claude-3-haiku-20240307": { "provider": "anthropic", "endpoint": "https://api.anthropic.com/v1/messages", "headers": {"x-api-key": ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01"}, "max_tokens": 4096, }, "claude-3-sonnet-20240229": { "provider": "anthropic", "endpoint": "https://api.anthropic.com/v1/messages", "headers": {"x-api-key": ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01"}, "max_tokens": 4096, }, "gemini-pro": { "provider": "google", "endpoint": f"https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key={GEMINI_API_KEY}", "headers": {"Content-Type": "application/json"}, "max_tokens": 8192, }, "gpt-4o": { "provider": "openai", "endpoint": "https://api.openai.com/v1/chat/completions", "headers": {"Authorization": f"Bearer {OPENAI_API_KEY}", "Content-Type": "application/json"}, "max_tokens": 4096, } } @app.post("/v1/chat/completions") async def chat_completions(request: Request): try: body = await request.json() except json.JSONDecodeError: raise HTTPException(status_code=400, detail="Invalid JSON in request body") model_name = body.get("model") if not model_name or model_name not in MODEL_MAP: raise HTTPException( status_code=400, detail=f"Unsupported model: {model_name}. Supported: {list(MODEL_MAP.keys())}" ) provider_config = MODEL_MAP[model_name] # Step 1: 将 OpenAI 格式请求体，转换为各厂商所需格式 converted_payload = convert_to_provider_format(body, provider_config["provider"]) # Step 2: 调用下游厂商 API async with httpx.AsyncClient() as client: try: resp = await client.post( provider_config["endpoint"], headers=provider_config["headers"], json=converted_payload, timeout=60.0 ) except httpx.TimeoutException: raise HTTPException(status_code=504, detail="Upstream timeout") except httpx.NetworkError: raise HTTPException(status_code=502, detail="Upstream network error") # Step 3: 将下游响应，标准化为 OpenAI 兼容格式 if resp.status_code != 200: # 关键：统一错误归因，把厂商原生错误包装成 OpenAI 风格 error_detail = resp.json().get("error", {}).get("message", resp.text) raise HTTPException( status_code=resp.status_code, detail=f"[{provider_config['provider'].upper()} ERROR] {error_detail}" ) openai_style_response = convert_to_openai_format(resp.json(), provider_config["provider"]) return JSONResponse(content=openai_style_response) def convert_to_provider_format(openai_body: Dict[str, Any], provider: str) -> Dict[str, Any]: """Convert OpenAI /v1/chat/completions payload to provider-specific format""" messages = openai_body.get("messages", []) max_tokens = openai_body.get("max_completion_tokens") or openai_body.get("max_tokens", 2048) if provider == "anthropic": # Anthropic 要求 system message 单独提取，且 messages 里不能有 role=system system_prompt = "" anthropic_messages = [] for msg in messages: if msg["role"] == "system": system_prompt = msg["content"] else: anthropic_messages.append({"role": msg["role"], "content": msg["content"]}) return { "model": "claude-3-haiku-20240307", # 此处固定，由 MODEL_MAP 控制 "max_tokens": max_tokens, "system": system_prompt, "messages": anthropic_messages, "temperature": openai_body.get("temperature", 0.7), } elif provider == "google": # Gemini 要求 content 数组，且 role 映射不同 gemini_contents = [] for msg in messages: role_map = {"user": "user", "assistant": "model", "system": "user"} # Gemini 无 system role，转为 user gemini_contents.append({ "role": role_map.get(msg["role"], "user"), "parts": [{"text": msg["content"]}] }) return { "contents": gemini_contents, "generationConfig": { "maxOutputTokens": max_tokens, "temperature": openai_body.get("temperature", 0.7), } } elif provider == "openai": # OpenAI 原生格式，基本透传 return { "model": "gpt-4o", "messages": messages, "max_tokens": max_tokens, "temperature": openai_body.get("temperature", 0.7), } return {} def convert_to_openai_format(provider_resp: Dict[str, Any], provider: str) -> Dict[str, Any]: """Convert provider response to OpenAI /v1/chat/completions format""" if provider == "anthropic": content = provider_resp.get("content", [{}])[0].get("text", "") return { "id": f"chatcmpl-{provider_resp.get('id', 'anthropic')}", "object": "chat.completion", "created": int(provider_resp.get("stop_reason", "0")), "model": "claude-3-haiku-20240307", "choices": [{ "index": 0, "message": {"role": "assistant", "content": content}, "finish_reason": "stop" }], "usage": { "prompt_tokens": provider_resp.get("usage", {}).get("input_tokens", 0), "completion_tokens": provider_resp.get("usage", {}).get("output_tokens", 0), "total_tokens": 0 } } elif provider == "google": candidates = provider_resp.get("candidates", []) content = candidates[0]["content"]["parts"][0]["text"] if candidates else "" return { "id": f"chatcmpl-{provider_resp.get('requestId', 'gemini')}", "object": "chat.completion", "created": 0, "model": "gemini-pro", "choices": [{ "index": 0, "message": {"role": "assistant", "content": content}, "finish_reason": "stop" }], "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0} } elif provider == "openai": return provider_resp # 直接返回 return {}

这就是 OpenClaw 的心脏。它不炫技，但每一步都直击痛点：

环境变量驱动：ANTHROPIC_API_KEY、GEMINI_API_KEY必须由你提供，这是安全底线。绝不在代码里硬编码密钥，也绝不走.env文件（易被 Git 误提交），生产环境必须用系统级环境变量。
模型映射表MODEL_MAP：这是你未来扩展新模型的唯一入口。想加 DeepSeek？只需往这里加一行字典；想切到 Claude-3.5？改个字符串就行。所有逻辑解耦，不碰主流程。
convert_to_provider_format函数：它处理了最让人头疼的“角色映射”问题。OpenAI 的system角色在 Anthropic 是顶层字段，在 Gemini 则根本不存在，必须转成user。这个函数就是你的协议翻译官。
统一错误包装：当 Anthropic 返回{"error": {"type": "overloaded_error", ...}}，它会被包装成[ANTHROPIC ERROR] Rate limit exceeded，前端一眼就知道是哪家的问题，不用再猜。

注意：这个服务默认监听http://localhost:8000。启动命令就是uvicorn main:app --reload。别急着配 Codex，先用 curl 测试它是否真的活了：
curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-3-haiku-20240307", "messages": [{"role": "user", "content": "你好，请用中文简单介绍你自己"}], "max_tokens": 1024 }'
如果看到一个标准的 OpenAI 风格 JSON 响应，恭喜，你的 OpenClaw 已经上线。如果报错，90% 是环境变量没设对，或者网络不通——这正是我们下一步要深挖的排错环节。

3. 排错实战：从`402 insufficient balance`到`context window limit`的完整归因链

写完代码只是开始，真正的功夫在排错。所有热搜词里那些让人抓狂的错误，其实都有清晰的归因路径。我不会告诉你“换个模型就好了”，而是带你走一遍完整的排查链条，让你以后看到任何api error，都能在 3 分钟内定位到根因。

我们以三个最高频错误为例，拆解它们在 OpenClaw 架构中的完整流转过程：

3.1 错误`api error: 402 insufficient balance`

表面现象：你在 Codex 里点发送，几秒后弹出红色提示框：“api error: 402 insufficient balance”。

你以为的原因：账户余额不足，赶紧去 Anthropic 控制台充钱。

OpenClaw 架构下的真实归因链：

Codex 发起请求：它向你的http://localhost:8000/v1/chat/completions发送了一个标准 OpenAI 格式请求，model字段是"claude-3-haiku-20240307"。
OpenClaw 主流程捕获：chat_completions()函数查MODEL_MAP，确认这是 Anthropic 模型，进入convert_to_provider_format()。
协议转换完成：生成 Anthropic 所需的{"model": "...", "system": "...", "messages": [...]}。
HTTP 调用下游：httpx.AsyncClient.post()向https://api.anthropic.com/v1/messages发起请求。
Anthropic 返回原始响应：状态码402，Body 是{"error": {"type": "insufficient_balance", "message": "Your account does not have sufficient balance."}}。
OpenClaw 错误拦截：if resp.status_code != 200:分支触发，执行raise HTTPException(...)，并将原始message包装进detail字段。
Codex 收到最终错误：它收到的是{"detail": "[ANTHROPIC ERROR] Your account does not have sufficient balance."}。

关键洞察：这个错误100% 来自 Anthropic 侧，OpenClaw 只是信使。但正因为 OpenClaw 加了[ANTHROPIC ERROR]前缀，你才不会误以为是自己的服务挂了，或是 Codex 配错了地址。

实操验证步骤（必须按顺序）：

在终端执行echo $ANTHROPIC_API_KEY，确认变量非空；

用curl直接调用 Anthropic 原生 endpoint（绕过 OpenClaw）：

curl -X POST "https://api.anthropic.com/v1/messages" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "Content-Type: application/json" \ -d '{"model":"claude-3-haiku-20240307","max_tokens":1024,"messages":[{"role":"user","content":"test"}]}'

如果这一步也返回402，问题锁定在 Anthropic 账户；如果这一步成功，说明 OpenClaw 的请求构造或网络代理有问题。

提示：很多人的402其实是401的伪装。Anthropic 有时会把无效密钥也返回402。所以第 2 步的curl测试是黄金标准，它剥离了所有中间层，直击源头。

3.2 错误`api error: the model has reached its context window limit.`

表面现象：你发了一段超长的代码文件给 Claude，它直接报错，不给任何输出。

你以为的原因：Prompt 太长了，得切分。

OpenClaw 架构下的真实归因链：

Codex 发送长请求：messages数组里有一个content字段长达 12000 个 token。
OpenClaw 转换为 Anthropic 格式：convert_to_provider_format()把它塞进messages数组，同时max_tokens设为 2048。
Anthropic 拒绝请求：Anthropic 的context window limit是指输入 + 输出的总 token 上限。Claude-3-Haiku 是 200K tokens，但它的 API 会校验：len(input_tokens) + max_tokens > 200000？如果是，直接返回400 Bad Request，Body 里有context_window_exceeded。
OpenClaw 捕获 400：进入错误分支，但这次resp.json().get("error", {}).get("message")可能为空，resp.text就是原始 HTML 或 JSON 字符串。
错误包装失效风险：如果resp.text是乱码或超长 JSON，detail字段会变得难以阅读。

解决方案不是切分，而是预计算：在convert_to_provider_format()之前，加入 token 预估。我用的是tiktoken库（OpenAI 官方 token 计算器），但它对 Claude 和 Gemini 不完全准确。更稳妥的做法是：在 OpenClaw 层加一个max_input_tokens配置项。

在MODEL_MAP里为每个模型增加一项：

"claude-3-haiku-20240307": { # ... 其他字段 "max_input_tokens": 190000, # 留 10K 给输出 },

然后在chat_completions()函数开头，插入 token 预估逻辑：

# 伪代码，实际需引入 tiktoken 或估算函数 estimated_input_tokens = estimate_tokens(body.get("messages", [])) if estimated_input_tokens > provider_config.get("max_input_tokens", 100000): raise HTTPException( status_code=400, detail=f"Input too long. Estimated {estimated_input_tokens} tokens, but {model_name} supports only {provider_config['max_input_tokens']} input tokens." )

这样，错误就从 Anthropic 的模糊400，变成了 OpenClaw 的精准提示：“Input too long. Estimated 210000 tokens…”。你立刻知道该删哪段注释，而不是盲目重试。

3.3 错误`claude's response exceeded the 32000 output token maximum.`

表面现象：你让 Claude 写一篇长报告，它写到一半就中断，报这个错。

你以为的原因：max_tokens设小了。

OpenClaw 架构下的真实归因链：

你设置了max_tokens: 32000：这本身没问题，Claude-3-Sonnet 确实支持 32K 输出。
OpenClaw 透传给 Anthropic：convert_to_provider_format()把它设为max_tokens字段。
Anthropic 开始流式输出：它一边生成，一边发event: content_block_delta。
OpenClaw 的convert_to_openai_format()函数失效：注意，上面的main.py只实现了同步响应（JSONResponse），不支持流式！当你在 Codex 里开启 “Stream responses”，Codex 会发stream: true，但我们的服务直接忽略它，强行返回完整 JSON，导致前端解析失败，表现为“响应截断”。

这才是根因：OpenClaw 的骨架默认是同步的，但现代 IDE 插件默认走流式。我们必须补上流式支持。

修复方案：新增一个/v1/chat/completions的流式路由，或（更推荐）重构主路由，让它根据body.get("stream", False)自动切换模式。这需要重写chat_completions()，用StreamingResponse包装一个异步生成器。代码会变长，但这是必经之路。

我的实操心得：不要一上来就写流式。先用同步模式跑通所有模型、所有错误类型，等curl测试 100% 稳定后，再加流式。否则你会陷入“是模型问题？是流式问题？是网络问题？”的三重嵌套调试，效率极低。OpenClaw 的价值，首先是“确定性”，其次是“高性能”。

4. Codex 与 VS Code 配置：如何让插件真正信任你的 OpenClaw

代码跑通了，错误也能看了，下一步是让 Codex、VS Code 的 Continue 插件这些“前端消费者”，把你的 OpenClaw 当成一个真正的 OpenAI 兼容服务来用。这步看似简单，却是最多人卡住的环节——因为配置项藏得太深，且文档语焉不详。

4.1 Codex 的`settings.json`配置详解

Codex 的配置入口在Settings→Extensions→Codex→Edit in settings.json。你需要修改的，是codex.api.baseUrl和codex.api.key这两个字段。

关键误区：很多人填http://localhost:8000，然后发现没反应。为什么？因为 Codex 默认走 HTTPS，而你的 FastAPI 是 HTTP。浏览器会直接拦截。

正确配置（Windows/macOS/Linux 通用）：

{ "codex.api.baseUrl": "http://localhost:8000/v1", "codex.api.key": "sk-xxx", // 这个值可以是任意非空字符串，因为 OpenClaw 不校验 key，只认 header "codex.model": "claude-3-haiku-20240307", "codex.temperature": 0.5 }

为什么key可以乱填？
回顾main.py，你会发现MODEL_MAP里的headers是从环境变量读的，不是从请求 header 里取的。Codex 发来的Authorization: Bearer sk-xxx，OpenClaw 根本没用它。所以key字段在这里纯粹是个占位符，只要不为空，Codex 就会发请求。

但有个隐藏陷阱：Codex 的baseUrl必须以/v1结尾。如果你填http://localhost:8000，它会拼成http://localhost:8000/chat/completions，而你的路由是/v1/chat/completions，404 直接报错。必须显式带上/v1。

4.2 VS Code Continue 插件的`continue.config.json`配置

Continue 的配置文件是项目根目录下的.continue/config.json。它的结构更复杂，但核心就三点：

{ "models": [ { "title": "My OpenClaw Haiku", "model": "claude-3-haiku-20240307", "provider": "openai", "apiKey": "anything", "apiBase": "http://localhost:8000/v1", "apiType": "openai" } ], "defaultModel": "My OpenClaw Haiku" }

逐项解析：

"provider": "openai"：这是硬性要求。Continue 不认识anthropic或google，它只认openai这个 provider 类型，然后把所有请求都按 OpenAI 格式发出去。这正是 OpenClaw 存在的意义——做协议翻译。
"apiBase": "http://localhost:8000/v1"：同 Codex，必须带/v1。
"apiKey"：同理，占位符，随便写。

实测技巧：Continue 启动时会打印日志到 VS Code 的Output面板（选择Continue）。如果配置错误，你会看到Failed to connect to http://localhost:8000/v1/chat/completions。这是最直接的诊断依据，比看 Codex 的红字提示更早、更准。

4.3 Chrome 浏览器内置 Gemini 消失的真相与替代方案

热搜词里大量出现chrome gemini没有显示、为什么chrome浏览器内置gemini消失，这和 OpenClaw 有什么关系？关系很大——因为很多人想用 OpenClaw 去“复活” Chrome 的 Gemini。

事实是：Chrome 内置的 Gemini 是 Google 官方深度集成的，它不走任何公开 API，而是调用 Chrome 内部的genai模块。你无法用 OpenClaw 去代理它，就像你不能用 Nginx 去代理 Windows 的注册表一样。

但你可以做到等效替代：

在 Chrome 地址栏输入chrome://apps，找到并打开Gemini Web App（网址通常是https://gemini.google.com/app）；
在这个网页里，右键 →检查→Network标签页；
输入一个问题并发送，观察 Network 面板里出现的generateContent请求；
复制这个请求的curl命令，粘贴到终端，你会发现它带有一长串Cookie和X-Goog-AuthUserheader；
这些 header 是登录态凭证，无法被 OpenClaw 复用。

所以，正确的思路不是“恢复内置”，而是“用 OpenClaw 构建一个功能更强的 Gemini Web UI”。你可以用 Streamlit 或 Gradio，快速搭一个界面，后端连你的 OpenClaw 服务，model选gemini-pro。它比 Chrome 内置版多了历史记录、多轮对话管理、自定义 system prompt，这才是 OpenClaw 的真正价值——不是复刻旧体验，而是创造新可能。

最后一个经验：所有配置完成后，务必重启 Codex/Continue 插件，而不是只重启服务。插件会缓存配置，有时候改了settings.json，不重启，它还在用旧的 baseUrl。这是我踩过最蠢的坑，浪费了整整两小时。

5. 进阶：从 OpenClaw 到生产级 API 网关的关键跃迁

你现在拥有了一个能跑、能调、能排错的 OpenClaw 核心。但它离一个可交付的生产服务，还有五道坎。跳过去，你就从“能用”升级为“可靠”；跳不过去，它永远是个玩具。

5.1 坎一：密钥管理——从环境变量到 Vault

os.getenv("ANTHROPIC_API_KEY")在开发时很爽，但在生产环境是定时炸弹。原因有三：

泄露风险：一旦进程崩溃，错误日志里可能打印出完整密钥；
轮换困难：密钥过期或泄露后，必须重启整个服务；
多租户不支持：所有用户共用一个密钥，无法做用量审计。

生产方案：HashiCorp Vault。它不是噱头，而是行业标准。部署一个 Vault 实例（Docker 一行命令），把所有 API Key 存进secret/openclaw/路径，然后用 Vault Agent 注入到 OpenClaw 容器的文件系统里。OpenClaw 启动时，读取/vault/secrets/anthropic_key这个文件，而不是环境变量。

好处立竿见影：密钥永不落地内存，轮换时只需更新 Vault，OpenClaw 自动 reload；未来加租户，只需在 Vault 里建secret/openclaw/tenant-a/和secret/openclaw/tenant-b/，OpenClaw 根据请求 header 里的X-Tenant-ID动态读取。

5.2 坎二：限流与熔断——防止一个用户拖垮全局

你肯定不想看到这样的场景：某个用户写了个死循环脚本，每秒调用 100 次gemini-pro，结果 Anthropic 的 quota 被刷爆，其他所有用户都 429。OpenClaw 必须有自己的流量阀门。

推荐方案：slowapi+ Redis。slowapi是 FastAPI 的限流插件，它依赖 Redis 存储计数器。在main.py顶部加：

from slowapi import Limiter from slowapi.util import get_remote_address from slowapi.middleware import SlowAPIMiddleware limiter = Limiter(key_func=get_remote_address, default_limits=["100/minute"]) app.state.limiter = limiter app.add_middleware(SlowAPIMiddleware)

然后在@app.post("/v1/chat/completions")上加装饰器：

@app.post("/v1/chat/completions") @limiter.limit("50/minute") # 每分钟最多 50 次 async def chat_completions(request: Request): # ... 原有逻辑

为什么是 Redis？因为单机内存限流（如memorybackend）在多实例部署时完全失效。Redis 是共享状态中心，保证全局速率限制。

5.3 坎三：可观测性——没有监控的服务等于黑盒

print("Request received")不是监控。生产级 OpenClaw 必须有三样东西：

Metrics（指标）：QPS、P95 延迟、各模型调用成功率。用prometheus-fastapi-instrumentator，一行代码接入 Prometheus；
Tracing（链路追踪）：一次请求从 Codex → OpenClaw → Anthropic 的完整耗时分布。用opentelemetry+ Jaeger；
Logging（日志）：结构化 JSON 日志，包含request_id、model、status_code、duration_ms。用structlog替代print。