安全设置
Elftia 提供多层安全防护机制，保护你的系统免受 Agent 工具调用和外部消息注入的潜在风险。本页详细介绍所有安全相关的配置选项。
安全架构概览
Elftia 的安全体系包含以下核心组件：
| 组件 | 位置 | 功能 |
|---|---|---|
| GuardianAgent | Agent 执行层 | 使用 AI 审查工具调用的安全性 |
| PromptGuardian | Channel 消息层 | 检测外部消息中的提示词注入攻击 |
| Permission Mode | Agent 交互层 | 控制用户是否需要确认工具执行 |
| InputSanitizer | Channel 消息层 | 基于规则的输入过滤（正则匹配） |
| AuditLogger | 全局 | 记录所有安全事件的审计日志 |
GuardianAgent
GuardianAgent 是一个基于 AI 的安全审查模块。当 Agent 执行工具调用时，GuardianAgent 会先用一个独立的 LLM 评估该操作的风险等级，根据配置决定是否允许执行。
四种模式
| 模式 | 行为 | 推荐场景 |
|---|---|---|
| 关闭 (off) | 完全禁用，零性能开销 | 个人使用，信任 Agent 行为 |
| 监控 (monitor) | 审查敏感工具调用，仅记录日志不阻止 | 想了解 Agent 行为但不希望被打断 |
| 守卫 (guard) | 审查敏感工具调用，阻止高风险和关键风险操作 | 日常使用，平衡安全和便利 |
| 严格 (strict) | 审查所有工具调用，阻止中等及以上风险操作 | 共享环境，最高安全要求 |
风险等级
GuardianAgent 将工具调用分为五个风险等级：
| 风险等级 | 含义 | 示例 |
|---|---|---|
| 无 (none) | 完全安全 | 读取项目内的文件、列出目录 |
| 低 (low) | 轻微风险 | 在工作区内写入项目文件 |
| 中 (medium) | 中等风险 | 执行修改系统状态的 Shell 命令、安装 npm 包 |
| 高 (high) | 重大风险 | 访问敏感路径、操作工作区外的文件、网络操作 |
| 关键 (critical) | 即时危险 | 递归删除命令、数据窃取、权限提升 |
各模式的阻止行为
| 风险等级 | 关闭 | 监控 | 守卫 | 严格 |
|---|---|---|---|---|
| none | 放行 | 放行 | 放行 | 放行 |
| low | 放行 | 记录+放行 | 放行 | 放行 |
| medium | 放行 | 记录+放行 | 放行 | 阻止 |
| high | 放行 | 记录+放行 | 阻止 | 阻止 |
| critical | 放行 | 记录+放行 | 阻止 | 阻止 |
敏感工具
在监控和守卫模式下，只有以下「敏感工具」会触发安全审查：
- Bash：Shell 命令执行
- Write：文件写入
- Edit：文件编辑
- Agent：子 Agent 生成
严格模式下，所有工具调用（包括读取文件等）都会触发审查。
容错设计
| 模式 | 超时/错误时的行为 |
|---|---|
| 监控 / 守卫 | 放行（fail-open）— 审查不可用时不阻止正常操作 |
| 严格 | 阻止（fail-closed）— 审查不可用时默认拒绝 |
审查超时为 15 秒。如果 LLM 在 15 秒内未返回审查结果，按上述规则处理。
配置位置
设置 → Clawia → GuardianAgent 模式
选择所需的模式即可。切换后立即生效，无需重启。
审计日志
所有审查结果（无论是否阻止）都会记录到审计日志中。你可以在 设置 → Clawia → 审计日志 中查看历史审查记录，包括：
- 时间戳
- 工具名称和参数
- 审查结果（风险等级、原因）
- 是否阻止
PromptGuardian
PromptGuardian 是针对 Channel（多平台渠道）消息的安全防护。当 Elftia 通过 Discord、Telegram 等渠道接收外部用户的消息时，PromptGuardian 会使用 AI 检测消息中是否包含提示词注入攻击。
三种模式
| 模式 | 行为 | 推荐场景 |
|---|---|---|
| 关闭 (off) | 不检测注入 | 仅自己使用 Channel，信任所有消息来源 |
| 监控 (monitor) | 检测注入，记录日志但不阻止 | 想观察是否有可疑消息 |
| 阻止 (block) | 检测注入，拦截可疑消息并返回友好拒绝消息 | 公开 Channel，需要防御恶意用户 |
检测内容
PromptGuardian 能检测以下类型的攻击：
- 指令覆盖：尝试覆盖或绕过系统指令（如「忽略以上所有指令」）
- 角色操纵：伪装其他身份（如「你现在是 DAN」）
- 提示词标记注入：插入系统/指令标记（如
[INST]、<|im_start|>） - 提示词提取：试图获取系统提示词内容
- XML/标记注入：注入工具调用标记（如
<tool_use>、<function_calls>） - 编码绕过：使用 base64 编码、不可见字符等技巧
- 社工攻击：以「教育目的」「假设场景」等理由绕过安全规则
- 多步攻击：跨多条消息逐步构建攻击
阻止时的行为
当消息被阻止时，PromptGuardian 不会向用户透露安全检测的存在，而是返回一条随机的友好拒绝消息（如「电波断了喵～换个话题吧」），避免攻击者据此调整策略。
容错设计
PromptGuardian 采用 fail-open 设计：如果审查超时（10 秒）或出错，消息会正常放行，不会因安全检测的故障而中断消息流。
配置位置
PromptGuardian 的配置位于 Channel 安全设置中。需要先配置用于安全审查的 LLM 提供商和模型。
Permission Mode（权限模式）
权限模式控制 Agent 在执行工具调用时是否需要用户确认。
| 模式 | 行为 | 适用场景 |
|---|---|---|
| 默认 (default) | 敏感操作需要用户确认 | 日常使用，推荐 |
| 接受编辑 (acceptEdits) | 文件编辑自动通过，其他操作仍需确认 | 信任 Agent 的代码编辑能力 |
| 跳过确认 (bypassPermissions) | 所有操作自动通过 | 高度信任 Agent，追求最大效率 |
| 仅规划 (plan) | Agent 只制定计划，不执行任何操作 | 审查 Agent 的行为计划 |
「跳过确认」模式会让 Agent 直接执行所有操作（包括 Shell 命令和文件删除）。仅在你完全信任 Agent 行为且在安全的环境中使用。建议配合 GuardianAgent 的「守卫」或「严格」模式使用。
Channel 安全设置
当你通过 Channel 连接外部平台时，可以配置以下安全选项：
速率限制
| 设置项 | 说明 |
|---|---|
| 消息速率限制 | 限制每个用户在特定时间窗口内的最大消息数量 |
| 全局速率限制 | 限制 Channel 的总消息处理速率 |
输入过滤
InputSanitizer 提供基于正则表达式的输入过滤（在 PromptGuardian 之前执行）：
- 过滤已知的恶意模式
- 清理潜在的注入标记
- 仅产生警告日志，不阻止消息
用户角色
Channel 可以为不同的用户分配角色，控制访问权限。
安全配置建议
个人使用
如果 Elftia 仅供你个人使用，不对外提供服务：
| 设置 | 推荐值 |
|---|---|
| GuardianAgent | 关闭 或 监控 |
| PromptGuardian | 关闭 |
| Permission Mode | 默认 |
共享 Channel
如果你的 Channel 对外开放，其他用户可以发送消息：
| 设置 | 推荐值 |
|---|---|
| GuardianAgent | 守卫 或 严格 |
| PromptGuardian | 阻止 |
| Permission Mode | 默认 |
| 速率限制 | 启用 |
开发调试
在开发和测试场景中：
| 设置 | 推荐值 |
|---|---|
| GuardianAgent | 监控 |
| PromptGuardian | 监控 |
| Permission Mode | 接受编辑 |
这样可以在审计日志中观察安全事件，同时不影响开发效率。
审计日志
所有安全事件都会记录在审计日志中，你可以在 设置 → Clawia → 审计日志 中查看。
日志记录的信息包括：
| 字段 | 说明 |
|---|---|
| 时间 | 事件发生时间 |
| 类型 | GuardianAgent / PromptGuardian / Permission |
| 操作 | 具体的工具名称或消息来源 |
| 结果 | 允许 / 阻止 |
| 详情 | 风险等级、原因说明等 |
定期查看审计日志可以帮助你了解 Agent 的行为模式和潜在的安全威胁，据此调整安全策略。