Configuración: herramientas y proveedores personalizados

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

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

Entrada de CLI (type: "cli"):

• command: ejecutable que se 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 que contiene uno o varios de image, audio y video.
• prompt, maxChars, maxBytes, timeoutSeconds, language: sobrescrituras por entrada.
• Las entradas timeoutSeconds coincidentes 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 propia solicitud y no se reduce por el trabajo de preparación anterior.
• En caso de fallo, 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.

• self: solo la clave de la sesión actual.
• tree: la sesión actual + las sesiones iniciadas por la sesión actual (subagentes). Para las operaciones de lectura, también incluye las sesiones de grupo del mismo agente que la sesión actual observa mediante el conocimiento ambiental de los grupos.
• agent: cualquier sesión perteneciente al identificador del agente actual (puede incluir a otros usuarios si se ejecutan sesiones por remitente con el mismo identificador de agente).
• all: cualquier sesión. La selección de sesiones de 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 pueden omitirse fuera del ámbito actual.

• 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 .manifest.json.
• Los archivos adjuntos de ACP se limitan a 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 elimina automáticamente de la persistencia de transcripciones.
• Las entradas Base64 se validan mediante comprobaciones estrictas del alfabeto y del relleno, así como una comprobación de tamaño previa a la descodificació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.
• Sustituya la raíz de configuración del agente mediante 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 solo tienen prioridad cuando ese proveedor no está gestionado mediante SecretRef en el contexto actual de configuración/perfil de autenticación.
  • Los valores apiKey de proveedores gestionados mediante SecretRef se actualizan a partir de marcadores de origen (ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/ejecución), en lugar de conservar secretos resueltos.
  • Los valores de cabecera de proveedores gestionados mediante SecretRef se actualizan a partir de marcadores de origen (secretref-env:ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/ejecución).
  • Los valores apiKey/baseUrl vacíos o ausentes del agente recurren a models.providers en la configuración.
  • Para contextWindow/maxTokens de modelos coincidentes: el valor explícito de la configuración tiene prioridad cuando está presente y es válido (un número finito positivo); de lo contrario, se utiliza el valor implícito/generado del catálogo.
  • El contextTokens de modelos coincidentes sigue la misma regla de prioridad del valor explícito y, en su defecto, del implícito; utilícelo 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 propiedad del plugin en el 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 con fragmentos de catálogo propiedad de plugins.
  • La persistencia de marcadores se rige por el origen: los marcadores se escriben desde la instantánea de configuración de origen activa (antes de la resolución), no desde los valores de secretos resueltos en tiempo de ejecución.

• models.mode: comportamiento del catálogo de proveedores (merge o replace).
• models.providers: mapa de proveedores personalizados 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 /v1/chat/completions autoalojados, 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, utiliza de forma predeterminada openai-completions; 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 de contexto efectivo predeterminado 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 opcional por proveedor, en segundos, para solicitudes HTTP de modelos, incluida la gestión de conexión, cabeceras, cuerpo y cancelación total de la solicitud.
• models.providers.*.injectNumCtxForOpenAICompat: para Ollama + openai-completions, inyecta 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 ascendente.
• models.providers.*.headers: cabeceras estáticas adicionales para el enrutamiento de proxy/inquilino.

models.providers.*.request: sustituciones del transporte para solicitudes HTTP a proveedores de modelos.

• request.headers: cabeceras adicionales (combinadas con los valores predeterminados del proveedor). Los valores admiten SecretRef.
• request.auth: sustitución de la estrategia de autenticación. Modos: "provider-default" (usar la autenticación integrada del proveedor), "authorization-bearer" (con token), "header" (con headerName, value y prefix opcional).
• request.proxy: sustitución del proxy HTTP. Modos: "env-proxy" (usar las variables de entorno HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (con url). Ambos modos admiten un subobjeto tls opcional.
• request.tls: sustitución de TLS para conexiones directas. Campos: ca, cert, key, passphrase (todos admiten SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: cuando sea true, permite que las solicitudes HTTP a proveedores 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, salvo los orígenes de metadatos/enlace local, que permanecen bloqueados sin una activación explícita. Establezca este valor en false para renunciar a la confianza en el origen exacto. WebSocket utiliza el mismo request para 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 de solo texto y ["text", "image"] para modelos nativos de imagen/visión. Los archivos adjuntos de imagen solo se incorporan a 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. Sustituye el contextWindow del proveedor para ese modelo.
• models.providers.*.models.*.contextTokens: límite de contexto opcional en tiempo de ejecución. Sustituye el contextTokens del proveedor; utilícelo cuando quiera un presupuesto de contexto efectivo menor que el contextWindow nativo del modelo; openclaw models list muestra ambos valores cuando difieren.

Declaraciones de capacidades de proveedores personalizados

Los catálogos de proveedores son propietarios de compat para las rutas de modelos incluidos y conocidos por el catálogo. No copie esas marcas en la configuración: OpenClaw utiliza la fila del catálogo cuando los valores configurados de api y baseUrl siguen identificando esa ruta. openclaw doctor --fix elimina las sustituciones heredadas coincidentes e informa de los valores divergentes para su revisión.

Se sigue admitiendo un bloque compat para un proveedor verdaderamente personalizado, un modelo personalizado o un modelo del catálogo enrutado a un endpoint diferente. Establezca únicamente las capacidades verificadas con ese endpoint:

• 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 o 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 de respaldo para los modelos descubiertos.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: cantidad máxima de tokens de salida de respaldo 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 conectarse directamente a 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.

Consulte Modelos locales. En resumen: ejecute un modelo local grande mediante la API Responses de LM Studio en hardware potente; mantenga combinados los modelos alojados para usarlos como respaldo.

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

Establezca MINIMAX_API_KEY. Atajos: openclaw onboard --auth-choice minimax-global-api o openclaw onboard --auth-choice minimax-cn-api. El catálogo de modelos usa M3 de forma predeterminada y también incluye las variantes M2.7. En la ruta de streaming compatible con Anthropic, OpenClaw desactiva de forma predeterminada el razonamiento de MiniMax M2.x, salvo que se establezca explícitamente thinking; MiniMax-M3 (y M3.x) permanece de forma predeterminada en la ruta de razonamiento omitido/adaptativo del proveedor. /fast on o params.fastMode: true reescribe MiniMax-M2.7 como 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" o openclaw onboard --auth-choice moonshot-api-key-cn.

Los endpoints nativos de Moonshot anuncian compatibilidad con el uso de streaming en el transporte compartido openai-completions, y OpenClaw la determina a partir de las capacidades del endpoint, no solo del identificador del proveedor integrado.

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

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

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M3" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M3": { alias: "MiniMax M3" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 262144,            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": {} },    },  },}

Establezca ZAI_API_KEY. Las referencias de modelos usan el identificador de proveedor canónico 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 comprueba la clave y detecta automáticamente a qué endpoint pertenece (si la detección no es concluyente, solicita una elección y usa 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, defina un proveedor personalizado con la URL base sobrescrita.