AutoGPT Classic 语音输出（TTS）配置指南：从 --speak 命令行开关到 ElevenLabs 接入全解析

本文基于 AutoGPT 仓库中 classic 版语音配置文档，讲解如何为 AutoGPT Classic 开启语音播报（Speak Mode）：完整继承原文档的启动命令、ElevenLabs API 配置步骤与可用音色表，并结合仓库源码还原 --speak 参数从命令行到 TTS 请求的实际调用链，以及各 TTS 提供者的配置项与默认值。读完后你可以独立完成语音能力的配置、音色选择，并在出问题时对照源码定位原因。

1. 开启 Speak Mode：--speak 命令行开关

原文档给出的启用方式是：

./autogpt.sh --speak

该命令对应 Classic 版 Python CLI 中注册的 --speak 布尔标志。在 cli.py 中可以看到该选项的定义：

@click.option("--speak", is_flag=True, help="Enable Speak Mode")

也就是说 --speak 是一个纯开关参数（is_flag=True），不带取值，加上即代表"启用 Speak Mode"。该参数随后通过 speak=speak 传入应用入口（cli.py），最终在 main.py 中落到全局配置上：

if speak:
    config.tts_config.speak_mode = True

从源码结构看，speak_mode 会一路传递到 UI 层（app_config.tts_config.speak_mode 被用于构造终端 provider 等，见 main.py），由界面层在打印 Agent 输出时触发语音合成。因此整个功能的核心链路是：命令行 --speak → tts_config.speak_mode = True → UI 层决定何时调用 TTS。

适用前提：本文针对 classic/original_autogpt 目录下的 Classic 版 AutoGPT；仓库根目录另有 autogpt_platform（平台版）与 classic/forge（Forge 版）代码库，本文第 4 节会涉及 Forge 版的同名实现作为佐证。

2. 配置 ElevenLabs API Key 与音色

AutoGPT 的语音输出由 Eleven Labs 提供，其提供语音设计、语音合成与预制音色等能力。按原文档的步骤配置：

1. 前往 ElevenLabs 官网注册账号（如尚未注册）。
2. 选择并开通 Starter 套餐。
3. 点击页面右上角头像图标，进入 Profile 找到你的 API Key。

然后在 .env 文件中设置：

• ELEVENLABS_API_KEY —— 你在 ElevenLabs 控制台中获取的 API Key；
• ELEVENLABS_VOICE_1_ID —— 音色标识，文档示例值为 "premade/Adam"。

关于音色环境变量的命名，需要注意源码与实际配置的差异。 当前仓库中实际被解析的环境变量是 ELEVENLABS_VOICE_ID：

• Classic 版设置定义中（introspection.py）：

"ELEVENLABS_API_KEY": SettingInfo(
    name="elevenlabs_api_key",
    env_var="ELEVENLABS_API_KEY",
    description="Eleven Labs API key",
    field_type="secret",
),
"ELEVENLABS_VOICE_ID": SettingInfo(
    name="elevenlabs_voice_id",
    env_var="ELEVENLABS_VOICE_ID",
    description="Eleven Labs voice ID",
    field_type="str",
),

• Forge 版的配置类（eleven_labs.py）同样读取这两个环境变量：

class ElevenLabsConfig(SystemConfiguration):
    api_key: str = UserConfigurable(from_env="ELEVENLABS_API_KEY")
    voice_id: str = UserConfigurable(from_env="ELEVENLABS_VOICE_ID")

从源码结构看，文档中的 ELEVENLABS_VOICE_1_ID 是旧版多音色编号命名的残留写法，而代码统一按 ELEVENLABS_VOICE_ID 取值，建议以源码为准填写该变量。

3. 可用音色列表（Voice Name 与 Voice ID 对照表）

原文档附带的完整音色表如下（ElevenLabs 提供的预制音色）：

Name	Voice ID
Rachel	21m00Tcm4TlvDq8ikWAM
Domi	AZnzlk1XvdvUeBnXmlld
Bella	EXAVITQu4vr4xnSDxMaL
Antoni	ErXwobaYiN019PkySvjV
Elli	MF3mGyEYCl7XYWbV9V6O
Josh	TxGEqnHWrfWFTfGW9XjX
Arnold	VR6AewLTigWG4xSOukaG
Adam	pNInz6obpgDQGcFmaJgB
Sam	yoZ06aMxZJJ28mfd3POQ

文档特别提示：配置音色时，既可以填写音色名称，也可以直接填写 Voice ID。这一点在源码中得到直接印证——eleven_labs.py 内维护了与文档表格完全一致的 voice_options 映射表：

default_voices = ["ErXwobaYiN019PkySvjV", "EXAVITQu4vr4xnSDxMaL"]
voice_options = {
    "Rachel": "21m00Tcm4TlvDq8ikWAM",
    "Domi":   "AZnzlk1XvdvUeBnXmlld",
    "Bella":  "EXAVITQu4vr4xnSDxMaL",
    "Antoni": "ErXwobaYiN019PkySvjV",
    "Elli":   "MF3mGyEYCl7XYWbV9V6O",
    "Josh":   "TxGEqnHWrfWFTfGW9XjX",
    "Arnold": "VR6AewLTigWG4xSOukaG",
    "Adam":   "pNInz6obpgDQGcFmaJgB",
    "Sam":    "yoZ06aMxZJJ28mfd3POQ",
}

初始化逻辑是：若用户配置的 voice_id 恰好是上表中的名称，则自动替换为对应的ID；若是 ID 或其他自定义值，则原样使用。此外，代码定义了占位符集合 PLACEHOLDERS = {"your-voice-id"}——如果环境变量里还留着模板占位值 your-voice-id，它会不被采纳，系统回退到 default_voices 中的默认音色（Antoni 与 Bella）。这对排查"我明明配了音色，声音却不是我想要的那个"类问题非常有用。

4. 源码级解析：一次语音合成的完整流程

以 Forge 版实现（classic/forge/forge/speech/eleven_labs.py）为参照，ElevenLabsSpeech 类的 _speech 方法展示了 TTS 的完整落地流程：

tts_url = (
    f"https://api.elevenlabs.io/v1/text-to-speech/{self._voices[voice_id]}"
)
response = requests.post(tts_url, headers=self._headers, json={"text": text})

if response.status_code == 200:
    with open("speech.mpeg", "wb") as f:
        f.write(response.content)
    playsound("speech.mpeg", True)
    os.remove("speech.mpeg")
    return True
else:
    logger.warning("Request failed with status code:", response.status_code)
    logger.info("Response content:", response.content)
    return False

可以从中读出四个关键实现细节：

1. 请求头：API Key 通过 xi-api-key 请求头传递（_headers 在 _setup 中由 config.api_key 构建），同时声明 Content-Type: application/json；
2. 播放方式：合成结果先写为临时文件 speech.mpeg，再通过 playsound 库同步播放后删除临时文件。这也解释了运行环境依赖——本机需要具备 playsound 的音频播放能力，无声音卡/无头环境下播放可能静默失败；
3. 失败可观测：请求非 200 时不抛异常，而是打 warning/info 日志（含状态码与响应体）并返回 False。若 Agent 输出"不发声"，第一排查点就是这条日志；
4. 多音色索引：_use_custom_voice 支持按 voice_index 指定使用哪个音色槽位，自定义音色（非占位符）会覆盖默认槽位 0。

5. TTS 提供者不止 ElevenLabs：可选项与默认值

原文档聚焦 ElevenLabs，但 Classic 版的设置体系暴露了完整的 TTS 提供者选项。在 introspection.py 中定义了：

环境变量	说明	取值/默认值
TEXT_TO_SPEECH_PROVIDER	文本转语音提供者	可选 gtts / streamelements / elevenlabs / macos，默认 gtts
ELEVENLABS_API_KEY	Eleven Labs API Key	secret 类型
ELEVENLABS_VOICE_ID	Eleven Labs 音色 ID	字符串
STREAMELEMENTS_VOICE	StreamElements 音色名	默认 Brian

也就是说：不配置任何 ElevenLabs 信息时，默认走 gtts 路径；若要切换到 ElevenLabs 的高保真音色，需把提供者设为 elevenlabs 并补齐 API Key 与音色 ID。tts 作为独立设置类别注册在 categories.py（id="tts"），在 Classic 版的设置界面中可整体管理。

6. 配置核对清单与排查要点

综合原文档与源码，一套可运行的 ElevenLabs 语音配置应满足：

• 启动参数：命令行带 --speak（对应 tts_config.speak_mode = True，见 main.py）；
• .env 中 ELEVENLABS_API_KEY 已填写有效 Key；
• .env 中 ELEVENLABS_VOICE_ID 填写第 3 节表格中的音色名称或 ID 均可（代码会自动做名称→ID 映射），不要保留占位符 your-voice-id，否则会回退到默认音色 Antoni/Bella；
• 若启用了提供者选择机制，TEXT_TO_SPEECH_PROVIDER 需为 elevenlabs（默认值是 gtts）；
• 排查无声问题：查看日志中 "Request failed with status code" 警告（401/403 通常意味着 API Key 无效，配额类错误则需检查 ElevenLabs 套餐状态）。

以上所有配置项、音色表与行为细节均可在仓库内对照验证：文档见 voice.md，Classic 设置定义见 introspection.py，合成实现见 eleven_labs.py。按此配置完成后，AutoGPT Classic 在开启 Speak Mode 运行时即可将 Agent 的输出通过所选 ElevenLabs 音色朗读出来。