메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
시작하기

1

API 키 받기

openrouter.ai/keys에서 API 키를 생성합니다.
2

온보딩 실행

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

(선택 사항) 특정 모델로 전환

온보딩의 기본값은 openrouter/auto입니다. 나중에 구체적인 모델을 선택하세요.
openclaw models set openrouter/<provider>/<model>

​
설정 예시

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

​
모델 참조

모델 참조는 openrouter/<provider>/<model> 패턴을 따릅니다. 사용 가능한 제공자와 모델의 전체 목록은 /concepts/model-providers를 참조하세요.
번들된 폴백 예시:
모델 참조참고
openrouter/autoOpenRouter 자동 라우팅
openrouter/moonshotai/kimi-k2.6MoonshotAI를 통한 Kimi K2.6
openrouter/moonshotai/kimi-k2.5MoonshotAI를 통한 Kimi K2.5

​
이미지 생성

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의 채팅 completions 이미지 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는 STT 엔드포인트(/audio/transcriptions)를 사용하여 공유 tools.media.audio 경로를 통해 인바운드 음성/오디오 첨부 파일을 전사할 수 있습니다. 이는 인바운드 음성/오디오를 미디어 이해 사전 검사로 전달하는 모든 채널 Plugin에 적용됩니다. 
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],
      },
    },
  },
}
OpenClaw는 OpenRouter STT 요청을 multipart OpenAI 양식 업로드가 아니라, input_audio 아래에 base64 오디오가 포함된 JSON(OpenRouter STT 계약)으로 보냅니다.

​
인증 및 헤더

OpenRouter는 내부적으로 API 키와 함께 Bearer 토큰을 사용합니다. 실제 OpenRouter 요청(https://openrouter.ai/api/v1)에서 OpenClaw는 OpenRouter에 문서화된 앱 귀속 헤더도 추가합니다.
헤더값
HTTP-Refererhttps://openclaw.ai
X-OpenRouter-TitleOpenClaw
X-OpenRouter-Categoriescli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent
OpenRouter 제공자를 다른 프록시나 기본 URL로 다시 지정하면, OpenClaw는 해당 OpenRouter 전용 헤더나 Anthropic 캐시 마커를 주입하지 않습니다.

​
고급 설정

OpenRouter 응답 캐싱은 옵트인입니다. 모델 매개변수로 OpenRouter 모델별로 활성화하세요.
{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}
OpenClaw는 X-OpenRouter-Cache: true를 보내며, 설정된 경우 X-OpenRouter-Cache-TTL도 보냅니다. responseCacheClear: true는 현재 요청에 대해 새로고침을 강제하고 대체 응답을 저장합니다. Snake_case 별칭(response_cache, response_cache_ttl_seconds, response_cache_clear)도 허용됩니다.이는 제공자 프롬프트 캐싱 및 OpenRouter의 Anthropic cache_control 마커와 별개입니다. 사용자 지정 프록시 기본 URL이 아니라 검증된 openrouter.ai 경로에만 적용됩니다.
검증된 OpenRouter 경로에서 Anthropic 모델 참조는 시스템/개발자 프롬프트 블록에서 더 나은 프롬프트 캐시 재사용을 위해 OpenClaw가 사용하는 OpenRouter 전용 Anthropic cache_control 마커를 유지합니다.
검증된 OpenRouter 경로에서 reasoning이 활성화된 Anthropic 모델 참조는 요청이 OpenRouter에 도달하기 전에 뒤따르는 어시스턴트 프리필 턴을 제거하여, reasoning 대화가 사용자 턴으로 끝나야 한다는 Anthropic의 요구사항과 맞춥니다.
지원되는 비-auto 경로에서 OpenClaw는 선택된 thinking 수준을 OpenRouter 프록시 reasoning 페이로드에 매핑합니다. 지원되지 않는 모델 힌트와 openrouter/auto는 해당 reasoning 주입을 건너뜁니다. Hunter Alpha도 오래된 설정 모델 참조에 대해 프록시 reasoning을 건너뜁니다. 해당 사용 중단된 경로에서는 OpenRouter가 reasoning 필드에 최종 답변 텍스트를 반환할 수 있기 때문입니다.
검증된 OpenRouter 경로에서 openrouter/deepseek/deepseek-v4-flash와 openrouter/deepseek/deepseek-v4-pro는 재생된 어시스턴트 턴에서 누락된 reasoning_content를 채워 thinking/도구 대화가 DeepSeek V4에 필요한 후속 형태를 유지하도록 합니다. OpenClaw는 이러한 경로에 OpenRouter가 지원하는 reasoning_effort 값을 보냅니다. xhigh는 공지된 가장 높은 수준이며, 오래된 max 오버라이드는 xhigh로 매핑됩니다.
OpenRouter는 여전히 프록시 스타일의 OpenAI 호환 경로를 거치므로, serviceTier, Responses store, OpenAI reasoning 호환 페이로드, 프롬프트 캐시 힌트 같은 네이티브 OpenAI 전용 요청 형태 지정은 전달되지 않습니다.
Gemini 기반 OpenRouter 참조는 프록시-Gemini 경로에 유지됩니다. OpenClaw는 그곳에서 Gemini thought-signature 정리를 유지하지만, 네이티브 Gemini 재생 검증이나 부트스트랩 재작성은 활성화하지 않습니다.
모델 매개변수 아래에 OpenRouter 제공자 라우팅을 전달하면, OpenClaw는 공유 스트림 래퍼가 실행되기 전에 이를 OpenRouter 라우팅 메타데이터로 전달합니다.

​
관련 항목

모델 선택

제공자, 모델 참조, 장애 조치 동작 선택.

설정 참조

에이전트, 모델, 제공자에 대한 전체 설정 참조입니다.