chore: initialize qiming workspace repository
This commit is contained in:
Codex
359
qimingclaw/docs/sandbox-writable-paths-fix.md
Normal file
359
qimingclaw/docs/sandbox-writable-paths-fix.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# macOS Seatbelt Strict 模式下 ACP 引擎工具调用 EPERM 修复
|
||||
|
||||
> 日期: 2026-04-09
|
||||
> 状态: 已修复（三轮迭代）
|
||||
> 影响范围: macOS + seatbelt strict/compat 模式下的 ACP 引擎（claude-code / qimingcode）
|
||||
> 跨平台: macOS / Linux / Windows 均已处理
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题描述
|
||||
|
||||
在 macOS 上，ACP 引擎被 seatbelt 沙箱以 `strict` 模式包裹后，所有需要 spawn 子进程的工具（Bash、Glob 等）因 `EPERM` 失败，无法正常执行。同时引擎无法写入应用数据目录（`~/.qimingclaw`），导致日志、npm 包等不可用。
|
||||
|
||||
### 1.1 claude-code 引擎
|
||||
|
||||
```
|
||||
EPERM: operation not permitted, mkdir '/private/tmp/claude-501/-Users-apple-Downloads-test-electron-client-computer-project-workspace-1746495851-1544430'
|
||||
```
|
||||
|
||||
claude-code 内部 Bash 工具使用**硬编码的** `/private/tmp/claude-{uid}/` 路径（不是 `os.tmpdir()`），不在 seatbelt profile 的 writablePaths 中。
|
||||
|
||||
### 1.2 qimingcode 引擎
|
||||
|
||||
```
|
||||
EPERM: operation not permitted, posix_spawn '/var/folders/.../qimingclaw-acp-xxx/.local/share/qimingcode/bin/rg'
|
||||
```
|
||||
|
||||
qimingcode 内部需要执行 `rg`（ripgrep）实现文件搜索工具，但 strict 模式下 `startupExecAllowlist` 未生效，`rg` 不在 exec allow 中。
|
||||
|
||||
### 1.3 应用数据目录不可写
|
||||
|
||||
strict 模式下 writablePaths 不包含 `~/.qimingclaw`，引擎无法：
|
||||
- 写日志到 `~/.qimingclaw/logs/`
|
||||
- 访问 `~/.qimingclaw/node_modules/` 中的 npm 包
|
||||
- 读写引擎配置缓存
|
||||
|
||||
### 1.4 Windows strict 模式限制
|
||||
|
||||
Windows sandbox helper 的 strict 模式只取 `writablePaths[0]`（工作区），忽略了应用数据目录、isolatedHome、临时目录等必要路径。
|
||||
|
||||
### 1.5 复现步骤
|
||||
|
||||
1. 启动 QimingClaw 桌面客户端，创建 ACP 会话（sandbox mode = strict）
|
||||
2. 发送提示词："运行 pwd 显示当前工作目录" 或 "运行 node -e ..."
|
||||
3. agent 尝试执行 Bash/Glob 工具 → EPERM
|
||||
|
||||
---
|
||||
|
||||
## 2. 根因分析
|
||||
|
||||
### 2.1 Seatbelt Profile 两个限制
|
||||
|
||||
**限制 1：写入权限不足**
|
||||
|
||||
strict 模式的 seatbelt profile，writablePaths 仅包含：
|
||||
|
||||
| 路径 | 来源 |
|
||||
|------|------|
|
||||
| `{projectWorkspaceDir}` | 用户工作区 |
|
||||
| `{isolatedHome}` | 引擎隔离 HOME |
|
||||
|
||||
缺少系统临时目录（`/private/tmp/` 等）。
|
||||
|
||||
**限制 2：执行权限不足**
|
||||
|
||||
strict 模式下，`SandboxInvoker.buildSeatbeltProfile()` 中 `startupExecAllowlist` 只在 compat 模式使用（原 line 442-443）。strict 模式只允许执行：
|
||||
- `/usr/bin/*`, `/bin/*`, `/usr/lib/*` — 系统路径
|
||||
- `{command}` — 引擎主二进制（如 node / qimingcode）
|
||||
|
||||
引擎内部二进制（如 isolatedHome 下的 `rg`）不在允许列表中。
|
||||
|
||||
### 2.2 失败工具调用清单（同一会话，共 5 次）
|
||||
|
||||
| Tool Call ID | 工具 | 命令 | 错误类型 |
|
||||
|---|---|---|---|
|
||||
| `call_0623c3816d9b47508f6ad079` | Bash | `pwd` | EPERM mkdir `/private/tmp/claude-501/...` |
|
||||
| `call_2277b5404d0c455da0db355b` | Bash | `pwd` | EPERM mkdir `/private/tmp/claude-501/...` |
|
||||
| `call_3400c1f44b76412e9bc0b258` | Bash | `echo $PWD` | EPERM mkdir `/private/tmp/claude-501/...` |
|
||||
| `call_d44e1ea2a9c14d1fb200c6d9` | Glob | `*` | `spawn EPERM` |
|
||||
| `call_b60209d94ce34affb3d032ec` | Bash | `ls -la` (含 `dangerouslyDisableSandbox:true`) | EPERM mkdir `/private/tmp/claude-501/...` |
|
||||
|
||||
注意：即使工具调用携带 `dangerouslyDisableSandbox: true`，依然失败。seatbelt 沙箱包裹的是整个引擎进程（进程级），不是单个工具调用。进程级的 seatbelt 限制无法被内部参数绕过。
|
||||
|
||||
---
|
||||
|
||||
## 3. 修复方案（三轮迭代）
|
||||
|
||||
### 3.1 第一轮：设置 TMPDIR 环境变量 → 失败
|
||||
|
||||
将 `TMPDIR`/`TEMP`/`TMP` 指向 `isolatedHome/tmp`。`isolatedHome/tmp/` 目录成功创建，但 claude-code 内部 Bash 工具不读取 `TMPDIR`，仍使用硬编码的 `/private/tmp/claude-{uid}/`。
|
||||
|
||||
**结论：TMPDIR 方案对 claude-code 无效。**（该代码保留 — 对其他场景仍有价值。）
|
||||
|
||||
### 3.2 第二轮：添加 `/private/tmp/claude-{uid}/` → 部分有效
|
||||
|
||||
将引擎特定的 `/private/tmp/claude-{uid}/` 加入 writablePaths。修复了 claude-code 的写入问题，但：
|
||||
- 路径是引擎特定（claude-），不统一
|
||||
- 没有覆盖 qimingcode 的 `rg` 执行问题
|
||||
- 没有跨平台考虑
|
||||
|
||||
### 3.3 第三轮（最终方案）：统一跨平台修复
|
||||
|
||||
**四个改动，统一适用于所有引擎和所有平台：**
|
||||
|
||||
#### 改动 1：跨平台系统临时目录加入 writablePaths
|
||||
|
||||
**文件**: `acpClient.ts`
|
||||
|
||||
```typescript
|
||||
const extraWritable: string[] = [isolatedHome, os.tmpdir()];
|
||||
try {
|
||||
extraWritable.push(fs.realpathSync(os.tmpdir()));
|
||||
} catch { /* skip */ }
|
||||
if (process.platform === "darwin") {
|
||||
extraWritable.push("/tmp", "/private/tmp");
|
||||
}
|
||||
```
|
||||
|
||||
| 平台 | 添加的路径 |
|
||||
|------|-----------|
|
||||
| **macOS** | `os.tmpdir()` (`/var/folders/.../T`) + realpath + `/tmp` + `/private/tmp` |
|
||||
| **Linux** | `os.tmpdir()` (`/tmp`) + realpath |
|
||||
| **Windows** | `os.tmpdir()` (`C:\Users\...\AppData\Local\Temp`) + realpath |
|
||||
|
||||
所有引擎统一使用同一套路径，无引擎特定逻辑。
|
||||
|
||||
#### 改动 1b：应用数据目录加入 writablePaths
|
||||
|
||||
**文件**: `acpClient.ts`
|
||||
|
||||
```typescript
|
||||
// App data directory (e.g. ~/.qimingclaw) — engine writes logs, npm packages, etc.
|
||||
const appDataDir = path.join(app.getPath("home"), APP_DATA_DIR_NAME);
|
||||
extraWritable.push(appDataDir);
|
||||
```
|
||||
|
||||
所有沙箱模式（strict / compat / permissive）和所有平台均可写入应用数据目录，引擎可正常写日志、访问 npm 包和配置缓存。
|
||||
|
||||
#### 改动 2：strict 模式也使用 startupExecAllowlist
|
||||
|
||||
**文件**: `SandboxInvoker.ts`
|
||||
|
||||
原代码中 `startupExecAllowlist` 只在 compat 模式生效。修改为 strict 和 compat 都使用：
|
||||
|
||||
```typescript
|
||||
// Before: only compat used startupExecAllowlist
|
||||
if (compat) {
|
||||
for (const p of startupExecAllowlist) execAllow.add(p);
|
||||
}
|
||||
|
||||
// After: both strict and compat include engine-internal binaries
|
||||
for (const p of startupExecAllowlist) execAllow.add(p);
|
||||
```
|
||||
|
||||
#### 改动 3：writablePaths 自动添加 process-exec subpath 规则
|
||||
|
||||
**文件**: `SandboxInvoker.ts`
|
||||
|
||||
每个 writablePath 同时添加 `file-write*` 和 `process-exec` 的 subpath 规则：
|
||||
|
||||
```typescript
|
||||
lines.push(`(allow file-write* (subpath "${p}"))`);
|
||||
lines.push(`(allow process-exec (subpath "${p}"))`);
|
||||
```
|
||||
|
||||
这解决了 qimingcode 的 `rg` 执行问题 — `rg` 位于 isolatedHome 内，isolatedHome 是 writablePath，现在也允许在其中执行二进制。
|
||||
|
||||
#### 改动 3b：Windows strict 模式使用完整 writablePaths
|
||||
|
||||
**文件**: `SandboxInvoker.ts`
|
||||
|
||||
Windows sandbox helper 的 strict 模式原来只取 `writablePaths[0]`（工作区），忽略了应用数据目录、isolatedHome、临时目录等。现在所有模式统一使用完整 `writablePaths`，不再区分 strict/compat：
|
||||
|
||||
```typescript
|
||||
// Before:
|
||||
if (sandboxMode === "strict") {
|
||||
sandboxPolicy.writable_roots = [params.writablePaths[0]!];
|
||||
} else {
|
||||
sandboxPolicy.writable_roots = params.writablePaths;
|
||||
}
|
||||
|
||||
// After:
|
||||
sandboxPolicy.writable_roots = params.writablePaths;
|
||||
```
|
||||
|
||||
### 3.4 修复后的 seatbelt profile（示例）
|
||||
|
||||
```seatbelt
|
||||
(version 1)
|
||||
(deny default)
|
||||
(allow network*)
|
||||
(allow file-read*)
|
||||
(allow process-exec (regex #"^/usr/bin/"))
|
||||
(allow process-exec (regex #"^/bin/"))
|
||||
(allow process-exec (regex #"^/usr/lib/"))
|
||||
(allow process-exec (literal ".../node")) ; 引擎主二进制
|
||||
(allow signal (target self))
|
||||
(allow process-fork)
|
||||
(allow sysctl-read)
|
||||
(allow mach-lookup)
|
||||
(allow ipc-posix*)
|
||||
(allow file-lock)
|
||||
; writablePaths — 同时允许 file-write 和 process-exec
|
||||
(allow file-write* (subpath "/Users/apple/project"))
|
||||
(allow process-exec (subpath "/Users/apple/project"))
|
||||
(allow file-write* (subpath ".../qimingclaw-acp-xxx"))
|
||||
(allow process-exec (subpath ".../qimingclaw-acp-xxx")) ; rg 等引擎内部二进制可执行
|
||||
(allow file-write* (subpath "/Users/apple/.qimingclaw"))
|
||||
(allow process-exec (subpath "/Users/apple/.qimingclaw")) ; 应用数据目录（日志、npm 包等）
|
||||
(allow file-write* (subpath "/var/folders/.../T"))
|
||||
(allow file-write* (subpath "/private/tmp")) ; claude-code Bash 工具
|
||||
(allow process-exec (subpath "/private/tmp"))
|
||||
(allow file-write* (subpath "/tmp"))
|
||||
(allow process-exec (subpath "/tmp"))
|
||||
(allow file-write* (literal "/dev/null"))
|
||||
(allow file-write* (literal "/dev/dtracehelper"))
|
||||
(allow file-write* (literal "/dev/urandom"))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 验证方式
|
||||
|
||||
1. 重新构建并启动 ACP 会话（strict 模式），发送 `pwd` → 应正常返回工作目录
|
||||
2. 发送 `node -e "console.log('hello')"` → 应正常输出
|
||||
3. 发送 `sandbox-testing-prompts.md` 中 A1 安全命令 → 全部正常执行
|
||||
4. 确认 qimingcode 引擎也能正常执行 Glob/Grep 工具（`rg` 不再 EPERM）
|
||||
5. 确认日志中 seatbelt profile 包含 `/private/tmp`、`process-exec (subpath isolatedHome)` 和 `~/.qimingclaw`
|
||||
6. 确认引擎可以写日志到 `~/.qimingclaw/logs/`
|
||||
7. 确认 compat/permissive 模式也正常工作
|
||||
8. 确认 Windows strict 模式下引擎也能写日志和临时文件
|
||||
|
||||
---
|
||||
|
||||
## 5. 涉及文件
|
||||
|
||||
| 文件 | 改动类型 | 说明 |
|
||||
|------|----------|------|
|
||||
| `acpClient.ts` | 修改 | 跨平台系统临时目录 + 应用数据目录加入 extraWritablePaths |
|
||||
| `SandboxInvoker.ts` | 修改 | strict 模式使用 startupExecAllowlist + writablePaths 添加 process-exec subpath + Windows strict 模式使用完整 writablePaths |
|
||||
| `docs/sandbox-strict-tmpdir-fix.md` | 文档 | 本文档 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 设计考量
|
||||
|
||||
### 为什么不直接去掉 ACP 引擎的 seatbelt 包裹
|
||||
|
||||
设计文档 (`sandbox-testing-prompts.md`) 提到 ACP 会话"不走 seatbelt"，但实际实现中 seatbelt 包裹是进程级安全隔离的重要层。通过修复 seatbelt profile 的路径和执行权限，可以在保留 seatbelt 保护的同时让引擎正常工作。工具级权限由 PermissionManager 管理。
|
||||
|
||||
### 为什么将 `/private/tmp/` 整体加入 writablePaths
|
||||
|
||||
- 引擎（claude-code）硬编码使用 `/private/tmp/claude-{uid}/`，无法通过 TMPDIR 重定向
|
||||
- 未来其他引擎也可能使用系统临时目录
|
||||
- 统一跨平台处理，避免引擎特定逻辑
|
||||
|
||||
---
|
||||
|
||||
## 7. Windows serve 模式 WRITE_RESTRICTED 修复（第四轮）
|
||||
|
||||
> 日期: 2026-04-09
|
||||
> 状态: 已修复
|
||||
> 影响范围: Windows strict/compat 模式下的 qimingcode 引擎
|
||||
|
||||
### 7.1 问题描述
|
||||
|
||||
前三轮修复后，qimingcode（opencode Go 二进制）的内部 `bash` 工具仍可写入 Desktop 等非工作区目录。Claude Code 引擎的 bash 通过 ACP Terminal API 已被正确沙箱化，但 qimingcode 的 bash 在内部执行，不经过 AcpTerminalManager。
|
||||
|
||||
### 7.2 根因
|
||||
|
||||
`qiming-sandbox-helper.exe serve` 子命令硬编码 `write_restricted=false`（`main.rs:585`）。
|
||||
|
||||
没有 `WRITE_RESTRICTED` flag 和 restricting SIDs 时，Windows 访问检查不考虑 capability SID 的 DACL ACEs。结果：进程级沙箱提供**零写入保护**。
|
||||
|
||||
```
|
||||
write_restricted=false → token: DISABLE_MAX_PRIVILEGE | LUA_TOKEN（无 restricting SIDs）
|
||||
→ add_allow_ace() / add_deny_write_ace() 对该 token 无效
|
||||
→ qimingcode bash 可写任意路径
|
||||
```
|
||||
|
||||
### 7.3 修复方案
|
||||
|
||||
**原则**: 最小侵入，单一权威源。
|
||||
|
||||
#### 改动 1: Rust helper `serve` 子命令新增 `--write-restricted` flag
|
||||
|
||||
```rust
|
||||
struct ServeArgs {
|
||||
common: CommonArgs,
|
||||
#[arg(long, default_value_t = false)]
|
||||
write_restricted: bool,
|
||||
}
|
||||
```
|
||||
|
||||
`write_restricted=true` 时，`create_restricted_token()` 添加：
|
||||
- `WRITE_RESTRICTED` flag
|
||||
- 3 个 restricting SIDs: capability SID + logon SID + everyone SID
|
||||
- 只有带 ALLOW ACE 的路径可写
|
||||
|
||||
#### 改动 2: Policy JSON 新增 `sandbox_mode` 字段
|
||||
|
||||
```typescript
|
||||
const sandboxPolicy = {
|
||||
type: "workspace-write",
|
||||
network_access: true,
|
||||
sandbox_mode: "strict", // ← 新字段
|
||||
writable_roots: [...],
|
||||
};
|
||||
```
|
||||
|
||||
Rust `policy.rs` 的 `SandboxPolicy::WorkspaceWrite` 解析此字段，
|
||||
`compute_allow_paths()` 根据它决定是否将 APPDATA/LOCALAPPDATA 加入 ALLOW ACEs。
|
||||
|
||||
#### 改动 3: SandboxInvoker 传递 `--write-restricted` 给 serve 模式
|
||||
|
||||
```typescript
|
||||
if (subcommand === "serve" && sandboxMode !== "permissive") {
|
||||
helperArgs.push("--write-restricted");
|
||||
}
|
||||
```
|
||||
|
||||
#### 改动 4: acpEngine.ts 跨平台扩展
|
||||
|
||||
- 移除 `this.engineName === "claude-code"` 限制（两个引擎均受保护）
|
||||
- 移除 `type === "windows-sandbox"` 限制（所有沙箱类型均受保护）
|
||||
- sandboxed-fs MCP 和 disallowedTools 扩展到所有平台
|
||||
|
||||
### 7.4 修复后的行为
|
||||
|
||||
| Mode | serve 进程可写路径 | sandboxed-fs MCP |
|
||||
|------|-------------------|-----------------|
|
||||
| **strict** | workspace + TEMP/TMP（APPDATA 不可写） | 仅 workspace + TEMP/TMP |
|
||||
| **compat** | workspace + TEMP/TMP + APPDATA/LOCALAPPDATA | workspace + TEMP/TMP + APPDATA |
|
||||
| **permissive** | 无限制（WRITE_RESTRICTED=false） | 不注入 MCP |
|
||||
|
||||
### 7.5 涉及文件
|
||||
|
||||
| 文件 | 改动类型 | 说明 |
|
||||
|------|----------|------|
|
||||
| `crates/windows-sandbox-helper/src/main.rs` | 修改 | serve 子命令新增 `--write-restricted` flag |
|
||||
| `crates/windows-sandbox-helper/src/policy.rs` | 修改 | `WorkspaceWrite` 新增 `sandbox_mode` 字段 |
|
||||
| `crates/windows-sandbox-helper/src/allow.rs` | 修改 | strict 模式排除 APPDATA；compat/permissive 包含 |
|
||||
| `SandboxInvoker.ts` | 修改 | 传递 `--write-restricted` + `sandbox_mode` 到 policy JSON |
|
||||
| `sandboxProcessWrapper.ts` | 修改 | 移除冗余 APPDATA 添加（Rust 是单一权威源） |
|
||||
| `acpEngine.ts` | 修改 | 跨平台/跨引擎扩展 sandboxed-fs MCP 和 disallowedTools |
|
||||
|
||||
### 7.6 设计决策
|
||||
|
||||
**为什么 Rust `compute_allow_paths()` 是 APPDATA 的单一权威源？**
|
||||
|
||||
之前 APPDATA 在 TypeScript（`sandboxProcessWrapper.ts`）和 Rust（`allow.rs`）两处添加，
|
||||
导致 strict 模式下 TypeScript 总是添加 APPDATA，与 strict 语义矛盾。
|
||||
现在统一由 Rust 根据 `sandbox_mode` 字段决定，TypeScript 只负责传递 `sandbox_mode`。
|
||||
|
||||
**为什么 strict 模式下 serve 进程的 APPDATA 不可写？**
|
||||
|
||||
strict 模式的目标是"最小写入面"。引擎基础设施日志写入通过 `isolatedHome`（TEMP 目录下）解决，
|
||||
不依赖 APPDATA。sandboxed-fs MCP 对 AI agent 的文件写入做独立路径验证，
|
||||
进程级和 MCP 级保护互不干扰。
|
||||
Reference in New Issue
Block a user