CPA Manager

CLIProxyAPI (CPA) 运维工具。基于官方 cpa-warden，用于库存扫描、401/限额清理、上传、补池与本地状态跟踪。

Security Scan

The package mostly matches its stated CPA maintenance purpose, but there are incoherences (undeclared env usage and an unexpected hardcoded external endpoint) that warrant caution before running it with real credentials.

Purpose & Capability

The skill's name/description (CPA Manager / cpa-warden based) align with the included scripts and SKILL.md: they scan inventory, probe for 401/quota, upload auth files, and perform maintenance. However the manifest declares no required environment variables or credentials while the shipped scripts accept/require a management token and base URL (CPA_TOKEN / CPA_BASE_URL or config.json). That mismatch between metadata and actual requirements is unexpected and should be corrected or confirmed.

Instruction Scope

The runtime instructions (SKILL.md) are consistent with the scripts' intended operations (scan, maintain, upload, delete_401, reenable_quota) and document local files created. But SKILL.md does not disclose that the main script contains a hardcoded WHAM_USAGE_URL (https://chatgpt.com/backend-api/wham/usage). That implies the code may make outbound requests to an external domain beyond the target CPA management API; the docs don't mention such external telemetry or probing. Any behavior that might contact third-party endpoints while using user credentials should be explicitly documented and audited.

Install Mechanism

There is no install spec (instruction-only install), so nothing is automatically downloaded or installed by the platform. The package contains Python scripts which must be executed directly; that's low-install-surface risk. Still, running those scripts will execute code included in the package, so contents should be reviewed before execution.

Credentials

Requesting a CPA management token and base URL is proportionate to the stated purpose. However the skill metadata lists no required env vars while the scripts rely on CPA_TOKEN / CPA_BASE_URL or a config.json containing the management token — an information mismatch. More importantly, the cpa_warden.py constant WHAM_USAGE_URL points to chatgpt.com; if probe logic uses target account credentials to call that endpoint (or any third-party endpoint), tokens or account-identifying data could be exposed. The presence of that hardcoded external URL is unexpected and not justified in docs.

Persistence & Privilege

The skill does not request elevated platform privileges and always:false. It does write local state files (SQLite and JSON) as part of normal operation; those are expected and documented. The package does not appear to modify other skills or global agent configs.

What to consider before installing

Before running this skill with real credentials: 1) Treat the manifest mismatch seriously — the package expects a management token (CPA_TOKEN/CPA_BASE_URL) or config.json even though metadata lists none. 2) Inspect cpa_warden.py around the WHAM_USAGE_URL and any code that performs probes: verify which external endpoints are contacted and whether any account tokens or sensitive payloads are sent there. 3) Run the tools in an isolated/test environment first (no production credentials) and monitor network traffic (e.g., with tcpdump/proxy) to ensure requests only go to your CPA service. 4) Prefer to use a config.json that points to internal network addresses and not provide tokens to unknown third-party endpoints. 5) If you cannot audit the code, prefer the upstream official cpa-warden repository (validate checksums/commit history) or request the author to explain and remove any unexpected external calls. These steps will reduce the risk of accidental credential exposure.

CPA Manager - CLIProxyAPI 运维

基于官方 cpa-warden。

先说结论

以后默认不要再用 --base-url / --token 直传参数。 当前官方用法应以 config.json 为主：

cd /path/to/cpa-manager/scripts
python3 cpa_warden.py --mode scan --config config.json

本地已验证：旧文档里的 --base-url http://cpa-service:8317 --token your-token 写法会报参数不识别。

---

配置路径

路径	说明
/path/to/cpa/config.yaml	CPA 主配置文件（Docker 挂载）
/path/to/cpa/auth/	OAuth 认证文件目录（CPA 实际扫描源）
http://cpa-service:8317	CPA 服务地址（根据实际部署调整）
your-management-token	Management Token（从CPA配置中获取）
/path/to/cpa-manager/scripts/config.json	cpa-warden 本地配置

---

官方能力边界

cpa-warden 不是"只扫 401 的小脚本"，而是一个有状态的 CPA 运维工具，至少包含：

1. 拉取库存：GET /v0/management/auth-files
2. 用 api-call 并发探测 wham/usage
3. 维护模式删除 401 / 处理限额
4. 上传 auth 文件到 CPA
5. maintain-refill 补池
6. 本地 SQLite 状态跟踪
7. 导出 401 / quota JSON 结果

因此要区分三层口径：

• CPA 库存层：/v0/management/auth-files
• cpa-warden 探测层：通过 api-call 实测是否 401 / quota
• 本地状态层：SQLite + 导出 JSON

它们不是同一个口径。

---

标准使用

1) 扫描（只读，不改远端）

cd /path/to/cpa-manager/scripts
python3 cpa_warden.py --mode scan --config config.json

适用：

• 看当前池子健康度
• 导出 401 / quota 列表
• 先预览再决定是否清理

2) 维护（扫描后执行删除/禁用）

python3 cpa_warden.py --mode maintain --config config.json --yes

适用：

• 删除 401
• 处理限额账号
• 执行恢复启用（若配置开启）

3) 预览维护（不删除 401）

python3 cpa_warden.py --mode maintain --config config.json --no-delete-401

适用：

• 先看 maintain 会命中哪些账号
• 不想立刻改远端状态时

4) 上传 auth 文件

python3 cpa_warden.py --mode upload --config config.json --upload-dir ./auth_files

5) maintain-refill

python3 cpa_warden.py --mode maintain-refill --config config.json --min-valid-accounts 100 --upload-dir ./auth_files

---

本地产物

cpa-warden 会写以下本地状态文件：

• cpa_warden_state.sqlite3 - 本地状态数据库
• cpa_warden_401_accounts.json - 当前探测出的 401 列表
• cpa_warden_quota_accounts.json - 当前探测出的限额列表
• cpa_warden.log - 运行日志

注意：这些文件会影响你对状态的理解。 不要把它们误当成 CPA 实时库存本身。

---

最佳实践

A. 管理扫描源目录

CPA 容器实际读的是 auth 目录。确保该目录只包含有效的认证文件，避免包含备份、日志等子目录。

B. 备份策略

备份目录必须移出 auth 根目录外部，避免被 CPA 递归扫描。

C. 文件命名规范

如果需要整理文件名，先离线 dedupe，再一次性生成新目录，最后原子替换。

D. 状态验证

auth-files active 不等于账号真可用。清池要以 cpa-warden 的 probe 结果为准，不要只看库存列表。

---

推荐操作顺序

日常健康检查

1. scan
2. 看 401 / quota 输出
3. 决定是否 maintain

需要清池时

1. 确认 auth 目录下没有 backup/trash/logs 子目录
2. maintain --yes
3. 再 scan 复查剩余 401
4. 必要时再做下一轮 maintain

需要整理命名时

1. 先备份到 auth 根目录外部
2. 只基于唯一 basename 集做重排
3. 重命名后重启 CPA
4. 再 scan

---

当前本地推荐命令

cd /path/to/cpa-manager/scripts

# 扫描
python3 cpa_warden.py --mode scan --config config.json

# 清理 401 / 限额
python3 cpa_warden.py --mode maintain --config config.json --yes

# 上传
python3 cpa_warden.py --mode upload --config config.json --upload-dir ./auth_files

---

参考

• 官方 README：https://github.com/fantasticjoe/cpa-warden?tab=readme-ov-file
• 本地脚本：/path/to/cpa-manager/scripts/cpa_warden.py
• CPA 主配置：/path/to/cpa/config.yaml
• CPA auth 目录：/path/to/cpa/auth/
• 容器内挂载点：/path/to/cpa/auth

---

注意事项

• 不要再用旧文档里的 --base-url --token 直接传参
• 不要把 backup/trash/logs 放进 auth 目录
• 不要把 auth-files 库存口径当成 probe 口径
• 不要在生产 auth 目录上连续试验式重命名
• 不要把"删除接口返回成功"直接当成库存已收敛，必须再复查

ClawHub 简短说明（可用于上传描述）

用于基于 auth 文件池的 CLIProxyAPI/CPA 运维，支持库存扫描、401/限额探测、清池、上传与补池。 适合有 management API 和本地 auth 目录的部署场景；不适用于纯转发型代理服务。