音声オーバーレイのライフサイクル（macOS）

対象読者: macOS アプリのコントリビューター。目的: ウェイクワードとプッシュトゥトークが重なったときも、音声オーバーレイを予測可能な状態に保つこと。

動作

• ウェイクワードによってオーバーレイがすでに表示されている状態でユーザーがホットキーを押すと、ホットキーセッションはテキストをリセットせず、既存のテキストを引き継ぎます。ホットキーを押している間、オーバーレイは表示されたままになります。キーを離したとき: 前後の空白を除去したテキストがあれば送信し、なければ閉じます。
• ウェイクワードのみの場合は、従来どおり無音を検出すると自動送信されます。プッシュトゥトークの場合は、キーを離すと即座に送信されます。

実装

• VoiceSessionCoordinator（apps/macos/Sources/OpenClaw/VoiceSessionCoordinator.swift）は、アクティブな音声セッションを一元的に管理します。これは actor ではなく、@MainActor @Observable のシングルトンです。API: startSession、updatePartial、finalize、sendNow、dismiss、updateLevel、snapshot。各セッションは UUID トークンを保持し、古いトークンまたは一致しないトークンを使用した呼び出しは破棄されます。
• VoiceWakeOverlayController（VoiceWakeOverlayController+Session.swift）はオーバーレイを描画し、ユーザー操作（requestSend、dismiss）をセッショントークン経由でコーディネーターに転送します。セッション状態自体を保持することはありません。
• プッシュトゥトーク（VoicePushToTalk.begin()）は、表示中のオーバーレイにあるテキストを（VoiceSessionCoordinator.shared.snapshot() を介して）adoptedPrefix として引き継ぎます。そのため、ウェイクオーバーレイの表示中にホットキーを押してもテキストが保持され、新しい音声認識結果が追加されます。キーを離すと、最終的な文字起こしを最大 1.5 秒待機してから、現在のテキストにフォールバックします。
• dismiss 時に、オーバーレイは VoiceSessionCoordinator.overlayDidDismiss を呼び出します。これにより VoiceWakeRuntime.refresh(state:) がトリガーされるため、X ボタンによる手動終了、空テキストによる終了、送信後の終了のいずれの場合も、ウェイクワードの待ち受けが再開されます。
• 統一された送信経路: 前後の空白を除去したテキストが空なら閉じます。それ以外の場合、sendNow が送信チャイムを一度だけ再生し、VoiceWakeForwarder を介して転送してから閉じます。

ログ記録

音声サブシステムは ai.openclaw です。各コンポーネントはそれぞれ独自のカテゴリでログを記録します。

デバッグチェックリスト

• オーバーレイが消えない問題を再現しながらログをストリーミングします。

  sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact

• アクティブなセッショントークンが 1 つだけであることを確認します。古いコールバックはコーディネーターによって破棄されます。

• プッシュトゥトークのキーを離したときに、アクティブなトークンを指定して必ず end() が呼び出されることを確認します。テキストが空の場合は、チャイムの再生や送信を行わずに閉じることが期待されます。

関連項目

• macOS アプリ
• 音声ウェイク（macOS）
• トークモード