sudo journalctl --machine openclaw@ --user -u openclaw.service -f<\/code><\/li>\n<\/ul>\nThe quadlet file lives at ~openclaw\/.config\/containers\/systemd\/openclaw.container<\/code>. To change ports or env, edit that file (or the .env<\/code> it sources), then sudo systemctl --machine openclaw@ --user daemon-reload<\/code> and restart the service. On boot, the service starts automatically if lingering is enabled for openclaw (setup does this when loginctl is available).<\/p>\nTo add quadlet after<\/strong> an initial setup that did not use it, re-run: .\/scripts\/podman\/setup.sh --quadlet<\/code>.<\/p>\nThe openclaw user (non-login)<\/h2>\n
scripts\/podman\/setup.sh<\/code> creates a dedicated system user openclaw<\/code>:<\/p>\n\n- \n
Shell:<\/strong> nologin<\/code> — no interactive login; reduces attack surface.<\/p>\n<\/li>\n- \n
Home:<\/strong> e.g. \/home\/openclaw<\/code> — holds ~\/.openclaw<\/code> (config, workspace) and the launch script run-openclaw-podman.sh<\/code>.<\/p>\n<\/li>\n- \n
Rootless Podman:<\/strong> The user must have a subuid<\/strong> and subgid<\/strong> range. Many distros assign these automatically when the user is created. If setup prints a warning, add lines to \/etc\/subuid<\/code> and \/etc\/subgid<\/code>:<\/p>\n<\/li>\n<\/ul>\ntext theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n openclaw:100000:65536<\/code><\/p>\nThen start the gateway as that user (e.g. from cron or systemd):<\/p>\n
bash theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\n sudo -u openclaw \/home\/openclaw\/run-openclaw-podman.sh
\n sudo -u openclaw \/home\/openclaw\/run-openclaw-podman.sh setup<\/code><\/p>\n\n- Config:<\/strong> Only
openclaw<\/code> and root can access \/home\/openclaw\/.openclaw<\/code>. To edit config: use the Control UI once the gateway is running, or sudo -u openclaw $EDITOR \/home\/openclaw\/.openclaw\/openclaw.json<\/code>.<\/li>\n<\/ul>\nEnvironment and config<\/h2>\n\n- Token:<\/strong> Stored in
~openclaw\/.openclaw\/.env<\/code> as OPENCLAW_GATEWAY_TOKEN<\/code>. scripts\/podman\/setup.sh<\/code> and run-openclaw-podman.sh<\/code> generate it if missing (uses openssl<\/code>, python3<\/code>, or od<\/code>).<\/li>\n- 可选项:<\/strong> In that
.env<\/code> you can set provider keys (e.g. GROQ_API_KEY<\/code>, OLLAMA_API_KEY<\/code>) and other OpenClaw env vars.<\/li>\n- Host ports:<\/strong> By default the script maps
18789<\/code> (gateway) and 18790<\/code> (bridge). Override the host<\/strong> port mapping with OPENCLAW_PODMAN_GATEWAY_HOST_PORT<\/code> and OPENCLAW_PODMAN_BRIDGE_HOST_PORT<\/code> when launching.<\/li>\n- Gateway bind:<\/strong> By default,
run-openclaw-podman.sh<\/code> starts the gateway with --bind loopback<\/code> for safe local access. To expose on LAN, set OPENCLAW_GATEWAY_BIND=lan<\/code> and configure gateway.controlUi.allowedOrigins<\/code> (or explicitly enable host-header fallback) in openclaw.json<\/code>.<\/li>\n- Paths:<\/strong> Host config and workspace default to
~openclaw\/.openclaw<\/code> and ~openclaw\/.openclaw\/workspace<\/code>. Override the host paths used by the launch script with OPENCLAW_CONFIG_DIR<\/code> and OPENCLAW_WORKSPACE_DIR<\/code>.<\/li>\n<\/ul>\nStorage model<\/h2>\n\n- Persistent host data:<\/strong>
OPENCLAW_CONFIG_DIR<\/code> and OPENCLAW_WORKSPACE_DIR<\/code> are bind-mounted into the container and retain state on the host.<\/li>\n- Ephemeral sandbox tmpfs:<\/strong> if you enable
agents.defaults.sandbox<\/code>, the tool sandbox containers mount tmpfs<\/code> at \/tmp<\/code>, \/var\/tmp<\/code>, and \/run<\/code>. Those paths are memory-backed and disappear with the sandbox container; the top-level Podman container setup does not add its own tmpfs mounts.<\/li>\n- Disk growth hotspots:<\/strong> the main paths to watch are
media\/<\/code>, agents\/<agentId>\/sessions\/sessions.json<\/code>, transcript JSONL files, cron\/runs\/*.jsonl<\/code>, and rolling file logs under \/tmp\/openclaw\/<\/code> (or your configured logging.file<\/code>).<\/li>\n<\/ul>\nscripts\/podman\/setup.sh<\/code> now stages the image tar in a private temp directory and prints the chosen base dir during setup. For non-root runs it accepts TMPDIR<\/code> only when that base is safe to use; otherwise it falls back to \/var\/tmp<\/code>, then \/tmp<\/code>. The saved tar stays owner-only and is streamed into the target user’s podman load<\/code>, so private caller temp dirs do not block setup.<\/p>\nUseful commands<\/h2>\n\n- Logs:<\/strong> With quadlet:
sudo journalctl --machine openclaw@ --user -u openclaw.service -f<\/code>. With script: sudo -u openclaw podman logs -f openclaw<\/code><\/li>\n- Stop:<\/strong> With quadlet:
sudo systemctl --machine openclaw@ --user stop openclaw.service<\/code>. With script: sudo -u openclaw podman stop openclaw<\/code><\/li>\n- Start again:<\/strong> With quadlet:
sudo systemctl --machine openclaw@ --user start openclaw.service<\/code>. With script: re-run the launch script or podman start openclaw<\/code><\/li>\n- Remove container:<\/strong>
sudo -u openclaw podman rm -f openclaw<\/code> — config and workspace on the host are kept<\/li>\n<\/ul>\n故障排查<\/h2>\n\n- Permission denied (EACCES) on config or auth-profiles:<\/strong> The container defaults to
--userns=keep-id<\/code> and runs as the same uid\/gid as the host user running the script. Ensure your host OPENCLAW_CONFIG_DIR<\/code> and OPENCLAW_WORKSPACE_DIR<\/code> are owned by that user.<\/li>\n- Gateway start blocked (missing
gateway.mode=local<\/code>):<\/strong> Ensure ~openclaw\/.openclaw\/openclaw.json<\/code> exists and sets gateway.mode=\"local\"<\/code>. scripts\/podman\/setup.sh<\/code> creates this file if missing.<\/li>\n- Rootless Podman fails for user openclaw:<\/strong> Check
\/etc\/subuid<\/code> and \/etc\/subgid<\/code> contain a line for openclaw<\/code> (e.g. openclaw:100000:65536<\/code>). Add it if missing and restart.<\/li>\n- Container name in use:<\/strong> The launch script uses
podman run --replace<\/code>, so the existing container is replaced when you start again. To clean up manually: podman rm -f openclaw<\/code>.<\/li>\n- Script not found when running as openclaw:<\/strong> Ensure
scripts\/podman\/setup.sh<\/code> was run so that run-openclaw-podman.sh<\/code> is copied to openclaw’s home (e.g. \/home\/openclaw\/run-openclaw-podman.sh<\/code>).<\/li>\n- Quadlet service not found or fails to start:<\/strong> Run
sudo systemctl --machine openclaw@ --user daemon-reload<\/code> after editing the .container<\/code> file. Quadlet requires cgroups v2: podman info --format '{{.Host.CgroupsVersion}}'<\/code> should show 2<\/code>.<\/li>\n<\/ul>\n可选项: run as your own user<\/h2>\n
To run the gateway as your normal user (no dedicated openclaw user): build the image, create ~\/.openclaw\/.env<\/code> with OPENCLAW_GATEWAY_TOKEN<\/code>, and run the container with --userns=keep-id<\/code> and mounts to your ~\/.openclaw<\/code>. The launch script is designed for the openclaw-user flow; for a single-user setup you can instead run the podman run<\/code> command from the script manually, pointing config and workspace to your home. 推荐 for most users: use scripts\/podman\/setup.sh<\/code> and run as the openclaw user so config and process are isolated.<\/p>\n","protected":false},"excerpt":{"rendered":"Podman Run the OpenClaw Gateway in a rootless Podman co […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-619","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/619","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=619"}],"version-history":[{"count":3,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/619\/revisions"}],"predecessor-version":[{"id":773,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/619\/revisions\/773"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=619"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=619"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=619"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}