clawdboz 3.5.1

嗑唠的宝子 - 基于 ACP 协议的多 Agent 智能飞书机器人，支持 Kimi、OpenCode、Claude Code、OpenClaw、Hermes 等多种 Agent

嗑唠的宝子 (Clawdboz) - 飞书 Bot

基于 ACP 协议的多 Agent 智能飞书机器人，支持 Kimi Code CLI、OpenCode、Claude Code、OpenClaw、Hermes 等多种 Agent，飞书丝滑适配，交互体验优化得很好。

✨ 核心亮点

• 🚀 开箱即用：pip install 后三行代码即可运行
• 🎯 多 Agent 支持：原生支持 Kimi Code CLI、OpenCode、Claude Code（via claude-code-acp）、OpenClaw（via openclaw-acp）、Hermes 等多种 ACP 协议 Agent，代码编辑、文件操作、终端命令样样精通
• 💬 飞书适配：自动获取群聊上下文，流式卡片输出，体验丝滑

📺 演示

功能特性

特性	说明
🤖 AI 对话	基于 ACP 协议，支持多种 Agent（Kimi、OpenCode、Claude、OpenClaw、Hermes）
📝 流式回复	实时显示思考过程，Markdown 卡片美化输出
🔧 MCP 工具	支持 MCP 协议调用外部工具，内置飞书文件/消息发送
📦 文件处理	自动下载图片/文件，支持发送文件到飞书
💬 群聊适配	自动获取群聊历史，理解对话脉络
⏰ 定时任务	内置定时任务调度，支持自定义定时执行
🔍 运维监控	自动监控 Bot 状态，故障自动恢复
🚀 自动配置	init 自动生成 MCP 配置和内置 Skills

🚀 三行代码运行

from clawdboz import Bot

bot = Bot(app_id="your-app-id", app_secret="your-app-secret")
bot.run()

就这么简单！

快速开始

1. 环境准备

⚠️ 前置依赖：请至少安装一种支持的 ACP Agent

嗑唠的宝子基于 ACP 协议，支持多种 Agent，您可选择安装其中之一或多个：

1. Kimi Code CLI（默认）

# 通过 pip 安装
pip install kimi-cli

# 或使用 uv 安装（推荐）
uv tool install --python 3.13 kimi-cli

# 验证安装
kimi --version

# 注意：首次安装需要登录 kimi code

2. OpenCode

# 安装方式请参考 OpenCode 官方文档
opencode --version

3. Claude Code（通过 claude-code-acp）

# 先安装claude code，参考官方文档
# 然后安装acp适配工具（claude code本身不支持acp，需要外部工具）
pip install claude-code-acp

# 验证安装
claude-code-acp --version

4. OpenClaw（通过 openclaw-acp）

# 先安装openclaw，参考官方文档
# 然后安装acp适配工具（openclaw本身的acp协议不标准，需要外部工具兼容）
pip install openclaw-acp

# 验证安装
openclaw-acp --version

5. Hermes Agent

# 安装方式请参考 Hermes 官方文档
hermes --version

2. 安装嗑唠的宝子

pip install clawdboz

或从源码安装：

git clone <repository-url>
cd larkbot
pip install -e .

3. 初始化项目

安装完成后，先初始化项目：

# 创建项目目录并进入
mkdir my-bot && cd my-bot

# 初始化项目（自动生成配置文件、MCP、Skills）
clawdboz init

clawdboz init 会自动完成：

• ✅ 检测已安装的 ACP Agent（Kimi CLI、OpenCode、claude-code-acp、openclaw-acp 等）
• ✅ 创建 config.json，自动填入 Python 路径和默认 Agent

💡 提示：安装完成后，可通过 config.json 中的 agent.executable 配置切换使用的 Agent的路径。

• ✅ 创建 .agents/mcp.json，配置飞书 MCP 工具
• ✅ 复制内置 Skills（scheduler、local-memory、find-skills）
• ✅ 创建 bot_manager.sh 管理脚本
• ✅ 创建 bot0.py 启动脚本
• ✅ 创建 .bots.md Agent 指令文件

4. 启动 Bot

1. 配置飞书凭证

编辑生成的 config.json：

{
  "agent": {
    "executable": "kimi或其它agent路径"
  },
  "feishu": {
    "app_id": "cli_xxxxxxxxxxxxxxxx",
    "app_secret": "xxxxxxxxxxxxxxxxxxxxxx"
  }
}

Agent 配置说明：

Agent	executable 配置值	安装方式
Kimi Code CLI	kimi 或绝对路径	pip install kimi-cli / uv tool install kimi-cli
OpenCode	opencode 或绝对路径	官方文档
Claude Code	claude-code-acp 或绝对路径	pip install claude-code-acp
OpenClaw	openclaw-acp 或绝对路径	pip install openclaw-acp
Hermes	hermes 或绝对路径	官方文档

或使用环境变量：

export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxx"

2. 管理命令

# 启动 Bot
./bot_manager.sh start

# 停止 Bot
./bot_manager.sh stop

# 重启 Bot
./bot_manager.sh restart

# 查看状态
./bot_manager.sh status

# 查看日志（最后50行）
./bot_manager.sh log 50

# 实时跟踪日志
./bot_manager.sh follow

# 运维检查
./bot_manager.sh check

定时运维监控（推荐）

配置 crontab 定时任务，每 30 分钟自动检查 Bot 状态：

# 编辑 crontab
export EDITOR=vim && crontab -e

# 添加以下行（每 30 分钟检查一次，故障时自动通知并尝试修复）
*/30 * * * * cd /path/to/your/bot && ./bot_manager.sh check >/dev/null 2>&1

check 命令功能：

• 检查 Bot 进程状态
• 检查 WebSocket 连接
• 检查所有日志文件错误
• 检查 MCP 配置
• 检查 Skills 状态
• 检查 Python 环境
• 发现异常时自动发送飞书通知
• 自动调用 Kimi 修复（需安装 Kimi CLI）

3. 自定义启动脚本 bot0.py

如果需要在 bot0.py 中添加自定义逻辑，创建该文件：

#!/usr/bin/env python3
import os
from clawdboz import Bot

# 从环境变量或 config.json 读取配置
app_id = os.environ.get('FEISHU_APP_ID', 'your-app-id')
app_secret = os.environ.get('FEISHU_APP_SECRET', 'your-app-secret')

bot = Bot(app_id=app_id, app_secret=app_secret)
bot.run()

管理脚本会优先使用 bot0.py，如果不存在则使用内置模块启动。

项目结构

运行 clawdboz init 后生成的项目结构：

.
├── .agents/                      # ACP Agent 配置目录
│   ├── mcp.json               # MCP 配置（自动生成）
│   └── skills/                # Skills 目录（自动生成）
│       ├── find-skills/
│       ├── local-memory/
│       └── scheduler/
│
├── WORKPLACE/                  # 工作目录（临时文件存放）
│   ├── user_images/           # 用户图片下载目录
│   └── user_files/            # 用户文件下载目录
│
├── logs/                       # 日志目录
│   ├── main.log
│   ├── bot_debug.log
│   └── feishu_api.log
│
├── .bots.md                    # Agent 指令文件（自动生成）
├── bot0.py                     # 启动脚本（自动生成）
├── bot_manager.sh              # 管理脚本（自动生成）
└── config.json                 # 配置文件（自动生成）

源码结构（安装包内）：

clawdboz/                       # 主包
├── __init__.py
├── simple_bot.py               # 简化版 Bot API
├── bot.py                      # Bot 核心类
├── cli.py                      # 命令行工具
└── .agents/                      # 内置 Skills 模板
    └── skills/
        ├── auto-test/
        ├── feishu-api-sender/  # 飞书消息/文件发送
        ├── find-skills/
        ├── local-memory/
        └── scheduler/

feishu_tools/                   # 飞书工具
└── notify_feishu.py            # 运维通知脚本

飞书应用配置

1. 创建应用

1. 前往 飞书开放平台 登录开发者账号
2. 点击「开发者后台」→「创建企业自建应用」
3. 填写应用名称和描述，点击「创建」
4. 进入应用详情页，获取 App ID 和 App Secret

2. 配置权限

需要的权限:

权限类型	权限名称	用途
API 权限	im:message:send	发送消息
API 权限	im:message:send_as_bot	发送消息卡片
API 权限	im:message:update	更新消息卡片
API 权限	im:message.resource	获取图片、文件
API 权限	im:chat:readonly	获取聊天记录
API 权限	im:file:create	上传文件
API 权限	im:file:send	发送文件消息
API 权限	im:image:create	上传图片
事件订阅	im.message.receive_v1	接收消息
机器人能力	receive_message	接收消息
机器人能力	send_message	发送消息

1. 在应用详情页，点击「权限管理」→ 申请上述 API 权限 备注：可通过feishu_permissions.json批量配置权限
2. 点击「事件与回调」→ 选择长连接方式，勾选所有事件和回调选项 备注：初次配置长连接，需要先启动bot进行连接，才能在飞书后台配置成功
3. 点击「机器人」→ 开启「接收消息」和「发送消息」能力

3. 发布应用

1. 点击「版本管理与发布」→「创建版本」
2. 填写版本号（如 1.0.0）
3. 选择「可用性状态」为「所有员工」
4. 点击「保存」并「申请发布」

4. 添加机器人到聊天

• 单聊：搜索机器人名称，进入对话
• 群聊：群设置 →「群机器人」→ 添加机器人 → 在群聊中 @机器人

与 Bot 交互

• 单聊：直接发送消息给 Bot
• 群聊：在群聊中 @Bot 后发送消息
• 文件/图片：Bot 自动下载到工作目录并分析
• 发送文件：使用 MCP 工具发送本地文件到飞书

打包发布

# 清理并重新打包
rm -rf build/ dist/ *.egg-info
python3 -m build

# 生成的文件
# dist/clawdboz-2.2.0-py3-none-any.whl
# dist/clawdboz-2.2.0.tar.gz

许可证

MIT License