PR #81301: fix(openai): clarify remote Codex OAuth prompt

• Repository: openclaw/openclaw
• Author: rubencu
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/81301

Description (problem / solution / changelog)

Summary

• Problem: Remote/VPS OpenAI Codex OAuth copy said to paste after signing in, but SSH-tunneled users can have the browser callback complete automatically before they paste anything.
• What changed: The remote note now gives paste-first instructions for the redirect URL and adds a final caveat that sign-in may finish automatically if the OpenClaw process can receive the browser callback.
• What did NOT change: manualInputPromptMessage, OAuth timing, callback handling, prompt cancellation, token exchange behavior, provider contracts, and config surface are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #81405
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: OpenAI Codex OAuth in a remote/VPS shell should present the redirect-URL paste path first, while warning SSH-tunneled users that sign-in may still finish automatically before they paste.
• Real environment tested: Local OpenClaw source checkout on Linux at PR head c7285edebb5611c461dd3895fd114ece7cada5a2, Node v22.22.2. The proof command inspected the production core provider and bundled OpenAI plugin runtime strings that ship this user-visible copy.
• Exact steps or command run after this patch: node <<'NODE' ... verify production OpenAI Codex OAuth prompt strings, unchanged manual prompt, and old remote fallback-first wording absence ... NODE
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Console output from the source-string smoke at the PR head:

head: c7285edebb5611c461dd3895fd114ece7cada5a2
node: v22.22.2
remote note: A URL will be shown for you to open in your LOCAL browser. / Open it, sign in, then paste the redirect URL here. / If this OpenClaw process can receive the browser callback, sign-in may finish automatically before you paste.
manual prompt unchanged from origin/main: Paste the authorization code (or full redirect URL):
old remote fallback-first wording present: no

• Observed result after fix: Both OpenAI Codex OAuth implementations now present redirect-URL paste as the primary remote instruction, preserve LOCAL browser emphasis, and mention automatic callback completion only as the tunneled-case caveat. The manual input prompt remains the current origin/main text.
• What was not tested: A live third-party OpenAI browser/account login; this PR changes only displayed text and does not change OAuth control flow.
• Before evidence (optional but encouraged): Current base remote note contains After signing in, paste the redirect URL back here. in src/plugins/provider-openai-codex-oauth.ts and extensions/openai/openai-codex-oauth.runtime.ts.

Root Cause (if applicable)

• Root cause: The remote/VPS copy was written for paste-only remote/headless setups, but SSH port forwarding can make the local OAuth callback reachable from the user's local browser.
• Missing detection / guardrail: The test suite did not lock the remote explanatory copy against the intended paste-first wording plus tunneled-callback caveat.
• Contributing context (if known): No-tunnel users still need paste instructions immediately, so delaying or hiding paste would regress that path.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/plugins/provider-openai-codex-oauth.test.ts
• Scenario the test should lock in: Remote OpenAI Codex OAuth notes describe redirect-URL paste as the primary remote path and automatic callback completion as a possible tunneled-case outcome.
• Why this is the smallest reliable guardrail: The bug is the displayed provider-owned copy, not OAuth transport behavior.
• Existing test that already covers this (if any): Existing remote manual-input tests covered the prompt path but not the explanatory note wording.
• If no new test is added, why not: N/A; a regression assertion was added.

User-visible / Behavior Changes

Remote OpenAI Codex OAuth wording now tells users to open the URL in their LOCAL browser, sign in, and paste the redirect URL. It also warns that sign-in may finish automatically before paste if the browser callback can reach OpenClaw. The manual paste prompt text itself is unchanged.

Diagram (if applicable)

Before:
remote auth URL -> copy says paste after sign-in -> tunneled callback may still complete automatically -> confusing stale expectation

After:
remote auth URL -> paste-first redirect URL instruction -> optional auto-completion caveat for tunneled callbacks

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node v22.22.2, pnpm repo wrapper
• Model/provider: OpenAI Codex OAuth provider copy
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Compare the remote OpenAI Codex OAuth note and manual input prompt on origin/main.
2. Apply this patch.
3. Run the source-string smoke, focused provider test, whitespace check, and Codex review.

Expected

• Remote copy gives paste-first redirect URL instructions and separately warns that callback completion may happen automatically for tunneled setups.
• The manual paste prompt is unchanged.

Actual

• Remote copy and regression test match that expectation.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Verification

• pnpm exec oxfmt --write --threads=1 src/plugins/provider-openai-codex-oauth.ts src/plugins/provider-openai-codex-oauth.test.ts extensions/openai/openai-codex-oauth.runtime.ts
• pnpm test src/plugins/provider-openai-codex-oauth.test.ts -- --reporter=verbose (17 tests passed)
• git diff --check origin/main...HEAD
• source-string smoke for core provider and bundled OpenAI plugin runtime, including unchanged manual prompt proof
• codex review --base origin/main (clean on the current head)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: The exact production copy at the PR head, focused provider tests, source-string smoke for both implementations, and local Codex review.
• Edge cases checked: The old fallback-first remote wording is absent from both the core provider and bundled OpenAI plugin runtime; manualInputPromptMessage remains identical to origin/main; no OAuth lifecycle code changed.
• What you did not verify: A live third-party OpenAI browser/account login.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

The existing top-level ClawSweeper comment refers to the previous callback-cancellation implementation. This branch has since been rewritten to the narrower wording-only patch and should receive fresh automation/maintainer review on the new head.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: The prompt can still remain visible after an SSH-forwarded callback succeeds, because this PR intentionally avoids the heavier callback-cancellation implementation.
  • Mitigation: The wording now warns that automatic completion may happen before paste; #81405 tracks the optional longer-term contract if maintainers want active prompt dismissal later.

Changed files

• CHANGELOG.md (modified, +1/-0)
• extensions/openai/openai-codex-oauth.runtime.ts (modified, +2/-1)
• src/plugins/provider-openai-codex-oauth.test.ts (modified, +18/-0)
• src/plugins/provider-openai-codex-oauth.ts (modified, +2/-1)