第 04 模块 · 1 节

权限系统与工具授权详解

《Claude Code 进阶实战》04 权限与安全模型 · 本节时长 36 分钟

让 AI 动手,也要给它「划边界」

Claude Code 能读文件、改文件、跑命令——这是它强大的地方,也是危险的地方。如果不设边界,它可能:

  • 改了你不该让它动的文件
  • 跑了有副作用的命令
  • 删了不能删的东西

权限系统就是给 AI 划边界:明确它能碰什么、不能碰什么。这一节讲权限系统本身。

对 codex-review 来说,权限是必须想清楚的一层:评审技能要派多个子 Agent 并行读文件,还可能要跑测试、查依赖——到底允许它们做到哪一步? 评审虽然以「只读」为主,但让它只读、还是允许改、允许跑命令,边界完全不同,风险也不同。

贯穿项目codex-review 是「用权限模型限制评审能做什么」的活样板。评审子 Agent 默认该是「只读」的——只读代码、只出结论,不该改文件、不该乱跑命令。这一节理解权限机制,就是给 codex-review 定「评审能碰什么、不能碰什么」的基础。

权限解决的核心问题

一句话:什么工具、什么目录、什么命令,允许它碰。

维度 问的是
它能看哪些文件
它能改哪些文件
执行 它能跑哪些命令

三件事都搞清楚,边界就清晰了。

对 codex-review,把这个三个维度套到评审技能上,就是一份「评审权限说明」:

维度 评审默认
能读本次改动涉及的文件、diff、仓库结构
默认不能改任何文件(只出评审报告)
执行 默认不跑命令;确需跑测试/依赖检查时再单独授权

核心思路:评审是只读为主的工作,权限也要收着给。


理解「授权」的粒度

Claude Code 的权限不是「全有或全无」,而是分级的:

  • 全放开:想读就读、想改就改、想跑就跑(适合一次性、低风险任务)
  • 按目录:只允许改某些目录(如只改 src/
  • 按命令:只允许跑某些命令(如只跑 npm test
  • 需确认:敏感操作每次弹确认

你要做的,是按任务风险选合适的粒度

对 codex-review,授权粒度要「按评审任务的风险」选:

  • 纯只读评审:只需要「读」权限,粒度最紧,最安全。
  • 评审 + 跑测试:在「读」基础上,按命令只放行 npm test,不给其他命令。
  • 评审 + 修正:如果希望评审顺带修「必须改」,才需要「按目录」改某个 src/ 下的目录,且仍要限制范围。

默认从最紧的「只读」起步,确有必要再逐级放开。


一个具体的权限示例

假设任务是「让 Claude 优化 src/utils/ 下的工具函数」:

允许:
- 读整个项目(它需要了解上下文)
- 只修改 src/utils/ 目录下的文件
- 运行 npm test

禁止:
- 修改 src/api/ 目录
- 运行删除、覆盖生产配置的命令
- 修改 package.json 的依赖

这样它既能干活,又被限制在合理范围。

对 codex-review 的一次纯评审,权限示例应该更紧:

评审任务:审 src/ 本次 30 个文件改动
允许:
- 读本次改动涉及的 src/ 文件、diff
- 读取 package.json 以核对依赖安全(只读)

禁止:
- 修改任何文件(评审只出报告,不改代码)
- 运行 npm install、npm run 之外的任何命令
- 访问生产环境配置、数据库、密钥文件

注意:评审默认禁止「改任何文件」。这是评审权限和「优化代码」权限最大的区别——评审的产出是报告,不是改动。


权限和「最小权限」的关系

这一节先理解权限的机制。最小权限(默认收紧、需要才放开)是下节课的重点,但原理要先懂:权限不是越宽越好,而是够用就好。

多给一分权限,就多一分风险。给到「能完成当前任务」即可。

对 codex-review,这个原理落到一个具体的判断:评审要做的事就是「读 + 出报告」,所以给它「读 + 不写」就够了,别因为顺手就给它改文件或跑命令的权限。 够用就好,多给的每一分都是风险。


权限跟着任务走

权限不是一次设好就一劳永逸,要跟着任务变

  • 纯评审 → 只读
  • 评审 + 跑测试 → 只读 + npm test
  • 评审 + 修「必须改」 → 只读 + 按目录改

同一个 codex-review,任务范围不同,权限边界就不同。每次开任务前先想「这次它需要到哪一步」,再定权限。

心法权限随任务走:codex-review 默认只读,需要跑测试就加「测试命令」,需要修正就加「按目录改」。永远从「这次任务最少需要什么」出发,而不是「给它全都能干」。

落地练习

练习① 三步走:第 1 步,为 codex-review 的一次「纯评审」写一份权限说明(读哪些、禁止改、禁止跑什么命令);第 2 步,再写一份「评审 + 跑测试」版本的权限说明,对比差异在哪;第 3 步,实际让 Claude 按「纯评审」权限跑一次,观察它是否遵守「只读不写」。

② 怎么判断做对了:你能清楚说出现场景的「读/改/执行」三个维度分别放开了什么、收紧了什么;纯评审时它确实只读不改、没乱跑命令。

③ 卡住了怎么办:如果它审着审着想去改文件或跑命令,明确说「本次是纯评审,只读不写、不跑命令」;如果分不清该给什么权限,就回到「这次任务最少需要什么」反问自己。

常见坑:评审也顺手给了「改」权限

评审的产出是报告,但很多人懒得分界,直接把「改代码」的权限也一起给了——理由是「反正审完可能顺手改」。结果就是:一个本该只读的评审,突然有了改文件、跑命令的能力,风险敞口一下大很多。 子 Agent 在评审中万一被诱导或判断失误去改了不该改的文件,后果比多跑一句命令严重得多。

对策:把「评审」和「修正」拆成两个阶段、两套权限。 评审阶段只给读、禁止写;等你看完报告、决定要修,再单独开一个带「改」权限的任务去修。两阶段分开,权限才能收到最小。

做法codex-review 的评审阶段权限一律「只读、不写、不跑命令」;要修「必须改」时另开一个明确的修正任务并单独授权。评审和修正分开,权限边界才清晰。

小结

  1. 权限 = 划清「能读/能改/能执行」的边界
  2. 授权粒度:全放开 / 按目录 / 按命令 / 需确认
  3. 按任务风险选粒度,够用就好
  4. 权限跟着任务走,别一次放开就不管
  5. codex-review 默认「只读评审」,要修正再单独授权

下一节,把「最小权限」落地成实践——用安全的边界约束 codex-review 的评审。