대화 모드

Talk 모드는 다섯 가지 런타임 형태를 지원합니다.

• 네이티브 macOS/iOS/Android Talk: 로컬 음성 인식, Gateway 채팅, talk.speak TTS를 사용합니다. Node는 talk 기능을 알리고 지원하는 talk.* 명령을 선언합니다.
• iOS Talk(실시간): webrtc 전송 방식을 선택하거나 전송 방식을 생략한 OpenAI 실시간 구성에는 클라이언트가 관리하는 WebRTC를 사용합니다. gateway-relay, provider-websocket을 명시한 구성과 OpenAI가 아닌 실시간 구성은 Gateway가 관리하는 릴레이를 계속 사용하며, 비실시간 구성은 네이티브 음성 루프를 사용합니다.
• 브라우저 Talk: 클라이언트가 관리하는 webrtc/provider-websocket 세션에는 talk.client.create를 사용하고, Gateway가 관리하는 gateway-relay 세션에는 talk.session.create를 사용합니다. managed-room은 Gateway 핸드오프 및 워키토키 방용으로 예약되어 있습니다.
• Android Talk(실시간): talk.realtime.mode: "realtime" 및 talk.realtime.transport: "gateway-relay"로 명시적으로 활성화합니다. 그렇지 않으면 Android는 네이티브 음성 인식, Gateway 채팅, talk.speak를 계속 사용합니다.
• 전사 전용 클라이언트: talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" })를 호출한 다음, 어시스턴트의 음성 응답 없이 자막/받아쓰기를 수행하려면 talk.session.appendAudio, talk.session.cancelTurn, talk.session.close를 사용합니다. 일회성으로 업로드된 음성 메모는 계속 미디어 이해 오디오 경로를 사용합니다.

네이티브 Talk는 연속 루프입니다. 음성을 기다리고, 활성 세션을 통해 전사문을 모델에 전송하고, 응답을 기다린 다음, 구성된 Talk 제공자(talk.speak)를 통해 음성으로 재생합니다.

클라이언트가 관리하는 실시간 Talk는 chat.send를 직접 호출하는 대신 talk.client.toolCall을 통해 제공자의 도구 호출을 전달합니다. 실시간 상담이 활성화된 동안 클라이언트는 talk.client.steer 또는 talk.session.steer를 호출하여 음성 입력을 status, steer, cancel, followup으로 분류할 수 있습니다. 수락된 조정 입력은 활성 내장 실행의 대기열에 추가되며, 거부된 조정 입력에는 no_active_run, not_streaming, compacting 등의 사유가 반환됩니다.

전사 전용 Talk는 실시간 및 STT/TTS 세션과 동일한 Talk 이벤트 봉투를 내보내지만, mode: "transcription" 및 brain: "none"을 사용합니다. 모든 Talk 세션은 talk.event 채널로 이벤트를 브로드캐스트합니다. 클라이언트는 부분/최종 전사 업데이트(transcript.delta/transcript.done)와 기타 세션 텔레메트리를 받기 위해 이 채널을 구독합니다.

동작(macOS)

• Talk 모드가 활성화된 동안 항상 오버레이를 표시합니다.
• 듣는 중 → 생각하는 중 → 말하는 중 단계로 전환됩니다.
• 잠시 멈추면(무음 구간) 현재 전사문이 전송됩니다.
• 답변은 입력한 메시지와 마찬가지로 WebChat에 기록됩니다.
• 음성으로 중단(기본값: 켜짐): 어시스턴트가 말하는 동안 사용자가 말하면 재생이 중지되고, 다음 프롬프트를 위해 중단 타임스탬프가 기록됩니다.

답변의 음성 지시문

어시스턴트는 음성을 제어하기 위해 답변 앞에 한 줄의 JSON을 추가할 수 있습니다.

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

규칙:

• 비어 있지 않은 첫 번째 줄에만 사용할 수 있으며, TTS 재생 전에 JSON 줄이 제거됩니다.
• 알 수 없는 키는 무시됩니다.
• once: true는 현재 답변에만 적용됩니다. 이 값이 없으면 해당 음성이 Talk 모드의 새로운 기본값이 됩니다.

지원되는 키: 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.1",          speakerVoice: "cedar",        },      },      instructions: "따뜻하게 말하고 답변은 간결하게 유지하세요.",      mode: "realtime",      transport: "webrtc",      brain: "agent-consult",    },  },}

talk.catalog는 정식 제공자 ID와 레지스트리 별칭, 각 제공자의 유효한 모드/전송 방식/브레인 전략/실시간 오디오 형식/기능 플래그, 그리고 런타임에서 선택된 준비 상태 결과를 노출합니다. 자사 Talk 클라이언트는 제공자 별칭을 로컬에서 관리하는 대신 해당 카탈로그를 읽어야 합니다. 그룹 준비 상태를 생략하는 이전 Gateway는 확실히 구성되지 않은 것으로 간주하지 말고 검증되지 않은 것으로 취급하세요. 스트리밍 음성 인식 제공자는 talk.catalog.transcription을 통해 검색됩니다. 현재 Gateway 릴레이는 전용 Talk 음성 인식 구성 인터페이스가 출시될 때까지 Voice Call 스트리밍 제공자 구성을 사용합니다.

macOS UI

• 메뉴 막대 토글: Talk
• 구성 탭: Talk Mode 그룹(음성 ID + 중단 토글)
• 오버레이: 구체는 범용 Talk 파형을 렌더링합니다(iOS, watchOS 및 Android와 공유). 듣기 중에는 실시간 마이크 레벨을 따르고, 말하기 중에는 실제 TTS 재생 엔벌로프를 따르며, 생각 중에는 부드럽게 호흡하듯 움직입니다. 구체를 클릭하면 일시 중지/재개하고, 두 번 클릭하면 말하기를 중지하며, X를 클릭하면 Talk 모드를 종료합니다.

Android UI

• 음성 탭 토글: Talk
• 수동 Mic와 Talk는 상호 배타적인 캡처 모드입니다.
• 수동 Mic와 실시간 Talk는 연결된 Bluetooth Classic 또는 BLE 헤드셋 마이크를 우선 사용합니다. 연결이 끊기면 앱이 다른 헤드셋 입력을 요청하거나 기본 마이크로 대체하며, 캡처가 중지되면 기본 환경설정을 복원합니다.
• 앱이 포그라운드를 벗어나거나 사용자가 음성 탭을 나가면 수동 Mic가 중지됩니다.
• Talk Mode는 토글로 끄거나 Node의 연결이 끊길 때까지 계속 실행되며, 활성 상태에서는 Android의 마이크 포그라운드 서비스 유형을 사용합니다.
• Android는 지연 시간이 짧은 AudioTrack 스트리밍을 위해 pcm_16000, pcm_22050, pcm_24000, pcm_44100 출력 형식을 지원합니다.

참고

• 음성 인식 및 마이크 권한이 필요합니다.
• 네이티브 Talk는 활성 Gateway 세션을 사용하며, 응답 이벤트를 사용할 수 없는 경우에만 기록 폴링으로 대체합니다.
• Gateway는 활성 Talk 제공자를 사용하여 talk.speak를 통해 Talk 재생을 처리합니다. Android는 해당 RPC를 사용할 수 없는 경우에만 로컬 시스템 TTS로 대체합니다.
• macOS 로컬 MLX 재생은 번들로 제공되는 openclaw-mlx-tts 도우미가 있으면 이를 사용하고, 그렇지 않으면 PATH에 있는 실행 파일을 사용합니다. 개발 중에 사용자 지정 도우미 바이너리를 지정하려면 OPENCLAW_MLX_TTS_BIN을 설정하세요.
• 음성 지시문 값 범위(ElevenLabs): stability, similarity, style은 0..1을 허용하고, speed는 0.5..2를 허용하며, latency_tier는 0..4를 허용합니다.

관련 문서

• 음성 깨우기
• 오디오 및 음성 메모
• 미디어 이해