--- url: /ai/sb2kd7zk/index.md description: 通过配置 Claude Code Hooks 系统添加声音提示，让 Claude 在权限请求、任务完成、等待输入等关键时刻发出提醒。 --- # Claude Code 添加任务提示音：让 AI 助手"出声"工作 ::: tip 为什么要添加提示音？ 使用 Claude Code 时，你可能遇到过这些场景： * 🔐 **需要授权确认**：Claude 等待你批准某个操作，但你没注意到 * ✅ **任务完成**：长时间运行的任务完成了，但你还在摸鱼 * ⌨️ **等待输入**：Claude 需要你提供更多信息，但你没看到提示 通过配置 **Hooks（钩子）** 系统，你可以为这些场景添加声音提示，让 Claude Code 在关键时刻发出提醒，不再错过任何重要信息！ ::: ## ✨ 提示音场景 Claude Code 支持在以下三个关键场景添加提示音： | 场景 | Hook 事件 | 触发时机 | |------|-----------|----------| | **要求授权** | `Notification` | Claude 需要你的权限来使用工具时 | | **任务完成** | `Stop` | 主 Claude 完成响应时 | | **等待输入** | `Notification` | 提示输入空闲超过 60 秒时 | ## 📦 配置文件位置 Hooks 配置文件按优先级排序（从高到低）： ::: details 配置文件说明 * **`.claude/settings.local.json`** - 项目本地配置（不提交到 Git，仅当前项目） * **`.claude/settings.json`** - 项目配置（提交到 Git，团队共享） * **`~/.claude/settings.json`** - 用户全局配置（所有项目生效） ::: **推荐做法**：将提示音配置放在 `~/.claude/settings.json`，这样所有项目都能使用！ ## 🎵 准备提示音文件 在配置之前，首先需要准备提示音文件（无论你选择哪种配置方法，都需要这一步）： ::: tip 提示音选择建议 * **授权提醒**：短促、明显的提示音（如"叮"声） * **任务完成**：愉悦、令人满意的音效（如"完成"音） * **等待输入**：持续或周期性的提醒音 ::: 你可以从以下资源获取提示音： * **系统音效库**：macOS / Windows / Linux 自带音效 * **免费音效网站**：[Freesound](https://freesound.org/)、[Zapsplat](https://www.zapsplat.com/) * **自制音效**：使用在线工具生成 将音效文件放在固定位置，例如： ```bash # macOS/Linux ~/.claude/sounds/ # Windows %USERPROFILE%\.claude\sounds\ ``` ::: info 音频文件格式建议 * 使用轻量级格式：MP3、OGG * 音频长度：1-3 秒 * 避免使用过大的 WAV 文件 ::: ## ⚡ 方法一：直接在 Claude Code 中配置（推荐） 官方提供了交互式 `/hooks` 命令，让你可以在对话中直接配置提示音，**无需手动编辑任何配置文件**！ ### 使用步骤 1. **打开 Hooks 配置界面** 在 Claude Code 对话中直接输入： ``` /hooks ``` 2. **选择配置存储位置** 系统会提示你选择配置保存位置： * **User** - 保存到 `~/.claude/settings.json`（全局生效，推荐） * **Project** - 保存到 `.claude/settings.json`（仅当前项目） ::: tip 提示 选择 **User** 可以让所有项目都使用提示音功能！ ::: 3. **添加 Hook 事件** 选择要配置的 Hook 事件类型： * **Notification** - 用于权限请求和等待输入提示 * **Stop** - 用于任务完成提示 4. **输入播放命令** 根据你的操作系统输入相应的播放命令： **macOS：** ```bash afplay ~/.claude/sounds/notification.mp3 ``` **Linux：** ```bash aplay ~/.claude/sounds/notification.mp3 ``` **Windows：** ```bash 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 已成功添加。 ::: info 优势 * ✅ **简单直观**：交互式界面，无需了解 JSON 语法 * ✅ **自动保存**：配置自动写入文件，无需手动操作 * ✅ **即时生效**：保存后立即生效，无需重启 * ✅ **安全可靠**：官方推荐方式，不易出错 ::: ## 📝 方法二：手动编辑配置文件（高级用户） 如果你更喜欢手动控制，或者需要批量配置多个 Hook，可以手动编辑配置文件。 ::: details 配置步骤 1. **编辑配置文件** ```bash # 编辑用户全局配置 nano ~/.claude/settings.json # 或者使用你喜欢的编辑器 code ~/.claude/settings.json ``` 2. **添加 Hooks 配置** 在 `settings.json` 中添加以下内容： ```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 配置 ::: details macOS 完整配置示例 ```json { "hooks": { "Notification": [ { "hooks": [ { "type": "command", "command": "afplay ~/.claude/sounds/notification.mp3" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "afplay ~/.claude/sounds/complete.mp3" } ] } ] } } ``` ::: ### Linux 配置 ::: details Linux 完整配置示例 ```json { "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 配置 ::: details Windows 完整配置示例 ```json { "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`），可以统一配置： ::: details 跨平台配置示例 ```json { "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` 事件。 ::: details 典型情况 * 执行 Shell 命令（Bash 工具） * 写入文件（Write 工具） * 访问网络（WebSearch/WebFetch） * 读取敏感文件 **提示音建议**：短促、明显，能快速吸引注意力 ::: ### 场景 2：任务完成（Stop Hook） 当主 Claude Code 完成响应时，触发 `Stop` 事件。 ::: details 典型情况 * 代码生成完成 * 文件修改完成 * 任务执行成功 * 分析报告完成 **提示音建议**：愉悦、令人满意，传达"完成"的感觉 ::: ### 场景 3：等待输入（Notification Hook） 当提示输入空闲超过 60 秒时，触发 `Notification` 事件。 ::: details 典型情况 * Claude 需要更多上下文信息 * 需要你确认某个选择 * 等待你提供必要的参数 **提示音建议**：持续或周期性，提醒你回来继续 ::: ## 🎨 高级配置 ### 区分不同通知类型 根据官方文档，**Notification hook 不使用 matcher**，你可以省略匹配器字段。Notification 输入 JSON 格式如下： ```json { "session_id": "abc123", "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl", "cwd": "/Users/...", "hook_event_name": "Notification", "message": "Claude 需要您的权限来使用 Bash" } ``` ::: warning 注意 官方文档中 Notification hook 的输入**只有** `message` 字段，**没有** `notification_type` 字段！ ::: 由于官方没有提供通知类型字段，你需要通过 `message` 文本内容来区分不同场景： ```bash #!/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 ``` ::: tip Notification 触发场景 根据官方文档，Notification 在以下情况触发： 1. **权限请求**：Claude 需要你的权限来使用工具 * 示例消息："Claude 需要您的权限来使用 Bash" 2. **空闲提示**：提示输入已空闲至少 60 秒 * 示例消息："Claude 正在等待您的输入" ::: 然后在配置中使用（**省略 matcher 字段**）： ```json { "hooks": { "Notification": [ { "hooks": [ { "type": "command", "command": "bash ~/.claude/hooks/play-sound.sh" } ] } ] } } ``` ### 添加视觉提示 除了声音，你还可以添加系统通知： ```json { "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`，你可以实现更灵活的语音提示： ::: warning 重要 根据官方文档，Notification hook 的输入中**没有** `notification_type` 字段。以下脚本通过 `message` 文本内容来区分不同场景。 ::: #### 方法一：直接朗读文本（实时） ```bash #!/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 ``` **配置使用：** ```json { "hooks": { "Notification": [ { "hooks": [ { "type": "command", "command": "bash ~/.claude/hooks/tts-notification.sh", "timeout": 10 } ] } ] } } ``` #### 方法二：生成音频文件后播放（推荐） 如果需要更高质量的语音效果，可以先生成音频文件，然后用 `afplay` 播放： ```bash #!/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 系统自带了丰富的音效库，无需下载额外文件： ```bash # 列出所有系统音效 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 # 潜水艇音效 ``` **快速配置示例：** ```json { "hooks": { "Notification": [ { "hooks": [ { "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "say \"任务已完成\" -v Ting-Ting" } ] } ] } } ``` **组合使用：** ```bash #!/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 ``` ::: tip 优势 * ✅ **无需下载**：系统自带，开箱即用 * ✅ **质量保证**：Apple 官方音效，质量可靠 * ✅ **轻量级**：系统音效文件很小，加载快 * ✅ **风格统一**：与 macOS 系统体验一致 ::: #### 可用的语音参数 `say` 命令支持多种参数和语音： ```bash # 列出所有可用语音 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' ``` #### 混合音频和语音提示 ```bash #!/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 ``` ::: tip 注意事项 * `say` 命令仅在 macOS 上可用，Linux 用户可使用 [espeak](https://espeak.sourceforge.io/) 或 [festival](http://www.cstr.ed.ac.uk/projects/festival/) * 朗读可能需要较长时间，建议设置合理的 `timeout` 值（10-15 秒） * 首次使用某个语音时可能需要下载语音包，请确保网络连接正常 ::: ### 根据任务类型播放不同音效 使用 `PreToolUse` Hook 记录任务类型，然后在 `Stop` Hook 中播放对应音效： ```python #!/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. 检查配置文件语法 ```bash # 验证 JSON 是否有效 cat ~/.claude/settings.json | jq . ``` 2. 手动测试播放命令 ```bash # 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 是否注册 ```bash # 在 Claude Code 中运行 /hooks ``` ### 问题 2：提示音延迟播放 **解决方案：** 添加 `timeout` 参数，确保音效能及时播放： ```json { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "ffplay -nodisp -autoexit ~/.claude/sounds/complete.mp3 2>/dev/null", "timeout": 3 } ] } ] } } ``` ### 问题 3：音频文件路径问题 **解决方案：** 使用绝对路径或 `$HOME` 环境变量： ```json { "command": "afplay $HOME/.claude/sounds/notification.mp3" } ``` ## 📚 完整示例 ::: details macOS 完整配置示例 ```json { "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 } ] } ] } } ``` ::: ::: details Linux 完整配置示例 ```json { "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 } ] } ] } } ``` ::: ::: details Windows 完整配置示例 ```json { "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. 安全考虑 ::: warning 安全提醒 * 只播放你信任的音频文件 * 不要在 Hook 中执行不明命令 * 定期检查 `~/.claude/settings.json` 内容 * 使用绝对路径避免路径遍历攻击 ::: ## 🎯 总结 通过为 Claude Code 添加提示音，你可以： ✅ **提高效率**：及时响应权限请求，不耽误工作流程 ✅ **改善体验**：无需紧盯屏幕，听声辨位 ✅ **减少遗漏**：不再错过重要的等待输入提示 ✅ **增强感知**：清楚知道任务何时完成 ✅ **个性化定制**：选择喜欢的音效，打造专属体验 ::: info 快速开始 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 官方文档](https://www.claude-cn.org/claude-code-docs-zh/reference/hooks) 或访问社区寻求帮助～ (,,><,,) ## 📚 参考资源 * [Claude Code Hooks 官方文档](https://www.claude-cn.org/claude-code-docs-zh/reference/hooks) * [Claude Code 钩子入门指南](https://www.claude-cn.org/claude-code-docs-zh/building/hooks-guide) * [给 Claude Code 的工具加上钩子 - 知乎](https://zhuanlan.zhihu.com/p/1948411557827581110) * [Claude Code Hooks 系统详解 - CSDN](https://blog.csdn.net/qq_44810930/article/details/156146071)