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，插件也不会在首次运行时现下载 —— 内置的可执行文件会先校验再安装到插件自管的路径。当前插件版本 0.8.2 内置 CLI 0.8.2。
daemonless 插件模式
插件模式下不再拉起 CLI daemon。插件进程直接持有 profile 的存储写者锁并直写通知 / 录音 / 图片 / 已同步网页，同时独占 openclaw-service 隧道 —— 手机通知 Relay 与 APP 会话 Relay 合并为同一条连接。CLI 的只读命令（notification *、recording list/status/events、image *、synced-web-page *）照常可用，读的就是同一批文件；yoooclaw daemon start 在插件持锁期间会被拒绝并返回 YOOOCLAW_DAEMON_DISABLED_BY_PLUGIN。停用插件后锁自动释放，即回到独立 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_...重复执行同一条命令即可升级（不需要 --force，走的是 pip install --upgrade）。也可以直接在对话里让插件自更新，见更新与升级。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可执行文件旁边（如果该目录可写）软链这两个命令； - 若发现新版独立 CLI（0.9+）已注册了开机自启动服务，安装前先禁用它，避免登录/重启后又把存储所有权抢回去；这一步禁用不了时（CLI 版本太旧不支持
daemon autostart）会直接拒绝接管； - 重启 Hermes gateway 后，分级验证插件是否真正激活：先确认包装好（
PACKAGE_INSTALLED）→ 再确认当前 Hermes profile 的plugins.enabled里勾上了（PLUGIN_CONFIGURED）→ 最后确认运行时真正接管了存储写者锁和 Relay 连接（PLUGIN_ACTIVE）。任一环节校验失败，脚本现在会以非零退出码结束并打印Package installed, activation failed.（此前无论校验是否通过都会打印"安装完成"）。daemonless 模式下写者锁必须由长驻的 gateway 进程持有，安装器只能验证而不能代为接管（临时 Python 进程一退出就会释放 OS 锁）。
常用选项：
| 选项 / 环境变量 | 说明 |
|---|---|
--enable-app / --no-enable-app | 已废弃的空操作：yoooclaw_app 适配器现在总是启用，这两个 flag 保留只为不让旧命令行报错。 |
--version <VERSION> / --oss-channel <NAME> | 装指定版本 / 指定读哪个版本标记（默认 latest）。见更新与升级。 |
--hermes-profile <name> / HERMES_PROFILE | Hermes 运行在具名 profile（hermes --profile <name>）下时指定，安装器会去改该 profile 的 config.yaml，网关重启命令也会带上 --profile；不传时改的是未使用具名 profile 场景下的全局配置。 |
YOOOCLAW_HERMES_CLI_LINK_DIR | 自定义 CLI 命令软链目录。 |
YOOOCLAW_HERMES_INSTALL_CLI=0 | 跳过 shell 命令软链。 |
--no-start-daemon | 跳过安装后的插件激活校验（历史命名，daemonless 模式下已无 daemon 可启）。 |
更多本地开发选项（--skip-install、--package、--version、--python、--no-restart、--no-start-daemon 等）可通过安装脚本的 --help 查看。稳定版通过 PyPI 分发（见下文手动安装）。
手动安装
稳定版也发布到 PyPI。装进 Hermes 使用的同一个 Python 环境后，Hermes 会发现这两个入口点插件：
pip install yoooclaw-hermes-pluginHermes 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。 - 内置 CLI：插件包自带目标平台的
yoooclaw可执行文件，PATH 查找只作为本地开发兜底。 - APP transport：插件进程内维持一族托管 WebSocket 连接 ——
openclaw-service*.yoooclaw.com隧道（每个 api-key 一条），同时承载 Hermes APP 会话 RPC 帧与手机通知 / 录音 / 图片 relay 帧；APP 协议层先认领自己的白名单帧，其余交给进程内的本地 ingest。 - 本地存储直写：通知、录音（App 下发的转写 / 总结，可选后台下载
ossUrl音频）、图片、已同步网页（浏览器扩展经 Relay 投递）全部由插件进程按 CLI 的目录约定落盘，状态事件经进程内事件总线转发到隧道。 - 本地 relay server 与浏览器聊天 UI，用于端到端 APP 会话测试。
APP 认证
APP 用户认证由 Relay 服务强制执行，Hermes 插件不再维护单独的本地 APP 用户白名单。
APP 适配器默认从 ~/.yoooclaw/credentials.json 解析 Relay key —— 和 yoooclaw CLI 读的是同一份，插件和 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 里清除。