codexwatch

codexwatch 展示 OpenAI Codex 的使用情况：按天、项目、模型、会话和工具统计令牌及其 API 等效费用，显示当前套餐的 5 小时和每周限额，以及这些限额每增加 1% 要花费多少。默认情况下，它只读取 Codex 已在本机写入的会话日志，不会打开你的登录信息，也不会发起网络请求；获取价格和刷新 codexhop 账户都由你主动发起。

pipx install codexwatch-cli  # or: pip install --user codexwatch-cli
codexwatch                   # the overview in your terminal
codexwatch dashboard         # the web dashboard

你只需使用这台机器上已有的 Codex 日志，因此运行第一条命令就能看到数据。在 Linux 上，从克隆的仓库运行 ./install.sh --tray --desktop，还会添加应用菜单项、桌面快捷方式和托盘图标。

与众不同之处

每条响应只计数一次

Codex 会为每条模型响应分配一个 ID。codexwatch 以此作为每行的键，因此，复制父会话历史记录的分叉会话、子 Agent、重复的令牌事件，或从另一台机器同步的相同日志，都不会导致令牌被重复计数。这是 Codex 使用量被高估的四种情况，每种都有对应测试进行复现。

套餐限额取自你自己的日志

每条响应之后，Codex 都会将套餐的速率限制读数写入会话日志：5 小时和每周窗口的使用比例，以及重置时间。codexwatch 会读取这些数据，因此实时数据无需网络请求或登录。

配额取证

由于每条读数都对应一条已知响应，codexwatch 可以将窗口内消耗的令牌数与窗口变化幅度进行对比。你会得到一个兑换率（每个窗口和每天的套餐限额每增加 1% 对应多少美元 API 使用费用），并能看到本地日志无法解释的任何增幅标记，例如来自另一台机器或 ChatGPT 本身的使用量。

快速处理大型日志

程序会根据行首字节筛选内容，因此不会解码工具输出和推理文本；对于持续增长的会话，也只会从上次扫描停止的位置继续读取。在开发所用的机器上，首次扫描 59 个会话中的 1.85 GB 日志约需 2 秒（实测于 2026-11-04）；后续扫描只会读取新增行。

价格可查证

每个内置价格都摘自 OpenAI 的定价页面，并附有日期和页面链接。没有公开价格的模型会标记为未定价，并从美元总额中排除，绝不会按 $0 计算。Fast 模式按 Fast 层级定价，超过 272K 个令牌的提示词则按长上下文费率定价。

仪表板

codexwatch dashboard 会在 127.0.0.1 上打开一个页面。它可离线使用，会遵循系统的浅色或深色设置，并在你工作时自动刷新。

页面顶部显示你的套餐信息：两个窗口及其重置时间、过去一小时的消耗速率、按当前速率填满窗口所需的时间，以及自窗口重置以来的花费。下方的红色区间将过去 30 天的用量与套餐费用进行比较。接下来依次显示你所选时段的总量、每日图表、模型和项目、配额分析、近期会话、按星期和小时划分的地图、工具调用，以及工作运行方式（CLI、IDE 或 codex exec，Standard 或 Fast，主会话或子 Agent）。

浅色主题和手机

分享卡片

codexwatch card 会生成一张 1200 × 630 的月度概览图片；仪表板中的“分享卡片”按钮可将其保存为 SVG 或 PNG。卡片会重点展示套餐带来的价值。除非你传入 --projects，否则卡片不会显示项目名称，因为项目名称可能是客户名称。

套餐价格取自 OpenAI 的 Codex 定价页面。Enterprise 和 Edu 没有公开价格，因此可使用 codexwatch config set plan_price 60 设置自己的价格。

在菜单栏、系统托盘、状态栏和提示符中使用

codexwatch bar -f FORMAT 会按各类状态栏所需的格式输出一行文本或一个小菜单。它只读取新增的日志行，因此每隔几秒调用一次也不会造成明显开销。

位置	方法
macOS 菜单栏	安装 SwiftBar 或 xbar，然后将 extras/swiftbar/codexwatch.30s.sh 复制到其插件文件夹（或运行 ./install.sh --swiftbar）。
Linux 系统托盘	运行 codexwatch tray，或运行 ./install.sh --tray 以立即启动并在每次登录时启动（--desktop 还会在桌面上创建快捷方式）。圆环显示 5 小时窗口；菜单包含两个窗口、今天的价值以及你的 codexhop 账户。它使用你所用发行版的 GTK 绑定（python3-gi 和 AppIndicator 软件包），即使 codexwatch 本身是通过 pipx 安装的也一样。
waybar	"custom/codex": {"exec": "codexwatch bar -f waybar", "return-type": "json", "interval": 30}
tmux	set -g status-right '#(codexwatch bar -f tmux)'
polybar、i3blocks	-f polybar、-f i3blocks
Shell 提示符	PS1='$(codexwatch bar -f prompt --no-scan) \$ '

当窗口使用量达到 75%、90% 和 100% 时，系统会分别发送一次桌面通知。通知由系统托盘发送，也可以通过定时器运行 codexwatch notify。

在 Codex 或 Claude 中询问用量

codexwatch mcp 是一个 MCP 服务，因此 Agent 可以在会话中途查看你的用量：

codex mcp add codexwatch -- codexwatch mcp     # OpenAI Codex
claude mcp add codexwatch -- codexwatch mcp    # Claude Code

然后询问“我的 5 小时窗口还剩多少？”或“这周花了多少钱？”。可用工具包括 usage_summary、plan_limits、quota_forensics、sessions、daily 和 budget_status。该服务已加入官方 MCP Registry，名称为 io.github.psychofict/codexwatch。

多个 ChatGPT 账号

codexhop 会为 Codex 保留多个 ChatGPT 登录，并在它们之间切换。安装后，codexwatch 会显示每个账号最近一次的用量读数和剩余空间最多的账号，在配额报告中标出每个计划窗口对应的账号，而 codexwatch limits --refresh 会要求 codexhop 刷新所有账号的用量读数。codexwatch 本身不会打开登录文件；凡是需要用到登录文件的操作，它都会运行 codexhop。

codexwatch autohop 会在当前账号用尽之前切换账号。在运行该命令前，此功能处于关闭状态；不带 --apply 时，命令只会说明将会执行什么操作：

$ codexwatch autohop
15:41:56  stay  work is at 31% of its 5-hour window and 29% weekly; below 92% / 97%, so stay

加上 --apply 后，当当前账号的 5 小时窗口用量达到 92% 或周窗口用量达到 97% 时，它会切换到 5 小时窗口至少还有 25% 余量的账号，并且每 20 分钟最多切换一次。所有数值都可以在 config.json 的 autohop 区块中修改。extras/systemd 会每 3 分钟运行一次；在 codexwatch 文件夹中创建名为 autohop.off 的文件即可停止此功能。

预算

codexwatch budget add --name "Monthly" --usd 300 --every month
codexwatch budget add --name "atlas daily" --usd 20 --every day --scope project:atlas-api
codexwatch budget add --name "5h headroom" --pct 80 --window 5h
codexwatch budget list

美元或令牌预算会累计本地日历日、周（从周一开始）或月内所有项目或指定项目、模型的 API 等效用量。百分比预算则会监控计划本身的窗口。每项预算都会在达到限额的 80% 时（--notify-pct）发送通知，并在额度用尽时再次发送。对于脚本和 CI，codexwatch budget check 会在任何一项预算超出限额时以 1 退出。

多台机器

将另一台机器的 ~/.codex（或仅复制其 sessions 文件夹）复制或同步到某处，然后添加它：

codexwatch sources add ~/sync/laptop-codex --machine laptop
codexwatch machines

两处都出现的响应会按响应 ID 只计数一次。

命令

每份报告都支持 -p/--period（today、7d、30d、week、month、year、all、2026-10、2026-10-31）、--since 和 --until、筛选条件（--project、--model、--client、--machine、--account）以及 --json。

命令	显示内容
codexwatch	计划限额、今天、近 7 天、本月和所有时间的总用量、近 30 天概览、热门模型和项目
daily、weekly、monthly	每个周期的令牌（输入、缓存、输出、推理）和 API 价值；--csv
projects、models、clients、machines、tiers、efforts、agents	按其他维度分组显示相同数据
sessions	最近会话及其标题、模型、轮数、令牌、价值和压缩次数；子 Agent 列在其父级会话下
tools	Codex 调用过的工具及调用次数
latency	按模型统计的轮次时间中位数和第 90 百分位数，以及首个令牌的耗时
hours	按星期和小时显示 Codex 使用时段
limits	每个计划窗口、消耗速率、额度用尽时间以及 codexhop 账号；--refresh
quota	每个窗口和每天每个百分点对应的美元用量，以及日志无法解释的增幅
live	每隔几秒重绘一次的全屏视图
dashboard	位于 127.0.0.1:7878 的网页仪表板
card	分享卡片；--projects、--theme light、--plan-price
bar	用于状态栏或提示词的单行信息
tray	Linux 系统托盘图标
budget	add、list、rm、check
notify	发送一次所有到期通知
autohop	在 codexhop 账号用尽前切换账号（除非指定 --apply，否则为试运行）
mcp	MCP 服务
demo	使用虚构数据的仪表板；使用 --terminal 查看概览
export	将所有响应导出为 CSV 或 JSON
prices	价格列表；update 获取 LiteLLM 的价格列表，path 显示覆盖文件的存放位置
sources	add 或 rm 另一台机器的日志
scan	立即读取新的日志行；--full 重新读取所有内容
config、doctor、reprice	设置、配置检查，以及价格变更后的重新计价

数字是如何得出的

美元金额表示按 OpenAI API 公布的标准价格计算相同 token 的费用。ChatGPT 套餐按固定费用计费，因此请将其视为用量指标，而不是账单。输入 token 包括缓存和写入缓存的 token，输出 token 包括推理 token，与 OpenAI 的 usage 对象一致。

套餐数据取自日志中的读数，因此会及时更新到你在这台机器上最近一次 Codex 请求为止。在其他机器、ChatGPT 或云端任务中的用量也会计入同一套餐，但只有你在这里发出下一次请求后才会出现在这些日志中；配额报告中的“日志无法解释的增幅”指的就是这一点。快速模式会以标准速率的 2.5 倍消耗套餐额度，配额报告也会按此加权计算。

docs/how-it-works.md 详细介绍了日志格式、所有计数规则和取证方法。

价格

内置列表涵盖了截至 2026-11-04 Codex 使用过的模型，从 gpt-5 和 o3 到 gpt-6-astra。codexwatch prices 会列出这些模型及其价格来源。要修改价格，请将其写入 codexwatch 文件夹中的 prices.json（codexwatch prices path）：

{"models": {"gpt-6-astra": {"input": 10.0, "cached": 1.0, "cache_write": 12.5, "output": 50.0}}}

价格单位为每百万 token 的美元。codexwatch prices update 会下载 LiteLLM 的列表以补全缺失价格；你自己的文件优先级更高，而 codexwatch reprice 会在价格变更后重新计算你的历史用量。

隐私

codexwatch 会读取 ~/.codex/sessions（以及 archived_sessions），并且只写入自己的文件夹：Linux 上为 ~/.config/codexwatch，macOS 上为 ~/Library/Application Support/codexwatch，Windows 上为 %APPDATA%\codexwatch。除非你运行 prices update，或者通过 limits --refresh、仪表板按钮或 autohop 请求 codexhop 提供读数，否则它不会发起网络请求。仪表板仅侦听 127.0.0.1，只会响应来自其自身页面的数据请求，并使用其他网页无法读取的令牌。详情请见 SECURITY.md。

平台

	Linux	macOS	Windows
CLI、实时视图、仪表板、卡片、MCP、预算	是	是	是
菜单栏或系统托盘	系统托盘（GTK）	SwiftBar 或 xbar	否
Autohop（需要 codexhop）	是	是	否

需要 Python 3.9 或更高版本；除标准库外无需安装其他包。

常见问题

为什么这个包叫 codexwatch-cli？ PyPI 将 codexwatch 视为与一个名为 codex-watch 的无关项目同名，因此这个包加上了后缀。命令是 codexwatch，也可以使用 codexwatch-cli。如果不安装，想要直接运行一次：uvx codexwatch-cli。

为什么我的美元金额和其他工具的不一样？ 最常见的原因是，其他工具将分叉会话、子 Agent 或重复事件计算了两次，按标准费率计算快速模式，或者将没有价格的模型视为 $0。codexwatch doctor 会列出未定价的模型，而 export 会导出每条响应供你核对。

它适用于 VS Code 中的 Codex、codex exec 和桌面应用吗？ 适用，它们都会写入相同的日志；codexwatch clients 会按运行位置拆分用量。Codex 云端任务不会写入本地日志，因此只会通过其对套餐用量窗口的影响体现出来。

我使用的是 API 密钥，而不是 ChatGPT 套餐。 这样就没有套餐用量窗口，美元金额也会接近你的实际账单。

没有 Codex 日志也能试用吗？ codexwatch demo 会打开仪表板，展示两个月的虚构用量，并与真实历史记录分开。

贡献

欢迎提交问题和拉取请求。CONTRIBUTING.md 介绍了如何运行测试（python -m pytest），以及如何添加日志格式或价格。

codexwatch 由 Ebenworks 构建。Ebenworks 还开发了 codexhop 和 claudehop，并与 Statotech Systems 合作开发了 Claude Usage Widget & Token Tracker。仪表板使用依据 SIL Open Font License 授权的 Geist 字体。

MIT 许可。与 OpenAI 无关联，也未获得 OpenAI 认可或赞助。“OpenAI”“Codex”和“ChatGPT”是 OpenAI 的商标，此处仅用于说明本项目兼容的产品。