OpenRouter

OpenRouter instrada le richieste verso numerosi modelli tramite un'unica API e un'unica chiave. È compatibile con OpenAI, quindi OpenClaw comunica con esso tramite lo stesso trasporto in stile openai-completions utilizzato per gli altri provider proxy.

Guida introduttiva

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 ai modelli

Modelli di riserva inclusi, utilizzati quando il rilevamento del catalogo in tempo reale non è disponibile:

Qualsiasi altro riferimento openrouter/<provider>/<model>, incluso openrouter/openrouter/fusion (vedere router Fusion), viene risolto dinamicamente rispetto al catalogo dei modelli in tempo reale di OpenRouter.

Generazione di immagini

OpenRouter può supportare lo strumento image_generate. Impostare un modello per immagini 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 immagini all'API per immagini basata sul completamento delle chat di OpenRouter con modalities: ["image", "text"]. I modelli per immagini Gemini ricevono inoltre indicazioni aspectRatio e resolution tramite image_config di OpenRouter; gli altri modelli per immagini non le ricevono. Utilizzare agents.defaults.imageGenerationModel.timeoutMs per i modelli più lenti; il valore timeoutMs specificato per singola chiamata dello strumento image_generate ha comunque la precedenza.

Generazione di video

OpenRouter può supportare lo strumento video_generate tramite la propria API asincrona /videos. Impostare 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 processi di generazione da testo a video e da immagine a video, interroga periodicamente il polling_url restituito e scarica il video completato dagli unsigned_urls di OpenRouter o dall'endpoint dei contenuti del processo. Per impostazione predefinita, le immagini di riferimento vengono usate come primo o ultimo fotogramma; le immagini contrassegnate con reference_image vengono invece inviate come riferimenti di input. Il modello predefinito incluso google/veo-3.1-fast supporta durate di 4/6/8 secondi, risoluzioni 720P/1080P e proporzioni 16:9/9:16. La generazione da video a video non è supportata: l'API a monte accetta solo riferimenti testuali e immagini.

Generazione di musica

OpenRouter può supportare lo strumento music_generate tramite l'output audio dei completamenti delle chat. Impostare 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 e rende disponibile anche google/lyria-3-clip-preview. OpenClaw invia modalities: ["text", "audio"], riceve la risposta in streaming, raccoglie i frammenti audio e salva il risultato come contenuto multimediale generato per la consegna al canale. I modelli Lyria accettano un'unica immagine di riferimento tramite il parametro condiviso music_generate image=.... L'audio in streaming, la conservazione della trascrizione e l'involucro derivato degli eventi SSE sono limitati da agents.defaults.mediaMaxMb (il limite audio predefinito è 16 MB).

Sintesi vocale

OpenRouter può fungere da provider TTS tramite il proprio 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 utilizza come ripiego models.providers.openrouter.apiKey, quindi OPENROUTER_API_KEY.

Da voce a testo (audio in ingresso)

OpenRouter può trascrivere gli allegati vocali/audio in ingresso tramite il percorso condiviso tools.media.audio, utilizzando il proprio endpoint STT (/audio/transcriptions). Questo vale per qualsiasi Plugin di canale che inoltri contenuti vocali/audio in ingresso al controllo preliminare di comprensione dei contenuti multimediali.

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

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

Router Fusion

OpenRouter Fusion invia un riferimento modello OpenClaw a diversi modelli OpenRouter in parallelo, fa valutare le loro risposte da OpenRouter e restituisce un'unica risposta finale tramite il normale endpoint OpenRouter. Lo slug del modello upstream è openrouter/fusion, quindi il riferimento modello OpenClaw include sia il prefisso del provider OpenClaw sia lo spazio dei nomi OpenRouter upstream:

openclaw models set openrouter/openrouter/fusion

Configura il gruppo di modelli e il giudice di Fusion tramite params.extraBody del modello; questi campi vengono inoltrati direttamente nel corpo della richiesta di completamento chat di OpenRouter. Fusion funziona con la configurazione iniziale sia tramite OAuth sia tramite chiave API; se utilizzi OAuth, ometti la riga env.OPENROUTER_API_KEY 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",                },              ],            },          },        },      },    },  },}

analysis_models è il gruppo parallelo; model nella configurazione del Plugin Fusion è il modello giudice. Nei normali turni dell'agente o della chat, non impostare tool_choice di primo livello su "required" per tentare di forzare Fusion: i turni OpenClaw possono includere le proprie definizioni degli strumenti e una scelta obbligatoria dello strumento di primo livello potrebbe selezionarne uno al posto del router Fusion. Quando questa configurazione del Plugin Fusion è presente, OpenClaw aggiunge al prompt di sistema una nota sanificata che elenca i modelli di analisi configurati e il modello giudice, così l'agente può rispondere alle domande sul proprio gruppo Fusion. Gli altri campi extraBody non vengono copiati nel prompt.

Fusion è più lento per progettazione: OpenRouter distribuisce il prompt a più modelli di analisi, quindi esegue una fase di valutazione e sintesi; di conseguenza, la latenza è superiore rispetto a una richiesta diretta a un singolo modello. Utilizzalo per risposte ponderate e di alta qualità o per percorsi di escalation, non come impostazione predefinita quando la latenza è un fattore critico. Mantieni ridotto il gruppo e scegli modelli di analisi e giudizio più veloci per ottenere risposte più rapide.

Verifica un riferimento configurato con una singola chiamata locale:

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

Autenticazione e intestazioni

OpenRouter utilizza un token Bearer derivato dalla chiave API. OAuth di OpenRouter è un flusso di accesso PKCE che emette una chiave API OpenRouter, pertanto OpenClaw memorizza il risultato nello stesso profilo di autenticazione tramite chiave API openrouter:default utilizzato per la configurazione manuale della chiave API.

Per accedere o ruotare la chiave memorizzata in un'installazione esistente senza ripetere l'intera configurazione iniziale:

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

Nelle richieste OpenRouter verificate (https://openrouter.ai/api/v1), OpenClaw aggiunge le intestazioni documentate da OpenRouter per l'attribuzione dell'applicazione:

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