为什么要添加提示音？

使用 Claude Code 时，你可能遇到过这些场景：

• 🔐 需要授权确认：Claude 等待你批准某个操作，但你没注意到
• ✅ 任务完成：长时间运行的任务完成了，但你还在摸鱼
• ⌨️ 等待输入：Claude 需要你提供更多信息，但你没看到提示

通过配置 Hooks（钩子） 系统，你可以为这些场景添加声音提示，让 Claude Code 在关键时刻发出提醒，不再错过任何重要信息！

✨ 提示音场景

Claude Code 支持在以下三个关键场景添加提示音：

场景	Hook 事件	触发时机
要求授权	Notification	Claude 需要你的权限来使用工具时
任务完成	Stop	主 Claude 完成响应时
等待输入	Notification	提示输入空闲超过 60 秒时

📦 配置文件位置

Hooks 配置文件按优先级排序（从高到低）：

配置文件说明

• .claude/settings.local.json - 项目本地配置（不提交到 Git，仅当前项目）
• .claude/settings.json - 项目配置（提交到 Git，团队共享）
• ~/.claude/settings.json - 用户全局配置（所有项目生效）

推荐做法：将提示音配置放在 ~/.claude/settings.json，这样所有项目都能使用！

🎵 准备提示音文件

在配置之前，首先需要准备提示音文件（无论你选择哪种配置方法，都需要这一步）：

提示音选择建议

• 授权提醒：短促、明显的提示音（如"叮"声）
• 任务完成：愉悦、令人满意的音效（如"完成"音）
• 等待输入：持续或周期性的提醒音

你可以从以下资源获取提示音：

• 系统音效库：macOS / Windows / Linux 自带音效
• 免费音效网站：Freesound、Zapsplat
• 自制音效：使用在线工具生成

将音效文件放在固定位置，例如：

# macOS/Linux
~/.claude/sounds/

# Windows
%USERPROFILE%\.claude\sounds\

音频文件格式建议

• 使用轻量级格式：MP3、OGG
• 音频长度：1-3 秒
• 避免使用过大的 WAV 文件

⚡ 方法一：直接在 Claude Code 中配置（推荐）

官方提供了交互式 /hooks 命令，让你可以在对话中直接配置提示音，无需手动编辑任何配置文件！

使用步骤

1. 打开 Hooks 配置界面

在 Claude Code 对话中直接输入：

/hooks

2. 选择配置存储位置

系统会提示你选择配置保存位置：

• User - 保存到 ~/.claude/settings.json（全局生效，推荐）
• Project - 保存到 .claude/settings.json（仅当前项目）

提示

选择 User 可以让所有项目都使用提示音功能！

3. 添加 Hook 事件

选择要配置的 Hook 事件类型：

• Notification - 用于权限请求和等待输入提示
• Stop - 用于任务完成提示

4. 输入播放命令

根据你的操作系统输入相应的播放命令：

macOS：

afplay ~/.claude/sounds/notification.mp3

Linux：

aplay ~/.claude/sounds/notification.mp3

Windows：

powershell -c (New-Object Media.SoundPlayer "$env:USERPROFILE\.claude\sounds\notification.wav").PlaySync()

5. 设置超时时间（可选）

建议设置为 3-5 秒，避免命令卡死：

timeout: 5

6. 保存配置

完成配置后，Claude Code 会自动保存到配置文件中。

验证配置

配置完成后，在 Claude Code 中运行：

/hooks

查看已注册的 Hook 列表，确认提示音 Hook 已成功添加。

优势

• ✅ 简单直观：交互式界面，无需了解 JSON 语法
• ✅ 自动保存：配置自动写入文件，无需手动操作
• ✅ 即时生效：保存后立即生效，无需重启
• ✅ 安全可靠：官方推荐方式，不易出错

📝 方法二：手动编辑配置文件（高级用户）

如果你更喜欢手动控制，或者需要批量配置多个 Hook，可以手动编辑配置文件。

配置步骤

1. 编辑配置文件

# 编辑用户全局配置
nano ~/.claude/settings.json
# 或者使用你喜欢的编辑器
code ~/.claude/settings.json

2. 添加 Hooks 配置

在 settings.json 中添加以下内容：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/notification.mp3",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/complete.mp3",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. 保存并重启 Claude Code

保存文件后，重启 Claude Code 使配置生效。

根据你的操作系统，选择以下相应的配置：

macOS 配置

macOS 完整配置示例

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/notification.mp3"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/complete.mp3"
          }
        ]
      }
    ]
  }
}

Linux 配置

Linux 完整配置示例

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "aplay ~/.claude/sounds/notification.mp3",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "aplay ~/.claude/sounds/complete.mp3",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Windows 配置

Windows 完整配置示例

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c (New-Object Media.SoundPlayer \"$env:USERPROFILE\\.claude\\sounds\\notification.wav\").PlaySync()",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c (New-Object Media.SoundPlayer \"$env:USERPROFILE\\.claude\\sounds\\complete.wav\").PlaySync()",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

跨平台配置（推荐）

如果你使用的是跨平台的音频播放工具（如 ffplay），可以统一配置：

跨平台配置示例

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "ffplay -nodisp -autoexit ~/.claude/sounds/notification.mp3 2>/dev/null",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "ffplay -nodisp -autoexit ~/.claude/sounds/complete.mp3 2>/dev/null",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

🎯 三大场景详解

场景 1：要求授权（Notification Hook）

当 Claude 需要你的权限来使用工具时，会触发 Notification 事件。

典型情况

• 执行 Shell 命令（Bash 工具）
• 写入文件（Write 工具）
• 访问网络（WebSearch/WebFetch）
• 读取敏感文件

提示音建议：短促、明显，能快速吸引注意力

场景 2：任务完成（Stop Hook）

当主 Claude Code 完成响应时，触发 Stop 事件。

典型情况

• 代码生成完成
• 文件修改完成
• 任务执行成功
• 分析报告完成

提示音建议：愉悦、令人满意，传达"完成"的感觉

场景 3：等待输入（Notification Hook）

当提示输入空闲超过 60 秒时，触发 Notification 事件。

典型情况

• Claude 需要更多上下文信息
• 需要你确认某个选择
• 等待你提供必要的参数

提示音建议：持续或周期性，提醒你回来继续

🎨 高级配置

区分不同通知类型

根据官方文档，Notification hook 不使用 matcher，你可以省略匹配器字段。Notification 输入 JSON 格式如下：

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude 需要您的权限来使用 Bash"
}

注意

官方文档中 Notification hook 的输入只有 message 字段，没有 notification_type 字段！

由于官方没有提供通知类型字段，你需要通过 message 文本内容来区分不同场景：

#!/bin/bash
# ~/.claude/hooks/play-sound.sh

input=$(cat)
message=$(echo "$input" | jq -r '.message // empty')

# 调试：记录通知内容（可选）
echo "$(date): $message" >> ~/.claude/hooks/debug.log

# 根据 message 文本内容匹配不同的通知类型
if [[ "$message" == *"权限"* ]] || [[ "$message" == *"permission"* ]]; then
    # 权限请求提示音 - Claude 需要你的权限来使用工具
    afplay ~/.claude/sounds/permission.mp3
elif [[ "$message" == *"等待"* ]] || [[ "$message" == *"waiting"* ]] || [[ "$message" == *"输入"* ]]; then
    # 空闲提示音 - Claude 等待你的输入
    afplay ~/.claude/sounds/idle.mp3
else
    # 默认提示音 - 其他通知
    afplay ~/.claude/sounds/default.mp3
fi

Notification 触发场景

根据官方文档，Notification 在以下情况触发：

1. 权限请求：Claude 需要你的权限来使用工具

   • 示例消息："Claude 需要您的权限来使用 Bash"

2. 空闲提示：提示输入已空闲至少 60 秒

   • 示例消息："Claude 正在等待您的输入"

然后在配置中使用（省略 matcher 字段）：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/play-sound.sh"
          }
        ]
      }
    ]
  }
}

添加视觉提示

除了声音，你还可以添加系统通知：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay ~/.claude/sounds/complete.mp3 && osascript -e 'display notification \"Claude Code 任务已完成\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

使用文本转语音（TTS）播放自定义提示

macOS 自带 say 命令，可以将文本转换为语音并朗读。结合 afplay，你可以实现更灵活的语音提示：

重要

根据官方文档，Notification hook 的输入中没有 notification_type 字段。以下脚本通过 message 文本内容来区分不同场景。

方法一：直接朗读文本（实时）

#!/bin/bash
# ~/.claude/hooks/tts-notification.sh

input=$(cat)
message=$(echo "$input" | jq -r '.message // empty')

# 根据 message 文本内容朗读不同的提示文本
if [[ "$message" == *"权限"* ]] || [[ "$message" == *"permission"* ]]; then
    say "主人，有权限请求需要您确认" -v Ting-Ting
elif [[ "$message" == *"等待"* ]] || [[ "$message" == *"waiting"* ]] || [[ "$message" == *"输入"* ]]; then
    say "您好，我在等待您的输入" -v Ting-Ting
else
    say "Claude Code 通知" -v Ting-Ting
fi

配置使用：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/tts-notification.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

方法二：生成音频文件后播放（推荐）

如果需要更高质量的语音效果，可以先生成音频文件，然后用 afplay 播放：

#!/bin/bash
# ~/.claude/hooks/tts-audio.sh

input=$(cat)
message=$(echo "$input" | jq -r '.message // empty')

# 根据 message 文本内容生成不同的语音提示
if [[ "$message" == *"权限"* ]] || [[ "$message" == *"permission"* ]]; then
    temp_audio=$(mktemp /tmp/claude_permission_XXX.aiff)
    say "主人，需要权限确认" -o "$temp_audio" -v Ting-Ting
    afplay "$temp_audio"
    rm "$temp_audio"
elif [[ "$message" == *"等待"* ]] || [[ "$message" == *"waiting"* ]] || [[ "$message" == *"输入"* ]]; then
    temp_audio=$(mktemp /tmp/claude_idle_XXX.aiff)
    say "等待您的归来" -o "$temp_audio" -v Ting-Ting
    afplay "$temp_audio"
    rm "$temp_audio"
else
    # 使用默认提示音
    afplay ~/.claude/sounds/default.mp3
fi

使用系统自带音效

macOS 系统自带了丰富的音效库，无需下载额外文件：

# 列出所有系统音效
ls /System/Library/Sounds/

# 常用系统音效示例
afplay /System/Library/Sounds/Glass.aiff      # 清脆的"叮"声（推荐）
afplay /System/Library/Sounds/Ping.aiff       # 温和的提示音
afplay /System/Library/Sounds/Purr.aiff       # 柔和的提示音
afplay /System/Library/Sounds/Sosumi.aiff     # 经典的 Mac 启动音
afplay /System/Library/Sounds/Tink.aiff       # 短促的提示音
afplay /System/Library/Sounds/Bottle.aiff     # 弹跳音效
afplay /System/Library/Sounds/Frog.aiff       # 蛙叫声
afplay /System/Library/Sounds/Submarine.aiff  # 潜水艇音效

快速配置示例：

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "say \"任务已完成\" -v Ting-Ting"
          }
        ]
      }
    ]
  }
}

组合使用：

#!/bin/bash
# ~/.claude/hooks/system-sound.sh

input=$(cat)
message=$(echo "$input" | jq -r '.message // empty')

# 根据 message 文本内容使用不同的提示方式
if [[ "$message" == *"权限"* ]] || [[ "$message" == *"permission"* ]]; then
    # 使用系统音效 + 语音播报
    afplay /System/Library/Sounds/Glass.aiff &
    say "Claude 需要输入" -v Ting-Ting -r 180
elif [[ "$message" == *"等待"* ]] || [[ "$message" == *"waiting"* ]] || [[ "$message" == *"输入"* ]]; then
    afplay /System/Library/Sounds/Ping.aiff
else
    afplay /System/Library/Sounds/Glass.aiff
fi

优势

• ✅ 无需下载：系统自带，开箱即用
• ✅ 质量保证：Apple 官方音效，质量可靠
• ✅ 轻量级：系统音效文件很小，加载快
• ✅ 风格统一：与 macOS 系统体验一致

可用的语音参数

say 命令支持多种参数和语音：

# 列出所有可用语音
say -v "?"

# 常用中文语音
say -v Ting-Ting "你好"     # 中文（女声）
say -v Sin-ji "你好"        # 粤语（女声）
say -v Mei-Jia "你好"       # 台湾普通话（女声）

# 常用英文语音
say -v Samantha "Hello"     # 英文（女声，美国）
say -v Daniel "Hello"       # 英文（男声，英国）
say -v Karen "Hello"        # 英文（女声，澳大利亚）

# 调整语速（默认 175，范围 10-500）
say "快速播报" -r 200
say "慢速播报" -r 100

# macOS 的 say 命令不支持直接调整音量
# 音量需要通过系统音量控制或使用其他工具
# 例如：osascript -e 'set volume output volume 75'

混合音频和语音提示

#!/bin/bash
# ~/.claude/hooks/hybrid-notification.sh

input=$(cat)
message=$(echo "$input" | jq -r '.message // empty')

# 先播放提示音，再朗读文本
if [[ "$message" == *"权限"* ]] || [[ "$message" == *"permission"* ]]; then
    afplay ~/.claude/sounds/notification.mp3 &
    sleep 0.3
    say "权限请求" -v Ting-Ting -r 180
else
    afplay ~/.claude/sounds/default.mp3
fi

注意事项

• say 命令仅在 macOS 上可用，Linux 用户可使用 espeak 或 festival
• 朗读可能需要较长时间，建议设置合理的 timeout 值（10-15 秒）
• 首次使用某个语音时可能需要下载语音包，请确保网络连接正常

根据任务类型播放不同音效

使用 PreToolUse Hook 记录任务类型，然后在 Stop Hook 中播放对应音效：

#!/usr/bin/env python3
# ~/.claude/hooks/task-tracker.py
import json
import sys

# 读取输入
input_data = json.load(sys.stdin)
event = input_data.get('hook_event_name', '')

if event == 'PreToolUse':
    tool_name = input_data.get('tool_name', '')
    # 记录当前任务类型
    with open('~/.claude/current_task', 'w') as f:
        f.write(tool_name)

elif event == 'Stop':
    # 读取任务类型
    try:
        with open('~/.claude/current_task', 'r') as f:
            task = f.read().strip()

        # 根据任务播放不同音效
        import subprocess
        if task == 'Write':
            subprocess.run(['afplay', '~/.claude/sounds/write-complete.mp3'])
        elif task == 'Bash':
            subprocess.run(['afplay', '~/.claude/sounds/bash-complete.mp3'])
        else:
            subprocess.run(['afplay', '~/.claude/sounds/complete.mp3'])
    except:
        pass

🐛 故障排查

问题 1：提示音没有播放

解决方案：

1. 检查配置文件语法

# 验证 JSON 是否有效
cat ~/.claude/settings.json | jq .

2. 手动测试播放命令

# macOS
afplay ~/.claude/sounds/notification.mp3

# Linux
aplay ~/.claude/sounds/notification.mp3

# Windows
powershell -c (New-Object Media.SoundPlayer "C:\Users\YourName\.claude\sounds\notification.wav").PlaySync()

3. 查看 Hook 是否注册

# 在 Claude Code 中运行
/hooks

问题 2：提示音延迟播放

解决方案：

添加 timeout 参数，确保音效能及时播放：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "ffplay -nodisp -autoexit ~/.claude/sounds/complete.mp3 2>/dev/null",
            "timeout": 3
          }
        ]
      }
    ]
  }
}

问题 3：音频文件路径问题

解决方案：

使用绝对路径或 $HOME 环境变量：

{
  "command": "afplay $HOME/.claude/sounds/notification.mp3"
}

📚 完整示例

macOS 完整配置示例

{
  "description": "Claude Code 提示音配置",
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay $HOME/.claude/sounds/notification.mp3",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay $HOME/.claude/sounds/complete.mp3 && osascript -e 'display notification \"Claude Code 任务已完成\" with title \"Claude Code\" sound name \"Glass\"'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Linux 完整配置示例

{
  "description": "Claude Code 提示音配置",
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "aplay $HOME/.claude/sounds/notification.mp3",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "aplay $HOME/.claude/sounds/complete.mp3 && notify-send 'Claude Code' '任务已完成'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Windows 完整配置示例

{
  "description": "Claude Code 提示音配置",
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \"(New-Object Media.SoundPlayer '$env:USERPROFILE\\.claude\\sounds\\notification.wav').PlaySync()\"",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -c \"[console]::beep(800,200); (New-Object Media.SoundPlayer '$env:USERPROFILE\\.claude\\sounds\\complete.wav').PlaySync(); Add-BurntToastNotification -Title 'Claude Code' -Text '任务已完成'\"",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

💡 最佳实践

1. 音效选择建议

• 音效长度：控制在 1-3 秒，避免过长
• 音量适中：不要太大声，以免惊吓
• 音质清晰：使用高质量的音频文件
• 风格统一：所有音效保持相似的风格

2. 性能优化

• 使用轻量级音频格式（MP3、OGG）
• 避免使用大型 WAV 文件
• 设置合理的 timeout 值
• 考虑使用系统内置音效

3. 安全考虑

安全提醒

• 只播放你信任的音频文件
• 不要在 Hook 中执行不明命令
• 定期检查 ~/.claude/settings.json 内容
• 使用绝对路径避免路径遍历攻击

🎯 总结

通过为 Claude Code 添加提示音，你可以：

✅ 提高效率：及时响应权限请求，不耽误工作流程

✅ 改善体验：无需紧盯屏幕，听声辨位

✅ 减少遗漏：不再错过重要的等待输入提示

✅ 增强感知：清楚知道任务何时完成

✅ 个性化定制：选择喜欢的音效，打造专属体验

快速开始

1. 准备三个音频文件（notification、complete、waiting）
2. 创建 ~/.claude/sounds/ 目录并放入音频文件
3. 编辑 ~/.claude/settings.json 添加 Hooks 配置
4. 重启 Claude Code
5. 运行 /hooks 验证配置
6. 开始享受有声的 Claude Code 体验！

---

快去试试吧！让 Claude Code 在关键时刻"出声"提醒你，打造更智能、更人性化的 AI 编程体验！ 🎵🚀

如果你遇到任何问题，欢迎查阅 Claude Code Hooks 官方文档 或访问社区寻求帮助～ (,,><,,)

📚 参考资源

• Claude Code Hooks 官方文档
• Claude Code 钩子入门指南
• 给 Claude Code 的工具加上钩子 - 知乎
• Claude Code Hooks 系统详解 - CSDN

版权所有

版权归属：AkaChou

许可证：署名 4.0 国际 (CC-BY-4.0)

贡献者: AkaChou

下一页UI/UX Pro Max：让 AI 成为你专属设计师的智能工具