多把 opencode key 不用手管：一个插件按真实用量自动分配

——CLIProxyAPI 插件 cpa-opencodego-pool

摘要：手上有多把 opencode Go 的 api-key，轮询会把同一个会话打散，也看不见哪把已经打满。这个 CLIProxyAPI 插件按上游真实用量做会话粘性路由：新会话走用量最低的 key，同一会话固定复用一把，打满即刻改绑。

项目源代码

它做什么

• 新会话 → 路由到 rolling 窗口用量最低的 key
• 同一个 x-opencode-session → 始终复用同一把 key，绝不随机漂移
• key 打满或失效 → 立即改绑到当前用量最低的那把
• key 增删无需重启 → 靠 config.yaml 热重载自动识别
• 只读资源页 → 实时看每把 key 的 rolling / weekly / monthly 用量、被排除的原因、绑定的会话数

一条边界：没有 x-opencode-session 头的请求它不干预，交回宿主默认调度。

安装

1. 构建并放进插件目录

make build          # 产出 bin/opencodego-pool.dylib
make install INSTALL_DIR=/path/to/cpa/plugins/darwin/arm64

宿主只在 <plugins_dir>/<GOOS>/<GOARCH>/（如 plugins/darwin/arm64/）和 <plugins_dir>/ 两处查找。文件名去掉扩展名就是插件 ID，所以必须叫 opencodego-pool.dylib。

2. 在 CLIProxyAPI 的 config.yaml 里开启

plugins:
  enabled: true
  configs:
    opencodego-pool:
      enabled: true              # 必须显式写，缺省值被宿主规范化为 false
      priority: 100              # 必须高于其它 scheduler 插件
      usage_url: "https://opencode.ai/zen/go/v1/usage"
      config_path: "/path/to/cpa/config.yaml"

usage_url 与 config_path 缺一不可，且 usage_url 不能从 base-url 推导：前者是 .../zen/go/v1/usage，后者是 .../zen/go/v1/chat/completions。

3. 验证

curl -s -H "Authorization: Bearer $CPA_MANAGEMENT_KEY" \
  http://127.0.0.1:8317/v0/management/plugins | jq '.plugins[] | select(.id=="opencodego-pool")'
# 关注 registered: true 与 effective_enabled: true

只读资源页（免鉴权）：http://127.0.0.1:8317/v0/resource/plugins/opencodego-pool/status

仓库：https://github.com/AlphaGodzilla/cpa-opencodego-pool

参考

• CLIProxyAPI（宿主）：https://github.com/router-for-me/CLIProxyAPI —— 插件目录查找规则、enabled 缺省为 false、usage_url 不可推导等行为均以其源码为准

关键词

CLIProxyAPI 插件 · 会话粘性路由 · 用量感知调度 · API Key 池 · opencode

---

知识库关联：[[API网关与技术选型综述]]、[[系统高可用与性能架构综述]]