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

推出 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)

在聊天室中开启 shell 工具即可试用，并阅读 shell、containers 和 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 和 Messages API 上支持 OpenAI 兼容的 Shell 工具，并在 Messages API 上支持 openrouter:bash，即 Anthropic 兼容的 Bash 工具。两者均可与任何模型配合使用。
Files API：工作区位于 /api/v1/files 下。上传文件，通过 id 将其附加到容器，并保留运行产生的文件。
Containers：这是运行 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:shell`	`openrouter:bash`
兼容于	OpenAI 的 `shell` 工具	Anthropic 的 bash 工具
API	Responses、Messages	Messages
默认运行命令的位置	在 OpenRouter 沙箱中	在你的应用中

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

Containers

容器是 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 结果，则会复用该容器。要显式选择容器，请在工具的 environment 字段中传入 { "type": "container_reference", "container_id": "my-project" }。
生命周期：容器在空闲 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"

提升会将容器文件复制到您的工作区，并返回一个新的 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 成本加上沙箱时间，沙箱时间会在日志页面该请求的时间线中单独显示为一行。

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

为工作区禁用工具

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

开始使用

Shell、Bash、Files API 和容器均处于测试阶段，现已可用。测试期间 API 可能会发生变化。如果某些功能的表现与预期不符，请在 Discord 的 #feedback 中告诉我们。