Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Início rápido e perguntas e respostas da primeira execução. Para operações diárias, modelos, autenticação, sessões e solução de problemas, consulte a FAQ principal.

​
Início rápido e configuração da primeira execução

Use um agente de IA local que consiga ver sua máquina. Isso é muito mais eficaz do que perguntar no Discord, porque a maioria dos casos de “estou travado” são problemas de configuração local ou ambiente que ajudantes remotos não conseguem inspecionar.Essas ferramentas podem ler o repositório, executar comandos, inspecionar logs e ajudar a corrigir sua configuração no nível da máquina (PATH, serviços, permissões, arquivos de autenticação). Dê a elas o checkout completo do código-fonte via instalação hackeável (git):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
Isso instala o OpenClaw a partir de um checkout git, para que o agente possa ler o código + a documentação e raciocinar sobre a versão exata que você está executando. Você sempre pode voltar para a versão estável depois executando novamente o instalador sem --install-method git.Dica: peça ao agente para planejar e supervisionar a correção (passo a passo) e, então, executar apenas os comandos necessários. Isso mantém as alterações pequenas e mais fáceis de auditar.Se você descobrir um bug real ou uma correção, abra uma issue no GitHub ou envie um PR: https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pullsComece com estes comandos (compartilhe as saídas ao pedir ajuda):
openclaw status
openclaw models status
openclaw doctor
O que eles fazem:
  • openclaw status: instantâneo rápido da integridade do gateway/agente + configuração básica.
  • openclaw models status: verifica autenticação do provedor + disponibilidade de modelos.
  • openclaw doctor: valida e repara problemas comuns de configuração/estado.
Outras verificações úteis da CLI: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose.Ciclo rápido de depuração: Primeiros 60 segundos se algo estiver quebrado. Documentação de instalação: Instalar, Flags do instalador, Atualizando.
Motivos comuns para ignorar o heartbeat:
  • quiet-hours: fora da janela de horário ativo configurada
  • empty-heartbeat-file: HEARTBEAT.md existe, mas contém apenas estrutura em branco ou só com cabeçalho
  • no-tasks-due: o modo de tarefas de HEARTBEAT.md está ativo, mas nenhum dos intervalos de tarefas venceu ainda
  • alerts-disabled: toda a visibilidade do heartbeat está desativada (showOk, showAlerts e useIndicator estão todos desligados)
No modo de tarefas, os timestamps de vencimento só são avançados depois que uma execução real do heartbeat é concluída. Execuções ignoradas não marcam tarefas como concluídas.Documentação: Heartbeat, Automação.
O repositório recomenda executar a partir do código-fonte e usar o onboarding:
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
O assistente também pode criar assets da UI automaticamente. Depois do onboarding, normalmente você executa o Gateway na porta 18789.A partir do código-fonte (contribuidores/dev):
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard
Se você ainda não tiver uma instalação global, execute via pnpm openclaw onboard.
O assistente abre seu navegador com uma URL limpa (sem token) do painel logo após o onboarding e também imprime o link no resumo. Mantenha essa aba aberta; se ela não tiver sido iniciada, copie/cole a URL impressa na mesma máquina.
Localhost (mesma máquina):
  • Abra http://127.0.0.1:18789/.
  • Se ele pedir autenticação por segredo compartilhado, cole o token ou a senha configurados nas configurações da Control UI.
  • Origem do token: gateway.auth.token (ou OPENCLAW_GATEWAY_TOKEN).
  • Origem da senha: gateway.auth.password (ou OPENCLAW_GATEWAY_PASSWORD).
  • Se nenhum segredo compartilhado estiver configurado ainda, gere um token com openclaw doctor --generate-gateway-token.
Não em localhost:
  • Tailscale Serve (recomendado): mantenha o bind em local loopback, execute openclaw gateway --tailscale serve, abra https://<magicdns>/. Se gateway.auth.allowTailscale for true, os cabeçalhos de identidade satisfazem a autenticação da Control UI/WebSocket (sem segredo compartilhado colado, pressupõe host de gateway confiável); APIs HTTP ainda exigem autenticação por segredo compartilhado, a menos que você use deliberadamente ingress privado none ou autenticação HTTP por proxy confiável. Tentativas ruins simultâneas de autenticação do Serve do mesmo cliente são serializadas antes de o limitador de falha de autenticação registrá-las, então a segunda tentativa ruim já pode mostrar retry later.
  • Bind na tailnet: execute openclaw gateway --bind tailnet --token "<token>" (ou configure autenticação por senha), abra http://<tailscale-ip>:18789/ e cole o segredo compartilhado correspondente nas configurações do painel.
  • Proxy reverso com reconhecimento de identidade: mantenha o Gateway atrás de um proxy confiável, configure gateway.auth.mode: "trusted-proxy" e abra a URL do proxy. Proxies de local loopback no mesmo host exigem gateway.auth.trustedProxy.allowLoopback = true explícito.
  • Túnel SSH: ssh -N -L 18789:127.0.0.1:18789 user@host e então abra http://127.0.0.1:18789/. A autenticação por segredo compartilhado ainda se aplica pelo túnel; cole o token ou a senha configurados se solicitado.
Consulte Painel e Superfícies web para modos de bind e detalhes de autenticação.
Elas controlam camadas diferentes:
  • approvals.exec: encaminha prompts de aprovação para destinos de chat
  • channels.<channel>.execApprovals: faz esse canal atuar como cliente nativo de aprovação para aprovações de exec
A política de exec do host ainda é o gate de aprovação real. A configuração de chat controla apenas onde os prompts de aprovação aparecem e como as pessoas podem respondê-los.Na maioria das configurações você não precisa dos dois:
  • Se o chat já oferece suporte a comandos e respostas, /approve no mesmo chat funciona pelo caminho compartilhado.
  • Se um canal nativo compatível consegue inferir aprovadores com segurança, o OpenClaw agora ativa automaticamente aprovações nativas com DM primeiro quando channels.<channel>.execApprovals.enabled está indefinido ou "auto".
  • Quando cartões/botões de aprovação nativos estão disponíveis, essa UI nativa é o caminho principal; o agente só deve incluir um comando manual /approve se o resultado da ferramenta disser que aprovações por chat estão indisponíveis ou que a aprovação manual é o único caminho.
  • Use approvals.exec apenas quando os prompts também precisarem ser encaminhados para outros chats ou salas explícitas de operações.
  • Use channels.<channel>.execApprovals.target: "channel" ou "both" apenas quando você quiser explicitamente que prompts de aprovação sejam publicados de volta na sala/tópico de origem.
  • Aprovações de Plugin são separadas novamente: elas usam /approve no mesmo chat por padrão, encaminhamento opcional approvals.plugin, e apenas alguns canais nativos mantêm o tratamento nativo de aprovação de Plugin por cima.
Versão curta: encaminhamento é para roteamento, configuração de cliente nativo é para uma UX mais rica específica do canal. Consulte Aprovações de Exec.
Node >= 22 é obrigatório. pnpm é recomendado. Bun não é recomendado para o Gateway.
Sim. O Gateway é leve - a documentação lista 512MB-1GB RAM, 1 core e cerca de 500MB de disco como suficiente para uso pessoal, e observa que um Raspberry Pi 4 pode executá-lo.Se você quiser folga extra (logs, mídia, outros serviços), 2GB é recomendado, mas isso não é um mínimo rígido.Dica: um Pi/VPS pequeno pode hospedar o Gateway, e você pode parear nós no seu laptop/celular para tela/câmera/canvas local ou execução de comandos. Consulte Nós.
Versão curta: funciona, mas espere arestas.
  • Use um SO 64-bit e mantenha Node >= 22.
  • Prefira a instalação hackeável (git) para poder ver logs e atualizar rapidamente.
  • Comece sem canais/skills e depois adicione um por um.
  • Se você encontrar problemas binários estranhos, geralmente é um problema de compatibilidade com ARM.
Documentação: Linux, Instalar.
Essa tela depende de o Gateway estar acessível e autenticado. A TUI também envia “Wake up, my friend!” automaticamente na primeira eclosão. Se você vir essa linha com nenhuma resposta e os tokens ficarem em 0, o agente nunca rodou.
  1. Reinicie o Gateway:
openclaw gateway restart
  1. Verifique status + autenticação:
openclaw status
openclaw models status
openclaw logs --follow
  1. Se ainda travar, execute:
openclaw doctor
Se o Gateway for remoto, garanta que a conexão de túnel/Tailscale esteja ativa e que a UI esteja apontada para o Gateway correto. Consulte Acesso remoto.
Sim. Copie o diretório de estado e o workspace e então execute o Doctor uma vez. Isso mantém seu bot “exatamente igual” (memória, histórico de sessões, autenticação e estado de canal), desde que você copie ambos os locais:
  1. Instale o OpenClaw na nova máquina.
  2. Copie $OPENCLAW_STATE_DIR (padrão: ~/.openclaw) da máquina antiga.
  3. Copie seu workspace (padrão: ~/.openclaw/workspace).
  4. Execute openclaw doctor e reinicie o serviço Gateway.
Isso preserva configuração, perfis de autenticação, credenciais do WhatsApp, sessões e memória. Se você estiver no modo remoto, lembre-se de que o host do gateway é dono do armazenamento de sessões e do workspace.Importante: se você apenas fizer commit/push do seu workspace para o GitHub, estará fazendo backup de memória + arquivos de bootstrap, mas não do histórico de sessões nem da autenticação. Eles ficam em ~/.openclaw/ (por exemplo ~/.openclaw/agents/<agentId>/sessions/).Relacionado: Migrando, Onde as coisas ficam no disco, Workspace do agente, Doctor, Modo remoto.
Consulte o changelog do GitHub: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.mdAs entradas mais novas ficam no topo. Se a seção superior estiver marcada como Unreleased, a próxima seção datada é a versão enviada mais recente. As entradas são agrupadas por Destaques, Alterações e Correções (além de seções de documentação/outras quando necessário).
Algumas conexões Comcast/Xfinity bloqueiam incorretamente docs.openclaw.ai via Xfinity Advanced Security. Desative isso ou adicione docs.openclaw.ai à lista de permissões e tente novamente. Ajude-nos a desbloquear reportando aqui: https://spa.xfinity.com/check_url_status.Se você ainda não conseguir acessar o site, a documentação está espelhada no GitHub: https://github.com/openclaw/openclaw/tree/main/docs
Estável e beta são dist-tags do npm, não linhas de código separadas:
  • latest = estável
  • beta = compilação inicial para testes
Normalmente, uma versão estável chega primeiro à beta e, depois, uma etapa explícita de promoção move essa mesma versão para latest. Os mantenedores também podem publicar diretamente em latest quando necessário. É por isso que beta e estável podem apontar para a mesma versão após a promoção.Veja o que mudou: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.mdPara comandos de instalação em uma linha e a diferença entre beta e dev, veja o acordeão abaixo.
Beta é a dist-tag beta do npm (pode corresponder a latest após a promoção). Dev é a ponta móvel de main (git); quando publicada, usa a dist-tag dev do npm.Comandos de uma linha (macOS/Linux):
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
Instalador do Windows (PowerShell): https://openclaw.ai/install.ps1Mais detalhes: Canais de desenvolvimento e Flags do instalador.
Duas opções:
  1. Canal dev (checkout git):
openclaw update --channel dev
Isso alterna para a branch main e atualiza a partir do código-fonte.
  1. Instalação editável (a partir do site do instalador):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
Isso fornece um repo local que você pode editar e depois atualizar via git.Se preferir um clone limpo manualmente, use:
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
Docs: Atualização, Canais de desenvolvimento, Instalação.
Guia aproximado:
  • Instalação: 2-5 minutos
  • Onboarding: 5-15 minutos, dependendo de quantos canais/modelos você configura
Se travar, use Instalador travado e o ciclo rápido de depuração em Estou travado.
Execute novamente o instalador com saída detalhada:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
Instalação beta com saída detalhada:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
Para uma instalação editável (git):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
Equivalente no Windows (PowerShell):
# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
Mais opções: Flags do instalador.
Dois problemas comuns no Windows:1) erro npm spawn git / git não encontrado
  • Instale o Git for Windows e garanta que git esteja no seu PATH.
  • Feche e reabra o PowerShell e execute novamente o instalador.
2) openclaw não é reconhecido após a instalação
  • Sua pasta bin global do npm não está no PATH.
  • Verifique o caminho: 
    npm config get prefix
  • Adicione esse diretório ao PATH do seu usuário (não é necessário o sufixo \bin no Windows; na maioria dos sistemas, é %AppData%\npm).
  • Feche e reabra o PowerShell após atualizar o PATH.
Se quiser a configuração mais tranquila no Windows, use WSL2 em vez do Windows nativo. Docs: Windows.
Isso geralmente é uma incompatibilidade de página de código do console em shells nativos do Windows.Sintomas:
  • A saída de system.run/exec renderiza chinês como mojibake
  • O mesmo comando parece correto em outro perfil de terminal
Solução rápida no PowerShell:
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
Depois reinicie o Gateway e tente novamente o comando:
openclaw gateway restart
Se você ainda conseguir reproduzir isso na versão mais recente do OpenClaw, acompanhe/relate em:
Use a instalação editável (git) para ter todo o código-fonte e a documentação localmente e, então, pergunte ao seu bot (ou Claude/Codex) a partir dessa pasta para que ele possa ler o repo e responder com precisão.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
Mais detalhes: Instalação e Flags do instalador.
Resposta curta: siga o guia do Linux e depois execute o onboarding.
Qualquer VPS Linux funciona. Instale no servidor e use SSH/Tailscale para acessar o Gateway.Guias: exe.dev, Hetzner, Fly.io. Acesso remoto: Gateway remoto.
Mantemos um hub de hospedagem com os provedores comuns. Escolha um e siga o guia:Como funciona na nuvem: o Gateway é executado no servidor, e você o acessa a partir do seu laptop/celular via Control UI (ou Tailscale/SSH). Seu estado + workspace ficam no servidor, portanto trate o host como a fonte da verdade e faça backup dele.Você pode parear nós (Mac/iOS/Android/headless) a esse Gateway na nuvem para acessar tela/câmera/canvas local ou executar comandos no seu laptop enquanto mantém o Gateway na nuvem.Hub: Plataformas. Acesso remoto: Gateway remoto. Nós: Nós, CLI de nós.
Resposta curta: possível, não recomendado. O fluxo de atualização pode reiniciar o Gateway (o que derruba a sessão ativa), pode precisar de um checkout git limpo e pode solicitar confirmação. Mais seguro: execute atualizações a partir de um shell como operador.Use a CLI:
openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart
Se precisar automatizar a partir de um agente:
openclaw update --yes --no-restart
openclaw gateway restart
Docs: Atualização, Atualizando.
openclaw onboard é o caminho de configuração recomendado. No modo local, ele guia você por:
  • Configuração de modelo/autenticação (OAuth de provedor, chaves de API, setup-token da Anthropic, além de opções de modelo local como LM Studio)
  • Localização do workspace + arquivos de bootstrap
  • Configurações do Gateway (bind/porta/autenticação/tailscale)
  • Canais (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, além de plugins de canal incluídos, como QQ Bot)
  • Instalação do daemon (LaunchAgent no macOS; unidade de usuário systemd no Linux/WSL2)
  • Verificações de integridade e seleção de skills
Ele também avisa se o modelo configurado for desconhecido ou não tiver autenticação.
Não. Você pode executar o OpenClaw com chaves de API (Anthropic/OpenAI/outros) ou com modelos somente locais, para que seus dados permaneçam no seu dispositivo. Assinaturas (Claude Pro/Max ou OpenAI Codex) são formas opcionais de autenticar esses provedores.Para Anthropic no OpenClaw, a divisão prática é:
  • Chave de API Anthropic: cobrança normal da API Anthropic
  • Claude CLI / autenticação de assinatura Claude no OpenClaw: a equipe da Anthropic nos disse que esse uso é permitido novamente, e o OpenClaw está tratando o uso de claude -p como sancionado para esta integração, a menos que a Anthropic publique uma nova política
Para hosts de gateway de longa duração, chaves de API Anthropic ainda são a configuração mais previsível. O OAuth do OpenAI Codex é explicitamente compatível com ferramentas externas como o OpenClaw.O OpenClaw também oferece suporte a outras opções hospedadas em estilo de assinatura, incluindo Qwen Cloud Coding Plan, MiniMax Coding Plan e Z.AI / GLM Coding Plan.Docs: Anthropic, OpenAI, Qwen Cloud, MiniMax, Modelos GLM, Modelos locais, Modelos.
Sim.A equipe da Anthropic nos disse que o uso da Claude CLI no estilo OpenClaw é permitido novamente, portanto o OpenClaw trata a autenticação de assinatura Claude e o uso de claude -p como sancionados para esta integração, a menos que a Anthropic publique uma nova política. Se você quiser a configuração do lado do servidor mais previsível, use uma chave de API Anthropic em vez disso.
Sim.A equipe da Anthropic nos disse que esse uso é permitido novamente, portanto o OpenClaw trata a reutilização da Claude CLI e o uso de claude -p como sancionados para esta integração, a menos que a Anthropic publique uma nova política.O setup-token da Anthropic ainda está disponível como um caminho de token do OpenClaw com suporte, mas agora o OpenClaw prefere a reutilização da Claude CLI e claude -p quando disponíveis. Para cargas de trabalho de produção ou multiusuário, a autenticação com chave de API Anthropic ainda é a escolha mais segura e previsível. Se quiser outras opções hospedadas em estilo de assinatura no OpenClaw, veja OpenAI, Qwen / Model Cloud, MiniMax e Modelos GLM.
Isso significa que sua cota/limite de taxa da Anthropic foi esgotada para a janela atual. Se você usa a Claude CLI, aguarde a janela ser redefinida ou faça upgrade do seu plano. Se você usa uma chave de API Anthropic, verifique o Console da Anthropic para uso/cobrança e aumente os limites conforme necessário.Se a mensagem for especificamente: Extra usage is required for long context requests, a solicitação está tentando usar a beta de contexto de 1M da Anthropic (context1m: true). Isso só funciona quando sua credencial é elegível para cobrança de contexto longo (cobrança por chave de API ou o caminho de login Claude do OpenClaw com Extra Usage habilitado).Dica: configure um modelo de fallback para que o OpenClaw possa continuar respondendo enquanto um provedor estiver com limite de taxa. Consulte Modelos, OAuth e /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.
Sim. O OpenClaw tem um provedor Amazon Bedrock (Converse) incluído. Com marcadores de ambiente da AWS presentes, o OpenClaw pode descobrir automaticamente o catálogo Bedrock de streaming/texto e mesclá-lo como um provedor amazon-bedrock implícito; caso contrário, você pode habilitar explicitamente plugins.entries.amazon-bedrock.config.discovery.enabled ou adicionar uma entrada manual de provedor. Consulte Amazon Bedrock e Provedores de modelos. Se preferir um fluxo de chave gerenciado, um proxy compatível com OpenAI na frente do Bedrock continua sendo uma opção válida.
O OpenClaw oferece suporte a OpenAI Code (Codex) via OAuth (login do ChatGPT). Use openai/gpt-5.5 para a configuração comum: autenticação por assinatura ChatGPT/Codex mais execução nativa no servidor de app do Codex. As refs de modelo openai-codex/gpt-* são configuração legada reparada por openclaw doctor --fix. O acesso direto por chave de API da OpenAI continua disponível para superfícies da API OpenAI que não sejam de agente e para modelos de agente por meio de um perfil de chave de API openai-codex ordenado. Consulte Provedores de modelos e Integração (CLI).
openai-codex é o id de provedor e perfil de autenticação para OAuth ChatGPT/Codex. Configurações mais antigas também o usavam como prefixo de modelo:
  • openai/gpt-5.5 = autenticação por assinatura ChatGPT/Codex com runtime nativo do Codex para turnos de agente
  • openai-codex/gpt-5.5 = rota de modelo legada reparada por openclaw doctor --fix
  • openai/gpt-5.5 mais um perfil de chave de API openai-codex ordenado = autenticação por chave de API para um modelo de agente OpenAI
  • openai-codex:... = id de perfil de autenticação, não uma ref de modelo
Se você quer o caminho direto de cobrança/limite da OpenAI Platform, defina OPENAI_API_KEY. Se você quer autenticação por assinatura ChatGPT/Codex, faça login com openclaw models auth login --provider openai-codex. Mantenha a ref de modelo como openai/gpt-5.5; refs de modelo openai-codex/* são configuração legada que openclaw doctor --fix reescreve.
O OAuth do Codex usa janelas de cota gerenciadas pela OpenAI e dependentes do plano. Na prática, esses limites podem diferir da experiência no site/app do ChatGPT, mesmo quando ambos estão vinculados à mesma conta.O OpenClaw pode mostrar as janelas de uso/cota do provedor atualmente visíveis em openclaw models status, mas ele não inventa nem normaliza direitos do ChatGPT-web em acesso direto à API. Se você quer o caminho direto de cobrança/limite da OpenAI Platform, use openai/* com uma chave de API.
Sim. O OpenClaw oferece suporte completo a OAuth por assinatura do OpenAI Code (Codex). A OpenAI permite explicitamente o uso de OAuth por assinatura em ferramentas/fluxos de trabalho externos como o OpenClaw. A integração pode executar o fluxo OAuth para você.Consulte OAuth, Provedores de modelos e Integração (CLI).
O Gemini CLI usa um fluxo de autenticação de Plugin, não um id de cliente ou segredo em openclaw.json.Etapas:
  1. Instale o Gemini CLI localmente para que gemini esteja no PATH
    • Homebrew: brew install gemini-cli
    • npm: npm install -g @google/gemini-cli
  2. Habilite o Plugin: openclaw plugins enable google
  3. Faça login: openclaw models auth login --provider google-gemini-cli --set-default
  4. Modelo padrão após o login: google-gemini-cli/gemini-3-flash-preview
  5. Se as solicitações falharem, defina GOOGLE_CLOUD_PROJECT ou GOOGLE_CLOUD_PROJECT_ID no host do gateway
Isso armazena tokens OAuth em perfis de autenticação no host do gateway. Detalhes: Provedores de modelos.
Geralmente, não. O OpenClaw precisa de contexto grande + segurança forte; placas pequenas truncam e vazam. Se for indispensável, execute localmente o build de modelo maior que puder (LM Studio) e consulte /gateway/local-models. Modelos menores/quantizados aumentam o risco de injeção de prompt - consulte Segurança.
Escolha endpoints fixados por região. O OpenRouter expõe opções hospedadas nos EUA para MiniMax, Kimi e GLM; escolha a variante hospedada nos EUA para manter os dados na região. Você ainda pode listar Anthropic/OpenAI junto com esses usando models.mode: "merge" para que fallbacks continuem disponíveis respeitando o provedor regional selecionado.
Não. O OpenClaw roda em macOS ou Linux (Windows via WSL2). Um Mac mini é opcional - algumas pessoas compram um como host sempre ligado, mas um VPS pequeno, servidor doméstico ou máquina da classe Raspberry Pi também funciona.Você só precisa de um Mac para ferramentas exclusivas do macOS. Para iMessage, use iMessage com imsg em qualquer Mac conectado ao Mensagens. Se o Gateway roda no Linux ou em outro lugar, defina channels.imessage.cliPath como um wrapper SSH que executa imsg nesse Mac. Se você quiser outras ferramentas exclusivas do macOS, execute o Gateway em um Mac ou emparelhe um nó macOS.Docs: iMessage, Nós, Modo remoto do Mac.
Você precisa de algum dispositivo macOS conectado ao Mensagens. Não precisa ser um Mac mini - qualquer Mac funciona. Use iMessage com imsg; o Gateway pode rodar nesse Mac ou em outro lugar com um wrapper SSH em cliPath.Configurações comuns:
  • Execute o Gateway no Linux/VPS e defina channels.imessage.cliPath como um wrapper SSH que executa imsg em um Mac conectado ao Mensagens.
  • Execute tudo no Mac se quiser a configuração mais simples em uma única máquina.
Docs: iMessage, Nós, Modo remoto do Mac.
Sim. O Mac mini pode executar o Gateway, e seu MacBook Pro pode se conectar como um nó (dispositivo complementar). Nós não executam o Gateway - eles fornecem recursos extras como tela/câmera/canvas e system.run nesse dispositivo.Padrão comum:
  • Gateway no Mac mini (sempre ligado).
  • MacBook Pro executa o app macOS ou um host de nó e emparelha com o Gateway.
  • Use openclaw nodes status / openclaw nodes list para vê-lo.
Docs: Nós, CLI de nós.
Bun não é recomendado. Vemos bugs de runtime, especialmente com WhatsApp e Telegram. Use Node para gateways estáveis.Se você ainda quiser experimentar Bun, faça isso em um gateway que não seja de produção sem WhatsApp/Telegram.
channels.telegram.allowFrom é o ID de usuário Telegram do remetente humano (numérico). Não é o nome de usuário do bot.A configuração solicita apenas IDs de usuário numéricos. Se você já tem entradas @username legadas na configuração, openclaw doctor --fix pode tentar resolvê-las.Mais seguro (sem bot de terceiros):
  • Envie DM para seu bot, depois execute openclaw logs --follow e leia from.id.
API oficial de bots:
  • Envie DM para seu bot, depois chame https://api.telegram.org/bot<bot_token>/getUpdates e leia message.from.id.
Terceiros (menos privado):
  • Envie DM para @userinfobot ou @getidsbot.
Consulte /channels/telegram.
Sim, via roteamento multiagente. Vincule a DM de WhatsApp de cada remetente (peer kind: "direct", remetente E.164 como +15551234567) a um agentId diferente, para que cada pessoa tenha seu próprio workspace e armazenamento de sessão. As respostas ainda vêm da mesma conta do WhatsApp, e o controle de acesso por DM (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) é global por conta do WhatsApp. Consulte Roteamento multiagente e WhatsApp.
Sim. Use roteamento multiagente: dê a cada agente seu próprio modelo padrão e vincule rotas de entrada (conta de provedor ou peers específicos) a cada agente. A configuração de exemplo está em Roteamento multiagente. Veja também Modelos e Configuração.
Sim. O Homebrew oferece suporte ao Linux (Linuxbrew). Configuração rápida:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>
Se você executar o OpenClaw via systemd, garanta que o PATH do serviço inclua /home/linuxbrew/.linuxbrew/bin (ou seu prefixo do brew) para que ferramentas instaladas pelo brew resolvam em shells sem login. Builds recentes também prefixam diretórios bin comuns de usuário em serviços systemd no Linux (por exemplo ~/.local/bin, ~/.npm-global/bin, ~/.local/share/pnpm, ~/.bun/bin) e respeitam PNPM_HOME, NPM_CONFIG_PREFIX, BUN_INSTALL, VOLTA_HOME, ASDF_DATA_DIR, NVM_DIR e FNM_DIR quando definidos.
  • Instalação hackeável (git): checkout completo do código-fonte, editável, melhor para contribuidores. Você executa builds localmente e pode corrigir código/docs.
  • Instalação npm: instalação global da CLI, sem repo, melhor para “apenas executar”. Atualizações vêm de dist-tags do npm.
Docs: Primeiros passos, Atualização.
Sim. Use openclaw update --channel ... quando o OpenClaw já estiver instalado. Isso não exclui seus dados - apenas altera a instalação do código do OpenClaw. Seu estado (~/.openclaw) e workspace (~/.openclaw/workspace) permanecem intocados.De npm para git:
openclaw update --channel dev
De git para npm:
openclaw update --channel stable
Adicione --dry-run para pré-visualizar primeiro a troca de modo planejada. O atualizador executa acompanhamentos do Doctor, atualiza as fontes de Plugin para o canal de destino e reinicia o gateway, a menos que você passe --no-restart.O instalador também pode forçar qualquer um dos modos:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
Dicas de backup: consulte Estratégia de backup.
Resposta curta: se você quer confiabilidade 24/7, use um VPS. Se você quer o menor atrito e aceita suspensões/reinicializações, execute localmente.Laptop (Gateway local)
  • Prós: sem custo de servidor, acesso direto a arquivos locais, janela do navegador ao vivo.
  • Contras: suspensão/quedas de rede = desconexões, atualizações/reinicializações do SO interrompem, precisa permanecer acordado.
VPS / nuvem
  • Prós: sempre ativo, rede estável, sem problemas de suspensão do laptop, mais fácil de manter em execução.
  • Contras: geralmente executado sem interface gráfica (use capturas de tela), acesso remoto apenas a arquivos, você precisa usar SSH para atualizações.
Observação específica do OpenClaw: WhatsApp/Telegram/Slack/Mattermost/Discord funcionam bem a partir de um VPS. A única troca real é navegador sem interface gráfica versus uma janela visível. Consulte Navegador.Padrão recomendado: VPS se você já teve desconexões do Gateway antes. Local é ótimo quando você está usando ativamente o Mac e quer acesso a arquivos locais ou automação de interface com um navegador visível.
Não é obrigatório, mas recomendado para confiabilidade e isolamento.
  • Host dedicado (VPS/Mac mini/Pi): sempre ativo, menos interrupções por suspensão/reinicialização, permissões mais limpas, mais fácil de manter em execução.
  • Laptop/desktop compartilhado: totalmente adequado para testes e uso ativo, mas espere pausas quando a máquina entrar em suspensão ou atualizar.
Se você quer o melhor dos dois mundos, mantenha o Gateway em um host dedicado e emparelhe seu laptop como um nó para ferramentas locais de tela/câmera/execução. Consulte Nós. Para orientações de segurança, leia Segurança.
O OpenClaw é leve. Para um Gateway básico + um canal de chat:
  • Mínimo absoluto: 1 vCPU, 1 GB de RAM, ~500 MB de disco.
  • Recomendado: 1-2 vCPU, 2 GB de RAM ou mais para folga (logs, mídia, vários canais). Ferramentas de Node e automação de navegador podem consumir muitos recursos.
SO: use Ubuntu LTS (ou qualquer Debian/Ubuntu moderno). O caminho de instalação no Linux é mais bem testado nele.Documentação: Linux, Hospedagem VPS.
Sim. Trate uma VM da mesma forma que um VPS: ela precisa estar sempre ligada, acessível e ter RAM suficiente para o Gateway e quaisquer canais que você habilitar.Orientação de base:
  • Mínimo absoluto: 1 vCPU, 1 GB de RAM.
  • Recomendado: 2 GB de RAM ou mais se você executar vários canais, automação de navegador ou ferramentas de mídia.
  • SO: Ubuntu LTS ou outro Debian/Ubuntu moderno.
Se você estiver no Windows, WSL2 é a configuração em estilo VM mais fácil e tem a melhor compatibilidade com ferramentas. Consulte Windows, Hospedagem VPS. Se você estiver executando macOS em uma VM, consulte VM macOS.

​
Relacionado