vLLM

vLLM 會被視為 proxy 樣式的 OpenAI 相容 /v1 後端，而不是原生 OpenAI 端點。這表示：

對於透過 vLLM 提供服務的 Qwen 模型，當伺服器預期 Qwen chat-template kwargs 時，請在模型項目上設定 params.qwenThinkingFormat: "chat-template"。OpenClaw 會將 /think off 對應為：

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

非 off 的 thinking 等級會傳送 enable_thinking: true。如果你的端點改為預期 DashScope 樣式的頂層旗標，請使用 params.qwenThinkingFormat: "top-level"，在請求根層級傳送 enable_thinking。也接受 snake-case 的 params.qwen_thinking_format。

vLLM/Nemotron 3 可以使用 chat-template kwargs 控制 reasoning 是作為隱藏 reasoning 還是可見回答文字回傳。當 OpenClaw 工作階段在關閉 thinking 的情況下使用 vllm/nemotron-3-* 時，內建的 vLLM Plugin 會傳送：

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

若要自訂這些值，請在模型 params 下設定 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 或工具從未執行
• assistant 列印原始 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 模型的全域預設，也不要使用會盲目將任意 assistant 文字轉換為可執行工具呼叫的 proxy。

如果你的 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: "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",
        request: { allowPrivateNetwork: true },
        timeoutSeconds: 300,
        models: [{ id: "your-model-id", name: "Local vLLM Model" }],
      },
    },
  },
}

timeoutSeconds 只套用於 vLLM 模型 HTTP 請求，包括連線建立、回應標頭、主體串流，以及整體 guarded-fetch 中止。請優先使用此設定，再考慮提高 agents.defaults.timeoutSeconds，後者控制整個 agent 執行。

檢查 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_API_KEY，且沒有明確的 models.providers.vllm 設定項目。如果你已手動定義提供者，OpenClaw 會略過探索，只使用你宣告的模型。

如果 Qwen 模型列印 JSON/XML 工具語法而不是執行 skill，請查看上方進階設定中的 Qwen 指引。通常的修正方式是：

• 使用該模型正確的剖析器/template 啟動 vLLM
• 使用 openclaw models list --provider vllm 確認確切模型 id
• 只有在 tool_choice: "auto" 仍回傳空白或僅文字的工具呼叫時，才加入專用的逐模型 params.extra_body.tool_choice: "required" 覆寫