Codex Multi Subscription Auth Fallbacks

Set up OpenClaw multi-provider auth with OpenAI Codex OAuth fallback profiles and automatic model switching. Use when configuring multiple OpenAI Codex accou...

Security Scan

The skill's requests and actions (local Codex device-flow login, reading ~/.codex/auth.json, and writing OpenClaw's auth-profiles.json) align with its stated purpose and the included script and docs show no external exfiltration or unexplained privileges.

Purpose & Capability

Name/description (multi-provider Codex OAuth import + failover) match the included script and templates. The only sensitive accesses are the Codex CLI auth file and OpenClaw auth-profiles file, which are required to import OAuth tokens—no unrelated services or credentials are requested.

Instruction Scope

SKILL.md and the script stay within scope: they back up and temporarily clear ~/.codex/auth.json, run the codex device-flow login, parse tokens locally with Node, and write to OpenClaw's auth-profiles.json. The optional cron template only runs local commands and writes a local state file per the documentation.

Install Mechanism

No install spec is present; this is instruction-only with a supplied script. The script requires the official codex CLI (npm) and node, which the SKILL.md documents. Nothing is downloaded from arbitrary URLs or written into system-wide locations.

Credentials

No environment variables or external credentials are requested. The script accesses sensitive OAuth tokens stored locally—this is necessary for the stated purpose. Users should be aware these tokens are handled locally and that backups are created; the behavior is proportional but inherently sensitive.

Persistence & Privilege

always: false and the skill does not request persistent platform privileges. It writes only to its declared OpenClaw auth-profiles path and creates timestamped backups; it does not modify other skills or system-wide agent settings.

Assessment

This skill appears internally consistent and does what it says: import Codex OAuth sessions into OpenClaw and optionally configure a local cron job to auto-switch models. Before running: (1) Inspect the script (you already have it) and confirm it matches what will be run; (2) Manually back up ~/.codex/auth.json and your OpenClaw configs (the script makes backups but manual backup is recommended); (3) Test with a non-production OpenAI account first; (4) Ensure you have the official codex CLI (npm package) and node installed, and do not run the script as root; (5) When enabling the cron job, replace placeholders (<workspace>, UUID, timestamps) and verify the job only executes local commands in an isolated session. If you see any hidden network requests or differences between the displayed script and the one you run, stop and re-evaluate—that would change this assessment.

Codex Auth Fallback

Multi-provider auth setup for OpenClaw with automatic failover between Anthropic and multiple OpenAI Codex OAuth sessions.

Overview

OpenClaw supports multiple auth profiles per provider. When one profile hits a rate limit, the platform can fail over to another. This skill covers:

1. Adding Codex OAuth profiles via device-flow login
2. Configuring openclaw.json for provider fallback order
3. Setting up auth-profiles.json with multiple profiles
4. Deploying a cron job to auto-switch models on cooldown

Prerequisites

• OpenClaw instance running
• codex CLI installed (npm i -g @openai/codex) — this also ensures node is available
• One or more OpenAI accounts with Codex access

Security & Safety

What this skill accesses:

File	Access	Purpose
~/.codex/auth.json	Read + Temporary Write	Temporarily cleared to force a fresh device-flow login, then restored from backup. Original tokens are never deleted — a timestamped backup is created first.
~/.openclaw/agents/main/agent/auth-profiles.json	Read + Write	Imported OAuth tokens (access + refresh) are written here. A timestamped backup is created before any modification.

Important safety notes:

• Tokens stay local. No tokens are sent to any external endpoint. The script reads tokens from the local Codex CLI auth file and writes them to the local OpenClaw auth-profiles file.
• Backups are always created. Both files are backed up with timestamps before any modification. If login fails or the script is interrupted, a trap handler restores the original Codex CLI auth automatically.
• Interactive confirmation. The script prompts for confirmation before clearing the Codex CLI auth file, so you can abort if needed.
• No elevated privileges. The script runs as your user and does not require sudo or any special permissions.
• Back up manually first. Despite the automatic backups, it is recommended to manually back up ~/.codex/auth.json and your OpenClaw configs before running, especially on first use.
• Test with a non-production account. For initial testing, consider using a throwaway or non-production OpenAI account.

Step 1: Add Codex OAuth Profiles

Run the bundled script for each OpenAI account:

./scripts/codex-add-profile.sh <profile-name>

The script:

1. Backs up ~/.codex/auth.json and auth-profiles.json
2. Clears Codex CLI auth to force fresh device-flow login
3. Runs codex auth login (opens browser for OAuth)
4. Extracts tokens and imports them into OpenClaw's auth-profiles.json
5. Restores the original Codex CLI auth

Repeat for each account. Profile names should be short identifiers (e.g., the OpenAI username).

Step 2: Configure openclaw.json

Add auth profile declarations and fallback model config. See references/config-templates.md for the exact JSON blocks to add to openclaw.json.

Key sections:

• auth.profiles — Declare each profile with provider and mode
• auth.order — Set failover priority per provider
• agents.defaults.model — Set primary model + fallbacks

Step 3: Auth Profiles JSON Structure

OpenClaw stores live tokens in agents/main/agent/auth-profiles.json. See references/config-templates.md for the schema.

Each Codex profile contains:

• type: "oauth"
• provider: "openai-codex"
• access: JWT access token (auto-populated by the add-profile script)
• refresh: Refresh token (auto-populated)
• expires: Token expiry in ms (parsed from JWT)
• accountId: OpenAI account ID (parsed from JWT)

The order object controls which profile is tried first per provider. The usageStats object tracks rate limits and cooldowns automatically.

Step 4: Model Cooldown Auto-Switch Cron (Optional)

This step is entirely optional. The auth profiles from Steps 1-3 work on their own with OpenClaw's built-in failover. This cron job adds automatic model switching, which means your active model may change without manual intervention. Only enable it if you understand and want this behavior.

Deploy a cron job that checks cooldown state every 10 minutes and switches the active model. See references/config-templates.md for the full cron job definition.

The cron job:

1. Runs openclaw models status to check cooldown state
2. Picks the best available model (priority: opus > codex profiles in order)
3. Updates the session model override if needed
4. Logs state to a local memory file; only notifies on change

Before enabling:

• Test manually first: run openclaw models status to verify your profiles are working
• Review the cron job template in references/config-templates.md — the job only runs local commands and writes to a local state file
• The job runs in an isolated session and does not affect your main chat unless a model switch occurs

Add the job to cron/jobs.json using the template in the references.

File Layout

codex-auth-fallback/
├── SKILL.md                    # This file
├── scripts/
│   └── codex-add-profile.sh    # Device-flow profile importer
└── references/
    └── config-templates.md     # openclaw.json, auth-profiles, cron templates