跳转至

配置 — 社区聊天频道

channels.* 键用于社区聊天频道:Discord、Matrix 和 IRC。

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: true,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { enabled: true },
            help: {
              enabled: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      suppressEmbeds: true,
      streaming: {
        mode: "progress", // explicit opt-in; Discord defaults to off
        chunkMode: "length", // length | newline
        progress: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
        },
      },
      maxLinesPerMessage: 17,
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
            whenOccupied: true,
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          providers: { openai: { speakerVoice: "alloy" } },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
    },
  },
}
  • Token:channels.discord.token,对于默认帐户,以 DISCORD_BOT_TOKEN 作为回退。
  • channels.discord.joinIntro 默认为 true。当机器人加入允许的服务器时,它会在系统频道(如果允许)或第一个它可以查看并发送消息的文本频道中发布一条介绍。仅在机器人可以读取消息历史时包含最近的消息。将此选项设为 false 可禁用介绍,或使用 channels.discord.accounts.<accountId>.joinIntro 进行特定于帐户的覆盖。在允许的情况下,每个服务器最多读取 100 条最近消息(每服务器一次);参见 群组加入介绍。介绍绝不会在私信中运行。
  • 提供显式 Discord token 的直接出站调用将使用该令牌进行调用;帐户策略设置仍来自活动运行时快照中的选定帐户。
  • 可选的 channels.discord.defaultAccount 在匹配已配置的帐户 id 时覆盖默认帐户选择。
  • 使用 user:<id>(私信)或 channel:<id>(服务器频道)作为投递目标;裸数字 ID 会被拒绝。
  • actions.reactions 控制 react、reactions 和 emoji-list;除非提供了 guildId,表情符号发现默认为当前服务器。
  • 服务器 slug 为小写,空格替换为 -;频道键使用 slug 化名称(不含 #)。优先使用服务器 ID。
  • 在正常的提及和访问规则下,机器人编写的消息默认被接受。设置 allowBots: false 以禁用机器人触发的轮次,或设置 allowBots: "mentions" 以要求主动提及机器人(自己的消息仍会被过滤)。此设置不会从历史记录或人工选择的回复目标中隐藏可访问的机器人消息;contextVisibility 控制补充上下文。
  • 支持机器人编写入站消息的频道可以使用共享的 机器人循环保护。为基线配对预算设置 channels.defaults.botLoopProtection,然后仅在某个表面需要不同限制时覆盖频道或帐户。
  • channels.discord.guilds.<id>.ignoreOtherMentions(以及频道覆盖)会丢弃发送给其他身份而非机器人的消息。这涵盖明确的用户/角色提及(不包括 @everyone/@here)以及回复另一个非 webhook 机器人的消息;明确提及当前机器人仍然有效。
  • channels.discord.mentionAliases 在发送前将稳定的出站 @handle 文本映射到 Discord 用户 ID,这样即使临时目录缓存为空,也能确定性地提及已知队友。按帐户的覆盖位于 channels.discord.accounts.<accountId>.mentionAliases 下。
  • maxLinesPerMessage(默认 17)会将较长的消息拆分,即使字符数少于 2000。
  • channels.discord.suppressEmbeds 默认为 true,因此出站 URL 不会展开为 Discord 链接预览,除非禁用。显式的 embeds 负载仍然正常发送;每消息工具调用可以使用 suppressEmbeds 覆盖。
  • channels.discord.threadBindings 控制 Discord 线程绑定路由:
  • enabled:Discord 对线程绑定会话生成、投递和路由的覆盖;使用 /session unbind、/agents、/session idle 和 /session max-age 管理绑定
  • idleHours:Discord 对非活动自动解除绑定的小时数覆盖(0 禁用)
  • maxAgeHours:Discord 对硬性最大存续小时数的覆盖(0 禁用)
  • spawnSessions:sessions_spawn({ thread: true }) 和 ACP 线程生成自动线程创建/绑定的开关(默认 true)
  • defaultSpawnContext:线程绑定生成的原生子代理上下文(默认 "fork")
  • 顶层 bindings[] 条目中 type: "acp" 为频道和线程配置持久 ACP 绑定(在 match.peer.id 中使用频道/线程 id)。字段语义在 ACP 代理 中共享。
  • channels.discord.agentComponents.ttlMs 控制已发送的 Discord 组件回调保持注册状态的时间。默认 1800000(30 分钟),最大 86400000(24 小时)。按帐户的覆盖位于 channels.discord.accounts.<accountId>.agentComponents.ttlMs 下。请优先选择适合工作流的最短 TTL。
  • channels.discord.voice 启用 Discord 语音频道对话以及可选的自动加入 + LLM + TTS 覆盖。纯文本 Discord 配置默认关闭语音;设置 channels.discord.voice.enabled=true 以选择启用。
  • channels.discord.voice.autoJoin[].whenOccupied 保持自动管理的语音频道断开连接,直到有真人出现,然后在最后一个真人离开时退出。默认为 false;机器人不计为占用者,手动或临时语音会话不受此策略管理。
  • channels.discord.voice.model 可选地覆盖用于 Discord 语音频道响应的 LLM 模型。
  • channels.discord.voice.daveEncryption(默认 true)和 channels.discord.voice.decryptionFailureTolerance(默认 24)透传给 @discordjs/voice DAVE 选项。
  • channels.discord.voice.connectTimeoutMs 控制 /vc join 和自动加入尝试时初始 @discordjs/voice Ready 等待时间(默认 30000)。
  • channels.discord.voice.reconnectGraceMs 控制断开的语音会话在 OpenClaw 销毁它之前可以花多少时间进入重连信令(默认 15000)。
  • Discord 语音播放不会被其他用户的开始说话事件中断。为避免反馈循环,OpenClaw 在 TTS 播放期间会忽略新的语音采集。
  • OpenClaw 还会在重复解密失败后通过离开/重新加入语音会话来尝试语音接收恢复。
  • channels.discord.streaming 是标准流模式键。Discord 预览流默认 off;设置 streaming.mode: "progress" 以选择加入一条经过编辑的工具/工作进度消息,或选择 partial 或 block 来获得答案预览。旧式扁平键(streamMode、chunkMode、blockStreaming、draftChunk、blockStreamingCoalesce)在运行时不再读取;运行 openclaw doctor --fix 以迁移持久化配置。
  • channels.discord.autoPresence 将运行时可用性映射到机器人状态(healthy => online、degraded => idle、exhausted => dnd),并允许可选的在线状态文本覆盖。
  • channels.discord.guilds.<id>.presenceEvents 将人工可用性到达事件作为代理系统事件路由到一个已配置的 Discord 频道。符合条件的成员必须能够查看 channelId;公共线程继承父级可见性,而私有线程还要求成员身份或“管理线程”权限。users 可以进一步缩小该受众范围。它从完整的 GUILD_CREATE 快照中填充当前在线成员,路由观察到的离线到在线转换,并将未见成员的首次后续在线信号视为新可用,而不断言该成员是在快照之后上线还是加入。超过 Discord 75,000 名成员快照限制的服务器需要先进行显式离线更新。限流旋钮:reconnectSuppressSeconds(新 Gateway 会话后重建服务器状态时的静默窗口,默认 300,0 禁用)和 burstLimit/burstWindowSeconds(每服务器成功排队的事件速率限制,默认每 60 秒滑动窗口 8 个事件)。恢复的会话不会启动重连抑制窗口。现有的每用户重新问候冷却时间仍为八小时。它需要 channels.discord.intents.presence=true、Discord 开发者门户中的特权 Presence Intent,以及已启用的代理心跳。
  • channels.discord.intents.messageContent 默认为 true。仅当 Discord 无法授予特权的 Message Content intent 时,才将其设为 false 以进行仅提及操作;私信和显式机器人提及仍携带消息内容,而其他服务器消息则不携带。在此模式下,在每个已配置的服务器频道上保持 requireMention: true。
  • channels.discord.dangerouslyAllowNameMatching 重新启用可变的名称/标签匹配(紧急兼容模式)。
  • channels.discord.execApprovals:Discord 原生 exec 审批投递和审批人授权。
  • enabled:true、false 或 "auto"。未设置或 false 禁用原生投递。当审批人从 approvers 或 commands.ownerAllowFrom 解析时,设置 true 或 "auto" 以激活它。
  • approvers:允许批准 exec 请求的 Discord 用户 ID。省略时回退到 commands.ownerAllowFrom。
  • agentFilter:可选的代理 ID 允许列表。省略则转发所有代理的审批。
  • sessionFilter:可选的会话键模式(子字符串或正则表达式)。
  • target:发送审批提示的位置。"dm"(默认)发送到审批人私信,"channel" 发送到发起频道,"both" 同时发送到两者。当目标包含 "channel" 时,按钮仅可由已解析的审批人使用。
  • cleanupAfterResolve:当为 true 时,在批准、拒绝或超时后删除审批私信。

反应通知模式: off(无),own(机器人消息,默认),all(所有消息),allowlist(来自 guilds.<id>.users 的所有消息)。

Matrix

Matrix 由插件支持,并在 channels.matrix 下配置。

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}
  • Token 认证使用 accessToken;密码认证使用 userId + password。
  • channels.matrix.proxy 将 Matrix HTTP 流量通过显式 HTTP(S) 代理路由。命名账户可以使用 channels.matrix.accounts.<id>.proxy 覆盖它。
  • channels.matrix.network.dangerouslyAllowPrivateNetwork 允许私有/内部 homeserver。proxy 和此网络启用选项是相互独立的控制项。
  • channels.matrix.defaultAccount 在多账户设置中选择首选账户。
  • channels.matrix.autoJoin 默认为 "off",因此被邀请的房间和新的 DM 式邀请会被忽略,直到你设置 autoJoin: "allowlist" 并配合 autoJoinAllowlist,或设置 autoJoin: "always"。
  • channels.matrix.joinIntro 默认为 true。当机器人实际加入一个允许加入的群聊房间时,它会发布一条介绍,使用房间名称、主题以及最多 100 条可读的最近消息。如果历史记录读取失败,则只留下仅包含元数据的介绍。将此选项设置为 false 可禁用介绍,或使用 channels.matrix.accounts.<accountId>.joinIntro 进行特定账户覆盖。每个房间只触发一次介绍;未接受的邀请、启动时的房间快照、使机器人保持加入状态的成员更新以及私聊房间不会触发介绍。参见 群组加入介绍。
  • channels.matrix.execApprovals:Matrix 原生的 exec 审批投递与审批者授权。
  • enabled:true、false 或 "auto"(默认)。在自动模式下,当可以从 approvers 或 commands.ownerAllowFrom 解析出审批者时,exec 审批会激活。
  • approvers:允许批准 exec 请求的 Matrix 用户 ID(例如 @owner:example.org)。
  • agentFilter:可选的 agent ID 允许列表。省略时,会为所有 agent 转发审批。
  • sessionFilter:可选的会话键模式(子字符串或正则表达式)。
  • target:发送审批提示的位置。"dm"(默认)、"channel"(来源房间)或 "both"。
  • 按账户覆盖:channels.matrix.accounts.<id>.execApprovals。
  • channels.matrix.dm.sessionScope 控制 Matrix DM 如何分组为会话:per-user(默认)按路由对端共享,而 per-room 隔离每个 DM 房间。
  • Matrix 状态检查和实时目录查找使用与运行时流量相同的代理策略。
  • 完整的 Matrix 配置、目标规则和设置示例记录在 Matrix 中。

IRC

IRC 由插件支持,并在 channels.irc 下配置。

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}
  • 此处涵盖的核心键路径:channels.irc、channels.irc.dmPolicy、channels.irc.configWrites、channels.irc.nickserv.*。
  • 可选的 channels.irc.defaultAccount 在匹配已配置的账户 id 时覆盖默认账户选择。
  • 完整的 IRC 频道配置(主机/端口/TLS/频道/允许列表/提及门控)记录在 IRC 中。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw