設定沙箱化 Bash 工具

• 啟用沙箱並選擇沙箱化命令的批准方式
• 設定命令可以到達的路徑和網路域
• 將沙箱化與權限規則和權限模式結合
• 在整個組織中強制執行沙箱化，使用受管設定

​

開始使用

/sandbox

​

設定 Linux 和 WSL2

• bubblewrap：無特權沙箱化工具，強制執行檔案系統隔離
• socat：用於通過沙箱代理路由網路流量的中繼

sudo apt-get install bubblewrap socat

sudo dnf install bubblewrap socat

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

sudo systemctl reload apparmor

​

沙箱模式

• 明確的 deny rules 始終被尊重
• 針對 /、您的主目錄或其他關鍵系統路徑的 rm 或 rmdir 命令仍然會觸發權限提示
• Ask rules 適用於回退到常規權限流程的命令

​

設定沙箱化

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}

​

沙箱化如何運作

​

檔案系統隔離

• 預設寫入行為：對目前工作目錄及其子目錄的讀取和寫入存取
• 預設讀取行為：對整個電腦的讀取存取，除了某些被拒絕的目錄。請注意，此預設仍允許讀取認證檔案，例如 ~/.aws/credentials 和 ~/.ssh/。將它們新增到 denyRead 以阻止它們。
• 被阻止的存取：無法在沒有明確權限的情況下修改目前工作目錄外的檔案，包括 shell 配置檔案（例如 ~/.bashrc）和 /bin/ 中的系統二進位檔案
• Git worktrees：當工作目錄是連結的 git worktree 時，沙箱也允許寫入主儲存庫的共享 .git 目錄，以便 git commit 等命令可以更新 refs 和索引。對該目錄內的 hooks/ 和 config 的寫入仍然被拒絕。
• 可配置：通過設定定義自訂允許和拒絕的路徑

​

網路隔離

• 域名限制：沒有預先允許的域名。命令首次需要新的域名時，Claude Code 會提示批准。使用 allowedDomains 預先允許域名以避免提示。
• 受管鎖定：如果在受管設定中設定了 allowManagedDomainsOnly，非允許的域名會自動被阻止而不是提示，只有來自受管設定的 allowedDomains 被尊重。
• 自訂代理支援：進階使用者可以在出站流量上實施自訂規則
• 全面覆蓋：限制適用於所有指令碼、程式和由命令產生的子流程

​

作業系統級別的強制執行

• macOS：使用 Seatbelt 進行沙箱強制執行
• Linux：使用 bubblewrap 進行隔離
• WSL2：使用 bubblewrap，與 Linux 相同

​

沙箱化與權限和權限模式的關係

​

權限規則

• 權限規則控制 Claude Code 可以使用哪些工具，並在任何工具執行之前進行評估。它們適用於所有工具：Bash、Read、Edit、WebFetch、MCP 和其他工具。
• 沙箱化提供作業系統級別的強制執行，限制 Bash 命令在檔案系統和網路級別可以存取的內容。它僅適用於 Bash 命令及其子流程。

​

權限模式

​

為您的組織設定沙箱

​

使用受管設定強制執行沙箱化

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

• failIfUnavailable：缺少的依賴項（例如 Linux 上的 bubblewrap）會阻止 Claude Code 啟動，而不是顯示警告並回退到未沙箱化執行
• allowUnsandboxedCommands: false：dangerouslyDisableSandbox 逃生艙被忽略，因此在沙箱下失敗的命令無法在其外重試

​

防止開發人員擴大策略

​

自訂代理配置

• 解密和檢查 HTTPS 流量
• 應用自訂過濾規則
• 記錄所有網路請求
• 與現有安全基礎設施整合

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

​

故障排除

• 命令因主機不允許錯誤而失敗：許多 CLI 工具需要到達特定主機。在提示時授予權限會將主機新增到您的允許清單，以便工具在將來在沙箱內執行。
• jest 掛起或失敗：watchman 與沙箱不相容。改為執行 jest --no-watchman。
• Go 型 CLI 在 macOS 上 TLS 驗證失敗：gh、gcloud 和 terraform 等工具在 Seatbelt 下可能無法進行 TLS 驗證。在 excludedCommands 中列出這些工具以在沙箱外執行它們。如果您使用 httpProxyPort 與 MITM 代理和自訂 CA，請改為將 enableWeakerNetworkIsolation 設定為 true。
• docker 命令失敗：docker 與沙箱不相容。將 docker * 新增到 excludedCommands 以在沙箱外執行它。
• Bubblewrap 在容器內啟動失敗：在無特權容器中，bubblewrap 無法掛載新的 /proc 檔案系統。將 enableWeakerNestedSandbox 設定為 true，以便內部沙箱綁定掛載容器的現有 /proc。僅在外部容器已提供您需要的隔離邊界時使用此設定，因為它向沙箱化命令公開流程資訊，新的 /proc 掛載會隱藏。
• Linux 上的 Seccomp 過濾器：seccomp 過濾器是阻止 Unix 域套接字所必需的。/sandbox 中的 Dependencies 標籤顯示它是否可用。如果缺少，請執行 npm install -g @anthropic-ai/sandbox-runtime 安裝幫助程式。
• --dangerously-skip-permissions 以 root 身份失敗：在 Linux 和 macOS 上以 root 身份或通過 sudo 執行時，此旗標被阻止，因為 root 存取加上沒有權限提示可以修改系統上的任何檔案或服務。檢查在識別的沙箱內自動跳過。若要在容器中自主執行，請使用 dev container 配置，它以非 root 使用者身份執行 Claude Code。

​

限制

​

安全限制

• 網路過濾：網路過濾系統通過限制流程允許連接的域名來運作。內建代理不終止或對出站流量執行 TLS 檢查，因此加密連接的內容不被檢查。您負責確保只有受信任的域名在您的策略中被允許。

• 通過 Unix 套接字的特權提升：allowUnixSockets 配置可能會無意中授予對強大系統服務的存取，這可能導致沙箱繞過。例如，允許存取 /var/run/docker.sock 有效地通過 Docker 套接字授予對主機系統的存取。仔細考慮您通過沙箱允許的任何 Unix 套接字。
• 檔案系統權限提升：過於寬泛的檔案系統寫入權限可能導致特權提升攻擊。允許寫入包含 $PATH 中可執行檔案的目錄、系統配置目錄或使用者 shell 配置檔案（例如 .bashrc 或 .zshrc）可能導致當其他使用者或系統流程存取這些檔案時在不同安全上下文中執行程式碼。
• Linux 沙箱強度：Linux 實現提供強大的檔案系統和網路隔離，但包含一個 enableWeakerNestedSandbox 模式，使其能夠在 Docker 環境中工作而無需特權命名空間，或在 Linux 主機上禁用無特權使用者命名空間的情況下。此選項大大削弱了安全性，應僅在其他隔離被強制執行時使用。
• 設定檔案受保護：沙箱自動拒絕對 Claude Code 的 settings.json 檔案在每個範圍和受管設定目錄的寫入存取，因此沙箱化命令無法修改其自己的策略。

​

平台和工具相容性

• 平台支援：支援 macOS、Linux 和 WSL2。不支援 WSL1 和原生 Windows。
• 效能開銷：最小，但某些檔案系統操作可能稍慢。
• 工具相容性：某些需要特定系統存取模式的工具可能需要配置調整，或可能需要在沙箱外執行。

​

範圍

• 內建檔案工具：Read、Edit 和 Write 直接使用權限系統，而不是通過沙箱執行。請參閱 permissions。
• 電腦使用：當 Claude 打開應用程式並控制您的螢幕時，它在您的實際桌面上執行，而不是在隔離環境中。每個應用程式的權限提示控制每個應用程式。請參閱 CLI 中的電腦使用 或 Desktop 中的電腦使用。
• 環境變數：沙箱化 Bash 命令預設繼承父流程環境，包括在那裡設定的任何認證。若要從子流程中去除 Anthropic 和雲端提供商認證，請設定 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB。
• 子代理：subagents 在與父工作階段相同的流程中執行，並使用相同的沙箱配置。當在父工作階段中啟用沙箱化時，子代理內的 Bash 命令被沙箱化。

​

另請參閱

• Sandbox environments：比較內建沙箱與開發容器、容器和虛擬機
• Security：全面的安全功能和最佳實踐
• Permissions：權限配置和存取控制
• Settings：完整配置參考
• CLI reference：命令列選項