@captain-app/openclaw 2026.2.4

package/docs/reference/AGENTS.default.md

@@ -0,0 +1,124 @@
+---
+summary: "Default OpenClaw agent instructions and skills roster for the personal assistant setup"
+read_when:
+  - Starting a new OpenClaw agent session
+  - Enabling or auditing default skills
+---
+
+# AGENTS.md — OpenClaw Personal Assistant (default)
+
+## First run (recommended)
+
+OpenClaw uses a dedicated workspace directory for the agent. Default: `~/.openclaw/workspace` (configurable via `agents.defaults.workspace`).
+
+1. Create the workspace (if it doesn’t already exist):
+
+```bash
+mkdir -p ~/.openclaw/workspace
+```
+
+2. Copy the default workspace templates into the workspace:
+
+```bash
+cp docs/reference/templates/AGENTS.md ~/.openclaw/workspace/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/.openclaw/workspace/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/.openclaw/workspace/TOOLS.md
+```
+
+3. Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+
+```bash
+cp docs/reference/AGENTS.default.md ~/.openclaw/workspace/AGENTS.md
+```
+
+4. Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
+
+```json5
+{
+  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
+}
+```
+
+## Safety defaults
+
+- Don’t dump directories or secrets into chat.
+- Don’t run destructive commands unless explicitly asked.
+- Don’t send partial/streaming replies to external messaging surfaces (only final replies).
+
+## Session start (required)
+
+- Read `SOUL.md`, `USER.md`, `memory.md`, and today+yesterday in `memory/`.
+- Do it before responding.
+
+## Soul (required)
+
+- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
+- If you change `SOUL.md`, tell the user.
+- You are a fresh instance each session; continuity lives in these files.
+
+## Shared spaces (recommended)
+
+- You’re not the user’s voice; be careful in group chats or public channels.
+- Don’t share private data, contact info, or internal notes.
+
+## Memory system (recommended)
+
+- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
+- Long-term memory: `memory.md` for durable facts, preferences, and decisions.
+- On session start, read today + yesterday + `memory.md` if present.
+- Capture: decisions, preferences, constraints, open loops.
+- Avoid secrets unless explicitly requested.
+
+## Tools & skills
+
+- Tools live in skills; follow each skill’s `SKILL.md` when you need it.
+- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+
+## Backup tip (recommended)
+
+If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
+
+```bash
+cd ~/.openclaw/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# Optional: add a private remote + push
+```
+
+## What OpenClaw Does
+
+- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
+- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `openclaw` CLI via its bundled binary.
+- Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<channel>:group:<id>` (rooms/channels: `agent:<agentId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.
+
+## Core Skills (enable in Settings → Skills)
+
+- **mcporter** — Tool server runtime/CLI for managing external skill backends.
+- **Peekaboo** — Fast macOS screenshots with optional AI vision analysis.
+- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
+- **oracle** — OpenAI-ready agent CLI with session replay and browser control.
+- **eightctl** — Control your sleep, from the terminal.
+- **imsg** — Send, read, stream iMessage & SMS.
+- **wacli** — WhatsApp CLI: sync, search, send.
+- **discord** — Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
+- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+- **spotify-player** — Terminal Spotify client to search/queue/control playback.
+- **sag** — ElevenLabs speech with mac-style say UX; streams to speakers by default.
+- **Sonos CLI** — Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
+- **blucli** — Play, group, and automate BluOS players from scripts.
+- **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
+- **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
+- **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
+- **bird** — X/Twitter CLI to tweet, reply, read threads, and search without a browser.
+- **agent-tools** — Utility toolkit for automations and helper scripts.
+
+## Usage Notes
+
+- Prefer the `openclaw` CLI for scripting; mac app handles permissions.
+- Run installs from the Skills tab; it hides the button if a binary is already present.
+- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
+- For browser-driven verification, use `openclaw browser` (tabs/status/screenshot) with the OpenClaw-managed Chrome profile.
+- For DOM inspection, use `openclaw browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
+- For interactions, use `openclaw browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).

package/docs/reference/RELEASING.md

@@ -0,0 +1,120 @@
+---
+summary: "Step-by-step release checklist for npm + macOS app"
+read_when:
+  - Cutting a new npm release
+  - Cutting a new macOS app release
+  - Verifying metadata before publishing
+---
+
+# Release Checklist (npm + macOS)
+
+Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tagging/publishing.
+
+## Operator trigger
+
+When the operator says “release”, immediately do this preflight (no extra questions unless blocked):
+
+- Read this doc and `docs/platforms/mac/release.md`.
+- Load env from `~/.profile` and confirm `SPARKLE_PRIVATE_KEY_FILE` + App Store Connect vars are set (SPARKLE_PRIVATE_KEY_FILE should live in `~/.profile`).
+- Use Sparkle keys from `~/Library/CloudStorage/Dropbox/Backup/Sparkle` if needed.
+
+1. **Version & metadata**
+
+- [ ] Bump `package.json` version (e.g., `2026.1.29`).
+- [ ] Run `pnpm plugins:sync` to align extension package versions + changelogs.
+- [ ] Update CLI/version strings: [`src/cli/program.ts`](https://github.com/openclaw/openclaw/blob/main/src/cli/program.ts) and the Baileys user agent in [`src/provider-web.ts`](https://github.com/openclaw/openclaw/blob/main/src/provider-web.ts).
+- [ ] Confirm package metadata (name, description, repository, keywords, license) and `bin` map points to [`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs) for `openclaw`.
+- [ ] If dependencies changed, run `pnpm install` so `pnpm-lock.yaml` is current.
+
+2. **Build & artifacts**
+
+- [ ] If A2UI inputs changed, run `pnpm canvas:a2ui:bundle` and commit any updated [`src/canvas-host/a2ui/a2ui.bundle.js`](https://github.com/openclaw/openclaw/blob/main/src/canvas-host/a2ui/a2ui.bundle.js).
+- [ ] `pnpm run build` (regenerates `dist/`).
+- [ ] Verify npm package `files` includes all required `dist/*` folders (notably `dist/node-host/**` and `dist/acp/**` for headless node + ACP CLI).
+- [ ] Confirm `dist/build-info.json` exists and includes the expected `commit` hash (CLI banner uses this for npm installs).
+- [ ] Optional: `npm pack --pack-destination /tmp` after the build; inspect the tarball contents and keep it handy for the GitHub release (do **not** commit it).
+
+3. **Changelog & docs**
+
+- [ ] Update `CHANGELOG.md` with user-facing highlights (create the file if missing); keep entries strictly descending by version.
+- [ ] Ensure README examples/flags match current CLI behavior (notably new commands or options).
+
+4. **Validation**
+
+- [ ] `pnpm build`
+- [ ] `pnpm check`
+- [ ] `pnpm test` (or `pnpm test:coverage` if you need coverage output)
+- [ ] `pnpm release:check` (verifies npm pack contents)
+- [ ] `OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke` (Docker install smoke test, fast path; required before release)
+  - If the immediate previous npm release is known broken, set `OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version>` or `OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1` for the preinstall step.
+- [ ] (Optional) Full installer smoke (adds non-root + CLI coverage): `pnpm test:install:smoke`
+- [ ] (Optional) Installer E2E (Docker, runs `curl -fsSL https://openclaw.ai/install.sh | bash`, onboards, then runs real tool calls):
+  - `pnpm test:install:e2e:openai` (requires `OPENAI_API_KEY`)
+  - `pnpm test:install:e2e:anthropic` (requires `ANTHROPIC_API_KEY`)
+  - `pnpm test:install:e2e` (requires both keys; runs both providers)
+- [ ] (Optional) Spot-check the web gateway if your changes affect send/receive paths.
+
+5. **macOS app (Sparkle)**
+
+- [ ] Build + sign the macOS app, then zip it for distribution.
+- [ ] Generate the Sparkle appcast (HTML notes via [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)) and update `appcast.xml`.
+- [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
+- [ ] Follow [macOS release](/platforms/mac/release) for the exact commands and required env vars.
+  - `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
+  - If notarizing, use the `openclaw-notary` keychain profile created from App Store Connect API env vars (see [macOS release](/platforms/mac/release)).
+
+6. **Publish (npm)**
+
+- [ ] Confirm git status is clean; commit and push as needed.
+- [ ] `npm login` (verify 2FA) if needed.
+- [ ] `npm publish --access public` (use `--tag beta` for pre-releases).
+- [ ] Verify the registry: `npm view openclaw version`, `npm view openclaw dist-tags`, and `npx -y openclaw@X.Y.Z --version` (or `--help`).
+
+### Troubleshooting (notes from 2.0.0-beta2 release)
+
+- **npm pack/publish hangs or produces huge tarball**: the macOS app bundle in `dist/OpenClaw.app` (and release zips) get swept into the package. Fix by whitelisting publish contents via `package.json` `files` (include dist subdirs, docs, skills; exclude app bundles). Confirm with `npm pack --dry-run` that `dist/OpenClaw.app` is not listed.
+- **npm auth web loop for dist-tags**: use legacy auth to get an OTP prompt:
+  - `NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add openclaw@X.Y.Z latest`
+- **`npx` verification fails with `ECOMPROMISED: Lock compromised`**: retry with a fresh cache:
+  - `NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y openclaw@X.Y.Z --version`
+- **Tag needs repointing after a late fix**: force-update and push the tag, then ensure the GitHub release assets still match:
+  - `git tag -f vX.Y.Z && git push -f origin vX.Y.Z`
+
+7. **GitHub release + appcast**
+
+- [ ] Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z` (or `git push --tags`).
+- [ ] Create/refresh the GitHub release for `vX.Y.Z` with **title `openclaw X.Y.Z`** (not just the tag); body should include the **full** changelog section for that version (Highlights + Changes + Fixes), inline (no bare links), and **must not repeat the title inside the body**.
+- [ ] Attach artifacts: `npm pack` tarball (optional), `OpenClaw-X.Y.Z.zip`, and `OpenClaw-X.Y.Z.dSYM.zip` (if generated).
+- [ ] Commit the updated `appcast.xml` and push it (Sparkle feeds from main).
+- [ ] From a clean temp directory (no `package.json`), run `npx -y openclaw@X.Y.Z send --help` to confirm install/CLI entrypoints work.
+- [ ] Announce/share release notes.
+
+## Plugin publish scope (npm)
+
+We only publish **existing npm plugins** under the `@openclaw/*` scope. Bundled
+plugins that are not on npm stay **disk-tree only** (still shipped in
+`extensions/**`).
+
+Process to derive the list:
+
+1. `npm search @openclaw --json` and capture the package names.
+2. Compare with `extensions/*/package.json` names.
+3. Publish only the **intersection** (already on npm).
+
+Current npm plugin list (update as needed):
+
+- @openclaw/bluebubbles
+- @openclaw/diagnostics-otel
+- @openclaw/discord
+- @openclaw/feishu
+- @openclaw/lobster
+- @openclaw/matrix
+- @openclaw/msteams
+- @openclaw/nextcloud-talk
+- @openclaw/nostr
+- @openclaw/voice-call
+- @openclaw/zalo
+- @openclaw/zalouser
+
+Release notes must also call out **new optional bundled plugins** that are **not
+on by default** (example: `tlon`).

package/docs/reference/api-usage-costs.md

@@ -0,0 +1,137 @@
+---
+summary: "Audit what can spend money, which keys are used, and how to view usage"
+read_when:
+  - You want to understand which features may call paid APIs
+  - You need to audit keys, costs, and usage visibility
+  - You’re explaining /status or /usage cost reporting
+title: "API Usage and Costs"
+---
+
+# API usage & costs
+
+This doc lists **features that can invoke API keys** and where their costs show up. It focuses on
+OpenClaw features that can generate provider usage or paid API calls.
+
+## Where costs show up (chat + CLI)
+
+**Per-session cost snapshot**
+
+- `/status` shows the current session model, context usage, and last response tokens.
+- If the model uses **API-key auth**, `/status` also shows **estimated cost** for the last reply.
+
+**Per-message cost footer**
+
+- `/usage full` appends a usage footer to every reply, including **estimated cost** (API-key only).
+- `/usage tokens` shows tokens only; OAuth flows hide dollar cost.
+
+**CLI usage windows (provider quotas)**
+
+- `openclaw status --usage` and `openclaw channels list` show provider **usage windows**
+  (quota snapshots, not per-message costs).
+
+See [Token use & costs](/token-use) for details and examples.
+
+## How keys are discovered
+
+OpenClaw can pick up credentials from:
+
+- **Auth profiles** (per-agent, stored in `auth-profiles.json`).
+- **Environment variables** (e.g. `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`).
+- **Config** (`models.providers.*.apiKey`, `tools.web.search.*`, `tools.web.fetch.firecrawl.*`,
+  `memorySearch.*`, `talk.apiKey`).
+- **Skills** (`skills.entries.<name>.apiKey`) which may export keys to the skill process env.
+
+## Features that can spend keys
+
+### 1) Core model responses (chat + tools)
+
+Every reply or tool call uses the **current model provider** (OpenAI, Anthropic, etc). This is the
+primary source of usage and cost.
+
+See [Models](/providers/models) for pricing config and [Token use & costs](/token-use) for display.
+
+### 2) Media understanding (audio/image/video)
+
+Inbound media can be summarized/transcribed before the reply runs. This uses model/provider APIs.
+
+- Audio: OpenAI / Groq / Deepgram (now **auto-enabled** when keys exist).
+- Image: OpenAI / Anthropic / Google.
+- Video: Google.
+
+See [Media understanding](/nodes/media-understanding).
+
+### 3) Memory embeddings + semantic search
+
+Semantic memory search uses **embedding APIs** when configured for remote providers:
+
+- `memorySearch.provider = "openai"` → OpenAI embeddings
+- `memorySearch.provider = "gemini"` → Gemini embeddings
+- Optional fallback to OpenAI if local embeddings fail
+
+You can keep it local with `memorySearch.provider = "local"` (no API usage).
+
+See [Memory](/concepts/memory).
+
+### 4) Web search tool (Brave / Perplexity via OpenRouter)
+
+`web_search` uses API keys and may incur usage charges:
+
+- **Brave Search API**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
+- **Perplexity** (via OpenRouter): `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
+
+**Brave free tier (generous):**
+
+- **2,000 requests/month**
+- **1 request/second**
+- **Credit card required** for verification (no charge unless you upgrade)
+
+See [Web tools](/tools/web).
+
+### 5) Web fetch tool (Firecrawl)
+
+`web_fetch` can call **Firecrawl** when an API key is present:
+
+- `FIRECRAWL_API_KEY` or `tools.web.fetch.firecrawl.apiKey`
+
+If Firecrawl isn’t configured, the tool falls back to direct fetch + readability (no paid API).
+
+See [Web tools](/tools/web).
+
+### 6) Provider usage snapshots (status/health)
+
+Some status commands call **provider usage endpoints** to display quota windows or auth health.
+These are typically low-volume calls but still hit provider APIs:
+
+- `openclaw status --usage`
+- `openclaw models status --json`
+
+See [Models CLI](/cli/models).
+
+### 7) Compaction safeguard summarization
+
+The compaction safeguard can summarize session history using the **current model**, which
+invokes provider APIs when it runs.
+
+See [Session management + compaction](/reference/session-management-compaction).
+
+### 8) Model scan / probe
+
+`openclaw models scan` can probe OpenRouter models and uses `OPENROUTER_API_KEY` when
+probing is enabled.
+
+See [Models CLI](/cli/models).
+
+### 9) Talk (speech)
+
+Talk mode can invoke **ElevenLabs** when configured:
+
+- `ELEVENLABS_API_KEY` or `talk.apiKey`
+
+See [Talk mode](/nodes/talk).
+
+### 10) Skills (third-party APIs)
+
+Skills can store `apiKey` in `skills.entries.<name>.apiKey`. If a skill uses that key for external
+APIs, it can incur costs according to the skill’s provider.
+
+See [Skills](/tools/skills).

package/docs/reference/device-models.md

@@ -0,0 +1,47 @@
+---
+summary: "How OpenClaw vendors Apple device model identifiers for friendly names in the macOS app."
+read_when:
+  - Updating device model identifier mappings or NOTICE/license files
+  - Changing how Instances UI displays device names
+title: "Device Model Database"
+---
+
+# Device model database (friendly names)
+
+The macOS companion app shows friendly Apple device model names in the **Instances** UI by mapping Apple model identifiers (e.g. `iPad16,6`, `Mac16,6`) to human-readable names.
+
+The mapping is vendored as JSON under:
+
+- `apps/macos/Sources/OpenClaw/Resources/DeviceModels/`
+
+## Data source
+
+We currently vendor the mapping from the MIT-licensed repository:
+
+- `kyle-seongwoo-jun/apple-device-identifiers`
+
+To keep builds deterministic, the JSON files are pinned to specific upstream commits (recorded in `apps/macos/Sources/OpenClaw/Resources/DeviceModels/NOTICE.md`).
+
+## Updating the database
+
+1. Pick the upstream commits you want to pin to (one for iOS, one for macOS).
+2. Update the commit hashes in `apps/macos/Sources/OpenClaw/Resources/DeviceModels/NOTICE.md`.
+3. Re-download the JSON files, pinned to those commits:
+
+```bash
+IOS_COMMIT="<commit sha for ios-device-identifiers.json>"
+MAC_COMMIT="<commit sha for mac-device-identifiers.json>"
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${IOS_COMMIT}/ios-device-identifiers.json" \
+  -o apps/macos/Sources/OpenClaw/Resources/DeviceModels/ios-device-identifiers.json
+
+curl -fsSL "https://raw.githubusercontent.com/kyle-seongwoo-jun/apple-device-identifiers/${MAC_COMMIT}/mac-device-identifiers.json" \
+  -o apps/macos/Sources/OpenClaw/Resources/DeviceModels/mac-device-identifiers.json
+```
+
+4. Ensure `apps/macos/Sources/OpenClaw/Resources/DeviceModels/LICENSE.apple-device-identifiers.txt` still matches upstream (replace it if the upstream license changes).
+5. Verify the macOS app builds cleanly (no warnings):
+
+```bash
+swift build --package-path apps/macos
+```

package/docs/reference/rpc.md

@@ -0,0 +1,43 @@
+---
+summary: "RPC adapters for external CLIs (signal-cli, legacy imsg) and gateway patterns"
+read_when:
+  - Adding or changing external CLI integrations
+  - Debugging RPC adapters (signal-cli, imsg)
+title: "RPC Adapters"
+---
+
+# RPC adapters
+
+OpenClaw integrates external CLIs via JSON-RPC. Two patterns are used today.
+
+## Pattern A: HTTP daemon (signal-cli)
+
+- `signal-cli` runs as a daemon with JSON-RPC over HTTP.
+- Event stream is SSE (`/api/v1/events`).
+- Health probe: `/api/v1/check`.
+- OpenClaw owns lifecycle when `channels.signal.autoStart=true`.
+
+See [Signal](/channels/signal) for setup and endpoints.
+
+## Pattern B: stdio child process (legacy: imsg)
+
+> **Note:** For new iMessage setups, use [BlueBubbles](/channels/bluebubbles) instead.
+
+- OpenClaw spawns `imsg rpc` as a child process (legacy iMessage integration).
+- JSON-RPC is line-delimited over stdin/stdout (one JSON object per line).
+- No TCP port, no daemon required.
+
+Core methods used:
+
+- `watch.subscribe` → notifications (`method: "message"`)
+- `watch.unsubscribe`
+- `send`
+- `chats.list` (probe/diagnostics)
+
+See [iMessage](/channels/imessage) for legacy setup and addressing (`chat_id` preferred).
+
+## Adapter guidelines
+
+- Gateway owns the process (start/stop tied to provider lifecycle).
+- Keep RPC clients resilient: timeouts, restart on exit.
+- Prefer stable IDs (e.g., `chat_id`) over display strings.