gem-hunter

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

• 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

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

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.

# 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

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).

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 checks account eligibility and schedules an offered update in the running standalone daemon, no earlier than ten minutes later. yc update check --check-only and yc update self only query eligibility. yc update install starts a detached installer. An API key is required.

# 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

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

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.

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.

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.

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 (🟡).

# 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

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.

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.

~/.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.

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.

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.

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.

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

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.

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.

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 -

--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

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).

--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

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.

POST /health-data accepts platform-neutral daily snapshots (schemaVersion: 3) through existing ingest authentication. /health advertises health-data-daily-v3. Relay uses path: "health-data" and the JSON string as payload of /api/message/messageBridge/send.

Each day contains date, ordinary items (metric/name/value/unit) and sleepSessions. Complete sleep sessions include observed start/end, sleep and stage minutes, awake minutes/count/longest interval, unknown minutes, boundary status, sources and the full ordered stage timeline. Sleep belongs to its end date and is never split at midnight. Stage minutes round each interval endpoin