AI / 自動化 2026年4月25日

2026-04-25 在租用的無頭雲端 Mac 上，OpenClaw doctor、CLI 設定與模型白名單：升級後排查

MacXCode 技術團隊 2026年4月25日 約 17 分鐘閱讀

在 香港 / 日本 / 韓國 / 新加坡 / 美國 租用的 Mac mini M4 上，您通常 先 SSH，只有必須圖形介面時才用 VNC。這正是 OpenClaw 針對的失敗模式：長期存活的 gateway、JSON 形設定、以及 npm 快速迭代——您的 git diff 沒動，生產仍可能因依賴收緊校驗、遷移預設值或 模型白名單 變嚴而掛掉。這份 2026-04-25 手冊是排查路徑，不重複 出站與 DNS 或 首次安裝與守護。它串聯：openclaw doctor（與可選的 --fix）、CLI 管理 的鍵與手改檔案的分工、如何證明 LaunchAgent 讀到的 ~/.openclaw，以及如何避免「在互動式 ssh -t shell 裡能跑、在 launchd 下掛掉」的經典坑。當 doctor 提示陳舊原生模組或重複 gateway 時，把 npm 與雙重重啟 寫進回滾故事。

為何升級會在無頭 Mac 上冒出「幽靈」問題

存在三套環境時鐘：您的筆記型電腦（PATH 豐富、.zshrc、HTTPS_PROXY 來自您忘掉的 VPN）、自動化用的 類 CI SSH 工作階段、以及面對 守護行程 的 launchd 環境（這才是唯一應生效的那套）。在 npm -g 或帶標籤的 OpenClaw 發佈之後，模式校驗可能開始拒絕您四月以來一直帶著的鍵；gateway 可能寫出 第二份 PID 檔案；或以往隱式的工具呼叫需要顯式 審批/能力 且只在 verbose 日誌裡出現。把 就緒探針 當作對 127.0.0.1:18789 監聽埠的快速篩子，而不是「整套人格設定仍一致」的證書——就緒必要，但不足以保證「各通道聊天都通」。

前 90 秒：先執行 openclaw doctor（與 --fix）

先做非破壞檢查，再做可回滾的修復：openclaw status --all 列印版本、PID、監聽埠與部件概覽；openclaw doctor 校驗模式、發現陳舊或衝突鍵、（視版本）引導到受支援路徑；openclaw doctor --fix 在 CLI 能安全清理明顯殘留時使用——例如崩潰後過期的 ~/.openclaw/gateway.pid、或遷移器可重寫的已棄用子鍵。在內部 wiki 中固化 順序：先 kill -9 再 doctor 與先 openclaw gateway stop 再 doctor 輸出會不同。若 doctor 報外掛載入失敗，請與生態裡常提到的 WebSocket 1006 類錯誤對照；不要看到「另有 gateway 在監聽」就停，還要排查舊裝遺留的 clawdbot 類程序，社群已多次記錄。

單一真相：CLI config 與磁碟上的 JSON

更傾向用 openclaw config set <key> <value> 與 openclaw config get <key>（隨版本而異的表面）來改設定——很多團隊因手改 ~/.openclaw/openclaw.json 多一個逗、或 UI 曾寫入而 CLI 不再序列化的鍵而產生模式漂移。手改後務必再跑 doctor。熱重載覆蓋許多 agent/模型/提示 值，但 gateway.port 與 gateway.bind 仍值得按上游熱重載約定做 完整 openclaw gateway restart，如同您只改了 nginx + Webhook 疊的一半時。金鑰放在 ~/.openclaw/.env，透過已為 launchd 中的 API 金鑰 使用的同一套 EnvironmentVariables 繼承，而不是您在就職時 cat >> ~/.zshrc 寫的一次性 export。

模型白名單：「不允許」常是政策，不是故障

當廠商重新命名模型串，而您的技能仍引用 anthropic/claude-3-5-sonnet-latest、gateway 只放行固定清單時，錯誤會像憑證問題。檢查有效白名單：openclaw config get agents.defaults.models（或您版本暴露的最近似項），讓字串與目標目錄 完全一致——大小寫、廠商前綴、插槽（主/備）都重要。與 出站 文互參：若錯誤在 TLS 與 HTTP/2 之後，是模型路由；若 TCP 都未完成，您要查 DNS/TLS。若您增加 cron 或子 agent 負載，它們不能落在您忘記合併的 更薄 的獨立白名單上。為每個排程作業記錄 實際解析的 模型，而不是您在 Slack 裡打的易讀標籤。

Gateway、PID 檔與「我已經 kill 了」

兩個監聽器疊在一起時，常是 使用者 LaunchAgent 重啟而手動前景 行程仍佔埠，或升級留下被 launchd 收養的 子 Node。lsof -iTCP:18789 -sTCP:LISTEN 與 ps -ax | grep -i openclaw 要在 擁有 plist 的同一帳戶 上跑——不是 root。若必須強制結束，先依文件建議的 有序 停止，再 doctor 後啟動。這與 gateway 升級/回滾 矩陣配套：在工單範本裡同時記下舊 PID、node 版本與 sidecar 原生建置用的 DEVELOPER_DIR，壞發佈更容易現形。

合併不阻塞規則： 在可丟棄的 租用 預發機上升級後、CI 中跑通綠色 openclaw doctor 並保留 status --all 日誌，勝過一張只證明手機端能看到 Telegram 的聊天螢幕截圖。

症狀 / 層次表（設定 vs 服務 vs 網路）

症狀 層次 穩定化
小版本剛升完就出現「模型不在白名單」 設定政策 擴展白名單、固定字串、在 debug 下單次對話重試
doctor 正常，shell 裡新金鑰仍 403 launchd 環境 / 出站 從執行中 PID 列印環境；再做出站 TLS 檢查
加外掛後 WebSocket 1006 Node 外掛圖 重跑 npm install，讀 gateway stderr；對照 子 agent 筆記

把維運主連結起來：ClawHub 技能 規定您能手動化什麼；結構化日誌 讓錯模型與錯路由看起來不同；當 100.64/ 與公網主機名是設計的一部分時讀 Tailscale。若仍在冷啟動，先看 安裝與守護 前置文。同系列另一篇講 CI 測覆蓋率與閾值：xcodebuild 測試、覆蓋率與 JUnit 閾值。

常見問題：共享建構機上的 doctor

問題 實務建議
是否每次發佈前都要跑 doctor？ 至少 npm 變更與 gateway/二進位升級後跑；與週末聊天斷連相比，它夠快。
手改 JSON 可以接受嗎？ 若合併上游範例——立刻 doctor + 對話煙測，而不是盲重啟。
若香港區域比美國晚收到映像？ 時間差正常；政策 與 出站 差異則不正常。用 租約 標籤拆儀表板，透過 各區域方案 擴容。

五區裸金屬 M4 為何仍佔優

診斷與 gateway 工作負載更在意 抖動 與 可重複 I/O 而非尖峰算力。MacXCode 上的 Mac mini M4 提供單租 NVMe 保留冗長 JSON 日誌、持久 SSH，並可在按國家拆分 provider 白名單時水平加節點。若 2026 年您要把 OpenClaw 與真正 的發佈流水線一起跑，同一家族節點也能承擔平台另一組手冊中的 Xcode 測試 + 覆蓋率 閾值——把租約當成可用 p95 度量 的容量，而不是黑盒一直重啟到綠。

在穩定、以 SSH 為先的 Mac 上執行 OpenClaw

港 · 日 · 韓 · 新 · 美 · 可選 VNC