FAQ - Frequently Asked Questions

Quick start and first-run setup

Im stuck whats the fastest way to get unstuck

Use a local AI agent that can see your machine. That is far more effective than asking in Discord, because most “I’m stuck” cases are local config or ...

What’s the recommended way to install and set up OpenClaw

The repo recommends running from source and using the onboarding wizard: curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-d...

How do I open the dashboard after onboarding

The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Kee...

How do I authenticate the dashboard token on localhost vs remote

Localhost (same machine): Open http://127.0.0.1:18789/. If it asks for auth, run openclaw dashboard and use the tokenized link (?token=...). The token...

What runtime do I need

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

Does it run on Raspberry Pi

Yes. The Gateway is lightweight - docs list 512MB-1GB RAM, 1 core, and about 500MB disk as enough for personal use, and note that a Raspberry Pi 4 can...

Any tips for Raspberry Pi installs

Short version: it works, but expect rough edges. Use a 64-bit OS and keep Node >= 22. Prefer the hackable (git) install so you can see logs and update...

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

That screen depends on the Gateway being reachable and authenticated. The TUI also sends “Wake up, my friend!” automatically on first hatch. If you se...

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

Yes. Copy the state directory and workspace, then run Doctor once. This keeps your bot “exactly the same” (memory, session history, auth, and channel ...

Where do I see whats new in the latest version

Check the GitHub changelog: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md Newest entries are at the top. If the top section is marked Un...

I cant access docs.openclaw.ai SSL error What now

Some Comcast/Xfinity connections incorrectly block docs.openclaw.ai via Xfinity Advanced Security. Disable it or allowlist docs.openclaw.ai, then retr...

What’s the difference between stable and beta

Stable and beta are npm dist‑tags, not separate code lines: latest = stable beta = early build for testing We ship builds to beta, test them, and once...

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

Beta is the npm dist‑tag beta (may match latest). Dev is the moving head of main (git); when published, it uses the npm dist‑tag dev. One‑liners (macO...

How long does install and onboarding usually take

Rough guide: Install: 2-5 minutes Onboarding: 5-15 minutes depending on how many channels/models you configure If it hangs, use Installer stuck and th...

How do I try the latest bits

Two options: Dev channel (git checkout): openclaw update --channel dev This switches to the main branch and updates from source. Hackable install (fro...

Installer stuck How do I get more feedback

Re-run the installer with verbose output: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose Beta install with verbose: curl -fsSL https...

Windows install says git not found or openclaw not recognized

Two common Windows issues: 1) npm error spawn git / git not found Install Git for Windows and make sure git is on your PATH. Close and reopen PowerShe...

The docs didnt answer my question how do I get a better answer

Use the hackable (git) install so you have the full source and docs locally, then ask your bot (or Claude/Codex) from that folder so it can read the r...

How do I install OpenClaw on Linux

Short answer: follow the Linux guide, then run the onboarding wizard. Linux quick path + service install: Linux. Full walkthrough: Getting Started. In...

How do I install OpenClaw on a VPS

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

Where are the cloudVPS install guides

We keep a hosting hub with the common providers. Pick one and follow the guide: VPS hosting (all providers in one place) Fly.io Hetzner exe.dev How it...

Can I ask OpenClaw to update itself

Short answer: possible, not recommended. The update flow can restart the Gateway (which drops the active session), may need a clean git checkout, and ...

What does the onboarding wizard actually do

openclaw onboard is the recommended setup path. In local mode it walks you through: Model/auth setup (Anthropic setup-token recommended for Claude sub...

Do I need a Claude or OpenAI subscription to run this

No. You can run OpenClaw with API keys (Anthropic/OpenAI/others) or with local‑only models so your data stays on your device. Subscriptions (Claude Pr...

Can I use Claude Max subscription without an API key

Yes. You can authenticate with a setup-token instead of an API key. This is the subscription path. Claude Pro/Max subscriptions do not include an API ...

How does Anthropic setuptoken auth work

claude setup-token generates a token string via the Claude Code CLI (it is not available in the web console). You can run it on any machine. Choose An...

Where do I find an Anthropic setuptoken

It is not in the Anthropic Console. The setup-token is generated by the Claude Code CLI on any machine: claude setup-token Copy the token it prints, t...

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

Yes — via setup-token. OpenClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere ...

Why am I seeing HTTP 429 ratelimiterror from Anthropic

That means your Anthropic quota/rate limit is exhausted for the current window. If you use a Claude subscription (setup‑token or Claude Code OAuth), w...

Is AWS Bedrock supported

Yes - via pi‑ai’s Amazon Bedrock (Converse) provider with manual config. You must supply AWS credentials/region on the gateway host and add a Bedrock ...

How does Codex auth work

OpenClaw supports OpenAI Code (Codex) via OAuth (ChatGPT sign-in). The wizard can run the OAuth flow and will set the default model to openai-codex/gp...

Do you support OpenAI subscription auth Codex OAuth

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

How do I set up Gemini CLI OAuth

Gemini CLI uses a plugin auth flow, not a client id or secret in openclaw.json. Steps: Enable the plugin: openclaw plugins enable google-gemini-cli-au...

Is a local model OK for casual chats

Usually no. OpenClaw needs large context + strong safety; small cards truncate and leak. If you must, run the largest MiniMax M2.1 build you can local...

How do I keep hosted model traffic in a specific region

Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. Yo...

Do I have to buy a Mac Mini to install this

No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people buy one as an always‑on host, but a small VPS, home serve...

Do I need a Mac mini for iMessage support

You need some macOS device signed into Messages. It does not have to be a Mac mini - any Mac works. OpenClaw’s iMessage integrations run on macOS (Blu...

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...

Telegram what goes in allowFrom

channels.telegram.allowFrom is the human sender’s Telegram user ID (numeric, recommended) or @username. It is not the bot username. Safer (no third-pa...

Can multiple people use one WhatsApp number with different OpenClaw instances

Yes, via multi‑agent routing. Bind each sender’s WhatsApp DM (peer kind: "dm", sender E.164 like +15551234567) to a different agentId, so each person ...

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

Yes. Use multi‑agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Exam...

Does Homebrew work on Linux

Yes. Homebrew supports Linux (Linuxbrew). Quick setup: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"...

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

Hackable (git) install: full source checkout, editable, best for contributors. You run builds locally and can patch code/docs. npm install: global CLI...

Can I switch between npm and git installs later

Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint. This does not delete your data - it only changes t...

Should I run the Gateway on my laptop or a VPS

Short answer: if you want 24/7 reliability, use a VPS. If you want the lowest friction and you’re okay with sleep/restarts, run it locally. Laptop (lo...

How important is it to run OpenClaw on a dedicated machine

Not required, but recommended for reliability and isolation. Dedicated host (VPS/Mac mini/Pi): always‑on, fewer sleep/reboot interruptions, cleaner pe...

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 mor...

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 guid...

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, Matt...

What’s the value proposition

OpenClaw is not “just a Claude wrapper.” It’s a local-first control plane that lets you run a capable assistant on your own hardware, reachable from t...

I just set it up what should I do first

Good first projects: Build a website (WordPress, Shopify, or a simple static site). Prototype a mobile app (outline, screens, API plan). Organize file...

What are the top five everyday use cases for OpenClaw

Everyday wins usually look like: Personal briefings: summaries of inbox, calendar, and news you care about. Research and drafting: quick research, sum...

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

Yes for research, qualification, and drafting. It can scan sites, build shortlists, summarize prospects, and write outreach or ad copy drafts. For out...

What are the advantages vs Claude Code for web development

OpenClaw is a personal assistant and coordination layer, not an IDE replacement. Use Claude Code or Codex for the fastest direct coding loop inside a ...

Skills and automation

How do I customize skills without keeping the repo dirty

Use managed overrides instead of editing the repo copy. Put your changes in ~/.openclaw/skills/<name>/SKILL.md (or add a folder via skills.load.extraD...

Can I load skills from a custom folder

Yes. Add extra directories via skills.load.extraDirs in ~/.openclaw/openclaw.json (lowest precedence). Default precedence remains: <workspace>/skills ...

How can I use different models for different tasks

Today the supported patterns are: Cron jobs: isolated jobs can set a model override per job. Sub-agents: route tasks to separate agents with different...

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

Use sub-agents for long or parallel tasks. Sub-agents run in their own session, return a summary, and keep your main chat responsive. Ask your bot to ...

Cron or reminders do not fire What should I check

Cron runs inside the Gateway process. If the Gateway is not running continuously, scheduled jobs will not run. Checklist: Confirm cron is enabled (cro...

How do I install skills on Linux

Use ClawHub (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux. Browse skills at https://clawhub.com. Install the ...

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

Yes. Use the Gateway scheduler: Cron jobs for scheduled or recurring tasks (persist across restarts). Heartbeat for “main session” periodic checks. Is...

Do you have a Notion or HeyGen integration

Not built‑in today. Options: Custom skill / plugin: best for reliable API access (Notion/HeyGen both have APIs). Browser automation: works without cod...

How do I install the Chrome extension for browser takeover

Use the built-in installer, then load the unpacked extension in Chrome: openclaw browser extension install openclaw browser extension path Then Chrome...

Sandboxing and memory

Is there a dedicated sandboxing doc

Yes. See Sandboxing. For Docker-specific setup (full gateway in Docker or sandbox images), see Docker. Can I keep DMs personal but make groups public ...

How do I bind a host folder into the sandbox

Set agents.defaults.sandbox.docker.binds to ["host:path:mode"] (e.g., "/home/user/src:/src:ro"). Global + per-agent binds merge; per-agent binds are i...

How does memory work

OpenClaw memory is just Markdown files in the agent workspace: Daily notes in memory/YYYY-MM-DD.md Curated long-term notes in MEMORY.md (main/private ...

Memory keeps forgetting things How do I make it stick

Ask the bot to write the fact to memory. Long-term notes belong in MEMORY.md, short-term context goes into memory/YYYY-MM-DD.md. This is still an area...

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 Co...

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 mod...

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. Local by default: sessions, memory files, config, and workspace li...

Where does OpenClaw store its data

Everything lives under $OPENCLAW_STATE_DIR (default: ~/.openclaw): Path Purpose $OPENCLAW_STATE_DIR/openclaw.json Main config (JSON5) $OPENCLAW_STATE_...

Where should AGENTSmd SOULmd USERmd MEMORYmd live

These files live in the agent workspace, not ~/.openclaw. Workspace (per agent): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md (or memory.md), m...

What’s the 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 ...

How do I completely uninstall OpenClaw

See the dedicated guide: Uninstall....

Can agents work outside the workspace

Yes. The workspace is the default cwd and memory anchor, not a hard sandbox. Relative paths resolve inside the workspace, but absolute paths can acces...

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...

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_CONFIG_PATH If the file is missing,...

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). { gateway: { bind: "lan", ...

Why do I need a token on localhost now

The wizard generates a gateway token by default (even on loopback) so local WS clients must authenticate. This blocks other local processes from calli...

Do I have to restart after changing config

The Gateway watches the config and supports hot‑reload: gateway.reload.mode: "hybrid" (default): hot‑apply safe changes, restart for critical ones hot...

How do I enable web search and web fetch

web_fetch works without an API key. web_search requires a Brave Search API key. Recommended: run openclaw configure --section web to store it in tools...

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...

Can the OpenClaw browser run headless

Yes. It’s a config option: { browser: { headless: true }, agents: { defaults: { sandbox: { browser: { headless: true } }, }, }, } ...

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....

Remote gateways + 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 need...

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 ov...

Tailscale is connected but I get no replies What now

Check the basics: Gateway is running: openclaw gateway status Gateway health: openclaw status Channel health: openclaw channels status Then verify aut...

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: Simplest: use a normal chat channel both bots can access...

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 an...

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/Linu...

Should I install on a second laptop or just add a 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. Lo...

Do nodes run a gateway service

No. Only one gateway should run per host unless you intentionally run isolated profiles (see Multiple gateways). Nodes are peripherals that connect to...

Is there an API RPC way to apply config

Yes. config.apply validates + writes the full config and restarts the Gateway as part of the operation....

configapply wiped my config How do I recover and avoid this

config.apply replaces the entire config. If you send a partial object, everything else is removed. Recover: Restore from backup (git or a copied ~/.op...

What’s a minimal sane config for a first install

{ agents: { defaults: { workspace: "~/.openclaw/workspace" } }, channels: { whatsapp: { allowFrom: ["+15555550123"] } }, } This sets your workspac...

How do I set up Tailscale on a VPS and connect from my Mac

Minimal steps: Install + login on the VPS curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up Install + login on your Mac Use the Tails...

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: Make sure the VPS + Mac are on the same...

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: .env from the current working directory a g...

I started the Gateway via the service and my env vars disappeared What now

Two common fixes: Put the missing keys in ~/.openclaw/.env so they’re picked up even when the service doesn’t inherit your shell env. Enable shell imp...

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 ...

Sessions & multiple chats

How do I start a fresh conversation

Send /new or /reset as a standalone message. See Session management....

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 transc...

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...

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 th...

How do I completely reset OpenClaw but keep it installed

Use the reset command: openclaw reset Non-interactive full reset: openclaw reset --scope full --yes --non-interactive Then re-run onboarding: openclaw...

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 <instructions> to guide the summary. Reset (fresh ...

Why am I seeing LLM request rejected messagesNcontentXtooluseinput 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 c...

Why am I getting heartbeat messages every 30 minutes

Heartbeats run every 30m by default. Tune or disable them: { agents: { defaults: { heartbeat: { every: "2h", // or "0m" to disable...

Do I need to add a bot account to a WhatsApp group

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 (...

How do I get the JID of a WhatsApp group

Option 1 (fastest): tail logs and send a test message in the group: openclaw logs --follow --json Look for chatId (or from) ending in @g.us, like: 123...

Why doesnt OpenClaw reply in a group

Two common causes: Mention gating is on (default). You must @mention the bot (or match mentionPatterns). You configured channels.whatsapp.groups witho...

Do groupsthreads 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 ...

How many workspaces and agents can I create

No hard limits. Dozens (even hundreds) are fine, but watch for: Disk growth: sessions + transcripts live under ~/.openclaw/agents/<agentId>/sessions/....

Can I run multiple bots or chats at the same time Slack and how should I set that up

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 c...

Models: defaults, selection, aliases, switching

What is the default model

OpenClaw’s default model is whatever you set as: agents.defaults.model.primary Models are referenced as provider/model (example: anthropic/claude-opus...

What model do you recommend

Recommended default: anthropic/claude-opus-4-5. Good alternative: anthropic/claude-sonnet-4-5. Reliable (less character): openai/gpt-5.2 - nearly as g...

Can I use selfhosted models llamacpp vLLM Ollama

Yes. If your local server exposes an OpenAI-compatible API, you can point a custom provider at it. Ollama is supported directly and is the easiest pat...

How do I switch models without wiping my config

Use model commands or edit only the model fields. Avoid full config replaces. Safe options: /model in chat (quick, per-session) openclaw models set .....

What do OpenClaw, Flawd, and Krill use for models

OpenClaw + Flawd: Anthropic Opus (anthropic/claude-opus-4-5) - see Anthropic. Krill: MiniMax M2.1 (minimax/MiniMax-M2.1) - see MiniMax....

How do I switch models on the fly without restarting

Use the /model command as a standalone message: /model sonnet /model haiku /model opus /model gpt /model gpt-mini /model gemini /model gemini-flash Yo...

Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding

Yes. Set one as default and switch as needed: Quick switch (per session): /model gpt-5.2 for daily tasks, /model gpt-5.2-codex for coding. Default + s...

Why do I see Model is not allowed and then no reply

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: Mod...

Why do I see Unknown model minimaxMiniMaxM21

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 detect...

Can I use MiniMax as my default and OpenAI for complex tasks

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 age...

Are opus sonnet gpt builtin shortcuts

Yes. OpenClaw ships a few default shorthands (only applied when the model exists in agents.defaults.models): opus → anthropic/claude-opus-4-5 sonnet →...

How do I defineoverride model shortcuts aliases

Aliases come from agents.defaults.models.<modelId>.alias. Example: { agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" }...

How do I add models from other providers like OpenRouter or ZAI

OpenRouter (pay‑per‑token; many models): { agents: { defaults: { model: { primary: "openrouter/anthropic/claude-sonnet-4-5" }, model...

How does failover work

Failover happens in two stages: Auth profile rotation within the same provider. Model fallback to the next model in agents.defaults.model.fallbacks. C...

What does this error mean

No credentials found for profile "anthropic:default" It means the system attempted to use the auth profile ID anthropic:default, but could not find cr...

Fix checklist for No credentials found for profile anthropicdefault

Confirm where auth profiles live (new vs legacy paths) Current: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json Legacy: ~/.openclaw/agent/* (mig...

Why did it also try Google Gemini and fail

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 ...

Auth profiles: what they are and how to manage them

What is an auth profile

An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in: ~/.openclaw/agents/<agentId>/agent/auth-profiles...

What are typical profile IDs

OpenClaw uses provider‑prefixed IDs like: anthropic:default (common when no email identity exists) anthropic:<email> for OAuth identities custom IDs y...

Can I control which auth profile is tried first

Yes. Config supports optional metadata for profiles and an ordering per provider (auth.order.<provider>). This does not store secrets; it maps IDs to ...

OAuth vs API key whats the difference

OpenClaw supports both: OAuth often leverages subscription access (where applicable). API keys use pay‑per‑token billing. The wizard explicitly suppor...

What port does the Gateway use

gateway.port controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.). Precedence: --port > OPENCLAW_GATEWAY_PORT > gateway...

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 calli...

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). Fix: openclaw gateway install -...

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 EADDR...

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: { gateway: { mode: "remote", remote: { ...

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. Facts (from code): The Control UI s...

I set gatewaybind tailnet but it cant bind 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 ...

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 ...

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...

Logging and debugging

How do I startstoprestart the Gateway service

Use the gateway helpers: openclaw gateway status openclaw gateway restart If you run the gateway manually, openclaw gateway --force can reclaim the po...

I closed my terminal on Windows how do I restart OpenClaw

There are two Windows install modes: 1) WSL2 (recommended): the Gateway runs inside Linux. Open PowerShell, enter WSL, then restart: wsl openclaw gate...

The Gateway is up but replies never arrive What should I check

Start with a quick health sweep: openclaw status openclaw models status openclaw channels status openclaw logs --follow Common causes: Model auth not ...

Disconnected from gateway no reason what now

This usually means the UI lost the WebSocket connection. Check: Is the Gateway running? openclaw gateway status Is the Gateway healthy? openclaw statu...

Telegram setMyCommands fails with network errors What should I check

Start with logs and channel status: openclaw channels status openclaw channels logs --channel telegram If you are on a VPS or behind a proxy, confirm ...

TUI shows no output What should I check

First confirm the Gateway is reachable and the agent can run: openclaw status openclaw models status openclaw logs --follow In the TUI, use /status to...

How do I completely stop then start the Gateway

If you installed the service: openclaw gateway stop openclaw gateway start This stops/starts the supervised service (launchd on macOS, systemd on Linu...

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 se...

What’s the 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....

Media & attachments

My skill generated an imagePDF but nothing was sent

Outbound attachments from the agent must include a MEDIA:<path-or-url> line (on its own line). See OpenClaw assistant setup and Agent send. CLI sendin...