问题排查
Agent HUD 在 Mac、iPhone 与 Apple Watch 上的常见问题：各自的原因，以及怎样解决。
下面每个问题先说原因，再说解决办法。没有找到你的问题时，见最后的「怎样获得帮助」。
为什么请求没有出现在 HUD 上
请求经由各 agent 自己设置里的回调来到 HUD，而 Agent HUD 只在你要求时才写入这些回调。
- 客户端回调没有打开。 在你打开之前，它一直是关着的：设置 → 通用 → 客户端 → 客户端回调。
- Agent HUD 不在「应用程序」里。 只有位于
/Applications/Agent HUD.app的 Agent HUD 才能安装客户端回调；从别处打开时，这个开关不可用。把应用移到「应用程序」，再从那里打开。 - Agent HUD 没有运行。 这时各个 agent 照常在自己的窗口里询问。
- 这个 agent 不发请求。 只有部分 agent 会发，有些还需要额外的一步：Codex 要先信任它的回调（见下一个问题），DeepSeek Harness 要在设置 → 智能体插件里装上 Agent HUD 的插件。见客户端回调。
你没有处理的请求，过了等待回答设定的时间就交还 agent，默认 10 分钟。
为什么 Codex 的请求不再出现在 HUD 上
Codex 只运行你信任过的回调；回调的命令一旦改变，它就停止运行这段回调，直到你重新审阅，而且不会提示你。打开客户端回调、打开远程会话时，Agent HUD 都会添加或修改 Codex 的回调。
- 解决： 在 Codex 里审阅 Agent HUD 的回调，重新信任它们。
- 另外确认： Codex 只把由你本人审阅的请求交给 Agent HUD；交给 Codex 自动审阅的请求留在 Codex 里。
为什么某个 agent 的额度从面板上消失了
Agent HUD 用 agent 自己的登录读取额度。agent 的命令行退出登录后，就没有账户可读，这个额度区块会从面板上消失；会话与 Token 不受影响。
- Claude Code： 在终端里运行
claude重新登录，下一次读取时额度就会回来。这期间 Claude 桌面版照常可用，因为它有自己的登录。读取只是一时失败时，上一次的读数会保留，Agent HUD 稍后自动重试。 - 用 API key 或第三方平台登录： 这种登录方式没有订阅额度，所以没有额度可显示。
- GitHub Copilot CLI： 在设置 → 智能体里打开读取 GitHub Copilot 额度之后，它的额度才会出现。
为什么 iPhone 找不到我的 Mac
在同一网络里，iPhone 直接读取 Mac，前提是两者已经配对。
- 共享没有打开。 在 Mac 上打开设置 → 局域网 → 局域网共享。在你打开之前，它一直是关着的。
- 邀请已过期。 邀请只能用一次，五分钟后失效。再点一次创建邀请，扫描新的二维码。
- 两台设备不在同一个网络。 让 iPhone 和 Mac 连接同一个 Wi-Fi。离开这个网络时，iPhone 需要 Agent HUD Remote。
- iOS 拦住了连接。 在 iPhone 的设置 → 隐私与安全性 → 本地网络里允许 Agent HUD。
- 配对已被撤销。 Mac 上点过撤销已配对设备之后，iPhone 会请你重新扫描这台 Mac 的配对码。
- 有一端的应用太旧。 iPhone 提示请更新两台设备上的 Agent HUD 时，把两边都更新。
Mac 上的 Agent HUD 要在运行，iPhone 才能读到它。
为什么 Remote 不更新
Remote 的一切都经由你的 iCloud 传递。Mac 大约每 30 秒发送一次用量与会话，请求与提醒则立即发送。
- Apple 账户不同。 Mac 和 iPhone 必须登录同一个 Apple 账户。
- Mac 上没有打开 Remote。 打开设置 → 远程 → Agent HUD Remote。
- 这台 Mac 没有名额。 在设置 → 订阅里，Agent HUD Remote 这一行应当写着 App Store。如果写着「本机尚未启用」，点使用 App Store 名额。名额都用完时，先移除另一台 Mac。
- Mac 上的 Agent HUD 没有运行，或者 Mac 在睡眠。它再次运行之前，什么都不会发出。
- iCloud 储存空间已满。 iCloud 拒收新的记录，Mac 每小时重试一次。清理出 iCloud 空间即可。
- 订阅已结束。 iPhone 显示 Agent HUD Remote 已到期，以及它最后收到的数据。
Mac 的设置 → 远程在状态下显示 iCloud 连接情况、还在等待的保存，以及上次保存的时间。在 iPhone 的首页、统计或会话页下拉，即可重新读取 iCloud。
请求、对话与消息还需要同步之外的几项：打开远程会话与共享对话，打开客户端回调，以及 Agent HUD 的 Claude Code 插件。见 Agent HUD Remote 中的「Mac 需要什么」。
为什么数字看起来不对
多数意外来自一个数字到底算的是什么。
- 费用是估算，按各厂商的标价计算，标有 ≈，不是实际扣费。某个模型的价格不对时，在设置 → 价格里改成你自己的。
- Token 历史在 Mac 上保留 30 天，更早的 Token 不再保留。
- 子 agent 算在开启它的会话里，所以一个会话的 Token 包含它的子 agent 做的工作。
- 额度属于账户。 两台 Mac 登录同一个账户，读到的是同一组窗口，iPhone 上这个账户只出现一次，用最新的读数。Token 历史则留在做了这些工作的那台 Mac 上。
- Cursor 的用量来自你的 Cursor 账户，所以也包含在其他电脑上做的工作。
- 变灰的额度是读数不正常，或者重置时间已过，直到下一次读数前都保持灰色。
- 在 iPhone 与 Apple Watch 上，百分比一律表示已用比例。
为什么消息没有送到另一个 agent
Agent 互发消息需要打开允许 agent 互发消息、在发信的 agent 里新开会话，并且收信的会话有一条进去的路。发信方会得到哪些说明、各自怎么办，见 Agent 互发消息 中的「消息没有送到时」。
怎样获得帮助
- 报告问题或提问：在 GitHub issues 里提出。写明你用的 Agent HUD 与 macOS 版本、涉及哪个 agent，以及你原本期望看到什么。
- 发邮件到 support@agenthud.app：订阅相关的问题，或者你不想公开发布的内容。
最后更新于