vilvona 1.0.0

package/docs/cli/proxy.md

@@ -0,0 +1,89 @@
+---
+summary: "CLI reference for `openclaw proxy`, including operator-managed proxy validation and the local debug proxy capture inspector"
+read_when:
+  - You need to validate operator-managed proxy routing before deployment
+  - You need to capture OpenClaw transport traffic locally for debugging
+  - You want to inspect debug proxy sessions, blobs, or built-in query presets
+title: "Proxy"
+---
+
+# `openclaw proxy`
+
+Validate operator-managed proxy routing, or run the local explicit debug proxy
+and inspect captured traffic.
+
+Use `validate` to preflight an operator-managed forward proxy before enabling
+OpenClaw proxy routing. The other commands are debugging tools for
+transport-level investigation: they can start a local proxy, run a child command
+with capture enabled, list capture sessions, query common traffic patterns, read
+captured blobs, and purge local capture data.
+
+## Commands
+
+```bash
+openclaw proxy start [--host <host>] [--port <port>]
+openclaw proxy run [--host <host>] [--port <port>] -- <cmd...>
+openclaw proxy validate [--json] [--proxy-url <url>] [--proxy-ca-file <path>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
+openclaw proxy coverage
+openclaw proxy sessions [--limit <count>]
+openclaw proxy query --preset <name> [--session <id>]
+openclaw proxy blob --id <blobId>
+openclaw proxy purge
+```
+
+## Validate
+
+`openclaw proxy validate` checks the effective operator-managed proxy URL from
+`--proxy-url`, config, or `OPENCLAW_PROXY_URL`. Managed proxy URLs can use
+`http://` for a plain forward-proxy listener or `https://` when OpenClaw must
+open TLS to the proxy endpoint before sending proxy requests. It reports a
+config problem when no proxy is enabled and configured; use `--proxy-url` for a
+one-off preflight before changing config. Add `--proxy-ca-file` to trust a
+private CA for the TLS connection to an HTTPS proxy endpoint. By default it
+verifies that a public destination succeeds through the proxy and that the proxy
+cannot reach a temporary loopback canary. Custom denied destinations are
+fail-closed: HTTP responses and ambiguous transport failures both fail unless
+you can verify a deployment-specific denial signal separately. Add
+`--apns-reachable` to also open an APNs HTTP/2 CONNECT tunnel through the proxy
+and confirm sandbox APNs responds; the probe uses an intentionally invalid
+provider token, so an APNs `403 InvalidProviderToken` response is a successful
+reachability signal.
+
+Options:
+
+- `--json`: print machine-readable JSON.
+- `--proxy-url <url>`: validate this `http://` or `https://` proxy URL instead of config or env.
+- `--proxy-ca-file <path>`: trust this PEM CA file for TLS verification of an HTTPS proxy endpoint.
+- `--allowed-url <url>`: add a destination expected to succeed through the proxy. Repeat to check multiple destinations.
+- `--denied-url <url>`: add a destination expected to be blocked by the proxy. Repeat to check multiple destinations.
+- `--apns-reachable`: also verify sandbox APNs HTTP/2 is reachable through the proxy.
+- `--apns-authority <url>`: APNs authority to probe with `--apns-reachable` (`https://api.sandbox.push.apple.com` by default; production is `https://api.push.apple.com`).
+- `--timeout-ms <ms>`: per-request timeout in milliseconds.
+
+See [Network Proxy](/security/network-proxy) for deployment guidance and denial
+semantics.
+
+## Query presets
+
+`openclaw proxy query --preset <name>` accepts:
+
+- `double-sends`
+- `retry-storms`
+- `cache-busting`
+- `ws-duplicate-frames`
+- `missing-ack`
+- `error-bursts`
+
+## Notes
+
+- `start` defaults to `127.0.0.1` unless `--host` is set.
+- `run` starts a local debug proxy and then runs the command after `--`.
+- The debug proxy's direct upstream forwarding opens upstream sockets for diagnostics. When OpenClaw managed proxy mode is active, direct forwarding for proxy requests and CONNECT tunnels is disabled by default; set `OPENCLAW_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1` only for approved local diagnostics.
+- `validate` exits with code 1 when proxy config or destination checks fail.
+- Captures are local debugging data; use `openclaw proxy purge` when finished.
+
+## Related
+
+- [CLI reference](/cli)
+- [Network Proxy](/security/network-proxy)
+- [Trusted proxy auth](/gateway/trusted-proxy-auth)

package/docs/cli/qr.md

@@ -0,0 +1,56 @@
+---
+summary: "CLI reference for `openclaw qr` (generate mobile pairing QR + setup code)"
+read_when:
+  - You want to pair a mobile node app with a gateway quickly
+  - You need setup-code output for remote/manual sharing
+title: "QR"
+---
+
+# `openclaw qr`
+
+Generate a mobile 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`: prefer `gateway.remote.url`; if it is unset, `gateway.tailscale.mode=serve|funnel` can still provide the remote public URL
+- `--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.
+- Built-in setup-code bootstrap returns a primary `node` token with `scopes: []` plus a bounded `operator` handoff token for trusted mobile onboarding.
+- The handed-off operator token is limited to `operator.approvals`, `operator.read`, `operator.talk.secrets`, and `operator.write`; `operator.admin` and `operator.pairing` require a separate approved operator pairing or token flow.
+- Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN addresses and `.local` Bonjour hosts remain supported over `ws://`, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a `wss://` gateway URL.
+- With `--remote`, OpenClaw requires either `gateway.remote.url` or
+  `gateway.tailscale.mode=serve|funnel`.
+- 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>`
+
+## Related
+
+- [CLI reference](/cli)
+- [Pairing](/cli/pairing)

package/docs/cli/reset.md

@@ -0,0 +1,39 @@
+---
+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).
+
+Options:
+
+- `--scope <scope>`: `config`, `config+creds+sessions`, or `full`
+- `--yes`: skip confirmation prompts
+- `--non-interactive`: disable prompts; requires `--scope` and `--yes`
+- `--dry-run`: print actions without removing files
+
+Examples:
+
+```bash
+openclaw backup create
+openclaw reset
+openclaw reset --dry-run
+openclaw reset --scope config --yes --non-interactive
+openclaw reset --scope config+creds+sessions --yes --non-interactive
+openclaw reset --scope full --yes --non-interactive
+```
+
+Notes:
+
+- Run `openclaw backup create` first if you want a restorable snapshot before removing local state.
+- If you omit `--scope`, `openclaw reset` uses an interactive prompt to choose what to remove.
+- `--non-interactive` is only valid when both `--scope` and `--yes` are set.
+
+## Related
+
+- [CLI reference](/cli)

package/docs/cli/sandbox.md

@@ -0,0 +1,208 @@
+---
+summary: "Manage sandbox runtimes and inspect effective sandbox policy"
+title: Sandbox CLI
+read_when: "You are managing sandbox runtimes or debugging sandbox/tool-policy behavior."
+status: active
+---
+
+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
+
+<Note>
+Runtimes are automatically recreated when the agent is next used.
+</Note>
+
+## 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 this is needed
+
+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.
+
+Use `openclaw sandbox recreate` to force removal of old runtimes. They are 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 or session keys change.
+</Tip>
+
+## Registry migration
+
+OpenClaw stores sandbox runtime metadata in the shared SQLite state database. Older installs may still have legacy sandbox registry files:
+
+- `~/.openclaw/sandbox/containers.json`
+- `~/.openclaw/sandbox/browsers.json`
+
+Some upgrades may also have one JSON shard per container/browser under `~/.openclaw/sandbox/containers/` or `~/.openclaw/sandbox/browsers/`. Regular sandbox runtime reads do not rewrite those legacy sources. Run `openclaw doctor --fix` to migrate valid legacy entries into SQLite. Invalid legacy files are quarantined so one bad old registry cannot hide current runtime entries.
+
+## 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
+        },
+      },
+    },
+  },
+}
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Sandboxing](/gateway/sandboxing)
+- [Agent workspace](/concepts/agent-workspace)
+- [Doctor](/gateway/doctor): checks sandbox setup.

package/docs/cli/secrets.md

@@ -0,0 +1,202 @@
+---
+summary: "CLI reference for `openclaw secrets` (reload, audit, configure, apply)"
+read_when:
+  - Re-resolving secret refs at runtime
+  - Auditing plaintext residues and unresolved refs
+  - Configuring SecretRefs and applying one-way scrub changes
+title: "Secrets"
+---
+
+# `openclaw secrets`
+
+Use `openclaw secrets` to manage SecretRefs and keep the active runtime snapshot healthy.
+
+Command roles:
+
+- `reload`: gateway RPC (`secrets.reload`) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
+- `audit`: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless `--allow-exec` is set).
+- `configure`: interactive planner for provider setup, target mapping, and preflight (TTY required).
+- `apply`: execute a saved plan (`--dry-run` for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless `--allow-exec` is set), then scrub targeted plaintext residues.
+
+Recommended operator loop:
+
+```bash
+openclaw secrets audit --check
+openclaw secrets configure
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
+openclaw secrets audit --check
+openclaw secrets reload
+```
+
+If your plan includes `exec` SecretRefs/providers, pass `--allow-exec` on both dry-run and write apply commands.
+
+Exit code note for CI/gates:
+
+- `audit --check` returns `1` on findings.
+- unresolved refs return `2`.
+
+Related:
+
+- Secrets guide: [Secrets Management](/gateway/secrets)
+- Credential surface: [SecretRef Credential Surface](/reference/secretref-credential-surface)
+- Security guide: [Security](/gateway/security)
+
+## Reload runtime snapshot
+
+Re-resolve secret refs and atomically swap runtime snapshot.
+
+```bash
+openclaw secrets reload
+openclaw secrets reload --json
+openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
+```
+
+Notes:
+
+- Uses gateway RPC method `secrets.reload`.
+- If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).
+- JSON response includes `warningCount`.
+
+Options:
+
+- `--url <url>`
+- `--token <token>`
+- `--timeout <ms>`
+- `--json`
+
+## Audit
+
+Scan OpenClaw state for:
+
+- plaintext secret storage
+- unresolved refs
+- precedence drift (`auth-profiles.json` credentials shadowing `openclaw.json` refs)
+- generated `agents/*/agent/models.json` residues (provider `apiKey` values and sensitive provider headers)
+- legacy residues (legacy auth store entries, OAuth reminders)
+
+Header residue note:
+
+- Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).
+
+```bash
+openclaw secrets audit
+openclaw secrets audit --check
+openclaw secrets audit --json
+openclaw secrets audit --allow-exec
+```
+
+Exit behavior:
+
+- `--check` exits non-zero on findings.
+- unresolved refs exit with higher-priority non-zero code.
+
+Report shape highlights:
+
+- `status`: `clean | findings | unresolved`
+- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
+- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
+- finding codes:
+  - `PLAINTEXT_FOUND`
+  - `REF_UNRESOLVED`
+  - `REF_SHADOWED`
+  - `LEGACY_RESIDUE`
+
+## Configure (interactive helper)
+
+Build provider and SecretRef changes interactively, run preflight, and optionally apply:
+
+```bash
+openclaw secrets configure
+openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
+openclaw secrets configure --apply --yes
+openclaw secrets configure --providers-only
+openclaw secrets configure --skip-provider-setup
+openclaw secrets configure --agent ops
+openclaw secrets configure --json
+```
+
+Flow:
+
+- Provider setup first (`add/edit/remove` for `secrets.providers` aliases).
+- Credential mapping second (select fields and assign `{source, provider, id}` refs).
+- Preflight and optional apply last.
+
+Flags:
+
+- `--providers-only`: configure `secrets.providers` only, skip credential mapping.
+- `--skip-provider-setup`: skip provider setup and map credentials to existing providers.
+- `--agent <id>`: scope `auth-profiles.json` target discovery and writes to one agent store.
+- `--allow-exec`: allow exec SecretRef checks during preflight/apply (may execute provider commands).
+
+Notes:
+
+- Requires an interactive TTY.
+- You cannot combine `--providers-only` with `--skip-provider-setup`.
+- `configure` targets secret-bearing fields in `openclaw.json` plus `auth-profiles.json` for the selected agent scope.
+- `configure` supports creating new `auth-profiles.json` mappings directly in the picker flow.
+- Canonical supported surface: [SecretRef Credential Surface](/reference/secretref-credential-surface).
+- It performs preflight resolution before apply.
+- If preflight/apply includes exec refs, keep `--allow-exec` set for both steps.
+- Generated plans default to scrub options (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` all enabled).
+- Apply path is one-way for scrubbed plaintext values.
+- Without `--apply`, CLI still prompts `Apply this plan now?` after preflight.
+- With `--apply` (and no `--yes`), CLI prompts an extra irreversible confirmation.
+- `--json` prints the plan + preflight report, but the command still requires an interactive TTY.
+
+Exec provider safety note:
+
+- Homebrew installs often expose symlinked binaries under `/opt/homebrew/bin/*`.
+- Set `allowSymlinkCommand: true` only when needed for trusted package-manager paths, and pair it with `trustedDirs` (for example `["/opt/homebrew"]`).
+- On Windows, if ACL verification is unavailable for a provider path, OpenClaw fails closed. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.
+
+## Apply a saved plan
+
+Apply or preflight a plan generated previously:
+
+```bash
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
+openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
+```
+
+Exec behavior:
+
+- `--dry-run` validates preflight without writing files.
+- exec SecretRef checks are skipped by default in dry-run.
+- write mode rejects plans that contain exec SecretRefs/providers unless `--allow-exec` is set.
+- Use `--allow-exec` to opt in to exec provider checks/execution in either mode.
+
+Plan contract details (allowed target paths, validation rules, and failure semantics):
+
+- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
+
+What `apply` may update:
+
+- `openclaw.json` (SecretRef targets + provider upserts/deletes)
+- `auth-profiles.json` (provider-target scrubbing)
+- legacy `auth.json` residues
+- `~/.openclaw/.env` known secret keys whose values were migrated
+
+## Why no rollback backups
+
+`secrets apply` intentionally does not write rollback backups containing old plaintext values.
+
+Safety comes from strict preflight + atomic-ish apply with best-effort in-memory restore on failure.
+
+## Example
+
+```bash
+openclaw secrets audit --check
+openclaw secrets configure
+openclaw secrets audit --check
+```
+
+If `audit --check` still reports plaintext findings, update the remaining reported target paths and rerun audit.
+
+## Related
+
+- [CLI reference](/cli)
+- [Secrets management](/gateway/secrets)