OpenRouter

OpenRouter enruta solicitudes a muchos modelos mediante una API y una clave. Es compatible con OpenAI, por lo que OpenClaw se comunica con él mediante el mismo transporte de estilo openai-completions utilizado para otros proveedores proxy.

Primeros pasos

OAuth
Clave de API

Ejecutar la incorporación mediante OAuth

openclaw onboard --auth-choice openrouter-oauth

OpenClaw abre el flujo de inicio de sesión de OpenRouter en el navegador (PKCE), intercambia el código por una clave de API de OpenRouter y la almacena en el perfil de autenticación predeterminado de OpenRouter. En hosts remotos o sin interfaz gráfica, OpenClaw muestra la URL de inicio de sesión y solicita que se pegue la URL de redirección después de iniciar sesión.

(Opcional) Cambiar a un modelo específico

La incorporación usa openrouter/auto de forma predeterminada. Se puede elegir un modelo concreto más adelante:

openclaw models set openrouter/<provider>/<model>

Obtener la clave de API

Cree una clave de API en openrouter.ai/keys.

Ejecutar la incorporación mediante clave de API

openclaw onboard --auth-choice openrouter-api-key

(Opcional) Cambiar a un modelo específico

La incorporación usa openrouter/auto de forma predeterminada. Se puede elegir un modelo concreto más adelante:

openclaw models set openrouter/<provider>/<model>

Ejemplo de configuración

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

Referencias de modelos

Las referencias de modelos siguen el patrón openrouter/<provider>/<model>. Para consultar la lista completa de proveedores y modelos disponibles, véase /concepts/model-providers.

Modelos alternativos incluidos, utilizados cuando el descubrimiento del catálogo en vivo no está disponible:

Referencia del modelo	Notas
`openrouter/auto`	Enrutamiento automático de OpenRouter
`openrouter/moonshotai/kimi-k2.6`	Kimi K2.6 mediante MoonshotAI
`openrouter/moonshotai/kimi-k2.5`	Kimi K2.5 mediante MoonshotAI

Cualquier otra referencia openrouter/<provider>/<model>, incluida openrouter/openrouter/fusion (véase Enrutador Fusion), se resuelve dinámicamente mediante el catálogo de modelos en vivo de OpenRouter.

Generación de imágenes

OpenRouter puede respaldar la herramienta image_generate. Configure un modelo de imágenes de OpenRouter en agents.defaults.mediaModels.image:

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
        timeoutMs: 180_000,
      },
    },
  },
}

OpenClaw envía solicitudes de imágenes a la API de imágenes de finalizaciones de chat de OpenRouter con modalities: ["image", "text"]. Los modelos de imágenes Gemini reciben además indicaciones aspectRatio y resolution mediante image_config de OpenRouter; los demás modelos de imágenes no. Utilice agents.defaults.mediaModels.image.timeoutMs para modelos más lentos; el valor timeoutMs por llamada de la herramienta image_generate sigue teniendo prioridad.

Generación de vídeo

OpenRouter puede respaldar la herramienta video_generate mediante su API asíncrona /videos. Configure un modelo de vídeo de OpenRouter en agents.defaults.mediaModels.video:

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

OpenClaw envía tareas de texto a vídeo e imagen a vídeo, consulta periódicamente el polling_url devuelto y descarga el vídeo terminado desde unsigned_urls de OpenRouter o desde el endpoint de contenido de la tarea. Las imágenes de referencia se usan de forma predeterminada como fotogramas iniciales o finales; las imágenes etiquetadas con reference_image se envían en su lugar como referencias de entrada. El valor predeterminado incluido google/veo-3.1-fast admite duraciones de 4/6/8 segundos, resoluciones 720P/1080P y relaciones de aspecto 16:9/9:16. No se admite la conversión de vídeo a vídeo: la API ascendente solo acepta referencias de texto e imágenes.

Generación de música

OpenRouter puede respaldar la herramienta music_generate mediante la salida de audio de finalizaciones de chat. Configure un modelo de audio de OpenRouter en agents.defaults.mediaModels.music:

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

El proveedor de música de OpenRouter incluido usa google/lyria-3-pro-preview de forma predeterminada y también expone google/lyria-3-clip-preview. OpenClaw envía modalities: ["text", "audio"], transmite la respuesta, recopila los fragmentos de audio y guarda el resultado como contenido multimedia generado para entregarlo al canal. Los modelos Lyria aceptan una imagen de referencia mediante el parámetro compartido music_generate image=.... El audio en streaming, la conservación de la transcripción y el sobre de eventos SSE derivado están limitados por agents.defaults.mediaMaxMb (el límite de audio predeterminado es de 16 MB).

Texto a voz

OpenRouter puede actuar como proveedor de TTS mediante su endpoint /audio/speech compatible con OpenAI.

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

Si se omite tts.providers.openrouter.apiKey, TTS recurre a models.providers.openrouter.apiKey y después a OPENROUTER_API_KEY.

Voz a texto (audio entrante)

OpenRouter puede transcribir archivos adjuntos entrantes de voz o audio mediante la ruta compartida tools.media.audio, utilizando su endpoint de STT (/audio/transcriptions). Esto se aplica a cualquier plugin de canal que reenvíe voz o audio entrante a la comprobación preliminar de comprensión multimedia.

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

OpenClaw envía las solicitudes de STT de OpenRouter como JSON con audio en base64 en input_audio (el contrato de STT de OpenRouter), no como cargas de formularios multipart de OpenAI.

Enrutador Fusion

OpenRouter Fusion envía una referencia de modelo de OpenClaw a varios modelos de OpenRouter en paralelo, hace que OpenRouter evalúe sus respuestas y devuelve una respuesta final mediante el endpoint habitual de OpenRouter. El slug del modelo ascendente es openrouter/fusion, por lo que la referencia de modelo de OpenClaw contiene tanto el prefijo del proveedor de OpenClaw como el espacio de nombres ascendente de OpenRouter:

openclaw models set openrouter/openrouter/fusion

Configure el panel y el evaluador de Fusion mediante params.extraBody del modelo; esos campos se reenvían directamente al cuerpo de la solicitud de finalizaciones de chat de OpenRouter. Fusion funciona con la incorporación mediante OAuth o clave de API; si se utiliza OAuth, omita la línea env.OPENROUTER_API_KEY siguiente.

{
  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 es el panel paralelo; model en la configuración del plugin Fusion es el modelo evaluador. No establezca tool_choice de nivel superior en "required" durante turnos normales del agente o del chat para intentar forzar Fusion: los turnos de OpenClaw pueden incluir sus propias definiciones de herramientas y una elección obligatoria de herramienta de nivel superior puede seleccionar una de ellas en lugar del enrutador Fusion. Cuando esta configuración del plugin Fusion está presente, OpenClaw añade una nota depurada al prompt del sistema que enumera los modelos de análisis configurados y el modelo evaluador, para que el agente pueda responder preguntas sobre su propio panel Fusion. Los demás campos extraBody no se copian al prompt. Fusion es más lento por diseño: OpenRouter distribuye el prompt entre varios modelos de análisis y después ejecuta un paso de evaluación y síntesis, por lo que la latencia es mayor que la de una solicitud directa a un único modelo. Utilícelo para respuestas deliberadas y de alta calidad o rutas de escalamiento, no como opción predeterminada cuando la latencia sea crítica. Mantenga el panel pequeño y elija modelos de análisis y evaluación más rápidos para obtener respuestas más rápidas. Pruebe una referencia configurada con una llamada local única:

openclaw infer model run --local \
  --model openrouter/openrouter/fusion \
  --prompt "Responde exactamente con: FUSION_OK" \
  --json

Autenticación y encabezados

OpenRouter utiliza un token Bearer procedente de la clave de API. OAuth de OpenRouter es un flujo de inicio de sesión PKCE que emite una clave de API de OpenRouter, por lo que OpenClaw almacena el resultado en el mismo perfil de autenticación mediante clave de API openrouter:default utilizado por la configuración manual de la clave de API. Para iniciar sesión o rotar la clave almacenada en una instalación existente sin volver a ejecutar toda la incorporación:

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

En las solicitudes verificadas de OpenRouter (https://openrouter.ai/api/v1), OpenClaw añade los encabezados documentados de atribución de aplicaciones de OpenRouter:

Encabezado	Valor
`HTTP-Referer`	`https://openclaw.ai`
`X-OpenRouter-Title`	`OpenClaw`
`X-OpenRouter-Categories`	`cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent`

Si se redirige el proveedor de OpenRouter a otro proxy o URL base, OpenClaw no inyecta esos encabezados específicos de OpenRouter ni los marcadores de caché de Anthropic.

Configuración avanzada

Almacenamiento en caché de respuestas

El almacenamiento en caché de respuestas de OpenRouter es opcional. Actívelo para cada modelo:

{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}

OpenClaw envía X-OpenRouter-Cache: true y, cuando está configurado, X-OpenRouter-Cache-TTL. responseCacheClear: true fuerza una actualización para la solicitud actual y almacena la respuesta de sustitución. Se aceptan alias en snake_case (response_cache, response_cache_ttl_seconds, response_cache_clear), así como responseCacheTtl / response_cache_ttl sin el sufijo Seconds.Esto es independiente del almacenamiento en caché de prompts del proveedor y de los marcadores cache_control de Anthropic de OpenRouter. Solo se aplica a rutas verificadas openrouter.ai, no a URL base de proxies personalizados.

Marcadores de caché de Anthropic

En las rutas verificadas de OpenRouter, las referencias de modelos Anthropic conservan los marcadores cache_control de Anthropic de OpenRouter para mejorar la reutilización de la caché de prompts en los bloques de prompts del sistema o del desarrollador.

Prefill de razonamiento de Anthropic

En las rutas verificadas de OpenRouter, las referencias de modelos Anthropic con el razonamiento habilitado descartan los turnos finales de prefill del asistente antes de que la solicitud llegue a OpenRouter, de acuerdo con el requisito de Anthropic de que las conversaciones de razonamiento terminen con un turno del usuario.

Inyección de pensamiento / razonamiento

En las rutas compatibles que no son auto, OpenClaw asigna el nivel de pensamiento seleccionado a las cargas útiles de razonamiento del proxy de OpenRouter. openrouter/auto y las indicaciones de modelos no compatibles omiten esa inyección. Las referencias obsoletas openrouter/hunter-alpha también la omiten, porque OpenRouter podría devolver el texto de la respuesta final en los campos de razonamiento de esa ruta retirada.

Reproducción del razonamiento de DeepSeek V4

En las rutas verificadas de OpenRouter, openrouter/deepseek/deepseek-v4-flash y openrouter/deepseek/deepseek-v4-pro completan los reasoning_content que faltan en los turnos reproducidos del asistente, lo que mantiene las conversaciones de pensamiento y herramientas con la estructura de seguimiento requerida por DeepSeek V4. OpenClaw envía los valores reasoning.effort compatibles con OpenRouter para estas rutas: xhigh/max se asignan a xhigh; cualquier otro nivel distinto de desactivado se asigna a high.

Adaptación de solicitudes exclusiva de OpenAI

OpenRouter se ejecuta mediante la ruta compatible con OpenAI de estilo proxy, por lo que no se reenvía la adaptación de solicitudes exclusiva del OpenAI nativo, como serviceTier, store de Responses, las cargas útiles de compatibilidad con el razonamiento de OpenAI y las indicaciones de caché de prompts.

Rutas respaldadas por Gemini

Las referencias de OpenRouter respaldadas por Gemini permanecen en la ruta proxy de Gemini: OpenClaw mantiene allí la depuración de firmas de pensamiento de Gemini, pero no habilita la validación de reproducción nativa de Gemini ni las reescrituras de arranque.

Metadatos de enrutamiento de proveedores

OpenRouter admite un objeto de solicitud provider para el enrutamiento del proveedor subyacente. Configure una política predeterminada para todas las solicitudes de modelos de texto de OpenRouter con models.providers.openrouter.params.provider:

{
  models: {
    providers: {
      openrouter: {
        params: {
          provider: {
            sort: "latency",
            require_parameters: true,
            data_collection: "deny",
          },
        },
      },
    },
  },
}

OpenClaw reenvía ese objeto a OpenRouter como carga útil provider de la solicitud. Utilice los campos snake_case documentados de OpenRouter, incluidos sort, only, ignore, order, allow_fallbacks, require_parameters, data_collection, quantizations, max_price, preferred_max_latency, preferred_min_throughput, zdr y enforce_distillable_text.Los parámetros específicos de cada modelo prevalecen sobre el objeto de enrutamiento general del proveedor:

{
  agents: {
    defaults: {
      models: {
        "openrouter/anthropic/claude-sonnet-4-6": {
          params: {
            provider: {
              order: ["anthropic"],
              allow_fallbacks: false,
            },
          },
        },
      },
    },
  },
}

Esto solo se aplica a las rutas de finalización de chat de OpenRouter. Las rutas directas de Anthropic, Google, OpenAI o proveedores personalizados ignoran los parámetros de enrutamiento de OpenRouter.

Contenido relacionado

Selección de modelos

Elección de proveedores, referencias de modelos y comportamiento de conmutación por error.

Referencia de configuración

Referencia completa de configuración para agentes, modelos y proveedores.

Overview

Concepts and configuration

Providers

Primeros pasos

Ejemplo de configuración

Referencias de modelos

Generación de imágenes

Generación de vídeo

Generación de música

Texto a voz

Voz a texto (audio entrante)

Enrutador Fusion

Autenticación y encabezados

Configuración avanzada

Contenido relacionado

Selección de modelos

Referencia de configuración

​Primeros pasos

​Ejemplo de configuración

​Referencias de modelos

​Generación de imágenes

​Generación de vídeo

​Generación de música

​Texto a voz

​Voz a texto (audio entrante)

​Enrutador Fusion

​Autenticación y encabezados

​Configuración avanzada

​Contenido relacionado

Selección de modelos

Referencia de configuración

Primeros pasos

Ejemplo de configuración

Referencias de modelos

Generación de imágenes

Generación de vídeo

Generación de música

Texto a voz

Voz a texto (audio entrante)

Enrutador Fusion

Autenticación y encabezados

Configuración avanzada

Contenido relacionado