FAQ: Quick-Start and First-Run Setup for Neura Market

Quick-start and first-run Q&A. For everyday operations, models, auth, sessions, and troubleshooting see the main FAQ.

Quick start and first-run setup

I am stuck, fastest way to get unstuck

Run a local AI agent that can see your machine. Most "I'm stuck" cases are local config or environment issues a remote helper cannot inspect, so this beats asking in Discord.

• Claude Code: https://www.anthropic.com/claude-code/
• OpenAI Codex: https://openai.com/codex/

Give the agent the full source checkout via the hackable (git) install so it can read code + docs and reason about the exact version you run:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

Ask the agent to plan and supervise the fix step-by-step, then execute only the necessary commands - smaller diffs are easier to audit.

Share these outputs when asking for help (in Discord or a GitHub issue):

Found a real bug or fix? File an issue or send a PR: Issues / Pull requests.

Quick debug loop: First 60 seconds if something is broken. Install docs: Install, Installer flags, Updating.

Heartbeat keeps skipping. What do the skip reasons mean?

Older heartbeat tasks: blocks migrate to independently scheduled cron jobs with openclaw doctor --fix.

Docs: Heartbeat, Automation.

Recommended way to install and set up OpenClaw

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

From source (contributors/dev):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard

No global install yet? Run pnpm openclaw onboard instead. If Control UI assets are missing, onboarding tries to build them itself, falling back to pnpm ui:build.

How do I open the dashboard after onboarding?

Onboarding opens your browser to a clean (non-tokenized) dashboard URL right after setup and prints the link in the summary. Keep that tab open; if it did not launch, copy/paste the printed URL on the same machine.

How do I authenticate the dashboard on localhost vs remote?

Localhost (same machine):

• Open http://127.0.0.1:18789/.
• If it asks for shared-secret auth, paste the configured token or password into Control UI settings.
• Token source: gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN).
• Password source: gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
• No shared secret configured yet? Run openclaw doctor --generate-gateway-token (or openclaw doctor --fix --generate-gateway-token).

Not on localhost:

• Tailscale Serve (recommended): keep bind loopback, run openclaw gateway --tailscale serve, open https://<magicdns>/. With gateway.auth.allowTailscale: true, identity headers satisfy Control UI/WebSocket auth (no pasted shared secret, assumes a trusted gateway host); HTTP APIs still need shared-secret auth unless you deliberately use private-ingress none or trusted-proxy HTTP auth. Concurrent bad-auth Serve attempts from the same client are serialized before the failed-auth limiter records them, so a second bad retry can already show retry later.
• Identity-aware reverse proxy: keep the Gateway behind a trusted proxy, set gateway.auth.mode: "trusted-proxy", open the proxy URL. Same-host loopback proxies need explicit gateway.auth.trustedProxy.allowLoopback: true.
• SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@gateway-host, then open http://127.0.0.1:18789/. Shared-secret auth still applies over the tunnel; paste the configured token or password if prompted.

See Dashboard and Web surfaces for bind modes and auth details.

Why are there two exec approval configs for chat approvals?

They control different layers:

• approvals.exec - forwards approval prompts to chat destinations.
• channels.<channel>.execApprovals - makes that channel a native approval client for exec approvals.

The host exec policy is still the real approval gate; chat config only controls where prompts appear and how people answer them.

You rarely need both:

• If the chat already handles commands and replies, /approve in the same chat operates through the shared path.
• OpenClaw automatically turns on DM-first native approvals when a supported native channel can safely infer approvers and channels.<channel>.execApprovals.enabled is either unset or "auto".
• When native approval cards or buttons exist, that UI takes priority; only reference a manual /approve command if the tool output indicates chat approvals are not available.
• approvals.exec should be used only when prompts need to reach other chats or explicit ops rooms as well.
• channels.<channel>.execApprovals.target: "channel" or "both" is for when you want approval prompts posted back into the original room or topic.
• Plugin approvals work differently: same-chat /approve is the default, approvals.plugin forwarding is optional, and only certain native channels preserve native handling for those.

In short, forwarding handles routing, while native client config provides richer channel-specific UX. See Exec Approvals.

What runtime do I need?

You need Node 22.22.3+, 24.15+, or 25.9+ (Node 26 is recommended). pnpm serves as the repo's package manager. Bun can install dependencies and execute package scripts, but it cannot run the OpenClaw CLI or Gateway because node:sqlite is missing.

Does it run on Raspberry Pi?

Yes, but check RAM first: Pi 5 and Pi 4 (2 GB+) are ideal; Pi 3B+ (1 GB) works but runs slowly; Pi Zero 2 W (512 MB) is not advised.

The absolute floor is 1 GB RAM, 1 core, 500 MB free disk, and a 64-bit OS. Since the Pi only runs the Gateway (models call out to cloud APIs), even a modest Pi handles the load.

A small Pi/VPS can also host just the Gateway while you pair nodes on your laptop/phone for local screen/camera or command execution. A paired Mac can also present hosted widgets in its native panel. See Nodes.

Full setup walkthrough: Raspberry Pi.

Any tips for Raspberry Pi installs?

• Run a 64-bit OS; avoid 32-bit Raspberry Pi OS.
• On 2 GB or smaller boards, add swap.
• Choose a USB SSD over an SD card for better performance and durability.
• Go with the hackable (git) install so you can view logs and update quickly.
• Begin with no channels/skills, then add them one at a time.
• Odd binary failures ("exec format error") typically mean an optional skill tool lacks an ARM64 build.

Full guide: Raspberry Pi. Also see Linux.

It is stuck on wake up my friend / onboarding will not hatch. What now?

That screen depends on the Gateway being reachable and authenticated. The TUI also sends "Wake up, my friend!" automatically on first hatch when a model provider is configured. If you skipped model/auth setup, onboarding shows a "Model auth missing" note and opens the TUI without sending anything, so add a provider with openclaw configure --section model. If you see the wake-up line with no reply and tokens stay at 0, the agent never ran.

1. Restart the Gateway:

openclaw gateway restart

2. Check status + auth:

openclaw status
openclaw models status
openclaw logs --follow

3. Still hanging? Run:

openclaw doctor

If the Gateway is remote, confirm the tunnel/Tailscale connection is up and the UI points at the right Gateway. See Remote access.

Can I migrate my setup to a new machine without redoing onboarding?

Yes. Copy the state directory and workspace, then run Doctor once:

1. Install OpenClaw on the new machine.
2. Copy $OPENCLAW_STATE_DIR (default: ~/.openclaw) from the old machine.
3. Copy your workspace (default: ~/.openclaw/workspace).
4. Run openclaw doctor and restart the Gateway service.

This preserves config, auth profiles, WhatsApp creds, sessions, and memory, keeping your bot exactly the same, as long as you copy both locations. In remote mode, the gateway host owns the session store and workspace.

Important: if you only commit/push your workspace to GitHub, you back up memory + bootstrap files, but not session history or auth. Those live under ~/.openclaw/ (for example ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite).

Related: Migrating, Where things live on disk, Agent workspace, Doctor, Remote mode.

Where do I see what is new in the latest version?

Check the GitHub changelog: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

Newest entries are at the top. If the top section is Unreleased, the next dated section is the latest shipped version. Entries group under Highlights, Changes, and Fixes (plus docs/other sections when needed).

Cannot access docs.openclaw.ai (SSL error)

Some Comcast/Xfinity connections incorrectly block docs.openclaw.ai via Xfinity Advanced Security. Disable it or allowlist docs.openclaw.ai, then retry. Help us get it unblocked: https://spa.xfinity.com/check_url_status.

Still blocked? Docs are mirrored on GitHub: https://github.com/openclaw/openclaw/tree/main/docs

Difference between stable and beta

Stable and beta are npm dist-tags, not separate code lines:

• latest = stable
• beta = early build for testing (falls back to latest when beta is missing or older than the current stable release)

A stable release usually lands on beta first, then an explicit promotion step moves that same version to latest without changing the version number. Maintainers can also publish straight to latest. That is why beta and stable can point at the same version after promotion.

See what changed: CHANGELOG.md.

For install one-liners and the difference between beta and dev, see the next accordion.

How do I install the beta version and what is the difference between beta and dev?

Beta is the npm dist-tag beta (may match latest after promotion). Dev is the moving head of main (git); when published to npm it uses dist-tag dev.

One-liners (macOS/Linux):

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

Windows installer (PowerShell): iwr -useb https://openclaw.ai/install.ps1 | iex

For more details, see Development channels and Installer flags.

How do I try the latest bits?

Two choices:

1. Dev channel (existing install):

openclaw update --channel dev

This moves you to a git checkout of main, pulls the latest upstream changes, then compiles and installs the CLI from that checkout.

2. Hackable (git) install (fresh machine):

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

A manual clone is the preferred route:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

Documentation: Update, Development channels, Install.

How long does install and onboarding usually take?

Approximate timing:

• Install: 2-5 minutes.
• QuickStart onboarding: a few minutes (loopback gateway, auto token, default workspace).
• Advanced/full onboarding: longer when provider sign-in, channel pairing, daemon install, network downloads, or skills need extra setup.

The wizard displays this timeline upfront. Optional steps can be skipped and revisited later with openclaw configure.

Stuck? See I am stuck above.

Installer stuck? How do I get more feedback?

Re-run with --verbose:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --verbose
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta --verbose
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose

install.ps1 has no dedicated verbose switch; wrap it in Set-PSDebug -Trace 1 / -Trace 0 instead. Full flag reference: Installer flags.

Windows install says git not found or openclaw not recognized

Two common Windows issues:

1) npm error spawn git / git not found

• Install Git for Windows, ensure git is on PATH.
• Close and reopen PowerShell, then re-run the installer.

2) openclaw is not recognized after install

• Your npm global bin folder is not on PATH.
• Verify it: npm config get prefix.
• Add that directory to your user PATH (no \bin suffix needed; on most systems it is %AppData%\npm).
• Close and reopen PowerShell.

Prefer a desktop app? Use Windows Hub. Terminal-only setup: the PowerShell installer and WSL2 Gateway paths are both supported. Docs: Windows.

Windows exec output shows garbled Chinese text - what should I do?

Usually a console code page mismatch on native Windows shells.

Symptoms: system.run/exec output renders Chinese as mojibake; the same command looks fine in another terminal profile.

Workaround in PowerShell:

chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

Then restart the Gateway and retry:

openclaw gateway restart

Still reproducing this on latest OpenClaw? Track/report it: Issue #30640.

The docs did not answer my question - how do I get a better answer?

Use the hackable (git) install so you have the full source and docs locally, then ask your bot (or Claude/Codex) from that folder so it can read the repo and answer precisely.

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

More detail: Install and Installer flags.

How do I install OpenClaw on Linux?

• Linux quick path + service install: Linux.
• Full walkthrough: Getting Started.
• Installer + updates: Install & updates.

How do I install OpenClaw on a VPS?

Any Linux VPS works. Install on the server, then reach the Gateway over SSH/Tailscale.

Guides: exe.dev, Hetzner, Fly.io. Remote access: Gateway remote.

Where are the cloud/VPS install guides?

Hosting hub with common providers:

• VPS hosting (all providers in one place)
• Fly.io
• Hetzner
• exe.dev

In the cloud, the Gateway runs on the server and you access it from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace live on the server, so treat the host as the source of truth and back it up.

Pair nodes (Mac/iOS/Android/headless) to that cloud Gateway for local screen/camera or command execution on your laptop while the Gateway stays in the cloud.

Hub: Platforms. Remote access: Gateway remote. Nodes: Nodes, Nodes CLI.

Can I ask OpenClaw to update itself?

Possible, not recommended. The update flow can restart the Gateway (dropping the active session), may need a clean git checkout, and can prompt for confirmation. Safer to run updates from a shell as the operator.

openclaw update
openclaw update status
openclaw update --channel stable|extended-stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart

Automating from an agent:

openclaw update --yes --no-restart
openclaw gateway restart

Docs: Update, Updating.

What does onboarding actually do?

openclaw onboard is the setup path we recommend. In local mode it covers these steps:

1. Model/Auth - OAuth for providers, API keys, or manual authentication (local options such as LM Studio included); choose a default model.
2. Workspace - location plus bootstrap files.
3. Gateway - port, bind address, auth mode, Tailscale exposure.
4. Channels - built-in and official plugin chat channels: iMessage, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp, and more.
5. Web search - sets up an optional search provider.
6. Skills - installs recommended skills and optional dependencies.
7. Daemon - LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task.
8. Health check - starts the Gateway and verifies it is running.

It sets duration expectations up front and warns if your configured model is unknown or missing auth. Full breakdown: Onboarding (CLI).

Do I need a Claude or OpenAI subscription to run this?

No. Run OpenClaw with API keys (Anthropic/OpenAI/others) or local-only models so your data stays on your device. Subscriptions (Claude Pro/Max, ChatGPT/Codex) are optional ways to authenticate those providers.

For Anthropic: an API key gives standard pay-as-you-go billing; Claude CLI reuses an existing Claude Code login on the same host. Anthropic currently treats Claude CLI's non-interactive claude -p path as Agent SDK/programmatic usage that still draws from your subscription's plan limits - check current Anthropic billing docs before relying on subscription behavior. For long-lived gateway hosts and shared automation, an Anthropic API key is the more predictable choice.

OpenAI Codex OAuth (ChatGPT/Codex subscription) is fully supported for agent models. OpenClaw also supports hosted subscription-style options including Qwen Cloud Coding Plan, MiniMax Coding Plan, and Z.AI / GLM Coding Plan.

Docs: Anthropic, OpenAI, Qwen Cloud, MiniMax, Z.AI (GLM), Local models, Models.

Can I use Claude Max subscription without an API key?

Yes. OpenClaw supports Claude CLI reuse for Pro/Max/Team/Enterprise plans. Anthropic currently treats the claude -p path OpenClaw uses as subscription-plan usage subject to your plan's limits, not a separate free allowance - see Anthropic for the current billing detail and links to Anthropic's own support articles. For the most predictable server-side setup, use an Anthropic API key instead.

Do you support Claude subscription auth (Claude Pro or Max)?

Yes, via Claude CLI reuse. Anthropic's billing treatment of claude -p/Agent SDK usage has changed over time; see Anthropic for the current state and dated links to Anthropic's support articles before relying on specific billing behavior.

Anthropic setup-token auth is also still a supported token path, but OpenClaw prefers Claude CLI reuse and claude -p when available. For production or multi-user workloads, an Anthropic API key remains the safer, more predictable choice. Other subscription-style hosted options: OpenAI, Qwen Cloud, MiniMax, Z.AI (GLM).

Why am I seeing HTTP 429 rate_limit_error from Anthropic?

Your Anthropic quota/rate limit is exhausted for the current window. On Claude CLI, wait for the window to reset or upgrade your plan. On an Anthropic API key, check usage/billing in the Anthropic Console and raise limits as needed.

If the message is specifically Extra usage is required for long context requests, the request is trying to use Anthropic's 1M context window (a GA-capable 1M Claude 4.x model, or legacy params.context1m: true config), and your current credential is not eligible for long-context billing.

Set a fallback model so OpenClaw keeps replying while a provider is rate-limited. See Models, OAuth, and Anthropic 429 extra usage required for long context.

Is AWS Bedrock supported?

Yes. OpenClaw has a bundled Amazon Bedrock (Converse) provider. With AWS env markers present (AWS_ACCESS_KEY_ID, AWS_PROFILE, AWS_BEARER_TOKEN_BEDROCK), OpenClaw auto-enables the implicit Bedrock provider for model discovery; otherwise set plugins.entries.amazon-bedrock.config.discovery.enabled: true or add a manual provider entry. See Amazon Bedrock and Model providers. An OpenAI-compatible proxy in front of Bedrock is still a valid option if you prefer a managed key flow.

How does Codex auth work?

OpenClaw supports OpenAI Codex via OAuth (ChatGPT sign-in). A fresh setup with no primary model uses exact openai/gpt-5.6-sol for ChatGPT/Codex subscription auth plus native Codex app-server execution. Reauthentication preserves an existing explicit model, including openai/gpt-5.5. If the Codex workspace does not expose GPT-5.6, select openai/gpt-5.5 explicitly; OpenClaw does not silently downgrade. Legacy Codex-prefixed model refs are legacy config repaired by openclaw doctor --fix. Direct OpenAI API-key access remains available for non-agent OpenAI API surfaces and, through an ordered openai API-key profile, for agent models too. See Model providers and Onboarding (CLI).

Why does OpenClaw still mention legacy OpenAI Codex prefix?

openai is the current provider and auth-profile id for both OpenAI API keys and ChatGPT/Codex OAuth - OpenAI Codex is folded into it. You may still see a legacy openai-codex prefix in older config and migration warnings:

• openai/gpt-5.6-sol = fresh ChatGPT/Codex subscription setup with the native Codex runtime for agent turns.
• openai/gpt-5.5 = explicit supported selection for existing config or accounts without GPT-5.6 access.
• Legacy openai-codex/* model refs = legacy route repaired by openclaw doctor --fix.
• openai/gpt-5.5 plus an ordered openai API-key profile = API-key auth for an OpenAI agent model.
• Legacy openai-codex auth profile ids = legacy ids migrated by openclaw doctor --fix.

Want direct OpenAI Platform billing? Set OPENAI_API_KEY. Want ChatGPT/Codex subscription auth? Run openclaw models auth login --provider openai. Keep model refs under the canonical openai/* provider. Fresh subscription setup uses exact openai/gpt-5.6-sol; doctor repairs legacy Codex-prefixed refs without upgrading an explicit openai/gpt-5.5 selection.

Why can Codex OAuth limits differ from ChatGPT web?

Codex OAuth quota windows are managed by OpenAI and tied to your plan, so they may not match what you see on the ChatGPT website or app, even with the same account.

The currently visible provider usage and quota windows are displayed by openclaw models status, but this does not fabricate or convert ChatGPT-web entitlements into direct API access. For the direct OpenAI Platform billing and limits route, go through openai/* with an API key.

Do you support OpenAI subscription auth (Codex OAuth)?

Absolutely. OpenAI permits subscription OAuth usage in external tools and workflows such as OpenClaw. The onboarding process can execute the OAuth flow on your behalf.

Refer to OAuth, Model providers, and Onboarding (CLI).

Can I use Gemini CLI or Antigravity OAuth?

OpenClaw does not support setting up new Gemini CLI OAuth or Antigravity OAuth. Instead, connect Google using an AI Studio API key or Vertex AI.

The optional google-gemini-cli runtime stays available for advanced configurations that rely on a supported Google API-key profile. Existing valid legacy Gemini CLI OAuth profiles can still run for compatibility, but OpenClaw cannot create or fix them.

More info: Google, Model providers.

Is a local model OK for casual chats?

Generally, no. OpenClaw requires large context and strong safety; small cards truncate context and omit provider-side safety filters. If necessary, run the largest model build you can locally (LM Studio), see Local models. Smaller or quantized models increase prompt-injection risk, see Security.

How do I keep hosted model traffic in a specific region?

Choose endpoints pinned to a region. OpenRouter offers US-hosted options for MiniMax, Kimi, and GLM; pick the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these with models.mode: "merge" so fallbacks remain available while respecting the regioned provider you select.

Do I have to buy a Mac Mini to install this?

No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is a common always-on host choice, but a small VPS, home server, or Raspberry Pi-class box also works.

You only need a Mac for macOS-only tools. For iMessage, use iMessage with imsg on any Mac signed into Messages; if the Gateway runs on Linux or elsewhere, set channels.imessage.cliPath to an SSH wrapper that runs imsg on that Mac. For other macOS-only tools, run the Gateway on a Mac or pair a macOS node.

Docs: iMessage, Nodes, Mac remote mode.

Do I need a Mac mini for iMessage support?

You need some macOS device signed into Messages, not necessarily a Mac mini, any Mac works. Use iMessage with imsg; the Gateway can run on that Mac, or elsewhere with an SSH wrapper cliPath.

Common setups:

• Gateway on Linux/VPS, channels.imessage.cliPath set to an SSH wrapper that runs imsg on a Mac signed into Messages.
• Everything on one Mac for the simplest single-machine setup.

Docs: iMessage, Nodes, Mac remote mode.

If I buy a Mac mini to run OpenClaw, can I connect it to my MacBook Pro?

Yes. The Mac mini can run the Gateway, and your MacBook Pro connects as a node (companion device). Nodes do not run the Gateway; they add capabilities like screen/camera and system.run on that device. A Mac node can also present hosted widgets in its native panel.

Common pattern: Gateway on the always-on Mac mini; MacBook Pro runs the macOS app or a node host and pairs to the Gateway. Check with openclaw nodes status / openclaw nodes list.

Docs: Nodes, Nodes CLI.

Can I use Bun?

You can use Bun to install dependencies or run package scripts. The OpenClaw CLI and Gateway require Node because the canonical state store uses node:sqlite; Bun does not provide that API.

Telegram: what goes in allowFrom?

channels.telegram.allowFrom is the human sender's Telegram user ID (numeric), not the bot username. Setup asks for numeric user IDs only; openclaw doctor --fix can try to resolve legacy @username entries.

Safer (no third-party bot): DM your bot, run openclaw logs --follow, read from.id.

Official Bot API: DM your bot, call https://api.telegram.org/bot<bot_token>/getUpdates, read message.from.id.

Third-party (less private): DM @userinfobot or @getidsbot.

See Telegram access control.

Can multiple people use one WhatsApp number with different OpenClaw instances?

Yes, via multi-agent routing. Bind each sender's WhatsApp DM (peer: { kind: "direct", id: "+15551234567" }) to a different agentId, giving each person their own workspace and session store. Replies still come from the same WhatsApp account; DM access control (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) is global per account. See Multi-Agent Routing and WhatsApp.

Can I run a "fast chat" agent and an "Opus for coding" agent?

Yes. Multi-agent routing handles this: assign a distinct default model to each agent, then map incoming routes (a provider account or specific peers) to the relevant agent. See Multi-Agent Routing for a sample config. Also check Models and Configuration.

Does Homebrew work on Linux?

Yes, through Linuxbrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>

For OpenClaw under systemd, confirm the service PATH contains /home/linuxbrew/.linuxbrew/bin (or your brew prefix) so that tools installed via brew are found in non-login shells. Newer builds also add common user bin directories to Linux systemd services (such as ~/.local/bin, ~/.npm-global/bin, ~/.local/share/pnpm, ~/.bun/bin) and respect PNPM_HOME, NPM_CONFIG_PREFIX, BUN_INSTALL, VOLTA_HOME, ASDF_DATA_DIR, NVM_DIR, and FNM_DIR when those are defined.

Difference between the hackable git install and npm install

• Hackable (git) install: complete source checkout, modifiable, ideal for contributors. You compile locally and can edit code or docs.
• npm install: global CLI setup, no repository, best for "just run it." Updates arrive via npm dist-tags.

Docs: Getting started, Updating.

Can I switch between npm and git installs later?

Yes, using openclaw update --channel ... on an existing setup. Your data is not removed; only the OpenClaw code installation is altered. State (~/.openclaw) and workspace (~/.openclaw/workspace) remain unchanged.

npm to git:

openclaw update --channel dev

git to npm:

openclaw update --channel stable

Add --dry-run to see the intended mode switch before it happens. The updater executes Doctor follow-ups, refreshes plugin sources for the target channel, and restarts the gateway unless --no-restart is supplied.

Either mode can also be forced by the installer:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method npm

Backup tips: Where things live on disk.

Should I run the Gateway on my laptop or a VPS?

Need round-the-clock uptime? Go with a VPS. Prefer minimal hassle and can tolerate sleep/restarts? Run it on your local machine.

Laptop (local Gateway)

• Pros: no server expense, immediate access to local files, a live browser window.
• Cons: sleep or network drops disconnect it, OS updates/reboots interrupt it, must remain awake.

VPS / cloud

• Pros: always-on, dependable network, no laptop sleep problems, simpler to maintain.
• Cons: often headless (use screenshots), remote file access only, SSH needed for updates.

WhatsApp/Telegram/Slack/Mattermost/Discord all operate fine from a VPS; the real choice is headless browser versus a visible window. See Browser.

Default advice: pick a VPS if you have seen gateway disconnects before; local works well when you are actively using the Mac and want local file access or visible-browser UI automation.

How important is it to run OpenClaw on a dedicated machine?

Not mandatory, but suggested for reliability and isolation.

• Dedicated host (VPS/Mac mini/Raspberry Pi): always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
• Shared laptop/desktop: fine for testing and active use, but expect pauses when the machine sleeps or updates.

Best of both worlds: keep the Gateway on a dedicated host and connect your laptop as a node for local screen/camera/exec tools. See Nodes and Security.

What are the minimum VPS requirements and recommended OS?

• Absolute minimum: 1 vCPU, 1 GB RAM, ~500 MB disk.
• Recommended: 1-2 vCPU, 2 GB+ RAM for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.

OS: Ubuntu LTS (or any modern Debian/Ubuntu) - the best-tested Linux install path.

Docs: Linux, VPS hosting.

Can I run OpenClaw in a VM and what are the requirements?

Yes. Treat a VM like a VPS: it must be always on, reachable, and have enough RAM for the Gateway and any channels you enable.

• Absolute minimum: 1 vCPU, 1 GB RAM.
• Recommended: 2 GB+ RAM for multiple channels, browser automation, or media tools.
• OS: Ubuntu LTS or another modern Debian/Ubuntu.

On Windows, use Windows Hub for desktop setup, or WSL2 for a Linux-style Gateway VM with broad tooling compatibility. See Windows, VPS hosting. Running macOS in a VM: see macOS VM.

Related

• FAQ - the main FAQ (models, sessions, gateway, security, more)
• Install overview
• Getting started
• Troubleshooting