Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

vLLM 可以通过 OpenAI 兼容 的 HTTP API 提供开源（以及某些自定义）模型。OpenClaw 使用 openai-completions API 连接到 vLLM。 当你启用 VLLM_API_KEY（如果你的服务器不强制认证，任何值都可以）并且没有显式定义 models.providers.vllm 条目时，OpenClaw 还可以从 vLLM 自动发现 可用模型。 OpenClaw 将 vllm 视为一个支持流式使用量统计的本地 OpenAI 兼容提供方，因此状态/上下文 token 计数可以从 stream_options.include_usage 响应中更新。
属性值
Provider IDvllm
APIopenai-completions（OpenAI 兼容）
AuthVLLM_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 环境变量

如果你的服务器不强制认证，任何值都可以：
export VLLM_API_KEY="vllm-local"
3

选择一个模型

替换为你 vLLM 中的某个模型 ID：
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

验证模型是否可用

openclaw models list --provider vllm

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

当设置了 VLLM_API_KEY（或存在认证配置文件）并且你没有定义 models.providers.vllm 时，OpenClaw 会查询： 
GET http://127.0.0.1:8000/v1/models
并将返回的 ID 转换为模型条目。
如果你显式设置了 models.providers.vllm，则会跳过自动发现，你必须手动定义模型。

​
显式配置（手动模型）

在以下情况使用显式配置：
  • vLLM 运行在不同的主机或端口上
  • 你想固定 contextWindow 或 maxTokens 的值
  • 你的服务器需要真实的 API key（或你想控制请求头）
  • 你连接到受信任的 loopback、LAN 或 Tailscale vLLM 端点
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        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,
          },
        ],
      },
    },
  },
}

​
高级配置

vLLM 被视为一个代理式的 OpenAI 兼容 /v1 后端，而不是原生 OpenAI 端点。这意味着：
行为是否应用？
原生 OpenAI 请求整形否
service_tier不发送
Responses store不发送
提示缓存提示不发送
OpenAI reasoning 兼容有效载荷整形不应用
隐藏的 OpenClaw 归因请求头不会在自定义 base URL 上注入
对于通过 vLLM 提供的 Qwen 模型，当服务器期望 Qwen chat-template 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。 也支持蛇形写法 params.qwen_thinking_format。
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,
            },
          },
        },
      },
    },
  },
}
先确保 vLLM 使用了适合该模型的正确工具调用解析器和 chat template。例如，vLLM 文档中为 Qwen2.5 模型使用 hermes，为 Qwen3-Coder 模型使用 qwen3_xml。症状：
  • skills 或 tools 从不运行
  • 助手打印原始 JSON/XML，例如 {"name":"read","arguments":...}
  • 当 OpenClaw 发送 tool_choice: "auto" 时，vLLM 返回空的 tool_calls 数组
某些 Qwen/vLLM 组合只有在 请求使用 tool_choice: "required" 时才会返回结构化工具调用。对于这些模型条目，请用 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 应用同样的覆盖：
openclaw config set agents.defaults.models '{"vllm/Qwen-Qwen2.5-Coder-32B-Instruct":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
这是一个可选的兼容性解决方案。它会让使用工具的每一轮模型交互都要求工具调用，因此仅应在可接受该行为的专用本地模型条目中使用。不要将其作为所有 vLLM 模型的全局默认值，也不要使用会把任意助手文本盲目转换为可执行工具调用的代理。
如果你的 vLLM 服务器运行在非默认主机或端口上，请在显式提供方配置中设置 baseUrl：
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [
          {
            id: "my-custom-model",
            name: "远程 vLLM 模型",
            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",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}
timeoutSeconds 仅适用于 vLLM 模型的 HTTP 请求，包括 连接建立、响应头、正文流式传输，以及整个 guarded-fetch 中止。优先使用这个设置，然后再考虑增加 agents.defaults.timeoutSeconds，后者控制整个代理运行。
检查 vLLM 服务器是否正在运行并可访问：
curl http://127.0.0.1:8000/v1/models
如果你看到连接错误，请检查主机、端口，以及 vLLM 是否以 OpenAI 兼容服务器模式启动。 对于显式的 loopback、LAN 或 Tailscale 端点，也要设置 models.providers.vllm.request.allowPrivateNetwork: true；除非提供方 被显式信任，否则提供方请求默认会阻止私有网络 URL。
如果请求因认证错误失败，请设置一个与服务器配置匹配的真实 VLLM_API_KEY，或者在 models.providers.vllm 下显式配置提供方。
如果你的 vLLM 服务器不强制认证，那么 VLLM_API_KEY 的任何非空值都可作为 OpenClaw 的可选启用信号。
自动发现要求已设置 VLLM_API_KEY，并且没有显式的 models.providers.vllm 配置条目。如果你已经手动定义了该提供方，OpenClaw 会跳过发现并只使用你声明的模型。
如果某个 Qwen 模型打印的是 JSON/XML 工具语法而不是执行技能， 请检查上方高级配置中的 Qwen 指引。通常的修复方法是：
  • 使用该模型正确的解析器/template 启动 vLLM
  • 使用 openclaw models list --provider vllm 确认精确的模型 id
  • 仅当 tool_choice: "auto" 仍然返回空的或仅文本的 工具调用时，才为该模型添加专用的 params.extra_body.tool_choice: "required" 覆盖
更多帮助：故障排查 和 FAQ。

​
相关内容

模型选择

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

OpenAI

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

OAuth 和认证

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

故障排查

常见问题及其解决方法。