中转站调用Claude Code时遇到的 “defer_loading: Extra inputs are not permitted” 错误完全解决指南

大家好,我最近在使用 Claude Code(claude -p)通过**转发站(LiteLLM 等代理)**调用 AWS Bedrock 上的 Anthropic 模型时,频繁遇到以下错误:

bash 复制代码
⎿ API 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: ...)"}

这个错误在 2025 年底到 2026 年初非常常见,尤其在使用 Claude Code 较新版本(2.1.x 系列)结合 Bedrock 时。

错误根本原因

defer_loading 是 Anthropic 推出的实验性(beta)功能,主要用于 Tool Search / 动态工具加载 。它的作用是允许把工具标记为 defer_loading: true,让 Claude 模型按需加载工具,而不是一次性把所有工具定义塞进请求中,从而节省 token 和提升效率。

然而,AWS Bedrock 当前对这个字段的支持并不完善。当请求体(尤其是 tools 定义)中包含 tools.*.custom.defer_loading 或类似自定义字段时,Bedrock 会直接抛出 ValidationException,认为这是"不允许的额外输入"(Extra inputs are not permitted)。

这个不兼容问题主要出现在:

  • 通过 LiteLLM、其他代理或自定义转发站调用 Bedrock 时
  • Claude Code 自动开启了实验性功能(如 Tool Search、Agent Teams、大量 MCP tools)
  • Claude Code 版本较新(2.1.22 及以上),默认或自动添加了 beta 字段

常见触发场景

  • 使用 claude -p 或 Claude Code 的 headless 模式
  • 启用了大量工具(tools)或 Tool Search 功能
  • 环境变量中开启了 ENABLE_TOOL_SEARCH 或类似实验特性
  • 通过 LiteLLM proxy 转发到 bedrock/us.anthropic.claude-xxx 模型

推荐修复方案(按优先级排序)

1. 最简单有效的方法:关闭实验性 Beta 功能(强烈推荐)

在运行 Claude Code 时设置环境变量:

bash 复制代码
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

或者在 Claude Code 的配置文件(通常是 settings.json)中添加:

json 复制代码
{
  "env": {
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}

这个变量会自动剥离 Anthropic 特定的 beta 请求头和工具 schema 中的实验字段(如 defer_loading),同时保留标准字段(name、description、input_schema 等)。设置后大多数情况下错误立即消失。

2. 如果使用 LiteLLM 作为转发站

在 LiteLLM 的模型配置中为 Bedrock 模型添加以下参数:

yaml 复制代码
litellm_params:
  model: bedrock/us.anthropic.claude-sonnet-xxx
  drop_params: true
  # 或者更精确地指定要丢弃的字段
  additional_drop_params: ["defer_loading", "context_management"]

drop_params: true 会让 LiteLLM 自动过滤不支持的额外参数,是通过代理时最方便的解决方案。

3. 其他实用调整
  • 临时关闭 Tool Search:设置 ENABLE_TOOL_SEARCH=false 或 ENABLE_TOOL_SEARCH=auto:30(提高阈值,减少 defer_loading 触发)
  • 降低工具数量:如果工具列表过大,先精简工具定义
  • 更新相关工具到最新稳定版本,但注意 Claude Code 的新版本有时会默认开启更多实验特性
4. 长期建议
  • 如果对实验功能(如动态工具加载)有强需求,优先考虑直接使用 Anthropic 原生 API(非 Bedrock),兼容性更好。
  • 关注 Anthropic 和 AWS Bedrock 的更新,未来这个字段应该会得到更好的支持。
  • 在生产环境中,建议在代理层统一做好参数清洗(drop extra params),避免类似兼容性问题反复出现。

总结

这个错误本质上是 Anthropic 的实验特性 与 AWS Bedrock 当前 API 限制 之间的兼容性问题,并非你的代码或配置有根本性错误。通过设置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 或在 LiteLLM 中启用 drop_params,大多数用户都能快速解决。

如果你也遇到了类似问题,欢迎在评论区分享你的具体环境(Claude Code 版本、是否用 LiteLLM、用了多少 tools 等),我可以帮你进一步细化解决方案。

希望这篇文章能帮到正在被这个 400 错误困扰的同学!如果觉得有用,欢迎转发给同样在使用 Claude + Bedrock 的朋友。


发布日期 :2026 年 3 月
作者:Hong(基于实际踩坑经验整理)

有任何疑问或更新,欢迎留言讨论~

相关推荐
逐梦苍穹2 天前
不训练不微调:直接改权重矩阵,给小模型补上新能力
ai编程·codex·claudecode
小七-七牛开发者4 天前
周 1 上线 | DSH 喜提原神进场动画,Anthropic 启动 IPO 路演;黄仁勋辞任;微软全球大宕机超 24 小时
ai·大模型·agent·token·工作流·claudecode·ai coding
逐梦苍穹5 天前
DeepInfer 推理框架源码精讲:逐行读 DeepSeek 开源的推理引擎(2 小时 20 分视频+文字版)
人工智能·开源·ai编程·deepseek·claudecode·deepinfer·deepseekinfer
meijinmeng10 天前
如何像使用高级工程师一样使用 Claude,而不是像使用聊天机器人一样使用 Claude
claudecode·ai开发工具实战
Florian13 天前
Claude Memory 设计解读:记住经验,保留边界
memory·claudecode·harness·dreaming
信息安全失业大专人员18 天前
每日了解一个智能体-ClaudeCode
智能体·claudecode
大连好光景25 天前
Claude Code Agent SDK详解
lsp·hooks·mcp·claudecode·skills·mcp命名规范与调用权限
范中勤1 个月前
缓存 Key 规范与 Claude 动态/静态 Prompt Cache 机制详解
claudecode·promptcache·缓存key·agent工程·动静边界
人生百态,人生如梦1 个月前
Ubuntu在低版本下使用ccswitch+claudecode(CCSwitch+Docker+Claude)连调教程
linux·ubuntu·docker·claudecode·ccswitch
三水写代码2 个月前
手写一个 Claude Code(1):从 Agent Loop 到工具、权限、Hooks 与任务规划
python·ai编程·claude·ai agent·claudecode