现象

Claude Code 装了 peon-ping，按照设置本该在 agent 跑完任务、弹权限请求，这些本该有提示音的时候，一点动静都没有。配置看着没问题， enabled: true ，音量 0.5，peasant 音效包也在。

排查

先开 debug 日志：

peon debug on
# 触发一次事件后查看
peon logs

日志里事件确实触发了， category 也分配对了（ task.complete 、 input.required ），声音文件也选好了。但播放那行写着：

[play] backend=ssh file=PeasantYes1.wav volume=0.5 async=true

backend=ssh 。这就是问题所在。

原因

peon-ping 的 detect_platform() 函数在启动时检查 SSH_CONNECTION 或 SSH_CLIENT 环境变量，只要有一个有值就把平台标记为 ssh 。后续 play_sound() 走 SSH 分支，把音频请求发往 relay（默认 localhost:19998 ），而不是直接调本机的 afplay 。

我的情况是开发环境通过 Termius App 远程 SSH 连到本机（ 127.0.0.1 ），所以 SSH_CONNECTION 一直有值。但是 relay 服务没在跑，声音就发到了一个不存在的端口上。

# 确认一下
echo $SSH_CONNECTION
# 输出: 127.0.0.1 57122 127.0.0.1 22

解决

peon-ping 提供了三种 SSH 音频路由模式，通过 ssh_audio_mode() 控制：

  • relay （默认）：发 HTTP 请求到本地 relay
  • local ：忽略 SSH 检测，直接用本机音频后端
  • auto ：先试 relay，失败再 fallback 到本地

我的场景是 SSH 到本机，改成 local 就行了：

peon ssh-audio local

把 SSH 音频模式从默认的 relay 改成 local=，这样即使检测到 SSH 环境也会直接用本机 =afplay 播放。

如果真的是远程服务器上开发、需要把声音传回本地，那得在本地启 relay：

peon relay --daemon

排查思路

peon-ping 不响的时候，按这个顺序来：

  • peon status 确认没被 pause
  • peon debug on 开日志
  • 触发一次事件，看 peon logs 里有没有 [sound] 和 [play]
  • 有 [play] 但 backend 不是 mac，说明走了非本地路径
  • 检查 SSH_CONNECTION 环境变量，看是不是被误判了