Hermes Decision Trace

CPA/CLIProxyAPI vs Sub2API 选型判断

对咱们现在这台 Hermes 主机，继续以 CPA/CLIProxyAPI 作为主链路更合适；Sub2API 更像“面向多人分发/计费/支付/商业化中转站”的平台，不适合作为当前本机代理的直接替代。更现实的策略是：CPA 保持主数据面；Sub2API 只作为备选观察或未来多人额度分发场景的候选，不现在迁。

HTML完整论证
Wiki可检索归档
Feishu短入口交付
🎯
核心结论

对咱们现在这台 Hermes 主机，继续以 CPA/CLIProxyAPI 作为主链路更合适；Sub2API 更像“面向多人分发/计费/支付/商业化中转站”的平台，不适合作为当前本机代理的直接替代。更现实的策略是：CPA 保持主数据面；Sub2API 只作为备选观察或未来多人额度分发场景的候选，不现在迁。

🧭
推荐路径

咱们现在选 CPA，不选 Sub2API。

🛡️
关键边界

不调用真实 executor；生产动作另走审批。

关键判断

判断项摘要
推荐方案咱们现在选 CPA，不选 Sub2API。
关键依据CLIProxyAPI 官方 README：提供 OpenAI/Gemini/Claude/Codex/Grok compatible API endpoints；支持 Codex/Claude Code/Grok Build OAuth；多账户 round-robin；支持 OpenAI-compatible upstream providers。
落地方式按行动清单推进，保持可回退。
风险边界不跨执行边界；真实执行需另走审批。

证据摘要

  • CLIProxyAPI 官方 README：提供 OpenAI/Gemini/Claude/Codex/Grok compatible API endpoints；支持 Codex/Claude Code/Grok Build OAuth；多账户 round-robin；支持 OpenAI-compatible upstream providers。证据点 1
  • CLIProxyAPI 官方 README_CN：明确多账户轮询、Codex/Claude/Grok/Gemini 支持、CPA-Manager 用于请求级监控、费用估算、Codex 账号池巡检。证据点 2
  • Sub2API 官方 README：定位为 AI API gateway platform for subscription quota distribution；支持多账号、API key distribution、precise billing、smart scheduling、concurrency control、rate limiting、built-in payment、admin dashboard。证据点 3
  • Sub2API README_CN：要求 PostgreSQL 15+、Redis 7+；支持 Docker；强调订阅额度分发、用户鉴权、计费、负载均衡和请求转发。证据点 4
  • 本地 wiki：CLIProxyAPI v7.0.4 + CPA-Manager 8316 已完成收口，CLIProxyAPI 负责主数据面与 management，CPA-Manager 负责 sidecar 统计与控制增强。证据点 5
  • GitHub API：CLIProxyAPI MIT，34.5k stars，5.7k forks，347 open issues，2026-05-23 push；Sub2API LGPL-3.0，23.1k stars，4.4k forks，1342 open issues，2026-05-24 push。证据点 6

行动清单

咱们现在选 CPA，不选 Sub2API。
Sub2API 不差，但它解决的是“平台运营/多租户/分发计费”问题；咱们当前要的是“本机 Hermes 稳定消费 CLI 订阅额度”。在目标没变之前，迁移就是增加复杂度。最优动作是继续把 CPA 这条线收紧：账号池健康、API key 漂移检测、usage 巡检、provider smoke test 自动化。Sub2API 作为未来多人额度分发的候选，先观察不落地。

边界 / 风险

风险点

未记录额外风险。

完整记录

本节目录一句话结论为什么不是端水方案对比CPA 的优势CPA 的短板Sub2API 的优势Sub2API 的短板推荐决策证据摘录最终建议

CPA/CLIProxyAPI vs Sub2API 选型判断

一句话结论

对咱们现在这台 Hermes 主机，继续以 CPA/CLIProxyAPI 作为主链路更合适；Sub2API 更像“面向多人分发/计费/支付/商业化中转站”的平台，不适合作为当前本机代理的直接替代。更现实的策略是：CPA 保持主数据面；Sub2API 只作为备选观察或未来多人额度分发场景的候选，不现在迁。

为什么不是端水

咱们的核心诉求不是搭一个公开售卖/拼车平台，而是：

  • Hermes 本机稳定接入 Codex / Claude Code / Gemini / Grok 等 CLI 订阅能力；
  • 本地可控、127.0.0.1 内网运行；
  • 多账号轮询、fallback、usage 观测够用；
  • 和现有 Hermes provider、CPA-Manager、systemd、已有 wiki/skill 运维链条兼容；
  • 出问题时能快速定位 owner、配置、凭证、API key 漂移和 token 可用性。

在这个目标下，CPA 已经实跑并收口过，迁到 Sub2API 会引入 PostgreSQL/Redis/支付/用户体系/更重控制面，收益不抵迁移风险。

方案对比

维度CPA / CLIProxyAPISub2API对咱们的判断
项目定位CLI 订阅/OAuth → OpenAI/Gemini/Claude/Codex/Grok 兼容 API 代理AI API gateway platform，用于订阅额度分发、用户 API key、计费、支付、调度CPA 更贴近“本机代理”；Sub2API 更像“中转站平台”
部署复杂度Go 单二进制为主，已有 systemd；默认端口 8317Go + Vue + PostgreSQL 15+ + Redis 7+，Docker-ready，也可自建依赖Sub2API 重很多，不适合轻量替换
当前落地状态本机已跑：CLIProxyAPI v7.0.4 at 127.0.0.1:8317；CPA-Manager sidecar at 8316未落地，需新增数据库、缓存、迁移配置、验证兼容性CPA 有现场资产与经验，Sub2API 没有
账号/额度管理多账户轮询，支持 Gemini/OpenAI/Claude/Grok；CPA-Manager 可做 usage/账号巡检多账号管理、API key 分发、精确计费、粘性会话、并发控制、rate limit多用户/商业分发 Sub2API 强；单机自用 CPA 足够
支持范围README 明确：OpenAI/Gemini/Claude/Grok compatible endpoints；Codex/Claude Code/Grok Build OAuth；OpenAI-compatible upstream providersREADME 明确：Claude/OpenAI/Gemini/Antigravity 订阅统一接入；赞助/服务生态覆盖 Claude Code、Codex、Gemini两者覆盖面都广；CPA 对 CLI-to-API 路线更直接
管理面内置 management + CPA-Manager sidecar，可请求监控、费用估算、Codex 账号池巡检Admin Dashboard + 用户/支付/计费/监控体系Sub2API 管理面更平台化，但对本机是冗余复杂度
Hermes 集成已接入、已踩坑：API key 漂移、proxy-url、management key、Codex provider wire_api 等都有 runbook需要重新接 Hermes provider，重新验证 /v1/models、chat/completions、Responses、流式、工具调用CPA 维护成本已被消化；Sub2API 迁移成本高
风险CLI 订阅反代天然有封控风险；Claude/Antigravity 风险更高；需要关注 release 和 token 刷新同样有订阅分发/账号共享/风控风险；还多了支付、用户体系、数据库安全与公网误暴露风险本机最小暴露优先，CPA 风险面更窄
社区热度GitHub API：34.5k stars，5.7k forks，347 open issues，MIT，2026-05-23 仍活跃GitHub API：23.1k stars，4.4k forks，1342 open issues，LGPL-3.0，2026-05-24 仍活跃两者都热；Sub2API issue 压力更大，许可证/平台化也更要注意

CPA 的优势

  1. 和咱们场景对位

CPA 的一句话就是把 CLI/OAuth 订阅变成兼容 API。本机 Hermes 要的是这个，不是用户计费平台。

  1. 轻量、边界清楚

主服务一个 Go binary + config.yaml + auth-dir；sidecar 管理层独立。现在已经形成：

CLIProxyAPI 8317 负责数据面，CPA-Manager 8316 负责 usage/控制增强。

  1. 已经有大量现场知识沉淀

包括 proxy-url 不读环境变量、management secret 明文/哈希、API key 漂移、Codex CLI provider 配置、OAuth auth 文件检查、systemd owner 判断等。这些是实战资产，迁走会丢掉一半确定性。

  1. 支持 openai-compatibility upstream

它不只是内建 OAuth 代理，也能挂 OpenAI-compatible 上游。对后续 Kiro gateway、第三方模型池、fallback 统一路由都有用。

CPA 的短板

  1. usage/管理能力不是主程序核心

新版本 usage 统计拆出去，需要 CPA-Manager / usage dashboard / keeper 之类 sidecar。

  1. 多用户商业化能力弱

如果要给多人分发 key、余额、套餐、支付、分账，CPA 本体不是为这个设计的。

  1. 协议变化敏感

CLI/OAuth 订阅反代会被上游协议变化影响，需要持续跟 release。

  1. Claude/Antigravity 等渠道风险不均衡

本地 skill 已记录：Codex/Gemini 风险相对低，Claude Code 中高，Antigravity 极高；不能无脑全开。

Sub2API 的优势

  1. 平台能力完整

README 明确支持多账号、用户 API key 分发、token 级计费、智能调度、粘性会话、并发控制、rate limit、支付、Admin Dashboard。

  1. 适合多人/拼车/商业分发

如果以后要做“小团队共享额度池”“用户充值自助”“多租户 API 网关”，Sub2API 明显更贴近。

  1. 控制面更重、更产品化

它不是只做代理，而是带用户、账单、支付、监控的一体化平台。

  1. 社区热度高、更新活跃

GitHub API 显示 2026-05-24 仍 push，stars 也很高。

Sub2API 的短板

  1. 对当前本机 Hermes 是重装甲

PostgreSQL + Redis + 前后端 + 支付/用户体系，引入的运维面比 CPA 大不少。

  1. 迁移收益不明显

当前 CPA 已经能承担主链路，Sub2API 对“单人本机自用”的增量主要是更强管理/计费，但这些我们暂时不是刚需。

  1. 风险面更宽

多用户、支付、余额、API key 分发、Web admin 都意味着更大的安全边界；如果误暴露公网，问题比本地 CPA 大。

  1. issue 压力和许可证边界要注意

GitHub API 显示 open issues 1342；许可证 LGPL-3.0，后续若做二次集成/分发，要比 MIT 更谨慎。

推荐决策

当前默认

不迁移，继续 CPA/CLIProxyAPI + CPA-Manager。

保持现有拓扑：

Hermes / Codex / 其他客户端 -> http://127.0.0.1:8317/v1 -> CLIProxyAPI 主服务 -> Codex / Claude Code / Gemini / Grok / OpenAI-compatible upstream CPA-Manager 8316 -> 只做管理面、usage、账号池巡检

Sub2API 什么时候值得上

只有出现下面任一明确需求，才进入 spike：

  1. 需要给多人/多项目发放独立 API key；
  2. 需要 token 级计费、余额、套餐或支付；
  3. 需要更复杂的用户级并发控制、rate limit、粘性会话；
  4. 准备做团队内共享额度池，而不是涛哥本机自用；
  5. CPA 的某些关键渠道长期不稳，而 Sub2API 在相同渠道上有实测优势。

如果要试 Sub2API，正确方式

不要直接替换 CPA。先做 sidecar spike：

  1. 独立端口部署 Sub2API；
  2. 不接公网，不接支付；
  3. 只导入一个低风险测试账号或 OpenAI-compatible upstream；
  4. 用 Hermes 建一个单独 provider 指向 Sub2API；
  5. 跑 /v1/models、chat/completions、streaming、tool calling、长上下文、错误恢复；
  6. 连续观察 3 天，再决定是否进入正式链路。

证据摘录

  • CLIProxyAPI 官方 README：提供 OpenAI/Gemini/Claude/Codex/Grok compatible API endpoints；支持 Codex/Claude Code/Grok Build OAuth；多账户 round-robin；支持 OpenAI-compatible upstream providers。
  • CLIProxyAPI 官方 README_CN：明确多账户轮询、Codex/Claude/Grok/Gemini 支持、CPA-Manager 用于请求级监控、费用估算、Codex 账号池巡检。
  • Sub2API 官方 README：定位为 AI API gateway platform for subscription quota distribution；支持多账号、API key distribution、precise billing、smart scheduling、concurrency control、rate limiting、built-in payment、admin dashboard。
  • Sub2API README_CN：要求 PostgreSQL 15+、Redis 7+；支持 Docker；强调订阅额度分发、用户鉴权、计费、负载均衡和请求转发。
  • 本地 wiki：CLIProxyAPI v7.0.4 + CPA-Manager 8316 已完成收口，CLIProxyAPI 负责主数据面与 management，CPA-Manager 负责 sidecar 统计与控制增强。
  • GitHub API：CLIProxyAPI MIT，34.5k stars，5.7k forks，347 open issues，2026-05-23 push；Sub2API LGPL-3.0，23.1k stars，4.4k forks，1342 open issues，2026-05-24 push。

最终建议

咱们现在选 CPA，不选 Sub2API。

Sub2API 不差，但它解决的是“平台运营/多租户/分发计费”问题；咱们当前要的是“本机 Hermes 稳定消费 CLI 订阅额度”。在目标没变之前，迁移就是增加复杂度。最优动作是继续把 CPA 这条线收紧：账号池健康、API key 漂移检测、usage 巡检、provider smoke test 自动化。Sub2API 作为未来多人额度分发的候选，先观察不落地。

Generated 2026-05-25T00:07:00+08:00 · Hermes decision trace