OpenRouter Shell 工具与 Files API 指南（Beta）

当模型需要读取文件、运行代码、排查错误并返回生成物时，OpenRouter 的 Shell 工作流会很有用。不过要先明确一点：openrouter:shell、容器和 Files API 目前都处于 Beta 阶段，因此更适合从边界清晰、风险可控的任务开始，不要一上来就把它接入生产环境的关键执行链路。

先说结论：什么情况下值得用 OpenRouter Shell

OpenRouter 的 openrouter:shell 可以为支持工具调用的模型提供一个托管式 Linux 环境。模型能够执行命令，接收 stdout、stderr 和退出码，再根据结果修正自己的操作。Files API 则负责输入文件与输出文件之间的交接。

以下场景比较适合使用：

• 希望 Agent 与模型解耦，并在应用服务器之外运行代码。
• 需要反复执行文件处理任务，例如分析 CSV、提取 PDF 内容或生成报告。
• 想先使用服务端工具执行能力，而不是立即自建沙箱。

但不要把它当成可以直接替代本地 Shell 的方案。网络默认关闭，容器也不会自动持久化，而且 Beta 期间 API 仍可能发生变化。

实际接入时，真正重要的是这三层

openrouter:bash 是兼容 Anthropic 的另一种选择。它默认要求应用在本地执行命令；如果需要远程执行，应设置 engine: "openrouter"，具体说明见 Shell 公告。

一个文件如何走完整条链路

1. 上传文件并作为输入附加

通过 POST /api/v1/files 以 multipart form data 格式上传文件。上传参考显示，单个文件大小上限为 100 MB，此外还可以选填 workspace_id 查询参数。

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

响应会返回文件 ID、文件名、MIME 类型、字节大小、创建时间以及 downloadable 标记等元数据。拿到文件 ID 后，将它填入 Shell 环境的 file_ids 数组。

附加的文件会以可写副本的形式复制到容器中。根据 Shell 公告，一个容器最多可以接收 20 个附加文件。修改副本不会影响工作区中的原始文件。

有开发者在提到此前处理 PDF/OCR 时遇到的麻烦后，专门表示希望支持 Files API。虽然这只是一个很小的信号，但也说明文件处理确实曾是集成过程中的具体痛点（帖子）。

2. 执行、检查，再根据结果迭代

模型会向容器发送一批命令。每次调用都会返回命令输出和退出状态，这样模型就能根据失败结果修复脚本，而不是只凭最初的提示词猜测问题所在（Shell 公告）。

默认网络策略是全部拒绝。如果任务需要下载软件包或访问外部服务，应在创建容器时配置允许列表。OpenRouter 文档说明，允许列表中的主机可使用端口 80 和 443；容器启动后不能再修改这一策略。访问允许列表之外的域名可能会返回 HTTP 520（Shell 公告）。

Shell 结果只会捕获 /workspace/home 下的文件。如果希望 API 报告某个生成物，就把它写到这个目录中。由 Shell 创建或修改的文件会获得 cfile_ 标识符（Shell 公告）。

3. 下载输出，或将其提升为持久文件

Shell 生成的文件可以通过容器文件内容接口获取：

GET /api/v1/containers/{container_id}/files/{file_id}/content

cfile_ 标识符属于对应容器。如果生成物需要在容器生命周期结束后继续存在，就应将它提升到工作区存储中。提升操作会创建一个新的 or_file_ 标识符，之后可以将其附加到新的运行任务中（Shell 公告）。

容器文件会保留 30 天。任何需要保存更久的文件，都应该执行提升操作（Shell 公告）。通用文件下载接口返回原始字节，并明确说明用户上传的文件会返回 HTTP 400。因此，直接上传的文件应被视为输入，而不是可以随意读写的通用对象存储文件。

会改变方案设计的成本与限制

OpenRouter 的 Shell 公告称，沙箱活跃时间的费用为每秒 $0.0001。冷启动容器的最低计费时长为 30 秒，因此按此计算，单次沙箱的最低费用是 $0.003。Token 费用另行计算。

对于同一任务的多个步骤，尽量复用温容器；同时减少不必要的模型—工具往返，并将 Token 费用和沙箱费用分开记录。公告还提到，Logs 视图会在时间线中分别显示模型活动和沙箱执行记录。

核心请求结构

Beta 阶段的具体环境 Schema 可能发生变化，但当前文档描述的流程大体如此：先上传文件，再把返回的文件 ID 传给启用 Shell 的请求。建议把请求适配层做薄，以便 Beta Schema 变化时快速调整。

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

将这种结构发送到 公告中说明的 Responses 接口。正式用于生产前，应根据在线的 server-tools 文档，重新核对当前请求 Schema 和响应字段。

第一次接入时，可以按下面的顺序操作：

1. 上传一个较小的输入文件，并记录返回的文件 ID。
2. 为支持工具调用的模型创建请求，在 tools 中加入 openrouter:shell。
3. 通过 file_ids 显式附加文件。
4. 要求模型将输出写入 /workspace/home 下。
5. 检查退出码和文件列表，确认任务确实成功。
6. 下载容器生成物；如果后续还要复用，就将其提升保存。
7. 将 Token 用量和沙箱时长分别记录为独立的成本字段。

如果是多请求工作流，请传入 session_id 或明确的容器引用。否则，后续请求可能拿到一个全新的容器，之前的状态也不会保留。

最容易出问题的地方，以及对应的规避方式

OpenRouter Shell 与 Files API 常见问题

OpenRouter Shell 是在我的电脑上执行命令吗？

不是。openrouter:shell 的设计目标是在 OpenRouter 托管的沙箱中执行命令。兼容 Anthropic 的 openrouter:bash 默认行为不同；如果要远程执行，请使用 engine: "openrouter"（Shell 公告）。

如何在多个请求之间保留文件？

复用会话或容器引用。如果没有明确指定复用路径，后续请求可能会从一个全新的容器开始。

or_file_ 和 cfile_ 有什么区别？

or_file_ 标识的是工作区中的 Files API 对象；cfile_ 标识的是在容器内创建或修改的文件。执行提升后，容器生成物会转换为一个新的工作区文件 ID。

Files API 会单独收取使用费吗？

Shell 公告称，Files API 使用本身不收取单独的使用费用，但工作区存储上限为 10 GiB。沙箱运行时间和模型 Token 用量仍会按照各自适用的费率计费。

Shell 工具已经可以用于生产环境了吗？

目前文档将它标记为 Beta，公告也提醒 API 可能发生变化。在把它接入无人值守的生产工作流前，应设置明确的限制，控制命令范围，加入应用层约束，并准备好备用执行路径。

当工作流确实需要生成文件时，再考虑它

OpenRouter Shell 和 Files API 适合用于分阶段处理流程，例如生成清洗后的 CSV、报告、转换后的图片或编译产物。实际使用时，应明确指定文件 ID，预先声明网络策略，复用容器，并通过提升操作保存需要长期保留的输出。

如果任务只是返回一段文字答案，引入额外的沙箱成本和生命周期管理就没有必要了。如果任务需要本地凭据、无限制的网络访问，或必须满足严格的生产级保证，那么在 Beta 足够成熟、能够承受这些风险之前，仍应把执行放在自己控制的基础设施中。

来源：OpenRouter Shell 与 Files API 公告、Files API 上传参考、文件内容下载参考。