設定沙箱化 Bash 工具

​

開始使用

/sandbox

claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'

​

設定 Linux 和 WSL2

• bubblewrap：強制檔案系統隔離的無特權 sandboxing 工具
• socat：用於透過 sandbox 代理路由網路流量的中繼

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

​

Sandbox 模式

​

自動允許模式

• 明確的拒絕規則始終受到尊重
• 針對關鍵路徑的 rm 或 rmdir 命令仍會進行一般權限流程
• 內容範圍的詢問規則（例如 Bash(git push *)）仍會強制提示，即使是 sandboxed 命令
• 裸 Bash 詢問規則或等效的 Bash(*) 形式會被跳過以執行 sandboxed 的命令；它仍然適用於回退到一般權限流程的命令。在計畫模式中，規則不會被跳過：它會提示 sandboxed 命令，包括唯讀命令。在 v2.1.212 之前，跳過也適用於計畫模式

​

一般權限模式

​

Unsandboxed 重試逃生艙

• 背景工作階段：嚴格 sandbox 模式也涵蓋 shell 模式命令
• Linux 工作階段，設定了 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB：每個命令都 sandboxed 執行，包括 shell 模式命令

​

暫存目錄

​

設定沙箱化

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

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

​

停用檔案系統隔離

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "disabled": true
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

​

哪些設定可以停用它

• 使用者設定、受管設定和 --settings CLI 旗標可以設定它。.claude/settings.json 和 .claude/settings.local.json 中的專案設定不能，因此簽出的專案無法關閉檔案系統隔離。
• 當受管設定配置 sandbox.filesystem 時，或列出任何 sandbox.credentials.files 項目且 "mode": "deny" 時，僅受管設定可以設定該鍵。這保持管理員部署的檔案系統限制有效；若要放鬆此類部署，請在受管設定中設定 "disabled": true。
• 當設定 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 時，Claude Code 會忽略來自每個來源（包括受管設定）的 filesystem.disabled，並保持檔案系統隔離開啟。

​

檔案系統隔離關閉時的變更

• 沙箱化命令繼承您的 shell 的 $TMPDIR 而不是工作階段暫存目錄，因為每個暫存目錄都是可寫的，Claude Code 不再將命令重定向到工作階段目錄。 在 Linux 上，變數通常在父 shell 中未設定，因此它可以在沙箱化命令內展開為空；Claude Code 告訴 Claude 通過其 Bash 工具指導使用 mktemp -d 建立暫存目錄，而不是依賴 $TMPDIR。
• autoAllowBashIfSandboxed 仍預設為 true，因此沙箱化命令繼續執行而不提示。設定為 false 以提示沙箱化命令。

​

保護認證

{
  "sandbox": {
    "enabled": true,
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "deny" },
        { "path": "~/.ssh", "mode": "deny" }
      ],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "deny" },
        { "name": "NPM_TOKEN", "mode": "deny" }
      ]
    }
  }
}

• 專案或本機設定：Claude Code 不應用其任何 credentials 項目。需要 Claude Code v2.1.246 或更新版本。
• 使用者設定：Claude Code 仍應用 ~/.claude/settings.json 中的 deny 項目，並保持其檔案 mask 項目作為限制，但放棄其環境變數 mask 項目。

​

遮罩認證

​

遮罩環境變數

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com", "registry.npmjs.org"]
    },
    "credentials": {
      "envVars": [
        { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },
        { "name": "NPM_TOKEN", "mode": "mask" }
      ]
    }
  }
}

• network.allowedDomains：括號形式網域清單使用，例如 "[::1]"。代理檢查此清單以允許連接。
• injectHosts：其規範壓縮形式中的裸地址，例如 "::1" 或 "2001:db8::1"。代理將每個項目與連接的裸目的地地址進行匹配，忽略連接埠，因此括號、區域 ID 或不同壓縮拼寫永遠不會匹配，代理永遠不會在那裡注入認證。

• extract：Claude Code 在整個值上應用的正規表達式，僅替換每個匹配的第 1 組捕獲的文字，因此解析值的工具（例如 DATABASE_URL 連接字串）在沙箱內仍然有效。模式必須包含至少一個捕獲組。
• onExtractNoMatch 控制模式匹配無內容時發生的情況：
  • warn（預設）警告並無遮罩地傳遞變數
  • deny 在沙箱內取消設定變數
  • error 停止沙箱設定，直到您修復配置
• decode: "jwt"：用於保存 JSON Web Token (JWT) 的變數。Claude Code 驗證值是 JWT 並將其替換為結構上有效的假令牌，因此沙箱內解碼令牌的程式碼繼續工作。新增 maskClaims 以列出要個別遮罩的頂級承載聲明，而不是替換整個令牌；其他聲明保持可讀。當值未驗證為 JWT 或沒有列出的聲明匹配時，Claude Code 無遮罩地傳遞變數並發出警告。decode 無法與 extract 結合。

​

重新簽署 AWS 請求

{
  "sandbox": {
    "credentials": {
      "awsPairs": [
        {
          "accessKeyIdVar": "MY_KEY_ID",
          "secretAccessKeyVar": "MY_SECRET_KEY",
          "sessionTokenVar": "MY_SESSION_TOKEN"
        }
      ]
    }
  }
}

• accessKeyIdVar 和 secretAccessKeyVar 命名保存存取鍵 ID 和機密鍵的遮罩 envVars 項目。可選的 sessionTokenVar 命名保存臨時認證工作階段令牌的項目；設定時，代理在重新簽署的請求上發送真實令牌作為 x-amz-security-token。
• 每個命名的變數必須是遮罩其整個值的 mask 項目，沒有 extract 或 decode。
• 代理在存取鍵 ID 項目的 injectHosts 中列出的主機上重新簽署請求。
• 在配對中命名任何常規變數會替換自動配對。

​

遮罩認證檔案

• Linux 和 WSL2：沙箱化命令讀取檔案的哨兵複本，一個機密被替換為佔位符值的替代品，沙箱代理在出站時替換真實值。
• macOS：沙箱化命令無法讀取列出的檔案。Claude Code 不建立哨兵複本，不在出站時替換任何內容，因此使用檔案進行身份驗證的工具在沙箱內不工作，與 deny 相同的效果。與 deny 項目不同，讀取區塊即使在您停用檔案系統隔離時也保持有效。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "tlsTerminate": {},
      "allowedDomains": ["*.github.com"]
    },
    "credentials": {
      "files": [
        {
          "path": "~/.config/gh/hosts.yml",
          "mode": "mask",
          "extract": "oauth_token:\\s*(\\S+)",
          "injectHosts": ["api.github.com"]
        }
      ]
    }
  }
}

• onExtractNoMatch 控制匹配在檔案中找不到要遮罩的內容時發生的情況：
  • warn（預設）警告並跳過項目，因此沙箱化命令可以無遮罩地讀取真實檔案。預設適合可能合法不存在的認證；如果機密可能存在但模式可能遺漏它，使用 deny
  • deny 使檔案無法讀取
  • error 停止沙箱設定，直到您修復配置
  每當讀取區塊不會被強制執行時，Claude Code 將 deny 視為 error：當您停用檔案系統隔離時，以及當任何設定來源的 filesystem.allowRead 項目重新開啟檔案的路徑時。
• maskDuplicates 也替換每個遮罩認證值的逐字複本，一個 extract 捕獲或 decode 驗證的令牌，在匹配跨度外找到，用於在匹配無法到達的地方重複的機密。它匹配原始子字串，因此短或常見值會被替換到處出現；為長、高熵機密保留它。預設：false。

​

沙箱隔離的運作方式

​

檔案系統隔離

• 預設寫入行為：對目前工作目錄及其子目錄、任何使用 --add-dir、/add-dir 或 permissions.additionalDirectories 新增的目錄，以及 $TMPDIR 指向的工作階段暫存目錄具有讀寫存取權限
• 預設讀取行為：對整個電腦具有讀取存取權限，除了某些被拒絕的目錄。請注意，此預設仍允許讀取認證檔案，例如 ~/.aws/credentials 和 ~/.ssh/。使用 sandbox.credentials 來阻止讀取這些檔案並取消設定祕密環境變數，或將路徑新增至 denyRead。
• 被阻止的存取：無法修改工作目錄、新增的目錄和工作階段暫存目錄外的檔案，除非有明確的權限，包括 shell 設定檔案（例如 ~/.bashrc）和 /bin/ 中的系統二進位檔
• Git worktrees：當工作目錄是連結的 git worktree 時，沙箱也允許寫入主儲存庫的共用 .git 目錄，以便 git commit 等命令可以更新參考和索引。對該目錄內的 hooks/ 和 config 的寫入仍被拒絕。
• 可設定：透過設定定義自訂允許和拒絕的路徑

​

受保護的路徑

• 在您的工作目錄及其上方的目錄中：.claude 設定檔案、.claude/skills、.claude/agents、.claude/commands 和 .claude/hooks 目錄、.mcp.json，以及 Claude Code 自行執行的檔案，例如 .claude/workflows 和 .claude/scheduled_tasks.json
• 僅在您的工作目錄中：shell 啟動檔案，例如 .bashrc 和 .zshrc、.gitconfig、.vscode 和 .idea 目錄，以及 .git 內的 hooks 和 config
• 會將您的工作目錄轉變為裸 git 儲存庫的檔案：頂層的 HEAD、objects 和 refs，加上 HEAD 旁邊的 config 和 hooks。即使沒有 HEAD，名為 config 的檔案也被拒絕。在 Linux 和 WSL2 上，當沙箱化命令執行時，沙箱會刪除出現的頂層 HEAD 檔案或 objects 或 refs 目錄
• 在 ~/.claude 中，或 CLAUDE_CONFIG_DIR 指向的目錄中：其大部分內容，加上 ~/.claude.json 和 .credentials.json 認證存放區

​

網路隔離

• 網域限制：Claude Code 預設不預先允許任何網域。命令首次需要新網域時，Claude Code 會提示批准；在自動模式中，Claude 改為在命令本身上命名命令需要的主機，根據每個命令允許的網域。
• 批准選擇：如果您在提示時選擇「是」，Claude Code 會在目前工作階段的其餘時間允許該主機，並且不會再次提示稍後連線到同一主機。如果您選擇「是，以後不要再問」，Claude Code 會將 WebFetch(domain:...) 允許規則儲存到您的本機設定，以便該主機在未來工作階段中保持允許。
• 預先允許的網域：使用 allowedDomains 預先允許網域以完全避免提示。Claude Code 也預先允許來自 WebFetch(domain:...) 允許規則的網域，如權限規則中所述。
• 嚴格允許清單：如果您在使用者、受管理或 CLI --settings 設定中將 strictAllowlist 設定為 true，Claude Code 會拒絕沙箱化命令存取允許清單外的任何主機，而不是提示。允許清單與沙箱以其他方式提示的清單相同：allowedDomains 加上來自 WebFetch(domain:...) 允許規則的網域，或當設定 allowManagedDomainsOnly 時僅受管理設定項目。Claude Code 僅對沙箱化命令強制執行此操作；進程內工具（例如 WebFetch）仍遵循其權限規則。在儲存庫的 .claude/settings.json 或 .claude/settings.local.json 中設定它沒有效果。需要 Claude Code v2.1.219 或更新版本。
• 受管理的鎖定：如果在受管理設定中設定了 allowManagedDomainsOnly，非允許的網域會自動被阻止而不是提示，並且僅受管理設定中的 allowedDomains 和 WebFetch(domain:...) 允許規則被接受。
• 公司代理：當您的網路要求出站流量通過公司代理時，請在設定的 env 區塊中設定 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY，如代理設定所述，以便背景代理也能取得它們，或在您啟動 Claude Code 的環境中設定。Claude Code 強制執行網域允許清單，然後透過該上游代理隧道允許的連線。
• 自訂代理支援：進階使用者可以在出站流量上實施自訂規則
• 全面涵蓋：限制適用於命令產生的所有指令碼、程式和子程序

​

自動模式中的每個命令允許的網域

​

網域清單中的 IPv6 位址

• 拒絕清單：Claude Code 拒絕項目解析為的每個讀法，所以無論您的意思是哪個讀法都被阻止。對於沒有可解析讀法的項目，Claude Code 不阻止任何內容。
• 允許清單：Claude Code 永遠不允許超過您寫的內容。當該讀法乾淨地解析時，它會將模稜兩可的項目重寫為其主機和連接埠讀法，並可能完全刪除項目，而不是擴大允許清單。

​

作業系統層級強制執行

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

​

沙箱隔離如何與權限和權限模式相關

​

權限規則

• 權限規則控制 Claude Code 可以使用哪些工具，並在任何工具執行前進行評估。它們適用於每個工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒絕或詢問規則無法阻止 EndConversation，而其他任何工具仍然存在。
• 沙箱隔離提供作業系統層級的強制執行，限制 shell 命令在檔案系統和網路層級可以存取的內容。它僅適用於 Bash、PowerShell 和 Monitor 命令及其子程序。

​

權限模式

​

為您的組織設定沙箱

​

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

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

• failIfUnavailable：缺少的依賴項（例如 Linux 上的 bubblewrap）會阻止 Claude Code 啟動，而不是顯示警告並回退到未沙箱化執行
• allowUnsandboxedCommands: false：Claude Code 忽略 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。
• open、osascript 或瀏覽器型驗證流程在 macOS 上因錯誤 -600 而失敗：沙箱預設會阻止 Apple Events。在您的使用者、受管理或 CLI 設定中將 allowAppleEvents 設定為 true 以允許它們。專案設定會被忽略此金鑰。啟用它會移除程式碼執行隔離，因為沙箱化命令之後可以啟動其他應用程式而不進行沙箱化，無需使用者提示，並向執行中的應用程式傳送 AppleScript 命令，受限於 macOS 自動化同意提示 (TCC)。或者，將命令新增到 excludedCommands。
• docker 命令失敗：docker 與沙箱不相容。將 docker * 新增到 excludedCommands。
• pbcopy、xclip 或 wl-copy 不會更新剪貼簿：這些剪貼簿公用程式可能無法從沙箱內到達系統剪貼簿，在這種情況下，傳送給它們的文字不會到達。 若要將 Claude 的輸出放在您的剪貼簿上，請要求 Claude 在其回應中列印它，然後執行 /copy。/copy 從 Claude Code 程序而不是從沙箱化命令寫入剪貼簿。 當 Claude 將文字傳送給這些工具之一時，將工具新增到 excludedCommands 本身不會將該呼叫從沙箱中取出。
• git 命令因 unable to unlink old 而失敗：git merge、git checkout 和類似命令在需要取代沙箱拒絕寫入的檔案時以這種方式失敗，無論該檔案是在 受保護路徑 下（例如 .claude/skills）、在您的 denyWrite 項目之一下，還是完全在沙箱允許命令寫入的目錄之外。在 Linux 和 WSL2 上，錯誤以 Read-only file system 結尾。 失敗後，Claude 可能會 提供在沙箱外重新執行命令；批准該重試，或在另一個終端中自己執行 git 命令。如果您已將 allowUnsandboxedCommands 設定為 false，Claude 無法提供重試，因此請自己執行命令。如果相同的 git 命令經常失敗，請將其新增到 excludedCommands。
• Bubblewrap 在容器內啟動失敗：在無特權容器中，bubblewrap 無法掛載新的 /proc 檔案系統，因此沙箱化命令失敗，出現 bwrap 錯誤，例如 Can't mount proc on /newroot/proc: Operation not permitted。將 enableWeakerNestedSandbox 設定為 true，以便內部沙箱綁定掛載容器的現有 /proc。僅在外部容器已提供您需要的隔離邊界時使用此設定，因為它向沙箱化命令公開程序資訊，新的 /proc 掛載會隱藏。
• 0 位元組唯讀檔案出現在 .claude 設定路徑，且「是，不要再問」不會儲存：在 Linux 和 WSL2 上，沙箱在沙箱化命令執行時透過在該處建立 0 位元組唯讀預留位置來保持對尚不存在的檔案的寫入拒絕。沙箱在之後移除預留位置。如果在該清理執行之前會話被終止，例如透過 SIGKILL，預留位置會保留下來。稍後的會話在每次啟動時再次將它們綁定為唯讀，因此設定寫入（例如儲存權限選擇）在其中一個位置失敗。 執行 claude doctor 以列出剩餘的預留位置檔案。Stale sandbox mask files left by a killed session 警告命名最多三個，並計算其餘的。在該專案中沒有其他 Claude Code 會話執行時，使用 rm 刪除每個檔案。在 v2.1.257 之前，Claude Code 留下相同的預留位置而不標記它們。
• --dangerously-skip-permissions 以 root 身份失敗：在 Linux 和 macOS 上以 root 身份或透過 sudo 執行時，此旗標被阻止，因為 root 存取加上沒有權限提示可以修改系統上的任何檔案或服務。檢查在識別的沙箱內自動跳過。若要在容器中自主執行，請使用 dev container 配置，它以非 root 使用者身份執行 Claude Code。

​

限制

​

安全限制

• 網路過濾：沙箱限制流程可以連接的域名。預設情況下，內建代理不終止或檢查出站流量上的 TLS，因此加密連接的內容不被檢查。實驗性的 network.tlsTerminate 設定在代理處終止 TLS 以進行 mask 認證替換，但不添加內容過濾。您負責確保只有受信任的域名在您的策略中被允許。

• 通過 Unix 套接字的特權提升：allowUnixSockets 配置可能會無意中授予對系統服務的存取，這可能導致沙箱繞過。例如，允許存取 /var/run/docker.sock 有效地通過 Docker 套接字授予對主機系統的存取。仔細考慮您通過沙箱允許的任何 Unix 套接字。
• 檔案系統權限提升：過於寬泛的檔案系統寫入權限可能導致特權提升攻擊。允許寫入包含 $PATH 中可執行檔案的目錄、系統配置目錄或使用者 shell 配置檔案（例如 .bashrc 或 .zshrc）可能導致當其他使用者或系統流程存取這些檔案時在不同安全上下文中執行程式碼。
• Linux 沙箱強度：Linux 實現提供強大的檔案系統和網路隔離，但包含一個 enableWeakerNestedSandbox 模式，使其能夠在 Docker 環境中工作而無需特權命名空間，或在 Linux 主機上禁用無特權使用者命名空間的情況下。此選項大大削弱了安全性，應僅在其他隔離被強制執行時使用。
• macOS 上的 Apple Events：macOS 沙箱預設阻止 Apple Events。allowAppleEvents 設定解除此限制，使 open 和 osascript 等工具能夠運作，但它移除了程式碼執行隔離：沙箱化命令可以啟動其他應用程式而不進行沙箱化，無需使用者提示，並可以向執行中的應用程式傳送 AppleScript 命令，受限於每個應用程式的 macOS 自動化同意提示 (TCC)。它僅從使用者、受管或 CLI 設定中被接受。專案設定無法啟用它。

​

平台和工具相容性

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

​

範圍

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

​

另請參閱

• Sandbox environments：比較內建沙箱與開發容器、容器和虛擬機
• Security：全面的安全功能和最佳實踐
• Permissions：權限配置和存取控制
• All settings：每個設定鍵
• CLI reference：命令列選項