# Codex Refresh Default Model

> 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.

- Skill: `liewcf/codex-refresh-default-model` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add liewcf/codex-refresh-default-model`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liewcf/codex-refresh-default-model/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: liewcf (https://skillmd.com/u/liewcf)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liewcf/codex-refresh-default-model

---


# 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

1. 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.
2. 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.
3. 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.
4. Run the bundled checker in read-only mode first:

   ```bash
   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`.

5. 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.
6. Apply only after the check identifies one safe app-server and a restart strategy:

   ```bash
   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`.

7. 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.
8. 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.
9. 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.
10. 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](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.