SubRouter 是一个 AI API 网关，提供单一 API Key、兼容 OpenAI 与 Anthropic 的接口、按请求在多个供应商之间智能路由，以及按 token 的透明计费。本技能用于教会 AI 智能体如何端到端地把用户连接到 SubRouter。
基础地址：使用用户指定的站点，或默认的 https://subrouter.ai。
安全规则（不可协商）：API Key 只能发送给用户选择的 SubRouter 主机，绝不发往其他域名；调用时始终使用 --max-redirs 0，防止重定向把密钥带到别处；除用户要求的客户端配置外，绝不把完整密钥打印到日志或文件，确认时最多显示 sk-xxxx… 前缀；绝不让凭据进入标准输出，授权响应包含完整的 device_code、key 和 access_token，裸 curl 会把它们打印到终端和智能体记录中，应始终把响应写入 0600 权限的文件再读取字段；支付始终由用户在浏览器中完成，绝不处理卡号、加密种子或支付凭据。
第 0 步——先确认要改动什么：获取密钥和重新配置用户的编码智能体是两件不同的事，不能从前者推断后者。在开始前说明理解并取得确认，包括目标（仅账户、一次性调用、配置 SDK/应用、切换编码智能体的模型供应商）、目标文件（绝对路径、会话级还是持久化）、现有设置（先读取目标文件并说明已有内容，若已含凭据或供应商需先询问）。默认选择满足请求的最小侵入方案。对 Codex 尤其注意：多数 Codex 用户使用 ChatGPT 订阅登录而非 API Key，除非用户明确要求，不要写入 ~/.codex/config.toml、不要覆盖 ~/.codex/auth.json、不要替换现有 model_provider。绝不覆盖已有配置文件，应追加或写入新 profile，并告知如何回退。
第 1 步——设备授权（获取 API Key）：先查找已保存的凭据（如 ~/.subrouter/credentials.json），若用该 sk- 密钥请求 GET $BASE/v1/models 返回 200 则复用并跳到第 2 步。启动设备授权时 channel 标识智能体类型（claude、cursor、codex 等），同一 channel 重新授权会返回账户已有的授权令牌而非新建。所有 /api 端点结果都包裹在信封中，载荷在 data 下，与 success 并列；失败时 success 为 false，message 说明原因。/v1 端点则是原始 OpenAI/Anthropic 结构，不包裹。把响应写入私有文件而非直接打印，读取 .data.user_code 和 .data.verification_url 展示给用户，device_code 是机器持有的秘密，绝不能回显。让用户在浏览器打开 URL 登录并确认，代码 10 分钟内有效。然后按 .data.interval 秒轮询，根据 .data.status 分支：authorization_pending 继续等待，slow_down 放慢，approved 时 .data.key、.data.access_token、.data.user_id 和 .data.base_url 已填充且仅投递一次，success:false 且提示无效或过期则重新开始。保留凭据，把已批准的响应移到稳定私有文件（如 install -m 600 到 ~/.subrouter/credentials.json），任务结束时不要删除，令牌不过期，删除会导致下次重新走浏览器审批。三个值权限不同：key（sk-…）用于模型调用、/v1/models、计费查询，放入客户端配置；access_token 是账户管理凭据，绝不放入客户端配置，仅用于管理调用；user_id 是数字账户 id，非秘密但管理调用必需。
第 2 步——配置客户端：同一密钥在两种协议面上都可用。Claude Code（Anthropic 协议）设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY；OpenAI SDK / Cursor / Codex（OpenAI 协议）设置 OPENAI_BASE_URL 为 $BASE/v1 和 OPENAI_API_KEY。核心端点：POST /v1/chat/completions、POST /v1/messages、GET /v1/models。sk 密钥还支持多模态：音频 POST /v1/audio/transcriptions、/v1/audio/speech、/v1/audio/translations；其他 POST /v1/embeddings、/v1/rerank、/v1/moderations、/v1/responses、GET /v1/realtime（WebSocket）。
第 2b 步——图像和视频使用异步任务 API：图像和视频生成耗时数十秒到数分钟，同步调用会长时间占用 HTTP 连接导致 504 或 502。视频任何模型始终异步；多张图像、批量或无人值守用异步；单张图像且用户交互等待可同步。计费规则：每次成功生成都计费，包括重试；每个用户请求只提交一次；重试是新收费，需明确告知并取得同意（提交前失败除外）；绝不丢弃已计费产物，每个完成任务输出都要写盘，用不同文件名；及时下载完成结果，上游 URL 会过期；提交前校验尺寸、时长和模型能力；结束时报告提交次数、模型、尺寸/时长、总成本和保存文件绝对路径。连接中断不要重新提交，通过 GET /api/task/self 恢复。提交图像在正常路径后加 /async，返回 202 和 Location 头及 media.task 体；视频 POST /v1/video/generations 本身异步，POST /v1/videos 是 OpenAI 兼容别名。轮询用 GET /v1/tasks/<task_id>，状态为 pending、processing、completed、failed，间隔不低于 2–3 秒。下载视频用 GET /v1/videos/<task_id>/content。
第 3 步——选择模型和供应商：价格和供应商市场公开无需认证，可查询 /api/pricing、/api/marketplace/models、/api/marketplace/providers 等，按用户偏好选择并展示候选让用户决定。
第 4 步——充值由用户在浏览器完成：先检查余额，仅在看到零/不足余额或收到 402 后引导用户到 $BASE/console/topup。
账户管理（使用 access_token）：管理端点需要两个头，Authorization: Bearer <access_token> 和 New-Api-User: <user_id>，两者都必需。可查询账户信息与余额、用量对账（日志默认今天，范围不超过 31 天）、每日配额用量、异步媒体任务、兑换码充值、推荐码与收益、列出/创建 API 令牌，以及创建限定模型、供应商和价格上限的令牌。