@captain-app/openclaw 2026.2.4

package/docs/tools/chrome-extension.md

@@ -0,0 +1,178 @@
+---
+summary: "Chrome extension: let OpenClaw drive your existing Chrome tab"
+read_when:
+  - You want the agent to drive an existing Chrome tab (toolbar button)
+  - You need remote Gateway + local browser automation via Tailscale
+  - You want to understand the security implications of browser takeover
+title: "Chrome Extension"
+---
+
+# Chrome extension (browser relay)
+
+The OpenClaw Chrome extension lets the agent control your **existing Chrome tabs** (your normal Chrome window) instead of launching a separate openclaw-managed Chrome profile.
+
+Attach/detach happens via a **single Chrome toolbar button**.
+
+## What it is (concept)
+
+There are three parts:
+
+- **Browser control service** (Gateway or node): the API the agent/tool calls (via the Gateway)
+- **Local relay server** (loopback CDP): bridges between the control server and the extension (`http://127.0.0.1:18792` by default)
+- **Chrome MV3 extension**: attaches to the active tab using `chrome.debugger` and pipes CDP messages to the relay
+
+OpenClaw then controls the attached tab through the normal `browser` tool surface (selecting the right profile).
+
+## Install / load (unpacked)
+
+1. Install the extension to a stable local path:
+
+```bash
+openclaw browser extension install
+```
+
+2. Print the installed extension directory path:
+
+```bash
+openclaw browser extension path
+```
+
+3. Chrome → `chrome://extensions`
+
+- Enable “Developer mode”
+- “Load unpacked” → select the directory printed above
+
+4. Pin the extension.
+
+## Updates (no build step)
+
+The extension ships inside the OpenClaw release (npm package) as static files. There is no separate “build” step.
+
+After upgrading OpenClaw:
+
+- Re-run `openclaw browser extension install` to refresh the installed files under your OpenClaw state directory.
+- Chrome → `chrome://extensions` → click “Reload” on the extension.
+
+## Use it (no extra config)
+
+OpenClaw ships with a built-in browser profile named `chrome` that targets the extension relay on the default port.
+
+Use it:
+
+- CLI: `openclaw browser --browser-profile chrome tabs`
+- Agent tool: `browser` with `profile="chrome"`
+
+If you want a different name or a different relay port, create your own profile:
+
+```bash
+openclaw browser create-profile \
+  --name my-chrome \
+  --driver extension \
+  --cdp-url http://127.0.0.1:18792 \
+  --color "#00AA00"
+```
+
+## Attach / detach (toolbar button)
+
+- Open the tab you want OpenClaw to control.
+- Click the extension icon.
+  - Badge shows `ON` when attached.
+- Click again to detach.
+
+## Which tab does it control?
+
+- It does **not** automatically control “whatever tab you’re looking at”.
+- It controls **only the tab(s) you explicitly attached** by clicking the toolbar button.
+- To switch: open the other tab and click the extension icon there.
+
+## Badge + common errors
+
+- `ON`: attached; OpenClaw can drive that tab.
+- `…`: connecting to the local relay.
+- `!`: relay not reachable (most common: browser relay server isn’t running on this machine).
+
+If you see `!`:
+
+- Make sure the Gateway is running locally (default setup), or run a node host on this machine if the Gateway runs elsewhere.
+- Open the extension Options page; it shows whether the relay is reachable.
+
+## Remote Gateway (use a node host)
+
+### Local Gateway (same machine as Chrome) — usually **no extra steps**
+
+If the Gateway runs on the same machine as Chrome, it starts the browser control service on loopback
+and auto-starts the relay server. The extension talks to the local relay; the CLI/tool calls go to the Gateway.
+
+### Remote Gateway (Gateway runs elsewhere) — **run a node host**
+
+If your Gateway runs on another machine, start a node host on the machine that runs Chrome.
+The Gateway will proxy browser actions to that node; the extension + relay stay local to the browser machine.
+
+If multiple nodes are connected, pin one with `gateway.nodes.browser.node` or set `gateway.nodes.browser.mode`.
+
+## Sandboxing (tool containers)
+
+If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:
+
+- By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
+- Chrome extension relay takeover requires controlling the **host** browser control server.
+
+Options:
+
+- Easiest: use the extension from a **non-sandboxed** session/agent.
+- Or allow host browser control for sandboxed sessions:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        browser: {
+          allowHostControl: true,
+        },
+      },
+    },
+  },
+}
+```
+
+Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.
+
+Debugging: `openclaw sandbox explain`
+
+## Remote access tips
+
+- Keep the Gateway and node host on the same tailnet; avoid exposing relay ports to LAN or public Internet.
+- Pair nodes intentionally; disable browser proxy routing if you don’t want remote control (`gateway.nodes.browser.mode="off"`).
+
+## How “extension path” works
+
+`openclaw browser extension path` prints the **installed** on-disk directory containing the extension files.
+
+The CLI intentionally does **not** print a `node_modules` path. Always run `openclaw browser extension install` first to copy the extension to a stable location under your OpenClaw state directory.
+
+If you move or delete that install directory, Chrome will mark the extension as broken until you reload it from a valid path.
+
+## Security implications (read this)
+
+This is powerful and risky. Treat it like giving the model “hands on your browser”.
+
+- The extension uses Chrome’s debugger API (`chrome.debugger`). When attached, the model can:
+  - click/type/navigate in that tab
+  - read page content
+  - access whatever the tab’s logged-in session can access
+- **This is not isolated** like the dedicated openclaw-managed profile.
+  - If you attach to your daily-driver profile/tab, you’re granting access to that account state.
+
+Recommendations:
+
+- Prefer a dedicated Chrome profile (separate from your personal browsing) for extension relay usage.
+- Keep the Gateway and any node hosts tailnet-only; rely on Gateway auth + node pairing.
+- Avoid exposing relay ports over LAN (`0.0.0.0`) and avoid Funnel (public).
+- The relay blocks non-extension origins and requires an internal auth token for CDP clients.
+
+Related:
+
+- Browser tool overview: [Browser](/tools/browser)
+- Security audit: [Security](/gateway/security)
+- Tailscale setup: [Tailscale](/gateway/tailscale)

package/docs/tools/clawhub.md

@@ -0,0 +1,257 @@
+---
+summary: "ClawHub guide: public skills registry + CLI workflows"
+read_when:
+  - Introducing ClawHub to new users
+  - Installing, searching, or publishing skills
+  - Explaining ClawHub CLI flags and sync behavior
+title: "ClawHub"
+---
+
+# ClawHub
+
+ClawHub is the **public skill registry for OpenClaw**. It is a free service: all skills are public, open, and visible to everyone for sharing and reuse. A skill is just a folder with a `SKILL.md` file (plus supporting text files). You can browse skills in the web app or use the CLI to search, install, update, and publish skills.
+
+Site: [clawhub.ai](https://clawhub.ai)
+
+## What ClawHub is
+
+- A public registry for OpenClaw skills.
+- A versioned store of skill bundles and metadata.
+- A discovery surface for search, tags, and usage signals.
+
+## How it works
+
+1. A user publishes a skill bundle (files + metadata).
+2. ClawHub stores the bundle, parses metadata, and assigns a version.
+3. The registry indexes the skill for search and discovery.
+4. Users browse, download, and install skills in OpenClaw.
+
+## What you can do
+
+- Publish new skills and new versions of existing skills.
+- Discover skills by name, tags, or search.
+- Download skill bundles and inspect their files.
+- Report skills that are abusive or unsafe.
+- If you are a moderator, hide, unhide, delete, or ban.
+
+## Who this is for (beginner-friendly)
+
+If you want to add new capabilities to your OpenClaw agent, ClawHub is the easiest way to find and install skills. You do not need to know how the backend works. You can:
+
+- Search for skills by plain language.
+- Install a skill into your workspace.
+- Update skills later with one command.
+- Back up your own skills by publishing them.
+
+## Quick start (non-technical)
+
+1. Install the CLI (see next section).
+2. Search for something you need:
+   - `clawhub search "calendar"`
+3. Install a skill:
+   - `clawhub install <skill-slug>`
+4. Start a new OpenClaw session so it picks up the new skill.
+
+## Install the CLI
+
+Pick one:
+
+```bash
+npm i -g clawhub
+```
+
+```bash
+pnpm add -g clawhub
+```
+
+## How it fits into OpenClaw
+
+By default, the CLI installs skills into `./skills` under your current working directory. If a OpenClaw workspace is configured, `clawhub` falls back to that workspace unless you override `--workdir` (or `CLAWHUB_WORKDIR`). OpenClaw loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.openclaw/skills` or bundled skills, workspace skills take precedence.
+
+For more detail on how skills are loaded, shared, and gated, see
+[Skills](/tools/skills).
+
+## Skill system overview
+
+A skill is a versioned bundle of files that teaches OpenClaw how to perform a
+specific task. Each publish creates a new version, and the registry keeps a
+history of versions so users can audit changes.
+
+A typical skill includes:
+
+- A `SKILL.md` file with the primary description and usage.
+- Optional configs, scripts, or supporting files used by the skill.
+- Metadata such as tags, summary, and install requirements.
+
+ClawHub uses metadata to power discovery and safely expose skill capabilities.
+The registry also tracks usage signals (such as stars and downloads) to improve
+ranking and visibility.
+
+## What the service provides (features)
+
+- **Public browsing** of skills and their `SKILL.md` content.
+- **Search** powered by embeddings (vector search), not just keywords.
+- **Versioning** with semver, changelogs, and tags (including `latest`).
+- **Downloads** as a zip per version.
+- **Stars and comments** for community feedback.
+- **Moderation** hooks for approvals and audits.
+- **CLI-friendly API** for automation and scripting.
+
+## Security and moderation
+
+ClawHub is open by default. Anyone can upload skills, but a GitHub account must
+be at least one week old to publish. This helps slow down abuse without blocking
+legitimate contributors.
+
+Reporting and moderation:
+
+- Any signed in user can report a skill.
+- Report reasons are required and recorded.
+- Each user can have up to 20 active reports at a time.
+- Skills with more than 3 unique reports are auto hidden by default.
+- Moderators can view hidden skills, unhide them, delete them, or ban users.
+- Abusing the report feature can result in account bans.
+
+Interested in becoming a moderator? Ask in the OpenClaw Discord and contact a
+moderator or maintainer.
+
+## CLI commands and parameters
+
+Global options (apply to all commands):
+
+- `--workdir <dir>`: Working directory (default: current dir; falls back to OpenClaw workspace).
+- `--dir <dir>`: Skills directory, relative to workdir (default: `skills`).
+- `--site <url>`: Site base URL (browser login).
+- `--registry <url>`: Registry API base URL.
+- `--no-input`: Disable prompts (non-interactive).
+- `-V, --cli-version`: Print CLI version.
+
+Auth:
+
+- `clawhub login` (browser flow) or `clawhub login --token <token>`
+- `clawhub logout`
+- `clawhub whoami`
+
+Options:
+
+- `--token <token>`: Paste an API token.
+- `--label <label>`: Label stored for browser login tokens (default: `CLI token`).
+- `--no-browser`: Do not open a browser (requires `--token`).
+
+Search:
+
+- `clawhub search "query"`
+- `--limit <n>`: Max results.
+
+Install:
+
+- `clawhub install <slug>`
+- `--version <version>`: Install a specific version.
+- `--force`: Overwrite if the folder already exists.
+
+Update:
+
+- `clawhub update <slug>`
+- `clawhub update --all`
+- `--version <version>`: Update to a specific version (single slug only).
+- `--force`: Overwrite when local files do not match any published version.
+
+List:
+
+- `clawhub list` (reads `.clawhub/lock.json`)
+
+Publish:
+
+- `clawhub publish <path>`
+- `--slug <slug>`: Skill slug.
+- `--name <name>`: Display name.
+- `--version <version>`: Semver version.
+- `--changelog <text>`: Changelog text (can be empty).
+- `--tags <tags>`: Comma-separated tags (default: `latest`).
+
+Delete/undelete (owner/admin only):
+
+- `clawhub delete <slug> --yes`
+- `clawhub undelete <slug> --yes`
+
+Sync (scan local skills + publish new/updated):
+
+- `clawhub sync`
+- `--root <dir...>`: Extra scan roots.
+- `--all`: Upload everything without prompts.
+- `--dry-run`: Show what would be uploaded.
+- `--bump <type>`: `patch|minor|major` for updates (default: `patch`).
+- `--changelog <text>`: Changelog for non-interactive updates.
+- `--tags <tags>`: Comma-separated tags (default: `latest`).
+- `--concurrency <n>`: Registry checks (default: 4).
+
+## Common workflows for agents
+
+### Search for skills
+
+```bash
+clawhub search "postgres backups"
+```
+
+### Download new skills
+
+```bash
+clawhub install my-skill-pack
+```
+
+### Update installed skills
+
+```bash
+clawhub update --all
+```
+
+### Back up your skills (publish or sync)
+
+For a single skill folder:
+
+```bash
+clawhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
+```
+
+To scan and back up many skills at once:
+
+```bash
+clawhub sync --all
+```
+
+## Advanced details (technical)
+
+### Versioning and tags
+
+- Each publish creates a new **semver** `SkillVersion`.
+- Tags (like `latest`) point to a version; moving tags lets you roll back.
+- Changelogs are attached per version and can be empty when syncing or publishing updates.
+
+### Local changes vs registry versions
+
+Updates compare the local skill contents to registry versions using a content hash. If local files do not match any published version, the CLI asks before overwriting (or requires `--force` in non-interactive runs).
+
+### Sync scanning and fallback roots
+
+`clawhub sync` scans your current workdir first. If no skills are found, it falls back to known legacy locations (for example `~/openclaw/skills` and `~/.openclaw/skills`). This is designed to find older skill installs without extra flags.
+
+### Storage and lockfile
+
+- Installed skills are recorded in `.clawhub/lock.json` under your workdir.
+- Auth tokens are stored in the ClawHub CLI config file (override via `CLAWHUB_CONFIG_PATH`).
+
+### Telemetry (install counts)
+
+When you run `clawhub sync` while logged in, the CLI sends a minimal snapshot to compute install counts. You can disable this entirely:
+
+```bash
+export CLAWHUB_DISABLE_TELEMETRY=1
+```
+
+## Environment variables
+
+- `CLAWHUB_SITE`: Override the site URL.
+- `CLAWHUB_REGISTRY`: Override the registry API URL.
+- `CLAWHUB_CONFIG_PATH`: Override where the CLI stores the token/config.
+- `CLAWHUB_WORKDIR`: Override the default workdir.
+- `CLAWHUB_DISABLE_TELEMETRY=1`: Disable telemetry on `sync`.

package/docs/tools/creating-skills.md

@@ -0,0 +1,54 @@
+---
+title: "Creating Skills"
+---
+
+# Creating Custom Skills 🛠
+
+OpenClaw is designed to be easily extensible. "Skills" are the primary way to add new capabilities to your assistant.
+
+## What is a Skill?
+
+A skill is a directory containing a `SKILL.md` file (which provides instructions and tool definitions to the LLM) and optionally some scripts or resources.
+
+## Step-by-Step: Your First Skill
+
+### 1. Create the Directory
+
+Skills live in your workspace, usually `~/.openclaw/workspace/skills/`. Create a new folder for your skill:
+
+```bash
+mkdir -p ~/.openclaw/workspace/skills/hello-world
+```
+
+### 2. Define the `SKILL.md`
+
+Create a `SKILL.md` file in that directory. This file uses YAML frontmatter for metadata and Markdown for instructions.
+
+```markdown
+---
+name: hello_world
+description: A simple skill that says hello.
+---
+
+# Hello World Skill
+
+When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
+```
+
+### 3. Add Tools (Optional)
+
+You can define custom tools in the frontmatter or instruct the agent to use existing system tools (like `bash` or `browser`).
+
+### 4. Refresh OpenClaw
+
+Ask your agent to "refresh skills" or restart the gateway. OpenClaw will discover the new directory and index the `SKILL.md`.
+
+## Best Practices
+
+- **Be Concise**: Instruct the model on _what_ to do, not how to be an AI.
+- **Safety First**: If your skill uses `bash`, ensure the prompts don't allow arbitrary command injection from untrusted user input.
+- **Test Locally**: Use `openclaw agent --message "use my new skill"` to test.
+
+## Shared Skills
+
+You can also browse and contribute skills to [ClawHub](https://clawhub.com).

package/docs/tools/elevated.md

@@ -0,0 +1,57 @@
+---
+summary: "Elevated exec mode and /elevated directives"
+read_when:
+  - Adjusting elevated mode defaults, allowlists, or slash command behavior
+title: "Elevated Mode"
+---
+
+# Elevated Mode (/elevated directives)
+
+## What it does
+
+- `/elevated on` runs on the gateway host and keeps exec approvals (same as `/elevated ask`).
+- `/elevated full` runs on the gateway host **and** auto-approves exec (skips exec approvals).
+- `/elevated ask` runs on the gateway host but keeps exec approvals (same as `/elevated on`).
+- `on`/`ask` do **not** force `exec.security=full`; configured security/ask policy still applies.
+- Only changes behavior when the agent is **sandboxed** (otherwise exec already runs on the host).
+- Directive forms: `/elevated on|off|ask|full`, `/elev on|off|ask|full`.
+- Only `on|off|ask|full` are accepted; anything else returns a hint and does not change state.
+
+## What it controls (and what it doesn’t)
+
+- **Availability gates**: `tools.elevated` is the global baseline. `agents.list[].tools.elevated` can further restrict elevated per agent (both must allow).
+- **Per-session state**: `/elevated on|off|ask|full` sets the elevated level for the current session key.
+- **Inline directive**: `/elevated on|ask|full` inside a message applies to that message only.
+- **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
+- **Host execution**: elevated forces `exec` onto the gateway host; `full` also sets `security=full`.
+- **Approvals**: `full` skips exec approvals; `on`/`ask` honor them when allowlist/ask rules require.
+- **Unsandboxed agents**: no-op for location; only affects gating, logging, and status.
+- **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.
+- **Separate from `/exec`**: `/exec` adjusts per-session defaults for authorized senders and does not require elevated.
+
+## Resolution order
+
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Global default (`agents.defaults.elevatedDefault` in config).
+
+## Setting a session default
+
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated full`.
+- Confirmation reply is sent (`Elevated mode set to full...` / `Elevated mode disabled.`).
+- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error and does not change session state.
+- Send `/elevated` (or `/elevated:`) with no argument to see the current elevated level.
+
+## Availability + allowlists
+
+- Feature gate: `tools.elevated.enabled` (default can be off via config even if the code supports it).
+- Sender allowlist: `tools.elevated.allowFrom` with per-provider allowlists (e.g. `discord`, `whatsapp`).
+- Per-agent gate: `agents.list[].tools.elevated.enabled` (optional; can only further restrict).
+- Per-agent allowlist: `agents.list[].tools.elevated.allowFrom` (optional; when set, the sender must match **both** global + per-agent allowlists).
+- Discord fallback: if `tools.elevated.allowFrom.discord` is omitted, the `channels.discord.dm.allowFrom` list is used as a fallback. Set `tools.elevated.allowFrom.discord` (even `[]`) to override. Per-agent allowlists do **not** use the fallback.
+- All gates must pass; otherwise elevated is treated as unavailable.
+
+## Logging + status
+
+- Elevated exec calls are logged at info level.
+- Session status includes elevated mode (e.g. `elevated=ask`, `elevated=full`).