多渠道 AI 助手 - 基于 iflow CLI 构建的多平台消息机器人。

将 iflow 的强大 AI 能力扩展到多个通讯平台，让 AI 助手无处不在。

✨ 特性

🔌 多渠道支持 - Telegram、Discord、Slack、飞书、钉钉、QQ、WhatsApp、Email、Mochat
🧠 AI 驱动 - 基于 iflow CLI，支持多种模型（GLM-5、Kimi K2.5、MiniMax M2.5 等）
💾 会话管理 - 自动管理多用户会话，支持对话上下文
📁 工作空间 - 每个机器人实例拥有独立的工作空间和记忆系统
🔐 权限控制 - 支持白名单、提及触发等多种策略
🔄 思考模式 - 可选启用 AI 思考过程展示
⚡ 流式输出 - 支持 Telegram、钉钉 AI Card 实时流式输出
🚀 Stdio 模式 - 直接通过 stdin/stdout 与 iflow 通信，响应更快

🎬 演示

Telegram 流式输出

钉钉 AI Card 流式输出

📋 前置要求

1. 安装 iflow CLI

iflow-bot 依赖 iflow CLI 运行，请先安装：

# 已有Node.js 22+
npm i -g @iflow-ai/iflow-cli@latest

2. 登录 iflow

iflow

运行 iflow 后选择 OLogin with iFlow 登录
CLI 会自动打开浏览器跳转到心流平台
完成注册/登录后授权 iFlow CLI
自动返回终端，开始使用

按照提示完成登录流程。

🚀 快速开始

安装

方式一：pip 安装（推荐）

pip install iflow-bot

安装完成后即可直接使用：

iflow-bot --help
iflow-bot onboard
iflow-bot gateway start

方式二：从源码安装

# 克隆仓库
git clone https://github.com/your-repo/iflow-bot.git
cd iflow-bot

# 安装依赖（使用 uv）
uv sync

初始化配置

# 创建默认配置文件（pip安装）
iflow-bot onboard

# 或源码安装
uv run iflow-bot onboard

# 或手动创建
mkdir -p ~/.iflow-bot
cp config.example.json ~/.iflow-bot/config.json

启动服务

pip 安装后：

# 前台运行（调试模式）
iflow-bot gateway run

# 后台运行
iflow-bot gateway start

# 查看状态
iflow-bot status

# 停止服务
iflow-bot gateway stop

源码安装后：

# 前台运行（调试模式）
uv run iflow-bot gateway run

# 后台运行
uv run iflow-bot gateway start

🐳 Docker 部署

# 构建镜像
docker build -t iflow-bot:latest .

# 准备宿主机配置文件
mkdir -p ./config
cp config/config.example.json ./config/config.json

然后编辑 ./config/config.json，按需启用渠道并填写 token。

# 使用 docker compose 启动
docker compose up -d

# 查看日志
docker compose logs -f iflow-bot

⚙️ 配置说明

配置文件位于 ~/.iflow-bot/config.json

完整配置示例

{
  "driver": {
    "mode": "stdio",
    "iflow_path": "iflow",
    "model": "minimax-m2.5",
    "yolo": true,
    "thinking": false,
    "max_turns": 40,
    "timeout": 600,
    "workspace": "~/.iflow-bot/workspace",
    "extra_args": []
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": []
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": []
    },
    "slack": {
      "enabled": false,
      "bot_token": "xoxb-xxx",
      "app_token": "xapp-xxx",
      "allow_from": [],
      "group_policy": "mention"
    },
    "feishu": {
      "enabled": false,
      "app_id": "cli_xxx",
      "app_secret": "xxx",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": []
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "xxx",
      "client_secret": "xxx",
      "robot_code": "xxx",
      "card_template_id": "xxx-xxx-xxx",
      "card_template_key": "content",
      "allow_from": []
    },
    "qq": {
      "enabled": false,
      "app_id": "xxx",
      "secret": "xxx",
      "allow_from": []
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "http://localhost:3001",
      "bridge_token": "",
      "allow_from": []
    },
    "email": {
      "enabled": false,
      "consent_granted": false,
      "imap_host": "imap.gmail.com",
      "imap_port": 993,
      "imap_username": "your@email.com",
      "imap_password": "app_password",
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "smtp_username": "your@email.com",
      "smtp_password": "app_password",
      "from_address": "your@email.com",
      "allow_from": [],
      "auto_reply_enabled": true
    },
    "mochat": {
      "enabled": false,
      "base_url": "https://mochat.io",
      "socket_url": "https://mochat.io",
      "socket_path": "/socket.io",
      "claw_token": "xxx",
      "agent_user_id": "",
      "sessions": ["*"],
      "panels": ["*"]
    }
  },
  "messages": {
    "new_conversation": "✨ New conversation started, previous context has been cleared."
  },
  "log_level": "INFO",
  "log_file": ""
}

Driver 配置

参数	类型	默认值	说明
`mode`	string	`"stdio"`	通信模式：`stdio`（推荐）、`acp`（WebSocket）、`cli`（子进程）
`iflow_path`	string	`"iflow"`	iflow CLI 路径【保持默认即可】
`model`	string	`"minimax-m2.5"`	默认模型（glm-5、kimi-k2.5、minimax-m2.5 等）
`yolo`	bool	`true`	自动确认模式
`thinking`	bool	`false`	显示 AI 思考过程
`max_turns`	int	`40`	单次最大对话轮次
`timeout`	int	`600`	超时时间（秒）
`workspace`	string	`~/.iflow-bot/workspace`	工作空间路径
`extra_args`	list	`[]`	额外的 iflow 参数
`acp_port`	int	`8090`	ACP 模式下的端口号
`acp_host`	string	`"localhost"`	ACP 模式下的主机地址

通信模式说明

Stdio 模式（⭐ 推荐）：

直接通过 stdin/stdout 与 iflow 通信
无需启动 WebSocket 服务，启动更快
支持实时流式输出，打字机效果
响应延迟更低，接近原生体验
Gateway 启动时自动执行 iflow --experimental-acp --stream

ACP 模式（WebSocket）：

通过 WebSocket 与 iflow 通信
需要先启动 WebSocket 服务器[自动启动]
支持实时流式输出
适合需要远程连接的场景

CLI 模式：

通过子进程调用 iflow CLI
每次对话独立启动进程
适合简单场景或调试

渠道配置

{
  "telegram": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "allow_from": ["user_id_1", "user_id_2"]
  }
}

在 @BotFather 创建机器人获取 Token
allow_from 为空表示允许所有用户

Discord

{
  "discord": {
    "enabled": true,
    "token": "YOUR_BOT_TOKEN",
    "allow_from": ["user_id_1"]
  }
}

在 Discord Developer Portal 创建应用
创建 Bot 用户并获取 Token
启用 Message Content Intent

Slack

{
  "slack": {
    "enabled": true,
    "bot_token": "xoxb-xxx",
    "app_token": "xapp-xxx",
    "allow_from": [],
    "group_policy": "mention"
  }
}

在 Slack API 创建应用
创建 Bot 并获取 Bot Token (xoxb-xxx)
启用 Socket Mode 获取 App Token (xapp-xxx)
group_policy 控制频道消息响应策略：
- mention: 只响应 @提及
- open: 响应所有消息
- allowlist: 只响应白名单频道

飞书 (Feishu/Lark)

{
  "feishu": {
    "enabled": true,
    "app_id": "cli_xxx",
    "app_secret": "xxx",
    "encrypt_key": "",
    "verification_token": "",
    "allow_from": []
  }
}

在飞书开放平台创建企业自建应用
启用机器人能力
配置事件订阅（使用 WebSocket，无需公网 IP）

钉钉 (DingTalk)

{
  "dingtalk": {
    "enabled": true,
    "client_id": "xxx",
    "client_secret": "xxx",
    "robot_code": "xxx",
    "card_template_id": "xxx-xxx-xxx",
    "card_template_key": "content",
    "allow_from": []
  }
}

在钉钉开放平台创建机器人
获取 Client ID 和 Client Secret
启用 Stream Mode（无需公网 IP）

AI Card 流式输出配置（可选，实现打字机效果）：

参数	说明
`robot_code`	机器人代码，群聊时需要配置
`card_template_id`	AI Card 模板 ID，在钉钉开发者后台创建
`card_template_key`	模板内容字段名，默认 `content`

创建 AI Card 模板：

登录钉钉开发者后台
进入「卡片平台」→「卡片模板」
创建模板，添加一个「文本」类型的字段
记录模板 ID 和字段名，配置到 card_template_id 和 card_template_key

流式输出效果：

用户发送消息后，机器人立即回复一张空白卡片
卡片内容实时更新，呈现打字机效果
无需等待完整响应，体验更流畅

QQ

{
  "qq": {
    "enabled": true,
    "app_id": "xxx",
    "secret": "xxx",
    "allow_from": []
  }
}

在 QQ 开放平台创建机器人
获取 App ID 和 Secret

{
  "whatsapp": {
    "enabled": true,
    "bridge_url": "http://localhost:3001",
    "bridge_token": "",
    "allow_from": []
  }
}

需要部署 WhatsApp Bridge（基于 baileys）

Email

{
  "email": {
    "enabled": true,
    "consent_granted": true,
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "imap_username": "your@email.com",
    "imap_password": "app_password",
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "your@email.com",
    "smtp_password": "app_password",
    "from_address": "your@email.com",
    "allow_from": ["sender@example.com"],
    "auto_reply_enabled": true
  }
}

重要: 使用 Gmail 需要创建应用专用密码

Mochat

{
  "mochat": {
    "enabled": true,
    "base_url": "https://mochat.io",
    "socket_url": "https://mochat.io",
    "socket_path": "/socket.io",
    "claw_token": "xxx",
    "agent_user_id": "",
    "sessions": ["*"],
    "panels": ["*"]
  }
}

🎮 CLI 命令

基础命令

# 查看版本
iflow-bot version
iflow-bot -v

# 查看帮助
iflow-bot --help

# 查看状态
iflow-bot status

# 初始化配置
iflow-bot onboard [--force]

# 启动 Web 控制台
iflow-bot console --host 127.0.0.1 --port 8787
# 可选访问令牌
iflow-bot console --token your_token

Gateway 服务管理

# 后台启动服务
iflow-bot gateway start

# 前台运行（调试模式）
iflow-bot gateway run

# 停止服务
iflow-bot gateway stop

# 重启服务
iflow-bot gateway restart

配置管理

# 显示配置
iflow-bot config --show

# 编辑配置
iflow-bot config -e

# 切换模型
iflow-bot model glm-5
iflow-bot model kimi-k2.5
iflow-bot model minimax-m2.5

# 思考模式
iflow-bot thinking on
iflow-bot thinking off

会话管理

# 列出所有会话
iflow-bot sessions

# 过滤渠道
iflow-bot sessions --channel telegram

# 过滤聊天ID
iflow-bot sessions --chat-id 123456

# 清除会话映射
iflow-bot sessions --clear

定时任务 (Cron)

# 列出任务
iflow-bot cron list [-a]

# 添加间隔任务
iflow-bot cron add -n "喝水提醒" -m "该喝水了！" -e 300 -d --channel telegram --to "123456"

# 添加一次性任务
iflow-bot cron add -n "会议提醒" -m "开会！" -a "2024-12-25T10:00:00" -d --channel telegram --to "123456"

# 添加 cron 表达式任务
iflow-bot cron add -n "早报" -m "发送早报" -c "0 9 * * *" -d --channel telegram --to "123456"

# 启用/禁用任务
iflow-bot cron enable <id>
iflow-bot cron disable <id>

# 立即执行任务
iflow-bot cron run <id>

# 移除任务
iflow-bot cron remove <id>

iflow 命令透传

# iflow 基础透传
iflow-bot iflow --help
iflow-bot iflow -p "hello"

# MCP 命令
iflow-bot mcp --help

# Agent 命令
iflow-bot agent --help

# Workflow 命令
iflow-bot workflow --help

# Skill 命令
iflow-bot skill --help

# Commands 命令
iflow-bot commands --help

📁 目录结构

~/.iflow-bot/
├── botpy.log                # QQ bot 日志
├── config.json              # 配置文件
├── gateway.pid              # PID 文件（后台运行）
├── gateway.log              # Gateway 日志
├── session_mappings.json    # Session 会话映射
├── workspace/               # iflow 工作空间
│   ├── AGENTS.md            # Agent 行为指南
│   ├── BOOT.md              # 启动配置
│   ├── HEARTBEAT.md         # 心跳任务
│   ├── IDENTITY.md          # 身份标识
│   ├── SOUL.md              # AI 人格定义
│   ├── TOOLS.md             # 工具配置
│   ├── USER.md              # 用户信息
│   └── memory/              # 记忆目录
│       └── MEMORY.md        # 长期记忆
└── data/                    # 数据目录
    └── cron/                # 定时任务
        └── jobs.json        # 任务数据

🔧 开发

流式输出支持

iflow-bot 支持实时流式输出，让用户看到 AI "打字"的过程。

支持流式输出的渠道：

渠道	流式方式	说明
Telegram	编辑消息	实时编辑消息内容
钉钉	AI Card	使用钉钉卡片模板流式更新
Discord	编辑消息	实时编辑消息内容（计划中）
Slack	编辑消息	实时编辑消息内容（计划中）

配置要求：

需要使用 Stdio 模式（driver.mode = "stdio"）或 ACP 模式（driver.mode = "acp"）
钉钉需要额外配置 AI Card 模板

流式输出缓冲机制：

内容累积到 10-25 个字符（随机）时推送一次更新
避免过于频繁的 API 调用
确保最终消息包含所有内容

Session 会话管理

iflow-bot 自动管理多用户会话，支持跨渠道对话上下文。

Session 映射存储：

存储位置：~/.iflow-bot/session_mappings.json
格式：{渠道}:{聊天ID} -> {sessionId}

Session 恢复机制：

Gateway 重启后自动恢复会话
Session 失效时自动创建新会话
支持通过 CLI 管理会话

# 查看所有会话
iflow-bot sessions

# 清除会话映射
iflow-bot sessions --clear

项目结构

iflow-bot/
├── iflow_bot/
│   ├── __init__.py
│   ├── __main__.py          # 入口点
│   ├── bus/                 # 消息总线
│   │   ├── events.py        # 事件定义
│   │   └── queue.py         # 消息队列
│   ├── channels/            # 渠道实现
│   │   ├── base.py          # 基类
│   │   ├── telegram.py
│   │   ├── discord.py
│   │   ├── slack.py
│   │   ├── feishu.py
│   │   ├── dingtalk.py
│   │   ├── qq.py
│   │   ├── whatsapp.py
│   │   ├── email.py
│   │   ├── mochat.py
│   │   └── manager.py       # 渠道管理器
│   ├── cli/                 # CLI 命令
│   │   └── commands.py
│   ├── config/              # 配置管理
│   │   ├── schema.py        # 配置模型
│   │   └── loader.py
│   ├── cron/                # 定时任务
│   │   ├── service.py
│   │   └── types.py
│   ├── engine/              # 核心引擎
│   │   ├── adapter.py       # iflow 适配器
│   │   ├── acp.py          # ACP 模式（WebSocket）
│   │   ├── stdio_acp.py    # Stdio 模式
│   │   └── loop.py          # 消息循环
│   ├── heartbeat/           # 心跳服务
│   │   └── service.py
│   ├── session/             # 会话管理
│   │   └── manager.py
│   ├── templates/           # 模板文件
│   │   ├── AGENTS.md
│   │   ├── SOUL.md
│   │   └── ...
│   └── utils/               # 工具函数
│       └── helpers.py
├── tests/
├── pyproject.toml
└── README.md

📝 工作空间模板

工作空间包含 AI 的"人格"和记忆：

SOUL.md - 定义 AI 的核心人格和行为准则
USER.md - 用户信息和偏好
AGENTS.md - 工作空间行为指南
TOOLS.md - 可用工具和配置
MEMORY.md - 长期记忆（重要事件、决策）
memory/YYYY-MM-DD.md - 日常记忆日志