Configuración — herramientas y proveedores personalizados

​

Herramientas

​

Perfiles de herramientas

​

Grupos de herramientas

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

​

tools.elevated

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

• La anulación por agente (agents.list[].tools.elevated) solo puede restringir más.
• /elevated on|off|ask|full almacena el estado por sesión; las directivas en línea se aplican a un solo mensaje.
• exec elevado omite el sandboxing y usa la ruta de escape configurada (gateway de forma predeterminada, o node cuando el destino de exec es node).

​

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.5"],
      },
    },
  },
}

​

tools.loopDetection

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• historySize: historial máximo de llamadas a herramientas conservado para análisis de bucles.
• warningThreshold: umbral de patrón repetido sin progreso para advertencias.
• criticalThreshold: umbral repetido más alto para bloquear bucles críticos.
• globalCircuitBreakerThreshold: umbral de detención estricta para cualquier ejecución sin progreso.
• detectors.genericRepeat: advierte sobre llamadas repetidas de la misma herramienta/con los mismos argumentos.
• detectors.knownPollNoProgress: advierte/bloquea sobre herramientas de sondeo conocidas (process.poll, command_status, etc.).
• detectors.pingPong: advierte/bloquea sobre patrones alternantes en pares sin progreso.
• Si warningThreshold >= criticalThreshold o criticalThreshold >= globalCircuitBreakerThreshold, falla la validación.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // optional; omit for auto-detect
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

​

tools.media

{
  tools: {
    media: {
      concurrency: 2,
      asyncCompletion: {
        directSend: false, // opt-in: send finished async music/video directly to the channel
      },
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

​

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

​

tools.sessions

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

• self: solo la clave de sesión actual.
• tree: sesión actual + sesiones generadas por la sesión actual (subagentes).
• agent: cualquier sesión que pertenezca al id del agente actual (puede incluir otros usuarios si ejecutas sesiones por remitente bajo el mismo id de agente).
• all: cualquier sesión. El direccionamiento entre agentes sigue requiriendo tools.agentToAgent.
• Restricción por sandbox: cuando la sesión actual está en sandbox y agents.defaults.sandbox.sessionToolsVisibility="spawned", la visibilidad se fuerza a tree incluso si tools.sessions.visibility="all".

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

• Los adjuntos solo se admiten para runtime: "subagent". El tiempo de ejecución ACP los rechaza.
• Los archivos se materializan en el espacio de trabajo hijo en .openclaw/attachments/<uuid>/ con un .manifest.json.
• El contenido de los adjuntos se redacta automáticamente al persistir la transcripción.
• Las entradas base64 se validan con comprobaciones estrictas de alfabeto/relleno y una protección de tamaño previa a la decodificación.
• Los permisos de archivos son 0700 para directorios y 0600 para archivos.
• La limpieza sigue la política cleanup: delete siempre elimina los adjuntos; keep los conserva solo cuando retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // enable experimental update_plan
    },
  },
}

• planTool: habilita la herramienta estructurada update_plan para el seguimiento de trabajo no trivial de varios pasos.
• Predeterminado: false salvo que agents.defaults.embeddedPi.executionContract (o una anulación por agente) esté establecido en "strict-agentic" para una ejecución de la familia GPT-5 de OpenAI u OpenAI Codex. Establece true para forzar la herramienta fuera de ese alcance, o false para mantenerla desactivada incluso en ejecuciones GPT-5 estrictas-agénticas.
• Cuando está habilitada, el prompt del sistema también agrega guía de uso para que el modelo solo la use en trabajo sustancial y mantenga como máximo un paso in_progress.

​

agents.defaults.subagents

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

• model: modelo predeterminado para subagentes generados. Si se omite, los subagentes heredan el modelo de quien llama.
• allowAgents: lista permitida predeterminada de ids de agentes de destino para sessions_spawn cuando el agente solicitante no establece su propio subagents.allowAgents (["*"] = cualquiera; predeterminado: solo el mismo agente).
• runTimeoutSeconds: tiempo de espera predeterminado (segundos) para sessions_spawn cuando la llamada de herramienta omite runTimeoutSeconds. 0 significa sin tiempo de espera.
• Política de herramientas por subagente: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Proveedores personalizados y URLs base

{
  models: {
    mode: "merge", // merge (default) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            contextTokens: 96000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

• Usa authHeader: true + headers para necesidades de autenticación personalizadas.
• Anula la raíz de configuración del agente con OPENCLAW_AGENT_DIR (o PI_CODING_AGENT_DIR, un alias heredado de variable de entorno).
• Precedencia de fusión para ids de proveedor coincidentes:
  • Los valores baseUrl no vacíos de models.json del agente prevalecen.
  • Los valores apiKey no vacíos del agente prevalecen solo cuando ese proveedor no está gestionado por SecretRef en el contexto actual de configuración/perfil de autenticación.
  • Los valores apiKey de proveedores gestionados por SecretRef se actualizan desde marcadores de origen (ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/exec) en lugar de conservar secretos resueltos.
  • Los valores de encabezado de proveedores gestionados por SecretRef se actualizan desde marcadores de origen (secretref-env:ENV_VAR_NAME para referencias de entorno, secretref-managed para referencias de archivo/exec).
  • Los apiKey/baseUrl del agente vacíos o ausentes recurren a models.providers en la configuración.
  • Los contextWindow/maxTokens de modelos coincidentes usan el valor más alto entre la configuración explícita y los valores implícitos del catálogo.
  • Los contextTokens de modelos coincidentes conservan un límite explícito de tiempo de ejecución cuando está presente; úsalo para limitar el contexto efectivo sin cambiar los metadatos nativos del modelo.
  • Usa models.mode: "replace" cuando quieras que la configuración reescriba por completo models.json.
  • La persistencia de marcadores es autoritativa desde el origen: los marcadores se escriben desde la instantánea activa de configuración de origen (antes de la resolución), no desde valores secretos resueltos en tiempo de ejecución.

​

Detalles de los campos del proveedor

• models.mode: comportamiento del catálogo del proveedor (merge o replace).
• models.providers: mapa de proveedores personalizados indexado por id de proveedor.
  • Ediciones seguras: usa 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 reemplazos destructivos a menos que pases --replace.
• models.providers.*.api: adaptador de solicitudes (openai-completions, openai-responses, anthropic-messages, google-generative-ai, etc.).
• models.providers.*.apiKey: credencial del proveedor (prefiere sustitución SecretRef/entorno).
• models.providers.*.auth: estrategia de autenticación (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: para Ollama + openai-completions, inyecta options.num_ctx en las solicitudes (predeterminado: true).
• models.providers.*.authHeader: fuerza el transporte de credenciales en el encabezado Authorization cuando se requiere.
• models.providers.*.baseUrl: URL base de la API upstream.
• models.providers.*.headers: encabezados estáticos adicionales para enrutamiento de proxy/inquilino.
• models.providers.*.request: anulaciones de transporte para solicitudes HTTP del proveedor de modelos.
  • request.headers: encabezados adicionales (fusionados con los valores predeterminados del proveedor). Los valores aceptan SecretRef.
  • request.auth: anulación de estrategia de autenticación. Modos: "provider-default" (usar la autenticación integrada del proveedor), "authorization-bearer" (con token), "header" (con headerName, value, prefix opcional).
  • request.proxy: anulación de proxy HTTP. Modos: "env-proxy" (usar 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 HTTPS a baseUrl cuando el DNS se resuelve a rangos privados, CGNAT o similares, mediante la protección de obtención HTTP del proveedor (opt-in del operador para endpoints autoalojados de confianza compatibles con OpenAI). WebSocket usa la misma request para encabezados/TLS, pero no esa barrera SSRF de fetch. Predeterminado false.
• models.providers.*.models: entradas explícitas del catálogo de modelos del proveedor.
• models.providers.*.models.*.contextWindow: metadatos nativos de la ventana de contexto del modelo.
• models.providers.*.models.*.contextTokens: límite opcional de contexto en tiempo de ejecución. Úsalo cuando quieras un presupuesto efectivo de contexto más pequeño que el contextWindow nativo del modelo.
• models.providers.*.models.*.compat.supportsDeveloperRole: sugerencia opcional de compatibilidad. Para api: "openai-completions" con un baseUrl no vacío y no nativo (host distinto de api.openai.com), OpenClaw fuerza esto a false en tiempo de ejecución. baseUrl vacío/omitido mantiene el comportamiento predeterminado de OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: sugerencia opcional de compatibilidad para endpoints de chat compatibles con OpenAI que solo aceptan cadenas. Cuando es true, OpenClaw aplana los arreglos messages[].content de texto puro en cadenas simples antes de enviar la solicitud.
• plugins.entries.amazon-bedrock.config.discovery: raíz de configuración del 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 de id de proveedor para descubrimiento dirigido.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervalo de sondeo para la actualización del descubrimiento.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: ventana de contexto alternativa para modelos descubiertos.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: máximo alternativo de tokens de salida para modelos descubiertos.

​

Ejemplos de proveedores

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (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: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

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

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

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

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

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

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

​

Relacionado

• Referencia de configuración — otras claves de nivel superior
• Configuración — agentes
• Configuración — canales
• Herramientas y Plugins