Documentação do OpenClaw: por onde começar a ler?

Fala aí, beleza? Você abre a documentação do OpenClaw pela primeira vez, bate o olho no menu lateral e pensa: "cara, isso aqui é um livro" 😅

E é grande mesmo, porque o projeto cobre muita coisa: um Gateway self-hosted, adaptadores pros apps de mensagem, ferramentas, skills, automação, nodes, referência de CLI

Só que tem um detalhe que muda tudo: no primeiro dia você precisa de uma fatia bem pequena disso

O resto não é leitura obrigatória, é consulta pra quando o problema aparecer

A sensação de travar antes de começar é a mesma de quem fica meses decidindo entre front-end e back-end em vez de escrever a primeira linha de código

Então bora montar a rota de leitura, na ordem, e deixar claro o que só faz sentido depois…

Onde a documentação oficial do OpenClaw fica (e de onde ela vem)

A doc publicada mora em docs.openclaw.ai

Esse é o link que você cita, salva nos favoritos e manda pro colega

Tem uma página de hubs que serve de porta de entrada pras áreas de topo: https://docs.openclaw.ai/start/hubs

Se você é do tipo que gosta de ver o mapa antes de andar, começa por ela

E de onde esse texto nasce?

Aqui vale entender o bastidor, porque isso resolve uma dúvida chata: onde reclamar quando a doc está errada?

Os textos em inglês são escritos na pasta docs/ do repositório openclaw/openclaw

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

O repositório openclaw/docs é um espelho: um workflow (.github/workflows/docs-sync-publish.yml) copia a árvore pra lá, e o arquivo .openclaw-sync/source.json registra de qual commit veio aquele espelho

Esse mesmo repo espelho é onde vive a saída dos locales gerados, ou seja, a parte de tradução, com fluxo incremental e reconciliação completa

A analogia que gosto de usar: é tipo um site estático publicado a partir de outro repositório

Você lê no site bonitinho, mas a fonte de verdade em inglês está no repo do projeto, não no espelho

A rota de leitura do primeiro dia, na ordem

Essa é a sequência que eu seguiria se estivesse abrindo a documentação do OpenClaw agora, do zero

Cada passo tem o erro clássico de quem lê fora de ordem, se liga:

1. Getting started (https://docs.openclaw.ai/start/getting-started): é a página de início rápido, e ela promete Gateway rodando, auth configurada e sessão de chat funcionando em cerca de 5 minutos. Leia inteira antes de digitar qualquer coisa

2. Confira os requisitos antes de instalar: a própria página declara Node.js 22.22.3+, 24.15+ ou 25.9+ (com Node 26 como runtime recomendado) e uma chave de API de um provedor de modelo (Anthropic, OpenAI, Google etc). O erro comum deste passo é achar que dá pra rodar sem chave de provedor e só descobrir isso no meio do onboarding, com o terminal aberto e a paciência acabando 😛

3. Visão geral do onboarding (https://docs.openclaw.ai/start/onboarding-overview): essa página separa o onboarding feito pelo terminal do onboarding pelo app de macOS. A doc é direta: a maioria deve começar pelo onboarding via CLI, porque funciona em todo lugar e dá mais controle. O erro comum aqui é usuário de Mac ir direto pro app e depois não achar na doc os passos que estão descritos pro caminho do CLI

4. Página do wizard (https://docs.openclaw.ai/start/wizard): o assistente conduz a escolha do provedor de modelo, a definição da chave de API e a configuração do Gateway. Ler antes evita aquele clique no escuro de "next, next e finish" sem saber o que ficou definido

5. Seção de instalação (https://docs.openclaw.ai/install): sim, ela é separada do Getting started, e esse é o erro de leitura mais comum de todos. O caminho recomendado é o script instalador, que baixa o release mais recente, instala globalmente e já chama o onboarding

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

No Windows, o equivalente é via PowerShell:

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

6. Conheça as alternativas de instalação: a mesma seção traz instalação por npm e por Docker, útil quando você não quer script rodando direto no seu shell

npm install -g openclaw@latest

docker run -p 18789:18789 -v ~/.openclaw:/root/.openclaw ghcr.io/openclaw/openclaw:latest

7. Verificação pós-instalação: a doc sugere dois comandos do CLI. O primeiro confirma que o Gateway subiu (ele escuta na porta 18789) e o segundo abre a Control UI no navegador

openclaw gateway status
openclaw dashboard

O erro comum deste passo é pular a verificação e ir configurar canal na sequência

Aí quando o Telegram não responde, você não sabe se o problema é o canal ou se o Gateway nunca subiu direito

8. Só depois disso, volte pro mapa: com o Gateway no ar e o dashboard aberto, aí sim vale abrir a tabela da próxima seção e escolher o que ler

Se você já passou por onboarding de outro agente de terminal, tipo quem está começando no Claude Code, esse ritmo vai parecer familiar: instala, autentica, testa uma sessão, depois configura o resto

Mapa das seções da documentação: o que cada uma cobre e quando ler

Essa tabela é o resumo que eu queria ter tido na primeira visita

A coluna da direita é a mais importante: ela separa o que é leitura de primeira visita do que só faz sentido com o Gateway já rodando

Repara que metade da tabela é consulta, não leitura corrida

Ninguém lê referência de configuração de ponta a ponta, beleza? Você abre na chave que precisa e fecha

Qual seção abrir depois, conforme o seu objetivo

Com o Gateway rodando, a doc deixa de ser um livro e vira menu

Escolhe pelo que você quer fazer:

Quero o agente respondendo no Telegram ou no WhatsApp

Vai pra Channels

Canais são adaptadores: eles pegam mensagens e eventos dos apps e normalizam pra um formato único que o Gateway entende

É por isso que o OpenClaw consegue falar com tanta coisa: Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, WhatsApp e mais, com os plugins oficiais de canal somando Matrix, Nextcloud Talk, Nostr, Twitch, Zalo e outros

As duas páginas que você vai usar de verdade: https://docs.openclaw.ai/channels/pairing e https://docs.openclaw.ai/channels/troubleshooting

Quero tarefa recorrente

Vai pra Automation

O agendador é embutido e aceita três formatos: lembrete único, expressão cron recorrente e gatilho por webhook de entrada

A saída pode cair em um canal de chat ou em um webhook, o que abre bastante coisa (relatório diário chegando no Telegram, por exemplo)

Quero ensinar o agente a usar ferramentas

Vai pra Tools e a página de skills

Skill aqui não é mágica, é arquivo

Cada skill vive em um diretório com um SKILL.md (frontmatter YAML mais corpo markdown)

O OpenClaw carrega as skills embutidas mais os overrides locais, e ainda filtra na carga por ambiente, config e presença de binário, com precedência da fonte mais alta

Ou seja: se uma skill sua não aparece, o motivo provavelmente está nesse filtro, não no modelo

Quero entender o desenho antes de mexer

Vai pra Concepts

A ideia central é simples: um único processo Gateway self-hosted rodando na sua máquina ou no seu servidor, fazendo a ponte entre os apps de mensagem e o agente

Depois que isso cai a ficha, o resto da documentação fica MUITO mais fácil de ler

O que a documentação não substitui: a parte de memória e skills

Agora a parte que a doc te dá o mapa, mas quem decide é a prática

No vídeo abaixo eu abro a documentação do próprio projeto na parte de memória, que achei bem completa, e recomendo a leitura ANTES de sair mexendo na configuração

Dentro dela eu separo as duas partes que considero principais pra quem tá começando: a busca vetorial na memória e a descarga de memória antes da compactação

O motivo de combinar as duas é bem prático: a busca resolve encontrar informação quando o arquivo de memória cresce, e a descarga resolve não perder o que já foi dito

Porque a compactação automática da conversa mantém só o que o modelo julga importante, e aí some coisa

Outra coisa que eu mostro na VPS: depois da instalação você tem dois diretórios principais, um oculto com as configurações e um visível que funciona como área de trabalho, onde a maioria dos arquivos é criada

Eu listo os arquivos incluindo ocultos só pra deixar os dois lado a lado, porque é isso que faz o resto fazer sentido

No diretório de trabalho eu passo arquivo por arquivo de Markdown explicando a função de cada um: instruções de comportamento do agente, personalidade e tom, informações sobre o usuário, nome e identidade do agente, ferramentas conectadas, checklist de rotinas e memória de longo prazo

E todos eles podem ser editados na mão ou alterados pedindo pro próprio agente, por prompt

Fiz dois testes ao vivo

No primeiro pedi pro agente anotar um nome na memória, ele confirmou, fui no servidor procurar e a informação estava gravada no arquivo de identidade

No segundo pedi pra lembrar de uma preferência de linguagem nos meus projetos, e ela caiu primeiro no arquivo de informações do usuário, não no de memória

Só depois que eu explicitei que queria NA memória o dado apareceu também lá

Detalhe que ninguém comenta: logo depois da instalação eu abri o arquivo de configuração e o conteúdo estava bem cru, praticamente só o que foi definido no processo inicial

Então não estranha se o seu estiver vazio, é assim mesmo

Com a descarga ativada, os arquivos extras de memória ficam em uma pasta e são nomeados pela data da compactação

E tem um ponto que vale seu cuidado: toda essa memória vive em arquivos, então ela some junto com o servidor

Eu versiono esses arquivos Markdown em um repositório de tempos em tempos, inclusive pedindo pro próprio agente fazer isso 🙂

Ah, e ainda dá pra configurar um caminho de reserva e um modo híbrido, que combina busca semântica com palavras-chave, o que amplia bastante as opções na hora de procurar dentro da memória

Por isso a leitura da doc de Tools/Skills e da configuração do Gateway anda junto com o teste: o texto te mostra o que existe, o teste te mostra onde a informação realmente caiu

Travou na leitura ou na instalação? Onde a própria doc manda procurar

Boa notícia: quase toda seção grande tem troubleshooting próprio

Então o segredo é não sair pesquisando no Google antes de olhar a página certa:

• Gateway não sobe ou não responde: https://docs.openclaw.ai/gateway/troubleshooting, e antes disso rode openclaw gateway status pra ver se ele está de pé na porta 18789
• Canal não pareia (Telegram, WhatsApp e afins): https://docs.openclaw.ai/channels/pairing pro passo de pareamento e https://docs.openclaw.ai/channels/troubleshooting quando o pareamento falha
• Agendamento não dispara: https://docs.openclaw.ai/automation/troubleshooting
• Node não conecta: https://docs.openclaw.ai/nodes/troubleshooting

E tem o comando que resolve metade do drama antes de você abrir issue:

openclaw doctor
openclaw doctor --fix

Prevenção (a parte que economiza sua noite)

Rode a verificação pós-instalação antes de seguir pra qualquer configuração

Gateway confirmado no ar, dashboard abrindo, aí sim você avança

E quando for pedir ajuda no Discord ou abrir uma issue, a doc pede três coisas: a mensagem de erro exata, a saída do openclaw doctor e as últimas 50 linhas de log

Leva esses três e a chance de alguém te responder rápido sobe muito

Já me ferrei uma vez chegando em fórum com "não funciona" e nada mais, e adivinha o que aconteceu? Nada haha

Conclusão

A documentação do OpenClaw parece intimidadora porque ela cobre o projeto inteiro, e não o seu primeiro dia

A rota mínima é curta: hubs pra ver o mapa, Getting started pra entender a promessa dos 5 minutos e os requisitos, visão geral do onboarding, wizard, seção de instalação, e fechar com openclaw gateway status e openclaw dashboard

Depois disso o critério de leitura muda: você lê o que resolve o SEU próximo passo, não a doc inteira

Quer o agente no Telegram? Channels

Quer rotina automática? Automation

Quer ampliar o que ele faz? Tools e skills

Quer entender o desenho? Concepts

E deixa o FAQ da área de ajuda salvo como parada rápida, porque muita dúvida de iniciante morre ali mesmo

Agora abre o Getting started, sobe o Gateway e só então volta pro mapa de seções

Até o próximo post! 😀