◆ Agentes Locais — Agentes que agem na sua máquina, sem nuvem · 24 € · ou todos os kits 49 € →

#Instalar OpenClaw: script oficial ou Docker?

O projeto documenta duas formas de instalar o OpenClaw. A primeira utiliza um script que instala o comando openclaw diretamente no sistema. A segunda executa o gateway (o processo central que conecta seus serviços de mensagens ao modelo) dentro de um contêiner Docker. Ambas resultam no mesmo software e no mesmo assistente de configuração, chamado onboarding.

Script oficial: O caminho mais direto em uma máquina pessoal com macOS, Linux ou WSL2. O script instala o comando openclaw e o Node.js, se necessário; depois, a configuração inicial registra o gateway como serviço da sua sessão.
Docker Compose: O gateway roda em um contêiner, e nada além do Docker é instalado no host. É uma opção prática em um VPS ou para poder remover tudo de uma só vez. A documentação apresenta essa opção como facultativa.
O que Docker não muda: O contêiner mantém acesso completo à pasta de configuração e ao espaço de trabalho montados a partir do sistema hospedeiro, bem como à rede. É uma barreira útil, não um cofre.

Terminal — o método via script, para referência

# Télécharger et exécuter l'installateur officiel
curl -fsSL https://openclaw.ai/install.sh | bash

# Lancer l'onboarding et installer le service
openclaw onboard --install-daemon

O restante deste guia segue o método com Docker, com um lembrete do comando equivalente para o método via script nas etapas de atualização e desinstalação. Se você ainda tiver dúvidas sobre a utilidade da ferramenta em si, nossa página “OpenClaw: o que é” trata dessa questão; aqui, vamos instalar.

Apenas fontes oficiais

O projeto mudou de nome duas vezes (Clawdbot, depois Moltbot, depois OpenClaw) e sua popularidade atraiu repositórios falsos, pacotes falsos e "instaladores com um clique" duvidosos. Nunca cole em um terminal um comando de instalação encontrado em um vídeo, fórum ou post de blog, incluindo este, sem compará-lo com a documentação. Três endereços servem de referência: openclaw.ai para o script, github.com/openclaw/openclaw para o código, docs.openclaw.ai para a documentação. E nada impede que você leia um script antes de executá-lo: baixe-o para um arquivo, abra-o e depois execute-o.

#Pré-requisitos

O kit Agentes Locais

Agentes que agem na sua máquina: Cline agêntico, MCP, n8n + Ollama, automações locais.

Espaço online vitalício
PDF + arquivos
Atualizações vitalícias

O kit Agentes Locais →ou todos os kits vitalícios — 49 € →

O próprio gateway consome poucos recursos: ele encaminha mensagens e chama um modelo. Os requisitos abaixo dizem respeito principalmente ao Docker e à construção da imagem.

Docker e Compose v2: Docker Desktop no macOS e Windows (com WSL2) ou Docker Engine acompanhado do plugin Compose no Linux. O comando é docker compose, com um espaço: o antigo binário docker-compose na versão 1 não é compatível.
Git: Para clonar o repositório oficial, que contém o Dockerfile, o arquivo docker-compose.yml e o script de instalação.
Memória: A documentação exige pelo menos 2 GB de RAM para construir a imagem. Em um host com 1 GB, a compilação pode ser interrompida pelo sistema devido à falta de memória (código de saída 137). A imagem pré-construída, apresentada abaixo, evita esse passo.
Disco: Espaço para imagens Docker e logs. A documentação não fornece um valor: monitore o espaço com docker system df.
Um modelo: Uma chave de API de um fornecedor online, com limite de gasto, ou um modelo local. A conexão de um modelo local é um tema separado, que este guia não aborda.
Em um VPS: Acesso SSH por chave e o firewall do provedor configurado para permitir apenas conexões SSH de entrada. Nenhuma outra porta precisa ser aberta, como veremos.

Terminal — verificar as ferramentas

docker --version
docker compose version
git --version

No Windows, trabalhe em um terminal WSL2: o script de instalação é um script de shell, e a documentação já direciona os usuários do Windows ao WSL2. Independentemente do computador, evite usar uma máquina que contenha seus documentos pessoais e senhas: um agente capaz de executar comandos deve rodar em uma máquina dedicada, em uma máquina virtual ou em um servidor alugado.

#Instalar o OpenClaw com Docker Compose, passo a passo

A instalação via Docker baseia-se em um script fornecido no repositório. Ele executa, em sequência, a preparação da imagem, o onboarding e a inicialização do gateway. As quatro etapas abaixo seguem essa ordem.

#1. Clonar o repositório oficial

Terminal

git clone https://github.com/openclaw/openclaw.git
cd openclaw

Verifique o endereço caractere por caractere: é a organização openclaw no GitHub, não um repositório com nome semelhante. Na documentação que conhecemos, o script de instalação do Docker se chama docker-setup.sh e fica na raiz do repositório. O projeto reorganiza frequentemente seus arquivos, e versões recentes podem colocá-lo em scripts/docker/: o comando a seguir mostra qual caminho existe no seu ambiente.

Terminal — localizar o script

ls docker-setup.sh scripts/docker/setup.sh 2>/dev/null

#2. Escolher entre imagem pré-construída e construção local

Por padrão, o script constrói a imagem na sua máquina a partir do Dockerfile e a nomeia openclaw:local. É a maneira mais transparente, pois você compila o código que acabou de clonar, mas exige memória e tempo de processamento. A alternativa é baixar a imagem publicada pelo projeto no registro de contêineres do GitHub, definindo a variável OPENCLAW_IMAGE antes de executar o script.

Terminal — opção: usar a imagem publicada

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

A etiqueta latest segue a versão mais recente publicada. Em um servidor, é melhor substituí-la por um número de versão preciso, obtido na página de releases do repositório: assim, você decide quando atualizar e sabe para qual versão voltar em caso de problemas.

#3. Executar o script de instalação

Terminal

./docker-setup.sh

De acordo com a documentação, este script realiza cinco coisas sequencialmente:

Imagem: Ele constrói a imagem localmente ou a baixa se OPENCLAW_IMAGE for definido.
Onboarding: Ele inicia o assistente de configuração em um contêiner temporário.
Token: Ele gera o token de acesso do gateway e o grava em um arquivo .env na raiz do repositório.
Início: Ele inicia o gateway com Docker Compose, com o nome de serviço openclaw-gateway.
Dados: Ele coloca a configuração e o espaço de trabalho na máquina hospedeira, em ~/.openclaw e ~/.openclaw/workspace. Esses diretórios sobrevivem à remoção do contêiner.

#4. Responder às perguntas do onboarding

O assistente faz perguntas sobre o modelo, os serviços de mensagens e o gateway. Para esta última parte, o script exibe as respostas esperadas em um contêiner. Elas diferem das de uma instalação convencional, e a primeira merece uma explicação.

Gateway bind: lan: Dentro do contêiner, o gateway deve escutar na interface da rede Docker; caso contrário, a porta publicada no host não consegue alcançá-lo. Esse ajuste não determina o que fica visível de fora: isso é definido no host; veja a seção VPS.
Autenticação de gateway: token: O acesso à interface e à API do gateway exige um token.
Gateway token: Use o token que o script acabou de exibir, para que ele corresponda ao arquivo .env.
Tailscale exposure : Off: Sem exposição automática. A decisão sobre acesso remoto fica para depois, com plena compreensão das implicações.
Install Gateway daemon : No: Nessa configuração, é o Docker Compose que reinicia o contêiner, não um serviço do sistema.

Para o modelo, forneça uma chave de API com orçamento limitado em vez da sua chave principal. Quanto aos serviços de mensagens, você pode pular essa etapa e voltar a ela depois de verificar o gateway. Lembre-se da regra de conversão: qualquer comando da documentação que comece com openclaw deve ser executado aqui com o prefixo docker compose run --rm openclaw-cli.

Terminal — adicionar um serviço de mensagens posteriormente

# WhatsApp : affiche un QR code à scanner depuis le téléphone
docker compose run --rm openclaw-cli channels login

# Telegram : avec le jeton du bot créé auprès de BotFather
docker compose run --rm openclaw-cli channels add --channel telegram --token "<jeton-du-bot>"

#Verificar se o gateway está em execução

Antes de conectar qualquer outra coisa, certifique-se de que o contêiner esteja em execução e que seus logs não indiquem erros.

Terminal

docker compose ps
docker compose logs -f openclaw-gateway

Abra em seguida a interface de controle no navegador da mesma máquina, e cole o token em suas configurações. Se você perdeu o link, o comando dashboard o exibe novamente sem tentar abrir um navegador.

Interface de controle (a partir da própria máquina)

http://127.0.0.1:18789/

Terminal — exibir novamente o link de acesso

docker compose run --rm openclaw-cli dashboard --no-open

Duas verificações integradas complementam a checagem. A primeira diagnostica a instalação e a configuração; a segunda revisa as configurações perigosas. Execute-as novamente após cada alteração de configuração.

Terminal — diagnóstico e auditoria

docker compose run --rm openclaw-cli doctor
docker compose run --rm openclaw-cli security audit --deep

Último passo: proteja o arquivo .env. Ele contém o token do gateway, e quem possuir esse token controla o agente e, portanto, tudo a que o agente tem acesso. O comando chmod 600 .env restringe a leitura à sua conta. Não copie esse arquivo para um repositório Git nem o inclua em uma captura de tela.

#OpenClaw em um VPS: não expor o gateway

Em um PC conectado à rede de um roteador doméstico, uma porta publicada pelo Docker permanece na rede local. Em um VPS, a máquina possui um endereço público: uma porta publicada sem especificar o endereço fica acessível a toda a Internet. No início de 2026, pesquisadores identificaram milhares de gateways OpenClaw acessíveis dessa forma. O token protege o acesso, mas uma única falha basta para contornar essa proteção: a vulnerabilidade CVE-2026-25253, corrigida no final de janeiro de 2026, permitia justamente roubar esse token. A postura adequada consiste em não expor absolutamente nada.

Docker contorna o UFW

O Docker escreve suas próprias regras de firewall. Uma porta publicada por um contêiner continua acessível de fora mesmo quando o UFW exibe uma política de bloqueio. Por esse motivo, a documentação de segurança do OpenClaw remete à cadeia DOCKER-USER. Não confie apenas no UFW: verifique quais serviços realmente estão escutando.

Terminal (no VPS) — em qual endereço a porta está publicada?

docker compose port openclaw-gateway 18789
ss -tlnp | grep 18789

Se a resposta começar com 0.0.0.0, a porta está publicada em todas as interfaces. Três camadas de proteção se somam, da mais externa até a mais próxima do contêiner.

Firewall do provedor: A filtragem oferecida no console do provedor de hospedagem atua antes da máquina, ou seja, antes do Docker. Permita apenas conexões SSH de entrada.
Publicação em 127.0.0.1: Peça ao Docker para publicar a porta apenas no endereço local do host, usando o arquivo abaixo.
Acesso por túnel: Acesse a interface de controle por meio de um túnel SSH ou uma VPN, nunca por um endereço público.

docker-compose.override.yml — exemplo para adaptar

services:
  openclaw-gateway:
    ports: !override
      - "127.0.0.1:18789:18789"
      - "127.0.0.1:18790:18790"

Este arquivo é um exemplo fornecido por nós, não um trecho da documentação do OpenClaw: compare o nome do serviço e a lista de portas com o docker-compose.yml da sua versão antes de usá-lo. A tag !override substitui a lista de portas em vez de acrescentar portas a ela; exige Docker Compose 2.24.4 ou uma versão mais recente. Coloque o arquivo ao lado de docker-compose.yml, recrie o contêiner com docker compose up -d openclaw-gateway e execute novamente a verificação: ela deve agora retornar 127.0.0.1:18789.

Terminal (no seu computador) — túnel SSH para o gateway

ssh -N -L 18789:127.0.0.1:18789 utilisateur@adresse-du-vps

Enquanto esse túnel estiver aberto, o endereço http://127.0.0.1:18789/ do seu computador leva ao gateway do servidor. Os serviços de mensagens, por sua vez, não precisam de nenhuma porta de entrada no modo de funcionamento habitual: para WhatsApp, Telegram ou Discord, é o gateway que abre conexões de saída. Portanto, não há motivo para publicar a interface de controle por meio de um nome de domínio. O raciocínio é o mesmo que para um servidor de modelos, detalhado em nosso guia sobre como proteger um servidor Ollama.

#Atualizar OpenClaw

O projeto publica versões com frequência, e algumas corrigem falhas. Deixar uma instalação inalterada por meses é um risco, não uma economia de tempo. Com Docker, atualizar significa apenas substituir a imagem e recriar o contêiner; seus dados, no diretório ~/.openclaw, não mudam.

01
Fazer backup da pasta de dados
Arquive ~/.openclaw antes de qualquer atualização. Uma nova versão pode migrar a configuração, e o retorno ao estado anterior é confiável apenas com uma cópia do estado anterior.
02
Baixar a nova versão
Atualize o repositório com git pull para obter o Dockerfile e o arquivo Compose atuais. Em seguida, reconstrua a imagem local ou baixe a imagem publicada, conforme a escolha feita na instalação.
03
Recriar o container
Reinicie o serviço openclaw-gateway. O Docker Compose substitui o container assim que detectar uma imagem diferente.
04
Verificar
Execute doctor, leia as últimas linhas dos logs e envie uma mensagem de teste pelo seu aplicativo de mensagens.

Terminal — 1. backup

tar czf openclaw-sauvegarde-$(date +%F).tar.gz -C ~ .openclaw

Terminal — 2 e 3, com imagem construída localmente

cd openclaw
git pull
docker build -t openclaw:local -f Dockerfile .
docker compose up -d openclaw-gateway

Terminal — 2 e 3, com a imagem publicada

cd openclaw
git pull
docker compose pull openclaw-gateway
docker compose up -d openclaw-gateway

Terminal — 4. verificação

docker compose run --rm openclaw-cli doctor
docker compose logs --tail 50 openclaw-gateway

A variante com imagem publicada pressupõe que a linha OPENCLAW_IMAGE esteja no arquivo .env, o que o script faz quando a variável estava definida no momento da instalação. Se você fixou um número de versão, altere essa linha primeiro. Para voltar atrás, recoloque o número antigo, recrie o contêiner e, se a configuração tiver sido migrada nesse intervalo, restaure o backup.

→

Ler as notas de versão antes, não depois

A página de releases do repositório informa sobre mudanças incompatíveis e correções de segurança. Trinta segundos de leitura antes de um git pull evitam descobrir uma configuração renomeada nos logs de um assistente que já não responde.

Com o método de instalação por script, a atualização é feita pelo comando integrado, seguida do mesmo diagnóstico.

Terminal — instalação por script

openclaw update
openclaw doctor

#Desinstalar o OpenClaw corretamente

Uma desinstalação completa remove três coisas: os contêineres e as imagens, os dados no disco e os acessos que você confiou ao assistente. A terceira é aquela que esquecemos.

Terminal — 1. contêineres e imagens

cd openclaw
docker compose down

# Supprimer l'image utilisée (l'une ou l'autre selon votre cas)
docker image rm openclaw:local
docker image rm ghcr.io/openclaw/openclaw:latest

# Vérifier qu'il ne reste ni conteneur ni volume
docker ps -a --filter name=openclaw
docker volume ls --filter name=openclaw

O diretório ~/.openclaw contém a configuração, as chaves de API, as sessões de mensagens e a memória do assistente. Sua exclusão é irreversível: mantenha uma cópia de segurança se achar que voltará um dia, ou se quiser reler o que o assistente anotou. O repositório clonado contém, por sua vez, o arquivo .env e seu token.

Terminal — 2. dados (irreversível)

rm -rf ~/.openclaw

# Le dépôt cloné, avec son fichier .env
cd ..
rm -rf openclaw

Chaves de API: Revogue com o fornecedor do modelo a chave confiada a OpenClaw. Excluir o arquivo local não anula a chave.
Bot do Telegram ou Discord: Revogue o token do bot ou exclua o bot pela ferramenta do serviço (BotFather para Telegram, portal de desenvolvedores para Discord).
WhatsApp: No aplicativo, abra a lista de dispositivos conectados e desconecte aquele que corresponde ao gateway.
Acesso à rede: Remova a regra de firewall, o túnel ou a máquina da VPN que foram criados para essa ocasião. Se o VPS foi alugado exclusivamente para esse uso, cancele a contratação do servidor.

Com o método de instalação por script, o comando integrado de desinstalação remove o serviço e oferece a opção de excluir os dados; depois, resta remover o próprio comando.

Terminal — instalação por script

openclaw uninstall
npm rm -g openclaw

#Solução de problemas: os obstáculos mais comuns

« unauthorized » ou « pairing required (1008) »: O navegador ainda não foi aprovado pelo gateway. Exiba novamente o link de acesso e, em seguida, liste e aprove o dispositivo com os comandos abaixo. Esse caso é comum em Docker e por trás de um túnel, pois a conexão não vem do endereço local do contêiner.
Compilação interrompida, código 137: O sistema matou a compilação devido à falta de memória. Mude para a imagem publicada com OPENCLAW_IMAGE ou use uma máquina com pelo menos 2 GB de RAM.
Permissão negada em /home/node/.openclaw: A imagem é executada com o usuário node, de identificador 1000. Os diretórios montados a partir do host devem pertencer a esse usuário: sudo chown -R 1000:1000 ~/.openclaw.
Porta 18789 já em uso: Outro serviço ou uma instalação antiga do OpenClaw está ocupando a porta. Interrompa o serviço ou altere OPENCLAW_GATEWAY_PORT no arquivo .env antes de recriar o contêiner.
docker compose introuvable: Você tem o antigo binário docker-compose ou não tem o plugin Compose. Instale o plugin Compose v2 da sua distribuição.
Modelo local inacessível: Em um contêiner, localhost refere-se ao contêiner, não ao host. Portanto, uma instância do Ollama que escuta em http://localhost:11434 no host não fica acessível dessa forma a partir do gateway. Esse ajuste faz parte da conexão do modelo e está fora do escopo deste guia.

Terminal — aprovar o navegador

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

Quando nenhuma dessas situações se aplica, os logs do serviço continuam sendo o melhor ponto de partida, seguidos do comando doctor. Antes de procurar uma solução em outro lugar, verifique a data das respostas que você encontra: as que mencionam Clawdbot ou Moltbot descrevem comandos antigos.

#Fontes oficiais para manter à mão

Este guia não se baseia em nenhum teste interno: não contém duração, medição nem comparação numérica. Os comandos seguem a documentação do projeto, que muda de versão para versão: nome do script, variáveis, etapas do onboarding. Em caso de divergência entre esta página e a documentação, prevalece a documentação.

Documentação: instalação com Docker

https://docs.openclaw.ai/install/docker

Documentação: atualização

https://docs.openclaw.ai/install/updating

Documentação: desinstalação

https://docs.openclaw.ai/install/uninstall

Documentação: segurança do gateway

https://docs.openclaw.ai/gateway/security

Repositório oficial e notas de versão

https://github.com/openclaw/openclaw/releases

#Para se aprofundar

A instalação é apenas a primeira metade do trabalho: é preciso configurar, monitorar e comparar um agente. Esses guias do site aprofundam os conceitos utilizados aqui.

OpenClaw: o que é e vale a pena instalar?: O funcionamento do gateway, os usos e os riscos, para decidir antes de instalar. https://quelllm.fr/guide/openclaw-c-est-quoi
Proteger um servidor Ollama: Firewall, escuta local e acesso remoto: a mesma lógica de exposição mínima, aplicada ao servidor de modelos. https://quelllm.fr/guide/securiser-serveur-ollama
Implantar um LLM com Docker Compose em produção: Arquivos Compose, reinício, logs e backups para uma pilha que roda continuamente. https://quelllm.fr/guide/deployer-llm-docker-compose-production
Instalar Ollama com Docker: Para rodar o servidor de modelos em um contêiner, na mesma máquina ou em outra. https://quelllm.fr/guide/ollama-docker-installation-guide
Agent Zero com Ollama no Docker: Outro agente auto-hospedado entregue em contêiner, para comparar as abordagens. https://quelllm.fr/guide/agent-zero-ollama-docker

Este guia ajudou você?

Um comentário, um erro ou uma observação? Avise-nos; isso ajuda a melhorar o guia para todos.

Os kits QuelLLMO guia de referência por uso

Agentes Locais Copiloto Local IA local RAG Local IA Empresarial IA Sem Filtros Mac Imagens IA

Todos os kits vitalícios — 49 €