openusage CLI 完整教程让 AI Agent 一键读取实时配额 JSON【免费下载链接】openusageBurning through your subscriptions too fast? Paying for stuff you never use? Stop guessing. OpenUsage is free and open source.项目地址: https://gitcode.com/gh_mirrors/op/openusageOpenUsage是一款免费开源的 macOS 菜单栏应用帮你追踪 Claude、Codex、Cursor 等 AI 订阅的用量。它的一次性 CLI 命令openusage无需启动 App直接输出与本地 HTTP API 完全一致的实时配额 JSON/v1/limits格式5 分钟内复用共享缓存是 AI Agent 和自动化脚本读取配额的极简方式。为什么需要 openusage 一次性 CLI 命令AI Agent 经常需要知道我还能用多少额度传统方式打开 App 看界面 → 无法被程序化读取轮询方式起一个常驻服务 → 占用资源、逻辑复杂openusage 方式一条命令打印 JSON立即退出 ✅它的核心特性特性说明一次性执行打印文档化的/v1/limitsJSON 后退出绝不启动菜单栏 App共享缓存与 App 共用同一个 5 分钟快照缓存正常读取免重复请求强制刷新--force跳过新鲜度检查等价于 App 内手动刷新⌘R凭证安全凭据仅在本地使用永远不会出现在输出中稳定契约输出是稳定标量限额/余额不含 UI 行、颜色、图表等易变内容命令入口源码OpenUsageCLI.swift参数解析见 CLIArguments.swift核心读取逻辑在 UsageReader.swift。安装 openusage 命令到系统 PATH官方文档docs/cli.md在 OpenUsage 中打开设置 → Command Line点击Install…。经过 macOS 标准的管理员授权后openusage即可在全新的终端会话中全局使用。 安装的软链接指向 App 内部签名的 helper 二进制因此 App 就地更新Sparkle 更新时命令会自动同步升级无需重装。安装逻辑见 CommandLineToolInstaller.swift目标路径为/usr/local/bin/openusage。三条核心命令速查来自 docs/cli.md 的官方示例openusage # 所有已启用 provider过期缓存项会刷新 openusage codex # 单个 provider缓存过期时刷新 openusage codex --force # 绕过新鲜度检查强制走共享引擎刷新完整帮助信息openusage --help # 查看用法 openusage --version # 查看版本号Provider 参数匹配规则与本地 HTTP API 完全一致纯字符串匹配无别名逻辑精确 provider ID如codex→ 该 provider家族 ID如claude、codex→ 该家族下所有账号卡片多账号支持时自动覆盖单账号则就是那一张卡片匹配不到任何 provider → 以错误退出不做任何猜测理解输出 JSONAI Agent 可直接解析openusage的输出就是本地 APIGET /v1/limits的响应体完整字段文档见 docs/local-http-api.md{ schema: openusage.limits.v1, generatedAt: 2026-07-13T01:40:00.000Z, providers: { codex: { displayName: Codex, plan: Pro 20x, fetchedAt: 2026-07-13T01:39:30.000Z, expiresAt: 2026-07-13T01:44:30.000Z, stale: false, resources: { session: { kind: consumption, // 消耗型看 used/remaining unit: percent, used: 42, limit: 100, remaining: 58, utilization: 0.42, resetsAt: 2026-07-13T06:00:00.000Z, windowSeconds: 18000 }, credits: { kind: balance, // 余额型看 available unit: credits, available: 821 } } } }, errors: [] }给 AI Agent 的解析要点resources按稳定资源 ID 索引如 Codex 有session、weekly、credits、sparkClaude 有session、weekly、sonnet、extraUsageCursor 有totalUsage、credits等完整清单见 docs/local-http-api.md 的公共资源表kind分两类consumption消耗型读used/remaining/utilization和balance余额型读availableunit可能随套餐变化如 CursortotalUsage在百分比计划下是percent企业请求制计划下是requests解析前务必先看单位stale: true表示数据已超过 5 分钟新鲜期刷新失败会进errors数组上一次成功快照仍保留不会清零无当前值的资源直接省略而不是编造 0退出码脚本里这样处理错误来自 OpenUsageCLI.swift 的实现退出码含义脚本应对0成功含部分 provider 的 warning 写往 stderr解析 stdout JSON2参数非法 / 未知 provider检查命令与 provider 名4刷新或本地读取失败部分 provider 失败时会打印 warning 后以此码退出回退到缓存数据或稍后重试openusage codex /tmp/codex.json 2/tmp/codex.err status$? [ $status -eq 0 ] cat /tmp/codex.json || echo refresh failed: $(cat /tmp/codex.err)缓存策略CLI 与 App 如何共享数据CLI 与 App导入同一套provider、认证存储、定价、刷新协调器和快照缓存架构见 docs/architecture.md正常读取复用5 分钟内的快照缺失或过期的条目会触发刷新——即使菜单栏 App 没有运行--force绕过新鲜度门槛成功结果写回同一个缓存App 立即可见Claude/Codex 的缓存条目带账号标记换账号后旧账号的缓存会在下次启动被丢弃避免误显示旧账号的限额缓存细节见 docs/refreshing.md。替代方案本地 HTTP API如果你的 Agent 常驻内存也可以不装 CLI直接读 docs/local-http-api.md 描述的本地接口Base URLhttp://127.0.0.1:6736仅回环地址局域网不可达GET /v1/limits—— 与 CLI 输出完全相同的机器友好格式推荐GET /v1/limits/:id—— 单个 provider / 家族对未启用的 provider 同样有效GET /v1/usage—— 旧版 UI 格式仅向后兼容保留⚠️ 隐私提示响应带宽松的 CORS 头浏览器页面在 App 运行期间也能读到这些数据与菜单栏显示的数字相同不含任何凭据。常见问题 FAQQ1CLI 需要菜单栏 App 在运行吗不需要。这是一次性命令自己走完整的 provider 读取链路输出后退出。Q2数据会不会很旧stale字段和expiresAt会明确告诉你快照是否超过 5 分钟需要实时数据时加--force。Q3输出里会有我的 API Key 吗不会。凭据只用于本地对应的 provider 请求输出中绝不包含任何凭证。Q4支持哪些 provider与 App 完全一致Claude、Codex、Cursor、Copilot、OpenRouter、OpenCode、Ollama、Z.ai、Devin、Grok、Antigravity 等清单与各家资源键见 docs/local-http-api.md。Q5openusage和openusage --force的区别前者尊重 5 分钟缓存秒回后者强制走共享刷新引擎重新拉取耗时与 App 手动刷新相当适合 Agent 在关键决策前确认实时额度。总结 用一句话概括openusage把 OpenUsage 菜单栏 App 的实时配额数据变成了一条可被 AI Agent 直接解析的 JSON 命令——共享缓存、稳定契约、凭证零泄露。推荐集成模式日常轮询openusage codex走 5 分钟缓存开销极低关键决策前openusage codex --force强制刷新一次常驻服务改用127.0.0.1:6736/v1/limitsHTTP 接口错误处理按退出码 0/2/4 分流errors数组非空时保留上一次快照更多文档CLI 文档、本地 HTTP API、刷新与缓存、架构总览。【免费下载链接】openusageBurning through your subscriptions too fast? Paying for stuff you never use? Stop guessing. OpenUsage is free and open source.项目地址: https://gitcode.com/gh_mirrors/op/openusage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
