{"skill":{"slug":"openai-codex-multi-oauth","displayName":"OpenAI Codex Multi OAuth","summary":"Manage and debug multiple OpenAI Codex OAuth profiles inside OpenClaw, including native multi-profile auth stores and external-router setups where one active...","description":"---\nname: openai-codex-multi-oauth\ndescription: Manage and debug multiple OpenAI Codex OAuth profiles inside OpenClaw, including native multi-profile auth stores and external-router setups where one active slot is backed by a repository of multiple OAuth identities. Use when fixing Codex profile switching, session `authProfileOverride` sync, `/status` or usage mismatches, auth.order behavior, active-slot routing, broken-token recovery, or same-email different-account/workspace selection bugs.\n---\n\n# OpenAI Codex Multi OAuth\n\nSupport and debug more than one `openai-codex` OAuth login inside OpenClaw.\n\n## Human-facing overview\n\nThis skill is also meant to help a human operator understand the setup, not only help an agent patch code.\n\nWhat humans usually want to know:\n\n- which Codex profile the current chat is using\n- whether the current chat has its own pinned profile override\n- whether OpenClaw auto-switched after rate limits\n- whether `/status` usage matches the profile they expected\n- why two profiles may look similar even when they should stay distinct\n\nCommon user-facing surfaces in real deployments:\n\n- `/status` — confirm the current chat's selected model, profile semantics, and usage summary\n- `/codex_profile` — an optional helper command in some setups for viewing or switching the current Codex profile\n- `/codex_usage` — an optional helper command in some setups for comparing live usage across profiles\n\nTreat `/codex_profile` and `/codex_usage` as common patterns, not guaranteed OpenClaw built-ins.\n\n## Start here\n\n1. Run `python3 scripts/summarize_codex_profiles.py`.\n2. If usage is involved, also run `python3 scripts/codex_usage_report.py`.\n3. Classify the bug before patching anything.\n4. Change the smallest wrong layer.\n5. Re-test after every change.\n\nIf the target setup includes a local helper command or router script, reproduce through that real entrypoint at least once. Synthetic env-injected tests can miss session-sync bugs.\n\n## Mental model\n\nTreat these as separate layers:\n\n- **stored preference** — any saved local pointer such as `codex_profile_id`\n- **auth order** — `order.openai-codex` in the auth store\n- **session override** — `authProfileOverride` for the current chat/session\n- **effective runtime profile** — the profile that actually handled the request after selection or failover\n- **usage source** — the token/accountId used by usage-fetch logic\n- **display metadata** — the label shown to the user, such as email/workspace\n- **optional external profile repo** — a separate file or store that keeps multiple Codex OAuth identities while runtime uses one active slot\n\nDo not assume these layers always match.\n\n## Common architectures\n\n### A. Native auth-store setup\n\nOpenClaw stores multiple `openai-codex:*` profiles directly in `auth-profiles.json`, and runtime resolves selection from auth order plus session override.\n\n### B. External-router setup\n\nA local repo of Codex OAuth identities exists outside normal runtime selection, and a helper/router copies one selected profile into an active slot such as `openai-codex:default`.\n\nIn that design, verify all of these separately:\n- repo profile selected by the router\n- active slot content after routing\n- current session `authProfileOverride`\n- `/status` oauth label\n- `/status` usage source\n\n## Decision tree\n\n### 1) The wrong account is selected\n\nCheck in this order:\n1. stored preference or helper-selected profile\n2. `order.openai-codex`\n3. session `authProfileOverride`\n4. effective runtime profile\n5. whether failover is expected or a bug\n\n### 2) `/codex_profile`-style helper switches profile, but `/status` does not follow\n\nCheck:\n1. whether the helper changed only the active slot or also the current session override\n2. whether the current chat/session was correctly identified\n3. whether the environment that invokes the helper is missing chat/session metadata\n4. whether the platform keeps companion session entries that also need syncing\n\nIf the helper is real, re-test through the real command path, not only manual edits.\n\n### 3) `/status` oauth changes, but usage does not\n\nCheck:\n1. current session `authProfileOverride`\n2. the effective runtime profile for the current chat\n3. whether the usage loader resolves auth from generic provider order instead of the current session profile\n4. whether the UI is mixing preferred-profile and effective-profile semantics\n5. whether the usage fetch hard-pins the exact inspected profile or only passes a soft preference\n\n### 4) Two profiles show the same usage unexpectedly\n\nCheck:\n1. whether they share the same `accountId` because they are in the same team workspace\n2. whether `user_id` is still different in the live `wham/usage` response\n3. whether the local code accidentally fetched usage with the wrong token because provider-order fallback overrode the intended profile\n4. whether the same-looking result was intermittent, which usually points to local selection/fallback bugs rather than backend quota semantics\n\n### 5) A profile works sometimes but not always\n\nCheck:\n1. cooldown / last-good logic\n2. token expiry\n3. soft-pin vs hard-pin semantics\n4. whether failover is expected behavior or a bug\n\n### 5) A token or profile entry is broken\n\nCheck:\n1. whether the same `accountId` exists in another store or backup\n2. whether only one profile entry can be restored surgically\n3. whether local token parsing fails before request dispatch\n\n### 6) `/status`, display labels, and runtime truth disagree\n\nDecide which semantic each surface should represent:\n- preferred profile\n- effective runtime profile\n- usage source profile\n- display metadata label\n\nThen verify every layer against that semantic before patching.\n\n## Stable design rules\n\n- Prefer profile identity by `accountId` before email when possible.\n- Preserve different workspaces/accounts as separate profiles even when email matches.\n- Keep profile ids stable, for example:\n  - `openai-codex:default`\n  - `openai-codex:secondary`\n  - `openai-codex:tertiary`\n  - `openai-codex:account-N`\n- Do not blur preferred profile, effective runtime profile, and usage source profile.\n- Hard-pin the exact profile credential when implementing per-profile usage inspection; a provider-level preference is not always a guarantee.\n- A Telegram menu entry alone does not create a real executable command. Wire any `/codex_usage`-style surface into the actual command handler path.\n- If an external repo exists, treat it as a separate layer instead of silently merging it into runtime state.\n\n## Validation checklist\n\nAfter each change, verify all of these:\n\n1. stored preference or helper-selected profile is what you expect\n2. auth order is what you expect\n3. current session `authProfileOverride` is what you expect\n4. runtime actually uses the intended profile\n5. `/status` shows the intended semantic\n6. usage matches the intended semantic, or the difference is explicitly understood\n7. any helper command resolves the same profile id the runtime is using\n\n## Common operator examples\n\nUse examples like these when explaining the setup to a human:\n\n- \"Use `/codex_profile` to inspect or switch the profile for this chat if your deployment exposes that helper.\"\n- \"Use `/status` to confirm which profile the current chat prefers and whether usage looks aligned.\"\n- \"If a `/codex_usage` helper exists, compare profiles directly when usage looks suspicious.\"\n- \"If OpenClaw auto-rotated after rate limits, explain that the runtime may have switched profiles even if the user did not do it manually.\"\n\nWhen documenting commands, always say whether they are:\n\n- built into OpenClaw\n- local helper commands added by a specific deployment\n- examples that another operator may need to adapt\n\n## Bundled resources\n\n- Read `references/runtime-files.md` for the file families that usually matter.\n- Read `references/workflows.md` for concrete repair workflows and rollback points.\n- Read `references/usage-debugging.md` when the bug involves usage mismatches, same-workspace confusion, or a new `/codex_usage`-style command.\n- Run `scripts/summarize_codex_profiles.py` before and after changes.\n- Run `scripts/codex_usage_report.py` when you need exact per-profile live usage evidence.\n\n## Guardrails\n\n- Back up auth files or runtime bundles before editing them.\n- Prefer surgical patches over broad rewrites.\n- Keep version-specific assumptions explicit.\n- Do not restart the gateway unless the user asked.\n- Commit workspace skill changes after edits.\n","topics":["Debug","Email","Sync"],"tags":{"latest":"1.2.1"},"stats":{"comments":0,"downloads":688,"installsAllTime":26,"installsCurrent":0,"stars":0,"versions":4},"createdAt":1773587261554,"updatedAt":1778491928981},"latestVersion":{"version":"1.2.1","createdAt":1773754399738,"changelog":"Make the skill more human-facing: clarify common commands and surfaces such as /status, optional /codex_profile, optional /codex_usage, auto-switch behavior, and operator usage flows.","license":"MIT-0"},"metadata":null,"owner":{"handle":"wthh031230","userId":"s1741nr1y7mc0pe2wfrxzf2q2n844kx0","displayName":"WTHH031230","image":"https://avatars.githubusercontent.com/u/184518394?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089936487}}