vLLM

vLLM 通过 OpenAI 兼容 的 HTTP API 提供开源（以及一些自定义）模型。OpenClaw 使用 openai-completions API 进行连接，并且当你选择使用 VLLM_API_KEY 启用时，可以自动发现模型。

属性	值
Provider ID	`vllm`
API	`openai-completions`（OpenAI 兼容）
Auth	`VLLM_API_KEY` 环境变量
默认基础 URL	`http://127.0.0.1:8000/v1`
流式传输用量	支持（`stream_options.include_usage`）

入门

使用 OpenAI 兼容服务器启动 vLLM

你的基础 URL 必须暴露 /v1 端点（/v1/models、/v1/chat/completions）。vLLM 通常运行在：

http://127.0.0.1:8000/v1

设置 API 密钥环境变量

如果你的服务器不强制认证，任何非空值都可以：

export VLLM_API_KEY="vllm-local"

选择一个模型

替换为你 vLLM 中的某个模型 ID：

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

验证模型是否可用

openclaw models list --provider vllm

对于非交互式设置（CI、脚本），直接传入基础 URL、密钥和模型：

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice vllm \
  --custom-base-url "http://127.0.0.1:8000/v1" \
  --custom-api-key "vllm-local" \
  --custom-model-id "your-model-id"

模型发现（隐式提供方）

当设置了 VLLM_API_KEY（或存在认证配置文件）且未定义 models.providers.vllm 时，OpenClaw 会查询 GET http://127.0.0.1:8000/v1/models，并将返回的 ID 转换为模型条目。

如果你显式设置了 models.providers.vllm，OpenClaw 只会使用你声明的模型。将 "vllm/*": {} 添加到 agents.defaults.models，以让 OpenClaw 也查询该已配置提供方的 /models 端点，并包含所有已公布的 vLLM 模型。

显式配置

当 vLLM 运行在不同的主机或端口上、你想固定 contextWindow/maxTokens、你的服务器需要真实的 API 密钥，或者你连接到受信任的回环、局域网或 Tailscale 端点时，请显式配置：

{
  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: "本地 vLLM 模型",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

为了让提供方保持动态而无需列出每个模型，请在可见模型目录中添加一个通配符：

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

高级配置

代理式行为

vLLM 被视为一种代理式、兼容 OpenAI 的 /v1 后端，而不是原生 OpenAI 端点：

行为	是否应用？
原生 OpenAI 请求整形	否
`service_tier`	不发送
Responses `store`	不发送
Prompt-cache 提示	不发送
OpenAI reasoning-compat 载荷整形	不应用
隐藏的 OpenClaw 归属请求头	对自定义 base URL 不注入

Qwen 思考控制

对于 Qwen 模型，当服务器期望 Qwen chat-template kwargs 时，请在模型行上设置 compat.thinkingFormat: "qwen-chat-template"。这些模型提供一个二元 /think 配置文件（off、on），因为 Qwen chat-template 的 thinking 是一个开关，而不是 OpenAI 风格的 effort 级别。

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

OpenClaw 将 /think off 映射为：

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

非 off 的 thinking 级别会发送 enable_thinking: true。如果你的端点期望的是 DashScope 风格的顶层标志，请使用 compat.thinkingFormat: "qwen"，以便在请求根部发送 enable_thinking。

Nemotron 3 思考控制

对于启用 thinking 的 vllm/nemotron-3-* 模型，当 thinking 关闭时，内置插件会发送：

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

Qwen 工具调用显示为文本

首先确认 vLLM 是否使用了与模型匹配的正确 tool-call 解析器和 chat template 启动。vLLM 文档中，Qwen2.5 模型使用 hermes，Qwen3-Coder 模型使用 qwen3_xml。症状：skills/tools 从不执行，assistant 输出原始 JSON/XML，例如 {"name":"read","arguments":...}，或者当 OpenClaw 发送 tool_choice: "auto" 时，vLLM 返回空的 tool_calls 数组。某些 Qwen/vLLM 组合只有在请求使用 tool_choice: "required" 时才会返回结构化 tool call。可以通过 params.extra_body 为单个模型强制设置：

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

将模型 id 替换为 openclaw models list --provider vllm 中的精确 id，或者通过 CLI 应用同样的覆盖：

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

这是一个可选的变通方案：它会强制每一轮带工具的交互都发起一次 tool call，所以只应在专用模型条目中使用，并且你能接受这种行为。不要将它设为所有 vLLM 模型的全局默认，也不要把它与会将任意 assistant 文本转换为可执行 tool call 的代理一起使用。

自定义 base 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: "远程 vLLM 模型",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

故障排查

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

对于大型本地模型、远程局域网主机或 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 请求：连接建立、响应头、正文流式传输，以及受保护的 fetch 总中止时间。它还会将该提供方的 LLM 空闲/流式看门狗上限提高到隐式约 120 秒默认值之上。优先使用此项，而不是增加 agents.defaults.timeoutSeconds，后者控制的是整个 agent 运行过程。

服务器不可达

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

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

如果你看到连接错误，请验证主机、端口，以及 vLLM 是否以 OpenAI 兼容的服务器模式启动。OpenClaw 会信任在 loopback、局域网和 Tailscale 端点上，针对受保护模型请求所配置的精确 models.providers.vllm.baseUrl 源。元数据/链路本地来源在未显式选择加入时仍会被阻止。仅当 vLLM 请求必须到达另一个私有源时，才将 models.providers.vllm.request.allowPrivateNetwork: true 设为允许；若要退出对精确来源的信任，则设为 false。

请求出现认证错误

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

如果你的 vLLM 服务器不强制认证，那么 VLLM_API_KEY 的任何非空值都可作为 OpenClaw 的可选启用信号。

未发现模型

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

工具渲染为原始文本

如果某个 Qwen 模型输出 JSON/XML 工具语法而不是执行 skill：

使用与该模型匹配的正确 parser/template 启动 vLLM。
通过 openclaw models list --provider vllm 确认精确的模型 id。
只有在 tool_choice: "auto" 仍然返回空的或仅文本的 tool call 时，才为该模型单独添加 params.extra_body.tool_choice: "required" 覆盖。

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

模型选择

选择提供方、模型引用和故障切换行为。

OpenAI

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

OAuth 和认证

认证细节和凭据复用规则。

故障排查

常见问题及其解决方法。

概览

概念与配置

提供商

入门

模型发现（隐式提供方）

显式配置

高级配置

故障排查

相关内容

模型选择

OpenAI

OAuth 和认证

故障排查

​入门

​模型发现（隐式提供方）

​显式配置

​高级配置

​故障排查

​相关内容

模型选择

OpenAI

OAuth 和认证

故障排查

入门

模型发现（隐式提供方）

显式配置

高级配置

故障排查

相关内容