Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

Akustische Hinweise

Status: Aktuell Geltungsbereich: Ton und gesprochene Hinweise der TUI von AX Code Zuletzt geprüft: 2026-09-12 Verantwortlich: Betreuende der Laufzeit von AX Code

Die TUI kann einen Systemton abspielen — oder eine kurze vorgegebene Wendung sprechen —, sobald AX Code Ihre Aufmerksamkeit braucht:

Anfrage einer Berechtigung — ein Werkzeug wartet auf Ihre Genehmigung.
Frage des Agenten — der Agent hat Ihnen eine Frage gestellt.
Runde abgeschlossen — der Lauf ist beendet (standardmäßig aus).
Fehler der Sitzung — die Runde ist fehlgeschlagen.

Der Ton folgt denselben Auslösern wie die Benachrichtigung des Terminals (Desktop-Benachrichtigung OSC 9 oder die Glocke des Terminals, wo OSC 9 nicht unterstützt wird) und hängt am selben Schalter notifications.enabled. Er ist standardmäßig aus. Das Einschalten ändert an den Benachrichtigungen sonst nichts.

Konfiguration

Setzen Sie notifications.sound in tui.json:

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

Feld	Werte	Voreinstellung	Bedeutung
`enabled`	boolean	`true`	Hauptschalter für Benachrichtigungen des Terminals und für Ton.
`sound`	`"off"`, `"chime"`, `"speak"`	`"off"`	`chime` spielt einen Systemton; `speak` erzeugt Sprache.
`voice`	string	`""`	Name der Stimme auf der Plattform (`say -v '?'` unter macOS); leer bedeutet Voreinstellung.
`rate`	integer	`0`	Sprechtempo, wo unterstützt (Wörter/min unter macOS, 1–500); 0 bedeutet Voreinstellung.
`events.permission`	boolean	`true`	Hinweis bei Anfragen einer Berechtigung.
`events.question`	boolean	`true`	Hinweis bei Fragen des Agenten.
`events.complete`	boolean	`false`	Hinweis, wenn eine Runde endet.
`events.error`	boolean	`true`	Hinweis bei Fehlern der Sitzung.

Ungültige Werte werden Feld für Feld verworfen: ein ungeeigneter Wert von sound fällt auf "off" zurück und lässt Ihre übrigen Einstellungen unberührt.

Unterstützung durch die Plattform

Plattform	Klingel	Sprache	Voraussetzung
macOS	`afplay` (Systemton)	`say`	Bereits enthalten.
Windows	`System.Media.SoundPlayer`	`System.Speech`	Bereits enthalten (PowerShell).
Linux	`paplay`, Rückfall `canberra-gtk-play`	`spd-say`, Rückfall `espeak-ng`	Installieren Sie PulseAudio/`libcanberra` und/oder `speech-dispatcher`/`espeak-ng`.

Die Verfügbarkeit wird zur Laufzeit geprüft. Ohne nutzbares Backend wird der Schritt für den Ton still übersprungen, und die Benachrichtigung des Terminals bleibt als Rückfall. Die Wiedergabe läuft nacheinander (jeweils ein Ton, Wiederholungen werden zusammengezogen), jedes Ereignis weist höchstens einmal hin, und die Oberfläche wartet nie auf die Wiedergabe. Läufe ohne Oberfläche (ax-code run) spielen nie Ton ab.

Was gesprochen wird

Die Sprache nutzt nur vier feste Vorlagen: Approval required: <tool>, Question: <first question>, Session idle: <session title> und AX Code error. Text wird gekürzt und von Steuerzeichen befreit. Argumente von Werkzeugen, Dateipfade aus Nutzdaten, Ausgabe des Modells und Fehlermeldungen werden nie gesprochen. Innerhalb dieser Grenzen bleibt das für gemeinsame Räume geeignet.

Eigene Klänge über Hooks

Für die volle Steuerung (Ihre eigene Klangdatei, anderer Text, weitere Ereignisse) binden Sie einen beliebigen Player über Hooks des Lebenszyklus an. Das funktioniert auch, wenn die akustischen Hinweise aus sind. Nach dem Einschalten mit AX_CODE_TRUST_PROJECT_CONFIG=1 legen Sie .ax-code/hooks.json an:

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

Nutzen Sie den Player Ihrer Plattform (afplay unter macOS, paplay unter Linux, PowerShell [System.Media] unter Windows). Befehle der Hooks sind Ausschnitte der Shell. Halten Sie sie so, dass sie nicht auf Abschluss warten, damit sie den Weg des Lebenszyklus nicht verzögern.

Einen externen Melder bauen

Externe Werkzeuge (Statusleisten, Push auf das Mobilgerät, eine Anwendung auf dem Desktop) können den Ereignisstrom des Servers abonnieren und auf permission.asked, question.asked, session.status und session.error reagieren. Siehe Kompatibilität von HTTP und OpenAPI.