古法编程

Appearance

vLLM 本地推理服务可通过 OpenAI 兼容 API 接入 OpenClaw，支持自动发现模型（设置 VLLM_API_KEY 后）或手动配置 provider。连接不上或模型未发现时检查 base URL 和 API key；工具调用输出为原始 JSON/XML 时需为 Qwen 模型添加 extra_body 强制 tool_choice。慢响应可调大 provider 的 timeoutSeconds。

OpenClaw vLLM 配置：模型发现、超时与工具调用 ​

vLLM 可通过 OpenAI 兼容 HTTP API 部署开源（及部分自定义）模型。OpenClaw 使用 openai-completions API 连接 vLLM。

设置 VLLM_API_KEY 后（如果你的服务器不要求鉴权，随便填个值即可），OpenClaw 还能自动发现 vLLM 上的可用模型——无需手动配置 models.providers.vllm。使用 vllm/* 作为 agents.defaults.models 中的通配符，可以在设置自定义 vLLM base URL 时保持动态发现。

OpenClaw 将 vllm 视为本地 OpenAI 兼容的 provider，支持流式用量统计，因此状态/上下文 token 计数可以随 stream_options.include_usage 响应更新。

属性值
Provider IDvllm
APIopenai-completions (OpenAI 兼容)
鉴权VLLM_API_KEY 环境变量
默认 base URLhttp://127.0.0.1:8000/v1

快速上手 ​

  1. 启动带 OpenAI 兼容端点的 vLLM 服务器
    base URL 需要暴露 /v1 系列接口（如 /v1/models、/v1/chat/completions）。vLLM 默认运行在：

    http://127.0.0.1:8000/v1

  2. 设置 API Key
    如果服务器未启用鉴权，任何非空值都可作为 opt-in 信号：

    bash
    export VLLM_API_KEY="vllm-local"

  3. 选择模型
    替换为你实际的 vLLM 模型 ID：

    json5
    {
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}

  4. 验证模型可用

    bash
    openclaw models list --provider vllm

模型自动发现（隐式 Provider） ​

当 VLLM_API_KEY 已设置（或存在 auth profile），且你没有显式定义 models.providers.vllm 时，OpenClaw 自动查询：

GET http://127.0.0.1:8000/v1/models

并将返回的模型 ID 转换为可用的模型条目。

::: note 如果你显式配置了 models.providers.vllm，OpenClaw 默认使用你声明的模型。需要在 agents.defaults.models 中添加 "vllm/*": {} 才能让 OpenClaw 查询该配置 provider 的 /models 端点并包含所有 vLLM 模型。 :::

手动配置（显式指定模型） ​

以下情况建议使用手动配置：

  • vLLM 运行在非默认的主机或端口
  • 需要固定 contextWindow / maxTokens 值
  • 服务器需要真实 API Key，或需要控制请求头
  • 连接到受信任的回环、局域网或 Tailscale vLLM 端点
json5
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300, // 可选：对慢速本地模型延长连接/响应/请求超时
        models: [
          {
            id: "your-model-id",
            name: "Local vLLM Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

如果要保持动态而不手动列出每个模型，在可见模型目录中添加 provider 通配符：

json5
{
  agents: {
    defaults: {
      models: {
        "vllm/*": {},
      },
    },
  },
}

高级配置 ​

代理式行为 ​

vLLM 被视为代理式 OpenAI 兼容 /v1 后端，而不是原生 OpenAI 端点。这意味着：

行为应用？
原生 OpenAI 请求整形否
service_tier不发送
Responses store不发送
提示缓存提示不发送
OpenAI 推理兼容 payload 整形不应用
隐藏的 OpenClaw 归属头不在自定义 base URL 上注入

Qwen 思考控制 ​

对于通过 vLLM 部署的 Qwen 模型，当服务器期望 Qwen chat-template kwargs 时，在模型条目上设置 params.qwenThinkingFormat: "chat-template"。OpenClaw 将 /think off 映射为：

json
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}

非 off 的思考级别会发送 enable_thinking: true。如果你的端点期望 DashScope 风格的顶级标志，改用 params.qwenThinkingFormat: "top-level" 来在请求根级发送 enable_thinking。也接受下划线格式 params.qwen_thinking_format。

Nemotron 3 思考控制 ​

vLLM/Nemotron 3 可以使用 chat-template kwargs 来控制推理以隐藏推理文本还是可见答案文本返回。当 OpenClaw 会话使用 vllm/nemotron-3-* 且思考关闭时，内置 vLLM 插件发送：

json
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "force_nonempty_content": true
  }
}

要自定义这些值，在模型 params 下设置 chat_template_kwargs。如果同时也设置了 params.extra_body.chat_template_kwargs，该值拥有最终优先级，因为 extra_body 是最后的请求体覆盖。

json5
{
  agents: {
    defaults: {
      models: {
        "vllm/nemotron-3-super": {
          params: {
            chat_template_kwargs: {
              enable_thinking: false,
              force_nonempty_content: true,
            },
          },
        },
      },
    },
  }
}

Qwen 工具调用显示为文本 ​

首先确保 vLLM 以正确的工具调用解析器和聊天模板启动。例如，vLLM 文档中 Qwen2.5 模型使用 hermes，Qwen3-Coder 模型使用 qwen3_xml。

症状：

  • 技能或工具从未运行
  • 助手打印原始 JSON/XML，如 {"name":"read","arguments":...}
  • 当 OpenClaw 发送 tool_choice: "auto" 时，vLLM 返回空的 tool_calls 数组

某些 Qwen/vLLM 组合只有在请求使用 tool_choice: "required" 时才返回结构化工具调用。对于这些模型条目，使用 params.extra_body 强制 OpenAI 兼容请求字段：

json5
{
  agents: {
    defaults: {
      models: {
        "vllm/Qwen-Qwen2.5-Coder-32B-Instruct": {
          params: {
            extra_body: {
              tool_choice: "required",
            },
          },
        },
      },
    },
  }
}

将 Qwen-Qwen2.5-Coder-32B-Instruct 替换为 openclaw models list --provider vllm 返回的确切 ID。

也可以从 CLI 应用相同的覆盖：

bash
openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

这是一个 opt-in 兼容性解决方法。它使每次带工具的模型轮次都需要工具调用，因此仅用于专用的本地模型条目，且能接受该行为。不要将其作为所有 vLLM 模型的全局默认值，也不要使用盲目将任意助手文本转换为可执行工具调用的代理。

自定义 base URL ​

如果 vLLM 服务器运行在非默认主机或端口，在显式 provider 配置中设置 baseUrl：

json5
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-custom-model",
            name: "Remote vLLM Model",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  }
}

故障排查 ​

首次响应慢或远程服务器超时 ​

对于大型本地模型、远程 LAN 主机或 tailnet 链接，设置 provider 级别的请求超时：

json5
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}

timeoutSeconds 仅适用于 vLLM 模型的 HTTP 请求，包括连接建立、响应头、流式主体以及受防护的 fetch 中止。优先于增加 agents.defaults.timeoutSeconds，后者控制整个智能体运行。

服务器不可达 ​

检查 vLLM 服务器是否运行且可访问：

bash
curl http://127.0.0.1:8000/v1/models

如果看到连接错误，验证主机、端口以及 vLLM 是否以 OpenAI 兼容服务器模式启动。对于显式的回环、局域网或 Tailscale 端点，OpenClaw 信任已配置的 models.providers.vllm.baseUrl 源用于受防护的模型请求。元数据/链路本地源在没有显式 opt-in 的情况下保持阻止。只有当 vLLM 请求必须到达另一个私有源时，设置 models.providers.vllm.request.allowPrivateNetwork: true，设为 false 以退出精确源信任。

请求出现鉴权错误 ​

如果请求因为鉴权错误失败，设置与服务器配置一致的 VLLM_API_KEY，或在 models.providers.vllm 下显式配置 provider。

TIP

如果 vLLM 服务器不要求鉴权，任何非空值作为 VLLM_API_KEY 都可以作为 opt-in 信号。

没有发现模型 ​

自动发现需要设置 VLLM_API_KEY。如果你已经定义了 models.providers.vllm，OpenClaw 只使用你声明的模型，除非 agents.defaults.models 包含 "vllm/*": {}。

工具渲染为原始文本 ​

如果 Qwen 模型打印 JSON/XML 工具语法而不是执行技能，请查看上文“Qwen 工具调用显示为文本”部分。通常的修复方法：

  • 使用正确的解析器/模板启动 vLLM 模型
  • 确认确切的模型 ID：openclaw models list --provider vllm
  • 只有当 tool_choice: "auto" 仍然返回空或纯文本工具调用时，添加专用的逐模型 params.extra_body.tool_choice: "required" 覆盖

WARNING

更多帮助：故障排查 和 FAQ。

相关 ​

  • 模型选择 — 选择 provider、模型引用和故障转移行为。
  • OpenAI — 原生 OpenAI provider 和 OpenAI 兼容路由行为。
  • OAuth 和鉴权 — 鉴权详细信息和凭据重用规则。
  • 故障排查 — 常见问题及解决方法。

常见问题 ​

vLLM 模型自动发现不生效怎么办？ ​

确认已设置 VLLM_API_KEY 环境变量（任意非空值即可）。如果已显式配置 models.providers.vllm，OpenClaw 不会自动发现模型；需要在 agents.defaults.models 中添加 "vllm/*": {} 来启用发现。运行 openclaw models list --provider vllm 查看是否列出模型。

Qwen 模型工具调用输出为文本怎么解决？ ​

先确认 vLLM 启动了正确的工具调用解析器和聊天模板（Qwen2.5 用 hermes，Qwen3-Coder 用 qwen3_xml）。如果仍输出原始 JSON，可以为该模型添加 params.extra_body.tool_choice: "required"。使用 openclaw models list --provider vllm 获取准确模型 ID 后，用 openclaw config set 命令添加覆盖。

vLLM 第一次响应很慢怎么调整？ ​

在 models.providers.vllm 中设置 timeoutSeconds，例如 300 秒。这仅影响 vLLM 的 HTTP 请求超时，而不是整个智能体运行超时。对于局域网或 Tailscale 的远程服务器，同样适用此方法。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策