Passer au contenu principal
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

1

Exécuter la configuration initiale OAuth

openclaw onboard --auth-choice openrouter-oauth
OpenClaw ouvre le flux de connexion par navigateur d’OpenRouter, échange le code PKCE contre une clé API OpenRouter, puis stocke cette clé dans le profil d’authentification OpenRouter par défaut. Sur les hôtes distants/sans interface graphique, OpenClaw affiche l’URL de connexion et vous demande de coller l’URL de redirection après vous être connecté.
2

(Facultatif) Passer à un modèle spécifique

La configuration initiale utilise openrouter/auto par défaut. Choisissez un modèle concret plus tard :
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

Les références de modèle suivent le modèle openrouter/<provider>/<model>. Pour la liste complète des fournisseurs et modèles disponibles, consultez /concepts/model-providers.
Exemples de secours intégrés :
Référence de modèleNotes
openrouter/autoRoutage automatique OpenRouter
openrouter/openrouter/fusionRouteur OpenRouter Fusion
openrouter/moonshotai/kimi-k2.6Kimi K2.6 via MoonshotAI
openrouter/moonshotai/kimi-k2.5Kimi K2.5 via MoonshotAI

​
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 :
En-têteValeur
HTTP-Refererhttps://openclaw.ai
X-OpenRouter-TitleOpenClaw
X-OpenRouter-Categoriescli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent
Si vous redirigez le fournisseur OpenRouter vers un autre proxy ou une autre URL de base, OpenClaw n’injecte pas ces en-têtes propres à OpenRouter ni les marqueurs de cache Anthropic.

​
Configuration avancée

La mise en cache des réponses OpenRouter est optionnelle. Activez-la par modèle OpenRouter avec les paramètres de modèle :
{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}
OpenClaw envoie X-OpenRouter-Cache: true et, lorsque configuré, X-OpenRouter-Cache-TTL. responseCacheClear: true force un rafraîchissement pour la requête actuelle et stocke la réponse de remplacement. Les alias snake_case (response_cache, response_cache_ttl_seconds et response_cache_clear) sont également acceptés.Cela est distinct de la mise en cache des invites du fournisseur et des marqueurs Anthropic cache_control d’OpenRouter. Cela ne s’applique qu’aux routes openrouter.ai vérifiées, pas aux URL de base de proxy personnalisées.
Sur les routes OpenRouter vérifiées, les références de modèles Anthropic conservent les marqueurs Anthropic cache_control propres à OpenRouter qu’OpenClaw utilise pour améliorer la réutilisation du cache d’invite sur les blocs d’invite système/développeur.
Sur les routes OpenRouter vérifiées, les références de modèles Anthropic avec le raisonnement activé suppriment les tours finaux de préremplissage assistant avant que la requête n’atteigne OpenRouter, conformément à l’exigence d’Anthropic selon laquelle les conversations de raisonnement doivent se terminer par un tour utilisateur.
Sur les routes non-auto prises en charge, OpenClaw mappe le niveau de réflexion sélectionné vers les charges utiles de raisonnement du proxy OpenRouter. Les indications de modèles non prises en charge et openrouter/auto ignorent cette injection de raisonnement. Hunter Alpha ignore aussi le raisonnement proxy pour les références de modèles configurées obsolètes, car OpenRouter pouvait renvoyer le texte de réponse finale dans les champs de raisonnement pour cette route retirée.
Sur les routes OpenRouter vérifiées, openrouter/deepseek/deepseek-v4-flash et openrouter/deepseek/deepseek-v4-pro remplissent le reasoning_content manquant sur les tours assistant relus afin que les conversations avec réflexion/outils conservent la forme de suivi requise par DeepSeek V4. OpenClaw envoie les valeurs reasoning.effort prises en charge par OpenRouter pour ces routes ; les niveaux non désactivés inférieurs sont mappés vers high, et les remplacements max obsolètes sont mappés vers xhigh.
OpenRouter passe toujours par le chemin proxy compatible avec OpenAI ; la mise en forme native des requêtes propres à OpenAI, comme serviceTier, store de Responses, les charges utiles de compatibilité du raisonnement OpenAI et les indications de cache de prompt, n’est donc pas transmise.
Les références OpenRouter adossées à Gemini restent sur le chemin proxy-Gemini : OpenClaw conserve l’assainissement des signatures de pensée Gemini à cet endroit, mais n’active pas la validation de relecture Gemini native ni les réécritures d’amorçage.
OpenRouter prend en charge un objet de requête provider pour le routage du fournisseur sous-jacent. Configurez une stratégie par défaut pour toutes les requêtes de modèles de texte OpenRouter avec models.providers.openrouter.params.provider :
{
  models: {
    providers: {
      openrouter: {
        params: {
          provider: {
            sort: "latency",
            require_parameters: true,
            data_collection: "deny",
          },
        },
      },
    },
  },
}
OpenClaw transmet cet objet à OpenRouter comme charge utile provider de la requête. Utilisez les champs snake_case documentés d’OpenRouter, notamment sort, only, ignore, order, allow_fallbacks, require_parameters, data_collection, quantizations, max_price, preferred_max_latency, preferred_min_throughput, zdr et enforce_distillable_text.Les paramètres par modèle remplacent toujours l’objet de routage valable pour tout le fournisseur :
{
  agents: {
    defaults: {
      models: {
        "openrouter/anthropic/claude-sonnet-4-6": {
          params: {
            provider: {
              order: ["anthropic"],
              allow_fallbacks: false,
            },
          },
        },
      },
    },
  },
}
Cela s’applique uniquement aux routes de chat completions OpenRouter. Les routes directes Anthropic, Google, OpenAI ou de fournisseurs personnalisés ignorent les paramètres de routage OpenRouter.

​
Articles connexes

Sélection des modèles

Choix des fournisseurs, des références de modèles et du comportement de basculement.

Référence de configuration

Référence complète de configuration pour les agents, les modèles et les fournisseurs.