移动端同步
在桌面与 iPhone 或任意兼容 SyncClipboard 客户端之间同步剪贴 —— 默认走局域网，也可经自建 server 节点或 Tailscale 跨网络。
本页介绍「常规同步」。连接手机弹窗还提供「设备直连（实验性）」，通过邀请码加入空间。
常规同步是一种 HTTP 伴侣模式（0.7 引入）：桌面守护进程暴露一个 兼容 SyncClipboard 的小型 HTTP 服务，已配对的手机用 HTTP Basic Auth 与之读写剪贴。
它能力上比桌面 ↔ 桌面同步窄一截：
- 不走 P2P。 手机就是个普通 HTTP 客户端 —— 不打洞、不走中继。 同一 LAN 下开箱即用；需要跨网络时，自建 无头 server 节点（公网 HTTPS 端点） 或走 Tailscale / VPN overlay（见 下文）。
- 监听器本身是明文 HTTP + Basic Auth —— TLS 由反向代理或 overlay 隧道 提供，监听器自己不做。裸 LAN 下只在可信网络打开。
- 手机 不是 空间的对端 —— 不分配 node ID，看不到加密历史数据库。
两台手机不会互相同步，它们都跟桌面通信。
v1 的线上格式是 LAN 上的明文 HTTP。不要 在咖啡馆 Wi-Fi、会议 Wi-Fi、或任何同一 SSID 上有不可信用户的网络下开启监听器。
一键启用
最快的方式是走向导 —— 一条命令打开功能、配置 LAN 监听器、注册手机、 打印 QR 码。
打开 设备 页
点击邀请按钮旁的手机图标，打开「连接手机」，选择 常规同步 后继续。 首次使用时先确认开启，再填写设备名称并添加。需要邀请码配对时，返回选择 设备直连（实验性）。配置和结果均在当前任务面板内显示，不叠加弹窗。
按需调整配置
一般无需手动配置。遇到连接错误时，可通过当前任务面板中的 配置 按钮调整网络；已注册手机分组也保留设置入口。
- 同步与局域网监听：分别控制常规同步和局域网监听，启用时按面板提示确认网络风险。
- 监听 IP：选择自动或具体网卡。Tailscale CGNAT（
100.64.0.0/10）地址也可作为候选；这与仅影响桌面设备配对的「允许覆盖网络地址」设置无关。实际监听地址仍为0.0.0.0，此选项决定向手机宣告的地址。 - 端口：默认
42720，冲突时再改；无效端口会在面板内提示。
保存后即时应用，无需重启守护进程。监听失败时，面板显示原因并提供配置与重试入口。
添加设备
填写设备名称（例如「My iPhone 15」）。默认自动生成用户名与密码，也可在高级选项中指定。 创建成功后，当前面板显示一次性连接信息：
- 连接二维码：将可达候选地址和凭据编码进
uniclipboard://connectURI。使用 UniClipboard iOS App、Android 客户端或支持该连接格式的客户端扫码。 - 手动输入：展开后可分别复制服务器地址、用户名与密码。密码默认遮挡，可按需显示。
- 还没装客户端？：展开后选择 iOS、Android 或可用的快捷指令安装方式，扫描对应安装二维码。
点击「完成」或关闭面板会保留已注册设备，并清除当前界面的一次性凭据。需要撤销时，从设备列表选择手机并撤销，参见管理已配对设备。明文密码不会在之后重新显示；遗失后需重设密码。
# 一键：启用功能 + LAN 监听器，注册一台设备，打印安装 QR + 一次性密码。
uniclip stop # 必须：写命令拒绝同 profile daemon 在跑
uniclip mobile setup # 推荐：交互式
# 或非交互（如 CI / 脚本）
uniclip mobile setup \
--label "My iPhone 15" \
--accept-network-risk \
--non-interactive
# → 输出 baseUrl、username、password (one-time)、installUrl，
# 以及一个多地址 QR (ASCII)，手机会逐个地址探活连通
# macOS/Linux 用户服务
uniclip service start
# Windows：兼容的后台启动方式（不支持服务命令）
uniclip start非交互模式下 --label、--accept-network-risk 必填；--ip / --port
是可选的高级覆盖项 —— 不给就让 QR 自动携带所有检测到的网卡，通常无需选择。
--username / --password-stdin 可选，缺省走自动生成。
明文密码 只显示一次。丢了就在 移动端同步 设备列表里点对应
设备卡片，在弹出的 dialog 里点 Edit device 设置或重新生成密码，
或 uniclip mobile revoke <id> + add 重新
签发 —— 没法把原始密码再拿回来。
配对一台 iPhone
iOS 端目前有两条路径，推荐使用 UniClipboard iOS App；快捷指令保留 作为备选。
iOS（UniClipboard App，TestFlight beta 公测）
UniClipboard iOS App 目前通过 TestFlight 进行 beta 公测，邀请链接：
https://testflight.apple.com/join/nyNQ8dQe
先在 App Store 安装 TestFlight
打开 iPhone 上的 App Store，搜索 TestFlight 并安装。TestFlight 是 Apple 官方的 beta 测试分发工具，是安装 UniClipboard iOS App beta 的 前置依赖。
打开邀请链接
在 iPhone 上点开上面的 TestFlight 邀请链接：
https://testflight.apple.com/join/nyNQ8dQe链接会自动跳转到 TestFlight App，点击 「接受 / Accept」，再点 「安装 / Install」，UniClipboard 就会装到主屏幕上。
在桌面 添加设备 拿到凭据
回到桌面端，按上文的流程在 设备 → 移动端同步 里点 添加设备。 凭据弹窗会直接展示一个把 base URL、用户名、一次性密码都编码进 connect URI 的大二维码 —— 不再有「先下载 → 再配对」的两步流程。 （如果手机端还没装 App，把 「还没装客户端？」 折叠区展开，里面 有 TestFlight 邀请的二维码；已经装好的直接在 App 里扫顶部那张大码 即可。）
在 App 里填入连接信息
打开 UniClipboard iOS App，点 「添加服务端」，扫描桌面端凭据 弹窗顶部那张大二维码。base URL、用户名、密码会自动填好，确认保存 即可。完成后即可与桌面双向同步剪贴板。
如果安装 / 启动遇到问题：先关掉代理梯子。 部分用户在使用 Loon、 Surge、Shadowrocket、Clash 等代理工具时，会遇到以下两类报错：
- TestFlight 打开邀请链接时提示 证书 或 HTTPS 错误；
- TestFlight 打不开 / 无法连入 App Store Connect，安装按钮一直转。
请 临时关闭代理梯子（含全局规则、TUN、HTTPS 解密、MitM 等），让 TestFlight 走直连；安装完应用后再把代理打开即可。App 本身只跟你局域网 内的桌面通信，不依赖代理。
iOS（快捷指令，备选，未安装 UniClipboard App）
如果暂时不方便走 TestFlight，也可以继续用快捷指令。在凭据弹窗中 展开 「还没装客户端？」 折叠区，停在 iOS tab，找到 「不想装 App？扫码安装快捷指令作为兜底」 那张子级二维码。
- 用 iPhone 相机扫这张快捷指令安装二维码（或在 Safari 打开安装
链接），iOS 会提示安装
UniClipboard.shortcut。 - 打开安装好的快捷指令，手动 把凭据复制过去：弹窗底部的 凭据 amber 折叠区里有完整的 base URL / 用户名 / 密码， 用其中的 备份 按钮一键复制三行后粘到快捷指令对应字段。 这张二维码只承载安装链接，不 预填凭据。
- 直接运行快捷指令（或从分享菜单触发），双向同步最新一条剪贴。
Android / 其他客户端
UniClipboard Android 客户端 的仓库地址是 github.com/UniClipboard/UniClip —— 一个客户端同时覆盖 iOS 与 Android，Android APK 直接在 releases 页 下载（侧载安装，目前不发布到 Google Play）。因为桌面监听器讲的是 SyncClipboard 协议，其他任意 SyncClipboard 协议兼容客户端也能接入。推荐顺序：
- UniClipboard/UniClip
—— 我们官方的 App（与 iOS 上是同一个客户端）：装好 APK 后填 base URL
- 用户名 + 密码即可双向同步剪贴。首选。
- SyncClipboard 官方客户端 —— 协议上游实现，跨平台桌面端为主、安卓端在 release 中也有提供，需要 自行匹配版本。适合已经在用 SyncClipboard 生态、或者想直接跟上游的人。
不论选哪一个，配置项都是同一组：
- Base URL / 服务端地址 ——
http://<对外宣告的 IP>:<port>，例如http://192.168.1.5:42720。注意是http://而非https://，监听器 本身在 v1 没有 TLS。 - Username —— 凭据弹窗 /
setup输出。 - Password —— 凭据弹窗 /
setup输出（一次性）。
经 HTTPS 反向代理走公网。 需要把移动同步暴露到公网时（例如无头 server 节点），在明文监听器前面放一层 TLS 反向代理（Caddy、nginx 等）， 并宣告它的地址而不是内网 IP：
uniclip mobile network set \
--url https://clip.example.com \
--accept-network-risk这样安装 URL / 二维码编码的是 https://clip.example.com（不带内网
端口），而监听器本身仍是内网明文 HTTP。反代终结 TLS 后转发到内网的
mobile_lan 端口 —— 该端口绝不能直接发布到公网。--ip <IP>
形态则产出 LAN 的 http://<IP>:<port>，两者互斥。
UniClipboard 移动端 App 讲的是与桌面监听器一致的 SyncClipboard 兼容协议。App 本身的 bug 一般请在 UniClipboard/UniClip 提，桌面端监听器 的协议侧 bug 留在本仓库即可。
当前 Android 限制： 监听器是明文 HTTP + Basic Auth（TLS 由反向代理或 overlay 提供）、默认同 LAN（跨网络可经 server 节点或 Tailscale）、移动端不进空间的信任网格，并且 Android 10+ 的后台剪贴板 限制会让 App 不在前台时收发被延迟或拦截。
跨网络同步：搭配 Tailscale
把桌面与手机接进同一个 Tailscale 网络（tailnet），两端各拿一个 100.x.x.x
地址，手机在蜂窝 / 异地 Wi-Fi 下也能像同 LAN 一样直连桌面 —— 不需要 VPS、
不需要域名。从 0.12 起，「监听 IP」下拉会一并列出 100.64.0.0/10
（Tailscale 的 CGNAT 段）。
完整步骤、注意事项与排错见 用 Tailscale 打通手机与桌面。 另一条跨网络路径是自建 server 节点，把网关 暴露成公网 HTTPS 端点；两者的取舍对照也在那篇里。
这条路径只换了「可达性」，没换 v1 的 HTTP 协议本身。 监听器对外依然是明文 HTTP + Basic
Auth，机密性由你信任的 Tailscale / WireGuard 隧道托底；而且它不会帮你关掉 LAN 上的监听 ——
socket 始终 bind 在 0.0.0.0，「监听 IP」只决定广告给手机的地址。
管理已配对设备
| 操作 | GUI | CLI |
|---|---|---|
| 列出已配对 | 设备页 → 移动端同步面板 | uniclip mobile status |
| 再加一台 | 移动端同步面板 → Add device | uniclip mobile add --label "…" |
| 编辑设备 | 点设备卡片 → dialog → Edit device（label / 用户名 / 密码） | 目前只 GUI；签新的并重新配对手机端 |
| 吊销一台设备 | 点设备卡片 → dialog → Revoke | uniclip mobile revoke <device-id> |
| 关闭整个功能 | 配置 modal → 关闭总开关 | uniclip mobile disable |
| 查当前监听 URL | 移动端同步面板状态条 | uniclip mobile status |
编辑设备 可以在 Edit device 视图里修改 label、用户名和/或密码。 设置或重新生成密码会签发一个新的一次性密码，并原子失效旧的 Argon2id 哈希；改用户名同样会重铸密码。旧凭据立即停用，需要把新凭据同步更新 到手机端（UniClipboard iOS App、快捷指令或其他客户端）。
吊销 会删除设备记录。携带旧凭据的后续请求会拿到 401 Unauthorized。
关闭功能 把总开关与监听器一起关掉，但 不会 清掉已配对设备记录
—— 后面再启用，原有的用户名仍然有效。要彻底清掉，用 revoke
（或 GUI 上的吊销按钮）。
安全模型 —— 覆盖了什么、没覆盖什么
| 范围 | 是否覆盖 |
|---|---|
| 桌面侧密码存储 | 是 —— 只持久化 Argon2id 哈希。 |
| 凭据轮换 | 是 —— Rotate password 签发新值并失效旧哈希。 |
| LAN 上的传输机密性 | 否（v1） —— 明文 HTTP。TLS 在 v2 才会有。 |
| 跨网络可达性 | 默认走 LAN —— 可经 server 节点（公网 HTTPS）或 Tailscale / VPN overlay 扩展（见下方）。 |
| 把手机当作 peer 加入信任网 | 否 —— 手机不会进入 iroh / 空间的信任网络。 |
实操含义：
- 把 LAN 监听器当作私网里的 SSH 服务来对待 —— 选择性地开启。
- 公共 Wi-Fi：保持监听器关闭。回到可信网络再启用。
- server 节点：想要常在线、从任意网络都能跨网络访问（又不必给每台设备 挂 VPN），可以跑一个无头 server 节点，用 TLS 反向代理把网关挡在前面 —— 具体步骤见 自建无头 server 节点。
- VPN / Tailscale：让桌面与手机进入同一个虚拟子网（RFC1918 VPN 或
Tailscale 的
100.64.0.0/10tailnet）可以当成「我想在家里之外用 LAN 风格同步」的折中。具体步骤见 跨网络同步：搭配 Tailscale。仍然是明文 HTTP，机密性由 VPN / WireGuard 隧道托底，必须信任这条覆盖网络。
故障排查
完整清单（手机连不上、401、图片损坏、改了 LAN IP 之后怎么办等）见 故障排查 — 移动端同步（iOS 快捷指令）。
接下来看哪里
- 移动端 LAN API —— 监听器对外的协议 （兼容 SyncClipboard 的 HTTP + JSON）。
- 移动端扫码接入协议 ——
uniclipboard://connect二维码协议规范。如果你在写一个新的兼容 SyncClipboard 客户端或快捷指令，需要消费弹窗里的「扫码接入」二维码， 看这一页。 - CLI 参考 — 移动端同步 —— 所有
uniclip mobile ...子命令与参数。 - 自建无头 server 节点 —— 把网关跑在 公网 VPS 上，让手机从任意网络都能经 HTTPS 访问。
- 配对与同步 — 移动端伴侣 —— 移动端 同步与桌面 ↔ 桌面配对的对照。
- 设备 — 移动端同步设备 —— 面板布局与 设备行控件细节。