cpa-codex-auth-sweep-cliproxy

# 技能说明

此技能用于：

1. 通过 **CLI Proxy Management API 的认证文件接口** 获取授权（`/v0/management/auth-files`）
2. 使用 **管理端 API Call 能力**（`/v0/management/api-call` + `auth_index + $TOKEN$`）探测每个 Codex 授权状态（对齐 CLI Proxy 的刷新/代理链路）
3. 识别 401/失效凭证并在用户明确要求时清理

## 交互要求（必须）

在每次准备执行扫描前，必须先主动向用户询问并确认：

- `base_url`（CLI Proxy 管理端地址）
- `management_key`（管理密钥）

如果用户未提供这两个参数，禁止开始扫描；应先提示用户补全。

## 安全提示（必须阅读）

本技能通过管理 API 的 `api-call` 发起探测，请求头中使用 `Authorization: Bearer $TOKEN$`。这意味着 **管理端会把真实 token 转发到 `probe-url` 指向的主机**。

因此必须遵守：

1. 默认仅允许 `https://chatgpt.com/...` 作为探测目标。
2. 扫描前必须向用户确认 `probe-url`（若用户改过）。
3. 若要使用非白名单主机，必须得到用户明确授权，并显式传 `--allow-unsafe-probe-host`。
4. 禁止默认使用 `--insecure`；仅在内网排障且用户明确授权时，才可同时传 `--insecure --allow-insecure-tls`。

## 执行入口

```bash
python3 <SKILL目录>/scripts/cliproxy_scanner.py \
  --base-url "<CLI_PROXY_BASE_URL>" \
  --management-key "<MANAGEMENT_KEY>" \
  --output-json
```

常见用法：

```bash
# 只扫描，不删除
python3 <SKILL目录>/scripts/cliproxy_scanner.py \
  --base-url "<CLI_PROXY_BASE_URL>" \
  --management-key "<MANAGEMENT_KEY>" \
  --output-json

# 扫描 + 删除 401（需要明确删除意图）
python3 <SKILL目录>/scripts/cliproxy_scanner.py \
  --base-url "<CLI_PROXY_BASE_URL>" \
  --management-key "<MANAGEMENT_KEY>" \
  --output-json --delete-401 --yes
```

## 必要环境变量（Required）

- `CLIPROXY_BASE_URL`：CLI Proxy API 管理端地址（例：`http://localhost:8317`）
- `CLIPROXY_MANAGEMENT_KEY`：管理密钥（Management Key，主凭据 / primary credential）

> 两者缺一不可。

可选：

- `CLIPROXY_AUTH_FILES_ENDPOINT`：认证文件列表接口（默认：`/v0/management/auth-files`）
- `CLIPROXY_API_CALL_ENDPOINT`：管理 API Call 接口（默认：`/v0/management/api-call`）
- `CLIPROXY_AUTH_DELETE_ENDPOINT`：认证文...

# cpa-codex-auth-sweep-cliproxy

基于 CLI Proxy Management API 的 Codex 授权巡检/清理技能。

## 功能

- 从管理端读取认证文件（`/v0/management/auth-files`）
- 通过管理端 `api-call` + `auth_index` + `$TOKEN$` 探测每个授权
- 统计：
  - 总数
  - 失效（401）
  - 周限额为 0（weekly quota）
  - 状态码分布
- 可选：自动删除 401 对应认证文件

## 安全说明（重要）

`api-call` 模式会让管理端将真实 token 带到 `probe-url` 指向的目标。
因此本脚本默认启用以下保护：

- 仅允许 `https` probe URL
- 默认仅允许 host=`chatgpt.com`
- 非白名单 host 需显式 `--allow-unsafe-probe-host`（高风险）
- `--insecure` 需要二次确认 `--allow-insecure-tls`（高风险）

### 凭据声明

- **Primary credential**：`CLIPROXY_MANAGEMENT_KEY`
- **Required endpoint config**：`CLIPROXY_BASE_URL`
- 以上两项为执行必需输入

## 目录结构

```text
cpa-codex-auth-sweep-cliproxy/
├── SKILL.md
├── README.md
└── scripts/
    └── cliproxy_scanner.py
```

## 使用方式

### 1) 仅扫描

```bash
python3 scripts/cliproxy_scanner.py \
  --base-url "https://your-cliproxy.example.com" \
  --management-key "YOUR_MANAGEMENT_KEY" \
  --workers 120 \
  --progress \
  --output-json
```

### 2) 扫描并删除 401

```bash
python3 scripts/cliproxy_scanner.py \
  --base-url "https://your-cliproxy.example.com" \
  --management-key "YOUR_MANAGEMENT_KEY" \
  --workers 120 \
  --progress \
  --delete-401 --yes \
  --output-json
```

### 3) 自签证书环境

```bash
python3 scripts/cliproxy_scanner.py ... --insecure
```

## 关键参数

- `--base-url`：CLI Proxy 管理端地址（必填）
- `--management-key`：管理密钥（必填）
- `--workers`：并发数（默认 80）
- `--delete-401 --yes`：启用并确认删除 401
- `--insecure`：关闭 TLS 校验（仅内网调试建议）
- `--allowed-probe-hosts`：probe host 白名单（默认 `chatgpt.com`）
- `--allow-unsafe-probe-host`：允许使用非白名单 probe host（危险）
- `--progress-every`：进度输出间隔（默认每 10 条）

## 输出说明

`summary` 主要字段：

- `total`：参与探测的总数
- `unauthorized_401`：判定失效数量
- `weekly_quota_zero`：周限额为 0 数量
- `ok`...