1. Claude HUD 状态栏不显示，先别急着重装
Claude HUD 是一个给 Claude Code 加状态栏的插件，能在终端底部实时显示工具调用、子代理状态、待办进度、会话时长这些信息。适合经常跑长任务、开多个 Agent、需要一眼看清当前会话在干什么的人。它的工作方式不是独立进程，而是通过 Claude Code 的statusLine机制，把一段命令挂到状态栏上，由 Claude Code 在每次刷新时调用。
问题就出在这个「挂载」环节。很多人装完插件，/plugin界面里明明写着 Installed，可状态栏一片空白，运行/claude-hud:setup还报Unknown command。我实测下来，这类故障基本集中在三个地方：插件缓存被锁导致安装不完整、statusLine里写死了错误路径、以及插件命令需要完全重启才能加载。这三个原因经常同时出现，所以只修一个往往还是起不来。
这篇按排查顺序走一遍：先确认插件到底装没装全，再检查 Node.js 环境，然后给出可复制的settings.json配置骨架，最后用一条命令验证 HUD 能不能初始化。全程在 Windows 11 + Git Bash 环境下操作，Linux/macOS 只需把路径换成对应写法。
2. 前置准备：Node.js 环境与 TaoToken 接入
Claude HUD 本质是一个 Node.js 脚本，statusLine调用的就是node dist/index.js。所以第一件事是确认 Node.js 可用，而且路径要是 Git Bash 能识别的格式。
which node node --version正常输出类似：
/d/Program Files/nodejs/node v24.14.1注意这里是/d/Program Files/nodejs/node，不是D:\Program Files\nodejs\node.exe。Git Bash 下配置statusLine必须用前者，写反斜杠路径会直接导致命令执行失败，状态栏什么都不显示。
如果你还没配好 Claude Code 的模型接入，可以先用 TaoToken 把链路跑通。它提供兼容 Anthropic 的接口，Claude Code 里配置ANTHROPIC_BASE_URL指向https://taotoken.net/api即可。API Key 在控制台创建，接入文档里有各客户端的填写示例。这一步不影响 HUD 本身，但能保证你在排查时 Claude Code 是能正常对话的，避免把「模型不通」和「状态栏不显示」混在一起。
3. 可复制配置：settings.json 与 statusLine 骨架
先看插件到底装在哪。读取插件注册文件：
cat ~/.claude/plugins/installed_plugins.json你会看到类似结构：
{ "version": 2, "plugins": { "claude-hud@claude-hud": [ { "scope": "user", "installPath": "C:\\Users\\{USER}\\.claude\\plugins\\cache\\claude-hud\\claude-hud\\0.1.0", "version": "0.1.0", "installedAt": "2026-04-23T15:52:57.164Z" } ] } }这里有个坑：installPath用的是 Windows 反斜杠风格，但 Git Bash 里执行命令时这个路径不能直接用。真正要引用的是plugins/cache/claude-hud/claude-hud/0.1.0/这个目录，而且版本号会变，所以配置里不要硬编码版本。
打开~/.claude/settings.json，把statusLine换成下面这段。它做了四件事：取终端宽度、留出输入区内边距、动态查找最新版本插件目录、用 Node.js 执行入口文件。
{ "statusLine": { "type": "command", "command": "cols=$(stty size </dev/tty 2>/dev/null | awk '{print $2}'); export COLUMNS=$(( ${cols:-120} > 4 ? ${cols:-120} - 4 : 1 )); plugin_dir=$(ls -1d \"${CLAUDE_CONFIG_DIR:-$HOME/.claude}\"/plugins/cache/*/claude-hud/*/ 2>/dev/null | sort -V | tail -1); exec \"/d/Program Files/nodejs/node\" \"${plugin_dir}dist/index.js\"" } }几个关键点对照：
| 片段 | 作用 |
|---|---|
stty size </dev/tty | 从终端设备直接读行列数，比$COLUMNS可靠 |
export COLUMNS=...-4 | 减 4 是给 Claude Code 输入区留内边距，避免状态栏被截断 |
ls -1d .../plugins/cache/*/claude-hud/*/ | 通配匹配任意版本目录，不写死 0.1.0 |
sort -V | tail -1 | GNU 版本排序，保证 0.1.0 < 0.2.0，取最新 |
exec "/d/Program Files/nodejs/node" | Git Bash 风格路径，直接替换当前进程 |
注意：
sort -V依赖 GNU sort，Windows Git Bash 自带，但如果你在别的精简 shell 里跑，可能不支持-V，那就退回sort | tail -1，只是多版本共存时排序不精确。
4. 验证请求：一条命令确认 HUD 能初始化
配置写完后，不要急着开 Claude Code，先在 Git Bash 里手动跑一遍statusLine里的命令，看它能不能输出初始化信息。把上面command的值整段贴进终端执行：
cols=$(stty size </dev/tty 2>/dev/null | awk '{print $2}'); export COLUMNS=$(( ${cols:-120} > 4 ? ${cols:-120} - 4 : 1 )); plugin_dir=$(ls -1d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/*/claude-hud/*/ 2>/dev/null | sort -V | tail -1); exec "/d/Program Files/nodejs/node" "${plugin_dir}dist/index.js"如果输出：
[claude-hud] Initializing...说明插件入口、Node.js 路径、动态查找逻辑全部正常。这时候再启动 Claude Code，状态栏应该就能显示了。
如果这一步报Cannot find module，说明plugin_dir没匹配到，回去检查plugins/cache/下到底有没有claude-hud目录。如果报node: command not found，说明exec后面的 Node 路径写错了，用which node的输出替换。
5. 本篇常见错排查
5.1 Unknown command: /claude-hud:setup
插件显示 Installed，但命令不可用。原因是 Claude Code 的插件命令在启动时加载，安装插件后当前会话不会热更新。必须完全退出进程再重启，不是关窗口。重启后/claude-hud:setup才会出现。
5.2 EBUSY: resource busy or locked
首次安装失败时缓存目录被锁，installed_plugins.json里虽然有注册记录，但实际文件不完整。清理缓存后重装：
rm -rf "/c/Users/{USER}/.claude/plugins/cache/claude-hud"然后在 Claude Code 里重新/plugin install claude-hud，再完全退出重启。
5.3 状态栏空白但无报错
多半是statusLine里路径写死了旧的市场暂存路径，比如marketplaces/jarrodwatts-claude-hud/dist/index.js。这个目录在安装完成后可能已经不存在。换成第 3 节里动态查找plugins/cache/的写法即可。
5.4 配置写入后仍不生效
statusLine配置写入settings.json后，同样需要重启 Claude Code 才生效。这是第二次重启：第一次是装完插件，第二次是写完配置。两次都别省。
5.5 可选功能不显示
创建~/.claude/plugins/claude-hud/config.json控制显示项：
{ "display": { "showTools": true, "showAgents": true, "showTodos": true, "showDuration": true, "showConfigCounts": true, "showSessionName": true } }showTools控制工具活动行，showAgents控制子代理状态，showTodos控制待办进度，showDuration控制会话时长，showConfigCounts显示 CLAUDE.md/rules/MCP 计数，showSessionName显示会话名。改完同样重启。
6. 把链路固定下来
排查完这一轮，建议把几个路径记在便签里，下次出问题直接对号入座：settings.json在C:\Users\{USER}\.claude\settings.json，插件注册在plugins\installed_plugins.json，插件缓存在plugins\cache\claude-hud\claude-hud\0.1.0\，插件配置在plugins\claude-hud\config.json。
如果你在配 Claude Code 的模型接入时想少折腾，API Key 在控制台创建，接入文档里有 Claude Code 的ANTHROPIC_BASE_URL填写方式；想先验证模型通不通，可以直接在模型对话里发一条测试；长期跑编码和 Agent 任务的话，Coding Plan 的额度模型更适合挂后台。HUD 只是显示层，底层链路稳了，状态栏才有意义。
