vLLM

vLLM은 기본 OpenAI 엔드포인트가 아니라 프록시 스타일의 OpenAI 호환 /v1 백엔드로 취급됩니다. 이는 다음을 의미합니다.

vLLM을 통해 제공되는 Qwen 모델의 경우 서버가 Qwen 채팅 템플릿 kwargs를 예상할 때 구성된 제공자 모델 행에 compat.thinkingFormat: "qwen-chat-template"을 설정하세요. 이렇게 구성된 모델은 Qwen 템플릿 thinking이 OpenAI 스타일 노력 단계가 아니라 켜기/끄기 요청 플래그이기 때문에 바이너리 /think 프로필(off, on)을 노출합니다.

{  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을 전송하세요.

vLLM/Nemotron 3는 추론이 숨겨진 추론으로 반환될지 표시되는 답변 텍스트로 반환될지 제어하기 위해 채팅 템플릿 kwargs를 사용할 수 있습니다. OpenClaw 세션이 thinking off 상태로 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가 마지막 요청 본문 override이므로 해당 값이 최종 우선순위를 갖습니다.

{  agents: {    defaults: {      models: {        "vllm/nemotron-3-super": {          params: {            chat_template_kwargs: {              enable_thinking: false,              force_nonempty_content: true,            },          },        },      },    },  },}

먼저 vLLM이 해당 모델에 맞는 올바른 도구 호출 파서와 채팅 템플릿으로 시작되었는지 확인하세요. 예를 들어 vLLM은 Qwen2.5 모델에는 hermes, Qwen3-Coder 모델에는 qwen3_xml을 문서화합니다.

증상:

• Skills 또는 도구가 실행되지 않음
• 어시스턴트가 {"name":"read","arguments":...} 같은 원시 JSON/XML을 출력함
• 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에서도 동일한 override를 적용할 수 있습니다.

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",        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는 연결 설정, 응답 헤더, 본문 스트리밍, 전체 guarded-fetch 중단을 포함하여 vLLM 모델 HTTP 요청에만 적용됩니다. 전체 에이전트 실행을 제어하는 agents.defaults.timeoutSeconds를 늘리기 전에 이를 우선 사용하세요.

vLLM 서버가 실행 중이고 접근 가능한지 확인하세요.

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

연결 오류가 표시되면 호스트, 포트, 그리고 vLLM이 OpenAI 호환 서버 모드로 시작되었는지 확인하세요. 명시적 loopback, LAN 또는 Tailscale 엔드포인트의 경우 OpenClaw는 보호된 모델 요청에 대해 정확히 구성된 models.providers.vllm.baseUrl 원본을 신뢰합니다. 메타데이터/link-local 원본은 명시적 옵트인 없이는 계속 차단됩니다. vLLM 요청이 다른 비공개 원본에 도달해야 하는 경우에만 models.providers.vllm.request.allowPrivateNetwork: true를 설정하고, 정확한 원본 신뢰를 옵트아웃하려면 이를 false로 설정하세요.

요청이 인증 오류로 실패하면 서버 구성과 일치하는 실제 VLLM_API_KEY를 설정하거나 models.providers.vllm 아래에서 제공자를 명시적으로 구성하세요.

자동 검색에는 VLLM_API_KEY 설정이 필요합니다. models.providers.vllm을 정의한 경우, agents.defaults.models에 "vllm/*": {}가 포함되어 있지 않으면 OpenClaw는 선언된 모델만 사용합니다.

Qwen 모델이 skill을 실행하는 대신 JSON/XML 도구 구문을 출력하는 경우 위의 고급 구성에서 Qwen 지침을 확인하세요. 일반적인 해결 방법은 다음과 같습니다.

• 해당 모델에 맞는 올바른 파서/템플릿으로 vLLM 시작
• openclaw models list --provider vllm으로 정확한 모델 ID 확인
• tool_choice: "auto"가 여전히 비어 있거나 텍스트 전용 도구 호출을 반환하는 경우에만 전용 모델별 params.extra_body.tool_choice: "required" override 추가