OpenClaw 2.0: An Easier Setup, With a Few Upgrade Traps

OpenClaw 2.0 is much easier to install, but I would still treat an upgrade as a small change-management project. Back up your state, run the migration from a real terminal, and test one existing workflow before giving the agent broader access.

I installed and upgraded OpenClaw 2.0 recently. The first-run experience is smoother, but the upgrade is not something I would run blindly on a machine that already has sessions, plugins, or custom skills.

The release is tagged v2026.8.1 and shipped around August 30–31, 2026. The 2.0 label reflects a large consolidated release rather than a normal semantic-version jump.

What OpenClaw actually runs

OpenClaw is a free, open-source (MIT License), self-hosted autonomous AI agent / personal assistant that runs primarily on your own hardware (macOS, Linux, Windows, with WSL2 recommended on Windows). Unlike pure chatbots such as ChatGPT that live in a browser tab and only suggest actions, OpenClaw executes real tasks: managing files, controlling browsers, sending messages across WhatsApp, Telegram, Slack, Discord, Signal, iMessage and other channels, automating workflows, and maintaining persistent memory.

It began life in late 2025 (initially as Warelay / related projects) under Peter Steinberger and the community, rebranded and open-sourced, and is now stewarded under the OpenClaw Foundation. The architecture centers on a local Gateway (control plane for sessions, tools, events, and channels), a Control UI / CLI / TUI, messaging channel plugins, and optional companion apps. Models can be hosted (OpenAI, Anthropic, Google, etc.), subscription-backed, or fully local (Ollama, LM Studio, llama.cpp). State and credentials stay under user control.

What feels better in 2.0

First-time setup now detects resources already present on the machine: existing ChatGPT, Claude, or Codex logins/subscriptions, API keys, and qualifying local models (Ollama, LM Studio). The installer verifies that the chosen model can actually complete a request before saving credentials, then moves most remaining configuration out of the initial wizard. Users reach a first conversation faster and finish setup by talking to the agent itself.

Default OpenAI-oriented setups lean toward recent models (coverage mentions GPT-5.6 defaults in places); local paths improved (e.g., hosted llama-server replacing older node-llama-cpp paths, higher default context lengths).

The browser app was rebuilt as a first-class surface. It opens directly into a conversation. The old Overview page is gone; sessions live in a sidebar. Files, approvals, terminals, git diffs, and a dockable browser panel sit alongside the chat. A “Session Rail” provides compact live status (progress, ratings, plan steps, pull requests). Interactive widgets can be pinned to session dashboards, granted scoped actions or network origins, and exported. Performance claims in simulated environments include reduced JavaScript requests (140 → 45) and faster startup (~1.6 s → ~575 ms).

The headline collaboration feature: multiple users can join the same ongoing agent session with full context, assign tasks, suggest changes, work in draft mode, or participate fully. Access levels are controllable by owners/admins. Sessions can run on the local Gateway, paired devices (openclaw connect), or disposable cloud machines via provisioning tools (AWS, Hetzner, etc.). Important caveat from the project: these are collaboration controls, not hostile-tenant isolation or network/file-system security boundaries.

Built-in Memory now owns core search and recall (the QMD add-on is retired via supported migration). Background consolidation (“grounded dreaming”) promotes provenance-qualified material into long-term memory (with a Dream Diary and an explicit off switch). Self-learning can turn strong reusable lessons into proposed skills. Full-text conversation search is available. Explicit controls such as openclaw memory forget exist. Sessions persist more durably across idle periods and day boundaries by default.

A Skill Workshop provides a guided path to create, validate, install, call, and review skills, with applied history and individual reporting of invalid skills instead of catalog breakage. Automations can stay linked to the conversation that created them; recurring actions can use one-time approval. IMAP plugins can trigger agent work from incoming email. Interactive widgets and durable progress cards turn the UI into a true control surface.

Approvals now bind more tightly to the exact request, command, session, and person. Reusable command permissions can bind to exact arguments and working directory; script-backed commands re-check reviewed bytes. Sessions support explicit modes: read-only, guarded, workspace, or full access. A team credential store keeps certain secret values write-only; agents can request credentials via masked prompts that never enter model-visible text. Plugin installs from arbitrary executable sources require an explicit force flag. These are meaningful steps after earlier security advisories, yet critics note remaining gaps (detailed in the risks section).

Install it without making the first mistake

• Node.js 22.22.3+, 24.15+, or 25.9+ (Node 26 recommended; installers often provision a suitable version)
• macOS, Linux, or Windows (WSL2 strongly recommended for the Gateway on Windows)
• Optional: pnpm if building from source

Desktop companions:

• Windows Hub (signed installers for x64/arm64)
• macOS menu-bar app (DMG/ZIP from GitHub releases)

The official installer is the simplest route:

macOS / Linux / WSL2:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows (PowerShell):

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

The script detects the OS, installs Node if needed, installs OpenClaw, and launches onboarding. Flags exist for --no-onboard and other automation options.

• npm (Node already managed):

npm install -g openclaw@latest --allow-scripts=openclaw # adjust for older npm
openclaw onboard --install-daemon

• pnpm or bun equivalents with appropriate trust/allow-build flags
• From source (contributors):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
corepack enable
pnpm install && pnpm build && pnpm ui:build
pnpm add --global "openclaw@link:$PWD"
openclaw onboard --install-daemon

• Local-prefix installer and container/VPS options are documented for advanced deployments.

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard # or open http://127.0.0.1:18789/ on the gateway host

Managed startup uses LaunchAgents (macOS), systemd user services (Linux/WSL2), or Scheduled Tasks (native Windows). Full details live in the official install documentation.

If you are upgrading, slow down

1. Create a verified backup of your OpenClaw state directory, configuration, sessions, and any custom plugins/skills.
2. Review the official release notes (docs.openclaw.ai/releases/2026.8.1) and updating guides.
3. Prefer an interactive terminal (TTY) for the upgrade and doctor steps—early reports showed non-interactive doctor --fix could silently skip 2.0 migrations.

• Sessions & transcripts → SQLite: New sessions after migration will not appear in older releases on downgrade. Backup first.
• Bundled OpenProse plugin & /prose command removed: Run openclaw doctor --fix; follow upstream Agent Skill migration. Existing .prose files are retained.
• codex/* and openai-codex/* model refs → openai/*: openclaw doctor --fix migrates routes, provider config, stored sessions, and automations. Conflicts flagged for manual repair.
• Plugin SDK subpath deprecations: September 1, 2026 gates; update plugins per the SDK migration guide.

Most cleanup is handled by openclaw doctor --fix (or --repair). After upgrade, re-evaluate per-session permission modes (prefer least privilege) and re-apply any hardening checklist from prior advisories.

• doctor --fix skipping migrations without a TTY (P1, fix reported quickly)
• Memory sync issues with certain embedding providers (e.g., Gemini batch limits)
• Plugin consent persistence for legacy installs
• Dashboard readiness false positives

A release of this magnitude typically sees follow-up patches; monitor the official tracker and release notes.

The security settings I would check first

The Register and others noted that while usability improved dramatically, “security by default” did not fully accompany it:

• Shared session controls are not network- or filesystem-level isolation / tenant boundaries.
• Secret Store values (passwords, API keys) are not encrypted at rest; they rely on filesystem permissions of the state directory.
• The sandbox for isolating untrusted code is not enabled by default.

Earlier 2026 analyses (pre-2.0) already documented risks around plaintext credentials, prompt injection leading to destructive actions, high-severity CVEs, and supply-chain concerns in the skills marketplace (ClawHub). 2.0 strengthens approval binding and permission modes, but operators remain responsible for least-privilege configuration, network isolation, secret management, and sandbox enablement. Granting a capable agent broad system and credential access should never be done lightly.

Using CometAPI for model access

OpenClaw accepts official provider keys, local models, or a unified gateway. CometAPI provides access to 500+ models under one key, with OpenAI-compatible, Anthropic-messages, and Google-generative-ai endpoints, model switching, and centralized observability. The source describes pricing as often 20%+ below list, rather than a fixed discount for every model.

1. Obtain a CometAPI key from cometapi.com.
2. Store it securely (e.g., COMETAPI_KEY in ~/.openclaw/.env with restricted permissions, or your preferred secret manager).
3. Edit ~/.openclaw/openclaw.json (or equivalent) to add providers, for example:

{
"agents": {
"defaults": {
"model": {
"primary": "cometapi-claude/claude-sonnet-4-6"
}
}
},
"models": {
"mode": "merge",
"providers": {
"cometapi-openai": {
"baseUrl": "https://api.cometapi.com/v1",
"apiKey": "${COMETAPI_KEY}",
"api": "openai-completions",
"models": [{ "id": "gpt-5.4", "name": "GPT-5.4" }]
},
"cometapi-claude": {
"baseUrl": "https://api.cometapi.com",
"apiKey": "${COMETAPI_KEY}",
"api": "anthropic-messages",
"models": [{ "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" }]
},
"cometapi-google": {
"baseUrl": "https://api.cometapi.com/v1beta",
"apiKey": "${COMETAPI_KEY}",
"api": "google-generative-ai",
"models": [{ "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" }]
}
}
}
}

(Exact model IDs and paths should be verified against current CometAPI and OpenClaw documentation, as catalogs evolve.) Use full provider/model references in sessions. After changes, restart the Gateway and verify with a test conversation.

This setup keeps OpenClaw’s self-hosted control plane intact while allowing model changes without separate vendor credentials. The software is MIT-licensed and free; hosted model usage or local compute still has a cost. Keep the official release notes and security advisories in the upgrade process, and verify the latest documentation before production deployment.

Final take

OpenClaw 2.0 is easier to start and more pleasant to use every day. The trade-off is that it now exposes more of the decisions an operator has to make: permissions, session sharing, secrets, plugins, and migration behavior.

My rule is simple: treat a new install as a quick setup, but treat an upgrade as a small change-management project. Back up first, run the doctor command from a real terminal, test one existing workflow, and only then open the door to broader access.

Disclosure: This article is adapted from research originally published by the CometAPI team.