方式一：OpenAkita Desktop
图形化配置，支持开关、凭证填写、状态检测和一键重启，适合新手与运维同学。
Tutorial / IM Channels
IM 通道配置与平台端申请
本页按最新开源文档重排，覆盖平台申请、OpenAkita 配置、验证与常见问题。
平台概览
推荐顺序：先完成 LLM 基础连通，再按平台逐个接入 IM 通道，最后统一做联调与上线检查。
| 平台 | 状态 | 接入方式 | 需要公网 IP | 安装命令 | 难度 |
|---|---|---|---|---|---|
| Telegram | 稳定 | Long Polling | 不需要 | 默认包含 | 低 |
| 飞书 | 稳定 | WebSocket 长连接 | 不需要 | `pip install openakita[feishu]` | 低 |
| 钉钉 | 稳定 | Stream 模式 | 不需要 | `pip install openakita[dingtalk]` | 低 |
| 企业微信 | 稳定 | HTTP 回调 | 需要 | `pip install openakita[wework]` | 中 |
| QQ 官方机器人 | 稳定 | QQ 开放平台 WebSocket | 不需要 | `pip install openakita[qqbot]` | 中 |
| OneBot | 稳定 | OneBot v11 WebSocket | 不需要 | `pip install openakita[onebot]` | 中 |
媒体类型支持（接收）
| 类型 | Telegram | 飞书 | 钉钉 | 企业微信 | QQ 官方机器人 | OneBot |
|---|---|---|---|---|---|---|
| 文字 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 |
| 图片 | 支持 | 支持 | 支持 | 单聊支持 | 支持 | 支持 |
| 语音 | Whisper 转写 | Whisper 转写 | Whisper 转写 | 不支持 | 支持 | Whisper 转写 |
| 文件 | 支持 | 支持 | 支持 | 不支持 | 支持 | 支持 |
| 视频 | 支持 | 支持 | 支持 | 不支持 | 支持 | 支持 |
媒体类型支持（发送）
| 类型 | Telegram | 飞书 | 钉钉 | 企业微信 | QQ 官方机器人 | OneBot |
|---|---|---|---|---|---|---|
| 文字 | 支持 | 支持 | 支持 | 支持（stream） | 支持 | 支持 |
| 图片 | 支持 | 支持 | 支持 | 支持（JPG/PNG） | 需公网 URL | 支持 |
| 语音 | 支持 | 支持 | 降级为文件 | 不支持 | 需 silk + 公网 URL | 支持 |
| 文件 | 支持 | 支持 | 降级为链接 | 降级为文本 | 暂未开放 | 支持 |
| 视频 | 支持 | 支持 | 支持 | 不支持 | 需公网 URL | 支持 |
企业微信智能机器人通过 stream 被动回复文本和图片，不支持语音、文件、视频收发。
快速安装
# 安装全部 IM 依赖
pip install openakita[all]
# 或按需安装单通道
pip install openakita[feishu]
pip install openakita[dingtalk]
pip install openakita[wework]
pip install openakita[qqbot]
pip install openakita[onebot]
pip install openakita[whisper]
# 组合安装示例
pip install openakita[feishu,dingtalk,qqbot,onebot,whisper]三种配置方式
方式二：CLI 向导
执行 `openakita setup`，在 Step 4 选择并配置 IM 通道，适合命令行用户。
方式三：手动 .env
直接编辑 `.env`，适合高级用户精细化控制。三种方式最终都写入同一文件。
CLI 向导命令
# 启动交互式配置向导
openakita setup配图位：Desktop 主界面建议放 OpenAkita Desktop 的 IM 通道入口
配图位：Desktop 状态页建议放通道在线状态（在线/离线/未启用）
一、Telegram 配置教程
Telegram 是最容易配置的 IM 通道，只需 Bot Token 即可，默认采用 Long Polling。
前置条件
- 具备 Telegram 账号。
- 网络可访问 Telegram（大陆环境通常需要代理）。
平台端申请步骤
1
打开 BotFather
搜索 `@BotFather` 并进入对话。
2
创建新机器人
发送 `/newbot`，设置 name 与以 `bot` 结尾的 username。
3
获取 Bot Token
复制创建完成后返回的 Token，妥善保存。
4
可选：设置资料
可执行 `/setuserpic`、`/setdescription`、`/setcommands`。
5
可选：隐私模式
群聊需要接收全量消息时，在 `/setprivacy` 中选择 Disable。
配图位：BotFather 完整流程建议放创建机器人和获取 Token 全流程截图
OpenAkita 配置
Desktop 配置
在 IM 通道中启用 `TELEGRAM_ENABLED`，填入 `TELEGRAM_BOT_TOKEN`，必要时配置 `TELEGRAM_PROXY`。
CLI 配置
# 启动向导后在 Step 4 选择 Telegram
openakita setup# --- 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 回调 |
验证与常见问题
- 发送 `/start` 后应收到回复。
- 启用配对时，需输入正确配对码。
- 群聊无响应时，检查隐私模式与群内权限。
Q：无法连接 Telegram？
A：优先检查 `TELEGRAM_PROXY` 是否可达，代理协议是否匹配。
Q：机器人不回复？
A：检查 Token 是否正确、服务是否正常启动、日志是否报错。
Q：群聊收不到消息？
A：根据需求在 BotFather 调整隐私模式设置。
二、飞书（Lark）配置教程
飞书使用长连接接收事件，不要求公网回调，适合企业内部部署。
平台端申请步骤
1
创建企业自建应用
在飞书开发者后台创建应用并填写基础信息。
2
获取 App ID / Secret
在「凭证与基础信息」中复制凭证。
3
添加机器人能力
在应用能力中添加机器人。
4
开通权限
开通 `im:message`、`im:message.create_v1`、`im:resource`、`im:file`。
5
配置事件订阅
选择「使用长连接接收事件」，添加 `im.message.receive_v1`。
6
创建版本并发布
设置可用范围并完成发布审批。
配图位：飞书凭证页建议放 App ID / App Secret 位置
配图位：事件订阅页建议放长连接模式与事件添加截图
OpenAkita 配置
# 安装依赖
pip install openakita[feishu]
# 向导配置
openakita setup
# --- .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：权限变更后需要重新发布应用。
三、钉钉配置教程
钉钉采用 Stream 模式（WebSocket）接入，通常不需要公网 IP。
平台端申请步骤
1
创建企业内部应用
在钉钉开放平台创建应用并填写基础信息。
2
获取凭证
在应用凭证中记录 AppKey（Client ID）和 AppSecret（Client Secret）。
3
开启机器人功能
在应用功能中开启机器人并配置名称、简介。
4
消息接收模式选 Stream
必须选择 Stream，不建议 HTTP 模式。
5
配置权限并发布
申请机器人发送消息、读取用户信息等权限后发布应用。
配图位：钉钉 Stream 模式页建议放消息接收模式选择截图
配图位：钉钉权限页建议放权限申请与发布截图
OpenAkita 配置
# 安装依赖
pip install openakita[dingtalk]
# 向导配置
openakita setup
# --- .env ---
DINGTALK_ENABLED=true
DINGTALK_CLIENT_ID=dingxxxxxxxxxx
DINGTALK_CLIENT_SECRET=xxxxxxxxxxxxxxxxxx验证与常见问题
- 日志出现 `DingTalk Stream client starting...`。
- 单聊可直接发消息，群聊需先将机器人拉入群并 @机器人。
Q：收不到消息？
A：检查后台是否选择 Stream 模式。
Q：群里 @ 机器人不回复？
A：确认机器人已在群内且应用已发布可见。
Q：图片/文件异常？
A：钉钉部分富媒体会降级为链接展示。
四、企业微信配置教程
企业微信采用 HTTP 回调模式，需要公网可访问 URL。最关键的是配置顺序。
关键顺序：先配置 OpenAkita 并启动回调端口，再在企业微信后台创建机器人并校验 URL。
网络准备
方案一：公网服务器
回调地址示例：`http://公网IP:9880/callback`。
方案二：端口转发
将路由器外网端口转发到内网机器 `9880` 端口。
方案三：ngrok
# 启动内网穿透
ngrok http 9880
# 回调 URL 示例
# https://abc123.ngrok-free.app/callback方案四：cpolar / frp
# cpolar
cpolar http 9880
# frp 客户端示例
[wework]
type = http
local_port = 9880
custom_domains = your-domain.com平台端申请步骤
1
获取企业 ID
企业微信管理后台「我的企业 -> 企业信息」中获取 Corp ID。
2
先启动 OpenAkita
先配置并启动服务，确保回调端口已监听。
3
创建智能机器人
在「应用管理 -> 智能机器人」创建机器人。
4
配置回调 URL
填写 URL、Token、EncodingAESKey 并完成校验。
5
设置可见范围
必须把目标部门/成员加入可见范围。
# 推荐：先写基础参数并启动服务
WEWORK_ENABLED=true
WEWORK_CORP_ID=ww1234567890abcdef
WEWORK_CALLBACK_PORT=9880
python -m openakita
# 或
openakita start# --- 企业微信完整 .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配置流程总结
1. 获取企业 ID
2. 写入 WEWORK_CORP_ID / WEWORK_ENABLED
3. 准备公网访问（公网IP/ngrok/frp/cpolar）
4. 启动 OpenAkita，确认回调端口监听
5. 创建智能机器人
6. 填回调 URL，获取 Token / EncodingAESKey
7. 更新 .env 后重启服务
8. 设置可见范围
9. 在企业微信中测试对话能力限制
| 方向 | 支持 | 限制 |
|---|---|---|
| 发送 | 文本、图片 | 语音/文件/视频不支持 |
| 接收 | 文字、图文混排、图片 | 图片仅单聊，群聊不支持图片输入 |
Q：创建机器人提示网络失败？
A：回调 URL 不通。确认服务已启动且公网地址可访问。
Q：URL 校验失败？
A：检查 Token 与 EncodingAESKey 是否与后台一致。
Q：群里有人 @ 不回复？
A：检查该成员是否在机器人可见范围内。
五、QQ 官方机器人配置教程
QQ 官方机器人通过 QQ 开放平台接入，使用官方 botpy 体系，支持频道、群聊与单聊消息。
平台端申请步骤
1
创建机器人应用
访问 https://q.qq.com，创建机器人并填写基本信息。
2
获取 AppID / AppSecret
在开发设置页复制凭证，后续用于 OpenAkita 鉴权。
3
配置事件订阅
在功能配置中开启消息接收相关事件，建议先在沙箱环境联调。
配图位：QQ 开放平台控制台建议放 AppID / AppSecret 获取页面
配图位：事件订阅页建议放消息订阅开关和沙箱配置截图
OpenAkita 配置
# 安装 QQ 官方机器人依赖
pip install openakita[qqbot]
# 交互式向导
openakita setup
# --- .env ---
QQBOT_ENABLED=true
QQBOT_APP_ID=你的AppID
QQBOT_APP_SECRET=你的AppSecret
QQBOT_SANDBOX=false # 调试阶段可改为 true验证与常见问题
- 日志出现
QQ Official Bot ready代表接入成功。 - 群聊/单聊富媒体通常需要先上传公网 URL，再下发消息。
- 语音需 silk 格式，文件发送能力当前受官方接口限制。
六、OneBot（通用协议）配置教程
OneBot 是通用聊天机器人协议（v11），可对接 NapCat、Lagrange 等实现端，不限于 QQ 官方体系。
部署 OneBot 服务
方案一：NapCat（推荐）
安装后登录账号，启用正向 WebSocket，默认地址可设为 ws://127.0.0.1:8080。
方案二：Lagrange.OneBot
按项目文档部署并开启正向 WebSocket 服务，再与 OpenAkita 对接。
配图位：NapCat 下载页建议放项目主页或版本下载入口
配图位：OneBot 配置页建议放 WS 地址和 Token 配置截图
OpenAkita 配置
# 安装 OneBot 依赖
pip install openakita[onebot]
# 启动向导并填写 OneBot URL
openakita setup
# --- .env ---
ONEBOT_ENABLED=true
ONEBOT_WS_URL=ws://127.0.0.1:8080
ONEBOT_ACCESS_TOKEN= # 可选，留空表示不校验验证与常见问题
- 先启动 OneBot 服务，再启动 OpenAkita。
- 日志出现
OneBot adapter connected表示连接成功。 - 连接失败优先检查 URL、端口防火墙和 Access Token 一致性。
七、语音识别（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：把多个 `*_ENABLED=true` 写入 `.env` 即可并行接入。
Q2：不同通道消息会互相影响吗？
A：不会。会话按通道独立隔离。
Q3：同一用户跨平台会话是否共享？
A：默认不共享，Telegram 与飞书会话分别存储。
Q4：如何查看通道状态？
A：可通过日志、OpenAkita Desktop 状态页和 `GET /api/im/channels` 查看。
Q5：代理设置对哪些通道生效？
A：Telegram 通常需要代理，其他国内平台一般不需要。
Q6：Desktop 和手动 .env 会冲突吗？
A：不会。两者最终写入同一个 `.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[qqbot]）---
QQBOT_ENABLED=false
QQBOT_APP_ID=
QQBOT_APP_SECRET=
QQBOT_SANDBOX=false
# --- OneBot（需要 openakita[onebot] + NapCat/Lagrange）---
ONEBOT_ENABLED=false
ONEBOT_WS_URL=ws://127.0.0.1:8080
ONEBOT_ACCESS_TOKEN=
# --- 语音识别 ---
WHISPER_MODEL=base
WHISPER_LANGUAGE=zh