Codex Profiler

Manage OpenAI Codex profiles via Telegram commands for usage checks and OAuth token refresh with queued safe apply and progress updates.

✅ Maintained path: use codex-profiler for all Codex profile operations. Standalone codex-usage and codex-auth skills are deprecated.

This skill consolidates both scripts:

• scripts/codex_usage.py (usage/limits)
• scripts/codex_auth.py (OAuth helper for start/status)

For auth/profile mutation, this skill now standardizes on gateway-native openclaw models auth ... commands.

Safe defaults

• Usage checks are read-only by default.
• Auth state is runtime-managed; one-shot direct file edits are unreliable and can be overwritten by in-memory/cooldown state.
• Treat auth-profiles.json as gateway-managed state. Never mutate it directly in normal operations.
• Prefer gateway-native auth mutation commands (openclaw models auth ..., openclaw models auth order ...) over script-level file writes.
• Use dry-run/read-only preflight first, then apply, then verify (strict anti-drift flow below).
• See RISK.md for allowed/denied operation boundaries.

Commands

Usage

• /codex_usage → selector (default / all / discovered profiles)
• /codex_usage <profile>

Auth

• /codex_auth → selector (profiles)
• /codex_auth <profile>
• /codex_auth finish <profile> <callback_url> (helper only; profile/order mutation must use gateway-native commands)

UX requirements (cross-channel)

For /codex_usage, send immediate progress message first as a separate message:

• "Running Codex usage checks now…"

Delivery rule:

• If progress is sent through channel message tool path, send final result through the same path (same target/session), then return NO_REPLY.
• Avoid mixed delivery (tool progress + plain reply final).

For auth/profile/order mutation, warn that writes are gateway-managed and enforce verify-after-apply:

• "I will apply this via openclaw models auth ... and then verify with models status + auth order get."
• "I won’t hand-edit auth files directly because runtime state can drift/overwrite one-shot edits."

Interaction adapter

• If inline buttons are supported: use selector buttons.
• If inline buttons are not supported: use text fallback prompts.
• Apply duplicate-request suppression per user for ~20s.
• Never echo full callback URLs in responses.

Profile removal policy (MANDATORY)

1. Best method (default): operational retire, not hard delete
   • Remove the target profile from active provider order (openclaw models auth order set ...) so it is never selected.
   • Keep profile data intact unless the user explicitly requests permanent deletion.
2. Hard delete only on explicit user instruction
   • Perform permanent profile deletion only when the user clearly asks to hard delete/remove permanently.
   • If gateway-native delete is unavailable in the installed OpenClaw version, do not improvise risky live edits; use a controlled maintenance window flow.

Strict anti-drift auth mutation flow (MANDATORY)

For auth/profile/order changes, use this exact 3-step flow:

1. Preflight (read-only)

bash

openclaw models status --json
openclaw models auth order get --provider openai-codex --agent <agent-id>

2. Apply (gateway-native command)

bash

openclaw models auth order set --provider openai-codex --agent <agent-id> <profile1> <profile2>
# or
openclaw models auth order clear --provider openai-codex --agent <agent-id>
# or provider login flow
openclaw models auth login --provider openai-codex

3. Verify (post-apply, no assumptions)

bash

openclaw models status --json
openclaw models auth order get --provider openai-codex --agent <agent-id>

Never skip verification. If results mismatch expectation, do not hand-edit files; diagnose and re-apply via gateway-native commands.

How to run

bash

# Usage checks (read-only)
python3 skills/codex-profiler/scripts/codex_usage.py --profile all --timeout-sec 25 --retries 1 --debug
python3 skills/codex-profiler/scripts/codex_usage.py --profile all --format text

# OAuth helper (callback parsing/status only)
python3 skills/codex-profiler/scripts/codex_auth.py start --profile default
python3 skills/codex-profiler/scripts/codex_auth.py status

Safety posture

• No remote shell execution (curl|bash, wget|sh) is allowed by this skill.
• No sudo/SSH/system-level host mutation commands are part of this skill path.
• Usage checks are restricted to trusted HTTPS endpoint host allowlist (chatgpt.com).
• Callback URLs and token material must be treated as sensitive and never echoed in full.

Multi-account rotation guidance

When asked about running multiple Codex accounts/profiles, rotation policy, or fallback strategy, read:

• references/multi-account-rotation.md

Use the short template for quick chat answers and the deep-dive template for setup/troubleshooting requests.

Notes

• Uses auth profiles at ~/.openclaw/agents/main/agent/auth-profiles.json by default.
• Current source of truth is auth-profiles.json; auth.json is legacy compatibility and should not be used as primary state.
• If profile routing behaves unexpectedly, check for mixed state (missing/stale auth-profiles.json, leftover legacy files, or stale runtime cooldown) before assuming model fallback bugs.
• Same accountId across two profile labels is not automatically a defect. In this environment, multiple labels can map to the same workspace/account identity while still operating correctly. Treat it as healthy when both profiles are auth-valid and usable in /codex_usage; investigate only when auth failures or routing failures appear.
• Codex usage endpoint: https://chatgpt.com/backend-api/wham/usage.
• Usage script now surfaces 401 as auth_not_accepted_by_usage_endpoint with a clear hint, while still returning local profile health.
• Usage output now includes top-level summary, formatted_profiles, and suggested_user_message for cleaner slash-command formatting.
• Preferred strict output format for /codex_usage (single line per profile):
  • 🟢 \%profile%` — 5h %5h_left% | week %week_left% | r5 %5h_reset% | rw %week_reset%`
  • Use 🟠 when limited and 🔴 when unusable/auth-invalid.
  • No preface, no table, no trailing summary unless explicitly requested.
• OAuth flow: OpenAI auth endpoints + localhost callback on port 1455.
• Preferred mutation path is gateway-native (openclaw models auth ... / openclaw models auth order ...) with mandatory preflight + verify.
• codex_auth.py status --profile <profile> remains useful for per-profile helper status checks.
• Keep temporary payload/token artifacts only until verification succeeds, then clean them up.
• Codex CLI installation is not required for usage endpoint reads in this skill path.