/proxy-local-ai-subscriptions

name: proxy-local-ai-subscriptions
description: 当用户希望把本机 Codex、ChatGPT Codex 或 Claude Code 订阅通过 localhost 暴露为 OpenAI 兼容端点，或希望在代理验证成功后把它添加成 NextClaw 自定义 provider 时使用。负责 CLIProxyAPI 安装检查、安全配置、OAuth 登录、Homebrew/systemd 持久托管、重启存活验收、NextClaw provider 事务式写入与 NCP 真实对话验收；不用于公网共享、转售、绕过配额或多用户账号池。

Proxy Local AI Subscriptions

把本机订阅接成受保护的 OpenAI 兼容端点，并在用户明确同意后接入 NextClaw。代理运行时固定使用 [router-for-me/CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)；本 skill 只负责接入、校验和故障诊断，不复制代理实现。

安全边界

• 只绑定 `127.0.0.1`，不支持公网、局域网、容器跨主机或反向隧道暴露。
• 只供当前用户本人使用。若用户要求共享账号、转售、规避订阅限制或绕过配额，停止并建议使用官方 API。
• OAuth token 只保存在 CLIProxyAPI 的 auth 目录；NextClaw 只保存代理生成的本地 API key。
• 不在命令行参数、聊天回复或日志里展示 API key。所有 bundled scripts 通过 mode `0600` 的 key 文件交换密钥。
• 当前审计与真实验收基线是 CLIProxyAPI `v7.2.90`。`check` 只自动接受 `7.2.x`；其他版本必须重新审计官方配置和登录合同后，才可用 `--allow-unaudited-version` 继续。
• Marketplace 安装只复制 skill 文件，不代表代理已经安装或登录。必须完成下面的真实验证后才能宣告可用。
• CLIProxyAPI 必须由 macOS Homebrew services 或 Linux systemd 独立托管。`nohup`、shell 后台 `&`、NextClaw 工具进程或一次端口可达都只能用于诊断，不能作为完成状态。

工作流

1. 先做只读检查

确认操作系统、`cliproxyapi`、`nextclaw` 和当前服务状态。不要先改配置或重启服务。

macOS 首选官方 Homebrew formula：

brew info cliproxyapi --json=v2

若缺失，说明将安装第三方 MIT 工具及其用途，得到用户同意后执行：

brew install cliproxyapi

Linux 必须使用 CLIProxyAPI 官方发布物或官方安装说明，并把真实二进制路径显式传给 bundled scripts；服务必须使用第 4 步生成的独立 systemd unit。Windows 尚无持久服务合同，不得在 Windows 上继续到 provider 写入或宣告完成。

2. 生成 localhost-only 配置

从本 skill 目录运行：

node scripts/cliproxy.mjs write-config \
  --config "$(brew --prefix)/etc/cliproxyapi.conf" \
  --auth-dir "$HOME/.cli-proxy-api" \
  --api-key-file "$HOME/.cli-proxy-api/nextclaw-api-key"

Linux 把配置、API key 与 OAuth auth 目录放在将要运行服务的普通用户 home 内，并以该用户执行配置生成；不要让 root 创建 mode `0600` 文件后再让普通用户服务读取。例如：

sudo -u <service-user> -H node scripts/cliproxy.mjs write-config \
  --config <service-home>/.cli-proxy-api/cliproxyapi.conf \
  --auth-dir <service-home>/.cli-proxy-api \
  --api-key-file <service-home>/.cli-proxy-api/nextclaw-api-key

`<service-user>` 与 `<service-home>` 必须来自机器上的真实账户信息，不得猜测；配置、OAuth 和 systemd unit 始终复用这一组值。

脚本会生成本地 API key、把 key 与配置设为 `0600`、关闭管理 API/控制面板，并把 factory template 自动备份后替换。若配置属于用户已有环境，脚本会拒绝覆盖；先解释差异并取得明确同意，才可加 `--force`。不要手写 YAML，也不要绕过备份保护。

若已存在运行中的 CLIProxyAPI，修改或重启前先告知会短暂中断该代理。不要擅自复用另一个实例的端口、auth 目录或 API key。

3. 完成订阅 OAuth

Codex：

cliproxyapi \
  --config "$(brew --prefix)/etc/cliproxyapi.conf" \
  --codex-login

Claude Code：

cliproxyapi \
  --config "$(brew --prefix)/etc/cliproxyapi.conf" \
  --claude-login

Linux 登录命令也必须以同一个 `<service-user>` 执行，并使用上一步的配置路径：

sudo -u <service-user> -H cliproxyapi \
  --config <service-home>/.cli-proxy-api/cliproxyapi.conf \
  --codex-login

没有图形浏览器时加 `--no-browser`，把官方 OAuth URL 交给用户本人完成。不要读取、复制或展示 token 文件内容。默认只登录用户指定的一个账号；不要主动建立多账号轮询池。

4. 启动并验证代理

macOS Homebrew：

brew services start cliproxyapi

如果服务已在运行且配置发生变化，先告知影响，再执行 `brew services restart cliproxyapi`。

Linux systemd：创建或更新 unit、启动服务会改变系统运行状态；先向用户说明影响并获得同意，然后使用 bundled script，禁止手写 unit：

sudo node scripts/cliproxy.mjs install-systemd \
  --binary <absolute-cliproxyapi-path> \
  --config <service-home>/.cli-proxy-api/cliproxyapi.conf \
  --auth-dir <service-home>/.cli-proxy-api \
  --service-user <service-user> \
  --home <service-home>

脚本只管理带有本 skill marker 的 `cliproxyapi.service`；遇到已有非托管 unit 时默认停止，只有解释差异并取得明确同意后才能使用 `--force`。unit 固定 `Restart=on-failure`、`WantedBy=multi-user.target`，并在安装后验证 active、enabled、MainPID 与独立 cgroup。

先做就绪检查。macOS：

node scripts/cliproxy.mjs check \
  --config "$(brew --prefix)/etc/cliproxyapi.conf" \
  --endpoint http://127.0.0.1:8317/v1 \
  --api-key-file "$HOME/.cli-proxy-api/nextclaw-api-key" \
  --service-manager homebrew \
  --service-name cliproxyapi

Linux：

node scripts/cliproxy.mjs check \
  --config <service-home>/.cli-proxy-api/cliproxyapi.conf \
  --endpoint http://127.0.0.1:8317/v1 \
  --api-key-file <service-home>/.cli-proxy-api/nextclaw-api-key \
  --binary <absolute-cliproxyapi-path> \
  --service-manager systemd \
  --service-name cliproxyapi.service

从输出的 `models` 中选择真实存在的模型，再跑 Responses API 真实回复：

node scripts/cliproxy.mjs smoke \
  --endpoint http://127.0.0.1:8317/v1 \
  --api-key-file "$HOME/.cli-proxy-api/nextclaw-api-key" \
  --model <raw-model-id>

首次 smoke 成功后，必须在用户已知会发生短暂中断的前提下执行一次托管重启验收。复用前述所有路径和 service 参数：

node scripts/cliproxy.mjs restart-smoke \
  --config <config-path> \
  --endpoint http://127.0.0.1:8317/v1 \
  --api-key-file <api-key-file> \
  --model <raw-model-id> \
  --service-manager <homebrew-or-systemd> \
  --service-name <service-name> \
  --binary <cliproxyapi-path>

Homebrew 可省略 `--binary`；systemd 必须给绝对路径。只有 `check.ok=true`、`lifecycle.active=true`、`lifecycle.enabled=true`、模型列表非空，以及 `restart-smoke.restartVerified=true` 且回复精确命中 marker，才算代理可持续使用。Linux 还必须满足 `lifecycle.independentFromNextclaw=true`。失败时按 `binary -> config safety -> service manager -> OAuth model list -> Responses API` 顺序缩圈，不要跳过上游直连就改 NextClaw。

5. 询问是否接入 NextClaw

代理真实回复成功后，必须明确询问：

> 本地 OpenAI 兼容端点已经验证成功。是否现在把它添加为 NextClaw provider？

用户没有明确同意时停止，不写 NextClaw 配置，也不改变默认模型。

接入前只选择一次 provider id，并在配置、模型 route 与 NCP 验收中始终复用它。provider id 是用户可自定义的 NextClaw 配置实例名，不是固定协议名：仅接 Codex 时推荐 `codex-sub`，仅接 Claude Code 时推荐 `claude-sub`；同一端点承载两类订阅时询问用户名称，推荐 `local-ai-subscriptions`。用户指定其他 kebab-case 名称时直接使用，不要改回预设名。

用户同意后执行：

node scripts/nextclaw-provider.mjs \
  --endpoint http://127.0.0.1:8317/v1 \
  --api-key-file "$HOME/.cli-proxy-api/nextclaw-api-key" \
  --proxy-config <config-path> \
  --service-manager <homebrew-or-systemd> \
  --service-name <service-name> \
  --proxy-binary <cliproxyapi-path> \
  --provider-id <provider-id> \
  --display-name "<display-name>" \
  --model <raw-model-id>

脚本默认从 `nextclaw status --json` 读取当前 API 地址，并使用 `wireApi=chat`。macOS Homebrew 可省略 `--proxy-binary`；Linux systemd 必须传绝对路径。脚本会先调用同包 `cliproxy.mjs check`，选择真实模型后再强制执行一次 `rest