assets

README

@yoooclaw/cli

English | 简体中文

yoooclaw is a standalone CLI — it ships its own background daemon and does not depend on the openclaw client being online — built for both humans and AI agents. It receives phone notifications locally, manages the Relay tunnel, handles recording ASR and light-effect rule evaluation, exposes unified --format output, and ships with an Agent Skill that works out of the box.

Service-oriented command tree, a three-tier command system, Agent-Native.

Install · Agent Skills · Auth · Commands · Advanced · Security · Contributing

Why yoooclaw?

• Ships its own daemon — a local daemon receives notifications, evaluates rules, and connects to Relay, independent of whether the openclaw client is online
• Agent-Native — the bundled Skill works out of the box; agents can call yoooclaw commands with zero extra config
• Three-tier command system — Shortcuts (human/AI friendly) → Service Commands (structured) → Raw API (full coverage), pick the granularity you need
• Disk-only queries — notification / voice-input / recording / image / captured web-page queries read directly from ~/.yoooclaw, no daemon required
• Unified output contract — --format json|pretty|table|ndjson, success and failure share one channel with predictable structure; local CLI errors return a non-zero exit code, and Raw/daemon HTTP responses should be checked against both ok and HTTP status
• Credential security — OS keychain storage by default, multi api-key management, gateway token auth for local ingest
• Native Go binary — a thin npm launcher + platform subpackages, or install the native binary directly; full macOS / Linux / Windows support

Capabilities at a Glance

Domain	Capabilities	daemon
📱 Notification	Query by time/app/sender/keyword, today/recent summaries, multi-dimension aggregate stats, chunked summarization for large batches	🟢
🔄 Sync	Scan/iterate unprocessed notifications, fetch details by date, commit batches — feeds memory systems	🟢
🗣️ Voice input	List/search daily JSONL dictation history, discover recent desktop App IDs/names, inspect optional audio	🟢
🎙️ Recording	Unified queries for YoooClaw Capture and smart-hardware recordings, plus hardware ASR config and events	🟢
🖼️ Image	List/query images, resolve local paths / thumbnails	🟢
🌐 Web	List/search captured web pages, resolve Markdown and storage paths	🟢
💡 Light	Send light-effect commands to hardware (segment / preset / rule — pick one), or show text on the hardware screen only	🟡
📐 Lightrule	CRUD for persistent "notification → light effect" rules, enable / disable	🟡
✅ Todo	Query, create, edit, complete / reopen and delete cloud todos	🟢
📦 Transfer	Migrate notifications, recordings, web pages and more between environments via OSS task IDs or local packages	🟢/🟡
⏰ Monitor	cron-driven scheduled notification monitoring jobs	🟡
🔌 Tunnel	Relay tunnel status, force reconnect, local ingest loopback self-check	🟡
🛡️ Gateway	Simulate phone-side calls into the daemon, verify local connectivity & auth	🟢/🟡
📋 Log	daemon log search & error-level filtering	🟢
⚙️ Infrastructure	config / profile / auth / daemon / owner / migrate / update / doctor / uninstall	🟢/🔵/🟡
🧩 Skills	Install bundled SKILL.md into the agent's discovery directory	🟢

daemon legend: 🟢 no daemon needed · 🟡 daemon must be running · 🔵 manages the daemon itself.

Installation & Quickstart

Two distribution channels with identical functionality — pick whichever fits. The npm package is now a very thin Node launcher; the actual work is done by the native Go binary installed via optionalDependencies. The direct-install channel skips Node entirely and downloads the same Go binary.

Platform support: the npm channel supports darwin/linux x64+arm64 and win32-x64 (the launcher needs Node ≥ 18); native direct install supports darwin/linux x64+arm64 and Windows x64 (Windows on ARM uses the OS x64 compatibility layer). On Windows, credentials are stored in plaintext at ~/.yoooclaw/credentials.json (no OS keychain hardening — yoooclaw doctor will warn about this), and the daemon shuts down gracefully over HTTP.

Channel A — npm (thin Node launcher + platform Go binary)

# No install needed (always pulls the latest version)
npx @yoooclaw/cli --help

# Global install (provides both the yoooclaw and yc commands)
npm i -g @yoooclaw/cli
yoooclaw --help
yc --help

Channel B — Native binary (no Node required)

A single-file Go executable — lighter cold-start and resource footprint than the older TS/Bun implementation.

One-command install on Windows PowerShell 5.1+, with no Node/npm or administrator rights required:

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

It installs yoooclaw.exe / yc.exe under %LOCALAPPDATA%\YoooClaw\bin and adds that directory to the current user's PATH. To pin a version or overwrite an existing installation:

& ([scriptblock]::Create((irm https://artifact.yoooclaw.com/cli/install.ps1))) -Version 0.12.0 -Force

If an older npm i -g @yoooclaw/cli installation is detected, the installer first verifies the new native CLI and then runs npm uninstall -g @yoooclaw/cli. Pass -KeepNpm to retain it. An npm cleanup failure never rolls back a verified native installation.

macOS / Linux:

# Auto-detect platform, download, verify sha256, install to ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/YoooClaw/cli/master/scripts/install.sh | sh

# Opt in if you want the installer to add its bin directory to your shell PATH
curl -fsSL https://raw.githubusercontent.com/YoooClaw/cli/master/scripts/install.sh \
  | sh -s -- --modify-path

# Pin a version / install directory / force overwrite
curl -fsSL https://raw.githubusercontent.com/YoooClaw/cli/master/scripts/install.sh \
  | sh -s -- --version 0.2.0-beta.2 --dir ~/bin --force

The Unix installer does not modify shell startup files by default; pass --modify-path to opt in. The Windows installer updates the user PATH by default; pass -NoModifyPath to opt out.

If a Linux Agent reports yoooclaw: command not found while your terminal works, use the absolute path printed by the installer (for example, /home/admin/.local/bin/yoooclaw --version). A non-interactive, non-login bash -c normally does not read .profile / .bashrc, so --modify-path or reopening a terminal may not fix the Agent's PATH. Add the actual install directory to PATH in the Agent runner / service startup environment, then restart that process. For the current Bash session, export PATH="$HOME/.local/bin:$PATH" is a temporary fix. Successful binary verification does not mean an already-running Agent can discover the command.

Direct-install supported platforms: darwin-arm64 / darwin-x64 / linux-x64 / linux-arm64 / win32-x64. You can also download manually from GitHub Releases (verify against the checksums.txt in the same release).

Unattended WUYING cloud desktop installation

The dedicated installer installs the CLI, writes the account API key, initializes the default config, installs Skills for the selected Agent host, and starts the daemon. It prefers login autostart and falls back to a detached daemon when no user service manager is available. --skill is required. --api-key is optional: omit it on upgrade to preserve existing credentials; supply it for first-time account setup or to replace the key:

For Claude / Codex, the script also writes the absolute CLI path and selected profile into the installed YoooClaw Skills, instructing the Agent to use the full command even when ~/.local/bin is absent from PATH. Reinstalling updates this configuration; existing Agent sessions must reload Skills or start a new session. Other hosts currently receive an absolute-path reminder only.

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

# Upgrade to a specific beta without changing credentials
curl -fsSL https://artifact.yoooclaw.com/cli/install-wuying.sh \
  | sh -s -- --skill claude --version 0.12.0-beta.11 --force

# Codex host; replace the binary and refresh installed Skills on reinstall/upgrade
curl -fsSL https://artifact.yoooclaw.com/cli/install-wuying.sh \
  | sh -s -- --api-key "$YOOOCLAW_API_KEY" --skill codex --env development --force

Current CLI releases accept claude and codex for --skill. The value is passed directly to the CLI Skill adapter, so the installer will not need a workflow change when a DeepSeek Harness adapter is added. --env accepts development, test, or production; it defaults to PHONE_NOTIFICATIONS_ENV, then production, and is persisted in the profile for systemd-launched daemons. The live script installs the CLI release that shipped it by default — always a stable one, since prereleases never overwrite the live scripts or the latest marker — and also accepts --version (the only way to install a prerelease), --dir, --profile, and --modify-path. It never prints the API key and writes it through stdin to the shared 0600 credentials file; reference an environment variable as above to keep the plaintext value out of shell history.

yc update check (yc update self is an alias) checks account eligibility through the rollout service. yc update install starts a detached installer. An API key is required.

Quickstart (Human Users)

# 1. Interactive first-run wizard: generates config + gateway token and starts the daemon
yoooclaw config init

# 2. Check auth and environment readiness
yoooclaw auth status
yoooclaw doctor

# 3. Start using it: notification queries read straight from disk, no daemon required
yoooclaw notification +today

Quickstart (AI Agent)

The steps below are for AI agents; some may need a human to confirm in the terminal. Query commands are disk-only; control commands require the daemon to be running.

# 1. Initialize via stdin config injection (no interactive prompts), which also starts the daemon
yoooclaw config init --non-interactive --from-file -

# 2. Confirm the daemon is running and the tunnel is connected
yoooclaw daemon status
yoooclaw tunnel status

# 3. Stream notification queries (always based on the latest disk data — don't rely on memory)
yoooclaw notification summary --app WeChat --from 2026-06-01T00:00:00+08:00 --format json

# 4. Install the bundled Skill into the current agent's discovery directory
yoooclaw skills install

Agent Skills

Recommended pairing: YoooClaw/skills. The yoooclaw-cli Skill distributed from that repo packages command routing, the --format output contract, daemon dependencies, and error handling into an agent-facing "instruction manual", so Codex / Claude Code and similar agents understand how to call yoooclaw out of the box. Install the CLI first, then the Skill:

# 1. Install the CLI (prerequisite)
npm install -g @yoooclaw/cli

# 2. Install the yoooclaw-cli Skill — Codex + Claude Code
npx skills@latest add YoooClaw/skills --skill yoooclaw-cli --global --agent codex --agent claude-code --copy --yes

# Install for just one agent: pass a single --agent
npx skills@latest add YoooClaw/skills --skill yoooclaw-cli --global --agent claude-code --copy --yes

For Hermes Agent, use hermes skills install https://raw.githubusercontent.com/YoooClaw/skills/main/yoooclaw-cli/SKILL.md. Restart the agent session after installing so it can be discovered.

Built-in Skill (bundled in this repo)

This repo bundles several Skills under skills/ that teach agents to call yoooclaw directly. Use yoooclaw skills install to copy the embedded Skills into an agent's discovery directory.

Skill	Description
yoooclaw-media-generate	Generates images and videos up to 30 seconds with Python 3; reads MODEL_PROXY_API_KEY from ~/.config/yoooclaw/credentials
yoooclaw-context-query	The sole query Skill for fresh notifications, voice input, recordings/transcripts, captured web pages, synchronized images, and cross-source local context
yoooclaw-notification-to-memory	Distills notifications into personal, daily, and long-term agent memory; commits each batch only after verified persistence
yoooclaw-recordings-process	Routes meeting minutes, translation, mind maps, interview restructuring, and entity extraction through one recording-source workflow
yoooclaw-light	Plays one-shot light effects and manages persistent “notification → light effect” rules through the standalone CLI
yoooclaw-todo	Query, create, edit, complete / reopen and delete personal todos; default for generic schedule / todo requests, confirms before deletion
yoooclaw-data-transfer	Migrates data via OSS task IDs or local packages (notifications, recordings, web pages, optional audio/images) between environments; packages interoperate with the OpenClaw plugin ntf transfer
yoooclaw-tunnel-debug	Debugs auth, daemon, ingest, Relay WebSocket, and phone-side synchronization failures (🟡)

yoooclaw skills list                 # List Skills bundled with this package
yoooclaw skills targets              # View supported agent targets and detection results
yoooclaw skills install              # Auto-detect the sole agent and copy-install
yoooclaw skills install --agent claude
yoooclaw skills install --force      # Refresh bundled Skills and remove merged legacy names

Skills are embedded in the native binary and copied during installation. After upgrading the CLI, rerun yoooclaw skills install --force, then restart the agent session.

Authentication

yoooclaw's authentication revolves around two kinds of credentials: api-key (account-level, signs phone-side upstream ingest) and gateway token (local daemon HTTP auth). Most commands are local checks (🟢); auth check performs an end-to-end call to the daemon (🟡).

Command	Description
auth set-api-key <key>	Set/rotate the account-level default api-key (- reads from stdin)
auth add-api-key <key>	Add a multi-key api-key entry, optionally with --label / --default
auth list-api-keys	List api-key entries (keys are automatically masked)
auth set-default-api-key <label>	Switch the default api-key
auth remove-api-key <label>	Remove the api-key entry with the given label
auth token-rotate	Generate a new gateway token; restart the daemon afterward if it's running
auth status	Show auth status (local check, does not call the daemon)
auth check	End-to-end auth health check (calls daemon /daemon/status)

# Write the default api-key securely from stdin, stored in the OS keychain
echo "ock-xxxx" | yoooclaw auth set-api-key - --keychain

# Multi-device/multi-client: manage multiple api-keys by label
yoooclaw auth add-api-key - --label phone-a --default
yoooclaw auth list-api-keys

# Rotate the gateway token, then restart the daemon so it takes effect
yoooclaw auth token-rotate
yoooclaw daemon restart

Daemon autostart

Initializing the active profile enables per-user login autostart by default (launchd on macOS, systemd user services on Linux, and Task Scheduler on Windows) and starts the daemon immediately. It never requires a system service or administrator privileges.

yoooclaw daemon autostart status
yoooclaw daemon stop                 # stop for this login; autostart stays enabled
yoooclaw daemon start                # start now; does not change the saved preference
yoooclaw daemon autostart disable    # stop now and opt out of future login starts
yoooclaw daemon autostart enable     # opt in and start now
yoooclaw daemon logs --supervisor    # inspect OS service startup failures

yoooclaw config init --no-start      # enable autostart, but do not start now
yoooclaw config init --no-autostart  # start now without enabling autostart

Autostart always follows the active profile. profile use transfers a running daemon to the new profile while preserving a manually stopped state. On Linux, autostart begins with the user service manager; enabling pre-login boot via yoooclaw daemon autostart enable --boot explicitly enables linger for the current OS user. daemon autostart status reports linger, unitEnabled, bootEnabled and any bootWarning; doctor warns when pre-login startup is unavailable. Disabling autostart does not disable linger, which may be used by other user services. Upgrades from releases without an autostart preference register the initialized active profile even if its daemon was stopped during the upgrade. An explicit autostart disable preference and a live Hermes owner are always preserved.

Switching or deleting a profile (profile use / profile delete) first waits for the old profile's daemon to actually release the account-level Relay consumer lock before proceeding (so a not-yet-exited old process can't keep writing production messages into a profile you've switched away from); an OS-managed autostart service is stopped/started along with it.

Linux startup and credential reload diagnostics

Run yoooclaw daemon logs --diagnostics --lines 100 to collect daemon and supervisor logs, lock/process identity, autostart state, and the Linux service journal for this boot. Use the installed executable's absolute path if it is absent from PATH. service.entry / daemon.ready identify the version, PID, profile and paths; status.observed / reload.request explain stale locks and compare systemd state. credentials.reload_applied records credential sources, labels, short SHA-256 fingerprints and tunnel changes without logging keys or tokens. Applying credentials does not confirm a connection: look for the subsequent connected or 401/403 logs. If no service.entry exists, inspect the collected systemd/journal records: an application cannot log before the OS has launched it.

Storage ownership: CLI ↔ Hermes plugin

~/.yoooclaw/profiles/<profile>/writer.lock guarantees exactly one storage writer per profile at a time. When the Hermes plugin runs in daemonless mode it holds this lock, and daemon start / daemon run-foreground are then refused with YOOOCLAW_DAEMON_DISABLED_BY_PLUGIN. On Windows, if probing the lock itself fails (e.g. a permission error), the behavior is fail-closed: startup is refused outright with YOOOCLAW_STORAGE_UNAVAILABLE, rather than treating a failed probe as "not held."

yoooclaw owner activate cli                          # hand ownership from the Hermes plugin to the standalone CLI
yoooclaw owner activate cli --hermes-profile work --no-start

install.sh / install.ps1 preserve ownership as it was before the upgrade by default—an upgrade never silently hands it off. Only passing --activate / -Activate explicitly (or setting YOOOCLAW_ACTIVATE_OWNER=cli) makes it actively hand ownership to the standalone CLI after install.

Daemon lifecycle protocol

yoooclaw daemon exposes lifecycle metadata so external orchestrators such as the Hermes plugin can keep the daemon and their websocket connections in the same generation.

yoooclaw daemon run-foreground --owner hermes-plugin --generation abc123
yoooclaw daemon stop --owner hermes-plugin --generation abc123 --wait
yoooclaw daemon status --format json

daemon status includes pid, version, executable, profile, relay.env, and a nested lifecycle object:

{
  "ok": true,
  "version": "0.3.0",
  "executable": "/Users/me/.yoooclaw/hermes-plugin/bin/0.3.0/yoooclaw",
  "profile": "test",
  "lifecycle": {
    "owner": "hermes-plugin",
    "generation": "abc123",
    "startedAt": "2026-06-18T10:34:07Z"
  }
}

The lifecycle flags are optional; normal human daemon start, stop, and restart usage remains unchanged. When supplied to daemon stop, owner and generation are checked before the process is terminated.

Ingress Modes (optional, proxyable daemon connection)

Once the "connection to the phone" is layered, --ingress selects the single owner, avoiding a double connection / double ingest when the standalone CLI and a host plugin (e.g. hermes-plugin) both try to connect to Relay. Priority order: --ingress flag > YOOOCLAW_INGRESS env var > config.ingress.mode, defaulting to standalone.

Mode	Owner of the phone connection	Relay tunnel	Ingest auth	Outbound events
standalone (default)	the Go daemon's own tunnel	enabled	gateway token / local	pushed back to the phone via Relay
proxied (embedded in a host plugin)	the host plugin proxies it	off	api-key required	POSTed back to the host callback URL
direct (LAN / testing)	the caller POSTs directly	off	api-key / token	discarded (disk write only)

Under proxied, the daemon doesn't connect to the tunnel; it only exposes the ingest API (POST /notifications /recordings /images, with Authorization: Bearer <api-key>) so the host can feed phone data in. Outbound events (such as recording.status) are posted back to the host via --egress-callback-url, and the host forwards them to the phone.

# Embedded in a host: turn off the Go daemon's own tunnel, let the host proxy the connection and receive callback events
yoooclaw daemon run-foreground --ingress proxied \
  --egress-callback-url http://127.0.0.1:8765/yoooclaw/egress \
  --egress-callback-token <token>

daemon status output now includes an ingressMode field. See the full layering design at docs/design/ingress-layering.md.

Three-Tier Command System

Ranging from quick shortcuts to fully custom calls, covering everyday operations up to any daemon endpoint:

1. Shortcuts

Prefixed with +, friendly to both humans and AI, with smart defaults and table output built in.

yoooclaw notification +today          # Today's notification summary
yoooclaw notification +recent         # Notifications from the last hour
yoooclaw recording +latest            # Details of the most recent recording
yoooclaw recording +today             # Recordings from today's local calendar day
yoooclaw voice +latest                # Most recent saved voice-input item
yoooclaw voice +today                 # Today's saved voice-input history
yoooclaw lightrule +on                # Enable all light-effect rules
yoooclaw tunnel +test                 # Daemon local ingest + auth self-check
yoooclaw log +errors                  # Error-level logs since yesterday

Run yoooclaw <service> --help to see all shortcuts for a given service.

2. Service Commands

yoooclaw <service> <subcommand> [...flags] — structured access to each domain's capabilities; see the service list via yoooclaw --help.

yoooclaw notification search --app WeChat --keyword meeting --limit 50
yoooclaw notification stats --dim app --from 2026-05-26
yoooclaw notification summary-job create --from 2026-06-01T00:00:00+08:00 --chunk-size 150  # Chunked summarization for large notification batches: create→next→commit→result
yoooclaw recording list [--source all|capture_app|smart_hardware] [--from <ISO_TIME_OR_DATE>] [--to <ISO_TIME_OR_DATE>]
yoooclaw recording setup-asr --mode api --language auto --non-interactive
yoooclaw recording setup-asr --mode api --language zh-TW --non-interactive   # Traditional Chinese / Taiwan hint
yoooclaw recording setup-asr --mode api --language zh-Hant --non-interactive # Traditional Chinese script hint
yoooclaw voice list [--from <ISO_TIME_OR_DATE>] [--to <ISO_TIME_OR_DATE>]
yoooclaw voice apps                                # Deduplicated App IDs/names from the recent 7 days
yoooclaw voice search "project" --app com.microsoft.VSCode
yoooclaw synced-web-page list [--from <ISO_TIME>] [--to <ISO_TIME>]
yoooclaw synced-web-page search "JavaScript" --limit 20
yoooclaw synced-web-page path <url-hash>
yoooclaw synced-web-page storage-path
yoooclaw todo list --is-done false --format json             # cloud todos
yoooclaw transfer export --via oss --format json              # pack and upload transfer data, returns a taskId
yoooclaw light send --title "Task done" --reason "Build passed"   # show text on the hardware screen only
yoooclaw lightrule create --intent "Flash red when my boss messages me on WeChat"  # Compiled & stored by the cloud service
yoooclaw monitor create daily-standup --schedule "0 9 * * 1-5" --match-rules '{"keyword":"standup"}'

synced-web-page list filters the index by capturedAt: --from is inclusive and --to is exclusive. Pass ISO 8601 timestamps with an explicit timezone.

For ASR language hints, auto keeps provider-side detection. Use zh-TW for Traditional Chinese in a Taiwan context, or zh-Hant when only the Traditional Chinese script preference matters.

An unfiltered voice list returns the rolling last 72 hours and includes an explicit notice in JSON. Use voice list --all for all saved history. There is no default row-count limit. voice apps defaults to the rolling last seven days, deduplicates by app_id, and returns both the observed app_id and app_name; use voice apps --all for an explicit all-history inventory. Voice history is read from daily audio-jsonl/YYYY-MM-DD.jsonl files; returned IDs are stable voice_id strings and the CLI never falls back to the legacy SQLite database. Recording queries default to both YoooClaw Capture (capture_app) and YoooClaw smart hardware (smart_hardware), and every result includes its source.

3. Raw API

yoooclaw api <METHOD> <PATH> [--data ...] reaches daemon HTTP endpoints directly, covering anything not wrapped by a service command.

yoooclaw api GET /daemon/status
yoooclaw api POST /images --data @image.json
echo '{"...":"..."}' | yoooclaw api POST /recordings --data -

Advanced Usage

Global flags

flag	Description
--profile <name>	Switch profile (default: default)
--format <fmt>	json|pretty|table|ndjson (defaults to pretty on a TTY, json when piped)
--quiet	Suppress progress logs, output only the final result
--no-color	Disable terminal colors

Output Formats

--format json      # Full JSON (default when piped)
--format pretty    # Human-friendly formatted output (default on a TTY)
--format table     # Readable table
--format ndjson    # Newline-delimited JSON, convenient for line-by-line piping

Output Contract

Success and failure share the same channel (stdout) with a predictable structure. Local CLI validation / runtime errors are additionally expressed via a non-zero exit code; Raw HTTP commands like api preserve the daemon's original response as much as possible, so scripts should check both ok and HTTP status:

{
  "ok": false,
  "error": {
    "code": "YOOOCLAW_DAEMON_NOT_RUNNING",
    "message": "...",
    "hint": "..."
  }
}

Error codes share a uniform YOOOCLAW_* prefix (see internal/errs/errors.go).

Multiple Profiles

--profile <name> switches between accounts/devices; data is isolated under ~/.yoooclaw/profiles/<profile>/.

yoooclaw profile list
yoooclaw profile create work
yoooclaw --profile work notification +today

Recording & Relay

The standalone daemon uses a Go implementation of recording storage, the state machine, OSS download, and ASR scheduling, and receives the app/cloud's recordings.result.write (writing transcripts/summaries, optionally downloading audio) via RelayClient + RelayDispatcher. New-recording payloads should include recording.created_at (or top-level createdAt / created_at); transcript.generatedAt is artifact-generation time and is never used as the recording time. Top-level durationMillis is truncated down to integer seconds and stored as numeric duration_sec; duration_display adds a human-readable unit form such as 16s, 1m 16s, or 1h 1m 1s. After the audio is downloaded, the CLI stores file_size_display using the Android Formatter.formatShortFileSize()-compatible SI short format; the removed file_size_bytes field is not emitted.

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

Audio downloads reuse the Alibaba Cloud OSS Go SDK v2 multipart downloader (8 MiB parts, concurrency 3, Range + ETag validation): a flaky network resumes from the checkpoint within the current download instead of deleting the partial file and starting over; 5 GiB max per audio file, and an existing non-empty local audio file is reused. recordings.result.write accepts an optional top-level ossTaskId (the upload service's task ID, ≤256 characters, must come with an audio URL; not the ASR task ID in transcript.source.taskId): on a 403 the daemon uses the api-key that wrote the recording to fetch a fresh signed URL from the cloud and retries — the api-key is never sent to OSS. ossTaskId is stored in the recording index and echoed in the write response, recording list/status and recording.status events (omitted when absent); a new write without it clears the old value.

Recording config and events live under the current profile at recordings/asr-config.json and recordings/state/events.jsonl respectively. Files under transcripts/ / summaries/ follow the naming convention <YYYYMMDDHH>_<title>_<id>.md, so filename order is chronological (files written before an upgrade keep their old names — no bulk migration). Recordings ingested via /gateway/recordings.* are tagged with the clientLabel of the api-key that wrote them, and the read side (recording list/status/events) is scoped the same way — a client connected over a Relay tunnel or a specific api-key only sees its own recordings, while loopback / gateway-token requests are unrestricted; synced-web-page and its endpoints follow the same scoping.

Data Transfer

yoooclaw transfer moves local data between environments (new computer, reinstall, another profile) as a plaintext package: a single .tar.gz file (since 0.12.0, when --out ends in .tar.gz/.tgz) or a package directory (any other path). The package format is the same as the OpenClaw plugin's ntf transfer (schema 1), so packages and capability files work in both directions; targets older than CLI 0.12.0 / plugin 1.18.0 only read directories, and --target-capabilities refuses a tar.gz export for them with YOOOCLAW_TRANSFER_ARCHIVE_UNSUPPORTED_BY_TARGET. Compression is not encryption.

yoooclaw transfer export --via oss                                 # Upload and return taskId
yoooclaw transfer import --task <taskId>                            # Download and import; server deletes cloud package after 24 hours
yoooclaw transfer import --task <taskId> --dry-run                  # Download and preview only
yoooclaw transfer export --dry-run                                  # Preview scope; no daemon needed
yoooclaw transfer export --out ~/yoooclaw-pkg.tar.gz [--with-audio] [--with-images] [--with-html] [--from <ISO+TZ>] [--to <ISO+TZ>]
yoooclaw transfer capabilities --out caps.json                      # On the target (needs the daemon)
yoooclaw transfer import --file ~/yoooclaw-pkg.tar.gz                # Stage + verify + preview, never merges (archive or directory)
yoooclaw transfer import --local <localTransferId> --plan <planId>   # Execute the previewed plan [--resume]

The data-transfer Skill defaults to OSS. Cloud commands use the existing CLI API key (cli scope, no extra scope header) and configured cloud environment; source and target keys must belong to the same account. Signed download URLs and STS credentials stay inside the command; users copy only the taskId. Upload and download reuse Alibaba Cloud OSS SDK checkpoints during retries within one invocation. Uploads automatically renew STS credentials via /file/plugin/refresh before expiry or after an expired-token error, preserving the original task and multipart checkpoint; no agent-facing refresh command is needed. The server automatically deletes cloud packages 24 hours after upload completion, regardless of import status. The CLI never deletes cloud packages and has no cloud deletion command. Successful imports still clean local staging; PARTIAL/failed imports retain local staging and reports for retry. Migration replies prominently warn: ⚠️ 迁移数据包含大量隐私信息，请妥善保管任务 ID 和数据包，避免向他人分享或泄露。 For interrupted upload confirmation, use yoooclaw transfer complete --task <taskId> --object-key <objectKey> from the error instead of creating a new task.

Imports run inside the target daemon, which owns the stores. Existing target records are never overwritten: differing records are reported as conflict, and a PARTIAL import keeps its staged package and report.json under <profile>/transfers/. Imported notifications are tagged transfer.memoryPolicy="skip-history" and excluded from yoooclaw sync (notification → memory). Memory, credentials and configuration are not transferred.

AI TODO cloud todos (0.11.0)

yc todo list|get|create|update|delete manages cloud todos directly without a daemon. Use --format json.

yc --format json todo list --is-done false
yc --format json todo get 841
yc --format json todo create --title "Meeting" --due-at "2026-09-11T15:00:00+08:00" --is-full-day false
yc --format json todo update 841 --is-done true
yc --format json todo update 841 --is-done false
yc --format json todo delete 841 --confirmed

Times are START times: ISO with explicit offsets, all-day dates, or JSON null for undated items. All commands accept --json-file FILE (- for stdin); field flags cannot be mixed with JSON. CLI list defaults to unfinished across all time; agents supply local day boundaries for natural-language today queries. Creation returns a requestKey; replay only the same request with --request-key KEY after an unknown outcome. Partial success remains ok:false with per-stage outcomes and a nonzero exit code. The yoooclaw-todo skill documents user-facing routing and confirmations.

Endpoints share /api/message/todo/agent/; API Key and environment use existing configuration. The latest recorded backend rejected undated creation with 910001; no silent time substitution is performed. See implementation plan for the contract and verification.

Data Directory

~/.yoooclaw/ (can be overridden with YOOOCLAW_HOME, useful for testing / multiple instances). See the layout in internal/paths/paths.go and the PRD's "Data Model" section.

Security & Risk Notice

This tool can be invoked by AI agents to automate operations against the local daemon and the phone-side link, which carries inherent risks such as model hallucination, unpredictable execution, and prompt injection. Once authorized, the agent will act within your identity and authorization scope, which may lead to sensitive data exposure or unintended operations — use with caution.

To reduce risk, the tool enables multiple layers of protection by default: the daemon only listens on a local port, local ingest is authenticated via gateway token, credentials are stored in the OS keychain by default, and sensitive fields are masked in terminal output. We strongly recommend against relaxing these default security settings; doing so significantly increases risk, and you assume full responsibility for the consequences. Please fully understand the risks involved — using this tool constitutes voluntary acceptance of the associated responsibility.

Development & Contributing

go test ./...
go vet ./...
scripts/build-go.sh --current
dist-native/yoooclaw-darwin-arm64 --help

Full documentation lives at yc-docs/src/cli. Issues and PRs are welcome; for larger changes, please open an issue to discuss first.

Source Layout

File / Directory	Responsibility
cmd/yc/main.go	Go binary entry point
internal/cli/root.go	cobra root, global flags, service command wiring
internal/cli/handler.go	handler wrapping, output and error rendering
internal/output/output.go	unified --format serialization
internal/errs/errors.go	YOOOCLAW_* error codes
internal/paths/paths.go	~/.yoooclaw/ directory layout resolution
internal/daemon/server.go	daemon HTTP server, auth, Relay wiring
internal/daemon/server_ingest.go	notifications / recordings / images ingest
internal/relay/dispatcher.go	in-process dispatch from inbound Relay frames to daemon HTTP/gateway
internal/recording	recording OSS download, state machine, ASR, transcript storage
internal/capturerecording	read-only daily indexes and artifact checks for YoooClaw Capture recordings
internal/voice	read-only daily JSONL queries for local voice-input history
internal/image	image OSS download and indexing
internal/ossdownload	resumable OSS multipart downloader shared by recordings and transfer
internal/transfer / internal/transfercloud	transfer package export / import, and OSS task upload / download
internal/aitodo	cloud todo API client and time semantics
internal/light	light-effect wire protocol, presets, sender
internal/skills	built-in Skill listing / installation into agent skills directories

All release artifacts are generated from the Go source via scripts/build-go.sh (npm platform subpackages + native binaries); the earlier TypeScript implementation has been retired and remains available only in git history.

License

MIT — see LICENSE.

Switch cloud environment

yc env show
yc env switch test       # production / test / development

This updates the selected shared profile without changing API keys or taking ownership from Hermes. A running Hermes owner blocks this command. A running CLI daemon must support the activity check; requests and background recording downloads defer the switch. An offline profile is saved without starting a daemon. Conflicting environment overrides and custom Relay URLs are not silently replaced. CLI and Hermes still inherit the shared environment when ownership changes.

Rollout updates (new in this branch; unreleased)

yc update check
yc update install
yc update install --version 0.13.0

Standalone daemons check after about one minute and then every four hours. Background installation waits for ten minutes without business requests and no active requests or recording downloads; eligibility and activity are checked again before replacement. Disabling autoUpdate.enabled retains checks, reporting and manual installation but disables background installation. Restart the daemon after changing this setting.

Only standalone binaries registered by the official native installer are replaced. Hermes embedded/shared binaries and npm installations are excluded. Updates retain environment, credentials and autostart settings. Claude skills are refreshed when detected, retaining Wuying command bindings. Manual installation works with an offline daemon and still requires rollout eligibility.

started means the installer was launched, not that the new version is active. Activation requires a running, connected new daemon; offline installs await its next startup. Phase logs and terminal results share an updateId; queues retry for up to seven days and redact errors before persistence. Official scripts report phases when the existing CLI supports reporting; a first install or older CLI cannot report those earlier phases.

Disable automatic updates for custom builds

Before modifying the source or using a custom build, disable automatic updates to prevent an official release from replacing it. Run these commands for the profile you use:

yc config set autoUpdate.enabled false
yc daemon restart

The setting is read at daemon startup, without periodic reloading. If the daemon is stopped, the next start picks it up. Add --profile <name> for a non-default profile. To restore automatic updates, set it to true and restart the daemon.

Documentation

Overview

Package assets 把随包发布的静态资源（SKILL.md 技能）通过 go:embed 编译进二进制。

Go 重写后 CLI 是单一二进制，没有 TS 版那种 <pkg>/skills/ 同级目录可供解析与软链； 因此把 skills/ 整个嵌入二进制，由 `skills install` 解包（复制）到 agent 技能目录。

Index

• Variables

Variables

var SkillsFS embed.FS

SkillsFS 内嵌 skills/ 目录（含各 yoooclaw-*/SKILL.md）。