Configuração — ferramentas e providers personalizados

​

Ferramentas

​

Perfis de ferramentas

​

Grupos de ferramentas

​

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

• A substituição por agente (agents.list[].tools.elevated) só pode restringir ainda mais.
• /elevated on|off|ask|full armazena estado por sessão; diretivas inline se aplicam a uma única mensagem.
• exec elevado ignora o sandbox e usa o caminho de escape configurado (gateway por padrão, ou node quando o destino de exec é 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: máximo do histórico de chamadas de ferramentas mantido para análise de loop.
• warningThreshold: limite de padrão repetitivo sem progresso para avisos.
• criticalThreshold: limite repetitivo mais alto para bloquear loops críticos.
• globalCircuitBreakerThreshold: limite de parada rígida para qualquer execução sem progresso.
• detectors.genericRepeat: avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos.
• detectors.knownPollNoProgress: avisa/bloqueia ferramentas de polling conhecidas (process.poll, command_status etc.).
• detectors.pingPong: avisa/bloqueia padrões alternados em pares sem progresso.
• Se warningThreshold >= criticalThreshold ou criticalThreshold >= globalCircuitBreakerThreshold, a validação falha.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // ou env BRAVE_API_KEY
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // opcional; omita para detecção automática
        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: envia música/vídeo assíncrono finalizado diretamente ao canal
      },
      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: somente a chave da sessão atual.
• tree: sessão atual + sessões iniciadas pela sessão atual (subagentes).
• agent: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo ID de agente).
• all: qualquer sessão. O direcionamento entre agentes ainda exige tools.agentToAgent.
• Restrição de sandbox: quando a sessão atual está em sandbox e agents.defaults.sandbox.sessionToolsVisibility="spawned", a visibilidade é forçada para tree mesmo se tools.sessions.visibility="all".

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: defina como true para permitir anexos de arquivo inline
        maxTotalBytes: 5242880, // 5 MB no total entre todos os arquivos
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB por arquivo
        retainOnSessionKeep: false, // mantém anexos quando cleanup="keep"
      },
    },
  },
}

• Anexos só são compatíveis com runtime: "subagent". O runtime ACP os rejeita.
• Os arquivos são materializados no workspace filho em .openclaw/attachments/<uuid>/ com um .manifest.json.
• O conteúdo do anexo é automaticamente redigido da persistência da transcrição.
• Entradas em Base64 são validadas com verificações rígidas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação.
• As permissões de arquivo são 0700 para diretórios e 0600 para arquivos.
• A limpeza segue a política cleanup: delete sempre remove anexos; keep só os mantém quando retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // habilita o update_plan experimental
    },
  },
}

• planTool: habilita a ferramenta estruturada update_plan para rastreamento de trabalho não trivial em várias etapas.
• Padrão: false, a menos que agents.defaults.embeddedPi.executionContract (ou uma substituição por agente) esteja definido como "strict-agentic" para uma execução da família GPT-5 do OpenAI ou OpenAI Codex. Defina true para forçar a ferramenta fora desse escopo, ou false para mantê-la desligada mesmo em execuções rígidas agentic GPT-5.
• Quando habilitado, o prompt do sistema também adiciona orientação de uso para que o modelo só a use em trabalho substancial e mantenha no máximo uma etapa in_progress.

​

agents.defaults.subagents

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

• model: modelo padrão para subagentes iniciados. Se omitido, os subagentes herdam o modelo do chamador.
• allowAgents: lista de permissão padrão de IDs de agente de destino para sessions_spawn quando o agente solicitante não define seu próprio subagents.allowAgents (["*"] = qualquer; padrão: somente o mesmo agente).
• runTimeoutSeconds: timeout padrão (segundos) para sessions_spawn quando a chamada da ferramenta omite runTimeoutSeconds. 0 significa sem timeout.
• Política de ferramentas por subagente: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Providers personalizados e base URLs

{
  models: {
    mode: "merge", // merge (padrão) | 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,
          },
        ],
      },
    },
  },
}

• Use authHeader: true + headers para necessidades de autenticação personalizadas.
• Substitua a raiz de configuração do agente com OPENCLAW_AGENT_DIR (ou PI_CODING_AGENT_DIR, um alias legado de variável de ambiente).
• Precedência de merge para IDs de provider correspondentes:
  • Valores não vazios de baseUrl em models.json do agente prevalecem.
  • Valores não vazios de apiKey do agente prevalecem somente quando esse provider não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação.
  • Valores de apiKey de provider gerenciados por SecretRef são atualizados a partir de marcadores de origem (ENV_VAR_NAME para refs de ambiente, secretref-managed para refs de arquivo/exec) em vez de persistirem segredos resolvidos.
  • Valores de header de provider gerenciados por SecretRef são atualizados a partir de marcadores de origem (secretref-env:ENV_VAR_NAME para refs de ambiente, secretref-managed para refs de arquivo/exec).
  • apiKey/baseUrl do agente vazios ou ausentes recorrem a models.providers na configuração.
  • contextWindow/maxTokens de modelo correspondente usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo.
  • contextTokens de modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo.
  • Use models.mode: "replace" quando quiser que a configuração reescreva totalmente models.json.
  • A persistência de marcadores é autoritativa da origem: os marcadores são gravados a partir do snapshot da configuração de origem ativa (pré-resolução), não dos valores secretos resolvidos em runtime.

​

Detalhes dos campos do provider

• models.mode: comportamento do catálogo de provider (merge ou replace).
• models.providers: mapa de providers personalizados indexado por ID do provider.
  • Edições seguras: use openclaw config set models.providers.<id> '<json>' --strict-json --merge ou openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge para atualizações aditivas. config set recusa substituições destrutivas a menos que você passe --replace.
• models.providers.*.api: adaptador de requisição (openai-completions, openai-responses, anthropic-messages, google-generative-ai etc.).
• models.providers.*.apiKey: credencial do provider (prefira SecretRef/substituição por ambiente).
• models.providers.*.auth: estratégia de autenticação (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: para Ollama + openai-completions, injeta options.num_ctx nas requisições (padrão: true).
• models.providers.*.authHeader: força o transporte de credencial no header Authorization quando necessário.
• models.providers.*.baseUrl: base URL da API upstream.
• models.providers.*.headers: headers estáticos extras para roteamento de proxy/tenant.
• models.providers.*.request: substituições de transporte para requisições HTTP do model-provider.
  • request.headers: headers extras (mesclados com os padrões do provider). Os valores aceitam SecretRef.
  • request.auth: substituição da estratégia de autenticação. Modos: "provider-default" (usa a autenticação integrada do provider), "authorization-bearer" (com token), "header" (com headerName, value, prefix opcional).
  • request.proxy: substituição de proxy HTTP. Modos: "env-proxy" (usa as variáveis de ambiente HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (com url). Ambos os modos aceitam um subobjeto tls opcional.
  • request.tls: substituição de TLS para conexões diretas. Campos: ca, cert, key, passphrase (todos aceitam SecretRef), serverName, insecureSkipVerify.
  • request.allowPrivateNetwork: quando true, permite HTTPS para baseUrl quando o DNS resolve para intervalos privados, CGNAT ou semelhantes, via a proteção SSRF de fetch HTTP do provider (opt-in do operador para endpoints autohospedados confiáveis compatíveis com OpenAI). O WebSocket usa o mesmo request para headers/TLS, mas não essa proteção SSRF de fetch. Padrão false.
• models.providers.*.models: entradas explícitas do catálogo de modelos do provider.
• models.providers.*.models.*.contextWindow: metadados nativos da janela de contexto do modelo.
• models.providers.*.models.*.contextTokens: limite opcional de contexto em runtime. Use isso quando quiser um orçamento efetivo de contexto menor que o contextWindow nativo do modelo.
• models.providers.*.models.*.compat.supportsDeveloperRole: dica opcional de compatibilidade. Para api: "openai-completions" com um baseUrl não nativo não vazio (host diferente de api.openai.com), o OpenClaw força isso para false em runtime. baseUrl vazio/omitido mantém o comportamento padrão da OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas string. Quando true, o OpenClaw achata arrays puros de texto messages[].content em strings simples antes de enviar a requisição.
• plugins.entries.amazon-bedrock.config.discovery: raiz das configurações de descoberta automática do Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: ativa/desativa a descoberta implícita.
• plugins.entries.amazon-bedrock.config.discovery.region: região AWS para descoberta.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro opcional de ID do provider para descoberta direcionada.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervalo de polling para atualização de descoberta.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: fallback de janela de contexto para modelos descobertos.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: fallback de máximo de tokens de saída para modelos descobertos.

​

Exemplos de provider

{
  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

• Referência de configuração — outras chaves de nível superior
• Configuração — agentes
• Configuração — canais
• Ferramentas e Plugins