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

Quick start and first run questions and answers. For regular use, models, authentication, sessions, and troubleshooting, refer to the main FAQ.

Quick start and first-run setup

I am stuck, fastest way to get unstuck

Run a local AI agent with visibility into your system. Most problems come from local configuration or environment issues that a remote helper cannot see, so this approach works better than asking on Discord.

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

Provide the agent with the full source checkout using the hackable (git) install so it can examine code and documentation and reason about the exact version you are running:

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

Have the agent plan and supervise the fix one step at a time, then run only the commands that are needed. Smaller diffs are simpler to review.

When requesting help (on Discord or in a GitHub issue), share these outputs:

Found an actual bug or have a fix? Open an issue or submit a PR: Issues / Pull requests.

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

Heartbeat keeps skipping. What do the skip reasons mean?

Older heartbeat tasks: blocks transition to independently scheduled cron jobs using openclaw doctor --fix.

Documentation: 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 and developers):

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 attempts to build them automatically, falling back to pnpm ui:build.

How do I open the dashboard after onboarding?

After setup, onboarding opens your browser to a clean (non-tokenized) dashboard URL and prints the link in the summary. Keep that tab open. If the browser did not launch, copy and 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 prompted for shared secret authentication, 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 the bind on loopback, run openclaw gateway --tailscale serve, open https://<magicdns>/. With gateway.auth.allowTailscale: true, identity headers satisfy Control UI and WebSocket authentication (no pasted shared secret, assumes a trusted gateway host). HTTP APIs still require shared secret authentication unless you deliberately use private-ingress none or trusted-proxy HTTP auth. Concurrent bad authentication 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.
• Tailnet bind: run openclaw gateway --bind tailnet --token "<token>" (or configure password authentication), open http://<tailscale-ip>:18789/, paste the matching shared secret in dashboard settings.
• Identity-aware reverse proxy: place the Gateway behind a trusted proxy, set gateway.auth.mode: "trusted-proxy", open the proxy URL. Loopback proxies on the same host 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 authentication still applies over the tunnel. Paste the configured token or password if prompted.

See Dashboard and Web surfaces for bind modes and authentication 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 execution approvals.

The host execution policy remains the actual approval gate. Chat configuration only determines where prompts appear and how users respond to them.

You seldom need both options:

• If the chat already handles commands and replies, using same-chat /approve operates through the shared pathway.
• When a supported native channel can reliably determine approvers, OpenClaw automatically enables DM-first native approvals when channels.<channel>.execApprovals.enabled is not configured or "auto".
• Where native approval cards or buttons exist, that interface takes priority. Only suggest a manual /approve command if the tool output indicates chat approvals are not available.
• Use approvals.exec only when prompts must reach additional chats or explicit operations rooms.
• Apply channels.<channel>.execApprovals.target: "channel" or "both" only when you want approval prompts returned to the original room or topic.
• Plugin approvals work independently: same-chat /approve by default, optional approvals.plugin forwarding, and only certain native channels keep native handling for those as well.

In brief: forwarding handles routing, while native client configuration provides richer channel-specific experiences. Refer to Exec Approvals.

What runtime do I need?

Node 22.22.3+, 24.15+, or 25.9+ is mandatory (Node 24 is recommended). The repository uses pnpm as its 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+) perform best; Pi 3B+ (1 GB) functions but runs slowly; Pi Zero 2 W (512 MB) is not advised.

Minimum requirements: 1 GB RAM, 1 core, 500 MB free disk space, 64-bit OS. Since the Pi only runs the Gateway (models call out to cloud APIs), even a modest Pi handles the workload.

A small Pi or VPS can host just the Gateway while you pair nodes on your laptop or phone for local screen, camera, canvas, or command execution. See Nodes.

Complete setup guide: Raspberry Pi.

Any tips for Raspberry Pi installs?

• Run a 64-bit OS; avoid 32-bit Raspberry Pi OS.
• Add swap on boards with 2 GB or less.
• Choose a USB SSD over an SD card for better performance and durability.
• Pick the hackable (git) install to view logs and update quickly.
• Begin without channels or skills, then add them one at a time.
• Strange binary failures ("exec format error") usually indicate a missing ARM64 build for an optional skill tool.

Full guide: Raspberry Pi. Also see Linux.

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

That screen requires the Gateway to be 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 or auth setup, onboarding shows a "Model auth missing" notice and opens the TUI without sending anything. Add a provider with openclaw configure --section model. If you see the wake-up line with no reply and tokens remain at 0, the agent never executed.

1. Restart the Gateway:

openclaw gateway restart

2. Check status and auth:

openclaw status
openclaw models status
openclaw logs --follow

3. Still stuck? Run:

openclaw doctor

If the Gateway is remote, verify the tunnel or Tailscale connection is active and the UI points to the correct 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 configuration, auth profiles, WhatsApp credentials, sessions, and memory. It keeps your bot identical, as long as you copy both locations. In remote mode, the gateway host owns the session store and workspace.

Important: if you only commit or push your workspace to GitHub, you back up memory and bootstrap files, but not session history or auth. Those reside 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?

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

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

Cannot access docs.openclaw.ai (SSL error)

Some Comcast or Xfinity connections incorrectly block docs.openclaw.ai via Xfinity Advanced Security. Disable it or allowlist docs.openclaw.ai, then try again. 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 typically lands on beta first, then an explicit promotion step moves that same version to latest without changing the version number. Maintainers can also publish directly to latest. That is why beta and stable can point to 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

More detail: Development channels and Installer flags.

How do I try the latest bits?

Two choices:

1. Dev channel (existing install):

openclaw update --channel dev

This method converts the installation to a git checkout of main, performs a rebase against upstream, then builds 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 recommended:

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

Docs: Update, Development channels, Install.

How long does install and onboarding usually take?

Approximate time estimates:

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

The wizard displays this timeline upfront. Skip any optional steps and come back later with openclaw configure.

Stuck? See I am stuck above.

Installer stuck? How do I get more feedback?

Run again 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 flag; instead, wrap it in Set-PSDebug -Trace 1 / -Trace 0. Full flag reference: Installer flags.

Windows install says git not found or openclaw not recognized

Two common problems on Windows:

1) npm error spawn git / git not found

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

2) openclaw is not recognized after install

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

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

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

Usually caused by a console code page mismatch on native Windows shells.

Symptoms: system.run/exec output shows Chinese characters as mojibake, but the same command renders correctly in a different 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 try again:

openclaw gateway restart

Still seeing this on the latest OpenClaw? Track or report it: Issue #30640.

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

Use the hackable (git) install to get the full source and docs locally, then ask your bot (or Claude/Codex) from that folder so it can read the repo and give precise answers.

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 with service install: Linux.
• Complete walkthrough: Getting Started.
• Installer and updates: Install & updates.

How do I install OpenClaw on a VPS?

Any Linux VPS works. Install on the server, then access the Gateway over SSH or 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 reach it from your laptop or phone through the Control UI (or Tailscale/SSH). Your state and 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, canvas, 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, but not recommended. The update process can restart the Gateway (dropping the active session), may require 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 preferred method for initial configuration. In local mode, it guides you through:

1. Model/Auth - provider OAuth, API keys, or manual authentication (including local alternatives like LM Studio); choose a default model.
2. Workspace - location and bootstrap files.
3. Gateway - port, bind address, authentication 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 others.
5. Daemon - LaunchAgent (macOS), systemd user unit (Linux/WSL2), or native Windows Scheduled Task.
6. Health check - launches the Gateway and confirms it is operational.
7. Skills - installs recommended skills and optional dependencies.

It communicates expected duration upfront and alerts you if the configured model is unrecognized or missing authentication. Complete details: 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 remains on your machine. Subscriptions (Claude Pro/Max, ChatGPT/Codex) are optional methods for authenticating those providers.

For Anthropic: an API key provides standard pay-as-you-go billing; Claude CLI reuses an existing Claude Code login on the same machine. Anthropic currently treats Claude CLI's non-interactive claude -p path as Agent SDK/programmatic usage that still counts against your subscription's plan limits - check current Anthropic billing documentation before depending on subscription behavior. For long-lived gateway hosts and shared automation, an Anthropic API key offers more predictable billing.

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

Documentation: 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 that OpenClaw uses as subscription-plan usage subject to your plan's limits, not a separate free allowance - see Anthropic for the latest billing information and links to Anthropic's 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, through 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 authentication remains 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 is 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 attempting 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 continues responding while a provider is rate-limited. See Models, OAuth, and Anthropic 429 extra usage required for long context.

Is AWS Bedrock supported?

Yes. OpenClaw includes a bundled Amazon Bedrock (Converse) provider. With AWS environment markers present (AWS_ACCESS_KEY_ID, AWS_PROFILE, AWS_BEARER_TOKEN_BEDROCK), OpenClaw automatically 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 remains a valid option if you prefer a managed key flow.

How does Codex auth work?

OpenClaw supports OpenAI Codex through OAuth (ChatGPT sign-in). A fresh setup with no primary model uses exact openai/gpt-5.6-sol for ChatGPT/Codex subscription authentication 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 references are legacy configuration 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 identifier for both OpenAI API keys and ChatGPT/Codex OAuth - OpenAI Codex is integrated into it. You may still see a legacy openai-codex prefix in older configuration 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 configuration or accounts without GPT-5.6 access.
• Legacy openai-codex/* model references = legacy route repaired by openclaw doctor --fix.
• openai/gpt-5.5 plus an ordered openai API-key profile = API-key authentication for an OpenAI agent model.
• Legacy openai-codex auth profile identifiers = legacy identifiers migrated by openclaw doctor --fix.

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

Why can Codex OAuth limits differ from ChatGPT web?

Codex OAuth enforces quota windows managed by OpenAI and tied to your plan, which may behave differently from what you see in the ChatGPT website or app, even when using the same account.

openclaw models status displays the current provider usage and quota windows visible to you, but it does not create or normalize ChatGPT web entitlements as direct API access. To go through the OpenAI Platform billing and limits path directly, use openai/* along with an API key.

Do you support OpenAI subscription auth (Codex OAuth)?

Absolutely, it is fully supported. 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).

How do I set up Gemini CLI OAuth?

Gemini CLI relies on a plugin auth flow rather than a client ID or secret stored in openclaw.json.

1. Install Gemini CLI locally so that gemini is available on PATH:
   • Homebrew: brew install gemini-cli
   • npm: npm install -g @google/gemini-cli
2. Activate the plugin: openclaw plugins enable google
3. Sign in: openclaw models auth login --provider google-gemini-cli --set-default
4. After signing in, the default model is google/gemini-3.1-pro-preview (at runtime google-gemini-cli)
5. If requests fail after login, set GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID on the gateway host and attempt again.

OAuth tokens reside in auth profiles on the gateway host. More information: Google, Model providers.

Is a local model OK for casual chats?

Typically not. OpenClaw requires large context windows and strong safety measures; small cards shorten context and bypass safety filters on the provider side. If you must proceed, run the largest model build you can locally using LM Studio. See Local models. Smaller or quantized models increase the risk of prompt injection. Refer to Security.

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

Select endpoints that are pinned to a specific region. OpenRouter provides US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data within that region. You can still list Anthropic or OpenAI alongside these using models.mode: "merge", so fallbacks remain available while honoring the regioned provider you pick.

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

No. OpenClaw operates on macOS or Linux, with Windows supported through WSL2. A Mac mini is a popular choice for an always-on host, but a small VPS, home server, or a Raspberry Pi-class machine will also work.

You only require a Mac for macOS-specific 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 attach a macOS node.

Documentation: 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 using an SSH wrapper cliPath.

Common configurations:

• Gateway on Linux or a VPS, with 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 arrangement.

Documentation: 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 such as screen, camera, canvas, and system.run on that device.

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

Documentation: Nodes, Nodes CLI.

Can I use Bun?

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

Telegram: what goes in allowFrom?

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

For a safer approach without third-party bots: DM your bot, run openclaw logs --follow, and read from.id.

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

For a third-party method with less privacy: DM @userinfobot or @getidsbot.

Refer to the documentation on Telegram access control.

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

Absolutely, using multi-agent routing. Link each sender's WhatsApp DM (peer: { kind: "direct", id: "+15551234567" }) to a separate agentId, which provides each user with their own workspace and session store. Replies are sent from the same WhatsApp account; DM access control (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) applies globally to the entire account. For more details, check Multi-Agent Routing and WhatsApp.

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

Yes. Apply multi-agent routing by assigning a distinct default model to each agent, then connect inbound routes (whether from a provider account or specific peers) to the corresponding agent. An example configuration is available at Multi-Agent Routing. Also consult 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>

If you run OpenClaw under systemd, make sure the service PATH includes /home/linuxbrew/.linuxbrew/bin (or your brew prefix) so tools installed via brew are found in non-login shells. Recent builds also automatically add common user binary directories on 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 variables are defined.

Difference between the hackable git install and npm install

• Hackable (git) install: a full source checkout that you can edit directly, ideal for contributors. You build locally and can modify code or documentation.
• npm install: a global CLI installation without a repository, meant for users who just want to run it. Updates come through npm dist-tags.

See the Getting started and Updating guides.

Can I switch between npm and git installs later?

Yes, using openclaw update --channel ... on an existing installation. This process does not remove your data; only the OpenClaw code installation is changed. Your state (~/.openclaw) and workspace (~/.openclaw/workspace) remain unaffected.

Switching from npm to git:

openclaw update --channel dev

Switching from git to npm:

openclaw update --channel stable

Add --dry-run to first preview the intended mode change. The updater runs Doctor follow-up checks, refreshes plugin sources for the target channel, and restarts the gateway unless you include --no-restart.

The installer can also force either mode:

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

For backup advice, see Where things live on disk.

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

Need round-the-clock reliability? Go with a VPS. Prefer minimal hassle and can tolerate sleep or restarts? Run it locally.

Laptop (local Gateway)

• Pros: no server costs, direct access to local files, and a live browser window.
• Cons: sleep or network drops disconnect it, OS updates and reboots cause interruptions, and the laptop must stay awake.

VPS / cloud

• Pros: always on, stable network, no laptop sleep issues, and easier to maintain.
• Cons: often headless (rely on screenshots), remote file access only, and SSH required for updates.

WhatsApp, Telegram, Slack, Mattermost, and Discord all work fine from a VPS; the main trade-off is between a headless browser and a visible window. See Browser.

Default recommendation: choose a VPS if you have experienced gateway disconnects before; local is a good option when you are actively using the Mac and need local file access or visible-browser UI automation.

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

Not mandatory, but advised for better reliability and isolation.

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

For the best of both approaches, run the Gateway on a dedicated host and connect your laptop as a node for local screen, camera, or exec tools. See Nodes and Security.

What are the minimum VPS requirements and recommended OS?

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

Operating system: Ubuntu LTS (or any modern Debian or Ubuntu) provides the best-tested Linux installation path.

Refer to Linux and VPS hosting for details.

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

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

• 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 or Ubuntu.

On Windows, use Windows Hub for a desktop setup, or WSL2 for a Linux-style Gateway VM with broad tooling compatibility. See Windows and VPS hosting. For running macOS inside a VM, see macOS VM.

Related

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