【Claude】权限被拒绝 (Permission Denied) 全场景排查 — 已解决

一键难忘

53人浏览 · 2026-07-01 11:03:44

一键难忘 · 2026-07-01 11:03:44 发布

【Claude】权限被拒绝 (Permission Denied) 全场景排查 — 已解决

适用版本：Claude Code v1.0.x 及以上
受影响场景：文件操作受限、命令执行被拒、工具调用失败、CI 环境权限冲突
阅读时长：约 25 分钟

1. 问题现象

1.1 典型问题表现

问题一：文件写入被拒绝

> 修改 src/config.py
[Claude 尝试编辑文件]
Error: Permission denied — Write(src/config.py) is not allowed
# Claude 无法修改文件

问题二：命令执行被拒绝

> 运行测试
[Claude 尝试执行 bash(npm test)]
Error: Permission denied — Bash(npm test) is not allowed
# 测试命令无法执行

问题三：CI 环境中权限提示阻塞

claude --print "修复 bug"
# Claude wants to run: bash(npm install)
# Allow? (y/n)
# CI 中无 TTY → 挂起等待

问题四：权限规则不生效

// .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(npm test*)"]
  }
}
// 但 Claude 仍然提示权限确认

问题五：子代理权限继承问题

# 主代理有权限，但子代理没有
> 使用 reviewer 子代理审查代码
[reviewer] Error: Permission denied — Read(src/secrets.yaml)
# 子代理继承了 deny 规则但没有 allow

2. 原理深挖：权限评估引擎

2.1 权限层级

┌─────────────────────────────────────────────────────┐
│              权限评估优先级 (从高到低)                │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Level 1: --dangerously-skip-permissions            │
│  → 跳过所有权限检查                                  │
│  → 仅限 CI/受信环境                                  │
│                                                     │
│  Level 2: deny 规则                                 │
│  → 明确禁止的操作                                    │
│  → 优先级最高（即使 allow 也无效）                    │
│                                                     │
│  Level 3: allow 规则                                 │
│  → 明确允许的操作                                    │
│  → 匹配则自动执行                                    │
│                                                     │
│  Level 4: 用户确认                                   │
│  → 不在 allow/deny 中的操作                          │
│  → 交互模式: 提示用户                                │
│  → Headless 模式: 拒绝                               │
│                                                     │
│  Level 5: 默认行为                                   │
│  → Read: 默认允许                                    │
│  → Write/Edit: 默认需确认                            │
│  → Bash: 默认需确认                                  │
│                                                     │
└─────────────────────────────────────────────────────┘

2.2 权限规则语法

规则格式: ToolName(pattern)

通配符:
  *     → 匹配任意
  **    → 递归匹配（路径）
  ?     → 匹配单个字符

示例:
  Read(**)              → 允许读取所有文件
  Read(src/**)          → 只允许读取 src/ 下
  Read(src/*.py)        → 只允许读取 src/ 下的 .py
  Bash(npm test*)       → 允许 npm test 及其参数
  Bash(git *)           → 允许所有 git 命令
  Write(src/**)         → 允许写入 src/ 下
  Write(.env*)          → 匹配 .env, .env.local 等
  Edit(tests/**)        → 允许编辑 tests/ 下

2.3 权限评估流程

Claude 要执行操作: Write(src/config.py)

评估步骤:
  1. 检查 --dangerously-skip-permissions
     → 如果设置，跳过检查，允许执行
  
  2. 检查 deny 规则
     deny: ["Write(.env*)", "Write(src/secrets/**)"]
     → src/config.py 不匹配任何 deny 规则
     → 继续
  
  3. 检查 allow 规则
     allow: ["Write(src/**)"]
     → src/config.py 匹配 Write(src/**)
     → ✅ 允许执行
  
  4. 如果不匹配 allow:
     → 交互模式: 提示用户 "Allow? (y/n)"
     → Headless 模式: 拒绝

2.4 配置文件优先级

配置加载顺序 (后者覆盖前者):

  1. ~/.claude/settings.json          (全局默认)
  2. ~/.claude/settings.local.json    (全局本地覆盖)
  3. .claude/settings.json            (项目级)
  4. .claude/settings.local.json      (项目本地覆盖)
  5. 企业策略配置 (企业版)

  权限合并:
    deny:  所有层级的 deny 合并（取并集）
    allow: 所有层级的 allow 合并（取并集）
    deny 优先于 allow

3. 根因分析：权限拒绝的七类根因

3.1 根因一：缺少 allow 规则

最常见原因。Claude 要执行的操作不在 allow 列表中，且未设置 --dangerously-skip-permissions。

3.2 根因二：deny 规则过于宽泛

deny: ["Bash(*)"] 会阻止所有命令执行，包括必要的测试和构建命令。

3.3 根因三：规则语法错误

Bash(npm test) 和 Bash(npm test*) 不同。前者精确匹配 npm test，后者匹配 npm test 及带参数的变体。

3.4 根因四：Headless 模式未跳过权限

claude -p 默认不跳过权限，遇到需要确认的操作会拒绝。

3.5 根因五：配置文件未加载

CLAUDE.md 或 settings.json 不在工作目录中，或文件名/路径不正确。

3.6 根因六：子代理权限未配置

子代理不自动继承主代理的 allow 规则，需要单独配置。

3.7 根因七：企业策略覆盖

企业版 Claude Code 可能有强制策略，覆盖用户级 allow 规则。

4. 多方案解决：从配置到绕行

4.1 方案一：正确配置权限规则

// .claude/settings.json — 完整权限配置示例
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Edit(src/**)",
      "Edit(tests/**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Write(docs/**)",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(npx tsc --noEmit)",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(python -m pytest*)",
      "Bash(go test*)",
      "Bash(cargo test*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(sudo *)",
      "Bash(curl *| sh)",
      "Bash(wget *| sh)",
      "Read(.env*)",
      "Read(.claude/secrets*)",
      "Read(**/id_rsa)",
      "Read(**/id_ed25519)",
      "Write(.env*)",
      "Write(.claude/secrets*)",
      "Write(**/id_rsa)",
      "Edit(.env*)",
      "Edit(.gitignore)",
      "Edit(package.json)",
      "Edit(tsconfig.json)"
    ]
  }
}

4.2 方案二：权限规则调试

#!/bin/bash
# debug-permissions.sh — 权限调试脚本

echo "=== 权限配置检查 ==="

# 检查所有配置文件
CONFIG_FILES=(
  "$HOME/.claude/settings.json"
  "$HOME/.claude/settings.local.json"
  ".claude/settings.json"
  ".claude/settings.local.json"
)

for config in "${CONFIG_FILES[@]}"; do
  if [ -f "$config" ]; then
    echo ""
    echo "📁 $config:"
    python3 -c "
import json
with open('$config') as f:
    data = json.load(f)
    perms = data.get('permissions', {})
    allow = perms.get('allow', [])
    deny = perms.get('deny', [])
    
    if allow:
        print('  Allow:')
        for rule in allow:
            print(f'    ✓ {rule}')
    if deny:
        print('  Deny:')
        for rule in deny:
            print(f'    ✗ {rule}')
    if not allow and not deny:
        print('  (无权限规则)')
" 2>/dev/null
  fi
done

# 检查命令行参数
echo ""
echo "命令行参数:"
if [ -n "$CLAUDE_SKIP_PERMISSIONS" ]; then
    echo "  ⚠ --dangerously-skip-permissions 已设置"
fi

4.3 方案三：权限规则生成器

#!/usr/bin/env python3
"""
根据项目类型自动生成权限规则
"""
import json
import os
from pathlib import Path

PROJECT_RULES = {
    "node": {
        "allow": [
            "Bash(npm test*)",
            "Bash(npm run lint*)",
            "Bash(npm run build*)",
            "Bash(npx tsc --noEmit)",
            "Bash(npx eslint*)",
            "Bash(npx prettier*)",
            "Bash(node *)"
        ],
        "deny": [
            "Bash(npm publish*)",
            "Write(package.json)",
            "Write(package-lock.json)"
        ]
    },
    "python": {

![配图](https://i-blog.csdnimg.cn/img_convert/634c9004eab189f8725326eeb1c32911.png)
        "allow": [
            "Bash(python *)",
            "Bash(python3 *)",
            "Bash(pip install*)",
            "Bash(pytest*)",
            "Bash(black *)",
            "Bash(ruff *)",
            "Bash(mypy *)"
        ],
        "deny": [
            "Bash(pip install --user*)",
            "Write(requirements.txt)"
        ]
    },
    "go": {
        "allow": [
            "Bash(go test*)",
            "Bash(go build*)",
            "Bash(go vet*)",
            "Bash(go fmt*)",
            "Bash(golangci-lint*)"
        ],
        "deny": [
            "Write(go.mod)",
            "Write(go.sum)"
        ]
    },
    "rust": {
        "allow": [
            "Bash(cargo test*)",
            "Bash(cargo build*)",
            "Bash(cargo check*)",
            "Bash(cargo clippy*)",
            "Bash(cargo fmt*)"
        ],
        "deny": [
            "Write(Cargo.toml)",
            "Write(Cargo.lock)"
        ]
    }
}

def detect_project_type(directory):
    """检测项目类型"""
    files = set(os.listdir(directory))
    
    if "package.json" in files:
        return "node"
    if "requirements.txt" in files or "pyproject.toml" in files:
        return "python"
    if "go.mod" in files:
        return "go"
    if "Cargo.toml" in files:
        return "rust"
    return "generic"

def generate_permissions(directory):
    """生成权限配置"""
    project_type = detect_project_type(directory)
    
    # 通用规则
    common = {
        "allow": [
            "Read(**)",
            "Edit(src/**)",
            "Edit(tests/**)",
            "Write(src/**)",
            "Write(tests/**)",
            "Write(docs/**)",
            "Bash(git status*)",
            "Bash(git diff*)",
            "Bash(git log*)"
        ],
        "deny": [
            "Bash(rm -rf*)",
            "Bash(git push --force*)",
            "Bash(sudo *)",
            "Read(.env*)",
            "Write(.env*)",
            "Edit(.env*)",
            "Read(**/id_rsa)",
            "Read(**/id_ed25519)",
            "Edit(.gitignore)"
        ]
    }
    
    # 合并项目特定规则
    project = PROJECT_RULES.get(project_type, {})
    
    merged = {
        "allow": list(set(common["allow"] + project.get("allow", []))),
        "deny": list(set(common["deny"] + project.get("deny", [])))
    }
    
    return {
        "permissions": merged
    }, project_type

# 使用
config, ptype = generate_permissions(".")
print(f"项目类型: {ptype}")
print(json.dumps(config, indent=2, ensure_ascii=False))

# 写入文件
with open(".claude/settings.json", "w") as f:
    json.dump(config, f, indent=2, ensure_ascii=False)
    print(f"\n✓ 已写入 .claude/settings.json")

4.4 方案四：Headless 模式权限处理

# 方案 A: 完全跳过权限 (CI/受信环境)
claude -p --dangerously-skip-permissions --max-turns 5 "task"

# 方案 B: 配置完整 allow 规则 (更安全)
# .claude/settings.json 已配置所有需要的 allow 规则
claude -p --max-turns 5 "task"
# → allow 规则匹配的操作自动执行
# → 不匹配的操作被拒绝 (Headless 无法交互)

# 方案 C: 混合模式 — CI 专用配置
cat > .claude/settings.ci.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm test*)",
      "Bash(npx tsc --noEmit)"
    ],
    "deny": [
      "Bash(rm*)",
      "Bash(git push*)",
      "Write(.env*)"
    ]
  }
}
EOF

# CI 中使用专用配置
CLAUDE_CONFIG_PATH=.claude/settings.ci.json claude -p "task"

4.5 方案五：子代理权限配置

// .claude/agents/coder.json — 子代理权限
{
  "name": "coder",
  "description": "编码子代理",
  "model": "claude-sonnet-4-20250514",
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Read(tests/**)",
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm test*)",
      "Bash(npx tsc --noEmit)"
    ],
    "deny": [
      "Bash(rm*)",
      "Read(.env*)",
      "Write(.env*)"
    ]
  },
  "maxTurns": 10
}

// .claude/agents/reviewer.json — 只读审查子代理
{
  "name": "reviewer",
  "description": "代码审查子代理（只读）",
  "model": "claude-opus-4-20250514",
  "permissions": {
    "allow": [
      "Read(**)"
    ],
    "deny": [
      "Write(**)",
      "Edit(**)",
      "Bash(*)"
    ]
  },
  "maxTurns": 5
}

4.6 方案六：权限问题应急处理

# 应急方案 1: 临时跳过权限 (不推荐用于生产)
claude --dangerously-skip-permissions "紧急修复"

# 应急方案 2: 扩展 allow 规则
# 快速添加允许规则
python3 -c "
import json
with open('.claude/settings.json', 'r+') as f:
    data = json.load(f)
    if 'permissions' not in data:
        data['permissions'] = {'allow': [], 'deny': []}
    data['permissions']['allow'].append('Bash(npm install*)')
    f.seek(0)
    json.dump(data, f, indent=2)
    f.truncate()
print('✓ 已添加 Bash(npm install*) 到 allow')
"

# 应急方案 3: 使用 /allowed 命令 (交互模式)
# 在 Claude Code 交互模式中:
# /allowed add Bash(docker *)
# /allowed list
# /allowed remove Bash(docker *)

# 应急方案 4: 临时配置文件
cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker *)",
      "Bash(docker-compose *)"
    ]
  }
}
EOF
# settings.local.json 不被 Git 跟踪，适合临时配置

4.7 方案七：权限审计

#!/usr/bin/env python3
"""
权限审计：分析权限配置的安全性
"""
import json
import re
from pathlib import Path

def audit_permissions(settings_path):
    """审计权限配置"""
    with open(settings_path) as f:
        data = json.load(f)
    
    perms = data.get("permissions", {})
    allow = perms.get("allow", [])
    deny = perms.get("deny", [])
    
    issues = []
    
    # 检查危险 allow 规则
    dangerous_allows = [
        (r"Bash\(\*\)", "允许所有 Bash 命令 — 极度危险"),
        (r"Bash\(sudo \*\)", "允许 sudo — 危险"),
        (r"Bash\(rm \*\)", "允许 rm — 危险"),
        (r"Write\(\*\*\)", "允许写入所有文件 — 危险"),
        (r"Edit\(\*\*\)", "允许编辑所有文件 — 危险"),
        (r"Read\(\*\*\)", "允许读取所有文件 — 注意 .env/密钥"),
    ]
    
    for pattern, warning in dangerous_allows:
        for rule in allow:
            if re.search(pattern, rule):
                issues.append(("HIGH", f"allow: {rule} — {warning}"))
    
    # 检查必要的 deny 规则
    recommended_denies = [
        r"Bash\(rm -rf",
        r"Bash\(sudo ",
        r"Bash\(git push --force",
        r"Read\(\.env",
        r"Write\(\.env",
        r"Read\(\*\*/id_rsa",
    ]
    
    for pattern in recommended_denies:
        found = any(re.search(pattern, d) for d in deny)
        if not found:
            issues.append(("MEDIUM", f"缺少 deny 规则: {pattern}"))
    
    # 检查 deny 与 allow 冲突
    for d in deny:
        for a in allow:
            if d == a:
                issues.append(("HIGH", f"allow 和 deny 冲突: {d}"))
    
    # 输出报告
    print(f"\n=== 权限审计报告 ({settings_path}) ===")
    print(f"Allow 规则: {len(allow)}")
    print(f"Deny 规则: {len(deny)}")
    
    if issues:
        print(f"\n发现问题: {len(issues)}")
        for severity, desc in issues:
            emoji = "🔴" if severity == "HIGH" else "🟡"
            print(f"  {emoji} [{severity}] {desc}")
    else:
        print("\n✓ 未发现安全问题")
    
    return issues

# 使用
audit_permissions(".claude/settings.json")
audit_permissions(".claude/settings.local.json")

5. 验证回归：权限配置验证

5.1 权限测试脚本

#!/bin/bash
# test-permissions.sh — 测试权限规则是否生效

echo "=== 权限规则测试 ==="

# 测试函数
test_permission() {
    local tool=$1
    local pattern=$2
    local expected=$3  # "allow" or "deny"
    
    echo -n "  $tool($pattern): "
    
    # 模拟权限检查 (通过 Claude Code 的 verbose 输出验证)
    # 实际使用时在 Claude Code 中执行对应操作
    echo "$expected"
}

# 读取配置
ALLOW_RULES=$(python3 -c "
import json
with open('.claude/settings.json') as f:
    data = json.load(f)
    for r in data.get('permissions', {}).get('allow', []):
        print(r)
")

DENY_RULES=$(python3 -c "
import json
with open('.claude/settings.json') as f:
    data = json.load(f)
    for r in data.get('permissions', {}).get('deny', []):
        print(r)
")

echo ""
echo "Allow 规则:"
echo "$ALLOW_RULES" | while read rule; do
    [ -n "$rule" ] && echo "  ✓ $rule"
done

echo ""
echo "Deny 规则:"
echo "$DENY_RULES" | while read rule; do
    [ -n "$rule" ] && echo "  ✗ $rule"
done

echo ""
echo "安全检查:"
echo "$DENY_RULES" | grep -q "rm -rf" && echo "  ✓ 已禁止 rm -rf" || echo "  ⚠ 未禁止 rm -rf"
echo "$DENY_RULES" | grep -q ".env" && echo "  ✓ 已保护 .env" || echo "  ⚠ 未保护 .env"
echo "$DENY_RULES" | grep -q "id_rsa" && echo "  ✓ 已保护 SSH 密钥" || echo "  ⚠ 未保护 SSH 密钥"

5.2 验证清单

#	验证项	预期	方法
1	allow 生效	操作自动执行	测试允许的命令
2	deny 生效	操作被拒绝	测试禁止的命令
3	deny 优先	deny 覆盖 allow	冲突规则测试
4	通配符	正确匹配	测试 * 和 **
5	Headless	不匹配被拒绝	claude -p 测试
6	子代理权限	独立配置	子代理操作测试
7	配置加载	正确合并	多配置文件
8	安全审计	无危险规则	审计脚本

6. 避坑最佳实践

6.1 权限配置原则

原则 1: 最小权限 — 只允许必要的操作
原则 2: deny 优先 — 先配置 deny 保护敏感资源
原则 3: 明确通配符 — * 和 ** 含义不同
原则 4: CI 用 skip — Headless 用 --dangerously-skip-permissions
原则 5: 子代理独立 — 每个子代理单独配置权限
原则 6: settings.local.json — 个人配置不入 Git
原则 7: 定期审计 — 用审计脚本检查安全性
原则 8: 保护密钥 — deny .env, id_rsa, credentials

6.2 权限规则模板

// 最小安全配置模板
{
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Read(tests/**)",
      "Read(docs/**)",
      "Edit(src/**)",
      "Write(src/**)",
      "Bash(npm test*)",
      "Bash(git status*)",
      "Bash(git diff*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(sudo *)",
      "Bash(git push --force*)",
      "Read(.env*)",
      "Read(**/id_rsa)",
      "Read(**/id_ed25519)",
      "Read(**/credentials*)",
      "Write(.env*)",
      "Write(.gitignore)",
      "Write(package.json)"
    ]
  }
}

6.3 常见陷阱

#	陷阱	后果	正确做法
1	Bash(npm test) 无通配符	带参数被拒	Bash(npm test*)
2	deny 太宽 Bash(*)	所有命令被拒	精确 deny
3	忘记 deny .env	密钥泄露	deny Read(.env*)
4	CI 无 skip-permissions	挂起	加 --dangerously-skip-permissions
5	子代理无权限	操作被拒	子代理单独配置
6	settings.json 不在 .claude/	不加载	路径正确
7	allow/deny 冲突	deny 优先	消除冲突
8	编辑 package.json	依赖被改	deny Edit(package.json)

7. 附录：权限规则速查表

7.1 工具-规则对照

工具	规则示例	说明
Read	`Read(src/**)`	读取 src/ 下所有文件
Write	`Write(src/**.py)`	写入 src/ 下的 .py 文件
Edit	`Edit(tests/**)`	编辑 tests/ 下文件
Bash	`Bash(npm test*)`	允许 npm test 及参数
Bash	`Bash(git *)`	允许所有 git 命令
WebFetch	`WebFetch(*)`	允许所有网络请求

7.2 通配符语义

通配符	匹配	示例
`*`	单层任意	`src/*` → src/a.py, 不匹配 src/dir/b.py
`**`	递归任意	`src/**` → src/a.py, src/dir/b.py
`?`	单字符	`file?.txt` → file1.txt, 不匹配 file12.txt

7.3 配置文件层级

文件	位置	Git 跟踪	用途
settings.json	~/.claude/	N/A	全局默认
settings.local.json	~/.claude/	N/A	全局个人
settings.json	.claude/	✅	项目共享
settings.local.json	.claude/	❌	项目个人