# 客户端回调

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

Agent HUD 往各 agent 的设置里写了什么来接收请求与回复，怎样打开，怎样在 Codex 里审核，以及怎样全部移除。

更新于 2026-10-28

客户端回调是 agent 自己设置里的一小段条目：agent 请求权限、向你提问或结束一轮时，它会运行 Agent HUD。打开客户端回调后，这些请求会在 HUD 上等你回应，一轮结束时出现**有新回复**提醒。Token、额度与会话从不依赖它。

> **默认关闭**
>
> 客户端回调默认关闭。只有装在「应用程序」里的 Agent HUD 才能打开它。

## 打开客户端回调

确认 Agent HUD 是从「应用程序」文件夹运行的。从其他位置启动的副本里，这个开关是灰色的。

打开**设置 → 通用**，打开**客户端回调**。开关下方的说明会变为「客户端回调已安装。」

如果你用 Codex CLI，在 Codex 里信任 Agent HUD 的回调，见下文「Codex 会审核新的回调」。

![设置 → 通用的「客户端」一节：客户端回调已打开，等待回答为 10 分钟](https://agenthud.app/docs/images/settings/general-clients.zh.webp)

开关下方的**等待回答**决定一个请求在 HUD 上等多久，到时交还 agent：1、3、5、10、30 或 60 分钟，默认 10 分钟。怎样回应请求，见[请求](https://agenthud.app/docs/zh/hud/requests/)。

## Agent HUD 写入什么、何时写入

打开客户端回调时，以及之后每次启动时，Agent HUD 为它在这台 Mac 上找到的每个受支持的 agent 写入回调。每条命令都指向「应用程序」里的这个应用。它把自己的条目加在你原有的回调旁边，从不改动原有的条目，移除时也只移除自己的。

| Agent | 位置（默认路径） | 带来什么 |
| --- | --- | --- |
| Claude Code | `~/.claude/settings.json` | 工具调用、提问与计划；会话的等待状态 |
| Codex | `~/.codex/hooks.json` | CLI 的工具调用，你信任回调之后才有 |
| Qoder、Qoder CN、QoderWork | `~/.qoder/settings.json`、`~/.qoder-cn/settings.json`、`~/.qoderwork/settings.json` | 工具调用 |
| CodeBuddy | `~/.codebuddy/settings.json` | 工具调用与回复 |
| WorkBuddy | `~/.workbuddy/settings.json` | 工具调用 |
| Qwen Code | `~/.qwen/settings.json` | 工具调用与回复 |
| Devin CLI | `~/.config/devin/config.json` | 工具调用与回复 |
| ZCode | `~/.zcode/cli/config.json` | 工具调用与提问 |
| Antigravity | `~/.gemini/config/hooks.json` | 回复 |
| Cursor | `~/.cursor/hooks.json` | 回复，以及每次生成的 Token |
| GitHub Copilot CLI | `~/.copilot/hooks/agent-hud.json` | 回复 |
| Pi | 一个扩展：`~/.pi/agent/extensions/agent-hud.ts` | 实时状态与回复 |
| OpenCode | OpenCode 插件文件夹里的一个插件 | 回复 |

agent 自己的目录设置，比如 `CLAUDE_CONFIG_DIR` 或 `CODEX_HOME`，会改变对应文件的位置。另有三条通道不写入任何内容，同样只在客户端回调打开时运行：

- **Codex 桌面版**：它自己的批准请求与提问，经由运行中的 Codex 桌面版的本机通道送来。
- **Antigravity**：工具批准请求与提问来自运行中的 Antigravity 桌面版的本机服务。
- **DeepSeek Harness**：提问与批准请求经由 Agent HUD 的 Harness 插件送来，这个插件需要你自己安装（见下文）。

ZCode 只在它自己的回调设置打开时运行回调。这项设置缺失时，Agent HUD 写入回调的同时把它打开；如果是你自己关掉的，Agent HUD 保持关闭。

## Codex 会审核新的回调

Codex 只运行你审核并信任过的回调。信任和回调的具体定义绑定在一起，所以任何新的或改动过的条目，Codex 都会标为待审核并跳过它，直到你信任为止；HUD 上不会有任何提示。Agent HUD 第一次写入回调时也是如此。

在终端里启动 Codex CLI。有回调需要审核时，Codex 会在启动时给出提示。

运行 `/hooks`。

查看 Agent HUD 的条目并信任它们。

因为只有「应用程序」里的副本会写入回调，它们的命令在更新前后保持不变，审核一次就够了。

即使已经信任，这个回调也只送来由你本人审核的那些轮次。交给 Codex 自动审核的请求留在 Codex 里。

## Agent HUD 没有运行时

退出 Agent HUD 后，回调仍留在各 agent 的设置里。agent 每次运行它时，找不到应用，就不作回答直接退出，agent 照常在自己的窗口里询问。不会有任何请求被替你作答。

## 需要你自己打开的附加项

下面这些和客户端回调无关，只在你要求时添加，也在同一个地方移除。

| 附加项 | 位置 | 写入什么 |
| --- | --- | --- |
| Claude Code 的 Agent HUD 插件 | **设置 → 智能体插件 → Claude Code** | 一个 Claude Code 插件，用 Claude Code 自己的插件命令安装。它把你对 Claude 桌面版里提问的回答送回去（**回答提问**），也负责 Agent HUD 发给 Claude Code 会话的消息 |
| DeepSeek Harness 的 Agent HUD 插件 | **设置 → 智能体插件 → DeepSeek Harness** | 在 Harness 的补丁文件 `~/.dsh/cordis.patch.yml` 里写入一个模块和一行带标记的条目，把 Harness 的提问与批准请求带到 HUD |
| HUD 工具 | **设置 → 智能体插件**，适用于 Claude Code、Codex、Cursor、DeepSeek Harness 与 Antigravity | 在 agent 的 MCP 配置里加入名为 `agent-hud` 的 Agent HUD MCP 服务，外加一个 skill。只能从「应用程序」里的副本添加。见[内置 MCP](https://agenthud.app/docs/zh/mcp/) |
| Antigravity CLI 额度回调 | **设置 → 智能体 → Antigravity → Antigravity CLI 账户** | 在 CLI 的状态栏旁加一个本地额度回调，原有状态栏保持不变。见[额度与余额](https://agenthud.app/docs/zh/agents/quotas/) |
| 远程会话 | 有 Agent HUD Remote 时，在**设置 → 远程 → 远程会话** | 在 Claude Code 与 Codex 的设置里再加一段回调，用于每轮的提示与结束，让手机上的对话保持最新。Codex 会像审核其他回调一样审核它。见 [Agent HUD Remote](https://agenthud.app/docs/zh/phone/remote/) |

启动时，Agent HUD 还会在 Claude Code 的 `~/.claude.json` 里把 `~/.agenthud/sessions/claude` 这一个文件夹标为已信任，这样从 Agent HUD 新建的、不属于任何项目的会话可以在那里运行。它不改动其他条目；没有安装 Claude Code 时不写入任何内容。

## 关闭客户端回调

在**设置 → 通用**中关闭**客户端回调**。Agent HUD 随即移除它的回调、Pi 的扩展与 OpenCode 的插件，之后也不再写回。

- 请求回到各个 agent 自己的窗口。
- 靠回调、扩展或插件上报回复的 agent 不再有回复提醒，Pi 的实时状态也随之停止。
- Cursor 的 Token 不再记录。
- Token、额度、会话及其历史保持不变。

## 全部移除

在**设置 → 通用**中关闭**客户端回调**。

在**设置 → 智能体插件**中移除你添加过的插件与 HUD 工具。

在**设置 → 智能体 → Antigravity** 中清空 **Antigravity CLI 账户**，再点**连接账户**，恢复各 CLI 原有的状态栏。

如果你用 Agent HUD Remote，在**设置 → 远程**中关闭**远程会话**。

退出 Agent HUD，把它移到废纸篓。

请在删除应用之前完成这些步骤。只删除应用，回调仍留在各 agent 的设置里，指向一个已经不存在的应用。

---

English: https://agenthud.app/docs/en/agents/hooks/