Proveedores de modelos

Referencia para proveedores de LLM/modelos (no canales de chat como WhatsApp/Telegram). Para las reglas de selección de modelos, consulta Modelos.

# Reglas rápidas

# Comportamiento de proveedor propiedad del plugin

La mayor parte de la lógica específica del proveedor vive en plugins de proveedor (registerProvider(...)), mientras OpenClaw mantiene el bucle de inferencia genérico. Los plugins son propietarios de la incorporación, los catálogos de modelos, el mapeo de variables de entorno de autenticación, la normalización de transporte/configuración, la limpieza de esquemas de herramientas, la clasificación de conmutación por error, la actualización de OAuth, los informes de uso, los perfiles de pensamiento/razonamiento y más.

La lista completa de hooks del SDK de proveedor y ejemplos de plugins incluidos está en Plugins de proveedor. Un proveedor que necesita un ejecutor de solicitudes totalmente personalizado es una superficie de extensión separada y más profunda.

# Rotación de claves de API

# Proveedores integrados (catálogo pi-ai)

OpenClaw se distribuye con el catálogo pi-ai. Estos proveedores no requieren configuración de models.providers; solo configura la autenticación y elige un modelo.

# OpenAI

• Proveedor: openai
• Autenticación: OPENAI_API_KEY
• Rotación opcional: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, más OPENCLAW_LIVE_OPENAI_KEY (sobrescritura única)
• Modelos de ejemplo: openai/gpt-5.5, openai/gpt-5.4-mini
• Verifica la disponibilidad de cuenta/modelo con openclaw models list --provider openai si una instalación específica o clave de API se comporta de manera diferente.
• CLI: openclaw onboard --auth-choice openai-api-key
• El transporte predeterminado es auto (WebSocket primero, respaldo SSE)
• Sobrescribe por modelo mediante agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket" o "auto")
• El calentamiento de WebSocket de OpenAI Responses está habilitado de forma predeterminada mediante params.openaiWsWarmup (true/false)
• El procesamiento prioritario de OpenAI se puede habilitar mediante agents.defaults.models["openai/<model>"].params.serviceTier
• /fast y params.fastMode asignan solicitudes directas de Responses openai/* a service_tier=priority en api.openai.com
• Usa params.serviceTier cuando quieras un nivel explícito en lugar del interruptor compartido /fast
• Los encabezados ocultos de atribución de OpenClaw (originator, version, User-Agent) se aplican solo en tráfico nativo de OpenAI hacia api.openai.com, no a proxies genéricos compatibles con OpenAI
• Las rutas nativas de OpenAI también conservan store de Responses, sugerencias de caché de prompts y conformación de payload compatible con razonamiento de OpenAI; las rutas de proxy no
• openai/gpt-5.3-codex-spark se suprime intencionalmente en OpenClaw porque las solicitudes activas a la API de OpenAI lo rechazan y el catálogo actual de Codex no lo expone

{
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

# Anthropic

• Proveedor: anthropic
• Autenticación: ANTHROPIC_API_KEY
• Rotación opcional: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, más OPENCLAW_LIVE_ANTHROPIC_KEY (sobrescritura única)
• Modelo de ejemplo: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Las solicitudes públicas directas de Anthropic admiten el interruptor compartido /fast y params.fastMode, incluido el tráfico autenticado con clave de API y OAuth enviado a api.anthropic.com; OpenClaw lo asigna a service_tier de Anthropic (auto frente a standard_only)
• La configuración preferida de Claude CLI conserva la referencia de modelo canónica y selecciona el backend de CLI por separado: anthropic/claude-opus-4-7 con agents.defaults.agentRuntime.id: "claude-cli". Las referencias heredadas claude-cli/claude-opus-4-7 siguen funcionando por compatibilidad.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

# OAuth de OpenAI Codex

• Proveedor: openai-codex
• Autenticación: OAuth (ChatGPT)
• Referencia de modelo de PI: openai-codex/gpt-5.5
• Referencia de arnés nativo de servidor de aplicación de Codex: openai/gpt-5.5 con agents.defaults.agentRuntime.id: "codex"
• Documentación del arnés nativo de servidor de aplicación de Codex: arnés de Codex
• Referencias de modelos heredadas: codex/gpt-*
• Límite de plugin: openai-codex/* carga el plugin de OpenAI; el plugin nativo de servidor de aplicación de Codex se selecciona solo mediante el runtime del arnés de Codex o referencias heredadas codex/*.
• CLI: openclaw onboard --auth-choice openai-codex o openclaw models auth login --provider openai-codex
• El transporte predeterminado es auto (WebSocket primero, respaldo SSE)
• Sobrescribe por modelo de PI mediante agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket" o "auto")
• params.serviceTier también se reenvía en solicitudes nativas de Codex Responses (chatgpt.com/backend-api)
• Los encabezados ocultos de atribución de OpenClaw (originator, version, User-Agent) solo se adjuntan en tráfico nativo de Codex hacia chatgpt.com/backend-api, no a proxies genéricos compatibles con OpenAI
• Comparte la misma configuración de interruptor /fast y params.fastMode que openai/* directo; OpenClaw lo asigna a service_tier=priority
• openai-codex/gpt-5.5 usa el contextWindow = 400000 nativo del catálogo de Codex y el runtime predeterminado contextTokens = 272000; sobrescribe el límite de runtime con models.providers.openai-codex.models[].contextTokens
• Nota de política: OAuth de OpenAI Codex es compatible explícitamente con herramientas/flujos de trabajo externos como OpenClaw.
• Para la ruta común de suscripción más runtime nativo de Codex, inicia sesión con autenticación openai-codex, pero configura openai/gpt-5.5 más agents.defaults.agentRuntime.id: "codex".
• Usa openai-codex/gpt-5.5 solo cuando quieras la ruta OAuth/suscripción de Codex mediante PI; usa openai/gpt-5.5 sin la sobrescritura del runtime de Codex cuando tu configuración con clave de API y el catálogo local expongan la ruta de API pública.
• Las referencias antiguas openai-codex/gpt-5.1*, openai-codex/gpt-5.2* y openai-codex/gpt-5.3* se suprimen porque las cuentas OAuth de ChatGPT/Codex las rechazan; usa openai-codex/gpt-5.5 o la ruta nativa de runtime de Codex en su lugar.

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      agentRuntime: { id: "codex" },
    },
  },
}

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

# Otras opciones alojadas con estilo de suscripción

# OpenCode

• Autenticación: OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY)
• Proveedor de runtime Zen: opencode
• Proveedor de runtime Go: opencode-go
• Modelos de ejemplo: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen o openclaw onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

# Google Gemini (clave de API)

• Proveedor: google
• Autenticación: GEMINI_API_KEY
• Rotación opcional: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, alternativa GOOGLE_API_KEY y OPENCLAW_LIVE_GEMINI_KEY (anulación única)
• Modelos de ejemplo: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Compatibilidad: la configuración heredada de OpenClaw que usa google/gemini-3.1-flash-preview se normaliza a google/gemini-3-flash-preview
• Alias: se acepta google/gemini-3.1-pro y se normaliza al id de la API Gemini en vivo de Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Razonamiento: /think adaptive usa el razonamiento dinámico de Google. Gemini 3/3.1 omite un thinkingLevel fijo; Gemini 2.5 envía thinkingBudget: -1.
• Las ejecuciones directas de Gemini también aceptan agents.defaults.models["google/<model>"].params.cachedContent (o el heredado cached_content) para reenviar un identificador nativo del proveedor cachedContents/...; los aciertos de caché de Gemini aparecen como cacheRead de OpenClaw

# Google Vertex y Gemini CLI

• Proveedores: google-vertex, google-gemini-cli
• Autenticación: Vertex usa ADC de gcloud; Gemini CLI usa su flujo OAuth

Gemini CLI OAuth se incluye como parte del Plugin google incluido.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

Las respuestas JSON de Gemini CLI se analizan desde response; el uso recurre a stats, con stats.cached normalizado a cacheRead de OpenClaw.

# Z.AI (GLM)

• Proveedor: zai
• Autenticación: ZAI_API_KEY
• Modelo de ejemplo: zai/glm-5.1
• CLI: openclaw onboard --auth-choice zai-api-key
  • Alias: z.ai/* y z-ai/* se normalizan a zai/*
  • zai-api-key detecta automáticamente el endpoint correspondiente de Z.AI; zai-coding-global, zai-coding-cn, zai-global y zai-cn fuerzan una superficie específica

# Vercel AI Gateway

• Proveedor: vercel-ai-gateway
• Autenticación: AI_GATEWAY_API_KEY
• Modelos de ejemplo: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

# Kilo Gateway

• Proveedor: kilocode
• Autenticación: KILOCODE_API_KEY
• Modelo de ejemplo: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• URL base: https://api.kilo.ai/api/gateway/
• El catálogo alternativo estático incluye kilocode/kilo/auto; el descubrimiento en vivo de https://api.kilo.ai/api/gateway/models puede ampliar aún más el catálogo en tiempo de ejecución.
• El enrutamiento upstream exacto detrás de kilocode/kilo/auto pertenece a Kilo Gateway, no está codificado de forma rígida en OpenClaw.

Consulta /providers/kilocode para ver los detalles de configuración.

# Otros Plugins de proveedor incluidos

# Peculiaridades que conviene conocer

# Proveedores mediante models.providers (personalizados/URL base)

Usa models.providers (o models.json) para añadir proveedores personalizados o proxies compatibles con OpenAI/Anthropic.

Muchos de los plugins de proveedor incluidos a continuación ya publican un catálogo predeterminado. Usa entradas explícitas de models.providers.<id> solo cuando quieras sobrescribir la URL base, los encabezados o la lista de modelos predeterminados.

Las comprobaciones de capacidad de modelos del Gateway también leen metadatos explícitos de models.providers.<id>.models[]. Si un modelo personalizado o proxy acepta imágenes, define input: ["text", "image"] en ese modelo para que WebChat y las rutas de adjuntos originadas en nodos pasen imágenes como entradas nativas del modelo en vez de referencias multimedia solo de texto.

# Moonshot AI (Kimi)

Moonshot se distribuye como un plugin de proveedor incluido. Usa el proveedor integrado de forma predeterminada y añade una entrada explícita models.providers.moonshot solo cuando necesites sobrescribir la URL base o los metadatos del modelo:

• Proveedor: moonshot
• Autenticación: MOONSHOT_API_KEY
• Modelo de ejemplo: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key o openclaw onboard --auth-choice moonshot-api-key-cn

Id. de modelo Kimi K2:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.6" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],
      },
    },
  },
}

# Programación con Kimi

Kimi Coding usa el endpoint compatible con Anthropic de Moonshot AI:

• Proveedor: kimi
• Autenticación: KIMI_API_KEY
• Modelo de ejemplo: kimi/kimi-code

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-code" } },
  },
}

Legacy kimi/k2p5 sigue aceptándose como id de modelo de compatibilidad.

# Volcano Engine (Doubao)

Volcano Engine (火山引擎) proporciona acceso a Doubao y otros modelos en China.

• Proveedor: volcengine (codificación: volcengine-plan)
• Autenticación: VOLCANO_ENGINE_API_KEY
• Modelo de ejemplo: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

La incorporación usa de forma predeterminada la superficie de codificación, pero el catálogo general volcengine/* se registra al mismo tiempo.

En los selectores de modelos de incorporación/configuración, la opción de autenticación de Volcengine prefiere tanto las filas volcengine/* como volcengine-plan/*. Si esos modelos aún no están cargados, OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector vacío limitado al proveedor.

# BytePlus (Internacional)

BytePlus ARK proporciona acceso a los mismos modelos que Volcano Engine para usuarios internacionales.

• Proveedor: byteplus (codificación: byteplus-plan)
• Autenticación: BYTEPLUS_API_KEY
• Modelo de ejemplo: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

La incorporación usa de forma predeterminada la superficie de codificación, pero el catálogo general byteplus/* se registra al mismo tiempo.

En los selectores de modelos de incorporación/configuración, la opción de autenticación de BytePlus prefiere tanto las filas byteplus/* como byteplus-plan/*. Si esos modelos aún no están cargados, OpenClaw recurre al catálogo sin filtrar en lugar de mostrar un selector vacío limitado al proveedor.

# Synthetic

Synthetic proporciona modelos compatibles con Anthropic detrás del proveedor synthetic:

• Proveedor: synthetic
• Autenticación: SYNTHETIC_API_KEY
• Modelo de ejemplo: synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI: openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],
      },
    },
  },
}

# MiniMax

MiniMax se configura mediante models.providers porque usa endpoints personalizados:

• MiniMax OAuth (Global): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• Clave de API de MiniMax (Global): --auth-choice minimax-global-api
• Clave de API de MiniMax (CN): --auth-choice minimax-cn-api
• Autenticación: MINIMAX_API_KEY para minimax; MINIMAX_OAUTH_TOKEN o MINIMAX_API_KEY para minimax-portal

Consulta /providers/minimax para ver detalles de configuración, opciones de modelos y fragmentos de configuración.

División de capacidades propiedad del Plugin:

• Los valores predeterminados de texto/chat permanecen en minimax/MiniMax-M2.7
• La generación de imágenes es minimax/image-01 o minimax-portal/image-01
• La comprensión de imágenes es MiniMax-VL-01, propiedad del Plugin, en ambas rutas de autenticación de MiniMax
• La búsqueda web permanece en el id de proveedor minimax

# LM Studio

LM Studio se distribuye como un Plugin de proveedor incluido que usa la API nativa:

• Proveedor: lmstudio
• Autenticación: LM_API_TOKEN
• URL base predeterminada de inferencia: http://localhost:1234/v1

Luego configura un modelo (reemplázalo por uno de los IDs devueltos por http://localhost:1234/api/v1/models):

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

OpenClaw usa los endpoints nativos /api/v1/models y /api/v1/models/load de LM Studio para descubrimiento y carga automática, con /v1/chat/completions para inferencia de forma predeterminada. Si quieres que la carga JIT, el TTL y la expulsión automática de LM Studio controlen el ciclo de vida del modelo, configura models.providers.lmstudio.params.preload: false. Consulta /providers/lmstudio para configuración y solución de problemas.

# Ollama

Ollama se distribuye como un Plugin de proveedor incluido y usa la API nativa de Ollama:

• Proveedor: ollama
• Autenticación: no requerida (servidor local)
• Modelo de ejemplo: ollama/llama3.3
• Instalación: https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

Ollama se detecta localmente en http://127.0.0.1:11434 cuando optas por usarlo con OLLAMA_API_KEY, y el Plugin de proveedor incluido agrega Ollama directamente a openclaw onboard y al selector de modelos. Consulta /providers/ollama para incorporación, modo en la nube/local y configuración personalizada.

# vLLM

vLLM se distribuye como un Plugin de proveedor incluido para servidores locales/autohospedados compatibles con OpenAI:

• Proveedor: vllm
• Autenticación: opcional (depende de tu servidor)
• URL base predeterminada: http://127.0.0.1:8000/v1

Para optar por el descubrimiento automático localmente (cualquier valor funciona si tu servidor no exige autenticación):

export VLLM_API_KEY="vllm-local"

Luego configura un modelo (reemplázalo por uno de los IDs devueltos por /v1/models):

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

Consulta /providers/vllm para ver detalles.

# SGLang

SGLang se distribuye como un Plugin de proveedor incluido para servidores rápidos autohospedados compatibles con OpenAI:

• Proveedor: sglang
• Autenticación: opcional (depende de tu servidor)
• URL base predeterminada: http://127.0.0.1:30000/v1

Para optar por el descubrimiento automático localmente (cualquier valor funciona si tu servidor no exige autenticación):

export SGLANG_API_KEY="sglang-local"

Luego configura un modelo (reemplázalo por uno de los IDs devueltos por /v1/models):

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

Consulta /providers/sglang para ver detalles.

# Proxies locales (LM Studio, vLLM, LiteLLM, etc.)

Ejemplo (compatible con OpenAI):

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

# Ejemplos de CLI

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

Consulta también: Configuración para ver ejemplos completos de configuración.

# Relacionado

• Referencia de configuración - claves de configuración de modelos
• Conmutación por error de modelos - cadenas de respaldo y comportamiento de reintento
• Modelos - configuración de modelos y alias
• Proveedores - guías de configuración por proveedor