Windows 沙箱

自 v0.7.4 起，Zagens 在 Windows 上为 exec_shell 提供 OS 级进程隔离（受限 Token + ACL + WFP 防火墙），不再仅以当前用户权限裸跑命令。

策略 vs 强制： 执行策略中的 sandbox_mode 声明 Agent 意图（如仅工作区可写）；Windows 沙箱决定 操作系统是否真正强制。两者需配合使用。

在哪里配置

入口	内容
侧栏沙箱	首次向导、Windows 模式、私有桌面、配置/生效状态
设置 → 系统 → 安全	全局 `sandbox_mode`、Shell 开关、审批策略
`~/.zagens/config.toml`	`[windows] sandbox`、`sandbox_initialized` 等

首次启动（Agent 模式）： 若尚未初始化，沙箱面板只显示向导 — 选择 提升沙箱（推荐） 或 非提升沙箱 后即可进入完整设置。

两种 Windows 模式

模式	适合谁	能力摘要
Elevated（提升，推荐）	日常开发、需 profile 读隔离	工作区外不可写；`.ssh` 等敏感目录不可读；默认 WFP 阻断出站（回环放行）；支持后台 shell 与 ConPTY 交互终端；首次 provisioning 需 UAC/管理员
Unelevated（非提升）	快速试用、无法提权的环境	工作区写隔离 + 尽力网络限制；不提供 profile 读隔离（产品如实标注，非营销夸大）

[windows] sandbox 未设置时：已完成 setup → 默认 elevated；未完成 setup → 回退 unelevated 并警告。

与 `sandbox_mode` 的关系

`sandbox_mode`	文件意图	Windows elevated 额外强制
`workspace-write`（默认）	工作区内读写	工作区外不可写
`read-only`	禁止写文件	同上 + 策略层只读
`danger-full-access`	更广写范围（慎用）	仍受 OS 沙箱边界约束（非完全裸奔）

工具开网络（network_access: true）时，elevated 路径会使用 online 沙箱用户，出站不受 host 白名单限制 — 见网络策略。

首次向导

侧栏打开沙箱。
初始化默认沙箱（推荐） — 触发 elevated provisioning（创建 offline/online 沙箱用户、WFP 规则等），会弹 UAC。
或 使用非提升沙箱 — 无需管理员，能力见上表。
完成后可调整：Auto / Elevated / Unelevated、私有桌面（sandbox_private_desktop）。

面板会显示 配置后端 与 生效后端。若选了 Elevated 但未完成 setup，会提示需运行 zagens sandbox setup。

CLI（高级用户）

在已安装 zagens CLI 的机器上（通常与桌面共用 runtime）：

zagens sandbox setup      # 一次性 elevated provisioning（需管理员）
zagens sandbox teardown   # 清理沙箱产物
zagens sandbox add-read-dir <path>   # 会话内临时授予读目录（elevated）

其它平台

平台	状态
macOS	Seatbelt（`sandbox-exec`）进程隔离
Linux	策略已声明，OS 强制为 degraded（环境标记 + 日志警告）
OpenSandbox	可选外部容器后端 — 见执行策略

故障排除

现象	处理
面板显示「需完成初始化」	运行 `zagens sandbox setup` 或重走首次向导
配置 Elevated 但生效 Unelevated	setup 未完成或 UAC 被拒；检查面板状态徽章
Shell 结果 `sandbox_enforced: false`	查看 stderr 警告；Linux 为预期 degraded
仍担心 Agent 访问整台电脑	使用 elevated + `workspace-write` + 工具审批

诚实边界

Unelevated 不能声称隔离 .ssh 等 profile 读取。
Elevated offline 禁网时，DNS 解析侧信道仍可能存在。
Online 用户开网络时出站 无域名白名单（与文件沙箱独立）。