Skip to main content

​
FAQ

Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see Troubleshooting. For the full config reference, see Configuration.

​
Table of contents

​
First 60 seconds if something’s broken

  1. Quick status (first check) 
    openclaw status
    Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when gateway is reachable).
  2. Pasteable report (safe to share) 
    openclaw status --all
    Read-only diagnosis with log tail (tokens redacted).
  3. Daemon + port state 
    openclaw gateway status
    Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used.
  4. Deep probes 
    openclaw status --deep
    Runs gateway health checks + provider probes (requires a reachable gateway). See Health.
  5. Tail the latest log 
    openclaw logs --follow
    If RPC is down, fall back to: 
    tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
    File logs are separate from service logs; see Logging and Troubleshooting.
  6. Run the doctor (repairs) 
    openclaw doctor
    Repairs/migrates config/state + runs health checks. See Doctor.
  7. Gateway snapshot 
    openclaw health --json
openclaw health --verbose   # shows the target URL + config path on errors
    Asks the running gateway for a full snapshot (WS-only). See Health.

​
Quick start and first-run setup

​
Im stuck whats the fastest way to get unstuck

Use a local AI agent that can see your machine. That is far more effective than asking in Discord, because most “I’m stuck” cases are local config or environment issues that remote helpers cannot inspect. These tools can read the repo, run commands, inspect logs, and help fix your machine-level setup (PATH, services, permissions, auth files). Give them the full source checkout via the hackable (git) install: 
curl -fsSL https://open-claw.blog/install.sh | bash -s -- --install-method git
This installs OpenClaw from a git checkout, so the agent can read the code + docs and reason about the exact version you are running. You can always switch back to stable later by re-running the installer without --install-method git. Tip: ask the agent to plan and supervise the fix (step-by-step), then execute only the necessary commands. That keeps changes small and easier to audit. If you discover a real bug or fix, please file a GitHub issue or send a PR: https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls Start with these commands (share outputs when asking for help): 
openclaw status
openclaw models status
openclaw doctor
What they do:
  • openclaw status: quick snapshot of gateway/agent health + basic config.
  • openclaw models status: checks provider auth + model availability.
  • openclaw doctor: validates and repairs common config/state issues.
Other useful CLI checks: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose. Quick debug loop: First 60 seconds if something’s broken. Install docs: Install, Installer flags, Updating. The repo recommends running from source and using the onboarding wizard: 
curl -fsSL https://open-claw.blog/install.sh | bash
openclaw onboard --install-daemon
The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port 18789. From source (contributors/dev): 
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
openclaw onboard
If you don’t have a global install yet, run it via pnpm openclaw onboard.

​
How do I open the dashboard after onboarding

The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine. Tokens stay local to your host-nothing is fetched from the browser.

​
How do I authenticate the dashboard token on localhost vs remote

Localhost (same machine):
  • Open http://127.0.0.1:18789/.
  • If it asks for auth, run openclaw dashboard and use the tokenized link (?token=...).
  • The token is the same value as gateway.auth.token (or OPENCLAW_GATEWAY_TOKEN) and is stored by the UI after first load.
Not on localhost:
  • Tailscale Serve (recommended): keep bind loopback, run openclaw gateway --tailscale serve, open https://<magicdns>/. If gateway.auth.allowTailscale is true, identity headers satisfy auth (no token).
  • Tailnet bind: run openclaw gateway --bind tailnet --token "<token>", open http://<tailscale-ip>:18789/, paste token in dashboard settings.
  • SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/?token=... from openclaw dashboard.
See Dashboard and Web surfaces for bind modes and auth details.

​
What runtime do I need

Node >= 22 is required. pnpm is recommended. Bun is not recommended for the Gateway.

​
Does it run on Raspberry Pi

Yes. The Gateway is lightweight - docs list 512MB-1GB RAM, 1 core, and about 500MB disk as enough for personal use, and note that a Raspberry Pi 4 can run it. If you want extra headroom (logs, media, other services), 2GB is recommended, but it’s not a hard minimum. Tip: a small Pi/VPS can host the Gateway, and you can pair nodes on your laptop/phone for local screen/camera/canvas or command execution. See Nodes.

​
Any tips for Raspberry Pi installs

Short version: it works, but expect rough edges.
  • Use a 64-bit OS and keep Node >= 22.
  • Prefer the hackable (git) install so you can see logs and update fast.
  • Start without channels/skills, then add them one by one.
  • If you hit weird binary issues, it is usually an ARM compatibility problem.
Docs: Linux, Install.

​
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. If you see that line with no reply and tokens stay at 0, the agent never ran.
  1. Restart the Gateway:
openclaw gateway restart
  1. Check status + auth:
openclaw status
openclaw models status
openclaw logs --follow
  1. If it still hangs, run:
openclaw doctor
If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI is pointed at the right Gateway. See Remote access.

​
Can I migrate my setup to a new machine Mac mini without redoing onboarding

Yes. Copy the state directory and workspace, then run Doctor once. This keeps your bot “exactly the same” (memory, session history, auth, and channel state) as long as you copy both locations:
  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.
That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you’re in remote mode, remember the gateway host owns the session store and workspace. Important: if you only commit/push your workspace to GitHub, you’re backing up memory + bootstrap files, but not session history or auth. Those live under ~/.openclaw/ (for example ~/.openclaw/agents/<agentId>/sessions/). Related: Migrating, Where things live on disk, Agent workspace, Doctor, Remote mode.

​
Where do I see whats 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 marked Unreleased, the next dated section is the latest shipped version. Entries are grouped by Highlights, Changes, and Fixes (plus docs/other sections when needed).

​
I cant access docs.open-claw.blog SSL error What now

Some Comcast/Xfinity connections incorrectly block docs.open-claw.blog via Xfinity Advanced Security. Disable it or allowlist docs.open-claw.blog, then retry. More detail: Troubleshooting. Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status. If you still can’t reach the site, the docs are mirrored on GitHub: https://github.com/openclaw/openclaw/tree/main/docs

​
What’s the difference between stable and beta

Stable and beta are npm dist‑tags, not separate code lines:
  • latest = stable
  • beta = early build for testing
We ship builds to beta, test them, and once a build is solid we promote that same version to latest. That’s why beta and stable can point at the same version. See what changed:
https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

​
How do I install the beta version and whats the difference between beta and dev

Beta is the npm dist‑tag beta (may match latest).
Dev is the moving head of main (git); when published, it uses the npm dist‑tag dev. One‑liners (macOS/Linux): 
curl -fsSL --proto '=https' --tlsv1.2 https://open-claw.blog/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://open-claw.blog/install.sh | bash -s -- --install-method git
Windows installer (PowerShell): https://open-claw.blog/install.ps1 More detail: Development channels and Installer flags.

​
How long does install and onboarding usually take

Rough guide:
  • Install: 2-5 minutes
  • Onboarding: 5-15 minutes depending on how many channels/models you configure
If it hangs, use Installer stuck and the fast debug loop in Im stuck.

​
How do I try the latest bits

Two options:
  1. Dev channel (git checkout):
openclaw update --channel dev
This switches to the main branch and updates from source.
  1. Hackable install (from the installer site):
curl -fsSL https://open-claw.blog/install.sh | bash -s -- --install-method git
That gives you a local repo you can edit, then update via git. If you prefer a clean clone manually, use: 
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
Docs: Update, Development channels, Install.

​
Installer stuck How do I get more feedback

Re-run the installer with verbose output: 
curl -fsSL https://open-claw.blog/install.sh | bash -s -- --verbose
Beta install with verbose: 
curl -fsSL https://open-claw.blog/install.sh | bash -s -- --beta --verbose
For a hackable (git) install: 
curl -fsSL https://open-claw.blog/install.sh | bash -s -- --install-method git --verbose
More options: 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 and make sure git is on your 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.
  • Check the path: 
    npm config get prefix
  • Ensure <prefix>\\bin is on PATH (on most systems it is %AppData%\\npm).
  • Close and reopen PowerShell after updating PATH.
If you want the smoothest Windows setup, use WSL2 instead of native Windows. Docs: Windows.

​
The docs didnt 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 https://open-claw.blog/install.sh | bash -s -- --install-method git
More detail: Install and Installer flags.

​
How do I install OpenClaw on Linux

Short answer: follow the Linux guide, then run the onboarding wizard.

​
How do I install OpenClaw on a VPS

Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway. Guides: exe.dev, Hetzner, Fly.io.
Remote access: Gateway remote.

​
Where are the cloudVPS install guides

We keep a hosting hub with the common providers. Pick one and follow the guide: How it works 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. You can pair nodes (Mac/iOS/Android/headless) to that cloud Gateway to access local screen/camera/canvas or run commands on your laptop while keeping the Gateway in the cloud. Hub: Platforms. Remote access: Gateway remote. Nodes: Nodes, Nodes CLI.

​
Can I ask OpenClaw to update itself

Short answer: possible, not recommended. The update flow can restart the Gateway (which drops the active session), may need a clean git checkout, and can prompt for confirmation. Safer: run updates from a shell as the operator. Use the CLI: 
openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart
If you must automate from an agent: 
openclaw update --yes --no-restart
openclaw gateway restart
Docs: Update, Updating.

​
What does the onboarding wizard actually do

openclaw onboard is the recommended setup path. In local mode it walks you through:
  • Model/auth setup (Anthropic setup-token recommended for Claude subscriptions, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)
  • Workspace location + bootstrap files
  • Gateway settings (bind/port/auth/tailscale)
  • Providers (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)
  • Daemon install (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
  • Health checks and skills selection
It also warns if your configured model is unknown or missing auth.

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

No. You can run OpenClaw with API keys (Anthropic/OpenAI/others) or with local‑only models so your data stays on your device. Subscriptions (Claude Pro/Max or OpenAI Codex) are optional ways to authenticate those providers. Docs: Anthropic, OpenAI, Local models, Models.

​
Can I use Claude Max subscription without an API key

Yes. You can authenticate with a setup-token instead of an API key. This is the subscription path. Claude Pro/Max subscriptions do not include an API key, so this is the correct approach for subscription accounts. Important: you must verify with Anthropic that this usage is allowed under their subscription policy and terms. If you want the most explicit, supported path, use an Anthropic API key.

​
How does Anthropic setuptoken auth work

claude setup-token generates a token string via the Claude Code CLI (it is not available in the web console). You can run it on any machine. Choose Anthropic token (paste setup-token) in the wizard or paste it with openclaw models auth paste-token --provider anthropic. The token is stored as an auth profile for the anthropic provider and used like an API key (no auto-refresh). More detail: OAuth.

​
Where do I find an Anthropic setuptoken

It is not in the Anthropic Console. The setup-token is generated by the Claude Code CLI on any machine: 
claude setup-token
Copy the token it prints, then choose Anthropic token (paste setup-token) in the wizard. If you want to run it on the gateway host, use openclaw models auth setup-token --provider anthropic. If you ran claude setup-token elsewhere, paste it on the gateway host with openclaw models auth paste-token --provider anthropic. See Anthropic.

​
Do you support Claude subscription auth (Claude Pro/Max)

Yes — via setup-token. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See Anthropic and OAuth. Note: Claude subscription access is governed by Anthropic’s terms. For production or multi‑user workloads, API keys are usually the safer choice.

​
Why am I seeing HTTP 429 ratelimiterror from Anthropic

That means your Anthropic quota/rate limit is exhausted for the current window. If you use a Claude subscription (setup‑token or Claude Code OAuth), wait for the window to reset or upgrade your plan. If you use an Anthropic API key, check the Anthropic Console for usage/billing and raise limits as needed. Tip: set a fallback model so OpenClaw can keep replying while a provider is rate‑limited. See Models and OAuth.

​
Is AWS Bedrock supported

Yes - via pi‑ai’s Amazon Bedrock (Converse) provider with manual config. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See Amazon Bedrock and Model providers. If you prefer a managed key flow, an OpenAI‑compatible proxy in front of Bedrock is still a valid option.

​
How does Codex auth work

OpenClaw supports OpenAI Code (Codex) via OAuth (ChatGPT sign-in). The wizard can run the OAuth flow and will set the default model to openai-codex/gpt-5.2 when appropriate. See Model providers and Wizard.

​
Do you support OpenAI subscription auth Codex OAuth

Yes. OpenClaw fully supports OpenAI Code (Codex) subscription OAuth. The onboarding wizard can run the OAuth flow for you. See OAuth, Model providers, and Wizard.

​
How do I set up Gemini CLI OAuth

Gemini CLI uses a plugin auth flow, not a client id or secret in openclaw.json. Steps:
  1. Enable the plugin: openclaw plugins enable google-gemini-cli-auth
  2. Login: openclaw models auth login --provider google-gemini-cli --set-default
This stores OAuth tokens in auth profiles on the gateway host. Details: Model providers.

​
Is a local model OK for casual chats

Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the largest MiniMax M2.1 build you can locally (LM Studio) and see /gateway/local-models. Smaller/quantized models increase prompt-injection risk - see Security.

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

Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using models.mode: "merge" so fallbacks stay 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 optional - some people buy one as an always‑on host, but a small VPS, home server, or Raspberry Pi‑class box works too. You only need a Mac for macOS‑only tools. For iMessage, you can keep the Gateway on Linux and run imsg on any Mac over SSH by pointing channels.imessage.cliPath at an SSH wrapper. If you want 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. It does not have to be a Mac mini - any Mac works. OpenClaw’s iMessage integrations run on macOS (BlueBubbles or imsg), while the Gateway can run elsewhere. Common setups:
  • Run the Gateway on Linux/VPS, and point channels.imessage.cliPath at an SSH wrapper that runs imsg on the Mac.
  • Run everything on the Mac if you want the simplest single‑machine setup.
Docs: iMessage, BlueBubbles, 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 can connect as a node (companion device). Nodes don’t run the Gateway - they provide extra capabilities like screen/camera/canvas and system.run on that device. Common pattern:
  • Gateway on the Mac mini (always‑on).
  • MacBook Pro runs the macOS app or a node host and pairs to the Gateway.
  • Use openclaw nodes status / openclaw nodes list to see it.
Docs: Nodes, Nodes CLI.

​
Can I use Bun

Bun is not recommended. We see runtime bugs, especially with WhatsApp and Telegram. Use Node for stable gateways. If you still want to experiment with Bun, do it on a non‑production gateway without WhatsApp/Telegram.

​
Telegram what goes in allowFrom

channels.telegram.allowFrom is the human sender’s Telegram user ID (numeric, recommended) or @username. It is not the bot username. Safer (no third-party bot):
  • DM your bot, then run openclaw logs --follow and read from.id.
Official Bot API:
  • DM your bot, then call https://api.telegram.org/bot<bot_token>/getUpdates and read message.from.id.
Third-party (less private):
  • DM @userinfobot or @getidsbot.
See /channels/telegram.

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

Yes, via multi‑agent routing. Bind each sender’s WhatsApp DM (peer kind: "dm", sender E.164 like +15551234567) to a different agentId, so each person gets their own workspace and session store. Replies still come from the same WhatsApp account, and DM access control (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) is global per WhatsApp account. See Multi-Agent Routing and WhatsApp.

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

Yes. Use multi‑agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in Multi-Agent Routing. See also Models and Configuration.

​
Does Homebrew work on Linux

Yes. Homebrew supports Linux (Linuxbrew). Quick setup: 
/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 via systemd, ensure the service PATH includes /home/linuxbrew/.linuxbrew/bin (or your brew prefix) so brew-installed tools resolve in non‑login shells. Recent builds also prepend common user bin dirs on Linux systemd services (for example ~/.local/bin, ~/.npm-global/bin, ~/.local/share/pnpm, ~/.bun/bin) and honor PNPM_HOME, NPM_CONFIG_PREFIX, BUN_INSTALL, VOLTA_HOME, ASDF_DATA_DIR, NVM_DIR, and FNM_DIR when set.

​
What’s the difference between the hackable git install and npm install

  • Hackable (git) install: full source checkout, editable, best for contributors. You run builds locally and can patch code/docs.
  • npm install: global CLI install, no repo, best for “just run it.” Updates come from npm dist‑tags.
Docs: Getting started, Updating.

​
Can I switch between npm and git installs later

Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint. This does not delete your data - it only changes the OpenClaw code install. Your state (~/.openclaw) and workspace (~/.openclaw/workspace) stay untouched. From npm → git: 
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart
From git → npm: 
npm install -g openclaw@latest
openclaw doctor
openclaw gateway restart
Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use --repair in automation). Backup tips: see Backup strategy.

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

Short answer: if you want 24/7 reliability, use a VPS. If you want the lowest friction and you’re okay with sleep/restarts, run it locally. Laptop (local Gateway)
  • Pros: no server cost, direct access to local files, live browser window.
  • Cons: sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
VPS / cloud
  • Pros: always‑on, stable network, no laptop sleep issues, easier to keep running.
  • Cons: often run headless (use screenshots), remote file access only, you must SSH for updates.
OpenClaw-specific note: WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord all work fine from a VPS. The only real trade-off is headless browser vs a visible window. See Browser. Recommended default: VPS if you had gateway disconnects before. Local is great when you’re actively using the Mac and want local file access or UI automation with a visible browser.

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

Not required, but recommended for reliability and isolation.
  • Dedicated host (VPS/Mac mini/Pi): always‑on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
  • Shared laptop/desktop: totally fine for testing and active use, but expect pauses when the machine sleeps or updates.
If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a node for local screen/camera/exec tools. See Nodes. For security guidance, read Security. OpenClaw is lightweight. For a basic Gateway + one chat channel:
  • Absolute minimum: 1 vCPU, 1GB RAM, ~500MB disk.
  • Recommended: 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.
OS: use Ubuntu LTS (or any modern Debian/Ubuntu). The Linux install path is best tested there. Docs: Linux, VPS hosting.

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

Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough RAM for the Gateway and any channels you enable. Baseline guidance:
  • Absolute minimum: 1 vCPU, 1GB RAM.
  • Recommended: 2GB RAM or more if you run multiple channels, browser automation, or media tools.
  • OS: Ubuntu LTS or another modern Debian/Ubuntu.
If you are on Windows, WSL2 is the easiest VM style setup and has the best tooling compatibility. See Windows, VPS hosting. If you are running macOS in a VM, see macOS VM.

​
What is OpenClaw?

​
What is OpenClaw in one paragraph

OpenClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The Gateway is the always-on control plane; the assistant is the product.

​
What’s the value proposition

OpenClaw is not “just a Claude wrapper.” It’s a local-first control plane that lets you run a capable assistant on your own hardware, reachable from the chat apps you already use, with stateful sessions, memory, and tools - without handing control of your workflows to a hosted SaaS. Highlights:
  • Your devices, your data: run the Gateway wherever you want (Mac, Linux, VPS) and keep the workspace + session history local.
  • Real channels, not a web sandbox: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, plus mobile voice and Canvas on supported platforms.
  • Model-agnostic: use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per‑agent routing and failover.
  • Local-only option: run local models so all data can stay on your device if you want.
  • Multi-agent routing: separate agents per channel, account, or task, each with its own workspace and defaults.
  • Open source and hackable: inspect, extend, and self-host without vendor lock‑in.
Docs: Gateway, Channels, Multi‑agent, Memory.

​
I just set it up what should I do first

Good first projects:
  • Build a website (WordPress, Shopify, or a simple static site).
  • Prototype a mobile app (outline, screens, API plan).
  • Organize files and folders (cleanup, naming, tagging).
  • Connect Gmail and automate summaries or follow ups.
It can handle large tasks, but it works best when you split them into phases and use sub agents for parallel work.

​
What are the top five everyday use cases for OpenClaw

Everyday wins usually look like:
  • Personal briefings: summaries of inbox, calendar, and news you care about.
  • Research and drafting: quick research, summaries, and first drafts for emails or docs.
  • Reminders and follow ups: cron or heartbeat driven nudges and checklists.
  • Browser automation: filling forms, collecting data, and repeating web tasks.
  • Cross device coordination: send a task from your phone, let the Gateway run it on a server, and get the result back in chat.

​
Can OpenClaw help with lead gen outreach ads and blogs for a SaaS

Yes for research, qualification, and drafting. It can scan sites, build shortlists, summarize prospects, and write outreach or ad copy drafts. For outreach or ad runs, keep a human in the loop. Avoid spam, follow local laws and platform policies, and review anything before it is sent. The safest pattern is to let OpenClaw draft and you approve. Docs: Security.

​
What are the advantages vs Claude Code for web development

OpenClaw is a personal assistant and coordination layer, not an IDE replacement. Use Claude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you want durable memory, cross-device access, and tool orchestration. Advantages:
  • Persistent memory + workspace across sessions
  • Multi-platform access (WhatsApp, Telegram, TUI, WebChat)
  • Tool orchestration (browser, files, scheduling, hooks)
  • Always-on Gateway (run on a VPS, interact from anywhere)
  • Nodes for local browser/screen/camera/exec
Showcase: https://open-claw.blog/showcase

​
Skills and automation

​
How do I customize skills without keeping the repo dirty

Use managed overrides instead of editing the repo copy. Put your changes in ~/.openclaw/skills/<name>/SKILL.md (or add a folder via skills.load.extraDirs in ~/.openclaw/openclaw.json). Precedence is <workspace>/skills > ~/.openclaw/skills > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs.

​
Can I load skills from a custom folder

Yes. Add extra directories via skills.load.extraDirs in ~/.openclaw/openclaw.json (lowest precedence). Default precedence remains: <workspace>/skills → ~/.openclaw/skills → bundled → skills.load.extraDirs. clawhub installs into ./skills by default, which OpenClaw treats as <workspace>/skills.

​
How can I use different models for different tasks

Today the supported patterns are:
  • Cron jobs: isolated jobs can set a model override per job.
  • Sub-agents: route tasks to separate agents with different default models.
  • On-demand switch: use /model to switch the current session model at any time.
See Cron jobs, Multi-Agent Routing, and Slash commands.

​
The bot freezes while doing heavy work How do I offload that

Use sub-agents for long or parallel tasks. Sub-agents run in their own session, return a summary, and keep your main chat responsive. Ask your bot to “spawn a sub-agent for this task” or use /subagents. Use /status in chat to see what the Gateway is doing right now (and whether it is busy). Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a cheaper model for sub-agents via agents.defaults.subagents.model. Docs: Sub-agents.

​
Cron or reminders do not fire What should I check

Cron runs inside the Gateway process. If the Gateway is not running continuously, scheduled jobs will not run. Checklist:
  • Confirm cron is enabled (cron.enabled) and OPENCLAW_SKIP_CRON is not set.
  • Check the Gateway is running 24/7 (no sleep/restarts).
  • Verify timezone settings for the job (--tz vs host timezone).
Debug: 
openclaw cron run <jobId> --force
openclaw cron runs --id <jobId> --limit 50
Docs: Cron jobs, Cron vs Heartbeat.

​
How do I install skills on Linux

Use ClawHub (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux. Browse skills at https://clawhub.com. Install the ClawHub CLI (pick one package manager): 
npm i -g clawhub

pnpm add -g clawhub

​
Can OpenClaw run tasks on a schedule or continuously in the background

Yes. Use the Gateway scheduler:
  • Cron jobs for scheduled or recurring tasks (persist across restarts).
  • Heartbeat for “main session” periodic checks.
  • Isolated jobs for autonomous agents that post summaries or deliver to chats.
Docs: Cron jobs, Cron vs Heartbeat, Heartbeat. Can I run Apple macOS only skills from Linux Not directly. macOS skills are gated by metadata.openclaw.os plus required binaries, and skills only appear in the system prompt when they are eligible on the Gateway host. On Linux, darwin-only skills (like imsg, apple-notes, apple-reminders) will not load unless you override the gating. You have three supported patterns: Option A - run the Gateway on a Mac (simplest).
Run the Gateway where the macOS binaries exist, then connect from Linux in remote mode or over Tailscale. The skills load normally because the Gateway host is macOS. Option B - use a macOS node (no SSH).
Run the Gateway on Linux, pair a macOS node (menubar app), and set Node Run Commands to “Always Ask” or “Always Allow” on the Mac. OpenClaw can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the nodes tool. If you choose “Always Ask”, approving “Always Allow” in the prompt adds that command to the allowlist. Option C - proxy macOS binaries over SSH (advanced).
Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
  1. Create an SSH wrapper for the binary (example: imsg): 
    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"
  2. Put the wrapper on PATH on the Linux host (for example ~/bin/imsg).
  3. Override the skill metadata (workspace or ~/.openclaw/skills) to allow Linux: 
    ---
name: imsg
description: iMessage/SMS CLI for listing chats, history, watch, and sending.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["imsg"] } } }
---
  4. Start a new session so the skills snapshot refreshes.
For iMessage specifically, you can also point channels.imessage.cliPath at an SSH wrapper (OpenClaw only needs stdio). See iMessage.

​
Do you have a Notion or HeyGen integration

Not built‑in today. Options:
  • Custom skill / plugin: best for reliable API access (Notion/HeyGen both have APIs).
  • Browser automation: works without code but is slower and more fragile.
If you want to keep context per client (agency workflows), a simple pattern is:
  • One Notion page per client (context + preferences + active work).
  • Ask the agent to fetch that page at the start of a session.
If you want a native integration, open a feature request or build a skill targeting those APIs. Install skills: 
clawhub install <skill-slug>
clawhub update --all
ClawHub installs into ./skills under your current directory (or falls back to your configured OpenClaw workspace); OpenClaw treats that as <workspace>/skills on the next session. For shared skills across agents, place them in ~/.openclaw/skills/<name>/SKILL.md. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See Skills and ClawHub.

​
How do I install the Chrome extension for browser takeover

Use the built-in installer, then load the unpacked extension in Chrome: 
openclaw browser extension install
openclaw browser extension path
Then Chrome → chrome://extensions → enable “Developer mode” → “Load unpacked” → pick that folder. Full guide (including remote Gateway + security notes): Chrome extension If the Gateway runs on the same machine as Chrome (default setup), you usually do not need anything extra. If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions. You still need to click the extension button on the tab you want to control (it doesn’t auto-attach).

​
Sandboxing and memory

​
Is there a dedicated sandboxing doc

Yes. See Sandboxing. For Docker-specific setup (full gateway in Docker or sandbox images), see Docker. Can I keep DMs personal but make groups public sandboxed with one agent Yes - if your private traffic is DMs and your public traffic is groups. Use agents.defaults.sandbox.mode: "non-main" so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via tools.sandbox.tools. Setup walkthrough + example config: Groups: personal DMs + public groups Key config reference: Gateway configuration

​
How do I bind a host folder into the sandbox

Set agents.defaults.sandbox.docker.binds to ["host:path:mode"] (e.g., "/home/user/src:/src:ro"). Global + per-agent binds merge; per-agent binds are ignored when scope: "shared". Use :ro for anything sensitive and remember binds bypass the sandbox filesystem walls. See Sandboxing and Sandbox vs Tool Policy vs Elevated for examples and safety notes.

​
How does memory work

OpenClaw memory is just Markdown files in the agent workspace:
  • Daily notes in memory/YYYY-MM-DD.md
  • Curated long-term notes in MEMORY.md (main/private sessions only)
OpenClaw also runs a silent pre-compaction memory flush to remind the model to write durable notes before auto-compaction. This only runs when the workspace is writable (read-only sandboxes skip it). See Memory.

​
Memory keeps forgetting things How do I make it stick

Ask the bot to write the fact to memory. Long-term notes belong in MEMORY.md, short-term context goes into memory/YYYY-MM-DD.md. This is still an area we are improving. It helps to remind the model to store memories; it will know what to do. If it keeps forgetting, verify the Gateway is using the same workspace on every run. Docs: Memory, Agent workspace.