工具权限与安全
Elftia 的 Agent 系统在赋予 AI 强大执行能力的同时，也提供了多层安全防护机制。本文详细介绍权限模式、工具敏感度分类、确认对话框流程以及各安全层的工作方式。
权限模式
权限模式（Permission Mode）决定了 Agent 执行工具时的安全级别。可以在 Agent 配置的 permissionMode 字段中设置。
模式一览
| 模式 | 标识 | 行为 | 适用场景 |
|---|---|---|---|
| 默认 | default | 敏感工具需要用户逐一确认 | 日常使用，安全第一 |
| 接受编辑 | acceptEdits | 文件读写自动通过，Shell/MCP 仍需确认 | 编程场景，信任文件操作 |
| 绕过权限 | bypassPermissions | 所有工具自动执行 | 完全信任 Agent |
| 只读模式 | plan | 仅允许只读工具 | 信息收集、分析、规划 |
模式行为对比
| 工具 | default | acceptEdits | bypassPermissions | plan |
|---|---|---|---|---|
| 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 消息：
- Agent 请求执行敏感工具
- 系统向 Channel 发送确认消息
- 用户回复
y（允许）/n（拒绝）/always（始终允许）
「始终允许」的作用域限制：
always 回复的范围是按「工具名 + 参数指纹」组合限定的。例如：
- 允许
Bash: npm test不会自动允许Bash: rm -rf / - 每个不同的命令/路径组合需要单独授权
超时处理： 5 分钟无响应自动拒绝。每个 Channel 最多同时存在 5 个待确认请求。
审计日志
所有安全相关事件都会记录到审计日志中，用于事后追溯。
| 事件类型 | 说明 |
|---|---|
firewall_block | ExecutionFirewall 阻止访问 |
guardian_review | GuardianAgent 评审结果 |
permission_granted | 用户批准工具执行 |
permission_denied | 用户拒绝工具执行 |
permission_timeout | 确认超时自动拒绝 |
command_blocked | Shell 命令黑名单阻止 |
injection_detected | 检测到提示注入 |
rate_limited | 速率限制触发 |
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 每次都要点确认，太烦了 | 权限模式为 default | 设为 acceptEdits 或 bypassPermissions |
| Agent 被 Firewall 阻止了正常操作 | 操作涉及系统路径或凭据文件 | 这是预期行为，不应修改系统文件 |
| GuardianAgent 误判阻止了安全操作 | 评估偏保守 | 将模式从 strict 调整为 guard |
| Channel 用户无法使用工具 | 用户角色为「访客」 | 将用户提升为「成员」或「管理员」 |
| 会话中白名单突然失效 | 会话已结束并重新开始 | 会话白名单不跨会话保留，需重新授权 |
| plan 模式下无法编辑文件 | plan 模式仅允许只读工具 | 切换到 default 或 acceptEdits 模式 |
相关链接
- Agent 概览 — Agent 系统总览
- 创建自定义 Agent — 配置权限模式
- 技能系统 — 技能的工具白名单