Codex Context Window

Configure the model catalog and top-level Codex setting together. A top-level model_context_window can be combined with the active model's effective_context_window_percent; changing only the TOML key may therefore appear to revert when the first turn starts.

Ask Before Writing

Inspect available models first:

python3 scripts/update_context_catalog.py --list-models

Ask the user for these values in one concise prompt. State defaults explicitly:

1. Target models. Accept full slugs, sol, terra, luna, or all-gpt-5.6.
2. Raw context window. Default: 372K (372000 tokens).
3. Effective-window percentage. Default: 95%. Calculate floor(raw_context * percentage / 100) before asking for confirmation.

Use this wording when the user has not already supplied the values:

请确认：要修改哪些模型？原始上下文窗口是多少（默认 372K）？有效窗口比例是多少（默认 95%，372K × 95% = 353.4K）？自动历史压缩要恢复模型默认值，还是设置一个明确 token 阈值？

Interpret the percentage carefully. It is the model catalog's effective_context_window_percent, not model_auto_compact_token_limit. For example, 372K at 95% gives 353400 usable tokens, commonly displayed as about 353K.

Ask separately only when relevant whether the user means the automatic history compaction token limit. Its model-default behavior is different from the percentage above. Do not write model_auto_compact_token_limit for a percentage such as 95%.

model_context_window is global for the active model. When the user selects only a subset of models, warn that the top-level raw window can also affect a later model switch; model-catalog entries still control each selected model's context metadata and effective percentage.

Apply

Show the selected models, raw context, effective percentage, computed usable window, and automatic-compaction action. A direct, unambiguous request to make the change counts as confirmation; otherwise wait for confirmation before using --apply.

To restore automatic compaction to the model default, use default below. It removes top-level model_auto_compact_token_limit and scope overrides after backing up the config. Use keep to leave any existing override unchanged.

python3 scripts/update_context_catalog.py \
  --models sol,terra,luna \
  --context 372K \
  --effective-percent 95 \
  --auto-compact-limit default \
  --apply

Run the command without --apply first to preview changes. The script:

• Uses the existing model_catalog_json when present; otherwise exports the current bundled model catalog.
• Changes only context_window, max_context_window, and effective_context_window_percent for selected models.
• Updates top-level model_context_window and model_catalog_json in $CODEX_HOME/config.toml (or ~/.codex/config.toml).
• Creates timestamped backups before a write.

Do not claim that a local setting increases the upstream provider's actual capacity. For a custom provider, confirm that the backend supports the requested raw context window.

Validate

Validate the syntax and resolved catalog without sending a billable model request:

codex exec --strict-config --ephemeral --skip-git-repo-check --help
codex debug models

Check the selected model entries in the second command and recompute the effective value. Fully restart the Codex desktop app or CLI because model_catalog_json is loaded at startup, then create a new task to observe the new runtime window.

Refresh After Upgrades

A custom catalog pins the bundled model metadata used by Codex. After updating Codex, rerun the confirmed command with --refresh-from-bundled to rebuild the catalog from the new binary while retaining the requested settings for the selected models.