本網站為獨立社群專案，與 OpenClaw 官方無任何關聯。內容僅供參考。 了解更多

翻譯文件

本頁為社群翻譯版本，可能與官方最新內容有出入。 查看官方英文原文 →

Podman

使用無 root 權限的 Podman 容器部署 OpenClaw Gateway 的指南。

在無 root 權限的 Podman 容器中執行 OpenClaw Gateway。使用與 Docker 相同的映像檔（從儲存庫的 Dockerfile 建置）。

需求

  • Podman（rootless 模式）
  • 一次性設定需要 Sudo 權限（建立使用者、建置映像檔）

快速開始

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

./setup-podman.sh

這也會建立最小化的 ~openclaw/.openclaw/openclaw.json（設定 gateway.mode="local"），讓 Gateway 可以不需要執行精靈即可啟動。

預設情況下容器不會安裝為 systemd 服務，您需要手動啟動（見下方）。若需要生產環境的自動啟動和重新啟動，請改為安裝為 systemd Quadlet 使用者服務：

./setup-podman.sh --quadlet

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

2. 啟動 Gateway（手動，用於快速測試）：

./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 單元，讓 Gateway 以 openclaw 使用者的 systemd 使用者服務執行。服務會在設定結束時啟用並啟動。

  • 啟動： 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（設定時若 loginctl 可用會自動執行），服務會自動啟動。

若要在未使用 Quadlet 的初始設定後加入 Quadlet，請重新執行：./setup-podman.sh --quadlet。

openclaw 使用者（non-login）

setup-podman.sh 會建立一個專用的系統使用者 openclaw：

  • Shell： nologin — 無法互動式登入；減少攻擊面。
  • Home： 例如 /home/openclaw — 存放 ~/.openclaw（設定、工作區）和啟動腳本 run-openclaw-podman.sh。
  • Rootless Podman： 使用者必須具有 subuid 和 subgid 範圍。許多發行版在建立使用者時會自動分配。若設定列印警告，請在 /etc/subuid 和 /etc/subgid 中新增行：
openclaw:100000:65536

然後以該使用者啟動 Gateway（例如透過 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。若要編輯設定：在 Gateway 執行時使用控制介面，或使用 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（Gateway）和 18790（bridge）。啟動時可透過 OPENCLAW_PODMAN_GATEWAY_HOST_PORT 和 OPENCLAW_PODMAN_BRIDGE_HOST_PORT 覆寫主機連接埠映射。
  • Gateway 綁定： 預設情況下，run-openclaw-podman.sh 使用 --bind loopback 啟動 Gateway 以確保安全的本地存取。若要在區域網路上公開，設定 OPENCLAW_GATEWAY_BIND=lan 並在 openclaw.json 中設定 gateway.controlUi.allowedOrigins（或明確啟用 host-header 回退）。
  • 路徑： 主機設定和工作區預設為 ~openclaw/.openclaw 和 ~openclaw/.openclaw/workspace。透過 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 覆寫啟動腳本使用的主機路徑。

常用指令

  • 日誌： 使用 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 — 主機上的設定和工作區會保留

疑難排解

  • 設定或 auth-profiles 的權限拒絕（EACCES）： 容器預設使用 --userns=keep-id 並以與執行腳本的主機使用者相同的 uid/gid 執行。請確保您的主機 OPENCLAW_CONFIG_DIR 和 OPENCLAW_WORKSPACE_DIR 由該使用者擁有。
  • Gateway 啟動被阻止（缺少 gateway.mode=local）： 確保 ~openclaw/.openclaw/openclaw.json 存在並設定 gateway.mode="local"。setup-podman.sh 會在缺少時建立此檔案。
  • openclaw 使用者的 Rootless Podman 失敗： 檢查 /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。

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

若要以您的一般使用者執行 Gateway（不使用專用的 openclaw 使用者）：建置映像檔，建立 ~/.openclaw/.env 並設定 OPENCLAW_GATEWAY_TOKEN，然後使用 --userns=keep-id 和指向您 ~/.openclaw 的掛載來執行容器。啟動腳本是為 openclaw 使用者流程設計的；對於單一使用者設定，您可以手動執行腳本中的 podman run 指令，將設定和工作區指向您的 home 目錄。建議大多數使用者使用 setup-podman.sh 並以 openclaw 使用者執行，以隔離設定和程序。