WebSearch 不再搜满 200 次就停：改成每小时回填 100 次

一个会话开一整天、让 Claude 边查资料边写代码的人，可能遇到过这种情况：前半天联网搜索好好的，到了下午 Claude 突然说搜不了了，只能凭已有知识回答。原因是交互会话里的 WebSearch 有一个总次数上限，以前是 200 次，用完这个会话就不能再搜。

CLI 2.1.290 把这个规则改了：额度不再是一次性的，而是随时间回填。

改了什么

• 以前：每个交互会话最多调用 WebSearch 200 次，用完为止，只能新开会话。
• 现在：额度按时间慢慢补回来，默认每小时 100 次。短时间内搜得很密时仍会碰到上限，但等一会儿就能接着搜，不用重开会话。
• 可调：新增环境变量 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR 设回填速度；设为 0 就是关掉回填。

这条改动针对的是交互会话。-p 无头模式、CI 里跑的脚本是不是同一套规则，变更说明里没讲，以你所用版本实测为准。

谁会感觉到差别

• 长会话用户：一个终端窗口挂一整天，靠 --continue 接着干的人，最容易在下午碰到「搜索额度用完」。
• 调研类任务：让 Claude 对比库的版本、查报错、翻文档，一个任务就可能连续搜几十次。
• 多步 Agent 流程：子代理、长计划里每一步都要查一下资料时，总量涨得很快。

只是偶尔让 Claude 查一两次的人，基本感觉不到变化。

怎么配置

默认值就够大多数人用，不需要改。确实想调的话，在启动 Claude Code 的环境里设：

# 每小时回填 30 次，适合想控制联网次数的场景
export CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=30
claude

# 关掉回填
export CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=0
claude

团队想统一的话，可以写进 settings 的 env 字段。几点提醒：

• 设为 0 只是不再回填，不是关掉 WebSearch 本身。关掉回填后额度上限具体是多少，以实测为准。
• 想让 Claude 完全不联网读网页，应该用 CLAUDE_CODE_DISABLE_WEB_FETCH 或权限规则，而不是靠这个变量。
• 回填速度调得太低，长任务中途可能频繁等额度，Claude 会退回凭已有知识回答，结果的时效性会变差。

碰到「搜不了」时怎么排查

1. claude --version 确认 ≥ 2.1.290。老版本还是 200 次用完即停，升级后重新开会话。
2. 检查自己或团队有没有设过 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=0 或一个很小的值。
3. 如果是短时间内连续大量搜索，等一段时间再让 Claude 搜。
4. 搜索本身报错（不是次数问题）的话，看看是不是历史记录或网关的问题，参考 WebSearch 历史 400 报错。

小结

• 交互会话的 WebSearch 从「200 次用完就停」改成每小时回填 100 次。
• 新增 CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR 调回填速度，0 表示关掉回填。
• 长会话、调研类任务受益最大；想彻底禁止联网，请用专门的开关或权限规则。

一个会话挂一整天的人，升级到 2.1.290 后基本不用再为了「搜索额度」去重开会话。