claude-code - 💡(How to fix) Fix [DOCS] Effort docs omit `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` unsupported-model behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/model-config

Section/Topic

Adjust effort level, model capability detection, and environment-variable controls for effort

Current Documentation

The model configuration page explains model-dependent effort support:

The available effort levels depend on the model. Models not listed here do not support effort:

It also documents normal fallback behavior when a configured effort level is not available on the active supported model:

If you set a level the active model does not support, Claude Code falls back to the highest supported level at or below the one you set. For example, xhigh runs as high on Opus 4.6.

The same page documents the public effort environment variable:

Environment variable: set CLAUDE_CODE_EFFORT_LEVEL to a level name or auto

And the environment variables reference says:

CLAUDE_CODE_EFFORT_LEVEL | Set the effort level for supported models. Values: low, medium, high, xhigh, max, or auto to use the model default. Available levels depend on the model.

The model configuration page also explains provider/custom-model capability overrides:

Claude Code enables features like effort levels and extended thinking by matching the model ID against known patterns. Provider-specific IDs such as Bedrock ARNs or custom deployment names often don't match these patterns, leaving supported features disabled. Set _SUPPORTED_CAPABILITIES to tell Claude Code which features the model actually supports:

No current page documents CLAUDE_CODE_ALWAYS_ENABLE_EFFORT or what happens when it is set for a model that does not support the API effort parameter.

What's Wrong or Missing?

Claude Code v2.1.154 fixed API 400 errors on models that do not support the effort parameter when CLAUDE_CODE_ALWAYS_ENABLE_EFFORT is set, but the docs do not explain that environment variable or its unsupported-model behavior.

That leaves three documentation gaps:

A. The environment variable is not listed

Users who see CLAUDE_CODE_ALWAYS_ENABLE_EFFORT in the v2.1.154 changelog, local environments, wrapper scripts, or support guidance cannot find it in the environment variables reference.

B. The relationship to normal effort controls is unclear

The docs document CLAUDE_CODE_EFFORT_LEVEL, /effort, effortLevel, and _SUPPORTED_CAPABILITIES, but not whether CLAUDE_CODE_ALWAYS_ENABLE_EFFORT is a supported user-facing override, an internal diagnostic flag, or a deprecated escape hatch.

C. Unsupported-model behavior is not explicit

The docs say models not listed do not support effort and that unavailable effort levels fall back on supported models. They do not say what Claude Code does when a force-enable flag asks it to send effort for a model that cannot accept the API parameter, or whether v2.1.154 now ignores, strips, warns about, or otherwise handles that configuration.

Suggested Improvement

Add a note in the effort section and, if the variable is user-facing, add an environment-variable reference row.

Suggested minimum wording:

CLAUDE_CODE_ALWAYS_ENABLE_EFFORT is an advanced override for effort-capability detection. Use it only when you know the selected model or gateway supports the API effort parameter. On models that do not support effort, Claude Code does not send the parameter, so the override should not cause an API 400 error in v2.1.154 and later.

If the variable is internal-only, document that instead:

CLAUDE_CODE_ALWAYS_ENABLE_EFFORT is an internal/debug override and is not supported for normal configuration. Use CLAUDE_CODE_EFFORT_LEVEL for supported models, or _SUPPORTED_CAPABILITIES when declaring custom provider model capabilities.

Also cross-reference _SUPPORTED_CAPABILITIES so gateway and third-party-provider users know the preferred supported path for declaring effort capability.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version context: v2.1.154 says Claude Code fixed API 400 errors on models that do not support the effort parameter when CLAUDE_CODE_ALWAYS_ENABLE_EFFORT is set.