在 AI 时代，市面上涌现了越来越多优秀的智能体（Agent），比如 OpenClaw、QwenPaw、Hermes 等。我们渴望拥有一个完全私有、安全且不受干扰的空间来管理这些智能体，而不是将它们分散在微信、Telegram 等社交软件中。 今天，我想向大家介绍我基于开源项目 VoceChat（https://doc.voce.chat/zh-cn/） 二次开发的一款私人聊天平台 —— CocoChat。它旨在解决个人用户对轻量级、私有化 AI 助理管理的需求。

一、为什么是 CocoChat？

你可能会问，市面上不是已经有 Telegram、WhatsApp 这种可以接入机器人的应用吗？或者企业微信、钉钉也能用。

确实如此，但它们各有痛点：

  • 国际应用（Telegram等）： 在国内访问体验极差，且数据在境外。
  • 办公软件（企微/钉钉）： 过于臃肿，且主要面向办公场景，缺乏私密性。
  • 其他开源方案（Rocket.Chat等）： 部署复杂，配置繁琐，对个人用户不友好。

CocoChat 的诞生正是为了解决这些问题。它继承了 VoceChat 的极致轻量和多端共通特性，并通过 Matrix 协议 实现了与市面上主流 AI 智能体的无缝对接。

简单来说，CocoChat 就是你手机里的“钢铁侠战衣”，一个完全私有、安全、且只属于你一个人的 AI 助理中心。

image-20260425112417155

二、快速部署：Docker 一键启动

部署 CocoChat 非常简单，你只需要一台云服务器（阿里云、腾讯云、华为云均可，推荐 Debian 12 或 Ubuntu 系统）。以下以 Ubuntu 24.04 为例：

1. 安装 Docker 环境

1
2
3

sudo apt update
sudo apt install -y ca-certificates curl
sudo apt install docker.io

2. 拉取镜像

由于 Docker Hub 国内访问困难，建议使用国内镜像源：

1
2

docker pull docker.1ms.run/winbomb/cocochat-server:latest
docker tag  docker.1ms.run/winbomb/cocochat-server:latest  winbomb/cocochat-server

3. 运行容器

推荐将数据挂载到本地目录，防止容器删除后数据丢失：

1
2
3
4
5
6

# 运行容器
docker run -d --restart=always \
  -p 3000:3000 \
  --name cocochat-server \
  -v ./data:/home/cocochat-server/data \
  winbomb/cocochat-server:latest

提示： 默认端口是 3000，如果需要修改，可以调整 -p 后面的端口号。

手动编译

如果你需要手动编译，请参考 github 项目地址。

三、初始化与使用

部署完成后，访问 http://你的服务器IP:3000 即可进入初始化页面。

1、初始化

输入服务器名称、管理员邮箱和密码，即可完成安装。

image-20260425114129749

用户注册

首页点击注册。注意，CocoChat 不强制验证邮箱真实性，只要格式正确即可注册登录。

image-20260425114339401

WEB端

在浏览器中输入服务器地址和端口号，登录页面输入邮箱账号和密码，登录成功即可使用。

image-20260425114419272

移动端

安卓用户可下载 APK 安装包（iOS 版本目前暂未编译，后续会跟进）。

安卓APK下载地址：

首页输入服务器的地址和端口号，然后在登录页面输入邮箱和密码完成登录即可使用。

app

四、接入 AI 智能体

CocoChat对VoceChat做了二次开发，可以快速接入各种 AI Agent。其实现原理是通过配置智能体的 Matrix 频道，将机器人接入到 CocoChat 服务中。

这里以 QwenPaw 为例，其他智能体（OpenClaw, Hermes 等）的配置逻辑大同小异。

1、创建机器人

以管理员身份登录 CocoChat 控制台，进入 “机器人 & Webhook” 菜单，点击创建机器人。

  • 名称： 随便起，比如 QwenBot。
  • Webhook URL： 可选，用于接收推送数据，在matrix协议连接机器人的情况下没有用。

创建机器人

2、设置密码或API Key

机器人创建成功后，点击“新增API Key”创建机器人密码和Key，请妥善保管这两个信息，后续matrix接入的时候会用到。

创建API Key

3、配置Matrix频道

QwenPaw有两种方式配置 Matrix 频道，其他智能体的配置方式可参见本节最后部分。

方式一： 在 Console 中配置

前往 控制 → 频道，点击 Matrix，启用后填写：

  • Homeserver URL: 填写你的 CocoChat 服务器地址，格式为 https://你的域名或IP:端口。
  • User ID: 填写刚才创建机器人得到的 ID。
  • Access Token: 填写刚才生成的 Token。

image-20260424153106140

方式二：编辑配置文件 (agent.json) 如果你是在本地运行智能体，找到 agent.json 文件（路径通常为 ~/.qwenpaw/workspaces/default/agent.json），在 channels 中添加 matrix 配置：

1
2
3
4
5
6
7

"matrix": {
  "enabled": true,
  "bot_prefix": "[BOT]",
  "homeserver": "https://matrix.org",
  "user_id": "@mybot:matrix.org",
  "access_token": "syt_..."
}

保存后，智能体通常会自动重载配置。

其他智能体的配置方式大同小异，注意目前cocochat仅支持一对一聊天加密，不支持群组聊天加密，因此开启e2ee加密选项的情况下可能有不稳定的情况。

智能体 配置说明文档
QwenPaw https://qwenpaw.agentscope.io/docs/channels#Matrix
OpenClaw https://docs.openclaw.ai/zh-CN/channels/matrix
Nanobot https://github.com/HKUDS/nanobot
Hermes Agent https://hermesagent.org.cn/docs/user-guide/messaging/matrix
ZeroClaw https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/i18n/zh-CN/security/matrix-e2ee-guide.zh-CN.md

4、开始对话

配置成功后，你的机器人就会出现在好友列表中。直接点击对话，发送“Hello”，如果能收到回复，说明链路已经打通！

image-20260425122205408

注意事项

  • 加密限制： 目前加密通讯功能尚不稳定，还在逐步完善过程中。如果agent开启了e2ee机密，可能存在不稳定的情况。
  • 域名与反向代理： 建议申请域名并通过 Nginx 进行反向代理，这样可以使用 HTTPS 协议，不仅更安全，也能避免部分网络环境下的连接问题。

5、结语

通过 CocoChat，你可以将散落在各处的 AI 能力汇聚到一个私有的空间里。无论是处理日常任务，还是进行复杂的自动化操作，它都能成为你得力的助手。如果你在部署或使用过程中遇到任何问题，欢迎在评论区留言交流。

GitHub 地址： https://github.com/winbomb/cocochat-server.git

下一篇博客，我将详细介绍如何申请域名、配置备案以及 Nginx 反向代理，敬请期待！