Erros comuns de instalação do OpenClaw e como corrigi-los

Guia de solução de problemas de instalação do OpenClaw

Uma postagem recente no r/openclaw aborda erros recorrentes de instalação e execução da ferramenta OpenClaw, fornecendo comandos e correções específicas.

Problemas principais e soluções

"instalado, mas o openclaw não é encontrado"

Isso ocorre quando o diretório bin global do npm não está no seu PATH. O binário existe, mas não pode ser encontrado.

• Execute npm prefix -g para encontrar seu prefixo global.
• Adicione <prefix>/bin ao seu $PATH no .bashrc ou .zshrc.
• Recarregue seu shell, então openclaw --version deve funcionar.

"EACCES: permissão negada" na instalação

Este é um problema de permissões com o diretório global padrão do npm, geralmente de propriedade do root.

• Não use sudo.
• Configure um prefixo de propriedade do usuário em vez disso:

  mkdir -p ~/.npm-global
  npm config set prefix '~/.npm-global'
  export PATH="$HOME/.npm-global/bin:$PATH"

• Adicione a exportação à configuração do seu shell e execute novamente a instalação sem sudo.

Falhas silenciosas do Node.js antigo

O OpenClaw requer Node.js 22+. Versões mais antigas podem instalar sem erro, mas produzem um binário que falha durante a execução.

• Sempre verifique node --version primeiro.

"ioctl inadequado para o dispositivo"

Este é um problema de TTY, comum em contêineres Docker ou ambientes de CI sem um terminal real.

• Execute openclaw onboard --non-interactive --accept-risk para pular o assistente interativo.

Plugin do Telegram travado como "não disponível"

Se uma instalação anterior com problemas deixou o plugin do Telegram em um estado parcialmente configurado, ele pode ficar travado.

• Execute openclaw doctor --fix para limpar o estado.

Nota sobre "pareamento de conexão do gateway necessário"

Esta mensagem não é um erro de instalação. Ela se relaciona à política de DM, onde o OpenClaw requer pareamento manual antes de responder a DMs por padrão. Consulte a documentação do OpenClaw sobre configuração de canal.