让 Agent 来帮你安装

English

当你想让 Codex、Claude 或其他 coding agent 安装、试运行或接入 codex-quota-monitor 时，用这份文档。它假设你已经有一个可访问的 CLIProxyAPI；这个项目不会替你安装、升级或管理 CPA。

你需要准备什么

• 期望安装在哪台机器，以及 Agent 是否允许在那台机器上执行命令
• 安装方式：优先 uv / Python 前台 smoke test、Docker / Compose，或已有 NixOS 仓库里的 flake module
• CLIProxyAPI management gateway URL，通常是 http://127.0.0.1:8317
• CPA management key file 的运行时路径；除非 gateway URL 指向会自动注入 key 的本地 proxy
• gateway health URL，通常是 http://127.0.0.1:8317/healthz
• 可选 direct quota sampling 的 Codex auth 文件目录
• SQLite history 是使用默认路径、关闭，还是指定自定义路径
• 页面访问方式：只允许本机、允许局域网，还是放在带鉴权的 reverse proxy / access layer 后面
• 浏览器实际访问时使用的 hostname 或 IP；局域网或反代访问时要进入 allowedHosts
• 可选 benchmark summary.json 路径和机器可读阈值告警；没有精确值时不要让 Agent 猜

告诉 Agent 的边界

• 不要安装或管理 CLIProxyAPI；只连接已有 CPA。
• 不要把 management key、Codex auth token 或完整 auth JSON 写进 repo、Nix store、日志、聊天记录或 issue。
• Docker 只挂载具体 management key 文件和 auth-files 目录，并保持只读；不要挂载整个 home、.config 或其它无关 secret 目录。
• 默认保持 127.0.0.1:4515；只有你明确要求局域网访问时，才允许绑定 0.0.0.0、设置 allowedHosts 并开放防火墙。
• reverse proxy 版本继续让应用监听 loopback，把 dashboard 发布到专用 hostname 的根路径，例如 https://quota.example/；不要配置 /quota/ 这类 path-prefix。
• 不明确是否要长期运行时，先做前台 smoke test，不启用或切换 system service。
• 完成后让 Agent 展示最终改动、实际执行过的命令和验收输出摘要。

可复制任务包

请帮我安装并验证 codex-quota-monitor。

已知事实：
- 我已经有可访问的 CLIProxyAPI；不要安装或管理 CPA。
- management gateway URL: http://127.0.0.1:8317
- management key file: /path/to/management-key
- gateway health URL: http://127.0.0.1:8317/healthz
- auth files dir: /path/to/auth-files
- dashboard 默认只允许本机访问，监听 127.0.0.1:4515
- SQLite history 使用默认值；除非我明确说明，不要关闭或改路径
- 除非我给出精确值，不要配置 benchmarkSummary 或 threshold alerts

安全边界：
- 不要把 key、token 或 auth JSON 内容写进仓库、Nix store、日志或回复正文
- 不要挂载整个 home、.config 或无关 secret 目录
- 不要扩大 LAN / 公网暴露面，除非我明确要求

验证要求：
- 优先做可回滚的前台 smoke test
- 运行 cqm --version、print-config、doctor
- 服务启动后检查 /healthz、/api/v1/status、/api/v1/alerts
- 回报实际命令、关键输出摘要和最终访问 URL

安装路径提示

uv / Python 适合首次验证和普通 Linux 前台运行：

优先用 uv tool install codex-quota-monitor==0.2.0。
如果 tag 还没发布，改用：
uv tool install 'git+https://github.com/xsyxnx/codex-quota-monitor.git'
先前台运行并完成 smoke test；只有我明确要求时，才落盘 user/system service。

Docker / Compose 适合需要运行时隔离、Docker Desktop 或统一容器部署的环境：

用 Docker 运行时保持 --read-only、--cap-drop=ALL、no-new-privileges 和只读 secret mount。
只把 /path/to/management-key 挂载为 /management-key:ro，只把 /path/to/auth-files 挂载为 /auth-files:ro。
如果 GHCR release image 还不可用，在仓库根目录运行 docker build -t codex-quota-monitor:local .。
需要 Compose 时，从 examples/docker-compose.yml 开始改，不要把宿主端口默认暴露到 0.0.0.0。

NixOS 只适合你已经有 NixOS 仓库并希望声明式接入 service 的情况：

如果这是已有 NixOS repo，请添加 flake input github:<owner>/codex-quota-monitor，
导入 inputs.codexQuotaMonitor.nixosModules.default，并启用 services.codexQuotaMonitor。
具体 option 和默认值看 docs/nixos-module.zh-CN.md；除非我明确要求，不要直接切换线上系统。

验收检查

让 Agent 运行或回报这些命令。路径、端口和 hostname 按你的部署值替换：

cqm --version
cqm print-config
cqm doctor
curl -fsS http://127.0.0.1:4515/healthz
curl -fsS http://127.0.0.1:4515/api/v1/status | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/alerts | jq '.'

如果 Agent 启用了 systemd service，再补充：

systemctl status codex-quota-monitor.service --no-pager

如果启用了局域网访问，再用手机或小屏浏览器打开 http://<host-lan-ip>:4515/，确认页面能正常渲染，而且不会出现整页闪白式 reload。