问题排查

下方按顺序列出各类现象，可在页面中搜索对应项。来自 herdr plugin 的 Os { NotFound } · update 提示 "not currently on a branch" · tailscale serve failed · 无响应（服务无法启动） · 手机无法打开 URL · 页面已加载但内容为空（空白页面，403） · 密码提示不接受输入 · 没有推送通知 · 重启后失效 · 窗格卡在较窄宽度 · Collie 拒绝打开 tmux 窗口 · tmux list: output did not parse · herdr plugin list 显示旧版本 · 重新构建后 UI 未更新 · 我在 Herdr 中保存了机器，但手机上没有显示 · 从手机发起的更新停留在 staging 状态 · macOS 上通过手机更新导致 Collie 未加载 · 在 macOS 上，collie status 显示“loaded, not running” · 窗格未显示 prompt-cache 标签 · Kiro 窗格的 History 打开为空 · 窗格没有 Chat 或 History · 新建的 Codex 窗格提示尚无历史记录 · 手机提示 Collie 无法读取智能体未显示的屏幕 · 发送失败 3 次且手机提供报告选项 · New 页面上的 agent 显示为灰色 · Start 提示没有文件夹，或提示无法确认 · walky talky：发送被拒绝，"run this inside a pane" · walky talky：消息停留在收件箱中且未被键入 · walky talky："no log record on this machine" · walky talky：skill 已过期 · durable agent 未显示，或显示 Unreachable。

herdr plugin … 失败并显示 Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }（插件安装失败，操作调用失败）。 这不是 Collie 的问题；这表示 Herdr 服务器未运行，因此其 CLI 无法连接控制套接字（~/.config/herdr/herdr.sock）。迹象是 原始 Os {…} 错误：可访问的服务器会返回结构化 JSON 来响应路径/清单问题（例如 plugin_manifest_not_found），因此纯粹的 Os { NotFound } 表示套接字连接失败，发生在检查 Collie 或你的路径之前。它会影响 link、install、action invoke 等所有与服务器通信的子命令，而 herdr plugin --help 仍可正常工作（它从不打开套接字）。解决方法：先启动 Herdr（运行 herdr server &，或直接启动 Herdr TUI，它会启动服务器），确认 ls ~/.config/herdr/herdr.sock 现已存在，然后重试安装。herdr plugin list 是一个快速检测手段：如果它抛出相同的错误，说明服务器已停止运行。

update 失败并显示 You are not currently on a branch。 在 0.23.1（#63）之前完成的 GitHub 安装；herdr plugin install 执行了分离而非克隆，因此旧的 update 没有可供 git pull 的分支。修复代码包含在它所修复的代码检出中，因此需要重新安装一次才能生效：如果升级失败并提示 "You are not currently on a branch" 包含这三条命令。

start 打印 note: tailscale serve failed。 Collie 本身正常（仍在 127.0.0.1 上运行），仅 tailnet 入口未启动，tailscale 自身的错误信息显示在提示上方的终端中。常见原因：你的用户不是 Tailscale 操作员（sudo tailscale set --operator=$USER）、节点已登出（tailscale up），或者在 Headscale / .internal tailnet 域名上没有可用的 HTTPS 证书（这正是 COLLIE_SERVE_MODE=http 的用途）：在 .env 中设置它，然后运行 bin/collie restart。使用 tailscale serve status 进行验证。

serve 显示 HTTPS certificates are not enabled on this tailnet。 未发布任何内容，也没有正在等待的内容。打开 admin console，开启“Enable HTTPS”，然后再次运行 collie serve。在 Headscale / .internal 域名上没有可启用的证书；请改用 COLLIE_SERVE_MODE=http。

横幅显示 ⚠ 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 秒自动重启一次，因此原因修复后通常会自行恢复。

手机无法打开 tailnet URL。 按顺序排查：(1) 手机运行 Tailscale 应用且已连接到与主机相同的 tailnet；(2) 你打开的是横幅中的 tailnet URL（bin/collie url），而非 local URL（http://127.0.0.1:8787 仅在主机本地有效）；(3) tailnet 的 DNS 设置中启用了 MagicDNS（该 URL 为 MagicDNS 名称）；(4) 主机处于在线状态；在主机上检查 tailscale status，或从手机的 Tailscale 应用 ping 主机；(5) 你的 tailnet 策略确实允许对等节点连接到此节点；如果没有，横幅现在会在 tailnet 行下方注明，其他方式均无法体现：前台入口已正确发布，证书有效，且在主机本地执行 curl 返回 200，因为回环流量从不经过数据包过滤器。有两点极易造成误导：tailscale ping 成功（disco ping 会绕过 ACL），且被拦截的流量是被直接丢弃而非拒绝，因此手机端只会一直挂起并表现为“服务器不可用”。在 ACL 策略中修复此问题（Tailscale 在 <https://login.tailscale.com/admin/acls>；Headscale 则为你的策略文件）。此项检查基于尽力而为原则，并且故意保持保守：仅当该节点的过滤器允许接入 无内容 时才会提示（这也可能意味着尚未有其他设备加入 tailnet），无法确定时则保持静默。

页面已加载但保持空白（空白页面，白屏）；API 调用失败 403 cross-origin rejected。 你正在通过不受信任的来源访问 Collie：自定义域名，或重写了 Host 的代理。使用 COLLIE_ALLOWED_ORIGINS 允许确切的公共来源（参见 配置），或让代理原样转发 Host，即 docs/deployment.md 中的第四个代理要求。

sudo（或 SSH 密码短语，或 gpg）提示不接受你的输入。 请使用键盘上方操作栏中的 键入，不要使用 Send。Send 会在按下 Enter 之前通过从屏幕回读来验证输入的内容（#34），而密码提示会关闭回显，导致无法回读：键入 会直接将你的按键发送到窗格，包括 Enter。你在 键入 中输入的任何内容都不会被存储、回显到草稿中或在稍后恢复，且 Collie 一旦识别出密码提示，就会立即丢弃已存储的草稿（#103）。

未收到推送通知。 手动触发一次：bin/collie push-test。命令按以下顺序区分三种原因：push 提示已禁用（密钥从未到达网桥，运行 push-keys 并重启，参见 Web Push）；提示没有已订阅的设备（此手机从未在“设置 → 提醒”中启用它们）；或者显示已发送但没有内容送达（手机处于纯 HTTP 源上，不属于安全上下文，“设置”会将其标记为 insecure）。

重启后 Collie 消失。 在 Linux 上这几乎总是 lingering 导致的，因此运行 loginctl enable-linger $USER（在系统重启后保持运行）。在 macOS 上，launchd agent 在 login 启动，因此请检查你是否实际已登录（而不是停留在登录窗口）并且 agent 已加载：launchctl print gui/$(id -u)/herdr.collie。

窗格的终端卡在较窄宽度，且其中的全屏应用被挤压（Copilot CLI、top，以及任何只渲染成一条、镜像其余部分留白的 TUI）。 该窗格的终端本身就只有这么宽，Collie 只是如实镜像它。Herdr 窗格的宽度取决于它在标签页分割网格中的矩形区域，因此共享标签页的窗格只会分到一部分列宽。Herdr 仅在连接了桌面客户端时应用窗格尺寸（herdr#1709）：在未连接任何客户端的情况下，关闭某个分屏后，剩余窗格仍会卡在原本的窄宽度，通过 socket 发送 pane.zoom 和 pane.resize 也无法调整它。Collie 无法在自身这一侧修复此问题；它完全不写入窗格尺寸数据（ADR 0031：手机仅在点击 Show in terminal 时调整操作终端）。此现象与具体应用无关：在 54 列的窗格中运行 top 效果完全一样。若要测量实际尺寸，可在窗格中运行 tput cols。这是真实宽度，可能与 herdr pane layout 报告的值不一致。若要修复，连接一个 Herdr 客户端并在其中缩放或调整窗格大小（一旦有客户端连接，herdr pane zoom <pane-id> --on 就会调整终端尺寸），或者关闭该窗格并重新打开一个（#167）。

Collie 拒绝打开 tmux 窗口（手机的 new tab 返回拒绝，并指明 window-size）。 这不是请求本身的错误：在低于 3.7 的 tmux 版本中，当服务器的 window-size 为 manual 时生成窗口会导致整个服务器崩溃（tmux #4849，已在 3.7 中修复），而崩溃的服务器会带走所有窗口。Collie 会直接拒绝，并指出检测到的 tmux 版本。解决方法是其打印的那行命令（在该服务器上运行 tmux set -g window-size latest），或者升级到 tmux 3.7。其他内容不受影响：这些窗格上的所有其他操作继续正常工作（环境要求 带有相同的注意事项）。

Collie 记录 tmux list: output did not parse 且仪表盘显示为空。 这并非崩溃：某些 tmux 版本（如 3.4，而非 3.6b）在输出 -F 列表时会对此适配器读取的分隔符进行转义。Collie 现在能兼容这两种格式，因此解析结果为零行的列表会被报告为 mux 错误，而不会被存储为空 herd；错误行会指明 tmux 版本以及检测到的行数。第二个原因是语言环境：在未设置 UTF-8 语言环境的情况下启动（例如极简容器或 systemd unit），tmux 会使用 _ 替换该分隔符而不是对其进行转义。Collie 现在运行时会在每个 tmux 命令中加入 -u，因此列表输出不再依赖 LANG 或 LC_ALL。如果仍遇到此问题，请记录 tmux -V 版本并提交 issue；此修复应在适配器中进行，而不是修改你的 .env。

update 后 herdr plugin list 仍显示旧版本。 符合预期：Herdr 会缓存其在安装或链接时读取的清单。实际运行版本的判定依据是页脚 build stamp 或 bin/collie version。对于链接的克隆，update 会重新链接并自动恢复（使用 herdr plugin link "$(pwd)" 强制执行）；在 Herdr ≥0.8.0 上，清单无论如何都会从磁盘重新读取。

重新构建后手机显示陈旧的 UI。 PWA 的 service-worker 缓存是按 origin 划分的，因此通过两个 origin 访问 Collie（自定义域名 和 原始 host:8787）会生成两个安装实例，各自缓存其对应的 bundle。页脚 build stamp (vX.Y.Z · sha · time) 显示你当前运行的 bundle；Collie 通过 X-Collie-Build 头和 /api/config 报告其提供的版本。若不匹配，页脚会提示 "new build — tap to update." 否则可以多重新打开几次 PWA（SW 会自动更新）或清除该 origin 的网站数据。最佳实践：选定一个 HTTPS origin 并始终使用它。（在纯 HTTP 下 SW 无法注册，虽然始终保持最新，但无法使用 PWA 功能。）

我在 Herdr 中保存了机器，但手机上没有显示。 正常现象。Herdr 保存的机器属于其自身客户端列表，而 crew 属于 Collie；两个列表互不同步。要从手机访问该机器，请将其登记：在 lead 上运行 collie crew add <ssh-host>，然后在 lead 上运行 collie restart 并执行 collie crew status 检查连接。在 Herdr 中添加或删除机器不会对 crew 产生任何改变（Herdr 机器与 crew）。

窗格未显示 prompt-cache 标签。 可能是三种情况之一，collie doctor 可区分它们。窗格的 harness 没有日志适配器，对应其 integration-<agent> 和 journal-roots 行标明的内容。窗格从未上报过会话，对应其 agent-sessions 行按窗格 ID 列出的内容。或者 agent 尚未执行轮次，这并非故障：测量前不会显示任何内容，因此标签会在 agent 的首次回复时出现。若 harness 厂商未发布缓存有效期，同样不会显示任何内容，cache-claims 列出了当前构建版本自带的全部规则。

Kiro 窗格的 History 打开为空。 检查窗格中的 Kiro 是否持有会话锁：

cat ~/.kiro/sessions/*/*/.lock

Herdr 不会为 Kiro 窗格指定会话名称，因此 Collie 通过运行中的 Kiro 所持有的锁来查找它。这仅在 Herdr 上有效，因为它是唯一能列出窗格前台进程的复用器，且仅在恰好有一个 Kiro 进程在其中运行时才有效。否则 History 会提示该窗格没有 agent 会话。

Collie 读取通过 --v3 或 --agent-engine v3 启动的、或在 Kiro 自身设置中将 V3 设为引擎的 Kiro V3 会话，因此请在该窗格中以这种方式重新启动 Kiro。Kiro 没有需要安装的 Herdr hook。如果其会话保存在其他位置，请设置 kiro_root，然后运行 collie restart。

某个窗格显示了终端，但你预期看到的是 Chat。 agent 窗格默认显示“聊天”，因此可能属于以下两种情况之一。该设备之前选择了终端：打开窗格的 ⋮ 菜单并点击 Chat 视图。或者窗格没有可读取的 session 或日志。新窗格会显示带有“发送消息以开始”的“聊天”，当其第一轮结束且没有可读内容时，或者当它先提出问题时，会回退到终端；菜单行会显示缺失的部分，下一项给出了具体步骤。

窗格中没有聊天或历史记录，且 ⋮ 菜单提示该窗格未命名任何会话。 聊天和历史记录会读取 agent 的会话日志，且仅当 agent 通过多路复用器上报其会话时，Collie 才能找到该日志。在 Herdr 上，该上报来自 agent 自身的集成，因此如果集成缺失或过旧，两者都会被隐藏且没有其他症状。collie doctor 在 agent-sessions 下列出了窗格名称，并在 integration-<agent> 下提供了修复方案。

1. 01
   运行 herdr integration status。若 agent 是 not installed 或 outdated，运行 herdr integration install <agent>。Oh My Pi 是 omp，pi 是 pi：两者需要分别配置。
2. 02
   在该窗格中重启 agent。agent 在启动时加载其 hook，因此在安装期间处于运行状态的 agent 会持续不上报任何内容。
3. 03
   如果 hook 是最新的，而重启后的窗格仍不上报任何内容，请检查该 agent 是否是从另一个 agent 打开的 shell 中启动的。当从父 agent 继承 OMPCODE=1 时，Oh My Pi 的 hook 会保持静默。请从全新的终端启动它。

在 tmux、zellij 和 tern 上，只有 Claude Code 会通过 Collie 的 beacon hook 上报会话。运行 collie hooks install claude（Collie 将 hook 写入 Claude 自身的设置中）。其他 agent 在那里没有 Chat 或 History。

新建的 Codex 窗格提示尚无历史记录。 在首次交互前属于正常现象。Codex 仅在发送第一个 prompt 时向 Herdr 上报会话，启动时并不上报，因此新建窗格在此之前既无会话，也无 History 链接。collie doctor 会将此类窗格列在 agent-sessions 下并标记为尚未上报，不计为故障。若 Codex 回复后该提示仍未消失，请在 Codex 中打开 /hooks。当 hooks 发生变动时，Codex 会要求审核；选择 "Continue without trusting" 会停用 Herdr hook，此时 herdr integration status 仍会显示其为最新。请在其中信任该 hook，或运行 herdr integration install codex 并启动新会话。

手机提示 Collie 无法读取对话框，或发送的内容未进入输入框，但电脑端的智能体仍显示正常 prompt。 Collie 读取屏幕出错，通常是因为智能体改变了绘制屏幕的方式。请提交 issue 并附上屏幕原始文本，它能体现截图无法展示的信息（即 Collie 读取的颜色与暗淡文本）。先用 herdr pane list 找到窗格 id，然后运行

herdr pane read <pane-id> --source recent --lines 200 --format ansi > pane.txt

在手机仍出现该问题时操作，并将 pane.txt 与智能体版本（claude --version、codex --version 等）一同附上。该文件为终端文本，请先阅读并移除所有隐私内容。

发送失败 3 次且手机提供报告选项。 单个窗格上连续 3 次发送因指向 Collie 的原因而失败：无法读取或写入输入框、文本已进入但未输入 Enter，或者丢失了发送跟踪。出于保护机制的拒绝（输入框中有草稿、轮次正在运行、打开了对话框）不计算在内。点击卡片上的 报告。在发出任何内容之前，工作表会显示整个 issue：Collie 和 agent 版本、复用器以及每次失败发送的状态码。除非您开启 包含我输入的内容 或 包含屏幕内容，否则它不包含您键入的文本和屏幕截图。屏幕内容为窗格的最后 40 行，并已屏蔽已知机密格式；但由于 issue 是公开的，仍请务必核对。在 GitHub 上打开 会使用您自己的 GitHub 账户在浏览器中打开已填充的表单，复制报告 会复制相同的文本。先点击 已经报告过？ 可查找具有相同特征行的 issue。窗格菜单和 设置 → 系统 可随时打开相同的工作表。点击叉号可在该窗格上关闭卡片，直到下次发送成功。crew 成员的窗格目前不提供报告；请使用上述步骤。

从手机发起的更新停留在 staging 状态。 在 1.6.0 及更早版本的 Collie 中，在手机上点击更新可能会将新版本暂存后停止：执行替换的 runner 从未启动，服务继续提供旧版本，且运行记录停留在 staging 并持有锁。同时满足以下三个现象即可确认此问题：collie update --status 报告 staging（或者超过十分钟后报告 interrupted — the updater is gone）、versions/ 下存在新版本的版本目录、~/.config/collie/collie.log 处的 runner 日志为 0 字节。在同一台机器的 shell 中输入 collie update 始终有效，这是从另一侧看到的同一个缺陷。此问题已在下一个版本中修复：移交现在会等待用户管理器确认 runner，被拒绝的移交将报告为失败并附带管理器自身的原因。

若要恢复已经卡住的机器，请等待十分钟且不要进行任何操作：updater 已退出的运行会在最后一次状态转换十分钟后停止阻塞重试，随后即可再次点击继续。若要立即恢复，请删除记录、锁以及 staging 进度文件，然后检查 --status 的输出：

collie update --status            # note the pid it names
ps -p <pid> -o command=           # empty output: the updater really is gone
rm -f ~/.local/state/collie/update.json ~/.local/state/collie/update.lock
rm -f ~/.local/state/collie/update-staging-*.log
collie update --status            # "no update has run on this install yet"

没有用于清除过期运行的子命令，这三个文件就是停滞的 staging 留下的全部状态。带后缀的实例会将它们保存在 ~/.local/state/collie-<name>/ 中。切勿在更新实际运行时删除这些文件，请先检查 pid：如果您移除了正在运行的 updater 的锁，它将在毫无保护的情况下切换 current。不要修改 versions/。暂存了一半的版本目录无害，重试时会重新写入其中，保留清理机制会自动移除不再需要的内容。

macOS 上通过手机更新导致 Collie 未加载。 在 Mac 上运行此命令：

collie restart

在不超过 1.8.x 的 Collie 版本中，在手机上点击更新可能会停止 launchd agent 且不再加载它，导致手机断开服务，launchctl print gui/$(id -u)/herdr.collie 找不到任何内容。runner 与 agent 共享进程组，重启 agent 会在半途将其杀死。collie restart 会重新写入 agent 的 plist 并加载它。从 1.9.0 开始，bridge 会在自己独立的进程会话中启动 runner。如果在此之后手机更新仍然卸载了 agent，请运行相同的命令并在 #213 中附上说明。

在 macOS 上，collie start 已执行完毕，但 collie status 显示 "loaded, not running"。 launchd 任务已加载但没有进程在运行，因此日志为空。手动启动该任务：

launchctl kickstart gui/$(id -u)/herdr.collie
collie status

带后缀的实例有自己的标签，例如 herdr.collie-next。从 1.17.0 开始，collie start 和 collie restart 会替你执行此步骤；如果没有进程出现，还会打印包含此命令的警告。如果任务在此之后仍保持 "loaded, not running"，请使用 collie logs 查看日志，然后在 #213 中添加说明。

New 页面上的 agent 显示为灰色。 原因紧随名称后显示在括号中。"not installed" 表示机器在登录 shell 使用的 PATH 中未找到该 agent 的命令。在该机器的登录 shell 中运行 bash -lc 'command -v claude'（或该 agent 本身的名称）。如果没有输出，请在该机器上安装该 agent，或修改 shell 登录文件中将其添加到 PATH 的配置行，然后重新打开页面。在 crew 中，请检查你选中的机器：每个成员只查找各自的磁盘。"this machine runs an older Collie" 表示需要更新该成员（在机器上启动任务）。"needs Herdr" 和带有机器名称的 "only on" 属于 新建 worktree 开关，不属于 agent。

Start 提示 "There is no folder … on this machine" 或 "could not confirm the start"。 第一种提示表示该文件夹不存在于执行启动的机器上，因此未启动任何内容。不以 / 或 ~ 开头的名称表示 home 目录下的文件夹，因此 projects 表示 ~/projects。创建该文件夹，或从 Recent 中选择一个。第二种提示表示手机未收到回复。请先查看仪表板，因为该窗格可能已经存在。重试 会发送完全相同的请求，绝不会重复打开第二个窗格（从手机启动 agent 或 shell）。

Walky talky

walky talky 最常出现六种故障现象。每种现象都有一个命令可显示其原因（Walky talky）。

collie walky send 提示 "run this inside a pane, or send from the phone"。 该命令在 agent 窗格外部运行，例如在普通终端中。Collie 会根据窗格自身的环境来确定发送方名称。不在窗格内的发送会被拒绝。请在 agent 窗格中运行该命令，或从手机发送。在 agent 窗格中，collie walky who 会用 (you) 标记你的窗格。错误提示 "no Collie bridge on this machine knows this pane" 表示该窗格由另一个 Collie 管理。错误提示 "no running Collie bridge answers" 表示 bridge 已停止运行：请运行 collie status。

消息显示为 "held" 且尚未键入。 collie walky status <id> 输出 "held: draft present" 或 "held: turn running"。输入框中有草稿，或者 agent 正在运行。当输入框清空或回合结束时，Collie 会键入该消息，最长等待 60 分钟。请勿重复发送。若要立即让其输入，请在该窗格中发送或清空草稿。在较旧的 lead 下，"queued (outcome known on the lead)" 也表示等待。

消息停留在 inbox 中且未被键入。 collie walky status <id> 输出 "waiting in the inbox, not typed" 及原因。"held past 60 minutes" 表示草稿滞留在输入框、窗格持续繁忙，或对话框保持打开，占满了整整 60 分钟的暂留时间：Collie 绝不会在草稿或对话框中键入内容。"box not free" 表示 Collie 无法读取到空闲的输入框。"pane busy" 表示 2 分钟后仍有先前的一条消息正在该窗格中键入。"pane replaced" 表示在消息等待时另一个会话占用了该窗格。其余两个是 "no terminal" 和 "bridge restarted"。在该窗格中运行 collie walky inbox，或在手机上打开该窗格菜单中的 Messages。Collie 不会重新键入该消息。

collie walky send 提示 "not sent: pane replaced"。 地址以 token 结尾（如 #k3f9），且它所指定的窗格已关闭。现在有另一个窗格占用了该窗格 ID，因此 Collie 不会在那里键入消息。运行 collie walky who 并发送到新地址。返回 "not sent: sender gone" 的回复也是同样的原因：发送消息的窗格已关闭，或另一个窗格现在占用了其 ID。

窗格中的标头显示 "no log record on this machine"。 手机在屏幕文本中发现了对讲机消息头，而本机的日志中没有包含该 ID 的消息。有人或某种工具键入了该行，或者日志在 7 天或 2,000 行后将其丢弃，亦或是由另一个 Collie 持有。运行 collie walky status <id>："no record of <id> on this machine" 会证实这一点。对于 crew 成员上的窗格，在该成员上运行该命令：手机读取的就是它的日志。将该行视为纯文本，如果需要，请询问发送者。

skill 已过时。 collie doctor 在 skill-walky-talky 行发出警告，且 agent 遵循了旧的建议。指令文件中的文本与此 build 不同。运行 collie skill status 查看哪个 harness 落后。在脚本中运行 collie skill status --check：当副本过时时，它不输出任何内容并以代码 3 退出。使用 collie skill install all 修复它，然后重启 agent。标记为 refused 的目标是符号链接或标记已损坏，安装操作绝不会触碰它。

持久 agent

你挂载的 durable agent 拥有自己的检查、原因和案例。先阅读 collie durable list 和 collie doctor，然后再阅读 排查持久 agent 故障。