---
title: "配置 Channel"
description: "配置 OpenClaw Channel：DM policy、group policy、mention gating、pairing、access groups、多账号、model override 和 Agent binding。"
verifiedAt: "2026-05-06"
---

Channel 是 OpenClaw 接入外部消息平台的边界。你可以把它理解成“谁能把消息送进 Agent”。新手配置 Channel 时，优先考虑访问控制，不要先追求接入的平台数量。

> [!NOTE]
> **这一章用 14 分钟换什么**：你会知道私信、群聊、mention、多账号、model override 和 channel binding 分别解决什么问题，并且能避免“为了跑通先 open”的危险配置。

## 1. 先理解 Channel 管什么

每个消息平台都有自己的账号、token、群组、thread 和身份格式，但 OpenClaw 把几个核心问题统一了：

- 这个渠道要不要启动。
- 哪些私信可以进来。
- 哪些群组可以进来。
- 群组消息是否必须 mention 才触发回复。
- 多账号时如何区分个人账号、工作账号和支持账号。
- 某个频道是否固定使用特定模型。
- 这个入口最终路由到哪个 Agent。

这些都是入口边界。入口边界配置错了，后面的 Agent、tools、workspace 配得再好也会被错误输入影响。

```mermaid
flowchart TD
    Sender["外部发送者"]
    Channel["Channel"]
    Access["DM / group access"]
    Mention["mention gating"]
    Binding["binding 选择 Agent"]
    Session["session key"]
    Agent["Agent"]

    Sender --> Channel
    Channel --> Access
    Access --> Mention
    Mention --> Binding
    Binding --> Session
    Session --> Agent

    style Channel fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Access fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Agent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

> [!IMPORTANT]
> **入口安全先于 Agent 能力**：一个陌生入口能触发完整 tools，比一个模型答错更危险。

## 2. 私信策略怎么选

官方 DM policy 有四类：

| DM policy | 行为 | 新手建议 |
|------|------|------|
| `pairing` | 默认；未知发送者收到一次性配对码，owner 批准后才能继续 | 首选 |
| `allowlist` | 只允许 `allowFrom` 或已配对 allow store 里的发送者 | 适合固定联系人 |
| `open` | 允许所有私信，但必须显式 `allowFrom: ["*"]` | 公开入口才考虑 |
| `disabled` | 忽略所有私信 | 只做群组或只做系统入口时用 |

新手默认选 `pairing` 或 `allowlist`。个人助手、家庭助手、工作助手都不应该默认 `open`。

`pairing` 有几个关键事实：

- pairing code 8 位、全大写、避开易混淆字符。
- pairing code 1 小时过期。
- 每个 channel 的 pending DM pairing request 默认最多 3 个。
- 批准 DM pairing code 只允许这个发送者私信访问，不会自动允许群组控制。

```bash
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
```

> [!WARNING]
> **`open` 不是“先跑通”的捷径**：`open` 只适合你明确在做公开入口，并且已经配好更窄的 tools、sandbox、session 隔离和审计。

## 3. 群组策略怎么选

群组比私信更容易出问题，因为群里每个人都可能说话，消息里还会夹杂转发、引用、链接和玩笑。

官方 group policy 的基本含义是：

| Group policy | 行为 | 新手建议 |
|------|------|------|
| `allowlist` | 默认；只允许配置过的群组或 sender | 首选 |
| `open` | 绕过群组 allowlist，但 mention gating 仍可生效 | 谨慎 |
| `disabled` | 阻止所有群组或房间消息 | 不接群时用 |

新手建议：群组先保持 `allowlist`，再开启 mention gating。只有当你能解释“这个群为什么可以触发 Agent”时，才把它放进允许列表。

如果 provider block 完全缺失，runtime group policy 会 fail-closed 回到 `allowlist` 并给启动 warning。这是好事：没配置清楚就不要让群消息进来。

## 4. Mention gating 为什么重要

群聊里不应该让 Agent 响应每一句话。Mention gating 的作用是：Agent 可以看到上下文，但只有被点名时才回复。

官方文档也强调，群组消息默认应该依赖 mention 或显式激活方式。新手配置时，先把 mention pattern 设得简单、明确，避免常用词误触发。

一个好规则是：群里的人需要有意识地叫它，它才行动。

WhatsApp 例子里，群组可以这样要求 mention：

```json5
{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          historyLimit: 50,
          mentionPatterns: ["@?openclaw"],
        },
      },
    ],
  },
}
```

> [!TIP]
> **mention pattern 越短越危险**：用产品名、bot 名或明确别名，不要用“助手”“帮我”这种高频词。

## 5. 多账号时先隔离 session

多账号不是多填几个 token。它会影响身份、审计、路由和上下文隔离。

如果同一个 Gateway 里有个人账号和工作账号，至少要想清楚：

- `accountId` 怎么命名，方便日志和路由区分。
- DM session 是否按 channel、account、peer 隔离。
- 不同账号是否路由到不同 Agent。
- 不同 Agent 是否使用不同 workspace 和 tools。

如果两个账号共享同一个 main session，个人上下文、工作上下文和权限暗示可能混在一起。

Session key 常见形状：

| 场景 | Session key 形状 |
|------|------|
| 默认直接消息 | `agent:<agentId>:<mainKey>` |
| 群组 | `agent:<agentId>:<channel>:group:<id>` |
| 频道 / 房间 | `agent:<agentId>:<channel>:channel:<id>` |
| Slack / Discord thread | 在基础 key 后追加 `:thread:{threadId}` |
| Telegram forum topic | 在 group key 里包含 `:topic:<topicId>` |

## 6. Channel binding 怎么选 Agent

OpenClaw 路由 inbound message 时会选择一个 Agent。大致顺序是：精确 peer、thread parent、Discord guild / roles、Slack team、account、channel、default agent。

这意味着 routing 是确定性的，不是模型临时选择。

| 你要实现 | 配置重点 |
|------|------|
| Slack 工作区进 support Agent | `bindings` 匹配 `teamId` |
| Telegram 某个群进 docs Agent | `bindings` 匹配 group peer |
| WhatsApp 工作账号进 work Agent | 匹配 channel + accountId |
| 默认入口进 main Agent | 设置 default agent 或让 `main` 兜底 |

> [!IMPORTANT]
> **模型不决定回复去哪**：回复回到消息来的 channel。Agent 选择由 host config 和 bindings 决定。

## 7. 按频道指定模型

`channels.modelByChannel` 适合把具体频道固定到某个模型。它只应服务明确场景：

- 高价值支持频道用强模型。
- 低风险通知频道用低成本模型。
- 截图或长上下文多的频道用更合适的模型。

不要把模型覆盖当成权限控制。模型更强不等于更安全；入口安全仍然靠 allowlist、mention、session 和 tools。

```json5
{
  channels: {
    modelByChannel: {
      telegram: {
        "-1000000000000": "openai/gpt-4.1-mini",
        "-1000000000000:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}
```

## 8. 支持哪些渠道

OpenClaw 支持多个消息平台同时接入。官方当前列出的入口包括 Discord、Feishu、Google Chat、IRC、LINE、Matrix、Mattermost、Microsoft Teams、Nextcloud Talk、QQ Bot、Signal、Slack、Telegram、Twitch、WebChat、WhatsApp、Zalo 等。

新手不要同时接十个平台。最快跑通通常是 Telegram；WhatsApp 需要 QR pairing，并且在磁盘上保留更多状态。

## 9. 新手常见坑

- 为了“先跑通”把 DM 设成 `open`。
- 群组开了 `open`，但 mention pattern 太宽。
- 多账号共用一个 workspace 和 session。
- 只配置 token，不配置 allowlist。
- 公开入口仍然加载完整 tools。
- 频道模型覆盖后，以为风险也被解决了。
- DM pairing 批准后，以为自动获得群组权限。
- bindings 没写清，导致工作入口落到 main Agent。

## 10. 怎么判断 Channel 配置健康

健康标准：

- 只接入当前真正要用的渠道。
- DM 默认是 `pairing` 或 `allowlist`。
- 群组默认是 `allowlist`，并要求 mention。
- 多账号能从日志里区分来源。
- 不同角色入口能路由到不同 Agent 或不同 workspace。
- `openclaw doctor` 没有访问控制相关警告。

新手先把一个渠道跑稳，再接第二个。不要同时接十个平台排错。

> [!IMPORTANT]
> **Channel 验收看四件事**：谁能私信、哪个群能触发、消息落到哪个 Agent、session 是否隔离；这四件说不清，就不要继续加新平台。

## 11. 本章自检

1. `pairing`、`allowlist`、`open`、`disabled` 的差异是什么？
2. 群聊为什么要先 allowlist，再做 mention gating？
3. Channel binding 和 model override 分别解决什么问题？

> [!IMPORTANT]
> **过关标准**：你能用一句话说清 —— “Channel 配置的核心不是接入更多平台，而是控制谁能进来、何时触发、落到哪个 Agent、使用哪个 session。”

## 12. 接下来去哪

<Cards>
  <Card href="/docs/openclaw/official/01-gateway-runtime/security-remote" title="安全与远程访问" description="Channel 入口清楚后，再看 Control UI、远程访问和共享入口风险。" />
  <Card href="/docs/openclaw/official/01-gateway-runtime/agents" title="Agent 配置" description="如果入口路由和 Agent 边界还没分清，先回到上一章。" />
  <Card href="/docs/openclaw/understanding/09-channel-security" title="理解：Channel 与安全" description="从原理篇继续核对入口、路由、session、tool policy 和 sandbox。" />
</Cards>

## 13. 官方资料

- [Configuration — channels](https://docs.openclaw.ai/gateway/config-channels)
- [Chat channels](https://docs.openclaw.ai/channels)
- [Group messages](https://docs.openclaw.ai/channels/group-messages)
- [Pairing](https://docs.openclaw.ai/channels/pairing)
- [Channel routing](https://docs.openclaw.ai/channels/channel-routing)
