vLLM

vLLM은 OpenAI 호환 HTTP API를 통해 오픈소스(및 일부 커스텀) 모델을 서빙할 수 있습니다. OpenClaw는 openai-completions API를 사용하여 vLLM에 연결할 수 있습니다.

OpenClaw는 VLLM_API_KEY(서버에서 인증을 강제하지 않는 경우 아무 값이나 가능)를 설정하고 명시적인 models.providers.vllm 항목을 정의하지 않으면 vLLM에서 사용 가능한 모델을 자동으로 검색할 수도 있습니다.

빠른 시작

OpenAI 호환 서버로 vLLM을 시작합니다.

기본 URL은 /v1 엔드포인트를 노출해야 합니다 (예: /v1/models, /v1/chat/completions). vLLM은 보통 다음 주소에서 실행됩니다:

http://127.0.0.1:8000/v1

사용을 시작합니다 (인증이 설정되지 않은 경우 아무 값이나 가능):

export VLLM_API_KEY="vllm-local"

모델을 선택합니다 (사용 중인 vLLM 모델 ID로 변경하세요):

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

모델 자동 검색 (암시적 프로바이더)

VLLM_API_KEY가 설정되어 있고(또는 인증 프로필이 존재하고) 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: "Local vLLM Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

문제 해결

서버에 접근 가능한지 확인합니다:

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

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