配置 — 社区聊天频道

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 的直接出站调用会使用该 token 进行调用；账户策略设置仍来自活动运行时快照中所选的账户。
可选的 channels.discord.defaultAccount 在匹配已配置的账户 ID 时覆盖默认账户选择。
使用 user:<id>（私信）或 channel:<id>（服务器频道）作为投递目标；纯数字 ID 将被拒绝。
actions.reactions 控制 react、reactions 和 emoji-list；emoji 发现默认使用当前服务器，除非提供了 guildId。
服务器（Guild）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 预览流式默认关闭；设置 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：可选的代理 ID 允许列表。省略则转发所有代理的审批。
sessionFilter：可选的会话键模式（子串或正则表达式）。
target：发送审批提示的位置。"dm"（默认）、"channel"（来源房间）或 "both"。
按账户覆盖：channels.matrix.accounts.<id>.execApprovals。
channels.matrix.dm.sessionScope 控制 Matrix 直接消息如何分组为会话：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