@gguf/claw

--- summary: "Frequently asked questions about OpenClaw setup, configuration, and usage" title: "FAQ" --- # 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](/gateway/troubleshooting). For the full config reference, see [Configuration](/gateway/configuration). ## Table of contents - [Quick start and first-run setup](#quick-start-and-firstrun-setup) - [Im stuck whats the fastest way to get unstuck?](#im-stuck-whats-the-fastest-way-to-get-unstuck) - [What's the recommended way to install and set up OpenClaw?](#whats-the-recommended-way-to-install-and-set-up-openclaw) - [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding) - [How do I authenticate the dashboard (token) on localhost vs remote?](#how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote) - [What runtime do I need?](#what-runtime-do-i-need) - [Does it run on Raspberry Pi?](#does-it-run-on-raspberry-pi) - [Any tips for Raspberry Pi installs?](#any-tips-for-raspberry-pi-installs) - [It is stuck on "wake up my friend" / onboarding will not hatch. What now?](#it-is-stuck-on-wake-up-my-friend-onboarding-will-not-hatch-what-now) - [Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?](#can-i-migrate-my-setup-to-a-new-machine-mac-mini-without-redoing-onboarding) - [Where do I see what is new in the latest version?](#where-do-i-see-what-is-new-in-the-latest-version) - [I can't access docs.openclaw.ai (SSL error). What now?](#i-cant-access-docsopenclawai-ssl-error-what-now) - [What's the difference between stable and beta?](#whats-the-difference-between-stable-and-beta) - [How do I install the beta version, and what's the difference between beta and dev?](#how-do-i-install-the-beta-version-and-whats-the-difference-between-beta-and-dev) - [How do I try the latest bits?](#how-do-i-try-the-latest-bits) - [How long does install and onboarding usually take?](#how-long-does-install-and-onboarding-usually-take) - [Installer stuck? How do I get more feedback?](#installer-stuck-how-do-i-get-more-feedback) - [Windows install says git not found or openclaw not recognized](#windows-install-says-git-not-found-or-openclaw-not-recognized) - [The docs didn't answer my question - how do I get a better answer?](#the-docs-didnt-answer-my-question-how-do-i-get-a-better-answer) - [How do I install OpenClaw on Linux?](#how-do-i-install-openclaw-on-linux) - [How do I install OpenClaw on a VPS?](#how-do-i-install-openclaw-on-a-vps) - [Where are the cloud/VPS install guides?](#where-are-the-cloudvps-install-guides) - [Can I ask OpenClaw to update itself?](#can-i-ask-openclaw-to-update-itself) - [What does the onboarding wizard actually do?](#what-does-the-onboarding-wizard-actually-do) - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this) - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key) - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work) - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken) - [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth) - [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) - [Is AWS Bedrock supported?](#is-aws-bedrock-supported) - [How does Codex auth work?](#how-does-codex-auth-work) - [Do you support OpenAI subscription auth (Codex OAuth)?](#do-you-support-openai-subscription-auth-codex-oauth) - [How do I set up Gemini CLI OAuth](#how-do-i-set-up-gemini-cli-oauth) - [Is a local model OK for casual chats?](#is-a-local-model-ok-for-casual-chats) - [How do I keep hosted model traffic in a specific region?](#how-do-i-keep-hosted-model-traffic-in-a-specific-region) - [Do I have to buy a Mac Mini to install this?](#do-i-have-to-buy-a-mac-mini-to-install-this) - [Do I need a Mac mini for iMessage support?](#do-i-need-a-mac-mini-for-imessage-support) - [If I buy a Mac mini to run OpenClaw, can I connect it to my MacBook Pro?](#if-i-buy-a-mac-mini-to-run-openclaw-can-i-connect-it-to-my-macbook-pro) - [Can I use Bun?](#can-i-use-bun) - [Telegram: what goes in `allowFrom`?](#telegram-what-goes-in-allowfrom) - [Can multiple people use one WhatsApp number with different OpenClaw instances?](#can-multiple-people-use-one-whatsapp-number-with-different-openclaw-instances) - [Can I run a "fast chat" agent and an "Opus for coding" agent?](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent) - [Does Homebrew work on Linux?](#does-homebrew-work-on-linux) - [What's the difference between the hackable (git) install and npm install?](#whats-the-difference-between-the-hackable-git-install-and-npm-install) - [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later) - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps) - [How important is it to run OpenClaw on a dedicated machine?](#how-important-is-it-to-run-openclaw-on-a-dedicated-machine) - [What are the minimum VPS requirements and recommended OS?](#what-are-the-minimum-vps-requirements-and-recommended-os) - [Can I run OpenClaw in a VM and what are the requirements](#can-i-run-openclaw-in-a-vm-and-what-are-the-requirements) - [What is OpenClaw?](#what-is-openclaw) - [What is OpenClaw, in one paragraph?](#what-is-openclaw-in-one-paragraph) - [What's the value proposition?](#whats-the-value-proposition) - [I just set it up what should I do first](#i-just-set-it-up-what-should-i-do-first) - [What are the top five everyday use cases for OpenClaw](#what-are-the-top-five-everyday-use-cases-for-openclaw) - [Can OpenClaw help with lead gen outreach ads and blogs for a SaaS](#can-openclaw-help-with-lead-gen-outreach-ads-and-blogs-for-a-saas) - [What are the advantages vs Claude Code for web development?](#what-are-the-advantages-vs-claude-code-for-web-development) - [Skills and automation](#skills-and-automation) - [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty) - [Can I load skills from a custom folder?](#can-i-load-skills-from-a-custom-folder) - [How can I use different models for different tasks?](#how-can-i-use-different-models-for-different-tasks) - [The bot freezes while doing heavy work. How do I offload that?](#the-bot-freezes-while-doing-heavy-work-how-do-i-offload-that) - [Cron or reminders do not fire. What should I check?](#cron-or-reminders-do-not-fire-what-should-i-check) - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux) - [Can OpenClaw run tasks on a schedule or continuously in the background?](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background) - [Can I run Apple/macOS-only skills from Linux?](#can-i-run-applemacosonly-skills-from-linux) - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration) - [How do I install the Chrome extension for browser takeover?](#how-do-i-install-the-chrome-extension-for-browser-takeover) - [Sandboxing and memory](#sandboxing-and-memory) - [Is there a dedicated sandboxing doc?](#is-there-a-dedicated-sandboxing-doc) - [How do I bind a host folder into the sandbox?](#how-do-i-bind-a-host-folder-into-the-sandbox) - [How does memory work?](#how-does-memory-work) - [Memory keeps forgetting things. How do I make it stick?](#memory-keeps-forgetting-things-how-do-i-make-it-stick) - [Does memory persist forever? What are the limits?](#does-memory-persist-forever-what-are-the-limits) - [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key) - [Where things live on disk](#where-things-live-on-disk) - [Is all data used with OpenClaw saved locally?](#is-all-data-used-with-openclaw-saved-locally) - [Where does OpenClaw store its data?](#where-does-openclaw-store-its-data) - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd-soulmd-usermd-memorymd-live) - [What's the recommended backup strategy?](#whats-the-recommended-backup-strategy) - [How do I completely uninstall OpenClaw?](#how-do-i-completely-uninstall-openclaw) - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace) - [I'm in remote mode - where is the session store?](#im-in-remote-mode-where-is-the-session-store) - [Config basics](#config-basics) - [What format is the config? Where is it?](#what-format-is-the-config-where-is-it) - [I set `gateway.bind: "lan"` (or `"tailnet"`) and now nothing listens / the UI says unauthorized](#i-set-gatewaybind-lan-or-tailnet-and-now-nothing-listens-the-ui-says-unauthorized) - [Why do I need a token on localhost now?](#why-do-i-need-a-token-on-localhost-now) - [Do I have to restart after changing config?](#do-i-have-to-restart-after-changing-config) - [How do I enable web search (and web fetch)?](#how-do-i-enable-web-search-and-web-fetch) - [config.apply wiped my config. How do I recover and avoid this?](#configapply-wiped-my-config-how-do-i-recover-and-avoid-this) - [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices) - [Can the OpenClaw browser run headless?](#can-the-openclaw-browser-run-headless) - [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control) - [Remote gateways + nodes](#remote-gateways-nodes) - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes) - [How can my agent access my computer if the Gateway is hosted remotely?](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely) - [Tailscale is connected but I get no replies. What now?](#tailscale-is-connected-but-i-get-no-replies-what-now) - [Can two OpenClaw instances talk to each other (local + VPS)?](#can-two-openclaw-instances-talk-to-each-other-local-vps) - [Do I need separate VPSes for multiple agents](#do-i-need-separate-vpses-for-multiple-agents) - [Is there a benefit to using a node on my personal laptop instead of SSH from a VPS?](#is-there-a-benefit-to-using-a-node-on-my-personal-laptop-instead-of-ssh-from-a-vps) - [Do nodes run a gateway service?](#do-nodes-run-a-gateway-service) - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config) - [What's a minimal "sane" config for a first install?](#whats-a-minimal-sane-config-for-a-first-install) - [How do I set up Tailscale on a VPS and connect from my Mac?](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac) - [How do I connect a Mac node to a remote Gateway (Tailscale Serve)?](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve) - [Should I install on a second laptop or just add a node?](#should-i-install-on-a-second-laptop-or-just-add-a-node) - [Env vars and .env loading](#env-vars-and-env-loading) - [How does OpenClaw load environment variables?](#how-does-openclaw-load-environment-variables) - ["I started the Gateway via the service and my env vars disappeared." What now?](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now) - [I set `COPILOT_GITHUB_TOKEN`, but models status shows "Shell env: off." Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why) - [Sessions & multiple chats](#sessions-multiple-chats) - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation) - [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new) - [Is there a way to make a team of OpenClaw instances one CEO and many agents](#is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents) - [Why did context get truncated mid-task? How do I prevent it?](#why-did-context-get-truncated-midtask-how-do-i-prevent-it) - [How do I completely reset OpenClaw but keep it installed?](#how-do-i-completely-reset-openclaw-but-keep-it-installed) - [I'm getting "context too large" errors - how do I reset or compact?](#im-getting-context-too-large-errors-how-do-i-reset-or-compact) - [Why am I seeing "LLM request rejected: messages.N.content.X.tool_use.input: Field required"?](#why-am-i-seeing-llm-request-rejected-messagesncontentxtooluseinput-field-required) - [Why am I getting heartbeat messages every 30 minutes?](#why-am-i-getting-heartbeat-messages-every-30-minutes) - [Do I need to add a "bot account" to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group) - [How do I get the JID of a WhatsApp group?](#how-do-i-get-the-jid-of-a-whatsapp-group) - [Why doesn't OpenClaw reply in a group?](#why-doesnt-openclaw-reply-in-a-group) - [Do groups/threads share context with DMs?](#do-groupsthreads-share-context-with-dms) - [How many workspaces and agents can I create?](#how-many-workspaces-and-agents-can-i-create) - [Can I run multiple bots or chats at the same time (Slack), and how should I set that up?](#can-i-run-multiple-bots-or-chats-at-the-same-time-slack-and-how-should-i-set-that-up) - [Models: defaults, selection, aliases, switching](#models-defaults-selection-aliases-switching) - [What is the "default model"?](#what-is-the-default-model) - [What model do you recommend?](#what-model-do-you-recommend) - [How do I switch models without wiping my config?](#how-do-i-switch-models-without-wiping-my-config) - [Can I use self-hosted models (llama.cpp, vLLM, Ollama)?](#can-i-use-selfhosted-models-llamacpp-vllm-ollama) - [What do OpenClaw, Flawd, and Krill use for models?](#what-do-openclaw-flawd-and-krill-use-for-models) - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting) - [Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding](#can-i-use-gpt-52-for-daily-tasks-and-codex-52-for-coding) - [Why do I see "Model … is not allowed" and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply) - [Why do I see "Unknown model: minimax/MiniMax-M2.1"?](#why-do-i-see-unknown-model-minimaxminimaxm21) - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks) - [Are opus / sonnet / gpt built-in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts) - [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases) - [How do I add models from other providers like OpenRouter or Z.AI?](#how-do-i-add-models-from-other-providers-like-openrouter-or-zai) - [Model failover and "All models failed"](#model-failover-and-all-models-failed) - [How does failover work?](#how-does-failover-work) - [What does this error mean?](#what-does-this-error-mean) - [Fix checklist for `No credentials found for profile "anthropic:default"`](#fix-checklist-for-no-credentials-found-for-profile-anthropicdefault) - [Why did it also try Google Gemini and fail?](#why-did-it-also-try-google-gemini-and-fail) - [Auth profiles: what they are and how to manage them](#auth-profiles-what-they-are-and-how-to-manage-them) - [What is an auth profile?](#what-is-an-auth-profile) - [What are typical profile IDs?](#what-are-typical-profile-ids) - [Can I control which auth profile is tried first?](#can-i-control-which-auth-profile-is-tried-first) - [OAuth vs API key: what's the difference?](#oauth-vs-api-key-whats-the-difference) - [Gateway: ports, "already running", and remote mode](#gateway-ports-already-running-and-remote-mode) - [What port does the Gateway use?](#what-port-does-the-gateway-use) - [Why does `openclaw gateway status` say `Runtime: running` but `RPC probe: failed`?](#why-does-openclaw-gateway-status-say-runtime-running-but-rpc-probe-failed) - [Why does `openclaw gateway status` show `Config (cli)` and `Config (service)` different?](#why-does-openclaw-gateway-status-show-config-cli-and-config-service-different) - [What does "another gateway instance is already listening" mean?](#what-does-another-gateway-instance-is-already-listening-mean) - [How do I run OpenClaw in remote mode (client connects to a Gateway elsewhere)?](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere) - [The Control UI says "unauthorized" (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now) - [I set `gateway.bind: "tailnet"` but it can't bind / nothing listens](#i-set-gatewaybind-tailnet-but-it-cant-bind-nothing-listens) - [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host) - [What does "invalid handshake" / code 1008 mean?](#what-does-invalid-handshake-code-1008-mean) - [Logging and debugging](#logging-and-debugging) - [Where are logs?](#where-are-logs) - [How do I start/stop/restart the Gateway service?](#how-do-i-startstoprestart-the-gateway-service) - [I closed my terminal on Windows - how do I restart OpenClaw?](#i-closed-my-terminal-on-windows-how-do-i-restart-openclaw) - [The Gateway is up but replies never arrive. What should I check?](#the-gateway-is-up-but-replies-never-arrive-what-should-i-check) - ["Disconnected from gateway: no reason" - what now?](#disconnected-from-gateway-no-reason-what-now) - [Telegram setMyCommands fails with network errors. What should I check?](#telegram-setmycommands-fails-with-network-errors-what-should-i-check) - [TUI shows no output. What should I check?](#tui-shows-no-output-what-should-i-check) - [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway) - [ELI5: `openclaw gateway restart` vs `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway) - [What's the fastest way to get more details when something fails?](#whats-the-fastest-way-to-get-more-details-when-something-fails) - [Media & attachments](#media-attachments) - [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent) - [Security and access control](#security-and-access-control) - [Is it safe to expose OpenClaw to inbound DMs?](#is-it-safe-to-expose-openclaw-to-inbound-dms) - [Is prompt injection only a concern for public bots?](#is-prompt-injection-only-a-concern-for-public-bots) - [Should my bot have its own email GitHub account or phone number](#should-my-bot-have-its-own-email-github-account-or-phone-number) - [Can I give it autonomy over my text messages and is that safe](#can-i-give-it-autonomy-over-my-text-messages-and-is-that-safe) - [Can I use cheaper models for personal assistant tasks?](#can-i-use-cheaper-models-for-personal-assistant-tasks) - [I ran `/start` in Telegram but didn't get a pairing code](#i-ran-start-in-telegram-but-didnt-get-a-pairing-code) - [WhatsApp: will it message my contacts? How does pairing work?](#whatsapp-will-it-message-my-contacts-how-does-pairing-work) - [Chat commands, aborting tasks, and "it won't stop"](#chat-commands-aborting-tasks-and-it-wont-stop) - [How do I stop internal system messages from showing in chat](#how-do-i-stop-internal-system-messages-from-showing-in-chat) - [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task) - [How do I send a Discord message from Telegram? ("Cross-context messaging denied")](#how-do-i-send-a-discord-message-from-telegram-crosscontext-messaging-denied) - [Why does it feel like the bot "ignores" rapid-fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages) ## First 60 seconds if something's broken 1. **Quick status (first check)** ```bash 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)** ```bash openclaw status --all ``` Read-only diagnosis with log tail (tokens redacted). 3. **Daemon + port state** ```bash openclaw gateway status ``` Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used. 4. **Deep probes** ```bash openclaw status --deep ``` Runs gateway health checks + provider probes (requires a reachable gateway). See [Health](/gateway/health). 5. **Tail the latest log** ```bash openclaw logs --follow ``` If RPC is down, fall back to: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` File logs are separate from service logs; see [Logging](/logging) and [Troubleshooting](/gateway/troubleshooting). 6. **Run the doctor (repairs)** ```bash openclaw doctor ``` Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor). 7. **Gateway snapshot** ```bash 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](/gateway/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. - **Claude Code**: https://www.anthropic.com/claude-code/ - **OpenAI Codex**: https://openai.com/codex/ 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: ```bash curl -fsSL https://openclaw.ai/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): ```bash 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](#first-60-seconds-if-somethings-broken). Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating). ### What's the recommended way to install and set up OpenClaw The repo recommends running from source and using the onboarding wizard: ```bash curl -fsSL https://openclaw.ai/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): ```bash 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](/web/dashboard) and [Web surfaces](/web) 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](/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](/platforms/linux), [Install](/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: ```bash openclaw gateway restart ``` 2. Check status + auth: ```bash openclaw status openclaw models status openclaw logs --follow ``` 3. If it still hangs, run: ```bash 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](/gateway/remote). ### 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](/install/migrating), [Where things live on disk](/help/faq#where-does-openclaw-store-its-data), [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor), [Remote mode](/gateway/remote). ### 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 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.openclaw.ai SSL error What now Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More detail: [Troubleshooting](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity). 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): ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Windows installer (PowerShell): https://openclaw.ai/install.ps1 More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer). ### 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](/help/faq#installer-stuck-how-do-i-get-more-feedback) and the fast debug loop in [Im stuck](/help/faq#im-stuck--whats-the-fastest-way-to-get-unstuck). ### How do I try the latest bits Two options: 1. **Dev channel (git checkout):** ```bash openclaw update --channel dev ``` This switches to the `main` branch and updates from source. 2. **Hackable install (from the installer site):** ```bash curl -fsSL https://openclaw.ai/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: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build ``` Docs: [Update](/cli/update), [Development channels](/install/development-channels), [Install](/install). ### Installer stuck How do I get more feedback Re-run the installer with **verbose output**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` Beta install with verbose: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` For a hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` More options: [Installer flags](/install/installer). ### 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: ```powershell 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](/platforms/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. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` More detail: [Install](/install) and [Installer flags](/install/installer). ### How do I install OpenClaw on Linux Short answer: follow the Linux guide, then run the onboarding wizard. - Linux quick path + service install: [Linux](/platforms/linux). - Full walkthrough: [Getting Started](/start/getting-started). - Installer + updates: [Install & updates](/install/updating). ### 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](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [Fly.io](/platforms/fly). Remote access: [Gateway remote](/gateway/remote). ### Where are the cloudVPS install guides We keep a **hosting hub** with the common providers. Pick one and follow the guide: - [VPS hosting](/vps) (all providers in one place) - [Fly.io](/platforms/fly) - [Hetzner](/platforms/hetzner) - [exe.dev](/platforms/exe-dev) 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](/platforms). Remote access: [Gateway remote](/gateway/remote). Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes). ### 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: ```bash 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: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` Docs: [Update](/cli/update), [Updating](/install/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](/providers/anthropic), [OpenAI](/providers/openai), [Local models](/gateway/local-models), [Models](/concepts/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](/concepts/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**: ```bash 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](/providers/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](/providers/anthropic) and [OAuth](/concepts/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](/cli/models) and [OAuth](/concepts/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](/bedrock) and [Model providers](/providers/models). 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](/concepts/model-providers) and [Wizard](/start/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](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/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](/concepts/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](/gateway/local-models). Smaller/quantized models increase prompt-injection risk - see [Security](/gateway/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, use [BlueBubbles](/channels/bluebubbles) (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node. Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote). ### 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. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere. Common setups: - Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages. - Run everything on the Mac if you want the simplest single‑machine setup. Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote). ### 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), [Nodes CLI](/cli/nodes). ### 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](/channels/telegram#access-control-dms--groups). ### 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](/concepts/multi-agent) and [WhatsApp](/channels/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](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration). ### Does Homebrew work on Linux Yes. Homebrew supports Linux (Linuxbrew). Quick setup: ```bash /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](/start/getting-started), [Updating](/install/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: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build openclaw doctor openclaw gateway restart ``` From git → npm: ```bash 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](/help/faq#whats-the-recommended-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](/tools/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](/nodes). For security guidance, read [Security](/gateway/security). ### What are the minimum VPS requirements and recommended OS 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](/platforms/linux), [VPS hosting](/vps). ### 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](/platforms/windows), [VPS hosting](/vps). If you are running macOS in a VM, see [macOS VM](/platforms/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