Podman

Run the OpenClaw Gateway in a rootless Podman container, managed by your current non-root user.

The intended model is:

• Podman runs the gateway container.
• Your host
  text

  Copy

  openclaw
  CLI is the control plane.
• Persistent state lives on the host under
  text

  Copy

  ~/.openclaw
  by default.
• Day-to-day management uses
  text

  Copy

  openclaw --container <name> ...
  instead of
  text

  Copy

  sudo -u openclaw
  ,
  text

  Copy

  podman exec
  , or a separate service user.

Prerequisites

• Podman in rootless mode
• OpenClaw CLI installed on the host
• Optional:
  text

  Copy

  systemd --user
  if you want Quadlet-managed auto-start
• Optional:
  text

  Copy

  sudo
  only if you want
  text

  Copy

  loginctl enable-linger "$(whoami)"
  for boot persistence on a headless host

Quick start

Setup details:

• text

  Copy

  ./scripts/podman/setup.sh
  builds
  text

  Copy

  openclaw:local
  in your rootless Podman store by default, or uses
  text

  Copy

  OPENCLAW_IMAGE
  /
  text

  Copy

  OPENCLAW_PODMAN_IMAGE
  if you set one.
• It creates
  text

  Copy

  ~/.openclaw/openclaw.json
  with
  text

  Copy

  gateway.mode: "local"
  if missing.
• It creates
  text

  Copy

  ~/.openclaw/.env
  with
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  if missing.
• For manual launches, the helper reads only a small allowlist of Podman-related keys from
  text

  Copy

  ~/.openclaw/.env
  and passes explicit runtime env vars to the container; it does not hand the full env file to Podman.

Quadlet-managed setup:

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

Quadlet is a Linux-only option because it depends on systemd user services.

You can also set

.

Optional build/setup env vars:

• text

  Copy

  OPENCLAW_IMAGE
  or
  text

  Copy

  OPENCLAW_PODMAN_IMAGE
  -- use an existing/pulled image instead of building
  text

  Copy

  openclaw:local
• text

  Copy

  OPENCLAW_DOCKER_APT_PACKAGES
  -- install extra apt packages during image build
• text

  Copy

  OPENCLAW_EXTENSIONS
  -- pre-install plugin dependencies at build time
• text

  Copy

  OPENCLAW_INSTALL_BROWSER
  -- pre-install Chromium and Xvfb for browser automation (set to
  text

  Copy

  1
  to enable)

Container start:

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

The script starts the container as your current uid/gid with

and bind-mounts your OpenClaw state into the container.

Onboarding:

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

Then open

and use the token from .

Host CLI default:

bash
Copy
export OPENCLAW_CONTAINER=openclaw

Then commands such as these will run inside that container automatically:

bash
Copy
openclaw dashboard --no-open
openclaw gateway status --deep   # includes extra service scan
openclaw doctor
openclaw channels login

On macOS, Podman machine may make the browser appear non-local to the gateway. If the Control UI reports device-auth errors after launch, use the Tailscale guidance in Podman + Tailscale.

Podman + Tailscale

For HTTPS or remote browser access, follow the main Tailscale docs.

Podman-specific note:

• Keep the Podman publish host at
  text

  Copy

  127.0.0.1
  .
• Prefer host-managed
  text

  Copy

  tailscale serve
  over
  text

  Copy

  openclaw gateway --tailscale serve
  .
• On macOS, if local browser device-auth context is unreliable, use Tailscale access instead of ad hoc local tunnel workarounds.

See:

• Tailscale
• Control UI

Systemd (Quadlet, optional)

If you ran

, setup installs a Quadlet file at:

bash
Copy
~/.config/containers/systemd/openclaw.container

Useful commands:

• Start:
  text

  Copy

  systemctl --user start openclaw.service
• Stop:
  text

  Copy

  systemctl --user stop openclaw.service
• Status:
  text

  Copy

  systemctl --user status openclaw.service
• Logs:
  text

  Copy

  journalctl --user -u openclaw.service -f

After editing the Quadlet file:

bash
Copy
systemctl --user daemon-reload
systemctl --user restart openclaw.service

For boot persistence on SSH/headless hosts, enable lingering for your current user:

bash
Copy
sudo loginctl enable-linger "$(whoami)"

Config, env, and storage

• Config dir:
  text

  Copy

  ~/.openclaw
• Workspace dir:
  text

  Copy

  ~/.openclaw/workspace
• Token file:
  text

  Copy

  ~/.openclaw/.env
• Launch helper:
  text

  Copy

  ./scripts/run-openclaw-podman.sh

The launch script and Quadlet bind-mount host state into the container:

• text

  Copy

  OPENCLAW_CONFIG_DIR
  ->
  text

  Copy

  /home/node/.openclaw
• text

  Copy

  OPENCLAW_WORKSPACE_DIR
  ->
  text

  Copy

  /home/node/.openclaw/workspace

By default those are host directories, not anonymous container state, so

, per-agent , channel/provider state, sessions, and workspace survive container replacement. The Podman setup also seeds for and on the published gateway port so the local dashboard works with the container's non-loopback bind.

Useful env vars for the manual launcher:

• text

  Copy

  OPENCLAW_PODMAN_CONTAINER
  -- container name (
  text

  Copy

  openclaw
  by default)
• text

  Copy

  OPENCLAW_PODMAN_IMAGE
  /
  text

  Copy

  OPENCLAW_IMAGE
  -- image to run
• text

  Copy

  OPENCLAW_PODMAN_GATEWAY_HOST_PORT
  -- host port mapped to container
  text

  Copy

  18789
• text

  Copy

  OPENCLAW_PODMAN_BRIDGE_HOST_PORT
  -- host port mapped to container
  text

  Copy

  18790
• text

  Copy

  OPENCLAW_PODMAN_PUBLISH_HOST
  -- host interface for published ports; default is
  text

  Copy

  127.0.0.1
• text

  Copy

  OPENCLAW_GATEWAY_BIND
  -- gateway bind mode inside the container; default is
  text

  Copy

  lan
• text

  Copy

  OPENCLAW_PODMAN_USERNS
  --
  text

  Copy

  keep-id
  (default),
  text

  Copy

  auto
  , or
  text

  Copy

  host

The manual launcher reads

before finalizing container/image defaults, so you can persist these there.

If you use a non-default

or , set the same variables for both and later commands. The repo-local launcher does not persist custom path overrides across shells.

Quadlet note:

• The generated Quadlet service intentionally keeps a fixed, hardened default shape:
  text

  Copy

  127.0.0.1
  published ports,
  text

  Copy

  --bind lan
  inside the container, and
  text

  Copy

  keep-id
  user namespace.
• It pins
  text

  Copy

  OPENCLAW_NO_RESPAWN=1
  ,
  text

  Copy

  Restart=on-failure
  , and
  text

  Copy

  TimeoutStartSec=300
  .
• It publishes both
  text

  Copy

  127.0.0.1:18789:18789
  (gateway) and
  text

  Copy

  127.0.0.1:18790:18790
  (bridge).
• It reads
  text

  Copy

  ~/.openclaw/.env
  as a runtime
  text

  Copy

  EnvironmentFile
  for values such as
  text

  Copy

  OPENCLAW_GATEWAY_TOKEN
  , but it does not consume the manual launcher's Podman-specific override allowlist.
• If you need custom publish ports, publish host, or other container-run flags, use the manual launcher or edit
  text

  Copy

  ~/.config/containers/systemd/openclaw.container
  directly, then reload and restart the service.

Useful commands

• Container logs:
  text

  Copy

  podman logs -f openclaw
• Stop container:
  text

  Copy

  podman stop openclaw
• Remove container:
  text

  Copy

  podman rm -f openclaw
• Open dashboard URL from host CLI:
  text

  Copy

  openclaw dashboard --no-open
• Health/status via host CLI:
  text

  Copy

  openclaw gateway status --deep
  (RPC probe + extra service scan)

Troubleshooting

• Permission denied (EACCES) on config or workspace: The container runs with
  text

  Copy

  --userns=keep-id
  and
  text

  Copy

  --user <your uid>:<your gid>
  by default. Ensure the host config/workspace paths are owned by your current user.
• Gateway start blocked (missing
  text

  Copy

  gateway.mode=local
  ): Ensure
  text

  Copy

  ~/.openclaw/openclaw.json
  exists and sets
  text

  Copy

  gateway.mode="local"
  .
  text

  Copy

  scripts/podman/setup.sh
  creates this if missing.
• Container CLI commands hit the wrong target: Use
  text

  Copy

  openclaw --container <name> ...
  explicitly, or export
  text

  Copy

  OPENCLAW_CONTAINER=<name>
  in your shell.
• text

  Copy

  openclaw update
  fails with
  text

  Copy

  --container
  : Expected. Rebuild/pull the image, then restart the container or the Quadlet service.
• Quadlet service does not start: Run
  text

  Copy

  systemctl --user daemon-reload
  , then
  text

  Copy

  systemctl --user start openclaw.service
  . On headless systems you may also need
  text

  Copy

  sudo loginctl enable-linger "$(whoami)"
  .
• SELinux blocks bind mounts: Leave the default mount behavior alone; the launcher auto-adds
  text

  Copy

  :Z
  on Linux when SELinux is enforcing or permissive.

Related

• Docker
• Gateway background process
• Gateway troubleshooting