理解 Claude Code 的安全机制：Sandbox、Trust 与 Approval

总结了「Claude Code」的安全机制。

目次

1. 1. 前言
2. 2. Sandbox - 限制可操作范围
3. 2-1. 什么是Sandbox
4. 2-2. 工作文件夹和保护文件
5. 2-3. 权限（Permissions）是什么
6. 2-4. 常见误解
7. 3. Trust - 启用项目特定设置
8. 3-1. 什么是Trust
9. 3-2. 常见误解
10. 4. Approval - 批准操作执行

1. 前言

Anthropic的「Claude Code」是一个能够自主进行程序创建、修改、测试和命令执行的AI编码代理。

由于AI会操作本地PC的文件并执行命令，因此存在误操作或安全风险。为此，Claude Code配备了限制AI操作并在必要时由用户授权的机制。

在实际使用Claude Code时，会遇到以下场景：

这些看起来像是类似的安全功能，但各自的作用不同。

本次将基于Anthropic的官方文档「Configure permissions」和「Configure the sandboxed Bash tool」，介绍Sandbox、Trust和Approval之间的区别。

2. Sandbox - 操作できる範囲を制限する

2-1. Sandboxとは

「Sandbox」（サンドボックス）は、Claude Codeが実行するコマンドに対して、ファイル操作やネットワーク通信などを制限する仕組みです。主にシェルコマンドを対象とし、ファイル編集ツールなどは別の仕組みで制御されます。

主に2種類の状態があります。

Claude Codeでは、Sandboxはデフォルトで無効です。通常の開発では、有効にすることをおすすめします。

将应用了沙箱限制的状态称为“沙箱内”，将不受该限制而执行命令的状态称为“沙箱外”。

2-2. 工作文件夹与受保护文件

“工作文件夹”是 Claude Code 进行操作的目标文件夹。在沙箱中，除了工作文件夹之外，临时文件夹等也可写入。

如果在 Claude Code 的 GUI 版中选择 my-app 文件夹，则 my-app 将成为工作文件夹。

启用沙箱后，原则上允许对工作文件夹内的内容进行写入。但是，即使在工作文件夹内，部分文件和文件夹的写入也会受到限制。

主要的保护对象如下所示。

在标准沙箱中，这些受保护对象禁止来自沙箱内命令的写入。

不过，并非所有以点开头的隐藏文件都会受到保护。例如，.env和.gitignore等会像普通文件一样被处理。

2-3. 权限（Permissions）是什么

“权限（Permissions）”是管理Claude Code所执行操作的允许、确认与禁止的机制。

沙箱主要限制Shell命令，而权限则涵盖对Read、Edit、Write等内置文件操作以及Shell命令等各类工具操作。

主要有三种规则。

Permissions 可以在 `~/.claude/settings.json` 等位置进行设置。

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Read(./src/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Bash(rm -rf *)"
    ]
  }
}

在此示例中，允许运行测试和读取 src 目录中的文件，对 git push 进行确认，并禁止读取 .env 文件和执行指定的删除命令。

当结合使用 Sandbox 和 Permissions 时，两者限制均会生效。不过，在 Sandbox 内执行的 shell 命令可根据配置省略 Permissions 的授权确认。

在日常开发中，无需从一开始就细致地配置 Permissions。

2-4. 常见的误解

误解1：在沙箱中无法执行命令
在沙箱中也可以执行命令。

例如，启用沙箱后，可以编辑工作文件夹中的文件并运行测试。但是，如果尝试进行被禁止的文件操作或通信，则会受到限制。

也就是说，沙箱内并非“禁止执行”，而是“在受限状态下执行”。

误解2：沙箱内指的是工作文件夹内部
沙箱内外表示的是否对命令应用了沙箱限制，而不是文件夹的位置。

例如，即使是对工作文件夹外部文件的操作，如果在沙箱内执行，写入也会受到限制。

误解3：无法访问工作文件夹之外的文件
在标准沙箱中，原则上禁止写入工作文件夹之外，但广泛允许读取。

因此，可能会访问其他项目的源代码或操作系统权限下可读取的机密文件。

仅选择工作文件夹并不能限制可读范围。

3. 信任 - 启用项目特定设置

3-1. 什么是信任

启动 Claude Code 时，系统有时会询问是否将工作文件夹“信任”（Trust）。

Trust是一种机制，用于决定是否启用Claude Code中那些扩大操作权限的项目特定设置等。

Claude Code的设置主要在以下三个地方进行管理。

根据信任状态的不同，区别如下。

项目特定的设置包括操作许可规则和额外的工作文件夹等。此外，即使未进行Trust，也有一些设置会被应用。

3-2. 常见的误解

误解1：Trust后，就能读写该文件夹
Trust本身不会授予文件读写权限。

实际的访问范围由沙盒、操作批准规则、操作系统权限等决定。

也就是说，“信任文件夹”和“允许访问文件夹”是不同的操作。

误解2：Trust后，沙盒限制会被解除
仅进行Trust并不会解除沙盒的限制。

但是，如果项目特定配置中包含以下指定，则需要注意。

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

启用这些设置后，指定的命令可能会在无需额外批准的情况下执行。但这并不会解除沙箱本身的限制。

也就是说，Trust 机制意味着接受项目所配置的安全设置。

误解三：如果不信任，就能安全运行
即使不信任，Claude Code 也并非无法访问所有文件。

Trust 主要用于决定是否启用特定于项目的操作许可规则等，而对文件的访问则受沙箱、操作审批规则以及操作系统权限等的限制。

此外，部分 Hooks 等在 Trust 之前也可能生效，因此对于从外部获取的项目需要格外注意。

4. 审批 - 批准执行操作

4-1. 什么是批准（Approval）

在 Claude Code 中，对于文件编辑或命令执行等操作，可能会要求用户进行“批准”（Approval）。

例如以下操作：

用户批准后，即可在已授权的范围内执行操作。

这是一种被称为“人在回路”（Human in the Loop）的安全设计，由人类对关键操作进行确认。

在Claude Code的GUI版本中，可以从以下模式中选择批准方式。

在常规开发中，Manual或Accept edits是基本选项。

4-2. Auto mode - AI自动批准

Claude Code还提供一种“Auto mode”（自动模式），由AI代替用户审查操作内容。

在常规的Approval中，由用户确认操作；而在Auto mode中，由另一套AI进行安全性判定处理，评估操作内容和风险，并判断是否可执行。

主要特点如下：

在Claude Code的GUI版本中，可以从输入框的批准模式中选择“自动”。

自动模式并非解除沙箱限制的功能，而是将通常由用户执行的批准判断部分委托给AI的机制。

不过，由于AI的判断并不总是正确的，因此在处理重要文件或认证信息的系统中使用时需谨慎。

4-3. 常见的误解

误解1：获得Approval后，沙箱的限制会被完全解除
Approval通常是对所请求操作的批准。
例如，即使批准了在沙箱外执行命令，也不会导致所有命令永久在沙箱外执行。
此外，根据操作系统或管理员策略，即使获得批准也可能无法执行。

误解2：在沙箱内允许的操作无需批准即可执行
即使在沙箱内被允许的操作，也可能因批准模式或命令规则等原因而需要批准。
也就是说，沙箱限制与Approval的判断并非一定是一一对应的关系。

5. Sandbox、Trust与Approval的关系

介绍结合这三种机制的具体示例。

在Claude Code中选择my-app作为工作文件夹，并按以下条件运行时的情形。

作業フォルダ：my-app
Sandbox：enabled
Trust：Trusted
Approval Mode：Manual
ネットワーク通信：禁止

在这种情况下，操作如下所示。

重要的是，并非因为信任了就能读写，而是由 Sandbox 或批准规则决定访问范围。

此外，Sandbox 内不允许的部分操作，可以通过 Approval 例外地执行。

实际的操作是否可行，还取决于操作系统权限、命令规则、管理员策略等因素。

6. 安全使用的基本设置

在常规的 Claude Code 开发中，推荐以下设置。

沙盒默认处于禁用状态，因此需要启用它。

Claude Code 的 GUI 版本允许从输入栏中选择批准模式。此外，可以通过以下配置文件启用沙盒：

・~/.claude/settings.json

{
  "sandbox": {
    "enabled": true
  }
}

这样可以限制命令的操作范围，并对需要的操作请求用户批准。如果希望在沙盒内无需批准即可执行命令，还可以设置 autoAllowBashIfSandboxed。

此外，根据需要还可以使用详细的安全设置。

在常规开发中，无需一开始就进行如此细致的配置。建议先理解沙箱（Sandbox）、信任（Trust）和审批（Approval），并在需要时再添加相关设置。

特别是对于从外部获取的项目并授予信任时，重要的是检查 .claude/settings.json 等文件中是否包含危险配置。