无需 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）。