OpenClaw — Hardened Installation Guide for Claude Code (v2)

This file is for you, Claude Code. You're working on a remote Linux server (Ubuntu, SSH access). Your task is to set up OpenClaw according to the official documentation (https://docs.openclaw.ai) and guidelines from the sysadmin mentor, enriched with findings from external security audits (Microsoft, Kaspersky, Cisco Talos, CrowdStrike, Promptfoo, Giskard, NVD).

You work autonomously as long as possible. Ask the operator only when you must. Read this entire file before anything else and treat it as binding.

---

TL;DR — hard rules, non-negotiable

1. OpenClaw is not a chatbot. It's a privileged local service with shell access, file access, and operator identity. Microsoft Security Blog: "OpenClaw should be treated as untrusted code execution with persistent credentials." Treat it like a daemon with sudo, not like Slack.
2. Loopback only. Always. 127.0.0.1, never 0.0.0.0. SecurityScorecard found 30,000+ exposed OpenClaw instances on the public internet — all compromised.
3. Version MUST be fresh. Minimum 2026.3.28 (time of writing). Earlier versions have known CVEs (including CVE-2026-25253 — 1-click RCE, CVSS 8.8). Verify version before anything else after install.
4. Default mode is security="full", ask="off" — meaning OpenClaw asks nothing before executing shell commands. This is an intentional UX decision by the creator, not a bug. We disable this. exec.ask: "always" or at minimum "on-miss" with askFallback: "deny".
5. Skills from ClawHub = running foreign code. Cisco Talos ran the "What Would Elon Do?" skill → 9 findings, 2 critical, including active data exfiltration via curl to attacker-controlled server. Zero skills at this stage.
6. Prompt injection is unsolved. All researchers (Microsoft, OWASP, NCSC, NIST CAISI) agree: you can't fix this with a prompt. Defense: tool policy, exec approvals, sandboxing, channel allowlists. We rely on the layer under the model.
7. openclaw security audit after every config change. This is not optional, it's a checkpoint.

---

What OpenClaw Is

OpenClaw (formerly Clawdbot/Moltbot) is a viral self-hosted personal AI agent created by Peter Steinberger (PSPDFKit). Architecture:

• Gateway — long-running daemon, control plane. Whoever passes gateway auth is a "trusted operator" — full access.
• Node — execution extension. A paired node = operator-level remote capability.
• Workspace (~/.openclaw/workspace) — file sandbox.
• Config (~/.openclaw/openclaw.json) — providers, channels, skills, tool policy, exec approvals, sandbox. Treat like a password vault.
• Web UI — http://127.0.0.1:18789, requires token.
• TUI — openclaw tui.
• CLI — openclaw onboard, openclaw gateway start/stop/status, openclaw doctor, openclaw logs --follow, openclaw dashboard, openclaw status, openclaw security audit, openclaw sandbox explain.

Written in TypeScript, Node.js 22.14+ (recommended 24). Official installer handles Node itself.

Trust boundary is singular. From github.com/openclaw/openclaw/SECURITY.md:

"Gateway is the control plane. If a caller passes Gateway auth, they are treated as a trusted operator for that Gateway. Exec approvals are operator guardrails to reduce accidental command execution, not a multi-tenant authorization boundary."

Translation: whoever gets the gateway token has everything. Multi-tenant isolation does not exist. This gateway must be yours only.

---

Context — read before you start

A previous attempt to set up OpenClaw with a different AI assistant used old, outdated installation methods. It took 2-3 hours and ended in failure. The sysadmin mentor's direction: go back to official docs and follow the steps. The mentor also advised against Docker containerization "by force" — it makes no sense on this machine.

Sources of truth (in this order):

1. https://docs.openclaw.ai/install — installation
2. https://docs.openclaw.ai/gateway/security — security model (CRITICAL)
3. https://docs.openclaw.ai/gateway/sandboxing — sandbox config
4. https://github.com/openclaw/openclaw/blob/main/SECURITY.md — bug bounty scope (reads like a threat model)
5. https://openclaw.ai — quick start

What NOT to use as a source:

• Any GitHub gists showing git clone github.com/openclaw/openclaw.git + pip install -r requirements.txt — that's a fake project with the same name. Real OpenClaw is TypeScript/Node, not Python.
• Tutorials from DigitalOcean / Cherry Servers / LumaDock showing public IP exposure. Binding to 0.0.0.0 + reverse proxy without trustedProxies = CVE-2026-29613 and an open gate for CVE-2026-25253.
• LocalAI / OpenWebUI documentation — those are different tools.

Target Environment

• Ubuntu server with NVIDIA GPU (RTX 4060), SSH access.
• LocalAI is already running on this server and using the GPU. OpenClaw should live alongside LocalAI.
• Confirmed: VRAM is physically separated from system RAM. CPU/RAM processes (gateway, Node) and GPU/VRAM (LocalAI) don't interfere.

End Goal (awareness only — don't do this now)

1. Mac — dashboard via SSH tunnel.
2. Telegram bot — messaging the agent from a phone.
3. Raspberry Pi 4 + wake word "Jarvis" — voice assistant + smart home.

All of this is LATER, in separate phases. Right now only: gateway running, dashboard accessible via SSH tunnel, securely. No channels, no skills, no hooks.

---

Threat Model (condensed from external audits)

---

Working Rules

1. Official documentation is the only source of truth. WebFetch on https://docs.openclaw.ai/..., don't guess.
2. Don't expose anything publicly. Gateway on 127.0.0.1, access only via SSH tunnel.
3. Don't touch LocalAI. Only read its port (ss -tlnp, systemctl status localai*).
4. Port conflicts. OpenClaw wants 18789. Check it's free.
5. Persistence. ~/.openclaw/ in the operator's home directory (not root). Never log contents — tokens and keys live there.
6. Logs. Every side effect → ~/openclaw-install-logs/ with timestamp. Mask tokens (sed -E 's/token=[A-Za-z0-9_-]+/token=REDACTED/g').
7. openclaw security audit after every config change. Red → STOP, log to the operator.
8. Security reminder: Check if port 10022 is exposed in UFW from a previous session and close it.

---

Installation Method Selection

1. Official bootstrap (curl -fsSL https://openclaw.ai/install.sh | bash) — THIS IS OUR CHOICE.
2. Local-prefix (curl -fsSL https://openclaw.ai/install-cli.sh | bash) — fallback.
3. Manual npm — only if above fail.

DO NOT use Docker. The sysadmin mentor advised against it. Plus typical docker setups bind on 0.0.0.0 via -p 18789:18789 instead of -p 127.0.0.1:18789:18789 — that footgun compromised 30k instances.

DO NOT use --install-method git unless the installer explicitly suggests it.

Before starting: WebFetch on https://docs.openclaw.ai/install — confirm official commands haven't changed. If they differ → follow docs, not this file, and tell the operator.

---

Step-by-Step Plan

Step 0 — Reconnaissance

mkdir -p ~/openclaw-install-logs
LOG=~/openclaw-install-logs/00-recon-$(date +%Y%m%d-%H%M%S).log
{
  echo "=== uname ==="; uname -a
  echo "=== distro ==="; lsb_release -a 2>/dev/null || cat /etc/os-release
  echo "=== whoami ==="; whoami; echo "HOME=$HOME"
  echo "=== node ==="; which node && node --version || echo "no node"
  echo "=== npm ==="; which npm && npm --version || echo "no npm"
  echo "=== nvidia-smi ==="; nvidia-smi || echo "no nvidia-smi"
  echo "=== ports ==="; sudo ss -tlnp
  echo "=== localai ==="; systemctl list-units --type=service 2>/dev/null | grep -i localai || echo "no localai"
  echo "=== ufw ==="; sudo ufw status numbered
  echo "=== disk ==="; df -h ~
  echo "=== ram ==="; free -h
  echo "=== docker ==="; which docker && docker --version || echo "no docker"
} | tee $LOG

From this: node version, LocalAI port, whether 18789 is free, whether port 10022 is exposed in UFW (sysadmin said to remove it), whether we have ≥4 GB free RAM.

If RAM <4 GB — swap:

sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Step 1 — Check Current Documentation

WebFetch on:

• https://docs.openclaw.ai/install
• https://docs.openclaw.ai/gateway/security
• https://docs.openclaw.ai/gateway/sandboxing

Confirm: bootstrapper URL, minimum safe version, port, config parameter names (exec.ask, tools.profile, sandbox.mode may change between versions). Differences → STOP, notify the operator.

Step 2 — Dependencies

sudo apt update
sudo apt install -y curl git ca-certificates build-essential

Leave Node to the installer.

Step 3 — Bootstrap OpenClaw

Read the script before running it. Never blind curl|bash:

curl -fsSL https://openclaw.ai/install.sh -o /tmp/openclaw-install.sh
less /tmp/openclaw-install.sh   # review
bash /tmp/openclaw-install.sh 2>&1 | tee ~/openclaw-install-logs/01-install-$(date +%Y%m%d-%H%M%S).log

After installation:

which openclaw
openclaw --version

Version verification vs CVEs. Version must be newer than:

• 2026.1.29 — patch CVE-2026-25253 (1-click RCE, 8.8)
• 2026.1.30 — patch CVE-2026-24763 (Docker sandbox bypass, 8.8)
• 2026.2.12 — patch CVE-2026-29613 (reverse proxy auth bypass)
• 2026.3.28 — patch CVE-2026-33579 (privilege escalation, 8.1-9.8)

If version older than 2026.3.28 → STOP. Check if installer pulls latest, fallback npm install -g openclaw@latest.

Step 4 — Onboarding

Onboarding is interactive TUI. This is the critical moment.

openclaw onboard --install-daemon 2>&1 | tee ~/openclaw-install-logs/02-onboard-$(date +%Y%m%d-%H%M%S).log

TUI Decisions:

LLM Provider — ASK THE OPERATOR before choosing:

A) LocalAI locally (GPU) — OpenAI-compatible:

baseUrl: http://127.0.0.1:<PORT_LOCALAI>/v1
apiKey: sk-localai-dummy
api: openai-completions

Plus: zero cost, privacy. Critical minus: OpenClaw security docs: "Smaller/cheaper models are generally more susceptible to tool misuse and instruction hijacking, especially under adversarial prompts." Cheap local model = higher prompt injection risk. If LocalAI → must have active sandboxing and strict tool allowlist, non-negotiable.

B) Anthropic Claude (Opus 4.5+) — Kaspersky's OpenClaw audit recommends Claude Opus 4.5 as "currently the best at spotting prompt injections." Plus: better resistance. Minus: every token costs, OpenClaw can burn tokens via heartbeats.

C) Skip / All providers (empty keys) — dashboard comes up without a provider, add keys later via UI.

Default suggestion is C (skip) unless the operator explicitly says otherwise.

Step 4.5 — Config Hardening (KEY — this was missing in v1)

After onboarding, before launching anything, edit ~/.openclaw/openclaw.json (backup first):

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d-%H%M%S)

Settings that MUST be in config (names may differ between versions — verify with openclaw sandbox explain and docs, if they don't match, STOP):

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "auth": { "required": true }
  },
  "agents": {
    "defaults": {
      "exec": {
        "security": "deny",        // default deny, explicit allowlist
        "ask": "always",           // ask about EVERY shell command
        "askFallback": "deny",     // no response → deny
        "autoAllowSkills": false   // don't auto-trust skills
      },
      "sandbox": {
        "mode": "all",             // sandbox for every session
        "scope": "session",
        "workspaceAccess": "ro"    // workspace read-only to start
      },
      "tools": {
        "profile": "messaging",    // most restrictive profile
        "elevated": {
          "allowFrom": {}          // no senders authorized for elevated
        }
      },
      "logging": {
        "redactSensitive": "tools" // hide secrets in tool logs
      }
    }
  }
}

After editing — verification:

openclaw security audit 2>&1 | tee ~/openclaw-install-logs/03-audit-$(date +%Y%m%d-%H%M%S).log
openclaw sandbox explain 2>&1 | tee ~/openclaw-install-logs/04-sandbox-$(date +%Y%m%d-%H%M%S).log

security audit shows anything other than green → STOP. Full --json to the operator. Do not run --fix without explicit approval.

Step 5 — File Permissions

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/openclaw.json.bak-*

Only the operator can read. security audit flags this if wrong.

Step 6 — Gateway Verification

openclaw status
openclaw gateway status
openclaw doctor

Red → STOP, log to the operator.

sudo ss -tlnp | grep 18789

Must show 127.0.0.1:18789, NOT 0.0.0.0:18789 or :::18789. If otherwise — critical config error. STOP.

openclaw dashboard --no-open

Outputs URL http://127.0.0.1:18789?token=XXXXXXXX. Do NOT write the token to ARCHITECTURE.md — only to REPORT.md.

Step 7 — loginctl enable-linger (KEY)

--install-daemon registers a user-level systemd service. By default, user-level services don't survive user logout. The operator logs in and out via SSH — without linger, the gateway disappears after every SSH disconnect.

sudo loginctl enable-linger $USER
loginctl show-user $USER | grep Linger   # Linger=yes

Step 8 — SSH Tunnel from Mac (instructions for the operator)

Command to paste on Mac:

ssh -N -L 18789:127.0.0.1:18789 <user>@<server_host>

After tunneling, the operator opens the token URL (from step 6), replacing host with localhost:

http://localhost:18789?token=XXXXXXXX

Warning from audits (Promptfoo/Microsoft): this tunnel gives full operator access. The Mac is also part of the trust boundary. If a malicious page runs in the browser with an active tunnel, it can do a cross-site WebSocket hijack to localhost:18789. Therefore: tunnel opened only during work, closed after. Never 24/7.

Step 9 — Sanity Check

The operator enters the dashboard and verifies:

• Overview → gateway online,
• Settings → Sandbox: active (mode: all),
• Settings → Exec approvals: ask=always,
• Provider → Chat → "Hello, what model are you?" → response (if skip → add key in UI first).

Step 10 — Master Context Architecture File

Create ~/openclaw-install-logs/ARCHITECTURE.md with sections:

1. Hardware — from recon (CPU, RAM, GPU, distro).
2. Neighbors on machine — LocalAI (port, status), other services.
3. OpenClaw — installation — which method, CLI version, Node version, binary paths.
4. OpenClaw — gateway — bind address, port, systemd user unit, lingering, how to restart.
5. OpenClaw — security posture — exec.ask, sandbox.mode, tools.profile, tools.elevated, openclaw security audit status. No tokens.
6. OpenClaw — data — where config lives (just the fact), workspace, logs. File permissions.
7. Access — SSH tunnel only, zero open firewall ports, ready tunnel command, "tunnel only on-demand" rule.
8. LLM Provider — which was chosen, endpoint if LocalAI, status. No keys.
9. Threat model — what was consciously omitted — channels, ClawHub skills, hooks, multi-user, public exposure, Pi/Jarvis integration, smart home. Each with reference to project phase.
10. Open risks and TODO — exposed UFW ports, SSH tunnel as risk, no system-level isolation, no provider rate-limiting, no backup, prompt injection unsolved, skills/channels only after code review, CVE subscription.
11. Diagram — visual architecture showing trust boundaries.
12. Update policy — check version weekly. CVEs come fast (5 high in 3 months).

This file goes to the operator together with REPORT.md. For sharing with the sysadmin. Zero tokens, zero keys.

Step 11 — Final Report

In ~/openclaw-install-logs/REPORT.md:

1. OpenClaw version + comparison to CVE list (all patched?).
2. Node version.
3. Dashboard port.
4. Provider status.
5. SSH tunnel command ready with real values.
6. Dashboard URL with token — ONLY HERE, in REPORT.md (local, not shareable).
7. Service commands (status, start/stop/restart, logs, doctor, audit, sandbox explain, systemctl).
8. Output of openclaw security audit — full.
9. TODO for the operator — close exposed ports, verify dashboard, test exec approval, add provider key, plan backup, subscribe to advisories, close tunnel after work.
10. What was left undone and why — channels, skills, hooks, Pi/Jarvis, smart home, lab isolation.
11. Links to logs in ~/openclaw-install-logs/.

---

What To Do When Things Break

• openclaw: command not found — PATH. source ~/.bashrc, ~/.local/bin, ~/.openclaw/bin, npm config get prefix.
• openclaw doctor reports Node — version too old. NodeSource setup_24.x.
• Port 18789 occupied — change in config, restart gateway, update tunnel command.
• ss -tlnp shows 0.0.0.0:18789 — CRITICAL. STOP. Check gateway.host, restart, verify.
• Gateway won't start — openclaw logs --follow. Most common: no Node, bad JSON, port occupied.
• Dashboard "Gateway disconnected" — gateway crashed or token mismatch.
• WebSocket "Connection refused" — SSH tunnel dropped.
• npm install OOM — swap (step 0).
• security audit returns finding — full --json to the operator. Don't run --fix without approval.
• Anything else → STOP, document the symptom, notify the operator. Don't try alternative installation paths.

---

What NOT To Do

• ❌ Docker. Sysadmin advised against, plus typical docker setups bind on 0.0.0.0.
• ❌ Bind dashboard to 0.0.0.0. Open 18789 in UFW. Reverse proxy.
• ❌ Touch LocalAI.
• ❌ Configure channels (Telegram/Discord/WhatsApp/iMessage/Slack/Signal).
• ❌ Install skills from ClawHub. Cisco Talos: active malware in "What Would Elon Do?".
• ❌ Hooks.
• ❌ web_search/web_fetch/browser tools until rate-limit and sandbox are in place.
• ❌ Leave default exec.ask="off".
• ❌ Run OpenClaw as root.
• ❌ Paste tokens or API keys into ARCHITECTURE.md.
• ❌ Reference the fake Python project or 2023 blog posts.
• ❌ Work around errors with hacks. One failed attempt per the docs → ask the operator.
• ❌ Leave SSH tunnel 24/7. On-demand only.

---

External Audit Findings (sources)

• Microsoft Security Blog (2026-02-19): treat as "untrusted code execution with persistent credentials." Isolate, don't run on primary work machine.
• Kaspersky (2026-02-10): 512 vulns in late-Jan audit, 8 critical. Recommends Claude Opus 4.5. Allowlist-only ports.
• Cisco Talos (2026-01): "What Would Elon Do?" skill — 9 findings, 2 critical, active data exfiltration. ClawHub unmoderated.
• CrowdStrike (2026-02-18): direct + indirect prompt injection taxonomy. Falcon AIDR as runtime guardrail layer.
• Promptfoo (2026-03-12): controlled lab — malicious webpage induced agent to enumerate capabilities, read local docs, send false incident messages. Trust boundary = action boundary.
• Giskard (2026-02-26): OpenClaw mirrors known MCP attack patterns: over-privileged tools, plaintext secrets, no indirect injection testing.
• NVD / GitHub Advisories: CVE-2026-25253 (8.8 RCE), -24763 (8.8 sandbox bypass), -29613 (reverse proxy bypass), -33579 (8.1-9.8 priv esc), -26327 (7.1 auth bypass), -28478 (8.7 DoS). 138 CVEs in jgamblin/OpenClawCVEs.
• OpenClaw official docs/SECURITY.md: prompt injection out of bug bounty scope (intentionally). Defense = tool policy + exec approvals + sandbox + channel allowlists. Multi-tenant isolation not supported.

---

Good luck. Documentation > improvisation. Audits > marketing. When in doubt → WebFetch docs.openclaw.ai or ask the operator.