docs(providers/openai): note OpenAI Realtime requires Platform credits, not Codex/ChatGPT subscription#77215
Conversation
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 725a5371a9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Fix: top up Platform credits at | ||
| [platform.openai.com/account/billing](https://platform.openai.com/account/billing) | ||
| and configure `OPENAI_API_KEY` (or `talk.providers.openai.apiKey` / | ||
| `voice.realtime.openai.apiKey`) with a key from that organization. For chat |
There was a problem hiding this comment.
Replace nonexistent voice config path
Update this path because voice.realtime.openai.apiKey is not a recognized config key, so users who follow the note will set a value that OpenClaw never reads. The realtime voice provider consumes plugins.entries.voice-call.config.realtime.providers.openai.apiKey (or OPENAI_API_KEY), so the current doc can leave Voice Call realtime misconfigured even after applying the suggested fix.
Useful? React with 👍 / 👎.
|
Codex review: needs changes before merge. Reviewed May 27, 2026, 2:41 AM ET / 06:41 UTC. Summary PR surface: Docs +23. Total +23 across 2 files. Reproducibility: not applicable. as a docs PR; the linked report supplies the user confusion and current source confirms the documented config/auth paths. Review metrics: 1 noteworthy metric.
Merge readiness Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch. Rank-up moves:
Risk before merge
Maintainer options:
Copy recommended automerge instructionNext step before merge Security Review findings
Review detailsBest possible solution: Keep the OpenAI provider docs clarification, remove the Do we have a high-confidence way to reproduce the issue? Not applicable as a docs PR; the linked report supplies the user confusion and current source confirms the documented config/auth paths. Is this the best way to solve the issue? No as submitted: the docs note is the right narrow fix, but the normal PR should not carry a Full review comments:
Overall correctness: patch is incorrect AGENTS.md: found and applied where relevant. Codex review notes: model gpt-5.5, reasoning high; reviewed against 8c8162f1f7d7. Label changesLabel changes:
Label justifications:
Evidence reviewedPR surface: Docs +23. Total +23 across 2 files. View PR surface stats
Acceptance criteria:
What I checked:
Likely related people:
What the crustacean ranks mean
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
|
08837fc to
f954d6c
Compare
|
Addressed [P2] from codex review ( |
f954d6c to
cb74204
Compare
|
Requesting This is a docs-only PR that adds an inline note to The supporting context for the documented behavior (Codex OAuth account hitting Happy to add |
cb74204 to
de3da6c
Compare
…lback Address Codex review on PR openclaw#77215: - Use talk.realtime.provider / talk.realtime.providers.openai.apiKey instead of the speech/TTS talk.provider keys - Stop implying API-key auth is the only Realtime route; document the openai-codex OAuth fallback that mints Realtime client secrets Realtime still requires Platform credits, but the credentials path can be either a Platform OPENAI_API_KEY or an openai-codex OAuth profile whose organization has funded Platform credits.
775197f to
7682598
Compare
|
@steipete — flagging you for review since codex identified you as the recent area owner of the OpenAI realtime provider and |
…s, not Codex/ChatGPT subscription (openclaw#76498) Realtime voice (Voice Call realtime.provider: openai and Control UI Talk with talk.provider: openai) goes through the public OpenAI Platform Realtime API and needs an OPENAI_API_KEY whose organization has funded Platform credits. Codex/ChatGPT subscription quota does not cover this route, so an install whose openai-codex/* chat works fine can still hit insufficient_quota / 'You exceeded your current quota' on the first Realtime turn. Adds an inline note next to the Realtime row of the OpenAI capability matrix and a follow-up Note block that explains the symptom, the fix (top up Platform credits + configure OPENAI_API_KEY), and why openai-codex is not registered as a realtime voice provider. This was the central confusion in openclaw#76498. Documenting it inline prevents the same fail-then-discover loop for the next user.
7682598 to
1c309e6
Compare
|
ClawSweeper PR egg 🔥 Warming up: real-behavior proof passed; findings, security review, or rank-up moves are still in progress. Hatch commandComment Hatchability rules:
What is this egg doing here?
|
|
Maintainer verification before merge:
Maintainer note: changelog entry accepted for this landing. |
Summary
Adds an inline clarification to
docs/providers/openai.mdthat OpenAI Realtime voice (used by Voice Callrealtime.provider: "openai"and Control UI Talk withtalk.realtime.provider: "openai") is billed against OpenAI Platform credits rather than Codex/ChatGPT subscription quota. Documents both supported auth routes — direct PlatformOPENAI_API_KEYand theopenai-codexOAuth fallback that mints Realtime client secrets through the Platform API.Why
From #76498: a user with healthy Codex OAuth (where
openai-codex/*chat worked fine) hitYou exceeded your current quotaon the first Realtime turn, even though the ChatGPT/Codex usage dashboard still showed remaining quota. The Realtime route goes through the public OpenAI Platform Realtime API, so the underlying organization needs funded Platform credits — independent of which auth path mints the client secret. Nothing in the docs surfaced that distinction, so troubleshooting was guesswork.Changes
docs/providers/openai.mdYes (requires OpenAI Platform credits, not Codex/ChatGPT subscription), with the surface column updated to include the correcttalk.realtime.provider: "openai"Control UI Talk key.<Note>block under the matrix that:realtime.provider: "openai"for Voice Call,talk.realtime.provider: "openai"for Control UI Talk)insufficient_quota/ "You exceeded your current quota" on the first Realtime turn even when chat works)OPENAI_API_KEY(viatalk.realtime.providers.openai.apiKeyorplugins.entries.voice-call.config.realtime.providers.openai.apiKey) or anopenai-codexOAuth profile whose underlying organization has Platform billing — both routes mint Realtime client secrets through the Platform API, so either way the org needs funded Platform creditsCHANGELOG.md— Unreleased > Changes entry.Test plan
pnpm exec oxfmt --check --threads=1 docs/providers/openai.md CHANGELOG.md— cleangit diff --check— clean<Note>JSX block, no em-dashes inside headings.origin/main(HEAD8dc213227b); preserves thecodex-cli/<model>legacy-row addition that landed on main.Closes #76498.
Real behavior proof
Behavior or issue addressed: Fixes Docs/UX: Realtime Talk with OpenAI requires OpenAI Platform API credits, not Codex/ChatGPT subscription quota #76498. Users with healthy
openai-codexOAuth who tried OpenAI Realtime voice gotinsufficient_quotaon the first Realtime turn even though their Codex subscription worked fine for chat. The Realtime route is billed against OpenAI Platform credits regardless of whether the credential is a direct Platform API key or anopenai-codexOAuth profile — both mint client secrets through the Platform API. The original docs didn't mention this; users had no signposting from "Codex works" to "but Realtime needs Platform billing on the same org."Real environment tested: The patched
docs/providers/openai.mdas rendered by Mintlify (the production docs hosting layer atdocs.openclaw.ai). Config keys verified against currentmain:talk.realtime.provider/talk.realtime.providers.openai.apiKey—src/gateway/server-methods/talk-shared.ts:112(Talk realtime config readsconfig.talk?.realtime, not the top-level Talk speech provider map).openai-codexOAuth fallback —extensions/openai/realtime-voice-provider.ts:304callsresolveProviderAuthProfileApiKey({ provider: "openai-codex" })when no direct key is present; native bridge atextensions/openai/realtime-voice-provider.ts:645falls through to OAuth-backed client-secret creation.extensions/openai/realtime-voice-provider.test.ts:282covers minting an ephemeral Realtime secret from anopenai-codexOAuth token when no direct API key is configured.Exact steps or command run after this patch (HEAD
768259819e, rebased ontoorigin/mainat8dc213227b):Evidence after fix (current HEAD
768259819e): The rendered<Note>block atdocs/providers/openai.md:99now contains the corrected, OAuth-aware remediation:The Realtime voice row in the capability table at
docs/providers/openai.md:96carries the updatedYes (requires OpenAI Platform credits, not Codex/ChatGPT subscription)status note and includestalk.realtime.provider: "openai"for Control UI Talk in the surface column.Observed result after fix: A user hitting
insufficient_quotaon their first Realtime turn while theiropenai-codex/*chat keeps working can now find the explanation by reading the OpenAI provider docs — the capability table flags the Platform-credits requirement on the Realtime row, and the<Note>block tells them both (a) which org's billing they need to top up and (b) which config keys to point at the funded credential, including the OAuth path. Pre-fix, the docs page did not mention the billing split at all and operators had no signposting from "Codex works" to "but Realtime needs Platform billing."What was not tested: Live
insufficient_quotareproduction against a real OpenAI organization without Platform billing — the bug is a documentation gap, not a code regression; the underlying API contract (Codex subscription ≠ Platform credits) is established by OpenAI's billing system and verified by the original reporter in Docs/UX: Realtime Talk with OpenAI requires OpenAI Platform API credits, not Codex/ChatGPT subscription quota #76498.