安装配置

本文档介绍 360disk CLI 工具的安装方式和鉴权配置。

更新时间：2026-05-09

安装方式

npm 全局安装（推荐）

npm install -g @aicloud360/360-ai-cloud-disk-cli

安装后即可直接使用：

360disk --version
360disk --help

npx 免安装使用

无需安装，直接通过 npx 运行：

npx -y -p @aicloud360/360-ai-cloud-disk-cli@latest 360disk dir ls /

提示

npx 方式每次运行会检查包版本，首次使用会下载依赖。适合临时使用或 CI/CD 环境。

系统要求

要求	说明
Node.js	>= 18.0.0
npm	>= 8.0.0
操作系统	macOS / Linux / Windows

验证安装

# 查看版本号
360disk --version

# 查看帮助
360disk --help

# 查看子命令帮助
360disk file --help
360disk file search --help

鉴权配置

使用 360disk 前需完成身份认证。可选方式包括：在开放平台获取 API Key 后配置，或使用 auth login-wechat 微信扫码登录（成功后同样将 api_key 写入本地配置，后续命令与 API Key 登录等价）。

获取 API Key

访问 360 AI 云盘开放平台 按指引获取 API Key。

API Key 格式为 yunpan_ 开头的字符串。

配置方式

360disk 支持三种鉴权方式，按优先级从高到低：

方式一：命令行参数（最高优先级）

360disk --api-key yunpan_xxx dir ls /

适用于临时使用或需要切换不同账号的场景。

方式二：环境变量

# 单次使用
API_KEY=yunpan_xxx 360disk dir ls /

# 或导出为环境变量（当前终端会话有效）
export API_KEY=yunpan_xxx
360disk dir ls /

适用于 CI/CD 环境或脚本中使用。

方式三：本地配置文件（持久化）

# 登录并保存到 ~/.360disk/config.json
360disk auth login --api-key yunpan_xxx

登录后，后续所有命令自动使用已保存的 API Key，无需重复配置。

# 查看当前鉴权状态
360disk auth whoami

# 退出登录（清除本地配置）
360disk auth logout

微信扫码登录（可选）

适用于已开通小程序扫码能力的账号。CLI 默认在终端展示 字符二维码；也可 --qr-mode file 将 PNG 写入本地再扫码。若使用 auth login-wechat --format json（或与 --quiet 组合后的两行 stdout 模式），第一行会为二维码元数据（内联 qr + Data URL/Base64，或 qr_file + 本地路径，见下），第二行为登录结束后的完整结果 JSON——适合 Agent、IDE 或非 TTY 环境。使用 微信扫描并在手机上确认 后，经 360 登录域完成轮询与票据同步，并调用云盘 OpenAPI Oauth.getApiKeyByQT（client_src=pcw_aidrive）换取 api_key，写入 ~/.360disk/config.json（与 auth login --api-key 共用同一配置结构）。

# 默认：终端字符二维码；结束时输出与普通命令一致的 JSON
360disk auth login-wechat

# 终端流程：PNG 写入文件（路径可省略，则写入系统临时目录）
360disk auth login-wechat --qr-mode file --qr-file /tmp/360disk-wechat-qr.png

# 测试环境（与 openapi 测试域名一致，见 ECS_ENV）
360disk auth login-wechat --env test --sub-channel open

# 调整等待与轮询间隔
360disk auth login-wechat --timeout 180 --interval 1000

# 人类可读成功摘要
360disk auth login-wechat --format text

# 流式 JSON：第一行为二维码负载（默认含 qr_image_data_url + qr_image_base64 + qr_image_mime），成功后再输出一行完整结果 JSON（适合 Agent / 脚本解析）
360disk auth login-wechat --format json

# 流式 JSON + 文件模式：首行 type=qr_file，仅含 png 绝对路径，避免单行过大或宿主禁用 data: URL
360disk auth login-wechat --format json --qr-mode file --qr-file /tmp/360disk-wechat-qr.png

常用子选项：--timeout（秒，默认 120）、--interval（毫秒，默认 1500）、--qr-mode（terminal / file）、--qr-file（与 file 联用）、--env、--sub-channel；与 auth 下其他子命令一样支持全局 --format / --quiet（需写在 auth login-wechat 上，见命令参考 · auth login-wechat）。

注意

• 本地配置文件存储路径：~/.360disk/config.json
• 该文件在 auth login 或 auth login-wechat 成功后写入/更新，安装时不会自动生成
• 请勿将配置文件提交到版本控制系统

鉴权优先级

当多种方式同时存在时，按以下优先级使用：

1. --api-key 命令行参数    （最高优先级）
2. API_KEY 环境变量
3. ~/.360disk/config.json   （最低优先级）

环境配置

除 API Key 外，还支持以下环境配置：

# 登录到测试环境
360disk auth login --api-key yunpan_xxx --env test

# 指定子渠道
360disk auth login --api-key yunpan_xxx --sub-channel custom

# 微信扫码登录到测试环境（效果与 API Key 登录一致，仅获取密钥方式不同）
360disk auth login-wechat --env test --sub-channel open

或通过环境变量：

export API_KEY=yunpan_xxx
export ECS_ENV=test       # 环境：prod（默认）/ test
export SUB_CHANNEL=open   # 子渠道（默认 open）

全局选项

所有命令均支持以下全局选项：

选项	说明	默认值
--api-key <key>	API 密钥（覆盖本地配置和环境变量）	—
--env <env>	环境：prod / test	prod
--sub-channel <channel>	子渠道标识	open
--format <type>	输出格式：json / text	json
--quiet	静默模式，仅输出 result 数据	false
--timeout <ms>	请求超时时间（毫秒）	30000
--retries <n>	失败重试次数（指数退避）	0
--help	显示帮助信息	—
--version	显示版本号	—

全局选项位置

全局选项需放在子命令之前：

# ✅ 正确
360disk --format text dir ls /
360disk --quiet --timeout 60000 file search "报告"

# ❌ 错误（全局选项不能放在子命令之后）
360disk dir ls / --format text

下一步

• 命令参考 - 全部 31 个子命令的详细说明（含 auth login-wechat、claw-backup / claw-restore / claw-auto-backup）
• 进阶用法 - 管道集成、错误码、CI/CD 场景