如何5分钟安装并跑通Agent HUD:面向新手的最快上手指南

原创2026-11-20 19:51:511,932 阅读

如何5分钟安装并跑通Agent HUD:面向新手的最快上手指南

Agent HUD 是一款面向编程智能体(coding agent)的 HUD 状态面板工具,能一屏盯住 Claude Code、Codex 等 27+ 编码助手的额度(quota)、token 消耗与会话状态,支持 Mac、Windows、Linux 桌面端,还能同步到手机与手表。本文教你用最少的命令完成 Agent HUD 安装,5 分钟从零跑通第一个界面。

一、Agent HUD 是什么?新手先花10秒了解

简单说,Agent HUD 就像给屏幕加装了一个"驾驶舱仪表盘":你的编码 agent 在后台干活,屏幕边缘的小面板用颜色告诉你——绿色额度充足、黄色接近上限、红色即将用完;agent 需要批准操作时,你不必切回终端,直接在面板上点"允许一次"。

下面这张图是它的完整演示:Notch 模式下呼吸的光圈代表额度,悬停展开各 agent 的配额与 token 统计,agent 提出请求时直接在 HUD 上回答:

Agent HUD 安装后的主界面演示:MacBook 刘海处的额度光圈、悬停面板与请求审批

它是用 Tauri 2 构建的(Rust 内核 + React 界面),跨平台且轻量,详见 docs/platform-architecture.md。

二、安装前检查:3个环境条件

开始 Agent HUD 快速上手 前,先确认你的环境:

安装方式 需要 适合人群
官方命令安装(推荐) macOS 14+ / Windows / Linux x86_64,有 Node.js 绝大多数新手
Homebrew 安装 仅 Mac,已装 Homebrew Mac 用户
源码构建 Node.js 24+、pnpm、Rust 1.90+ 工具链 开发者

💡 前两种方式不需要任何编程基础,一条命令即可。

三、三步完成 Agent HUD 安装

3.1 macOS:一条 brew 命令装好

打开"终端",执行:

brew install --cask jazzenchen/tap/agent-hud

如果应用已经在 /Applications 里,加一个参数即可接管:

brew install --cask jazzenchen/tap/agent-hud --adopt

装完后 Mac 上的 Agent HUD 会自动更新自己。

3.2 Windows / Linux:npx 一键安装命令

只要有 Node.js,任意平台执行同一句命令:

npx @agenthud/install

它会从官方 release 自动下载对应系统的安装包(含测试版),并用 SHA256 校验后再安装。各系统实际发生的事:

  • macOS:把 Agent HUD.app 放入 /Applications,先校验 Developer ID 签名;
  • Windows:自动运行安装程序(注意目前为未签名的测试构建);
  • Linux x86_64:安装到 ~/Applications/Agent-HUD.AppImage(部分系统需要 FUSE 2,即 libfuse2)。

常用可选参数(完整说明见 src/apps/installer/README.md):

参数 作用
--release <version> 安装指定版本,而不是最新版
--dir <folder> 指定安装目录(Mac/Linux 无写权限时)
--no-open 安装完不自动打开应用

3.3 进阶:从源码构建自己的 Agent HUD

想参与贡献或尝鲜最新代码?按 README.md 的步骤:

git clone https://gitcode.com/gh_mirrors/ag/agent-hud-open
cd agent-hud-open
pnpm install
pnpm run check
pnpm run build:macos -- --bundle

Windows 和 Linux 分别改用 build:windows、build:linux,构建产物位于 target/release/bundle。没有装任何 agent 也能体验:加 --demo 启动,会直接用样例数据打开。

四、跑通验证:第一次启动后看什么

安装完成后打开 Agent HUD,按这个清单确认"跑通":

  1. 找到你的 agent:装好并登录过的编码工具(如 Claude Code、Codex)会被自动发现,HUD 面板上出现对应的"机器人"头像;
  2. 看颜色:光圈的绿/黄/红对应额度低于 70%、70%–90%、90% 以上;
  3. 试一次交互:agent 提出需要批准的请求时,在面板上直接 Approve / Deny;
  4. 打开统计窗口:查看 token 用量、成本与历史趋势。

Simple 模式则是悬浮在屏幕任意边缘的小面板,每个 agent 头像外圈就是它的额度环:

Agent HUD 安装后的 Simple 模式:屏幕边缘的 agent 额度环面板

没有 agent 在手?源码构建加 --demo,或直接看下面两张统计窗口的样例数据效果:

Agent HUD 统计窗口:年度 token 用量、成本估算与会话热力图

Agent HUD 会话详情:单轮对话的 sub-agent 时间线与工具调用

五、装完还能解锁什么

  • 手机端同步:同一网络下,iPhone/Apple Watch 免费查看桌面端的额度、统计与会话;
  • agent 互发消息:内置 MCP 服务让 Claude Code 修完代码后让 Codex 帮忙 review,详见 docs/agent-messages.md;
  • 自定义 HUD:通过 MCP 工具让 agent 自己调整面板布局与展示内容。

手机端统计效果(iPhone Duo 展开屏示例):

Agent HUD 手机端:iPhone Duo 上的 token 统计面板

六、新手常见问题 FAQ

Q1:安装后面板没出现? 检查 Settings → Display,可以为每块屏幕单独开关 HUD、消息与请求;Notch 模式只在有刘海的 Mac 上默认可用,其他屏幕请用 Simple 模式。

Q2:Windows/Linux 版本能用吗? 可以,但目前是未签名的测试构建(preview),功能以 docs/platforms.md 的对照表为准;macOS 是功能最完整的正式平台。

Q3:会上传我的数据吗? 不会。会话记录只读你本机已有的文件,用量历史存在本地 SQLite 数据库;从这个源码构建的应用不上传任何数据。

Q4:如何更新? Mac 上自动更新;Windows/Linux 重新执行一次 npx @agenthud/install 即可。

Q5:语言能切中文吗? 可以,Settings → General → Language,支持简中、繁中、日、韩等 9 种语言。

总结

步骤 命令/操作 耗时
1. 安装 npx @agenthud/install(或 brew 命令) 约 2 分钟
2. 打开应用 自动弹出或从程序列表启动 10 秒
3. 确认 agent 被识别 看 HUD 面板上的头像与光圈 1 分钟
4. 打开统计窗口 查看 token 与成本 1 分钟

全程不超过 5 分钟。Agent HUD 安装完成后,它几乎不占资源(空闲时约 7% 单核 CPU),安静地守在屏幕边缘,让你的编码 agent 状态从此一目了然。

登录后查看全文
agent-hud-open