feat(xai): route OAuth login through device-code flow (#97249)

Jaaneek · fuller-stack-dev · web-flow · commit 84bcd500c974 · 2026-06-27T10:02:57.000-06:00
Route xAI OAuth through device-code sign-in so remote and headless hosts do not need a localhost callback. Preserve the legacy manual `xai-device-code` auth choice/method as a compatibility alias to the same device-code flow.

Also migrate stale xAI token endpoints on refresh and fail fast on structured refresh errors while keeping retries scoped to detected HTML/Cloudflare challenge responses.

Verification:
- `node scripts/run-vitest.mjs extensions/xai/index.test.ts extensions/xai/xai-oauth.test.ts`
- `node scripts/run-vitest.mjs src/cli/models-cli.test.ts -t 'maps --device-code'`
- `node scripts/run-vitest.mjs src/commands/auth-choice.test.ts -t 'removed provider auth choice'`
- Crabbox local-container live smoke on exact head `fef3cb24afb01cd1f69cf04ef67ed11d71dfadb3`: xAI discovery and device authorization returned 200.
- `$autoreview` after the live smoke: clean.

Co-authored-by: Jaaneek &lt;Jaaneek@users.noreply.github.com&gt;
Co-authored-by: fuller-stack-dev &lt;263060202+fuller-stack-dev@users.noreply.github.com&gt;
diff --git a/docs/providers/xai.md b/docs/providers/xai.md
@@ -29,10 +29,11 @@ Use the path that matches your OpenClaw install state:
     openclaw onboard --install-daemon
     ```
 
-    On a VPS or over SSH, use device-code during onboarding:
+    On a VPS or over SSH, select xAI OAuth directly; OpenClaw uses device-code
+    verification and does not require a localhost callback:
 
     ```bash
-    openclaw onboard --install-daemon --auth-choice xai-device-code
+    openclaw onboard --install-daemon --auth-choice xai-oauth
     ```
 
     OAuth does not require an xAI API key. OpenClaw does not require the Grok
@@ -48,13 +49,6 @@ Use the path that matches your OpenClaw install state:
     openclaw models auth login --provider xai --method oauth
     ```
 
-    Use the device-code flow instead when the Gateway runs over SSH, Docker, or
-    a VPS and a localhost browser callback is awkward:
-
-    ```bash
-    openclaw models auth login --provider xai --device-code
-    ```
-
     To make Grok the default model after signing in, apply it separately:
 
     ```bash
@@ -86,8 +80,7 @@ Use the path that matches your OpenClaw install state:
 
 <Note>
 OpenClaw uses the xAI Responses API as the bundled xAI transport. The same
-credential from `openclaw models auth login --provider xai --method oauth`,
-`openclaw models auth login --provider xai --device-code`, or
+credential from `openclaw models auth login --provider xai --method oauth` or
 `openclaw models auth login --provider xai --method api-key` can also power first-class
 `web_search`, `x_search`, remote `code_execution`, and xAI image/video generation.
 Speech and transcription currently require `XAI_API_KEY` or provider config.
@@ -102,8 +95,9 @@ and, by default, `x_search` through an operator xAI Responses proxy.
 
 ## OAuth troubleshooting
 
-- If browser OAuth cannot reach `127.0.0.1:56121`, use
-  `openclaw models auth login --provider xai --device-code`.
+- For SSH, Docker, VPS, or other remote setups, use
+  `openclaw models auth login --provider xai --method oauth`; xAI OAuth uses
+  device-code verification instead of a localhost callback.
 - If sign-in succeeds but Grok is not the default model, run
   `openclaw models set xai/grok-4.3`.
 - To inspect saved xAI auth profiles, run:
@@ -117,9 +111,9 @@ and, by default, `x_search` through an operator xAI Responses proxy.
   eligible, try the API-key path or check the subscription on xAI's side.
 
 <Tip>
-Use `xai-device-code` when signing in from SSH, Docker, or a VPS. OpenClaw
-prints an xAI URL and short code; finish sign-in in any local browser while the
-remote process polls xAI for the completed token exchange.
+Use `xai-oauth` when signing in from SSH, Docker, or a VPS. OpenClaw prints an
+xAI URL and short code; finish sign-in in any local browser while the remote
+process polls xAI for the completed token exchange.
 </Tip>
 
 ## Built-in catalog
@@ -498,12 +492,10 @@ Legacy aliases still normalize to the canonical bundled ids:
 
   <Accordion title="Known limits">
     - xAI auth can use an API key, environment variable, plugin config fallback,
-      browser OAuth, or device-code OAuth with an eligible xAI account. Browser
-      OAuth uses a local callback on `127.0.0.1:56121`; for remote hosts, use
-      `xai-device-code` unless you want to forward that port before opening the
-      sign-in URL. xAI decides which accounts can receive OAuth API tokens, and
-      the consent page may show Grok Build even though OpenClaw does not require
-      the Grok Build app.
+      or OAuth with an eligible xAI account. OAuth uses device-code verification
+      without a localhost callback. xAI decides which accounts can receive OAuth
+      API tokens, and the consent page may show Grok Build even though OpenClaw
+      does not require the Grok Build app.
     - OpenClaw does not currently expose the xAI multi-agent model family. xAI
       serves these models through the Responses API, but they do not accept the
       client-side or custom tools used by OpenClaw's shared agent loop. See the
diff --git a/docs/tools/code-execution.md b/docs/tools/code-execution.md
@@ -38,21 +38,21 @@ Do **not** use it when you need local files, your shell, your repo, or paired de
 <Steps>
   <Step title="Provide xAI credentials">
     Sign in with Grok OAuth using an eligible SuperGrok or X Premium subscription,
-    use the remote-friendly device-code flow, or store an API key. OAuth works
-    for `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search
-    config can also power Grok `web_search`.
+    or store an API key. xAI OAuth uses device-code verification, so it works
+    from remote hosts without a localhost callback. OAuth works for
+    `code_execution` and `x_search`; `XAI_API_KEY` or plugin web-search config
+    can also power Grok `web_search`.
 
     ```bash
     openclaw models auth login --provider xai --method oauth
-    openclaw models auth login --provider xai --device-code
     ```
 
     During a fresh install, the same auth choices are available inside
     onboarding:
 
     ```bash
     openclaw onboard --install-daemon
-    openclaw onboard --install-daemon --auth-choice xai-device-code
+    openclaw onboard --install-daemon --auth-choice xai-oauth
     ```
 
     Or use an API key:
diff --git a/extensions/xai/index.test.ts b/extensions/xai/index.test.ts
@@ -18,6 +18,7 @@ const providerAuthRuntimeMocks = vi.hoisted(() => ({
 vi.mock("openclaw/plugin-sdk/provider-auth-runtime", () => providerAuthRuntimeMocks);
 
 import plugin from "./index.js";
+import manifest from "./openclaw.plugin.json" with { type: "json" };
 import { buildLiveXaiProvider } from "./provider-catalog.js";
 import setupPlugin from "./setup-api.js";
 import {
@@ -82,13 +83,24 @@ describe("xai provider plugin", () => {
     vi.unstubAllGlobals();
   });
 
-  it("exposes OAuth and device-code auth choices", async () => {
+  it("exposes xAI OAuth and preserves the explicit device-code alias", async () => {
     const provider = await registerSingleProviderPlugin(plugin);
 
     expect(provider.auth?.map((method) => method.id)).toEqual(["api-key", "oauth", "device-code"]);
+    const oauth = provider.auth?.find((method) => method.id === "oauth");
+    expect(oauth?.kind).toBe("oauth");
+    expect(oauth?.wizard?.choiceId).toBe("xai-oauth");
     const deviceCode = provider.auth?.find((method) => method.id === "device-code");
     expect(deviceCode?.kind).toBe("device_code");
     expect(deviceCode?.wizard?.choiceId).toBe("xai-device-code");
+    expect(deviceCode?.wizard?.assistantVisibility).toBe("manual-only");
+    expect(manifest.providerAuthChoices).toContainEqual(
+      expect.objectContaining({
+        assistantVisibility: "manual-only",
+        choiceId: "xai-device-code",
+        method: "device-code",
+      }),
+    );
   });
 
   it("filters the xAI API-key catalog against live model ids", async () => {
diff --git a/extensions/xai/openclaw.plugin.json b/extensions/xai/openclaw.plugin.json
@@ -87,7 +87,7 @@
       "choiceLabel": "xAI API key",
       "groupId": "xai",
       "groupLabel": "xAI (Grok)",
-      "groupHint": "API key or browser OAuth",
+      "groupHint": "API key or OAuth",
       "onboardingFeatured": true,
       "optionKey": "xaiApiKey",
       "cliFlag": "--xai-api-key",
@@ -99,22 +99,22 @@
       "method": "oauth",
       "choiceId": "xai-oauth",
       "choiceLabel": "xAI OAuth",
-      "choiceHint": "Browser sign-in for eligible xAI accounts",
+      "choiceHint": "Remote-friendly browser sign-in without a localhost callback",
       "groupId": "xai",
       "groupLabel": "xAI (Grok)",
-      "groupHint": "API key or browser OAuth",
+      "groupHint": "API key or OAuth",
       "onboardingFeatured": true
     },
     {
       "provider": "xai",
       "method": "device-code",
       "choiceId": "xai-device-code",
       "choiceLabel": "xAI device code",
-      "choiceHint": "Remote-friendly browser sign-in without a localhost callback",
+      "choiceHint": "Compatibility alias for xAI OAuth device-code sign-in",
+      "assistantVisibility": "manual-only",
       "groupId": "xai",
       "groupLabel": "xAI (Grok)",
-      "groupHint": "API key or browser OAuth",
-      "onboardingFeatured": true
+      "groupHint": "API key or OAuth"
     }
   ],
   "uiHints": {
diff --git a/extensions/xai/xai-oauth.test.ts b/extensions/xai/xai-oauth.test.ts
diff --git a/extensions/xai/xai-oauth.ts b/extensions/xai/xai-oauth.ts
