OpenRouter

OpenRouter fornece uma API unificada que roteia solicitações para muitos modelos por trás de um único endpoint e chave de API. Ela é compatível com OpenAI, então a maioria dos SDKs da OpenAI funciona ao trocar a URL base.

Primeiros passos

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>

Exemplo de configuração

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

Referências de modelos

Exemplos de fallback incluídos:

Geração de imagens

OpenRouter também pode dar suporte à ferramenta image_generate. Use um modelo de imagem da OpenRouter em agents.defaults.imageGenerationModel:

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

OpenClaw envia solicitações de imagem para a API de imagens de conclusões de chat da OpenRouter com modalities: ["image", "text"]. Modelos de imagem Gemini recebem dicas compatíveis de aspectRatio e resolution por meio de image_config da OpenRouter. Use agents.defaults.imageGenerationModel.timeoutMs para modelos de imagem mais lentos da OpenRouter; o parâmetro timeoutMs por chamada da ferramenta image_generate ainda prevalece.

Geração de vídeo

OpenRouter também pode dar suporte à ferramenta video_generate por meio de sua API assíncrona /videos. Use um modelo de vídeo da OpenRouter em agents.defaults.videoGenerationModel:

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

OpenClaw envia tarefas de texto para vídeo e imagem para vídeo para a OpenRouter, consulta o polling_url retornado e baixa o vídeo concluído a partir dos unsigned_urls da OpenRouter ou do endpoint documentado de conteúdo da tarefa. Imagens de referência são enviadas como imagens do primeiro/último quadro por padrão; imagens marcadas com reference_image são enviadas como referências de entrada da OpenRouter. O padrão incluído google/veo-3.1-fast anuncia as durações de 4/6/8 segundos atualmente compatíveis, resoluções 720P/1080P e proporções de aspecto 16:9/9:16. Vídeo para vídeo não é registrado para a OpenRouter porque a API upstream de geração de vídeo atualmente aceita referências de texto e imagem.

Geração de música

OpenRouter também pode dar suporte à ferramenta music_generate por meio da saída de áudio de conclusões de chat. Use um modelo de áudio da OpenRouter em agents.defaults.musicGenerationModel:

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

O provedor de música OpenRouter incluído usa google/lyria-3-pro-preview por padrão e também expõe google/lyria-3-clip-preview. OpenClaw envia modalities: ["text", "audio"], habilita streaming, coleta os fragmentos de áudio transmitidos e salva o resultado como mídia gerada para entrega em canais. Imagens de referência são aceitas para modelos Lyria por meio do parâmetro compartilhado music_generate image=....

Texto para fala

OpenRouter também pode ser usado como provedor de TTS por meio do endpoint compatível com OpenAI /audio/speech.

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

Se messages.tts.providers.openrouter.apiKey for omitido, o TTS reutiliza models.providers.openrouter.apiKey, depois OPENROUTER_API_KEY.

Fala para texto (áudio de entrada)

O OpenRouter pode transcrever anexos de voz/áudio de entrada pelo caminho compartilhado tools.media.audio usando seu endpoint de STT (/audio/transcriptions). Isso se aplica a qualquer Plugin de canal que encaminhe voz/áudio de entrada para o preflight de entendimento de mídia.

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

O OpenClaw envia solicitações de STT do OpenRouter como JSON com áudio em base64 em input_audio (contrato de STT do OpenRouter), não como uploads de formulário multipart do OpenAI.

Roteador Fusion

Use o OpenRouter Fusion quando quiser que uma ref de modelo do OpenClaw consulte vários modelos do OpenRouter em paralelo, que o OpenRouter julgue as respostas deles e retorne uma única resposta final pelo endpoint normal do provedor OpenRouter. Como o slug do modelo upstream é openrouter/fusion, a ref de modelo do OpenClaw inclui tanto o prefixo de provedor do OpenClaw quanto o namespace upstream do OpenRouter:

openclaw models set openrouter/openrouter/fusion

Configure o painel e o juiz do Fusion por meio de params.extraBody do modelo. Esses campos são encaminhados para o corpo da solicitação de chat-completions do OpenRouter. O Fusion funciona com onboarding OAuth do OpenRouter ou onboarding por chave de API; se você usar OAuth, omita a linha env.OPENROUTER_API_KEY do exemplo abaixo.

{  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",                },              ],            },          },        },      },    },  },}

A lista analysis_models é o painel paralelo, e model dentro da configuração do Plugin Fusion é o modelo juiz. Não defina tool_choice de nível superior como "required" em turnos normais de agente/chat do OpenClaw para tentar forçar o Fusion; os turnos do OpenClaw podem incluir definições de ferramentas do OpenClaw, e uma escolha de ferramenta obrigatória em nível superior pode exigir uma dessas ferramentas em vez do roteador Fusion. Quando essa configuração do Plugin Fusion está presente, o OpenClaw também adiciona uma nota sanitizada ao prompt do sistema com os modelos de análise configurados e o modelo juiz, para que o agente possa responder a perguntas sobre seu painel Fusion atual. Outros campos de extraBody não são copiados para o prompt.

O Fusion é mais lento por design. O OpenRouter pode enviar o mesmo prompt do OpenClaw para vários modelos de análise e depois executar uma etapa final de julgamento/síntese, portanto a latência geralmente é maior do que em uma solicitação direta a um único modelo. Use o Fusion para respostas deliberadas e de alta qualidade ou caminhos de escalonamento, não como padrão para chats sensíveis à latência. Para respostas mais rápidas, mantenha o painel pequeno e escolha modelos de análise e juiz mais rápidos.

Teste a ref configurada com uma chamada local de modelo de uso único:

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

Autenticação e cabeçalhos

O OpenRouter usa um token Bearer com sua chave de API nos bastidores. O OAuth do OpenRouter é um fluxo de login PKCE que emite uma chave de API do OpenRouter, então o OpenClaw armazena o resultado como o mesmo perfil de autenticação por chave de API openrouter:default usado pelo caminho de configuração manual por chave de API.

Em uma instalação existente, faça login ou rotacione a chave armazenada do OpenRouter sem executar novamente todo o onboarding:

openclaw models auth login --provider openrouter --method oauth

Use openclaw models auth login --provider openrouter --method api-key quando quiser colar uma chave criada manualmente no OpenRouter.

Em solicitações reais do OpenRouter (https://openrouter.ai/api/v1), o OpenClaw também adiciona os cabeçalhos de atribuição de app documentados pelo OpenRouter:

Configuração avançada

{  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,            },          },        },      },    },  },}

Relacionado