OpenRouter 推出有状态 server tool「Shell」：任意模型都能在托管 Linux 容器里跑命令

模型聚合平台 OpenRouter 于北京时间 9 月 10 日晚 10 时 58 分在官方 X 账号宣布，新的有状态 server tool「Shell」当日以 beta（测试版）形式上线：OpenRouter 上的任意模型都可以在官方托管的 Linux 容器中执行 shell 命令，并配合新推出的 Files API 把文件传入、传出容器。按官方推文的说法，开发者只需在请求的 tools 数组中加入一行配置，由模型自行决定何时需要终端（OpenRouter 官方推文）。

这条推文同时给出了定价口径：按请求内计费，每活跃秒 0.0001 美元且已包含文件使用费用，冷启动的容器按 30 秒最低计费。功能细节目前均来自 OpenRouter 单方公告与官方文档，尚未见独立验证。

在 tools 数组中加一行，模型自己决定何时开终端

官方给出的接入方式是一个 JSON 对象：{ "type": "openrouter:shell", "parameters": { "engine": "openrouter" } }。把它放进请求的 tools 数组后，模型会根据提示词自行判断是否需要运行命令，需要时发出 shell 调用（官方推文）。OpenRouter 随后在同一帖子串中贴出这段配置并附上文档链接（规格说明推文）。

官方文档描述了完整的执行回路：模型发出调用后，OpenRouter 在隔离的沙箱（sandbox）容器中按顺序执行命令，把每条命令的 stdout、stderr 以及退出码或超时结果返回给模型，模型消化结果后可以在同一请求内继续发起下一批命令（Shell Server Tool 文档）。调用参数沿用 OpenAI hosted shell 的形状，包括 commands（命令列表）、timeout_ms（单条命令超时）和 max_output_length（stdout/stderr 每流的字符上限）。

容器本身可以配置复用。文档中的 environment 参数提供两种选择：默认的 container_auto 是 OpenRouter 托管的一次性临时容器；container_reference 则通过 container_id 在多个请求之间复用同一个容器。sleep_after_seconds 参数控制容器在最后一条命令之后保持热状态的时长，默认 900 秒，每执行一条命令都会重新计时，上限 14,400 秒（4 小时）。

同时兼容 OpenAI shell tool 与 Anthropic bash tool 两套规格

这次发布在协议层面的卖点是「两种规格都支持」。官方推文称，Shell 同时支持 OpenAI 原生 shell tool 与 Anthropic bash tool 两种 spec（官方推文）。

文档给出了更具体的分工：在 Responses API 上，开发者可以直接发送 OpenAI 的原生工具形状 { "type": "shell" } 或旧版 Codex 的 local_shell；遇到 OpenAI 模型时走 OpenAI 自己的托管 shell，遇到其他模型时 OpenRouter 会把调用透明地路由到自己的沙箱，两种情况下响应都返回原生的 shell_call 输出项。engine 参数的默认值 auto 也是同样的逻辑——有原生 hosted shell 就用原生的，没有就落到 OpenRouter 沙箱；显式指定 engine: "openrouter" 则强制走 OpenRouter 沙箱。

不过兼容并非完全对等。文档明确写道，shell tool 没有客户端执行模式，命令只能在托管环境中运行，这一点与 Anthropic 的 Bash tool 不同（后者支持在客户端本地执行）。另外，由于 Anthropic 没有定义原生的 shell 结果块，Messages API 上命令输出由 OpenRouter 自行命名的 openrouter_shell_tool_result 内容块承载。

beta 期的边界：只在全局端点可用，Chat Completions 请求直接报错

作为 beta 功能，Shell 的适用面有几条硬性限制，均出自官方文档：API 和行为可能变化；工具只在全局端点 openrouter.ai 上可用，经由区域端点 eu.openrouter.ai 或 us.openrouter.ai 发起的请求会被直接拒绝；接口上只支持 Responses API 和 Messages API，在 Chat Completions API 上请求这个工具会返回 400 错误（文档）。

对不写代码的用户，官方留了一条试用路径：在 chatroom 中打开 shell tool 即可体验，不必自己拼请求（官方推文）。文档中的快速上手示例用的是 anthropic/claude-sonnet-4.5，也侧面说明这个工具并非绑定某一家模型。

Files API 补上文件进出：上传任意类型，让模型写脚本处理

Shell 之外，OpenRouter 同步推出了 Files API。官方推文对其定位的表述是：模型不再受限于自己原生能读写的内容——上传任意文件类型，模型就写一个脚本来处理它；要求任意文件类型的产出，模型就写一个脚本把它生成出来（官方推文）。

Files API 的费用被并入同一套计费。官方称，定价「通过把计算机的计费完全纳入请求内来保持追踪简单」，文件使用已包含在每活跃秒的单价之内，开发者不需要为容器和文件分别维护两套账单。

默认断网的沙箱，以及用户追问的容器复用问题

安全设计上，文档写明容器默认没有出站互联网访问：需要联网时可通过 network_policy 配置域名白名单，最多 50 条主机名或 glob（通配符匹配）模式，仅开放 80 和 443 端口，且白名单策略在容器启动时固定，向已运行的温容器发送不同策略会得到 409 错误。文档还提示了一个容易踩的坑：pip install 需要同时把 pypi.org 和 files.pythonhosted.org 加入白名单。容器按账号和工作区隔离，不会跨租户共享（文档）。

公告发出后，有开发者当即追问状态性的含义：容器是否跨请求复用，还是 Files API 就是全部的「有状态」？用户 @sirHe12 在回复中写道，如果冷启动是按请求发生的，30 秒最低计费「对交互式循环来说很残酷」（该回复）。文档给出的对应选项是：container_auto 为一次性容器，跨请求复用需显式改用 container_reference，默认路径下冷启动费用可能随请求反复产生。也有开发者给出正面评价，@coderchrisdean 称「hosted shell 加 Files API 是让 agent 循环真正触到机器的缺失一环」（该回复）。

文档同时注明，上述默认值与上限反映的是当前服务端强制执行的限额，在 beta 期间可能变动。

参考链接

• OpenRouter 官方推文（2026-09-10）
• OpenRouter 官方推文（规格说明，同日）
• Shell Server Tool 官方文档
• @sirHe12 的回复
• @coderchrisdean 的回复