OMX HUD 双层级状态栏实战指南：从 Codex 内置 status_line 到 `omx hud` 编排状态监控

OMX（Oh My codeX）的 HUD 是一套"双层状态栏"体系：第一层复用 Codex CLI 内置的 TUI 底部状态栏（statusLine），实时展示模型、Git 分支与上下文用量；第二层由 omx hud 命令读取 .omx/state/ 下的编排状态文件，将 ralph、ultrawork、autopilot、team、pipeline 等高级工作流的运行状态聚合到一行可读性极强的状态行中。本文以 skills/hud/SKILL.md 为主线，结合 src/hud/ 与 src/config/ 的源码实现，完整讲解 HUD 的两层架构、三种预设、配置项、颜色编码与故障排查，让你能在自己的仓库里一键开启并定制这套监控面板。

一、架构总览：为什么是"两层"

OMX HUD 将"看得见 Codex"与"看得见 OMX"两件事拆开，各司其职：

1. Layer 1 —— Codex 内置 statusLine：由 Codex CLI 原生渲染的 TUI 页脚，展示模型、Git 分支、上下文用量等实时信息。通过 ~/.codex/config.toml 中的 [tui] status_line 配置，零代码即可生效。
2. Layer 2 —— omx hud CLI 命令：展示 OMX 专属的编排状态（ralph、ultrawork、autopilot、team、pipeline、ecomode、turns 等），数据来自仓库内 .omx/state/ 目录的状态文件。

两层各司其职：Layer 1 负责"Codex 会话本身"的可见性，Layer 2 负责"OMX 驱动的高级工作流"的可见性。从源码结构看，omx hud 的命令入口在 src/hud/index.ts，而 Codex 侧 statusLine 的生成逻辑在 src/config/generator.ts 中统一管理。

二、快速命令一览

omx hud 支持以下子命令形态（与 src/hud/index.ts 中的 HUD_USAGE 完全一致）：

命令	说明
omx hud	显示当前 HUD（模式、turns、活动状态）
omx hud --watch	实时刷新显示（每 1 秒轮询一次）
omx hud --json	输出原始状态 JSON，便于脚本消费
omx hud --preset=minimal	最小化显示
omx hud --preset=focused	默认显示
omx hud --preset=full	显示全部元素
omx hud --tmux	在 tmux 分屏面板中打开 HUD（自动检测方向）
omx hud --reconcile-tmux	触发 tmux HUD 面板的一致性收敛（内部命令）

--help/-h 会直接打印上述用法。命令行参数解析位于 src/hud/index.ts 的 parseFlags：--watch（别名 -w）、--json、--tmux、--preset= 均被逐一识别，其中 preset 仅接受 minimal、focused、full 三个合法值，其余值会被静默忽略并回落到配置默认值。

三、快速配置：omx setup 一键完成

运行 omx setup 会自动完成两层的配置：

• 在 ~/.codex/config.toml 中添加 [tui] status_line（Layer 1）；
• 写入 .omx/hud-config.json，默认 preset 为 focused（Layer 2）；
• 默认 preset 为 focused；如果 HUD/状态栏变化没有立刻出现，请重启一次 Codex CLI。

换句话说，从零到可用只需两步：执行 omx setup，然后重启 Codex CLI。hud-config.json 与 [tui] 段的写入/管理逻辑分别落在 src/hud/state.ts（读取与归一化）与 src/config/generator.ts（statusLine 生成与 upsert）。

四、Layer 1：Codex 内置 StatusLine

4.1 配置方式

在 ~/.codex/config.toml 中配置：

[tui]
status_line = ["model-with-reasoning", "git-branch", "context-remaining"]

这是 Codex CLI 原生能力，OMX 只是帮你把这段配置写进去，因此"零代码、零运行时开销"。

4.2 可用内置字段（Codex CLI v0.101.0+）

以下字段均可放入 status_line 数组：

model-name、model-with-reasoning、current-dir、project-root、git-branch、context-remaining、context-used、five-hour-limit、weekly-limit、codex-version、context-window-size、used-tokens、total-input-tokens、total-output-tokens、session-id

4.3 源码视角：OMX 如何管理这段配置

在 src/config/generator.ts 中，OMX 定义了与 HUD 预设一一对应的 statusLine 字段组合：

• minimal：["model-with-reasoning", "git-branch"]
• focused：["model-with-reasoning", "git-branch", "context-remaining", "total-input-tokens", "total-output-tokens", "five-hour-limit", "weekly-limit"]（共 7 个字段）
• full：当前与 focused 相同，为未来 Codex CLI 支持更多 status_line 字段预留（源码注释明确说明这一保留意图）

写入时 OMX 会在 status_line 上方插入标记注释 # omx:managed-status-line。这一标记用于区分"OMX 托管的配置"与"用户手工编辑过的配置"：升级或切换预设时，只有带标记（或匹配旧版安装遗留的 7 字段字面量）的行才会被 OMX 改写；用户自行修改过的 status_line 会被识别为用户定制并保留。从源码可以推断，这套标记机制保证了 omx setup 的幂等性与对用户手工配置的尊重。

五、Layer 2：OMX 编排 HUD

omx hud 命令聚合读取以下状态文件（列表来自 skills/hud/SKILL.md）：

• .omx/state/ralph-state.json —— Ralph 循环迭代进度
• .omx/state/ultrawork-state.json —— Ultrawork 模式
• .omx/state/autopilot-state.json —— Autopilot 阶段
• .omx/state/team-state.json —— Team 工作进程
• .omx/state/pipeline-state.json —— Pipeline 阶段
• .omx/state/ecomode-state.json —— Ecomode 是否激活
• .omx/state/hud-state.json —— 最近活动时间（由 notify hook 写入）
• .omx/metrics.json —— 轮次计数

在实现层面，src/hud/state.ts 的 readAllState 通过 readAuthoritativeModeState 按当前会话 ID 解析各 <mode>-state.json 的路径（getStateFilePath，见 src/mcp/state-paths.ts），并额外聚合了 current-autopilot.json、skill 活动状态（readVisibleSkillActiveStateForStateDir）、subagent 跟踪、GitGuardex finish-runs 事件流以及 Rust 运行时桥的 snapshot.json，最终组装成一个完整的 HudRenderContext。这意味着 HUD 不仅能显示文档中列出的八类状态文件，还能把 ultraqa、code-review、ultragoal、ralplan、deep-interview、autoresearch 等更细粒度的运行阶段纳入同一渲染上下文。

5.1 渲染管线

渲染入口是 src/hud/render.ts 的 renderHud：它根据预设选择一组"元素渲染器"（ElementRenderer），逐一从 HudRenderContext 中取值，过滤掉空项后用 | 分隔符拼接为一行（必要时按终端宽度自动换行、截断并保留 ANSI 颜色）。状态行的标签形如 [OMX#版本号]，例如 [OMX] 或 [OMX0.21.2]（版本号去掉前导 v）。

每个模式都有专属的渲染器，对应不同的显示语义：

渲染器	显示形态	颜色
renderRalph	ralph:3/10	绿/黄/红（按进度）
renderUltrawork	ultrawork	青色
renderAutopilot	autopilot:execution	黄色
renderRalplan	ralplan:2/2 或 ralplan:phase	青色
renderDeepInterview	interview:phase（输入锁定时追加 :lock）	黄色
renderAutoresearch	research:phase	青色
renderCodeReview	code-review:phase	绿色
renderUltraqa	qa:phase	绿色
renderTeam	team:3 workers	绿色
renderUltragoal	ultragoal 2/5 ▶ goal: 标题	青色进度、品红目标
renderGuardexFinish	gx:1/3 review（含旋转动画）	黄色
renderTurns / renderTokens / renderQuota / renderLastActivity / renderSessionDuration / renderTotalTurns	轮次、token、配额、最近活动、会话时长、总轮次	暗色（dim）

六、三种预设详解

minimal

[OMX] ralph:3/10 | turns:42

对应 src/hud/render.ts 的 MINIMAL_ELEMENTS：只显示 Git 分支、Guardex、ralph、ultrawork、ralplan、deep-interview、autoresearch、code-review、ultraqa、执行摘要（team/ultragoal）、stale autopilot 与 turns，不含 token、配额、会话时长等"软信息"，适合空间紧张的窄窗口。

focused（默认）

[OMX] ralph:3/10 | ultrawork | team:3 workers | turns:42 | last:5s ago

对应 FOCUSED_ELEMENTS，在 minimal 基础上增加 renderAutopilot、renderTokens、renderQuota、renderSessionDuration、renderLastActivity，是开箱即用的默认形态。

full

[OMX] ralph:3/10 | ultrawork | autopilot:execution | team:3 workers | pipeline:exec | turns:42 | last:5s ago | total-turns:156

对应 FULL_ELEMENTS，是元素最全的预设，在 focused 基础上追加 renderTotalTurns（累计总轮次），适合需要完整审计信息的大屏监控。

提示：三个预设的元素集合由 getElements(preset) 按名称选择，任何未知预设都会回落到 focused。另需注意，即使没有工作流运行，HUD 也会显示 Git 分支等基础信息；只有在所有模式都未激活时，才会渲染 No active modes. 占位文案。

七、HUD 配置文件 .omx/hud-config.json

配置存储于仓库根目录的 .omx/hud-config.json，SKILL.md 给出的最小示例：

{
  "preset": "focused"
}

结合 src/hud/types.ts 的类型定义与 src/hud/state.ts 的 normalizeHudConfig，完整可用的配置结构如下：

{
  "preset": "focused",
  "git": {
    "display": "repo-branch",
    "remoteName": "origin",
    "repoLabel": "my-repo"
  },
  "statusLine": {
    "preset": "focused"
  },
  "guardex": {
    "enabled": false
  }
}

各字段说明（源码 DEFAULT_HUD_CONFIG 中的默认值见 src/hud/types.ts）：

• preset：HUD 渲染预设，合法值为 minimal / focused / full，默认 focused；
• git.display：Git 分支显示方式，branch（仅分支名）或 repo-branch（仓库名/分支名），默认 repo-branch；
• git.remoteName：用于提取仓库名的 remote 名称，缺省时依次尝试配置值、origin、第一个可用 remote，最后回落到工作树目录名（对应 src/hud/state.ts 的 resolveRepoLabel）；
• git.repoLabel：显式指定的仓库显示名，优先级最高；
• statusLine.preset：Layer 1 Codex statusLine 使用的预设，默认 focused；
• guardex.enabled：是否读取 GitGuardex gx branch finish 进度到 HUD，默认 false。

归一化逻辑对每个字段都做了合法性校验（isValidPreset、isValidGitDisplay），非法值会被静默丢弃并回落到默认值，因此配置文件"写坏了也不会崩"，容错性较强。

八、高级用法：watch、json 与 tmux

8.1 --watch：实时轮询

omx hud --watch 以 1 秒为间隔轮询重绘，每次渲染前清屏，退出时恢复光标并清屏（对应 src/hud/index.ts 的 watchRenderLoop/runWatchMode）。实现细节包括：

• TTY 要求：非 TTY 且非 CI 环境下会直接报错退出（HUD watch mode requires a TTY）；
• 1s 节流：渲染耗时超过 1 秒时自动跳过堆积帧（inFlight/queued 双标志），避免渲染堆积；
• 会话感知：通过 isHudWatchSessionAttached 判断当前 tmux 会话是否还有客户端附着；分离状态下跳过纯渲染工作，仅继续执行 authority tick 与拓扑收敛（对应 issue #3577 的修复）；
• cwd 跟随：resolveHudWatchCwd 会对比启动目录与进程实时 cwd，若目录被重命名或复用，会跟随实时 cwd 读取状态，避免显示过期会话的数据。

8.2 --json：机器可读输出

omx hud --json 输出完整 HudRenderContext 的 JSON 序列化（2 空格缩进），包含 version、gitBranch、各模式状态、metrics、hudNotify、session 等全部字段，便于脚本（如 statusbar 工具、CI 巡检）二次消费。

8.3 --tmux：分屏面板 HUD

omx hud --tmux 会在当前 tmux 窗口下方开一个独立面板持续运行 hud --watch：

• 前置条件：必须在 tmux 会话内执行，否则报错 Not inside a tmux session；
• 面板高度：默认 2 行（HUD_TMUX_HEIGHT_LINES），ultragoal 激活时自动扩到 3 行（HUD_TMUX_ULTRAGOAL_HEIGHT_LINES），见 src/hud/constants.ts；
• 防重复：同一 leader 面板/session 已存在 HUD 面板时会复用并清理重复面板（listCurrentWindowHudPaneIds + killTmuxPane）；
• 拥挤窗口保护：窗口高度不足 45 行时不强行分屏（HUD_TMUX_MIN_LAUNCH_WINDOW_HEIGHT_LINES，对应 issue #2754），避免挤占 Codex TUI 的可读空间；
• 退出方式：在 HUD 面板内按 Ctrl+C，或执行 tmux kill-pane -t bottom；
• 一致性收敛：--reconcile-tmux 模式在每次 prompt 提交后校验面板拓扑、高度与 resize 钩子，确保 HUD 面板始终贴合当前渲染行数。

面板命令通过 execFileSync('tmux', args) 以 argv 数组传递（不经 shell），cwd 与 omxBin 均做了转义，降低了命令注入风险（见 buildTmuxSplitArgs 的防御性注释）。

九、颜色编码：一眼识别健康度

HUD 的颜色语义以"ralph 迭代进度"为核心（阈值计算见 src/hud/colors.ts 的 getRalphColor）：

• 绿色：正常/健康。ralph 迭代未超过 max 的 70%；同时 team、code-review、ultraqa、git 分支等常规信息也使用绿色/青色系；
• 黄色：警告。ralph 迭代超过 max 的 70%（Math.floor(max * 0.7)）；autopilot、deep-interview、guardex 等"进行中"状态同样使用黄色；
• 红色：临界。ralph 迭代超过 max 的 90%（Math.floor(max * 0.9)）。

实现上颜色通过 ANSI 转义码注入（\x1b[31m 等），渲染器在拼接时保留颜色、在计算可见宽度时剥离 ANSI 序列（stripAnsi），保证截断/换行不会破坏颜色状态或数错宽度。非彩色终端（isColorEnabled() 为假）下会退化为纯文本输出。

十、故障排查

问题一：TUI 状态栏（Layer 1）不显示

1. 确认安装了 Codex CLI v0.101.0 及以上版本（内置 statusLine 字段在此版本起可用）；
2. 运行 omx setup 配置 [tui] 段；
3. 重启 Codex CLI，让 TUI 重新加载配置。

如果仍不生效，可检查 ~/.codex/config.toml 中 status_line 是否带 # omx:managed-status-line 标记、字段名是否在 4.2 节列出的合法集合内。

问题二：omx hud 显示 "No active modes."

• 这是预期行为：当前没有任何工作流在运行；
• 启动一个工作流（如 ralph、autopilot、team、ultragoal）后再查看，对应模式的状态便会出现在 HUD 中。

问题三：watch 模式卡住或不刷新

• 确认终端是 TTY（非重定向/管道场景）；
• 若在 tmux 中使用 --watch，确认会话仍处于附着状态（分离会话默认跳过渲染）；
• HUD 数据来自 .omx/state/ 下的 JSON 文件，确认工作流确实写入了状态文件且当前会话 ID 匹配。

十一、源码地图：继续深入

• 命令入口与参数解析：src/hud/index.ts
• 状态文件读取与聚合：src/hud/state.ts
• 渲染器与预设元素集合：src/hud/render.ts
• 类型定义与默认配置：src/hud/types.ts
• ANSI 颜色与阈值：src/hud/colors.ts
• tmux 面板高度/窗口保护常量：src/hud/constants.ts
• tmux 面板注入与一致性收敛：src/hud/tmux.ts、src/hud/reconcile.ts
• Layer 1 statusLine 生成与标记管理：src/config/generator.ts
• 测试覆盖：src/hud/tests/（渲染、状态、watch、tmux 注入、资源泄漏、detached 会话等场景）

OMX HUD 的价值在于把"Codex 会话内"与"OMX 工作流内"两类状态放进同一个视觉框架：上层的 TUI 页脚由 Codex 原生渲染、零开销；下层的 omx hud 状态行则把 ralph 迭代、team 并发、autopilot 阶段等关键编排信息压缩成一行随时可读的监控视图。无论是日常开发时的轻量巡检，还是长任务运行时的 tmux 分屏盯盘，这套双层方案都能用最小成本把"代码助手正在做什么"讲清楚。