OpenAI Agents SDK 沙箱能力发布后开发者该如何划分执行权限

OpenAI Agents SDK 最近把沙箱执行、文件工具、工作区生命周期和快照能力放进了更完整的运行框架。真正需要迁移的不是某个 API 名称，而是权限设计：模型能不能调用工具、工具以谁的身份执行、文件本身能不能被写入、宿主机目录是否被授权，以及运行结束后哪些内容可以恢复，应该分开回答。

最稳妥的做法是默认只给一个专用工作区和低权限执行身份；只有经过代码审核的配置，才增加只读的宿主机路径授权。快照只负责恢复工作区状态，不能替代审批、凭据管理或路径隔离。

先把四种权限放到不同层

官方文档将沙箱定位为 Agent 的受控执行环境，并特别区分了几个容易混淆的概念。外层应用仍应掌握审批、追踪、密钥和业务系统访问；沙箱负责命令、文件变化和环境隔离。清单里的 Permissions 只描述被物化文件的 owner、group、other 权限，不能替代模型是否需要人工批准。

因此，读写内部代码仓库时，至少要记录四个决定：工作区根目录是什么；文件由谁拥有；模型工具以哪个用户运行；是否存在工作区外的绝对路径授权。任何一项写成“全部可用”，后面都很难审计。

OpenAI Agents SDK 沙箱能力上线后，开发者可以按照任务可信度、资源访问边界、操作敏感等级三个维度逐层收拢权限，既避免给Agent开放过高权限带来的安全泄露风险，也不会因为限制过严让新特性的代码运行优势完全无法落地。

用 Manifest 和 run_as 收窄工作区内的写入范围

例如，应用可以把待分析资料复制到沙箱工作区，并建立一个只允许专用用户读写的条目。下面的片段展示的是权限分层思路，实际项目还要根据所用 sandbox client 补充客户端和 Runner 配置：

from agents.sandbox import FileMode, Manifest, Permissions, User
from agents.sandbox.entries import File

# 只把本次任务需要的资料放进工作区，避免把宿主机目录直接暴露给模型
manifest = Manifest(
    root="/workspace",
    users=(User(name="agent-worker"),),
    entries=(
        File(
            path="/workspace/input.txt",
            content=b"approved input",
            permissions=Permissions(
                owner=FileMode.READ | FileMode.WRITE,
                group=FileMode.NONE,
                other=FileMode.NONE,
            ),
        ),
    ),
)

# 让沙箱原生工具以专用身份执行，而不是沿用宿主进程身份
sandbox_agent = SandboxAgent(manifest=manifest, run_as="agent-worker")

关键点是“资料复制”和“路径挂载”不是一回事：复制适合少量、可审查的输入；挂载适合必须保留原路径语义的场景，但授权面更大。不要因为文件条目设置了只读，就误以为外层审批已经完成。

只为明确需求增加主机路径授权

当 Agent 必须读取工作区外的工具链或临时目录时，再考虑 SandboxPathGrant。路径应由可信代码写死或经过人工配置审核，不能直接从模型输出中读取。对只需读取的目录使用 read_only=True，并把授权原因写进部署配置。

from agents.sandbox import Manifest, SandboxPathGrant

# /opt/toolchain 仅作为只读运行时依赖；它不会随工作区快照保存
manifest = Manifest(
    extra_path_grants=(
        SandboxPathGrant(path="/opt/toolchain", read_only=True),
        SandboxPathGrant(path="/tmp/agent-output"),  # 临时产物目录，按任务清理
    ),
)

发布前可以用一张小表复核边界：

快照保存的是工作区，不是无限权限

snapshot 用于新沙箱会话的工作区恢复与持久化；如果要连接一个已经序列化的后端会话，使用的是 session_state。两者都不应被理解为“把上一次的所有授权永久带回来”。官方说明指出，额外授权是运行时访问，挂载和临时路径也不作为工作区内容写入快照。

这会影响恢复策略：工作区里的中间文件可以进入下一次任务，但密钥不应靠快照传递；每次新运行都应重新注入短期凭据，并重新计算路径授权。若应用使用开发者自持有的 session，还要明确由应用负责关闭、检查和清理会话。

采用前的迁移清单要落到代码审查

先在本地用最小工作区验证：Agent 能读输入、只能写输出目录，访问未授权绝对路径会失败；然后重启一个 fresh session，确认快照只恢复预期文件。最后检查日志中是否记录了执行用户、授权路径、快照标识和人工审批结果。

• 是否把模型工具审批与沙箱文件权限分成两套策略？
• 是否使用专用 run_as 用户，而不是继承宿主机高权限账号？
• 每个 extra_path_grants 是否有具体路径、只读选择和业务理由？
• 是否明确哪些输入能进 snapshot，哪些密钥只能运行时注入？

Agents SDK 的沙箱能力适合把执行环境标准化，但 Beta 能力仍可能变化。迁移时应锁定依赖版本，保留一组权限回归测试，并在升级后重新核对 Manifest、client 和 snapshot 的行为。更多边界以 Agents SDK 沙箱概念文档、Sandbox Agents 快速入门 和 OpenAI 官方能力说明为准。

常见问题

Permissions 能阻止模型调用危险命令吗？

不能。它描述清单文件的读写执行位；命令审批、工具暴露和业务授权仍应由外层应用与运行策略处理。

extra_path_grants 会随 snapshot 一起保存吗？

不会。它是运行时访问授权，快照只覆盖工作区根目录中的持久化内容。

什么时候使用 session_state 而不是 snapshot？

需要连接已经序列化的具体沙箱会话时使用 session_state；需要用保存的工作区内容创建新会话时使用 snapshot。