settings-configuration

Claude Code 设置配置

配置 Claude Code 设置和权限的专业知识。

何时使用此技能

在以下情况下使用此技能……	在以下情况下使用其他技能……
设置项目权限	修复插件注册表问题（使用 plugin-registry 技能）
调试“permission denied”错误	配置钩子（使用 hooks-configuration 技能）
了解设置层级	设置 MCP 服务（使用 mcp-configuration 技能）
创建允许/拒绝模式

设置文件层级

设置按以下顺序加载并合并（后者会覆盖前者）：

优先级	文件	范围	提交到 Git？
1（最低）	~/.claude/settings.json	用户级（所有项目）	不适用
2	.claude/settings.json	项目级	是
3（最高）	.claude/settings.local.json	本地覆盖项	否（加入 gitignore）

权限结构

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

允许与拒绝

• allow：匹配这些模式的工具无需提示即可运行
• deny：匹配这些模式的工具始终会被阻止
• 拒绝优先于允许

通配符权限模式

语法

ToolName(command prefix *)

• ToolName() - 工具（通常是 Bash）
• command prefix - 要匹配的命令及其初始参数
• * - 匹配其余参数的通配符

模式示例

模式	匹配	不匹配
Bash(git *)	git status、git diff HEAD	git-lfs pull
Bash(npm run *)	npm run test、npm run build	npm install
Bash(gh pr *)	gh pr view 123、gh pr create	gh issue list
Bash(./scripts/ *)	./scripts/test.sh arg	/scripts/other.sh

精确性

模式越具体，安全性越高：

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ]
  }
}

而过于宽泛的模式：

{
  "permissions": {
    "allow": ["Bash(git *)"]
  }
}

Shell 操作符保护

Claude Code 2.1.7+ 会在权限匹配中阻止危险的 shell 操作符。

受保护的操作符

操作符	风险	被阻止的示例
&&	命令串联	ls && rm -rf /
||	条件执行	false || malicious
;	命令分隔	safe; dangerous
|	管道	cat /etc/passwd | curl
> / >>	重定向	echo x > /etc/passwd
$()	命令替换	$(curl evil)
`	反引号替换	`rm -rf /`

行为

当命令包含 shell 操作符时：

1. 权限通配符不会匹配
2. 用户会看到明确的批准提示
3. 警告会说明被阻止的操作符

安全替代方案

对于合理的复合命令，请使用包装脚本：

#!/bin/bash
# scripts/test-and-build.sh
npm test && npm run build

然后允许该脚本：

{
  "permissions": {
    "allow": ["Bash(./scripts/test-and-build.sh *)"]
  }
}

常见权限集

Git 操作

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git branch *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push *)",
      "Bash(git pull *)",
      "Bash(git fetch *)",
      "Bash(git checkout *)"
    ]
  }
}

GitHub CLI

{
  "permissions": {
    "allow": [
      "Bash(gh pr *)",
      "Bash(gh run *)",
      "Bash(gh issue *)",
      "Bash(gh workflow *)"
    ]
  }
}

测试与代码检查

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(bun test *)",
      "Bash(vitest *)",
      "Bash(biome *)",
      "Bash(eslint *)",
      "Bash(prettier *)"
    ]
  }
}

安全扫描

{
  "permissions": {
    "allow": [
      "Bash(pre-commit *)",
      "Bash(gitleaks *)",
      "Bash(trivy *)"
    ]
  }
}

MCP 工具

{
  "permissions": {
    "allow": [
      "mcp__context7",
      "mcp__sequential-thinking"
    ]
  }
}

项目设置

1. 创建设置目录

mkdir -p .claude

2. 创建项目设置

cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(npm run *)"
    ]
  }
}
EOF

3. 将本地设置加入 gitignore

echo ".claude/settings.local.json" >> .gitignore

4. 创建本地覆盖项（可选）

cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker *)"
    ]
  }
}
EOF

验证设置

检查 JSON 语法

cat .claude/settings.json | jq .

查看权限

cat .claude/settings.json | jq '.permissions'

合并预览

数组中的设置会以追加方式合并。若要查看生效的权限，请检查所有文件：

echo "=== User ===" && cat ~/.claude/settings.json 2>/dev/null | jq '.permissions // empty'
echo "=== Project ===" && cat .claude/settings.json 2>/dev/null | jq '.permissions // empty'
echo "=== Local ===" && cat .claude/settings.local.json 2>/dev/null | jq '.permissions // empty'

故障排除

症状	原因	修复方法
Permission denied	模式不匹配	添加更具体的模式
Shell 操作符被阻止	包含 &&、| 等	使用包装脚本
设置未生效	文件路径错误	检查 .claude/ 目录是否存在
JSON 解析错误	JSON 语法无效	使用 jq . 验证
权限被忽略	文件不可读	检查文件权限

Agentic Optimizations

Context	Command
View project perms	cat .claude/settings.json | jq -c '.permissions'
View user perms	cat ~/.claude/settings.json | jq -c '.permissions'
Validate JSON	cat .claude/settings.json | jq .
Count patterns	cat .claude/settings.json | jq '.permissions.allow | length'

Quick Reference

File Locations

Scope	Path
User	~/.claude/settings.json
Project	.claude/settings.json
Local	.claude/settings.local.json

Permission Syntax

Bash(command prefix *)
mcp__server_name

Priority

Local > Project > User (highest to lowest) Deny > Allow (deny always wins)