OpenClaw 语音转文字配置指南（Azure OpenAI）
目标读者：本文为 AI agent 可逐步执行的操作手册。每个步骤都有明确的前提条件、操作命令和验证方法。
OpenClaw 支持在收到语音消息时自动将其转录为文字，转录后的内容会替换消息体，供后续 agent 处理。本文介绍如何使用 Azure OpenAI gpt-4o-transcribe 部署来实现这一功能。
前提条件
在开始之前，请确认：
- OpenClaw 已安装并正常运行（
openclaw gateway status返回 running） - 已有一个 Azure OpenAI 资源，并在其中创建了
gpt-4o-transcribe模型部署 - 能够编辑
~/.openclaw/openclaw.json
需要用户提供的信息：
| 参数 | 说明 |
|---|---|
AZURE_OPENAI_ENDPOINT | Azure OpenAI 资源的 Endpoint，格式如 https://<resource-name>.openai.azure.com |
AZURE_OPENAI_API_KEY | 对应资源的 API Key |
DEPLOYMENT_NAME | gpt-4o-transcribe 模型的部署名称（通常就是 gpt-4o-transcribe） |
工作原理
OpenClaw 的语音转录通过 tools.media.audio 配置项控制。当收到音频附件时：
- OpenClaw 定位音频文件（本地路径或 URL）
- 按
models列表顺序尝试转录，第一个成功的结果生效 - 转录成功后，消息体被替换为
[Audio]块，同时设置{{Transcript}}变量 - Agent 接收到的就是转录后的文字内容
支持的配置方式有两种：
- Provider 模式：直接声明
provider: "openai"（适用于标准 OpenAI 端点） - CLI 模式：通过
curl等命令调用 API（适用于 Azure OpenAI 等自定义端点）
由于 Azure OpenAI 的 Endpoint 和认证方式与标准 OpenAI 不同，这里使用 CLI 模式，通过 curl 直接调用 Azure 的转录 API。
步骤一：验证 Azure OpenAI 部署可用
在配置 OpenClaw 之前，先手动验证 API 可用。
操作： 准备一段测试音频文件（任意 .wav 或 .mp3），然后执行：
curl -s \
"https://<YOUR_ENDPOINT>/openai/deployments/<YOUR_DEPLOYMENT_NAME>/audio/transcriptions?api-version=2025-03-01-preview" \
-H "api-key: <YOUR_API_KEY>" \
-F "file=@/path/to/test-audio.wav"预期结果： 返回 JSON，其中包含 "text" 字段，例如：
{"text": "你好，这是一段测试音频。"}如果返回 401 或 404，请检查 Endpoint、部署名称和 API Key 是否正确。
步骤二：编辑 OpenClaw 配置文件
操作： 打开 ~/.openclaw/openclaw.json，在 tools 节点下添加或修改 media.audio 配置：
{
"tools": {
"media": {
"audio": {
"enabled": true,
"models": [
{
"type": "cli",
"command": "curl",
"args": [
"-s",
"https://<YOUR_ENDPOINT>/openai/deployments/<YOUR_DEPLOYMENT_NAME>/audio/transcriptions?api-version=2025-03-01-preview",
"-H",
"api-key: <YOUR_API_KEY>",
"-F",
"file=@{{MediaPath}}"
]
}
]
}
}
}
}参数说明：
<YOUR_ENDPOINT>：替换为你的 Azure OpenAI 资源 Endpoint（不含末尾斜杠）<YOUR_DEPLOYMENT_NAME>：替换为你的gpt-4o-transcribe部署名称<YOUR_API_KEY>：替换为对应的 API Key{{MediaPath}}：保持原样，这是 OpenClaw 运行时自动替换为实际音频文件路径的模板变量
注意： curl 调用 Azure OpenAI 转录 API，返回的是 JSON 格式，其中 text 字段为转录内容。OpenClaw 会自动从 stdout 中解析 {"text": "..."} 格式的输出并提取文字内容。
步骤三：重启 Gateway 使配置生效
操作：
openclaw gateway restart或者，如果通过 systemd 管理：
systemctl --user restart openclaw-gateway验证： 执行以下命令确认 Gateway 正常运行：
openclaw gateway status预期输出包含 running 或 active。
步骤四：发送语音消息验证功能
操作： 通过已配置的 channel（如 Discord、Telegram、WhatsApp），向 OpenClaw 发送一条语音消息。
预期结果：
- OpenClaw 自动转录语音内容
- Agent 收到的是转录后的文字，并据此回复
- 如果开启了
echoTranscript（见可选配置），会在 agent 回复前先发送一条转录确认消息
故障排查：
- 如果语音消息没有被处理，检查 Gateway 日志：
journalctl _PID=$(pgrep -f openclaw) | tail -50 - 如果返回 JSON 格式不对，手动执行步骤一的 curl 命令，确认 API 返回格式正确
可选配置
显示转录内容（echoTranscript）
如果希望在 agent 处理前，先将转录内容回显到 chat，可添加：
{
"tools": {
"media": {
"audio": {
"enabled": true,
"echoTranscript": true,
"echoFormat": "📝 \"{transcript}\"",
"models": ["..."]
}
}
}
}限制文件大小（maxBytes）
默认上限为 20MB。如需调整：
{
"tools": {
"media": {
"audio": {
"enabled": true,
"maxBytes": 10485760,
"models": ["..."]
}
}
}
}按 chat 类型限制转录范围（scope）
如果只想在私聊中转录，群组中不转录：
{
"tools": {
"media": {
"audio": {
"enabled": true,
"scope": {
"default": "allow",
"rules": [
{ "action": "deny", "match": { "chatType": "group" } }
]
},
"models": ["..."]
}
}
}
}完整配置示例
以下是含转录功能的最简完整配置片段（~/.openclaw/openclaw.json 中的相关部分）：
{
"tools": {
"media": {
"audio": {
"enabled": true,
"echoTranscript": false,
"models": [
{
"type": "cli",
"command": "curl",
"args": [
"-s",
"https://<YOUR_ENDPOINT>/openai/deployments/<YOUR_DEPLOYMENT_NAME>/audio/transcriptions?api-version=2025-03-01-preview",
"-H",
"api-key: <YOUR_API_KEY>",
"-F",
"file=@{{MediaPath}}"
]
}
]
}
}
}
}⚠️ 安全提示：API Key 以明文存储在配置文件中，请确保
~/.openclaw/openclaw.json的文件权限设置为仅所有者可读（chmod 600 ~/.openclaw/openclaw.json）。