Claude 服务端工具 web_search 与 code_execution 接入指南

Claude 的服务端工具可以经 Router One 使用。在 Anthropic 兼容的 POST /v1/messages 端点上，web_search 服务端工具与 code_execution 工具（含 bash_code_execution、text_editor_code_execution 两个子工具，以及跨轮次的容器复用）按 Anthropic 官方定义原样接受。

在 tools 里声明带日期版本的工具类型，把请求发到 https://api.router.one/v1/messages，带上 Router One 的 Key 和一个 Claude 目录 id，搜索或沙箱执行在模型侧完成，Router One 负责转发请求、按该模型标准 token 费率计量、记录每请求 Trace。国内直连，无需 VPN；钱包用支付宝或银行卡充值。两样东西过不去：web_fetch 服务端工具和 MCP（mcp_toolset 工具或 mcp_servers 字段）会在调用任何模型之前被拒绝，返回 HTTP 400 invalid_request_error。本文给出精确的请求形状、响应块长什么样，以及账单和 Trace 怎么读。

客户端工具 vs 服务端工具

普通的工具调用里，工具在你的代码里跑：你用 input_schema 声明一个函数，模型回一个 tool_use 块，你执行完再把 tool_result 发回去。这套循环在目录里每个支持工具调用的模型上都通用，也是 OpenAI 兼容端点的用法。

服务端工具把循环反过来。你只声明一个带日期的 type（web_search_20250305、code_execution_20250825），不带 schema；模型供应商的 API 在同一个请求内部完成搜索或沙箱执行——可能反复几轮——最后返回带引用的正文或执行输出。请求中途不会有任何东西回到你的代码。

Router One 的角色刻意收窄：校验 Key、把请求转发给 Claude 模型、写 Trace、按模型报告的 usage 结算。Router One 自身不执行工具，这条信任边界写在 API 兼容性事实页上。

经 Router One 发送 web_search

就是你熟悉的 Anthropic Messages 请求，换个主机名：

curl https://api.router.one/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "最新一个 Node.js LTS 版本改了什么？给出来源。"}
    ],
    "tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}]
  }'

有三个细节值得留意。Key 放在 x-api-key 或 Authorization: Bearer 都行，后者正是 Claude Code 通过 ANTHROPIC_AUTH_TOKEN 发出的形式。model 填目录 id（anthropic/claude-sonnet-4.6）；多数官方原名如 claude-sonnet-4.6 也作为别名接受，但目录 id 最稳。max_uses、allowed_domains / blocked_domains（二选一，不能同时给）和 user_location 原样转发，更新的工具版本 web_search_20260209（动态过滤）与 web_search_20260318（response_inclusion）同样如此。

用官方 Python SDK 时，base_url 只填主机名，SDK 自己会拼上 /v1/messages：

import anthropic

client = anthropic.Anthropic(
    api_key="sk-your-api-key",
    base_url="https://api.router.one",  # 只填主机名，SDK 会补 /v1/messages
)

response = client.messages.create(
    model="anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "最新一个 Node.js LTS 版本改了什么？给出来源。"}],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
print(response.usage.server_tool_use)  # web_search_requests=N

响应的 content 数组按这一轮发生的顺序排列：一个 Claude 决定去搜的 text 块，一个 server_tool_use 块（name: "web_search"，查询词在 input 里），一个 web_search_tool_result 块（content 是 web_search_result 列表，含 url、title、page_age 和 encrypted_content），最后是带 citations 的 text 块，引用类型为 web_search_result_location。usage.server_tool_use.web_search_requests 记录搜索次数。要继续对话，把 assistant 的块原样发回去，encrypted_content 也要带上——Router One 接受下一轮回放的 server_tool_use 与 web_search_tool_result 块，并像其他内容一样按输入 token 计量。开 stream: true 时同样的块以 content_block_start 事件到达，搜索期间会有一段停顿，事件流的细节见流式输出指南。

发送 code_execution

形状一样，换工具类型：

curl https://api.router.one/v1/messages \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 4096,
    "messages": [
      {"role": "user", "content": "从正态分布抽 1000 个样本，报告均值、中位数和标准差。"}
    ],
    "tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
  }'

Claude 会返回名为 bash_code_execution（跑 shell 命令）或 text_editor_code_execution（查看、创建、编辑文件）的 server_tool_use 块，每个后面跟一个带 stdout、stderr 和 return_code 的 bash_code_execution_tool_result 块，或一个承载查看 / 创建 / 编辑结果的 text_editor_code_execution_tool_result 块，然后才是最终正文。响应顶层还有一个 container 对象，含 id 和 expires_at；下一轮把这个 id 作为顶层 container 请求参数发回去，就能保留 Claude 创建的文件——Router One 接受跨轮次的容器 id。需要 REPL 状态保持或程序化工具调用时，code_execution_20260120 与 code_execution_20260521 同样原样转发。

不需要 anthropic-beta 头：当前三个 code execution 版本都不要求它，旧的 beta 头只是可选的兼容开关。如果你的 SDK 或旧集成仍然发 anthropic-beta，Router One 会原样转发。

一条要提前规划的边界：Router One 不提供 Files API。把 code execution 用在结果直接回到响应正文的工作上——stdout、计算结果、文本——而不是依赖按 file_id 上传输入文件或事后下载生成文件的流程。

Router One 拒绝什么，为什么这反而有用

三样东西会在调用任何模型之前被拒绝，均为 HTTP 400，使用 Anthropic 错误外层结构 {"type":"error","error":{"type":"invalid_request_error","message":...},"request_id":...}：

• web_fetch 服务端工具，任何日期版本；
• mcp_toolset 工具条目；
• 非空的 mcp_servers 字段（MCP connector）。

错误信息会点名被拒绝的特性，改法一目了然；而且请求根本没到模型，一个 token 都不花。你的 SDK 抛出的就是普通 Anthropic 400 对应的 BadRequestError。这个端点上其他的 400 见错误码页。

替代方案很直接。要网页内容，要么让 web_search 把它带进来（搜索结果会加载进模型上下文），要么在自己的代码里抓取页面、把文本作为普通内容块传入。要 MCP，就在你这边跑 MCP 客户端，把它发现的工具作为客户端函数工具暴露给模型——工具调用指南里的循环正是干这个的。

账单与请求 Trace

服务端工具的活动按该模型的标准 token 费率计量。Claude 读到的搜索结果和消费的执行输出，就是模型报告的 usage 里的输入和输出 token，按模型页公示的单价结算——例如 Claude Sonnet 4.6——没有单独的按次搜索或按容器计费行，容器时长也不另外按次计费。价格页有当前费率，部分模型最低官方价 1 折（最高省 90%）。

每个请求都会进入 Dashboard → Logs，带模型、输入输出 token、费用、延迟和状态；一轮搜索密集或执行密集的对话，在 Trace 里就是一笔更大的 token 账，和其他调用放在同一张表里。自己记账的话，响应正文里的 usage.server_tool_use 记录了搜索和执行次数。如果 agent 可能触发没有上限的搜索，给 Key 设消费硬上限（maxSpend）和速率限制——与《Claude Code 为什么烧这么多 token》讲的 Key 级控制是同一套。

哪些模型、哪个端点

服务端工具是 /v1/messages 上 Claude 系列的能力。哪个 Claude 模型支持哪个工具版本由 Anthropic 决定且会变；目录里现有的 Claude id——anthropic/claude-opus-5、anthropic/claude-sonnet-4.6、anthropic/claude-haiku-4.5 及同门——各自的模型页都列有 POST /v1/messages。DeepSeek V4 也在 /v1/messages 上应答，但只支持客户端函数工具：服务端工具在那里没有执行方。OpenAI 兼容的 /v1/chat/completions 请求形状里没有 Anthropic 这种带类型的服务端工具的位置，所以在那个端点上，所有模型的工具调用都是客户端的。

对国内开发者来说，最直接受益的是 Claude Code：它内置的 WebSearch 依赖端点接受 web_search 服务端工具（在拒绝服务端工具的中转站上它会失效），所以按 Claude Code 国内接入把 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN 指向 Router One 之后，WebSearch 照常可用，国内直连不需要 VPN；遇到 5xx 或超时，网关按同一模型的候选线路做故障转移。Claude Code 的 WebFetch 是自己抓页面，不经 web_fetch 服务端工具，所以上面的拒绝不影响它。各项接受时间见更新日志。

常见问题

经 Router One 用 code_execution 需要 anthropic-beta 头吗？ 不需要。当前的 code_execution_20250825、code_execution_20260120、code_execution_20260521 三个版本都不要求 anthropic-beta 头。客户端如果照发，Router One 原样转发。

经 Router One 用 web_search，每次搜索另外收费吗？ 服务端工具活动按该模型的标准 token 费率计量：模型读到的搜索内容按模型报告的 usage 里的输入 token 计费，没有单独的按次搜索计费行。每请求 Trace 显示总额，响应里的 usage.server_tool_use.web_search_requests 记录搜索次数。

能经 Router One 用 web_fetch 或 MCP 服务器吗？ 不能。web_fetch 服务端工具、mcp_toolset 工具与 mcp_servers 字段会在调用任何模型之前以 HTTP 400 invalid_request_error 拒绝，请求不花钱。页面内容请在自己的代码里抓取；MCP 请在你这边跑客户端，把工具作为客户端函数工具暴露给模型。

Claude Code 的 WebSearch 经 Router One 能用吗？ 能。Claude Code 的 WebSearch 依赖端点接受本文讲的 web_search 服务端工具，而它在 /v1/messages 上被接受。按 Claude Code 国内接入页设置 ANTHROPIC_BASE_URL=https://api.router.one 与 ANTHROPIC_AUTH_TOKEN（填 Router One 的 Key）即可，国内直连无需 VPN。

服务端工具能发给 DeepSeek V4，或用在 /v1/chat/completions 上吗？ 不能。服务端工具在 Claude API 侧执行，只对 /v1/messages 上的 Claude 系列模型有意义。/v1/messages 上的 DeepSeek V4，以及 OpenAI 兼容端点 /v1/chat/completions 上的所有模型，都用客户端函数工具。

下一步

• 读工具调用指南，掌握在所有模型上通用的客户端循环。
• 按 Claude Code 国内接入把 Claude Code 指向网关——WebSearch 一并可用。
• Messages 端点参考与 API 文档写明了请求与错误的形状。
• 在模型目录里挑一个 Claude 模型，查看它的端点与实时单价；折扣口径见价格页。