Claude360 CLI

面向 Claude360 已注册用户的跨平台命令行工具，让不熟悉终端配置的用户也能一行命令完成 Claude Code / Codex 的安装、授权、Key 选择、余额查询、微信扫码充值与日常启动。

• 不要求用户在终端输入站点账号密码，授权全程在浏览器完成。
• 不修改 shell profile / PowerShell profile / 全局环境变量。
• 分组倍率、充值金额、API 凭证生命周期均以后端为唯一来源，CLI 不内置任何业务口径。
• 全部交互文字采用分层语义配色，自动适配 truecolor / 256 色 / 无色终端。

本仓库仅包含 CLI 客户端（Node.js）。其依赖的 /api/cli/* 后端接口由 Claude360 服务端提供，不在本仓库内。

目录

• 功能特性
• 系统要求
• 快速开始
• 首次配置流程
• 日常使用
• 终端配色体系
• 本地配置
• 后端接口契约
• Claude Code 与 Codex 集成
• 诊断与故障排查
• 开发与测试
• 项目结构
• 安全模型
• 致谢
• 许可证

功能特性

| 功能 | 说明 | | --- | --- | | 一行命令安装 | Windows PowerShell / macOS / Linux bash 一行命令拉起 bootstrap，自动检测 Node/npm 与全局 npm 权限 | | 方向键交互 | 全部菜单 / 选择 / 确认使用方向键导航（↑↓ 移动、Enter 确认、Esc 返回、空格多选、←→ 切换 YES/NO），非 TTY / CI 环境自动降级为编号输入 | | 分层语义配色 | 成功 / 失败 / 警告 / 信息 / 步骤 / 键值回显 / 路径 / 标题等按角色着色，层次分明；自动适配 truecolor / 256 色 / NO_COLOR | | 真实模型选择 | 模型列表来自 GET /api/cli/models（用户可用分组 × 模型元数据），展示模型 ID / 名称 / 标签 / 说明，保存真实 model id | | 浏览器设备授权 | 通过 /api/cli/auth/* 设备码流程换取受限 CLI 凭证，不接触账号密码 | | API Key 选择/创建 | 已有 Key 列表展示并选择；无 Key 时按后端分组倍率向导创建 | | 余额与分组展示 | 日常主菜单展示账户余额、当前 Key、当前分组与倍率（来自后端） | | 微信 Native 扫码充值 | 终端内渲染二维码；金额选项与最低充值额由后端返回，CLI 不内置 | | 启动 Claude Code | 自动注入 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，以子进程启动 | | 启动 Codex | 写入隔离的 Claude360 provider / profile 覆盖层配置，并以 codex --profile claude360 启动 | | 工具更新 | 菜单内更新 claude360 自身、Claude Code、Codex，全部需要二次确认 | | 一键完整初始化 | 登录、Key、安装/更新、API 注入、输出语言、提示词风格、工作流、MCP、模型、权限配置、连接测试、启动一站式向导 | | 推荐工作流 / Skill | 六步工作流、Git 指令、功能规划 UX、BMad 安装器等，写入 ~/.claude/commands/claude360/ 与 ~/.codex/prompts/，写前备份、冲突二次确认 | | 推荐 MCP | Context7 / Open Web Search / Spec 工作流 / DeepWiki / Playwright / Exa / Serena，多选安装、重依赖单独确认、同名去重 | | AI 输出语言 / 提示词风格 | 写入 ~/.claude/CLAUDE.md 或 ~/.codex/AGENTS.md 的 Claude360 标记区块，不覆盖用户内容 | | 配置备份 | 所有写入用户工具配置的操作先备份到 ~/.claude/backup/ 或 ~/.codex/backup/ 时间戳目录 | | 诊断报告 | OS/Node/npm/全局 npm 权限/工具版本/连通性/授权状态/余额/Key/支付端点一站式检查，按模块分组着色表格展示 | | cc-switch 配置生成 | 生成可导入 cc-switch 的供应商配置，支持完整 / 脱敏预览与本地保存（0600） |

系统要求

• Node.js 18+ 与 npm（没有时 bootstrap 脚本会经用户确认后通过系统包管理器 winget / brew / apt / dnf 安装 Node.js LTS；不修改 shell profile，不持久化环境变量）。
• 网络可达 https://claude360.xyz。
• macOS / Linux：当前用户对其 ~/.claude360/ 拥有写权限。
• Windows：当前用户对 %USERPROFILE%\.claude360\ 拥有写权限。
• 任何包管理或全局 npm 操作执行前都需要在 CLI 内显式确认。

快速开始

一行命令安装（推荐）

macOS / Linux：

curl -fsSL https://claude360.xyz/install.sh | bash

Windows PowerShell：

irm https://claude360.xyz/install.ps1 | iex

Bootstrap 脚本职责：识别 OS / 架构 → 检查 Node.js 与 npm（缺失或 < 18 直接退出并给出修复建议）→ 展示影响范围并要求确认 → npm install -g claude360@latest → claude360 setup 进入首次配置向导。

通过 npm 全局安装

npm install -g claude360@latest
claude360

从源码运行（开发者）

git clone https://github.com/Johnhpure/claude360cli.git
cd claude360cli
npm install
node ./bin/claude360.js          # 直接以源码模式运行
# 或链接到全局命令：
npm link && claude360

首次配置流程

┌───────────────────┐
│ 启动 claude360    │
└─────────┬─────────┘
          ↓
读取 ~/.claude360/config.json
          ↓
┌─ 无 cliToken ─┐   ┌─ 有 cliToken ─┐
│ 设备码授权    │   │ 跳过授权步骤  │
│ → 浏览器     │   └──────┬───────┘
│ → 轮询批准   │          │
└──────┬───────┘          │
       ↓                   ↓
读取或创建 API Key（按分组倍率向导）
       ↓
写入本地配置（mode 0600）
       ↓
进入主菜单

关键约束：

• 首次运行（无 cliToken）会先做环境检查（Node≥18 / npm / 全局 npm 权限），缺失或版本过低则给出修复指引并中止；CLI 自身不安装系统运行时（连 Node/npm 都没有的用户请使用上文 bootstrap 一键脚本）。
• 环境检查通过后进入工具安装引导（Claude Code / Codex / 两者 / 跳过），已安装的工具会标注，安装失败不阻断后续授权。
• 授权服务不可用（接口返回 404 或网络不可达）时给出友好提示并退出，已安装工具不受影响，可稍后运行 claude360 setup 重新完成授权与 Key 配置。
• 授权码短期有效；CLI 仅在浏览器无法自动打开时把 verification_url 与 user_code 输出到终端。
• 多个 Key 时展示：名称 / 脱敏 Key / 分组 / 状态 / 剩余额度（或无限额度）/ 过期时间。
• 无 Key 时，CLI 通过 /api/cli/groups 拉取分组并按 display_name（倍率 1.0x） 风格展示，由用户选择后调用 POST /api/cli/tokens 创建。

日常使用

主菜单按分组展示，TTY 环境下用 方向键 + Enter 选择（Esc 返回）；非 TTY / CI 环境自动降级为编号输入：

请选择功能：
─── 常用操作 ───
❯ 启动 Claude Code        使用 Claude360 接入配置直接启动
  启动 Codex              使用 Claude360 接入配置直接启动
─── 账户与充值 ───
  余额与充值              查看余额用量，支持微信扫码充值
  切换 Key / 模型         切换当前 API Key 或默认模型
  创建新的 API Key        在当前账号下新建一个 API Key
  打开 Claude360 控制台   在浏览器中打开网页控制台
─── Key / 模型 / MCP 配置 ───
  Claude Code 配置        完整初始化、工作流、MCP、模型与记忆配置
  Codex 配置              完整初始化、Provider、工作流与 MCP 配置
  一键完整初始化          Claude Code / Codex 完整初始化向导
  推荐 MCP / Skill        安装推荐的 MCP、工作流与 Skill 增强
  生成 cc-switch 配置     生成可导入 cc-switch 的供应商配置
─── 维护与设置 ───
  安装或更新工具          安装或升级 Claude Code / Codex / 本 CLI
  诊断与修复              一键诊断环境与配置问题并尝试修复
  重新登录                清除本地登录态后重新浏览器授权
  退出                    退出 claude360 CLI

• 余额与充值：调用 GET /api/cli/me 展示账号、余额、已用、当前 Key 名称与分组；充值先取 /api/cli/topup/options，按后端校验通过的金额或最低额提交，再用 qrcode-terminal 在终端渲染 code_url，渲染失败时降级为纯文本 URL。轮询订单状态，支付完成自动刷新余额。
• 启动 Claude Code：以 claude 子进程启动，并通过 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN 注入。
• 启动 Codex：写入 ~/.codex/config.toml 的 [model_providers.claude360] 与 profile 覆盖层 ~/.codex/claude360.config.toml，发现冲突字段会先要求用户确认再覆盖，然后 codex --profile claude360，并通过 CLAUDE360_API_KEY 注入。
• 安装或更新工具：三选一菜单（仅 Claude Code / 仅 Codex / 两者），每步都需要确认。
• 切换 Key / 模型：重新进入 Token 向导，或从 /api/cli/models 拉取真实模型列表选择默认模型。

终端配色体系

CLI 的全部行内交互文字通过统一的语义消息层（src/messages.js）输出，每种角色有专属颜色与符号前缀，形成清晰层级；色值集中在 src/colors.js 的单一主题中：

| 角色 | 符号 | 颜色 | 用途 | | --- | --- | --- | --- | | success | ✓ | 绿 | 操作成功 | | error | × | 红 | 失败 / 异常 | | warn | ! | 黄 | 警告 / 降级 | | step | → | 紫 | 进行中 / 步骤 | | info | — | 天蓝 | 中性信息 | | result | — | 灰蓝标签 + 亮白值 | 键值回显 | | path / hint | — | 灰阶 | 路径 / 次要说明 | | title / heading | — | 白 / 亮青（加粗） | 标题 |

着色能力自动探测：truecolor（24-bit）→ 256 色（量化）→ 无色。设置环境变量 NO_COLOR=1 可强制关闭颜色，FORCE_COLOR=2 可强制真彩色；非 TTY / 管道 / CI 输出默认为纯文本（不含 ANSI 序列），保证可被脚本解析。

本地配置

| 平台 | 路径 | | --- | --- | | macOS / Linux | ~/.claude360/config.json（权限 0600） | | Windows | %USERPROFILE%\.claude360\config.json |

示例：

{
  "baseUrl": "https://claude360.xyz",
  "cliToken": "cli_xxx",
  "apiKey": "sk-xxx",
  "selectedTokenId": 456,
  "tokenName": "daily-key",
  "group": "default"
}

注意事项：

• 当前版本接受本地明文保存 cliToken 与 apiKey，CLI 仅收紧文件权限，不接入系统密钥链。
• CLI 日志与诊断输出会脱敏 API Key。
• 若需要重置，删除 ~/.claude360/config.json 即可触发完整重新授权。

后端接口契约

CLI 仅依赖一组隔离的 /api/cli 接口（由 Claude360 服务端提供，后端代码不在本仓库）：

| 方法 | 路径 | 说明 | | --- | --- | --- | | POST | /api/cli/auth/start | 创建设备码授权会话 | | POST | /api/cli/auth/confirm | 浏览器端登录用户确认授权（站点 Web Session） | | POST | /api/cli/auth/poll | CLI 轮询授权结果：pending / approved / denied / expired / consumed | | GET | /api/cli/me | 返回当前用户、分组、余额、已用额度、展示单位 | | GET | /api/cli/tokens | 当前用户 Key 列表（脱敏） | | POST | /api/cli/tokens/:id/reveal | 校验归属并返回明文 Key，被限频且禁用缓存 | | POST | /api/cli/tokens | 按分组创建新 Key | | GET | /api/cli/groups | 用户可用分组（含 display_name、ratio、description） | | GET | /api/cli/models | 当前用户可用模型列表（含 display_name、tags、description、recommended） | | GET | /api/cli/topup/options | 后端配置的充值金额选项与最低额，包含 WeChat 启用状态 | | POST | /api/cli/topup/wechat | 创建微信 Native 订单，返回 code_url、order_id、pay_money | | GET | /api/cli/topup/order?order_id= | 查询订单状态（仅订单所属用户） |

契约要点：

• 设备码、user_code、CLI 凭证均有过期机制；CLI 凭证可后台吊销。
• 已批准会话被消费后保持 consumed，CLI 凭证有独立有效期，设备码窗口过期不影响已发出的凭证。
• Key reveal 强制鉴权 + 限频；后端日志不记录明文 Key。
• 充值订单仅订单所属用户可查询。

Claude Code 与 Codex 集成

Claude Code

启动时注入：

ANTHROPIC_BASE_URL=https://claude360.xyz
ANTHROPIC_AUTH_TOKEN=<selected_api_key>

依据 Claude Code LLM gateway 官方文档，ANTHROPIC_BASE_URL 指向网关时，ANTHROPIC_AUTH_TOKEN 会作为 bearer token 发送到 /v1/messages 与 /v1/messages/count_tokens。

Codex

写入 ~/.codex/config.toml（仅修改 model_providers.claude360，不动其他 provider），模型等覆盖项写入隔离的 profile 覆盖层 ~/.codex/claude360.config.toml：

# ~/.codex/config.toml
[model_providers.claude360]
name = "Claude360"
base_url = "https://claude360.xyz/v1"
env_key = "CLAUDE360_API_KEY"
wire_api = "responses"

启动命令：

codex --profile claude360

并通过子进程环境变量 CLAUDE360_API_KEY=<selected_api_key> 注入凭证。

风险说明：Codex 自定义 provider 使用 Responses 协议（wire_api = "responses"）。后端网关必须支持 /v1/responses 或在网关层将 Responses 请求适配到现有模型能力，否则 Codex 调用会失败。

诊断与故障排查

主菜单“诊断与修复”会汇报：操作系统与架构、终端二维码渲染能力、Node.js / npm 版本、全局 npm 安装权限、Claude Code / Codex 安装与版本、API 连通性、CLI 授权状态、账户余额、Key 列表拉取状态、微信支付端点可用性。报告以分组着色表格展示，状态用绿 ✓ / 黄 ! / 红 × 区分，失败项附修复建议。

| 现象 | 处理 | | --- | --- | | 浏览器未自动打开 | 复制终端打印的 verification_url 与 user_code 到任意浏览器 | | 授权超时 / 拒绝 / 过期 | 重新执行 claude360，会自动发起新的授权会话 | | 无可用 Key | 进入创建 Key 流程，按分组倍率提示完成 | | 二维码无法渲染 | CLI 自动降级为打印 code_url 文本 | | 启动 Claude Code 失败 | 检查 claude 是否在 PATH 中（npm install -g @anthropic-ai/claude-code） | | 启动 Codex 失败 | 检查 codex 是否在 PATH 中（npm i -g @openai/codex），并复核 ~/.codex/config.toml | | Node 版本过低 | 升级到 Node.js 18 LTS 后重新运行 bootstrap | | 全局 npm 权限不足 | 修复 npm 全局目录权限，或使用 nvm 等用户级 Node 管理器 |

开发与测试

项目使用 Node 内置 test runner，不引入额外测试框架。

npm install        # 安装依赖（@inquirer/core、qrcode-terminal、smol-toml）
npm test           # 跑全部测试（26 个测试文件 / 232 个用例）
npm test messages  # 只跑某个测试文件（test/messages.test.js）

调试入口：

node ./bin/claude360.js     # 源码模式运行
npm link && claude360       # 链接到全局命令

src/index.js 的 runCli({...}) 全部依赖（提示器、API client、浏览器打开函数、writeLine、execCommand 等）均可注入，便于自动化测试与插桩。

项目结构

claude360cli/
├── bin/
│   └── claude360.js          # CLI 入口
├── install/
│   ├── install.sh            # macOS / Linux bootstrap
│   ├── install.ps1           # Windows PowerShell bootstrap
│   └── verification-matrix.md
├── scripts/
│   └── test.js               # 测试运行器（node --test 包装）
├── src/
│   ├── index.js              # 顶层编排：环境检查 → 工具引导 → 授权 → Key → 主菜单
│   ├── colors.js             # 色彩能力探测 + 单一语义主题（PALETTE / theme）
│   ├── messages.js           # 语义消息层（formatMessage / createMessenger）
│   ├── banner.js             # 品牌横幅与流光动效、环境检查行
│   ├── menu.js               # 首次 / 日常菜单渲染与选择
│   ├── prompts.js            # 方向键单选 / 多选 / 确认（@inquirer/core）+ 降级输入
│   ├── ui.js                 # 表格 / 标题 / 信息盒子等结构化渲染
│   ├── api-client.js         # HTTP + 后端信封解析
│   ├── auth.js               # 设备码授权流程
│   ├── token-manager.js      # Key 选择 / 创建 / reveal
│   ├── account-status.js     # 主菜单账户状态面板
│   ├── topup.js              # 微信 Native 充值流程
│   ├── diagnostics.js        # 诊断报告
│   ├── init-config.js        # 输出语言 / 提示词风格 / 默认模型 / 权限写入
│   ├── init-flow.js          # 一键完整初始化编排
│   ├── mcp-skill.js          # 推荐 MCP / Skill / AGENTS 安装
│   ├── workflows.js          # 推荐工作流安装
│   ├── tool-installer.js     # 全局 npm 安装 / 更新（需确认）
│   ├── tool-launcher.js      # Claude Code / Codex 子进程启动与配置写入
│   ├── cc-switch.js          # cc-switch 供应商配置生成
│   ├── config-store.js       # 本地配置读写（0600）
│   ├── group-manager.js      # 分组与倍率展示（无本地映射）
│   ├── backup.js             # 写入前时间戳备份
│   ├── sanitize.js           # 输出脱敏（Key / 错误信息）
│   ├── onboarding.js         # 环境检查与工具安装引导
│   ├── platform.js           # 平台路径与能力探测
│   └── zcf-notice.js         # 开源参考声明
├── test/                     # 26 个测试文件（与 src 一一对应）
├── package.json
└── README.md

安全模型

• CLI 不接收、不保存站点账号密码。
• 设备码、user_code、CLI 凭证均短期有效；CLI 凭证可后台吊销。
• 授权轮询限频；POST /api/cli/tokens/:id/reveal 强制鉴权 + 限频 + 禁用缓存。
• 后端日志不记录明文 Key；CLI 日志不打印完整 Key（统一经 sanitize.js 脱敏）。
• 充值订单只能被订单所属用户查询。
• 本地配置文件 macOS/Linux 写入 mode 0600；Windows 写入当前用户目录。
• 任何全局 npm、系统运行时安装都需用户在终端显式确认。
• CLI 不修改 shell profile / PowerShell profile / 全局环境变量。

致谢

本 CLI 的交互式初始化流程、工作流导入、MCP 推荐配置等设计，借鉴并参考了开源项目 NPX ZCF 的部分功能体验，感谢作者 UfoMiao 的开源贡献。

• 相关功能入口（完整初始化、推荐工作流 / MCP / Skill / AGENTS）会在终端展示开源参考声明。
• 随 CLI 安装的推荐工作流文件均为 Claude360 自研改编内容，文件头保留对 NPX ZCF 的 attribution 注释。

许可证

本仓库尚未声明开源许可证。在对外公开分发前，建议补充一个 LICENSE 文件（如 MIT）。在添加许可证之前，默认保留所有权利（All Rights Reserved）。