OpenRouter

OpenRouter는 단일 엔드포인트와 API 키 뒤에서 여러 모델로 요청을 라우팅하는 통합 API를 제공합니다. OpenAI와 호환되므로 대부분의 OpenAI SDK는 기본 URL을 바꾸는 것만으로 작동합니다.

# 시작하기

openclaw onboard --auth-choice openrouter-api-key

openclaw models set openrouter/<provider>/<model>

# 구성 예시

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/auto" },
    },
  },
}

# 모델 참조

번들된 폴백 예시:

# 이미지 생성

OpenRouter는 image_generate 도구도 지원할 수 있습니다. agents.defaults.imageGenerationModel 아래에 OpenRouter 이미지 모델을 사용하세요.

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
        timeoutMs: 180_000,
      },
    },
  },
}

OpenClaw는 modalities: ["image", "text"]와 함께 OpenRouter의 채팅 완성 이미지 API로 이미지 요청을 보냅니다. Gemini 이미지 모델은 OpenRouter의 image_config를 통해 지원되는 aspectRatio 및 resolution 힌트를 받습니다. 더 느린 OpenRouter 이미지 모델에는 agents.defaults.imageGenerationModel.timeoutMs를 사용하세요. image_generate 도구의 호출별 timeoutMs 매개변수가 여전히 우선합니다.

# 동영상 생성

OpenRouter는 비동기 /videos API를 통해 video_generate 도구도 지원할 수 있습니다. agents.defaults.videoGenerationModel 아래에 OpenRouter 동영상 모델을 사용하세요.

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "openrouter/google/veo-3.1-fast",
      },
    },
  },
}

OpenClaw는 텍스트-동영상 및 이미지-동영상 작업을 OpenRouter에 제출하고, 반환된 polling_url을 폴링한 뒤, OpenRouter의 unsigned_urls 또는 문서화된 작업 콘텐츠 엔드포인트에서 완료된 동영상을 다운로드합니다. 참조 이미지는 기본적으로 첫 번째/마지막 프레임 이미지로 전송되며, reference_image로 태그된 이미지는 OpenRouter 입력 참조로 전송됩니다. 번들된 google/veo-3.1-fast 기본값은 현재 지원되는 4/6/8초 길이, 720P/1080P 해상도, 16:9/9:16 종횡비를 알립니다. 업스트림 동영상 생성 API가 현재 텍스트와 이미지 참조를 받기 때문에 OpenRouter에는 동영상-동영상이 등록되어 있지 않습니다.

# 텍스트 음성 변환

OpenRouter는 OpenAI 호환 /audio/speech 엔드포인트를 통해 TTS 제공자로도 사용할 수 있습니다.

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          model: "hexgrad/kokoro-82m",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

messages.tts.providers.openrouter.apiKey가 생략되면 TTS는 models.providers.openrouter.apiKey를 재사용한 다음 OPENROUTER_API_KEY를 사용합니다.

# 인증 및 헤더

OpenRouter는 내부적으로 API 키와 함께 Bearer 토큰을 사용합니다.

실제 OpenRouter 요청(https://openrouter.ai/api/v1)에서 OpenClaw는 OpenRouter의 문서화된 앱 귀속 헤더도 추가합니다.

# 고급 구성

{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}

# 관련 항목