メインコンテンツまでスキップ

工具权限与安全

Elftia 的 Agent 系统在赋予 AI 强大执行能力的同时，也提供了多层安全防护机制。本文详细介绍权限模式、工具敏感度分类、确认对话框流程以及各安全层的工作方式。

权限模式​

权限模式（Permission Mode）决定了 Agent 执行工具时的安全级别。可以在 Agent 配置的 permissionMode 字段中设置。

模式一览​

模式标识行为适用场景
默认default敏感工具需要用户逐一确认日常使用，安全第一
接受编辑acceptEdits文件读写自动通过，Shell/MCP 仍需确认编程场景，信任文件操作
绕过权限bypassPermissions所有工具自动执行完全信任 Agent
只读模式plan仅允许只读工具信息收集、分析、规划

模式行为对比​

工具defaultacceptEditsbypassPermissionsplan
Read / Glob / Grep自动自动自动自动
Write / Edit确认自动自动禁止
Bash确认确认自动禁止
spawn_agent确认确认自动禁止
MCP 工具确认确认自动禁止
WebSearch / WebFetch自动自动自动自动

plan 模式可用工具​

plan 模式下只允许以下只读工具：

  • Read — 读取文件
  • ListDir — 列出目录
  • Glob — 文件匹配
  • Grep — 内容搜索
  • WebSearch — 网页搜索
  • WebFetch — 网页抓取
  • list_skills — 列出技能
  • read_skill — 读取技能

工具敏感度分类​

TinyElf 引擎将工具分为两类：安全工具和敏感工具。

安全工具（永不需要确认）​

工具说明
Read读取文件内容
ListDir列出目录
Glob文件名匹配搜索
Grep文件内容搜索
WebSearch网页搜索
WebFetch抓取网页内容
list_skills列出可用技能
read_skill读取技能内容
Notify发送桌面通知
SessionsYield结束 Agent 循环
SessionsHistory查看会话历史

敏感工具（根据权限模式决定是否需要确认）​

工具风险说明
Bash可执行任意 Shell 命令
Write可创建或覆盖文件
Edit可修改现有文件内容
spawn_agent可启动子 Agent 执行任务
MCP 工具（mcp__*）外部工具，行为不可预测

:::info MCP 工具默认敏感 所有 MCP 工具默认被视为敏感工具。这是因为 MCP 工具来自外部服务器，其行为无法被 Elftia 预先审核。 :::

确认对话框流程​

当 Agent 尝试使用敏感工具时（在需要确认的权限模式下），系统会向用户展示确认对话框。

桌面模式流程​

Agent 请求执行 Bash("npm test")
     ↓
系统发送权限请求（IPC: permissionRequest）
     ↓
前端显示确认对话框：
  ┌─────────────────────────────┐
  │  Bash: npm test             │
  │                             │
  │  [允许] [拒绝] [本次会话允许] │
  └─────────────────────────────┘
     ↓
用户选择 → 结果返回给 Agent

用户选项​

选项行为
允许（Allow）仅本次允许执行
拒绝（Deny）本次拒绝执行，Agent 收到拒绝通知
本次会话允许（Allow for Session）本次允许，且后续同一工具自动通过

会话级工具白名单​

选择「本次会话允许」后，该工具名称会被加入当前会话的白名单。后续对同一工具的调用将自动通过，无需再次确认。白名单在会话结束时清除。

超时处理​

如果用户在 5 分钟 内未响应确认对话框，系统会自动拒绝该请求。

三层安全防护​

TinyElf 引擎实现了三层安全防护管道，按以下顺序执行：

工具调用请求
     ↓
[第一层] ExecutionFirewall — 路径和命令验证
     ↓ (通过)
[第二层] GuardianAgent — AI 安全评估
     ↓ (通过)
[第三层] Permission Callback — 用户确认
     ↓ (通过)
执行工具

任何一层拒绝，工具执行立即终止。

第一层：ExecutionFirewall​

ExecutionFirewall 是确定性的安全网关，基于路径规则阻止对敏感系统文件和目录的访问。

被阻止的路径类型：

路径类型示例操作
系统目录C:\Windows\、/etc/、/usr/读写均禁止
程序目录C:\Program Files\、/sbin/读写均禁止
凭据文件.ssh/、.aws/、.gnupg/读写均禁止
SSH 密钥id_rsa、id_ed25519读写均禁止
环境变量.env、.env.production读写均禁止
浏览器数据Chrome/Firefox/Edge 用户数据读写均禁止
注册表System32\config\SAM 等读写均禁止
配置文件.gitconfig、.bashrc、.npmrc可读不可写

第二层：GuardianAgent​

GuardianAgent 使用 LLM 对工具调用进行安全评估。它是可选的，通过配置启用。

工作模式：

模式标识行为
关闭off不启用（零开销）
监控monitor审查敏感工具，仅记录日志，不阻止
守护guard审查敏感工具，阻止高风险和关键风险
严格strict审查所有工具，阻止中等及以上风险

风险等级：

风险等级含义示例
none完全安全读取工作区内文件
low低风险写入项目文件
medium中等风险安装 npm 包、修改状态
high高风险访问敏感路径、网络操作
critical关键风险rm -rf、权限提升、数据窃取

关键规则（始终标记为高/关键风险）：

  • 工作区外的文件删除
  • 递归删除命令
  • 系统目录操作
  • 权限提升（sudo、runas）
  • 管道执行（curl | sh）
  • 凭据访问或窃取
  • 安全功能绕过

错误处理策略：

模式超时/错误时行为
monitor / guard失败开放（允许执行）
strict失败关闭（拒绝执行）

第三层：Permission Callback​

最后一层是用户确认，通过 IPC 消息向前端发送确认请求。

Channel 权限门控​

当 Agent 通过 Channel（Discord、Telegram 等）接收消息时，权限确认流程有所不同。

Channel 用户角色​

角色工具使用确认要求
管理员允许按权限模式决定
成员允许所有工具都需要确认
访客禁止无法使用任何工具

Channel 确认流程​

Channel 会话中的确认不通过桌面对话框，而是通过 Channel 消息：

  1. Agent 请求执行敏感工具
  2. 系统向 Channel 发送确认消息
  3. 用户回复 y（允许）/ n（拒绝）/ always（始终允许）

「始终允许」的作用域限制：

always 回复的范围是按「工具名 + 参数指纹」组合限定的。例如：

  • 允许 Bash: npm test 不会自动允许 Bash: rm -rf /
  • 每个不同的命令/路径组合需要单独授权

超时处理： 5 分钟无响应自动拒绝。每个 Channel 最多同时存在 5 个待确认请求。

审计日志​

所有安全相关事件都会记录到审计日志中，用于事后追溯。

事件类型说明
firewall_blockExecutionFirewall 阻止访问
guardian_reviewGuardianAgent 评审结果
permission_granted用户批准工具执行
permission_denied用户拒绝工具执行
permission_timeout确认超时自动拒绝
command_blockedShell 命令黑名单阻止
injection_detected检测到提示注入
rate_limited速率限制触发

常见问题​

问题原因解决方案
每次都要点确认，太烦了权限模式为 default设为 acceptEdits 或 bypassPermissions
Agent 被 Firewall 阻止了正常操作操作涉及系统路径或凭据文件这是预期行为，不应修改系统文件
GuardianAgent 误判阻止了安全操作评估偏保守将模式从 strict 调整为 guard
Channel 用户无法使用工具用户角色为「访客」将用户提升为「成员」或「管理员」
会话中白名单突然失效会话已结束并重新开始会话白名单不跨会话保留，需重新授权
plan 模式下无法编辑文件plan 模式仅允许只读工具切换到 default 或 acceptEdits 模式

相关链接​