【Claude】Extra inputs are not permitted 错误代理剥离 Beta 标头的解决方案 bug报错已解决在使用 Claude Code 通过代理或 LLM 网关如 LiteLLM、OpenRouter、Nginx 反向代理连接 Anthropic API 时你可能会遇到一个令人困惑的 400 错误Extra inputs are not permitted。这个错误通常与defer_loading、context_management等字段相关根本原因是代理/网关在转发请求时剥离了 Anthropic 的 Beta 标头。本文将深入分析该错误的技术原理并提供多种经过验证的解决方案。一、错误现象1.1 典型报错信息根据使用场景和后端 API 的不同错误信息有以下几种变体变体 A通过 AWS BedrockAPI Error: 400 {error:{type:nil,message:InvokeModelWithResponseStream: operation error Bedrock Runtime: InvokeModelWithResponseStream, https response error StatusCode: 400, RequestID: 8752a71a-e464-4591-8eeb-bf3aa405e8c5, ValidationException: ***.***.custom.defer_loading: Extra inputs are not permitted (request id: ...)}}变体 B通过 LiteLLM / OpenRouterAPI Error: 400 ... context_management: Extra inputs are not permitted变体 C直接调用 Anthropic API但通过代理API Error: 400 {type:invalid_request_error,message:Extra inputs are not permitted}1.2 触发条件条件说明Claude Code 版本≥ 2.1.22引入了实验性 Beta 功能连接方式通过代理/网关/中转站连接 API后端 APIAWS Bedrock、Vertex AI、第三方中转功能触发Tool Search、动态工具加载、上下文管理等 Beta 功能1.3 不受影响的场景直接连接 Anthropic 原生 API不经过任何代理使用官方 Claude.ai 网页版使用 Claude Code 直连 API设置ANTHROPIC_API_KEY不设置ANTHROPIC_BASE_URL二、根本原因深度分析2.1 什么是 Beta 标头Anthropic 在其 API 中使用anthropic-betaHTTP 标头来声明请求中使用了哪些实验性功能。这是一种标准做法——允许 API 消费者选择加入尚未正式发布的特性。示例请求头anthropic-beta: prompt-caching-scope-2026-01-05,defer-loading-2026-03-152.2 什么是实验性 Beta 功能Claude Code 在新版本中引入了多个实验性功能这些功能通过 Beta 标头和额外的请求字段实现Beta 功能请求字段说明Tool Search / 动态工具加载tools.*.custom.defer_loading允许将工具标记为defer_loading: true按需加载工具以节省 token上下文管理context_management智能管理上下文窗口自动裁剪不必要的内容Prompt Caching Scopeprompt-caching-scope更精细的缓存控制2.3 错误发生的完整链路Claude Code 发送请求 │ ├── 请求体包含 Beta 字段如 defer_loading、context_management ├── 请求头包含 anthropic-beta 标头声明这些字段 │ ├── 请求到达代理/网关 │ └── 代理/网关处理请求 │ ├── 可能剥离 anthropic-beta 标头 ❌ │ └── 但保留请求体中的 Beta 字段 │ └── 请求到达 Anthropic API / AWS Bedrock ├── 收到请求体中的 Beta 字段 ├── 但没有 anthropic-beta 标头来解释这些字段 └── 结果这些字段被视为不允许的额外输入 → 400 错误2.4 为什么代理会剥离 Beta 标头代理/网关剥离anthropic-beta标头的原因通常有以下几种默认行为许多反向代理如 Nginx默认不会转发所有自定义标头安全策略企业代理可能过滤未知标头协议限制某些 LLM 网关如 OpenRouter可能不支持 Anthropic 特有的标头AWS Bedrock 的 API 限制Bedrock 的 API 规范不包含 Anthropic 的 Beta 字段即使标头正确传递Bedrock 也会拒绝这些字段2.5 两个不同的问题层面需要区分两个问题层面问题层面说明影响标头被剥离代理不转发anthropic-beta标头Anthropic 原生 API 无法识别 Beta 字段后端不支持AWS Bedrock 不支持这些 Beta 字段即使标头正确传递也会被拒绝对于 Anthropic 原生 API问题是标头被剥离。解决方案是确保标头被正确转发。对于 AWS Bedrock问题是 Bedrock API 不支持这些字段。解决方案是从请求中移除这些字段。三、解决方案方案一禁用实验性 Beta 功能最简单有效强烈推荐这是最简单的解决方案适用于所有场景。通过设置环境变量让 Claude Code 不再发送实验性 Beta 字段和标头。方法1设置环境变量exportCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS1方法2在配置文件中设置在~/.claude/settings.json中添加{env:{CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS:1}}方法3在 Shell 配置文件中永久设置ZshmacOS 默认echoexport CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS1~/.zshrcsource~/.zshrcBashechoexport CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS1~/.bash_profilesource~/.bash_profile效果设置后Claude Code 会自动✅ 剥离 Anthropic 特定的 Beta 请求头✅ 移除工具 schema 中的实验字段如defer_loading✅ 移除请求体中的context_management等实验字段✅ 保留标准字段name、description、input_schema 等大多数情况下设置此环境变量后错误立即消失。注意禁用实验性 Beta 功能意味着你无法使用 Tool Search动态工具加载等新特性。如果你需要这些功能请参考方案二或方案三。方案二配置代理/网关正确转发 Beta 标头如果你需要保留 Beta 功能可以配置代理/网关正确转发anthropic-beta标头。2.1 LiteLLM 配置LiteLLM 是最常用的 LLM 代理之一有两种处理方式方式A自动丢弃不支持的参数model_list:-model_name:claude-sonnetlitellm_params:model:bedrock/us.anthropic.claude-sonnet-4-20250514drop_params:true# 自动丢弃不支持的参数drop_params: true让 LiteLLM 自动过滤后端不支持的额外参数是最方便的解决方案。方式B精确指定要丢弃的字段model_list:-model_name:claude-sonnetlitellm_params:model:bedrock/us.anthropic.claude-sonnet-4-20250514drop_params:trueadditional_drop_params:[defer_loading,context_management]方式C转发到 Anthropic 原生 API如果你使用 Anthropic 原生 API而非 Bedrock需要确保标头被正确转发model_list:-model_name:claude-sonnetlitellm_params:model:anthropic/claude-sonnet-4-20250514api_key:os.environ/ANTHROPIC_API_KEY# LiteLLM 默认会转发 anthropic-beta 标头2.2 Nginx 反向代理配置如果你使用 Nginx 作为反向代理需要显式配置标头转发server { listen 443 ssl; server_name your-proxy.example.com; location /v1/ { proxy_pass https://api.anthropic.com/v1/; # 关键转发 anthropic-beta 标头 proxy_pass_header anthropic-beta; proxy_set_header anthropic-beta $http_anthropic_beta; # 其他必要标头 proxy_set_header Host api.anthropic.com; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # SSE 支持流式响应 proxy_buffering off; proxy_cache off; proxy_read_timeout 300s; } }关键配置说明proxy_pass_header anthropic-beta允许anthropic-beta标头通过代理proxy_set_header anthropic-beta $http_anthropic_beta将客户端发送的anthropic-beta标头转发给上游2.3 OpenRouter 配置OpenRouter 作为第三方 LLM 网关对自定义标头的支持有限。如果遇到此问题检查 OpenRouter 是否支持传递anthropic-beta标头如果不支持使用方案一禁用 Beta 功能或考虑切换到直接连接 Anthropic API2.4 通用检查方法无论使用什么代理都可以通过以下方法检查标头是否被正确转发# 在代理服务器上检查请求头# 方法1使用 tcpdump 抓包sudotcpdump-iany-A-s0tcp port 443|grep-ianthropic-beta# 方法2在代理后端添加日志# Nginx 示例在 location 块中添加access_log /var/log/nginx/anthropic_debug.log;log_format anthropic_debug$http_anthropic_beta;方案三调整 Tool Search 配置defer_loading字段主要与 Tool Search 功能相关。如果你不想完全禁用 Beta 功能可以调整 Tool Search 的配置。3.1 关闭 Tool SearchexportENABLE_TOOL_SEARCHfalse3.2 提高 Tool Search 阈值减少defer_loading的触发# 设置更高的阈值默认30设为更大的值减少触发exportENABLE_TOOL_SEARCHauto:503.3 减少工具数量如果你的 MCP 服务器配置了大量工具精简工具列表可以减少defer_loading的使用检查~/.claude/settings.json中的 MCP 配置禁用当前不需要的 MCP 服务器运行/doctor检查工具 token 占用方案四直接连接 Anthropic 原生 API如果你需要使用 Beta 功能且代理/网关无法正确处理最可靠的方案是绕过代理直接连接。4.1 取消代理配置unsetANTHROPIC_BASE_URLunsetHTTP_PROXYunsetHTTPS_PROXY4.2 使用 API Key 直连exportANTHROPIC_API_KEYsk-ant-api03-xxxxx# 不设置 ANTHROPIC_BASE_URL直连 api.anthropic.com4.3 AWS Bedrock / Vertex AI 用户的替代方案如果你必须使用 Bedrock 或 Vertex AI如合规要求但又需要 Beta 功能使用 Anthropic 原生 API 作为开发环境Bedrock/Vertex 作为生产环境等待 Bedrock/Vertex 更新支持这些 Beta 字段在代理层实现参数清洗见方案二中的 LiteLLMdrop_params配置四、方案选择指南根据你的具体场景选择最合适的方案场景推荐方案理由通过 Bedrock/Vertex 使用 Claude Code方案一最简单Bedrock 不支持 Beta 字段通过 LiteLLM 代理方案二LiteLLM drop_params保留基本功能自动过滤通过 Nginx 反向代理方案二Nginx 配置配置标头转发即可通过 OpenRouter方案一OpenRouter 对自定义标头支持有限需要 Beta 功能方案四直连唯一能完整使用 Beta 功能的方式不确定使用什么方案方案一先禁用 Beta 功能确认问题再根据需要调整五、验证与回归测试5.1 验证修复应用修复后按以下步骤验证步骤1运行 /doctorclaude doctor确认无新的错误项。步骤2测试基本对话向 Claude Code 发送一条简单消息确认能正常响应步骤3测试 MCP 工具尝试使用 MCP 工具确认连接正常步骤4测试流式响应进行一段较长的代码生成确认流式输出正常5.2 回归测试检查清单检查项预期结果基本对话正常响应无 400 错误MCP 工具连接工具可正常调用流式响应输出完整无截断Tool Search如果启用了 Beta 功能应正常工作/doctor诊断所有检查项通过/usage查询正常显示用量信息六、常见问题Q1禁用 Beta 功能会影响什么功能影响Tool Search动态工具加载❌ 不可用上下文管理自动裁剪❌ 不可用基本对话和代码生成✅ 正常MCP 工具使用✅ 正常文件操作✅ 正常搜索功能✅ 正常Q2如何确认我的代理是否在剥离标头在 Claude Code 中启用调试日志exportCLAUDE_CODE_DEBUG1claude查看日志中的请求头确认anthropic-beta是否被发送且是否出现在代理的转发请求中。Q3为什么直接连接没问题通过代理就有问题直接连接时Claude Code 的请求直接到达 Anthropic API所有标头和字段都被正确传递。通过代理时代理可能会修改或删除部分标头和字段导致 API 无法正确识别请求。Q4使用 drop_params 会不会丢失重要功能drop_params只丢弃后端不支持的字段。对于 Bedrock 来说defer_loading和context_management本身就不被支持丢弃它们不会影响基本功能——只是无法使用这些实验性特性。Q5每次更新 Claude Code 都需要重新处理这个问题吗有可能。Claude Code 的新版本可能引入新的实验性 Beta 功能和字段。如果你使用代理/网关建议升级后先运行/doctor如果出现新的 400 错误确认是否为新的 Beta 字段导致确保CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS1仍然生效或更新代理配置以处理新字段七、预防措施与最佳实践7.1 代理层统一参数清洗在生产环境中建议在代理层统一做好参数清洗# LiteLLM 配置示例litellm_params:drop_params:trueadditional_drop_params:[defer_loading,context_management]这样即使 Claude Code 新增 Beta 字段也不会因为后端不支持而导致错误。7.2 版本管理建议关注更新日志了解每个版本引入了哪些 Beta 功能灰度升级先在测试环境验证新版本确认无兼容性问题后再升级生产环境环境变量优先使用环境变量而非硬编码配置方便快速调整7.3 监控与告警监控 400 错误率如果突然出现大量 400 错误可能是新增了不兼容的 Beta 字段日志分析定期分析代理日志确认标头是否被正确转发自动化测试在 CI/CD 中加入基本的 Claude Code 调用测试7.4 长期建议如果对实验功能如动态工具加载有强需求优先考虑直接使用Anthropic 原生 API关注 Anthropic 和 AWS Bedrock 的更新未来这些字段应会得到更好的支持在代理层做好参数清洗避免类似兼容性问题反复出现八、总结速查修复方式适用场景难度是否保留 Beta 功能CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS1所有代理/网关场景⭐ 最简单❌ 不保留LiteLLMdrop_params: true通过 LiteLLM 代理⭐⭐ 简单部分标准功能保留Nginx 转发anthropic-beta标头通过 Nginx 代理⭐⭐ 简单✅ 保留调整 Tool Search 配置工具数量多时⭐⭐ 简单部分直连 Anthropic 原生 API需要 Beta 功能⭐⭐⭐ 中等✅ 完整保留核心原则Extra inputs are not permitted错误的根源是代理/网关与 Anthropic Beta 功能之间的兼容性问题。解决思路只有两条——要么让代理正确处理 Beta 字段要么让 Claude Code 不发送 Beta 字段。选择哪条路线取决于你是否需要这些实验性功能。