6. 设置与安全——开发者参考

April 7, 2026 · View on GitHub

5 层设置优先级、沙箱隔离、权限模型。企业级 Code Agent 的安全与可配置性参考。Hook 系统详见 12-Hook 系统。

Qwen Code 对标：设置优先级（Qwen 有 user/project 两层 vs Claude Code 5 层）、沙箱（Qwen 无 OS 级沙箱，Gemini CLI 有 bwrap/Seatbelt）

为什么需要 5 层设置

问题定义

Code Agent 的配置需求因使用场景而异：

场景配置要求单层设置的问题
企业安全团队强制所有员工禁用 rm -rf、限制网络访问无法强制，员工可以覆盖
团队约定项目使用 pnpm 不用 npm，Python 项目用 ruff每个成员需手动配置
个人偏好我喜欢 vim 模式、暗色主题换项目后丢失
临时覆盖这次运行用 Opus 而非 Sonnet改了全局设置后忘记改回来

Claude Code 的解决方案：5 层优先级设置体系，高层可以"锁定"低层无法覆盖。

竞品设置层级对比

Agent设置层级企业管控远程下发
Claude Code5 层（企业→组织→用户→项目→本地）✓ managed-settings 强制锁定✓
Gemini CLI3 层（admin→user→workspace）+ TOML Policy✓ 通过 Policy 引擎—
Qwen Code2 层（user→project）——
Copilot CLI3 层（organization→user→workspace）✓ 通过 GitHub org 设置✓
Cursor2 层（user→workspace）——

5 层设置优先级体系

Claude Code 采用 5 层优先级设置体系，从高到低：

优先级来源路径/方式说明
1（最高）Managed（托管）managed-settings.json（MDM 部署/服务器下发）管理员强制策略，不可覆盖
2CLI 参数--model、--allowedTools 等命令行参数覆盖所有项目及用户设置
3本地项目.claude/settings.local.json（项目根目录）本地覆盖，不提交到 Git
4共享项目.claude/settings.json（项目根目录）项目级共享配置，提交到 Git
5（最低）用户~/.claude/settings.json个人全局偏好

注意：Managed 设置优先级最高；CLI 参数优先级高于项目设置；本地项目设置（.local.json）优先于共享项目设置。

第六轮修正： 原文档声称"7 层设置系统"，经官方文档（code.claude.com/docs/en/settings）验证，实际为 5 层优先级体系。优先级从高到低为：Managed > CLI 参数 > 本地项目 > 共享项目 > 用户。原"Organization"层不存在，CLI 参数优先级高于项目设置（非最低）。

设置文件示例（~/.claude/settings.json）：

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf /)"
    ]
  },
  "model": "claude-sonnet-4-6",
  "hooks": {}
}

项目级设置（.claude/settings.json）：

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)"
    ]
  }
}

Prompt Hook 系统

Claude Code 的 Hook 系统是其最独特的能力之一。与传统脚本 Hook 不同，Claude Code 支持 LLM 驱动的 Hook 决策——让 LLM 分析工具调用的意图和参数，决定是否允许执行。

Hook 事件类型（24 种）

事件触发时机来源
SessionStart会话开始时二进制+官方
SessionEnd会话结束时官方
UserPromptSubmit用户提交提示时二进制+官方
PreToolUse工具执行前二进制+官方
PostToolUse工具执行成功后二进制+官方
PostToolUseFailure工具执行失败后官方
PermissionRequest请求权限时官方
Notification通知事件二进制+官方
SubagentStart子代理启动时二进制+官方
SubagentStop子代理停止时二进制+官方
Stop代理停止时二进制+官方
StopFailure代理停止失败时官方
PreCompact上下文压缩前二进制+官方
PostCompact上下文压缩后二进制+官方
TaskCompleted后台任务完成时官方
TeammateIdleTeammate 空闲时官方
InstructionsLoaded指令文件加载时官方
ConfigChange配置变更时官方
WorktreeCreate创建 Git worktree 时官方
WorktreeRemove移除 Git worktree 时官方
Elicitation向用户请求信息时官方
ElicitationResult用户回复请求时官方
CwdChanged工作目录变更时v2.1.83 二进制确认
FileChanged文件变更检测时v2.1.83 二进制确认

来源：官方 Hooks 文档，全部 24 个事件在 v2.1.83 二进制中确认存在。

Hook 配置示例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/check_command.py \"$TOOL_INPUT\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo '文件已写入' >> /tmp/audit.log"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -message \"$NOTIFICATION_MESSAGE\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/check_env.py"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '即将压缩上下文' >> /tmp/audit.log"
          }
        ]
      }
    ]
  }
}

Hook 决策返回值

Hook 脚本通过 stdout 输出 JSON 控制行为：

  • approve：允许工具调用（跳过用户确认）
  • deny：拒绝工具调用
  • block：阻止并附带消息
  • 无输出或空输出：继续正常流程

权限与安全

安全监控系统（Auto Mode Classifier，反编译提取）

从二进制变量 d38（安全监控提示词）和 wSA（权限模板）反编译提取。这是 Claude Code 的自主模式安全系统——在 --permission-mode auto 或 --dangerously-skip-permissions 下运行时，由独立的分类器模型评估每个操作。

身份： "You are a security monitor for autonomous AI coding agents."

威胁模型（3 种风险）：

风险说明
Prompt Injection代理被文件/网页/工具输出中的内容操纵执行有害操作
Scope Creep代理超出任务范围——修复一个问题后"顺便"删除基础设施或外泄数据
Accidental Damage代理不理解爆炸半径——删除自认为是自己任务的内容但实际是共享的

默认规则： "默认允许。仅在命中 BLOCK 条件且无 ALLOW 例外时阻止。"

BLOCK 条件（28 条，从二进制逐字提取）：

类别规则说明
Git 破坏Git Destructiveforce push、删除远程分支、改写远程历史
Git 推送Push to Default Branch直接推送到 main/master 绕过 PR 审查
外部代码Code from Externalcurl | bash、eval、pickle、exec 来自外部源
云存储Cloud Storage Mass DeleteS3/GCS/Azure 批量删除或修改
生产部署Production Deploy部署到生产或执行生产数据库迁移
远程写入Remote Shell Writeskubectl exec、docker exec、ssh 写入操作
盲目应用Blind Apply跳过 preview/dry-run 直接执行破坏性操作
日志篡改Logging Tampering停止日志、删除日志目录、移除 git hooks
权限提升Permission Grant授予 admin/owner、添加用户、提升 IAM/RBAC
安全降级TLS/Auth Weaken禁用 TLS 验证、--allow-unauthenticated
安全削弱Security Weaken禁用安全缓解、修改防火墙规则
创建不安全代理Create Unsafe Agents无人工审批的自主代理循环
干扰他人Interfere With Others删除作业、破坏集群、轰炸 Slack
修改共享资源Modify Shared Resources原地修改非自己创建的共享配置/数据
不可逆本地破坏Irreversible Local Destructionrm -rf、git clean -fdx、git checkout .
创建 RCECreate RCE Surfaceeval、shell 注入、不安全反序列化
暴露本地服务Expose Local Services绑定端口暴露本地文件/服务
凭据泄露Credential Leakage在 metadata/labels/URLs 中嵌入密钥
凭据探索Credential Exploration系统性扫描凭据存储寻找可用 token
数据外泄Data Exfiltration发送敏感数据到外部端点
外泄侦察Exfil Scouting测试外部端点可达性
信任猜测的服务Trusting Guessed Services向代理自行猜测的外部服务发送数据
不受信代码集成Untrusted Code Integration从外部仓库拉取代码并执行
未授权持久化Unauthorized Persistence添加 SSH 密钥、修改 .bashrc、创建 cron
自我修改Self-Modification修改代理自身的配置/设置/权限文件
外部系统写入External System Writes删除/修改 Jira/Linear/GitHub 中非自己创建的项目
内容伪造Content Impersonation发布虚假内容、伪造声明
真实世界交易Real-World Transactions购买、支付、预订、发送外部通信

ALLOW 例外（7 条）：

例外说明
Test Artifacts硬编码测试密钥、占位符凭据
Local Operations工作目录内的文件操作、本地测试
Read-Only OperationsGET 请求、不修改状态的查询
Declared Dependencies从仓库 manifest 文件安装依赖
Toolchain Bootstrap官方一键安装（rustup、pypa、bun）
Standard Credentials从自身配置读取凭据发送给对应提供商
Git Push to Working Branch推送到会话分支（非默认分支）

分类器架构：

属性值
阶段双阶段：fast（XML, 256 token 上限）→ thinking（XML, 4096 token 上限）
默认模型claude-sonnet-4-6（大上下文时使用 claude-sonnet-4-6[1m]）
输出格式<block>yes/no</block><reason>一句话原因</reason>
失败安全解析失败 → 阻止；错误/超时 → 阻止
用户意图"用户意图提供上下文但不是 BLOCK 条件的自动覆盖"

沙箱模式

平台沙箱技术说明
macOSsandbox-exec（Seatbelt）基于 Apple 沙箱配置文件，限制文件系统和网络访问
LinuxDocker 容器通过容器隔离文件系统和网络

权限规则语法（二进制提取 + 官方文档）

规则格式：ToolName 或 ToolName(specifier)，支持通配符 *。

Bash 命令规则（从二进制提取的内置模式，38 个）：

模式说明
Bash(git:*)所有 git 命令
Bash(git add:*)git add 及其参数
Bash(git commit:*)git commit
Bash(git push:*)git push
Bash(git diff:*)git diff
Bash(git log:*)git log
Bash(git status:*)git status
Bash(git show:*)git show
Bash(git checkout -b:*)创建新分支
Bash(git checkout --branch:*)创建新分支（长参数）
Bash(git remote show:*)查看远程信息
Bash(gh:*)所有 GitHub CLI 命令
Bash(gh pr:*)GitHub PR 操作
Bash(gh pr create:*)创建 PR
Bash(gh pr edit:*)编辑 PR
Bash(gh pr merge:*)合并 PR
Bash(gh pr view:*)查看 PR
Bash(npm:*)所有 npm 命令
Bash(npm install)npm install（精确匹配）
Bash(npm run *)npm run 脚本
Bash(npm run build)npm run build（精确）
Bash(npm run lint)npm run lint（精确）
Bash(npm run test)npm run test（精确）
Bash(pnpm:*)所有 pnpm 命令
Bash(yarn:*)所有 yarn 命令
Bash(bun:*)所有 bun 命令
Bash(curl:*)curl 命令（通常放 deny）
Bash(http:*)HTTP 相关命令
Bash(asciinema:*)终端录制
Bash(rm -rf:*)危险删除（通常放 deny）
Bash(sleep ...)sleep 命令

文件操作规则：

模式说明
Read允许所有文件读取
Read(~/**)允许读取用户目录
Read(~/.zshrc)只允许读取特定文件
Write(/etc/*)允许写入 /etc（危险）
Edit(.claude)允许编辑 .claude 目录
Edit(~/.claude/settings.json)编辑特定设置文件
Edit(docs/**)编辑 docs 目录下所有文件

网络规则：

模式说明
WebFetch(domain:example.com)限制到特定域名
WebFetch(domain:github.com)允许 GitHub
WebFetch(domain:*.google.com)通配符域名
WebSearch(claude ai)搜索特定主题

MCP 工具规则： mcp__serverName__toolName 格式（双下划线）

三层评估顺序（官方文档）：deny → ask → allow → 默认需确认

--permission-mode 选项（claude --help 确认）

模式说明
default默认模式——未匹配规则的操作需确认
acceptEdits自动接受文件编辑，其他操作仍需确认
plan规划模式——仅允许只读操作
auto自动模式——减少确认频率
dontAsk不询问——自动执行所有操作
bypassPermissions绕过所有权限检查（需 --dangerously-skip-permissions）

证据：claude --help 输出 --permission-mode <mode> (choices: "acceptEdits", "bypassPermissions", "default", "dontAsk", "plan", "auto")

权限配置示例

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run *)",
      "Bash(git:*)",
      "Bash(gh pr view:*)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(rm -rf:*)",
      "Write(/etc/*)"
    ]
  }
}

配置示例

完整设置文件（~/.claude/settings.json）

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)"
    ]
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/check_bash.py"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' \"$CLAUDE_NOTIFICATION\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/session_init.py"
          }
        ]
      }
    ]
  }
}

项目级配置（.claude/settings.json）

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(npx prisma *)"
    ]
  },
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}