本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。英文原文

音频通知

状态：当前范围：AX Code TUI 的声音与语音提醒最近审阅：2026-09-12 负责人：AX Code 运行时维护者

每当 AX Code 需要你注意时，TUI 可以播放系统声音 — 或说出一句简短的模板短语：

权限请求 — 某个工具正在等待你的批准。
代理提问 — 代理向你提了一个问题。
回合完成 — 运行已结束（默认关闭）。
会话错误 — 回合失败了。

音频与终端通知使用相同的触发器（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`。

可用性在运行时探测。没有可用后端时，音频步骤会静默跳过，终端通知仍然作为回退。播放是串行的（一次一个声音，重复会合并），每个事件最多提醒一次，界面从不会等待播放。无头运行（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'" }
  ]
}

使用你平台的播放器（macOS 上的 afplay，Linux 上的 paplay，Windows 上的 PowerShell [System.Media]）。钩子命令是 shell 片段 — 让它们即发即弃，以免拖延生命周期路径。

构建外部通知器

外部工具（状态栏、移动推送、桌面应用）可以订阅服务器的事件流，并对 permission.asked、question.asked、session.status 和 session.error 作出反应 — 见 HTTP 与 OpenAPI 兼容性。