silentlake 2026.3.24

package/docs/cli/onboard.md

@@ -0,0 +1,157 @@
+---
+summary: "CLI reference for `openclaw onboard` (interactive onboarding)"
+read_when:
+  - You want guided setup for gateway, workspace, auth, channels, and skills
+title: "onboard"
+---
+
+# `openclaw onboard`
+
+Interactive onboarding for local or remote Gateway setup.
+
+## Related guides
+
+- CLI onboarding hub: [Onboarding (CLI)](/start/wizard)
+- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
+- CLI onboarding reference: [CLI Setup Reference](/start/wizard-cli-reference)
+- CLI automation: [CLI Automation](/start/wizard-cli-automation)
+- macOS onboarding: [Onboarding (macOS App)](/start/onboarding)
+
+## Examples
+
+```bash
+openclaw onboard
+openclaw onboard --flow quickstart
+openclaw onboard --flow manual
+openclaw onboard --mode remote --remote-url wss://gateway-host:18789
+```
+
+For plaintext private-network `ws://` targets (trusted networks only), set
+`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` in the onboarding process environment.
+
+Non-interactive custom provider:
+
+```bash
+openclaw onboard --non-interactive \
+  --auth-choice custom-api-key \
+  --custom-base-url "https://llm.example.com/v1" \
+  --custom-model-id "foo-large" \
+  --custom-api-key "$CUSTOM_API_KEY" \
+  --secret-input-mode plaintext \
+  --custom-compatibility openai
+```
+
+`--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`.
+
+Non-interactive Ollama:
+
+```bash
+openclaw onboard --non-interactive \
+  --auth-choice ollama \
+  --custom-base-url "http://ollama-host:11434" \
+  --custom-model-id "qwen3.5:27b" \
+  --accept-risk
+```
+
+`--custom-base-url` defaults to `http://127.0.0.1:11434`. `--custom-model-id` is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as `kimi-k2.5:cloud` also work here.
+
+Store provider keys as refs instead of plaintext:
+
+```bash
+openclaw onboard --non-interactive \
+  --auth-choice openai-api-key \
+  --secret-input-mode ref \
+  --accept-risk
+```
+
+With `--secret-input-mode ref`, onboarding writes env-backed refs instead of plaintext key values.
+For auth-profile backed providers this writes `keyRef` entries; for custom providers this writes `models.providers.<id>.apiKey` as an env ref (for example `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
+
+Non-interactive `ref` mode contract:
+
+- Set the provider env var in the onboarding process environment (for example `OPENAI_API_KEY`).
+- Do not pass inline key flags (for example `--openai-api-key`) unless that env var is also set.
+- If an inline key flag is passed without the required env var, onboarding fails fast with guidance.
+
+Gateway token options in non-interactive mode:
+
+- `--gateway-auth token --gateway-token <token>` stores a plaintext token.
+- `--gateway-auth token --gateway-token-ref-env <name>` stores `gateway.auth.token` as an env SecretRef.
+- `--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
+- `--gateway-token-ref-env` requires a non-empty env var in the onboarding process environment.
+- With `--install-daemon`, when token auth requires a token, SecretRef-managed gateway tokens are validated but not persisted as resolved plaintext in supervisor service environment metadata.
+- With `--install-daemon`, if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
+- With `--install-daemon`, if both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, onboarding blocks install until mode is set explicitly.
+
+Example:
+
+```bash
+export OPENCLAW_GATEWAY_TOKEN="your-token"
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice skip \
+  --gateway-auth token \
+  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
+  --accept-risk
+```
+
+Non-interactive local gateway health:
+
+- Unless you pass `--skip-health`, onboarding waits for a reachable local gateway before it exits successfully.
+- `--install-daemon` starts the managed gateway install path first. Without it, you must already have a local gateway running, for example `openclaw gateway run`.
+- If you only want config/workspace/bootstrap writes in automation, use `--skip-health`.
+- On native Windows, `--install-daemon` tries Scheduled Tasks first and falls back to a per-user Startup-folder login item if task creation is denied.
+
+Interactive onboarding behavior with reference mode:
+
+- Choose **Use secret reference** when prompted.
+- Then choose either:
+  - Environment variable
+  - Configured secret provider (`file` or `exec`)
+- Onboarding performs a fast preflight validation before saving the ref.
+  - If validation fails, onboarding shows the error and lets you retry.
+
+Non-interactive Z.AI endpoint choices:
+
+Note: `--auth-choice zai-api-key` now auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5`).
+If you specifically want the GLM Coding Plan endpoints, pick `zai-coding-global` or `zai-coding-cn`.
+
+```bash
+# Promptless endpoint selection
+openclaw onboard --non-interactive \
+  --auth-choice zai-coding-global \
+  --zai-api-key "$ZAI_API_KEY"
+
+# Other Z.AI endpoint choices:
+# --auth-choice zai-coding-cn
+# --auth-choice zai-global
+# --auth-choice zai-cn
+```
+
+Non-interactive Mistral example:
+
+```bash
+openclaw onboard --non-interactive \
+  --auth-choice mistral-api-key \
+  --mistral-api-key "$MISTRAL_API_KEY"
+```
+
+Flow notes:
+
+- `quickstart`: minimal prompts, auto-generates a gateway token.
+- `manual`: full prompts for port/bind/auth (alias of `advanced`).
+- Local onboarding DM scope behavior: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals).
+- Fastest first chat: `openclaw dashboard` (Control UI, no channel setup).
+- Custom Provider: connect any OpenAI or Anthropic compatible endpoint,
+  including hosted providers not listed. Use Unknown to auto-detect.
+
+## Common follow-up commands
+
+```bash
+openclaw configure
+openclaw agents add <name>
+```
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
+</Note>

package/docs/cli/pairing.md

@@ -0,0 +1,32 @@
+---
+summary: "CLI reference for `openclaw pairing` (approve/list pairing requests)"
+read_when:
+  - You’re using pairing-mode DMs and need to approve senders
+title: "pairing"
+---
+
+# `openclaw pairing`
+
+Approve or inspect DM pairing requests (for channels that support pairing).
+
+Related:
+
+- Pairing flow: [Pairing](/channels/pairing)
+
+## Commands
+
+```bash
+openclaw pairing list telegram
+openclaw pairing list --channel telegram --account work
+openclaw pairing list telegram --json
+
+openclaw pairing approve telegram <code>
+openclaw pairing approve --channel telegram --account work <code> --notify
+```
+
+## Notes
+
+- Channel input: pass it positionally (`pairing list telegram`) or with `--channel <channel>`.
+- `pairing list` supports `--account <accountId>` for multi-account channels.
+- `pairing approve` supports `--account <accountId>` and `--notify`.
+- If only one pairing-capable channel is configured, `pairing approve <code>` is allowed.

package/docs/cli/plugins.md

@@ -0,0 +1,186 @@
+---
+summary: "CLI reference for `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)"
+read_when:
+  - You want to install or manage Gateway plugins or compatible bundles
+  - You want to debug plugin load failures
+title: "plugins"
+---
+
+# `openclaw plugins`
+
+Manage Gateway plugins/extensions and compatible bundles.
+
+Related:
+
+- Plugin system: [Plugins](/tools/plugin)
+- Bundle compatibility: [Plugin bundles](/plugins/bundles)
+- Plugin manifest + schema: [Plugin manifest](/plugins/manifest)
+- Security hardening: [Security](/gateway/security)
+
+## Commands
+
+```bash
+openclaw plugins list
+openclaw plugins install <path-or-spec>
+openclaw plugins inspect <id>
+openclaw plugins enable <id>
+openclaw plugins disable <id>
+openclaw plugins uninstall <id>
+openclaw plugins doctor
+openclaw plugins update <id>
+openclaw plugins update --all
+openclaw plugins marketplace list <marketplace>
+```
+
+Bundled plugins ship with OpenClaw but start disabled. Use `plugins enable` to
+activate them.
+
+Native OpenClaw plugins must ship `openclaw.plugin.json` with an inline JSON
+Schema (`configSchema`, even if empty). Compatible bundles use their own bundle
+manifests instead.
+
+`plugins list` shows `Format: openclaw` or `Format: bundle`. Verbose list/info
+output also shows the bundle subtype (`codex`, `claude`, or `cursor`) plus detected bundle
+capabilities.
+
+### Install
+
+```bash
+openclaw plugins install <path-or-spec>
+openclaw plugins install <npm-spec> --pin
+openclaw plugins install <plugin>@<marketplace>
+openclaw plugins install <plugin> --marketplace <marketplace>
+```
+
+Security note: treat plugin installs like running code. Prefer pinned versions.
+
+Npm specs are **registry-only** (package name + optional **exact version** or
+**dist-tag**). Git/URL/file specs and semver ranges are rejected. Dependency
+installs run with `--ignore-scripts` for safety.
+
+Bare specs and `@latest` stay on the stable track. If npm resolves either of
+those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a
+prerelease tag such as `@beta`/`@rc` or an exact prerelease version such as
+`@1.2.3-beta.4`.
+
+If a bare install spec matches a bundled plugin id (for example `diffs`), OpenClaw
+installs the bundled plugin directly. To install an npm package with the same
+name, use an explicit scoped spec (for example `@scope/diffs`).
+
+Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
+
+Claude marketplace installs are also supported.
+
+Use `plugin@marketplace` shorthand when the marketplace name exists in Claude's
+local registry cache at `~/.claude/plugins/known_marketplaces.json`:
+
+```bash
+openclaw plugins marketplace list <marketplace-name>
+openclaw plugins install <plugin-name>@<marketplace-name>
+```
+
+Use `--marketplace` when you want to pass the marketplace source explicitly:
+
+```bash
+openclaw plugins install <plugin-name> --marketplace <marketplace-name>
+openclaw plugins install <plugin-name> --marketplace <owner/repo>
+openclaw plugins install <plugin-name> --marketplace ./my-marketplace
+```
+
+Marketplace sources can be:
+
+- a Claude known-marketplace name from `~/.claude/plugins/known_marketplaces.json`
+- a local marketplace root or `marketplace.json` path
+- a GitHub repo shorthand such as `owner/repo`
+- a git URL
+
+For local paths and archives, OpenClaw auto-detects:
+
+- native OpenClaw plugins (`openclaw.plugin.json`)
+- Codex-compatible bundles (`.codex-plugin/plugin.json`)
+- Claude-compatible bundles (`.claude-plugin/plugin.json` or the default Claude
+  component layout)
+- Cursor-compatible bundles (`.cursor-plugin/plugin.json`)
+
+Compatible bundles install into the normal extensions root and participate in
+the same list/info/enable/disable flow. Today, bundle skills, Claude
+command-skills, Claude `settings.json` defaults, Cursor command-skills, and compatible Codex hook
+directories are supported; other detected bundle capabilities are shown in
+diagnostics/info but are not yet wired into runtime execution.
+
+Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
+
+```bash
+openclaw plugins install -l ./my-plugin
+```
+
+Use `--pin` on npm installs to save the resolved exact spec (`name@version`) in
+`plugins.installs` while keeping the default behavior unpinned.
+
+### Uninstall
+
+```bash
+openclaw plugins uninstall <id>
+openclaw plugins uninstall <id> --dry-run
+openclaw plugins uninstall <id> --keep-files
+```
+
+`uninstall` removes plugin records from `plugins.entries`, `plugins.installs`,
+the plugin allowlist, and linked `plugins.load.paths` entries when applicable.
+For active memory plugins, the memory slot resets to `memory-core`.
+
+By default, uninstall also removes the plugin install directory under the active
+state dir extensions root (`$OPENCLAW_STATE_DIR/extensions/<id>`). Use
+`--keep-files` to keep files on disk.
+
+`--keep-config` is supported as a deprecated alias for `--keep-files`.
+
+### Update
+
+```bash
+openclaw plugins update <id-or-npm-spec>
+openclaw plugins update --all
+openclaw plugins update <id-or-npm-spec> --dry-run
+openclaw plugins update @openclaw/voice-call@beta
+```
+
+Updates apply to tracked installs in `plugins.installs`, currently npm and
+marketplace installs.
+
+When you pass a plugin id, OpenClaw reuses the recorded install spec for that
+plugin. That means previously stored dist-tags such as `@beta` and exact pinned
+versions continue to be used on later `update <id>` runs.
+
+For npm installs, you can also pass an explicit npm package spec with a dist-tag
+or exact version. OpenClaw resolves that package name back to the tracked plugin
+record, updates that installed plugin, and records the new npm spec for future
+id-based updates.
+
+When a stored integrity hash exists and the fetched artifact hash changes,
+OpenClaw prints a warning and asks for confirmation before proceeding. Use
+global `--yes` to bypass prompts in CI/non-interactive runs.
+
+### Inspect
+
+```bash
+openclaw plugins inspect <id>
+openclaw plugins inspect <id> --json
+```
+
+Deep introspection for a single plugin. Shows identity, load status, source,
+registered capabilities, hooks, tools, commands, services, gateway methods,
+HTTP routes, policy flags, diagnostics, and install metadata.
+
+Each plugin is classified by what it actually registers at runtime:
+
+- **plain-capability** — one capability type (e.g. a provider-only plugin)
+- **hybrid-capability** — multiple capability types (e.g. text + speech + images)
+- **hook-only** — only hooks, no capabilities or surfaces
+- **non-capability** — tools/commands/services but no capabilities
+
+See [Plugin shapes](/plugins/architecture#plugin-shapes) for more on the capability model.
+
+The `--json` flag outputs a machine-readable report suitable for scripting and
+auditing.
+
+`info` is an alias for `inspect`.

package/docs/cli/qr.md

@@ -0,0 +1,46 @@
+---
+summary: "CLI reference for `openclaw qr` (generate iOS pairing QR + setup code)"
+read_when:
+  - You want to pair the iOS app with a gateway quickly
+  - You need setup-code output for remote/manual sharing
+title: "qr"
+---
+
+# `openclaw qr`
+
+Generate an iOS pairing QR and setup code from your current Gateway configuration.
+
+## Usage
+
+```bash
+openclaw qr
+openclaw qr --setup-code-only
+openclaw qr --json
+openclaw qr --remote
+openclaw qr --url wss://gateway.example/ws
+```
+
+## Options
+
+- `--remote`: use `gateway.remote.url` plus remote token/password from config
+- `--url <url>`: override gateway URL used in payload
+- `--public-url <url>`: override public URL used in payload
+- `--token <token>`: override which gateway token the bootstrap flow authenticates against
+- `--password <password>`: override which gateway password the bootstrap flow authenticates against
+- `--setup-code-only`: print only setup code
+- `--no-ascii`: skip ASCII QR rendering
+- `--json`: emit JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
+
+## Notes
+
+- `--token` and `--password` are mutually exclusive.
+- The setup code itself now carries an opaque short-lived `bootstrapToken`, not the shared gateway token/password.
+- With `--remote`, if effectively active remote credentials are configured as SecretRefs and you do not pass `--token` or `--password`, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
+- Without `--remote`, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
+  - `gateway.auth.token` resolves when token auth can win (explicit `gateway.auth.mode="token"` or inferred mode where no password source wins).
+  - `gateway.auth.password` resolves when password auth can win (explicit `gateway.auth.mode="password"` or inferred mode with no winning token from auth/env).
+- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs) and `gateway.auth.mode` is unset, setup-code resolution fails until mode is set explicitly.
+- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
+- After scanning, approve device pairing with:
+  - `openclaw devices list`
+  - `openclaw devices approve <requestId>`

package/docs/cli/reset.md

@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `openclaw reset` (reset local state/config)"
+read_when:
+  - You want to wipe local state while keeping the CLI installed
+  - You want a dry-run of what would be removed
+title: "reset"
+---
+
+# `openclaw reset`
+
+Reset local config/state (keeps the CLI installed).
+
+```bash
+openclaw backup create
+openclaw reset
+openclaw reset --dry-run
+openclaw reset --scope config+creds+sessions --yes --non-interactive
+```
+
+Run `openclaw backup create` first if you want a restorable snapshot before removing local state.

package/docs/cli/sandbox.md

@@ -0,0 +1,197 @@
+---
+title: Sandbox CLI
+summary: "Manage sandbox runtimes and inspect effective sandbox policy"
+read_when: "You are managing sandbox runtimes or debugging sandbox/tool-policy behavior."
+status: active
+---
+
+# Sandbox CLI
+
+Manage sandbox runtimes for isolated agent execution.
+
+## Overview
+
+OpenClaw can run agents in isolated sandbox runtimes for security. The `sandbox` commands help you inspect and recreate those runtimes after updates or configuration changes.
+
+Today that usually means:
+
+- Docker sandbox containers
+- SSH sandbox runtimes when `agents.defaults.sandbox.backend = "ssh"`
+- OpenShell sandbox runtimes when `agents.defaults.sandbox.backend = "openshell"`
+
+For `ssh` and OpenShell `remote`, recreate matters more than with Docker:
+
+- the remote workspace is canonical after the initial seed
+- `openclaw sandbox recreate` deletes that canonical remote workspace for the selected scope
+- next use seeds it again from the current local workspace
+
+## Commands
+
+### `openclaw sandbox explain`
+
+Inspect the **effective** sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).
+
+```bash
+openclaw sandbox explain
+openclaw sandbox explain --session agent:main:main
+openclaw sandbox explain --agent work
+openclaw sandbox explain --json
+```
+
+### `openclaw sandbox list`
+
+List all sandbox runtimes with their status and configuration.
+
+```bash
+openclaw sandbox list
+openclaw sandbox list --browser  # List only browser containers
+openclaw sandbox list --json     # JSON output
+```
+
+**Output includes:**
+
+- Runtime name and status
+- Backend (`docker`, `openshell`, etc.)
+- Config label and whether it matches current config
+- Age (time since creation)
+- Idle time (time since last use)
+- Associated session/agent
+
+### `openclaw sandbox recreate`
+
+Remove sandbox runtimes to force recreation with updated config.
+
+```bash
+openclaw sandbox recreate --all                # Recreate all containers
+openclaw sandbox recreate --session main       # Specific session
+openclaw sandbox recreate --agent mybot        # Specific agent
+openclaw sandbox recreate --browser            # Only browser containers
+openclaw sandbox recreate --all --force        # Skip confirmation
+```
+
+**Options:**
+
+- `--all`: Recreate all sandbox containers
+- `--session <key>`: Recreate container for specific session
+- `--agent <id>`: Recreate containers for specific agent
+- `--browser`: Only recreate browser containers
+- `--force`: Skip confirmation prompt
+
+**Important:** Runtimes are automatically recreated when the agent is next used.
+
+## Use Cases
+
+### After updating a Docker image
+
+```bash
+# Pull new image
+docker pull openclaw-sandbox:latest
+docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
+
+# Update config to use new image
+# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
+
+# Recreate containers
+openclaw sandbox recreate --all
+```
+
+### After changing sandbox configuration
+
+```bash
+# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
+
+# Recreate to apply new config
+openclaw sandbox recreate --all
+```
+
+### After changing SSH target or SSH auth material
+
+```bash
+# Edit config:
+# - agents.defaults.sandbox.backend
+# - agents.defaults.sandbox.ssh.target
+# - agents.defaults.sandbox.ssh.workspaceRoot
+# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
+# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
+
+openclaw sandbox recreate --all
+```
+
+For the core `ssh` backend, recreate deletes the per-scope remote workspace root
+on the SSH target. The next run seeds it again from the local workspace.
+
+### After changing OpenShell source, policy, or mode
+
+```bash
+# Edit config:
+# - agents.defaults.sandbox.backend
+# - plugins.entries.openshell.config.from
+# - plugins.entries.openshell.config.mode
+# - plugins.entries.openshell.config.policy
+
+openclaw sandbox recreate --all
+```
+
+For OpenShell `remote` mode, recreate deletes the canonical remote workspace
+for that scope. The next run seeds it again from the local workspace.
+
+### After changing setupCommand
+
+```bash
+openclaw sandbox recreate --all
+# or just one agent:
+openclaw sandbox recreate --agent family
+```
+
+### For a specific agent only
+
+```bash
+# Update only one agent's containers
+openclaw sandbox recreate --agent alfred
+```
+
+## Why is this needed?
+
+**Problem:** When you update sandbox configuration:
+
+- Existing runtimes continue running with old settings
+- Runtimes are only pruned after 24h of inactivity
+- Regularly-used agents keep old runtimes alive indefinitely
+
+**Solution:** Use `openclaw sandbox recreate` to force removal of old runtimes. They'll be recreated automatically with current settings when next needed.
+
+Tip: prefer `openclaw sandbox recreate` over manual backend-specific cleanup.
+It uses the Gateway’s runtime registry and avoids mismatches when scope/session keys change.
+
+## Configuration
+
+Sandbox settings live in `~/.openclaw/openclaw.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):
+
+```jsonc
+{
+  "agents": {
+    "defaults": {
+      "sandbox": {
+        "mode": "all", // off, non-main, all
+        "backend": "docker", // docker, ssh, openshell
+        "scope": "agent", // session, agent, shared
+        "docker": {
+          "image": "openclaw-sandbox:bookworm-slim",
+          "containerPrefix": "openclaw-sbx-",
+          // ... more Docker options
+        },
+        "prune": {
+          "idleHours": 24, // Auto-prune after 24h idle
+          "maxAgeDays": 7, // Auto-prune after 7 days
+        },
+      },
+    },
+  },
+}
+```
+
+## See Also
+
+- [Sandbox Documentation](/gateway/sandboxing)
+- [Agent Configuration](/concepts/agent-workspace)
+- [Doctor Command](/gateway/doctor) - Check sandbox setup