Skip to content

OpenClaw How-to Guides

Task recipes for installing, configuring, securing, operating, upgrading, and troubleshooting an OpenClaw Gateway. Commands were checked against the 2026.9.x docs and CLI reference; look-up tables (ports, paths, config keys, full command map) live in Reference.

Read the trust model first

OpenClaw treats every authenticated Gateway caller as a trusted operator, and tool execution runs on the host unless you enable sandboxing. Read Security Model before exposing a Gateway or connecting other people.

Installation

Quick Install (macOS/Linux)

The installer provisions a supported Node.js runtime when needed, installs the package, and starts onboarding.

# macOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iex

Install with npm

Use this when you already manage Node.js (24.16+ or 26.1+; Node 26 recommended).

# npm 12 or npm 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 and earlier: omit --allow-scripts=openclaw

openclaw onboard --install-daemon   # wizard + launchd/systemd user service
openclaw gateway status
openclaw dashboard                  # opens the Control UI at http://127.0.0.1:18789/

Docker is optional. The supported path is the repo's setup script with Docker Compose; it writes a Gateway token to .env, runs onboarding, and starts the openclaw-gateway service.

git clone https://github.com/openclaw/openclaw.git && cd openclaw

# Use the pre-built image from GHCR instead of building locally
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

# Print the dashboard URL again later
docker compose run --rm openclaw-cli dashboard --no-open

Pin a version tag (for example ghcr.io/openclaw/openclaw:2026.9.6) for production instead of latest. Use the -browser image variant if the Gateway's managed browser must run inside the container.

Container bind default

Container images default to an exposed bind so the host can reach the Gateway. Keep Gateway auth on, publish the port only on 127.0.0.1, and filter the DOCKER-USER chain on public hosts.

Headless Docker Bootstrap

For unattended hosts, put credentials in the Compose .env (OPENAI_API_KEY, OPENCLAW_GATEWAY_TOKEN, TELEGRAM_BOT_TOKEN) and onboard without a TTY:

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --non-interactive --accept-risk --skip-health \
  --mode local --auth-choice openai-api-key --secret-input-mode ref \
  --gateway-auth token --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --skip-channels --no-install-daemon

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js channels add --channel telegram --use-env

docker compose up -d openclaw-gateway

NemoClaw (Secure Deployment)

NVIDIA NemoClaw installs OpenClaw (default agent) inside an NVIDIA OpenShell sandbox with managed inference and network policy. It is an alpha project; review the prerequisites first.

curl -fsSL https://www.nvidia.com/nemoclaw.sh | bash
nemoclaw list                 # registered sandboxes
nemoclaw <name> status        # sandbox and OpenClaw version
nemoclaw <name> connect       # shell into the sandbox

Configuration

Core Config File

OpenClaw reads an optional JSON5 file at ~/.openclaw/openclaw.json. The Gateway watches it and hot-reloads most changes. Validation is strict: unknown keys or bad values stop the Gateway from starting until openclaw doctor --fix repairs them.

// ~/.openclaw/openclaw.json - minimal example
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "anthropic/claude-opus-4-6",   // provider/model ref
    },
  },
  gateway: {
    bind: "loopback",                       // default; keep it
  },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
  },
}

Correction

Earlier versions of this page showed a YAML file at ~/.openclaw/config.yaml with model.provider / channels.telegram.token keys. That format does not exist in current releases; the file is openclaw.json (JSON5) and channel credentials are best added with openclaw channels add or SecretRefs.

Edit Config from the CLI

openclaw configure                                   # guided editor
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config schema > openclaw.schema.json        # canonical JSON Schema
openclaw config validate

Environment Variables

Keep provider and channel secrets out of openclaw.json. Use env vars or SecretRefs (env, file, exec, store sources); see the variable list in Reference.

openclaw secrets configure       # set up secret references
openclaw secrets audit --check   # fail CI when plaintext secrets are found

Commands & Recipes

Core CLI Commands

openclaw gateway start          # start the installed service
openclaw gateway stop
openclaw gateway restart
openclaw gateway status --deep  # service + connectivity probe
openclaw gateway run            # foreground
openclaw status
openclaw health
openclaw logs --follow
openclaw tui                    # terminal chat; `openclaw chat` is an alias for `tui --local`

Connect a Channel

Telegram is the fastest first channel (bot token, no plugin install).

openclaw channels add --channel telegram --token <bot-token>
openclaw channels login                 # WhatsApp QR pairing
openclaw plugins install @openclaw/discord
openclaw channels status --probe

Approve a Pairing Request

Unknown DM senders receive a pairing code instead of reaching the agent.

openclaw pairing list
openclaw pairing approve telegram <code>

Skill Management

openclaw skills list
openclaw skills search "code review"
openclaw skills verify @owner/<slug>          # ClawHub trust envelope before install
openclaw skills install @owner/<slug>         # into the workspace skills/ dir
openclaw skills install @owner/<slug> --global
openclaw skills install git:owner/repo@ref
openclaw skills update --all

To remove a skill, delete its directory from the workspace skills/ (or ~/.openclaw/skills for --global) or disable it with skills.entries.<name>.enabled: false. Scaffold new skills with the bundled skill-creator skill or the Skill Workshop.

Memory Management

openclaw memory status
openclaw memory index                 # (re)build the memory index
openclaw memory search "deployment procedure"

MEMORY.md and memory/*.md are plain Markdown in the agent workspace; read or edit them directly.

Connect MCP Servers

openclaw mcp status --verbose        # what is saved, without starting servers
openclaw mcp add                     # save a third-party MCP server
openclaw mcp probe <name>            # live connection + capability list
openclaw mcp serve                   # expose OpenClaw conversations to an MCP client over stdio

Lobster Workflows

Lobster is an optional plugin tool that the agent calls; there is no openclaw lobster CLI.

openclaw plugins install @openclaw/lobster

// ~/.openclaw/openclaw.json - allow the tool on top of the active profile
{ tools: { alsoAllow: ["lobster"] } }

The agent then invokes the lobster tool with {"action": "run", "pipeline": "/path/to/flow.lobster"}; a paused run returns needs_approval with a resumeToken, and {"action": "resume", "token": "<resumeToken>", "approve": true} continues it.

Multi-Instance Orchestration (claworc)

claworc is a community control plane that runs each OpenClaw instance in its own container behind one authenticated entry point (Docker or Kubernetes). Follow its installation docs; the repository ships an install.sh.

Deployment Best Practices

Security First

OpenClaw's CVE record (see Reference) is dominated by bugs reachable from exposed or shared Gateways. Keep it on loopback, keep it updated, and turn on sandboxing.

Network Security

  1. Never expose port 18789 directly to the public internet.
  2. Prefer Tailscale Serve or an SSH tunnel for remote access; use a reverse proxy only with gateway.trustedProxies configured.
  3. Keep Gateway auth on (token generated at onboarding); never set gateway.auth.mode: "none" outside private ingress.
  4. Use NemoClaw or the OpenShell sandbox backend for confidential workloads.

Remote Access over SSH

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
# then open http://127.0.0.1:18789/ locally; the same token applies

Reverse Proxy (Caddy)

Caddy terminates TLS and proxies the WebSocket upgrade. Gateway token auth still applies behind it; add gateway.trustedProxies for the proxy address and set gateway.controlUi.allowedOrigins (or gateway.publicOrigin) for the public origin.

openclaw.example.com {
    reverse_proxy 127.0.0.1:18789
    basic_auth {
        admin <bcrypt-hash>   # generate with: caddy hash-password
    }
}

Firewall Configuration

Minimum host rules for a Gateway fronted by a local reverse proxy (adapt to nftables/ufw):

# Allow HTTPS (reverse proxy)
iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# Allow Gateway only from loopback, drop everything else
iptables -A INPUT -p tcp --dport 18789 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 18789 -j DROP

On Docker hosts, published ports bypass the INPUT chain; filter them in DOCKER-USER instead. Hostname-based egress rules such as -d api.anthropic.com resolve once at insert time, so use an egress proxy (OPENCLAW_PROXY_URL) or OpenShell network policy for real egress allowlisting.

Hardened Docker Run

A hand-rolled container with reduced privileges. This is a starting point, not an official recipe; the official path is scripts/docker/setup.sh.

docker run -d \
  --name openclaw \
  --read-only \
  --tmpfs /tmp \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v openclaw-state:/home/node/.openclaw:rw \
  -p 127.0.0.1:18789:18789 \
  -e OPENCLAW_GATEWAY_TOKEN \
  ghcr.io/openclaw/openclaw:2026.9.6

-p 127.0.0.1:18789:18789 publishes only on loopback; -p 18789:18789 publishes on all interfaces, the misconfiguration behind most exposed instances.

Enable Sandboxing

Tool execution runs on the host by default (agents.defaults.sandbox.mode: "off"). Sandbox non-main sessions with no workspace access:

{
  agents: {
    defaults: {
      sandbox: { mode: "non-main", scope: "session", workspaceAccess: "none" },
    },
  },
}

openclaw sandbox explain --agent main   # effective mode, mounts, tool policy
openclaw sandbox list
openclaw sandbox recreate --all         # apply new sandbox config

Run the Security Audit

openclaw security audit          # findings with check IDs
openclaw security audit --deep   # schedule this and alert on check IDs

Monitoring

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz    # channel-aware readiness
openclaw gateway usage-cost                # model spend summary
openclaw channels status --probe

For production, export OpenTelemetry or Prometheus metrics from the Gateway and ship container logs to an external collector.

Troubleshooting

Common Issues

Gateway does not start

lsof -i :18789                 # port already in use?
openclaw doctor                # shows exact config/state problems
openclaw doctor --fix          # applies supported repairs (same as --repair)
openclaw logs --follow

Only diagnostic commands (doctor, logs, health, status) work while the config is invalid. Rejected writes are saved as openclaw.json.rejected.<timestamp>.

Channel disconnections

openclaw channels status --probe
openclaw channels logs
openclaw channels logout && openclaw channels login   # re-pair WhatsApp

Memory search not working

openclaw memory status
openclaw memory index

Unstable sessions or crashes

  • Upgrade first; 2026.9.1 and 2026.9.6 specifically targeted Gateway startup recovery and resuming unfinished work after restarts.
  • openclaw doctor reports raw vs injected sizes of oversized MEMORY.md / bootstrap files.

Docker Gateway exits with code 78

Required state cannot be migrated safely. Keep the volume, run doctor once with the same mounts, then restart:

docker run --rm -v openclaw-state:/home/node/.openclaw ghcr.io/openclaw/openclaw:2026.9.6 openclaw doctor --fix
docker compose run --rm openclaw-cli doctor --json

NemoClaw-Specific

nemoclaw <name> status        # sandbox health and agent version
nemoclaw <name> logs
nemoclaw <name> doctor
nemoclaw <name> policy list   # applied network policy presets
nemoclaw <name> recover

The nemoclaw sandbox status, nemoclaw policy logs, nemoclaw inference test and nemoclaw k3s status commands in earlier versions of this page do not exist in the NemoClaw command reference.

Upgrade Procedures

openclaw update                        # managed update; restarts and verifies the Gateway
openclaw update --dry-run
openclaw update status --json
openclaw update --channel extended-stable
openclaw update --tag 2026.9.6         # one-off version, not persisted
openclaw backup create                 # before risky upgrades

Failed post-update Doctor runs roll back the npm candidate (since 2026.9.1). Package rollback cannot undo migrated state, so keep backups. Manual path when the updater refuses:

openclaw gateway stop
npm install -g openclaw@<target> --allow-scripts=openclaw
openclaw doctor --fix
openclaw gateway start

Docker upgrade: change OPENCLAW_IMAGE (or the tag) in .env, then

docker compose pull openclaw-gateway openclaw-cli
docker compose up -d openclaw-gateway

The new container runs Doctor migrations before readiness and saves <database>.pre-startup-migration-<id>.bak copies.

Sources