把 Claude Code 的手脚管住：用 settings.json 权限模式给 Agentic Coding 装上安全阀

1. 为什么 Claude Code 需要一道“安全阀”Claude Code 在 Agentic Coding 场景里最容易被低估的能力不是补全代码而是它能读文件、改文件、跑 shell command、访问外部服务。一个 coding agent 真正危险的地方往往不是它答错了什么而是它在没人盯着的时候动了什么。我见过最典型的翻车场景是让它“顺手把测试跑通”结果它执行了git reset --hard把同事未提交的改动清掉了或者它为了修一个 lint 报错直接改了package.json里的依赖版本连锁触发 CI 失败。Claude Code 的权限系统就是围绕这个问题设计的。它把“思考”和“行动”拆开模型可以自由分析、搜索、读上下文但涉及写文件、执行命令、访问外部资源时必须经过权限模式、规则、配置层级、人工确认这几道关卡。核心不是让 Claude Code 变保守而是让它在不同工作阶段拥有不同的行动边界。这篇内容聚焦三件事第一把settings.json的权限骨架讲清楚让你能直接复制第二梳理 Plan mode 与权限模式的协作边界避免“计划还没批就动手”第三给出逐项验证动作让你在本地复现安全阀效果。如果你还没决定用哪条 API 通道可以先用 TaoToken 统一 Key 和接入地址后面配置里会给出具体写法。2. 前置准备用 TaoToken 统一 Key 与 API 通道在动settings.json之前先把模型接入通道固定下来。Claude Code 这类工具会频繁发起请求如果 Key 分散在多个地方排障时很难判断是权限规则拦了还是通道本身不通。TaoToken 的作用是把 Key 和 API 地址统一管理官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你需要先拿到一个可用的 Key。进入控制台创建 API Key页面在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建后把 Key 写进环境变量不要硬编码进settings.json因为settings.json通常会进版本控制。# 写入 shell 配置按你实际使用的 shell 选择 echo export ANTHROPIC_BASE_URLhttps://taotoken.net/api ~/.zshrc echo export ANTHROPIC_API_KEYsk-你的TaoTokenKey ~/.zshrc source ~/.zshrc # 验证环境变量已生效 echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8这里有个容易踩的坑ANTHROPIC_BASE_URL末尾不要带/v1Claude Code 会自己拼接路径。如果你之前配过别的地址先清掉旧变量再写入避免多个配置互相覆盖。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有不同客户端的完整参数说明。注意Key 只放在环境变量或本机未纳入版本控制的文件里。settings.json里写的是权限规则不是凭证。3. 可复制的 settings.json 权限骨架Claude Code 的权限配置分三层用户级~/.claude/settings.json、项目共享级.claude/settings.json、项目本地级.claude/settings.local.json。评估顺序是 deny → ask → allow只要命中 deny再窄的 allow 也救不回来。这个顺序很关键安全策略应该让禁止规则优先。下面是一份可以直接复制的项目级骨架放在仓库根目录的.claude/settings.json{ permissions: { defaultMode: default, allow: [ Bash(git status), Bash(git diff:*), Bash(git log:*), Bash(npm run lint), Bash(npm run test:*), Bash(pnpm typecheck), Read(./src/**), Read(./tests/**) ], ask: [ Bash(git push:*), Bash(npm install:*), Bash(terraform plan:*), Edit(./package.json) ], deny: [ Read(./.env), Read(./.env.*), Read(./secrets/**), Bash(git push origin main), Bash(git reset --hard:*), Bash(git clean:*), Bash(npm publish:*), Bash(terraform destroy:*), Bash(kubectl apply:*), Bash(aws *:*) ] } }逐项解释一下设计意图。defaultMode设成default意味着默认每次写文件和跑命令都要确认这是最稳的起点。allow里只放只读或可恢复的命令git status、git diff、git log是纯读npm run lint、npm run test、pnpm typecheck是本地反馈循环跑坏了重跑就行。Read规则限定在src和tests避免它去翻整个 home 目录。ask里放的是“需要人看一眼”的动作git push会影响远端npm install会改 lock fileterraform plan虽然只读但会暴露基础设施信息Edit(./package.json)单独拎出来是因为依赖变更影响面大。deny是硬边界.env和secrets目录直接禁止读取防止凭证被带进上下文git push origin main、git reset --hard、git clean禁止避免不可逆的版本库操作npm publish、terraform destroy、kubectl apply、aws *禁止把发布、销毁、集群变更、云资源操作全部锁死。如果你想让个人偏好覆盖项目配置在.claude/settings.local.json里写更保守的规则比如把defaultMode设成plan。这个文件不要提交到 git。4. 验证权限规则是否真的生效配置写完不代表生效必须逐项验证。下面这套动作可以在本地复现安全阀效果。第一步确认配置文件被加载。在项目根目录启动 Claude Code输入/permissions查看当前生效的规则列表。你应该能看到allow、ask、deny三组规则以及当前的defaultMode。第二步验证 allow 规则。让 Claude Code 执行git status它应该直接运行不弹确认。再让它跑npm run test同样应该自动执行。如果这里弹了确认说明规则没匹配上检查命令字符串是否和allow里的写法完全一致。第三步验证 deny 规则。让它尝试读取.env应该被直接拒绝并提示命中 deny 规则。再让它执行git reset --hard HEAD~1同样应该被拦下。这一步是安全阀的核心如果 deny 没生效说明规则顺序或写法有问题。第四步验证 ask 规则。让它执行git push origin feature/test应该弹出确认框等你手动批准。这里注意git push origin main会被 deny 直接拦掉不会走到 ask这正是 deny 优先的体现。第五步验证 Plan mode 与权限的协作。按ShiftTab切到 Plan mode让 Claude Code 分析一个复杂改动比如“把 REST controller 迁移到 OData V4”。它应该只读文件、跑只读命令、给出计划不会直接改源文件。计划出来后你可以选择批准并进入 accept edits或者继续让它调整。这一步验证的是“计划未批不动手”的边界。# 验证 deny 规则时可以在 Claude Code 里直接输入 # 读取 .env 应该被拒绝 Read ./.env # 执行破坏性 git 命令应该被拒绝 git reset --hard HEAD~1 # 验证 allow 规则 git status npm run test如果某条规则没按预期生效先看/permissions里的实际加载结果再检查 JSON 语法。settings.json对格式很敏感多一个逗号就会整份失效。5. 本篇常见错排查错误一规则写了但完全不生效。最常见原因是 JSON 语法错误。用python -m json.tool .claude/settings.json校验一下能快速定位逗号、引号问题。另一个原因是文件放错位置项目级必须是.claude/settings.json不是根目录的settings.json。错误二deny 规则被 allow 覆盖。不会发生评估顺序是 deny → ask → allow。如果你发现 deny 没拦住检查是不是写成了Bash(git reset --hard)但实际命令带了参数git reset --hard HEAD~1。带参数的命令要用:*通配比如Bash(git reset --hard:*)。错误三Plan mode 下它还是改了文件。检查当前模式是否真的切到了 Plan。ShiftTab循环切换状态栏会显示当前模式。如果状态栏显示的是 accept edits那它当然会直接改。另外Plan mode 下权限提示仍按 default 规则走只读命令不需要确认写操作会被拦。错误四Auto accept edits 下跑了危险命令。这个模式会自动批准常见文件系统命令比如mkdir、mv、cp、sed但不会自动批准npm publish、kubectl apply这类。如果你发现危险命令被自动执行了检查是不是把它误放进了allow。allow里只放低风险命令这是底线。错误五环境变量没生效请求全部失败。先echo $ANTHROPIC_BASE_URL确认地址是https://taotoken.net/api再确认 Key 没有多余空格。如果用的是 IDE 内置终端可能需要重启 IDE 让环境变量重新加载。接入文档里有各客户端的排查清单遇到通道问题可以直接对照。错误六团队共享配置和个人配置冲突。数组类型的权限规则会跨 scope 合并不是覆盖。所以团队.claude/settings.json里的 deny 规则个人.claude/settings.local.json里加不回来。这是设计如此安全规则应该让组织层优先。如果你需要个人放宽只能改团队配置或换项目。6. 把权限模式用成工作流而不是开关Claude Code 的权限模式不是“开或关”而是随任务风险动态调整的工作流。需求不清楚时用 Plan mode让它先出方案再动手补丁目标明确时用 Auto accept edits配合 allow 规则跑短反馈循环触达生产、凭证、远程基础设施时回到 Default mode甚至加 deny 规则。settings.json把个人偏好、项目规范、组织政策串起来让这套边界可以进版本控制、分发给团队。如果你还在选接入通道建议先用 TaoToken 把 Key 和 API 地址统一起来再配权限规则。模型对话入口在 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 适合验证模型是否通长期编码和 Agent 任务可以用 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。先把通道跑通再把安全阀装上顺序别反。