Codex Profile Orchestrator

Manage multiple OpenAI Codex OAuth profiles inside OpenClaw without using an AI decision loop. Use when you need a deterministic, always-on account orchestra...

Security Scan

The skill largely does what it claims (discover, alias, quarantine, select, sync and notify) but it reads/writes the local auth store and will transmit bearer tokens to an external usage endpoint (chatgpt.com) and can delete profiles — these behaviors deserve careful review before installing.

Purpose & Capability

The scripts implement profile discovery, alias creation, health/quota checks, quarantine/delete of invalid profiles, session synchronization and notifications — which match the SKILL.md features. However the ability to modify the local auth store (create aliases, write snapshots, and delete profiles) is powerful and not limited by declared requirements (the skill declares no env/config needs). That write/delete capability is coherent for an 'orchestrator' but should be recognized as an impactful privilege.

Instruction Scope

Runtime instructions direct the agent/operator to run included Python scripts which will read and (in apply mode) modify auth-profiles.json and write backups. The code also fetches usage by making HTTP requests that include profile bearer tokens to an external endpoint (USAGE_URL = https://chatgpt.com/backend-api/wham/usage). The SKILL.md mentions auth-profiles.json, but the instructions do not emphasize the external network calls or the potential for profile deletion; both are material and should be called out to users before run/apply/daemon.

Install Mechanism

This is instruction-only with included scripts; there is no external download or package install. Nothing is pulled from untrusted URLs during install — the risk is limited to running the shipped code on your system.

Credentials

The skill declares no required environment variables but expects read/write access to the OpenClaw auth store (auth-profiles.json) and workspace state directories; it can add alias profiles and delete invalid profiles after a threshold. It also sends bearer tokens from those profiles to an external service (chatgpt.com) when fetching usage. Both access to the auth store and sending tokens externally are high-impact and should be considered disproportionate unless you explicitly intend to allow the skill to manage tokens and contact that third-party endpoint.

Persistence & Privilege

The skill is not forced-always, but it supports daemon mode and the installer writes a config that points to a registry/state file. It will modify the auth store and can permanently delete profiles after the configured invalid-streak threshold. Running it as a long-lived daemon increases blast radius because it can autonomously change auth-profiles.json over time and trigger external network calls and notifications.

What to consider before installing

This skill's code appears to implement the claimed orchestration, but it will read and (when run with --apply/daemon) modify your OpenClaw auth store (auth-profiles.json) and can remove profiles after an 'invalid streak'. It also fetches usage by sending profile bearer tokens to https://chatgpt.com/backend-api/wham/usage — verify you trust that endpoint. Before installing: (1) review the scripts yourself (they are included), (2) run only dry-run mode first and inspect outputs, (3) back up your auth-profiles.json and workspace state, (4) consider running in a contained test workspace, (5) confirm the USAGE_URL domain is acceptable for your security policy, and (6) avoid enabling daemon/apply until you are comfortable with the deletion behavior and external token usage.

Use this skill to replace ad hoc failover scripts with one deterministic account orchestration loop.

What it provides

• profile discovery from auth-profiles.json
• same-email workspace variant detection and ws2/ws3 alias creation
• quota-aware profile selection using a fixed threshold
• invalid profile quarantine and optional auto-removal after repeated failures
• session synchronization for main and background sessions
• short Telegram notifications sent through OpenClaw's native messaging layer
• daemon mode for continuous polling

Recommended workflow

1. Read references/flow.md, references/state-model.md, and references/naming-rules.md.
2. Install the config with scripts/install_codex_profile_orchestrator.py.
3. Run a dry run and inspect the JSON output.
4. Run apply mode once.
5. Start daemon mode.

Commands

Install config

python3 scripts/install_codex_profile_orchestrator.py --workspace /path/to/workspace --telegram-target <telegram-chat-id>

Optional additional session targets:

python3 scripts/install_codex_profile_orchestrator.py \
  --workspace /path/to/workspace \
  --telegram-target <telegram-chat-id> \
  --session-target agent:main:worker-a \
  --session-target agent:main:worker-b

Dry run

python3 scripts/codex_profile_orchestrator.py --config /path/to/workspace/config/codex-profile-orchestrator.json --dry-run --json

Apply

python3 scripts/codex_profile_orchestrator.py --config /path/to/workspace/config/codex-profile-orchestrator.json --apply --json

Daemon

nohup python3 scripts/codex_profile_orchestrator.py --config /path/to/workspace/config/codex-profile-orchestrator.json --apply --daemon >> /path/to/workspace/state/codex-profile-orchestrator.log 2>&1 &

Core rules

• Discover the currently active profile first, then register it if it is new.
• If the current profile is above the threshold, keep using it.
• If the current profile is below the threshold and a better usable profile exists, switch to the healthiest one.
• If every usable profile is below the threshold, keep using the current one until it becomes unusable, then switch.
• Treat same email + same user_id + same account_id as a duplicate.
• Treat same email + different account_id as a new workspace variant.
• Remove 401/403-style profiles from the active selection pool immediately.
• Delete invalid profiles only after the configured invalid streak threshold is reached.

Notifications

Notifications must stay short and event-focused:

• new account found
• new workspace variant found
• duplicate ignored
• active profile switched
• profile quarantined
• profile removed

References

• references/flow.md
• references/state-model.md
• references/naming-rules.md
• references/telegram-notify-rules.md