> https://router.one/zh/blog/claude-web-search-code-execution-api 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 发布：2026-09-02 · 作者：Router One Team

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

_经 Router One 的 Anthropic 兼容 /v1/messages 端点使用 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 服务端工具

普通的[工具调用](https://router.one/zh/llm-tool-calling)里，工具在你的代码里跑：你用 `input_schema` 声明一个函数，模型回一个 `tool_use` 块，你执行完再把 `tool_result` 发回去。这套循环在[目录](https://router.one/zh/models)里每个支持工具调用的模型上都通用，也是 OpenAI 兼容端点的用法。

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

Router One 的角色刻意收窄：校验 Key、把请求转发给 Claude 模型、写 Trace、按模型报告的 usage 结算。Router One 自身不执行工具，这条信任边界写在 [API 兼容性事实页](https://router.one/zh/facts/api-compatibility.md)上。

## 经 Router One 发送 web_search

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

```bash
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`：

```python
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` 事件到达，搜索期间会有一段停顿，事件流的细节见[流式输出指南](https://router.one/zh/llm-streaming)。

## 发送 code_execution

形状一样，换工具类型：

```bash
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 见[错误码页](https://router.one/zh/llm-api-error-codes)。

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

## 账单与请求 Trace

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

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

## 哪些模型、哪个端点

服务端工具是 `/v1/messages` 上 Claude 系列的能力。哪个 Claude 模型支持哪个工具版本由 Anthropic 决定且会变；[目录](https://router.one/zh/models)里现有的 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 国内接入](https://router.one/zh/claude-code-china)把 `ANTHROPIC_BASE_URL` 与 `ANTHROPIC_AUTH_TOKEN` 指向 Router One 之后，WebSearch 照常可用，国内直连不需要 VPN；遇到 5xx 或超时，网关按同一模型的候选线路做故障转移。Claude Code 的 WebFetch 是自己抓页面，不经 `web_fetch` 服务端工具，所以上面的拒绝不影响它。各项接受时间见[更新日志](https://router.one/zh/blog/changelog)。

## 常见问题

**经 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` 上的所有模型，都用客户端函数工具。

## 下一步

- 读[工具调用指南](https://router.one/zh/llm-tool-calling)，掌握在所有模型上通用的客户端循环。
- 按 [Claude Code 国内接入](https://router.one/zh/claude-code-china)把 Claude Code 指向网关——WebSearch 一并可用。
- [Messages 端点参考](https://router.one/zh/docs/chat/createMessage)与 [API 文档](https://router.one/zh/docs)写明了请求与错误的形状。
- 在[模型目录](https://router.one/zh/models)里挑一个 Claude 模型，查看它的端点与实时单价；折扣口径见[价格页](https://router.one/zh/pricing)。

## 相关页面

- 本页规范地址：https://router.one/zh/blog/claude-web-search-code-execution-api
- LLM API 网关与路由：https://router.one/zh/llm-api-gateway
- 全部博客文章：https://router.one/zh/blog
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md