vLLM

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

OpenClaw 也可以从 vLLM 自动发现 可用模型，当你选择使用 VLLM_API_KEY 时（如果你的服务器不强制认证，任何值都可以）。当你还配置了自定义 vLLM 基础 URL 时，请在 agents.defaults.models 中使用 vllm/* 以保持发现动态更新。

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

属性	值
提供商 ID	`vllm`
API	`openai-completions`OpenAI（OpenAI 兼容）
身份验证	`VLLM_API_KEY` 环境变量
默认基础 URL	`http://127.0.0.1:8000/v1`

入门指南

OpenAI启动兼容 OpenAI 的 vLLM 服务器
您的基础 URL 应公开 /v1 端点（例如 /v1/models、/v1/chat/completions）。vLLM 通常运行在：
```
http://127.0.0.1:8000/v1
```
设置 API 密钥环境变量
如果您的服务器不强制进行身份验证，则可以使用任意值：
Terminal window
```
export VLLM_API_KEY="vllm-local"
```

选择模型

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

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

验证模型是否可用
Terminal window
```
openclaw models list --provider vllm
```

模型发现（隐式提供商）

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

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

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

显式配置（手动模型）

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

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/*": {},
      },
    },
  },
}

高级配置

Proxy-style behavior

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

行为	是否应用？
原生 OpenAI 请求塑形	否
`service_tier`	未发送
响应 `store`	未发送
提示缓存提示	未发送
OpenAI 推理兼容负载塑形	未应用
隐藏的 OpenClaw 归属标头	不会注入到自定义基础 URL

QwenQwen 思维控制

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

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

非 off 思维级别会发送 enable_thinking: true。如果您的端点改为期望 DashScope 风格的顶级标志，请使用 params.qwenThinkingFormat: "top-level" 在请求根级别发送 enable_thinking。也接受蛇形命名法（snake-case）的 params.qwen_thinking_format。

Nemotron 3 思维控制

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

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

要自定义这些值，请在模型参数下设置 chat_template_kwargs。如果您还设置了 params.extra_body.chat_template_kwargs，该值将具有最终优先权，因为 extra_body 是最后一个请求体覆盖项。

{
  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：

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

故障排除

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

对于大型本地模型、远程 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 请求，包括连接设置、响应头、主体流传输和总受保护提取中止。在增加 agents.defaults.timeoutSeconds 之前，请优先使用此项，后者控制整个代理运行。

服务器无法访问

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

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 以退出确切的源信任。

请求上的身份验证错误

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

未发现模型

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

工具呈现为原始文本

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

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