Refresh Codex Default Model
Use this skill for Linux Codex installations only. It is deliberately fail-closed: it must not edit configuration or signal a process when the official target, local availability, process identity, restart strategy, or required authorization is uncertain.
Workflow
Resolve the target from the current official OpenAI model guidance at https://developers.openai.com/api/docs/guides/latest-model.md (the machine-readable Markdown form of the canonical page). Fetch over HTTPS with certificate verification and a bounded timeout. Identify exactly one alias using the script's anchored marker rule; do not infer a model slug from prose, use a fallback, or hard-code a model name. If resolution fails, report whether the failure was network, parse, or ambiguity and make no changes.
Confirm the target is the model intended for the Codex app-server at implementation time. The API guidance is not automatically a Codex app-server contract; if the official pages diverge, stop and update the skill before applying repairs.
Select one installation with --codex-home PATH (default $CODEX_HOME, then $HOME/.codex). Version 1 handles one home per invocation. Never substitute /root/.codex for the invoking user's home.
Run the bundled checker in read-only mode first:
python3 scripts/refresh_codex_default_model.py --check --codex-home "$CODEX_HOME" --target "$TARGET" --json
--check performs zero filesystem writes, cache touches, process signals, or status-file writes. On non-Linux it reports platform_unsupported and exits 4, except for disposable fixture tests using CODEX_REFRESH_ALLOW_NON_LINUX_TEST=1.
Before --apply, ensure the current Codex process is not the app-server being repaired. If the skill's process ancestry includes the target app-server, stop and ask the user to run the apply stage from an external shell, then re-run the check after the restart.
Apply only after the check identifies one safe app-server and a restart strategy:
python3 scripts/refresh_codex_default_model.py --apply --codex-home "$CODEX_HOME" --target "$TARGET" --json
The script backs up config.toml and models_cache.json before any mutation. Managed servers are restarted through their owning systemd user unit. Unmanaged servers are matched by full argv, executable identity, and user ID; their original argv/environment are captured for restart. Unknown or ambiguous matches abort before TERM.
If graceful termination times out, the script exits with approval_required (2) and does not force-kill. Ask the user for explicit authorization, then re-run with --approve-kill; the script re-verifies the PID, executable, argv, and UID immediately before KILL. Never force-kill a server that could host the current session.
Treat refreshed local metadata as the availability check. The target must appear in the refreshed model metadata before config.toml is changed. Do not claim to know server-side entitlement and do not read or print auth tokens.
Verify three script-level outcomes: refreshed metadata contains the target, the root-table model key references the target, and the app-server is alive/current. Picker confirmation is a separate manual step for a Linux UI build; for a headless build, report the metadata/config/server checks instead.
On any post-change failure, restore both configuration and cache backups, make one bounded restart attempt with the previous state, and report terminal failure with exact backup paths. Never delete the cache or touch Apache, MariaDB, Docker, WordPress, or Codex proxy processes.
Safety Rules
- Use only
$CODEX_HOME/config.toml and the isolated $CODEX_HOME/models_cache.json metadata path in v1. A missing or renamed cache is a reported no-op, not a guessed path.
- Parse TOML with the standard library. Edit only the root-table
model key. Ignore profile/provider keys, dotted keys, near-miss names, and comments. Abort on malformed TOML or genuinely ambiguous root entries. Write through a same-directory temporary file and atomic rename while preserving permissions.
- Validate every target against
^[a-z0-9][a-z0-9._-]{1,63}$, TOML-escape it, and pass it as an argv value rather than shell text. Verify it is present in local metadata before writing.
- Keep apply runs exclusive with a
flock lock under the selected Codex home. Keep timestamped backups under $CODEX_HOME/backups/codex-refresh-default-model/; never auto-delete them in v1.
- Never print access tokens, account IDs, credit IDs, email addresses, or profile image URLs. Redact sensitive values in text and JSON output.
Bundled CLI
Read the command's JSON output when another tool or agent needs to branch on a result. Stable exit codes are: 0 success, 1 failure, 2 approval required, 3 target unresolved, and 4 unsupported platform. Use --wait-seconds to bound graceful termination and --json for machine-readable status. Use --target only for a target already resolved from the official guidance; omitting it makes the script resolve the pinned page itself.
The source implementation is scripts/refresh_codex_default_model.py. The skill is Linux-only and must be tested on Linux for process behavior; macOS fixture tests are limited to file/config logic with the explicit disposable-home override.
1---2name: codex-refresh-default-model3description: Diagnose and safely repair stale Linux Codex model metadata, app-server state, and the configured default model. Use when the Codex model picker is missing current models, the app-server or model cache is stale, a Codex default model needs updating, or one user has multiple Codex homes to inspect.4---56# Refresh Codex Default Model78Use this skill for Linux Codex installations only. It is deliberately fail-closed: it must not edit configuration or signal a process when the official target, local availability, process identity, restart strategy, or required authorization is uncertain.910## Workflow11121. Resolve the target from the current official OpenAI model guidance at `https://developers.openai.com/api/docs/guides/latest-model.md` (the machine-readable Markdown form of the canonical page). Fetch over HTTPS with certificate verification and a bounded timeout. Identify exactly one alias using the script's anchored marker rule; do not infer a model slug from prose, use a fallback, or hard-code a model name. If resolution fails, report whether the failure was network, parse, or ambiguity and make no changes.132. Confirm the target is the model intended for the Codex app-server at implementation time. The API guidance is not automatically a Codex app-server contract; if the official pages diverge, stop and update the skill before applying repairs.143. Select one installation with `--codex-home PATH` (default `$CODEX_HOME`, then `$HOME/.codex`). Version 1 handles one home per invocation. Never substitute `/root/.codex` for the invoking user's home.154. Run the bundled checker in read-only mode first:1617 ```bash18 python3 scripts/refresh_codex_default_model.py --check --codex-home "$CODEX_HOME" --target "$TARGET" --json19 ```2021 `--check` performs zero filesystem writes, cache touches, process signals, or status-file writes. On non-Linux it reports `platform_unsupported` and exits 4, except for disposable fixture tests using `CODEX_REFRESH_ALLOW_NON_LINUX_TEST=1`.22235. Before `--apply`, ensure the current Codex process is not the app-server being repaired. If the skill's process ancestry includes the target app-server, stop and ask the user to run the apply stage from an external shell, then re-run the check after the restart.246. Apply only after the check identifies one safe app-server and a restart strategy:2526 ```bash27 python3 scripts/refresh_codex_default_model.py --apply --codex-home "$CODEX_HOME" --target "$TARGET" --json28 ```2930 The script backs up `config.toml` and `models_cache.json` before any mutation. Managed servers are restarted through their owning systemd user unit. Unmanaged servers are matched by full argv, executable identity, and user ID; their original argv/environment are captured for restart. Unknown or ambiguous matches abort before `TERM`.31327. If graceful termination times out, the script exits with `approval_required` (2) and does not force-kill. Ask the user for explicit authorization, then re-run with `--approve-kill`; the script re-verifies the PID, executable, argv, and UID immediately before `KILL`. Never force-kill a server that could host the current session.338. Treat refreshed local metadata as the availability check. The target must appear in the refreshed model metadata before `config.toml` is changed. Do not claim to know server-side entitlement and do not read or print auth tokens.349. Verify three script-level outcomes: refreshed metadata contains the target, the root-table `model` key references the target, and the app-server is alive/current. Picker confirmation is a separate manual step for a Linux UI build; for a headless build, report the metadata/config/server checks instead.3510. On any post-change failure, restore both configuration and cache backups, make one bounded restart attempt with the previous state, and report terminal failure with exact backup paths. Never delete the cache or touch Apache, MariaDB, Docker, WordPress, or Codex proxy processes.3637## Safety Rules3839- Use only `$CODEX_HOME/config.toml` and the isolated `$CODEX_HOME/models_cache.json` metadata path in v1. A missing or renamed cache is a reported no-op, not a guessed path.40- Parse TOML with the standard library. Edit only the root-table `model` key. Ignore profile/provider keys, dotted keys, near-miss names, and comments. Abort on malformed TOML or genuinely ambiguous root entries. Write through a same-directory temporary file and atomic rename while preserving permissions.41- Validate every target against `^[a-z0-9][a-z0-9._-]{1,63}$`, TOML-escape it, and pass it as an argv value rather than shell text. Verify it is present in local metadata before writing.42- Keep apply runs exclusive with a `flock` lock under the selected Codex home. Keep timestamped backups under `$CODEX_HOME/backups/codex-refresh-default-model/`; never auto-delete them in v1.43- Never print access tokens, account IDs, credit IDs, email addresses, or profile image URLs. Redact sensitive values in text and JSON output.4445## Bundled CLI4647Read the command's JSON output when another tool or agent needs to branch on a result. Stable exit codes are: `0` success, `1` failure, `2` approval required, `3` target unresolved, and `4` unsupported platform. Use `--wait-seconds` to bound graceful termination and `--json` for machine-readable status. Use `--target` only for a target already resolved from the official guidance; omitting it makes the script resolve the pinned page itself.4849The source implementation is [scripts/refresh_codex_default_model.py](scripts/refresh_codex_default_model.py). The skill is Linux-only and must be tested on Linux for process behavior; macOS fixture tests are limited to file/config logic with the explicit disposable-home override.
liewcf