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

OpenClaw AI网关：本地可部署的AI模型路由与协议兼容方案

news 2026/6/24 4:59:09

1. 项目概述：OpenClaw AI 聊天网关到底是什么，为什么值得你花时间配置它

OpenClaw AI 聊天网关不是另一个需要你从零写代码的AI服务框架，也不是一个只能在云上跑、动不动就扣费的黑盒API。它是一个本地可部署、协议兼容强、模型路由灵活的AI请求中转层——你可以把它理解成你电脑或内网里的一位“AI调度员”。它不自己生成文字，但能听懂你的请求（比如“用Qwen3回答这个问题”“调Claude-3.5-sonnet查专利摘要”），然后精准地把任务派给后端真正干活的模型服务（本地Ollama、远程Anthropic API、自建vLLM集群、甚至飞书/钉钉的Bot接口），再把结果原样、带格式、带流式响应地交还给你。这背后解决的是真实场景里最让人头疼的三个断层：模型太多管不过来、API协议五花八门、调试时满屏502 Bad Gateway却不知错在哪一层。

我第一次在客户现场看到这个需求，是某家做专利分析的律所。他们同时在用本地部署的Qwen3做中文权利要求解析，用Anthropic的Claude-3.5做英文说明书润色，还要把结果自动推送到飞书群。之前他们靠写一堆Python脚本硬桥接，每次Claude API更新路径、Ollama升级模型名、飞书Webhook换Token，整个流程就崩一次。后来换成OpenClaw Gateway，只改了一行配置，三路请求全部稳住，连前端工程师都不用碰后端代码。这就是网关的价值：把“谁来干”和“怎么干”彻底解耦。它不替代模型，而是让模型能力像水电一样即插即用。标题里的“Gateway 启动与使用”，核心就落在两个字上：可控——你能看清每条请求走了哪条路、耗了多少时间、卡在哪个环节；你能用一套统一的/v1/chat/completions接口对接所有下游，不用为每个模型重写SDK；你还能在本地加Redis缓存、加Sentinel限流、加日志审计，完全掌握数据主权。这不是玩具项目，而是面向生产环境设计的AI基础设施组件。如果你正被“模型越来越多、接口越来越乱、错误越来越难查”困扰，那这篇配置教程就是你今天该做的第一件事。

2. 整体架构设计与方案选型逻辑：为什么是OpenClaw，而不是自己手写一个HTTP代理

2.1 OpenClaw网关的核心定位与不可替代性

很多人看到“网关”第一反应是：“我用Nginx反向代理不就行了？”或者“写个Express中间件几行代码搞定”。这种想法在测试阶段确实成立，但一旦进入真实业务流，就会立刻暴露出根本性缺陷。OpenClaw的设计哲学不是做一个通用HTTP转发器，而是专为AI大模型交互场景深度定制的语义网关。它的不可替代性体现在三个硬核层面：

第一是协议语义理解能力。标准HTTP代理只认URL和Header，而OpenClaw能解析/v1/chat/completions请求体里的model字段、messages结构、stream布尔值、tools数组，甚至能识别response_format: { "type": "json_object" }这类高级指令。这意味着它能做智能路由——当请求里写着model: "claude-3-5-sonnet"，它自动转发到Anthropic后端；写着model: "qwen3:14b"，则路由到本地Ollama；写着model: "feishu-bot"，就走飞书Bot SDK封装的专用通道。Nginx做不到这点，它只能按URL前缀粗暴分流，而AI请求的URL几乎全是/v1/chat/completions，根本无法区分。

第二是流式响应（Streaming）的无损透传与增强。AI对话最核心的体验就是实时打字效果，这依赖于SSE（Server-Sent Events）或分块传输编码（chunked transfer encoding）。普通代理在转发流式响应时极易出现缓冲、截断、乱序，导致前端收到的data: {"delta":{"content":"..."}}消息缺失或错乱。OpenClaw内置了专门的流式管道处理引擎，它会逐块读取后端响应、校验JSON完整性、添加统一的id和created时间戳，再原样推送出去。更重要的是，它支持在流式过程中注入元数据——比如在每条delta消息前插入{"gateway":"openclaw","route":"ollama-qwen3","latency_ms":42}，让你在前端就能实时监控链路健康度，这是任何通用代理都无法提供的能力。

第三是错误语义的精准翻译与降级。看热搜词里高频出现的unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:1572，这其实是OpenClaw在告诉你：“我作为网关本身运行正常，但我调用下游服务时失败了，且失败原因不明”。它没有把原始错误（比如Ollama进程崩溃、网络超时、认证失败）直接甩给前端，而是做了标准化包装。更关键的是，它支持配置fallback策略：当Claude API返回429（限流）时，自动降级到本地Qwen3继续响应；当Ollama返回404（模型未加载）时，返回预设的友好提示而非裸露的502。这种基于AI业务语义的错误治理，是手写代理永远无法覆盖的护城河。

2.2 为什么放弃其他网关方案：对比Spring Cloud Gateway、Kong、Traefik

在选型阶段，我们团队实测过四套主流网关方案，最终锁定OpenClaw，决策依据非常务实：

Spring Cloud Gateway：Java生态成熟，但启动内存占用高达512MB+，对轻量级本地部署不友好；其Predicate和Filter机制需大量Java代码开发才能实现模型路由逻辑，配置复杂度远超YAML；最关键的是，它默认不支持SSE流式响应的透传优化，需额外开发WebClient流式适配器，工程成本过高。
Kong：功能强大，插件生态丰富，但重度依赖PostgreSQL数据库存储路由规则，本地单机部署需额外维护DB；其AI专用插件（如kong-plugin-ai-proxy）社区维护停滞，最新版不兼容OpenAI v1.0+规范；实测中遇到doesn't look like an anthropic model: expected a gateway model route reference这类错误时，Kong日志仅显示“upstream timeout”，无法定位是Anthropic API变更还是路由配置错误。
Traefik：Docker友好，动态配置优秀，但其Middleware机制对请求体解析能力弱，无法根据messages[0].role或tools字段做条件路由；对流式响应的支持停留在基础代理层，无法注入usage统计或finish_reason等AI特有字段。
OpenClaw：纯Go编写，单二进制文件<15MB，Windows/macOS/Linux一键运行；所有路由规则、模型映射、限流策略均通过config.yaml声明式定义；内置openclaw skill机制，允许用JavaScript编写自定义路由逻辑（比如“当用户提问含‘专利’二字且长度>50字时，强制路由到Claude”）；错误日志明确标注cc switch local proxy failed while handling，直指本地代理模块故障，排查路径极短。我们用同一份curl -X POST http://localhost:3000/v1/chat/completions -d '{"model":"qwen3","messages":[{"role":"user","content":"你好"}]}'命令，在四套网关上压测1000次，OpenClaw的502错误率最低（0.3% vs Kong 2.1%），平均延迟最低（87ms vs Traefik 142ms），这才是生产环境要的数据。

2.3 本地部署的最小可行架构：你需要准备哪些“零件”

OpenClaw本身只是一个网关，它不生产模型，只调度模型。因此，完整的本地AI工作流必须包含三个物理或逻辑组件，缺一不可：

OpenClaw Gateway主程序：这是核心调度中枢，负责接收统一API、解析请求、路由决策、响应组装。它监听http://localhost:3000（默认端口），对外暴露标准OpenAI兼容接口。
下游模型服务（Provider）：这是真正的“劳动力”。至少需要一个可用的Provider，常见组合有：
- 本地Ollama：http://localhost:11434，提供Qwen3、Llama3等开源模型，零API Key，适合离线场景；
- 远程Anthropic API：https://api.anthropic.com，需有效API Key，提供Claude系列闭源模型，适合高精度任务；
- 自建vLLM服务：http://localhost:8000，通过--served-model-name qwen3-vllm指定模型名，适合需要GPU加速的大模型；
- 飞书Bot Webhook：https://open.feishu.cn/open-apis/bot/v2/hook/xxx，用于将AI响应自动推送到飞书群，实现“AI助理”功能。
支撑服务（Supporting Services）：非必需但强烈推荐，用于提升稳定性与可观测性：
- Redis：redis://localhost:6379，用于分布式限流（Sentinel）、请求缓存、会话状态存储。没有Redis，OpenClaw仍可运行，但会丢失gateway sentinel等高级功能。
- MySQL/PostgreSQL：用于持久化审计日志、用户配额、模型使用统计。教程中暂不启用，但生产环境必须配置。

提示：很多新手踩坑源于混淆“网关”和“模型服务”。当你看到url: http://127.0.0.1:1572报错时，请先确认：1572端口是谁在监听？如果是Ollama，默认端口是11434，1572很可能是你误配了Ollama的--port参数，或是其他服务占用了该端口。用netstat -ano | findstr :1572（Windows）或lsof -i :1572（macOS/Linux）快速定位。

3. 核心配置细节与实操要点：从零开始配置OpenClaw网关的完整链路

3.1 环境准备：安装必备工具链（Node.js、Git、Redis、MySQL）

OpenClaw本身是Go二进制，无需编译，但配置过程高度依赖现代开发工具链。以下步骤按顺序执行，跳过任一环节都可能导致后续配置失败：

第一步：安装Node.js（v18.17.0+）
OpenClaw的openclaw skill（自定义路由脚本）和部分CLI工具基于Node.js。下载地址：https://nodejs.org/dist/
验证安装：

node -v # 必须输出 v18.17.0 或更高版本 npm -v # 必须输出 9.6.7 或更高版本

注意：不要用nvm管理多个Node版本，OpenClaw对Node ABI敏感，混用版本会导致skill加载失败。若已安装旧版，建议卸载后重装v18.17.0 LTS。

第二步：安装Git（v2.35+）
用于克隆OpenClaw官方仓库、拉取最新配置模板。下载地址：https://git-scm.com/
验证安装：

git --version # 输出 2.35.0.windows.1 或类似

实操心得：Git安装时务必勾选“Add Git to PATH”，否则后续git clone命令会报“command not found”。Windows用户注意关闭Windows Defender实时保护，它有时会误杀Git的git-bash.exe进程。

第三步：安装Redis（v7.0+）
OpenClaw的gateway sentinel限流功能强依赖Redis。Windows用户推荐使用MSI安装包（https://github.com/microsoftarchive/redis/releases），macOS用户用brew install redis，Linux用户用sudo apt install redis-server。
启动并验证：

# Windows PowerShell redis-server.exe # macOS/Linux redis-server & # 验证连接 redis-cli ping # 应返回 "PONG"

提示：Redis默认绑定127.0.0.1:6379，无需修改配置。若端口被占用，可在redis.conf中修改port 6379，但需同步更新OpenClaw的config.yaml。

第四步：安装MySQL（v8.0+）或PostgreSQL（v14+）
审计日志功能需要关系型数据库。MySQL安装包：https://dev.mysql.com/downloads/installer/，PostgreSQL：https://www.postgresql.org/download/。
创建专用数据库（以MySQL为例）：

CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'openclaw'@'localhost' IDENTIFIED BY 'StrongPass123!'; GRANT ALL PRIVILEGES ON openclaw.* TO 'openclaw'@'localhost'; FLUSH PRIVILEGES;

注意：密码必须包含大小写字母、数字、特殊字符，MySQL 8.0+默认启用caching_sha2_password插件，确保客户端连接时指定--default-auth=caching_sha2_password。

3.2 获取OpenClaw二进制与初始化配置

OpenClaw不提供传统意义上的“安装包”，而是通过GitHub Release分发预编译二进制。这是为了确保跨平台一致性，避免用户因Go环境差异导致构建失败。

获取二进制文件：
访问 https://github.com/openclaw-ai/openclaw/releases ，找到最新Release（如v0.8.2），下载对应操作系统的openclaw_*.zip文件。

Windows：openclaw_0.8.2_windows_amd64.zip
macOS Intel：openclaw_0.8.2_darwin_amd64.zip
macOS Apple Silicon：openclaw_0.8.2_darwin_arm64.zip
Linux：openclaw_0.8.2_linux_amd64.tar.gz

解压并初始化配置：

# 创建项目目录 mkdir openclaw-deploy && cd openclaw-deploy # 解压（以Windows为例） tar -xzf openclaw_0.8.2_windows_amd64.zip # 初始化默认配置（关键步骤！） ./openclaw init config

此命令会生成config.yaml、providers.yaml、skills/目录三个核心文件。init config不是简单复制模板，而是根据当前系统环境（如检测到已安装Redis）自动填充redis_url: redis://localhost:6379等字段，极大降低新手配置门槛。

实操心得：./openclaw init config必须在openclaw二进制同级目录下执行，否则会报failed to create config: no such file or directory。若执行后config.yaml为空，说明二进制文件权限不足（Linux/macOS需chmod +x openclaw）。

3.3 深度解析config.yaml：每个字段背后的业务含义

config.yaml是OpenClaw的“大脑”，其结构设计直指AI网关的核心矛盾。下面逐字段解读，不仅告诉你“怎么填”，更解释“为什么这样填”：

# config.yaml 核心字段详解 server: host: "0.0.0.0" # 监听所有网卡，允许局域网设备访问（如手机调试） port: 3000 # 对外API端口，可改为8000避免与Docker冲突 cors: true # 启用CORS，让浏览器前端（如Vue/React）可直接调用 providers: - name: "ollama" # Provider唯一标识，路由规则中引用此名 type: "ollama" # 类型决定底层通信协议（ollama/vllm/anthropic/feishu） base_url: "http://localhost:11434" # Ollama默认端口，非1572！ models: # 此Provider支持的模型列表，必须与Ollama中`ollama list`输出一致 - "qwen3:14b" # 模型名需精确匹配，包括tag（:14b） - "llama3:8b" timeout: 30000 # 单次请求超时30秒，防止Ollama加载大模型卡死 - name: "anthropic" # 第二个Provider，支持Claude type: "anthropic" base_url: "https://api.anthropic.com" api_key: "${ANTHROPIC_API_KEY}" # 强烈建议用环境变量，避免密钥硬编码 models: - "claude-3-5-sonnet-20240620" timeout: 60000 # Anthropic响应较慢，超时设为60秒 routes: - model: "qwen3.*" # 正则匹配，所有以qwen3开头的model名 provider: "ollama" # 路由到ollama Provider priority: 10 # 优先级，数值越大越优先匹配 - model: "claude.*" # 匹配claude系列 provider: "anthropic" priority: 20 - model: ".*" # 通配符，兜底路由 provider: "ollama" # 所有未匹配的请求，都交给本地Ollama sentinel: enabled: true # 启用限流，防止API被刷爆 redis_url: "redis://localhost:6379" # 必须与你安装的Redis地址一致 rules: - key: "ip" # 按IP限流 limit: 10 # 每分钟最多10次 window: 60 - key: "model" # 按模型限流 limit: 5 # 每分钟每个模型最多5次 window: 60 logging: level: "info" # 日志级别，调试时可设为"debug" file: "logs/openclaw.log" # 日志文件路径，自动创建logs目录

关键参数计算逻辑：timeout值不是拍脑袋定的。Ollama加载14B模型首次响应约2-5秒，后续流式响应间隔<100ms，故设30秒足够；Anthropic API因网络抖动，P95延迟约45秒，设60秒留出缓冲。priority值决定路由顺序，若qwen3.*和.*同时匹配，优先级高的qwen3.*生效，避免兜底规则误伤。

3.4 providers.yaml：如何安全接入不同类型的模型服务

providers.yaml是OpenClaw的“供应商名录”，它解耦了网关与具体模型服务的耦合。每个Provider的配置都针对其协议特性做了深度适配：

Ollama Provider配置要点：

name: "ollama" type: "ollama" base_url: "http://localhost:11434" models: - "qwen3:14b" - "llama3:8b" timeout: 30000 # 无需api_key，Ollama默认无认证

注意：Ollama必须提前加载模型！执行ollama run qwen3:14b，等待下载完成并看到>>>提示符。若base_url指向127.0.0.1:1572，请立即检查Ollama是否在该端口运行：ollama serve --host 127.0.0.1:1572（不推荐，破坏默认约定）。

Anthropic Provider配置要点：

name: "anthropic" type: "anthropic" base_url: "https://api.anthropic.com" api_key: "${ANTHROPIC_API_KEY}" models: - "claude-3-5-sonnet-20240620" timeout: 60000 headers: "anthropic-version": "2023-06-01" # Anthropic API强制要求的Header

安全实践：api_key必须用环境变量${ANTHROPIC_API_KEY}。在启动前设置：export ANTHROPIC_API_KEY="sk-ant-api03-xxx"（Linux/macOS）或set ANTHROPIC_API_KEY=sk-ant-api03-xxx（Windows）。硬编码密钥会导致Git提交泄露，是严重安全风险。

飞书Bot Provider配置要点：

name: "feishu-bot" type: "feishu" webhook_url: "${FEISHU_WEBHOOK_URL}" # 飞书群Bot的Webhook地址 timeout: 10000 # 飞书Bot不支持流式，故自动禁用streaming

实操技巧：飞书Webhook地址在飞书管理后台“机器人”页面生成，格式为https://open.feishu.cn/open-apis/bot/v2/hook/xxx。测试时，先用curl -X POST ${FEISHU_WEBHOOK_URL} -d '{"msg_type":"text","content":{"text":"test"}}'验证Bot是否可用。

3.5 启动与验证：三步确认网关是否真正就绪

配置完成后，启动是最后一步，也是最容易出错的环节。我们采用“分层验证法”，逐层排除问题：

第一步：启动OpenClaw并观察日志

# 启动（后台运行，便于查看日志） ./openclaw start --config config.yaml # 或前台运行，实时查看日志 ./openclaw run --config config.yaml

成功启动的日志特征：

INFO[0000] OpenClaw Gateway started on http://0.0.0.0:3000 INFO[0000] Loaded 2 providers: ollama, anthropic INFO[0000] Loaded 3 routes with priorities [10 20 30] INFO[0000] Sentinel enabled with Redis at redis://localhost:6379

常见失败日志：FATAL[0000] failed to connect to Redis: dial tcp 127.0.0.1:6379: connect: connection refused—— 表明Redis未启动；ERROR[0000] provider 'ollama' failed health check: Get "http://localhost:11434/health": dial tcp 127.0.0.1:11434: connect: connection refused—— 表明Ollama未运行。

第二步：健康检查API验证
用curl调用网关自带的健康检查端点：

curl http://localhost:3000/health # 应返回 {"status":"ok","providers":[{"name":"ollama","status":"healthy"},{"name":"anthropic","status":"healthy"}]}

此API会主动探测所有Provider的连通性，是比单纯看端口更可靠的验证方式。

第三步：真实请求测试（关键！）
发送一个标准OpenAI格式请求，验证端到端链路：

curl -X POST http://localhost:3000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3:14b", "messages": [{"role": "user", "content": "你好，你是谁？"}], "stream": false }'

预期成功响应（精简）：

{ "id": "chatcmpl-xxx", "object": "chat.completion", "created": 1717023456, "model": "qwen3:14b", "choices": [{ "index": 0, "message": {"role": "assistant", "content": "我是通义千问Qwen3，一个开源大语言模型..."}, "finish_reason": "stop" }] }

注意：若返回502 Bad Gateway，请按此顺序排查：1)curl http://localhost:11434/health确认Ollama健康；2)cat logs/openclaw.log | grep "qwen3"查看网关路由日志；3) 检查config.yaml中routes的model正则是否匹配qwen3:14b（冒号是字面量，需转义）。

4. 实操过程与核心环节实现：从启动到生产就绪的完整工作流

4.1 启动脚本自动化：告别每次手动敲命令

手动执行./openclaw run --config config.yaml效率低下，且无法保证服务常驻。我们为不同系统编写健壮的启动脚本：

Windows批处理脚本（start-gateway.bat）：

@echo off setlocal enabledelayedexpansion :: 设置环境变量 set ANTHROPIC_API_KEY=sk-ant-api03-xxx set FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx :: 启动Redis（若未运行） tasklist /fi "imagename eq redis-server.exe" 2>nul | find /i "redis-server.exe" >nul if %errorlevel% neq 0 ( echo Starting Redis... start "" "C:\Program Files\Redis\redis-server.exe" timeout /t 3 >nul ) :: 启动OpenClaw echo Starting OpenClaw Gateway... start "" "./openclaw.exe" run --config config.yaml --log-level info echo Gateway started. Logs in logs/openclaw.log pause

实操心得：Windows批处理中start ""命令可避免控制台窗口阻塞，timeout /t 3确保Redis有足够时间初始化。将此脚本放在openclaw-deploy根目录，双击即可一键启动。

Linux/macOS Shell脚本（start-gateway.sh）：

#!/bin/bash # 设置环境变量 export ANTHROPIC_API_KEY="sk-ant-api03-xxx" export FEISHU_WEBHOOK_URL="https://open.feishu.cn/open-apis/bot/v2/hook/xxx" # 启动Redis（systemd用户可跳过） if ! pgrep -x "redis-server" > /dev/null; then echo "Starting Redis..." redis-server & sleep 3 fi # 启动OpenClaw（后台运行，日志重定向） echo "Starting OpenClaw Gateway..." nohup ./openclaw run --config config.yaml --log-level info > logs/gateway.log 2>&1 & echo "Gateway PID: $!" echo "Logs: tail -f logs/gateway.log"

赋予执行权限：chmod +x start-gateway.sh，然后./start-gateway.sh。

4.2 流式响应实战：在前端实现真正的“打字机”效果

OpenClaw的流式响应是其最大亮点，但前端实现有坑。以下是Vue 3 Composition API的可靠实现：

<script setup> import { ref, onMounted } from 'vue' const messages = ref([]) const inputText = ref('') const isLoading = ref(false) const sendMessage = async () => { if (!inputText.value.trim()) return isLoading.value = true // 添加用户消息 messages.value.push({ role: 'user', content: inputText.value }) try { const response = await fetch('http://localhost:3000/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'qwen3:14b', messages: messages.value, stream: true // 关键：必须设为true }) }) if (!response.ok) throw new Error(`HTTP ${response.status}`) // 处理SSE流式响应 const reader = response.body.getReader() let assistantMessage = { role: 'assistant', content: '' } messages.value.push(assistantMessage) while (true) { const { done, value } = await reader.read() if (done) break const chunk = new TextDecoder().decode(value) // 解析SSE格式：data: {"id":"...","choices":[{"delta":{"content":"a"}}]} const lines = chunk.split('\n') for (const line of lines) { if (line.startsWith('data: ')) { try { const data = JSON.parse(line.slice(6)) if (data.choices?.[0]?.delta?.content) { assistantMessage.content += data.choices[0].delta.content // 触发UI更新 messages.value = [...messages.value] } } catch (e) { // 忽略非JSON行（如event: message, id: xxx） } } } } } catch (error) { console.error('Stream error:', error) messages.value.push({ role: 'assistant', content: `❌ 请求失败: ${error.message}` }) } finally { isLoading.value = false } } onMounted(() => { // 按Enter发送 const input = document.getElementById('user-input') input?.addEventListener('keypress', (e) => { if (e.key === 'Enter' && !e.shiftKey) { e.preventDefault() sendMessage() } }) }) </script> <template> <div class="chat-container"> <div class="messages" v-for="msg in messages" :key="msg.id"> <div :class="['message', msg.role]"> <strong>{{ msg.role }}:</strong> {{ msg.content }} </div> </div> <div class="input-area"> <textarea id="user-input" v-model="inputText" placeholder="输入消息..." :disabled="isLoading" /> <button @click="sendMessage" :disabled="isLoading"> {{ isLoading ? '发送中...' : '发送' }} </button> </div> </div> </template>

关键细节：response.body.getReader()是处理流式响应的正确方式，fetch的response.json()会等待整个响应结束，无法实现流式。line.slice(6)精准剥离data:前缀，避免JSON解析失败。实测在Chrome/Firefox/Safari中100%稳定。

4.3 错误诊断与502 Bad Gateway深度排查

热搜词中502 Bad Gateway出现频率极高，但其根源千差万别。我们整理了一份“502错误速查表”，按发生概率排序：

错误日志片段	根本原因	排查命令	解决方案
`url: http://127.0.0.1:1572`	Ollama未在1572端口运行，或`config.yaml`中`base_url`配错	`curl http://localhost:1572/health`	修改`providers.yaml`中`base_url`为`http://localhost:11434`，或启动Ollama时指定端口`ollama serve --host 127.0.0.1:1572`
`cc switch local proxy failed while handling`	OpenClaw的本地代理模块异常，通常因网络策略或防火墙拦截	`telnet localhost 11434`	关闭Windows Defender防火墙，或在`config.yaml`中`server.host`设为`127.0.0.1`（禁用外部访问）
`unauthorized: gateway token missing`	启用了Dashboard鉴权但未提供Token	`curl http://localhost:3000/dashboard`	访问`http://localhost:3000/dashboard`，复制页面顶部Token，添加Header`Authorization: Bearer <token>`到请求中
`doesn't look like an anthropic model: expected a gateway model route reference`	`routes`中`model`正则未匹配到请求的`model`字段	`grep -r "claude" config.yaml`	检查`routes`中`model: "claude.*"`是否拼写正确，确保请求中`"model":"claude-3-5-sonnet-20240620"`能被正则匹配

独家避坑技巧：当curl测试返回502但日志无记录时，大概率是DNS解析失败。OpenClaw默认使用系统DNS，若公司内网DNS污染，会导致base_url域名无法解析。解决方案：在config.yaml中providers下添加dns: ["8.8.8.8", "1.1.1.1"]，强制使用公共DNS。

4.4 生产环境加固：从开发模式到企业级部署

开发环境配置好只是起点，生产环境需关注四大维度：

1. 进程守护：

Linux：用systemd确保开机自启。创建/etc/systemd/system/openclaw.service：

[Unit] Description=OpenClaw AI Gateway After=network.target redis.service [Service] Type=simple User=ubuntu WorkingDirectory=/opt/openclaw-deploy ExecStart=/opt/openclaw-deploy/openclaw run --config /opt/openclaw-deploy/config.yaml Restart=always RestartSec=10 Environment="ANTHROPIC_API_KEY=sk-ant-api03-xxx" [Install] WantedBy=multi-user.target

启用：sudo systemctl daemon-reload && sudo systemctl enable openclaw && sudo systemctl start openclaw

2. HTTPS加密：