ElevenLabs CLI 报错怎么解决？6 类高频错误速查

ElevenLabs CLI 的报错大多集中在三类：安装方式不对、凭据冲突、agents push 配置校验失败。下表整理自官方 GitHub 仓库的 30 多个真实 issue，先对号入座找现象，再按对应解法处理（官方仓库）。

报错速查表

逐个展开：现象、原因、解法

1. Invalid hook call（npx 或 pnpm 运行时报 React 错误）

现象：运行 npx @elevenlabs/cli 时输出一大段 Invalid hook call，最后是 Cannot read properties of null (reading 'useEffect')。

这是官方仓库被反复报告的问题（issue #28、issue #40）：CLI 内部打包的 React 在 npx 缓存或 pnpm 链接环境下出现多副本冲突。维护者确认 v0.3.4 修复，期间有用户反馈 npm 安装正常、pnpm 仍有问题。

解法：npm install -g @elevenlabs/cli 装最新版，或清理 npx 缓存后重跑。

2. error: unknown command 'init'

现象：按早期 README 执行 npx @elevenlabs/cli init，报 unknown command 'init'（issue #41）。新版没有 init 子命令，文档写法过时。

解法：去掉 init 直接运行 npx @elevenlabs/cli。

3. agents push 报 422 UnprocessableEntityError

现象：agents init、pull 一路顺利，push 时报 422，提示 workflow edges 缺 conditions（issue #45），甚至配置完全没改也报。原因是 pull 拉下来的 workflow 回推时校验不过，官方已在后续版本修复；同类的 Say 节点 push 失败（issue #74）截至发稿仍开放。

解法：先升级 CLI；仍失败时检查 workflow 的 edges 是否带条件，或把 Say 节点换成标准 TTS 节点。

4. Invalid API key（但 key 明明是对的）

现象：npx @elevenlabs/cli auth login 输入正确的 key 却提示 Invalid API key（issue #80）。真实原因是用了受限范围的 key，权限不够，但旧版提示误导性强，维护者确认 v1 改进了反馈。

解法：到 ElevenLabs 官网后台生成权限充足的 key，再重新登录。

5. Only one of xi-api-key and authorization headers must be provided

现象：voices search 等命令报 api_key_with_authorization_header_not_allowed（issue #142，v1.1.0，官方已确认待修复）。原因是环境变量 ELEVENLABS_API_KEY 和 auth login 存下的 OAuth 凭据同时存在，CLI 把两个鉴权头一起发了出去。

解法：二选一，unset ELEVENLABS_API_KEY 或执行 elevenlabs auth logout。

6. --page-all 只返回第一页

现象：加 --page-all 参数后 has_more 为 true 且退出码 0，但只拿到第一页数据（issue #138）。截至发稿未修复。

解法：批量拉取时改用 --page 逐页处理。

预防建议

1. 固定版本全局安装（npm i -g），少用 npx 直跑，避开缓存冲突
2. 一台机器只保留一种凭据方式，环境变量和 OAuth 登录不要同时配
3. agents push 前先在网页端备份 agent 配置，push 失败可回滚

安装步骤、Node 环境和终端准备见站内 ElevenLabs CLI 安装教程。做语音 Agent 选型时可参考 GLM6 最新消息与发布进展，原型搭建则推荐 Google AI Studio 使用指南。