跳到主要内容

安全设置

Elftia 提供多层安全防护机制,保护你的系统免受 Agent 工具调用和外部消息注入的潜在风险。本页详细介绍所有安全相关的配置选项。

安全架构概览​

Elftia 的安全体系包含以下核心组件:

组件位置功能
GuardianAgentAgent 执行层使用 AI 审查工具调用的安全性
PromptGuardianChannel 消息层检测外部消息中的提示词注入攻击
Permission ModeAgent 交互层控制用户是否需要确认工具执行
InputSanitizerChannel 消息层基于规则的输入过滤(正则匹配)
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 的行为模式和潜在的安全威胁,据此调整安全策略。


如需了解更多设置项,请参阅 设置项参考。如在使用过程中遇到安全相关问题,请查阅 常见问题。