使用与生命周期

切换环境

Relay endpoint 挂在每个 yoooclaw profile 上（每个 profile config.json 里的 relay.url / cloud.host）。用 env 一步切换当前 profile 并重建 websocket 服务组：

hermes yoooclaw env            # 查看当前环境 + Relay 状态
hermes yoooclaw env test       # 切到 test profile
hermes yc env test             # 等价短别名
hermes yoooclaw env default    # 切回 default（生产）profile

聊天会话里也可以直接 /yoooclaw env <profile> 或 /yc env <profile> 达到同样效果。内建的 default、test、development 三个 profile 首次使用时会自动初始化，并写入对应的 Relay endpoint。profile 变化会改变 lifecycle generation，watchdog 随即释放旧 profile 的存储写者锁、接管新 profile 并重建隧道 —— 任意时刻只有一个 profile 处于被接管状态；切到不存在的 profile 名会直接失败，不影响当前连接。

Relay 的 apiKey 是 account 级全局配置（~/.yoooclaw/credentials.json），跟 profile 无关；某个环境需要换一把 key 时用：

yoooclaw auth set-default-api-key <label>

CLI profile 统一用 openclaw-service*.yoooclaw.com 作为 Relay 隧道，APP 会话共用同一条连接。如果旧版插件曾经把过期的历史地址写进过 CLI profile，安装器会自动修复。

daemonless 存储模型

插件模式下没有 CLI daemon。插件进程既是隧道持有者，也是 profile 存储的唯一写者：

	插件模式	独立 CLI 模式
触发条件	Hermes 加载 yoooclaw / yoooclaw_app 插件	用户只装 CLI，自行 daemon start
存储写者	插件进程（唯一）	daemon（唯一）
隧道持有者	插件	daemon 自己的 Relay WS
CLI 只读命令	照常（直接读文件）	照常
yoooclaw daemon start	拒绝：YOOOCLAW_DAEMON_DISABLED_BY_PLUGIN	照常

两种模式靠 ~/.yoooclaw/profiles/<profile>/writer.lock 互斥 —— OS 建议锁，进程死亡自动释放，跨语言（Python 插件 / Go CLI）同一锁命名空间。插件启动时先停掉遗留 daemon 再抢锁；停用插件后锁自动释放，yoooclaw daemon start 即回到独立模式，数据文件不需要任何迁移（存储布局是两边共同的契约）。

另有一把独立于 profile 目录之外的账号级 Relay 消费锁（standalone-relay.flock，跨平台兼容 CLI 侧同名锁），在打开任何 Relay 连接前必须先拿到，防止同一账号被两个 profile、或插件和独立 CLI 同时消费 Relay 流量导致消息重复落盘。当前 active profile 指向的目录被手动删掉时，也会安全回落到 default 而不是报错。

进来的帧直接落到插件进程内的存储引擎：/notifications、recordings.result.write、images.sync 等按 CLI 的目录约定写盘（tmp 文件 + 原子替换），recording.status 这类事件走进程内事件总线转发到隧道，不再经过本地 HTTP 回调。lightrules.* 与 /light/send 帧转成内置 CLI 子进程调用 —— 规则文件归 CLI 所有，避免双写。

插件模式下明确不提供的能力：recordings.retranscribe 与 asr.init 返回 YOOOCLAW_NOT_IMPLEMENTED（Hermes 场景的 ASR 由 App 侧完成）。

生命周期管理

插件把存储接管和 openclaw-service 隧道当成一个事务边界统一管理。启动时按插件版本、当前 profile、Relay environment、PHONE_NOTIFICATIONS_ENV、openclaw-service URL、api-key 指纹算出一个 lifecycle generation（SHA-256 前 24 位）；任何一项变化都会让 generation 对不上，触发整组重建。

hermes yoooclaw lifecycle status
hermes yoooclaw lifecycle restart
hermes yc lifecycle status

lifecycle restart 不会当场重连，而是置一个 restart 标记，由 watchdog 在下一轮轮询（默认 ≤5 秒）看到 mismatch 后 disconnect + connect 重建隧道。

lifecycle 快照的 schema 目前是 v3，新增了 pid、instanceId、hermesProfile、profile、heartbeatAt、lastControlRequestId、lastControlStatus、pendingControlRequestId 等字段；设了 --hermes-profile/HERMES_PROFILE 时，快照文件按 profile 名拆开存放（lifecycle/<hermesProfile>.json），不再是单一的 lifecycle.json。同时新增了一个跨进程控制文件（control/<profile>.json）：外部一次性的 CLI 调用可以写这个文件请求网关重启，长驻的 gateway 进程消费请求后在自己的快照里回 ACK——hermes yoooclaw lifecycle status 现在读的是这份持久化快照，按心跳新鲜度（默认 30 秒内视为存活）汇报 running/stale/stopped/mismatch，而不是「本地没有已注册的 transport 就判定 stopped」。Relay 握手也带上了 clientType/version/capabilities（如 agent-commands-v1）和稳定的 instanceId，方便排查多进程/多实例场景。

APP 适配器在连接期间跑着 watchdog：generation 变化时重建整组；Relay websocket 断连超过 YOOOCLAW_HERMES_WS_RESTART_AFTER（默认 30 秒）同样重建。YOOOCLAW_HERMES_LIFECYCLE_WATCH_INTERVAL 调整轮询间隔（默认 5 秒），失败恢复用指数退避，上限 YOOOCLAW_HERMES_LIFECYCLE_MAX_BACKOFF（默认 60 秒）。

存储接管失败（写者锁被别的进程占着）不会阻塞连接：聊天和查询照常，只是 ingest 走回退路径，原因会记在日志和 lifecycle status 里。

功能面

工具插件暴露的能力：通知、录音（recording_list 同样支持按录音时间的 from/to 过滤）、已同步网页（synced_web_page_list / search / path / storage_path，支持按 capturedAt 的 from/to 时间范围过滤——历史上这组工具叫 web_*，因为容易和 Hermes 内置的联网 web_search 混淆，已改名 synced_web_page_*）、图片、Relay、灯控、灯效规则 CRUD、状态报告（工具名仍是 daemon_status，daemonless 模式下报告存储接管与隧道状态）、doctor。APP 平台适配器直连 Relay，把既有的 OpenClaw 兼容 chat.send、chat.history、chat.abort、sessions.* RPC 帧翻译成 Hermes 消息和 APP 自有的会话状态。

常用生命周期相关环境变量

大部分场景不需要手动设置，遇到需要调整超时、关闭某个自动行为、或者本地开发调试时会用到：

环境变量	默认值	作用
YOOOCLAW_HERMES_CLAIM_STORAGE	开启	设为 0 关闭插件加载时接管本机存储；此时 ingest 走回退路径。未设置时沿用 YOOOCLAW_HERMES_AUTO_START_DAEMON 的取值（历史命名）。
YOOOCLAW_HERMES_DIRECT_INGEST	开启	设为 0 让 ingest 退回旧的 daemon HTTP 链路（kill switch）。
YOOOCLAW_HERMES_WS_RESTART_AFTER	30（秒）	Relay websocket 断连超过这个时长才触发整组重启。
YOOOCLAW_HERMES_LIFECYCLE_WATCH_INTERVAL	5（秒）	watchdog 轮询间隔。
YOOOCLAW_HERMES_LIFECYCLE_MAX_BACKOFF	60（秒）	恢复失败后指数退避的上限。
YOOOCLAW_HERMES_LIFECYCLE_MISMATCH_STREAK	2	状态连续判定为 mismatch 多少次才触发重启（避免探测抖动误杀）。
YOOOCLAW_CLI_PATH	未设置	显式指定 CLI 二进制路径，设置后完全跳过内置 CLI 的 PATH 注入逻辑，仅用于本地开发调试内置 CLI 之外的版本。
YOOOCLAW_HERMES_INSTALL_CLI	开启	设为 0 关闭插件加载时的 PATH 注入（shim 安装）。
YOOOCLAW_HERMES_INSTALL_SKILLS	开启	设为 0 关闭 skills 拷贝安装。
HERMES_PROFILE	未设置	Hermes 运行在具名 profile 下时指定该 profile 名，安装器/网关重启命令据此定位配置文件和拆分 lifecycle 快照；等价于安装器的 --hermes-profile。

下一步

• 调试与排错 —— 日志位置、常见故障处理。
• 独立 CLI —— 插件内置的就是这套 CLI；只读命令与存储布局完全共享。