gateway.token 走向 gateway.auth.token，互動 shell 解析到較新的全域 openclaw，launchd 卻仍指向舊前綴；或把 gateway.bind 改成 lan 卻未同步認證，導致 Gateway 拒絕監聽。本文整理升級前快照、openclaw doctor 與 openclaw gateway status --deep 的順序、分岔修復、埠 18789 的可重現 ssh -L 與 Tailscale 模式，以及 gateway install --force 真正會動到的範圍。請與 安裝檢核 及 全天候穩定 併讀，才能把導入、升級、常駐串成同一套營運閉環。2026 升級後五種典型故障：別先怪模型
近期 OpenClaw 組建強化本機 Gateway 綁定與認證防線。gateway.bind 離開 loopback 卻沒有有效 gateway.auth.token 時，啟動會快速失敗。互動 shell 解析到較新的全域 openclaw，launchd 仍啟動舊路徑時，會出現 doctor 乾淨、RPC 探測卻失敗的典型「雙重心跳」。第三種是只留已廢棄的 gateway.token，新 schema 忽略它，儀表板反覆 401。第四種把 state 放在企業同步碟或網路家目錄，升級寫入與常駐行程讀取互相競態。第五種在應用層認證尚未就緒前，把 18789 暴露在公網介面，放大掃描雜訊並讓值班誤判為模型逾時。
下列五個檢查點強制順序：先凍結版本與檔案，再動溫度或 API 金鑰。若首次開機 onboarding 尚未完成，請先跑完 安裝檢核，再回到升級專用路徑。
金鑰漂移： npm 已升級但 gateway.auth.token 從未進入 plist 可見的設定檔描述，儀表板與 CLI 讀到不同片段。
雙二進位： which openclaw 與 plist 第一個 ProgramArguments 不一致；新欄位只作用在一側。
bind 與認證不成對： lan 無權杖時 Gateway 直接結束，日誌常見拒絕綁定特徵。
埠表無擁有者： 18789 被除錯殘留行程占用，清理前重開仍 EADDRINUSE。
生公網暴露： 在隧道或邊界 ACL 就緒前於不可信介面監聽，只會招來無意義重試。
把升級視為二進位、plist 中繼資料、設定檔三者的對齊問題；對齊後再選隧道或受控 bind 策略。
環境繼承也是陷阱：launchd 工作不會自動匯入你為方便而寫進 shell profile 的 export。若在互動階段產生權杖卻只寫進 rc，常駐服務永遠看不到。耐久作法是把機密放在服務本來就會讀的設定，或使用套件支援的 env-file 掛鉤，重啟後再用 doctor 驗證服務視角。變更單應在 plist 標籤旁註記預期的 CLI SHA 或 semver，避免下次升級讓人類執行與監督執行悄悄分道。
多台筆電共用一台雲端 Mac 做實驗時，請在 runbook 加上短輪值紀錄：誰最後跑 force、哪個 profile 擁有 Gateway、臨時 bind 是否已還原。共用主機會放大分岔，因為每個人都假設自己的 PATH 是全域真理。單一權威表列出二進位、plist 標籤、監聽位址，可減少週五晚上的猜測工時。
金級映像重烤後，Node 全域前綴常與舊 LaunchAgent 內嵌路徑脫鉤；平台團若忘了改寫自訂 agent，服務會靜默掛在幽靈二進位上。任何 token 或 bind 調整前，先比對 launchd 下與互動 shell 的 openclaw --version。這與 全天候文 的 heartbeat 假設一致：冷重開與升級後必須仍是同一顆執行檔在回應。
若 CI 會烘焙映像，建議在 build 後跑非互動 doctor，並以你自訂的警告閾值讓 pipeline fail，把升級迴歸左移。煙測產物應與映像版本字串並存，方便比對週二與週四差異而無需 SSH 考古。另請在工單同列區域、SKU、18789 擁有者，財務與平台才能看同一張表。
比較：僅 loopback、LAN 加權杖、隧道後的儀表板
雲端 Mac 的預設姿態是 loopback 加上 SSH 本機轉送，或搭配緊 ACL 的 Tailnet；與把 18789 綁在公網介面的威脅模型不同。把表放在 runbook 第一頁，值班才不會臨時辯論 bind。
| 模式 | 最適場景 | 前置條件 | 尖角 |
|---|---|---|---|
| loopback | 單一工程師 SSH 加本機瀏覽器 | 最簡預設；權杖可選 | 無隧道時網際健康檢查仍失敗 |
| lan + token | 固定 RFC1918 內部探測 | 需 gateway.auth.token 與最小防火牆孔 | plist 環境缺權杖時服務空手而歸 |
| SSH -L / Tailscale | 跨網際的零信任邊界維運 | SSH 金鑰輪替與 MagicDNS 規劃 | 本機埠衝突；睡眠後重連腳本 |
| 訊號 | 正常時代表 | 異常時先查 |
|---|---|---|
openclaw doctor | schema、權杖、埠、監督一致性 | 舊鍵、PATH、同步鎖 |
openclaw gateway status | 執行時期與 RPC 探測摘要 | 行程在但 RPC 死、權杖漂移 |
openclaw gateway status --deep | 重複安裝與 user 對 system unit 提示 | 雙重 launchd 工作、舊 plist |
先對齊「誰執行、讀哪份設定、哪個位址監聽」，再談隧道；否則只是把不一致廣播到更多筆電。
上游除錯從 openclaw status、openclaw gateway status、openclaw logs --follow、openclaw doctor 開始。雲端映像亦應記錄金級映像刷新後 Node 與 plist 預期是否仍一致。
Tailscale 與 SSH 隧道營運成本不同：前者給小團隊 DNS 名與 ACL，少記 per-host SSH 參數，但多一條修補與稽核鏈；後者單調，合規若要最少活動零件時反而有利。常見組合是 Tailscale 管可達性、Gateway 維持 loopback bind、再以 ACL 避免升級期誤開 LAN。隧道掉線時的劣化行為也應文件化，避免代理程式死敲 socket。
容量規劃仍在：升級 OpenClaw 不會消除大型工具鏈的記憶體壓力。若日誌在 Gateway 重啟旁出現 OOM，應與認證失敗分開開票。本站記憶體與儲存體專文可協助判斷 M4 Pro 餘裕是否買到穩定，或只需整理監督中繼資料。
多區部署時，每個 Gateway 實例都應有獨立的變更紀錄欄位：bind 模式與隧道指令。否則 A 團隊成功切到 loopback 加 SSH，B 團隊仍留實驗性 LAN bind，指標卻混在同一張表。請按區域與模式合併指標，而非全域攪拌。並與 安裝檢核 交叉連結，避免舊截圖把公網 bind 又抄回來。
權杖遷移與分岔：讓監督程式讀到你編輯的內容
~/.openclaw/openclaw.json 已有 gateway.auth.token 仍 401 時，下一步不是發第十組 token。請查 launchd 工作目錄與 OPENCLAW_STATE_DIR 是否與互動 shell 一致。部分雲端映像拆分自動化帳號與登入帳號的家目錄；plist 指錯帳號會造成 cat 看得到權杖、服務卻沒有的錯覺。
若 doctor 回報較新設定被較舊二進位碰過，先修 PATH，再從目標安裝重寫監督中繼資料。舊二進位仍被監督時連打 config set，meta 版本守門可能無 UI 提示就擋下變更。
openclaw doctor openclaw config get gateway.auth.token openclaw gateway status --deep openclaw gateway install --force openclaw gateway restart
備註：變更視窗請同批快照 openclaw.json、plist 標籤、openclaw --version 輸出；回滾以三者為組，不做單檔還原。
交接時把上述四段指令輸出貼在 全天候文 的 heartbeat 小節旁，夜間值班才不靠聊天室口述的埠調整。
每次 force 後請再確認僅一個啟用中的使用者層 LaunchAgent 擁有 Gateway 行程，且無孤兒 ProgramArguments 指向過期 npm 路徑。deep 狀態常挖出被遺忘的重複實驗，佔埠或讀錯權杖；下次發版前應顯式停用，否則重開機後分岔再現。
從 loopback 健全到安全遠端 18789 的六個可重現步驟
假設伺服器上 loopback 已通；否則回到 安裝檢核 處理 onboarding 與常駐。確認網路誤判不會偽裝成認證失敗後，再加遠端路徑。
本機驗證：在主機對 http://127.0.0.1:18789/ 或文件健康路徑執行 curl 並記 HTTP 狀態碼。
選路徑：單人筆電偏好 ssh -L 18789:127.0.0.1:18789 user@cloud-mac；較大團隊評估 Tailscale 與 ACL。
解衝突：本機 18789 被占用則用 ssh -L 19000:127.0.0.1:18789 改走高埠瀏覽。
對齊權杖：隧道仍會把 Gateway 權杖送到瀏覽器；值放金庫勿貼聊天室。
斷線計畫：以 autossh 等避免無人工作假設 Gateway 消失。
寫工單：bind 模式、隧道指令、埠擁有者與區域、SKU 同一張變更紀錄；採購走可稽核訂購頁。
第六步請補上筆電與雲端 Mac 間允許的防火牆規則，以及企業 VPN split-tunnel 是否會截斷 SSH。許多假陽性認證問題其實是 VPN 擋了本機轉發，而非權杖錯誤；runbook 一句話可省數小時。
三道上線關卡與何時該用 gateway install --force
版本戳一致：meta.lastTouchedVersion 與 openclaw --version 同步移動；刻意降版需另訂政策，非默默濫用 force。
單一監督來源：預設每台主機一個使用者層 Gateway unit；deep 掃到重複先停用多餘再 force。
force 邊界：plist 埠與線上設定不一致，或 doctor 明確要求監督刷新時；不可取代金鑰輪替或安全群組審查。
警告：未讀日誌與 doctor 就連打 force，易把單純埠衝突變成重啟迴圈並拉長事故窗。
相較把同事筆電當 Gateway 主機，把 OpenClaw 錨在可租用的 KVMNODE 雲端 Mac 上，更容易把二進位路徑、plist 標籤、權杖與隧道指令寫進同一張變更紀錄；筆電仍會因睡眠與系統升級耗時。若團隊必須在週報稽核可觀測性、升級回滾與續租，多機房可選的專用裸金屬通常比散落硬體好執行：先在選定區域短期租用驗證升級與隧道，再以租用價格與說明中心資訊決定 M4 Pro 與長約，勝過發版夜裡口頭加機器。
事後檢討請把 force 事件明確對應到 A/B/C 關卡；缺少分類會讓團隊誤以為 force 是萬靈丹，最後在金鑰已輪替、監督仍握舊中繼資料時再次漂移。