[DOCS] `CLAUDE_CODE_MAX_OUTPUT_TOKENS` defaults vs. Amazon Bedrock requirements

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/settings#environment-variables - https://code.claude.com/docs/en/amazon-bedrock#5-output-token-configuration

Section/Topic

The description for CLAUDE_CODE_MAX_OUTPUT_TOKENS within the "Environment variables" table on the Settings page.

Current Documentation

On Settings (https://code.claude.com/docs/en/settings), the documentation states:

CLAUDE_CODE_MAX_OUTPUT_TOKENS: Set the maximum number of output tokens for most requests. Default: 32,000. Maximum: 64,000.

However, on Amazon Bedrock (https://code.claude.com/docs/en/amazon-bedrock), the documentation states:

Recommended output token settings for Bedrock export CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096 Why these values: CLAUDE_CODE_MAX_OUTPUT_TOKENS=4096: Bedrock's burndown throttling logic sets a minimum of 4096 tokens as the max_token penalty. Setting this lower won't reduce costs but may cut off long tool uses, causing the Claude Code agent loop to fail persistently.

What's Wrong or Missing?

There is a conflict between the general default and the platform-specific requirement. A user setting up Claude Code with Amazon Bedrock who references the general settings.md page (or relies on the default value of 32,000) will encounter persistent agent loop failures due to Bedrock's specific throttling logic. The settings.md page currently lacks a warning or cross-reference regarding this Bedrock-specific limitation.

Suggested Improvement

Update the description in the settings.md Environment Variables table to include a specific note for Bedrock users.

Current text:
"Set the maximum number of output tokens for most requests. Default: 32,000. Maximum: 64,000. Increasing this value reduces the effective context window available before auto-compaction triggers."

Suggested text:
"Set the maximum number of output tokens for most requests. Default: 32,000. Maximum: 64,000. Increasing this value reduces the effective context window available before auto-compaction triggers. Note: Amazon Bedrock users should set this to 4096 to avoid throttling issues. See Amazon Bedrock configuration for details."

Impact

High - Prevents users from using a feature

Additional Context

This is a minor severity issue, but it creates a potential configuration conflict that breaks the agent loop for Bedrock users. Adding the cross-reference ensures users configuring their environment variables via the main settings page are aware of platform-specific constraints.