Wiki AI

Gateway Channel 配置

5分钟阅读

channels.* 下的各 Channel 配置键，涵盖 DM/群组访问控制、多账号、@提及门控等。

通用访问策略

DM 策略

策略行为
pairing（默认）未知发送者获得一次性配对码，需 owner 审批
allowlist仅允许 allowFrom 中的发送者
open允许所有入站 DM（需 allowFrom: ["*"]）
disabled忽略所有入站 DM

群组策略

策略行为
allowlist（默认）仅匹配配置白名单的群组
open绕过群组白名单（@提及门控仍生效）
disabled阻止所有群组/房间消息

配对码 1 小时后过期，每个 channel 最多 3 个待处理 DM 配对请求。

Channel 默认值

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

按 Channel 覆盖模型

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

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      textChunkLimit: 4000,
      sendReadReceipts: true,
      groups: { "*": { requireMention: true } },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

多账号：

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {},
      },
    },
  },
}

Telegram

{
  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"] },
          },
        },
      },
      streaming: "partial",  // off | partial | block | progress
      replyToMode: "first",  // off | first | all | batched
      proxy: "socks5://localhost:9050",
    },
  },
}
  • Bot token：channels.telegram.botToken 或 TELEGRAM_BOT_TOKEN 环境变量
  • apiRoot 只填 API 根（如 https://api.telegram.org），不要加 /bot<TOKEN> 后缀

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["1234567890"],
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
      streaming: { mode: "progress" },  // Discord 默认 progress
      threadBindings: { enabled: true, idleHours: 24 },
      voice: {
        enabled: true,
        autoJoin: [{ guildId: "123456789012345678", channelId: "234567890123456789" }],
        tts: { provider: "openai", openai: { voice: "alloy" } },
      },
      execApprovals: {
        enabled: "auto",  // true | false | "auto"
        approvers: ["987654321098765432"],
        target: "dm",  // dm | channel | both
      },
    },
  },
}
  • Token：channels.discord.token 或 DISCORD_BOT_TOKEN
  • 投递目标使用 user:<id>（DM）或 channel:<id>（服务器频道），拒绝裸数字 ID
  • allowBots: true 允许机器人消息；"mentions" 仅接受提及机器人的机器人消息

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",  // Socket Mode 需要
      dmPolicy: "pairing",
      allowFrom: ["U123"],
      channels: {
        C123: { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
      streaming: { mode: "partial", nativeTransport: true },
      slashCommand: { enabled: true, name: "openclaw", ephemeral: true },
      typingReaction: "hourglass_flowing_sand",
      execApprovals: { enabled: "auto", approvers: ["U123"] },
    },
  },
}
  • Socket Mode 需要 botToken + appToken
  • HTTP Mode 需要 botToken + signingSecret
  • 投递目标：user:<id>（DM）或 channel:<id>

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      dm: { enabled: true, policy: "pairing" },
      groups: { "spaces/AAAA": { allow: true, requireMention: true } },
    },
  },
}

Signal

{
  channels: {
    signal: {
      enabled: true,
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      reactionNotifications: "own",  // off | own | all | allowlist
    },
  },
}

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      includeAttachments: false,
      actions: { reactions: true, edit: true, unsend: true },
    },
  },
}
  • 需要 Messages 数据库的完全磁盘访问权限
  • 优先使用 chat_id:<id> 目标，用 imsg chats --limit 20 列出聊天

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      encryption: true,
      autoJoin: "allowlist",  // off | allowlist | always
      accounts: {
        ops: { userId: "@ops:example.org", accessToken: "syt_ops_xxx" },
      },
    },
  },
}

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      chatmode: "oncall",  // oncall | onmessage | onchar
      groups: { "*": { requireMention: true } },
    },
  },
}

多账号（所有 Channel）

{
  channels: {
    telegram: {
      accounts: {
        default: { name: "Primary bot", botToken: "123456:ABC..." },
        alerts: { name: "Alerts bot", botToken: "987654:XYZ..." },
      },
    },
  },
}
  • default 账号在省略 accountId 时使用
  • 环境变量 token 只适用于 default 账号
  • 用 bindings[].match.accountId 将不同账号路由到不同 agent

群组 @提及门控

{
  messages: {
    visibleReplies: "automatic",
    groupChat: { visibleReplies: "message_tool" },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}
  • 元数据提及：原生平台 @提及
  • 文本模式：mentionPatterns 中的安全正则
  • messages.groupChat.visibleReplies: "message_tool"（默认）：普通最终回复保持私密，可见房间输出需要 message(action=send) 工具

命令配置

{
  commands: {
    native: "auto",
    text: true,
    bash: false,
    config: false,
    restart: true,
    ownerAllowFrom: ["discord:123456789012345678"],
  },
}

相关链接

关系图谱

反向链接