第8章 常用聊天渠道接入 - 保姆级教程

详细的渠道接入教程，包括 QQ、飞书、钉钉、企业微信等平台。

🎯 本章目标

• 目标 1

• 目标 2

• 目标 3

• 目标 4

---

QQ 机器人接入

方案一：使用 napcat（推荐）

napcat 是新一代 QQ 机器人框架，更稳定可靠。

1. 安装 napcat

# 使用 Docker（推荐）
docker run -d \
  --name napcat \
  -p 3001:3001 \
  -v ~/napcat:/app/napcat \
  mlikiowa/napcat-docker:latest

2. 配置 napcat

编辑 ~/napcat/config/napcat.json：

{
  "http": {
    "enable": true,
    "host": "0.0.0.0",
    "port": 3001,
    "secret": "your_secret",
    "enableHeart": true,
    "enablePost": true,
    "postUrls": ["http://localhost:3000/webhook/qq"]
  }
}

3. 配置 OpenClaw

openclaw config set channels.qq.enabled true
openclaw config set channels.qq.protocol napcat
openclaw config set channels.qq.host localhost
openclaw config set channels.qq.port 3001
openclaw config set channels.qq.secret your_secret

4. 启动并测试

# 启动 OpenClaw
openclaw server

# 在 QQ 中发送消息测试
# @机器人 你好

方案二：使用 go-cqhttp

1. 下载 go-cqhttp

# Linux/macOS
wget https://github.com/Mrs4s/go-cqhttp/releases/download/v1.2.0/go-cqhttp_linux_amd64.tar.gz
tar -xzf go-cqhttp_linux_amd64.tar.gz

# 首次运行生成配置
./go-cqhttp

2. 配置 go-cqhttp

编辑 config.yml：

account:
  uin: 你的QQ号
  password: '你的密码'

servers:
  - http:
      host: 0.0.0.0
      port: 5700
      post:
        - url: 'http://localhost:3000/webhook/qq'
          secret: 'your_secret'

3. 配置 OpenClaw

openclaw config set channels.qq.enabled true
openclaw config set channels.qq.protocol go-cqhttp
openclaw config set channels.qq.host localhost
openclaw config set channels.qq.port 5700

---

飞书机器人接入（保姆级）

第一步：创建飞书应用

1. 访问 飞书开放平台

2. 点击"创建企业自建应用"

3. 填写应用信息：

   • 应用名称：OpenClaw Bot
   • 应用描述：AI 智能助手
   • 应用图标：上传图标

第二步：配置应用权限

在"权限管理"中添加以下权限：

• im:message - 获取与发送单聊、群组消息

• im:message:send_as_bot - 以应用身份发消息

• im:chat - 获取群组信息

• contact:user.base - 获取用户基本信息

第三步：配置事件订阅

1. 在"事件订阅"中添加请求网址：

   https://your-domain.com/webhook/feishu

2. 添加事件：

   • im.message.receive_v1 - 接收消息

第四步：获取凭证

在"凭证与基础信息"中获取：

• App ID

• App Secret

第五步：配置 OpenClaw

# 设置飞书配置
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.appId cli_xxxxx
openclaw config set channels.feishu.appSecret xxxxx
openclaw config set channels.feishu.verificationToken xxxxx
openclaw config set channels.feishu.encryptKey xxxxx

# 启动服务
openclaw server

第六步：配置 Nginx 反向代理

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /webhook/feishu {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

第七步：测试

1. 在飞书中搜索你的机器人

2. 发送消息：“你好”

3. 机器人应该会回复

---

钉钉机器人接入

企业内部机器人

1. 创建应用

1. 访问 钉钉开放平台

2. 创建企业内部应用

3. 获取 AppKey 和 AppSecret

2. 配置权限

添加以下权限：

• 企业内部通讯录只读权限

• 消息通知权限

3. 配置 OpenClaw

openclaw config set channels.dingtalk.enabled true
openclaw config set channels.dingtalk.appKey xxxxx
openclaw config set channels.dingtalk.appSecret xxxxx

群机器人（Webhook）

1. 创建群机器人

1. 在钉钉群中点击"群设置"

2. 选择"智能群助手"

3. 添加机器人，选择"自定义"

4. 获取 Webhook 地址

2. 配置安全设置

选择"加签"方式，获取密钥。

3. 使用示例

import crypto from 'crypto';

function signDingTalk(timestamp: number, secret: string): string {
  const stringToSign = `${timestamp}\n${secret}`;
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(stringToSign);
  return hmac.digest('base64');
}

// 发送消息
async function sendToDingTalk(webhook: string, secret: string, text: string) {
  const timestamp = Date.now();
  const sign = signDingTalk(timestamp, secret);
  
  await fetch(`${webhook}&timestamp=${timestamp}&sign=${encodeURIComponent(sign)}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      msgtype: 'text',
      text: { content: text }
    })
  });
}

---

企业微信应用接入

第一步：创建应用

1. 登录 企业微信管理后台

2. 进入"应用管理" → “创建应用”

3. 填写应用信息并创建

第二步：获取凭证

在应用详情页获取：

• AgentId

• Secret

• CorpId（企业ID）

第三步：配置接收消息

1. 设置"接收消息"的 URL：

   https://your-domain.com/webhook/wework

2. 设置 Token 和 EncodingAESKey

第四步：配置 OpenClaw

openclaw config set channels.wework.enabled true
openclaw config set channels.wework.corpId ww_xxxxx
openclaw config set channels.wework.agentId 1000002
openclaw config set channels.wework.secret xxxxx
openclaw config set channels.wework.token xxxxx
openclaw config set channels.wework.encodingAESKey xxxxx

---

Telegram Bot 接入

第一步：创建 Bot

1. 在 Telegram 中搜索 @BotFather

2. 发送 /newbot 命令

3. 按提示设置 Bot 名称和用户名

4. 获取 Bot Token

第二步：配置 OpenClaw

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.token xxxxx:xxxxx

第三步：设置 Webhook（可选）

# 使用 Webhook 模式（需要公网 IP）
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -d "url=https://your-domain.com/webhook/telegram"

# 或使用轮询模式（无需公网 IP）
openclaw config set channels.telegram.mode polling

---

Discord Bot 接入

第一步：创建应用

1. 访问 Discord Developer Portal

2. 点击"New Application"

3. 填写应用名称

第二步：创建 Bot

1. 在左侧菜单选择"Bot"

2. 点击"Add Bot"

3. 获取 Bot Token

第三步：配置权限

在"OAuth2" → "URL Generator"中：

1. 选择 Scopes：bot

2. 选择 Bot Permissions：

   • Send Messages
   • Read Message History
   • Use Slash Commands

第四步：邀请 Bot

复制生成的 URL，在浏览器中打开，选择服务器并授权。

第五步：配置 OpenClaw

openclaw config set channels.discord.enabled true
openclaw config set channels.discord.token xxxxx
openclaw config set channels.discord.clientId xxxxx

---

WebSocket 直连方式

适合没有公网 IP 的场景。

服务端配置

openclaw config set channels.websocket.enabled true
openclaw config set channels.websocket.port 3002
openclaw config set channels.websocket.path /ws

客户端连接

const ws = new WebSocket('ws://localhost:3002/ws');

ws.on('open', () => {
  console.log('Connected to OpenClaw');
  
  // 发送消息
  ws.send(JSON.stringify({
    type: 'message',
    content: '你好，OpenClaw！'
  }));
});

ws.on('message', (data) => {
  const response = JSON.parse(data);
  console.log('Response:', response.content);
});

认证配置

# 启用认证
openclaw config set channels.websocket.auth.enabled true
openclaw config set channels.websocket.auth.token your_secret_token

// 客户端带认证
const ws = new WebSocket('ws://localhost:3002/ws', {
  headers: {
    'Authorization': 'Bearer your_secret_token'
  }
});

---

多渠道统一管理

配置示例

{
  "channels": {
    "qq": {
      "enabled": true,
      "protocol": "napcat",
      "priority": 1
    },
    "feishu": {
      "enabled": true,
      "priority": 2
    },
    "telegram": {
      "enabled": true,
      "priority": 3
    }
  },
  "routing": {
    "strategy": "round-robin",
    "fallback": "telegram"
  }
}

消息路由

// 根据渠道类型路由
if (message.channel === 'qq') {
  // QQ 特定处理
} else if (message.channel === 'feishu') {
  // 飞书特定处理
}

// 统一处理
const response = await agent.process(message.content);
await channel.send(response);

最佳实践

1. 实践 1 - 说明

2. 实践 2 - 说明

3. 实践 3 - 说明

常见问题

问题 1

症状：错误描述

解决方案：

# 解决命令

下一步

• 第9章

• 返回目录

---

📚 本章小结

✅ 完成了主要学习目标
✅ 掌握了核心概念
✅ 实践了示例代码
✅ 了解了最佳实践

---

返回目录 | 上一章 | 下一章