触发规则与安全
本页详细介绍 Channel 系统的触发规则配置和安全管线机制。触发规则决定 Agent 何时回复，安全管线决定消息能否到达 Agent。
触发规则
触发规则通过 ChannelTriggerConfig 配置，每个 Channel 实例可以独立设置。
:::info 私信始终触发 无论触发规则如何配置，私信 (DM) 始终会触发 Agent 回复。触发规则仅影响群组聊天中的消息。 :::
all 模式 — 回复所有消息
Agent 对群组中的每一条消息都生成回复。
{
"mode": "all"
}
适用场景：
- 个人专属机器人
- 测试环境
- 只有少数人的小群组
注意： 在活跃的多人群组中使用此模式会导致大量 API 调用，建议搭配速率限制使用。
mention 模式 — @提及时回复
Agent 仅在消息中被 @提及 时回复。未触发的消息会被缓存为上下文（最多 50 条），当触发时一并发送给 Agent，使其了解群组中的对话背景。
{
"mode": "mention",
"mentionName": "Clawia"
}
适用场景：
- 共享 Discord/Slack 服务器
- 多人工作群组
- 不希望机器人过于频繁发言
mentionName 字段： 设置为机器人在平台上的用户名。系统会检查消息内容是否包含 @Clawia（区分大小写）来判断是否触发。
keyword 模式 — 关键词匹配
Agent 在消息包含指定关键词时回复。关键词匹配不区分大小写。
{
"mode": "keyword",
"keywords": ["help", "帮忙", "Clawia"]
}
适用场景：
- 客服场景，用户发送「帮忙」时触发
- 特定话题频道
匹配规则： 只要消息内容中包含任一关键词即触发。例如消息 请帮忙查一下 会匹配关键词 帮忙。
dm_only 模式 — 仅私信
Agent 只回复私信，完全忽略群组消息（不缓存、不回复）。
{
"mode": "dm_only"
}
适用场景：
- 在公开服务器中部署机器人，但只接受一对一对话
- 隐私敏感场景
通用选项
以下选项可与任何触发模式组合使用：
ignoreBot — 忽略自身消息
{
"mode": "all",
"ignoreBot": true
}
当设置为 true 时，机器人自身发送的消息不会触发回复，避免自我对话循环。
allowFrom — 发送者白名单
{
"mode": "all",
"allowFrom": ["123456789", "987654321"]
}
限制只有白名单中的用户才能触发 Agent 回复。allowFrom 中填写平台用户 ID（如 Discord 用户 ID）。
- 空数组或
["*"]表示允许所有人 - ID 匹配不区分大小写
- 此检查优先于触发模式：不在白名单中的用户即使 @提及 机器人也不会触发回复
消息缓存机制
在 mention 和 keyword 模式下，未触发的消息不会被丢弃，而是被缓存到一个滑动窗口中：
- 每个「Channel 实例 + 聊天会话」维护一个独立的消息缓冲区
- 缓冲区最多保存 50 条最近消息（FIFO，先进先出）
- 当触发条件满足时，缓冲区中的所有消息连同触发消息一起发送给 Agent
- 群组消息以 XML 格式封装，包含发送者、时间戳等上下文信息
这让 Agent 在被 @提及 时能够理解群组中的对话背景，而不是只看到单条消息。
安全管线
每条来自外部平台的消息在到达 Agent 之前，都会依次通过 5 个安全层。任何一层拦截消息，后续层不再执行。
消息进入
│
├── [1] RateLimiter ─── 频率超限？→ 静默丢弃
│
├── [2] InputSanitizer ─── 包含控制字符？→ 清除后继续
│
├── [3] PromptGuardian ─── 检测到注入攻击？→ 拦截 + 回复偏转消息
│
├── [4] UserPermissionService ─── 用户角色被禁止？→ 拦截
│
├── [5] ChannelPermissionGate ─── 是权限确认回复？→ 消费该消息
│
└── 触发规则匹配 → 路由到 Agent
第一层：RateLimiter — 速率限制
滑动窗口速率限制器，基于内存实现，无需持久化。
| 配置项 | 默认值 | 说明 |
|---|---|---|
enabled | false | 是否启用速率限制 |
maxPerMinute | 20 | 每用户每分钟最大消息数 |
maxPerHour | 200 | 每用户每小时最大消息数 |
globalMaxPerMinute | 60 | 所有用户合计每分钟最大消息数 |
行为： 超过限制的消息被静默丢弃（不回复、不通知发送者）。
速率限制键： 按 channelId + senderId 进行追踪，即同一用户在同一 Channel 实例中的消息共享限额。
速率限制默认关闭。建议在面向公众的机器人中启用，防止恶意刷屏导致 API 成本飙升。
第二层：InputSanitizer — 输入净化
清除消息中的不可见 Unicode 控制字符，防止编码欺骗和混淆攻击。
| 配置项 | 默认值 | 说明 |
|---|---|---|
enabled | true | 是否启用输入净化 |
stripControlChars | true | 是否清除控制字符 |
清除的字符类型：
- 空字节 (null bytes,
\x00) - 零宽字符 (zero-width spaces,
\u200B-\u200F) - Unicode 双向控制字符 (
\u2028-\u202E) - BOM 标记 (
\uFEFF) - 其他 C0/C1 控制字符（保留常规空白字符如换行、制表符）
行为： 净化后的消息继续传递，原始消息中被清除的字符数会记录到日志。不会拦截消息。
第三层：PromptGuardian — 提示注入检测
使用 AI（LLM）对消息进行语义级别的安全审查，检测提示注入 (prompt injection)、越狱 (jailbreak) 和对抗性操纵。
| 配置项 | 可选值 | 说明 |
|---|---|---|
mode | off / monitor / block | 工作模式 |
工作模式说明：
| 模式 | 行为 |
|---|---|
off | 完全关闭，零开销（默认） |
monitor | 检测并记录，但不拦截消息。用于评估误报率 |
block | 检测到注入时拦截消息，并向发送者回复一条幽默的偏转消息 |
设计原则：
- 失败即放行 (fail-open)：如果 LLM 审查超时（10 秒）或报错，消息自动放行，不会因安全层故障阻塞正常通信
- 短消息（少于 10 个字符）跳过审查
- 安全的消息结果会被缓存（SHA-256 哈希键），避免重复审查
第四层：UserPermissionService — 用户权限
基于角色的访问控制系统。首次发送消息的外部用户会被自动注册为 guest 角色。
角色体系
角色从高到低排列：
| 角色 | 聊天 | 工具执行 | 需要确认 | 管理用户 | 管理设置 |
|---|---|---|---|---|---|
| owner | 允许 | 允许 | 否 | 允许 | 允许 |
| admin | 允许 | 允许 | 否 | 允许 | 否 |
| trusted | 允许 | 允许 | 否 | 否 | 否 |
| member | 允许 | 允许 | 是 | 否 | 否 |
| guest | 允许 | 否 | - | 否 | 否 |
| blocked | 否 | 否 | - | 否 | 否 |
字段说明：
- 聊天：是否允许消息到达 Agent（
canChat） - 工具执行：是否允许触发工具调用，如文件读写、Shell 命令（
canUseTool） - 需要确认：敏感工具（Shell、文件写入）执行前是否需要发送者在 Channel 中确认（
requireConfirmation） - 管理用户：是否可以管理比自己角色低的用户（
canManageUsers） - 管理设置：是否可以修改 Agent 和安全相关设置（
canManageSettings）
默认行为：
- 新用户自动注册为
guest，只能聊天，不能触发工具 blocked用户的消息会被静默丢弃，并收到一条封禁通知- 管理员可以通过 Elftia 界面修改用户角色
第五层：ChannelPermissionGate — 操作确认
当 member 角色的用户触发敏感工具（Shell 命令、文件写入等）时，系统不会直接执行，而是在 Channel 中发送确认请求：
⚠️ Permission Required
Clawia wants to execute: **Shell Command**
> npm test
Reply: **y** (approve) / **n** (deny) / **always** (always allow this tool)
⏱ Auto-denied in 5 minutes. [confirm-xxx]
确认回复选项：
| 回复 | 效果 |
|---|---|
y / yes / ok / 确认 / はい | 批准本次执行 |
n / no / cancel / 拒绝 / いいえ | 拒绝本次执行 |
always / 始终允许 / 常に許可 | 批准并记住此工具+参数的组合，后续自动批准 |
关键细节：
- 确认请求 5 分钟超时后自动拒绝
- 每个 Channel + 聊天会话最多 5 个待处理确认
always的作用范围精确到工具+参数组合（例如「始终允许 Bash: npm test」不会自动批准「Bash: rm -rf /」）owner、admin、trusted角色无需确认，直接执行guest角色根本不能触发工具，不会到达确认环节
安全配置建议
个人使用
{
"rateLimiter": { "enabled": false },
"sanitizer": { "enabled": true },
"promptGuardian": { "mode": "off" }
}
个人使用无需严格安全。保持输入净化开启即可。
小团队
{
"rateLimiter": { "enabled": true, "maxPerMinute": 30, "maxPerHour": 300 },
"sanitizer": { "enabled": true },
"promptGuardian": { "mode": "monitor" }
}
启用速率限制防止误操作刷屏。PromptGuardian 先用 monitor 模式评估误报率。
面向公众
{
"rateLimiter": { "enabled": true, "maxPerMinute": 10, "maxPerHour": 100 },
"sanitizer": { "enabled": true },
"promptGuardian": { "mode": "block" }
}
全面启用安全管线。严格的速率限制 + 提示注入拦截。建议搭配 allowFrom 白名单或 mention 触发模式使用。