若您要在本機或 VPS 上跑 OpenClaw 閘道並接到業務工作流，或在 遠端 Mac（如 MacCompute 類託管環境）穩定執行長時 Agent／批次腳本，本文依 OpenClaw 官方 Docker 文件（2026 年公開版本）整理可複現指令、控制埠與綁定模式、Token／HTTPS 反代與常見報錯對照。站內可連 首頁、筆記與指南列表；計費與下單見 定價。
2026 年 OpenClaw 部署背景與典型使用場景
OpenClaw 將對話式 Agent、工具執行與閘道服務整合；官方將 Docker 定位為「可拋式隔離環境」或「無需在主機本機安裝完整工具鏈」時的選項，並提醒 Agent 沙箱亦可獨立使用 Docker，未必整個閘道都要進容器。常見場景包括：團隊在固定 VPS上長駐閘道、以反向代理＋TLS對外開放控制介面、以及在 Apple Silicon 遠端主機上與 Xcode／腳本管線並存，離峰跑批次或通知。
環境與前置檢查清單（可勾選）
部署前請逐項確認，避免卡在建置或網路暴露。
- Docker Engine／Desktop 與 Docker Compose v2 已安裝且 docker compose version 正常。
- 記憶體：文件建議映像建置至少約 2 GB RAM（1 GB 主機可能於 pnpm install 階段 OOM，exit 137）。
- 磁碟：預留映像、日誌與工作區空間；持久化目錄含主機上的 ~/.openclaw 與 ~/.openclaw/workspace（Compose 綁載）。
- 網域與憑證：若對外公開控制介面，預先準備 FQDN 與 ACME（Let’s Encrypt）或既有 TLS 憑證。
- 防火牆：僅對管理來源開放反代埠；並閱讀官方 Security hardening for network exposure（含 Docker DOCKER-USER 策略）。
可複現安裝路徑：全域安裝與 Docker／docker-setup 對照
官方文件區分「本機一般安裝流程（最快開發迴圈）」與「容器化閘道」。下列為實務對照（細節以官方文件為準）。
| 路徑 | 適用情境 | 要點與指令骨架 |
|---|---|---|
| 本機／伺服器一般安裝 | 個人開發機、要最短迭代 | 依 Installer 文件於主機安裝；不使用完整 Docker 閘道堆疊。 |
| docker-setup.sh（建議） | VPS、要可重現的 Compose 堆疊 | git clone https://github.com/openclaw/openclaw.git && cd openclaw && ./docker-setup.sh；可選 export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" 改為拉取 ghcr.io/openclaw/openclaw 映像。 |
| 手動 Compose | 需細控建置參數或 CI | docker build -t openclaw:local -f Dockerfile . → docker compose run --rm openclaw-cli onboard → docker compose up -d openclaw-gateway；自動化加 -T。 |
完成後，文件載明於瀏覽器開啟 http://127.0.0.1:18789/，並將寫入 .env 的閘道 Token貼至控制介面設定。探測可用：
curl -fsS http://127.0.0.1:18789/healthz 與 curl -fsS http://127.0.0.1:18789/readyz。
最小安全配置：監聽位址、Token、沙箱與出站策略
- Bind 模式：設定 gateway.bind 時使用 lan／loopback 等模式值，文件明確說明勿填 0.0.0.0、localhost 這類主機別名。Docker 情境下預設常與 OPENCLAW_GATEWAY_BIND=lan 搭配，讓主機經發布埠連到閘道。
- Token 與配對：控制介面需 Token；若出現未授權或 WebSocket 配對問題，可用 docker compose run --rm openclaw-cli dashboard --no-open 與 devices approve 流程處理。
- 沙箱：可選 export OPENCLAW_SANDBOX=1 再跑 docker-setup.sh；文件說明沙箱映像與 docker.sock 掛載條件，失敗時會將沙箱模式重置以免殘留錯誤設定。
- 工具／網路：預設沙箱 Docker 網路常為 none（無出站），工具允許／拒絕清單以 deny 為優先；對外業務整合應「顯式開權限」而非全開。
- CLI 與閘道共用網路命名空間：文件提醒 openclaw-cli 服務使用 network_mode: service:openclaw-gateway，迴路內信任邊界與本機隔離不同，高風險環境應評估改由獨立主機執行 CLI。
Nginx／Caddy 反向代理與 HTTPS 落地步驟
對外請勿直接裸奔容器埠；標準做法是本機只聽 127.0.0.1:18789，由反代終止 TLS 並加存取控制。
- 為管理介面準備專用子網域，取得憑證（Caddy 自動 ACME 或 Nginx＋certbot）。
- 反代上游設為 http://127.0.0.1:18789，開啟 WebSocket 所需標頭（Upgrade、Connection）。
- 加IP 允許清單、基本驗證或零信任接入（與 Token 機制疊加防禦深度）。
- 釋出後再以 curl -fsS https://您的網域/healthz 驗證鏈路。
具體 server {}／Caddyfile 可依您既有基線範本調整；重點是 TLS、WS 與來源限制三者缺一不可。
問題排查矩陣：埠、權限、映像與閘道連線
| 現象 | 優先檢查 | 建議動作 |
|---|---|---|
| 18789 連不上 | 埠占用、compose 未起、防火牆 | docker compose ps；主機上 lsof -i :18789（macOS）或對應工具；確認只由反代或本機存取。 |
| 建置 exit 137／OOM | 記憶體不足 | 拉高 Docker 可用 RAM 或改用 OPENCLAW_IMAGE 跳過本機 build。 |
| EACCES 於設定目錄 | 映像內使用者 uid 1000 與掛載檔權限 | Linux 主機對綁載目錄執行 chown -R 1000:1000（見文件範例）。 |
| CLI 顯示 ws://172.x 或反覆配對失敗 | gateway.mode／gateway.bind | 依文件執行 openclaw-cli config set gateway.mode local、gateway.bind lan 後重試裝置指令。 |
| unhealthy 容器 | 內建 HEALTHCHECK 打 /healthz | 檢視日誌與 readyz 是否 503（受管理通道連線影響）。 |
業務實例：在遠端 Mac 上串聯建置、腳本與通知
在 MacCompute 類遠端 Mac上，建議將「長時執行」與「可觀測性」寫進同一套管線：
- SSH 登入後啟用 Docker（Desktop 或團隊核准的守護行程），複製 OpenClaw 儲存庫並跑 ./docker-setup.sh（或預先拉好 ghcr.io/openclaw/openclaw:latest）。
- 以 launchd 或 cron 在開機後執行 docker compose up -d（工作目錄指向 repo 根），並將 log 導向檔案供集中收集。
- 建置／腳本：Agent 或 CI 觸發 shell 腳本完成編譯、測試報告產出；產物寫入掛載的 workspace 目錄。
- 通知：腳本尾端以 curl 打 Slack／企業微信 Webhook，或上傳報告至物件儲存；條件式告警避免刷屏。
- 驗收：從外部僅能經 HTTPS 反代連到 UI；內部以 gateway probe 與健康 URL 做啟動判斷。
預期結果：閘道常駐、UI 可管理、腳本可無人值守重跑，且敏感介面不直接暴露在公網埠掃描下。
FAQ 與排錯清單
Q：能否只用 Docker 映像而不 clone 儲存庫？
A：OPENCLAW_IMAGE 可跳過本機 build，但文件說明 docker-setup.sh 仍須在含 docker-compose.yml 的儲存庫根目錄執行。
Q：無頭環境 OAuth 卡住？
A：文件提及 Codex OAuth 回呼可能落在 http://127.0.0.1:1455/auth/callback；Docker 下可改以複製完整 redirect URL 回填精靈。
Q：與 Mac 租用平台如何銜接？
A：先完成 SSH／VNC 首次連線 與金鑰管理，再佈署 Docker 堆疊；長時任務選月租或較高記憶體檔位較穩。