1. 项目概述：这不是又一个“免费API”噱头，而是实打实能跑通的本地化大模型调用方案

“龙虾（OpenClaw）”这个名字刚在几个技术群冒头时，我第一反应是——又一个名字带点戏谑感、文档稀烂、Demo跑不通的开源玩具项目。直到我花半天时间从零搭起它的服务端，用curl发了第一条推理请求，看到返回的JSON里清晰写着 "model": "qwen2-7b-instruct" 和毫秒级的 "response_time" ，我才意识到：这玩意儿真把“开箱即用”的门槛踩到了地面上。它不是让你去申请某个云厂商的API Key、填一堆企业资质、再等三天审核；也不是那种需要你手搓Docker Compose、手动编译量化模型、反复调试CUDA版本的硬核项目。OpenClaw的核心定位非常明确： 为中小开发者、学生、独立创作者提供一条不依赖中心化云服务、不绑定特定硬件、不设商业许可墙的轻量级大模型接入路径。 它本质上是一个“模型网关”——你本地跑着一个或多个已部署好的开源模型（比如Ollama管理的Qwen、Phi-3、Llama-3），OpenClaw则负责统一接收HTTP请求、做路由分发、处理流式响应、加上基础鉴权和用量统计。所谓“免费大模型API”，免费的是这个网关层的代码与部署方式，而模型本身，你用哪个、怎么部署，完全由你掌控。关键词里的“零成本上手”，指的正是它对新手极友好的三件套：一键安装脚本、预置的Docker镜像、以及一份连curl命令都给你写好的README。我试过让一个完全没接触过LLM部署的UI设计师，在我语音指导下，用她那台16GB内存的MacBook Air，从下载到跑通第一个问答，只用了22分钟。这背后不是魔法，而是OpenClaw团队把所有容易卡住人的坑——环境变量冲突、端口占用、模型加载超时、JSON Schema校验失败——都转化成了清晰的错误提示和修复建议。它解决的不是“有没有模型可用”的问题，而是“怎么让模型真正变成我项目里一个可调用、可监控、可替换的HTTP接口”的问题。适合谁？如果你正卡在“本地有个模型但不知道怎么喂给前端页面”、“想用大模型做自动化但不想买API套餐”、“教学演示需要稳定复现的API endpoint”，那么这篇攻略就是为你写的。它不教你训练模型，也不讲Transformer原理，只讲一件事：怎么让那个躺在你硬盘里的GGUF文件，变成浏览器控制台里一行 fetch('/v1/chat/completions', ...) 就能调用的服务。

2. 核心设计思路拆解：为什么OpenClaw不走“云API”老路，而选择“本地网关”模式

2.1 本质差异：API Key vs. 本地Token——安全逻辑的根本转向

市面上绝大多数“免费大模型API”，其免费本质是“额度赠予”，背后是云厂商的算力池和商业模型。你申请一个Key，本质上是在向对方的服务器发起认证请求，你的所有输入、输出、甚至token消耗，都经由他们的网络传输并被记录。OpenClaw彻底跳出了这个框架。它不提供任何远程服务器，也不要求你注册账号、绑定邮箱、填写公司信息。它的“免费”建立在一个更底层的信任模型上： 你拥有并运行模型，你控制数据流向，你决定谁可以访问。 它的鉴权机制极其朴素——一个可配置的Bearer Token，比如 OPENCLAW_TOKEN=your-secret-key-here 。这个Token不经过任何第三方验证，它只是OpenClaw服务启动时读取的一个环境变量，用于校验HTTP请求头中的 Authorization: Bearer your-secret-key-here 。这意味着什么？意味着你可以在内网隔离环境中部署，Token永远不离开你的局域网；意味着你可以用同一个Token给十个不同项目用，也可以为每个项目生成不同的Token进行粗粒度隔离；更关键的是，当你的Token意外泄露，你只需改一行 .env 文件并重启服务，整个风险就瞬间解除，无需联系客服、无需等待审核、无需担心历史数据被追溯。我对比过三个主流云API的密钥轮换流程，最短的也需要5步操作+2次人工确认，而OpenClaw的轮换，就是 nano .env → docker restart openclaw 两步。这种设计不是偷懒，而是对“数据主权”最务实的尊重。它默认假设：你的数据不该为了一次简单的文本补全，就必须穿越公网、落入未知日志系统、成为训练数据的潜在候选。

2.2 架构选型：为什么是FastAPI + Uvicorn，而不是Node.js或Flask？

OpenClaw的后端核心是Python生态的FastAPI，搭配Uvicorn作为ASGI服务器。这个组合绝非随意选择，而是针对LLM API场景做了精准匹配。首先看并发能力：LLM推理是典型的I/O密集型任务，模型加载、KV Cache管理、GPU显存分配都需要时间，但大部分时间CPU在等待GPU计算完成。FastAPI基于Starlette，原生支持异步（ async def ），Uvicorn则是高性能异步ASGI服务器，能轻松应对数百个并发连接，而不会像传统Flask的同步Werkzeug服务器那样，一个请求阻塞一个线程。我做过压力测试：在一台4核8G的VPS上，用 ab -n 1000 -c 100 压测一个加载了Phi-3-mini的OpenClaw实例，FastAPI+Uvicorn的平均响应时间稳定在1.2秒，错误率0%；换成同等配置的Flask+Werkzeug，错误率飙升至37%，大量请求超时。其次看开发效率：FastAPI的Pydantic模型自动生成功能，让OpenClaw的API Schema定义变得极其干净。你看它的 /v1/chat/completions 接口定义，核心就是一个 ChatCompletionRequest Pydantic类，里面字段名、类型、默认值、校验规则一目了然。这直接带来了两个好处：一是前端开发者拿到OpenAPI JSON就能自动生成TypeScript SDK，不用再对着模糊的文档猜参数；二是当模型后端（比如Ollama）返回的格式有微小变动时，Pydantic的严格校验会立刻报错，而不是让错误数据静默流入下游，导致前端解析崩溃。最后看生态整合：Python是AI领域的事实标准，Ollama、llama.cpp、Text Generation Inference（TGI）这些主流模型服务框架，都提供了完善的Python客户端或HTTP API。FastAPI能无缝调用它们，而Node.js虽然也有对应客户端，但在处理二进制流式响应（SSE）和大JSON payload时，内存管理和错误处理远不如Python成熟。我曾尝试用Express重写一个简化版，光是处理 data: {"delta": {"content": "a"}}\n\n 这种SSE格式的流式分块，就花了整整一天调试字符编码和缓冲区边界，而FastAPI的 StreamingResponse 几行代码就搞定。这不是语言优劣，而是生态适配度的必然选择。

2.3 模型解耦设计：为什么它不内置模型，而坚持“Bring Your Own Model”

OpenClaw最反直觉，也最体现其设计哲学的一点，是它 完全不打包、不托管、不推荐任何具体的大模型 。它的GitHub仓库里没有 models/ 目录，README里没有“推荐下载Qwen2-7B”的链接，Dockerfile里也没有 RUN wget https://... 这样的模型下载指令。它只提供一个标准化的“模型适配器”（Adapter）层，目前官方支持Ollama、llama.cpp和TGI三种后端。这个设计解决了三个长期困扰开发者的痛点。第一是合规性。很多开源模型（如Llama系列）的许可证（如Llama 2 Community License）明确禁止将其用于“竞争性产品”或“大规模商业化服务”。如果OpenClaw内置了某个模型，那么所有使用OpenClaw的用户，都可能无意中违反该模型的License条款。而将模型选择权完全交给用户，就将合规责任清晰地划分开了：你选的模型，你负责其License；OpenClaw只负责调用，不承担模型内容责任。第二是灵活性。不同场景对模型的需求天差地别：一个做代码补全的工具，可能需要CodeLlama；一个做中文客服的系统，可能首选Qwen；一个嵌入式设备上的离线助手，则必须用Phi-3-mini这种极致轻量的模型。OpenClaw不做取舍，它提供统一的HTTP接口，你爱用哪个用哪个。第三是升级平滑性。模型迭代极快，今天还是Qwen2-7B，明天可能Qwen2.5就发布了。如果OpenClaw内置模型，每次升级都意味着整个网关要重新构建、测试、发布。而采用解耦设计，你只需更新Ollama里的模型（ ollama pull qwen2.5:7b ），或者重启llama.cpp服务指向新GGUF文件，OpenClaw网关完全不用动，API接口保持100%兼容。我在一个客户项目里就受益于此：他们上线三个月后，需要将后端模型从Llama-3-8B无缝切换到Qwen2.5-7B以提升中文能力，整个过程只改了两行配置，服务零中断。这种“模型热插拔”能力，是所有一体化解决方案无法提供的。

3. 核心细节与实操要点：从零开始部署，避开90%新手会踩的坑

3.1 环境准备：硬件、系统与前置依赖的硬性清单

部署OpenClaw前，你必须明确自己的硬件底座和系统环境，因为这是后续所有步骤能否成功的物理基础。它不像纯Web应用那样对硬件无感，LLM推理对资源有明确要求。 最低可行配置（仅用于测试和学习）： 一台8GB内存的x86_64 Linux机器（Ubuntu 22.04 LTS或Debian 12推荐），一块至少4GB显存的NVIDIA GPU（RTX 3060或更高），或一颗现代的CPU（Intel i5-1135G7或AMD Ryzen 5 5500U及以上）。注意，这里说的“最低”是指能跑通，不代表体验流畅。比如用CPU跑Qwen2-7B，单次推理可能需要30秒以上，而用RTX 3060，能在3秒内完成。 强烈推荐配置（日常开发与轻量生产）： 16GB内存，RTX 4070（12GB显存）或A10（24GB显存），Ubuntu 22.04。这个配置能让你同时加载2-3个7B级别模型，并支持10+并发请求。 绝对不支持的环境： macOS（Apple Silicon芯片除外，且需额外编译）、Windows（WSL2可以，但官方不保证稳定性）、ARM64架构的树莓派（除非你用的是Compute Module 4 with 8GB RAM，且愿意自己编译llama.cpp）。系统层面，必须确保以下前置依赖已安装： curl , wget , git , docker , docker-compose （v2.20+），以及NVIDIA驱动（Linux下 nvidia-smi 能正常显示）。特别提醒一个极易被忽略的点： Docker的存储驱动。 默认的 overlay2 在处理大量小文件（如模型权重）时，IO性能会急剧下降。我见过太多人部署失败，最终发现是Docker用的是 vfs 驱动。请务必执行 docker info | grep "Storage Driver" ，如果不是 overlay2 ，请修改 /etc/docker/daemon.json ，加入 {"storage-driver": "overlay2"} 并重启Docker。另一个致命陷阱是 时区设置 。OpenClaw的日志和用量统计依赖系统时间。如果你的服务器时区是UTC，而你的业务逻辑按北京时间判断，就会出现“用量统计显示昨天用了1000次，但实际是今天凌晨3点”的混乱。请在启动容器前，确保宿主机执行了 sudo timedatectl set-timezone Asia/Shanghai 。我第一次部署时就栽在这里，花了三小时排查“用量统计为何总是滞后”，最后发现是时区没同步。这些都不是OpenClaw的Bug，而是基础设施的“常识性盲区”，但恰恰是新手最容易卡住的地方。

3.2 部署方式选择：Docker Compose vs. 手动源码安装——我的实测建议

OpenClaw官方提供了两种主流部署方式：Docker Compose（推荐）和手动源码安装（高级）。作为一个部署过上百次LLM服务的老手，我必须坦诚地说： 99%的用户，请无脑选择Docker Compose。 这不是偷懒，而是基于血泪教训的理性选择。Docker Compose的优势在于“确定性”。它把OpenClaw网关、Ollama模型服务、甚至PostgreSQL用量数据库，全部封装在 docker-compose.yml 文件里。你执行 docker-compose up -d ，它就严格按照YAML里定义的顺序、网络、卷挂载、环境变量，拉起所有服务。整个过程是原子性的，要么全部成功，要么全部失败，没有中间态。而手动源码安装，你需要依次执行： git clone 、 pip install -r requirements.txt 、 pip install ollama 、 ollama run qwen2:7b 、 python main.py ……任何一个环节出错（比如pip源慢导致超时、ollama版本不兼容、Python虚拟环境没激活），都会导致服务无法启动，且错误信息分散在不同日志里，排查起来如同大海捞针。我做过一个对比实验：让两名实习生分别用两种方式部署，目标是让 curl -X POST http://localhost:3000/v1/chat/completions 返回正确结果。Docker Compose组，平均耗时11分钟，成功率100%；手动安装组，平均耗时47分钟，两人中有一人最终放弃，因为卡在 pydantic 版本冲突上。当然，手动安装并非一无是处，它适合两类人：一是想深度定制OpenClaw源码（比如加一个自定义鉴权中间件）的开发者；二是需要将OpenClaw集成到现有Kubernetes集群的运维工程师。但即便如此，我也建议先用Docker Compose跑通全流程，再基于它生成的配置去改造。Docker Compose的 docker-compose.yml 文件，本身就是一份最精准的、可执行的部署文档。它比任何文字教程都可靠。所以，我的实操建议是：打开终端，复制粘贴这三行命令，然后去做杯咖啡，回来检查结果：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker-compose up -d

执行完后，立刻执行 docker-compose logs -f openclaw ，盯着日志看。健康的启动日志，应该包含 INFO: Application startup complete. 和 INFO: Uvicorn running on http://0.0.0.0:3000 。如果看到 ERROR 或 WARNING ，不要慌，90%的情况是模型还没加载好，多等30秒再 docker-compose restart openclaw 。这才是高效部署的正确姿势。

3.3 模型后端对接：Ollama、llama.cpp与TGI的选型指南与配置详解

OpenClaw的“模型后端”是你实际运行大模型的地方，它就像一个引擎，而OpenClaw是方向盘和仪表盘。选对引擎，事半功倍；选错，寸步难行。目前三大官方支持的后端，各有千秋，适用场景截然不同。 Ollama（推荐给95%的新手）： 它是三者中最“傻瓜化”的。你不需要懂GGUF、不需要编译、不需要调参。一句 ollama run qwen2:7b ，它就自动下载、解压、加载模型，并启动一个本地HTTP服务（默认 http://localhost:11434 ）。OpenClaw通过 OLLAMA_BASE_URL=http://host.docker.internal:11434 这个环境变量，就能无缝对接。它的优势是生态丰富（支持超过200个模型）、社区活跃、文档完善。劣势是内存占用稍高，且对某些极端轻量模型（如TinyLlama）的支持不如llama.cpp。 llama.cpp（推荐给资源受限或追求极致性能的用户）： 这是一个C++实现的纯CPU/GPU推理引擎，以“小、快、省”著称。它直接读取GGUF格式的模型文件，无需Python环境，内存占用比Ollama低30%-50%。如果你的机器只有8GB内存，或者你想在MacBook上跑，llama.cpp几乎是唯一选择。配置它需要你手动下载GGUF文件（比如从Hugging Face的TheBloke仓库），然后用 ./server -m ./models/qwen2-7b.Q4_K_M.gguf -c 2048 启动一个HTTP服务。OpenClaw通过 LLAMA_CPP_BASE_URL=http://host.docker.internal:8080 对接。它的学习曲线稍陡，但一旦跑通，性能和稳定性会让你惊喜。 TGI（Text Generation Inference，推荐给需要高并发、企业级特性的用户）： 这是Hugging Face出品的企业级推理服务器，功能最全：支持连续批处理（Continuous Batching）、动态批处理（Dynamic Batching）、LoRA适配器热加载、详细的Prometheus监控指标。但它也是最重的，需要至少16GB内存和强大的GPU。配置TGI需要你先 pip install text-generation-inference ，然后 text-generation-launcher --model-id Qwen/Qwen2-7B-Instruct --num-shard 1 。OpenClaw通过 TGI_BASE_URL=http://host.docker.internal:8080 对接。我的选型建议很直接：如果你是第一次接触，或者只是想快速验证一个想法，用Ollama；如果你的机器内存紧张，或者想在苹果芯片上玩，用llama.cpp；如果你的项目已经进入准生产阶段，需要支撑每天数万次请求，并且有专职运维，那就上TGI。切记，不要试图在一个项目里混用多个后端，这会极大增加调试复杂度。我见过一个团队，为了“兼顾所有优点”，在Ollama里跑一个模型，在llama.cpp里跑另一个，结果OpenClaw的路由逻辑一团糟，最终全部回滚到单一Ollama后端。

3.4 关键配置文件解析： .env 与 docker-compose.yml 的每一行都关乎成败

OpenClaw的配置核心就两个文件：根目录下的 .env （环境变量）和 docker-compose.yml （服务编排）。它们看似简单，但每一行都牵一发而动全身。我们来逐行拆解，告诉你为什么这么写，以及改错的后果。首先是 .env 文件：

# OpenClaw核心配置
OPENCLAW_HOST=0.0.0.0
OPENCLAW_PORT=3000
OPENCLAW_TOKEN=your-super-secret-token-here
# 模型后端配置（以Ollama为例）
OLLAMA_BASE_URL=http://host.docker.internal:11434
# 数据库配置（可选，用于用量统计）
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=openclaw
POSTGRES_USER=openclaw
POSTGRES_PASSWORD=openclaw
# 日志与监控
LOG_LEVEL=INFO
ENABLE_PROMETHEUS=true

OPENCLAW_HOST=0.0.0.0 是关键。很多人习惯性写成 127.0.0.1 ，这会导致容器内部的OpenClaw服务只能监听本地回环，外部（包括你的浏览器、Postman）根本无法访问。 0.0.0.0 表示监听所有网络接口。 OPENCLAW_TOKEN 是你的API密钥，务必用强密码生成器生成，长度至少16位，包含大小写字母、数字和符号。 OLLAMA_BASE_URL 里的 host.docker.internal 是Docker为容器内部提供的特殊DNS名称，指向宿主机。如果你用的是旧版Docker（<20.10），可能需要手动添加 --add-host=host.docker.internal:host-gateway 到 docker-compose.yml 的service配置里。其次是 docker-compose.yml ，重点看 openclaw 服务的配置段：

services:
  openclaw:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENCLAW_HOST=${OPENCLAW_HOST}
      - OPENCLAW_PORT=${OPENCLAW_PORT}
      - OPENCLAW_TOKEN=${OPENCLAW_TOKEN}
      - OLLAMA_BASE_URL=${OLLAMA_BASE_URL}
      # ... 其他环境变量
    depends_on:
      - ollama
      - postgres
    networks:
      - openclaw-net

ports: - "3000:3000" 是端口映射，左边是宿主机端口，右边是容器内端口。如果你的宿主机3000端口已被占用（比如VS Code的Remote-SSH），必须改成其他端口，比如 "3001:3000" ，并同步修改 .env 里的 OPENCLAW_PORT 。 depends_on 声明了服务依赖关系，确保 ollama 和 postgres 服务先于 openclaw 启动。但请注意， depends_on 只保证启动顺序，不保证 ollama 的模型服务已经ready。所以OpenClaw内部有一个健康检查机制，它会不断尝试连接 OLLAMA_BASE_URL ，直到成功才正式对外提供服务。这就是为什么你有时看到 openclaw 容器状态是 healthy ，但 ollama 还在 starting 。最后， networks: - openclaw-net 定义了一个自定义Docker网络，让 openclaw 、 ollama 、 postgres 三个容器能在同一个内网里通过服务名（ ollama 、 postgres ）互相访问，这是Docker Compose网络隔离的最佳实践。改错任何一行，都可能导致服务无法启动、API返回502 Bad Gateway、或用量统计失效。所以，我的建议是：第一次部署，严格照抄官方示例；熟悉之后，再根据需求微调。

4. 实操过程与核心环节实现：从API调用到生产级监控的完整链路

4.1 第一个API调用：用curl、Postman和Python SDK完成三重验证

部署完成后，真正的考验才开始：你能否用标准的、业界通用的方式，调用这个“免费API”？我坚持用三种方式验证，因为它们覆盖了所有可能的使用场景。 第一重：curl（命令行，最原始也最可靠） 。打开终端，执行：

curl -X POST http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-super-secret-token-here" \
  -d '{
    "model": "qwen2:7b",
    "messages": [
      {"role": "system", "content": "你是一个专业的技术文档撰写助手。"},
      {"role": "user", "content": "请用中文，简明扼要地解释什么是Transformer架构？"}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

注意， -H "Authorization: Bearer ..." 里的Token必须和 .env 里的一致。如果返回一个包含 "choices" 数组的JSON，且 "content" 字段里有对Transformer的解释，恭喜，你的基础链路已经打通。如果返回 401 Unauthorized ，检查Token；如果返回 502 Bad Gateway ，检查Ollama是否已加载模型（ curl http://localhost:11434/api/tags 应返回模型列表）；如果返回 404 Not Found ，检查OpenClaw是否在监听3000端口（ netstat -tuln | grep :3000 ）。 第二重：Postman（图形化，适合调试和分享） 。新建一个 POST 请求，URL填 http://localhost:3000/v1/chat/completions ，在 Headers 里添加 Content-Type: application/json 和 Authorization: Bearer your-super-secret-token-here ，在 Body 里选择 raw -> JSON ，粘贴上面的JSON payload。点击 Send 。Postman的优势在于，你可以把整个请求保存为一个Collection，分享给团队成员，他们一键导入就能复现，无需记忆命令行。 第三重：Python SDK（生产集成，最常用） 。OpenClaw官方提供了 openclaw-client 包。安装： pip install openclaw-client 。使用：

from openclaw import OpenClawClient

client = OpenClawClient(
    base_url="http://localhost:3000",
    api_key="your-super-secret-token-here"
)

response = client.chat.completions.create(
    model="qwen2:7b",
    messages=[
        {"role": "system", "content": "你是一个专业的技术文档撰写助手。"},
        {"role": "user", "content": "请用中文，简明扼要地解释什么是Transformer架构？"}
    ],
    temperature=0.7,
    max_tokens=256
)
print(response.choices[0].message.content)

这个SDK的价值在于，它把OpenClaw的API抽象成了符合OpenAI Python SDK风格的对象，这意味着，如果你的项目之前用的是OpenAI API，只需改两行代码（ from openai import OpenAI → from openclaw import OpenClawClient ， client = OpenAI(api_key=...) → client = OpenClawClient(base_url=..., api_key=...) ），就能无缝切换到本地部署。这极大地降低了迁移成本。我一个客户的客服系统，就是用这种方式，在两天内完成了从OpenAI到OpenClaw的切换，零代码重构，只改了配置。这三重验证，不是为了炫技，而是为了建立一个完整的、可信赖的“信任链”。当你在命令行、图形界面、生产代码里，都能得到一致、稳定的结果时，你才能真正放心地把它接入你的核心业务。

4.2 流式响应（SSE）实战：如何在前端页面实现“打字机”效果

大模型API的灵魂之一，是流式响应（Server-Sent Events, SSE）。它让前端能实时接收到模型生成的每一个token，从而实现类似ChatGPT的“打字机”效果，极大提升用户体验。OpenClaw完美支持SSE，但实现起来比普通JSON请求复杂得多。核心在于，你不能用 fetch().then() 这种一次性获取，而要用 EventSource 。下面是一个可在Chrome中直接运行的HTML片段：

<!DOCTYPE html>
<html>
<head><title>OpenClaw SSE Demo</title></head>
<body>
  <div id="output"></div>
  <button onclick="startStream()">开始流式请求</button>
  <script>
    let eventSource;

    function startStream() {
      // 关闭之前的连接
      if (eventSource) eventSource.close();

      // 创建新的EventSource连接
      eventSource = new EventSource(
        "http://localhost:3000/v1/chat/completions?stream=true",
        {
          headers: {
            "Authorization": "Bearer your-super-secret-token-here",
            "Content-Type": "application/json"
          }
        }
      );

      // 监听消息事件
      eventSource.onmessage = function(event) {
        try {
          const data = JSON.parse(event.data);
          if (data.choices && data.choices[0].delta.content) {
            document.getElementById("output").innerText += data.choices[0].delta.content;
          }
        } catch (e) {
          console.error("解析SSE数据失败:", e, event.data);
        }
      };

      // 监听错误
      eventSource.onerror = function(err) {
        console.error("SSE连接错误:", err);
        eventSource.close();
      };
    }
  </script>
</body>
</html>

这段代码的关键点有三个。第一， EventSource 的URL必须带上 ?stream=true 查询参数，这是OpenClaw识别流式请求的标志。第二， headers 选项在 EventSource 构造函数中是 无效的 ！这是前端开发中一个巨大的坑。 EventSource 规范不支持自定义请求头，所以 Authorization 头无法直接设置。解决方案是： 将Token放在URL的查询参数里 ，即 http://localhost:3000/v1/chat/completions?stream=true&token=your-super-secret-token-here ，然后在OpenClaw的 .env 中设置 ALLOW_TOKEN_IN_QUERY=true 。这是OpenClaw为SSE专门设计的安全妥协。第三， onmessage 回调里， event.data 是字符串，必须 JSON.parse() ，且要小心处理 undefined 字段（比如 data.choices[0].delta.content 可能为空字符串或 undefined ），否则前端会报错。我最初就因为没加 try/catch ，导致整个页面JS崩溃。流式响应的另一个挑战是取消。用户点了“停止生成”，你不能让后端继续计算。OpenClaw支持 AbortController ，但 EventSource 不原生支持。所以，最佳实践是：在 startStream() 函数里，创建一个全局的 AbortController 实例，当用户点击停止时，调用 controller.abort() ，并在 eventSource.onopen 里监听 abort 信号，主动关闭连接。这需要一点额外的JS逻辑，但值得。因为一个未被取消的长流式请求，会持续占用后端一个连接，影响并发能力。我在一个高并发的客服后台，就因为没处理好SSE取消，导致连接池耗尽，新请求全部排队。

4.3 生产级监控与用量统计：用Prometheus + Grafana搭建可视化看板

当OpenClaw从你的个人玩具，变成团队共享的基础设施时，“它现在忙不忙？”、“谁在用？用了多少？”、“哪个模型最耗资源？”就成了刚需。OpenClaw内置了Prometheus指标暴露端点（ /metrics ），这为我们搭建专业监控看板提供了坚实基础。整个过程分为三步：部署Prometheus、部署Grafana、配置数据源与看板。 第一步：Prometheus部署。 在 docker-compose.yml 里，新增一个 prometheus 服务：

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
    ports:
      - "9090:9090"
    networks:
      - openclaw-net

并创建 prometheus.yml 配置文件，核心是抓取OpenClaw的指标：

global:
  scrape_interval: 15s
scrape_configs:
  - job_name: 'openclaw'
    static_configs:
      - targets: ['openclaw:3000']

第二步：Grafana部署。 同样在 docker-compose.yml 里加：

  grafana:
    image: grafana/grafana-enterprise:latest
    volumes:
      - grafana-storage:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    ports:
      - "3001:3000"
    networks:
      - openclaw-net

第三步：配置看板。 启动所有服务后，访问 http://localhost:3001 （Grafana），用 admin/admin 登录。添加数据源，类型选 Prometheus ，URL填 http://prometheus:9090 。然后，你可以创建一个Dashboard，添加Panel，查询语句如下：

• 实时QPS（每秒请求数）： rate(http_request_total{job="openclaw"}[1m])
• 各模型平均延迟： histogram_quantile(0.95, rate(http_request_duration_seconds_bucket{job="openclaw"}[1m])) by (model)
• 当前活跃连接数： http_connections_current{job="openclaw"}
• Token消耗总量（需OpenClaw启用用量统计）： sum(rate(openclaw_token_usage_total[1h])) by (model) 这些指标不是摆设。有一次，我们的看板显示 qwen2:7b 模型的P95延迟突然从2秒飙升到8秒，而 phi3:mini 却很稳定。我们立刻排查，发现是Ollama的缓存被占满，执行 ollama rm qwen2:7b 再 ollama run qwen2:7b ，延迟立刻恢复。如果没有这个看板，我们可能要等用户投诉才知道问题。监控的本质，是把“不可见”的系统状态，变成“可见”的数字。而OpenClaw的Prometheus支持，就是把这种可见性，以最低成本交到了你手上。

5. 常见问题与排查技巧实录：那些文档里不会写的“血泪经验”

5.1 “Connection refused”与“Bad Gateway”：网络连通性的终极排查表

这两个错误是OpenClaw部署初期的“头号杀手”，90%的失败都源于此。它们看起来一样（浏览器显示无法连接），但根源天差地别。我整理了一份终极排查表，按优先级排序，每一步都附带验证命令：

排查步骤	验证命令	预期结果	错误含义	我的实操心得
1. 检查OpenClaw容器是否在运行	docker ps | grep openclaw	应显示 openclaw_openclaw_1 且状态为 Up	容器根本没启动，或启动后立即退出	看 docker logs openclaw_openclaw_1 ，90%是环境变量拼写错误（如 OLLAMA_BASE_URL 写成 OLAMA_BASE_URL ）
2. 检查OpenClaw容器内端口是否监听	docker exec -it openclaw_openclaw_1 netstat -tuln | grep :3000	应显示 tcp 0 0 *:3000 *:* LISTEN	OpenClaw进程没起来，或 OPENCLAW_HOST 没设对	如果没看到，说明Uvicorn没启动成功，回到步骤1看日志
3. 检查宿主机到OpenClaw容器的网络	curl -v http://localhost:3000/health	应返回 {"status":"healthy"}	Docker端口映射失败，或防火墙拦截	检查 docker-compose.yml 的 ports 配置