vilvona 1.0.0

package/docs/install/render.mdx

@@ -0,0 +1,167 @@
+---
+summary: "Deploy OpenClaw on Render with Infrastructure-as-Code"
+read_when:
+  - Deploying OpenClaw to Render
+  - You want a declarative cloud deploy with Render Blueprints
+title: "Render"
+---
+
+# Render
+
+Deploy OpenClaw on Render using Infrastructure as Code. The included `render.yaml` Blueprint defines your entire stack declaratively, service, disk, environment variables, so you can deploy with a single click and version your infrastructure alongside your code.
+
+## Prerequisites
+
+- A [Render account](https://render.com) (free tier available)
+- An API key from your preferred [model provider](/providers)
+
+## Deploy with a Render Blueprint
+
+[Deploy to Render](https://render.com/deploy?repo=https://github.com/openclaw/openclaw)
+
+Clicking this link will:
+
+1. Create a new Render service from the `render.yaml` Blueprint at the root of this repo.
+2. Build the Docker image and deploy
+
+Once deployed, your service URL follows the pattern `https://<service-name>.onrender.com`.
+
+## Understanding the Blueprint
+
+Render Blueprints are YAML files that define your infrastructure. The `render.yaml` in this
+repository configures everything needed to run OpenClaw:
+
+```yaml
+services:
+  - type: web
+    name: openclaw
+    runtime: docker
+    plan: starter
+    healthCheckPath: /health
+    envVars:
+      - key: OPENCLAW_GATEWAY_PORT
+        value: "8080"
+      - key: OPENCLAW_STATE_DIR
+        value: /data/.openclaw
+      - key: OPENCLAW_WORKSPACE_DIR
+        value: /data/workspace
+      - key: OPENCLAW_GATEWAY_TOKEN
+        generateValue: true # auto-generates a secure token
+    disk:
+      name: openclaw-data
+      mountPath: /data
+      sizeGB: 1
+```
+
+Key Blueprint features used:
+
+| Feature               | Purpose                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `runtime: docker`     | Builds from the repo's Dockerfile                          |
+| `healthCheckPath`     | Render monitors `/health` and restarts unhealthy instances |
+| `generateValue: true` | Auto-generates a cryptographically secure value            |
+| `disk`                | Persistent storage that survives redeploys                 |
+
+## Choosing a plan
+
+| Plan      | Spin-down         | Disk          | Best for                      |
+| --------- | ----------------- | ------------- | ----------------------------- |
+| Free      | After 15 min idle | Not available | Testing, demos                |
+| Starter   | Never             | 1GB+          | Personal use, small teams     |
+| Standard+ | Never             | 1GB+          | Production, multiple channels |
+
+The Blueprint defaults to `starter`. To use free tier, change `plan: free` in
+your fork's `render.yaml` (but note: no persistent disk means OpenClaw state
+resets on each deploy).
+
+## After deployment
+
+### Access the Control UI
+
+The web dashboard is available at `https://<your-service>.onrender.com/`.
+
+Connect using the configured shared secret. This deploy template auto-generates
+`OPENCLAW_GATEWAY_TOKEN` (find it in **Dashboard → your service →
+Environment**); if you replace it with password auth, use that password
+instead.
+
+## Render Dashboard features
+
+### Logs
+
+View real-time logs in **Dashboard → your service → Logs**. Filter by:
+
+- Build logs (Docker image creation)
+- Deploy logs (service startup)
+- Runtime logs (application output)
+
+### Shell access
+
+For debugging, open a shell session via **Dashboard → your service → Shell**. The persistent disk is mounted at `/data`.
+
+### Environment variables
+
+Modify variables in **Dashboard → your service → Environment**. Changes trigger an automatic redeploy.
+
+### Auto-deploy
+
+If you use the original OpenClaw repository, Render will not auto-deploy your OpenClaw. To update it, run a manual Blueprint sync from the dashboard.
+
+## Custom domain
+
+1. Go to **Dashboard → your service → Settings → Custom Domains**
+2. Add your domain
+3. Configure DNS as instructed (CNAME to `*.onrender.com`)
+4. Render provisions a TLS certificate automatically
+
+## Scaling
+
+Render supports horizontal and vertical scaling:
+
+- **Vertical**: Change the plan to get more CPU/RAM
+- **Horizontal**: Increase instance count (Standard plan and above)
+
+For OpenClaw, vertical scaling is usually sufficient. Horizontal scaling requires sticky sessions or external state management.
+
+## Backups and migration
+
+Export your state, config, auth profiles, and workspace at any time using the
+shell access in the Render Dashboard:
+
+```bash
+openclaw backup create
+```
+
+This creates a portable backup archive with OpenClaw state plus any configured
+workspace. See [Backup](/cli/backup) for details.
+
+## Troubleshooting
+
+### Service will not start
+
+Check the deploy logs in the Render Dashboard. Common issues:
+
+- Missing `OPENCLAW_GATEWAY_TOKEN` — verify it is set in **Dashboard → Environment**
+- Port mismatch — ensure `OPENCLAW_GATEWAY_PORT=8080` is set so the gateway binds to the port Render expects
+
+### Slow cold starts (free tier)
+
+Free tier services spin down after 15 minutes of inactivity. The first request after spin-down takes a few seconds while the container starts. Upgrade to Starter plan for always-on.
+
+### Data loss after redeploy
+
+This happens on free tier (no persistent disk). Upgrade to a paid plan, or
+regularly export a full backup via `openclaw backup create` in the Render shell.
+
+### Health check failures
+
+Render expects a 200 response from `/health` within 30 seconds. If builds succeed but deploys fail, the service may be taking too long to start. Check:
+
+- Build logs for errors
+- Whether the container runs locally with `docker build && docker run`
+
+## Next steps
+
+- Set up messaging channels: [Channels](/channels)
+- Configure the Gateway: [Gateway configuration](/gateway/configuration)
+- Keep OpenClaw up to date: [Updating](/install/updating)

package/docs/install/uninstall.md

@@ -0,0 +1,140 @@
+---
+summary: "Uninstall OpenClaw completely (CLI, service, state, workspace)"
+read_when:
+  - You want to remove OpenClaw from a machine
+  - The gateway service is still running after uninstall
+title: "Uninstall"
+---
+
+Two paths:
+
+- **Easy path** if `openclaw` is still installed.
+- **Manual service removal** if the CLI is gone but the service is still running.
+
+## Easy path (CLI still installed)
+
+Recommended: use the built-in uninstaller:
+
+```bash
+openclaw uninstall
+```
+
+When using the CLI, state removal preserves configured workspace directories unless you also select `--workspace`.
+
+Preview what will be removed (safe):
+
+```bash
+openclaw uninstall --dry-run --all
+```
+
+Non-interactive (automation / npx). Use with caution and only after confirming scopes:
+
+```bash
+openclaw uninstall --all --yes --non-interactive
+npx -y openclaw uninstall --all --yes --non-interactive
+```
+
+Manual steps (same result):
+
+1. Stop the gateway service:
+
+```bash
+openclaw gateway stop
+```
+
+2. Uninstall the gateway service (launchd/systemd/schtasks):
+
+```bash
+openclaw gateway uninstall
+```
+
+3. Delete state + config:
+
+```bash
+rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
+```
+
+If you set `OPENCLAW_CONFIG_PATH` to a custom location outside the state dir, delete that file too.
+If you want to keep a workspace inside the state dir, such as `~/.openclaw/workspace`, move it aside before running `rm -rf` or delete state contents selectively.
+
+4. Delete your workspace (optional, removes agent files):
+
+```bash
+rm -rf ~/.openclaw/workspace
+```
+
+5. Remove the CLI install (pick the one you used):
+
+```bash
+npm rm -g openclaw
+pnpm remove -g openclaw
+bun remove -g openclaw
+```
+
+6. If you installed the macOS app:
+
+```bash
+rm -rf /Applications/OpenClaw.app
+```
+
+Notes:
+
+- If you used profiles (`--profile` / `OPENCLAW_PROFILE`), repeat step 3 for each state dir (defaults are `~/.openclaw-<profile>`).
+- In remote mode, the state dir lives on the **gateway host**, so run steps 1-4 there too.
+
+## Manual service removal (CLI not installed)
+
+Use this if the gateway service keeps running but `openclaw` is missing.
+
+### macOS (launchd)
+
+Default label is `ai.openclaw.gateway` (or `ai.openclaw.<profile>`; legacy `com.openclaw.*` may still exist):
+
+```bash
+launchctl bootout gui/$UID/ai.openclaw.gateway
+rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist
+```
+
+If you used a profile, replace the label and plist name with `ai.openclaw.<profile>`. Remove any legacy `com.openclaw.*` plists if present.
+
+### Linux (systemd user unit)
+
+Default unit name is `openclaw-gateway.service` (or `openclaw-gateway-<profile>.service`):
+
+```bash
+systemctl --user disable --now openclaw-gateway.service
+rm -f ~/.config/systemd/user/openclaw-gateway.service
+systemctl --user daemon-reload
+```
+
+### Windows (Scheduled Task)
+
+Default task name is `OpenClaw Gateway` (or `OpenClaw Gateway (<profile>)`).
+The task script lives under your state dir.
+
+```powershell
+schtasks /Delete /F /TN "OpenClaw Gateway"
+Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"
+```
+
+If you used a profile, delete the matching task name and `~\.openclaw-<profile>\gateway.cmd`.
+
+## Normal install vs source checkout
+
+### Normal install (install.sh / npm / pnpm / bun)
+
+If you used `https://openclaw.ai/install.sh` or `install.ps1`, the CLI was installed with `npm install -g openclaw@latest`.
+Remove it with `npm rm -g openclaw` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
+
+### Source checkout (git clone)
+
+If you run from a repo checkout (`git clone` + `openclaw ...` / `bun run openclaw ...`):
+
+1. Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
+2. Delete the repo directory.
+3. Remove state + workspace as shown above.
+
+## Related
+
+- [Install overview](/install)
+- [Migration guide](/install/migrating)

package/docs/install/updating.md

@@ -0,0 +1,284 @@
+---
+summary: "Updating OpenClaw safely (global install or source), plus rollback strategy"
+read_when:
+  - Updating OpenClaw
+  - Something breaks after an update
+title: "Updating"
+---
+
+Keep OpenClaw up to date.
+
+## Recommended: `openclaw update`
+
+The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `openclaw doctor`, and restarts the gateway.
+
+```bash
+openclaw update
+```
+
+To switch channels or target a specific version:
+
+```bash
+openclaw update --channel beta
+openclaw update --channel dev
+openclaw update --dry-run   # preview without applying
+```
+
+`openclaw update` does not accept `--verbose`. For update diagnostics, use
+`--dry-run` to preview the planned actions, `--json` for structured results, or
+`openclaw update status --json` to inspect channel and availability state. The
+installer has its own `--verbose` flag, but that flag is not part of
+`openclaw update`.
+
+`--channel beta` prefers beta, but the runtime falls back to stable/latest when
+the beta tag is missing or older than the latest stable release. Use `--tag beta`
+if you want the raw npm beta dist-tag for a one-off package update.
+
+Use `--channel dev` for a persistent moving GitHub `main` checkout. For package
+updates, `--tag main` maps to `github:openclaw/openclaw#main` for one run, and
+GitHub/git source specs are packed into a temporary tarball before the staged
+npm install.
+
+For managed plugins, beta-channel fallback is a warning: the core update can
+still succeed while a plugin uses its recorded default/latest release because no
+plugin beta is available.
+
+See [Development channels](/install/development-channels) for channel semantics.
+
+## Switch between npm and git installs
+
+Use channels when you want to change the install type. The updater keeps your
+state, config, credentials, and workspace in `~/.openclaw`; it only changes
+which OpenClaw code install the CLI and gateway use.
+
+```bash
+# npm package install -> editable git checkout
+openclaw update --channel dev
+
+# git checkout -> npm package install
+openclaw update --channel stable
+```
+
+Run with `--dry-run` first to preview the exact install-mode switch:
+
+```bash
+openclaw update --channel dev --dry-run
+openclaw update --channel stable --dry-run
+```
+
+The `dev` channel ensures a git checkout, builds it, and installs the global CLI
+from that checkout. The `stable` and `beta` channels use package installs. If the
+gateway is already installed, `openclaw update` refreshes the service metadata
+and restarts it unless you pass `--no-restart`.
+
+For package installs with a managed Gateway service, `openclaw update` targets
+the package root used by that service. If the shell `openclaw` command comes
+from a different install, the updater prints both roots and the managed service
+Node path. The package update uses the package manager that owns the service
+root and checks the managed service Node against the target release engine
+before replacing the package.
+
+## Alternative: re-run the installer
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+Add `--no-onboard` to skip onboarding. To force a specific install type through
+the installer, pass `--install-method git --no-onboard` or
+`--install-method npm --no-onboard`.
+
+If `openclaw update` fails after the npm package install phase, re-run the
+installer. The installer does not call the old updater; it runs the global
+package install directly and can recover a partially updated npm install.
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
+```
+
+To pin the recovery to a specific version or dist-tag, add `--version`:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
+```
+
+## Alternative: manual npm, pnpm, or bun
+
+```bash
+npm i -g openclaw@latest
+```
+
+Prefer `openclaw update` for supervised installs because it can coordinate the
+package swap with the running Gateway service. If you update manually on a
+supervised install, stop the managed Gateway before the package manager starts.
+Package managers replace files in place, and a running Gateway can otherwise try
+to load core or plugin files while the package tree is temporarily half-swapped.
+Restart the Gateway after the package manager finishes so the service picks up
+the new install.
+
+For a root-owned Linux system-global install, if `openclaw update` fails with
+`EACCES` and you recover with system npm, keep the Gateway stopped through the
+manual package replacement. Use the same `openclaw` profile flags or environment
+you normally use for that Gateway. Replace `/usr/bin/npm` with the system npm
+that owns the root-owned global prefix on your host:
+
+```bash
+openclaw gateway stop
+sudo /usr/bin/npm i -g openclaw@latest
+openclaw gateway install --force
+openclaw gateway restart
+```
+
+Then verify the service:
+
+```bash
+openclaw --version
+curl -fsS http://127.0.0.1:18789/readyz
+openclaw plugins list --json
+openclaw gateway status --deep --json
+openclaw doctor --lint --json
+```
+
+When `openclaw update` manages a global npm install, it installs the target into
+a temporary npm prefix first, verifies the packaged `dist` inventory, then swaps
+the clean package tree into the real global prefix. That avoids npm overlaying a
+new package onto stale files from the old package. If the install command fails,
+OpenClaw retries once with `--omit=optional`. That retry helps hosts where native
+optional dependencies cannot compile, while keeping the original failure visible
+if the fallback also fails.
+
+OpenClaw-managed npm update and plugin-update commands also clear npm
+`min-release-age` quarantine for the child npm process. npm may report that
+policy as a derived `before` cutoff; both are useful for general supply-chain
+quarantine policies, but an explicit OpenClaw update means "install the selected
+OpenClaw release now."
+
+```bash
+pnpm add -g openclaw@latest
+```
+
+```bash
+bun add -g openclaw@latest
+```
+
+### Advanced npm install topics
+
+<AccordionGroup>
+  <Accordion title="Read-only package tree">
+    OpenClaw treats packaged global installs as read-only at runtime, even when the global package directory is writable by the current user. Plugin package installs live in OpenClaw-owned npm/git roots under the user config directory, and Gateway startup does not mutate the OpenClaw package tree.
+
+    Some Linux npm setups install global packages under root-owned directories such as `/usr/lib/node_modules/openclaw`. OpenClaw supports that layout because plugin install/update commands write outside that global package directory.
+
+  </Accordion>
+  <Accordion title="Hardened systemd units">
+    Give OpenClaw write access to its config/state roots so explicit plugin installs, plugin updates, and doctor cleanup can persist their changes:
+
+    ```ini
+    ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
+    ```
+
+  </Accordion>
+  <Accordion title="Disk-space preflight">
+    Before package updates and explicit plugin installs, OpenClaw tries a best-effort disk-space check for the target volume. Low space produces a warning with the checked path, but does not block the update because filesystem quotas, snapshots, and network volumes can change after the check. The actual package-manager install and post-install verification remain authoritative.
+  </Accordion>
+</AccordionGroup>
+
+## Auto-updater
+
+The auto-updater is off by default. Enable it in `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  update: {
+    channel: "stable",
+    auto: {
+      enabled: true,
+      stableDelayHours: 6,
+      stableJitterHours: 12,
+      betaCheckIntervalHours: 1,
+    },
+  },
+}
+```
+
+| Channel  | Behavior                                                                                                      |
+| -------- | ------------------------------------------------------------------------------------------------------------- |
+| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
+| `beta`   | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately.                              |
+| `dev`    | No automatic apply. Use `openclaw update` manually.                                                           |
+
+The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).
+For downgrade or incident recovery, set `OPENCLAW_NO_AUTO_UPDATE=1` in the gateway environment to block automatic applies even when `update.auto.enabled` is configured. Startup update hints can still run unless `update.checkOnStart` is also disabled.
+
+Package-manager updates requested through the live Gateway control-plane handler
+do not replace the package tree inside the running Gateway process. On managed
+service installs, the Gateway starts a detached handoff, exits, and lets the
+normal `openclaw update --yes --json` CLI path stop the service, replace the
+package, refresh service metadata, restart, verify the Gateway version and
+reachability, and recover an installed-but-unloaded macOS LaunchAgent when
+possible. If the Gateway cannot make that handoff safely, `update.run` reports a
+safe shell command instead of running the package manager in-process.
+
+## After updating
+
+<Steps>
+
+### Run doctor
+
+```bash
+openclaw doctor
+```
+
+Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)
+
+### Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+### Verify
+
+```bash
+openclaw health
+```
+
+</Steps>
+
+## Rollback
+
+### Pin a version (npm)
+
+```bash
+npm i -g openclaw@<version>
+openclaw doctor
+openclaw gateway restart
+```
+
+<Tip>
+`npm view openclaw version` shows the current published version.
+</Tip>
+
+### Pin a commit (source)
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+pnpm install && pnpm build
+openclaw gateway restart
+```
+
+To return to latest: `git checkout main && git pull`.
+
+## If you are stuck
+
+- Run `openclaw doctor` again and read the output carefully.
+- For `openclaw update --channel dev` on source checkouts, the updater auto-bootstraps `pnpm` when needed. If you see a pnpm/corepack bootstrap error, install `pnpm` manually (or re-enable `corepack`) and rerun the update.
+- Check: [Troubleshooting](/gateway/troubleshooting)
+- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
+
+## Related
+
+- [Install overview](/install): all installation methods.
+- [Doctor](/gateway/doctor): health checks after updates.
+- [Migrating](/install/migrating): major version migration guides.

package/docs/install/upstash.md

@@ -0,0 +1,96 @@
+---
+summary: "Host OpenClaw on Upstash Box with keep-alive and SSH tunnel access"
+read_when:
+  - Deploying OpenClaw to Upstash Box
+  - You want a managed Linux environment for OpenClaw with SSH-tunneled dashboard access
+title: "Upstash Box"
+---
+
+Run a persistent OpenClaw Gateway on Upstash Box, a managed Linux environment
+with keep-alive lifecycle support.
+
+Use an SSH tunnel for dashboard access. Do not expose the Gateway port directly
+to the public internet.
+
+## Prerequisites
+
+- Upstash account
+- Keep-alive Upstash Box
+- SSH client on your local machine
+
+## Create a Box
+
+Create a keep-alive Box in the Upstash Console. Note the Box ID, such as
+`right-flamingo-14486`, and your Box API key.
+
+Upstash maintains its current OpenClaw Box walkthrough at
+[OpenClaw Setup](https://upstash.com/docs/box/guides/openclaw-setup).
+
+## Connect with an SSH tunnel
+
+Forward the OpenClaw dashboard port to your local machine. Use your Box API key
+as the SSH password when prompted:
+
+```bash
+ssh -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -L 18789:127.0.0.1:18789 <box-id>@us-east-1.box.upstash.com
+```
+
+The keepalive options reduce idle tunnel drops during onboarding.
+
+## Install OpenClaw
+
+Inside the Box:
+
+```bash
+sudo npm install -g openclaw
+```
+
+## Run onboarding
+
+```bash
+openclaw onboard --install-daemon
+```
+
+Follow the prompts. Copy the dashboard URL and token when onboarding finishes.
+
+## Start the Gateway
+
+Configure the Gateway for the Box network and start it in the background:
+
+```bash
+openclaw config set gateway.bind lan
+nohup openclaw gateway > gateway.log 2>&1 &
+```
+
+With the SSH tunnel active, open the dashboard URL locally:
+
+```text
+http://127.0.0.1:18789/#token=<your-token>
+```
+
+## Auto-restart
+
+Set this command as the Box init script so the Gateway restarts when the Box
+starts:
+
+```bash
+nohup openclaw gateway > gateway.log 2>&1 &
+```
+
+## Troubleshooting
+
+If SSH freezes during onboarding, reconnect with a clean SSH config and
+keepalives:
+
+```bash
+ssh -F /dev/null -o ControlMaster=no -o ServerAliveInterval=15 -o ServerAliveCountMax=3 -L 18789:127.0.0.1:18789 <box-id>@us-east-1.box.upstash.com
+```
+
+This bypasses stale local `~/.ssh/config` settings and keeps the tunnel active
+through idle network periods.
+
+## Related
+
+- [Remote access](/gateway/remote)
+- [Gateway security](/gateway/security)
+- [Updating OpenClaw](/install/updating)