Claude Code Hook 通知与提示音配置#

在 Windows 上，Claude Code 可以通过原生 Hook 在需要权限确认、完成一轮回答或执行失败时显示系统托盘通知，并播放提示音。本次实测的最终方案不依赖第三方通知工具，也不需要更换已有 Hook 配置；只需把 notify.ps1 的播放实现改为同步加载并播放 Windows 自带的 WAV 文件。

最终结论#

保留原有的 %USERPROFILE%\.claude\settings.json Hook 配置，只替换 %USERPROFILE%\.claude\hooks\notify.ps1：

使用 System.Windows.Forms.NotifyIcon 显示托盘气泡通知。
使用 System.Media.SoundPlayer 播放 %WINDIR%\Media 下的 WAV 文件。
播放前显式调用 Load()，再调用 PlaySync()，避免异步播放时脚本过早退出。
Alarm02.wav 或 Alarm03.wav 不存在时，回退到 Alarm01.wav。
声音播放失败时写入脚本目录下的 notify-error.log，不再使用空的 catch 隐藏异常。

事件与声音映射#

Claude Code 事件	Hook 参数	默认声音	用途
`Notification`，匹配 `permission_prompt`	`permission`	`Alarm01.wav`	等待用户批准工具操作
`Stop`	`done`	`Alarm03.wav`	主 Agent 完成本轮响应
`StopFailure`	`error`	`Alarm02.wav`	本轮因 API 或其他错误结束

Stop 表示本轮响应结束，不等同于长期任务的所有工作都已完成；用户主动中断时也不会触发 Stop。StopFailure 用于 API 错误等异常结束场景。

如果当前操作已经被允许、处于自动批准模式，或本身不需要权限，permission_prompt 不会触发；这不是 Hook 失效，完成通知仍可正常触发。

可直接使用的 `notify.ps1`#

文件位置：

1
%USERPROFILE%\.claude\hooks\notify.ps1

1
param(
2
    [ValidateSet("permission", "done", "error")]
3
    [string]$EventType = "done"
4
)
5

6
$ErrorActionPreference = "Stop"
7

8
Add-Type -AssemblyName System.Windows.Forms
9
Add-Type -AssemblyName System.Drawing
10

11
switch ($EventType) {
12
    "permission" {
13
        $title = "Claude Code 需要确认"
14
        $message = "Claude Code 正在等待你批准操作。"
15
        $tipIcon = [System.Windows.Forms.ToolTipIcon]::Warning
16
        $trayIcon = [System.Drawing.SystemIcons]::Warning
17
        $soundPath = "$env:WINDIR\Media\Alarm01.wav"
18
    }
19

20
    "error" {
21
        $title = "Claude Code 执行失败"
22
        $message = "本轮响应因错误而结束。"
23
        $tipIcon = [System.Windows.Forms.ToolTipIcon]::Error
24
        $trayIcon = [System.Drawing.SystemIcons]::Error
25
        $soundPath = "$env:WINDIR\Media\Alarm02.wav"
26
    }
27

28
    default {
29
        $title = "Claude Code 已完成"
30
        $message = "本轮回答已经完成，可以回来查看了。"
31
        $tipIcon = [System.Windows.Forms.ToolTipIcon]::Info
32
        $trayIcon = [System.Drawing.SystemIcons]::Information
33
        $soundPath = "$env:WINDIR\Media\Alarm03.wav"
34
    }
35
}
36

37
# 某些 Windows 安装没有 Alarm02.wav 或 Alarm03.wav，统一回退到 Alarm01.wav。
38
if (-not (Test-Path -LiteralPath $soundPath)) {
39
    $soundPath = "$env:WINDIR\Media\Alarm01.wav"
40
}
41

42
$notification = $null
43

44
try {
45
    $notification = New-Object System.Windows.Forms.NotifyIcon
46
    $notification.Icon = $trayIcon
47
    $notification.BalloonTipIcon = $tipIcon
48
    $notification.BalloonTipTitle = $title
49
    $notification.BalloonTipText = $message
50
    $notification.Visible = $true
51

52
    $notification.ShowBalloonTip(6000)
53

54
    $player = New-Object System.Media.SoundPlayer $soundPath
55
    $player.Load()
56
    $player.PlaySync()
57

58
    # 保持进程短暂存活，确保气泡通知有时间显示。
59
    Start-Sleep -Seconds 5
60
}
61
catch {
62
    $logPath = Join-Path $PSScriptRoot "notify-error.log"
63

64
    "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')`r`n$($_ | Out-String)" |
65
        Add-Content -Path $logPath -Encoding UTF8
66
}
67
finally {
68
    if ($null -ne $notification) {
69
        $notification.Dispose()
70
    }
71
}

Hook 配置#

已经有可用 Hook 时#

不需要修改 settings.json。只要现有命令已经调用 notify.ps1，并把三种事件分别传入 permission、done、error 即可。保留：

1
"shell": "powershell",
2
"async": true

其中 async: true 可以避免通知脚本等待声音播放时阻塞 Claude Code。

在 Windows 上，shell: "powershell" 由 Claude Code 负责选择 PowerShell 运行时，并在 PowerShell 7 不可用时回退到 Windows PowerShell 5.1。除非兼容性测试证明有必要，否则不需要在每个 Hook 命令中硬编码 powershell.exe 的完整路径。

从零配置时的最小示例#

如果尚未配置 Hook，可将下面内容合并进 %USERPROFILE%\.claude\settings.json 的顶层 hooks 对象。已有 env、插件或其他配置时，只添加对应事件，不要覆盖整个文件。

1
{
2
  "hooks": {
3
    "Notification": [
4
      {
5
        "matcher": "permission_prompt",
6
        "hooks": [
7
          {
8
            "type": "command",
9
            "shell": "powershell",
10
            "command": "& \"$env:USERPROFILE/.claude/hooks/notify.ps1\" -EventType permission",
11
            "async": true
12
          }
13
        ]
14
      }
15
    ],
16
    "Stop": [
17
      {
18
        "hooks": [
19
          {
20
            "type": "command",
21
            "shell": "powershell",
22
            "command": "& \"$env:USERPROFILE/.claude/hooks/notify.ps1\" -EventType done",
23
            "async": true
24
          }
25
        ]
26
      }
27
    ],
28
    "StopFailure": [
29
      {
30
        "hooks": [
31
          {
32
            "type": "command",
33
            "shell": "powershell",
34
            "command": "& \"$env:USERPROFILE/.claude/hooks/notify.ps1\" -EventType error",
35
            "async": true
36
          }
37
        ]
38
      }
39
    ]
40
  }
41
}

安装与验证#

先备份当前可用脚本，再覆盖内容：

1
Copy-Item `
2
  "$env:USERPROFILE\.claude\hooks\notify.ps1" `
3
  "$env:USERPROFILE\.claude\hooks\notify-working.ps1"

依次手动测试三种事件：

1
& "$env:USERPROFILE\.claude\hooks\notify.ps1" -EventType permission
2
& "$env:USERPROFILE\.claude\hooks\notify.ps1" -EventType done
3
& "$env:USERPROFILE\.claude\hooks\notify.ps1" -EventType error

检查 WAV 文件是否存在：

1
Test-Path "$env:WINDIR\Media\Alarm01.wav"
2
Get-ChildItem "$env:WINDIR\Media" -Filter "*.wav" |
3
    Select-Object -ExpandProperty FullName

检查 settings.json 是否仍是合法 JSON：

1
Get-Content "$env:USERPROFILE\.claude\settings.json" -Raw |
2
    ConvertFrom-Json |
3
    Out-Null
4

5
Write-Host "settings.json 格式正确"

完全退出并重新启动 Claude Code，然后运行 /hooks 检查 Notification、Stop 和 StopFailure 是否已注册。

无声音时的排查顺序#

先用默认播放器确认 Windows 音频输出设备、主音量和 WAV 文件本身正常。

再单独测试同步播放：

1
$player = New-Object System.Media.SoundPlayer "$env:WINDIR\Media\Alarm01.wav"
2
$player.Load()
3
$player.PlaySync()

如果当前 PowerShell 版本测试仍无声，可只用 Windows PowerShell 5.1 做兼容性验证，不必先修改 Hook：

1
& "$env:WINDIR\System32\WindowsPowerShell\v1.0\powershell.exe" `
2
  -NoProfile `
3
  -Command '$p = New-Object System.Media.SoundPlayer "$env:WINDIR\Media\Alarm01.wav"; $p.Load(); $p.PlaySync()'

若直接播放成功但 Hook 无声，查看脚本目录下的 notify-error.log，并确认 Claude Code 使用的 Hook 命令确实指向当前 notify.ps1。
检查 Windows 音量混合器中的系统声音、PowerShell 或终端应用是否被单独静音，或输出到了错误设备。

如果提示禁止运行脚本，只对当前用户启用本地脚本即可：

1
Set-ExecutionPolicy `
2
  -Scope CurrentUser `
3
  -ExecutionPolicy RemoteSigned

不需要为了运行这个本地脚本而使用 ExecutionPolicy Bypass。

本次排障中不需要保留的方案#

不需要安装 Code-Notify 或其他第三方通知模块。
不需要把 WAV 文件关联到默认播放器作为 Hook 的播放机制。
不需要使用 Windows Media Player COM 组件或 winmm.dll 的替代实现。
不要为了绕过安全软件而信任远程下载后立即执行的 PowerShell 安装脚本。

本方案依赖 Windows 自带的 Forms、Drawing 和 SoundPlayer，不产生网络请求，也不需要提交本机的 .claude 配置、日志或声音文件。

参考#

Claude Code Hooks 官方文档

音乐

音乐

Claude Code Hook 通知与提示音配置#

最终结论#

事件与声音映射#

可直接使用的 `notify.ps1`#

Hook 配置#

已经有可用 Hook 时#

从零配置时的最小示例#

安装与验证#

无声音时的排查顺序#

本次排障中不需要保留的方案#

参考#

文章分享

音乐

Claude Code Hook 通知与提示音配置

Claude Code Hook 通知与提示音配置#

最终结论#

事件与声音映射#

可直接使用的 notify.ps1#

Hook 配置#

已经有可用 Hook 时#

从零配置时的最小示例#

安装与验证#

无声音时的排查顺序#

本次排障中不需要保留的方案#

参考#

文章分享

可直接使用的 `notify.ps1`#