跳转到内容
OpenClaw Docs

vLLM

vLLM 可以通过 OpenAI 兼容的 HTTP API 提供开源（及一些自定义）模型。OpenClaw 使用 OpenAIAPIOpenClawopenai-completionsAPI API 连接到 vLLM。

当您选择使用 OpenClawVLLM_API_KEY（如果您的服务器不强制验证身份，任何值均可）时，OpenClaw 还可以 自动发现 vLLM 中的可用模型。当您还配置了自定义 vLLM 基础 URL 时，请在 agents.defaults.models 中使用 vllm/* 以保持发现机制的动态性。

OpenClaw 将 OpenClawvllmOpenAI 视为支持流式使用计数的本地 OpenAI 兼容提供商，因此状态/上下文令牌计数可以从 stream_options.include_usage 响应中更新。

属性值
提供商 IDvllm
APIopenai-completionsOpenAI (OpenAI 兼容)
身份验证VLLM_API_KEY 环境变量
默认基础 URLhttp://127.0.0.1:8000/v1

入门指南

Section titled “入门指南”

  1. OpenAI使用 OpenAI 兼容服务器启动 vLLM

    您的基础 URL 应公开 /v1 端点（例如 /v1/models、/v1/chat/completions）。vLLM 通常运行在：

    http://127.0.0.1:8000/v1

  2. API设置 API 密钥环境变量

    如果您的服务器不强制验证身份，任何值均可：

    Terminal window
    export VLLM_API_KEY="vllm-local"

  3. 选择模型

    替换为您的 vLLM 模型 ID 之一：

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

  4. 验证模型是否可用

    Terminal window
    openclaw models list --provider vllm

模型发现（隐式提供商）

Section titled “模型发现（隐式提供商）”

当设置了 VLLM_API_KEY（或存在身份验证配置文件）并且您没有定义 models.providers.vllm 时，OpenClaw 将查询：

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

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

显式配置（手动模型）

Section titled “显式配置（手动模型）”

在以下情况下使用显式配置：

  • vLLM 运行在不同的主机或端口上
  • 您想要固定 contextWindow 或 maxTokens 值
  • 您的服务器需要真实的 API 密钥（或者您想要控制请求头）
  • 您连接到受信任的环回、LAN 或 Tailscale vLLM 端点
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300, // Optional: extend connect/header/body/request timeout for slow local models
        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,
          },
        ],
      },
    },
  },
}

要保持此提供商的动态而无需手动列出每个模型，请将提供商通配符添加到可见模型目录：

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

高级配置

Section titled “高级配置”
Proxy-style behavior

vLLM 被视为代理风格的 OpenAI 兼容 /v1 后端，而非原生 OpenAI 端点。这意味着：

BehaviorApplied?
原生 OpenAI 请求塑形否
service_tier未发送
响应 store未发送
提示缓存提示未发送
OpenAI 推理兼容负载塑形未应用
隐藏的 OpenClaw 归属标头未在自定义基础 URL 上注入
QwenQwen 思维控制

对于通过 vLLM 提供的 Qwen 模型，当服务器期望 Qwen 聊天模板 kwargs 时，请在配置的提供商模型行上设置 compat.thinkingFormat: "qwen-chat-template"Qwen。以这种方式配置的模型会暴露一个二进制 /think 配置文件（off，onQwenOpenAI），因为 Qwen 模板思维是一个开/关请求标志，而不是 OpenAI 风格的努力阶梯。

{
  models: {
    providers: {
      vllm: {
        models: [
          {
            id: "Qwen/Qwen3-8B",
            name: "Qwen3 8B",
            reasoning: true,
            compat: { thinkingFormat: "qwen-chat-template" },
          },
        ],
      },
    },
  },
}
```OpenClaw


OpenClaw 将 `/think off` 映射为：


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

非 off 思维级别发送 enable_thinking: true。如果您的端点 期望 DashScope 风格的顶级标志，请改用 compat.thinkingFormat: "qwen" 在请求根目录发送 enable_thinking。

<Accordion title=“Nemotron 3 思维控制”OpenClaw> vLLM/Nemotron 3 可以使用聊天模板 kwargs 来控制推理是作为隐藏推理返回还是作为可见的答案文本返回。当 OpenClaw 会话 在思维关闭的情况下使用 vllm/nemotron-3-* 时，捆绑的 vLLM 插件会发送：

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


要自定义这些值，请在模型参数下设置 `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,
            },
          },
        },
      },
    },
  },
}
```
QwenQwen 工具调用显示为文本

首先请确保启动 vLLM 时使用了适合该模型工具调用解析器和聊天模板。 例如，vLLM 文档中针对 Qwen2.5 模型记录了 hermes，针对 Qwen3-Coder 模型记录了 qwen3_xml。

症状：

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

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

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

将 Qwen-Qwen2.5-Coder-32B-Instruct 替换为以下命令返回的确切 ID：

Terminal window
openclaw models list --provider vllm
```CLI


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


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

这是一个可选的兼容性变通方案。它会导致每一次带工具的模型轮次都要求必须进行工具调用， 因此请仅对接受该行为的专用本地模型条目使用它。不要将其作为所有 vLLM 模型的全局默认值， 也不要使用盲目地将任意助手文本转换为可执行工具调用的代理。

自定义基础 URL

如果您的 vLLM 服务器运行在非默认主机或端口上，请在显式提供商配置中设置 baseUrl：

{
  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,
          },
        ],
      },
    },
  },
}

故障排除

Section titled “故障排除”
首次响应缓慢或远程服务器超时

对于大型本地模型、远程 LAN 主机或 tailnet 链接，请设置一个 提供商范围的请求超时：

{
  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 请求，包括 连接建立、响应头、主体流传输以及整体 guarded-fetch 中止。在增加 agents.defaults.timeoutSeconds 之前请优先使用此设置， 因为 agents.defaults.timeoutSeconds 控制的是整个代理的运行。

Server not reachable

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

Terminal window
curl http://127.0.0.1:8000/v1/models

如果看到连接错误，请验证主机、端口，以及 vLLM 是否以 OpenAI 兼容的服务器模式启动。 对于显式环回、LAN 或 Tailscale 端点，OpenClaw 信任 为受保护的模型请求精确配置的 models.providers.vllm.baseUrl 源。如果没有显式 选择加入，元数据/链路本地源仍将被阻止。仅当 vLLM 请求必须到达另一个私有源时，才设置 models.providers.vllm.request.allowPrivateNetwork: true，并将其设置为 false 以退出精确源信任。

Auth errors on requests

如果请求因身份验证错误而失败，请设置与服务器配置匹配的真实 VLLM_API_KEY，或在 models.providers.vllm 下显式配置提供商。

No models discovered

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

Tools render as raw text

如果 Qwen 模型打印 JSON/XML 工具语法而不是执行技能， 请检查上方高级配置中的 Qwen 指南。通常的修复方法是：

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

相关

Section titled “相关”
模型选择

选择提供商、模型引用和故障转移行为。

OpenAI

原生 OpenAI 提供商和 OpenAI 兼容路由行为。

OAuth 和 auth

身份验证详细信息和凭据重用规则。

故障排除

常见问题及其解决方法。