silentlake 2026.3.24

package/docs/cli/approvals.md

@@ -0,0 +1,50 @@
+---
+summary: "CLI reference for `openclaw approvals` (exec approvals for gateway or node hosts)"
+read_when:
+  - You want to edit exec approvals from the CLI
+  - You need to manage allowlists on gateway or node hosts
+title: "approvals"
+---
+
+# `openclaw approvals`
+
+Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
+By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
+
+Related:
+
+- Exec approvals: [Exec approvals](/tools/exec-approvals)
+- Nodes: [Nodes](/nodes)
+
+## Common commands
+
+```bash
+openclaw approvals get
+openclaw approvals get --node <id|name|ip>
+openclaw approvals get --gateway
+```
+
+## Replace approvals from a file
+
+```bash
+openclaw approvals set --file ./exec-approvals.json
+openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
+openclaw approvals set --gateway --file ./exec-approvals.json
+```
+
+## Allowlist helpers
+
+```bash
+openclaw approvals allowlist add "~/Projects/**/bin/rg"
+openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
+openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
+
+openclaw approvals allowlist remove "~/Projects/**/bin/rg"
+```
+
+## Notes
+
+- `--node` uses the same resolver as `openclaw nodes` (id, name, ip, or id prefix).
+- `--agent` defaults to `"*"`, which applies to all agents.
+- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
+- Approvals files are stored per host at `~/.openclaw/exec-approvals.json`.

package/docs/cli/backup.md

@@ -0,0 +1,76 @@
+---
+summary: "CLI reference for `openclaw backup` (create local backup archives)"
+read_when:
+  - You want a first-class backup archive for local OpenClaw state
+  - You want to preview which paths would be included before reset or uninstall
+title: "backup"
+---
+
+# `openclaw backup`
+
+Create a local backup archive for OpenClaw state, config, credentials, sessions, and optionally workspaces.
+
+```bash
+openclaw backup create
+openclaw backup create --output ~/Backups
+openclaw backup create --dry-run --json
+openclaw backup create --verify
+openclaw backup create --no-include-workspace
+openclaw backup create --only-config
+openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
+```
+
+## Notes
+
+- The archive includes a `manifest.json` file with the resolved source paths and archive layout.
+- Default output is a timestamped `.tar.gz` archive in the current working directory.
+- If the current working directory is inside a backed-up source tree, OpenClaw falls back to your home directory for the default archive location.
+- Existing archive files are never overwritten.
+- Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
+- `openclaw backup verify <archive>` validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
+- `openclaw backup create --verify` runs that validation immediately after writing the archive.
+- `openclaw backup create --only-config` backs up just the active JSON config file.
+
+## What gets backed up
+
+`openclaw backup create` plans backup sources from your local OpenClaw install:
+
+- The state directory returned by OpenClaw's local state resolver, usually `~/.openclaw`
+- The active config file path
+- The OAuth / credentials directory
+- Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
+
+If you use `--only-config`, OpenClaw skips state, credentials, and workspace discovery and archives only the active config file path.
+
+OpenClaw canonicalizes paths before building the archive. If config, credentials, or a workspace already live inside the state directory, they are not duplicated as separate top-level backup sources. Missing paths are skipped.
+
+The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
+
+## Invalid config behavior
+
+`openclaw backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `openclaw backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.
+
+If you still want a partial backup in that situation, rerun:
+
+```bash
+openclaw backup create --no-include-workspace
+```
+
+That keeps state, config, and credentials in scope while skipping workspace discovery entirely.
+
+If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery.
+
+## Size and performance
+
+OpenClaw does not enforce a built-in maximum backup size or per-file size limit.
+
+Practical limits come from the local machine and destination filesystem:
+
+- Available space for the temporary archive write plus the final archive
+- Time to walk large workspace trees and compress them into a `.tar.gz`
+- Time to rescan the archive if you use `openclaw backup create --verify` or run `openclaw backup verify`
+- Filesystem behavior at the destination path. OpenClaw prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported
+
+Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
+
+For the smallest archive, use `--only-config`.

package/docs/cli/browser.md

@@ -0,0 +1,106 @@
+---
+summary: "CLI reference for `openclaw browser` (profiles, tabs, actions, Chrome MCP, and CDP)"
+read_when:
+  - You use `openclaw browser` and want examples for common tasks
+  - You want to control a browser running on another machine via a node host
+  - You want to attach to your local signed-in Chrome via Chrome MCP
+title: "browser"
+---
+
+# `openclaw browser`
+
+Manage OpenClaw’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
+
+Related:
+
+- Browser tool + API: [Browser tool](/tools/browser)
+
+## Common flags
+
+- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
+- `--token <token>`: Gateway token (if required).
+- `--timeout <ms>`: request timeout (ms).
+- `--browser-profile <name>`: choose a browser profile (default from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+openclaw browser profiles
+openclaw browser --browser-profile openclaw start
+openclaw browser --browser-profile openclaw open https://example.com
+openclaw browser --browser-profile openclaw snapshot
+```
+
+## Profiles
+
+Profiles are named browser routing configs. In practice:
+
+- `openclaw`: launches or attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
+- `user`: controls your existing signed-in Chrome session via Chrome DevTools MCP.
+- custom CDP profiles: point at a local or remote CDP endpoint.
+
+```bash
+openclaw browser profiles
+openclaw browser create-profile --name work --color "#FF5A36"
+openclaw browser create-profile --name chrome-live --driver existing-session
+openclaw browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+openclaw browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+openclaw browser tabs
+openclaw browser open https://docs.openclaw.ai
+openclaw browser focus <targetId>
+openclaw browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+openclaw browser snapshot
+```
+
+Screenshot:
+
+```bash
+openclaw browser screenshot
+```
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+openclaw browser navigate https://example.com
+openclaw browser click <ref>
+openclaw browser type <ref> "hello"
+```
+
+## Existing Chrome via MCP
+
+Use the built-in `user` profile, or create your own `existing-session` profile:
+
+```bash
+openclaw browser --browser-profile user tabs
+openclaw browser create-profile --name chrome-live --driver existing-session
+openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
+openclaw browser --browser-profile chrome-live tabs
+```
+
+This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
+
+## Remote browser control (node host proxy)
+
+If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).
+
+Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
+
+Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

package/docs/cli/channels.md

@@ -0,0 +1,102 @@
+---
+summary: "CLI reference for `openclaw channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage)
+  - You want to check channel status or tail channel logs
+title: "channels"
+---
+
+# `openclaw channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+openclaw channels list
+openclaw channels status
+openclaw channels capabilities
+openclaw channels capabilities --channel discord --target channel:123
+openclaw channels resolve --channel slack "#general" "@jane"
+openclaw channels logs --channel all
+```
+
+## Add / remove accounts
+
+```bash
+openclaw channels add --channel telegram --token <bot-token>
+openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
+openclaw channels remove --channel telegram --delete
+```
+
+Tip: `openclaw channels add --help` shows per-channel flags (token, private key, app token, signal-cli paths, etc).
+
+When you run `openclaw channels add` without flags, the interactive wizard can prompt:
+
+- account ids per selected channel
+- optional display names for those accounts
+- `Bind configured channel accounts to agents now?`
+
+If you confirm bind now, the wizard asks which agent should own each configured channel account and writes account-scoped routing bindings.
+
+You can also manage the same routing rules later with `openclaw agents bindings`, `openclaw agents bind`, and `openclaw agents unbind` (see [agents](/cli/agents)).
+
+When you add a non-default account to a channel that is still using single-account top-level settings (no `channels.<channel>.accounts` entries yet), OpenClaw moves account-scoped single-account top-level values into `channels.<channel>.accounts.default`, then writes the new account. This preserves the original account behavior while moving to the multi-account shape.
+
+Routing behavior stays consistent:
+
+- Existing channel-only bindings (no `accountId`) continue to match the default account.
+- `channels add` does not auto-create or rewrite bindings in non-interactive mode.
+- Interactive setup can optionally add account-scoped bindings.
+
+If your config was already in a mixed state (named accounts present, missing `default`, and top-level single-account values still set), run `openclaw doctor --fix` to move account-scoped values into `accounts.default`.
+
+## Login / logout (interactive)
+
+```bash
+openclaw channels login --channel whatsapp
+openclaw channels logout --channel whatsapp
+```
+
+## Troubleshooting
+
+- Run `openclaw status --deep` for a broad probe.
+- Use `openclaw doctor` for guided fixes.
+- `openclaw channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude Code CLI.
+- `openclaw channels status` falls back to config-only summaries when the gateway is unreachable. If a supported channel credential is configured via SecretRef but unavailable in the current command path, it reports that account as configured with degraded notes instead of showing it as not configured.
+
+## Capabilities probe
+
+Fetch provider capability hints (intents/scopes where available) plus static feature support:
+
+```bash
+openclaw channels capabilities
+openclaw channels capabilities --channel discord --target channel:123
+```
+
+Notes:
+
+- `--channel` is optional; omit it to list every channel (including extensions).
+- `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord.
+- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; Microsoft Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
+
+## Resolve names to IDs
+
+Resolve channel/user names to IDs using the provider directory:
+
+```bash
+openclaw channels resolve --channel slack "#general" "@jane"
+openclaw channels resolve --channel discord "My Server/#support" "@someone"
+openclaw channels resolve --channel matrix "Project Room"
+```
+
+Notes:
+
+- Use `--kind user|group|auto` to force the target type.
+- Resolution prefers active matches when multiple entries share the same name.
+- `channels resolve` is read-only. If a selected account is configured via SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting the entire run.

package/docs/cli/clawbot.md

@@ -0,0 +1,21 @@
+---
+summary: "CLI reference for `openclaw clawbot` (legacy alias namespace)"
+read_when:
+  - You maintain older scripts using `openclaw clawbot ...`
+  - You need migration guidance to current commands
+title: "clawbot"
+---
+
+# `openclaw clawbot`
+
+Legacy alias namespace kept for backwards compatibility.
+
+Current supported alias:
+
+- `openclaw clawbot qr` (same behavior as [`openclaw qr`](/cli/qr))
+
+## Migration
+
+Prefer modern top-level commands directly:
+
+- `openclaw clawbot qr` -> `openclaw qr`

package/docs/cli/completion.md

@@ -0,0 +1,35 @@
+---
+summary: "CLI reference for `openclaw completion` (generate/install shell completion scripts)"
+read_when:
+  - You want shell completions for zsh/bash/fish/PowerShell
+  - You need to cache completion scripts under OpenClaw state
+title: "completion"
+---
+
+# `openclaw completion`
+
+Generate shell completion scripts and optionally install them into your shell profile.
+
+## Usage
+
+```bash
+openclaw completion
+openclaw completion --shell zsh
+openclaw completion --install
+openclaw completion --shell fish --install
+openclaw completion --write-state
+openclaw completion --shell bash --write-state
+```
+
+## Options
+
+- `-s, --shell <shell>`: shell target (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`)
+- `-i, --install`: install completion by adding a source line to your shell profile
+- `--write-state`: write completion script(s) to `$OPENCLAW_STATE_DIR/completions` without printing to stdout
+- `-y, --yes`: skip install confirmation prompts
+
+## Notes
+
+- `--install` writes a small "OpenClaw Completion" block into your shell profile and points it at the cached script.
+- Without `--install` or `--write-state`, the command prints the script to stdout.
+- Completion generation eagerly loads command trees so nested subcommands are included.

package/docs/cli/config.md

@@ -0,0 +1,295 @@
+---
+summary: "CLI reference for `openclaw config` (get/set/unset/file/validate)"
+read_when:
+  - You want to read or edit config non-interactively
+title: "config"
+---
+
+# `openclaw config`
+
+Config helpers for non-interactive edits in `openclaw.json`: get/set/unset/validate
+values by path and print the active config file. Run without a subcommand to
+open the configure wizard (same as `openclaw configure`).
+
+## Examples
+
+```bash
+openclaw config file
+openclaw config get browser.executablePath
+openclaw config set browser.executablePath "/usr/bin/google-chrome"
+openclaw config set agents.defaults.heartbeat.every "2h"
+openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
+openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
+openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
+openclaw config unset plugins.entries.brave.config.webSearch.apiKey
+openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
+openclaw config validate
+openclaw config validate --json
+```
+
+## Paths
+
+Paths use dot or bracket notation:
+
+```bash
+openclaw config get agents.defaults.workspace
+openclaw config get agents.list[0].id
+```
+
+Use the agent list index to target a specific agent:
+
+```bash
+openclaw config get agents.list
+openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
+```
+
+## Values
+
+Values are parsed as JSON5 when possible; otherwise they are treated as strings.
+Use `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
+
+```bash
+openclaw config set agents.defaults.heartbeat.every "0m"
+openclaw config set gateway.port 19001 --strict-json
+openclaw config set channels.whatsapp.groups '["*"]' --strict-json
+```
+
+## `config set` modes
+
+`openclaw config set` supports four assignment styles:
+
+1. Value mode: `openclaw config set <path> <value>`
+2. SecretRef builder mode:
+
+```bash
+openclaw config set channels.discord.token \
+  --ref-provider default \
+  --ref-source env \
+  --ref-id DISCORD_BOT_TOKEN
+```
+
+3. Provider builder mode (`secrets.providers.<alias>` path only):
+
+```bash
+openclaw config set secrets.providers.vault \
+  --provider-source exec \
+  --provider-command /usr/local/bin/openclaw-vault \
+  --provider-arg read \
+  --provider-arg openai/api-key \
+  --provider-timeout-ms 5000
+```
+
+4. Batch mode (`--batch-json` or `--batch-file`):
+
+```bash
+openclaw config set --batch-json '[
+  {
+    "path": "secrets.providers.default",
+    "provider": { "source": "env" }
+  },
+  {
+    "path": "channels.discord.token",
+    "ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
+  }
+]'
+```
+
+```bash
+openclaw config set --batch-file ./config-set.batch.json --dry-run
+```
+
+Batch parsing always uses the batch payload (`--batch-json`/`--batch-file`) as the source of truth.
+`--strict-json` / `--json` do not change batch parsing behavior.
+
+JSON path/value mode remains supported for both SecretRefs and providers:
+
+```bash
+openclaw config set channels.discord.token \
+  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
+  --strict-json
+
+openclaw config set secrets.providers.vaultfile \
+  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
+  --strict-json
+```
+
+## Provider Builder Flags
+
+Provider builder targets must use `secrets.providers.<alias>` as the path.
+
+Common flags:
+
+- `--provider-source <env|file|exec>`
+- `--provider-timeout-ms <ms>` (`file`, `exec`)
+
+Env provider (`--provider-source env`):
+
+- `--provider-allowlist <ENV_VAR>` (repeatable)
+
+File provider (`--provider-source file`):
+
+- `--provider-path <path>` (required)
+- `--provider-mode <singleValue|json>`
+- `--provider-max-bytes <bytes>`
+
+Exec provider (`--provider-source exec`):
+
+- `--provider-command <path>` (required)
+- `--provider-arg <arg>` (repeatable)
+- `--provider-no-output-timeout-ms <ms>`
+- `--provider-max-output-bytes <bytes>`
+- `--provider-json-only`
+- `--provider-env <KEY=VALUE>` (repeatable)
+- `--provider-pass-env <ENV_VAR>` (repeatable)
+- `--provider-trusted-dir <path>` (repeatable)
+- `--provider-allow-insecure-path`
+- `--provider-allow-symlink-command`
+
+Hardened exec provider example:
+
+```bash
+openclaw config set secrets.providers.vault \
+  --provider-source exec \
+  --provider-command /usr/local/bin/openclaw-vault \
+  --provider-arg read \
+  --provider-arg openai/api-key \
+  --provider-json-only \
+  --provider-pass-env VAULT_TOKEN \
+  --provider-trusted-dir /usr/local/bin \
+  --provider-timeout-ms 5000
+```
+
+## Dry run
+
+Use `--dry-run` to validate changes without writing `openclaw.json`.
+
+```bash
+openclaw config set channels.discord.token \
+  --ref-provider default \
+  --ref-source env \
+  --ref-id DISCORD_BOT_TOKEN \
+  --dry-run
+
+openclaw config set channels.discord.token \
+  --ref-provider default \
+  --ref-source env \
+  --ref-id DISCORD_BOT_TOKEN \
+  --dry-run \
+  --json
+
+openclaw config set channels.discord.token \
+  --ref-provider vault \
+  --ref-source exec \
+  --ref-id discord/token \
+  --dry-run \
+  --allow-exec
+```
+
+Dry-run behavior:
+
+- Builder mode: runs SecretRef resolvability checks for changed refs/providers.
+- JSON mode (`--strict-json`, `--json`, or batch mode): runs schema validation plus SecretRef resolvability checks.
+- Exec SecretRef checks are skipped by default during dry-run to avoid command side effects.
+- Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
+- `--allow-exec` is dry-run only and errors if used without `--dry-run`.
+
+`--dry-run --json` prints a machine-readable report:
+
+- `ok`: whether dry-run passed
+- `operations`: number of assignments evaluated
+- `checks`: whether schema/resolvability checks ran
+- `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
+- `refsChecked`: number of refs actually resolved during dry-run
+- `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
+- `errors`: structured schema/resolvability failures when `ok=false`
+
+### JSON Output Shape
+
+```json5
+{
+  ok: boolean,
+  operations: number,
+  configPath: string,
+  inputModes: ["value" | "json" | "builder", ...],
+  checks: {
+    schema: boolean,
+    resolvability: boolean,
+    resolvabilityComplete: boolean,
+  },
+  refsChecked: number,
+  skippedExecRefs: number,
+  errors?: [
+    {
+      kind: "schema" | "resolvability",
+      message: string,
+      ref?: string, // present for resolvability errors
+    },
+  ],
+}
+```
+
+Success example:
+
+```json
+{
+  "ok": true,
+  "operations": 1,
+  "configPath": "~/.openclaw/openclaw.json",
+  "inputModes": ["builder"],
+  "checks": {
+    "schema": false,
+    "resolvability": true,
+    "resolvabilityComplete": true
+  },
+  "refsChecked": 1,
+  "skippedExecRefs": 0
+}
+```
+
+Failure example:
+
+```json
+{
+  "ok": false,
+  "operations": 1,
+  "configPath": "~/.openclaw/openclaw.json",
+  "inputModes": ["builder"],
+  "checks": {
+    "schema": false,
+    "resolvability": true,
+    "resolvabilityComplete": true
+  },
+  "refsChecked": 1,
+  "skippedExecRefs": 0,
+  "errors": [
+    {
+      "kind": "resolvability",
+      "message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
+      "ref": "env:default:MISSING_TEST_SECRET"
+    }
+  ]
+}
+```
+
+If dry-run fails:
+
+- `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
+- `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
+- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
+- For batch mode, fix failing entries and rerun `--dry-run` before writing.
+
+## Subcommands
+
+- `config file`: Print the active config file path (resolved from `OPENCLAW_CONFIG_PATH` or default location).
+
+Restart the gateway after edits.
+
+## Validate
+
+Validate the current config against the active schema without starting the
+gateway.
+
+```bash
+openclaw config validate
+openclaw config validate --json
+```