Não consegue instalar o OpenClaw? Eu já caí nestas 7 armadilhas

Atualizado em 08/06/2026: os nomes dos modelos nos exemplos de configuração foram ajustados para as versões disponíveis no momento (claude-sonnet-4-6 para Anthropic e gpt-5 para OpenAI). Os requisitos do Node (v22.14+, com v24 recomendada), a alocação de recursos e os comandos de diagnóstico também foram conferidos novamente em junho de 2026. Consulte sempre docs.openclaw.ai/install como referência final.

O terminal mostra uma mensagem de erro vermelha pela enésima vez. Você só queria experimentar o OpenClaw, mas passou a noite inteira instalando: erro de permissão no npm, contêiner Docker reiniciando sem parar, API key que não funciona de jeito nenhum… A cada problema resolvido, aparecem outros três. Depois de ver uma pilha de pessoas perguntando a mesma coisa nas GitHub Issues, fica claro que a barreira de instalação é bem maior do que parece.

Você segue a documentação oficial passo a passo, mas a ferramenta simplesmente não inicia. O terminal fica cheio de erros intimidadores e não dá nem para saber por onde começar.

A boa notícia é que, depois de passar um fim de semana inteiro testando, eu já caí em todas essas armadilhas. Este guia cobre as sete categorias de problemas mais comuns na instalação do OpenClaw, com etapas claras de diagnóstico e solução para cada uma. Além de mostrar o que fazer, explico por que o erro acontece, para que você saiba em que direção investigar da próxima vez.

Guia econômico para criar seu “camarão”: o ArkClaw deixa os agentes de IA acessíveis de verdade

O OpenClaw, que ficou popular recentemente, é útil, mas sua configuração afasta muita gente. O ArkClaw, da Volcengine da ByteDance, reduz essa barreira ao mínimo. Sem precisar lidar com servidor ou configuração de token, você recebe com um clique um “funcionário de IA” disponível 24 horas, capaz de controlar o navegador, executar scripts e gerenciar o calendário.

O destaque é o preço: a mensalidade custa apenas 9,9 yuans e, com meu código de convite ZLKUK54M (cadastre-se aqui), cai para 8,9 yuans. Se você programa, também pode aderir diretamente ao Coding Plan Pro sem custo adicional.

Problemas com a versão do Node.js (o caso mais comum)

A primeira coisa a conferir ao instalar o OpenClaw é a versão do Node.js. No começo, eu usava o Node 16 que veio com o sistema e recebi vários erros de sintaxe sem explicação aparente.

Primeiro, confira sua versão:

node -v

Se a versão estiver claramente desatualizada, este deve ser o primeiro suspeito. Siga docs.openclaw.ai/install: o mínimo é Node.js v22.14+, e a versão Node.js v24 é recomendada. Versões anteriores podem causar incompatibilidade de sintaxe ou de APIs em tempo de execução.

Os erros típicos de incompatibilidade de versão são assim:

SyntaxError: Unexpected token '?'
TypeError: fetch is not a function

O primeiro costuma aparecer quando o runtime é antigo demais e não aceita recursos como optional chaining. O segundo é comum quando você não atende à versão mínima oficial do Node (v22.14+) ou quando o node usado de fato pelo shell não corresponde ao ambiente esperado, gerando incompatibilidade com APIs integradas como fetch. Ao ver esses erros, quase sempre vale conferir a versão, o PATH e a versão selecionada pelo nvm.

Como resolver? Gerencie as versões com o nvm.

Recomendo bastante o nvm (Node Version Manager), que permite alternar livremente entre versões do Node.js sem afetar outros projetos.

🪟 Usuários do Windows:

Baixe o instalador em nvm-windows. Antes de instalar, remova completamente qualquer Node.js já instalado no sistema para evitar conflitos no PATH.

🐧 Usuários de Linux/macOS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

Depois de instalar o nvm, instale o Node.js 24, que é a versão recomendada oficialmente e atende ao mínimo v22.14+:

nvm install 24
nvm use 24
nvm alias default 24

O último comando define a versão 24 como padrão, inclusive em novos terminais.

Erros de permissão do npm (frequentes em WSL2/Linux)

Os erros de permissão do npm me deram bastante trabalho. Especialmente no WSL2, toda execução de npm install mostrava um erro EACCES.

Primeiro, veja como esse erro costuma aparecer:

EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'
EACCES: permission denied, open 'package.json'

O primeiro ocorre em instalações globais; o segundo geralmente aparece dentro do diretório /mnt/c no WSL2.

❌ Não corra para estas soluções:

• Não use sudo npm install: isso bagunça a propriedade dos arquivos e cria mais problemas depois
• Não use chmod 777: isso abre uma brecha de segurança
• Não use npm config set unsafe-perm true: é apenas um paliativo

✅ Há três soluções corretas; escolha a mais adequada ao seu caso:

Opção A: altere o diretório global do npm (recomendada para todos os usuários Linux)

A ideia é mover o diretório de instalação global do npm para sua pasta home, eliminando o problema de permissão.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Abra um novo terminal e tente instalar novamente com o npm. O erro de permissão deve desaparecer.

Opção B: corrija as permissões do sistema de arquivos do WSL2

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

🔧 O WSL2 tem uma armadilha importante: o modelo de permissões do sistema de arquivos do Windows montado em /mnt/c é diferente do Linux, e o npm frequentemente falha ali.

Edite o arquivo /etc/wsl.conf:

sudo nano /etc/wsl.conf

Adicione estas linhas:

[automount]
options = "metadata,umask=22,fmask=11"

Salve o arquivo e execute no PowerShell do Windows:

wsl.exe --shutdown

Abra o WSL2 novamente. Isso costuma resolver o problema de permissão.

Opção C: trabalhe no diretório home do WSL (a solução mais simples)

Sinceramente, a saída mais tranquila é não desenvolver dentro de /mnt/c. Use um diretório nativo do WSL como ~/projects: a instalação com npm fica muito mais rápida e evita permissões estranhas.

mkdir ~/projects
cd ~/projects
# Instale o OpenClaw aqui

Problemas relacionados ao Docker

A parte do Docker é um pouco confusa, e eu também fiquei travado nela por bastante tempo. Há muitas causas possíveis para uma falha de inicialização do contêiner, então é preciso investigar passo a passo.

Comece diagnosticando o problema:

# Etapa 1: confira o status dos contêineres
docker compose ps

# Etapa 2: consulte os logs
docker compose logs openclaw-gateway

# Etapa 3: filtre as mensagens de erro
docker compose logs openclaw-gateway | grep -i "error"

Essas três etapas ajudam a localizar rapidamente a origem do problema.

Problema A: a verificação de integridade falha e o contêiner reinicia sem parar

Já encontrei esse problema várias vezes. O contêiner inicia, para sozinho depois de alguns segundos e reinicia, repetindo o ciclo.

O log mostra algo parecido com isto:

Health check failed: container unhealthy
Container openclaw-gateway exited with code 137

Quase sempre faltam recursos. O OpenClaw recomenda oficialmente no mínimo 2 vCPUs / 4 GB de RAM, com 4 vCPUs / 8 GB de RAM como configuração recomendada.

Como ajustar os recursos do Docker?

🪟 Windows/Mac: abra Docker Desktop → Settings → Resources e aumente CPU e memória.

🐧 Linux: em geral não é necessária uma configuração separada; o Docker usa todos os recursos do host.

Se sua máquina realmente não tiver recursos suficientes, você pode desativar temporariamente a verificação de integridade. Não é recomendado, mas serve para uma emergência:

# Edite docker-compose.yml
healthcheck:
  disable: true

Problema B: erro de permissão do Docker (somente Linux)

Usuários Linux podem encontrar este erro:

permission denied while trying to connect to the Docker daemon socket

Isso acontece porque seu usuário não pertence ao grupo docker. Para corrigir:

sudo usermod -aG docker $USER
newgrp docker

⚠️ Aviso de segurança: incluir um usuário no grupo docker equivale a conceder permissões de nível root. Em produção ou em um servidor compartilhado, considere usar o Docker rootless.

Problema C: a porta 18789 está em uso

Às vezes, um processo antigo do OpenClaw não foi encerrado corretamente e continua ocupando a porta.

🐧 Diagnóstico no Linux/Mac:

lsof -i :18789

🪟 Diagnóstico no Windows:

netstat -ano | findstr 18789

Depois de encontrar o ID do processo que ocupa a porta, encerre-o de forma normal:

openclaw gateway stop

Ou force o encerramento, substituindo PID pelo valor encontrado:

kill -9 <PID>

Problema D: arquitetura ARM64 (atenção, usuários de Apple Silicon)

Em um Mac com chip M1/M2, pode haver incompatibilidade no caminho do Chromium. É um caso menos comum, mas difícil de resolver quando aparece.

A solução é criar um Dockerfile personalizado que indique o caminho do Chromium para ARM64. Procure nas GitHub Issues do OpenClaw; há configurações completas publicadas por outros usuários.

Problemas na configuração da chave de API

Também tive bastante dificuldade com chaves de API. Eu colocava a key no arquivo de configuração, mas o OpenClaw insistia em dizer que não a encontrava.

Estes são alguns erros comuns:

No API key found for anthropic
Invalid API key format
API key validation failed

Ao encontrar essas mensagens, mantenha a calma e siga a lista de verificação abaixo.

Verificação 1: a variável de ambiente foi configurada corretamente?

Primeiro, confirme se ela realmente entrou em vigor:

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

Se a saída estiver vazia, a variável de ambiente não foi configurada corretamente.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Forma correta de configuração:

# Configuração temporária (válida no terminal atual)
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# Configuração permanente (gravada no arquivo de configuração)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

🔧 Atenção, usuários do WSL2: as variáveis de ambiente definidas no WSL2 não são compartilhadas com o Windows. Não adianta defini-las no Windows e tentar acessá-las no WSL2.

Verificação 2: o arquivo de configuração está correto?

Se você usa o arquivo ~/.openclaw/openclaw.json, ele precisa seguir rigorosamente o formato JSON. Atualmente, a configuração principal e os dados de estado ficam em ~/.openclaw/. Se você ainda usa o diretório antigo ~/.clawdbot/, leia primeiro o artigo sobre o histórico de renomeação do OpenClaw nesta série e só então faça a migração.

Os erros que mais vejo são:

• Espaços ou aspas extras
• Vírgulas ausentes
• Uma vírgula depois do último item

Use este comando para validar o JSON:

cat ~/.openclaw/openclaw.json | jq .

Se o jq mostrar um erro, há algum problema no JSON. Caso não tenha o jq instalado:

# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq

Verificação 3: há algum problema com a própria API key?

Às vezes, o problema não está na configuração: a key pode ter expirado ou ter sido revogada.

• Anthropic Claude: acesse https://console.anthropic.com/settings/keys
• OpenAI GPT: acesse https://platform.openai.com/api-keys

Confira se a key está com status Active e se há algum limite de uso.

Dica: diferenças de configuração entre provedores de API

Para trocar o modelo padrão, especifique-o no arquivo de configuração:

{
  "defaultProvider": "anthropic",
  "anthropic": {
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-sonnet-4-6"
  },
  "openai": {
    "apiKey": "sk-xxxxx",
    "model": "gpt-5"
  }
}

Configuração específica para o ambiente WSL2

Se você usa Windows com WSL2, provavelmente já percebeu que vários tutoriais de Linux não funcionam exatamente da mesma forma. Existem diferenças reais entre o WSL2 e o Linux nativo.

Há três diferenças principais:

1. Modelo de permissões do sistema de arquivos diferente — já abordado na seção sobre permissões do npm
2. Pilha de rede independente — às vezes o localhost não é compartilhado
3. Problemas de integração com o Docker Desktop — o compartilhamento do Docker entre Windows e WSL2 pode falhar

Configuração completa de /etc/wsl.conf para WSL2

Recomendo configurar o arquivo por completo para evitar vários desses problemas:

sudo nano /etc/wsl.conf

Insira o seguinte conteúdo:

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[interop]
enabled = true
appendWindowsPath = true

[network]
generateResolvConf = true

Depois, reinicie o WSL2:

# Execute no Windows PowerShell
wsl.exe --shutdown

Configuração da integração do Docker Desktop for Windows

Se você usa o Docker Desktop, habilite a integração com o WSL2 nas configurações:

1. Abra o Docker Desktop
2. Acesse Settings → Resources → WSL Integration
3. Marque a distribuição WSL2 utilizada, como Ubuntu
4. Clique em Apply & Restart

Otimização de desempenho: não atravesse sistemas de arquivos

Essa foi a armadilha que mais me atrapalhou. No início, deixei o código na unidade D: do Windows, acessada como /mnt/d no WSL2, e o npm install ficou extremamente lento.

Operações entre sistemas de arquivos, acessando arquivos do Windows a partir do WSL2, podem perder de 50% a 90% do desempenho. Não é exagero.

Faça assim:

# Trabalhe no diretório home do WSL2
cd ~
mkdir projects
cd projects
git clone https://github.com/openclaw/openclaw.git

Faça tudo no sistema de arquivos nativo do WSL2, em /home/username, para obter muito mais velocidade.

Limites de recursos (opcional)

Se seu computador tiver pouca memória, você pode limitar o uso de recursos do WSL2. Crie .wslconfig no diretório do usuário do Windows:

# C:\Users\seu-nome-de-usuario\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB

Mas o OpenClaw já exige muitos recursos, então limites muito baixos podem impedir sua execução.

Timeout e dependências na instalação de skills

Também encontrei alguns timeouts ao instalar skills, especialmente na primeira instalação, quando o processo parecia travado por muito tempo.

Comece identificando a origem:

openclaw skill check <skill-name>

O comando mostra o estado da skill e detalhes do erro.

Os logs do Gateway também oferecem pistas:

docker compose logs openclaw-gateway | grep -i "skill"

Há alguns problemas de dependência comuns:

Problema A: dependência binária ausente

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Algumas skills precisam de dependências específicas do sistema, como o ambiente Go. Sem elas, a skill não carrega.

Se o log indicar uma dependência ausente, instale-a conforme a mensagem:

# Por exemplo, se faltar Go
sudo apt install golang-go

# Ou dependências do Python
sudo apt install python3-dev

Problema B: timeout de rede

Este é o caso mais comum. Na primeira instalação de uma skill, o OpenClaw precisa baixar várias dependências; com uma conexão ruim, o processo expira facilmente.

O progresso fica parado e aparecem mensagens como timeout ou connection refused no log.

A solução é simples: tente novamente.

openclaw skill install <skill-name>

Se você estiver na China, pode configurar um mirror do npm para acelerar o processo:

npm config set registry https://registry.npmmirror.com

Também é possível trocar o mirror do Docker por um servidor na China; há muitos tutoriais sobre isso, então não vou detalhar aqui.

Problema C: configuração incompatível do sistema operacional

Algumas skills são otimizadas para sistemas específicos. Se uma delas foi testada apenas no Ubuntu 22.04 e você usa outra distribuição, podem surgir problemas.

Nesse caso, procure nas GitHub Issues do OpenClaw por relatos semelhantes. Normalmente há uma solução alternativa.

Dica:

Skills com dependências em Go podem levar de 5 a 10 minutos na primeira instalação. Se o log continua exibindo mensagens, o processo está funcionando. Não pressione Ctrl+C cedo demais.

Processo sistemático de diagnóstico

Depois de tantos problemas específicos, aqui está um processo sistemático para quando você não souber por onde começar.

Comandos de diagnóstico integrados ao OpenClaw:

# Confira o status do serviço
openclaw status

# Verificação de integridade
openclaw health

# Diagnóstico completo (recomendado)
openclaw doctor

O comando openclaw doctor é especialmente útil: ele confere automaticamente a versão do Node.js, o estado do Docker, a configuração das chaves de API, as portas em uso e vários outros problemas comuns, gerando um relatório de diagnóstico.

Dicas para analisar logs:

Não se assuste com a quantidade de mensagens. Concentre-se nestes pontos:

• Mensagens de nível ERROR — filtre com grep -i "error"
• O primeiro erro — os posteriores normalmente são efeitos em cadeia
• Stack trace — ajuda a localizar a linha exata do código onde surgiu o problema

Quando abrir uma GitHub Issue?

Se você seguiu todo o processo acima e ainda não resolveu, talvez tenha encontrado um bug real.

Antes de abrir a Issue, reúna estas informações:

• Sistema operacional e versão (Windows 11 + WSL2 Ubuntu 22.04 / macOS 14 / Ubuntu 22.04)
• Versão do Node.js (node -v)
• Versão do OpenClaw (openclaw --version)
• Log de erro completo, formatado em bloco de código
• Etapas para reproduzir o problema

Quanto mais detalhes você fornecer, mais fácil será para os mantenedores localizar a causa.

Conclusão

Depois de tudo isso, vale resumir as principais soluções para as sete categorias de problemas:

1. Versão do Node.js — use o nvm para instalar o Node 24, ou pelo menos v22.14+, de acordo com a exigência oficial
2. Permissões do npm — mude o diretório global para a home ou trabalhe diretamente em um diretório nativo do WSL
3. Problemas do Docker — consulte primeiro os logs; na maioria dos casos faltam recursos ou há conflito de porta
4. Chaves de API — confira as variáveis de ambiente, o formato JSON e a validade da key
5. Configuração do WSL2 — ajuste o wsl.conf e evite operações entre sistemas de arquivos
6. Instalação de skills — tente novamente em caso de timeout e instale as dependências ausentes
7. Diagnóstico sistemático — use openclaw doctor e verifique os itens em ordem

Instalar o OpenClaw realmente dá trabalho, mas, depois de passar por essas armadilhas uma vez, fica muito mais fácil evitá-las. O mais importante é desenvolver um método de diagnóstico: não entre em pânico ao ver um erro. Primeiro identifique em qual etapa ele surgiu e aplique a solução adequada.

Guarde esta lista para consultar rapidamente na próxima vez. Se ela poupou seu tempo, compartilhe com outras pessoas que também estão tentando configurar o OpenClaw.

Encontrou um problema que não aparece no artigo? Deixe um comentário; continuarei atualizando este guia.