常见任务

每个渠道在 `channels.<provider>` 下都有自己的配置节。有关设置步骤，请参阅专门的渠道页面：

- [Discord](../../channels/discord.md) - `channels.discord`
- [Feishu](../../channels/feishu.md) - `channels.feishu`
- [Google Chat](../../channels/googlechat.md) - `channels.googlechat`
- [iMessage](../../channels/imessage.md) - `channels.imessage`
- [Mattermost](../../channels/mattermost.md) - `channels.mattermost`
- [Microsoft Teams](../../channels/msteams.md) - `channels.msteams`
- [Signal](../../channels/signal.md) - `channels.signal`
- [Slack](../../channels/slack.md) - `channels.slack`
- [Telegram](../../channels/telegram.md) - `channels.telegram`
- [WhatsApp](../../channels/whatsapp.md) - `channels.whatsapp`

所有渠道共用相同的 DM 策略模式：

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
```

设置主模型和可选的备用模型：

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
```

- `agents.defaults.models` 存储别名和按模型的设置；添加条目绝不会限制 `/model` 或 `--model` 覆盖。
- `agents.defaults.modelPolicy.allow` 是用于覆盖和模型选择器的显式允许列表。它接受精确的模型引用和 `provider/*` 通配符；省略它或使用 `[]` 即可允许任意模型。
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图片的缩小处理（默认 `1200`）；较低的值通常可减少截图密集型运行中的 vision-token 用量。
- 有关在聊天中切换模型，请参阅 [Models CLI](../../concepts/models.md)；有关认证轮换和回退行为，请参阅 [Model Failover](../../concepts/model-failover.md)。
- 对于自定义/自托管提供商，请参阅参考文档中的 [Custom providers](../config-tools.md#custom-providers-and-base-urls)。

DM 访问权限通过 `dmPolicy`（默认 `"pairing"`）按渠道控制：

- `"pairing"`：未知发送者会收到一个需批准的一次性配对码
- `"allowlist"`：仅允许 `allowFrom`（或已配对的允许存储）中的发送者
- `"open"`：允许所有入站 DM（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有 DM

对于群组，请使用 `groupPolicy`（`"allowlist" | "open" | "disabled"`）以及 `groupAllowFrom` 或特定于渠道的允许列表。

有关各渠道的详细信息，请参阅[完整参考](../config-channels.md#dm-and-group-access)。

群消息默认**要求提及（mention）**。可为每个代理配置触发模式。普通群组/渠道回复会自动发布；对于需要代理自行决定何时发言的共享房间，可选择使用 message-tool 路径：

```json5
{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)
      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context
    },
  },
  agents: {
    entries: {
      main: {
        default: true,
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    },
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **元数据提及**：原生 @提及（WhatsApp 点按提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全正则表达式模式
- **可见回复**：`messages.visibleReplies` 可全局要求通过 message-tool 发送；`messages.groupChat.visibleReplies` 可为群组/渠道覆盖此设置。
- 有关可见回复模式、按渠道覆盖以及自我聊天模式，请参阅[完整参考](../config-channels.md#group-chat-mention-gating)。

使用 `agents.defaults.skills` 设置共享基线，然后通过 `agents.entries.*.skills` 覆盖特定代理：

```json5
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    entries: {
      writer: { default: true }, // inherits github, weather
      docs: { skills: ["docs-search"] }, // replaces defaults
      "locked-down": { skills: [] }, // no skills
    },
  },
}
```

- 省略 `agents.defaults.skills` 表示默认不限制技能。
- 省略 `agents.entries.*.skills` 则继承默认设置。
- 将 `agents.entries.*.skills` 设为 `[]` 表示不启用任何技能。
- 请参阅 [Skills](../../tools/skills.md)、[Skills config](../../tools/skills-config.md) 以及 [Configuration Reference](../config-agents/workspace-and-bootstrap.md#agents-defaults-skills)。

为某个渠道或账号禁用或启用自动健康重启：

```json5
{
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
```

- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 来控制某个渠道或账号的自动重启。
- 有关运维排障，请参阅 [Health Checks](../health.md)；有关所有字段，请参阅[完整参考](../config-gateway.md#gateway)。