【Bug已解决】Claude: "permission denied" / File write blocked by sandbox — Claude 沙箱权限拒绝解决方案
1. 问题描述
Claude Code 在沙箱模式下被拒绝写入文件或执行命令:
# 权限拒绝 $ claude "修改 src/index.js" Error: Permission denied Sandbox blocked write to src/index.js # 或命令被拒绝 $ claude "运行 npm install" Error: Permission denied Sandbox blocked command: npm install # 或目录被拒绝 $ claude "修改 config/settings.json" Error: Permission denied Directory 'config/' is not in allowedDirectories. # 或读取被拒绝 $ claude "分析 .env 文件" Error: Permission denied File '.env' is blocked by sandbox.这个问题在以下场景中特别常见:
- 沙箱配置过于严格
- 目录不在 allowedDirectories
- 命令不在 allowedCommands
- 敏感文件被保护
- 沙箱默认配置
- Docker 中沙箱问题
2. 原因分析
原因分类表
| 原因分类 | 具体表现 | 占比 |
|---|---|---|
| 目录限制 | 不在 allowed | 约 35% |
| 命令限制 | 不在 allowed | 约 25% |
- 敏感文件 | .env 保护 | 约 20% | | 配置严格 | 默认 | 约 10% | | Docker | 隔离 | 约 5% | | 权限 | EACCES | 约 5% |
3. 解决方案
方案一:更新 allowedDirectories(最推荐)
# 步骤 1:检查沙箱配置 cat ~/.claude/settings.json | grep -A10 sandbox # 步骤 2:添加目录 cat > ~/.claude/settings.json << 'EOF' { "sandbox": { "enabled": true, "allowedDirectories": ["./src", "./tests", "./docs", "./config"] } } EOF # 步骤 3:验证 claude --auto-approve "修改 src/index.js" # 步骤 4:如果仍被拒绝,检查路径 claude --debug 2>&1 | grep -i "sandbox\|permission"方案二:使用 --no-sandbox
# 步骤 1:临时禁用沙箱 claude --no-sandbox "修改 src/index.js" # 步骤 2:或使用 --dangerously-skip-permissions claude --dangerously-skip-permissions "task" # 步骤 3:CI/CD 中 claude --no-sandbox --auto-approve "task" --max-turns 10 # 步骤 4:验证 claude --no-sandbox "运行 npm install"方案三:使用 --allowedTools
# 步骤 1:允许特定工具 claude --allowedTools "Read,Write,Edit,Bash" "task" # 步骤 2:或 --auto-approve claude --auto-approve "task" # 步骤 3:在配置中设置 cat > ~/.claude/settings.json << 'EOF' { "allowedTools": ["Read", "Write", "Edit", "Bash"] } EOF # 步骤 4:验证 claude --auto-approve "修改 src/index.js"方案四:检查文件权限
# 步骤 1:检查文件权限 ls -la src/index.js # 步骤 2:修复权限 chmod u+w src/index.js sudo chown $(whoami) src/index.js # 步骤 3:检查目录权限 ls -la src/ chmod -R u+rw src/ # 步骤 4:验证 claude --auto-approve "修改 src/index.js"方案五:配置 allowedCommands
# 步骤 1:允许特定命令 cat > ~/.claude/settings.json << 'EOF' { "sandbox": { "enabled": true, "allowedDirectories": ["./src", "./tests"], "allowedCommands": ["npm", "node", "python3", "git", "ls", "cat"] } } EOF # 步骤 2:验证 claude --auto-approve "运行 npm install" # 步骤 3:如果命令仍被拒绝 claude --debug 2>&1 | grep -i "command\|blocked" # 步骤 4:使用 --no-sandbox 临时绕过 claude --no-sandbox "运行 npm install"方案六:使用 .claudeignore
# 步骤 1:创建 .claudeignore cat > .claudeignore << 'EOF' node_modules/ .env .git/ *.log dist/ EOF # 步骤 2:但确保需要修改的文件不在忽略列表 # 如果 src/index.js 被忽略,从 .claudeignore 中移除 # 步骤 3:验证 claude --auto-approve "修改 src/index.js" # 步骤 4:检查 claude --debug 2>&1 | grep -i "ignore\|block"4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一:allowedDirectories | 长期 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二:--no-sandbox | 临时 | ⭐⭐⭐⭐⭐ | 低 |
| 方案三:--allowedTools | 工具 | ⭐⭐⭐⭐⭐ | 低 |
| 方案四:文件权限 | EACCES | ⭐⭐⭐⭐⭐ | 低 |
| 方案五:allowedCommands | 命令 | ⭐⭐⭐⭐⭐ | 低 |
| 方案六:.claudeignore | 忽略 | ⭐⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.1 沙箱是什么
Claude Code 的安全机制,限制可以修改的目录和执行的命令。
5.2 如何禁用沙箱
claude --no-sandbox "task" # 或 claude --dangerously-skip-permissions "task"5.3 allowedDirectories 是什么
沙箱配置,指定 Claude 可以读取/修改的目录列表。
5.4 allowedCommands 是什么
沙箱配置,指定 Claude 可以执行的命令列表。
5.5 如何检查沙箱配置
cat ~/.claude/settings.json | grep -A10 sandbox5.6 .env 被保护
在 .claudeignore 中移除 .env,或在 allowedDirectories 中添加。
5.7 --auto-approve 和 --no-sandbox 的区别
--auto-approve: 自动审批工具调用--no-sandbox: 完全禁用沙箱
5.8 Docker 中沙箱问题
使用--no-sandbox或配置allowedDirectories包含容器目录。
5.9 如何查看被拒绝的操作
claude --debug 2>&1 | grep -i "block\|denied\|permission"5.10 排查清单速查表
□ 1. cat settings.json | grep sandbox 检查 □ 2. allowedDirectories 添加目录 □ 3. allowedCommands 添加命令 □ 4. --no-sandbox 临时禁用 □ 5. --auto-approve 自动审批 □ 6. --allowedTools "Read,Write,Bash" □ 7. chmod u+w 修复文件权限 □ 8. sudo chown 修复所有者 □ 9. .claudeignore 检查忽略列表 □ 10. claude --debug | grep block 查看拒绝6. 总结
- 根本原因:权限拒绝最常见原因是目录不在 allowedDirectories(35%)和命令不在 allowedCommands(25%)
- 最佳实践:在
settings.json中配置allowedDirectories和allowedCommands - 临时绕过:使用
--no-sandbox或--dangerously-skip-permissions临时禁用沙箱 - 文件权限:
chmod u+w和sudo chown修复文件权限问题 - 最佳实践建议:配置
allowedDirectories: ["./src", "./tests"]和allowedCommands: ["npm", "node", "git"],使用--auto-approve
故障排查流程图
flowchart TD A[权限拒绝] --> B{是目录问题?} B -->|是| C[添加到 allowedDirectories] B -->|否| D{是命令问题?} C --> E["./src ./tests ./docs"] E --> F[claude 验证] D -->|是| G[添加到 allowedCommands] D -->|否| H{是文件权限?} G --> I["npm node git python3"] I --> F H -->|是| j[chmod u+w] H -->|否| K[使用 --no-sandbox] j --> L[sudo chown $(whoami)] L --> F K --> M[claude --no-sandbox "task"] M --> F F --> N{成功?} N -->|是| O[✅ 问题解决] N -->|否| P[使用 --auto-approve] P --> Q[claude --auto-approve "task"] Q --> R{成功?} R -->|是| O R -->|否| S[检查 .claudeignore] S --> T[移除被忽略的文件] T --> F F --> U{成功?} U -->|是| O U -->|否| V[使用 --dangerously-skip-permissions] V --> W[临时绕过所有权限] W --> O O --> X[长期: sandbox + allowedTools] X --> Y[✅ 长期方案]