05. 权限、计划与安全

第一次权限询问

Matcha CLI 要改文件、跑命令或调用外部工具时，可以先停下问你。第一张卡片是一次性决定，不会悄悄切到始终批准。

允许、拒绝与取消

这是三种不同的结果。它们都会在你回答之前拦住工具，但事后含义不一样。

结果	你做了什么	工具会跑吗？	记录标记
允许	确认某一行允许（在高亮行按 `Enter`，或按对应数字）	会	工具继续执行
拒绝	选拒绝行（`No, reject`）	不会	`Permission denied in …`
取消	在卡片上按 `Ctrl+C`	不会	`Turn cancelled by user in …`

拒绝是对这次工具说不。取消是放弃这次权限请求——以及这一轮——且不会记下一次拒绝。不要当成同一把键。

权限卡片是输入区里的阻塞询问。第一张 bash 风格卡片上常见的行，从 1 编号：

第一行是 TUI 额外加上的。它允许这次调用，然后把会话切到始终批准（提示符上出现 · always-approve，提示 ⚠ Always-approve ON: all tool actions auto-run）。这是权限最大的选项。它不是默认高亮。

新会话里光标落在 Yes, proceed（允许一次）。因此 Enter 只允许这次调用，会话仍停留在询问。仍可用 1 或 Ctrl+O 选始终批准。

改文件的卡片会多一行 Yes, allow all edits during this session（只在内存里；重启后不保留）。额外的 Always allow: <command> 行只有你主动打开后才出现——见「询问、自动与始终批准」。

读取、搜索，以及一份固定的只读 shell 片段（ls、git status、rg 等）通常不弹卡片。链式命令会拆开：ls && rm -rf tmp 仍会为 rm 询问。匹配的 ask 或 deny 规则，或 PreToolUse 钩子，仍能拦住一次「免费」读取。

按键	效果
`Enter`	确认高亮行。第一张卡片上，那就是允许一次。
`1`–`9`	立刻选中对应编号的行。
`↑` / `↓` 或 `j` / `k`	移动高亮。
在拒绝行上输入	附上反馈，再按 `Enter` 带着这段文字拒绝。
`Ctrl+C`	取消这次请求。标记：`Turn cancelled by user`。
`Ctrl+O`	切换始终批准，不必用第 `1` 行。
`Esc`（焦点在选项上）	把卡片暂挂，把键盘交给滚动记录。这不是拒绝，也不是取消。`Tab` 或 `Space` 回到卡片。
`Esc`（正在输入拒绝反馈）	回到选项列表。草稿会保留。

出现「始终允许这条……」行时，方向键（← / →）可调整命令或 MCP 作用范围。

Yes, proceed 跑这次调用。会话仍停留在询问。之后的询问会记住你上次确认的允许类型（一次，还是始终允许这条命令），并在下次高亮同类选项。选始终批准、「本会话允许全部编辑」或拒绝，不会把下次光标带到那些选项。

第 1 行先允许这次调用一次，然后会话切到始终批准，队列里剩下的卡片会一并放行。管理员可以锁死这次切换——当前这次调用仍可允许一次。见「询问、自动与始终批准」。

No, reject 不跑工具。这一轮以 Permission denied in … 结束。在 Enter 之前输入的文字会随拒绝一起送出。

Ctrl+C 不跑工具。这一轮以 Turn cancelled by user in … 结束。这不是一次记下的拒绝。

未设置时默认是允许一次。若只想改第一次询问的落点：

# ~/.matcha/config.toml
[ui]
default_selected_permission = "allow_once"   # default
# always_allow_all_sessions | allow_command_always | reject

MATCHA_DEFAULT_SELECTED_PERMISSION 会覆盖该进程的文件设置（GROK_DEFAULT_SELECTED_PERMISSION 是已登记的别名）。你确认过任意允许行之后，后续卡片会跟上次用过的类型，直到进程退出。