Run OpenClaw with Rootless Podman: Quick Setup Guide

thought}Setting up a gateway can be a bit of a headache when you’re trying to balance security with ease of use. You want to keep your host system clean while ensuring your services stay up and running without constant babysitting.

Running the OpenClaw gateway in a rootless Podman container is a great way to handle this. It uses the same image as Docker, built directly from the repo’s Dockerfile, but keeps everything isolated from your root user.

Requirements

To get started, you’ll need:

• Podman (rootless)
• Sudo for one-time setup tasks like creating the user and building the image

Quick start

1. One-time setup (run this from the repo root to create the user, build the image, and install the launch script):

./setup-podman.sh

This script also creates a minimal ~openclaw/.openclaw/openclaw.json and sets gateway.mode="local". This means the gateway can start right away without you needing to run the wizard first.

By default, the container isn’t installed as a systemd service, so you’ll start it manually. If you want a production-style setup with auto-start and restarts, you can install it as a systemd Quadlet user service:

./setup-podman.sh --quadlet

You can also set OPENCLAW_PODMAN_QUADLET=1 or use --container to install only the container and launch script. If you need to customize the build, you can set these environment variables before running the setup:

• OPENCLAW_DOCKER_APT_PACKAGES — install extra apt packages during the image build
• OPENCLAW_EXTENSIONS — pre-install extension dependencies (space-separated names, like diagnostics-otel matrix)
• OPENCLAW_PODMAN_GATEWAY_HOST_PORT — override the default gateway port
• OPENCLAW_PODMAN_BRIDGE_HOST_PORT — override the default bridge port

2. Start gateway (manual, for quick smoke testing):

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

3. Onboarding wizard (use this to add channels or providers):

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

After running this, open http://127.0.0.1:18789/ and use the token found in ~openclaw/.openclaw/.env or the value printed during setup.

Systemd (Quadlet, optional)

If you chose the --quadlet option or set OPENCLAW_PODMAN_QUADLET=1, a Podman Quadlet unit is installed. This lets the gateway run as a systemd

openclaw:100000:65536

sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup