Omarchy 顶栏 Agents 面板指南集中监控 Claude Code、Codex 与 Fireworks 的订阅额度与用量【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchyOmarchy 是一个「美丽、现代且高度定制化」的 Linux 桌面环境。其内置的omarchy.agents插件AI 订阅用量面板为每台机器上每一个已安装的 AI 编码订阅Claude Code、Codex、Fireworks 等提供一个顶栏图标与一个原生面板让你随时掌握额度消耗、节奏pace、今日用量、最近一周趋势与全量模型消耗而无需打开各家控制台。读完本文你将掌握该插件的界面语义、底层数据管线、配置方式、跨设备同步方案以及如何为新的 AI 编码代理扩展出面板标签。插件的核心设计面板只负责「展示」omarchy.agents面板在架构上被刻意设计成一个纯展示层。根据 插件 README 的说明面板只监视omarchy-agent-usage-update命令写入~/.local/state/omarchy/agents/usage/目录的用量记录然后把里面出现的内容原样画出来——它从不直接解析 CLI 的磁盘格式也从不直接调用各家远程 API。这套「数据采集与展示解耦」的架构由三个 QML 文件 一个更新命令协同实现Panel.qml 拥有顶栏按钮与弹出面板负责 UI 交互与渲染Main.qml 负责发现并监视记录文件同时处理可选的跨设备汇总sync以及定时刷新逻辑Agent.qml 是单个记录文件的 watcher——用FileView监视一个 JSON 文件的变化文件更新就重新解析omarchy-agent-usage-update 是写入者它为每个 agent 运行一个omarchy-agent-usage-agent采集器把各采集器打印的标准 JSON 原子地写入 usage 目录。Main.qml的注释点明了这一分工的关键收益见 Main.qml所有提取逻辑都藏在omarchy-agent-usage-update背后界面只做「发现记录、监视变化、合并快照」三件事。因此新增一个 agent 永远不会改动这个插件本身——只要新增一个采集器脚本面板就自动获得一个标签页。Agent.qml的实现进一步印证了这点面板并不知道数字是怎么算出来的「只要出现在 usage 目录里的记录就是一个 agent无论它由谁写入」见 Agent.qml。面板界面逐块拆解面板被设计成一个信息密度较高的「仪表盘」打开即可阅读限额和历史尽量无需滚动见 Panel.qml。从上到下各区块如下Hero身份区显示订阅方的mark徽标、工具名称与当前运行的订阅计划例如 Max 20x、Pro。认证或端点问题发生时计划行会被替换为状态说明文字并额外以卡片形式重复展示一次authHelpText。Hero 的 meta 行逻辑在 Panel.qml 的 heroMeta()当usageStatusText非空时优先展示状态否则展示tierLabel计划名。计划名的来源值得注意Claude 采集器会把登录凭据里的rateLimitTier/subscriptionType规整成可读标签——例如从 tier 字符串max_20x解析出 Max 20x见 omarchy-agent-usage-claude 的 plan_label()而 Fireworks 直接固定标注tierLabel: Prepaid见 omarchy-agent-usage-fireworks。订阅切换Subscription switch每个已启用的 agent 对应一个 chip用h/l或点击切换。它只在启用了一个以上 agent 时出现见 Panel.qml。只有一个订阅时不会显示切换行一个都没有时整个模块会从顶栏消失而不是放一个空荡荡的图标在那里。这就是文档所说的「宁可消失、绝不空置」原则。额度Limits展示每个额度窗口的已用百分比、对应计量条Meter以及会话/周窗口重置的倒计时。两端口的窗口语义差异在面板中被归一化Claude 把它写成 Session (5-hour)、Codex 缩写为 5h window/30m window面板通过 windowIsLong() / windowTitle() 统一识别为 Session/Weekly/Monthly 三种形态。比例 0.9即用掉 90%的行会被标记为警示色alarming见 Panel.qml LimitRow。每行下方还会显示 Resets in Xd Yh / Xh Ym 之类的倒计时resetMsFor() / formatDuration()。余额Balance预付费prepaid类 agent目前即 Fireworks不报告 rate-limit 窗口而是报告一个信用卡台账credit ledger剩余信用额、一根越用越空的「油量表」、以及 funded-versus-spent已充值 vs 已花费明细。余额仪表的警示阈值是剩余低于充值的 10%见 Panel.qml。余额明细文本在 balanceDetailText() 中生成例如 $5.20 spent of $20.00 funded · estimated——当余额是估算值时会额外标注 · estimated。按天 Token 用量Tokens by day最近 7 天每天一行星期几、比例条、token 数今天的行加粗放在最底部并高亮见 Panel.qml DayRow。把鼠标悬停在今天上可以看到该日的prompt 数与 session 数见 dayTooltip()。比例条以一周中最忙的一天为基准缩放scale-to-peak。按模型 Token 用量Tokens by model按模型列出 token 消耗每一行背后的比例条以最重的模型为基准缩放与周图以最忙日缩放是同一套逻辑见 Panel.qml ModelRow。悬停可查看input / output / cache read / cache write的拆分modelTooltip()。模型行只显示用量最高的 4 个modelRows()并且模型 ID 会经过 friendlyModelName() 的美化把claude-opus-4-8、gpt-5.6-sol这类连字符 ID 重排为 Opus 4.8、GPT 5.6 Sol 这样易读的名字。数据目录与记录契约每个 agent 对应~/.local/state/omarchy/agents/usage/下的一个 JSON 记录文件由omarchy-agent-usage-update写入。update 脚本本身bin/omarchy-agent-usage-update非常透明遍历$OMARCHY_PATH/bin/omarchy-agent-usage-*下所有可执行采集器跳过update自己支持参数--force无视缓存强制重扫与重新探测额度、--limits-only只刷新远端额度、复用本地统计、--except agent跳过某 agent、以及末尾可指定的[agent...]白名单每个采集器并行运行各自先把输出写到mkstemp临时文件校验通过为合法 JSON 后再mv原子替换为agent.json避免面板读到半截文件。命令行对应的实际用法为omarchy:examples元数据见脚本头部注释omarchy agent usage-update # 刷新全部 omarchy agent usage-update claude # 只刷新 claude omarchy agent usage-update --except codex # 跳过 codex面板侧的数据流完全围绕这个目录展开Main.qml用find ... -name *.json做目录发现并用Instantiator为每个发现的 JSON 动态实例化一个 Agent.qml。Agent.qml内的FileView设置了watchChanges: true一旦文件落盘即触发解析若 JSON 解析失败则把record置空并打出警告见 Agent.qml。面板不关心是谁写了这些文件——这意味着哪怕你不用面板自带的刷新定时器只要别的工具往该目录投递了符合契约的记录面板同样会立即呈现。在面板打开 / 关闭与记录变化的驱动下Main.qml会周期性默认 900 秒触发一次omarchy-agent-usage-update用户按下刷新时则使用--force。此外打开面板时只触发一次--limits-only的refreshLimits()——因为用户此时想要的是会过时的远端数字而不是再对磁盘上每个 transcript 重新走一遍见 Main.qml refreshLimits() 及注释。一个值得注意的细节若某采集器在记录里写了retryAdvised典型的场景是登录后头几秒网络路由尚未就绪连不上远端Main.qml会在 30 秒后只对标记了该字段的 agent提早重试一次而不是把每个采集器都拖上 30 秒的循环见 Main.qml。各采集器的数据来源下表来自 插件 README概括了三个内置采集器的取数通道采集器Limits远端额度Local stats本地统计claudeAnthropic 的 OAuth usage endpoint5 小时会话窗口 7 天周窗口~/.claude/projectstranscripts、运行在 Anthropic provider 上的 opencode sessions外加stats-cache.json与history.jsonl兜底codexCodex app-server RPC原生 Codex CLI session 文件以及 pi、opencode 的 sessionsfireworks估算的预付费余额配置的 funding 减去按费率核算的账户开销Fireworks billing API按最近 30 天以天/模型分组Claude 采集器内部流程omarchy-agent-usage-claude 是本插件的取数样板。main()的组装顺序见其 main()展示了多层数据源是如何融合成一个记录的Transcript 扫描递归扫描~/.claude/projects下所有*.jsonl先做usage:的廉价行级预过滤只统计 assistant 消息按 message id 去重拆出 input/output/cacheRead/cacheWrite 四种 token 与模型归属兜底链路当 transcript 扫描结果为空时依次尝试stats-cache.json聚合计数器与history.jsonl按天的 prompt/session保证「磁盘上没有 transcript 的机器」仍能报出今日数据pi/omp 与 opencode 会话合并通过.pi/agent/sessions、.omp/agent/sessions与~/.local/share/opencode/opencode.db以只读 URI 方式打开 SQLite避免与正在写入的 opencode 冲突统计所有跑在 Anthropic provider 上的消息并merge_stats()合并进主记录额度探测从.credentials.json读取 OAuth access tokentoken 只用于探测请求的 Authorization 头绝不写入记录请求 Anthropic 的 OAuth usage endpoint带anthropic-beta: oauth-2025-04-20头。额度解析做了很多兼容性工作Anthropic 端点目前按百分比上报如 37.0、1.0旧 payload 有时用小数0.37采集器用「任一值 1 即按百分制」的规则统一归一化见 normalize_utilization()limits数组里的模型级配额比如某周窗口只被 Fable 消耗也被显式解析成带标题的窗口scoped_limits()原因是seven_day_opus这类旧 key 已经留在 null只读 flat bucket 会悄悄漏掉账户真实在消耗的额度。Claude limits 需要登录过的 CLI无凭据时authHelpText会提示运行claude auth login面板只展示本地统计见 README 及 AUTH_HELP。若保存的 token 已过期但窗口中还留有上次的缓存数字记录会标 Sign-in expired 并回退展示「窗口尚未重置」的最近已知值collect_limits()。非默认目录通过环境变量指定CLAUDE_CONFIG_DIRClaude、CODEX_HOMECodex。Fireworks 余额与配置Fireworks 是「预付费」路径的样板。其采集器omarchy-agent-usage-fireworks的 token 统计来自 billing API按天/模型、最近 30 天、本地时区边界换算成 UTC 窗口发出查询额度则是一个估算余额。README 明确交代了一个特殊事实采集器会先尝试账户的:getBalance端点获取真实的预付费台账——该端点存在但被权限门控截至 2026 年 8 月控制台签发的 API key 都无法通过它Fireworks 似乎将其保留给 dashboard 会话。该探测之所以保留是因为它很廉价而且一旦 Fireworks 向 key 开放实时数字会自动点亮见 live_balance()。在那之前余额靠~/.config/omarchy/agents/fireworks.json的配置估算{ accountId: , fundedAmount: 20, fundedAt: 2026-07-01 }配置语义README 原文要点 源码印证fundedAmount你实际购买的信用额美元。不配置时标签页仍会显示 token 用量只是没有余额fundedAt购买日期ISO 格式。省略时采集器使用账户创建时间。后续追加充值top-up时应把fundedAmount增加新信用额、同时保留最初的fundedAt这样 funding 与 spend 仍覆盖同一时间段估算才不失真accountId仅当一个 API key 能访问多个账户时才需要——对应源码里discover_account()发现多个账户时抛出的错误提示 Set accountId in fireworks.json when the API key can access multiple accounts见 omarchy-agent-usage-fireworks。采集器计算剩余 max(0, funded - spent)其中 spent 来自账户的 usageCosts 查询subtotal 不可用时回退到 billing/summary 的 lineItems 求和见 spent()并把记录标记为estimated: true、scope: account。Fireworks 的凭据读取顺序为先FIREWORKS_API_KEY与FIREWORKS_ACCOUNT_ID环境变量其次~/.fireworks/auth.inifirectl set-api-key创建的 INI兼容 default section 或任意 section 里的 api_key/account_id最后才是 opencode 在~/.local/share/opencode/auth.json里存下的 Fireworks keycredentials()。Fireworks 记录还声明了两个影响面板与跨设备合并的字段base_record()scope: accountbilling API 的数字是账户全局的不是单机本地的因此跨设备聚合不能简单相加以及hasPromptStats: falsebilling API 只报 token从不报 prompt/session 数面板因此在 today 的 tooltip 里不显示 0 prompts 以免被误读为安静的一天。顶栏图标与键盘/鼠标/IPC 交互顶栏图标的行为在 Panel.qml 的按钮事件处理 中有明确实现左键打开/关闭面板toggle右键启动 agent调用omarchy-agent --pick选择并启动中键切换到下一个订阅next subscription额度或余额进入警示状态任一窗口 90% 或余额低于 10%时图标高亮为警示色active: root.alarming。面板内键盘操作README Interactions 部分h/l切换订阅j/k滚动内容r或 Enter刷新Tab移动到相邻的顶栏面板Esc关闭。面板与外部通信走 IPC命令形式为omarchy-shell omarchy.agents open|close|toggle|refresh|next对应的 IPC handler 在 Panel.qml 中注册refresh返回oknext把选中项推进到下一个 provider。此外面板打开期间会每 30 秒重算一次nowMs确保「resets in Xh」这类倒计时在面板一直开着时也保持准确见 Panel.qml。配置项与omarchy bar set命令插件的设置存放在~/.config/omarchy/shell.json中该 widget 的条目下顶层键可以用命令设置。完整键位表README Settings 部分Key默认值作用refreshIntervalSec900用量记录多久重新生成一次syncModeOffOn时写入本机快照并合并其他机器的快照syncDir由 Syncthing、Dropbox、rsync 等同步的文件夹syncFileNamehostname.json本机快照文件名syncDeviceIdhostname快照内部的稳定设备名数字类型的值必须用--json否则会以字符串形式写进shell.jsonomarchy bar set omarchy.agents refreshIntervalSec 300 --json omarchy bar set omarchy.agents syncDir ~/Sync/agent-usagemanifest.json中的 schema见 shell/plugins/agents/manifest.json对取值范围给出约束refreshIntervalSec为 integermin 30、max 3600、步进 30syncFileName描述为Optional. Defaults tohostname.json. Use a different file name on each machine, such as laptop.json or desktop.json.——每台机器建议用不同的文件名如laptop.json、desktop.json因为如果所有机器都用 hostname 默认名同一文件夹里会出现文件名冲突。各 agent 的启停是嵌套结构。由于set是字面量写入键、不会遍历点号路径所以传入整个providers对象时需要整块传 JSON或直接编辑shell.jsonomarchy bar set omarchy.agents providers { claude: { enabled: true }, codex: { enabled: false }, fireworks: { enabled: true } } --jsonenabled对每个被发现的 agent 默认都是true设为false可以隐藏一个已安装的订阅。被禁用的 agent 在记录重新生成时也会被跳过——Main.qml构造 update 命令时会为每个enabled false的 provider 追加--except id见 Main.qml updateCommand()update 脚本侧则用wanted()过滤见 omarchy-agent-usage-update。无订阅时的自我隐藏「只在设置中启用、并且实际产生过用量本机或同步过来的机器的订阅才会出现」是一条硬性规则只有一个时没有切换行一个都没有时整个模块直接离开顶栏见 README。这种自隐藏正是 widget 能随默认顶栏布局一起出厂的原因——从未运行过任何 AI 编码 agent 的机器画不出任何东西图标会在某次扫描第一次发现用量时自己出现。若想手动移除它omarchy plugin disable omarchy.agents实现层面Main.qml的enabledProviders会把「有本地记录且 enabled」「无本地记录但有同步数据且 enabled」的 provider 汇集起来再用providerHasData()过滤出真正有数字的见 Main.qml而Panel.qml的visible: providers.length 0让整个槽位在无数据时坍缩出顶栏Panel.qml。反向场景也在代码里被照顾到会话中途新装的 CLI会在下一次刷新时自然浮现因为没有任何逻辑在磁盘上轮询等待某个特定 agent 出现。跨设备汇总sync合并你所有开发机的用量打开syncMode后插件会把本机当前的用量快照写入syncDir下的syncFileName默认hostname.json并把该目录里每一个*.json快照合并起来。于是「今天」「最近 7 天」与「all-time」总量能覆盖你所有编码过的机器。合并规则有几个关键细节README 与 Main.qml 的 aggregateSnapshots() 相互印证活跃天按日期取并集union而不是相加两台机器在同一天工作该日只计一次活跃activeDays取max(累加计数值, activeDates 并集大小)额度rate limits永远按账户各自独立绝不跨设备合并余额同理两者都是账户级事实scope: account的记录取最宽值而非求和Fireworks billing API 在每个同步设备上报告的是同一份账户全局事实如果两台机器都同步它再相加每个 token 都会被算两遍。设备级默认devicescope统计才跨机相加账户级则用Math.max见 combineNumber()快照保持旧版 Omarchy 字段名让混跑不同版本的机器群双向合并依然干净见 providerSnapshot() 的注释。面板底部的 footer 会在数字覆盖了不止本机时给出提示——例如 Merged from 2 devicesfooterText()。同步管线本身是异步的写快照前先mkdir -p目标目录写完后用一个 bash 脚本扫描目录里所有*.json并解析为汇总数据一次同步进行中又触发同步时会把请求排队、结束后重跑见 Main.qml 的 sync 段。一个关于 all-time 的重要注意点README 收尾的 caveatCodex 采集器只读最近 30 天触碰过的原生 session 文件Fireworks 也只向 billing API 请求最近 30 天因此它们的 all-time 总量与天数都只覆盖这个窗口Claude 的则覆盖仍留在磁盘上的每一份 transcript。跨来源对比 totals 时要留意这一语义差异。为新的 AI 编码代理扩展一个标签得益于纯展示架构接入新 agent 的成本极低且完全不需要改动面板插件。流程如下在bin/里新增一个可执行的omarchy-agent-usage-id采集器脚本参考现成的 omarchy-agent-usage-claude、omarchy-agent-usage-codex 与 omarchy-agent-usage-fireworks让它向 stdout 打印一份符合记录契约的 JSON含id、name、ready、today*、recentDays、modelUsage、limits/balance等字段面板即自动获得一个标签页可选为它提供assets/id.svg徽标如果该徽标在浅色表面上需要深色变体再准备一个assets/id-light.svg。若两者都没有面板会用模块自带的顶栏字形bar glyph兜底见 Panel.qml iconCandidatesForProvider()以及现有资产目录 shell/plugins/agents/assets 中的claude.svg、codex.svg/codex-light.svg、fireworks.svg在~/.config/omarchy/shell.json的 widget 设置里或通过omarchy bar set按需声明该 provider 的enabled状态。采集器的 CLI 参数约定是统一的接受--force与--limits-onlyFireworks 因统计与余额来自同几笔 API 调用这两个 flag 只是为保持所有采集器同一调用形态而存在见其 main 注释。records 每次刷新时omarchy-agent-usage-update会自动发现并并行运行这个新采集器——插件对新增 agent 的支持本质上是「发布一个采集器」。小结omarchy.agents用一套「采集器写 JSON 目录、面板纯展示」的极简架构把一个多订阅 AI 用量仪表盘做成了 Omarchy 顶栏的天然组成部分Claude 的 5 小时会话 7 天周窗口、Codex 的 app-server RPC 额度、Fireworks 的预付费估算余额各有其数据通道与展示形态按天/按模型图表、余额警示、账户级与设备级数据在跨设备同步中的正确合并、以及「无数据即自我隐藏」的出厂友好行为都在这份设计里得到统一。想深入验证或二次开发建议按序阅读 插件 README、Main.qml、Panel.qml、三个采集器脚本与 manifest.json。【免费下载链接】omarchyBeautiful, Modern Opinionated Linux项目地址: https://gitcode.com/GitHub_Trending/om/omarchy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
