~/.openclaw/openclaw.json.
O caminho da configuração ativa deve ser um arquivo regular. Layouts de openclaw.json
com symlink não são compatíveis para escritas pertencentes ao OpenClaw; uma escrita atômica pode substituir
o caminho em vez de preservar o symlink. Se você mantiver a configuração fora do
diretório de estado padrão, aponte OPENCLAW_CONFIG_PATH diretamente para o arquivo real.
Se o arquivo estiver ausente, o OpenClaw usará padrões seguros. Motivos comuns para adicionar uma configuração:
- Conectar canais e controlar quem pode enviar mensagens ao bot
- Definir modelos, ferramentas, sandboxing ou automação (cron, hooks)
- Ajustar sessões, mídia, rede ou UI
config.schema.lookup para obter a documentação exata
em nível de campo antes de editar a configuração. Use esta página para orientações orientadas a tarefas e a
referência de configuração para o mapa de campos
mais amplo e os padrões.
Configuração mínima
Editando a configuração
- Assistente interativo
- CLI (comandos curtos)
- Control UI
- Edição direta
Validação estrita
openclaw config schema imprime o JSON Schema canônico usado pela Control UI
e pela validação. config.schema.lookup busca um único nó com escopo por caminho mais
resumos dos filhos para ferramentas de detalhamento. Metadados de documentação de campo title/description
são preservados em objetos aninhados, wildcard (*), item de array ([]) e ramificações anyOf/
oneOf/allOf. Schemas de plugins e canais em tempo de execução são mesclados quando o
registro de manifesto é carregado.
Quando a validação falha:
- O Gateway não inicializa
- Apenas comandos de diagnóstico funcionam (
openclaw doctor,openclaw logs,openclaw health,openclaw status) - Execute
openclaw doctorpara ver os problemas exatos - Execute
openclaw doctor --fix(ou--yes) para aplicar reparos
openclaw.json
falhar na validação (incluindo validação local de plugin), a inicialização do Gateway falha ou
a recarga é ignorada e o runtime atual mantém a última configuração aceita.
Execute openclaw doctor --fix (ou --yes) para reparar configurações prefixadas/sobrescritas ou
restaurar a cópia da última configuração válida conhecida. A promoção para a última configuração válida conhecida é ignorada quando uma
candidata contém placeholders de segredos redigidos, como ***.
Tarefas comuns
Configurar um canal (WhatsApp, Telegram, Discord etc.)
Configurar um canal (WhatsApp, Telegram, Discord etc.)
channels.<provider>. Consulte a página dedicada do canal para ver as etapas de configuração:- WhatsApp -
channels.whatsapp - Telegram -
channels.telegram - Discord -
channels.discord - Feishu -
channels.feishu - Google Chat -
channels.googlechat - Microsoft Teams -
channels.msteams - Slack -
channels.slack - Signal -
channels.signal - iMessage -
channels.imessage - Mattermost -
channels.mattermost
Escolher e configurar modelos
Escolher e configurar modelos
agents.defaults.modelsdefine o catálogo de modelos e atua como allowlist para/model; entradasprovider/*filtram/model,/modelse seletores de modelo para provedores selecionados, enquanto ainda usam descoberta dinâmica de modelos.- Use
openclaw config set agents.defaults.models '<json>' --strict-json --mergepara adicionar entradas à allowlist sem remover modelos existentes. Substituições simples que removeriam entradas são rejeitadas, a menos que você passe--replace. - Referências de modelo usam o formato
provider/model(por exemplo,anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPxcontrola o redimensionamento de imagens de transcrição/ferramenta (padrão1200); valores menores normalmente reduzem o uso de tokens de visão em execuções com muitos screenshots.- Consulte CLI de modelos para alternar modelos no chat e Failover de modelo para rotação de autenticação e comportamento de fallback.
- Para provedores personalizados/auto-hospedados, consulte Provedores personalizados na referência.
Controlar quem pode enviar mensagens ao bot
Controlar quem pode enviar mensagens ao bot
dmPolicy:"pairing"(padrão): remetentes desconhecidos recebem um código de pareamento único para aprovação"allowlist": apenas remetentes emallowFrom(ou no armazenamento de permissões pareadas)"open": permite todas as DMs recebidas (requerallowFrom: ["*"])"disabled": ignora todas as DMs
groupPolicy + groupAllowFrom ou allowlists específicas do canal.Consulte a referência completa para detalhes por canal.Configurar gating de menções em chat de grupo
Configurar gating de menções em chat de grupo
- Menções por metadados: @-menções nativas (toque para mencionar no WhatsApp, @bot no Telegram etc.)
- Padrões de texto: padrões regex seguros em
mentionPatterns - Respostas visíveis:
messages.visibleRepliespode exigir envios por ferramenta de mensagem globalmente;messages.groupChat.visibleRepliessubstitui isso para grupos/canais. - Consulte a referência completa para modos de resposta visível, substituições por canal e modo de self-chat.
Restringir Skills por agente
Restringir Skills por agente
agents.defaults.skills para uma linha de base compartilhada e, em seguida, substitua em agentes
específicos com agents.list[].skills:- Omita
agents.defaults.skillspara Skills irrestritas por padrão. - Omita
agents.list[].skillspara herdar os padrões. - Defina
agents.list[].skills: []para nenhuma Skill. - Consulte Skills, Configuração de Skills e a referência de configuração.
Ajustar o monitoramento de integridade de canais do gateway
Ajustar o monitoramento de integridade de canais do gateway
- Defina
gateway.channelHealthCheckMinutes: 0para desabilitar reinicializações do monitor de integridade globalmente. channelStaleEventThresholdMinutesdeve ser maior ou igual ao intervalo de verificação.- Use
channels.<provider>.healthMonitor.enabledouchannels.<provider>.accounts.<id>.healthMonitor.enabledpara desabilitar reinicializações automáticas para um canal ou conta sem desabilitar o monitor global. - Consulte Verificações de integridade para depuração operacional e a referência completa para todos os campos.
Ajustar o tempo limite do handshake WebSocket do gateway
Ajustar o tempo limite do handshake WebSocket do gateway
- O padrão é
15000milissegundos. OPENCLAW_HANDSHAKE_TIMEOUT_MSainda tem precedência para substituições pontuais de serviço ou shell.- Prefira corrigir primeiro travamentos de inicialização/event loop; este controle é para hosts que estão saudáveis, mas lentos durante o aquecimento.
Configurar sessões e redefinições
Configurar sessões e redefinições
dmScope:main(compartilhado) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: padrões globais para roteamento de sessões vinculadas a threads (Discord oferece suporte a/focus,/unfocus,/agents,/session idlee/session max-age).- Consulte Gerenciamento de sessões para escopo, vínculos de identidade e política de envio.
- Consulte a referência completa para todos os campos.
Habilitar isolamento em sandbox
Habilitar isolamento em sandbox
scripts/sandbox-setup.sh; ou, a partir de uma instalação npm, consulte o comando docker build embutido em Sandboxing § Imagens e configuração.Consulte Sandboxing para o guia completo e a referência completa para todas as opções.Habilitar push apoiado por relay para builds oficiais do iOS
Habilitar push apoiado por relay para builds oficiais do iOS
https://ios-push-relay.openclaw.ai.Implantações de relay personalizadas exigem um caminho de build/implantação iOS deliberadamente separado, cuja URL de relay corresponda à URL de relay do Gateway. Se você estiver usando um build de relay personalizado, defina isto na configuração do gateway:- Permite que o gateway envie
push.test, estímulos de ativação e ativações de reconexão pelo relay externo. - Usa uma concessão de envio com escopo de registro encaminhada pelo app iOS pareado. O gateway não precisa de um token de relay amplo da implantação.
- Vincula cada registro apoiado por relay à identidade do gateway com a qual o app iOS foi pareado, para que outro gateway não possa reutilizar o registro armazenado.
- Mantém builds iOS locais/manuais em APNs direto. Envios apoiados por relay se aplicam apenas a builds distribuídos oficiais registrados pelo relay.
- Deve corresponder à URL base de relay incorporada ao build iOS, para que o tráfego de registro e envio chegue à mesma implantação de relay.
- Instale o app iOS oficial.
- Opcional: configure
gateway.push.apns.relay.baseUrlno gateway somente ao usar um build de relay personalizado deliberadamente separado. - Pareie o app iOS com o gateway e permita que as sessões de nó e operador se conectem.
- O app iOS busca a identidade do gateway, registra-se no relay usando App Attest mais o recibo do app e então publica a carga
push.apns.registerapoiada por relay no gateway pareado. - O gateway armazena o identificador de relay e a concessão de envio, depois os usa para
push.test, estímulos de ativação e ativações de reconexão.
- Se você trocar o app iOS para outro gateway, reconecte o app para que ele possa publicar um novo registro de relay vinculado a esse gateway.
- Se você enviar um novo build iOS que aponta para uma implantação de relay diferente, o app atualiza seu registro de relay em cache em vez de reutilizar a origem de relay antiga.
OPENCLAW_APNS_RELAY_BASE_URLeOPENCLAW_APNS_RELAY_TIMEOUT_MSainda funcionam como substituições temporárias de env.- URLs de relay de gateway personalizadas devem corresponder à URL base de relay incorporada ao build iOS. A faixa de lançamento pública da App Store rejeita substituições de URL de relay iOS personalizadas.
OPENCLAW_APNS_RELAY_ALLOW_HTTP=truecontinua sendo uma válvula de escape de desenvolvimento apenas para loopback; não persista URLs de relay HTTP na configuração.
Configurar Heartbeat (check-ins periódicos)
Configurar Heartbeat (check-ins periódicos)
every: string de duração (30m,2h). Defina0mpara desabilitar.target:last|none|<channel-id>(por exemplodiscord,matrix,telegramouwhatsapp)directPolicy:allow(padrão) oublockpara destinos de Heartbeat no estilo DM- Consulte Heartbeat para o guia completo.
Configurar tarefas Cron
Configurar tarefas Cron
sessionRetention: remove sessões de execução isoladas concluídas desessions.json(padrão24h; definafalsepara desabilitar).runLog: remove linhas retidas do histórico de execuções de Cron por tarefa.maxBytescontinua aceito para logs de execução antigos baseados em arquivo.- Consulte Tarefas Cron para a visão geral do recurso e exemplos de CLI.
Configurar Webhooks (hooks)
Configurar Webhooks (hooks)
- Trate todo o conteúdo de payload de hook/Webhook como entrada não confiável.
- Use um
hooks.tokendedicado; não reutilize segredos ativos de autenticação do Gateway (gateway.auth.token/OPENCLAW_GATEWAY_TOKENougateway.auth.password/OPENCLAW_GATEWAY_PASSWORD). - A autenticação de hook é somente por cabeçalho (
Authorization: Bearer ...oux-openclaw-token); tokens em query string são rejeitados. hooks.pathnão pode ser/; mantenha a entrada de Webhook em um subcaminho dedicado, como/hooks.- Mantenha os flags de desvio de conteúdo inseguro desabilitados (
hooks.gmail.allowUnsafeExternalContent,hooks.mappings[].allowUnsafeExternalContent), exceto ao fazer depuração com escopo bem restrito. - Se você habilitar
hooks.allowRequestSessionKey, também definahooks.allowedSessionKeyPrefixespara limitar chaves de sessão selecionadas pelo chamador. - Para agentes acionados por hook, prefira tiers de modelos modernos fortes e política de ferramentas estrita (por exemplo, somente mensagens mais sandboxing quando possível).
Configurar roteamento multiagente
Configurar roteamento multiagente
Dividir configuração em vários arquivos ($include)
Dividir configuração em vários arquivos ($include)
$include para organizar configurações grandes:- Arquivo único: substitui o objeto contêiner
- Array de arquivos: mesclado profundamente em ordem (o posterior vence)
- Chaves irmãs: mescladas após includes (substituem valores incluídos)
- Includes aninhados: compatíveis até 10 níveis de profundidade
- Caminhos relativos: resolvidos em relação ao arquivo que inclui
- Formato de caminho: caminhos de include não devem conter bytes nulos e devem ter estritamente menos de 4096 caracteres antes e depois da resolução
- Escritas pertencentes ao OpenClaw: quando uma escrita altera apenas uma seção de nível superior
apoiada por um include de arquivo único, como
plugins: { $include: "./plugins.json5" }, o OpenClaw atualiza esse arquivo incluído e deixaopenclaw.jsonintacto - Write-through sem suporte: includes raiz, arrays de include e includes com substituições irmãs falham de forma fechada para escritas pertencentes ao OpenClaw, em vez de achatar a configuração
- Confinamento: caminhos
$includedevem ser resolvidos abaixo do diretório que contémopenclaw.json. Para compartilhar uma árvore entre máquinas ou usuários, definaOPENCLAW_INCLUDE_ROOTScomo uma lista de caminhos (:no POSIX,;no Windows) de diretórios adicionais que includes podem referenciar. Symlinks são resolvidos e verificados novamente, portanto um caminho que lexicalmente fica em um diretório de configuração, mas cujo destino real escapa de toda raiz permitida, ainda é rejeitado. - Tratamento de erros: erros claros para arquivos ausentes, erros de análise, includes circulares, formato de caminho inválido e comprimento excessivo
Recarga a quente da configuração
O Gateway monitora~/.openclaw/openclaw.json e aplica alterações automaticamente - nenhuma reinicialização manual é necessária para a maioria das configurações.
Edições diretas de arquivo são tratadas como não confiáveis até serem validadas. O monitor aguarda
a agitação de escrita temporária/renomeação do editor se estabilizar, lê o arquivo final e rejeita
edições externas inválidas sem reescrever openclaw.json. Escritas de configuração
pertencentes ao OpenClaw usam o mesmo gate de esquema antes de escrever; substituições destrutivas, como
remover gateway.mode ou reduzir o arquivo em mais da metade, são rejeitadas e
salvas como .rejected.* para inspeção.
Se você vir config reload skipped (invalid config) ou a inicialização relatar Invalid config, inspecione a configuração, execute openclaw config validate e então execute openclaw doctor --fix para reparo. Consulte Solução de problemas do Gateway
para a checklist.
Modos de recarga
| Modo | Comportamento |
|---|---|
hybrid (padrão) | Aplica alterações seguras a quente instantaneamente. Reinicia automaticamente para as críticas. |
hot | Aplica somente alterações seguras a quente. Registra um aviso quando uma reinicialização é necessária - você cuida disso. |
restart | Reinicia o Gateway em qualquer alteração de configuração, segura ou não. |
off | Desabilita o monitoramento de arquivo. As alterações entram em vigor na próxima reinicialização manual. |
O que aplica a quente vs. o que precisa de reinicialização
A maioria dos campos é aplicada a quente sem indisponibilidade. No modohybrid, alterações que exigem reinicialização são tratadas automaticamente.
| Categoria | Campos | Reinício necessário? |
|---|---|---|
| Canais | channels.*, web (WhatsApp) - todos os canais integrados e de plugin | Não |
| Agente e modelos | agent, agents, models, routing | Não |
| Automação | hooks, cron, agent.heartbeat | Não |
| Sessões e mensagens | session, messages | Não |
| Ferramentas e mídia | tools, browser, skills, mcp, audio, talk | Não |
| UI e diversos | ui, logging, identity, bindings | Não |
| Servidor Gateway | gateway.* (port, bind, auth, tailscale, TLS, HTTP) | Sim |
| Infraestrutura | discovery, plugins | Sim |
gateway.reload e gateway.remote são exceções - alterá-los não aciona um reinício.Planejamento de recarregamento
Quando você edita um arquivo de origem referenciado por$include, o OpenClaw planeja
o recarregamento a partir do layout criado na origem, não da visualização achatada em memória.
Isso mantém as decisões de recarregamento a quente (aplicação a quente vs reinício) previsíveis, mesmo quando uma
única seção de nível superior vive em seu próprio arquivo incluído, como
plugins: { $include: "./plugins.json5" }. O planejamento de recarregamento falha de forma fechada se o
layout de origem for ambíguo.
RPC de configuração (atualizações programáticas)
Para ferramentas que gravam configuração pela API do Gateway, prefira este fluxo:config.schema.lookuppara inspecionar uma subárvore (nó de esquema superficial + resumos de filhos)config.getpara buscar o snapshot atual maishashconfig.patchpara atualizações parciais (patch de mesclagem JSON: objetos são mesclados,nullexclui, arrays são substituídos quando explicitamente confirmados comreplacePathsse entradas seriam removidas)config.applysomente quando você pretende substituir a configuração inteiraupdate.runpara autoatualização explícita mais reinício; incluacontinuationMessagequando a sessão pós-reinício deve executar uma rodada de acompanhamentoupdate.statuspara inspecionar o sentinela de reinício da atualização mais recente e verificar a versão em execução após um reinício
config.schema.lookup como o primeiro ponto de consulta para documentação e restrições
exatas em nível de campo. Use Referência de configuração
quando precisarem do mapa de configuração mais amplo, padrões ou links para referências dedicadas
de subsistemas.
config.apply, config.patch, update.run) são
limitadas a 3 solicitações por 60 segundos por deviceId+clientIp. Solicitações de reinício
são agrupadas e, em seguida, aplicam um período de espera de 30 segundos entre ciclos de reinício.
update.status é somente leitura, mas tem escopo de administrador, porque o sentinela de reinício pode
incluir resumos de etapas de atualização e trechos finais da saída de comandos.config.apply quanto config.patch aceitam raw, baseHash, sessionKey,
note e restartDelayMs. baseHash é obrigatório para ambos os métodos quando uma
configuração já existe.
config.patch também aceita replacePaths, um array de caminhos de configuração cuja substituição de array
é intencional. Se um patch substituísse ou excluísse um array existente
com menos entradas, o Gateway rejeita a gravação, a menos que esse caminho exato apareça
em replacePaths; arrays aninhados sob entradas de array usam [], como
agents.list[].skills. Isso impede que snapshots truncados de config.get
sobrescrevam silenciosamente arrays de roteamento ou listas de permissões. Use config.apply quando você
pretende substituir a configuração completa.
Variáveis de ambiente
O OpenClaw lê variáveis de ambiente do processo pai mais:.envdo diretório de trabalho atual (se presente)~/.openclaw/.env(fallback global)
Importação de ambiente do shell (opcional)
Importação de ambiente do shell (opcional)
OPENCLAW_LOAD_SHELL_ENV=1Substituição de variáveis de ambiente em valores de configuração
Substituição de variáveis de ambiente em valores de configuração
${VAR_NAME}:- Somente nomes em maiúsculas correspondem:
[A-Z_][A-Z0-9_]* - Variáveis ausentes/vazias geram um erro no momento do carregamento
- Faça escape com
$${VAR}para saída literal - Funciona dentro de arquivos
$include - Substituição inline:
"${BASE}/v1"→"https://api.example.com/v1"
Referências a segredos (env, file, exec)
Referências a segredos (env, file, exec)
secrets.providers para env/file/exec) estão em Gerenciamento de segredos.
Os caminhos de credenciais compatíveis estão listados em Superfície de credenciais SecretRef.Referência completa
Para a referência completa campo por campo, consulte Referência de configuração.Relacionado: Exemplos de configuração · Referência de configuração · Doctor