一點就閃退？openclaw doctor 揪出閘道未啟動、模型鑑權與六步自救 runbook（2026 Mac）
你雙擊捷徑——或在 Terminal 輸入 openclaw——視窗就消失了。 沒有堆疊追蹤、沒有友善對話框，只有沉默。同時 Slack 仍顯示「gateway not active」，模型選擇器轉個不停，昨天你按掉的權限彈窗又以紅字回來。這不是「你不會用電腦」；而是環境漂移：Node 版本不對、使用者不對、設定檔不對，或閘道行程從未在 launchd 下存活。
openclaw doctor 是 OpenClaw 官方自我診斷指令。 它輸出結構化檢查清單——CLI 是否在 PATH、設定是否可讀、閘道是否可達、auth profile、磁碟餘量——讓你一次修一行，而不是照部落格重裝。本教學是新手救援路線：doctor 查什麼、如何解讀黃行與紅行、可貼進工單的六步 runbook，以及兩則新手常見錯誤的故障排查食譜。若在租用 Mac 上完成 onboard 後需要 SLA 級驗收，請讀另文 上線後 doctor 矩陣；本文對應的是「今天又閃退了。」
首次提及時請搭配 OpenClaw 第零小時安裝合約（Node 22+ 底線）、限流與預算報警（避免重試偽裝成當機），以及本地模型取代雲端金鑰時的 OpenClaw + Ollama 耦合。上游安裝參考：OpenClaw 安裝腳本 與 閘道設定範例。硬體背景：Apple Mac mini 技術規格。
披露說明：KvmZone 僅在租用 Mac 能給新手乾淨 SSH shell 執行 openclaw doctor 時提及。多數步驟在你已有的 Mac 上同樣適用。
為何 doctor 勝過從頭重裝
| 新手描述的症狀 | doctor 通常會浮現 |
|---|---|
| 啟動時 Terminal「閃退」 | shell profile 錯誤；非登入 shell 找不到 CLI PATH |
| UI 顯示「gateway not active」 | daemon 未執行；埠衝突；plist 使用者過期 |
| 模型永遠連不上 | 缺少 API key 環境變數；auth profile 指向錯誤檔案 |
| macOS 更新後權限錯誤 | TCC 提示被擋；doctor 標記 Keychain / 完整磁碟存取缺口 |
rm -rf ~/.openclaw 之前先跑 openclaw doctor。未修正 PATH 或 launchd 使用者不一致就重裝，十分鐘內會重現相同當機。若 npm registry 逾時或出口代理過濾，OpenClaw 看起來像壞掉，而真因只是 registry 連線失敗——doctor 的 network/TLS 行是第一份證據。doctor 本身不需要香港或新加坡租用主機。
架構：openclaw doctor 檢查什麼
Terminal / launchd → openclaw CLI → doctor 模組 → 讀取 ~/.openclaw/* → 探測閘道 HTTP → 輸出 PASS/WARN/FAIL 行檔案與角色
| 元件 | 路徑 / 指令 | 用途 |
|---|---|---|
| 即時設定 | ~/.openclaw/openclaw.json | 閘道埠、auth profile、模型路由 |
| 日誌 | ~/.openclaw/logs/（典型） | doctor 全綠後的當機證據 |
| CLI 二進位 | which openclaw | 必須與 launchd 使用的一致 |
| Node 執行環境 | node -v → 2026 年底線 v22.x | Node 不一致是 #1「瞬間退出」原因 |
| 閘道探測 | doctor 後執行 openclaw status | 確認行程，而非僅設定語法 |
| 非登入一致性 | sudo -u <daemon-user> openclaw doctor | 抓出「只在 Terminal 能用」 |
Doctor 不能取代負載測試或 webhook POP 規劃——那是 上線後矩陣 的範圍。它能告訴你現在是否還不能怪模型廠商。
決策矩陣：當機類型 → 第一個指令
| 若你看到… | 先執行 | doctor 對 PATH 顯示 WARN | 合併策略 |
|---|---|---|---|
| 視窗 <2 秒內關閉 | 在 Terminal.app 執行 openclaw doctor | 修正 ~/.zprofile / ~/.zshrc；用 nvm 或 Homebrew 只留一套 Node | PATH 未綠前不要開閘道 |
| UI：gateway not active | openclaw doctor + openclaw status | 重載 launchd plist；對齊 UserName | status 未 OK 90 秒前阻擋 demo |
| 模型聊天 401/403 | doctor auth 區段 | 在 plist EnvironmentVariables 匯出金鑰 | 輪替金鑰；重跑 doctor |
| 掛住 >60 秒後退出 | doctor + df -h / | 磁碟可用 < 18GB → 清理 npm/skills | 加新 skill 前先擴容 |
建議路徑： 若 shell 閃退，先互動式跑 doctor——不要透過 GUI 捷徑除錯。若 doctor 已綠但選單列 agent 仍顯示 inactive，修 launchd 使用者與埠，不要先動 LLM API 金鑰。
六步 openclaw doctor 救援 runbook
Step 1 — 開真正的 shell（不要雙擊別名）
# macOS：使用 Terminal.app 或 iTerm — 記下使用者名稱
whoami
echo $SHELL保存輸出；跳過登入 shell 的捷徑會藏住 PATH 修正。
Step 2 — 確認 Node 22+ 與 CLI 在 PATH
node -v
which openclaw
openclaw --version通過： node 回報 v22 或更新；which openclaw 回傳 /opt/homebrew 下或你文件化的全域 prefix 的單一路徑。
Step 3 — 執行 doctor 並保存 transcript
openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log把此檔附到任何支援工單。每次修正後重跑——不要堆疊猜測。
Step 4 — 修第一個 FAIL（通常是 PATH 或設定 JSON）
# 範例：重啟前驗證 JSON
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"若 JSON 失敗，從備份還原：
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)Step 5 — 對齊 daemon 使用者（gateway inactive 修正）
# 查看 launchd 使用的使用者（label 依安裝而異）
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# 若與 Step 1 不同，以該使用者執行 doctor
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log通過： 互動式與 daemon transcript 一致，或每個差異都有文件。
Step 6 — 重啟閘道並驗證 status
openclaw gateway restart # 或依安裝文件用 launchctl kickstart
sleep 5
openclaw status
openclaw doctor通過： status 顯示監聽埠；doctor 無未解釋的 FAIL 行。然後——且僅然後——重試 agent 或捷徑。
僅 SSH 的租用主機，請用 遠端 Mac SSH 流程，除非文件化的 GUI gate 要求像素工具。
故障排查
錯誤模式：zsh: command not found: openclaw（或視窗瞬間關閉）
症狀： 腳本或 .app 包裝在 UI 出現前退出；doctor 從未執行。
修正：
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor在 launchd plist 的 EnvironmentVariables 對齊相同 PATH（見 第零小時合約）。
錯誤模式：gateway not active / ECONNREFUSED 127.0.0.1
症狀： CLI 存在；UI 或 openclaw status 無法連到本機閘道。
修正：
lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart若埠被其他使用者佔用，停止孤兒行程或變更 ~/.openclaw/openclaw.json 的 gateway.port，然後重跑 doctor。閘道穩定後設定 限流——重試風暴感覺像當機。
FAQ
openclaw doctor 會刪除我的 agent 或 skill 嗎？~/.openclaw/openclaw.json 或釋放磁碟，但不會清空 ~/.openclaw，除非你另外執行解除安裝指令。PATH 與 API 金鑰匯出複製到 plist，或使用 launchctl config user path——Step 5 有說明。openclaw status 都綠之後才追 CDN/區域；webhook 地理見 上線後 POP 矩陣。延伸閱讀
- OpenClaw 第零小時安裝合約 — Node 22+ 紀律
- 上線後 doctor + webhook POP — 回呼入口
- OpenClaw 限流與預算報警 — 重試風暴 vs 當機
- OpenClaw + Ollama 租用 M4 耦合 — 無雲端金鑰的本地模型
- 遠端 Mac SSH 安全流程 — 僅 SSH 維運
僅在需要乾淨 SSH 實驗環境時再 Compare 地域
多數 doctor 步驟在你已有的 Mac 上即可完成。若需租用機做 daemon 使用者對照，可在定價頁 Compare 六地域 Mac mini M4，並依 webhook 入口選節點。