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 and 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 is pointed at openai-codex and seeded with a Codex CLI access-token pool entry, so it follows the active Codex CLI account without handing turns to codex app-server. If hermes-gateway.service is active, it is restarted so Feishu and other messaging channels pick up the new auth immediately.
• Current OpenClaw installs are synchronized through the SQLite auth store by writing openai:default from the active Codex CLI OAuth token. Older JSON auth-state installs still use the legacy openai-codex:default bridge.

You can run that step explicitly too:

ai-auth-switch auth sync codex

Hermes does not import or share the Codex CLI refresh token. The sync clears Hermes's old independent openai-codex OAuth state, installs the current Codex CLI access token into Hermes's openai-codex credential pool, and leaves Hermes's openai_runtime on auto. Current OpenClaw versions no longer import Codex CLI auth from ~/.codex at runtime, so the sync writes the active Codex OAuth tokens into OpenClaw's own SQLite auth store as openai:default and clears any failure cooldown for that profile. Older OpenClaw JSON auth-state installs still fall back to the legacy openai-codex:default bridge profile.

The old Hermes login flag is kept only for command compatibility and is now a no-op:

ai-auth-switch auth sync codex --hermes-login

Use ai-auth-switch auth sync codex normally. Before restarting active gateway services, the current process's standard proxy variables (http_proxy, https_proxy, and their uppercase variants) are imported into the systemd user manager, so Hermes/OpenClaw do not need a hard-coded proxy env file. To leave a running Hermes gateway untouched during an explicit sync, pass --no-hermes-restart.

If Codex reports that a refresh token was already used after switching profiles, that profile's stored refresh token has already been invalidated by the server. Log in to that Codex account again and save it back into the same profile name:

ai-auth-switch auth login codex <profile>

Recent versions sync Codex's atomically replaced auth.json back into the managed profile before switching away, which prevents reactivating a stale refresh token after Codex refreshes it.

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 three separate layers:

• Auth management: save, list, activate, rename, remove, and inspect profiles.
• Dependent sync: point Hermes and OpenClaw at the active Codex CLI auth.
• 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.