feat(providers): add gateway-owned xAI Grok subscription OAuth provider #2742

Problem Statement

OpenShell does not currently provide a first-class way for a NemoClaw/OpenClaw sandbox to use a user's Grok subscription (SuperGrok or X Premium) through xAI's supported OAuth flow while keeping the OAuth grant under gateway control.

Upstream OpenClaw already has a bundled xai provider. The recommended path is Grok OAuth with an eligible SuperGrok or X Premium subscription; an API key is the fallback. Gateway, config, routing, and tools stay local; only Grok requests go to xAI. See https://docs.openclaw.ai/providers/xai and https://x.ai/news/grok-openclaw.

That does not give OpenShell a sandbox-safe subscription path. Today the practical choices are incomplete:

• sign in inside the sandbox or copy the OpenClaw/xAI auth profile, exposing usable OAuth material to the sandbox;
• copy an existing host OpenClaw xai OAuth login into OpenShell, creating two owners of rotating credentials;
• run a separate host OpenClaw gateway and point OpenShell's compatible-endpoint provider at it;
• use an XAI_API_KEY or a local model instead of the user's Grok subscription.

This is the same class of gap as #2740 (Codex subscription OAuth). #2740 should stay Codex-only. This issue is the xAI sibling on the same #1306 substrate.

A current downstream test on NemoClaw v0.0.103, OpenShell 0.0.85, and OpenClaw 2026.7.1-2 can use OpenClaw's host-side xai OAuth, but an xAI/Grok login initiated from the sandbox is not a first-class OpenShell provider. Local OpenAI-compatible inference can remain healthy while subscription Grok is still missing as a sandbox inference path. This is an authentication/provider-integration gap rather than a general inference outage.

#988 proved provider-backed placeholders can work (Codex). #1306 provides the generic gateway-owned refresh foundation (oauth2_refresh_token) and already names ChatGPT/OpenAI OAuth-style integrations; it does not define an xAI/Grok subscription provider, login UX, endpoint policy, or NemoClaw/OpenClaw integration.

Proposed Design

Add a provider profile such as xai-grok-oauth with a user-facing alias such as grok-subscription.

1. Explicit, provider-owned login

   • A provider creation login option starts an attended xAI-supported Grok/SuperGrok or X Premium browser or device-code login (the same class of flow OpenClaw already uses for --provider xai --method oauth).
   • The resulting grant is created specifically for OpenShell and is owned by that provider instance.
   • Do not import or copy a live OpenClaw xai refresh token. An existing OpenClaw xAI login must remain independently usable.

2. Gateway-only credential lifecycle

   • Store access, refresh, and account material in the non-injectable gateway refresh state from feat(providers): add gateway-owned credential refresh for short-lived provider tokens #1306.
   • Do not return real OAuth material through provider environment resolution, sandbox files, normal provider reads, diagnostics, or logs.
   • The sandbox receives only placeholders and/or an inference.local route.

3. Sandbox-scoped authorization

   • Resolve the subscription route only for an authenticated sandbox that has this exact provider attached.
   • An unattached sandbox must not receive or use a gateway-wide personal subscription route.
   • Keep provider instances isolated by owner and sandbox attachment.
   • A sandbox attached only to the Codex provider from feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740 must not be able to use this Grok route, and the reverse.

4. Endpoint-bound use

   • Pin or strictly allow-list the supported HTTPS xAI origins and required route shapes (OpenClaw's bundled transport is the xAI Responses API).
   • Do not honor a generic provider base-URL override for this bearer credential.
   • If xAI does not publish a stable third-party integration contract for this grant, mark the provider experimental and centralize/version the compatibility boundary rather than spreading private constants through the codebase.

5. Fail-closed refresh and expiry

   • Refresh persistence must be version-matched and atomic across rotation, deletion, and reconfiguration.
   • Distinguish terminal grant rejection from retryable timeout, rate-limit, and server errors.
   • Enforce credential expiry during route resolution and in supervisor caches; an expired or reauth-required credential must be omitted and previously cached routes cleared.
   • Provide bounded status, re-login, logout, and revocation guidance without exposing credentials.

6. NemoClaw/OpenClaw UX

   • NemoClaw should be able to attach the provider to an OpenClaw sandbox and select a Grok-backed model without a separately managed host gateway.
   • OpenClaw should complete a normal tool-free response through inference.local, while the subscription credential remains gateway-side.
   • Optional follow-up, not this issue's first slice: the same gateway-owned grant may later back Grok web_search / x_search the way OpenClaw reuses one xAI credential. First slice is inference only.

Dual-proof with #2740

The two providers should be proofed together as evidence that #1306 is a shared substrate, not a Codex one-off:

• Create both provider instances (Codex subscription + Grok subscription) from attended logins.
• Attach only Codex to sandbox A and only Grok to sandbox B. A cannot reach xAI; B cannot reach ChatGPT/Codex.
• Logout/revoke of one grant leaves the other usable.
• Existing Codex desktop/CLI login and existing OpenClaw xai OAuth login remain independently usable before and after OpenShell refresh.
• No reusable credential from either grant appears in either sandbox.

This dual-proof is acceptance evidence. It is not a request to merge the two provider designs into one issue.

Acceptance Criteria

• OpenShell creates a distinct gateway-owned xAI grant; an existing OpenClaw xai OAuth login continues working before and after OpenShell refresh.
• No access token, refresh token, account token, or equivalent reusable credential appears in sandbox environment, filesystem, normal CLI output, diagnostics, or logs.
• Sandbox A with this provider attached can use the Grok route; sandbox B without it is denied.
• A hostile or custom base URL cannot receive the subscription bearer credential.
• Refresh, delete-during-refresh, reconfigure-during-refresh, expiry, reauth-required, 408/429, and transient 5xx cases are covered.
• Expired routes stop resolving even when a supervisor cannot refresh its bundle from the gateway.
• E2E proof covers provider login, attachment, one OpenClaw response, credential rotation, and logout/revocation behavior.
• Dual-proof with feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740 (or a recorded equivalent) shows isolation between the two subscription grants.
• The implementation does not remove unrelated provider-refresh or concurrency regression coverage.

Alternatives Considered

• Copy the host OpenClaw xAI auth profile. Rejected: it exposes or duplicates reusable OAuth material and creates ambiguous refresh ownership.
• Reuse the current OpenClaw xai OAuth login. Rejected: two independent refreshers can invalidate one another. This was the central failure mode identified in feat(providers): anthropic subscription oauth #2285.
• Keep the host OpenClaw gateway bridge. It works for models OpenClaw already speaks, but requires another daemon, credential boundary, policy path, and timeout configuration.
• Use an API key. Supported and appropriate for usage-based xAI API access, but it does not satisfy subscription-backed Grok access (SuperGrok / X Premium).
• Use only local inference. Valid for offline/local deployments, but it does not address the requested cloud-provider capability.
• Fold this into feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740. Rejected: feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740 is the Codex provider contract. This issue is the xAI contract on the same substrate.

Agent Investigation

• Reviewed existing issues and provider architecture:
  • feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740 — sibling Codex subscription OAuth design; this issue mirrors that contract for xAI/Grok.
  • feat(providers): add gateway-owned credential refresh for short-lived provider tokens #1306 — generic gateway-owned refresh substrate (oauth2_refresh_token); first-pass strategies are Microsoft/Google, with ChatGPT/OpenAI OAuth-style integrations named as blocked use cases.
  • Support Codex OAuth in OpenShell using provider-backed auth.json placeholders #988 — completed proof for provider-backed Codex auth placeholders.
  • OpenAI/ChatGPT OAuth is not a viable NemoClaw provider path without manual host-side OpenClaw gateway bridging NemoClaw#1793 — downstream report of the missing first-class ChatGPT/Codex path and host-gateway workaround. The Grok equivalent is the same missing first-class path.
• Reviewed feat(providers): anthropic subscription oauth #2285 and its security findings. The reusable lessons are:
  • never share another client's rotating refresh token;
  • scope personal subscription routes to attached sandboxes;
  • pin credential-bearing endpoints;
  • enforce expiry in route caches;
  • use race-safe refresh persistence;
  • preserve independent integration and concurrency coverage.
• Confirmed OpenClaw already ships @openclaw/xai-plugin / openclaw models auth login --provider xai --method oauth. OpenShell has no xai / grok provider profile today (providers/ has codex.yaml and no xAI equivalent).
• Did not print or copy credentials. Did not open an upstream PR.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request
• This does not change the scope of feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740