OpenClaw OpenAI Account Switcher

Use this skill for multiple OpenAI OAuth login accounts managed inside OpenClaw, especially OpenClaw's own openai-codex OAuth accounts, not just plain Codex CLI account files.

What this skill does

• - Save the current OpenClaw openai-codex:default OAuth profile as a named snapshot
• Add a new account by running INLINECODE2
• Switch all agents to a named snapshot
• Show the current active account (email/account id when available)
• Show cached/observed 5-hour and weekly usage when quota data can be collected
• Auto-switch to the account with remaining quota
• Fall back to a backup model when all accounts are exhausted

Files

• - Main script: INLINECODE3
• Regression test script: INLINECODE4
• State store: INLINECODE5

Run the bundled regression suite with:

CODEBLOCK0

Daily local check command:

CODEBLOCK1

It writes timestamped logs under:

• - INLINECODE6

First use

List current snapshots:

CODEBLOCK2

INLINECODE7, add, use, auto, and cron-check all reconcile the current live OpenClaw login back into the saved account list before reporting or switching, so out-of-band openclaw models auth login --provider openai-codex changes are picked up automatically.
The same reconciliation also keeps related OpenClaw auth metadata in sync:

• - add missing auth.profiles email aliases in INLINECODE14
• keep auth.order.openai-codex aligned with the saved account list and current active account
• add/remove matching named email profiles in each agent INLINECODE16
• prune stale aliases that no longer correspond to any saved account

Probe real quota via Codex CLI and show it in the list:

CODEBLOCK3

Add an account (interactive OAuth login):

CODEBLOCK4

Switch account:

CODEBLOCK5

Auto-pick best account or fall back:

CODEBLOCK6

Auto-check mode for cron/systemd (single-line notification-friendly output):

CODEBLOCK7

Important behavior

1. Canonical auth source

This skill treats OpenClaw agent auth files as the source of truth:

• - INLINECODE17

It updates all configured agents to keep openai-codex:default aligned.

2. Quota collection

Quota collection works in two modes:

• - Preferred: if a matching Codex CLI account snapshot exists and codex is installed, collect real 5-hour / weekly rate-limit data
• Fallback: if no Codex CLI snapshot exists, keep local observations and report that quota is unknown

3. Fallback model

Default backup model is:

• - INLINECODE20

You can also override defaults via environment variables:

• - OPENCLAW_HOME — OpenClaw data root (default ~/.openclaw)
• INLINECODE23 — canonical agent whose auth file is treated as the real active auth (default taizi)
• INLINECODE25 — backup model to use when all OpenAI accounts are exhausted (default bailian/qwen3.5-plus)

Override it with:

CODEBLOCK8

4. Automatic checks

Run periodically with cron/systemd/loop. Example one-shot command:

CODEBLOCK9

A good interval is every 10-15 minutes.

For unattended auto-switching, prefer a two-stage threshold with a short inactivity guard. The bundled script now supports:

CODEBLOCK10

This means:

• - when 5-hour usage reaches 80% (about 20% left), attempt switching only if no non-cron session across configured agents has been active within the last 3 minutes
• when 5-hour usage reaches 90% (about 10% left), switch immediately to avoid hitting rate limits, even if sessions are active
• when weekly usage reaches 90% (about 10% left for the week), attempt switching only if no non-cron session across configured agents has been active within the last 3 minutes
• when weekly usage reaches 95% (about 5% left for the week), switch immediately to preserve the remaining weekly quota

Recommended policy

Use this policy by default:

• - Check every 10 minutes
• At 5-hour usage 80%: try switching only when all non-cron sessions have been inactive for 3 minutes
• At 5-hour usage 90%: switch immediately to avoid rate limits
• At weekly usage 90%: try switching only when all non-cron sessions have been inactive for 3 minutes
• At weekly usage 95%: switch immediately to preserve the remaining weekly quota
• Prefer staying on the current account if it is still under both soft thresholds
• Prefer same-model account rotation (openai-codex/gpt-5.4 → another openai-codex/gpt-5.4 account)
• Fall back to a backup model only when all accounts are above threshold or quota is unknown

Default thresholds in the script:

• - 5-hour soft switch threshold: INLINECODE29
• 5-hour hard switch threshold: INLINECODE30
• weekly soft switch threshold: INLINECODE31
• weekly hard switch threshold: INLINECODE32
• inactivity guard: 3 minutes

Recommended workflow

1. 1. Add at least two accounts
2. Run list --verbose to verify identities
3. Run auto to validate selection logic
4. When the user wants automation, schedule auto periodically
5. When switching happens, report:

Health states

The script now distinguishes these states:

• - healthy: token works and rate limits were read successfully
• INLINECODE38: token/refresh/login is invalid and the account should be re-logged-in
• INLINECODE39: token exists but the workspace/plan/model is not usable
• INLINECODE40: quota could not be determined yet

These states appear in list --verbose and status.

Important implementation note

After inspecting OpenClaw source (/tmp/openclaw/src/commands/models/auth.ts and /tmp/openclaw/src/commands/onboard-auth.credentials.ts) plus live runtime files, the built-in openclaw models auth login --provider openai-codex has these practical semantics:

1. 1. the live credential is used via INLINECODE46
2. switching accounts writes the new token into INLINECODE47
3. email-specific profiles such as openai-codex:user@example.com are kept as named records
4. sibling agent auth stores are synced together
5. existing usageStats and lastGood are preserved instead of being cleared

This skill now mirrors that model:

• - real active-account detection keys off the live openai-codex:default credential
• snapshots keep a stable email-based identity instead of relying on ambiguous INLINECODE52
• switching rewrites :default across all agents while also retaining/upserting the email-specific profile entry
• metadata migration repairs older snapshot records that incorrectly treated :default as a unique account id
• email is the canonical human identity for deduplication; accountId may change when the same email moves to a different workspace/team, so same-email re-logins update the existing saved account instead of creating a duplicate

Notes

• - This skill stores sensitive OAuth tokens under INLINECODE56
• Treat those files like credentials
• Prefer list --verbose or status before making risky changes
• Active account display is derived from the real OpenClaw auth file (~/.openclaw/agents/<agent>/agent/auth-profiles.json), then synced back into skill metadata. This avoids stale ACTIVE markers after manual openclaw models auth login or other out-of-band auth changes.
• During periodic checks, if the real current OpenClaw auth is not present in the list yet, the skill will auto-enroll it as a new accountN snapshot and mark it active.