Configuração — ferramentas e provedores personalizados

Entrada de provedor (type: "provider" ou omitido):

• provider: ID do provedor da API (openai, anthropic, google/gemini, groq etc.)
• model: substituição do ID do modelo
• profile / preferredProfile: seleção de perfil em auth-profiles.json

Entrada de CLI (type: "cli"):

• command: executável a ser executado
• args: argumentos com modelos de substituição (compatíveis com {{MediaPath}}, {{Prompt}}, {{MaxChars}} etc.; openclaw doctor --fix migra os espaços reservados obsoletos {input} para {{MediaPath}})

Campos comuns:

• capabilities: lista opcional (image, audio, video). Cada Plugin de provedor declara seu próprio conjunto padrão de recursos; por exemplo, o provedor openai incluído usa imagem+áudio por padrão, anthropic/minimax usam imagem, google usa imagem+áudio+vídeo e groq usa áudio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: substituições por entrada.
• As entradas tools.media.image.timeoutSeconds e timeoutSeconds correspondentes do modelo de imagem também se aplicam quando o agente chama explicitamente a ferramenta image. Para compreensão de imagens, esse tempo limite se aplica à própria solicitação e não é reduzido pelo trabalho de preparação anterior.
• Em caso de falha, usa-se a próxima entrada.

A autenticação do provedor segue a ordem padrão: auth-profiles.json → variáveis de ambiente → models.providers.*.apiKey.

Campos de conclusão assíncrona:

• asyncCompletion.directSend: sinalizador de compatibilidade obsoleto. As tarefas assíncronas de mídia concluídas continuam mediadas pela sessão solicitante, para que o agente receba o resultado, decida como comunicá-lo ao usuário e use a ferramenta de mensagem quando a entrega à origem exigir isso.

• self: somente a chave da sessão atual.
• tree: sessão atual + sessões criadas 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 da sandbox: quando a sessão atual está em sandbox e agents.defaults.sandbox.sessionToolsVisibility="spawned" (o padrão), a visibilidade é forçada para tree, mesmo que tools.sessions.visibility="all".
• Quando não é all, sessions_list inclui um campo compacto visibility que descreve o modo efetivo e um aviso de que algumas sessões podem ser omitidas fora do escopo atual.

• Os anexos exigem enabled: true.
• Os anexos de subagentes são materializados no espaço de trabalho filho em .openclaw/attachments/<uuid>/, com um arquivo .manifest.json.
• Os anexos de ACP aceitam somente imagens e são encaminhados de forma embutida ao ambiente de execução ACP depois de aprovados os mesmos limites de quantidade de arquivos, bytes por arquivo e bytes totais.
• O conteúdo dos anexos é ocultado automaticamente da persistência da transcrição.
• As entradas Base64 são validadas com verificações rigorosas de alfabeto e preenchimento, além de uma proteção de tamanho antes da decodificação.
• As permissões dos arquivos de anexos de subagentes são 0700 para diretórios e 0600 para arquivos.
• A limpeza de subagentes segue a política cleanup: delete sempre remove os anexos; keep só os mantém quando retainOnSessionKeep: true.

• Use authHeader: true + headers para necessidades de autenticação personalizadas.
• Substitua o diretório raiz de configuração do agente com OPENCLAW_AGENT_DIR.
• Precedência de mesclagem para IDs de provedores correspondentes:
  • Valores baseUrl não vazios do models.json do agente têm precedência.
  • Valores apiKey não vazios do agente têm precedência somente quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação.
  • Valores apiKey de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (ENV_VAR_NAME para referências de ambiente, secretref-managed para referências de arquivo/execução), em vez de persistir segredos resolvidos.
  • Valores de cabeçalho de provedores gerenciados por SecretRef são atualizados a partir de marcadores de origem (secretref-env:ENV_VAR_NAME para referências de ambiente, secretref-managed para referências de arquivo/execução).
  • Valores apiKey/baseUrl do agente vazios ou ausentes usam como fallback models.providers na configuração.
  • Para contextWindow/maxTokens de modelos correspondentes: o valor explícito da configuração tem precedência quando está presente e é válido (um número positivo e finito); caso contrário, o valor implícito/gerado do catálogo é usado.
  • contextTokens de modelos correspondentes segue a mesma regra de precedência do valor explícito, ou, na ausência dele, do valor implícito; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo.
  • Catálogos de Plugins de provedor são armazenados como fragmentos de catálogo gerados e pertencentes ao Plugin no estado de Plugins do agente.
  • Use models.mode: "replace" quando quiser que a configuração reescreva completamente o models.json e ignore a mesclagem de fragmentos de catálogo pertencentes a Plugins.
  • A persistência de marcadores tem a origem como autoridade: os marcadores são gravados a partir do snapshot ativo da configuração de origem (antes da resolução), não a partir dos valores de segredo resolvidos em tempo de execução.

• models.mode: comportamento do catálogo de provedores (merge ou replace).
• models.providers: mapa personalizado de provedores indexado pelo ID do provedor.
  • 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ê forneça --replace.

• models.providers.*.api: adaptador de solicitação (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 auto-hospedados de /v1/chat/completions, como MLX, vLLM, SGLang e a maioria dos servidores locais compatíveis com OpenAI, use openai-completions. Um provedor personalizado com baseUrl, mas sem api, usa openai-completions por padrão; defina openai-responses somente quando o backend oferecer suporte a /v1/responses.
• models.providers.*.apiKey: credencial do provedor (prefira substituição por SecretRef/variável de ambiente).
• models.providers.*.auth: estratégia de autenticação (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: janela de contexto nativa padrão para os modelos deste provedor quando a entrada do modelo não define contextWindow.
• models.providers.*.contextTokens: limite efetivo padrão de contexto em tempo de execução para os modelos deste provedor quando a entrada do modelo não define contextTokens.
• models.providers.*.maxTokens: limite padrão de tokens de saída para os modelos deste provedor quando a entrada do modelo não define maxTokens.
• models.providers.*.timeoutSeconds: tempo limite opcional, por provedor, para solicitações HTTP do modelo, em segundos, incluindo conexão, cabeçalhos, corpo e tratamento de cancelamento da solicitação completa.
• models.providers.*.injectNumCtxForOpenAICompat: para Ollama + openai-completions, injeta options.num_ctx nas solicitações (padrão: true).
• models.providers.*.authHeader: força o transporte da credencial no cabeçalho Authorization quando necessário.
• models.providers.*.baseUrl: URL base da API upstream.
• models.providers.*.headers: cabeçalhos estáticos adicionais para roteamento por proxy/locatário.

models.providers.*.request: substituições de transporte para solicitações HTTP ao provedor do modelo.

• request.headers: cabeçalhos adicionais (mesclados com os padrões do provedor). Os valores aceitam SecretRef.
• request.auth: substituição da estratégia de autenticação. Modos: "provider-default" (usa a autenticação integrada do provedor), "authorization-bearer" (com token), "header" (com headerName, value e prefix opcional).
• request.proxy: substituição do 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 solicitações HTTP ao provedor do modelo para intervalos privados, CGNAT ou semelhantes por meio da proteção de busca HTTP do provedor. URLs base de provedores personalizados/locais já confiam na origem exata configurada, exceto origens de metadados/link-local, que continuam bloqueadas sem adesão explícita. Defina como false para desativar a confiança na origem exata. O WebSocket usa a mesma configuração request para cabeçalhos/TLS, mas não essa proteção contra SSRF na busca. Padrão: false.

• models.providers.*.models: entradas explícitas do catálogo de modelos do provedor.
• models.providers.*.models.*.input: modalidades de entrada do modelo. Use ["text"] para modelos somente de texto e ["text", "image"] para modelos nativos de imagem/visão. Anexos de imagem são injetados nos turnos do agente somente quando o modelo selecionado está marcado como compatível com imagens.
• models.providers.*.models.*.contextWindow: metadados da janela de contexto nativa do modelo. Isso substitui o contextWindow no nível do provedor para esse modelo.
• models.providers.*.models.*.contextTokens: limite opcional de contexto em tempo de execução. Isso substitui o contextTokens no nível do provedor; use-o quando quiser um orçamento de contexto efetivo menor que o contextWindow nativo do modelo; openclaw models list mostra ambos os valores quando são diferentes.
• models.providers.*.models.*.compat.supportsDeveloperRole: indicação opcional de compatibilidade. Para api: "openai-completions" com um baseUrl não vazio e não nativo (host diferente de api.openai.com), o OpenClaw força esse valor para false em tempo de execução. Um baseUrl vazio/omitido mantém o comportamento padrão da OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: indicação opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam somente strings. Quando true, o OpenClaw converte arrays messages[].content contendo somente texto em strings simples antes de enviar a solicitação.
• models.providers.*.models.*.compat.strictMessageKeys: indicação opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que sejam estritos. Quando true, o OpenClaw reduz os objetos de mensagem de Chat Completions enviados a role e content antes de enviar a solicitação.
• models.providers.*.models.*.compat.thinkingFormat: indicação opcional do payload de raciocínio. Use "together" para reasoning.enabled no estilo da Together, "qwen" para enable_thinking no nível superior ou "qwen-chat-template" para chat_template_kwargs.enable_thinking em servidores compatíveis com OpenAI da família Qwen que aceitem argumentos nomeados de modelo de chat no nível da solicitação, como o vLLM. Modelos Qwen configurados no vLLM expõem opções binárias de /think (off, on) para esses formatos.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: indicação opcional de compatibilidade para backends de Chat Completions no estilo do DeepSeek que exigem que mensagens anteriores do assistente mantenham reasoning_content durante a reprodução. Quando true, o OpenClaw preserva esse campo nas mensagens enviadas do assistente. Use isso ao conectar um proxy personalizado compatível com DeepSeek que rejeite solicitações após a remoção do raciocínio. Padrão: false.

• 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 da AWS para descoberta.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filtro opcional de ID do provedor para descoberta direcionada.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: intervalo de sondagem para atualização da descoberta.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: janela de contexto de fallback para modelos descobertos.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: quantidade máxima de tokens de saída de fallback para modelos descobertos.

O Plugin de provedor externo oficial cerebras pode configurar isso por meio de openclaw onboard --auth-choice cerebras-api-key. Use uma configuração explícita do provedor somente ao substituir os padrões.

{  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 a Cerebras; zai/glm-4.7 para acesso direto à Z.AI.

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

Provedor integrado compatível com Anthropic. Atalho: openclaw onboard --auth-choice kimi-code-api-key.

Consulte Modelos locais. Resumindo: execute um modelo local de grande porte pela API Responses do LM Studio em um hardware robusto; mantenha os modelos hospedados mesclados como fallback.

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

Defina MINIMAX_API_KEY. Atalhos: openclaw onboard --auth-choice minimax-global-api ou openclaw onboard --auth-choice minimax-cn-api. O catálogo de modelos usa o M3 por padrão e também inclui as variantes do M2.7. No caminho de streaming compatível com a Anthropic, o OpenClaw desativa por padrão o raciocínio do MiniMax M2.x, a menos que você defina explicitamente thinking; o MiniMax-M3 (e o M3.x) permanece por padrão no caminho de raciocínio omitido/adaptativo do provedor. /fast on ou params.fastMode: true reescreve 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 o endpoint da China: baseUrl: "https://api.moonshot.cn/v1" ou openclaw onboard --auth-choice moonshot-api-key-cn.

Os endpoints nativos da Moonshot anunciam compatibilidade com o uso de streaming no transporte compartilhado openai-completions, e o OpenClaw determina isso com base nos recursos do endpoint, não apenas no ID integrado do provedor.

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

Defina OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY). Use referências opencode/... para o catálogo Zen ou referências opencode-go/... para o catálogo Go. Atalho: openclaw onboard --auth-choice opencode-zen ou 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,          },        ],      },    },  },}

A URL base deve omitir /v1 (o cliente Anthropic a acrescenta). Atalho: openclaw onboard --auth-choice synthetic-api-key.

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

Defina ZAI_API_KEY. As referências de modelo usam o ID canônico de provedor zai/*. Atalho: openclaw onboard --auth-choice zai-api-key.

• Endpoint geral: https://api.z.ai/api/paas/v4
• Endpoint de programação: https://api.z.ai/api/coding/paas/v4
• A opção de autenticação padrão zai-api-key verifica sua chave e detecta automaticamente a qual endpoint ela pertence (recorrendo a uma solicitação, com o padrão Global, se a detecção for inconclusiva). Também estão disponíveis opções de autenticação dedicadas para CN e Coding-Plan, permitindo a seleção explícita.
• Para o endpoint geral, defina um provedor personalizado com a substituição da URL base.