메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

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

vLLM은 OpenAI 호환 HTTP API를 통해 오픈 소스(및 일부 사용자 지정) 모델을 제공할 수 있습니다. OpenClaw는 openai-completions API를 사용하여 vLLM에 연결합니다. OpenClaw는 VLLM_API_KEY로 옵트인하면 vLLM에서 사용 가능한 모델을 자동 검색할 수도 있습니다(서버가 인증을 강제하지 않는 경우 아무 값이나 작동합니다). 사용자 지정 vLLM 기본 URL도 구성하는 경우 검색을 동적으로 유지하려면 agents.defaults.models에서 vllm/*를 사용하세요. OpenClaw는 vllm을 스트리밍 사용량 계산을 지원하는 로컬 OpenAI 호환 제공자로 취급하므로, 상태/컨텍스트 토큰 수가 stream_options.include_usage 응답에서 업데이트될 수 있습니다.
속성값
제공자 IDvllm
APIopenai-completions (OpenAI 호환)
인증VLLM_API_KEY 환경 변수
기본 기본 URLhttp://127.0.0.1:8000/v1

​
시작하기

1

Start vLLM with an OpenAI-compatible server

기본 URL은 /v1 엔드포인트(예: /v1/models, /v1/chat/completions)를 노출해야 합니다. vLLM은 일반적으로 다음에서 실행됩니다.
http://127.0.0.1:8000/v1
2

Set the API key environment variable

서버가 인증을 강제하지 않는 경우 아무 값이나 작동합니다.
export VLLM_API_KEY="vllm-local"
3

Select a model

vLLM 모델 ID 중 하나로 바꾸세요.
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

Verify the model is available

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을 명시적으로 설정하면 OpenClaw는 기본적으로 선언된 모델을 사용합니다. OpenClaw가 구성된 제공자의 /models 엔드포인트를 쿼리하고 광고된 모든 vLLM 모델을 포함하도록 하려면 agents.defaults.models에 "vllm/*": {}를 추가하세요.

​
명시적 구성(수동 모델)

다음과 같은 경우 명시적 구성을 사용하세요.
  • vLLM이 다른 호스트 또는 포트에서 실행되는 경우
  • contextWindow 또는 maxTokens 값을 고정하려는 경우
  • 서버에 실제 API 키가 필요한 경우(또는 헤더를 제어하려는 경우)
  • 신뢰할 수 있는 루프백, 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, // Optional: extend connect/header/body/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 엔드포인트가 아니라 프록시 스타일의 OpenAI 호환 /v1 백엔드로 취급됩니다. 이는 다음을 의미합니다.
동작적용 여부
네이티브 OpenAI 요청 형성아니요
service_tier전송되지 않음
Responses store전송되지 않음
프롬프트 캐시 힌트전송되지 않음
OpenAI 추론 호환 페이로드 형성적용되지 않음
숨겨진 OpenClaw 속성 헤더사용자 지정 기본 URL에는 주입되지 않음
vLLM을 통해 제공되는 Qwen 모델의 경우, 서버가 Qwen 채팅 템플릿 kwargs를 기대하면 모델 항목에 params.qwenThinkingFormat: "chat-template"를 설정하세요. OpenClaw는 /think off를 다음으로 매핑합니다.
{
  "chat_template_kwargs": {
    "enable_thinking": false,
    "preserve_thinking": true
  }
}
off가 아닌 thinking 레벨은 enable_thinking: true를 전송합니다. 엔드포인트가 대신 DashScope 스타일의 최상위 플래그를 기대하는 경우, 요청 루트에 enable_thinking을 전송하려면 params.qwenThinkingFormat: "top-level"을 사용하세요. 스네이크 케이스 params.qwen_thinking_format도 허용됩니다.
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가 마지막 요청 본문 재정의이므로 해당 값이 최종 우선권을 가집니다.
{
  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에서도 동일한 재정의를 적용할 수 있습니다.
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: "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는 연결 설정, 응답 헤더, 본문 스트리밍, 전체 보호된 fetch 중단을 포함하여 vLLM 모델 HTTP 요청에만 적용됩니다. 전체 에이전트 실행을 제어하는 agents.defaults.timeoutSeconds를 늘리기 전에 이를 우선 사용하세요.
vLLM 서버가 실행 중이고 접근 가능한지 확인하세요.
curl http://127.0.0.1:8000/v1/models
연결 오류가 표시되면 호스트, 포트, 그리고 vLLM이 OpenAI 호환 서버 모드로 시작되었는지 확인하세요. 명시적 루프백, 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을 정의한 경우, 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" 재정의 추가
추가 도움말: 문제 해결 및 FAQ.

​
관련 항목

Model selection

제공자, 모델 참조, 장애 조치 동작 선택.

OpenAI

네이티브 OpenAI 제공자 및 OpenAI 호환 라우트 동작.

OAuth and auth

인증 세부 정보 및 자격 증명 재사용 규칙.

Troubleshooting

일반적인 문제와 해결 방법.