群组消息 - 群聊中使用 Agent

OpenClaw 的 Agent（智能体）不仅支持一对一私信，还可以加入群组聊天，在团队协作场景中提供智能辅助。本文介绍群组消息的工作机制和配置方式。

Agent 在群组中的工作方式

当 Agent 被添加到群组后，它会监听群组中的消息。但默认情况下，Agent 不会响应每一条消息——它只在被 @mention（@提及）时才会回复。

群组聊天                              Agent 行为
─────────                            ──────────
Alice: 今天下午开会讨论方案              → 忽略（未被提及）
Bob: 好的，我准备下资料                  → 忽略（未被提及）
Alice: @OpenClaw 帮我总结下昨天的会议纪要  → 响应（被 @提及）
Agent: 好的，以下是昨天会议纪要的摘要...   → 发送回复
Charlie: 谢谢！                         → 忽略（未被提及）

为什么默认需要 @mention？

在活跃的群组中，如果 Agent 响应每条消息，会产生大量无关回复，干扰正常对话。@mention 机制确保 Agent 只在被明确召唤时才参与讨论。

Mention Gating（@提及触发）

Mention Gating（@提及触发机制）控制 Agent 是否需要被 @mention 才响应。

配置

yaml

channels:
  telegram:
    enabled: true
    groups:
      - id: "group_12345"
        requireMention: true    # 默认值：需要 @mention 才响应
      - id: "group_67890"
        requireMention: false   # 响应群组中的所有消息

触发方式

不同平台的 @mention 方式略有差异：

平台	触发方式	示例
Telegram	@机器人用户名	`@my_openclaw_bot 你好`
Slack	@App名称	`@OpenClaw 帮我查下数据`
Discord	@Bot名称	`@OpenClaw 总结讨论`
飞书	@机器人名称	`@OpenClaw 创建任务`
企业微信	@机器人名称	`@OpenClaw 查询工单`
钉钉	@机器人名称	`@OpenClaw 发送周报`

动态切换

可以通过 CLI 命令动态切换 Mention Gating：

bash

# 查看当前激活模式
openclaw activation status

# 切换为需要 mention（默认）
openclaw activation mention --require

# 切换为不需要 mention（响应所有消息）
openclaw activation mention --disable

# 针对特定群组切换
openclaw activation mention --require --group "group_12345"

Group Policy（群组策略）

Group Policy（群组策略）控制 Agent 可以加入哪些群组：

三种策略

open — 开放disabled — 禁用allowlist — 白名单

yaml

channels:
  telegram:
    enabled: true
    groupPolicy: open
    # Agent 可以被添加到任何群组
    # 适合公共服务型 Agent

yaml

channels:
  slack:
    enabled: true
    groupPolicy: disabled
    # Agent 不接受任何群组消息
    # 仅支持 DM（私信）交互

yaml

channels:
  feishu:
    enabled: true
    groupPolicy: allowlist
    groups:
      - id: "oc_group_001"    # 只允许特定群组
      - id: "oc_group_002"
    # 未在列表中的群组消息会被忽略

策略	行为	适用场景
`open`	接受所有群组邀请和消息	公共/内部通用 Agent
`disabled`	忽略所有群组消息	仅私信交互的 Agent
`allowlist`	仅响应白名单中的群组	企业内部指定群组

注意

open 策略下，任何人都可以将你的 Agent 拉入群组，这意味着 Agent 可能在不受控的环境中被使用。建议生产环境使用 allowlist 策略。

会话隔离

Group Session（群组会话）与 DM Session（私信会话）是完全隔离的：

┌──────────────────────┐    ┌──────────────────────┐
│   DM Session          │    │   Group Session       │
│   main:::dm:tg:alice  │    │   main:::group:tg:g1  │
│                       │    │                       │
│   上下文：Alice 的私聊  │    │   上下文：群组 g1 的讨论 │
│   工具：完整权限         │    │   工具：可能受限         │
│   历史：仅 Alice 的消息  │    │   历史：群组所有消息     │
└──────────────────────┘    └──────────────────────┘
         ↕ 完全隔离 ↕

隔离的含义：

上下文不共享：Agent 在群组中不会引用私信中的对话内容，反之亦然
工具权限独立：群组会话可以限制可用工具（见下方沙箱机制）
消息历史独立：每个会话维护自己的消息历史
Memory（记忆）独立：长期记忆按会话隔离存储

工具沙箱（Sandboxing）

群组环境中，你可能不希望 Agent 执行所有工具操作。Sandboxing（沙箱机制）允许你限制群组会话中可用的工具。

非主模式（Non-main Mode）

yaml

channels:
  telegram:
    groups:
      - id: "group_12345"
        mode: "non-main"    # 非主模式：限制高危工具

non-main 模式下，以下类型的工具会被自动禁用：

文件系统操作（读写删除文件）
系统命令执行
数据库写入操作
外部 API 的写入/删除请求

自定义工具限制

更精细的控制可以使用 tools 和 toolsBySender 配置：

按群组限制工具按发送者限制工具

yaml

channels:
  slack:
    groups:
      - id: "C04GENERAL"
        tools:
          allow:             # 白名单：仅允许这些工具
            - "search"
            - "summarize"
            - "translate"
          deny:              # 黑名单：禁止这些工具
            - "file_write"
            - "system_exec"
            - "db_*"         # 支持通配符

yaml

channels:
  feishu:
    groups:
      - id: "oc_dev_team"
        toolsBySender:
          # 管理员可以使用所有工具
          "ou_admin_001":
            allow: ["*"]
          # 普通成员只能使用查询类工具
          default:
            allow:
              - "search"
              - "query_*"
            deny:
              - "file_*"
              - "system_*"

安全提示

在公开或半公开群组中，强烈建议启用工具沙箱。未限制工具的群组 Agent 可能被恶意用户利用执行危险操作。

Context Fields（上下文字段）

群组消息会携带额外的 Context Fields（上下文字段），供 Agent 和工具使用：

json

{
  "ChatType": "group",
  "WasMentioned": true,
  "GroupId": "group_12345",
  "GroupName": "产品团队讨论群",
  "SenderId": "user_alice",
  "SenderName": "Alice",
  "MessageId": "msg_abc123",
  "ReplyTo": "msg_xyz789",
  "ThreadId": "thread_001"
}

字段	类型	说明
`ChatType`	`string`	会话类型：`"dm"` 或 `"group"`
`WasMentioned`	`boolean`	Agent 是否被 @mention
`GroupId`	`string`	群组唯一 ID
`GroupName`	`string`	群组显示名称
`SenderId`	`string`	消息发送者 ID
`SenderName`	`string`	消息发送者显示名称
`MessageId`	`string`	消息唯一 ID
`ReplyTo`	`string`	被回复消息的 ID（如果是回复消息）
`ThreadId`	`string`	话题/线程 ID（支持 Thread 的平台）

在 Prompt 中使用上下文

yaml

agents:
  main:
    systemPrompt: |
      你是一个团队助手。
      {% if context.ChatType == "group" %}
      你正在群组「{{ context.GroupName }}」中对话。
      请注意简洁回复，避免刷屏。
      仅回复与你被提及相关的内容。
      {% else %}
      你正在与用户进行一对一私聊。
      可以提供详细的回复。
      {% endif %}

Activation Commands（激活命令）

在群组中，你可以通过命令动态控制 Agent 的行为：

bash

# 在群聊中发送以下命令（需要管理员权限）：

/openclaw mention on       # 开启 @mention 触发（默认）
/openclaw mention off      # 关闭 @mention 触发（响应所有消息）
/openclaw status           # 查看 Agent 在当前群组的状态
/openclaw tools            # 查看当前群组可用的工具列表
/openclaw pause            # 暂停 Agent（停止响应）
/openclaw resume           # 恢复 Agent

最佳实践

默认启用 requireMention：避免 Agent 在群组中产生不必要的回复
使用 allowlist 策略：在生产环境中控制 Agent 可以加入的群组
启用工具沙箱：群组会话中限制高危工具的访问权限
按群组定制行为：不同群组可以有不同的工具权限和触发规则
监控群组活跃度：使用 openclaw sessions list --type group 监控群组会话

🇨🇳 中国用户须知

飞书群组接入： 飞书机器人在群组中默认需要被 @mention 才会响应，这与 OpenClaw 的默认行为一致。飞书还支持「消息卡片」交互，OpenClaw 会自动将富文本回复转换为飞书卡片格式。

企业微信群聊： 企业微信群机器人有两种模式——Webhook 机器人（仅能发送消息）和应用机器人（可以接收和回复消息）。OpenClaw 使用应用机器人模式，支持完整的双向交互。

钉钉群组： 钉钉群机器人支持「互动卡片」，OpenClaw 可以利用此功能提供按钮式交互体验。在钉钉群组中，Agent 默认通过 @mention 触发。

群组消息的合规提醒： 如果 Agent 在群组中处理敏感信息（如客户数据、财务数据），请确保群组成员都经过授权，并在 Agent 的 System Prompt 中加入合规提示。

群组消息 - 群聊中使用 Agent ​

Agent 在群组中的工作方式 ​

Mention Gating（@提及触发） ​

配置 ​

触发方式 ​

动态切换 ​

Group Policy（群组策略） ​

三种策略 ​

会话隔离 ​

工具沙箱（Sandboxing） ​

非主模式（Non-main Mode） ​

自定义工具限制 ​

Context Fields（上下文字段） ​

在 Prompt 中使用上下文 ​

Activation Commands（激活命令） ​

最佳实践 ​

群组消息 - 群聊中使用 Agent

Agent 在群组中的工作方式

Mention Gating（@提及触发）

配置

触发方式

动态切换

Group Policy（群组策略）

三种策略

会话隔离

工具沙箱（Sandboxing）

非主模式（Non-main Mode）

自定义工具限制

Context Fields（上下文字段）

在 Prompt 中使用上下文

Activation Commands（激活命令）

最佳实践