Um comando de instalação e um token de bot: como configurar o OpenClaw 2.0 se você nunca rodou um agente

Os números oficiais de instalação do OpenClaw são pouco espetaculares, e isso é um elogio. O script de instalação leva 2 a 5 minutos. O onboarding QuickStart leva "alguns minutos". Depois você digita openclaw dashboard, uma aba do navegador abre, você manda uma mensagem e alguma coisa responde.

Ou seja: a parte difícil não é a instalação. A parte difícil é a semana seguinte — decidir no que essa coisa pode encostar, o que pedir a ela e o que fazer quando ela fica calada e você não faz ideia do porquê.

Este guia é o companheiro prático da nossa leitura sobre o que a versão 2.0 mudou de fato. Aqui não há análise, só procedimento: o que ter em mãos, os comandos exatos, o que o novo onboarding guiado pergunta e em que ordem, como ligar no Telegram, três primeiras tarefas do tamanho certo, as permissões para acertar no primeiro dia e as cinco falhas em que instalações novas realmente tropeçam. Todo comando abaixo vem da documentação oficial do OpenClaw, consultada em 1º de setembro de 2026. Onde a documentação se cala, este guia diz isso em vez de chutar.

Resumo:

• Você precisa de Node.js 22.22.3+, 24.15+ ou 25.9+ (Node 26 recomendado) e de uma fonte de IA: um login de Claude ou ChatGPT que você já tenha, uma chave de API ou um modelo local.
• O caminho para iniciantes é uma linha — curl -fsSL https://openclaw.ai/install.sh | bash — que instala o Node se ele faltar e já abre o onboarding.
• O onboarding guiado da 2.0 tenta primeiro reaproveitar o acesso de IA que você já tem e não salva nenhuma rota de modelo antes de uma completion real funcionar. Essa mudança sozinha elimina o jeito mais comum pelo qual instalações antigas falhavam em silêncio.

Os passos 1 a 4 são o início rápido documentado. Fonte: OpenClaw "Getting started" e "Install", consultados em 1º de setembro de 2026.

O que ter antes de digitar qualquer coisa

Três pré-requisitos, e só um deles exige uma decisão.

Um Node.js suportado. A página de instalação lista Node 22.22.3+, 24.15+ ou 25.9+, com o Node 26 recomendado. Confira o seu com node --version. Se o Node não existir na máquina, o instalador provisiona — Node 26 no macOS, Node 24 LTS no Linux.

Uma máquina que fique acordada. macOS, Linux e Windows funcionam. A documentação coloca o trade-off sem rodeios: um notebook é a opção de menor atrito e dá ao agente acesso direto aos seus arquivos locais e a uma janela de navegador visível, mas suspensão, quedas de rede e atualizações do sistema interrompem tudo isso. Um servidor pequeno fica sempre ligado, porém sem tela. O mínimo documentado para um VPS é 1 vCPU, 1 GB de RAM e cerca de 500 MB de disco, com 2 GB ou mais recomendados por folga. Um Raspberry Pi 4 de 4 GB dá conta, porque o Pi roda apenas o gateway enquanto o modelo é chamado pela rede.

Comece no notebook que você já tem. Depois dá para mover tudo copiando dois diretórios, e essa migração está documentada.

Uma fonte de IA. Aqui está a decisão. O OpenClaw não traz um modelo; ele se conecta a um.

A configuração guiada detecta a rota 1 automaticamente. Preços de tabela dos fornecedores, consultados em 1º de setembro de 2026.

Coloque um número real na linha da chave de API, porque "cobrança por token" não ajuda nada na hora de decidir. Suponha trinta trocas por dia, cada uma enviando cerca de 8.000 tokens de contexto e devolvendo 700. São 240.000 tokens de entrada e 21.000 de saída por dia. Nos preços de tabela do Claude Sonnet 5, isso dá cerca de 0,69 dólar por dia, perto de 21 por mês. Com o gpt-5.6-luna, cerca de 0,07 dólar por dia, perto de 2,20 por mês. É aritmética sobre preços publicados, não uma fatura medida — seu contexto será maior do que você imagina e o cache devolve parte disso — mas a ordem de grandeza fica estabelecida: dólares, não centenas de dólares.

Nossa recomendação para a primeira instalação: use a assinatura que você já paga, porque a configuração guiada a encontra sem você colar nada. Caso contrário, pegue uma chave de API em qualquer fornecedor e defina um teto de gasto rígido no console dele antes de rodar o onboarding. Deixe os modelos locais para depois; são um destino legítimo, mas uma péssima linha de partida.

Instalação: um comando e duas alternativas que vale conhecer

O caminho para iniciantes documentado é o script de instalação. Ele detecta o sistema, instala o Node se necessário, instala o OpenClaw e abre o onboarding — um comando no lugar de quatro decisões.

No macOS, Linux ou WSL2:

curl -fsSL https://openclaw.ai/install.sh | bash

No Windows PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

Essa é a instalação inteira. Duas alternativas valem ser conhecidas mesmo que você não as use hoje.

Aplicativos de desktop, se o terminal não for o seu lugar. O Windows tem um instalador Hub assinado que roda como qualquer programa do Windows; o macOS tem um app de barra de menus distribuído como .dmg nos releases do projeto no GitHub. Os dois conseguem provisionar um gateway local na primeira execução.

npm, se você já gerencia o Node por conta própria. No npm 12 ou npm 11.16+:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

A opção --allow-scripts=openclaw importa: o npm 12 bloqueia por padrão scripts de ciclo de vida não aprovados e, sem ela, reporta os passos preinstall e postinstall do OpenClaw como "blocked because they are not covered by allowScripts". No npm 11.15 e anteriores, rode o mesmo comando sem a opção. Docker, Podman, Nix e uma build a partir do código com pnpm também estão documentados, e todos são a escolha errada para a sua primeira hora.

O que o onboarding guiado da 2.0 pergunta, em ordem

É aqui que a v2026.8.1 mais mudou a experiência de quem está começando, então vale saber o que vem. O simples openclaw onboard — que o instalador abre para você — agora segue um caminho guiado de seis etapas:

1. Aceitar o aviso de segurança. Leia. Ele enuncia o modelo de confiança ao qual você está aderindo, e a última seção deste guia traduz isso em linguagem direta.
2. Uma detecção somente leitura é executada. O OpenClaw procura modelos já configurados, chaves de API em variáveis de ambiente, CLIs de IA locais suportadas e modelos com suporte a ferramentas já instalados em um servidor Ollama ou LM Studio alcançável. Essa passagem nunca baixa um modelo. Há duas exclusões documentadas: Gemini CLI e Antigravity não são oferecidos como rotas detectadas, e instalações de Pi e OpenCode podem aparecer como informação sem servirem de rota de inferência.
3. O primeiro candidato é testado com uma completion real. Se falhar, o onboarding mostra o motivo e passa ao próximo candidato em vez de salvar uma rota quebrada.
4. Se a detecção não achar nada, você escolhe um fornecedor. O primeiro menu traz OpenAI, Anthropic, xAI (Grok), Google e OpenRouter, com More… para o restante e Custom Provider para um endpoint não listado. Um segundo menu mostra regiões, planos e métodos de autenticação suportados — navegador, dispositivo, chave de API ou token. Toda rota passa pelo mesmo teste de completion real. Skip for now sai sem prosseguir.
5. Só a rota verificada é salva, junto com as credenciais ou o estado de plugin de que ela precisa. Seu workspace e as configurações do gateway ficam intactos nesta etapa.
6. O assistente de configuração inicia com esse modelo verificado e configura o resto por conversa — workspace, gateway, canais, agentes, plugins.

Depois verifique você mesmo:

openclaw gateway status     # deve mostrar o gateway ouvindo na porta 18789
openclaw dashboard          # abre a Control UI no navegador

Digite uma mensagem no chat da Control UI. Uma resposta significa que todas as camadas funcionam.

E aqui está o ponto, a coisa mais útil de se entender sobre a 2.0: o fluxo guiado se recusa a salvar uma rota de modelo cujo funcionamento ele não provou. Rodar openclaw onboard de novo numa instalação já configurada funciona, portanto, como passagem de reparo: ele testa primeiro o modelo padrão atual e, se falhar, nunca troca o modelo em silêncio — para e pergunta.

Duas coisas o onboarding guiado deliberadamente não faz. Não trata de configuração de gateway remoto, assistentes de pareamento de canal, controle do daemon, skills ou importações — isso mora no assistente clássico, openclaw onboard --classic. E para mudar de fornecedor ou de autenticação depois, você sai do assistente e roda openclaw onboard de novo; o assistente conversacional não abre fluxos de fornecedor.

Conectar o Telegram: quatro passos e um número que você precisa achar

A documentação aponta o Telegram como o canal mais rápido de montar, porque não exige nada além de um token de bot. A política de mensagens diretas vem por padrão em pairing, que é o padrão seguro e a razão de existir o passo 3.

1. Crie o bot. No Telegram, mande mensagem para @BotFather — confira que o nome é exatamente esse — e rode /newbot. Siga as instruções e guarde o token. Há também um fluxo web pelo app do BotFather, se você preferir interface.

2. Coloque o token na configuração, em ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

A variável de ambiente TELEGRAM_BOT_TOKEN funciona como alternativa, mas só para a conta padrão. O Telegram não usa openclaw channels login telegram — coloque o token na configuração ou no ambiente e inicie o gateway.

3. Inicie o gateway, mande mensagem ao bot e aprove você mesmo:

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Os códigos de pareamento expiram em 1 hora. Se o seu venceu, mande outra mensagem ao bot para receber um novo.

4. Descubra seu ID numérico de usuário do Telegram e fixe-o. A aprovação de pareamento concede acesso apenas às mensagens diretas; não é autorização geral. O método com mais privacidade indicado na documentação: mande mensagem ao seu bot, rode openclaw logs --follow e leia from.id na linha de log. O caminho oficial da Bot API é curl "https://api.telegram.org/bot<bot_token>/getUpdates" e ler message.from.id. Existem bots de terceiros para isso, menos privados. Com o número em mãos, para um bot de dono único a documentação recomenda dmPolicy: "allowlist" com seu ID numérico em channels.telegram.allowFrom, em vez de depender de uma aprovação de pareamento antiga.

Grupos são outra decisão, com outra armadilha. Bots do Telegram vêm em Privacy Mode por padrão, o que limita quais mensagens de grupo eles chegam a receber. Para ver tudo, desative esse modo com /setprivacy no BotFather ou torne o bot administrador do grupo — e, depois de alternar, é preciso remover e adicionar o bot de novo em cada grupo para o Telegram aplicar a mudança. No primeiro dia, pule os grupos.

Discord, Signal, WhatsApp, Slack, iMessage, Matrix, Microsoft Teams e mais uns vinte canais são suportados, cada um com sua página. Nenhum deles sobe tão rápido quanto um token de bot.

Suas três primeiras tarefas, no tamanho de uma semana

Agentes são bons em buscar, resumir, vigiar e lembrar. São pouco confiáveis em qualquer coisa em que errar sai caro e ninguém confere. Escolha primeiras tarefas em que uma resposta errada custe cinco segundos de irritação.

Tarefa um: um lembrete único. Ela prova que agendador, modelo e rota de entrega funcionam juntos, e se apaga sozinha ao terminar.

openclaw automations create "2026-09-08T09:00:00Z" \
  --name "Reminder" \
  --session main \
  --system-event "Reminder: review the OpenClaw permissions I set on day one" \
  --wake now \
  --delete-after-run

Tarefa dois: um resumo matinal recorrente. O campo de agendamento aceita uma expressão cron padrão, e o prompt é o segundo argumento posicional.

openclaw automations create "0 7 * * *" \
  "Summarize what changed in my workspace notes since yesterday." \
  --name "Morning brief"

Depois inspecione o que você construiu, porque ler o histórico de execuções é como se aprende o que o agente de fato fez:

openclaw automations list
openclaw automations runs --id <job-id>

Duas propriedades das automações merecem ser internalizadas agora. Elas rodam dentro do processo do gateway, o que significa que os agendamentos só disparam enquanto o gateway estiver de pé — um notebook fechado é um agendador parado. E cada execução cria um registro de tarefa em segundo plano, então openclaw tasks list e openclaw tasks audit dão uma trilha de auditoria em vez de um mistério.

Tarefa três: algo somente leitura sobre o seu próprio material. Aponte o agente para o workspace dele e peça que resuma, procure ou compare. Sem escrita, sem e-mail, sem calendário, sem shell. O que você está fazendo é calibrar: depois de uma semana você saberá, em concreto, quais pedidos ele acerta e quais responde com confiança e errado. Essa calibração é o entregável real da primeira semana — não as automações.

O que segurar: o caminho de e-mail documentado, o gatilho IMAP, é um padrão genuinamente útil, mas a própria documentação dele o configura atrás de um agente leitor restrito dedicado, com tools.profile: "minimal", um sandbox com workspaceAccess: "none", uma lista de remetentes permitidos e autenticação de remetente baseada em DMARC. É exatamente a dose certa de paranoia para deixar texto de estranhos chegar a um modelo, e não é projeto de primeiro dia.

O perímetro do primeiro dia: decida até onde ele alcança antes de decidir o que ele faz

A página de segurança do OpenClaw abre afirmando que o produto sai com padrões conservadores: o gateway escuta em loopback, a maioria dos canais responde a uma mensagem direta desconhecida com um código de pareamento em vez de processá-la, e o acesso a grupos passa por lista de permissões atrás de uma barreira de menção. Seu trabalho no primeiro dia é, sobretudo, não desfazer isso.

O modelo de confiança, em linguagem simples. Um gateway equivale a uma fronteira de confiança. Todo mundo que pode mandar mensagem para um agente com ferramentas compartilha a autoridade dessas ferramentas. Para você, tudo bem; para colegas que já confiam uns nos outros, tudo bem; e para usuários mutuamente hostis dividindo um agente, explicitamente sem suporte. Quem consegue editar arquivos em ~/.openclaw é, por definição, um operador confiável. Se você precisa atender pessoas que não confiam entre si, a resposta documentada é separar gateways, de preferência também usuários do sistema ou máquinas — não uma configuração esperta.

Um comando diz se você saiu da linha:

openclaw security audit
openclaw security audit --fix    # aplica só correções estreitas e seguras

A própria ordem de triagem da auditoria é uma boa lista de prioridades para iniciantes: primeiro qualquer coisa "aberta" combinada com ferramentas ativas, depois exposição pública na rede, depois exposição do controle do navegador, depois permissões de arquivos, depois plugins e por último a escolha do modelo.

O que não conectar na primeira semana. Não deixe nenhuma dmPolicy como "open" — isso permite que qualquer conta do Telegram que ache ou adivinhe o nome do seu bot dê ordens a ele. Não exponha o gateway além do loopback e não ligue o Tailscale Funnel. Não habilite tools.elevated, a saída de emergência que roda comandos de shell fora do sandbox. Não instale plugins que você não leu. E prefira o modelo de geração atual mais forte que conseguir, porque a documentação é explícita: modelos mais fracos ou excessivamente quantizados são mais fáceis de sequestrar por injeção de prompt — o que passa a importar no instante em que um agente com ferramentas lê texto escrito por outra pessoa.

Comece somente leitura onde der. Um perfil documentado combina um sandbox com workspaceAccess: "ro" e uma lista de ferramentas negadas:

{
  agents: {
    entries: {
      family: {
        default: true,
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: ["read"],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    },
  },
}

Como parar. Aprenda esses comandos antes de precisar deles, não depois.

openclaw gateway stop        # para o serviço gerenciado
openclaw gateway restart     # reinicia (não encadeie stop e start como substituto)
openclaw backup create       # snapshot antes de qualquer operação destrutiva
openclaw uninstall --dry-run # ver exatamente o que uma remoção apagaria

openclaw gateway stop exige --force em um shell não interativo. No macOS ele remove o LaunchAgent da sessão de boot atual; use --disable se quiser que a parada sobreviva a um reinício. E a ordem de contenção, se algo realmente sair errado: parar o processo, definir gateway.bind: "loopback" e então mudar as mensagens diretas de risco para dmPolicy: "disabled" e apagar toda entrada "*".

As cinco falhas em que iniciantes realmente tropeçam

openclaw: command not found depois de uma instalação bem-sucedida. Quase sempre é PATH — o diretório bin global do npm não está no PATH do seu shell. Diagnostique com node -v, npm prefix -g e echo "$PATH". No Windows, confira npm config get prefix, adicione esse diretório ao PATH do usuário e reabra o PowerShell.

O instalador parece travado. Rode de novo com --verbose para ter retorno de verdade: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --verbose. O instalador do PowerShell não tem chave verbose; envolva-o em Set-PSDebug -Trace 1.

O onboarding mostra a linha de despertar, nada responde e a contagem de tokens fica em 0. O agente nunca rodou. Reinicie o gateway e então cheque autenticação e logs nesta ordem:

openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --follow
openclaw doctor

Se você pulou a configuração de modelo, o onboarding avisa com a nota "Model auth missing" — resolva com openclaw configure --section model.

O Telegram reporta getMe returned 401 na inicialização. É falha de autenticação do seu token de bot, ponto. Copie de novo ou regenere o token no BotFather e atualize channels.telegram.botToken. Um deleteWebhook 401 Unauthorized durante a inicialização é o mesmo token ruim aparecendo em outra chamada.

O bot ignora mensagens de grupo. Cheque três coisas nesta ordem: se o modo privacidade ainda está ligado (BotFather /setprivacy, depois remover e readicionar o bot), se o grupo está mesmo listado em channels.telegram.groups, e qual motivo de descarte aparece em openclaw logs --follow. IDs negativos de supergrupo que começam com -100 vão em groups, não em groupAllowFrom — uma confusão realmente comum.

Quando nada disso resolve, um comando transforma o estado da sua instalação em diagnóstico: openclaw triage roda verificações somente leitura, escreve um prompt higienizado com o que encontrou e oferece entregar esse prompt a um agente de código presente na sua máquina. Nada sai da sua máquina até você escolher um, e segredos, tokens, payloads brutos de conversa e logs brutos ficam fora do prompt.

Para onde ir depois

O destino é a documentação, e ela é surpreendentemente navegável: acrescente .md a qualquer URL de página para obter Markdown limpo, e docs.openclaw.ai/llms.txt é um índice completo de todas as páginas com uma linha de descrição. Para favoritar no primeiro dia: Getting started, Channels, Security e Automations. O comando openclaw docs busca nesse índice pelo terminal.

Um limite honesto antes de encerrar. Agentes erram, e um agente com ferramentas comete erros que encostam em coisas. A própria documentação do OpenClaw diz isso sem rodeios: o texto devolvido por busca, fetch, MCP, plugins e navegador é limitado, normalizado e explicitamente marcado como não confiável antes de o modelo vê-lo — e, mesmo assim, "o modelo ainda pode ser influenciado por material hostil que lê". Adote o hábito de conceder a permissão mais estreita que torna uma tarefa possível e alargue o perímetro só quando uma tarefa específica exigir.

Conclusão: a instalação leva oito minutos, o discernimento leva o resto da semana

A instalação é mesmo um comando. O onboarding realmente encontra a assinatura que você já paga. O que nenhum instalador faz por você é decidir até onde um processo autônomo pode alcançar em seu nome — e é essa decisão, não a instalação, que separa quem tira trabalho de verdade de um agente de quem para de abri-lo discretamente depois de duas semanas.

Comece com um agente somente leitura que, no máximo, pode te irritar. Alargue o perímetro uma permissão de cada vez, sempre porque uma tarefa específica exigiu. É uma primeira semana mais lenta e um segundo mês muito melhor.

O que você realmente confiaria a um programa enquanto não está olhando?

---

Onde o Telli.sh entra: um agente cuida das tarefas que você entrega a ele; o Telli.sh guarda o registro das conversas que você tem com pessoas. Ele aplica transcrição em tempo real, separação de falantes e resumos com IA às suas reuniões, com tradução para 44 idiomas de destino e interface em 15 — para que as decisões tomadas numa chamada virem uma nota pesquisável e não uma lembrança. Se o seu agente vai agir com base no que a equipe combinou, algo precisa ter escrito esse acordo com precisão antes.

Começar uma nota de IA ao vivo

Fontes

• OpenClaw — Getting started — exigência de Node 22.22.3+/24.15+/25.9+, comandos de instalação, openclaw gateway status na porta 18789, openclaw dashboard e openclaw triage; consultado em 1º de setembro de 2026
• OpenClaw — Install — requisitos de sistema, downloads dos aplicativos de desktop, caminhos npm/pnpm/bun e a política --allow-scripts=openclaw do npm 12, solução de problemas de PATH; consultado em 1º de setembro de 2026
• OpenClaw — Onboarding (CLI) — o caminho guiado de seis etapas, a verificação por completion real, os menus de fornecedores, a exclusão de Gemini CLI e Antigravity e o escopo de --classic; consultado em 1º de setembro de 2026
• OpenClaw — Notas da versão v2026.8.1 (OpenClaw 2.0) — onboarding guiado como fluxo custodian local, entrega ao navegador após a configuração e marcação de conteúdo externo não confiável; consultado em 1º de setembro de 2026
• OpenClaw — Telegram — /newbot no BotFather, bloco de configuração, openclaw pairing list/approve, expiração de uma hora, modo privacidade e a exigência de readicionar o bot, regra dos IDs -100 e a assinatura getMe returned 401; consultado em 1º de setembro de 2026
• OpenClaw — Security — padrões conservadores, modelo de uma fronteira de confiança por gateway, openclaw security audit e sua ordem de triagem, perfil de agente somente leitura e sequência de contenção; consultado em 1º de setembro de 2026
• OpenClaw — FAQ: first-run setup — estimativa de 2 a 5 minutos, reaproveitamento do Claude CLI e sua ressalva de cobrança, suporte a OAuth do Codex, sequência de recuperação quando não há resposta, mínimos de VPS e o trade-off notebook versus servidor; consultado em 1º de setembro de 2026
• OpenClaw — FAQ: models and auth — a recomendação do modelo mais forte para agentes com ferramentas e o caminho de configuração do Ollama; consultado em 1º de setembro de 2026
• OpenClaw — Automations e openclaw automations — sintaxe create para jobs únicos e cron, execução dentro do gateway e histórico; consultado em 1º de setembro de 2026
• OpenClaw — Local models — a limitação de uma GPU única de 24 GB e o alerta sobre checkpoints quantizados; consultado em 1º de setembro de 2026
• OpenClaw — openclaw gateway e openclaw uninstall — semântica de parada e reinício, exigência de --force em shells não interativos e remoção com --dry-run; consultado em 1º de setembro de 2026
• Anthropic — Preços dos modelos — Claude Sonnet 5 a 2/10 dólares por milhão de tokens e Claude Opus 5 a 5/25; consultado em 1º de setembro de 2026
• OpenAI — Preços da API — gpt-5.6-luna a 0,20 dólar de entrada e 1,20 de saída por milhão de tokens; consultado em 1º de setembro de 2026
• Nosso artigo companheiro sobre o que o lançamento do OpenClaw 2.0 realmente mudou