QwenCloud 使用方法

查询 QwenCloud 使用量、免费额度、编码计划状态以及按量付费账单。

前提条件

• QwenCloud CLI 必须已安装。可通过以下命令验证：

qwencloud version

如未安装，请运行：

npm install -g @qwencloud/qwencloud-cli

需 Node.js >= 18。

• 认证：首次使用无需手动配置。CLI 会自动检测非 TTY 环境并安全完成登录（详见下方“认证流程”）。

环境变量

认证流程（面向 Agent）

CLI 可自动检测非 TTY 环境，并安全降级处理——无需额外包装脚本。

简明版 —— 三步认证路径

1. qwencloud auth status --format json → 若返回 authenticated: true，则跳过登录，直接执行命令
2. qwencloud auth login --init-only --format json → 提取 verification_url → 在浏览器中打开该地址
3. qwencloud auth login --complete --format json → 持续轮询，直至收到 success 事件

快速检查：是否已登录？

qwencloud auth status --format json

若返回 authenticated: true 且 token 未过期，则完全跳过登录步骤。

推荐方式：两阶段登录

适用于所有环境（桌面端、无头环境、远程容器）。

第 1 步 — 初始化登录（非阻塞）：

qwencloud auth login --init-only --format json

立即退出。解析 stdout 返回的 JSON 中的 events 数组：

• already_authenticated → 用户已登录，可直接执行后续命令
• device_code → 提取 verification_url 并展示给用户

在具备浏览器的桌面环境中，可为用户自动打开该 URL：

open "$VERIFICATION_URL"          # macOS
xdg-open "$VERIFICATION_URL"      # Linux
start "" "$VERIFICATION_URL"      # Windows

第 2 步 — 立即启动轮询（切勿等待用户确认）：

qwencloud auth login --complete --format json

解析 stdout 返回的 JSON 中的 events 数组：

• success → 登录完成，继续执行后续命令
• expired → 设备码已过期，返回第 1 步重试
• error → 报告失败

TTY 环境（交互式终端）

若 Agent 运行于 TTY 环境（例如用户终端），只需直接运行：

qwencloud auth login

CLI 将自动打开浏览器并持续轮询，直至授权完成。

JSON 事件结构

--init-only 和 --complete 均输出单一 JSON 文档：

{
  "events": [
    {"event": "device_code", "verification_url": "...", "expires_in": 300},
    {"event": "success", "authenticated": true, "user": {"aliyunId": "..."}}
  ]
}

支持的事件类型包括：already_authenticated、device_code、success、expired、error、pending。

绝对禁止的操作：

• ❌ 在运行 --complete 前，向用户提问“您是否已完成授权？”
• ❌ 在轮询前等待用户确认——应在展示 URL 后立即运行 --complete
• ❌ 在未完成上一次登录流程的情况下重复运行 --init-only（这将生成新设备码并使旧设备码失效）

使用方法

所有命令均支持 --format json（输出结构化、机器可解析的 JSON，推荐作为默认格式），以及 --format text（输出简洁明了的纯文本）。

对于 Agent 场景，务必优先使用 --format json 并解析其 JSON 响应；仅当用户明确要求人类可读的纯文本时，才回退至 --format text。

请勿以编程方式解析 table 格式输出——其中包含 ANSI 控制码与 Unicode 边框字符。

认证相关命令

qwencloud auth status — 检查当前认证状态

qwencloud auth status --format json

qwencloud auth logout — 在服务端撤销会话并清除本地凭证

qwencloud auth logout

用量查询命令

qwencloud usage summary — 查看用量汇总（含免费额度、编码计划、按量付费）

qwencloud usage summary                      # 当前月份
qwencloud usage summary --period last-month  # 上个月
qwencloud usage summary --from 2026-03-01 --to 2026-03-31
qwencloud usage summary --format json        # JSON 输出

周期预设值：today、yesterday、week、month（默认）、last-month、quarter、year、YYYY-MM

qwencloud usage breakdown — 查看各模型用量明细

qwencloud usage breakdown --model qwen3.6-plus --days 7
qwencloud usage breakdown --model qwen3.5-plus --period 2026-03
qwencloud usage breakdown --model qwen-plus --period 2026-03 --granularity month
qwencloud usage breakdown --model qwen3.6-plus --format json

qwencloud usage free-tier — 查看免费额度详情

qwencloud usage free-tier
qwencloud usage free-tier --format json

qwencloud usage payg — 查看按量付费账单详情

qwencloud usage payg
qwencloud usage payg --format json

明细查询参数：理解其设计逻辑

三个正交维度，可自由组合：

--model（必需）+ 日期范围 + 粒度（granularity）

模型范围：

• --model — 指定单一模型（例如 qwen3.5-plus）；明细查询必需指定

日期范围 — 共四种模式，请根据用户描述选择最匹配的一种：

粒度（granularity） — 决定结果分组方式，不影响时间范围：

• day（默认）— 每日一行；适合识别用量突增点
• month — 每自然月一行；适合分析跨月趋势
• quarter — 每季度一行；适合同比/环比分析

典型示例：

# 单一模型、单月、按日明细
qwencloud usage breakdown --model qwen3.5-plus --period 2026-03

# 单一模型、最近三个月、按月汇总
qwencloud usage breakdown --model qwen3.5-plus --days 90 --granularity month

# 单一模型、特定季度、按季度汇总
qwencloud usage breakdown --model qwen3.5-plus --from 2026-01-01 --to 2026-03-31 --granularity quarter

# 单一模型、本月、按日明细
qwencloud usage breakdown --model qwen3.6-plus --period month

输出与 Agent 展示规范

CLI 命令在 Agent/管道环境中的默认输出格式为 JSON（auto 模式：TTY → table，管道 → json）。JSON 是 Agent 的主要输出格式——请始终显式传入 --format json，解析结构化响应后，再向用户呈现人类可读的摘要。

JSON 输出示例（--format json）

qwencloud usage summary --period month --format json

返回结构化 JSON，含以下三个部分：

{
  "period": { "from": "2026-04-01", "to": "2026-04-24" },
  "free_tier": [
    { "model_id": "qwen3.6-plus", "quota": { "remaining": 850000, "total": 1000000, "unit": "tokens", "used_pct": 15 } }
  ],
  "coding_plan": {
    "subscribed": true,
    "plan": "PRO",
    "windows": {
      "per_5h": { "remaining": 4800, "total": 6000, "used_pct": 20 },
      "weekly": { "remaining": 38200, "total": 45000, "used_pct": 15 },
      "monthly": { "remaining": 82500, "total": 90000, "used_pct": 8 }
    }
  },
  "pay_as_you_go": {
    "models": [
      { "model_id": "qwen3.6-plus", "usage": { "tokens_total": 480000 }, "cost": 0.38, "currency": "USD" },
      { "model_id": "qwen-plus", "usage": { "tokens_total": 460000 }, "cost": 0.13, "currency": "USD" }
    ],
    "total": { "cost": 0.51, "currency": "USD" }
  }
}

文本输出示例（--format text）

qwencloud usage summary --period month --format text

Usage Summary  ·  2026-04-10

-- Free Tier Quota -------------------------------------------------------
Model                Remaining      Total          Progress
qwen3.6-plus         850K tokens    1M tokens      85% left
wan2.6-t2i           38 images      50 images      76% left
--------------------------------------------------------------------------

-- Coding Plan · PRO Plan ------------------------------------------------
Window           Remaining      Total          Progress
Per 5 hours      4.8K req       6K req         20% used
This week        38.2K req      45K req        15% used
This month       82.5K req      90K req         8% used
--------------------------------------------------------------------------

-- Pay-as-you-go · 2026-04-01 → 2026-04-10 -------------------------------
Model                Usage              Cost
qwen3.6-plus         480K tok           $0.38
qwen-plus            460K tok           $0.13
--------------------------------------------------------------------------
Total                —                  $0.51

⚠️ 关键规范：如何向用户呈现输出

当使用 --format json（Agent 推荐）时：

1. 解析 JSON，提取与用户问题相关的数据
2. 呈现人类可读的摘要 — 切勿将原始 JSON 直接输出给用户
3. 分析内容置于摘要之后 — 用 --- 明确分隔

当使用 --format text 时：

1. 原样展示 CLI 输出 — 不做任何修改或重新排版
2. 保留全部格式 — 对齐、空格、进度条、分隔线等均需保持原貌
3. 分析内容仅置于输出之后 — 用 --- 明确分隔

绝对禁止的操作：

• ❌ 将原始 JSON 未经解释直接输出给用户
• ❌ 对 text/table 输出进行重新格式化或总结
• ❌ 添加类似 “这是您的用量信息：” 的前缀
• ❌ 将 text/table 输出转换为项目符号列表

✅ 正确示例（JSON 模式）：

您在四月的 QwenCloud 使用情况如下：

**免费额度**：qwen3.6-plus 剩余 85%（850K / 1M tokens），wan2.6-t2i 剩余 76%（38 / 50 images）。
**编码计划（PRO）**：本月已使用 8%（82.5K / 90K 请求）。
**按量付费**：总计 $0.51 — 其中 qwen3.6-plus $0.38，qwen-plus $0.13。

---

**💡 分析**：您的 qwen3.6-plus 免费额度尚有 85% 剩余...

✅ 正确示例（Text 模式）：

[CLI text 输出 - 完全原样]

---

**💡 分析**：您的 qwen3.6-plus 免费额度尚有 85% 剩余...

❌ 错误示例：

这是您的用量信息：
- qwen3.6-plus：剩余 850K tokens（剩余 85%）

退出码

CLI 版本更新检查

当用户明确要求检查 CLI 更新（例如：“检查 CLI 更新”、“检查 CLI 版本”、“是否有新版本 CLI”）时：

1. 执行：qwencloud version --check
2. 如实报告结果。

QwenCloud CLI 原生支持更新通知机制；本能力无需额外处理 stderr 信号。

实现说明

• 按量付费：API 仅返回总用量（不区分输入/输出）
• 编码计划：请求计数在计划层级聚合（不提供每模型明细）
• logout：在服务端撤销会话并清除本地凭证（密钥链 + 文件）。服务端调用为尽力而为；本地登出始终成功。
• 认证：采用 OAuth 2.0 Device Authorization Grant（带 PKCE）。凭证优先存于操作系统密钥链，若不可用则回退至加密文件存储。
• breakdown 的 --model 参数为必需项：与旧版 Python 实现不同，CLI 要求 breakdown 必须指定 --model。如需查询所有模型用量，请改用 qwencloud usage summary。