English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Containers

Podman

在 rootless Podman 容器中執行 OpenClaw Gateway，並由你目前的非 root 使用者管理。

預期模型如下：

  • Podman 執行 Gateway 容器。
  • 主機上的 openclaw CLI 是控制平面。
  • 預設情況下，持久狀態位於主機的 ~/.openclaw 下。
  • 日常管理使用 openclaw --container <name> ...，而不是 sudo -u openclaw、podman exec 或獨立的服務使用者。

先決條件

  • rootless 模式的 Podman
  • 主機上已安裝 OpenClaw CLI
  • 選用： 如果你想要由 Quadlet 管理自動啟動，需使用 systemd --user
  • 選用： 只有在 headless 主機上想要執行 loginctl enable-linger "$(whoami)" 以維持開機持久性時，才需要 sudo

快速開始

  • 一次性設定

    從 repo 根目錄執行 ./scripts/podman/setup.sh。

  • 啟動 Gateway 容器

    使用 ./scripts/run-openclaw-podman.sh launch 啟動容器。

  • 在容器內執行 onboarding

    執行 ./scripts/run-openclaw-podman.sh launch setup，然後開啟 http://127.0.0.1:18789/。

  • 從主機 CLI 管理正在執行的容器

    設定 OPENCLAW_CONTAINER=openclaw，然後從主機使用一般的 openclaw 命令。

    • 設定詳細資訊：

    • ./scripts/podman/setup.sh 預設會在你的 rootless Podman 儲存區中建置 openclaw:local，如果你有設定 OPENCLAW_IMAGE / OPENCLAW_PODMAN_IMAGE，則會使用該映像。
    • 如果缺少 ~/.openclaw/openclaw.json，它會建立該檔案並設定 gateway.mode: "local"。
    • 如果缺少 ~/.openclaw/.env，它會建立該檔案並設定 OPENCLAW_GATEWAY_TOKEN。
    • 對於手動啟動，輔助工具只會從 ~/.openclaw/.env 讀取一小組 Podman 相關鍵的 allowlist，並將明確的 runtime env vars 傳給容器；它不會把完整 env 檔案交給 Podman。

    由 Quadlet 管理的設定：

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

    Quadlet 是僅限 Linux 的選項，因為它依賴 systemd 使用者服務。

    你也可以設定 OPENCLAW_PODMAN_QUADLET=1。

    選用的建置/設定 env vars：

    • OPENCLAW_IMAGE 或 OPENCLAW_PODMAN_IMAGE -- 使用既有/已拉取的映像，而不是建置 openclaw:local
    • OPENCLAW_DOCKER_APT_PACKAGES -- 在映像建置期間安裝額外的 apt 套件
    • OPENCLAW_EXTENSIONS -- 在建置時預先安裝 Plugin 相依項
    • OPENCLAW_INSTALL_BROWSER -- 為瀏覽器自動化預先安裝 Chromium 和 Xvfb（設為 1 以啟用）

    容器啟動：

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

    此指令碼會以你目前的 uid/gid 搭配 --userns=keep-id 啟動容器，並將你的 OpenClaw 狀態 bind-mount 到容器中。

    Onboarding：

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

    然後開啟 http://127.0.0.1:18789/，並使用 ~/.openclaw/.env 中的 token。

    主機 CLI 預設值：

    export OPENCLAW_CONTAINER=openclaw

    接著，像這樣的命令會自動在該容器內執行：

    openclaw dashboard --no-open
openclaw gateway status --deep   # includes extra service scan
openclaw doctor
openclaw channels login

    在 macOS 上，Podman machine 可能會讓瀏覽器對 Gateway 而言看起來不是本機。 如果控制 UI 在啟動後回報裝置驗證錯誤，請使用 Podman 與 Tailscale 中的 Tailscale 指引。

    Podman 與 Tailscale

    若要使用 HTTPS 或遠端瀏覽器存取，請遵循主要的 Tailscale 文件。

    Podman 專屬注意事項：

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

    請參閱：

    Systemd（Quadlet，選用）

    如果你執行了 ./scripts/podman/setup.sh --quadlet，設定會在以下位置安裝 Quadlet 檔案：

    ~/.config/containers/systemd/openclaw.container

    實用命令：

    • 啟動： 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/headless 主機上維持開機持久性，請為目前使用者啟用 lingering：

    sudo loginctl enable-linger "$(whoami)"

    設定、env 與儲存空間

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

    啟動指令碼和 Quadlet 會將主機狀態 bind-mount 到容器中：

    • OPENCLAW_CONFIG_DIR -> /home/node/.openclaw
    • OPENCLAW_WORKSPACE_DIR -> /home/node/.openclaw/workspace

    預設情況下，這些是主機目錄，而不是匿名容器狀態，因此 openclaw.json、每個 agent 的 auth-profiles.json、channel/provider 狀態、 sessions 和工作區會在容器替換後保留下來。 Podman 設定也會為已發布 Gateway 連接埠上的 127.0.0.1 和 localhost 種子設定 gateway.controlUi.allowedOrigins，讓本機 dashboard 可搭配容器的非 loopback 綁定運作。

    手動啟動器的實用 env vars：

    • OPENCLAW_PODMAN_CONTAINER -- 容器名稱（預設為 openclaw）
    • OPENCLAW_PODMAN_IMAGE / OPENCLAW_IMAGE -- 要執行的映像
    • OPENCLAW_PODMAN_GATEWAY_HOST_PORT -- 對應到容器 18789 的主機連接埠
    • OPENCLAW_PODMAN_BRIDGE_HOST_PORT -- 對應到容器 18790 的主機連接埠
    • OPENCLAW_PODMAN_PUBLISH_HOST -- 發布連接埠的主機介面；預設為 127.0.0.1
    • OPENCLAW_GATEWAY_BIND -- 容器內的 Gateway 綁定模式；預設為 lan
    • OPENCLAW_PODMAN_USERNS -- keep-id（預設）、auto 或 host

    手動啟動器會在最終確定容器/映像預設值之前讀取 ~/.openclaw/.env，因此你可以將這些值持久化在其中。

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

    Quadlet 注意事項：

    • 產生的 Quadlet 服務會刻意保持固定且強化的預設形狀：127.0.0.1 發布連接埠、容器內 --bind lan，以及 keep-id 使用者命名空間。
    • 它會固定 OPENCLAW_NO_RESPAWN=1、Restart=on-failure 和 TimeoutStartSec=300。
    • 它會發布 127.0.0.1:18789:18789（Gateway）和 127.0.0.1:18790:18790（bridge）。
    • 它會將 ~/.openclaw/.env 作為 runtime EnvironmentFile 讀取，用於 OPENCLAW_GATEWAY_TOKEN 等值，但不會使用手動啟動器的 Podman 專屬覆寫 allowlist。
    • 如果你需要自訂發布連接埠、發布主機或其他 container-run 旗標，請使用手動啟動器，或直接編輯 ~/.config/containers/systemd/openclaw.container，然後重新載入並重新啟動服務。

    實用命令

    • 容器記錄： podman logs -f openclaw
    • 停止容器： podman stop openclaw
    • 移除容器： podman rm -f openclaw
    • 從主機 CLI 開啟 dashboard URL： openclaw dashboard --no-open
    • 透過主機 CLI 取得健康狀態/狀態： openclaw gateway status --deep（RPC probe + 額外 服務掃描）

    疑難排解

    • 設定或工作區發生權限遭拒（EACCES）： 容器預設會使用 --userns=keep-id 和 --user <your uid>:<your gid> 執行。請確認主機設定/工作區路徑由你目前的使用者擁有。
    • Gateway 啟動遭阻擋（缺少 gateway.mode=local）： 請確認 ~/.openclaw/openclaw.json 存在，且設定了 gateway.mode="local"。若缺少此檔案，scripts/podman/setup.sh 會建立它。
    • 容器 CLI 命令命中錯誤目標： 明確使用 openclaw --container <name> ...，或在 shell 中匯出 OPENCLAW_CONTAINER=<name>。
    • openclaw update 搭配 --container 失敗： 這是預期行為。重新建置/拉取映像，然後重新啟動容器或 Quadlet 服務。
    • Quadlet 服務未啟動： 執行 systemctl --user daemon-reload，然後執行 systemctl --user start openclaw.service。在 headless 系統上，你可能也需要執行 sudo loginctl enable-linger "$(whoami)"。
    • SELinux 阻擋 bind mounts： 保留預設掛載行為；當 SELinux 為 enforcing 或 permissive 時，啟動器會在 Linux 上自動加入 :Z。

    相關內容