# 问题排查

[Agent HUD 文档](https://agenthud.app/docs/zh/)

Agent HUD 在 Mac、iPhone 与 Apple Watch 上的常见问题：各自的原因，以及怎样解决。

更新于 2026-10-28

下面每个问题先说原因，再说解决办法。没有找到你的问题时，见最后的「怎样获得帮助」。

## 为什么请求没有出现在 HUD 上

请求经由各 agent 自己设置里的回调来到 HUD，而 Agent HUD 只在你要求时才写入这些回调。

1. **客户端回调没有打开。** 在你打开之前，它一直是关着的：**设置 → 通用 → 客户端 → 客户端回调**。
2. **Agent HUD 不在「应用程序」里。** 只有位于 `/Applications/Agent HUD.app` 的 Agent HUD 才能安装客户端回调；从别处打开时，这个开关不可用。把应用移到「应用程序」，再从那里打开。
3. **Agent HUD 没有运行。** 这时各个 agent 照常在自己的窗口里询问。
4. **这个 agent 不发请求。** 只有部分 agent 会发，有些还需要额外的一步：Codex 要先信任它的回调（见下一个问题），DeepSeek Harness 要在**设置 → 智能体插件**里装上 Agent HUD 的插件。见[客户端回调](https://agenthud.app/docs/zh/agents/hooks/)。

你没有处理的请求，过了**等待回答**设定的时间就交还 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，前提是两者已经配对。

1. **共享没有打开。** 在 Mac 上打开**设置 → 局域网 → 局域网共享**。在你打开之前，它一直是关着的。
2. **邀请已过期。** 邀请只能用一次，五分钟后失效。再点一次**创建邀请**，扫描新的二维码。
3. **两台设备不在同一个网络。** 让 iPhone 和 Mac 连接同一个 Wi-Fi。离开这个网络时，iPhone 需要 [Agent HUD Remote](https://agenthud.app/docs/zh/phone/remote/)。
4. **iOS 拦住了连接。** 在 iPhone 的**设置 → 隐私与安全性 → 本地网络**里允许 Agent HUD。
5. **配对已被撤销。** Mac 上点过**撤销已配对设备**之后，iPhone 会请你重新扫描这台 Mac 的配对码。
6. **有一端的应用太旧。** iPhone 提示请更新两台设备上的 Agent HUD 时，把两边都更新。

Mac 上的 Agent HUD 要在运行，iPhone 才能读到它。

## 为什么 Remote 不更新

Remote 的一切都经由你的 iCloud 传递。Mac 大约每 30 秒发送一次用量与会话，请求与提醒则立即发送。

1. **Apple 账户不同。** Mac 和 iPhone 必须登录同一个 Apple 账户。
2. **Mac 上没有打开 Remote。** 打开**设置 → 远程 → Agent HUD Remote**。
3. **这台 Mac 没有名额。** 在**设置 → 订阅**里，**Agent HUD Remote** 这一行应当写着 App Store。如果写着「本机尚未启用」，点**使用 App Store 名额**。名额都用完时，先移除另一台 Mac。
4. **Mac 上的 Agent HUD 没有运行**，或者 Mac 在睡眠。它再次运行之前，什么都不会发出。
5. **iCloud 储存空间已满。** iCloud 拒收新的记录，Mac 每小时重试一次。清理出 iCloud 空间即可。
6. **订阅已结束。** iPhone 显示 **Agent HUD Remote 已到期**，以及它最后收到的数据。

Mac 的**设置 → 远程**在**状态**下显示 iCloud 连接情况、还在等待的保存，以及上次保存的时间。在 iPhone 的首页、统计或会话页下拉，即可重新读取 iCloud。

请求、对话与消息还需要同步之外的几项：打开**远程会话**与**共享对话**，打开客户端回调，以及 Agent HUD 的 Claude Code 插件。见 [Agent HUD Remote](https://agenthud.app/docs/zh/phone/remote/) 中的「Mac 需要什么」。

## 为什么数字看起来不对

多数意外来自一个数字到底算的是什么。

- **费用是估算**，按各厂商的标价计算，标有 ≈，不是实际扣费。某个模型的价格不对时，在**设置 → 价格**里改成你自己的。
- **Token 历史在 Mac 上保留 30 天**，更早的 Token 不再保留。
- **子 agent 算在开启它的会话里**，所以一个会话的 Token 包含它的子 agent 做的工作。
- **额度属于账户。** 两台 Mac 登录同一个账户，读到的是同一组窗口，iPhone 上这个账户只出现一次，用最新的读数。Token 历史则留在做了这些工作的那台 Mac 上。
- **Cursor 的用量来自你的 Cursor 账户**，所以也包含在其他电脑上做的工作。
- **变灰的额度**是读数不正常，或者重置时间已过，直到下一次读数前都保持灰色。
- **在 iPhone 与 Apple Watch 上**，百分比一律表示已用比例。

## 为什么消息没有送到另一个 agent

Agent 互发消息需要打开**允许 agent 互发消息**、在发信的 agent 里新开会话，并且收信的会话有一条进去的路。发信方会得到哪些说明、各自怎么办，见 [Agent 互发消息](https://agenthud.app/docs/zh/mcp/messaging/) 中的「消息没有送到时」。

## 怎样获得帮助

- **报告问题或提问**：在 [GitHub issues](https://github.com/jazzenchen/agent-hud-open/issues) 里提出。写明你用的 Agent HUD 与 macOS 版本、涉及哪个 agent，以及你原本期望看到什么。
- **发邮件**到 [support@agenthud.app](mailto:support@agenthud.app)：订阅相关的问题，或者你不想公开发布的内容。

---

English: https://agenthud.app/docs/en/troubleshooting/