A apresentação do OpenClaw com Service Unavailable não identifica uma única falha. No tópico da IceWhale Community de fevereiro de 2026, a resolução de problemas revelou, em sequência, três camadas diferentes: um token de gateway obrigatório, permissões insuficientes para inspecionar o Docker a partir da conta de anfitrião do ZimaOS e, por fim, um contentor OpenClaw que nunca tinha concluído a sua configuração inicial.
O tópico é especialmente útil porque algumas sugestões intermédias acabaram por se revelar erradas para a imagem empacotada Big-Bear. Adicionar uma GATEWAY_MODE a variável de ambiente não resolveu o ciclo de reinícios, e acrescentar --gateway.mode=local ao comando errado produziu um opção desconhecida erro. A documentação atual do OpenClaw confirma que gateway.mode=local faz parte da configuração persistente do OpenClaw e que as implementações Docker devem executar o processo de integração ou configuração para criar essa configuração.
Verifique primeiro se o contentor do OpenClaw está realmente em execução
A publicação original mostrava a aplicação OpenClaw a indicar que não estava a funcionar corretamente e a apresentar uma dica sobre OPENCLAW_GATEWAY_TOKEN.
Antes de alterar as definições da aplicação, inspecione o estado do contentor a partir do anfitrião ZimaOS ou CasaOS:
docker ps -a | grep openclawSe o contentor estiver a reiniciar ou tiver sido terminado, leia os respetivos registos:
docker logs big-bear-openclaw --tail 100O nome exato do contentor pode variar. Utilize docker ps -a para identificar o nome real, em vez de assumir que é sempre big-bear-openclaw.
Gerar e armazenar OPENCLAW_GATEWAY_TOKEN
A primeira sugestão da comunidade foi gerar um token de gateway aleatório forte:
openssl rand -hex 32Se o OpenSSL não estiver disponível, o tópico sugeria uma alternativa local para gerar bytes aleatórios:
head -c 32 /dev/urandom | xxd -p -c 32A documentação oficial atual do OpenClaw para Docker também utiliza OPENCLAW_GATEWAY_TOKEN para a autenticação do gateway. O script de configuração padrão gera um token e grava-o no .env automaticamente o ficheiro. Numa aplicação CasaOS empacotada manualmente, introduza o valor gerado no campo da variável de ambiente esperado por essa imagem.
Trate este token como um segredo. Não o cole num fórum público, numa captura de ecrã, num pedido de suporte ou num repositório.
Um erro de permissões do Docker não é um erro de permissões do OpenClaw
Depois de adicionar um token, o autor original deparou-se com:
permissão negada ao tentar ligar-se ao socket do daemon do Docker
/var/run/docker.sock: ligação: permissão negada
A recomendação da comunidade foi elevar temporariamente os privilégios antes de executar comandos administrativos do Docker:
sudo -i
docker psUtilize privilégios de root apenas para os comandos que deles necessitam realmente. Não reduza a segurança de /var/run/docker.sock permissões nem torne o socket do Docker acessível a todos apenas para eliminar o erro. O acesso ao Docker concede efetivamente controlo administrativo sobre o anfitrião.
O verdadeiro erro do OpenClaw era «Missing config»
Quando foi possível aceder aos registos do Docker, surgiu a mensagem importante:
Configuração em falta. Execute `openclaw setup` ou defina gateway.mode=local
Isto foi mais útil do que a página genérica «Service Unavailable». A documentação atual do gateway do OpenClaw confirma que o gateway se recusa a iniciar normalmente a menos que a sua configuração contenha:
gateway.mode = localO OpenClaw atual também indica que qualquer uma das opções configuração do OpenClaw ou openclaw onboard --mode local grava o modo de gateway local na configuração persistente.
Porque é que GATEWAY_MODE=local não corrigiu esta imagem
Uma resposta intermédia da comunidade sugeriu acrescentar:
GATEWAY_MODE=localO utilizador tentou fazê-lo, mas o ciclo de reinício continuou. É importante preservar esta correção: a documentação oficial atual do OpenClaw não define uma GATEWAY_MODE variável de ambiente como substituição da definição persistente gateway.mode utilizada por este fluxo de trabalho.
Não converta todas as chaves de configuração OpenClaw com pontos em variáveis de ambiente inventadas em maiúsculas. Utilize o método de configuração documentado para a imagem OpenClaw ou o modelo de implementação exatos.
Porque é que --gateway.mode=local produziu «Unknown option»
Uma tentativa posterior da comunidade acrescentou:
--gateway.mode=localao comando do contentor do CasaOS. A imagem devolveu então:
opção desconhecida '--gateway.mode'A discussão identificou corretamente o motivo: o CasaOS estava a acrescentar a opção a uma camada de comando que não a aceitava. A CLI atual do OpenClaw utiliza comandos como openclaw gateway, configuração do OpenClaw, openclaw onboard, e openclaw config set; gateway.mode é uma chave de configuração, não uma opção de execução universal de nível superior que possa ser colocada em qualquer parte do comando de um contentor.
A imagem Big-Bear precisava de um diretório de configuração persistente e inicializado
O diagnóstico final da comunidade centrou-se neste ponto de montagem:
/DATA/AppData/big-bear-openclaw
→ /home/node/.openclawO contentor esperava encontrar a configuração em /home/node/.openclaw, mas o diretório montado ainda não tinha sido inicializado. Isto é consistente com a documentação atual do OpenClaw para Docker: o diretório de configuração montado contém os dados persistentes openclaw.json, dados do perfil de autenticação e segredos provenientes do ambiente.
A sugestão final da discussão foi executar a configuração dentro do contentor, para que o diretório montado recebesse uma configuração real do OpenClaw. No entanto, o autor original não voltou a confirmar o resultado após essa última resposta. Considere-a o diagnóstico mais provável da discussão, não uma resolução final verificada.
Prefira a configuração inicial atual do Docker do OpenClaw numa instalação nova
Numa implementação atual, siga o guia oficial de instalação do Docker do OpenClaw, em vez de reconstruir a sequência de resolução de problemas de 2026, um erro de cada vez.
O OpenClaw disponibiliza atualmente um script de configuração do Docker que:
- compila ou obtém a imagem do gateway;
- executa a configuração inicial;
- gera um token do gateway;
- escreve a configuração persistente;
- cria os diretórios necessários para os segredos;
- inicia o gateway através do Docker Compose.
Para implementações Docker sem interface, o OpenClaw documenta também a configuração inicial não interativa com o modo de gateway local e autenticação por token. Esta abordagem é preferível a inventar manualmente variáveis de ambiente ou a acrescentar flags não suportadas.
Padrão de configuração manual atual
O guia atual do Docker do OpenClaw documenta um padrão manual equivalente a:
openclaw onboard --mode local --no-install-daemon
openclaw config set gateway.mode local
openclaw config set gateway.bind lanNo Docker Compose, esses comandos são normalmente executados através do contentor dedicado da CLI ou de configuração inicial definido pelo projeto. Não cole comandos executados no anfitrião numa imagem CasaOS empacotada sem verificar primeiro o respetivo entrypoint e os mounts.
A atual documentação da CLI do Gateway do OpenClaw confirma que openclaw setup e openclaw onboard --mode local criam a configuração local necessária do gateway.
Utilize o mesmo token do gateway na Control UI
A documentação atual do Docker do OpenClaw disponibiliza a Control UI na porta 18789 na configuração padrão do Compose e instrui os utilizadores a colar nas definições da interface o token do gateway proveniente do ambiente de implementação.
Uma incompatibilidade de tokens pode causar falhas de autenticação depois de o gateway estar operacional, mas é diferente de um contentor que termina repetidamente porque não existe configuração. Diagnostique primeiro o arranque e, em seguida, a autenticação da interface.
Não transforme --allow-unconfigured numa solução permanente
O OpenClaw disponibiliza --allow-unconfigured para arranque ad hoc ou de desenvolvimento. A documentação atual afirma explicitamente que ignora a proteção do modo local sem escrever nem reparar a configuração. É útil para testes, mas não substitui a configuração adequada de um servidor persistente.
Lista de verificação para resolver problemas de indisponibilidade do serviço OpenClaw
- Verifique se o contentor do OpenClaw está em execução, parado ou a reiniciar.
- Leia os registos atuais do contentor antes de alterar as definições.
- Confirme
OPENCLAW_GATEWAY_TOKENexiste e é tratado como um segredo. - Se os comandos do Docker falharem com um erro de permissão no socket, utilize uma shell administrativa autorizada em vez de reduzir as permissões do socket do Docker.
- Procure especificamente por
Configuração em faltaougateway.mode=localerros. - Confirme que o caminho AppData do anfitrião está montado no diretório de configuração do OpenClaw esperado pela imagem.
- Execute o fluxo de configuração/integração inicial suportado pelo OpenClaw para que
openclaw.jsoné criado no armazenamento persistente. - Não dependa de
GATEWAY_MODE=locala menos que a documentação exata da imagem o defina explicitamente. - Não acrescente
--gateway.mode=localpara um comando arbitrário do contentor do CasaOS. - Reinicie o contentor e volte a verificar os registos depois de a configuração ser escrita.
- Só depois de o gateway permanecer ativo deve solucionar problemas de autenticação do token da interface de controlo ou de configuração do fornecedor do modelo.
Perguntas frequentes sobre a indisponibilidade do serviço OpenClaw
O OpenClaw requer OPENCLAW_GATEWAY_TOKEN?
As implementações Docker atuais do OpenClaw suportam e utilizam normalmente OPENCLAW_GATEWAY_TOKEN para a autenticação do gateway. O script oficial de configuração pode gerar um automaticamente. As imagens de terceiros empacotadas podem disponibilizar este valor de forma diferente, por isso siga o esquema de ambiente efetivamente utilizado pela imagem.
O que significa «permission denied /var/run/docker.sock»?
Significa que o utilizador atual do anfitrião não consegue aceder ao daemon do Docker. Por si só, isso não significa que o diretório de dados interno do OpenClaw não permita escrita. Utilize uma conta administrativa autorizada para os diagnósticos do Docker.
Como defino gateway.mode=local?
Utilize o comando de configuração, integração inicial ou configuração suportado pelo OpenClaw, para que o valor seja escrito no openclaw.json. A documentação atual indica configuração do OpenClaw ou openclaw onboard --mode local cria esta definição.
Devo adicionar GATEWAY_MODE=local?
Não com base neste tópico. Essa sugestão não resolveu o ciclo de reinício da imagem empacotada do utilizador, e a documentação atual do upstream trata gateway.mode como configuração, e não como uma variável de ambiente genérica denominada GATEWAY_MODE.
Porque é que --gateway.mode=local indica uma opção desconhecida?
Porque a opção foi acrescentada à camada de comando errada no pacote do CasaOS. Uma chave de configuração com pontos não é automaticamente um sinalizador de linha de comandos válido para todos os binários ou pontos de entrada do OpenClaw.
O tópico da comunidade foi definitivamente resolvido?
O tópico chegou a um diagnóstico final sólido — um diretório de configuração persistente não inicializado — e recomendou executar configuração do OpenClaw dentro do contentor. O autor original não publicou uma confirmação final após essa última instrução, pelo que a página não deve afirmar uma resolução verificada que não consta na fonte.
