OpenRouter

OpenRouter fornisce una API unificata che instrada le richieste a molti modelli dietro un singolo endpoint e una chiave API. È compatibile con OpenAI, quindi la maggior parte degli SDK OpenAI funziona cambiando l'URL di base.

Per iniziare

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>

Esempio di configurazione

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

Riferimenti dei modelli

Esempi di fallback inclusi:

Generazione di immagini

OpenRouter può anche supportare lo strumento image_generate. Usa un modello immagine OpenRouter in 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 invia le richieste di immagine all'API immagini delle chat completions di OpenRouter con modalities: ["image", "text"]. I modelli immagine Gemini ricevono suggerimenti aspectRatio e resolution supportati tramite image_config di OpenRouter. Usa agents.defaults.imageGenerationModel.timeoutMs per i modelli immagine OpenRouter più lenti; il parametro per chiamata timeoutMs dello strumento image_generate ha comunque la precedenza.

Generazione di video

OpenRouter può anche supportare lo strumento video_generate tramite la sua API asincrona /videos. Usa un modello video OpenRouter in agents.defaults.videoGenerationModel:

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

OpenClaw invia a OpenRouter job da testo a video e da immagine a video, esegue il polling del polling_url restituito e scarica il video completato da unsigned_urls di OpenRouter o dall'endpoint documentato dei contenuti del job. Le immagini di riferimento vengono inviate per impostazione predefinita come immagini del primo/ultimo frame; le immagini contrassegnate con reference_image vengono inviate come riferimenti di input OpenRouter. Il valore predefinito incluso google/veo-3.1-fast dichiara le durate attualmente supportate di 4/6/8 secondi, le risoluzioni 720P/1080P e i rapporti d'aspetto 16:9/9:16. Il video-to-video non è registrato per OpenRouter perché l'API upstream di generazione video attualmente accetta testo e riferimenti immagine.

Generazione musicale

OpenRouter può anche supportare lo strumento music_generate tramite l'output audio delle chat completions. Usa un modello audio OpenRouter in agents.defaults.musicGenerationModel:

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

Il provider musicale OpenRouter incluso usa per impostazione predefinita google/lyria-3-pro-preview ed espone anche google/lyria-3-clip-preview. OpenClaw invia modalities: ["text", "audio"], abilita lo streaming, raccoglie i chunk audio in streaming e salva il risultato come media generato per la consegna sul canale. Le immagini di riferimento sono accettate per i modelli Lyria tramite il parametro condiviso music_generate image=....

Sintesi vocale

OpenRouter può anche essere usato come provider TTS tramite il suo endpoint compatibile con 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 viene omesso, TTS riutilizza models.providers.openrouter.apiKey, poi OPENROUTER_API_KEY.

Riconoscimento vocale (audio in ingresso)

OpenRouter può trascrivere allegati vocali/audio in ingresso tramite il percorso condiviso tools.media.audio usando il suo endpoint STT (/audio/transcriptions). Questo si applica a qualsiasi plugin di canale che inoltra voce/audio in ingresso alla preflight di comprensione dei media.

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

OpenClaw invia le richieste STT OpenRouter come JSON con audio base64 in input_audio (contratto STT OpenRouter), non come caricamenti multipart di moduli OpenAI.

Router Fusion

Usa OpenRouter Fusion quando vuoi che un unico riferimento modello OpenClaw chieda a più modelli OpenRouter in parallelo, faccia valutare le loro risposte da OpenRouter e restituisca una singola risposta finale tramite il normale endpoint del provider OpenRouter. Poiché lo slug del modello upstream è openrouter/fusion, il riferimento modello OpenClaw include sia il prefisso del provider OpenClaw sia il namespace OpenRouter upstream:

openclaw models set openrouter/openrouter/fusion

Configura il pannello e il giudice di Fusion tramite params.extraBody del modello. Quei campi vengono inoltrati nel corpo della richiesta chat-completions di OpenRouter. Fusion funziona sia con l'onboarding OAuth OpenRouter sia con l'onboarding con chiave API; se usi OAuth, ometti la riga env.OPENROUTER_API_KEY dall'esempio seguente.

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

L'elenco analysis_models è il pannello parallelo, e model dentro la configurazione del plugin Fusion è il modello giudice. Non impostare tool_choice di primo livello su "required" nei normali turni agente/chat di OpenClaw per provare a forzare Fusion; i turni OpenClaw possono includere definizioni di strumenti OpenClaw, e una scelta strumento richiesta di primo livello può richiedere uno di quegli strumenti invece del router Fusion. Quando questa configurazione del plugin Fusion è presente, OpenClaw aggiunge anche una nota sanitizzata al prompt di sistema con i modelli di analisi configurati e il modello giudice, così l'agente può rispondere a domande sul suo pannello Fusion corrente. Gli altri campi extraBody non vengono copiati nel prompt.

Fusion è più lento per progettazione. OpenRouter può inviare lo stesso prompt OpenClaw a più modelli di analisi e poi eseguire un passaggio finale di giudizio/sintesi, quindi la latenza è di solito più alta rispetto a una richiesta diretta a modello singolo. Usa Fusion per risposte deliberate e di alta qualità o per percorsi di escalation, non come predefinito per chat sensibili alla latenza. Per risposte più rapide, mantieni piccolo il pannello e scegli modelli di analisi e giudizio più veloci.

Testa il riferimento configurato con una chiamata locale one-shot al modello:

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

Autenticazione e header

OpenRouter usa internamente un token Bearer con la tua chiave API. OpenRouter OAuth è un flusso di accesso PKCE che emette una chiave API OpenRouter, quindi OpenClaw archivia il risultato come lo stesso profilo di autenticazione con chiave API openrouter:default usato dal percorso di configurazione manuale con chiave API.

Per un'installazione esistente, accedi o ruota la chiave OpenRouter archiviata senza rieseguire l'onboarding completo:

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

Usa openclaw models auth login --provider openrouter --method api-key quando vuoi incollare una chiave creata manualmente su OpenRouter.

Nelle richieste OpenRouter reali (https://openrouter.ai/api/v1), OpenClaw aggiunge anche gli header di attribuzione dell'app documentati da OpenRouter:

Configurazione avanzata

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

Correlati