Podman

Execute o Gateway do OpenClaw em um contêiner Podman sem privilégios de root, gerenciado pelo seu usuário atual sem privilégios de root.

O modelo:

• O Podman executa o contêiner do Gateway.
• A CLI openclaw do host é o plano de controle.
• Por padrão, o estado persistente fica no host, em ~/.openclaw.
• O gerenciamento cotidiano usa openclaw --container <name> ... em vez de sudo -u openclaw, podman exec ou um usuário de serviço separado.

Pré-requisitos

• Podman no modo sem privilégios de root
• CLI do OpenClaw instalada no host
• Opcional: systemd --user se você quiser inicialização automática gerenciada pelo Quadlet
• Opcional: sudo somente se você quiser usar loginctl enable-linger "$(whoami)" para persistência após a inicialização em um host sem interface gráfica

Início rápido

./scripts/podman/setup.sh --quadlet

./scripts/run-openclaw-podman.sh launch

./scripts/run-openclaw-podman.sh launch setup

export OPENCLAW_CONTAINER=openclaw

openclaw dashboard --no-openopenclaw gateway status --deep   # includes extra service scanopenclaw doctoropenclaw channels login

O inicializador manual lê somente uma pequena lista de chaves relacionadas ao Podman permitidas em ~/.openclaw/.env e passa variáveis de ambiente de execução explícitas ao contêiner; ele não fornece o arquivo de ambiente completo ao Podman.

Podman e Tailscale

Para acesso por HTTPS ou acesso remoto pelo navegador, siga a documentação principal do Tailscale.

Observações específicas do Podman:

• Mantenha o host de publicação do Podman como 127.0.0.1.
• Prefira tailscale serve gerenciado pelo host em vez de openclaw gateway --tailscale serve.
• No macOS, se o contexto de autenticação de dispositivo do navegador local não for confiável, use o acesso pelo Tailscale em vez de soluções improvisadas com túneis locais.

Consulte Tailscale e Interface de Controle.

Systemd (Quadlet, opcional)

Se você executou ./scripts/podman/setup.sh --quadlet, a configuração instala um arquivo Quadlet em ~/.config/containers/systemd/openclaw.container.

Após editar o arquivo Quadlet:

systemctl --user daemon-reloadsystemctl --user restart openclaw.service

Para manter a execução após a inicialização em hosts acessados por SSH ou sem interface gráfica, habilite a permanência para o usuário atual:

sudo loginctl enable-linger "$(whoami)"

O serviço Quadlet gerado mantém uma configuração padrão fixa e reforçada: portas publicadas em 127.0.0.1 (18789 para o Gateway, 18790 para a ponte), --bind lan dentro do contêiner, namespace de usuário keep-id, OPENCLAW_NO_RESPAWN=1, Restart=on-failure e TimeoutStartSec=300. Ele lê ~/.openclaw/.env como um EnvironmentFile de execução para valores como OPENCLAW_GATEWAY_TOKEN, mas não utiliza a lista de substituições específicas do Podman permitidas pelo inicializador manual. Para personalizar portas publicadas, o host de publicação ou outros sinalizadores de execução do contêiner, use o inicializador manual ou edite diretamente ~/.config/containers/systemd/openclaw.container e depois recarregue e reinicie o serviço.

Configuração, ambiente e armazenamento

• Diretório de configuração: ~/.openclaw
• Diretório do espaço de trabalho: ~/.openclaw/workspace
• Arquivo de token: ~/.openclaw/.env
• Auxiliar de inicialização: ./scripts/run-openclaw-podman.sh

O script de inicialização e o Quadlet montam por associação o estado do host no contêiner: OPENCLAW_CONFIG_DIR -> /home/node/.openclaw, OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace. Por padrão, esses são diretórios do host, não um estado anônimo do contêiner; portanto, openclaw.json, os arquivos auth-profiles.json de cada agente, o estado dos canais/provedores, as sessões e o espaço de trabalho sobrevivem à substituição do contêiner. A configuração também preenche gateway.controlUi.allowedOrigins para 127.0.0.1 e localhost na porta publicada do Gateway, para que o painel local funcione com a vinculação não local loopback do contêiner.

Variáveis de ambiente úteis para o inicializador manual (mantenha-as em ~/.openclaw/.env; o inicializador lê esse arquivo antes de finalizar os padrões do contêiner e da imagem):

Se você usar valores não padrão para OPENCLAW_CONFIG_DIR ou OPENCLAW_WORKSPACE_DIR, defina as mesmas variáveis tanto para ./scripts/podman/setup.sh quanto para os comandos posteriores ./scripts/run-openclaw-podman.sh launch — o inicializador local do repositório não mantém substituições personalizadas de caminhos entre sessões do shell.

Atualização de imagens

Depois de recompilar ou baixar uma nova imagem, reinicie o contêiner ou o serviço Quadlet. Na primeira inicialização de uma nova versão do OpenClaw, o Gateway executa reparos seguros no estado e nos plugins antes de informar que está pronto.

Se o Gateway encerrar em vez de ficar pronto, execute a mesma imagem uma vez com openclaw doctor --fix usando o mesmo estado/configuração montado e depois reinicie o Gateway normalmente:

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}" podman run --rm -it \  --userns=keep-id \  --user "$(id -u):$(id -g)" \  -e HOME=/home/node \  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \  "$OPENCLAW_PODMAN_IMAGE" \  openclaw doctor --fix

Em hosts com SELinux, adicione ,Z às duas montagens por associação se o Podman bloquear o acesso ao estado montado.

Comandos úteis

• Logs do contêiner: podman logs -f openclaw
• Parar o contêiner: podman stop openclaw
• Remover o contêiner: podman rm -f openclaw
• Abrir a URL do painel pela CLI do host: openclaw dashboard --no-open
• Integridade/status pela CLI do host: openclaw gateway status --deep (sondagem RPC + verificação adicional de serviços)

Solução de problemas

• Permissão negada (EACCES) na configuração ou no espaço de trabalho: Por padrão, o contêiner é executado com --userns=keep-id e --user <your uid>:<your gid>. Verifique se os caminhos de configuração/espaço de trabalho no host pertencem ao usuário atual.
• Inicialização do Gateway bloqueada (gateway.mode=local ausente): Verifique se ~/.openclaw/openclaw.json existe e define gateway.mode="local". scripts/podman/setup.sh cria esse arquivo se estiver ausente.
• O contêiner reinicia após uma atualização da imagem: Execute uma vez o comando openclaw doctor --fix descrito em Atualização de imagens e depois inicie novamente o Gateway.
• Os comandos da CLI do contêiner atingem o destino errado: Use explicitamente openclaw --container <name> ... ou exporte OPENCLAW_CONTAINER=<name> no shell.
• openclaw update falha com --container: Isso é esperado. Recompile/baixe a imagem e depois reinicie o contêiner ou o serviço Quadlet.
• O serviço Quadlet não inicia: Execute systemctl --user daemon-reload e depois systemctl --user start openclaw.service. Em sistemas sem interface gráfica, talvez também seja necessário executar sudo loginctl enable-linger "$(whoami)".
• O SELinux bloqueia montagens por associação: Não altere o comportamento padrão de montagem; o inicializador adiciona automaticamente :Z no Linux quando o SELinux está no modo de imposição ou permissivo.

Relacionado

• Docker
• Processo do Gateway em segundo plano
• Solução de problemas do Gateway