設定 — 頻道

各頻道的設定鍵位於 channels.* 之下。涵蓋 DM 與群組存取、多帳號設定、提及閘控，以及 Slack、Discord、Telegram、WhatsApp、Matrix、iMessage 和其他內建頻道 Plugin 的各頻道鍵。如需 agents、工具、gateway runtime 與其他頂層鍵，請參閱設定參考。

頻道

每個頻道會在其設定區段存在時自動啟動（除非 enabled: false）。

DM 與群組存取

所有頻道都支援 DM 政策與群組政策：

DM 政策	行為
`pairing`（預設）	未知寄件者會收到一次性配對碼；owner 必須核准
`allowlist`	僅允許 `allowFrom`（或已配對允許儲存區）中的寄件者
`open`	允許所有傳入 DM（需要 `allowFrom: ["*"]`）
`disabled`	忽略所有傳入 DM

群組政策	行為
`allowlist`（預設）	僅允許符合已設定允許清單的群組
`open`	略過群組允許清單（提及閘控仍然適用）
`disabled`	封鎖所有群組/房間訊息

channels.defaults.groupPolicy 會在 provider 的 groupPolicy 未設定時設定預設值。配對碼會在 1 小時後過期。待處理的 DM 配對請求上限為每個頻道 3 個。如果 provider 區塊完全缺少（沒有 channels.<provider>），runtime 群組政策會退回到 allowlist（失敗關閉），並在啟動時顯示警告。

頻道模型覆寫

使用 channels.modelByChannel 將特定頻道 ID 固定到某個模型。值可接受 provider/model 或已設定的模型別名。當 session 尚未有模型覆寫時（例如透過 /model 設定），會套用頻道對應。

{
  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",
      },
    },
  },
}

頻道預設值與 Heartbeat

使用 channels.defaults 設定跨 provider 共用的群組政策與 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（預設，包含所有引用/thread/history 情境）、allowlist（僅包含來自允許清單寄件者的情境）、allowlist_quote（與 allowlist 相同，但保留明確引用/回覆情境）。各頻道覆寫：channels.<channel>.contextVisibility。
channels.defaults.heartbeat.showOk：在 Heartbeat 輸出中包含健康的頻道狀態。
channels.defaults.heartbeat.showAlerts：在 Heartbeat 輸出中包含 degraded/error 狀態。
channels.defaults.heartbeat.useIndicator：呈現精簡指示器風格的 Heartbeat 輸出。

WhatsApp 透過 gateway 的 web 頻道（Baileys Web）執行。當已連結的 session 存在時會自動啟動。

{
  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"],
    },
  },
}

多帳號 WhatsApp

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

傳出命令預設使用帳號 default（若存在）；否則使用第一個已設定的 account id（排序後）。
可選的 channels.whatsapp.defaultAccount 會在符合已設定 account id 時覆寫該備援預設帳號選擇。
舊版單帳號 Baileys auth dir 會由 openclaw doctor 遷移到 whatsapp/default。
各帳號覆寫：channels.whatsapp.accounts.<id>.sendReadReceipts、channels.whatsapp.accounts.<id>.dmPolicy、channels.whatsapp.accounts.<id>.allowFrom。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      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 或 channels.telegram.tokenFile（僅限一般檔案；拒絕 symlink），預設帳號則以 TELEGRAM_BOT_TOKEN 作為備援。
apiRoot 僅是 Telegram Bot API root。請使用 https://api.telegram.org 或你的自託管/proxy root，不要使用 https://api.telegram.org/bot<TOKEN>；openclaw doctor --fix 會移除意外結尾的 /bot<TOKEN> suffix。
可選的 channels.telegram.defaultAccount 會在符合已設定 account id 時覆寫預設帳號選擇。
在多帳號設定（2 個以上 account id）中，請設定明確的預設值（channels.telegram.defaultAccount 或 channels.telegram.accounts.default）以避免備援路由；當此設定缺少或無效時，openclaw doctor 會發出警告。
configWrites: false 會封鎖由 Telegram 啟動的設定寫入（supergroup ID 遷移、/config set|unset）。
帶有 type: "acp" 的頂層 bindings[] 項目會為論壇主題設定持久 ACP 綁定（在 match.peer.id 中使用標準 chatId:topic:topicId）。欄位語意共用於 ACP Agents。
Telegram 串流預覽使用 sendMessage + editMessageText（可在 direct 與群組聊天中運作）。
Retry 政策：請參閱 Retry 政策。

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: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: {
        mode: "progress", // off | partial | block | progress (Discord default: progress)
        progress: {
          label: "auto",
          maxLines: 8,
          toolProgress: true,
        },
      },
      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，並以 DISCORD_BOT_TOKEN 作為預設帳戶的備援。
提供明確 Discord token 的直接對外呼叫會使用該 token 進行呼叫；帳戶重試/政策設定仍來自現用執行階段快照中選取的帳戶。
可選的 channels.discord.defaultAccount 會在符合已設定帳戶 ID 時覆寫預設帳戶選擇。
使用 user:<id>（DM）或 channel:<id>（公會頻道）作為傳遞目標；裸數字 ID 會被拒絕。
公會 slug 會轉為小寫，並將空格替換為 -；頻道鍵使用 slug 化名稱（不含 #）。建議優先使用公會 ID。
預設會忽略機器人撰寫的訊息。allowBots: true 會啟用它們；使用 allowBots: "mentions" 只接受提及該機器人的機器人訊息（自己的訊息仍會被篩除）。
channels.discord.guilds.<id>.ignoreOtherMentions（以及頻道覆寫）會丟棄提及其他使用者或角色但未提及機器人的訊息（排除 @everyone/@here）。
channels.discord.mentionAliases 會在傳送前，將穩定的對外 @handle 文字對應到 Discord 使用者 ID，因此即使暫時性目錄快取為空，也能以確定方式提及已知隊友。每個帳戶的覆寫位於 channels.discord.accounts.<accountId>.mentionAliases 下。
maxLinesPerMessage（預設 17）會拆分過高的訊息，即使其低於 2000 個字元。
channels.discord.threadBindings 控制 Discord 執行緒綁定路由：
- enabled：Discord 對執行緒綁定工作階段功能的覆寫（/focus、/unfocus、/agents、/session idle、/session max-age，以及綁定傳遞/路由）
- idleHours：Discord 對閒置自動取消焦點的小時數覆寫（0 會停用）
- maxAgeHours：Discord 對硬性最長存續時間的小時數覆寫（0 會停用）
- spawnSessions：sessions_spawn({ thread: true }) 與 ACP 執行緒衍生自動建立/綁定執行緒的開關（預設：true）
- defaultSpawnContext：執行緒綁定衍生的原生子代理內容（預設為 "fork"）
具有 type: "acp" 的頂層 bindings[] 項目會為頻道與執行緒設定持久 ACP 綁定（在 match.peer.id 中使用頻道/執行緒 ID）。欄位語意在 ACP Agents 中共用。
channels.discord.ui.components.accentColor 設定 Discord 元件 v2 容器的強調色。
channels.discord.voice 會啟用 Discord 語音頻道對話，以及可選的自動加入 + LLM + TTS 覆寫。純文字 Discord 設定預設會關閉語音；設定 channels.discord.voice.enabled=true 以選擇啟用。
channels.discord.voice.model 可選擇覆寫用於 Discord 語音頻道回應的 LLM 模型。
channels.discord.voice.daveEncryption 與 channels.discord.voice.decryptionFailureTolerance 會傳遞到 @discordjs/voice DAVE 選項（預設為 true 與 24）。
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"，因此工具/工作進度會出現在一則經編輯的預覽訊息中；設定 streaming.mode: "off" 可停用它。舊版 streamMode 與布林值 streaming 值仍是執行階段別名；執行 openclaw doctor --fix 以重寫持久化設定。
channels.discord.autoPresence 會將執行階段可用性對應到機器人狀態（healthy => online、degraded => idle、exhausted => dnd），並允許可選的狀態文字覆寫。
channels.discord.dangerouslyAllowNameMatching 會重新啟用可變名稱/標籤比對（緊急相容模式）。
channels.discord.execApprovals：Discord 原生 exec 核准傳遞與核准者授權。
- enabled：true、false 或 "auto"（預設）。在自動模式中，當可從 approvers 或 commands.ownerAllowFrom 解析核准者時，exec 核准會啟用。
- approvers：允許核准 exec 請求的 Discord 使用者 ID。省略時會回退到 commands.ownerAllowFrom。
- agentFilter：可選代理 ID 允許清單。省略時會轉送所有代理的核准。
- sessionFilter：可選工作階段鍵模式（子字串或 regex）。
- target：要傳送核准提示的位置。"dm"（預設）會傳送給核准者 DM，"channel" 會傳送到來源頻道，"both" 會同時傳送到兩者。當目標包含 "channel" 時，按鈕僅可由已解析的核准者使用。
- cleanupAfterResolve：為 true 時，會在核准、拒絕或逾時後刪除核准 DM。

反應通知模式： off（無）、own（機器人的訊息，預設）、all（所有訊息）、allowlist（來自所有訊息上的 guilds.<id>.users）。

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,
    },
  },
}

服務帳戶 JSON：內嵌（serviceAccount）或檔案型（serviceAccountFile）。
也支援服務帳戶 SecretRef（serviceAccountRef）。
環境備援：GOOGLE_CHAT_SERVICE_ACCOUNT 或 GOOGLE_CHAT_SERVICE_ACCOUNT_FILE。
使用 spaces/<spaceId> 或 users/<userId> 作為傳遞目標。
channels.googlechat.dangerouslyAllowNameMatching 會重新啟用可變電子郵件主體比對（緊急相容模式）。

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: "Short answers only.",
        },
      },
      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",
      unfurlLinks: false,
      unfurlMedia: false,
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // use Slack native streaming API when 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 模式 需要 botToken 加上 signingSecret（位於根層級或各帳戶）。
socketMode 會將 Slack SDK Socket Mode 傳輸調校傳遞到公開 Bolt 接收器 API。僅在調查 ping/pong 逾時或過期 websocket 行為時使用它。
botToken、appToken、signingSecret 與 userToken 接受純文字字串或 SecretRef 物件。
Slack 帳戶快照會公開每個憑證的來源/狀態欄位，例如 botTokenSource、botTokenStatus、appTokenStatus，以及在 HTTP 模式中的 signingSecretStatus。configured_unavailable 表示帳戶是透過 SecretRef 設定，但目前的命令/執行階段路徑無法解析密鑰值。
configWrites: false 會封鎖 Slack 發起的設定寫入。
可選的 channels.slack.defaultAccount 會在符合已設定帳戶 ID 時覆寫預設帳戶選擇。
channels.slack.streaming.mode 是標準 Slack 串流模式鍵。channels.slack.streaming.nativeTransport 控制 Slack 的原生串流傳輸。舊版 streamMode、布林值 streaming 與 nativeStreaming 值仍是執行階段別名；執行 openclaw doctor --fix 以重寫持久化設定。
unfurlLinks 與 unfurlMedia 會將 Slack 的 chat.postMessage 連結與媒體展開布林值傳遞給機器人回覆。省略它們可保留 Slack 的預設行為；在 channels.slack.accounts.<accountId> 設定它們可覆寫單一帳戶的頂層預設值。
使用 user:<id>（DM）或 channel:<id> 作為傳遞目標。

反應通知模式： off、own（預設）、all、allowlist（來自 reactionAllowlist）。 執行緒工作階段隔離： thread.historyScope 是每個執行緒（預設）或跨頻道共用。thread.inheritParent 會將父頻道對話記錄複製到新執行緒。

Slack 原生串流加上 Slack 助理風格的「is typing…」執行緒狀態需要回覆執行緒目標。頂層 DM 預設保持在執行緒外，因此仍可透過 Slack 草稿發佈與編輯預覽進行串流，而不是顯示執行緒風格的原生串流/狀態預覽。
typingReaction 會在回覆執行期間，對傳入的 Slack 訊息新增暫時反應，並在完成時移除。使用 Slack emoji 短代碼，例如 "hourglass_flowing_sand"。
channels.slack.execApprovals：Slack 原生 exec 核准傳遞與核准者授權。與 Discord 相同的 schema：enabled（true/false/"auto"）、approvers（Slack 使用者 ID）、agentFilter、sessionFilter 與 target（"dm"、"channel" 或 "both"）。

動作群組	預設	備註
reactions	已啟用	反應 + 列出反應
messages	已啟用	讀取/傳送/編輯/刪除
pins	已啟用	釘選/取消釘選/列出
memberInfo	已啟用	成員資訊
emojiList	已啟用	自訂 emoji 清單

Mattermost

Mattermost 在目前 OpenClaw 版本中作為隨附 Plugin 發佈。較舊或自訂建置可以使用 openclaw plugins install @openclaw/mattermost 安裝目前的 npm 套件。在釘選版本前，請查看 npmjs.com/package/@openclaw/mattermost 以取得目前的 dist-tags。

{
  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",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

聊天模式：oncall（在 @-提及時回覆，預設）、onmessage（每則訊息）、onchar（以觸發前綴開頭的訊息）。啟用 Mattermost 原生命令時：

commands.callbackPath 必須是路徑（例如 /api/channels/mattermost/command），而不是完整 URL。
commands.callbackUrl 必須解析到 OpenClaw Gateway 端點，且 Mattermost 伺服器必須能連線到它。
原生斜線命令回呼會使用 Mattermost 在斜線命令註冊期間傳回的每命令權杖進行驗證。如果註冊失敗或沒有啟用任何命令，OpenClaw 會以 Unauthorized: invalid command token. 拒絕回呼。
對於私有/tailnet/內部回呼主機，Mattermost 可能需要 ServiceSettings.AllowedUntrustedInternalConnections 包含該回呼主機/網域。請使用主機/網域值，而不是完整 URL。
channels.mattermost.configWrites：允許或拒絕由 Mattermost 起始的設定寫入。
channels.mattermost.requireMention：在頻道中回覆前要求 @mention。
channels.mattermost.groups.<channelId>.requireMention：每頻道提及門控覆寫（"*" 表示預設）。
選用的 channels.mattermost.defaultAccount 會在符合已設定的帳戶 ID 時覆寫預設帳戶選擇。

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      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,
    },
  },
}

反應通知模式： off、own（預設）、all、allowlist（來自 reactionAllowlist）。

channels.signal.account：將頻道啟動固定到特定 Signal 帳戶身分。
channels.signal.configWrites：允許或拒絕由 Signal 起始的設定寫入。
選用的 channels.signal.defaultAccount 會在符合已設定的帳戶 ID 時覆寫預設帳戶選擇。

iMessage

OpenClaw 會產生 imsg rpc（透過 stdio 的 JSON-RPC）。不需要 daemon 或連接埠。當主機可以授予 Messages 資料庫與 Automation 權限時，這是新 OpenClaw iMessage 設定的偏好路徑。 BlueBubbles 支援已移除。請將 channels.bluebubbles 設定遷移到 channels.imessage；OpenClaw 僅透過 imsg 支援 iMessage。如果 Gateway 未在已登入 Messages 的 Mac 上執行，請保留 channels.imessage.enabled=true，並將 channels.imessage.cliPath 設為在該 Mac 上執行 imsg "$@" 的 SSH 包裝器。預設本機 imsg 路徑僅適用於 macOS。

{
  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 時覆寫預設帳戶選擇。
需要 Messages DB 的完整磁碟存取權限。
偏好使用 chat_id:<id> 目標。使用 imsg chats --limit 20 列出聊天。
cliPath 可以指向 SSH 包裝器；設定 remoteHost（host 或 user@host）以便透過 SCP 擷取附件。
attachmentRoots 和 remoteAttachmentRoots 會限制傳入附件路徑（預設：/Users/*/Library/Messages/Attachments）。
SCP 使用嚴格主機金鑰檢查，因此請確保中繼主機金鑰已存在於 ~/.ssh/known_hosts。
channels.imessage.configWrites：允許或拒絕由 iMessage 起始的設定寫入。
具有 type: "acp" 的頂層 bindings[] 項目可以將 iMessage 對話繫結到持久 ACP 工作階段。在 match.peer.id 中使用正規化控制代碼或明確聊天目標（chat_id:*、chat_guid:*、chat_identifier:*）。共用欄位語意：ACP Agents。

iMessage SSH 包裝器範例

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

Matrix

Matrix 由 Plugin 支援，並在 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",
        },
      },
    },
  },
}

權杖驗證使用 accessToken；密碼驗證使用 userId + password。
channels.matrix.proxy 會透過明確的 HTTP(S) proxy 路由 Matrix HTTP 流量。具名帳戶可以使用 channels.matrix.accounts.<id>.proxy 覆寫它。
channels.matrix.network.dangerouslyAllowPrivateNetwork 允許私有/內部 homeserver。proxy 與這個網路選用設定是彼此獨立的控制項。
channels.matrix.defaultAccount 會在多帳戶設定中選取偏好的帳戶。
channels.matrix.autoJoin 預設為 off，因此受邀房間和新的 DM 樣式邀請會被忽略，直到你設定含 autoJoinAllowlist 的 autoJoin: "allowlist" 或 autoJoin: "always"。
channels.matrix.execApprovals：Matrix 原生 exec 核准傳送與核准者授權。
- enabled：true、false 或 "auto"（預設）。在自動模式中，當可從 approvers 或 commands.ownerAllowFrom 解析核准者時，exec 核准會啟用。
- approvers：允許核准 exec 請求的 Matrix 使用者 ID（例如 @owner:example.org）。
- agentFilter：選用的 agent ID allowlist。省略時會轉送所有 agent 的核准。
- sessionFilter：選用的工作階段金鑰模式（子字串或 regex）。
- target：傳送核准提示的位置。"dm"（預設）、"channel"（來源房間）或 "both"。
- 每帳戶覆寫：channels.matrix.accounts.<id>.execApprovals。
channels.matrix.dm.sessionScope 控制 Matrix DM 如何分組成工作階段：per-user（預設）依路由 peer 共用，而 per-room 會隔離每個 DM 房間。
Matrix 狀態探測與即時目錄查詢使用與執行時流量相同的 proxy 政策。
完整 Matrix 設定、目標規則與設定範例記錄在 Matrix。

Microsoft Teams

Microsoft Teams 由 Plugin 支援，並在 channels.msteams 下設定。

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

此處涵蓋的核心金鑰路徑：channels.msteams、channels.msteams.configWrites。
完整 Teams 設定（認證、webhook、DM/群組政策、每團隊/每頻道覆寫）記錄在 Microsoft Teams。

IRC

IRC 由 Plugin 支援，並在 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/頻道/allowlist/提及門控）記錄在 IRC。

多帳戶（所有頻道）

每個頻道執行多個帳戶（每個帳戶都有自己的 accountId）：

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

省略 accountId 時會使用 default（CLI + 路由）。
環境權杖只會套用到預設帳戶。
基礎頻道設定會套用到所有帳戶，除非每帳戶覆寫。
使用 bindings[].match.accountId 將每個帳戶路由到不同 agent。
如果你在仍使用單帳戶頂層頻道設定時，透過 openclaw channels add（或頻道 onboarding）新增非預設帳戶，OpenClaw 會先將帳戶範圍的頂層單帳戶值提升到頻道帳戶對應表，讓原始帳戶繼續運作。大多數頻道會將它們移到 channels.<channel>.accounts.default；Matrix 則可以改為保留現有相符的具名/預設目標。
現有的僅頻道繫結（沒有 accountId）會繼續符合預設帳戶；帳戶範圍繫結仍為選用。
openclaw doctor --fix 也會修復混合形狀，方法是將帳戶範圍的頂層單帳戶值移到為該頻道選擇的提升帳戶。大多數頻道使用 accounts.default；Matrix 則可以改為保留現有相符的具名/預設目標。

其他 Plugin 頻道

許多 Plugin 頻道設定為 channels.<id>，並記錄在其專用頻道頁面中（例如 Feishu、Matrix、LINE、Nostr、Zalo、Nextcloud Talk、Synology Chat 和 Twitch）。請參閱完整頻道索引：Channels。

群組聊天提及門控

群組訊息預設為要求提及（metadata 提及或安全 regex 模式）。適用於 WhatsApp、Telegram、Discord、Google Chat 和 iMessage 群組聊天。可見回覆會另行控制。群組/頻道房間預設為 messages.groupChat.visibleReplies: "message_tool"：OpenClaw 仍會處理該回合，但一般最終回覆會保持私密，且可見房間輸出需要 message(action=send)。只有在你想要舊版行為，也就是將一般回覆發回房間時，才設定 "automatic"。若要將相同的僅工具可見回覆行為也套用到直接聊天，請設定 messages.visibleReplies: "message_tool"；Codex harness 也將該僅工具行為作為其未設定的直接聊天預設。僅工具可見回覆需要能可靠呼叫工具的模型/執行時。如果工作階段記錄顯示 assistant 文字帶有 didSendViaMessagingTool: false，表示模型產生了私密最終答案，而不是呼叫訊息工具。請為該頻道切換到更強的工具呼叫模型，或設定 messages.groupChat.visibleReplies: "automatic" 以還原舊版可見最終回覆。如果訊息工具在作用中的工具政策下無法使用，OpenClaw 會回退到自動可見回覆，而不是默默抑制回應。openclaw doctor 會警告這種不相符情況。 Gateway 會在檔案儲存後熱重新載入 messages 設定。只有在部署中停用檔案監看或設定重新載入時，才需要重新啟動。 提及類型：

中繼資料提及：原生平台 @-mentions。在 WhatsApp 自我聊天模式中會被忽略。
文字模式：agents.list[].groupChat.mentionPatterns 中的安全 regex patterns。無效模式和不安全的巢狀重複會被忽略。
只有在可以偵測時（原生提及或至少一個模式），才會強制執行提及門檻。

{
  messages: {
    visibleReplies: "automatic", // direct/source chats 的全域預設值；Codex harness 會將未設定的直接聊天預設為 message_tool
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // 預設值；舊版最終回覆請使用 "automatic"
    },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit 會設定全域預設值。Channels 可以使用 channels.<channel>.historyLimit（或逐帳號）覆寫。設為 0 可停用。 messages.visibleReplies 是全域 source-turn 預設值；messages.groupChat.visibleReplies 會針對群組/channel source turns 覆寫它。未設定 messages.visibleReplies 時，harness 可以提供自己的直接/source 預設值；Codex harness 預設為 message_tool。Channel allowlists 和提及門檻仍會決定是否處理某個 turn。

DM 歷史記錄限制

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

解析順序：逐 DM 覆寫 → provider 預設值 → 無限制（全部保留）。支援：telegram、whatsapp、discord、slack、signal、imessage、msteams。

自我聊天模式

在 allowFrom 中包含你自己的號碼，以啟用自我聊天模式（忽略原生 @-mentions，只回應文字模式）：

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

命令（聊天命令處理）

{
  commands: {
    native: "auto", // 支援時註冊原生命令
    nativeSkills: "auto", // 支援時註冊原生 skill 命令
    text: true, // 解析聊天訊息中的 /commands
    bash: false, // 允許 !（別名：/bash）
    bashForegroundMs: 2000,
    config: false, // 允許 /config
    mcp: false, // 允許 /mcp
    plugins: false, // 允許 /plugins
    debug: false, // 允許 /debug
    restart: true, // 允許 /restart + gateway 重新啟動工具
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

命令詳細資訊

此區塊會設定命令介面。若要查看目前內建 + bundled 命令目錄，請參閱 Slash Commands。
此頁是設定鍵參考，不是完整命令目錄。Channel/Plugin 擁有的命令，例如 QQ Bot /bot-ping /bot-help /bot-logs、LINE /card、裝置配對 /pair、記憶體 /dreaming、手機控制 /phone，以及 Talk /voice，會記錄在各自的 channel/Plugin 頁面和 Slash Commands 中。
文字命令必須是帶有前置 / 的獨立訊息。
native: "auto" 會為 Discord/Telegram 開啟原生命令，並讓 Slack 保持關閉。
nativeSkills: "auto" 會為 Discord/Telegram 開啟原生 skill 命令，並讓 Slack 保持關閉。
逐 channel 覆寫：channels.discord.commands.native（bool 或 "auto"）。對 Discord 而言，false 會在啟動期間略過原生命令註冊和清理。
使用 channels.<provider>.commands.nativeSkills 逐 channel 覆寫原生 skill 註冊。
channels.telegram.customCommands 會加入額外的 Telegram bot 選單項目。
bash: true 會啟用 host shell 的 ! <cmd>。需要 tools.elevated.enabled，且傳送者必須在 tools.elevated.allowFrom.<channel> 中。
config: true 會啟用 /config（讀取/寫入 openclaw.json）。對於 gateway chat.send 用戶端，持久化 /config set|unset 寫入也需要 operator.admin；唯讀 /config show 仍可供一般寫入範圍的 operator 用戶端使用。
mcp: true 會為 mcp.servers 下由 OpenClaw 管理的 MCP server 設定啟用 /mcp。
plugins: true 會為 Plugin 探索、安裝，以及啟用/停用控制啟用 /plugins。
channels.<provider>.configWrites 會逐 channel 控制設定變更（預設：true）。
對多帳號 channels，channels.<provider>.accounts.<id>.configWrites 也會控制以該帳號為目標的寫入（例如 /allowlist --config --account <id> 或 /config set channels.<provider>.accounts.<id>...）。
restart: false 會停用 /restart 和 Gateway 重新啟動工具動作。預設值：true。
ownerAllowFrom 是僅限擁有者命令/工具的明確擁有者 allowlist。它與 allowFrom 分開。
ownerDisplay: "hash" 會在系統提示中雜湊擁有者 id。設定 ownerDisplaySecret 可控制雜湊。
allowFrom 是逐 provider 設定。設定後，它就是唯一授權來源（channel allowlists/配對和 useAccessGroups 會被忽略）。
useAccessGroups: false 允許命令在未設定 allowFrom 時繞過存取群組政策。
命令文件對應：
- 內建 + bundled 目錄：Slash Commands
- channel 特定命令介面：Channels
- QQ Bot 命令：QQ Bot
- 配對命令：配對
- LINE 卡片命令：LINE
- 記憶體 Dreaming：Dreaming

Gateway

Remote access

Security

Nodes and media

Web interfaces

設定 — 頻道

頻道

DM 與群組存取

頻道模型覆寫

頻道預設值與 Heartbeat

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

iMessage

Matrix

Microsoft Teams

IRC

多帳戶（所有頻道）

其他 Plugin 頻道

群組聊天提及門控

DM 歷史記錄限制

自我聊天模式

命令（聊天命令處理）

相關

Gateway

Remote access

Security

Nodes and media

Web interfaces

Documentation Index

​頻道

​DM 與群組存取

​頻道模型覆寫

​頻道預設值與 Heartbeat

​WhatsApp

​Telegram

​Discord

​Google Chat

​Slack

​Mattermost

​Signal

​iMessage

​Matrix

​Microsoft Teams

​IRC

​多帳戶（所有頻道）

​其他 Plugin 頻道

​群組聊天提及門控

​DM 歷史記錄限制

​自我聊天模式

​命令（聊天命令處理）

​相關

頻道

DM 與群組存取

頻道模型覆寫

頻道預設值與 Heartbeat

WhatsApp

Telegram

Discord

Google Chat

Slack

Mattermost

Signal

iMessage

Matrix

Microsoft Teams

IRC

多帳戶（所有頻道）

其他 Plugin 頻道

群組聊天提及門控

DM 歷史記錄限制

自我聊天模式

命令（聊天命令處理）

相關