このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。英語版

音声通知

ステータス: 現行対象範囲: AX Code TUI の効果音と読み上げアラート最終確認: 2026-09-12 所有者: AX Code runtime のメンテナー

TUI は、AX Code が注意を必要とするたびに、システムの音を鳴らすか、短い定型句を読み上げることができます。

権限の要求 — ツールが承認を待っています。
エージェントの質問 — エージェントが質問しました。
ターン完了 — 実行が終わりました（既定ではオフ）。
セッションエラー — ターンが失敗しました。

音声はターミナル通知と同じきっかけに乗ります（OSC 9 のデスクトップ通知、または OSC 9 が未対応のところではターミナルベル）。同じ notifications.enabled の切り替えで門がかかります。既定ではオフ で、有効にしても通知の他の部分は変わりません。

設定

notifications.sound を設定します。場所は tui.json です。

{
  "notifications": {
    "enabled": true,
    "sound": "chime",
    "events": {
      "permission": true,
      "question": true,
      "complete": false,
      "error": true
    }
  }
}

フィールド	値	既定	意味
`enabled`	真偽値	`true`	ターミナル通知と音声の主スイッチです。
`sound`	`"off"`、`"chime"`、`"speak"`	`"off"`	`chime` はシステムの音を鳴らします。`speak` は音声を合成します。
`voice`	文字列	`""`	プラットフォームの音声名（macOS では `say -v '?'`）。空は既定です。
`rate`	整数	`0`	対応しているときの話速（macOS は語/分、1–500）。0 は既定です。
`events.permission`	真偽値	`true`	権限要求で知らせます。
`events.question`	真偽値	`true`	エージェントの質問で知らせます。
`events.complete`	真偽値	`false`	ターン完了時に知らせます。
`events.error`	真偽値	`true`	セッションエラーで知らせます。

無効な値はフィールドごとに捨てられます。悪い sound の値は、他の設定に影響せず "off" へ戻ります。

プラットフォームのサポート

プラットフォーム	チャイム	読み上げ	要件
macOS	`afplay`（システムの音）	`say`	組み込みです。
Windows	`System.Media.SoundPlayer`	`System.Speech`	組み込みです（PowerShell）。
Linux	`paplay`、フォールバック `canberra-gtk-play`	`spd-say`、フォールバック `espeak-ng`	PulseAudio/`libcanberra` と、または `speech-dispatcher`/`espeak-ng` をインストールします。

利用可能性は実行時に探査されます。使えるバックエンドがないとき、音声の手順は黙ってスキップされ、ターミナル通知がフォールバックとして残ります。再生は直列化され（一度に 1 つの音、繰り返しはまとまる）、各イベントは多くても 1 回知らせ、インターフェースは再生を待ちません。ヘッドレス実行（ax-code run）は音声を決して鳴らしません。

何が読み上げられるか

読み上げが使う定型は 4 つだけです。Approval required: <tool>、Question: <first question>、Session idle: <session title>、AX Code error です。テキストは切り詰められ、制御文字が除かれます。ツール引数、ペイロードのファイルパス、モデル出力、エラーメッセージは決して読み上げられません。その限界の中では、共有空間でも安全です。

フックによる独自の音

完全な制御（自分の音声ファイル、異なるテキスト、追加のイベント）が必要なら、ライフサイクルフックを通じて任意のプレーヤーをつないでください。音声通知が無効でも動きます。AX_CODE_TRUST_PROJECT_CONFIG=1 でオプトインしたあと、.ax-code/hooks.json を作ります。

{
  "hooks": [
    { "event": "Stop", "command": "afplay /System/Library/Sounds/Glass.aiff" },
    { "event": "PreToolUse", "matcher": "bash|edit|write", "command": "say 'AX Code needs approval'" }
  ]
}

プラットフォームのプレーヤーを使います（macOS では afplay、Linux では paplay、Windows では PowerShell の [System.Media]）。フックコマンドはシェルの断片です。ライフサイクル経路を遅らせないよう、投げっぱなしにしてください。

外部通知器を作る

外部ツール（ステータスバー、モバイルプッシュ、デスクトップアプリ）は、サーバーのイベントストリームを購読し、permission.asked、question.asked、session.status、session.error に反応できます。HTTP と OpenAPI の互換性を参照してください。