OpenAI Shell 工具怎么用？

先选托管容器还是本地运行

托管 Shell 最小请求

官方当前示例使用 gpt-6-astra；模型可用性会变化，上线前应再次核对模型页。不要把示例模型写死成长期保证。

import OpenAI from "openai";

const client = new OpenAI();
const response = await client.responses.create({
  model: "gpt-6-astra",
  tools: [{
    type: "shell",
    environment: { type: "container_auto" }
  }],
  input: "列出 /mnt/data，并显示 Python 与 Node 版本。",
  tool_choice: "auto"
});

console.log(response.output_text);

托管运行时当前基于 Debian 12，默认工作目录是 /mnt/data；可下载产物也应写到这里。它没有交互式 TTY，命令不能使用 sudo，但工作流需要时可以在容器内启动服务。运行时和预装语言版本都可能调整，任务应先探测版本而不是假设。

需要复用环境时使用 container_reference

1. 通过 Containers API 创建容器，并按业务记录 container_id。
2. 上传输入文件或挂载需要的 Skills。
3. 在 Responses 请求中把环境设为 container_reference。
4. 在容器有效期内下载 /mnt/data 产物，完成后主动清理。

const response = await client.responses.create({
  model: "gpt-6-astra",
  tools: [{
    type: "shell",
    environment: {
      type: "container_reference",
      container_id: container.id
    }
  }],
  input: "检查已有文件并生成 /mnt/data/report.md"
});

官方示例可把过期时间锚定到最后活跃时间并设置 20 分钟，但这不是永久存储承诺。容器过期或被显式删除后，临时文件会删除；业务数据应有自己的持久化与恢复方案。

文件、Skills 和产物怎么处理

• 把输入文件通过容器或 Responses 支持的文件入口提供，不要把二进制内容塞进命令参数。
• 要求模型把最终产物写入 /mnt/data，并校验文件名、大小、类型和内容后再给用户下载。
• 可在创建容器时附加版本化 Skill；同一活动容器内挂载内容可复用。
• 不要让不可信文档或 Skill 获得超出任务所需的文件、网络或密钥权限。
• 大输出应保存为文件或摘要；本地回传可用 max_output_length 控制上下文体积。

联网默认关闭，白名单要双重收紧

托管容器默认没有出站网络。要联网，管理员需先在组织中配置允许域名，请求还要显式传入 network_policy；请求级配置只能缩小组织白名单。只允许任务确实需要、且攻击者不能用来接收外泄数据的域名。

environment: {
  type: "container_auto",
  network_policy: {
    type: "allowlist",
    allowed_domains: ["pypi.org", "files.pythonhosted.org"]
  }
}

需要给特定目标注入凭据时，可使用 domain_secrets 把值绑定到批准的域名与变量名。模型和运行时看到的是占位符，网络侧车仅对批准目标注入原值；这仍不等于可以信任远端内容，必须防范提示注入和数据外泄。

本地 Shell 的完整调用循环

本地模式用统一的 shell 工具和 environment: {type:"local"}。模型返回 shell_call 后，应用验证命令、在隔离运行时执行，捕获 stdout、stderr 与退出或超时结果，再用同一 call_id 返回 shell_call_output。不要把命令直接交给宿主机默认 Shell。

const first = await client.responses.create({
  model: "gpt-6-astra",
  instructions: "本地环境为 Linux；只允许读取工作目录。",
  tools: [{ type: "shell", environment: { type: "local" } }],
  input: "找出工作目录中最大的 PDF。"
});

// 应用校验并执行 first.output 中的 shell_call
const next = await client.responses.create({
  model: "gpt-6-astra",
  previous_response_id: first.id,
  input: [{
    type: "shell_call_output",
    call_id: shellCall.call_id,
    max_output_length: 4096,
    output: [{
      stdout: result.stdout,
      stderr: result.stderr,
      outcome: { type: "exit", exit_code: result.exitCode }
    }]
  }]
});

超时应返回 outcome: {type:"timeout"}；非零退出码也要如实回传，不能把失败包装成成功。旧文档中的 local_shell 属于旧迁移路径，新实现应优先使用当前统一的 shell 工具。

安全基线：模型建议命令，应用决定能否执行

• 每次执行使用独立沙箱、非特权用户和最小挂载，默认只读。
• 限制可执行文件、参数、工作目录、环境变量、网络域名、CPU、内存、进程数、输出和时长。
• 禁止访问宿主 Docker Socket、云元数据、SSH Key、生产凭据和用户未授权路径。
• 对删除、安装、外发、写入生产或产生费用的命令保留审批。
• 记录请求、模型、shell_call、策略判定、stdout/stderr 摘要、outcome 与产物哈希。
• 把网页、仓库、文档和命令输出都视为不可信数据，防止其诱导扩大权限。

常见错误与排查顺序

1. 工具不触发：确认使用 Responses API、模型当前支持 Shell，工具类型和 environment 正确。
2. 命令需要交互：托管环境没有 TTY，改为非交互参数并设置超时。
3. sudo 失败：托管命令不是 sudo；选择无需提权的路径或改用自控沙箱。
4. 无法联网：核对组织白名单与请求 network_policy，两层都必须允许。
5. 文件找不到：核对容器 ID、有效期、上传状态和 /mnt/data 路径。
6. 本地循环卡住：检查是否保存原始 call_id，并返回正确的 shell_call_output 与 outcome。
7. 输出太大：限制输出长度，把完整结果写入文件并只回传摘要。

上线前检查清单

• 托管与本地模式分别有明确的权限、文件和网络边界。
• 命令允许/拒绝策略、审批、超时、资源限制和取消均已测试。
• 容器过期、重复请求、部分失败、非零退出和超时可以恢复。
• 产物仅从 /mnt/data 或受控本地目录导出，并经过校验。
• 凭据不进入提示、日志、stdout、产物或模型可见上下文。
• 对比 Shell、Code Interpreter 和普通 Function Calling 的成功率、延迟、Token 与单位成功成本。

常见问题

本文核对日期为 2026-11-01。Shell 的模型支持、托管运行时、预装语言、容器生命周期、网络与安全能力可能变化；生产上线前请重新读取 Shell、Containers、Skills、Files 与 Deployment checklist 官方页面。