Podman

Execute o gateway OpenClaw em um container rootless Podman. Usa a mesma imagem do Docker (construida a partir do Dockerfile do repositorio).

Requisitos

Podman (rootless)
Sudo para configuracao unica (criar usuario, construir imagem)

Inicio rapido

1. Configuracao unica (a partir da raiz do repositorio; cria o usuario, constroi a imagem, instala o script de inicializacao):

./setup-podman.sh

Isso tambem cria um ~openclaw/.openclaw/openclaw.json minimo (define gateway.mode="local") para que o gateway possa iniciar sem rodar o assistente.

Por padrao, o container nao e instalado como servico systemd, voce o inicia manualmente (veja abaixo). Para uma configuracao de producao com inicio automatico e reinicializacoes, instale como servico de usuario systemd Quadlet:

./setup-podman.sh --quadlet

(Ou defina OPENCLAW_PODMAN_QUADLET=1; use --container para instalar apenas o container e o script de inicializacao.)

Variaveis de ambiente opcionais de build (defina antes de executar setup-podman.sh):

OPENCLAW_DOCKER_APT_PACKAGES — instalar pacotes apt extras durante o build da imagem
OPENCLAW_EXTENSIONS — pre-instalar dependencias de extensoes (nomes de extensoes separados por espaco, por ex. diagnostics-otel matrix)

2. Iniciar o gateway (manual, para teste rapido):

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

3. Assistente de onboarding (por ex. para adicionar canais ou provedores):

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

Depois abra http://127.0.0.1:18789/ e use o token de ~openclaw/.openclaw/.env (ou o valor exibido pelo setup).

Systemd (Quadlet, opcional)

Se voce executou ./setup-podman.sh --quadlet (ou OPENCLAW_PODMAN_QUADLET=1), uma unidade Podman Quadlet e instalada para que o gateway rode como servico de usuario systemd para o usuario openclaw. O servico e habilitado e iniciado ao final da configuracao.

Iniciar: sudo systemctl --machine openclaw@ --user start openclaw.service
Parar: sudo systemctl --machine openclaw@ --user stop openclaw.service
Status: sudo systemctl --machine openclaw@ --user status openclaw.service
Logs: sudo journalctl --machine openclaw@ --user -u openclaw.service -f

O arquivo quadlet fica em ~openclaw/.config/containers/systemd/openclaw.container. Para mudar portas ou ambiente, edite esse arquivo (ou o .env que ele carrega), depois sudo systemctl --machine openclaw@ --user daemon-reload e reinicie o servico. No boot, o servico inicia automaticamente se lingering esta habilitado para openclaw (o setup faz isso quando loginctl esta disponivel).

Para adicionar quadlet apos uma configuracao inicial que nao o usou, re-execute: ./setup-podman.sh --quadlet.

setup-podman.sh cria um usuario de sistema dedicado openclaw:

Shell: nologin — sem login interativo; reduz a superficie de ataque.
Home: por ex. /home/openclaw — contem ~/.openclaw (config, workspace) e o script de inicializacao run-openclaw-podman.sh.
Podman rootless: O usuario deve ter um range subuid e subgid. Muitas distros atribuem automaticamente ao criar o usuario. Se o setup exibir um aviso, adicione linhas em /etc/subuid e /etc/subgid:
```
openclaw:100000:65536
```
Depois inicie o gateway como esse usuario (por ex. via cron ou systemd):
```
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup
```
Configuracao: Apenas openclaw e root podem acessar /home/openclaw/.openclaw. Para editar a config: use a interface de controle quando o gateway estiver rodando, ou sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json.

Ambiente e configuracao

Token: Armazenado em ~openclaw/.openclaw/.env como OPENCLAW_GATEWAY_TOKEN. setup-podman.sh e run-openclaw-podman.sh o geram se estiver ausente (usa openssl, python3, ou od).
Opcional: Nesse .env voce pode definir chaves de provedores (por ex. GROQ_API_KEY, OLLAMA_API_KEY) e outras variaveis de ambiente do OpenClaw.
Portas do host: Por padrao, o script mapeia 18789 (gateway) e 18790 (bridge). Sobrescreva o mapeamento de porta do host com OPENCLAW_PODMAN_GATEWAY_HOST_PORT e OPENCLAW_PODMAN_BRIDGE_HOST_PORT ao iniciar.
Binding do gateway: Por padrao, run-openclaw-podman.sh inicia o gateway com --bind loopback para acesso local seguro. Para expor na LAN, defina OPENCLAW_GATEWAY_BIND=lan e configure gateway.controlUi.allowedOrigins (ou habilite explicitamente o fallback host-header) em openclaw.json.
Caminhos: Config e workspace do host sao por padrao ~openclaw/.openclaw e ~openclaw/.openclaw/workspace. Sobrescreva os caminhos do host usados pelo script de inicializacao com OPENCLAW_CONFIG_DIR e OPENCLAW_WORKSPACE_DIR.

Modelo de armazenamento

Dados persistentes do host: OPENCLAW_CONFIG_DIR e OPENCLAW_WORKSPACE_DIR sao montados em bind no container e mantem o estado no host.
tmpfs sandbox efemero: se voce habilitar agents.defaults.sandbox, os containers sandbox de ferramentas montam tmpfs em /tmp, /var/tmp e /run. Esses caminhos sao em memoria e desaparecem com o container sandbox; a configuracao do container Podman principal nao adiciona seus proprios montagens tmpfs.
Pontos quentes de crescimento de disco: os principais caminhos a monitorar sao media/, agents/<agentId>/sessions/sessions.json, arquivos JSONL de transcricao, cron/runs/*.jsonl e logs de arquivo rotativos em /tmp/openclaw/ (ou seu logging.file configurado).

Comandos uteis

Logs: Com quadlet: sudo journalctl --machine openclaw@ --user -u openclaw.service -f. Com script: sudo -u openclaw podman logs -f openclaw
Parar: Com quadlet: sudo systemctl --machine openclaw@ --user stop openclaw.service. Com script: sudo -u openclaw podman stop openclaw
Iniciar novamente: Com quadlet: sudo systemctl --machine openclaw@ --user start openclaw.service. Com script: re-execute o script de inicializacao ou podman start openclaw
Remover container: sudo -u openclaw podman rm -f openclaw — config e workspace no host sao mantidos

Solucao de problemas

Permissao negada (EACCES) na config ou perfis de auth: O container usa --userns=keep-id por padrao e roda com o mesmo uid/gid do usuario host executando o script. Garanta que seus OPENCLAW_CONFIG_DIR e OPENCLAW_WORKSPACE_DIR no host pertencam a esse usuario.
Inicio do gateway bloqueado (faltando gateway.mode=local): Garanta que ~openclaw/.openclaw/openclaw.json existe e define gateway.mode="local". setup-podman.sh cria este arquivo se estiver ausente.
Podman rootless falha para o usuario openclaw: Verifique se /etc/subuid e /etc/subgid contem uma linha para openclaw (por ex. openclaw:100000:65536). Adicione se estiver faltando e reinicie.
Nome de container em uso: O script de inicializacao usa podman run --replace, entao o container existente e substituido ao iniciar. Para limpar manualmente: podman rm -f openclaw.
Script nao encontrado ao executar como openclaw: Garanta que setup-podman.sh foi executado para que run-openclaw-podman.sh tenha sido copiado para o home do openclaw (por ex. /home/openclaw/run-openclaw-podman.sh).
Servico quadlet nao encontrado ou falha ao iniciar: Execute sudo systemctl --machine openclaw@ --user daemon-reload apos editar o arquivo .container. Quadlet requer cgroups v2: podman info --format '{{.Host.CgroupsVersion}}' deve mostrar 2.

Opcional: executar como seu proprio usuario

Para executar o gateway como seu usuario normal (sem usuario openclaw dedicado): construa a imagem, crie ~/.openclaw/.env com OPENCLAW_GATEWAY_TOKEN, e execute o container com --userns=keep-id e montagens para seu ~/.openclaw. O script de inicializacao e projetado para o fluxo do usuario openclaw; para uma configuracao de usuario unico, voce pode executar o comando podman run do script manualmente, apontando config e workspace para seu home. Recomendado para a maioria dos usuarios: use setup-podman.sh e execute como usuario openclaw para que config e processo fiquem isolados.