Perguntas frequentes

OpenClaw é um assistente pessoal de IA que você executa nos seus próprios dispositivos. Ele responde nas superfícies de mensagem que você já usa (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat e plugins de canal incluídos, como QQ Bot) e também pode usar voz + um Canvas ao vivo em plataformas compatíveis. O Gateway é o plano de controle sempre ativo; o assistente é o produto.

OpenClaw não é "apenas um wrapper do Claude." É um plano de controle local-first que permite executar um assistente capaz no seu próprio hardware, acessível pelos aplicativos de chat que você já usa, com sessões com estado, memória e ferramentas - sem entregar o controle dos seus fluxos de trabalho a um SaaS hospedado.

Destaques:

• Seus dispositivos, seus dados: execute o Gateway onde quiser (Mac, Linux, VPS) e mantenha o workspace + histórico de sessões local.
• Canais reais, não uma sandbox web: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, além de voz móvel e Canvas em plataformas compatíveis.
• Independente de modelo: use Anthropic, OpenAI, MiniMax, OpenRouter, etc., com roteamento por agente e failover.
• Opção somente local: execute modelos locais para que todos os dados possam ficar no seu dispositivo se você quiser.
• Roteamento multiagente: agentes separados por canal, conta ou tarefa, cada um com seu próprio workspace e padrões.
• Código aberto e hackeável: inspecione, estenda e hospede você mesmo sem dependência de fornecedor.

Docs: Gateway, Canais, Multiagente, Memória.

Bons primeiros projetos:

• Criar um site (WordPress, Shopify ou um site estático simples).
• Prototipar um aplicativo móvel (esboço, telas, plano de API).
• Organizar arquivos e pastas (limpeza, nomes, marcação).
• Conectar o Gmail e automatizar resumos ou acompanhamentos.

Ele consegue lidar com tarefas grandes, mas funciona melhor quando você as divide em fases e usa subagentes para trabalho paralelo.

Ganhos cotidianos geralmente são assim:

• Briefings pessoais: resumos de caixa de entrada, calendário e notícias que importam para você.
• Pesquisa e redação: pesquisa rápida, resumos e primeiros rascunhos para e-mails ou documentos.
• Lembretes e acompanhamentos: avisos e checklists acionados por Cron ou Heartbeat.
• Automação de navegador: preencher formulários, coletar dados e repetir tarefas web.
• Coordenação entre dispositivos: envie uma tarefa do seu telefone, deixe o Gateway executá-la em um servidor e receba o resultado de volta no chat.

Sim para pesquisa, qualificação e redação. Ele pode varrer sites, criar listas curtas, resumir prospects e escrever rascunhos de prospecção ou textos de anúncios.

Para ações de prospecção ou anúncios, mantenha um humano no fluxo. Evite spam, siga as leis locais e as políticas das plataformas, e revise tudo antes do envio. O padrão mais seguro é deixar o OpenClaw redigir e você aprovar.

Docs: Segurança.

OpenClaw é um assistente pessoal e uma camada de coordenação, não um substituto de IDE. Use Claude Code ou Codex para o loop de codificação direta mais rápido dentro de um repositório. Use OpenClaw quando você quiser memória durável, acesso entre dispositivos e orquestração de ferramentas.

Vantagens:

• Memória persistente + workspace entre sessões
• Acesso multiplataforma (WhatsApp, Telegram, TUI, WebChat)
• Orquestração de ferramentas (navegador, arquivos, agendamento, hooks)
• Gateway sempre ativo (execute em uma VPS, interaja de qualquer lugar)
• Nodes para navegador/tela/câmera/exec locais

Showcase: https://openclaw.ai/showcase

Use substituições gerenciadas em vez de editar a cópia do repositório. Coloque suas alterações em ~/.openclaw/skills/<name>/SKILL.md (ou adicione uma pasta via skills.load.extraDirs em ~/.openclaw/openclaw.json). A precedência é <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → incluídas → skills.load.extraDirs, então substituições gerenciadas ainda vencem Skills incluídas sem tocar no git. Se você precisar que a skill seja instalada globalmente, mas visível apenas para alguns agentes, mantenha a cópia compartilhada em ~/.openclaw/skills e controle a visibilidade com agents.defaults.skills e agents.list[].skills. Apenas edições que merecem ir para upstream devem ficar no repositório e sair como PRs.

Sim. Adicione diretórios extras via skills.load.extraDirs em ~/.openclaw/openclaw.json (menor precedência). A precedência padrão é <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → incluídas → skills.load.extraDirs. clawhub instala em ./skills por padrão, que o OpenClaw trata como <workspace>/skills na próxima sessão. Se a skill deve ficar visível apenas para certos agentes, combine isso com agents.defaults.skills ou agents.list[].skills.

Hoje, os padrões compatíveis são:

• Trabalhos Cron: trabalhos isolados podem definir uma substituição de model por trabalho.
• Subagentes: roteie tarefas para agentes separados com modelos padrão diferentes.
• Troca sob demanda: use /model para trocar o modelo da sessão atual a qualquer momento.

Consulte Trabalhos Cron, Roteamento Multiagente e Comandos de barra.

Use subagentes para tarefas longas ou paralelas. Subagentes executam na própria sessão, retornam um resumo e mantêm seu chat principal responsivo.

Peça ao bot para "gerar um subagente para esta tarefa" ou use /subagents. Use /status no chat para ver o que o Gateway está fazendo agora (e se ele está ocupado).

Dica sobre tokens: tarefas longas e subagentes consomem tokens. Se custo for uma preocupação, defina um modelo mais barato para subagentes via agents.defaults.subagents.model.

Docs: Subagentes, Tarefas em segundo plano.

Use vinculações de thread. Você pode vincular uma thread do Discord a um subagente ou destino de sessão para que mensagens de acompanhamento nessa thread permaneçam nessa sessão vinculada.

Fluxo básico:

• Gere com sessions_spawn usando thread: true (e opcionalmente mode: "session" para acompanhamento persistente).
• Ou vincule manualmente com /focus <target>.
• Use /agents para inspecionar o estado da vinculação.
• Use /session idle <duration|off> e /session max-age <duration|off> para controlar o auto-unfocus.
• Use /unfocus para desvincular a thread.

Configuração obrigatória:

• Padrões globais: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Substituições do Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
• Vinculação automática ao gerar: channels.discord.threadBindings.spawnSessions usa true por padrão; defina como false para desativar gerações de sessão vinculadas a thread.

Docs: Subagentes, Discord, Referência de configuração, Comandos de barra.

Verifique primeiro a rota resolvida do solicitante:

• A entrega de subagente em modo de conclusão prefere qualquer thread vinculada ou rota de conversa quando existir.
• Se a origem da conclusão carrega apenas um canal, OpenClaw recorre à rota armazenada da sessão solicitante (lastChannel / lastTo / lastAccountId) para que a entrega direta ainda possa ter sucesso.
• Se não houver uma rota vinculada nem uma rota armazenada utilizável, a entrega direta pode falhar e o resultado volta para entrega enfileirada da sessão em vez de ser publicado imediatamente no chat.
• Destinos inválidos ou obsoletos ainda podem forçar fallback para fila ou falha final de entrega.
• Se a última resposta visível do assistente filho for o token silencioso exato NO_REPLY / no_reply, ou exatamente ANNOUNCE_SKIP, OpenClaw suprime intencionalmente o anúncio em vez de publicar progresso anterior obsoleto.
• Se o filho excedeu o tempo limite após apenas chamadas de ferramentas, o anúncio pode condensar isso em um resumo curto de progresso parcial em vez de reproduzir saída bruta de ferramentas.

Depuração:

openclaw tasks show <runId-or-sessionKey>

Docs: Subagentes, Tarefas em segundo plano, Ferramentas de sessão.

Cron executa dentro do processo do Gateway. Se o Gateway não estiver em execução continuamente, trabalhos agendados não serão executados.

Checklist:

• Confirme que cron está ativado (cron.enabled) e que OPENCLAW_SKIP_CRON não está definido.
• Verifique se o Gateway está em execução 24/7 (sem suspensão/reinicializações).
• Verifique as configurações de fuso horário do trabalho (--tz versus fuso horário do host).

Depuração:

openclaw cron run <jobId>
openclaw cron runs --id <jobId> --limit 50

Docs: Trabalhos Cron, Automação e tarefas.

Verifique primeiro o modo de entrega:

• --no-deliver / delivery.mode: "none" significa que nenhum envio de fallback do executor é esperado.
• Um destino de anúncio ausente ou inválido (channel / to) significa que o executor ignorou a entrega de saída.
• Falhas de autenticação do canal (unauthorized, Forbidden) significam que o executor tentou entregar, mas as credenciais bloquearam a entrega.
• Um resultado isolado silencioso (somente NO_REPLY / no_reply) é tratado como intencionalmente não entregável, então o executor também suprime a entrega de fallback enfileirada.

Para trabalhos de Cron isolados, o agente ainda pode enviar diretamente com a ferramenta message quando uma rota de chat estiver disponível. --announce controla apenas o caminho de fallback do executor para o texto final que o agente ainda não enviou.

Depuração:

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

Documentação: Trabalhos de Cron, Tarefas em segundo plano.

Isso geralmente é o caminho de troca de modelo ao vivo, não agendamento duplicado.

Cron isolado pode persistir uma transferência de modelo em tempo de execução e tentar novamente quando a execução ativa lança LiveSessionModelSwitchError. A nova tentativa mantém o provedor/modelo trocado e, se a troca carregou uma nova substituição de perfil de autenticação, o Cron também a persiste antes de tentar novamente.

Regras de seleção relacionadas:

• A substituição de modelo do hook do Gmail vence primeiro quando aplicável.
• Depois, model por trabalho.
• Depois, qualquer substituição de modelo armazenada da sessão de Cron.
• Depois, a seleção normal de modelo do agente/padrão.

O loop de repetição é limitado. Após a tentativa inicial mais 2 novas tentativas de troca, o Cron aborta em vez de ficar em loop para sempre.

Depuração:

openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>

Documentação: Trabalhos de Cron, CLI de Cron.

Use comandos nativos openclaw skills ou coloque Skills no seu workspace. A interface de Skills do macOS não está disponível no Linux. Procure Skills em https://clawhub.ai.

openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check

O openclaw skills install nativo grava no diretório skills/ do workspace ativo. Instale a CLI clawhub separada somente se quiser publicar ou sincronizar suas próprias Skills. Para instalações compartilhadas entre agentes, coloque a Skill em ~/.openclaw/skills e use agents.defaults.skills ou agents.list[].skills se quiser restringir quais agentes podem vê-la.

Sim. Use o agendador do Gateway:

• Trabalhos de Cron para tarefas agendadas ou recorrentes (persistem entre reinicializações).
• Heartbeat para verificações periódicas da "sessão principal".
• Trabalhos isolados para agentes autônomos que publicam resumos ou entregam em chats.

Documentação: Trabalhos de Cron, Automação e tarefas, Heartbeat.

Não diretamente. Skills do macOS são controladas por metadata.openclaw.os mais os binários necessários, e as Skills só aparecem no prompt do sistema quando são elegíveis no host do Gateway. No Linux, Skills exclusivas de darwin (como apple-notes, apple-reminders, things-mac) não serão carregadas a menos que você substitua esse controle.

Você tem três padrões compatíveis:

Opção A - execute o Gateway em um Mac (mais simples). Execute o Gateway onde os binários do macOS existem e depois conecte a partir do Linux no modo remoto ou por Tailscale. As Skills são carregadas normalmente porque o host do Gateway é macOS.

Opção B - use um Node macOS (sem SSH). Execute o Gateway no Linux, pareie um Node macOS (app da barra de menus) e defina Comandos de execução do Node como "Sempre perguntar" ou "Sempre permitir" no Mac. O OpenClaw pode tratar Skills exclusivas do macOS como elegíveis quando os binários necessários existem no Node. O agente executa essas Skills por meio da ferramenta nodes. Se você escolher "Sempre perguntar", aprovar "Sempre permitir" no prompt adiciona esse comando à lista de permissões.

Opção C - faça proxy de binários do macOS via SSH (avançado). Mantenha o Gateway no Linux, mas faça com que os binários de CLI necessários resolvam para wrappers SSH que executam em um Mac. Depois, substitua a Skill para permitir Linux, para que ela permaneça elegível.

1. Crie um wrapper SSH para o binário (exemplo: memo para Apple Notes):

   #!/usr/bin/env bash
   set -euo pipefail
   exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
   

2. Coloque o wrapper no PATH no host Linux (por exemplo, ~/bin/memo).

3. Substitua os metadados da Skill (workspace ou ~/.openclaw/skills) para permitir Linux:

   ---
   name: apple-notes
   description: Manage Apple Notes via the memo CLI on macOS.
   metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
   ---
   

4. Inicie uma nova sessão para que o snapshot de Skills seja atualizado.

Não integrada hoje.

Opções:

• Skill / Plugin personalizado: melhor para acesso confiável por API (Notion/HeyGen têm APIs).
• Automação de navegador: funciona sem código, mas é mais lenta e mais frágil.

Se você quiser manter o contexto por cliente (fluxos de trabalho de agência), um padrão simples é:

• Uma página do Notion por cliente (contexto + preferências + trabalho ativo).
• Peça ao agente para buscar essa página no início de uma sessão.

Se quiser uma integração nativa, abra uma solicitação de recurso ou crie uma Skill direcionada a essas APIs.

Instale Skills:

openclaw skills install <skill-slug>
openclaw skills update --all

Instalações nativas vão para o diretório skills/ do workspace ativo. Para Skills compartilhadas entre agentes, coloque-as em ~/.openclaw/skills/<name>/SKILL.md. Se apenas alguns agentes devem ver uma instalação compartilhada, configure agents.defaults.skills ou agents.list[].skills. Algumas Skills esperam binários instalados via Homebrew; no Linux, isso significa Linuxbrew (veja a entrada de FAQ do Homebrew para Linux acima). Veja Skills, Configuração de Skills e ClawHub.

Use o perfil de navegador user integrado, que se conecta por meio do Chrome DevTools MCP:

openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot

Se quiser um nome personalizado, crie um perfil MCP explícito:

openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs

Esse caminho pode usar o navegador do host local ou um Node de navegador conectado. Se o Gateway executar em outro lugar, execute um host de Node na máquina do navegador ou use CDP remoto.

Limites atuais em existing-session / user:

• as ações são orientadas por ref, não por seletor CSS
• uploads exigem ref / inputRef e atualmente aceitam um arquivo por vez
• responsebody, exportação de PDF, interceptação de download e ações em lote ainda precisam de um navegador gerenciado ou perfil CDP bruto

Sim. Veja Sandboxing. Para configuração específica de Docker (Gateway completo no Docker ou imagens de sandbox), veja Docker.

A imagem padrão prioriza segurança e executa como o usuário node, então ela não inclui pacotes do sistema, Homebrew ou navegadores incluídos. Para uma configuração mais completa:

• Persista /home/node com OPENCLAW_HOME_VOLUME para que os caches sobrevivam.
• Inclua dependências do sistema na imagem com OPENCLAW_DOCKER_APT_PACKAGES.
• Instale navegadores Playwright via CLI incluída: node /app/node_modules/playwright-core/cli.js install chromium
• Defina PLAYWRIGHT_BROWSERS_PATH e garanta que o caminho seja persistido.

Documentação: Docker, Navegador.

Sim - se seu tráfego privado for DMs e seu tráfego público for grupos.

Use agents.defaults.sandbox.mode: "non-main" para que sessões de grupo/canal (chaves não principais) executem no backend de sandbox configurado, enquanto a sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um. Depois, restrinja quais ferramentas ficam disponíveis em sessões com sandbox via tools.sandbox.tools.

Passo a passo de configuração + exemplo de configuração: Grupos: DMs pessoais + grupos públicos

Referência de configuração principal: Configuração do Gateway

Defina agents.defaults.sandbox.docker.binds como ["host:path:mode"] (por exemplo, "/home/user/src:/src:ro"). Vinculações globais + por agente são mescladas; vinculações por agente são ignoradas quando scope: "shared". Use :ro para qualquer coisa sensível e lembre-se de que vinculações contornam as paredes do sistema de arquivos do sandbox.

O OpenClaw valida origens de vinculação tanto contra o caminho normalizado quanto contra o caminho canônico resolvido pelo ancestral existente mais profundo. Isso significa que escapes por pai de symlink ainda falham fechados mesmo quando o último segmento do caminho ainda não existe, e as verificações de raiz permitida ainda se aplicam após a resolução de symlink.

Veja Sandboxing e Sandbox vs política de ferramentas vs elevado para exemplos e notas de segurança.

A memória do OpenClaw é apenas arquivos Markdown no workspace do agente:

• Notas diárias em memory/YYYY-MM-DD.md
• Notas de longo prazo selecionadas em MEMORY.md (somente sessões principais/privadas)

O OpenClaw também executa uma descarga silenciosa de memória pré-Compaction para lembrar o modelo de escrever notas duráveis antes da Compaction automática. Isso só executa quando o workspace é gravável (sandboxes somente leitura pulam essa etapa). Veja Memória.

Peça ao bot para escrever o fato na memória. Notas de longo prazo pertencem a MEMORY.md, contexto de curto prazo vai para memory/YYYY-MM-DD.md.

Essa ainda é uma área que estamos melhorando. Ajuda lembrar o modelo de armazenar memórias; ele saberá o que fazer. Se ele continuar esquecendo, verifique se o Gateway está usando o mesmo workspace em todas as execuções.

Documentação: Memória, Workspace do agente.

Arquivos de memória vivem no disco e persistem até você excluí-los. O limite é seu armazenamento, não o modelo. O contexto da sessão ainda é limitado pela janela de contexto do modelo, então conversas longas podem passar por Compaction ou ser truncadas. É por isso que a busca de memória existe - ela traz de volta para o contexto apenas as partes relevantes.

Documentação: Memória, Contexto.

Somente se você usar embeddings da OpenAI. O OAuth do Codex cobre chat/completions e não concede acesso a embeddings, portanto entrar com o Codex (OAuth ou o login da Codex CLI) não ajuda na busca semântica de memória. Embeddings da OpenAI ainda precisam de uma chave de API real (OPENAI_API_KEY ou models.providers.openai.apiKey).

Se você não definir um provedor explicitamente, o OpenClaw seleciona automaticamente um provedor quando consegue resolver uma chave de API (perfis de autenticação, models.providers.*.apiKey ou variáveis de ambiente). Ele prefere a OpenAI se uma chave da OpenAI for resolvida; caso contrário, Gemini se uma chave da Gemini for resolvida, depois Voyage e depois Mistral. Se nenhuma chave remota estiver disponível, a busca de memória permanece desativada até você configurá-la. Se você tiver um caminho de modelo local configurado e presente, o OpenClaw prefere local. O Ollama é compatível quando você define explicitamente memorySearch.provider = "ollama".

Se preferir permanecer local, defina memorySearch.provider = "local" (e opcionalmente memorySearch.fallback = "none"). Se quiser embeddings do Gemini, defina memorySearch.provider = "gemini" e forneça GEMINI_API_KEY (ou memorySearch.remote.apiKey). Oferecemos suporte a modelos de embedding OpenAI, Gemini, Voyage, Mistral, Ollama ou local - consulte Memória para ver os detalhes de configuração.

Não - o estado do OpenClaw é local, mas serviços externos ainda veem o que você envia a eles.

• Local por padrão: sessões, arquivos de memória, configuração e workspace ficam no host do Gateway (~/.openclaw + o diretório do seu workspace).
• Remoto por necessidade: mensagens que você envia para provedores de modelo (Anthropic/OpenAI/etc.) vão para as APIs deles, e plataformas de chat (WhatsApp/Telegram/Slack/etc.) armazenam dados de mensagens em seus servidores.
• Você controla a pegada: usar modelos locais mantém os prompts na sua máquina, mas o tráfego do canal ainda passa pelos servidores do canal.

Relacionado: Workspace do agente, Memória.

Tudo fica em $OPENCLAW_STATE_DIR (padrão: ~/.openclaw):

Caminho legado de agente único: ~/.openclaw/agent/* (migrado por openclaw doctor).

Seu workspace (AGENTS.md, arquivos de memória, skills etc.) é separado e configurado via agents.defaults.workspace (padrão: ~/.openclaw/workspace).

Esses arquivos ficam no workspace do agente, não em ~/.openclaw.

• Workspace (por agente): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, HEARTBEAT.md opcional. A raiz em minúsculas memory.md é apenas entrada de reparo legada; openclaw doctor --fix pode mesclá-la em MEMORY.md quando ambos os arquivos existem.
• Diretório de estado (~/.openclaw): configuração, estado de canal/provedor, perfis de autenticação, sessões, logs e Skills compartilhadas (~/.openclaw/skills).

O workspace padrão é ~/.openclaw/workspace, configurável via:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

Se o bot "esquecer" depois de uma reinicialização, confirme se o Gateway está usando o mesmo workspace em cada inicialização (e lembre-se: o modo remoto usa o workspace do host do gateway, não o seu laptop local).

Dica: se você quiser um comportamento ou preferência durável, peça ao bot para escrevê-lo em AGENTS.md ou MEMORY.md em vez de depender do histórico do chat.

Consulte Workspace do agente e Memória.

Coloque seu workspace do agente em um repositório git privado e faça backup dele em algum lugar privado (por exemplo, GitHub privado). Isso captura memória + arquivos AGENTS/SOUL/USER e permite restaurar a "mente" do assistente depois.

Não faça commit de nada em ~/.openclaw (credenciais, sessões, tokens ou payloads de segredos criptografados). Se precisar de uma restauração completa, faça backup do workspace e do diretório de estado separadamente (consulte a pergunta sobre migração acima).

Docs: Workspace do agente.

Consulte o guia dedicado: Desinstalar.

Sim. O workspace é o cwd padrão e a âncora de memória, não uma sandbox rígida. Caminhos relativos são resolvidos dentro do workspace, mas caminhos absolutos podem acessar outros locais do host, a menos que a sandbox esteja ativada. Se precisar de isolamento, use agents.defaults.sandbox ou configurações de sandbox por agente. Se você quiser que um repositório seja o diretório de trabalho padrão, aponte o workspace desse agente para a raiz do repositório. O repositório do OpenClaw é apenas código-fonte; mantenha o workspace separado, a menos que você queira intencionalmente que o agente trabalhe dentro dele.

Exemplo (repositório como cwd padrão):

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}

O estado da sessão pertence ao host do gateway. Se você estiver no modo remoto, o armazenamento de sessões relevante fica na máquina remota, não no seu laptop local. Consulte Gerenciamento de sessões.

O OpenClaw lê uma configuração JSON5 opcional de $OPENCLAW_CONFIG_PATH (padrão: ~/.openclaw/openclaw.json):

$OPENCLAW_CONFIG_PATH

Se o arquivo estiver ausente, ele usa padrões razoavelmente seguros (incluindo um workspace padrão de ~/.openclaw/workspace).

Binds sem loopback exigem um caminho válido de autenticação do gateway. Na prática, isso significa:

• autenticação por segredo compartilhado: token ou senha
• gateway.auth.mode: "trusted-proxy" atrás de um proxy reverso com reconhecimento de identidade configurado corretamente

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}

Observações:

• gateway.remote.token / .password não ativam autenticação de gateway local por si só.
• Caminhos de chamada locais podem usar gateway.remote.* como fallback somente quando gateway.auth.* não está definido.
• Para autenticação por senha, defina gateway.auth.mode: "password" mais gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD) em vez disso.
• Se gateway.auth.token / gateway.auth.password estiver explicitamente configurado via SecretRef e não for resolvido, a resolução falha fechada (sem mascaramento por fallback remoto).
• Configurações da Control UI com segredo compartilhado autenticam via connect.params.auth.token ou connect.params.auth.password (armazenados nas configurações do app/UI). Modos portadores de identidade, como Tailscale Serve ou trusted-proxy, usam cabeçalhos de requisição em vez disso. Evite colocar segredos compartilhados em URLs.
• Com gateway.auth.mode: "trusted-proxy", proxies reversos de loopback no mesmo host exigem gateway.auth.trustedProxy.allowLoopback = true explícito e uma entrada de loopback em gateway.trustedProxies.

O OpenClaw aplica autenticação do gateway por padrão, incluindo loopback. No caminho padrão normal, isso significa autenticação por token: se nenhum caminho de autenticação explícito estiver configurado, a inicialização do gateway resolve para o modo de token e gera um token somente de runtime para essa inicialização, portanto clientes WS locais precisam se autenticar. Configure gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN ou OPENCLAW_GATEWAY_PASSWORD explicitamente quando clientes precisarem de um segredo estável entre reinicializações. Isso impede que outros processos locais chamem o Gateway.

Se preferir um caminho de autenticação diferente, você pode escolher explicitamente o modo de senha (ou, para proxies reversos com reconhecimento de identidade, trusted-proxy). Se você realmente quiser loopback aberto, defina gateway.auth.mode: "none" explicitamente na sua configuração. O Doctor pode gerar um token para você a qualquer momento: openclaw doctor --generate-gateway-token.

O Gateway observa a configuração e oferece suporte a hot-reload:

• gateway.reload.mode: "hybrid" (padrão): aplica alterações seguras a quente, reinicia para alterações críticas
• hot, restart, off também são compatíveis

Defina cli.banner.taglineMode na configuração:

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• off: oculta o texto da frase, mas mantém a linha de título/versão do banner.
• default: usa All your chats, one OpenClaw. sempre.
• random: frases engraçadas/sazonais rotativas (comportamento padrão).
• Se você não quiser banner nenhum, defina a variável de ambiente OPENCLAW_HIDE_BANNER=1.

web_fetch funciona sem uma chave de API. web_search depende do provedor selecionado:

• Provedores baseados em API, como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity e Tavily, exigem a configuração normal de chave de API deles.
• O Ollama Web Search não exige chave, mas usa seu host Ollama configurado e exige ollama signin.
• DuckDuckGo não exige chave, mas é uma integração não oficial baseada em HTML.
• SearXNG não exige chave/pode ser auto-hospedado; configure SEARXNG_BASE_URL ou plugins.entries.searxng.config.webSearch.baseUrl.

Recomendado: execute openclaw configure --section web e escolha um provedor. Alternativas de ambiente:

• Brave: BRAVE_API_KEY
• Exa: EXA_API_KEY
• Firecrawl: FIRECRAWL_API_KEY
• Gemini: GEMINI_API_KEY
• Grok: XAI_API_KEY
• Kimi: KIMI_API_KEY ou MOONSHOT_API_KEY
• MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY ou MINIMAX_API_KEY
• Perplexity: PERPLEXITY_API_KEY ou OPENROUTER_API_KEY
• SearXNG: SEARXNG_BASE_URL
• Tavily: TAVILY_API_KEY

{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}

A configuração de pesquisa web específica do provedor agora fica em plugins.entries.<plugin>.config.webSearch.*. Caminhos de provedor legados tools.web.search.* ainda carregam temporariamente para compatibilidade, mas não devem ser usados em novas configurações. A configuração de fallback de busca web do Firecrawl fica em plugins.entries.firecrawl.config.webFetch.*.

Observações:

• Se você usa listas de permissão, adicione web_search/web_fetch/x_search ou group:web.
• web_fetch é habilitado por padrão (a menos que seja explicitamente desabilitado).
• Se tools.web.fetch.provider for omitido, o OpenClaw detecta automaticamente o primeiro provedor de fallback de busca pronto a partir das credenciais disponíveis. Hoje, o provedor incluído é o Firecrawl.
• Daemons leem variáveis de ambiente de ~/.openclaw/.env (ou do ambiente do serviço).

Docs: Ferramentas web.

config.apply substitui a configuração inteira. Se você enviar um objeto parcial, todo o restante será removido.

O OpenClaw atual protege contra muitas sobrescritas acidentais:

• Escritas de configuração pertencentes ao OpenClaw validam a configuração completa após a alteração antes de gravar.
• Escritas inválidas ou destrutivas pertencentes ao OpenClaw são rejeitadas e salvas como openclaw.json.rejected.*.
• Se uma edição direta quebrar a inicialização ou o recarregamento automático, o Gateway falha de forma fechada ou ignora o recarregamento; ele não reescreve openclaw.json.
• openclaw doctor --fix é responsável pelo reparo e pode restaurar a última configuração válida conhecida salvando o arquivo rejeitado como openclaw.json.clobbered.*.

Recuperação:

• Verifique openclaw logs --follow para Invalid config at, Config write rejected: ou config reload skipped (invalid config).
• Inspecione o openclaw.json.clobbered.* ou openclaw.json.rejected.* mais recente ao lado da configuração ativa.
• Execute openclaw config validate e openclaw doctor --fix.
• Copie de volta apenas as chaves pretendidas com openclaw config set ou config.patch.
• Se você não tiver uma última configuração válida conhecida nem payload rejeitado, restaure de um backup ou execute novamente openclaw doctor e reconfigure canais/modelos.
• Se isso foi inesperado, abra um bug e inclua sua última configuração conhecida ou qualquer backup.
• Um agente de codificação local muitas vezes consegue reconstruir uma configuração funcional a partir de logs ou histórico.

Evite isso:

• Use openclaw config set para pequenas alterações.
• Use openclaw configure para edições interativas.
• Use config.schema.lookup primeiro quando você não tiver certeza sobre um caminho exato ou o formato de um campo; ele retorna um nó de esquema superficial mais resumos dos filhos imediatos para aprofundamento.
• Use config.patch para edições RPC parciais; mantenha config.apply apenas para substituição de configuração completa.
• Se você estiver usando a ferramenta gateway exclusiva do proprietário a partir de uma execução de agente, ela ainda rejeitará escritas em tools.exec.ask / tools.exec.security (incluindo aliases legados tools.bash.* que normalizam para os mesmos caminhos de execução protegidos).

Docs: Configuração, Configurar, Solução de problemas do Gateway, Doctor.

O padrão comum é um Gateway (por exemplo, Raspberry Pi) mais nós e agentes:

• Gateway (central): possui canais (Signal/WhatsApp), roteamento e sessões.
• Nós (dispositivos): Macs/iOS/Android conectam-se como periféricos e expõem ferramentas locais (system.run, canvas, camera).
• Agentes (workers): cérebros/workspaces separados para funções especiais (por exemplo, "Operações Hetzner", "Dados pessoais").
• Subagentes: geram trabalho em segundo plano a partir de um agente principal quando você quer paralelismo.
• TUI: conecte-se ao Gateway e alterne agentes/sessões.

Docs: Nós, Acesso remoto, Roteamento multiagente, Subagentes, TUI.

Sim. É uma opção de configuração:

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}

O padrão é false (com interface). Headless tem maior probabilidade de acionar verificações anti-bot em alguns sites. Consulte Navegador.

Headless usa o mesmo mecanismo Chromium e funciona para a maioria das automações (formulários, cliques, scraping, logins). As principais diferenças:

• Nenhuma janela de navegador visível (use capturas de tela se precisar de elementos visuais).
• Alguns sites são mais rigorosos quanto à automação em modo headless (CAPTCHAs, anti-bot). Por exemplo, X/Twitter costuma bloquear sessões headless.

Defina browser.executablePath para o binário do Brave (ou qualquer navegador baseado em Chromium) e reinicie o Gateway. Veja os exemplos completos de configuração em Navegador.

Mensagens do Telegram são processadas pelo gateway. O gateway executa o agente e só então chama nós pelo Gateway WebSocket quando uma ferramenta de nó é necessária:

Telegram → Gateway → Agente → node.* → Nó → Gateway → Telegram

Nós não veem tráfego de provedor de entrada; eles recebem apenas chamadas RPC de nó.

Resposta curta: pareie seu computador como um nó. O Gateway roda em outro lugar, mas pode chamar ferramentas node.* (tela, câmera, sistema) na sua máquina local pelo Gateway WebSocket.

Configuração típica:

1. Execute o Gateway no host sempre ativo (VPS/servidor doméstico).

2. Coloque o host do Gateway e seu computador na mesma tailnet.

3. Garanta que o Gateway WS esteja acessível (bind da tailnet ou túnel SSH).

4. Abra o app macOS localmente e conecte em modo Remoto por SSH (ou tailnet direta) para que ele possa se registrar como um nó.

5. Aprove o nó no Gateway:

   openclaw devices list
   openclaw devices approve <requestId>
   

Nenhuma ponte TCP separada é necessária; nós se conectam pelo Gateway WebSocket.

Lembrete de segurança: parear um nó macOS permite system.run nessa máquina. Pareie apenas dispositivos em que você confia e revise Segurança.

Docs: Nós, Protocolo do Gateway, Modo remoto do macOS, Segurança.

Verifique o básico:

• Gateway em execução: openclaw gateway status
• Saúde do Gateway: openclaw status
• Saúde do canal: openclaw channels status

Depois, verifique autenticação e roteamento:

• Se você usa Tailscale Serve, verifique se gateway.auth.allowTailscale está definido corretamente.
• Se você se conecta por túnel SSH, confirme que o túnel local está ativo e aponta para a porta correta.
• Confirme que suas listas de permissão (DM ou grupo) incluem sua conta.

Docs: Tailscale, Acesso remoto, Canais.

Sim. Não há uma ponte "bot-para-bot" integrada, mas você pode conectá-las de algumas maneiras confiáveis:

Mais simples: use um canal de chat normal que ambos os bots possam acessar (Telegram/Slack/WhatsApp). Faça o Bot A enviar uma mensagem ao Bot B e deixe o Bot B responder como de costume.

Ponte CLI (genérica): execute um script que chama o outro Gateway com openclaw agent --message ... --deliver, mirando um chat em que o outro bot escuta. Se um bot estiver em um VPS remoto, aponte sua CLI para esse Gateway remoto via SSH/Tailscale (consulte Acesso remoto).

Padrão de exemplo (execute a partir de uma máquina que consiga alcançar o Gateway de destino):

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

Dica: adicione uma proteção para que os dois bots não entrem em loop infinito (apenas menção, listas de permissão de canal ou uma regra "não responder a mensagens de bot").

Docs: Acesso remoto, CLI do agente, Envio do agente.

Não. Um Gateway pode hospedar vários agentes, cada um com seu próprio workspace, padrões de modelo e roteamento. Essa é a configuração normal, e é muito mais barata e simples do que executar uma VPS por agente.

Use VPSes separadas apenas quando precisar de isolamento rígido (limites de segurança) ou configurações muito diferentes que você não quer compartilhar. Caso contrário, mantenha um Gateway e use vários agentes ou subagentes.

Sim - nós são a forma de primeira classe de acessar seu laptop a partir de um Gateway remoto, e eles desbloqueiam mais do que acesso shell. O Gateway roda em macOS/Linux (Windows via WSL2) e é leve (um VPS pequeno ou uma máquina da classe Raspberry Pi é suficiente; 4 GB de RAM é bastante), então uma configuração comum é um host sempre ativo mais seu laptop como um nó.

• Nenhum SSH de entrada necessário. Nós se conectam de saída ao Gateway WebSocket e usam pareamento de dispositivo.
• Controles de execução mais seguros. system.run é protegido por listas de permissão/aprovações de nó nesse laptop.
• Mais ferramentas de dispositivo. Nós expõem canvas, camera e screen além de system.run.
• Automação local do navegador. Mantenha o Gateway em um VPS, mas execute o Chrome localmente por meio de um host de nó no laptop, ou anexe ao Chrome local no host via Chrome MCP.

SSH é adequado para acesso shell ad hoc, mas nós são mais simples para fluxos de trabalho contínuos de agentes e automação de dispositivos.

Docs: Nós, CLI de nós, Navegador.

Não. Apenas um gateway deve rodar por host, a menos que você execute intencionalmente perfis isolados (consulte Vários gateways). Nós são periféricos que se conectam ao gateway (nós iOS/Android, ou "modo de nó" macOS no app da barra de menus). Para hosts de nó headless e controle por CLI, consulte CLI do host de Node.

Uma reinicialização completa é necessária para alterações em gateway, discovery e na superfície de Plugin hospedado.

Sim.

• config.schema.lookup: inspecione uma subárvore de configuração com seu nó de esquema superficial, dica de UI correspondente e resumos imediatos dos filhos antes de escrever
• config.get: busca o snapshot atual + hash
• config.patch: atualização parcial segura (preferida para a maioria das edições RPC); recarrega a quente quando possível e reinicia quando necessário
• config.apply: valida + substitui a configuração completa; recarrega a quente quando possível e reinicia quando necessário
• A ferramenta de runtime gateway, exclusiva do proprietário, ainda se recusa a reescrever tools.exec.ask / tools.exec.security; aliases legados tools.bash.* normalizam para os mesmos caminhos protegidos de exec

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Isso define seu workspace e restringe quem pode acionar o bot.

Etapas mínimas:

1. Instale + faça login no VPS

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up
   

2. Instale + faça login no seu Mac

   • Use o app Tailscale e entre na mesma tailnet.

3. Ative o MagicDNS (recomendado)

   • No console de administração do Tailscale, ative o MagicDNS para que o VPS tenha um nome estável.

4. Use o hostname da tailnet

   • SSH: ssh [email protected]
   • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789

Se você quiser a UI de controle sem SSH, use o Tailscale Serve no VPS:

openclaw gateway --tailscale serve

Isso mantém o Gateway vinculado ao loopback e expõe HTTPS via Tailscale. Consulte Tailscale.

O Serve expõe a UI de controle do Gateway + WS. Nós se conectam pelo mesmo endpoint WS do Gateway.

Configuração recomendada:

1. Garanta que o VPS + Mac estejam na mesma tailnet.

2. Use o app macOS no modo remoto (o destino SSH pode ser o hostname da tailnet). O app tunelará a porta do Gateway e se conectará como um nó.

3. Aprove o nó no Gateway:

   openclaw devices list
   openclaw devices approve <requestId>
   

Docs: Protocolo do Gateway, Descoberta, modo remoto do macOS.

Se você precisa apenas de ferramentas locais (tela/câmera/exec) no segundo laptop, adicione-o como um nó. Isso mantém um único Gateway e evita configuração duplicada. As ferramentas de nó local são atualmente compatíveis apenas com macOS, mas planejamos estendê-las para outros sistemas operacionais.

Instale um segundo Gateway somente quando precisar de isolamento rígido ou de dois bots totalmente separados.

Docs: Nós, CLI de nós, Vários gateways.

O OpenClaw lê variáveis de ambiente do processo pai (shell, launchd/systemd, CI etc.) e também carrega:

• .env do diretório de trabalho atual
• um .env global de fallback de ~/.openclaw/.env (também conhecido como $OPENCLAW_STATE_DIR/.env)

Nenhum arquivo .env sobrescreve variáveis de ambiente existentes.

Você também pode definir variáveis de ambiente inline na configuração (aplicadas apenas se ausentes do ambiente do processo):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Consulte /environment para precedência e fontes completas.

Duas correções comuns:

1. Coloque as chaves ausentes em ~/.openclaw/.env para que sejam carregadas mesmo quando o serviço não herdar o ambiente do seu shell.
2. Ative a importação do shell (conveniência opcional):

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Isso executa seu shell de login e importa apenas chaves esperadas ausentes (nunca sobrescreve). Equivalentes de variáveis de ambiente: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

openclaw models status informa se a importação de ambiente do shell está ativada. "Shell env: off" não significa que suas variáveis de ambiente estão ausentes - significa apenas que o OpenClaw não carregará seu shell de login automaticamente.

Se o Gateway roda como serviço (launchd/systemd), ele não herdará seu ambiente de shell. Corrija fazendo uma destas opções:

1. Coloque o token em ~/.openclaw/.env:

   COPILOT_GITHUB_TOKEN=...
   

2. Ou ative a importação do shell (env.shellEnv.enabled: true).

3. Ou adicione-o ao bloco env da sua configuração (aplica-se apenas se estiver ausente).

Em seguida, reinicie o Gateway e verifique novamente:

openclaw models status

Tokens do Copilot são lidos de COPILOT_GITHUB_TOKEN (também GH_TOKEN / GITHUB_TOKEN). Consulte /concepts/model-providers e /environment.

Envie /new ou /reset como uma mensagem independente. Consulte Gerenciamento de sessões.

Sessões podem expirar após session.idleMinutes, mas isso vem desativado por padrão (padrão 0). Defina um valor positivo para ativar a expiração por inatividade. Quando ativada, a próxima mensagem após o período de inatividade inicia um novo ID de sessão para essa chave de chat. Isso não exclui transcrições - apenas inicia uma nova sessão.

{
  session: {
    idleMinutes: 240,
  },
}

Sim, via roteamento multiagente e subagentes. Você pode criar um agente coordenador e vários agentes trabalhadores com seus próprios workspaces e modelos.

Dito isso, isso é melhor visto como um experimento divertido. Consome muitos tokens e frequentemente é menos eficiente do que usar um bot com sessões separadas. O modelo típico que imaginamos é um bot com o qual você conversa, com diferentes sessões para trabalho paralelo. Esse bot também pode gerar subagentes quando necessário.

Docs: Roteamento multiagente, Subagentes, CLI de agentes.

O contexto da sessão é limitado pela janela do modelo. Chats longos, grandes saídas de ferramentas ou muitos arquivos podem acionar compactação ou truncamento.

O que ajuda:

• Peça ao bot para resumir o estado atual e gravá-lo em um arquivo.
• Use /compact antes de tarefas longas e /new ao trocar de assunto.
• Mantenha contexto importante no workspace e peça ao bot para relê-lo.
• Use subagentes para trabalho longo ou paralelo para que o chat principal permaneça menor.
• Escolha um modelo com uma janela de contexto maior se isso acontecer com frequência.

Use o comando de reset:

openclaw reset

Reset completo não interativo:

openclaw reset --scope full --yes --non-interactive

Depois, execute a configuração novamente:

openclaw onboard --install-daemon

Observações:

• O onboarding também oferece Reset se detectar uma configuração existente. Consulte Onboarding (CLI).
• Se você usou perfis (--profile / OPENCLAW_PROFILE), redefina cada diretório de estado (os padrões são ~/.openclaw-<profile>).
• Reset de desenvolvimento: openclaw gateway --dev --reset (somente dev; apaga configuração de dev + credenciais + sessões + workspace).

Use uma destas opções:

• Compactar (mantém a conversa, mas resume turnos antigos):

  /compact
  

  ou /compact <instructions> para orientar o resumo.

• Reset (novo ID de sessão para a mesma chave de chat):

  /new
  /reset
  

Se continuar acontecendo:

• Ative ou ajuste a poda de sessão (agents.defaults.contextPruning) para aparar saídas antigas de ferramentas.
• Use um modelo com uma janela de contexto maior.

Docs: Compaction, Poda de sessão, Gerenciamento de sessões.

Este é um erro de validação do provedor: o modelo emitiu um bloco tool_use sem o input obrigatório. Geralmente significa que o histórico da sessão está obsoleto ou corrompido (muitas vezes após threads longas ou uma alteração de ferramenta/esquema).

Correção: inicie uma nova sessão com /new (mensagem independente).

Heartbeats rodam a cada 30m por padrão (1h ao usar autenticação OAuth). Ajuste ou desative-os:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}

Se HEARTBEAT.md existir, mas estiver efetivamente vazio (apenas linhas em branco e cabeçalhos markdown como # Heading), o OpenClaw pula a execução de Heartbeat para economizar chamadas de API. Se o arquivo estiver ausente, o Heartbeat ainda roda e o modelo decide o que fazer.

Sobrescritas por agente usam agents.list[].heartbeat. Docs: Heartbeat.

Não. O OpenClaw roda na sua própria conta, então, se você está no grupo, o OpenClaw pode vê-lo. Por padrão, respostas em grupo são bloqueadas até que você permita remetentes (groupPolicy: "allowlist").

Se você quiser que somente você possa acionar respostas em grupo:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

Opção 1 (mais rápida): acompanhe os logs e envie uma mensagem de teste no grupo:

openclaw logs --follow --json

Procure por chatId (ou from) terminando em @g.us, como: [email protected].

Opção 2 (se já estiver configurado/na lista de permissões): liste grupos a partir da configuração:

openclaw directory groups list --channel whatsapp

Docs: WhatsApp, Diretório, Logs.

Duas causas comuns:

• O bloqueio por menção está ativado (padrão). Você deve @mencionar o bot (ou corresponder a mentionPatterns).
• Você configurou channels.whatsapp.groups sem "*" e o grupo não está na lista de permissões.

Consulte Grupos e Mensagens de grupo.

Chats diretos convergem para a sessão principal por padrão. Grupos/canais têm suas próprias chaves de sessão, e tópicos do Telegram / threads do Discord são sessões separadas. Consulte Grupos e Mensagens de grupo.

Sem limites rígidos. Dezenas (até centenas) funcionam bem, mas fique atento a:

• Crescimento do disco: sessões + transcrições ficam em ~/.openclaw/agents/<agentId>/sessions/.
• Custo de tokens: mais agents significam mais uso simultâneo de modelos.
• Sobrecarga operacional: perfis de autenticação, workspaces e roteamento de canais por agent.

Dicas:

• Mantenha um workspace ativo por agent (agents.defaults.workspace).
• Remova sessões antigas (exclua JSONL ou entradas armazenadas) se o disco crescer.
• Use openclaw doctor para detectar workspaces perdidos e incompatibilidades de perfil.

Sim. Use Roteamento Multi-Agent para executar vários agents isolados e rotear mensagens recebidas por canal/conta/par. O Slack é compatível como canal e pode ser vinculado a agents específicos.

O acesso pelo navegador é poderoso, mas não permite "fazer qualquer coisa que uma pessoa faria" - anti-bot, CAPTCHAs e MFA ainda podem bloquear a automação. Para o controle de navegador mais confiável, use Chrome MCP local no host ou use CDP na máquina que realmente executa o navegador.

Configuração recomendada:

• Host de Gateway sempre ativo (VPS/Mac mini).
• Um agent por função (vínculos).
• Canal(is) do Slack vinculados a esses agents.
• Navegador local via Chrome MCP ou um Node quando necessário.

Docs: Roteamento Multi-Agent, Slack, Navegador, Nodes.

gateway.port controla a única porta multiplexada para WebSocket + HTTP (UI de Controle, hooks etc.).

Precedência:

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

Porque "running" é a visão do supervisor (launchd/systemd/schtasks). A sondagem de conectividade é a CLI realmente se conectando ao WebSocket do Gateway.

Use openclaw gateway status e confie nestas linhas:

• Probe target: (a URL que a sondagem realmente usou)
• Listening: (o que está realmente vinculado à porta)
• Last gateway error: (causa raiz comum quando o processo está ativo, mas a porta não está escutando)

Você está editando um arquivo de configuração enquanto o serviço está executando outro (geralmente uma incompatibilidade de --profile / OPENCLAW_STATE_DIR).

Correção:

openclaw gateway install --force

Execute isso a partir do mesmo --profile / ambiente que você quer que o serviço use.

O OpenClaw impõe um bloqueio de runtime vinculando o listener WebSocket imediatamente na inicialização (padrão ws://127.0.0.1:18789). Se o vínculo falhar com EADDRINUSE, ele lança GatewayLockError indicando que outra instância já está escutando.

Correção: pare a outra instância, libere a porta ou execute com openclaw gateway --port <port>.

Defina gateway.mode: "remote" e aponte para uma URL WebSocket remota, opcionalmente com credenciais remotas de segredo compartilhado:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}

Observações:

• openclaw gateway só inicia quando gateway.mode é local (ou quando você passa a flag de substituição).
• O app macOS observa o arquivo de configuração e alterna modos ao vivo quando esses valores mudam.
• gateway.remote.token / .password são apenas credenciais remotas do lado do cliente; elas não habilitam autenticação de gateway local por si mesmas.

O caminho de autenticação do seu Gateway e o método de autenticação da UI não correspondem.

Fatos (a partir do código):

• A UI de Controle mantém o token em sessionStorage para a sessão atual da aba do navegador e a URL de gateway selecionada, então atualizações na mesma aba continuam funcionando sem restaurar persistência de token de longa duração em localStorage.
• Em AUTH_TOKEN_MISMATCH, clientes confiáveis podem tentar uma nova tentativa limitada com um token de dispositivo em cache quando o Gateway retorna dicas de nova tentativa (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
• Essa nova tentativa com token em cache agora reutiliza os escopos aprovados em cache armazenados com o token de dispositivo. Chamadores com deviceToken explícito / scopes explícitos ainda mantêm o conjunto de escopos solicitado em vez de herdar escopos em cache.
• Fora desse caminho de nova tentativa, a precedência de autenticação de conexão é token/senha compartilhado explícito primeiro, depois deviceToken explícito, depois token de dispositivo armazenado, depois token de bootstrap.
• Verificações de escopo do token de bootstrap são prefixadas por função. A allowlist interna de operador de bootstrap só satisfaz solicitações de operador; Node ou outras funções não operadoras ainda precisam de escopos sob seu próprio prefixo de função.

Correção:

• Mais rápido: openclaw dashboard (imprime + copia a URL do dashboard, tenta abrir; mostra dica de SSH se estiver sem interface gráfica).
• Se você ainda não tem um token: openclaw doctor --generate-gateway-token.
• Se for remoto, crie o túnel primeiro: ssh -N -L 18789:127.0.0.1:18789 user@host e depois abra http://127.0.0.1:18789/.
• Modo de segredo compartilhado: defina gateway.auth.token / OPENCLAW_GATEWAY_TOKEN ou gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, depois cole o segredo correspondente nas configurações da UI de Controle.
• Modo Tailscale Serve: verifique se gateway.auth.allowTailscale está habilitado e se você está abrindo a URL do Serve, não uma URL bruta de loopback/tailnet que ignora cabeçalhos de identidade do Tailscale.
• Modo proxy confiável: verifique se você está vindo pelo proxy configurado com reconhecimento de identidade, não por uma URL bruta do gateway. Proxies local loopback no mesmo host também precisam de gateway.auth.trustedProxy.allowLoopback = true.
• Se a incompatibilidade persistir após a única nova tentativa, rotacione/aprove novamente o token de dispositivo pareado:
  • openclaw devices list
  • openclaw devices rotate --device <id> --role operator
• Se essa chamada de rotação disser que foi negada, verifique duas coisas:
  • sessões de dispositivo pareado só podem rotacionar seu próprio dispositivo, a menos que também tenham operator.admin
  • valores explícitos de --scope não podem exceder os escopos atuais de operador do chamador
• Ainda travado? Execute openclaw status --all e siga Solução de problemas. Consulte Dashboard para detalhes de autenticação.

O vínculo tailnet escolhe um IP do Tailscale nas suas interfaces de rede (100.64.0.0/10). Se a máquina não estiver no Tailscale (ou a interface estiver inativa), não há nada a que vincular.

Correção:

• Inicie o Tailscale nesse host (para que ele tenha um endereço 100.x), ou
• Mude para gateway.bind: "loopback" / "lan".

Observação: tailnet é explícito. auto prefere loopback; use gateway.bind: "tailnet" quando quiser um vínculo apenas para tailnet.

Normalmente não - um Gateway pode executar vários canais de mensagens e agents. Use vários Gateways apenas quando precisar de redundância (ex.: bot de resgate) ou isolamento rígido.

Sim, mas você precisa isolar:

• OPENCLAW_CONFIG_PATH (configuração por instância)
• OPENCLAW_STATE_DIR (estado por instância)
• agents.defaults.workspace (isolamento de workspace)
• gateway.port (portas únicas)

Configuração rápida (recomendada):

• Use openclaw --profile <name> ... por instância (cria automaticamente ~/.openclaw-<name>).
• Defina um gateway.port único na configuração de cada perfil (ou passe --port para execuções manuais).
• Instale um serviço por perfil: openclaw --profile <name> gateway install.

Perfis também adicionam sufixos aos nomes de serviço (ai.openclaw.<profile>; legado com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). Guia completo: Vários gateways.

O Gateway é um servidor WebSocket, e ele espera que a primeira mensagem seja um frame connect. Se receber qualquer outra coisa, ele fecha a conexão com código 1008 (violação de política).

Causas comuns:

• Você abriu a URL HTTP em um navegador (http://...) em vez de um cliente WS.
• Você usou a porta ou o caminho errado.
• Um proxy ou túnel removeu cabeçalhos de autenticação ou enviou uma solicitação que não era do Gateway.

Correções rápidas:

1. Use a URL WS: ws://<host>:18789 (ou wss://... se for HTTPS).
2. Não abra a porta WS em uma aba normal do navegador.
3. Se a autenticação estiver ativa, inclua o token/senha no frame connect.

Se você estiver usando a CLI ou TUI, a URL deve se parecer com:

openclaw tui --url ws://<host>:18789 --token <token>

Detalhes do protocolo: Protocolo do Gateway.

Logs em arquivo (estruturados):

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Você pode definir um caminho estável via logging.file. O nível de log em arquivo é controlado por logging.level. A verbosidade do console é controlada por --verbose e logging.consoleLevel.

Maneira mais rápida de acompanhar logs:

openclaw logs --follow

Logs de serviço/supervisor (quando o gateway executa via launchd/systemd):

• macOS: $OPENCLAW_STATE_DIR/logs/gateway.log e gateway.err.log (padrão: ~/.openclaw/logs/...; perfis usam ~/.openclaw-<profile>/logs/...)
• Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

Consulte Solução de problemas para mais.

Use os auxiliares de gateway:

openclaw gateway status
openclaw gateway restart

Se você executar o gateway manualmente, openclaw gateway --force pode recuperar a porta. Consulte Gateway.

Há dois modos de instalação no Windows:

1) WSL2 (recomendado): o Gateway executa dentro do Linux.

Abra o PowerShell, entre no WSL e reinicie:

wsl
openclaw gateway status
openclaw gateway restart

Se você nunca instalou o serviço, inicie-o em primeiro plano:

openclaw gateway run

2) Windows nativo (não recomendado): o Gateway executa diretamente no Windows.

Abra o PowerShell e execute:

openclaw gateway status
openclaw gateway restart

Se você executá-lo manualmente (sem serviço), use:

openclaw gateway run

Docs: Windows (WSL2), Runbook do serviço do Gateway.

Comece com uma varredura rápida de integridade:

openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow

Causas comuns:

• A autenticação do modelo não foi carregada no host do gateway (verifique models status).
• Emparelhamento/lista de permissões do canal bloqueando respostas (verifique a configuração do canal + logs).
• O WebChat/Painel está aberto sem o token correto.

Se você estiver remoto, confirme que a conexão do túnel/Tailscale está ativa e que o WebSocket do Gateway está acessível.

Docs: Canais, Solução de problemas, Acesso remoto.

Isso geralmente significa que a UI perdeu a conexão WebSocket. Verifique:

1. O Gateway está em execução? openclaw gateway status
2. O Gateway está íntegro? openclaw status
3. A UI tem o token correto? openclaw dashboard
4. Se remoto, o link do túnel/Tailscale está ativo?

Em seguida, acompanhe os logs:

openclaw logs --follow

Docs: Painel, Acesso remoto, Solução de problemas.

Comece pelos logs e pelo status do canal:

openclaw channels status
openclaw channels logs --channel telegram

Em seguida, compare o erro:

• BOT_COMMANDS_TOO_MUCH: o menu do Telegram tem entradas demais. O OpenClaw já reduz para o limite do Telegram e tenta novamente com menos comandos, mas algumas entradas do menu ainda precisam ser removidas. Reduza comandos de plugin/skill/personalizados, ou desative channels.telegram.commands.native se você não precisar do menu.
• TypeError: fetch failed, Network request for 'setMyCommands' failed!, ou erros de rede semelhantes: se você estiver em um VPS ou atrás de um proxy, confirme que HTTPS de saída é permitido e que o DNS funciona para api.telegram.org.

Se o Gateway for remoto, certifique-se de que você está olhando os logs no host do Gateway.

Docs: Telegram, Solução de problemas de canais.

Primeiro confirme que o Gateway está acessível e que o agente consegue executar:

openclaw status
openclaw models status
openclaw logs --follow

Na TUI, use /status para ver o estado atual. Se você espera respostas em um canal de chat, certifique-se de que a entrega está ativada (/deliver on).

Docs: TUI, Comandos de barra.

Se você instalou o serviço:

openclaw gateway stop
openclaw gateway start

Isso para/inicia o serviço supervisionado (launchd no macOS, systemd no Linux). Use isso quando o Gateway é executado em segundo plano como um daemon.

Se você estiver executando em primeiro plano, pare com Ctrl-C, depois:

openclaw gateway run

Docs: Runbook do serviço Gateway.

• openclaw gateway restart: reinicia o serviço em segundo plano (launchd/systemd).
• openclaw gateway: executa o gateway em primeiro plano para esta sessão de terminal.

Se você instalou o serviço, use os comandos do gateway. Use openclaw gateway quando quiser uma execução avulsa em primeiro plano.

Inicie o Gateway com --verbose para obter mais detalhes no console. Depois inspecione o arquivo de log em busca de erros de autenticação de canal, roteamento de modelo e RPC.

Anexos de saída do agente devem incluir uma linha MEDIA:<path-or-url> (em sua própria linha). Consulte Configuração do assistente OpenClaw e Envio do agente.

Envio pela CLI:

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

Verifique também:

• O canal de destino oferece suporte a mídia de saída e não está bloqueado por listas de permissões.
• O arquivo está dentro dos limites de tamanho do provedor (imagens são redimensionadas para no máximo 2048px).
• tools.fs.workspaceOnly=true mantém envios por caminho local limitados ao workspace, temp/media-store e arquivos validados pelo sandbox.
• tools.fs.workspaceOnly=false permite que MEDIA: envie arquivos locais do host que o agente já consegue ler, mas apenas para mídia e tipos de documentos seguros (imagens, áudio, vídeo, PDF e documentos do Office). Arquivos de texto simples e semelhantes a segredos continuam bloqueados.

Consulte Imagens.

Trate DMs de entrada como entrada não confiável. Os padrões foram projetados para reduzir riscos:

• O comportamento padrão em canais compatíveis com DM é emparelhamento:
  • Remetentes desconhecidos recebem um código de emparelhamento; o bot não processa a mensagem deles.
  • Aprove com: openclaw pairing approve --channel <channel> [--account <id>] <code>
  • Solicitações pendentes são limitadas a 3 por canal; verifique openclaw pairing list --channel <channel> [--account <id>] se um código não chegou.
• Abrir DMs publicamente exige opt-in explícito (dmPolicy: "open" e lista de permissões "*").

Execute openclaw doctor para revelar políticas de DM arriscadas.

Não. Injeção de prompt envolve conteúdo não confiável, não apenas quem pode enviar DM ao bot. Se seu assistente lê conteúdo externo (pesquisa/busca na web, páginas de navegador, emails, docs, anexos, logs colados), esse conteúdo pode incluir instruções que tentam sequestrar o modelo. Isso pode acontecer mesmo se você for o único remetente.

O maior risco é quando ferramentas estão ativadas: o modelo pode ser enganado para exfiltrar contexto ou chamar ferramentas em seu nome. Reduza o raio de impacto:

• usando um agente "leitor" somente leitura ou com ferramentas desativadas para resumir conteúdo não confiável
• mantendo web_search / web_fetch / browser desativados para agentes com ferramentas ativadas
• tratando texto decodificado de arquivos/documentos também como não confiável: OpenResponses input_file e a extração de anexos de mídia envolvem o texto extraído em marcadores explícitos de limite de conteúdo externo, em vez de passar o texto bruto do arquivo
• usando sandboxing e listas de permissões de ferramentas rigorosas

Detalhes: Segurança.

Sim, para a maioria das configurações. Isolar o bot com contas e números de telefone separados reduz o raio de impacto se algo der errado. Isso também facilita rotacionar credenciais ou revogar acesso sem afetar suas contas pessoais.

Comece pequeno. Dê acesso apenas às ferramentas e contas de que você realmente precisa, e expanda depois se necessário.

Docs: Segurança, Emparelhamento.

Nós não recomendamos autonomia total sobre suas mensagens pessoais. O padrão mais seguro é:

• Mantenha DMs em modo de emparelhamento ou em uma lista de permissões restrita.
• Use um número ou conta separados se quiser que ele envie mensagens em seu nome.
• Deixe-o rascunhar, depois aprove antes de enviar.

Se quiser experimentar, faça isso em uma conta dedicada e mantenha-a isolada. Consulte Segurança.

Sim, se o agente for apenas de chat e a entrada for confiável. Tiers menores são mais suscetíveis a sequestro por instruções, então evite-os para agentes com ferramentas ativadas ou ao ler conteúdo não confiável. Se você precisar usar um modelo menor, restrinja as ferramentas e execute dentro de um sandbox. Consulte Segurança.

Códigos de emparelhamento são enviados somente quando um remetente desconhecido envia mensagem ao bot e dmPolicy: "pairing" está ativado. /start por si só não gera um código.

Verifique solicitações pendentes:

openclaw pairing list telegram

Se quiser acesso imediato, adicione seu ID de remetente à lista de permissões ou defina dmPolicy: "open" para essa conta.

Não. A política padrão de DM do WhatsApp é emparelhamento. Remetentes desconhecidos recebem apenas um código de emparelhamento e a mensagem deles não é processada. O OpenClaw só responde a chats que recebe ou a envios explícitos que você aciona.

Aprove o emparelhamento com:

openclaw pairing approve whatsapp <code>

Liste solicitações pendentes:

openclaw pairing list whatsapp

Prompt do número de telefone no assistente: ele é usado para definir sua lista de permissões/proprietário para que suas próprias DMs sejam permitidas. Ele não é usado para envio automático. Se você executar no seu número pessoal do WhatsApp, use esse número e ative channels.whatsapp.selfChatMode.

A maioria das mensagens internas ou de ferramentas só aparece quando verbose, trace ou reasoning está ativado para essa sessão.

Corrija no chat onde você vê isso:

/verbose off
/trace off
/reasoning off

Se ainda estiver ruidoso, verifique as configurações da sessão na UI de Controle e defina verbose como herdar. Confirme também que você não está usando um perfil de bot com verboseDefault definido como on na configuração.

Docs: Pensamento e verbose, Segurança.

Envie qualquer uma destas como mensagem independente (sem barra):

stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt

Estes são gatilhos de interrupção (não comandos de barra).

Para processos em segundo plano (da ferramenta exec), você pode pedir ao agente para executar:

process action:kill sessionId:XXX

Visão geral dos comandos de barra: consulte Comandos de barra.

A maioria dos comandos deve ser enviada como uma mensagem independente que começa com /, mas alguns atalhos (como /status) também funcionam inline para remetentes na lista de permissões.

O OpenClaw bloqueia mensagens entre provedores por padrão. Se uma chamada de ferramenta estiver vinculada ao Telegram, ela não enviará para o Discord a menos que você permita explicitamente.

Ative mensagens entre provedores para o agente:

{
  tools: {
    message: {
      crossContext: {
        allowAcrossProviders: true,
        marker: { enabled: true, prefix: "[from {channel}] " },
      },
    },
  },
}

Reinicie o gateway depois de editar a configuração.

O modo de fila controla como novas mensagens interagem com uma execução em andamento. Use /queue para alterar modos:

• steer - enfileirar todas as orientações pendentes para o próximo limite do modelo na execução atual
• queue - orientação legada, uma por vez
• followup - executar mensagens uma por vez
• collect - agrupar mensagens e responder uma vez
• steer-backlog - orientar agora, depois processar o backlog
• interrupt - interromper a execução atual e começar do zero

O modo padrão é steer. Você pode adicionar opções como debounce:0.5s cap:25 drop:summarize para modos de acompanhamento. Consulte Fila de comandos e Fila de direcionamento.

No OpenClaw, as credenciais e a seleção de modelo são separadas. Definir ANTHROPIC_API_KEY (ou armazenar uma chave de API da Anthropic nos perfis de autenticação) habilita a autenticação, mas o modelo padrão real é o que você configurar em agents.defaults.model.primary (por exemplo, anthropic/claude-sonnet-4-6 ou anthropic/claude-opus-4-6). Se você vir No credentials found for profile "anthropic:default", isso significa que o Gateway não conseguiu encontrar credenciais da Anthropic no auth-profiles.json esperado para o agente que está em execução.