MochiBot 接入你的 AI 智能体：一步步完成扫码连接
本文适用于已经运行 OpenClaw 的 Ubuntu 云服务器。首次接入按顺序操作；服务器已经装好连接服务、只是手机重新绑定时，直接看第 8 步，不要重复初始化。
操作位置先分清： 下载 APK、扫码和聊天在手机完成；下面的 shell 命令都在运行 OpenClaw 的服务器终端执行，不能在 Windows PowerShell 或 MochiBot 聊天框里执行。
1. 先确认 OpenClaw 和模型已经能用
没有部署过时，先完成云服务器首次部署教程 ↗，配置自己的模型 API，并在 OpenClaw 中发送“请回复连接成功”。收到回复后再继续本文。
在云服务器控制台找到这台机器的公网 IPv4并保存。手机和电脑都应能从自己的网络访问这台服务器；购买地域不能替代连通性检查。模型 API Key 保存在服务器上，不填写进 MochiBot。
2. 手机下载安装正式版
用手机打开MochiBot 下载区 ↗，点击“下载 APK”，安装 MochiBot 1.0.0。如系统要求安装来源权限，只为实际下载 APK 的浏览器或文件管理器按需开启。
无需注册 MochiBot 账户。安装后先打开底部“设置”，暂时不用填写手动连接表单。
3. 在云控制台放行 TCP 443
腾讯云轻量应用服务器
- 电脑打开轻量应用服务器控制台 ↗。
- 选择运行 OpenClaw 的那台实例，进入实例详情。
- 打开“防火墙”页签，点击“添加规则”。
- 填写：应用类型选 HTTPS；若使用“自定义”，协议选 TCP、端口填 443；来源填 0.0.0.0/0，策略选 允许，备注填
MochiBot HTTPS。 - 点击保存。回到规则列表，确认能看到允许 TCP 443 的记录；已经有同样规则时，不重复添加。
这里的来源是允许连接的客户端地址范围，不是让你填写服务器 IP。手机移动网络地址会变化，所以本例只向公网放行需要的 443 端口，不放通全部端口。
腾讯云 CVM 或其他云厂商
CVM 在“实例详情 → 安全组 → 已绑定的安全组 → 入站规则”添加同样的 TCP 443 允许规则。其他云厂商在实例的“安全组/防火墙 → 入站规则”操作。只添加这一条所需规则，保留原 SSH 登录规则。
参考：腾讯云轻量防火墙规则 ↗、HTTPS 规则示例 ↗。
4. 打开服务器终端，检查环境
腾讯云实例页面点“登录”，进入终端。使用平时运行 OpenClaw 的同一个普通用户；不要切换成 root，也不要在 node connect.mjs 前加 sudo，以免创建到另一份工作区。
先逐条执行：
whoami
node --version
openclaw --version
openclaw gateway status
作用与结果： whoami 显示当前用户名；node --version 显示 Node 版本；连接包要求 Node 22 或以上，OpenClaw 本身若要求更高版本，按其要求准备。后两条应显示已安装的 OpenClaw 及网关状态。命令不存在、网关未启动或模型不能回复时，先回首次部署教程处理，不要继续安装连接服务。
检查系统防火墙：
sudo ufw status
若显示 Status: active，执行下面这条；若显示 inactive 或系统没有 ufw，跳过即可，不要为了本文启用或关闭防火墙：
sudo ufw allow 443/tcp
检查端口是否已经被其他服务占用：
sudo ss -lntp | grep -E ':(80|443)'
无输出表示没有匹配的监听进程。若已有网站、Nginx、Apache 或其他 HTTPS 服务，先让服务器管理员核对入口配置，不要停止或覆盖现有服务后硬装。
5. 下载、上传并解压连接服务
电脑下载连接服务包 0.1.6 ↗。它是服务器程序，不是手机 APK。
在服务器终端旁打开“文件管理器”，进入当前用户的主目录，使用上传按钮把 ZIP 上传到该目录。以用户名 ubuntu 为例，目标是 /home/ubuntu/MochiBot_Connector_0.1.6.zip；其他用户名以实际主目录为准，不把 ubuntu 原样照搬。
回到终端确认文件在主目录：
ls -lh ~/MochiBot_Connector_0.1.6.zip
能看到文件名和大小才继续；出现 No such file 就回文件管理器核对上传位置。
首次安装到一个新目录：
sudo apt-get update
sudo apt-get install -y unzip openssl
mkdir -p ~/mochibot
unzip ~/MochiBot_Connector_0.1.6.zip -d ~/mochibot
cd ~/mochibot/MochiBotConnector
apt-get 准备系统工具；unzip 解压；cd 进入程序目录。若解压提示已有同名文件，不选“全部覆盖”，先确认是不是之前已安装过的服务。
确认当前目录和二维码依赖：
pwd
ls connect.mjs package.json
node --input-type=module -e "await import('qrcode-terminal'); console.log('QR dependency OK')"
应看到路径以 MochiBotConnector 结尾、能找到两个文件，最后显示 QR dependency OK。发布包已包含二维码依赖；只有提示找不到 qrcode-terminal 时，才在当前目录执行：
npm install --omit=dev
安装成功后，再运行上一条依赖检查。
6. 运行首次接入命令，自动准备 HTTPS
先确认当前用户有安装系统服务的 sudo 权限：
sudo -v
sudo -n true && echo "sudo ready"
如系统要求密码，在终端私下输入自己的 sudo 密码。看到 sudo ready 后，在同一个终端执行下面两行。先把第一行的 YOUR_PUBLIC_IPV4 替换为第 1 步保存的真实公网 IPv4；保留两边单引号：
SERVER_IP='YOUR_PUBLIC_IPV4'
node connect.mjs setup --ip "$SERVER_IP"
这一条接入命令会做什么： 准备 MochiBot 专属助手及工作区、保存连接配置、安装或配置 Caddy HTTPS 入口、生成服务器证书及公钥指纹，并安装连接服务后台进程。已有同名助手或服务不符合预期时会报错停止，不要反复重跑试图覆盖。
完成后应显示：专属助手、工作区、https://你的公网IP 入口以及五分钟有效的配对二维码。工作区路径和助手 ID 以你自己的终端输出为准，不需要和教程截图完全相同。
HTTPS 具体怎样实现
连接服务只在服务器内部监听；Caddy 在公网 TCP 443 接收 HTTPS，再转给本机连接服务。首次接入命令自动生成服务器证书，把服务器公钥指纹放入配对二维码。手机扫描后，由你核对服务器并确认绑定，MochiBot 保存该指纹，后续连接核对公钥，数据在传输途中使用 TLS 加密。
这套 IP 入口使用应用内指纹校验，不是公开 CA 签发的浏览器信任证书。不要以浏览器是否显示小锁作为这条接入方式的成功标准，也不需要在手机上安装根证书。程序还会安装每日证书检查任务，临近过期时使用同一私钥续期；服务器重装或更换密钥后，需要重新扫码确认。
无需手工编辑 Caddyfile 或运行 openssl 生成证书。想核对自动生成的证书时，在刚才的终端执行：
openssl x509 -in "/etc/caddy/mochibot-ip/$SERVER_IP/server.crt" -noout -subject -dates
它只显示证书主题和有效期，不输出私钥。证书、私钥和连接配置文件不要放到网站下载区。
7. 检查服务已运行
在服务器终端逐条执行：
systemctl --user is-active mochibot.service
systemctl is-active caddy
node connect.mjs status
前两条应显示 active，最后一条应返回连接服务状态。服务没起来时，先看最近日志：
journalctl --user -u mochibot.service -n 30 --no-pager
sudo journalctl -u caddy -n 30 --no-pager
第一条查连接服务，第二条查 HTTPS 入口。按具体报错处理环境、配置或端口占用；寻求帮助时遮住令牌、密钥和私人内容。443 放通只代表防火墙允许连接，不代表这两个服务已经启动。
8. 手机扫码确认绑定
手机打开 设置 → 扫码连接，允许相机权限，扫描终端二维码。确认窗口出现后，核对是你自己的服务器和助手，再点“确认绑定”。出现“绑定成功”后点“开始使用”。
二维码五分钟有效。过期、扫码失败或手机重新绑定时，在已经安装连接服务的原目录执行：
node connect.mjs pair
这条命令只生成新的短期配对码，不需要重新安装或重新执行 setup。未完成绑定的旧配对码会失效；已经绑定的设备不受影响。不要把有效配对码发到公开群里。
9. 验证聊天、文件和 Skills
在手机聊天页发送“你好，请只回复连接成功”，收到助手回复后，说明手机已能通过这条连接访问自己的智能体。“＋”可以选文件，文件也可以单独发送；先用不含私人内容的小文件测试。
打开底部 Skills 查看列表，点“查看详情与用法”。仅查看列表不会安装 Skill。需要 MochiLab Skills 时，按连接 Skills 助手 ↗登录各自的 MochiLab 账户，再点“交给我的助手安装”，核对聊天框里的任务后发送；等待助手报告安装与验证结果。
免费注册可使用 MochiLab Skills 助手并下载免费 Skills；会员 Skills 按详情页权益使用。兼容的第三方 Skills 也可使用。
10. 提醒、断开和多人使用
“提醒”页可设置本机定时提醒，并按设备条件选择远程接收模式。语音提醒需设备支持，并开启相应的推送、通知和后台权限。远程提醒还需要服务器配置对应推送通道；聊天连接成功不会自动完成推送通道配置。
临时断开：设置 → 断开连接。新版保留已保存的地址和加密密钥，之后点“重新连接”即可。只有在“设置 → 高级设置 → 移除连接信息”时才清除这些信息；清除后需重新扫码。
聊天和文件交给你配置的服务器；使用中转时也会经过该中转。模型数据按你选择的服务商处理；完全使用自己的本地模型且没有云端回退时，无需第三方模型 API。
家人、同事或朋友共用服务器时，另按多个 BOT 独立运行教程 ↗配置隔离。单独创建一个文件夹不等于完成权限隔离。
连不上时按这个顺序检查
- 二维码没有反应： 在 MochiBot 内扫码，检查相机权限；用
node connect.mjs pair 换新码，确认二维码完整显示。 - 能识别二维码但绑定超时： 确认手机网络能访问这台公网 IP，再查云防火墙 TCP 443、系统防火墙和 Caddy 状态。
- 已绑定但助手不回复： 先查连接服务和 OpenClaw Gateway，再查模型 API 授权、额度及报错；这不是重新生成二维码能解决的问题。
- 聊天正常但远程语音没来： 查所选推送通道、设备登记、通知/后台权限和语音设置，按提醒配置说明逐项处理。