字段	内容
作者	Evan
日期	2026-05-05
事项	v0.3.0 重大架构升级。声音播放从 HTTP server 中转改为 hooks 直连 afplay，App 关闭 / 电脑重启都不再失声。移除 LaunchAgent，删除 Clash Verge 直连规则需求。老用户首次启动 v0.3.0 自动迁移
版本	v1.4

English · 中文

🔊 Claude Sound

为 Claude Code 和 Claude 桌面客户端配置事件提示音的 macOS 菜单栏小工具。让你在长任务跑完、需要权限确认时听得到。

双击 .dmg 拖到 Applications 就能用，菜单栏一键开关，零终端门槛。

痛点

Claude Code / Claude 桌面客户端默认在以下时刻没有声音：

• 🔐 弹出权限请求弹窗（Allow / Deny）—— 切走干别的事最容易错过
• 🔔 idle 等待你输入
• ✅ 主任务回复完成 —— 不知道好了没
• 🤖 子 Agent 跑完
• ❌ 任务出错或被打断

本工具通过 Claude Code 的 hooks 机制，把这些事件接上 macOS 系统声音或自定义声音。桌面客户端、终端 claude 命令双端通杀。

v0.3.0 关键升级

旧版本（v0.2.x）声音走 HTTP 模式：hooks 触发 → 请求本地 server → server 调 afplay。这个链路有两个故障窗口：

• App 重启后 server 启动需要 2-5 秒，期间触发的 hook 会静默失败
• 电脑重启后 server 还没起来就触发 hook，同样失败

v0.3.0 把 hooks 改成 command 模式——直接写 afplay /path/to/sound.aiff 到 ~/.claude/settings.json，完全绕过 server。afplay 是 macOS 内置命令永远在线，App 退出 / 电脑重启都不影响声音播放。

App 的角色变了：从「runtime」变成「纯配置工具」。打开 App 是为了改声音 / 改音量 / 总开关，配置完可以直接退出，声音照响。

如果你从 v0.2.x 升级，第一次启动 v0.3.0 会自动：

• 卸载老版本 LaunchAgent（不再需要）
• 把 settings.json 里的 http hooks 改写成 command hooks

截图

特性

模块	描述
🍎 菜单栏小工具	不占 Dock，顶部菜单栏一个图标，点开关声音 / 配置
🚀 解压即用	DMG 拖拽安装，无需 Node.js / 不动终端
💪 零依赖运行	hooks 直连 afplay，App 关了照样响，重启电脑也照样响
🎯 6 个事件	PermissionRequest / Notification / Stop / StopFailure / SubagentStop / SessionStart
🍎 系统声音	自动扫描 /System/Library/Sounds/，下拉选 + 试听
📁 自定义声音	拖拽上传 aiff/wav/mp3/m4a/caf，存到 ~/.claude/sounds/
🔊 每事件独立音量	0–100% 滑杆
🌗 亮/暗主题 + 中/英双语	跟随系统，可切换
💾 自动持久化	改动直接写 ~/.claude/settings.json，跨会话永久生效

安装

系统要求

• macOS 10.12+（依赖系统自带的 afplay）
• 已安装 Claude Code 或 Claude 桌面客户端

步骤

1. 去 Releases 下最新 .dmg

   • Apple Silicon（M1/M2/M3/M4）：Claude Sound-x.x.x-arm64.dmg
   • Intel Mac：Claude Sound-x.x.x.dmg

2. 双击打开，把 Claude Sound 拖到 Applications 文件夹

3. 第一次打开（未签名，需要绕过 Gatekeeper）：

   xattr -dr com.apple.quarantine /Applications/Claude\ Sound.app
   open /Applications/Claude\ Sound.app

   或者手动：应用程序 文件夹 → 右键 Claude Sound.app → 打开 → 点弹出对话框的「打开」

4. 菜单栏右上角看到 🔊 图标 + 配置面板自动弹出 = 完工

没花苹果开发者 99 美元做签名，这一步绕一下。star 多了再补。

使用

菜单栏菜单

点击菜单栏图标 →

菜单项	作用
🔊 / 🔇 声音：开启 / 关闭	一键切换。关闭 = 从 settings.json 摘除 hooks，安静到底
打开配置面板…	弹出 web UI，调每个事件的声音 / 音量
退出	关掉菜单栏图标。声音 hooks 不受影响照常播放

配置完可以直接退出

v0.3.0 hooks 是直连 afplay 的 command 模式，App 只是配置工具。改完声音 / 音量后，点「退出」就行——下次想改再开。声音永远在响，跟 App 是不是开着无关。

让配置生效

⚠️ 修改 hooks 后当前正在运行的 Claude Code 不会立刻生效（hooks 在会话启动时加载）。

• 终端 claude：Ctrl+C × 2 退出，重新跑
• 桌面客户端：⌘+Q 完全退出，重新打开

数据存储

路径	用途
~/.claude/settings.json	hooks 配置（合并写入，不覆盖你的其他设置）
~/.claude/sounds/	你上传的自定义声音文件
~/.claude/sounds/.claude-sound-stash.json	总开关「关闭」时备份的 hook 配置

v0.3.0 不再需要 ~/Library/LaunchAgents/com.evan.claude-sound.plist、/tmp/claude-sound.log。从 v0.2.x 升级时会自动清理。

完全卸载

1. 菜单栏图标 → 退出
2. 把 Claude Sound.app 从 Applications 拖到废纸篓
3. 选删干净 ↓

   rm -rf ~/.claude/sounds
   # 手动从 ~/.claude/settings.json 删除 hooks 下相关事件键

FAQ

Q: 装好了没声音？ A: 三步排查：

1. 菜单栏「声音」是不是已开启？
2. 配置面板里点试听有没有声？没声 → 系统音量 / 输出设备问题
3. 终端跑 afplay /System/Library/Sounds/Glass.aiff，能响则确认是 hook 没触发；不能响则是系统层面问题

Q: 我从 v0.2.x 升级，需要做什么？ A: 不用做任何事。第一次启动 v0.3.0 会自动卸老 LaunchAgent + 把 http hooks 改写成 command hooks。打开 App 看一眼，菜单栏图标在了，配置还在了，就 OK 了。

Q: 重启电脑 / 重启 App 后还会失声吗？ A: 不会。v0.3.0 hooks 直接调 afplay（macOS 系统命令），不依赖任何后台进程。这正是这一版升级的核心。

Q: 桌面客户端发条消息后，hook 真的会触发吗？ A: 会。Stop / PermissionRequest 都验证过。如果没响，先 ⌘+Q 完全退出桌面客户端再重新开（hooks 只在新会话生效）。

Q: 「未签名应用」对话框怎么办？ A: 跑一行 xattr -dr com.apple.quarantine /Applications/Claude\ Sound.app，或右键 .app → 打开 → 打开。仅首次需要。

Q: Windows 或 Linux 能用吗？ A: 当前不行，依赖 macOS 的 afplay。Linux 可改用 paplay/aplay，欢迎 PR。

Q: 会影响我已有的 settings.json 吗？ A: 不会。本工具只读写 hooks 下 6 个特定事件键，其他设置原样保留。

Q: 端口 3737 被占用怎么办？ A: 先看是不是另一个 Claude Sound 实例在跑（lsof -i:3737）。是的话退掉。不是的话设环境变量 PORT=3838 重新打开 App。注意 v0.3.0 的 server 仅服务于配置面板 UI，端口被占只影响打开配置，不影响声音播放。

Q: 我用 Clash Verge / 系统代理，需要加直连规则吗？ A: v0.3.0 不需要。v0.2.x 那个 Clash Verge 必读问题已经从根上消失——hooks 不再走 HTTP，没有 localhost 请求被代理拦截的可能。

从源码构建（开发者）

git clone https://github.com/vanci444-hue/claude-sound.git
cd claude-sound
npm install
npm run dev:electron        # dev 模式（Tray + 配置窗口）
npm run dist:mac            # 出 .dmg 和 .zip 到 dist/

路线图

• macOS 菜单栏 App，DMG 一键安装（v0.2.0）
• LaunchAgent 后台守护 + 开机自启（v0.2.0）
• 总开关：一键开 / 关声音（v0.2.0）
• command 模式直连 afplay，告别 server 依赖（v0.3.0）
• 老版本自动迁移（v0.3.0）
• 苹果开发者签名 + 公证（解决 Gatekeeper 警告）
• Linux 支持（paplay）
• 自动避让被占用端口
• 发布到 Homebrew tap：brew install vanci444-hue/tap/claude-sound
• 配置导出/导入（跨机器同步）
• 预设方案（"安静"/"活泼"/"专注"）

License

MIT © 2026 Evan