Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Звуковые уведомления

Статус: актуально Область: звук и голосовые оповещения TUI AX Code Последняя проверка: 2026-09-12 Владелец: сопровождающие среды выполнения AX Code

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`	строка	`""`	Имя голоса платформы (`say -v '?'` в macOS); пусто = по умолчанию.
`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`.

Доступность проверяется во время выполнения. Если пригодного бэкенда нет, шаг звука молча пропускается, а уведомление терминала остаётся запасным вариантом. Воспроизведение идёт по очереди (один звук за раз, повторы сливаются), каждое событие оповещает не более одного раза, и интерфейс никогда не ждёт окончания воспроизведения. Безголовые запуски (ax-code run) звук не воспроизводят.

Что произносится

Речь использует только четыре фиксированных шаблона: 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'" }
  ]
}

Используйте проигрыватель своей платформы (afplay в macOS, paplay в Linux, PowerShell [System.Media] в Windows). Команды хуков — фрагменты оболочки: запускайте их и не ждите завершения, чтобы они не задерживали путь жизненного цикла.

Внешний уведомитель

Внешние инструменты (строки состояния, мобильные push-уведомления, приложение рабочего стола) могут подписаться на поток событий сервера и реагировать на permission.asked, question.asked, session.status и session.error — см. Совместимость HTTP и OpenAPI.