IT架构师

奔赴山海，保持热爱

0%

OpenClaw Satori Channel 插件详解：连接 QQ/Telegram/Discord/飞书的全能聊天机器人

发表于 更新于 分类于 ，
本文字数： 11k 阅读时长 ≈ 19 分钟
openclaw-satori-channel 是 OpenClaw 的频道插件，通过 Satori 协议连接 QQ、Telegram、Discord、飞书等多个聊天平台。本文详解架构、部署、配置和实战应用。

OpenClaw Satori Channel 插件详解：连接 QQ/Telegram/Discord/飞书的全能聊天机器人

写在前面：openclaw-satori-channel 是一个强大的 OpenClaw 频道插件，让你的 AI 助手能够连接任何支持 Satori 协议的聊天平台——包括 QQ、Telegram、Discord、飞书、LINE 等。通过 Koishi 作为中介，实现统一的聊天机器人部署。

一、项目概述

1.1 核心定位

openclaw-satori-channel 是一个 OpenClaw 频道插件，主要功能：

  • ✅ 多平台支持 - QQ、Telegram、Discord、飞书、LINE 等
  • ✅ Satori 协议 - 统一的聊天协议标准
  • ✅ Koishi 集成 - 通过 Koishi 连接各平台
  • ✅ 实时通信 - WebSocket 双向消息流
  • ✅ 权限管理 - DM 白名单、群组策略、@提及控制

项目信息：

1.2 工作原理

1
2
3
4
5
6
7
8
9
QQ / 飞书 / Telegram / Discord / ...
        ↓  (平台适配器)
    Koishi 实例
        ↓  (@koishijs/plugin-server-satori)
  Satori 协议端点  (ws://localhost:5140/satori/v1/events)
        ↓
  openclaw-satori-channel
        ↓
     OpenClaw AI Agent

数据流：

  1. 用户在 QQ/Telegram 等平台发送消息
  2. Koishi 通过平台适配器接收消息
  3. Koishi 将消息转换为 Satori 协议
  4. openclaw-satori-channel 通过 WebSocket 接收
  5. OpenClaw AI 处理消息并生成回复
  6. 回复通过 Satori HTTP API 发送回 Koishi
  7. Koishi 通过平台适配器发送给用户

二、核心架构

2.1 技术组件

组件 作用 说明
Koishi 聊天机器人框架 连接各聊天平台
Satori 协议 统一通信协议 标准化消息格式
openclaw-satori-channel OpenClaw 插件 连接 OpenClaw 和 Satori
OpenClaw AI 助手框架 处理消息和生成回复
平台适配器 平台接入 OneBot、Telegram、Discord 等

2.2 消息格式

Satori 消息对象：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "message-123",
  "type": "message",
  "channel": {
    "id": "200000001",
    "type": 2  // 1=私聊，2=群组
  },
  "user": {
    "id": "100000001",
    "name": "username"
  },
  "content": "Hello OpenClaw!",
  "elements": [
    {
      "type": "text",
      "attrs": {
        "content": "Hello OpenClaw!"
      }
    }
  ],
  "timestamp": 1710604800000
}

2.3 Session Key 格式

每个对话通过唯一的 Session Key 标识：

1
agent:main:satori-channel:{platform}:{chatType}:{peerId}

字段说明：

字段 值 说明
platform onebot, telegram, feishu 平台标识
chatType direct, group 私聊/群组
peerId 用户 ID/群组 ID 对话标识

示例：

1
2
3
agent:main:satori-channel:onebot:direct:100000001  // QQ 私聊
agent:main:satori-channel:onebot:group:200000001   // QQ 群组
agent:main:satori-channel:telegram:direct:100000001 // Telegram 私聊

三、部署流程

3.1 前置要求

组件 版本要求 说明
OpenClaw >= 2026.0.0 AI 助手框架
Node.js >= 18.0.0 运行环境
Koishi 最新版 聊天机器人框架
Satori Server 最新版 Koishi 插件

3.2 步骤 1：安装 Koishi

1
2
3
4
5
6
7
8
9
# 使用官方模板创建 Koishi 实例
git clone https://github.com/koishijs/koishi-starter
cd koishi-starter

# 安装依赖
npm install

# 启动 Koishi
npm start

访问 Koishi 控制台：

1
http://localhost:5140

3.3 步骤 2：安装平台适配器

在 Koishi 插件市场安装并配置平台适配器：

QQ (OneBot)：

1
npm install @koishijs/adapter-onebot

配置：

1
2
3
4
5
# Koishi 配置文件
adapters:
  onebot:
    protocol: ws
    endpoint: ws://127.0.0.1:6700

Telegram：

1
npm install @koishijs/adapter-telegram

配置：

1
2
3
adapters:
  telegram:
    token: YOUR_BOT_TOKEN

Discord：

1
npm install @koishijs/adapter-discord

飞书：

1
npm install @koishijs/adapter-feishu

3.4 步骤 3：启用 Satori Server

在 Koishi 中安装并启用 Satori Server 插件：

1
npm install @koishijs/plugin-server-satori

配置：

1
2
3
4
plugins:
  server-satori:
    path: /satori
    port: 5140

端点信息：

1
2
WebSocket: ws://localhost:5140/satori/v1/events
HTTP API:  http://localhost:5140/satori/v1/

3.5 步骤 4：安装 openclaw-satori-channel

1
2
3
4
5
6
7
# 克隆插件
cd /home/johnzok/.openclaw/plugins
git clone https://github.com/DoiiarX/openclaw-satori-channel.git

# 安装依赖
cd openclaw-satori-channel
npm install

3.6 步骤 5：配置 OpenClaw

编辑 openclaw.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "plugins": {
    "allow": ["satori-channel"],
    "load": {
      "paths": ["/home/johnzok/.openclaw/plugins/openclaw-satori-channel"]
    },
    "entries": {
      "satori-channel": {
        "enabled": true
      }
    }
  },
  "channels": {
    "satori-channel": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "host": "localhost",
          "port": 5140,
          "path": "/satori",
          "platform": "onebot",
          "selfId": "123456789",
          "token": "",
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["your_qq_number"],
          "requireMention": true
        }
      }
    }
  }
}

3.7 步骤 6：重启 OpenClaw

1
2
3
4
5
# 重启 OpenClaw Gateway
openclaw gateway restart

# 检查状态
openclaw status

四、配置详解

4.1 完整配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "channels": {
    "satori-channel": {
      "enabled": true,
      "defaultAccount": "default",
      "accounts": {
        "default": {
          "host": "localhost",
          "port": 5140,
          "path": "/satori",
          "platform": "onebot",
          "selfId": "123456789",
          "token": "",
          "enabled": true,
          "allowFrom": ["111222333"],
          "defaultTo": "",
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["111222333", "444555666"],
          "requireMention": true
        },
        "telegram": {
          "host": "localhost",
          "port": 5140,
          "path": "/satori",
          "platform": "telegram",
          "selfId": "telegram_bot_id",
          "token": "",
          "groupPolicy": "open",
          "requireMention": false
        }
      }
    }
  }
}

4.2 配置字段说明

字段 类型 默认值 说明
host string "localhost" Satori 服务器地址
port number 5140 Satori 服务器端口
path string "" 路径前缀，必须与 Koishi 配置一致
platform string "unknown" 平台标识（onebot/telegram/feishu）
selfId string — 机器人在平台的用户 ID
token string — Satori 服务器认证 Token
enabled boolean true 启用/禁用此账号
allowFrom string[] — 允许私聊的用户 ID 列表
defaultTo string — 默认发送消息的频道 ID
groupPolicy "open"|"allowlist"|"disabled" "allowlist" 群组消息策略
groupAllowFrom string[] — 允许在群组发言的用户 ID
requireMention boolean true 是否需要@机器人才能回复

4.3 权限系统

三道权限门：

Gate 1 - 私聊白名单

1
2
3
4
5
// 只允许特定用户私聊
{ "allowFrom": ["111222333", "444555666"] }

// 允许所有人私聊
{ "allowFrom": ["*"] }

Gate 2 - 群组策略

1
2
3
4
5
6
7
8
// 只允许特定用户在群组发言（默认）
{ "groupPolicy": "allowlist", "groupAllowFrom": ["111222333"] }

// 允许群组所有人发言
{ "groupPolicy": "open" }

// 禁用所有群组消息
{ "groupPolicy": "disabled" }

Gate 3 - @提及控制

1
2
3
4
5
// 只在被@时回复（默认）
{ "requireMention": true }

// 回复所有消息
{ "requireMention": false }

注意：groupAllowFrom 列表中的用户即使在 requireMention: true 时也可以无需@直接触发回复。

五、实战应用场景

5.1 QQ 机器人

场景：在 QQ 群部署 AI 助手

配置：

1
2
3
4
5
6
7
{
  "platform": "onebot",
  "selfId": "123456789",
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["群主 QQ", "管理员 QQ"],
  "requireMention": true
}

使用方式：

  • 群成员：@机器人 今天天气怎么样？
  • 机器人：今天天气晴朗，气温 25°C...

5.2 Telegram 机器人

场景：个人 AI 助手

配置：

1
2
3
4
5
6
{
  "platform": "telegram",
  "selfId": "telegram_bot_id",
  "groupPolicy": "open",
  "requireMention": false
}

使用方式：

  • 私聊直接发送消息
  • 群组中自由发言

5.3 飞书机器人

场景：企业 AI 助手

配置：

1
2
3
4
5
6
7
{
  "platform": "feishu",
  "selfId": "feishu_bot_id",
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["员工飞书 ID"],
  "requireMention": true
}

使用方式：

  • 工作群咨询问题
  • 文档查询
  • 日程管理

5.4 Discord 机器人

场景：社区 AI 助手

配置：

1
2
3
4
5
6
{
  "platform": "discord",
  "selfId": "discord_bot_id",
  "groupPolicy": "open",
  "requireMention": true
}

使用方式：

  • 社区问答
  • 新手引导
  • 活动组织

六、高级功能

6.1 多平台支持

配置多个平台账号：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "accounts": {
    "qq": {
      "platform": "onebot",
      "selfId": "qq_bot_id",
      "groupPolicy": "allowlist"
    },
    "telegram": {
      "platform": "telegram",
      "selfId": "tg_bot_id",
      "groupPolicy": "open"
    },
    "feishu": {
      "platform": "feishu",
      "selfId": "feishu_bot_id",
      "groupPolicy": "allowlist"
    }
  }
}

6.2 消息类型支持

支持的消息类型：

类型 说明 示例
文本 纯文本消息 Hello
图片 图片消息 [图片]
音频 语音消息 [语音]
视频 视频消息 [视频]
文件 文件传输 [文件]
@提及 提及用户 @user

6.3 自动重连

内置自动重连机制：

1
2
3
// 指数退避策略
重试间隔：1s → 2s → 4s → 8s → 16s → 32s
最大重试：无限

6.4 状态追踪

监控插件状态：

1
2
3
4
5
6
{
  "status": "connected",
  "reconnectAttempts": 0,
  "lastInbound": "2026-03-17T00:30:00Z",
  "lastOutbound": "2026-03-17T00:31:00Z"
}

七、故障排查

7.1 常见问题

问题 1：无法连接 Satori 服务器

1
2
3
4
5
6
7
8
# 检查 Koishi 是否运行
systemctl status koishi

# 检查 Satori Server 插件
curl http://localhost:5140/satori/v1/

# 检查 WebSocket 连接
wscat -c ws://localhost:5140/satori/v1/events

解决：

  • 确保 Koishi 正常运行
  • 检查 Satori Server 插件已启用
  • 确认路径配置一致

问题 2：消息不回复

1
2
3
4
5
# 检查权限配置
cat openclaw.json | jq '.channels.satori-channel'

# 检查用户是否在白名单
# 检查 requireMention 设置

解决：

  • 确认用户在 allowFrom 或 groupAllowFrom 列表中
  • 检查 requireMention 设置
  • 查看 OpenClaw 日志

问题 3：平台消息接收失败

1
2
3
4
5
# 检查 Koishi 平台适配器
koishi status

# 检查平台 Token 是否有效
# 检查网络连接

解决：

  • 重新配置平台适配器
  • 更新 Token
  • 检查网络防火墙

7.2 日志查看

1
2
3
4
5
6
7
8
# OpenClaw 日志
tail -f ~/.openclaw/logs/gateway.log

# Koishi 日志
tail -f ~/.koishi/koishi.log

# Satori Server 日志
tail -f ~/.koishi/logs/satori-server.log

八、性能优化

8.1 WebSocket 连接优化

1
2
3
4
5
6
7
8
9
10
11
{
  "heartbeat": {
    "interval": 30000,
    "timeout": 90000
  },
  "reconnect": {
    "maxAttempts": 10,
    "initialDelay": 1000,
    "maxDelay": 30000
  }
}

8.2 消息处理优化

1
2
3
4
5
6
{
  "messageQueue": {
    "maxSize": 1000,
    "concurrency": 5
  }
}

8.3 资源限制

1
2
3
4
5
6
7
8
9
10
{
  "limits": {
    "maxMessageLength": 2000,
    "maxAttachments": 5,
    "rateLimit": {
      "window": 60000,
      "maxRequests": 60
    }
  }
}

九、安全加固

9.1 Token 保护

1
2
3
4
5
6
7
8
9
{
  "accounts": {
    "default": {
      "token": "${SATORI_TOKEN}",  // 使用环境变量
      "host": "localhost",  // 限制为本地
      "groupPolicy": "allowlist"
    }
  }
}

9.2 访问控制

1
2
3
4
5
6
{
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["信任的用户 ID"],
  "allowFrom": ["信任的用户 ID"],
  "requireMention": true
}

9.3 速率限制

1
2
3
4
5
6
7
{
  "rateLimit": {
    "enabled": true,
    "window": 60000,  // 1 分钟
    "maxRequests": 60  // 最多 60 条消息
  }
}

十、总结

10.1 核心优势

优势 说明
多平台支持 QQ/Telegram/Discord/飞书等
统一协议 Satori 标准化
易于部署 Koishi 一键安装
权限完善 三道权限门
实时通信 WebSocket 双向流

10.2 适用场景

  • 🤖 QQ 机器人 - 群组 AI 助手
  • 💬 Telegram 机器人 - 个人 AI 助手
  • 🏢 飞书机器人 - 企业 AI 助手
  • 🎮 Discord 机器人 - 社区 AI 助手
  • 📱 多平台部署 - 统一 AI 助手

10.3 下一步优化

  • 🔧 自动化部署 - Docker 容器化
  • 🔧 监控告警 - Prometheus + Grafana
  • 🔧 消息队列 - Redis/RabbitMQ
  • 🔧 负载均衡 - 多实例部署

参考资源

  1. 项目 GitHub: https://github.com/DoiiarX/openclaw-satori-channel
  2. Satori 协议: https://satori.chat/
  3. Koishi 文档: https://koishi.chat/
  4. OpenClaw 文档: https://openclaw.dev
  5. OneBot 协议: https://onebot.dev/

本文是 OpenClaw 插件系列的第 106 篇，下一篇将介绍如何开发自定义的 OpenClaw 频道插件。