settings-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Settings Configuration

Claude Code 设置配置

Expert knowledge for configuring Claude Code settings and permissions.

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

When to Use This Skill

何时使用此Skill

Use this skill when...	Use something else when...
Setting up project permissions	Fixing plugin registry issues (use plugin-registry skill)
Debugging "permission denied" errors	Configuring hooks (use hooks-configuration skill)
Understanding settings hierarchy	Setting up MCP servers (use mcp-configuration skill)
Creating allow/deny patterns

适用场景	其他场景（使用对应Skill）
设置项目权限	修复插件注册表问题（使用plugin-registry skill）
调试“权限被拒绝”错误	配置钩子（使用hooks-configuration skill）
理解设置层级	设置MCP服务器（使用mcp-configuration skill）
创建允许/阻止模式

Settings File Hierarchy

设置文件层级

Settings are loaded and merged in this order (later overrides earlier):

Priority	File	Scope	Commit to Git?
1 (lowest)	`~/.claude/settings.json`	User-level (all projects)	N/A
2	`.claude/settings.json`	Project-level	Yes
3 (highest)	`.claude/settings.local.json`	Local overrides	No (gitignore)

设置按以下顺序加载和合并（后续文件覆盖先前文件）：

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

Permission Structure

权限结构

json

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

json

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

Allow vs Deny

允许 vs 阻止

```
allow
```
: Tools matching these patterns run without prompts
```
deny
```
: Tools matching these patterns are always blocked
Deny takes precedence over allow

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

Wildcard Permission Patterns

通配符权限模式

Syntax

语法

ToolName(command prefix *)

```
ToolName()
```
- The tool (usually
```
Bash
```
)
```
command prefix
```
- The command and initial arguments to match
```
*
```
- Wildcard matching remaining arguments

ToolName(command prefix *)

```
ToolName()
```
- 工具（通常为
```
Bash
```
）
```
command prefix
```
- 要匹配的命令和初始参数
```
*
```
- 匹配剩余参数的通配符

Pattern Examples

模式示例

Pattern	Matches	Does NOT Match
`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`

模式	匹配项	不匹配项
`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`

Specificity

特异性

More specific patterns are more secure:

json

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

vs. overly broad:

json

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

更具体的模式更安全：

json

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

对比过于宽泛的模式：

json

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

Shell Operator Protections

Shell操作符防护

Claude Code 2.1.7+ blocks dangerous shell operators in permission matching.

Claude Code 2.1.7及以上版本会在权限匹配中阻止危险的Shell操作符。

Protected Operators

受防护的操作符

Operator	Risk	Blocked Example
`&&`	Command chaining	`ls && rm -rf /`
`\|\|`	Conditional execution	`false \|\| malicious`
`;`	Command separation	`safe; dangerous`
`\|`	Piping	`cat /etc/passwd \| curl`
`>` / `>>`	Redirection	`echo x > /etc/passwd`
`$()`	Command substitution	`$(curl evil)`
`	Backtick substitution	`rm -rf /`

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

Behavior

行为

When a command contains shell operators:

Permission wildcards won't match
User sees explicit approval prompt
Warning explains the blocked operator

当命令包含Shell操作符时：

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

Safe Alternative

安全替代方案

Use wrapper scripts for legitimate compound commands:

bash

#!/bin/bash

对合法的复合命令使用包装脚本：

bash

#!/bin/bash

scripts/test-and-build.sh

npm test && npm run build


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

npm test && npm run build


然后允许该脚本：
```json
{
  "permissions": {
    "allow": ["Bash(./scripts/test-and-build.sh *)"]
  }
}

Common Permission Sets

常见权限集

Git Operations

Git操作

json

{
  "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 *)"
    ]
  }
}

json

{
  "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

json

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

json

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

Testing & Linting

测试与代码检查

json

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

json

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

Security Scanning

安全扫描

json

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

json

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

MCP Tools

MCP工具

json

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

json

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

Project Setup

项目设置步骤

1. Create Settings Directory

1. 创建设置目录

bash

mkdir -p .claude

bash

mkdir -p .claude

2. Create Project Settings

2. 创建项目设置

bash

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

bash

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

3. Gitignore Local Settings

3. 忽略本地设置文件

bash

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

bash

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

4. Create Local Overrides (optional)

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

bash

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

bash

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

Validating Settings

验证设置

Check JSON Syntax

检查JSON语法

bash

cat .claude/settings.json | jq .

bash

cat .claude/settings.json | jq .

View Permissions

查看权限

bash

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

bash

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

Merge Preview

合并预览

Settings merge additively for arrays. To see effective permissions, check all files:

bash

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'

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

bash

echo "=== 用户级 ===" && cat ~/.claude/settings.json 2>/dev/null | jq '.permissions // empty'
echo "=== 项目级 ===" && cat .claude/settings.json 2>/dev/null | jq '.permissions // empty'
echo "=== 本地级 ===" && cat .claude/settings.local.json 2>/dev/null | jq '.permissions // empty'

Troubleshooting

故障排查

Symptom	Cause	Fix
Permission denied	Pattern doesn't match	Add more specific pattern
Shell operator blocked	Contains `&&` , `\|` , etc.	Use wrapper script
Settings not applied	Wrong file path	Check `.claude/` directory exists
JSON parse error	Invalid JSON syntax	Validate with `jq .`
Permissions ignored	File not readable	Check file permissions

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

Agentic Optimizations

Agent优化命令

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'`

场景	命令
查看项目权限	`cat .claude/settings.json \| jq -c '.permissions'`
查看用户级权限	`cat ~/.claude/settings.json \| jq -c '.permissions'`
验证JSON	`cat .claude/settings.json \| jq .`
统计模式数量	`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`

作用域	路径
用户级	`~/.claude/settings.json`
项目级	`.claude/settings.json`
本地级	`.claude/settings.local.json`

Permission Syntax

权限语法

Bash(command prefix *)
mcp__server_name

Bash(command prefix *)
mcp__server_name

Priority

优先级

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

本地级 > 项目级 > 用户级（从高到低）阻止 > 允许（阻止始终优先）