feat(providers): add gateway-owned OpenAI Codex subscription OAuth provider #2740

Problem Statement

OpenShell does not currently provide a first-class way for a NemoClaw/OpenClaw sandbox to use a user's Codex subscription through OpenAI's supported Sign in with ChatGPT flow while keeping the OAuth grant under gateway control.

Official OpenAI documentation says Codex CLI supports signing in with ChatGPT for subscription access through a browser flow: https://learn.chatgpt.com/docs/auth

Today the practical choices are incomplete:

• sign in inside the sandbox or copy the Codex auth file, exposing usable OAuth material to the sandbox;
• copy an existing host Codex 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 API key or a local model instead of the user's Codex subscription.

A current downstream test on NemoClaw v0.0.103, OpenShell 0.0.85, and OpenClaw 2026.7.1-2 reproduced the gap: an openai-codex login initiated from the sandbox was denied at the OpenShell egress boundary before the browser login could complete. No OpenClaw auth profile was created. Local OpenAI-compatible inference remained healthy, so this was an authentication/provider-integration gap rather than a general inference outage.

This is downstream-visible in NVIDIA/NemoClaw#1793. #988 proved that provider-backed Codex placeholders can work, but it did not establish gateway ownership of login, refresh, expiry, or revocation. #1306 provides the generic gateway-owned refresh foundation but does not define the OpenAI/Codex subscription provider, login UX, endpoint policy, or NemoClaw/OpenClaw integration.

Proposed Design

Add a provider profile such as openai-codex-oauth with a user-facing alias such as codex-subscription.

1. Explicit, provider-owned login

   • A provider creation login option starts an attended OpenAI-supported Codex/ChatGPT browser login.
   • The resulting grant is created specifically for OpenShell and is owned by that provider instance.
   • Do not import or copy a live Codex desktop/CLI refresh token. An existing Codex 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.

4. Endpoint-bound use

   • Pin or strictly allow-list the supported HTTPS OpenAI/Codex origins and required route shapes.
   • Do not honor a generic provider base-URL override for this bearer credential.
   • If OpenAI does not publish a stable third-party integration contract, 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 the Codex-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.

Acceptance Criteria

• OpenShell creates a distinct gateway-owned grant; an existing Codex desktop/CLI 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 the provider attached can use the 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.
• The implementation does not remove unrelated provider-refresh or concurrency regression coverage.

Alternatives Considered

• Copy the host Codex auth file. Rejected: it exposes or duplicates reusable OAuth material and creates ambiguous refresh ownership.
• Reuse the current Codex desktop/CLI 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, as reported in OpenAI/ChatGPT OAuth is not a viable NemoClaw provider path without manual host-side OpenClaw gateway bridging NemoClaw#1793, but requires another daemon, credential boundary, policy path, and timeout configuration.
• Use an API key. Supported and appropriate for usage-based API access, but it does not satisfy subscription-backed Codex access.
• Use only local inference. Valid for offline/local deployments, but it does not address the requested cloud-provider capability.

Agent Investigation

• Reviewed existing issues and provider architecture:
  • feat(providers): add gateway-owned credential refresh for short-lived provider tokens #1306 — generic gateway-owned refresh substrate; explicitly names ChatGPT/OpenAI OAuth-style integrations.
  • 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 path and host-gateway workaround.
• 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.
• Reproduced the downstream login gap without printing or copying credentials. The attempted sandbox login was stopped at egress policy before authorization completed; the existing local inference route was left unchanged.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request