無需 localhost 回呼 · SSH/VNC 決策矩陣 · 八步 Runbook · 二十分鐘驗收表
OpenClaw v2026.5.20 把 xAI（Grok） 的訂閱型登入正式納入 device-code OAuth 一等公民路徑：終端會列印 xAI 授權 URL + 一次性驗證碼，遠端 CLI 在伺服器側輪詢 token 端點完成交換——不需要在 Gateway 機器上監聽 127.0.0.1:56121 之類的 localhost 回呼，也不必做 SSH 反向連接埠轉發。這對租用遠端 Mac、主力機在 Windows/Linux 的團隊是實質性利好：Grok 憑據可以落在雲端 Gateway 同機，而瀏覽器授權發生在你的本機裝置。若你卡在「Codex OAuth 路由錯亂」「純 API Key 無法覆蓋 SuperGrok 訂閱額度」「SSH 裡完成了登入但 Gateway 仍 401」——本文按可審計維運寫法給出：與《v2026.5.6 Doctor/Codex OAuth 修復》正交的 xAI 專用路徑、SSH × VNC 決策矩陣、八步 Runbook、四條可貼工單結論，以及 FAQ。前置建議先對照《十分鐘安裝路線圖》把 CLI/Gateway 跑通；若你在 Linux VPS 與 macOS 租用節點之間選型，請並行閱讀《Linux 無桌面 vs macOS+VNC Gateway 邊界》與《CLI/Gateway 分工》；Grok 接入後若要配主備鏈，見《多模型路由》。
v2026.5.20 之前，很多團隊在雲端 Gateway 上接 Grok 只能走裸 API Key或localhost 回呼型 OAuth；前者無法對齊 X Premium / SuperGrok 訂閱權益，後者在「Gateway 在機房、瀏覽器在筆電」拓撲下幾乎不可維運。device-code 解決了授權拓撲，但下列六類問題在工單裡仍高頻出現。
回呼 OAuth 與遠端拓撲不兼容：傳統 OAuth 要求本機瀏覽器跳回 http://127.0.0.1:56121/callback（埠因版本而異）；純 SSH 遠端 Mac 時，瀏覽器跑在本機 Windows，回呼落在筆電而非 Gateway，token 寫進錯誤機器或乾脆超時。
CLI 與 Gateway 使用者上下文分裂：在 root 或錯誤 macOS 使用者下執行 models auth login，token 落盤到 A 的 HOME，而 launchd 守護的 Gateway 讀 B 的憑據目錄——症狀是「CLI 測試通、Gateway 401」。
版本未跟到 v2026.5.20：--auth-choice xai-device-code 與 --device-code 子命令在更早構建中不存在或行為不完整；混跑 npm 全域 CLI 與舊 LaunchAgent 二進位時尤其隱蔽。
與 Codex OAuth 路由混淆：5.5 一帶曾出現 openai-codex/* 被誤歸併到 openai/* 的 doctor 副作用；xAI provider 命名空間若被手工 alias 汙染，會表現為間歇性刷新失敗——升級後務必跑 openclaw doctor 對照5.6 修復文。
device-code 輪詢視窗與使用者操作節奏：驗證碼通常有時效；SSH 會話斷線或終端 multiplex 切走，會導致輪詢中斷。應在穩定 SSH 或 VNC 內終端完成全流程，並在本機瀏覽器及時完成授權。
模型 id 與 provider 別名不一致：OAuth 成功只代表 xAI 憑據可用；若 openclaw.json 裡 Grok 模型串仍指向舊別名或 fallback 到未授權 provider，控制臺會看到「已登入但推理 404/401」——需與多模型路由一併驗收。
device-code 大幅降低了 Grok OAuth 對圖形桌面的依賴，但不等於遠端 Mac 上所有 OpenClaw 維運都只需 SSH。下表把驗收動作對應到推薦介質。
| 驗收動作 | 僅 SSH | device-code 友善 | 建議 VNC | 通過標準 |
|---|---|---|---|---|
| openclaw --version / doctor | 足夠 | — | 可選 | CLI 與 Gateway ≥ v2026.5.20，doctor 無 xAI 命名空間衝突 |
| onboard --auth-choice xai-device-code | 足夠 | 是 | 可選 | 守護程式安裝成功，token 落盤路徑與 launchd 使用者一致 |
| models auth login --provider xai --device-code | 足夠 | 是 | 可選 | 終端出現 URL+code，輪詢成功後 models list 顯示 xai 已授權 |
| 本機瀏覽器完成 xAI 授權 | N/A（在使用者筆電） | 是 | 不必 | 無需 Gateway 側 localhost 回呼 |
| gateway restart + 煙測 Grok | 足夠 | — | 建議互證 | Gateway 日誌出現 xai provider 命中，首條回復非 401 |
| 18789 控制臺 / Network 面板 | curl 探針 | — | 建議 | WebSocket 與模型下拉顯示 grok 別名，無混合內容報錯 |
| launchd 同使用者 / 鑰匙圈 | 僅文本日誌 | — | 建議 | 與守護程式清單同使用者 checklist 一致 |
| 多模型 fallback 鏈 | CLI 改設定 | — | 控制臺對照 | fallback 不跨未授權 provider |
xAI device-code 的正確心智模型：SSH 完成授權與重啟，VNC 完成控制臺與同使用者互證——而不是「OAuth 必須開桌面」。localhost 56121 回呼型登入才幾乎強制 VNC/連接埠轉發。
若你的節點是無桌面 Linux，device-code 同樣可在 SSH 完成，但 Grok 之外的通道（瀏覽器 MCP、掃碼 IM、Talk 麥克風）仍可能強制圖形會話——邊界詳見Linux vs macOS 對照文。
凍結與備份：匯出 OpenClaw 設定與狀態目錄；記錄 openclaw --version、LaunchAgent 使用者、現有 provider 清單。新環境可先走十分鐘路線圖。
確認版本 ≥ v2026.5.20：不足則升級 OpenClaw 並確保 Gateway 守護程式與 CLI 同源構建；混版本是 device-code 子命令「不存在」的首要原因。
全新節點：onboard 一站式：在與 Gateway 相同的 macOS 使用者下執行 openclaw onboard --install-daemon --auth-choice xai-device-code；按提示在本機瀏覽器打開終端列印的 xAI URL，輸入驗證碼；等待遠端輪詢完成。
已有 Gateway：補登 xAI：執行 openclaw models auth login --provider xai --device-code；同樣複製 URL+code 到本機瀏覽器，不要嘗試在遠端 Mac 上設定 localhost 回呼或 ssh -R 56121: 轉發。
doctor 互證：跑 openclaw doctor，確認 xAI provider 命名空間、token 檔案路徑、無與 Codex/OpenAI 衝突的重複 alias；若曾從 5.5 升級，對照5.6 文檢查 OAuth 路由是否被重複改寫。
設定 Grok 模型：在 openclaw.json 或交互設定裡把主模型指向 xAI Grok（如 xai/grok-* 系列，以 openclaw models list 輸出為準）；若有多 provider，按多模型路由設置 fallback，避免降級到未授權線路。
重啟 Gateway：openclaw gateway restart 後觀察 launchd 日誌，確認新 token 被 Gateway 進程加載；勿只重啟終端會話而不重啟守護程式。
煙測與歸檔：從控制臺或已配對通道發一條短句，保留 Gateway 日誌裡 provider=xai、model=grok 的命中列寫入變更單；若 401，先查使用者上下文與版本同源，再查模型 id 別名。
openclaw --version openclaw doctor # 全新節點：裝守護程式 + xAI device-code 首登 openclaw onboard --install-daemon --auth-choice xai-device-code # 已有 Gateway：僅補 xAI OAuth openclaw models auth login --provider xai --device-code openclaw models list openclaw doctor openclaw gateway restart # 煙測（示例，以 models list 為準） openclaw agent --message "用 Grok 回復 OK" --model xai/grok
device-code 時序說明：CLI 向 xAI 申請 device_code → 終端列印「請存取 URL + 輸入 code」→ 你在任意聯網瀏覽器完成授權 → CLI 在遠端 Mac 上後臺輪詢 token 端點直至成功或超時 → token 寫入 OpenClaw 憑據存儲。全程 Gateway 機器無需開放 127.0.0.1:56121，這與 Codex/OpenAI 部分舊式 localhost 回呼形成鮮明對比——也解釋了為何租用遠端 Mac 時 device-code 應作為 Grok 首選路徑。
若 Grok 已通但任務仍無回復，按《任務無回復排查》分支檢查 heartbeat、thinking 與通道入站；OAuth 401 與「模型慢/空包」在日誌關鍵字上應分開檢索。
| 核對項 | SSH 側證據 | VNC 側證據（建議） | 通過標準 |
|---|---|---|---|
| 版本與 doctor | --version、doctor 輸出 | 可選：About 面板 | ≥ v2026.5.20，無 xAI/OAuth 衝突告警 |
| device-code 授權 | 終端 URL+code、輪詢成功日誌 | 同使用者終端視窗截圖 | 憑據目錄新增 xai token 檔案 |
| Gateway 加載 | gateway restart 後日誌 | 控制臺在線、模型下拉 | 重啟後首條 Grok 非 401 |
| 模型路由 | models list、設定 diff | 控制臺選定 grok 別名 | 請求命中 xai/grok-* |
| 同使用者上下文 | whoami、launchctl 清單 | 桌面使用者 = SSH 使用者 | 與守護程式 checklist 一致 |
在租用遠端 Mac 上，VNCMac 一類節點的價值是：device-code 授權可在 SSH 完成，但 Gateway 控制臺、launchd 同使用者核對與（可選）18789 瀏覽器面板仍可在同一 VNC 圖形會話一次性閉環——把「OAuth 成了但 Gateway 讀不到」從數小時扯皮壓到二十分鐘可審計驗收。Windows 主力機團隊可固定「SSH onboard/login + VNC 控制臺互證 + 本機瀏覽器 xAI 授權」三軌值班範本。
CLI、Gateway 與首次對話。
閱讀 →無桌面與 VNC 能力邊界對照。
閱讀 →安裝路徑與同使用者衝突排查。
閱讀 →Codex OAuth 路由與 Gateway 自檢。
閱讀 →主備鏈、降級與 Grok 別名對齊。
閱讀 →device-code 在終端列印 xAI URL 與驗證碼，CLI 在遠端 Mac輪詢 token；瀏覽器授權在你本機裝置完成，Gateway 無需監聽 127.0.0.1:56121。localhost 回呼型 OAuth 則要求瀏覽器與監聽器同機，不適合「Gateway 在雲端、瀏覽器在筆電」拓撲。
可以。device-code 的設計目標就是脫離圖形桌面；你只需在 SSH 裡跑 login 子命令，再到本機瀏覽器完成授權。但若需核對 Gateway 控制臺、launchd 使用者或鑰匙圈，仍建議開 VNC 與守護程式同使用者交叉驗證。
全新租用節點用 openclaw onboard --install-daemon --auth-choice xai-device-code 一次性裝 LaunchAgent 並完成首登；已有 Gateway 僅補 xAI 憑據時用 openclaw models auth login --provider xai --device-code，然後 openclaw gateway restart。
依序：openclaw doctor → 確認 CLI/Gateway 同源且已 restart → 核對 token 落盤使用者與 launchd 使用者 → 檢查模型 id 是否指向 xai/grok 而非未授權 fallback。仍失敗時對照5.6 OAuth 修復文看是否 alias 汙染。
OpenClaw v2026.5.20 的 xAI device-code OAuth 把 Grok 訂閱登入從「localhost 回呼玄學」拉回到可複現的遠端維運：SSH 裡跑 onboard 或 models auth login，本機瀏覽器點授權，Gateway 側輪詢落盤——不必再跟 127.0.0.1:56121 搏鬥。真正決定穩不穩的仍是：CLI 與 Gateway 同源同使用者、doctor 互證、Grok 模型路由與 restart 後的煙測，以及在需要時用 VNC 把控制臺與 launchd 證據鏈對齊。自有 Mac 或自建 VPS 仍要承擔睡眠喚醒、多人搶用桌面時的使用者上下文錯位；在可租用的遠端 Apple Silicon 上，把 Gateway 與（可選）18789 控制臺放在同一 VNC 桌面，通常能把「OAuth 過了但 Gateway 401」從一整晚扯皮壓到二十分鐘可審計驗收。
若你需要一臺便於完成本文第五節同款SSH device-code + VNC 控制臺互證的遠端 Mac，可透過 VNCMac 下單：購買頁選節點與套餐；連接步驟見幫助中心（SSH-VNC）。