codex-fast-proxy

Use this skill when the user wants Codex to manage the local auth-split and Fast proxy for Codex App.

Trigger patterns

• Enable requests such as "enable Codex Fast proxy".
• App Fast requests such as "make Codex App use Fast".
• Provider-specific requests such as "enable Fast for PackyAPI".
• ChatGPT login compatibility requests such as "plugins work but model requests return 401".
• Benchmark requests such as "run the Fast proxy benchmark" or "check whether my provider supports Fast".
• Upstream URL changes such as "set the Codex Fast proxy upstream to https://api.example.com/v1".
• Maintenance requests such as "show status", "check updates", "stop", or "uninstall".

How to execute

Run the manager as the source of truth:

python -m codex_fast_proxy doctor
python -m codex_fast_proxy install --start
python -m codex_fast_proxy install --start --use-provider-auth-file
python -m codex_fast_proxy prepare-chatgpt-login
python -m codex_fast_proxy prepare-chatgpt-login --apply
python -m codex_fast_proxy verify-upstream --upstream-base https://api.example.com/v1
python -m codex_fast_proxy set-upstream --upstream-base https://api.example.com/v1
python -m codex_fast_proxy set-upstream --use-provider-auth-file
python -m codex_fast_proxy set-upstream --clear-upstream-auth
python -m codex_fast_proxy set-upstream --service-tier-policy auto
python -m codex_fast_proxy set-upstream --service-tier-policy inject_missing
python -m codex_fast_proxy status
python -m codex_fast_proxy check-update
python -m codex_fast_proxy benchmark
python -m codex_fast_proxy autostart --quiet
python -m codex_fast_proxy stop --force
python -m codex_fast_proxy uninstall --defer-stop
python -m codex_fast_proxy uninstall

Safety model

• Installing the repo or skill must not change Codex provider config.
• Enable with install --start; it starts the local proxy before switching Codex config.
• Enable also installs one user-level Codex SessionStart hook in ~/.codex/hooks.json and enables the Codex hooks feature flag. Newer Codex builds use features.hooks = true; older docs/builds may refer to features.codex_hooks. During the CLI/App transition, write both keys and treat either key as enabled. The hook starts a missing proxy on future Codex sessions only when the recorded provider still points to the local proxy. It must not restart an already healthy proxy just because runtime code is stale. Current Codex builds may also require a trusted hook state entry, so treat startup_hook: true as installed, enabled, and trusted; if startup_hook_trust reports modified or untrusted, rerun enable/update instead of relying on ~/.codex/hooks.json alone.
• After an enabled update, install --start compares the running proxy runtime with the installed code and restarts stale proxy runtime before returning when config still points to the local proxy. Codex may fire SessionStart for each new or resumed session; autostart --quiet does not log normal no-op checks and does not refresh stale runtime implicitly.
• Do not run plain install to enable the proxy; the manager rejects config switching without --start.
• Default service tier policy is auto: ChatGPT-login or unclear states preserve Codex App/CLI Fast choices, while API-key mode can inject priority when Codex omits service_tier because the App Fast UI may not be available. Use --service-tier-policy inject_missing only when the user explicitly asks for global Fast injection and accepts that Codex App's Fast UI toggle will no longer control missing tiers. Use --service-tier-policy preserve only when the user explicitly wants no proxy-side Fast injection.
• Before first enable or model-path setting changes, install --start verifies the candidate upstream and auth source with one side-path Codex-style POST /v1/responses request using stream=true. If verification fails, do not pass --no-verify unless the user explicitly accepts that future Codex model requests may fail.
• Existing enabled installs that do not yet have service_tier_policy in settings are legacy global-Fast installs when they do not also have split upstream auth; preserve that behavior as inject_missing unless the user explicitly asks for App-controlled Fast. Missing policy plus split upstream auth belongs to the ChatGPT-login auth split path and should be treated as App-controlled preserve.
• For ChatGPT account login compatibility, prefer the proxy-managed provider auth file over editing auth.json, passing literal keys, or writing global user environment variables. This makes the proxy replace the upstream model-provider Authorization header for requests already routed through the local proxy while leaving ChatGPT plugin/GitHub/App connector requests alone. In this override mode, the proxy also drops unexpected Cookie headers before forwarding provider API requests. Existing --upstream-api-key-env <ENV_NAME> installs remain supported as an advanced compatibility path.
• When the user wants ChatGPT login compatibility, run prepare-chatgpt-login as a dry run first. It may find the current working provider key in auth.json or the environment, but it must not print the key. Report the non-secret JSON fields, ask for approval, then run prepare-chatgpt-login --apply. After apply, run set-upstream --use-provider-auth-file so a streaming /v1/responses side-path verification succeeds before settings are saved.
• If set-upstream --use-provider-auth-file returns restart_required=true or a following status reports needs_restart=true, do not tell the user they can sign in with ChatGPT yet. Explain that provider auth was verified and saved, but the running proxy has not loaded the new override yet. The user must restart Codex App or explicitly allow python -m codex_fast_proxy start before signing in with ChatGPT.
• After provider auth split is active and status.needs_restart=false, tell the user they can sign in with ChatGPT, and report the chatgpt_login_windows_troubleshooting JSON field when present.
• If proxy startup or config switching fails, the manager restores the backed-up config before returning.
• Use set-upstream when the user wants to change the provider URL, upstream auth source, or service tier policy while the proxy is already enabled. It must keep Codex config pointed at the local proxy, update the saved settings and uninstall baseline, and refuse to run if config no longer points to the recorded proxy. Do not pass --restart unless the user explicitly accepts that restarting the proxy can interrupt current proxy-backed Codex sessions. Without --restart, tell the user to restart Codex App, open a new CLI process, or run start later to apply the new upstream.
• Use verify-upstream when the user asks to test a candidate upstream or auth source without changing local state. It must run the same streaming /v1/responses side-path check as set-upstream, then stop without writing settings, editing Codex config, installing hooks, or restarting the proxy.
• Do not edit the active provider base_url directly while the proxy is enabled. For ChatGPT login compatibility, configure upstream provider auth with prepare-chatgpt-login --apply and set-upstream --use-provider-auth-file rather than editing auth.json. Model, reasoning, and other Codex config fields can still be edited directly by the user or agent.
• Running Codex processes do not hot-switch provider config. After enable, restart Codex App and resume the same conversation if desired, or open a new CLI process.
• If the current process is already using the proxy, stopping the proxy can interrupt the conversation. Disable with uninstall --defer-stop, tell the user to restart Codex App or open a new CLI process, then run uninstall again to finish cleanup.
• If uninstall output has status="confirmation_required", no uninstall changes were applied. Report direct_upstream_auth_warning first. Ask whether the user wants to keep the proxy enabled, switch Codex App back to API-key/third-party provider auth before uninstalling, or explicitly continue despite the ChatGPT-login direct-upstream 401 risk. Only after explicit confirmation, rerun with --confirm-chatgpt-direct-uninstall.
• If confirmed uninstall output includes direct_upstream_auth_warning, report it before any restart instruction. Restored direct upstream mode no longer has the proxy auth override; if Codex App remains signed in with ChatGPT, a third-party provider may receive ChatGPT auth and return 401. Tell the user to switch back to API-key/third-party provider auth before restarting, or keep the proxy enabled if they want ChatGPT-login UI with a third-party provider.
• Uninstall removes only the codex-fast-proxy hook and must preserve unrelated hooks.
• Do not run stop while Codex config still points to the proxy unless the user explicitly accepts that current and future sessions may fail.
• Run benchmark only when the user explicitly asks for an A/B check or confirms the cost. The default benchmark uses codex-cli mode: it starts a local forwarding capture proxy, launches real codex exec requests, and runs three interleaved default-vs-priority pairs against the saved upstream. It can consume noticeable token quota. It uses existing Codex/provider authentication when available, records upstream latency without storing response content, and should compare full-response latency even when the provider response does not expose service_tier.
• When the user asks whether their provider supports Fast/Priority, run or request enough input to run benchmark with the default full profile. Do not use normal proxy logs, service_tier_injected=true, or HTTP 200 responses as proof of provider Fast support; those only prove the proxy sent a successful request. If automatic auth discovery cannot find a key in env/provider config/~/.codex/auth.json, ask the user for the API key environment variable name and rerun with --api-key-env.
• The default benchmark timeout is 600 seconds per sample. If full benchmark reports TimeoutExpired, rerun with a larger explicit timeout such as --timeout 900 before drawing a stability conclusion.
• status and doctor include a local health check and runtime check; treat healthy=false as a reason to stop and diagnose before continuing. If status.needs_restart=true after update, tell the user to restart Codex App, open a new CLI process after the old proxy is gone, or run python -m codex_fast_proxy start when it is safe to refresh runtime code. The startup hook should not restart an already healthy proxy just because runtime code is stale.
• If the user asks only to check for updates, run check-update and stop. It is read-only and must not pull, install, restart the proxy, edit Codex config, or write proxy state.
• After a successful enable, report the JSON result, the top-level next_user_action, and the chatgpt_login_hint message. If chatgpt_login_hint.status=optional_setup_available, tell the user they can keep API-key mode for third-party API plus global Fast, and should run prepare-chatgpt-login before switching Codex App to ChatGPT login for plugin marketplace, GitHub/Apps/connectors, manual Fast controls, status hints, and voice input. Avoid chaining unrelated work in the same turn.