文档

快速开始

按你真正会执行的顺序来：先跑通后端，再让手机和电脑握上手，最后开出第一条实时会话。

环境检查

  • —Node.js 18 或更高版本
  • —一台可以长期运行后端的设备（本机、NAS 或 VPS 均可）
  • —一台真实手机（模拟器无法接收推送）
  • —手机与电脑都能访问后端地址

1. 启动后端

在你自己的服务器或本机启动 Joint 后端。

git clone <repo> && cd joint/server
npm install && npm run start

预期结果：终端打印监听端口，浏览器访问 /health 返回 ok。

常见错误：端口被占用 → 修改 PORT；启动即退出 → 检查数据库路径权限。

2. 手机填写后端 URL

打开手机 App，在首屏填入后端地址（含协议与端口）。

http://192.168.1.10:8080

预期结果：App 显示「已连接」。

常见错误：连接失败 → 确认手机与后端在同一网络，或后端已通过公网 HTTPS 暴露。

3. 邮箱验证码登录

输入邮箱，接收 6 位验证码完成登录。

预期结果：进入设备列表页面。

常见错误：收不到邮件 → 检查后端邮件服务配置，或查看后端日志中的验证码（仅开发模式）。

4. 生成配对码

在手机端点击「添加设备」，生成 6 位配对码（有效期有限）。

预期结果：屏幕显示配对码与倒计时。

常见错误：过期 → 重新生成；连续输错 5 次会作废。

5. 桌面连接器输入配对码

在电脑上运行连接器并输入配对码完成绑定。

joint-notify pair

预期结果：手机设备列表出现这台电脑。

常见错误：提示无效 → 确认电脑与手机指向同一个后端地址。

6. 开启工具 Hook

为你在用的工具写入通知 Hook。

joint-notify install --tool codex-cli

预期结果：对应配置文件出现 Joint 的 notify 配置。

常见错误：Codex CLI 已有 notify 配置时可能被覆盖，安装前请先备份。

7. 启动第一条实时会话

用 run 包裹你的命令，手机即可实时查看并回复。

joint-notify run --tool codex-cli -- codex

预期结果：手机会话页出现与电脑一致的终端画面。

常见错误：画面不刷新 → 检查 WebSocket 是否被反向代理拦截（需要 Upgrade 头）。

验证安装

  • —手机设备列表能看到这台电脑
  • —任务完成时手机收到通知
  • —会话输出能实时刷新
  • —手机上输入的内容出现在电脑终端里
任何一项没通过，先看后端日志，再对照 自托管部署 页中的反向代理与环境变量章节。