Summary

Remote OpenAI Codex OAuth should eventually expose an explicit browser-callback-settled signal so OpenClaw can dismiss a visible manual paste prompt when SSH-tunneled sign-in completes automatically.

This is a longer-term prompt lifecycle improvement for the OpenAI Codex / ChatGPT OAuth provider. It is not required for the near-term copy-only fix in #81301.

Current behavior

Remote OpenAI Codex OAuth has two valid completion paths:

• Paste-only/headless users open the auth URL in their local browser, sign in, then paste the redirect URL back into OpenClaw. The existing manual prompt may also accept an authorization code; fix(openai): clarify remote Codex OAuth prompt #81301 intentionally does not change that prompt text or parser behavior.
• SSH-forwarded callback users open the auth URL in their local browser and the browser callback can reach the OpenClaw process, so onboarding may continue automatically without pasted input.

Auth is already correct in the SSH-tunneled case. The remaining UX issue is that a manual paste prompt can be visible even though the browser callback already completed sign-in.

Problem to solve

OpenClaw can explain both remote paths in copy, but the current OAuth helper does not expose a clean event for "the browser callback won." Without that event, OpenClaw cannot reliably cancel or dismiss a manual paste prompt once pasted input is no longer needed.

Desired behavior

A future implementation should be able to do this without timing hacks or token-endpoint inference:

1. Remote/VPS flow shows the auth URL and paste input immediately.
2. Paste-only users can paste the redirect URL immediately.
3. SSH-tunneled users can still complete automatically through the browser callback.
4. When the browser callback is received, OpenClaw dismisses or cancels the manual paste prompt because no pasted input is needed anymore.
5. Local non-remote browser flows keep their existing delayed manual fallback behavior.

Possible design

Add or adopt an explicit callback-settled contract for OpenAI Codex OAuth. Possible shapes:

• onCallbackCodeReceived / onBrowserCallbackSettled fired when the local callback receives and validates the callback payload
• a lower-level helper that returns { authUrl, waitForCallback, exchangeCode } so OpenClaw can race browser callback and manual paste itself
• an upstream-supported abort/cancellation signal for onManualCodeInput when the browser callback wins

The important contract is the event, not the exact API name: OpenClaw needs a provider-owned signal that manual paste input is no longer necessary.

Non-goals

• Do not delay the remote paste prompt; paste-only users rely on it.
• Do not require paste for SSH-tunneled users whose browser callback already works.
• Do not add a config flag unless maintainers find two genuinely supported behaviors that cannot share one safe default.
• Do not move broad OpenAI Codex OAuth ownership into core; owner-specific behavior should stay in the OpenAI provider/plugin path.

Alternatives considered

• Copy-only short-term fix: fix(openai): clarify remote Codex OAuth prompt #81301 updates the remote note to say paste the redirect URL first, with a caveat that sign-in may finish automatically before paste. This is safe because it changes wording only.
• Monitor OpenAI Codex token-exchange traffic to infer that the callback won. This can work against today's implementation, but couples prompt lifecycle to downstream token request details instead of the callback event.
• Delay the remote paste prompt. This improves the tunneled case but makes paste-only users wait before they can do the only thing that will complete auth.
• Always require paste in remote mode. This removes stale prompt ambiguity but regresses users whose SSH-forwarded callback works.
• Internalize the full OpenAI Codex OAuth flow in OpenClaw. This would expose the event but increases ownership and drift from the upstream helper.

Impact

Affected users: Remote/VPS users authenticating with the OpenAI Codex / ChatGPT OAuth provider.

Severity: Low to medium. SSH-tunneled auth can already succeed; the issue is stale/confusing UI when a manual prompt remains visible after automatic callback completion.

Frequency: Any remote OpenAI Codex OAuth login where some users are paste-only and others have a working SSH-forwarded callback.

Maintainer impact: A proper contract would keep prompt lifecycle logic clear and avoid future workarounds based on token exchange timing, global fetch wrapping, or arbitrary delays.

Acceptance criteria

• Remote OpenAI Codex OAuth still presents paste input immediately.
• Browser callback completion can cancel/dismiss the manual paste prompt without pasted input.
• The implementation does not rely on monitoring OpenAI token-exchange requests as the primary success signal.
• Paste-only and SSH-forwarded callback paths are both covered by focused tests or equivalent proof.
• Any shared prompt-cancellation seam is generic, while OpenAI-specific OAuth behavior remains owned by the OpenAI provider/plugin.

Related work

• fix(openai): clarify remote Codex OAuth prompt #81301 updates the near-term remote prompt wording so first-time users see redirect-URL paste instructions plus an automatic-completion caveat. It does not change manualInputPromptMessage or OAuth control flow.
• fix(auth): support remote Codex OAuth manual input #51631 added earlier remote manual-input integration.
• OpenAI Codex OAuth port conflict still opens browser to occupied localhost:1455 and produces confusing state failure #80963 covers adjacent fixed-port callback UX.
• [Feature]: Non-interactive command to use Codex OAuth for model provider #47750 covers adjacent non-interactive Codex OAuth needs.

Duplicate search performed before filing:

• gh search issues --repo openclaw/openclaw --match title,body -- "OpenAI Codex OAuth manual prompt callback"
• gh search issues --repo openclaw/openclaw --match title,body -- "OAuth onManualCodeInput callback token exchange"
• gh search issues --repo openclaw/openclaw --match title,body -- "openai-codex oauth"
• gh search prs --repo openclaw/openclaw --match title,body -- "onManualCodeInput"

No existing issue was found for this callback-settled prompt contract.