Ubuntu 24.04 上 Claude Code 沙盒起不來：AppArmor 擋住 bubblewrap 建立 user namespace 的檢查與修復

在 Ubuntu 24.04 以上裝好 bubblewrap 和 socat，Claude Code 的沙盒卻還是起不來，常見原因是 AppArmor 的預設政策不讓 bubblewrap 建立它需要的 user namespace。官方沙盒文件有專門一段處理，v2.1.310 還讓 /sandbox 與啟動警告直接指名這個限制。本文照官方文件整理檢查與修復步驟；指令我沒有在 Ubuntu 機器上跑過，請在自己的環境確認。

先確認是不是這個問題

文件的檢查方式（WSL2 裡也適用）：

sysctl kernel.apparmor_restrict_unprivileged_userns

• 回傳 0：不用做這一步。
• 印出 No such file or directory：這個 key 不存在，也不用做。
• 回傳 1：需要替 bwrap 加一個 AppArmor 設定檔。

另外，/sandbox 的 Dependencies 分頁會列出缺少的 ripgrep、bubblewrap、socat 與 seccomp 過濾器；依賴檢查在啟動時執行，所以裝完套件要重開 Claude Code。看不到這個分頁，代表依賴都在。

文件的修復步驟

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

文件特別說明：這個設定檔只套用在 bwrap 本身，不套用在它在沙盒裡執行的命令。也就是說，它授權的是「建立沙盒」這個動作，不是放寬沙盒內的程式。這和先前提過的 sandbox.allowNestedUserNamespaces 是不同層：後者讓沙盒裡面的命令也能建立 user namespace，而且官方警告那會關掉一道安全邊界；AppArmor 這一步只讓沙盒能起來。

為什麼要認真處理，而不是忽略

官方文件說：預設情況下，如果沙盒因為缺依賴或平台不支援而無法啟動，Claude Code 會在沒有沙盒的情況下執行命令；要讓它改成啟動時直接結束，設 sandbox.failIfUnavailable 為 true。文件列的是「缺依賴或平台不支援」這兩種情況；AppArmor 擋住 bubblewrap 是否算在內，文件沒有直說，這是我的推論，但如果你依賴沙盒，我建議兩件事都做：修好 AppArmor，並視需要開 failIfUnavailable，管理員的部署可以搭配 allowUnsandboxedCommands: false。文件也提醒：沙盒在原生 Windows 上不能跑，設了 failIfUnavailable 會讓 Claude Code 在那些機器上啟動時退出。

驗證沙盒真的有開

文件提供的探測命令之一：touch ~/sandbox-probe，在 Linux 與 WSL2 上應該以 Read-only file system 失敗（macOS 是 Operation not permitted）；curl --noproxy '*' https://example.com 應該以 Could not resolve host 失敗，因為命令沒有繞過沙盒代理的路。文件還說，如果 Claude 要求在沙盒外重試失敗的命令，要拒絕；若 touch 成功，而你的家目錄不是沙盒允許寫入的目錄，就刪掉 ~/sandbox-probe，再執行 /sandbox 檢查。

另外兩種容易混淆的情況

• 容器裡：在非特權容器中，bubblewrap 無法掛載新的 /proc，沙盒命令會以 bwrap 錯誤失敗，例如 Can't mount proc on /newroot/proc: Operation not permitted。文件的解法是 enableWeakerNestedSandbox: true，並警告只在外層容器已提供你需要的隔離時才用，因為它會把新的 /proc 本來會隱藏的行程資訊暴露給沙盒命令。
• WSL1：如果看到 Sandboxing requires WSL2，代表你的發行版跑在 WSL1，要升級到 WSL2，或不用沙盒執行 Claude Code。用 wsl -l -v 檢查版本。

我的判斷

以下是我的整理，不是官方建議：遇到沙盒起不來，先照 /sandbox 的提示做；Ubuntu 24.04 以上先查那個 sysctl；容器與 WSL1 是另外兩條路，不要混用解法。尤其不要為了讓沙盒「看起來能跑」就去開 allowNestedUserNamespaces，它解決的是不同的問題。