独立 CLI

@yoooclaw/cli 是独立运行的 yoooclaw / yc 命令行 —— 自带后台守护进程（daemon），不依赖 openclaw 客户端在线。设计对齐飞书 lark-cli：Service-oriented 命令树、三层命令体系（Shortcuts / Service Commands / Raw API）、统一 --format、Agent-Native。

当前状态：命令全部可用

全部 service 命令已落地：本地查询类（🟢，纯读磁盘）开箱即用；守护进程类（🔵）与需 daemon 在跑的控制类（🟡）通过本地 HTTP RPC 协作。手机端可以经 yoooclaw 托管 Relay 进入本机 daemon；Relay 不可用时仍可用 cloudflared / tailscale serve 反代本地 HTTP server 作为兜底。

安装

两种分发渠道，功能完全一致，按是否方便装 Node 选择。npm 包是极薄 Node launcher，安装时通过 optionalDependencies 拉取当前平台的 Go 原生二进制；原生二进制渠道则直接下载同一套 Go binary。

平台支持

npm 渠道支持 darwin/linux 的 x64+arm64 与 win32-x64（launcher 需 Node ≥ 18）。原生直装支持 darwin/linux 的 x64+arm64（install.sh）与 Windows x64（install.ps1，Windows on ARM 经系统 x64 兼容层运行）。Windows 上有两点差异：凭据以明文存放在 ~/.yoooclaw/credentials.json（无系统 keychain 加固，yoooclaw doctor 会标记为 skip 并提示），yoooclaw daemon stop 经 HTTP /daemon/stop 优雅退出而非 POSIX 信号。详见 存储与目录。

A. npm（薄 Node launcher + 平台 Go 二进制）

免安装（npx，每次拉最新版）：

npx @yoooclaw/cli --help          # 主命令
npx @yoooclaw/cli notification +today

全局安装（提供 yoooclaw / yc 两个命令）：

npm i -g @yoooclaw/cli
yoooclaw --help        # 主命令
yc --help              # 等价短 alias

npx @yoooclaw/cli 始终调用 yoooclaw 入口（yoooclaw 与 yc 指向同一可执行文件）。

B. 原生二进制（无需 Node）

单文件 Go 可执行，冷启动和资源占用都比旧 TS/Bun 形态更轻。

macOS / Linux：

# 自动检测平台、下载、校验 sha256、写入 ~/.local/bin（阿里云 OSS 分发，国内直连）
curl -fsSL https://artifact.yoooclaw.com/cli/install.sh | sh

# 指定版本 / 安装目录 / 覆盖（预发布版只能这样显式指定版本号安装）
curl -fsSL https://artifact.yoooclaw.com/cli/install.sh \
  | sh -s -- --version 0.12.0 --dir ~/bin --force

# 顺带把安装目录写进 shell 配置文件（PATH）
curl -fsSL https://artifact.yoooclaw.com/cli/install.sh | sh -s -- --modify-path

安装目录默认优先 ~/.local/bin，其次是可写的 /usr/local/bin。安装器默认不会修改任何 shell 配置文件，只装二进制；要让新开终端直接能跑 yoooclaw，需要显式加 --modify-path——此时才会按登录 shell 幂等地把安装目录写进对应配置文件（zsh → .zshrc、bash → .bashrc / .bash_profile、fish → config.fish、POSIX shell → .profile），配置发生变更时会提示重开终端或 source 一次。不传 --modify-path 就需要自己把安装目录加进 PATH；--no-modify-path 仍然接受，只为兼容旧调用，效果等同于默认行为（不修改）。

不便访问 OSS 时也可用 GitHub 源脚本（从 GitHub Release 下载，参数相同）：

curl -fsSL https://raw.githubusercontent.com/YoooClaw/cli/master/scripts/install.sh | sh

安装器不再有 --beta

不带 --version 时安装器只解析正式版；--beta 已移除，传了会直接报错并提示改用 --version <预发布版本号>。预发布版发布时也不会再覆盖 live 安装脚本和 latest 标记，所以默认装到的一定是正式版。

安装器会先用完整路径验证二进制可运行，再检查安装时继承的 PATH 能否按命令名找到它，并打印一条不依赖 PATH 的完整路径调用方式。Linux 上如果 Agent 里报 yoooclaw: command not found、普通终端却能用：Agent / 服务的非交互式 bash -c 通常不读 .profile / .bashrc，--modify-path 和重开终端都不一定能修好——请在 Agent runner / 服务的启动环境里把安装目录加进 PATH 并重启对应进程，或直接用安装器输出的完整路径（例如 /home/admin/.local/bin/yoooclaw）。

Windows（PowerShell 5.1+，无需 Node/npm、无需管理员权限）：

irm https://artifact.yoooclaw.com/cli/install.ps1 | iex

# 指定版本 / 覆盖升级
& ([scriptblock]::Create((irm https://artifact.yoooclaw.com/cli/install.ps1))) -Version 0.12.0 -Force

默认装到 %LOCALAPPDATA%\YoooClaw\bin（yoooclaw.exe / yc.exe），并自动写入当前用户 PATH（-NoModifyPath 关闭）。检测到此前 npm i -g @yoooclaw/cli 装的旧版本时，安装器会在确认新原生 CLI 可执行后自动 npm uninstall -g @yoooclaw/cli 清理旧包（-KeepNpm 保留）；npm 清理出错不会回滚已验证可用的新版本。其他参数：-InstallDir、-Activate、-HermesProfile（含义同 install.sh 的 --dir / --activate / --hermes-profile）。

直装支持平台：darwin-arm64 / darwin-x64 / linux-x64 / linux-arm64 / win32-x64。

二进制也可从 GitHub Releases 或 OSS 制品目录 手动下载，配合同目录的 checksums.txt 校验。

yoooclaw update self 会自动识别当前安装来源（npm vs 原生二进制）和系统，给出对应的升级命令（原生形态的命令已自带 --force / -Force）—— 不要混用两种渠道。详见更新与升级。

C. 无影云电脑无人值守安装

面向阿里云无影云电脑等「装好就给 Agent 用」的环境。一条命令完成：安装原生 CLI → 写入 account api-key → 非交互初始化默认配置 → 为指定 Agent 宿主安装 Skill → 接管独立 CLI 所有权并启动 daemon（优先注册登录自启；用户级服务管理器不可用时降级为 detached daemon）。

export YOOOCLAW_API_KEY='ock-xxxx'
curl -fsSL https://artifact.yoooclaw.com/cli/install-wuying.sh \
  | sh -s -- --api-key "$YOOOCLAW_API_KEY" --skill claude --env production

# 已装过、只升级：可省略 --api-key（保留现有凭据），--force 覆盖二进制与已安装 Skill
curl -fsSL https://artifact.yoooclaw.com/cli/install-wuying.sh \
  | sh -s -- --skill codex --force

选项	说明
--skill <agent>	必填，Skill 宿主，直接传给 yoooclaw skills install --agent，当前支持 claude / codex。
--api-key <key>	写入新的 account api-key；省略则保留已有凭据（升级场景）。脚本不打印 key，经 stdin 写入 0600 的共享凭据文件，建议像示例一样引用环境变量，避免留在 shell 历史里。
--env <name>	development / test / production，默认读 PHONE_NOTIFICATIONS_ENV，未设置时为 production；会持久化到 profile 配置，供 systemd 服务使用。
--version / --dir / --profile / --force / --modify-path	同 install.sh。live 脚本默认装发布它的同版本正式版 CLI，--version 是安装预发布版的唯一途径。

对 Claude / Codex，脚本还会把本机 CLI 的绝对路径和所选 profile 写进已安装的 YoooClaw Skill，让 Agent 用完整命令调用，不依赖 ~/.local/bin 是否在 PATH 里；重复安装会更新这段配置，已有 Agent 会话需重新加载 Skill 或新开会话。

卸载

# 停 daemon + 删二进制与配置，保留通知 / 录音 / 图片数据
yoooclaw uninstall

# 连数据一起清空（清空 ~/.yoooclaw），免确认
yoooclaw uninstall --data --yes

原生二进制形态会自删 yoooclaw 与 yc；Windows 原生安装还会删除 install.ps1 写入的用户 PATH 条目与安装目录（包括跨盘安装的情况），返回里用 userPathRemoved / installDirsRemoved 标出。npm 安装形态由 node_modules 托管无法自删，uninstall 会提示再跑一次 npm uninstall -g @yoooclaw/cli。

5 分钟上手

# 1) 交互式向导：填入 Relay api-key，生成 config.json、gateway token，
#    并自动后台启动守护进程（无需再单独跑 daemon start）
yoooclaw config init

# 2) 看状态：PID、监听端口、relay、灯效规则数、最近 ingest
yoooclaw daemon status

# 3) 查今天的通知（手机推送落盘后）
yoooclaw notification +today

config init 收尾会自动后台拉起 daemon，并注册用户级登录自启动（macOS launchd / Linux systemd user service / Windows 任务计划，无需管理员权限）。Linux 服务器想在无人登录时也随开机启动，再执行 yoooclaw daemon autostart enable --boot。向导里填了 api-key 就直接连上 Relay、开箱即用； 如果当时留空，事后用 yoooclaw auth set-api-key <ock_xxx> 设置后再 yoooclaw daemon restart 让 daemon 连上 Relay。 只想注册自启动、暂不立即启动 daemon，加 --no-start；只想启动这一次、不留开机自启动，加 --no-autostart。自启动状态可用 yoooclaw daemon autostart status 查看，详见命令参考 · daemon。

多手机 / 多账号接入时，可以给每个 key 一个稳定 label；daemon 会为每个 label 各连一条 Relay 隧道，入站数据也会带上对应 clientLabel：

yoooclaw auth add-api-key <ock_phone_a> --label phone-a --default
yoooclaw auth add-api-key <ock_phone_b> --label phone-b
yoooclaw daemon reload
yoooclaw tunnel status
yoooclaw notification +today --client phone-a

服务器 / 无 GUI 部署（systemd / launchd 包装）：

yoooclaw daemon start --bind 0.0.0.0 --port 18365 --no-detach

绑 0.0.0.0 时强制要求已设置 gateway token，否则拒绝启动。

录音同步与 ASR

daemon 经 recordings.result.write 接收 App / 云端写入的转写与总结（可选带 ossUrl 时后台下载音频）到当前 profile 的 recordings/。音频下载复用阿里云 OSS SDK 的分片续传（单次下载流程内断点续传、有限重试，单个音频上限 5 GiB）；App 额外带上 ossTaskId 时，签名 URL 过期返回 403 会自动用它换一个新地址继续下载。本机重新转写经 recordings.retranscribe 按配置触发 ASR；独立 CLI 形态下，ASR 配置由本机一次性写入 recordings/asr-config.json，请求没带 asr 时 daemon 会自动读取本地配置。

# api 模式：不传 --api-key 时，daemon 会回退到 account 级 ock- key
yoooclaw recording setup-asr --mode api --language auto --non-interactive

当前 Go beta 只支持 api / model-proxy ASR。local 和 yoooclaw mode 仍保留在配置 schema 里用于兼容旧请求，但会在校验阶段被拒绝。

录音同步过程中，daemon 会把状态变化追加到 recordings/state/events.jsonl，CLI 可以直接查询或持续跟随：

yoooclaw recording list
yoooclaw recording +latest
yoooclaw recording events --since 1h --limit 50
yoooclaw recording events --id <recording-id> --watch

Agent-Native

CLI 自身就是 Agent 的工具表，无需再起一层 MCP server：

• 所有命令支持 --format ndjson，便于 Agent 流式逐条消费；
• 失败统一返回 { ok: false, error: { code, message, hint } }，错误码前缀 YOOOCLAW_*；本地 CLI 错误会返回非零退出码，Raw HTTP 结果请同时看 ok / HTTP status；
• yoooclaw api <METHOD> <PATH> 作为 Raw escape hatch 直达 daemon HTTP。

随包发布了 8 个 Skill（本地数据统一查询、录音加工、设备显示与灯效、云端待办、通知沉淀为记忆、数据迁移、图片 / 视频生成、隧道排查），教 Agent 直接调命令。安装前可先查看支持的 Agent 目标：

yoooclaw skills targets      # 查看可安装到哪些 Agent
yoooclaw skills install      # 自动探测唯一 Agent 后安装

详见 Agent Skill。

下一步

• 命令体系与输出 —— 三层命令、全局 flags、输出契约与数据目录。
• 命令参考 —— 按 service 列出全部子命令与示例。
• Agent Skill —— 把随包 Skill 安装到 Agent 让它自己驱动 CLI。