Hermes Agent不弹出通知时，如何修复和设置？

本文共计1012个文字，预计阅读时间需要5分钟。

如果您已配置Hermes Agent的通知功能，但系统提醒或消息弹窗未正常触发，可能的原因包括：

一、检查并启用桌面通知权限

Hermes Agent 依赖操作系统级桌面通知 API（如 Linux 的 D-Bus、macOS 的 Notification Center、Windows 的 Toast API），若权限被禁用或未授权，将无法弹出提醒。

1、在 Linux 系统中，确认已安装并运行 notify-send 工具：which notify-send，若无输出，请执行 sudo apt install libnotify-bin（Ubuntu/Debian）或 brew install terminal-notifier（macOS）。

2、在 macOS 上，打开“系统设置 → 通知与焦点 → Hermes Agent”，确保“允许通知”和“在屏幕顶部显示横幅”已开启。

3、在 Windows 上，进入“设置 → 系统 → 通知 → Hermes Agent”，确认开关为开启状态，并检查“通知样式”是否设为“横幅和声音”。

二、验证 Gateway 服务是否正常运行

弹窗提醒由 Hermes Agent 的 Gateway 模块统一调度，若 Gateway 未启动或异常退出，则所有通知通道均失效。

1、在终端中执行 hermes gateway status，确认输出为 running 且 PID 存在。

2、若状态为 stopped 或报错，执行 hermes gateway start 启动服务。

3、若启动失败，查看日志：执行 hermes gateway logs --tail 50，重点排查 Failed to bind to port 9118 或 lark-oapi not found 类错误。

三、安装缺失的通知依赖库

部分平台需额外安装 SDK 或 CLI 工具以支持特定通知渠道，例如飞书、企业微信等需对应官方 SDK 才能触发桌面弹窗。

1、针对飞书通知，确认已安装 lark-oapi：执行 pip show lark-oapi，若未安装则运行 pip install lark-oapi。

2、针对企业微信，确保 wecom-api 已就绪：执行 pip install wecom-api，并核对 ~/.hermes/config.yaml 中 webhook_url 是否指向有效的应用机器人地址。

3、针对本地桌面弹窗（非第三方平台），确认虚拟环境内已安装 plyer：执行 pip install plyer，该库提供跨平台通知抽象层。

四、检查 config.yaml 中通知配置项

Hermes Agent 仅在明确启用且配置合法时才触发弹窗，config.yaml 中相关字段必须存在且值为 true。

1、使用编辑器打开 ~/.hermes/config.yaml，查找 notifications: 区块。

2、确认以下三项均为 true：enabled、desktop_popup、sound_alert。

3、若使用飞书或钉钉等集成通道，还需检查 channels: 下对应条目是否包含 popup: true，例如：feishu: { popup: true, enabled: true }。

五、绕过桌面通知，启用终端内联提示

当图形界面不可用（如 WSL2、Termux、云服务器 SSH 会话）时，桌面弹窗必然失效，此时可切换至终端原生提示模式。

1、编辑 ~/.hermes/config.yaml，将 notifications.desktop_popup 设为 false。

2、将 notifications.terminal_bell 设为 true，使新消息到达时触发声音提示。

3、将 notifications.inline_display 设为 true，确保关键事件（如会话建立、模型响应完成）以高亮文本形式直接打印在当前终端窗口。