OpenClaw 调用本地模型（vLLM）

应用场景：OpenClaw + 本地 vLLM + Qwen3-8B + clawdbot-dingtalk

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

写在最前面

部署 OpenClaw vLLM 后端

运行命令 openclaw configure

在配置向导中，依次选择：Local (this machine) -> Model -> vLLM

设置 vLLM 服务地址：http://IP:端口/v1

设置 vLLM API key：填写你的密钥（若服务未启用鉴权，可暂用任意字符）

指定 vLLM 模型名称：Qwen3-8B

完成配置，点击 Continue 保存

最后，重启网关服务：openclaw gateway restart

以下是部署与调试中可能遇到的典型问题及解决方案。

1. 文档目标

本文档旨在提供一份操作指南，帮助你在 OpenClaw 框架内快速集成并调用本地部署的 vLLM 模型服务，实现稳定、高效的任务处理。我们将重点解决以下四个核心问题：

• 如何部署本地 vLLM 服务，并使其完美兼容 OpenAI 的 API 接口规范。

• 如何在 OpenClaw 的配置文件中，准确无误地声明并指向本地模型服务端点。

• 如何配置模型优先级策略，确保以本地模型为主力，同时设置可靠的云端模型降级备用链路。

• 如何诊断并解决模型交互中常见的 400 状态码错误，特别是在 Qwen3-8B 执行工具调用时的典型故障。

2. 关键结论与配置原则

核心发现：当 OpenClaw 的上下文长度参数已修正为模型真实值，但调用 vLLM 接口仍返回 400 错误，且日志中出现“strict/store ignored”类警告时，这些警告通常具有误导性。问题根源往往在于 vLLM 服务端未启用自动工具调用功能。针对 Qwen3-8B 模型，解决方案是在启动 vLLM 服务器时，显式添加 `--enable-auto-tool-choice` 和 `--tool-call-parser hermes` 这两个关键参数。

由此，我们总结出以下必须遵循的配置原则：

• OpenClaw 配置中的 `contextWindow` 值，必须与后端模型的实际上下文窗口大小（例如 32K）严格对齐，严禁使用超出模型能力的虚高数值。

• 若模型通过 vLLM 提供的 OpenAI 兼容接口进行调用，则 OpenClaw 中对应的 `provider` 类型必须设置为 `openai-completions`。

• 为使 Qwen3-8B 模型能够正确处理和响应 OpenClaw 发起的工具调用请求，必须在 vLLM 启动流程中激活自动工具选择开关，并指定 Hermes 解析器。

• 在排查 400 错误时，首要关注点应是 vLLM 接口返回的响应体（response body）中的 `message` 错误信息，而非仅依赖访问日志进行判断。

3. 环境要求与前置检查

在开始配置前，请确保你的环境满足以下要求：

项目

建议值 / 说明

模型服务引擎

vLLM，需启用并配置 OpenAI 兼容 API

本地部署模型

Qwen3-8B 或其 LoRA 微调版本

OpenClaw Provider 类型

openai-completions

vLLM 服务端口

本文示例使用 18000 端口

模型服务别名

建议统一使用 `sinollm`，以简化配置

上下文窗口大小

必须反映模型真实能力，例如 32768 (32K)

4. vLLM 服务端启动命令详解

以下是为 Qwen3-8B 模型优化后的 vLLM 服务启动命令，已集成保障工具调用功能正常运作的必要参数：

python3 start_server.py \
  --model /application/Qwen3-8B \
  --served-model-name Qwen3-8B\
  --uvicorn-log-level info \
  --chat-template /application/qwen3_nonthinking.jinja \
  --enable-auto-tool-choice \
  --tool-call-parser hermes \
  --disable-async-output-proc \
  --gpu-memory-utilization 0.6 \
  --max-num-batched-tokens 4096 \
  --dtype float16

重点解析 `--enable-auto-tool-choice` 与 `--tool-call-parser hermes` 的必要性：当 OpenClaw 向 vLLM 服务发送包含 `tools` 字段及 `tool_choice=auto` 参数的请求时，若 vLLM 未启用相应功能，将无法解析此类结构化请求。其表象是：访问日志可能仅打印无关紧要的“strict/store ignored”警告，而 `/v1/chat/completions` 接口则会直接返回 400 错误，增加排障难度。

5. OpenClaw 配置文件示例

以下是一段经过验证的 `openclaw.json` 配置片段，其策略是优先调用本地 vLLM 模型，并在遭遇失败时无缝切换至备选模型，保障服务连续性：

{
  "models": {
    "mode": "merge",
    "providers": {
      "vllm": {
        "baseUrl": "http://127.0.0.1:8000/v1",
        "apiKey": "VLLM_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "Qwen3-8B",
            "name": "Qwen3-8B",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 32768,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "vllm/Qwen3-8B"
      }
    }
  }
}

6. 配置验证清单

配置完成后，请对照此清单进行最终检查：

• 确保 `baseUrl` 字段的末尾包含 `/v1` 路径，完整格式应为 `http://:/v1`。

• 确认 `api` 字段的值已设置为 `openai-completions`，避免误用为 `anthropic-messages` 等类型。

• OpenClaw 配置中 `model` 对象的 `id` 字段，必须与 vLLM 启动命令中 `--served-model-name` 指定的名称完全一致（本文示例统一为 `sinollm`）。

• 核对 `contextWindow` 数值，确保其为模型真实支持的长度（如 `32768`），切勿保留或设置如 `128000` 等不切实际的高值。

• 如需配置故障转移，建议将 fallback 目标指向可靠的云端模型；但需注意，HTTP 400 类错误可能不会自动触发 fallback 机制。

7. 快速验证与接口测试

7.1 基础聊天功能验证

使用以下 curl 命令，测试 vLLM 服务的常规对话接口是否就绪：

curl http://127.0.0.1:18000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VLLM_API_KEY" \
  -d '{
    "model": "Qwen3-8B",
    "messages": [
      {"role": "user", "content": "你好，只回复OK"}
    ],
    "max_tokens": 16
  }'

7.2 自动工具调用功能验证

使用此命令，验证 vLLM 服务端是否正确启用了自动工具调用能力，这是 OpenClaw 调用本地模型执行复杂操作的关键：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VLLM_API_KEY" \
  -d '{
    "model": "Qwen3-8B",
    "messages": [
      {"role": "user", "content": "北京现在多少度？请调用工具"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "获取天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {"type": "string"}
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto",
    "max_tokens": 128
  }'

8. 故障诊断与问题排查

遇到问题时，可参考下表进行快速定位和修复：

现象

原因判断

处理动作

日志提示 strict/store ignored 并伴随 400 错误

日志中的 ignored 信息为次要提示。核心原因是请求格式（含工具调用）与当前 vLLM 服务能力不匹配。

在 vLLM 启动命令中补全 `--enable-auto-tool-choice` 与 `--tool-call-parser hermes` 参数，并仔细检查 API 返回的错误信息详情。

普通聊天请求成功，但工具调用请求失败

vLLM 服务未启用自动工具调用功能，或当前加载的对话模板不支持工具调用结构。

首要检查 vLLM 启动参数中关于工具调用的配置项，并确认所使用的聊天模板适配工具调用格式。

收到 context length exceeded 或 max_tokens 非法等错误

OpenClaw 中配置的上下文窗口长度超过了模型的实际处理能力。

在 OpenClaw 配置中将 `contextWindow` 修正为模型真实支持值，并检查是否在对话中累积了过长的历史消息。

请求返回 model not found 错误

HTTP 请求或 OpenClaw 配置中指定的模型名称，与 vLLM 服务实际注册的名称不匹配。

统一所有配置和请求中的模型标识，确保与 `--served-model-name` 设定的名称（如 `sinollm`）保持一致。

9. 生产环境运维建议

为确保服务长期稳定运行，建议遵循以下运维实践：

• 将包含全部关键参数（尤其是工具调用相关参数）的 vLLM 启动命令，写入 systemd 或 supervisor 等进程管理工具的配置文件中，确保服务重启后参数不丢失。

• 在 OpenClaw 的 JSON 配置文件中，对所有敏感信息（如 API Key、clientSecret、gateway token）使用环境变量进行引用替代，杜绝明文硬编码，提升配置安全性。

• 当本地模型开始承担生产流量后，建议编写独立的健康检查脚本（基于 curl 命令），以便在出现故障时，能快速区分问题是源于 OpenClaw 配置错误还是 vLLM 服务本身异常。

10. 技术依据与参考

本文档提供的解决方案基于以下官方文档与实践经验：

• 依据 OpenClaw 官方集成指南，通过 `openai-completions` 类型的 provider 接入本地 vLLM 的 OpenAI 兼容服务。

• 遵循 vLLM 官方文档说明，启用自动工具调用功能需明确配置 `--enable-auto-tool-choice` 参数，并配合相应的 `--tool-call-parser`。

• 根据 Qwen 模型官方推荐，Qwen3 系列建议采用 Hermes 风格的工具调用解析方式，vLLM 也为此提供了 `--tool-call-parser hermes` 的标准支持。

— 完 —