OpenRouter

OpenRouter는 하나의 API와 하나의 키를 통해 여러 모델로 요청을 라우팅합니다. OpenAI와 호환되므로 OpenClaw는 다른 프록시 제공자에 사용하는 것과 동일한 openai-completions 스타일 전송 방식을 통해 통신합니다.

시작하기

openclaw onboard --auth-choice openrouter-oauth

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

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/openrouter/fusion을 포함하여 그 밖의 모든 openrouter/<provider>/<model> 참조는 OpenRouter의 실시간 모델 카탈로그를 기준으로 동적으로 해석됩니다.

이미지 생성

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 힌트가 전달되지만, 다른 이미지 모델에는 전달되지 않습니다. 속도가 느린 모델에는 agents.defaults.imageGenerationModel.timeoutMs를 사용하세요. 단, image_generate 도구의 호출별 timeoutMs가 항상 우선합니다.

동영상 생성

OpenRouter의 비동기 /videos API를 통해 video_generate 도구의 백엔드로 OpenRouter를 사용할 수 있습니다. agents.defaults.videoGenerationModel 아래에 OpenRouter 동영상 모델을 설정하세요.

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

OpenClaw는 텍스트-동영상 및 이미지-동영상 작업을 제출하고, 반환된 polling_url을 폴링한 다음 OpenRouter의 unsigned_urls 또는 작업 콘텐츠 엔드포인트에서 완성된 동영상을 다운로드합니다. 참조 이미지는 기본적으로 첫 프레임/마지막 프레임 이미지로 사용되며, reference_image로 태그된 이미지는 대신 입력 참조로 전송됩니다. 번들 기본값인 google/veo-3.1-fast는 4/6/8초 길이, 720P/1080P 해상도, 16:9/9:16 화면비를 지원합니다. 동영상-동영상 변환은 지원되지 않습니다. 업스트림 API는 텍스트 및 이미지 참조만 허용합니다.

음악 생성

채팅 완성 오디오 출력을 통해 music_generate 도구의 백엔드로 OpenRouter를 사용할 수 있습니다. agents.defaults.musicGenerationModel 아래에 OpenRouter 오디오 모델을 설정하세요.

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      musicGenerationModel: {        primary: "openrouter/google/lyria-3-pro-preview",        timeoutMs: 180_000,      },    },  },}

번들 OpenRouter 음악 제공자의 기본값은 google/lyria-3-pro-preview이며, google/lyria-3-clip-preview도 제공합니다. OpenClaw는 modalities: ["text", "audio"]를 전송하고, 응답을 스트리밍하며, 오디오 청크를 수집한 다음 채널 전달용으로 생성된 미디어에 결과를 저장합니다. Lyria 모델은 공유 music_generate image=... 매개변수를 통해 하나의 참조 이미지를 받을 수 있습니다. 스트리밍 오디오, 트랜스크립트 보존 및 파생된 SSE 이벤트 봉투는 agents.defaults.mediaMaxMb의 제한을 받습니다(기본 오디오 한도는 16MB).

텍스트 음성 변환

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

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

messages.tts.providers.openrouter.apiKey를 생략하면 TTS는 models.providers.openrouter.apiKey, 그다음 OPENROUTER_API_KEY를 차례로 사용합니다.

음성 텍스트 변환(인바운드 오디오)

OpenRouter는 STT 엔드포인트(/audio/transcriptions)를 사용하는 공유 tools.media.audio 경로를 통해 인바운드 음성/오디오 첨부 파일을 텍스트로 변환할 수 있습니다. 이는 인바운드 음성/오디오를 미디어 이해 사전 점검으로 전달하는 모든 채널 Plugin에 적용됩니다.

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],      },    },  },}

OpenClaw는 멀티파트 OpenAI 양식 업로드가 아니라 input_audio 아래에 base64 오디오를 포함하는 JSON(OpenRouter의 STT 계약)으로 OpenRouter STT 요청을 보냅니다.

퓨전 라우터

OpenRouter Fusion은 하나의 OpenClaw 모델 참조를 여러 OpenRouter 모델에 병렬로 전송하고, OpenRouter가 해당 답변을 평가하게 한 다음 일반 OpenRouter 엔드포인트를 통해 하나의 최종 응답을 반환합니다. 업스트림 모델 슬러그는 openrouter/fusion이므로 OpenClaw 모델 참조에는 OpenClaw 제공자 접두사와 업스트림 OpenRouter 네임스페이스가 모두 포함됩니다.

openclaw models set openrouter/openrouter/fusion

모델의 params.extraBody를 통해 Fusion의 패널과 평가 모델을 구성하세요. 해당 필드는 OpenRouter 채팅 완성 요청 본문에 직접 전달됩니다. Fusion은 OAuth 또는 API 키 온보딩 모두에서 작동합니다. OAuth를 사용하는 경우 아래의 env.OPENROUTER_API_KEY 줄을 생략하세요.

{  env: { OPENROUTER_API_KEY: "sk-or-..." },  agents: {    defaults: {      model: { primary: "openrouter/openrouter/fusion" },      models: {        "openrouter/openrouter/fusion": {          params: {            extraBody: {              plugins: [                {                  id: "fusion",                  analysis_models: [                    "google/gemini-3.5-flash",                    "moonshotai/kimi-k2.6",                    "deepseek/deepseek-v4-pro",                  ],                  model: "google/gemini-3.5-flash",                },              ],            },          },        },      },    },  },}

analysis_models는 병렬 패널이며, Fusion Plugin 구성 내부의 model은 평가 모델입니다. Fusion을 강제하기 위해 일반 에이전트/채팅 턴에서 최상위 tool_choice를 "required"로 설정하지 마세요. OpenClaw 턴에는 자체 도구 정의가 포함될 수 있으며, 최상위 필수 도구 선택이 Fusion 라우터 대신 해당 도구 중 하나를 선택할 수 있습니다. 이 Fusion Plugin 구성이 있으면 OpenClaw는 구성된 분석 모델과 평가 모델을 나열하는 정제된 시스템 프롬프트 메모를 추가하므로 에이전트가 자체 Fusion 패널에 관한 질문에 답할 수 있습니다. 다른 extraBody 필드는 프롬프트에 복사되지 않습니다.

Fusion은 설계상 더 느립니다. OpenRouter가 프롬프트를 여러 분석 모델에 분산한 다음 평가/종합 단계를 실행하므로 직접적인 단일 모델 요청보다 지연 시간이 더 깁니다. 지연 시간에 민감한 기본값으로 사용하지 말고, 신중한 고품질 답변이나 에스컬레이션 경로에 사용하세요. 더 빠른 응답을 원한다면 패널을 작게 유지하고 더 빠른 분석/평가 모델을 선택하세요.

구성된 참조를 일회성 로컬 호출로 테스트하세요.

openclaw infer model run --local \  --model openrouter/openrouter/fusion \  --prompt "Reply with exactly: FUSION_OK" \  --json

인증 및 헤더

OpenRouter는 API 키의 Bearer 토큰을 사용합니다. OpenRouter OAuth는 OpenRouter API 키를 발급하는 PKCE 로그인 흐름이므로 OpenClaw는 수동 API 키 설정에 사용되는 것과 동일한 openrouter:default API 키 인증 프로필에 결과를 저장합니다.

전체 온보딩을 다시 실행하지 않고 기존 설치에서 로그인하거나 저장된 키를 교체하려면 다음을 실행하세요.

openclaw models auth login --provider openrouter --method oauthopenclaw models auth login --provider openrouter --method api-key

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

고급 구성

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

{  models: {    providers: {      openrouter: {        params: {          provider: {            sort: "latency",            require_parameters: true,            data_collection: "deny",          },        },      },    },  },}

{  agents: {    defaults: {      models: {        "openrouter/anthropic/claude-sonnet-4-6": {          params: {            provider: {              order: ["anthropic"],              allow_fallbacks: false,            },          },        },      },    },  },}

관련 항목