From 6a54c11701303234c405aeba41e4ea7fc9b90194 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:49:11 +0200 Subject: [PATCH 01/12] comparison: fix channel count, cut marketing lines, align agent rows --- docs/reference/comparison.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/reference/comparison.md b/docs/reference/comparison.md index a31fbe2..fe82646 100644 --- a/docs/reference/comparison.md +++ b/docs/reference/comparison.md @@ -9,8 +9,6 @@ keywords: [openclaw, openclaw vs, alternative, comparison, hermes agent, devin, # Comparison -How does OpenClaw compare to other AI agent frameworks, coding assistants, and automation tools? This page is a side-by-side comparison with the trade-offs left in. - Star counts are from `gh api` and prices from each vendor's pricing page, **as of 2026-10-18**. Both drift; check before you decide. --- @@ -19,7 +17,7 @@ Star counts are from `gh api` and prices from each vendor's pricing page, **as o | Framework | Stars | Type | Price | Messaging apps | Runs locally | Multi-agent | |-----------|------:|------|-------|-----------|-------|-------------| -| **OpenClaw** | 392k | Self-hosted agent gateway | Free (MIT) + model costs | Built in (dozens of channels) | Yes | Yes (agents, sub-agents) | +| **OpenClaw** | 392k | Self-hosted agent gateway | Free (MIT) + model costs | Built in (about 30 channels, most as official plugins) | Yes | Yes (agents, sub-agents) | | **Hermes Agent** | 255k | Self-hosted personal agent | Free (MIT) + model costs | Built in (Telegram, Discord, Slack, WhatsApp, Signal) | Yes | Sub-agents | | **AutoGPT** | 187.6k | Agent platform | Free (OSS) | No | Yes | Limited | | **n8n** | 207.9k | Workflow automation | Self-host free | Via nodes | Self-host | N/A | @@ -35,7 +33,7 @@ Star counts are from `gh api` and prices from each vendor's pricing page, **as o Repos: [Hermes Agent](https://github.com/NousResearch/hermes-agent), [AutoGPT](https://github.com/Significant-Gravitas/AutoGPT), [n8n](https://github.com/n8n-io/n8n), [LangChain](https://github.com/langchain-ai/langchain), [MetaGPT](https://github.com/FoundationAgents/MetaGPT), [Open Interpreter](https://github.com/openinterpreter/openinterpreter), [CrewAI](https://github.com/crewAIInc/crewAI), [Goose](https://github.com/aaif-goose/goose). -A security column used to sit here. Security depends far more on how you deploy a tool than on which tool it is, so it now has its own [section below](#the-trade-off). +There is no security column: security depends more on how you deploy a tool than on which tool it is. See [The trade-off](#the-trade-off). --- @@ -61,7 +59,7 @@ Several managed hosts run both; see [Hosting Providers](/guides/hosting-provider ### Auto-GPT -The OG autonomous agent. One of the first projects to demonstrate LLM-driven autonomous behavior (launched 2023). +One of the first LLM-driven autonomous agent projects (2023), now a low-code agent platform. | | Auto-GPT | OpenClaw | |---|---|---| @@ -81,7 +79,7 @@ The closest conceptual relative — both give LLMs local system access through n | | Open Interpreter | OpenClaw | |---|---|---| -| **Interface** | Terminal only | 50+ messaging platforms | +| **Interface** | Terminal only | About 30 chat channels, Control UI, native apps | | **Focus** | Code execution via conversation | General-purpose life automation | | **Memory** | Conversation-scoped by default | Persistent across sessions | | **Autonomy** | Reactive | Proactive (heartbeat, scheduled Automations) | @@ -114,7 +112,7 @@ Purpose-built for multi-agent collaboration with role-based agent design. ### LangChain / LangGraph -The enterprise standard for building AI applications. +A developer library for building LLM applications; LangGraph adds stateful, multi-agent graphs. | | LangChain/LangGraph | OpenClaw | |---|---|---| @@ -122,11 +120,11 @@ The enterprise standard for building AI applications. | **Stability** | Versioned library releases | Rapidly evolving; doctor migrates or refuses retired config keys | | **Enterprise** | Widely used in production apps | Built for a single trusted operator per Gateway; team features are newer | | **Observability** | LangSmith platform | Official [`diagnostics-otel`](https://docs.openclaw.ai/plugins/reference/diagnostics-otel) OpenTelemetry plugin, audit ledger | -| **Learning curve** | Steep (significant abstraction) | Low (just configure and chat) | +| **Learning curve** | Steep (significant abstraction) | Low to start; running it safely takes config and [hardening](/security/hardening) | **Choose LangChain if:** You're building a production AI application and need enterprise observability, reliability, and support. -**Choose OpenClaw if:** You want something that works out of the box without writing code. +**Choose OpenClaw if:** You want a ready-made assistant rather than a library to build one. ### MetaGPT @@ -135,7 +133,7 @@ Multi-agent framework modeled on a software company (PM, architect, engineer rol | | MetaGPT | OpenClaw | |---|---|---| | **Approach** | Software company simulation | Personal assistant | -| **Agents** | PM → Architect → Engineer → QA | Single agent with skills | +| **Agents** | PM → Architect → Engineer → QA | One default agent; more via `agents.entries` and sub-agents | | **Best for** | Generating entire software projects from one-line requirements | General-purpose automation | | **Stars** | 70.9k | 392k | | **Activity** | No push since 2026-01-21 | Daily | @@ -157,7 +155,7 @@ AI software engineer with its own cloud IDE, browser, and terminal. | **Autonomy** | End-to-end coding tasks | Any automation task | | **Data** | Goes to Cognition's servers | Files stay local; prompts go to your model provider unless you run local models | -**Choose Devin if:** You need an AI junior developer for end-to-end coding with enterprise security. +**Choose Devin if:** You want end-to-end coding tasks run in a vendor-hosted sandbox. **Choose OpenClaw if:** You want a free, general-purpose agent that runs locally. From ab572476f4c4f0c510cf8af7105bccbe3df72e2b Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:49:37 +0200 Subject: [PATCH 02/12] configuration: stop calling the no-file defaults safe, steer keys to .env --- docs/reference/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 6da1375..e043892 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -14,7 +14,7 @@ This page explains how OpenClaw's config works and shows the sections most self- ## How the config works -- **One JSON5 file.** OpenClaw reads `~/.openclaw/openclaw.json` (override with `OPENCLAW_CONFIG_PATH`). JSON5 allows comments, unquoted keys and trailing commas. The file is optional; with no file, OpenClaw uses safe defaults. Keep it a regular file, not a symlink: OpenClaw writes it atomically, which replaces a symlink target. +- **One JSON5 file.** OpenClaw reads `~/.openclaw/openclaw.json` (override with `OPENCLAW_CONFIG_PATH`). JSON5 allows comments, unquoted keys and trailing commas. The file is optional; with no file, OpenClaw uses built-in defaults (which include host exec without approval prompts; see [`tools`](#tools-exec-approvals-and-tool-policy)). Keep it a regular file, not a symlink: OpenClaw writes it atomically, which replaces a symlink target. - **Strict schema.** Unknown keys, wrong types and invalid enum values make the Gateway **refuse to start**. Only `$schema` is allowed as an extra root key. Pasting a key from an old blog post is the most common way to break an install. See [Strict validation](https://docs.openclaw.ai/gateway/configuration#strict-validation). - **Two buckets.** Root sections (`gateway`, `channels`, `models`, `tools`, ...) hold infrastructure and cross-agent defaults. `agents.defaults` holds agent-loop behaviour (model, workspace, heartbeat, sandbox). `agents.entries.` overrides either per agent. - **Hot reload.** The Gateway watches the file. Most changes apply live; a few (auth mode, listener topology, TLS) restart the Gateway automatically in the default `hybrid` reload mode. An invalid edit is skipped and the last good config keeps running. See [Config hot reload](https://docs.openclaw.ai/gateway/configuration/hot-reload). @@ -57,7 +57,7 @@ Large configs can be split. An object can be replaced by `{ $include: "./file.js Any string value can reference an environment variable with `${VAR_NAME}`. Only uppercase names (`[A-Z_][A-Z0-9_]*`) are substituted. A missing or empty variable stays visibly unresolved, logs a warning, and the feature that needs it is unavailable: it does not fall back to anything. Write `$${VAR}` for a literal `${VAR}`. -Variables come from the process environment, then `./.env`, then `~/.openclaw/.env`, then the config's own `env.vars` block; none of these override a variable that is already set. `~/.openclaw/.env` is the usual place for API keys on a self-hosted box. Details: [Environment variables](/reference/environment-variables) and [upstream](https://docs.openclaw.ai/gateway/configuration/environment-variables). +Variables come from the process environment, then `./.env`, then `~/.openclaw/.env`, then the config's own `env.vars` block; none of these override a variable that is already set. `~/.openclaw/.env` (mode `600`) is the usual place for API keys on a self-hosted box; `env.vars` (below) also works, but it puts the key in `openclaw.json` itself, which ends up in backups and screen shares. Details: [Environment variables](/reference/environment-variables) and [upstream](https://docs.openclaw.ai/gateway/configuration/environment-variables). ```json5 title="~/.openclaw/openclaw.json" { From 467a7b1871d3c2f5b34e5e927efaa122ef36ea9b Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:50:00 +0200 Subject: [PATCH 03/12] ecosystem: cut star-count intro, fix Windows Hub count, label the Apple minimum change as beta --- docs/reference/ecosystem.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/reference/ecosystem.md b/docs/reference/ecosystem.md index ac2dbab..75d9958 100644 --- a/docs/reference/ecosystem.md +++ b/docs/reference/ecosystem.md @@ -9,7 +9,7 @@ keywords: [openclaw, openclaw ecosystem, community projects, tools, integrations # Ecosystem & Community Tools -OpenClaw passed 392,000 GitHub stars about eleven months after its first release, and a large ecosystem grew around it. This page lists the official companion projects first, then community tools by category. +Official companion projects first, then community tools by category. :::info How to read this page Star counts, last-push dates and archive status come from `gh api` **as of 2026-10-18**. Re-run `node scripts/refresh-stars.mjs` to refresh them. Community projects are not reviewed or endorsed by OpenClaw or by clawdocs; check activity and the code before you give any of them credentials. Archived or abandoned projects are kept below only so that old links still explain themselves. @@ -71,17 +71,17 @@ In February 2026, Koi Security reported 341 malicious skills on ClawHub (the fir Started by Scott Hanselman as `shanselman/openclaw-windows-hub`, it now lives at [openclaw/openclaw-windows-node](https://github.com/openclaw/openclaw-windows-node) and is upstream's **recommended Windows desktop app**: a native WinUI app for Windows 10 20H2+ and 11 with setup, tray status, chat, diagnostics and Windows node capabilities, signed x64 and ARM64 installers, and no admin rights needed. See [docs.openclaw.ai/platforms/windows](https://docs.openclaw.ai/platforms/windows). -- 2,158 stars, last push 2026-10-17. +- 2,159 stars, last push 2026-10-17. The installers are named `OpenClawCompanion-Setup-x64.exe` and `-arm64.exe`. ### Native apps - **macOS:** OpenClaw.app in v2026.10.4 needs macOS 15.0 (Sequoia) or later; Voice Wake and push-to-talk need macOS 26 ([docs](https://docs.openclaw.ai/platforms/macos)). - **iOS/iPadOS:** on the App Store; v2026.10.4 targets iOS 18.0 or later ([docs](https://docs.openclaw.ai/platforms/ios)). +- **Android:** on Google Play, plus a signed APK on some GitHub releases; minSdk 31. It is a companion node and needs a running Gateway ([docs](https://docs.openclaw.ai/platforms/android)). -:::note -The next release raises the minimum for both apps to macOS 26.2 (Tahoe) and iOS/iPadOS 26.2. The live upstream pages already show the new minimum. +:::warning Changing in 2026.10.10 (beta) +2026.10.10-beta.1 (npm `beta`, 2026-10-15; not in 2026.10.4) raises the minimum for both Apple apps to macOS 26.2 (Tahoe) and iOS/iPadOS 26.2. The live upstream pages, built from `main`, already show the new minimum. ::: -- **Android:** on Google Play, plus a signed APK on some GitHub releases; minSdk 31. It is a companion node and needs a running Gateway ([docs](https://docs.openclaw.ai/platforms/android)). --- From 6bcdddd8e86a3c3562ff50b61ee99e0bb4d616a2 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:50:56 +0200 Subject: [PATCH 04/12] faq: cut unsourced cost table, correct rollback and ClawHub scan claims, fix DeepSeek Flash ref --- docs/reference/faq.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 591f010..7b6fa90 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -20,7 +20,7 @@ OpenClaw is a free, open-source AI agent that you run yourself. A long-running G ### Is OpenClaw free? -**OpenClaw itself is free** (MIT license). You pay for LLM API usage if you use cloud providers. Users have reported costs from a few dollars a day to $3,600/month depending on usage. Running [local models](/guides/local-models) removes API costs. +**OpenClaw itself is free** (MIT license). You pay for LLM API usage if you use cloud providers. Reported bills range from a few dollars a month to thousands; see [How much does it cost to run?](#how-much-does-it-cost-to-run). Running [local models](/guides/local-models) removes API costs. ### Why was it renamed twice? @@ -56,7 +56,7 @@ The v2026.6.11 regression where tools returned empty output after the first call ### Is OpenClaw safe to use? -It is powerful, and it carries real risk. It has had: +Only if you configure it carefully. It has real access to your machine, and it has had: - **722 published GitHub security advisories** as of 2026-10-18, 14 of them critical ([Known Vulnerabilities](/security/known-vulnerabilities#advisories-at-a-glance)) - Batches of 45 advisories on [June 30, 2026](/security/known-vulnerabilities#june-2026-advisory-batch-june-30-2026) and 75 on [September 11, 2026](/security/known-vulnerabilities#september-2026-advisory-batch), all fixed in released versions. Run the latest stable release. - A [one-click RCE](/security/known-vulnerabilities#cve-2026-25253-one-click-remote-code-execution) (CVE-2026-25253, fixed in v2026.1.29) @@ -94,15 +94,7 @@ Workspace `.env` files cannot override `OPENCLAW_*` variables or provider creden ### How much does it cost to run? -Costs people reported in early 2026 (press and forum posts, not our measurements): - -| User | Usage | Monthly cost | -|------|-------|-------------| -| Light user | CLI chat, occasional tasks | $30-150 | -| Moderate user | Heartbeat + 1-2 channels | $150-450 | -| Heavy user (Federico Viticci) | Full automation, 1.8M tokens | $3,600 | -| German magazine c't test | Full-day testing | $100+ in one day | -| Heartbeat overnight | Just asking "Is it daytime yet?" | $18.75 overnight | +It depends almost entirely on the model, how often the agent wakes up, and how long sessions grow. Anecdotes from early 2026 ranged from a few dollars a month to $3,600 in one month of always-on automation, on older models and prices; we have not measured them, so treat them as a warning, not an estimate. [Cost Management](/guides/cost-management) has worked estimates. The main cost drivers are **context accumulation** (long sessions), the **heartbeat** (it runs even when idle), and **autonomous multi-step tool use**. `openclaw gateway usage-cost` shows what you have actually spent. @@ -128,7 +120,7 @@ Yes, with [local models](/guides/local-models) via Ollama, LM Studio or vLLM. No |--------------|---------------| | Best quality | `anthropic/claude-opus-5-5` | | Best balance | `anthropic/claude-sonnet-5-5` | -| Cheap and fast | `anthropic/claude-haiku-5-5` or `deepseek/deepseek-v4-flash` | +| Cheap and fast | `anthropic/claude-haiku-5-5` or `deepseek/deepseek-flash` | | Free (local) | an Ollama model such as `ollama/qwen3:14b` | A fresh Anthropic setup picks `anthropic/claude-opus-5-5`. Prices change often; check the provider's pricing page. See the [Model Selection Guide](/guides/model-selection) and the upstream [provider pages](https://docs.openclaw.ai/providers/anthropic). @@ -226,7 +218,7 @@ openclaw update openclaw doctor ``` -`openclaw update` checks the result and rolls back if the post-update Doctor fails ([Updating](https://docs.openclaw.ai/install/updating)). If you skipped many releases, run `openclaw doctor --fix` to migrate retired config keys and files. +If the new version fails validation, the old Gateway keeps serving. Automatic rollback after activation works only when no database schema migration ran, so the backup is your real safety net ([Rollback and recovery](https://docs.openclaw.ai/install/updating/rollback-and-recovery)). If you skipped many releases, run `openclaw doctor --fix` to migrate retired config keys and files. Notable breaking updates from 2026: @@ -300,7 +292,7 @@ Yes, but email is an automation trigger, not a chat channel. Use the [Gmail Pub/ ### What is ClawHub? -[ClawHub](https://clawhub.ai) is OpenClaw's skill and plugin registry. It was the target of a [malicious skill campaign](/security/known-vulnerabilities#malicious-clawhub-skills-february-2026) in February 2026. Every release now gets an audit status from VirusTotal, ClawScan and static analysis, and `openclaw skills verify @owner/` fetches that verdict. A pending scan can still allow an install with a warning, so review skills yourself ([Skill Verification](/security/skill-verification)). +[ClawHub](https://clawhub.ai) is OpenClaw's skill and plugin registry. It was the target of a [malicious skill campaign](/security/known-vulnerabilities#malicious-clawhub-skills-february-2026) in February 2026. Since 2026-10-13 new releases stay unpublished until TruffleHog and ClawScan pass, and `openclaw skills verify @owner/` fetches a release's audit verdict. A pass is a signal, not a guarantee, so review skills yourself ([Skill Verification](/security/skill-verification)). ### What is Lobster? From fc34fe7247af0186bfa2dbd573699be413ec40ee Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:51:21 +0200 Subject: [PATCH 05/12] glossary: label the Apple minimum change as beta, current ClawHub scan hold, concrete monitor scratch commands --- docs/reference/glossary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index a8e54f1..9657a8c 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -47,7 +47,7 @@ Koi Security's [pre-install skill check](https://koisecurity.com/clawdex) agains ## ClawHub {#clawhub} -OpenClaw's skill and plugin registry at [clawhub.ai](https://clawhub.ai). Each release gets an audit status from VirusTotal, ClawScan and static analysis; `openclaw skills verify @owner/` fetches it. Target of the [ClawHavoc](#clawhavoc) campaign. See [ClawHub Guide](/guides/clawhub). +OpenClaw's skill and plugin registry at [clawhub.ai](https://clawhub.ai). Since 2026-10-13 a new release stays unpublished until its TruffleHog and ClawScan checks pass; `openclaw skills verify @owner/` fetches a release's audit verdict. Target of the [ClawHavoc](#clawhavoc) campaign. See [ClawHub Guide](/guides/clawhub). ## ClawHavoc {#clawhavoc} @@ -75,7 +75,7 @@ VirusTotal's AI-based package analysis, which early-2026 reports said [ClawHub]( ## Companion apps -Official native clients: the macOS app (macOS 15.0+ in v2026.10.4; the next release requires 26.2), the iOS app on the App Store, the Android app on Google Play, and the [Windows Hub](#windows-hub). See [Platforms](https://docs.openclaw.ai/platforms). +Official native clients: the macOS app (macOS 15.0+ in v2026.10.4; the 2026.10.10 beta raises it to 26.2), the iOS app on the App Store, the Android app on Google Play, and the [Windows Hub](#windows-hub). See [Platforms](https://docs.openclaw.ai/platforms). ## openclaw.json @@ -155,7 +155,7 @@ OpenClaw's second name (January 27-30, 2026), adopted after the [Clawdbot](#claw ## Monitor scratch {#monitor-scratch} -The heartbeat's instruction text, stored in the state database instead of a file. Edit it with `openclaw cron scratch `, or let the agent update it during a heartbeat turn. Replaces [HEARTBEAT.md](#heartbeatmd). See [Heartbeat](https://docs.openclaw.ai/gateway/heartbeat). +The heartbeat's instruction text, stored in the state database instead of a file. The heartbeat runs as an automation job: find its id with `openclaw cron list --all`, then read the scratch with `openclaw cron scratch ` or replace it with `--set "..."`. Replaces [HEARTBEAT.md](#heartbeatmd). See [Heartbeat](https://docs.openclaw.ai/gateway/heartbeat). ## NanoClaw From 8acb5d80915243bc2671016c055c3f31f8ed554c Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:51:41 +0200 Subject: [PATCH 06/12] resources: cut tables duplicated from Ecosystem (images, security tools, frontends, apps, alternatives) and link the canonical sections --- docs/reference/resources.md | 64 +++---------------------------------- 1 file changed, 5 insertions(+), 59 deletions(-) diff --git a/docs/reference/resources.md b/docs/reference/resources.md index 2cb4438..d70c1ac 100644 --- a/docs/reference/resources.md +++ b/docs/reference/resources.md @@ -142,27 +142,12 @@ For self-hosting, see [Deployment Options](/guides/deployment-options). | Template | Stars | Platform | Notes | |----------|------:|----------|-------| | [Railway template](https://github.com/arjunkomath/openclaw-railway-template) | 51 | Railway | Gateway + Control UI, persistent volume; upstream guide at [docs.openclaw.ai/install/railway](https://docs.openclaw.ai/install/railway) | -| [Helm chart (XROW)](https://artifacthub.io/packages/helm/openclaw/openclaw) | — | Kubernetes | Version 1.111.0 on Artifact Hub | -| [Helm chart (community)](https://github.com/serhanekicii/openclaw-helm) | 192 | Kubernetes | **Archived** (last push 2026-05-24) | -| [Coolify template](https://github.com/essamamdani/openclaw-coolify) | 154 | Coolify | Docker sidecar, Cloudflare Tunnel, SearXNG | -| [Moltworker](https://github.com/cloudflare/moltworker) | 9,948 | Cloudflare Workers | Experimental proof of concept, not officially supported; about $34.50/month 24/7 per its README | -Upstream maintains its own guides for Kubernetes (Kustomize), Cloudflare (Workers + Durable Object) and more: [docs.openclaw.ai/install](https://docs.openclaw.ai/install). +Helm charts, the Coolify template and Cloudflare's Moltworker are covered in [Ecosystem: Deployment tools](/reference/ecosystem#deployment-tools). Upstream maintains its own guides for Kubernetes (Kustomize), Cloudflare (Workers + Durable Object) and more: [docs.openclaw.ai/install](https://docs.openclaw.ai/install). ### Docker images -:::warning -Upstream says to use `ghcr.io/openclaw/openclaw` or `openclaw/openclaw` and to "avoid unofficial mirrors" ([Docker install](https://docs.openclaw.ai/install/docker)). -::: - -| Image | Maintainer | Notes | -|-------|-----------|-------| -| `ghcr.io/openclaw/openclaw` | OpenClaw | **Official**, primary; `-slim` and `-browser` variants | -| `openclaw/openclaw` | OpenClaw | **Official** Docker Hub mirror | -| `1panel/openclaw` | 1Panel | Unofficial | -| `coollabsio/openclaw` | Coolify team | Unofficial | -| `alpine/openclaw` | Community | Unofficial; last updated 2026-06-21 | -| `land007/webclaw` | Community | Unofficial WebClaw frontend image; WebClaw cannot connect to current Gateways | +Use the official images, `ghcr.io/openclaw/openclaw` or its Docker Hub mirror `openclaw/openclaw`. Unofficial images are listed, with warnings, in [Ecosystem: Docker images](/reference/ecosystem#docker-images). ### Cloud platforms @@ -218,52 +203,13 @@ For a comparison, see [Memory Systems](/guides/memory-systems). | [Known Vulnerabilities](/security/known-vulnerabilities) | CVE history | | [Skill Verification](/security/skill-verification) | Checking skills before install | -### Community tools - -| Tool | Stars | Status | -|------|------:|--------| -| [ClawSec](https://github.com/prompt-security/clawsec) | 1,122 | Active; security skill suite | -| [Security Monitor](https://github.com/adibirzu/openclaw-security-monitor) | 49 | Active; scheduled threat checks | -| [ClawBands](https://github.com/SeyZ/clawbands) | 196 | No push since 2026-02-09; approval middleware | -| [Clawprint](https://github.com/tsyrulb/clawprint) | 1 | **Archived**; "historical personal project" | -| [SkillGuard](https://github.com/bossondehiggs/skillguard) | 0 | Abandoned; not recommended | - ---- - -## Browser and desktop frontends - -| Frontend | Stars | Status | Notes | -|----------|------:|--------|-------| -| **Control UI** (built in) | — | Official | Served by the Gateway at `http://127.0.0.1:18789/`; chat, files, approvals, settings ([docs](https://docs.openclaw.ai/web/control-ui)) | -| [Windows Hub](https://github.com/openclaw/openclaw-windows-node) | 2,158 | Official | Native WinUI app ([Ecosystem](/reference/ecosystem#openclaw-windows-hub)) | -| [WebClaw](https://github.com/ibelick/webclaw) | 647 | No push since 2026-03-17; protocol 3 only, cannot connect to current Gateways (use the Control UI) | [WebClaw Guide](/guides/webclaw) | -| [PinchChat](https://github.com/MarlBurroW/pinchchat) | 187 | Last push 2026-06-18 | [WebClaw Guide](/guides/webclaw#pinchchat-alternative-frontend) | - ---- - -## Companion apps - -| Platform | Status | Notes | -|----------|--------|-------| -| **macOS** | Released | OpenClaw.app, macOS 15.0 or later in v2026.10.4 (the next release requires 26.2) ([docs](https://docs.openclaw.ai/platforms/macos)) | -| **iOS / iPadOS** | App Store | iOS 18.0 or later in v2026.10.4 (the next release requires 26.2) ([docs](https://docs.openclaw.ai/platforms/ios)) | -| **Android** | Google Play | Companion node, minSdk 31; signed APK on some GitHub releases ([docs](https://docs.openclaw.ai/platforms/android)) | -| **Windows** | Official | [Windows Hub](https://docs.openclaw.ai/platforms/windows), x64 and ARM64 | +Community security tools (ClawSec, ClawBands and others) are reviewed in [Ecosystem: Security tools](/reference/ecosystem#security-tools). --- -## Lightweight alternatives - -| Project | Stars | Language | Notes | -|---------|------:|----------|-------| -| [Nanobot](https://github.com/HKUDS/nanobot) | 49,143 | Python | HKUDS; many chat apps and providers | -| [NanoClaw](https://github.com/nanocoai/nanoclaw) | 30,964 | TypeScript | Agents in containers | -| [PicoClaw](https://github.com/sipeed/picoclaw) | 30,087 | Go | $10 hardware; pre-1.0 | -| [IronClaw](https://github.com/nearai/ironclaw) | 12,661 | Rust | NEAR AI; WASM-sandboxed tools | -| [MimiClaw](https://github.com/memovai/mimiclaw) | 5,799 | C | ESP32-S3 | -| [TinyAGI](https://github.com/TinyAGI/tinyagi) | 3,621 | TypeScript | Agent teams; formerly `jlia0/tinyclaw` | +## Apps and alternative agents -More in [Lightweight Variants](/guides/lightweight-variants) and [Ecosystem](/reference/ecosystem#lightweight-alternatives). +The official apps (macOS, iOS, Android, Windows Hub), third-party frontends and lightweight alternative agents are listed once, with stars and status, in [Ecosystem & Community Tools](/reference/ecosystem). The built-in Control UI at `http://127.0.0.1:18789/` is the supported browser client. --- From 08fde6ece7491c83b9a2f799dd9f5d1f373aba78 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:52:35 +0200 Subject: [PATCH 07/12] troubleshooting: make the first-steps ladder truly read-only (doctor --lint), correct rollback claim, fix Discord invite --- docs/reference/troubleshooting.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 3d97388..bd71b4c 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -9,7 +9,7 @@ keywords: [openclaw, openclaw troubleshooting, fix, debug, openclaw not working, # Troubleshooting & Debugging -A short, tested companion to the official runbooks. Every command here exists in OpenClaw v2026.10.4, and every error string is quoted from upstream docs or source. For the full symptom index, see the upstream [General troubleshooting](https://docs.openclaw.ai/help/troubleshooting) hub and the deep [Gateway troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting) runbook. +Every command here exists in OpenClaw v2026.10.4, and every error string is quoted from upstream docs or source. For the full symptom index, see the upstream [General troubleshooting](https://docs.openclaw.ai/help/troubleshooting) hub and the deep [Gateway troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting) runbook. --- @@ -20,12 +20,14 @@ Run this ladder in order. Each step is read-only. ```bash openclaw status # channels, auth, versions at a glance openclaw gateway status # service state, probe, capability -openclaw doctor # config and service checks (add --fix to repair) +openclaw doctor --lint # read-only config and service checks openclaw channels status --probe openclaw logs --follow # live gateway log ``` -Healthy output: `openclaw gateway status` shows `Runtime: running`, `Connectivity probe: ok` and a `Capability: ...` line; `openclaw doctor` reports no blocking issues; `channels status --probe` shows each account connected (and `works` or `audit ok` where supported). +Healthy output: `openclaw gateway status` shows `Runtime: running`, `Connectivity probe: ok` and a `Capability: ...` line; `openclaw doctor --lint` reports no blocking findings; `channels status --probe` shows each account connected (and `works` or `audit ok` where supported). + +Plain `openclaw doctor` (without `--lint` or `--json`) is not read-only: it can copy legacy config and migrate state even without `--fix`. Take a backup before you run it on a broken install. If you want one bundle to hand to a person or a coding agent, `openclaw triage` writes a sanitized diagnosis and, when the Gateway is reachable, a support archive. @@ -506,7 +508,7 @@ openclaw backup create --verify ### Rollback Procedure -`openclaw update` rehearses in an isolated candidate state and rolls back when post-update Doctor fails. To go back by hand: +If a new version fails validation, the old Gateway keeps serving. Automatic rollback after activation only happens when no database schema migration ran ([Rollback and recovery](https://docs.openclaw.ai/install/updating/rollback-and-recovery)). To go back by hand: ```bash openclaw update --tag 2026.10.3 --yes # one-off install of a specific version @@ -529,7 +531,9 @@ openclaw backup restore ~/Backups/latest.tar.gz --target ./restored-openclaw Back up with `openclaw backup create`, which covers config, credentials, sessions and workspaces; copying files by hand misses the state database. -### Enable Audit Logging +### Audit Logging {#enable-audit-logging} + +The audit ledger is on by default. These are its main keys, shown with explicit values: ```json5 title="~/.openclaw/openclaw.json" { @@ -577,14 +581,14 @@ openclaw gateway diagnostics export # payload-free .zip to attach openclaw status --all # pasteable text report ``` -- **Discord:** [discord.gg/openclaw](https://discord.gg/openclaw) +- **Discord:** [discord.gg/clawd](https://discord.gg/clawd) (`#help`, `#users-helping-users`) - **GitHub Issues:** [github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) - **FAQ:** [/reference/faq](/reference/faq) When reporting an issue, include: 1. `openclaw --version`, `node --version`, OS and architecture 2. `openclaw status --all` -3. `openclaw doctor` output +3. `openclaw doctor --lint` output 4. Relevant log lines (`openclaw logs --limit 50`) Check that pasted output contains no tokens or keys. From 1b6e51b808a5d8a7f0f8c3cafcf1485eb398903f Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:52:35 +0200 Subject: [PATCH 08/12] cli: note that only doctor --lint is read-only --- docs/reference/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index dcff0d5..78acb14 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -35,7 +35,7 @@ There is no global `--config`, `--json`, `--verbose` or `--quiet`. Use `OPENCLAW | [`setup`](https://docs.openclaw.ai/cli/setup) | Chat with OpenClaw, onboarding first if setup is incomplete. `setup --baseline` just writes the baseline config and workspace. | | [`configure`](https://docs.openclaw.ai/cli/configure) | Interactive editor for an existing setup (models, Gateway, channels, plugins, skills). | | [`config`](https://docs.openclaw.ai/cli/config) | Non-interactive `get`, `set`, `patch`, `unset`, `file`, `schema`, `validate`. See [Configuration](/reference/configuration). | -| [`doctor`](https://docs.openclaw.ai/cli/doctor) | Health checks; `--fix` applies repairs and config migrations. Run it after every upgrade. | +| [`doctor`](https://docs.openclaw.ai/cli/doctor) | Health checks; `--fix` applies repairs and config migrations. Run it after every upgrade. Plain `doctor` can still migrate state; `--lint` is the read-only mode. | | [`update`](https://docs.openclaw.ai/cli/update) | Update OpenClaw (`--channel stable\|extended-stable\|beta\|dev`, `--dry-run`, `status`). | | [`backup`](https://docs.openclaw.ai/cli/backup) | `create`, `verify`, `restore` archives of config, credentials, sessions and workspaces. | | [`reset`](https://docs.openclaw.ai/cli/reset) / [`uninstall`](https://docs.openclaw.ai/cli/uninstall) | Reset local state, or remove the service and local data. | From ef837c11977e8969b9e42c6a19c339d9e317d4f4 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:53:14 +0200 Subject: [PATCH 09/12] api-webhooks: replace the duplicated protocol walkthrough with integrator notes and a link to the Gateway API reference --- docs/guides/api-webhooks.md | 41 ++++++------------------------------- 1 file changed, 6 insertions(+), 35 deletions(-) diff --git a/docs/guides/api-webhooks.md b/docs/guides/api-webhooks.md index 1361c1b..fc09bfb 100644 --- a/docs/guides/api-webhooks.md +++ b/docs/guides/api-webhooks.md @@ -9,7 +9,7 @@ keywords: [openclaw, openclaw api, webhook, hooks, websocket, gateway protocol, # API & Webhooks -Everything external talks to one place: the Gateway, on one port (default `18789`). This page covers the surfaces you can integrate with, how to authenticate, and how to expose them safely. Checked against OpenClaw **v2026.10.4** on 2026-10-18. +Everything external talks to the Gateway on one port (default `18789`). This page covers webhooks in, results out, the client library, and how to expose them safely. --- @@ -215,40 +215,11 @@ OpenClaw has no generic outbound-webhook system (`webhooks.outgoing` does not ex ## WebSocket API -The Gateway's WebSocket protocol is what the CLI, Control UI and native apps use. It is a typed RPC protocol, currently **version 4**. Clients that only speak v3 (except node-role devices) are rejected. +The Gateway's WebSocket protocol (version 4) is what the CLI, Control UI and native apps use. Frames, the `connect.challenge` handshake, scopes and the method list are summarised in the [Gateway API reference](/reference/gateway-api); this section covers what an integrator does differently. -### Frames - -- Request: `{ "type": "req", "id", "method", "params" }` -- Response: `{ "type": "res", "id", "ok", "payload" | "error" }` -- Event: `{ "type": "event", "event", "payload", "seq"? }` - -### Handshake - -1. The client opens the socket. The Gateway sends a `connect.challenge` event with a `nonce` and `ts`. -2. The client's first frame **must** be a `connect` request: - -{/* snippet:skip: Gateway protocol frame, not openclaw.json */} -```json title="connect request (abridged)" -{ - "type": "req", - "id": "1", - "method": "connect", - "params": { - "minProtocol": 4, - "maxProtocol": 4, - "client": { "id": "my-dashboard", "version": "0.1.0", "platform": "linux", "mode": "operator" }, - "role": "operator", - "scopes": ["operator.read", "operator.write"], - "auth": { "token": "" }, - "device": { "id": "…", "publicKey": "…", "signature": "…", "signedAt": 1737264000000, "nonce": "…" } - } -} -``` - -3. The Gateway replies with `hello-ok` (negotiated protocol, granted role and scopes, method and event lists, limits) and, after device pairing, a `deviceToken` to use on later connections. - -The token goes in `connect.params.auth.token`, **never** in the URL. A third-party UI client signs the challenge with its own Ed25519 device key and must be approved once on the Gateway host (`openclaw devices list`, then `openclaw devices approve `). Request only the scopes you need: `operator.read` (history, sessions), `operator.write` (`chat.send`), `operator.approvals` (exec approvals). `operator.admin` is full control. +- The token goes in `connect.params.auth.token`, **never** in the URL. +- A third-party UI client signs the challenge with its own Ed25519 device key and must be approved once on the Gateway host (`openclaw devices list`, then `openclaw devices approve `). After pairing, `hello-ok` returns a `deviceToken` for later connections. +- Request only the scopes you need: `operator.read` (history, sessions), `operator.write` (`chat.send`), `operator.approvals` (exec approvals). `operator.admin` is full control. ### Use the reference client @@ -299,7 +270,7 @@ The Gateway can serve `POST /v1/chat/completions`, `GET /v1/models` and `POST /v } ``` -The `model` field selects an OpenClaw **agent**, not a raw provider model. `POST /tools/invoke` runs a single tool under tool policy and is always on. +The `model` field selects an OpenClaw **agent** (`openclaw/`), not a raw provider model. `POST /tools/invoke` runs a single tool under tool policy and is always on. Endpoint details are in the [Gateway API reference](/reference/gateway-api#http-endpoints). :::danger Full operator access With token or password auth, a request to `/v1/*` or `/tools/invoke` carrying the Gateway token is treated as the owner, with every operator scope including `operator.admin`. If the agent may use exec or other sensitive tools, so may the caller. Keep these endpoints on loopback or a tailnet; never publish them. From b4a90f5f6f7a1f6299eee53bb69af8f98677b8a6 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:53:57 +0200 Subject: [PATCH 10/12] automation: point inbound webhook detail at API & Webhooks, keep tokens out of config, replace the padded platform table --- docs/guides/automation.md | 40 +++++++++------------------------------ 1 file changed, 9 insertions(+), 31 deletions(-) diff --git a/docs/guides/automation.md b/docs/guides/automation.md index 9e84dce..afc7eb0 100644 --- a/docs/guides/automation.md +++ b/docs/guides/automation.md @@ -119,7 +119,7 @@ Commands take the job **id** (from `list`), not its name. There is no `pause`/`r enabled: true, // false (or OPENCLAW_SKIP_CRON=1) stops all automations, including heartbeats skipMissedJobs: true, // don't catch up recurring slots missed while the Gateway was down sessionRetention: "24h", - webhookToken: "replace-with-a-dedicated-token", // Bearer token on outbound job webhooks + webhookToken: "${OPENCLAW_CRON_WEBHOOK_TOKEN}", // Bearer token on outbound job webhooks; keep the value in ~/.openclaw/.env }, } ``` @@ -140,40 +140,26 @@ Beyond time schedules, automations can fire from events. Each is documented upst ### Inbound webhooks {#incoming-webhooks} -Gateway HTTP hooks let an external service wake an agent or submit a turn. They are off by default and live under the `hooks` key: +Gateway HTTP hooks let an external service wake an agent or submit a turn. They are off by default and live under the `hooks` key, with their own token: ```json5 title="~/.openclaw/openclaw.json" { hooks: { enabled: true, - token: "replace-with-a-long-random-hook-token", // not your Gateway token - path: "/hooks", + token: "${OPENCLAW_HOOKS_TOKEN}", // a long random value, not your Gateway token allowedAgentIds: ["main"], - allowRequestSessionKey: false, }, } ``` -After `openclaw config validate` and `openclaw gateway restart`, test it from the Gateway host: +- `POST /hooks/agent` runs an agent turn with `message`; add `channel` and `to` to deliver the result. +- `POST /hooks/wake` queues a short, trusted system event for the main session. +- `POST /hooks/` maps custom paths through `hooks.mappings`. -```bash -curl --include http://127.0.0.1:18789/hooks/agent \ - -H 'Authorization: Bearer replace-with-a-long-random-hook-token' \ - -H 'Content-Type: application/json' \ - -H 'Idempotency-Key: deploy-2026-10-18-001' \ - --data '{"message":"A deployment just completed. Summarize the release notes.","agentId":"main","deliver":false}' -``` - -Endpoints: - -- `POST /hooks/agent`: run an agent turn with `message`. Add `channel` and `to` to deliver the result, or `"waitForCompletion": true` to get the outcome in the response. -- `POST /hooks/wake`: queue a short system event (`text`) for the main session. -- `POST /hooks/`: custom paths, defined in `hooks.mappings` with templates or transforms. See [Hooks config](https://docs.openclaw.ai/gateway/config-hooks). - -HTTP `200` means the run was admitted, not that it finished or delivered. Check `openclaw logs --follow` for `hook agent run completed`. +HTTP `200` means the run was admitted, not that it finished. Payload fields, `curl` examples, status codes, mappings and integration recipes (GitHub Actions, Home Assistant, n8n) are in [API & Webhooks](/guides/api-webhooks#webhook-ingress-external-to-agent). :::warning Webhook payloads are untrusted -Anything a webhook carries (an email body, an issue title, a deploy message) can contain instructions aimed at your agent. Route untrusted content through `/hooks/agent` to an agent with restricted tools, never through `/hooks/wake`, and keep the hook token separate from Gateway auth. See [Security hardening](/security/hardening). +Anything a webhook carries (an email body, an issue title, a deploy message) can contain instructions aimed at your agent. Route untrusted content through `/hooks/agent` to an agent with restricted tools, never through `/hooks/wake`. See [Security hardening](/security/hardening). ::: ### Outbound webhooks {#outgoing-webhooks} @@ -275,15 +261,7 @@ Run it with `lobster run deploy.lobster`. Syntax, approvals and the OpenClaw plu ### Messaging platforms {#messaging-platforms} -Full guides are in [Channels & Integrations](/guides/channels). - -| Platform | Setup | Automation use case | -|----------|-------|---------------------| -| **Slack** | App token | Team notifications, standup bots, incident response | -| **Discord** | Bot token | Community management, moderation, FAQ bot | -| **Telegram** | Bot token | Personal assistant, alerts, remote control | -| **WhatsApp** | QR pairing | Personal messaging, family coordination | -| **iMessage** | macOS only | Personal assistant (calendar, reminders) | +Any connected channel can receive automation output through `--announce --channel --to `. Target formats differ per channel (a Telegram chat id, `channel:C123...` on Slack, an E.164 number on WhatsApp); `openclaw directory` looks them up. Setup is in [Channels & Integrations](/guides/channels). ### Developer tools and smart home {#developer-tools} From 0a36a2b563b4d538988582bffdbe2118125a8824 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:54:46 +0200 Subject: [PATCH 11/12] basic-usage: fix the setup description, cut flag and command tables duplicated from the CLI reference; triage is only non-interactive with --non-interactive --- docs/guides/basic-usage.md | 69 +++---------------------------- docs/reference/faq.md | 2 +- docs/reference/troubleshooting.md | 4 +- 3 files changed, 8 insertions(+), 67 deletions(-) diff --git a/docs/guides/basic-usage.md b/docs/guides/basic-usage.md index d1d3ebf..27b6073 100644 --- a/docs/guides/basic-usage.md +++ b/docs/guides/basic-usage.md @@ -9,7 +9,7 @@ keywords: [openclaw, openclaw usage, openclaw commands, how to use openclaw, ope # Basic Usage -This guide covers what you need day to day: how to talk to your agent, the slash commands, exec approvals, sessions, memory, skills and the config file. It assumes you have run `openclaw onboard` and the Gateway is running (`openclaw gateway status`). +This guide assumes you have run `openclaw onboard` and the Gateway is running (`openclaw gateway status`). --- @@ -20,7 +20,7 @@ There are four ways in. They all talk to the same Gateway and the same agent. | Where | Command | Good for | |-------|---------|----------| | Browser (Control UI) | `openclaw dashboard` | Chat, settings, editing workspace files, approving pairing requests | -| Terminal UI | `openclaw` or `openclaw tui` | Interactive chat in a terminal | +| Terminal UI | `openclaw tui` (bare `openclaw` opens it once setup is complete) | Interactive chat in a terminal | | One-shot CLI | `openclaw agent --agent main --message "..."` | Scripts, quick questions | | Chat apps | Telegram, Discord, Slack, WhatsApp… | Everyday use from your phone ([channels](/guides/channels)) | @@ -54,20 +54,7 @@ openclaw agent --agent main --message "List my five largest files" --json You must pass a session selector: `--agent`, `--session-key`, `--session-id` or `--to`. `--agent main` uses the main agent's main session, so the turn shares context with your TUI and Control UI conversation. -### Global flags - -These work on every command (`openclaw --help`): - -| Flag | Effect | -|------|--------| -| `--dev` | Dev profile: separate state under `~/.openclaw-dev`, Gateway port 19001 | -| `--profile ` | Separate state and config under `~/.openclaw-` (for example a work install) | -| `--container ` | Run the CLI inside an existing Podman/Docker container with that name | -| `--log-level ` | Log level override (`silent` … `trace`) | -| `--no-color` | Disable ANSI colors | -| `-V`, `--version` | Print the version | - -There is no global `--model` or `--format` flag. `--model` is an option of `openclaw agent`, and most commands take `--json` for machine-readable output. +Global flags such as `--profile`, `--dev` and `--log-level` go before the command; they are listed in the [CLI Reference](/reference/cli#global-flags). There is no global `--model` or `--format` flag: `--model` belongs to `openclaw agent`, and most commands take `--json`. --- @@ -76,7 +63,7 @@ There is no global `--model` or `--format` flag. `--model` is an option of `open | Command | Purpose | |---------|---------| | `openclaw onboard` | Guided setup: verifies model access, writes config, seeds the workspace, and offers channels and skills | -| `openclaw setup` | Same initialization; also recreates missing workspace files without overwriting existing ones | +| `openclaw setup` | Starts a chat, running onboarding first if setup is incomplete; `--baseline` only creates the config, workspace and session folders | | `openclaw configure` | Targeted wizard for one area later (models, channels, gateway…) | | `openclaw channels add` | Connect a chat channel | | `openclaw dashboard` | Open the Control UI | @@ -517,52 +504,6 @@ More starting points: [configuration examples](https://docs.openclaw.ai/gateway/ --- -## CLI Command Reference (Quick) - -The commands you'll use most. `openclaw --help` lists them all, and every command has `--help`. - -| Command | Purpose | -|---------|---------| -| `openclaw` / `openclaw tui` | Terminal chat | -| `openclaw dashboard` | Open the Control UI | -| `openclaw agent --agent --message "..."` | One-shot turn through the Gateway | -| `openclaw onboard` / `setup` / `configure` | Setup wizards | -| `openclaw status` | Overall health | -| `openclaw gateway start\|stop\|restart\|status` | Manage the Gateway service | -| `openclaw channels add\|list\|status\|login\|remove` | Manage chat channels | -| `openclaw pairing list\|approve` | Approve new DM senders | -| `openclaw sessions list\|tail` | Inspect sessions | -| `openclaw agents list\|add\|bindings` | Manage agents | -| `openclaw cron add\|list\|runs\|rm` | Automations (alias: `openclaw automations`) | -| `openclaw memory status\|search\|index\|forget` | Memory | -| `openclaw skills list\|search\|install\|verify\|update` | Skills | -| `openclaw approvals get` / `openclaw exec-policy show` | Exec approvals | -| `openclaw config get\|set\|patch\|validate` | Edit config | -| `openclaw models list` | Available models | -| `openclaw gateway usage-cost` | Cost summary | -| `openclaw logs --follow` | Gateway logs | -| `openclaw doctor` / `openclaw triage` | Diagnose problems | -| `openclaw update` | Update OpenClaw | - -See the [CLI Reference](/reference/cli) and the [upstream CLI docs](https://docs.openclaw.ai/cli). - ---- - -## Tips for Better Results - -| Tip | Example | -|-----|---------| -| Be specific about paths | "Edit `~/project/src/auth.ts`" not "edit the auth file" | -| State desired output | "Create a JSON config file" not just "set up config" | -| Provide constraints | "Use Python 3.12, no external dependencies" | -| Reference past context | "Like the script we made yesterday" | -| One-shot for simple tasks | `openclaw agent --agent main --message "What's my public IP?"` | -| Interactive for complex work | `openclaw tui`, then build up context | -| Pipe large inputs | `{ echo "Find errors:"; cat big.log; } \| openclaw agent --agent main --message-file /dev/stdin` | -| Use JSON for scripts | `openclaw agent --agent main --message "..." --json \| jq .` | - ---- - ## Troubleshooting | Problem | Solution | @@ -574,7 +515,7 @@ See the [CLI Reference](/reference/cli) and the [upstream CLI docs](https://docs | Agent won't run commands | `openclaw exec-policy show` and `openclaw approvals get` | | Memory search returns nothing | `openclaw memory status --deep`, then `openclaw memory index` | | Channel disconnected | `openclaw channels status --probe`; re-link with `openclaw channels login` or `openclaw gateway restart` | -| Not sure what's wrong | `openclaw triage` runs read-only checks and writes a sanitized diagnosis | +| Not sure what's wrong | `openclaw triage --non-interactive` writes a sanitized diagnosis without starting a repair agent; see [Troubleshooting](/reference/troubleshooting) | --- diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 7b6fa90..38ec30f 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -324,7 +324,7 @@ Yes. See [Contributing to OpenClaw](/contributing/openclaw) and [Contributing to ## Troubleshooting Quick Reference -Start with `openclaw status --all`, `openclaw doctor` and `openclaw logs --follow`, or `openclaw triage` for a sanitized diagnosis ([General troubleshooting](https://docs.openclaw.ai/help/troubleshooting)). +Start with `openclaw status --all`, `openclaw doctor` and `openclaw logs --follow`, or `openclaw triage --non-interactive` for a sanitized diagnosis ([General troubleshooting](https://docs.openclaw.ai/help/troubleshooting)). | Problem | Quick fix | |---------|-----------| diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index bd71b4c..ecd6791 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -29,7 +29,7 @@ Healthy output: `openclaw gateway status` shows `Runtime: running`, `Connectivit Plain `openclaw doctor` (without `--lint` or `--json`) is not read-only: it can copy legacy config and migrate state even without `--fix`. Take a backup before you run it on a broken install. -If you want one bundle to hand to a person or a coding agent, `openclaw triage` writes a sanitized diagnosis and, when the Gateway is reachable, a support archive. +If you want one bundle to hand to a person, `openclaw triage --non-interactive` writes a sanitized diagnosis and, when the Gateway is reachable, a support archive. Without `--non-interactive`, `triage` goes on to offer a local coding agent (Claude, Codex and others) to attempt repairs. --- @@ -576,7 +576,7 @@ If you really want a clean install, keep the backup and run `openclaw onboard` a ## Getting More Help ```bash -openclaw triage # sanitized, agent-ready diagnosis +openclaw triage --non-interactive # sanitized diagnosis, no repair agent openclaw gateway diagnostics export # payload-free .zip to attach openclaw status --all # pasteable text report ``` From 06933549f7e0fe84547f109cff83bf616c7d6596 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:55:29 +0200 Subject: [PATCH 12/12] channels: correct QQ Bot packaging, scope the sanitization and SecretRef claims to what upstream says --- docs/guides/channels.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/channels.md b/docs/guides/channels.md index c2c7247..75c396a 100644 --- a/docs/guides/channels.md +++ b/docs/guides/channels.md @@ -50,7 +50,7 @@ Upstream sorts channels into four groups: | **A2A**, **Reef** | `a2a`, `reef` | bundled | Agent-to-agent protocols | | **Buzz**, **ClickClack**, **Raft** | `buzz`, `clickclack`, `raft` | `@openclaw/` | See the upstream page for each | | **WeChat** | — | external: `@tencent-weixin/openclaw-weixin` | Tencent's plugin | -| **QQ Bot** | `qqbot` | external: `@tencent-connect/openclaw-qqbot` | Tencent's plugin | +| **QQ Bot** | `qqbot` | `@tencent-connect/openclaw-qqbot` (official, published by Tencent) | Older `@openclaw/qqbot` installs are rewritten on update | | **WeCom**, **Yuanbao**, **Zalo ClawBot** | — | external | See the upstream page for each | **Voice Call** (`@openclaw/voice-call`, telephony via Plivo, Telnyx or Twilio) is a communication plugin, not a chat channel: [docs.openclaw.ai/plugins/voice-call](https://docs.openclaw.ai/plugins/voice-call). @@ -471,7 +471,7 @@ OpenClaw sanitizes incoming channel content to make prompt injection harder: 2. **Wraps external content in boundary markers**: it is enclosed in `<<>>` with `Source: External` metadata. :::info -This closes tokenizer-level bypasses. It does not make untrusted messages safe to act on. See [Security Hardening](/security/hardening) for the rest of the defense stack. +Token stripping matters mainly for self-hosted backends (vLLM, LM Studio and similar) that would otherwise read those strings as real role boundaries. Neither step makes untrusted messages safe to act on. See [Security Hardening](/security/hardening) for the rest of the defense stack. ::: ### Credentials @@ -485,13 +485,13 @@ Channel tokens accept plain strings, `${ENV_VAR}` substitution, or a **SecretRef | Exec (password manager CLI) | `{ source: "exec", provider: "", id: "..." }`, same | | Secret Store | `{ source: "store", provider: "default", id: "..." }` | -Plaintext tokens in config or `.env` are readable by the agent itself. SecretRefs keep them out of reach. Telegram's `tokenFile` must be a regular file; symlinks are rejected. Reference: [Secrets](https://docs.openclaw.ai/gateway/secrets). +Plaintext tokens in `openclaw.json` or `.env` are readable by an agent that can read files. SecretRefs reduce that exposure once every credential is migrated; `openclaw secrets audit --check` reports any plaintext left. Telegram's `tokenFile` must be a regular file; symlinks are rejected. Reference: [Secrets](https://docs.openclaw.ai/gateway/secrets). ### Encryption comparison | Channel | Encryption | Metadata exposure | Self-hostable | |---------|-----------|-------------------|---------------| -| **Signal** | E2E | Minimal | No (you run `signal-cli`) | +| **Signal** | E2E | Minimal | No (Signal's servers; you run only the `signal-cli` client) | | **WhatsApp** | E2E | Meta collects metadata | No | | **Matrix** | Optional E2E | Depends on homeserver | Yes | | **Telegram** | TLS to Telegram servers (bots cannot use secret chats) | Moderate | Partial (Bot API server) |