Collie 故障排查清单:连不上、推送不响、配对失败等 8 类症状的快速解决方案

原创2026-10-14 07:03:452,281 阅读

Collie 故障排查清单:连不上、推送不响、配对失败等 8 类症状的快速解决方案

Collie 是一款自托管 PWA 手机客户端,让你从 iPhone 或 Android 远程控制 Herdr、tmux、zellij 中的 Claude Code、Codex、Pi、OpenCode 等 AI 编码代理,并支持推送通知。日常使用中偶尔会遇到连不上、白屏、推送不响等问题。本文把 docs/troubleshooting.md 中的官方故障排查经验,按 8 类高频症状 整理成一份快速解决方案清单,帮你定位并修复问题。

Collie 手机 AI 代理远程客户端界面

30 秒速查:8 类症状对照表

# 症状 快速解法
1 手机连不上 / 打不开 URL 先查 Herdr 服务与 Tailscale 链路
2 服务启动后不响应 看日志:多半是端口被占用
3 页面加载但空白(403) 用 COLLIE_ALLOWED_ORIGINS 放行来源
4 推送通知不响 collie push-test 定位三叉原因
5 重启后 Collie 消失 启用 linger(Linux)或检查 launchd(macOS)
6 窗口窄条 / 拒绝开 tmux 窗口 终端真窄或 tmux 版本过旧
7 配对失败 / 密码框卡住 核对 COLLIE_TRUSTED_USER;用 Type 而不是 Send
8 界面过期 / 更新卡 staging 固定单一 HTTPS 来源,看 build stamp

建议同时运行一次 collie doctor——它能直接报出 PATH 问题、未上报的 agent session、缺失的 journal 适配器等,是排查第一选择(见 docs/commands.md)。

1️⃣ 症状一:手机连不上、打不开 Collie URL

典型信号:手机上 tailnet URL 一直转圈或加载失败;或者 herdr plugin … 报 Os { code: 2, kind: NotFound };或 start 提示 tailscale serve failed。

排查顺序(由内而外):

  1. Herdr 服务是否在运行? herdr plugin 命令直接报原始 Os { NotFound } 说明 CLI 连不上控制 socket(~/.config/herdr/herdr.sock)。先启动 Herdr(herdr server & 或打开 Herdr TUI 即可拉起服务端),再用 herdr plugin list 快速探测。
  2. Tailscale 链路五连查:手机装有 Tailscale 并已连接到同一 tailnet;你打开的是 bin/collie url 输出的 tailnet 地址(http://127.0.0.1:8787 只能在主机本机打开);tailnet 已开启 MagicDNS;主机在线(tailscale status);ACL 策略允许该 peer 访问此节点。
  3. HTTPS 证书问题:tailscale serve 报 HTTPS certificates are not enabled on this tailnet 时,去 Tailscale 管理控制台开启 "Enable HTTPS";Headscale / .internal 域没有证书可开,改用 COLLIE_SERVE_MODE=http 写入 .env 后 bin/collie restart。

⚠️ 一个隐蔽陷阱:ACL 拦截时 tailscale ping 依然成功(disco ping 绕过 ACL),流量是被静默丢弃而非拒绝,手机只会表现为"卡死",极易误判为服务器挂了。横幅(banner)在 tailnet 行下方会提示 ACL 不通过,看到它就直接去改 ACL 策略。

2️⃣ 症状二:服务起来了但 Collie 不响应

典型信号:横幅显示 ⚠ Collie isn't answering on :8787 yet、连接被拒绝。

服务单元已拉起但 HTTP 服务没应答。按顺序检查:

systemctl --user status collie   # 先看单元状态
bin/collie logs                  # 或 journalctl --user -u collie -f 实时跟踪

最常见原因:端口被占用。在 .env 里设置新的 COLLIE_PORT,再 bin/collie restart(该命令会重新对新端口执行 tailscale serve)。另一类原因是首次构建失败,日志会直接说明,修好后运行 bin/collie build。单元每 5 秒自动重试,原因修好后服务通常自己就能恢复。

3️⃣ 症状三:页面能打开却空白(白屏、403)

典型信号:页面加载成功但一片空白;API 调用失败报 403 cross-origin rejected。

你在用一个 Collie 未预期的 origin 访问——自定义域名,或改写了 Host 头的反向代理。两种解法:

  • 在 .env 中用 COLLIE_ALLOWED_ORIGINS 放行确切的公开 origin(写法见 docs/configure.md);
  • 或者让代理原样转发 Host 头——这是 docs/deployment.md 中变体 B(identity-aware proxy)的四条代理要求之一。

安全提醒:Collie 设计上提供远程 shell 能力,URL 等同 root 登录。请固定使用 tailnet 内的 HTTPS 来源,设置 COLLIE_TRUSTED_USER,永远不要使用 tailscale funnel(那会把端口暴露到公网)。详见 docs/security.md。

4️⃣ 症状四:推送通知不响

典型信号:agent 等待输入了,手机却没收到任何推送。

先在主机上手动发一条:

bin/collie push-test

该命令会按顺序区分三种原因:

  1. 推送显示未启用 —— VAPID 密钥没进到 bridge。运行 collie push-keys 生成密钥对(写入 .env 的 COLLIE_VAPID_PUBLIC / COLLIE_VAPID_PRIVATE,权限 600),再 collie restart。
  2. 没有已订阅设备 —— 这台手机从未在 Settings → Alerts 里开启过通知,去开启即可。
  3. 显示已发送但收不到 —— 手机当前用的是纯 HTTP origin(非安全上下文),Settings 里会标记 insecure。Web Push 必须运行在 HTTPS 来源下。

完整推送设置流程见 docs/voice-and-push.md 的 Web Push 小节。

5️⃣ 症状五:重启后 Collie 消失了

典型信号:主机重启或重新登录后,Collie 服务没了。

  • Linux:几乎都是 lingering 未开启导致的。systemd 用户服务默认随用户会话退出而停止:

    loginctl enable-linger $USER
    

    更多细节见 docs/upgrading.md 的 "Surviving reboots" 小节。

  • macOS:launchd agent 在用户登录时启动。确认你真的登录了(而不是停在登录窗口),并检查 agent 是否已加载:launchctl print gui/$(id -u)/herdr.collie。若 collie status 显示 "loaded, not running",手动拉起:launchctl kickstart gui/$(id -u)/herdr.collie。

6️⃣ 症状六:窗口是窄条 / 终端显示异常

典型信号:全屏应用(如 top、Copilot CLI)被挤成一条;手机新建标签页被拒绝(提示 window-size);日志出现 tmux list: output did not parse。

  • 窄条窗口:pane 里的终端真的就这么宽,Collie 是忠实镜像。在 pane 里运行 tput cols 可量出真实宽度。Herdr 的 pane 宽度来自分屏网格,且只在有桌面客户端附着时才应用几何变化——没附着时关闭一个分屏,幸存者会卡在旧窄宽,socket 上的 pane.zoom / pane.resize 也推不动它。修复方式:连接一个 Herdr 客户端,在里面放大(herdr pane zoom <pane-id> --on)或调整大小;或直接关掉该 pane 新建一个。
  • 拒绝开 tmux 窗口:tmux 3.7 以下、window-size 为 manual 时,创建窗口会崩掉整个 tmux 服务器,Collie 主动拒绝并提示。执行它打印的那行修复命令 tmux set -g window-size latest,或升级 tmux 3.7+。
  • output did not parse:个别 tmux 版本(如 3.4)转义分隔符的方式不同,或启动时没有 UTF-8 locale。新版 Collie 已兼容两种形态且强制以 -u 运行 tmux 命令;仍复现的话,记录 tmux -V 版本并提 issue。

7️⃣ 症状七:配对失败 / 认证不通过

典型信号:浏览器打开 Collie 只看到配对界面、请求全部被拒;或密码框输入卡住。

  • Collie 的设备配对常开:每个设备需要对每一个请求出示 token,未配对的浏览器只能看到配对页。核对 .env 里的 COLLIE_TRUSTED_USER 与你的 tailnet 登录名完全一致(tailscale serve 会注入 Tailscale-User-Login 头,Collie 据此拒绝其他人),并只配对你实际使用的那台物理手机。配对流程详见 docs/security.md。
  • 密码 / sudo / SSH 口令框收不到你的回复:这是设计行为。Send 会先回读屏幕来校验输入,而密码提示会关闭回显,导致无内容可校验。请改用键盘上方的 Type——它把按键(含 Enter)直接送入 pane,不存储、不回显,识别到密码提示后 Collie 还会顺手丢弃已存的草稿。

8️⃣ 症状八:界面看着像旧的 / 更新卡住

典型信号:rebuild 后手机显示旧 UI;页脚 build stamp 与主机版本不一致;手机上点更新停在 staging。

  • stale UI:PWA 的 service worker 按 origin 缓存——你同时用自定义域名和裸 host:8787 访问,就等于装了两套,各自缓存。页脚 build stamp(vX.Y.Z · sha · time)显示你实际运行的 bundle;不一致时页脚会出现 "new build — tap to update",点它即可;也可以重开 PWA 几次让 SW 自动更新,或清除该 origin 的站点数据。最佳实践:固定使用一个 HTTPS origin。
  • 手机更新卡在 staging(1.6.0 之前):collie update --status 报 staging(超 10 分钟变 interrupted)、新版本目录存在、runner 日志 0 字节——三者同时出现即为此缺陷。新版已修复交接等待逻辑;已卡住的机器可等 10 分钟让锁自动失效,或按 docs/troubleshooting.md 的步骤核对 pid 后清理 ~/.local/state/collie/ 下的 update.json、update.lock 和 update-staging-*.log(正在更新时切勿删除,versions/ 目录保持原样)。
  • macOS 手机更新后 agent 未加载:在 Mac 上运行 collie restart 即可重写并加载 plist(1.9.0 起 runner 独立会话启动,已根治)。
  • agent 在 New 页置灰:名字后括号里就是原因。"not installed" 说明登录 shell 的 PATH 里找不到该命令——在目标机器上跑 bash -lc 'command -v claude' 验证,装好或修好登录文件里的 PATH 行后重开页面。
  • Start 提示 "There is no folder …":不带 / 或 ~ 前缀的名字按家目录下解释,projects 即 ~/projects;创建该文件夹或从 Recent 里选一个。提示 "could not confirm the start" 只是手机没收到回执,先看 dashboard——pane 很可能已经存在,点 Try again 重发同一请求即可,不会开出第二个 pane。

附:常用诊断命令速记

命令 作用
collie doctor 全面体检:PATH、agent session、journal 适配器、缓存规则
collie push-test 手动发一条推送,区分推送三叉故障
collie push-keys 生成 VAPID 密钥对写入 .env
bin/collie url 输出应打开的 tailnet 地址
bin/collie logs 查看服务日志(等价 journalctl --user -u collie -f)
collie version / 页脚 build stamp 确认真正运行的版本

💡 遇到读不出的对话框或发送进不了输入框:用 herdr pane list 找到 pane id,运行 herdr pane read <pane-id> --source recent --lines 200 --format ansi > pane.txt,把脱敏后的 pane.txt 连同 agent 版本一起提 issue——原始终端文本能揭示截图看不见的颜色与暗色信息。

更多按"搜索词"组织的完整症状列表,见仓库官方文档 docs/troubleshooting.md;所有 CLI 命令的完整说明见 docs/commands.md。

登录后查看全文
collie