Codex Usage

Codex usage

Use this when the user asks things like:

• "what's my codex usage"
• "check codex quota"
• "how much codex do I have left"
• "do I have codex left"
• "how many Codex resets do I have"
• "use/redeem a Codex reset"

Goal

Return a fast, glanceable summary of OpenAI Codex usage.

This skill is primarily intended for OpenClaw / HermesAgent-style environments that already have OpenAI Codex authentication available locally. It can also be used in other environments by passing a bearer token explicitly.

Default to a concise multi-line summary. Only use the one-line terse variant when the user explicitly asks for terse or one-line output.

Included helper script

This skill ships with a reusable helper script:

scripts/codex_usage.py

The script:

• accepts a direct access token or a local auth file
• extracts Codex access tokens from standalone Codex CLI auth, Hermes/OpenClaw provider auth, or Hermes credential-pool auth
• sends ChatGPT-Account-Id automatically when the auth file contains an account id
• calls https://chatgpt.com/backend-api/wham/usage
• includes banked reset-credit count when the endpoint returns rate_limit_reset_credits.available_count
• can redeem one banked reset credit via https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume
• prints either a human summary, terse summary, normalized JSON, or raw JSON

Prerequisite

You need a valid OpenAI Codex bearer token.

In OpenClaw / HermesAgent-style setups, that token is often already available via local auth storage. In other environments, provide the token directly:

export OPENAI_CODEX_ACCESS_TOKEN="your_token_here"
python3 scripts/codex_usage.py

If your environment already stores Codex auth in a local file, you can point the script at that file instead.

Auth discovery

The script resolves credentials in this priority order:

1. --access-token ...
2. $OPENAI_CODEX_ACCESS_TOKEN
3. --auth-path /path/to/auth.json
4. $CODEX_AUTH_PATH
5. auto-discovered auth files in common local locations

The intended default is OpenClaw / HermesAgent-style local auth. Token-first usage remains fully supported for other agents or standalone shell workflows.

Preferred commands

Default when local auth is already present, or when OPENAI_CODEX_ACCESS_TOKEN is already set:

python3 scripts/codex_usage.py

One-line terse output:

python3 scripts/codex_usage.py --terse

Normalized JSON:

python3 scripts/codex_usage.py --json

Raw endpoint JSON:

python3 scripts/codex_usage.py --raw

Show account email explicitly:

python3 scripts/codex_usage.py --show-email

Use a specific timezone label supported by Python zoneinfo:

python3 scripts/codex_usage.py --tz Asia/Bangkok

Use a direct token explicitly:

python3 scripts/codex_usage.py --access-token "$OPENAI_CODEX_ACCESS_TOKEN"

When using a direct token for an account that requires account scoping, include the account id:

python3 scripts/codex_usage.py --access-token "$OPENAI_CODEX_ACCESS_TOKEN" --account-id "$OPENAI_CODEX_ACCOUNT_ID"

Use a custom auth file:

python3 scripts/codex_usage.py --auth-path /path/to/auth.json

Redeem one banked reset credit:

python3 scripts/codex_usage.py --consume-reset --confirm-consume-reset

--confirm-consume-reset is required because this is a live account-side effect. Without it, the script refuses to make the consume request.

For retry-safe automation, provide a stable idempotency key. Reusing the same key should return already_redeemed rather than consume another reset:

python3 scripts/codex_usage.py --consume-reset --confirm-consume-reset --idempotency-key "$(uuidgen)"

Only run --consume-reset after the user explicitly asks to spend a reset credit. It is a real account-side effect.

Expected terse format

Codex: 95% 5h · 89% week · resets 00:22 / Fri 17 Apr, 17:10 · 3 banked resets

Response style

• Prefer a concise multi-line summary by default
• Use the terse one-line summary only when the user explicitly asks
• Do not include ASCII bars unless requested
• Do not include credits or internal fields unless requested
• Avoid showing account email unless the user asked for it

Verification

Before replying to a usage-check request, make sure the usage command actually ran successfully and returned live values. For code changes to this skill, prefer offline tests/mocks for reset redemption; do not exercise --consume-reset --confirm-consume-reset against a real account unless the user explicitly asks to spend a reset credit.

Notes

• This skill expects either a valid Codex access token or an auth file containing standalone tokens.access_token, providers.openai-codex.tokens.access_token, or a credential_pool.openai-codex token entry
• If auto-discovery fails, pass --access-token or --auth-path explicitly
• The reset count is read from rate_limit_reset_credits.available_count
• Reset redemption posts {"redeem_request_id": "..."} to /wham/rate-limit-reset-credits/consume; known response codes are reset, nothing_to_reset, no_credit, and already_redeemed
• If the endpoint schema changes, update the helper script first, then refresh the skill instructions