codex-account-switcher

SKILL.md content

---
name: codex-account-switcher
description: Manage multiple OpenAI Codex accounts. Capture current login tokens and switch between them instantly.
metadata:
  clawdbot:
    emoji: "🎭"
    requires:
      bins: ["python3"]
---

# Codex Account Switcher

Manage multiple OpenAI Codex identities (e.g. personal vs. work) by swapping the authentication token file.

## Usage

### 1. List Accounts
Show saved accounts (active one is marked with `ACTIVE` on the right). Default output is compact.

- `--verbose` includes refresh age + token TTL (debug)
- `--json` outputs the verbose info as JSON
```bash
./codex-accounts.py list
```

To include emails/diagnostics:
```bash
./codex-accounts.py list --verbose
```

### 2. Add an Account
Interactive wizard to capture login(s).

- **Always starts a fresh browser login** (`codex logout && codex login`) so you explicitly choose the identity to capture.
- After each login it saves a snapshot.
- In an interactive terminal it asks if you want to add another.
- When invoked non-interactively (e.g. via Clawdbot), it runs **single-shot** (no "add another" prompt).
- When naming an account, **press Enter** to accept the default name (local-part of the detected email, e.g. `oliver` from `oliver@…`).

```bash
./codex-accounts.py add
```

### 3. Switch Account
Instantly swap the active login.
```bash
./codex-accounts.py use work
```

### 4. Auto-Switch to Best Quota
Check all accounts and switch to the one with most weekly quota available.
```bash
./codex-accounts.py auto
./codex-accounts.py auto --json
```

Output:
```
🔄 Checking quota for 2 account(s)...

  → sylvia... weekly 27% used
  → oliver... weekly 100% used

✅ Switched to: sylvia
   Weekly quota: 27% used (73% available)

All accounts:
   sylvia: 27% weekly ←
   oliver: 100% weekly
```

## How It Works

- Stores `auth.json` files in `~/.codex/accounts/<name>.json`.
- Identifies accounts by decoding the JWT `id_token` to find the email address.
- "Switching" simply overwrites `~/.codex/auth.json` with the saved copy.

## Installation

Add the script to your path for easy access:
```bash
ln -s $(pwd)/codex-accounts.py ~/bin/codex-accounts
```

How this skill works

• On invocation with action=\"list\": Returns list of available accounts and current active account
• On invocation with action=\"switch\" and valid account: Switches to the specified account, sets it as current, and confirms
• Accounts are stored in a persistent store (file-based JSON at ~/.openclaw/codex-accounts.json)
• Current active account is tracked in the same store
• Validates account existence before switching
• If invalid account specified, returns error message without switching

When to use it

• When the agent needs to switch the active Codex account to a specified pre-configured account
• When managing multiple Codex accounts during extended API usage sessions

Best practices

• Configure accounts as an array of objects with 'name' and 'api_key' properties
• Set a 'default_account' value in the configuration
• Validate API keys before configuring the skill
• Store configuration securely since API keys are in plain text
• Do not commit API keys to version control systems

Example use cases

• Bypassing rate limits during intensive API usage: Switches to an alternative Codex account when the primary account hits OpenAI API rate limits, enabling continued task execution.
• Load balancing across multiple accounts: Rotates between configured Codex accounts to distribute API calls and prevent any single account from being throttled.
• Seamless continuation of long-running tasks: Automatically handles account switching mid-task to maintain workflow without interruption due to quota exhaustion.

FAQs