Talk mode

Talk mode 문서는 OpenClaw 공식 문서(nodes/talk)를 한국어로 정리한 가이드입니다. Talk mode: continuous speech conversations across local STT/TTS and realtime voice 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Talk mode: continuous speech conversations across local STT/TTS and realtime voice

한국어 가이드 범위: nodes/talk 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Behavior (macOS)
Voice directives in replies
Config (~/.openclaw/openclaw.json)
macOS UI
Android UI
참고
관련 문서

상세 내용

본문

Native Talk is a continuous loop: listen for speech, send the transcript to the model through the active session, wait for the response, then speak it via the configured Talk provider (talk.speak).

주요 항목:

Native macOS/iOS/Android Talk: native speech recognition, Gateway chat, and talk.speak TTS. Apple Speech recognition on macOS/iOS may use network services; Android behavior depends on the installed speech service. Nodes advertise the talk capability and declare which talk.* commands they support.
iOS Talk (realtime): client-owned WebRTC for OpenAI realtime configs that select webrtc transport or omit transport. Explicit gateway-relay, provider-websocket, and non-OpenAI realtime configs stay on the Gateway-owned relay; non-realtime configs use the native speech loop.
Browser Talk: talk.client.create for client-owned webrtc/provider-websocket sessions, or talk.session.create for Gateway-owned gateway-relay sessions. managed-room is reserved for Gateway handoff and walkie-talkie rooms.
Android Talk (realtime): opt in with talk.realtime.mode: "realtime" and talk.realtime.transport: "gateway-relay". Otherwise Android stays on native speech recognition, Gateway chat, and talk.speak.
Transcription-only clients: talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" }), then talk.session.appendAudio, talk.session.cancelTurn, and talk.session.close for captions/dictation without an assistant voice response. One-shot uploaded voice notes still use the media understanding audio path.

Behavior (macOS)

주요 항목:

Always-on overlay while Talk mode is enabled.
Listening → Thinking → Speaking phase transitions.
On a short pause (silence window), the current transcript is sent.
Replies are written to WebChat (same as typing).
Interrupt on speech (default on): if the user talks while the assistant is speaking, playback stops and the interruption timestamp is noted for the next prompt.

Voice directives in replies

The assistant can prefix a reply with a single JSON line to control voice:

주요 항목:

First non-empty line only; the JSON line is stripped before TTS playback.
Unknown keys are ignored.
once: true applies to the current reply only; without it, the voice becomes the new Talk mode default.

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

Config (~/.openclaw/openclaw.json)

talk.catalog exposes canonical provider ids and registry aliases, each provider's valid modes/transports/brain strategies/realtime audio formats/capability flags, and the runtime-selected readiness result. First-party Talk clients should read that catalog instead of maintaining provider aliases locally; treat an older Gateway that omits group readiness as unverified rather than definitively unconfigured. Streaming transcription providers are discovered through talk.catalog.transcription; the current Gateway relay uses the Voice Call streaming provider config until a dedicated Talk transcription config surface ships.

Key	Default	Notes
`provider`	-	Active Talk TTS provider. Use `elevenlabs`, `mlx`, or `system` for macOS-local playback paths.
`providers.<id>.voiceId`	-	ElevenLabs falls back to `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`, or the first available voice with an API key.
`speechLocale`	device default	BCP 47 locale for Android, iOS, and macOS native speech recognition. Apple Speech may use network services; Android also forwards the language component to realtime input transcription.
`providers.elevenlabs.modelId`	`eleven_v3`
`providers.mlx.modelId`	`mlx-community/Soprano-80M-bf16`
`providers.elevenlabs.apiKey`	-	Falls back to `ELEVENLABS_API_KEY` (or gateway shell profile if available).
`silenceTimeoutMs`	`700` ms macOS/Android, `900` ms iOS	Pause window before Talk sends the transcript.
`interruptOnSpeech`	`true`
`outputFormat`	`pcm_44100` macOS/iOS, `pcm_24000` Android	Set `mp3_*` to force MP3 streaming.
`consultThinkingLevel`	unset	Thinking level override for the agent run behind realtime `openclaw_agent_consult` calls.
`consultFastMode`	unset	Fast-mode override for realtime `openclaw_agent_consult` calls.
`realtime.provider`	-	`openai` for WebRTC, `google` for provider WebSocket, or a bridge-only provider through Gateway relay.
`realtime.providers.<id>`	-	Provider-owned realtime config. Browsers receive only ephemeral/constrained session credentials, never a standard API key.
`realtime.providers.openai.speakerVoice`	`alloy`	Built-in OpenAI Realtime voice id (the older `voice` key still works but is deprecated). Current `gpt-realtime-2.1` voices: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `marin`, `sage`, `shimmer`, `verse`; `marin` and `cedar` are recommended for best quality.
`realtime.transport`	-	`webrtc`: client-owned OpenAI WebRTC on iOS and in the browser. `provider-websocket`: browser-owned, stays on Gateway relay on iOS. `gateway-relay`: keeps provider audio on the Gateway; Android uses realtime only with this transport.
`realtime.brain`	-	`agent-consult` routes realtime tool calls through Gateway policy; `direct-tools` is legacy direct-tool compatibility; `none` is for transcription/external orchestration.
`realtime.consultRouting`	-	`provider-direct` preserves the provider's direct reply when it skips `openclaw_agent_consult`; `force-agent-consult` routes finalized user transcripts through OpenClaw instead.
`realtime.instructions`	-	Appends provider-facing system instructions to OpenClaw's built-in realtime prompt (voice style/tone); the default `openclaw_agent_consult` guidance stays.

{
  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: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

macOS UI

주요 항목:

Menu bar toggle: Talk
Config tab: Talk Mode group (voice id + interrupt toggle)
Overlay: the orb renders the universal talk waveform (shared with iOS, watchOS, and Android). Listening follows the live mic level, Speaking follows the actual TTS playback envelope, Thinking breathes softly. Click the orb to pause/resume, double-click to stop speaking, click X to exit Talk mode.

Android UI

lives in the Chat composer rather than a separate Voice tab.

주요 항목:

Android's main navigation is Home, Chat, and Settings. Voice input
Tap the composer microphone for on-device dictation. Long-press it to record
Dictation, voice-note recording, and Talk are mutually exclusive microphone
Realtime Talk prefers a connected Bluetooth Classic or BLE headset
Dictation and voice-note recording stop when the app leaves the foreground or
Talk Mode keeps running until toggled off or the node disconnects, using Android's microphone foreground-service type while active.
Android supports pcm_16000, pcm_22050, pcm_24000, and pcm_44100 output formats for low-latency AudioTrack streaming.

참고

주요 항목:

Requires Speech + Microphone permissions.
Native Talk uses the active Gateway session and only falls back to history polling when response events are unavailable.
The gateway resolves Talk playback through talk.speak using the active Talk provider. Android falls back to local system TTS only when that RPC is unavailable.
macOS local MLX playback uses the bundled openclaw-mlx-tts helper when present, or an executable on PATH. Set OPENCLAW_MLX_TTS_BIN to point at a custom helper binary during development.
Voice directive value ranges (ElevenLabs): stability, similarity, and style accept 0..1; speed accepts 0.5..2; latency_tier accepts 0..4.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/nodes/talk
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  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: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

Talk mode

핵심 요약

Talk mode: continuous speech conversations across local STT/TTS and realtime voice

한국어 가이드 범위: nodes/talk 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Behavior (macOS)
Voice directives in replies
Config (~/.openclaw/openclaw.json)
macOS UI
Android UI
참고
관련 문서

상세 내용

본문

Native Talk is a continuous loop: listen for speech, send the transcript to the model through the active session, wait for the response, then speak it via the configured Talk provider (talk.speak).

주요 항목:

Native macOS/iOS/Android Talk: native speech recognition, Gateway chat, and talk.speak TTS. Apple Speech recognition on macOS/iOS may use network services; Android behavior depends on the installed speech service. Nodes advertise the talk capability and declare which talk.* commands they support.
iOS Talk (realtime): client-owned WebRTC for OpenAI realtime configs that select webrtc transport or omit transport. Explicit gateway-relay, provider-websocket, and non-OpenAI realtime configs stay on the Gateway-owned relay; non-realtime configs use the native speech loop.
Browser Talk: talk.client.create for client-owned webrtc/provider-websocket sessions, or talk.session.create for Gateway-owned gateway-relay sessions. managed-room is reserved for Gateway handoff and walkie-talkie rooms.
Android Talk (realtime): opt in with talk.realtime.mode: "realtime" and talk.realtime.transport: "gateway-relay". Otherwise Android stays on native speech recognition, Gateway chat, and talk.speak.
Transcription-only clients: talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" }), then talk.session.appendAudio, talk.session.cancelTurn, and talk.session.close for captions/dictation without an assistant voice response. One-shot uploaded voice notes still use the media understanding audio path.

Behavior (macOS)

주요 항목:

Always-on overlay while Talk mode is enabled.
Listening → Thinking → Speaking phase transitions.
On a short pause (silence window), the current transcript is sent.
Replies are written to WebChat (same as typing).
Interrupt on speech (default on): if the user talks while the assistant is speaking, playback stops and the interruption timestamp is noted for the next prompt.

Voice directives in replies

The assistant can prefix a reply with a single JSON line to control voice:

주요 항목:

First non-empty line only; the JSON line is stripped before TTS playback.
Unknown keys are ignored.
once: true applies to the current reply only; without it, the voice becomes the new Talk mode default.

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

Config (~/.openclaw/openclaw.json)

Key	Default	Notes
`provider`	-	Active Talk TTS provider. Use `elevenlabs`, `mlx`, or `system` for macOS-local playback paths.
`providers.<id>.voiceId`	-	ElevenLabs falls back to `ELEVENLABS_VOICE_ID` / `SAG_VOICE_ID`, or the first available voice with an API key.
`speechLocale`	device default	BCP 47 locale for Android, iOS, and macOS native speech recognition. Apple Speech may use network services; Android also forwards the language component to realtime input transcription.
`providers.elevenlabs.modelId`	`eleven_v3`
`providers.mlx.modelId`	`mlx-community/Soprano-80M-bf16`
`providers.elevenlabs.apiKey`	-	Falls back to `ELEVENLABS_API_KEY` (or gateway shell profile if available).
`silenceTimeoutMs`	`700` ms macOS/Android, `900` ms iOS	Pause window before Talk sends the transcript.
`interruptOnSpeech`	`true`
`outputFormat`	`pcm_44100` macOS/iOS, `pcm_24000` Android	Set `mp3_*` to force MP3 streaming.
`consultThinkingLevel`	unset	Thinking level override for the agent run behind realtime `openclaw_agent_consult` calls.
`consultFastMode`	unset	Fast-mode override for realtime `openclaw_agent_consult` calls.
`realtime.provider`	-	`openai` for WebRTC, `google` for provider WebSocket, or a bridge-only provider through Gateway relay.
`realtime.providers.<id>`	-	Provider-owned realtime config. Browsers receive only ephemeral/constrained session credentials, never a standard API key.
`realtime.providers.openai.speakerVoice`	`alloy`	Built-in OpenAI Realtime voice id (the older `voice` key still works but is deprecated). Current `gpt-realtime-2.1` voices: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `marin`, `sage`, `shimmer`, `verse`; `marin` and `cedar` are recommended for best quality.
`realtime.transport`	-	`webrtc`: client-owned OpenAI WebRTC on iOS and in the browser. `provider-websocket`: browser-owned, stays on Gateway relay on iOS. `gateway-relay`: keeps provider audio on the Gateway; Android uses realtime only with this transport.
`realtime.brain`	-	`agent-consult` routes realtime tool calls through Gateway policy; `direct-tools` is legacy direct-tool compatibility; `none` is for transcription/external orchestration.
`realtime.consultRouting`	-	`provider-direct` preserves the provider's direct reply when it skips `openclaw_agent_consult`; `force-agent-consult` routes finalized user transcripts through OpenClaw instead.
`realtime.instructions`	-	Appends provider-facing system instructions to OpenClaw's built-in realtime prompt (voice style/tone); the default `openclaw_agent_consult` guidance stays.

{
  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: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

macOS UI

주요 항목:

Menu bar toggle: Talk
Config tab: Talk Mode group (voice id + interrupt toggle)
Overlay: the orb renders the universal talk waveform (shared with iOS, watchOS, and Android). Listening follows the live mic level, Speaking follows the actual TTS playback envelope, Thinking breathes softly. Click the orb to pause/resume, double-click to stop speaking, click X to exit Talk mode.

Android UI

lives in the Chat composer rather than a separate Voice tab.

주요 항목:

Android's main navigation is Home, Chat, and Settings. Voice input
Tap the composer microphone for on-device dictation. Long-press it to record
Dictation, voice-note recording, and Talk are mutually exclusive microphone
Realtime Talk prefers a connected Bluetooth Classic or BLE headset
Dictation and voice-note recording stop when the app leaves the foreground or
Talk Mode keeps running until toggled off or the node disconnects, using Android's microphone foreground-service type while active.
Android supports pcm_16000, pcm_22050, pcm_24000, and pcm_44100 output formats for low-latency AudioTrack streaming.

참고

주요 항목:

Requires Speech + Microphone permissions.
Native Talk uses the active Gateway session and only falls back to history polling when response events are unavailable.
The gateway resolves Talk playback through talk.speak using the active Talk provider. Android falls back to local system TTS only when that RPC is unavailable.
macOS local MLX playback uses the bundled openclaw-mlx-tts helper when present, or an executable on PATH. Set OPENCLAW_MLX_TTS_BIN to point at a custom helper binary during development.
Voice directive value ranges (ElevenLabs): stability, similarity, and style accept 0..1; speed accepts 0.5..2; latency_tier accepts 0..4.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/nodes/talk
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  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: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

Talk mode

핵심 요약

문서 구성

상세 내용

본문

Behavior (macOS)

Voice directives in replies

Config (~/.openclaw/openclaw.json)

macOS UI

Android UI

참고

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Talk mode

핵심 요약

문서 구성

상세 내용

본문

Behavior (macOS)

Voice directives in replies

Config (~/.openclaw/openclaw.json)

macOS UI

Android UI

참고

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드