AI跃云 API CLI

用户侧终端工具，用于安装后在本机配置AI跃云 API Key、查询用量、测试线路，并把AI跃云 API endpoint 配置到 Codex CLI 与 Claude Code。

当前能力

• macOS / Linux：src/yueyun-cli.sh
• Windows PowerShell：src/yueyun-cli.ps1
• npm / npx：npx yueyun-cli
• 智能检测密钥模型系列，并自动配置兼容的 Codex CLI / Codex 桌面版或 Claude Code
• 查看 Key 用量摘要
• 测试 /v1/models 线路
• 写入官方配置文件前完整备份，支持恢复和重置

默认写入位置：

• AI跃云本机私密配置：~/.yueyun/
• Codex CLI / Desktop 官方配置：~/.codex/config.toml 中的 model_providers.yueyun，必要时的受控顶层 model_provider/model，以及 ~/.codex/yueyun.config.toml 的新版 profile 配置
• Claude Code 官方配置：~/.claude/settings.json 中的 env.ANTHROPIC_BASE_URL 与 apiKeyHelper
• 可选启动器：~/.local/bin/yueyun-codex、~/.local/bin/yueyun-claude-code

为兼容 Codex 桌面版启动，CLI 会把当前 OpenAI/GPT 主卡写入当前用户的桌面应用环境：macOS 使用 launchctl setenv，Windows 使用用户级环境变量。写入前会记录原值，restore 会恢复原值，reset 会恢复原值或移除AI跃云写入值。

CLI 只追加或更新AI跃云托管配置，不会删除用户已有的其他 Codex profile、provider 或 Claude Code settings。若 Codex 中已有非AI跃云托管的同名 yueyun provider、[profiles.yueyun] 或 yueyun.config.toml profile 文件，CLI 会停止写入，避免覆盖用户或 switch 管理的配置。

需要恢复官方 Codex / Claude Code 时，优先运行 yueyun-cli reset 移除AI跃云托管配置；也可以使用 cc-switch 等 switch 工具切回官方配置，或用用户自己的备份覆盖 ~/.codex/config.toml、~/.claude/settings.json。restore 用于恢复 CLI 最近一次写入前的快照，不等同于通用 switch。

用户配置流程

用户通过发货页提供的终端命令启动 CLI。命令不包含完整 Key。

快速使用指南

1. 前置条件

使用本工具需确保运行环境已安装 Node.js，建议 v16.0 及以上版本。未安装的用户可前往 Node.js 官方网站下载适配版本。

2. 执行命令

完成环境准备后，只需在终端 / 命令行中执行：

npx yueyun-cli

终端页面会提供：

• 智能检测密钥并配置兼容应用（推荐）
• 只配置 Codex CLI / Codex 桌面版
• 只配置 Claude Code
• 查询 Key 余额
• 查看用量、测试线路、离线诊断、备份、恢复和重置
• 充值（叠卡）

用户选择配置目标后，在本机终端输入AI跃云门户发售的 Key 卡密。CLI 会先调用公开 HTTP API 验证 Key 状态、可调用性和模型系列，验证通过后才写入本机配置。Sub2API 原生用户自己创建的普通 native key 不作为门户 Key 配置。

密钥按模型系列区分，CLI 会自动判断后端返回的 family：

• family=openai：配置 Codex CLI / Codex 桌面版，默认使用 OpenAI Responses 兼容接口。
• family=claude：配置 Claude Code，默认使用 Anthropic Messages 兼容接口。
• 显式选择了不兼容应用时，CLI 会用中文提示并拒绝写入本机配置。

完整 API Key 只在用户本机交互输入，不应放入可转发安装命令、工单、日志或截图。

本地运行

通过 npm/npx 入口运行：

npx yueyun-cli

源码调试时也可以直接运行：

bash src/yueyun-cli.sh

pwsh -NoProfile -ExecutionPolicy Bypass -File src/yueyun-cli.ps1

也可以直接执行单个动作：

YUEYUN_API_KEY="sk-..." \
bash src/yueyun-cli.sh usage

API 端点配置

正常用户流程不要求用户输入端点。生产发布包内置AI跃云线上公开 API 根地址 https://api.yue-yun.com，用户只需要执行 npx yueyun-cli 并在终端输入密钥。

YUEYUN_API_ENDPOINT 只用于开发、测试或高级手动覆盖：

• 生产默认 endpoint 是 https://api.yue-yun.com，普通用户不需要设置 YUEYUN_API_ENDPOINT。
• 手动覆盖值必须是 HTTPS 根地址，不要带 /v1，也不要带用户密钥。
• 本地源码测试可使用 http://127.0.0.1:18080，但必须同时设置 YUEYUN_ALLOW_INSECURE_LOCAL=1。
• Codex 配置会自动把根地址补齐为 /v1；例如 http://127.0.0.1:18080 会写成 http://127.0.0.1:18080/v1。
• Claude Code 配置使用根地址 https://api.yue-yun.com，不额外追加 /v1。
• 正式发布前不得保留示例占位 endpoint。

常用动作：

bash src/yueyun-cli.sh configure
bash src/yueyun-cli.sh configure-codex
bash src/yueyun-cli.sh configure-claude
bash src/yueyun-cli.sh balance
bash src/yueyun-cli.sh usage
bash src/yueyun-cli.sh test
bash src/yueyun-cli.sh stack
bash src/yueyun-cli.sh backup
bash src/yueyun-cli.sh restore
bash src/yueyun-cli.sh reset

renew 和 redeem 动作暂未开放给用户菜单；当前请统一使用 stack 完成充值（叠卡）。

余额/用量优先读取门户接口 GET /api/custom/key/native-usage；该接口不可用时退回 GET /api/custom/key/me 展示基础余额。充值（叠卡）只由后端判定是否允许。CLI 不判断来源 Key 是否为主卡、是否同分组、日卡/订阅卡是否兼容、是否已激活、已绑定或已使用；它只把来源 Key 提交给后端，并展示成功结果或脱敏后的中文失败提示。

配置完成后，推荐使用启动器。Codex 启动器会从本机私密配置加载当前 OpenAI/GPT 主卡并调用官方 profile；Claude Code 启动器会清理旧认证环境变量，并通过 apiKeyHelper 从本机私密配置读取当前 Claude 主卡，避免登录 token 与 API Key 冲突：

yueyun-codex
yueyun-claude-code

更换 Codex/GPT 主卡后，CLI 会写入 yueyun profile-v2 文件和托管兼容 profile。继续在当前窗口使用 Codex 时，推荐运行 yueyun-codex；也可以显式运行 codex --profile yueyun。启动器会固定使用本次写入的 Codex 配置目录，并清理旧 OpenAI/Claude 环境变量。如果配置前已有 switch 或用户自定义默认 provider，直接运行 codex 可能仍走原 provider，这是为了不破坏用户原配置；此时以 CLI 成功提示中的启动器路径为准。Codex Desktop 如已打开，需要完全重启后读取新的配置和桌面环境变量。

更换 Claude 主卡后，CLI 会更新 Claude Code 的 apiKeyHelper 和私密配置；推荐通过 yueyun-claude-code 启动，或重新启动 Claude Code 后读取当前主卡。不要手动同时设置 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY，否则 Claude Code 会提示认证冲突。

如果 Codex 报 429、断流、profile yueyun not found、请求落到 127.0.0.1，或不确定当前走的是哪个 provider，可以先运行离线诊断：

yueyun-cli doctor codex
yueyun-cli doctor claude

doctor 只读取本机配置，不联网、不写文件，并且只输出脱敏后的 Key 前后缀。

切回官方接口时，运行 yueyun-cli reset 后再使用官方登录或 switch 工具；不要依赖重新登录一定会清理第三方 profile，因为官方登录通常只处理认证状态，不保证删除第三方配置段。

Codex profile 默认模型为 gpt-5.3-codex，可在配置前通过 YUEYUN_CODEX_MODEL 覆盖；真实上线验收建议用 gpt-5.5 做 Codex 调用链路测试。

安装器

推荐的生产入口是 npm 包：

npx yueyun-cli

install.sh / install.ps1 仍保留为私有 HTTPS artifact 分发或应急安装入口。生产发布时，将 src/yueyun-cli.sh / src/yueyun-cli.ps1 上传到 HTTPS 静态地址，并把对应 SHA256 写入发布说明或 manifest。

macOS / Linux：

YUEYUN_CLI_DOWNLOAD_URL="https://yue-yun.com/.well-known/yueyun-cli/yueyun-cli.sh" \
YUEYUN_CLI_SHA256="<sha256>" \
bash install.sh

Windows PowerShell：

$env:YUEYUN_CLI_DOWNLOAD_URL="https://yue-yun.com/.well-known/yueyun-cli/yueyun-cli.ps1"
$env:YUEYUN_CLI_SHA256="<sha256>"
pwsh -NoProfile -ExecutionPolicy Bypass -File install.ps1

验证

make test

没有 pwsh 的环境会跳过 PowerShell 语法检查和 Windows 版测试。

需要用真实测试 Key 做端到端沙盒验证时，使用任意公开 API 兼容沙盒端点；本地源码后端只是可选端点示例：

YUEYUN_ALLOW_INSECURE_LOCAL=1 \
YUEYUN_REAL_API_ENDPOINT="http://127.0.0.1:18080" \
YUEYUN_REAL_API_KEY="<本机测试密钥>" \
make test-real-sandbox

该脚本会使用临时 HOME，不会修改当前用户真实的 Codex 或 Claude Code 配置。脚本会验证余额、用量、线路测试、备份、恢复、重置，并从沙盒配置文件反读端点和密钥发起一次真实模型调用；输出会检查不得泄露完整密钥。

真实模型调用会按测试 Key 产生少量消耗。叠卡只做公开契约烟测：如需验证成功或拒绝路径，显式提供 YUEYUN_REAL_STACK_SUCCESS_KEY 或 YUEYUN_REAL_STACK_REJECT_KEY；来源 Key 是否可叠、是否同组同策略、是否已激活或已绑定，仍由后端测试覆盖。

与 sub2api-business 的接口契约

CLI 只依赖公开 HTTP API，不直接读取业务项目数据库或内部文件：

• POST /api/custom/key/activate
• GET /api/custom/key/me
• GET /api/custom/key/native-usage
• POST /api/custom/key/stack
• GET /v1/models

业务仓库可以继续通过发货响应或用户门户展示安装入口，但 CLI 源码、测试和发布流程应在本仓库维护。