Platform setup
How to Run OpenClaw with Podman
Browse more in Platform setup.
All platform setup guides →This guide shows you how to run the OpenClaw Gateway in a rootless Podman container, controlled from your host with the OpenClaw CLI. You will build or select the OpenClaw image, launch the gateway, run onboarding, and optionally wire it into systemd Quadlet for auto-start.
openclaw` on your host.
Prerequisites
- ✓Podman installed and configured in rootless mode for your current non-root user.
- ✓OpenClaw CLI installed on the host so you can run `openclaw` commands.
- ✓`systemd --user` available if you want Quadlet-managed auto-start for the Podman container.
- ✓`sudo` access if you plan to run `sudo loginctl enable-linger "$(whoami)"` for boot persistence on a headless host.
Steps
- 1
Run the one-time Podman setup script
From the OpenClaw repo root, run the Podman setup script to build `openclaw:local` in your rootless Podman store or use an image you specify via `OPENCLAW_IMAGE` / `OPENCLAW_PODMAN_IMAGE`. env` with `OPENCLAW_GATEWAY_TOKEN` if they are missing.
bash./scripts/podman/setup.sh - 2
Optionally enable Quadlet-managed Podman setup
If you want systemd to manage the Podman container for auto-start and restart-on-failure, run the setup script with the Quadlet flag. 1:18790:18790`.
bash./scripts/podman/setup.sh --quadlet - 3
Launch the OpenClaw Gateway Podman container
Start the gateway container using the launcher script so it runs as your current uid/gid with `--userns=keep-id` and bind-mounts your OpenClaw state into the container. json`, auth profiles, channel/provider state, sessions, and workspace on the host so they survive container replacement.
bash./scripts/run-openclaw-podman.sh launch - 4
Run onboarding inside the Podman container
Run the launcher in setup mode to trigger onboarding inside the container, then connect from your browser. env` when the Control UI prompts you so the gateway can authenticate your device.
bash./scripts/run-openclaw-podman.sh launch setup - 5
Verify the gateway is reachable on the published port
Once onboarding is running, hit the gateway from your host using the published port to confirm Podman networking and the bind-mounts are working. 1` and `localhost` on this port so the local dashboard works with the container’s non-loopback bind.
bashopenclaw gateway status --deep # includes extra service scan - 6
Control the running container from the host OpenClaw CLI
Export the container name so your host `openclaw` CLI automatically targets the Podman container instead of a local process. Then you can open the dashboard, inspect gateway status, run diagnostics, and log into channels without manually exec’ing into the container.
bashexport OPENCLAW_CONTAINER=openclaw openclaw dashboard --no-open openclaw gateway status --deep # includes extra service scan openclaw doctor openclaw channels login - 7
Manage the Quadlet systemd service when enabled
If you enabled Quadlet, use systemd user commands to start, stop, inspect, and tail logs for the OpenClaw service. After editing the Quadlet file, reload the user daemon and restart the service; on headless systems, enable lingering so the user service starts at boot.
bashsystemctl --user start openclaw.service systemctl --user stop openclaw.service systemctl --user status openclaw.service journalctl --user -u openclaw.service -f systemctl --user daemon-reload systemctl --user restart openclaw.service sudo loginctl enable-linger "$(whoami)" - 8
Use Podman and OpenClaw helper commands for day-to-day ops
For low-level container operations, use Podman to inspect logs, stop, or remove the `openclaw` container. For gateway-level operations, prefer the host `openclaw` CLI so you keep the same workflow whether the gateway runs in Podman or directly on the host.
bashpodman logs -f openclaw podman stop openclaw podman rm -f openclaw openclaw dashboard --no-open openclaw gateway status --deep
Configuration
| Option | Description | Example |
|---|---|---|
| OPENCLAW_IMAGE | Use an existing or pulled image instead of building `openclaw:local` during setup and launch. | ghcr.io/openclaw/openclaw:latest |
| OPENCLAW_PODMAN_IMAGE | Alternative variable to specify which image the Podman launcher should run instead of the locally built one. | ghcr.io/openclaw/openclaw:stable |
| OPENCLAW_DOCKER_APT_PACKAGES | Extra apt packages to install during the image build when running the Podman setup script. | git curl |
| OPENCLAW_EXTENSIONS | Extension dependencies to pre-install at image build time so they are available inside the container. | @openclaw/some-extension,@openclaw/another-extension |
| OPENCLAW_PODMAN_QUADLET | Enables Quadlet-managed setup when set, so the setup script generates a systemd user service for the container. | 1 |
| OPENCLAW_CONFIG_DIR | Host directory that stores OpenClaw configuration and is bind-mounted into `/home/node/.openclaw` inside the container. | /home/alice/.openclaw |
| OPENCLAW_WORKSPACE_DIR | Host directory for the OpenClaw workspace, bind-mounted into `/home/node/.openclaw/workspace` inside the container. | /home/alice/.openclaw/workspace |
| OPENCLAW_PODMAN_CONTAINER | Name of the Podman container that the manual launcher and host CLI target; defaults to `openclaw`. | openclaw |
| OPENCLAW_PODMAN_GATEWAY_HOST_PORT | Host port mapped to the container’s gateway port 18789. | 18789 |
| OPENCLAW_PODMAN_BRIDGE_HOST_PORT | Host port mapped to the container’s bridge port 18790. | 18790 |
| OPENCLAW_PODMAN_PUBLISH_HOST | Host interface for published ports; default is `127.0.0.1` for local-only access. | 127.0.0.1 |
| OPENCLAW_GATEWAY_BIND | Gateway bind mode inside the container; default is `lan`. | lan |
| OPENCLAW_PODMAN_USERNS | User namespace mode for the container, such as `keep-id`, `auto`, or `host`. | keep-id |
| OPENCLAW_CONTAINER | Default container name that the host `openclaw` CLI targets when running commands with `--container` semantics. | openclaw |
Troubleshooting
Permission denied (EACCES) on config or workspace
The container runs with `--userns=keep-id` and `--user <your uid>:<your gid>` by default, so Podman expects the bind-mounted config and workspace paths to be owned by your current user. openclaw/workspace`) are owned by your user so the container can read and write them.
Gateway start blocked (missing `gateway.mode=local`)
mode="local"`. sh` from the repo root so it creates this file with the correct mode if it is missing.
./scripts/podman/setup.shContainer CLI commands hit the wrong target
If `openclaw` commands are talking to the wrong gateway, explicitly point the CLI at your Podman container. ` on each command, or export `OPENCLAW_CONTAINER=<name>` in your shell so the CLI defaults to that container.
export OPENCLAW_CONTAINER=openclaw
openclaw gateway status --deep`openclaw update` fails with `--container`
`openclaw update` is expected to fail when used with `--container` because updates happen at the image level. Rebuild or pull a new image instead, then restart the Podman container or the Quadlet service so it runs the updated image.
Quadlet service does not start
service` fails to start, reload the user systemd daemon and start the service again. On SSH/headless systems you may also need to enable lingering for your user so the service can start at boot.
systemctl --user daemon-reload
systemctl --user start openclaw.service
sudo loginctl enable-linger "$(whoami)"SELinux blocks bind mounts
When SELinux is enforcing or permissive and blocks the container’s bind mounts, keep the default mount behavior from the launcher. The Podman launcher auto-adds `:Z` on Linux when SELinux is enforcing or permissive so the container can access the host directories safely.
Frequently asked questions
Powered by Mem0
Add persistent memory to OpenClaw
Official Mem0 plugin for OpenClaw keeps context across chats and tools. Smaller prompts, lower cost, better continuity for your agents.