--- read_when: - 여러 LLM에 하나의 API 키를 사용하려는 경우 - OpenClaw에서 OpenRouter를 통해 모델을 실행하려고 합니다 - 이미지 생성에 OpenRouter를 사용하려는 경우 - 음악 생성에 OpenRouter를 사용하려는 경우 - 동영상 생성에 OpenRouter를 사용하려는 경우 summary: OpenRouter의 통합 API를 사용하여 OpenClaw에서 다양한 모델에 액세스하기 title: OpenRouter x-i18n: generated_at: "2026-07-12T01:08:36Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 3047a4da1727db1463d77fcc566231b528e2c34cc64eccaa36827e2927cc60a7 source_path: providers/openrouter.md workflow: 16 --- OpenRouter는 하나의 API와 하나의 키를 통해 여러 모델로 요청을 라우팅합니다. OpenAI와 호환되므로 OpenClaw는 다른 프록시 제공자에 사용하는 것과 동일한 `openai-completions` 스타일 전송 방식을 통해 통신합니다. ## 시작하기 ```bash openclaw onboard --auth-choice openrouter-oauth ``` OpenClaw는 OpenRouter의 브라우저 로그인 흐름(PKCE)을 열고, 코드를 OpenRouter API 키로 교환한 다음 기본 OpenRouter 인증 프로필에 저장합니다. 원격/헤드리스 호스트에서는 OpenClaw가 로그인 URL을 출력하고, 로그인 후 리디렉션 URL을 붙여 넣으라는 메시지를 표시합니다. 온보딩의 기본값은 `openrouter/auto`입니다. 나중에 구체적인 모델을 선택할 수 있습니다. ```bash openclaw models set openrouter// ``` [openrouter.ai/keys](https://openrouter.ai/keys)에서 API 키를 생성합니다. ```bash openclaw onboard --auth-choice openrouter-api-key ``` 온보딩의 기본값은 `openrouter/auto`입니다. 나중에 구체적인 모델을 선택할 수 있습니다. ```bash openclaw models set openrouter// ``` ## 구성 예시 ```json5 { env: { OPENROUTER_API_KEY: "sk-or-..." }, agents: { defaults: { model: { primary: "openrouter/auto" }, }, }, } ``` ## 모델 참조 모델 참조는 `openrouter//` 패턴을 따릅니다. 사용 가능한 제공자와 모델의 전체 목록은 [/concepts/model-providers](/ko/concepts/model-providers)를 참조하세요. 실시간 카탈로그 검색을 사용할 수 없을 때 사용되는 번들 폴백 모델: | 모델 참조 | 참고 | | --------------------------------- | ---------------------------- | | `openrouter/auto` | OpenRouter 자동 라우팅 | | `openrouter/moonshotai/kimi-k2.6` | MoonshotAI를 통한 Kimi K2.6 | | `openrouter/moonshotai/kimi-k2.5` | MoonshotAI를 통한 Kimi K2.5 | [퓨전 라우터](#fusion-router)를 참조하는 `openrouter/openrouter/fusion`을 포함하여 그 밖의 모든 `openrouter//` 참조는 OpenRouter의 실시간 모델 카탈로그를 기준으로 동적으로 해석됩니다. ## 이미지 생성 OpenRouter를 `image_generate` 도구의 백엔드로 사용할 수 있습니다. `agents.defaults.imageGenerationModel` 아래에 OpenRouter 이미지 모델을 설정하세요. ```json5 { 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 동영상 모델을 설정하세요. ```json5 { 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 오디오 모델을 설정하세요. ```json5 { 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 제공자 역할을 할 수 있습니다. ```json5 { 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에 적용됩니다. ```json5 { 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 네임스페이스가 모두 포함됩니다. ```bash openclaw models set openrouter/openrouter/fusion ``` 모델의 `params.extraBody`를 통해 Fusion의 패널과 평가 모델을 구성하세요. 해당 필드는 OpenRouter 채팅 완성 요청 본문에 직접 전달됩니다. Fusion은 OAuth 또는 API 키 온보딩 모두에서 작동합니다. OAuth를 사용하는 경우 아래의 `env.OPENROUTER_API_KEY` 줄을 생략하세요. ```json5 { 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가 프롬프트를 여러 분석 모델에 분산한 다음 평가/종합 단계를 실행하므로 직접적인 단일 모델 요청보다 지연 시간이 더 깁니다. 지연 시간에 민감한 기본값으로 사용하지 말고, 신중한 고품질 답변이나 에스컬레이션 경로에 사용하세요. 더 빠른 응답을 원한다면 패널을 작게 유지하고 더 빠른 분석/평가 모델을 선택하세요. 구성된 참조를 일회성 로컬 호출로 테스트하세요. ```bash 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 키 인증 프로필에 결과를 저장합니다. 전체 온보딩을 다시 실행하지 않고 기존 설치에서 로그인하거나 저장된 키를 교체하려면 다음을 실행하세요. ```bash openclaw models auth login --provider openrouter --method oauth openclaw models auth login --provider openrouter --method api-key ``` 검증된 OpenRouter 요청(`https://openrouter.ai/api/v1`)에서 OpenClaw는 OpenRouter에 문서화된 앱 귀속 헤더를 추가합니다. | 헤더 | 값 | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | `HTTP-Referer` | `https://openclaw.ai` | | `X-OpenRouter-Title` | `OpenClaw` | | `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` | OpenRouter 제공자가 다른 프록시 또는 기본 URL을 가리키도록 변경하면 OpenClaw는 해당 OpenRouter 전용 헤더나 Anthropic 캐시 마커를 삽입하지 **않습니다**. ## 고급 구성 OpenRouter 응답 캐싱은 명시적으로 활성화해야 합니다. 모델별로 활성화하세요. ```json5 { agents: { defaults: { models: { "openrouter/auto": { params: { responseCache: true, responseCacheTtlSeconds: 300, }, }, }, }, }, } ``` OpenClaw는 `X-OpenRouter-Cache: true`를 전송하며, 구성된 경우 `X-OpenRouter-Cache-TTL`도 전송합니다. `responseCacheClear: true`는 현재 요청에 대해 새로 고침을 강제하고 대체 응답을 저장합니다. 스네이크 케이스 별칭(`response_cache`, `response_cache_ttl_seconds`, `response_cache_clear`)도 허용되며, `Seconds` 접미사가 없는 `responseCacheTtl` / `response_cache_ttl`도 허용됩니다. 이는 제공자 프롬프트 캐싱 및 OpenRouter의 Anthropic `cache_control` 마커와 별개입니다. 사용자 지정 프록시 기본 URL이 아닌 검증된 `openrouter.ai` 경로에만 적용됩니다. 검증된 OpenRouter 경로에서 Anthropic 모델 참조는 시스템/개발자 프롬프트 블록의 프롬프트 캐시 재사용을 개선하기 위해 OpenRouter의 Anthropic `cache_control` 마커를 유지합니다. 검증된 OpenRouter 경로에서는 추론이 활성화된 Anthropic 모델 참조의 경우 요청이 OpenRouter에 도달하기 전에 마지막 어시스턴트 프리필 턴을 제거하여, 추론 대화가 사용자 턴으로 끝나야 한다는 Anthropic의 요구 사항을 충족합니다. 지원되는 `auto` 이외의 경로에서 OpenClaw는 선택한 사고 수준을 OpenRouter 프록시 추론 페이로드에 매핑합니다. `openrouter/auto` 및 지원되지 않는 모델 힌트에서는 이 주입을 건너뜁니다. 오래된 `openrouter/hunter-alpha` 참조에서도 이를 건너뜁니다. 폐기된 해당 경로에서는 OpenRouter가 추론 필드에 최종 답변 텍스트를 반환할 수 있기 때문입니다. 검증된 OpenRouter 경로에서 `openrouter/deepseek/deepseek-v4-flash` 및 `openrouter/deepseek/deepseek-v4-pro`는 재현된 어시스턴트 턴에 누락된 `reasoning_content`를 채워 사고/도구 대화를 DeepSeek V4에서 요구하는 후속 형식으로 유지합니다. OpenClaw는 이러한 경로에 OpenRouter가 지원하는 `reasoning.effort` 값을 전송합니다. `xhigh`/`max`는 `xhigh`로 매핑되고, 끄기 이외의 다른 모든 수준은 `high`로 매핑됩니다. OpenRouter는 프록시 방식의 OpenAI 호환 경로를 통해 실행되므로, `serviceTier`, Responses `store`, OpenAI 추론 호환 페이로드, 프롬프트 캐시 힌트와 같은 네이티브 OpenAI 전용 요청 형식 조정은 전달되지 않습니다. Gemini 기반 OpenRouter 참조는 프록시 Gemini 경로를 유지합니다. OpenClaw는 이 경로에서 Gemini 사고 서명 정제를 유지하지만, 네이티브 Gemini 재현 검증이나 부트스트랩 재작성은 활성화하지 않습니다. OpenRouter는 기반 제공자 라우팅을 위한 `provider` 요청 객체를 지원합니다. `models.providers.openrouter.params.provider`를 사용하여 모든 OpenRouter 텍스트 모델 요청의 기본 정책을 구성합니다. ```json5 { models: { providers: { openrouter: { params: { provider: { sort: "latency", require_parameters: true, data_collection: "deny", }, }, }, }, }, } ``` OpenClaw는 해당 객체를 요청의 `provider` 페이로드로 OpenRouter에 전달합니다. `sort`, `only`, `ignore`, `order`, `allow_fallbacks`, `require_parameters`, `data_collection`, `quantizations`, `max_price`, `preferred_max_latency`, `preferred_min_throughput`, `zdr`, `enforce_distillable_text`를 포함하여 OpenRouter 문서에 명시된 snake_case 필드를 사용하세요. 모델별 매개변수는 제공자 전체에 적용되는 라우팅 객체보다 우선합니다. ```json5 { agents: { defaults: { models: { "openrouter/anthropic/claude-sonnet-4-6": { params: { provider: { order: ["anthropic"], allow_fallbacks: false, }, }, }, }, }, }, } ``` 이는 OpenRouter 채팅 완성 경로에만 적용됩니다. Anthropic, Google, OpenAI 또는 사용자 지정 제공자의 직접 경로에서는 OpenRouter 라우팅 매개변수를 무시합니다. ## 관련 항목 제공자, 모델 참조 및 장애 조치 동작을 선택합니다. 에이전트, 모델 및 제공자의 전체 구성 참조입니다.