AI代理的服务端代码执行工具对比

假设你正在构建一个代理，用于回答关于客户上传的CSV文件的问题。模型需要运行Python才能得出答案。那么这些代码在哪里运行？

一种选择是自己运行。这意味着需要一个沙箱平台，如 E2B 或 Modal，或者你在Docker上的自有容器，再加上让它远离你的数据库和互联网、限制其运行时长以及修补镜像等工作。

另一种选择是服务端代码执行工具。你将该工具添加到API请求中，模型决定何时需要运行某些内容，提供商在自己的沙箱中运行命令，并在同一请求内将输出返回给模型。这里的沙箱是指一个隔离的Linux容器，拥有自己的文件系统、时间限制，并且默认没有网络访问权限。

本文介绍目前提供这种沙箱的四个提供商，各自的沙箱能做什么、不能做什么，它在延迟和费用上的成本，以及哪些任务仍需要你自己运维的沙箱。

简要总结

• 服务端代码执行工具会在你的API请求期间，在提供商的沙箱中运行模型的命令。你无需配置、修补或加固容器。
• OpenAI、Anthropic和Google各自为其自家模型运行代码。我们的 openrouter:shell 工具可在Responses和Messages API上为任何模型运行命令，而我们的 openrouter:bash 工具仅在Messages API上提供同样的功能。两个工具目前都处于测试阶段。
• 我们的沙箱是一个以你的账户和工作区为范围的隔离容器，默认关闭出站网络访问，并对运行时长和输出大小设置每条命令的限制。沙箱时间按每秒0.0001美元计费，新建或休眠容器的最低计费为30秒。
• 对于自定义基础镜像、GPU任务或需要运行数小时的会话，自己运维沙箱平台仍然是正确的选择。

服务端代码执行的含义

模型自身从不运行任何东西。当它调用一个工具时，它会发出一个请求，指明工具名称和参数，而必须有某个东西去执行它。对于客户端工具，执行者是你的应用程序代码或你所构建的代理框架。你的应用程序接收调用、运行它，并在后续请求中把结果发回。对于服务端工具，提供商会在其自己的基础设施上运行该调用，并在同一请求内将结果返回给模型，因此你的应用程序无需为它编写处理逻辑。服务端代码执行就属于第二种。

你可能已经在使用以这种方式工作的工具。 网页搜索 让模型能够在实时互联网上查找信息， 网页抓取 让它能够读取URL的内容。在这两种情况下，你只需在请求中添加一个条目，其余由提供商完成。代码执行将同样的模式应用于运行命令。

工具调用如何变成实际运行的命令

这些步骤适用于任何服务端代码执行工具。凡是出现字段名的地方，都是我们的shell工具所使用的字段名。

1. 你将该工具包含在请求的 tools 数组中。
2. 模型决定需要运行某些内容，并发出一个携带一条或多条shell命令的调用。
3. 提供商会在一个沙盒容器中按顺序运行这些命令。
4. 每条命令的标准输出、标准错误和结果都会返回给模型。结果要么是一个退出码,要么是超时。
5. 模型读取结果后,要么回答你,要么在同一请求中运行更多命令。

第二到第五步会不断重复,直到模型给出答案。模型运行某个命令,读取输出,判断是否需要再运行下一条命令,然后再次执行。代码执行工具的价值正体现在这个循环中,因为模型可以依据真实输出检验自己的工作,而不是凭空猜测。

我们对这个循环设置了上限。 max_tool_calls 字段规定了一次请求可以执行的 servidor 工具步骤数。我们的 server tools reference 中,默认值和最大值均为 30。

托管沙盒与你自建沙盒的区别

自建沙盒意味着要承担原本由提供商承担的部分。你需要选择基础镜像、配置计算资源、接入 SDK 来启动运行并读取输出,并管理每次运行的生命周期。你还要自己负责安全边界。

托管工具用 JSON 数组中的一个条目换来了上述控制权。你无需调整容器规格、打补丁或运维容器。我们构建 openrouter:shell 就是为了应对每个请求只需少量短命令的场景。

如今谁在提供托管代码执行

本文涵盖 OpenAI、Anthropic、Google 和 OpenRouter。Agent SDK 和专用沙箱平台是单独的类别，两者都将在本文后面介绍。这四家提供商的区别在于它们各自为哪些模型运行代码。

OpenAI 为 OpenAI 模型运行一个托管 shell

OpenAI 的 shell 工具 在 Responses API 上，于 OpenAI 管理的容器中运行命令。OpenAI 将该托管运行时记录为 Debian 12，默认工作目录为 /mnt/data。命令在没有 sudo的情况下运行，且不支持交互式 TTY 会话。文档中列出的预装语言包括 Python 3.11、Node.js 22.16、Java 17、PHP 8.2、Ruby 3.1 和 Go 1.23。

托管容器默认没有出站网络访问。要启用它，组织管理员需在 OpenAI 控制台中配置白名单，并在请求中为容器环境设置 network_policy 在请求中的容器环境上。通过在一个请求中传入其 id,一个容器可以在多个请求之间重复使用。 container_reference 环境中传入其 id，容器可以在多个请求之间复用，其过期时间在创建容器时设定。OpenAI 还有一个单独的 代码解释器工具 用于 Python。

Anthropic 为 Claude 模型运行 Python 和 Bash

Anthropic 的 代码执行工具 在 Messages API 上，于 Anthropic 管理的沙箱中运行 Python 和 Bash。文档记载的环境是一个 Linux x86_64 容器，配备 Python 3.11、5 GiB 内存、5 GiB 工作区存储和一个 CPU。互联网访问被禁用，不允许任何出站连接，因此 Claude 只能使用预装的库，无法在运行期间安装软件包。

共有三种 工具版本 ，每个受支持的模型都接受全部三种。 code_execution_20250825 支持 Bash 命令和文件操作。 code_execution_20260120 增加了在请求之间持久化的 Python 解释器状态，这依赖于 Anthropic 的程序化工具调用，在 Claude Haiku 4.5 上不可用。容器在创建 30 天后过期。闲置约 5 分钟后，容器会被设置检查点，在 30 天窗口内传入其 id 的请求可以恢复它。

Google 为 Gemini 模型运行 Python

Google 的 代码执行工具 在 Google 管理的沙箱中运行 Python，通过请求 tools 中的一个 code_execution 条目来启用。文档指出，该模型只能生成并执行 Python，代码环境的最大运行时长为 30 秒，并且你无法安装自己的库。Google 发布了该环境包含的库列表。

我们为任何模型运行托管 shell

上述三个工具各自只能与一家公司的模型配合使用。我们的工具可与 Responses 和 Messages API 上的任何模型配合使用，因为我们在路由层而不是在单一模型提供商内部运行沙箱。

我们提供两个代码执行工具。 openrouter:shell 借鉴了 OpenAI 托管 shell 工具的形态，并且可以在 Responses API 以及 Messages API。 openrouter:bash 镜像了 Anthropic 的 bash 工具的形态，且仅适用于 Messages API。

这两个工具均处于 beta 阶段,因此 API 可能会变化。沙盒执行运行在全局 openrouter.ai 仅为端点。该 区域内端点 不提供 shell 工具，而 Chat Completions 会以 400 错误拒绝这两个工具，并指出支持它们的 API。

集合 engine 至 openrouter 在任一工具上，命令都会在我们的沙箱中运行。默认 engine 是 auto。对于 openrouter:shell, auto 在提供商存在原生托管 shell 时保留该原生托管 shell，否则路由到我们的沙箱。对于 openrouter:bash， auto 将工具调用返回到您的应用程序以在客户端运行，我们的服务器上不会执行任何内容。

在我们的沙盒中运行命令

以下是一个完整的请求，它会运行两个命令并读回结果。

import os
import requests

response = requests.post(
    "https://openrouter.ai/api/v1/responses",
    headers={"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"},
    json={
        "model": "anthropic/claude-sonnet-4.5",
        "input": "Run `cat /etc/os-release` and `python3 --version`, then tell me the OS and Python version in one sentence.",
        "tools": [
            {"type": "openrouter:shell", "parameters": {"engine": "openrouter"}}
        ],
    },
)

for item in response.json()["output"]:
    if item["type"] == "openrouter:shell":
        print(item["container_id"], item["action"]["commands"])
        for result in item["output"]:
            print(result["stdout"], result["outcome"])

我们于2026年9月22日运行了该请求。模型在一次shell调用中发送了这两条命令,每条命令都返回了自己的结果。完整 os-release 输出运行到多行，此处截取前两行。

{
  "type": "openrouter:shell",
  "container_id": "sess_art10-418b8597e044",
  "action": { "commands": ["cat /etc/os-release", "python3 --version"] },
  "output": [
    {
      "stdout": "PRETTY_NAME=\"Ubuntu 22.04.5 LTS\"\nNAME=\"Ubuntu\"\n",
      "stderr": "",
      "outcome": { "type": "exit", "exit_code": 0 }
    },
    {
      "stdout": "Python 3.11.14",
      "stderr": "",
      "outcome": { "type": "exit", "exit_code": 0 }
    }
  ]
}

沙箱报告称当天使用的是 Ubuntu 22.04.5 LTS 与 Python 3.11.14。运行时镜像可能会变化，因此应从容器中读取版本，而不是硬编码。 服务器工具参考 涵盖其余参数。

为您封装沙箱环境的 Agent SDK

如果你是基于代理 SDK 构建而不是直接调用 API，一些 SDK 会封装这些工具之一。

The OpenAI Agents SDK ships CodeInterpreterTool，它在 OpenAI 的沙箱中运行代码，以及 ShellTool，根据你对环境的配置方式，它既可以在你的本地运行时中运行，也可以在 OpenAI 托管的容器中运行。在假设某条命令已在远程运行之前，请先检查你配置的是哪种模式。在我们这边，openrouter:shell 是 tools 数组中的一个普通条目，因此它会进入与原始请求相同方式的 OpenRouter Agent SDK 循环。

哪些场景仍需要你自己的沙箱

托管工具适合简短、有边界的任务，例如运行脚本、转换文件或检查结果。任何需要特定基础镜像或 GPU 的任务都不属于这四种托管工具的范围，需要你自己运营的沙箱平台。

对比

每个托管工具单元格均来自上文链接的供应商自己的文档，唯有 OpenRouter 运行时单元格除外，它是我们运行上述请求时沙箱报告的结果。自管理一列描述的是你自己运行的沙箱，而非任何特定平台。

我们的沙盒强制执行的内容

沙盒的意义在于你不必信任模型。一条你从未打算执行的命令无法访问网络或他人的容器，并且会在运行时长和输出量的硬性限制处停止。本节中的所有内容描述的都是我们的沙盒。上表显示了其他三者在哪些地方有所不同。

适用于每条命令的限制

我们在一个隔离的容器中运行每条命令，该容器与为你的请求提供服务的 infra 结构以及你的机器相互分离，并且仅限于你的账户和工作区。你可以通过 timeout_ms 设置命令可运行的最长时间，通过 max_output_length 设置它可打印的最大输出量。 timeout_ms 默认值为 120,000 ms，且不能超过 300,000 ms。 max_output_length 默认值为每个流 16,384 个字符，且不能超过 65,536。包含超过 100 条命令的 shell 调用会被拒绝。

除非你主动开启，出站网络访问是关闭的。我们在 2026 年 9 月 22 日验证了这一点，方法是发送一个不带 network_policy 的请求，并要求模型获取 https://example.com ，同时 curl仅打印 HTTP 状态码，并在 5 秒后放弃。该命令打印了 000，这正是 curl 在没有响应到达时打印的内容，并以退出码 28 结束，即 curl 超时。

{ "stdout": "000", "stderr": "curl: (28) Failed to connect to example.com port 443 after 5206 ms: Connection timed out", "outcome": { "type": "exit", "exit_code": 28 } }

要开放网络，可设置一个最多包含 50 个主机名或 glob 模式的 network_policy 最多 50 个主机名或 glob 模式的允许列表。只有端口 80 和 443 是可达的，并且该策略在容器启动时即被固定。 pip install 需要同时将 pypi.org 和 files.pythonhosted.org 加入允许列表。

提示注入以及沙箱的限制范围

给模型一个 shell 会使你面临 提示注入的风险。如果你的智能体读取了某个网页、支持工单或他人上传的文件，攻击者可以在这些文本中隐藏指令，指示模型忽略你的提示并执行其他操作。

上述限制无论模型是在遵循你的提示还是攻击者的指令时都适用。在被注入的指令下运行的命令无法访问你在 network_policy 中配置的主机之外的任何主机，并且当你不启用策略时它完全没有网络访问权限。它无法访问其他租户的容器，并且会在同样的超时时间停止。允许列表会扩大被注入命令可访问的范围，而 allowed_domains: ["*"] 允许不受限制的出站流量，因此请将允许列表限制在任务所需的主机。

你还可以检测随请求本身到达的注入企图。 提示注入检测 作为一种 工作区防护机制 在将请求转发给模型之前，会针对常见注入技术的 regex 模式检查每个传入请求中用户提供的消息内容。它不会检查服务器工具在此之后获取的内容，因此模型通过工具读取的页面、文件或命令输出需要您自己的控制措施，例如审查您的应用程序接收到的沙箱输出。匹配成功后会根据您配置的操作执行以下三种操作之一。

• Flag 记录检测到的情况，并将请求原样转发。
• Redact 会用以下内容替换匹配的文本片段 [PROMPT_INJECTION] 并转发经过清理的请求。
• Block 在请求到达模型之前返回 403 并拒绝该请求。

当多个护栏同时适用时,以最严格的操作为准,顺序为 block(阻止)、redact(脱敏)、flag(标记)。检测并非详尽无遗,可能产生误报,因此在启用 redact 或 block 之前,请先在 flag 模式下针对您自己的流量测量匹配率。您可以在 Logs 页面报告误报。

托管沙盒在时间和金钱上会让你付出什么代价

托管沙盒会为请求增加数秒时间，而且不会留下任何可供运行的基础设施。它还为你提供一个可以随时返回的容器。

文件在请求之间得以保留

命令运行于 /workspace/home,并且我们在每次执行命令后将更改的文件保存在该目录下。发送一个稳定的 session_id，或者在工具的 环境 配置,并且每个带有该 id 的请求都会到达同一个容器和同一批文件。A session_id 只能使用字母、数字、 _，以及 -。包含任何其他字符的 id 会被忽略，我们会像你没有发送 session_id一样选择容器，这意味着如果回放的对话中有最近的 container_id 就使用它，否则为该请求创建一个新容器。当 session_id 的长度超过 20 个字符时，我们只使用最后 20 个字符，因此两个以相同方式结尾的长 id 会共享一个容器。而 container_reference id 可以由同一字符集组成 1 到 40 个字符且不会被截断，因此当你需要 id 完全精确时应使用它。我们在 2026 年 9 月 22 日确认了这一点：在一个请求中写入文件，然后在共享相同 session_id.

容器在空闲 5 分钟后会休眠，且空闲时间不可配置。休眠不会删除文件。当稍后收到带有相同 id 的请求时，会启动一个新的沙盒并首先加载保存的文件。运行中的进程、环境变量以及已安装的系统状态不会被恢复，因此请将唤醒后的容器视为一台保存着你文件的新机器。保存的文件在容器最后一次使用后保留 30 天。要取出制品， GET /api/v1/containers/{container_id}/files 列出某个容器产生了什么，以及 提升端点 将文件复制到你的工作区文档中，在那里它不会过期。

您之后可以查看的内容

响应中的每个 shell 工具结果都包含模型运行的命令以及每条命令的 stdout、stderr 和结果，因此您的应用程序可以像记录响应的其余部分一样记录它们。 输入与输出日志记录 会将你的提示词和补全结果存储在 OpenRouter 上，以便在 Logs 页面进行查看，护栏检测结果也会显示在那里。对于生产环境监控而言， 广播 将追踪流式传输到外部可观测性平台，随着请求的完成。

如果你路由 区域内，shell 工具不可用，并且即使已启用 Input & Output Logging，该日志记录也会被跳过。Broadcast 支持区域内路由，每个目的地都配置了其接收追踪的数据区域。

这一往返行程要花你多少钱

运行沙盒化命令的请求比不含沙盒命令的相同请求耗时更长。在我们于2026年9月22日发送的一组单次请求中,不含 shell 工具的请求约在 2 秒内返回,而进行一次 shell 调用的请求则根据模型不同在 8 到 21 秒内返回。这些只是来自一个会话的单个样本,并非基准测试。请为每次 shell 调用预留数秒的开销。

沙盒时间按每秒 0.0001 美元计费。计时从请求首次运行沙盒命令开始，到响应完成时停止。启动新容器或休眠容器的请求最低按 30 秒计费，而后续复用同一热容器的请求只需支付其实际计量时间。上面的请求启动了一个新容器，其使用对象报告了 server_tool_cost 为 0.003，即 30 秒的最低计费标准。请求之间处于空闲状态的容器不会被计费。

无需改动工具代码即可更换模型

更换模型后，你的工具定义保持不变。

我们于2026年9月22日发送了同一个请求体六次，仅更改了 model 字段，并要求每个模型在沙箱中运行 python3 -c "print(sum(range(1, 101)))" 。每个模型都进行了一次 shell 调用并返回 5050。

这六个模型都在同一个沙箱中使用相同的工具定义运行，无论它们各自的提供商原生提供什么，因为沙箱属于我们而不是模型的提供商。在基于某个模型构建之前，请先测试你打算使用的模型，因为不同模型之间的工具调用可靠性各不相同。我们的 工具调用指南 介绍服务器工具与你自己的函数工具如何共用同一个 tools 数组。

当你想要一个自己的沙箱平台时

当托管工具无法满足需求时，请选择专用的沙箱平台。 Modal 的文档介绍了基于自定义镜像构建的沙箱，其生命周期最长可配置为 24 小时，并支持 GPU 资源。 Daytona 的文档介绍了基于公共容器镜像创建的沙箱，包括 GPU 沙箱。 E2B 的文档介绍了其 Pro 计划下可运行最长 24 小时、基础计划下可运行 1 小时的沙箱，并支持通过暂停和恢复来处理更长的工作负载。

结论

对于模型请求内部的简短、有边界的命令，请使用托管工具。你只需向 tools 数组添加一个条目，即可获得一个默认关闭出站网络访问的隔离容器，并且只需为推理加上沙箱运行的秒数付费。为每次 shell 调用预留几秒钟的开销，并尽可能复用容器。

当任务需要自定义基础镜像、GPU、运行数小时的会话，或需要掌控安全边界本身时，请转为你自己运营的沙箱平台。无论哪种情况，在做出决定之前请查看提供商的最新文档，因为我们的两个工具尚处于 beta 阶段，其他三家提供商的工具也在不断变化。

常见问题

是否有模型可以在请求期间直接调用的托管沙箱 shell 工具？

有。我们的 openrouter:shell 服务器工具在 Responses API 和 Messages API 上都为模型提供一个在我们基础设施上运行、请求期间有效的沙箱化 Linux shell。将 engine 设置为 openrouter 后，命令将在隔离容器中运行，每个命令的 stdout、stderr 以及退出或超时结果都会返回给模型。OpenAI、Anthropic 和 Google 各自为其自家模型提供托管代码执行工具。

我可以为模型提供一个可运行命令的沙箱 shell 吗？

可以。在 Responses 或 Messages API 请求的 {"type": "openrouter:shell", "parameters": {"engine": "openrouter"}} 数组中添加 tools 。模型随后可以发出 shell 调用，我们在隔离容器中运行这些命令，并将每条命令的输出返回给模型。除非你配置了 network_policy 允许列表，否则容器没有出站网络访问。

哪些 SDK 或平台开箱即用地提供服务端代码执行？

我们的 openrouter:shell server 工具在 Responses 和 Messages API 上为任何模型运行命令，而我们的 openrouter:bash server 工具仅在 Messages API 上实现同样的功能。OpenAI、Anthropic 和 Google 各自通过 Responses API 的 shell 工具、代码执行工具和 Gemini API 代码执行工具为自己的模型运行代码。OpenAI Agents SDK 将 OpenAI 的托管工具封装为 CodeInterpreterTool 和 ShellTool。E2B、Modal 和 Daytona 是由你自己集成和运营的沙箱平台，而不是由提供商在 API 调用内部运行的工具。

哪种沙箱最适合 AI 智能体？

这取决于工作运行的时间长短以及你对运行时环境需要多大控制权。对于请求内的短命令，像 openrouter:shell 这样的托管工具意味着你无需运行任何基础设施。对于自定义基础镜像、GPU 访问或运行数小时的会话，由你自己运营的沙箱平台（如 Modal 或 Daytona）能提供这些控制能力。

如何对 AI 智能体进行沙箱隔离？

你在与自己的系统隔离的环境中运行智能体的命令，并限制该环境能访问的范围。使用托管工具时由提供商完成这一点。在 OpenRouter 上，容器与我们的基础设施以及你的机器相隔离，作用域限定在你的账户和工作区，出站网络访问默认关闭，每条命令受 timeout_ms限制，输出受 max_output_length限制。工作区防护措施在模型之前增加了提示词注入检测。

什么是沙箱化的 AI 工具？

它是一种其副作用被限制在隔离环境中而非你的生产系统中的工具。对于代码执行而言，模型的命令在一个拥有自己文件系统、受限网络访问和时间限制的容器中运行，只有命令输出会传回给模型。我们的 shell 和 bash server 工具就是这样工作的。

参考资料

• Server 工具参考
• Shell server 工具
• Bash server 工具
• 容器
• 防护措施 和 提示词注入检测
• Input & Output Logging
• 工具调用指南
• Responses API 工具调用
• 模型目录