@yhong91/cpac

v0.1.38

Published

4 days ago

Connect Codex and Claude Code to a remote CLIProxyAPI gateway

0High
0Medium
0Low

yhong91

pi-package

CPA Companion (cpac)

CPAC 将 Codex 和 Claude Code 接入远端 CLIProxyAPI（CPA）：

Codex：注入模型目录和 loopback 网关，保留内置 openai provider。无用户改动时逐字节恢复原配置；注入期间改过文件则只撤掉 CPAC 字段。
Claude Code：通过临时环境变量启动，不修改 Claude Code 配置。

实现基于 TypeScript + Node.js，运行时零依赖。

要求

Node.js 20 或更新版本（npm 随 Node 安装）
已安装需要使用的 agent：codex、claude、pi、kimi 或 grok
有权访问的 CPA API key

安装

从 npm 安装后：

npm install -g @yhong91/cpac
cpac

快速上手

# 1. 安装
npm install -g @yhong91/cpac

# 2. 配置密钥：无参数运行进入交互引导，自动写入 shell 启动文件；
#    也可手动写入（zsh 示例）：
cpac
echo 'export CPA_API_KEY="<你的key>"' >> ~/.zshrc && source ~/.zshrc

# 3. 验证
cpac status

# 4a. 持久注入（长期生效，写入 agent 配置，可完整恢复）
cpac install --all                     # 注入所有检测到的目标（codex/pi/kimi）
cpac install codex                     # 只注入 Codex（默认开启 multi-agent v2）
cpac install codex --v2_models         # 先多选 spawn_agent 模型再注入
cpac install codex --max_context       # 注入时把模型上下文提升到实测上限（opt-in，仅限 codex）
cpac restore codex                     # 撤掉注入；注入期间的用户改动会留下

# 4b. 临时接管（退出无痕，不写任何配置文件）
cpac claude                            # Claude Code 走 CPA

# 5. 可选：Agent 配置向导与模型选择（只写配置，不启动）
cpac setup codex                       # Codex 配置向导 → 注入
cpac setup claude                      # Claude 模型向导
cpac claude setup                      # 配置完再启动（agent 下的 setup 才会 launch）

# 6. 升级（装上新版本后自动 sync 已接入的 agent）
cpac upgrade

各命令的完整参数与行为见下方对应章节。

Agent 自动化安装指南

本节面向 AI agent：按顺序执行即可完成安装与配置，全程无交互。注意：cpac codex --config 和 cpac claude --config 的交互向导是 TTY-only，agent 必须走下方直接写配置 JSON 的路径。

检查前置：node --version ≥ 20；确认用户需要哪些 agent（codex/claude/pi/kimi/grok 在 PATH 上）。向用户索取 CPA API key。
安装与密钥：

npm install -g @yhong91/cpac
echo 'export CPA_API_KEY="<key>"' >> ~/.zshrc   # bash 用 ~/.bash_profile 或 ~/.bashrc
source ~/.zshrc
cpac status   # 验证：CPA_API_KEY 应显示 configured

写入模型配置（创建或合并 ~/.config/cpac/config.json，已有键保留）：

{
  "spawn_models": ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gemini-3.7-flash-high", "grok-4.6"]
}

Claude 槽位（opus/sonnet/haiku）通常不用配：cpac 启动时自动选择——同家族 claude 模型优先，否则 gemini → grok → luna → 目录第一个；opus 无匹配则不设。这个链条在常见目录上正好给出理想结果：sonnet 落在 claude-sonnet-*（它同时充当 Auto mode 分类器的替身，避免分类请求失败后回退到昂贵的会话主模型），haiku 落在快的 gemini flash。只有目录奇怪时才用 cpac setup claude 交互式配置。codex spawn subagent 取三个 GPT + gemini + grok 五席（顺序即优先级，Codex 只广告 catalog 前 5），可通过 cpac setup codex 交互式配置。候选替换：mimo-v2.5（haiku）、grok-4.5（haiku）。若上述 slug 不在目录中（curl -s -H "Authorization: Bearer $CPA_API_KEY" "$CPA_BASE_URL/v1/models" 可查），按家族就近替换。分类器机制细节见 docs/claude-auto-mode-classifier.md。

持久注入（只对检测到的目标；codex 会应用步骤 3 的 spawn_models）：

cpac install --all
cpac status   # 验证：各 target 显示 ready/injected

统一启动与配置：
- 启动：cpac <codex|claude|kimi|grok|pi> [args...]（所有原生参数如 -c 等原样透明传递）
  - setup / --setup：配置 Codex/Claude，然后启动
  - clear：还原原生配置
- 只写配置、不启动：cpac setup [claude|codex]；查看当前：cpac setup
已安装后升级：npm 发布新版本后，等 publish 成功再执行 cpac upgrade。它会按需 npm install -g，再对已接入的 Codex / Pi / Kimi / Grok 做 sync。不要拆成 npm install -g @yhong91/cpac 再手动 cpac sync。只刷新配置、不升 CLI 时才用 cpac sync。

失败处理：任何一步报错时先跑 cpac status；密钥未配置回到步骤 2；注入后异常用 cpac <agent> clear 或 cpac restore <codex|pi|kimi|grok> 恢复原配置。

首次引导

无参数运行 cpac 会显示当前 CPA、密钥状态和可用命令：

CPA Companion

CPA: http://124.223.178.52:8317
CPA_API_KEY: configured / not configured

Commands:
  cpac <agent> [args...] Launch an agent through CPA
  cpac setup            Show current Codex/Claude setup
  cpac status            Show agent support status
  cpac restore <codex|pi|kimi|grok> | --all  Detach injected agents
  cpac --help            Show command usage

默认 CPA 地址内置为 http://124.223.178.52:8317，不需要创建 ~/.config/cpac/。

若 CPA_API_KEY 尚未设置，交互式引导会隐藏输入密钥，并将受 CPAC 标记管理的 export 区块写入当前 shell 的启动文件：

| Shell | 写入位置 | | --- | --- | | zsh | ~/.zshrc | | bash（macOS） | ~/.bash_profile | | bash（Linux 等） | ~/.bashrc | | sh / dash / ksh | ~/.profile |

写入内容形如：

# >>> CPAC CPA_API_KEY >>>
export CPA_API_KEY='...'
# <<< CPAC CPA_API_KEY <<<

CPAC 会保留启动文件中的其他设置；再次运行引导配置密钥时，受管区块会原位更新，不会重复追加。写入后按引导提示打开新终端，或在当前终端执行：

source ~/.zshrc # 使用引导实际显示的文件

程序无法直接修改已经运行的父 shell，所以 source 或新终端仍然是必要的。

也可以跳过引导，自行设置：

export CPA_API_KEY='...'

命令

引导和帮助

cpac
cpac --help

统一管理（detect / install / sync / restore / uninstall / upgrade）

参考 vibetime 的目标式命令，对 codex、pi、kimi、grok 四个持久注入目标统一管理（claude 是临时接管，用 cpac claude 启动，不属于 install 目标）：

cpac detect [--json]
cpac install [codex|pi|kimi|grok...] [--all] [--dry-run] [--force] [--v2_off] [--v2_models] [--max_context]
cpac sync [codex|pi|kimi|grok...] [--all] [--dry-run] [--v2_off] [--v2_models] [--max_context]
cpac restore <codex|pi|kimi|grok...> | --all [--dry-run]
cpac uninstall [--dry-run]
cpac upgrade [--check]
cpac -v | --version

detect 列出每个目标是否被检测到、是否已接入 CPAC；--json 输出机器可读结果。
install 默认作用于检测到的目标；后面直接写 agent 名（cpac install codex pi），--all 全部。codex 写入 catalog 并拉起 loopback 代理；pi/kimi/grok 写入各自配置。--dry-run 只打印将要做的事，--force 允许重装已安装目标。
sync 按当前 cpa_url 和 CPA 目录强制刷新已经接入的目标（Codex 重新注入、Pi 按 CLI 版本决定写入 packages / pi update / 跳过，并清理旧的 extensions/pi-cpac.ts、Kimi 配置重写），用来在 CPA 地址或模型目录变化后一次对齐本地配置。不带参数只动已安装目标；--all 会对检测到的目标做同样的强制刷新（尚未安装的会装上）。--max_context 仍只对 cpac install codex 有效。
Codex 注入默认开启 multi-agent v2（写入 [features.multi_agent_v2] enabled = true，catalog 行打 multi_agent_version: "v2"）；install codex --v2_off 关掉 toml 并去掉 catalog 戳。v2 开着时会剥掉 [agents] max_threads（Codex 否则拒启动）。cpac status 对照 config 里的 v2_off / max_context 和 live toml / catalog。服务端还需在 CPA 配置中开启 codex.optimize-multi-agent-v2。
--v2_models 进入 arrow-key 复选框选择最多 5 个 spawn_agent 模型（勾选顺序即推荐顺序），选择结果存入配置文件的 spawn_models，注入时把这些模型排到 codex-models.json 最前——Codex 客户端只把 catalog 前 5 个可见模型广告为 spawn 覆盖项。
restore 必须带 agent 名或 --all，卸掉指定（或全部）已注入目标。--all 时未安装的目标静默跳过。
uninstall 先用和 cpac setup codex 相同的方向键选择器确认（默认 Cancel），再 restore --all，最后 npm uninstall -g @yhong91/cpac。不要跟 agent 名；卸载的是 cpac 包本身。非终端取消。--dry-run 跳过确认。
upgrade 是发布后更新本机的一次性入口：查 npm → 需要时 npm install -g → 对已接入的 Codex / Pi / Kimi 执行 sync。已是最新也会 sync。不要先手动 npm install -g 再 cpac sync。--check 只报告版本，不安装也不 sync。没有已安装目标时跳过 sync，不报错。只刷新配置、不升 CLI 时用 cpac sync。

Claude Code

通过 CPA 启动 Claude Code，后续所有原生参数原样传递（如 -c 继续会话、--model 等）：

cpac claude
cpac claude -c                         # 继续上一次对话（原生 -c 原样直通）
cpac claude --model claude-sonnet-4-5
cpac claude -- -p "检查当前项目"

配置与清除

cpac setup claude                      # 交互式依次配置 Sonnet / Haiku / Opus（不启动）
cpac claude setup                      # 同上，完成后启动
cpac claude clear                      # 重置所有覆盖，恢复自动选择

未设置的槽位启动时自动选择：claude 池内同家族模型优先，否则按 gemini → grok → luna → 目录第一个回退；opus 无匹配则不设。

所有设定写入配置文件持久缓存，每次 cpac claude 启动自动生效。

--opus / --sonnet / --haiku 对应 ANTHROPIC_DEFAULT_*_MODEL（haiku 同时写入 ANTHROPIC_SMALL_FAST_MODEL）。旧版的 --classifier 已移除：CLAUDE_CODE_AUTO_MODE_MODEL 在 Claude Code 2.1.224 上不被读取，Auto mode 分类器由官方自选（默认 Sonnet 5）；现版本唯一能影响分类器替身的旋钮是 --sonnet（副作用：同时改 sonnet 别名）。完整选择顺序、回退规则与出处见 docs/claude-auto-mode-classifier.md。

你自己 export 同名环境变量时以你为准。

Claude Code 的发现协议不携带 context 信息，claude 前缀的未知模型默认按 200K 记账，且 CLAUDE_CODE_MAX_CONTEXT_TOKENS 对 claude 前缀的名字不生效。cpac 采用与 opencodex 相同的机制：目录里窗口足够大的别名模型会带 [1m] 标记出现在选择器中（Claude Code 按 1M 记账，发请求前自己剥掉标记），同时 cpac claude 注入 CLAUDE_CODE_AUTO_COMPACT_WINDOW（默认 350K，与 opencodex 一致，接受范围 100K–1M）作为压缩阈值。你自己 export 该变量时以你为准。claude 系模型如需 1M 窗口，在模型名后加 [1m]（如 cpac claude --model claude-sonnet-4-6[1m]）。

CPA 服务端必须支持 Claude Code 使用的 Anthropic Messages API（/v1/messages）。

Codex

启动 Codex，后续所有原生参数原样传递（如 -c 动态覆盖配置、exec 等）：

cpac codex                             # 自动确保注入和代理后拉起 Codex
cpac codex -c model="gpt-5"            # 动态覆盖 Codex 配置（原生 -c 原样直通）
cpac codex exec "帮我写一个测试"

配置与清除

cpac setup codex                       # 交互式配置后注入（不启动）
cpac codex setup                       # 同上，完成后启动 Codex
cpac codex clear                       # 还原 Codex 原生配置并关闭代理

注入（`cpac install codex`）

cpac install codex [--v2_off] [--v2_models] [--max_context]
cpac restore codex

install codex 从远端 /v1/models?client_version=1 获取 Codex rich catalog，并启动只监听 127.0.0.1 的轻量转发代理。Codex 配置保留内置 openai provider，只写入根级 model_catalog_json 和：

openai_base_url = "http://127.0.0.1:10101/v1"

Codex App/CLI 发给本地代理的 ChatGPT bearer 不会转发到 CPA；代理会改用 CPA_API_KEY，并将请求和流式响应原样转发到远端 CPA。这保留了 Codex App 的原生 openai provider 身份、历史和账号相关界面。已有用户自定义根级 openai_base_url 或非 openai 的活动 model_provider 时，CPAC 会拒绝覆盖。

Codex App 的长驻 app-server 可能缓存旧目录。注入会删除 models_cache.json；如果选择器仍未更新，请重启 Codex App。

注入命令可选 --max_context（cpac install codex --max_context，默认不带）：把 catalog 中 max_context_window 高于 context_window 的模型提升到上限，并把 auto_compact_token_limit 设为上限的 90%。Codex 把 context_window 当输入预算而非展示标签，上游默认保留保守运营值（如 GPT-5.6 家族 272k），带上该参数后可用到实测上限（约 921k，opencodex 实测）；90% 压缩线确保在硬上限前触发 auto-compact。不带参数注入的仍是原本上下文的目录。该参数仅限 codex，与其他 target 组合使用会直接报错。

config.toml 不存在时拒绝注入。当前是 native 时把原文件备份到 state_dir/codex/config.toml（覆盖更旧的 native 快照）；已注入后再装不覆盖备份。kimi/grok 同样：没有旧配置不写空备份，native 覆盖旧快照，已接入则保留。Pi 只改 settings.json 的 packages，不备份。restore codex：若 config.toml 相对注入未改，按原 mode 逐字节还原备份；若用户在注入期间改过文件，只撤掉 CPAC 写入的 catalog、url 和标记。没有其它需要代理的 agent 时才关闭代理。

loopback 代理是 detached 用户进程，不安装系统服务。机器重启或进程意外退出后，cpac status 会报告 loopback proxy stopped；重新执行 cpac install codex 或 cpac kimi / cpac grok 即可恢复。

默认路径：

Codex 配置：$CODEX_HOME/config.toml，未设置 CODEX_HOME 时为 ~/.codex/config.toml
CPAC state：~/.cpac/state.json（公用 proxy 字段 + 已接入 agent 记录）
各 agent 配置备份：~/.cpac/<agent>/<原文件名>
  Codex  ~/.cpac/codex/config.toml
  Kimi   ~/.cpac/kimi/config.toml
  Grok   ~/.cpac/grok/config.toml
restore / `<agent> clear` 会删掉该 agent 的备份目录和 state.json 里的对应记录

为防止误删或覆盖，state_dir 不能是文件系统根目录、用户 home、系统临时目录，也不能包含 Codex 配置文件。

Pi

cpac install pi
cpac pi

未接入时把 npm:@yhong91/cpac 写入 ~/.pi/agent/settings.json 的 packages。已接入则比较 ~/.pi/agent/npm/node_modules/@yhong91/cpac 与当前 CLI 版本：落后则 pi update npm:@yhong91/cpac，已是最新（或尚未下载副本）则跳过。cpac pi 启动前走同一套判断。Pi 启动时加载 extensions/pi-cpac.ts 从 CPA 动态注册模型。旧版 ~/.pi/agent/extensions/pi-cpac.ts 会在 install / restore 时删掉。

卸载：cpac restore pi 或 cpac pi clear。尊重 PI_CODING_AGENT_DIR。

Kimi Code

写入 CPA provider 配置到 Kimi Code：

cpac kimi install

它在 ~/.kimi-code/config.toml 追加一个由 CPAC 管理的块，注册 cpac OpenAI 兼容 provider，并把 CPA 目录里的每个模型映射为一个 cpac/<模型名> 条目。带 supported_reasoning_levels 的模型会写入 capabilities、support_efforts 和 default_effort，否则 Kimi 只给 Claude 名套内置 thinking profile，其它模型会停在 thinking off 且无法改 effort。base_url 指向共享 loopback 代理，因此密钥不落盘。install 会写入 state.json 并在需要时启动代理，不必先单独注入 Codex。卸载与状态：

cpac restore kimi

Kimi Code 配置目录尊重 KIMI_CODE_HOME 环境变量。首次写入前若 config.toml 已存在，会在 state_dir/kimi/config.toml 保留一份原始快照（只存最早版本），万一文件损坏可手动复制回去。

环境变量

| 变量 | 默认值 | 作用 | | --- | --- | --- | | CPA_API_KEY | 无 | CPA Bearer key；可由 cpac 首次引导写入 shell 启动文件 | | CPA_BASE_URL | http://124.223.178.52:8317 | 覆盖内置 CPA 地址 | | PI_CODING_AGENT_DIR | ~/.pi/agent | 覆盖 Pi agent 目录（影响 settings.json 写入位置） | | KIMI_CODE_HOME | ~/.kimi-code | 覆盖 Kimi Code 目录（影响 cpac kimi install 写入位置） | | CPAC_CONFIG | ~/.config/cpac/config.json | 指定可选 JSON 配置路径 | | CODEX_HOME | ~/.codex | Codex home 目录 |

CPAC CLI 可临时覆盖 CPA 地址：

CPA_BASE_URL='https://cpa.example.com' cpac claude

Pi 扩展只从进程环境读取 CPA_BASE_URL（默认内置地址）和 CPA_API_KEY；不读取 config.json 的 cpa_url，也不读用户 home 中的私有文件。

可选 JSON 配置

默认场景不需要配置文件，文件不存在时 CPAC 直接使用内置默认值，也不会创建目录。仅在需要覆盖 Codex 路径、state 目录或密钥变量名时创建配置，例如：

{
  "cpa_url": "https://cpa.example.com",
  "api_key_env": "CPA_API_KEY",
  "codex_config": "~/.codex/config.toml",
  "codex_proxy_port": 10101,
  "state_dir": "~/.cpac"
}

支持字段：

cpa_url：可选，绝对 http(s) URL，可带或不带 /v1
api_key_env：可选，密钥环境变量名，默认 CPA_API_KEY
codex_config：可选，Codex 配置路径
codex_proxy_port：可选，本地 Codex 转发端口，默认 10101；设为 0 时自动选择空闲端口
state_dir：可选，CPAC state 路径

使用自定义配置：

cpac install codex --config ./cpac.json
cpac claude --config ./cpac.json -- --model claude-sonnet-4-5

也可以设置：

export CPAC_CONFIG=/path/to/cpac.json

安全行为

API key 不写入 CPAC JSON、Codex 配置、备份、state、catalog 或日志。
Codex loopback 代理仅监听 127.0.0.1，拒绝非本地浏览器 Origin，并在内存中用 CPA key 替换入站 Authorization。
引导输入不回显，写入 shell 时会正确引用特殊字符。
shell 启动文件和 Codex 配置均通过同目录临时文件原子替换。
CPA 请求失败、catalog 无效或 key 缺失时，首次注入不会修改 Codex 配置。
restore 只删除 CPAC 自有的 state、backup 和 catalog，不删除 state_dir 中的其他文件。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

CPA Companion (cpac)

要求

安装

快速上手

Agent 自动化安装指南

首次引导

命令

引导和帮助

统一管理（detect / install / sync / restore / uninstall / upgrade）

Claude Code

配置与清除

Codex

配置与清除

注入（cpac install codex）

Pi

Kimi Code

环境变量

可选 JSON 配置

安全行为

注入（`cpac install codex`）