1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

优先级从高到低：

① 系统托管（不可被任何层级覆盖）
   macOS:   /Library/Application Support/ClaudeCode/managed-settings.json
   Linux:   /etc/claude-code/managed-settings.json
   Windows: C:\Program Files\ClaudeCode\managed-settings.json
            HKLM\SOFTWARE\Policies\ClaudeCode（注册表）

② 命令行参数（临时会话级覆盖）

③ 本地项目（个人私有，git 忽略）
   <repo>/.claude/settings.local.json

④ 共享项目（团队共享，git 追踪）
   <repo>/.claude/settings.json

⑤ 用户全局（最低优先级）
   ~/.claude/settings.json

1
2

CLAUDE.md      → 目录向上遍历，沿途所有文件全部加载（越过 git root 继续）
settings.json  → 固定路径，不做任何目录遍历

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

权限控制完全依赖启动参数，三种模式：

  --approval-mode suggest    所有操作需用户确认（默认）
  --approval-mode auto-edit  文件编辑自动批准，shell 命令需确认
  --approval-mode full-auto  全自动执行（依赖 OS 沙箱隔离）

沙箱机制：
  macOS：Seatbelt（系统调用级别隔离）
  Linux：Docker 容器隔离

full-auto 模式：网络访问被完全禁止，文件系统受 OS 限制

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

加载顺序（优先级从低到高）：

① 远程组织配置（最低）
   .well-known/opencode（通过 HTTP 拉取，组织级默认值）

② 用户全局配置
   ~/.config/opencode/opencode.json

③ 环境变量指定路径
   $OPENCODE_CONFIG 指向的文件

④ 项目配置（从当前目录向上遍历查找，停在 git root）
   ./opencode.json

⑤ .opencode 目录（agents/, commands/ 等子目录）

⑥ 内联配置（最高）
   $OPENCODE_CONFIG_CONTENT 环境变量内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",            // Bash 命令，支持通配符
      "Bash(git commit *)",
      "Read(./src/**)",             // 文件读取，gitignore 风格
      "Read(~/data/work/**)",       // 波浪号路径（指定目录免确认）
      "Edit(./src/**/*.java)",      // 文件编辑
      "WebFetch(domain:github.com)", // 域名匹配
      "Glob(**/*.ts)",              // 文件搜索
      "Grep(./src/**)"              // 内容搜索
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env*)",              // 拒绝读取环境变量文件
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",           // 敏感操作需二次确认
      "Bash(docker *)",
      "Bash(kubectl *)"
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// opencode.json
{
  "permission": {
    // 工具级别全局设置
    "read":      "allow",
    "edit":      "allow",
    "glob":      "allow",
    "grep":      "allow",
    "list":      "allow",
    "webfetch":  "ask",
    "lsp":       "allow",

    // bash 细粒度规则（最后匹配生效）
    "bash": {
      "*":          "ask",      // 默认所有命令需确认
      "git *":      "allow",    // git 命令放行
      "npm run *":  "allow",    // npm 命令放行
      "rm *":       "deny",     // 拒绝 rm
      "curl *":     "deny"      // 拒绝 curl
    }
  }
}

1
2
3
4

# 无配置文件，仅启动参数
codex --approval-mode suggest    # 全部询问（默认）
codex --approval-mode auto-edit  # 文件编辑自动放行
codex --approval-mode full-auto  # 沙箱内全自动

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

数组类字段（跨层级合并，去重）：
  permissions.allow / deny / ask

示例：
  managed-settings.json:   allow: ["Bash(//opt/company-tools/*)"]
  ~/.claude/settings.json: allow: ["Bash(npm run *)", "Bash(mvn *)"]
  .claude/settings.json:   allow: ["Bash(git *)", "Read(./src/**)"]

  最终生效：
  allow: [
    "Bash(//opt/company-tools/*)",   ← 来自 managed
    "Bash(npm run *)",               ← 来自用户全局
    "Bash(mvn *)",                   ← 来自用户全局
    "Bash(git *)",                   ← 来自项目
    "Read(./src/**)"                 ← 来自项目
  ]

标量字段（高优先级完全覆盖低优先级）：
  model、theme 等

deny 的特殊地位：
  任何层级的 deny 均生效，低层级无法解除
  managed 层设置的 deny 不可被任何层级覆盖

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

~/.config/opencode/opencode.json（用户全局）：
{
  "permission": {
    "read":  "allow",
    "edit":  "allow",
    "bash": {
      "*":      "ask",
      "git *":  "allow"
    }
  }
}

./opencode.json（项目级）：
{
  "permission": {
    "webfetch": "deny",         // 项目级新增字段
    "bash": {
      "npm run *": "allow"      // 项目级追加规则
    }
  }
}

合并结果：
{
  "permission": {
    "read":     "allow",        // 来自全局
    "edit":     "allow",        // 来自全局
    "webfetch": "deny",         // 来自项目（新增）
    "bash": {
      "*":         "ask",       // 来自全局
      "git *":     "allow",     // 来自全局
      "npm run *": "allow"      // 来自项目（追加）
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

合并后的 bash 规则：
  "*":         "ask"
  "git *":     "allow"
  "npm run *": "allow"

执行 "git commit -m fix" 时：
  匹配 "*"       → ask
  匹配 "git *"   → allow    ← 最后匹配，最终生效 ✅

执行 "curl http://..." 时：
  匹配 "*"       → ask      ← 唯一匹配，最终生效 ✅

执行 "rm -rf /tmp" 时：
  匹配 "*"       → ask      ← 唯一匹配，最终生效 ✅

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "permission": {
    "bash": { "*": "ask", "git *": "allow" }   // 全局权限
  },
  "agent": {
    "reviewer": {
      "permission": {
        "read": "allow",
        "bash": "deny",    // 直接覆盖，全局的 git * allow 被完全忽略
        "edit": "deny"
      }
    }
  }
}

1
2
3
4
5
6
7

reviewer agent 最终权限：
  read: allow  ←  agent 定义
  bash: deny   ←  agent 定义（全局 git * allow 失效）
  edit: deny   ←  agent 定义

默认 agent 最终权限：
  bash: { "*": "ask", "git *": "allow" }  ← 使用全局规则

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

~/projects/
├── CLAUDE.md                          ✅ 指令文件，目录遍历自动加载
├── .claude/settings.json              ❌ 不会被加载（不在固定路径）
│
├── order-service/
│   ├── CLAUDE.md                      ✅ 指令文件，自动加载
│   └── .claude/
│       ├── settings.json              ✅ 项目级权限（团队共享）
│       └── settings.local.json        ✅ 本地个人权限（git 忽略）
│
└── notify-service/
    ├── CLAUDE.md                      ✅ 指令文件，自动加载
    └── .claude/
        └── settings.json              ✅ 项目级权限（团队共享）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(mvn *)",
      "Bash(npm run *)",
      "Read(~/data/work/**)",
      "Read(~/.claude/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(kubectl *)",
      "Bash(docker *)"
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "permissions": {
    "allow": [
      "Bash(java *)",
      "Bash(mvn spring-boot:run)",
      "Read(./src/**)",
      "Edit(./src/**)"
    ]
  }
}

1
2
3
4
5
6
7
8

{
  "permissions": {
    "allow": [
      "Bash(ssh *)",
      "Read(~/.ssh/config)"
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "permission": {
    "read":  "allow",
    "edit":  "allow",
    "bash": {
      "*":        "ask",
      "git *":    "allow",
      "mvn *":    "allow",
      "rm -rf *": "deny",
      "curl *":   "deny"
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "permission": {
    "bash": {
      "java *":             "allow",
      "mvn spring-boot:run": "allow"
    }
  },
  "agent": {
    "reviewer": {
      "permission": {
        "read": "allow",
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

Claude Code（首个匹配）：
  规则检查顺序：deny → ask → allow
  第一个匹配的规则立即生效，后续规则忽略

  陷阱示例：
    deny:  ["Bash(rm *)"]
    allow: ["Bash(rm -rf /tmp/*)"]   ← 永远不会生效（已被 deny 首先匹配）

  正确写法：把宽泛的 deny 放后面，具体的 allow 放前面
    allow: ["Bash(rm -rf /tmp/*)"]   ← 先匹配，放行 /tmp 下的删除
    deny:  ["Bash(rm *)"]            ← 再匹配其他 rm 命令

OpenCode（最后匹配）：
  越靠后的规则优先级越高，适合从宽泛默认逐步精细化

  示例：
    "bash": {
      "*":          "ask",           // 默认询问
      "rm *":       "deny",          // 拒绝 rm
      "rm /tmp/*":  "allow"          // 最后匹配：/tmp 下 rm 允许 ✅
    }