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
yoooclawcommands 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 / 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 bothokand 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
| 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 | 🟢 |
| 🎙️ Recording | List/query recordings, ASR transcription config (api/model-proxy; local mode deprecated), follow status event stream | 🟢 |
| 🖼️ 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), connectivity self-check | 🟡 |
| 📐 Lightrule | CRUD for persistent "notification → light effect" rules, enable / disable | 🟡 |
| ⏰ 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 / 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.
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); install.sh / GitHub Release direct install supports darwin/linux x64+arm64. 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 --helpA single-file Go executable — lighter cold-start and resource footprint than the older TS/Bun implementation.
# 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 --forceThe installer does not modify shell startup files by default. It only updates PATH when
--modify-path is explicitly supplied; --no-modify-path remains accepted for compatibility.
Direct-install supported platforms: darwin-arm64 / darwin-x64 / linux-x64 / linux-arm64. The Windows Go binary currently ships only via the npm platform subpackage. You can also download manually from GitHub Releases (verify against the checksums.txt in the same release).
yoooclaw update selfgives you the right upgrade command for how you installed (npm →npm update -g, binary → install.sh).
# 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 +todayThe 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 installRecommended pairing: YoooClaw/skills. The
yoooclaw-cliSkill distributed from that repo packages command routing, the--formatoutput contract, daemon dependencies, and error handling into an agent-facing "instruction manual", so Codex / Claude Code and similar agents understand how to callyoooclawout 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 --yesFor 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.
| Skill | Description |
|---|---|
yoooclaw-context-query |
The sole query Skill for fresh notifications, recordings/transcripts, captured web pages, synchronized images, and cross-source local context |
yoooclaw-recordings-process |
Routes meeting minutes, translation, mind maps, interview restructuring, and entity extraction through one recording-source workflow |
yoooclaw-lightrule-create |
Creates and manages persistent “notification → light effect” rules through the standalone CLI; retained because this package has no Agent light-rule tools |
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 namesSkills 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 (🟡).
| 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 restartyoooclaw 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 jsondaemon 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.
| 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.
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 light +blink # Light-effect connectivity test (red-strobe-3)
yoooclaw lightrule +on # Enable all light-effect rules
yoooclaw tunnel +test # Daemon local ingest + auth self-check
yoooclaw log +errors # Error-level logs since yesterdayRun 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 --status synced [--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 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 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.
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 -| 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 |
--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 pipingSuccess 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 +todayThe 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> --watchRecording config and events live under the current profile at recordings/asr-config.json and recordings/state/events.jsonl respectively.
~/.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.
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.
go test ./...
go vet ./...
scripts/build-go.sh --current
dist-native/yoooclaw-darwin-arm64 --helpFull documentation lives at yc-docs/src/cli. Issues and PRs are welcome; for larger changes, please open an issue to discuss first.
| 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/image | image OSS download and indexing |
| 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.
MIT — see LICENSE.