openclaw - 💡(How to fix) Fix Default `toolResultMaxChars` (16K) is too small for frontier models and undocumented

Summary

agents.defaults.contextLimits.toolResultMaxChars defaults to 16,000 chars, which is appropriate for ~8K-context models but leaves frontier models (Claude Opus 200K, Grok 1M+, GPT-5 400K) using a tiny fraction of their context window per tool result. The knob exists and works (schema max 250,000), but it's effectively invisible:

• It's not surfaced in openclaw doctor output
• It's not mentioned in docs/gateway/configuration.md or related onboarding
• gateway action config.patch blocks it as a "protected config path" (only direct openclaw.json edit works)
• The truncation marker shown to the model ([... N more characters truncated]) and the user-facing version (⚠️ [... middle content omitted — showing head and tail ...]) don't hint that the cap is configurable

The result: agents and operators discover the knob only after burning context-debugging time, often by spelunking through dist/ or filing issues. This in turn drives the "Agent couldn't generate a response" symptoms reported in past issues (e.g., the now-closed #85801, where the recommended fix added the 16K cap but didn't surface its tunability).

Repro / discovery friction

Operator on Claude Opus (200K context) tool-loop session:

1. read a 50KB strategic-report markdown file → output truncated at 16K, both head-and-tail markers shown
2. exec returning a 30KB config dump → truncated at 16K with [... 14000 more characters truncated] notice
3. Operator searches openclaw.json schema → finds nothing under tools.*
4. Operator searches dist source → eventually finds DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS = 16e3 in pi-embedded-runner/tool-result-truncation.ts and the resolver chain reading agents.defaults.contextLimits.toolResultMaxChars
5. gateway config.patch agents.defaults.contextLimits.toolResultMaxChars → rejected as protected path
6. Operator directly edits ~/.openclaw/openclaw.json, hot-reload picks it up, problem solved

Time-to-solve: ~30 min spelunking. Could be ~30 sec if discoverable.

Asks (in priority order)

1. Raise the default to something modern-model-aware. A flat 16K default punishes the 95% of OpenClaw users who are on frontier models. Suggested defaults:

   • When primary model context window ≥ 200K → default toolResultMaxChars: 64000 (still under 30% of context)
   • When primary model context window ≥ 100K → default 32000
   • Otherwise → keep 16000

   This can be a calculated default in resolveLiveToolResultMaxChars() reading contextWindowTokens (already plumbed) rather than a static constant.

2. Document the knob. Add to docs/gateway/configuration.md and to openclaw doctor advisory output ("⚠️ Your model has a 200K context window but toolResultMaxChars is 16K. Consider raising it. See: …").

3. Allow gateway config.patch to mutate this path. It's a performance knob, not a security boundary — protected-path treatment is inappropriate. Or document why it's protected and add a config.patch --force style override.

4. Make the truncation marker actionable. Append a hint to the model-facing notice: [... N more characters truncated; raise agents.defaults.contextLimits.toolResultMaxChars to keep more]. This converts a silent friction surface into self-documenting recovery.

5. Surface as a top-level tools.maxOutputChars alias. The current path is buried 4 keys deep under agents.defaults.contextLimits. A top-level alias would dramatically improve discoverability for the most-likely-tuned knob.

Why this matters

Frontier-model OpenClaw deployments waste both context budget and operator time on a configuration default that hasn't kept pace with model capabilities. The cost of fixing this is small (default-resolution logic + docs); the cumulative friction across the user base is substantial.

Related

• #85801 (closed) — original request that introduced the 16K cap; didn't address discoverability or modern-model defaults
• #82246 (open) — webchat-side truncation knobs (gateway.webchat.toolProgressMaxChars / toolTranscriptMaxChars); orthogonal code path but same class of friction
• #45503 (open) — Manual context clearing for tool results; complementary

Version

• OpenClaw 2026.5.19 on macOS Darwin 25.5.0 / Node v25.9.0
• Model: anthropic/claude-opus-4-7 (200K context window)