---
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：

```bash
brew info cliproxyapi --json=v2
```

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

```bash
brew install cliproxyapi
```

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

### 2. 生成 localhost-only 配置

从本 skill 目录运行：

```bash
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` 文件后再让普通用户服务读取。例如：

```bash
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：

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

Claude Code：

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

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

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

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

### 4. 启动并验证代理

macOS Homebrew：

```bash
brew services start cliproxyapi
```

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

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

```bash
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：

```bash
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：

```bash
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 真实回复：

```bash
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 参数：

```bash
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 名称时直接使用，不要改回预设名。

用户同意后执行：

```bash
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`，选择真实模型后再强制执行一次 `restart-smoke`；未证明服务 active、enabled、独立托管且重启后真实回复成功时，在任何 provider API 请求前停止，因此不能绕过持久服务门禁。直接调用脚本且省略 `--provider-id` 时，为兼容既有用法仍默认 `local-subscriptions`；标准 skill 工作流必须显式传入上一步选定的 id，不能依赖该默认值。代理直连仍用 Responses API 证明 OpenAI 端点成立，但 NextClaw `native` 会携带工具定义；本次真实验收确认 Chat Completions wire 能保持工具 schema 兼容。脚本会先对候选配置执行真实 provider test，成功后才启用；新建 provider 在失败时自动删除回滚。若同名 provider 已指向其他端点，必须先解释冲突并获得同意，才可加 `--replace-existing`。

随后必须走 `native` session type 做一次 NCP 真实对话：

```bash
node scripts/nextclaw-smoke.mjs \
  --model <provider-id>/<raw-model-id>
```

只有 provider test 和 NCP 最终回复都通过，才能说“已可在 NextClaw 使用”。不要因为 `/api/health`、模型列表或编译通过就宣告完成。

## 完成报告

报告以下事实，不输出任何 secret：

- CLIProxyAPI 版本、配置路径、auth 目录、监听地址；
- 服务管理器、服务名、active/enabled 状态；Linux 还要报告独立 cgroup 与重启存活验收；
- OAuth 类型（Codex 或 Claude），不要输出账号 token；
- 真实验证的 raw model id 与 OpenAI wire；
- 实际创建/更新的 provider id 与 display name；
- NCP session type 必须是 `native`，模型必须复用同一个 `<provider-id>/<raw-model-id>`；
- 未验证的平台或能力（例如本次只验 Codex，就明确 Claude 未做真实验收）。

## 故障与退出

- `check` 报非 localhost 配置：停止服务并修复绑定；不要带风险继续。
- `check` 报服务未 active/enabled 或 cgroup 不独立：停止 provider 接入，使用对应服务管理器修复；不要用 `nohup` 临时补位。
- `restart-smoke` 失败：保持或恢复代理服务，报告持久性验收未完成；不得创建 provider。
- `/v1/models` 为空：重新执行对应 OAuth 登录并检查 auth 目录，不要猜模型名。
- 代理直连成功但 provider test 失败：检查 `apiBase` 是否带 `/v1`、模型是否 provider-scoped、`wireApi` 是否为 `chat`。
- provider test 成功但 NCP 失败：按 NextClaw NCP SSE 链路排查；不要把问题归因成 OAuth 已失效。
- 删除 provider、恢复备份配置、注销 OAuth 或卸载 CLIProxyAPI 都是破坏性动作，只在用户明确要求后执行。