> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 音声ウェイク

# 音声ウェイク & プッシュトゥトーク

## モード

* **ウェイクワードモード**（デフォルト）：常時オンの音声認識がトリガートークン（`swabbleTriggerWords`）を待機します。一致するとキャプチャを開始し、部分テキスト付きのオーバーレイを表示し、無音後に自動送信します。 一致するとキャプチャが開始され、部分的なテキストでオーバーレイが表示され、沈黙後に自動送信されます。 一致するとキャプチャが開始され、部分的なテキストでオーバーレイが表示され、沈黙後に自動送信されます。
* **プッシュトゥトーク(右オプションホールド)**: 右のOptionキーを押すとすぐにキャプチャできます。トリガーは必要ありません。 オーバーレイは、保留中に表示されます。リリースは、短い遅延の後に確定および転送されるので、テキストを調整できます。 オーバーレイは、保留中に表示されます。リリースは、短い遅延の後に確定および転送されるので、テキストを調整できます。

## ランタイム動作（ウェイクワード）

* 音声認識は `VoiceWakeRuntime` に常駐します。
* トリガーはwake単語と次の単語（〜0.55秒間隔）の間に**意味のある一時停止**がある場合にのみ発生します。 オーバーレイ/チャイムは、コマンドが開始される前でもポーズで開始できます。 オーバーレイ/チャイムは、コマンドが開始される前でもポーズで開始できます。
* 無音ウィンドウ：発話が継続している場合は 2.0 秒、トリガーのみが聞こえた場合は 5.0 秒です。
* ハードストップ：暴走セッションを防ぐため 120 秒。
* セッション間のデバウンス：350 ms。
* オーバーレイは、確定／揮発の色分けを用いて `VoiceWakeOverlayController` 経由で駆動されます。
* 送信後、認識器は次のトリガーを待つためにクリーンに再起動します。

## ライフサイクル不変条件

* 音声ウェイクが有効で権限が付与されている場合、ウェイクワード認識は（明示的なプッシュトゥトークのキャプチャ中を除き）常に待機している必要があります。
* オーバーレイの表示状態（X ボタンによる手動の閉鎖を含む）は、認識の再開を妨げてはなりません。

## 固着オーバーレイの障害モード（以前）

以前は、オーバーレイが表示されたまま固着し、手動で閉じた場合、ランタイムの再起動試行がオーバーレイの可視性によってブロックされ、その後の再起動がスケジュールされないため、音声ウェイクが「停止した」ように見えることがありました。

強化対応：

* ウェイクランタイムの再起動は、オーバーレイの可視性によってブロックされなくなりました。
* オーバーレイの閉鎖完了は `VoiceSessionCoordinator` 経由で `VoiceWakeRuntime.refresh(...)` をトリガーするため、X による手動閉鎖でも必ずリスニングが再開されます。

## プッシュツートークの詳細

* ホットキー検出は、**右 Option**（`keyCode 61` + `.option`）に対するグローバルな `.flagsChanged` モニターを使用します。イベントは監視のみで、消費（スワロー）はしません。 私たちは、イベント(飲み込まない)だけを観察します。 私たちは、イベント(飲み込まない)だけを観察します。
* キャプチャパイプラインは `VoicePushToTalk` にあり、音声認識を即時開始し、部分結果をオーバーレイへストリーミングし、リリース時に `VoiceWakeForwarder` を呼び出します。
* プッシュトゥトーク開始時は、音声タップの競合を避けるためウェイクワードランタイムを一時停止します。リリース後に自動で再開します。
* 権限：マイク + 音声認識が必要です。イベントの検知にはアクセシビリティ／入力監視の承認が必要です。
* 外付けキーボード：右 Option が期待どおりに露出しない場合があります—取りこぼしの報告がある場合は代替ショートカットを提示してください。

## ユーザー向け設定

* **音声ウェイク** トグル：ウェイクワードランタイムを有効化します。
* **Cmd+Fnを長押し**: プッシュトゥトークモニタを有効にします。 macOS 26以降では無効になっています。
* 言語およびマイクのピッカー、ライブレベルメーター、トリガーワード表、テスター（ローカルのみ；転送しません）。
* マイクピッカーは、デバイスが切断されても最後の選択を保持し、切断のヒントを表示し、復帰するまで一時的にシステムデフォルトへフォールバックします。
* **サウンド**：トリガー検出時および送信時のチャイム。デフォルトは macOS の「Glass」システムサウンドです。各イベントごとに、任意の `NSSound` でロード可能なファイル（例：MP3/WAV/AIFF）を選択するか、**サウンドなし** を選べます。 イベントごとに任意の `NSSound`-loadable ファイル (例: MP3/WAV/AIFF) を選択するか、**No Sound** を選択します。 イベントごとに任意の `NSSound`-loadable ファイル (例: MP3/WAV/AIFF) を選択するか、**No Sound** を選択します。

## 転送動作

* 音声ウェイクが有効な場合、文字起こしはアクティブなゲートウェイ／エージェント（mac アプリ全体で使用されるローカル／リモートの同一モード）に転送されます。
* 返信は **最後に使用したメインプロバイダー**（WhatsApp/Telegram/Discord/WebChat）に配信されます。配信に失敗した場合、エラーはログに記録され、実行は WebChat／セッションログから引き続き確認できます。 配信に失敗した場合、エラーは記録され、実行は WebChat/セッション ログ経由で表示されます。

## 転送ペイロード

* 送信前に `VoiceWakeForwarder.prefixedTranscript(_:)` がマシンヒントを前置します。ウェイクワードとプッシュトゥトークの両パスで共有されます。 ウェイクワードとプッシュトゥトークのパス間で共有されました。 ウェイクワードとプッシュトゥトークのパス間で共有されました。

## クイック検証

* プッシュトゥトークをオンにし、Cmd+Fn を押し続けて話し、離します：オーバーレイに部分結果が表示され、その後送信されるはずです。
* 押下中、メニューバーの耳は拡大されたまま（`triggerVoiceEars(ttl:nil)` を使用）で、リリース後に元に戻ります。