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。
安裝與驗證 - Alibaba Cloud Model Studio