"通道配置详解"

龙虾学堂2026年5月7日

"深入解析 OpenClaw 的通道配置机制，掌握多平台接入与消息路由的核心逻辑"

通道配置详解

本文聚焦：通道配置的核心字段 + 多平台消息路由机制

前置知识：模型配置详解相关阅读：配置 Telegram Provider

通道（Channel）是 OpenClaw 与外部世界通信的桥梁。无论是 Telegram、飞书还是 Discord，都需要通过通道配置来接入。理解通道的工作机制，是构建多平台 AI 助手的关键。

配置文件位置：~/.openclaw/openclaw.json（Linux/macOS）或 %USERPROFILE%\.openclaw\openclaw.json（Windows）

知识点 1：通道配置的核心字段

通道的基本结构

在 openclaw.json 中，通道配置位于 channels 对象下，每个通道都有一个唯一的标识符作为键：

{
  "channels": {
    "telegram-main": {
      "kind": "telegram",
      "token": "${TELEGRAM_BOT_TOKEN}",
      "defaultAgent": "main"
    },
    "feishu-work": {
      "kind": "feishu",
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "defaultAgent": "main"
    }
  }
}

通用字段说明

所有通道类型都支持以下通用字段：

字段	类型	必填	说明
`kind`	string	✅	通道类型标识（如 `telegram`、`feishu`）
`defaultAgent`	string	❌	默认路由到的 Agent 名称
`enabled`	boolean	❌	是否启用该通道（默认 `true`）

平台特有字段

不同平台需要不同的认证凭据：

Telegram 通道：

{
  "kind": "telegram",
  "token": "123456789:ABCdefGHIjklMNOpqrSTUvwxyz",
  "defaultAgent": "main",
  "webhookUrl": "https://your-domain.com/webhook/telegram"
}

字段	说明
`token`	Bot Token，从 @BotFather 获取（详见创建 Telegram Bot）
`webhookUrl`	可选，自定义 webhook 接收地址。默认使用长轮询（polling），如需使用 webhook 需配置公网可访问的 HTTPS 地址

飞书通道：

{
  "kind": "feishu",
  "appId": "cli_xxxxxxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "defaultAgent": "main",
  "encryptKey": "${FEISHU_ENCRYPT_KEY}"
}

字段	说明
`appId`	飞书应用的 App ID
`appSecret`	飞书应用的 App Secret
`encryptKey`	可选，消息加密密钥。在飞书开放平台「事件订阅」-「加密策略」中获取

⚠️ 重要：飞书通道还需要在飞书开放平台配置「事件订阅」的 Request URL，请参考配置 Feishu Provider

Discord 通道：

{
  "kind": "discord",
  "token": "${DISCORD_BOT_TOKEN}",
  "defaultAgent": "main",
  "intents": ["Guilds", "GuildMessages", "MessageContent"]
}

字段	说明
`token`	Discord Bot Token
`intents`	Gateway Intents，用于订阅特定事件（如 `MessageContent` 用于接收消息内容）

注意：Discord 配置可能因 OpenClaw 版本而异，请参考对应版本文档确认具体配置方式。

知识点 2：多平台消息路由机制

什么是消息路由？

消息路由决定了「从哪个平台进来的消息，由哪个 Agent 处理」。OpenClaw 的路由机制非常灵活，支持多个层级：

用户消息 → 通道 → 路由决策 → Agent → 回复

路由优先级

OpenClaw 按以下优先级决定使用哪个 Agent：

消息中显式指定的 Agent（最高优先级）——通过 /agent <name> 命令切换
通道的 defaultAgent 配置
全局默认 Agent（配置文件中 defaultAgent 字段指定的 Agent，或第一个 Agent）

配置示例：多平台多 Agent

假设你有两个 Agent 和两个通道：

{
  "agents": {
    "general": {
      "provider": "gemini",
      "model": "gemini-2.0-flash",
      "systemPrompt": "你是通用助手，擅长日常问答。"
    },
    "coder": {
      "provider": "openai",
      "model": "gpt-4o",
      "systemPrompt": "你是代码专家，擅长编程和技术问题。"
    }
  },
  "channels": {
    "telegram-personal": {
      "kind": "telegram",
      "token": "${TELEGRAM_PERSONAL_BOT_TOKEN}",
      "defaultAgent": "general"
    },
    "telegram-dev": {
      "kind": "telegram",
      "token": "${TELEGRAM_DEV_BOT_TOKEN}",
      "defaultAgent": "coder"
    },
    "feishu-team": {
      "kind": "feishu",
      "appId": "${FEISHU_APP_ID}",
      "appSecret": "${FEISHU_APP_SECRET}",
      "defaultAgent": "general"
    }
  }
}

路由效果：

通道	默认 Agent	适用场景
`telegram-personal`	`general`	个人日常助手
`telegram-dev`	`coder`	开发者群组，处理代码问题
`feishu-team`	`general`	团队工作沟通

动态切换 Agent

用户可以在对话中通过 /agent 命令动态切换 Agent：

用户：/agent coder
系统：已切换到代码专家模式

用户：帮我写一个 Python 函数...
→ 由 coder Agent 处理

用户：/agent general
系统：已切换到通用助手模式

用户：今天天气怎么样？
→ 由 general Agent 处理

这种机制让同一个通道可以灵活使用不同的 Agent 能力。

配置生效与验证

环境变量设置

在启动 OpenClaw Gateway 之前，先设置环境变量：

# Linux/macOS
export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxyz"
export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 如需持久化，添加到 ~/.bashrc 或 ~/.zshrc

使配置生效

修改 openclaw.json 后，需要重启 Gateway 使配置生效：

# 重启 Gateway
openclaw gateway restart

# 或使用 Docker
docker-compose restart

验证通道状态

# 查看 Gateway 状态
openclaw gateway status

# 查看详细日志
tail -f ~/.openclaw/logs/gateway.log

验证 Token 有效性

Telegram：

# 测试 Bot Token 是否有效
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"

如果返回包含 "ok":true 的 JSON，说明 Token 有效。

实践建议

为不同场景配置专用通道

{
  "channels": {
    "telegram-private": { "defaultAgent": "personal" },
    "telegram-work": { "defaultAgent": "work" },
    "telegram-public": { "defaultAgent": "public" }
  }
}

使用环境变量管理密钥 永远不要把真实 token 写入配置文件：
```
{ "token": "${TELEGRAM_BOT_TOKEN}" }
```

在 Agent 级别配置工具限制 工具限制通常在 Agent 配置中设置：

{
  "agents": {
    "myagent": {
      "allowedTools": ["web_search", "read"]
    }
  }
}

监控通道健康状态 定期检查各通道的连接状态：
```
openclaw gateway status
```

为生产环境配置备用通道 重要场景建议配置多个通道作为备份：

{
  "channels": {
    "telegram-primary": { "enabled": true, ... },
    "telegram-backup": { "enabled": false, ... }
  }
}

常见陷阱

⚠️ 通道 ID 重复

{
  "channels": {
    "telegram": { ... },
    "telegram": { ... }  // ❌ 重复的键，后一个会覆盖前一个
  }
}

⚠️ 未设置 defaultAgent 如果通道没有设置 defaultAgent，且消息中没有指定 Agent，会使用全局默认 Agent。建议显式配置以避免意外。

⚠️ 混淆 kind 和 id

{
  "channels": {
    "my-telegram": {        // ← 这是通道 ID（自定义）
      "kind": "telegram",   // ← 这是通道类型（固定值）
      ...
    }
  }
}

⚠️ Token 权限不足

Telegram Bot 需要**关闭 Privacy Mode（隐私模式）**才能在群组中读取所有消息
飞书 Bot 需要在后台申请相应权限

故障排查

通道无法接收消息

检查 Gateway 是否运行
```
openclaw gateway status
```
检查日志
```
tail -f ~/.openclaw/logs/gateway.log
```
验证网络连接
- Telegram 需要访问外网
- 飞书需要能够接收 webhook 回调
检查 Token 权限
- Telegram：使用 /getMe API 测试
- 飞书：检查应用权限和事件订阅配置

消息发送失败

检查 Token 是否过期或被吊销
检查目标 Chat ID 是否正确
检查 Bot 是否被群组移除或禁言