Bug: `limit.output` in config is silently capped at 32k; `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` is a poor workaround

[g199209]

Summary

OpenCode silently caps per-step maxOutputTokens at 32,000 even when opencode.json sets a much larger limit.output (e.g. 384000 for DeepSeek, 128000 for GPT/Claude). The only documented escape hatch is an experimental environment variable, OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX, which users must discover via scattered GitHub threads.

This is surprising, breaks agent runs on reasoning-heavy models, and makes user configuration misleading.

Expected behavior

When a model defines explicit limits in config:

"deepseek-v4-flash": {
  "limit": {
    "context": 1000000,
    "output": 384000
  }
}

OpenCode should send max_output_tokens / max_tokens based on limit.output (possibly clamped to what the provider actually supports), not an undocumented global ceiling of 32k.

Actual behavior

ProviderTransform.maxOutputTokens() always applies a default cap:

export const OUTPUT_TOKEN_MAX = 32_000

export function maxOutputTokens(model: Provider.Model, outputTokenMax = OUTPUT_TOKEN_MAX): number {
  return Math.min(model.limit.output, outputTokenMax) || outputTokenMax
}

Unless OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX is set in the environment, min(384000, 32000) === 32000 is what gets sent to the API.

Real-world impact (agent benchmark)

On a coding task with reasoningEffort: "max" via @ai-sdk/openai-compatible:

• A step finishes with reason: "length"
• Token usage: reasoning: 32000, output: 0
• The agent stops mid-task with no visible completion

The same model with reasoningEffort: "high" completes normally in the same step budget because reasoning does not consume the entire cap.

This is not a provider failure; logs show OpenCode requesting ~32k max output while config says 384k.

Why OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX feels like the wrong fix

1. Misleading config — Users set limit.output in opencode.json believing it controls API behavior. It does not, unless they also export an env var whose name does not reference limit.output at all.

2. Experimental / undiscoverable — The variable is buried under “experimental” flags in CLI docs. Issue max_tokens defaults to 32000 when using a custom provider #1735 was auto-closed; Custom provider (LM Studio) ignores limit.output config, hardcodes max_tokens to 32000 #20078 remains open with the same root cause.

3. Global knob for per-model limits — Setting OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=1048576 is a shotgun fix across all models instead of respecting per-model limit.output.

4. Still does not fix overflow semantics — overflow.ts uses context - maxOutputTokens() when limit.input is absent. Models with output close to context (e.g. Kimi K2.6 at 262144/262144) get usable === 0 once the env var is raised, causing immediate compaction/overflow unless users also add limit.input — another undocumented workaround.

Related issues

• max_tokens defaults to 32000 when using a custom provider #1735 — max_tokens defaults to 32000 for custom providers (closed by stale bot, problem persists)
• Custom provider (LM Studio) ignores limit.output config, hardcodes max_tokens to 32000 #20078 — limit.output ignored, hardcodes 32000 (open)
• OUTPUT_TOKEN_MAX hardcoded to 32k prevents using full 64k output limit for Claude Sonnet 4.5 with extended thinking #2949 — 32k cap vs extended thinking / zero output tokens (closed with partial fix)

Suggested direction

1. Respect configured limit.output by default — Use OUTPUT_TOKEN_MAX (32k) only as a fallback when limit.output is missing or zero, not as Math.min(limit.output, 32k) for every model. (PR fix(provider): respect configured output limit #24384 attempted this but was closed as “not the right fix”; the problem remains.)

2. Optional global ceiling — If a safety cap is still desired, expose it in opencode.json (e.g. limits.maxOutputTokens) rather than a cryptic env var.

3. Decouple overflow math from per-step output cap — usable should not use context - limit.output when output can equal the full window; consider limit.input defaults or context - reserved for shared-window models.

4. Document the contract — Clarify in config schema/docs what limit.context, limit.input, and limit.output each control (API request vs compaction vs fallback).

Environment

• OpenCode: v1.14.x (local install from anomalyco/opencode)
• Custom provider: @ai-sdk/openai-compatible → OpenAI-compatible gateway
• Models: DeepSeek V4 Flash/Pro, Kimi K2.6, GPT 5.5, etc. with explicit limit blocks in opencode.json

Workaround today (ugly)

export OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=1048576

Plus per-model limit.input for shared-window models — none of which should be required when limit.output is already configured.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Custom provider (LM Studio) ignores limit.output config, hardcodes max_tokens to 32000 #20078: Same root cause — limit.output config ignored, max_tokens hardcoded to 32000 for custom providers (open, assigned)

If your issue adds meaningful new context beyond what's already tracked in #20078 (e.g., the overflow/compaction math issue with shared-window models, or the OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX critique), it may be worth keeping open — but please coordinate with the maintainers to avoid duplicate effort.

[divitkashyap]

Investigated this with the goal of submitting a fix — there are two layers to the cap and it's worth being explicit about both before anyone opens a PR:

Layer 1 — config is dropped on the floor. When the model comes from models.dev, configured limit.output in opencode.json was being discarded entirely in provider/provider.ts. @sjawhar's #29354 (open since yesterday) fixes this — configured limits are now merged over the models.dev defaults. That PR closes #21564 but doesn't reference this one, even though it's a prerequisite.

Layer 2 — even with a correct model.limit.output, the transform re-caps at 32k. packages/opencode/src/provider/transform.ts:1261:

export function maxOutputTokens(model: Provider.Model, outputTokenMax = OUTPUT_TOKEN_MAX): number {
  // ...uses Math.min(model.limit.output, outputTokenMax)
}

OUTPUT_TOKEN_MAX = 32_000 (transform.ts:18). OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX overrides only that ceiling, not the Math.min. So even after #29354 merges limit.output: 384000 into the model, this function still returns 32000.

Even after #29354 lands, this issue would still reproduce.

Question for maintainers (@thdxr / @simonklee): is the 32k cap deliberately a safety net for providers that genuinely can't handle larger outputs, or is it vestigial? If it's a safety net, the right fix is probably to apply it only when model.limit.output is absent or zero (i.e. treat an explicit non-zero limit.output as authoritative). Happy to put up that follow-up to #29354 if there's interest.

[rekram1-node]

We aren't ignoring configs here, this is how many tokens we cap the agent to reply with for a given step of a turn, the case where it reaches limit prolly needs additional handling but making a larger value here is uncommon, we alreadyy have a pretty standard value and some other coding agents make it even smaller. Happy to make the configuration option more exposed tho

The limit.output tracks the maximum supported output tokens from a model, we don't want to always use that cause then u could potentially use up the entire context window in a single turn also it makes compaction math more annoying

[lexlian]

Submit a PR #29513 , and it fix the issue:

• it makes maxOutputTokens() use limit.output directly when configured (> 0), fall back to OUTPUT_TOKEN_MAX only when no limit is set, and preserve OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX as an optional safety ceiling.

Could consider deprecating OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX in favor of a global limits.maxOutputTokens in opencode.json. This would make the safety ceiling discoverable and configurable without requiring an experimental env var. Per-model limit.output stays fully respected below the ceiling.

[rekram1-node]

did u read my message i literally said not to do that

[g199209]

We aren't ignoring configs here, this is how many tokens we cap the agent to reply with for a given step of a turn, the case where it reaches limit prolly needs additional handling but making a larger value here is uncommon, we alreadyy have a pretty standard value and some other coding agents make it even smaller. Happy to make the configuration option more exposed tho

The limit.output tracks the maximum supported output tokens from a model, we don't want to always use that cause then u could potentially use up the entire context window in a single turn also it makes compaction math more annoying

deepseek v4 model has 1M context window, and it can generate very long chain of thought, much longer than 32k. Limit output to 32k making the thinking process truncated. This make the whole program unusable.

[lexlian]

did u read my message i literally said not to do that

@rekram1-node I didn't actually 'see' your message before I posted my previous message as I was using gh cli tool.

I spent some time trying to summarize all these and hopefully we all could find our conversation valuable for future decision:

1. What does modern LLM models support

Provider	Latest Model	Context Window	Max Output Tokens
OpenAI	GPT-5.5 / GPT-5.4	~1,000,000 tokens	128,000
Anthropic	Claude Opus 4.7	1,000,000 tokens	128,000 (sync) / 300,000 (Batch API)
Google	Gemini 3.5 Flash	~1,000,000 tokens	65,536
DeepSeek	DeepSeek V4 Pro	1,000,000 tokens	384,000

2. Claude Code and Codex CLI current mechanism

Claude Code lets the model cap drive output (from online tech doc):

• CLAUDE_CODE_MAX_OUTPUT_TOKENS 'Set the maximum number of output tokens for most requests. Defaults and caps vary by model;' env var defaults to model's own max output (128k Opus 4.7, 64k Sonnet 4.6)
• Sync API: up to model max, Batch API: up to 300k via output-300k-2026-03-24 beta header
• Docs: code.claude.com/env-vars → platform.claude.com/models

OpenAI Codex CLI hardcodes 128k for all GPT-5 models (from github info):

• max_output_tokens: 128_000 in codex-rs/core/src/openai_model_info.rs
• Users hit stream disconnected before completion: reason: max_output_tokens (GitHub issue #14753)
• Not user-configurable — feature requested in issue #20861
• Source: codex-rs/openai_model_info.rs (mentioned by issue #3523)

3. Possible directions

Option 1 Maintain current behavior and allow global config to adjust max output tokens.

Option 2 Allow per-model max output tokens overrides.

Option 3 Allow per-profile or per-job configuration. As someone may want aggressively truncated tool call output for certain projects. Others might need larger windows for long run tasks like log analysis and self driven code generation, etc.

[rekram1-node]

max output tokens for a model, and the requested output tokens are 2 separate concepts

[g199209]

max output tokens for a model, and the requested output tokens are 2 separate concepts

@rekram1-node Agreed that model capability and per-request output cap are different concepts — this issue isn't about the concept.

The concrete failure I'm reporting (reproducible):

• DeepSeek V4 Pro, limit.output: 384000, reasoningEffort: "max"
• Single step ends with finish_reason: "length", reasoning: 32000, output: 0
• Agent loop hard-stops. No retry, no continuation, no surfaced error.

This is not "uncommon to want a larger value." As you can see in @lexlian 's previous comment, for any frontier reasoning model in 2026 — GPT-5.5 reasoning=max, Claude Opus 4.7 extended thinking, DeepSeek V4 long CoT — reasoning tokens routinely exceed 32k in a single step. Under the current cap that's 0 visible output, ~100% of the time, not an edge case. Comparable tools already account for this: Claude Code defaults CLAUDE_CODE_MAX_OUTPUT_TOKENS to the model's own max (128k Opus / 64k Sonnet); Codex CLI hardcodes 128k for GPT‑5.

Keeping your concept distinction intact, the asks are orthogonal to it:

1. Expose the per-request cap in opencode.json (non-experimental). You said you'd be happy to — this is that.
2. Default the cap from model metadata rather than a fixed 32k.
3. Handle finish_reason: "length" gracefully instead of a hard stop.
4. Decouple compaction math in overflow.ts from the per-step cap — this is the legitimate concern you raised, and it's solvable independently of (1)–(3).

None of these collapse the capability-vs-request-cap distinction.

Concrete question I'd like a direct answer on: is opencode intended to be usable with reasoningEffort: high/max on frontier models today? If the answer is no, please state that explicitly in the official docs — something like "opencode is not designed for frontier models with long-form output / extended reasoning; do not use it for such workloads." That at least sets correct expectations, instead of letting users configure limit.output and silently get it capped at 32k.