From 69f6e1a20b96224c7f289ef2179b5870347d2538 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 25 Jan 2026 04:55:14 +0000 Subject: [PATCH] docs: add multi-agent team faq --- docs/help/faq.md | 396 ++++++++++++++++++++++++++--------------------- 1 file changed, 221 insertions(+), 175 deletions(-) diff --git a/docs/help/faq.md b/docs/help/faq.md index ef283be30..9e5fb676c 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -7,33 +7,34 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## Table of contents -- [Quick start and first-run setup](#quick-start-and-first-run-setup) - - [Im stuck - whats the fastest way to get unstuck?](#im-stuck--whats-the-fastest-way-to-get-unstuck) +- [Quick start and first-run setup](#quick-start-and-firstrun-setup) + - [Im stuck whats the fastest way to get unstuck?](#im-stuck-whats-the-fastest-way-to-get-unstuck) - [What’s the recommended way to install and set up Clawdbot?](#whats-the-recommended-way-to-install-and-set-up-clawdbot) - [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) + - [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’s new in the latest version?](#where-do-i-see-whats-new-in-the-latest-version) - [I can't access docs.clawd.bot (SSL error). What now?](#i-cant-access-docsclawdbot-ssl-error-what-now) - [What’s the difference between stable and beta?](#whats-the-difference-between-stable-and-beta) - - [How do I install the beta version, and what’s the difference between beta and dev?](#how-do-i-install-the-beta-version-and-whats-the-difference-between-beta-and-dev) +- [How do I install the beta version, and what’s the difference between beta and dev?](#how-do-i-install-the-beta-version-and-whats-the-difference-between-beta-and-dev) - [How do I try the latest bits?](#how-do-i-try-the-latest-bits) + - [How long does install and onboarding usually take?](#how-long-does-install-and-onboarding-usually-take) - [Installer stuck? How do I get more feedback?](#installer-stuck-how-do-i-get-more-feedback) - - [The docs didn’t answer my question - how do I get a better answer?](#the-docs-didnt-answer-my-question--how-do-i-get-a-better-answer) + - [The docs didn’t answer my question - how do I get a better answer?](#the-docs-didnt-answer-my-question-how-do-i-get-a-better-answer) - [How do I install Clawdbot on Linux?](#how-do-i-install-clawdbot-on-linux) - [How do I install Clawdbot on a VPS?](#how-do-i-install-clawdbot-on-a-vps) - [Where are the cloud/VPS install guides?](#where-are-the-cloudvps-install-guides) - [Can I ask Clawd to update itself?](#can-i-ask-clawd-to-update-itself) - [What does the onboarding wizard actually do?](#what-does-the-onboarding-wizard-actually-do) - [Do I need a Claude or OpenAI subscription to run this?](#do-i-need-a-claude-or-openai-subscription-to-run-this) - - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setup-token-auth-work) - - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setup-token) + - [How does Anthropic "setup-token" auth work?](#how-does-anthropic-setuptoken-auth-work) + - [Where do I find an Anthropic setup-token?](#where-do-i-find-an-anthropic-setuptoken) - [Do you support Claude subscription auth (Claude Code OAuth)?](#do-you-support-claude-subscription-auth-claude-code-oauth) - - [Why am I seeing `HTTP 429: rate_limit_error` from Anthropic?](#why-am-i-seeing-http-429-rate_limit_error-from-anthropic) + - [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) @@ -63,7 +64,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [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 Clawdbot run tasks on a schedule or continuously in the background?](#can-clawdbot-run-tasks-on-a-schedule-or-continuously-in-the-background) - - [Can I run Apple/macOS-only skills from Linux?](#can-i-run-applemacos-only-skills-from-linux) + - [Can I run Apple/macOS-only skills from Linux?](#can-i-run-applemacosonly-skills-from-linux) - [Do you have a Notion or HeyGen integration?](#do-you-have-a-notion-or-heygen-integration) - [How do I install the Chrome extension for browser takeover?](#how-do-i-install-the-chrome-extension-for-browser-takeover) - [Sandboxing and memory](#sandboxing-and-memory) @@ -71,11 +72,12 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [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 Clawdbot saved locally?](#is-all-data-used-with-clawdbot-saved-locally) - [Where does Clawdbot store its data?](#where-does-clawdbot-store-its-data) - - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd--soulmd--usermd--memorymd-live) + - [Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live?](#where-should-agentsmd-soulmd-usermd-memorymd-live) - [What’s the recommended backup strategy?](#whats-the-recommended-backup-strategy) - [How do I completely uninstall Clawdbot?](#how-do-i-completely-uninstall-clawdbot) - [Can agents work outside the workspace?](#can-agents-work-outside-the-workspace) @@ -94,7 +96,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [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 Clawdbots talk to each other (local + VPS)?](#can-two-clawdbots-talk-to-each-other-local--vps) + - [Can two Clawdbots talk to each other (local + VPS)?](#can-two-clawdbots-talk-to-each-other-local-vps) - [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) @@ -105,13 +107,15 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [Env vars and .env loading](#env-vars-and-env-loading) - [How does Clawdbot load environment variables?](#how-does-clawdbot-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-copilot_github_token-but-models-status-shows-shell-env-off-why) + - [I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why?](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why) - [Sessions & multiple chats](#sessions-multiple-chats) - [How do I start a fresh conversation?](#how-do-i-start-a-fresh-conversation) - [Do sessions reset automatically if I never send `/new`?](#do-sessions-reset-automatically-if-i-never-send-new) + - [Is there a way to make a team of Clawdbots one CEO and many agents](#is-there-a-way-to-make-a-team-of-clawdbots-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 Clawdbot but keep it installed?](#how-do-i-completely-reset-clawdbot-but-keep-it-installed) - [I’m getting “context too large” errors - how do I reset or compact?](#im-getting-context-too-large-errors-how-do-i-reset-or-compact) - - [Why am I seeing “LLM request rejected: messages.N.content.X.tool_use.input: Field required”?](#why-am-i-seeing-llm-request-rejected-messagesncontentxtool_useinput-field-required) + - [Why am I seeing “LLM request rejected: messages.N.content.X.tool_use.input: Field required”?](#why-am-i-seeing-llm-request-rejected-messagesncontentxtooluseinput-field-required) - [Why am I getting heartbeat messages every 30 minutes?](#why-am-i-getting-heartbeat-messages-every-30-minutes) - [Do I need to add a “bot account” to a WhatsApp group?](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group) - [How do I get the JID of a WhatsApp group?](#how-do-i-get-the-jid-of-a-whatsapp-group) @@ -123,11 +127,11 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [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-self-hosted-models-llamacpp-vllm-ollama) + - [Can I use self-hosted models (llama.cpp, vLLM, Ollama)?](#can-i-use-selfhosted-models-llamacpp-vllm-ollama) - [What do Clawd, Flawd, and Krill use for models?](#what-do-clawd-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) - [Why do I see “Model … is not allowed” and then no reply?](#why-do-i-see-model-is-not-allowed-and-then-no-reply) - - [Why do I see “Unknown model: minimax/MiniMax-M2.1”?](#why-do-i-see-unknown-model-minimaxminimax-m21) + - [Why do I see “Unknown model: minimax/MiniMax-M2.1”?](#why-do-i-see-unknown-model-minimaxminimaxm21) - [Can I use MiniMax as my default and OpenAI for complex tasks?](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks) - [Are opus / sonnet / gpt built‑in shortcuts?](#are-opus-sonnet-gpt-builtin-shortcuts) - [How do I define/override model shortcuts (aliases)?](#how-do-i-defineoverride-model-shortcuts-aliases) @@ -151,13 +155,13 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [The Control UI says “unauthorized” (or keeps reconnecting). What now?](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now) - [I set `gateway.bind: "tailnet"` but it can’t bind / nothing listens](#i-set-gatewaybind-tailnet-but-it-cant-bind-nothing-listens) - [Can I run multiple Gateways on the same host?](#can-i-run-multiple-gateways-on-the-same-host) - - [What does “invalid handshake” / code 1008 mean?](#what-does-invalid-handshake--code-1008-mean) + - [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 Clawdbot?](#i-closed-my-terminal-on-windows--how-do-i-restart-clawdbot) + - [I closed my terminal on Windows - how do I restart Clawdbot?](#i-closed-my-terminal-on-windows-how-do-i-restart-clawdbot) - [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) + - ["Disconnected from gateway: no reason" - what now?](#disconnected-from-gateway-no-reason-what-now) - [Telegram setMyCommands fails with network errors. What should I check?](#telegram-setmycommands-fails-with-network-errors-what-should-i-check) - [TUI shows no output. What should I check?](#tui-shows-no-output-what-should-i-check) - [How do I completely stop then start the Gateway?](#how-do-i-completely-stop-then-start-the-gateway) @@ -173,7 +177,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, - [WhatsApp: will it message my contacts? How does pairing work?](#whatsapp-will-it-message-my-contacts-how-does-pairing-work) - [Chat commands, aborting tasks, and “it won’t stop”](#chat-commands-aborting-tasks-and-it-wont-stop) - [How do I stop/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-cross-context-messaging-denied) + - [How do I send a Discord message from Telegram? (“Cross-context messaging denied”)](#how-do-i-send-a-discord-message-from-telegram-crosscontext-messaging-denied) - [Why does it feel like the bot “ignores” rapid‑fire messages?](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages) ## First 60 seconds if something's broken @@ -227,7 +231,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, ## Quick start and first-run setup -### Im stuck - whats the fastest way to get unstuck? +### Im stuck whats the fastest way to get unstuck Use a local AI agent that can **see your machine**. That is far more effective than asking in Discord, because most "I'm stuck" cases are **local config or environment issues** that @@ -274,7 +278,7 @@ Other useful CLI checks: `clawdbot status --all`, `clawdbot logs --follow`, Quick debug loop: [First 60 seconds if something's broken](#first-60-seconds-if-somethings-broken). Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating). -### What’s the recommended way to install and set up Clawdbot? +### Whats the recommended way to install and set up Clawdbot The repo recommends running from source and using the onboarding wizard: @@ -298,11 +302,11 @@ clawdbot onboard If you don’t have a global install yet, run it via `pnpm clawdbot onboard`. -### How do I open the dashboard after onboarding? +### How do I open the dashboard after onboarding The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine. Tokens stay local to your host-nothing is fetched from the browser. -### How do I authenticate the dashboard (token) on localhost vs remote? +### How do I authenticate the dashboard token on localhost vs remote **Localhost (same machine):** - Open `http://127.0.0.1:18789/`. @@ -316,11 +320,11 @@ The wizard now opens your browser with a tokenized dashboard URL right after onb See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details. -### What runtime do I need? +### 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? +### Does it run on Raspberry Pi Yes. The Gateway is lightweight - docs list **512MB–1GB RAM**, **1 core**, and about **500MB** disk as enough for personal use, and note that a **Raspberry Pi 4 can run it**. @@ -331,7 +335,7 @@ not a hard minimum. Tip: a small Pi/VPS can host the Gateway, and you can pair **nodes** on your laptop/phone for local screen/camera/canvas or command execution. See [Nodes](/nodes). -### Any tips for Raspberry Pi installs? +### Any tips for Raspberry Pi installs Short version: it works, but expect rough edges. @@ -342,7 +346,7 @@ Short version: it works, but expect rough edges. Docs: [Linux](/platforms/linux), [Install](/install). -### 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 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** @@ -366,7 +370,7 @@ clawdbot doctor If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI is pointed at the right Gateway. See [Remote access](/gateway/remote). -### Can I migrate my setup to a new machine (Mac mini) without redoing onboarding? +### 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 @@ -388,7 +392,7 @@ Related: [Where things live on disk](/help/faq#where-does-clawdbot-store-its-dat [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor), [Remote mode](/gateway/remote). -### Where do I see what’s new in the latest version? +### Where do I see whats new in the latest version Check the GitHub changelog: https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md @@ -397,7 +401,7 @@ Newest entries are at the top. If the top section is marked **Unreleased**, the section is the latest shipped version. Entries are grouped by **Highlights**, **Changes**, and **Fixes** (plus docs/other sections when needed). -### I can't access docs.clawd.bot (SSL error). What now? +### I cant access docsclawdbot SSL error What now Some Comcast/Xfinity connections incorrectly block `docs.clawd.bot` via Xfinity Advanced Security. Disable it or allowlist `docs.clawd.bot`, then retry. More @@ -407,7 +411,7 @@ Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_s If you still can't reach the site, the docs are mirrored on GitHub: https://github.com/clawdbot/clawdbot/tree/main/docs -### What’s the difference between stable and beta? +### Whats the difference between stable and beta **Stable** and **beta** are **npm dist‑tags**, not separate code lines: - `latest` = stable @@ -420,7 +424,7 @@ that same version to `latest`**. That’s why beta and stable can point at the See what changed: https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md -### How do I install the beta version, and what’s the difference between beta and dev? +### How do I install the beta version and whats the difference between beta and dev **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`. @@ -440,7 +444,16 @@ https://clawd.bot/install.ps1 More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer). -### How do I try the latest bits? +### How long does install and onboarding usually take + +Rough guide: +- **Install:** 2-5 minutes +- **Onboarding:** 5-15 minutes depending on how many channels/models you configure + +If it hangs, use [Installer stuck](/help/faq#installer-stuck-how-do-i-get-more-feedback) +and the fast debug loop in [Im stuck](/help/faq#im-stuck--whats-the-fastest-way-to-get-unstuck). + +### How do I try the latest bits Two options: @@ -467,7 +480,7 @@ pnpm build Docs: [Update](/cli/update), [Development channels](/install/development-channels), [Install](/install). -### Installer stuck? How do I get more feedback? +### Installer stuck How do I get more feedback Re-run the installer with **verbose output**: @@ -489,7 +502,7 @@ curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --verb More options: [Installer flags](/install/installer). -### The docs didn’t answer my question - how do I get a better answer? +### The docs didnt answer my question how do I get a better answer 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. @@ -500,7 +513,7 @@ curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git More detail: [Install](/install) and [Installer flags](/install/installer). -### How do I install Clawdbot on Linux? +### How do I install Clawdbot on Linux Short answer: follow the Linux guide, then run the onboarding wizard. @@ -508,14 +521,14 @@ Short answer: follow the Linux guide, then run the onboarding wizard. - Full walkthrough: [Getting Started](/start/getting-started). - Installer + updates: [Install & updates](/install/updating). -### How do I install Clawdbot on a VPS? +### How do I install Clawdbot on a VPS Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway. Guides: [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [Fly.io](/platforms/fly). Remote access: [Gateway remote](/gateway/remote). -### Where are the cloud/VPS install guides? +### Where are the cloudVPS install guides We keep a **hosting hub** with the common providers. Pick one and follow the guide: @@ -536,7 +549,7 @@ Gateway in the cloud. Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote). Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes). -### Can I ask Clawd to update itself? +### Can I ask Clawd 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 @@ -561,7 +574,7 @@ clawdbot gateway restart Docs: [Update](/cli/update), [Updating](/install/updating). -### What does the onboarding wizard actually do? +### What does the onboarding wizard actually do `clawdbot onboard` is the recommended setup path. In **local mode** it walks you through: @@ -574,7 +587,7 @@ Docs: [Update](/cli/update), [Updating](/install/updating). It also warns if your configured model is unknown or missing auth. -### Do I need a Claude or OpenAI subscription to run this? +### Do I need a Claude or OpenAI subscription to run this No. You can run Clawdbot with **API keys** (Anthropic/OpenAI/others) or with **local‑only models** so your data stays on your device. Subscriptions (Claude @@ -583,7 +596,7 @@ Pro/Max or OpenAI Codex) are optional ways to authenticate those providers. Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai), [Local models](/gateway/local-models), [Models](/concepts/models). -### How does Anthropic "setup-token" auth work? +### 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**. If Claude Code CLI credentials are present on the gateway host, Clawdbot can reuse them; otherwise choose **Anthropic token (paste setup-token)** and paste the string. The token is stored as an auth profile for the **anthropic** provider and used like an API key or OAuth profile. More detail: [OAuth](/concepts/oauth). @@ -591,7 +604,7 @@ Clawdbot keeps `auth.profiles["anthropic:claude-cli"].mode` set to `"oauth"` so the profile accepts both OAuth and setup-token credentials; older `"token"` mode entries auto-migrate. -### Where do I find an Anthropic setup-token? +### 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**: @@ -601,13 +614,13 @@ claude setup-token Copy the token it prints, then choose **Anthropic token (paste setup-token)** in the wizard. If you want to run it on the gateway host, use `clawdbot models auth setup-token --provider anthropic`. If you ran `claude setup-token` elsewhere, paste it on the gateway host with `clawdbot models auth paste-token --provider anthropic`. See [Anthropic](/providers/anthropic). -### Do you support Claude subscription auth (Claude Code OAuth)? +### Do you support Claude subscription auth Claude Code OAuth Yes. Clawdbot can **reuse Claude Code CLI credentials** (OAuth) and also supports **setup-token**. If you have a Claude subscription, we recommend **setup-token** for long‑running setups (requires Claude Pro/Max + the `claude` CLI). You can generate it anywhere and paste it on the gateway host. OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. See [Anthropic](/providers/anthropic) and [OAuth](/concepts/oauth). Note: Claude subscription access is governed by Anthropic’s terms. For production or multi‑user workloads, API keys are usually the safer choice. -### Why am I seeing `HTTP 429: rate_limit_error` from Anthropic? +### Why am I seeing HTTP 429 ratelimiterror from Anthropic That means your **Anthropic quota/rate limit** is exhausted for the current window. If you use a **Claude subscription** (setup‑token or Claude Code OAuth), wait for the window to @@ -617,15 +630,15 @@ for usage/billing and raise limits as needed. Tip: set a **fallback model** so Clawdbot can keep replying while a provider is rate‑limited. See [Models](/cli/models) and [OAuth](/concepts/oauth). -### Is AWS Bedrock supported? +### Is AWS Bedrock supported Yes - via pi‑ai’s **Amazon Bedrock (Converse)** provider with **manual config**. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See [Amazon Bedrock](/bedrock) and [Model providers](/providers/models). If you prefer a managed key flow, an OpenAI‑compatible proxy in front of Bedrock is still a valid option. -### How does Codex auth work? +### How does Codex auth work Clawdbot supports **OpenAI Code (Codex)** via OAuth or by reusing your Codex CLI login (`~/.codex/auth.json`). The wizard can import the CLI login or run the OAuth flow and will set the default model to `openai-codex/gpt-5.2` when appropriate. See [Model providers](/concepts/model-providers) and [Wizard](/start/wizard). -### Do you support OpenAI subscription auth (Codex OAuth)? +### Do you support OpenAI subscription auth Codex OAuth Yes. Clawdbot fully supports **OpenAI Code (Codex) subscription OAuth** and can also reuse an existing Codex CLI login (`~/.codex/auth.json`) on the gateway host. The onboarding wizard @@ -633,15 +646,15 @@ can import the CLI login or run the OAuth flow for you. See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Wizard](/start/wizard). -### Is a local model OK for casual chats? +### Is a local model OK for casual chats Usually no. Clawdbot needs large context + strong safety; small cards truncate and leak. If you must, run the **largest** MiniMax M2.1 build you can locally (LM Studio) and see [/gateway/local-models](/gateway/local-models). Smaller/quantized models increase prompt-injection risk - see [Security](/gateway/security). -### How do I keep hosted model traffic in a specific region? +### How do I keep hosted model traffic in a specific region Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using `models.mode: "merge"` so fallbacks stay available while respecting the regioned provider you select. -### Do I have to buy a Mac Mini to install this? +### Do I have to buy a Mac Mini to install this No. Clawdbot 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. @@ -652,7 +665,7 @@ If you want other macOS‑only tools, run the Gateway on a Mac or pair a macOS n Docs: [iMessage](/channels/imessage), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote). -### Do I need a Mac mini for iMessage support? +### 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. Clawdbot’s iMessage integrations run on macOS (BlueBubbles or `imsg`), while @@ -666,7 +679,7 @@ Common setups: Docs: [iMessage](/channels/imessage), [BlueBubbles](/channels/bluebubbles), [Mac remote mode](/platforms/mac/remote). -### If I buy a Mac mini to run Clawdbot, can I connect it to my MacBook Pro? +### If I buy a Mac mini to run Clawdbot 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 @@ -679,7 +692,7 @@ Common pattern: Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes). -### Can I use Bun? +### Can I use Bun Bun is **not recommended**. We see runtime bugs, especially with WhatsApp and Telegram. Use **Node** for stable gateways. @@ -687,7 +700,7 @@ Use **Node** for stable gateways. If you still want to experiment with Bun, do it on a non‑production gateway without WhatsApp/Telegram. -### Telegram: what goes in `allowFrom`? +### 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. @@ -702,15 +715,15 @@ Third-party (less private): See [/channels/telegram](/channels/telegram#access-control-dms--groups). -### Can multiple people use one WhatsApp number with different Clawdbots? +### Can multiple people use one WhatsApp number with different Clawdbots Yes, via **multi‑agent routing**. Bind each sender’s WhatsApp **DM** (peer `kind: "dm"`, sender E.164 like `+15551234567`) to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp). -### Can I run a "fast chat" agent and an "Opus for coding" agent? +### Can I run a fast chat agent and an Opus for coding agent Yes. Use multi‑agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and [Configuration](/gateway/configuration). -### Does Homebrew work on Linux? +### Does Homebrew work on Linux Yes. Homebrew supports Linux (Linuxbrew). Quick setup: @@ -724,7 +737,7 @@ brew install If you run Clawdbot via systemd, ensure the service PATH includes `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools resolve in non‑login shells. Recent builds also prepend common user bin dirs on Linux systemd services (for example `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set. -### What’s the difference between the hackable (git) install and npm install? +### Whats 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. @@ -733,7 +746,7 @@ Recent builds also prepend common user bin dirs on Linux systemd services (for e Docs: [Getting started](/start/getting-started), [Updating](/install/updating). -### Can I switch between npm and git installs later? +### Can I switch between npm and git installs later Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint. This **does not delete your data** - it only changes the Clawdbot code install. Your state @@ -762,7 +775,7 @@ Doctor detects a gateway service entrypoint mismatch and offers to rewrite the s Backup tips: see [Backup strategy](/help/faq#whats-the-recommended-backup-strategy). -### Should I run the Gateway on my laptop or a VPS? +### 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. @@ -779,7 +792,7 @@ lowest friction and you’re okay with sleep/restarts, run it locally. **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 Clawdbot on a dedicated machine? +### How important is it to run Clawdbot on a dedicated machine Not required, but **recommended for reliability and isolation**. @@ -789,7 +802,7 @@ Not required, but **recommended for reliability and isolation**. If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a **node** for local screen/camera/exec tools. See [Nodes](/nodes). For security guidance, read [Security](/gateway/security). -### What are the minimum VPS requirements and recommended OS? +### What are the minimum VPS requirements and recommended OS Clawdbot is lightweight. For a basic Gateway + one chat channel: @@ -802,11 +815,11 @@ Docs: [Linux](/platforms/linux), [VPS hosting](/vps). ## What is Clawdbot? -### What is Clawdbot, in one paragraph? +### What is Clawdbot in one paragraph Clawdbot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The **Gateway** is the always-on control plane; the assistant is the product. -### What’s the value proposition? +### Whats the value proposition Clawdbot 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 @@ -830,15 +843,15 @@ Docs: [Gateway](/gateway), [Channels](/channels), [Multi‑agent](/concepts/mult ## Skills and automation -### How do I customize skills without keeping the repo dirty? +### How do I customize skills without keeping the repo dirty Use managed overrides instead of editing the repo copy. Put your changes in `~/.clawdbot/skills//SKILL.md` (or add a folder via `skills.load.extraDirs` in `~/.clawdbot/clawdbot.json`). Precedence is `/skills` > `~/.clawdbot/skills` > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs. -### Can I load skills from a custom folder? +### Can I load skills from a custom folder Yes. Add extra directories via `skills.load.extraDirs` in `~/.clawdbot/clawdbot.json` (lowest precedence). Default precedence remains: `/skills` → `~/.clawdbot/skills` → bundled → `skills.load.extraDirs`. `clawdhub` installs into `./skills` by default, which Clawdbot treats as `/skills`. -### How can I use different models for different tasks? +### 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. @@ -847,7 +860,7 @@ Today the supported patterns are: See [Cron jobs](/automation/cron-jobs), [Multi-Agent Routing](/concepts/multi-agent), and [Slash commands](/tools/slash-commands). -### The bot freezes while doing heavy work. How do I offload that? +### 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. @@ -860,7 +873,7 @@ cheaper model for sub-agents via `agents.defaults.subagents.model`. Docs: [Sub-agents](/tools/subagents). -### Cron or reminders do not fire. What should I check? +### 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. @@ -878,7 +891,7 @@ clawdbot cron runs --id --limit 50 Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat). -### How do I install skills on Linux? +### How do I install skills on Linux Use **ClawdHub** (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux. Browse skills at https://clawdhub.com. @@ -893,7 +906,7 @@ npm i -g clawdhub pnpm add -g clawdhub ``` -### Can Clawdbot run tasks on a schedule or continuously in the background? +### Can Clawdbot run tasks on a schedule or continuously in the background Yes. Use the Gateway scheduler: @@ -904,7 +917,7 @@ Yes. Use the Gateway scheduler: Docs: [Cron jobs](/automation/cron-jobs), [Cron vs Heartbeat](/automation/cron-vs-heartbeat), [Heartbeat](/gateway/heartbeat). -### Is there a way to run Apple/macOS-only skills if my Gateway runs on Linux? +**Can I run Apple macOS only skills from Linux** Not directly. macOS skills are gated by `metadata.clawdbot.os` plus required binaries, and skills only appear in the system prompt when they are eligible on the **Gateway host**. On Linux, `darwin`-only skills (like `imsg`, `apple-notes`, `apple-reminders`) will not load unless you override the gating. @@ -938,7 +951,7 @@ Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wra For iMessage specifically, you can also point `channels.imessage.cliPath` at an SSH wrapper (Clawdbot only needs stdio). See [iMessage](/channels/imessage). -### Do you have a Notion or HeyGen integration? +### Do you have a Notion or HeyGen integration Not built‑in today. @@ -962,7 +975,7 @@ clawdhub update --all ClawdHub installs into `./skills` under your current directory (or falls back to your configured Clawdbot workspace); Clawdbot treats that as `/skills` on the next session. For shared skills across agents, place them in `~/.clawdbot/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 [ClawdHub](/tools/clawdhub). -### How do I install the Chrome extension for browser takeover? +### How do I install the Chrome extension for browser takeover Use the built-in installer, then load the unpacked extension in Chrome: @@ -980,11 +993,11 @@ You still need to click the extension button on the tab you want to control (it ## Sandboxing and memory -### Is there a dedicated sandboxing doc? +### 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). -### Can I keep DMs “personal” but make groups “public/sandboxed” with one agent? +**Can I keep DMs personal but make groups public sandboxed with one agent** Yes - if your private traffic is **DMs** and your public traffic is **groups**. @@ -994,11 +1007,11 @@ Setup walkthrough + example config: [Groups: personal DMs + public groups](/conc Key config reference: [Gateway configuration](/gateway/configuration#agentsdefaultssandbox) -### How do I bind a host folder into the sandbox? +### How do I bind a host folder into the sandbox Set `agents.defaults.sandbox.docker.binds` to `["host:path:mode"]` (e.g., `"/home/user/src:/src:ro"`). Global + per-agent binds merge; per-agent binds are ignored when `scope: "shared"`. Use `:ro` for anything sensitive and remember binds bypass the sandbox filesystem walls. See [Sandboxing](/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 does memory work? +### How does memory work Clawdbot memory is just Markdown files in the agent workspace: - Daily notes in `memory/YYYY-MM-DD.md` @@ -1008,7 +1021,7 @@ Clawdbot 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). -### Memory keeps forgetting things. How do I make it stick? +### 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`. @@ -1019,7 +1032,7 @@ workspace on every run. Docs: [Memory](/concepts/memory), [Agent workspace](/concepts/agent-workspace). -### Does semantic memory search require an OpenAI API key? +### 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 @@ -1039,9 +1052,18 @@ If you’d rather stay local, set `memorySearch.provider = "local"` (and optiona `memorySearch.remote.apiKey`). We support **OpenAI, Gemini, 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 Clawdbot saved locally? +### Is all data used with Clawdbot saved locally No - **Clawdbot’s state is local**, but **external services still see what you send them**. @@ -1055,7 +1077,7 @@ No - **Clawdbot’s state is local**, but **external services still see what you Related: [Agent workspace](/concepts/agent-workspace), [Memory](/concepts/memory). -### Where does Clawdbot store its data? +### Where does Clawdbot store its data Everything lives under `$CLAWDBOT_STATE_DIR` (default: `~/.clawdbot`): @@ -1074,7 +1096,7 @@ Legacy single‑agent path: `~/.clawdbot/agent/*` (migrated by `clawdbot doctor` Your **workspace** (AGENTS.md, memory files, skills, etc.) is separate and configured via `agents.defaults.workspace` (default: `~/clawd`). -### Where should AGENTS.md / SOUL.md / USER.md / MEMORY.md live? +### Where should AGENTSmd SOULmd USERmd MEMORYmd live These files live in the **agent workspace**, not `~/.clawdbot`. @@ -1100,7 +1122,7 @@ AGENTS.md or MEMORY.md** rather than relying on chat history. See [Agent workspace](/concepts/agent-workspace) and [Memory](/concepts/memory). -### What’s the recommended backup strategy? +### Whats 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 @@ -1112,11 +1134,11 @@ separately (see the migration question above). Docs: [Agent workspace](/concepts/agent-workspace). -### How do I completely uninstall Clawdbot? +### How do I completely uninstall Clawdbot See the dedicated guide: [Uninstall](/install/uninstall). -### Can agents work outside the workspace? +### 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 access other @@ -1138,13 +1160,13 @@ Example (repo as default cwd): } ``` -### I’m in remote mode - where is the session store? +### 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). ## Config basics -### What format is the config? Where is it? +### What format is the config Where is it Clawdbot reads an optional **JSON5** config from `$CLAWDBOT_CONFIG_PATH` (default: `~/.clawdbot/clawdbot.json`): @@ -1154,7 +1176,7 @@ $CLAWDBOT_CONFIG_PATH If the file is missing, it uses safe‑ish defaults (including a default workspace of `~/clawd`). -### 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 Non-loopback binds **require auth**. Configure `gateway.auth.mode` + `gateway.auth.token` (or use `CLAWDBOT_GATEWAY_TOKEN`). @@ -1174,20 +1196,20 @@ Notes: - `gateway.remote.token` is for **remote CLI calls** only; it does not enable local gateway auth. - 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? +### 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 calling the Gateway. Paste the token into the Control UI settings (or your client config) to connect. If you **really** want open loopback, remove `gateway.auth` from your config. Doctor can generate a token for you any time: `clawdbot doctor --generate-gateway-token`. -### Do I have to restart after changing config? +### 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`, `restart`, `off` are also supported -### How do I enable web search (and web fetch)? +### 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 `clawdbot configure --section web` to store it in @@ -1218,7 +1240,7 @@ Notes: Docs: [Web tools](/tools/web). -### How do I run a central Gateway with specialized workers across devices? +### 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**: @@ -1230,7 +1252,7 @@ The common pattern is **one Gateway** (e.g. Raspberry Pi) plus **nodes** and **a Docs: [Nodes](/nodes), [Remote access](/gateway/remote), [Multi-Agent Routing](/concepts/multi-agent), [Sub-agents](/tools/subagents), [TUI](/tui). -### Can the Clawdbot browser run headless? +### Can the Clawdbot browser run headless Yes. It’s a config option: @@ -1252,14 +1274,14 @@ Headless uses the **same Chromium engine** and works for most automation (forms, - 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? +### 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). ## Remote gateways + nodes -### How do commands propagate between Telegram, the gateway, 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: @@ -1268,7 +1290,7 @@ Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram 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? +### 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. @@ -1292,7 +1314,7 @@ 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). -### Tailscale is connected but I get no replies. What now? +### Tailscale is connected but I get no replies What now Check the basics: - Gateway is running: `clawdbot gateway status` @@ -1306,7 +1328,7 @@ Then verify auth and routing: Docs: [Tailscale](/gateway/tailscale), [Remote access](/gateway/remote), [Channels](/channels). -### Can two Clawdbots talk to each other (local + VPS)? +### Can two Clawdbots 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: @@ -1329,7 +1351,7 @@ allowlists, or a "do not reply to bot messages" rule). Docs: [Remote access](/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/tools/agent-send). -### 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 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 @@ -1347,7 +1369,7 @@ device automation. Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Chrome extension](/tools/chrome-extension). -### Should I install on a second laptop or just add a node? +### 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. Local node tools are @@ -1357,7 +1379,7 @@ Install a second Gateway only when you need **hard isolation** or two fully sepa Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes), [Multiple gateways](/gateway/multiple-gateways). -### Do nodes run a gateway service? +### Do nodes run a gateway service 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 @@ -1365,11 +1387,11 @@ hosts and CLI control, see [Node host CLI](/cli/node). A full restart is required for `gateway`, `discovery`, and `canvasHost` changes. -### Is there an API / RPC way to apply config? +### 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. -### config.apply wiped my config. How do I recover and avoid this? +### 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. @@ -1386,7 +1408,7 @@ Avoid it: Docs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doctor). -### What’s a minimal “sane” config for a first install? +### Whats a minimal sane config for a first install ```json5 { @@ -1397,7 +1419,7 @@ Docs: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/gateway/doct This sets your workspace and restricts who can trigger the bot. -### 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 Minimal steps: @@ -1420,7 +1442,7 @@ clawdbot 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)? +### 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. @@ -1438,7 +1460,7 @@ Docs: [Gateway protocol](/gateway/protocol), [Discovery](/gateway/discovery), [m ## Env vars and .env loading -### How does Clawdbot load environment variables? +### How does Clawdbot load environment variables Clawdbot reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads: @@ -1460,7 +1482,7 @@ You can also define inline env vars in config (applied only if missing from the See [/environment](/environment) for full precedence and sources. -### “I started the Gateway via a service and my env vars disappeared.” What now? +### I started the Gateway via the service and my env vars disappeared What now Two common fixes: @@ -1481,7 +1503,7 @@ Two common fixes: This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents: `CLAWDBOT_LOAD_SHELL_ENV=1`, `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`. -### I set `COPILOT_GITHUB_TOKEN`, but models status shows “Shell env: off.” Why? +### I set COPILOTGITHUBTOKEN but models status shows Shell env off Why `clawdbot models status` reports whether **shell env import** is enabled. “Shell env: off” does **not** mean your env vars are missing - it just means Clawdbot won’t load @@ -1507,11 +1529,11 @@ See [/concepts/model-providers](/concepts/model-providers) and [/environment](/e ## Sessions & multiple chats -### How do I start a fresh conversation? +### How do I start a fresh conversation Send `/new` or `/reset` as a standalone message. See [Session management](/concepts/session). -### Do sessions reset automatically if I never send `/new`? +### 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 @@ -1525,7 +1547,31 @@ transcripts - it just starts a new session. } ``` -### How do I completely reset Clawdbot but keep it installed? +### Is there a way to make a team of Clawdbots 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 Clawdbot but keep it installed Use the reset command: @@ -1550,7 +1596,7 @@ Notes: - If you used profiles (`--profile` / `CLAWDBOT_PROFILE`), reset each state dir (defaults are `~/.clawdbot-`). - Dev reset: `clawdbot gateway --dev --reset` (dev-only; wipes dev config + credentials + sessions + workspace). -### 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 Use one of these: @@ -1572,7 +1618,7 @@ If it keeps happening: Docs: [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning), [Session management](/concepts/session). -### Why am I seeing “LLM request rejected: messages.N.content.X.tool_use.input: Field required”? +### Why am I seeing LLM request rejected messagesNcontentXtooluseinput Field required 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 @@ -1580,7 +1626,7 @@ or a tool/schema change). Fix: start a fresh session with `/new` (standalone message). -### Why am I getting heartbeat messages every 30 minutes? +### Why am I getting heartbeat messages every 30 minutes Heartbeats run every **30m** by default. Tune or disable them: @@ -1602,7 +1648,7 @@ If the file is missing, the heartbeat still runs and the model decides what to d Per-agent overrides use `agents.list[].heartbeat`. Docs: [Heartbeat](/gateway/heartbeat). -### Do I need to add a “bot account” to a WhatsApp group? +### Do I need to add a bot account to a WhatsApp group No. Clawdbot runs on **your own account**, so if you’re in the group, Clawdbot can see it. By default, group replies are blocked until you allow senders (`groupPolicy: "allowlist"`). @@ -1620,7 +1666,7 @@ If you want only **you** to be able to trigger group replies: } ``` -### How do I get the JID of a WhatsApp group? +### How do I get the JID of a WhatsApp group Option 1 (fastest): tail logs and send a test message in the group: @@ -1639,7 +1685,7 @@ clawdbot directory groups list --channel whatsapp Docs: [WhatsApp](/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). -### Why doesn’t Clawdbot reply in a group? +### Why doesnt Clawdbot reply in a group Two common causes: - Mention gating is on (default). You must @mention the bot (or match `mentionPatterns`). @@ -1647,11 +1693,11 @@ Two common causes: See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages). -### Do groups/threads share context with DMs? +### 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 sessions. See [Groups](/concepts/groups) and [Group messages](/concepts/group-messages). -### How many workspaces and agents can I create? +### How many workspaces and agents can I create No hard limits. Dozens (even hundreds) are fine, but watch for: @@ -1664,7 +1710,7 @@ Tips: - Prune old sessions (delete JSONL or store entries) if disk grows. - Use `clawdbot doctor` to spot stray workspaces and profile mismatches. -### 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 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. @@ -1684,7 +1730,7 @@ Docs: [Multi‑Agent Routing](/concepts/multi-agent), [Slack](/channels/slack), ## Models: defaults, selection, aliases, switching -### What is the “default model”? +### What is the default model Clawdbot’s default model is whatever you set as: @@ -1694,7 +1740,7 @@ agents.defaults.model.primary Models are referenced as `provider/model` (example: `anthropic/claude-opus-4-5`). If you omit the provider, Clawdbot currently assumes `anthropic` as a temporary deprecation fallback - but you should still **explicitly** set `provider/model`. -### What model do you recommend? +### What model do you recommend **Recommended default:** `anthropic/claude-opus-4-5`. **Good alternative:** `anthropic/claude-sonnet-4-5`. @@ -1714,7 +1760,7 @@ injection and unsafe behavior. See [Security](/gateway/security). More context: [Models](/concepts/models). -### Can I use self-hosted models (llama.cpp, vLLM, Ollama)? +### 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 path. @@ -1727,7 +1773,7 @@ Docs: [Ollama](/providers/ollama), [Local models](/gateway/local-models), [Model providers](/concepts/model-providers), [Security](/gateway/security), [Sandboxing](/gateway/sandboxing). -### How do I switch models without wiping my config? +### How do I switch models without wiping my config Use **model commands** or edit only the **model** fields. Avoid full config replaces. @@ -1742,12 +1788,12 @@ If you did overwrite config, restore from backup or re-run `clawdbot doctor` to Docs: [Models](/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/gateway/doctor). -### What do Clawd, Flawd, and Krill use for models? +### What do Clawd Flawd and Krill use for models - **Clawd + Flawd:** Anthropic Opus (`anthropic/claude-opus-4-5`) - see [Anthropic](/providers/anthropic). - **Krill:** MiniMax M2.1 (`minimax/MiniMax-M2.1`) - see [MiniMax](/providers/minimax). -### How do I switch models on the fly (without restarting)? +### How do I switch models on the fly without restarting Use the `/model` command as a standalone message: @@ -1779,7 +1825,7 @@ 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. -### How do I unpin a profile I set with `@profile`? +**How do I unpin a profile I set with profile** Re-run `/model` **without** the `@profile` suffix: @@ -1790,7 +1836,7 @@ 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. -### Why do I see “Model … is not allowed” and then no reply? +### 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: @@ -1802,7 +1848,7 @@ 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`. -### Why do I see “Unknown model: minimax/MiniMax-M2.1”? +### 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 detection is @@ -1822,7 +1868,7 @@ Fix checklist: See [MiniMax](/providers/minimax) and [Models](/concepts/models). -### Can I use MiniMax as my default and OpenAI for complex tasks? +### 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 agent. @@ -1855,7 +1901,7 @@ Then: Docs: [Models](/concepts/models), [Multi-Agent Routing](/concepts/multi-agent), [MiniMax](/providers/minimax), [OpenAI](/providers/openai). -### Are opus / sonnet / gpt built‑in shortcuts? +### Are opus sonnet gpt builtin shortcuts Yes. Clawdbot ships a few default shorthands (only applied when the model exists in `agents.defaults.models`): @@ -1868,7 +1914,7 @@ Yes. Clawdbot ships a few default shorthands (only applied when the model exists If you set your own alias with the same name, your value wins. -### How do I define/override model shortcuts (aliases)? +### How do I defineoverride model shortcuts aliases Aliases come from `agents.defaults.models..alias`. Example: @@ -1889,7 +1935,7 @@ Aliases come from `agents.defaults.models..alias`. Example: Then `/model sonnet` (or `/` when supported) resolves to that model ID. -### 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 OpenRouter (pay‑per‑token; many models): @@ -1921,7 +1967,7 @@ Z.AI (GLM models): 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: @@ -1938,7 +1984,7 @@ Do **not** reuse `agentDir` across agents; it causes auth/session collisions. ## Model failover and “All models failed” -### How does failover work? +### How does failover work Failover happens in two stages: @@ -1947,7 +1993,7 @@ Failover happens in two stages: Cooldowns apply to failing profiles (exponential backoff), so Clawdbot can keep responding even when a provider is rate‑limited or temporarily failing. -### What does this error mean? +### What does this error mean ``` No credentials found for profile "anthropic:default" @@ -1955,7 +2001,7 @@ No credentials found for profile "anthropic:default" 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. -### Fix checklist for `No credentials found for profile "anthropic:default"` +### Fix checklist for No credentials found for profile anthropicdefault - **Confirm where auth profiles live** (new vs legacy paths) - Current: `~/.clawdbot/agents//agent/auth-profiles.json` @@ -1967,7 +2013,7 @@ It means the system attempted to use the auth profile ID `anthropic:default`, bu - **Sanity‑check model/auth status** - Use `clawdbot models status` to see configured models and whether providers are authenticated. -### Fix checklist for `No credentials found for profile "anthropic:claude-cli"` +**Fix checklist for No credentials found for profile anthropic claude cli** This means the run is pinned to the **Claude Code CLI** profile, but the Gateway can’t find that profile in its auth store. @@ -1988,13 +2034,13 @@ can’t find that profile in its auth store. - **Confirm you’re running commands on the gateway host** - In remote mode, auth profiles live on the gateway machine, not your laptop. -### Why did it also try Google Gemini and fail? +### 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), Clawdbot will try it during model fallback. If you haven’t configured Google credentials, you’ll see `No API key found for provider "google"`. Fix: either provide Google auth, or remove/avoid Google models in `agents.defaults.model.fallbacks` / aliases so fallback doesn’t route there. -### “LLM request rejected: messages.*.thinking.signature required (google‑antigravity)” +**LLM request rejected message thinking signature required google antigravity** Cause: the session history contains **thinking blocks without signatures** (often from an aborted/partial stream). Google Antigravity requires signatures for thinking blocks. @@ -2005,7 +2051,7 @@ Fix: Clawdbot now strips unsigned thinking blocks for Google Antigravity Claude. Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-account patterns, CLI sync) -### What is an auth profile? +### What is an auth profile An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in: @@ -2013,7 +2059,7 @@ An auth profile is a named credential record (OAuth or API key) tied to a provid ~/.clawdbot/agents//agent/auth-profiles.json ``` -### What are typical profile IDs? +### What are typical profile IDs Clawdbot uses provider‑prefixed IDs like: @@ -2021,7 +2067,7 @@ Clawdbot uses provider‑prefixed IDs like: - `anthropic:` for OAuth identities - custom IDs you choose (e.g. `anthropic:work`) -### Can I control which auth profile is tried first? +### 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. @@ -2049,7 +2095,7 @@ To target a specific agent: clawdbot models auth order set --provider anthropic --agent main anthropic:claude-cli ``` -### OAuth vs API key: what’s the difference? +### OAuth vs API key whats the difference Clawdbot supports both: @@ -2060,7 +2106,7 @@ The wizard explicitly supports Anthropic OAuth and OpenAI Codex OAuth and can st ## Gateway: ports, “already running”, and remote mode -### What port does the Gateway use? +### What port does the Gateway use `gateway.port` controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.). @@ -2070,7 +2116,7 @@ Precedence: --port > CLAWDBOT_GATEWAY_PORT > gateway.port > default 18789 ``` -### Why does `clawdbot gateway status` say `Runtime: running` but `RPC probe: failed`? +### Why does clawdbot 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`. @@ -2079,7 +2125,7 @@ Use `clawdbot gateway status` and trust these lines: - `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 `clawdbot gateway status` show `Config (cli)` and `Config (service)` different? +### Why does clawdbot gateway status show Config cli and Config service different You’re editing one config file while the service is running another (often a `--profile` / `CLAWDBOT_STATE_DIR` mismatch). @@ -2089,13 +2135,13 @@ clawdbot gateway install --force ``` Run that from the same `--profile` / environment you want the service to use. -### What does “another gateway instance is already listening” mean? +### What does another gateway instance is already listening mean Clawdbot 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 `clawdbot gateway --port `. -### How do I run Clawdbot in remote mode (client connects to a Gateway elsewhere)? +### How do I run Clawdbot 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: @@ -2116,7 +2162,7 @@ Notes: - `clawdbot 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? +### 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. @@ -2132,7 +2178,7 @@ Fix: - In the Control UI settings, paste the same token (or refresh with a one-time `?token=...` link). - Still stuck? Run `clawdbot status --all` and follow [Troubleshooting](/gateway/troubleshooting). See [Dashboard](/web/dashboard) for auth details. -### I set `gateway.bind: "tailnet"` but it can’t bind / nothing listens +### 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 nothing to bind to. @@ -2142,7 +2188,7 @@ Fix: 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? +### 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. @@ -2161,7 +2207,7 @@ Quick setup (recommended): Profiles also suffix service names (`com.clawdbot.`, `clawdbot-gateway-.service`, `Clawdbot Gateway ()`). Full guide: [Multiple gateways](/gateway/multiple-gateways). -### What does “invalid handshake” / code 1008 mean? +### 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 @@ -2186,7 +2232,7 @@ Protocol details: [Gateway protocol](/gateway/protocol). ## Logging and debugging -### Where are logs? +### Where are logs File logs (structured): @@ -2209,7 +2255,7 @@ Service/supervisor logs (when the gateway runs via launchd/systemd): See [Troubleshooting](/gateway/troubleshooting#log-locations) for more. -### How do I start/stop/restart the Gateway service? +### How do I startstoprestart the Gateway service Use the gateway helpers: @@ -2220,7 +2266,7 @@ clawdbot gateway restart If you run the gateway manually, `clawdbot gateway --force` can reclaim the port. See [Gateway](/gateway). -### I closed my terminal on Windows - how do I restart Clawdbot? +### I closed my terminal on Windows how do I restart Clawdbot There are **two Windows install modes**: @@ -2257,7 +2303,7 @@ clawdbot gateway run Docs: [Windows (WSL2)](/platforms/windows), [Gateway service runbook](/gateway). -### The Gateway is up but replies never arrive. What should I check? +### The Gateway is up but replies never arrive What should I check Start with a quick health sweep: @@ -2278,7 +2324,7 @@ Gateway WebSocket is reachable. Docs: [Channels](/channels), [Troubleshooting](/gateway/troubleshooting), [Remote access](/gateway/remote). -### "Disconnected from gateway: no reason" - what now? +### Disconnected from gateway no reason what now This usually means the UI lost the WebSocket connection. Check: @@ -2295,7 +2341,7 @@ clawdbot logs --follow Docs: [Dashboard](/web/dashboard), [Remote access](/gateway/remote), [Troubleshooting](/gateway/troubleshooting). -### Telegram setMyCommands fails with network errors. What should I check? +### Telegram setMyCommands fails with network errors What should I check Start with logs and channel status: @@ -2309,7 +2355,7 @@ If the Gateway is remote, make sure you are looking at logs on the Gateway host. Docs: [Telegram](/channels/telegram), [Channel troubleshooting](/channels/troubleshooting). -### TUI shows no output. What should I check? +### TUI shows no output What should I check First confirm the Gateway is reachable and the agent can run: @@ -2324,7 +2370,7 @@ channel, make sure delivery is enabled (`/deliver on`). Docs: [TUI](/tui), [Slash commands](/tools/slash-commands). -### How do I completely stop then start the Gateway? +### How do I completely stop then start the Gateway If you installed the service: @@ -2344,7 +2390,7 @@ clawdbot gateway run Docs: [Gateway service runbook](/gateway). -### ELI5: `clawdbot gateway restart` vs `clawdbot gateway` +### ELI5 clawdbot gateway restart vs clawdbot gateway - `clawdbot gateway restart`: restarts the **background service** (launchd/systemd). - `clawdbot gateway`: runs the gateway **in the foreground** for this terminal session. @@ -2352,13 +2398,13 @@ Docs: [Gateway service runbook](/gateway). If you installed the service, use the gateway commands. Use `clawdbot gateway` when you want a one-off, foreground run. -### What’s the fastest way to get more details when something fails? +### Whats 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 image/PDF, but nothing was sent +### My skill generated an imagePDF but nothing was sent Outbound attachments from the agent must include a `MEDIA:` line (on its own line). See [Clawdbot assistant setup](/start/clawd) and [Agent send](/tools/agent-send). @@ -2376,7 +2422,7 @@ See [Images](/nodes/images). ## Security and access control -### Is it safe to expose Clawdbot to inbound DMs? +### Is it safe to expose Clawdbot to inbound DMs Treat inbound DMs as untrusted input. Defaults are designed to reduce risk: @@ -2388,7 +2434,7 @@ Treat inbound DMs as untrusted input. Defaults are designed to reduce risk: Run `clawdbot doctor` to surface risky DM policies. -### Is prompt injection only a concern for public bots? +### 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, @@ -2403,14 +2449,14 @@ exfiltrating context or calling tools on your behalf. Reduce the blast radius by Details: [Security](/gateway/security). -### Can I use cheaper models for personal assistant tasks? +### 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). -### I ran `/start` in Telegram but didn’t get a pairing code +### I ran start in Telegram but didnt get a pairing code 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. @@ -2423,7 +2469,7 @@ clawdbot pairing list telegram If you want immediate access, allowlist your sender id or set `dmPolicy: "open"` for that account. -### WhatsApp: will it message my contacts? How does pairing work? +### WhatsApp will it message my contacts How does pairing work No. Default WhatsApp DM policy is **pairing**. Unknown senders only get a pairing code and their message is **not processed**. Clawdbot only replies to chats it receives or to explicit sends you trigger. @@ -2443,7 +2489,7 @@ Wizard phone number prompt: it’s used to set your **allowlist/owner** so your ## Chat commands, aborting tasks, and “it won’t stop” -### How do I stop/cancel a running task? +### How do I stopcancel a running task Send any of these **as a standalone message** (no slash): @@ -2468,7 +2514,7 @@ 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. -### 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 Clawdbot 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. @@ -2495,7 +2541,7 @@ Enable cross‑provider messaging for the agent: 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” rapid‑fire messages? +### 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: