适用于 OpenClaw v2026.2 | 本文假设你已完成 OpenClaw 安装，有一个可用的 Telegram Bot Token（免费获取）。

TL;DR: Telegram 是配置最简单的渠道：创建 Bot（@BotFather）、获取 Token、配置到 ~/.openclaw/openclaw.json、启动 Gateway。默认启用 DM 配对保护，群组需 @提及才响应。同时覆盖 WhatsApp（扫码登录）、Discord（Bot Token）、Slack 配置。

为什么从 Telegram 开始？

渠道对比

选择 Telegram 的理由

1. 配置最简单：只需创建 Bot 获取 Token 即可
2. 文档最完善：Telegram Bot API 是业界标杆
3. 功能最丰富：支持命令、按钮、内联查询等
4. 社区最活跃：问题容易找到解决方案

Telegram Bot 创建

步骤 1：找到 BotFather

1. 打开 Telegram 应用
2. 搜索 @BotFather（官方 Bot 管理工具）
3. 点击进入对话

sequenceDiagram
    participant U as 你
    participant BF as BotFather
    participant TG as Telegram
    
    U->>BF: /newbot
    BF->>U: 输入 Bot 显示名称
    U->>BF: My OpenClaw Assistant
    BF->>U: 输入 Bot 用户名（必须以 bot 结尾）
    U->>BF: myclaw_bot
    BF->>TG: 创建 Bot
    TG-->>BF: Bot 创建成功
    BF->>U: 返回 API Token

步骤 2：创建新 Bot

在 BotFather 中发送命令：

/newbot

按提示操作：

1. Bot 显示名称：如 My OpenClaw（可以有空格）
2. Bot 用户名：如 myclaw_bot（必须以 bot 结尾）

创建成功后，BotFather 会返回：

Done! Congratulations on your new bot...

Use this token to access the HTTP API:
7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your token secure...

⚠️ 重要：妥善保管 API Token，它拥有完全控制你 Bot 的权限。

步骤 3：配置 Bot 信息（可选）

# 在 BotFather 中设置 Bot 头像
/setuserpic
# 选择你的 Bot，上传图片

# 设置 Bot 描述
/setdescription
# 选择你的 Bot，输入描述文字

# 设置 Bot 简介
/setabouttext
# 选择你的 Bot，输入简介文字

# 设置 Bot 命令
/setcommands
# 输入命令列表，如：
# start - 开始使用
# help - 获取帮助
# status - 查看状态

配置 OpenClaw

方式 A：环境变量（快速测试）

# 设置环境变量
export TELEGRAM_BOT_TOKEN="7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 启动 Gateway
openclaw gateway

方式 B：配置文件（推荐生产）

编辑 ~/.openclaw/openclaw.json：

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "channels": {
    "telegram": {
      "botToken": "7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  }
}

方式 C：使用 CLI 配置

# 交互式配置
openclaw config set channels.telegram.botToken "7123456789:AAH..."

# 或通过 onboard 向导
openclaw onboard

验证配置

# 检查配置
openclaw config get channels.telegram.botToken

# 运行诊断
openclaw doctor

# 启动 Gateway（调试模式）
openclaw gateway --verbose

成功启动后，你应该看到类似日志：

[INFO] Gateway starting on port 18789
[INFO] Telegram channel connected
[INFO] Bot: @myclaw_bot
[INFO] Waiting for messages...

安全配置

DM 配对机制

默认情况下，OpenClaw 启用 DM 配对机制（dmPolicy: "pairing"），防止陌生人滥用你的 Bot。

sequenceDiagram
    participant S as 陌生人
    participant B as Bot
    participant G as Gateway
    participant O as 你
    
    S->>B: 发送消息 "你好"
    B->>G: 消息到达
    G->>G: 检查配对状态
    G-->>B: 未配对，返回配对码
    B-->>S: "请配对：配对码 ABC123"
    S->>O: 告诉你配对码
    O->>G: openclaw pairing approve telegram ABC123
    G->>G: 添加到白名单
    G-->>S: 配对成功，可以对话

配置 DM 策略

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "dmPolicy": "pairing",
      "allowFrom": []
    }
  }
}

管理配对请求

# 查看待配对列表
openclaw pairing list

# 输出示例：
# Channel    Code     User        Created
# telegram   ABC123   @stranger   2026-02-26 10:30:00

# 批准配对
openclaw pairing approve telegram ABC123

# 拒绝配对
openclaw pairing reject telegram ABC123

# 查看已配对用户
openclaw pairing show telegram

白名单模式

只允许特定用户发送消息：

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "dmPolicy": "open",
      "allowFrom": [123456789, 987654321]
    }
  }
}

💡 获取 Telegram 用户 ID：向 @userinfobot 发送任意消息，它会返回你的数字 ID。

群组配置

基本群组设置

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

多群组差异化配置

{
  "channels": {
    "telegram": {
      "botToken": "your_token",
      "groups": {
        "-100123456789": {
          "requireMention": false,
          "name": "工作群"
        },
        "-100987654321": {
          "requireMention": true,
          "name": "闲聊群"
        },
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

💡 获取群组 ID：将 Bot 添加到群组后，在群组中发送任意消息，查看 Gateway 日志即可看到群组 ID。

添加 Bot 到群组

1. 在群组设置中点击「添加成员」
2. 搜索你的 Bot 用户名（如 @myclaw_bot）
3. 选择添加
4. （可选）将 Bot 设为管理员以获取更多权限

WhatsApp 配置

方式：扫码登录

WhatsApp 使用 Web 协议，需要扫码绑定：

# 启动登录流程
openclaw channels login whatsapp

# 终端显示二维码
# 使用手机 WhatsApp 扫描：
# 设置 > 已关联的设备 > 关联设备 > 扫描二维码

sequenceDiagram
    participant U as 用户
    participant C as CLI
    participant W as WhatsApp
    participant G as Gateway
    
    U->>C: openclaw channels login whatsapp
    C->>W: 请求二维码
    W-->>C: 返回二维码
    C->>U: 显示二维码
    U->>W: 手机扫码
    W-->>C: 认证成功
    C->>G: 保存认证信息
    G-->>U: WhatsApp 已连接

配置示例

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

WhatsApp 限制

Discord 配置

创建 Discord Bot

1. 访问 Discord Developer Portal
2. 点击「New Application」
3. 输入名称，如 OpenClaw Assistant
4. 进入「Bot」页面，点击「Add Bot」
5. 复制 Token（注意不是 Application ID）

配置 OAuth2 权限

1. 进入「OAuth2」>「URL Generator」
2. 勾选以下权限：

3. 复制生成的邀请链接
4. 在浏览器打开链接，将 Bot 邀请到服务器

配置示例

{
  "channels": {
    "discord": {
      "token": "MTk4NjIyNDgzNDc...",
      "guilds": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

Discord 特性配置

{
  "channels": {
    "discord": {
      "token": "your_token",
      "commands": {
        "native": true,
        "text": true
      },
      "mediaMaxMb": 25
    }
  }
}

Slack 配置

创建 Slack App

1. 访问 Slack API
2. 点击「Create New App」
3. 选择「From scratch」
4. 输入 App 名称，选择工作区

配置 OAuth 权限

在「OAuth & Permissions」页面添加以下 Bot Token Scopes：

app_mentions:read
channels:history
channels:read
chat:write
files:read
files:write
groups:history
groups:read
im:history
im:read
im:write
mpim:history
mpim:read
mpim:write
reactions:read
reactions:write
users:read

安装到工作区

1. 点击「Install to Workspace」
2. 授权权限
3. 复制 Bot User OAuth Token（以 xoxb- 开头）

配置示例

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "signingSecret": "..."
    }
  }
}

启用 Socket Mode（推荐）

1. 在「Socket Mode」页面启用
2. 生成 App-Level Token
3. 配置到 OpenClaw：

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "socketMode": true
    }
  }
}

多渠道同时启用

完整配置示例

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  },
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "channels": {
    "telegram": {
      "botToken": "telegram_bot_token",
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "whatsapp": {
      "allowFrom": ["+8613800138000"]
    },
    "discord": {
      "token": "discord_token",
      "guilds": {
        "*": { "requireMention": true }
      }
    },
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-..."
    }
  }
}

消息路由示意

flowchart TB
    subgraph Users["用户"]
        WA[WhatsApp 用户]
        TG[Telegram 用户]
        DC[Discord 用户]
        SL[Slack 用户]
    end
    
    subgraph Gateway["Gateway"]
        MR[Message Router]
        SM[Session Manager]
    end
    
    subgraph Agent["Pi Agent"]
        AI[AI 核心]
        CTX[共享上下文]
    end
    
    WA --> MR
    TG --> MR
    DC --> MR
    SL --> MR
    MR --> SM
    SM --> AI
    AI --> CTX

所有渠道共享同一个 Agent，上下文统一管理。这意味着：

• 在 Telegram 问的问题，可以在 WhatsApp 继续讨论
• 不同渠道的用户可以共享同一份记忆
• 每个渠道可以有独立的会话隔离策略

会话管理命令

所有渠道通用命令（在聊天中发送）：

故障排查

Telegram Bot 无响应

症状：发送消息后无回复

排查步骤：

# 1. 检查 Gateway 是否运行
curl http://127.0.0.1:18789/health

# 2. 检查 Bot Token
openclaw config get channels.telegram.botToken

# 3. 查看详细日志
openclaw gateway --verbose

# 4. 使用 doctor 诊断
openclaw doctor

常见原因：

WhatsApp 扫码失败

症状：扫码后显示失败

解决方案：

# 重新生成二维码
openclaw channels logout whatsapp
openclaw channels login whatsapp

# 检查网络
ping web.whatsapp.com

# 清除凭据缓存
rm -rf ~/.openclaw/credentials/whatsapp*

Discord Bot 无权限

症状：Bot 在服务器中无响应或无权限

解决方案：

1. 检查 Bot 角色权限
2. 确认 Bot 已被邀请到服务器
3. 重新邀请 Bot（使用正确的 OAuth URL）

# 查看日志中的权限错误
openclaw gateway --verbose 2>&1 | grep -i permission

配置不生效

症状：修改配置后行为未变化

解决方案：

# 1. 重启 Gateway
openclaw gateway --restart

# 2. 清除缓存
rm -rf ~/.openclaw/cache/*

# 3. 验证配置文件语法
cat ~/.openclaw/openclaw.json | jq .

# 4. 检查配置优先级
openclaw config list

安全最佳实践

1. Token 安全

# 不要将 Token 提交到版本控制
echo ".openclaw/" >> .gitignore

# 使用环境变量存储敏感信息
export TELEGRAM_BOT_TOKEN="your_token"

# 定期轮换 Token（在 BotFather 中）
# /revoke 命令可以重新生成 Token

2. 访问控制

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"
      }
    }
  }
}

3. 日志审计

# 启用详细日志
openclaw gateway --verbose

# 查看会话历史
openclaw sessions list
openclaw sessions show <session-id>

# 审计命令执行
grep "bash" ~/.openclaw/logs/gateway.log

下一步

恭喜！你已经完成了第一个渠道的配置。现在可以：

1. 测试对话 → 在配置的渠道中发送消息
2. 安装 Skills → 扩展 AI 能力
3. 配置多渠道 → 添加更多渠道

本篇小结：

• 掌握了 Telegram Bot 创建和配置
• 理解了 DM 配对和群组配置
• 学会了 WhatsApp、Discord、Slack 的配置方法
• 了解了多渠道同时启用的方式
• 掌握了常见问题的排查方法

更新记录：

• 2026-02-26：初版发布，基于 OpenClaw v2026.2

系列导航：

• ← 上一篇：环境搭建与首次运行
• → 下一篇：Gateway 核心概念解析