qwen-code/docs/users/configuration
tanzhenxin fa7fdbca01
fix(core): clamp max_tokens to the context window; retire the output reservation (#6556)
* fix(core): clamp max_tokens to the context window; retire the output reservation

Auto-compaction was firing far too early — a 200K-window session compacted at roughly half the window. The cause was not the compaction engine but that every request manufactured a large max_tokens, which forced a defensive reservation of that output budget out of the window before computing compaction thresholds. The reservation shrank the effective window, pulled the trigger down, and spawned a chain of band-aids.

Size max_tokens to the room actually left in the window instead — the smaller of the model's output ceiling and (window − prompt − margin) — so an oversized request can never exceed the context limit. Once output is guaranteed to fit, the reservation is unnecessary and is removed; compaction gates on the full window again. Raise the default proportional threshold from 0.70 to 0.85, and replace the temporary half-window reservation cap with a flat 64K output ceiling.

This resolves early compaction, the 400 "maximum context length" error on request, the "hard limit: 0" pre-send NOOP for env-configured models, and retires the half-window reservation cap, while keeping max_tokens on the wire for both OpenAI- and Anthropic-shaped providers.

Fixes #5950
Fixes #6384

Claude-Session: https://claude.ai/code/session_014DW2TynKHLjsbRqTBSyQue

* test(cli): update /context threshold expectations for 85% default

The auto-compaction default moved from 70% to 85% and the output
reservation was removed, so computeThresholds(200K) now yields
warn=150K / auto=170K (was 147K / 167K). Update the /context
command tests that hard-coded the old ladder.

* fix(core): apply window clamp to samplingParams users who omit max_tokens

Previously a samplingParams config without a max_tokens key sent no
max_tokens on the wire (OpenAI path), so those users bypassed the
prompt + max_tokens <= window clamp — inconsistent with the Anthropic
path, which always injects the clamped value. Mirror the Anthropic
fallback (reconcile ?? config ?? request) so the clamped maxOutputTokens
is injected when samplingParams omits max_tokens.

Guard the injection: when samplingParams targets a provider-specific
output-budget key (max_completion_tokens for GPT-5/o-series, max_new_tokens),
leave it verbatim — adding max_tokens alongside double-specifies the
budget and those endpoints reject the pair.

* fix(core): clamp provider output-budget keys to the window in samplingParams

A samplingParams config carrying a provider-specific output-budget key
(max_completion_tokens for GPT-5/o-series, max_new_tokens) but no
max_tokens previously passed the key through verbatim, so its value
escaped the prompt + output <= window clamp — e.g. max_completion_tokens:
200000 on a 200K window with a 150K prompt.

Clamp the key's value in place to the remaining window (min with the
request maxOutputTokens) instead of injecting a separate max_tokens:
sending both keys double-specifies the output budget and o-series
rejects the pair. The value only shrinks when the window is tight; when
there is room it passes through unchanged, matching how max_tokens is
already treated.

* fix(core): compact on the window ceiling, not the max of the threshold ladder (#6583)

* fix(core): compact on the window ceiling (min), not the max of the ladder

computeThresholds combined the proportional term (pct*window) and the
absolute term (effectiveWindow - AUTOCOMPACT_BUFFER) with Math.max, which
pushed the auto-compaction trigger toward the top of the window on large
windows — a 1M-token window compacted at ~97%, leaving ~33K headroom.

The absolute term is structurally a ceiling ("compact before the prompt
leaves too little room for the summarization side-query, which needs up
to SUMMARY_RESERVE of output"), so it composes with Math.min, matching
the claude-code reference (services/compact/autoCompact.ts, which uses
Math.min and whose default trigger is the absolute term alone).

  auto = absoluteCeiling > 0 ? min(pct*window, absoluteCeiling) : pct*window
  warn = max(0, auto - WARN_BUFFER)   // WARN_PCT_OFFSET retired
  hard = unchanged

Effect: large windows compact at ~85% (the DEFAULT_PCT ceiling) instead
of ~97%; small/mid windows keep room to run compaction (a 128K window's
summary now provably fits); sub-33K windows are unchanged. A lower
context.autoCompactThreshold now pulls compaction earlier on large
windows, matching the reference's Math.min override semantics.

Updates the threshold unit tests, the settings schema description, and
the user docs to describe the setting as a ceiling on the trigger.

* refactor(core): trim threshold doc comments; name the hard-edge term

Post-review cleanup (no behavior change):
- Collapse the duplicated regime explanation shared between the DEFAULT_PCT
  and computeThresholds doc comments into one canonical block; point the
  constant's doc at computeThresholds.
- Rename rawHard -> hardEdge and note it is the window-edge ceiling, so the
  two roles of the hard tier (window edge vs. auto + HARD_BUFFER) are legible.
- Shorten the context.autoCompactThreshold description in settings.md to the
  concise schema wording (also un-widens the docs table).

* fix(core): clamp provider output-budget keys on every samplingParams exit

A config carrying both max_tokens and a provider-specific output-budget
key (max_completion_tokens / max_new_tokens) took the max_tokens early
return, spreading the provider key onto the wire unclamped — on backends
honoring the larger key, prompt + output could exceed the window.

Collapse the two returns into a single exit that always runs the
provider-key clamp, so no output-budget key escapes the window clamp
regardless of which combination of keys is present.

---------

Co-authored-by: 易良 <1204183885@qq.com>
2026-07-10 14:44:14 +00:00
..
_meta.ts docs: fix config/command/auth drift and surface the model-providers page (#5735) 2026-06-24 06:06:01 +08:00
auth.md docs: fix model-provider config shape and refresh feature/setting drift (#6552) 2026-07-08 23:04:47 +00:00
model-providers.md Fix long session timeline scrolling (#6526) 2026-07-09 11:43:21 +00:00
qwen-ignore.md feat(core): respect configurable agent ignore files (#4653) 2026-06-23 10:44:37 +08:00
settings.md fix(core): clamp max_tokens to the context window; retire the output reservation (#6556) 2026-07-10 14:44:14 +00:00
themes.md fix(core): Align MCP OAuth guidance and docs (#5589) 2026-06-24 07:09:53 +08:00
trusted-folders.md docs: updated all links, click and open in vscode, new showcase video in overview 2025-12-17 11:10:31 +08:00