OPENCLAW MACOS
STALE_
LAUNCHAGENT_
TOKEN.

2026.4.x 週期內，常見情況是：你在控制面或 doctor 取得新 Gateway Token，但 Telegram、企業 IM、Web UI、CLI 整批回 401／unauthorized；本機偶爾仍見 `openclaw gateway status` 正常，因為探針路徑未必打到與頻道相同的授權邏輯。真正的斷點通常在 macOS LaunchAgent：先前 `openclaw gateway install` 已把 OPENCLAW_GATEWAY_TOKEN 寫入 plist，之後你只改了 shell 或某份 compose，而 launchctl 實際載入的仍是舊值。若未使用 --force，gateway install 可能顯示「已安裝」而不覆寫 plist。下文提供可寫進工單的七步 Runbook、遠端 Mac 檢查表與三條硬門禁；並請與《升級 breaking 與環境鑑權》《Docker／CLI 與 token compose》《換機遷移與 Gateway 重配》《launchd／systemd 常駐》交錯閱讀。

1. 為何「全端 401」仍可能看到局部綠燈？

第一，頻道外掛與瀏覽器 UI 對 401 極敏感；部分本機探針只看行程與埠，不驗證 Authorization。第二，交互式終端匯出的環境與 plist 內 EnvironmentVariables 可能完全分裂。第三，控制面若已廢止舊 token，而 launchd 仍注入舊字串，凡依 Gateway 轉送的路徑會同步失敗。第四，gateway install 的「成功」訊息不等於「已刷新 plist」——必須檢查檔案 mtime 或明確走強制安裝。

2. 症狀—證據矩陣

現象	優先懷疑	首選證據
所有通路同時 401	Gateway 授權與當前 token 不一致	對照失敗請求與 Gateway 日誌中的 auth 關鍵字
僅 launchd 拉起失敗，手動前景正常	plist 內嵌舊 OPENCLAW_GATEWAY_TOKEN	plutil -p ~/Library/LaunchAgents/*.openclaw*.plist | grep -i token
install 顯示已安裝仍無解	未觸發 plist 覆寫	比對 install 前後 mtime；必要時 --force
僅遠端 headless Mac 發作	SSH 使用者與 GUI 使用者的 launchd 網域不一致	launchctl print gui/$uid 與實際登入帳號

3. 根因：LaunchAgent 如何把「忘了改 plist」放大成全站事故

plist 屬宣告式設定：寫入後需 bootout／改檔／bootstrap 才會換血，子行程不會跟著 zshrc「即時聯動」。生產上請把令牌輪換視為小型發布：更新金鑰→更新 plist／compose→顛簸重啟→用真實業務請求驗 200，且別只用「行程還在」自我安慰。

4. 七步 Runbook

Step 01：凍結並記錄版本

記錄 CLI／Gateway 版本、LaunchAgent Label、輪換時間，避免多人並行第二次 install。

Step 02：鎖定 plist 路徑

多在 ~/Library/LaunchAgents/；多使用者迷你主機要核對是哪個 $HOME。

Step 03：三份 token 視角比對

（A）plist、（B）交互 shell（若有）、（C）金鑰庫「當前有效」指紋；工單嚴禁貼完整 secret。

Step 04：優雅卸載後改寫

對應 Label bootout，替換 token 或改為讀取受限檔／鑰匙圈，再 bootstrap。

Step 05：需要刷新時使用 --force

以 CLI 覆寫時使用文件標明的 openclaw gateway install --force，並對 checksum／mtime 留痕。

Step 06：分層驗證

日誌健康→單頻道最小收發→再開 Web UI。若仍 401，排查第二份 plist、Docker 環境或《silent Gateway 診斷》所述被跳過的 doctor 步驟。

Step 07：安全收斂

長期避免明文長期躺在 world-readable 備份；輪換後將舊版備份加密或標記作廢。

5. 遠端 Mac：SSH 十項檢查

確認 Unix 使用者一致；echo $HOME 對齊 plist；launchctl print gui/$(id -u) 服務存在；ProgramArguments 指到正確二進位；遷移後 workspace 未指舊路徑；防火牆最小放行；辨識 Aqua 登入與純 SSH；日誌目錄權限；Docker 混部時對照 compose 與 launchd 優先序；工單附已遮罩日誌與截圖。

6. 誤區複盤

只改 .env 但 Gateway 由 launchd 管理→仍 401。install 印綠但未動 plist→仍 401。本機 curl 成功但公網客戶端走另一 TLS／路由→需分開驗證。

7. 與升級／遷移交界

breaking 升級常同時動到裝置身分與 Gateway 校驗；doctor 後若只改一半環境會出現「部分 RPC 過、部分頻道死」。請把《升級 breaking》的自檢與本稿 plist 段落同一工單串行。遷移完成後應維持單一真源下發 token，避免新舊機各持一半。

8. 事故時間線（輪換後 0–30 分鐘）

T+0～2 分鐘：凍結——禁止第二次 install 撞車；禁止未讀 plist 就全員重登；置頂 Gateway 版號、換發工單與懷疑中的 LaunchAgent Label。T+3～8 分鐘：取證——各撈一筆帶 request_id 的 401 與 Gateway auth 日誌；若客戶端有錯、網關無聲，多為打到另一反代或舊埠。T+9～15 分鐘：真源對齊——三人並行：plist 指紋、Docker compose（若有）、vault 現版；任兩源不一致即判定組態漂移。T+16～25 分鐘：改寫與滾動——bootout→改 plist 或 force install→bootstrap；消費者／Gateway 啟停順序全事件只能選一種 SOP。T+26～30 分鐘：關閉門禁——未通過 Hard gates 前禁止 all-clear。遠端機房無法拍肩，文字化時間軸即是唯一穩定信道。

9. 雙實例、埠位與反代：以為連 A 其實打 B

常見：除錯時前景起了一份 Gateway 佔 loopback，launchd 仍在另一埠看家；換發只同步到其中鏈路。或 NGINX／Caddy TLS 已換新，proxy_pass 仍指去年備援機。解法：定義唯一 health／build 端點，輪換後強制 curl loopback 與公網主機名各一次，hash 需一致。Docker Desktop 與 Colima 並存會形成第三真源；要嘛只保留一種監督器（僅 launchd 或僅 compose），要嘛 RFC 強制 dual-write 檢查表。

10. plist ↔ launchctl ↔ 行程：三角證據鏈

層級	健康訊號	典型壞相
plist 檔	mtime 落於變更窗；plutil 無語法錯	手改 XML 未閉合；權限漂移導致 launchd 靜默拒載
launchctl	launchctl print gui/$uid/… 路徑與 which 一致	指到已刪 nvm Node；ExitTimeout 異常升高
行程環境	pid 環境中 token 指紋與 vault 相符	鍵缺失卻仍能啟——表示讀了別份設定檔
日誌	401 浪與 auth 拒絕同一分鐘收斂	CPU 高但無日誌——先排除 jsonl／bootstrap 卡住再回到權杖主線

systemd 類比只成立一半：Linux unit 常 EnvironmentFile=-；macOS 偏好把字面量嵌進 plist。勿把 Ubuntu VPS 肌肉記憶硬搬，要以表格式強迫「每層一證據」。

11. FAQ：仍 401 的隱蔽分支

問：plist 已換仍 401？答：確認改的是 launchctl print 指到的那份，而非雲端同步備份。問：先 revoke 再起飛？答：風險高；宜先滾動行程或接受極短重疊窗。問：doctor 全綠仍死？答：doctor 路徑可能短於完整頻道交握，以真實訊息回環為準。問：多使用者 mini？答：各 Unix 帳號各自 LaunchAgents，勿共用同一 Gateway plist。

問：token 移轉鑰匙圈？答：長期值得，但先在測試機驗證 launchd 可讀性，勿周五晚高峰硬切。問：要順轉 SSH／API 金鑰嗎？答：僅在威脅模型要求時一併做，避免變更面爆炸。

12. 結語

macOS 上 OpenClaw 的「全員 401」多數是令牌真源分裂，LaunchAgent plist 是最隱蔽的一環。若你需要不吃灰的 Mac mini 雲端算力承載常駐 Gateway，可參考 MACGPU 定價 與 Telegram（關鍵字 MACGPU）。本文由 MACGPU 團隊撰寫，實際旗標請以官方 CLI 說明為準。