OpenAI Hosted Sandboxes 网络访问怎么配置？2026 Agent 安全部署指南

OpenAI Agents SDK 当前文档已经把托管容器的网络策略区分为禁用等不同模式，不能把“能运行代码”误认为“默认可以访问互联网”。(OpenAI Agents SDK 工具文档)

症状： Agent 能读写文件，却在安装依赖、调用 API 或连接内部服务时失败。 最快解法： 默认按无网络任务设计；只为明确需要的公共 API 配置有限出口；一旦涉及私有 API、数据库或内部系统，优先使用自托管环境或受控网关，不要直接扩大沙箱权限。

这篇文章适合三类人：独立开发者，准备把代码执行型 Agent 从 Demo 变成可重复任务；AI 应用工程师，需要安装依赖、读写文件并调用业务 API；平台工程师，负责沙箱、密钥、网络出口和审计边界。

先判断：你的 Agent 到底需要哪一种网络？

OpenAI Hosted Sandboxes 的价值在于提供 Linux 工作区、文件处理、代码执行、依赖和产物管理能力，但“需要工作区”与“需要访问互联网”是两个不同决策。官方介绍强调，Hosted Sandbox 可以配置文件、包、技能和插件，并由平台负责提供执行环境；这并不等于所有任务都应开放任意网络。(OpenAI Agents API 官方介绍)

你可以先把任务归入下面四类：

• 本地文件计算： 例如 CSV 清洗、PDF 提取、图片转换、代码静态分析。保持禁网，输入文件通过工作区提供，输出写入明确的产物目录。
• 安装依赖： 例如安装 Python、Node.js 或系统库。不要让模型在每次运行时自由搜索并安装软件，应该在环境准备阶段固定依赖来源和版本。
• 访问公共 API： 例如调用天气、汇率、公开数据或你自己的公网接口。使用有限出口，并为域名、方法、请求体和超时设置约束。
• 访问私有服务： 例如企业内网、数据库、内部 Git、工单系统或支付后台。不要把 Hosted Sandbox 直接放进可信内网，优先评估自托管环境、专用执行节点或受控后端代理。

Hosted Sandbox 的默认联网边界是什么？ 更稳妥的工程答案是：不要把它当作默认开放互联网的环境。OpenAI 的相关执行环境文档明确提供禁用网络策略，官方技术材料也将隔离容器描述为网络默认受限的执行边界；具体 Hosted Sandbox 的网络字段、可用策略和当前限制，应以你正在使用的开发者文档和实际环境返回状态为准。(OpenAI Agents SDK 工具文档)

决策条件：三条路径怎么选？

• 若任务只处理已上传文件，且不需要下载依赖，选择保持禁网。 这是最容易审计、最不容易发生数据外传的路径。
• 若任务只需访问少量公共 API，选择有限出口。 先列出域名、端口、请求方式和超时，再用最小测试验证连接，而不是给 Agent 一个“可以联网”的笼统权限。
• 若任务需要私有 API、数据库、内网服务或长期运行，回退到自托管环境或受控网关。 OpenAI Agents API 允许你选择由平台管理的沙箱、自己的基础设施或其他执行环境，执行层与 Agent 编排层可以分离。(OpenAI Agents API 官方介绍)

提醒： “能执行 curl”只是命令存在，不代表目标域名可达，也不代表凭据、DNS、TLS 和出口策略已经配置完成。

第一步：把工作目录、依赖和网络当成一份环境合同

代码执行沙箱失败，很多时候不是网络问题，而是 Agent 根本没有拿到正确的工作区。Agents SDK 使用 Manifest 描述新会话的文件、目录、仓库、挂载和环境入口；工作目录决定输入文件在哪里，输出目录决定产物是否能被稳定取回，额外路径授权则决定是否能接触工作区之外的资源。(Sandbox Agent 指南)

建议按以下顺序准备环境：

1. 先定义目录结构。 例如将输入统一放在 /workspace/input，中间文件放在 /workspace/tmp，最终产物放在 /workspace/output。目录名称可以不同，但必须在 Agent 指令和测试脚本中保持一致。
2. 在启动阶段安装固定依赖。 Python 包使用锁定文件，Node.js 使用锁定版本的包管理文件，系统包则放进基础镜像或受控初始化脚本。
3. 把 setup command 与任务命令分开。 setup command 负责准备环境，任务命令只负责处理当前输入。不要让模型根据错误信息临时决定安装一个来源不明的软件包。
4. 先验证版本，再执行真实任务。 至少输出 Python、Node.js、关键库和系统工具的版本，确认它们来自预期路径。
5. 最后验证网络。 对每个允许访问的域名执行一次 DNS、TLS 和 HTTP 层测试，并记录状态码、响应时间和错误信息。

Python、Node.js 与系统依赖应如何准备？ 不要把“安装语言运行时”和“安装项目依赖”混为一谈。官方 Sandbox Agent 文档展示了通过 Manifest 提供文件、仓库和工作区内容的方式；本地或 Docker 环境还可以通过对应客户端选择镜像和隔离边界。对于 Hosted Sandbox，应优先使用官方支持的依赖配置入口或启动配置，确认依赖安装完成后再启动 Agent。(Sandbox Agents 官方文档)

一个最小验证脚本可以包含：

pwd
python --version
node --version
python -c "import requests; print(requests.__version__)"
test -d /workspace/input
test -d /workspace/output

如果第五步失败，说明工作区合同没有满足；如果 Python 包导入失败，说明依赖配置没有真正进入运行环境；如果版本正确但网络请求失败，再进入网络排查，不要一开始就扩大权限。

第二步：外部 API、数据库和 Webhook 应该怎么接入？

公共 API 与私有服务的风险完全不同。公共天气接口即使泄露请求内容，影响可能有限；企业数据库则可能包含客户资料、订单、内部代码和高权限操作。把两者都交给 Agent 直接访问，会让权限边界难以审计。

外部 API 接入应采用什么架构？ 推荐采用“沙箱—受控后端代理—业务服务”的结构：

• 沙箱只访问代理的固定域名或固定入口；
• 代理验证 Agent 任务身份、租户、资源范围和请求方法；
• 代理向真实业务 API 发出请求，并过滤响应中的敏感字段；
• 对写操作增加人工审批、幂等键和请求审计；
• 对数据库访问优先提供窄接口，而不是把数据库账号放进沙箱。

这种方式比直接把数据库连接串交给模型更容易回收权限，也更容易区分“配置错误”“业务服务故障”和“Agent 生成了错误请求”。

密钥隔离：不要让模型替你保管凭据

API Key 怎样避免进入沙箱和日志？ 至少遵守以下边界：

• ❌ 不把 API Key 写进提示词、上传文件、代码片段或 Git 仓库；
• ❌ 不让 Agent 把环境变量完整打印到日志；
• ❌ 不把长期高权限密钥直接注入代码执行沙箱；
• ✅ 通过后端代理持有长期凭据；
• ✅ 如果必须由运行环境访问服务，使用短期凭据、窄权限和明确过期时间；
• ✅ 对命令输出、异常堆栈和产物下载做敏感信息脱敏；
• ✅ 将“允许访问的服务”与“允许执行的操作”分开控制。

OpenAI Agents SDK 的设计也强调将 Agent harness 与实际计算环境分离，这有助于避免把凭据长期暴露在模型生成代码所在的执行空间中。(Agents SDK 演进说明)

如果你使用的是本地客户端，还要特别注意本地环境的边界：官方文档指出，Linux 上的 UnixLocalSandboxClient 以宿主进程方式运行，并不自动提供操作系统级隔离；macOS 的文件限制也不等同于网络隔离。处理不可信命令时，应选择适当的 Docker 或托管环境，而不是仅依赖工作目录限制。(Sandbox Agents 官方文档)

网络失败怎么排查，才能避免反复改配置？

网络访问失败时，按什么顺序定位？ 不要让 Agent 反复重试同一条命令。按下面顺序记录证据：

1. 环境创建失败： 检查环境类型、启动配置、Manifest、依赖声明和初始化命令是否被接受。
2. 连接被拒绝： 确认目标域名、端口、出口策略和代理设置；不要直接把失败解释为 API 服务宕机。
3. DNS 错误： 记录解析结果和失败域名，区分域名不存在、私有 DNS 不可见和临时解析故障。
4. TLS 错误： 检查证书链、系统时间、代理中间人证书和目标服务是否要求特定协议。
5. 依赖安装失败： 分开记录包源不可达、版本冲突、编译工具缺失和系统包权限不足。
6. 任务超时： 检查连接建立时间、下载时间、服务端处理时间和 Agent 自身的重复调用，不要只增加总超时。
7. 结果异常： 对照输入文件版本、环境状态、命令输出和 Agent 生成的请求，判断是配置错误、外部服务故障还是模型误判。

每次运行至少保存四类证据：环境状态、错误事件、命令输出、输入文件版本。OpenAI Agents SDK 提供 Trace viewer 用于查看 Agent 运行过程；使用它可以确认模型到底发起了什么工具调用，以及失败发生在模型决策、沙箱执行还是外部服务响应阶段。(Agents SDK 快速开始)

经验： 如果同一个请求在命令行中成功、在 Agent 中失败，先比较环境变量、工作目录、代理设置和超时，再考虑模型问题。不要用“重试成功”掩盖权限配置不稳定。

上线前的权限收缩与运行观测基线

上线前建议建立一份最小基线：

• 网络出口： 只允许任务需要的域名、端口和方法；
• 文件目录： 输入只读，输出单独目录，中间文件定期清理；
• 包版本： 使用锁定版本，禁止模型随意升级核心依赖；
• 密钥： 代理持有长期凭据，沙箱只获得短期、窄权限访问；
• 日志： 记录请求摘要和结果状态，过滤令牌、Cookie、数据库连接串；
• 产物下载： 只允许下载明确生成的文件，禁止把整个工作区打包导出；
• 宿主访问： 验证 Agent 无法读取工作区之外的无关文件、进程环境和宿主凭据。

如果你需要长期工作区、完整自定义网络、固定公网出口、内网路由或持续运行数小时以上的 Agent，Hosted Sandbox 未必是最佳长期方案。OpenAI 官方文档将托管提供商、Docker 和本地执行区分为不同客户端，说明执行环境本身就是可替换的架构层，而不是必须永久绑定的一种方式。(Sandbox 客户端官方文档)

不同任务应该选哪种部署路径？

• 数据清洗： 若文件已经准备好，不需要下载数据，选择禁网 Hosted Sandbox；若数据来自内部对象存储，通过受控挂载或后端下载接口提供。
• 代码构建： 若项目依赖公开包且构建时间短，可以使用有限出口；若需要私有仓库、内部制品库或自定义工具链，优先自托管。
• 网页抓取： 若只是访问少量公开页面，先确认合规、域名和请求速率，再配置有限出口；若需要浏览器状态、长期 Cookie 或复杂网络策略，应使用可控的云端工作区。
• 内部系统操作： 不建议让 Agent 直接进入企业内网，使用受控代理、审批和窄接口。
• 长任务 Agent： 需要持久工作区、状态恢复、固定网络和稳定日志时，优先自托管或云端工作区，而不是把所有能力堆进一次性沙箱。

你可以在部署前逐项确认：

• ✅ 是否能在无网络状态下完成大部分任务？
• ✅ 所有外部域名是否已经列出并经过测试？
• ✅ 依赖是否在启动阶段固定完成？
• ✅ 输入、输出和临时文件是否分目录？
• ✅ API Key 是否没有进入提示词、文件和原始日志？
• ✅ 私有服务是否通过代理而不是直接暴露？
• ✅ 失败时能否区分环境、网络、依赖和 Agent 决策？
• ✅ 是否验证过 Agent 不能读取宿主环境或无关路径？

如果你还没有确定执行环境，可以先查看 kvmboot 的帮助中心，把网络出口、远程连接和工作区持久化需求分开评估；需要了解长期云端工作区适用边界时，也可以参考 kvmboot 的服务说明。

对于临时文件处理、短流程代码执行和少量公共 API 调用，Hosted Sandbox 通常更适合快速验证；但当前方案一旦需要自定义内网路由、长期保存工作区、稳定公网出口或持续运行的 Agent，就会受到权限、状态持久化和网络控制粒度的限制。此时，租赁 kvmboot 的云端 Mac 作为可控工作区，往往比继续给一次性沙箱追加权限更容易管理，尤其适合需要远程开发、固定环境和人工介入的任务。

先对照本文的网络与凭据边界清单，再继续阅读 OpenAI Hosted Sandboxes 成本估算和生产验收相关主题；如果你的需求已经超出托管沙箱的权限模型，就应尽早迁移到可控的云端工作区，而不是等一次密钥泄露或长任务中断后再重构。