AI Agent 工具权限粒度设计：如何避免"要么全给要么全不给"
给 AI Agent 配工具时，最容易踩的坑不是工具太少或太多，而是权限粒度只有两档：完全信任或完全不给。结果要么 Agent 什么危险操作都能做（删文件、跑任意命令、改生产配置），要么处处要人工确认导致体验退化成”AI 打字机”。本文讨论如何设计一套中间地带的权限体系。（工具本身的语义设计参考AI Agent 工具集合的设计原则，本文只聚焦权限维度。）
一、为什么权限粒度是 Agent 落地的关键变量
Agent 与传统程序最大的区别是决策路径不可完全预测——你给它一把删除文件的权限，它可能在第 3 步就用上，也可能在第 30 步才用上，具体触发条件取决于模型对任务的理解，不是代码里写死的分支。
这带来一个直接后果：权限设计不能靠”审查代码逻辑”来兜底，必须靠运行时的边界控制。也就是说，即使 Agent 的 prompt 和工具描述写得再谨慎，也需要一层独立于模型判断之外的权限系统。
常见的两种失败模式：
- 过度收紧：每个文件写入、每条命令执行都要人工 approve，Agent 沦为”建议生成器”，长任务场景完全跑不起来；
- 过度放开：为了让 Agent”自主”，给了 shell 全权限，结果一次误判的
rm或者一次被注入的 prompt 就能造成实际破坏。
权限粒度设计的目标，是找到”Agent 能自主完成大多数安全操作，同时高风险操作强制经过额外校验”的那个平衡点。
二、按操作风险分级，而不是按工具分级
一个常见误区是把权限绑定在”工具”这个粒度上——比如”文件工具允许，命令行工具需要确认”。这个粒度太粗，因为同一个工具内部的不同调用风险差异极大：读文件和删文件都是”文件工具”，风险完全不在一个量级。
更合理的分级方式是按操作的可逆性和影响范围来划分：
| 风险等级 | 特征 | 示例操作 | 授权策略 |
|---|---|---|---|
| 低风险 | 只读、可逆 | 读文件、跑测试、查日志 | 自动放行 |
| 中风险 | 可逆但影响范围大 | 写文件、创建分支、装依赖 | 自动放行 + 事后可审计 |
| 高风险 | 不可逆或影响生产 | 删除文件、git push --force、执行任意 shell 命令、访问密钥 | 强制人工确认 |
| 禁止 | 无论如何不应由 Agent 触发 | 修改权限系统本身、访问生产数据库写权限 | 不暴露为工具 |
这套分级的关键在于第三档：不是完全禁止，而是”强制人工确认”——既不牺牲自主性上限，又给不可逆操作加了一道人工闸门。Claude Code、Codex CLI 这类 CLI 编程 Agent 的 approval policy 机制本质上都是这个思路的落地实现。
三、最小权限原则的具体落地方式
“最小权限”说起来容易，落地时容易变成一句口号。具体可执行的做法包括：
按任务动态收缩权限范围，而不是给 Agent 一个固定不变的权限集合。比如一个”修 bug”任务，只需要开放当前 repo 目录的读写权限，不需要开放整个文件系统；一个”发布”任务，才临时开放部署相关的权限，任务结束后收回。
用路径/资源白名单代替”是否允许某类操作”的二元开关。例如文件写入权限不是”允许/禁止”，而是”允许写入 src/ 目录下的文件，禁止写入 .env、.git/config 等敏感路径”。
区分”读取密钥”和”使用密钥”。Agent 执行需要调用外部 API 的任务时，理想情况下它不应该看到密钥明文，而是通过一层代理注入凭证——这样即使 Agent 的输出被意外记录或泄露到日志里，密钥本身也不会暴露。
四、审批流设计：同步确认 vs 异步审计
高风险操作的处理方式不止”实时弹窗确认”一种，实际可以按场景选择：
同步确认：适合交互式会话（终端里跑 Claude Code/Codex CLI），
Agent 卡住等人工点头，体验成本高但风险控制最强。
异步审计：适合后台批量任务（CI 里跑的自动化 Agent），
Agent 先执行低风险操作，高风险操作生成"待执行计划"，
人工在下一个检查点批量审核，不阻塞任务本身的推进。
分级放行：对可信任务类型（如运行测试）设白名单自动跳过确认，
对陌生任务类型保留确认，随着信任积累逐步放宽。三种模式不互斥，成熟的 Agent 系统往往是组合使用：交互式场景用同步确认兜底高风险操作，批量场景用异步审计+事后回滚能力覆盖，同时通过分级放行减少不必要的打断。
五、沙箱隔离是权限设计的物理边界
权限系统再精细，也只是”软约束”——真正的硬约束是沙箱。让 Agent 在容器、虚拟机或者受限文件系统里运行，即使权限判断出现漏洞（比如被 prompt injection 诱导执行了不该执行的命令），实际影响范围也被限制在沙箱内，不会波及宿主系统。
沙箱隔离和权限分级是互补关系，不是替代关系：
- 权限分级解决”Agent 应该做什么”（意图层面的约束）
- 沙箱隔离解决”即使 Agent 做错了，代价有多大”（后果层面的约束）
只做权限分级不做沙箱，相当于只靠”信任”撑着；只做沙箱不做权限分级，Agent 在沙箱里也可能把自己的工作成果搞乱（比如误删本次任务的产出文件），影响任务完成质量。两层都要有。
六、多 Agent 场景下的权限传递问题
当一个 Agent 可以调用子 Agent（比如主任务 Agent 分派子任务给专门的代码审查 Agent），权限设计还要处理传递问题：子 Agent 是否继承主 Agent 的全部权限？
推荐原则是权限只能收窄，不能扩大——子 Agent 拿到的权限集合必须是父 Agent 权限集合的子集，且默认应该比父 Agent 更严格（子任务通常范围更窄，不需要父任务的全部权限）。这能避免”通过多层委派逐步扩大实际权限”的隐蔽风险，这类风险在权限审计时最容易被忽略，因为审计者往往只看顶层 Agent 的权限声明，而不会逐层检查子 Agent 的实际权限。
七、和错误恢复机制的配合
权限系统与Agent 的错误恢复设计是两个互相支撑的机制：权限系统防止 Agent 主动做出不可逆的破坏，错误恢复机制处理 Agent 判断失误后的补救（回滚、重试、降级）。两者都缺一不可——只有权限控制没有错误恢复，Agent 在中风险操作上出错后无法自愈；只有错误恢复没有权限控制，高风险操作一旦执行，有些后果是恢复机制也无法挽回的（比如密钥泄露、生产数据被覆盖）。
八、一个可以直接套用的检查清单
设计或审查一套 Agent 权限体系时，可以逐项确认：
- 是否按”可逆性 + 影响范围”而非”工具类别”划分风险等级
- 高风险操作是否有强制人工确认或事后审计，而不是完全放开
- 敏感路径/资源是否用白名单而非黑名单方式限定
- Agent 是否需要看到密钥明文，还是可以通过代理层间接使用
- 是否有物理层面的沙箱兜底，而不只依赖软件层面的权限判断
- 多 Agent 场景下，子 Agent 权限是否严格是父 Agent 权限的子集
九、相关阅读
搭建自己的 Agent 权限体系时，底层模型 API 的稳定接入同样重要，通过 YoTradeApi 中转可以统一管理多模型调用凭证，减少密钥在 Agent 各层之间裸传的风险。