OpenAI Agents API 怎样把工具权限限制在沙箱

想让 OpenAI Agents API 的工具只在沙箱里做事，关键不是在提示词中写一句“请安全执行”，而是同时收紧三层边界：Agent 能调用哪些工具、工具在哪个执行环境中运行、这个环境能看到哪些文件和网络。官方把 Agent、Environment、Session 分开描述；因此 workspace_directory 只是工作区配置，不等于自动获得完整的主机隔离。

官方地址：https://developers.openai.com/api/docs/guides/agents-api/overview

最小权限的做法是：先选受控的 sandbox 环境，再只挂载任务需要的目录，最后把工具清单和网络出口收窄。第三方密钥留在应用或受控代理中，不要直接暴露给沙箱代码。

一、环境边界要先于工具清单

Agents API 的 Agent 由模型、instructions、tools 和 MCP servers 组成；Environment 则是可选的 sandbox 或 computer，负责文件、技能和命令的执行位置。做权限设计时，先画出这两个边界，再决定工具清单，排查时会清楚很多。

如果使用自托管环境，可以把工作目录和能力目录写进会话配置：

from openai import OpenAI

client = OpenAI()

# 让会话只把约定的工作区和技能目录交给执行环境。
session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "只在工作区内处理任务，不访问未声明的资源。",
        "tools": [{"type": "programmatic_tool_calling"}],
    },
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/capabilities/skills"],
    },
    input=[{
        "role": "user",
        "content": [{"type": "input_text", "text": "整理 workspace 中的报告"}],
    }],
)
print(session.id)

这里的 tools 是模型可见的工具面，environment 是执行面，二者不能互相替代。若任务只需要回答问题，不需要文件、命令或持久工作区，直接使用 Responses API 或不带 sandbox 的基础 Agent runtime 更简单；真正需要操作文件时再引入 sandbox。

二、只暴露完成任务所需的工具

“放进沙箱”并不会自动降低工具权限。如果 Agent 同时拥有任意 shell、写文件、外部 MCP 和高权限函数，代码仍可能触达不该触达的资源。更稳的做法是按任务拆分工具：只读任务不提供写入工具，不需要联网就不配置网络型工具，不需要命令执行就不要加入 shell 能力。

敏感数据适合通过应用侧函数工具访问。模型只传递业务参数，函数在可信应用进程里读取凭据并返回最小结果：

from agents import Agent, function_tool

@function_tool
def get_report_status(report_id: str) -> str:
    """返回报告状态，不把第三方令牌交给模型。"""
    # 令牌只由应用侧的连接器读取，参数先经过业务层校验。
    record = app_report_client.fetch_status(report_id)
    # 只返回完成任务所需字段，避免把原始响应和凭据带出可信边界。
    return record.status

agent = Agent(
    name="Report reader",
    instructions="只查询报告状态，不修改报告和工作区文件。",
    tools=[get_report_status],
)

这个例子的权限重点不在函数名，而在返回值和连接器边界：函数内部可以使用密钥，但工具结果只给出状态。工具说明、参数校验和返回字段都应按最小化设计，避免用一个“万能 API”掩盖多个高权限动作。

三、本地执行不能只依赖工作目录

自托管环境适合把编排放在自己的服务中，但 /workspace 这个路径本身不是操作系统级隔离。官方 SDK 文档明确提示：Unix-local 在 Linux 上不提供 OS 级 confinement；在 macOS 上有文件限制，但没有网络隔离。遇到不可信输入或会执行模型生成命令的任务，应选择 Docker、虚拟机或托管 sandbox，并把挂载范围缩到任务所需目录。

from docker import from_env as docker_from_env
from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.sandbox.sandboxes.docker import DockerSandboxClient

# Docker 负责提供外部执行边界，应用仍要限制挂载目录和网络策略。
docker_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=DockerSandboxClient(docker_from_env()),
    ),
    workflow_name="restricted-report-agent",
)

# 运行时只把已选定的 Agent 和任务交给该 sandbox；不要把主机密钥目录挂载进去。
result = await Runner.run(agent, "读取工作区报告并生成摘要", run_config=docker_config)
print(result.final_output)

容器不是万能的安全结论，仍需配合只读或精确的工作区挂载、非特权用户、必要的包来源和出站网络白名单。网络边界要按“允许访问什么”配置，而不是只在提示词里要求模型不要联网。

四、把凭据放在沙箱外的受控出口

官方安全建议把应用 API key 留在环境之外；OpenAI 托管 sandbox 可以通过 vault secret 作为环境变量，并由代理为批准的目标注入真实密钥。自托管场景则需要由自己的可信代理或服务端函数完成同样的工作。要特别注意：把密钥注入沙箱环境，仍意味着生成的代码有机会读取它，所以只注入短时、窄权限、可撤销的凭据。

因此可以用一个简单的上线前判断收尾：任务是否真的需要 sandbox？若需要，工具是否最小？工作区是否只读或精确挂载？网络是否默认拒绝后按需放行？凭据是否由可信应用持有并可轮换？任一项答不上来，就不要把“已限制在沙箱”写成安全结论。

相关问题

只设置 workspace_directory 能防止 Agent 读取主机其他文件吗？

不能把它当成完整的 OS 隔离。它描述了工作区位置，实际防护还取决于 sandbox provider、挂载方式、运行用户和宿主机策略。

什么时候 function tool 比直接给 shell 更合适？

当任务只需要一个受控业务动作时更合适，例如查询状态、读取脱敏数据或提交工单。函数可以在应用侧保管密钥，并把返回字段限制在最小范围。