当你满心欢喜把 Qwen3-32B 跑起来，却发现 OpenClaw 怎么都不理你，甚至甩给你一个 400 —— 别慌，这篇就是为你准备的。

🦞 写在前面

如果你和我一样，手头有台 4 卡 L20 服务器，想把 Qwen3-32B 作为 OpenClaw 的本地大脑，那么恭喜你，你已经走完了最难的一步——让模型跑起来。但接下来的“联调”环节，才是真正考验耐心的时候。

OpenClaw（江湖人称“龙虾”）是一个强大的 AI 助理框架，但它和 vLLM 的磨合并不是开箱即用的。这篇文章记录了我在集成过程中遇到的所有奇葩问题，以及最终找到的解决方案。希望你能少熬几个夜。

⚙️ 基础环境回顾（快速带过）

· 服务器：Ubuntu 22.04 + 4×NVIDIA L20 (192GB 显存)
· 推理框架：vLLM 0.8.5
· 模型：Qwen3-32B-AWQ (4-bit 量化)
· OpenClaw 版本：2026.3.8

如果你还没部署模型，可以参考我另一篇文章《4卡部署Qwen3-32B终极指南》，这里直接跳过模型部署，聚焦 OpenClaw 集成。

🚧 坑一：OpenClaw 配置模型提供商——一个斜杠引发的血案

现象

在 OpenClaw 配置文件中添加了自定义模型，启动后却总是报 400 Bad Request，日志里啥也没有。

原因

OpenClaw 的 baseUrl 必须指向 vLLM 服务的 /v1 路径。很多人会写成 http://10.10.12.6:8000，少了最后的 /v1，导致 OpenClaw 请求的 URL 变成了 http://10.10.12.6:8000/chat/completions，而不是正确的 http://10.10.12.6:8000/v1/chat/completions。

解决方案

```json
{
  "baseUrl": "http://10.10.12.6:8000/v1",  // 注意最后的 /v1 不能省
  "apiKey": "your-secure-key",
  "api": "openai-completions",
  "models": [
    {
      "id": "qwen3",        // 必须与 vLLM 的 --served-model-name 一致
      "name": "Qwen3-32B",
      "contextWindow": 40960,
      "maxTokens": 4096
    }
  ]
}
```

🚧 坑二：模型名称——你以为的“qwen3”不一定是“qwen3”

现象

配置明明看起来没问题，但 OpenClaw 发请求时还是 400。查看 vLLM 日志，发现报错 model not found。

原因

OpenClaw 发送的 model 字段值必须和 vLLM 启动时指定的 --served-model-name 完全一致。如果你启动时用了：

```bash
--served-model-name qwen3
```

那么 OpenClaw 配置里的 id 必须是 "qwen3"。

如果你没加 --served-model-name，那么 vLLM 默认使用模型路径作为模型 ID，比如 "/media/chizi/data/qwen3-32b-awq/Qwen/Qwen3-32B-AWQ"。这种情况下，OpenClaw 的 id 必须填这个长路径。

教训：强烈建议启动时指定一个短名称，比如 --served-model-name qwen3，省去后期配置的麻烦。

🚧 坑三：工具调用（Function Calling）——OpenClaw 的隐藏需求

现象

OpenClaw 发起的请求中包含了 tools 字段（用于让模型调用工具），但 vLLM 报错：

```
{"object":"error","message":"\"auto\" tool choice requires --enable-auto-tool-choice and --tool-call-parse to be set","type":"BadRequestError"}
```

原因

OpenClaw 默认会发送一个巨大的工具列表（包括 read、write、exec 等几十个工具定义），并期望模型支持工具调用。但 vLLM 启动时没有开启工具调用功能。

解决方案

在 vLLM 启动命令中加上：

```bash
--enable-auto-tool-choice \
--tool-call-parser hermes
```

hermes 是一个兼容性较好的 parser，实测对 Qwen3 有效。如果你用其他 parser（比如 mistral、llama3_json），可能会遇到格式不匹配的问题。

🚧 坑四：上下文长度 mismatch——400 的另一个元凶

现象

OpenClaw 发送的请求明明不大，却返回 400。查看 vLLM 日志，发现：

```
ValueError: This model's maximum context length is 14000 tokens. However, you requested 14233 tokens...
```

原因

OpenClaw 的请求中，系统提示、用户消息加上工具定义，总 token 数超过了 vLLM 设置的 --max-model-len。

解决方案

1. 调高 vLLM 的 max-model-len（如果你的显存够）：
   ```bash
   --max-model-len 40960
   ```
2. 同步修改 OpenClaw 配置中的 contextWindow，让 OpenClaw 知道模型能处理多长上下文：
   ```json
   "contextWindow": 40960
   ```
3. 如果显存不够，可以限制 OpenClaw 发送的最大 token 数，但 OpenClaw 本身没有直接配置，需要调整它的系统提示或工具列表。

🚧 坑五：Subagents 并发——多卡也要排队

现象

OpenClaw 执行复杂任务时（比如同时分析多个文件），vLLM 服务突然卡死，甚至崩溃。

原因

OpenClaw 的 subagents 特性会同时发起多个请求，而 vLLM 默认的并发处理能力有限（--max-num-seqs 默认值较低）。当多个请求同时涌入时，可能耗尽显存或导致 vLLM 内部队列溢出。

解决方案

1. 提高 vLLM 的并发上限：
   ```bash
   --max-num-seqs 64       # 允许同时处理 64 个请求
   --max-num-batched-tokens 40960  # 单批次最大 token 数
   ```
2. 在 OpenClaw 中限制 subagents 并发（可选）：
   ```json
   "subagents": {
     "maxConcurrent": 8
   }
   ```

🚧 坑六：API Key 的幽灵

现象

所有配置都对了，但偶尔还是 401 Unauthorized。

原因

OpenClaw 配置中的 apiKey 与 vLLM 启动时的 --api-key 不一致。可能的问题：

· 启动命令中 API Key 被截断（比如我一开始的命令末尾少了几个字符）
· OpenClaw 配置文件中填了多余的空格
· 环境变量中的 apiKey 被 __OPENCLAW_REDACTED__ 覆盖，但实际值不匹配

解决方案

1. 检查 vLLM 启动命令，确保 --api-key 是完整且没有特殊字符的字符串。
2. 在 OpenClaw 中重新输入一次，不要从文档复制粘贴（容易带隐形字符）。
3. 测试 API：用 curl 直接请求，确认密钥有效：
   ```bash
   curl -H "Authorization: Bearer your-key" http://10.10.12.6:8000/v1/models
   ```

🚧 坑七：心跳日志刷屏，但模型不干活

现象

OpenClaw 日志里不断出现：

```
DEBUG 03-07 17:38:24 [metrics.py:486] Avg prompt throughput: 0.0 tokens/s...
DEBUG 03-07 17:38:24 [engine.py:215] Waiting for new requests in engine loop.
```

但发消息没反应。

原因

这是 vLLM 的正常空闲日志，不代表有问题。真正的原因可能是 OpenClaw 根本没把请求发过来，或者请求格式错误。

解决

回到坑一到坑六，检查 OpenClaw 配置。如果 curl 能通，OpenClaw 不通，大概率是配置问题。

✅ 最终稳定配置（可直接复制）

vLLM 启动命令

```bash
export VLLM_USE_V1=0
export NCCL_P2P_DISABLE=1
export NCCL_IB_DISABLE=1
export NCCL_SOCKET_IFNAME=ens33

nohup vllm serve /media/chizi/data/qwen3-32b-awq/Qwen/Qwen3-32B-AWQ \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.8 \
  --max-model-len 40960 \
  --trust-remote-code \
  --port 8000 \
  --host 0.0.0.0 \
  --served-model-name qwen3 \
  --api-key "your-secure-key" \
  --enable-auto-tool-choice \
  --tool-call-parser hermes \
  --max-num-seqs 64 \
  --enforce-eager \
  > qwen3.log 2>&1 &
```

OpenClaw 配置片段

```json
"custom-qwen": {
  "baseUrl": "http://10.10.12.6:8000/v1",
  "apiKey": "your-secure-key",
  "api": "openai-completions",
  "models": [
    {
      "id": "qwen3",
      "name": "Qwen3-32B (4卡)",
      "contextWindow": 40960,
      "maxTokens": 4096
    }
  ]
}
```

📌 总结

OpenClaw 和 vLLM 的集成，本质上是一个“协议对齐”的过程。OpenClaw 期待一个标准的 OpenAI API 服务，而 vLLM 默认可能没开启某些功能。只要把以下几点对齐，就能丝滑运行：

1. URL 必须带 /v1
2. 模型名称必须一致
3. 开启工具调用
4. 上下文长度对齐
5. API Key 不能错

如果你也踩过类似的坑，欢迎在评论区补充。愿你的龙虾和千问从此和睦相处，不再 400。