沙箱 vs 工具策略 vs 提权

Gateway 提供三种互补的安全机制来控制 Agent 的行为。本文档帮助你理解它们的区别，并选择合适的配置。

三种机制概览

┌──────────────────────────────────────────────────────┐
│                    用户请求                            │
│                      │                               │
│                      ▼                               │
│             ┌────────────────┐                       │
│             │   工具策略检查   │ ← "可以用这个工具吗？"│
│             │  (Tool Policy) │                       │
│             └───────┬────────┘                       │
│                     │                                │
│            ┌────────┴────────┐                       │
│            │                 │                       │
│         允许/需审批        拒绝 → 返回错误             │
│            │                                         │
│            ▼                                         │
│    ┌───────────────┐                                 │
│    │   沙箱执行     │ ← "在哪里执行？有什么限制？"     │
│    │  (Sandbox)    │                                 │
│    └───────┬───────┘                                 │
│            │                                         │
│      需要额外权限？                                    │
│            │                                         │
│            ▼                                         │
│    ┌───────────────┐                                 │
│    │   提权请求     │ ← "临时授予更多权限？"           │
│    │  (Elevated)   │                                 │
│    └───────────────┘                                 │
└──────────────────────────────────────────────────────┘

详细对比

维度	沙箱 (Sandbox)	工具策略 (Tool Policy)	提权 (Elevated)
作用	隔离执行环境	控制工具可用性	临时扩展权限
粒度	进程/环境级	工具级	操作级
检查时机	执行时	调用前	需要时
持续性	始终生效	始终生效	临时（单次操作）
配置位置	security.sandbox	security.toolPolicy	运行时交互

沙箱 (Sandbox)

"在哪里、用什么资源执行"

沙箱控制工具执行的物理环境：文件访问范围、网络权限、资源配额。

{
  "security": {
    "sandbox": {
      "enabled": true,
      "mode": "standard",
      "filesystem": {
        "allowedPaths": ["/home/user/project"]
      },
      "network": {
        "outbound": "restricted"
      }
    }
  }
}

适用场景：

• 限制 Agent 只能访问项目目录
• 防止工具访问系统敏感文件
• 控制网络访问范围

类比

沙箱就像一个"围栏" — 不管做什么操作，都不能越过围栏的边界。

工具策略 (Tool Policy)

"能不能用这个工具"

工具策略控制 Agent 可以使用哪些工具，以及哪些工具需要用户审批。

{
  "security": {
    "toolPolicy": {
      // 自动批准：不需要用户确认
      "autoApprove": [
        "read_file",
        "list_files",
        "search_files"
      ],
      // 需要审批：每次使用前需用户确认
      "requireApproval": [
        "write_file",
        "execute_command"
      ],
      // 禁用：完全不允许使用
      "denied": [
        "delete_directory",
        "modify_system"
      ]
    }
  }
}

适用场景：

• 禁止 Agent 执行危险命令
• 要求写入操作必须人工确认
• 限制可用工具集合

类比

工具策略就像"白名单/黑名单" — 决定哪些工具可以拿起来用。

提权 (Elevated)

"临时给更多权限"

当工具执行遇到权限不足时，Agent 可以请求临时提权（Elevation），经用户确认后获得一次性的扩展权限。

Agent: 我需要修改 /etc/hosts 文件来配置本地域名。
       这超出了当前沙箱范围。请求提权。

User:  [批准] / [拒绝] / [批准并记住]

Gateway: 临时授予对 /etc/hosts 的写入权限（本次会话有效）

提权配置

{
  "security": {
    "elevation": {
      "enabled": true,
      "maxDuration": 3600,        // 最大提权时间（秒）
      "requireReason": true,       // 要求 Agent 说明原因
      "allowRemember": true,       // 允许"记住"选择
      "rememberScope": "session"   // 记住范围：session / permanent
    }
  }
}

适用场景：

• Agent 需要临时访问受限资源
• 需要执行超出常规权限的操作
• 灵活平衡安全与便利

类比

提权就像"临时通行证" — 经过审批后，获得一次性的额外权限。

配置决策指南

场景 1：个人开发

{
  "security": {
    "sandbox": { "mode": "standard" },
    "toolPolicy": {
      "autoApprove": ["read_file", "list_files", "search_files", "write_file"],
      "requireApproval": ["execute_command"]
    },
    "elevation": { "enabled": true }
  }
}

场景 2：团队协作

{
  "security": {
    "sandbox": { "mode": "standard" },
    "toolPolicy": {
      "autoApprove": ["read_file", "list_files"],
      "requireApproval": ["write_file", "execute_command"],
      "denied": ["delete_directory"]
    },
    "elevation": { "enabled": true, "requireReason": true }
  }
}

场景 3：生产环境

{
  "security": {
    "sandbox": { "mode": "strict" },
    "toolPolicy": {
      "autoApprove": ["read_file"],
      "requireApproval": ["list_files", "search_files"],
      "denied": ["write_file", "execute_command", "delete_directory"]
    },
    "elevation": { "enabled": false }
  }
}

生产环境

生产环境建议使用严格沙箱 + 最小工具权限 + 禁用提权，最大程度降低安全风险。

执行流程示例

Agent 请求: write_file("/home/user/project/main.py", "...")

1. 工具策略检查
   └─ write_file 在 requireApproval 列表中
   └─ 等待用户审批...
   └─ 用户批准 ✓

2. 沙箱检查
   └─ /home/user/project/ 在 allowedPaths 中
   └─ 文件大小未超配额
   └─ 检查通过 ✓

3. 执行
   └─ 写入文件成功
   └─ 返回结果

相关文档

• 沙箱机制 — 沙箱详细配置
• 安全概览 — 完整安全架构
• 配置参考 — 完整配置项列表