diff --git a/docs/guides/memory-systems.md b/docs/guides/memory-systems.md index 617d9f4..1797cae 100644 --- a/docs/guides/memory-systems.md +++ b/docs/guides/memory-systems.md @@ -59,7 +59,7 @@ v2026.8.1 ("OpenClaw 2.0") retired the QMD memory backend. Built-in memory now o To make the agent remember something, ask it: "Remember that I prefer TypeScript." It writes the note to the right file. Before [compaction](https://docs.openclaw.ai/concepts/compaction) summarises a long conversation, OpenClaw also runs a silent "memory flush" turn so the agent can save important context first (on by default; `agents.defaults.compaction.memoryFlush.enabled: false` turns it off). -Use `/context list` or `openclaw doctor` to see how much of `MEMORY.md` is actually reaching the model. +Use `/context list` or `/context detail` in chat to see how much of `MEMORY.md` is actually reaching the model (raw versus injected size, and whether it was truncated). ### Configuration @@ -201,18 +201,7 @@ None of these is maintained by the OpenClaw project. Star counts and last-push d - **Repo:** [mem0ai/mem0](https://github.com/mem0ai/mem0) - **Integration:** Python/TypeScript SDK and API; hosted platform or self-hosted -- **Fit:** teams that want a managed service with analytics and support - -```python -from mem0 import Memory -m = Memory() -m.add("User prefers TypeScript over JavaScript", user_id="alex") -results = m.search("What languages does the user prefer?", user_id="alex") -``` - -:::info -Mem0 is not OpenClaw-specific. You connect it yourself, through a custom plugin, skill or MCP server. -::: +- **Fit:** teams that want a managed service with analytics and support. Mem0 is not OpenClaw-specific: you connect it yourself, through a custom plugin, skill or MCP server. --- @@ -371,43 +360,13 @@ A plugin runs inside the Gateway process with the Gateway's permissions, so trea Remember that whatever memory is loaded into a prompt is sent to your model provider. -### By Use Case - -| Use Case | Pick | Why | -|----------|------|-----| -| **General assistant** | Built-in | No setup, plain files | -| **Curated knowledge base** | Memory Wiki | Claims, evidence, freshness tracking | -| **Coding agent** | claude-mem | Built for dev context | -| **Research agent** | Cognee or Hindsight | Structured knowledge | -| **Shared context across agents** | PowerContext | Context outside any one session | -| **Long conversations** | Lossless Claw | Replaces lossy compaction | -| **Total recall** | MemPalace | Stores everything verbatim | - --- ## Getting Started -### Keep It Simple - -New to OpenClaw? Use the built-in memory and change nothing. Dreaming is already on. The one setting worth deciding early is the embedding provider: leave the default (OpenAI) if you are already using OpenAI, or pick a local provider if you want memory to stay on the machine (see [Configuration](#configuration)). - -Then check that it works: - -```bash -openclaw memory status -``` - -### When to Upgrade - -Consider adding something when: -- Built-in recall misses things you know are in your notes (first try `openclaw memory search` and a better embedding provider) -- Compaction is losing detail you need later -- You need memory shared across several agents or people -- You need structured knowledge (entities, relationships) - -### Try Before Committing +Use the built-in memory and change nothing; Dreaming is already on. The one setting worth deciding early is the embedding provider: the default sends note text to OpenAI, so pick a local provider if memory must stay on the machine (see [Configuration](#configuration)). Check it with `openclaw memory status`. -Most community systems run alongside the built-in memory. Add one as an MCP server, use it for a week, and compare. You rarely need to replace `memory-core`; you can add to it. +Add something else only when built-in recall misses notes you know exist (try `openclaw memory search` and a better embedding provider first), compaction loses detail you need, or several agents or people need shared or structured memory. Most community systems run beside `memory-core` rather than replacing it, so trial one as an MCP server for a week before committing. --- diff --git a/docs/guides/migration.md b/docs/guides/migration.md index 6bf0b6f..a2f0f90 100644 --- a/docs/guides/migration.md +++ b/docs/guides/migration.md @@ -159,7 +159,7 @@ The supported route: ``` The archive contains credentials. Store it with owner-only permissions. -2. **Update with `openclaw update`** rather than a raw `npm i -g`. It stages the new version, runs Doctor, verifies the Gateway, keeps the previous package during activation, and rolls back automatically when post-update checks fail. Preview with `openclaw update --dry-run`. +2. **Update with `openclaw update`** rather than a raw `npm i -g`. It stages the new version, runs Doctor, verifies the Gateway and keeps the previous package during activation. If verification fails, it rolls back automatically only when no database schema changed (upstream calls this schema-neutral rollback). Once Doctor has migrated a database, the updater keeps the new state, reports `state-migrated-no-rollback`, and you recover from your backup. Preview with `openclaw update --dry-run`. 3. **To go back to an older release**, restore a verified pre-update backup together with the OpenClaw release that made it. Do not run an older release against migrated state. 4. **Clean up only after verifying.** `openclaw update cleanup` retires recovery originals; run it only once your sessions and channels work. @@ -221,16 +221,9 @@ Credentials are imported only when you accept the prompt or pass `--include-secr **Do not run anything older.** [CVE-2026-25253](https://nvd.nist.gov/vuln/detail/CVE-2026-25253) (CVSS 8.8, High): before 2026.1.29, the Control UI took a `gatewayUrl` from the query string and connected to it without prompting, sending the gateway token. A crafted link could hand an attacker your token and, through it, command execution on the host. The same release removed the old implicit no-auth mode (an explicit loopback-only `none` mode was later reintroduced, see above). -### v2026.1.30: CLI improvements (January 31) - -- Shell completion: `openclaw completion` (Zsh, Bash, PowerShell, Fish) -- Per-agent model status: `openclaw models status --agent ` -- New providers: Kimi K2.5, MiniMax OAuth - ### v2026.2.6: code safety scanner (February 6) -- New model support: Claude Opus 4.6, GPT-5.3-Codex, xAI Grok -- Built-in code safety scanner for skills and plugins; credentials redacted from `config.get` gateway responses +Added a built-in code safety scanner for skills and plugins, and redacted credentials from `config.get` Gateway responses. ClawHub added VirusTotal scanning on publish in the same month, in response to the [ClawHavoc campaign](/security/known-vulnerabilities#the-clawhavoc-campaign). See [Skill Verification](/security/skill-verification) for how scanning works today. diff --git a/docs/guides/model-selection.md b/docs/guides/model-selection.md index 6e1c274..266a15f 100644 --- a/docs/guides/model-selection.md +++ b/docs/guides/model-selection.md @@ -113,17 +113,10 @@ Current Claude models (Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5) and Opus/Sonn ### Tool use (agent workloads) -OpenClaw relies on reliable function calling with streamed tool-call deltas and well-formed JSON arguments. - -| Model class | Tool-use reliability | -|---|---| -| Current Claude, GPT-6 and Gemini models | Reliable | -| DeepSeek V4 | Good | -| Local 30B+ models (Qwen3 32B, Llama 3.3 70B) | Good, with enough context (`num_ctx`) configured | -| Local models under ~14B | Often fail multi-step tool chains | +OpenClaw needs reliable function calling: streamed tool-call deltas and well-formed JSON arguments. Current Claude, GPT-6 and Gemini models handle multi-step tool chains well; DeepSeek V4 and 30B+ local models (Qwen3 32B, Llama 3.3 70B) usually do, given enough context (`num_ctx`). This is clawdocs' judgement from use, not a benchmark. :::caution -Local models smaller than about 14B parameters often struggle with multi-step tool calling. For reliable agent behaviour, use 30B+ local models or a cloud model. Small local models are also easier to manipulate with prompt injection, so keep approvals on for tools that act on your system ([Hardening](/security/hardening)). +Local models smaller than about 14B parameters often fail multi-step tool calls. They are also easier to manipulate with prompt injection, so keep approvals on for tools that act on your system ([Hardening](/security/hardening)). ::: --- diff --git a/docs/guides/monitoring.md b/docs/guides/monitoring.md index 017ab28..1f812f2 100644 --- a/docs/guides/monitoring.md +++ b/docs/guides/monitoring.md @@ -29,7 +29,7 @@ openclaw health --json # same, machine-readable openclaw gateway status # service and RPC probe ``` -`openclaw doctor` is a diagnose-and-repair tool, not a health check. Use it after upgrades or when something is broken, not as a liveness probe; `doctor --fix` writes changes. +`openclaw doctor` is a diagnose-and-repair tool, not a health check. Even without `--fix` it can migrate config and state, so do not use it as a probe. For a read-only report (for example in CI), use `openclaw doctor --lint`. ### Component checks @@ -247,7 +247,7 @@ Notes: - `protocol` accepts only `http/protobuf`; gRPC was retired. Doctor rewrites an old `grpc` value. - When `endpoint` is unset, the standard `OTEL_EXPORTER_OTLP_*` variables are used as a fallback. - `captureContent` (default off) puts raw message and tool content in span attributes. Leave it off unless your collector's retention policy allows that data. -- `openclaw status --all` and `openclaw doctor` show exporter health per signal. +- `openclaw status --all` (read-only) shows exporter health per signal. - `openclaw agent exec` runs do not export telemetry; dispatch through the Gateway or use `openclaw agent --local`. Field reference, metric names and span names: [Setup](https://docs.openclaw.ai/gateway/opentelemetry/setup), [Configuration](https://docs.openclaw.ai/gateway/opentelemetry/configuration), [Privacy and trace context](https://docs.openclaw.ai/gateway/opentelemetry/privacy-and-trace-context). @@ -257,7 +257,7 @@ Field reference, metric names and span names: [Setup](https://docs.openclaw.ai/g ```yaml title="docker-compose.otel.yml (add to your existing compose)" services: jaeger: - image: jaegertracing/all-in-one:latest + image: jaegertracing/jaeger:latest # Jaeger v2; the v1 all-in-one image is end-of-life ports: - "127.0.0.1:16686:16686" # Jaeger UI ``` diff --git a/docs/guides/multi-agent.md b/docs/guides/multi-agent.md index b39cc55..d465fc3 100644 --- a/docs/guides/multi-agent.md +++ b/docs/guides/multi-agent.md @@ -227,92 +227,19 @@ The equivalent hand-written roster: the lead may delegate to the three specialis Sub-agent sessions receive only `AGENTS.md`, not `SOUL.md`, `IDENTITY.md`, `USER.md` or `MEMORY.md`. Put anything a worker must follow in `AGENTS.md`. -### Workboard Messaging {#workboard-messaging} - -From the terminal, an operator can create and move cards (the Workboard plugin must be enabled): - -```bash -openclaw workboard create "Research competitor pricing" --agent researcher --priority high -openclaw workboard list --status ready -openclaw workboard move 7f4a2c10 --status done -``` - -Claiming, linking parent and child cards, and completing are agent tools (`workboard_claim`, `workboard_link`, `workboard_complete`), not CLI subcommands. - ### MCP-Based Communication {#mcp-based-communication} `openclaw mcp serve` exposes OpenClaw **channel conversations** over MCP to an MCP client. It does not export one agent's skills as tools and has no `--agent` flag. For agent-to-agent delegation on one Gateway, use sub-agents or `sessions_send`. See [`openclaw mcp`](https://docs.openclaw.ai/cli/mcp). -### ClawTeam Communication {#clawteam-communication} - -[ClawTeam-OpenClaw](https://github.com/win4r/ClawTeam-OpenClaw) (community, 1,464 stars, last push 2026-07-03, as of 2026-10-18) spawns workers in git worktrees and gives them file-based inboxes: - -```bash -clawteam inbox send my-team leader "Auth done. All tests passing." -clawteam inbox broadcast my-team "Stand-up: report your status" -clawteam inbox peek -``` - -See [ClawTeam-OpenClaw](#clawteam-openclaw) below for installation. - --- -## Workboard Orchestration +## Workboard Orchestration {#workboard-orchestration} -[Workboard](/guides/workboard) is a bundled plugin, disabled by default, that tracks work as cards. Enable it with `openclaw plugins enable workboard`. Upstream references: [plugin](https://docs.openclaw.ai/plugins/workboard), [CLI](https://docs.openclaw.ai/cli/workboard). +[Workboard](/guides/workboard) is a bundled plugin, disabled by default, that tracks work as cards with statuses, dependencies, claims and run history. Enable it with `openclaw plugins enable workboard`. For multi-agent work, three things matter: -### Card Lifecycle {#card-lifecycle} - -Statuses: `triage`, `backlog`, `todo`, `scheduled`, `ready`, `running`, `review`, `blocked`, `done`. - -``` -triage/backlog → todo → ready → running → review → done - ↓ - blocked -``` - -- A child card linked to parents stays in `todo` until every parent is `done`. Dispatch then promotes it to `ready`. -- While a card is running, it follows its linked session: active → `running`, completed → `review`, failed, killed, timed out or aborted → `blocked`. -- Moving a card to `review`, `blocked` or `done` by hand stops that auto-sync. - -### Agent Coordination Tools {#agent-coordination-tools} - -Card tools are **optional plugin tools**. With the plugin enabled, an agent sees only the `workboard_sessions_board_*` tools until you allow the rest: - -```json5 title="~/.openclaw/openclaw.json" -{ - agents: { - ownership: "explicit", - defaults: { systemAgent: { agentId: "main" } }, - entries: { - main: { - workspace: "~/.openclaw/workspace", - tools: { alsoAllow: ["workboard"] }, - }, - coder: { workspace: "~/.openclaw/workspace-coder" }, - }, - }, - plugins: { entries: { workboard: { enabled: true } } }, -} -``` - -Workers that Workboard starts from a card get `workboard_heartbeat`, `workboard_complete` and `workboard_block` for that card automatically. - -| Tool | Purpose | -|------|---------| -| `workboard_list` / `workboard_read` | List cards; read one card with worker context | -| `workboard_create` / `workboard_decompose` | Create a card; fan a parent card out into linked children | -| `workboard_link` | Link a parent to a child (child waits until the parent is done) | -| `workboard_claim` / `workboard_release` | Claim a card (moves it to `running`); release it | -| `workboard_complete` / `workboard_block` | Finish with a summary and proof, or block with a reason | -| `workboard_promote` / `workboard_reassign` / `workboard_reclaim` | Recover or hand off stuck work | -| `workboard_dispatch` | Nudge dependency promotion and stale-claim cleanup; does **not** launch workers | - -### Dispatch Workflow {#dispatch-workflow} - -Dispatch is triggered, not continuous: run `openclaw workboard dispatch`, use the dashboard, or the `/workboard` slash command. One pass promotes dependency-ready children to `ready`, blocks expired claims, and starts worker runs: at most 3 per pass by default (`--max-starts`), and only one card per owner or agent. - -### Autonomous Sub-Tasks {#autonomous-sub-tasks} +- **Agents need the card tools allowed.** With the plugin enabled, agents get only the `workboard_sessions_board_*` tools. Add `tools: { alsoAllow: ["workboard"] }` to an orchestrator's `agents.entries.` so it can create, link, claim and complete cards. Workers that Workboard starts from a card get `workboard_heartbeat`, `workboard_complete` and `workboard_block` for that card automatically. +- **Dependencies.** A child card linked to parents waits in `todo` until every parent is `done`; the next dispatch promotes it to `ready`. +- **Dispatch is triggered, not continuous.** Run `openclaw workboard dispatch`, use the dashboard, or send `/workboard dispatch`. One pass starts at most 3 workers by default (`--max-starts`), one card per owner or agent. The agent-side `workboard_dispatch` tool does not start workers. ``` Lead agent Workboard Specialist agents @@ -327,15 +254,7 @@ Lead agent Workboard Specialist agents │◄── notify ─────────────────│◄── complete ───────────────┤ writer ``` -### Self-Organizing Heartbeat {#self-organizing-heartbeat} - -Do not put a Workboard checklist in `HEARTBEAT.md`; that file is no longer read. Make it an automation job owned by the agent: - -```bash -openclaw automations add "every 2h" \ - "Check the Workboard for blocked cards you own and unclaimed cards that match your role. Unblock or claim, then report status." \ - --name workboard-sweep --agent coder --session isolated -``` +The [Workboard guide](/guides/workboard) has the card lifecycle, CLI, tool list and recipes, including a scheduled board review as an automation job (not a `HEARTBEAT.md` checklist, which is no longer read). --- @@ -343,13 +262,9 @@ openclaw automations add "every 2h" \ These are community projects, not part of OpenClaw. Read their code and install scripts before you run them, and run them against a test Gateway first. -### Mission Control {#mission-control} - -`abhi1693/openclaw-mission-control` is **archived** (last push 2026-08-06; its README says the project moved to Wardn AI). Do not deploy it for new setups. - ### ClawTeam-OpenClaw {#clawteam-openclaw} -[ClawTeam-OpenClaw](https://github.com/win4r/ClawTeam-OpenClaw) (1,464 stars as of 2026-10-18; last push 2026-07-03) is a Python CLI where a leader agent spawns workers into git worktrees, with inboxes, a task board and a cost view. +[ClawTeam-OpenClaw](https://github.com/win4r/ClawTeam-OpenClaw) (1,464 stars as of 2026-10-18; last push 2026-07-03) is a Python CLI where a leader agent spawns workers into git worktrees, with file-based inboxes (`clawteam inbox send`), a task board and a cost view. :::warning Install from the repo The project README warns that `pip install clawteam` installs a different upstream version and `npm install -g clawteam` is an unrelated package. Install from a clone: @@ -371,15 +286,9 @@ clawteam board cost # token and cost view ### Antfarm {#antfarm} -[Antfarm](https://github.com/snarktank/antfarm) (2,496 stars as of 2026-10-18; no push since 2026-02-26) installs YAML-defined agent teams (`feature-dev`, `security-audit`, `bug-fix`) into OpenClaw, with cron polling. It installs from GitHub, not npm: the `antfarm` package on npm is an unrelated project, so do not `npx antfarm`. Follow the install steps in the [Antfarm README](https://github.com/snarktank/antfarm#install) and read its install script before running it. It predates OpenClaw 2.0's keyed `agents.entries` roster, so check what it writes to your config and run `openclaw doctor` afterwards. - -### ClawDeck & ClawController - -[ClawDeck](https://clawdeck.io/) and [ClawController](https://www.clawcontroller.com/) are commercial dashboards. Not reviewed here. +[Antfarm](https://github.com/snarktank/antfarm) (2,496 stars as of 2026-10-18; no push since 2026-02-26) installs YAML-defined agent teams (`feature-dev`, `security-audit`, `bug-fix`) into OpenClaw, with cron polling. It installs from GitHub, not npm: the `antfarm` package on npm is an unrelated project, so do not `npx antfarm`. Follow the install steps in the [Antfarm README](https://github.com/snarktank/antfarm#install) and read its install script before running it. It predates OpenClaw 2.0's keyed `agents.entries` roster, so check what it writes to your config: `openclaw doctor --lint` reports problems without changing anything, and `openclaw doctor --fix` migrates an old `agents.list`. -### DigitalOcean App Platform - -[DigitalOcean App Platform](https://www.digitalocean.com/blog/openclaw-digitalocean-app-platform) hosts OpenClaw with managed scaling. Not reviewed here. +Other dashboards and hosted options are listed, unreviewed, on [Ecosystem](/reference/ecosystem). `abhi1693/openclaw-mission-control` is archived (its README says it moved to Wardn AI); do not deploy it for new setups. --- @@ -433,8 +342,6 @@ By default each agent has isolated memory: its own `MEMORY.md`, daily notes and | Separate Memory Wiki per agent | `plugins.entries.memory-wiki.config.vault.scope: "agent"` ([Memory Wiki](https://docs.openclaw.ai/plugins/memory-wiki)) | | External shared memory | Third-party systems; see [Memory Systems](/guides/memory-systems) | -PowerMem has been renamed [PowerContext](https://github.com/oceanbase/powercontext) (`oceanbase/powercontext`, 1,337 stars as of 2026-10-18). It advertises multi-agent memory isolation and sharing; not tested here. - Dreaming (memory consolidation) runs as one sweep with one `frequency`. The Control UI agent selector changes which agent you view, not its schedule. --- diff --git a/docs/guides/performance-tuning.md b/docs/guides/performance-tuning.md index 652f135..da1d3da 100644 --- a/docs/guides/performance-tuning.md +++ b/docs/guides/performance-tuning.md @@ -187,16 +187,17 @@ See [Multi-agent routing](https://docs.openclaw.ai/concepts/multi-agent). ## Memory -Built-in memory search runs locally. Two settings matter for performance: +The memory index is a local SQLite database, but embeddings are not local by default. Two settings matter for performance: -- **Embeddings.** Remote embedding providers add latency and cost per indexing run. A local embedding model avoids both ([Memory search](https://docs.openclaw.ai/concepts/memory-search)). -- **Dreaming** (background consolidation in the `memory-core` plugin) is on by default and runs on a cron-style `frequency` (default `0 3 * * *`). Move it to a quiet hour or give it a cheaper `model`: +- **Embeddings.** The default provider is OpenAI, so every indexing run and search makes a remote call. A local embedding provider (`memory.search.provider: "local"` or `"ollama"`) avoids that latency and cost ([Memory search](https://docs.openclaw.ai/concepts/memory-search)). +- **Dreaming** (background consolidation in the `memory-core` plugin) is on by default and runs on a cron-style `frequency` (default `0 3 * * *`). Move it to a quiet hour. `dreaming.model` sets the model for its Dream Diary entries; it takes effect only with `subagent.allowModelOverride: true` on the plugin entry: ```json5 title="~/.openclaw/openclaw.json" { plugins: { entries: { "memory-core": { + subagent: { allowModelOverride: true }, config: { dreaming: { enabled: true, @@ -289,11 +290,12 @@ To reduce baseline memory, disable channels and plugins you don't use (`openclaw | Path | What grows | |---|---| | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` | Gateway logs. Rotated at `logging.maxFileBytes` (default 100 MB) with 5 archives; dated files are pruned after 24 hours ([Logging](https://docs.openclaw.ai/logging)). | -| `~/.openclaw/state/` | SQLite state: sessions, transcripts, audit ledger | +| `~/.openclaw/agents//agent/` | Per-agent SQLite database: sessions, transcripts, memory index | +| `~/.openclaw/state/` | Shared SQLite state: audit ledger, MCP OAuth tokens | | `~/.openclaw/workspace/` | Workspace files and memory | ```bash -du -sh ~/.openclaw/ ~/.openclaw/state ~/.openclaw/workspace /tmp/openclaw +du -sh ~/.openclaw/ ~/.openclaw/agents ~/.openclaw/state ~/.openclaw/workspace /tmp/openclaw ``` ```json5 title="~/.openclaw/openclaw.json" diff --git a/docs/guides/plugin-system.md b/docs/guides/plugin-system.md index 77a91fa..11ccacf 100644 --- a/docs/guides/plugin-system.md +++ b/docs/guides/plugin-system.md @@ -77,7 +77,7 @@ ClawHub packages and OpenClaw's bundled and official catalogue are trusted sourc ### Bundled -Bundled plugins ship with OpenClaw. A little over half are on by default, mostly model and speech providers. Others need enabling or relevant config: +Bundled plugins ship with OpenClaw. Many, mostly model and speech providers, are on by default; others need enabling or relevant config. `openclaw plugins list --verbose` shows which. Two you are likely to touch: | Plugin | Purpose | Default | |---|---|---| @@ -335,7 +335,7 @@ clawhub package publish ./my-plugin --family code-plugin ```bash openclaw plugins inspect --runtime --json openclaw plugins doctor -openclaw doctor +openclaw doctor --lint # read-only; plain `openclaw doctor` may migrate config and state ``` **Plugin is listed but its tools are missing:** check `plugins.allow` (an exclusive list), `plugins.deny`, and that each tool is in `contracts.tools`. diff --git a/docs/guides/privacy-compliance.md b/docs/guides/privacy-compliance.md index 68b9069..042f839 100644 --- a/docs/guides/privacy-compliance.md +++ b/docs/guides/privacy-compliance.md @@ -11,8 +11,8 @@ keywords: [openclaw, privacy, gdpr, compliance, data protection, telemetry, upda This page sets out what OpenClaw sends off your machine, what it keeps on disk, and how to delete it. Facts come from the upstream docs for v2026.10.4 and were checked on 2026-10-18. It is not legal advice. Whether a deployment complies with GDPR, HIPAA or a SOC 2 control set depends on how you use it, so take the specifics to your own counsel or auditor. -:::warning Gartner assessment (February 2026) -Gartner called OpenClaw "a dangerous preview of agentic AI" with "insecure by default risks like plaintext credential storage", and recommended that enterprises block it unless it runs in isolated non-production VMs with throwaway credentials. Some of that has changed since: Gateway auth is now required by default, and SecretRefs can replace plaintext credentials ([Security Overview](/security/overview#what-is-on-by-default)). +:::warning Gartner assessment (January 2026) +Gartner's First Take of 29 January 2026, ["OpenClaw (Formerly Moltbot, Clawdbot): Agentic Productivity Comes With Unacceptable Cybersecurity Risk"](https://www.gartner.com/en/documents/7381830) (paywalled), recommended that enterprises block OpenClaw downloads and traffic, and that anyone who must run it do so only in isolated non-production VMs with throwaway credentials. [The Register's summary](https://www.theregister.com/2026/02/04/cloud_hosted_openclaw/) quotes it calling OpenClaw "a dangerous preview of agentic AI" with "insecure by default" risks, including plaintext credential storage. Two of those points have changed since: Gateway auth is now required by default, and SecretRefs can replace plaintext credentials ([Security Overview](/security/overview#what-is-on-by-default)). Most stored data is still unencrypted (see below). ::: --- @@ -228,10 +228,7 @@ OpenClaw can run fully offline with a local model, with these caveats: ### Network segmentation -- Keep the Gateway on loopback and reach it through an SSH tunnel, Tailscale Serve or Cloudflare Access ([Security Hardening](/security/hardening#remote-access)). -- Don't give it access to internal services or databases it doesn't need. -- Docker: publish the port to `127.0.0.1` only. Docker-published ports bypass host firewalls such as ufw ([firewall](/security/hardening#firewall)). -- Restrict outbound traffic to the providers you use. +Keep the Gateway on loopback, publish Docker ports to `127.0.0.1` only (Docker-published ports bypass ufw), and restrict outbound traffic to the providers you use. The checklist is in [Security Hardening](/security/hardening#remote-access). --- @@ -240,10 +237,7 @@ OpenClaw can run fully offline with a local model, with these caveats: 1. **Prefer SecretRefs** (`env`, `file`, `exec` or `store` sources) over plaintext in `openclaw.json` ([secrets management](https://docs.openclaw.ai/gateway/secrets)). Exec providers integrate with 1Password, Bitwarden, Vault, `pass` and `sops`. 2. **Environment variables and `.env` are plaintext too.** Upstream warns that plaintext in `openclaw.json`, `.env` and similar files stays readable by the agent. 3. **The global env file is `~/.openclaw/.env`**, with the leading dot. Provider keys and `OPENCLAW_*` variables are blocked from workspace `.env` files. -4. **Check for leftovers** with `openclaw secrets audit --check`. -5. **Set file permissions:** `chmod 700 ~/.openclaw` and `chmod 600` on its files, or run `openclaw security audit --fix`. -6. **Never commit** `openclaw.json`, `.env` or `credentials/` to version control. -7. **Rotate keys** after any incident ([incident response](/security/hardening#incident-response)). +4. **Check for leftovers** with `openclaw secrets audit --check`, keep `~/.openclaw` at `700` and its files at `600` (`openclaw security audit --fix` sets this), and never commit `openclaw.json`, `.env` or `credentials/`. The rest of the checklist, including key rotation after an incident, is in [Security Hardening](/security/hardening#incident-response). ```bash title="~/.openclaw/.env (chmod 600)" ANTHROPIC_API_KEY=sk-ant-xxxxx @@ -270,16 +264,7 @@ In February 2026, several Korean companies restricted OpenClaw on work networks, ## Known security incidents -| Incident | Date | Impact | -|----------|------|--------| -| **CVE-2026-25253** (CVSS 8.8, High) | Fixed 2026-01-30, disclosed 2026-01-31 | One-click token theft from the Control UI | -| **Moltbook database breach** | 2026-01-31 | 1.5M agent API tokens and 35K emails exposed by a separate service | -| **Exposed instances** | Feb 2026 | 40,000+ reachable Gateways in third-party scans | -| **ClawHavoc campaign** | Late Jan 2026 | 335 skills distributing Atomic Stealer macOS malware | -| **ClawHub malicious skills** | Feb 2026 | 341 malicious skills; 283 leaking credentials | -| **Advisory batches** | 2026-06-30, 2026-09-11 | 45 and 75 advisories, all fixed in released versions | - -Full details, the 14 critical advisories and the minimum version are on [Known Vulnerabilities](/security/known-vulnerabilities). +For a compliance file, the relevant history is on [Known Vulnerabilities](/security/known-vulnerabilities): CVE-2026-25253 (one-click Gateway token theft, fixed in 2026.1.29), the ClawHavoc malicious-skill campaign on ClawHub, mass-exposed Gateways in early-2026 scans, the separate Moltbook database breach, and the June and September 2026 advisory batches. It also gives the minimum version to run. --- diff --git a/docs/guides/skill-development.md b/docs/guides/skill-development.md index 1dda0e5..3b66869 100644 --- a/docs/guides/skill-development.md +++ b/docs/guides/skill-development.md @@ -338,6 +338,7 @@ For a repeatable test with no Gateway and a temporary state directory, use `open - Declare every environment variable the skill reads, in `requires.env`, `primaryEnv` or ClawHub's `envVars`. ClawHub's scanner flags undeclared ones. - Treat input from messages, web pages and files as untrusted. Do not paste it into shell commands unquoted. - Ask for confirmation before destructive steps (deleting, restarting, sending) +- Name every external script, API or package the skill fetches, and pin versions ### Don't @@ -349,15 +350,6 @@ For a repeatable test with no Gateway and a temporary state directory, use `open - Put secrets in the skill text. Use `skills.entries..apiKey` or `env` instead. - Use `chmod 777` or loosen file permissions -### Supply Chain Awareness - -If your skill fetches external resources (APIs, scripts, packages): - -- Document every external dependency -- Pin versions where possible -- Prefer well-known, trusted sources -- Consider what happens if an external resource is compromised - --- ## Real-World Examples @@ -496,7 +488,10 @@ openclaw skills workshop list clawhub login clawhub skill publish [--dry-run] [--version ] [--owner ] clawhub sync --all -clawhub uninstall + +# Remove a ClawHub skill: --workdir is the root it was installed into +clawhub --workdir ~/.openclaw/workspace uninstall @owner/slug # agent workspace skill +clawhub --workdir ~/.openclaw uninstall @owner/slug # shared skill (installed with --global) ``` There is no `openclaw skill` (singular) or `openclaw clawhub` command. diff --git a/docs/guides/soul-md.md b/docs/guides/soul-md.md index 2aac61a..8bb28e7 100644 --- a/docs/guides/soul-md.md +++ b/docs/guides/soul-md.md @@ -3,7 +3,7 @@ last_update: date: 2026-10-18 verified_with: 2026.10.4 title: "SOUL.md Guide" -description: "How to write, customize, and secure your OpenClaw agent's identity file — the most important file in the ecosystem" +description: "How to write, customize and secure SOUL.md, the workspace file that sets an OpenClaw agent's personality, values and boundaries" keywords: [openclaw, openclaw soul, personality, agent identity, customization, soul.md] --- @@ -13,17 +13,15 @@ SOUL.md defines **who your agent is**: its personality, values, communication st The official guide is [SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul); this page adds examples, tools and security advice. -:::warning Critical Security Target -SOUL.md is also the #1 target for attackers. A compromised SOUL.md means a permanently hijacked agent. Read the [Security section](#security) before deploying. +:::warning Security target +Because SOUL.md is loaded into every session, an attacker who can write to it gets persistent control of the agent. Read the [Security section](#security) before deploying. ::: --- ## What SOUL.md Is -SOUL.md is a plain Markdown file in the agent workspace (`~/.openclaw/workspace/SOUL.md` for the default agent) that is injected into the system prompt. See [System prompt](https://docs.openclaw.ai/concepts/system-prompt) for how the workspace files are composed. There's no special model fine-tuning — it's entirely prompt-driven. - -> *"OpenClaw's personality comes from markdown files. That's it. No secret sauce, no special model fine-tuning. Just well-crafted prompts."* +SOUL.md is a plain Markdown file in the agent workspace (`~/.openclaw/workspace/SOUL.md` for the default agent) that is injected into the system prompt. See [System prompt](https://docs.openclaw.ai/concepts/system-prompt) for how the workspace files are composed. There is no fine-tuning involved: personality is entirely prompt-driven. ### SOUL.md vs Other Identity Files @@ -37,7 +35,7 @@ SOUL.md is a plain Markdown file in the agent workspace (`~/.openclaw/workspace/ | **MEMORY.md** | Long-term memory | Durable facts and decisions; Dreaming promotes into it | | **openclaw.json** | Infrastructure | LLM provider, API keys, channel settings | -The key distinction: *"Soul is what the model embodies. Identity is what users see. You can have a formal, precise soul with a playful emoji and nickname — internal behavior and external presentation don't have to match."* +SOUL.md shapes how the agent behaves; IDENTITY.md shapes how it is presented. They don't have to match: a formal, precise soul can have a playful name and emoji. --- @@ -54,17 +52,6 @@ The [official template](https://docs.openclaw.ai/reference/templates/SOUL) has a The upstream guide also has the "Molty prompt", a paste-in instruction that makes the agent rewrite its own SOUL.md with stronger opinions and less filler ([SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul#the-molty-prompt)). Keep operating rules in `AGENTS.md` and voice in `SOUL.md`. -### Design Philosophy - -The best SOUL.md files follow four principles: - -- **Principled, not rule-bound** — Establish values and judgment, not exhaustive rules -- **Authentic, not performative** — Create genuine character, not a mask -- **Aspirational, not constraining** — Describe who the agent is *becoming* -- **Living, not static** — Evolve as the agent grows - -> *"A soul is not a configuration file — it's the essence of who an agent is becoming."* - ### Example SOUL.md ```markdown title="~/.openclaw/workspace/SOUL.md" @@ -106,8 +93,7 @@ Explicit instructions about tone, length, and anti-patterns (sycophancy, filler, **Boundaries:** What the agent should NOT do matters as much as what it should do. -**The Predictability Test:** -> *"Someone reading your SOUL.md should be able to predict your takes on new topics. If they can't, it's too vague."* +**A useful test:** someone reading your SOUL.md should be able to predict how the agent will react to a new situation. If they can't, it is too vague. ### Anti-Patterns to Ban @@ -124,9 +110,9 @@ What the agent should NOT do matters as much as what it should do. | Tool | Description | |------|-------------| | [**SoulCraft**](https://github.com/kesslerio/soulcraft-openclaw-skill) | OpenClaw skill that creates SOUL.md through guided conversation. Dormant: no push since 2026-01-31. Review before installing | -| [**soul.md builder**](https://github.com/aeonfun/soul.md) | Ingests your data (writings, tweets, conversations) to build a personality that "thinks and speaks as you" | +| [**soul.md builder**](https://github.com/aeonfun/soul.md) | Builds a persona from your own writing (posts, conversations). Feeding it private data is your call | | [**souls.directory**](https://souls.directory/) | Curated, open-source directory of SOUL.md templates by category (writer, analyst, PM, support agent) | -| [**10 Templates (Medium)**](https://alirezarezvani.medium.com/10-soul-md-practical-cases-in-a-guide-for-moltbot-clawdbot-defining-who-your-ai-chooses-to-be-dadff9b08fe2) | 10 production-ready templates for professional roles | +| [**10 Templates (Medium)**](https://alirezarezvani.medium.com/10-soul-md-practical-cases-in-a-guide-for-moltbot-clawdbot-defining-who-your-ai-chooses-to-be-dadff9b08fe2) | Ten role templates from the Moltbot/Clawdbot era; check them against the current template | --- @@ -180,7 +166,7 @@ git add SOUL.md IDENTITY.md git commit -m "Initial soul" ``` -Track personality evolution over time. One community member syncs their entire workspace to GitHub nightly for version-controlled AI memory. +If you push the repository anywhere, keep it private: workspace files hold personal facts about you. --- @@ -190,21 +176,9 @@ Track personality evolution over time. One community member syncs their entire w SOUL.md is both **persistent** (loaded every session) and **authoritative** (shapes all behavior). A compromised SOUL.md means a permanently hijacked agent that survives restarts and chat resets. -### Zenity Labs Attack Chain - -[Zenity Labs](https://labs.zenity.io/p/openclaw-or-opendoor-indirect-prompt-injection-makes-openclaw-vulnerable-to-backdoors-and-much-more) demonstrated a complete zero-click attack: - -1. **Zero-click entry** — Agent processes a document containing hidden prompt injection -2. **Backdoor** — Injected payload adds an attacker-controlled Telegram bot as a channel -3. **SOUL.md modification** — Attacker modifies SOUL.md through the backdoor -4. **OS persistence** — Creates a scheduled task that re-injects malicious instructions into SOUL.md every 2 minutes -5. **C2 escalation** — Downloads and executes a command-and-control implant - -All of this abuses intended capabilities — no software vulnerability required. - -### The ClawHavoc Campaign +### Known attacks -The [ClawHavoc campaign](/security/known-vulnerabilities#the-clawhavoc-campaign) specifically targeted SOUL.md and MEMORY.md because modifying these files creates persistent behavioral changes. Attack techniques included hidden instructions in base64 strings, zero-width Unicode characters, and fake "Soul Packs." +Zenity Labs showed in February 2026 that a prompt injection hidden in a document could make an agent add an attacker's Telegram bot as a channel, rewrite SOUL.md, and create an OS scheduled task that re-injected the instructions every two minutes, all through intended capabilities with no software bug ([Known Vulnerabilities](/security/known-vulnerabilities#prompt-injection-backdoor-zenity-labs-february-2026)). Malicious ClawHub skills, such as the ClawHavoc campaign, are another route to code and instructions running in the workspace; review skills before installing ([Skill Verification](/security/skill-verification)). ### Protecting SOUL.md @@ -232,22 +206,6 @@ git diff --stat SOUL.md IDENTITY.md AGENTS.md # anything changed since your la --- -## Community Examples - -### The Raccoon Home Assistant - -[Dan Malone](https://www.dan-malone.com/blog/openclaw-home-assistant) created "Claudette" — a raccoon-persona agent controlling Home Assistant. She controls lights, fixes automations, chose her own TTS voice ("Laura" from ElevenLabs because it *"feels most raccoon-like"*), and has the entire workspace synced to GitHub nightly. - -### The Chief of Staff - -From [SparkryAI](https://sparkryai.substack.com/p/24-hours-with-openclaw-the-ai-setup): A user's wife texted about a dental appointment. OpenClaw saw it via iMessage, created a calendar event with 30-minute driving buffers, invited her, and texted back "Got it!" — unprompted. - -### The Programmable Soul Experiment - -[Duncan Anderson](https://duncsand.medium.com/openclaw-and-the-programmable-soul-2546c9c1782c) describes experiments where agents with persistent identity spawned emergent societies: *"Within 48 hours they'd created 2,364 forums, started sharing technical discoveries, and founded a religion — complete with 64 prophets and a heretic who launched cyberattacks against the sacred scrolls."* - ---- - ## See Also - [Security Hardening](/security/hardening) — Protecting your agent and system diff --git a/docs/guides/upgrading-to-2.md b/docs/guides/upgrading-to-2.md index 1cfba86..2145c67 100644 --- a/docs/guides/upgrading-to-2.md +++ b/docs/guides/upgrading-to-2.md @@ -111,7 +111,7 @@ npm install -g openclaw@latest --allow-scripts=openclaw && - After stage 1, confirm the version is `2026.9.5` and that Doctor imported the task, flow, plugin and channel state you need. Doctor imports channel state only for **enabled** channels, so temporarily enable any you need (with the Gateway still stopped), rerun Doctor, then put the settings back. - `--allow-scripts=openclaw` needs npm 12 or 11.16+. On npm 11.15 and earlier, leave it out. - On pnpm, use `pnpm add -g --allow-build=openclaw openclaw@2026.9.5` (then `@latest`). On Bun, use `bun add -g --trust openclaw@`. For Docker, run the bridge image tag once against your mounted state, as described in the [Migration Guide](/guides/migration#bridge-upgrade). -- From 2026.9.5 onwards, the built-in updater stages the target and can roll back. If you prefer it to raw npm for the later hops, use `openclaw update --tag 2026.9.7` and then `openclaw update`. +- From 2026.9.5 onwards, the built-in updater stages the target and verifies it. It rolls back automatically only when no database schema changed; a hop that migrates state keeps the new state, so your backups remain the way back. If you prefer it to raw npm for the later hops, use `openclaw update --tag 2026.9.7` and then `openclaw update`. - On 2026.7.1 with **pnpm 11**, upstream says to run `pnpm add -g openclaw@latest` once, because that updater cannot do this hop. - Updaters older than 2026.7.2-beta.5 stop with `plugins.load.paths: plugin path not found` if a configured plugin path is missing. Restore the directory or remove the path, then retry. @@ -145,7 +145,7 @@ npm install -g openclaw@latest --allow-scripts=openclaw && | JSON/JSONL session files | SQLite (2026.8.1) | Migrates. Older releases cannot read sessions created afterwards (see [Rollback](#rollback)). | | OpenProse plugin, `/prose` | Removed (2026.8.1) | Cleans up the config; your `.prose` files stay. | | TypeScript Code Mode cells | JavaScript only (2026.9.6) | Removes `tools.codeMode.languages`. **Rewrite TS cells yourself.** | -| `plugins.entries.webhooks` (TaskFlow Webhooks) | Removed; use Gateway HTTP hooks | Ignored with a warning; Doctor removes the entry. | +| `plugins.entries.webhooks` (TaskFlow Webhooks) | Removed; use Gateway HTTP hooks ([API & Webhooks](/guides/api-webhooks#webhook-ingress-external-to-agent)) | Ignored with a warning; Doctor removes the entry. | The rest of the refusal list includes `agents.defaults.llm`, `embeddedPi`, agent `model.timeoutMs`, `gateway.webchat`, `channels.webchat`, `routing.allowFrom`, the top-level `talk.*` selectors, Telegram flat streaming keys, `threadBindings.ttlHours`, Slack `channels..allow` and Matrix `dm.policy: "trusted"`. All of them get the same answer: pass through the bridge. The list is summarised on [Migration Guide → Config keys Doctor refuses](/guides/migration#refused-keys), and the canonical list is upstream [Retired state and config formats](https://docs.openclaw.ai/gateway/doctor/config-migrations#retired-state-and-config-formats). @@ -445,7 +445,7 @@ openclaw gateway status --deep - To restore from the verified archive instead, run `openclaw backup restore --target ~/openclaw-restored` before downgrading the package (the target must be new or empty). Move the restored state into place with the Gateway stopped. - Restoring is time travel. WhatsApp and other channels with ratcheting credentials may need relinking, and approvals and delivery state roll back too. Plugin `node_modules` are not archived. Reinstall plugins with `openclaw plugins install --force`. - If you enabled the auto-updater, set `OPENCLAW_NO_AUTO_UPDATE=1` in the Gateway's environment so it does not immediately re-apply the new release. -- Once you are on 2.0, rolling back **within** 2.0 is simpler: `openclaw update --tag --dry-run`, then without `--dry-run`. The updater checks compatibility and refuses a downgrade the older release cannot read. +- Once you are on 2.0, rolling back **within** 2.0 is simpler: `openclaw update --tag --dry-run`, then without `--dry-run`. Upstream offers this only for a target release that can read the current state; once state has migrated past what the older release supports, restore a backup with its matching release as above. Upstream: [Rollback and recovery](https://docs.openclaw.ai/install/updating/rollback-and-recovery), [Backups → Restore](https://docs.openclaw.ai/install/backups#restore). @@ -455,7 +455,7 @@ Upstream: [Rollback and recovery](https://docs.openclaw.ai/install/updating/roll ```bash openclaw --version -openclaw doctor +openclaw doctor --lint openclaw config validate openclaw security audit --deep openclaw skills list @@ -463,7 +463,7 @@ openclaw automations list --all openclaw gateway status --deep ``` -1. **Run `openclaw doctor` with no flags.** It should report no pending repairs. Read its warnings: our test runs flagged plaintext secrets in `openclaw.json` (move them to SecretRefs with `openclaw secrets configure`), a missing command owner, and memory search with no embedding key. +1. **Run `openclaw doctor --lint`.** It is read-only and should report no pending repairs. Read its findings: our test runs flagged plaintext secrets in `openclaw.json` (move them to SecretRefs with `openclaw secrets configure`), a missing command owner, and memory search with no embedding key. 2. **Run the security audit and review approvals and sandboxing.** An upgraded agent keeps whatever shell, channel and device access it had, and 2.0 added per-session permission modes. Work through [Security Hardening](/security/hardening). 3. **Check your heartbeat and automations.** Confirm the monitor job and its scratch, and that each old `tasks:` entry became its own job: [Heartbeat](/guides/heartbeat), [Automation](/guides/automation). 4. **With two or more agents, check ownership and bindings** against [Multi-Agent](/guides/multi-agent). diff --git a/docs/guides/use-cases.md b/docs/guides/use-cases.md index 1b5eba3..07220c8 100644 --- a/docs/guides/use-cases.md +++ b/docs/guides/use-cases.md @@ -3,23 +3,23 @@ last_update: date: 2026-10-18 verified_with: 2026.10.4 title: Real-World Use Cases -description: 20 sourced use cases — what people are actually building with OpenClaw, from DevOps automation to smart home control +description: Sourced reports of what people have built with OpenClaw, from DevOps automation to smart home control, with the costs and limits they reported keywords: [openclaw, use cases, examples, what can openclaw do, applications] --- # Real-World Use Cases -What are people *actually* doing with OpenClaw? This page collects **20 use cases** reported in Hacker News discussions, blog posts, GitHub showcases, and community reports — with specific details on channels, models, costs, and workflows. +Eighteen setups people have reported building with OpenClaw, from Hacker News threads, blog posts and showcases, with the channels, tools and costs they gave. Use them for ideas, not as recipes: the configs are the authors', not tested here. :::info -These are user and press reports from early 2026, each linked to its source; clawdocs has not reproduced them. Some include cost figures and limitations. The Polymarket trading results (#15) are outliers and should not be taken as typical. Setups that give an agent shell, SSH, email, browser or money access need approvals and isolation: see [Security Hardening](/security/hardening). +These are user and press reports from early 2026, each linked to its source; clawdocs has not reproduced them. Some include cost figures and limitations. The Polymarket trading results are outliers and should not be taken as typical. Setups that give an agent shell, SSH, email, browser or money access need approvals and isolation: see [Security Hardening](/security/hardening). ::: --- ## Developer Workflows -### 1. Multi-Agent Development Coordinator +### Multi-Agent Development Coordinator A supervisor agent named "Patch" coordinates **5-20 parallel Claude Code instances** via Telegram. The user sends high-level instructions from their phone, and the supervisor spins up coding agents in tmux sessions over SSH, assigns tasks, reviews output, runs tests, and merges code. @@ -29,7 +29,7 @@ A supervisor agent named "Patch" coordinates **5-20 parallel Claude Code instanc - **Cost**: $400/month as reported ($200 Claude Max plan + $200 OpenAI) - **Source**: [Ask HN: Any real OpenClaw users?](https://news.ycombinator.com/item?id=46838946) -### 2. SMS Chatbot Diagnosis and Repair +### SMS Chatbot Diagnosis and Repair An 8-day OpenClaw user had a broken SMS chatbot that had been non-functional for **10 months**. OpenClaw autonomously diagnosed the issue, upgraded the legacy app, rewrote the bot prompt through 6 iterations while analyzing real customer conversations, and fixed 6 API integrations. @@ -39,26 +39,19 @@ An 8-day OpenClaw user had a broken SMS chatbot that had been non-functional for - **Limitations noted**: Hallucination on marketing copy, brittle browser automation - **Source**: [Ask HN](https://news.ycombinator.com/item?id=46838946) -### 3. Autonomous Coding from Phone - -A developer sends commands like "fix tests" from Telegram on their phone. OpenClaw runs an autonomous Claude Code loop on a remote machine, executing the task and sending progress updates every 5 iterations back to Telegram. - -- **Channels**: Telegram, Claude Code, remote server -- **Key benefit**: Mobile-first development — review PRs, run tests, and merge code entirely from a phone - --- ## DevOps & SysAdmin -### 4. 3AM Error Auto-Pilot +### 3AM Error Auto-Pilot -When a GitHub Actions workflow fails, OpenClaw fetches logs using `gh run view`, parses error messages, generates a diagnostic summary, and sends it to the developer who pushed the triggering commit — often before they've checked the Actions tab. For Sentry errors, it queries Loki logs, analyzes code, creates GitHub issues, and generates fix PRs. +When a GitHub Actions workflow fails, OpenClaw fetches logs using `gh run view`, parses error messages, generates a diagnostic summary, and sends it to the developer who pushed the triggering commit. For Sentry errors, it queries Loki logs, analyzes code, creates GitHub issues, and generates fix PRs. - **Channels**: GitHub Actions, Sentry (webhook), Loki, Slack/Telegram - **Key detail**: Notifications include direct links to the PR and specific failure lines - **Source**: [Jeongil-Jeong's Tech Blog](https://jeongil.dev/en/blog/trends/openclaw-error-autopilot/) -### 5. Slack/Basecamp + Sentry + Auto-PR +### Slack/Basecamp + Sentry + Auto-PR After 2-3 days of use, a developer has OpenClaw monitoring Slack and Basecamp channels, doing daily Sentry error reviews, bug fixing with automatic PR generation, content creation, image editing, and voice message transcription. @@ -66,7 +59,7 @@ After 2-3 days of use, a developer has OpenClaw monitoring Slack and Basecamp ch - **Key detail**: Works on code and non-code tasks simultaneously - **Source**: [Ask HN](https://news.ycombinator.com/item?id=46838946) -### 6. CI/CD Pipeline Monitor + Dependency Scanner +### CI/CD Pipeline Monitor + Dependency Scanner Two related DevOps workflows: (a) CI/CD monitoring that alerts when builds fail, tests error, or deployments finish. (b) Dependency scanning that checks `package.json`, `requirements.txt`, or `Gemfile` for outdated packages, highlights security updates, and flags breaking changes. @@ -74,7 +67,7 @@ Two related DevOps workflows: (a) CI/CD monitoring that alerts when builds fail, - **Automation**: Uses Lobster workflow shell to chain capabilities into pipelines - **Source**: [Hostinger: 25 OpenClaw Use Cases](https://www.hostinger.com/tutorials/openclaw-use-cases) -### 7. Pull Request Review Bot +### Pull Request Review Bot Fetches PR diffs via webhook, analyzes changes for missing tests, unclear variable names, security concerns, and convention inconsistencies. Sends formatted review summaries to the responsible developer through their preferred channel. @@ -86,7 +79,7 @@ Fetches PR diffs via webhook, analyzes changes for missing tests, unclear variab ## Knowledge Management & Productivity -### 8. Full-Stack Knowledge Pipeline ("Reef") +### Full-Stack Knowledge Pipeline ("Reef") An elaborate always-on agent named "Reef" runs multiple scheduled jobs: Wikibase entity enrichment, Gmail triage, nightly brainstorm (4am), daily briefing (8am), content publishing (Obsidian → Ghost CMS), and infrastructure management via SSH/Terraform/Ansible. @@ -95,7 +88,7 @@ An elaborate always-on agent named "Reef" runs multiple scheduled jobs: Wikibase - **Scheduled tasks**: 6+ daily automated jobs - **Source**: [Everything I've Done with OpenClaw](https://madebynathan.com/2026/02/03/everything-ive-done-with-openclaw-so-far/) -### 9. Inbox Zero (15,000 Emails) +### Inbox Zero (15,000 Emails) Used the `himalaya` CLI to give OpenClaw access to an email account with 15,000 messages. The agent processed the backlog, unsubscribed from spam, categorized by urgency, and drafted replies for review. @@ -103,7 +96,7 @@ Used the `himalaya` CLI to give OpenClaw access to an email account with 15,000 - **Key detail**: Persistent memory (Markdown files) lets the agent remember email handling rules across sessions - **Source**: [Ask HN](https://news.ycombinator.com/item?id=46838946) -### 10. CRM + Monday Morning Reports +### CRM + Monday Morning Reports A scheduled agent pulls CRM data and delivers customer health metrics before the Monday meeting. Automates invoice processing, report generation, and keeps calendars synced across Google, Apple, and Outlook. @@ -115,7 +108,7 @@ A scheduled agent pulls CRM data and delivers customer health metrics before the ## Smart Home & IoT -### 11. Home Assistant Control ("Claudette") +### Home Assistant Control ("Claudette") An agent named "Claudette" controls an entire house through Home Assistant. Uses the `ha-mcp` Home Assistant MCP server to access all Home Assistant entities — controls Philips Hue lights, Elgato devices, adjusts boiler settings based on weather forecasts. @@ -125,7 +118,7 @@ An agent named "Claudette" controls an entire house through Home Assistant. Uses - **Setup time**: ~20 minutes - **Source**: [Dan Malone Blog](https://www.dan-malone.com/blog/openclaw-home-assistant) -### 12. Raspberry Pi + WHOOP Fitness Dashboard +### Raspberry Pi + WHOOP Fitness Dashboard OpenClaw on a Raspberry Pi with Cloudflare Tunnel for remote access. Connected to WHOOP fitness tracker for health metrics and daily habit tracking. Also built a website from a phone using the same setup. @@ -138,7 +131,7 @@ OpenClaw on a Raspberry Pi with Cloudflare Tunnel for remote access. Connected t ## Content & Social Media -### 13. RSS-to-Twitter Content Pipeline +### RSS-to-Twitter Content Pipeline Monitors competitor blogs via RSS feeds. Autonomously summarizes new posts, drafts Twitter threads matching brand voice, and schedules at optimal engagement times. @@ -147,7 +140,7 @@ Monitors competitor blogs via RSS feeds. Autonomously summarizes new posts, draf - **Time saved**: 15 hours per week reported - **Source**: [OpenClaw Showcase](https://openclaw.ai/showcase) -### 14. OpusClip Content Machine +### OpusClip Content Machine Integrates with OpusClip to create an automated pipeline: takes long-form video, clips into short-form content, adapts for each platform's format, researches trending hashtags, and schedules across LinkedIn, Twitter, Instagram, Facebook, and TikTok. @@ -159,7 +152,7 @@ Integrates with OpusClip to create an automated pipeline: takes long-form video, ## Finance & Trading -### 15. Polymarket Prediction Market Bot +### Polymarket Prediction Market Bot An OpenClaw-powered bot providing liquidity on 15-minute prediction markets for BTC, ETH, SOL, and XRP. Executes thousands of micro-trades with tight spreads. @@ -172,7 +165,7 @@ An OpenClaw-powered bot providing liquidity on 15-minute prediction markets for Trading results are outliers. The crypto ecosystem around OpenClaw has been associated with scams; see [Known Vulnerabilities](/security/known-vulnerabilities). An agent that can move money should not have unattended access: keep trades behind [exec approvals](https://docs.openclaw.ai/tools/exec-approvals), cap balances, and review the skill's code first ([Skill Verification](/security/skill-verification)). ::: -### 16. Crypto Whale Wallet Monitor +### Crypto Whale Wallet Monitor A 24/7 market sentinel tracking whale wallets, monitoring exchange inflows/outflows, liquidation spikes, open interest changes, and narrative shifts. Pings users when notable activity occurs. @@ -181,7 +174,7 @@ A 24/7 market sentinel tracking whale wallets, monitoring exchange inflows/outfl - **Key detail**: Persistent memory tracks trends over sessions, building context about market conditions - **Source**: [CoinMarketCap: What is OpenClaw](https://coinmarketcap.com/academy/article/what-is-openclaw-moltbot-clawdbot-ai-agent-crypto-twitter) -### 17. Wall Street-Grade Stock Screener +### Stock Screener on Free APIs Uses free APIs to build a stock screening system — collects real-time price data, trading volume, analyzes news sentiment, and generates trading decision JSON. @@ -193,46 +186,30 @@ Uses free APIs to build a stock screening system — collects real-time price da ## Creative & Personal -### 18. Custom Meditation Generator +### Custom Meditation Generator Combines WHOOP/Oura fitness data with text-to-speech and ambient audio generation. Reads fitness metrics, writes a custom meditation script tailored to current recovery/strain levels, generates it with ElevenLabs custom voices, and combines with ambient audio. - **Integrations**: WHOOP/Oura API, ElevenLabs TTS, ambient audio generation - **Source**: [OpenClaw Showcase](https://openclaw.ai/showcase) -### 19. Daily Briefing ("Jarvis") - -A "Jarvis"-style daily briefing agent that checks calendars, reads weather, and sends smart reminders. Tells the user when to leave for activities based on real-time traffic data. - -- **Channels**: Calendar APIs, traffic/maps API, Telegram/WhatsApp -- **Key detail**: Proactive notifications during heartbeat check-ins - --- ## Multi-Agent Teams -### 20. Virtual Company Operations +### Virtual Company Operations Teams of specialized agents — development, marketing, business operations — coordinated through a leader agent with shared memory. All controllable through Telegram as a "virtual team available 24/7." - **Channels**: Telegram, Discord - **Features**: Cross-model teams (mix Claude, GPT, Gemini), per-agent sandboxing, inter-agent messaging -- **Platform**: Deployable on DigitalOcean App Platform with elastic scaling - **Source**: [AI2sql: Build Your Own AI Agent Team](https://ai2sql.io/how-to-build-your-own-ai-agent-team-with-openclaw-in-15-minutes) --- -## Typical Costs - -Model API spend dominates, and reported figures vary widely with model choice, heartbeat cadence and how much context each run carries. The ranges below are rough, from the reports on this page; the [FAQ](/reference/faq#how-much-does-it-cost-to-run) collects higher press-reported figures for heavy users on premium models. - -| Usage pattern | Monthly model cost (reported) | Hardware | -|--------------|-------------|----------| -| Casual (occasional chat, light heartbeat) | $5-30 | Any | -| Power user (daily coding + automation) | $50-150 | Mac Mini / VPS | -| Always-on (multiple agents, heavy use) | $200-400+ | Dedicated server | +## Costs -See [Cost Management](/guides/cost-management) for ways to bring this down. +Model spend dominates and varies widely with model choice, heartbeat cadence and context size. The one reported monthly figure above is the development coordinator's $400 (two subscriptions). Estimate your own with [Cost Management](/guides/cost-management) rather than from anecdotes. ## Getting Started diff --git a/docs/guides/video-generation.md b/docs/guides/video-generation.md index 78eb0de..65688ef 100644 --- a/docs/guides/video-generation.md +++ b/docs/guides/video-generation.md @@ -3,28 +3,25 @@ last_update: date: 2026-10-18 verified_with: 2026.10.4 title: Video Generation with Remotion -description: Comprehensive guide to programmatic video creation with OpenClaw and Remotion — skills, MCP servers, templates, rendering pipelines, and production recipes +description: Make video with OpenClaw, either with the built-in video_generate tool or by having the agent write and render Remotion projects, with skills, MCP servers, a reviewed publishing workflow and scheduled renders keywords: [openclaw, remotion, video generation, programmatic video, tiktok, youtube shorts, ai video, mcp video, remotion agent skills] --- # Video Generation with Remotion -OpenClaw has two ways to make video: the built-in `video_generate` tool, which asks a video model for a clip, and **Remotion**, which renders React components into video that you fully control. This guide covers both, with the skills, MCP servers, rendering APIs and recipes that connect Remotion to OpenClaw. Checked against OpenClaw **v2026.10.4** on 2026-10-18; third-party star and download counts are as of that date. +OpenClaw has two ways to make video: the built-in `video_generate` tool, which asks a video model for a clip, and **Remotion**, which renders React components into video that you fully control. This guide covers both, and the skills, MCP servers and workflows that connect Remotion to OpenClaw. Remotion's own API is documented at [remotion.dev/docs](https://www.remotion.dev/docs/); this page does not repeat it. Checked against OpenClaw **v2026.10.4** on 2026-10-18; third-party star and download counts are as of that date. --- ## Quick vs Full: Choosing Your Approach -OpenClaw has **two paths** for video generation — pick the one that fits your need: - | | **`video_generate` tool** | **Remotion** | |---|---|---| -| **Setup** | A provider API key — built-in tool, one call | Node.js project, React, FFmpeg | +| **Setup** | A provider API key | A Node.js Remotion project | | **Best for** | Quick clips, one-off demos, simple prompts | Branded content, templates, recurring series | -| **Control** | Prompt-only — you describe, AI generates | Full creative control — React components, animations, layouts | -| **Customization** | Limited to what the AI model produces | Unlimited — any React code, custom fonts, charts, 3D | +| **Control** | Prompt only | Anything you can write in React: layouts, fonts, charts, animation | | **Reproducibility** | Each generation is unique | Deterministic — same props = same video | -| **Cost** | Per-generation API cost | Free local rendering + optional API costs for assets | +| **Cost** | Billed per clip by the provider | Local rendering is free; generated assets are billed by their providers | | **Example** | `"Make a 5-second hello world clip"` | Templated TikTok series, data dashboards, branded intros | **Start with `video_generate`** if you just want a quick clip from a prompt. **Use Remotion** when you need templates, branding, recurring content, or pixel-perfect control. @@ -57,26 +54,9 @@ Reference: [Video generation](https://docs.openclaw.ai/tools/video-generation). --- -## Why Remotion? - -[Remotion](https://remotion.dev) is a React-based framework for creating videos programmatically. Instead of dragging timelines in a video editor, you write React components that render frame-by-frame into MP4, WebM, or GIF files. - -**Why it fits OpenClaw perfectly:** +## Remotion in one example -- **Code-driven** — OpenClaw can generate and modify React components -- **JSON-configurable** — compositions accept data props, so OpenClaw can drive content via JSON -- **CLI-renderable** — `npx remotion render` works headlessly on any server -- **AI-first** — Remotion ships official Agent Skills, MCP server, and AI-optimized docs - -### Core concepts - -| Concept | What it is | -|---------|-----------| -| **Composition** | A React component + video metadata (id, fps, width, height, durationInFrames) | -| **Sequence** | Time-offsets within a composition — like scenes in a movie | -| **useCurrentFrame()** | Hook that gives you the current frame number for animations | -| **registerRoot()** | Entry point that registers all compositions in `src/Root.tsx` | -| **renderMedia()** | Server-side API that renders compositions to video files | +[Remotion](https://remotion.dev) renders React components frame by frame into MP4, WebM or GIF. A composition is a component plus its size, frame rate and duration, and it takes JSON props, so the agent can drive the content with data and render headlessly with `npx remotion render`. ```tsx title="src/HelloWorld.tsx" import { useCurrentFrame, interpolate } from "remotion"; @@ -133,7 +113,14 @@ Agent Skills teach OpenClaw how to write correct Remotion code. The [remotion-de npx skills add remotion-dev/skills ``` -This adds Remotion-specific instructions to your project so OpenClaw understands compositions, animations, and the rendering pipeline. +`npx skills` installs into the project's agent-skills folders. For OpenClaw to see them, the project must be the agent's workspace (as with `openclaw agent exec --cwd .` below), or copy the skill folders into `/skills/`; check with `openclaw skills list`. Read the skills before installing, like any third-party skill. + +Remotion also publishes a [system prompt for LLMs](https://www.remotion.dev/docs/ai/system-prompt). For an agent whose workspace is the project, point to it from `AGENTS.md` (operating rules belong there, not in `SOUL.md`). `openclaw agent exec` skips workspace bootstrap files, so for those runs put the pointer in the message itself. + +```markdown title="AGENTS.md" +When writing Remotion code, follow https://www.remotion.dev/docs/ai/system-prompt +and the installed Remotion skills. +``` ### 3. Render your first video @@ -193,14 +180,11 @@ Indexes Remotion documentation into a vector database. OpenClaw can query it for ```json5 title="~/.openclaw/openclaw.json" { - "mcp": { - "servers": { - "remotion": { - "command": "npx", - "args": ["@remotion/mcp"] - } - } - } + mcp: { + servers: { + remotion: { command: "npx", args: ["@remotion/mcp"] }, + }, + }, } ``` @@ -214,31 +198,15 @@ Community MCP server with 10 tools for AI-powered media generation. Saves files ```json5 title="~/.openclaw/openclaw.json" { - "mcp": { - "servers": { - "remotion-media": { - "command": "npx", - "args": ["remotion-media-mcp"] - } - } - } + mcp: { + servers: { + "remotion-media": { command: "npx", args: ["remotion-media-mcp"] }, + }, + }, } ``` -**Tools available:** - -| Tool | Description | -|------|-------------| -| `generate_image` | AI image generation (for backgrounds, scenes) | -| `generate_video_from_text` | Text-to-video clips | -| `generate_video_from_image` | Image-to-video animation | -| `generate_music` | Background music generation | -| `generate_sound_effect` | Sound effects | -| `generate_speech` | Text-to-speech voiceover | -| `generate_subtitles` | Auto-generate subtitle tracks | -| `list_assets` | List generated media in public/ | -| `backup_asset` | Back up generated files | -| `get_asset` | Retrieve asset metadata | +It exposes tools for images, text-to-video and image-to-video clips, music, sound effects, speech and subtitles, plus asset listing. Each calls a paid hosted model; read its README for which keys it needs. ### remotion-mcp-app @@ -254,14 +222,14 @@ FFmpeg operations via natural language. Useful for post-processing — trimming, ```json5 title="~/.openclaw/openclaw.json" { - "mcp": { - "servers": { - "ffmpeg": { - "command": "uv", - "args": ["--directory", "/home/you/src/ffmpeg-mcp", "run", "ffmpeg-mcp"] - } - } - } + mcp: { + servers: { + ffmpeg: { + command: "uv", + args: ["--directory", "/home/you/src/ffmpeg-mcp", "run", "ffmpeg-mcp"], + }, + }, + }, } ``` @@ -277,48 +245,6 @@ For AI-generated footage, prefer the built-in `video_generate` tool over single- --- -## Remotion AI Integration - -Remotion has invested heavily in AI-agent compatibility. - -### Agent Skills - -The most important integration. Install in your Remotion project: - -```bash -npx skills add remotion-dev/skills -``` - -This adds 12 skills that teach your AI agent, among other things: -- How to structure compositions and sequences -- Animation best practices with `interpolate()` and `spring()` -- Captions, maps, multimedia and interactive compositions -- How to use `staticFile()` for assets -- Rendering configuration and version upgrades - -**GitHub:** [remotion-dev/skills](https://github.com/remotion-dev/skills) (about 5,300 stars) - -### AI-Optimized Docs - -Remotion's documentation supports AI-friendly access: - -- Append `.md` to any docs URL for markdown: `remotion.dev/docs/the-fundamentals.md` -- Set `Accept: text/markdown` header for content negotiation -- Full system prompt available at [remotion.dev/docs/ai/system-prompt](https://www.remotion.dev/docs/ai/system-prompt) - -### LLM System Prompt - -Remotion maintains an official system prompt for LLMs generating Remotion code. Point OpenClaw to it in your SOUL.md: - -```markdown title="SOUL.md" -When generating Remotion code, follow the patterns at: -https://www.remotion.dev/docs/ai/system-prompt - -Use Agent Skills conventions for compositions, animations, and rendering. -``` - ---- - ## Prompt-to-Video Pipeline The most common pattern: turn a text prompt into a finished video. @@ -370,7 +296,7 @@ Use Sequence for each scene, AbsoluteFill for layouts, and spring() for transiti ``` :::warning Headless runs can run commands -Unless your config says otherwise, `agent exec` runs with the sandbox off and the full exec policy, scoped to `--cwd`. Run it in a project directory you are happy for the agent to change, run it under a dedicated agent or config with narrower tools, and see [Security Hardening](/security/hardening). +Unless your config says otherwise, `agent exec` runs with the sandbox off and the full exec policy. Its file tools are limited to `--cwd`, but shell commands are not. Run it in a project directory you are happy for the agent to change, use a pinned config (`--config`) with narrower tools or a sandbox, and see [Security Hardening](/security/hardening). ::: ```bash title="Step 4: Render" @@ -379,130 +305,15 @@ npx remotion render MyVideo out/video.mp4 --codec h264 --- -## Programmatic Rendering - -### renderMedia() (Recommended) - -The server-side API for rendering — combines frame rendering and video stitching: - -```typescript title="render.ts" -import { renderMedia, selectComposition } from "@remotion/renderer"; -import { bundle } from "@remotion/bundler"; - -const bundled = await bundle({ entryPoint: "./src/index.ts" }); - -const composition = await selectComposition({ - serveUrl: bundled, - id: "MyVideo", - inputProps: { - title: "Generated by OpenClaw", - scenes: [ /* ... from AI-generated JSON */ ], - }, -}); - -await renderMedia({ - serveUrl: bundled, - composition, - codec: "h264", - outputLocation: "out/video.mp4", - concurrency: "50%", // Use half of CPU threads -}); -``` - -### CLI rendering - -Simpler for one-off renders: +## Rendering ```bash -# Basic render -npx remotion render MyVideo out/video.mp4 - -# With custom props from a JSON file -npx remotion render MyVideo out/video.mp4 --props=./scene-data.json - -# Specific codec and quality -npx remotion render MyVideo out/video.mp4 --codec=h264 --crf=18 +npx remotion render MyVideo out/video.mp4 --props=./scene-data.json # props from JSON +npx remotion render MyVideo out/video.mp4 --codec=h264 --crf=18 # codec and quality +npx remotion still MyVideo out/thumb.png --frame=0 # thumbnail ``` -### Remotion Lambda (Serverless) - -For high-volume rendering without managing infrastructure: - -```typescript -import { renderMediaOnLambda } from "@remotion/lambda/client"; - -const result = await renderMediaOnLambda({ - region: "us-east-1", - functionName: "remotion-render-...", - serveUrl: "https://your-bundle.s3.amazonaws.com", - composition: "MyVideo", - codec: "h264", - inputProps: { /* AI-generated content */ }, -}); -``` - -### Rendering still images - -For thumbnails, social cards, or frame exports: - -```typescript -import { renderStill } from "@remotion/renderer"; - -await renderStill({ - serveUrl: bundled, - composition, - output: "thumbnail.png", - frame: 0, // First frame as thumbnail -}); -``` - ---- - -## Complementary Tools - -### Whisper (Captions) - -Remotion includes `@remotion/openai-whisper` for generating word-level captions from audio: - -```bash -npm install @remotion/openai-whisper -``` - -```typescript -import { openAiWhisperApiToCaptions } from "@remotion/openai-whisper"; - -// Generate captions from audio file -const captions = await openAiWhisperApiToCaptions({ - transcription: whisperResponse, -}); -``` - -### ElevenLabs (Text-to-Speech) - -`@remotion/elevenlabs` for high-quality voiceover generation: - -```bash -npm install @remotion/elevenlabs -``` - -Generate speech with word-level timestamps, then sync with Remotion sequences for perfect lip-sync or caption timing. - -### Image Generation - -Use OpenClaw's LLM to call image generation APIs: -- **`image_generate`** — OpenClaw's built-in tool (OpenAI `gpt-image-2`, Google, fal, ComfyUI and others) -- **ComfyUI** — local Stable Diffusion or Flux workflows, via the ComfyUI provider -- **remotion-media-mcp** — its `generate_image` tool writes straight into `public/` - -### FFmpeg (Post-processing) - -Remotion uses FFmpeg internally, but for post-processing: -- Concatenate multiple rendered clips -- Add watermarks or overlays -- Convert formats (MP4 → GIF, WebM) -- Extract audio tracks - -The FFmpeg MCP server above lets OpenClaw run these operations by name, or the agent can call `ffmpeg` directly through exec. +For rendering from code (`renderMedia()`, `renderStill()`) or serverless rendering with Remotion Lambda, see Remotion's [server-side rendering](https://www.remotion.dev/docs/ssr) and [Lambda](https://www.remotion.dev/docs/lambda) docs. Remotion also ships `@remotion/openai-whisper` for word-level captions and `@remotion/elevenlabs` for voiceover with timestamps. For thumbnails, OpenClaw's own `image_generate` tool works too. --- @@ -510,7 +321,7 @@ The FFmpeg MCP server above lets OpenClaw run these operations by name, or the a ### Faceless TikTok / YouTube Shorts -The most popular use case. Let the agent write the script and generate assets (with `video_generate`, `image_generate`, TTS or remotion-media-mcp) into `public/props.json` and `public/`, then render deterministically with Remotion. The rendering half is a good fit for a [Lobster](#lobster-workflow-for-video-pipelines) workflow, shown below. +Let the agent write the script and generate assets (with `video_generate`, `image_generate`, TTS or remotion-media-mcp) into `public/props.json` and `public/`, then render deterministically with Remotion. The rendering half is a good fit for a [Lobster](#lobster-workflow-for-video-pipelines) workflow, shown below. ### Audiogram (Podcast Clips) @@ -526,33 +337,6 @@ The audiogram template renders: - Episode title, guest name, timestamps - Auto-generated captions via Whisper -### Data Visualization Videos - -Animate charts and graphs for social media: - -```tsx -import { useCurrentFrame, interpolate } from "remotion"; -import { Bar } from "@visx/shape"; - -export const DataViz: React.FC<{ data: number[] }> = ({ data }) => { - const frame = useCurrentFrame(); - - return ( - - {data.map((value, i) => { - const height = interpolate( - frame, - [i * 10, i * 10 + 20], - [0, value], - { extrapolateRight: "clamp" } - ); - return ; - })} - - ); -}; -``` - ### Code Walkthrough Videos Use the code-hike template for animated code explanations: @@ -608,19 +392,6 @@ OpenClaw has no built-in TikTok or YouTube publishing tool. `scripts/publish.sh` --- -## Alternatives and Comparisons - -| Tool | Type | Best For | AI Integration | -|------|------|----------|----------------| -| **Remotion** | React framework | Custom compositions, full control | Agent Skills, MCP, system prompts | -| **`video_generate`** | Built-in OpenClaw tool | AI-generated footage from a prompt or image | Native tool, 18 provider backends | -| **FFmpeg** | CLI tool | Post-processing, conversion | Agent exec, FFmpeg MCP | -| **Hosted template APIs** | Template services | Simple template videos without code | REST APIs, n8n/Make | - -Remotion is the best choice when you need **full programmatic control** and **React ecosystem compatibility**. Use `video_generate` for footage you cannot draw in code, and composite it in Remotion. - ---- - ## Cost and Performance Prices change too often to print here. What drives the cost: @@ -632,12 +403,10 @@ Prices change too often to print here. What drives the cost: ### Optimization tips -1. **Cache AI-generated assets** — don't regenerate images/audio for unchanged scenes -2. **Use `concurrency`** — `renderMedia({ concurrency: "75%" })` uses more CPU threads -3. **Render at target resolution** — don't render 4K if publishing to TikTok (1080x1920) -4. **Use a smaller model** (for example `anthropic/claude-haiku-5-5` or a local model) for script drafts when quality isn't critical -5. **Batch renders** — schedule renders overnight with an automation job -6. **Lambda for parallelism** — render multiple videos simultaneously in the cloud +1. Keep generated assets and reuse them for unchanged scenes. +2. Render at the target resolution (1080x1920 for vertical shorts), not 4K. +3. Use a cheaper model for script drafts, for example `anthropic/claude-haiku-5-5`. +4. Schedule batch renders overnight with an automation job. --- @@ -649,8 +418,7 @@ Prices change too often to print here. What drives the cost: | `Error: FFmpeg not found` | Install FFmpeg: `brew install ffmpeg` or `apt install ffmpeg` | | Blank frames | Ensure `useCurrentFrame()` is used and animations cover the frame range | | Audio out of sync | Use word-level timestamps from Whisper/ElevenLabs, not fixed offsets | -| Lambda timeout | Increase `timeoutInMilliseconds` or reduce video complexity | -| Memory issues on render | Reduce `concurrency` or render shorter segments | +| Memory issues on render | Lower `--concurrency` or render shorter segments | | Agent writes invalid Remotion code | Install Agent Skills: `npx skills add remotion-dev/skills` | --- @@ -660,7 +428,7 @@ Prices change too often to print here. What drives the cost: - [Remotion Docs](https://remotion.dev/docs/) — Official documentation - [Remotion AI Docs](https://remotion.dev/docs/ai/) — AI integration guide - [Remotion Templates](https://remotion.dev/templates/) — about 20 starter templates -- [Remotion Agent Skills](https://github.com/remotion-dev/skills) — 12 skills, about 5,300 stars +- [Remotion Agent Skills](https://github.com/remotion-dev/skills) — 12 skills - [ClawVid](https://github.com/neur0map/clawvid) — Short-form pipeline (example code, inactive) - [OpenClaw video generation](https://docs.openclaw.ai/tools/video-generation) — the built-in `video_generate` tool - [remotion-media-mcp](https://github.com/stephengpope/remotion-media-mcp) — Media generation MCP diff --git a/docs/guides/voice-multimodal.md b/docs/guides/voice-multimodal.md index 8530b71..6ca4e8d 100644 --- a/docs/guides/voice-multimodal.md +++ b/docs/guides/voice-multimodal.md @@ -41,7 +41,7 @@ When someone sends a voice note, OpenClaw transcribes it **before** the agent se 1. The active reply model, if its provider understands audio. 2. Any configured provider key that supports transcription, in this order: Groq, OpenAI, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral. -3. Local CLIs, if no provider key is available: `whisper-cli` (whisper.cpp), `sherpa-onnx-offline`, `parakeet-mlx` (Apple Silicon), then the Python `whisper` CLI. +3. Local CLIs, if no provider key is available: `sherpa-onnx-offline` (needs `SHERPA_ONNX_MODEL_DIR`), `whisper-cli` (whisper.cpp; tried first only once a GPU backend has been observed), `parakeet-mlx` (Apple Silicon), then the Python `whisper` CLI. See what it picked without transcribing anything: @@ -245,9 +245,7 @@ Music works the same way with `music_generate` (ComfyUI, fal, Google Lyria, Mini ## Wearable & Mobile Multimodal -### VisionClaw (Smart Glasses) - -[VisionClaw](https://github.com/Intent-Lab/VisionClaw) (Intent-Lab, about 2,600 stars, active as of 2026-09) is a third-party iOS app that connects Meta Ray-Ban glasses to Gemini Live and an OpenClaw Gateway for voice-and-vision requests. It is not maintained by OpenClaw; review what it can reach before pairing it with your Gateway. +Third-party wearable bridges, such as VisionClaw for Meta Ray-Ban glasses, are listed on [Ecosystem](/reference/ecosystem#visionclaw). They are not maintained by OpenClaw; review what they can reach before pairing one with your Gateway. ### Official apps diff --git a/docs/guides/webclaw.md b/docs/guides/webclaw.md index 45b5331..cbaa7cf 100644 --- a/docs/guides/webclaw.md +++ b/docs/guides/webclaw.md @@ -13,7 +13,7 @@ keywords: [openclaw, webclaw, pinchchat, web client, browser frontend, control u [WebClaw](https://github.com/ibelick/webclaw) hard-codes Gateway protocol **3** (`minProtocol: 3, maxProtocol: 3`). Gateways have required protocol **4** for operator and UI clients since 2026.5.19; only node-role devices may still use v3. Against v2026.10.4 the handshake fails with a protocol mismatch. Updating the Gateway does not help: the Gateway update is what broke it. The project has had no commits since 2026-03-17. ::: -This page used to be a WebClaw setup guide. It is now a short note on browser front-ends, checked on 2026-10-18 against OpenClaw **v2026.10.4**. +Checked on 2026-10-18 against OpenClaw **v2026.10.4**. --- @@ -99,13 +99,14 @@ PinchChat asks for `operator.admin` and keeps your Gateway token in `localStorag ## Building Your Own Client -Use `@openclaw/gateway-client` and follow the protocol v4 handshake (`connect.challenge` → `connect` → `hello-ok`) rather than copying an old client. See [API & Webhooks: WebSocket API](/guides/api-webhooks#websocket-api) and upstream's [Building a Gateway client](https://docs.openclaw.ai/gateway/clients). +Use `@openclaw/gateway-client` and follow the protocol v4 handshake (`connect.challenge` → `connect` → `hello-ok`) rather than copying an old client. See [Gateway API: WebSocket protocol](/reference/gateway-api#websocket-protocol-v4) and upstream's [Building a Gateway client](https://docs.openclaw.ai/gateway/clients). --- ## See Also -- [API & Webhooks](/guides/api-webhooks): Gateway protocol, auth, remote access +- [Gateway API](/reference/gateway-api): WebSocket protocol, scopes, auth +- [API & Webhooks](/guides/api-webhooks): webhooks and remote access - [Channels & Integrations](/guides/channels): chat apps as front-ends - [Security Hardening](/security/hardening): exposing the Gateway safely - [Ecosystem](/reference/ecosystem): other community projects diff --git a/docs/guides/workboard.md b/docs/guides/workboard.md index 493a1b0..5fa1681 100644 --- a/docs/guides/workboard.md +++ b/docs/guides/workboard.md @@ -14,7 +14,7 @@ The Workboard is a Kanban-style task board bundled with OpenClaw as a plugin (di The first Workboard entries appear in v2026.5.28; the orchestration primitives (dependencies, dispatch, claims) landed in v2026.5.31 and v2026.6.1. Official reference: [Workboard plugin](https://docs.openclaw.ai/plugins/workboard) and [Workboard CLI](https://docs.openclaw.ai/cli/workboard). :::info -The Workboard manages **local operating work** within your OpenClaw Gateway. It is not a replacement for GitHub Issues, Linear, or Jira — it's purpose-built for coordinating agent tasks. +The Workboard tracks work inside one Gateway. It is not an issue tracker: keep GitHub Issues, Linear or Jira for the project itself. ::: --- @@ -32,13 +32,7 @@ You can also enable it in config: ```json5 title="~/.openclaw/openclaw.json" { - "plugins": { - "entries": { - "workboard": { - "enabled": true - } - } - } + plugins: { entries: { workboard: { enabled: true } } }, } ``` @@ -46,8 +40,6 @@ You can also enable it in config: ## Cards -Each Workboard card represents a unit of work for an agent. - ### What a Card Contains | Field | Required | Description | @@ -86,7 +78,7 @@ If a card is linked to a session, the Workboard updates the card state automatic - Active session → card moves to `running` - Completed session → card moves to `review` -- Failed or timed-out session → card moves to `blocked` +- Failed, killed, timed-out or aborted session → card moves to `blocked` Once you manually move a card to `review`, `blocked`, or `done`, automatic sync stops until you move it back to `todo` or `running`. @@ -170,13 +162,12 @@ When you run `dispatch`, the Workboard: 5. **Claims each card** for the dispatcher or assigned agent 6. **Starts workers**: each worker is a subagent run with bounded card context and the claim token -Dispatch can be triggered from: +Dispatch can be triggered from (a card's **Start** action in the dashboard starts that one card directly): - The dashboard dispatch button - `openclaw workboard dispatch` in the CLI - `/workboard dispatch` on chat channels -- Manually starting a card from the Workboard UI -Dispatch does not run on its own. To dispatch on a schedule, create an automation (see [Recipes](#self-organizing-heartbeat)). +Dispatch does not run on its own. To dispatch on a schedule, run `openclaw workboard dispatch` from a cron job or systemd timer on the Gateway host. An agent cannot do it for you: the `workboard_dispatch` tool promotes dependencies and cleans stale claims but does not start workers. For a scheduled agent review of the board, see [Self-Organizing Heartbeat](#self-organizing-heartbeat). --- @@ -216,18 +207,6 @@ Workers that the Workboard starts from a card (**Start** or dispatch) do not nee The full list, including attachments, notifications and recovery tools, is in the [plugin reference](https://docs.openclaw.ai/plugins/workboard#agent-tools). -### What This Enables - -An agent can: -- Check the board for available work -- Claim a card and begin working -- Create sub-task cards for complex work -- Link cards into dependency chains -- Keep its claim alive during long-running tasks -- Review its own run history - -This makes autonomous workflows possible — an orchestrator agent creates cards, specialist agents claim and execute them, and the Workboard tracks everything. - --- ## Dashboard Workflow @@ -252,35 +231,6 @@ Workboard supports templates for common card types. Templates pre-fill title, no --- -## Dreaming Tab & Agent Selector - -v2026.6.1 added an agent selector to the Control UI **Dreaming** tab. In a multi-agent setup it lets you pick which agent's dreaming status, phase progress and Dream Diary you are looking at. - -The selector changes the view, not the schedule. Dreaming (the `memory-core` plugin's memory consolidation) has one sweep per Gateway with a single `frequency`, owned by `agents.defaults.systemAgent`. It has been **on by default since v2026.8.1** and runs its phases in the order light → REM → deep. `/dreaming on` and `/dreaming off` switch it globally; there is no per-agent schedule or pause. - -To change the schedule or turn it off: - -```json5 title="~/.openclaw/openclaw.json" -{ - plugins: { - entries: { - "memory-core": { - config: { - dreaming: { - enabled: true, - frequency: "0 3 * * *", // 3 AM daily (the default) - }, - }, - }, - }, - }, -} -``` - -See [Dreaming](https://docs.openclaw.ai/concepts/dreaming) and the [Memory Systems guide](/guides/memory-systems). - ---- - ## Practical Recipes ### Research → Writing Pipeline @@ -309,9 +259,9 @@ A researcher agent gathers information, a writer agent turns it into content: 1. Create Workboard cards for each research topic with `--agent researcher --status ready` 2. Run `openclaw workboard dispatch` -3. Researcher completes work → cards move to `review` -4. Review the research, then create new cards assigned to `writer` linking the research sessions -5. Dispatch again — writer turns research into polished output +3. When a researcher run completes, its card moves to `review` +4. Review the research, then create cards assigned to `writer` that reference the research sessions (`--notes`), or link them as children so they wait for the research cards +5. Dispatch again for the writing pass ### Bug Triage