From d6dad5752ca6adce72ea44c9b19f48827a69b307 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:57:51 +0200 Subject: [PATCH 1/5] Getting started: cut duplicated safety and cost material, fix small inaccuracies - introduction: heartbeat is on by default, not optional; replace the six-step safety list and cost table with links to the canonical checklist and cost pages - quick-start: openclaw chat "hi" fails rather than being read silently; collapse three link tables into one next-steps list - core-concepts: automations command is openclaw cron (automations alias); drop the duplicate SOUL.md example - installation: the Docker entrypoint runs doctor --fix on every start; shorten the onboarding section that repeated the Quick Start --- docs/getting-started/core-concepts.md | 19 ++--------- docs/getting-started/installation.md | 14 ++------- docs/getting-started/introduction.md | 39 ++++------------------- docs/getting-started/quick-start.md | 45 +++++---------------------- 4 files changed, 20 insertions(+), 97 deletions(-) diff --git a/docs/getting-started/core-concepts.md b/docs/getting-started/core-concepts.md index b4b2ed5..a023f28 100644 --- a/docs/getting-started/core-concepts.md +++ b/docs/getting-started/core-concepts.md @@ -9,7 +9,7 @@ keywords: [openclaw, openclaw architecture, how openclaw works, openclaw gateway # Core Concepts -Before going deeper, learn the handful of parts that make OpenClaw work. Upstream's own overview is [Architecture](https://docs.openclaw.ai/concepts/architecture). +The handful of parts that make OpenClaw work, each with a link to its deep dive. Upstream's own overview is [Architecture](https://docs.openclaw.ai/concepts/architecture). ## The Gateway @@ -97,7 +97,7 @@ The **heartbeat** makes OpenClaw proactive. It is a scheduled turn in the agent' - Configure it under `agents.defaults.heartbeat` (`every`, `activeHours`, `model`, `isolatedSession`, `lightContext`, `target`). - A short standing checklist lives in the heartbeat's monitor scratch (`openclaw cron scratch --set "..."`). -- Jobs on a fixed schedule ("daily at 9am", "every Monday") are **automations**: `openclaw automations create` (alias `openclaw cron`). They can run in an isolated session and deliver results to a channel. +- Jobs on a fixed schedule ("daily at 9am", "every Monday") are **automations**: `openclaw cron add` (`openclaw automations create` is the same command). They can run in an isolated session and deliver results to a channel. `HEARTBEAT.md` is retired: the runtime no longer reads it, and `openclaw doctor --fix` migrates an old one. See [Heartbeat](/architecture/heartbeat) and the official [heartbeat docs](https://docs.openclaw.ai/gateway/heartbeat). @@ -121,20 +121,7 @@ graph TD ## SOUL.md (persona) -`SOUL.md` in the workspace defines *who* the agent is: name, personality, tone, rules and boundaries. - -```markdown title="~/.openclaw/workspace/SOUL.md" -# Agent Identity - -You are Jarvis, a helpful personal assistant. - -## Rules -- Always respond politely -- Never make purchases without explicit approval -- Summarize long emails instead of forwarding them in full -``` - -It is loaded into every session. Operating rules ("how to work") belong in `AGENTS.md`; persona ("who to be") in `SOUL.md`. Because the agent can write to its own workspace, these files are also an [attack surface](/security/hardening#soulmd-protection) for prompt injection. See the [SOUL.md Guide](/guides/soul-md). +`SOUL.md` in the workspace defines *who* the agent is: personality, tone and boundaries. It is loaded into every session; the [Quick Start](/getting-started/quick-start#step-6-personalize-your-agent-optional) has a starter file. A rule written there ("never make purchases without approval") is an instruction the model usually follows, not an enforced control; approvals and tool policy enforce. Operating rules ("how to work") belong in `AGENTS.md`; persona ("who to be") in `SOUL.md`. Because the agent can write to its own workspace, these files are also an [attack surface](/security/hardening#soulmd-protection) for prompt injection. See the [SOUL.md Guide](/guides/soul-md). ## Skills diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 11b19ec..f8019bf 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -98,7 +98,7 @@ If you write your own `docker run` or Compose file, get these right: - **Health checks:** the image's built-in `HEALTHCHECK` uses `/healthz`. `/readyz` is the deeper, channel-aware probe. - Use only `ghcr.io/openclaw/openclaw` or the Docker Hub mirror `openclaw/openclaw`. -On upgrade, the container entrypoint runs `openclaw doctor --fix` against the mounted state before the Gateway starts. Podman, Nix, Kubernetes, Ansible and cloud recipes are listed on the [install index](https://docs.openclaw.ai/install); see also [Deployment Options](/guides/deployment-options). +The container entrypoint runs `openclaw doctor --fix --non-interactive` against the mounted state each time the Gateway container starts, so an image upgrade migrates state before the Gateway runs. Podman, Nix, Kubernetes, Ansible and cloud recipes are listed on the [install index](https://docs.openclaw.ai/install); see also [Deployment Options](/guides/deployment-options). ## Method 5: From source (developers) @@ -125,17 +125,9 @@ The installer script starts onboarding for you. Otherwise run: openclaw onboard --install-daemon ``` -Onboarding: +Onboarding checks your model access with a real request, creates the workspace (`~/.openclaw/workspace`) and `~/.openclaw/openclaw.json` with a generated Gateway token, and with `--install-daemon` installs the Gateway as a service (LaunchAgent on macOS, systemd user service on Linux and WSL2, Scheduled Task on Windows). The [Quick Start](/getting-started/quick-start#step-2-onboard) walks through it. Without `--install-daemon`, install the service later with `openclaw gateway install`. -1. **Sets up model access.** It detects a Claude Code or Codex login or an API key and verifies it with a real request, or walks you through provider setup. -2. **Creates the workspace** at `~/.openclaw/workspace` and writes `~/.openclaw/openclaw.json`, including a generated Gateway token. -3. **Installs the Gateway service** (with `--install-daemon`): a LaunchAgent on macOS, a systemd user service on Linux and WSL2, or a Scheduled Task on Windows. - -Channels can be added later with `openclaw channels add`. To change things afterwards, use `openclaw configure`. Onboarding reference: [Onboarding (CLI)](https://docs.openclaw.ai/start/wizard). - -:::tip -Without `--install-daemon`, onboarding can leave the Gateway running in the foreground of that terminal. Install the background service any time with `openclaw gateway install`. -::: +Change settings afterwards with `openclaw configure`; add channels with `openclaw channels add`. Reference: [Onboarding (CLI)](https://docs.openclaw.ai/start/wizard). ## Verify installation diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index 2290ee8..a58978b 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -26,7 +26,7 @@ This site is a community companion to the official docs at [docs.openclaw.ai](ht | What it can touch | Text in, text out | Shell, files, browser, APIs, paired devices | | Memory | Per-session, or vendor-held | Markdown files in your workspace (`~/.openclaw/workspace`) | | How you reach it | One web app | Control UI, terminal UI, desktop and mobile apps, 20+ chat channels | -| Proactivity | Waits for you | Optional [heartbeat](/architecture/heartbeat) and scheduled automations | +| Proactivity | Waits for you | A [heartbeat](/architecture/heartbeat) (on by default) and scheduled automations | | Models | One vendor | Any supported provider, or local models | "Runs locally" does not mean "nothing leaves your machine". Your prompts, memory snippets and tool output go to the model provider you configure, and memory search uses OpenAI embeddings by default. See [Privacy and compliance](/guides/privacy-compliance). @@ -96,9 +96,7 @@ As of 2026-10-18, [openclaw/openclaw](https://github.com/openclaw/openclaw) has - **Not just a CLI.** It ships a full web Control UI (open it with `openclaw dashboard`) and desktop and mobile apps. Use the Control UI rather than a third-party web client: [WebClaw](/guides/webclaw) only speaks Gateway protocol v3, and current Gateways require v4 from operator and UI clients ([protocol versioning](https://docs.openclaw.ai/gateway/protocol/versioning)), so it cannot connect. - **Not a coding IDE.** It can write and edit code, but it is a general-purpose agent, not a replacement for your editor. - **Not free to run.** OpenClaw is free; model API calls are not. Local models cost nothing per token but need capable hardware. -- **Not safe by default.** It runs with your user's permissions, shell commands run without approval by default, and the sandbox is off. Read the [Security Overview](/security/overview) before connecting it to anything important. - **Not a hosted service.** You run it yourself. Third parties sell managed hosting; see [Hosting Providers](/guides/hosting-providers). -- **Not multi-tenant.** Upstream's trust model is one trusted operator per Gateway. Give mutually untrusted people separate Gateways. --- @@ -114,16 +112,7 @@ OpenClaw gives a language model real access to your machine. Know these facts be | **Many advisories** | As of 2026-10-18 GitHub lists 722 security advisories for openclaw/openclaw (14 critical, 249 high). Stay on a current release. | | **Skills are code** | Malicious skills have been published to ClawHub. Review before installing. | -### How to stay safe - -1. **Update often:** `openclaw update`. -2. **Keep the Gateway on loopback** (`gateway.bind: "loopback"`, the default). For remote access use SSH tunnels or Tailscale, not a public port. -3. **Keep token auth on** (`gateway.auth.mode: "token"`). -4. **Turn on exec approvals:** `openclaw config set tools.exec.mode ask`. -5. **Consider the sandbox** for anything that reads untrusted input: `agents.defaults.sandbox.mode: "non-main"` or `"all"` (needs Docker or another backend). Note that the global `--container` flag only runs the CLI inside an existing container; it is not a sandbox. -6. **Audit your setup:** `openclaw security audit --deep`. - -See [Security Overview](/security/overview) and the [Hardening Guide](/security/hardening). +Keep the Gateway on loopback, turn on approvals and run `openclaw security audit --deep`. The twelve-item list is the [secure-by-default checklist](/getting-started/choosing-your-setup#checklist); the reasoning is in [Security Hardening](/security/hardening). :::warning Do not run OpenClaw as root. Do not expose port 18789 to the internet. Do not install skills you have not read. @@ -133,19 +122,7 @@ Do not run OpenClaw as root. Do not expose port 18789 to the internet. Do not in ## The cost question -OpenClaw itself is free. Your bill comes from model tokens, and it depends almost entirely on which model you use and how much the agent runs unattended. Check your provider's current price list rather than trusting a table on a community site. - -The main levers, all real config keys: - -| Lever | How | -|---|---| -| Cheaper model for the heartbeat | `agents.defaults.heartbeat.model`, e.g. `anthropic/claude-haiku-5-5` | -| Less frequent heartbeat | `agents.defaults.heartbeat.every: "1h"` (or `"0m"` to turn the recurring heartbeat off) | -| Only during waking hours | `agents.defaults.heartbeat.activeHours: { start: "08:00", end: "22:00" }` | -| Smaller heartbeat context | `agents.defaults.heartbeat.isolatedSession: true` and `lightContext: true` | -| Local models | Ollama, LM Studio or vLLM; see [Local Models](/guides/local-models) | - -See [Cost Management](/guides/cost-management) and the official [heartbeat docs](https://docs.openclaw.ai/gateway/heartbeat). +OpenClaw itself is free. Your bill comes from model tokens, and it depends almost entirely on which model you use and how much the agent runs unattended, including the heartbeat. As a rough scale (as of 2026-10-18, 600 requests a month), Haiku 5.5 costs about $2 a month and Opus 5.5 about $72; local models cost nothing per token. The worked numbers and configs are in [Choosing Your Setup](/getting-started/choosing-your-setup#models), the levers in [Cost Management](/guides/cost-management). --- @@ -181,10 +158,6 @@ For **local models**, the GPU matters far more than the Gateway. See [Local Mode ## Next steps -| Step | Link | -|---|---| -| Install OpenClaw | [Installation](/getting-started/installation) | -| Get your first chat working | [Quick Start](/getting-started/quick-start) | -| Understand the moving parts | [Core Concepts](/getting-started/core-concepts) | -| Structured learning path | [First 7 Days](/guides/first-7-days) | -| Lock down security | [Security Hardening](/security/hardening) | +1. [Choosing Your Setup](/getting-started/choosing-your-setup): pick a model, a channel and a host. +2. [Installation](/getting-started/installation), then the [Quick Start](/getting-started/quick-start). +3. [Core Concepts](/getting-started/core-concepts), or the [First 7 Days](/guides/first-7-days) path. diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index f7e758f..3513904 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -13,11 +13,9 @@ keywords: [openclaw, openclaw getting started, openclaw tutorial, openclaw quick # Quick Start -Get from zero to a working OpenClaw agent in about 5 minutes. The official version of this walkthrough is [Getting started](https://docs.openclaw.ai/start/getting-started). +From zero to a working agent in about 5 minutes. The official version is [Getting started](https://docs.openclaw.ai/start/getting-started). Not sure which model, channel or host to pick? [Choosing Your Setup](/getting-started/choosing-your-setup) recommends one for each. -Not sure which model, channel or host to pick? [Choosing Your Setup](/getting-started/choosing-your-setup) recommends one for each. - -**What you'll have at the end:** a Gateway running as a background service, the Control UI open in your browser, and an agent that can answer questions, read and write files, and run shell commands. Optionally, a chat app on your phone connected to it. +**At the end you have** a Gateway running as a background service, the Control UI open in your browser, and an agent that can answer questions, read and write files, and run shell commands. Optionally, a chat app on your phone connected to it. **Prerequisites:** - Node.js 24.16+ or 26.1+ (26 recommended; 22, 23 and 25 are unsupported). Check with `node --version`. The installer script installs Node for you if needed. @@ -107,7 +105,7 @@ openclaw tui openclaw agent --agent main --message "What files are in my home directory?" ``` -`openclaw chat` is a shortcut for `openclaw tui --local`: it runs the agent in-process instead of through the Gateway. To start it with a first message use `openclaw chat --message "..."`. A bare positional argument (`openclaw chat "hi"`) is read as a session target, not a message. +`openclaw chat` is a shortcut for `openclaw tui --local`: it runs the agent in-process instead of through the Gateway. To start it with a first message use `openclaw chat --message "..."`. `openclaw chat "hi"` fails: a positional argument is a session target, not a message, and local mode rejects targets. ## Step 5: Try some real tasks @@ -264,35 +262,8 @@ If a step fails, `openclaw triage` collects sanitized diagnostics and can hand t ## What's next? -### Do these first - -| Goal | Guide | -|---|---| -| Learn everyday commands | [Basic Usage](/guides/basic-usage) | -| Lock down security | [Security Hardening](/security/hardening) | -| Understand the moving parts | [Core Concepts](/getting-started/core-concepts) | - -### First week - -| Goal | Guide | -|---|---| -| Structured learning path | [First 7 Days](/guides/first-7-days) | -| Customize your agent's personality | [SOUL.md Guide](/guides/soul-md) | -| Connect messaging channels | [Channels Guide](/guides/channels) | -| Set up scheduled tasks | [Automation](/guides/automation) | - -### Going deeper - -| Goal | Guide | -|---|---| -| Choose the right model for each task | [Model Selection](/guides/model-selection) | -| Run without API costs | [Local Models](/guides/local-models) | -| Find community skills | [ClawHub](/guides/clawhub) | -| Build your own skills | [Skill Development](/guides/skill-development) | -| Run multi-agent workflows | [Multi-Agent](/guides/multi-agent) | -| Keep costs down | [Cost Management](/guides/cost-management) | -| Build integrations | [API & Webhooks](/guides/api-webhooks) | - -:::tip -Ask questions in the official [OpenClaw Discord](https://discord.gg/clawd), or on [r/OpenClaw](https://reddit.com/r/OpenClaw). -::: +1. Lock it down before you connect channels other people can reach: [Security Hardening](/security/hardening), or the short [secure-by-default checklist](/getting-started/choosing-your-setup#checklist). +2. Learn the everyday commands: [Basic Usage](/guides/basic-usage). +3. Follow the [First 7 Days](/guides/first-7-days) path: persona, daily use, automations, skills, channels, multi-agent and production. + +Questions go to the official [OpenClaw Discord](https://discord.gg/clawd). From 3ee37b4c43f9fef7b90af146920f7af7ebe72a92 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:57:51 +0200 Subject: [PATCH 2/5] Architecture and contributing: trim duplication, fix test guidance - brain-and-hands: drop an unrelated advisory note and the bootstrap limits repeated from the overview; shorten the naming note - contributing/openclaw: CONTRIBUTING.md asks for build, check and test before review, not focused tests only --- docs/architecture/brain-and-hands.md | 12 +++--------- docs/contributing/openclaw.md | 2 +- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/architecture/brain-and-hands.md b/docs/architecture/brain-and-hands.md index c601207..42ec2a7 100644 --- a/docs/architecture/brain-and-hands.md +++ b/docs/architecture/brain-and-hands.md @@ -10,8 +10,8 @@ keywords: [openclaw, agent loop, agent runtime, llm integration, tools, exec app # Agent Runtime and Tools -:::note About the name -Earlier versions of this page called the model the "Brain" and the tools the "Hands". That is this site's analogy, not an OpenClaw concept, and there is no `brain` or `hands` config key. OpenClaw's own terms are the **agent loop** (runtime), **models**, **tools**, **exec approvals**, the **sandbox**, and **nodes**. This page uses those terms. +:::note +"Brain and hands" was this site's old analogy for models and tools. There is no `brain` or `hands` config key; this page uses OpenClaw's own terms. ::: In one sentence: the agent loop sends the assembled prompt to a model, the model answers with text and/or tool calls, OpenClaw runs the tools (subject to tool policy, approvals and the sandbox), and feeds the results back until the model gives a final reply. @@ -35,9 +35,7 @@ Tool calls use the provider's native tool-use format. OpenClaw does not have its From the CLI, `openclaw agent --message "..."` runs one turn through the Gateway, and `openclaw chat` opens the local terminal UI. -### Bootstrap context - -Large bootstrap files are truncated when injected: `agents.defaults.bootstrapMaxChars` (default 20000 per file) and `bootstrapTotalMaxChars` (default 60000). Related keys: `skipBootstrap` (do not create the files) and `skipOptionalBootstrapFiles`. For cheap scheduled turns, `agents.defaults.heartbeat.lightContext` and `isolatedSession` reduce what a heartbeat loads. See [Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace). +What goes into the prompt, and the bootstrap size limits, are on [Architecture Overview](/architecture/overview#what-goes-into-the-prompt). --- @@ -223,10 +221,6 @@ Check what applies to a session with `openclaw sandbox explain`. See [Sandboxing With the defaults (`tools.exec.mode: "full"`, sandbox `off`), anyone who can message the agent can get commands run on your host. Before you connect channels, set `tools.exec.mode` to `ask` or `allowlist`, restrict who can DM the bot, and consider `sandbox.mode: "non-main"`. See [Security Hardening](/security/hardening). ::: -### Advisory note - -GHSA-9p3r-hh9g-5cmg (critical) was a TOCTOU race in the remote filesystem bridge `readFile`. It affected versions up to 2026.3.28 and was fixed in 2026.3.31; GitHub credits AntAISecurityLab. Stay on a current release; see [Known Vulnerabilities](/security/known-vulnerabilities). - --- ## Nodes diff --git a/docs/contributing/openclaw.md b/docs/contributing/openclaw.md index b02d6dc..aef9cb3 100644 --- a/docs/contributing/openclaw.md +++ b/docs/contributing/openclaw.md @@ -36,7 +36,7 @@ pnpm build pnpm dev ``` -Run focused tests for what you touched rather than the whole suite: `pnpm test --maxWorkers=1`, plus `pnpm test:extension ` for a plugin. PR CI runs the full suite. +CONTRIBUTING.md asks for `pnpm build && pnpm check && pnpm test` before review. For a plugin change, start with the fast lane, `pnpm test:extension `. If you add or change tests, the repo's `AGENTS.md` asks the PR to state the wall time of `pnpm test --maxWorkers=1`. ## Pull requests From 8296a4b636c348fdde6c619df50ddb8e2cb45e79 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:57:51 +0200 Subject: [PATCH 3/5] Security: one canonical checklist, fix clawhub uninstall, trim repeats - overview: replace the third checklist, the unreviewed tools table and the dated Gartner quote with links to their canonical pages - hardening: clawhub uninstall needs --workdir; link the overview's baseline instead of repeating it; split the redaction paragraph - skill-verification: drop the study table duplicated from Known Vulnerabilities --- docs/security/hardening.md | 20 ++++------------ docs/security/overview.md | 37 ++++------------------------- docs/security/skill-verification.md | 18 +------------- 3 files changed, 10 insertions(+), 65 deletions(-) diff --git a/docs/security/hardening.md b/docs/security/hardening.md index 9778102..59f3c4c 100644 --- a/docs/security/hardening.md +++ b/docs/security/hardening.md @@ -59,7 +59,6 @@ openclaw skills update --all - Docker: pin an exact image tag such as `ghcr.io/openclaw/openclaw:2026.10.4` if you want reproducible deploys, but bump it on every release. Use only `ghcr.io/openclaw/openclaw` or `openclaw/openclaw` images ([Docker install](https://docs.openclaw.ai/install/docker)). - The `extended-stable` channel trails stable by about a month and never auto-applies ([release channels](https://docs.openclaw.ai/install/development-channels)). If you use it, check each new advisory's patched versions against what you run. - Watch the repository for security alerts: on GitHub, **Watch → Custom → Security alerts** on [openclaw/openclaw](https://github.com/openclaw/openclaw/security/advisories). - - Background auto-update for stable package installs is opt-in: `update.auto.enabled: true` (default `false`; [updating](https://docs.openclaw.ai/install/updating)). ## Keep the Gateway on loopback {#bind} @@ -400,18 +399,7 @@ The effective policy is the **stricter** of `tools.exec.*` in `openclaw.json` an - `tools.fs.workspaceOnly` keeps file tools inside the workspace. Exec can still reach the rest of the filesystem, which is why the sandbox matters. - `sessions.visibility` and `agentToAgent` default to Gateway-wide reach. Narrow them when agents have different trust levels. -For an agent that only chats and should never touch the host, upstream's 60-second baseline denies whole tool groups: - -```json5 title="~/.openclaw/openclaw.json" -{ - tools: { - profile: "messaging", - deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"], - exec: { mode: "deny" }, - elevated: { enabled: false }, - }, -} -``` +For an agent that only chats and should never touch the host, start from upstream's 60-second baseline, which denies the runtime, file and automation tool groups: it is reproduced on [Security Overview](/security/overview#2-start-from-a-hardened-baseline). Allowlists and approvals are guardrails for operator intent, not a sandbox. Upstream says they don't model every interpreter path. Text blocklists such as "block `rm -rf`" are not a security boundary either ([SECURITY.md](https://github.com/openclaw/openclaw/blob/main/SECURITY.md)). Pair them with the sandbox for anything that reads untrusted input. @@ -503,7 +491,9 @@ openclaw secrets audit --check # non-zero exit while plaintext or unresolved openclaw secrets configure # interactive migration helper ``` -Give the agent its own scoped, short-lived credentials: a read-only GitHub token, a separate email account, a bot number. Don't hand it your personal ones. In v2026.10.4, sensitive-value redaction is always on and masks matching secrets before file-log lines and transcript text are written. It is best-effort pattern matching, so `logging.redactPatterns` for your own token formats is worth adding (it replaces the default string list; built-in structural protections still apply). Share `openclaw status --all` (redacted) rather than raw logs. This masking also covers tool payloads before they reach the model. +Give the agent its own scoped, short-lived credentials: a read-only GitHub token, a separate email account, a bot number. Don't hand it your personal ones. + +In v2026.10.4, sensitive-value redaction is always on. It masks matching secrets in tool payloads before they reach the model, and before file-log lines and transcript text are written. It is best-effort pattern matching, so add `logging.redactPatterns` for your own token formats (it replaces the default string list; built-in structural protections still apply). Share `openclaw status --all` (redacted) rather than raw logs. :::warning Changing in 2026.10.10 (beta) 2026.10.10-beta.1 (npm `beta`, 2026-10-15; not in 2026.10.4) removes automatic secret masking of tool payloads. Tool arguments, tool results and `.env` reads keep their original text, credentials included, in model context, transcripts, session history and UI tool events. Log tails, console output, support bundles and telemetry export stay masked; the log files themselves are written raw with `0600` permissions. Before upgrading, assume anything a tool reads will reach your provider and the session store: keep secrets in SecretRefs rather than in files the agent can read, and protect `~/.openclaw` and the log directory like a credentials store ([PR #169063](https://github.com/openclaw/openclaw/pull/169063)). @@ -623,7 +613,7 @@ openclaw devices remove - `openclaw logs` and `openclaw audit` for the time window. - The transcripts of the affected sessions. - Config changes that widened access: `gateway.bind`, `gateway.auth`, DM and group policies, `tools.elevated`, `tools.exec.mode`, plugins. -- Recently installed skills and plugins. Remove ClawHub skills with `clawhub uninstall @owner/` (`npm i -g clawhub` first). Remove plugins with `openclaw plugins uninstall `. +- Recently installed skills and plugins. Remove ClawHub skills with `clawhub --workdir uninstall @owner/` (`npm i -g clawhub` first; see [Skill Verification](/security/skill-verification#post-incident-if-you-installed-a-malicious-skill)). Remove plugins with `openclaw plugins uninstall `. - Workspace files (`SOUL.md`, `AGENTS.md`, `MEMORY.md`) and scheduled jobs (`openclaw cron list`) for persistence. - To drop the derived memory index without deleting sessions: `openclaw memory reset --agent --yes`. diff --git a/docs/security/overview.md b/docs/security/overview.md index 07bce53..98996c1 100644 --- a/docs/security/overview.md +++ b/docs/security/overview.md @@ -9,7 +9,7 @@ keywords: [openclaw, openclaw security, threat model, attack surface, is opencla # Security Overview -OpenClaw gives an AI agent real access to your machine and your accounts. This page covers what is safe by default, what isn't, and a baseline config to start from. It was checked against OpenClaw v2026.10.4 on 2026-10-18. For the full checklist, see [Security Hardening](/security/hardening). +OpenClaw gives an AI agent real access to your machine and your accounts. This page covers what is safe by default, what isn't, and a baseline config to start from; [Security Hardening](/security/hardening) has the full checklist. Checked against v2026.10.4 on 2026-10-18. --- @@ -153,44 +153,15 @@ Every step used intended capabilities. The defences that would have stopped it a ## Checklist -- [ ] **Run the latest stable release** (v2026.10.4 as of 2026-10-18) and `openclaw plugins update --all` -- [ ] **Keep `gateway.bind: "loopback"`**; in Docker, publish to `127.0.0.1` only -- [ ] **Use a token of at least 24 characters**, ideally 64 hex -- [ ] **Remote access via SSH tunnel, Tailscale Serve or Cloudflare Access**, never an open port -- [ ] **Set `gateway.trustedProxies`** if any reverse proxy is in front -- [ ] **Keep DM pairing or allowlists**; mention-gate groups; set `session.dmScope: "per-channel-peer"` if more than one person DMs the bot -- [ ] **Turn on exec approvals** (`tools.exec.mode: "ask"` or `"auto"`) and **the sandbox** (`agents.defaults.sandbox.mode: "non-main"`) -- [ ] **Review skills and plugins**: `openclaw skills list`, `openclaw skills verify @owner/`, `openclaw plugins list` -- [ ] **Move secrets to SecretRefs** and run `openclaw secrets audit --check` -- [ ] **Limit when heartbeats run** with `agents.defaults.heartbeat.activeHours` -- [ ] **Review memory**: `~/.openclaw/workspace/MEMORY.md` and `memory/*.md` -- [ ] **Watch workspace files** (`SOUL.md`, `AGENTS.md`) for changes you didn't make -- [ ] **Run `openclaw security audit --deep`** after every change +The canonical checklist, with a config and a reason for every item, is [Security Hardening](/security/hardening#the-checklist). For a twelve-line version to tick off before connecting a channel, see [Choosing Your Setup](/getting-started/choosing-your-setup#checklist). --- ## Community security tools -Third-party projects, listed for reference. **clawdocs has not reviewed their code.** A security tool runs with the same access as the agent, so vet it like any other skill or plugin. +Third-party scanners and monitors are listed, unreviewed, on [Ecosystem](/reference/ecosystem#security-tools) and in [Skill Verification](/security/skill-verification#third-party-scanning-tools). A security tool runs with the same access as the agent, so vet it like any other skill or plugin. -| Tool | Description | -|------|-------------| -| [**ClawSec**](https://github.com/prompt-security/clawsec) | Skill suite: SOUL.md drift detection, advisory monitoring, audit watchdog | -| [**ClawBands**](https://github.com/SeyZ/clawbands) | Middleware that asks for human approval before dangerous actions | -| [**Security Monitor**](https://github.com/adibirzu/openclaw-security-monitor) | Monitoring scripts targeting known threat campaigns | -| [**openclaw-secure**](https://github.com/seomikewaltman/openclaw-secure) | Hardware-gated secret management with pluggable backends | -| [**Clawdex**](https://koisecurity.com/clawdex) | Koi Security's lookup of skills against its malicious-skills database | -| [**Cisco Skill Scanner**](https://github.com/cisco-ai-defense/skill-scanner) | Static, dataflow and LLM-based scanning of agent skills | - -See the [Ecosystem page](/reference/ecosystem#security-tools) for more. - ---- - -## Enterprise assessment - -> *"It is not enterprise software. There is no promise of quality, no vendor support, no SLA... it ships without authentication enforced by default."* — Gartner, February 2026 - -The authentication part of that quote is out of date: current releases require Gateway auth by default and fail closed ([network exposure](https://docs.openclaw.ai/gateway/security/network-exposure)). The rest still describes an open-source project without a vendor. For compliance questions, see [Privacy & Compliance](/guides/privacy-compliance). +For compliance questions (GDPR, SOC 2, HIPAA, analyst assessments), see [Privacy & Compliance](/guides/privacy-compliance). --- diff --git a/docs/security/skill-verification.md b/docs/security/skill-verification.md index 575282a..305d919 100644 --- a/docs/security/skill-verification.md +++ b/docs/security/skill-verification.md @@ -11,28 +11,12 @@ keywords: [openclaw, openclaw skill security, clawhub security, malicious skills Skills are instructions, and often scripts, that your agent follows with its own tools. Upstream's guidance is to treat third-party skills as **untrusted code** and read them before enabling them ([skills: security](https://docs.openclaw.ai/tools/skills)). The commands below were checked against OpenClaw v2026.10.4 on 2026-10-18. -Why it matters: in February 2026, researchers found **341 malicious skills** on ClawHub, **283 skills leaking credentials**, and security flaws in **36%** of the skills sampled (details on [Known Vulnerabilities](/security/known-vulnerabilities#malicious-clawhub-skills-february-2026)). Snyk called this "the first documented supply-chain attack specifically targeting AI agent skills." - -:::danger Supply chain risk -Snyk's ToxicSkills study found that **91% of malicious skills** combined prompt injection with traditional malware. A skill doesn't need to contain malicious code. It can simply tell the agent to do something harmful. -::: +Why it matters: in February 2026, researchers found 341 malicious skills on ClawHub, and Snyk found security flaws in 36% of the 3,984 skills it sampled. The studies, and what ClawHub changed afterwards, are on [Known Vulnerabilities](/security/known-vulnerabilities#malicious-clawhub-skills-february-2026). These are early-2026 figures; ClawHub's scanning has changed since (see [ClawHub scanning](#virustotal-integration-v202626)). --- ## The Threat Landscape -### What was found on ClawHub (February 2026) - -| Study | Skills analysed | Malicious / flawed | Key finding | -|-------|----------------|-------------------|-------------| -| **Koi Security** | 2,857 | 341 malicious (12%) | ClawHavoc campaign: 335 skills distributing AMOS malware | -| **Snyk ToxicSkills** | 3,984 | 1,467 flawed (36%), 534 critical (13.4%), 76 confirmed malicious | Hybrid prompt-injection and malware attacks | -| **Snyk credential leaks** | 3,984 | 283 leaking credentials (7.1%) | Popular skills push API keys through the model context | -| **Bitdefender** | not stated | ~900 malicious (~20%, Bitdefender's estimate) | Highest published estimate | -| **Cisco AI Defense** | The top-ranked skill | 9 vulnerabilities (2 critical) | Data exfiltration and prompt injection without user awareness | - -These are third-party figures from early 2026. ClawHub's scanning and moderation have changed since then (see [ClawHub scanning](#virustotal-integration-v202626)). - ### How malicious skills work **Traditional malware (ClawHavoc):** From fae1399e0b32a5bd7c9a50ed6d4873fa73348349 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:57:51 +0200 Subject: [PATCH 4/5] First 7 days: fix automation delivery, fresh-session and uninstall steps - day 1: openclaw agent reuses the main session; use --session-key for a fresh one - day 2: move the no-approval warning above the file prompts; stop suggesting a hand-rolled ~/.openclaw backup; cut repeated prompts - day 3: CLI jobs default to --channel last, they do not require a route; chat-created jobs run in the creating conversation; command jobs bypass exec approvals but need operator.admin - day 4: clawhub uninstall with --workdir; add time estimate - day 6: positional schedules accept intervals; replace the exec disk check with a pointer to command jobs; explain automation approvals - day 7: self-check job needs --tools exec and a standing grant under ask - index: Telegram is a bundled plugin; cut filler --- .../first-7-days/day-1-make-it-yours.md | 10 +-- .../guides/first-7-days/day-2-daily-driver.md | 65 +++++-------------- docs/guides/first-7-days/day-3-automation.md | 8 +-- docs/guides/first-7-days/day-4-skills.md | 6 +- .../first-7-days/day-5-multi-channel.md | 2 +- docs/guides/first-7-days/day-6-power-moves.md | 14 ++-- docs/guides/first-7-days/day-7-production.md | 8 +-- docs/guides/first-7-days/index.md | 8 +-- 8 files changed, 43 insertions(+), 78 deletions(-) diff --git a/docs/guides/first-7-days/day-1-make-it-yours.md b/docs/guides/first-7-days/day-1-make-it-yours.md index 8589ad9..c3a47b6 100644 --- a/docs/guides/first-7-days/day-1-make-it-yours.md +++ b/docs/guides/first-7-days/day-1-make-it-yours.md @@ -39,7 +39,7 @@ openclaw agent --agent main --message "Who are you?" `openclaw tui` also accepts `--message "Who are you?"` to send an opening message. Running `openclaw` with no arguments opens the TUI too. If you connected Telegram during setup, you can message your bot there as well. :::note Old tutorials -Some older guides show `openclaw chat "Who are you?"`. That does not work: `openclaw chat` is an alias for `openclaw tui --local` and takes no message argument. Use `openclaw agent --message` for one-shot messages. +Some older guides show `openclaw chat "Who are you?"`. That fails: `openclaw chat` is `openclaw tui --local`, and a positional argument is a session target, not a message. Use `openclaw agent --message` for one-shot messages, or `openclaw chat --message "..."` to open the local TUI with a first message. ::: --- @@ -97,10 +97,10 @@ Software development, system administration, research, writing. I learn the user's stack and preferences over time. ``` -Start a fresh session so the new file is loaded (type `/new` in the chat, or run): +Start a fresh session so the new file is loaded: type `/new` in the chat and ask "Who are you?". From the shell, `openclaw agent` reuses the main session, so give it a new session key instead: ```bash -openclaw agent --agent main --message "Who are you?" +openclaw agent --agent main --session-key soul-test --message "Who are you?" ``` For deeper customization, see the [SOUL.md Guide](/guides/soul-md) and upstream's [SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul). @@ -218,10 +218,10 @@ That last one is especially useful — the answer depends on your tool policy an The model only remembers what is written to disk ([memory](https://docs.openclaw.ai/concepts/memory)). `USER.md` and `MEMORY.md` load at the start of each session; daily notes in `memory/` are searched on demand. -Start a new session (`/new` in chat) and ask: +Start a new session (`/new` in chat) and ask "What do you know about me?", or from the shell: ```bash -openclaw agent --agent main --message "What do you know about me?" +openclaw agent --agent main --session-key memory-test --message "What do you know about me?" ``` The bot should reference your `USER.md` directives and anything it saved during your conversation. diff --git a/docs/guides/first-7-days/day-2-daily-driver.md b/docs/guides/first-7-days/day-2-daily-driver.md index a07ec95..f63f35f 100644 --- a/docs/guides/first-7-days/day-2-daily-driver.md +++ b/docs/guides/first-7-days/day-2-daily-driver.md @@ -9,7 +9,7 @@ keywords: [openclaw, daily use, everyday tasks, productivity, chat commands, sum # Day 2: Your Daily Driver -Yesterday you gave your bot a personality. Today you put it to work on the things you actually do every day — summarizing content, researching topics, managing files, writing scripts, and keeping your system healthy. +Today you put the bot to work: summaries, research, file management, quick scripts and system checks. **Time:** ~30 minutes @@ -59,7 +59,6 @@ For long content, tell the bot what you care about: "Summarize this, focusing on ## Research Assistant -The bot can research topics, compare options, and find documentation — saving you the tab-switching and skimming. ``` What are the main differences between SQLite, PostgreSQL, and MySQL for a small self-hosted app? @@ -85,7 +84,20 @@ Web search needs a search provider. OpenClaw auto-detects one from the credentia ## File Management -One of OpenClaw's strongest practical uses: managing files without memorizing find/xargs/sed incantations. +Managing files without memorizing find/xargs/sed incantations. These prompts move and rename real files, so read this first: + +:::warning The bot does not ask first by default +By default OpenClaw runs commands **without asking**, including destructive ones (deleting, moving, overwriting): `tools.exec.mode` defaults to `full` and the sandbox is off. Asking it to "show me the plan first" is a request the model may or may not honour, not a safety control. + +For a real confirmation step, turn on approvals and check the result: + +```bash +openclaw config set tools.exec.mode ask +openclaw exec-policy show +``` + +In `ask` mode, allowlisted commands run and everything else waits for you to approve it in the chat or Control UI. `openclaw approvals get` shows the requested policy, the host approvals file and the effective result. See [permission modes](https://docs.openclaw.ai/tools/permission-modes) and the [hardening checklist](/security/hardening#exec-approvals). +::: ### Organize files @@ -111,19 +123,6 @@ Rename all files in ~/screenshots to the format YYYY-MM-DD_HH-MM-SS.png based on Create a project structure for a Python CLI tool called "timetrack" with src, tests, docs, and config directories, including __init__.py files and a pyproject.toml ``` -:::warning The bot does not ask first by default -By default OpenClaw runs commands **without asking**, including destructive ones (deleting, moving, overwriting): `tools.exec.mode` defaults to `full` and the sandbox is off. Asking it to "show me the plan first" is a request the model may or may not honour, not a safety control. - -For a real confirmation step, turn on approvals and check the result: - -```bash -openclaw config set tools.exec.mode ask -openclaw exec-policy show -``` - -In `ask` mode, allowlisted commands run and everything else waits for you to approve it in the chat or Control UI. `openclaw approvals get` shows the requested policy, the host approvals file and the effective result. See [permission modes](https://docs.openclaw.ai/tools/permission-modes) and the [hardening checklist](/security/hardening#exec-approvals). -::: - --- ## Quick Scripts @@ -131,9 +130,11 @@ In `ask` mode, allowlisted commands run and everything else waits for you to app Need a one-off script? Describe what you want in plain language. The bot writes it, explains it, and can run it for you. ``` -Write a bash script that backs up my ~/.openclaw directory to ~/backups with a timestamp +Write a bash script that backs up ~/Documents/notes to ~/backups with a timestamp ``` +(For OpenClaw's own state, use `openclaw backup create` instead; copying `~/.openclaw` while the Gateway runs can catch its SQLite databases mid-write. See [Day 7](./day-7-production.md#backups).) + ``` Write a Python script that reads a CSV file and outputs the rows where the "status" column is "failed" ``` @@ -184,36 +185,6 @@ System access depends on the permissions of the user running OpenClaw. The bot c --- -## Practical Examples - -Copy-paste these into your next chat session. Each one is a real task you can try right now: - -``` -Summarize https://news.ycombinator.com -``` - -``` -Find all files larger than 100MB in my home directory -``` - -``` -Write a bash script that backs up my ~/.openclaw directory to ~/backups with a timestamp -``` - -``` -What processes are using the most memory right now? -``` - -``` -Create a Python script that converts all PNG files in ~/images to JPEG -``` - -``` -Show my current git branches across all repos in ~/projects and flag any with uncommitted changes -``` - ---- - ## Tips for Better Results **Be specific.** "Write a script" is vague. "Write a bash script that monitors CPU temperature and logs it to ~/logs/temp.csv every 5 minutes" gives the bot everything it needs in one shot. diff --git a/docs/guides/first-7-days/day-3-automation.md b/docs/guides/first-7-days/day-3-automation.md index ce055dd..bb27b5b 100644 --- a/docs/guides/first-7-days/day-3-automation.md +++ b/docs/guides/first-7-days/day-3-automation.md @@ -25,7 +25,7 @@ OpenClaw has two kinds of scheduled work, and both are run by the Gateway's auto |---|---|---| | What it is | A job you create: a schedule plus a prompt (or a command) | One system-owned monitor job per agent | | When it runs | Exactly when you say: `0 8 * * *`, `every 2h`, a one-shot `--at 20m` | Every `30m` by default (`1h` with Anthropic OAuth/token auth) | -| Where it runs | Its own isolated session by default | The agent's main session by default | +| Where it runs | A fresh isolated session when created from the CLI; the creating conversation when created in chat | The agent's main session by default | | What it does | Whatever the prompt says, then delivers the result | Checks its scratch notes and replies `NO_REPLY` if nothing needs attention | | Use it for | Briefings, reports, recurring checks | "Is anything urgent?" sweeps, follow-ups on background work | @@ -45,7 +45,7 @@ Scheduled work needs somewhere to send its results. openclaw config set commands.ownerAllowFrom '["telegram:123456789"]' ``` -- **Automations** you create from a chat reply to that chat. Automations you create from the CLI need a route: pass `--channel telegram --to ""` (for a DM with your bot, the chat ID is your user ID). +- **Automations** you create from a chat reply to that chat. From the CLI, a job defaults to `--channel last`, which resolves from session history (or your only configured channel) and fails closed if it can't. Pin the destination with `--channel telegram --to ""` (for a DM with your bot, the chat ID is your user ID); `openclaw cron show ` previews the resolved route. - **Times** use your timezone. Set `agents.defaults.userTimezone` (see [Day 1](./day-1-make-it-yours.md#tell-it-about-you)); automation cron expressions use the Gateway host's timezone unless you pass `--tz`. @@ -109,7 +109,7 @@ Issue and PR text is written by strangers. Treat it as untrusted input: keep thi ### Server Health Check -For checks with a clear pass/fail rule, a **command job** is safer and cheaper than a model run. It executes a fixed shell command on the Gateway host, with no model in the loop, and delivers its output. Output that is exactly `NO_REPLY` is suppressed: +For checks with a clear pass/fail rule, a **command job** is safer and cheaper than a model run. It executes a fixed shell command on the Gateway host, with no model in the loop, and delivers its output. Output that is exactly `NO_REPLY` is suppressed. The command runs inside the Gateway process, not through the agent's `exec` tool, so exec approvals do not apply: only an operator (`operator.admin`) can create one, and the model can't change what it runs: ```bash openclaw cron add "0 * * * *" \ @@ -263,7 +263,7 @@ Common issues: - **Nothing runs:** Check that `openclaw gateway status` shows the Gateway running, and `openclaw cron status` shows the scheduler enabled. `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1` turns scheduling off. - **Heartbeat never messages you:** That is normal when nothing needs attention (`NO_REPLY`). If the logs show heartbeat polls skipped with `reason=no-route`, there is no owner to deliver to: set `commands.ownerAllowFrom`. -- **Automation runs but you get nothing:** Check the delivery column in `openclaw cron runs `. CLI-created jobs need `--channel` and `--to`. +- **Automation runs but you get nothing:** Check the delivery column in `openclaw cron runs ` and the route in `openclaw cron show `. Pin it with `openclaw cron edit --channel telegram --to ""`. - **Wrong timing:** Check `--tz` on the job and `agents.defaults.userTimezone`. Heartbeats outside `activeHours` are skipped. - **High costs:** Lower the frequency, add `lightContext`/`isolatedSession`, and move script-decidable checks to command jobs. Check `openclaw gateway usage-cost`. diff --git a/docs/guides/first-7-days/day-4-skills.md b/docs/guides/first-7-days/day-4-skills.md index 523f107..8916471 100644 --- a/docs/guides/first-7-days/day-4-skills.md +++ b/docs/guides/first-7-days/day-4-skills.md @@ -15,6 +15,8 @@ keywords: [openclaw, skills, install skills, clawhub, skill tutorial, community Your bot can chat and run scheduled jobs. Today you give it **skills**: written instructions that teach it how to do specific jobs well, like working with GitHub, your calendar or your notes. Many skills already ship with OpenClaw. More are on ClawHub, the community registry. +**Time:** ~30 minutes + ## What are skills? A skill is a **directory** that contains a `SKILL.md` file. The file has YAML frontmatter with a `name` and a `description`, then Markdown instructions ([Skills](https://docs.openclaw.ai/tools/skills)). @@ -154,11 +156,11 @@ To turn a skill off without uninstalling it, disable it in config: API keys and settings for a skill also go in `skills.entries.` (`apiKey`, `env`, `config`), not in the skill file ([Skills config](https://docs.openclaw.ai/tools/skills-config)). Those values are injected into the host process for that turn, not into a sandbox. -To remove a ClawHub skill, use the standalone ClawHub CLI, which asks for confirmation before deleting the folder: +To remove a ClawHub skill, use the standalone ClawHub CLI. Point `--workdir` at the workspace it was installed into (`~/.openclaw` for a `--global` install); it asks for confirmation before deleting the folder ([remove a ClawHub skill](https://docs.openclaw.ai/cli/skills)): ```bash npm i -g clawhub -clawhub uninstall @asleep123/caldav-calendar +clawhub --workdir ~/.openclaw/workspace uninstall @asleep123/caldav-calendar ``` ## Building vs installing diff --git a/docs/guides/first-7-days/day-5-multi-channel.md b/docs/guides/first-7-days/day-5-multi-channel.md index e7e5bd4..9318897 100644 --- a/docs/guides/first-7-days/day-5-multi-channel.md +++ b/docs/guides/first-7-days/day-5-multi-channel.md @@ -234,7 +234,7 @@ Notes: - To also wake the bot on a text pattern (for example `!bot`), add `groupChat.mentionPatterns` to the agent: `agents.entries.main.groupChat.mentionPatterns: ["!bot"]`. - There is no per-channel message rate limit setting. Control cost with model choice and by keeping the bot out of busy rooms. -Upstream's channel access guidance, with more examples: [Who can talk to the agent](/security/hardening#channel-access). +More examples and the reasoning: [Who can talk to the agent](/security/hardening#channel-access) on the hardening page, and upstream's [access control](https://docs.openclaw.ai/gateway/security/access-control). --- diff --git a/docs/guides/first-7-days/day-6-power-moves.md b/docs/guides/first-7-days/day-6-power-moves.md index c9c4a19..ed38bfd 100644 --- a/docs/guides/first-7-days/day-6-power-moves.md +++ b/docs/guides/first-7-days/day-6-power-moves.md @@ -134,7 +134,7 @@ openclaw cron add "0 17 * * 5" \ --tools read,write ``` -This runs every Friday at 17:00 in the Gateway host's timezone (add `--tz Europe/Berlin` to pin one). The schedule is standard [cron syntax](https://crontab.guru/). For an interval or a one-shot time, use `--every 6h` or `--at 20m` instead. The first argument then becomes the job name and the prompt goes in `--message`. +This runs every Friday at 17:00 in the Gateway host's timezone (add `--tz Europe/Berlin` to pin one). The schedule is standard [cron syntax](https://crontab.guru/). The positional schedule also takes an interval (`"every 6h"`) or a one-shot time (`"20m"`, or an ISO timestamp). `--tools` limits the job to the tools it needs. Without it, the job gets the agent's full tool policy, which by default includes running shell commands without approval. Give scheduled jobs the smallest tool list that works ([job payloads](https://docs.openclaw.ai/automation/cron-jobs/payloads)). @@ -146,18 +146,14 @@ openclaw cron add "30 7 * * 1-5" \ "Search for the latest news in AI and open source and summarise the top 5 stories with links" \ --name "Morning digest" \ --tools web_search,web_fetch - -# Disk check every 6 hours -openclaw cron add "0 */6 * * *" \ - "Run df -h. If any filesystem is above 85% used, tell me which one. Otherwise reply NO_REPLY." \ - --name "Disk check" \ - --tools exec ``` -Results are delivered to the last channel you used. Add `--channel telegram --to ` to pin a destination, or `--no-deliver` to keep a job's output internal. +For a check a script can decide, such as disk usage, use a command job instead of giving a model `exec` ([Day 3](./day-3-automation.md#server-health-check)). + +Results go to `--channel last` by default, which follows your recent conversation and fails closed if there is none. Add `--channel telegram --to ` to pin a destination, or `--no-deliver` to keep a job's output internal. :::warning Jobs run unattended -A scheduled job that can run shell commands does it with nobody watching. Turn on exec approvals (`tools.exec.mode: "ask"`) and keep prompts specific. See [Security Hardening: exec approvals](/security/hardening#exec-approvals). For backing up OpenClaw itself, use `openclaw backup create` rather than a prompt. +A scheduled job that can run shell commands does it with nobody watching. Keep `exec` out of `--tools` unless the job needs it, and turn on exec approvals (`tools.exec.mode: "ask"`). With approvals on, an automation's exec request goes to the Control UI or a companion app (never to chat); if none is connected, it is denied. **Always allow** on that card mints a standing grant for that exact job and command ([standing grants](https://docs.openclaw.ai/tools/exec-approvals#standing-grants-for-automations)). See [Security Hardening: exec approvals](/security/hardening#exec-approvals). For backing up OpenClaw itself, use `openclaw backup create` rather than a prompt. ::: ### Manage jobs diff --git a/docs/guides/first-7-days/day-7-production.md b/docs/guides/first-7-days/day-7-production.md index d31cd11..ac239f3 100644 --- a/docs/guides/first-7-days/day-7-production.md +++ b/docs/guides/first-7-days/day-7-production.md @@ -76,7 +76,7 @@ openclaw config validate openclaw gateway restart openclaw approvals get # what exec policy is actually in force openclaw security audit --deep -openclaw security audit --fix # tightens file permissions and safe defaults +openclaw security audit --fix # file permissions and open group policies only openclaw secrets audit --check ``` @@ -135,15 +135,15 @@ Useful for channel issues, skill runs and automations. Press `Ctrl+C` to stop. ` ### A daily self-check -Make it an automation, not a heartbeat note. This runs at 07:30 every day and only reports problems: +Make it an automation, not a heartbeat note. This runs at 07:30 every day and only reports problems. It needs `exec` to run the two commands, and nothing else: ```bash openclaw cron add "30 7 * * *" \ "Run openclaw status --deep and openclaw security audit. If anything is failing, disconnected or flagged, message me a short summary. Otherwise reply NO_REPLY." \ - --name "Daily self-check" --light-context + --name "Daily self-check" --light-context --tools exec ``` -`openclaw cron list` shows the job id; `openclaw cron runs ` shows its history. +With approvals on (you set `ask` above), test it once with `openclaw cron run --wait` while the Control UI is open, and choose **Always allow** on each approval card. That mints a standing grant for this job and these exact commands. Any other command the job tries still needs approval, and is denied when no approval client is connected ([standing grants](https://docs.openclaw.ai/tools/exec-approvals#standing-grants-for-automations)). `openclaw cron runs ` shows its history. --- diff --git a/docs/guides/first-7-days/index.md b/docs/guides/first-7-days/index.md index 8b00f0a..ef003fe 100644 --- a/docs/guides/first-7-days/index.md +++ b/docs/guides/first-7-days/index.md @@ -9,9 +9,7 @@ keywords: [openclaw, tutorial, getting started, learn openclaw, beginner guide, # First 7 Days with OpenClaw -You installed OpenClaw. You typed "hello." It replied. Now what? - -This series takes you from first conversation to power user in 7 steps. Each "day" is a self-contained guide you can finish in under an hour. Do them at your own pace — one per day, or all in an afternoon. Every command and config block was checked against OpenClaw **v2026.10.4**. +Seven self-contained guides that take you from a first conversation to a hardened, automated setup. Each takes under an hour; do one a day or several in an afternoon. Every command and config block was checked against OpenClaw **v2026.10.4**. | Day | What You'll Learn | Time | |-----|------------------|------| @@ -31,7 +29,7 @@ This series takes you from first conversation to power user in 7 steps. Each "da - OpenClaw installed and onboarded. `openclaw onboard` (or the installer's Quick start) verifies your model access, starts the Gateway and seeds the workspace files used on Day 1. See [Getting started](https://docs.openclaw.ai/start/getting-started). - The Gateway running. `openclaw gateway status` should show it listening on port 18789, and `openclaw status` shows channel health. -- A way to talk to the bot. The Control UI (`openclaw dashboard`) and the terminal UI (`openclaw tui`) work with no extra setup. For your phone, Telegram is the easiest first channel: it is built into core and needs only a bot token ([Telegram setup](https://docs.openclaw.ai/channels/telegram/setup)). +- A way to talk to the bot. The Control UI (`openclaw dashboard`) and the terminal UI (`openclaw tui`) work with no extra setup. For your phone, Telegram is the easiest first channel: it is bundled with OpenClaw and needs only a bot token ([Telegram setup](https://docs.openclaw.ai/channels/telegram/setup)). - An owner set for proactive messages. Approving your own first Telegram DM with `openclaw pairing approve` sets `commands.ownerAllowFrom` for you; Day 3 explains why it matters. ```bash @@ -52,5 +50,3 @@ Out of the box, OpenClaw runs shell commands **without asking** (`tools.exec.mod - Bundled and community skills installed and checked - At least one custom skill you built yourself - A hardened, backed-up, cost-aware setup - -Let's get started. From 36d50367745bee0afd25d6311094c4455b7e44c2 Mon Sep 17 00:00:00 2001 From: Melvin Carvalho Date: Sun, 18 Oct 2026 17:59:37 +0200 Subject: [PATCH 5/5] Day 7 and skill verification: triage needs --non-interactive; reconcile pending-scan statements --- docs/guides/first-7-days/day-7-production.md | 2 +- docs/security/skill-verification.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/first-7-days/day-7-production.md b/docs/guides/first-7-days/day-7-production.md index ac239f3..6c5b5c2 100644 --- a/docs/guides/first-7-days/day-7-production.md +++ b/docs/guides/first-7-days/day-7-production.md @@ -228,7 +228,7 @@ openclaw backup restore ~/Backups/openclaw/.tar.gz --target ~/openclaw- `backup restore` verifies the archive and extracts it into a fresh staging directory; it never overwrites your live install. Follow the rollback guide for putting the restored state back with the matching release. `openclaw gateway start` brings the service back up. -If you're stuck, `openclaw triage` runs read-only checks and writes a sanitized diagnosis you can hand to a coding agent or paste into a bug report. +If you're stuck, `openclaw triage --non-interactive` runs checks without offering a repair agent and writes a sanitized diagnosis you can hand to a coding agent or paste into a bug report. --- diff --git a/docs/security/skill-verification.md b/docs/security/skill-verification.md index 305d919..29c1e16 100644 --- a/docs/security/skill-verification.md +++ b/docs/security/skill-verification.md @@ -61,7 +61,7 @@ openclaw skills verify @owner/ --version `verify` exits non-zero when ClawHub marks verification as failed. When ClawHub has kept them, the JSON includes the full SkillSpector and AIG scanner reports under `security.scannerReports`. Use owner-qualified refs (`@owner/`) to avoid picking up a lookalike publisher. -A pass is a signal, not a guarantee. A pending or stale scan can still allow installation with a warning, so installation is not proof that every scan completed ([why OpenClaw](https://docs.openclaw.ai/start/why-openclaw)). +A pass is a signal, not a guarantee. Since 2026-10-13 new ClawHub releases stay unpublished until their pre-publication scans pass ([see below](#virustotal-integration-v202626)), but releases from before that date and later rescans can still show a pending or stale result, and installation may proceed with a warning. Installation is not proof that every scan completed ([why OpenClaw](https://docs.openclaw.ai/start/why-openclaw)). ### 2. Check Against Koi Security's Database