OpenClaw OpenAI Multi Account

---

name: openclaw-openai-multi-account description: Manage multiple OpenAI OAuth login accounts inside OpenClaw, including OpenAI Codex OAuth account snapshots, switching, real active-account detection, 5-hour and weekly quota inspection via Codex CLI cache, ACTIVE metadata repair, auto-enrollment of newly logged-in accounts, same-model auto-rotation near exhaustion, and fallback to a backup model such as Bailian when all OpenAI accounts are unavailable. Use when the user asks about multiple OpenAI OAuth accounts in OpenClaw, OpenAI/Codex account switching, the current real active account, local saved accounts, 5h or weekly remaining quota, OAuth re-login, automatic account rotation, or fallback behavior in OpenClaw.

---

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 openclaw models auth login --provider openai-codex

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: scripts/openclaw-openai-accounts.py

Regression test script: scripts/test_openclaw_openai_accounts.py

State store: ~/.openclaw/openai-codex-accounts/

Run the bundled regression suite with:

python3 scripts/test_openclaw_openai_accounts.py

Daily local check command:

/home/djy/.openclaw/workspace-taizi/bin/check-openai-multi-account

It writes timestamped logs under:

/home/djy/.openclaw/workspace-taizi/data/openai-multi-account-checks/

First use

List current snapshots:

python3 scripts/openclaw-openai-accounts.py list

> list, 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 openclaw.json > - keep auth.order.openai-codex aligned with the saved account list and current active account > - add/remove matching named email profiles in each agent auth-profiles.json > - prune stale aliases that no longer correspond to any saved account

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

python3 scripts/openclaw-openai-accounts.py list --verbose --probe

Add an account (interactive OAuth login):

python3 scripts/openclaw-openai-accounts.py add --name work

Switch account:

python3 scripts/openclaw-openai-accounts.py use work

Auto-pick best account or fall back:

python3 scripts/openclaw-openai-accounts.py auto

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

python3 scripts/openclaw-openai-accounts.py cron-check

Important behavior

1. Canonical auth source

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

~/.openclaw/agents//agent/auth-profiles.json

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:

bailian/qwen3.5-plus

You can also override defaults via environment variables:

OPENCLAW_HOME — OpenClaw data root (default ~/.openclaw)

OPENCLAW_PRIMARY_AGENT — canonical agent whose auth file is treated as the real active auth (default taizi)

OPENCLAW_FALLBACK_MODEL — backup model to use when all OpenAI accounts are exhausted (default bailian/qwen3.5-plus)

Override it with:

python3 scripts/openclaw-openai-accounts.py auto --fallback-model bailian/glm-5

4. Automatic checks

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

python3 scripts/openclaw-openai-accounts.py auto --json

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:

python3 scripts/openclaw-openai-accounts.py auto --five-hour-switch-at 80 --five-hour-hard-switch-at 90 --weekly-switch-at 90 --weekly-hard-switch-at 95 --inactive-minutes 3
python3 scripts/openclaw-openai-accounts.py cron-check --five-hour-switch-at 80 --five-hour-hard-switch-at 90 --weekly-switch-at 90 --weekly-hard-switch-at 95 --inactive-minutes 3

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: 80%

5-hour hard switch threshold: 90%

weekly soft switch threshold: 90%

weekly hard switch threshold: 95%

inactivity guard: 3 minutes

Recommended workflow

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: - active account name - email - 5-hour usage - weekly usage - current primary model / fallback model

Health states

The script now distinguishes these states:

healthy: token works and rate limits were read successfully

auth-invalid: token/refresh/login is invalid and the account should be re-logged-in

plan-unavailable: token exists but the workspace/plan/model is not usable

quota-unknown: 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. the live credential is used via openai-codex:default 2. switching accounts writes the new token into openai-codex:default 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 :default

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 ~/.openclaw/openai-codex-accounts/

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/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.

This skill stores sensitive OAuth tokens under ~/.openclaw/openai-codex-accounts/

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/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.