diff --git a/docs/help/faq.md b/docs/help/faq.md
index 4d161578ed9..68debcd807c 100644
--- a/docs/help/faq.md
+++ b/docs/help/faq.md
@@ -10,196 +10,6 @@ title: "FAQ"
Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see [Troubleshooting](/gateway/troubleshooting). For the full config reference, see [Configuration](/gateway/configuration).
-## Table of contents
-
-- [Quick start and first-run setup]
- - [I am stuck, fastest way to get unstuck](#i-am-stuck-fastest-way-to-get-unstuck)
- - [Recommended way to install and set up OpenClaw](#recommended-way-to-install-and-set-up-openclaw)
- - [How do I open the dashboard after onboarding?](#how-do-i-open-the-dashboard-after-onboarding)
- - [How do I authenticate the dashboard (token) on localhost vs remote?](#how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote)
- - [What runtime do I need?](#what-runtime-do-i-need)
- - [Does it run on Raspberry Pi?](#does-it-run-on-raspberry-pi)
- - [Any tips for Raspberry Pi installs?](#any-tips-for-raspberry-pi-installs)
- - [It is stuck on "wake up my friend" / onboarding will not hatch. What now?](#it-is-stuck-on-wake-up-my-friend-onboarding-will-not-hatch-what-now)
- - [Can I migrate my setup to a new machine (Mac mini) without redoing onboarding?](#can-i-migrate-my-setup-to-a-new-machine-mac-mini-without-redoing-onboarding)
- - [Where do I see what is new in the latest version?](#where-do-i-see-what-is-new-in-the-latest-version)
- - [Cannot access docs.openclaw.ai (SSL error)](#cannot-access-docsopenclawai-ssl-error)
- - [Difference between stable and beta](#difference-between-stable-and-beta)
- - [How do I install the beta version and what is the difference between beta and dev](#how-do-i-install-the-beta-version-and-what-is-the-difference-between-beta-and-dev)
- - [How do I try the latest bits?](#how-do-i-try-the-latest-bits)
- - [How long does install and onboarding usually take?](#how-long-does-install-and-onboarding-usually-take)
- - [Installer stuck? How do I get more feedback?](#installer-stuck-how-do-i-get-more-feedback)
- - [Windows install says git not found or openclaw not recognized](#windows-install-says-git-not-found-or-openclaw-not-recognized)
- - [Windows exec output shows garbled Chinese text what should I do](#windows-exec-output-shows-garbled-chinese-text-what-should-i-do)
- - [The docs did not answer my question - how do I get a better answer](#the-docs-did-not-answer-my-question---how-do-i-get-a-better-answer)
- - [How do I install OpenClaw on Linux?](#how-do-i-install-openclaw-on-linux)
- - [How do I install OpenClaw on a VPS?](#how-do-i-install-openclaw-on-a-vps)
- - [Where are the cloud/VPS install guides?](#where-are-the-cloudvps-install-guides)
- - [Can I ask OpenClaw to update itself?](#can-i-ask-openclaw-to-update-itself)
- - [What does onboarding actually do?](#what-does-onboarding-actually-do)
- - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this)
- - [Can I use Claude Max subscription without an API key](#can-i-use-claude-max-subscription-without-an-api-key)
- - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work)
- - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken)
- - [Do you support Claude subscription auth (Claude Pro or Max)?](#do-you-support-claude-subscription-auth-claude-pro-or-max)
- - [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
- - [Is AWS Bedrock supported?](#is-aws-bedrock-supported)
- - [How does Codex auth work?](#how-does-codex-auth-work)
- - [Do you support OpenAI subscription auth (Codex OAuth)?](#do-you-support-openai-subscription-auth-codex-oauth)
- - [How do I set up Gemini CLI OAuth](#how-do-i-set-up-gemini-cli-oauth)
- - [Is a local model OK for casual chats?](#is-a-local-model-ok-for-casual-chats)
- - [How do I keep hosted model traffic in a specific region?](#how-do-i-keep-hosted-model-traffic-in-a-specific-region)
- - [Do I have to buy a Mac Mini to install this?](#do-i-have-to-buy-a-mac-mini-to-install-this)
- - [Do I need a Mac mini for iMessage support?](#do-i-need-a-mac-mini-for-imessage-support)
- - [If I buy a Mac mini to run OpenClaw, can I connect it to my MacBook Pro?](#if-i-buy-a-mac-mini-to-run-openclaw-can-i-connect-it-to-my-macbook-pro)
- - [Can I use Bun?](#can-i-use-bun)
- - [Telegram: what goes in `allowFrom`?](#telegram-what-goes-in-allowfrom)
- - [Can multiple people use one WhatsApp number with different OpenClaw instances?](#can-multiple-people-use-one-whatsapp-number-with-different-openclaw-instances)
- - [Can I run a "fast chat" agent and an "Opus for coding" agent?](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent)
- - [Does Homebrew work on Linux?](#does-homebrew-work-on-linux)
- - [Difference between the hackable git install and npm install](#difference-between-the-hackable-git-install-and-npm-install)
- - [Can I switch between npm and git installs later?](#can-i-switch-between-npm-and-git-installs-later)
- - [Should I run the Gateway on my laptop or a VPS?](#should-i-run-the-gateway-on-my-laptop-or-a-vps)
- - [How important is it to run OpenClaw on a dedicated machine?](#how-important-is-it-to-run-openclaw-on-a-dedicated-machine)
- - [What are the minimum VPS requirements and recommended OS?](#what-are-the-minimum-vps-requirements-and-recommended-os)
- - [Can I run OpenClaw in a VM and what are the requirements](#can-i-run-openclaw-in-a-vm-and-what-are-the-requirements)
-- [What is OpenClaw?](#what-is-openclaw)
- - [What is OpenClaw, in one paragraph?](#what-is-openclaw-in-one-paragraph)
- - [Value proposition](#value-proposition)
- - [I just set it up what should I do first](#i-just-set-it-up-what-should-i-do-first)
- - [What are the top five everyday use cases for OpenClaw](#what-are-the-top-five-everyday-use-cases-for-openclaw)
- - [Can OpenClaw help with lead gen outreach ads and blogs for a SaaS](#can-openclaw-help-with-lead-gen-outreach-ads-and-blogs-for-a-saas)
- - [What are the advantages vs Claude Code for web development?](#what-are-the-advantages-vs-claude-code-for-web-development)
-- [Skills and automation](#skills-and-automation)
- - [How do I customize skills without keeping the repo dirty?](#how-do-i-customize-skills-without-keeping-the-repo-dirty)
- - [Can I load skills from a custom folder?](#can-i-load-skills-from-a-custom-folder)
- - [How can I use different models for different tasks?](#how-can-i-use-different-models-for-different-tasks)
- - [The bot freezes while doing heavy work. How do I offload that?](#the-bot-freezes-while-doing-heavy-work-how-do-i-offload-that)
- - [Cron or reminders do not fire. What should I check?](#cron-or-reminders-do-not-fire-what-should-i-check)
- - [How do I install skills on Linux?](#how-do-i-install-skills-on-linux)
- - [Can OpenClaw run tasks on a schedule or continuously in the background?](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background)
- - [Can I run Apple macOS-only skills from Linux?](#can-i-run-apple-macos-only-skills-from-linux)
- - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration)
- - [How do I use my existing signed-in Chrome with OpenClaw?](#how-do-i-use-my-existing-signed-in-chrome-with-openclaw)
-- [Sandboxing and memory](#sandboxing-and-memory)
- - [Is there a dedicated sandboxing doc?](#is-there-a-dedicated-sandboxing-doc)
- - [How do I bind a host folder into the sandbox?](#how-do-i-bind-a-host-folder-into-the-sandbox)
- - [How does memory work?](#how-does-memory-work)
- - [Memory keeps forgetting things. How do I make it stick?](#memory-keeps-forgetting-things-how-do-i-make-it-stick)
- - [Does memory persist forever? What are the limits?](#does-memory-persist-forever-what-are-the-limits)
- - [Does semantic memory search require an OpenAI API key?](#does-semantic-memory-search-require-an-openai-api-key)
-- [Where things live on disk](#where-things-live-on-disk)
- - [Is all data used with OpenClaw saved locally?](#is-all-data-used-with-openclaw-saved-locally)
- - [Where does OpenClaw store its data?](#where-does-openclaw-store-its-data)
- - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd-soulmd-usermd-memorymd-live)
- - [Recommended backup strategy](#recommended-backup-strategy)
- - [How do I completely uninstall OpenClaw?](#how-do-i-completely-uninstall-openclaw)
- - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace)
- - [I'm in remote mode - where is the session store?](#im-in-remote-mode-where-is-the-session-store)
-- [Config basics](#config-basics)
- - [What format is the config? Where is it?](#what-format-is-the-config-where-is-it)
- - [I set `gateway.bind: "lan"` (or `"tailnet"`) and now nothing listens / the UI says unauthorized](#i-set-gatewaybind-lan-or-tailnet-and-now-nothing-listens-the-ui-says-unauthorized)
- - [Why do I need a token on localhost now?](#why-do-i-need-a-token-on-localhost-now)
- - [Do I have to restart after changing config?](#do-i-have-to-restart-after-changing-config)
- - [How do I disable funny CLI taglines?](#how-do-i-disable-funny-cli-taglines)
- - [How do I enable web search (and web fetch)?](#how-do-i-enable-web-search-and-web-fetch)
- - [config.apply wiped my config. How do I recover and avoid this?](#configapply-wiped-my-config-how-do-i-recover-and-avoid-this)
- - [How do I run a central Gateway with specialized workers across devices?](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices)
- - [Can the OpenClaw browser run headless?](#can-the-openclaw-browser-run-headless)
- - [How do I use Brave for browser control?](#how-do-i-use-brave-for-browser-control)
-- [Remote gateways and nodes](#remote-gateways-and-nodes)
- - [How do commands propagate between Telegram, the gateway, and nodes?](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes)
- - [How can my agent access my computer if the Gateway is hosted remotely?](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely)
- - [Tailscale is connected but I get no replies. What now?](#tailscale-is-connected-but-i-get-no-replies-what-now)
- - [Can two OpenClaw instances talk to each other (local + VPS)?](#can-two-openclaw-instances-talk-to-each-other-local-vps)
- - [Do I need separate VPSes for multiple agents](#do-i-need-separate-vpses-for-multiple-agents)
- - [Is there a benefit to using a node on my personal laptop instead of SSH from a VPS?](#is-there-a-benefit-to-using-a-node-on-my-personal-laptop-instead-of-ssh-from-a-vps)
- - [Do nodes run a gateway service?](#do-nodes-run-a-gateway-service)
- - [Is there an API / RPC way to apply config?](#is-there-an-api-rpc-way-to-apply-config)
- - [Minimal sane config for a first install](#minimal-sane-config-for-a-first-install)
- - [How do I set up Tailscale on a VPS and connect from my Mac?](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac)
- - [How do I connect a Mac node to a remote Gateway (Tailscale Serve)?](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve)
- - [Should I install on a second laptop or just add a node?](#should-i-install-on-a-second-laptop-or-just-add-a-node)
-- [Env vars and .env loading](#env-vars-and-env-loading)
- - [How does OpenClaw load environment variables?](#how-does-openclaw-load-environment-variables)
- - ["I started the Gateway via the service and my env vars disappeared." What now?](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now)
- - [I set `COPILOT_GITHUB_TOKEN`, but models status shows "Shell env: off." Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why)
-- [Sessions and multiple chats](#sessions-and-multiple-chats)
- - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation)
- - [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new)
- - [Is there a way to make a team of OpenClaw instances one CEO and many agents](#is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents)
- - [Why did context get truncated mid-task? How do I prevent it?](#why-did-context-get-truncated-midtask-how-do-i-prevent-it)
- - [How do I completely reset OpenClaw but keep it installed?](#how-do-i-completely-reset-openclaw-but-keep-it-installed)
- - [I'm getting "context too large" errors - how do I reset or compact?](#im-getting-context-too-large-errors-how-do-i-reset-or-compact)
- - [Why am I seeing "LLM request rejected: messages.content.tool_use.input field required"?](#why-am-i-seeing-llm-request-rejected-messagescontenttool_useinput-field-required)
- - [Why am I getting heartbeat messages every 30 minutes?](#why-am-i-getting-heartbeat-messages-every-30-minutes)
- - [Do I need to add a "bot account" to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group)
- - [How do I get the JID of a WhatsApp group?](#how-do-i-get-the-jid-of-a-whatsapp-group)
- - [Why does OpenClaw not reply in a group](#why-does-openclaw-not-reply-in-a-group)
- - [Do groups/threads share context with DMs?](#do-groupsthreads-share-context-with-dms)
- - [How many workspaces and agents can I create?](#how-many-workspaces-and-agents-can-i-create)
- - [Can I run multiple bots or chats at the same time (Slack), and how should I set that up?](#can-i-run-multiple-bots-or-chats-at-the-same-time-slack-and-how-should-i-set-that-up)
-- [Models: defaults, selection, aliases, switching](#models-defaults-selection-aliases-switching)
- - [What is the "default model"?](#what-is-the-default-model)
- - [What model do you recommend?](#what-model-do-you-recommend)
- - [How do I switch models without wiping my config?](#how-do-i-switch-models-without-wiping-my-config)
- - [Can I use self-hosted models (llama.cpp, vLLM, Ollama)?](#can-i-use-selfhosted-models-llamacpp-vllm-ollama)
- - [What do OpenClaw, Flawd, and Krill use for models?](#what-do-openclaw-flawd-and-krill-use-for-models)
- - [How do I switch models on the fly (without restarting)?](#how-do-i-switch-models-on-the-fly-without-restarting)
- - [Can I use GPT 5.2 for daily tasks and Codex 5.3 for coding](#can-i-use-gpt-52-for-daily-tasks-and-codex-53-for-coding)
- - [Why do I see "Model … is not allowed" and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply)
- - [Why do I see "Unknown model: minimax/MiniMax-M2.5"?](#why-do-i-see-unknown-model-minimaxminimaxm25)
- - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks)
- - [Are opus / sonnet / gpt built-in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts)
- - [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases)
- - [How do I add models from other providers like OpenRouter or Z.AI?](#how-do-i-add-models-from-other-providers-like-openrouter-or-zai)
-- [Model failover and "All models failed"](#model-failover-and-all-models-failed)
- - [How does failover work?](#how-does-failover-work)
- - [What does this error mean?](#what-does-this-error-mean)
- - [Fix checklist for `No credentials found for profile "anthropic:default"`](#fix-checklist-for-no-credentials-found-for-profile-anthropicdefault)
- - [Why did it also try Google Gemini and fail?](#why-did-it-also-try-google-gemini-and-fail)
-- [Auth profiles: what they are and how to manage them](#auth-profiles-what-they-are-and-how-to-manage-them)
- - [What is an auth profile?](#what-is-an-auth-profile)
- - [What are typical profile IDs?](#what-are-typical-profile-ids)
- - [Can I control which auth profile is tried first?](#can-i-control-which-auth-profile-is-tried-first)
- - [OAuth vs API key - what is the difference](#oauth-vs-api-key---what-is-the-difference)
-- [Gateway: ports, "already running", and remote mode](#gateway-ports-already-running-and-remote-mode)
- - [What port does the Gateway use?](#what-port-does-the-gateway-use)
- - [Why does `openclaw gateway status` say `Runtime: running` but `RPC probe: failed`?](#why-does-openclaw-gateway-status-say-runtime-running-but-rpc-probe-failed)
- - [Why does `openclaw gateway status` show `Config (cli)` and `Config (service)` different?](#why-does-openclaw-gateway-status-show-config-cli-and-config-service-different)
- - [What does "another gateway instance is already listening" mean?](#what-does-another-gateway-instance-is-already-listening-mean)
- - [How do I run OpenClaw in remote mode (client connects to a Gateway elsewhere)?](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere)
- - [The Control UI says "unauthorized" (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now)
- - [I set gateway.bind tailnet but it cannot bind and nothing listens](#i-set-gatewaybind-tailnet-but-it-cannot-bind-and-nothing-listens)
- - [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host)
- - [What does "invalid handshake" / code 1008 mean?](#what-does-invalid-handshake-code-1008-mean)
-- [Logging and debugging](#logging-and-debugging)
- - [Where are logs?](#where-are-logs)
- - [How do I start/stop/restart the Gateway service?](#how-do-i-startstoprestart-the-gateway-service)
- - [I closed my terminal on Windows - how do I restart OpenClaw?](#i-closed-my-terminal-on-windows-how-do-i-restart-openclaw)
- - [The Gateway is up but replies never arrive. What should I check?](#the-gateway-is-up-but-replies-never-arrive-what-should-i-check)
- - ["Disconnected from gateway: no reason" - what now?](#disconnected-from-gateway-no-reason-what-now)
- - [Telegram setMyCommands fails. What should I check?](#telegram-setmycommands-fails-what-should-i-check)
- - [TUI shows no output. What should I check?](#tui-shows-no-output-what-should-i-check)
- - [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway)
- - [ELI5: `openclaw gateway restart` vs `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway)
- - [Fastest way to get more details when something fails](#fastest-way-to-get-more-details-when-something-fails)
-- [Media and attachments](#media-and-attachments)
- - [My skill generated an image/PDF, but nothing was sent](#my-skill-generated-an-imagepdf-but-nothing-was-sent)
-- [Security and access control](#security-and-access-control)
- - [Is it safe to expose OpenClaw to inbound DMs?](#is-it-safe-to-expose-openclaw-to-inbound-dms)
- - [Is prompt injection only a concern for public bots?](#is-prompt-injection-only-a-concern-for-public-bots)
- - [Should my bot have its own email GitHub account or phone number](#should-my-bot-have-its-own-email-github-account-or-phone-number)
- - [Can I give it autonomy over my text messages and is that safe](#can-i-give-it-autonomy-over-my-text-messages-and-is-that-safe)
- - [Can I use cheaper models for personal assistant tasks?](#can-i-use-cheaper-models-for-personal-assistant-tasks)
- - [I ran /start in Telegram but did not get a pairing code](#i-ran-start-in-telegram-but-did-not-get-a-pairing-code)
- - [WhatsApp: will it message my contacts? How does pairing work?](#whatsapp-will-it-message-my-contacts-how-does-pairing-work)
-- [Chat commands, aborting tasks, and "it will not stop"](#chat-commands-aborting-tasks-and-it-will-not-stop)
- - [How do I stop internal system messages from showing in chat](#how-do-i-stop-internal-system-messages-from-showing-in-chat)
- - [How do I stop/cancel a running task?](#how-do-i-stopcancel-a-running-task)
- - [How do I send a Discord message from Telegram? ("Cross-context messaging denied")](#how-do-i-send-a-discord-message-from-telegram-crosscontext-messaging-denied)
- - [Why does it feel like the bot "ignores" rapid-fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages)
-
## First 60 seconds if something is broken
1. **Quick status (first check)**
@@ -267,2740 +77,2921 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
## Quick start and first-run setup
-### I am stuck, fastest way to get unstuck
+
+
+ Use a local AI agent that can **see your machine**. That is far more effective than asking
+ in Discord, because most "I'm stuck" cases are **local config or environment issues** that
+ remote helpers cannot inspect.
-Use a local AI agent that can **see your machine**. That is far more effective than asking
-in Discord, because most "I'm stuck" cases are **local config or environment issues** that
-remote helpers cannot inspect.
+ - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
+ - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
-- **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
-- **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)
+ These tools can read the repo, run commands, inspect logs, and help fix your machine-level
+ setup (PATH, services, permissions, auth files). Give them the **full source checkout** via
+ the hackable (git) install:
-These tools can read the repo, run commands, inspect logs, and help fix your machine-level
-setup (PATH, services, permissions, auth files). Give them the **full source checkout** via
-the hackable (git) install:
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+ ```
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
-```
+ This installs OpenClaw **from a git checkout**, so the agent can read the code + docs and
+ reason about the exact version you are running. You can always switch back to stable later
+ by re-running the installer without `--install-method git`.
-This installs OpenClaw **from a git checkout**, so the agent can read the code + docs and
-reason about the exact version you are running. You can always switch back to stable later
-by re-running the installer without `--install-method git`.
+ Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the
+ necessary commands. That keeps changes small and easier to audit.
-Tip: ask the agent to **plan and supervise** the fix (step-by-step), then execute only the
-necessary commands. That keeps changes small and easier to audit.
+ If you discover a real bug or fix, please file a GitHub issue or send a PR:
+ [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
+ [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
-If you discover a real bug or fix, please file a GitHub issue or send a PR:
-[https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues)
-[https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls)
+ Start with these commands (share outputs when asking for help):
-Start with these commands (share outputs when asking for help):
+ ```bash
+ openclaw status
+ openclaw models status
+ openclaw doctor
+ ```
-```bash
-openclaw status
-openclaw models status
-openclaw doctor
-```
+ What they do:
-What they do:
+ - `openclaw status`: quick snapshot of gateway/agent health + basic config.
+ - `openclaw models status`: checks provider auth + model availability.
+ - `openclaw doctor`: validates and repairs common config/state issues.
-- `openclaw status`: quick snapshot of gateway/agent health + basic config.
-- `openclaw models status`: checks provider auth + model availability.
-- `openclaw doctor`: validates and repairs common config/state issues.
+ Other useful CLI checks: `openclaw status --all`, `openclaw logs --follow`,
+ `openclaw gateway status`, `openclaw health --verbose`.
-Other useful CLI checks: `openclaw status --all`, `openclaw logs --follow`,
-`openclaw gateway status`, `openclaw health --verbose`.
+ Quick debug loop: [First 60 seconds if something is broken](#first-60-seconds-if-something-is-broken).
+ Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating).
-Quick debug loop: [First 60 seconds if something is broken](#first-60-seconds-if-something-is-broken).
-Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating).
+
-### Recommended way to install and set up OpenClaw
+
+ The repo recommends running from source and using onboarding:
-The repo recommends running from source and using onboarding:
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash
+ openclaw onboard --install-daemon
+ ```
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash
-openclaw onboard --install-daemon
-```
+ The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.
-The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port **18789**.
+ From source (contributors/dev):
-From source (contributors/dev):
+ ```bash
+ git clone https://github.com/openclaw/openclaw.git
+ cd openclaw
+ pnpm install
+ pnpm build
+ pnpm ui:build # auto-installs UI deps on first run
+ openclaw onboard
+ ```
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm build
-pnpm ui:build # auto-installs UI deps on first run
-openclaw onboard
-```
+ If you don't have a global install yet, run it via `pnpm openclaw onboard`.
-If you don't have a global install yet, run it via `pnpm openclaw onboard`.
+
-### How do I open the dashboard after onboarding
+
+ The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine.
+
-The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn't launch, copy/paste the printed URL on the same machine.
+
+ **Localhost (same machine):**
-### How do I authenticate the dashboard token on localhost vs remote
+ - Open `http://127.0.0.1:18789/`.
+ - If it asks for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings.
+ - Retrieve it from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`).
-**Localhost (same machine):**
+ **Not on localhost:**
-- Open `http://127.0.0.1:18789/`.
-- If it asks for auth, paste the token from `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) into Control UI settings.
-- Retrieve it from the gateway host: `openclaw config get gateway.auth.token` (or generate one: `openclaw doctor --generate-gateway-token`).
+ - **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https:///`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no token, assumes trusted gateway host); HTTP APIs still require token/password.
+ - **Tailnet bind**: run `openclaw gateway --bind tailnet --token ""`, open `http://:18789/`, paste token in dashboard settings.
+ - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/` and paste the token in Control UI settings.
-**Not on localhost:**
+ See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.
-- **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https:///`. If `gateway.auth.allowTailscale` is `true`, identity headers satisfy Control UI/WebSocket auth (no token, assumes trusted gateway host); HTTP APIs still require token/password.
-- **Tailnet bind**: run `openclaw gateway --bind tailnet --token ""`, open `http://:18789/`, paste token in dashboard settings.
-- **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/` and paste the token in Control UI settings.
+
-See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.
+
+ Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.
+
-### What runtime do I need
+
+ Yes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB**
+ disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**.
-Node **>= 22** is required. `pnpm` is recommended. Bun is **not recommended** for the Gateway.
+ If you want extra headroom (logs, media, other services), **2GB is recommended**, but it's
+ not a hard minimum.
-### Does it run on Raspberry Pi
+ Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for
+ local screen/camera/canvas or command execution. See [Nodes](/nodes).
-Yes. The Gateway is lightweight - docs list **512MB-1GB RAM**, **1 core**, and about **500MB**
-disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**.
+
-If you want extra headroom (logs, media, other services), **2GB is recommended**, but it's
-not a hard minimum.
+
+ Short version: it works, but expect rough edges.
-Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for
-local screen/camera/canvas or command execution. See [Nodes](/nodes).
+ - Use a **64-bit** OS and keep Node >= 22.
+ - Prefer the **hackable (git) install** so you can see logs and update fast.
+ - Start without channels/skills, then add them one by one.
+ - If you hit weird binary issues, it is usually an **ARM compatibility** problem.
-### Any tips for Raspberry Pi installs
+ Docs: [Linux](/platforms/linux), [Install](/install).
-Short version: it works, but expect rough edges.
+
-- Use a **64-bit** OS and keep Node >= 22.
-- Prefer the **hackable (git) install** so you can see logs and update fast.
-- Start without channels/skills, then add them one by one.
-- If you hit weird binary issues, it is usually an **ARM compatibility** problem.
+
+ That screen depends on the Gateway being reachable and authenticated. The TUI also sends
+ "Wake up, my friend!" automatically on first hatch. If you see that line with **no reply**
+ and tokens stay at 0, the agent never ran.
-Docs: [Linux](/platforms/linux), [Install](/install).
+ 1. Restart the Gateway:
-### It is stuck on wake up my friend onboarding will not hatch What now
+ ```bash
+ openclaw gateway restart
+ ```
-That screen depends on the Gateway being reachable and authenticated. The TUI also sends
-"Wake up, my friend!" automatically on first hatch. If you see that line with **no reply**
-and tokens stay at 0, the agent never ran.
+ 2. Check status + auth:
-1. Restart the Gateway:
+ ```bash
+ openclaw status
+ openclaw models status
+ openclaw logs --follow
+ ```
-```bash
-openclaw gateway restart
-```
+ 3. If it still hangs, run:
-2. Check status + auth:
+ ```bash
+ openclaw doctor
+ ```
-```bash
-openclaw status
-openclaw models status
-openclaw logs --follow
-```
+ If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI
+ is pointed at the right Gateway. See [Remote access](/gateway/remote).
-3. If it still hangs, run:
+
-```bash
-openclaw doctor
-```
+
+ Yes. Copy the **state directory** and **workspace**, then run Doctor once. This
+ keeps your bot "exactly the same" (memory, session history, auth, and channel
+ state) as long as you copy **both** locations:
-If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI
-is pointed at the right Gateway. See [Remote access](/gateway/remote).
+ 1. Install OpenClaw on the new machine.
+ 2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine.
+ 3. Copy your workspace (default: `~/.openclaw/workspace`).
+ 4. Run `openclaw doctor` and restart the Gateway service.
-### Can I migrate my setup to a new machine Mac mini without redoing onboarding
+ That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in
+ remote mode, remember the gateway host owns the session store and workspace.
-Yes. Copy the **state directory** and **workspace**, then run Doctor once. This
-keeps your bot "exactly the same" (memory, session history, auth, and channel
-state) as long as you copy **both** locations:
+ **Important:** if you only commit/push your workspace to GitHub, you're backing
+ up **memory + bootstrap files**, but **not** session history or auth. Those live
+ under `~/.openclaw/` (for example `~/.openclaw/agents//sessions/`).
-1. Install OpenClaw on the new machine.
-2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine.
-3. Copy your workspace (default: `~/.openclaw/workspace`).
-4. Run `openclaw doctor` and restart the Gateway service.
+ Related: [Migrating](/install/migrating), [Where things live on disk](#where-things-live-on-disk),
+ [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),
+ [Remote mode](/gateway/remote).
-That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you're in
-remote mode, remember the gateway host owns the session store and workspace.
+
-**Important:** if you only commit/push your workspace to GitHub, you're backing
-up **memory + bootstrap files**, but **not** session history or auth. Those live
-under `~/.openclaw/` (for example `~/.openclaw/agents//sessions/`).
+
+ Check the GitHub changelog:
+ [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
-Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq#where-does-openclaw-store-its-data),
-[Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),
-[Remote mode](/gateway/remote).
+ Newest entries are at the top. If the top section is marked **Unreleased**, the next dated
+ section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and
+ **Fixes** (plus docs/other sections when needed).
-### Where do I see what is new in the latest version
+
-Check the GitHub changelog:
-[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
+
+ Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity
+ Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More
+ detail: [Troubleshooting](/help/faq#docsopenclawai-shows-an-ssl-error-comcast-xfinity).
+ Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).
-Newest entries are at the top. If the top section is marked **Unreleased**, the next dated
-section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and
-**Fixes** (plus docs/other sections when needed).
+ If you still can't reach the site, the docs are mirrored on GitHub:
+ [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
-### Cannot access docs.openclaw.ai (SSL error)
+
-Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity
-Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. More
-detail: [Troubleshooting](/help/faq#docsopenclawai-shows-an-ssl-error-comcast-xfinity).
-Please help us unblock it by reporting here: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).
+
+ **Stable** and **beta** are **npm dist-tags**, not separate code lines:
-If you still can't reach the site, the docs are mirrored on GitHub:
-[https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)
+ - `latest` = stable
+ - `beta` = early build for testing
-### Difference between stable and beta
+ We ship builds to **beta**, test them, and once a build is solid we **promote
+ that same version to `latest`**. That's why beta and stable can point at the
+ **same version**.
-**Stable** and **beta** are **npm dist-tags**, not separate code lines:
+ See what changed:
+ [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
-- `latest` = stable
-- `beta` = early build for testing
+
-We ship builds to **beta**, test them, and once a build is solid we **promote
-that same version to `latest`**. That's why beta and stable can point at the
-**same version**.
+
+ **Beta** is the npm dist-tag `beta` (may match `latest`).
+ **Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`.
-See what changed:
-[https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
+ One-liners (macOS/Linux):
-### How do I install the beta version and what is the difference between beta and dev
+ ```bash
+ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta
+ ```
-**Beta** is the npm dist-tag `beta` (may match `latest`).
-**Dev** is the moving head of `main` (git); when published, it uses the npm dist-tag `dev`.
+ ```bash
+ curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
+ ```
-One-liners (macOS/Linux):
+ Windows installer (PowerShell):
+ [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)
-```bash
-curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta
-```
+ More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).
-```bash
-curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
-```
+
-Windows installer (PowerShell):
-[https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1)
+
+ Two options:
-More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).
+ 1. **Dev channel (git checkout):**
-### How long does install and onboarding usually take
+ ```bash
+ openclaw update --channel dev
+ ```
-Rough guide:
+ This switches to the `main` branch and updates from source.
-- **Install:** 2-5 minutes
-- **Onboarding:** 5-15 minutes depending on how many channels/models you configure
+ 2. **Hackable install (from the installer site):**
-If it hangs, use [Installer stuck](/help/faq#installer-stuck-how-do-i-get-more-feedback)
-and the fast debug loop in [I am stuck](/help/faq#i-am-stuck-fastest-way-to-get-unstuck).
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+ ```
-### How do I try the latest bits
+ That gives you a local repo you can edit, then update via git.
-Two options:
+ If you prefer a clean clone manually, use:
-1. **Dev channel (git checkout):**
+ ```bash
+ git clone https://github.com/openclaw/openclaw.git
+ cd openclaw
+ pnpm install
+ pnpm build
+ ```
-```bash
-openclaw update --channel dev
-```
+ Docs: [Update](/cli/update), [Development channels](/install/development-channels),
+ [Install](/install).
-This switches to the `main` branch and updates from source.
+
-2. **Hackable install (from the installer site):**
+
+ Rough guide:
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
-```
+ - **Install:** 2-5 minutes
+ - **Onboarding:** 5-15 minutes depending on how many channels/models you configure
-That gives you a local repo you can edit, then update via git.
+ If it hangs, use [Installer stuck](#quick-start-and-first-run-setup)
+ and the fast debug loop in [I am stuck](#quick-start-and-first-run-setup).
-If you prefer a clean clone manually, use:
+
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm build
-```
+
+ Re-run the installer with **verbose output**:
-Docs: [Update](/cli/update), [Development channels](/install/development-channels),
-[Install](/install).
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
+ ```
-### Installer stuck How do I get more feedback
+ Beta install with verbose:
-Re-run the installer with **verbose output**:
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
+ ```
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
-```
+ For a hackable (git) install:
-Beta install with verbose:
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
+ ```
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
-```
+ Windows (PowerShell) equivalent:
-For a hackable (git) install:
+ ```powershell
+ # install.ps1 has no dedicated -Verbose flag yet.
+ Set-PSDebug -Trace 1
+ & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
+ Set-PSDebug -Trace 0
+ ```
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
-```
+ More options: [Installer flags](/install/installer).
-Windows (PowerShell) equivalent:
+
-```powershell
-# install.ps1 has no dedicated -Verbose flag yet.
-Set-PSDebug -Trace 1
-& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
-Set-PSDebug -Trace 0
-```
+
+ Two common Windows issues:
-More options: [Installer flags](/install/installer).
+ **1) npm error spawn git / git not found**
-### Windows install says git not found or openclaw not recognized
+ - Install **Git for Windows** and make sure `git` is on your PATH.
+ - Close and reopen PowerShell, then re-run the installer.
-Two common Windows issues:
+ **2) openclaw is not recognized after install**
-**1) npm error spawn git / git not found**
+ - Your npm global bin folder is not on PATH.
+ - Check the path:
-- Install **Git for Windows** and make sure `git` is on your PATH.
-- Close and reopen PowerShell, then re-run the installer.
+ ```powershell
+ npm config get prefix
+ ```
-**2) openclaw is not recognized after install**
+ - Add that directory to your user PATH (no `\bin` suffix needed on Windows; on most systems it is `%AppData%\npm`).
+ - Close and reopen PowerShell after updating PATH.
-- Your npm global bin folder is not on PATH.
-- Check the path:
+ If you want the smoothest Windows setup, use **WSL2** instead of native Windows.
+ Docs: [Windows](/platforms/windows).
- ```powershell
- npm config get prefix
- ```
+
-- Add that directory to your user PATH (no `\bin` suffix needed on Windows; on most systems it is `%AppData%\npm`).
-- Close and reopen PowerShell after updating PATH.
+
+ This is usually a console code page mismatch on native Windows shells.
-If you want the smoothest Windows setup, use **WSL2** instead of native Windows.
-Docs: [Windows](/platforms/windows).
+ Symptoms:
-### Windows exec output shows garbled Chinese text what should I do
+ - `system.run`/`exec` output renders Chinese as mojibake
+ - The same command looks fine in another terminal profile
-This is usually a console code page mismatch on native Windows shells.
+ Quick workaround in PowerShell:
-Symptoms:
+ ```powershell
+ chcp 65001
+ [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+ [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+ $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+ ```
-- `system.run`/`exec` output renders Chinese as mojibake
-- The same command looks fine in another terminal profile
+ Then restart the Gateway and retry your command:
-Quick workaround in PowerShell:
+ ```powershell
+ openclaw gateway restart
+ ```
-```powershell
-chcp 65001
-[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
-[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
-$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
-```
+ If you still reproduce this on latest OpenClaw, track/report it in:
-Then restart the Gateway and retry your command:
+ - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640)
-```powershell
-openclaw gateway restart
-```
+
-If you still reproduce this on latest OpenClaw, track/report it in:
+
+ Use the **hackable (git) install** so you have the full source and docs locally, then ask
+ your bot (or Claude/Codex) _from that folder_ so it can read the repo and answer precisely.
-- [Issue #30640](https://github.com/openclaw/openclaw/issues/30640)
+ ```bash
+ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
+ ```
-### The docs did not answer my question - how do I get a better answer
+ More detail: [Install](/install) and [Installer flags](/install/installer).
-Use the **hackable (git) install** so you have the full source and docs locally, then ask
-your bot (or Claude/Codex) _from that folder_ so it can read the repo and answer precisely.
+
-```bash
-curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
-```
+
+ Short answer: follow the Linux guide, then run onboarding.
-More detail: [Install](/install) and [Installer flags](/install/installer).
+ - Linux quick path + service install: [Linux](/platforms/linux).
+ - Full walkthrough: [Getting Started](/start/getting-started).
+ - Installer + updates: [Install & updates](/install/updating).
-### How do I install OpenClaw on Linux
+
-Short answer: follow the Linux guide, then run onboarding.
+
+ Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.
-- Linux quick path + service install: [Linux](/platforms/linux).
-- Full walkthrough: [Getting Started](/start/getting-started).
-- Installer + updates: [Install & updates](/install/updating).
+ Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly).
+ Remote access: [Gateway remote](/gateway/remote).
-### How do I install OpenClaw on a VPS
+
-Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.
+
+ We keep a **hosting hub** with the common providers. Pick one and follow the guide:
-Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly).
-Remote access: [Gateway remote](/gateway/remote).
+ - [VPS hosting](/vps) (all providers in one place)
+ - [Fly.io](/install/fly)
+ - [Hetzner](/install/hetzner)
+ - [exe.dev](/install/exe-dev)
-### Where are the cloudVPS install guides
+ How it works in the cloud: the **Gateway runs on the server**, and you access it
+ from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace
+ live on the server, so treat the host as the source of truth and back it up.
-We keep a **hosting hub** with the common providers. Pick one and follow the guide:
+ You can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access
+ local screen/camera/canvas or run commands on your laptop while keeping the
+ Gateway in the cloud.
-- [VPS hosting](/vps) (all providers in one place)
-- [Fly.io](/install/fly)
-- [Hetzner](/install/hetzner)
-- [exe.dev](/install/exe-dev)
+ Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote).
+ Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
-How it works in the cloud: the **Gateway runs on the server**, and you access it
-from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace
-live on the server, so treat the host as the source of truth and back it up.
+
-You can pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway to access
-local screen/camera/canvas or run commands on your laptop while keeping the
-Gateway in the cloud.
+
+ Short answer: **possible, not recommended**. The update flow can restart the
+ Gateway (which drops the active session), may need a clean git checkout, and
+ can prompt for confirmation. Safer: run updates from a shell as the operator.
-Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote).
-Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
+ Use the CLI:
-### Can I ask OpenClaw to update itself
+ ```bash
+ openclaw update
+ openclaw update status
+ openclaw update --channel stable|beta|dev
+ openclaw update --tag
+ openclaw update --no-restart
+ ```
-Short answer: **possible, not recommended**. The update flow can restart the
-Gateway (which drops the active session), may need a clean git checkout, and
-can prompt for confirmation. Safer: run updates from a shell as the operator.
+ If you must automate from an agent:
-Use the CLI:
+ ```bash
+ openclaw update --yes --no-restart
+ openclaw gateway restart
+ ```
-```bash
-openclaw update
-openclaw update status
-openclaw update --channel stable|beta|dev
-openclaw update --tag
-openclaw update --no-restart
-```
+ Docs: [Update](/cli/update), [Updating](/install/updating).
-If you must automate from an agent:
+
-```bash
-openclaw update --yes --no-restart
-openclaw gateway restart
-```
+
+ `openclaw onboard` is the recommended setup path. In **local mode** it walks you through:
-Docs: [Update](/cli/update), [Updating](/install/updating).
+ - **Model/auth setup** (provider OAuth/setup-token flows and API keys supported, plus local model options such as LM Studio)
+ - **Workspace** location + bootstrap files
+ - **Gateway settings** (bind/port/auth/tailscale)
+ - **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)
+ - **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
+ - **Health checks** and **skills** selection
-### What does onboarding actually do
+ It also warns if your configured model is unknown or missing auth.
-`openclaw onboard` is the recommended setup path. In **local mode** it walks you through:
+
-- **Model/auth setup** (provider OAuth/setup-token flows and API keys supported, plus local model options such as LM Studio)
-- **Workspace** location + bootstrap files
-- **Gateway settings** (bind/port/auth/tailscale)
-- **Providers** (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)
-- **Daemon install** (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
-- **Health checks** and **skills** selection
+
+ No. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with
+ **local-only models** so your data stays on your device. Subscriptions (Claude
+ Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
-It also warns if your configured model is unknown or missing auth.
+ If you choose Anthropic subscription auth, decide for yourself whether to use it:
+ Anthropic has blocked some subscription usage outside Claude Code in the past.
+ OpenAI Codex OAuth is explicitly supported for external tools like OpenClaw.
-### Do I need a Claude or OpenAI subscription to run this
+ Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),
+ [Local models](/gateway/local-models), [Models](/concepts/models).
-No. You can run OpenClaw with **API keys** (Anthropic/OpenAI/others) or with
-**local-only models** so your data stays on your device. Subscriptions (Claude
-Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
+
-If you choose Anthropic subscription auth, decide for yourself whether to use it:
-Anthropic has blocked some subscription usage outside Claude Code in the past.
-OpenAI Codex OAuth is explicitly supported for external tools like OpenClaw.
+
+ Yes. You can authenticate with a **setup-token**
+ instead of an API key. This is the subscription path.
-Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),
-[Local models](/gateway/local-models), [Models](/concepts/models).
+ Claude Pro/Max subscriptions **do not include an API key**, so this is the
+ technical path for subscription accounts. But this is your decision: Anthropic
+ has blocked some subscription usage outside Claude Code in the past.
+ If you want the clearest and safest supported path for production, use an Anthropic API key.
-### Can I use Claude Max subscription without an API key
+
-Yes. You can authenticate with a **setup-token**
-instead of an API key. This is the subscription path.
+
+ `claude 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 onboarding 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).
+
-Claude Pro/Max subscriptions **do not include an API key**, so this is the
-technical path for subscription accounts. But this is your decision: Anthropic
-has blocked some subscription usage outside Claude Code in the past.
-If you want the clearest and safest supported path for production, use an Anthropic API key.
+
+ It is **not** in the Anthropic Console. The setup-token is generated by the **Claude Code CLI** on **any machine**:
-### How does Anthropic setuptoken auth work
+ ```bash
+ claude setup-token
+ ```
-`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 onboarding 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).
+ Copy the token it prints, then choose **Anthropic token (paste setup-token)** in onboarding. 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).
-### Where do I find an Anthropic setuptoken
+
-It is **not** in the Anthropic Console. The setup-token is generated by the **Claude Code CLI** on **any machine**:
+
+ Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
-```bash
-claude setup-token
-```
+ Important: this is technical compatibility, not a policy guarantee. Anthropic
+ has blocked some subscription usage outside Claude Code in the past.
+ You need to decide whether to use it and verify Anthropic's current terms.
+ For production or multi-user workloads, Anthropic API key auth is the safer, recommended choice.
-Copy the token it prints, then choose **Anthropic token (paste setup-token)** in onboarding. If you want to run it on the gateway host, use `openclaw models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `openclaw models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic).
+
-### Do you support Claude subscription auth (Claude Pro or Max)
+
+ That means your **Anthropic quota/rate limit** is exhausted for the current window. If you
+ use a **Claude subscription** (setup-token), wait for the window to
+ reset or upgrade your plan. If you use an **Anthropic API key**, check the Anthropic Console
+ for usage/billing and raise limits as needed.
-Yes - via **setup-token**. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth).
+ If the message is specifically:
+ `Extra usage is required for long context requests`, the request is trying to use
+ Anthropic's 1M context beta (`context1m: true`). That only works when your
+ credential is eligible for long-context billing (API key billing or subscription
+ with Extra Usage enabled).
-Important: this is technical compatibility, not a policy guarantee. Anthropic
-has blocked some subscription usage outside Claude Code in the past.
-You need to decide whether to use it and verify Anthropic's current terms.
-For production or multi-user workloads, Anthropic API key auth is the safer, recommended choice.
+ Tip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited.
+ See [Models](/cli/models), [OAuth](/concepts/oauth), and
+ [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
-### Why am I seeing HTTP 429 ratelimiterror from Anthropic
+
-That means your **Anthropic quota/rate limit** is exhausted for the current window. If you
-use a **Claude subscription** (setup-token), wait for the window to
-reset or upgrade your plan. If you use an **Anthropic API key**, check the Anthropic Console
-for usage/billing and raise limits as needed.
+
+ Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/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.
+
-If the message is specifically:
-`Extra usage is required for long context requests`, the request is trying to use
-Anthropic's 1M context beta (`context1m: true`). That only works when your
-credential is eligible for long-context billing (API key billing or subscription
-with Extra Usage enabled).
+
+ OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).
+
-Tip: set a **fallback model** so OpenClaw can keep replying while a provider is rate-limited.
-See [Models](/cli/models), [OAuth](/concepts/oauth), and
-[/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).
+
+ Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**.
+ OpenAI explicitly allows subscription OAuth usage in external tools/workflows
+ like OpenClaw. Onboarding can run the OAuth flow for you.
-### Is AWS Bedrock supported
+ See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard).
-Yes - via pi-ai's **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
+
-### How does Codex auth work
+
+ Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.
-OpenClaw supports **OpenAI Code (Codex)** via OAuth (ChatGPT sign-in). Onboarding can run the OAuth flow and will set the default model to `openai-codex/gpt-5.4` when appropriate. See [Model providers](/concepts/model-providers) and [Onboarding (CLI)](/start/wizard).
+ Steps:
-### Do you support OpenAI subscription auth Codex OAuth
+ 1. Enable the plugin: `openclaw plugins enable google`
+ 2. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
-Yes. OpenClaw fully supports **OpenAI Code (Codex) subscription OAuth**.
-OpenAI explicitly allows subscription OAuth usage in external tools/workflows
-like OpenClaw. Onboarding can run the OAuth flow for you.
+ This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).
-See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard).
+
-### How do I set up Gemini CLI OAuth
+
+ Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** MiniMax M2.5 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).
+
-Gemini CLI uses a **plugin auth flow**, not a client id or secret in `openclaw.json`.
+
+ Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using `models.mode: "merge"` so fallbacks stay available while respecting the regioned provider you select.
+
-Steps:
+
+ No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people
+ buy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too.
-1. Enable the plugin: `openclaw plugins enable google`
-2. Login: `openclaw models auth login --provider google-gemini-cli --set-default`
+ You only need a Mac **for macOS-only tools**. For iMessage, use [BlueBubbles](/channels/bluebubbles) (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node.
-This stores OAuth tokens in auth profiles on the gateway host. Details: [Model providers](/concepts/model-providers).
+ Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).
-### Is a local model OK for casual chats
+
-Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** MiniMax M2.5 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).
+
+ You need **some macOS device** signed into Messages. It does **not** have to be a Mac mini -
+ any Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere.
-### How do I keep hosted model traffic in a specific region
+ Common setups:
-Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using `models.mode: "merge"` so fallbacks stay available while respecting the regioned provider you select.
+ - Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages.
+ - Run everything on the Mac if you want the simplest single-machine setup.
-### Do I have to buy a Mac Mini to install this
+ Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes),
+ [Mac remote mode](/platforms/mac/remote).
-No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people
-buy one as an always-on host, but a small VPS, home server, or Raspberry Pi-class box works too.
+
-You only need a Mac **for macOS-only tools**. For iMessage, use [BlueBubbles](/channels/bluebubbles) (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node.
+
+ Yes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a
+ **node** (companion device). Nodes don't run the Gateway - they provide extra
+ capabilities like screen/camera/canvas and `system.run` on that device.
-Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).
+ Common pattern:
-### Do I need a Mac mini for iMessage support
+ - Gateway on the Mac mini (always-on).
+ - MacBook Pro runs the macOS app or a node host and pairs to the Gateway.
+ - Use `openclaw nodes status` / `openclaw nodes list` to see it.
-You need **some macOS device** signed into Messages. It does **not** have to be a Mac mini -
-any Mac works. **Use [BlueBubbles](/channels/bluebubbles)** (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere.
+ Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
-Common setups:
+
-- Run the Gateway on Linux/VPS, and run the BlueBubbles server on any Mac signed into Messages.
-- Run everything on the Mac if you want the simplest single‑machine setup.
+
+ Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.
+ Use **Node** for stable gateways.
-Docs: [BlueBubbles](/channels/bluebubbles), [Nodes](/nodes),
-[Mac remote mode](/platforms/mac/remote).
+ If you still want to experiment with Bun, do it on a non-production gateway
+ without WhatsApp/Telegram.
-### If I buy a Mac mini to run OpenClaw can I connect it to my MacBook Pro
+
-Yes. The **Mac mini can run the Gateway**, and your MacBook Pro can connect as a
-**node** (companion device). Nodes don't run the Gateway - they provide extra
-capabilities like screen/camera/canvas and `system.run` on that device.
+
+ `channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username.
-Common pattern:
+ Onboarding accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only.
-- Gateway on the Mac mini (always-on).
-- MacBook Pro runs the macOS app or a node host and pairs to the Gateway.
-- Use `openclaw nodes status` / `openclaw nodes list` to see it.
+ Safer (no third-party bot):
-Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).
+ - DM your bot, then run `openclaw logs --follow` and read `from.id`.
-### Can I use Bun
+ Official Bot API:
-Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram.
-Use **Node** for stable gateways.
+ - DM your bot, then call `https://api.telegram.org/bot/getUpdates` and read `message.from.id`.
-If you still want to experiment with Bun, do it on a non-production gateway
-without WhatsApp/Telegram.
+ Third-party (less private):
-### Telegram what goes in allowFrom
+ - DM `@userinfobot` or `@getidsbot`.
-`channels.telegram.allowFrom` is **the human sender's Telegram user ID** (numeric). It is not the bot username.
+ See [/channels/telegram](/channels/telegram#access-control-and-activation).
-Onboarding accepts `@username` input and resolves it to a numeric ID, but OpenClaw authorization uses numeric IDs only.
+
-Safer (no third-party bot):
+
+ Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "direct"`, 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).
+
-- DM your bot, then run `openclaw logs --follow` and read `from.id`.
+
+ Yes. Use multi-agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration).
+
-Official Bot API:
+
+ Yes. Homebrew supports Linux (Linuxbrew). Quick setup:
-- DM your bot, then call `https://api.telegram.org/bot/getUpdates` and read `message.from.id`.
+ ```bash
+ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+ echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
+ eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+ brew install
+ ```
-Third-party (less private):
+ If you run OpenClaw via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non-login shells.
+ Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set.
-- DM `@userinfobot` or `@getidsbot`.
+
-See [/channels/telegram](/channels/telegram#access-control-and-activation).
+
+ - **Hackable (git) install:** full source checkout, editable, best for contributors.
+ You run builds locally and can patch code/docs.
+ - **npm install:** global CLI install, no repo, best for "just run it."
+ Updates come from npm dist-tags.
-### Can multiple people use one WhatsApp number with different OpenClaw instances
+ Docs: [Getting started](/start/getting-started), [Updating](/install/updating).
-Yes, via **multi-agent routing**. Bind each sender's WhatsApp **DM** (peer `kind: "direct"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp).
+
-### Can I run a fast chat agent and an Opus for coding agent
+
+ Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
+ This **does not delete your data** - it only changes the OpenClaw code install. Your state
+ (`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched.
-Yes. Use multi-agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration).
+ From npm to git:
-### Does Homebrew work on Linux
+ ```bash
+ git clone https://github.com/openclaw/openclaw.git
+ cd openclaw
+ pnpm install
+ pnpm build
+ openclaw doctor
+ openclaw gateway restart
+ ```
-Yes. Homebrew supports Linux (Linuxbrew). Quick setup:
+ From git to npm:
-```bash
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
-eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
-brew install
-```
+ ```bash
+ npm install -g openclaw@latest
+ openclaw doctor
+ openclaw gateway restart
+ ```
-If you run OpenClaw via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non-login shells.
-Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set.
+ Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).
-### Difference between the hackable git install and npm install
+ Backup tips: see [Backup strategy](#where-things-live-on-disk).
-- **Hackable (git) install:** full source checkout, editable, best for contributors.
- You run builds locally and can patch code/docs.
-- **npm install:** global CLI install, no repo, best for "just run it."
- Updates come from npm dist-tags.
+
-Docs: [Getting started](/start/getting-started), [Updating](/install/updating).
+
+ Short answer: **if you want 24/7 reliability, use a VPS**. If you want the
+ lowest friction and you're okay with sleep/restarts, run it locally.
-### Can I switch between npm and git installs later
+ **Laptop (local Gateway)**
-Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
-This **does not delete your data** - it only changes the OpenClaw code install. Your state
-(`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched.
+ - **Pros:** no server cost, direct access to local files, live browser window.
+ - **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
-From npm → git:
+ **VPS / cloud**
-```bash
-git clone https://github.com/openclaw/openclaw.git
-cd openclaw
-pnpm install
-pnpm build
-openclaw doctor
-openclaw gateway restart
-```
+ - **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.
+ - **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.
-From git → npm:
+ **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).
-```bash
-npm install -g openclaw@latest
-openclaw doctor
-openclaw gateway restart
-```
+ **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.
-Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation).
+
-Backup tips: see [Backup strategy](/help/faq#recommended-backup-strategy).
+
+ Not required, but **recommended for reliability and isolation**.
-### Should I run the Gateway on my laptop or a VPS
+ - **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
+ - **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates.
-Short answer: **if you want 24/7 reliability, use a VPS**. If you want the
-lowest friction and you're okay with sleep/restarts, run it locally.
+ If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a **node** for local screen/camera/exec tools. See [Nodes](/nodes).
+ For security guidance, read [Security](/gateway/security).
-**Laptop (local Gateway)**
+
-- **Pros:** no server cost, direct access to local files, live browser window.
-- **Cons:** sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
+
+ OpenClaw is lightweight. For a basic Gateway + one chat channel:
-**VPS / cloud**
+ - **Absolute minimum:** 1 vCPU, 1GB RAM, ~500MB disk.
+ - **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.
-- **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.
-- **Cons:** often run headless (use screenshots), remote file access only, you must SSH for updates.
+ OS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there.
-**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).
+ Docs: [Linux](/platforms/linux), [VPS hosting](/vps).
-**Recommended default:** VPS if you had gateway disconnects before. Local is great when you're actively using the Mac and want local file access or UI automation with a visible browser.
+
-### How important is it to run OpenClaw on a dedicated machine
+
+ Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough
+ RAM for the Gateway and any channels you enable.
-Not required, but **recommended for reliability and isolation**.
+ Baseline guidance:
-- **Dedicated host (VPS/Mac mini/Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
-- **Shared laptop/desktop:** totally fine for testing and active use, but expect pauses when the machine sleeps or updates.
+ - **Absolute minimum:** 1 vCPU, 1GB RAM.
+ - **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools.
+ - **OS:** Ubuntu LTS or another modern Debian/Ubuntu.
-If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a **node** for local screen/camera/exec tools. See [Nodes](/nodes).
-For security guidance, read [Security](/gateway/security).
+ If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling
+ compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
+ If you are running macOS in a VM, see [macOS VM](/install/macos-vm).
-### What are the minimum VPS requirements and recommended OS
-
-OpenClaw is lightweight. For a basic Gateway + one chat channel:
-
-- **Absolute minimum:** 1 vCPU, 1GB RAM, ~500MB disk.
-- **Recommended:** 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.
-
-OS: use **Ubuntu LTS** (or any modern Debian/Ubuntu). The Linux install path is best tested there.
-
-Docs: [Linux](/platforms/linux), [VPS hosting](/vps).
-
-### Can I run OpenClaw in a VM and what are the requirements
-
-Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough
-RAM for the Gateway and any channels you enable.
-
-Baseline guidance:
-
-- **Absolute minimum:** 1 vCPU, 1GB RAM.
-- **Recommended:** 2GB RAM or more if you run multiple channels, browser automation, or media tools.
-- **OS:** Ubuntu LTS or another modern Debian/Ubuntu.
-
-If you are on Windows, **WSL2 is the easiest VM style setup** and has the best tooling
-compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
-If you are running macOS in a VM, see [macOS VM](/install/macos-vm).
+
+
## What is OpenClaw?
-### What is OpenClaw in one paragraph
+
+
+ OpenClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product.
+
-OpenClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product.
+
+ OpenClaw is not "just a Claude wrapper." It's a **local-first control plane** that lets you run a
+ capable assistant on **your own hardware**, reachable from the chat apps you already use, with
+ stateful sessions, memory, and tools - without handing control of your workflows to a hosted
+ SaaS.
-### Value proposition
+ Highlights:
-OpenClaw is not "just a Claude wrapper." It's a **local-first control plane** that lets you run a
-capable assistant on **your own hardware**, reachable from the chat apps you already use, with
-stateful sessions, memory, and tools - without handing control of your workflows to a hosted
-SaaS.
+ - **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the
+ workspace + session history local.
+ - **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc,
+ plus mobile voice and Canvas on supported platforms.
+ - **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per-agent routing
+ and failover.
+ - **Local-only option:** run local models so **all data can stay on your device** if you want.
+ - **Multi-agent routing:** separate agents per channel, account, or task, each with its own
+ workspace and defaults.
+ - **Open source and hackable:** inspect, extend, and self-host without vendor lock-in.
-Highlights:
+ Docs: [Gateway](/gateway), [Channels](/channels), [Multi-agent](/concepts/multi-agent),
+ [Memory](/concepts/memory).
-- **Your devices, your data:** run the Gateway wherever you want (Mac, Linux, VPS) and keep the
- workspace + session history local.
-- **Real channels, not a web sandbox:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc,
- plus mobile voice and Canvas on supported platforms.
-- **Model-agnostic:** use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per-agent routing
- and failover.
-- **Local-only option:** run local models so **all data can stay on your device** if you want.
-- **Multi-agent routing:** separate agents per channel, account, or task, each with its own
- workspace and defaults.
-- **Open source and hackable:** inspect, extend, and self-host without vendor lock-in.
+
-Docs: [Gateway](/gateway), [Channels](/channels), [Multi-agent](/concepts/multi-agent),
-[Memory](/concepts/memory).
+
+ Good first projects:
-### I just set it up what should I do first
+ - Build a website (WordPress, Shopify, or a simple static site).
+ - Prototype a mobile app (outline, screens, API plan).
+ - Organize files and folders (cleanup, naming, tagging).
+ - Connect Gmail and automate summaries or follow ups.
-Good first projects:
+ It can handle large tasks, but it works best when you split them into phases and
+ use sub agents for parallel work.
-- Build a website (WordPress, Shopify, or a simple static site).
-- Prototype a mobile app (outline, screens, API plan).
-- Organize files and folders (cleanup, naming, tagging).
-- Connect Gmail and automate summaries or follow ups.
+
-It can handle large tasks, but it works best when you split them into phases and
-use sub agents for parallel work.
+
+ Everyday wins usually look like:
-### What are the top five everyday use cases for OpenClaw
+ - **Personal briefings:** summaries of inbox, calendar, and news you care about.
+ - **Research and drafting:** quick research, summaries, and first drafts for emails or docs.
+ - **Reminders and follow ups:** cron or heartbeat driven nudges and checklists.
+ - **Browser automation:** filling forms, collecting data, and repeating web tasks.
+ - **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat.
-Everyday wins usually look like:
+
-- **Personal briefings:** summaries of inbox, calendar, and news you care about.
-- **Research and drafting:** quick research, summaries, and first drafts for emails or docs.
-- **Reminders and follow ups:** cron or heartbeat driven nudges and checklists.
-- **Browser automation:** filling forms, collecting data, and repeating web tasks.
-- **Cross device coordination:** send a task from your phone, let the Gateway run it on a server, and get the result back in chat.
+
+ Yes for **research, qualification, and drafting**. It can scan sites, build shortlists,
+ summarize prospects, and write outreach or ad copy drafts.
-### Can OpenClaw help with lead gen outreach ads and blogs for a SaaS
+ For **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and
+ platform policies, and review anything before it is sent. The safest pattern is to let
+ OpenClaw draft and you approve.
-Yes for **research, qualification, and drafting**. It can scan sites, build shortlists,
-summarize prospects, and write outreach or ad copy drafts.
+ Docs: [Security](/gateway/security).
-For **outreach or ad runs**, keep a human in the loop. Avoid spam, follow local laws and
-platform policies, and review anything before it is sent. The safest pattern is to let
-OpenClaw draft and you approve.
+
-Docs: [Security](/gateway/security).
+
+ OpenClaw is a **personal assistant** and coordination layer, not an IDE replacement. Use
+ Claude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you
+ want durable memory, cross-device access, and tool orchestration.
-### What are the advantages vs Claude Code for web development
+ Advantages:
-OpenClaw is a **personal assistant** and coordination layer, not an IDE replacement. Use
-Claude Code or Codex for the fastest direct coding loop inside a repo. Use OpenClaw when you
-want durable memory, cross-device access, and tool orchestration.
+ - **Persistent memory + workspace** across sessions
+ - **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat)
+ - **Tool orchestration** (browser, files, scheduling, hooks)
+ - **Always-on Gateway** (run on a VPS, interact from anywhere)
+ - **Nodes** for local browser/screen/camera/exec
-Advantages:
+ Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)
-- **Persistent memory + workspace** across sessions
-- **Multi-platform access** (WhatsApp, Telegram, TUI, WebChat)
-- **Tool orchestration** (browser, files, scheduling, hooks)
-- **Always-on Gateway** (run on a VPS, interact from anywhere)
-- **Nodes** for local browser/screen/camera/exec
-
-Showcase: [https://openclaw.ai/showcase](https://openclaw.ai/showcase)
+
+
## Skills and automation
-### How do I customize skills without keeping the repo dirty
+
+
+ Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `/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.
+
-Use managed overrides instead of editing the repo copy. Put your changes in `~/.openclaw/skills//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.openclaw/openclaw.json`). Precedence is `/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.
+
+ Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `/skills` on the next session.
+
-### Can I load skills from a custom folder
+
+ Today the supported patterns are:
-Yes. Add extra directories via `skills.load.extraDirs` in `~/.openclaw/openclaw.json` (lowest precedence). Default precedence remains: `/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` installs into `./skills` by default, which OpenClaw treats as `/skills`.
+ - **Cron jobs**: isolated jobs can set a `model` override per job.
+ - **Sub-agents**: route tasks to separate agents with different default models.
+ - **On-demand switch**: use `/model` to switch the current session model at any time.
-### How can I use different models for different tasks
+ See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands).
-Today the supported patterns are:
+
-- **Cron jobs**: isolated jobs can set a `model` override per job.
-- **Sub-agents**: route tasks to separate agents with different default models.
-- **On-demand switch**: use `/model` to switch the current session model at any time.
+
+ Use **sub-agents** for long or parallel tasks. Sub-agents run in their own session,
+ return a summary, and keep your main chat responsive.
-See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands).
+ Ask your bot to "spawn a sub-agent for this task" or use `/subagents`.
+ Use `/status` in chat to see what the Gateway is doing right now (and whether it is busy).
-### The bot freezes while doing heavy work How do I offload that
+ Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a
+ cheaper model for sub-agents via `agents.defaults.subagents.model`.
-Use **sub-agents** for long or parallel tasks. Sub-agents run in their own session,
-return a summary, and keep your main chat responsive.
+ Docs: [Sub-agents](/tools/subagents).
-Ask your bot to "spawn a sub-agent for this task" or use `/subagents`.
-Use `/status` in chat to see what the Gateway is doing right now (and whether it is busy).
+
-Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a
-cheaper model for sub-agents via `agents.defaults.subagents.model`.
+
+ Use thread bindings. You can bind a Discord thread to a subagent or session target so follow-up messages in that thread stay on that bound session.
-Docs: [Sub-agents](/tools/subagents).
+ Basic flow:
-### How do thread-bound subagent sessions work on Discord
+ - Spawn with `sessions_spawn` using `thread: true` (and optionally `mode: "session"` for persistent follow-up).
+ - Or manually bind with `/focus `.
+ - Use `/agents` to inspect binding state.
+ - Use `/session idle ` and `/session max-age ` to control auto-unfocus.
+ - Use `/unfocus` to detach the thread.
-Use thread bindings. You can bind a Discord thread to a subagent or session target so follow-up messages in that thread stay on that bound session.
+ Required config:
-Basic flow:
+ - Global defaults: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
+ - Discord overrides: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`.
+ - Auto-bind on spawn: set `channels.discord.threadBindings.spawnSubagentSessions: true`.
-- Spawn with `sessions_spawn` using `thread: true` (and optionally `mode: "session"` for persistent follow-up).
-- Or manually bind with `/focus `.
-- Use `/agents` to inspect binding state.
-- Use `/session idle ` and `/session max-age ` to control auto-unfocus.
-- Use `/unfocus` to detach the thread.
+ Docs: [Sub-agents](/tools/subagents), [Discord](/channels/discord), [Configuration Reference](/gateway/configuration-reference), [Slash commands](/tools/slash-commands).
-Required config:
+
-- Global defaults: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
-- Discord overrides: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`.
-- Auto-bind on spawn: set `channels.discord.threadBindings.spawnSubagentSessions: true`.
+
+ Cron runs inside the Gateway process. If the Gateway is not running continuously,
+ scheduled jobs will not run.
-Docs: [Sub-agents](/tools/subagents), [Discord](/channels/discord), [Configuration Reference](/gateway/configuration-reference), [Slash commands](/tools/slash-commands).
+ Checklist:
-### Cron or reminders do not fire What should I check
+ - Confirm cron is enabled (`cron.enabled`) and `OPENCLAW_SKIP_CRON` is not set.
+ - Check the Gateway is running 24/7 (no sleep/restarts).
+ - Verify timezone settings for the job (`--tz` vs host timezone).
-Cron runs inside the Gateway process. If the Gateway is not running continuously,
-scheduled jobs will not run.
+ Debug:
-Checklist:
+ ```bash
+ openclaw cron run --force
+ openclaw cron runs --id --limit 50
+ ```
-- Confirm cron is enabled (`cron.enabled`) and `OPENCLAW_SKIP_CRON` is not set.
-- Check the Gateway is running 24/7 (no sleep/restarts).
-- Verify timezone settings for the job (`--tz` vs host timezone).
+ Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat).
-Debug:
+
-```bash
-openclaw cron run --force
-openclaw cron runs --id --limit 50
-```
+
+ Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux.
+ Browse skills at [https://clawhub.com](https://clawhub.com).
-Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat).
+ Install the ClawHub CLI (pick one package manager):
-### How do I install skills on Linux
+ ```bash
+ npm i -g clawhub
+ ```
-Use **ClawHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn't available on Linux.
-Browse skills at [https://clawhub.com](https://clawhub.com).
+ ```bash
+ pnpm add -g clawhub
+ ```
-Install the ClawHub CLI (pick one package manager):
+
-```bash
-npm i -g clawhub
-```
+
+ Yes. Use the Gateway scheduler:
-```bash
-pnpm add -g clawhub
-```
+ - **Cron jobs** for scheduled or recurring tasks (persist across restarts).
+ - **Heartbeat** for "main session" periodic checks.
+ - **Isolated jobs** for autonomous agents that post summaries or deliver to chats.
-### Can OpenClaw run tasks on a schedule or continuously in the background
+ Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat),
+ [Heartbeat](/gateway/heartbeat).
-Yes. Use the Gateway scheduler:
+
-- **Cron jobs** for scheduled or recurring tasks (persist across restarts).
-- **Heartbeat** for "main session" periodic checks.
-- **Isolated jobs** for autonomous agents that post summaries or deliver to chats.
+
+ Not directly. macOS skills are gated by `metadata.openclaw.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating.
-Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat),
-[Heartbeat](/gateway/heartbeat).
+ You have three supported patterns:
-### Can I run Apple macOS-only skills from Linux?
+ **Option A - run the Gateway on a Mac (simplest).**
+ Run the Gateway where the macOS binaries exist, then connect from Linux in [remote mode](#gateway-ports-already-running-and-remote-mode) or over Tailscale. The skills load normally because the Gateway host is macOS.
-Not directly. macOS skills are gated by `metadata.openclaw.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `apple-notes`, `apple-reminders`, `things-mac`) will not load unless you override the gating.
+ **Option B - use a macOS node (no SSH).**
+ Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Commands** to "Always Ask" or "Always Allow" on the Mac. OpenClaw can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the `nodes` tool. If you choose "Always Ask", approving "Always Allow" in the prompt adds that command to the allowlist.
-You have three supported patterns:
+ **Option C - proxy macOS binaries over SSH (advanced).**
+ Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
-**Option A - run the Gateway on a Mac (simplest).**
-Run 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.
+ 1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes):
-**Option B - use a macOS node (no SSH).**
-Run the Gateway on Linux, pair a macOS node (menubar app), and set **Node Run Commands** to "Always Ask" or "Always Allow" on the Mac. OpenClaw can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the `nodes` tool. If you choose "Always Ask", approving "Always Allow" in the prompt adds that command to the allowlist.
+ ```bash
+ #!/usr/bin/env bash
+ set -euo pipefail
+ exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
+ ```
-**Option C - proxy macOS binaries over SSH (advanced).**
-Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
+ 2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`).
+ 3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux:
-1. Create an SSH wrapper for the binary (example: `memo` for Apple Notes):
+ ```markdown
+ ---
+ name: apple-notes
+ description: Manage Apple Notes via the memo CLI on macOS.
+ metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
+ ---
+ ```
- ```bash
- #!/usr/bin/env bash
- set -euo pipefail
- exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
- ```
+ 4. Start a new session so the skills snapshot refreshes.
-2. Put the wrapper on `PATH` on the Linux host (for example `~/bin/memo`).
-3. Override the skill metadata (workspace or `~/.openclaw/skills`) to allow Linux:
+
- ```markdown
- ---
- name: apple-notes
- description: Manage Apple Notes via the memo CLI on macOS.
- metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
- ---
- ```
+
+ Not built-in today.
-4. Start a new session so the skills snapshot refreshes.
+ Options:
-### Do you have a Notion or HeyGen integration
+ - **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs).
+ - **Browser automation:** works without code but is slower and more fragile.
-Not built-in today.
+ If you want to keep context per client (agency workflows), a simple pattern is:
-Options:
+ - One Notion page per client (context + preferences + active work).
+ - Ask the agent to fetch that page at the start of a session.
-- **Custom skill / plugin:** best for reliable API access (Notion/HeyGen both have APIs).
-- **Browser automation:** works without code but is slower and more fragile.
+ If you want a native integration, open a feature request or build a skill
+ targeting those APIs.
-If you want to keep context per client (agency workflows), a simple pattern is:
+ Install skills:
-- One Notion page per client (context + preferences + active work).
-- Ask the agent to fetch that page at the start of a session.
+ ```bash
+ clawhub install
+ clawhub update --all
+ ```
-If you want a native integration, open a feature request or build a skill
-targeting those APIs.
+ ClawHub installs into `./skills` under your current directory (or falls back to your configured OpenClaw workspace); OpenClaw treats that as `/skills` on the next session. For shared skills across agents, place them in `~/.openclaw/skills//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).
-Install skills:
+
-```bash
-clawhub install
-clawhub update --all
-```
+
+ Use the built-in `user` browser profile, which attaches through Chrome DevTools MCP:
-ClawHub installs into `./skills` under your current directory (or falls back to your configured OpenClaw workspace); OpenClaw treats that as `/skills` on the next session. For shared skills across agents, place them in `~/.openclaw/skills//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).
+ ```bash
+ openclaw browser --browser-profile user tabs
+ openclaw browser --browser-profile user snapshot
+ ```
-### How do I use my existing signed-in Chrome with OpenClaw
+ If you want a custom name, create an explicit MCP profile:
-Use the built-in `user` browser profile, which attaches through Chrome DevTools MCP:
+ ```bash
+ openclaw browser create-profile --name chrome-live --driver existing-session
+ openclaw browser --browser-profile chrome-live tabs
+ ```
-```bash
-openclaw browser --browser-profile user tabs
-openclaw browser --browser-profile user snapshot
-```
+ This path is host-local. If the Gateway runs elsewhere, either run a node host on the browser machine or use remote CDP instead.
-If you want a custom name, create an explicit MCP profile:
-
-```bash
-openclaw browser create-profile --name chrome-live --driver existing-session
-openclaw browser --browser-profile chrome-live tabs
-```
-
-This path is host-local. If the Gateway runs elsewhere, either run a node host on the browser machine or use remote CDP instead.
+
+
## Sandboxing and memory
-### Is there a dedicated sandboxing doc
+
+
+ Yes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker).
+
-Yes. See [Sandboxing](/gateway/sandboxing). For Docker-specific setup (full gateway in Docker or sandbox images), see [Docker](/install/docker).
+
+ The default image is security-first and runs as the `node` user, so it does not
+ include system packages, Homebrew, or bundled browsers. For a fuller setup:
-### Docker feels limited How do I enable full features
+ - Persist `/home/node` with `OPENCLAW_HOME_VOLUME` so caches survive.
+ - Bake system deps into the image with `OPENCLAW_DOCKER_APT_PACKAGES`.
+ - Install Playwright browsers via the bundled CLI:
+ `node /app/node_modules/playwright-core/cli.js install chromium`
+ - Set `PLAYWRIGHT_BROWSERS_PATH` and ensure the path is persisted.
-The default image is security-first and runs as the `node` user, so it does not
-include system packages, Homebrew, or bundled browsers. For a fuller setup:
+ Docs: [Docker](/install/docker), [Browser](/tools/browser).
-- Persist `/home/node` with `OPENCLAW_HOME_VOLUME` so caches survive.
-- Bake system deps into the image with `OPENCLAW_DOCKER_APT_PACKAGES`.
-- Install Playwright browsers via the bundled CLI:
- `node /app/node_modules/playwright-core/cli.js install chromium`
-- Set `PLAYWRIGHT_BROWSERS_PATH` and ensure the path is persisted.
+
-Docs: [Docker](/install/docker), [Browser](/tools/browser).
+
+ Yes - if your private traffic is **DMs** and your public traffic is **groups**.
-**Can I keep DMs personal but make groups public sandboxed with one agent**
+ Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`.
-Yes - if your private traffic is **DMs** and your public traffic is **groups**.
+ Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent)
-Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`.
+ Key config reference: [Gateway configuration](/gateway/configuration-reference#agents-defaults-sandbox)
-Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent)
+
-Key config reference: [Gateway configuration](/gateway/configuration-reference#agents-defaults-sandbox)
+
+ Set `agents.defaults.sandbox.docker.binds` to `["host:path:mode"]` (e.g., `"/home/user/src:/src:ro"`). Global + per-agent binds merge; per-agent binds are ignored when `scope: "shared"`. Use `:ro` for anything sensitive and remember binds bypass the sandbox filesystem walls. See [Sandboxing](/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.
+
-### How do I bind a host folder into the sandbox
+
+ OpenClaw memory is just Markdown files in the agent workspace:
-Set `agents.defaults.sandbox.docker.binds` to `["host:path:mode"]` (e.g., `"/home/user/src:/src:ro"`). Global + per-agent binds merge; per-agent binds are ignored when `scope: "shared"`. Use `:ro` for anything sensitive and remember binds bypass the sandbox filesystem walls. See [Sandboxing](/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.
+ - Daily notes in `memory/YYYY-MM-DD.md`
+ - Curated long-term notes in `MEMORY.md` (main/private sessions only)
-### How does memory work
+ OpenClaw also runs a **silent pre-compaction memory flush** to remind the model
+ to write durable notes before auto-compaction. This only runs when the workspace
+ is writable (read-only sandboxes skip it). See [Memory](/concepts/memory).
-OpenClaw memory is just Markdown files in the agent workspace:
+
-- Daily notes in `memory/YYYY-MM-DD.md`
-- Curated long-term notes in `MEMORY.md` (main/private sessions only)
+
+ Ask the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`,
+ short-term context goes into `memory/YYYY-MM-DD.md`.
-OpenClaw also runs a **silent pre-compaction memory flush** to remind the model
-to write durable notes before auto-compaction. This only runs when the workspace
-is writable (read-only sandboxes skip it). See [Memory](/concepts/memory).
+ This is still an area we are improving. It helps to remind the model to store memories;
+ it will know what to do. If it keeps forgetting, verify the Gateway is using the same
+ workspace on every run.
-### Memory keeps forgetting things How do I make it stick
+ Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace).
-Ask the bot to **write the fact to memory**. Long-term notes belong in `MEMORY.md`,
-short-term context goes into `memory/YYYY-MM-DD.md`.
+
-This is still an area we are improving. It helps to remind the model to store memories;
-it will know what to do. If it keeps forgetting, verify the Gateway is using the same
-workspace on every run.
+
+ Memory files live on disk and persist until you delete them. The limit is your
+ storage, not the model. The **session context** is still limited by the model
+ context window, so long conversations can compact or truncate. That is why
+ memory search exists - it pulls only the relevant parts back into context.
-Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace).
+ Docs: [Memory](/concepts/memory), [Context](/concepts/context).
-### Does semantic memory search require an OpenAI API key
+
-Only if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and
-does **not** grant embeddings access, so **signing in with Codex (OAuth or the
-Codex CLI login)** does not help for semantic memory search. OpenAI embeddings
-still need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`).
+
+ Only if you use **OpenAI embeddings**. Codex OAuth covers chat/completions and
+ does **not** grant embeddings access, so **signing in with Codex (OAuth or the
+ Codex CLI login)** does not help for semantic memory search. OpenAI embeddings
+ still need a real API key (`OPENAI_API_KEY` or `models.providers.openai.apiKey`).
-If you don't set a provider explicitly, OpenClaw auto-selects a provider when it
-can resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars).
-It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key
-resolves, then Voyage, then Mistral. If no remote key is available, memory
-search stays disabled until you configure it. If you have a local model path
-configured and present, OpenClaw
-prefers `local`. Ollama is supported when you explicitly set
-`memorySearch.provider = "ollama"`.
+ If you don't set a provider explicitly, OpenClaw auto-selects a provider when it
+ can resolve an API key (auth profiles, `models.providers.*.apiKey`, or env vars).
+ It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key
+ resolves, then Voyage, then Mistral. If no remote key is available, memory
+ search stays disabled until you configure it. If you have a local model path
+ configured and present, OpenClaw
+ prefers `local`. Ollama is supported when you explicitly set
+ `memorySearch.provider = "ollama"`.
-If you'd rather stay local, set `memorySearch.provider = "local"` (and optionally
-`memorySearch.fallback = "none"`). If you want Gemini embeddings, set
-`memorySearch.provider = "gemini"` and provide `GEMINI_API_KEY` (or
-`memorySearch.remote.apiKey`). We support **OpenAI, Gemini, Voyage, Mistral, Ollama, or local** embedding
-models - see [Memory](/concepts/memory) for the setup details.
+ If you'd rather stay local, set `memorySearch.provider = "local"` (and optionally
+ `memorySearch.fallback = "none"`). If you want Gemini embeddings, set
+ `memorySearch.provider = "gemini"` and provide `GEMINI_API_KEY` (or
+ `memorySearch.remote.apiKey`). We support **OpenAI, Gemini, Voyage, Mistral, Ollama, or local** embedding
+ models - see [Memory](/concepts/memory) for the setup details.
-### Does memory persist forever What are the limits
-
-Memory files live on disk and persist until you delete them. The limit is your
-storage, not the model. The **session context** is still limited by the model
-context window, so long conversations can compact or truncate. That is why
-memory search exists - it pulls only the relevant parts back into context.
-
-Docs: [Memory](/concepts/memory), [Context](/concepts/context).
+
+
## Where things live on disk
-### Is all data used with OpenClaw saved locally
+
+
+ No - **OpenClaw's state is local**, but **external services still see what you send them**.
-No - **OpenClaw's state is local**, but **external services still see what you send them**.
+ - **Local by default:** sessions, memory files, config, and workspace live on the Gateway host
+ (`~/.openclaw` + your workspace directory).
+ - **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to
+ their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their
+ servers.
+ - **You control the footprint:** using local models keeps prompts on your machine, but channel
+ traffic still goes through the channel's servers.
-- **Local by default:** sessions, memory files, config, and workspace live on the Gateway host
- (`~/.openclaw` + your workspace directory).
-- **Remote by necessity:** messages you send to model providers (Anthropic/OpenAI/etc.) go to
- their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their
- servers.
-- **You control the footprint:** using local models keeps prompts on your machine, but channel
- traffic still goes through the channel's servers.
+ Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory).
-Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory).
+
-### Where does OpenClaw store its data
+
+ Everything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`):
-Everything lives under `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`):
+ | Path | Purpose |
+ | --------------------------------------------------------------- | ------------------------------------------------------------------ |
+ | `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) |
+ | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) |
+ | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys, and optional `keyRef`/`tokenRef`) |
+ | `$OPENCLAW_STATE_DIR/secrets.json` | Optional file-backed secret payload for `file` SecretRef providers |
+ | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) |
+ | `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) |
+ | `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) |
+ | `$OPENCLAW_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) |
+ | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) |
-| Path | Purpose |
-| --------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `$OPENCLAW_STATE_DIR/openclaw.json` | Main config (JSON5) |
-| `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (copied into auth profiles on first use) |
-| `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys, and optional `keyRef`/`tokenRef`) |
-| `$OPENCLAW_STATE_DIR/secrets.json` | Optional file-backed secret payload for `file` SecretRef providers |
-| `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy compatibility file (static `api_key` entries scrubbed) |
-| `$OPENCLAW_STATE_DIR/credentials/` | Provider state (e.g. `whatsapp//creds.json`) |
-| `$OPENCLAW_STATE_DIR/agents/` | Per-agent state (agentDir + sessions) |
-| `$OPENCLAW_STATE_DIR/agents//sessions/` | Conversation history & state (per agent) |
-| `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session metadata (per agent) |
+ Legacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`).
-Legacy single-agent path: `~/.openclaw/agent/*` (migrated by `openclaw doctor`).
+ Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/.openclaw/workspace`).
-Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/.openclaw/workspace`).
+
-### Where should AGENTSmd SOULmd USERmd MEMORYmd live
+
+ These files live in the **agent workspace**, not `~/.openclaw`.
-These files live in the **agent workspace**, not `~/.openclaw`.
+ - **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`,
+ `MEMORY.md` (or legacy fallback `memory.md` when `MEMORY.md` is absent),
+ `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`.
+ - **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs,
+ and shared skills (`~/.openclaw/skills`).
-- **Workspace (per agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`,
- `MEMORY.md` (or legacy fallback `memory.md` when `MEMORY.md` is absent),
- `memory/YYYY-MM-DD.md`, optional `HEARTBEAT.md`.
-- **State dir (`~/.openclaw`)**: config, credentials, auth profiles, sessions, logs,
- and shared skills (`~/.openclaw/skills`).
+ Default workspace is `~/.openclaw/workspace`, configurable via:
-Default workspace is `~/.openclaw/workspace`, configurable via:
+ ```json5
+ {
+ agents: { defaults: { workspace: "~/.openclaw/workspace" } },
+ }
+ ```
-```json5
-{
- agents: { defaults: { workspace: "~/.openclaw/workspace" } },
-}
-```
+ If the bot "forgets" after a restart, confirm the Gateway is using the same
+ workspace on every launch (and remember: remote mode uses the **gateway host's**
+ workspace, not your local laptop).
-If the bot "forgets" after a restart, confirm the Gateway is using the same
-workspace on every launch (and remember: remote mode uses the **gateway host's**
-workspace, not your local laptop).
+ Tip: if you want a durable behavior or preference, ask the bot to **write it into
+ AGENTS.md or MEMORY.md** rather than relying on chat history.
-Tip: if you want a durable behavior or preference, ask the bot to **write it into
-AGENTS.md or MEMORY.md** rather than relying on chat history.
+ See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).
-See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory).
+
-### Recommended backup strategy
+
+ Put your **agent workspace** in a **private** git repo and back it up somewhere
+ private (for example GitHub private). This captures memory + AGENTS/SOUL/USER
+ files, and lets you restore the assistant's "mind" later.
-Put your **agent workspace** in a **private** git repo and back it up somewhere
-private (for example GitHub private). This captures memory + AGENTS/SOUL/USER
-files, and lets you restore the assistant's "mind" later.
+ Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens, or encrypted secrets payloads).
+ If you need a full restore, back up both the workspace and the state directory
+ separately (see the migration question above).
-Do **not** commit anything under `~/.openclaw` (credentials, sessions, tokens, or encrypted secrets payloads).
-If you need a full restore, back up both the workspace and the state directory
-separately (see the migration question above).
+ Docs: [Agent workspace](/concepts/agent-workspace).
-Docs: [Agent workspace](/concepts/agent-workspace).
+
-### How do I completely uninstall OpenClaw
+
+ See the dedicated guide: [Uninstall](/install/uninstall).
+
-See the dedicated guide: [Uninstall](/install/uninstall).
+
+ Yes. The workspace is the **default cwd** and memory anchor, not a hard sandbox.
+ Relative paths resolve inside the workspace, but absolute paths can access other
+ host locations unless sandboxing is enabled. If you need isolation, use
+ [`agents.defaults.sandbox`](/gateway/sandboxing) or per-agent sandbox settings. If you
+ want a repo to be the default working directory, point that agent's
+ `workspace` to the repo root. The OpenClaw repo is just source code; keep the
+ workspace separate unless you intentionally want the agent to work inside it.
-### Can agents work outside the workspace
+ Example (repo as default cwd):
-Yes. The workspace is the **default cwd** and memory anchor, not a hard sandbox.
-Relative paths resolve inside the workspace, but absolute paths can access other
-host locations unless sandboxing is enabled. If you need isolation, use
-[`agents.defaults.sandbox`](/gateway/sandboxing) or per-agent sandbox settings. If you
-want a repo to be the default working directory, point that agent's
-`workspace` to the repo root. The OpenClaw repo is just source code; keep the
-workspace separate unless you intentionally want the agent to work inside it.
+ ```json5
+ {
+ agents: {
+ defaults: {
+ workspace: "~/Projects/my-repo",
+ },
+ },
+ }
+ ```
-Example (repo as default cwd):
+
-```json5
-{
- agents: {
- defaults: {
- workspace: "~/Projects/my-repo",
- },
- },
-}
-```
-
-### Im in remote mode where is the session store
-
-Session 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).
+
+ Session 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).
+
+
## Config basics
-### What format is the config Where is it
+
+
+ OpenClaw reads an optional **JSON5** config from `$OPENCLAW_CONFIG_PATH` (default: `~/.openclaw/openclaw.json`):
-OpenClaw reads an optional **JSON5** config from `$OPENCLAW_CONFIG_PATH` (default: `~/.openclaw/openclaw.json`):
+ ```
+ $OPENCLAW_CONFIG_PATH
+ ```
-```
-$OPENCLAW_CONFIG_PATH
-```
+ If the file is missing, it uses safe-ish defaults (including a default workspace of `~/.openclaw/workspace`).
-If the file is missing, it uses safe-ish defaults (including a default workspace of `~/.openclaw/workspace`).
+
-### I set gatewaybind lan or tailnet and now nothing listens the UI says unauthorized
+
+ Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`).
-Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `OPENCLAW_GATEWAY_TOKEN`).
+ ```json5
+ {
+ gateway: {
+ bind: "lan",
+ auth: {
+ mode: "token",
+ token: "replace-me",
+ },
+ },
+ }
+ ```
-```json5
-{
- gateway: {
- bind: "lan",
- auth: {
- mode: "token",
- token: "replace-me",
- },
- },
-}
-```
+ Notes:
-Notes:
+ - `gateway.remote.token` / `.password` do **not** enable local gateway auth by themselves.
+ - Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset.
+ - If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
+ - The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs.
-- `gateway.remote.token` / `.password` do **not** enable local gateway auth by themselves.
-- Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset.
-- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
-- The Control UI authenticates via `connect.params.auth.token` (stored in app/UI settings). Avoid putting tokens in URLs.
+
-### Why do I need a token on localhost now
+
+ OpenClaw enforces token auth by default, including loopback. If no token is configured, gateway startup auto-generates one and saves it to `gateway.auth.token`, so **local WS clients must authenticate**. This blocks other local processes from calling the Gateway.
-OpenClaw enforces token auth by default, including loopback. If no token is configured, gateway startup auto-generates one and saves it to `gateway.auth.token`, so **local WS clients must authenticate**. This blocks other local processes from calling the Gateway.
+ If you **really** want open loopback, set `gateway.auth.mode: "none"` explicitly in your config. Doctor can generate a token for you any time: `openclaw doctor --generate-gateway-token`.
-If you **really** want open loopback, set `gateway.auth.mode: "none"` explicitly in your config. Doctor can generate a token for you any time: `openclaw doctor --generate-gateway-token`.
+
-### Do I have to restart after changing config
+
+ The Gateway watches the config and supports hot-reload:
-The Gateway watches the config and supports hot-reload:
+ - `gateway.reload.mode: "hybrid"` (default): hot-apply safe changes, restart for critical ones
+ - `hot`, `restart`, `off` are also supported
-- `gateway.reload.mode: "hybrid"` (default): hot-apply safe changes, restart for critical ones
-- `hot`, `restart`, `off` are also supported
+
-### How do I disable funny CLI taglines
+
+ Set `cli.banner.taglineMode` in config:
-Set `cli.banner.taglineMode` in config:
+ ```json5
+ {
+ cli: {
+ banner: {
+ taglineMode: "off", // random | default | off
+ },
+ },
+ }
+ ```
-```json5
-{
- cli: {
- banner: {
- taglineMode: "off", // random | default | off
- },
- },
-}
-```
+ - `off`: hides tagline text but keeps the banner title/version line.
+ - `default`: uses `All your chats, one OpenClaw.` every time.
+ - `random`: rotating funny/seasonal taglines (default behavior).
+ - If you want no banner at all, set env `OPENCLAW_HIDE_BANNER=1`.
-- `off`: hides tagline text but keeps the banner title/version line.
-- `default`: uses `All your chats, one OpenClaw.` every time.
-- `random`: rotating funny/seasonal taglines (default behavior).
-- If you want no banner at all, set env `OPENCLAW_HIDE_BANNER=1`.
+
-### How do I enable web search and web fetch
+
+ `web_fetch` works without an API key. `web_search` requires a key for your
+ selected provider (Brave, Gemini, Grok, Kimi, or Perplexity).
+ **Recommended:** run `openclaw configure --section web` and choose a provider.
+ Environment alternatives:
-`web_fetch` works without an API key. `web_search` requires a key for your
-selected provider (Brave, Gemini, Grok, Kimi, or Perplexity).
-**Recommended:** run `openclaw configure --section web` and choose a provider.
-Environment alternatives:
+ - Brave: `BRAVE_API_KEY`
+ - Gemini: `GEMINI_API_KEY`
+ - Grok: `XAI_API_KEY`
+ - Kimi: `KIMI_API_KEY` or `MOONSHOT_API_KEY`
+ - Perplexity: `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
-- Brave: `BRAVE_API_KEY`
-- Gemini: `GEMINI_API_KEY`
-- Grok: `XAI_API_KEY`
-- Kimi: `KIMI_API_KEY` or `MOONSHOT_API_KEY`
-- Perplexity: `PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
-
-```json5
-{
- plugins: {
- entries: {
- brave: {
- config: {
- webSearch: {
- apiKey: "BRAVE_API_KEY_HERE",
+ ```json5
+ {
+ plugins: {
+ entries: {
+ brave: {
+ config: {
+ webSearch: {
+ apiKey: "BRAVE_API_KEY_HERE",
+ },
+ },
},
},
},
- },
- },
- tools: {
- web: {
- search: {
- enabled: true,
- provider: "brave",
- maxResults: 5,
+ tools: {
+ web: {
+ search: {
+ enabled: true,
+ provider: "brave",
+ maxResults: 5,
+ },
+ fetch: {
+ enabled: true,
+ },
+ },
},
- fetch: {
- enabled: true,
+ }
+ ```
+
+ Provider-specific web-search config now lives under `plugins.entries..config.webSearch.*`.
+ Legacy `tools.web.search.*` provider paths still load temporarily for compatibility, but they should not be used for new configs.
+
+ Notes:
+
+ - If you use allowlists, add `web_search`/`web_fetch` or `group:web`.
+ - `web_fetch` is enabled by default (unless explicitly disabled).
+ - Daemons read env vars from `~/.openclaw/.env` (or the service environment).
+
+ Docs: [Web tools](/tools/web).
+
+
+
+
+ `config.apply` replaces the **entire config**. If you send a partial object, everything
+ else is removed.
+
+ Recover:
+
+ - Restore from backup (git or a copied `~/.openclaw/openclaw.json`).
+ - If you have no backup, re-run `openclaw doctor` and reconfigure channels/models.
+ - If this was unexpected, file a bug and include your last known config or any backup.
+ - A local coding agent can often reconstruct a working config from logs or history.
+
+ Avoid it:
+
+ - Use `openclaw config set` for small changes.
+ - Use `openclaw configure` for interactive edits.
+
+ Docs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor).
+
+
+
+
+ The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**:
+
+ - **Gateway (central):** owns channels (Signal/WhatsApp), routing, and sessions.
+ - **Nodes (devices):** Macs/iOS/Android connect as peripherals and expose local tools (`system.run`, `canvas`, `camera`).
+ - **Agents (workers):** separate brains/workspaces for special roles (e.g. "Hetzner ops", "Personal data").
+ - **Sub-agents:** spawn background work from a main agent when you want parallelism.
+ - **TUI:** connect to the Gateway and switch agents/sessions.
+
+ Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui).
+
+
+
+
+ Yes. It's a config option:
+
+ ```json5
+ {
+ browser: { headless: true },
+ agents: {
+ defaults: {
+ sandbox: { browser: { headless: true } },
+ },
},
- },
- },
-}
-```
+ }
+ ```
-Provider-specific web-search config now lives under `plugins.entries..config.webSearch.*`.
-Legacy `tools.web.search.*` provider paths still load temporarily for compatibility, but they should not be used for new configs.
+ Default is `false` (headful). Headless is more likely to trigger anti-bot checks on some sites. See [Browser](/tools/browser).
-Notes:
+ Headless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences:
-- If you use allowlists, add `web_search`/`web_fetch` or `group:web`.
-- `web_fetch` is enabled by default (unless explicitly disabled).
-- Daemons read env vars from `~/.openclaw/.env` (or the service environment).
+ - No visible browser window (use screenshots if you need visuals).
+ - Some sites are stricter about automation in headless mode (CAPTCHAs, anti-bot).
+ For example, X/Twitter often blocks headless sessions.
-Docs: [Web tools](/tools/web).
+
-### How do I run a central Gateway with specialized workers across devices
-
-The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **agents**:
-
-- **Gateway (central):** owns channels (Signal/WhatsApp), routing, and sessions.
-- **Nodes (devices):** Macs/iOS/Android connect as peripherals and expose local tools (`system.run`, `canvas`, `camera`).
-- **Agents (workers):** separate brains/workspaces for special roles (e.g. "Hetzner ops", "Personal data").
-- **Sub-agents:** spawn background work from a main agent when you want parallelism.
-- **TUI:** connect to the Gateway and switch agents/sessions.
-
-Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/web/tui).
-
-### Can the OpenClaw browser run headless
-
-Yes. It's a config option:
-
-```json5
-{
- browser: { headless: true },
- agents: {
- defaults: {
- sandbox: { browser: { headless: true } },
- },
- },
-}
-```
-
-Default is `false` (headful). Headless is more likely to trigger anti-bot checks on some sites. See [Browser](/tools/browser).
-
-Headless uses the **same Chromium engine** and works for most automation (forms, clicks, scraping, logins). The main differences:
-
-- No visible browser window (use screenshots if you need visuals).
-- Some sites are stricter about automation in headless mode (CAPTCHAs, anti-bot).
- For example, X/Twitter often blocks headless sessions.
-
-### How do I use Brave for browser control
-
-Set `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway.
-See the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser).
+
+ Set `browser.executablePath` to your Brave binary (or any Chromium-based browser) and restart the Gateway.
+ See the full config examples in [Browser](/tools/browser#use-brave-or-another-chromium-based-browser).
+
+
## Remote gateways and nodes
-### How do commands propagate between Telegram the gateway and nodes
+
+
+ Telegram messages are handled by the **gateway**. The gateway runs the agent and
+ only then calls nodes over the **Gateway WebSocket** when a node tool is needed:
-Telegram messages are handled by the **gateway**. The gateway runs the agent and
-only then calls nodes over the **Gateway WebSocket** when a node tool is needed:
+ Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram
-Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram
+ Nodes don't see inbound provider traffic; they only receive node RPC calls.
-Nodes don't see inbound provider traffic; they only receive node RPC calls.
+
-### How can my agent access my computer if the Gateway is hosted remotely
+
+ Short answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can
+ call `node.*` tools (screen, camera, system) on your local machine over the Gateway WebSocket.
-Short answer: **pair your computer as a node**. The Gateway runs elsewhere, but it can
-call `node.*` tools (screen, camera, system) on your local machine over the Gateway WebSocket.
+ Typical setup:
-Typical setup:
+ 1. Run the Gateway on the always-on host (VPS/home server).
+ 2. Put the Gateway host + your computer on the same tailnet.
+ 3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).
+ 4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet)
+ so it can register as a node.
+ 5. Approve the node on the Gateway:
-1. Run the Gateway on the always-on host (VPS/home server).
-2. Put the Gateway host + your computer on the same tailnet.
-3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).
-4. Open the macOS app locally and connect in **Remote over SSH** mode (or direct tailnet)
- so it can register as a node.
-5. Approve the node on the Gateway:
+ ```bash
+ openclaw devices list
+ openclaw devices approve
+ ```
- ```bash
- openclaw devices list
- openclaw devices approve
- ```
+ No separate TCP bridge is required; nodes connect over the Gateway WebSocket.
-No separate TCP bridge is required; nodes connect over the Gateway WebSocket.
+ Security reminder: pairing a macOS node allows `system.run` on that machine. Only
+ pair devices you trust, and review [Security](/gateway/security).
-Security reminder: pairing a macOS node allows `system.run` on that machine. Only
-pair devices you trust, and review [Security](/gateway/security).
+ Docs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security).
-Docs: [Nodes](/nodes), [Gateway protocol](/gateway/protocol), [macOS remote mode](/platforms/mac/remote), [Security](/gateway/security).
+
-### Tailscale is connected but I get no replies What now
+
+ Check the basics:
-Check the basics:
+ - Gateway is running: `openclaw gateway status`
+ - Gateway health: `openclaw status`
+ - Channel health: `openclaw channels status`
-- Gateway is running: `openclaw gateway status`
-- Gateway health: `openclaw status`
-- Channel health: `openclaw channels status`
+ Then verify auth and routing:
-Then verify auth and routing:
+ - If you use Tailscale Serve, make sure `gateway.auth.allowTailscale` is set correctly.
+ - If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port.
+ - Confirm your allowlists (DM or group) include your account.
-- If you use Tailscale Serve, make sure `gateway.auth.allowTailscale` is set correctly.
-- If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port.
-- Confirm your allowlists (DM or group) include your account.
+ Docs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels).
-Docs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels).
+
-### Can two OpenClaw instances talk to each other local VPS
+
+ Yes. There is no built-in "bot-to-bot" bridge, but you can wire it up in a few
+ reliable ways:
-Yes. There is no built-in "bot-to-bot" bridge, but you can wire it up in a few
-reliable ways:
+ **Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp).
+ Have Bot A send a message to Bot B, then let Bot B reply as usual.
-**Simplest:** use a normal chat channel both bots can access (Telegram/Slack/WhatsApp).
-Have Bot A send a message to Bot B, then let Bot B reply as usual.
+ **CLI bridge (generic):** run a script that calls the other Gateway with
+ `openclaw agent --message ... --deliver`, targeting a chat where the other bot
+ listens. If one bot is on a remote VPS, point your CLI at that remote Gateway
+ via SSH/Tailscale (see [Remote access](/gateway/remote)).
-**CLI bridge (generic):** run a script that calls the other Gateway with
-`openclaw agent --message ... --deliver`, targeting a chat where the other bot
-listens. If one bot is on a remote VPS, point your CLI at that remote Gateway
-via SSH/Tailscale (see [Remote access](/gateway/remote)).
+ Example pattern (run from a machine that can reach the target Gateway):
-Example pattern (run from a machine that can reach the target Gateway):
+ ```bash
+ openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to
+ ```
-```bash
-openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to
-```
+ Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel
+ allowlists, or a "do not reply to bot messages" rule).
-Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel
-allowlists, or a "do not reply to bot messages" rule).
+ Docs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send).
-Docs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send).
+
-### Do I need separate VPSes for multiple agents
+
+ No. One Gateway can host multiple agents, each with its own workspace, model defaults,
+ and routing. That is the normal setup and it is much cheaper and simpler than running
+ one VPS per agent.
-No. One Gateway can host multiple agents, each with its own workspace, model defaults,
-and routing. That is the normal setup and it is much cheaper and simpler than running
-one VPS per agent.
+ Use separate VPSes only when you need hard isolation (security boundaries) or very
+ different configs that you do not want to share. Otherwise, keep one Gateway and
+ use multiple agents or sub-agents.
-Use separate VPSes only when you need hard isolation (security boundaries) or very
-different configs that you do not want to share. Otherwise, keep one Gateway and
-use multiple agents or sub-agents.
+
-### Is there a benefit to using a node on my personal laptop instead of SSH from a VPS
+
+ Yes - nodes are the first-class way to reach your laptop from a remote Gateway, and they
+ unlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is
+ lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common
+ setup is an always-on host plus your laptop as a node.
-Yes - nodes are the first-class way to reach your laptop from a remote Gateway, and they
-unlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is
-lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common
-setup is an always-on host plus your laptop as a node.
+ - **No inbound SSH required.** Nodes connect out to the Gateway WebSocket and use device pairing.
+ - **Safer execution controls.** `system.run` is gated by node allowlists/approvals on that laptop.
+ - **More device tools.** Nodes expose `canvas`, `camera`, and `screen` in addition to `system.run`.
+ - **Local browser automation.** Keep the Gateway on a VPS, but run Chrome locally through a node host on the laptop, or attach to local Chrome on the host via Chrome MCP.
-- **No inbound SSH required.** Nodes connect out to the Gateway WebSocket and use device pairing.
-- **Safer execution controls.** `system.run` is gated by node allowlists/approvals on that laptop.
-- **More device tools.** Nodes expose `canvas`, `camera`, and `screen` in addition to `system.run`.
-- **Local browser automation.** Keep the Gateway on a VPS, but run Chrome locally through a node host on the laptop, or attach to local Chrome on the host via Chrome MCP.
+ SSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and
+ device automation.
-SSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and
-device automation.
+ Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Browser](/tools/browser).
-Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Browser](/tools/browser).
+
-### Should I install on a second laptop or just add a node
+
+ No. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect
+ to the gateway (iOS/Android nodes, or macOS "node mode" in the menubar app). For headless node
+ hosts and CLI control, see [Node host CLI](/cli/node).
-If you only need **local tools** (screen/camera/exec) on the second laptop, add it as a
-**node**. That keeps a single Gateway and avoids duplicated config. Local node tools are
-currently macOS-only, but we plan to extend them to other OSes.
+ A full restart is required for `gateway`, `discovery`, and `canvasHost` changes.
-Install a second Gateway only when you need **hard isolation** or two fully separate bots.
+
-Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways).
+
+ Yes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation.
+
-### Do nodes run a gateway service
+
+ ```json5
+ {
+ agents: { defaults: { workspace: "~/.openclaw/workspace" } },
+ channels: { whatsapp: { allowFrom: ["+15555550123"] } },
+ }
+ ```
-No. Only **one gateway** should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)). Nodes are peripherals that connect
-to the gateway (iOS/Android nodes, or macOS "node mode" in the menubar app). For headless node
-hosts and CLI control, see [Node host CLI](/cli/node).
+ This sets your workspace and restricts who can trigger the bot.
-A full restart is required for `gateway`, `discovery`, and `canvasHost` changes.
+
-### Is there an API RPC way to apply config
+
+ Minimal steps:
-Yes. `config.apply` validates + writes the full config and restarts the Gateway as part of the operation.
+ 1. **Install + login on the VPS**
-### configapply wiped my config How do I recover and avoid this
+ ```bash
+ curl -fsSL https://tailscale.com/install.sh | sh
+ sudo tailscale up
+ ```
-`config.apply` replaces the **entire config**. If you send a partial object, everything
-else is removed.
+ 2. **Install + login on your Mac**
+ - Use the Tailscale app and sign in to the same tailnet.
+ 3. **Enable MagicDNS (recommended)**
+ - In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.
+ 4. **Use the tailnet hostname**
+ - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`
+ - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`
-Recover:
+ If you want the Control UI without SSH, use Tailscale Serve on the VPS:
-- Restore from backup (git or a copied `~/.openclaw/openclaw.json`).
-- If you have no backup, re-run `openclaw doctor` and reconfigure channels/models.
-- If this was unexpected, file a bug and include your last known config or any backup.
-- A local coding agent can often reconstruct a working config from logs or history.
+ ```bash
+ openclaw gateway --tailscale serve
+ ```
-Avoid it:
+ This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale).
-- Use `openclaw config set` for small changes.
-- Use `openclaw configure` for interactive edits.
+
-Docs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor).
+
+ Serve exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint.
-### Minimal sane config for a first install
+ Recommended setup:
-```json5
-{
- agents: { defaults: { workspace: "~/.openclaw/workspace" } },
- channels: { whatsapp: { allowFrom: ["+15555550123"] } },
-}
-```
+ 1. **Make sure the VPS + Mac are on the same tailnet**.
+ 2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).
+ The app will tunnel the Gateway port and connect as a node.
+ 3. **Approve the node** on the gateway:
-This sets your workspace and restricts who can trigger the bot.
+ ```bash
+ openclaw devices list
+ openclaw devices approve
+ ```
-### How do I set up Tailscale on a VPS and connect from my Mac
+ Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote).
-Minimal steps:
+
-1. **Install + login on the VPS**
+
+ If you only need **local tools** (screen/camera/exec) on the second laptop, add it as a
+ **node**. That keeps a single Gateway and avoids duplicated config. Local node tools are
+ currently macOS-only, but we plan to extend them to other OSes.
- ```bash
- curl -fsSL https://tailscale.com/install.sh | sh
- sudo tailscale up
- ```
+ Install a second Gateway only when you need **hard isolation** or two fully separate bots.
-2. **Install + login on your Mac**
- - Use the Tailscale app and sign in to the same tailnet.
-3. **Enable MagicDNS (recommended)**
- - In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.
-4. **Use the tailnet hostname**
- - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net`
- - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789`
+ Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways).
-If you want the Control UI without SSH, use Tailscale Serve on the VPS:
-
-```bash
-openclaw gateway --tailscale serve
-```
-
-This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See [Tailscale](/gateway/tailscale).
-
-### How do I connect a Mac node to a remote Gateway Tailscale Serve
-
-Serve exposes the **Gateway Control UI + WS**. Nodes connect over the same Gateway WS endpoint.
-
-Recommended setup:
-
-1. **Make sure the VPS + Mac are on the same tailnet**.
-2. **Use the macOS app in Remote mode** (SSH target can be the tailnet hostname).
- The app will tunnel the Gateway port and connect as a node.
-3. **Approve the node** on the gateway:
-
- ```bash
- openclaw devices list
- openclaw devices approve
- ```
-
-Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [macOS remote mode](/platforms/mac/remote).
+
+
## Env vars and .env loading
-### How does OpenClaw load environment variables
+
+
+ OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:
-OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:
+ - `.env` from the current working directory
+ - a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`)
-- `.env` from the current working directory
-- a global fallback `.env` from `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`)
+ Neither `.env` file overrides existing env vars.
-Neither `.env` file overrides existing env vars.
+ You can also define inline env vars in config (applied only if missing from the process env):
-You can also define inline env vars in config (applied only if missing from the process env):
+ ```json5
+ {
+ env: {
+ OPENROUTER_API_KEY: "sk-or-...",
+ vars: { GROQ_API_KEY: "gsk-..." },
+ },
+ }
+ ```
-```json5
-{
- env: {
- OPENROUTER_API_KEY: "sk-or-...",
- vars: { GROQ_API_KEY: "gsk-..." },
- },
-}
-```
+ See [/environment](/help/environment) for full precedence and sources.
-See [/environment](/help/environment) for full precedence and sources.
+
-### I started the Gateway via the service and my env vars disappeared What now
+
+ Two common fixes:
-Two common fixes:
+ 1. Put the missing keys in `~/.openclaw/.env` so they're picked up even when the service doesn't inherit your shell env.
+ 2. Enable shell import (opt-in convenience):
-1. Put the missing keys in `~/.openclaw/.env` so they're picked up even when the service doesn't inherit your shell env.
-2. Enable shell import (opt-in convenience):
+ ```json5
+ {
+ env: {
+ shellEnv: {
+ enabled: true,
+ timeoutMs: 15000,
+ },
+ },
+ }
+ ```
-```json5
-{
- env: {
- shellEnv: {
- enabled: true,
- timeoutMs: 15000,
- },
- },
-}
-```
+ This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
+ `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`.
-This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
-`OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`.
+
-### I set COPILOTGITHUBTOKEN but models status shows Shell env off Why
+
+ `openclaw models status` reports whether **shell env import** is enabled. "Shell env: off"
+ does **not** mean your env vars are missing - it just means OpenClaw won't load
+ your login shell automatically.
-`openclaw models status` reports whether **shell env import** is enabled. "Shell env: off"
-does **not** mean your env vars are missing - it just means OpenClaw won't load
-your login shell automatically.
+ If the Gateway runs as a service (launchd/systemd), it won't inherit your shell
+ environment. Fix by doing one of these:
-If the Gateway runs as a service (launchd/systemd), it won't inherit your shell
-environment. Fix by doing one of these:
+ 1. Put the token in `~/.openclaw/.env`:
-1. Put the token in `~/.openclaw/.env`:
+ ```
+ COPILOT_GITHUB_TOKEN=...
+ ```
- ```
- COPILOT_GITHUB_TOKEN=...
- ```
+ 2. Or enable shell import (`env.shellEnv.enabled: true`).
+ 3. Or add it to your config `env` block (applies only if missing).
-2. Or enable shell import (`env.shellEnv.enabled: true`).
-3. Or add it to your config `env` block (applies only if missing).
+ Then restart the gateway and recheck:
-Then restart the gateway and recheck:
+ ```bash
+ openclaw models status
+ ```
-```bash
-openclaw models status
-```
+ Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
+ See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment).
-Copilot tokens are read from `COPILOT_GITHUB_TOKEN` (also `GH_TOKEN` / `GITHUB_TOKEN`).
-See [/concepts/model-providers](/concepts/model-providers) and [/environment](/help/environment).
+
+
## Sessions and multiple chats
-### How do I start a fresh conversation
+
+
+ Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).
+
-Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session).
+
+ Yes. Sessions expire after `session.idleMinutes` (default **60**). The **next**
+ message starts a fresh session id for that chat key. This does not delete
+ transcripts - it just starts a new session.
-### Do sessions reset automatically if I never send new
-
-Yes. Sessions expire after `session.idleMinutes` (default **60**). The **next**
-message starts a fresh session id for that chat key. This does not delete
-transcripts - it just starts a new session.
-
-```json5
-{
- session: {
- idleMinutes: 240,
- },
-}
-```
-
-### Is there a way to make a team of OpenClaw instances one CEO and many agents
-
-Yes, via **multi-agent routing** and **sub-agents**. You can create one coordinator
-agent and several worker agents with their own workspaces and models.
-
-That said, this is best seen as a **fun experiment**. It is token heavy and often
-less efficient than using one bot with separate sessions. The typical model we
-envision is one bot you talk to, with different sessions for parallel work. That
-bot can also spawn sub-agents when needed.
-
-Docs: [Multi-agent routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [Agents CLI](/cli/agents).
-
-### Why did context get truncated midtask How do I prevent it
-
-Session context is limited by the model window. Long chats, large tool outputs, or many
-files can trigger compaction or truncation.
-
-What helps:
-
-- Ask the bot to summarize the current state and write it to a file.
-- Use `/compact` before long tasks, and `/new` when switching topics.
-- Keep important context in the workspace and ask the bot to read it back.
-- Use sub-agents for long or parallel work so the main chat stays smaller.
-- Pick a model with a larger context window if this happens often.
-
-### How do I completely reset OpenClaw but keep it installed
-
-Use the reset command:
-
-```bash
-openclaw reset
-```
-
-Non-interactive full reset:
-
-```bash
-openclaw reset --scope full --yes --non-interactive
-```
-
-Then re-run setup:
-
-```bash
-openclaw onboard --install-daemon
-```
-
-Notes:
-
-- Onboarding also offers **Reset** if it sees an existing config. See [Onboarding (CLI)](/start/wizard).
-- If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-`).
-- Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).
-
-### Im getting context too large errors how do I reset or compact
-
-Use one of these:
-
-- **Compact** (keeps the conversation but summarizes older turns):
-
- ```
- /compact
- ```
-
- or `/compact ` to guide the summary.
-
-- **Reset** (fresh session ID for the same chat key):
-
- ```
- /new
- /reset
- ```
-
-If it keeps happening:
-
-- Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output.
-- Use a model with a larger context window.
-
-Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session).
-
-### Why am I seeing "LLM request rejected: messages.content.tool_use.input field required"?
-
-This is a provider validation error: the model emitted a `tool_use` block without the required
-`input`. It usually means the session history is stale or corrupted (often after long threads
-or a tool/schema change).
-
-Fix: start a fresh session with `/new` (standalone message).
-
-### Why am I getting heartbeat messages every 30 minutes
-
-Heartbeats run every **30m** by default. Tune or disable them:
-
-```json5
-{
- agents: {
- defaults: {
- heartbeat: {
- every: "2h", // or "0m" to disable
+ ```json5
+ {
+ session: {
+ idleMinutes: 240,
},
- },
- },
-}
-```
+ }
+ ```
-If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
-headers like `# Heading`), OpenClaw skips the heartbeat run to save API calls.
-If the file is missing, the heartbeat still runs and the model decides what to do.
+
-Per-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat).
+
+ Yes, via **multi-agent routing** and **sub-agents**. You can create one coordinator
+ agent and several worker agents with their own workspaces and models.
-### Do I need to add a bot account to a WhatsApp group
+ That said, this is best seen as a **fun experiment**. It is token heavy and often
+ less efficient than using one bot with separate sessions. The typical model we
+ envision is one bot you talk to, with different sessions for parallel work. That
+ bot can also spawn sub-agents when needed.
-No. OpenClaw runs on **your own account**, so if you're in the group, OpenClaw can see it.
-By default, group replies are blocked until you allow senders (`groupPolicy: "allowlist"`).
+ Docs: [Multi-agent routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [Agents CLI](/cli/agents).
-If you want only **you** to be able to trigger group replies:
+
-```json5
-{
- channels: {
- whatsapp: {
- groupPolicy: "allowlist",
- groupAllowFrom: ["+15551234567"],
- },
- },
-}
-```
+
+ Session context is limited by the model window. Long chats, large tool outputs, or many
+ files can trigger compaction or truncation.
-### How do I get the JID of a WhatsApp group
+ What helps:
-Option 1 (fastest): tail logs and send a test message in the group:
+ - Ask the bot to summarize the current state and write it to a file.
+ - Use `/compact` before long tasks, and `/new` when switching topics.
+ - Keep important context in the workspace and ask the bot to read it back.
+ - Use sub-agents for long or parallel work so the main chat stays smaller.
+ - Pick a model with a larger context window if this happens often.
-```bash
-openclaw logs --follow --json
-```
+
-Look for `chatId` (or `from`) ending in `@g.us`, like:
-`1234567890-1234567890@g.us`.
+
+ Use the reset command:
-Option 2 (if already configured/allowlisted): list groups from config:
+ ```bash
+ openclaw reset
+ ```
-```bash
-openclaw directory groups list --channel whatsapp
-```
+ Non-interactive full reset:
-Docs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs).
+ ```bash
+ openclaw reset --scope full --yes --non-interactive
+ ```
-### Why does OpenClaw not reply in a group
+ Then re-run setup:
-Two common causes:
+ ```bash
+ openclaw onboard --install-daemon
+ ```
-- Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).
-- You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted.
+ Notes:
-See [Groups](/channels/groups) and [Group messages](/channels/group-messages).
+ - Onboarding also offers **Reset** if it sees an existing config. See [Onboarding (CLI)](/start/wizard).
+ - If you used profiles (`--profile` / `OPENCLAW_PROFILE`), reset each state dir (defaults are `~/.openclaw-`).
+ - Dev reset: `openclaw gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace).
-### Do groups/threads share context with DMs
+
-Direct 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](/channels/groups) and [Group messages](/channels/group-messages).
+
+ Use one of these:
-### How many workspaces and agents can I create
+ - **Compact** (keeps the conversation but summarizes older turns):
-No hard limits. Dozens (even hundreds) are fine, but watch for:
+ ```
+ /compact
+ ```
-- **Disk growth:** sessions + transcripts live under `~/.openclaw/agents//sessions/`.
-- **Token cost:** more agents means more concurrent model usage.
-- **Ops overhead:** per-agent auth profiles, workspaces, and channel routing.
+ or `/compact ` to guide the summary.
-Tips:
+ - **Reset** (fresh session ID for the same chat key):
-- Keep one **active** workspace per agent (`agents.defaults.workspace`).
-- Prune old sessions (delete JSONL or store entries) if disk grows.
-- Use `openclaw doctor` to spot stray workspaces and profile mismatches.
+ ```
+ /new
+ /reset
+ ```
-### Can I run multiple bots or chats at the same time Slack and how should I set that up
+ If it keeps happening:
-Yes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbound messages by
-channel/account/peer. Slack is supported as a channel and can be bound to specific agents.
+ - Enable or tune **session pruning** (`agents.defaults.contextPruning`) to trim old tool output.
+ - Use a model with a larger context window.
-Browser access is powerful but not "do anything a human can" - anti-bot, CAPTCHAs, and MFA can
-still block automation. For the most reliable browser control, use local Chrome MCP on the host,
-or use CDP on the machine that actually runs the browser.
+ Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session).
-Best-practice setup:
+
-- Always-on Gateway host (VPS/Mac mini).
-- One agent per role (bindings).
-- Slack channel(s) bound to those agents.
-- Local browser via Chrome MCP or a node when needed.
+
+ This is a provider validation error: the model emitted a `tool_use` block without the required
+ `input`. It usually means the session history is stale or corrupted (often after long threads
+ or a tool/schema change).
-Docs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack),
-[Browser](/tools/browser), [Nodes](/nodes).
+ Fix: start a fresh session with `/new` (standalone message).
+
+
+
+
+ Heartbeats run every **30m** by default. Tune or disable them:
+
+ ```json5
+ {
+ agents: {
+ defaults: {
+ heartbeat: {
+ every: "2h", // or "0m" to disable
+ },
+ },
+ },
+ }
+ ```
+
+ If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown
+ headers like `# Heading`), OpenClaw skips the heartbeat run to save API calls.
+ If the file is missing, the heartbeat still runs and the model decides what to do.
+
+ Per-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat).
+
+
+
+
+ No. OpenClaw runs on **your own account**, so if you're in the group, OpenClaw can see it.
+ By default, group replies are blocked until you allow senders (`groupPolicy: "allowlist"`).
+
+ If you want only **you** to be able to trigger group replies:
+
+ ```json5
+ {
+ channels: {
+ whatsapp: {
+ groupPolicy: "allowlist",
+ groupAllowFrom: ["+15551234567"],
+ },
+ },
+ }
+ ```
+
+
+
+
+ Option 1 (fastest): tail logs and send a test message in the group:
+
+ ```bash
+ openclaw logs --follow --json
+ ```
+
+ Look for `chatId` (or `from`) ending in `@g.us`, like:
+ `1234567890-1234567890@g.us`.
+
+ Option 2 (if already configured/allowlisted): list groups from config:
+
+ ```bash
+ openclaw directory groups list --channel whatsapp
+ ```
+
+ Docs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs).
+
+
+
+
+ Two common causes:
+
+ - Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`).
+ - You configured `channels.whatsapp.groups` without `"*"` and the group isn't allowlisted.
+
+ See [Groups](/channels/groups) and [Group messages](/channels/group-messages).
+
+
+
+
+ Direct 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](/channels/groups) and [Group messages](/channels/group-messages).
+
+
+
+ No hard limits. Dozens (even hundreds) are fine, but watch for:
+
+ - **Disk growth:** sessions + transcripts live under `~/.openclaw/agents//sessions/`.
+ - **Token cost:** more agents means more concurrent model usage.
+ - **Ops overhead:** per-agent auth profiles, workspaces, and channel routing.
+
+ Tips:
+
+ - Keep one **active** workspace per agent (`agents.defaults.workspace`).
+ - Prune old sessions (delete JSONL or store entries) if disk grows.
+ - Use `openclaw doctor` to spot stray workspaces and profile mismatches.
+
+
+
+
+ Yes. Use **Multi-Agent Routing** to run multiple isolated agents and route inbound messages by
+ channel/account/peer. Slack is supported as a channel and can be bound to specific agents.
+
+ Browser access is powerful but not "do anything a human can" - anti-bot, CAPTCHAs, and MFA can
+ still block automation. For the most reliable browser control, use local Chrome MCP on the host,
+ or use CDP on the machine that actually runs the browser.
+
+ Best-practice setup:
+
+ - Always-on Gateway host (VPS/Mac mini).
+ - One agent per role (bindings).
+ - Slack channel(s) bound to those agents.
+ - Local browser via Chrome MCP or a node when needed.
+
+ Docs: [Multi-Agent Routing](/concepts/multi-agent), [Slack](/channels/slack),
+ [Browser](/tools/browser), [Nodes](/nodes).
+
+
+
## Models: defaults, selection, aliases, switching
-### What is the default model
+
+
+ OpenClaw's default model is whatever you set as:
-OpenClaw's default model is whatever you set as:
+ ```
+ agents.defaults.model.primary
+ ```
-```
-agents.defaults.model.primary
-```
+ Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-6`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`.
-Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-6`). If you omit the provider, OpenClaw currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`.
+
-### What model do you recommend
+
+ **Recommended default:** use the strongest latest-generation model available in your provider stack.
+ **For tool-enabled or untrusted-input agents:** prioritize model strength over cost.
+ **For routine/low-stakes chat:** use cheaper fallback models and route by agent role.
-**Recommended default:** use the strongest latest-generation model available in your provider stack.
-**For tool-enabled or untrusted-input agents:** prioritize model strength over cost.
-**For routine/low-stakes chat:** use cheaper fallback models and route by agent role.
+ MiniMax M2.5 has its own docs: [MiniMax](/providers/minimax) and
+ [Local models](/gateway/local-models).
-MiniMax M2.5 has its own docs: [MiniMax](/providers/minimax) and
-[Local models](/gateway/local-models).
+ Rule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper
+ model for routine chat or summaries. You can route models per agent and use sub-agents to
+ parallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and
+ [Sub-agents](/tools/subagents).
-Rule of thumb: use the **best model you can afford** for high-stakes work, and a cheaper
-model for routine chat or summaries. You can route models per agent and use sub-agents to
-parallelize long tasks (each sub-agent consumes tokens). See [Models](/concepts/models) and
-[Sub-agents](/tools/subagents).
+ Strong warning: weaker/over-quantized models are more vulnerable to prompt
+ injection and unsafe behavior. See [Security](/gateway/security).
-Strong warning: weaker/over-quantized models are more vulnerable to prompt
-injection and unsafe behavior. See [Security](/gateway/security).
+ More context: [Models](/concepts/models).
-More context: [Models](/concepts/models).
+
-### Can I use selfhosted models llamacpp vLLM Ollama
+
+ Use **model commands** or edit only the **model** fields. Avoid full config replaces.
-Yes. Ollama is the easiest path for local models.
+ Safe options:
-Quickest setup:
+ - `/model` in chat (quick, per-session)
+ - `openclaw models set ...` (updates just model config)
+ - `openclaw configure --section model` (interactive)
+ - edit `agents.defaults.model` in `~/.openclaw/openclaw.json`
-1. Install Ollama from `https://ollama.com/download`
-2. Pull a local model such as `ollama pull glm-4.7-flash`
-3. If you want Ollama Cloud too, run `ollama signin`
-4. Run `openclaw onboard` and choose `Ollama`
-5. Pick `Local` or `Cloud + Local`
+ Avoid `config.apply` with a partial object unless you intend to replace the whole config.
+ If you did overwrite config, restore from backup or re-run `openclaw doctor` to repair.
-Notes:
+ Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor).
-- `Cloud + Local` gives you Ollama Cloud models plus your local Ollama models
-- cloud models such as `kimi-k2.5:cloud` do not need a local pull
-- for manual switching, use `openclaw models list` and `openclaw models set ollama/`
+
-Security note: smaller or heavily quantized models are more vulnerable to prompt
-injection. We strongly recommend **large models** for any bot that can use tools.
-If you still want small models, enable sandboxing and strict tool allowlists.
+
+ Yes. Ollama is the easiest path for local models.
-Docs: [Ollama](/providers/ollama), [Local models](/gateway/local-models),
-[Model providers](/concepts/model-providers), [Security](/gateway/security),
-[Sandboxing](/gateway/sandboxing).
+ Quickest setup:
-### How do I switch models without wiping my config
+ 1. Install Ollama from `https://ollama.com/download`
+ 2. Pull a local model such as `ollama pull glm-4.7-flash`
+ 3. If you want Ollama Cloud too, run `ollama signin`
+ 4. Run `openclaw onboard` and choose `Ollama`
+ 5. Pick `Local` or `Cloud + Local`
-Use **model commands** or edit only the **model** fields. Avoid full config replaces.
+ Notes:
-Safe options:
+ - `Cloud + Local` gives you Ollama Cloud models plus your local Ollama models
+ - cloud models such as `kimi-k2.5:cloud` do not need a local pull
+ - for manual switching, use `openclaw models list` and `openclaw models set ollama/`
-- `/model` in chat (quick, per-session)
-- `openclaw models set ...` (updates just model config)
-- `openclaw configure --section model` (interactive)
-- edit `agents.defaults.model` in `~/.openclaw/openclaw.json`
+ Security note: smaller or heavily quantized models are more vulnerable to prompt
+ injection. We strongly recommend **large models** for any bot that can use tools.
+ If you still want small models, enable sandboxing and strict tool allowlists.
-Avoid `config.apply` with a partial object unless you intend to replace the whole config.
-If you did overwrite config, restore from backup or re-run `openclaw doctor` to repair.
+ Docs: [Ollama](/providers/ollama), [Local models](/gateway/local-models),
+ [Model providers](/concepts/model-providers), [Security](/gateway/security),
+ [Sandboxing](/gateway/sandboxing).
-Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor).
+
-### What do OpenClaw, Flawd, and Krill use for models
+
+ - These deployments can differ and may change over time; there is no fixed provider recommendation.
+ - Check the current runtime setting on each gateway with `openclaw models status`.
+ - For security-sensitive/tool-enabled agents, use the strongest latest-generation model available.
+
-- These deployments can differ and may change over time; there is no fixed provider recommendation.
-- Check the current runtime setting on each gateway with `openclaw models status`.
-- For security-sensitive/tool-enabled agents, use the strongest latest-generation model available.
+
+ Use the `/model` command as a standalone message:
-### How do I switch models on the fly without restarting
+ ```
+ /model sonnet
+ /model haiku
+ /model opus
+ /model gpt
+ /model gpt-mini
+ /model gemini
+ /model gemini-flash
+ ```
-Use the `/model` command as a standalone message:
+ You can list available models with `/model`, `/model list`, or `/model status`.
-```
-/model sonnet
-/model haiku
-/model opus
-/model gpt
-/model gpt-mini
-/model gemini
-/model gemini-flash
-```
+ `/model` (and `/model list`) shows a compact, numbered picker. Select by number:
-You can list available models with `/model`, `/model list`, or `/model status`.
+ ```
+ /model 3
+ ```
-`/model` (and `/model list`) shows a compact, numbered picker. Select by number:
+ You can also force a specific auth profile for the provider (per session):
-```
-/model 3
-```
+ ```
+ /model opus@anthropic:default
+ /model opus@anthropic:work
+ ```
-You can also force a specific auth profile for the provider (per session):
+ Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.
+ It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
-```
-/model opus@anthropic:default
-/model opus@anthropic:work
-```
+ **How do I unpin a profile I set with @profile?**
-Tip: `/model status` shows which agent is active, which `auth-profiles.json` file is being used, and which auth profile will be tried next.
-It also shows the configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
+ Re-run `/model` **without** the `@profile` suffix:
-**How do I unpin a profile I set with profile**
+ ```
+ /model anthropic/claude-opus-4-6
+ ```
-Re-run `/model` **without** the `@profile` suffix:
+ If you want to return to the default, pick it from `/model` (or send `/model `).
+ Use `/model status` to confirm which auth profile is active.
-```
-/model anthropic/claude-opus-4-6
-```
+
-If you want to return to the default, pick it from `/model` (or send `/model `).
-Use `/model status` to confirm which auth profile is active.
+
+ Yes. Set one as default and switch as needed:
-### Can I use GPT 5.2 for daily tasks and Codex 5.3 for coding
+ - **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model openai-codex/gpt-5.4` for coding with Codex OAuth.
+ - **Default + switch:** set `agents.defaults.model.primary` to `openai/gpt-5.2`, then switch to `openai-codex/gpt-5.4` when coding (or the other way around).
+ - **Sub-agents:** route coding tasks to sub-agents with a different default model.
-Yes. Set one as default and switch as needed:
+ See [Models](/concepts/models) and [Slash commands](/tools/slash-commands).
-- **Quick switch (per session):** `/model gpt-5.2` for daily tasks, `/model openai-codex/gpt-5.4` for coding with Codex OAuth.
-- **Default + switch:** set `agents.defaults.model.primary` to `openai/gpt-5.2`, then switch to `openai-codex/gpt-5.4` when coding (or the other way around).
-- **Sub-agents:** route coding tasks to sub-agents with a different default model.
+
-See [Models](/concepts/models) and [Slash commands](/tools/slash-commands).
+
+ If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any
+ session overrides. Choosing a model that isn't in that list returns:
-### Why do I see Model is not allowed and then no reply
+ ```
+ Model "provider/model" is not allowed. Use /model to list available models.
+ ```
-If `agents.defaults.models` is set, it becomes the **allowlist** for `/model` and any
-session overrides. Choosing a model that isn't in that list returns:
+ That error is returned **instead of** a normal reply. Fix: add the model to
+ `agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.
-```
-Model "provider/model" is not allowed. Use /model to list available models.
-```
+
-That error is returned **instead of** a normal reply. Fix: add the model to
-`agents.defaults.models`, remove the allowlist, or pick a model from `/model list`.
+
+ This means the **provider isn't configured** (no MiniMax provider config or auth
+ profile was found), so the model can't be resolved. A fix for this detection is
+ in **2026.1.12** (unreleased at the time of writing).
-### Why do I see Unknown model minimaxMiniMaxM25
+ Fix checklist:
-This means the **provider isn't configured** (no MiniMax provider config or auth
-profile was found), so the model can't be resolved. A fix for this detection is
-in **2026.1.12** (unreleased at the time of writing).
+ 1. Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway.
+ 2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key
+ exists in env/auth profiles so the provider can be injected.
+ 3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.5` or
+ `minimax/MiniMax-M2.5-highspeed`.
+ 4. Run:
-Fix checklist:
+ ```bash
+ openclaw models list
+ ```
-1. Upgrade to **2026.1.12** (or run from source `main`), then restart the gateway.
-2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key
- exists in env/auth profiles so the provider can be injected.
-3. Use the exact model id (case-sensitive): `minimax/MiniMax-M2.5` or
- `minimax/MiniMax-M2.5-highspeed`.
-4. Run:
+ and pick from the list (or `/model list` in chat).
- ```bash
- openclaw models list
- ```
+ See [MiniMax](/providers/minimax) and [Models](/concepts/models).
- and pick from the list (or `/model list` in chat).
+
-See [MiniMax](/providers/minimax) and [Models](/concepts/models).
+
+ Yes. Use **MiniMax as the default** and switch models **per session** when needed.
+ Fallbacks are for **errors**, not "hard tasks," so use `/model` or a separate agent.
-### Can I use MiniMax as my default and OpenAI for complex tasks
+ **Option A: switch per session**
-Yes. Use **MiniMax as the default** and switch models **per session** when needed.
-Fallbacks are for **errors**, not "hard tasks," so use `/model` or a separate agent.
-
-**Option A: switch per session**
-
-```json5
-{
- env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
- agents: {
- defaults: {
- model: { primary: "minimax/MiniMax-M2.5" },
- models: {
- "minimax/MiniMax-M2.5": { alias: "minimax" },
- "openai/gpt-5.2": { alias: "gpt" },
+ ```json5
+ {
+ env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
+ agents: {
+ defaults: {
+ model: { primary: "minimax/MiniMax-M2.5" },
+ models: {
+ "minimax/MiniMax-M2.5": { alias: "minimax" },
+ "openai/gpt-5.2": { alias: "gpt" },
+ },
+ },
},
- },
- },
-}
-```
+ }
+ ```
-Then:
+ Then:
-```
-/model gpt
-```
+ ```
+ /model gpt
+ ```
-**Option B: separate agents**
+ **Option B: separate agents**
-- Agent A default: MiniMax
-- Agent B default: OpenAI
-- Route by agent or use `/agent` to switch
+ - Agent A default: MiniMax
+ - Agent B default: OpenAI
+ - Route by agent or use `/agent` to switch
-Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).
+ Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai).
-### Are opus sonnet gpt builtin shortcuts
+
-Yes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):
+
+ Yes. OpenClaw ships a few default shorthands (only applied when the model exists in `agents.defaults.models`):
-- `opus` → `anthropic/claude-opus-4-6`
-- `sonnet` → `anthropic/claude-sonnet-4-6`
-- `gpt` → `openai/gpt-5.4`
-- `gpt-mini` → `openai/gpt-5-mini`
-- `gemini` → `google/gemini-3.1-pro-preview`
-- `gemini-flash` → `google/gemini-3-flash-preview`
-- `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
+ - `opus` → `anthropic/claude-opus-4-6`
+ - `sonnet` → `anthropic/claude-sonnet-4-6`
+ - `gpt` → `openai/gpt-5.4`
+ - `gpt-mini` → `openai/gpt-5-mini`
+ - `gemini` → `google/gemini-3.1-pro-preview`
+ - `gemini-flash` → `google/gemini-3-flash-preview`
+ - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview`
-If you set your own alias with the same name, your value wins.
+ If you set your own alias with the same name, your value wins.
-### How do I defineoverride model shortcuts aliases
+
-Aliases come from `agents.defaults.models..alias`. Example:
+
+ Aliases come from `agents.defaults.models..alias`. Example:
-```json5
-{
- agents: {
- defaults: {
- model: { primary: "anthropic/claude-opus-4-6" },
- models: {
- "anthropic/claude-opus-4-6": { alias: "opus" },
- "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
- "anthropic/claude-haiku-4-5": { alias: "haiku" },
+ ```json5
+ {
+ agents: {
+ defaults: {
+ model: { primary: "anthropic/claude-opus-4-6" },
+ models: {
+ "anthropic/claude-opus-4-6": { alias: "opus" },
+ "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
+ "anthropic/claude-haiku-4-5": { alias: "haiku" },
+ },
+ },
},
- },
- },
-}
-```
+ }
+ ```
-Then `/model sonnet` (or `/` when supported) resolves to that model ID.
+ Then `/model sonnet` (or `/` when supported) resolves to that model ID.
-### How do I add models from other providers like OpenRouter or ZAI
+
-OpenRouter (pay-per-token; many models):
+
+ OpenRouter (pay-per-token; many models):
-```json5
-{
- agents: {
- defaults: {
- model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
- models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
- },
- },
- env: { OPENROUTER_API_KEY: "sk-or-..." },
-}
-```
+ ```json5
+ {
+ agents: {
+ defaults: {
+ model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
+ models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
+ },
+ },
+ env: { OPENROUTER_API_KEY: "sk-or-..." },
+ }
+ ```
-Z.AI (GLM models):
+ Z.AI (GLM models):
-```json5
-{
- agents: {
- defaults: {
- model: { primary: "zai/glm-5" },
- models: { "zai/glm-5": {} },
- },
- },
- env: { ZAI_API_KEY: "..." },
-}
-```
+ ```json5
+ {
+ agents: {
+ defaults: {
+ model: { primary: "zai/glm-5" },
+ models: { "zai/glm-5": {} },
+ },
+ },
+ env: { ZAI_API_KEY: "..." },
+ }
+ ```
-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"`).
+ 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"`).
-**No API key found for provider after adding a new agent**
+ **No API key found for provider after adding a new agent**
-This usually means the **new agent** has an empty auth store. Auth is per-agent and
-stored in:
+ This usually means the **new agent** has an empty auth store. Auth is per-agent and
+ stored in:
-```
-~/.openclaw/agents//agent/auth-profiles.json
-```
+ ```
+ ~/.openclaw/agents//agent/auth-profiles.json
+ ```
-Fix options:
+ Fix options:
-- Run `openclaw agents add ` and configure auth during the wizard.
-- Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`.
+ - Run `openclaw agents add ` and configure auth during the wizard.
+ - Or copy `auth-profiles.json` from the main agent's `agentDir` into the new agent's `agentDir`.
-Do **not** reuse `agentDir` across agents; it causes auth/session collisions.
+ Do **not** reuse `agentDir` across agents; it causes auth/session collisions.
+
+
+
## Model failover and "All models failed"
-### How does failover work
+
+
+ Failover happens in two stages:
-Failover happens in two stages:
+ 1. **Auth profile rotation** within the same provider.
+ 2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`.
-1. **Auth profile rotation** within the same provider.
-2. **Model fallback** to the next model in `agents.defaults.model.fallbacks`.
+ Cooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing.
-Cooldowns apply to failing profiles (exponential backoff), so OpenClaw can keep responding even when a provider is rate-limited or temporarily failing.
+
-### What does this error mean
+
+ 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.
-```
-No credentials found for profile "anthropic:default"
-```
+ **Fix checklist:**
-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.
+ - **Confirm where auth profiles live** (new vs legacy paths)
+ - Current: `~/.openclaw/agents//agent/auth-profiles.json`
+ - Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`)
+ - **Confirm your env var is loaded by the Gateway**
+ - 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`.
+ - **Make sure you're editing the correct agent**
+ - Multi-agent setups mean there can be multiple `auth-profiles.json` files.
+ - **Sanity-check model/auth status**
+ - Use `openclaw models status` to see configured models and whether providers are authenticated.
-### Fix checklist for No credentials found for profile anthropicdefault
+ **Fix checklist for "No credentials found for profile anthropic"**
-- **Confirm where auth profiles live** (new vs legacy paths)
- - Current: `~/.openclaw/agents//agent/auth-profiles.json`
- - Legacy: `~/.openclaw/agent/*` (migrated by `openclaw doctor`)
-- **Confirm your env var is loaded by the Gateway**
- - 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`.
-- **Make sure you're editing the correct agent**
- - Multi-agent setups mean there can be multiple `auth-profiles.json` files.
-- **Sanity-check model/auth status**
- - Use `openclaw models status` to see configured models and whether providers are authenticated.
+ This means the run is pinned to an Anthropic auth profile, but the Gateway
+ can't find it in its auth store.
-**Fix checklist for No credentials found for profile anthropic**
+ - **Use a setup-token**
+ - Run `claude setup-token`, then paste it with `openclaw models auth setup-token --provider anthropic`.
+ - If the token was created on another machine, use `openclaw models auth paste-token --provider anthropic`.
+ - **If you want to use an API key instead**
+ - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.
+ - Clear any pinned order that forces a missing profile:
-This means the run is pinned to an Anthropic auth profile, but the Gateway
-can't find it in its auth store.
+ ```bash
+ openclaw models auth order clear --provider anthropic
+ ```
-- **Use a setup-token**
- - Run `claude setup-token`, then paste it with `openclaw models auth setup-token --provider anthropic`.
- - If the token was created on another machine, use `openclaw models auth paste-token --provider anthropic`.
-- **If you want to use an API key instead**
- - Put `ANTHROPIC_API_KEY` in `~/.openclaw/.env` on the **gateway host**.
- - Clear any pinned order that forces a missing profile:
+ - **Confirm you're running commands on the gateway host**
+ - In remote mode, auth profiles live on the gateway machine, not your laptop.
- ```bash
- openclaw models auth order clear --provider anthropic
- ```
+
-- **Confirm you're running commands on the gateway host**
- - In remote mode, auth profiles live on the gateway machine, not your laptop.
+
+ If 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"`.
-### Why did it also try Google Gemini and fail
+ Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there.
-If 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"`.
+ **LLM request rejected: thinking signature required (Google Antigravity)**
-Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn't route there.
+ Cause: the session history contains **thinking blocks without signatures** (often from
+ an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.
-**LLM request rejected message thinking signature required google antigravity**
+ Fix: 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.
-Cause: the session history contains **thinking blocks without signatures** (often from
-an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.
-
-Fix: 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.
+
+
## Auth profiles: what they are and how to manage them
Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns)
-### What is an auth profile
+
+
+ An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:
-An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:
+ ```
+ ~/.openclaw/agents//agent/auth-profiles.json
+ ```
-```
-~/.openclaw/agents//agent/auth-profiles.json
-```
+
-### What are typical profile IDs
+
+ OpenClaw uses provider-prefixed IDs like:
-OpenClaw uses provider-prefixed IDs like:
+ - `anthropic:default` (common when no email identity exists)
+ - `anthropic:` for OAuth identities
+ - custom IDs you choose (e.g. `anthropic:work`)
-- `anthropic:default` (common when no email identity exists)
-- `anthropic:` for OAuth identities
-- custom IDs you choose (e.g. `anthropic:work`)
+
-### Can I control which auth profile is tried first
+
+ Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.
-Yes. Config supports optional metadata for profiles and an ordering per provider (`auth.order.`). This does **not** store secrets; it maps IDs to provider/mode and sets rotation order.
+ OpenClaw 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*`.
-OpenClaw 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*`.
+ You can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI:
-You can also set a **per-agent** order override (stored in that agent's `auth-profiles.json`) via the CLI:
+ ```bash
+ # Defaults to the configured default agent (omit --agent)
+ openclaw models auth order get --provider anthropic
-```bash
-# Defaults to the configured default agent (omit --agent)
-openclaw models auth order get --provider anthropic
+ # Lock rotation to a single profile (only try this one)
+ openclaw models auth order set --provider anthropic anthropic:default
-# Lock rotation to a single profile (only try this one)
-openclaw models auth order set --provider anthropic anthropic:default
+ # Or set an explicit order (fallback within provider)
+ openclaw models auth order set --provider anthropic anthropic:work anthropic:default
-# Or set an explicit order (fallback within provider)
-openclaw models auth order set --provider anthropic anthropic:work anthropic:default
+ # Clear override (fall back to config auth.order / round-robin)
+ openclaw models auth order clear --provider anthropic
+ ```
-# Clear override (fall back to config auth.order / round-robin)
-openclaw models auth order clear --provider anthropic
-```
+ To target a specific agent:
-To target a specific agent:
+ ```bash
+ openclaw models auth order set --provider anthropic --agent main anthropic:default
+ ```
-```bash
-openclaw models auth order set --provider anthropic --agent main anthropic:default
-```
+
-### OAuth vs API key - what is the difference
+
+ OpenClaw supports both:
-OpenClaw supports both:
+ - **OAuth** often leverages subscription access (where applicable).
+ - **API keys** use pay-per-token billing.
-- **OAuth** often leverages subscription access (where applicable).
-- **API keys** use pay-per-token billing.
+ The wizard explicitly supports Anthropic setup-token and OpenAI Codex OAuth and can store API keys for you.
-The wizard explicitly supports Anthropic setup-token and OpenAI Codex OAuth and can store API keys for you.
+
+
## Gateway: ports, "already running", and remote mode
-### What port does the Gateway use
+
+
+ `gateway.port` controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.).
-`gateway.port` controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.).
+ Precedence:
-Precedence:
+ ```
+ --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789
+ ```
-```
---port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789
-```
+
-### Why does openclaw gateway status say Runtime running but RPC probe failed
+
+ Because "running" is the **supervisor's** view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling `status`.
-Because "running" is the **supervisor's** view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling `status`.
+ Use `openclaw gateway status` and trust these lines:
-Use `openclaw gateway status` and trust these lines:
+ - `Probe target:` (the URL the probe actually used)
+ - `Listening:` (what's actually bound on the port)
+ - `Last gateway error:` (common root cause when the process is alive but the port isn't listening)
-- `Probe target:` (the URL the probe actually used)
-- `Listening:` (what's actually bound on the port)
-- `Last gateway error:` (common root cause when the process is alive but the port isn't listening)
+
-### Why does openclaw gateway status show Config cli and Config service different
+
+ You're editing one config file while the service is running another (often a `--profile` / `OPENCLAW_STATE_DIR` mismatch).
-You're editing one config file while the service is running another (often a `--profile` / `OPENCLAW_STATE_DIR` mismatch).
+ Fix:
-Fix:
+ ```bash
+ openclaw gateway install --force
+ ```
-```bash
-openclaw gateway install --force
-```
+ Run that from the same `--profile` / environment you want the service to use.
-Run that from the same `--profile` / environment you want the service to use.
+
-### What does another gateway instance is already listening mean
+
+ OpenClaw enforces a runtime lock by binding the WebSocket listener immediately on startup (default `ws://127.0.0.1:18789`). If the bind fails with `EADDRINUSE`, it throws `GatewayLockError` indicating another instance is already listening.
-OpenClaw enforces a runtime lock by binding the WebSocket listener immediately on startup (default `ws://127.0.0.1:18789`). If the bind fails with `EADDRINUSE`, it throws `GatewayLockError` indicating another instance is already listening.
+ Fix: stop the other instance, free the port, or run with `openclaw gateway --port `.
-Fix: stop the other instance, free the port, or run with `openclaw gateway --port `.
+
-### How do I run OpenClaw in remote mode client connects to a Gateway elsewhere
+
+ Set `gateway.mode: "remote"` and point to a remote WebSocket URL, optionally with a token/password:
-Set `gateway.mode: "remote"` and point to a remote WebSocket URL, optionally with a token/password:
+ ```json5
+ {
+ gateway: {
+ mode: "remote",
+ remote: {
+ url: "ws://gateway.tailnet:18789",
+ token: "your-token",
+ password: "your-password",
+ },
+ },
+ }
+ ```
-```json5
-{
- gateway: {
- mode: "remote",
- remote: {
- url: "ws://gateway.tailnet:18789",
- token: "your-token",
- password: "your-password",
- },
- },
-}
-```
+ Notes:
-Notes:
+ - `openclaw gateway` only starts when `gateway.mode` is `local` (or you pass the override flag).
+ - The macOS app watches the config file and switches modes live when these values change.
-- `openclaw gateway` only starts when `gateway.mode` is `local` (or you pass the override flag).
-- The macOS app watches the config file and switches modes live when these values change.
+
-### The Control UI says unauthorized or keeps reconnecting What now
+
+ Your gateway is running with auth enabled (`gateway.auth.*`), but the UI is not sending the matching token/password.
-Your gateway is running with auth enabled (`gateway.auth.*`), but the UI is not sending the matching token/password.
+ Facts (from code):
-Facts (from code):
+ - The Control UI keeps the token in `sessionStorage` for the current browser tab session and selected gateway URL, so same-tab refreshes keep working without restoring long-lived localStorage token persistence.
+ - On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`).
-- The Control UI keeps the token in `sessionStorage` for the current browser tab session and selected gateway URL, so same-tab refreshes keep working without restoring long-lived localStorage token persistence.
-- On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`).
+ Fix:
-Fix:
+ - Fastest: `openclaw dashboard` (prints + copies the dashboard URL, tries to open; shows SSH hint if headless).
+ - If you don't have a token yet: `openclaw doctor --generate-gateway-token`.
+ - If remote, tunnel first: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`.
+ - Set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) on the gateway host.
+ - In the Control UI settings, paste the same token.
+ - If mismatch persists after the one retry, rotate/re-approve the paired device token:
+ - `openclaw devices list`
+ - `openclaw devices rotate --device --role operator`
+ - Still stuck? Run `openclaw status --all` and follow [Troubleshooting](/gateway/troubleshooting). See [Dashboard](/web/dashboard) for auth details.
-- Fastest: `openclaw dashboard` (prints + copies the dashboard URL, tries to open; shows SSH hint if headless).
-- If you don't have a token yet: `openclaw doctor --generate-gateway-token`.
-- If remote, tunnel first: `ssh -N -L 18789:127.0.0.1:18789 user@host` then open `http://127.0.0.1:18789/`.
-- Set `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`) on the gateway host.
-- In the Control UI settings, paste the same token.
-- If mismatch persists after the one retry, rotate/re-approve the paired device token:
- - `openclaw devices list`
- - `openclaw devices rotate --device --role operator`
-- Still stuck? Run `openclaw status --all` and follow [Troubleshooting](/gateway/troubleshooting). See [Dashboard](/web/dashboard) for auth details.
+
-### I set gateway.bind tailnet but it cannot bind and nothing listens
+
+ `tailnet` bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn't on Tailscale (or the interface is down), there's nothing to bind to.
-`tailnet` bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn't on Tailscale (or the interface is down), there's nothing to bind to.
+ Fix:
-Fix:
+ - Start Tailscale on that host (so it has a 100.x address), or
+ - Switch to `gateway.bind: "loopback"` / `"lan"`.
-- Start Tailscale on that host (so it has a 100.x address), or
-- Switch to `gateway.bind: "loopback"` / `"lan"`.
+ Note: `tailnet` is explicit. `auto` prefers loopback; use `gateway.bind: "tailnet"` when you want a tailnet-only bind.
-Note: `tailnet` is explicit. `auto` prefers loopback; use `gateway.bind: "tailnet"` when you want a tailnet-only bind.
+
-### Can I run multiple Gateways on the same host
+
+ Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation.
-Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation.
+ Yes, but you must isolate:
-Yes, but you must isolate:
+ - `OPENCLAW_CONFIG_PATH` (per-instance config)
+ - `OPENCLAW_STATE_DIR` (per-instance state)
+ - `agents.defaults.workspace` (workspace isolation)
+ - `gateway.port` (unique ports)
-- `OPENCLAW_CONFIG_PATH` (per-instance config)
-- `OPENCLAW_STATE_DIR` (per-instance state)
-- `agents.defaults.workspace` (workspace isolation)
-- `gateway.port` (unique ports)
+ Quick setup (recommended):
-Quick setup (recommended):
+ - Use `openclaw --profile ...` per instance (auto-creates `~/.openclaw-`).
+ - Set a unique `gateway.port` in each profile config (or pass `--port` for manual runs).
+ - Install a per-profile service: `openclaw --profile gateway install`.
-- Use `openclaw --profile …` per instance (auto-creates `~/.openclaw-`).
-- Set a unique `gateway.port` in each profile config (or pass `--port` for manual runs).
-- Install a per-profile service: `openclaw --profile gateway install`.
+ Profiles also suffix service names (`ai.openclaw.`; legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`).
+ Full guide: [Multiple gateways](/gateway/multiple-gateways).
-Profiles also suffix service names (`ai.openclaw.`; legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`).
-Full guide: [Multiple gateways](/gateway/multiple-gateways).
+
-### What does invalid handshake code 1008 mean
+
+ The Gateway is a **WebSocket server**, and it expects the very first message to
+ be a `connect` frame. If it receives anything else, it closes the connection
+ with **code 1008** (policy violation).
-The Gateway is a **WebSocket server**, and it expects the very first message to
-be a `connect` frame. If it receives anything else, it closes the connection
-with **code 1008** (policy violation).
+ Common causes:
-Common causes:
+ - You opened the **HTTP** URL in a browser (`http://...`) instead of a WS client.
+ - You used the wrong port or path.
+ - A proxy or tunnel stripped auth headers or sent a non-Gateway request.
-- You opened the **HTTP** URL in a browser (`http://...`) instead of a WS client.
-- You used the wrong port or path.
-- A proxy or tunnel stripped auth headers or sent a non-Gateway request.
+ Quick fixes:
-Quick fixes:
+ 1. Use the WS URL: `ws://:18789` (or `wss://...` if HTTPS).
+ 2. Don't open the WS port in a normal browser tab.
+ 3. If auth is on, include the token/password in the `connect` frame.
-1. Use the WS URL: `ws://:18789` (or `wss://...` if HTTPS).
-2. Don't open the WS port in a normal browser tab.
-3. If auth is on, include the token/password in the `connect` frame.
+ If you're using the CLI or TUI, the URL should look like:
-If you're using the CLI or TUI, the URL should look like:
+ ```
+ openclaw tui --url ws://:18789 --token
+ ```
-```
-openclaw tui --url ws://:18789 --token
-```
+ Protocol details: [Gateway protocol](/gateway/protocol).
-Protocol details: [Gateway protocol](/gateway/protocol).
+
+
## Logging and debugging
-### Where are logs
+
+
+ File logs (structured):
-File logs (structured):
+ ```
+ /tmp/openclaw/openclaw-YYYY-MM-DD.log
+ ```
-```
-/tmp/openclaw/openclaw-YYYY-MM-DD.log
-```
+ You can set a stable path via `logging.file`. File log level is controlled by `logging.level`. Console verbosity is controlled by `--verbose` and `logging.consoleLevel`.
-You can set a stable path via `logging.file`. File log level is controlled by `logging.level`. Console verbosity is controlled by `--verbose` and `logging.consoleLevel`.
+ Fastest log tail:
-Fastest log tail:
+ ```bash
+ openclaw logs --follow
+ ```
-```bash
-openclaw logs --follow
-```
+ Service/supervisor logs (when the gateway runs via launchd/systemd):
-Service/supervisor logs (when the gateway runs via launchd/systemd):
+ - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-/logs/...`)
+ - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager`
+ - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST`
-- macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` and `gateway.err.log` (default: `~/.openclaw/logs/...`; profiles use `~/.openclaw-/logs/...`)
-- Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager`
-- Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST`
+ See [Troubleshooting](/gateway/troubleshooting) for more.
-See [Troubleshooting](/gateway/troubleshooting) for more.
+
-### How do I start/stop/restart the Gateway service
+
+ Use the gateway helpers:
-Use the gateway helpers:
+ ```bash
+ openclaw gateway status
+ openclaw gateway restart
+ ```
-```bash
-openclaw gateway status
-openclaw gateway restart
-```
+ If you run the gateway manually, `openclaw gateway --force` can reclaim the port. See [Gateway](/gateway).
-If you run the gateway manually, `openclaw gateway --force` can reclaim the port. See [Gateway](/gateway).
+
-### I closed my terminal on Windows how do I restart OpenClaw
+
+ There are **two Windows install modes**:
-There are **two Windows install modes**:
+ **1) WSL2 (recommended):** the Gateway runs inside Linux.
-**1) WSL2 (recommended):** the Gateway runs inside Linux.
+ Open PowerShell, enter WSL, then restart:
-Open PowerShell, enter WSL, then restart:
+ ```powershell
+ wsl
+ openclaw gateway status
+ openclaw gateway restart
+ ```
-```powershell
-wsl
-openclaw gateway status
-openclaw gateway restart
-```
+ If you never installed the service, start it in the foreground:
-If you never installed the service, start it in the foreground:
+ ```bash
+ openclaw gateway run
+ ```
-```bash
-openclaw gateway run
-```
+ **2) Native Windows (not recommended):** the Gateway runs directly in Windows.
-**2) Native Windows (not recommended):** the Gateway runs directly in Windows.
+ Open PowerShell and run:
-Open PowerShell and run:
+ ```powershell
+ openclaw gateway status
+ openclaw gateway restart
+ ```
-```powershell
-openclaw gateway status
-openclaw gateway restart
-```
+ If you run it manually (no service), use:
-If you run it manually (no service), use:
+ ```powershell
+ openclaw gateway run
+ ```
-```powershell
-openclaw gateway run
-```
+ Docs: [Windows (WSL2)](/platforms/windows), [Gateway service runbook](/gateway).
-Docs: [Windows (WSL2)](/platforms/windows), [Gateway service runbook](/gateway).
+
-### The Gateway is up but replies never arrive What should I check
+
+ Start with a quick health sweep:
-Start with a quick health sweep:
+ ```bash
+ openclaw status
+ openclaw models status
+ openclaw channels status
+ openclaw logs --follow
+ ```
-```bash
-openclaw status
-openclaw models status
-openclaw channels status
-openclaw logs --follow
-```
+ Common causes:
-Common causes:
+ - Model auth not loaded on the **gateway host** (check `models status`).
+ - Channel pairing/allowlist blocking replies (check channel config + logs).
+ - WebChat/Dashboard is open without the right token.
-- Model auth not loaded on the **gateway host** (check `models status`).
-- Channel pairing/allowlist blocking replies (check channel config + logs).
-- WebChat/Dashboard is open without the right token.
+ If you are remote, confirm the tunnel/Tailscale connection is up and that the
+ Gateway WebSocket is reachable.
-If you are remote, confirm the tunnel/Tailscale connection is up and that the
-Gateway WebSocket is reachable.
+ Docs: [Channels](/channels), [Troubleshooting](/gateway/troubleshooting), [Remote access](/gateway/remote).
-Docs: [Channels](/channels), [Troubleshooting](/gateway/troubleshooting), [Remote access](/gateway/remote).
+
-### Disconnected from gateway no reason what now
+
+ This usually means the UI lost the WebSocket connection. Check:
-This usually means the UI lost the WebSocket connection. Check:
+ 1. Is the Gateway running? `openclaw gateway status`
+ 2. Is the Gateway healthy? `openclaw status`
+ 3. Does the UI have the right token? `openclaw dashboard`
+ 4. If remote, is the tunnel/Tailscale link up?
-1. Is the Gateway running? `openclaw gateway status`
-2. Is the Gateway healthy? `openclaw status`
-3. Does the UI have the right token? `openclaw dashboard`
-4. If remote, is the tunnel/Tailscale link up?
+ Then tail logs:
-Then tail logs:
+ ```bash
+ openclaw logs --follow
+ ```
-```bash
-openclaw logs --follow
-```
+ Docs: [Dashboard](/web/dashboard), [Remote access](/gateway/remote), [Troubleshooting](/gateway/troubleshooting).
-Docs: [Dashboard](/web/dashboard), [Remote access](/gateway/remote), [Troubleshooting](/gateway/troubleshooting).
+
-### Telegram setMyCommands fails What should I check
+
+ Start with logs and channel status:
-Start with logs and channel status:
+ ```bash
+ openclaw channels status
+ openclaw channels logs --channel telegram
+ ```
-```bash
-openclaw channels status
-openclaw channels logs --channel telegram
-```
+ Then match the error:
-Then match the error:
+ - `BOT_COMMANDS_TOO_MUCH`: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries still need to be dropped. Reduce plugin/skill/custom commands, or disable `channels.telegram.commands.native` if you do not need the menu.
+ - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!`, or similar network errors: if you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for `api.telegram.org`.
-- `BOT_COMMANDS_TOO_MUCH`: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries still need to be dropped. Reduce plugin/skill/custom commands, or disable `channels.telegram.commands.native` if you do not need the menu.
-- `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!`, or similar network errors: if you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for `api.telegram.org`.
+ If the Gateway is remote, make sure you are looking at logs on the Gateway host.
-If the Gateway is remote, make sure you are looking at logs on the Gateway host.
+ Docs: [Telegram](/channels/telegram), [Channel troubleshooting](/channels/troubleshooting).
-Docs: [Telegram](/channels/telegram), [Channel troubleshooting](/channels/troubleshooting).
+
-### TUI shows no output What should I check
+
+ First confirm the Gateway is reachable and the agent can run:
-First confirm the Gateway is reachable and the agent can run:
+ ```bash
+ openclaw status
+ openclaw models status
+ openclaw logs --follow
+ ```
-```bash
-openclaw status
-openclaw models status
-openclaw logs --follow
-```
+ In the TUI, use `/status` to see the current state. If you expect replies in a chat
+ channel, make sure delivery is enabled (`/deliver on`).
-In the TUI, use `/status` to see the current state. If you expect replies in a chat
-channel, make sure delivery is enabled (`/deliver on`).
+ Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands).
-Docs: [TUI](/web/tui), [Slash commands](/tools/slash-commands).
+
-### How do I completely stop then start the Gateway
+
+ If you installed the service:
-If you installed the service:
+ ```bash
+ openclaw gateway stop
+ openclaw gateway start
+ ```
-```bash
-openclaw gateway stop
-openclaw gateway start
-```
+ This stops/starts the **supervised service** (launchd on macOS, systemd on Linux).
+ Use this when the Gateway runs in the background as a daemon.
-This stops/starts the **supervised service** (launchd on macOS, systemd on Linux).
-Use this when the Gateway runs in the background as a daemon.
+ If you're running in the foreground, stop with Ctrl-C, then:
-If you're running in the foreground, stop with Ctrl-C, then:
+ ```bash
+ openclaw gateway run
+ ```
-```bash
-openclaw gateway run
-```
+ Docs: [Gateway service runbook](/gateway).
-Docs: [Gateway service runbook](/gateway).
+
-### ELI5 openclaw gateway restart vs openclaw gateway
+
+ - `openclaw gateway restart`: restarts the **background service** (launchd/systemd).
+ - `openclaw gateway`: runs the gateway **in the foreground** for this terminal session.
-- `openclaw gateway restart`: restarts the **background service** (launchd/systemd).
-- `openclaw gateway`: runs the gateway **in the foreground** for this terminal session.
+ If you installed the service, use the gateway commands. Use `openclaw gateway` when
+ you want a one-off, foreground run.
-If you installed the service, use the gateway commands. Use `openclaw gateway` when
-you want a one-off, foreground run.
+
-### Fastest way to get more details when something fails
-
-Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors.
+
+ Start the Gateway with `--verbose` to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors.
+
+
## Media and attachments
-### My skill generated an imagePDF but nothing was sent
+
+
+ Outbound attachments from the agent must include a `MEDIA:` line (on its own line). See [OpenClaw assistant setup](/start/openclaw) and [Agent send](/tools/agent-send).
-Outbound attachments from the agent must include a `MEDIA:` line (on its own line). See [OpenClaw assistant setup](/start/openclaw) and [Agent send](/tools/agent-send).
+ CLI sending:
-CLI sending:
+ ```bash
+ openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
+ ```
-```bash
-openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
-```
+ Also check:
-Also check:
+ - The target channel supports outbound media and isn't blocked by allowlists.
+ - The file is within the provider's size limits (images are resized to max 2048px).
-- The target channel supports outbound media and isn't blocked by allowlists.
-- The file is within the provider's size limits (images are resized to max 2048px).
+ See [Images](/nodes/images).
-See [Images](/nodes/images).
+
+
## Security and access control
-### Is it safe to expose OpenClaw to inbound DMs
+
+
+ Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:
-Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:
+ - Default behavior on DM-capable channels is **pairing**:
+ - Unknown senders receive a pairing code; the bot does not process their message.
+ - Approve with: `openclaw pairing approve --channel [--account ] `
+ - Pending requests are capped at **3 per channel**; check `openclaw pairing list --channel [--account ]` if a code didn't arrive.
+ - Opening DMs publicly requires explicit opt-in (`dmPolicy: "open"` and allowlist `"*"`).
-- Default behavior on DM-capable channels is **pairing**:
- - Unknown senders receive a pairing code; the bot does not process their message.
- - Approve with: `openclaw pairing approve --channel [--account ] `
- - Pending requests are capped at **3 per channel**; check `openclaw pairing list --channel [--account ]` if a code didn't arrive.
-- Opening DMs publicly requires explicit opt-in (`dmPolicy: "open"` and allowlist `"*"`).
+ Run `openclaw doctor` to surface risky DM policies.
-Run `openclaw doctor` to surface risky DM policies.
+
-### Is prompt injection only a concern for public bots
+
+ No. Prompt injection is about **untrusted content**, not just who can DM the bot.
+ If your assistant reads external content (web search/fetch, browser pages, emails,
+ docs, attachments, pasted logs), that content can include instructions that try
+ to hijack the model. This can happen even if **you are the only sender**.
-No. Prompt injection is about **untrusted content**, not just who can DM the bot.
-If your assistant reads external content (web search/fetch, browser pages, emails,
-docs, attachments, pasted logs), that content can include instructions that try
-to hijack the model. This can happen even if **you are the only sender**.
+ The biggest risk is when tools are enabled: the model can be tricked into
+ exfiltrating context or calling tools on your behalf. Reduce the blast radius by:
-The biggest risk is when tools are enabled: the model can be tricked into
-exfiltrating context or calling tools on your behalf. Reduce the blast radius by:
+ - using a read-only or tool-disabled "reader" agent to summarize untrusted content
+ - keeping `web_search` / `web_fetch` / `browser` off for tool-enabled agents
+ - sandboxing and strict tool allowlists
-- using a read-only or tool-disabled "reader" agent to summarize untrusted content
-- keeping `web_search` / `web_fetch` / `browser` off for tool-enabled agents
-- sandboxing and strict tool allowlists
+ Details: [Security](/gateway/security).
-Details: [Security](/gateway/security).
+
-### Should my bot have its own email GitHub account or phone number
+
+ Yes, for most setups. Isolating the bot with separate accounts and phone numbers
+ reduces the blast radius if something goes wrong. This also makes it easier to rotate
+ credentials or revoke access without impacting your personal accounts.
-Yes, for most setups. Isolating the bot with separate accounts and phone numbers
-reduces the blast radius if something goes wrong. This also makes it easier to rotate
-credentials or revoke access without impacting your personal accounts.
+ Start small. Give access only to the tools and accounts you actually need, and expand
+ later if required.
-Start small. Give access only to the tools and accounts you actually need, and expand
-later if required.
+ Docs: [Security](/gateway/security), [Pairing](/channels/pairing).
-Docs: [Security](/gateway/security), [Pairing](/channels/pairing).
+
-### Can I give it autonomy over my text messages and is that safe
+
+ We do **not** recommend full autonomy over your personal messages. The safest pattern is:
-We do **not** recommend full autonomy over your personal messages. The safest pattern is:
+ - Keep DMs in **pairing mode** or a tight allowlist.
+ - Use a **separate number or account** if you want it to message on your behalf.
+ - Let it draft, then **approve before sending**.
-- Keep DMs in **pairing mode** or a tight allowlist.
-- Use a **separate number or account** if you want it to message on your behalf.
-- Let it draft, then **approve before sending**.
+ If you want to experiment, do it on a dedicated account and keep it isolated. See
+ [Security](/gateway/security).
-If you want to experiment, do it on a dedicated account and keep it isolated. See
-[Security](/gateway/security).
+
-### Can I use cheaper models for personal assistant tasks
+
+ Yes, **if** the agent is chat-only and the input is trusted. Smaller tiers are
+ more susceptible to instruction hijacking, so avoid them for tool-enabled agents
+ or when reading untrusted content. If you must use a smaller model, lock down
+ tools and run inside a sandbox. See [Security](/gateway/security).
+
-Yes, **if** the agent is chat-only and the input is trusted. Smaller tiers are
-more susceptible to instruction hijacking, so avoid them for tool-enabled agents
-or when reading untrusted content. If you must use a smaller model, lock down
-tools and run inside a sandbox. See [Security](/gateway/security).
+
+ Pairing codes are sent **only** when an unknown sender messages the bot and
+ `dmPolicy: "pairing"` is enabled. `/start` by itself doesn't generate a code.
-### I ran start in Telegram but did not get a pairing code
+ Check pending requests:
-Pairing codes are sent **only** when an unknown sender messages the bot and
-`dmPolicy: "pairing"` is enabled. `/start` by itself doesn't generate a code.
+ ```bash
+ openclaw pairing list telegram
+ ```
-Check pending requests:
+ If you want immediate access, allowlist your sender id or set `dmPolicy: "open"`
+ for that account.
-```bash
-openclaw pairing list telegram
-```
+
-If you want immediate access, allowlist your sender id or set `dmPolicy: "open"`
-for that account.
+
+ No. Default WhatsApp DM policy is **pairing**. Unknown senders only get a pairing code and their message is **not processed**. OpenClaw only replies to chats it receives or to explicit sends you trigger.
-### WhatsApp will it message my contacts How does pairing work
+ Approve pairing with:
-No. Default WhatsApp DM policy is **pairing**. Unknown senders only get a pairing code and their message is **not processed**. OpenClaw only replies to chats it receives or to explicit sends you trigger.
+ ```bash
+ openclaw pairing approve whatsapp
+ ```
-Approve pairing with:
+ List pending requests:
-```bash
-openclaw pairing approve whatsapp
-```
+ ```bash
+ openclaw pairing list whatsapp
+ ```
-List pending requests:
+ Wizard phone number prompt: it's used to set your **allowlist/owner** so your own DMs are permitted. It's not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable `channels.whatsapp.selfChatMode`.
-```bash
-openclaw pairing list whatsapp
-```
-
-Wizard phone number prompt: it's used to set your **allowlist/owner** so your own DMs are permitted. It's not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable `channels.whatsapp.selfChatMode`.
+
+
## Chat commands, aborting tasks, and "it will not stop"
-### How do I stop internal system messages from showing in chat
+
+
+ Most internal or tool messages only appear when **verbose** or **reasoning** is enabled
+ for that session.
-Most internal or tool messages only appear when **verbose** or **reasoning** is enabled
-for that session.
+ Fix in the chat where you see it:
-Fix in the chat where you see it:
+ ```
+ /verbose off
+ /reasoning off
+ ```
-```
-/verbose off
-/reasoning off
-```
+ If it is still noisy, check the session settings in the Control UI and set verbose
+ to **inherit**. Also confirm you are not using a bot profile with `verboseDefault` set
+ to `on` in config.
-If it is still noisy, check the session settings in the Control UI and set verbose
-to **inherit**. Also confirm you are not using a bot profile with `verboseDefault` set
-to `on` in config.
+ Docs: [Thinking and verbose](/tools/thinking), [Security](/gateway/security#reasoning-verbose-output-in-groups).
-Docs: [Thinking and verbose](/tools/thinking), [Security](/gateway/security#reasoning-verbose-output-in-groups).
+
-### How do I stopcancel a running task
+
+ Send any of these **as a standalone message** (no slash):
-Send any of these **as a standalone message** (no slash):
+ ```
+ stop
+ stop action
+ stop current action
+ stop run
+ stop current run
+ stop agent
+ stop the agent
+ stop openclaw
+ openclaw stop
+ stop don't do anything
+ stop do not do anything
+ stop doing anything
+ please stop
+ stop please
+ abort
+ esc
+ wait
+ exit
+ interrupt
+ ```
-```
-stop
-stop action
-stop current action
-stop run
-stop current run
-stop agent
-stop the agent
-stop openclaw
-openclaw stop
-stop don't do anything
-stop do not do anything
-stop doing anything
-please stop
-stop please
-abort
-esc
-wait
-exit
-interrupt
-```
+ These are abort triggers (not slash commands).
-These are abort triggers (not slash commands).
+ For background processes (from the exec tool), you can ask the agent to run:
-For background processes (from the exec tool), you can ask the agent to run:
+ ```
+ process action:kill sessionId:XXX
+ ```
-```
-process action:kill sessionId:XXX
-```
+ Slash commands overview: see [Slash commands](/tools/slash-commands).
-Slash commands overview: see [Slash commands](/tools/slash-commands).
+ Most commands must be sent as a **standalone** message that starts with `/`, but a few shortcuts (like `/status`) also work inline for allowlisted senders.
-Most commands must be sent as a **standalone** message that starts with `/`, but a few shortcuts (like `/status`) also work inline for allowlisted senders.
+
-### How do I send a Discord message from Telegram Crosscontext messaging denied
+
+ OpenClaw blocks **cross-provider** messaging by default. If a tool call is bound
+ to Telegram, it won't send to Discord unless you explicitly allow it.
-OpenClaw blocks **cross-provider** messaging by default. If a tool call is bound
-to Telegram, it won't send to Discord unless you explicitly allow it.
+ Enable cross-provider messaging for the agent:
-Enable cross-provider messaging for the agent:
-
-```json5
-{
- agents: {
- defaults: {
- tools: {
- message: {
- crossContext: {
- allowAcrossProviders: true,
- marker: { enabled: true, prefix: "[from {channel}] " },
+ ```json5
+ {
+ agents: {
+ defaults: {
+ tools: {
+ message: {
+ crossContext: {
+ allowAcrossProviders: true,
+ marker: { enabled: true, prefix: "[from {channel}] " },
+ },
+ },
},
},
},
- },
- },
-}
-```
+ }
+ ```
-Restart the gateway after editing config. If you only want this for a single
-agent, set it under `agents.list[].tools.message` instead.
+ Restart the gateway after editing config. If you only want this for a single
+ agent, set it under `agents.list[].tools.message` instead.
-### Why does it feel like the bot ignores rapidfire messages
+
-Queue mode controls how new messages interact with an in-flight run. Use `/queue` to change modes:
+
+ Queue mode controls how new messages interact with an in-flight run. Use `/queue` to change modes:
-- `steer` - new messages redirect the current task
-- `followup` - run messages one at a time
-- `collect` - batch messages and reply once (default)
-- `steer-backlog` - steer now, then process backlog
-- `interrupt` - abort current run and start fresh
+ - `steer` - new messages redirect the current task
+ - `followup` - run messages one at a time
+ - `collect` - batch messages and reply once (default)
+ - `steer-backlog` - steer now, then process backlog
+ - `interrupt` - abort current run and start fresh
-You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
+ You can add options like `debounce:2s cap:25 drop:summarize` for followup modes.
-## Answer the exact question from the screenshot/chat log
+
+
-**Q: "What's the default model for Anthropic with an API key?"**
+## Miscellaneous
-**A:** In OpenClaw, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agents.defaults.model.primary` (for example, `anthropic/claude-sonnet-4-6` or `anthropic/claude-opus-4-6`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn't find Anthropic credentials in the expected `auth-profiles.json` for the agent that's running.
+
+
+ In OpenClaw, credentials and model selection are separate. Setting `ANTHROPIC_API_KEY` (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in `agents.defaults.model.primary` (for example, `anthropic/claude-sonnet-4-6` or `anthropic/claude-opus-4-6`). If you see `No credentials found for profile "anthropic:default"`, it means the Gateway couldn't find Anthropic credentials in the expected `auth-profiles.json` for the agent that's running.
+
+
---
diff --git a/docs/help/index.md b/docs/help/index.md
index 5d0942909b6..26b990c1533 100644
--- a/docs/help/index.md
+++ b/docs/help/index.md
@@ -19,3 +19,10 @@ If you want a quick “get unstuck” flow, start here:
If you’re looking for conceptual questions (not “something broke”):
- [FAQ (concepts)](/help/faq)
+
+## Environment and debugging
+
+- **Environment variables:** [Where OpenClaw loads env vars and precedence](/help/environment)
+- **Debugging:** [Watch mode, raw streams, and dev profile](/help/debugging)
+- **Testing:** [Test suites, live tests, and Docker runners](/help/testing)
+- **Scripts:** [Repository helper scripts](/help/scripts)