OpenRouter

OpenRouter fournit une API unifiée qui achemine les requêtes vers de nombreux modèles derrière un seul endpoint et une seule clé API. Elle est compatible avec OpenAI, donc la plupart des SDK OpenAI fonctionnent en changeant l’URL de base.

Premiers pas

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>

Exemple de configuration

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

Références de modèle

Exemples de secours intégrés :

Génération d’images

OpenRouter peut également servir de backend à l’outil image_generate. Utilisez un modèle d’image OpenRouter sous 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 envoie les requêtes d’image à l’API d’images des complétions de chat d’OpenRouter avec modalities: ["image", "text"]. Les modèles d’image Gemini reçoivent les indications aspectRatio et resolution prises en charge via image_config d’OpenRouter. Utilisez agents.defaults.imageGenerationModel.timeoutMs pour les modèles d’image OpenRouter plus lents ; le paramètre timeoutMs par appel de l’outil image_generate reste prioritaire.

Génération de vidéos

OpenRouter peut également servir de backend à l’outil video_generate via son API asynchrone /videos. Utilisez un modèle vidéo OpenRouter sous agents.defaults.videoGenerationModel :

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

OpenClaw soumet à OpenRouter les tâches de texte vers vidéo et d’image vers vidéo, interroge le polling_url renvoyé, puis télécharge la vidéo terminée depuis les unsigned_urls d’OpenRouter ou l’endpoint documenté du contenu de la tâche. Les images de référence sont envoyées par défaut comme images de première/dernière image ; les images marquées avec reference_image sont envoyées comme références d’entrée OpenRouter. Le paramètre par défaut intégré google/veo-3.1-fast annonce les durées actuellement prises en charge de 4/6/8 secondes, les résolutions 720P/1080P et les formats d’image 16:9/9:16. La vidéo vers vidéo n’est pas enregistrée pour OpenRouter, car l’API amont de génération vidéo accepte actuellement le texte et les références d’image.

Génération de musique

OpenRouter peut également servir de backend à l’outil music_generate via la sortie audio des complétions de chat. Utilisez un modèle audio OpenRouter sous agents.defaults.musicGenerationModel :

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

Le fournisseur de musique OpenRouter intégré utilise par défaut google/lyria-3-pro-preview et expose également google/lyria-3-clip-preview. OpenClaw envoie modalities: ["text", "audio"], active le streaming, collecte les fragments audio diffusés en streaming, puis enregistre le résultat comme média généré pour la livraison dans les canaux. Les images de référence sont acceptées pour les modèles Lyria via le paramètre partagé music_generate image=....

Synthèse vocale

OpenRouter peut également être utilisé comme fournisseur TTS via son endpoint /audio/speech compatible avec OpenAI.

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

Si messages.tts.providers.openrouter.apiKey est omis, la synthèse vocale réutilise models.providers.openrouter.apiKey, puis OPENROUTER_API_KEY.

Transcription vocale (audio entrant)

OpenRouter peut transcrire les pièces jointes vocales/audio entrantes via le chemin partagé tools.media.audio en utilisant son point de terminaison STT (/audio/transcriptions). Cela s’applique à tout Plugin de canal qui transmet la voix/l’audio entrant à la pré-vérification de compréhension des médias.

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

OpenClaw envoie les requêtes STT OpenRouter au format JSON avec l’audio en base64 sous input_audio (contrat STT OpenRouter), et non sous forme de téléversements de formulaires OpenAI multipart.

Routeur Fusion

Utilisez OpenRouter Fusion lorsque vous voulez qu’une seule référence de modèle OpenClaw interroge plusieurs modèles OpenRouter en parallèle, qu’OpenRouter juge leurs réponses et renvoie une réponse finale unique via le point de terminaison normal du fournisseur OpenRouter. Comme le slug du modèle amont est openrouter/fusion, la référence de modèle OpenClaw inclut à la fois le préfixe du fournisseur OpenClaw et l’espace de noms OpenRouter amont :

openclaw models set openrouter/openrouter/fusion

Configurez le panel et le juge de Fusion via le params.extraBody du modèle. Ces champs sont transmis dans le corps de la requête de complétion de chat OpenRouter. Fusion fonctionne avec l’onboarding OAuth OpenRouter ou l’onboarding par clé d’API ; si vous utilisez OAuth, omettez la ligne env.OPENROUTER_API_KEY de l’exemple ci-dessous.

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

La liste analysis_models est le panel parallèle, et model dans la configuration du plugin Fusion est le modèle juge. Ne définissez pas tool_choice au niveau supérieur sur "required" dans les tours normaux d’agent/chat OpenClaw pour tenter de forcer Fusion ; les tours OpenClaw peuvent inclure des définitions d’outils OpenClaw, et un choix d’outil obligatoire au niveau supérieur peut exiger l’un de ces outils plutôt que le routeur Fusion. Lorsque cette configuration du Plugin Fusion est présente, OpenClaw ajoute aussi une note d’invite système assainie avec les modèles d’analyse configurés et le modèle juge, afin que l’agent puisse répondre aux questions sur son panel Fusion actuel. Les autres champs extraBody ne sont pas copiés dans l’invite.

Fusion est plus lent par conception. OpenRouter peut envoyer la même invite OpenClaw à plusieurs modèles d’analyse, puis exécuter une étape finale de jugement/synthèse ; la latence est donc généralement plus élevée qu’avec une requête directe à un seul modèle. Utilisez Fusion pour des réponses réfléchies et de haute qualité ou pour des chemins d’escalade, pas comme valeur par défaut pour un chat sensible à la latence. Pour des réponses plus rapides, gardez le panel petit et choisissez des modèles d’analyse et de jugement plus rapides.

Testez la référence configurée avec un appel local ponctuel au modèle :

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

Authentification et en-têtes

OpenRouter utilise en interne un jeton Bearer avec votre clé d’API. OAuth OpenRouter est un flux de connexion PKCE qui émet une clé d’API OpenRouter ; OpenClaw stocke donc le résultat comme le même profil d’authentification par clé d’API openrouter:default que celui utilisé par le chemin de configuration manuelle par clé d’API.

Pour une installation existante, connectez-vous ou faites tourner la clé OpenRouter stockée sans relancer l’onboarding complet :

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

Utilisez openclaw models auth login --provider openrouter --method api-key lorsque vous voulez coller une clé créée manuellement sur OpenRouter.

Sur les requêtes OpenRouter réelles (https://openrouter.ai/api/v1), OpenClaw ajoute aussi les en-têtes d’attribution d’application documentés par OpenRouter :

Configuration avancée

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

Articles connexes