交談模式

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 原生 macOS/iOS/Android 對話使用本機語音辨識、Gateway 聊天，以及 talk.speak TTS。節點會公告 talk capability，並宣告它們支援的 talk.* 指令。
• 瀏覽器對話會使用 talk.client.create 建立由用戶端擁有的 webrtc 和 provider-websocket 工作階段，或使用 talk.session.create 建立由 Gateway 擁有的 gateway-relay 工作階段。managed-room 保留給 Gateway 交接和對講機房間使用。
• 僅轉錄用戶端會使用 talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" })，接著在需要字幕或聽寫且不需要助理語音回應時，使用 talk.session.appendAudio、talk.session.cancelTurn 和 talk.session.close。

1. 聆聽語音
2. 透過作用中的工作階段將轉錄文字傳送給模型
3. 等待回應
4. 透過設定的對話提供者說出回應（talk.speak）

​

行為（macOS）

• 啟用對話模式時，顯示常駐覆蓋層。
• 聆聽 → 思考 → 說話 階段轉換。
• 發生短暫停頓（靜音視窗）時，會送出目前的轉錄文字。
• 回覆會寫入 WebChat（與輸入相同）。
• 語音打斷（預設開啟）：如果使用者在助理說話時開始說話，我們會停止播放，並記錄打斷時間戳以供下一個提示使用。

​

回覆中的語音指令

{ "voice": "<voice-id>", "once": true }

• 僅限第一個非空白行。
• 未知鍵會被忽略。
• once: true 僅套用於目前回覆。
• 若沒有 once，該語音會成為對話模式的新預設值。
• JSON 行會在 TTS 播放前被移除。

• voice / voice_id / voiceId
• model / model_id / modelId
• speed、rate（WPM）、stability、similarity、style、speakerBoost
• seed、normalize、lang、output_format、latency_tier
• once

​

設定（~/.openclaw/openclaw.json）

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          apiKey: "openai_api_key",
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• interruptOnSpeech: true
• silenceTimeoutMs: 未設定時，對話會在傳送轉錄文字前保留平台預設的停頓視窗（macOS 和 Android 為 700 ms，iOS 為 900 ms）
• provider: 選擇作用中的對話提供者。macOS 本機播放路徑請使用 elevenlabs、mlx 或 system。
• providers.<provider>.voiceId: ElevenLabs 會回退到 ELEVENLABS_VOICE_ID / SAG_VOICE_ID（或 API 金鑰可用時的第一個 ElevenLabs 語音）。
• providers.elevenlabs.modelId: 未設定時預設為 eleven_v3。
• providers.mlx.modelId: 未設定時預設為 mlx-community/Soprano-80M-bf16。
• providers.elevenlabs.apiKey: 回退到 ELEVENLABS_API_KEY（或 Gateway shell profile，如果可用）。
• consultThinkingLevel: 即時 openclaw_agent_consult 呼叫背後完整 OpenClaw 代理執行的選用思考層級覆寫。
• consultFastMode: 即時 openclaw_agent_consult 呼叫的選用快速模式覆寫。
• realtime.provider: 選擇作用中的瀏覽器/伺服器即時語音提供者。WebRTC 請使用 openai，提供者 WebSocket 請使用 google，或透過 Gateway relay 使用僅橋接提供者。
• realtime.providers.<provider> 儲存由提供者擁有的即時設定。瀏覽器只會收到暫時性或受限制的工作階段憑證，絕不會收到標準 API 金鑰。
• realtime.providers.openai.voice: 內建 OpenAI Realtime 語音 ID。目前 gpt-realtime-2 語音包含 alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin 和 cedar；建議使用 marin 和 cedar 以取得最佳品質。
• realtime.brain: agent-consult 會透過 Gateway policy 路由即時工具呼叫；direct-tools 是僅限擁有者的相容性行為；none 用於轉錄或外部編排。
• realtime.instructions: 將提供者面向的系統指示附加到 OpenClaw 的內建即時提示。用它設定語音風格和語氣；OpenClaw 會保留預設的 openclaw_agent_consult 指引。
• talk.catalog 會公開各提供者的有效模式、傳輸方式、brain 策略、即時音訊格式和 capability 旗標，讓第一方對話用戶端能避免不支援的組合。
• 串流轉錄提供者會透過 talk.catalog.transcription 探索。目前 Gateway relay 會使用語音通話串流提供者設定，直到新增專用的對話轉錄設定介面。
• speechLocale: iOS/macOS 上裝置端對話語音辨識的選用 BCP 47 locale ID。未設定時會使用裝置預設值。
• outputFormat: macOS/iOS 預設為 pcm_44100，Android 預設為 pcm_24000（設定 mp3_* 可強制 MP3 串流）

​

macOS UI

• 選單列切換：對話
• 設定分頁：對話模式 群組（語音 ID + 打斷切換）
• 覆蓋層：
  • 聆聽：雲朵會隨麥克風音量脈動
  • 思考：下沉動畫
  • 說話：向外輻射的圓環
  • 點按雲朵：停止說話
  • 點按 X：退出對話模式

​

Android UI

• 語音分頁切換：對話
• 手動麥克風與對話是互斥的執行階段擷取模式。
• 當應用程式離開前景或使用者離開語音分頁時，手動麥克風會停止。
• 對話模式會持續執行，直到被切換關閉或 Android 節點中斷連線，並在作用中時使用 Android 的麥克風前景服務類型。

​

備註

• 需要語音與麥克風權限。
• 原生對話使用作用中的 Gateway 工作階段，且只有在回應事件不可用時才會回退到歷史記錄輪詢。
• 瀏覽器即時對話會使用 talk.client.toolCall 進行 openclaw_agent_consult，而不是將 chat.send 暴露給提供者擁有的瀏覽器工作階段。
• 僅轉錄對話使用 talk.session.create、talk.session.appendAudio、talk.session.cancelTurn 和 talk.session.close；用戶端會訂閱 talk.event 以取得部分/最終轉錄更新。
• Gateway 會使用作用中的對話提供者，透過 talk.speak 解析對話播放。Android 只有在該 RPC 不可用時，才會回退到本機系統 TTS。
• macOS 本機 MLX 播放會在存在時使用隨附的 openclaw-mlx-tts 輔助程式，或使用 PATH 上的可執行檔。開發期間可設定 OPENCLAW_MLX_TTS_BIN 指向自訂輔助二進位檔。
• eleven_v3 的 stability 會驗證為 0.0、0.5 或 1.0；其他模型接受 0..1。
• 設定 latency_tier 時，會驗證為 0..4。
• Android 支援 pcm_16000、pcm_22050、pcm_24000 和 pcm_44100 輸出格式，以進行低延遲 AudioTrack 串流。

​

相關

• 語音喚醒
• 音訊與語音備忘
• 媒體理解