Authorize Grok without localhost callback · three login paths · eight-step runbook · twenty-minute acceptance
OpenClaw v2026.5.20 (2026-05-21 stable) adds xAI device-code OAuth so leased remote Macs, Docker hosts, and pure SSH sessions can authorize Grok without relying on a 127.0.0.1:56121 browser callback. If you run Gateway on a cloud Mac with SuperGrok or X Premium but hit “OAuth opened on the server but my laptop never saw the redirect,” “device-code printed but polling timed out,” “auth succeeded yet Grok is not the default model,” or “doctor warns about plaintext API keys while I thought OAuth replaced keys,” this article is an auditable ops path: three login paths compared, an SSH versus VNC decision matrix, an eight-step runbook, four ticket-ready conclusions, ordered triage, and a twenty-minute acceptance grid. Start with the ten-minute install route map if CLI and Gateway are not up yet. For outbound HTTP through corporate proxies, read the outbound proxy runbook before blaming OAuth. For Grok search and plugin approvals after auth, see the v2026.3.28 Grok guide. If you recently hit Codex OAuth namespace bugs, cross-check the v2026.5.6 Doctor recovery article so xAI and Codex tickets stay separate.
Teams that already route Claude or OpenAI through OpenClaw often assume xAI is the same: export a key, set a model ref, done. Grok’s recommended path is subscription OAuth, and until v2026.5.20 the practical default on remote hosts was awkward browser OAuth with a loopback callback. The failure modes cluster around callback reachability, account eligibility, post-auth model selection, and credential storage context — not model quality.
Loopback callback mismatch: browser OAuth expects 127.0.0.1:56121 on the machine running the login command. SSH into a leased Mac and opening the URL on your Windows laptop completes consent on the wrong host; tokens land where you did not intend.
Headless without device-code: before 5.20, operators forwarded port 56121 or ran a graphical browser on the server. Both work but are brittle under NAT, sleep policies, and multi-user HOME directories.
Auth succeeded, model still wrong: OAuth stores an xAI profile but does not automatically rewrite agents.defaults.model.primary. Smoke tests against the old default look like “Grok broken.”
Subscription eligibility: xAI decides which accounts receive OAuth API tokens. SuperGrok or X Premium may be required; ineligible accounts need the API-key path documented on OpenClaw xAI provider docs.
Consent UI says Grok Build: OpenClaw uses xAI’s shared OAuth client. The consent screen may show Grok Build branding even though OpenClaw does not require the Grok Build app — record this in tickets to avoid false “wrong app” escalations.
OAuth vs API key for media: chat, web_search, and x_search can run on OAuth; batch TTS, some STT paths, and explicit media config may still need XAI_API_KEY. Mixed expectations cause “half the stack works” incidents.
v2026.5.20 also ships the bundled Policy plugin (doctor lint and channel conformance). That is valuable for production hardening but orthogonal to Grok login — do not conflate “Policy warnings” with “OAuth failed.” Treat xAI auth as its own acceptance slice before you tune multi-model routing in the multi-model routing guide.
OpenClaw documents three xAI credential paths. Pick explicitly in change tickets — “we use OAuth” is not precise enough for remote Mac ops.
| Path | When to use | Remote Mac notes | Pass criteria |
|---|---|---|---|
| Browser OAuth --method oauth | Same-machine GUI session; callback reachable | Works in VNC desktop on the Gateway host; fragile over pure SSH | models auth list --provider xai shows profile |
| Device-code OAuth --device-code | SSH, Docker, VPS, no loopback forward | CLI prints URL + code; finish in any local browser; remote polls | Polling completes; no timeout in CLI |
| API key --method api-key | Console keys, media-only surfaces, ineligible OAuth accounts | Store via SecretRef; doctor warns on plaintext in config | Key resolves; model probe returns 200 |
| Acceptance step | SSH only | VNC recommended | Pass criteria |
|---|---|---|---|
| openclaw --version ≥ 2026.5.20 | Sufficient | Optional | CLI and Gateway builds aligned |
| Device-code login | Sufficient | Optional for side-by-side URL | Token exchange completes |
| Browser OAuth on host | Cannot complete alone | Yes — local Safari/Chrome on Mac | Callback on 56121 succeeds |
| models set xai/grok-4.3 | Sufficient | Console model picker cross-check | Default model shows xai ref |
| Gateway chat smoke test | IM or CLI message | Console + channel client | Round-trip Grok reply |
| web_search / x_search | Tool logs | Console tool trace | Retrieval with citations when configured |
| Doctor plaintext-secret lint | openclaw doctor | Review config tree in GUI | No stray plaintext xAI keys if OAuth-only |
Lowest-friction Grok rollout on a leased Mac: SSH for device-code login and logs + VNC as the same user for console model status and Gateway cross-check — not either/or.
Device-code solves the authorization transport problem; it does not replace daemon user discipline. Pair with the launchd daemon checklist so tokens written during an SSH session as user A are visible to Gateway running as user B.
Freeze and backup: export OpenClaw config and state; record openclaw --version, Gateway build, launchd user. Greenfield hosts follow the ten-minute route map.
Upgrade to ≥ 2026.5.20: device-code OAuth landed in this release. Align CLI and Gateway on the same build before auth — mixed versions produce “login succeeded but Gateway still 401” ghosts.
New install path: during onboarding choose device-code explicitly: openclaw onboard --install-daemon --auth-choice xai-device-code. OAuth does not require an xAI API key.
Existing install — add Grok only: do not rerun full onboarding. Sign in with openclaw models auth login --provider xai --device-code as the same user as the Gateway daemon.
Complete device-code in any browser: CLI prints an xAI URL and short code. Open the URL on your laptop or phone, enter the code, approve consent. Keep the SSH session open until polling reports success.
Set default model: auth alone does not switch defaults. Run openclaw models set xai/grok-4.3 (or your chosen catalog id). Verify with openclaw models status and openclaw models auth list --provider xai.
Enable search tools if needed: for Grok-backed retrieval set tools.web.search.provider grok and confirm x_search plugin config per the Grok approvals guide.
Restart and probe: openclaw gateway restart, then send a short chat smoke test from your configured channel. Attach CLI auth output and one Gateway log excerpt to the change ticket. If replies stall, use no-reply triage before reopening OAuth.
openclaw --version openclaw doctor # New install (remote / SSH-friendly) openclaw onboard --install-daemon --auth-choice xai-device-code # Existing install — Grok auth only openclaw models auth login --provider xai --device-code openclaw models auth list --provider xai openclaw models set xai/grok-4.3 openclaw models status openclaw config set tools.web.search.provider grok openclaw gateway restart
Browser OAuth alternative: when you already sit in a VNC desktop on the Gateway host, openclaw models auth login --provider xai --method oauth can be faster because the loopback callback lands locally. Switch to device-code when forwarding 56121 is blocked or when multiple operators share one SSH bastion.
v2026.5.20 also introduces the bundled Policy plugin for doctor lint and channel conformance. Mention Policy findings separately from xAI auth — mixing them slows CAB review. When doctor warns about plaintext provider keys, migrate to SecretRef per the SecretRef audit checklist even if Grok chat already works on OAuth.
xAI OAuth tokens live in OpenClaw local state on the Gateway machine. Treat the remote Mac as a high-sensitivity asset even when you never pasted an API key:
User context: SSH user, VNC desktop user, and launchd daemon user must match for token visibility. Echo $HOME in SSH and VNC before comparing auth artifacts.
Backup scope: restrict config/state backups that include OAuth profiles; never sync token-bearing dirs to public cloud drives.
Subscription boundary: xAI decides OAuth eligibility. Ineligible accounts should pivot to API-key auth documented on the provider page — do not loop device-code indefinitely.
Gateway exposure: OAuth tokens and the 18789 console are different trust domains. Follow the Gateway HTTPS reverse-proxy checklist if you expose the console beyond loopback.
Egress and proxy: corporate forward proxies can stall OAuth polling. Set HTTPS_PROXY per the outbound proxy runbook before blaming xAI or OpenClaw.
Ordered triage when device-code fails: (1) confirm CLI ≥ 2026.5.20 and Gateway restarted; (2) verify account subscription on xAI; (3) retry device-code with a fresh code before the poll window expires; (4) check proxy egress; (5) compare models auth list against the daemon user; (6) only then fall back to API-key path or browser OAuth inside VNC.
| Check | VNC evidence | SSH evidence | Pass |
|---|---|---|---|
| Version ≥ 5.20 | About or console build badge | openclaw --version | CLI matches Gateway |
| Device-code login | Optional: terminal URL readable | Auth list shows xAI profile | Poll completed, no timeout |
| Default model | Console picker shows xai/grok-4.3 | models status | Primary ref is xai |
| Chat round-trip | Channel client shows Grok reply | Gateway inbound/outbound logs | Response within SLA |
| Grok search tool | Console tool trace with citations | web_search log lines | Retrieval succeeds when enabled |
| Doctor lint | Review flagged plaintext keys | openclaw doctor | No blocking auth/config errors |
On leased remote Macs, VNCMac-class nodes keep device-code terminal output, optional Safari for browser OAuth, and Gateway console inspection in one graphical session, shrinking Grok rollout from “tokens landed in the wrong HOME” to a twenty-minute auditable acceptance. Windows-first teams can standardize “SSH device-code login + VNC model console cross-check” on-call, sharing evidence format with v2026.5.18 subagent acceptance. Print echo $HOME and whoami in SSH and VNC before comparing auth profiles — multi-home hosts amplify user mismatch during OAuth acceptance.
CLI, Gateway, first chat.
Read →x_search, /approve, ACP binds.
Read →Codex route fix — contrast with xAI.
Read →Primary, fallback, cost caps.
Read →Yes for authorization: openclaw models auth login --provider xai --device-code prints URL and code; finish in any browser while the remote session polls. Use VNC when you need console model status or same-user Gateway cross-check.
No for chat and bundled Grok search when OAuth succeeds. Speech, streaming TTS, and some media surfaces may still require XAI_API_KEY per OpenClaw docs.
OpenClaw uses xAI shared OAuth client metadata. The label Grok Build on the consent page is expected and does not mean you installed the wrong app.
If 127.0.0.1:56121 is unreachable from the machine where you opened the link, switch to device-code instead of port forwarding. Run login as the Gateway daemon user.
Run openclaw models set xai/grok-4.3 and openclaw models status. OAuth stores credentials separately from the default model ref — a successful login with the wrong primary model looks like provider failure.
OpenClaw v2026.5.20 finally gives remote Mac operators a first-class xAI device-code OAuth path: authorize Grok with SuperGrok or X Premium without fighting localhost callbacks, then set the model ref and prove round-trip replies in one change ticket. Stability still hinges on version alignment, same-user token storage, explicit default model selection, and separating xAI auth from Codex or Policy lint noise. Owning hardware still leaves sleep policies, egress filters, and HOME mismatches when several people touch one host. On a leased Apple Silicon Mac, placing the device-code terminal and Gateway console on one VNC desktop often compresses “OAuth worked but Grok silent” from hours of debate to roughly twenty minutes of auditable acceptance.
When you need a host built for section-six console and OAuth cross-check, use VNCMac: pricing and plans for node selection; technical support for SSH and VNC baselines.