命令参考

按 service 列出全部子命令。依赖标记：🟢 不需要 daemon · 🟡 需要 daemon 在跑 · 🔵 管理 daemon 自身。 所有命令支持全局 flags（--profile / --format / --quiet / --no-color），见命令体系与输出。

config — 配置管理 🟢

命令	说明
config init	交互式首次向导，生成 config.json + gateway token，打印手机端配置摘要，自动后台拉起 daemon 并注册开机自启动（macOS launchd / Linux systemd user service / Windows 任务计划，均为用户级登录自启动，不需要管理员权限）。支持 --non-interactive --from-file <config.json>（- 读 stdin）、--force 覆盖、--no-start（只注册自启动，不立即启动 daemon）、--no-autostart（立即启动 daemon 但不注册自启动）。
config show	显示当前 profile 配置（敏感字段遮罩）。--show-secrets 明文输出（需 TTY + 二次确认）。
config set <key> <value>	设置单个配置项，支持点号路径（daemon.port、notification.ignoredApps 用逗号分隔）。
config unset <key>	删除单个配置项。

yoooclaw config init
yoooclaw config set daemon.port 18365
yoooclaw config show --format json

cloud.host 是灯效 / 灯效规则 / ASR 共用的云端主机。留空时跟随 PHONE_NOTIFICATIONS_ENV；填了以它为准，Relay 隧道地址仍是内置默认形态时也从它派生，避免出现「隧道连着但灯效 401」的环境错配。完整优先级见 调试与排错：环境 / 主机对不上。

yoooclaw config set cloud.host openclaw-service.yoooclaw.com
yoooclaw config unset cloud.host    # 清掉后回到跟随环境变量

profile — 多 profile 管理 🟢

命令	说明
profile list	列出所有 profile，标注 active。
profile use <name>	切换 active profile。
profile create <name>	新建 profile（走 config init 向导，同样支持 --no-start/--no-autostart）。
profile delete <name>	删除 profile（不允许删 active，需 --yes）。

切换 / 删除 profile 时，CLI 会先停掉旧 profile 的 daemon（等待其 Relay 消费锁真正释放）再切换，如果旧 profile 是 OS 托管自启动则一并停掉对应 OS 服务；新 profile 原本在跑就随之重启。目的是防止旧 profile 的 daemon 继续消费账号的 Relay 流量、把生产通知/录音写进一个已经切走的测试 profile。

auth — 凭据与鉴权

命令	说明
auth set-api-key <key> 🟢	设置 / 轮换 account 级 default api-key（- 从 stdin 读，避免进 shell history）。已有 apiKeys[] 时只更新 default 条目；--keychain 写 OS keychain。
auth add-api-key <key> 🟢	新增一条带 label 的 api-key。--label <label> 必填（[a-z0-9-]{1,32}），--default 设为默认，--force 覆盖同名 label。
auth list-api-keys 🟢	列出 api-key 条目、mode、defaultLabel，key 自动遮罩。
auth remove-api-key <label> 🟢	删除指定 label 的 api-key。删掉 default 时，第一条剩余 key 自动成为新 default。
auth set-default-api-key <label> 🟢	切换 default api-key；云端 ASR fallback 和旧的单 key 调用会用它。
auth status 🟢	显示 api-key / gateway token 是否存在、来源（env/keychain/file）、mode、defaultLabel、daemon 是否可达。不调 daemon。key 形态可疑（不以 ock- 开头）时在 warnings 里点名到具体 label —— 这类 key 连 Relay 没问题，但灯效 / ASR 这类插件侧 API 会回 401。
auth token-rotate 🟡	生成新 gateway token 并写入（按 auth.tokenRef）。--length <n> 字节长度，默认 32。
auth check 🟡	端到端鉴权体检：用本地 token 调 daemon /daemon/status 验证一致性。

echo 'ock_xxx' | yoooclaw auth set-api-key -
yoooclaw auth add-api-key <ock_phone_a> --label phone-a --default
yoooclaw auth add-api-key <ock_phone_b> --label phone-b
yoooclaw auth list-api-keys
yoooclaw auth set-default-api-key phone-b
yoooclaw auth status --format json

多 key 存在共享 ~/.yoooclaw/credentials.json 的 apiKeys[]，跨 profile 生效。daemon 在跑时会通过文件 watch 热重载；如果 watch 不可靠，执行 yoooclaw daemon reload 主动重读凭据并增量刷新 Relay 隧道。每个 key label 会成为入站数据的 clientLabel，可用各查询命令的 --client <label> 过滤。

daemon — 守护进程管理 🔵

命令	说明
daemon start	启动 daemon，默认 fork 到后台 detach；自启已启用时改由系统用户服务托管启动。--bind <host>、--port <n>、--no-detach（systemd/launchd 用）、--log-level <level>。当前 profile 的写者锁被 Hermes 插件持有时拒绝启动，返回 YOOOCLAW_DAEMON_DISABLED_BY_PLUGIN（见下方写者锁）。
daemon stop	发送 SIGTERM，最多等 10s 后 SIGKILL。
daemon restart	等同 stop + start，保留原启动参数。
daemon reload	不重启进程，重读 api-key CredentialSet 并增量启动 / 停止 / 重连 Relay 隧道。
daemon status	打印 PID、监听地址、启动时间、relay 状态、灯效规则数、最近 ingest、内存占用，cloud 段（灯效 / ASR 实际打到哪台主机），以及 supervision 段（是否 OS 托管自启动、期望状态 vs 实际状态）。
daemon logs	跟踪 daemon 日志。-f, --follow、--lines <n>（默认 100）、--level <level>、--supervisor（改看 OS 服务本身的启动日志 ~/.yoooclaw/logs/daemon-supervisor.log，与常规 daemon 日志分开）、--diagnostics（一次汇总 daemon 日志、supervisor 日志、锁文件 / 进程身份、自启状态，Linux 上再附带本次开机的 systemd 服务状态与 journal）。--lines 取值 1–1000。
daemon autostart enable	注册用户级登录自启动（macOS launchd / Linux systemd user service / Windows 任务计划）并立即启动 daemon。--no-start 只注册不启动；--boot（仅 Linux）同时为当前系统用户开启 linger，支持无人登录时随开机启动。
daemon autostart disable	停止 daemon 并移除自启动注册。
daemon autostart status	显示期望状态 vs OS 服务实际状态，检测漂移（比如升级后可执行文件路径变了、可执行文件已不存在、或 unit 未 enable）。Linux 上额外返回 linger、unitEnabled、bootEnabled（两者都为真才算具备开机自启条件）和 bootWarning。

yoooclaw daemon start
yoooclaw daemon status --format json
yoooclaw daemon logs --lines 200 --level error
yoooclaw daemon logs --supervisor         # 看 OS 服务启动日志，不是 daemon 自身日志
yoooclaw daemon logs --diagnostics --lines 100   # 自启 / 重载问题一次汇总
yoooclaw daemon autostart enable --boot   # Linux：无人登录也随开机启动
yoooclaw daemon autostart status --format json

daemon start / daemon restart 会自动识别当前 daemon 是否由 OS 服务托管，是的话改走 supervisor 重启而不是裸进程 spawn；daemon doctor 新增 daemon-autostart 自检项（--fix 可自动修复可执行文件路径漂移等问题）；profile use 切换 profile、uninstall 卸载 CLI 时都会先处理自启动注册，见上方 profile 与下方 维护命令。自启动注册失败或状态异常时返回 YOOOCLAW_AUTOSTART_UNAVAILABLE；如果是在 autostart enable 过程中失败、而 daemon 原本没在跑，CLI 会先把 standalone daemon 拉起来保证连接可用，再报告「已恢复 daemon 但尚未配置登录自启」，退出受限的 Agent 环境后重试即可。

几条与自启相关的行为：

• 关闭自启不会关 linger：autostart disable 只移除本应用的服务，--boot 开启的 linger 保留，以免影响同一用户的其他服务。doctor 会在期望启用但不具备开机自启条件时给出 bootWarning。
• 旧版本升级自动补注册：早期版本没有持久化的自启偏好。升级（install.sh / install.ps1）后会为已初始化的 active profile 补注册自启——即使当时 daemon 恰好停着；用户明确执行过 autostart disable、或 Hermes 插件正持有存储所有权时不会被覆盖。
• 诊断日志：service.entry / daemon.ready 标明版本、PID、profile、配置路径与实际监听端口；status.observed / reload.request 区分锁不存在、无法读取、进程已死、可执行文件或命令行不匹配；credentials.reload_applied 记录重载前后的来源、label、脱敏 SHA-256 指纹与隧道增删结果（只代表本地已应用，连上要看随后的 connected）。日志不输出完整 key、gateway token 或凭据文件内容。连 service.entry 都没有时，优先看 --diagnostics 汇总里的 systemd / journal——进程没起来时它自己写不了日志。
• Linux 安装器保护：在 Agent shell 里升级时如果访问不到当前用户的 systemd（缺登录会话环境），安装器会先尝试从 /run/user/<uid> 恢复；仍不行就保留旧 daemon 和旧二进制、停止更新，而不是停掉 daemon 后无法再拉起。内部还有一个隐藏命令 daemon run-service，是 OS 服务定义自身调用的入口，不用于日常手动执行。

daemon status 的 cloud 段回答「配置写着 A 为什么打到 B」：

{ "cloud": { "env": "production", "host": "openclaw-service.yoooclaw.com",
             "source": "cloud.host",
             "lightApiUrl": "https://…", "lightRuleApi": "https://…" } }

source 是 env / cloud.host / relay.url / default 四选一，直接指出这台主机是谁定的。

写者锁与 Hermes 插件模式

~/.yoooclaw/profiles/<profile>/writer.lock 是同一 profile 存储的单写者互斥锁（OS 建议锁，进程死亡自动释放）。Hermes 插件以 daemonless 模式运行时由插件进程持有，此时 daemon start / daemon run-foreground 会被拒绝：

{ "ok": false, "error": { "code": "YOOOCLAW_DAEMON_DISABLED_BY_PLUGIN",
    "message": "storage is owned by hermes-plugin (pid …)" } }

只读命令（notification *、recording list/status/events、image *、log）不碰这把锁，插件模式下照常可用。停用插件后锁自动释放，daemon start 即回到独立模式，数据文件不需要迁移。--ingress proxied 是豁免的 —— 那是宿主自己托管的 daemon。

Windows 上探测这把锁失败（比如权限错误）时，行为是 fail-closed：daemon start / daemon run-foreground 会直接拒绝启动并返回 YOOOCLAW_STORAGE_UNAVAILABLE，而不是假定锁未持有就继续跑——避免和正在跑的 Hermes 插件同时写同一份存储。

owner — Relay / 存储所有权切换 🟡

CLI 与 Hermes 插件互斥地共享同一份 profile 存储和 Relay 隧道，谁持有写者锁谁就是「owner」。多数情况下装哪个用哪个，不需要手动切换；只有当同一台机器上 CLI 和 Hermes 插件都装了、需要显式把 Relay 所有权从插件转交回独立 CLI 时才用这组命令。

命令	说明
owner activate cli	停用 Hermes 的 yoooclaw / yoooclaw_app 插件（--hermes-profile <name> 指定 Hermes profile），必要时重启 Hermes gateway 促使其释放写者锁 / Relay 连接，等待释放后启动独立 CLI daemon 接管。--no-start 只完成移交，不启动 daemon。自启偏好未被显式关闭时，接管后改由 OS 用户服务托管启动（返回 supervised: true）。账号级 Relay 消费锁（standalone-relay.flock）仍被另一个独立 daemon 占着时直接拒绝（YOOOCLAW_DAEMON_ALREADY_RUNNING），需先停掉那个进程或用户服务。

install.sh / install.ps1 升级 CLI 时默认保留升级前的所有权归属——如果之前是插件持锁，升级后还是插件持锁；只有显式传 --activate / -Activate（或设置环境变量 YOOOCLAW_ACTIVATE_OWNER=cli）才会在装完后把所有权转交给独立 CLI，同样支持 --hermes-profile <name>。升级过程中如果本来就有独立 CLI daemon 在跑，安装器会先停掉、换完二进制后按原 profile 重新拉起（失败自动回滚重启），不会因为一次升级悄悄丢失 Relay 所有权。

yoooclaw owner activate cli
yoooclaw owner activate cli --hermes-profile work --no-start

notification — 通知查询 🟢

命令	说明
notification search	按条件查询，时间倒序。--from/--to <iso8601>、--app、--sender、--conversation-type group|private、--keyword、--client <label>、--limit（默认 100）。
notification summary	聚合统计 + 样例摘要，供 Agent 总结。支持 --client <label>，追加 --sample <n>（默认 30）、--top <n>（默认 10）。显式传 --limit 时只聚合最近 N 条。
notification summary-job	分片通知总结任务：大批量通知切片 → 逐片总结 → 合并结果。子命令见下方 summary-job。
notification stats	按维度聚合。--from/--to <YYYY-MM-DD>、--app、--client <label>、--dim date|app|sender|hour|client|all。
notification storage-path	打印 notifications 目录绝对路径。
notification +today	今日通知。支持 --client <label>。
notification +recent	最近 1 小时通知。支持 --client <label>。
notification +unread	（预留）未读通知，需先落地已读状态模型，当前返回 YOOOCLAW_NOT_IMPLEMENTED。

--app 支持中英文别名：微信/wechat、飞书/feishu/lark、钉钉/dingtalk、企业微信/wecom、qq 等。

yoooclaw notification search --app 微信 --keyword 开会 --format ndjson
yoooclaw notification summary --top 10 --format json

notification summary-job — 分片通知总结 🟢

供大批量通知的「切片 → 逐片总结 → 合并」工作流。summary 适合小批量一次性聚合；通知条数很多、需要逐片喂给模型时走 summary-job：create 建任务并切片，next 领一个待总结分片，commit 回填该片摘要，全部完成后 result 合并出最终结果。也可用 run 跳过模型、用抽取式摘要自动跑完。

命令	说明
notification summary-job create	创建任务并按查询切片。复用全部 notification 查询 flags（--from/--to、--app、--sender、--conversation-type、--keyword、--client、--limit，--limit 默认 1000），加 --chunk-size <n>（每片条数，默认 150）、--max-content <n>（单条标题/正文最大字数，默认 120）。
notification summary-job status <id>	查看任务状态与各分片进度。
notification summary-job next <id>	领取或重试下一个待总结分片，返回分片内容与 chunkId。
notification summary-job commit <id>	回填分片摘要并标记该片完成。--chunk-id <id>（必填，来自 next），--summary <text> 或 --summary-file <path> 二选一传入摘要。
notification summary-job run <id>	用抽取式摘要自动处理待总结分片（无需模型）。--max-chunks <n>（本次最多处理片数，默认 20）、--include-result（完成时输出 markdown 结果）。
notification summary-job result <id>	合并已提交的分片摘要并返回最终结果。
notification summary-job cancel <id>	取消任务（保留已落盘的分片与摘要）。

# Agent 驱动：建任务 → 循环 next/commit → 合并
JOB=$(yoooclaw notification summary-job create --app 微信 --limit 2000 --format json)
yoooclaw notification summary-job next <id>     # 取一片，喂给模型总结
yoooclaw notification summary-job commit <id> --chunk-id <chunk> --summary "本片摘要…"
yoooclaw notification summary-job result <id> --format json

# 无模型场景：抽取式自动跑完
yoooclaw notification summary-job run <id> --include-result --format json

sync — 通知同步给记忆系统 🟢

供外部记忆系统按批次拉取通知的 checkpoint 协议。scan / next 共享一组日期范围 flags：--all（处理 checkpoint 之后所有日期）、--date <YYYY-MM-DD>（仅指定日期）、--from-date / --to-date（区间）；都不传时默认只处理本地当天。

命令	说明
sync scan	扫描未处理通知，默认只返回本地当天待同步摘要；配合范围 flags 扩大扫描范围。
sync next	通用批次迭代器：返回范围内下一批未处理通知（≤100 条）及 commitCommand，全部处理完返回 done=true。配合范围 flags 使用。
sync fetch --date <YYYY-MM-DD>	获取指定日期未处理通知详情。--max-end-index <n> 用于幂等切片。
sync commit --date <YYYY-MM-DD>	标记当前批次处理完成。--end-index <n> 精确提交。

经 transfer import 迁入的历史通知带 transfer.memoryPolicy="skip-history" 标记，不会进入记忆同步：scan / next / fetch 的计数和返回列表都会过滤掉它们，但它们仍占 checkpoint 位置，endIndex 按原始下标推进；某一批全是迁入条目时返回 skippedOnly: true，照常 commit 即可跳过。

# 迭代器写法：next 直接返回下一批 + 提交命令，处理完 done=true
yoooclaw sync next --all --format json
yoooclaw sync commit --date 2026-06-17 --end-index 42

recording — 录音管理

recording 现在统一了两个数据来源：smart_hardware（手机端录音硬件上报的转写，原有链路）和 capture_app（桌面「YoooClaw Capture」应用录的会议录音，落在 voice/recordings-jsonl/）。查询类命令都新增了 --source all|capture_app|smart_hardware 过滤（默认 all），返回条目里带 source_type / source_name 标出来源，以及 has_audio / has_transcript / has_summary / missing_artifacts 指出这条记录实际有哪些产物。两个来源的转写结构不同：hardware 是扁平转写，Capture 是 transcripts[].sentences[]（带 begin_time/end_time/speaker_id）；recording events 只覆盖 hardware 的状态事件流，Capture 没有对应事件。

命令	说明
recording list 🟢	列出所有录音，按有效录音时间倒序。--source all|capture_app|smart_hardware，--status <status>（仅对 hardware 来源有意义），--client <label>（按 api-key label 过滤，只影响 hardware 来源，Capture 不受影响），--from <ISO8601|YYYY-MM-DD>（含）/ --to <ISO8601|YYYY-MM-DD>（不含）按录音时间过滤。范围内没有结果时返回空列表，不会回退到「最新一条」。
recording status <id> 🟢	单条录音详情（metadata、文件路径、ASR 状态、错误）。同一 ID 在两个来源都存在时必须传 --source 消歧，否则返回 NOT_FOUND。
recording storage-path 🟢	打印录音存储目录绝对路径。
recording setup-asr 🟢	配置 ASR 转写参数。当前可用模式是 --mode api；local 仍保留在 flag/schema 中用于兼容旧请求，但 Go beta 会拒绝本地 Whisper 模式。支持 --api-key、--endpoint、--language、--non-interactive。
recording events 🟢	查询 hardware 来源的录音状态事件流（Capture 无此事件流）。--id <recordingId>、--since <10m|1h|24h>、--watch、--limit <n>（默认 200）。
recording +latest 🟢	展示最新一条录音详情（跨两个来源取最新）。
recording +today 🟢	列出本地自然日内的今日录音。支持 --source、--status、--client <label>。

独立 CLI 的 daemon 经 recordings.result.write 接收 App / 云端写入的 hardware 来源转写与总结（可选带 ossUrl 时后台下载音频），落在当前 profile 的 recordings/。本机重新转写经 recordings.retranscribe 触发：setup-asr 写出的 asr-config.json 与请求级 asr 参数兼容；当 mode=api 且未写入 apiKey 时，会回退到 account 级 ock- key。当前 Go beta 只支持 api / model-proxy ASR。

录音时间以结果里的实际录制时间为准（而非转写生成时间），跨时区上报也会解析成真实时间点再排序，避免「最新」选错。duration_sec 是整数秒；duration_display 是配套的人读格式（如 16s、1m 16s、1h 1m 1s）；Capture 来源额外带毫秒精度的 duration_ms。音频下载完成后 file_size_display 用 Android Formatter.formatShortFileSize() 兼容格式给出大小；已废弃的 file_size_bytes 字段不再输出。transcripts/ 与 summaries/ 下的文件名约定改成了 <YYYYMMDDHH>_<标题>_<id>.md（时间+标题在前，方便按文件名排序），升级前写入的旧文件保留原文件名，不会批量迁移。音频下载复用阿里云 OSS SDK v2 的分片下载（8 MiB 分片、并发 3、Range + ETag 校验），网络抖动时在本次下载流程内从断点继续，而不是删掉片段从头重下；单个音频上限 5 GiB，进程重启后的恢复仍由录音恢复流程重新发起下载。recordings.result.write 新增可选的 ossTaskId（上传服务返回的任务 ID，≤256 字符，必须同时带音频 URL；与 transcript.source.taskId 这个 ASR 任务 ID 不是一回事）：下载遇到 403 时 daemon 会用发起写入的那把 api-key 调云端换一个新的签名 URL 再试，api-key 不会发给 OSS。它会存进录音索引，并在写入响应、recording list/status、recording.status 事件里回显（无值时省略）；新写入不带 ossTaskId 时会清掉旧值，避免拿旧任务刷新新地址。经 /gateway/recordings.* 写入的录音现在会正确按发起写入的 api-key 打上 clientLabel（此前误落到 "default"）；对应地，读侧（recordings.list、recording status/events、Relay 回推的 recording.status 事件）也按客户端隔离——通过 Relay 隧道或某个 api-key 接入的客户端只能看到/操作自己名下的录音，本机 loopback / gateway token 请求不受限；没打标或历史遗留的 default 条目对所有客户端可见（升级兼容）。synced-web-page 与 /web-pages/index、/web-pages/status 同样按这套鉴权上下文做了隔离。

yoooclaw recording setup-asr --mode api --language auto --non-interactive
yoooclaw recording events --since 1h --limit 50 --format json
yoooclaw recording events --id 2026-03-23_14-32 --watch
yoooclaw recording list --from 2026-07-01 --to 2026-08-01 --format json
yoooclaw recording +today --source capture_app --format table

voice — 语音输入（口述）历史查询 🟢

查询本机保存的语音输入 / 口述历史：每次口述最终上屏的文本、输入到了哪个 App、识别语言与状态，以及可选的本地音频。纯读当前 profile 的 voice/audio-jsonl/YYYY-MM-DD.jsonl（按天分片），不需要 daemon，也不会访问另一台电脑的数据。注意它不是会议录音——会议录音（YoooClaw Capture / 智能硬件）走上面的 recording *。

命令	说明
voice list	按时间倒序列出口述历史。不带任何筛选条件时默认只看滚动最近 72 小时（JSON 里会明确提示），--all 显式查全部历史；没有默认条数上限，--limit 可限制。过滤：--from / --to（带时区 ISO 8601 或 YYYY-MM-DD，左闭右开）、--app <app_id|app_name>（精确匹配，不做模糊别名）、--status、--language、--has-audio（只要本地确有音频文件的记录）。
voice search <keyword>	在最终上屏文本里搜索；不带时间过滤时搜全部已保存历史。按目标 App 过滤用 --app，不要把 App 名当关键词。
voice show <id>	单条完整记录。id / voice_id 是稳定字符串，不是数据库行号；音频缺失不影响文本可用。
voice apps	列出出现过的目标 App，默认只看最近 7 天（--all 看全部历史），按 app_id 去重，同时返回 app_id 与 app_name。
voice +latest	全历史中最新一条。
voice +today	本地自然日内的口述历史。
voice storage-path	打印口述历史 JSONL 与产物目录路径。

yoooclaw voice apps --format json               # 先拿 app_id
yoooclaw voice list --app com.microsoft.VSCode --format json
yoooclaw voice list --from 2026-10-09T09:00:00+08:00 --to 2026-10-09T10:00:00+08:00
yoooclaw voice search "项目" --app com.microsoft.VSCode

问「我刚才说了什么」这类请求时，Agent 应显式传最近一小时的 --from/--to，不要拿更早的「最新一条」顶替。保存下来的口述历史也不等于真实使用量，不适合做统计口径——voice stats 已在 0.9.0 移除且无替代；不会回退读取旧版的 voice.sqlite3。

image — 图片管理 🟢

图片由 daemon 后台从 OSS 下载到 images/files/；查询命令纯读 images/index.json。

命令	说明
image list	列出图片。--status syncing|synced|sync_failed、--app、--from/--to <iso8601>、--client <label>、--limit。
image status <id>	单张图片详情。
image path <id>	打印本地文件绝对路径（供 Agent 喂多模态模型）。--thumbnail 返回缩略图。未下载完成返回 YOOOCLAW_IMAGE_NOT_READY。
image storage-path	打印图片存储目录绝对路径。
image +latest	展示最新一张图片详情。

synced-web-page — 已同步网页查询 🟢

浏览器扩展抓取的网页正文经 Relay 投递到 daemon（POST /web-pages），落成 Markdown + 元数据；本组命令纯读该本地索引，不访问互联网。历史上叫 web，命名容易和「联网搜索」混淆，已改名为 synced-web-page。

命令	说明
synced-web-page list	按抓取时间（capturedAt）倒序列出所有已同步网页。--from <ISO8601>（含）/ --to <ISO8601>（不含）按抓取时间过滤，需带时区。
synced-web-page search <keyword>	在标题、站点名、URL、canonical URL 和 Markdown 正文中搜索。--limit <n>（默认 20）。
synced-web-page path <urlHash>	根据 URL 哈希（支持前缀，唯一匹配即可）打印网页 Markdown 文件绝对路径。
synced-web-page storage-path	打印网页存储目录绝对路径。

yoooclaw synced-web-page list --from 2026-07-29T00:00:00+08:00 --format json
yoooclaw synced-web-page search "JavaScript" --limit 20
yoooclaw synced-web-page path <urlHash>

list 每条返回 urlHash、title、siteName、canonicalUrl、capturedAt、firstCapturedAt（首次抓取时间）、captureCount（重复抓取次数）、relativePath、hasArchive、clientLabel。同一 URL 被重复收藏只会保留一条、累加 captureCount，不会重复落盘。

light — 灯效硬件控制 🟡

命令	说明
light send	发送灯效指令。--segments <json>（灯效参数）、--preset <name>（内置预设，如 red-steady / red-strobe-3 / green-steady）或 --rule <name>（已保存的 lightrule）三选一；--repeat、--repeat-times <n>；--reason（亮灯原因 / 推送正文）、--title（推送标题，未传时按 reason 或灯效生成）。

• 只显示文字：带屏幕的二代硬件会把这次下发的 title / reason 显示在屏上。只传 --title / --reason、不传灯效参数时，按「纯文字屏幕展示」处理：下发一段 8 秒、亮度 0 的显式关灯段，不循环（可能会关掉当前正在亮的灯效）。
• 段参数默认值：一次性灯效里省略的 brightness 默认 128、color 默认白色 {r:255,g:255,b:255}；显式写出的 null / 0 / 非法值仍按严格校验处理，已保存规则不受影响。
• light +blink 已移除，连通性测试改用 yoooclaw light send --preset red-strobe-3。
• 独立 daemon 暂无连接的灯效设备会话时，命令返回 accepted: true, delivered: false（需手机端在线 / relay）。

yoooclaw light send --preset green-steady --title "任务完成" --reason "构建已通过"
yoooclaw light send --title "会议提醒" --reason "15:00 产品评审"   # 只在屏幕上显示文字

lightrule — 灯效规则管理 🟡

规则由云端 Notification Intelligence 服务负责编译、评估和触发；lightrule 管理命令直连该云端 API（而非本地 daemon），需先 yc auth set-api-key <apiKey>。命中的云端主机与灯效、ASR 一致，由 cloud.host 决定。

命令	说明
lightrule list	列出所有规则及状态。
lightrule show <id>	单条规则详情。
lightrule create	通过云端 Agent 由自然语言编译生成规则。--intent <text> 必填；文本必须包含通知/消息/来电等触发信号，否则报错——一次性亮灯请用 light send。
lightrule update <id>	更新现有规则，未指定字段保留原值。--intent（重新编译替换整条规则，不可与其他字段混用）或 --title/--description/--segments <json>/--repeat/--repeat-times <n>。启停用 enable / disable 子命令。
lightrule delete <id>	删除规则（--yes 跳过确认）。
lightrule enable <id> / disable <id>	启用 / 停用单条规则。
lightrule +on / +off	启用 / 停用所有规则。

yoooclaw lightrule create --intent "微信来消息时亮红灯 3 次"
yoooclaw lightrule update <id> --intent "改成绿灯呼吸"
yoooclaw lightrule list --format json

灯效 / 灯效规则报 401 Invalid plugin API Key 时，错误信息会追加当前环境、遮罩后的 key 和下一步动作。这类 401 的实际成因几乎都是 key 与环境不匹配（api-key 分环境签发），而不是 key 本身失效 —— 对照 daemon status 的 cloud.env 与手机 App 所在环境即可确认。

todo — 云端待办 🟢

直接管理 App 里的云端待办，不需要 daemon；凭据与环境沿用已有的 account api-key 和 cloud.host。建议加 --format json 获取结构化结果。

命令	说明
todo list	查询待办。--is-done true|false|null、--start-time / --end-time（带时区 ISO 或 null）、--keyword、--page-no、--page-size。默认查询不限时间的未完成事项。
todo get <todoId>	单条详情。
todo create	新建待办。--title、--due-at（开始时间：定时用带偏移的 ISO，全天用 YYYY-MM-DD，无时间传 null）、--is-full-day true|false（未传时按 --due-at 格式推断）。返回 requestKey。
todo update <todoId>	修改 --title / --due-at / --is-full-day；--is-done true 完成，--is-done false 恢复为未完成。
todo delete <todoId...>	删除指定待办，必须带 --confirmed。

所有子命令都支持 --json-file <file>（- 读 stdin）传一个 JSON 对象，不能与字段参数混用。

yc --format json todo list --is-done false
yc --format json todo create --title '产品评审' --due-at '2026-10-10T15:00:00+08:00' --is-full-day false
yc --format json todo update 841 --is-done true
yc --format json todo delete 841 --confirmed

• 幂等重放：创建结果不确定（超时、网络中断）时，只能用返回的 --request-key <key> 加相同参数重放，避免重复创建。
• 部分成功：组合更新等多阶段操作部分成功时，返回 ok: false、分阶段结果和非零退出码，不会被当成整体成功。
• Agent 查询「今天」时应显式传当地日界的 --start-time / --end-time；配套的 yoooclaw-todo Skill 规定了自然语言路由、创建后的查看入口（App 首页待办卡片 / 待办列表）和删除前的确认。

monitor — 定时通知监控任务 🟡

cron 表达式驱动的定时任务定义（当前持久化定义与启用状态）。

命令	说明
monitor list	列出所有监控任务。
monitor show <name>	任务详情。
monitor create <name>	创建任务。--description、--match-rules <json>、--schedule <cron> 均必填。
monitor delete <name>	删除任务（--yes）。
monitor enable <name> / disable <name>	启用 / 暂停任务。

tunnel — Relay 隧道 🟡

命令	说明
tunnel status	查询 Relay 连接状态（connected / reconnectAttempt / 断开原因 / stale + currentUrl + expectedUrl）。多 key 时返回 tunnels[]；--client <label> 只看指定隧道。详见 调试与排错。
tunnel reconnect	强制断开重连。--client <label> 只重连指定 label；不传则重连全部隧道。
tunnel +test	端到端联通性自检：daemon 通过本地回环给自己发一条 echo 通知，验证 ingest + 鉴权链路。--client <label> 用指定 api-key 写入。

log — 日志检索 🟢

命令	说明
log [keyword]	搜索 daemon 日志。--from/--to <YYYY-MM-DD>、--limit（默认 50）、--level。
log +errors	昨天起的 error 级日志。

gateway — 协议自检 🟡

命令	说明
gateway test	模拟手机端调 daemon /notifications，验证连通 / 鉴权。--from-phone-ip <ip>、--via-relay。

api — Raw HTTP escape hatch 🟡

yoooclaw api GET /daemon/status
yoooclaw api POST /images --data @img.json
yoooclaw api POST /light/send --data '{"preset":"red-strobe-3"}'

--data 支持 @filename（读文件）、-（读 stdin）或内联 JSON；--header <key:value> 可重复。

Raw API 会尽量保留 daemon 的原始 HTTP 语义；脚本消费时请同时检查返回体 ok 与 HTTP status，不要只依赖进程退出码。

skills — Agent 技能管理 🟢

把随包发布的 SKILL.md 安装到 Agent 的 skills 发现目录，让 Agent 自己驱动 yoooclaw 命令。详见 Agent Skill。

命令	说明
skills list	列出随 CLI 发布的内置 Skill 及其触发说明。
skills targets	列出支持的 Agent skills 目录和自动探测结果。
skills install	安装到 Agent skills 目录。--agent <agent>（auto / claude / codex / custom，默认 auto）、--target <dir>、--copy、--force。

yoooclaw skills list
yoooclaw skills targets
yoooclaw skills install            # 自动探测唯一 Agent 后安装
yoooclaw skills install --agent codex

transfer — 数据迁移

在两个环境之间搬运本地数据（换电脑、重装、另一个 profile，或在独立 CLI 与 OpenClaw 插件之间）。可迁移通知、录音（转写 / 摘要）、已同步网页，可选音频 / 图片 / 网页 HTML 存档；不迁移记忆、凭据和配置。包格式与 OpenClaw 插件的 ntf transfer 相同（schema 1），数据包和能力文件双向通用。

命令	说明
transfer export 🟢	导出数据包，直接读本地文件，不需要 daemon。范围：--include notifications,recordings,web-pages,images（缺省前三类）、--from / --to（必须带时区，左闭右开）、--with-audio / --with-images / --with-html；--dry-run 只预览条数与体积；--target-capabilities <file> 按目标端能力预检。--via oss 打包成 tar.gz 上传云端并返回迁移 taskId；--via local（默认）配合 --out <新路径> 落本地：以 .tar.gz / .tgz 结尾生成单个压缩包，否则生成包目录。
transfer import 🟡	在目标 daemon 内执行导入。--task <taskId> 自动换取下载地址、下载、校验并导入（--dry-run 只下载预览）；--file <包> 只暂存 + 校验 + 预览，从不合并，返回 localTransferId / planId / 各动作计数和 nextCommand；--local <id> --plan <id> 执行预览出的计划，--resume 续跑中断或 PARTIAL 的导入。
transfer capabilities 🟡	读取目标端（运行中的 daemon）的迁移能力，--out 保存成文件交给源端 export --target-capabilities。
transfer complete	上传字节已发完但「确认完成」失败时，用报错里给出的 --task <taskId> --object-key <objectKey> 重试确认；不会重新上传，也不会新建任务。

# 默认：云端中转（源端）
yoooclaw transfer export --dry-run --format json
yoooclaw transfer export --via oss --format json           # → taskId
# 目标端
yoooclaw transfer import --task <taskId> --format json

# 离线：本地包
yoooclaw transfer export --out ~/yoooclaw-pkg.tar.gz --with-audio
yoooclaw transfer import --file ~/yoooclaw-pkg.tar.gz
yoooclaw transfer import --local <localTransferId> --plan <planId>

几条关键约束：

• 云端中转使用当前 profile 配置的 account api-key 与云端环境，源端和目标端的 api-key 必须属于同一账号、同一环境。上传用阿里云 OSS SDK 分片续传，STS 凭据会在上传过程中自动续期；下载带 Range 断点恢复。续传只在本次命令内有效，进程重启后不恢复。创建任务消耗配额（每天最多 3 次），失败不要反复重跑 export，确认失败用 transfer complete。
• 云端包由服务端维护：上传完成 24 小时后自动删除，与是否导入无关；CLI 不提供云端删除命令。签名下载地址只在命令内部使用，不会出现在输出里。
• 隐私：迁移包是明文（tar.gz 只是打包，不是加密），任务 ID 与数据包都应妥善保管，不要分享给他人。
• 目标端不覆盖：目标已有记录永不覆盖，内容不同的记录报 conflict；迁入的通知按目标时区重新分桶，并带 skip-history 标记不进入记忆同步（见 sync）。导入成功后自动清理本地暂存；PARTIAL 或失败时在 <profile>/transfers/ 下保留暂存包与 report.json 供 --resume，只预览未导入的暂存 7 天后清理。
• 源端只写一个标记：导出会在每个源数据目录写一个 .transfer-origin，用于多跳迁移保留原始来源身份；--dry-run 不写，源数据不会被修改或删除。
• 兼容性：低于 CLI 0.12.0 / 插件 1.18.0 的目标端只能导入包目录，带 --target-capabilities 导出 tar.gz 会报 YOOOCLAW_TRANSFER_ARCHIVE_UNSUPPORTED_BY_TARGET。daemon 比 CLI 旧时报 YOOOCLAW_TRANSFER_UNSUPPORTED，daemon restart 即可。范围过大会在导出时就拒绝（YOOOCLAW_TRANSFER_PACKAGE_TOO_MANY_RECORDS / _MANIFEST_TOO_LARGE），用 --include / --from / --to 缩小。

配套的 yoooclaw-data-transfer Skill 会把导出结果整理成「隐私提醒 + 一句可复制的导入话术」（帮我导入这份迁移数据：<taskId>），用户只需把这句话发给目标端的 Agent。

维护命令

命令	说明
migrate from-openclaw 🟢	把 ~/.openclaw/plugins/phone-notifications/ 的通知 / 录音 / 规则 / 图片与 api-key 迁移到 ~/.yoooclaw/，迁移前自动备份。--dry-run、--source <path>。
update self 🟢	查 npm registry 比对版本并提示（不自动更新）。响应里 dist 标识当前安装来源（npm / native），command 给出对应的升级命令：npm 形态返回 npm update -g @yoooclaw/cli；原生二进制在 macOS / Linux 返回 curl ... install.sh | sh -s -- --version <v> --force，在 Windows 返回 install.ps1 ... -Version <v> -Force。--beta、--json。
doctor 🟢/🟡	环境自检：Go runtime、目录权限、keychain、daemon（锁文件存在但进程不存在或身份校验不匹配时报 warn）、daemon-autostart（服务缺失 / 未 enable / 指向旧二进制可 --fix；Linux 不具备开机自启条件时给出 bootWarning）、配置。--json、--fix。网络类自检（relay / OSS）交给 gateway test / tunnel +test。
uninstall 🔵	卸载 CLI：先移除 OS 级开机自启动注册（见 daemon autostart），停掉所有 profile 的 daemon，删除二进制（yoooclaw 及 yc）与配置（account / profile 的 config.json、credentials.json、active-profile、daemon.lock），默认保留通知 / 录音 / 图片等数据。--data 连同数据一并删除（清空 ~/.yoooclaw）；--yes 跳过确认。Windows 原生安装会一并清理用户 PATH 条目与安装目录（含跨盘安装），删除失败时报错而不是静默跳过。npm 安装形态无法自删二进制，会提示运行 npm uninstall -g @yoooclaw/cli。

yoooclaw migrate from-openclaw --dry-run
yoooclaw doctor --format json
yoooclaw uninstall              # 停 daemon + 删二进制与配置，保留数据
yoooclaw uninstall --data --yes # 连数据一起清空，免确认