排查

电脑上先跑：

pairfob doctor

用户服务状态：

pairfob service status

界面上的句子

你看到的	先做什么
电脑现在不在线	睡眠、合盖、断网，或 pairfob 没在跑。先把电脑唤醒，不用重新配对。再 pairfob doctor
不在线 · 上次连上 … / 连不上 …（宽屏整页的标题）	唯一配对的电脑或 pairfob.com 连不上。照页面列的步骤做；页面会自动重试，不用重新配对
电脑上的 Herdr 没在运行	机器还醒着，但 Herdr 退了。打开 Herdr；Pairfob 会自动恢复
… 上还没有会话	已经连上，但还没有会话——可以新建，或在电脑上打开终端
请完整输入电脑上显示的配对码	手输要 8+6 位
配对码还没输完整：需要 14 位	把定位码也贴上
配对码太长了：应该是 14 位	只留电脑上显示的那 14 位
配对码过期或已经用过	电脑重新 pairfob pair
配对码不正确	用当前打印的新码，不要改旧码
尝试太频繁	等一会儿，不要循环重试
当前 Herdr 版本还不支持这个操作	那是电脑上的 Herdr，不是手机缺按钮
电脑可能已经执行了操作。请先刷新确认，不要立即重试	不要连点；先看画面
这个会话已经不在了	回列表
这台设备的连接被另一个窗口接管了	只用一个打开的 Pairfob 页
无法读取站点配置	网络不对，或打开了错误的网页
另一台电脑开启了配对	被挤掉，在目标电脑上重新 pair
暂时无法建立 P2P，已继续使用 Relay	直连没通，会话还在中继上。要停掉自动重试，到设置把网络路线改成 仅 Relay
当前站点未开放 P2P	这个站点关掉了直连，只能走中继

doctor 对照

输出	处理
Running no	按提示执行：未安装用 pairfob service install，已停止用 pairfob service start，服务运行但无响应用 pairfob service restart，服务管理器不可用时用 pairfob run
Herdr 不是 ready	照那一行的提示做：pairfob setup 会在缺少 Herdr 时安装最新稳定版，并按需启动服务。需要 Herdr 0.8+
Origin … not set up	再跑一遍安装脚本
Paired 0	pairfob pair
P2P off	这台电脑只用中继（PAIRFOB_P2P=0）

容器中没有 systemd 用户总线

在 Linux 容器或 Kubernetes pod 中，systemctl --user 可能报 Failed to connect to bus: No medium found。即使存在 pairfob.service 文件，也不代表 systemd 用户服务管理器可用。仅设置 XDG_RUNTIME_DIR 不会启动它。

此时 pairfob update 可以替换磁盘上的程序，但无法通过服务管理器重启守护进程。 命令会报告重启失败，原来的进程可能继续运行旧程序。pairfob version 显示的是 已安装程序的版本，不是正在运行的进程版本。

用 pairfob doctor 检查运行中的守护进程。服务管理器查询失败时， pairfob service status 也会通过本地管理套接字检查 PID、版本和程序是否一致， 单独显示服务管理器错误。由于无法验证用户服务，即使安装和运行的程序一致， 它仍会以非零状态退出。

让容器入口或外部进程管理器通过绝对路径执行 pairfob run，例如 /home/agent/.local/bin/pairfob run。更新后通过该管理器重启进程；如果用 cron 看门狗，先暂停看门狗、停止旧进程，再让它启动新程序。保持用户、HOME、状态目录 和运行环境一致，以保留配对。没有守护进程运行时，可用 pairfob run 在前台启动。 重启后再次运行 pairfob doctor 和 pairfob service status 检查。

macOS 反复询问文件访问权限

“访问其他 App 的数据”与“访问下载/桌面/文稿文件夹”不是同一种授权。 部分应用数据授权只在进程运行期间有效，后台服务重启后可能再次询问。 旧版或本地编译的临时签名程序，更新后也可能无法沿用旧授权。 正式发布构建使用固定开发者签名身份；首次从旧签名切换时仍可能需要重新允许。

Pairfob 的终端和聊天功能不需要照片图库、录屏、辅助功能或输入监控权限。 文件功能需要访问所选工作区；聊天记录和额度查询需要读取相应 Agent 的本地数据， 部分额度查询还会单独请求钥匙串授权。

新版 Pairfob 的普通额度刷新只静默读取钥匙串。需要解锁或授权时会暂停该来源， 不会在后台不断弹窗；超时也会与需要授权分别报告。运行 pairfob doctor 可查看 实际程序路径、磁盘上的签名、启用的额度来源和最近的钥匙串读取状态。

需要授权时，在电脑上运行 pairfob quota authorize cursor（也支持 claude、 antigravity）。只有这项主动操作允许显示系统钥匙串提示；是否长期允许由你在 macOS 中选择。若已自行调整权限，运行 pairfob quota retry cursor 恢复静默读取。 之后等待一分钟的额度缓存过期，再刷新。授权要使用与后台服务相同的程序路径； 未编译原生钥匙串支持的开发版本会显示不可用。

只需部分额度来源时，可在安装服务时设置，例如：

PAIRFOB_QUOTA_PROVIDERS=codex,cursor pairfob service install

none 会关闭所有额度读取；未设置时保持全部来源。此设置仅影响额度查询。 重新安装服务会使用当前终端的环境，请保留原有的其他服务配置。

在 macOS 上，整个用户主目录及其上级目录不执行工作区递归搜索，也不提供 Git 状态扫描。仍可逐层浏览文件；请将会话的工作目录设为具体项目后再使用搜索和 Git 变更功能。位于下载或文稿目录中的项目仍可能在首次访问时请求相应授权。

如果确实需要持续访问受保护文件，可自行在 系统设置 → 隐私与安全性 → 完全磁盘访问权限 中添加 Pairfob。先运行 pairfob service status，使用 Executable 显示的实际程序路径；默认是 ~/.local/bin/pairfob。添加窗口中 按 ⌘⇧G 可输入路径。开启后运行 pairfob service restart。

完全磁盘访问权限覆盖的范围比项目目录大，并非使用 Pairfob 的必需条件，也不能 代替钥匙串授权。Pairfob 不会自动修改系统隐私设置。不要通过重置全部隐私权限来 解决重复弹窗，否则其他程序的授权也需要重做。

参见 Apple 关于应用数据授权的说明。

安装和登记

• 不要设 PAIRFOB_JOIN_TOKEN 或 PAIRFOB_JOIN_GRANT
• 校验和对不上时安装脚本会直接失败
• 不支持的 OS（Windows）脚本会拒绝
• ~/.local/bin 不在 PATH 时，敲 pairfob 会找不到命令，并不是服务没装上

配对

• 用当前终端里的码，不用截图
• 手输 14 位；缺 6 位定位码时请求不会发出
• 扫码失败时检查摄像头权限，或改用手输
• 电脑必须保持 pairfob pair 还在等待；Ctrl-C 掉了就重新开
• 两台电脑同时 pair 会互挤

网络路线

• 默认 自动：先走 Relay，能直连就升 P2P；升不上去会话不会断
• 切换 Wi-Fi 或重新上线会立刻再试，并重置 P2P 重试间隔
• 设置里能看到上次直连失败的原因，会话仍留在 Relay
• 直连一直失败：设置 → 电脑卡片 → 网络路线 → 仅 Relay
• 想再试直连：改回 自动，或选 仅 P2P 立即尝试
• 选 仅 Relay 后，这次浏览器里不会再自动试 P2P
• 没有 TURN；对称 NAT 会留在 Relay
• 已经在 P2P 上但 ICE 断了，会话会掉回 Relay 再升级，不会整段断开

连上了但不能操作

• 还停在配对页就还没配上
• 电脑 Herdr 退出后，已打开的会话会失败，先把 Herdr 打开
• 按钮缺失：升级并重启正在跑的 Herdr
• 路径被拒绝：超出电脑允许的目录

锁屏、合盖、睡眠

• 锁屏但机器还醒着：应该能用。Pairfob 不需要桌面保持解锁
• 合盖 / 睡眠：手机显示 电脑现在不在线。揭盖或唤醒即可，不用重新配对；电脑仍在名单上
• 机器醒着但 Herdr 退了：电脑上的 Herdr 没在运行
• Pairfob 唤不醒已经睡着的电脑。详见 常见问题

还是不行

把 pairfob doctor 的全文留下来。不要把配对码贴出去。