跳转至

vLLM

vLLM 通过 OpenAI 兼容 HTTP API 提供开源(以及部分自定义)模型。OpenClaw 使用 openai-completions API 连接,并在你通过 VLLM_API_KEY 选择加入时,可以 自动发现 模型。

属性 值
提供商 ID vllm
API openai-completions(OpenAI 兼容)
认证 VLLM_API_KEY 环境变量
默认基础 URL http://127.0.0.1:8000/v1
流式用量 支持(stream_options.include_usage)

快速开始

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

你的基础 URL 必须暴露 /v1 端点(/v1/models、/v1/chat/completions)。使用你要提供的模型启动服务器:

vllm serve <model-id>

有关标志,请参阅 vLLM 在线服务文档。vLLM 通常运行在:

http://127.0.0.1:8000/v1

2. 设置 API 密钥环境变量

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

export VLLM_API_KEY="vllm-local"

3. 选择模型

替换为你的某个 vLLM 模型 ID:

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

4. 验证模型是否可用

openclaw models list --provider vllm

Tip

对于非交互式设置(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 转换为模型条目。

Note

如果你显式设置了 models.providers.vllm,OpenClaw 仅使用你声明的模型。将 "vllm/*": {} 添加到 agents.defaults.models,可让 OpenClaw 同时查询该已配置提供商的 /models 端点,并包含所有已通告的 vLLM 模型。

显式配置

当 vLLM 运行在不同的主机或端口、你想固定 contextWindow/maxTokens、你的服务器需要真实 API 密钥,或你连接到受信任的 loopback、LAN 或 Tailscale 端点时,请显式配置:

{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        timeoutSeconds: 300, // Optional: extend 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/*": {},
      },
    },
  },
}

高级配置

代理式行为

vLLM 被视为代理式 OpenAI 兼容 /v1 后端,而不是原生 OpenAI 端点:

行为 是否应用?
原生 OpenAI 请求整形 否
service_tier 不发送
Responses store 不发送
Prompt-cache 提示 不发送
OpenAI 推理兼容负载整形 不应用
隐藏的 OpenClaw 归属头 在自定义基础 URL 上不注入
Qwen 思考控制

对于 Qwen 模型,当服务器期望 Qwen chat-template kwargs 时,在模型行上设置 compat.thinkingFormat: "qwen-chat-template"。这些模型暴露一个二元 /think 配置(off、on),因为 Qwen chat-template 思考是一个开/关标志,而不是 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 的思考级别会发送 enable_thinking: true。如果你的端点期望的是 DashScope 风格的顶层标志,请使用 compat.thinkingFormat: "qwen",在请求根节点发送 enable_thinking。

如果你提供的模板接受 effort 级别,请在 compat.supportedReasoningEfforts 中声明它们,例如 ["low", "medium", "xhigh"]。然后 OpenClaw 会暴露这些 /think 选项以及 off。共享推理解析器会将所选级别映射到声明的传输值。对于 qwen-chat-template,该值位于 chat_template_kwargs.reasoning_effort;对于 qwen,它位于根 reasoning_effort。

提供商原生值区分大小写。使用 compat.reasoningEffortMap(例如 { low: "LOW", high: "HIGH" })将逻辑选项映射到声明的原生列表(例如 ["LOW", "HIGH"])。未映射的原生标签不会作为 effort 选项通告。缺失、为空或不可用的列表会保持二元思考,compat.supportsReasoningEffort: false 也是如此。

插件会在会话设置之前将这些映射准备为模型能力,因此当原生线路标签不同时,诸如 xhigh 和 max 等高级选项也能在会话级钳制中保留下来。

默认值仍为 `off`,包括在升级已配置的现有模型之后。显式启用的级别现在会发送其声明的 effort,而不是静默使用模板默认值。普通二进制 Qwen 模型保持其现有请求形状。每个模型的 `params.extra_body` 仍然是最终请求体覆盖。
DeepSeek V4 思考控制

对于包含 deepseek-v4 或 deepseek_v4 的 vLLM 模型 ID,请配置 reasoning: true。OpenClaw 会通过 chat_template_kwargs.reasoning_effort 发送所选的 effort,并将 thinking 和 enable_thinking 都设置为 true。声明的 effort 值和 reasoningEffortMap 使用与其他 OpenAI 兼容模型相同的共享解析器。

/think off 会将两个模板标志都发送为 false,因为当任一标志为 true 时,vLLM 会启用 DeepSeek 思考。托管 DeepSeek 的根 thinking 对象和根 reasoning_effort 会被移除。现有的显式模板 kwargs 以及最终的 params.extra_body 覆盖仍然具有权威性。显式的 Qwen 思考格式优先于模型名称匹配。

这种请求整形不会为标记为 reasoning: false 的目录行启用推理,也不会更改发现启发式规则。如果自动发现未识别其推理能力,请显式配置该模型。

Nemotron 3 思考控制

对于思考关闭的 vllm/nemotron-3-* 模型,内置插件会发送:

{
  "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 已使用适合该模型的正确工具调用解析器和聊天模板启动。vLLM 文档将 hermes 用于 Qwen2.5 模型,将 qwen3_xml 用于 Qwen3-Coder 模型。

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

某些 Qwen/vLLM 组合仅在请求使用 tool_choice: "required" 时返回结构化工具调用。使用 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

这是一种可选的变通方案:它会强制每个带有工具的回合都发起工具调用,因此仅用于可接受此行为的专用模型条目。不要将其设置为所有 vLLM 模型的全局默认值,也不要将其与将任意助手文本转换为可执行工具调用的代理配对使用。

自定义 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: "Remote vLLM Model",
            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 请求:连接建立、响应头、正文流式传输以及总 guarded-fetch 中止。它还会将该提供商的 LLM 空闲/流式看门狗上限提高到隐式约 120 秒默认值之上。建议优先使用此设置,而不是增加 agents.defaults.timeoutSeconds,后者控制整个 agent 运行。

服务器无法访问

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

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

如果你看到连接错误,请验证主机、端口,以及 vLLM 是否以 OpenAI 兼容服务器模式启动。OpenClaw 对于回环、局域网和 Tailscale 端点上的受保护模型请求,信任精确配置的 models.providers.vllm.baseUrl 源。元数据、链路本地和本地用途 NAT64(64:ff9b:1::/48)源在没有显式选择加入的情况下仍会被阻止。仅当 vLLM 请求必须到达另一个私有源时,才设置 models.providers.vllm.request.allowPrivateNetwork: true,或设置为 false 以退出精确源信任。

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

Tip

如果你的 vLLM 服务器不强制身份验证,则 VLLM_API_KEY 的任何非空值都可以作为 OpenClaw 的启用信号。

未发现模型

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

工具渲染为原始文本

如果 Qwen 模型输出 JSON/XML 工具语法而不是执行技能:

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

Warning

更多帮助:故障排除 和 常见问题。

模型选择

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

OpenAI

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

OAuth 和身份验证

身份验证详情和凭据重用规则。

故障排除

常见问题及解决方法。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw