配置 — channels

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Channels

​

DM 和群组访问

​

Channel model overrides

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

Channel defaults and heartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy：当 provider 级 groupPolicy 未设置时的回退群组策略。
• channels.defaults.contextVisibility：所有频道的默认补充上下文可见性模式。取值：all（默认，包含所有引用/线程/历史上下文）、allowlist（仅包含来自 allowlist 中发送者的上下文）、allowlist_quote（同 allowlist，但保留显式引用/回复上下文）。每频道覆盖：channels.<channel>.contextVisibility。
• channels.defaults.heartbeat.showOk：在 heartbeat 输出中包含健康的频道状态。
• channels.defaults.heartbeat.showAlerts：在 heartbeat 输出中包含降级/错误状态。
• channels.defaults.heartbeat.useIndicator：渲染紧凑的指示器风格 heartbeat 输出。

​

WhatsApp

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    whatsapp: {
      keepAliveIntervalMs: 25000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "保持回答简洁。",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "保持主题相关。",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git 备份" },
        { command: "generate", description: "创建图片" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      apiRoot: "https://api.telegram.org",
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Bot token: channels.telegram.botToken or channels.telegram.tokenFile (regular file only; symlinks rejected), with TELEGRAM_BOT_TOKEN as fallback for the default account.
• apiRoot is the Telegram Bot API root only. Use https://api.telegram.org or your self-hosted/proxy root, not https://api.telegram.org/bot<TOKEN>; openclaw doctor --fix removes an accidental trailing /bot<TOKEN> suffix.
• Optional channels.telegram.defaultAccount overrides default account selection when it matches a configured account id.
• In multi-account setups (2+ account ids), set an explicit default (channels.telegram.defaultAccount or channels.telegram.accounts.default) to avoid fallback routing; openclaw doctor warns when this is missing or invalid.
• configWrites: false blocks Telegram-initiated config writes (supergroup ID migrations, /config set|unset).
• Top-level bindings[] entries with type: "acp" configure persistent ACP bindings for forum topics (use canonical chatId:topic:topicId in match.peer.id). Field semantics are shared in ACP Agents.
• Telegram stream previews use sendMessage + editMessageText (works in direct and group chats).
• Retry policy: see Retry policy.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      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: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "仅限简短回答。",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSessions: true,
        defaultSpawnContext: "fork",
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        connectTimeoutMs: 30000,
        reconnectGraceMs: 15000,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, with DISCORD_BOT_TOKEN as fallback for the default account.
• Direct outbound calls that provide an explicit Discord token use that token for the call; account retry/policy settings still come from the selected account in the active runtime snapshot.
• Optional channels.discord.defaultAccount overrides default account selection when it matches a configured account id.
• Use user:<id> (DM) or channel:<id> (guild channel) for delivery targets; bare numeric IDs are rejected.
• Guild slugs are lowercase with spaces replaced by -; channel keys use the slugged name (no #). Prefer guild IDs.
• Bot-authored messages are ignored by default. allowBots: true enables them; use allowBots: "mentions" to only accept bot messages that mention the bot (own messages still filtered).
• channels.discord.guilds.<id>.ignoreOtherMentions (and channel overrides) drops messages that mention another user or role but not the bot (excluding @everyone/@here).
• channels.discord.mentionAliases maps stable outbound @handle text to Discord user IDs before sending, so known teammates can be mentioned deterministically even when the transient directory cache is empty. Per-account overrides live under channels.discord.accounts.<accountId>.mentionAliases.
• maxLinesPerMessage (default 17) splits tall messages even when under 2000 chars.
• channels.discord.threadBindings controls Discord thread-bound routing:
  • enabled: Discord override for thread-bound session features (/focus, /unfocus, /agents, /session idle, /session max-age, and bound delivery/routing)
  • idleHours: Discord override for inactivity auto-unfocus in hours (0 disables)
  • maxAgeHours: Discord override for hard max age in hours (0 disables)
  • spawnSessions: switch for sessions_spawn({ thread: true }) and ACP thread-spawn auto thread creation/binding (default: true)
  • defaultSpawnContext: native subagent context for thread-bound spawns ("fork" by default)
• Top-level bindings[] entries with type: "acp" configure persistent ACP bindings for channels and threads (use channel/thread id in match.peer.id). Field semantics are shared in ACP Agents.
• channels.discord.ui.components.accentColor sets the accent color for Discord components v2 containers.
• channels.discord.voice enables Discord voice channel conversations and optional auto-join + LLM + TTS overrides. Text-only Discord configs leave voice off by default; set channels.discord.voice.enabled=true to opt in.
• channels.discord.voice.model optionally overrides the LLM model used for Discord voice channel responses.
• channels.discord.voice.daveEncryption and channels.discord.voice.decryptionFailureTolerance pass through to @discordjs/voice DAVE options (true and 24 by default).
• channels.discord.voice.connectTimeoutMs controls the initial @discordjs/voice Ready wait for /vc join and auto-join attempts (30000 by default).
• channels.discord.voice.reconnectGraceMs controls how long a disconnected voice session may take to enter reconnect signalling before OpenClaw destroys it (15000 by default).
• OpenClaw additionally attempts voice receive recovery by leaving/rejoining a voice session after repeated decrypt failures.
• channels.discord.streaming is the canonical stream mode key. Legacy streamMode and boolean streaming values are auto-migrated.
• channels.discord.autoPresence maps runtime availability to bot presence (healthy => online, degraded => idle, exhausted => dnd) and allows optional status text overrides.
• channels.discord.dangerouslyAllowNameMatching re-enables mutable name/tag matching (break-glass compatibility mode).
• channels.discord.execApprovals: Discord-native exec approval delivery and approver authorization.
  • enabled: true, false, or "auto" (default). In auto mode, exec approvals activate when approvers can be resolved from approvers or commands.ownerAllowFrom.
  • approvers: Discord user IDs allowed to approve exec requests. Falls back to commands.ownerAllowFrom when omitted.
  • agentFilter: optional agent ID allowlist. Omit to forward approvals for all agents.
  • sessionFilter: optional session key patterns (substring or regex).
  • target: where to send approval prompts. "dm" (default) sends to approver DMs, "channel" sends to the originating channel, "both" sends to both. When target includes "channel", buttons are only usable by resolved approvers.
  • cleanupAfterResolve: when true, deletes approval DMs after approval, denial, or timeout.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• Service account JSON：可内联（serviceAccount）或基于文件（serviceAccountFile）。
• 也支持 Service account SecretRef（serviceAccountRef）。
• 环境变量回退：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
• 投递目标使用 spaces/<spaceId> 或 users/<userId>。
• channels.googlechat.dangerouslyAllowNameMatching 重新启用可变 email principal 匹配（break-glass 兼容模式）。

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      socketMode: {
        clientPingTimeout: 15000,
        serverPingTimeout: 30000,
        pingPongLoggingEnabled: false,
      },
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "仅限简短回答。",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // 使用 Slack 原生流式 API，当 mode=partial 时
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket mode 需要同时提供 botToken 和 appToken（默认账号环境变量回退使用 SLACK_BOT_TOKEN + SLACK_APP_TOKEN）。
• HTTP mode 需要 botToken 加 signingSecret（在根级或每账号级）。
• socketMode 将 Slack SDK Socket Mode 的传输调优透传给公开的 Bolt receiver API。仅在排查 ping/pong 超时或 websocket 陈旧行为时使用。
• botToken、appToken、signingSecret 和 userToken 可接受明文字符串或 SecretRef 对象。
• Slack 账号快照会暴露每个凭证的 source/status 字段，例如 botTokenSource、botTokenStatus、appTokenStatus，以及在 HTTP mode 下的 signingSecretStatus。configured_unavailable 表示该账号已通过 SecretRef 配置，但当前命令/runtime 路径无法解析出 secret 值。
• configWrites: false 会阻止 Slack 触发的配置写入。
• 可选的 channels.slack.defaultAccount 会在其与已配置账号 id 匹配时覆盖默认账号选择。
• channels.slack.streaming.mode 是规范的 Slack 流模式键。channels.slack.streaming.nativeTransport 控制 Slack 的原生流式传输。旧的 streamMode、布尔型 streaming 和 nativeStreaming 值会自动迁移。
• 使用 user:<id>（DM）或 channel:<id> 作为投递目标。

• Slack native streaming plus the Slack assistant-style “is typing…” thread status require a reply thread target. Top-level DMs stay off-thread by default, so they can still stream through Slack draft post-and-edit previews instead of showing the thread-style native stream/status preview.
• typingReaction adds a temporary reaction to the inbound Slack message while a reply is running, then removes it on completion. Use a Slack emoji shortcode such as "hourglass_flowing_sand".
• channels.slack.execApprovals: Slack-native exec approval delivery and approver authorization. Same schema as Discord: enabled (true/false/"auto"), approvers (Slack user IDs), agentFilter, sessionFilter, and target ("dm", "channel", or "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // 可选的显式 URL，适用于反向代理/公网部署
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• commands.callbackPath 必须是路径（例如 /api/channels/mattermost/command），不能是完整 URL。
• commands.callbackUrl 必须解析到 OpenClaw gateway 端点，并且 Mattermost 服务器可以访问。
• 原生 slash 回调使用 Mattermost 在 slash command 注册期间返回的每命令 token 进行认证。如果注册失败或没有激活任何命令，OpenClaw 会以 Unauthorized: invalid command token. 拒绝回调。
• 对于私有/tailnet/internal 回调主机，Mattermost 可能要求 ServiceSettings.AllowedUntrustedInternalConnections 包含回调主机/域名。 请使用主机/域名值，不要使用完整 URL。
• channels.mattermost.configWrites：允许或拒绝 Mattermost 触发的配置写入。
• channels.mattermost.requireMention：在频道中回复前是否需要 @mention。
• channels.mattermost.groups.<channelId>.requireMention：每频道 mention 门控覆盖（默认使用 "*"）。
• 可选的 channels.mattermost.defaultAccount 会在其与已配置账号 id 匹配时覆盖默认账号选择。

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // 可选账号绑定
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account：将频道启动固定到特定的 Signal 账号身份。
• channels.signal.configWrites：允许或拒绝 Signal 触发的配置写入。
• 可选的 channels.signal.defaultAccount 会在其与已配置账号 id 匹配时覆盖默认账号选择。

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Core key paths covered here: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• Optional channels.bluebubbles.defaultAccount overrides default account selection when it matches a configured account id.
• Top-level bindings[] entries with type: "acp" can bind BlueBubbles conversations to persistent ACP sessions. Use a BlueBubbles handle or target string (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Shared field semantics: ACP Agents.
• Full BlueBubbles channel configuration is documented in BlueBubbles.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• 可选的 channels.imessage.defaultAccount 会在其与已配置账号 id 匹配时覆盖默认账号选择。
• Requires Full Disk Access to the Messages DB.
• Prefer chat_id:<id> targets. Use imsg chats --limit 20 to list chats.
• cliPath can point to an SSH wrapper; set remoteHost (host or user@host) for SCP attachment fetching.
• attachmentRoots and remoteAttachmentRoots restrict inbound attachment paths (default: /Users/*/Library/Messages/Attachments).
• SCP uses strict host-key checking, so ensure the relay host key already exists in ~/.ssh/known_hosts.
• channels.imessage.configWrites: allow or deny iMessage-initiated config writes.
• Top-level bindings[] entries with type: "acp" can bind iMessage conversations to persistent ACP sessions. Use a normalized handle or explicit chat target (chat_id:*, chat_guid:*, chat_identifier:*) in match.peer.id. Shared field semantics: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

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 会通过显式 HTTP(S) 代理路由 Matrix HTTP 流量。命名账号可通过 channels.matrix.accounts.<id>.proxy 覆盖它。
• channels.matrix.network.dangerouslyAllowPrivateNetwork 允许私有/内部 homeserver。proxy 和该网络显式启用是彼此独立的控制项。
• channels.matrix.defaultAccount 会在多账号设置中选择首选账号。
• channels.matrix.autoJoin 默认为 off，因此被邀请的 room 和新的 DM 风格邀请会被忽略，直到你将 autoJoin: "allowlist" 搭配 autoJoinAllowlist，或将其设为 autoJoin: "always"。
• channels.matrix.execApprovals：Matrix 原生执行审批的投递与审批者授权。
  • enabled：true、false 或 "auto"（默认）。在 auto 模式下，当可以从 approvers 或 commands.ownerAllowFrom 解析审批者时，exec approvals 会激活。
  • approvers：允许批准 exec 请求的 Matrix 用户 ID（例如 @owner:example.org）。
  • agentFilter：可选的 agent ID allowlist。省略则转发所有 agent 的审批。
  • sessionFilter：可选的 session key 模式（子串或正则）。
  • target：审批提示的发送位置。"dm"（默认）、"channel"（来源 room）或 "both"。
  • 每账号覆盖：channels.matrix.accounts.<id>.execApprovals。
• channels.matrix.dm.sessionScope 控制 Matrix DM 如何分组为会话：per-user（默认）按路由 peer 共享，而 per-room 会隔离每个 DM room。
• Matrix 状态探测和实时目录查询使用与运行时流量相同的代理策略。
• 完整的 Matrix 配置、投递目标规则和设置示例见 Matrix。

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• 此处涵盖的核心键路径：channels.msteams、channels.msteams.configWrites。
• 完整的 Teams 配置（凭证、webhook、DM/group policy、每团队/每频道覆盖）见 Microsoft Teams。

​

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 频道配置（host/port/TLS/channels/allowlists/mention gating）见 IRC。

​

Multi-account (all channels)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• 当省略 accountId 时使用 default（CLI + 路由）。
• 环境变量 token 仅适用于默认账号。
• 基础频道设置适用于所有账号，除非按账号覆盖。
• 使用 bindings[].match.accountId 将每个账号路由到不同的 agent。
• 如果你在仍处于单账号顶层频道配置时，通过 openclaw channels add（或 channel onboarding）添加非默认账号，OpenClaw 会先把账号作用域的顶层单账号值提升到频道账号映射中，这样原始账号仍可继续工作。大多数频道会将它们移动到 channels.<channel>.accounts.default；Matrix 也可以改为保留现有匹配的 named/default 目标。
• 现有的仅频道绑定（没有 accountId）会继续匹配默认账号；账号作用域绑定仍然是可选的。
• openclaw doctor --fix 也会通过把账号作用域的顶层单账号值移动到该频道选定的提升账号来修复混合结构。大多数频道使用 accounts.default；Matrix 也可以保留现有匹配的 named/default 目标。

​

Other plugin channels

​

Group chat mention gating

• Metadata mentions：原生平台 @-mentions。在 WhatsApp self-chat mode 中会被忽略。
• Text patterns：agents.list[].groupChat.mentionPatterns 中的安全正则模式。无效模式和不安全的嵌套重复会被忽略。
• 只有在能够检测到时才会强制提及门控（原生 mentions 或至少一个模式）。

{
  messages: {
    visibleReplies: "automatic", // direct/source chats 的全局默认；Codex harness 对未设置的 direct chats 默认使用 message_tool
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // 默认；若要使用旧的最终回复则设为 "automatic"
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

DM history limits

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

Self-chat mode

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

Commands (chat command handling)

{
  commands: {
    native: "auto", // 在支持时注册原生命令
    nativeSkills: "auto", // 在支持时注册原生技能命令
    text: true, // 解析聊天消息中的 /commands
    bash: false, // 允许 !（别名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允许 /config
    mcp: false, // 允许 /mcp
    plugins: false, // 允许 /plugins
    debug: false, // 允许 /debug
    restart: true, // 允许 /restart + gateway restart tool
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

相关内容

• 配置参考 — 顶级键
• 配置 — 代理
• 渠道概览