ChatAgentCore

聊天机器人核心项目 - AI 驱动的对话系统基础设施

项目简介

ChatAgentCore 是一个中间服务程序，作为 Qt AI 应用与国内主流聊天软件之间的桥接中间件，支持多平台并发交互，配置驱动，提供统一的通用接口规范。

核心功能：

✅ 飞书：支持 WebSocket 长连接方式收发消息
✅ 微信：支持 HTTP JSON API 长轮询方式接入，完整对话能力
🔧 钉钉：适配器待完善
🔧 企业微信：适配器待开发
提供模块化的消息处理和路由组件
实现 HTTP API 接口
支持动态配置管理
可在个人电脑上轻量部署

快速体验（5 分钟上手）

0. Python 环境准备

项目要求 Python >= 3.10。如果你的系统 Python 版本低于 3.10，需要先升级。

检查当前版本

python3 --version

使用 pyenv 安装 Python 3.10+（推荐）

安装 pyenv：

# 使用 curl 安装
curl https://pyenv.run | bash

# 或使用 wget 安装
wget -qO- https://pyenv.run | bash

配置环境变量：

将以下内容添加到 ~/.bashrc 或 ~/.zshrc：

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

重新加载配置：

source ~/.bashrc   # bash
# 或
source ~/.zshrc    # zsh

安装 Python 3.10+：

# 列出可安装的 Python 版本
pyenv install --list | grep "3\.[1-9][0-9]"

# 安装 Python 3.10（选择最新稳定版）
pyenv install 3.10.15

# 设置为项目局部版本（推荐）
cd /path/to/chatagentcore
pyenv local 3.10.15

# 验证版本
python --version

创建虚拟环境：

# 使用 pyenv 指定的 Python 版本创建虚拟环境
python -m venv venv
source venv/bin/activate

# 或直接使用 pyenv-virtualenv（可选）
pyenv virtualenv 3.10.15 chatagentcore
pyenv local chatagentcore

其他安装方式

从源码编译（如果无法使用 pyenv）：

# 下载 Python 3.10 源码
wget https://www.python.org/ftp/python/3.10.15/Python-3.10.15.tgz
tar -xzf Python-3.10.15.tgz
cd Python-3.10.15

# 配置编译（安装到用户目录，无需 root）
./configure --prefix=$HOME/.local

# 编译安装
make -j4
make install

# 更新 PATH
export PATH="$HOME/.local/bin:$PATH"

提示：编译需要系统安装 build-essential、zlib1g-dev、libssl-dev 等依赖包。

1. 环境检查

python3 scripts/verify_setup.py

预期输出：

[OK] 环境验证通过！可以开始使用 ChatAgentCore

注意：项目要求 Python >= 3.10。如果版本检查失败，请参考上方 0. Python 环境准备 章节升级 Python 版本。

2. 安装依赖

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

3. 配置复制

# 复制配置文件
cp config/config.yaml.example config/config.yaml

# 编辑配置文件
nano config/config.yaml

必填配置：

auth.token: 设置你的 API Token
platforms.feishu.app_secret: 替换为实际的飞书应用密钥
如需使用微信，设置 platforms.weixin.enabled: true

4. 启动服务

# 方式 1：直接启动
python3 main.py

# 方式 2：开发模式（自动重载）
python3 main.py --reload

# 方式 3：指定端口
python3 main.py --port 8080

启动成功输出：

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

5. 发送测试消息

# 飞书测试（需要先配置 App Secret）
python3 cli/test_feishu_ws.py

# 微信测试（需要先扫码登录）
python3 cli/test_weixin.py login

服务管理

启动服务

方式 1：直接运行

python3 main.py

方式 2：指定参数

python3 main.py --host 0.0.0.0 --port 8000

方式 3：开发模式

python3 main.py --reload  # 代码变动自动重启

方式 4：调试模式

python3 main.py --debug

停止服务

按 Ctrl + C 停止服务

重启服务

# 停止后重新启动
python3 main.py

日志查看

# 查看最新日志
tail -f logs/chatagentcore.log

# 查看错误日志
grep ERROR logs/chatagentcore.log

健康检查

# 检查服务状态
curl http://localhost:8000/health

# 预期输出
# {"status":"healthy","plugins_loaded":1}

平台配置

飞书配置

创建飞书应用

访问飞书开放平台
创建 企业自建应用
在 凭证与基础信息 页面获取 App ID 和 App Secret

必需权限

权限	范围	说明
`im:message`	消息	发送和接收消息
`im:message.p2p_msg:readonly`	私聊	读取发给机器人的私聊消息
`im:message.group_at_msg:readonly`	群聊	接收群内 @机器人的消息
`im:message:send_as_bot`	发送	以机器人身份发送消息
`im:resource`	媒体	上传和下载图片/文件

事件订阅 ⚠️

这是最容易遗漏的配置！ 如果机器人能发消息但收不到消息，请检查此项。

在飞书开放平台的应用后台，进入 事件与回调 页面：

事件订阅方式：选择 使用长连接接收事件（推荐，无需公网 IP）

添加事件订阅，勾选以下事件：

事件	说明
`im.message.receive_v1`	接收消息（必需）
`im.message.message_read_v1`	消息已读回执（可选）
`im.chat.member.bot.added_v1`	机器人进群（可选）
`im.chat.member.bot.deleted_v1`	机器人被移出群（可选）

确保事件订阅的权限已申请并通过审核

配置文件示例

platforms:
  feishu:
    enabled: true                    # 是否启用
    type: "app"                       # 应用类型：app (企业自建应用) | group (群机器人)
    app_id: "cli_a909cd66f9f8dbde"    # 飞书应用 ID
    app_secret: "your_app_secret"     # 飞书应用密钥
    connection_mode: "websocket"      # 连接模式：websocket (推荐，无需公网IP) | webhook
    domain: "feishu"                  # 域名：feishu (国内) | lark (海外)

微信配置

微信适配器支持通过扫码方式登录，无需申请应用。

扫码登录

# 使用测试工具扫码登录
python3 cli/test_weixin.py login

登录成功后，Token 会自动保存到 ~/.openclaw-weixin/accounts/{account_id}.json

配置示例

platforms:
  weixin:
    enabled: true                    # 是否启用
    account_id: "default"            # 账号标识
    base_url: "https://ilinkai.weixin.qq.com"  # API 基础 URL
    cdn_base_url: "https://novac2c.cdn.weixin.qq.com/c2c"  # CDN 基础 URL
    state_dir: "~/.openclaw-weixin"   # 状态目录（Token 自动保存位置）
    token: ""                        # Bot Token（可选，扫码登录后自动保存）

详细文档请参考：微信适配器文档

钉钉配置（待完善）

platforms:
  dingtalk:
    enabled: false
    type: "app"
    app_key: "your_app_key"         # 从钉钉开放平台获取
    app_secret: "your_app_secret"   # 从钉钉开放平台获取
    connection_mode: "websocket"     # 连接模式：websocket | webhook

QQ 机器人配置

platforms:
  qq:
    enabled: false
    type: "app"
    app_id: "your_app_id"           # 从 QQ 机器人后台获取 (AppID)
    token: "your_token"             # 从 QQ 机器人后台获取 (Token/AppSecret)

测试指南

独立测试（CLI 工具）

飞书测试

启动交互式飞书测试工具：

python3 cli/test_feishu_ws.py

使用说明：

在飞书中向机器人发送消息建立会话
命令行输入文本即可回复
支持命令：/status、/set 目标ID、/clear、/help、/quit

微信测试

1. 扫码登录

python3 cli/test_weixin.py login

2. 接收消息

# 默认 60 秒
python3 cli/test_weixin.py receive

# 指定时长 120 秒
python3 cli/test_weixin.py receive --duration 120

3. 发送消息

python3 cli/test_weixin.py send --to "xxx@im.wechat" --text "你好，世界！"

集成测试（HTTP API）

配置 Token

在 config/config.yaml 中设置：

auth:
  token: "your_api_token_here"

发送消息示例

curl -X POST "http://localhost:8000/api/v1/message/send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{
    "platform": "feishu",
    "to": "ou_xxxxxxxxxxxxx",
    "message_type": "text",
    "content": "Hello World",
    "conversation_type": "user"
  }'

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "message_id": "msg_id_xxxxx",
    "status": "sent"
  },
  "timestamp": 1711234567
}

查询消息状态

curl -X POST "http://localhost:8000/api/v1/message/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{
    "platform": "feishu",
    "message_id": "msg_id_xxxxx"
  }'

获取会话列表

curl -X POST "http://localhost:8000/api/v1/conversation/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_token_here" \
  -d '{
    "platform": "feishu"
  }'

API 参考

认证方式

Bearer Token 认证

所有 API 请求需要在 Header 中携带 Token：

Authorization: Bearer your_api_token_here

Token 在 config/config.yaml 的 auth.token 中配置。

接口清单

接口	方法	说明
`/api/v1/message/send`	POST	发送消息到聊天平台
`/api/v1/message/status`	POST	查询消息状态
`/api/v1/conversation/list`	POST	获取会话列表
`/api/config`	GET	获取配置
`/config`	GET	获取配置（旧接口）
`/health`	GET	健康检查
`/docs`	GET	Swagger API 文档
`/redoc`	GET	ReDoc API 文档
`/admin`	GET	管理后台界面

发送消息

接口：POST /api/v1/message/send

请求参数：

字段	类型	必填	说明
platform	string	是	平台名称：feishu / weixin / dingtalk / qq
to	string	是	接收者 ID
message_type	string	是	消息类型：text / image / card
content	string/object	是	消息内容
conversation_type	string	否	会话类型：user / group，默认 user

请求示例：

{
  "platform": "feishu",
  "to": "ou_xxxxxxxxxxxxx",
  "message_type": "text",
  "content": "你好，这是测试消息",
  "conversation_type": "user"
}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "message_id": "msg_id_xxxxx",
    "status": "sent"
  },
  "timestamp": 1711234567
}

查询消息状态

接口：POST /api/v1/message/status

请求参数：

字段	类型	必填	说明
platform	string	是	平台名称
message_id	string	是	消息 ID

请求示例：

{
  "platform": "feishu",
  "message_id": "msg_id_xxxxx"
}

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "platform": "feishu",
    "message_id": "msg_id_xxxxx",
    "status": "sent",
    "sent_at": 1711234567
  },
  "timestamp": 1711234567
}

获取会话列表

接口：POST /api/v1/conversation/list

请求参数：

字段	类型	必填	说明
platform	string	是	平台名称
cursor	string	否	分页游标
limit	number	否	每页数量，默认 20

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "conversations": [
      {
        "conversation_id": "oc_xxxxxxx",
        "conversation_type": "user",
        "unread_count": 2
      }
    ],
    "has_more": false,
    "cursor": null
  },
  "timestamp": 1711234567
}

故障排查

Python 版本不满足要求

问题：环境验证显示 Python 3.x.x (need >= 3.10)

解决方案：

参考 快速体验 > 0. Python 环境准备 章节，使用 pyenv 安装 Python 3.10+。

pyenv 常见问题

pyenv 命令找不到：

# 确认环境变量已配置
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# 重新加载 shell 配置
source ~/.bashrc

编译 Python 时报错（缺少依赖）：

# Ubuntu/Debian
sudo apt install build-essential zlib1g-dev libssl-dev libbz2-dev libreadline-dev libsqlite3-dev

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install zlib-devel openssl-devel bzip2-devel readline-devel sqlite-devel

切换版本后显示旧版本：

# 检查是否在正确的目录
pyenv local 3.10.15

# 验证当前版本
python --version

# 如果仍显示旧版本
hash -r

服务启动失败

问题：启动时提示模块找不到

解决方案：

# 检查依赖安装
pip install -r requirements.txt

# 检查 Python 版本
python3 --version  # 需要 >= 3.10

Token 无效

问题：返回 403 错误 "Invalid token"

解决方案：

检查 config/config.yaml 中的 auth.token
确保请求 Header 中携带正确的 Token
Token 格式：Authorization: Bearer your_token

机器人收不到消息

飞书：

检查是否配置了 事件订阅
确认事件订阅方式选择了 长连接
验证 im.message.receive_v1 事件已添加
检查相关权限是否已审核通过

微信：

确认已扫码登录成功
检查 state_dir 目录下是否有 Token 文件
确认长轮询状态正常

在飞书里找不到机器人

确保应用已发布（至少发布到测试版本）
在飞书搜索框中搜索机器人名称
检查应用可用范围是否包含你的账号

日志位置

默认日志文件：`logs/chatagentcore.log

# 实时查看日志
tail -f logs/chatagentcore.log

# 查看错误
grep ERROR logs/chatagentcore.log

# 查看特定平台日志
grep "飞书" logs/chatagentcore.log

WebSocket 连接断开

现象：连接频繁断开或无法建立

排查：

检查网络连接
确认应用凭证（App Secret）正确
查看服务日志中的错误信息

技术栈

组件	选型
编程语言	Python 3.10+
Web 框架	FastAPI
飞书 SDK	lark_oapi (WebSocket 长连接)
HTTP 客户端	httpx
配置管理	Pydantic + YAML
日志	loguru

目录结构

chatagentcore/
├── core/                  # 核心服务层
├── adapters/              # 平台适配层
│   ├── base.py            # 适配器基类
│   ├── feishu/            # ✅ 飞书适配器
│   ├── weixin/            # ✅ 微信适配器
│   ├── dingtalk/          # 🔧 钉钉适配器（待完善）
│   └── qq/                # 🔧 QQ 适配器
├── api/                   # 接口层
├── cli/                   # 命令行工具
│   ├── test_feishu_ws.py  # 飞书测试工具
│   ├── test_qq_ws.py      # QQ 测试工具
│   └── test_weixin.py     # 微信测试工具
├── config/                # 配置文件
├── docs/                  # 技术文档
│   └── adapters/          # 适配器详细文档
│       └── weixin.md      # 微信适配器文档
├── scripts/               # 辅助脚本
│   ├── verify_setup.py    # 环境验证
│   └── test_all.sh        # 自动化测试
├── static/                # 管理后台静态文件
└── tests/                 # 测试套件

变更记录

日期	变更内容
2026-03-23	✅ 实现微信适配器 - 支持扫码登录、消息收发、媒体上传、AES加密、完整对话能力
2026-02-05	✅ 实现飞书 WebSocket 长连接及双向对话

许可证

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.claude		.claude
chatagentcore		chatagentcore
cli		cli
config		config
deploy		deploy
docs		docs
scripts		scripts
static		static
tasks		tasks
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
GEMINI.md		GEMINI.md
LICENSE		LICENSE
README.md		README.md
README_USER.md		README_USER.md
build.sh		build.sh
main.py		main.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

ChatAgentCore

项目简介

快速体验（5 分钟上手）

0. Python 环境准备

检查当前版本

使用 pyenv 安装 Python 3.10+（推荐）

其他安装方式

1. 环境检查

2. 安装依赖

3. 配置复制

4. 启动服务

5. 发送测试消息

服务管理

启动服务

停止服务

重启服务

日志查看

健康检查

平台配置

飞书配置

创建飞书应用

必需权限

事件订阅 ⚠️

配置文件示例

微信配置

扫码登录

配置示例

钉钉配置（待完善）

QQ 机器人配置

测试指南

独立测试（CLI 工具）

飞书测试

微信测试

集成测试（HTTP API）

配置 Token

发送消息示例

查询消息状态

获取会话列表

API 参考

认证方式

接口清单

发送消息

查询消息状态

获取会话列表

故障排查

Python 版本不满足要求

pyenv 常见问题

服务启动失败

Token 无效

机器人收不到消息

在飞书里找不到机器人

日志位置

WebSocket 连接断开

技术栈

目录结构

变更记录

许可证

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages