在 Podman 中部署 OpenClaw：無 root 權限快速安裝指南

在伺服器上部署服務時，權限管理往往是最讓人頭痛的一環。如果你不想給 Docker 太高的權限，或者希望在一個完全隔離的環境下執行你的 Gateway，那麼使用 rootless 的 Podman 會是一個聰明的選擇。

這篇文章會教你如何透過 Podman 來執行 OpenClaw，讓你的 Gateway 跑得既安全又輕鬆。我們會使用與 Docker 相同的 Image（基於 repo 中的 Dockerfile 構建）。

需求

Podman (rootless)
用於一次性設定的 Sudo 權限（建立使用者、構建 Image）

快速開始

1. 一次性設定（在 repo 根目錄執行；這會建立使用者、構建 Image 並安裝啟動腳本）：

./setup-podman.sh

這也會建立一個基本的 ~openclaw/.openclaw/openclaw.json（並將 gateway.mode 設定為 "local"），讓 Gateway 可以在不執行引導精靈的情況下直接啟動。

預設情況下，容器不會安裝為 systemd 服務，你需要手動啟動它（見下文）。如果你需要自動啟動與重啟的生產環境配置，請改為安裝為 systemd Quadlet 使用者服務：

./setup-podman.sh --quadlet

（或者設定環境變數 OPENCLAW_PODMAN_QUADLET=1；使用 --container 參數則僅安裝容器與啟動腳本。）

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

OPENCLAW_DOCKER_APT_PACKAGES — 在構建 Image 期間安裝額外的 apt 套件。
OPENCLAW_EXTENSIONS — 預先安裝擴充功能依賴（以空格分隔，例如 diagnostics-otel matrix）。

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

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

3. 引導設定精靈（例如用於新增 Channel 或 Provider）：

./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，請重新執行：./setup-podman.sh --quadlet。

openclaw 使用者 (非登入型)

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

Shell： nologin — 不允許互動式登入，減少被攻擊的風險。
家目錄： 例如 /home/openclaw — 存放 ~/.openclaw（配置、工作區）以及啟動腳本 run-openclaw-podman.sh。
Rootless Podman： 該使用者必須擁有 subuid 與 subgid 範圍。許多發行版在建立使用者時會自動分配。如果設定時出現警告，請在 /etc/subuid 與 /etc/subgid 中加入：
```
openclaw:100000:65536
```
接著以該使用者身份啟動 Gateway（例如透過 cron 或 systemd）：
Terminal window
```
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 執行後使用 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 檔案中設定 Provider 金鑰（例如 GROQ_API_KEY, OLLAMA_API_KEY）與其他 OpenClaw 環境變數。
連接埠與綁定： 預設對應 18789 (Gateway) 與 18790 (Bridge)。你可以透過 OPENCLAW_PODMAN_GATEWAY_HOST_PORT 覆蓋連接埠，或將 OPENCLAW_GATEWAY_BIND 設定為 lan 以開放區域網路存取。
路徑設定： 主機配置與工作區預設為 ~openclaw/.openclaw 與 ~openclaw/.openclaw/workspace。你可以透過 OPENCLAW_CONFIG_DIR 與 OPENCLAW_WORKSPACE_DIR 來自定義路徑。

儲存模型

持久化資料： OPENCLAW_CONFIG_DIR 與 OPENCLAW_WORKSPACE_DIR 會掛載到容器中，確保資料保存在主機上。
暫時性沙盒： 如果你啟用了 agents.defaults.sandbox，工具沙盒容器會將 tmpfs 掛載到 /tmp 等路徑，這些資料會隨容器消失。
磁碟空間監控： 請留意 media/、工作階段 JSON 檔案、逐字稿 JSONL 以及 /tmp/openclaw/ 下的滾動日誌檔案。
暫存處理： setup-podman.sh 會將 Image 暫存在私有臨時目錄中，並在設定期間顯示該路徑，確保安裝過程安全且不被阻擋。

常用指令

查看日誌： 使用 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 — 這會保留主機上的配置與工作區資料。

疑難排解

配置或權限錯誤 (EACCES)： 容器預設使用 --userns=keep-id。請確保主機上的 OPENCLAW_CONFIG_DIR 擁有者與執行腳本的使用者一致。
Gateway 啟動被阻擋： 檢查 ~openclaw/.openclaw/openclaw.json 是否存在且 gateway.mode 已設為 "local"。
Rootless Podman 失敗： 檢查 /etc/subuid 與 /etc/subgid 是否包含 openclaw 的設定。
容器名稱已被佔用： 啟動腳本使用 podman run --replace，會自動替換舊容器。你也可以手動執行 podman rm -f openclaw 清理。
找不到腳本： 確保已執行過 setup-podman.sh，讓腳本被正確複製到 openclaw 的家目錄。
Quadlet 服務問題： 修改 .container 檔案後務必執行 daemon-reload。此外，請確認系統支援 cgroups v2。

選填：以你自己的使用者身份執行

如果你不想建立專用的 openclaw 使用者，也可以用一般使用者執行：構建 Image，建立包含 OPENCLAW_GATEWAY_TOKEN 的 ~/.openclaw/.env，並使用 --userns=keep-id 參數手動執行 podman run。不過為了安全與隔離性，我們仍然推薦使用 setup-podman.sh 的預設流程。

想要更輕鬆地完成設定嗎？試試我們的 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。