메인 콘텐츠로 건너뛰기

​
vLLM

vLLM은 OpenAI 호환 HTTP API를 통해 오픈소스(및 일부 커스텀) 모델을 제공할 수 있습니다. OpenClaw는 openai-completions API를 사용해 vLLM에 연결합니다. VLLM_API_KEY로 옵트인하고(서버가 인증을 강제하지 않는다면 어떤 값이든 가능) 명시적인 models.providers.vllm 항목을 정의하지 않으면, OpenClaw는 vLLM에서 사용 가능한 모델을 자동 검색할 수도 있습니다.
속성값
Provider IDvllm
APIopenai-completions (OpenAI 호환)
인증VLLM_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 키 환경 변수 설정

서버가 인증을 강제하지 않는다면 어떤 값이든 동작합니다:
export VLLM_API_KEY="vllm-local"
3

모델 선택

자신의 vLLM 모델 ID 중 하나로 교체하세요:
{
  agents: {
    defaults: {
      model: { primary: "vllm/your-model-id" },
    },
  },
}
4

모델 사용 가능 여부 확인

openclaw models list --provider vllm

​
모델 검색(암시적 provider)

VLLM_API_KEY가 설정되어 있거나(또는 auth profile이 존재하고) models.providers.vllm을 정의하지 않은 경우, OpenClaw는 다음을 조회합니다. 
GET http://127.0.0.1:8000/v1/models
그리고 반환된 ID를 모델 항목으로 변환합니다.
models.providers.vllm을 명시적으로 설정하면 자동 검색은 건너뛰어지며, 모델을 수동으로 정의해야 합니다.

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

다음과 같은 경우에는 명시적 구성을 사용하세요.
  • vLLM이 다른 호스트 또는 포트에서 실행되는 경우
  • contextWindow 또는 maxTokens 값을 고정하고 싶은 경우
  • 서버가 실제 API 키를 요구하는 경우(또는 헤더를 직접 제어하고 싶은 경우)
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        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 엔드포인트가 아니라 프록시 스타일 OpenAI 호환 /v1 백엔드로 취급됩니다. 이는 다음을 의미합니다.
동작적용 여부
기본 OpenAI 요청 형태 구성아니요
service_tier전송되지 않음
Responses store전송되지 않음
프롬프트 캐시 힌트전송되지 않음
OpenAI reasoning 호환 페이로드 형태 구성적용되지 않음
숨겨진 OpenClaw attribution 헤더커스텀 base URL에는 주입되지 않음
vLLM 서버가 기본이 아닌 호스트나 포트에서 실행된다면, 명시적 provider 구성에서 baseUrl을 설정하세요.
{
  models: {
    providers: {
      vllm: {
        baseUrl: "http://192.168.1.50:9000/v1",
        apiKey: "${VLLM_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "my-custom-model",
            name: "원격 vLLM 모델",
            reasoning: false,
            input: ["text"],
            contextWindow: 64000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

​
문제 해결

vLLM 서버가 실행 중이고 접근 가능한지 확인하세요.
curl http://127.0.0.1:8000/v1/models
연결 오류가 보이면 호스트, 포트, 그리고 vLLM이 OpenAI 호환 서버 모드로 시작되었는지 확인하세요.
요청이 인증 오류로 실패하면 서버 구성과 일치하는 실제 VLLM_API_KEY를 설정하거나, models.providers.vllm 아래에 provider를 명시적으로 구성하세요.
vLLM 서버가 인증을 강제하지 않는다면, VLLM_API_KEY에 비어 있지 않은 아무 값이나 넣어도 OpenClaw의 옵트인 신호로 동작합니다.
자동 검색이 동작하려면 VLLM_API_KEY가 설정되어 있어야 하고, 동시에 명시적 models.providers.vllm 구성 항목이 없어야 합니다. provider를 수동 정의한 경우, OpenClaw는 검색을 건너뛰고 선언된 모델만 사용합니다.
추가 도움말: 문제 해결 및 FAQ.

​
관련 항목

모델 선택

Provider, 모델 ref, 장애 조치 동작을 선택합니다.

OpenAI

기본 OpenAI provider 및 OpenAI 호환 경로 동작.

OAuth 및 인증

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

문제 해결

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