所有文章
AnthropicClaudeAItool use

在本地使用 Anthropic 工具调用:面向 Claude 的隧道

Claude 的工具调用不是 webhook。你的后端发送一条消息,Claude 回应,有时附带调用某个工具的请求,你的代码运行该工具并把结果发回。整个过程都通过从你机器发出的出站 HTTPS 完成。那这篇文章为什么讲隧道?

因为一旦你用 Claude 构建任何真实的东西——编码代理、客服自动化、MCP 服务器、长时间运行的工作流——你就开始需要入站连通性。为浏览器客户端。为暴露给其他应用的 MCP 服务器。为模型调用的第三方工具发回的 webhook。

隧道真正派上用场的地方

Claude 应用的浏览器前端

OpenAI Realtime 配置形态相同。你的前端不能保存 Anthropic API 密钥,所以它和后端通信,后端再和 Anthropic 通信。前端需要 HTTPS 才能让流式响应干净渲染(某些浏览器在纯 HTTP 上会降级 SSE 处理),如果前端是 HTTPS,后端也需要 HTTPS。隧道两者都能搞定。

本地运行的 MCP 服务器

Model Context Protocol 让 Claude(以及其他客户端)连接到你以 MCP 服务器形式暴露的工具。对于 HTTP 传输的 MCP 服务器——区别于 stdio——客户端需要能访问到你的服务器。如果你在原型一个 MCP 服务器并想用 Claude Desktop 或其他远程客户端测试,通过隧道暴露本地 MCP 服务器是阻力最小的路径。

computer use 回调

如果你在使用 Claude 的 computer use 测试版,且模型与一个向你机器发回 webhook 的服务交互,你就进入了 webhook 领域。和任何服务商相同的模式:捕获、重放、验证(如适用)。

隧道不做的事

仅仅从本地脚本调用 Claude 不需要隧道。curl https://api.anthropic.com/v1/messages 在任何机器上都能用。Python 和 TypeScript 的 SDK 也都正常。工具调用本身是出站交互——Claude 想用工具时不会调用你的机器,而是你的代码根据 Claude 的回应去调用。

第一次接触时有些人会被绊住。模式是:

  1. 你的代码把用户消息连同可用工具列表发给 Claude。
  2. Claude 回应,可能带一个描述要调用工具的 tool_use 块。
  3. 你的代码针对你的本地系统执行该工具。
  4. 你的代码把工具结果作为后续消息发回给 Claude。
  5. 循环直到完成。

这五步全部发生在一个 Python 或 TypeScript 进程里。没有入站流量。没有隧道。

隧道帮助 Claude 工作流的真正原因

我们在 Claude 开发中最终运行隧道的原因不是模型本身,而是它周围的一切:展示代理进度的仪表盘、流式输出工具结果的前端、为测试而暴露的 MCP 服务器、代理调用的第三方工具发来的 webhook(“发一条 Slack 消息”“在 Linear 创建一个工单”)。代理触发一连串连锁反应,而在这条链的某处,一个外部服务最终想要访问你的机器。

MCP 服务器开发循环的配置

  1. 用 HTTP 传输实现你的 MCP 服务器。
  2. 在你选择的端口上本地运行它。
  3. npx portpreview 3000(或你的端口)。
  4. 在 Claude Desktop 或你的其他 MCP 客户端中,配置指向你隧道的远程服务器 URL。
  5. 发出命令。观察隧道中的请求捕获以及你服务器返回的响应。

如果你的 MCP 服务器是 stdio 传输,这一节不适用——stdio 服务器通过进程管道通信,按设计就是本地的。

流式响应与隧道

Claude 通过 SSE 流式返回响应。隧道必须正确处理长连接的流式响应——大多数都行,但一些老旧的 HTTP 代理会缓冲响应、只在结束时一次性刷出,这就破坏了流式的意义。PortPreview、Cloudflare 和 ngrok 处理 SSE 时不缓冲。如果你看到前端在长时间等待后一次性收到整个响应,说明你的隧道在缓冲。这是隧道的问题,不是 Claude 的问题。

调试代理循环

Claude 工具调用开发最难的部分不是 API,而是理解模型在每一步决定做什么。执行前记录每个 tool_use 块。返回 Claude 前记录每个工具结果。如果你的前端和后端之间有隧道,请求捕获还会给你一份用户消息的记录——便于在不重新输入提示的情况下重放代理运行。

趋势走向

Anthropic 的工具调用生态发展很快——MCP、computer use、更长的上下文窗口、更低的延迟。在本地调试 webhook 的 webhook 模式,以及签名验证指南里的签名运算,在代理调用的任何外部工具向你机器发回回调时都适用。

加入 PortPreview 等候名单,获得内置捕获、重放和 SSE 安全转发的隧道。

常见问题

使用 Claude 工具调用需要隧道吗?
核心 API 不需要。Claude 工具调用是出站交互——你的代码调用 Anthropic,Claude 返回工具请求,你的代码执行,再把结果发回。全是出站。只有当外部服务调用你的机器时才需要隧道:浏览器前端、远程暴露的 MCP 服务器,或向你发回 webhook 的第三方工具。
如何在本地用 Claude 测试 MCP 服务器?
对于 HTTP 传输的 MCP 服务器,在本地运行服务器并通过隧道暴露。用隧道 URL 配置 Claude Desktop(或其他远程 MCP 客户端)。stdio MCP 服务器不需要隧道,因为它们通过进程管道通信。
隧道会破坏 Claude 的流式响应吗?
大多数现代隧道处理 SSE 流式时不缓冲。如果你的前端在长延迟后一次性收到完整响应,说明隧道在缓冲并破坏了流式行为。PortPreview 和其他较新的隧道会避免这一点。