openclaw-skill/openclaw-knowhow-skill/output/openclaw-docs_data/pages/FAQ_62e816f7f3.json

{
  "title": "FAQ",
  "content": "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).\n\n* [Quick start and first-run setup](#quick-start-and-firstrun-setup)\n  * [Im stuck whats the fastest way to get unstuck?](#im-stuck-whats-the-fastest-way-to-get-unstuck)\n  * [What's the recommended way to install and set up OpenClaw?](#whats-the-recommended-way-to-install-and-set-up-openclaw)\n  * [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding)\n  * [How do I authenticate the dashboard (token) on localhost vs remote?](#how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote)\n  * [What runtime do I need?](#what-runtime-do-i-need)\n  * [Does it run on Raspberry Pi?](#does-it-run-on-raspberry-pi)\n  * [Any tips for Raspberry Pi installs?](#any-tips-for-raspberry-pi-installs)\n  * [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)\n  * [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)\n  * [Where do I see what is new in the latest version?](#where-do-i-see-what-is-new-in-the-latest-version)\n  * [I can't access docs.openclaw.ai (SSL error). What now?](#i-cant-access-docsopenclawai-ssl-error-what-now)\n  * [What's the difference between stable and beta?](#whats-the-difference-between-stable-and-beta)\n  * [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)\n  * [How do I try the latest bits?](#how-do-i-try-the-latest-bits)\n  * [How long does install and onboarding usually take?](#how-long-does-install-and-onboarding-usually-take)\n  * [Installer stuck? How do I get more feedback?](#installer-stuck-how-do-i-get-more-feedback)\n  * [Windows install says git not found or openclaw not recognized](#windows-install-says-git-not-found-or-openclaw-not-recognized)\n  * [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)\n  * [How do I install OpenClaw on Linux?](#how-do-i-install-openclaw-on-linux)\n  * [How do I install OpenClaw on a VPS?](#how-do-i-install-openclaw-on-a-vps)\n  * [Where are the cloud/VPS install guides?](#where-are-the-cloudvps-install-guides)\n  * [Can I ask OpenClaw to update itself?](#can-i-ask-openclaw-to-update-itself)\n  * [What does the onboarding wizard actually do?](#what-does-the-onboarding-wizard-actually-do)\n  * [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this)\n  * [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key)\n  * [How does Anthropic \"setup-token\" auth work?](#how-does-anthropic-setuptoken-auth-work)\n  * [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken)\n  * [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth)\n  * [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)\n  * [Is AWS Bedrock supported?](#is-aws-bedrock-supported)\n  * [How does Codex auth work?](#how-does-codex-auth-work)\n  * [Do you support OpenAI subscription auth (Codex OAuth)?](#do-you-support-openai-subscription-auth-codex-oauth)\n  * [How do I set up Gemini CLI OAuth](#how-do-i-set-up-gemini-cli-oauth)\n  * [Is a local model OK for casual chats?](#is-a-local-model-ok-for-casual-chats)\n  * [How do I keep hosted model traffic in a specific region?](#how-do-i-keep-hosted-model-traffic-in-a-specific-region)\n  * [Do I have to buy a Mac Mini to install this?](#do-i-have-to-buy-a-mac-mini-to-install-this)\n  * [Do I need a Mac mini for iMessage support?](#do-i-need-a-mac-mini-for-imessage-support)\n  * [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)\n  * [Can I use Bun?](#can-i-use-bun)\n  * [Telegram: what goes in `allowFrom`?](#telegram-what-goes-in-allowfrom)\n  * [Can multiple people use one WhatsApp number with different OpenClaw instances?](#can-multiple-people-use-one-whatsapp-number-with-different-openclaw-instances)\n  * [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)\n  * [Does Homebrew work on Linux?](#does-homebrew-work-on-linux)\n  * [What's the difference between the hackable (git) install and npm install?](#whats-the-difference-between-the-hackable-git-install-and-npm-install)\n  * [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later)\n  * [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps)\n  * [How important is it to run OpenClaw on a dedicated machine?](#how-important-is-it-to-run-openclaw-on-a-dedicated-machine)\n  * [What are the minimum VPS requirements and recommended OS?](#what-are-the-minimum-vps-requirements-and-recommended-os)\n  * [Can I run OpenClaw in a VM and what are the requirements](#can-i-run-openclaw-in-a-vm-and-what-are-the-requirements)\n* [What is OpenClaw?](#what-is-openclaw)\n  * [What is OpenClaw, in one paragraph?](#what-is-openclaw-in-one-paragraph)\n  * [What's the value proposition?](#whats-the-value-proposition)\n  * [I just set it up what should I do first](#i-just-set-it-up-what-should-i-do-first)\n  * [What are the top five everyday use cases for OpenClaw](#what-are-the-top-five-everyday-use-cases-for-openclaw)\n  * [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)\n  * [What are the advantages vs Claude Code for web development?](#what-are-the-advantages-vs-claude-code-for-web-development)\n* [Skills and automation](#skills-and-automation)\n  * [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty)\n  * [Can I load skills from a custom folder?](#can-i-load-skills-from-a-custom-folder)\n  * [How can I use different models for different tasks?](#how-can-i-use-different-models-for-different-tasks)\n  * [The bot freezes while doing heavy work. How do I offload that?](#the-bot-freezes-while-doing-heavy-work-how-do-i-offload-that)\n  * [Cron or reminders do not fire. What should I check?](#cron-or-reminders-do-not-fire-what-should-i-check)\n  * [How do I install skills on Linux?](#how-do-i-install-skills-on-linux)\n  * [Can OpenClaw run tasks on a schedule or continuously in the background?](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background)\n  * [Can I run Apple/macOS-only skills from Linux?](#can-i-run-applemacosonly-skills-from-linux)\n  * [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration)\n  * [How do I install the Chrome extension for browser takeover?](#how-do-i-install-the-chrome-extension-for-browser-takeover)\n* [Sandboxing and memory](#sandboxing-and-memory)\n  * [Is there a dedicated sandboxing doc?](#is-there-a-dedicated-sandboxing-doc)\n  * [How do I bind a host folder into the sandbox?](#how-do-i-bind-a-host-folder-into-the-sandbox)\n  * [How does memory work?](#how-does-memory-work)\n  * [Memory keeps forgetting things. How do I make it stick?](#memory-keeps-forgetting-things-how-do-i-make-it-stick)\n  * [Does memory persist forever? What are the limits?](#does-memory-persist-forever-what-are-the-limits)\n  * [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key)\n* [Where things live on disk](#where-things-live-on-disk)\n  * [Is all data used with OpenClaw saved locally?](#is-all-data-used-with-openclaw-saved-locally)\n  * [Where does OpenClaw store its data?](#where-does-openclaw-store-its-data)\n  * [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd-soulmd-usermd-memorymd-live)\n  * [What's the recommended backup strategy?](#whats-the-recommended-backup-strategy)\n  * [How do I completely uninstall OpenClaw?](#how-do-i-completely-uninstall-openclaw)\n  * [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace)\n  * [I'm in remote mode - where is the session store?](#im-in-remote-mode-where-is-the-session-store)\n* [Config basics](#config-basics)\n  * [What format is the config? Where is it?](#what-format-is-the-config-where-is-it)\n  * [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)\n  * [Why do I need a token on localhost now?](#why-do-i-need-a-token-on-localhost-now)\n  * [Do I have to restart after changing config?](#do-i-have-to-restart-after-changing-config)\n  * [How do I enable web search (and web fetch)?](#how-do-i-enable-web-search-and-web-fetch)\n  * [config.apply wiped my config. How do I recover and avoid this?](#configapply-wiped-my-config-how-do-i-recover-and-avoid-this)\n  * [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices)\n  * [Can the OpenClaw browser run headless?](#can-the-openclaw-browser-run-headless)\n  * [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control)\n* [Remote gateways + nodes](#remote-gateways-nodes)\n  * [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes)\n  * [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)\n  * [Tailscale is connected but I get no replies. What now?](#tailscale-is-connected-but-i-get-no-replies-what-now)\n  * [Can two OpenClaw instances talk to each other (local + VPS)?](#can-two-openclaw-instances-talk-to-each-other-local-vps)\n  * [Do I need separate VPSes for multiple agents](#do-i-need-separate-vpses-for-multiple-agents)\n  * [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)\n  * [Do nodes run a gateway service?](#do-nodes-run-a-gateway-service)\n  * [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config)\n  * [What's a minimal \"sane\" config for a first install?](#whats-a-minimal-sane-config-for-a-first-install)\n  * [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)\n  * [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)\n  * [Should I install on a second laptop or just add a node?](#should-i-install-on-a-second-laptop-or-just-add-a-node)\n* [Env vars and .env loading](#env-vars-and-env-loading)\n  * [How does OpenClaw load environment variables?](#how-does-openclaw-load-environment-variables)\n  * [\"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)\n  * [I set `COPILOT_GITHUB_TOKEN`, but models status shows \"Shell env: off.\" Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why)\n* [Sessions & multiple chats](#sessions-multiple-chats)\n  * [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation)\n  * [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new)\n  * [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)\n  * [Why did context get truncated mid-task? How do I prevent it?](#why-did-context-get-truncated-midtask-how-do-i-prevent-it)\n  * [How do I completely reset OpenClaw but keep it installed?](#how-do-i-completely-reset-openclaw-but-keep-it-installed)\n  * [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)\n  * [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)\n  * [Why am I getting heartbeat messages every 30 minutes?](#why-am-i-getting-heartbeat-messages-every-30-minutes)\n  * [Do I need to add a \"bot account\" to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group)\n  * [How do I get the JID of a WhatsApp group?](#how-do-i-get-the-jid-of-a-whatsapp-group)\n  * [Why doesn't OpenClaw reply in a group?](#why-doesnt-openclaw-reply-in-a-group)\n  * [Do groups/threads share context with DMs?](#do-groupsthreads-share-context-with-dms)\n  * [How many workspaces and agents can I create?](#how-many-workspaces-and-agents-can-i-create)\n  * [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)\n* [Models: defaults, selection, aliases, switching](#models-defaults-selection-aliases-switching)\n  * [What is the \"default model\"?](#what-is-the-default-model)\n  * [What model do you recommend?](#what-model-do-you-recommend)\n  * [How do I switch models without wiping my config?](#how-do-i-switch-models-without-wiping-my-config)\n  * [Can I use self-hosted models (llama.cpp, vLLM, Ollama)?](#can-i-use-selfhosted-models-llamacpp-vllm-ollama)\n  * [What do OpenClaw, Flawd, and Krill use for models?](#what-do-openclaw-flawd-and-krill-use-for-models)\n  * [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting)\n  * [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)\n  * [Why do I see \"Model … is not allowed\" and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply)\n  * [Why do I see \"Unknown model: minimax/MiniMax-M2.1\"?](#why-do-i-see-unknown-model-minimaxminimaxm21)\n  * [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks)\n  * [Are opus / sonnet / gpt built-in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts)\n  * [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases)\n  * [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)\n* [Model failover and \"All models failed\"](#model-failover-and-all-models-failed)\n  * [How does failover work?](#how-does-failover-work)\n  * [What does this error mean?](#what-does-this-error-mean)\n  * [Fix checklist for `No credentials found for profile \"anthropic:default\"`](#fix-checklist-for-no-credentials-found-for-profile-anthropicdefault)\n  * [Why did it also try Google Gemini and fail?](#why-did-it-also-try-google-gemini-and-fail)\n* [Auth profiles: what they are and how to manage them](#auth-profiles-what-they-are-and-how-to-manage-them)\n  * [What is an auth profile?](#what-is-an-auth-profile)\n  * [What are typical profile IDs?](#what-are-typical-profile-ids)\n  * [Can I control which auth profile is tried first?](#can-i-control-which-auth-profile-is-tried-first)\n  * [OAuth vs API key: what's the difference?](#oauth-vs-api-key-whats-the-difference)\n* [Gateway: ports, \"already running\", and remote mode](#gateway-ports-already-running-and-remote-mode)\n  * [What port does the Gateway use?](#what-port-does-the-gateway-use)\n  * [Why does `openclaw gateway status` say `Runtime: running` but `RPC probe: failed`?](#why-does-openclaw-gateway-status-say-runtime-running-but-rpc-probe-failed)\n  * [Why does `openclaw gateway status` show `Config (cli)` and `Config (service)` different?](#why-does-openclaw-gateway-status-show-config-cli-and-config-service-different)\n  * [What does \"another gateway instance is already listening\" mean?](#what-does-another-gateway-instance-is-already-listening-mean)\n  * [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)\n  * [The Control UI says \"unauthorized\" (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now)\n  * [I set `gateway.bind: \"tailnet\"` but it can't bind / nothing listens](#i-set-gatewaybind-tailnet-but-it-cant-bind-nothing-listens)\n  * [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host)\n  * [What does \"invalid handshake\" / code 1008 mean?](#what-does-invalid-handshake-code-1008-mean)\n* [Logging and debugging](#logging-and-debugging)\n  * [Where are logs?](#where-are-logs)\n  * [How do I start/stop/restart the Gateway service?](#how-do-i-startstoprestart-the-gateway-service)\n  * [I closed my terminal on Windows - how do I restart OpenClaw?](#i-closed-my-terminal-on-windows-how-do-i-restart-openclaw)\n  * [The Gateway is up but replies never arrive. What should I check?](#the-gateway-is-up-but-replies-never-arrive-what-should-i-check)\n  * [\"Disconnected from gateway: no reason\" - what now?](#disconnected-from-gateway-no-reason-what-now)\n  * [Telegram setMyCommands fails with network errors. What should I check?](#telegram-setmycommands-fails-with-network-errors-what-should-i-check)\n  * [TUI shows no output. What should I check?](#tui-shows-no-output-what-should-i-check)\n  * [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway)\n  * [ELI5: `openclaw gateway restart` vs `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway)\n  * [What's the fastest way to get more details when something fails?](#whats-the-fastest-way-to-get-more-details-when-something-fails)\n* [Media & attachments](#media-attachments)\n  * [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent)\n* [Security and access control](#security-and-access-control)\n  * [Is it safe to expose OpenClaw to inbound DMs?](#is-it-safe-to-expose-openclaw-to-inbound-dms)\n  * [Is prompt injection only a concern for public bots?](#is-prompt-injection-only-a-concern-for-public-bots)\n  * [Should my bot have its own email GitHub account or phone number](#should-my-bot-have-its-own-email-github-account-or-phone-number)\n  * [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)\n  * [Can I use cheaper models for personal assistant tasks?](#can-i-use-cheaper-models-for-personal-assistant-tasks)\n  * [I ran `/start` in Telegram but didn't get a pairing code](#i-ran-start-in-telegram-but-didnt-get-a-pairing-code)\n  * [WhatsApp: will it message my contacts? How does pairing work?](#whatsapp-will-it-message-my-contacts-how-does-pairing-work)\n* [Chat commands, aborting tasks, and \"it won't stop\"](#chat-commands-aborting-tasks-and-it-wont-stop)\n  * [How do I stop internal system messages from showing in chat](#how-do-i-stop-internal-system-messages-from-showing-in-chat)\n  * [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task)\n  * [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)\n  * [Why does it feel like the bot \"ignores\" rapid-fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages)\n\n## First 60 seconds if something's broken\n\n1. **Quick status (first check)**\n\nFast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when gateway is reachable).\n\n2. **Pasteable report (safe to share)**\n\nRead-only diagnosis with log tail (tokens redacted).\n\n3. **Daemon + port state**\n\nShows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used.\n\nRuns gateway health checks + provider probes (requires a reachable gateway). See [Health](/gateway/health).\n\n5. **Tail the latest log**\n\nIf RPC is down, fall back to:\n\nFile logs are separate from service logs; see [Logging](/logging) and [Troubleshooting](/gateway/troubleshooting).\n\n6. **Run the doctor (repairs)**\n\nRepairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor).\n\n7. **Gateway snapshot**\n   \n   Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health).\n\n## Quick start and first-run setup\n\n### Im stuck whats the fastest way to get unstuck\n\nUse a local AI agent that can **see your machine**. That is far more effective than asking\nin Discord, because most \"I'm stuck\" cases are **local config or environment issues** that\nremote helpers cannot inspect.\n\n* **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)\n* **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)\n\nThese tools can read the repo, run commands, inspect logs, and help fix your machine-level\nsetup (PATH, services, permissions, auth files). Give them the **full source checkout** via\nthe hackable (git) install:\n\nThis installs OpenClaw **from a git checkout**, so the agent can read the code + docs and\nreason about the exact version you are running. You can always switch back to stable later\nby re-running the installer without `--install-method git`.\n\nTip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the\nnecessary commands. That keeps changes small and easier to audit.\n\nIf you discover a real bug or fix, please file a GitHub issue or send a PR:\n[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)\n[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)\n\nStart with these commands (share outputs when asking for help):\n\n* `openclaw status`: quick snapshot of gateway/agent health + basic config.\n* `openclaw models status`: checks provider auth + model availability.\n* `openclaw doctor`: validates and repairs common config/state issues.\n\nOther useful CLI checks: `openclaw status --all`, `openclaw logs --follow`,\n`openclaw gateway status`, `openclaw health --verbose`.\n\nQuick debug loop: [First 60 seconds if something's broken](#first-60-seconds-if-somethings-broken).\nInstall docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating).\n\n### What's the recommended way to install and set up OpenClaw\n\nThe repo recommends running from source and using the onboarding wizard:\n\nThe wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.\n\nFrom source (contributors/dev):\n\nIf you don't have a global install yet, run it via `pnpm openclaw onboard`.\n\n### How do I open the dashboard after onboarding\n\nThe 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.\n\n### How do I authenticate the dashboard token on localhost vs remote\n\n**Localhost (same machine):**\n\n* Open `http://127.0.0.1:18789/`.\n* If it asks for auth, run `openclaw dashboard` and use the tokenized link (`?token=...`).\n* The token is the same value as `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) and is stored by the UI after first load.\n\n**Not on localhost:**\n\n* **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).\n* **Tailnet bind**: run `openclaw gateway --bind tailnet --token \"<token>\"`, open `http://<tailscale-ip>:18789/`, paste token in dashboard settings.\n* **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`.\n\nSee [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.\n\n### What runtime do I need\n\nNode **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.\n\n### Does it run on Raspberry Pi\n\nYes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB**\ndisk as enough for personal use, and note that a **Raspberry Pi 4 can run it**.\n\nIf you want extra headroom (logs, media, other services), **2GB is recommended**, but it's\nnot a hard minimum.\n\nTip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for\nlocal screen/camera/canvas or command execution. See [Nodes](/nodes).\n\n### Any tips for Raspberry Pi installs\n\nShort version: it works, but expect rough edges.\n\n* Use a **64-bit** OS and keep Node >= 22.\n* Prefer the **hackable (git) install** so you can see logs and update fast.\n* Start without channels/skills, then add them one by one.\n* If you hit weird binary issues, it is usually an **ARM compatibility** problem.\n\nDocs: [Linux](/platforms/linux), [Install](/install).\n\n### It is stuck on wake up my friend onboarding will not hatch What now\n\nThat screen depends on the Gateway being reachable and authenticated. The TUI also sends\n\"Wake up, my friend!\" automatically on first hatch. If you see that line with **no reply**\nand tokens stay at 0, the agent never ran.\n\n1. Restart the Gateway:\n\n2. Check status + auth:\n\n3. If it still hangs, run:\n\nIf the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI\nis pointed at the right Gateway. See [Remote access](/gateway/remote).\n\n### Can I migrate my setup to a new machine Mac mini without redoing onboarding\n\nYes. Copy the **state directory** and **workspace**, then run Doctor once. This\nkeeps your bot \"exactly the same\" (memory, session history, auth, and channel\nstate) as long as you copy **both** locations:\n\n1. Install OpenClaw on the new machine.\n2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine.\n3. Copy your workspace (default: `~/.openclaw/workspace`).\n4. Run `openclaw doctor` and restart the Gateway service.\n\nThat preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in\nremote mode, remember the gateway host owns the session store and workspace.\n\n**Important:** if you only commit/push your workspace to GitHub, you're backing\nup **memory + bootstrap files**, but **not** session history or auth. Those live\nunder `~/.openclaw/` (for example `~/.openclaw/agents/<agentId>/sessions/`).\n\nRelated: [Migrating](/install/migrating), [Where things live on disk](/help/faq#where-does-openclaw-store-its-data),\n[Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),\n[Remote mode](/gateway/remote).\n\n### Where do I see what is new in the latest version\n\nCheck the GitHub changelog:\n[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)\n\nNewest entries are at the top. If the top section is marked **Unreleased**, the next dated\nsection is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and\n**Fixes** (plus docs/other sections when needed).\n\n### I cant access docs.openclaw\\.ai SSL error What now\n\nSome Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity\nAdvanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More\ndetail: [Troubleshooting](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity).\nPlease help us unblock it by reporting here: [https://spa.xfinity.com/check\\_url\\_status](https://spa.xfinity.com/check_url_status).\n\nIf you still can't reach the site, the docs are mirrored on GitHub:\n[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)\n\n### What's the difference between stable and beta\n\n**Stable** and **beta** are **npm dist-tags**, not separate code lines:\n\n* `latest` = stable\n* `beta` = early build for testing\n\nWe ship builds to **beta**, test them, and once a build is solid we **promote\nthat same version to `latest`**. That's why beta and stable can point at the\n**same version**.\n\nSee what changed:\n[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)\n\n### How do I install the beta version and whats the difference between beta and dev\n\n**Beta** is the npm dist-tag `beta` (may match `latest`).\n**Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`.\n\nOne-liners (macOS/Linux):\n\nWindows installer (PowerShell):\n[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)\n\nMore detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).\n\n### How long does install and onboarding usually take\n\n* **Install:** 2-5 minutes\n* **Onboarding:** 5-15 minutes depending on how many channels/models you configure\n\nIf it hangs, use [Installer stuck](/help/faq#installer-stuck-how-do-i-get-more-feedback)\nand the fast debug loop in [Im stuck](/help/faq#im-stuck--whats-the-fastest-way-to-get-unstuck).\n\n### How do I try the latest bits\n\n1. **Dev channel (git checkout):**\n\nThis switches to the `main` branch and updates from source.\n\n2. **Hackable install (from the installer site):**\n\nThat gives you a local repo you can edit, then update via git.\n\nIf you prefer a clean clone manually, use:\n\nDocs: [Update](/cli/update), [Development channels](/install/development-channels),\n[Install](/install).\n\n### Installer stuck How do I get more feedback\n\nRe-run the installer with **verbose output**:\n\nBeta install with verbose:\n\nFor a hackable (git) install:\n\nMore options: [Installer flags](/install/installer).\n\n### Windows install says git not found or openclaw not recognized\n\nTwo common Windows issues:\n\n**1) npm error spawn git / git not found**\n\n* Install **Git for Windows** and make sure `git` is on your PATH.\n* Close and reopen PowerShell, then re-run the installer.\n\n**2) openclaw is not recognized after install**\n\n* Your npm global bin folder is not on PATH.\n* Check the path:\n  \n* Ensure `<prefix>\\\\bin` is on PATH (on most systems it is `%AppData%\\\\npm`).\n* Close and reopen PowerShell after updating PATH.\n\nIf you want the smoothest Windows setup, use **WSL2** instead of native Windows.\nDocs: [Windows](/platforms/windows).\n\n### The docs didnt answer my question how do I get a better answer\n\nUse the **hackable (git) install** so you have the full source and docs locally, then ask\nyour bot (or Claude/Codex) *from that folder* so it can read the repo and answer precisely.\n\nMore detail: [Install](/install) and [Installer flags](/install/installer).\n\n### How do I install OpenClaw on Linux\n\nShort answer: follow the Linux guide, then run the onboarding wizard.\n\n* Linux quick path + service install: [Linux](/platforms/linux).\n* Full walkthrough: [Getting Started](/start/getting-started).\n* Installer + updates: [Install & updates](/install/updating).\n\n### How do I install OpenClaw on a VPS\n\nAny Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.\n\nGuides: [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [Fly.io](/platforms/fly).\nRemote access: [Gateway remote](/gateway/remote).\n\n### Where are the cloudVPS install guides\n\nWe keep a **hosting hub** with the common providers. Pick one and follow the guide:\n\n* [VPS hosting](/vps) (all providers in one place)\n* [Fly.io](/platforms/fly)\n* [Hetzner](/platforms/hetzner)\n* [exe.dev](/platforms/exe-dev)\n\nHow it works in the cloud: the **Gateway runs on the server**, and you access it\nfrom your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace\nlive on the server, so treat the host as the source of truth and back it up.\n\nYou can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access\nlocal screen/camera/canvas or run commands on your laptop while keeping the\nGateway in the cloud.\n\nHub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote).\nNodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes).\n\n### Can I ask OpenClaw to update itself\n\nShort answer: **possible, not recommended**. The update flow can restart the\nGateway (which drops the active session), may need a clean git checkout, and\ncan prompt for confirmation. Safer: run updates from a shell as the operator.\n\nIf you must automate from an agent:\n\nDocs: [Update](/cli/update), [Updating](/install/updating).\n\n### What does the onboarding wizard actually do\n\n`openclaw onboard` is the recommended setup path. In **local mode** it walks you through:\n\n* **Model/auth setup** (Anthropic **setup-token** recommended for Claude subscriptions, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)\n* **Workspace** location + bootstrap files\n* **Gateway settings** (bind/port/auth/tailscale)\n* **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)\n* **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)\n* **Health checks** and **skills** selection\n\nIt also warns if your configured model is unknown or missing auth.\n\n### Do I need a Claude or OpenAI subscription to run this\n\nNo. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with\n**local-only models** so your data stays on your device. Subscriptions (Claude\nPro/Max or OpenAI Codex) are optional ways to authenticate those providers.\n\nDocs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),\n[Local models](/gateway/local-models), [Models](/concepts/models).\n\n### Can I use Claude Max subscription without an API key\n\nYes. You can authenticate with a **setup-token**\ninstead of an API key. This is the subscription path.\n\nClaude Pro/Max subscriptions **do not include an API key**, so this is the\ncorrect approach for subscription accounts. Important: you must verify with\nAnthropic that this usage is allowed under their subscription policy and terms.\nIf you want the most explicit, supported path, use an Anthropic API key.\n\n### How does Anthropic setuptoken auth work\n\n`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).\n\n### Where do I find an Anthropic setuptoken\n\nIt is **not** in the Anthropic Console. The setup-token is generated by the **Claude Code CLI** on **any machine**:\n\nCopy 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).\n\n### Do you support Claude subscription auth (Claude Pro/Max)\n\nYes - 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).\n\nNote: Claude subscription access is governed by Anthropic's terms. For production or multi-user workloads, API keys are usually the safer choice.\n\n### Why am I seeing HTTP 429 ratelimiterror from Anthropic\n\nThat means your **Anthropic quota/rate limit** is exhausted for the current window. If you\nuse a **Claude subscription** (setup-token or Claude Code OAuth), wait for the window to\nreset or upgrade your plan. If you use an **Anthropic API key**, check the Anthropic Console\nfor usage/billing and raise limits as needed.\n\nTip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited.\nSee [Models](/cli/models) and [OAuth](/concepts/oauth).\n\n### Is AWS Bedrock supported\n\nYes - 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.\n\n### How does Codex auth work\n\nOpenClaw 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).\n\n### Do you support OpenAI subscription auth Codex OAuth\n\nYes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**. The onboarding wizard\ncan run the OAuth flow for you.\n\nSee [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/wizard).\n\n### How do I set up Gemini CLI OAuth\n\nGemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.\n\n1. Enable the plugin: `openclaw plugins enable google-gemini-cli-auth`\n2. Login: `openclaw models auth login --provider google-gemini-cli --set-default`\n\nThis stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).\n\n### Is a local model OK for casual chats\n\nUsually 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).\n\n### How do I keep hosted model traffic in a specific region\n\nPick 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.\n\n### Do I have to buy a Mac Mini to install this\n\nNo. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people\nbuy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too.\n\nYou 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.\n\nDocs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).\n\n### Do I need a Mac mini for iMessage support\n\nYou need **some macOS device** signed into Messages. It does **not** have to be a Mac mini -\nany Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere.\n\n* Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages.\n* Run everything on the Mac if you want the simplest single‑machine setup.\n\nDocs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes),\n[Mac remote mode](/platforms/mac/remote).\n\n### If I buy a Mac mini to run OpenClaw can I connect it to my MacBook Pro\n\nYes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a\n**node** (companion device). Nodes don't run the Gateway - they provide extra\ncapabilities like screen/camera/canvas and `system.run` on that device.\n\n* Gateway on the Mac mini (always-on).\n* MacBook Pro runs the macOS app or a node host and pairs to the Gateway.\n* Use `openclaw nodes status` / `openclaw nodes list` to see it.\n\nDocs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).\n\nBun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.\nUse **Node** for stable gateways.\n\nIf you still want to experiment with Bun, do it on a non-production gateway\nwithout WhatsApp/Telegram.\n\n### Telegram what goes in allowFrom\n\n`channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric, recommended) or `@username`. It is not the bot username.\n\nSafer (no third-party bot):\n\n* DM your bot, then run `openclaw logs --follow` and read `from.id`.\n\n* DM your bot, then call `https://api.telegram.org/bot<bot_token>/getUpdates` and read `message.from.id`.\n\nThird-party (less private):\n\n* DM `@userinfobot` or `@getidsbot`.\n\nSee [/channels/telegram](/channels/telegram#access-control-dms--groups).\n\n### Can multiple people use one WhatsApp number with different OpenClaw instances\n\nYes, 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).\n\n### Can I run a fast chat agent and an Opus for coding agent\n\nYes. 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).\n\n### Does Homebrew work on Linux\n\nYes. Homebrew supports Linux (Linuxbrew). Quick setup:\n\nIf 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.\nRecent 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.\n\n### What's the difference between the hackable git install and npm install\n\n* **Hackable (git) install:** full source checkout, editable, best for contributors.\n  You run builds locally and can patch code/docs.\n* **npm install:** global CLI install, no repo, best for \"just run it.\"\n  Updates come from npm dist-tags.\n\nDocs: [Getting started](/start/getting-started), [Updating](/install/updating).\n\n### Can I switch between npm and git installs later\n\nYes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.\nThis **does not delete your data** - it only changes the OpenClaw code install. Your state\n(`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched.\n\nDoctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).\n\nBackup tips: see [Backup strategy](/help/faq#whats-the-recommended-backup-strategy).\n\n### Should I run the Gateway on my laptop or a VPS\n\nShort answer: **if you want 24/7 reliability, use a VPS**. If you want the\nlowest friction and you're okay with sleep/restarts, run it locally.\n\n**Laptop (local Gateway)**\n\n* **Pros:** no server cost, direct access to local files, live browser window.\n* **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.\n\n* **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.\n* **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.\n\n**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).\n\n**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.\n\n### How important is it to run OpenClaw on a dedicated machine\n\nNot required, but **recommended for reliability and isolation**.\n\n* **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.\n* **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates.\n\nIf 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).\nFor security guidance, read [Security](/gateway/security).\n\n### What are the minimum VPS requirements and recommended OS\n\nOpenClaw is lightweight. For a basic Gateway + one chat channel:\n\n* **Absolute minimum:** 1 vCPU, 1GB RAM, \\~500MB disk.\n* **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.\n\nOS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there.\n\nDocs: [Linux](/platforms/linux), [VPS hosting](/vps).\n\n### Can I run OpenClaw in a VM and what are the requirements\n\nYes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough\nRAM for the Gateway and any channels you enable.\n\n* **Absolute minimum:** 1 vCPU, 1GB RAM.\n* **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools.\n* **OS:** Ubuntu LTS or another modern Debian/Ubuntu.\n\nIf you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling\ncompatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).\nIf you are running macOS in a VM, see [macOS VM](/platforms/macos-vm).\n\n### What is OpenClaw in one paragraph\n\nOpenClaw 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.\n\n### What's the value proposition\n\nOpenClaw is not \"just a Claude wrapper.\" It's a **local-first control plane** that lets you run a\ncapable assistant on **your own hardware**, reachable from the chat apps you already use, with\nstateful sessions, memory, and tools - without handing control of your workflows to a hosted\nSaaS.\n\n* **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the\n  workspace + session history local.\n* **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc,\n  plus mobile voice and Canvas on supported platforms.\n* **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per-agent routing\n  and failover.\n* **Local-only option:** run local models so **all data can stay on your device** if you want.\n* **Multi-agent routing:** separate agents per channel, account, or task, each with its own\n  workspace and defaults.\n* **Open source and hackable:** inspect, extend, and self-host without vendor lock-in.\n\nDocs: [Gateway](/gateway), [Channels](/channels), [Multi-agent](/concepts/multi-agent),\n[Memory](/concepts/memory).\n\n### I just set it up what should I do first\n\n* Build a website (WordPress, Shopify, or a simple static site).\n* Prototype a mobile app (outline, screens, API plan).\n* Organize files and folders (cleanup, naming, tagging).\n* Connect Gmail and automate summaries or follow ups.\n\nIt can handle large tasks, but it works best when you split them into phases and\nuse sub agents for parallel work.\n\n### What are the top five everyday use cases for OpenClaw\n\nEveryday wins usually look like:\n\n* **Personal briefings:** summaries of inbox, calendar, and news you care about.\n* **Research and drafting:** quick research, summaries, and first drafts for emails or docs.\n* **Reminders and follow ups:** cron or heartbeat driven nudges and checklists.\n* **Browser automation:** filling forms, collecting data, and repeating web tasks.\n* **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat.\n\n### Can OpenClaw help with lead gen outreach ads and blogs for a SaaS\n\nYes for **research, qualification, and drafting**. It can scan sites, build shortlists,\nsummarize prospects, and write outreach or ad copy drafts.\n\nFor **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and\nplatform policies, and review anything before it is sent. The safest pattern is to let\nOpenClaw draft and you approve.\n\nDocs: [Security](/gateway/security).\n\n### What are the advantages vs Claude Code for web development\n\nOpenClaw is a **personal assistant** and coordination layer, not an IDE replacement. Use\nClaude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you\nwant durable memory, cross-device access, and tool orchestration.\n\n* **Persistent memory + workspace** across sessions\n* **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat)\n* **Tool orchestration** (browser, files, scheduling, hooks)\n* **Always-on Gateway** (run on a VPS, interact from anywhere)\n* **Nodes** for local browser/screen/camera/exec\n\nShowcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)\n\n## Skills and automation\n\n### How do I customize skills without keeping the repo dirty\n\nUse 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.\n\n### Can I load skills from a custom folder\n\nYes. 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`.\n\n### How can I use different models for different tasks\n\nToday the supported patterns are:\n\n* **Cron jobs**: isolated jobs can set a `model` override per job.\n* **Sub-agents**: route tasks to separate agents with different default models.\n* **On-demand switch**: use `/model` to switch the current session model at any time.\n\nSee [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands).\n\n### The bot freezes while doing heavy work How do I offload that\n\nUse **sub-agents** for long or parallel tasks. Sub-agents run in their own session,\nreturn a summary, and keep your main chat responsive.\n\nAsk your bot to \"spawn a sub-agent for this task\" or use `/subagents`.\nUse `/status` in chat to see what the Gateway is doing right now (and whether it is busy).\n\nToken tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a\ncheaper model for sub-agents via `agents.defaults.subagents.model`.\n\nDocs: [Sub-agents](/tools/subagents).\n\n### Cron or reminders do not fire What should I check\n\nCron runs inside the Gateway process. If the Gateway is not running continuously,\nscheduled jobs will not run.\n\n* Confirm cron is enabled (`cron.enabled`) and `OPENCLAW_SKIP_CRON` is not set.\n* Check the Gateway is running 24/7 (no sleep/restarts).\n* Verify timezone settings for the job (`--tz` vs host timezone).\n\nDocs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat).\n\n### How do I install skills on Linux\n\nUse **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux.\nBrowse skills at [https://clawhub.com](https://clawhub.com).\n\nInstall the ClawHub CLI (pick one package manager):\n\n### Can OpenClaw run tasks on a schedule or continuously in the background\n\nYes. Use the Gateway scheduler:\n\n* **Cron jobs** for scheduled or recurring tasks (persist across restarts).\n* **Heartbeat** for \"main session\" periodic checks.\n* **Isolated jobs** for autonomous agents that post summaries or deliver to chats.\n\nDocs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat),\n[Heartbeat](/gateway/heartbeat).\n\n**Can I run Apple macOS only skills from Linux**\n\nNot 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 `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating.\n\nYou have three supported patterns:\n\n**Option A - run the Gateway on a Mac (simplest).**\nRun the Gateway where the macOS binaries exist, then connect from Linux in [remote mode](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere) or over Tailscale. The skills load normally because the Gateway host is macOS.\n\n**Option B - use a macOS node (no SSH).**\nRun 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.\n\n**Option C - proxy macOS binaries over SSH (advanced).**\nKeep 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.\n\n1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes):\n   \n2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`).\n3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux:\n   \n4. Start a new session so the skills snapshot refreshes.\n\n### Do you have a Notion or HeyGen integration\n\n* **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs).\n* **Browser automation:** works without code but is slower and more fragile.\n\nIf you want to keep context per client (agency workflows), a simple pattern is:\n\n* One Notion page per client (context + preferences + active work).\n* Ask the agent to fetch that page at the start of a session.\n\nIf you want a native integration, open a feature request or build a skill\ntargeting those APIs.\n\nClawHub 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](/tools/skills) and [ClawHub](/tools/clawhub).\n\n### How do I install the Chrome extension for browser takeover\n\nUse the built-in installer, then load the unpacked extension in Chrome:\n\nThen Chrome → `chrome://extensions` → enable \"Developer mode\" → \"Load unpacked\" → pick that folder.\n\nFull guide (including remote Gateway + security notes): [Chrome extension](/tools/chrome-extension)\n\nIf the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need anything extra.\nIf the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.\nYou still need to click the extension button on the tab you want to control (it doesn't auto-attach).\n\n## Sandboxing and memory\n\n### Is there a dedicated sandboxing doc\n\nYes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker).\n\n### Docker feels limited How do I enable full features\n\nThe default image is security-first and runs as the `node` user, so it does not\ninclude system packages, Homebrew, or bundled browsers. For a fuller setup:\n\n* Persist `/home/node` with `OPENCLAW_HOME_VOLUME` so caches survive.\n* Bake system deps into the image with `OPENCLAW_DOCKER_APT_PACKAGES`.\n* Install Playwright browsers via the bundled CLI:\n  `node /app/node_modules/playwright-core/cli.js install chromium`\n* Set `PLAYWRIGHT_BROWSERS_PATH` and ensure the path is persisted.\n\nDocs: [Docker](/install/docker), [Browser](/tools/browser).\n\n**Can I keep DMs personal but make groups public sandboxed with one agent**\n\nYes - if your private traffic is **DMs** and your public traffic is **groups**.\n\nUse `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`.\n\nSetup walkthrough + example config: [Groups: personal DMs + public groups](/concepts/groups#pattern-personal-dms-public-groups-single-agent)\n\nKey config reference: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)\n\n### How do I bind a host folder into the sandbox\n\nSet `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](/gateway/sandboxing#custom-bind-mounts) and [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) for examples and safety notes.\n\n### How does memory work\n\nOpenClaw memory is just Markdown files in the agent workspace:\n\n* Daily notes in `memory/YYYY-MM-DD.md`\n* Curated long-term notes in `MEMORY.md` (main/private sessions only)\n\nOpenClaw also runs a **silent pre-compaction memory flush** to remind the model\nto write durable notes before auto-compaction. This only runs when the workspace\nis writable (read-only sandboxes skip it). See [Memory](/concepts/memory).\n\n### Memory keeps forgetting things How do I make it stick\n\nAsk the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`,\nshort-term context goes into `memory/YYYY-MM-DD.md`.\n\nThis is still an area we are improving. It helps to remind the model to store memories;\nit will know what to do. If it keeps forgetting, verify the Gateway is using the same\nworkspace on every run.\n\nDocs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace).\n\n### Does semantic memory search require an OpenAI API key\n\nOnly if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and\ndoes **not** grant embeddings access, so **signing in with Codex (OAuth or the\nCodex CLI login)** does not help for semantic memory search. OpenAI embeddings\nstill need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`).\n\nIf you don't set a provider explicitly, OpenClaw auto-selects a provider when it\ncan resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars).\nIt prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key\nresolves. If neither key is available, memory search stays disabled until you\nconfigure it. If you have a local model path configured and present, OpenClaw\nprefers `local`.\n\nIf you'd rather stay local, set `memorySearch.provider = \"local\"` (and optionally\n`memorySearch.fallback = \"none\"`). If you want Gemini embeddings, set\n`memorySearch.provider = \"gemini\"` and provide `GEMINI_API_KEY` (or\n`memorySearch.remote.apiKey`). We support **OpenAI, Gemini, or local** embedding\nmodels - see [Memory](/concepts/memory) for the setup details.\n\n### Does memory persist forever What are the limits\n\nMemory files live on disk and persist until you delete them. The limit is your\nstorage, not the model. The **session context** is still limited by the model\ncontext window, so long conversations can compact or truncate. That is why\nmemory search exists - it pulls only the relevant parts back into context.\n\nDocs: [Memory](/concepts/memory), [Context](/concepts/context).\n\n## Where things live on disk\n\n### Is all data used with OpenClaw saved locally\n\nNo - **OpenClaw's state is local**, but **external services still see what you send them**.\n\n* **Local by default:** sessions, memory files, config, and workspace live on the Gateway host\n  (`~/.openclaw` + your workspace directory).\n* **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to\n  their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their\n  servers.\n* **You control the footprint:** using local models keeps prompts on your machine, but channel\n  traffic still goes through the channel's servers.\n\nRelated: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory).\n\n### Where does OpenClaw store its data\n\nEverything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`):\n\n| Path                                                            | Purpose                                                      |\n| --------------------------------------------------------------- | ------------------------------------------------------------ |\n| `$OPENCLAW_STATE_DIR/openclaw.json`                             | Main config (JSON5)                                          |\n| `$OPENCLAW_STATE_DIR/credentials/oauth.json`                    | Legacy OAuth import (copied into auth profiles on first use) |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys)                             |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json`          | Runtime auth cache (managed automatically)                   |\n| `$OPENCLAW_STATE_DIR/credentials/`                              | Provider state (e.g. `whatsapp/<accountId>/creds.json`)      |\n| `$OPENCLAW_STATE_DIR/agents/`                                   | Per-agent state (agentDir + sessions)                        |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`                | Conversation history & state (per agent)                     |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json`   | Session metadata (per agent)                                 |\n\nLegacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`).\n\nYour **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/.openclaw/workspace`).\n\n### Where should AGENTSmd SOULmd USERmd MEMORYmd live\n\nThese files live in the **agent workspace**, not `~/.openclaw`.\n\n* **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`,\n  `MEMORY.md` (or `memory.md`), `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`.\n* **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs,\n  and shared skills (`~/.openclaw/skills`).\n\nDefault workspace is `~/.openclaw/workspace`, configurable via:\n\nIf the bot \"forgets\" after a restart, confirm the Gateway is using the same\nworkspace on every launch (and remember: remote mode uses the **gateway host's**\nworkspace, not your local laptop).\n\nTip: if you want a durable behavior or preference, ask the bot to **write it into\nAGENTS.md or MEMORY.md** rather than relying on chat history.\n\nSee [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).\n\n### What's the recommended backup strategy\n\nPut your **agent workspace** in a **private** git repo and back it up somewhere\nprivate (for example GitHub private). This captures memory + AGENTS/SOUL/USER\nfiles, and lets you restore the assistant's \"mind\" later.\n\nDo **not** commit anything under `~/.openclaw` (credentials, sessions, tokens).\nIf you need a full restore, back up both the workspace and the state directory\nseparately (see the migration question above).\n\nDocs: [Agent workspace](/concepts/agent-workspace).\n\n### How do I completely uninstall OpenClaw\n\nSee the dedicated guide: [Uninstall](/install/uninstall).\n\n### Can agents work outside the workspace\n\nYes. The workspace is the **default cwd** and memory anchor, not a hard sandbox.\nRelative paths resolve inside the workspace, but absolute paths can access other\nhost locations unless sandboxing is enabled. If you need isolation, use\n[`agents.defaults.sandbox`](/gateway/sandboxing) or per-agent sandbox settings. If you\nwant a repo to be the default working directory, point that agent's\n`workspace` to the repo root. The OpenClaw repo is just source code; keep the\nworkspace separate unless you intentionally want the agent to work inside it.\n\nExample (repo as default cwd):\n\n### Im in remote mode where is the session store\n\nSession state is owned by the **gateway host**. If you're in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session).\n\n### What format is the config Where is it\n\nOpenClaw reads an optional **JSON5** config from `$OPENCLAW_CONFIG_PATH` (default: `~/.openclaw/openclaw.json`):\n\nIf the file is missing, it uses safe-ish defaults (including a default workspace of `~/.openclaw/workspace`).\n\n### I set gatewaybind lan or tailnet and now nothing listens the UI says unauthorized\n\nNon-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`).\n\n* `gateway.remote.token` is for **remote CLI calls** only; it does not enable local gateway auth.\n* The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs.\n\n### Why do I need a token on localhost now\n\nThe wizard generates a gateway token by default (even on loopback) so **local WS clients must authenticate**. This blocks other local processes from calling the Gateway. Paste the token into the Control UI settings (or your client config) to connect.\n\nIf you **really** want open loopback, remove `gateway.auth` from your config. Doctor can generate a token for you any time: `openclaw doctor --generate-gateway-token`.\n\n### Do I have to restart after changing config\n\nThe Gateway watches the config and supports hot-reload:\n\n* `gateway.reload.mode: \"hybrid\"` (default): hot-apply safe changes, restart for critical ones\n* `hot`, `restart`, `off` are also supported\n\n### How do I enable web search and web fetch\n\n`web_fetch` works without an API key. `web_search` requires a Brave Search API\nkey. **Recommended:** run `openclaw configure --section web` to store it in\n`tools.web.search.apiKey`. Environment alternative: set `BRAVE_API_KEY` for the\nGateway process.\n\n* If you use allowlists, add `web_search`/`web_fetch` or `group:web`.\n* `web_fetch` is enabled by default (unless explicitly disabled).\n* Daemons read env vars from `~/.openclaw/.env` (or the service environment).\n\nDocs: [Web tools](/tools/web).\n\n### How do I run a central Gateway with specialized workers across devices\n\nThe common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**:\n\n* **Gateway (central):** owns channels (Signal/WhatsApp), routing, and sessions.\n* **Nodes (devices):** Macs/iOS/Android connect as peripherals and expose local tools (`system.run`, `canvas`, `camera`).\n* **Agents (workers):** separate brains/workspaces for special roles (e.g. \"Hetzner ops\", \"Personal data\").\n* **Sub-agents:** spawn background work from a main agent when you want parallelism.\n* **TUI:** connect to the Gateway and switch agents/sessions.\n\nDocs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/tui).\n\n### Can the OpenClaw browser run headless\n\nYes. It's a config option:\n\nDefault is `false` (headful). Headless is more likely to trigger anti-bot checks on some sites. See [Browser](/tools/browser).\n\nHeadless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences:\n\n* No visible browser window (use screenshots if you need visuals).\n* Some sites are stricter about automation in headless mode (CAPTCHAs, anti-bot).\n  For example, X/Twitter often blocks headless sessions.\n\n### How do I use Brave for browser control\n\nSet `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway.\nSee the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser).\n\n## Remote gateways + nodes\n\n### How do commands propagate between Telegram the gateway and nodes\n\nTelegram messages are handled by the **gateway**. The gateway runs the agent and\nonly then calls nodes over the **Gateway WebSocket** when a node tool is needed:\n\nTelegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram\n\nNodes don't see inbound provider traffic; they only receive node RPC calls.\n\n### How can my agent access my computer if the Gateway is hosted remotely\n\nShort answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can\ncall `node.*` tools (screen, camera, system) on your local machine over the Gateway WebSocket.\n\n1. Run the Gateway on the always-on host (VPS/home server).\n2. Put the Gateway host + your computer on the same tailnet.\n3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).\n4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet)\n   so it can register as a node.\n5. Approve the node on the Gateway:\n\nNo separate TCP bridge is required; nodes connect over the Gateway WebSocket.\n\nSecurity reminder: pairing a macOS node allows `system.run` on that machine. Only\npair devices you trust, and review [Security](/gateway/security).\n\nDocs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security).\n\n### Tailscale is connected but I get no replies What now\n\n* Gateway is running: `openclaw gateway status`\n* Gateway health: `openclaw status`\n* Channel health: `openclaw channels status`\n\nThen verify auth and routing:\n\n* If you use Tailscale Serve, make sure `gateway.auth.allowTailscale` is set correctly.\n* If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port.\n* Confirm your allowlists (DM or group) include your account.\n\nDocs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels).\n\n### Can two OpenClaw instances talk to each other local VPS\n\nYes. There is no built-in \"bot-to-bot\" bridge, but you can wire it up in a few\nreliable ways:\n\n**Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp).\nHave Bot A send a message to Bot B, then let Bot B reply as usual.\n\n**CLI bridge (generic):** run a script that calls the other Gateway with\n`openclaw agent --message ... --deliver`, targeting a chat where the other bot\nlistens. If one bot is on a remote VPS, point your CLI at that remote Gateway\nvia SSH/Tailscale (see [Remote access](/gateway/remote)).\n\nExample pattern (run from a machine that can reach the target Gateway):\n\nTip: add a guardrail so the two bots do not loop endlessly (mention-only, channel\nallowlists, or a \"do not reply to bot messages\" rule).\n\nDocs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send).\n\n### Do I need separate VPSes for multiple agents\n\nNo. One Gateway can host multiple agents, each with its own workspace, model defaults,\nand routing. That is the normal setup and it is much cheaper and simpler than running\none VPS per agent.\n\nUse separate VPSes only when you need hard isolation (security boundaries) or very\ndifferent configs that you do not want to share. Otherwise, keep one Gateway and\nuse multiple agents or sub-agents.\n\n### Is there a benefit to using a node on my personal laptop instead of SSH from a VPS\n\nYes - nodes are the first-class way to reach your laptop from a remote Gateway, and they\nunlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is\nlightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common\nsetup is an always-on host plus your laptop as a node.\n\n* **No inbound SSH required.** Nodes connect out to the Gateway WebSocket and use device pairing.\n* **Safer execution controls.** `system.run` is gated by node allowlists/approvals on that laptop.\n* **More device tools.** Nodes expose `canvas`, `camera`, and `screen` in addition to `system.run`.\n* **Local browser automation.** Keep the Gateway on a VPS, but run Chrome locally and relay control\n  with the Chrome extension + a node host on the laptop.\n\nSSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and\ndevice automation.\n\nDocs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Chrome extension](/tools/chrome-extension).\n\n### Should I install on a second laptop or just add a node\n\nIf you only need **local tools** (screen/camera/exec) on the second laptop, add it as a\n**node**. That keeps a single Gateway and avoids duplicated config. Local node tools are\ncurrently macOS-only, but we plan to extend them to other OSes.\n\nInstall a second Gateway only when you need **hard isolation** or two fully separate bots.\n\nDocs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways).\n\n### Do nodes run a gateway service\n\nNo. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect\nto the gateway (iOS/Android nodes, or macOS \"node mode\" in the menubar app). For headless node\nhosts and CLI control, see [Node host CLI](/cli/node).\n\nA full restart is required for `gateway`, `discovery`, and `canvasHost` changes.\n\n### Is there an API RPC way to apply config\n\nYes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation.\n\n### configapply wiped my config How do I recover and avoid this\n\n`config.apply` replaces the **entire config**. If you send a partial object, everything\nelse is removed.\n\n* Restore from backup (git or a copied `~/.openclaw/openclaw.json`).\n* If you have no backup, re-run `openclaw doctor` and reconfigure channels/models.\n* If this was unexpected, file a bug and include your last known config or any backup.\n* A local coding agent can often reconstruct a working config from logs or history.\n\n* Use `openclaw config set` for small changes.\n* Use `openclaw configure` for interactive edits.\n\nDocs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor).\n\n### What's a minimal sane config for a first install\n\nThis sets your workspace and restricts who can trigger the bot.\n\n### How do I set up Tailscale on a VPS and connect from my Mac\n\n1. **Install + login on the VPS**\n   \n2. **Install + login on your Mac**\n   * Use the Tailscale app and sign in to the same tailnet.\n3. **Enable MagicDNS (recommended)**\n   * In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.\n4. **Use the tailnet hostname**\n   * SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`\n   * Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`\n\nIf you want the Control UI without SSH, use Tailscale Serve on the VPS:\n\nThis keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale).\n\n### How do I connect a Mac node to a remote Gateway Tailscale Serve\n\nServe exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint.\n\n1. **Make sure the VPS + Mac are on the same tailnet**.\n2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).\n   The app will tunnel the Gateway port and connect as a node.\n3. **Approve the node** on the gateway:\n\nDocs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote).\n\n## Env vars and .env loading\n\n### How does OpenClaw load environment variables\n\nOpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:\n\n* `.env` from the current working directory\n* a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`)\n\nNeither `.env` file overrides existing env vars.\n\nYou can also define inline env vars in config (applied only if missing from the process env):\n\nSee [/environment](/environment) for full precedence and sources.\n\n### I started the Gateway via the service and my env vars disappeared What now\n\n1. Put the missing keys in `~/.openclaw/.env` so they're picked up even when the service doesn't inherit your shell env.\n2. Enable shell import (opt-in convenience):\n\nThis runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:\n`OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`.\n\n### I set COPILOTGITHUBTOKEN but models status shows Shell env off Why\n\n`openclaw models status` reports whether **shell env import** is enabled. \"Shell env: off\"\ndoes **not** mean your env vars are missing - it just means OpenClaw won't load\nyour login shell automatically.\n\nIf the Gateway runs as a service (launchd/systemd), it won't inherit your shell\nenvironment. Fix by doing one of these:\n\n1. Put the token in `~/.openclaw/.env`:\n   \n2. Or enable shell import (`env.shellEnv.enabled: true`).\n3. Or add it to your config `env` block (applies only if missing).\n\nThen restart the gateway and recheck:\n\nCopilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).\nSee [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).\n\n## Sessions & multiple chats\n\n### How do I start a fresh conversation\n\nSend `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).\n\n### Do sessions reset automatically if I never send new\n\nYes. Sessions expire after `session.idleMinutes` (default **60**). The **next**\nmessage starts a fresh session id for that chat key. This does not delete\ntranscripts - it just starts a new session.\n\n### Is there a way to make a team of OpenClaw instances one CEO and many agents\n\nYes, via **multi-agent routing** and **sub-agents**. You can create one coordinator\nagent and several worker agents with their own workspaces and models.\n\nThat said, this is best seen as a **fun experiment**. It is token heavy and often\nless efficient than using one bot with separate sessions. The typical model we\nenvision is one bot you talk to, with different sessions for parallel work. That\nbot can also spawn sub-agents when needed.\n\nDocs: [Multi-agent routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [Agents CLI](/cli/agents).\n\n### Why did context get truncated midtask How do I prevent it\n\nSession context is limited by the model window. Long chats, large tool outputs, or many\nfiles can trigger compaction or truncation.\n\n* Ask the bot to summarize the current state and write it to a file.\n* Use `/compact` before long tasks, and `/new` when switching topics.\n* Keep important context in the workspace and ask the bot to read it back.\n* Use sub-agents for long or parallel work so the main chat stays smaller.\n* Pick a model with a larger context window if this happens often.\n\n### How do I completely reset OpenClaw but keep it installed\n\nUse the reset command:\n\nNon-interactive full reset:\n\nThen re-run onboarding:\n\n* The onboarding wizard also offers **Reset** if it sees an existing config. See [Wizard](/start/wizard).\n* If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-<profile>`).\n* Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).\n\n### Im getting context too large errors how do I reset or compact\n\n* **Compact** (keeps the conversation but summarizes older turns):\n\nor `/compact <instructions>` to guide the summary.\n\n* **Reset** (fresh session ID for the same chat key):\n\nIf it keeps happening:\n\n* Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output.\n* Use a model with a larger context window.\n\nDocs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session).\n\n### Why am I seeing LLM request rejected messagesNcontentXtooluseinput Field required\n\nThis is a provider validation error: the model emitted a `tool_use` block without the required\n`input`. It usually means the session history is stale or corrupted (often after long threads\nor a tool/schema change).\n\nFix: start a fresh session with `/new` (standalone message).\n\n### Why am I getting heartbeat messages every 30 minutes\n\nHeartbeats run every **30m** by default. Tune or disable them:\n\nIf `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown\nheaders like `# Heading`), OpenClaw skips the heartbeat run to save API calls.\nIf the file is missing, the heartbeat still runs and the model decides what to do.\n\nPer-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat).\n\n### Do I need to add a bot account to a WhatsApp group\n\nNo. OpenClaw runs on **your own account**, so if you're in the group, OpenClaw can see it.\nBy default, group replies are blocked until you allow senders (`groupPolicy: \"allowlist\"`).\n\nIf you want only **you** to be able to trigger group replies:\n\n### How do I get the JID of a WhatsApp group\n\nOption 1 (fastest): tail logs and send a test message in the group:\n\nLook for `chatId` (or `from`) ending in `@g.us`, like:\n`1234567890-1234567890@g.us`.\n\nOption 2 (if already configured/allowlisted): list groups from config:\n\nDocs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs).\n\n### Why doesnt OpenClaw reply in a group\n\n* Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).\n* You configured `channels.whatsapp.groups` without `\"*\"` and the group isn't allowlisted.\n\nSee [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).\n\n### Do groupsthreads share context with DMs\n\nDirect chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).\n\n### How many workspaces and agents can I create\n\nNo hard limits. Dozens (even hundreds) are fine, but watch for:\n\n* **Disk growth:** sessions + transcripts live under `~/.openclaw/agents/<agentId>/sessions/`.\n* **Token cost:** more agents means more concurrent model usage.\n* **Ops overhead:** per-agent auth profiles, workspaces, and channel routing.\n\n* Keep one **active** workspace per agent (`agents.defaults.workspace`).\n* Prune old sessions (delete JSONL or store entries) if disk grows.\n* Use `openclaw doctor` to spot stray workspaces and profile mismatches.\n\n### Can I run multiple bots or chats at the same time Slack and how should I set that up\n\nYes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbound messages by\nchannel/account/peer. Slack is supported as a channel and can be bound to specific agents.\n\nBrowser access is powerful but not \"do anything a human can\" - anti-bot, CAPTCHAs, and MFA can\nstill block automation. For the most reliable browser control, use the Chrome extension relay\non the machine that runs the browser (and keep the Gateway anywhere).\n\n* Always-on Gateway host (VPS/Mac mini).\n* One agent per role (bindings).\n* Slack channel(s) bound to those agents.\n* Local browser via extension relay (or a node) when needed.\n\nDocs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack),\n[Browser](/tools/browser), [Chrome extension](/tools/chrome-extension), [Nodes](/nodes).\n\n## Models: defaults, selection, aliases, switching\n\n### What is the default model\n\nOpenClaw's default model is whatever you set as:\n\nModels are referenced as `provider/model` (example: `anthropic/claude-opus-4-5`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`.\n\n### What model do you recommend\n\n**Recommended default:** `anthropic/claude-opus-4-5`.\n**Good alternative:** `anthropic/claude-sonnet-4-5`.\n**Reliable (less character):** `openai/gpt-5.2` - nearly as good as Opus, just less personality.\n**Budget:** `zai/glm-4.7`.\n\nMiniMax M2.1 has its own docs: [MiniMax](/providers/minimax) and\n[Local models](/gateway/local-models).\n\nRule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper\nmodel for routine chat or summaries. You can route models per agent and use sub-agents to\nparallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and\n[Sub-agents](/tools/subagents).\n\nStrong warning: weaker/over-quantized models are more vulnerable to prompt\ninjection and unsafe behavior. See [Security](/gateway/security).\n\nMore context: [Models](/concepts/models).\n\n### Can I use selfhosted models llamacpp vLLM Ollama\n\nYes. If your local server exposes an OpenAI-compatible API, you can point a\ncustom provider at it. Ollama is supported directly and is the easiest path.\n\nSecurity note: smaller or heavily quantized models are more vulnerable to prompt\ninjection. We strongly recommend **large models** for any bot that can use tools.\nIf you still want small models, enable sandboxing and strict tool allowlists.\n\nDocs: [Ollama](/providers/ollama), [Local models](/gateway/local-models),\n[Model providers](/concepts/model-providers), [Security](/gateway/security),\n[Sandboxing](/gateway/sandboxing).\n\n### How do I switch models without wiping my config\n\nUse **model commands** or edit only the **model** fields. Avoid full config replaces.\n\n* `/model` in chat (quick, per-session)\n* `openclaw models set ...` (updates just model config)\n* `openclaw configure --section models` (interactive)\n* edit `agents.defaults.model` in `~/.openclaw/openclaw.json`\n\nAvoid `config.apply` with a partial object unless you intend to replace the whole config.\nIf you did overwrite config, restore from backup or re-run `openclaw doctor` to repair.\n\nDocs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor).\n\n### What do OpenClaw, Flawd, and Krill use for models\n\n* **OpenClaw + Flawd:** Anthropic Opus (`anthropic/claude-opus-4-5`) - see [Anthropic](/providers/anthropic).\n* **Krill:** MiniMax M2.1 (`minimax/MiniMax-M2.1`) - see [MiniMax](/providers/minimax).\n\n### How do I switch models on the fly without restarting\n\nUse the `/model` command as a standalone message:\n\nYou can list available models with `/model`, `/model list`, or `/model status`.\n\n`/model` (and `/model list`) shows a compact, numbered picker. Select by number:\n\nYou can also force a specific auth profile for the provider (per session):\n\nTip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.\nIt also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available.\n\n**How do I unpin a profile I set with profile**\n\nRe-run `/model` **without** the `@profile` suffix:\n\nIf you want to return to the default, pick it from `/model` (or send `/model <default provider/model>`).\nUse `/model status` to confirm which auth profile is active.\n\n### Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding\n\nYes. Set one as default and switch as needed:\n\n* **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model gpt-5.2-codex` for coding.\n* **Default + switch:** set `agents.defaults.model.primary` to `openai-codex/gpt-5.2`, then switch to `openai-codex/gpt-5.2-codex` when coding (or the other way around).\n* **Sub-agents:** route coding tasks to sub-agents with a different default model.\n\nSee [Models](/concepts/models) and [Slash commands](/tools/slash-commands).\n\n### Why do I see Model is not allowed and then no reply\n\nIf `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any\nsession overrides. Choosing a model that isn't in that list returns:\n\nThat error is returned **instead of** a normal reply. Fix: add the model to\n`agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.\n\n### Why do I see Unknown model minimaxMiniMaxM21\n\nThis means the **provider isn't configured** (no MiniMax provider config or auth\nprofile was found), so the model can't be resolved. A fix for this detection is\nin **2026.1.12** (unreleased at the time of writing).\n\n1. Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway.\n2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key\n   exists in env/auth profiles so the provider can be injected.\n3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.1` or\n   `minimax/MiniMax-M2.1-lightning`.\n4. Run:\n   \n   and pick from the list (or `/model list` in chat).\n\nSee [MiniMax](/providers/minimax) and [Models](/concepts/models).\n\n### Can I use MiniMax as my default and OpenAI for complex tasks\n\nYes. Use **MiniMax as the default** and switch models **per session** when needed.\nFallbacks are for **errors**, not \"hard tasks,\" so use `/model` or a separate agent.\n\n**Option A: switch per session**\n\n**Option B: separate agents**\n\n* Agent A default: MiniMax\n* Agent B default: OpenAI\n* Route by agent or use `/agent` to switch\n\nDocs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).\n\n### Are opus sonnet gpt builtin shortcuts\n\nYes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):\n\n* `opus` → `anthropic/claude-opus-4-5`\n* `sonnet` → `anthropic/claude-sonnet-4-5`\n* `gpt` → `openai/gpt-5.2`\n* `gpt-mini` → `openai/gpt-5-mini`\n* `gemini` → `google/gemini-3-pro-preview`\n* `gemini-flash` → `google/gemini-3-flash-preview`\n\nIf you set your own alias with the same name, your value wins.\n\n### How do I defineoverride model shortcuts aliases\n\nAliases come from `agents.defaults.models.<modelId>.alias`. Example:\n\nThen `/model sonnet` (or `/<alias>` when supported) resolves to that model ID.\n\n### How do I add models from other providers like OpenRouter or ZAI\n\nOpenRouter (pay-per-token; many models):\n\nIf you reference a provider/model but the required provider key is missing, you'll get a runtime auth error (e.g. `No API key found for provider \"zai\"`).\n\n**No API key found for provider after adding a new agent**\n\nThis usually means the **new agent** has an empty auth store. Auth is per-agent and\nstored in:\n\n* Run `openclaw agents add <id>` and configure auth during the wizard.\n* Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`.\n\nDo **not** reuse `agentDir` across agents; it causes auth/session collisions.\n\n## Model failover and \"All models failed\"\n\n### How does failover work\n\nFailover happens in two stages:\n\n1. **Auth profile rotation** within the same provider.\n2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`.\n\nCooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing.\n\n### What does this error mean\n\nIt means the system attempted to use the auth profile ID `anthropic:default`, but could not find credentials for it in the expected auth store.\n\n### Fix checklist for No credentials found for profile anthropicdefault\n\n* **Confirm where auth profiles live** (new vs legacy paths)\n  * Current: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`\n  * Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`)\n* **Confirm your env var is loaded by the Gateway**\n  * If you set `ANTHROPIC_API_KEY` in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in `~/.openclaw/.env` or enable `env.shellEnv`.\n* **Make sure you're editing the correct agent**\n  * Multi-agent setups mean there can be multiple `auth-profiles.json` files.\n* **Sanity-check model/auth status**\n  * Use `openclaw models status` to see configured models and whether providers are authenticated.\n\n**Fix checklist for No credentials found for profile anthropic**\n\nThis means the run is pinned to an Anthropic auth profile, but the Gateway\ncan't find it in its auth store.\n\n* **Use a setup-token**\n  * Run `claude setup-token`, then paste it with `openclaw models auth setup-token --provider anthropic`.\n  * If the token was created on another machine, use `openclaw models auth paste-token --provider anthropic`.\n* **If you want to use an API key instead**\n  * Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.\n  * Clear any pinned order that forces a missing profile:\n    \n* **Confirm you're running commands on the gateway host**\n  * In remote mode, auth profiles live on the gateway machine, not your laptop.\n\n### Why did it also try Google Gemini and fail\n\nIf your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw will try it during model fallback. If you haven't configured Google credentials, you'll see `No API key found for provider \"google\"`.\n\nFix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there.\n\n**LLM request rejected message thinking signature required google antigravity**\n\nCause: the session history contains **thinking blocks without signatures** (often from\nan aborted/partial stream). Google Antigravity requires signatures for thinking blocks.\n\nFix: OpenClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a **new session** or set `/thinking off` for that agent.\n\n## Auth profiles: what they are and how to manage them\n\nRelated: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns)\n\n### What is an auth profile\n\nAn auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:\n\n### What are typical profile IDs\n\nOpenClaw uses provider-prefixed IDs like:\n\n* `anthropic:default` (common when no email identity exists)\n* `anthropic:<email>` for OAuth identities\n* custom IDs you choose (e.g. `anthropic:work`)\n\n### Can I control which auth profile is tried first\n\nYes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.<provider>`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.\n\nOpenClaw may temporarily skip a profile if it's in a short **cooldown** (rate limits/timeouts/auth failures) or a longer **disabled** state (billing/insufficient credits). To inspect this, run `openclaw models status --json` and check `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`.\n\nYou can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI:",
  "code_samples": [
    {
      "code": "Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when gateway is reachable).\n\n2. **Pasteable report (safe to share)**",
      "language": "unknown"
    },
    {
      "code": "Read-only diagnosis with log tail (tokens redacted).\n\n3. **Daemon + port state**",
      "language": "unknown"
    },
    {
      "code": "Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used.\n\n4. **Deep probes**",
      "language": "unknown"
    },
    {
      "code": "Runs gateway health checks + provider probes (requires a reachable gateway). See [Health](/gateway/health).\n\n5. **Tail the latest log**",
      "language": "unknown"
    },
    {
      "code": "If RPC is down, fall back to:",
      "language": "unknown"
    },
    {
      "code": "File logs are separate from service logs; see [Logging](/logging) and [Troubleshooting](/gateway/troubleshooting).\n\n6. **Run the doctor (repairs)**",
      "language": "unknown"
    },
    {
      "code": "Repairs/migrates config/state + runs health checks. See [Doctor](/gateway/doctor).\n\n7. **Gateway snapshot**",
      "language": "unknown"
    },
    {
      "code": "Asks the running gateway for a full snapshot (WS-only). See [Health](/gateway/health).\n\n## Quick start and first-run setup\n\n### Im stuck whats the fastest way to get unstuck\n\nUse a local AI agent that can **see your machine**. That is far more effective than asking\nin Discord, because most \"I'm stuck\" cases are **local config or environment issues** that\nremote helpers cannot inspect.\n\n* **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)\n* **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)\n\nThese tools can read the repo, run commands, inspect logs, and help fix your machine-level\nsetup (PATH, services, permissions, auth files). Give them the **full source checkout** via\nthe hackable (git) install:",
      "language": "unknown"
    },
    {
      "code": "This installs OpenClaw **from a git checkout**, so the agent can read the code + docs and\nreason about the exact version you are running. You can always switch back to stable later\nby re-running the installer without `--install-method git`.\n\nTip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the\nnecessary commands. That keeps changes small and easier to audit.\n\nIf you discover a real bug or fix, please file a GitHub issue or send a PR:\n[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)\n[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)\n\nStart with these commands (share outputs when asking for help):",
      "language": "unknown"
    },
    {
      "code": "What they do:\n\n* `openclaw status`: quick snapshot of gateway/agent health + basic config.\n* `openclaw models status`: checks provider auth + model availability.\n* `openclaw doctor`: validates and repairs common config/state issues.\n\nOther useful CLI checks: `openclaw status --all`, `openclaw logs --follow`,\n`openclaw gateway status`, `openclaw health --verbose`.\n\nQuick debug loop: [First 60 seconds if something's broken](#first-60-seconds-if-somethings-broken).\nInstall docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating).\n\n### What's the recommended way to install and set up OpenClaw\n\nThe repo recommends running from source and using the onboarding wizard:",
      "language": "unknown"
    },
    {
      "code": "The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.\n\nFrom source (contributors/dev):",
      "language": "unknown"
    },
    {
      "code": "If you don't have a global install yet, run it via `pnpm openclaw onboard`.\n\n### How do I open the dashboard after onboarding\n\nThe 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.\n\n### How do I authenticate the dashboard token on localhost vs remote\n\n**Localhost (same machine):**\n\n* Open `http://127.0.0.1:18789/`.\n* If it asks for auth, run `openclaw dashboard` and use the tokenized link (`?token=...`).\n* The token is the same value as `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) and is stored by the UI after first load.\n\n**Not on localhost:**\n\n* **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).\n* **Tailnet bind**: run `openclaw gateway --bind tailnet --token \"<token>\"`, open `http://<tailscale-ip>:18789/`, paste token in dashboard settings.\n* **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`.\n\nSee [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.\n\n### What runtime do I need\n\nNode **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.\n\n### Does it run on Raspberry Pi\n\nYes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB**\ndisk as enough for personal use, and note that a **Raspberry Pi 4 can run it**.\n\nIf you want extra headroom (logs, media, other services), **2GB is recommended**, but it's\nnot a hard minimum.\n\nTip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for\nlocal screen/camera/canvas or command execution. See [Nodes](/nodes).\n\n### Any tips for Raspberry Pi installs\n\nShort version: it works, but expect rough edges.\n\n* Use a **64-bit** OS and keep Node >= 22.\n* Prefer the **hackable (git) install** so you can see logs and update fast.\n* Start without channels/skills, then add them one by one.\n* If you hit weird binary issues, it is usually an **ARM compatibility** problem.\n\nDocs: [Linux](/platforms/linux), [Install](/install).\n\n### It is stuck on wake up my friend onboarding will not hatch What now\n\nThat screen depends on the Gateway being reachable and authenticated. The TUI also sends\n\"Wake up, my friend!\" automatically on first hatch. If you see that line with **no reply**\nand tokens stay at 0, the agent never ran.\n\n1. Restart the Gateway:",
      "language": "unknown"
    },
    {
      "code": "2. Check status + auth:",
      "language": "unknown"
    },
    {
      "code": "3. If it still hangs, run:",
      "language": "unknown"
    },
    {
      "code": "If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI\nis pointed at the right Gateway. See [Remote access](/gateway/remote).\n\n### Can I migrate my setup to a new machine Mac mini without redoing onboarding\n\nYes. Copy the **state directory** and **workspace**, then run Doctor once. This\nkeeps your bot \"exactly the same\" (memory, session history, auth, and channel\nstate) as long as you copy **both** locations:\n\n1. Install OpenClaw on the new machine.\n2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine.\n3. Copy your workspace (default: `~/.openclaw/workspace`).\n4. Run `openclaw doctor` and restart the Gateway service.\n\nThat preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in\nremote mode, remember the gateway host owns the session store and workspace.\n\n**Important:** if you only commit/push your workspace to GitHub, you're backing\nup **memory + bootstrap files**, but **not** session history or auth. Those live\nunder `~/.openclaw/` (for example `~/.openclaw/agents/<agentId>/sessions/`).\n\nRelated: [Migrating](/install/migrating), [Where things live on disk](/help/faq#where-does-openclaw-store-its-data),\n[Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),\n[Remote mode](/gateway/remote).\n\n### Where do I see what is new in the latest version\n\nCheck the GitHub changelog:\n[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)\n\nNewest entries are at the top. If the top section is marked **Unreleased**, the next dated\nsection is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and\n**Fixes** (plus docs/other sections when needed).\n\n### I cant access docs.openclaw\\.ai SSL error What now\n\nSome Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity\nAdvanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More\ndetail: [Troubleshooting](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity).\nPlease help us unblock it by reporting here: [https://spa.xfinity.com/check\\_url\\_status](https://spa.xfinity.com/check_url_status).\n\nIf you still can't reach the site, the docs are mirrored on GitHub:\n[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)\n\n### What's the difference between stable and beta\n\n**Stable** and **beta** are **npm dist-tags**, not separate code lines:\n\n* `latest` = stable\n* `beta` = early build for testing\n\nWe ship builds to **beta**, test them, and once a build is solid we **promote\nthat same version to `latest`**. That's why beta and stable can point at the\n**same version**.\n\nSee what changed:\n[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)\n\n### How do I install the beta version and whats the difference between beta and dev\n\n**Beta** is the npm dist-tag `beta` (may match `latest`).\n**Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`.\n\nOne-liners (macOS/Linux):",
      "language": "unknown"
    },
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "Windows installer (PowerShell):\n[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)\n\nMore detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).\n\n### How long does install and onboarding usually take\n\nRough guide:\n\n* **Install:** 2-5 minutes\n* **Onboarding:** 5-15 minutes depending on how many channels/models you configure\n\nIf it hangs, use [Installer stuck](/help/faq#installer-stuck-how-do-i-get-more-feedback)\nand the fast debug loop in [Im stuck](/help/faq#im-stuck--whats-the-fastest-way-to-get-unstuck).\n\n### How do I try the latest bits\n\nTwo options:\n\n1. **Dev channel (git checkout):**",
      "language": "unknown"
    },
    {
      "code": "This switches to the `main` branch and updates from source.\n\n2. **Hackable install (from the installer site):**",
      "language": "unknown"
    },
    {
      "code": "That gives you a local repo you can edit, then update via git.\n\nIf you prefer a clean clone manually, use:",
      "language": "unknown"
    },
    {
      "code": "Docs: [Update](/cli/update), [Development channels](/install/development-channels),\n[Install](/install).\n\n### Installer stuck How do I get more feedback\n\nRe-run the installer with **verbose output**:",
      "language": "unknown"
    },
    {
      "code": "Beta install with verbose:",
      "language": "unknown"
    },
    {
      "code": "For a hackable (git) install:",
      "language": "unknown"
    },
    {
      "code": "More options: [Installer flags](/install/installer).\n\n### Windows install says git not found or openclaw not recognized\n\nTwo common Windows issues:\n\n**1) npm error spawn git / git not found**\n\n* Install **Git for Windows** and make sure `git` is on your PATH.\n* Close and reopen PowerShell, then re-run the installer.\n\n**2) openclaw is not recognized after install**\n\n* Your npm global bin folder is not on PATH.\n* Check the path:",
      "language": "unknown"
    },
    {
      "code": "* Ensure `<prefix>\\\\bin` is on PATH (on most systems it is `%AppData%\\\\npm`).\n* Close and reopen PowerShell after updating PATH.\n\nIf you want the smoothest Windows setup, use **WSL2** instead of native Windows.\nDocs: [Windows](/platforms/windows).\n\n### The docs didnt answer my question how do I get a better answer\n\nUse the **hackable (git) install** so you have the full source and docs locally, then ask\nyour bot (or Claude/Codex) *from that folder* so it can read the repo and answer precisely.",
      "language": "unknown"
    },
    {
      "code": "More detail: [Install](/install) and [Installer flags](/install/installer).\n\n### How do I install OpenClaw on Linux\n\nShort answer: follow the Linux guide, then run the onboarding wizard.\n\n* Linux quick path + service install: [Linux](/platforms/linux).\n* Full walkthrough: [Getting Started](/start/getting-started).\n* Installer + updates: [Install & updates](/install/updating).\n\n### How do I install OpenClaw on a VPS\n\nAny Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.\n\nGuides: [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [Fly.io](/platforms/fly).\nRemote access: [Gateway remote](/gateway/remote).\n\n### Where are the cloudVPS install guides\n\nWe keep a **hosting hub** with the common providers. Pick one and follow the guide:\n\n* [VPS hosting](/vps) (all providers in one place)\n* [Fly.io](/platforms/fly)\n* [Hetzner](/platforms/hetzner)\n* [exe.dev](/platforms/exe-dev)\n\nHow it works in the cloud: the **Gateway runs on the server**, and you access it\nfrom your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace\nlive on the server, so treat the host as the source of truth and back it up.\n\nYou can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access\nlocal screen/camera/canvas or run commands on your laptop while keeping the\nGateway in the cloud.\n\nHub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote).\nNodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes).\n\n### Can I ask OpenClaw to update itself\n\nShort answer: **possible, not recommended**. The update flow can restart the\nGateway (which drops the active session), may need a clean git checkout, and\ncan prompt for confirmation. Safer: run updates from a shell as the operator.\n\nUse the CLI:",
      "language": "unknown"
    },
    {
      "code": "If you must automate from an agent:",
      "language": "unknown"
    },
    {
      "code": "Docs: [Update](/cli/update), [Updating](/install/updating).\n\n### What does the onboarding wizard actually do\n\n`openclaw onboard` is the recommended setup path. In **local mode** it walks you through:\n\n* **Model/auth setup** (Anthropic **setup-token** recommended for Claude subscriptions, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)\n* **Workspace** location + bootstrap files\n* **Gateway settings** (bind/port/auth/tailscale)\n* **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)\n* **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)\n* **Health checks** and **skills** selection\n\nIt also warns if your configured model is unknown or missing auth.\n\n### Do I need a Claude or OpenAI subscription to run this\n\nNo. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with\n**local-only models** so your data stays on your device. Subscriptions (Claude\nPro/Max or OpenAI Codex) are optional ways to authenticate those providers.\n\nDocs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),\n[Local models](/gateway/local-models), [Models](/concepts/models).\n\n### Can I use Claude Max subscription without an API key\n\nYes. You can authenticate with a **setup-token**\ninstead of an API key. This is the subscription path.\n\nClaude Pro/Max subscriptions **do not include an API key**, so this is the\ncorrect approach for subscription accounts. Important: you must verify with\nAnthropic that this usage is allowed under their subscription policy and terms.\nIf you want the most explicit, supported path, use an Anthropic API key.\n\n### How does Anthropic setuptoken auth work\n\n`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).\n\n### Where do I find an Anthropic setuptoken\n\nIt is **not** in the Anthropic Console. The setup-token is generated by the **Claude Code CLI** on **any machine**:",
      "language": "unknown"
    },
    {
      "code": "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).\n\n### Do you support Claude subscription auth (Claude Pro/Max)\n\nYes - 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).\n\nNote: Claude subscription access is governed by Anthropic's terms. For production or multi-user workloads, API keys are usually the safer choice.\n\n### Why am I seeing HTTP 429 ratelimiterror from Anthropic\n\nThat means your **Anthropic quota/rate limit** is exhausted for the current window. If you\nuse a **Claude subscription** (setup-token or Claude Code OAuth), wait for the window to\nreset or upgrade your plan. If you use an **Anthropic API key**, check the Anthropic Console\nfor usage/billing and raise limits as needed.\n\nTip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited.\nSee [Models](/cli/models) and [OAuth](/concepts/oauth).\n\n### Is AWS Bedrock supported\n\nYes - 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.\n\n### How does Codex auth work\n\nOpenClaw 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).\n\n### Do you support OpenAI subscription auth Codex OAuth\n\nYes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**. The onboarding wizard\ncan run the OAuth flow for you.\n\nSee [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/wizard).\n\n### How do I set up Gemini CLI OAuth\n\nGemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.\n\nSteps:\n\n1. Enable the plugin: `openclaw plugins enable google-gemini-cli-auth`\n2. Login: `openclaw models auth login --provider google-gemini-cli --set-default`\n\nThis stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).\n\n### Is a local model OK for casual chats\n\nUsually 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).\n\n### How do I keep hosted model traffic in a specific region\n\nPick 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.\n\n### Do I have to buy a Mac Mini to install this\n\nNo. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people\nbuy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too.\n\nYou 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.\n\nDocs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).\n\n### Do I need a Mac mini for iMessage support\n\nYou need **some macOS device** signed into Messages. It does **not** have to be a Mac mini -\nany Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere.\n\nCommon setups:\n\n* Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages.\n* Run everything on the Mac if you want the simplest single‑machine setup.\n\nDocs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes),\n[Mac remote mode](/platforms/mac/remote).\n\n### If I buy a Mac mini to run OpenClaw can I connect it to my MacBook Pro\n\nYes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a\n**node** (companion device). Nodes don't run the Gateway - they provide extra\ncapabilities like screen/camera/canvas and `system.run` on that device.\n\nCommon pattern:\n\n* Gateway on the Mac mini (always-on).\n* MacBook Pro runs the macOS app or a node host and pairs to the Gateway.\n* Use `openclaw nodes status` / `openclaw nodes list` to see it.\n\nDocs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).\n\n### Can I use Bun\n\nBun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.\nUse **Node** for stable gateways.\n\nIf you still want to experiment with Bun, do it on a non-production gateway\nwithout WhatsApp/Telegram.\n\n### Telegram what goes in allowFrom\n\n`channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric, recommended) or `@username`. It is not the bot username.\n\nSafer (no third-party bot):\n\n* DM your bot, then run `openclaw logs --follow` and read `from.id`.\n\nOfficial Bot API:\n\n* DM your bot, then call `https://api.telegram.org/bot<bot_token>/getUpdates` and read `message.from.id`.\n\nThird-party (less private):\n\n* DM `@userinfobot` or `@getidsbot`.\n\nSee [/channels/telegram](/channels/telegram#access-control-dms--groups).\n\n### Can multiple people use one WhatsApp number with different OpenClaw instances\n\nYes, 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).\n\n### Can I run a fast chat agent and an Opus for coding agent\n\nYes. 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).\n\n### Does Homebrew work on Linux\n\nYes. Homebrew supports Linux (Linuxbrew). Quick setup:",
      "language": "unknown"
    },
    {
      "code": "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.\nRecent 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.\n\n### What's the difference between the hackable git install and npm install\n\n* **Hackable (git) install:** full source checkout, editable, best for contributors.\n  You run builds locally and can patch code/docs.\n* **npm install:** global CLI install, no repo, best for \"just run it.\"\n  Updates come from npm dist-tags.\n\nDocs: [Getting started](/start/getting-started), [Updating](/install/updating).\n\n### Can I switch between npm and git installs later\n\nYes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.\nThis **does not delete your data** - it only changes the OpenClaw code install. Your state\n(`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched.\n\nFrom npm → git:",
      "language": "unknown"
    },
    {
      "code": "From git → npm:",
      "language": "unknown"
    },
    {
      "code": "Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).\n\nBackup tips: see [Backup strategy](/help/faq#whats-the-recommended-backup-strategy).\n\n### Should I run the Gateway on my laptop or a VPS\n\nShort answer: **if you want 24/7 reliability, use a VPS**. If you want the\nlowest friction and you're okay with sleep/restarts, run it locally.\n\n**Laptop (local Gateway)**\n\n* **Pros:** no server cost, direct access to local files, live browser window.\n* **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.\n\n**VPS / cloud**\n\n* **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.\n* **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.\n\n**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).\n\n**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.\n\n### How important is it to run OpenClaw on a dedicated machine\n\nNot required, but **recommended for reliability and isolation**.\n\n* **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.\n* **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates.\n\nIf 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).\nFor security guidance, read [Security](/gateway/security).\n\n### What are the minimum VPS requirements and recommended OS\n\nOpenClaw is lightweight. For a basic Gateway + one chat channel:\n\n* **Absolute minimum:** 1 vCPU, 1GB RAM, \\~500MB disk.\n* **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.\n\nOS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there.\n\nDocs: [Linux](/platforms/linux), [VPS hosting](/vps).\n\n### Can I run OpenClaw in a VM and what are the requirements\n\nYes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough\nRAM for the Gateway and any channels you enable.\n\nBaseline guidance:\n\n* **Absolute minimum:** 1 vCPU, 1GB RAM.\n* **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools.\n* **OS:** Ubuntu LTS or another modern Debian/Ubuntu.\n\nIf you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling\ncompatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).\nIf you are running macOS in a VM, see [macOS VM](/platforms/macos-vm).\n\n## What is OpenClaw?\n\n### What is OpenClaw in one paragraph\n\nOpenClaw 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.\n\n### What's the value proposition\n\nOpenClaw is not \"just a Claude wrapper.\" It's a **local-first control plane** that lets you run a\ncapable assistant on **your own hardware**, reachable from the chat apps you already use, with\nstateful sessions, memory, and tools - without handing control of your workflows to a hosted\nSaaS.\n\nHighlights:\n\n* **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the\n  workspace + session history local.\n* **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc,\n  plus mobile voice and Canvas on supported platforms.\n* **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per-agent routing\n  and failover.\n* **Local-only option:** run local models so **all data can stay on your device** if you want.\n* **Multi-agent routing:** separate agents per channel, account, or task, each with its own\n  workspace and defaults.\n* **Open source and hackable:** inspect, extend, and self-host without vendor lock-in.\n\nDocs: [Gateway](/gateway), [Channels](/channels), [Multi-agent](/concepts/multi-agent),\n[Memory](/concepts/memory).\n\n### I just set it up what should I do first\n\nGood first projects:\n\n* Build a website (WordPress, Shopify, or a simple static site).\n* Prototype a mobile app (outline, screens, API plan).\n* Organize files and folders (cleanup, naming, tagging).\n* Connect Gmail and automate summaries or follow ups.\n\nIt can handle large tasks, but it works best when you split them into phases and\nuse sub agents for parallel work.\n\n### What are the top five everyday use cases for OpenClaw\n\nEveryday wins usually look like:\n\n* **Personal briefings:** summaries of inbox, calendar, and news you care about.\n* **Research and drafting:** quick research, summaries, and first drafts for emails or docs.\n* **Reminders and follow ups:** cron or heartbeat driven nudges and checklists.\n* **Browser automation:** filling forms, collecting data, and repeating web tasks.\n* **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat.\n\n### Can OpenClaw help with lead gen outreach ads and blogs for a SaaS\n\nYes for **research, qualification, and drafting**. It can scan sites, build shortlists,\nsummarize prospects, and write outreach or ad copy drafts.\n\nFor **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and\nplatform policies, and review anything before it is sent. The safest pattern is to let\nOpenClaw draft and you approve.\n\nDocs: [Security](/gateway/security).\n\n### What are the advantages vs Claude Code for web development\n\nOpenClaw is a **personal assistant** and coordination layer, not an IDE replacement. Use\nClaude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you\nwant durable memory, cross-device access, and tool orchestration.\n\nAdvantages:\n\n* **Persistent memory + workspace** across sessions\n* **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat)\n* **Tool orchestration** (browser, files, scheduling, hooks)\n* **Always-on Gateway** (run on a VPS, interact from anywhere)\n* **Nodes** for local browser/screen/camera/exec\n\nShowcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)\n\n## Skills and automation\n\n### How do I customize skills without keeping the repo dirty\n\nUse 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.\n\n### Can I load skills from a custom folder\n\nYes. 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`.\n\n### How can I use different models for different tasks\n\nToday the supported patterns are:\n\n* **Cron jobs**: isolated jobs can set a `model` override per job.\n* **Sub-agents**: route tasks to separate agents with different default models.\n* **On-demand switch**: use `/model` to switch the current session model at any time.\n\nSee [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands).\n\n### The bot freezes while doing heavy work How do I offload that\n\nUse **sub-agents** for long or parallel tasks. Sub-agents run in their own session,\nreturn a summary, and keep your main chat responsive.\n\nAsk your bot to \"spawn a sub-agent for this task\" or use `/subagents`.\nUse `/status` in chat to see what the Gateway is doing right now (and whether it is busy).\n\nToken tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a\ncheaper model for sub-agents via `agents.defaults.subagents.model`.\n\nDocs: [Sub-agents](/tools/subagents).\n\n### Cron or reminders do not fire What should I check\n\nCron runs inside the Gateway process. If the Gateway is not running continuously,\nscheduled jobs will not run.\n\nChecklist:\n\n* Confirm cron is enabled (`cron.enabled`) and `OPENCLAW_SKIP_CRON` is not set.\n* Check the Gateway is running 24/7 (no sleep/restarts).\n* Verify timezone settings for the job (`--tz` vs host timezone).\n\nDebug:",
      "language": "unknown"
    },
    {
      "code": "Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat).\n\n### How do I install skills on Linux\n\nUse **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux.\nBrowse skills at [https://clawhub.com](https://clawhub.com).\n\nInstall the ClawHub CLI (pick one package manager):",
      "language": "unknown"
    },
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "### Can OpenClaw run tasks on a schedule or continuously in the background\n\nYes. Use the Gateway scheduler:\n\n* **Cron jobs** for scheduled or recurring tasks (persist across restarts).\n* **Heartbeat** for \"main session\" periodic checks.\n* **Isolated jobs** for autonomous agents that post summaries or deliver to chats.\n\nDocs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat),\n[Heartbeat](/gateway/heartbeat).\n\n**Can I run Apple macOS only skills from Linux**\n\nNot 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 `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating.\n\nYou have three supported patterns:\n\n**Option A - run the Gateway on a Mac (simplest).**\nRun the Gateway where the macOS binaries exist, then connect from Linux in [remote mode](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere) or over Tailscale. The skills load normally because the Gateway host is macOS.\n\n**Option B - use a macOS node (no SSH).**\nRun 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.\n\n**Option C - proxy macOS binaries over SSH (advanced).**\nKeep 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.\n\n1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes):",
      "language": "unknown"
    },
    {
      "code": "2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`).\n3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux:",
      "language": "unknown"
    },
    {
      "code": "4. Start a new session so the skills snapshot refreshes.\n\n### Do you have a Notion or HeyGen integration\n\nNot built-in today.\n\nOptions:\n\n* **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs).\n* **Browser automation:** works without code but is slower and more fragile.\n\nIf you want to keep context per client (agency workflows), a simple pattern is:\n\n* One Notion page per client (context + preferences + active work).\n* Ask the agent to fetch that page at the start of a session.\n\nIf you want a native integration, open a feature request or build a skill\ntargeting those APIs.\n\nInstall skills:",
      "language": "unknown"
    },
    {
      "code": "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](/tools/skills) and [ClawHub](/tools/clawhub).\n\n### How do I install the Chrome extension for browser takeover\n\nUse the built-in installer, then load the unpacked extension in Chrome:",
      "language": "unknown"
    },
    {
      "code": "Then Chrome → `chrome://extensions` → enable \"Developer mode\" → \"Load unpacked\" → pick that folder.\n\nFull guide (including remote Gateway + security notes): [Chrome extension](/tools/chrome-extension)\n\nIf the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need anything extra.\nIf the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions.\nYou still need to click the extension button on the tab you want to control (it doesn't auto-attach).\n\n## Sandboxing and memory\n\n### Is there a dedicated sandboxing doc\n\nYes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker).\n\n### Docker feels limited How do I enable full features\n\nThe default image is security-first and runs as the `node` user, so it does not\ninclude system packages, Homebrew, or bundled browsers. For a fuller setup:\n\n* Persist `/home/node` with `OPENCLAW_HOME_VOLUME` so caches survive.\n* Bake system deps into the image with `OPENCLAW_DOCKER_APT_PACKAGES`.\n* Install Playwright browsers via the bundled CLI:\n  `node /app/node_modules/playwright-core/cli.js install chromium`\n* Set `PLAYWRIGHT_BROWSERS_PATH` and ensure the path is persisted.\n\nDocs: [Docker](/install/docker), [Browser](/tools/browser).\n\n**Can I keep DMs personal but make groups public sandboxed with one agent**\n\nYes - if your private traffic is **DMs** and your public traffic is **groups**.\n\nUse `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`.\n\nSetup walkthrough + example config: [Groups: personal DMs + public groups](/concepts/groups#pattern-personal-dms-public-groups-single-agent)\n\nKey config reference: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox)\n\n### How do I bind a host folder into the sandbox\n\nSet `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](/gateway/sandboxing#custom-bind-mounts) and [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) for examples and safety notes.\n\n### How does memory work\n\nOpenClaw memory is just Markdown files in the agent workspace:\n\n* Daily notes in `memory/YYYY-MM-DD.md`\n* Curated long-term notes in `MEMORY.md` (main/private sessions only)\n\nOpenClaw also runs a **silent pre-compaction memory flush** to remind the model\nto write durable notes before auto-compaction. This only runs when the workspace\nis writable (read-only sandboxes skip it). See [Memory](/concepts/memory).\n\n### Memory keeps forgetting things How do I make it stick\n\nAsk the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`,\nshort-term context goes into `memory/YYYY-MM-DD.md`.\n\nThis is still an area we are improving. It helps to remind the model to store memories;\nit will know what to do. If it keeps forgetting, verify the Gateway is using the same\nworkspace on every run.\n\nDocs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace).\n\n### Does semantic memory search require an OpenAI API key\n\nOnly if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and\ndoes **not** grant embeddings access, so **signing in with Codex (OAuth or the\nCodex CLI login)** does not help for semantic memory search. OpenAI embeddings\nstill need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`).\n\nIf you don't set a provider explicitly, OpenClaw auto-selects a provider when it\ncan resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars).\nIt prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key\nresolves. If neither key is available, memory search stays disabled until you\nconfigure it. If you have a local model path configured and present, OpenClaw\nprefers `local`.\n\nIf you'd rather stay local, set `memorySearch.provider = \"local\"` (and optionally\n`memorySearch.fallback = \"none\"`). If you want Gemini embeddings, set\n`memorySearch.provider = \"gemini\"` and provide `GEMINI_API_KEY` (or\n`memorySearch.remote.apiKey`). We support **OpenAI, Gemini, or local** embedding\nmodels - see [Memory](/concepts/memory) for the setup details.\n\n### Does memory persist forever What are the limits\n\nMemory files live on disk and persist until you delete them. The limit is your\nstorage, not the model. The **session context** is still limited by the model\ncontext window, so long conversations can compact or truncate. That is why\nmemory search exists - it pulls only the relevant parts back into context.\n\nDocs: [Memory](/concepts/memory), [Context](/concepts/context).\n\n## Where things live on disk\n\n### Is all data used with OpenClaw saved locally\n\nNo - **OpenClaw's state is local**, but **external services still see what you send them**.\n\n* **Local by default:** sessions, memory files, config, and workspace live on the Gateway host\n  (`~/.openclaw` + your workspace directory).\n* **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to\n  their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their\n  servers.\n* **You control the footprint:** using local models keeps prompts on your machine, but channel\n  traffic still goes through the channel's servers.\n\nRelated: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory).\n\n### Where does OpenClaw store its data\n\nEverything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`):\n\n| Path                                                            | Purpose                                                      |\n| --------------------------------------------------------------- | ------------------------------------------------------------ |\n| `$OPENCLAW_STATE_DIR/openclaw.json`                             | Main config (JSON5)                                          |\n| `$OPENCLAW_STATE_DIR/credentials/oauth.json`                    | Legacy OAuth import (copied into auth profiles on first use) |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json` | Auth profiles (OAuth + API keys)                             |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json`          | Runtime auth cache (managed automatically)                   |\n| `$OPENCLAW_STATE_DIR/credentials/`                              | Provider state (e.g. `whatsapp/<accountId>/creds.json`)      |\n| `$OPENCLAW_STATE_DIR/agents/`                                   | Per-agent state (agentDir + sessions)                        |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`                | Conversation history & state (per agent)                     |\n| `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json`   | Session metadata (per agent)                                 |\n\nLegacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`).\n\nYour **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/.openclaw/workspace`).\n\n### Where should AGENTSmd SOULmd USERmd MEMORYmd live\n\nThese files live in the **agent workspace**, not `~/.openclaw`.\n\n* **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`,\n  `MEMORY.md` (or `memory.md`), `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`.\n* **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs,\n  and shared skills (`~/.openclaw/skills`).\n\nDefault workspace is `~/.openclaw/workspace`, configurable via:",
      "language": "unknown"
    },
    {
      "code": "If the bot \"forgets\" after a restart, confirm the Gateway is using the same\nworkspace on every launch (and remember: remote mode uses the **gateway host's**\nworkspace, not your local laptop).\n\nTip: if you want a durable behavior or preference, ask the bot to **write it into\nAGENTS.md or MEMORY.md** rather than relying on chat history.\n\nSee [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).\n\n### What's the recommended backup strategy\n\nPut your **agent workspace** in a **private** git repo and back it up somewhere\nprivate (for example GitHub private). This captures memory + AGENTS/SOUL/USER\nfiles, and lets you restore the assistant's \"mind\" later.\n\nDo **not** commit anything under `~/.openclaw` (credentials, sessions, tokens).\nIf you need a full restore, back up both the workspace and the state directory\nseparately (see the migration question above).\n\nDocs: [Agent workspace](/concepts/agent-workspace).\n\n### How do I completely uninstall OpenClaw\n\nSee the dedicated guide: [Uninstall](/install/uninstall).\n\n### Can agents work outside the workspace\n\nYes. The workspace is the **default cwd** and memory anchor, not a hard sandbox.\nRelative paths resolve inside the workspace, but absolute paths can access other\nhost locations unless sandboxing is enabled. If you need isolation, use\n[`agents.defaults.sandbox`](/gateway/sandboxing) or per-agent sandbox settings. If you\nwant a repo to be the default working directory, point that agent's\n`workspace` to the repo root. The OpenClaw repo is just source code; keep the\nworkspace separate unless you intentionally want the agent to work inside it.\n\nExample (repo as default cwd):",
      "language": "unknown"
    },
    {
      "code": "### Im in remote mode where is the session store\n\nSession state is owned by the **gateway host**. If you're in remote mode, the session store you care about is on the remote machine, not your local laptop. See [Session management](/concepts/session).\n\n## Config basics\n\n### What format is the config Where is it\n\nOpenClaw reads an optional **JSON5** config from `$OPENCLAW_CONFIG_PATH` (default: `~/.openclaw/openclaw.json`):",
      "language": "unknown"
    },
    {
      "code": "If the file is missing, it uses safe-ish defaults (including a default workspace of `~/.openclaw/workspace`).\n\n### I set gatewaybind lan or tailnet and now nothing listens the UI says unauthorized\n\nNon-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`).",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* `gateway.remote.token` is for **remote CLI calls** only; it does not enable local gateway auth.\n* The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs.\n\n### Why do I need a token on localhost now\n\nThe wizard generates a gateway token by default (even on loopback) so **local WS clients must authenticate**. This blocks other local processes from calling the Gateway. Paste the token into the Control UI settings (or your client config) to connect.\n\nIf you **really** want open loopback, remove `gateway.auth` from your config. Doctor can generate a token for you any time: `openclaw doctor --generate-gateway-token`.\n\n### Do I have to restart after changing config\n\nThe Gateway watches the config and supports hot-reload:\n\n* `gateway.reload.mode: \"hybrid\"` (default): hot-apply safe changes, restart for critical ones\n* `hot`, `restart`, `off` are also supported\n\n### How do I enable web search and web fetch\n\n`web_fetch` works without an API key. `web_search` requires a Brave Search API\nkey. **Recommended:** run `openclaw configure --section web` to store it in\n`tools.web.search.apiKey`. Environment alternative: set `BRAVE_API_KEY` for the\nGateway process.",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* If you use allowlists, add `web_search`/`web_fetch` or `group:web`.\n* `web_fetch` is enabled by default (unless explicitly disabled).\n* Daemons read env vars from `~/.openclaw/.env` (or the service environment).\n\nDocs: [Web tools](/tools/web).\n\n### How do I run a central Gateway with specialized workers across devices\n\nThe common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**:\n\n* **Gateway (central):** owns channels (Signal/WhatsApp), routing, and sessions.\n* **Nodes (devices):** Macs/iOS/Android connect as peripherals and expose local tools (`system.run`, `canvas`, `camera`).\n* **Agents (workers):** separate brains/workspaces for special roles (e.g. \"Hetzner ops\", \"Personal data\").\n* **Sub-agents:** spawn background work from a main agent when you want parallelism.\n* **TUI:** connect to the Gateway and switch agents/sessions.\n\nDocs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/tui).\n\n### Can the OpenClaw browser run headless\n\nYes. It's a config option:",
      "language": "unknown"
    },
    {
      "code": "Default is `false` (headful). Headless is more likely to trigger anti-bot checks on some sites. See [Browser](/tools/browser).\n\nHeadless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences:\n\n* No visible browser window (use screenshots if you need visuals).\n* Some sites are stricter about automation in headless mode (CAPTCHAs, anti-bot).\n  For example, X/Twitter often blocks headless sessions.\n\n### How do I use Brave for browser control\n\nSet `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway.\nSee the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser).\n\n## Remote gateways + nodes\n\n### How do commands propagate between Telegram the gateway and nodes\n\nTelegram messages are handled by the **gateway**. The gateway runs the agent and\nonly then calls nodes over the **Gateway WebSocket** when a node tool is needed:\n\nTelegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram\n\nNodes don't see inbound provider traffic; they only receive node RPC calls.\n\n### How can my agent access my computer if the Gateway is hosted remotely\n\nShort answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can\ncall `node.*` tools (screen, camera, system) on your local machine over the Gateway WebSocket.\n\nTypical setup:\n\n1. Run the Gateway on the always-on host (VPS/home server).\n2. Put the Gateway host + your computer on the same tailnet.\n3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).\n4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet)\n   so it can register as a node.\n5. Approve the node on the Gateway:",
      "language": "unknown"
    },
    {
      "code": "No separate TCP bridge is required; nodes connect over the Gateway WebSocket.\n\nSecurity reminder: pairing a macOS node allows `system.run` on that machine. Only\npair devices you trust, and review [Security](/gateway/security).\n\nDocs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security).\n\n### Tailscale is connected but I get no replies What now\n\nCheck the basics:\n\n* Gateway is running: `openclaw gateway status`\n* Gateway health: `openclaw status`\n* Channel health: `openclaw channels status`\n\nThen verify auth and routing:\n\n* If you use Tailscale Serve, make sure `gateway.auth.allowTailscale` is set correctly.\n* If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port.\n* Confirm your allowlists (DM or group) include your account.\n\nDocs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels).\n\n### Can two OpenClaw instances talk to each other local VPS\n\nYes. There is no built-in \"bot-to-bot\" bridge, but you can wire it up in a few\nreliable ways:\n\n**Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp).\nHave Bot A send a message to Bot B, then let Bot B reply as usual.\n\n**CLI bridge (generic):** run a script that calls the other Gateway with\n`openclaw agent --message ... --deliver`, targeting a chat where the other bot\nlistens. If one bot is on a remote VPS, point your CLI at that remote Gateway\nvia SSH/Tailscale (see [Remote access](/gateway/remote)).\n\nExample pattern (run from a machine that can reach the target Gateway):",
      "language": "unknown"
    },
    {
      "code": "Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel\nallowlists, or a \"do not reply to bot messages\" rule).\n\nDocs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send).\n\n### Do I need separate VPSes for multiple agents\n\nNo. One Gateway can host multiple agents, each with its own workspace, model defaults,\nand routing. That is the normal setup and it is much cheaper and simpler than running\none VPS per agent.\n\nUse separate VPSes only when you need hard isolation (security boundaries) or very\ndifferent configs that you do not want to share. Otherwise, keep one Gateway and\nuse multiple agents or sub-agents.\n\n### Is there a benefit to using a node on my personal laptop instead of SSH from a VPS\n\nYes - nodes are the first-class way to reach your laptop from a remote Gateway, and they\nunlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is\nlightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common\nsetup is an always-on host plus your laptop as a node.\n\n* **No inbound SSH required.** Nodes connect out to the Gateway WebSocket and use device pairing.\n* **Safer execution controls.** `system.run` is gated by node allowlists/approvals on that laptop.\n* **More device tools.** Nodes expose `canvas`, `camera`, and `screen` in addition to `system.run`.\n* **Local browser automation.** Keep the Gateway on a VPS, but run Chrome locally and relay control\n  with the Chrome extension + a node host on the laptop.\n\nSSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and\ndevice automation.\n\nDocs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Chrome extension](/tools/chrome-extension).\n\n### Should I install on a second laptop or just add a node\n\nIf you only need **local tools** (screen/camera/exec) on the second laptop, add it as a\n**node**. That keeps a single Gateway and avoids duplicated config. Local node tools are\ncurrently macOS-only, but we plan to extend them to other OSes.\n\nInstall a second Gateway only when you need **hard isolation** or two fully separate bots.\n\nDocs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways).\n\n### Do nodes run a gateway service\n\nNo. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect\nto the gateway (iOS/Android nodes, or macOS \"node mode\" in the menubar app). For headless node\nhosts and CLI control, see [Node host CLI](/cli/node).\n\nA full restart is required for `gateway`, `discovery`, and `canvasHost` changes.\n\n### Is there an API RPC way to apply config\n\nYes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation.\n\n### configapply wiped my config How do I recover and avoid this\n\n`config.apply` replaces the **entire config**. If you send a partial object, everything\nelse is removed.\n\nRecover:\n\n* Restore from backup (git or a copied `~/.openclaw/openclaw.json`).\n* If you have no backup, re-run `openclaw doctor` and reconfigure channels/models.\n* If this was unexpected, file a bug and include your last known config or any backup.\n* A local coding agent can often reconstruct a working config from logs or history.\n\nAvoid it:\n\n* Use `openclaw config set` for small changes.\n* Use `openclaw configure` for interactive edits.\n\nDocs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor).\n\n### What's a minimal sane config for a first install",
      "language": "unknown"
    },
    {
      "code": "This sets your workspace and restricts who can trigger the bot.\n\n### How do I set up Tailscale on a VPS and connect from my Mac\n\nMinimal steps:\n\n1. **Install + login on the VPS**",
      "language": "unknown"
    },
    {
      "code": "2. **Install + login on your Mac**\n   * Use the Tailscale app and sign in to the same tailnet.\n3. **Enable MagicDNS (recommended)**\n   * In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.\n4. **Use the tailnet hostname**\n   * SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`\n   * Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`\n\nIf you want the Control UI without SSH, use Tailscale Serve on the VPS:",
      "language": "unknown"
    },
    {
      "code": "This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale).\n\n### How do I connect a Mac node to a remote Gateway Tailscale Serve\n\nServe exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint.\n\nRecommended setup:\n\n1. **Make sure the VPS + Mac are on the same tailnet**.\n2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).\n   The app will tunnel the Gateway port and connect as a node.\n3. **Approve the node** on the gateway:",
      "language": "unknown"
    },
    {
      "code": "Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote).\n\n## Env vars and .env loading\n\n### How does OpenClaw load environment variables\n\nOpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:\n\n* `.env` from the current working directory\n* a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`)\n\nNeither `.env` file overrides existing env vars.\n\nYou can also define inline env vars in config (applied only if missing from the process env):",
      "language": "unknown"
    },
    {
      "code": "See [/environment](/environment) for full precedence and sources.\n\n### I started the Gateway via the service and my env vars disappeared What now\n\nTwo common fixes:\n\n1. Put the missing keys in `~/.openclaw/.env` so they're picked up even when the service doesn't inherit your shell env.\n2. Enable shell import (opt-in convenience):",
      "language": "unknown"
    },
    {
      "code": "This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:\n`OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`.\n\n### I set COPILOTGITHUBTOKEN but models status shows Shell env off Why\n\n`openclaw models status` reports whether **shell env import** is enabled. \"Shell env: off\"\ndoes **not** mean your env vars are missing - it just means OpenClaw won't load\nyour login shell automatically.\n\nIf the Gateway runs as a service (launchd/systemd), it won't inherit your shell\nenvironment. Fix by doing one of these:\n\n1. Put the token in `~/.openclaw/.env`:",
      "language": "unknown"
    },
    {
      "code": "2. Or enable shell import (`env.shellEnv.enabled: true`).\n3. Or add it to your config `env` block (applies only if missing).\n\nThen restart the gateway and recheck:",
      "language": "unknown"
    },
    {
      "code": "Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).\nSee [/concepts/model-providers](/concepts/model-providers) and [/environment](/environment).\n\n## Sessions & multiple chats\n\n### How do I start a fresh conversation\n\nSend `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).\n\n### Do sessions reset automatically if I never send new\n\nYes. Sessions expire after `session.idleMinutes` (default **60**). The **next**\nmessage starts a fresh session id for that chat key. This does not delete\ntranscripts - it just starts a new session.",
      "language": "unknown"
    },
    {
      "code": "### Is there a way to make a team of OpenClaw instances one CEO and many agents\n\nYes, via **multi-agent routing** and **sub-agents**. You can create one coordinator\nagent and several worker agents with their own workspaces and models.\n\nThat said, this is best seen as a **fun experiment**. It is token heavy and often\nless efficient than using one bot with separate sessions. The typical model we\nenvision is one bot you talk to, with different sessions for parallel work. That\nbot can also spawn sub-agents when needed.\n\nDocs: [Multi-agent routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [Agents CLI](/cli/agents).\n\n### Why did context get truncated midtask How do I prevent it\n\nSession context is limited by the model window. Long chats, large tool outputs, or many\nfiles can trigger compaction or truncation.\n\nWhat helps:\n\n* Ask the bot to summarize the current state and write it to a file.\n* Use `/compact` before long tasks, and `/new` when switching topics.\n* Keep important context in the workspace and ask the bot to read it back.\n* Use sub-agents for long or parallel work so the main chat stays smaller.\n* Pick a model with a larger context window if this happens often.\n\n### How do I completely reset OpenClaw but keep it installed\n\nUse the reset command:",
      "language": "unknown"
    },
    {
      "code": "Non-interactive full reset:",
      "language": "unknown"
    },
    {
      "code": "Then re-run onboarding:",
      "language": "unknown"
    },
    {
      "code": "Notes:\n\n* The onboarding wizard also offers **Reset** if it sees an existing config. See [Wizard](/start/wizard).\n* If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-<profile>`).\n* Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).\n\n### Im getting context too large errors how do I reset or compact\n\nUse one of these:\n\n* **Compact** (keeps the conversation but summarizes older turns):",
      "language": "unknown"
    },
    {
      "code": "or `/compact <instructions>` to guide the summary.\n\n* **Reset** (fresh session ID for the same chat key):",
      "language": "unknown"
    },
    {
      "code": "If it keeps happening:\n\n* Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output.\n* Use a model with a larger context window.\n\nDocs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session).\n\n### Why am I seeing LLM request rejected messagesNcontentXtooluseinput Field required\n\nThis is a provider validation error: the model emitted a `tool_use` block without the required\n`input`. It usually means the session history is stale or corrupted (often after long threads\nor a tool/schema change).\n\nFix: start a fresh session with `/new` (standalone message).\n\n### Why am I getting heartbeat messages every 30 minutes\n\nHeartbeats run every **30m** by default. Tune or disable them:",
      "language": "unknown"
    },
    {
      "code": "If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown\nheaders like `# Heading`), OpenClaw skips the heartbeat run to save API calls.\nIf the file is missing, the heartbeat still runs and the model decides what to do.\n\nPer-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat).\n\n### Do I need to add a bot account to a WhatsApp group\n\nNo. OpenClaw runs on **your own account**, so if you're in the group, OpenClaw can see it.\nBy default, group replies are blocked until you allow senders (`groupPolicy: \"allowlist\"`).\n\nIf you want only **you** to be able to trigger group replies:",
      "language": "unknown"
    },
    {
      "code": "### How do I get the JID of a WhatsApp group\n\nOption 1 (fastest): tail logs and send a test message in the group:",
      "language": "unknown"
    },
    {
      "code": "Look for `chatId` (or `from`) ending in `@g.us`, like:\n`1234567890-1234567890@g.us`.\n\nOption 2 (if already configured/allowlisted): list groups from config:",
      "language": "unknown"
    },
    {
      "code": "Docs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs).\n\n### Why doesnt OpenClaw reply in a group\n\nTwo common causes:\n\n* Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).\n* You configured `channels.whatsapp.groups` without `\"*\"` and the group isn't allowlisted.\n\nSee [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).\n\n### Do groupsthreads share context with DMs\n\nDirect chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages).\n\n### How many workspaces and agents can I create\n\nNo hard limits. Dozens (even hundreds) are fine, but watch for:\n\n* **Disk growth:** sessions + transcripts live under `~/.openclaw/agents/<agentId>/sessions/`.\n* **Token cost:** more agents means more concurrent model usage.\n* **Ops overhead:** per-agent auth profiles, workspaces, and channel routing.\n\nTips:\n\n* Keep one **active** workspace per agent (`agents.defaults.workspace`).\n* Prune old sessions (delete JSONL or store entries) if disk grows.\n* Use `openclaw doctor` to spot stray workspaces and profile mismatches.\n\n### Can I run multiple bots or chats at the same time Slack and how should I set that up\n\nYes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbound messages by\nchannel/account/peer. Slack is supported as a channel and can be bound to specific agents.\n\nBrowser access is powerful but not \"do anything a human can\" - anti-bot, CAPTCHAs, and MFA can\nstill block automation. For the most reliable browser control, use the Chrome extension relay\non the machine that runs the browser (and keep the Gateway anywhere).\n\nBest-practice setup:\n\n* Always-on Gateway host (VPS/Mac mini).\n* One agent per role (bindings).\n* Slack channel(s) bound to those agents.\n* Local browser via extension relay (or a node) when needed.\n\nDocs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack),\n[Browser](/tools/browser), [Chrome extension](/tools/chrome-extension), [Nodes](/nodes).\n\n## Models: defaults, selection, aliases, switching\n\n### What is the default model\n\nOpenClaw's default model is whatever you set as:",
      "language": "unknown"
    },
    {
      "code": "Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-5`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`.\n\n### What model do you recommend\n\n**Recommended default:** `anthropic/claude-opus-4-5`.\n**Good alternative:** `anthropic/claude-sonnet-4-5`.\n**Reliable (less character):** `openai/gpt-5.2` - nearly as good as Opus, just less personality.\n**Budget:** `zai/glm-4.7`.\n\nMiniMax M2.1 has its own docs: [MiniMax](/providers/minimax) and\n[Local models](/gateway/local-models).\n\nRule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper\nmodel for routine chat or summaries. You can route models per agent and use sub-agents to\nparallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and\n[Sub-agents](/tools/subagents).\n\nStrong warning: weaker/over-quantized models are more vulnerable to prompt\ninjection and unsafe behavior. See [Security](/gateway/security).\n\nMore context: [Models](/concepts/models).\n\n### Can I use selfhosted models llamacpp vLLM Ollama\n\nYes. If your local server exposes an OpenAI-compatible API, you can point a\ncustom provider at it. Ollama is supported directly and is the easiest path.\n\nSecurity note: smaller or heavily quantized models are more vulnerable to prompt\ninjection. We strongly recommend **large models** for any bot that can use tools.\nIf you still want small models, enable sandboxing and strict tool allowlists.\n\nDocs: [Ollama](/providers/ollama), [Local models](/gateway/local-models),\n[Model providers](/concepts/model-providers), [Security](/gateway/security),\n[Sandboxing](/gateway/sandboxing).\n\n### How do I switch models without wiping my config\n\nUse **model commands** or edit only the **model** fields. Avoid full config replaces.\n\nSafe options:\n\n* `/model` in chat (quick, per-session)\n* `openclaw models set ...` (updates just model config)\n* `openclaw configure --section models` (interactive)\n* edit `agents.defaults.model` in `~/.openclaw/openclaw.json`\n\nAvoid `config.apply` with a partial object unless you intend to replace the whole config.\nIf you did overwrite config, restore from backup or re-run `openclaw doctor` to repair.\n\nDocs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor).\n\n### What do OpenClaw, Flawd, and Krill use for models\n\n* **OpenClaw + Flawd:** Anthropic Opus (`anthropic/claude-opus-4-5`) - see [Anthropic](/providers/anthropic).\n* **Krill:** MiniMax M2.1 (`minimax/MiniMax-M2.1`) - see [MiniMax](/providers/minimax).\n\n### How do I switch models on the fly without restarting\n\nUse the `/model` command as a standalone message:",
      "language": "unknown"
    },
    {
      "code": "You can list available models with `/model`, `/model list`, or `/model status`.\n\n`/model` (and `/model list`) shows a compact, numbered picker. Select by number:",
      "language": "unknown"
    },
    {
      "code": "You can also force a specific auth profile for the provider (per session):",
      "language": "unknown"
    },
    {
      "code": "Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.\nIt also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available.\n\n**How do I unpin a profile I set with profile**\n\nRe-run `/model` **without** the `@profile` suffix:",
      "language": "unknown"
    },
    {
      "code": "If you want to return to the default, pick it from `/model` (or send `/model <default provider/model>`).\nUse `/model status` to confirm which auth profile is active.\n\n### Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding\n\nYes. Set one as default and switch as needed:\n\n* **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model gpt-5.2-codex` for coding.\n* **Default + switch:** set `agents.defaults.model.primary` to `openai-codex/gpt-5.2`, then switch to `openai-codex/gpt-5.2-codex` when coding (or the other way around).\n* **Sub-agents:** route coding tasks to sub-agents with a different default model.\n\nSee [Models](/concepts/models) and [Slash commands](/tools/slash-commands).\n\n### Why do I see Model is not allowed and then no reply\n\nIf `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any\nsession overrides. Choosing a model that isn't in that list returns:",
      "language": "unknown"
    },
    {
      "code": "That error is returned **instead of** a normal reply. Fix: add the model to\n`agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.\n\n### Why do I see Unknown model minimaxMiniMaxM21\n\nThis means the **provider isn't configured** (no MiniMax provider config or auth\nprofile was found), so the model can't be resolved. A fix for this detection is\nin **2026.1.12** (unreleased at the time of writing).\n\nFix checklist:\n\n1. Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway.\n2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key\n   exists in env/auth profiles so the provider can be injected.\n3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.1` or\n   `minimax/MiniMax-M2.1-lightning`.\n4. Run:",
      "language": "unknown"
    },
    {
      "code": "and pick from the list (or `/model list` in chat).\n\nSee [MiniMax](/providers/minimax) and [Models](/concepts/models).\n\n### Can I use MiniMax as my default and OpenAI for complex tasks\n\nYes. Use **MiniMax as the default** and switch models **per session** when needed.\nFallbacks are for **errors**, not \"hard tasks,\" so use `/model` or a separate agent.\n\n**Option A: switch per session**",
      "language": "unknown"
    },
    {
      "code": "Then:",
      "language": "unknown"
    },
    {
      "code": "**Option B: separate agents**\n\n* Agent A default: MiniMax\n* Agent B default: OpenAI\n* Route by agent or use `/agent` to switch\n\nDocs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).\n\n### Are opus sonnet gpt builtin shortcuts\n\nYes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):\n\n* `opus` → `anthropic/claude-opus-4-5`\n* `sonnet` → `anthropic/claude-sonnet-4-5`\n* `gpt` → `openai/gpt-5.2`\n* `gpt-mini` → `openai/gpt-5-mini`\n* `gemini` → `google/gemini-3-pro-preview`\n* `gemini-flash` → `google/gemini-3-flash-preview`\n\nIf you set your own alias with the same name, your value wins.\n\n### How do I defineoverride model shortcuts aliases\n\nAliases come from `agents.defaults.models.<modelId>.alias`. Example:",
      "language": "unknown"
    },
    {
      "code": "Then `/model sonnet` (or `/<alias>` when supported) resolves to that model ID.\n\n### How do I add models from other providers like OpenRouter or ZAI\n\nOpenRouter (pay-per-token; many models):",
      "language": "unknown"
    },
    {
      "code": "Z.AI (GLM models):",
      "language": "unknown"
    },
    {
      "code": "If you reference a provider/model but the required provider key is missing, you'll get a runtime auth error (e.g. `No API key found for provider \"zai\"`).\n\n**No API key found for provider after adding a new agent**\n\nThis usually means the **new agent** has an empty auth store. Auth is per-agent and\nstored in:",
      "language": "unknown"
    },
    {
      "code": "Fix options:\n\n* Run `openclaw agents add <id>` and configure auth during the wizard.\n* Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`.\n\nDo **not** reuse `agentDir` across agents; it causes auth/session collisions.\n\n## Model failover and \"All models failed\"\n\n### How does failover work\n\nFailover happens in two stages:\n\n1. **Auth profile rotation** within the same provider.\n2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`.\n\nCooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing.\n\n### What does this error mean",
      "language": "unknown"
    },
    {
      "code": "It means the system attempted to use the auth profile ID `anthropic:default`, but could not find credentials for it in the expected auth store.\n\n### Fix checklist for No credentials found for profile anthropicdefault\n\n* **Confirm where auth profiles live** (new vs legacy paths)\n  * Current: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`\n  * Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`)\n* **Confirm your env var is loaded by the Gateway**\n  * If you set `ANTHROPIC_API_KEY` in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in `~/.openclaw/.env` or enable `env.shellEnv`.\n* **Make sure you're editing the correct agent**\n  * Multi-agent setups mean there can be multiple `auth-profiles.json` files.\n* **Sanity-check model/auth status**\n  * Use `openclaw models status` to see configured models and whether providers are authenticated.\n\n**Fix checklist for No credentials found for profile anthropic**\n\nThis means the run is pinned to an Anthropic auth profile, but the Gateway\ncan't find it in its auth store.\n\n* **Use a setup-token**\n  * Run `claude setup-token`, then paste it with `openclaw models auth setup-token --provider anthropic`.\n  * If the token was created on another machine, use `openclaw models auth paste-token --provider anthropic`.\n* **If you want to use an API key instead**\n  * Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.\n  * Clear any pinned order that forces a missing profile:",
      "language": "unknown"
    },
    {
      "code": "* **Confirm you're running commands on the gateway host**\n  * In remote mode, auth profiles live on the gateway machine, not your laptop.\n\n### Why did it also try Google Gemini and fail\n\nIf your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw will try it during model fallback. If you haven't configured Google credentials, you'll see `No API key found for provider \"google\"`.\n\nFix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there.\n\n**LLM request rejected message thinking signature required google antigravity**\n\nCause: the session history contains **thinking blocks without signatures** (often from\nan aborted/partial stream). Google Antigravity requires signatures for thinking blocks.\n\nFix: OpenClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a **new session** or set `/thinking off` for that agent.\n\n## Auth profiles: what they are and how to manage them\n\nRelated: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns)\n\n### What is an auth profile\n\nAn auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:",
      "language": "unknown"
    },
    {
      "code": "### What are typical profile IDs\n\nOpenClaw uses provider-prefixed IDs like:\n\n* `anthropic:default` (common when no email identity exists)\n* `anthropic:<email>` for OAuth identities\n* custom IDs you choose (e.g. `anthropic:work`)\n\n### Can I control which auth profile is tried first\n\nYes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.<provider>`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.\n\nOpenClaw may temporarily skip a profile if it's in a short **cooldown** (rate limits/timeouts/auth failures) or a longer **disabled** state (billing/insufficient credits). To inspect this, run `openclaw models status --json` and check `auth.unusableProfiles`. Tuning: `auth.cooldowns.billingBackoffHours*`.\n\nYou can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Table of contents",
      "id": "table-of-contents"
    },
    {
      "level": "h2",
      "text": "First 60 seconds if something's broken",
      "id": "first-60-seconds-if-something's-broken"
    },
    {
      "level": "h2",
      "text": "Quick start and first-run setup",
      "id": "quick-start-and-first-run-setup"
    },
    {
      "level": "h3",
      "text": "Im stuck whats the fastest way to get unstuck",
      "id": "im-stuck-whats-the-fastest-way-to-get-unstuck"
    },
    {
      "level": "h3",
      "text": "What's the recommended way to install and set up OpenClaw",
      "id": "what's-the-recommended-way-to-install-and-set-up-openclaw"
    },
    {
      "level": "h3",
      "text": "How do I open the dashboard after onboarding",
      "id": "how-do-i-open-the-dashboard-after-onboarding"
    },
    {
      "level": "h3",
      "text": "How do I authenticate the dashboard token on localhost vs remote",
      "id": "how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote"
    },
    {
      "level": "h3",
      "text": "What runtime do I need",
      "id": "what-runtime-do-i-need"
    },
    {
      "level": "h3",
      "text": "Does it run on Raspberry Pi",
      "id": "does-it-run-on-raspberry-pi"
    },
    {
      "level": "h3",
      "text": "Any tips for Raspberry Pi installs",
      "id": "any-tips-for-raspberry-pi-installs"
    },
    {
      "level": "h3",
      "text": "It is stuck on wake up my friend onboarding will not hatch What now",
      "id": "it-is-stuck-on-wake-up-my-friend-onboarding-will-not-hatch-what-now"
    },
    {
      "level": "h3",
      "text": "Can I migrate my setup to a new machine Mac mini without redoing onboarding",
      "id": "can-i-migrate-my-setup-to-a-new-machine-mac-mini-without-redoing-onboarding"
    },
    {
      "level": "h3",
      "text": "Where do I see what is new in the latest version",
      "id": "where-do-i-see-what-is-new-in-the-latest-version"
    },
    {
      "level": "h3",
      "text": "I cant access docs.openclaw\\.ai SSL error What now",
      "id": "i-cant-access-docs.openclaw\\.ai-ssl-error-what-now"
    },
    {
      "level": "h3",
      "text": "What's the difference between stable and beta",
      "id": "what's-the-difference-between-stable-and-beta"
    },
    {
      "level": "h3",
      "text": "How do I install the beta version and whats the difference between beta and dev",
      "id": "how-do-i-install-the-beta-version-and-whats-the-difference-between-beta-and-dev"
    },
    {
      "level": "h3",
      "text": "How long does install and onboarding usually take",
      "id": "how-long-does-install-and-onboarding-usually-take"
    },
    {
      "level": "h3",
      "text": "How do I try the latest bits",
      "id": "how-do-i-try-the-latest-bits"
    },
    {
      "level": "h3",
      "text": "Installer stuck How do I get more feedback",
      "id": "installer-stuck-how-do-i-get-more-feedback"
    },
    {
      "level": "h3",
      "text": "Windows install says git not found or openclaw not recognized",
      "id": "windows-install-says-git-not-found-or-openclaw-not-recognized"
    },
    {
      "level": "h3",
      "text": "The docs didnt answer my question how do I get a better answer",
      "id": "the-docs-didnt-answer-my-question-how-do-i-get-a-better-answer"
    },
    {
      "level": "h3",
      "text": "How do I install OpenClaw on Linux",
      "id": "how-do-i-install-openclaw-on-linux"
    },
    {
      "level": "h3",
      "text": "How do I install OpenClaw on a VPS",
      "id": "how-do-i-install-openclaw-on-a-vps"
    },
    {
      "level": "h3",
      "text": "Where are the cloudVPS install guides",
      "id": "where-are-the-cloudvps-install-guides"
    },
    {
      "level": "h3",
      "text": "Can I ask OpenClaw to update itself",
      "id": "can-i-ask-openclaw-to-update-itself"
    },
    {
      "level": "h3",
      "text": "What does the onboarding wizard actually do",
      "id": "what-does-the-onboarding-wizard-actually-do"
    },
    {
      "level": "h3",
      "text": "Do I need a Claude or OpenAI subscription to run this",
      "id": "do-i-need-a-claude-or-openai-subscription-to-run-this"
    },
    {
      "level": "h3",
      "text": "Can I use Claude Max subscription without an API key",
      "id": "can-i-use-claude-max-subscription-without-an-api-key"
    },
    {
      "level": "h3",
      "text": "How does Anthropic setuptoken auth work",
      "id": "how-does-anthropic-setuptoken-auth-work"
    },
    {
      "level": "h3",
      "text": "Where do I find an Anthropic setuptoken",
      "id": "where-do-i-find-an-anthropic-setuptoken"
    },
    {
      "level": "h3",
      "text": "Do you support Claude subscription auth (Claude Pro/Max)",
      "id": "do-you-support-claude-subscription-auth-(claude-pro/max)"
    },
    {
      "level": "h3",
      "text": "Why am I seeing HTTP 429 ratelimiterror from Anthropic",
      "id": "why-am-i-seeing-http-429-ratelimiterror-from-anthropic"
    },
    {
      "level": "h3",
      "text": "Is AWS Bedrock supported",
      "id": "is-aws-bedrock-supported"
    },
    {
      "level": "h3",
      "text": "How does Codex auth work",
      "id": "how-does-codex-auth-work"
    },
    {
      "level": "h3",
      "text": "Do you support OpenAI subscription auth Codex OAuth",
      "id": "do-you-support-openai-subscription-auth-codex-oauth"
    },
    {
      "level": "h3",
      "text": "How do I set up Gemini CLI OAuth",
      "id": "how-do-i-set-up-gemini-cli-oauth"
    },
    {
      "level": "h3",
      "text": "Is a local model OK for casual chats",
      "id": "is-a-local-model-ok-for-casual-chats"
    },
    {
      "level": "h3",
      "text": "How do I keep hosted model traffic in a specific region",
      "id": "how-do-i-keep-hosted-model-traffic-in-a-specific-region"
    },
    {
      "level": "h3",
      "text": "Do I have to buy a Mac Mini to install this",
      "id": "do-i-have-to-buy-a-mac-mini-to-install-this"
    },
    {
      "level": "h3",
      "text": "Do I need a Mac mini for iMessage support",
      "id": "do-i-need-a-mac-mini-for-imessage-support"
    },
    {
      "level": "h3",
      "text": "If I buy a Mac mini to run OpenClaw can I connect it to my MacBook Pro",
      "id": "if-i-buy-a-mac-mini-to-run-openclaw-can-i-connect-it-to-my-macbook-pro"
    },
    {
      "level": "h3",
      "text": "Can I use Bun",
      "id": "can-i-use-bun"
    },
    {
      "level": "h3",
      "text": "Telegram what goes in allowFrom",
      "id": "telegram-what-goes-in-allowfrom"
    },
    {
      "level": "h3",
      "text": "Can multiple people use one WhatsApp number with different OpenClaw instances",
      "id": "can-multiple-people-use-one-whatsapp-number-with-different-openclaw-instances"
    },
    {
      "level": "h3",
      "text": "Can I run a fast chat agent and an Opus for coding agent",
      "id": "can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent"
    },
    {
      "level": "h3",
      "text": "Does Homebrew work on Linux",
      "id": "does-homebrew-work-on-linux"
    },
    {
      "level": "h3",
      "text": "What's the difference between the hackable git install and npm install",
      "id": "what's-the-difference-between-the-hackable-git-install-and-npm-install"
    },
    {
      "level": "h3",
      "text": "Can I switch between npm and git installs later",
      "id": "can-i-switch-between-npm-and-git-installs-later"
    },
    {
      "level": "h3",
      "text": "Should I run the Gateway on my laptop or a VPS",
      "id": "should-i-run-the-gateway-on-my-laptop-or-a-vps"
    },
    {
      "level": "h3",
      "text": "How important is it to run OpenClaw on a dedicated machine",
      "id": "how-important-is-it-to-run-openclaw-on-a-dedicated-machine"
    },
    {
      "level": "h3",
      "text": "What are the minimum VPS requirements and recommended OS",
      "id": "what-are-the-minimum-vps-requirements-and-recommended-os"
    },
    {
      "level": "h3",
      "text": "Can I run OpenClaw in a VM and what are the requirements",
      "id": "can-i-run-openclaw-in-a-vm-and-what-are-the-requirements"
    },
    {
      "level": "h2",
      "text": "What is OpenClaw?",
      "id": "what-is-openclaw?"
    },
    {
      "level": "h3",
      "text": "What is OpenClaw in one paragraph",
      "id": "what-is-openclaw-in-one-paragraph"
    },
    {
      "level": "h3",
      "text": "What's the value proposition",
      "id": "what's-the-value-proposition"
    },
    {
      "level": "h3",
      "text": "I just set it up what should I do first",
      "id": "i-just-set-it-up-what-should-i-do-first"
    },
    {
      "level": "h3",
      "text": "What are the top five everyday use cases for OpenClaw",
      "id": "what-are-the-top-five-everyday-use-cases-for-openclaw"
    },
    {
      "level": "h3",
      "text": "Can OpenClaw help with lead gen outreach ads and blogs for a SaaS",
      "id": "can-openclaw-help-with-lead-gen-outreach-ads-and-blogs-for-a-saas"
    },
    {
      "level": "h3",
      "text": "What are the advantages vs Claude Code for web development",
      "id": "what-are-the-advantages-vs-claude-code-for-web-development"
    },
    {
      "level": "h2",
      "text": "Skills and automation",
      "id": "skills-and-automation"
    },
    {
      "level": "h3",
      "text": "How do I customize skills without keeping the repo dirty",
      "id": "how-do-i-customize-skills-without-keeping-the-repo-dirty"
    },
    {
      "level": "h3",
      "text": "Can I load skills from a custom folder",
      "id": "can-i-load-skills-from-a-custom-folder"
    },
    {
      "level": "h3",
      "text": "How can I use different models for different tasks",
      "id": "how-can-i-use-different-models-for-different-tasks"
    },
    {
      "level": "h3",
      "text": "The bot freezes while doing heavy work How do I offload that",
      "id": "the-bot-freezes-while-doing-heavy-work-how-do-i-offload-that"
    },
    {
      "level": "h3",
      "text": "Cron or reminders do not fire What should I check",
      "id": "cron-or-reminders-do-not-fire-what-should-i-check"
    },
    {
      "level": "h3",
      "text": "How do I install skills on Linux",
      "id": "how-do-i-install-skills-on-linux"
    },
    {
      "level": "h3",
      "text": "Can OpenClaw run tasks on a schedule or continuously in the background",
      "id": "can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background"
    },
    {
      "level": "h3",
      "text": "Do you have a Notion or HeyGen integration",
      "id": "do-you-have-a-notion-or-heygen-integration"
    },
    {
      "level": "h3",
      "text": "How do I install the Chrome extension for browser takeover",
      "id": "how-do-i-install-the-chrome-extension-for-browser-takeover"
    },
    {
      "level": "h2",
      "text": "Sandboxing and memory",
      "id": "sandboxing-and-memory"
    },
    {
      "level": "h3",
      "text": "Is there a dedicated sandboxing doc",
      "id": "is-there-a-dedicated-sandboxing-doc"
    },
    {
      "level": "h3",
      "text": "Docker feels limited How do I enable full features",
      "id": "docker-feels-limited-how-do-i-enable-full-features"
    },
    {
      "level": "h3",
      "text": "How do I bind a host folder into the sandbox",
      "id": "how-do-i-bind-a-host-folder-into-the-sandbox"
    },
    {
      "level": "h3",
      "text": "How does memory work",
      "id": "how-does-memory-work"
    },
    {
      "level": "h3",
      "text": "Memory keeps forgetting things How do I make it stick",
      "id": "memory-keeps-forgetting-things-how-do-i-make-it-stick"
    },
    {
      "level": "h3",
      "text": "Does semantic memory search require an OpenAI API key",
      "id": "does-semantic-memory-search-require-an-openai-api-key"
    },
    {
      "level": "h3",
      "text": "Does memory persist forever What are the limits",
      "id": "does-memory-persist-forever-what-are-the-limits"
    },
    {
      "level": "h2",
      "text": "Where things live on disk",
      "id": "where-things-live-on-disk"
    },
    {
      "level": "h3",
      "text": "Is all data used with OpenClaw saved locally",
      "id": "is-all-data-used-with-openclaw-saved-locally"
    },
    {
      "level": "h3",
      "text": "Where does OpenClaw store its data",
      "id": "where-does-openclaw-store-its-data"
    },
    {
      "level": "h3",
      "text": "Where should AGENTSmd SOULmd USERmd MEMORYmd live",
      "id": "where-should-agentsmd-soulmd-usermd-memorymd-live"
    },
    {
      "level": "h3",
      "text": "What's the recommended backup strategy",
      "id": "what's-the-recommended-backup-strategy"
    },
    {
      "level": "h3",
      "text": "How do I completely uninstall OpenClaw",
      "id": "how-do-i-completely-uninstall-openclaw"
    },
    {
      "level": "h3",
      "text": "Can agents work outside the workspace",
      "id": "can-agents-work-outside-the-workspace"
    },
    {
      "level": "h3",
      "text": "Im in remote mode where is the session store",
      "id": "im-in-remote-mode-where-is-the-session-store"
    },
    {
      "level": "h2",
      "text": "Config basics",
      "id": "config-basics"
    },
    {
      "level": "h3",
      "text": "What format is the config Where is it",
      "id": "what-format-is-the-config-where-is-it"
    },
    {
      "level": "h3",
      "text": "I set gatewaybind lan or tailnet and now nothing listens the UI says unauthorized",
      "id": "i-set-gatewaybind-lan-or-tailnet-and-now-nothing-listens-the-ui-says-unauthorized"
    },
    {
      "level": "h3",
      "text": "Why do I need a token on localhost now",
      "id": "why-do-i-need-a-token-on-localhost-now"
    },
    {
      "level": "h3",
      "text": "Do I have to restart after changing config",
      "id": "do-i-have-to-restart-after-changing-config"
    },
    {
      "level": "h3",
      "text": "How do I enable web search and web fetch",
      "id": "how-do-i-enable-web-search-and-web-fetch"
    },
    {
      "level": "h3",
      "text": "How do I run a central Gateway with specialized workers across devices",
      "id": "how-do-i-run-a-central-gateway-with-specialized-workers-across-devices"
    },
    {
      "level": "h3",
      "text": "Can the OpenClaw browser run headless",
      "id": "can-the-openclaw-browser-run-headless"
    },
    {
      "level": "h3",
      "text": "How do I use Brave for browser control",
      "id": "how-do-i-use-brave-for-browser-control"
    },
    {
      "level": "h2",
      "text": "Remote gateways + nodes",
      "id": "remote-gateways-+-nodes"
    },
    {
      "level": "h3",
      "text": "How do commands propagate between Telegram the gateway and nodes",
      "id": "how-do-commands-propagate-between-telegram-the-gateway-and-nodes"
    },
    {
      "level": "h3",
      "text": "How can my agent access my computer if the Gateway is hosted remotely",
      "id": "how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely"
    },
    {
      "level": "h3",
      "text": "Tailscale is connected but I get no replies What now",
      "id": "tailscale-is-connected-but-i-get-no-replies-what-now"
    },
    {
      "level": "h3",
      "text": "Can two OpenClaw instances talk to each other local VPS",
      "id": "can-two-openclaw-instances-talk-to-each-other-local-vps"
    },
    {
      "level": "h3",
      "text": "Do I need separate VPSes for multiple agents",
      "id": "do-i-need-separate-vpses-for-multiple-agents"
    },
    {
      "level": "h3",
      "text": "Is there a benefit to using a node on my personal laptop instead of SSH from a VPS",
      "id": "is-there-a-benefit-to-using-a-node-on-my-personal-laptop-instead-of-ssh-from-a-vps"
    },
    {
      "level": "h3",
      "text": "Should I install on a second laptop or just add a node",
      "id": "should-i-install-on-a-second-laptop-or-just-add-a-node"
    },
    {
      "level": "h3",
      "text": "Do nodes run a gateway service",
      "id": "do-nodes-run-a-gateway-service"
    },
    {
      "level": "h3",
      "text": "Is there an API RPC way to apply config",
      "id": "is-there-an-api-rpc-way-to-apply-config"
    },
    {
      "level": "h3",
      "text": "configapply wiped my config How do I recover and avoid this",
      "id": "configapply-wiped-my-config-how-do-i-recover-and-avoid-this"
    },
    {
      "level": "h3",
      "text": "What's a minimal sane config for a first install",
      "id": "what's-a-minimal-sane-config-for-a-first-install"
    },
    {
      "level": "h3",
      "text": "How do I set up Tailscale on a VPS and connect from my Mac",
      "id": "how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac"
    },
    {
      "level": "h3",
      "text": "How do I connect a Mac node to a remote Gateway Tailscale Serve",
      "id": "how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve"
    },
    {
      "level": "h2",
      "text": "Env vars and .env loading",
      "id": "env-vars-and-.env-loading"
    },
    {
      "level": "h3",
      "text": "How does OpenClaw load environment variables",
      "id": "how-does-openclaw-load-environment-variables"
    },
    {
      "level": "h3",
      "text": "I started the Gateway via the service and my env vars disappeared What now",
      "id": "i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now"
    },
    {
      "level": "h3",
      "text": "I set COPILOTGITHUBTOKEN but models status shows Shell env off Why",
      "id": "i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why"
    },
    {
      "level": "h2",
      "text": "Sessions & multiple chats",
      "id": "sessions-&-multiple-chats"
    },
    {
      "level": "h3",
      "text": "How do I start a fresh conversation",
      "id": "how-do-i-start-a-fresh-conversation"
    },
    {
      "level": "h3",
      "text": "Do sessions reset automatically if I never send new",
      "id": "do-sessions-reset-automatically-if-i-never-send-new"
    },
    {
      "level": "h3",
      "text": "Is there a way to make a team of OpenClaw instances one CEO and many agents",
      "id": "is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents"
    },
    {
      "level": "h3",
      "text": "Why did context get truncated midtask How do I prevent it",
      "id": "why-did-context-get-truncated-midtask-how-do-i-prevent-it"
    },
    {
      "level": "h3",
      "text": "How do I completely reset OpenClaw but keep it installed",
      "id": "how-do-i-completely-reset-openclaw-but-keep-it-installed"
    },
    {
      "level": "h3",
      "text": "Im getting context too large errors how do I reset or compact",
      "id": "im-getting-context-too-large-errors-how-do-i-reset-or-compact"
    },
    {
      "level": "h3",
      "text": "Why am I seeing LLM request rejected messagesNcontentXtooluseinput Field required",
      "id": "why-am-i-seeing-llm-request-rejected-messagesncontentxtooluseinput-field-required"
    },
    {
      "level": "h3",
      "text": "Why am I getting heartbeat messages every 30 minutes",
      "id": "why-am-i-getting-heartbeat-messages-every-30-minutes"
    },
    {
      "level": "h3",
      "text": "Do I need to add a bot account to a WhatsApp group",
      "id": "do-i-need-to-add-a-bot-account-to-a-whatsapp-group"
    },
    {
      "level": "h3",
      "text": "How do I get the JID of a WhatsApp group",
      "id": "how-do-i-get-the-jid-of-a-whatsapp-group"
    },
    {
      "level": "h3",
      "text": "Why doesnt OpenClaw reply in a group",
      "id": "why-doesnt-openclaw-reply-in-a-group"
    },
    {
      "level": "h3",
      "text": "Do groupsthreads share context with DMs",
      "id": "do-groupsthreads-share-context-with-dms"
    },
    {
      "level": "h3",
      "text": "How many workspaces and agents can I create",
      "id": "how-many-workspaces-and-agents-can-i-create"
    },
    {
      "level": "h3",
      "text": "Can I run multiple bots or chats at the same time Slack and how should I set that up",
      "id": "can-i-run-multiple-bots-or-chats-at-the-same-time-slack-and-how-should-i-set-that-up"
    },
    {
      "level": "h2",
      "text": "Models: defaults, selection, aliases, switching",
      "id": "models:-defaults,-selection,-aliases,-switching"
    },
    {
      "level": "h3",
      "text": "What is the default model",
      "id": "what-is-the-default-model"
    },
    {
      "level": "h3",
      "text": "What model do you recommend",
      "id": "what-model-do-you-recommend"
    },
    {
      "level": "h3",
      "text": "Can I use selfhosted models llamacpp vLLM Ollama",
      "id": "can-i-use-selfhosted-models-llamacpp-vllm-ollama"
    },
    {
      "level": "h3",
      "text": "How do I switch models without wiping my config",
      "id": "how-do-i-switch-models-without-wiping-my-config"
    },
    {
      "level": "h3",
      "text": "What do OpenClaw, Flawd, and Krill use for models",
      "id": "what-do-openclaw,-flawd,-and-krill-use-for-models"
    },
    {
      "level": "h3",
      "text": "How do I switch models on the fly without restarting",
      "id": "how-do-i-switch-models-on-the-fly-without-restarting"
    },
    {
      "level": "h3",
      "text": "Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding",
      "id": "can-i-use-gpt-5.2-for-daily-tasks-and-codex-5.2-for-coding"
    },
    {
      "level": "h3",
      "text": "Why do I see Model is not allowed and then no reply",
      "id": "why-do-i-see-model-is-not-allowed-and-then-no-reply"
    },
    {
      "level": "h3",
      "text": "Why do I see Unknown model minimaxMiniMaxM21",
      "id": "why-do-i-see-unknown-model-minimaxminimaxm21"
    },
    {
      "level": "h3",
      "text": "Can I use MiniMax as my default and OpenAI for complex tasks",
      "id": "can-i-use-minimax-as-my-default-and-openai-for-complex-tasks"
    },
    {
      "level": "h3",
      "text": "Are opus sonnet gpt builtin shortcuts",
      "id": "are-opus-sonnet-gpt-builtin-shortcuts"
    },
    {
      "level": "h3",
      "text": "How do I defineoverride model shortcuts aliases",
      "id": "how-do-i-defineoverride-model-shortcuts-aliases"
    },
    {
      "level": "h3",
      "text": "How do I add models from other providers like OpenRouter or ZAI",
      "id": "how-do-i-add-models-from-other-providers-like-openrouter-or-zai"
    },
    {
      "level": "h2",
      "text": "Model failover and \"All models failed\"",
      "id": "model-failover-and-\"all-models-failed\""
    },
    {
      "level": "h3",
      "text": "How does failover work",
      "id": "how-does-failover-work"
    },
    {
      "level": "h3",
      "text": "What does this error mean",
      "id": "what-does-this-error-mean"
    },
    {
      "level": "h3",
      "text": "Fix checklist for No credentials found for profile anthropicdefault",
      "id": "fix-checklist-for-no-credentials-found-for-profile-anthropicdefault"
    },
    {
      "level": "h3",
      "text": "Why did it also try Google Gemini and fail",
      "id": "why-did-it-also-try-google-gemini-and-fail"
    },
    {
      "level": "h2",
      "text": "Auth profiles: what they are and how to manage them",
      "id": "auth-profiles:-what-they-are-and-how-to-manage-them"
    },
    {
      "level": "h3",
      "text": "What is an auth profile",
      "id": "what-is-an-auth-profile"
    },
    {
      "level": "h3",
      "text": "What are typical profile IDs",
      "id": "what-are-typical-profile-ids"
    },
    {
      "level": "h3",
      "text": "Can I control which auth profile is tried first",
      "id": "can-i-control-which-auth-profile-is-tried-first"
    }
  ],
  "url": "llms-txt#faq",
  "links": []
}