2026 OpenClaw 無圖形 Linux Docker：onboard 掛起、pending.json 與 dashboard --no-open 的 headless 驗證 Runbook

約 16 分鐘閱讀 · MACCOME

如果你在無桌面、無瀏覽器的 Linux 雲主機 / VPS 上只用 Docker 跑 OpenClaw，卻被嚮導或 onboard 卡在 pending、日誌提示要打開本地瀏覽器、或 dashboard 在無 DISPLAY 環境下直接失敗，本文給你一套可寫進變更單的 headless 驗收階梯：先凍結「單軌 compose + 單一 TOKEN 真源」，再用 dashboard --no-open、gateway status/probe、結構化日誌替代「肉眼看 Control UI」。與站內三平臺安裝總覽、Windows Docker 排錯、Linux systemd+Tunnel 非 Docker、Compose 配對 1006/1008分工；生產常駐可並聯SSH 轉發六國獨佔 Gateway。

無圖形 Linux Docker 上 OpenClaw 最常見的六類「假故障」

  1. 把「必須彈瀏覽器」寫進驗收標準：headless 主機上失敗的不是 Gateway，而是驗收腳本；應改用 CLI 與日誌契約。
  2. onboard 與 compose 雙軌並行：兩個入口各寫一半 pending.json / 環境變量，表現為隨機 pending 或 TOKEN 漂移（與 Compose 配對文 的症狀同源）。
  3. 未設置 silent 或等價 headless 開關：嚮導等待交互，進程並不退出，監控卻顯示「healthy」。
  4. cgroup / 存儲驅動與 ulimit 默認值：小規格 VPS 上 Gateway 子進程 OOM 或 fd 耗盡，被誤報為 WebSocket 1006。
  5. 公司出口 MITM 或透明代理：鏡像層拉取成功但 WebSocket 握手被改寫，需對照官方 TLS 要求與內網根證書信任鏈。
  6. 把 Linux 當 Windows 抄作業：WSL2、Docker Desktop 與 Linux engine 的前置條件完全不同；應回到 doctor 分診 的「先引擎後業務」順序。

無圖形的價值是攻擊面更小、可自動化更強；若驗收仍依賴人工點瀏覽器，只是把圖形桌面的混亂換成 SSH 裡的混亂。與Docker 生產 Runbook同讀時，請把「鏡像版本、compose 哈希、TOKEN 注入方式」寫進同一工單，否則 headless 只會放大配置漂移。

若團隊同時維護 systemd 裸跑 與 Docker 兩套拓撲，必須在 README 標明默認真源：哪套用於 CI 鏡像集成測試，哪套用於生產；混用主機是最難排障的一類。

維度 無圖形 Docker（本稿） Linux systemd + Tunnel（非容器）
復現與升級 鏡像 tag + compose 文件可版本化，回滾快 依賴發行版包與單元文件，定製深但鏡像化弱
headless 驗收 天然適合 --no-open 與容器日誌驅動 journald + curl 探針為主，路徑與 Docker 不同
網絡命名空間 1006/1008 多與 bridge / publish 組合相關 主機網絡棧，問題常落在 Tunnel 與本地 bind
與遠程常駐 Mac 可把 Gateway 遷到獨佔機，本機只跑 agent 側 CLI 同樣可遷；差異在運維習慣而非結論
典型誤用 在 CI 與生產 compose 分叉卻不打標籤 把 Tunnel 與 Docker 網關混在同一主機雙啟
info

提示：社區中常見「將 pending.json 中 silent 設為 true 以跳過阻塞式嚮導」的做法，在寫入流水線前必須與當前 OpenClaw 版本文檔核對欄位名與語義；版本升級後應做一次回歸，避免 silent 失效導致 silent hang。

六步 headless Runbook：從「能 pull 鏡像」到「gateway probe 綠」

  1. 凍結單軌入口：選定只通過 compose 或只通過官方 docker-setup 腳本之一完成安裝；另一路徑僅作只讀對照。
  2. 校驗引擎與磁碟：docker info、數據根分區空閒、ulimit -n；小規格 VPS 先加 swap 或限並發再談功能。
  3. 處理 onboard / pending：按文檔設置 headless 相關開關；變更後列印 pending 文件哈希進 CI 日誌以便審計。
  4. 拉起 Gateway 並只走 CLI 驗證：openclaw gateway status → openclaw gateway probe（若版本提供）→ openclaw dashboard --no-open；禁止以「我瀏覽器裡看見了」作為唯一通過條件。
  5. 跑 doctor 並登記豁免：與 安裝後 doctor 分診 對齊欄位；豁免項必須帶到期日與負責人。
  6. 寫回歸用例：容器重建後 10 分鐘內應重複通過同一腳本；失敗則自動打開 incident 並附上 compose 哈希與鏡像 digest。
bash
# 示例：僅驗證 CLI 與 Gateway（佔位符按你們 compose 服務名調整）
docker compose ps
docker compose logs -f --tail=200 openclaw-gateway

openclaw gateway status || true
openclaw dashboard --no-open || true
openclaw doctor --yes || true

三條應寫進 SLO 或值班手冊的量化口徑（閾值按機型替換）

  • 冷啟動到首次 probe 成功（G2P）：從 compose up -d 到首次 gateway probe 成功的中位數分鐘數；若周環比上升 >40% 且鏡像 tag 未變，優先查磁碟與 fd，而不是先升級模型。
  • 無圖形主機上「瀏覽器依賴」步驟計數：目標為 0；任何新增步驟若要求 DISPLAY，應退回產品化改造或拆到僅用於開發檔的 compose profile。
  • 雙 Gateway 事件：統計同一主機 18789 上雙監聽或 TOKEN 雙源告警次數；連續兩周 >0 即應觸發架構復盤（與 TOKEN 雙源文 對齊）。

為什麼「強行給伺服器裝輕量桌面 + VNC」或「無限重試 onboard 直到運氣變好」在 2026 年不划算

輕量桌面增加補丁面與登錄會話審計成本；VNC 若暴露到公網更是典型高風險配置。無限重試 onboard 只會把「欄位漂移」藏進人肉操作裡，無法寫進自動化。

當你需要7×24、可審計、與團隊 CI 節奏一致的 Gateway，而 headless Linux 更適合做邊緣試跑或短期 PoC時，把權威 Gateway 落在獨佔 Apple Silicon 遠程 Mac、用文檔化 SSH 轉發或尾網收口，往往比在小內存 VPS 上與 cgroup 搏鬥更省總擁有成本——MACCOME在六國提供 Mac mini（M4 / M4 Pro）與彈性租期，可與本站多篇 OpenClaw 與遠程 Mac Runbook 串聯設計；公開檔位請先對照節點與租期指南再定拓撲。

收束：headless 驗收清單應成為 DOCKER_GATEWAY.md 的一節，而不是口頭傳說

交付物建議包含：compose 文件版本、鏡像 digest、silent/pending 策略、CLI 驗證命令輸出樣例、禁止瀏覽器依賴的聲明。任何不能在第二臺無圖形機上復現的步驟，都應視為文檔未完成。

與 Windows Docker 排錯 對照時，記住：驗證階梯一致，宿主與引擎不同；不要混用 Docker Desktop 與 Linux engine 的日誌路徑假設。

常見問題

無圖形伺服器上 onboard 一直 pending，一定要裝桌面嗎？

多數不需要：用 headless 開關與 CLI 驗收替代瀏覽器；並與官方文檔核對 pending.json 欄位。若計劃上生產常駐 Gateway，可先閱讀租賃價格說明與幫助中心了解獨佔節點選項。

Linux Docker 與 systemd+Tunnel 能混在同一臺機嗎？

技術上可並存，但極易出現雙 Gateway / 雙 TOKEN 真源；除非分環境檔位並寫清默認真源，否則不建議。詳見 Tunnel Runbook 與 Compose 配對文的分工說明。