mem_limit · WASM 首輪等待 · allowedOrigins · compose exec 配對 · 可複製 compose
已依教學拉起 docker compose 的開發者在小記憶體 VPS 上最常遇到三類表象：容器立即結束 137、18789 長時間無回應、Control UI 顯示 non-loopback 或 Host 標頭相關錯誤。本文先給free -h 與 mem_limit、首輪 WASM 編譯 3～7 分鐘視窗的可執行清單，再用症狀 → docker logs 證據 → 修復動作表涵蓋 Exit 137、磁碟區權限與掛載錯位；接著用127.0.0.1 綁定、allowedOrigins 與反向代理決策表收斂 UI 錯誤；最後給出六步容器內裝置配對與上線前十項勾選。可與OpenClaw v2026.4 安裝與 Docker 強化長文、Gateway 安裝與 doctor 除錯清單、執行期三段式除錯交叉閱讀，把「能起容器」升級到「無人值守也穩定」。
OpenClaw Gateway 在容器內首次啟動時常見CPU 打滿但連接埠遲遲不開，多數屬於 WASM 沙箱編譯階段而非死結。與v2026.4 安裝長文中的資源建議對齊：宿主可用記憶體與 mem_limit 同時過緊時，Linux OOM 會直接給出 Exit 137，日誌裡未必來得及印出友善錯誤。
宿主側：在宿主機執行 free -h，確認可用記憶體是否長期低於約 1.5～2 GiB 的可用餘量；swap 為 0 時 137 更常見。
Compose 側：為服務設定 mem_limit: 2g 或更高，並避免與其他重服務同機搶記憶體。
首輪視窗：冷啟動預留 3～7 分鐘再判定失敗；期間可用 docker logs -f 觀察是否仍在編譯鏈。
健康檢查：healthcheck.start_period 建議至少 360s，避免 compose 在 WASM 完成前誤殺重啟。
誤判止損：不要在首輪視窗內連續 docker compose restart，否則每次都會重新觸發冷編譯峰值。
把以上五條寫進「VPS 上架 OpenClaw」Runbook 的第一頁，可顯著減少「教學一步步照做仍起不來」的工單量。更完整的 Gateway 分層除錯見執行期三段式長文。
下列表格刻意保持「先證據後動作」順序，便於把工單從「感覺閘道壞了」收斂到可重現欄位。與doctor 安裝除錯清單聯用時，可把表格列號寫進工單範本。
| 症狀 | docker logs / 宿主證據 | 優先修復動作 |
|---|---|---|
| 立即 137 | dmesg 出現 OOM；或日誌突然中斷 | 提高 mem_limit / 升級規格；減少同機競爭 |
| Permission denied 讀 workspace | 掛載目錄屬主為 root，容器內 node 使用者無法寫入 | chown 到容器 UID 或改用 user: 與磁碟區一致 |
| 設定寫了但不生效 | 宿主機路徑與 compose 磁碟區指向兩套 .openclaw | 統一為單一綁定路徑；重啟前 docker compose config 驗證 |
| DNS 偶發失敗 | 容器內 curl 模型端點逾時 | 依安裝長文檢查 Docker dns 與宿主解析 |
| 反覆重啟無新日誌 | 健康檢查過短觸發殺行程 | 放寬 start_period 與 retries |
Docker 除錯是否高效，取決於「137 是否先被證明為 OOM，而不是先被猜為應用程式 bug」。
若你把 Gateway 與始終在線的遠端 Mac 節點組合使用，請把「容器資源」和「節點 SLA」分成兩條驗收線：前者看 compose 與日誌，後者看供應商可用區與維護視窗。
在 VPS 上把 18789 暴露到公網是最常見的誤設定之一。安裝長文建議容器只綁定回環位址，由 Caddy 或 Nginx 在 443 終止 TLS。Control UI 若顯示 non-loopback 類錯誤，本質是瀏覽器來源與 Gateway 允許的 Origin 不一致，而不是「Docker 壞了」。
| 情境 | 監聽與反向代理 | 設定取向 |
|---|---|---|
| 僅本機 SSH 通道除錯 | 127.0.0.1:18789 | allowedOrigins 含 http://127.0.0.1:18789 |
| HTTPS 網域正式存取 | 反向代理到回環上游 | allowedOrigins 列出 https://您的網域；優先不用 Host 後援 |
| 臨時實驗室 | HTTP 內網 IP | 明確列出 IP 來源；縮小 CIDR；配好維護視窗後回收 |
| 除錯期「只想先看到 UI」 | 仍建議保留 TLS 外層 | 僅在理解風險下使用官方文件提到的 Host 標頭後援開關；事後必須回滾 |
{
"gateway": {
"mode": "local",
"controlUi": {
"allowedOrigins": ["https://openclaw.example.com"]
}
}
}
提示：改 openclaw.json 後觀察 docker compose restart 是否落在首輪 WASM 視窗內，避免與第二節的誤判疊加。
容器內執行 openclaw 時，HOME 與設定磁碟區必須與執行時程序一致，否則會出現「宿主機已 approve、容器裡仍 pending」。下列步驟預設服務名 openclaw，請依你的 compose 服務名替換。
確認服務名：docker compose ps 找到實際執行 Gateway 的容器。
進入相同環境：docker compose exec openclaw sh -lc 'pwd; echo $HOME; ls -la ~/.openclaw | head'
列出待配對請求：docker compose exec openclaw openclaw devices list
複製 Request ID：從 UI 或日誌拿到 ID 後執行 openclaw devices approve <id>。
校驗 API Key 可見性：若顯示 No API key found for provider，檢查 .env 是否被 compose 傳入容器，而非只寫在宿主機 shell 設定檔。
寫回工單欄位：把 compose 檔路徑、映像 tag、openclaw.json 摘要與 approve 指令貼進工單，便於下次複用。
注意：在宿主機直接跑 openclaw devices approve 但設定磁碟區只掛在容器內時，會出現「指令成功但 Gateway 仍不認」的假陰性。
下列三條為社群與生產環境常見的核對區間，請用你們宿主機的真實監控資料替換；寫進 README 可避免新人重複踩坑。
| 序號 | 上線前勾選 | 通過判準 |
|---|---|---|
| 01 | ports 僅綁定 127.0.0.1 | 公網直連 18789 關閉 |
| 02 | env_file 與金鑰注入路徑一致 | 容器內可讀到模型供應商 Key |
| 03 | mem_limit 與 swap 策略寫明 | 壓測一輪無 137 |
| 04 | healthcheck.start_period ≥ 360s | 首輪視窗內無重啟風暴 |
| 05 | openclaw.json 中 gateway.mode 為 local | 非法鍵已清理 |
| 06 | 反向代理 TLS 與 HSTS 策略 | 瀏覽器無混合內容警告 |
| 07 | allowedOrigins 涵蓋真實存取來源 | Control UI 無 non-loopback 錯誤 |
| 08 | 裝置配對在容器內走通 | devices list 為空或已 approve |
| 09 | 備份 .openclaw 路徑與版號 | 可在一頁 runbook 復原 |
| 10 | 與通道文件對齊 | IM 或 Webhook 側回呼可達 |
services:
openclaw:
image: ghcr.io/openclaw/openclaw:latest
restart: unless-stopped
mem_limit: 2g
ports:
- "127.0.0.1:18789:18789"
volumes:
- ${HOME}/.openclaw:/home/node/.openclaw
env_file:
- .env
healthcheck:
test: ["CMD", "curl", "-f", "http://127.0.0.1:18789/health"]
interval: 60s
timeout: 15s
retries: 5
start_period: 360s
在筆電上長期跑 Gateway 往往被睡眠、闔蓋與不穩定上行拖累；純靠家用寬頻也很難給出可驗收 SLA。相較之下，依週期計費的雲端 Mac mini 節點更適合承載「需要與 VPS 上 OpenClaw 協同、又要圖形或 Xcode 側操作」的混合工作流程。
常見誤區：把 0.0.0.0:18789 當作「方便除錯」；在公網 VPS 上等於把控制面暴露給掃描器。
若你希望Docker 閘道穩定在線，同時把重編譯或真機相關步驟放到可合約化的 macOS 環境，繼續維護自購固定資產往往在採購與多地同步上不占優。對需要7×24 可驗收節點與彈性規格的情境，VpsMesh 的 Mac mini 雲端租賃通常是更優解：把 VPS 上的 OpenClaw 與專用遠端 Mac 的分工寫進架構圖，再用租用價格與雲端訂購做容量評審，比口頭承諾更容易落地。遠端連通條目見雲端說明。
多數情況下應先對照宿主 dmesg 與 mem_limit 是否觸發 OOM；同時預留首輪 WASM 編譯視窗。資源基線可與OpenClaw v2026.4 安裝長文中的建議一併檢視。
優先在 openclaw.json 的 gateway.controlUi.allowedOrigins 列出真實 HTTPS 來源，並確認反向代理沒有把錯誤的 Host 傳到上游。更完整的安裝與 doctor 流程見Gateway 安裝除錯清單。