方式一：OpenAkita Desktop
图形化配置，支持开关、凭证填写、状态检测和一键重启，适合新手与运维同学。
Tutorial / IM Channels
IM 通道配置与平台端申请
本教程详细介绍如何为 OpenAkita 配置各 IM 通道，包含平台端完整的申请流程和配置步骤。
平台概览
推荐顺序：先完成 LLM 基础连通，再按平台逐个接入 IM 通道，最后统一做联调与上线检查。
| 平台 | 状态 | 接入方式 | 需要公网 IP | 安装命令 | 难度 |
|---|---|---|---|---|---|
| Telegram | 稳定 | Long Polling | 不需要 | 默认包含 | 低 |
| 飞书 | 稳定 | WebSocket 长连接 | 不需要 | pip install openakita[feishu] | 低 |
| 钉钉 | 稳定 | Stream 模式 | 不需要 | pip install openakita[dingtalk] | 低 |
| 企业微信 | 稳定 | WebSocket 长连接 | 不需要 | pip install openakita[wework] | 低 |
| 稳定 | WebSocket 长连接 | 不需要 | pip install openakita[qq] | 低 | |
| 微信 | 稳定 | iLink Bot API | 不需要 | pip install openakita[wechat] | 低 |
媒体类型支持（接收）
| 类型 | Telegram | 飞书 | 钉钉 | 企业微信 | 微信 | |
|---|---|---|---|---|---|---|
| 文字 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 |
| 图片 | 支持 | 支持 | 支持 | 单聊支持 | 支持 | 支持 |
| 语音 | Whisper 转写 | Whisper 转写 | Whisper 转写 | 不支持 | Whisper 转写 | Whisper 转写 |
| 文件 | 支持 | 支持 | 支持 | 不支持 | 支持 | 支持 |
| 视频 | 支持 | 支持 | 支持 | 不支持 | 支持 | 支持 |
媒体类型支持（发送）
| 类型 | Telegram | 飞书 | 钉钉 | 企业微信 | 微信 | |
|---|---|---|---|---|---|---|
| 文字 | 支持 | 支持 | 支持 | 支持（stream） | 支持 | 支持 |
| 图片 | 支持 | 支持 | 支持 | 支持（JPG/PNG） | 支持 | 支持 |
| 语音 | 支持 | 支持 | 降级为文件 | 不支持 | 支持 | 支持 |
| 文件 | 支持 | 支持 | 降级为链接 | 降级为文本 | 支持 | 支持 |
| 视频 | 支持 | 支持 | 支持 | 不支持 | 支持 | 支持 |
企业微信智能机器人通过 stream 被动回复文本和图片，不支持语音、文件、视频收发。
快速安装
# 安装全部 IM 依赖
pip install openakita[all]
# 或按需安装单通道
pip install openakita[feishu]
pip install openakita[dingtalk]
pip install openakita[wework]
pip install openakita[qq]
pip install openakita[wechat]
pip install openakita[whisper]
# 组合安装示例
pip install openakita[feishu,dingtalk,qq,wechat,whisper]三种配置方式
方式二：CLI 向导
执行 openakita setup，在 Step 4 选择并配置 IM 通道，适合命令行用户。
方式三：手动 .env
直接编辑 .env，适合高级用户精细化控制。三种方式最终都写入同一文件。
CLI 向导命令
# 启动交互式配置向导
openakita setup
一、Telegram 配置教程
Telegram 是最容易配置的 IM 通道，只需 Bot Token 即可，默认采用 Long Polling。
前置条件
- 具备 Telegram 账号（手机号注册即可）。
- 网络可访问 Telegram（大陆环境通常需要代理）。
平台端申请步骤
1
打开 BotFather
在 Telegram 搜索栏中搜索 @BotFather，点击进入对话。
2
创建新机器人
发送 /newbot，设置显示名称以 bot 后缀结尾。
3
获取 Bot Token
创建完成后 BotFather 返回 Bot Token，妥善保管。
4
可选：设置资料
可执行 /setuserpic、/setdescription、/setcommands 等。
5
可选：隐私模式
群聊需要接收全量消息时，向 BotFather 发送 /setprivacy 并选择 Disable。
OpenAkita 配置
方式 A：OpenAkita Desktop（推荐）
1
打开 Desktop，进入「IM 通道」，点击「引导创建」
2
选择接入「Telegram」，选择绑定的 Agent
3
设置机器人标识和名称（Bot ID 创建后不可更改）
4
填写 Bot Token，生成配对码，保存并重启服务
方式 B：CLI 交互式向导
# 启动向导后在 Step 4 选择 Telegram
openakita setup
# 按提示输入 Bot Token、是否启用配对码、代理地址等方式 C：手动编辑 .env 文件
# --- Telegram ---
TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_PROXY=http://127.0.0.1:7890
# TELEGRAM_PROXY=socks5://127.0.0.1:1080
# 可选：配对机制
# TELEGRAM_REQUIRE_PAIRING=true
# TELEGRAM_PAIRING_CODE=your-secret-code
# 可选：Webhook 模式
# TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook/telegram部署模式
| 模式 | 需要公网 IP | 说明 |
|---|---|---|
| Long Polling（默认） | 不需要 | 适合绝大多数场景 |
| Webhook | 需要 | 需要公网 HTTPS 回调 |
验证与测试
- 启动 OpenAkita，在 Telegram 中搜索你的机器人用户名。
- 点击 Start 或发送
/start，如启用配对需输入配对码。 - 发送一条测试消息，等待机器人回复。
常见问题
Q：无法连接 Telegram？
A：优先检查 TELEGRAM_PROXY 是否可达，代理协议是否匹配。
Q：机器人不回复？
A：检查 Token 是否正确、服务是否正常启动、日志是否报错。
Q：群聊收不到消息？
A：检查是否需要关闭隐私模式（通过 BotFather /setprivacy）。
Q：提示"配对码错误"？
A：确认 TELEGRAM_PAIRING_CODE 与输入一致。
二、飞书（Lark）配置教程
飞书通过 WebSocket 长连接接入，无需公网 IP，适合企业内部使用。
前置条件
- 一个飞书账号。
依赖安装
# OpenAkita Desktop 用户可跳过，依赖会自动安装
pip install openakita[feishu]OpenAkita 配置
方式 A：OpenAkita Desktop（推荐）
1
打开 Desktop，进入「IM 通道」，点击「引导创建」
2
选择接入「飞书」，选择绑定的 Agent
3
设置机器人标识和名称
4
飞书扫码创建机器人
5
保存并重启服务
方式 B：CLI 交互式向导
openakita setup
# 在 Step 4 选择 [2] Feishu (Lark)，按提示输入 App ID 和 App Secret方式 C：手动编辑 .env 文件
# --- 飞书 ---
FEISHU_ENABLED=true
FEISHU_APP_ID=cli_a5xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxx验证与测试
- 日志应出现
Feishu adapter: WebSocket started in background。 - 打开飞书，找到机器人并发送消息测试。
常见问题
Q：搜索不到机器人？
A：确认应用已发布且你在可用范围内。
Q：收不到消息？
A：确认是长连接模式，不是 Webhook 模式。
Q：权限不足？
A：确认所有必要权限已开通，且应用已重新发布。
Q：日志显示连接失败？
A：检查 App ID 和 App Secret 是否正确。
三、钉钉配置教程
钉钉使用 Stream 模式（WebSocket）接入，无需公网 IP，企业内部部署友好。
前置条件
- 一个企业钉钉账号。
- 钉钉管理员或具有应用开发权限的账号。
平台端申请步骤
1
登录钉钉开发者后台
访问 钉钉开放平台，使用钉钉扫码或账号密码登录。
2
创建企业内部应用
在「应用开发」中选择「企业内部应用」→「钉钉应用」→「创建应用」。
3
获取凭证
在「凭证与基础信息」中记录 AppKey（Client ID）和 AppSecret（Client Secret）。
4
开启机器人功能
在「添加应用能力」中添加机器人，并填写名称、简介等信息。
5
消息接收模式选 Stream
⚠️ 必须选择 Stream 模式（WebSocket），不要选 HTTP 模式。
6
配置权限并发布
申请「企业内机器人发送消息」「通讯录个人信息读权限」后发布应用。
OpenAkita 配置
# OpenAkita Desktop 用户可跳过，依赖会自动安装
pip install openakita[dingtalk]方式 A：OpenAkita Desktop（推荐）
1
打开 Desktop，进入「IM 通道」，点击「引导创建」
2
选择接入「钉钉」，选择绑定的 Agent
3
设置机器人标识和名称
4
填写 App Key 和 App Secret，保存并重启服务
方式 B：CLI 交互式向导
openakita setup
# 在 Step 4 选择 [4] DingTalk (钉钉)，按提示输入 App Key 和 App Secret方式 C：手动编辑 .env 文件
# --- 钉钉 ---
DINGTALK_ENABLED=true
DINGTALK_CLIENT_ID=dingxxxxxxxxxx
DINGTALK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxx验证与测试
- 日志出现
DingTalk Stream client starting...。 - 单聊可直接发消息，群聊需先将机器人拉入群并 @机器人。
常见问题
Q：收不到消息？
A：确认后台已选择 Stream 模式（不是 HTTP 模式）。
Q：Stream 连接失败？
A：检查 Client ID 和 Client Secret 是否正确。
Q：群里 @ 机器人不回复？
A：确认机器人已添加到群聊中且应用已发布可见。
Q：图片/文件异常？
A：钉钉部分富媒体会降级为链接展示。
四、企业微信配置教程
企业微信通过 WebSocket 长连接接入，无需公网 IP。
依赖安装
# OpenAkita Desktop 用户可跳过，依赖会自动安装
pip install openakita[wework]OpenAkita 配置
方式 A：OpenAkita Desktop（推荐）
1
打开 Desktop，进入「IM 通道」，点击「引导创建」
2
选择接入「企业微信」，选择绑定的 Agent
3
选择接入模式 — WebSocket 长连接
4
设置机器人标识和名称
5
扫码配置企业微信机器人
6
保存并重启服务
方式 B：CLI 交互式向导
openakita setup
# 在 Step 4 选择 [3] WeCom (企业微信)，按提示输入 Corp ID、Token、EncodingAESKey方式 C：手动编辑 .env 文件
# --- 企业微信 ---
WEWORK_ENABLED=true
WEWORK_CORP_ID=ww1234567890abcdef
WEWORK_TOKEN=your-token-here
WEWORK_ENCODING_AES_KEY=your-aes-key-here
WEWORK_CALLBACK_PORT=9880消息回复机制
企业微信智能机器人使用 stream 流式被动回复机制。
| 方向 | 支持 | 限制 |
|---|---|---|
| 发送 | 文本、图片（JPG/PNG ≤10MB） | 语音/文件/视频不支持 |
| 接收 | 文字、图文混排、图片 | 图片仅单聊，群聊不支持图片输入 |
验证与测试
- 确认日志中出现
WeWorkBot adapter started。 - 在企业微信中搜索机器人，发送消息测试。
常见问题
Q：创建机器人提示网络失败？
A：回调 URL 不通。确认服务已启动且公网地址可访问。
Q：URL 校验失败？
A：检查 Token 与 EncodingAESKey 是否与后台一致。
Q：群里有人 @ 不回复？
A：检查该成员是否在机器人可见范围内。
五、QQ 配置教程
QQ 通过 WebSocket 长连接接入，无需公网 IP。
依赖安装
# OpenAkita Desktop 用户可跳过，依赖会自动安装
pip install openakita[qq]OpenAkita 配置
方式 A：OpenAkita Desktop（推荐）
1
打开 Desktop，进入「IM 通道」，点击「引导创建」
2
选择接入「QQ」，选择绑定的 Agent
3
设置机器人标识和名称
4
微信扫码登录 QQ
5
保存并重启服务
验证与测试
- 先启动 OneBot 服务器（如 NapCat），确认 WebSocket 监听正常。
- 启动 OpenAkita，日志应显示
QQ adapter connected。 - 使用另一个 QQ 号给机器人发消息测试。
常见问题
Q：连接失败？
A：确认 OneBot 服务器已启动且 WebSocket 地址正确。
Q：频繁断线？
A：适配器支持自动重连（指数退避策略，初始 1 秒，最大 60 秒）。
Q：文件发送失败？
A：确认 OneBot 实现支持 upload_group_file / upload_private_file API。
六、微信配置教程
微信通过 iLink Bot API 接入，无需公网 IP。
依赖安装
# OpenAkita Desktop 用户可跳过，依赖会自动安装
pip install openakita[wechat]OpenAkita 配置
方式 A：OpenAkita Desktop（推荐）
1
打开 Desktop，进入「IM 通道」，点击「引导创建」
2
选择接入「微信」，选择绑定的 Agent
3
设置机器人标识和名称
4
微信扫码登录
5
保存并重启服务
验证与测试
- 在微信中打开机器人对话，发送一条消息测试。
- 也可将机器人拉入群聊，@机器人 发消息测试。
七、语音识别（Whisper）配置
所有通道语音消息统一走 Whisper 转写。
工作流程
用户发送语音 -> IM 适配器接收 -> Gateway 下载语音 -> Whisper 转写 -> 文本传给 Agent安装 ffmpeg
# Windows
winget install FFmpeg
# macOS
brew install ffmpeg
# Linux (Ubuntu/Debian)
sudo apt install ffmpeg
# Python 静态版
pip install static-ffmpeg配置
WHISPER_MODEL=base
WHISPER_LANGUAGE=zh # zh | en | auto模型选择参考
| 模型 | 大小 | 速度 | 精度 | 推荐场景 |
|---|---|---|---|---|
| tiny | 39MB | 最快 | 一般 | 资源有限设备 |
| base | 74MB | 快 | 较好 | 默认推荐 |
| small | 244MB | 中 | 好 | 对精度有要求 |
| medium | 769MB | 慢 | 很好 | 专业场景 |
| large | 1.5GB | 最慢 | 最好 | 高精度场景 |
八、视频教程与常见问题
Q1：如何同时启用多个通道？
A：在 .env 中将多个通道的 *_ENABLED 设为 true 即可，OpenAkita 会同时连接所有启用的通道。
Q2：不同通道消息会互相影响吗？
A：不会。会话按通道独立隔离。
Q3：同一用户跨平台会话是否共享？
A：默认不共享，每个平台的对话历史分开存储。
Q4：消息处理的架构是怎样的？
A：平台消息 → Adapter（解析）→ UnifiedMessage → Gateway（预处理）→ Agent → 回复原路返回。
Q5：如何查看通道状态？
A：可通过日志、OpenAkita Desktop 状态页和 GET /api/im/channels 查看。
Q6：代理设置对哪些通道生效？
A：Telegram 通常需要代理，其他国内平台一般不需要。
Q7：Desktop 和手动 .env 会冲突吗？
A：不会。两者最终写入同一个 .env 文件，可以先用 Desktop 完成基本配置，再手动微调。
Q8：有桌面安装中心吗？
A：有。OpenAkita Desktop（基于 Tauri）提供图形界面完成所有 IM 通道配置，无需手动编辑 .env 文件。
附录：完整 .env 模板
# ========== IM 通道 ==========
# --- Telegram ---
TELEGRAM_ENABLED=false
TELEGRAM_BOT_TOKEN=
TELEGRAM_PROXY=
# TELEGRAM_WEBHOOK_URL=
# TELEGRAM_REQUIRE_PAIRING=true
# TELEGRAM_PAIRING_CODE=
# --- 飞书（需要 openakita[feishu]）---
FEISHU_ENABLED=false
FEISHU_APP_ID=
FEISHU_APP_SECRET=
# --- 钉钉（需要 openakita[dingtalk]）---
DINGTALK_ENABLED=false
DINGTALK_CLIENT_ID=
DINGTALK_CLIENT_SECRET=
# --- 企业微信（需要 openakita[wework]）---
WEWORK_ENABLED=false
WEWORK_CORP_ID=
WEWORK_TOKEN=
WEWORK_ENCODING_AES_KEY=
# WEWORK_CALLBACK_PORT=9880
# --- QQ（需要 openakita[qq]）---
QQ_ENABLED=false
QQ_WS_URL=ws://127.0.0.1:8080
QQ_ACCESS_TOKEN=
# --- 微信（需要 openakita[wechat]）---
WECHAT_ENABLED=false
# --- 语音识别 ---
WHISPER_MODEL=base
WHISPER_LANGUAGE=zh