대화 모드

Documentation Index

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

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

• 네이티브 macOS/iOS/Android Talk는 로컬 음성 인식, Gateway 채팅, talk.speak TTS를 사용합니다. 노드는 talk capability를 알리고, 지원하는 talk.* 명령을 선언합니다.
• 브라우저 Talk는 클라이언트 소유 webrtc 및 provider-websocket 세션에는 talk.client.create를 사용하고, Gateway 소유 gateway-relay 세션에는 talk.session.create를 사용합니다. managed-room은 Gateway 핸드오프와 워키토키 방을 위해 예약되어 있습니다.
• 전사 전용 클라이언트는 어시스턴트 음성 응답 없이 자막이나 받아쓰기가 필요할 때 talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" })를 사용한 뒤 talk.session.appendAudio, talk.session.cancelTurn, talk.session.close를 사용합니다.

1. 음성을 듣습니다
2. 활성 세션을 통해 transcript를 모델로 보냅니다
3. 응답을 기다립니다
4. 구성된 Talk 프로바이더(talk.speak)를 통해 음성으로 재생합니다

​

동작 (macOS)

• Talk 모드가 활성화된 동안 항상 켜진 overlay.
• Listening → Thinking → Speaking 단계 전환.
• 짧은 일시정지(무음 window) 시 현재 transcript가 전송됩니다.
• 답변은 WebChat에 작성됩니다(입력한 것과 동일).
• 음성으로 중단(기본값 켜짐): 어시스턴트가 말하는 동안 사용자가 말하기 시작하면, 재생을 중지하고 다음 prompt를 위해 중단 timestamp를 기록합니다.

​

답변의 음성 지시문

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

• 비어 있지 않은 첫 줄에만 적용됩니다.
• 알 수 없는 key는 무시됩니다.
• once: true는 현재 답변에만 적용됩니다.
• once가 없으면 해당 음성이 Talk 모드의 새 기본값이 됩니다.
• 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: 설정하지 않으면 Talk는 transcript를 보내기 전 플랫폼 기본 일시정지 window를 유지합니다(macOS 및 Android에서는 700 ms, iOS에서는 900 ms)
• provider: 활성 Talk 프로바이더를 선택합니다. macOS 로컬 재생 경로에는 elevenlabs, mlx, 또는 system을 사용하세요.
• providers.<provider>.voiceId: ElevenLabs의 경우 ELEVENLABS_VOICE_ID / SAG_VOICE_ID로 fallback합니다(또는 API key를 사용할 수 있으면 첫 번째 ElevenLabs voice).
• providers.elevenlabs.modelId: 설정하지 않으면 기본값은 eleven_v3입니다.
• providers.mlx.modelId: 설정하지 않으면 기본값은 mlx-community/Soprano-80M-bf16입니다.
• providers.elevenlabs.apiKey: ELEVENLABS_API_KEY로 fallback합니다(또는 사용 가능한 경우 gateway shell profile).
• consultThinkingLevel: 실시간 openclaw_agent_consult 호출 뒤의 전체 OpenClaw agent 실행에 대한 선택적 thinking level override입니다.
• consultFastMode: 실시간 openclaw_agent_consult 호출에 대한 선택적 fast-mode override입니다.
• realtime.provider: 활성 브라우저/서버 실시간 음성 프로바이더를 선택합니다. WebRTC에는 openai, 프로바이더 WebSocket에는 google, Gateway relay를 통하는 bridge 전용 프로바이더를 사용하세요.
• realtime.providers.<provider>는 프로바이더 소유 실시간 구성을 저장합니다. 브라우저는 표준 API key가 아니라 ephemeral 또는 제한된 세션 자격 증명만 받습니다.
• realtime.providers.openai.voice: 기본 제공 OpenAI Realtime voice id입니다. 현재 gpt-realtime-2 voice는 alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar이며, 최고 품질에는 marin과 cedar가 권장됩니다.
• realtime.brain: agent-consult는 실시간 도구 호출을 Gateway policy를 통해 라우팅합니다. direct-tools는 소유자 전용 compatibility 동작입니다. none은 전사 또는 외부 orchestration용입니다.
• realtime.instructions: 프로바이더 대상 system instructions를 OpenClaw의 기본 제공 실시간 prompt에 추가합니다. 음성 스타일과 톤에 사용하세요. OpenClaw는 기본 openclaw_agent_consult guidance를 유지합니다.
• talk.catalog는 각 프로바이더의 유효한 모드, transport, brain 전략, 실시간 오디오 형식, capability flag를 노출하여 first-party Talk 클라이언트가 지원되지 않는 조합을 피할 수 있게 합니다.
• Streaming 전사 프로바이더는 talk.catalog.transcription을 통해 발견됩니다. 현재 Gateway relay는 전용 Talk 전사 구성 surface가 추가될 때까지 Voice Call Streaming 프로바이더 구성을 사용합니다.
• speechLocale: iOS/macOS의 온디바이스 Talk 음성 인식을 위한 선택적 BCP 47 locale id입니다. 디바이스 기본값을 사용하려면 설정하지 마세요.
• outputFormat: macOS/iOS에서는 기본값이 pcm_44100, Android에서는 pcm_24000입니다(MP3 Streaming을 강제하려면 mp3_* 설정)

​

macOS UI

• 메뉴 막대 toggle: Talk
• 구성 탭: Talk Mode group(voice id + interrupt toggle)
• Overlay:
  • Listening: cloud가 마이크 level에 따라 pulse
  • Thinking: 가라앉는 animation
  • Speaking: 방사형 ring
  • cloud 클릭: 말하기 중지
  • X 클릭: Talk 모드 종료

​

Android UI

• Voice 탭 toggle: Talk
• 수동 Mic와 Talk는 상호 배타적인 런타임 캡처 모드입니다.
• 앱이 foreground를 벗어나거나 사용자가 Voice 탭을 떠나면 수동 Mic가 중지됩니다.
• Talk Mode는 꺼질 때까지 또는 Android 노드 연결이 끊길 때까지 계속 실행되며, 활성 상태에서는 Android의 microphone foreground-service type을 사용합니다.

​

참고

• Speech + Microphone permission이 필요합니다.
• 네이티브 Talk는 활성 Gateway 세션을 사용하며, 응답 이벤트를 사용할 수 없을 때만 history polling으로 fallback합니다.
• 브라우저 실시간 Talk는 chat.send를 프로바이더 소유 브라우저 세션에 노출하는 대신 openclaw_agent_consult에 talk.client.toolCall을 사용합니다.
• 전사 전용 Talk는 talk.session.create, talk.session.appendAudio, talk.session.cancelTurn, talk.session.close를 사용합니다. 클라이언트는 부분/최종 transcript update를 위해 talk.event를 구독합니다.
• gateway는 활성 Talk 프로바이더를 사용해 talk.speak를 통해 Talk 재생을 resolve합니다. Android는 해당 RPC를 사용할 수 없을 때만 로컬 system TTS로 fallback합니다.
• macOS 로컬 MLX 재생은 번들된 openclaw-mlx-tts helper가 있으면 이를 사용하고, 없으면 PATH의 실행 파일을 사용합니다. 개발 중 custom helper binary를 가리키려면 OPENCLAW_MLX_TTS_BIN을 설정하세요.
• eleven_v3의 stability는 0.0, 0.5, 1.0으로 검증됩니다. 다른 모델은 0..1을 허용합니다.
• latency_tier는 설정된 경우 0..4로 검증됩니다.
• Android는 저지연 AudioTrack Streaming을 위해 pcm_16000, pcm_22050, pcm_24000, pcm_44100 출력 형식을 지원합니다.

​

관련 항목

• Voice wake
• Audio 및 음성 메모
• Media 이해