Docs: rollout_budget documents stale reminder_interval_tokens key

Open 💬 0 comments Opened Aug 3, 2026 by Nagi-Inaba

Summary

The published Codex configuration reference documents the stale
features.rollout_budget.reminder_interval_tokens key, but Codex CLI expects
features.rollout_budget.reminder_at_remaining_tokens as an array of explicit
remaining-token thresholds.

Documentation:
https://learn.chatgpt.com/docs/config-file/config-reference#configtoml

This makes the documented TOML fail to parse and prevents users from enabling
the under-development rollout_budget feature from the published reference.

Environment

  • Codex CLI: 0.144.1
  • OS: Windows
  • The same reminder_at_remaining_tokens field is present in the

rust-v0.144.1 tag and current main.

Reproduction

Using the key currently listed in the configuration reference:

[features.rollout_budget]
enabled = true
limit_tokens = 100000
reminder_interval_tokens = 10000

Equivalent one-off CLI reproduction:

codex -c 'features.rollout_budget.enabled=true' \
  -c 'features.rollout_budget.limit_tokens=100000' \
  -c 'features.rollout_budget.reminder_interval_tokens=10000' \
  features list

Observed result:

Error: data did not match any variant of untagged enum FeatureToml
in `features.rollout_budget`

Implemented configuration

The CLI accepts the following configuration instead:

[features.rollout_budget]
enabled = true
limit_tokens = 100000
reminder_at_remaining_tokens = [50000, 25000, 10000]
sampling_token_weight = 1.0
prefill_token_weight = 1.0

With the equivalent one-off overrides, codex features list exits successfully
and reports:

rollout_budget  under development  true

Root cause

PR #29423 intentionally replaced the interval configuration with explicit
remaining-token reminder thresholds:

https://github.com/openai/codex/pull/29423

The implementation and generated schema now use:

pub reminder_at_remaining_tokens: Option<Vec<i64>>,

The published configuration reference still lists:

  • features.rollout_budget.reminder_interval_tokens
  • type: integer
  • a claimed default of 10% of limit_tokens

Those statements describe the pre-#29423 implementation.

Suggested documentation fix

  1. Replace features.rollout_budget.reminder_interval_tokens with

features.rollout_budget.reminder_at_remaining_tokens.

  1. Change the documented type from integer to array<integer>.
  2. Explain that every threshold must be positive and below limit_tokens.
  3. Remove the old claim that the interval defaults to 10% of limit_tokens;

the current implementation requires the threshold array when the feature is
enabled.

  1. Update the sample configuration to use an explicit array such as

[50000, 25000, 10000].

  1. If practical, validate published config keys against

codex-rs/core/config.schema.json to catch future drift.

Contribution offer

I have read docs/contributing.md and understand that external pull requests
are accepted by invitation only. If a Codex team member invites me to
contribute this fix, I would be happy to submit a focused documentation PR with
the updated reference/sample and any requested validation coverage.

View original on GitHub ↗