Podman

在由目前非 root 使用者管理的無 root 權限 Podman 容器中執行 OpenClaw 閘道。

運作模式：

• Podman 執行閘道容器。
• 主機上的 openclaw 命令列介面是控制平面。
• 持久化狀態預設儲存在主機的 ~/.openclaw 下。
• 日常管理使用 openclaw --container <name> ...，而非 sudo -u openclaw、podman exec 或獨立的服務使用者。

​

先決條件

• 以無 root 權限模式執行的 Podman
• 已安裝在主機上的 OpenClaw 命令列介面
• **選用：**若要使用 Quadlet 管理的自動啟動，需有 systemd --user
• **選用：**僅當你希望在無頭主機上使用 loginctl enable-linger "$(whoami)" 保持開機後持續執行時，才需要 sudo

​

快速開始

1. 一次性設定

   從儲存庫根目錄執行 ./scripts/podman/setup.sh。

   這會在無 root 權限的 Podman 儲存區中建置 openclaw:local（若有設定，則提取 OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE）；若 ~/.openclaw/openclaw.json 不存在，則使用 gateway.mode: "local" 建立；若 ~/.openclaw/.env 不存在，則使用產生的 OPENCLAW_GATEWAY_TOKEN 建立。

   選用的建置階段環境變數：

   變數	效果
   OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE	使用現有／已提取的映像檔，而非建置 openclaw:local
   OPENCLAW_IMAGE_APT_PACKAGES	在建置映像檔期間安裝額外的 apt 套件（也接受舊版 OPENCLAW_DOCKER_APT_PACKAGES）
   OPENCLAW_IMAGE_PIP_PACKAGES	在建置映像檔期間安裝額外的 Python 套件；請鎖定版本，並僅使用你信任的套件索引
   OPENCLAW_EXTENSIONS	編譯／封裝所選且受支援的外掛，並安裝其執行階段相依套件
   OPENCLAW_INSTALL_BROWSER	預先安裝 Chromium 和 Xvfb 以進行瀏覽器自動化（設為 1）

   若要改用 Quadlet 管理的設定（僅限 Linux + systemd 使用者服務）：

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

   或設定 OPENCLAW_PODMAN_QUADLET=1。

2. 啟動閘道容器

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

   使用 --userns=keep-id，以目前使用者的 uid/gid 啟動容器，並將 OpenClaw 狀態繫結掛載至容器。

3. 在容器內執行引導設定

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

   接著開啟 http://127.0.0.1:18789/，並使用 ~/.openclaw/.env 中的權杖。

   模型驗證：在設定期間使用由 OpenClaw 管理的驗證（Anthropic API 金鑰，或針對由 Codex 支援的 OpenAI，使用 OpenAI Codex 瀏覽器 OAuth／裝置代碼驗證）。Podman 啟動器不會將主機命令列介面的認證資訊目錄（例如 ~/.claude 或 ~/.codex）掛載到設定或閘道容器中。主機命令列介面既有的登入僅是在同一主機上的便利途徑；對於容器安裝，請將提供者驗證資料保存在由設定流程管理、已掛載的 ~/.openclaw 狀態中。

4. 從主機命令列介面管理執行中的容器

   export OPENCLAW_CONTAINER=openclaw
   

   之後，一般的 openclaw 命令會自動在該容器內執行：

   openclaw dashboard --no-open
   openclaw gateway status --deep   # 包含額外的服務掃描
   openclaw doctor
   openclaw channels login
   

   在 macOS 上，Podman machine 可能會讓瀏覽器對閘道而言看起來並非本機。如果啟動後控制介面回報裝置驗證錯誤，請採用 Podman 與 Tailscale 中的 Tailscale 指引。

手動啟動器只會從 ~/.openclaw/.env 讀取少量允許的 Podman 相關鍵，並將明確的執行階段環境變數傳遞給容器；不會將完整的環境檔交給 Podman。

​

Podman 與 Tailscale

如需 HTTPS 或遠端瀏覽器存取，請依照主要的 Tailscale 文件操作。

Podman 特有注意事項：

• 將 Podman 發布主機維持為 127.0.0.1。
• 優先使用由主機管理的 tailscale serve，而非 openclaw gateway --tailscale serve。
• 在 macOS 上，如果本機瀏覽器的裝置驗證內容不可靠，請使用 Tailscale 存取，而非臨時的本機通道因應方式。

請參閱 Tailscale 和控制介面。

​

Systemd（Quadlet，選用）

如果已執行 ./scripts/podman/setup.sh --quadlet，設定流程會在 ~/.config/containers/systemd/openclaw.container 安裝 Quadlet 檔案。

動作	命令
啟動	systemctl --user start openclaw.service
停止	systemctl --user stop openclaw.service
狀態	systemctl --user status openclaw.service
記錄	journalctl --user -u openclaw.service -f

編輯 Quadlet 檔案後：

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

若要在 SSH／無頭主機上保持開機後持續執行，請為目前使用者啟用 lingering：

sudo loginctl enable-linger "$(whoami)"

產生的 Quadlet 服務會維持固定且強化的預設形式：127.0.0.1 發布的連接埠（18789 閘道、18790 橋接器）、容器內的 --bind lan、keep-id 使用者命名空間、OPENCLAW_NO_RESPAWN=1、Restart=on-failure 和 TimeoutStartSec=300。它會將 ~/.openclaw/.env 作為執行階段 EnvironmentFile 讀取，以取得 OPENCLAW_GATEWAY_TOKEN 等值，但不會使用手動啟動器允許的 Podman 特有覆寫項目。若要自訂發布連接埠、發布主機或其他容器執行旗標，請改用手動啟動器，或直接編輯 ~/.config/containers/systemd/openclaw.container，然後重新載入並重新啟動服務。

​

設定、環境與儲存空間

• 設定目錄：~/.openclaw
• 工作區目錄：~/.openclaw/workspace
• 權杖檔案：~/.openclaw/.env
• 啟動輔助程式：./scripts/run-openclaw-podman.sh

啟動指令碼和 Quadlet 會將主機狀態繫結掛載至容器：OPENCLAW_CONFIG_DIR -> /home/node/.openclaw、OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace。預設情況下，這些是主機目錄，而非匿名容器狀態，因此 openclaw.json、各代理程式的 auth-profiles.json、頻道／提供者狀態、工作階段及工作區都能在替換容器後保留。設定流程也會為已發布閘道連接埠上的 127.0.0.1 和 localhost 植入 gateway.controlUi.allowedOrigins，讓本機儀表板能搭配容器的非迴路繫結運作。

手動啟動器的實用環境變數（請將其持久化至 ~/.openclaw/.env；啟動器會在最終確定容器／映像檔預設值前讀取該檔案）：

變數	預設值	效果
OPENCLAW_PODMAN_CONTAINER	openclaw	容器名稱
OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE	openclaw:local	要執行的映像檔
OPENCLAW_PODMAN_GATEWAY_HOST_PORT	18789	對應至容器 18789 的主機連接埠
OPENCLAW_PODMAN_BRIDGE_HOST_PORT	18790	對應至容器 18790 的主機連接埠
OPENCLAW_PODMAN_PUBLISH_HOST	127.0.0.1	發布連接埠所使用的主機介面
OPENCLAW_GATEWAY_BIND	lan	容器內的閘道繫結模式
OPENCLAW_PODMAN_USERNS	keep-id	keep-id、auto 或 host

如果使用非預設的 OPENCLAW_CONFIG_DIR 或 OPENCLAW_WORKSPACE_DIR，請為 ./scripts/podman/setup.sh 和後續的 ./scripts/run-openclaw-podman.sh launch 命令設定相同變數，因為儲存庫本機啟動器不會跨 shell 保留自訂路徑覆寫。

​

升級映像檔

重新建置或提取新映像檔後，請重新啟動容器或 Quadlet 服務。 閘道在新 OpenClaw 版本首次啟動時，會先執行安全的狀態和 外掛修復，再回報已就緒。

如果閘道結束而未進入就緒狀態，請使用相同的掛載狀態／設定， 針對相同映像檔執行一次 openclaw doctor --fix，然後以一般方式重新啟動 閘道：

OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$OPENCLAW_CONFIG_DIR/workspace}"
OPENCLAW_PODMAN_IMAGE="${OPENCLAW_PODMAN_IMAGE:-${OPENCLAW_IMAGE:-openclaw:local}}"

podman run --rm -it \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/node \
  -e NPM_CONFIG_CACHE=/home/node/.openclaw/.npm \
  -v "$OPENCLAW_CONFIG_DIR:/home/node/.openclaw:rw" \
  -v "$OPENCLAW_WORKSPACE_DIR:/home/node/.openclaw/workspace:rw" \
  "$OPENCLAW_PODMAN_IMAGE" \
  openclaw doctor --fix

在 SELinux 主機上，如果 Podman 封鎖對已掛載狀態的存取，請在兩個繫結掛載中加入 ,Z。

​

實用命令

• 容器記錄：podman logs -f openclaw
• 停止容器：podman stop openclaw
• 移除容器：podman rm -f openclaw
• 從主機命令列介面開啟儀表板網址：openclaw dashboard --no-open
• 透過主機命令列介面檢查健康狀況／狀態：openclaw gateway status --deep（RPC 探查 + 額外服務掃描）

​

疑難排解

• **設定或工作區發生權限遭拒（EACCES）：**容器預設使用 --userns=keep-id 和 --user <your uid>:<your gid> 執行。請確認主機設定／工作區路徑由目前使用者擁有。
• **閘道啟動遭封鎖（缺少 gateway.mode=local）：**請確認 ~/.openclaw/openclaw.json 存在並設定 gateway.mode="local"。若缺少，scripts/podman/setup.sh 會建立它。
• **映像檔更新後容器重新啟動：**執行升級映像檔中的一次性 openclaw doctor --fix 命令，然後再次啟動閘道。
• **容器命令列介面命令連到錯誤的目標：**明確使用 openclaw --container <name> ...，或在 shell 中匯出 OPENCLAW_CONTAINER=<name>。
• **openclaw update 失敗並顯示 --container：**這是預期行為。重新建置／提取映像檔，然後重新啟動容器或 Quadlet 服務。
• **Quadlet 服務未啟動：**執行 systemctl --user daemon-reload，接著執行 systemctl --user start openclaw.service。在無頭系統上，可能還需要 sudo loginctl enable-linger "$(whoami)"。
• **SELinux 封鎖繫結掛載：**維持預設掛載行為；當 SELinux 處於強制或寬容模式時，啟動器會在 Linux 上自動加入 :Z。

​

相關內容

• Docker
• 閘道背景程序
• 閘道疑難排解