melvincarvalho · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026 · Oct 18, 2026
diff --git a/docs/guides/cicd-testing.md b/docs/guides/cicd-testing.md
@@ -292,12 +292,11 @@ The skills watcher picks up skill changes on the next agent turn; config changes
 openclaw backup create --verify --output ~/Backups
 openclaw update --dry-run
 openclaw update --yes
-openclaw doctor --fix
-openclaw config validate
+openclaw doctor --lint
 openclaw channels status --probe
 ```
 
-`openclaw update` rehearses the update, restarts the Gateway, and rolls back if the post-update doctor fails. Run `openclaw doctor --fix` after every upgrade: releases retire config keys and Doctor migrates them. To roll back by hand, restore the backup and install the previous version with `openclaw update --tag <version>`.
+`openclaw update` runs the Doctor migrations the new release needs, restarts the Gateway and verifies it. If verification fails, it rolls back to the previous package and config automatically **only when no database schema changed** (a schema-neutral update); otherwise it keeps the new version and its recovery artifacts and reports what to do ([Rollback and recovery](https://docs.openclaw.ai/install/updating/rollback-and-recovery)). Installing an older version does not reverse migrations, so the reliable way back after a migrating update is to restore the verified backup with its matching release. `openclaw update --tag <version>` only works while the older release can still read your state.
 
 ### Docker
 
@@ -327,29 +326,7 @@ The image already has a `HEALTHCHECK` on `/healthz` (liveness). Use `/startupz`
 
 ## Triggering the Agent From CI
 
-To have a pipeline wake an agent (for example, "summarize this failed build"), enable Gateway HTTP hooks with a dedicated token:
-
-```json5 title="~/.openclaw/openclaw.json"
-{
-  hooks: {
-    enabled: true,
-    token: "${OPENCLAW_HOOKS_TOKEN}",
-    path: "/hooks",
-    allowedAgentIds: ["main"],
-    allowRequestSessionKey: false,
-  },
-}
-```
-
-```bash
-curl -fsS https://agent.example.com/hooks/agent \
-  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
-  -H 'Content-Type: application/json' \
-  -H "Idempotency-Key: build-$GITHUB_RUN_ID" \
-  --data '{"message":"Build failed on main. Summarize the log at the attached URL.","agentId":"main","deliver":true}'
-```
-
-An HTTP 200 means the run was admitted, not that it finished. Expose the Gateway only over HTTPS or a private network, never as plain HTTP on the internet. Treat the message as untrusted input to the agent. See [Inbound webhooks](https://docs.openclaw.ai/automation/cron-jobs/webhooks) and [API & Webhooks](/guides/api-webhooks).
+To have a pipeline wake an agent ("summarize this failed build"), enable Gateway HTTP hooks with their own token and `curl` the `/hooks/agent` endpoint from the job, using the run ID as the `Idempotency-Key`. Config, a GitHub Actions example and the security notes are in [API & Webhooks](/guides/api-webhooks#github-actions). Treat the message as untrusted input to the agent, and reach the Gateway only over HTTPS or a private network.
 
 For scheduled checks on the agent host itself, use an [Automation](/guides/automation) job, for example `openclaw cron add "0 2 * * *" "Run the nightly health checklist" --name nightly-check`.
 
@@ -371,7 +348,7 @@ For scheduled checks on the agent host itself, use an [Automation](/guides/autom
 
 - [ ] `openclaw backup create --verify`
 - [ ] Release notes read; `openclaw update --dry-run`
-- [ ] `openclaw doctor --fix` and `openclaw config validate` after the update
+- [ ] `openclaw doctor --lint` after the update; a verified backup kept until you have checked the upgrade
 - [ ] `openclaw channels status --probe` shows channels back
 
 ---

diff --git a/docs/guides/clawhub.md b/docs/guides/clawhub.md
@@ -52,7 +52,7 @@ Skill names are scoped to their publisher: `@alice/meeting-notes` and `@bob/meet
 
 ### Other directories
 
-- [skills.sh](https://skills.sh): an Agent Skills directory across agents. OpenClaw installs from it with `openclaw skills install skills-sh:owner/repo/slug`. These entries are marked **Not scanned by ClawHub**.
+- [skills.sh](https://skills.sh): an Agent Skills directory across agents. OpenClaw installs from it with `openclaw skills install skills-sh:owner/repo/slug`. OpenClaw marks these installs **Not scanned by ClawHub**.
 - [VoltAgent/awesome-openclaw-skills](https://github.com/VoltAgent/awesome-openclaw-skills): a large community list. Inclusion is not a security review.
 - [clawskills.sh](https://clawskills.sh): a third-party discovery site, unrelated to skills.sh.
 
@@ -164,7 +164,7 @@ For CI, ClawHub ships a reusable GitHub Actions workflow; see [CI/CD & Testing](
 
 ### After you publish
 
-Publishes are staged: since 2026-10-13 every skill version and package release is held as pending behind pre-publication checks, and a scanner failure or timeout leaves it unpublished rather than letting it through ([clawhub PR #3947](https://github.com/openclaw/clawhub/pull/3947)). The checks are static analysis, VirusTotal, SkillSpector, Tencent A.I.G and ClawScan risk analysis; the release appears in search once it clears. Releases that are held or blocked stay visible to their owner. Download the scan report for a blocked version with:
+A new release stays pending until it clears ClawHub's pre-publication checks (see [What ClawHub checks today](#what-clawhub-checks-today)), then appears in search. Releases that are held or blocked stay visible to their owner. Download the scan report for a blocked version with:
 
 ```bash
 clawhub scan download my-skill --version 1.0.1 --output report.zip
@@ -176,96 +176,21 @@ Skills the agent writes for itself go through [Skill Workshop](/guides/skill-wor
 
 ## Security
 
-### The ClawHavoc incident (February 2026)
+### Incident history {#the-clawhavoc-incident-february-2026}
 
-Koi Security audited all 2,857 skills then on ClawHub and flagged 341 as malicious, 335 of them from one campaign it named **ClawHavoc** ([The Hacker News](https://thehackernews.com/2026/02/researchers-find-341-malicious-clawhub.html), [SC Media](https://www.scworld.com/news/openclaw-agents-targeted-with-341-malicious-clawhub-skills), [eSecurity Planet](https://www.esecurityplanet.com/threats/hundreds-of-malicious-skills-found-in-openclaws-clawhub/)). The skills posed as crypto wallet trackers, Polymarket bots, YouTube tools and Google Workspace integrations, often under typosquatted names. Most told the user to run a fake "Prerequisites" step that installed **Atomic macOS Stealer (AMOS)**. Windows users were sent a password-protected ZIP containing a keylogger.
-
-Around the same time, Snyk's **ToxicSkills** study scanned 3,984 skills from ClawHub and skills.sh and found at least one security flaw in 36.8% of them, a critical issue in 13.4%, and 76 confirmed malicious payloads ([Snyk](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub)).
-
-### Unit 42 findings (June 2026)
-
-On 23 June 2026, Palo Alto Networks Unit 42 reported five malicious skills that had passed ClawHub's scanning between February and May 2026 ([Unit 42](https://unit42.paloaltonetworks.com/openclaw-ai-supply-chain-risk/)):
-
-- **Two macOS infostealers** with command-and-control connectivity
-- **`omnicogg`**, which hid an AMOS dropper in `README.md` and padded the file with 22 MB of junk to get past scanner size limits. Both VirusTotal and ClawScan returned clean.
-- **`money-radar`**, a fake financial adviser that injected affiliate links at runtime
-- **`letssendit`**, an agentic Solana front-running skill
-
-The publisher accounts were banned and the skills removed. The lesson stands: scanning catches a lot, and attackers design around it.
+In February 2026 Koi Security flagged 341 of the 2,857 skills then on ClawHub as malicious, 335 of them from one campaign (**ClawHavoc**) that used a fake "Prerequisites" step to install the Atomic macOS Stealer. In June 2026 Palo Alto Networks Unit 42 reported five more malicious skills that had passed ClawHub's scanning, including one that padded `README.md` with 22 MB of junk to get past scanner size limits ([Unit 42](https://unit42.paloaltonetworks.com/openclaw-ai-supply-chain-risk/)). Scanning catches a lot, and attackers design around it. The full history is in [Known Vulnerabilities](/security/known-vulnerabilities#malicious-clawhub-skills-february-2026).
 
 ### What ClawHub checks today
 
-Each release gets a security audit on its skill page, combining ([Security audits](https://docs.openclaw.ai/clawhub/security-audits)):
-
-- **NVIDIA SkillSpector** findings
-- **Tencent A.I.G** findings on agent instructions. Because A.I.G cannot inspect Python bytecode, ClawHub rejects skills containing `.pyc`, `.pyo` or `.pyd` files.
-- **ClawScan** risk analysis, which asks whether the name, description, declared permissions and actual content line up, using the OWASP Agentic Skills Top 10 as a lens
-- **VirusTotal** and static analysis results, shown as detail pages
+Since 2026-10-13 every new skill version and package release is held as **pending** until the TruffleHog and ClawScan pre-publication checks pass on that exact artifact. A malicious verdict blocks the release; a scanner failure or timeout leaves it unpublished ([clawhub PR #3947](https://github.com/openclaw/clawhub/pull/3947)). The skill's security audit page then combines results from NVIDIA SkillSpector, Tencent A.I.G, ClawScan, VirusTotal and static analysis ([Security audits](https://docs.openclaw.ai/clawhub/security-audits)). Because A.I.G cannot inspect Python bytecode, ClawHub rejects skills containing `.pyc`, `.pyo` or `.pyd` files.
 
 Signed-in users can report a skill with the **Report skill** button. Reports never hide a skill automatically; moderators review them ([ClawHub moderation spec](https://github.com/openclaw/clawhub/blob/main/specs/security-moderation.md)). The old auto-hide rule was withdrawn after GHSA-5jj4-m8c9-gwcq showed that four ordinary accounts could hide any skill, official ones included.
 
-OpenClaw itself also has a local code-safety scanner (since 2026.2.6), and `openclaw skills install` refuses releases ClawHub has marked malicious or blocked.
-
-### Third-party tools
-
-- [Clawdex by Koi](https://clawhub.ai/wearekoi/skills/clawdex) (`@wearekoi/clawdex`): a skill that checks other skills against Koi's malicious-skills database before you install them. Koi is now part of Palo Alto Networks.
-- [Snyk agent-scan](https://github.com/snyk/agent-scan): an open-source security scanner for AI agents, MCP servers and agent skills (formerly `mcp-scan`).
-
-### Red flags
-
-Avoid skills that contain:
-
-- `curl | bash` or `wget | bash`, or a "prerequisites" step that downloads and runs something
-- Base64-encoded strings or zero-width Unicode characters
-- Very large files with little content (padding to evade scanners)
-- Hardcoded URLs to unknown domains
-- Reads of `~/.ssh`, `~/.aws`, browser profiles, wallets or other credential paths
-- Environment variables that do not fit the skill's purpose
-- `chmod 777`, or instructions to edit `SOUL.md` or agent config
+On the OpenClaw side, `openclaw skills install` refuses releases ClawHub has marked malicious or blocked, and `openclaw security audit --deep` runs the local code-safety scanner over installed skills. Red flags to look for when reading a skill, and third-party scanners, are in [Skill Verification](/security/skill-verification#3-review-the-source).
 
 ### Locking down installs
 
-There is no setting that switches ClawHub off. To control what can be installed, use `security.installPolicy`: a trusted local command that OpenClaw runs before every skill or plugin install or update (ClawHub, skills.sh, git, local, uploads, dependency installers). It answers `allow`, `warn` or `block`, and installs fail closed if it cannot answer.
-
-```json5 title="~/.openclaw/openclaw.json"
-{
-  security: {
-    installPolicy: {
-      enabled: true,
-      targets: ["skill", "plugin"],
-      exec: {
-        source: "exec",
-        command: "/usr/local/bin/openclaw-install-policy",
-        timeoutMs: 10000,
-        trustedDirs: ["/usr/local/bin"],
-      },
-    },
-  },
-}
-```
-
-The command reads one JSON request on stdin and writes one decision on stdout:
-
-```js title="/usr/local/bin/openclaw-install-policy"
-#!/usr/bin/env node
-let input = "";
-process.stdin.on("data", (c) => (input += c));
-process.stdin.on("end", () => {
-  const req = JSON.parse(input);
-  const decision =
-    req.targetType === "skill"
-      ? { protocolVersion: 1, decision: "block", reason: "skill installs are disabled on this host" }
-      : { protocolVersion: 1, decision: "allow" };
-  process.stdout.write(JSON.stringify(decision));
-});
-```
-
-The file must be a regular file owned by a trusted user with restricted permissions. `openclaw doctor --deep` runs a test request against it. See [Operator install policy](https://docs.openclaw.ai/tools/skills-config#operator-install-policy-security-installpolicy) for the full request and response format.
-
-Two more controls:
-
-- `skills.allowBundled: ["github", "weather"]` limits which **bundled** skills are eligible.
-- `agents.defaults.skills` and `agents.entries.<id>.skills` limit which skills each agent can see. See [Skill Development](/guides/skill-development#which-agent-sees-which-skill).
+There is no setting that switches ClawHub off. `security.installPolicy` runs a trusted local command before every skill or plugin install or update (ClawHub, skills.sh, git, local, uploads, dependency installers); it answers `allow`, `warn` or `block`, and installs fail closed if it cannot answer. `skills.allowBundled` limits which bundled skills are eligible, and `agents.defaults.skills` / `agents.entries.<id>.skills` limit which skills each agent sees. Config and caveats: [Skill Verification](/security/skill-verification#restrict-or-block-installs) and upstream [Operator install policy](https://docs.openclaw.ai/tools/skills-config#operator-install-policy-security-installpolicy).
 
 ### Reporting
 
@@ -296,16 +221,16 @@ clawhub whoami
 clawhub search "query"
 clawhub explore [--sort downloads]
 clawhub inspect @owner/slug [--files] [--file <path>] [--versions]
-clawhub uninstall @owner/slug
-clawhub list
-clawhub pin <slug> [--reason <text>]
-clawhub unpin <slug>
+clawhub --workdir <dir> uninstall @owner/slug   # <dir>: agent workspace, or ~/.openclaw for --global
+clawhub --workdir <dir> list
+clawhub --workdir <dir> pin <slug> [--reason <text>]
+clawhub --workdir <dir> unpin <slug>
 clawhub skill publish <dir> [--dry-run] [--version <v>] [--owner <handle>] [--categories <slugs>]
 clawhub sync --all [--dry-run] [--bump minor]
 clawhub scan download <slug> --version <v>
 ```
 
-Full reference: [ClawHub CLI](https://docs.openclaw.ai/clawhub/cli) and [`openclaw skills`](https://docs.openclaw.ai/cli/skills).
+Full reference: [ClawHub CLI](https://docs.openclaw.ai/clawhub/cli), [`openclaw skills`](https://docs.openclaw.ai/cli/skills) and the site [CLI Reference](/reference/cli#skills-plugins-and-mcp).
 
 ---
 

diff --git a/docs/guides/cloud-gpu-models.md b/docs/guides/cloud-gpu-models.md
@@ -49,7 +49,7 @@ Prices are approximate on-demand list prices **as of 2026-10-18**, taken from ea
 | [**RunPod**](https://www.runpod.io/pricing) | A100 80GB | 80 GB | $1.19-$1.79 | ~$870-$1,310 | 70B quantized, 32B full precision |
 | [**RunPod**](https://www.runpod.io/pricing) | H100 80GB | 80 GB | $1.99-$3.99 | ~$1,450-$2,910 | PCIe vs SXM, community vs secure |
 | [**Lambda**](https://lambda.ai/pricing) | A100 40GB | 40 GB | $1.99 | ~$1,450 | Simple pricing |
-| [**Lambda**](https://lambda.ai/pricing) | H100 80GB | 80 GB | $3.29 PCIe / $4.29 SXM | ~$2,400 / ~$3,130 | |
+| [**Lambda**](https://lambda.ai/pricing) | H100 80GB | 80 GB | $3.29 PCIe / $3.99-$4.29 SXM | ~$2,400 / ~$2,910-$3,130 | |
 | [**Vast.ai**](https://vast.ai/pricing) | Various | Various | Marketplace (live) | Varies | Auction/marketplace model, usually cheapest, less predictable |
 | [**CoreWeave**](https://www.coreweave.com/pricing) | A100 / H100 | 80 GB | See pricing page | | Enterprise, InfiniBand |
 | [**AMD Developer Cloud**](https://devcloud.amd.com/) | MI300X | 192 GB | See site | | Check the site for current credit offers |
@@ -126,7 +126,7 @@ These providers host open-weight models behind an API. You pay per token; there
 | [**Together AI**](https://www.together.ai/pricing) | Bundled `together` provider | `TOGETHER_API_KEY` | Llama, DeepSeek, Kimi, GLM and more |
 | [**Fireworks AI**](https://fireworks.ai/pricing) | Official plugin `@openclaw/fireworks-provider` | `FIREWORKS_API_KEY` | Open-weight models and routers |
 | [**OpenRouter**](https://openrouter.ai) | Bundled `openrouter` provider; refs `openrouter/<author>/<slug>` | `OPENROUTER_API_KEY` | One key, many upstream providers |
-| [**Hugging Face**](https://huggingface.co/pricing) | Provider page upstream | `HF_TOKEN` | See [Hugging Face](https://docs.openclaw.ai/providers/huggingface) |
+| [**Hugging Face**](https://huggingface.co/pricing) | Bundled `huggingface` provider | `HF_TOKEN` or `HUGGINGFACE_HUB_TOKEN` | Routes to many inference providers; see [Hugging Face](https://docs.openclaw.ai/providers/huggingface) |
 | [**Modal**](https://modal.com/pricing) | Custom provider | your key | Serverless GPUs running your own vLLM |
 
 Per-token prices differ per model and change often, so check the linked pricing pages. OpenClaw's usage view shows the cost estimates it applies (`openclaw gateway usage-cost`).
@@ -256,23 +256,13 @@ TabbyAPI uses ExLlamaV2/V3 for speed on RTX 3090/4090 with EXL2/GPTQ quantized m
 
 ## OpenClaw Configuration Notes
 
-### Where things live
-
-| File | Purpose |
-|------|---------|
-| `~/.openclaw/openclaw.json` | Providers, models, agents, Gateway config |
-| `~/.openclaw/.env` | API keys and other secrets (keep it `600`) |
-
 ### Key rules
 
-| Rule | Detail |
-|------|--------|
-| `baseUrl` | OpenAI-compatible servers usually end in `/v1`. Ollama's native API must **not** have `/v1`. Copy the URL from the provider's docs |
-| `api` | Optional on custom providers (defaults to `openai-completions`); use `openai-responses` only if the server supports `/v1/responses` |
-| `models` | An array of `{ id, name, ... }`; `id` is provider-local, with no provider prefix |
-| Env substitution | `${ENV_VAR}` works in config values |
-| Model refs | Select models as `provider-id/model-id` |
-| Context window | Keep `contextWindow` at or below the server's `--max-model-len` |
+- `baseUrl`: OpenAI-compatible servers usually end in `/v1`; Ollama's native API must **not**. Copy it from the provider's docs.
+- `api`: optional on custom providers (defaults to `openai-completions`). Use `openai-responses` only if the server supports `/v1/responses`.
+- `models[].id` is provider-local, with no provider prefix; you select it as `provider-id/model-id`.
+- Keep `contextWindow` at or below the server's `--max-model-len`.
+- Put keys in `~/.openclaw/.env` (mode `600`) and reference them as `${ENV_VAR}`.
 
 ### How OpenClaw picks a model
 
@@ -357,10 +347,10 @@ For a full model selection guide covering cloud, local and hybrid setups, see th
 - **DeepSeek-R1-Distill-Qwen-32B** for planning and reasoning-heavy work
 - **Qwen 2.5 Coder 32B** for code-heavy work
 
-These are community experience, not benchmarks. The [llama.cpp recipes](https://docs.openclaw.ai/plugins/llama-cpp) are the maintained reference in 2026.10.4; upstream adds a [recommended models](https://docs.openclaw.ai/concepts/recommended-models) page after that release.
+These are community experience, not benchmarks. Upstream's [llama.cpp page](https://docs.openclaw.ai/plugins/llama-cpp) has maintained model recipes.
 
 :::warning
-**Avoid models under about 8B parameters** for agent work. They hallucinate tool calls and lose track of multi-step tasks. Test real tasks before you make an open model your default; the best results with OpenClaw still come from frontier hosted models.
+**Models under about 14B parameters often struggle with multi-step tool calling**, and those under 8B hallucinate tool calls. For reliable agent work use 30B+ or keep a hosted fallback. Test real tasks before you make an open model your default; the best results with OpenClaw still come from frontier hosted models.
 :::
 
 ---