ElevenLabs CLI 安装教程：5 分钟装好就能用

ElevenLabs CLI 是 ElevenLabs 官方开源的命令行工具（Rust 编写，MIT 协议），完整流程只需要两步：装好二进制、配一个 API Key，大约 5 分钟就能跑通，免费注册的账号有免费额度可试用。它有两层能力：把 ElevenLabs 所有 API 端点变成子命令直接调用，以及把对话式语音智能体（Conversational AI agents）的配置放到本地文件里像代码一样管理。

先说一个搜索时容易踩的坑：老教程里常写的仓库地址 elevenlabs/elevenlabs-cli 已经不可用，官方现仓库是 github.com/elevenlabs/cli，本文所有命令以该仓库 README 为准（v1 版本）。

装之前需要准备什么

• 一个 ElevenLabs 账号（elevenlabs.io 注册），用于生成 API Key。
• 一把 API Key：登录后到 API Keys 设置页 创建，以 xi- 开头。
• 操作系统不限：macOS、Linux、Windows 都有官方安装通道，无需额外运行时（npm 安装方式除外，它需要 Node.js）。

四种安装方式，按你的系统选

方式一：Homebrew（推荐 macOS / Linux）

brew install elevenlabs/tap/elevenlabs

方式二：npm（全平台通用）

npm install -g @elevenlabs/cli

npm 包装的是同一个二进制，会自动选对平台构建。不想全局安装可以用 npx @elevenlabs/cli <command> 单次运行。

方式三：官方 Shell 脚本（macOS / Linux）

curl --proto '=https' --tlsv1.2 -LsS https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh

方式四：PowerShell（Windows）

powershell -ExecutionPolicy ByPass -c "irm https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.ps1 | iex"

Windows 用户也可用 Scoop：先 scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket，再 scoop install elevenlabs。开发者还可以从源码构建（Rust 工具链 + cargo install --path .）。

安装完成后在终端输入 elevenlabs --help，能列出所有子命令就说明装好了。再用 elevenlabs user get --xi-api-key xi-你的key 试一把鉴权，能返回账号信息说明 Key 也配通了，后面就可以直接用环境变量方式。

配置 API Key：三种姿势

每次请求都通过 xi-api-key 头鉴权，最常用的做法是设环境变量：

export ELEVENLABS_API_KEY=xi-你的key

两种替代写法：在项目目录放一个 .env 文件写入同样内容（CLI 会自动读取，适合按项目隔离密钥）；或单次调用时用 --xi-api-key 参数临时传。

注意密钥安全：xi- 开头的 Key 等同于你的账号额度，别提交进 git 仓库。

第一条命令：让终端开口说话

elevenlabs say "this came from the terminal"
echo "build finished" | elevenlabs say

say 是最直观的命令：把文字转成语音并直接播放，还能配合管道用，比如构建结束时播报提示。默认音色、模型、播放器可以用 elevenlabs say config 查看和修改；默认模型是 eleven_v3，这是官方表现力最强的语音模型，能读 [whispers] 这类音频标签。想存成文件就加 --output out.mp3。

一个实用细节：CLI 本身不带播放器，会自动找系统里的 ffplay、mpv、afplay（macOS 自带）等工具播放，一个都没有时建议先装 ffmpeg 或 mpv。

杀手锏：Agents as Code

这是 CLI 相对网页控制台最大的增量。你可以把语音智能体的配置存成本地 JSON 文件，走 git 分支管理，再推拉同步到 ElevenLabs 云端：

elevenlabs agents init my-project        # 初始化项目脚手架
elevenlabs agents add reception --template customer-service   # 从模板创建智能体
elevenlabs agents status                  # 查看本地配置状态
elevenlabs agents push                    # 推送到云端

官方内置 6 套模板：default、minimal、voice-only、text-only、customer-service、assistant。同步是双向无损的：pull 拉下来的就是线上原始配置，push 会覆盖云端对应分支。配套的还有 tools（工具管理）和 tests（自动化测试智能体对话）两套子命令。

中文语音效果与选型对比，可参考 Gemini 3.5 Transcribe 详解、MAI-Transcribe-2 详解 和 2026 AI 语音产品横评。

从 v0 升级的注意：v0 的 agents list 显示的是本地配置，v1 里这个命令属于云端 API，本地视图改用 agents status；删除智能体也改成了 agents delete --agent-id <id>。

数据驻留与合规

企业用户可以用 elevenlabs residency eu-residency 把请求路由切到欧盟区，支持 global（默认）、us、eu、india、singapore 五个区域，设置保存在 ~/.elevenlabs/config.json，对所有命令生效。

常见报错速查