古法编程

Appearance

群组消息处理依赖 `groupPolicy`、群组白名单和提及门控三个层级的配置。默认 `groupPolicy: "allowlist"` 且 `requireMention: true`，意味着只有白名单内的用户 @提及 OpenClaw 后才会回复。要禁用所有群组回复，设置 `groupPolicy: "disabled"`；要允许所有群组但要求 @提及，使用 `groups: { "*": { requireMention: true } }`。注意 DM 配对审批不覆盖群组授权，群组发送者必须显式配置在白名单中。

OpenClaw 群组配置：策略、提及门控与白名单设置 ​

OpenClaw 在各消息渠道中以一致的逻辑处理群组聊天消息，支持的渠道包括 Discord、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo。其行为可概括为：OpenClaw 依附于你的个人账号，如果你在某个群组里，智能体就能看到该群组并可选择是否回复。

新手入门：黑盒变白名单 ​

默认情况下，群组回复是受限的：

  • groupPolicy: "allowlist"：群组默认不开放，仅白名单内的群组或用户能触发。
  • requireMention: true：即使在允许的群组中，也需要 @提及智能体才会回复。

简而言之：白名单用户 + 明确 @提及 = 回复。

消息处理流程示意图：

groupPolicy: disabled -> 丢弃消息
groupPolicy: allowlist -> 群组不在白名单内 -> 丢弃消息
requireMention: yes -> 未被 @提及 -> 仅存入上下文，不回复
满足条件 -> 转为用户请求，开始处理

快速对照表

目标配置方式
允许所有群组但只响应 @提及groups: { "*": { requireMention: true } }
完全禁用所有群组回复groupPolicy: "disabled"
只允许特定群组回复在 groups 下列出群组 ID，不要包含 "*" 键
只允许你自己在群组中触发groupPolicy: "allowlist" + groupAllowFrom: ["+15551234567"]
复用一套可信发送者白名单groupAllowFrom: ["accessGroup:operators"]（参见访问组）

群组策略 ​

groupPolicy 在每个渠道下独立配置，决定是否处理群组消息。

json5
{
  channels: {
    whatsapp: {
      groupPolicy: "disabled", // "open" | "disabled" | "allowlist"
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "disabled",
      groupAllowFrom: ["123456789"], // Telegram 用户数字 ID
    },
    signal: {
      groupPolicy: "disabled",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "disabled",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "disabled",
      groupAllowFrom: ["user@org.com"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: { channels: { help: { allow: true } } },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
    matrix: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["@owner:example.org"],
      groups: {
        "!roomId:example.org": { enabled: true },
        "#alias:example.org": { enabled: true },
      },
    },
  },
}
策略行为说明
"open"绕过群组白名单，但仍受提及门控约束。
"disabled"完全丢弃群组消息，不处理。
"allowlist"仅处理白名单内的群组/房间消息。

注意事项

  • groupPolicy 与提及门控是独立的两个控制层。
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo 使用 groupAllowFrom 作为发送者白名单；若无配置，回退使用 allowFrom。
  • DM 配对审批（*-allowFrom 存储条目）只控制私信访问，不适用于群组。群组发送者必须通过 groupAllowFrom 或渠道特定的群组白名单授权。
  • Discord 的群组白名单配置在 channels.discord.guilds.<id>.channels；Slack 在 channels.slack.channels；Matrix 在 channels.matrix.groups。Matrix 中优先使用房间 ID 或别名，已加入的房间名查找是尽力而为，未解析的名称在运行时会被忽略。
  • Telegram 白名单支持用户 ID 前缀（如 "123456789"、"telegram:123456789"、"tg:123456789"）或 @username（如 "@alice"，@ 可选），前缀不区分大小写。
  • 默认值为 groupPolicy: "allowlist"。若群组白名单为空，群组消息全部被拦截。
  • 运行时安全：如果某个渠道的配置块完全缺失（channels.<provider> 不存在），该渠道的群组策略会自动回退到故障关闭模式（通常为 allowlist），而不是继承 channels.defaults.groupPolicy。

提及门控（默认行为） ​

群组消息默认需要 @提及，除非针对特定群组取消该要求。门控检测的优先级为：原生平台提及 > 自定义 mentionPatterns。

json5
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },
      },
    },
    telegram: {
      groups: {
        "*": { requireMention: true },
        "123456789": { requireMention: false },
      },
    },
    imessage: {
      groups: {
        "*": { requireMention: true },
        "123": { requireMention: false },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"],
          historyLimit: 50,
        },
      },
    ],
  },
}

关键点

  • mentionPatterns 是不区分大小写的安全正则表达式。无效模式或不安全的嵌套重复形式会被静默忽略。
  • 对于支持原生 @提及的渠道（如 Slack、Discord），原生提及优先；mentionPatterns 作为后备方案。
  • 当多个智能体共享一个群组时，可以通过 agents.list[].groupChat.mentionPatterns 为每个智能体独立配置提及模式。
  • 即使群组已被白名单允许，提及门控仍然生效。如需允许所有消息触发回复，需要将对应群组的 requireMention 设为 false。
  • 群组历史上下文只包含因提及门控而跳过的挂起消息。使用 messages.groupChat.historyLimit 控制全局历史消息数量；渠道级别可通过 channels.<channel>.historyLimit 覆盖；设为 0 禁用。

可见回复与 Message Tool ​

默认情况下，群组请求使用可见回复（messages.groupChat.visibleReplies: "automatic"）。若希望智能体自行决定何时发言（通过调用 message(action=send)），可配置为 "message_tool"。

重要限制：message_tool 模式要求底层模型能稳定使用工具。如果模型在本轮未调用消息工具但输出了最终文案，OpenClaw 会将该文案保留在内部，不会发送到群组。若当前工具策略下消息工具不可用，OpenClaw 会回退到自动可见回复，openclaw doctor 命令会对此发出警告。

对于原生支持斜杠命令的渠道（Discord、Telegram），这些命令会绕过 visibleReplies: "message_tool"，始终以可见方式回复，以确保平台 UI 能正常获得响应。仅对已验证的原生命令回合生效；文本输入的 /... 命令仍遵循群组默认配置。

配置示例（消息工具模式，热加载生效）：

json5
{
  messages: {
    groupChat: {
      visibleReplies: "message_tool",
    },
  },
}

全局生效（对所有来源会话生效）：

json5
{
  messages: {
    visibleReplies: "message_tool",
  },
}

上下文可见性与白名单 ​

群组安全涉及两个独立的控制维度：

  • 触发授权：通过 groupPolicy、groups、groupAllowFrom 决定谁能触发智能体。
  • 上下文可见性：决定哪些补充上下文（回复文本、引用、历史记录、转发元数据）被注入到模型中。

当前，OpenClaw 对补充上下文的处理因渠道而异（部分渠道做了发送者过滤，部分未做）。计划中的强化方向引入了 contextVisibility 配置（"all" / "allowlist" / "allowlist_quote"），但目前还未在所有渠道一致实现。

模式：个人私信 + 公开群组（单智能体） ​

该模式适合个人流量通过私信、公开流量通过群组的场景。在单智能体模式下，私信会落在主会话（agent:main:main），群组总是使用非主会话（agent:main:<channel>:group:<id>）。通过 sandbox.mode: "non-main"，可以让群组会话运行在沙箱中而私信会话保持在宿主机上，实现“一个大脑，两种执行姿态”。

完整配置示例：

json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // 群组/频道 -> 沙箱化
        scope: "session", // 每个群组/频道使用独立容器
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["group:messaging", "group:sessions"], // 仅允许消息类和会话类工具
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}

如需向沙箱挂载宿主机特定目录而非完全禁止访问，使用 docker.binds：

json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          binds: ["/home/user/FriendsShared:/data:ro"],
        },
      },
    },
  },
}

相关配置：openclaw doctor 可检查工具是否被拦截；参见沙箱 vs 工具策略 vs 提权。

群组工具限制（可选） ​

对特定群组/频道可单独设置工具访问权限，配置在 groups 或 channels 子项下。

  • tools：为整个群组设置 allow/deny 列表。
  • toolsBySender：按发送者覆盖工具策略。键前缀支持 id:、e164:、username:、name: 及通配符 "*"。

解析顺序（越具体优先越高）：

  1. 群组内的 toolsBySender 匹配
  2. 群组 tools 列表
  3. 默认 "*" 的 toolsBySender 匹配
  4. 默认 "*" 的 tools 列表

示例（Telegram 群组，默认禁止执行，但允许特定发送者）：

json5
{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },
          },
        },
      },
    },
  },
}

注意：群组/频道工具限制在全局和智能体工具策略之上额外生效，deny 始终优先生效。

群组白名单 ​

当配置了 channels.whatsapp.groups、channels.telegram.groups 等键时，这些键充当群组 ID 白名单。"*" 表示允许所有群组，但仍受默认提及门控约束。

常用配置模板 ​

禁用所有群组回复

json5
{ channels: { whatsapp: { groupPolicy: "disabled" } } }

仅允许特定群组（WhatsApp）

json5
{
  channels: {
    whatsapp: {
      groups: {
        "123@g.us": { requireMention: true },
        "456@g.us": { requireMention: false },
      },
    },
  },
}

允许所有群组但要求 @提及

json5
{
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

仅群主可在群组中触发（WhatsApp）

json5
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
      groups: { "*": { requireMention: true } },
    },
  },
}

会话密钥 ​

  • 群组会话：agent:<agentId>:&lt;channel&gt;:group:&lt;id&gt;
  • 频道/房间会话：agent:<agentId>:&lt;channel&gt;:channel:&lt;id&gt;
  • Telegram 论坛话题会追加 :topic:<threadId>
  • 群组会话不发送心跳

激活命令（仅群主） ​

群主可在群中通过 /activation 命令切换该群的激活模式：

  • /activation mention：仅响应 @提及（默认）
  • /activation always：响应所有消息

群主身份由 channels.whatsapp.allowFrom 决定，若未配置则使用 Bot 自身号码。该命令需作为独立消息发送。其他渠道目前暂不支持 /activation。

iMessage 专项说明 ​

  • 白名单中优先使用 chat_id:&lt;id&gt; 格式
  • 列出所有聊天：imsg chats --limit 20
  • 群组回复始终回到同一 chat_id

常见问题 ​

怎么禁止 OpenClaw 回复所有群消息？ ​

在对应渠道的配置中设置 groupPolicy: "disabled"。注意，为安全起见，请在配置中确实移除或覆盖该字段，避免因配置块缺失导致 fallback 到允许模式。

为什么在群组里 @OpenClaw 没有回复？ ​

请依次检查：(1) groupPolicy 是否为 allowlist 或 open；(2) 该群组 ID 是否在 groups 或 groupAllowFrom 白名单中；(3) 提及门控 requireMention 是否开启，以及 mentionPatterns 是否正确配置（尤其注意正则表达式不要写错）。使用 openclaw doctor 命令可帮助诊断工具策略冲突。

场景：Bot 在私信里可以执行代码，但在群里只能发消息和查会话，怎么配置？ ​

启用沙箱的 mode: "non-main"，并在 tools.sandbox.tools 中只放行 group:messaging 和 group:sessions 工具，其他工具全部设为 deny。这样私信运行在宿主机上拥有完整权限，群组会话运行在沙箱中且工具受限。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策