docs: clarify legacy openai-codex auth

[jalehman]

What

Clarifies that OpenAI API-key profiles and ChatGPT/Codex OAuth profiles now both use the canonical openai provider id, while openai-codex is legacy migration input handled by doctor.

Why

Users searching for the old openai-codex auth provider wording could find doctor migration notes, but the general OAuth and authentication docs did not explicitly bridge that legacy name to current openai auth profile setup.

Changes

• Add auth reference guidance
• Add OAuth concept guidance
• Document doctor migration path

Testing

• pnpm docs:list
• pnpm docs:check-mdx
• pnpm format:docs:check
• git diff --check
• .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 3, 2026, 7:11 PM ET / 23:11 UTC.

Summary
The branch updates the OAuth and model authentication docs to say legacy openai-codex auth/profile/order state should migrate to canonical openai provider/profile ids.

PR surface: Docs +39. Total +39 across 2 files.

Reproducibility: not applicable. This PR updates documentation rather than reporting a runnable product bug. I verified the documented behavior against current source, adjacent docs, tests, and upstream Codex protocol/source.

Review metrics: none identified.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🌊 off-meta tidepool
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

• [P2] The protected maintainer label makes this a human merge decision, and there is no narrow repair finding for automation to address.

Security
Cleared: The PR changes only Markdown docs and does not touch executable code, dependencies, workflows, lockfiles, secrets, or package metadata.

Review details

Best possible solution:

Land the documentation clarification after maintainer review if the docs checks remain green; no code repair is needed for the reviewed diff.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR updates documentation rather than reporting a runnable product bug. I verified the documented behavior against current source, adjacent docs, tests, and upstream Codex protocol/source.

Is this the best way to solve the issue?

Yes. Updating the general OAuth and authentication pages is the narrow maintainable fix because the current provider, doctor migration, and OpenAI docs already establish the canonical openai route.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against c96a12d3c887.

Label changes

Label changes:

• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This is a low-risk docs clarification with no runtime or configuration surface changed.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence reviewed

PR surface:

Docs +39. Total +39 across 2 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	0	0	0	0
Docs	2	40	1	+39
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	2	40	1	+39

What I checked:

• Repository policy read and applied: Root policy requires full AGENTS.md review, scoped docs guidance, source-backed docs claims, and a direct Codex source check for Codex-related work; docs/AGENTS.md requires root-relative Mintlify links and generic docs content. (AGENTS.md:10, c96a12d3c887)
• PR docs add canonical auth guidance: The PR head states that OpenAI API-key auth and ChatGPT/Codex OAuth both use canonical provider id openai, and tells users to run doctor for legacy openai-codex:* profile ids and auth.order.openai-codex. Public docs: docs/concepts/oauth.md. (docs/concepts/oauth.md:22, 047d540459b0)
• PR docs add CLI recovery path: The PR head documents openclaw doctor --fix followed by openclaw models auth list --provider openai before copying repaired profile ids into auth order or model profile overrides. Public docs: docs/gateway/authentication.md. (docs/gateway/authentication.md:196, 047d540459b0)
• Current OpenAI docs already match the claim: Current main says OpenClaw uses one provider id, openai, for both auth shapes, and that doctor rewrites legacy Codex model refs, auth profile ids, and auth order to canonical OpenAI routing. Public docs: docs/providers/openai.md. (docs/providers/openai.md:10, c96a12d3c887)
• Current OpenAI provider exposes ChatGPT OAuth under openai: The current OpenAI provider test asserts provider id openai and auth methods oauth, device-code, and api-key, supporting the docs distinction between auth method and provider id. (extensions/openai/openai-chatgpt-provider.test.ts:26, c96a12d3c887)
• Doctor migration source backs the legacy-profile wording: Current doctor code recognizes openai-codex, allocates collision-safe openai:* profile ids, deletes legacy auth.order.openai-codex, and writes the rewritten order under auth.order.openai. (src/commands/doctor-auth-flat-profiles.ts:525, c96a12d3c887)

Likely related people:

• vincentkoc: Current-main blame/log for the OpenAI auth migration code, OAuth adapter, and OpenAI provider docs points to commit 8c89d35, which carries the canonical openai behavior this PR documents. (role: current behavior and docs provenance; confidence: medium; commits: 8c89d35a8ad8; files: src/commands/doctor-auth-flat-profiles.ts, src/llm/utils/oauth/openai-chatgpt.ts, docs/providers/openai.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.