opencode-usage-watchdog

查询一个或多个 OpenCode Go 密钥的额度；定时运行时只在需要关注时输出。Python 3.11+，仅标准库，无需安装依赖。English

快速使用

git clone https://github.com/getaskclaw/opencode-usage-watchdog.git
cd opencode-usage-watchdog
python3 opencode_usage_monitor.py --once

单密钥沿用现有配置，按顺序读取：

1. OPENCODE_GO_API_KEY / OPENCODE_ZEN_API_KEY 环境变量；
2. $HERMES_HOME/.env；
3. ~/.hermes/.env。

OPENCODE_ZEN_API_KEY 只是兼容的变量名：查询的仍是 Go 用量接口，不是 Zen 余额接口。

多密钥

在仓库外创建私有 keys.json，内容为数组（以下是假值）：

[
  {"name": "laptop", "key": "YOUR_FIRST_KEY"},
  {"name": "server", "key": "YOUR_SECOND_KEY"}
]

chmod 600 /path/to/keys.json
python3 opencode_usage_monitor.py --keys-file /path/to/keys.json --once
python3 opencode_usage_monitor.py --keys-file /path/to/keys.json --once --json

• 显式文件优先，不会偷偷回退到环境变量；相同密钥只查一次，保留首次标签。
• --workers 4 控制并发（1–16，默认 4）；单个失败不会中断其他查询。
• 不要把密钥放进标签、命令行参数、Git 或截图。配置文件是明文，请妥善保护。
• 不同密钥可能属于同一账号；不要把额度相加。

读懂结果

接口：GET https://opencode.ai/zen/go/v1/usage，Bearer 认证。

每个密钥显示 rolling（滚动）、weekly（周）、monthly（月）的已用/剩余百分比、状态及重置时间。--json 提供机器可读结果及成功/失败计数。

百分比不是 token 数，也不是账单。 已移除旧版按固定 $12/$30/$60 换算金额的逻辑；OPENCODE_WATCHDOG_DOLLAR_LIMITS 不再使用。查询成功也不等于模型请求一定可用。

定时监控

去掉 --once 即执行一次有状态巡检；脚本不是常驻进程。首次检查、每日 UTC 首次检查、用量变化至少 2 个百分点、达到 70% 预警或 85% 告警、配额状态异常时输出。失败消息每个密钥最多每小时一次；静默不代表成功，仍须检查退出码。--json 用于机器读取，不采用静默输出。

状态和历史默认位于 $HERMES_HOME（未设置则 ~/.hermes），文件名加入密钥的 SHA-256 标识，不存原始密钥。OPENCODE_WATCHDOG_STATE、OPENCODE_WATCHDOG_HISTORY 可覆盖基础路径，仍会加入标识。旧版无账号标识的状态文件保留但不导入，升级后会重新首报；不要同时运行多个写入相同状态的巡检进程。

--once 不读写监控状态或历史，适合临时检查。

测试

python3 -m unittest -v
python3 opencode_usage_monitor.py --selftest

测试使用离线数据，不验证真实账号。--selftest 需要仓库里的测试文件。

退出码：0 查询完成（可能有额度告警），1 配置错误，2 查询或存储失败。命令行参数错误也返回 2。