Shell

在 Responses 和 Messages API 上为任意模型提供沙箱化的托管 Shell

openrouter:shell 服务端工具为模型提供托管 Shell——这是 OpenAI 托管 shell 工具的沙箱版实现，可与任意模型配合使用。当模型需要运行命令时，会发出 Shell 调用；OpenRouter 在隔离的 Linux 容器中于服务端执行这些命令，并返回每条命令的 stdout、stderr 以及退出或超时结果。

与 Bash 工具不同，Shell 工具没有客户端执行模式：命令始终在托管环境中运行，要么是 OpenAI 的原生 Shell，要么是 OpenRouter 的沙箱。

工作原理

1. 在 Responses 或 Messages API 请求的 tools 数组中加入 { "type": "openrouter:shell" }。在 Responses API 上，你也可以发送 OpenAI 的原生 shell 工具形态——在非 OpenAI 模型上，它会自动路由到 OpenRouter 沙箱。
2. 模型根据提示词决定运行一条或多条 Shell 命令，并发出 Shell 调用。
3. OpenRouter 按顺序执行这些命令，每条命令各自一次调用，均在沙箱容器内进行。
4. 每条命令的 stdout、stderr 和结果（退出码或超时）返回给模型。
5. 模型纳入这些结果，并可能在同一次请求中继续运行后续命令批次。

快速开始

const response = await fetch('https://openrouter.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-4.5',
    input: '列出当前目录中的文件，并告诉我操作系统版本。',
    tools: [
      { type: 'openrouter:shell', parameters: { engine: 'openrouter' } }
    ]
  }),
});

const data = await response.json();
console.log(data);

配置

Shell 工具接受可选的 parameters，用于选择执行引擎和环境：

{
  "type": "openrouter:shell",
  "parameters": {
    "engine": "openrouter",
    "environment": { "type": "container_auto" }
  }
}

默认值和上限反映当前服务端强制执行的限制，在该工具处于测试阶段时可能会变更。

调用参数

模型生成调用参数，与 OpenAI 托管 Shell 的 shell_call.action 一致：

OpenAI 原生 Shell 工具

在 Responses API 上，你也可以发送 OpenAI 的原生工具形态（{ "type": "shell" }，或旧版 Codex 的 local_shell），而不是 openrouter:shell。在 OpenAI 模型上，这会使用 OpenAI 自己的托管 Shell；在任何其他模型上，OpenRouter 会透明地将调用路由到其沙箱。无论哪种情况，响应都会发出原生 shell_call 输出项。

响应格式

该工具为每条命令返回一项，与 OpenAI 的 shell_call_output.output[] 一致：

{
  "output": [
    {
      "stdout": "total 0\ndrwxr-xr-x 2 root root 40 Jun  1 12:00 .\n",
      "stderr": "",
      "outcome": { "type": "exit", "exit_code": 0 }
    }
  ]
}

每条命令的 outcome 要么是 { "type": "exit", "exit_code": <int> }，要么是 { "type": "timeout" }。非零退出码表示命令失败；错误输出会返回在 stderr 上，以便模型读取并作出反应。

安全性

Shell 执行在设计上就是沙箱化的：

• 命令在隔离容器中执行——不在 OpenRouter 基础设施上，也不在你的机器上。使用 container_auto 时容器是临时的；使用 container_reference 时它会跨请求持久存在。
• 容器按账户和工作区隔离，因此永远不会跨租户共享。
• 执行时间受 timeout_ms 限制（会被钳制到服务端最大值）。
• stdout 和 stderr 各自截断到 max_output_length（按流封顶，其本身也会被钳制到服务端最大值）。

后续步骤

• 服务端工具概览 — 了解服务端工具
• Bash — 面向 Anthropic Messages API 的沙箱 Shell
• 工具调用 — 了解用户自定义工具调用