1. 当 Claude Code 说“我没有权限”时它在说什么你第一次在终端里让 Claude Code 帮忙改一个配置文件它读完src/下的代码后突然停下来问你要不要允许它读取~/.config/app/settings.json。你点了允许它继续干活下一次换个项目它又问一遍。你可能会想这玩意儿到底是怎么判断哪些文件能碰、哪些不能碰的Claude Code 的权限制度本质上是一套“最小授权 显式确认”的访问控制层。它不会默认拥有你整个磁盘的读写权而是把每一次文件读取、写入、命令执行都当成一次需要审批的动作。默认状态下它能自由操作的范围通常只覆盖当前工作目录及其子目录一旦越界——比如去读~/.ssh/、/etc/、或者项目外的绝对路径——就会触发权限请求等你点头才继续。这套机制适合谁如果你是第一次配置 Claude Code、或者被Permission denied、Tool use blocked这类报错卡住那理解它的权限模型就是绕不开的一步。它解决的核心问题是让 AI 助手在帮你改代码的同时不会因为一条模糊指令就把敏感文件读走或覆盖掉。你可以把它想象成一个刚入职的实习生工位工作目录里的东西随便用但要进档案室系统目录、家目录敏感文件得先找你要钥匙。下面我会从权限配置骨架讲起给出settings.json里allow/deny规则的写法然后演示一次“文件读取被拦截 → 放行”的完整验证动作最后把常见的权限报错逐个拆开。全程围绕一个目标让你能自己画出 Claude Code 的最小授权边界。2. 前置准备拿到可用的 API Key 与接入地址在动权限配置之前得先让 Claude Code 能正常发请求。Claude Code 走的是 Anthropic 兼容的接口协议所以你需要一个可用的 API Key 和一个兼容的接入地址。我这边用的是 TaoToken 提供的接入方式它的 API 地址是https://taotoken.net/api模型对话、Coding Plan、控制台和 API Keys 管理都有对应的入口。具体操作路径是这样的先到控制台创建 API Key然后把它配置到 Claude Code 的环境变量里。Claude Code 读取的是ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL这两个变量。如果你用的是 Claude Code 的 Anthropic 接入模式把 base URL 指向兼容端点即可。# 在 shell 配置文件里写入以 zsh 为例bash 换成 ~/.bashrc export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_BASE_URLhttps://taotoken.net/api写完记得source ~/.zshrc让变量生效。验证变量是否写进去echo $ANTHROPIC_API_KEY | head -c 8 echo $ANTHROPIC_BASE_URL第一条应该输出你 key 的前 8 位第二条应该输出接入地址。如果第一条是空的说明变量没生效Claude Code 启动时会直接报鉴权失败而不是权限问题——这两个报错长得像但根因完全不同先分清楚。注意API Key 属于敏感凭据不要写进项目里的settings.json然后提交到 git。环境变量或者本地的密钥管理工具才是它该待的地方。拿到 Key 之后Claude Code 的请求链路就通了。接下来才是权限制度真正起作用的地方它管的是“这次请求里模型想碰哪个文件”。3. 可复制的权限配置骨架settings.json 里的 allow 与 denyClaude Code 的权限规则主要写在settings.json里。这个文件可以放在项目级的.claude/settings.json也可以放在用户级的~/.claude/settings.json。项目级配置只对当前项目生效用户级配置对你所有项目生效。排查权限问题时第一件事就是确认到底哪一层配置在起作用——两层都写了规则时项目级通常优先。一个最小可用的权限配置骨架长这样{ permissions: { allow: [ Read(./src/**), Read(./tests/**), Read(./*.md), Write(./src/**), Bash(npm run lint), Bash(npm run test:*) ], deny: [ Read(./.env), Read(./.env.*), Read(./**/*.pem), Read(./**/*.key), Read(~/.ssh/**), Read(/etc/**), Write(./.git/**), Bash(rm -rf:*), Bash(curl:*) ] } }这里有几个关键点需要拆开讲。allow列表里的规则是“预先授权”命中这些规则的操作用不着每次问你直接放行。deny列表是“硬拦截”命中就拒绝连问都不问。没命中任何一条的走默认询问流程——弹出来让你决定。规则格式是工具名(匹配模式)。Read、Write、Bash是最常用的三类。路径匹配支持 glob./src/**表示src目录下任意层级./*.md表示项目根目录下的 Markdown 文件~/.ssh/**表示家目录下的 ssh 目录。deny的优先级高于allow。也就是说哪怕你在allow里写了Read(./**)只要deny里有Read(./.env).env依然读不了。这个设计很关键它让你可以放心地开一个大范围的读权限同时用deny把敏感文件单独圈出来。提示Bash规则的匹配是前缀匹配Bash(npm run test:*)里的:*表示“后面可以跟任意参数”。写Bash(rm -rf:*)能拦住绝大多数危险删除但拦不住rm -r -f这种参数顺序变体所以别把它当成唯一防线。配置改完之后Claude Code 需要重新加载。多数情况下重启会话即可生效。如果你改了用户级配置但项目里没反应检查一下项目级.claude/settings.json是不是覆盖了同名规则。4. 验证一次拦截到放行文件读取的完整动作光看配置不够得实际跑一遍才能确认权限制度真的在工作。下面这个验证动作我建议你在一个测试项目里做别拿生产仓库练手。第一步在项目根目录建一个敏感文件和一个普通文件mkdir -p /tmp/perm-demo/src cd /tmp/perm-demo echo SECRET_TOKENabc123 .env echo console.log(hello) src/index.js第二步写一个只允许读src/、明确拒绝.env的配置{ permissions: { allow: [Read(./src/**)], deny: [Read(./.env)] } }第三步启动 Claude Code让它读src/index.js。这个操作命中allow应该直接返回文件内容不弹权限请求。第四步让它读.env。这个操作命中deny你应该看到类似这样的拦截信息Tool use blocked: Read(./.env) is denied by permission settings.注意这里不会弹“是否允许”的询问框因为deny是硬拦截。如果你看到的是询问框而不是拦截说明deny规则没写对或者被更高优先级的配置覆盖了。第五步把.env从deny里挪出来改成放进“默认询问”区间——也就是allow和deny都不写它。重启会话后再让它读.env这次应该弹出权限请求。你点允许它读到内容点拒绝它拿到拒绝结果并继续。这一套动作跑下来你就把三种状态都验证了allow直接放行、deny硬拦截、未命中走询问。理解这三态是排查所有权限报错的基础。5. 本篇常见权限报错排查权限相关的报错看着五花八门但根因基本落在几个固定位置。下面按出现频率排。报错一Tool use blocked但你没写过 deny 规则。先检查是不是用户级~/.claude/settings.json里有全局deny。很多人早期为了安全加过Read(~/**)之类的规则后来忘了。用cat ~/.claude/settings.json确认一遍。报错二明明 allow 了却还弹询问。大概率是路径没匹配上。Read(./src/**)匹配的是相对项目根目录的路径如果 Claude Code 实际请求的是绝对路径/tmp/perm-demo/src/index.js规则就对不上。解决办法是把规则写成能覆盖绝对路径的形式或者确认工作目录设置正确。报错三改了配置不生效。Claude Code 的配置加载有缓存。改完settings.json后要重启会话而不是在同一个会话里继续。另外确认你改的是当前生效的那一层——项目级和用户级同名规则项目级优先。报错四Bash命令被拦但规则看着没问题。Bash规则匹配的是命令字符串前缀。Bash(npm run test:*)能匹配npm run test:unit但匹配不了cd /tmp npm run test。带、;、管道符的复合命令往往需要拆开授权或者干脆走询问流程。报错五写入被拒但读没问题。Read和Write是分开授权的。你 allow 了Read(./src/**)不代表能写。要写就得单独加Write(./src/**)。这是最小授权原则的体现别嫌麻烦。报错六鉴权失败被误当成权限问题。如果报错里出现401、authentication、invalid api key这类字样那是 API Key 或接入地址的问题跟文件权限无关。回到第 2 节检查环境变量。排查顺序建议固定成先看报错类型鉴权还是权限→ 再看是哪一层配置 → 再看规则匹配模式 → 最后重启验证。按这个顺序走绝大多数权限问题五分钟内能定位。6. 把权限边界收进你的日常工作流权限配置不是配一次就完事的。项目在变敏感文件的位置在变你的授权范围也该跟着调。我的习惯是每个新项目初始化时先写一份最小allow列表——通常就是src/、tests/、几个配置文件——然后随着实际需要往里加。deny列表反而相对稳定.env、密钥文件、.git/内部、系统目录这几类基本每个项目都要拦。如果你经常在不同机器上切换用户级配置里放一套通用的deny兜底项目级配置里放具体的allow这样既不会漏掉敏感文件又不用每个项目重复写拦截规则。验证权限是否按预期工作最省事的办法就是第 4 节那套动作拿一个测试文件跑一遍 allow、deny、询问三态。花两分钟比事后猜“为什么它读不了这个文件”划算得多。需要管理多个项目的 Key 或者查看调用情况时控制台和 API Keys 页面能帮上忙如果你打算把 Claude Code 长期用在编码和 Agent 任务上Coding Plan 的额度模式会比按次调用更省心。接入文档里有完整的端点和参数说明配置卡住时对着查一遍通常就能解决。