移动端同步

在桌面与 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 码。

打开设备页

页面顶部是「本设备」Hero，中间一行是两个 tab：「已配对设备」 与 「手机同步」。切到「手机同步」tab，tab 行右侧出现 配置 与 添加设备 两个按钮。监听器若 bind 失败，添加设备 仍可点击，点击后弹出提示说明原因；详细错误显示在「配置」modal 里。

点配置

弹出居中的「移动端同步配置」modal。在「同步开关」段打开 启用移动端同步 与 LAN 监听，再到「网络参数」段选：

监听 IP —— 留作 Auto，复制时桌面会列出全部 RFC1918 候选；或挑一个具体网卡，把对外宣告的 URL 固定到该接口。Tailscale CGNAT (100.64.0.0/10) 地址会一并出现在下拉里，让 Tailscale 可达的手机也能像同 LAN 一样配对；这与 设置 → 网络 → 允许覆盖网络地址 开关无关，那个开关只影响桌面 ↔ 桌面 pairing。无论选哪种，实际 socket 永远 bind 在 0.0.0.0，这个选项只决定要给移动设备宣告哪个地址。
端口 —— 默认 42720，冲突时再改。

modal 里实时显示 当前监听地址（Listening URL）。若监听 IP 为 Auto，该行会内联展开列出全部 LAN IPv4 候选，挑移动设备能拨通的那个直接复制；若挑了具体网卡，行内就是单一 URL。LAN 监听是热切换的，改完即时生效，不需要重启 daemon。

如果守护进程上抛 lan_listener_error（端口被占或权限不足等）， modal 顶部会出现红色 Alert，列出具体原因；监听不起来时点击 添加设备 也会弹出同样的原因提示。

点添加设备

填一个标签（例如「My iPhone 15」）。桌面会签发一次性的 用户名 与密码，并在一个 扫码优先（scan-first） 的凭据弹窗中一次性展示：

大二维码（顶部，常驻） —— 把 全部可达候选地址（已配置的公网入口 + 所有合格网卡 IP，含 Tailscale CGNAT）连同凭据编码进单一 uniclipboard://connect URI —— 同一个码在内网、外网都能用，支持候选列表的客户端会逐个探活选路。用 UniClipboard iOS App （TestFlight beta 公测中，推荐路径，详见下文配对一台 iPhone）、 UniClipboard Android 客户端或任何兼容 SyncClipboard 协议的客户端扫一下即可，所有字段自动填好、无需手输。二维码旁边带一个 baseUrl 下拉，可以切换哪个地址作为首选（第一）候选——其余候选仍保留在码里——不必回到「配置」 modal。
「还没装客户端？」折叠区（默认收起） —— 手机端还没装客户端时再展开。里面分两个 tab：iOS tab 展示 TestFlight 邀请链接的二维码（附带一个快捷指令安装二维码作为子级 fallback，给不便走 TestFlight 的用户）；Android tab 展示 GitHub Releases APK 下载页的二维码。
「凭据」折叠区（amber 警告色，默认收起） —— 展开后才显示明文 username / password，主要给那些需要手输的客户端使用。顶部带一个备份按钮，可以一键把 Server / Username / Password 三行复制到剪贴板。

关闭弹窗（完成按钮、X 图标、Esc、点弹窗外都行）都会 保留设备，弹窗里不再提供「丢弃」入口。如果要撤销已注册的设备，回到 移动端同步 设备列表上点对应卡片走 dialog 操作（见管理已配对设备）。

明文密码 只显示一次。弹窗关闭后桌面只保留 Argon2id 哈希。

# 一键：启用功能 + 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)，手机会逐个地址探活连通

uniclip start                                # 把 daemon 拉回来

非交互模式下 --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/10 tailnet）可以当成「我想在家里之外用 LAN 风格同步」的折中。具体步骤见跨网络同步：搭配 Tailscale。仍然是明文 HTTP，机密性由 VPN / WireGuard 隧道托底，必须信任这条覆盖网络。

故障排查

完整清单（手机连不上、401、图片损坏、改了 LAN IP 之后怎么办等）见故障排查 — 移动端同步（iOS 快捷指令）。

接下来看哪里

移动端 LAN API —— 监听器对外的协议（兼容 SyncClipboard 的 HTTP + JSON）。
移动端扫码接入协议 —— uniclipboard://connect 二维码协议规范。如果你在写一个新的兼容 SyncClipboard 客户端或快捷指令，需要消费弹窗里的「扫码接入」二维码，看这一页。
CLI 参考 — 移动端同步 —— 所有 uniclip mobile ... 子命令与参数。
自建无头 server 节点 —— 把网关跑在公网 VPS 上，让手机从任意网络都能经 HTTPS 访问。
配对与同步 — 移动端伴侣 —— 移动端同步与桌面 ↔ 桌面配对的对照。
设备 — 移动端同步设备 —— 面板布局与设备行控件细节。