Hermes 插件

yoooclaw-hermes-plugin 是 Hermes Agent 与 YoooClaw 之间的 Python 插件桥接层。它包含两个入口点插件：

• yoooclaw —— 通用 Hermes 插件：tools、hooks、slash commands、CLI 子命令、skills。
• yoooclaw_app —— APP 平台适配器：把手机 APP 消息接入 Hermes，并把 Hermes 回复转发回 APP。

共享的通知 / 录音 / 图片 / 凭据 / 灯效数据面仍由 @yoooclaw/cli daemon 负责；Hermes 插件把这个 daemon 作为 localhost sidecar 启动和管理，并独立承担两条外部 WebSocket 通路：手机通知 Relay（openclaw-service）和 APP 会话 Relay，二者现在合并为同一条隧道。

生产环境发布的插件包里内置了对应平台的 yoooclaw 可执行文件，不需要用户预先装 CLI，插件也不会在首次运行时现下载 —— 内置的可执行文件会先校验再安装到插件自管的路径。

一键安装

curl -fsSL https://artifact.yoooclaw.com/hermes-plugin/install.sh | bash -s -- --api-key "ock_..."

Windows（PowerShell）：

& ([scriptblock]::Create((irm https://artifact.yoooclaw.com/hermes-plugin/install.ps1))) --api-key ock_...

重复执行同一条命令即可升级。PowerShell 安装器会自动解析匹配的 win_amd64 wheel、定位标准安装路径下的 Hermes Agent 虚拟环境，必要时用 ensurepip 引导 pip，再用 pip install --upgrade 完成安装。

版本要求

安装器要求 Hermes Agent >= 0.14.0。更早版本没有 APP 适配器依赖的插件平台 API（PluginContext.register_platform），安装器会直接报错停止，而不是留下一个半启用的插件。

安装器做的事情：

• 把共享 api-key 写入 ~/.yoooclaw/credentials.json；
• 清理 ~/.hermes/.env 里过期的 API-key / 旧版本地 APP 授权环境变量；
• 确保 ~/.hermes/config.yaml 的 plugins.enabled 里同时有 yoooclaw 和 yoooclaw_app；
• 把内置的 yoooclaw / yc 可执行文件装到 ~/.yoooclaw/hermes-plugin/bin，维护托管 shim，并在检测到的 hermes 可执行文件旁边（如果该目录可写）软链这两个命令；
• 重启 Hermes gateway 后，确保 YoooClaw daemon 正在运行。

常用选项：

选项 / 环境变量	说明
--no-enable-app / YOOOCLAW_HERMES_ENABLE_APP=0	仅安装 tools 插件，不启用 APP 适配器。
YOOOCLAW_HERMES_CLI_LINK_DIR	自定义 CLI 命令软链目录。
YOOOCLAW_HERMES_INSTALL_CLI=0	跳过 shell 命令软链。
--no-start-daemon / YOOOCLAW_HERMES_START_DAEMON=0	跳过安装后自动启动 daemon。

更多本地开发选项（--skip-install、--package、--version、--python、--no-restart、--no-start-daemon 等）可通过安装脚本的 --help 查看。稳定版通过 PyPI 分发（见下文手动安装）。

手动安装

稳定版也发布到 PyPI。装进 Hermes 使用的同一个 Python 环境后，Hermes 会发现这两个入口点插件：

pip install yoooclaw-hermes-plugin

Hermes 0.15.1 及更早版本的入口点插件启用方式

hermes plugins enable <name> / disable / list 只识别目录形式（~/.hermes/plugins/）和内置插件，不会扫描 Python entry points，所以 hermes plugins enable yoooclaw 会报 "Plugin 'yoooclaw' is not installed or bundled."。运行时加载器确实会加载入口点插件，但前提是插件名出现在 plugins.enabled 白名单里。对 pip 安装的场景，直接编辑 ~/.hermes/config.yaml：

plugins:
  enabled: [yoooclaw, yoooclaw_app]

然后重启 gateway（hermes gateway restart）。上面的一键安装器已经自动处理了这一步配置写入。

功能概览

• 通用 Hermes 插件：tools、hooks、slash commands、CLI 子命令、skills。
• yoooclaw_app 平台适配器：APP 消息进 Hermes，Hermes 回复出 APP。
• Tool bridge：调用 yc --format json 与 daemon 的 localhost HTTP API。
• 内置 CLI：插件包自带目标平台的 yoooclaw 可执行文件，PATH 查找只作为本地开发兜底。
• APP transport：插件进程内维持一族托管 WebSocket 连接 —— openclaw-service*.yoooclaw.com 隧道（每个 api-key 一条），同时承载 Hermes APP 会话 RPC 帧与手机通知 / 录音 / 图片 relay 帧；APP 协议层先认领自己的白名单帧，其余全部桥接到本地 CLI sidecar。
• 本地 relay server 与浏览器聊天 UI，用于端到端 APP 会话测试。
• 通知 watcher：用 OS 文件通知监听当前 CLI profile 的 notifications/ 目录，把新落盘的通知喂给宿主侧灯效规则运行时，不需要额外加一个 daemon 事件 API。

APP 认证

APP 用户认证由 Relay 服务强制执行，Hermes 插件不再维护单独的本地 APP 用户白名单。

APP 适配器默认从 ~/.yoooclaw/credentials.json 解析 Relay key —— 和 yoooclaw CLI / 基础 daemon 读的是同一份，插件和 CLI 因此保持同一把 key。Hermes 环境里残留的 YOOOCLAW_APP_API_KEY / YOOOCLAW_API_KEY 会被忽略，安装器也会把它们清掉。

APP 会话走 openclaw-service Relay 隧道，endpoint 跟随 PHONE_NOTIFICATIONS_ENV / 当前 profile：

PHONE_NOTIFICATIONS_ENV	Relay host
production（默认）	openclaw-service.yoooclaw.com
development / test	对应的内部 staging 主机（仅内部使用）

未设置或未知值会回落到当前 profile 的 environment，再回落到 production。YOOOCLAW_OPENCLAW_RELAY_URL 可以覆盖隧道 URL 用于本地或 staging 验证；已废弃的 YOOOCLAW_APP_RELAY_URL 会被安装器从 .env 里清除。

下一步

• 使用与生命周期 —— 环境切换、daemon 生命周期、常用命令。
• 调试与排错 —— 日志位置、lifecycle 诊断、常见故障处理。