Configuración: herramientas y proveedores personalizados

Entrada de proveedor (type: "provider" u omitido):

• provider: identificador del proveedor de API (openai, anthropic, google/gemini, groq, etc.)
• model: sustitución del identificador del modelo
• profile / preferredProfile: selección del perfil de auth-profiles.json

Entrada de CLI (type: "cli"):

• command: ejecutable que se debe ejecutar
• args: argumentos con plantilla (admite {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc.; openclaw doctor --fix migra los marcadores de posición obsoletos {input} a {{MediaPath}})

Campos comunes:

• capabilities: lista opcional (image, audio, video). Cada Plugin de proveedor declara su propio conjunto predeterminado de capacidades; por ejemplo, el proveedor openai incluido usa de forma predeterminada imagen y audio, anthropic/minimax usa imagen, google usa imagen, audio y vídeo, y groq usa audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: sustituciones específicas de cada entrada.
• tools.media.image.timeoutSeconds y las entradas timeoutSeconds correspondientes del modelo de imagen también se aplican cuando el agente llama a la herramienta explícita image. Para la comprensión de imágenes, este tiempo de espera se aplica a la solicitud en sí y no se reduce por el trabajo de preparación anterior.
• En caso de error, se recurre a la siguiente entrada.

La autenticación del proveedor sigue el orden estándar: auth-profiles.json → variables de entorno → models.providers.*.apiKey.

Campos de finalización asíncrona:

• asyncCompletion.directSend: indicador de compatibilidad obsoleto. Las tareas multimedia asíncronas completadas siguen mediadas por la sesión solicitante para que el agente reciba el resultado, decida cómo comunicárselo al usuario y utilice la herramienta de mensajes cuando la entrega al origen lo requiera.

• self: solo la clave de la sesión actual.
• tree: la sesión actual y las sesiones generadas por ella (subagentes).
• agent: cualquier sesión que pertenezca al identificador del agente actual (puede incluir otros usuarios si ejecuta sesiones por remitente con el mismo identificador de agente).
• all: cualquier sesión. Dirigirse a otros agentes sigue requiriendo tools.agentToAgent.
• Restricción del entorno aislado: cuando la sesión actual está aislada y agents.defaults.sandbox.sessionToolsVisibility="spawned" (el valor predeterminado), la visibilidad se fuerza a tree, incluso si tools.sessions.visibility="all".
• Cuando no es all, sessions_list incluye un campo compacto visibility que describe el modo efectivo y una advertencia de que algunas sesiones fuera del ámbito actual pueden omitirse.

• Los archivos adjuntos requieren enabled: true.
• Los archivos adjuntos de los subagentes se materializan en el espacio de trabajo secundario en .openclaw/attachments/<uuid>/ con un archivo .manifest.json.
• Los archivos adjuntos de ACP solo pueden ser imágenes y se reenvían insertados al entorno de ejecución de ACP después de superar los mismos límites de cantidad de archivos, bytes por archivo y bytes totales.
• El contenido de los archivos adjuntos se censura automáticamente al conservar la transcripción.
• Las entradas Base64 se validan mediante comprobaciones estrictas del alfabeto y del relleno, además de una protección de tamaño previa a la decodificación.
• Los permisos de los archivos adjuntos de los subagentes son 0700 para los directorios y 0600 para los archivos.
• La limpieza de los subagentes sigue la política cleanup: delete siempre elimina los archivos adjuntos; keep solo los conserva cuando retainOnSessionKeep: true.

• Use authHeader: true + headers para necesidades de autenticación personalizadas.
• Sobrescriba la raíz de configuración del agente con OPENCLAW_AGENT_DIR.
• Precedencia de combinación para identificadores de proveedor coincidentes:
  • Los valores baseUrl no vacíos de models.json del agente tienen prioridad.
  • Los valores apiKey no vacíos del agente tienen prioridad solo cuando ese proveedor no está administrado mediante SecretRef en el contexto actual de configuración/perfil de autenticación.
  • Los valores apiKey de proveedores administrados mediante SecretRef se actualizan desde marcadores de origen (ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/ejecución), en lugar de conservar los secretos resueltos.
  • Los valores de cabecera de proveedores administrados mediante SecretRef se actualizan desde marcadores de origen (secretref-env:ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/ejecución).
  • Los valores apiKey/baseUrl del agente vacíos o ausentes recurren a models.providers en la configuración.
  • Para contextWindow/maxTokens de modelos coincidentes: el valor explícito de configuración tiene prioridad cuando está presente y es válido (un número finito positivo); de lo contrario, se usa el valor implícito/generado del catálogo.
  • contextTokens de modelos coincidentes sigue la misma regla de prioridad del valor explícito y, en su ausencia, del implícito; úselo para limitar el contexto efectivo sin cambiar los metadatos nativos del modelo.
  • Los catálogos de plugins de proveedores se almacenan como fragmentos de catálogo generados y pertenecientes al plugin dentro del estado de plugins del agente.
  • Use models.mode: "replace" cuando quiera que la configuración reescriba por completo models.json y omita la combinación de fragmentos de catálogo pertenecientes a plugins.
  • La persistencia de marcadores toma el origen como autoridad: los marcadores se escriben a partir de la instantánea activa de la configuración de origen (antes de la resolución), no a partir de los valores secretos resueltos en tiempo de ejecución.

• models.mode: comportamiento del catálogo de proveedores (merge o replace).
• models.providers: mapa personalizado de proveedores indexado por identificador de proveedor.
  • Ediciones seguras: use openclaw config set models.providers.<id> '<json>' --strict-json --merge o openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge para actualizaciones aditivas. config set rechaza los reemplazos destructivos a menos que pase --replace.

• models.providers.*.api: adaptador de solicitudes (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). Para backends autoalojados de /v1/chat/completions, como MLX, vLLM, SGLang y la mayoría de los servidores locales compatibles con OpenAI, use openai-completions. Un proveedor personalizado con baseUrl pero sin api usa openai-completions de forma predeterminada; establezca openai-responses solo cuando el backend admita /v1/responses.
• models.providers.*.apiKey: credencial del proveedor (se recomienda la sustitución mediante SecretRef/entorno).
• models.providers.*.auth: estrategia de autenticación (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: ventana de contexto nativa predeterminada para los modelos de este proveedor cuando la entrada del modelo no establece contextWindow.
• models.providers.*.contextTokens: límite efectivo predeterminado del contexto en tiempo de ejecución para los modelos de este proveedor cuando la entrada del modelo no establece contextTokens.
• models.providers.*.maxTokens: límite predeterminado de tokens de salida para los modelos de este proveedor cuando la entrada del modelo no establece maxTokens.
• models.providers.*.timeoutSeconds: tiempo de espera HTTP opcional, por proveedor y en segundos, para solicitudes al modelo, incluidos la conexión, las cabeceras, el cuerpo y la gestión de la cancelación total de la solicitud.
• models.providers.*.injectNumCtxForOpenAICompat: para Ollama + openai-completions, inserta options.num_ctx en las solicitudes (valor predeterminado: true).
• models.providers.*.authHeader: fuerza el transporte de credenciales en la cabecera Authorization cuando sea necesario.
• models.providers.*.baseUrl: URL base de la API de origen.
• models.providers.*.headers: cabeceras estáticas adicionales para el enrutamiento por proxy/inquilino.

models.providers.*.request: sobrescrituras del transporte para solicitudes HTTP al proveedor de modelos.

• request.headers: cabeceras adicionales (combinadas con los valores predeterminados del proveedor). Los valores aceptan SecretRef.
• request.auth: sobrescritura de la estrategia de autenticación. Modos: "provider-default" (usa la autenticación integrada del proveedor), "authorization-bearer" (con token), "header" (con headerName, value y prefix opcional).
• request.proxy: sobrescritura del proxy HTTP. Modos: "env-proxy" (usa las variables de entorno HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (con url). Ambos modos aceptan un subobjeto tls opcional.
• request.tls: sobrescritura de TLS para conexiones directas. Campos: ca, cert, key, passphrase (todos aceptan SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: cuando es true, permite que las solicitudes HTTP al proveedor de modelos accedan a rangos privados, CGNAT o similares a través de la protección de obtención HTTP del proveedor. Las URL base de proveedores personalizados/locales ya confían en el origen configurado exacto, excepto los orígenes de metadatos/enlace local, que permanecen bloqueados sin una aceptación explícita. Establezca este valor en false para desactivar la confianza en el origen exacto. WebSocket usa el mismo request para las cabeceras/TLS, pero no esa protección SSRF de obtención. Valor predeterminado: false.

• models.providers.*.models: entradas explícitas del catálogo de modelos del proveedor.
• models.providers.*.models.*.input: modalidades de entrada del modelo. Use ["text"] para modelos que solo admiten texto y ["text", "image"] para modelos nativos de imagen/visión. Los archivos adjuntos de imagen solo se insertan en los turnos del agente cuando el modelo seleccionado está marcado como compatible con imágenes.
• models.providers.*.models.*.contextWindow: metadatos de la ventana de contexto nativa del modelo. Este valor sobrescribe contextWindow a nivel de proveedor para ese modelo.
• models.providers.*.models.*.contextTokens: límite opcional del contexto en tiempo de ejecución. Este valor sobrescribe contextTokens a nivel de proveedor; úselo cuando quiera un presupuesto de contexto efectivo menor que el contextWindow nativo del modelo; openclaw models list muestra ambos valores cuando difieren.
• models.providers.*.models.*.compat.supportsDeveloperRole: indicación opcional de compatibilidad. Para api: "openai-completions" con un baseUrl no nativo y no vacío (el host no es api.openai.com), OpenClaw fuerza este valor a false en tiempo de ejecución. Un baseUrl vacío/omitido conserva el comportamiento predeterminado de OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: indicación opcional de compatibilidad para endpoints de chat compatibles con OpenAI que solo admiten cadenas. Cuando es true, OpenClaw aplana los arreglos messages[].content de texto puro y los convierte en cadenas simples antes de enviar la solicitud.
• models.providers.*.models.*.compat.strictMessageKeys: indicación opcional de compatibilidad para endpoints de chat compatibles con OpenAI que aplican validación estricta. Cuando es true, OpenClaw reduce los objetos de mensajes salientes de Chat Completions a role y content antes de enviar la solicitud.
• models.providers.*.models.*.compat.thinkingFormat: indicación opcional sobre la carga útil de razonamiento. Use "together" para reasoning.enabled al estilo de Together, "qwen" para enable_thinking en el nivel superior o "qwen-chat-template" para chat_template_kwargs.enable_thinking en servidores compatibles con OpenAI de la familia Qwen que admitan argumentos de palabra clave de plantilla de chat a nivel de solicitud, como vLLM. Los modelos Qwen de vLLM configurados exponen opciones binarias de /think (off, on) para estos formatos.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: indicación opcional de compatibilidad para backends de Chat Completions al estilo de DeepSeek que requieren que los mensajes anteriores del asistente conserven reasoning_content al reproducirse. Cuando es true, OpenClaw conserva ese campo en los mensajes salientes del asistente. Úselo al conectar un proxy personalizado compatible con DeepSeek que rechace solicitudes después de eliminar el razonamiento. Valor predeterminado: false.

• plugins.entries.amazon-bedrock.config.discovery: raíz de la configuración de descubrimiento automático de Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: activa/desactiva el descubrimiento implícito.
• plugins.entries.amazon-bedrock.config.discovery.region: región de AWS para el descubrimiento.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro opcional por identificador de proveedor para el descubrimiento dirigido.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervalo de sondeo para actualizar el descubrimiento.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: ventana de contexto alternativa para los modelos descubiertos.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: máximo alternativo de tokens de salida para los modelos descubiertos.

El Plugin de proveedor externo oficial cerebras puede configurar esto mediante openclaw onboard --auth-choice cerebras-api-key. Use una configuración explícita del proveedor solo al sobrescribir los valores predeterminados.

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

Use cerebras/zai-glm-4.7 para Cerebras; zai/glm-4.7 para la conexión directa con Z.AI.

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },    },  },}

Proveedor integrado compatible con Anthropic. Atajo: openclaw onboard --auth-choice kimi-code-api-key.

Consulta Modelos locales. En resumen: ejecuta un modelo local grande mediante la API Responses de LM Studio en hardware potente; mantén combinados los modelos alojados como alternativa.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

Define MINIMAX_API_KEY. Atajos: openclaw onboard --auth-choice minimax-global-api u openclaw onboard --auth-choice minimax-cn-api. El catálogo de modelos usa M3 de forma predeterminada y también incluye las variantes de M2.7. En la ruta de transmisión compatible con Anthropic, OpenClaw desactiva de forma predeterminada el razonamiento de MiniMax M2.x, a menos que configures thinking explícitamente; MiniMax-M3 (y M3.x) permanece de forma predeterminada en la ruta de razonamiento omitido/adaptativo del proveedor. /fast on o params.fastMode: true sustituye MiniMax-M2.7 por MiniMax-M2.7-highspeed.

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "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",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

Para el endpoint de China: baseUrl: "https://api.moonshot.cn/v1" u openclaw onboard --auth-choice moonshot-api-key-cn.

Los endpoints nativos de Moonshot anuncian compatibilidad con el uso de transmisión en el transporte compartido openai-completions, y OpenClaw la activa según las capacidades del endpoint, en lugar de basarse únicamente en el identificador del proveedor integrado.

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

Define OPENCODE_API_KEY (u OPENCODE_ZEN_API_KEY). Usa referencias opencode/... para el catálogo Zen o referencias opencode-go/... para el catálogo Go. Atajo: openclaw onboard --auth-choice opencode-zen u openclaw onboard --auth-choice opencode-go.

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "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",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

La URL base debe omitir /v1 (el cliente de Anthropic lo añade). Atajo: openclaw onboard --auth-choice synthetic-api-key.

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

Define ZAI_API_KEY. Las referencias de modelos usan el identificador canónico del proveedor zai/*. Atajo: openclaw onboard --auth-choice zai-api-key.

• Endpoint general: https://api.z.ai/api/paas/v4
• Endpoint de programación: https://api.z.ai/api/coding/paas/v4
• La opción de autenticación predeterminada zai-api-key prueba tu clave y detecta automáticamente a qué endpoint pertenece (si la detección no es concluyente, solicita que elijas uno y selecciona Global de forma predeterminada). También hay opciones de autenticación específicas para CN y Coding-Plan que permiten seleccionarlas explícitamente.
• Para el endpoint general, define un proveedor personalizado con la sobrescritura de la URL base.