跳到正文
北京时间
原文
OpenRouter：Announcements（RSS）· Brian Thomas·· 21 天前精选AI 评分73

OpenRouter 推出 shell 沙箱工具与 Files API，任何模型可在托管 Linux 容器中执行命令

Give any model a terminal and files

AI 导读

OpenRouter 发布 openrouter:shell 服务端工具和 Files API，OpenRouter 上任何支持工具调用的模型都可在托管 Linux 容器中运行命令，两者现已在 beta 阶段开放。

推荐理由

原文给出定价、容器网络策略和文件生命周期等落地细节，读者可以据此评估在自己的 Agent 工作流中怎么用这套沙箱。

正文 · AI 翻译

Give any model a terminal and files

隆重推出 openrouter:shell 服务器工具和 Files API：现在，OpenRouter 上的任何模型都可以在托管的 Linux 容器中运行命令。Files API 支持上传文件供模型处理，并下载输出结果。两者即日起均以 beta 版提供。

Shell 和 Files 加入了我们不断壮大的 服务器工具列表，让你能够创建可在不同模型之间自由切换的服务器端智能体行为。例如，你可以让任何模型搜索网页、编写一个将结果转化为图表的脚本，并完全通过服务器端算力来运行它。

Diagram of how the shell tool, containers, and the Files API work together. The model writes commands, the shell tool runs them in a container, and the Files API moves files into and out of that container (light mode)

Diagram of how the shell tool, containers, and the Files API work together. The model writes commands, the shell tool runs them in a container, and the Files API moves files into and out of that container (dark mode)

在 聊天室中开启 shell 工具即可试用，并阅读 shell、容器和 Files API指南了解 API 细节。沙箱时间费用为每秒 $0.0001，作为请求的一部分计费，并包含 Files API 的使用。详情见 定价部分。

shell 的工作原理

要使用 openrouter:shell，请将其放入任何支持工具调用的模型的 tools 数组中。这样模型就能自行决定何时需要终端以及何时调用它：

curl https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-pro-0813",
    "input": "Check the Python version, then write a script that prints the first 20 primes and run it.",
    "tools": [
      { "type": "openrouter:shell", "parameters": { "engine": "openrouter" } }
    ]
  }'

我们推出了三项协同工作的能力，共同提供服务器端命令执行和文件功能：

  • Shell 与 Bash：我们在 Responses API 和 Anthropic Messages API 上支持 OpenAI 兼容的 Shell 工具，同时也在 Messages API 上支持 openrouter:bash，即 Anthropic 兼容的 Bash 工具。两者均可配合任意模型使用。
  • Files API：位于 /api/v1/files 下的工作区存储。上传文件，通过 id 将其挂载到容器，并保留某次运行所产生的文件。
  • 容器：这是运行 shell 命令的沙箱。写入其中的文件会在共享同一容器 id 的请求之间持久保留。你可以通过 /api/v1/containers API 访问容器的内容。

当模型调用该工具时，它会发出一批命令。这些命令在容器内执行，每条命令各自独立调用，并将 stdout、stderr 和退出码返回给模型。这使模型能够对其收到的输出做出反应。例如，如果它编写了一个脚本来解析你的 CSV，而解析失败，它可以在 stderr 上看到问题，并在回答之前修复该脚本。

日志页面上的生成详情视图以时间线形式展示请求。模型轮次和沙箱运行显示为单独的行，各自带有自己的耗时和成本：

Server-tool generations timeline for a request with the shell tool, showing the model turn, the tool call, the shell tool run, and the follow-up model turn, each with its own duration and cost

Shell 与 bash

我们发布了两个不同的沙箱命令执行工具，以同时兼容 OpenAI 和 Anthropic 的规范。最显著的区别在于，bash 工具默认会要求你的应用在本地运行该命令。在 OpenRouter 上，你可以更改引擎来覆盖此行为，改为在服务器端执行。

openrouter:shellopenrouter:bash
兼容OpenAI 的 shell 工具Anthropic 的 bash 工具
APIResponses、MessagesMessages
默认运行命令在 OpenRouter 沙箱中在你的应用中

在任一工具上使用 engine: "openrouter"，即可保证在 OpenRouter 沙箱中通过任意模型进行服务器端执行。

容器

容器是 OpenRouter 基础设施上隔离的 Linux 环境，作用域限定在你的工作区。容器可以根据你的应用需求进行配置：

  • 网络：出站访问默认关闭。对于像 pip3 install 这样的任务，将 network_policy 设置为允许列表，例如 { "type": "allowlist", "allowed_domains": ["pypi.org", "files.pythonhosted.org"] }，或设置为 { "type": "allowlist", "allowed_domains": ["*"] } 以允许不受限制的出站流量。允许列表中的主机可通过 80 和 443 端口访问；对允许列表之外域名的请求会以 HTTP 520 失败，而不是连接错误。容器启动后该策略无法更改。
  • 文件：仅捕获主目录（/workspace/home）下的文件。每个 shell 结果还会返回命令创建或更改的文件 id 列表（以 cfile_ 为前缀）。容器文件端点列出容器中保存的所有内容，而 Files API用于移入和移出文件。
  • 跨请求复用：默认情况下，一次对话会获得一个全新的容器。如果某个请求包含一个session_id或带有可识别容器的先前 shell 结果，则会复用该容器。要显式选择一个容器，请传入{ "type": "container_reference", "container_id": "my-project" }该工具的environment字段。
  • 生命周期：容器在空闲 5 分钟后进入休眠。此设置不可配置。

文件与 shell 协同工作

Files API 是与容器并列的工作区存储。你把输入上传到那里供 shell 处理，再把 shell 的输出移回其中。

为 shell 上传文件

使用 POST /api/v1/files 上传输入。响应中会包含一个以 or_file_ 开头的文件 id：

curl https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

然后在工具的 environment 中通过 id 将其附加：

{
  "type": "openrouter:shell",
  "parameters": {
    "engine": "openrouter",
    "environment": {
      "type": "container_auto",
      "file_ids": ["or_file_011CNha8iCJcU1wXNR6q4V8w"]
    }
  }
}

附加的文件会以可写副本的形式出现在主目录中，每个容器最多 20 个。每个副本以文件 id 的最后 8 个字符加上原始文件名命名，因此用上面的 id 附加的 data/sales.csv 会变成 ~/NR6q4V8w-sales.csv。容器内的更改不会影响原始工作区文件。容器启动时只包含你附加到其中的文件。

下载 shell 生成的文件

每个 shell 结果都会列出该命令涉及的文件，并为每个文件提供一个 cfile_ id。使用 容器文件内容端点下载这些文件：

curl "https://openrouter.ai/api/v1/containers/$CONTAINER_ID/files/$FILE_ID/content" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -o output.txt

容器文件会保留 30 天。若要长期保留某个文件，请将其提升：

curl -X POST "https://openrouter.ai/api/v1/containers/$CONTAINER_ID/files/$FILE_ID/promote" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

提升（promote）会将容器文件复制到你的工作区，并返回一个新的 or_file_ id，你可以像上传文件一样将其附加到后续运行中。与上传不同，提升后的文件可以通过 Files API 下载。

Files API 详情

你可以在 工作区文件页面查看所有文件。你直接上传的文件无法下载，但从容器提升的文件可以。

组合使用多个服务器工具

Shell 是我们提供的众多 服务器工具之一，组合使用时功能强大。在这里，模型使用网络搜索查找素材，并用 shell 将其转换为文件：

curl https://openrouter.ai/api/v1/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-pro-0813",
    "input": "Look up the three biggest open-source AI releases this week, then write ~/out/releases.md with one paragraph each and a source link.",
    "tools": [
      { "type": "openrouter:web_search" },
      { "type": "openrouter:shell", "parameters": { "engine": "openrouter" } }
    ]
  }'

生成的结果 ~/out/releases.md 会出现在 shell 结果的文件列表中，你可以通过上面的容器文件内容端点下载它。

如果你不想给容器网络访问权限，这种组合也很重要。网络搜索在容器外部运行，因此模型可以获取网络内容并将其传入命令，而容器则保持默认网络策略，自身没有互联网访问权限。

在 聊天室中，开启 shell 和网络搜索开关后，同样的组合也能生效。运行所创建的文件会以可下载形式出现在对话中。

定价

Shell 和 Bash 的使用按沙箱时间计费。价格为 每个活跃秒 $0.0001，从请求首次运行沙箱命令的那一刻起，计量到最后一条沙箱命令。请求结束后容器闲置的时间不计费。

当请求启动冷容器时，我们按最低 30 秒计费，无论是新容器还是已进入闲置状态的容器。如果某个智能体连续向同一容器发起多个请求，只有第一个请求支付最低计费。

按请求计费让查找运行特定请求的成本变得很容易。一个请求的成本等于其 token 成本加上沙箱时间，沙箱时间会在 Logs 页面该请求的时间线上单独显示为一行。

Files API 的使用不单独收费，但总存储量限制为 10 GiB。

为工作区禁用工具

服务器工具默认启用。工作区管理员可以在工作区的 Server Tools 页面关闭其中任何一个，每个工具都有一个开关，显示 Available 或 Blocked。该设置适用于该工作区发起的每一个请求，无论是通过 API key、聊天室还是预设。

Shell、Bash、Files API 和容器均处于 beta 阶段，现已可用。API 在 beta 期间可能会发生变化。如果有哪里不符合你的预期，请在我们的 Discord 上的 #feedback 中告诉我们。

来源：OpenRouter：Announcements（RSS） · openrouter.ai

#Agent#MCP/工具调用#产品更新#部署/工程

相关事件