🎤 OpenClaw Matrix 语音消息集成

为什么选择 Matrix 做语音交互？

Matrix 是一个开放的、去中心化的通信协议。相比 Discord、Telegram 等封闭平台，Matrix 的优势在于：

• 完全自主可控：自建服务器，数据不出域
• 开放协议：没有平台锁定，随时迁移
• 端到端加密：语音消息也支持 E2EE
• 丰富的媒体支持：原生支持音频、视频消息

在 2026 年 6 月的更新中，OpenClaw 正式支持了 Matrix 协议的语音消息收发，让 AI Agent 在 Matrix 平台上实现了"能听会说"。

架构概览

配置步骤

第一步：Matrix 服务器配置

# openclaw.json - Matrix 频道配置
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.your-domain.com",
      "userId": "@bot:your-domain.com",
      "accessToken": "syt_xxxxxxxxxxxx",
      "deviceId": "OPENCLAW_BOT",
      "voice": {
        "enabled": true,
        "receiveVoiceMessages": true,
        "sendVoiceMessages": true,
        "maxDurationSeconds": 300
      }
    }
  }
}

第二步：STT 语音识别配置

# 语音转文字配置
{
  "stt": {
    "provider": "whisper",  // whisper | google | azure
    "model": "whisper-1",
    "language": "zh",
    "apiKey": "your-api-key",
    "fallback": {
      "enabled": true,
      "provider": "local-whisper"
    }
  }
}

第三步：TTS 语音合成配置

# 文字转语音配置
{
  "tts": {
    "provider": "openai",  // openai | elevenlabs | edge-tts
    "voice": "alloy",
    "speed": 1.0,
    "format": "ogg",  // Matrix 原生支持 ogg
    "fallback": {
      "enabled": true,
      "provider": "edge-tts"
    }
  }
}

语音消息处理流程

接收语音消息

# Agent 收到语音消息时的处理流程
1. 下载音频文件 (.ogg / .m4a / .wav)
2. 调用 STT 服务转录为文字
3. 将文字作为用户消息传递给 Agent
4. Agent 生成文字回复
5. 调用 TTS 服务合成为语音
6. 通过 Matrix 发送语音消息

在 Agent 中感知语音上下文

# 当消息来自语音时，Agent 会收到额外上下文
{
  "message_type": "voice",
  "transcript": "帮我查一下明天的天气",
  "confidence": 0.95,
  "duration_seconds": 3.2,
  "language": "zh-CN"
}

高级功能

语音+文字双回复

# 配置同时发送语音和文字回复
{
  "voice": {
    "replyMode": "both",  // voice-only | text-only | both
    "textFirst": true     // 先发文字，再发语音
  }
}

多语言语音切换

# 根据用户语言自动切换语音
{
  "tts": {
    "languageMapping": {
      "zh": { "provider": "edge-tts", "voice": "zh-CN-XiaoxiaoNeural" },
      "en": { "provider": "openai", "voice": "alloy" },
      "ja": { "provider": "edge-tts", "voice": "ja-JP-NanamiNeural" }
    }
  }
}

语音消息的情感控制

# TTS 情感参数（部分 TTS 引擎支持）
{
  "tts": {
    "emotion": "friendly",  // friendly | professional | excited
    "emphasis": "moderate"
  }
}

最佳实践