qiming/qimingclaw/crates/agent-electron-client/docs/sandbox/TROUBLESHOOTING.md

沙箱故障排查指南

版本: 1.0.0
更新: 2026-03-22

---

1. Docker 相关问题

1.1 Docker 不可用

症状： SandboxError: SANDBOX_UNAVAILABLE

排查步骤：

# 1. 检查 Docker 是否安装
docker --version

# 2. 检查 Docker 服务状态
# macOS
docker status
# Linux
sudo systemctl status docker

# 3. 检查 Docker 权限
docker ps

解决方案：

平台	命令
macOS	安装 Docker Desktop 并启动
Linux	sudo systemctl start docker
Windows	安装 Docker Desktop 并启用 WSL2

---

1.2 容器启动失败

症状： SandboxError: WORKSPACE_EXISTS 或容器无法创建

排查步骤：

# 1. 检查容器列表
docker ps -a

# 2. 检查 Docker 日志
docker logs <container-id>

# 3. 检查磁盘空间
docker system df

解决方案：

# 清理未使用的容器和镜像
docker system prune -a

# 增加 Docker 磁盘配额（Docker Desktop -> Settings -> Disk）

---

1.3 容器内命令执行失败

症状： SandboxError: EXECUTION_FAILED

排查步骤：

# 1. 检查容器是否运行
docker ps | grep <container-id>

# 2. 进入容器调试
docker exec -it <container-id> /bin/sh

# 3. 检查容器资源
docker stats <container-id>

---

2. Windows WSL 相关问题

2.1 WSL 未安装

症状： SandboxError: SANDBOX_UNAVAILABLE (Windows)

排查步骤：

# 检查 WSL 状态
wsl --status

# 列出已安装的发行版
wsl --list --verbose

解决方案：

# 安装 WSL
wsl --install -d Ubuntu-22.04

# 重启后检查
wsl --set-default Ubuntu-22.04

---

2.2 WSL 发行版启动失败

症状： SandboxError: WORKSPACE_EXISTS

排查步骤：

# 关闭所有 WSL 实例
wsl --shutdown

# 检查发行版状态
wsl --list --verbose

---

3. Linux Firejail 相关问题

3.1 Firejail 未安装

症状： SandboxError: SANDBOX_UNAVAILABLE (Linux)

排查步骤：

# 检查 Firejail
firejail --version

# 安装 Firejail
# Ubuntu/Debian
sudo apt install firejail

# Fedora
sudo dnf install firejail

---

3.2 Firejail 配置文件错误

症状： SandboxError: EXECUTION_FAILED

排查步骤：

# 检查 profile 语法
firejail --debug-profile=/path/to/profile 2>&1

# 测试 profile
firejail --profile=/path/to/profile /bin/ls

---

4. 权限相关问题

4.1 权限被拒绝

症状： SandboxError: PERMISSION_DENIED

排查步骤：

# 检查工作区目录权限
ls -la ~/.qimingclaw/workspaces/

# 检查用户组
groups $USER

解决方案：

# 修复目录权限
chmod -R 755 ~/.qimingclaw/workspaces/

# 将用户加入 docker 组
sudo usermod -aG docker $USER

---

4.2 权限请求无响应

症状： 命令挂起等待权限确认

排查步骤：

# 检查待处理的权限请求
# 在渲染进程中查看 PendingPermissions 状态

解决方案：

• 检查用户是否看到了权限确认弹窗
• 增加权限请求超时时间
• 设置自动批准常见操作

---

5. 工作区问题

5.1 工作区创建失败

症状： SandboxError: WORKSPACE_EXISTS

排查步骤：

# 检查工作区目录
ls -la ~/.qimingclaw/workspaces/

# 检查是否有残留进程
ps aux | grep qimingclaw

解决方案：

# 删除残留目录
rm -rf ~/.qimingclaw/workspaces/<session-id>

# 重启应用

---

5.2 工作区磁盘空间不足

症状： SandboxError: EXECUTION_FAILED (disk full)

排查步骤：

# 检查磁盘空间
df -h ~/.qimingclaw/

# 检查工作区大小
du -sh ~/.qimingclaw/workspaces/*

解决方案：

# 清理临时文件
rm -rf ~/.qimingclaw/workspaces/*/tmp/*

# 增加磁盘限额配置
# 在 sandbox.json 中设置 maxDiskUsage

---

5.3 工作区清理失败

症状： 退出应用后工作区仍然存在

排查步骤：

# 检查保留策略配置
cat ~/.qimingclaw/workspaces/<session-id>/sandbox.json

# 检查是否有进程占用
lsof +D ~/.qimingclaw/workspaces/<session-id>

---

6. 性能问题

6.1 沙箱启动慢

症状： 首次创建沙箱需要很长时间

原因： Docker 镜像下载、WSL 初始化等

解决方案：

# 预热：提前拉取镜像
docker pull node:20-slim

# WSL 预初始化
wsl -d Ubuntu-22.04

---

6.2 命令执行超时

症状： SandboxError: EXECUTION_TIMEOUT

排查步骤：

# 检查命令复杂度
# 增加超时时间

解决方案：

// 增加默认超时
const executeOptions: ExecuteOptions = {
  timeout: 600000, // 10 分钟
};

---

7. 网络问题

7.1 沙箱内无法访问网络

症状： npm install 失败

排查步骤：

# 检查 Docker 网络
docker network ls

# 测试网络连通性
docker exec <container-id> ping 8.8.8.8

解决方案：

// 在配置中启用网络
const config: SandboxConfig = {
  networkEnabled: true,
};

---

8. 跨平台路径问题

8.1 Windows 路径错误

症状： 文件找不到

排查步骤：

# 检查路径格式
echo $PATH

解决方案：

// 使用 path 模块
import path from 'path';

const sandboxPath = path.join(workspacePath, 'projects');
// 避免手动拼接字符串

---

9. 日志获取

9.1 主进程日志

# 查看主进程日志
tail -f ~/.qimingclaw/logs/main.$(date +%Y-%m-%d).log

9.2 Docker 容器日志

# 查看容器日志
docker logs <container-id>

# 实时跟踪
docker logs -f <container-id>

---

10. 常见错误代码

错误代码	说明	解决方案
SANDBOX_UNAVAILABLE	沙箱不可用	检查 Docker/WSL/Firejail 安装
WORKSPACE_NOT_FOUND	工作区不存在	创建工作区或检查 ID
WORKSPACE_EXISTS	工作区已存在	销毁现有工作区
PERMISSION_DENIED	权限不足	检查权限配置或用户确认
EXECUTION_FAILED	执行失败	查看详细日志
EXECUTION_TIMEOUT	执行超时	增加超时或优化命令
FILE_NOT_FOUND	文件不存在	检查路径
FILE_WRITE_FAILED	文件写入失败	检查磁盘空间和权限
CLEANUP_FAILED	清理失败	手动清理或检查进程
CONFIG_INVALID	配置无效	检查配置参数

---

11. 获取帮助

11.1 收集诊断信息

# 1. 系统信息
uname -a

# 2. Docker 信息
docker version
docker info

# 3. 应用日志
tar -czf diagnostics.tar.gz ~/.qimingclaw/logs/

# 4. 配置文件
cat ~/.qimingclaw/config.json

11.2 报告问题

报告问题时请包含：

• 操作系统版本
• Docker/WSL/Firejail 版本
• 错误日志
• 复现步骤
• 预期行为

---

12. 变更记录

日期	版本	变更
2026-03-22	1.0.0	初始版本