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

推出 openrouter:shell 服务器工具和 Files API：OpenRouter 上的任何模型现在都可以在托管的 Linux 容器中运行命令。Files API 支持上传文件供模型使用，并可下载输出结果。这两项功能今天起以 beta 版本提供。

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

在 聊天室 中开启 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 上看到问题，并在回答前修复脚本。

日志页面上的生成详情视图将请求显示为时间线。模型轮次和沙箱运行显示为单独的行，每行都有各自的持续时间和成本：

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"

Promoting（提升）会将容器文件复制到你的工作区，并返回一个新的 or_file_ id，你可以像上传文件一样，在后续运行中附加该 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 页面关闭其中任意工具，每个工具都有一个显示“可用”或“已阻止”的开关。该设置适用于工作区发出的每一个请求，无论是通过 API 密钥、聊天室还是预设配置发出的。

Shell、Bash、Files API 和容器目前处于测试阶段，现已可用。API 在测试期间可能会发生变化。如果有任何功能不符合你的预期，请在我们的 Discord 的 #feedback 频道告诉我们。

Shell 服务器工具

Bash 服务器工具

Files API

容器

所有服务器工具