阿里云百炼CLI安装与配置全攻略：三步接入，赋能AI Agent高效调用10+模型能力

2026年9月2日15:27

针对当前开发者在AI Agent落地过程中普遍面临的多模态能力集成门槛高、跨工具适配成本高、复杂场景产出链路割裂的核心痛点，阿里云百炼CLI打造了专为AI Agent生态优化的命令行能力接入体系，只需一行安装指令完成认证，即可将百炼平台全栈多模态AI能力快速接入各类主流AI开发工具。通过极简的三步接入流程，开发者可将其无缝集成至Claude Code、Cursor等主流开发环境，工具覆盖10余项核心AI能力，配套全场景实战命令示例与参数解析，提供覆盖模型调用、应用管理、记忆存储的全链路命令集，帮助AI Agent自动调度能力完成电商图、视频、播客等专业级产出，大幅降低复杂多模态AI应用的前期开发与集成成本，显著提升AI Agent的落地效率与业务交付能力。更多阿里云百炼平台知识可参考：https://www.aliyun.com/product/bailian

一、3 步完成接入 CLI

第一步：安装 CLI
复制下面的内容，告诉您的 AI Agent 阅读安装文档后，能够自动装好阿里云百炼 CLI。

请阅读：https://bailian.aliyun.com/cli/install.md 并按照说明为我安装阿里云百炼 CLI

第二步：鉴权配置
方式一：快捷登录
复制命令给 Agent 后自动完成鉴权信息配置。

帮我执行 bl auth login --console 控制台登录

方式二：API Key 配置
获取 API Key ，然后把 Key 告诉 Agent 完成配置。

API Key 是：sk-xxxxxxxxxxxx

第三步：开始使用
完成 1、2 步骤后，给您的 Agent 下发需求即可调度 CLI 能力进行产出，尝试给 Agent 发送第一个示例：

帮我生成一套电商主图，6 张图，产品是纯黑色夏日男装 T 恤

二、安装与配置

2.1 安装

说明前置要求：Node.js ≥ 22.12.0。百炼 CLI 仅支持通过 npm 安装。

方式一：在 AI Agent 中安装（推荐）

在 AI Agent 中告诉 Agent：

请阅读 https://bailian.aliyun.com/cli/install.md 并按照说明为我安装阿里云百炼 CLI

方式二：手动安装

# 第 1 步：安装 CLI
npm install -g bailian-cli

# 第 2 步：安装 Skills（将百炼能力描述文件注册到各 Agent 的 Skills 目录）
npx skills add modelstudioai/cli --all -g

# 第 3 步：验证安装
bl --version

2.2 认证与配置

使用百炼 CLI 前，您需要完成身份认证。支持以下认证方式：

认证方式命令适用场景
控制台登录（推荐）bl auth login --console模型调用 + 应用管理（拉起浏览器完成 OAuth 登录）
API Keybl auth login --api-key sk-xxx（获取 API Key）模型调用（文本、图像、视频、语音等）
Token Plan API Keybl auth login --config token-plan --api-key sk-sp-xxx（获取 Token Plan API Key）Token Plan 个人版订阅用户的模型调用。使用 bl config use --name token-plan 切换为默认配置，或在命令中加 --config token-plan 单次指定
环境变量配置 API Key 环境变量CI/CD、无界面环境
配置文件bl config set --key api_key --value sk-xxx持久化（不校验 Key 有效性）
临时传入bl text chat --api-key sk-xxx --message "你好"单次调用，不落盘

控制台登录和 API Key 可同时配置，互不覆盖。

说明如果您通过控制台登录后，执行 bl text chat 等模型调用命令时仍提示"缺少 API Key"，请先运行 bl update 升级到最新版本。若升级后问题仍然存在，请单独配置 API Key：bl auth login --api-key <your-key>。

认证完成后，您可以通过 bl config 设置模型、输出目录等参数：

# 查看当前配置
bl config show

# 设置默认文本模型
bl config set --key default-text-model --value qwen3.7-max

# 设置输出目录
bl config set --key output_dir --value ~/bailian-output

常用全局参数

参数说明
--api-key <key>指定 API Key（仅本次生效）
--region <cn\|us\|intl>切换地域（默认 cn）
--base-url <url>自定义 API 端点
--output <text\|json>输出格式
--timeout <seconds>请求超时时间
--quiet静默模式，减少输出
--verbose打印 HTTP 请求/响应详情
--no-color禁用 ANSI 颜色
--dry-run预览请求，不实际执行
--non-interactive非交互模式，适用于 Agent 和 CI/CD
--concurrent <n>并发请求数（默认 1）

百炼 CLI 兼容 Claude Code、Cursor、Codex、Qwen Code 等主流 AI 工具和框架。完整兼容列表和集成方式，请参见百炼 CLI GitHub 仓库。

三、场景实战

3.1 电商套图生成

告诉 Agent：

帮我生成一套亚马逊电商主图，6 张图，产品是纯黑色夏日男装 T 恤

Agent 会组合多个命令完成任务：

  1. 生成 6 张产品主图：
 bl image generate --prompt "纯黑色夏日男装T恤，白色背景，亚马逊电商主图风格" --n 6 --out-dir ./ecommerce/
  1. 如需调整某张图：
 bl image edit --image ./ecommerce/image_01.png --prompt "添加模特穿着效果"
  1. 如需生成产品展示视频：
 bl video generate --image ./ecommerce/image_01.png --prompt "T恤360度旋转展示" --download tshirt-demo.mp4

3.2 新闻播客生成

告诉 Agent：

搜索今天关于 AI 的新闻，写一段相声，然后生成男女音色区分的音频播客

Agent 会依次执行：

  1. 联网搜索获取新闻素材：
 bl search web --query "今天AI新闻"
  1. 用大模型撰写相声稿本：
 bl text chat --message "根据以下新闻素材，写一段相声..."
  1. 分角色生成音频：
 bl speech synthesize --text "甲：您听说了吗..." --voice Ethan --out host_male.mp3
 bl speech synthesize --text "乙：怎么了？..." --voice Cherry --out host_female.mp3
  1. 用 ffmpeg 合并音频片段为完整播客。

3.3 故事书生成

告诉 Agent：

帮我生成一部小红帽的故事书，真人写实版本，保持人物连续一致性，需要有 20 页，尺寸是 16:9 的，变成 PDF 给我

Agent 会自动完成：为每页生成故事文字 → 根据文字生成风格一致的配图 → 排版并输出 PDF。

四、命令参考

4.1 文本对话

bl text chat

发送文本对话请求，兼容 OpenAI 接口格式。

bl text chat --message <text> [flags]
参数说明默认值
--model <model>模型 IDqwen3.7-max
--message <text>消息内容（可重复，前缀 role: 设置角色）—
--messages-file <path>从 JSON 文件读取消息（- 表示标准输入）—
--system <text>系统提示词—
--max-tokens <n>最大生成 token 数4096
--temperature <n>采样温度 (0.0, 2.0\]—
--top-p <n>核采样阈值—
--stream流式输出（TTY 下默认开启）—
--tool <json-or-path>工具定义，JSON 或文件路径（可重复）—
--enable-thinking开启思考模式（适用于 qwen3/qwq 模型）—
--thinking-budget <n>思考模式最大 token 数4096

4.2 全模态理解

bl omni

全模态对话，支持图片、音频、视频输入，文本和语音输出。

bl omni --message <text> [flags]
参数说明默认值
--message <text>消息内容（可重复）—
--model <model>模型 IDqwen3.5-omni-plus
--system <text>系统提示词—
--image <url>图片 URL 或本地文件（可重复）—
--audio <url>音频 URL 或本地文件（可重复）—
--video <url>视频 URL 或本地文件—
--voice <voice>输出音色（可选：Chelsie、Cherry、Ethan、Serena、Tina）Cherry
--audio-format <fmt>音频输出格式wav
--audio-out <path>保存音频到文件自动生成
--text-only仅输出文本，不生成音频—
--max-tokens <n>最大生成 token 数—
--temperature <n>采样温度 (0.0, 2.0\]—

4.3 图像生成与编辑

bl image generate

文字生成图像。

bl image generate --prompt <text> [flags]
参数说明默认值
--prompt <text>图像描述—
--model <model>模型 IDqwen-image-2.0
--size <W*H>图像尺寸，支持比例（3:4, 16:9）或像素（2048\*2048）—
--n <count>每次生成图片数量（最多 6）1
--seed <n>随机种子，用于复现结果—
--negative-prompt <text>反向提示词，排除不需要的内容—
--prompt-extend <bool>是否启用提示词扩展true（同步模式）
--watermark <bool>是否添加水印true
--no-wait异步模式，立即返回任务 ID—
--out-dir <dir>图片保存目录—
--out-prefix <prefix>文件名前缀image
--poll-interval <seconds>轮询间隔3

bl image edit

编辑已有图像，支持多图合成。

bl image edit --image <url> --prompt <text> [flags]
参数说明默认值
--image <url>源图片 URL 或本地文件（可重复，用于多图合成）—
--prompt <text>编辑指令—
--model <model>模型 IDqwen-image-2.0
--size <W*H>输出尺寸—
--n <count>生成数量（最多 6）1
--seed <n>随机种子—
--negative-prompt <text>反向提示词—
--prompt-extend <bool>是否启用提示词扩展true
--watermark <bool>是否添加水印true
--out-dir <dir>保存目录—
--out-prefix <prefix>文件名前缀edited

4.4 视频生成与编辑

bl video generate

文字或图片生成视频。

bl video generate --prompt <text> [--image <url>] [flags]
参数说明默认值
--prompt <text>视频描述—
--model <model>模型 IDhappyhorse-1.1-t2v（有 --image 时为 i2v）
--image <url>输入图片，启用图生视频模式—
--negative-prompt <text>反向提示词—
--resolution <res>分辨率（如 1280\*720）—
--ratio <ratio>宽高比（如 16:9, 1:1）—
--duration <seconds>视频时长（秒）5
--prompt-extend <bool>是否启用提示词扩展—
--watermark <bool>是否添加水印true
--seed <n>随机种子—
--download <path>完成后保存到文件—
--async立即返回任务 ID（异步模式，适用于 Agent/CI）—
--poll-interval <seconds>轮询间隔5

bl video edit

编辑视频，支持风格转换、对象替换等。

bl video edit --video <url> --prompt <text> [flags]
参数说明默认值
--video <url>输入视频 URL 或本地文件（2-10 秒）—
--prompt <text>编辑指令—
--model <model>模型 IDhappyhorse-1.0-video-edit
--ref-image <url>参考图片（最多 4 张，逗号分隔）—
--negative-prompt <text>反向提示词—
--resolution <res>分辨率：720P 或 1080P1080P
--ratio <ratio>宽高比（16:9, 9:16, 1:1, 4:3, 3:4）—
--duration <seconds>输出时长（2-10 秒）—
--audio-setting <mode>音频处理：auto 或 origin（保留原声）auto
--prompt-extend <bool>是否启用提示词扩展—
--watermark <bool>是否添加水印true
--seed <n>随机种子—
--download <path>保存到文件—
--no-wait立即返回任务 ID—
--poll-interval <seconds>轮询间隔15

bl video ref

多图参考生成视频，支持多主体、多镜头、配音。

bl video ref --prompt <text> --image <url>... [flags]
参数说明默认值
--prompt <text>视频描述，使用标记引用素材（图1、视频1 等）—
--model <model>模型 IDhappyhorse-1.1-r2v
--image <url>参考图片（可重复，用于多主体）—
--ref-video <url>参考视频（可重复）—
--image-voice <url>图片对应的配音（按位置配对）—
--video-voice <url>视频对应的配音（按位置配对）—
--resolution <res>分辨率：720P 或 1080P720P
--ratio <ratio>宽高比（16:9, 9:16, 1:1）—
--duration <seconds>视频时长（2-10 秒）5
--prompt-extend <bool>是否启用提示词扩展—
--watermark <bool>是否添加水印true
--seed <n>随机种子—
--download <path>保存到文件—
--no-wait立即返回任务 ID—
--poll-interval <seconds>轮询间隔15

bl video task get

查询异步视频任务的状态。

bl video task get --task-id <id>
参数说明
--task-id <id>异步任务 ID

bl video download

按任务 ID 下载已完成的视频。

bl video download --task-id <id> --out <path>
参数说明
--task-id <id>任务 ID
--out <path>输出文件路径

4.5 视觉理解

bl vision describe

使用视觉模型描述图片或视频内容。

bl vision describe --image <path-or-url> [flags]
参数说明默认值
--image <path-or-url>图片路径或 URL—
--video <url>视频文件路径或 URL—
--prompt <text>关于内容的问题自动检测
--model <model>视觉模型qwen3-vl-plus

4.6 语音合成与识别

bl speech synthesize

文字转语音（TTS）。

bl speech synthesize --text <text> [flags]
参数说明默认值
--text <text>要合成的文本—
--text-file <path>从文件读取文本—
--model <model>模型 IDcosyvoice-v3-flash
--voice <voice>音色 ID（用 --list-voices 查看）—
--list-voices列出可用音色—
--format <format>音频格式：mp3、pcm、wav、opusmp3
--sample-rate <rate>采样率（Hz）—
--volume <volume>音量（0-100）50
--rate <rate>语速（0.5-2.0）1.0
--pitch <pitch>音调（0.5-2.0）1.0
--seed <seed>随机种子（0-65535）—
--language <lang>语言提示（zh、en、ja、ko 等）—
--instruction <text>自然语言风格指令（如"请用温柔的语调"）—
--enable-ssml启用 SSML 标记解析—
--out <path>保存音频到文件自动生成
--stream流式输出原始 PCM 音频—

bl speech recognize

语音转文字（ASR）。

bl speech recognize --url <audio-url> [flags]
参数说明默认值
--url <url>音频文件 URL 或本地路径（可重复，最多 100 个）—
--model <model>模型 IDfun-asr
--language <lang>语言提示（zh、en、ja 等）—
--diarization启用说话人分离—
--speaker-count <n>预期说话人数（需配合 --diarization）—
--vocabulary-id <id>热词表 ID，提高识别准确率—
--channel-id <n>音频通道 ID0
--out <path>保存完整识别结果到 JSON 文件—
--no-wait立即返回任务 ID—
--poll-interval <seconds>轮询间隔2

4.7 联网搜索

bl search web

联网搜索。

bl search web --query <text> [flags]
参数说明默认值
--query <text>搜索关键词—
--count <n>搜索结果数量10
--list-tools列出可用的 MCP 搜索工具—

4.8 应用与数据

bl app call

调用百炼应用（智能体或工作流）。

bl app call --app-id <id> --prompt <text> [flags]
参数说明默认值
--app-id <id>应用 ID（必填）—
--prompt <text>输入提示—
--image <url>图片 URL（可重复）—
--file-id <id>预上传的文件 ID（可重复）—
--session-id <id>会话 ID，用于多轮对话—
--stream流式输出（TTY 下默认开启）—
--pipeline-ids <ids>知识库 Pipeline ID（逗号分隔）—
--memory-id <id>记忆 ID，启用长期记忆—
--biz-params <json>业务参数 JSON（工作流变量）—
--has-thoughts显示 Agent 思考过程—

bl app list

列出百炼应用。

bl app list [flags]
参数说明默认值
--name <name>按名称搜索—
--page <n>页码1
--page-size <n>每页数量30
--region <region>API 地域cn-beijing

bl memory add

添加记忆。

bl memory add --user-id <id> [flags]
参数说明
--user-id <id>用户 ID（必填）
--messages <json>消息 JSON 数组
--content <text>自定义记忆内容
--profile-schema <id>用户画像 Schema ID
--memory-library-id <id>记忆库 ID（隔离记忆空间）

bl memory search

搜索记忆。

bl memory search --user-id <id> [flags]
参数说明默认值
--user-id <id>用户 ID（必填）—
--query <text>搜索关键词—
--messages <json>消息 JSON 数组，用于上下文搜索—
--top-k <n>返回结果数量10
--memory-library-id <id>记忆库 ID—

bl memory list

列出记忆。

bl memory list --user-id <id> [flags]
参数说明默认值
--user-id <id>用户 ID（必填）—
--page-size <n>每页数量10
--page <n>页码1
--memory-library-id <id>记忆库 ID—

bl knowledge retrieve

从百炼知识库检索（需要 AccessKey 认证）。

bl knowledge retrieve --index-id <id> --query <text> [flags]
参数说明默认值
--index-id <id>知识库索引 ID（必填）—
--query <text>搜索关键词（必填）—
--workspace-id <id>百炼工作空间 ID—
--top-k <n>返回结果数量10
--rerank启用重排序—
--rerank-top-n <n>重排序后保留数量—
--access-key-id <key>阿里云 AccessKey ID—
--access-key-secret <key>阿里云 AccessKey Secret—

五、开发辅助

bl file upload

上传本地文件到 DashScope 临时存储（48 小时有效）。

bl file upload --file <path> --model <model>
参数说明
--file <path>本地文件路径
--model <model>目标模型名称（文件绑定到此模型）

bl usage free

查询模型免费额度。

bl usage free --model <model> [flags]
参数说明默认值
--model <model>模型名称—
--region <region>API 地域cn-beijing

bl mcp list

列出已激活的 MCP 服务。

bl mcp list [flags]
参数说明默认值
--name <text>按名称过滤—
--type <type>服务类型：OFFICIAL 或 PRIVATEOFFICIAL
--page <n>页码1
--page-size <n>每页数量30
--region <region>API 地域cn-beijing

bl pipeline run

运行流水线工作流。

bl pipeline run <file> [flags]
参数说明默认值
--input <json>运行时输入（JSON）—
--input-file <path>从文件读取输入—
--concurrency <n>最大并行步骤数1
--events <format>事件输出格式：jsonl—
--timeout <seconds>步骤超时时间—

bl advisor recommend

根据需求推荐最佳模型。

bl advisor recommend <prompt> [flags]
参数说明
--message <text>描述您的需求
--dry-run仅显示意图分析和候选列表，不进行排序

六、常见问题

Q：安装失败怎么办？

确认 Node.js 版本 ≥ 22.12.0 且使用 npm 安装（不支持 pnpm/yarn）：

node --version
npm install -g bailian-cli
npx skills add modelstudioai/cli --all -g

Q：提示认证失败？

检查 API Key 是否正确配置：

bl auth status

如需重新配置：

bl auth logout
bl auth login --api-key sk-xxx
# 或拉起浏览器登录
bl auth login --console

Q：本地文件可以直接用吗？

可以。直接把文件路径传给 Agent 即可，CLI 会自动上传到临时存储（48 小时有效）：

帮我把 ./photo.png 改成水彩风格
帮我识别 ./meeting.wav 这段录音
描述一下 ./demo.mp4 这个视频的内容

Q：如何查看命令的完整参数？

告诉 Agent “看一下 bl image generate 有哪些参数”，或直接运行：

bl <命令> --help

👉友情提示:购买之前，别忘了先领优惠券：
https://www.aliyun.com/minisite/goods 领了之后再买活动中的云产品，可以享受折上折。

综上所述，阿里云百炼CLI通过极简的三步接入流程（安装、鉴权、使用），将平台强大的多模态AI能力无缝集成至主流的AI Agent工具生态中，赋能开发者一键调度图像生成与编辑、全模态理解、语音合成与识别、联网搜索等10余项模型能力，高效交付电商套图、新闻播客、故事书等复杂业务场景的专业级产出。这套命令行工具不仅兼容Claude Code、Cursor等主流开发环境，还提供了覆盖文本、图像、视频、语音的全链路API支持与详尽的参数指引，显著降低了多模态AI应用的门槛与开发周期，让开发者能更专注于业务创新而非底层技术集成，是加速AI Agent落地的得力助手。

本文原创链接：https://www.tengxunyun8.com/20600.html
版权所有,如未注明,均为原创,转载请注明