ai-auth-switch

Switch auth profiles for AI coding agents while keeping the app's normal configuration, history, sessions, and cache layout unchanged.

The first provider is Codex. The design keeps Codex itself as the source of truth for everything except the active auth file:

• ~/.codex/config.toml is not rewritten.
• ~/.codex/history.jsonl, sessions/, skills/, and other Codex state stay in place.
• auth.json is the only active Codex file switched.
• Saved profiles live outside Codex under ~/.local/share/ai-auth-switch/.
• Hermes/OpenClaw Codex-dependent auth state is synchronized after Codex auth changes.

Install From Checkout

python -m pip install -e .

You can also run without installation:

./bin/ai-auth-switch --help

Codex Usage

Save the currently active Codex login:

ai-auth-switch auth save codex

The profile name is inferred from the email inside the Codex OAuth token when available. If the token does not expose an email, the fallback is chatgpt-<account-id-prefix>.

Login a new Codex account and save it:

ai-auth-switch auth login codex

Optionally force a profile name:

ai-auth-switch auth login codex work

List and switch profiles:

ai-auth-switch auth list
ai-auth-switch auth list codex
ai-auth-switch auth use codex someone@example.com
ai-auth-switch auth current codex

After Codex auth is saved, logged in, or switched, ai-auth-switch also syncs Codex-dependent local tools: Hermes gets openai-codex credentials imported from the active Codex auth, and OpenClaw is pointed at its Codex CLI default profile. You can run that step explicitly too:

ai-auth-switch auth sync codex

On a fresh install, auth list can be empty even when Codex is already logged in. Import the active Codex auth first:

ai-auth-switch auth save codex

If you run as another Unix user, make sure CODEX_HOME points at the Codex config directory you actually use, or pass --codex-home /path/to/.codex.

Run Codex with a profile for the lifetime of one process, then restore the previous active auth:

ai-auth-switch run codex someone@example.com -- codex -C ~/workspace/project

Directory Overrides

By default Codex auth is read from:

$CODEX_HOME/auth.json

or, when CODEX_HOME is unset:

~/.codex/auth.json

Override it explicitly:

ai-auth-switch --codex-home /path/to/.codex auth list codex

The profile store can be moved with:

AI_AUTH_SWITCH_HOME=/secure/path ai-auth-switch auth list codex

Architecture

ai-auth-switch has two separate layers:

• Auth management: save, list, activate, rename, remove, and inspect profiles.
• Wrapper: run a command under a selected profile without permanently changing the active profile after the command exits.

Provider support is intentionally small. A provider only needs to define where its active auth file lives, how to infer a profile name, and which login command should be run for interactive login.