05. 权限、计划与安全

沙箱

沙箱是可选的操作系统级隔离，包住 Matcha CLI 进程和它启动的命令。权限决定模型可以请求什么。沙箱决定请求被批准之后，进程实际能做什么。

启动时生效

非 off 的配置档在启动时应用到整个进程（Linux 上是 Landlock，macOS 上是 Seatbelt）。对该进程不可撤销。助手之后不能放宽它。子进程继承文件系统限制。

默认是关。你主动打开。

内置配置档

配置档	文件系统读	文件系统写	子进程网络	典型用途
`off`（默认）	不限制	不限制	不限制	可信机器，不隔离
`workspace`	任意位置	当前工作目录 + `~/.matcha/` + 临时目录	允许	日常开发
`devbox`	任意位置	顶层目录，除 `/data`（以及 `/proc`、`/sys`、`/dev`）	允许	一次性虚拟机
`read-only`	任意位置	`~/.matcha/` + 临时目录	Linux 上拦截	审阅、探索
`strict`	当前工作目录 + 系统路径	当前工作目录 + `~/.matcha/` + 临时目录	Linux 上拦截	不信任的目录树

临时目录包括 /tmp、/var/tmp，以及 macOS 上 /private/var/folders 下真实的 TMPDIR。子进程网络拦截只用 Linux 上的 seccomp。macOS 上 restrict_network 是空操作。

workspace、read-only 和 strict 会拒绝写入用户全局钩子来源（~/.matcha/hooks/、~/.matcha/hooks-paths，以及其中列出的绝对目标），以免沙箱会话改写那些钩子。devbox 不施加这项保护。

自定义配置档

自定义配置档写在 ~/.matcha/sandbox.toml 或 .matcha/sandbox.toml。它们 extends 一份内置配置档，再加 read_only、read_write、restrict_network，以及内核强制的 deny 列表（如 **/.env 这类 glob）。自定义名不能占用内置名：--sandbox devbox 永远跑内置的。若用户文件和项目文件用同一自定义名却定义不同，用户文件胜出，启动时会警告；/doctor 会显示两条路径。

请求非 off 配置档时，助手留在本进程（没有共享 leader）。matcha workspace start / restart / resume 不可用；pause、stop 和 status 仍可用。

内置配置档无法生效时（内核过旧、缺少 entitlements）会警告并无强制地继续，但仍拒绝 leader。自定义配置档无法生效时（未知名称、损坏的 sandbox.toml，或 Linux deny 没有 bubblewrap）会拒绝启动。

配置档随会话保存。恢复会话会还原它。恢复时 --sandbox 必须与保存的配置档一致，否则 Matcha CLI 报错；要改隔离，请开新会话。

什么时候用

希望助手能读系统、但只写这个项目和 Matcha CLI 自己的主目录时，用 workspace。面对不信任的目录树，用 read-only 或 strict。助手必须装包或写到工作目录之外时，跳过沙箱。

权限加上沙箱比单独用任何一项都更强：拒绝规则拦住模型去请求；内核拦住仍试图动手的进程。

用配置档启动

matcha --sandbox workspace
matcha --sandbox read-only
matcha --sandbox strict

MATCHA_SANDBOX 选择同一份配置档（GROK_SANDBOX 是已登记的别名）。新会话的解析顺序：

钉死配置档的托管要求
--sandbox / MATCHA_SANDBOX
配置里的 [sandbox] profile
off

自定义配置档示例

# ~/.matcha/sandbox.toml
[profiles.project]
extends = "workspace"
restrict_network = true
read_only = ["/data"]
read_write = ["/tmp/scratch"]
deny = ["/data/shared-secrets", "**/.env", "**/*.pem"]

matcha --sandbox project

带 *、? 或 [ 的 deny 项是 glob。macOS 上在运行时匹配（之后创建的文件仍能命中）。Linux 上在启动时展开——之后才出现的匹配不覆盖；Linux 必须严密时请写确切路径。两边都不支持的 glob 语法会拒绝启动。

恢复会话

matcha --continue
matcha --resume <id>

省略 --sandbox 以保留保存的配置档。传入不同的配置档会被拒绝。

Shell 环境

[shell_environment_policy] 过滤工具命令继承的变量，以免你 shell 里的密钥漏进子进程。这相关，但不是内核沙箱。默认是不动环境（inherit = "all"）。

事件

违规和配置档已应用的记录写入 ~/.matcha/sandbox-events.jsonl。