跪拜 Guibai
← All articles
AI Programming

Kill Codex's 3208-Token Output Cap for Local Models with a Model Catalog

By 郑世录 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Anyone running Codex against a local model hits this hidden output cap exactly when doing large edits; the workaround (and the catalog schema behind it) is the difference between a model that silently fails and one that finishes a multi-file patch. It also exposes a client-side assumption that local models behave like OpenAI's cloud services, which this configuration explicitly overrides.

Summary

Codex silently falls back to a conservative metadata set when it can't find a local model's metadata, which caps each tool-call output at 3208 tokens. A 131072-token context doesn't help because the limit is client-side, not server-side; the server accepts max_tokens up to 100000 without complaint.

The fix is to create a model-catalog.json entry for the model, setting truncation_policy.limit to 16384 (or higher), and reference that file via the model_catalog_json key in config.toml. A PowerShell script automates this for one or more models, and a manual path explains each required field, common errors like the deprecated model_max_output_tokens key, and how to extract the exact field list from the Codex binary for newer versions.

Verification involves three checks: the missing-metadata warning disappears, a 1500-line output completes without truncation, and a 2500-line output (1.6x the old cap) also completes, confirming the change holds under pressure. The same article also documents a related 401 pitfall caused by the STRATA_API_KEY environment variable being read by both server and client, turning a fake client key into forced server authentication.

Takeaways
— Codex defaults to 3208 tokens per single output when it lacks model metadata for a local model, even if the context window is 131072 tokens.
— The server accepts max_tokens up to 100000 without error; the bottleneck is purely client-side fallback metadata.
— To raise the cap, create a model-catalog.json with a truncation_policy object: { mode: 'tokens', limit: 16384 }.
— Reference the catalog file in config.toml using the model_catalog_json key; the value must be a file path, not an inline JSON string.
— The deprecated key model_max_output_tokens is ignored in Codex 0.169 and later; using it causes a warning and no effect.
— The model_catalog_json file requires many fields beyond truncation_policy: slug, displayed_name, supported_reasoning_levels, shell_type, visibility, supported_in_api, priority, available_access_programs, base_instructions, and others.
— Verify the fix by checking that the startup warning disappears, a 1500-line output completes, and a 2500-line output (more than 1.6x the old cap) also completes.
— A curl POST to the local /v1/messages endpoint with max_tokens=8192 confirms server-side capability before touching any config.
— When the server requires an API key (STRATA_API_KEY set), giving the client a fake key flips the server from no-auth to forced validation, causing 401 errors; remove the environment variable and the env_key line in config.toml to keep both sides keyless.
— Changing truncation_policy.limit takes effect immediately without restart, but output length scales linearly with token generation speed (e.g., 2500 lines took 120 seconds at 61 tok/s).
Conclusions

The 3208 cap is a quiet default that only surfaces when a user pushes a genuinely large edit; most local-model workflows avoid it by accident, masking the need for metadata configuration.

The solution relies on reverse-engineering Codex's serialization schema from the binary, a pragmatic approach for any open-source CLI that doesn't expose its config format officially.

The 401/AUTH pitfall shows how environment variables create hidden coupling between client and server; a single variable can switch a service from open to locked without either side noticing until a request fails.

Setting truncation_policy.limit too high (e.g., 131072) passes validation but makes single responses impractically slow, so the practical cap is bounded by generation speed, not just token count.

Concepts & terms
model-catalog.json
A JSON file that declares metadata for models Codex doesn't recognize, including per-model output limits, context windows, and reasoning levels. Codex reads it via the model_catalog_json key in config.toml and uses the entry instead of fallback defaults.
truncation_policy
A field in the model catalog that controls the maximum length of a single model response. It has mode (bytes or tokens) and limit (the cap). Setting limit to 16384 or higher removes Codex's default 3208-token output restriction.
fallback metadata
When Codex cannot find metadata for a model, it uses a conservative default profile that limits output tokens to 3208 and may degrade performance. The startup warning 'Model metadata not found' triggers this mode.
model_max_output_tokens
A deprecated configuration key in Codex (0.169 and later) that was previously used to set output limits. It is now ignored; the replacement is truncation_policy in the model catalog.
From the discussion
Featured comments
郑世录

If you run into other errors, you can paste them here. I have a reference table of 15 errors, and if it matches, I'll directly give the conclusion.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗