openclaw onboard 默认尝试打开 127.0.0.1:56121 浏览器回调，无 GUI 的远程 Mac 无法完成授权，日志停在「等待 OAuth 回调」。OpenClaw v2026.5.20（2026-05-21）正式引入 xAI Device-Code OAuth，可在纯终端完成 Grok 登录。本文给出 2026 年可执行路径：三种鉴权方式决策矩阵、openclaw update 升级 Runbook、Device-Code 六步骨架，以及升级后 Node 22.19 与 Gateway 健康验收清单。
无头云 Mac 上 Grok 鉴权最常见的五条误判签名
OpenClaw 在 2026 年的 xAI Provider 同时支持 API Key、浏览器 Loopback OAuth 与 Device-Code OAuth 三条路径。云 Mac 运维若把「能 SSH 登录」等同于「能完成 Grok 授权」，就会在首小时反复重装 Gateway，而真正阻塞点往往是鉴权方式选错或Node 版本低于 22.19。v2026.5.20 还修复了 openclaw update 在多 Node 安装环境下 Gateway 静默切换二进制的问题——升级后若跳过 doctor 验收，渠道可能「已连接但模型调用 401」。建议变更单先勾选签名编号，再决定是切换 Device-Code、钉扎 Node 路径，还是把 Gateway 迁到规格更高的云 Mac。
在无 GUI 云 Mac 上仍选浏览器 OAuth：Loopback 回调依赖本机浏览器打开 127.0.0.1:56121；纯 SSH 会话无法完成，应改用 --device-code 或 xai-device-code onboard 选项。
把 Device-Code 短码当成 API Key 写入 config：Device-Code 是一次性授权流程，完成后 Token 存入 auth profile；不应把验证码字符串硬编码进 openclaw.json。
升级 v2026.5.20 后未验证 Node 一致性：该版本修复 Gateway 与 CLI 使用不同 Node 二进制的问题；升级后必须 openclaw doctor 并核对 managed service 的 Node 路径。
OAuth 成功但默认模型仍是 OpenAI：Device-Code 完成后需 openclaw models set xai/grok-4.3（或目标 Grok 型号），否则 Agent 仍路由到旧 Provider。
在 16GB 云 Mac 上同时跑 Grok 云端推理与本地 Ollama 重模型：Gateway 本身轻量，但浏览器自动化 + 并行工具调用会顶满内存；应参照规格分水岭表选 24GB 或分机。
以上签名与站内《无头 SSH 首小时验收清单》《Ollama 混合模型 Provider 指南》形成互补：首小时解决 Node 与 Gateway 基线，本文聚焦 v2026.5.20 的 Grok OAuth 新能力与升级验收。
xAI API Key、浏览器 OAuth 与 Device-Code OAuth 怎么选？
xAI 官方文档明确：Grok OAuth 面向具备 SuperGrok 或 X Premium 订阅资格的账户，无需单独购买 API Key。OpenClaw 作为 local-first Gateway，鉴权 Token 保存在云 Mac 状态目录，模型请求经 xAI API 出站。三种方式的差异在于授权交互形态与无头环境适配度，而非 Grok 模型能力本身。
| 维度 | API Key | 浏览器 Loopback OAuth | Device-Code OAuth（v2026.5.20+） |
|---|---|---|---|
| 适用场景 | 已有 xAI 开发者 Key、批量自动化 | 本机 macOS/Windows 有 GUI、可开浏览器 | SSH 云 Mac、Docker、VPS 无 GUI |
| 交互方式 | 环境变量或 config 写入 Key | 自动打开 127.0.0.1:56121 回调 | 终端打印 URL + 短码，任意设备浏览器授权 |
| 无头云 Mac | 可行但需付费 Key | 需 SSH 端口转发或 VNC | 推荐默认路径 |
| Token 存储 | 静态 Key | xai/oauth auth profile | 同左，轮询完成后自动持久化 |
| 与云 Mac Gateway | 适合生产但成本随调用量增长 | 首装方便，不适合纯 SSH 运维 | 与 MESHLAUNCH 六区裸金属 7×24 Gateway 最匹配 |
生产 Gateway 在裸金属云 Mac 上 7×24 运行时，Device-Code OAuth 是唯一不需要 VNC 也能完成 Grok 订阅鉴权的官方路径。
若团队已用 Ollama 做本地回落，Grok 可作为云端主模型：路由策略见混合 Provider 文，本文不重复模型切换全文。关键是 OAuth 完成后用 openclaw models list 确认 xai/grok-4.3 处于可用且默认状态。
OpenClaw v2026.5.20 升级与 Device-Code 命令骨架
v2026.5.20 于 2026-05-21 发布，核心变更包括：xAI Device-Code OAuth（PR #84005）、CLI/update 在多 Node 环境下保持 managed Gateway 使用同一 Node 二进制、Windows install.ps1 向导渲染修复。2026.5.19 起官方将 Node.js 最低版本提升至 22.19，低于该线的环境可能在 doctor 通过但插件加载异常。升级前建议 openclaw update --dry-run 预览变更，并在变更窗口内完成 Gateway 重启与 channels probe。
node -v openclaw update --dry-run openclaw update openclaw gateway restart openclaw onboard --install-daemon --auth-choice xai-device-code openclaw models auth login --provider xai --device-code openclaw models set xai/grok-4.3 openclaw doctor openclaw channels probe
提示：若 Gateway 已安装且仅需补 Grok 鉴权，可跳过完整 onboard，直接执行 models auth login --provider xai --device-code。Device-Code 流程会打印 xAI 验证 URL 与短码，在任意本地浏览器完成授权，SSH 终端保持轮询直至 Token 交换成功。
Device-Code 与 Loopback OAuth 的 consent 页可能显示 Grok Build 字样——这是 xAI 共享 OAuth 客户端的正常现象，OpenClaw 文档明确不要求安装 Grok Build 应用。授权成功后状态目录会生成 xai/oauth auth profile，可用 openclaw models auth list 验证。若需回滚版本，对照站内《update 发布渠道与回滚 Runbook》钉扎 dist-tag 后再做 doctor。
六步 Runbook：从升级到 Grok 可用 + Gateway 验收
Node 22.19 基线验收：执行 node -v，确认 ≥ 22.19；多 Node 环境用 which node 与 LaunchAgent plist 内 Node 路径对照，避免 v2026.5.20 修复前的二进制漂移复发。
干跑升级：openclaw update --dry-run 记录目标版本与插件变更；生产 Gateway 选低流量窗口，先 openclaw backup create --verify（或 tar 状态目录）。
执行升级并重启 Gateway：openclaw update → openclaw gateway restart → openclaw gateway status 确认 active；核对 openclaw --version 为 2026.5.20。
Device-Code Grok 授权：新装走 onboard --install-daemon --auth-choice xai-device-code；已有 Gateway 走 models auth login --provider xai --device-code；在本地浏览器打开终端打印的 URL 输入短码。
默认模型与探活：openclaw models set xai/grok-4.3；openclaw infer model run --local --model xai/grok-4.3 --prompt 'ping' 验证推理链路；再跑 openclaw doctor --fix 处理 config 漂移。
渠道与 7×24 验收：openclaw channels probe 全绿；断开 SSH 等待 10 分钟再 probe，确认 LaunchAgent 守护有效；记录版本、Node 路径与 auth profile 快照入 Runbook。
三条值班硬阈值与六区云 Mac Gateway 规格对照
Node 版本红线：官方 2026.5.19+ 强制 Node 22.19 地板；云 Mac 首装若 install.sh 拉取的 Node 偏旧，应在升级 OpenClaw 前先 nvm install 22 或系统级升级，否则 doctor 与插件 registry 行为不一致。
Device-Code 超时阈值：轮询窗口通常数分钟；若 SSH 会话因 idle 断开导致授权失败，应使用 tmux 或 mosh 保持终端，并在本地浏览器完成验证后再观察终端输出。
内存分水岭：Gateway + Grok 云端推理本身占用 modest，但 OpenClaw 浏览器自动化与并行 tool call 在 16GB 云 Mac 上易触发 Swap；建议重任务 Gateway 选 24GB 或 M4 Pro 档，轻量渠道 Bot 可 16GB 日租试跑。
注意：阈值为值班沟通口径，不构成厂商 SLA。xAI OAuth 资格由 xAI 账户策略决定，OpenClaw 无法绕过。
把 Grok Gateway 绑在本地笔记本上，会重新引入睡眠、漫游网络与 OAuth 回调不可达；纯 Linux VPS 虽可跑 Node，却与 macOS 浏览器自动化工具链脱节。以裸金属云 Mac 为 7×24 Gateway、SSH 完成 Device-Code 授权，能在 Apple 生态邻近性、loopback 安全纪律与可预测换租窗口之间取得平衡。对要 Grok 订阅驱动 Agent、又不愿赌消费级硬件在线率的团队，MESHLAUNCH 的 Mac Mini 云端租赁通常是更优解：建议目标城区日租先完整跑通六步与一次 Gateway 重启，再锁月租。容量与下单见 租赁价格 与 帮助中心。
先 openclaw doctor 与 which node，确认 managed service Node 与 CLI 一致；再 gateway status 与 channels probe。回滚见 update 回滚 Runbook。