Codex OAuth

codex-oauth is a CLI for managing multiple Codex accounts, rotating between them, and exposing a stable local proxy for Codex-compatible clients.

It is designed around three practical jobs:

• keep a local registry of Codex auth snapshots
• switch or rotate accounts when usage gets tight
• provide one local proxy endpoint so your clients do not need to care which account is active

[!IMPORTANT] After any account change, restart Codex CLI, the VS Code extension, or the Codex App so the new auth state is picked up.

Table of Contents

• Highlights
• Supported Clients and Platforms
• Install
• Quick Start
• Quick Setup (one-step)
• Command Reference
• Account Management
• Importing Accounts
• Auto-Switching
• Usage and Account API Refresh
• Telegram Alerts
• Local Proxy
• Manual Client Configuration
• Proxy Test Examples
• Troubleshooting
• Uninstall
• Disclaimer

Highlights

• add the currently logged-in Codex account into a managed local registry
• import auth files, CPA token exports, or Go-Pool JSON exports in bulk
• run setup to import accounts and enable auto-switching and proxy in one command
• remove accounts, clean stale files, and rebuild the registry index
• auto-switch accounts based on 5-hour and weekly usage thresholds
• run a local proxy with a stable base URL and API key
• install the proxy as a background service with proxy-daemon
• generate or apply local client configuration snippets
• send Telegram alerts on account errors, quota exhaustion, and quota reset countdowns

Supported Clients and Platforms

Works well with:

• Codex CLI
• Codex VS Code extension
• Codex App

Published npm packages are available for:

• Linux x64
• Linux arm64
• macOS x64
• macOS arm64
• Windows x64
• Windows arm64

For the smoothest login flow, install the official Codex CLI too:

npm install -g @openai/codex

Then you can sign in with Codex and add the current account with codex-oauth login.

Install

Install globally:

npm install -g @zenith139/codex-oauth

Or run it with npx:

npx @zenith139/codex-oauth list

Requirements:

• Node.js 18+

Quick Start

1. Log into Codex

codex login

2. Add the current account into the managed registry

codex-oauth login

3. Check what is stored

codex-oauth list
codex-oauth status

4. Optional: enable background auto-switching

codex-oauth config auto enable

5. Optional: run the local proxy

Foreground mode:

codex-oauth serve

Background service:

codex-oauth proxy-daemon --enable

Quick Setup (one-step)

Once you have accounts in the registry (via login or import), run:

codex-oauth setup

setup checks whether any accounts exist. If none are found, it prints instructions on how to add them. If accounts are present, it automatically:

1. Enables the auto-switch background daemon
2. Enables the proxy daemon
3. Applies Codex client config (points Codex at the local proxy)

After setup completes, open Codex and start working — accounts rotate automatically in the background.

Typical first-time workflow

# Step 1: add accounts (pick one method)
codex login && codex-oauth login          # from a live Codex session
codex-oauth import /path/to/auth.json    # from a single auth file
codex-oauth import /path/to/auth-dir/   # from a directory of auth files
codex-oauth import --cpa /path/to/cpa/  # from CPA token exports
codex-oauth import --gopool /path/to/gopool-dir/  # from Go-Pool exports

# Step 2: one command to configure everything
codex-oauth setup

Command Reference

Core Commands

| Command | Description | | --- | --- | | codex-oauth list | List available accounts | | codex-oauth status | Show auto-switch, API, and proxy status | | codex-oauth login | Login and add the current account | | codex-oauth setup | Check accounts, then enable auto-switch daemon and proxy in one step | | codex-oauth import <path> [--alias <alias>] | Import one auth file or a directory | | codex-oauth import --cpa [<path>] [--alias <alias>] | Import CPA flat token JSON | | codex-oauth import --gopool <path> | Import Go-Pool JSON exports | | codex-oauth import --purge [<path>] | Rebuild registry.json from auth files | | codex-oauth export [<query>\|--all] | Export selected account tokens as JSON | | codex-oauth remove [<query>\|--all] | Remove one or more accounts | | codex-oauth clean | Delete backup and stale files under accounts/ | | codex-oauth serve | Run the local Codex proxy | | codex-oauth proxy-daemon --enable\|--disable\|--status\|--restart | Manage the proxy daemon service |

Configuration Commands

| Command | Description | | --- | --- | | codex-oauth config auto enable | Enable background auto-switching | | codex-oauth config auto disable | Disable background auto-switching | | codex-oauth config auto --5h <percent> [--weekly <percent>] | Configure auto-switch thresholds | | codex-oauth config api enable | Enable usage and account API refresh | | codex-oauth config api disable | Disable usage and account API refresh | | codex-oauth config proxy | Show current proxy settings | | codex-oauth config proxy --port <port> | Set proxy listen port | | codex-oauth config proxy --api-key <value> | Set the local proxy API key | | codex-oauth config proxy --strategy <fill-first\|round-robin> | Set account selection strategy | | codex-oauth config proxy --round-robin <on\|off> | Toggle round-robin account selection | | codex-oauth config proxy --sticky-limit <count> | Set the round-robin stickiness limit | | codex-oauth config proxy --manual-config | Print local client config snippets | | codex-oauth config proxy --apply-config | Write local client config files | | codex-oauth config proxy --reset-config | Revert Codex config files to plain OAuth login | | codex-oauth config telegram --token <bot-token> | Link a Telegram bot for account alerts | | codex-oauth config telegram --test | Send a sample alert to the linked Telegram chat |

Account Management

Add the Current Account

codex-oauth login

This reads the currently active Codex auth and stores it as a managed snapshot.

List Accounts

codex-oauth list

Remove Accounts

Interactive remove:

codex-oauth remove

Remove by query:

codex-oauth remove [email protected]

Remove everything:

codex-oauth remove --all

Clean Backups and Stale Files

codex-oauth clean

This removes old backup files and stale account artifacts under ~/.codex/accounts/.

Importing Accounts

Import a Single Auth File

codex-oauth import /path/to/auth.json --alias personal

Import a Directory of Auth Files

codex-oauth import /path/to/auth-exports

Typical output:

Scanning /path/to/auth-exports...
  ✓ imported  [email protected]
  ✓ updated   [email protected]
  ✗ skipped   token_invalid: MalformedJson
Import Summary: 1 imported, 1 updated, 1 skipped (total 3 files)

Import CPA Token Exports

codex-oauth can import flat JSON token files from CLIProxyAPI:

codex-oauth import --cpa
codex-oauth import --cpa /path/to/cpa-dir
codex-oauth import --cpa /path/to/token.json --alias work

Import Go-Pool JSON Exports

codex-oauth can import account files exported from Go-Pool (e.g. from a zip archive):

# Unzip the archive first, then import the directory
unzip accounts.zip -d gopool-exports
codex-oauth import --gopool gopool-exports

Go-Pool JSON files use a different schema (no id_token, separate credential fields). codex-oauth converts them automatically on import.

Rebuild the Registry From Existing Auth Files

If the registry is out of sync with the files on disk:

codex-oauth import --purge
codex-oauth import --purge /path/to/auth-exports

This does not import new files. It re-indexes the auth files that already exist.

Exporting Accounts

Export selected account tokens in a flat JSON array:

codex-oauth export
codex-oauth export [email protected]
codex-oauth export --all

Each exported object contains accessToken, refreshToken, idToken, and email.

Auto-Switching

Enable:

codex-oauth config auto enable

Disable:

codex-oauth config auto disable

Adjust thresholds:

codex-oauth config auto --5h 12
codex-oauth config auto --5h 12 --weekly 8
codex-oauth config auto --weekly 8

By default, auto-switching moves away from the current account when either:

• 5-hour remaining usage drops below 10%
• weekly remaining usage drops below 5%

Background worker model by platform:

• Linux and WSL: user-level systemd
• macOS: LaunchAgent
• Windows: scheduled task

Usage and Account API Refresh

Enable API-backed refresh:

codex-oauth config api enable

Disable API-backed refresh and fall back to local-only data:

codex-oauth config api disable

When API mode is on:

• usage refresh uses the remote usage endpoint
• account metadata refresh uses the remote account endpoint

When API mode is off:

• usage is read from local rollout or session files when possible
• account API refresh is skipped

Check the current mode with:

codex-oauth status

Telegram Alerts

codex-oauth can push a Telegram message whenever it detects a problem: an account's credentials stop working, a 5-hour or weekly quota is running low or fully exhausted, or the local proxy gets an upstream error (401/403/429/5xx) while serving a request.

Link a Bot

Create a bot with @BotFather and copy its token, then run:

codex-oauth config telegram --token <bot-token>

This verifies the token, saves it, then waits (~50s) for you to send any message to the bot on Telegram so it can automatically detect your chat_id — no need to look it up yourself. Once linked, a welcome message confirms the connection and alerts are enabled.

If the message doesn't arrive in time, message the bot and retry chat-id detection:

codex-oauth config telegram --relink

Manage Alerts

codex-oauth config telegram          # show status (masked token, chat id, enabled, linked-at)
codex-oauth config telegram --test   # send a sample alert
codex-oauth config telegram --enable
codex-oauth config telegram --disable
codex-oauth config telegram --unlink # forget the saved token and chat id

What Triggers an Alert

• Account errors and quota alerts — checked by the background auto-switch daemon, so they require auto-switching to be enabled (codex-oauth config auto enable).
• Proxy request errors — sent by the running local proxy (codex-oauth serve or proxy-daemon --enable), independent of auto-switch.

Local Proxy

Show Current Proxy Settings

codex-oauth config proxy

Example output:

proxy base-url: http://127.0.0.1:4318/v1
proxy strategy: round-robin
proxy sticky-limit: 3
proxy api-key: Q5qu...2EJ-

Update Proxy Settings

codex-oauth config proxy --port 4318
codex-oauth config proxy --api-key my-local-key
codex-oauth config proxy --strategy round-robin
codex-oauth config proxy --round-robin off
codex-oauth config proxy --sticky-limit 3

--round-robin <on|off> is a shortcut for --strategy round-robin / --strategy fill-first.

Run the Proxy in the Foreground

codex-oauth serve

The proxy listens on 127.0.0.1:4318 by default and exposes:

• GET /healthz
• GET /v1/models
• POST /v1/responses
• POST /v1/messages
• POST /v1/messages/count_tokens

Install the Proxy as a Background Service

codex-oauth proxy-daemon --enable
codex-oauth proxy-daemon --status
codex-oauth proxy-daemon --restart
codex-oauth proxy-daemon --disable

Platform-specific service type:

• Linux: user systemd service
• macOS: LaunchAgent
• Windows: scheduled task launching codex-oauth-proxy.exe

The daemon reuses the proxy listen host, port, strategy, and API key from codex-oauth config proxy.

Manual Client Configuration

Print generated config snippets:

codex-oauth config proxy --manual-config

Apply generated config files automatically:

codex-oauth config proxy --apply-config

Current generated files:

• ~/.codex/config.toml
• ~/.codex/auth.json
• ~/.claude/settings.json

Reset Codex Config Back to Plain OAuth

If you no longer want Codex clients to go through the local proxy/API and prefer to sign in directly with your own account via codex login, revert the config changes that --apply-config made:

codex-oauth config proxy --reset-config
codex login

This removes the proxy-managed model, model_provider, model_reasoning_effort, service_tier, and [model_providers.codex_oauth] entries from ~/.codex/config.toml (leaving unrelated settings untouched), and deletes ~/.codex/auth.json if it only contains the proxy API key so codex login can write fresh OAuth tokens.

For Codex, the generated config uses:

• model gpt-5.5
• model_provider = "codex_oauth"
• model_reasoning_effort = "high"
• wire_api = "responses"
• requires_openai_auth = true, so Codex sends the proxy API key from ~/.codex/auth.json

Re-running codex-oauth setup or codex-oauth config proxy --apply-config also repairs older generated provider blocks that omitted requires_openai_auth or set it to false.

Proxy Test Examples

Health Check

curl -sS http://127.0.0.1:4318/healthz

Expected response:

{"ok":true}

List Models

curl -sS http://127.0.0.1:4318/v1/models \
  -H 'Authorization: Bearer YOUR_PROXY_API_KEY'

Send a Simple Codex Request

When calling /v1/responses directly, the upstream Codex backend expects instructions and store: false.

curl -sS http://127.0.0.1:4318/v1/responses \
  -H 'Authorization: Bearer YOUR_PROXY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are a concise assistant.",
    "store": false,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Say hello in Vietnamese in one short sentence."
          }
        ]
      }
    ],
    "stream": false
  }'

Streaming Request

curl -N http://127.0.0.1:4318/v1/responses \
  -H 'Authorization: Bearer YOUR_PROXY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.5",
    "instructions": "You are a concise assistant.",
    "store": false,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Say hello in Vietnamese in one short sentence."
          }
        ]
      }
    ],
    "stream": true
  }'

Troubleshooting

My usage limit is stale

If codex-oauth is in local-only mode, it reads usage data from the newest rollout or session files under ~/.codex/sessions/. Those files can lag behind the real usage state.

Switch back to API mode:

codex-oauth config api enable
codex-oauth status

status should show:

usage: api
account: api

I upgraded the proxy but behavior did not change

Restart the managed daemon after upgrades:

codex-oauth proxy-daemon --restart

If you run the proxy in the foreground, stop the old process and start codex-oauth serve again.

Interactive remove says it needs a TTY

Use a non-interactive selector instead:

codex-oauth remove [email protected]
codex-oauth remove --all

Uninstall

Remove the npm package:

npm uninstall -g @zenith139/codex-oauth

Disclaimer

This project is provided as-is. Use it at your own risk.

When API mode is enabled, codex-oauth sends your account access token to OpenAI endpoints for usage and account refresh. Depending on your environment and OpenAI policy enforcement, this may create account risk. You are responsible for deciding whether to use that mode.