Kill Codex's 3208-Token Output Cap for Local Models with a Model Catalog
Connecting Codex to a Local Model: Single Output Stuck at 3208 Tokens — A Complete Tutorial You Can Follow
I connected Codex to a Qwen3.8 model running locally on Strata (RTX 5060 Ti 16GB + 64GB RAM, 131072 context, server at 127.0.0.1:8080).
Everyday Q&A works fine, and small file edits work fine. But when I asked it to modify a 200+ line script, it stopped halfway, leaving two lines on screen:
writing a tool call: 2368 of max 3208 tokens, 61.6 tok/s
Incomplete response returned, reason: max_output_tokens
The context is clearly 131072, yet single output only gets 3208, which is 2.4%.
This tutorial records the complete process of increasing the output length to 16384. You can follow along: first check your situation, then use a script to make the change, and finally verify with three criteria. If the script doesn't work, there's also a manual path and an error reference table.
1. First, Determine: Whether You Need to Do Anything
Compare the three scenarios below; only the third requires changing configuration.
| Your situation | Symptom | What to do |
|---|---|---|
| Using official models (gpt-5 / claude etc.) | No such warning | Nothing to do, irrelevant to this article |
| Using a local model, but only for Q&A / small file edits | Occasional trigger | Can leave as is; just break tasks into smaller pieces (see Option A in Section 2) |
| Local model, but need to write long files / large patches | Frequent Incomplete response |
Modify catalog per Section 3, solves it once |
The deciding factor is one line: whether Codex prints this on startup:
warning: Model metadata for `<your model name>` not found.
Defaulting to fallback metadata; this can degrade performance and cause issues.
If you see this, it means Codex doesn't recognize your model and is using fallback metadata, which is where 3208 comes from.
2. Three Options, Choose the Cheap One First
Before modifying configuration, confirm you really need it.
Option A: Split tasks. Ask it to write only one file at a time, no more than 200 lines per output, and break large files into multiple requests. Zero cost, but interrupts flow.
Option B: Switch clients. Same server, Claude Code uses /v1/messages, DSH connects directly to 8080, neither has the 3208 limit. Fits if you're already switching between multiple clients.
Option C: Add model metadata. Let Codex recognize your model, solve it once, and all future tasks benefit. This is what this article teaches.
If you use Codex for writing code long-term, choose C. If you just want to finish the current task, choose A.
3. Confirm Which Side the Bottleneck Is On (Don't Change the Wrong Thing)
Many skip this step and end up changing the wrong place. Use one command to distinguish server-side vs client-side:
curl.exe -s -X POST http://127.0.0.1:8080/v1/messages `
-H 'Content-Type: application/json' `
-H 'anthropic-version: 2023-06-01' `
-d '{"model":"x","max_tokens":8192,"messages":[{"role":"user","content":"Output integers from 1 to 2000, one per line"}]}'
Look at two fields in the response:
stop_reason: max_tokens
output_tokens: 8192
If output_tokens reaches 8192, the server can provide that length, so the bottleneck is on the Codex side. I also tried setting max_tokens to 100000 / 32768 / 16384, and the server accepted all without error or truncation.
If the server errors or truncates at this step, it's outside this article's scope; first check the server's max_tokens handling.
4. Quick Path: Run a Script
The script does two things: generates model-catalog.json and writes its path into config.toml.
Save as 生成-model-catalog.ps1:
param(
[string[]]$Spec,
[int]$ContextWindow = 131072,
[int]$AutoCompact = 100000,
[string]$CatalogPath,
[string]$ConfigPath,
[switch]$DryRun
)
$codexDir = Join-Path $env:USERPROFILE '.codex'
if (-not $CatalogPath) { $CatalogPath = Join-Path $codexDir 'model-catalog.json' }
if (-not $ConfigPath) { $ConfigPath = Join-Path $codexDir 'config.toml' }
function New-ModelEntry {
param([string]$Slug, [string]$Name, [int]$MaxOutput)
[ordered]@{
slug = $Slug
display_name = $Name
default_reasoning_level = 'none'
supported_reasoning_levels = @(@{ effort = 'none'; description = 'no reasoning' })
shell_type = 'default'
visibility = 'list'
supported_in_api = $true
priority = 1
additional_speed_tiers = @()
service_tiers = @()
available_access_programs = @{ cyber = @() }
model_messages = @{}
base_instructions = 'You are a helpful coding assistant running locally.'
include_skills_usage_instructions = $false
include_plugin_usage_instructions = $false
include_apps_usage_instructions = $false
supports_reasoning_summary_parameter = $false
support_verbosity = $false
truncation_policy = @{ mode = 'tokens'; limit = $MaxOutput }
supports_image_detail_original = $false
max_context_window = $ContextWindow
auto_compact_token_limit = $AutoCompact
effective_context_window_percent = 100
experimental_supported_tools = @()
input_modalities = @('text')
supports_search_tool = $false
supports_experimental_context = $false
use_responses_lite = $false
supports_reasoning_effort_updates = $false
}
}
$models = @()
foreach ($s in $Spec) {
$p = $s.Split('|')
$limit = 16384
if ($p.Count -ge 3 -and $p[2]) { $limit = [int]$p[2] }
$models += (New-ModelEntry -Slug $p[0].Trim() -Name $p[1].Trim() -MaxOutput $limit)
}
$json = @{ models = $models } | ConvertTo-Json -Depth 10
[System.IO.File]::WriteAllText($CatalogPath, $json, (New-Object System.Text.UTF8Encoding($false)))
Write-Host ('[OK] wrote ' + $CatalogPath)
# Write path into config.toml (replace if exists)
$lines = Get-Content $ConfigPath -Encoding UTF8
$newLine = 'model_catalog_json = "' + ($CatalogPath -replace '\','\\') + '"'
$out = @(); $found = $false
foreach ($l in $lines) {
if ($l -match '^\s*model_catalog_json\s*=') { $out += $newLine; $found = $true; continue }
$out += $l
}
if (-not $found) {
$out2 = @(); $done = $false
foreach ($l in $out) {
$out2 += $l
if (-not $done -and $l -match '^\s*model_auto_compact_token_limit\s*=') { $out2 += $newLine; $done = $true }
}
if (-not $done) { $out2 += $newLine }
$out = $out2
}
Copy-Item $ConfigPath ($ConfigPath + '.bak-' + (Get-Date -Format 'yyyyMMdd-HHmmss')) -Force
[System.IO.File]::WriteAllText($ConfigPath, ($out -join "`r`n"), (New-Object System.Text.UTF8Encoding($false)))
Write-Host ('[OK] updated ' + $ConfigPath)
Run it (replace slug with your model name):
.\生成-model-catalog.ps1 -Spec 'qwen3.8-flash-next-iq3_s|Qwen3.8 IQ3_S (local)|16384'
Where does the model name come from? Two ways:
Option 1: The warning line when Codex starts ("Model metadata for `xxx` not found")
Option 2: curl http://127.0.0.1:8080/v1/models and look at the returned id
After the script runs, verify per Section 6. If verification fails, or you want to understand each field, continue to Section 5 for the manual path.
5. Manual Path: Field-by-Field Explanation
5.1 Key Conclusion First
The only field that determines "how long a single output can be" is:
"truncation_policy": { "mode": "tokens", "limit": 16384 }
mode can be bytes or tokens; when using tokens, limit is the single-output cap.
There's a common pitfall: there is no max_output_tokens field, and no model_max_output_tokens. The latter is deprecated since Codex 0.169 and will be ignored, printing a line on startup:
user (C:\Users\zsl.codex\config.toml): `model_max_output_tokens` is ignored.
I first wrote this key from memory and wasted a round.
5.2 What the Catalog File Looks Like
A complete one (minimal usable content for one model):
{
"models": [
{
"slug": "qwen3.8-flash-next-iq3_s",
"display_name": "Qwen3.8 IQ3_S (local)",
"default_reasoning_level": "none",
"supported_reasoning_levels": [{ "effort": "none", "description": "no reasoning" }],
"shell_type": "default",
"visibility": "list",
"supported_in_api": true,
"priority": 1,
"additional_speed_tiers": [],
"service_tiers": [],
"available_access_programs": { "cyber": [] },
"model_messages": {},
"base_instructions": "You are a helpful coding assistant running locally.",
"include_skills_usage_instructions": false,
"include_plugin_usage_instructions": false,
"include_apps_usage_instructions": false,
"supports_reasoning_summary_parameter": false,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 16384 },
"supports_image_detail_original": false,
"max_context_window": 131072,
"auto_compact_token_limit": 100000,
"effective_context_window_percent": 100,
"experimental_supported_tools": [],
"input_modalities": ["text"],
"supports_search_tool": false,
"supports_experimental_context": false,
"use_responses_lite": false,
"supports_reasoning_effort_updates": false
}
]
}
Save it as C:\Users<you>.codex\model-catalog.json.
5.3 Wire into config.toml
In C:\Users<you>.codex\config.toml, add a line (note Windows paths need double backslashes):
model_catalog_json = "C:\Users\zsl\.codex\model-catalog.json"
Note this key name includes "json" but the value is a file path. Directly putting a JSON string will error:
Error: The filename, directory name, or volume label syntax is incorrect. (os error 123)
5.4 What Each Field Does
| Field | Purpose | Common value |
|---|---|---|
slug |
Must exactly match the model name in Codex's request, otherwise lookup fails | Your model id |
display_name |
Name shown in UI | Anything |
truncation_policy |
Single-output cap | {mode:"tokens", limit:16384} |
max_context_window |
Context window | Match server, e.g., 131072 |
auto_compact_token_limit |
When to auto-compact history | About 75% of context window |
base_instructions |
System prompt, required | One sentence is fine |
shell_type |
Tool execution method | default |
visibility |
Whether it appears in model list | list |
supported_reasoning_levels |
Supported reasoning levels | [{effort:"none",description:"no reasoning"}] |
available_access_programs |
Access program whitelist | Must write {"cyber": []} |
5.5 Errors You'll Encounter, One by One
These are all errors I hit during testing, ordered by appearance:
| Error | Cause | Fix |
|---|---|---|
model_max_output_tokens is ignored |
Key is deprecated | Delete it, use truncation_policy |
The filename, directory name, or volume label syntax is incorrect (os error 123) |
Passed JSON as path | model_catalog_json should contain a file path |
missing field supported_reasoning_levels |
Missing field | Add [{effort,description}] |
expected struct ReasoningEffortPreset |
Passed a string | Elements must be objects |
missing field shell_type |
Missing field | default / local / shell_command / unified_exec |
missing field visibility |
Missing field | list / hide / none |
missing field supported_in_api / priority |
Missing field | true / 1 |
missing field support_verbosity |
Missing field | false |
missing field truncation_policy |
Missing field | See 5.1 |
missing field mode |
Missing subfield | bytes or tokens |
missing field limit |
Missing subfield | Number |
invalid length 0, expected struct ModelAccessPrograms |
Wrong array shape | {"cyber": []} |
expected a sequence (cyber) |
Passed string/boolean | {"cyber": []} |
invalid type: null, expected string or map |
Wrote null for optional field | Delete the entire line, don't write null |
missing both base_instructions and model_messages.instructions_template |
Missing system prompt | Add base_instructions |
5.6 How to Dig Out the Field Table Yourself
Your Codex version may be newer than 0.169, with fields added or removed. Rather than guessing, extract directly from the binary:
$bin = Get-ChildItem "$env:APPDATA\npm\node_modules@openai\codex" -Recurse -Filter codex.exe |
Select-Object -First 1
$text = [System.Text.Encoding]::ASCII.GetString([System.IO.File]::ReadAllBytes($bin.FullName))
$i = $text.IndexOf('supported_reasoning_levels')
$text.Substring([Math]::Max(0,$i-120), 1400) -replace '[^\x20-\x7E]','|'
Rust compiled artifacts leave field names of serialization structs as ASCII strings in the binary, in declaration order. The output of the above roughly looks like:
... slug display_name default_reasoning_level supported_reasoning_levels
shell_type visibility supported_in_api priority additional_speed_tiers
service_tiers default_service_tier available_access_programs ...
truncation_policy supports_image_detail_original max_context_window ...
Also search for struct X with N elements to get the field count of each struct, useful for checking if anything is missing:
struct TruncationPolicyConfig with 2 elements
struct ReasoningEffortPreset with 2 elements
struct ModelAccessPrograms with 1 element
6. Verification: Three Criteria
After changing, you must verify; otherwise you can't tell if it took effect or just happened not to trigger.
Criterion 1: Warning disappears
codex --profile strata exec --skip-git-repo-check "Just reply OK"
No more Model metadata ... not found, meaning Codex actually read your catalog.
There's also more direct evidence: the session header in the Codex UI shows the display_name from the catalog.
Before: qwen3.8-flash-next-iq3_xxs default <- original model name, using fallback
After: Qwen3.8 IQ3_XXS (local) default <- catalog's display_name takes effect
The image above was taken during a multi-file repair task after the change: the session ran continuously for 34 minutes without interruption, and no Incomplete response appeared. The bottom-left shows the byte count and line count returned per tool call; the task manager on the right shows VRAM 15.4/16 GB, RAM 61.0 GB, GPU 33% usage, CPU 52% — that's what a local model really looks like when working.
Criterion 2: Long output is not truncated
codex --profile strata exec --skip-git-repo-check "Output integers from 1 to 1500, one per line, no other text"
Check if Incomplete response appears. My test:
Time: 84 seconds
Incomplete response: none
Max number: 1500 (complete)
Criterion 3: Double the pressure
codex --profile strata exec --skip-git-repo-check "Output integers from 1 to 2500, one per line, no other text"
2500 lines is about 5000+ tokens, 1.6 times the old 3208 cap. Tested: complete output, 120 seconds.
Pass all three for a true fix.
7. Advanced
To increase further: change truncation_policy.limit, e.g., to 32768, takes effect immediately without restart. But note two things: single-response time grows linearly (at 61 tok/s, 5000 tokens is 120 seconds); input + output cannot exceed max_context_window.
Multiple models: put multiple entries in the models array, each with its own slug. I created entries for two quantizations on the same machine.
Switching machines/models: rerun the script with a different -Spec; the config.toml line doesn't need touching (the script maintains it).
8. Four Common Misconceptions
Misconception 1: Thinking this is a model capability limit. The server accepts max_tokens=100000; 3208 is the client's own fallback setting.
Misconception 2: Thinking editing the profile file works. Provider definitions and these global keys live in ~/.codex/config.toml; profile is just an overlay, editing it is ineffective.
Misconception 3: Thinking the slug in the catalog can be anything. It looks up by name; if not found, it falls back, so the name must exactly match the model name in Codex's request.
Misconception 4: Thinking bigger output is always better. Setting limit to 131072 passes validation, but a single response drags on for minutes; splitting tasks is actually better.
9. Rollback
Every time the script modifies config.toml, it leaves a backup:
Get-ChildItem "$env:USERPROFILE.codex\config.toml.bak-*" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Copy-Item <selected backup> "$env:USERPROFILE.codex\config.toml" -Force
Deleting model_catalog.json also returns to fallback state.
10. Another Pitfall on the Same Machine: 401 and API Key
While troubleshooting this issue, I hit an adjacent problem; jotting it down so others don't have to debug it again.
The symptom: Codex reported on connecting to the server:
unexpected status 401 Unauthorized: missing or wrong API key,
url: http://127.0.0.1:8080/v1/responses
While the local server startup log's last line read:
ready: http://127.0.0.1:8080/v1 (OpenAI: /v1/chat/completions,
Anthropic: /v1/messages, context 131072 tokens, images on, API key required)
Note the ending "API key required".
The reason is simple: the same environment variable is read by both sides.
Server: reads STRATA_API_KEY at startup; if non-empty, forces validation on /v1/*
Client: Codex's provider config has env_key = STRATA_API_KEY,
only checks if the variable exists, regardless of whether the server actually validates
So the action "give the client a fake key" simultaneously switches the server from no-auth to forced validation, and the client doesn't carry a real key, so a 401 is inevitable.
To have no key on either side, three actions are required: delete the user-level STRATA_API_KEY, remove the env_key line from [model_providers.*] in config.toml, and restart the server so it re-reads the environment.
Also note: Codex's provider definitions are in ~/.codex/config.toml; profile files are just overlays. Only deleting env_key from the profile won't work — that was my first mistake.
11. One-Sentence Summary
When Codex doesn't recognize your local model, it uses fallback metadata and caps single output at 3208; write a model-catalog.json and point model_catalog_json to it, where truncation_policy.limit is the real output cap — set it to 16384 and long outputs are no longer blocked.
Data source: tested on local machine on November 19, 2026 (Windows 11 / RTX 5060 Ti 16GB / 64GB DDR4-3600 / codex-cli 0.169.0 / Strata 0.1.61 / Qwen3.8-Flash-Next IQ3_S, server at 127.0.0.1:8080, context 131072).
Different Codex versions may have different fields; use the method in 5.6 to verify before acting.
Original: https://shilu.dpdns.org , also published on CSDN / Juejin / Zhihu.
Top 1 from juejin.cn, machine-translated. The original thread is authoritative.
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.