Claude Code配置体系全解析：五层优先级到权限沙箱实战

graph TB
    subgraph "配置优先级（从高到低）"
        A["🔒 Managed<br/>企业托管配置<br/>无法被任何层级覆盖"]
        B["⌨️ CLI Arguments<br/>命令行参数<br/>临时会话覆盖"]
        C["🏠 Local<br/>~/.claude/settings.local.json<br/>项目级个人覆盖"]
        D["📂 Project<br/>项目级共享配置<br/>团队统一规范"]
        E["👤 User<br/>用户级全局配置<br/>跨项目个人偏好"]
    end
    A --> B --> C --> D --> E
    style A fill:#ff6b6b,color:#fff
    style B fill:#ffd93d,color:#333
    style C fill:#6bcb77,color:#fff
    style D fill:#4d96ff,color:#fff
    style E fill:#9b59b6,color:#fff

# 查看当前所有权限规则及其来源
/permissions

# 在终端中直接检查配置
cat ~/.claude/settings.json         # 用户级
cat .claude/settings.json           # 项目级
cat .claude/settings.local.json     # 本地覆盖

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": [],
    "defaultMode": "default"
  },
  "hooks": {},
  "env": {},
  "model": "claude-sonnet-4-6",
  "sandbox": {
    "enabled": false
  },
  "outputStyle": "default",
  "spinnerTipsEnabled": true,
  "additionalDirectories": [],
  "enabledPlugins": [],
  "strictKnownMarketplaces": [],
  "allowManagedPermissionRulesOnly": false,
  "allowManagedHooksOnly": false
}

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(npm test *)",
      "Bash(git status)",
      "Read",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "WebSearch"
    ],
    "ask": [
      "Bash(*)"
    ],
    "disableBypassPermissionsMode": "disable",
    "disableAutoMode": "disable"
  }
}

graph LR
    subgraph "权限模式光谱"
        A["plan<br/>只读探索<br/>最安全"] --> B["default<br/>标准确认"]
        B --> C["acceptEdits<br/>自动编辑"]
        C --> D["auto<br/>后台安全检查"]
        D --> E["dontAsk<br/>拒绝未预批准"]
        E --> F["bypassPermissions<br/>跳过所有提示<br/>最危险"]
    end
    style A fill:#27ae60,color:#fff
    style F fill:#e74c3c,color:#fff

{
  "env": {
    "ANTHROPIC_API_KEY": "",
    "NODE_ENV": "development",
    "CUSTOM_CONFIG_PATH": "/path/to/config"
  }
}

{
  "model": "claude-sonnet-4-6"
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": false,
    "excludedCommands": ["git"],
    "network": {
      "allowLocalBinding": false,
      "allowedDomains": ["registry.npmjs.org", "github.com"],
      "allowAllUnixSockets": false,
      "allowUnixSockets": []
    },
    "enableWeakerNestedSandbox": false
  }
}

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(git *)",
      "Bash(node *)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(pwd)",
      "Read",
      "Grep",
      "Glob",
      "WebFetch"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~)",
      "Bash(sudo *)",
      "Bash(chmod 777 *)"
    ],
    "ask": [
      "Bash(*)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npm test 2>&1 | tail -20"
          }
        ]
      }
    ]
  },
  "additionalDirectories": ["../shared-lib"],
  "spinnerTipsEnabled": false
}

ToolName(pattern)

flowchart TD
    A["工具调用请求"] --> B{"匹配deny规则?"}
    B -->|是| C["❌ 拒绝执行"]
    B -->|否| D{"匹配ask规则?"}
    D -->|是| E["🔔 弹出确认对话框"]
    D -->|否| F{"匹配allow规则?"}
    F -->|是| G["✅ 自动执行"]
    F -->|否| H{"权限模式?"}
    H -->|default| E
    H -->|bypassPermissions| G
    H -->|plan| I["❌ 拒绝（plan模式不可写入）"]
    style C fill:#e74c3c,color:#fff
    style G fill:#27ae60,color:#fff
    style E fill:#f39c12,color:#fff

{
  "allow": [
    "Bash(npm run lint)",
    "Bash(npm test *)",
    "Bash(git status)",
    "Bash(git diff *)",
    "Bash(git log *)",
    "Bash(python3 *)"
  ],
  "deny": [
    "Bash(rm -rf *)",
    "Bash(sudo *)",
    "Bash(curl * | bash)",
    "Bash(wget * -O * | bash)"
  ]
}

{
  "allow": [
    "Read",
    "Glob",
    "Grep"
  ],
  "deny": [
    "Write(.env*)",
    "Edit(.env*)",
    "Write(*credentials*)",
    "Write(*secret*)"
  ]
}

{
  "allow": [
    "mcp__github__*",
    "mcp__database__query"
  ],
  "deny": [
    "mcp__database__drop*"
  ]
}

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "github.com",
        "api.github.com"
      ],
      "allowLocalBinding": false
    }
  }
}

graph TB
    subgraph "Lax - 宽松模式"
        L1["✅ Bash命令自由执行"]
        L2["✅ 无沙箱限制"]
        L3["✅ 仅禁止bypass模式"]
    end
    subgraph "Strict - 严格模式"
        S1["🔔 所有Bash需确认"]
        S2["❌ 禁止WebSearch/WebFetch"]
        S3["❌ 禁止用户自定义hooks"]
        S4["❌ 禁止用户自定义权限规则"]
    end
    subgraph "Sandbox - 沙箱模式"
        X1["🔒 Bash在沙箱内执行"]
        X2["🔒 网络白名单限制"]
        X3["❌ 禁止用户自定义权限规则"]
    end
    L1 --- L2 --- L3
    S1 --- S2 --- S3 --- S4
    X1 --- X2 --- X3

{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  },
  "strictKnownMarketplaces": []
}

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "ask": ["Bash"],
    "deny": ["WebSearch", "WebFetch"]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "strictKnownMarketplaces": []
}

{
  "allowManagedPermissionRulesOnly": true,
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowLocalBinding": false,
      "allowedDomains": []
    }
  }
}

> /permissions

Permission Rules (from settings.json)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ ALLOW  Bash(npm test *)          — project settings
✅ ALLOW  Bash(git *)               — project settings
✅ ALLOW  Read                      — user settings
🔔 ASK    Bash(*)                   — project settings
❌ DENY   Bash(rm -rf *)            — project settings
❌ DENY   Bash(sudo *)              — managed settings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

flowchart LR
    subgraph "会话生命周期"
        A["SessionStart"] --> B["InstructionsLoaded"]
        B --> C["UserPromptSubmit"]
        C --> D["PreToolUse"]
        D --> E["PostToolUse"]
        E --> F["PostToolBatch"]
        F --> G["Stop"]
        G --> C
    end

    subgraph "特殊事件"
        H["PermissionRequest"]
        I["PermissionDenied"]
        J["Notification"]
        K["SubagentStart"]
        L["SubagentStop"]
        M["SessionEnd"]
    end

    style A fill:#3498db,color:#fff
    style G fill:#e74c3c,color:#fff
    style M fill:#2c3e50,color:#fff

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<ToolPattern>",
        "hooks": [
          {
            "type": "command",
            "command": "your-shell-command"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint \"$CLAUDE_FILE_PATH\" --fix 2>&1 | head -30"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cd $PROJECT_DIR && npm test 2>&1 | tail -30"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=\"$CLAUDE_FILE_PATH\"; if echo \"$FILE\" | grep -qE '\\.(env|key|pem|p12)$|credentials|secret'; then echo 'BLOCK: Sensitive file detected' >&2; exit 2; fi"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "git add \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST \"$SLACK_WEBHOOK_URL\" -H 'Content-type: application/json' --data '{\"text\":\"Claude Code: $CLAUDE_NOTIFICATION\"}'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/validate",
            "headers": {
              "Authorization": "Bearer $VALIDATION_TOKEN"
            }
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run build 2>&1 | tail -10",
            "async": true
          }
        ]
      }
    ]
  }
}

project-root/
├── .claude/
│   ├── settings.json          # 项目级共享配置
│   ├── settings.local.json    # 项目级个人覆盖（gitignored）
│   ├── CLAUDE.md              # 项目级指令（备选位置）
│   ├── rules/                 # 条件加载的规则文件
│   │   ├── typescript.md      # TypeScript相关规则
│   │   ├── react.md           # React相关规则
│   │   └── database.md        # 数据库相关规则
│   ├── agents/                # 自定义子Agent
│   │   ├── reviewer.md        # 代码审查Agent
│   │   └── architect.md       # 架构设计Agent
│   ├── skills/                # 自定义Skills
│   │   └── deploy/
│   │       └── SKILL.md
│   ├── commands/              # 自定义斜杠命令
│   │   └── check.md
│   ├── output-styles/         # 自定义输出样式
│   │   └── concise.md
│   └── auto.md                # 自动记忆存储
├── CLAUDE.md                  # 项目指令（主位置）
├── CLAUDE.local.md            # 个人项目指令（gitignored）
└── .mcp.json                  # MCP服务器配置

<!-- .claude/rules/typescript.md -->
---
description: TypeScript项目规则
globs: ["**/*.ts", "**/*.tsx"]
---

# TypeScript 规范
- 使用严格模式
- 优先使用 interface 而非 type
- 禁止使用 any
- 导出函数必须有JSDoc注释

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

# 项目：Next.js电商平台

## 技术栈
- Next.js 15 (App Router)
- TypeScript 5.x
- Tailwind CSS 4
- Prisma ORM
- PostgreSQL

## 代码规范
- 使用函数组件和hooks
- 文件命名：kebab-case
- 组件目录：src/components/
- API路由：src/app/api/
- 数据库操作：src/lib/db.ts
- 禁止直接使用fetch，使用 src/lib/api-client.ts

## 测试
- 测试框架：Vitest + Testing Library
- 运行命令：npm test
- 所有新功能必须有测试

## Git
- 分支命名：feat/xxx, fix/xxx, chore/xxx
- Commit message：Conventional Commits
- 不自动commit，需要手动确认

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(npm run *)",
      "Bash(npx *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(node *)",
      "Read",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Write(.env*)",
      "Write(*credentials*)",
      "Write(*secret*)"
    ],
    "ask": [
      "Bash(*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          },
          {
            "type": "command",
            "command": "npx eslint \"$CLAUDE_FILE_PATH\" --fix 2>&1 | tail -5"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npm run typecheck 2>&1 | tail -10"
          }
        ]
      }
    ]
  },
  "additionalDirectories": [],
  "spinnerTipsEnabled": false
}

<!-- .claude/rules/api-routes.md -->
---
description: API路由开发规则
globs: ["src/app/api/**/*.ts"]
---

# API路由规则
- 所有API路由必须有输入验证（使用zod）
- 错误处理使用统一的 errorResponse 函数
- 响应格式：{ success: boolean, data?: T, error?: string }
- 必须认证的路由使用 withAuth 中间件包装

<!-- .claude/rules/components.md -->
---
description: React组件开发规则
globs: ["src/components/**/*.tsx"]
---

# 组件规则
- 使用 "use client" 标记客户端组件
- Props使用 interface 定义
- 事件处理函数使用 handle 前缀
- 状态管理优先使用 useState，复杂场景用 zustand
- 每个组件对应一个 .test.tsx 测试文件

{
  "model": "claude-opus-4-6",
  "outputStyle": "concise",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"File: $CLAUDE_FILE_PATH\" with title \"Claude Code\"' 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          permission_mode: "plan"
          settings: |
            {
              "permissions": {
                "defaultMode": "plan",
                "deny": ["Bash", "Write", "Edit"]
              }
            }

# 验证配置文件存在且格式正确
find . -name "settings*.json" -o -name "CLAUDE*.md" -o -name "*.mcp.json" | \
  while read f; do
    echo "=== $f ==="
    if [[ "$f" == *.json ]]; then
      python3 -m json.tool "$f" > /dev/null && echo "✅ Valid JSON" || echo "❌ Invalid JSON"
    else
      head -3 "$f"
    fi
  done

=== ./CLAUDE.md ===
# 项目：Next.js电商平台
=== ./CLAUDE.local.md ===
# 个人项目偏好
=== .claude/settings.json ===
✅ Valid JSON
=== .claude/settings.local.json ===
✅ Valid JSON

{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "disableAutoMode": "disable",
    "deny": [
      "WebSearch",
      "WebFetch",
      "Bash(curl * | *)",
      "Bash(wget * | *)"
    ],
    "ask": [
      "Bash(*)"
    ]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "strictKnownMarketplaces": ["https://marketplace.example.com"],
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": false,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "github.com",
        "internal-npm.company.com"
      ],
      "allowLocalBinding": false
    }
  }
}

# macOS
defaults read com.anthropic.claude-code

# 在Claude Code中
/config
# 查看 "Managed Settings" 标签页

# 查看Claude Code实际加载的配置（需要开启verbose模式）
claude --verbose "check config"

# 检查各层级配置文件是否存在
echo "=== User Level ===" && cat ~/.claude/settings.json 2>/dev/null || echo "Not found"
echo "=== Project Level ===" && cat .claude/settings.json 2>/dev/null || echo "Not found"
echo "=== Local Override ===" && cat .claude/settings.local.json 2>/dev/null || echo "Not found"

flowchart TD
    A["配置行为异常"] --> B{"是权限问题?"}
    B -->|是| C["运行 /permissions"]
    C --> D["检查规则来源层级"]
    D --> E["调整对应层级配置"]
    B -->|否| F{"是Hook问题?"}
    F -->|是| G["检查 /hooks 菜单"]
    G --> H["验证matcher和命令"]
    H --> I["手动运行Hook命令测试"]
    F -->|否| J{"是环境变量?"}
    J -->|是| K["检查 settings.json env 字段"]
    K --> L["对比系统环境变量"]
    J -->|否| M["检查CLAUDE.md加载"]
    M --> N["确认文件位置和格式"]