Vai al contenuto principale
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

1

Esegui l'onboarding OAuth

openclaw onboard --auth-choice openrouter-oauth
OpenClaw apre il flusso di accesso dal browser di OpenRouter, scambia il codice PKCE con una chiave API OpenRouter e archivia quella chiave nel profilo di autenticazione OpenRouter predefinito. Sugli host remoti/headless, OpenClaw stampa l’URL di accesso e chiede di incollare l’URL di reindirizzamento dopo l’accesso.
2

(Facoltativo) Passa a un modello specifico

L’onboarding usa per impostazione predefinita openrouter/auto. Scegli un modello concreto in seguito:
openclaw models set openrouter/<provider>/<model>

​
Esempio di configurazione

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

​
Riferimenti dei modelli

I riferimenti dei modelli seguono il pattern openrouter/<provider>/<model>. Per l’elenco completo di provider e modelli disponibili, consulta /concepts/model-providers.
Esempi di fallback inclusi:
Riferimento modelloNote
openrouter/autoInstradamento automatico OpenRouter
openrouter/openrouter/fusionRouter OpenRouter Fusion
openrouter/moonshotai/kimi-k2.6Kimi K2.6 tramite MoonshotAI
openrouter/moonshotai/kimi-k2.5Kimi K2.5 tramite MoonshotAI

​
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:
HeaderValore
HTTP-Refererhttps://openclaw.ai
X-OpenRouter-TitleOpenClaw
X-OpenRouter-Categoriescli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent
Se reindirizzi il provider OpenRouter a un altro proxy o URL di base, OpenClaw non inietta quegli header specifici di OpenRouter né i marker di cache Anthropic.

​
Configurazione avanzata

Il caching delle risposte OpenRouter è opt-in. Abilitalo per ogni modello OpenRouter con i parametri del modello:
{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}
OpenClaw invia X-OpenRouter-Cache: true e, quando configurato, X-OpenRouter-Cache-TTL. responseCacheClear: true forza un aggiornamento per la richiesta corrente e archivia la risposta sostitutiva. Sono accettati anche gli alias snake_case (response_cache, response_cache_ttl_seconds e response_cache_clear).Questo è separato dal caching dei prompt del provider e dai marker Anthropic cache_control di OpenRouter. Viene applicato solo su route openrouter.ai verificate, non su URL di base di proxy personalizzati.
Sulle route OpenRouter verificate, i riferimenti dei modelli Anthropic mantengono i marker Anthropic cache_control specifici di OpenRouter che OpenClaw usa per un migliore riutilizzo della cache dei prompt sui blocchi prompt di sistema/sviluppatore.
Sulle route OpenRouter verificate, i riferimenti ai modelli Anthropic con ragionamento abilitato rimuovono i turni finali di prefill dell’assistente prima che la richiesta raggiunga OpenRouter, in linea con il requisito di Anthropic secondo cui le conversazioni con ragionamento terminano con un turno utente.
Sulle route non auto supportate, OpenClaw mappa il livello di thinking selezionato ai payload di ragionamento del proxy OpenRouter. Gli hint di modello non supportati e openrouter/auto saltano quell’iniezione di ragionamento. Hunter Alpha salta inoltre il ragionamento del proxy per riferimenti a modelli configurati obsoleti perché OpenRouter potrebbe restituire testo di risposta finale nei campi di ragionamento per quella route ritirata.
Sulle route OpenRouter verificate, openrouter/deepseek/deepseek-v4-flash e openrouter/deepseek/deepseek-v4-pro compilano il reasoning_content mancante nei turni assistente riprodotti, così le conversazioni con thinking/strumenti mantengono la forma di follow-up richiesta da DeepSeek V4. OpenClaw invia valori di reasoning.effort supportati da OpenRouter per queste route; i livelli inferiori non off vengono mappati a high e gli override max obsoleti vengono mappati a xhigh.
OpenRouter passa ancora attraverso il percorso in stile proxy compatibile con OpenAI, quindi la modellazione nativa delle richieste solo OpenAI, come serviceTier, Responses store, i payload di compatibilità del ragionamento OpenAI e gli hint della cache dei prompt non viene inoltrata.
I riferimenti OpenRouter basati su Gemini rimangono sul percorso proxy-Gemini: OpenClaw mantiene lì la sanificazione delle firme di pensiero Gemini, ma non abilita la convalida nativa del replay Gemini né le riscritture bootstrap.
OpenRouter supporta un oggetto richiesta provider per il routing del provider sottostante. Configura una policy predefinita per tutte le richieste OpenRouter di modelli di testo con models.providers.openrouter.params.provider:
{
  models: {
    providers: {
      openrouter: {
        params: {
          provider: {
            sort: "latency",
            require_parameters: true,
            data_collection: "deny",
          },
        },
      },
    },
  },
}
OpenClaw inoltra quell’oggetto a OpenRouter come payload provider della richiesta. Usa i campi snake_case documentati da OpenRouter, inclusi sort, only, ignore, order, allow_fallbacks, require_parameters, data_collection, quantizations, max_price, preferred_max_latency, preferred_min_throughput, zdr e enforce_distillable_text.I parametri per modello sovrascrivono comunque l’oggetto di routing valido per tutto il provider:
{
  agents: {
    defaults: {
      models: {
        "openrouter/anthropic/claude-sonnet-4-6": {
          params: {
            provider: {
              order: ["anthropic"],
              allow_fallbacks: false,
            },
          },
        },
      },
    },
  },
}
Questo si applica solo alle route OpenRouter chat-completions. Le route dirette Anthropic, Google, OpenAI o provider personalizzati ignorano i parametri di routing OpenRouter.

​
Correlati

Selezione del modello

Scelta di provider, riferimenti ai modelli e comportamento di failover.

Riferimento di configurazione

Riferimento completo di configurazione per agenti, modelli e provider.