Configuración: herramientas y proveedores personalizados

• 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 auth-profiles.json

• command: ejecutable que se va a ejecutar
• args: argumentos con plantilla (admite {{AttachmentPath}}, {{AttachmentUrl}}, {{AttachmentContentType}}, {{AttachmentDir}}, {{AttachmentIndex}}, {{Prompt}}, {{MaxChars}}, etc.; openclaw doctor --fix migra los marcadores de posición obsoletos {input} a {{AttachmentPath}}). Los alias anteriores {{MediaPath}}, {{MediaUrl}}, {{MediaType}} y {{MediaDir}} siguen disponibles durante su periodo de compatibilidad, pero están obsoletos.

• capabilities: lista que contiene uno o varios de image, audio y video.
• prompt, maxChars, maxBytes, timeoutSeconds, language: sustituciones por entrada.
• Las entradas coincidentes timeoutSeconds 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.

• self: solo la clave de la sesión actual.
• tree: sesión actual + sesiones generadas 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 del grupo.
• 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. 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" (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 adjuntos requieren enabled: true.
• Los adjuntos de subagentes se materializan en el espacio de trabajo secundario en .openclaw/attachments/<uuid>/ con un .manifest.json.
• Los adjuntos de ACP se limitan a imágenes y se reenvían en línea al entorno de ejecución de ACP una vez superados los mismos límites de cantidad de archivos, bytes por archivo y bytes totales.
• El contenido de los adjuntos se censura automáticamente al conservar la transcripción.
• Las entradas Base64 se validan mediante comprobaciones estrictas del alfabeto y el relleno, además de una protección de tamaño previa a la descodificación.
• Los permisos de los archivos adjuntos de subagentes son 0700 para los directorios y 0600 para los archivos.
• La limpieza de subagentes sigue la política cleanup: delete siempre elimina los adjuntos; keep solo los conserva cuando retainOnSessionKeep: true.

• Utilice authHeader: true + headers para necesidades de autenticación personalizadas.
• Anule la raíz de configuración del agente con OPENCLAW_AGENT_DIR.
• Precedencia de combinación para identificadores de proveedores coincidentes:
  • Prevalecen los valores no vacíos de models.json baseUrl del agente.
  • Los valores no vacíos de apiKey del agente prevalecen 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 los 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 los 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 configuración prevalece 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 prevalencia 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.
  • Utilice models.mode: "replace" cuando desee que la configuración reescriba por completo models.json y omita la combinación de los fragmentos de catálogo propiedad de los plugins.
  • La persistencia de marcadores tiene como autoridad el origen: los marcadores se escriben a partir de la instantánea activa de la configuración de origen (antes de la resolución), no de los valores secretos resueltos durante la 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: utilice 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 se proporcione --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, utilice 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 durante la 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 las solicitudes HTTP del modelo, incluida la gestión de conexión, cabeceras, cuerpo y 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 ascendente.
• models.providers.*.headers: cabeceras estáticas adicionales para el enrutamiento por proxy/inquilino.

• request.headers: cabeceras adicionales (combinadas con los valores predeterminados del proveedor). Los valores aceptan SecretRef.
• request.auth: anulación de la estrategia de autenticación. Modos: "provider-default" (utilizar la autenticación incorporada del proveedor), "authorization-bearer" (con token), "header" (con headerName, value y prefix opcional).
• request.proxy: anulación del proxy HTTP. Modos: "env-proxy" (utilizar las variables de entorno HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (con url). Ambos modos aceptan un subobjeto tls opcional.
• request.tls: anulación 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 del 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 habilitación explícita. Establezca este valor en false para desactivar la confianza en el origen exacto. WebSocket utiliza 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. Utilice ["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 anula el contextWindow del proveedor para ese modelo.
• models.providers.*.models.*.contextTokens: límite opcional del contexto durante la ejecución. Este valor anula el contextTokens del proveedor; utilícelo cuando desee 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

• plugins.entries.amazon-bedrock.config.discovery: raíz de la configuración de detección automática de Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: activa o desactiva la detección implícita.
• plugins.entries.amazon-bedrock.config.discovery.region: región de AWS para la detección.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro opcional por id de proveedor para la detección dirigida.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervalo de sondeo para actualizar la detección.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: ventana de contexto de respaldo para los modelos detectados.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: cantidad máxima de tokens de salida de respaldo para los modelos detectados.

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

• 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 selección cuyo valor predeterminado es Global). También hay opciones de autenticación específicas de CN y Coding-Plan para realizar una selección explícita.
• Para el endpoint general, defina un proveedor personalizado con el reemplazo de la URL base.