Skip to main content
开始使用

安装与鉴权

安装阿里云百炼 CLI 与 Skills，完成鉴权配置并校验。

本页介绍如何安装阿里云百炼 CLI、安装配套 Skills，以及完成鉴权配置。

前置条件

  • 能访问网络（npm registry 或 bailian.aliyun.com，取决于下方选择的安装方式）。
  • 若选择 npm 安装：Node.js ≥ 18.17.0（执行 node -v 确认）与 npm（执行 npm -v 确认）。若本机没有 Node.js 或版本过低，可直接用下方的二进制安装脚本，无需装 Node。

安装 CLI

  • npm（已有 Node.js 环境）
  • 二进制脚本（无需 Node.js）
npm install -g bailian-cli
即使本机已安装 pnpm / yarn，安装 bailian-cli 时仍需使用 npm；不要改用 pnpm / yarn 安装 CLI。
安装成功后，PATH 中会新增两个命令：bl（短别名）与 bailian（全名）。校验： 
bl --version
which bl   # Windows 可用 where bl
后续可随时执行 bl update 检查并更新 CLI 到最新版本。
若提示 command not found，检查全局 bin 目录是否在 PATH 中：npm 安装执行 npm config get prefix，其下的 bin 目录需加入 PATH；二进制安装按脚本输出提示的路径加入 PATH。

安装 Skills

CLI 校验通过后，安装配套 Skills，让 Agent 具备完整的阿里云百炼能力调度。首选内置的一键安装命令： 
bl skill init
该命令一次装齐 registry 中全部 bailian-* Skills（含共享协议 bailian-protocol），是官方推荐的安装方式。若 bl skill init 不可用，可改用 skills 工具（需要本机有 Git；最新 skills 要求 Node.js ≥ 22.20，Node.js 18 环境请固定 skills@1.5.18）： 
npx skills@1.5.18 add modelstudioai/cli --skill '*' -g
只安装某个 Skill 时，把 --skill '*' 换成具体名称；--list 可查看仓库内的全部 Skill。

鉴权配置

安装后必须完成鉴权才能调用 API。根据环境选择下列任一方式。
  • 控制台登录（推荐）
  • 普通 API Key
  • Token Plan
  • AK/SK 临时令牌
  • 环境变量
适用于本机交互式安装，无需手动复制 API Key。命令会拉起浏览器完成阿里云控制台登录授权：
bl auth login --console
此方式同时打通 app list、usage free 等控制台能力，并自动配置 API Key 调用所需的鉴权信息。
普通 API Key 与 Token Plan 订阅的 API Key 差异如下：
对比项普通 API KeyToken Plan API Key
计费归属按量计费（含新用户免费额度）扣减 Token Plan 订阅额度
权限范围调用模型服务调用 Token Plan 支持的模型
典型场景未订阅套餐或按量调用已订阅 Token Plan，优先消耗套餐额度
配置方式bl auth login --api-key <Key>bl auth login --config token-plan --api-key <sk-sp-Key>

校验配置

登录命令本身已完成可用性测试，通过后只需确认配置状态： 
bl auth status --output json
无需再执行重复的模型调用测试。若登录失败，可根据输出中的 hint 或 message 排查（网络、Key 无效、base_url 等）。
汇报鉴权状态时只使用 masked 字段，切勿回显完整 API Key，也不要把真实 Key 写入仓库、日志或聊天记录的可公开部分。

退出登录

需要清除本地凭证、退出登录状态时，执行： 
bl auth logout

常见问题

全局 bin 目录不在 PATH 中。执行 npm config get prefix，将其下的 bin 目录加入 PATH 后重试。
Node.js 版本过低。升级到 ≥ 18.17.0 后重新安装。
未登录或 API Key 无效。按 Key 类型重新执行对应的登录命令（普通 API Key 或 Token Plan）。
当前生效的凭据是普通 API Key（default Profile）。Token Plan 需使用订阅的 API Key 并登录到 token-plan Profile；可用 bl auth status --output json 查看当前生效的凭据来源。
使用订阅 API Key 登录 Token Plan Profile：bl auth login --config token-plan --api-key <sk-sp-Key>。已有该 Profile 时，用 bl config use --name token-plan 将其切换为当前生效配置。
不能。模型调用类命令可用；控制台类命令（如 app list、usage free、workspace）需要先完成控制台登录（bl auth login --console），Token Plan 席位管理等命令还需要阿里云 OpenAPI AK/SK 凭据。对比见鉴权配置。
执行 bl auth status --output json 查看当前凭据（脱敏输出）；执行 bl config list 查看全部 Profile，bl config use --name <profile> 切换当前 Profile。
需配置镜像或代理。配置 registry 或代理后再安装。
改用二进制安装脚本（无需 Node.js/npm）：curl -fsSL https://bailian.aliyun.com/cli/install.sh | bash；也可以先安装或修复 npm 再用 npm install -g bailian-cli，但不要改用 pnpm / yarn 安装 CLI。
开始使用
能力参考
更新日志