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

[saariuslystoned]

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

[saariuslystoned]

Public implementation groundwork is staged on a separate lane repo because this account's one GitHub fork slot is already used by the #2740 Codex work:

• Lane repo: https://github.com/saariuslystoned/OpenShell-grok
• Branch: https://github.com/saariuslystoned/OpenShell-grok/tree/feat/2742-xai-grok-oauth/saariuslystoned
• Review PR: feat(providers): add gateway-owned xAI Grok subscription OAuth saariuslystoned/OpenShell-grok#6

Base is upstream main c4b500a7. I have not opened an upstream NVIDIA/OpenShell PR: this issue is still state:triage-needed, and the contributor account is not yet listed in the vouch file (discussion #2741). A feature PR against NVIDIA/OpenShell would be auto-closed.

First slice is inference only: OpenShell-owned device-code grant, gateway-only refresh, sandbox-scoped inference.local, pinned api.x.ai. It does not import a live OpenClaw xai refresh token. Live login, OpenClaw e2e, and dual-proof with #2740 remain human-gated.

[saariuslystoned]

Implementation and proof update for the Grok design

The Grok lane has been rebased conceptually onto the shared Codex/Grok subscription OAuth foundation in saariuslystoned/OpenShell#1, superseding the duplicated lifecycle in the original OpenShell-grok PR #6.

• Exact reviewed head: 2098a95c872c72ddfe36430a8c0f0c1a37b5edfb on immutable upstream base c4b500a7de64d0b66e3ee8098f58d14299092162
• The xAI adapter was reconciled against xai-org/grok-build@eb267feff13129e568df38fb6fdf0ceb65f735d6: public client identity and authorities, device referrer, displayed-code validation, no-scope refresh form, rotation behavior, and the narrower six-scope inference grant are explicit.
• The implementation exposes only the proven pinned xAI /v1/chat/completions route shape for this first inference slice.
• A strict tool-free OpenClaw turn through inference.local selected grok-subscription-e2e/grok-4.6, returned HTTP 200 with the exact expected payload, used no fallback, exposed no checked credential environment variables, and offered zero tools.
• Grok rotation advanced only its own generation and passed immediately; Codex remained usable. Codex rotation likewise left Grok usable.
• Codex logout/revoke left Grok passing. Grok logout then remotely revoked and locally cleared only the Grok grant, after which its OpenClaw and direct routes failed closed with sanitized HTTP 503. Terminal Grok credential/config key count was zero.
• Reciprocal attachment order plus explicit sandbox-local provider/model selection proved that neither provider can mask the other.
• Terminal mise run ci passed in 299.32 seconds; the server result was 1,366 passed, 0 failed, 7 pre-existing ignored. Exact-head OpenClaw autoreview completed two passes with TruffleHog clean, 0 accepted/actionable findings, and confidence 0.99.

Proof: authoritative packet and dual-provider live runtime matrix.

No host OpenClaw/xAI credential was imported or inspected. The task-owned grant was remotely revoked and locally cleared after proof. No merge, deploy, or upstream feature PR has been performed; maintainer triage and contributor-vouch gates remain unchanged.