Podman

在 rootless Podman 容器中執行 OpenClaw 閘道。使用與 Docker 相同的映像（從儲存庫 Dockerfile 建置）。

需求

Podman（rootless）
一次性設定需要 sudo（建立使用者、建置映像）

快速開始

1. 一次性設定（從儲存庫根目錄；建立使用者、建置映像、安裝啟動腳本）：

./setup-podman.sh

同時建立最小的 ~openclaw/.openclaw/openclaw.json（設定 gateway.mode="local"），讓閘道可以不經過精靈直接啟動。

預設情況下容器不會安裝為 systemd 服務，你需要手動啟動（見下方）。如需 production 設定的自動啟動與重啟，改為安裝 systemd Quadlet user service：

./setup-podman.sh --quadlet

（或設定 OPENCLAW_PODMAN_QUADLET=1；使用 --container 僅安裝容器和啟動腳本。）

建置時的選用環境變數（在執行 setup-podman.sh 前設定）：

OPENCLAW_DOCKER_APT_PACKAGES — 建置映像時安裝額外 apt 套件
OPENCLAW_EXTENSIONS — 預先安裝擴充功能相依套件（空白分隔，如 diagnostics-otel matrix）

2. 啟動閘道（手動，用於快速 smoke test）：

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

3. 設定精靈（如新增頻道或供應商）：

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

然後開啟 http://127.0.0.1:18789/ 並使用 ~openclaw/.openclaw/.env 中的 token（或設定時印出的值）。

Systemd（Quadlet，選用）

如果你執行了 ./setup-podman.sh --quadlet（或 OPENCLAW_PODMAN_QUADLET=1），會安裝 Podman Quadlet 作為 openclaw 使用者的 systemd user service。服務在設定結束時啟用並啟動。

啟動： sudo systemctl --machine openclaw@ --user start openclaw.service
停止： sudo systemctl --machine openclaw@ --user stop openclaw.service
狀態： sudo systemctl --machine openclaw@ --user status openclaw.service
日誌： sudo journalctl --machine openclaw@ --user -u openclaw.service -f

Quadlet 檔案位於 ~openclaw/.config/containers/systemd/openclaw.container。要變更連接埠或環境變數，編輯該檔案（或它引用的 .env），然後 sudo systemctl --machine openclaw@ --user daemon-reload 並重啟服務。開機時，如果 openclaw 啟用了 lingering（setup 在 loginctl 可用時會這樣做），服務會自動啟動。

要在未使用 quadlet 的初始設定之後新增 quadlet，重新執行：./setup-podman.sh --quadlet。

openclaw 使用者（非登入）

setup-podman.sh 建立專用系統使用者 openclaw：

Shell： nologin — 無互動登入；減少攻擊面。
Home： 如 /home/openclaw — 包含 ~/.openclaw（設定、workspace）和啟動腳本 run-openclaw-podman.sh。
Rootless Podman： 使用者需要 subuid 和 subgid 範圍。許多發行版在建立使用者時自動分配。如果 setup 印出警告，在 /etc/subuid 和 /etc/subgid 加入：
```
openclaw:100000:65536
```
然後以該使用者啟動閘道（如透過 cron 或 systemd）：
```
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh
sudo -u openclaw /home/openclaw/run-openclaw-podman.sh setup
```
設定： 僅 openclaw 和 root 可存取 /home/openclaw/.openclaw。編輯設定：使用 Control UI（閘道運行時），或 sudo -u openclaw $EDITOR /home/openclaw/.openclaw/openclaw.json。

環境與設定

Token： 儲存在 ~openclaw/.openclaw/.env 中的 OPENCLAW_GATEWAY_TOKEN。setup-podman.sh 和 run-openclaw-podman.sh 在缺少時產生（使用 openssl、python3 或 od）。
選用： 在 .env 中可設定供應商金鑰（如 GROQ_API_KEY、OLLAMA_API_KEY）和其他 OpenClaw 環境變數。
主機連接埠： 預設腳本映射 18789（閘道）和 18790（bridge）。透過 OPENCLAW_PODMAN_GATEWAY_HOST_PORT 和 OPENCLAW_PODMAN_BRIDGE_HOST_PORT 覆寫主機連接埠。
閘道綁定： 預設 run-openclaw-podman.sh 以 --bind loopback 啟動閘道，確保安全的本機存取。要暴露到 LAN，設定 OPENCLAW_GATEWAY_BIND=lan 並在 openclaw.json 中設定 gateway.controlUi.allowedOrigins。
路徑： 主機設定和 workspace 預設在 ~openclaw/.openclaw 和 ~openclaw/.openclaw/workspace。透過 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 覆寫主機路徑。

儲存模型

持久主機資料： OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 以 bind-mount 掛載到容器中，在主機上保留狀態。
暫時性 sandbox tmpfs： 啟用 agents.defaults.sandbox 時，sandbox 容器在 /tmp、/var/tmp 和 /run 掛載 tmpfs。這些路徑以記憶體為基礎，隨 sandbox 容器消失；最上層 Podman 容器設定不會加入自己的 tmpfs 掛載。
磁碟成長熱點： 注意 media/、agents/<agentId>/sessions/sessions.json、轉錄 JSONL 檔案、cron/runs/*.jsonl 和 /tmp/openclaw/（或你設定的 logging.file）下的輪轉日誌。

setup-podman.sh 現在將映像 tar 暫存在私有暫存目錄中，並在設定期間印出選擇的基礎目錄。非 root 執行時僅在該基礎安全可用時接受 TMPDIR；否則 fallback 到 /var/tmp，再到 /tmp。

常用指令

日誌： Quadlet：sudo journalctl --machine openclaw@ --user -u openclaw.service -f。腳本：sudo -u openclaw podman logs -f openclaw
停止： Quadlet：sudo systemctl --machine openclaw@ --user stop openclaw.service。腳本：sudo -u openclaw podman stop openclaw
再次啟動： Quadlet：sudo systemctl --machine openclaw@ --user start openclaw.service。腳本：重新執行啟動腳本或 podman start openclaw
移除容器： sudo -u openclaw podman rm -f openclaw — 主機上的設定和 workspace 會保留

疑難排解

Permission denied（EACCES）設定或 auth-profiles： 容器預設使用 --userns=keep-id，以執行腳本的主機使用者相同 uid/gid 執行。確認 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 由該使用者擁有。
閘道啟動被封鎖（缺少 gateway.mode=local）： 確認 ~openclaw/.openclaw/openclaw.json 存在且設定了 gateway.mode="local"。setup-podman.sh 在缺少時會建立此檔案。
Rootless Podman 對 openclaw 使用者失敗： 檢查 /etc/subuid 和 /etc/subgid 是否有 openclaw 的行（如 openclaw:100000:65536）。缺少則新增並重啟。
容器名稱已使用： 啟動腳本使用 podman run --replace，會替換現有容器。手動清理：podman rm -f openclaw。
以 openclaw 身分執行時找不到腳本： 確認已執行 setup-podman.sh，且 run-openclaw-podman.sh 已複製到 openclaw 的 home（如 /home/openclaw/run-openclaw-podman.sh）。
Quadlet 服務找不到或無法啟動： 編輯 .container 檔案後執行 sudo systemctl --machine openclaw@ --user daemon-reload。Quadlet 需要 cgroups v2：podman info --format '{{.Host.CgroupsVersion}}' 應顯示 2。

選用：以自己的使用者執行

要以一般使用者執行閘道（不建立專用 openclaw 使用者）：建置映像，建立含有 OPENCLAW_GATEWAY_TOKEN 的 ~/.openclaw/.env，並以 --userns=keep-id 和掛載到 ~/.openclaw 的方式執行容器。啟動腳本設計為 openclaw 使用者流程；對於單使用者設定，你可以手動執行腳本中的 podman run 指令，將設定和 workspace 指向你的 home。大多數使用者建議：使用 setup-podman.sh 並以 openclaw 使用者執行，以隔離設定和程序。