Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Notificaciones de audio

Estado: Vigente Alcance: sonido y avisos hablados de la TUI de AX Code Última revisión: 2026-09-12 Responsable: mantenedores del entorno de ejecución de AX Code

La TUI puede reproducir un sonido del sistema — o pronunciar una frase corta con plantilla — siempre que AX Code necesite tu atención:

Solicitud de permiso: una herramienta espera tu aprobación.
Pregunta del agente: el agente te hizo una pregunta.
Turno completado: la ejecución terminó (desactivado de forma predeterminada).
Error de sesión: el turno falló.

El audio usa los mismos disparadores que la notificación de la terminal (notificación de escritorio OSC 9, o la campana de la terminal donde OSC 9 no se admite) y está condicionado por el mismo interruptor notifications.enabled. Está desactivado de forma predeterminada; activarlo no cambia nada más de las notificaciones.

Configuración

Define notifications.sound en tui.json:

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

Campo	Valores	Predeterminado	Significado
`enabled`	booleano	`true`	Compuerta principal de las notificaciones de terminal y del audio.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` reproduce un sonido del sistema; `speak` sintetiza la voz.
`voice`	cadena	`""`	Nombre de la voz de la plataforma (`say -v '?'` en macOS); vacío = predeterminado.
`rate`	entero	`0`	Velocidad del habla donde se admite (palabras/min en macOS, 1–500); 0 = predeterminado.
`events.permission`	booleano	`true`	Aviso en las solicitudes de permiso.
`events.question`	booleano	`true`	Aviso en las preguntas del agente.
`events.complete`	booleano	`false`	Aviso cuando un turno se completa.
`events.error`	booleano	`true`	Aviso en los errores de sesión.

Los valores no válidos se descartan campo a campo: un valor incorrecto de sound vuelve a "off" sin afectar al resto de tus ajustes.

Soporte de plataformas

Plataforma	Timbre	Voz	Requisito
macOS	`afplay` (sonido del sistema)	`say`	Integrado.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Integrado (PowerShell).
Linux	`paplay`, reserva `canberra-gtk-play`	`spd-say`, reserva `espeak-ng`	Instala PulseAudio/`libcanberra` y/o `speech-dispatcher`/`espeak-ng`.

La disponibilidad se sondea en el entorno de ejecución. Sin un backend utilizable, el paso de audio se omite en silencio y la notificación de la terminal permanece como reserva. La reproducción se serializa (un sonido a la vez; las repeticiones se fusionan), cada evento avisa como máximo una vez y la interfaz nunca espera a la reproducción. Las ejecuciones sin interfaz (ax-code run) nunca reproducen audio.

Qué se pronuncia

La voz usa solo cuatro plantillas fijas: Approval required: <tool>, Question: <first question>, Session idle: <session title> y AX Code error. El texto se trunca y se le quitan los caracteres de control. Los argumentos de herramientas, las rutas de archivo de las cargas, la salida del modelo y los mensajes de error nunca se pronuncian: es seguro para espacios compartidos dentro de esos límites.

Sonidos personalizados mediante hooks

Para un control total (tu propio archivo de sonido, un texto distinto, eventos extra), conecta cualquier reproductor mediante los hooks de ciclo de vida: esto también funciona con las notificaciones de audio desactivadas. Después de optar por ello con AX_CODE_TRUST_PROJECT_CONFIG=1, crea .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'" }
  ]
}

Usa el reproductor de tu plataforma (afplay en macOS, paplay en Linux, PowerShell [System.Media] en Windows). Los comandos de hook son fragmentos de shell: mantenlos de disparar y olvidar para que no puedan retrasar el camino del ciclo de vida.

Crear un notificador externo

Las herramientas externas (barras de estado, avisos al móvil, una aplicación de escritorio) pueden suscribirse al flujo de eventos del servidor y reaccionar a permission.asked, question.asked, session.status y session.error. Consulta Compatibilidad HTTP y OpenAPI.