命令体系与输出

三层命令体系

• Shortcuts（+ 前缀）：对最常用场景做参数预设，如 yoooclaw notification +today、yoooclaw light +blink、yoooclaw lightrule +on、yoooclaw recording +latest、yoooclaw image +latest。
• Service commands：yoooclaw <service> <subcommand>，service 列表见 yoooclaw --help。
• Raw API：yoooclaw api <METHOD> <PATH> [--data ...] 直达 daemon HTTP 端点，调试和未包装能力都不卡。

完整子命令清单见 命令参考。

daemon 依赖标记

文档里用三个标记区分命令对 daemon 的依赖：

标记	含义
🟢	不需要 daemon（纯读磁盘或纯本地操作）
🟡	需要 daemon 在跑（控制类，走本地 HTTP RPC）
🔵	进程类（管理 daemon 自身）

全局 flags

flag	说明
--profile <name>	切换 profile（默认 default，也可用环境变量 YOOOCLAW_PROFILE）
--format <fmt>	json | pretty | table | ndjson（TTY 默认 pretty，管道默认 json）
--quiet	抑制进度日志，只输出最终结果
--no-color	关闭终端颜色

输出格式

格式	行为	适用
json	单行 JSON.stringify	非 TTY / 管道默认
pretty	缩进两空格	TTY 默认
table	数组结果按列对齐	人看列表
ndjson	每条结果一行 JSON，无包裹数组	流式 / 大批量 / Agent 消费

输出契约

成功与失败共用同一通道（stdout）与可预测结构；失败额外以非零退出码表达：

{ "ok": false, "error": { "code": "YOOOCLAW_DAEMON_NOT_RUNNING", "message": "daemon 未运行", "hint": "先执行 yoooclaw daemon start" } }

错误码统一前缀 YOOOCLAW_*，进入半正式契约。常见错误码：

code	含义
YOOOCLAW_INVALID_ARGUMENT	参数校验失败
YOOOCLAW_CONFIG_INVALID	profile 未初始化或配置非法
YOOOCLAW_DAEMON_NOT_RUNNING	daemon 未运行（🟡 命令前置检查）
YOOOCLAW_DAEMON_ALREADY_RUNNING	daemon 已在运行（单实例保护）
YOOOCLAW_UNAUTHORIZED	gateway token 不一致
YOOOCLAW_NOT_FOUND	资源不存在
YOOOCLAW_IMAGE_NOT_READY	图片尚未下载完成

Profile

--profile <name> 切换到 ~/.yoooclaw/profiles/<name>/；未指定时用 ~/.yoooclaw/active-profile 记录的 active profile，缺省 default。多机 / 多账号各跑一个 profile：

yoooclaw --profile home daemon status
yoooclaw --profile work daemon status
yoooclaw profile list          # 列出全部，标注 active
yoooclaw profile use work       # 切换 active

数据目录

~/.yoooclaw/（可用环境变量 YOOOCLAW_HOME 覆盖，便于测试 / 多实例）。落盘文件 0600、目录 0700：

~/.yoooclaw/
├── credentials.json          # account 级共享 api-key（跨 profile，且与插件共用）
├── active-profile            # 当前 active profile 名
└── profiles/
    └── default/
        ├── config.json       # daemon / relay / 灯效规则 / 输出等配置
        ├── credentials.json  # instance 级密文（gateway token / webhook secret）
        ├── daemon.lock       # 进程锁（PID + 启动时间 + 监听地址）
        ├── daemon.log        # 当前日志（按日轮转为 daemon.log.YYYY-MM-DD）
        ├── notifications/    # 按日期 YYYY-MM-DD.json
        ├── recordings/       # index.json + 音频 / 转写稿 / asr-config.json
        ├── images/           # index.json + files/（从 OSS 下载的本体）
        ├── tasks/            # 灯效规则
        └── state/            # monitors.json、last-update-check.json 等

凭据解析

敏感凭据按 env → keychain（可选）→ 文件 分层解析，命中即停：

• api-key（account 级，调 yoooclaw AI / app-name-map）：YOOOCLAW_API_KEY → keychain yoooclaw/api-key → 共享 ~/.yoooclaw/credentials.json。yoooclaw auth set-api-key 写一次，插件 / CLI / daemon 三方同时生效。
• gateway token / webhook secret（instance 级）：随 profile 走，由 config.json 的 *Ref 引用（env: / file: / keychain: / inline:）。