oh-my-pi 工具审批模式Tool Approval Mode完全指南声明、策略与安全审批体系【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi导读本文系统讲解 oh-my-pi 中工具审批模式Tool Approval Mode的完整机制它由工具声明、工具策略与用户策略三路输入共同决定每一次工具调用的批准结果并通过tools.approvalMode的always-ask/write/yolo三种模式控制自动批准与人工确认的边界。读完本文你将掌握如何在config.yml中为内置工具与 MCP 工具配置审批策略、理解bash.patterns危险命令防护与复合命令链的判定规则、学会用formatApprovalDetails定制审批提示详情并知道在 ACP 会话与无头子代理subagent场景下审批模式的行为差异。本文主体内容对应仓库文档 docs/approval-mode.md所有配置项均可对照 packages/coding-agent/src/config/settings-schema.ts 中的 schema 定义逐条验证。审批的三个输入声明、工具策略与用户策略每次工具调用是否放行由三个相互独立又层层叠加的输入决定工具声明Tool declaration——每个工具都可以声明一个approval层级tier取值如下read只读取数据或更新仅影响 UI 的会话元数据write会改动工作区/会话状态但不会执行任意代码exec执行代码、调用外部 shell、驱动浏览器、派生子代理或执行类似宽泛动作。工具策略Tool policy——以对象形式声明的审批决策可以设置policy: allow | deny | prompt并可选附带override与reason用于实现依赖参数的安全/模式规则。用户策略User policy——配置中的tools.approval.toolName: allow | deny | prompt可以覆盖当前模式但不能绕过工具自身的 deny/prompt 策略也不能绕过非 yolo 模式下的安全 override。一个重要的安全默认值没有声明approval的工具以及格式非法的审批决策一律按exec层级处理。这意味着任何未知的自定义工具custom tool默认都需要人工确认才能放行。MCP 服务器上的工具默认声明为write层级。三种审批模式通过配置项tools.approvalMode设置在 settings-schema.ts 中定义为always-ask | write | yolo枚举默认值为yolo模式自动批准需要提示always-askreadwrite、execwriteread、writeexecyolo默认read、write、exec无命令行参数--auto-approve与--yolo等价都会强制本次会话的tools.approvalMode为yolo。在 cli/args.ts 中可以看到二者共享同一分支处理。用户级覆盖tools.approvaltools.approval在每一种模式下都被优先遵守这也是模式管默认、策略管特例的关键设计tools: approvalMode: write approval: bash: prompt read: allow mcp__filesystem_delete: deny上面的例子中整体处于write模式但bash工具被单独提升为每次调用都询问read被显式放行而 MCP 文件系统工具的delete被无条件禁止。MCP 工具的策略命名对 MCP 工具配置策略时必须使用注册后的最终名称。常规形式为mcp__sanitized_server_sanitized_tool且工具名中冗余的server_前缀会被移除——例如服务器echo上的工具echo_it会注册为mcp__echo_it而非mcp__echo_echo_it。超过 64 字符的名称会被截断并追加确定性哈希后缀因此配置时必须使用最终截断后的名称而不是未截断的模式。完整规则参见 MCP 工具命名与冲突域。每次调用的解析顺序文档对单次工具调用的审批解析顺序给出了明确的六步流程先评估tool.approval(args)缺失或格式非法的决策默认落到exec层级。工具声明的policy: deny永远拒绝随后检查用户deny也永远拒绝。在yolo模式下显式的工具allow/prompt策略优先否则有效的用户策略生效再否则直接放行。单独的override标志在 yolo 模式下不会强制弹窗。在非 yolo 模式下override: true的决策只允许配合工具policy: allow生效其余未被 deny 的情况一律弹窗询问。没有 override 时显式的工具allow/prompt策略优先其次才是有效的用户策略。完全没有显式策略时由当前模式按层级自动批准或弹窗。策略字符串会被去空白并做大小写归一化非法的用户策略值会被静默忽略。安全 override危险命令的强制确认工具可以用对象形式的审批强制弹窗approval: { tier: exec, override: true, reason: Critical pattern detected }bash工具就用这种方式拦截关键破坏性模式例如rm -rf /、fork 炸弹、远程拉取后立即执行、写入/etc/passwd、以及主机关机命令。reason会原样显示在审批提示中。此外bash支持通过配置的bash.patterns规则细化deny是绝对的直接拒绝prompt强制弹窗确认allow显式允许匹配的简单命令按write层级放行。注意边界在 yolo 模式下裸的 critical override 会被忽略但显式的工具/用户prompt或deny策略仍然生效——即 yolo 并不豁免任何明说不要的策略。在 settings-schema.ts 中bash.patterns被定义为有序数组每个条目包含match与approval字段且只支持*通配符与文档描述完全一致。bash.allowCompoundCommands复合命令链的审批bash.allowCompoundCommands默认关闭。启用后它只识别由连接的扁平命令链且链上每个片段必须由字面量参数构成。规则按顺序在每个片段内生效片段内第一个匹配的规则胜出。跨片段的显式限制采用保守合并任一匹配deny胜出否则任一匹配prompt胜出如果某条限制匹配的是整条链而非单个片段则作为整链否决whole-chain veto。整链限制会全部纳入考虑因此后出现的整链deny可以覆盖先出现的prompt。该特性要求通过集中的 shell 分类器识别出 POSIX 引号语义的 shell 才可启用Cmd、PowerShell、fish 及未知 shell 保持旧版审批行为。这些显式的链/片段限制会在既有的 raw 与 canonical 关键命令检查之前解析全部片段显式解析为allow的链最终获得write层级的放行若存在未匹配的片段bash 则回归其独立的exec审批层级且无显式策略随后由通用解析器应用tools.approval.bash与当前模式——因此未匹配的片段只有在既有工具级策略或模式要求时才弹窗。展开、赋值、其他控制流、重定向、通配符、换行、语法错误以及改变 shell 状态的 builtin 均不参与该判定保持旧版行为。模式策略不是进程沙箱需要特别强调bash.patterns只控制审批不是进程或文件系统级的隔离。被批准的命令仍拥有 shell 的全部环境权限文件系统、网络、子进程。同时eval工具也声明了exec层级并且能通过子进程拉起 shell因此bash.patterns里的deny不适用于经由eval执行的同一命令——在 yolo 下那次exec调用会解析为allow。要想限制eval能触达的 shell需要额外添加tools.approval.eval策略prompt或deny与bash.patterns配合使用。Computer 安全computer-use默认关闭的 EvalcomputerAPI见 docs/computer-use.md会按调用逐次选择层级直接辅助方法computer.windows()、win.screenshot()、win.ax()、el.bounds()、computer.clipboard.read()等当被调用方法仅做检查时用read涉及输入、聚焦、变更与clipboard.write时用execread调用还会运行在 worker 的只读保护之下computer.run(fnOrCode, options)仅当read_only: trueJavaScript 尾随选项或 Python 关键字时为readread_only: false、字段缺失、参数畸形或其他任何值都按exec处理。审批提示在适用时会显示read-only随后附上格式化后的 JavaScript 代码标准格式化器会截断到 2000 字符。对computer.run而言read_only是由审批层级强制执行的信任声明而不是对脚本做静态分析得出的结论。另外provider 发起的 computer-use 调用可能携带pendingSafetyChecks元数据任何待处理的安全检查都会强制交互式弹窗无视 yolo 模式或 per-toolallow。提示会逐一列出安全检查码、消息与经过清洗/截断的数据在没有交互式 UI 的环境下调用会以失败关闭报错pending provider safety checks but no interactive UI is available。最后一条底线原则工具审批并不授权底层的真实世界行为。屏幕上的文本不可信不能覆盖用户的直接指令后果性操作仍需要在风险点对确切的执行目标、范围与取值进行确认除非用户已在下发的直接消息中预先授权。审批提示详情formatApprovalDetails工具可以用formatApprovalDetails(args)向审批提示追加正文行。标准提示包含Allow tool: name工具名Origin: MCP server tool未标注来源的mcp__...工具会显示该行Reason: reason当工具决策提供了 reason 时工具特有详情如命令、路径、代码、浏览器动作或子代理任务分配如何在工具上定义审批内置工具与自定义工具共享同一套声明形态对应 docs/approval-mode.md 中的类型定义export type ToolTier read | write | exec; export type ToolApprovalDecision | ToolTier | { tier: ToolTier; reason?: string; override?: boolean; policy?: allow | deny | prompt; }; export type ToolApproval ToolApprovalDecision | ((args: unknown) ToolApprovalDecision); approval?: ToolApproval; formatApprovalDetails?: (args: unknown) string | string[] | undefined;四种典型用法// 固定只读层级 approval: read; // 依据参数动态选择层级如 LSP 只读动作放行其余升级为 write approval: (args) (LSP_READONLY_ACTIONS.has(args.action) ? read : write); // 命中关键模式时强制弹窗带 override 与 reason否则按 exec approval: (args) isCritical(args.command) ? { tier: exec, override: true, reason: Critical pattern detected } : exec; // 命中禁止清单时显式 deny其余按 write approval: (args) isForbidden(args) ? { tier: exec, policy: deny, reason: Blocked by tool policy } : write;ACP 会话中的审批ACPomp acp使用与普通 OMP 启动相同的设置解析器全局~/.omp/agent/config.yml生效ACP 会话cwd下的项目配置生效任何传给 ACP 服务器进程的--config file覆盖层也会应用到该进程创建的会话。要自动批准 ACP 工具调用可在全局或项目配置中设置tools: approvalMode: yolo或者用运行时覆盖/一次性配置覆盖启动 ACP 服务器omp acp --yolo omp acp --auto-approve omp acp --approval-mode yolo omp acp --config ./acp-yolo.yml # 文件内容为 tools.approvalMode: yolo优先级遵循常规设置优先级运行时标志--approval-mode、--auto-approve、--yolo--config覆盖层 项目配置 全局配置。ACP 目前没有定义session/new、session/load、session/resume的审批策略字段因此需要按会话区分 yolo 的 ACP 客户端应启动独立的omp acp进程配合上述标志之一或会话专属的--config覆盖层。需要注意两个容易踩的坑tools.approvalMode: yolo只有在显式配置或由运行时标志提供时才对 ACP 完全生效它会跳过 OMP 的审批弹窗也会跳过 ACP 客户端对bash、edit、delete、move的权限门除非tools.approval.tool被设为prompt或deny。schema 默认值虽然是yolo但默认配置的 ACP 会话仍会保留客户端权限门客户端需要无人值守执行时必须显式设置tools.approvalMode: yolo。当 ACP 需要审批时OMP 会经由 ACP 客户端而非终端 TUI 路由客户端门控的bash/edit/delete/move调用使用 ACP 的session/request_permission通用审批弹窗在客户端声明支持elicitation.form时使用表单 elicitation。被拒绝、取消或不受支持的提示会直接拒绝/取消该工具调用OMP 不会静默放行。子代理Subagents的审批边界子代理以无头方式运行并强制使用tools.approvalMode: yolo这样常规的层级弹窗不会卡住它们——父任务的task审批才是授权边界。与此同时用户的tools.approval.tool设置依然权威deny直接阻止该工具allow允许使用prompt在无头子代理中无法被满足因此会拒绝该调用。这套设计保证了子代理内部可以自主推进但用户显式表达过的禁止与询问意愿始终具有最高优先级不会因 yolo 模式而被绕过。总结配置一份合理的审批策略综合上文落地一份稳妥的审批配置可以遵循以下思路根据任务信任度选择tools.approvalMode日常交互推荐write无人值守的批处理/CI 才考虑yolo用tools.approval为高影响工具单独收紧如bash: prompt为纯只读工具显式放行如read: allow对 MCP 工具用最终注册名mcp__...配置策略必要时用deny封死危险能力如mcp__filesystem_delete: deny用bash.patterns声明关键命令的 deny/prompt 规则并记得同时为eval配置策略避免绕过路径ACP 客户端与子代理场景下显式配置tools.approvalMode: yolo并理解其与客户端权限门的关系避免看似无人值守实则卡住或看似 yolo 实则仍被拦截。所有配置项均可通过 packages/coding-agent/src/config/settings-schema.ts 检索验证命令行标志可在 packages/coding-agent/src/cli/args.ts 中确认其解析行为。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考