gateway.bind 改成 lan 卻未讓 launchd 讀到 OPENCLAW_GATEWAY_TOKEN，常見 refusing to bind without auth；SSH 能開 Control UI、同事筆電卻 unauthorized 則多半是探針 URL 與 listen 位址不一致。本文整理 loopback 與 lan 決策樹、.env 與 openclaw.json 單一事實源、六步驗收命令塊、gateway.reload.mode=hybrid 與硬重啟分界，以及 gateway.controlUi.allowedOrigins 與 LaunchAgent 漂移檢查；與 launchd token、升級遠端認證、診斷梯子、官方 install-daemon 交叉閱讀。
loopback 與 lan：何時值得付非回環綁定的認證成本
OpenClaw Gateway 預設 loopback，因為 KVMNODE 雲端 Mac 的威脅模型不是家用 Wi-Fi：主機在供應商網段上，有自動掃描與多地 SSH 值班。loopback 加 ssh -L 或 Tailscale 可讓 18789 不意外暴露在錯誤介面，仍能在本機瀏覽器開 Control UI。單一工程師、從同一 SSH 工作階段裝通道，且從不分享儀表板時，這仍是預設最佳解，可對照 無頭 SSH 跟做。
gateway.bind=lan 適用於區網內必須直連 Gateway 的場景：同辦公室第二台 Mac 以 remote 模式跑 OpenClaw 用戶端、無法為每台主機維護 SSH 隧道的內部健康彙整、或同事機器不經單一筆電轉發就要開 Control UI。近版建置在無有效 token 與 gateway.auth.mode 時會拒絕在非 loopback 位址監聽，沒有匿名 LAN 後門。應把拒絕當成安全特性，避免週五為除錯放寬 bind、週末忘記改回。
單人 SSH 隧道：維持 loopback；本機探針可不帶 token；變更單記錄轉發命令。
小團隊零信任：優先 Tailscale 與 ACL，再考慮供應商 RFC1918 上的 raw lan。
固定內網探針：lan + token，監控直接打 /healthz。
多端 Control UI：lan + token + allowedOrigins；勿在無邊界 ACL 下把 18789 暴露公網。
生產通道：微信 ClawBot 等仍依賴 Gateway 常駐，bind 模式不能取代 全天候穩定 的 launchd 口徑。
| 模式 | bind | 認證 | 典型誤判 |
|---|---|---|---|
| 一人 SSH | loopback | 本機可選 | 為測試開安全群組 |
| 遠端 macOS App | lan 或 tailnet | lan 必須 token | token 只在 shell rc、plist 沒有 |
| 維運探針 | 私網 NIC 上 lan | Authorization Bearer | 探針仍打 127.0.0.1 |
| 升級後漂移 | 設定寫 lan | 仍留 gateway.token | doctor 綠、RPC unauthorized |
平台負責人應在資產清冊註記 bind 意圖：生產 lan、staging 僅 loopback、或僅隧道。若尚未完成 install-daemon 驗收，請先走 官方 install-daemon 再放大 bind 範圍。
單一事實源：.env 託管 OPENCLAW_GATEWAY_TOKEN 與 openclaw.json
KVMNODE 雲端 Mac 上較穩定的生產做法是密鑰與結構分離：在 ~/.openclaw/.env 寫入 OPENCLAW_GATEWAY_TOKEN、限制檔案權限，openclaw.json 只宣告 gateway.bind、gateway.auth.mode（通常 token）、埠與 reload 設定，不在 JSON 重複明文 token，避免備份與截圖外洩。OpenClaw 在行程啟動時解析環境變數；launchd 必須載入與互動式 CLI 相同的檔案，否則會重演 升級認證 裡的 split brain。
LaunchAgent 漂移常起於有人在 .zshrc export token、SSH 驗證通過，plist 常駐行程卻 unauthorized。應把 env 鏡射到 plist 的 EnvironmentVariables，或讓 CLI 與 daemon 共用同一 state 目錄。勿把 .env 提交 git；共用主機應在工程師離職時輪替 token。廢棄的 gateway.token 鍵必須移除，新 schema 讀 gateway.auth.token 或 env 替換，靜默忽略會讓儀表板 401 迴圈，對照 診斷梯子 L2。
| 位置 | 存放 | 避免 |
|---|---|---|
| ~/.openclaw/.env | OPENCLAW_GATEWAY_TOKEN | 全域可讀權限 |
| openclaw.json | gateway.auth.mode、bind | JSON 內明文 token |
| LaunchAgent plist | PATH、WorkingDirectory、env 路徑 | 2025 複製一次的舊 token |
| 工單／聊天 | 僅遮罩後四碼 | 截圖含完整 token |
一份 token、一個 .env、一組 plist 設定檔——三份明文不是冗餘，是漂移。
輪替時產生新 token、更新 .env、執行 openclaw gateway restart，同一變更窗更新用戶端與探針。部分輪替會讓手機 App 仍通、 cron 探針失敗，表面像基礎設施不穩而非認證問題。可搭配 openclaw config get gateway.auth.mode 與 launchd token 文，避免小版本升級後 env 再次遺失。
六步跟做：停舊行程、寫 .env、設 lan、install 常駐、healthz、用戶端 token 驗收
請在擁有 LaunchAgent Gateway 的同一台雲端 Mac上操作，通常經 SSH 連 KVMNODE。勿在筆電改 bind 而 Gateway 在新加坡——會分裂設定真源。
停舊行程：openclaw gateway stop，lsof -nP -iTCP:18789 確認清空，見 安裝排錯。
寫 .env：新增 OPENCLAW_GATEWAY_TOKEN，chmod 600。
設設定：gateway.bind=lan、gateway.auth.mode=token。
刷新常駐：openclaw gateway install 或 doctor 要求時 --force；PATH 對齊 which openclaw。
健康探針：本機 curl /healthz，再以 LAN IP 帶 Bearer token 重試。
用戶端驗收：Control UI 或 remote App 帶 token 連線；變更單記錄 bind、輪替日與 deep status JSON。
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" openclaw gateway stop lsof -nP -iTCP:18789 -sTCP:LISTEN || true umask 077 printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' "$(openssl rand -hex 32)" >> ~/.openclaw/.env openclaw config set gateway.bind lan openclaw config set gateway.auth.mode token openclaw gateway install --force openclaw gateway restart openclaw gateway status --deep curl -sf "http://127.0.0.1:18789/healthz" curl -sf -H "Authorization: Bearer $(grep OPENCLAW_GATEWAY_TOKEN ~/.openclaw/.env | cut -d= -f2)" \ "http://$(ipconfig getifaddr en0):18789/healthz"
提示：部分雲端映像主要介面非 en0，請 ifconfig 確認一次並寫進 Runbook。
分散式團隊應明確 SSH 到租賃主機驗收，勿在本機複製設定檔。驗收週請每日從 loopback 與 LAN 雙向打 healthz，plist 改動後的 bind 迴歸會先反映在探針而非通道使用者抱怨。
hybrid 熱重載與硬重啟分界，以及 controlUi allowedOrigins
gateway.reload.mode=hybrid 可在營業時間套用部分設定而不全量重啟，適合微調通道路由。但bind 位址、監聽埠、auth.mode、token 來源變更必須 supervised restart，因為 socket 與認證中介在啟動期初始化。僅依賴 hybrid 切到 lan 後，常見 status 仍寫 loopback、lsof 卻是舊二進位 LAN listener 的半套用狀態。
| 變更 | hybrid | 需重啟 |
|---|---|---|
| 通道路由表 | 常可 | 探針仍舊路由時 |
| gateway.bind／埠 | 否 | 必重啟並 lsof 驗證 |
| gateway.auth.mode | 否 | 必重啟 |
| token 輪替 | 否 | 重啟後更新用戶端 |
| controlUi.allowedOrigins | 有時 | CORS 仍擋則重啟 |
遠端瀏覽器開 Control UI 需設定 gateway.controlUi.allowedOrigins 為團隊 HTTPS 來源，勿用公網萬用字元。origins 與 token 認證並用，避免私網 lan 上任意網站驅動 Gateway。改完 origins 若瀏覽器仍 CORS 失敗，優先 gateway restart 而非假設 hybrid 已生效。
排錯分叉、LaunchAgent 漂移檢查與雲端 Mac 選型
refusing to bind without auth：已離開 loopback 但 plist 未讀到 token。EADDRINUSE：手動 gateway start 與 plist 雙註冊。healthz unauthorized：探針未帶 Bearer 或 CLI 快取舊 token。Runtime running · probe failed：listen 與探針 URL 不一致，見 診斷梯子 L1。
LaunchAgent 漂移：SSH 的 which openclaw 對 plist ProgramArguments，見 CLI 對齊。
Env 漂移：launchctl print 須含 token 路徑，見 launchd token。
變更證據：工單附 deep status、healthz 狀態碼、plist Label。
| 宿主 | lan Gateway 體驗 | 維運結論 |
|---|---|---|
| 合蓋筆電 | 睡眠導致 LAN listener 抖動 | 僅試驗 |
| 共用 VM | 鄰居干擾、非 Apple launchd 常態 | 自建監控負擔大 |
| KVMNODE 獨佔雲端 Mac | 穩定 NIC、launchd、六區 | 生產 lan + 通道預設 |
注意：未完成 token 就放大 bind 會引來掃描雜訊與假模型逾時工單。
同一台主機若並跑 iOS CI，記憶體尖峰可能讓 healthz 變慢而非 bind 失效，應升 M4 Pro 或拆池而非 incident 中改回 loopback。對需可稽核、lan Gateway 與通道同機的團隊，KVMNODE Mac Mini 雲端租用通常是更優解：獨佔 Apple Silicon、六區、按天至月租。檔位見 定價頁，操作見 幫助中心，下單見 訂購入口。