# Table of Contents - [Index - Clawdbot](#index-clawdbot) - [Page Not Found](#page-not-found) - [Index - Clawdbot](#index-clawdbot) - [Index - Clawdbot](#index-clawdbot) - [Index - Clawdbot](#index-clawdbot) - [Index - Clawdbot](#index-clawdbot) - [Index - Clawdbot](#index-clawdbot) - [Bluebubbles - Clawdbot](#bluebubbles-clawdbot) - [Nextcloud talk - Clawdbot](#nextcloud-talk-clawdbot) - [Nostr - Clawdbot](#nostr-clawdbot) - [Index - Clawdbot](#index-clawdbot) - [Tts - Clawdbot](#tts-clawdbot) - [Cron add hardening - Clawdbot](#cron-add-hardening-clawdbot) - [Tlon - Clawdbot](#tlon-clawdbot) - [Webhooks - Clawdbot](#webhooks-clawdbot) - [Brave search - Clawdbot](#brave-search-clawdbot) - [Perplexity - Clawdbot](#perplexity-clawdbot) - [Node - Clawdbot](#node-clawdbot) - [Devices - Clawdbot](#devices-clawdbot) - [Config - Clawdbot](#config-clawdbot) - [Firecrawl - Clawdbot](#firecrawl-clawdbot) - [Acp - Clawdbot](#acp-clawdbot) - [Vercel ai gateway - Clawdbot](#vercel-ai-gateway-clawdbot) - [Agent tools - Clawdbot](#agent-tools-clawdbot) - [Group policy hardening - Clawdbot](#group-policy-hardening-clawdbot) - [Qwen - Clawdbot](#qwen-clawdbot) - [Model config - Clawdbot](#model-config-clawdbot) - [Transcript hygiene - Clawdbot](#transcript-hygiene-clawdbot) - [Onboarding config protocol - Clawdbot](#onboarding-config-protocol-clawdbot) - [Memory - Clawdbot](#memory-clawdbot) - [Ollama - Clawdbot](#ollama-clawdbot) - [Manifest - Clawdbot](#manifest-clawdbot) - [Date time - Clawdbot](#date-time-clawdbot) - [Prose - Clawdbot](#prose-clawdbot) - [Index - Clawdbot](#index-clawdbot) - [Deepgram - Clawdbot](#deepgram-clawdbot) - [Openresponses http api - Clawdbot](#openresponses-http-api-clawdbot) - [Logging - Clawdbot](#logging-clawdbot) - [Network - Clawdbot](#network-clawdbot) - [Exec approvals - Clawdbot](#exec-approvals-clawdbot) - [Page Not Found](#page-not-found) --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... Ctrl K Search... Navigation On this page * [Clawdbot ๐Ÿฆž](https://docs.clawd.bot/#clawdbot-%F0%9F%A6%9E) * [Start here](https://docs.clawd.bot/#start-here) * [Dashboard (browser Control UI)](https://docs.clawd.bot/#dashboard-browser-control-ui) * [How it works](https://docs.clawd.bot/#how-it-works) * [Network model](https://docs.clawd.bot/#network-model) * [Features (high level)](https://docs.clawd.bot/#features-high-level) * [Quick start](https://docs.clawd.bot/#quick-start) * [Configuration (optional)](https://docs.clawd.bot/#configuration-optional) * [Docs](https://docs.clawd.bot/#docs) * [The name](https://docs.clawd.bot/#the-name) * [Credits](https://docs.clawd.bot/#credits) * [Core Contributors](https://docs.clawd.bot/#core-contributors) * [License](https://docs.clawd.bot/#license) [โ€‹](https://docs.clawd.bot/#clawdbot-%F0%9F%A6%9E) Clawdbot ๐Ÿฆž ================================================================= > _โ€œEXFOLIATE! EXFOLIATE!โ€_ โ€” A space lobster, probably ![Clawdbot](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/whatsapp-clawd.jpg?w=2500&fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=facbfb9b42b052ba6ce500858ab753d0) **Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).** Plugins add Mattermost and more. Send a message, get an agent response โ€” from your pocket. [GitHub](https://github.com/clawdbot/clawdbot) ยท [Releases](https://github.com/clawdbot/clawdbot/releases) ยท [Docs](https://docs.clawd.bot/) ยท [Clawdbot assistant setup](https://docs.clawd.bot/start/clawd) Clawdbot bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono) . Plugins add Mattermost (Bot API + WebSocket) and more. Clawdbot also powers [Clawd](https://clawd.me/) , the spaceโ€‘lobster assistant. [โ€‹](https://docs.clawd.bot/#start-here) Start here ----------------------------------------------------- * **New install from zero:** [Getting Started](https://docs.clawd.bot/start/getting-started) * **Guided setup (recommended):** [Wizard](https://docs.clawd.bot/start/wizard) (`clawdbot onboard`) * **Open the dashboard (local Gateway):** [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (or [http://localhost:18789/](http://localhost:18789/) ) If the Gateway is running on the same computer, that link opens the browser Control UI immediately. If it fails, start the Gateway first: `clawdbot gateway`. [โ€‹](https://docs.clawd.bot/#dashboard-browser-control-ui) Dashboard (browser Control UI) ------------------------------------------------------------------------------------------- The dashboard is the browser Control UI for chat, config, nodes, sessions, and more. Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/) Remote access: [Web surfaces](https://docs.clawd.bot/web) and [Tailscale](https://docs.clawd.bot/gateway/tailscale) [โ€‹](https://docs.clawd.bot/#how-it-works) How it works --------------------------------------------------------- Copy WhatsApp / Telegram / Discord / iMessage (+ plugins) โ”‚ โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Gateway โ”‚ ws://127.0.0.1:18789 (loopback-only) โ”‚ (single source) โ”‚ โ”‚ โ”‚ http://:18793 โ”‚ โ”‚ /__clawdbot__/canvas/ (Canvas host) โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”œโ”€ Pi agent (RPC) โ”œโ”€ CLI (clawdbot โ€ฆ) โ”œโ”€ Chat UI (SwiftUI) โ”œโ”€ macOS app (Clawdbot.app) โ”œโ”€ iOS node via Gateway WS + pairing โ””โ”€ Android node via Gateway WS + pairing Most operations flow through the **Gateway** (`clawdbot gateway`), a single long-running process that owns channel connections and the WebSocket control plane. [โ€‹](https://docs.clawd.bot/#network-model) Network model ----------------------------------------------------------- * **One Gateway per host (recommended)**: it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see [Multiple gateways](https://docs.clawd.bot/gateway/multiple-gateways) . * **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`. * The wizard now generates a gateway token by default (even for loopback). * For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds). * **Nodes**: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed. * **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [Gateway configuration](https://docs.clawd.bot/gateway/configuration) (`canvasHost`). * **Remote use**: SSH tunnel or tailnet/VPN; see [Remote access](https://docs.clawd.bot/gateway/remote) and [Discovery](https://docs.clawd.bot/gateway/discovery) . [โ€‹](https://docs.clawd.bot/#features-high-level) Features (high level) ------------------------------------------------------------------------- * ๐Ÿ“ฑ **WhatsApp Integration** โ€” Uses Baileys for WhatsApp Web protocol * โœˆ๏ธ **Telegram Bot** โ€” DMs + groups via grammY * ๐ŸŽฎ **Discord Bot** โ€” DMs + guild channels via channels.discord.js * ๐Ÿงฉ **Mattermost Bot (plugin)** โ€” Bot token + WebSocket events * ๐Ÿ’ฌ **iMessage** โ€” Local imsg CLI integration (macOS) * ๐Ÿค– **Agent bridge** โ€” Pi (RPC mode) with tool streaming * โฑ๏ธ **Streaming + chunking** โ€” Block streaming + Telegram draft streaming details ([/concepts/streaming](https://docs.clawd.bot/concepts/streaming) ) * ๐Ÿง  **Multi-agent routing** โ€” Route provider accounts/peers to isolated agents (workspace + per-agent sessions) * ๐Ÿ” **Subscription auth** โ€” Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth * ๐Ÿ’ฌ **Sessions** โ€” Direct chats collapse into shared `main` (default); groups are isolated * ๐Ÿ‘ฅ **Group Chat Support** โ€” Mention-based by default; owner can toggle `/activation always|mention` * ๐Ÿ“Ž **Media Support** โ€” Send and receive images, audio, documents * ๐ŸŽค **Voice notes** โ€” Optional transcription hook * ๐Ÿ–ฅ๏ธ **WebChat + macOS app** โ€” Local UI + menu bar companion for ops and voice wake * ๐Ÿ“ฑ **iOS node** โ€” Pairs as a node and exposes a Canvas surface * ๐Ÿ“ฑ **Android node** โ€” Pairs as a node and exposes Canvas + Chat + Camera Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path. [โ€‹](https://docs.clawd.bot/#quick-start) Quick start ------------------------------------------------------- Runtime requirement: **Node โ‰ฅ 22**. Copy # Recommended: global install (npm/pnpm) npm install -g clawdbot@latest # or: pnpm add -g clawdbot@latest # Onboard + install the service (launchd/systemd user service) clawdbot onboard --install-daemon # Pair WhatsApp Web (shows QR) clawdbot channels login # Gateway runs via the service after onboarding; manual run is still possible: clawdbot gateway --port 18789 Switching between npm and git installs later is easy: install the other flavor and run `clawdbot doctor` to update the gateway service entrypoint. From source (development): Copy git clone https://github.com/clawdbot/clawdbot.git cd clawdbot pnpm install pnpm ui:build # auto-installs UI deps on first run pnpm build clawdbot onboard --install-daemon If you donโ€™t have a global install yet, run the onboarding step via `pnpm clawdbot ...` from the repo. Multi-instance quickstart (optional): Copy CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \ CLAWDBOT_STATE_DIR=~/.clawdbot-a \ clawdbot gateway --port 19001 Send a test message (requires a running Gateway): Copy clawdbot message send --target +15555550123 --message "Hello from Clawdbot" [โ€‹](https://docs.clawd.bot/#configuration-optional) Configuration (optional) ------------------------------------------------------------------------------- Config lives at `~/.clawdbot/clawdbot.json`. * If you **do nothing**, Clawdbot uses the bundled Pi binary in RPC mode with per-sender sessions. * If you want to lock it down, start with `channels.whatsapp.allowFrom` and (for groups) mention rules. Example: Copy { channels: { whatsapp: { allowFrom: ["+15555550123"], groups: { "*": { requireMention: true } } } }, messages: { groupChat: { mentionPatterns: ["@clawd"] } } } [โ€‹](https://docs.clawd.bot/#docs) Docs ----------------------------------------- * Start here: * [Docs hubs (all pages linked)](https://docs.clawd.bot/start/hubs) * [Help](https://docs.clawd.bot/help) โ† _common fixes + troubleshooting_ * [Configuration](https://docs.clawd.bot/gateway/configuration) * [Configuration examples](https://docs.clawd.bot/gateway/configuration-examples) * [Slash commands](https://docs.clawd.bot/tools/slash-commands) * [Multi-agent routing](https://docs.clawd.bot/concepts/multi-agent) * [Updating / rollback](https://docs.clawd.bot/install/updating) * [Pairing (DM + nodes)](https://docs.clawd.bot/start/pairing) * [Nix mode](https://docs.clawd.bot/install/nix) * [Clawdbot assistant setup (Clawd)](https://docs.clawd.bot/start/clawd) * [Skills](https://docs.clawd.bot/tools/skills) * [Skills config](https://docs.clawd.bot/tools/skills-config) * [Workspace templates](https://docs.clawd.bot/reference/templates/AGENTS) * [RPC adapters](https://docs.clawd.bot/reference/rpc) * [Gateway runbook](https://docs.clawd.bot/gateway) * [Nodes (iOS/Android)](https://docs.clawd.bot/nodes) * [Web surfaces (Control UI)](https://docs.clawd.bot/web) * [Discovery + transports](https://docs.clawd.bot/gateway/discovery) * [Remote access](https://docs.clawd.bot/gateway/remote) * Providers and UX: * [WebChat](https://docs.clawd.bot/web/webchat) * [Control UI (browser)](https://docs.clawd.bot/web/control-ui) * [Telegram](https://docs.clawd.bot/channels/telegram) * [Discord](https://docs.clawd.bot/channels/discord) * [Mattermost (plugin)](https://docs.clawd.bot/channels/mattermost) * [iMessage](https://docs.clawd.bot/channels/imessage) * [Groups](https://docs.clawd.bot/concepts/groups) * [WhatsApp group messages](https://docs.clawd.bot/concepts/group-messages) * [Media: images](https://docs.clawd.bot/nodes/images) * [Media: audio](https://docs.clawd.bot/nodes/audio) * Companion apps: * [macOS app](https://docs.clawd.bot/platforms/macos) * [iOS app](https://docs.clawd.bot/platforms/ios) * [Android app](https://docs.clawd.bot/platforms/android) * [Windows (WSL2)](https://docs.clawd.bot/platforms/windows) * [Linux app](https://docs.clawd.bot/platforms/linux) * Ops and safety: * [Sessions](https://docs.clawd.bot/concepts/session) * [Cron jobs](https://docs.clawd.bot/automation/cron-jobs) * [Webhooks](https://docs.clawd.bot/automation/webhook) * [Gmail hooks (Pub/Sub)](https://docs.clawd.bot/automation/gmail-pubsub) * [Security](https://docs.clawd.bot/gateway/security) * [Troubleshooting](https://docs.clawd.bot/gateway/troubleshooting) [โ€‹](https://docs.clawd.bot/#the-name) The name ------------------------------------------------- **Clawdbot = CLAW + TARDIS** โ€” because every space lobster needs a time-and-space machine. * * * _โ€œWeโ€™re all just playing with our own prompts.โ€_ โ€” an AI, probably high on tokens [โ€‹](https://docs.clawd.bot/#credits) Credits ----------------------------------------------- * **Peter Steinberger** ([@steipete](https://twitter.com/steipete) ) โ€” Creator, lobster whisperer * **Mario Zechner** ([@badlogicc](https://twitter.com/badlogicgames) ) โ€” Pi creator, security pen-tester * **Clawd** โ€” The space lobster who demanded a better name [โ€‹](https://docs.clawd.bot/#core-contributors) Core Contributors ------------------------------------------------------------------- * **Maxim Vovshin** (@Hyaxia, [36747317+Hyaxia@users.noreply.github.com](mailto:36747317+Hyaxia@users.noreply.github.com) ) โ€” Blogwatcher skill * **Nacho Iacovino** (@nachoiacovino, [nacho.iacovino@gmail.com](mailto:nacho.iacovino@gmail.com) ) โ€” Location parsing (Telegram + WhatsApp) [โ€‹](https://docs.clawd.bot/#license) License ----------------------------------------------- MIT โ€” Free as a lobster in the ocean ๐Ÿฆž * * * _โ€œWeโ€™re all just playing with our own prompts.โ€_ โ€” An AI, probably high on tokens [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/index.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/) [Getting started](https://docs.clawd.bot/start/getting-started) Ctrl+I Assistant Responses are generated using AI and may contain mistakes. ![Clawdbot](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/whatsapp-clawd.jpg?w=2500&fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=facbfb9b42b052ba6ce500858ab753d0) --- # Page Not Found [Skip to main content](https://docs.clawd.bot/channels/googlechat#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation Channels Page Not Found 404 Page Not Found ============== We couldn't find the page. Maybe you were looking for one of these pages below? [Configuration](https://docs.clawd.bot/gateway/configuration#channels-googlechat-chat-api-webhook) [Msteams](https://docs.clawd.bot/channels/msteams#team-and-channel-ids-common-gotcha) [Message](https://docs.clawd.bot/cli/message#usage) โŒ˜I --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/platforms#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Platforms](https://docs.clawd.bot/platforms#platforms) * [Choose your OS](https://docs.clawd.bot/platforms#choose-your-os) * [VPS & hosting](https://docs.clawd.bot/platforms#vps-%26-hosting) * [Common links](https://docs.clawd.bot/platforms#common-links) * [Gateway service install (CLI)](https://docs.clawd.bot/platforms#gateway-service-install-cli) [โ€‹](https://docs.clawd.bot/platforms#platforms) Platforms ============================================================ Clawdbot core is written in TypeScript. **Node is the recommended runtime**. Bun is not recommended for the Gateway (WhatsApp/Telegram bugs). Companion apps exist for macOS (menu bar app) and mobile nodes (iOS/Android). Windows and Linux companion apps are planned, but the Gateway is fully supported today. Native companion apps for Windows are also planned; the Gateway is recommended via WSL2. [โ€‹](https://docs.clawd.bot/platforms#choose-your-os) Choose your OS ---------------------------------------------------------------------- * macOS: [macOS](https://docs.clawd.bot/platforms/macos) * iOS: [iOS](https://docs.clawd.bot/platforms/ios) * Android: [Android](https://docs.clawd.bot/platforms/android) * Windows: [Windows](https://docs.clawd.bot/platforms/windows) * Linux: [Linux](https://docs.clawd.bot/platforms/linux) [โ€‹](https://docs.clawd.bot/platforms#vps-&-hosting) VPS & hosting -------------------------------------------------------------------- * Fly.io: [Fly.io](https://docs.clawd.bot/platforms/fly) * Hetzner (Docker): [Hetzner](https://docs.clawd.bot/platforms/hetzner) * exe.dev (VM + HTTPS proxy): [exe.dev](https://docs.clawd.bot/platforms/exe-dev) [โ€‹](https://docs.clawd.bot/platforms#common-links) Common links ------------------------------------------------------------------ * Install guide: [Getting Started](https://docs.clawd.bot/start/getting-started) * Gateway runbook: [Gateway](https://docs.clawd.bot/gateway) * Gateway configuration: [Configuration](https://docs.clawd.bot/gateway/configuration) * Service status: `clawdbot gateway status` [โ€‹](https://docs.clawd.bot/platforms#gateway-service-install-cli) Gateway service install (CLI) -------------------------------------------------------------------------------------------------- Use one of these (all supported): * Wizard (recommended): `clawdbot onboard --install-daemon` * Direct: `clawdbot gateway install` * Configure flow: `clawdbot configure` โ†’ select **Gateway service** * Repair/migrate: `clawdbot doctor` (offers to install or fix the service) The service target depends on OS: * macOS: LaunchAgent (`com.clawdbot.gateway` or `com.clawdbot.`) * Linux/WSL2: systemd user service (`clawdbot-gateway[-].service`) [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/platforms.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/platforms) [Talk](https://docs.clawd.bot/nodes/talk) [Macos](https://docs.clawd.bot/platforms/macos) โŒ˜I --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/web#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Web (Gateway)](https://docs.clawd.bot/web#web-gateway) * [Webhooks](https://docs.clawd.bot/web#webhooks) * [Config (default-on)](https://docs.clawd.bot/web#config-default-on) * [Tailscale access](https://docs.clawd.bot/web#tailscale-access) * [Integrated Serve (recommended)](https://docs.clawd.bot/web#integrated-serve-recommended) * [Tailnet bind + token](https://docs.clawd.bot/web#tailnet-bind-%2B-token) * [Public internet (Funnel)](https://docs.clawd.bot/web#public-internet-funnel) * [Security notes](https://docs.clawd.bot/web#security-notes) * [Building the UI](https://docs.clawd.bot/web#building-the-ui) [โ€‹](https://docs.clawd.bot/web#web-gateway) Web (Gateway) ============================================================ The Gateway serves a small **browser Control UI** (Vite + Lit) from the same port as the Gateway WebSocket: * default: `http://:18789/` * optional prefix: set `gateway.controlUi.basePath` (e.g. `/clawdbot`) Capabilities live in [Control UI](https://docs.clawd.bot/web/control-ui) . This page focuses on bind modes, security, and web-facing surfaces. [โ€‹](https://docs.clawd.bot/web#webhooks) Webhooks ---------------------------------------------------- When `hooks.enabled=true`, the Gateway also exposes a small webhook endpoint on the same HTTP server. See [Gateway configuration](https://docs.clawd.bot/gateway/configuration) โ†’ `hooks` for auth + payloads. [โ€‹](https://docs.clawd.bot/web#config-default-on) Config (default-on) ------------------------------------------------------------------------ The Control UI is **enabled by default** when assets are present (`dist/control-ui`). You can control it via config: Copy { gateway: { controlUi: { enabled: true, basePath: "/clawdbot" } // basePath optional } } [โ€‹](https://docs.clawd.bot/web#tailscale-access) Tailscale access -------------------------------------------------------------------- ### [โ€‹](https://docs.clawd.bot/web#integrated-serve-recommended) Integrated Serve (recommended) Keep the Gateway on loopback and let Tailscale Serve proxy it: Copy { gateway: { bind: "loopback", tailscale: { mode: "serve" } } } Then start the gateway: Copy clawdbot gateway Open: * `https:///` (or your configured `gateway.controlUi.basePath`) ### [โ€‹](https://docs.clawd.bot/web#tailnet-bind-+-token) Tailnet bind + token Copy { gateway: { bind: "tailnet", controlUi: { enabled: true }, auth: { mode: "token", token: "your-token" } } } Then start the gateway (token required for non-loopback binds): Copy clawdbot gateway Open: * `http://:18789/` (or your configured `gateway.controlUi.basePath`) ### [โ€‹](https://docs.clawd.bot/web#public-internet-funnel) Public internet (Funnel) Copy { gateway: { bind: "loopback", tailscale: { mode: "funnel" }, auth: { mode: "password" } // or CLAWDBOT_GATEWAY_PASSWORD } } [โ€‹](https://docs.clawd.bot/web#security-notes) Security notes ---------------------------------------------------------------- * Binding the Gateway to a non-loopback address **requires** auth (`gateway.auth` or `CLAWDBOT_GATEWAY_TOKEN`). * The wizard generates a gateway token by default (even on loopback). * The UI sends `connect.params.auth.token` or `connect.params.auth.password`. * With Serve, Tailscale identity headers can satisfy auth when `gateway.auth.allowTailscale` is `true` (no token/password required). Set `gateway.auth.allowTailscale: false` to require explicit credentials. See [Tailscale](https://docs.clawd.bot/gateway/tailscale) and [Security](https://docs.clawd.bot/gateway/security) . * `gateway.tailscale.mode: "funnel"` requires `gateway.auth.mode: "password"` (shared password). [โ€‹](https://docs.clawd.bot/web#building-the-ui) Building the UI ------------------------------------------------------------------ The Gateway serves static files from `dist/control-ui`. Build them with: Copy pnpm ui:build # auto-installs UI deps on first run [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/web.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/web) [Tailscale](https://docs.clawd.bot/gateway/tailscale) [Control ui](https://docs.clawd.bot/web/control-ui) โŒ˜I --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/nodes#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Nodes](https://docs.clawd.bot/nodes#nodes) * [Pairing + status](https://docs.clawd.bot/nodes#pairing-%2B-status) * [Remote node host (system.run)](https://docs.clawd.bot/nodes#remote-node-host-system-run) * [What runs where](https://docs.clawd.bot/nodes#what-runs-where) * [Start a node host (foreground)](https://docs.clawd.bot/nodes#start-a-node-host-foreground) * [Start a node host (service)](https://docs.clawd.bot/nodes#start-a-node-host-service) * [Pair + name](https://docs.clawd.bot/nodes#pair-%2B-name) * [Allowlist the commands](https://docs.clawd.bot/nodes#allowlist-the-commands) * [Point exec at the node](https://docs.clawd.bot/nodes#point-exec-at-the-node) * [Invoking commands](https://docs.clawd.bot/nodes#invoking-commands) * [Screenshots (canvas snapshots)](https://docs.clawd.bot/nodes#screenshots-canvas-snapshots) * [Canvas controls](https://docs.clawd.bot/nodes#canvas-controls) * [A2UI (Canvas)](https://docs.clawd.bot/nodes#a2ui-canvas) * [Photos + videos (node camera)](https://docs.clawd.bot/nodes#photos-%2B-videos-node-camera) * [Screen recordings (nodes)](https://docs.clawd.bot/nodes#screen-recordings-nodes) * [Location (nodes)](https://docs.clawd.bot/nodes#location-nodes) * [SMS (Android nodes)](https://docs.clawd.bot/nodes#sms-android-nodes) * [System commands (node host / mac node)](https://docs.clawd.bot/nodes#system-commands-node-host-%2F-mac-node) * [Exec node binding](https://docs.clawd.bot/nodes#exec-node-binding) * [Permissions map](https://docs.clawd.bot/nodes#permissions-map) * [Headless node host (cross-platform)](https://docs.clawd.bot/nodes#headless-node-host-cross-platform) * [Mac node mode](https://docs.clawd.bot/nodes#mac-node-mode) [โ€‹](https://docs.clawd.bot/nodes#nodes) Nodes ================================================ A **node** is a companion device (macOS/iOS/Android/headless) that connects to the Gateway **WebSocket** (same port as operators) with `role: "node"` and exposes a command surface (e.g. `canvas.*`, `camera.*`, `system.*`) via `node.invoke`. Protocol details: [Gateway protocol](https://docs.clawd.bot/gateway/protocol) . Legacy transport: [Bridge protocol](https://docs.clawd.bot/gateway/bridge-protocol) (TCP JSONL; deprecated/removed for current nodes). macOS can also run in **node mode**: the menubar app connects to the Gatewayโ€™s WS server and exposes its local canvas/camera commands as a node (so `clawdbot nodes โ€ฆ` works against this Mac). Notes: * Nodes are **peripherals**, not gateways. They donโ€™t run the gateway service. * Telegram/WhatsApp/etc. messages land on the **gateway**, not on nodes. [โ€‹](https://docs.clawd.bot/nodes#pairing-+-status) Pairing + status ---------------------------------------------------------------------- **WS nodes use device pairing.** Nodes present a device identity during `connect`; the Gateway creates a device pairing request for `role: node`. Approve via the devices CLI (or UI). Quick CLI: Copy clawdbot devices list clawdbot devices approve clawdbot devices reject clawdbot nodes status clawdbot nodes describe --node Notes: * `nodes status` marks a node as **paired** when its device pairing role includes `node`. * `node.pair.*` (CLI: `clawdbot nodes pending/approve/reject`) is a separate gateway-owned node pairing store; it does **not** gate the WS `connect` handshake. [โ€‹](https://docs.clawd.bot/nodes#remote-node-host-system-run) Remote node host (system.run) ---------------------------------------------------------------------------------------------- Use a **node host** when your Gateway runs on one machine and you want commands to execute on another. The model still talks to the **gateway**; the gateway forwards `exec` calls to the **node host** when `host=node` is selected. ### [โ€‹](https://docs.clawd.bot/nodes#what-runs-where) What runs where * **Gateway host**: receives messages, runs the model, routes tool calls. * **Node host**: executes `system.run`/`system.which` on the node machine. * **Approvals**: enforced on the node host via `~/.clawdbot/exec-approvals.json`. ### [โ€‹](https://docs.clawd.bot/nodes#start-a-node-host-foreground) Start a node host (foreground) On the node machine: Copy clawdbot node run --host --port 18789 --display-name "Build Node" ### [โ€‹](https://docs.clawd.bot/nodes#start-a-node-host-service) Start a node host (service) Copy clawdbot node install --host --port 18789 --display-name "Build Node" clawdbot node restart ### [โ€‹](https://docs.clawd.bot/nodes#pair-+-name) Pair + name On the gateway host: Copy clawdbot nodes pending clawdbot nodes approve clawdbot nodes list Naming options: * `--display-name` on `clawdbot node run` / `clawdbot node install` (persists in `~/.clawdbot/node.json` on the node). * `clawdbot nodes rename --node --name "Build Node"` (gateway override). ### [โ€‹](https://docs.clawd.bot/nodes#allowlist-the-commands) Allowlist the commands Exec approvals are **per node host**. Add allowlist entries from the gateway: Copy clawdbot approvals allowlist add --node "/usr/bin/uname" clawdbot approvals allowlist add --node "/usr/bin/sw_vers" Approvals live on the node host at `~/.clawdbot/exec-approvals.json`. ### [โ€‹](https://docs.clawd.bot/nodes#point-exec-at-the-node) Point exec at the node Configure defaults (gateway config): Copy clawdbot config set tools.exec.host node clawdbot config set tools.exec.security allowlist clawdbot config set tools.exec.node "" Or per session: Copy /exec host=node security=allowlist node= Once set, any `exec` call with `host=node` runs on the node host (subject to the node allowlist/approvals). Related: * [Node host CLI](https://docs.clawd.bot/cli/node) * [Exec tool](https://docs.clawd.bot/tools/exec) * [Exec approvals](https://docs.clawd.bot/tools/exec-approvals) [โ€‹](https://docs.clawd.bot/nodes#invoking-commands) Invoking commands ------------------------------------------------------------------------ Low-level (raw RPC): Copy clawdbot nodes invoke --node --command canvas.eval --params '{"javaScript":"location.href"}' Higher-level helpers exist for the common โ€œgive the agent a MEDIA attachmentโ€ workflows. [โ€‹](https://docs.clawd.bot/nodes#screenshots-canvas-snapshots) Screenshots (canvas snapshots) ------------------------------------------------------------------------------------------------ If the node is showing the Canvas (WebView), `canvas.snapshot` returns `{ format, base64 }`. CLI helper (writes to a temp file and prints `MEDIA:`): Copy clawdbot nodes canvas snapshot --node --format png clawdbot nodes canvas snapshot --node --format jpg --max-width 1200 --quality 0.9 ### [โ€‹](https://docs.clawd.bot/nodes#canvas-controls) Canvas controls Copy clawdbot nodes canvas present --node --target https://example.com clawdbot nodes canvas hide --node clawdbot nodes canvas navigate https://example.com --node clawdbot nodes canvas eval --node --js "document.title" Notes: * `canvas present` accepts URLs or local file paths (`--target`), plus optional `--x/--y/--width/--height` for positioning. * `canvas eval` accepts inline JS (`--js`) or a positional arg. ### [โ€‹](https://docs.clawd.bot/nodes#a2ui-canvas) A2UI (Canvas) Copy clawdbot nodes canvas a2ui push --node --text "Hello" clawdbot nodes canvas a2ui push --node --jsonl ./payload.jsonl clawdbot nodes canvas a2ui reset --node Notes: * Only A2UI v0.8 JSONL is supported (v0.9/createSurface is rejected). [โ€‹](https://docs.clawd.bot/nodes#photos-+-videos-node-camera) Photos + videos (node camera) ---------------------------------------------------------------------------------------------- Photos (`jpg`): Copy clawdbot nodes camera list --node clawdbot nodes camera snap --node # default: both facings (2 MEDIA lines) clawdbot nodes camera snap --node --facing front Video clips (`mp4`): Copy clawdbot nodes camera clip --node --duration 10s clawdbot nodes camera clip --node --duration 3000 --no-audio Notes: * The node must be **foregrounded** for `canvas.*` and `camera.*` (background calls return `NODE_BACKGROUND_UNAVAILABLE`). * Clip duration is clamped (currently `<= 60s`) to avoid oversized base64 payloads. * Android will prompt for `CAMERA`/`RECORD_AUDIO` permissions when possible; denied permissions fail with `*_PERMISSION_REQUIRED`. [โ€‹](https://docs.clawd.bot/nodes#screen-recordings-nodes) Screen recordings (nodes) -------------------------------------------------------------------------------------- Nodes expose `screen.record` (mp4). Example: Copy clawdbot nodes screen record --node --duration 10s --fps 10 clawdbot nodes screen record --node --duration 10s --fps 10 --no-audio Notes: * `screen.record` requires the node app to be foregrounded. * Android will show the system screen-capture prompt before recording. * Screen recordings are clamped to `<= 60s`. * `--no-audio` disables microphone capture (supported on iOS/Android; macOS uses system capture audio). * Use `--screen ` to select a display when multiple screens are available. [โ€‹](https://docs.clawd.bot/nodes#location-nodes) Location (nodes) -------------------------------------------------------------------- Nodes expose `location.get` when Location is enabled in settings. CLI helper: Copy clawdbot nodes location get --node clawdbot nodes location get --node --accuracy precise --max-age 15000 --location-timeout 10000 Notes: * Location is **off by default**. * โ€œAlwaysโ€ requires system permission; background fetch is best-effort. * The response includes lat/lon, accuracy (meters), and timestamp. [โ€‹](https://docs.clawd.bot/nodes#sms-android-nodes) SMS (Android nodes) -------------------------------------------------------------------------- Android nodes can expose `sms.send` when the user grants **SMS** permission and the device supports telephony. Low-level invoke: Copy clawdbot nodes invoke --node --command sms.send --params '{"to":"+15555550123","message":"Hello from Clawdbot"}' Notes: * The permission prompt must be accepted on the Android device before the capability is advertised. * Wi-Fi-only devices without telephony will not advertise `sms.send`. [โ€‹](https://docs.clawd.bot/nodes#system-commands-node-host-/-mac-node) System commands (node host / mac node) ---------------------------------------------------------------------------------------------------------------- The macOS node exposes `system.run`, `system.notify`, and `system.execApprovals.get/set`. The headless node host exposes `system.run`, `system.which`, and `system.execApprovals.get/set`. Examples: Copy clawdbot nodes run --node -- echo "Hello from mac node" clawdbot nodes notify --node --title "Ping" --body "Gateway ready" Notes: * `system.run` returns stdout/stderr/exit code in the payload. * `system.notify` respects notification permission state on the macOS app. * `system.run` supports `--cwd`, `--env KEY=VAL`, `--command-timeout`, and `--needs-screen-recording`. * `system.notify` supports `--priority ` and `--delivery `. * macOS nodes drop `PATH` overrides; headless node hosts only accept `PATH` when it prepends the node host PATH. * On macOS node mode, `system.run` is gated by exec approvals in the macOS app (Settings โ†’ Exec approvals). Ask/allowlist/full behave the same as the headless node host; denied prompts return `SYSTEM_RUN_DENIED`. * On headless node host, `system.run` is gated by exec approvals (`~/.clawdbot/exec-approvals.json`). [โ€‹](https://docs.clawd.bot/nodes#exec-node-binding) Exec node binding ------------------------------------------------------------------------ When multiple nodes are available, you can bind exec to a specific node. This sets the default node for `exec host=node` (and can be overridden per agent). Global default: Copy clawdbot config set tools.exec.node "node-id-or-name" Per-agent override: Copy clawdbot config get agents.list clawdbot config set agents.list[0].tools.exec.node "node-id-or-name" Unset to allow any node: Copy clawdbot config unset tools.exec.node clawdbot config unset agents.list[0].tools.exec.node [โ€‹](https://docs.clawd.bot/nodes#permissions-map) Permissions map -------------------------------------------------------------------- Nodes may include a `permissions` map in `node.list` / `node.describe`, keyed by permission name (e.g. `screenRecording`, `accessibility`) with boolean values (`true` = granted). [โ€‹](https://docs.clawd.bot/nodes#headless-node-host-cross-platform) Headless node host (cross-platform) ---------------------------------------------------------------------------------------------------------- Clawdbot can run a **headless node host** (no UI) that connects to the Gateway WebSocket and exposes `system.run` / `system.which`. This is useful on Linux/Windows or for running a minimal node alongside a server. Start it: Copy clawdbot node run --host --port 18789 Notes: * Pairing is still required (the Gateway will show a node approval prompt). * The node host stores its node id, token, display name, and gateway connection info in `~/.clawdbot/node.json`. * Exec approvals are enforced locally via `~/.clawdbot/exec-approvals.json` (see [Exec approvals](https://docs.clawd.bot/tools/exec-approvals) ). * On macOS, the headless node host prefers the companion app exec host when reachable and falls back to local execution if the app is unavailable. Set `CLAWDBOT_NODE_EXEC_HOST=app` to require the app, or `CLAWDBOT_NODE_EXEC_FALLBACK=0` to disable fallback. * Add `--tls` / `--tls-fingerprint` when the Gateway WS uses TLS. [โ€‹](https://docs.clawd.bot/nodes#mac-node-mode) Mac node mode ---------------------------------------------------------------- * The macOS menubar app connects to the Gateway WS server as a node (so `clawdbot nodes โ€ฆ` works against this Mac). * In remote mode, the app opens an SSH tunnel for the Gateway port and connects to `localhost`. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/nodes.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/nodes) [Clawdhub](https://docs.clawd.bot/tools/clawdhub) [Camera](https://docs.clawd.bot/nodes/camera) โŒ˜I --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/gateway#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Gateway service runbook](https://docs.clawd.bot/gateway#gateway-service-runbook) * [What it is](https://docs.clawd.bot/gateway#what-it-is) * [How to run (local)](https://docs.clawd.bot/gateway#how-to-run-local) * [Remote access](https://docs.clawd.bot/gateway#remote-access) * [Multiple gateways (same host)](https://docs.clawd.bot/gateway#multiple-gateways-same-host) * [Dev profile (--dev)](https://docs.clawd.bot/gateway#dev-profile-dev) * [Protocol (operator view)](https://docs.clawd.bot/gateway#protocol-operator-view) * [Methods (initial set)](https://docs.clawd.bot/gateway#methods-initial-set) * [Events](https://docs.clawd.bot/gateway#events) * [WebChat integration](https://docs.clawd.bot/gateway#webchat-integration) * [Typing and validation](https://docs.clawd.bot/gateway#typing-and-validation) * [Connection snapshot](https://docs.clawd.bot/gateway#connection-snapshot) * [Error codes (res.error shape)](https://docs.clawd.bot/gateway#error-codes-res-error-shape) * [Keepalive behavior](https://docs.clawd.bot/gateway#keepalive-behavior) * [Replay / gaps](https://docs.clawd.bot/gateway#replay-%2F-gaps) * [Supervision (macOS example)](https://docs.clawd.bot/gateway#supervision-macos-example) * [Gateway service management (CLI)](https://docs.clawd.bot/gateway#gateway-service-management-cli) * [Supervision (systemd user unit)](https://docs.clawd.bot/gateway#supervision-systemd-user-unit) * [Windows (WSL2)](https://docs.clawd.bot/gateway#windows-wsl2) * [Operational checks](https://docs.clawd.bot/gateway#operational-checks) * [Safety guarantees](https://docs.clawd.bot/gateway#safety-guarantees) * [CLI helpers](https://docs.clawd.bot/gateway#cli-helpers) * [Migration guidance](https://docs.clawd.bot/gateway#migration-guidance) [โ€‹](https://docs.clawd.bot/gateway#gateway-service-runbook) Gateway service runbook ====================================================================================== Last updated: 2025-12-09 [โ€‹](https://docs.clawd.bot/gateway#what-it-is) What it is ------------------------------------------------------------ * The always-on process that owns the single Baileys/Telegram connection and the control/event plane. * Replaces the legacy `gateway` command. CLI entry point: `clawdbot gateway`. * Runs until stopped; exits non-zero on fatal errors so the supervisor restarts it. [โ€‹](https://docs.clawd.bot/gateway#how-to-run-local) How to run (local) -------------------------------------------------------------------------- Copy clawdbot gateway --port 18789 # for full debug/trace logs in stdio: clawdbot gateway --port 18789 --verbose # if the port is busy, terminate listeners then start: clawdbot gateway --force # dev loop (auto-reload on TS changes): pnpm gateway:watch * Config hot reload watches `~/.clawdbot/clawdbot.json` (or `CLAWDBOT_CONFIG_PATH`). * Default mode: `gateway.reload.mode="hybrid"` (hot-apply safe changes, restart on critical). * Hot reload uses in-process restart via **SIGUSR1** when needed. * Disable with `gateway.reload.mode="off"`. * Binds WebSocket control plane to `127.0.0.1:` (default 18789). * The same port also serves HTTP (control UI, hooks, A2UI). Single-port multiplex. * OpenAI Chat Completions (HTTP): [`/v1/chat/completions`](https://docs.clawd.bot/gateway/openai-http-api) . * OpenResponses (HTTP): [`/v1/responses`](https://docs.clawd.bot/gateway/openresponses-http-api) . * Tools Invoke (HTTP): [`/tools/invoke`](https://docs.clawd.bot/gateway/tools-invoke-http-api) . * Starts a Canvas file server by default on `canvasHost.port` (default `18793`), serving `http://:18793/__clawdbot__/canvas/` from `~/clawd/canvas`. Disable with `canvasHost.enabled=false` or `CLAWDBOT_SKIP_CANVAS_HOST=1`. * Logs to stdout; use launchd/systemd to keep it alive and rotate logs. * Pass `--verbose` to mirror debug logging (handshakes, req/res, events) from the log file into stdio when troubleshooting. * `--force` uses `lsof` to find listeners on the chosen port, sends SIGTERM, logs what it killed, then starts the gateway (fails fast if `lsof` is missing). * If you run under a supervisor (launchd/systemd/mac app child-process mode), a stop/restart typically sends **SIGTERM**; older builds may surface this as `pnpm` `ELIFECYCLE` exit code **143** (SIGTERM), which is a normal shutdown, not a crash. * **SIGUSR1** triggers an in-process restart when authorized (gateway tool/config apply/update, or enable `commands.restart` for manual restarts). * Gateway auth: set `gateway.auth.mode=token` + `gateway.auth.token` (or pass `--token ` / `CLAWDBOT_GATEWAY_TOKEN`) to require clients to send `connect.params.auth.token`. * The wizard now generates a token by default, even on loopback. * Port precedence: `--port` > `CLAWDBOT_GATEWAY_PORT` > `gateway.port` > default `18789`. [โ€‹](https://docs.clawd.bot/gateway#remote-access) Remote access ------------------------------------------------------------------ * Tailscale/VPN preferred; otherwise SSH tunnel: Copy ssh -N -L 18789:127.0.0.1:18789 user@host * Clients then connect to `ws://127.0.0.1:18789` through the tunnel. * If a token is configured, clients must include it in `connect.params.auth.token` even over the tunnel. [โ€‹](https://docs.clawd.bot/gateway#multiple-gateways-same-host) Multiple gateways (same host) ------------------------------------------------------------------------------------------------ Usually unnecessary: one Gateway can serve multiple messaging channels and agents. Use multiple Gateways only for redundancy or strict isolation (ex: rescue bot). Supported if you isolate state + config and use unique ports. Full guide: [Multiple gateways](https://docs.clawd.bot/gateway/multiple-gateways) . Service names are profile-aware: * macOS: `com.clawdbot.` * Linux: `clawdbot-gateway-.service` * Windows: `Clawdbot Gateway ()` Install metadata is embedded in the service config: * `CLAWDBOT_SERVICE_MARKER=clawdbot` * `CLAWDBOT_SERVICE_KIND=gateway` * `CLAWDBOT_SERVICE_VERSION=` Rescue-Bot Pattern: keep a second Gateway isolated with its own profile, state dir, workspace, and base port spacing. Full guide: [Rescue-bot guide](https://docs.clawd.bot/gateway/multiple-gateways#rescue-bot-guide) . ### [โ€‹](https://docs.clawd.bot/gateway#dev-profile-dev) Dev profile (`--dev`) Fast path: run a fully-isolated dev instance (config/state/workspace) without touching your primary setup. Copy clawdbot --dev setup clawdbot --dev gateway --allow-unconfigured # then target the dev instance: clawdbot --dev status clawdbot --dev health Defaults (can be overridden via env/flags/config): * `CLAWDBOT_STATE_DIR=~/.clawdbot-dev` * `CLAWDBOT_CONFIG_PATH=~/.clawdbot-dev/clawdbot.json` * `CLAWDBOT_GATEWAY_PORT=19001` (Gateway WS + HTTP) * `browser.controlUrl=http://127.0.0.1:19003` (derived: `gateway.port+2`) * `canvasHost.port=19005` (derived: `gateway.port+4`) * `agents.defaults.workspace` default becomes `~/clawd-dev` when you run `setup`/`onboard` under `--dev`. Derived ports (rules of thumb): * Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`) * `browser.controlUrl port = base + 2` (or `CLAWDBOT_BROWSER_CONTROL_URL` / config override) * `canvasHost.port = base + 4` (or `CLAWDBOT_CANVAS_HOST_PORT` / config override) * Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile). Checklist per instance: * unique `gateway.port` * unique `CLAWDBOT_CONFIG_PATH` * unique `CLAWDBOT_STATE_DIR` * unique `agents.defaults.workspace` * separate WhatsApp numbers (if using WA) Service install per profile: Copy clawdbot --profile main gateway install clawdbot --profile rescue gateway install Example: Copy CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a clawdbot gateway --port 19001 CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbot gateway --port 19002 [โ€‹](https://docs.clawd.bot/gateway#protocol-operator-view) Protocol (operator view) -------------------------------------------------------------------------------------- * Full docs: [Gateway protocol](https://docs.clawd.bot/gateway/protocol) and [Bridge protocol (legacy)](https://docs.clawd.bot/gateway/bridge-protocol) . * Mandatory first frame from client: `req {type:"req", id, method:"connect", params:{minProtocol,maxProtocol,client:{id,displayName?,version,platform,deviceFamily?,modelIdentifier?,mode,instanceId?}, caps, auth?, locale?, userAgent? } }`. * Gateway replies `res {type:"res", id, ok:true, payload:hello-ok }` (or `ok:false` with an error, then closes). * After handshake: * Requests: `{type:"req", id, method, params}` โ†’ `{type:"res", id, ok, payload|error}` * Events: `{type:"event", event, payload, seq?, stateVersion?}` * Structured presence entries: `{host, ip, version, platform?, deviceFamily?, modelIdentifier?, mode, lastInputSeconds?, ts, reason?, tags?[], instanceId? }` (for WS clients, `instanceId` comes from `connect.client.instanceId`). * `agent` responses are two-stage: first `res` ack `{runId,status:"accepted"}`, then a final `res` `{runId,status:"ok"|"error",summary}` after the run finishes; streamed output arrives as `event:"agent"`. [โ€‹](https://docs.clawd.bot/gateway#methods-initial-set) Methods (initial set) -------------------------------------------------------------------------------- * `health` โ€” full health snapshot (same shape as `clawdbot health --json`). * `status` โ€” short summary. * `system-presence` โ€” current presence list. * `system-event` โ€” post a presence/system note (structured). * `send` โ€” send a message via the active channel(s). * `agent` โ€” run an agent turn (streams events back on same connection). * `node.list` โ€” list paired + currently-connected nodes (includes `caps`, `deviceFamily`, `modelIdentifier`, `paired`, `connected`, and advertised `commands`). * `node.describe` โ€” describe a node (capabilities + supported `node.invoke` commands; works for paired nodes and for currently-connected unpaired nodes). * `node.invoke` โ€” invoke a command on a node (e.g. `canvas.*`, `camera.*`). * `node.pair.*` โ€” pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`). See also: [Presence](https://docs.clawd.bot/concepts/presence) for how presence is produced/deduped and why a stable `client.instanceId` matters. [โ€‹](https://docs.clawd.bot/gateway#events) Events ---------------------------------------------------- * `agent` โ€” streamed tool/output events from the agent run (seq-tagged). * `presence` โ€” presence updates (deltas with stateVersion) pushed to all connected clients. * `tick` โ€” periodic keepalive/no-op to confirm liveness. * `shutdown` โ€” Gateway is exiting; payload includes `reason` and optional `restartExpectedMs`. Clients should reconnect. [โ€‹](https://docs.clawd.bot/gateway#webchat-integration) WebChat integration ------------------------------------------------------------------------------ * WebChat is a native SwiftUI UI that talks directly to the Gateway WebSocket for history, sends, abort, and events. * Remote use goes through the same SSH/Tailscale tunnel; if a gateway token is configured, the client includes it during `connect`. * macOS app connects via a single WS (shared connection); it hydrates presence from the initial snapshot and listens for `presence` events to update the UI. [โ€‹](https://docs.clawd.bot/gateway#typing-and-validation) Typing and validation ---------------------------------------------------------------------------------- * Server validates every inbound frame with AJV against JSON Schema emitted from the protocol definitions. * Clients (TS/Swift) consume generated types (TS directly; Swift via the repoโ€™s generator). * Protocol definitions are the source of truth; regenerate schema/models with: * `pnpm protocol:gen` * `pnpm protocol:gen:swift` [โ€‹](https://docs.clawd.bot/gateway#connection-snapshot) Connection snapshot ------------------------------------------------------------------------------ * `hello-ok` includes a `snapshot` with `presence`, `health`, `stateVersion`, and `uptimeMs` plus `policy {maxPayload,maxBufferedBytes,tickIntervalMs}` so clients can render immediately without extra requests. * `health`/`system-presence` remain available for manual refresh, but are not required at connect time. [โ€‹](https://docs.clawd.bot/gateway#error-codes-res-error-shape) Error codes (res.error shape) ------------------------------------------------------------------------------------------------ * Errors use `{ code, message, details?, retryable?, retryAfterMs? }`. * Standard codes: * `NOT_LINKED` โ€” WhatsApp not authenticated. * `AGENT_TIMEOUT` โ€” agent did not respond within the configured deadline. * `INVALID_REQUEST` โ€” schema/param validation failed. * `UNAVAILABLE` โ€” Gateway is shutting down or a dependency is unavailable. [โ€‹](https://docs.clawd.bot/gateway#keepalive-behavior) Keepalive behavior ---------------------------------------------------------------------------- * `tick` events (or WS ping/pong) are emitted periodically so clients know the Gateway is alive even when no traffic occurs. * Send/agent acknowledgements remain separate responses; do not overload ticks for sends. [โ€‹](https://docs.clawd.bot/gateway#replay-/-gaps) Replay / gaps ------------------------------------------------------------------ * Events are not replayed. Clients detect seq gaps and should refresh (`health` + `system-presence`) before continuing. WebChat and macOS clients now auto-refresh on gap. [โ€‹](https://docs.clawd.bot/gateway#supervision-macos-example) Supervision (macOS example) -------------------------------------------------------------------------------------------- * Use launchd to keep the service alive: * Program: path to `clawdbot` * Arguments: `gateway` * KeepAlive: true * StandardOut/Err: file paths or `syslog` * On failure, launchd restarts; fatal misconfig should keep exiting so the operator notices. * LaunchAgents are per-user and require a logged-in session; for headless setups use a custom LaunchDaemon (not shipped). * `clawdbot gateway install` writes `~/Library/LaunchAgents/com.clawdbot.gateway.plist` (or `com.clawdbot..plist`). * `clawdbot doctor` audits the LaunchAgent config and can update it to current defaults. [โ€‹](https://docs.clawd.bot/gateway#gateway-service-management-cli) Gateway service management (CLI) ------------------------------------------------------------------------------------------------------ Use the Gateway CLI for install/start/stop/restart/status: Copy clawdbot gateway status clawdbot gateway install clawdbot gateway stop clawdbot gateway restart clawdbot logs --follow Notes: * `gateway status` probes the Gateway RPC by default using the serviceโ€™s resolved port/config (override with `--url`). * `gateway status --deep` adds system-level scans (LaunchDaemons/system units). * `gateway status --no-probe` skips the RPC probe (useful when networking is down). * `gateway status --json` is stable for scripts. * `gateway status` reports **supervisor runtime** (launchd/systemd running) separately from **RPC reachability** (WS connect + status RPC). * `gateway status` prints config path + probe target to avoid โ€œlocalhost vs LAN bindโ€ confusion and profile mismatches. * `gateway status` includes the last gateway error line when the service looks running but the port is closed. * `logs` tails the Gateway file log via RPC (no manual `tail`/`grep` needed). * If other gateway-like services are detected, the CLI warns unless they are Clawdbot profile services. We still recommend **one gateway per machine** for most setups; use isolated profiles/ports for redundancy or a rescue bot. See [Multiple gateways](https://docs.clawd.bot/gateway/multiple-gateways) . * Cleanup: `clawdbot gateway uninstall` (current service) and `clawdbot doctor` (legacy migrations). * `gateway install` is a no-op when already installed; use `clawdbot gateway install --force` to reinstall (profile/env/path changes). Bundled mac app: * Clawdbot.app can bundle a Node-based gateway relay and install a per-user LaunchAgent labeled `com.clawdbot.gateway` (or `com.clawdbot.`). * To stop it cleanly, use `clawdbot gateway stop` (or `launchctl bootout gui/$UID/com.clawdbot.gateway`). * To restart, use `clawdbot gateway restart` (or `launchctl kickstart -k gui/$UID/com.clawdbot.gateway`). * `launchctl` only works if the LaunchAgent is installed; otherwise use `clawdbot gateway install` first. * Replace the label with `com.clawdbot.` when running a named profile. [โ€‹](https://docs.clawd.bot/gateway#supervision-systemd-user-unit) Supervision (systemd user unit) ---------------------------------------------------------------------------------------------------- Clawdbot installs a **systemd user service** by default on Linux/WSL2. We recommend user services for single-user machines (simpler env, per-user config). Use a **system service** for multi-user or always-on servers (no lingering required, shared supervision). `clawdbot gateway install` writes the user unit. `clawdbot doctor` audits the unit and can update it to match the current recommended defaults. Create `~/.config/systemd/user/clawdbot-gateway[-].service`: Copy [Unit] Description=Clawdbot Gateway (profile: , v) After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/clawdbot gateway --port 18789 Restart=always RestartSec=5 Environment=CLAWDBOT_GATEWAY_TOKEN= WorkingDirectory=/home/youruser [Install] WantedBy=default.target Enable lingering (required so the user service survives logout/idle): Copy sudo loginctl enable-linger youruser Onboarding runs this on Linux/WSL2 (may prompt for sudo; writes `/var/lib/systemd/linger`). Then enable the service: Copy systemctl --user enable --now clawdbot-gateway[-].service **Alternative (system service)** - for always-on or multi-user servers, you can install a systemd **system** unit instead of a user unit (no lingering needed). Create `/etc/systemd/system/clawdbot-gateway[-].service` (copy the unit above, switch `WantedBy=multi-user.target`, set `User=` + `WorkingDirectory=`), then: Copy sudo systemctl daemon-reload sudo systemctl enable --now clawdbot-gateway[-].service [โ€‹](https://docs.clawd.bot/gateway#windows-wsl2) Windows (WSL2) ------------------------------------------------------------------ Windows installs should use **WSL2** and follow the Linux systemd section above. [โ€‹](https://docs.clawd.bot/gateway#operational-checks) Operational checks ---------------------------------------------------------------------------- * Liveness: open WS and send `req:connect` โ†’ expect `res` with `payload.type="hello-ok"` (with snapshot). * Readiness: call `health` โ†’ expect `ok: true` and a linked channel in `linkChannel` (when applicable). * Debug: subscribe to `tick` and `presence` events; ensure `status` shows linked/auth age; presence entries show Gateway host and connected clients. [โ€‹](https://docs.clawd.bot/gateway#safety-guarantees) Safety guarantees -------------------------------------------------------------------------- * Assume one Gateway per host by default; if you run multiple profiles, isolate ports/state and target the right instance. * No fallback to direct Baileys connections; if the Gateway is down, sends fail fast. * Non-connect first frames or malformed JSON are rejected and the socket is closed. * Graceful shutdown: emit `shutdown` event before closing; clients must handle close + reconnect. [โ€‹](https://docs.clawd.bot/gateway#cli-helpers) CLI helpers -------------------------------------------------------------- * `clawdbot gateway health|status` โ€” request health/status over the Gateway WS. * `clawdbot message send --target --message "hi" [--media ...]` โ€” send via Gateway (idempotent for WhatsApp). * `clawdbot agent --message "hi" --to ` โ€” run an agent turn (waits for final by default). * `clawdbot gateway call --params '{"k":"v"}'` โ€” raw method invoker for debugging. * `clawdbot gateway stop|restart` โ€” stop/restart the supervised gateway service (launchd/systemd). * Gateway helper subcommands assume a running gateway on `--url`; they no longer auto-spawn one. [โ€‹](https://docs.clawd.bot/gateway#migration-guidance) Migration guidance ---------------------------------------------------------------------------- * Retire uses of `clawdbot gateway` and the legacy TCP control port. * Update clients to speak the WS protocol with mandatory connect and structured presence. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/gateway.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/gateway) [Typebox](https://docs.clawd.bot/concepts/typebox) [Protocol](https://docs.clawd.bot/gateway/protocol) โŒ˜I --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/tools#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Tools (Clawdbot)](https://docs.clawd.bot/tools#tools-clawdbot) * [Disabling tools](https://docs.clawd.bot/tools#disabling-tools) * [Tool profiles (base allowlist)](https://docs.clawd.bot/tools#tool-profiles-base-allowlist) * [Provider-specific tool policy](https://docs.clawd.bot/tools#provider-specific-tool-policy) * [Tool groups (shorthands)](https://docs.clawd.bot/tools#tool-groups-shorthands) * [Plugins + tools](https://docs.clawd.bot/tools#plugins-%2B-tools) * [Tool inventory](https://docs.clawd.bot/tools#tool-inventory) * [apply\_patch](https://docs.clawd.bot/tools#apply_patch) * [exec](https://docs.clawd.bot/tools#exec) * [process](https://docs.clawd.bot/tools#process) * [web\_search](https://docs.clawd.bot/tools#web_search) * [web\_fetch](https://docs.clawd.bot/tools#web_fetch) * [browser](https://docs.clawd.bot/tools#browser) * [canvas](https://docs.clawd.bot/tools#canvas) * [nodes](https://docs.clawd.bot/tools#nodes) * [image](https://docs.clawd.bot/tools#image) * [message](https://docs.clawd.bot/tools#message) * [cron](https://docs.clawd.bot/tools#cron) * [gateway](https://docs.clawd.bot/tools#gateway) * [sessions\_list / sessions\_history / sessions\_send / sessions\_spawn / session\_status](https://docs.clawd.bot/tools#sessions_list-%2F-sessions_history-%2F-sessions_send-%2F-sessions_spawn-%2F-session_status) * [agents\_list](https://docs.clawd.bot/tools#agents_list) * [Parameters (common)](https://docs.clawd.bot/tools#parameters-common) * [Recommended agent flows](https://docs.clawd.bot/tools#recommended-agent-flows) * [Safety](https://docs.clawd.bot/tools#safety) * [How tools are presented to the agent](https://docs.clawd.bot/tools#how-tools-are-presented-to-the-agent) [โ€‹](https://docs.clawd.bot/tools#tools-clawdbot) Tools (Clawdbot) ==================================================================== Clawdbot exposes **first-class agent tools** for browser, canvas, nodes, and cron. These replace the old `clawdbot-*` skills: the tools are typed, no shelling, and the agent should rely on them directly. [โ€‹](https://docs.clawd.bot/tools#disabling-tools) Disabling tools -------------------------------------------------------------------- You can globally allow/deny tools via `tools.allow` / `tools.deny` in `clawdbot.json` (deny wins). This prevents disallowed tools from being sent to model providers. Copy { tools: { deny: ["browser"] } } Notes: * Matching is case-insensitive. * `*` wildcards are supported (`"*"` means all tools). * If `tools.allow` only references unknown or unloaded plugin tool names, Clawdbot logs a warning and ignores the allowlist so core tools stay available. [โ€‹](https://docs.clawd.bot/tools#tool-profiles-base-allowlist) Tool profiles (base allowlist) ------------------------------------------------------------------------------------------------ `tools.profile` sets a **base tool allowlist** before `tools.allow`/`tools.deny`. Per-agent override: `agents.list[].tools.profile`. Profiles: * `minimal`: `session_status` only * `coding`: `group:fs`, `group:runtime`, `group:sessions`, `group:memory`, `image` * `messaging`: `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` * `full`: no restriction (same as unset) Example (messaging-only by default, allow Slack + Discord tools too): Copy { tools: { profile: "messaging", allow: ["slack", "discord"] } } Example (coding profile, but deny exec/process everywhere): Copy { tools: { profile: "coding", deny: ["group:runtime"] } } Example (global coding profile, messaging-only support agent): Copy { tools: { profile: "coding" }, agents: { list: [\ {\ id: "support",\ tools: { profile: "messaging", allow: ["slack"] }\ }\ ] } } [โ€‹](https://docs.clawd.bot/tools#provider-specific-tool-policy) Provider-specific tool policy ------------------------------------------------------------------------------------------------ Use `tools.byProvider` to **further restrict** tools for specific providers (or a single `provider/model`) without changing your global defaults. Per-agent override: `agents.list[].tools.byProvider`. This is applied **after** the base tool profile and **before** allow/deny lists, so it can only narrow the tool set. Provider keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`). Example (keep global coding profile, but minimal tools for Google Antigravity): Copy { tools: { profile: "coding", byProvider: { "google-antigravity": { profile: "minimal" } } } } Example (provider/model-specific allowlist for a flaky endpoint): Copy { tools: { allow: ["group:fs", "group:runtime", "sessions_list"], byProvider: { "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] } } } } Example (agent-specific override for a single provider): Copy { agents: { list: [\ {\ id: "support",\ tools: {\ byProvider: {\ "google-antigravity": { allow: ["message", "sessions_list"] }\ }\ }\ }\ ] } } [โ€‹](https://docs.clawd.bot/tools#tool-groups-shorthands) Tool groups (shorthands) ------------------------------------------------------------------------------------ Tool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools. Use these in `tools.allow` / `tools.deny`. Available groups: * `group:runtime`: `exec`, `bash`, `process` * `group:fs`: `read`, `write`, `edit`, `apply_patch` * `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` * `group:memory`: `memory_search`, `memory_get` * `group:web`: `web_search`, `web_fetch` * `group:ui`: `browser`, `canvas` * `group:automation`: `cron`, `gateway` * `group:messaging`: `message` * `group:nodes`: `nodes` * `group:clawdbot`: all built-in Clawdbot tools (excludes provider plugins) Example (allow only file tools + browser): Copy { tools: { allow: ["group:fs", "browser"] } } [โ€‹](https://docs.clawd.bot/tools#plugins-+-tools) Plugins + tools -------------------------------------------------------------------- Plugins can register **additional tools** (and CLI commands) beyond the core set. See [Plugins](https://docs.clawd.bot/plugin) for install + config, and [Skills](https://docs.clawd.bot/tools/skills) for how tool usage guidance is injected into prompts. Some plugins ship their own skills alongside tools (for example, the voice-call plugin). Optional plugin tools: * [Lobster](https://docs.clawd.bot/tools/lobster) : typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host). * [LLM Task](https://docs.clawd.bot/tools/llm-task) : JSON-only LLM step for structured workflow output (optional schema validation). [โ€‹](https://docs.clawd.bot/tools#tool-inventory) Tool inventory ------------------------------------------------------------------ ### [โ€‹](https://docs.clawd.bot/tools#apply_patch) `apply_patch` Apply structured patches across one or more files. Use for multi-hunk edits. Experimental: enable via `tools.exec.applyPatch.enabled` (OpenAI models only). ### [โ€‹](https://docs.clawd.bot/tools#exec) `exec` Run shell commands in the workspace. Core parameters: * `command` (required) * `yieldMs` (auto-background after timeout, default 10000) * `background` (immediate background) * `timeout` (seconds; kills the process if exceeded, default 1800) * `elevated` (bool; run on host if elevated mode is enabled/allowed; only changes behavior when the agent is sandboxed) * `host` (`sandbox | gateway | node`) * `security` (`deny | allowlist | full`) * `ask` (`off | on-miss | always`) * `node` (node id/name for `host=node`) * Need a real TTY? Set `pty: true`. Notes: * Returns `status: "running"` with a `sessionId` when backgrounded. * Use `process` to poll/log/write/kill/clear background sessions. * If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`. * `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and is an alias for `host=gateway` + `security=full`. * `elevated` only changes behavior when the agent is sandboxed (otherwise itโ€™s a no-op). * `host=node` can target a macOS companion app or a headless node host (`clawdbot node run`). * gateway/node approvals and allowlists: [Exec approvals](https://docs.clawd.bot/tools/exec-approvals) . ### [โ€‹](https://docs.clawd.bot/tools#process) `process` Manage background exec sessions. Core actions: * `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove` Notes: * `poll` returns new output and exit status when complete. * `log` supports line-based `offset`/`limit` (omit `offset` to grab the last N lines). * `process` is scoped per agent; sessions from other agents are not visible. ### [โ€‹](https://docs.clawd.bot/tools#web_search) `web_search` Search the web using Brave Search API. Core parameters: * `query` (required) * `count` (1โ€“10; default from `tools.web.search.maxResults`) Notes: * Requires a Brave API key (recommended: `clawdbot configure --section web`, or set `BRAVE_API_KEY`). * Enable via `tools.web.search.enabled`. * Responses are cached (default 15 min). * See [Web tools](https://docs.clawd.bot/tools/web) for setup. ### [โ€‹](https://docs.clawd.bot/tools#web_fetch) `web_fetch` Fetch and extract readable content from a URL (HTML โ†’ markdown/text). Core parameters: * `url` (required) * `extractMode` (`markdown` | `text`) * `maxChars` (truncate long pages) Notes: * Enable via `tools.web.fetch.enabled`. * Responses are cached (default 15 min). * For JS-heavy sites, prefer the browser tool. * See [Web tools](https://docs.clawd.bot/tools/web) for setup. * See [Firecrawl](https://docs.clawd.bot/tools/firecrawl) for the optional anti-bot fallback. ### [โ€‹](https://docs.clawd.bot/tools#browser) `browser` Control the dedicated clawd browser. Core actions: * `status`, `start`, `stop`, `tabs`, `open`, `focus`, `close` * `snapshot` (aria/ai) * `screenshot` (returns image block + `MEDIA:`) * `act` (UI actions: click/type/press/hover/drag/select/fill/resize/wait/evaluate) * `navigate`, `console`, `pdf`, `upload`, `dialog` Profile management: * `profiles` โ€” list all browser profiles with status * `create-profile` โ€” create new profile with auto-allocated port (or `cdpUrl`) * `delete-profile` โ€” stop browser, delete user data, remove from config (local only) * `reset-profile` โ€” kill orphan process on profileโ€™s port (local only) Common parameters: * `controlUrl` (defaults from config) * `profile` (optional; defaults to `browser.defaultProfile`) Notes: * Requires `browser.enabled=true` (default is `true`; set `false` to disable). * Uses `browser.controlUrl` unless `controlUrl` is passed explicitly. * All actions accept optional `profile` parameter for multi-instance support. * When `profile` is omitted, uses `browser.defaultProfile` (defaults to โ€œchromeโ€). * Profile names: lowercase alphanumeric + hyphens only (max 64 chars). * Port range: 18800-18899 (~100 profiles max). * Remote profiles are attach-only (no start/stop/reset). * `snapshot` defaults to `ai` when Playwright is installed; use `aria` for the accessibility tree. * `snapshot` also supports role-snapshot options (`interactive`, `compact`, `depth`, `selector`) which return refs like `e12`. * `act` requires `ref` from `snapshot` (numeric `12` from AI snapshots, or `e12` from role snapshots); use `evaluate` for rare CSS selector needs. * Avoid `act` โ†’ `wait` by default; use it only in exceptional cases (no reliable UI state to wait on). * `upload` can optionally pass a `ref` to auto-click after arming. * `upload` also supports `inputRef` (aria ref) or `element` (CSS selector) to set `` directly. ### [โ€‹](https://docs.clawd.bot/tools#canvas) `canvas` Drive the node Canvas (present, eval, snapshot, A2UI). Core actions: * `present`, `hide`, `navigate`, `eval` * `snapshot` (returns image block + `MEDIA:`) * `a2ui_push`, `a2ui_reset` Notes: * Uses gateway `node.invoke` under the hood. * If no `node` is provided, the tool picks a default (single connected node or local mac node). * A2UI is v0.8 only (no `createSurface`); the CLI rejects v0.9 JSONL with line errors. * Quick smoke: `clawdbot nodes canvas a2ui push --node --text "Hello from A2UI"`. ### [โ€‹](https://docs.clawd.bot/tools#nodes) `nodes` Discover and target paired nodes; send notifications; capture camera/screen. Core actions: * `status`, `describe` * `pending`, `approve`, `reject` (pairing) * `notify` (macOS `system.notify`) * `run` (macOS `system.run`) * `camera_snap`, `camera_clip`, `screen_record` * `location_get` Notes: * Camera/screen commands require the node app to be foregrounded. * Images return image blocks + `MEDIA:`. * Videos return `FILE:` (mp4). * Location returns a JSON payload (lat/lon/accuracy/timestamp). * `run` params: `command` argv array; optional `cwd`, `env` (`KEY=VAL`), `commandTimeoutMs`, `invokeTimeoutMs`, `needsScreenRecording`. Example (`run`): Copy { "action": "run", "node": "office-mac", "command": ["echo", "Hello"], "env": ["FOO=bar"], "commandTimeoutMs": 12000, "invokeTimeoutMs": 45000, "needsScreenRecording": false } ### [โ€‹](https://docs.clawd.bot/tools#image) `image` Analyze an image with the configured image model. Core parameters: * `image` (required path or URL) * `prompt` (optional; defaults to โ€œDescribe the image.โ€) * `model` (optional override) * `maxBytesMb` (optional size cap) Notes: * Only available when `agents.defaults.imageModel` is configured (primary or fallbacks), or when an implicit image model can be inferred from your default model + configured auth (best-effort pairing). * Uses the image model directly (independent of the main chat model). ### [โ€‹](https://docs.clawd.bot/tools#message) `message` Send messages and channel actions across Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams. Core actions: * `send` (text + optional media; MS Teams also supports `card` for Adaptive Cards) * `poll` (WhatsApp/Discord/MS Teams polls) * `react` / `reactions` / `read` / `edit` / `delete` * `pin` / `unpin` / `list-pins` * `permissions` * `thread-create` / `thread-list` / `thread-reply` * `search` * `sticker` * `member-info` / `role-info` * `emoji-list` / `emoji-upload` / `sticker-upload` * `role-add` / `role-remove` * `channel-info` / `channel-list` * `voice-status` * `event-list` / `event-create` * `timeout` / `kick` / `ban` Notes: * `send` routes WhatsApp via the Gateway; other channels go direct. * `poll` uses the Gateway for WhatsApp and MS Teams; Discord polls go direct. * When a message tool call is bound to an active chat session, sends are constrained to that sessionโ€™s target to avoid cross-context leaks. ### [โ€‹](https://docs.clawd.bot/tools#cron) `cron` Manage Gateway cron jobs and wakeups. Core actions: * `status`, `list` * `add`, `update`, `remove`, `run`, `runs` * `wake` (enqueue system event + optional immediate heartbeat) Notes: * `add` expects a full cron job object (same schema as `cron.add` RPC). * `update` uses `{ id, patch }`. ### [โ€‹](https://docs.clawd.bot/tools#gateway) `gateway` Restart or apply updates to the running Gateway process (in-place). Core actions: * `restart` (authorizes + sends `SIGUSR1` for in-process restart; `clawdbot gateway` restart in-place) * `config.get` / `config.schema` * `config.apply` (validate + write config + restart + wake) * `config.patch` (merge partial update + restart + wake) * `update.run` (run update + restart + wake) Notes: * Use `delayMs` (defaults to 2000) to avoid interrupting an in-flight reply. * `restart` is disabled by default; enable with `commands.restart: true`. ### [โ€‹](https://docs.clawd.bot/tools#sessions_list-/-sessions_history-/-sessions_send-/-sessions_spawn-/-session_status) `sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status` List sessions, inspect transcript history, or send to another session. Core parameters: * `sessions_list`: `kinds?`, `limit?`, `activeMinutes?`, `messageLimit?` (0 = none) * `sessions_history`: `sessionKey` (or `sessionId`), `limit?`, `includeTools?` * `sessions_send`: `sessionKey` (or `sessionId`), `message`, `timeoutSeconds?` (0 = fire-and-forget) * `sessions_spawn`: `task`, `label?`, `agentId?`, `model?`, `runTimeoutSeconds?`, `cleanup?` * `session_status`: `sessionKey?` (default current; accepts `sessionId`), `model?` (`default` clears override) Notes: * `main` is the canonical direct-chat key; global/unknown are hidden. * `messageLimit > 0` fetches last N messages per session (tool messages filtered). * `sessions_send` waits for final completion when `timeoutSeconds > 0`. * Delivery/announce happens after completion and is best-effort; `status: "ok"` confirms the agent run finished, not that the announce was delivered. * `sessions_spawn` starts a sub-agent run and posts an announce reply back to the requester chat. * `sessions_spawn` is non-blocking and returns `status: "accepted"` immediately. * `sessions_send` runs a replyโ€‘back pingโ€‘pong (reply `REPLY_SKIP` to stop; max turns via `session.agentToAgent.maxPingPongTurns`, 0โ€“5). * After the pingโ€‘pong, the target agent runs an **announce step**; reply `ANNOUNCE_SKIP` to suppress the announcement. ### [โ€‹](https://docs.clawd.bot/tools#agents_list) `agents_list` List agent ids that the current session may target with `sessions_spawn`. Notes: * Result is restricted to per-agent allowlists (`agents.list[].subagents.allowAgents`). * When `["*"]` is configured, the tool includes all configured agents and marks `allowAny: true`. [โ€‹](https://docs.clawd.bot/tools#parameters-common) Parameters (common) -------------------------------------------------------------------------- Gateway-backed tools (`canvas`, `nodes`, `cron`): * `gatewayUrl` (default `ws://127.0.0.1:18789`) * `gatewayToken` (if auth enabled) * `timeoutMs` Browser tool: * `controlUrl` (defaults from config) [โ€‹](https://docs.clawd.bot/tools#recommended-agent-flows) Recommended agent flows ------------------------------------------------------------------------------------ Browser automation: 1. `browser` โ†’ `status` / `start` 2. `snapshot` (ai or aria) 3. `act` (click/type/press) 4. `screenshot` if you need visual confirmation Canvas render: 1. `canvas` โ†’ `present` 2. `a2ui_push` (optional) 3. `snapshot` Node targeting: 1. `nodes` โ†’ `status` 2. `describe` on the chosen node 3. `notify` / `run` / `camera_snap` / `screen_record` [โ€‹](https://docs.clawd.bot/tools#safety) Safety -------------------------------------------------- * Avoid direct `system.run`; use `nodes` โ†’ `run` only with explicit user consent. * Respect user consent for camera/screen capture. * Use `status/describe` to ensure permissions before invoking media commands. [โ€‹](https://docs.clawd.bot/tools#how-tools-are-presented-to-the-agent) How tools are presented to the agent -------------------------------------------------------------------------------------------------------------- Tools are exposed in two parallel channels: 1. **System prompt text**: a human-readable list + guidance. 2. **Tool schema**: the structured function definitions sent to the model API. That means the agent sees both โ€œwhat tools existโ€ and โ€œhow to call them.โ€ If a tool doesnโ€™t appear in the system prompt or the schema, the model cannot call it. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/tools.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/tools) [Poll](https://docs.clawd.bot/automation/poll) [Lobster](https://docs.clawd.bot/tools/lobster) โŒ˜I --- # Bluebubbles - Clawdbot [Skip to main content](https://docs.clawd.bot/channels/bluebubbles#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [BlueBubbles (macOS REST)](https://docs.clawd.bot/channels/bluebubbles#bluebubbles-macos-rest) * [Overview](https://docs.clawd.bot/channels/bluebubbles#overview) * [Quick start](https://docs.clawd.bot/channels/bluebubbles#quick-start) * [Onboarding](https://docs.clawd.bot/channels/bluebubbles#onboarding) * [Access control (DMs + groups)](https://docs.clawd.bot/channels/bluebubbles#access-control-dms-%2B-groups) * [Mention gating (groups)](https://docs.clawd.bot/channels/bluebubbles#mention-gating-groups) * [Command gating](https://docs.clawd.bot/channels/bluebubbles#command-gating) * [Typing + read receipts](https://docs.clawd.bot/channels/bluebubbles#typing-%2B-read-receipts) * [Advanced actions](https://docs.clawd.bot/channels/bluebubbles#advanced-actions) * [Message IDs (short vs full)](https://docs.clawd.bot/channels/bluebubbles#message-ids-short-vs-full) * [Block streaming](https://docs.clawd.bot/channels/bluebubbles#block-streaming) * [Media + limits](https://docs.clawd.bot/channels/bluebubbles#media-%2B-limits) * [Configuration reference](https://docs.clawd.bot/channels/bluebubbles#configuration-reference) * [Addressing / delivery targets](https://docs.clawd.bot/channels/bluebubbles#addressing-%2F-delivery-targets) * [Security](https://docs.clawd.bot/channels/bluebubbles#security) * [Troubleshooting](https://docs.clawd.bot/channels/bluebubbles#troubleshooting) [โ€‹](https://docs.clawd.bot/channels/bluebubbles#bluebubbles-macos-rest) BlueBubbles (macOS REST) =================================================================================================== Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended for iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#overview) Overview --------------------------------------------------------------------- * Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app/) ). * Recommended/tested: macOS Sequoia (15). macOS Tahoe (26) works; edit is currently broken on Tahoe, and group icon updates may report success but not sync. * Clawdbot talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). * Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls. * Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible). * Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes. * Reactions are surfaced as system events just like Slack/Telegram so agents can โ€œmentionโ€ them before replying. * Advanced features: edit, unsend, reply threading, message effects, group management. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#quick-start) Quick start --------------------------------------------------------------------------- 1. Install the BlueBubbles server on your Mac (follow the instructions at [bluebubbles.app/install](https://bluebubbles.app/install) ). 2. In the BlueBubbles config, enable the web API and set a password. 3. Run `clawdbot onboard` and select BlueBubbles, or configure manually: Copy { channels: { bluebubbles: { enabled: true, serverUrl: "http://192.168.1.100:1234", password: "example-password", webhookPath: "/bluebubbles-webhook" } } } 4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). 5. Start the gateway; it will register the webhook handler and start pairing. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#onboarding) Onboarding ------------------------------------------------------------------------- BlueBubbles is available in the interactive setup wizard: Copy clawdbot onboard The wizard prompts for: * **Server URL** (required): BlueBubbles server address (e.g., `http://192.168.1.100:1234`) * **Password** (required): API password from BlueBubbles Server settings * **Webhook path** (optional): Defaults to `/bluebubbles-webhook` * **DM policy**: pairing, allowlist, open, or disabled * **Allow list**: Phone numbers, emails, or chat targets You can also add BlueBubbles via CLI: Copy clawdbot channels add bluebubbles --http-url http://192.168.1.100:1234 --password [โ€‹](https://docs.clawd.bot/channels/bluebubbles#access-control-dms-+-groups) Access control (DMs + groups) ------------------------------------------------------------------------------------------------------------- DMs: * Default: `channels.bluebubbles.dmPolicy = "pairing"`. * Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour). * Approve via: * `clawdbot pairing list bluebubbles` * `clawdbot pairing approve bluebubbles ` * Pairing is the default token exchange. Details: [Pairing](https://docs.clawd.bot/start/pairing) Groups: * `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`). * `channels.bluebubbles.groupAllowFrom` controls who can trigger in groups when `allowlist` is set. ### [โ€‹](https://docs.clawd.bot/channels/bluebubbles#mention-gating-groups) Mention gating (groups) BlueBubbles supports mention gating for group chats, matching iMessage/WhatsApp behavior: * Uses `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) to detect mentions. * When `requireMention` is enabled for a group, the agent only responds when mentioned. * Control commands from authorized senders bypass mention gating. Per-group configuration: Copy { channels: { bluebubbles: { groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { "*": { requireMention: true }, // default for all groups "iMessage;-;chat123": { requireMention: false } // override for specific group } } } } ### [โ€‹](https://docs.clawd.bot/channels/bluebubbles#command-gating) Command gating * Control commands (e.g., `/config`, `/model`) require authorization. * Uses `allowFrom` and `groupAllowFrom` to determine command authorization. * Authorized senders can run control commands even without mentioning in groups. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#typing-+-read-receipts) Typing + read receipts ------------------------------------------------------------------------------------------------- * **Typing indicators**: Sent automatically before and during response generation. * **Read receipts**: Controlled by `channels.bluebubbles.sendReadReceipts` (default: `true`). * **Typing indicators**: Clawdbot sends typing start events; BlueBubbles clears typing automatically on send or timeout (manual stop via DELETE is unreliable). Copy { channels: { bluebubbles: { sendReadReceipts: false // disable read receipts } } } [โ€‹](https://docs.clawd.bot/channels/bluebubbles#advanced-actions) Advanced actions ------------------------------------------------------------------------------------- BlueBubbles supports advanced message actions when enabled in config: Copy { channels: { bluebubbles: { actions: { reactions: true, // tapbacks (default: true) edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe) unsend: true, // unsend messages (macOS 13+) reply: true, // reply threading by message GUID sendWithEffect: true, // message effects (slam, loud, etc.) renameGroup: true, // rename group chats setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe) addParticipant: true, // add participants to groups removeParticipant: true, // remove participants from groups leaveGroup: true, // leave group chats sendAttachment: true // send attachments/media } } } } Available actions: * **react**: Add/remove tapback reactions (`messageId`, `emoji`, `remove`) * **edit**: Edit a sent message (`messageId`, `text`) * **unsend**: Unsend a message (`messageId`) * **reply**: Reply to a specific message (`messageId`, `text`, `to`) * **sendWithEffect**: Send with iMessage effect (`text`, `to`, `effectId`) * **renameGroup**: Rename a group chat (`chatGuid`, `displayName`) * **setGroupIcon**: Set a group chatโ€™s icon/photo (`chatGuid`, `media`) โ€” flaky on macOS 26 Tahoe (API may return success but the icon does not sync). * **addParticipant**: Add someone to a group (`chatGuid`, `address`) * **removeParticipant**: Remove someone from a group (`chatGuid`, `address`) * **leaveGroup**: Leave a group chat (`chatGuid`) * **sendAttachment**: Send media/files (`to`, `buffer`, `filename`, `asVoice`) * Voice memos: set `asVoice: true` with **MP3** or **CAF** audio to send as an iMessage voice message. BlueBubbles converts MP3 โ†’ CAF when sending voice memos. ### [โ€‹](https://docs.clawd.bot/channels/bluebubbles#message-ids-short-vs-full) Message IDs (short vs full) Clawdbot may surface _short_ message IDs (e.g., `1`, `2`) to save tokens. * `MessageSid` / `ReplyToId` can be short IDs. * `MessageSidFull` / `ReplyToIdFull` contain the provider full IDs. * Short IDs are in-memory; they can expire on restart or cache eviction. * Actions accept short or full `messageId`, but short IDs will error if no longer available. Use full IDs for durable automations and storage: * Templates: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` * Context: `MessageSidFull` / `ReplyToIdFull` in inbound payloads See [Configuration](https://docs.clawd.bot/gateway/configuration) for template variables. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#block-streaming) Block streaming ----------------------------------------------------------------------------------- Control whether responses are sent as a single message or streamed in blocks: Copy { channels: { bluebubbles: { blockStreaming: true // enable block streaming (default behavior) } } } [โ€‹](https://docs.clawd.bot/channels/bluebubbles#media-+-limits) Media + limits --------------------------------------------------------------------------------- * Inbound attachments are downloaded and stored in the media cache. * Media cap via `channels.bluebubbles.mediaMaxMb` (default: 8 MB). * Outbound text is chunked to `channels.bluebubbles.textChunkLimit` (default: 4000 chars). [โ€‹](https://docs.clawd.bot/channels/bluebubbles#configuration-reference) Configuration reference --------------------------------------------------------------------------------------------------- Full configuration: [Configuration](https://docs.clawd.bot/gateway/configuration) Provider options: * `channels.bluebubbles.enabled`: Enable/disable the channel. * `channels.bluebubbles.serverUrl`: BlueBubbles REST API base URL. * `channels.bluebubbles.password`: API password. * `channels.bluebubbles.webhookPath`: Webhook endpoint path (default: `/bluebubbles-webhook`). * `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`). * `channels.bluebubbles.allowFrom`: DM allowlist (handles, emails, E.164 numbers, `chat_id:*`, `chat_guid:*`). * `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`). * `channels.bluebubbles.groupAllowFrom`: Group sender allowlist. * `channels.bluebubbles.groups`: Per-group config (`requireMention`, etc.). * `channels.bluebubbles.sendReadReceipts`: Send read receipts (default: `true`). * `channels.bluebubbles.blockStreaming`: Enable block streaming (default: `true`). * `channels.bluebubbles.textChunkLimit`: Outbound chunk size in chars (default: 4000). * `channels.bluebubbles.mediaMaxMb`: Inbound media cap in MB (default: 8). * `channels.bluebubbles.historyLimit`: Max group messages for context (0 disables). * `channels.bluebubbles.dmHistoryLimit`: DM history limit. * `channels.bluebubbles.actions`: Enable/disable specific actions. * `channels.bluebubbles.accounts`: Multi-account configuration. Related global options: * `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`). * `messages.responsePrefix`. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#addressing-/-delivery-targets) Addressing / delivery targets --------------------------------------------------------------------------------------------------------------- Prefer `chat_guid` for stable routing: * `chat_guid:iMessage;-;+15555550123` (preferred for groups) * `chat_id:123` * `chat_identifier:...` * Direct handles: `+15555550123`, `[[emailย protected]](https://docs.clawd.bot/cdn-cgi/l/email-protection) ` [โ€‹](https://docs.clawd.bot/channels/bluebubbles#security) Security --------------------------------------------------------------------- * Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted. * Keep the API password and webhook endpoint secret (treat them like credentials). * Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN. [โ€‹](https://docs.clawd.bot/channels/bluebubbles#troubleshooting) Troubleshooting ----------------------------------------------------------------------------------- * If typing/read events stop working, check the BlueBubbles webhook logs and verify the gateway path matches `channels.bluebubbles.webhookPath`. * Pairing codes expire after one hour; use `clawdbot pairing list bluebubbles` and `clawdbot pairing approve bluebubbles `. * Reactions require the BlueBubbles private API (`POST /api/v1/message/react`); ensure the server version exposes it. * Edit/unsend require macOS 13+ and a compatible BlueBubbles server version. On macOS 26 (Tahoe), edit is currently broken due to private API changes. * Group icon updates can be flaky on macOS 26 (Tahoe): the API may return success but the new icon does not sync. * Clawdbot auto-hides known-broken actions based on the BlueBubbles serverโ€™s macOS version. If edit still appears on macOS 26 (Tahoe), disable it manually with `channels.bluebubbles.actions.edit=false`. * For status/health info: `clawdbot status --all` or `clawdbot status --deep`. For general channel workflow reference, see [Channels](https://docs.clawd.bot/channels) and the [Plugins](https://docs.clawd.bot/plugins) guide. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/channels/bluebubbles.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/channels/bluebubbles) โŒ˜I --- # Nextcloud talk - Clawdbot [Skip to main content](https://docs.clawd.bot/channels/nextcloud-talk#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Nextcloud Talk (plugin)](https://docs.clawd.bot/channels/nextcloud-talk#nextcloud-talk-plugin) * [Plugin required](https://docs.clawd.bot/channels/nextcloud-talk#plugin-required) * [Quick setup (beginner)](https://docs.clawd.bot/channels/nextcloud-talk#quick-setup-beginner) * [Notes](https://docs.clawd.bot/channels/nextcloud-talk#notes) * [Access control (DMs)](https://docs.clawd.bot/channels/nextcloud-talk#access-control-dms) * [Rooms (groups)](https://docs.clawd.bot/channels/nextcloud-talk#rooms-groups) * [Capabilities](https://docs.clawd.bot/channels/nextcloud-talk#capabilities) * [Configuration reference (Nextcloud Talk)](https://docs.clawd.bot/channels/nextcloud-talk#configuration-reference-nextcloud-talk) [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#nextcloud-talk-plugin) Nextcloud Talk (plugin) ==================================================================================================== Status: supported via plugin (webhook bot). Direct messages, rooms, reactions, and markdown messages are supported. [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#plugin-required) Plugin required -------------------------------------------------------------------------------------- Nextcloud Talk ships as a plugin and is not bundled with the core install. Install via CLI (npm registry): Copy clawdbot plugins install @clawdbot/nextcloud-talk Local checkout (when running from a git repo): Copy clawdbot plugins install ./extensions/nextcloud-talk If you choose Nextcloud Talk during configure/onboarding and a git checkout is detected, Clawdbot will offer the local install path automatically. Details: [Plugins](https://docs.clawd.bot/plugin) [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#quick-setup-beginner) Quick setup (beginner) -------------------------------------------------------------------------------------------------- 1. Install the Nextcloud Talk plugin. 2. On your Nextcloud server, create a bot: Copy ./occ talk:bot:install "Clawdbot" "" "" --feature reaction 3. Enable the bot in the target room settings. 4. Configure Clawdbot: * Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` * Or env: `NEXTCLOUD_TALK_BOT_SECRET` (default account only) 5. Restart the gateway (or finish onboarding). Minimal config: Copy { channels: { "nextcloud-talk": { enabled: true, baseUrl: "https://cloud.example.com", botSecret: "shared-secret", dmPolicy: "pairing" } } } [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#notes) Notes ------------------------------------------------------------------ * Bots cannot initiate DMs. The user must message the bot first. * Webhook URL must be reachable by the Gateway; set `webhookPublicUrl` if behind a proxy. * Media uploads are not supported by the bot API; media is sent as URLs. * The webhook payload does not distinguish DMs vs rooms; set `apiUser` + `apiPassword` to enable room-type lookups (otherwise DMs are treated as rooms). [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#access-control-dms) Access control (DMs) ---------------------------------------------------------------------------------------------- * Default: `channels.nextcloud-talk.dmPolicy = "pairing"`. Unknown senders get a pairing code. * Approve via: * `clawdbot pairing list nextcloud-talk` * `clawdbot pairing approve nextcloud-talk ` * Public DMs: `channels.nextcloud-talk.dmPolicy="open"` plus `channels.nextcloud-talk.allowFrom=["*"]`. [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#rooms-groups) Rooms (groups) ---------------------------------------------------------------------------------- * Default: `channels.nextcloud-talk.groupPolicy = "allowlist"` (mention-gated). * Allowlist rooms with `channels.nextcloud-talk.rooms`: Copy { channels: { "nextcloud-talk": { rooms: { "room-token": { requireMention: true } } } } } * To allow no rooms, keep the allowlist empty or set `channels.nextcloud-talk.groupPolicy="disabled"`. [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#capabilities) Capabilities -------------------------------------------------------------------------------- | Feature | Status | | --- | --- | | Direct messages | Supported | | Rooms | Supported | | Threads | Not supported | | Media | URL-only | | Reactions | Supported | | Native commands | Not supported | [โ€‹](https://docs.clawd.bot/channels/nextcloud-talk#configuration-reference-nextcloud-talk) Configuration reference (Nextcloud Talk) -------------------------------------------------------------------------------------------------------------------------------------- Full configuration: [Configuration](https://docs.clawd.bot/gateway/configuration) Provider options: * `channels.nextcloud-talk.enabled`: enable/disable channel startup. * `channels.nextcloud-talk.baseUrl`: Nextcloud instance URL. * `channels.nextcloud-talk.botSecret`: bot shared secret. * `channels.nextcloud-talk.botSecretFile`: secret file path. * `channels.nextcloud-talk.apiUser`: API user for room lookups (DM detection). * `channels.nextcloud-talk.apiPassword`: API/app password for room lookups. * `channels.nextcloud-talk.apiPasswordFile`: API password file path. * `channels.nextcloud-talk.webhookPort`: webhook listener port (default: 8788). * `channels.nextcloud-talk.webhookHost`: webhook host (default: 0.0.0.0). * `channels.nextcloud-talk.webhookPath`: webhook path (default: /nextcloud-talk-webhook). * `channels.nextcloud-talk.webhookPublicUrl`: externally reachable webhook URL. * `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`. * `channels.nextcloud-talk.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`. * `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`. * `channels.nextcloud-talk.groupAllowFrom`: group allowlist (user IDs). * `channels.nextcloud-talk.rooms`: per-room settings and allowlist. * `channels.nextcloud-talk.historyLimit`: group history limit (0 disables). * `channels.nextcloud-talk.dmHistoryLimit`: DM history limit (0 disables). * `channels.nextcloud-talk.dms`: per-DM overrides (historyLimit). * `channels.nextcloud-talk.textChunkLimit`: outbound text chunk size (chars). * `channels.nextcloud-talk.blockStreaming`: disable block streaming for this channel. * `channels.nextcloud-talk.blockStreamingCoalesce`: block streaming coalesce tuning. * `channels.nextcloud-talk.mediaMaxMb`: inbound media cap (MB). [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/channels/nextcloud-talk.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/channels/nextcloud-talk) โŒ˜I --- # Nostr - Clawdbot [Skip to main content](https://docs.clawd.bot/channels/nostr#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Nostr](https://docs.clawd.bot/channels/nostr#nostr) * [Install (on demand)](https://docs.clawd.bot/channels/nostr#install-on-demand) * [Onboarding (recommended)](https://docs.clawd.bot/channels/nostr#onboarding-recommended) * [Manual install](https://docs.clawd.bot/channels/nostr#manual-install) * [Quick setup](https://docs.clawd.bot/channels/nostr#quick-setup) * [Configuration reference](https://docs.clawd.bot/channels/nostr#configuration-reference) * [Profile metadata](https://docs.clawd.bot/channels/nostr#profile-metadata) * [Access control](https://docs.clawd.bot/channels/nostr#access-control) * [DM policies](https://docs.clawd.bot/channels/nostr#dm-policies) * [Allowlist example](https://docs.clawd.bot/channels/nostr#allowlist-example) * [Key formats](https://docs.clawd.bot/channels/nostr#key-formats) * [Relays](https://docs.clawd.bot/channels/nostr#relays) * [Protocol support](https://docs.clawd.bot/channels/nostr#protocol-support) * [Testing](https://docs.clawd.bot/channels/nostr#testing) * [Local relay](https://docs.clawd.bot/channels/nostr#local-relay) * [Manual test](https://docs.clawd.bot/channels/nostr#manual-test) * [Troubleshooting](https://docs.clawd.bot/channels/nostr#troubleshooting) * [Not receiving messages](https://docs.clawd.bot/channels/nostr#not-receiving-messages) * [Not sending responses](https://docs.clawd.bot/channels/nostr#not-sending-responses) * [Duplicate responses](https://docs.clawd.bot/channels/nostr#duplicate-responses) * [Security](https://docs.clawd.bot/channels/nostr#security) * [Limitations (MVP)](https://docs.clawd.bot/channels/nostr#limitations-mvp) [โ€‹](https://docs.clawd.bot/channels/nostr#nostr) Nostr ========================================================= **Status:** Optional plugin (disabled by default). Nostr is a decentralized protocol for social networking. This channel enables Clawdbot to receive and respond to encrypted direct messages (DMs) via NIP-04. [โ€‹](https://docs.clawd.bot/channels/nostr#install-on-demand) Install (on demand) ----------------------------------------------------------------------------------- ### [โ€‹](https://docs.clawd.bot/channels/nostr#onboarding-recommended) Onboarding (recommended) * The onboarding wizard (`clawdbot onboard`) and `clawdbot channels add` list optional channel plugins. * Selecting Nostr prompts you to install the plugin on demand. Install defaults: * **Dev channel + git checkout available:** uses the local plugin path. * **Stable/Beta:** downloads from npm. You can always override the choice in the prompt. ### [โ€‹](https://docs.clawd.bot/channels/nostr#manual-install) Manual install Copy clawdbot plugins install @clawdbot/nostr Use a local checkout (dev workflows): Copy clawdbot plugins install --link /extensions/nostr Restart the Gateway after installing or enabling plugins. [โ€‹](https://docs.clawd.bot/channels/nostr#quick-setup) Quick setup --------------------------------------------------------------------- 1. Generate a Nostr keypair (if needed): Copy # Using nak nak key generate 2. Add to config: Copy { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}" } } } 3. Export the key: Copy export NOSTR_PRIVATE_KEY="nsec1..." 4. Restart the Gateway. [โ€‹](https://docs.clawd.bot/channels/nostr#configuration-reference) Configuration reference --------------------------------------------------------------------------------------------- | Key | Type | Default | Description | | --- | --- | --- | --- | | `privateKey` | string | required | Private key in `nsec` or hex format | | `relays` | string\[\] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URLs (WebSocket) | | `dmPolicy` | string | `pairing` | DM access policy | | `allowFrom` | string\[\] | `[]` | Allowed sender pubkeys | | `enabled` | boolean | `true` | Enable/disable channel | | `name` | string | \- | Display name | | `profile` | object | \- | NIP-01 profile metadata | [โ€‹](https://docs.clawd.bot/channels/nostr#profile-metadata) Profile metadata ------------------------------------------------------------------------------- Profile data is published as a NIP-01 `kind:0` event. You can manage it from the Control UI (Channels -> Nostr -> Profile) or set it directly in config. Example: Copy { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "profile": { "name": "clawdbot", "displayName": "Clawdbot", "about": "Personal assistant DM bot", "picture": "https://example.com/avatar.png", "banner": "https://example.com/banner.png", "website": "https://example.com", "nip05": "[emailย protected]", "lud16": "[emailย protected]" } } } } Notes: * Profile URLs must use `https://`. * Importing from relays merges fields and preserves local overrides. [โ€‹](https://docs.clawd.bot/channels/nostr#access-control) Access control --------------------------------------------------------------------------- ### [โ€‹](https://docs.clawd.bot/channels/nostr#dm-policies) DM policies * **pairing** (default): unknown senders get a pairing code. * **allowlist**: only pubkeys in `allowFrom` can DM. * **open**: public inbound DMs (requires `allowFrom: ["*"]`). * **disabled**: ignore inbound DMs. ### [โ€‹](https://docs.clawd.bot/channels/nostr#allowlist-example) Allowlist example Copy { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "dmPolicy": "allowlist", "allowFrom": ["npub1abc...", "npub1xyz..."] } } } [โ€‹](https://docs.clawd.bot/channels/nostr#key-formats) Key formats --------------------------------------------------------------------- Accepted formats: * **Private key:** `nsec...` or 64-char hex * **Pubkeys (`allowFrom`):** `npub...` or hex [โ€‹](https://docs.clawd.bot/channels/nostr#relays) Relays ----------------------------------------------------------- Defaults: `relay.damus.io` and `nos.lol`. Copy { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "relays": [\ "wss://relay.damus.io",\ "wss://relay.primal.net",\ "wss://nostr.wine"\ ] } } } Tips: * Use 2-3 relays for redundancy. * Avoid too many relays (latency, duplication). * Paid relays can improve reliability. * Local relays are fine for testing (`ws://localhost:7777`). [โ€‹](https://docs.clawd.bot/channels/nostr#protocol-support) Protocol support ------------------------------------------------------------------------------- | NIP | Status | Description | | --- | --- | --- | | NIP-01 | Supported | Basic event format + profile metadata | | NIP-04 | Supported | Encrypted DMs (`kind:4`) | | NIP-17 | Planned | Gift-wrapped DMs | | NIP-44 | Planned | Versioned encryption | [โ€‹](https://docs.clawd.bot/channels/nostr#testing) Testing ------------------------------------------------------------- ### [โ€‹](https://docs.clawd.bot/channels/nostr#local-relay) Local relay Copy # Start strfry docker run -p 7777:7777 ghcr.io/hoytech/strfry Copy { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "relays": ["ws://localhost:7777"] } } } ### [โ€‹](https://docs.clawd.bot/channels/nostr#manual-test) Manual test 1. Note the bot pubkey (npub) from logs. 2. Open a Nostr client (Damus, Amethyst, etc.). 3. DM the bot pubkey. 4. Verify the response. [โ€‹](https://docs.clawd.bot/channels/nostr#troubleshooting) Troubleshooting ----------------------------------------------------------------------------- ### [โ€‹](https://docs.clawd.bot/channels/nostr#not-receiving-messages) Not receiving messages * Verify the private key is valid. * Ensure relay URLs are reachable and use `wss://` (or `ws://` for local). * Confirm `enabled` is not `false`. * Check Gateway logs for relay connection errors. ### [โ€‹](https://docs.clawd.bot/channels/nostr#not-sending-responses) Not sending responses * Check relay accepts writes. * Verify outbound connectivity. * Watch for relay rate limits. ### [โ€‹](https://docs.clawd.bot/channels/nostr#duplicate-responses) Duplicate responses * Expected when using multiple relays. * Messages are deduplicated by event ID; only the first delivery triggers a response. [โ€‹](https://docs.clawd.bot/channels/nostr#security) Security --------------------------------------------------------------- * Never commit private keys. * Use environment variables for keys. * Consider `allowlist` for production bots. [โ€‹](https://docs.clawd.bot/channels/nostr#limitations-mvp) Limitations (MVP) ------------------------------------------------------------------------------- * Direct messages only (no group chats). * No media attachments. * NIP-04 only (NIP-17 gift-wrap planned). [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/channels/nostr.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/channels/nostr) โŒ˜I --- # Index - Clawdbot [Skip to main content](https://docs.clawd.bot/channels/index#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Chat Channels](https://docs.clawd.bot/channels/index#chat-channels) * [Supported channels](https://docs.clawd.bot/channels/index#supported-channels) * [Notes](https://docs.clawd.bot/channels/index#notes) [โ€‹](https://docs.clawd.bot/channels/index#chat-channels) Chat Channels ========================================================================= Clawdbot can talk to you on any chat app you already use. Each channel connects via the Gateway. Text is supported everywhere; media and reactions vary by channel. [โ€‹](https://docs.clawd.bot/channels/index#supported-channels) Supported channels ----------------------------------------------------------------------------------- * [WhatsApp](https://docs.clawd.bot/channels/whatsapp) โ€” Most popular; uses Baileys and requires QR pairing. * [Telegram](https://docs.clawd.bot/channels/telegram) โ€” Bot API via grammY; supports groups. * [Discord](https://docs.clawd.bot/channels/discord) โ€” Discord Bot API + Gateway; supports servers, channels, and DMs. * [Slack](https://docs.clawd.bot/channels/slack) โ€” Bolt SDK; workspace apps. * [Google Chat](https://docs.clawd.bot/channels/googlechat) โ€” Google Chat API app via HTTP webhook. * [Mattermost](https://docs.clawd.bot/channels/mattermost) โ€” Bot API + WebSocket; channels, groups, DMs (plugin, installed separately). * [Signal](https://docs.clawd.bot/channels/signal) โ€” signal-cli; privacy-focused. * [BlueBubbles](https://docs.clawd.bot/channels/bluebubbles) โ€” **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management โ€” edit currently broken on macOS 26 Tahoe). * [iMessage](https://docs.clawd.bot/channels/imessage) โ€” macOS only; native integration via imsg (legacy, consider BlueBubbles for new setups). * [Microsoft Teams](https://docs.clawd.bot/channels/msteams) โ€” Bot Framework; enterprise support (plugin, installed separately). * [Nextcloud Talk](https://docs.clawd.bot/channels/nextcloud-talk) โ€” Self-hosted chat via Nextcloud Talk (plugin, installed separately). * [Matrix](https://docs.clawd.bot/channels/matrix) โ€” Matrix protocol (plugin, installed separately). * [Nostr](https://docs.clawd.bot/channels/nostr) โ€” Decentralized DMs via NIP-04 (plugin, installed separately). * [Tlon](https://docs.clawd.bot/channels/tlon) โ€” Urbit-based messenger (plugin, installed separately). * [Zalo](https://docs.clawd.bot/channels/zalo) โ€” Zalo Bot API; Vietnamโ€™s popular messenger (plugin, installed separately). * [Zalo Personal](https://docs.clawd.bot/channels/zalouser) โ€” Zalo personal account via QR login (plugin, installed separately). * [WebChat](https://docs.clawd.bot/web/webchat) โ€” Gateway WebChat UI over WebSocket. [โ€‹](https://docs.clawd.bot/channels/index#notes) Notes --------------------------------------------------------- * Channels can run simultaneously; configure multiple and Clawdbot will route per chat. * Group behavior varies by channel; see [Groups](https://docs.clawd.bot/concepts/groups) . * DM pairing and allowlists are enforced for safety; see [Security](https://docs.clawd.bot/gateway/security) . * Telegram internals: [grammY notes](https://docs.clawd.bot/channels/grammy) . * Troubleshooting: [Channel troubleshooting](https://docs.clawd.bot/channels/troubleshooting) . * Model providers are documented separately; see [Model Providers](https://docs.clawd.bot/providers/models) . [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/channels/index.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/channels/index) [Tui](https://docs.clawd.bot/tui) [Whatsapp](https://docs.clawd.bot/channels/whatsapp) โŒ˜I --- # Tts - Clawdbot [Skip to main content](https://docs.clawd.bot/tts#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Text-to-speech (TTS)](https://docs.clawd.bot/tts#text-to-speech-tts) * [Supported services](https://docs.clawd.bot/tts#supported-services) * [Required keys](https://docs.clawd.bot/tts#required-keys) * [Service links](https://docs.clawd.bot/tts#service-links) * [Is it enabled by default?](https://docs.clawd.bot/tts#is-it-enabled-by-default) * [Config](https://docs.clawd.bot/tts#config) * [Minimal config (enable + provider)](https://docs.clawd.bot/tts#minimal-config-enable-%2B-provider) * [OpenAI primary with ElevenLabs fallback](https://docs.clawd.bot/tts#openai-primary-with-elevenlabs-fallback) * [Custom limits + prefs path](https://docs.clawd.bot/tts#custom-limits-%2B-prefs-path) * [Disable auto-summary for long replies](https://docs.clawd.bot/tts#disable-auto-summary-for-long-replies) * [Notes on fields](https://docs.clawd.bot/tts#notes-on-fields) * [Model-driven overrides (default on)](https://docs.clawd.bot/tts#model-driven-overrides-default-on) * [Per-user preferences](https://docs.clawd.bot/tts#per-user-preferences) * [Output formats (fixed)](https://docs.clawd.bot/tts#output-formats-fixed) * [Auto-TTS behavior](https://docs.clawd.bot/tts#auto-tts-behavior) * [Flow diagram](https://docs.clawd.bot/tts#flow-diagram) * [Slash command usage](https://docs.clawd.bot/tts#slash-command-usage) * [Agent tool](https://docs.clawd.bot/tts#agent-tool) * [Gateway RPC](https://docs.clawd.bot/tts#gateway-rpc) [โ€‹](https://docs.clawd.bot/tts#text-to-speech-tts) Text-to-speech (TTS) ========================================================================== Clawdbot can convert outbound replies into audio using ElevenLabs or OpenAI. It works anywhere Clawdbot can send audio; Telegram gets a round voice-note bubble. [โ€‹](https://docs.clawd.bot/tts#supported-services) Supported services ------------------------------------------------------------------------ * **ElevenLabs** (primary or fallback provider) * **OpenAI** (primary or fallback provider; also used for summaries) [โ€‹](https://docs.clawd.bot/tts#required-keys) Required keys -------------------------------------------------------------- At least one of: * `ELEVENLABS_API_KEY` (or `XI_API_KEY`) * `OPENAI_API_KEY` If both are configured, the selected provider is used first and the other is a fallback. Auto-summary uses the configured `summaryModel` (or `agents.defaults.model.primary`), so that provider must also be authenticated if you enable summaries. [โ€‹](https://docs.clawd.bot/tts#service-links) Service links -------------------------------------------------------------- * [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech) * [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio) * [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) * [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication) [โ€‹](https://docs.clawd.bot/tts#is-it-enabled-by-default) Is it enabled by default? ------------------------------------------------------------------------------------- No. TTS is **disabled** by default. Enable it in config or with `/tts on`, which writes a local preference override. [โ€‹](https://docs.clawd.bot/tts#config) Config ------------------------------------------------ TTS config lives under `messages.tts` in `clawdbot.json`. Full schema is in [Gateway configuration](https://docs.clawd.bot/gateway/configuration) . ### [โ€‹](https://docs.clawd.bot/tts#minimal-config-enable-+-provider) Minimal config (enable + provider) Copy { messages: { tts: { enabled: true, provider: "elevenlabs" } } } ### [โ€‹](https://docs.clawd.bot/tts#openai-primary-with-elevenlabs-fallback) OpenAI primary with ElevenLabs fallback Copy { messages: { tts: { enabled: true, provider: "openai", summaryModel: "openai/gpt-4.1-mini", modelOverrides: { enabled: true }, openai: { apiKey: "openai_api_key", model: "gpt-4o-mini-tts", voice: "alloy" }, elevenlabs: { apiKey: "elevenlabs_api_key", baseUrl: "https://api.elevenlabs.io", voiceId: "voice_id", modelId: "eleven_multilingual_v2", seed: 42, applyTextNormalization: "auto", languageCode: "en", voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 } } } } } ### [โ€‹](https://docs.clawd.bot/tts#custom-limits-+-prefs-path) Custom limits + prefs path Copy { messages: { tts: { enabled: true, maxTextLength: 4000, timeoutMs: 30000, prefsPath: "~/.clawdbot/settings/tts.json" } } } ### [โ€‹](https://docs.clawd.bot/tts#disable-auto-summary-for-long-replies) Disable auto-summary for long replies Copy { messages: { tts: { enabled: true } } } Then run: Copy /tts summary off ### [โ€‹](https://docs.clawd.bot/tts#notes-on-fields) Notes on fields * `enabled`: master toggle (default `false`; local prefs can override). * `mode`: `"final"` (default) or `"all"` (includes tool/block replies). * `provider`: `"elevenlabs"` or `"openai"` (fallback is automatic). * `summaryModel`: optional cheap model for auto-summary; defaults to `agents.defaults.model.primary`. * Accepts `provider/model` or a configured model alias. * `modelOverrides`: allow the model to emit TTS directives (on by default). * `maxTextLength`: hard cap for TTS input (chars). `/tts audio` fails if exceeded. * `timeoutMs`: request timeout (ms). * `prefsPath`: override the local prefs JSON path. * `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `OPENAI_API_KEY`). * `elevenlabs.baseUrl`: override ElevenLabs API base URL. * `elevenlabs.voiceSettings`: * `stability`, `similarityBoost`, `style`: `0..1` * `useSpeakerBoost`: `true|false` * `speed`: `0.5..2.0` (1.0 = normal) * `elevenlabs.applyTextNormalization`: `auto|on|off` * `elevenlabs.languageCode`: 2-letter ISO 639-1 (e.g. `en`, `de`) * `elevenlabs.seed`: integer `0..4294967295` (best-effort determinism) [โ€‹](https://docs.clawd.bot/tts#model-driven-overrides-default-on) Model-driven overrides (default on) -------------------------------------------------------------------------------------------------------- By default, the model **can** emit TTS directives for a single reply. When enabled, the model can emit `[[tts:...]]` directives to override the voice for a single reply, plus an optional `[[tts:text]]...[[/tts:text]]` block to provide expressive tags (laughter, singing cues, etc) that should only appear in the audio. Example reply payload: Copy Here you go. [[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] [[tts:text]](laughs) Read the song once more.[[/tts:text]] Available directive keys (when enabled): * `provider` (`openai` | `elevenlabs`) * `voice` (OpenAI voice) or `voiceId` (ElevenLabs) * `model` (OpenAI TTS model or ElevenLabs model id) * `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` * `applyTextNormalization` (`auto|on|off`) * `languageCode` (ISO 639-1) * `seed` Disable all model overrides: Copy { messages: { tts: { modelOverrides: { enabled: false } } } } Optional allowlist (disable specific overrides while keeping tags enabled): Copy { messages: { tts: { modelOverrides: { enabled: true, allowProvider: false, allowSeed: false } } } } [โ€‹](https://docs.clawd.bot/tts#per-user-preferences) Per-user preferences ---------------------------------------------------------------------------- Slash commands write local overrides to `prefsPath` (default: `~/.clawdbot/settings/tts.json`, override with `CLAWDBOT_TTS_PREFS` or `messages.tts.prefsPath`). Stored fields: * `enabled` * `provider` * `maxLength` (summary threshold; default 1500 chars) * `summarize` (default `true`) These override `messages.tts.*` for that host. [โ€‹](https://docs.clawd.bot/tts#output-formats-fixed) Output formats (fixed) ------------------------------------------------------------------------------ * **Telegram**: Opus voice note (`opus_48000_64` from ElevenLabs, `opus` from OpenAI). * 48kHz / 64kbps is a good voice-note tradeoff and required for the round bubble. * **Other channels**: MP3 (`mp3_44100_128` from ElevenLabs, `mp3` from OpenAI). * 44.1kHz / 128kbps is the default balance for speech clarity. This is not configurable; Telegram expects Opus for voice-note UX. [โ€‹](https://docs.clawd.bot/tts#auto-tts-behavior) Auto-TTS behavior ---------------------------------------------------------------------- When enabled, Clawdbot: * skips TTS if the reply already contains media or a `MEDIA:` directive. * skips very short replies (< 10 chars). * summarizes long replies when enabled using `agents.defaults.model.primary` (or `summaryModel`). * attaches the generated audio to the reply. If the reply exceeds `maxLength` and summary is off (or no API key for the summary model), audio is skipped and the normal text reply is sent. [โ€‹](https://docs.clawd.bot/tts#flow-diagram) Flow diagram ------------------------------------------------------------ Copy Reply -> TTS enabled? no -> send text yes -> has media / MEDIA: / short? yes -> send text no -> length > limit? no -> TTS -> attach audio yes -> summary enabled? no -> send text yes -> summarize (summaryModel or agents.defaults.model.primary) -> TTS -> attach audio [โ€‹](https://docs.clawd.bot/tts#slash-command-usage) Slash command usage -------------------------------------------------------------------------- There is a single command: `/tts`. See [Slash commands](https://docs.clawd.bot/tools/slash-commands) for enablement details. Discord note: `/tts` is a built-in Discord command, so Clawdbot registers `/voice` as the native command there. Text `/tts ...` still works. Copy /tts on /tts off /tts status /tts provider openai /tts limit 2000 /tts summary off /tts audio Hello from Clawdbot Notes: * Commands require an authorized sender (allowlist/owner rules still apply). * `commands.text` or native command registration must be enabled. * `limit` and `summary` are stored in local prefs, not the main config. * `/tts audio` generates a one-off audio reply (does not toggle TTS on). [โ€‹](https://docs.clawd.bot/tts#agent-tool) Agent tool -------------------------------------------------------- The `tts` tool converts text to speech and returns a `MEDIA:` path. When the result is Telegram-compatible, the tool includes `[[audio_as_voice]]` so Telegram sends a voice bubble. [โ€‹](https://docs.clawd.bot/tts#gateway-rpc) Gateway RPC ---------------------------------------------------------- Gateway methods: * `tts.status` * `tts.enable` * `tts.disable` * `tts.convert` * `tts.setProvider` * `tts.providers` [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/tts.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/tts) โŒ˜I --- # Cron add hardening - Clawdbot [Skip to main content](https://docs.clawd.bot/experiments/plans/cron-add-hardening#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Cron Add Hardening & Schema Alignment](https://docs.clawd.bot/experiments/plans/cron-add-hardening#cron-add-hardening-%26-schema-alignment) * [Context](https://docs.clawd.bot/experiments/plans/cron-add-hardening#context) * [Goals](https://docs.clawd.bot/experiments/plans/cron-add-hardening#goals) * [Non-goals](https://docs.clawd.bot/experiments/plans/cron-add-hardening#non-goals) * [Findings (current gaps)](https://docs.clawd.bot/experiments/plans/cron-add-hardening#findings-current-gaps) * [What changed](https://docs.clawd.bot/experiments/plans/cron-add-hardening#what-changed) * [Current behavior](https://docs.clawd.bot/experiments/plans/cron-add-hardening#current-behavior) * [Verification](https://docs.clawd.bot/experiments/plans/cron-add-hardening#verification) * [Optional Follow-ups](https://docs.clawd.bot/experiments/plans/cron-add-hardening#optional-follow-ups) * [Open Questions](https://docs.clawd.bot/experiments/plans/cron-add-hardening#open-questions) [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#cron-add-hardening-&-schema-alignment) Cron Add Hardening & Schema Alignment =============================================================================================================================================== [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#context) Context ----------------------------------------------------------------------------------- Recent gateway logs show repeated `cron.add` failures with invalid parameters (missing `sessionTarget`, `wakeMode`, `payload`, and malformed `schedule`). This indicates that at least one client (likely the agent tool call path) is sending wrapped or partially specified job payloads. Separately, there is drift between cron provider enums in TypeScript, gateway schema, CLI flags, and UI form types, plus a UI mismatch for `cron.status` (expects `jobCount` while gateway returns `jobs`). [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#goals) Goals ------------------------------------------------------------------------------- * Stop `cron.add` INVALID\_REQUEST spam by normalizing common wrapper payloads and inferring missing `kind` fields. * Align cron provider lists across gateway schema, cron types, CLI docs, and UI forms. * Make agent cron tool schema explicit so the LLM produces correct job payloads. * Fix the Control UI cron status job count display. * Add tests to cover normalization and tool behavior. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#non-goals) Non-goals --------------------------------------------------------------------------------------- * Change cron scheduling semantics or job execution behavior. * Add new schedule kinds or cron expression parsing. * Overhaul the UI/UX for cron beyond the necessary field fixes. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#findings-current-gaps) Findings (current gaps) ----------------------------------------------------------------------------------------------------------------- * `CronPayloadSchema` in gateway excludes `signal` + `imessage`, while TS types include them. * Control UI CronStatus expects `jobCount`, but gateway returns `jobs`. * Agent cron tool schema allows arbitrary `job` objects, enabling malformed inputs. * Gateway strictly validates `cron.add` with no normalization, so wrapped payloads fail. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#what-changed) What changed --------------------------------------------------------------------------------------------- * `cron.add` and `cron.update` now normalize common wrapper shapes and infer missing `kind` fields. * Agent cron tool schema matches the gateway schema, which reduces invalid payloads. * Provider enums are aligned across gateway, CLI, UI, and macOS picker. * Control UI uses the gatewayโ€™s `jobs` count field for status. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#current-behavior) Current behavior ----------------------------------------------------------------------------------------------------- * **Normalization:** wrapped `data`/`job` payloads are unwrapped; `schedule.kind` and `payload.kind` are inferred when safe. * **Defaults:** safe defaults are applied for `wakeMode` and `sessionTarget` when missing. * **Providers:** Discord/Slack/Signal/iMessage are now consistently surfaced across CLI/UI. See [Cron jobs](https://docs.clawd.bot/automation/cron-jobs) for the normalized shape and examples. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#verification) Verification --------------------------------------------------------------------------------------------- * Watch gateway logs for reduced `cron.add` INVALID\_REQUEST errors. * Confirm Control UI cron status shows job count after refresh. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#optional-follow-ups) Optional Follow-ups ----------------------------------------------------------------------------------------------------------- * Manual Control UI smoke: add a cron job per provider + verify status job count. [โ€‹](https://docs.clawd.bot/experiments/plans/cron-add-hardening#open-questions) Open Questions ------------------------------------------------------------------------------------------------- * Should `cron.add` accept explicit `state` from clients (currently disallowed by schema)? * Should we allow `webchat` as an explicit delivery provider (currently filtered in delivery resolution)? [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/experiments/plans/cron-add-hardening.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/experiments/plans/cron-add-hardening) โŒ˜I --- # Tlon - Clawdbot [Skip to main content](https://docs.clawd.bot/channels/tlon#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Tlon (plugin)](https://docs.clawd.bot/channels/tlon#tlon-plugin) * [Plugin required](https://docs.clawd.bot/channels/tlon#plugin-required) * [Setup](https://docs.clawd.bot/channels/tlon#setup) * [Group channels](https://docs.clawd.bot/channels/tlon#group-channels) * [Access control](https://docs.clawd.bot/channels/tlon#access-control) * [Delivery targets (CLI/cron)](https://docs.clawd.bot/channels/tlon#delivery-targets-cli%2Fcron) * [Notes](https://docs.clawd.bot/channels/tlon#notes) [โ€‹](https://docs.clawd.bot/channels/tlon#tlon-plugin) Tlon (plugin) ====================================================================== Tlon is a decentralized messenger built on Urbit. Clawdbot connects to your Urbit ship and can respond to DMs and group chat messages. Group replies require an @ mention by default and can be further restricted via allowlists. Status: supported via plugin. DMs, group mentions, thread replies, and text-only media fallback (URL appended to caption). Reactions, polls, and native media uploads are not supported. [โ€‹](https://docs.clawd.bot/channels/tlon#plugin-required) Plugin required ---------------------------------------------------------------------------- Tlon ships as a plugin and is not bundled with the core install. Install via CLI (npm registry): Copy clawdbot plugins install @clawdbot/tlon Local checkout (when running from a git repo): Copy clawdbot plugins install ./extensions/tlon Details: [Plugins](https://docs.clawd.bot/plugin) [โ€‹](https://docs.clawd.bot/channels/tlon#setup) Setup -------------------------------------------------------- 1. Install the Tlon plugin. 2. Gather your ship URL and login code. 3. Configure `channels.tlon`. 4. Restart the gateway. 5. DM the bot or mention it in a group channel. Minimal config (single account): Copy { channels: { tlon: { enabled: true, ship: "~sampel-palnet", url: "https://your-ship-host", code: "lidlut-tabwed-pillex-ridrup" } } } [โ€‹](https://docs.clawd.bot/channels/tlon#group-channels) Group channels -------------------------------------------------------------------------- Auto-discovery is enabled by default. You can also pin channels manually: Copy { channels: { tlon: { groupChannels: [\ "chat/~host-ship/general",\ "chat/~host-ship/support"\ ] } } } Disable auto-discovery: Copy { channels: { tlon: { autoDiscoverChannels: false } } } [โ€‹](https://docs.clawd.bot/channels/tlon#access-control) Access control -------------------------------------------------------------------------- DM allowlist (empty = allow all): Copy { channels: { tlon: { dmAllowlist: ["~zod", "~nec"] } } } Group authorization (restricted by default): Copy { channels: { tlon: { defaultAuthorizedShips: ["~zod"], authorization: { channelRules: { "chat/~host-ship/general": { mode: "restricted", allowedShips: ["~zod", "~nec"] }, "chat/~host-ship/announcements": { mode: "open" } } } } } } [โ€‹](https://docs.clawd.bot/channels/tlon#delivery-targets-cli/cron) Delivery targets (CLI/cron) -------------------------------------------------------------------------------------------------- Use these with `clawdbot message send` or cron delivery: * DM: `~sampel-palnet` or `dm/~sampel-palnet` * Group: `chat/~host-ship/channel` or `group:~host-ship/channel` [โ€‹](https://docs.clawd.bot/channels/tlon#notes) Notes -------------------------------------------------------- * Group replies require a mention (e.g. `~your-bot-ship`) to respond. * Thread replies: if the inbound message is in a thread, Clawdbot replies in-thread. * Media: `sendMedia` falls back to text + URL (no native upload). [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/channels/tlon.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/channels/tlon) โŒ˜I --- # Webhooks - Clawdbot [Skip to main content](https://docs.clawd.bot/cli/webhooks#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [clawdbot webhooks](https://docs.clawd.bot/cli/webhooks#clawdbot-webhooks) * [Gmail](https://docs.clawd.bot/cli/webhooks#gmail) [โ€‹](https://docs.clawd.bot/cli/webhooks#clawdbot-webhooks) `clawdbot webhooks` ================================================================================= Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers). Related: * Webhooks: [Webhook](https://docs.clawd.bot/automation/webhook) * Gmail Pub/Sub: [Gmail Pub/Sub](https://docs.clawd.bot/automation/gmail-pubsub) [โ€‹](https://docs.clawd.bot/cli/webhooks#gmail) Gmail ------------------------------------------------------- Copy clawdbot webhooks gmail setup --account [emailย protected] clawdbot webhooks gmail run See [Gmail Pub/Sub documentation](https://docs.clawd.bot/automation/gmail-pubsub) for details. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/cli/webhooks.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/webhooks) โŒ˜I --- # Brave search - Clawdbot [Skip to main content](https://docs.clawd.bot/brave-search#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Brave Search API](https://docs.clawd.bot/brave-search#brave-search-api) * [Get an API key](https://docs.clawd.bot/brave-search#get-an-api-key) * [Config example](https://docs.clawd.bot/brave-search#config-example) * [Notes](https://docs.clawd.bot/brave-search#notes) [โ€‹](https://docs.clawd.bot/brave-search#brave-search-api) Brave Search API ============================================================================= Clawdbot uses Brave Search as the default provider for `web_search`. [โ€‹](https://docs.clawd.bot/brave-search#get-an-api-key) Get an API key ------------------------------------------------------------------------- 1. Create a Brave Search API account at [https://brave.com/search/api/](https://brave.com/search/api/) 2. In the dashboard, choose the **Data for Search** plan and generate an API key. 3. Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment. [โ€‹](https://docs.clawd.bot/brave-search#config-example) Config example ------------------------------------------------------------------------- Copy { tools: { web: { search: { provider: "brave", apiKey: "BRAVE_API_KEY_HERE", maxResults: 5, timeoutSeconds: 30 } } } } [โ€‹](https://docs.clawd.bot/brave-search#notes) Notes ------------------------------------------------------- * The Data for AI plan is **not** compatible with `web_search`. * Brave provides a free tier plus paid plans; check the Brave API portal for current limits. See [Web tools](https://docs.clawd.bot/tools/web) for the full web\_search configuration. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/brave-search.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/brave-search) โŒ˜I --- # Perplexity - Clawdbot [Skip to main content](https://docs.clawd.bot/perplexity#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Perplexity Sonar](https://docs.clawd.bot/perplexity#perplexity-sonar) * [API options](https://docs.clawd.bot/perplexity#api-options) * [Perplexity (direct)](https://docs.clawd.bot/perplexity#perplexity-direct) * [OpenRouter (alternative)](https://docs.clawd.bot/perplexity#openrouter-alternative) * [Config example](https://docs.clawd.bot/perplexity#config-example) * [Switching from Brave](https://docs.clawd.bot/perplexity#switching-from-brave) * [Models](https://docs.clawd.bot/perplexity#models) [โ€‹](https://docs.clawd.bot/perplexity#perplexity-sonar) Perplexity Sonar =========================================================================== Clawdbot can use Perplexity Sonar for the `web_search` tool. You can connect through Perplexityโ€™s direct API or via OpenRouter. [โ€‹](https://docs.clawd.bot/perplexity#api-options) API options ----------------------------------------------------------------- ### [โ€‹](https://docs.clawd.bot/perplexity#perplexity-direct) Perplexity (direct) * Base URL: [https://api.perplexity.ai](https://api.perplexity.ai/) * Environment variable: `PERPLEXITY_API_KEY` ### [โ€‹](https://docs.clawd.bot/perplexity#openrouter-alternative) OpenRouter (alternative) * Base URL: [https://openrouter.ai/api/v1](https://openrouter.ai/api/v1) * Environment variable: `OPENROUTER_API_KEY` * Supports prepaid/crypto credits. [โ€‹](https://docs.clawd.bot/perplexity#config-example) Config example ----------------------------------------------------------------------- Copy { tools: { web: { search: { provider: "perplexity", perplexity: { apiKey: "pplx-...", baseUrl: "https://api.perplexity.ai", model: "perplexity/sonar-pro" } } } } } [โ€‹](https://docs.clawd.bot/perplexity#switching-from-brave) Switching from Brave ----------------------------------------------------------------------------------- Copy { tools: { web: { search: { provider: "perplexity", perplexity: { apiKey: "pplx-...", baseUrl: "https://api.perplexity.ai" } } } } } If both `PERPLEXITY_API_KEY` and `OPENROUTER_API_KEY` are set, set `tools.web.search.perplexity.baseUrl` (or `tools.web.search.perplexity.apiKey`) to disambiguate. If no base URL is set, Clawdbot chooses a default based on the API key source: * `PERPLEXITY_API_KEY` or `pplx-...` โ†’ direct Perplexity (`https://api.perplexity.ai`) * `OPENROUTER_API_KEY` or `sk-or-...` โ†’ OpenRouter (`https://openrouter.ai/api/v1`) * Unknown key formats โ†’ OpenRouter (safe fallback) [โ€‹](https://docs.clawd.bot/perplexity#models) Models ------------------------------------------------------- * `perplexity/sonar` โ€” fast Q&A with web search * `perplexity/sonar-pro` (default) โ€” multi-step reasoning + web search * `perplexity/sonar-reasoning-pro` โ€” deep research See [Web tools](https://docs.clawd.bot/tools/web) for the full web\_search configuration. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/perplexity.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/perplexity) โŒ˜I --- # Node - Clawdbot [Skip to main content](https://docs.clawd.bot/cli/node#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [clawdbot node](https://docs.clawd.bot/cli/node#clawdbot-node) * [Why use a node host?](https://docs.clawd.bot/cli/node#why-use-a-node-host) * [Browser proxy (zero-config)](https://docs.clawd.bot/cli/node#browser-proxy-zero-config) * [Run (foreground)](https://docs.clawd.bot/cli/node#run-foreground) * [Service (background)](https://docs.clawd.bot/cli/node#service-background) * [Pairing](https://docs.clawd.bot/cli/node#pairing) * [Exec approvals](https://docs.clawd.bot/cli/node#exec-approvals) [โ€‹](https://docs.clawd.bot/cli/node#clawdbot-node) `clawdbot node` ===================================================================== Run a **headless node host** that connects to the Gateway WebSocket and exposes `system.run` / `system.which` on this machine. [โ€‹](https://docs.clawd.bot/cli/node#why-use-a-node-host) Why use a node host? -------------------------------------------------------------------------------- Use a node host when you want agents to **run commands on other machines** in your network without installing a full macOS companion app there. Common use cases: * Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS). * Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts. * Provide a lightweight, headless execution target for automation or CI nodes. Execution is still guarded by **exec approvals** and perโ€‘agent allowlists on the node host, so you can keep command access scoped and explicit. [โ€‹](https://docs.clawd.bot/cli/node#browser-proxy-zero-config) Browser proxy (zero-config) --------------------------------------------------------------------------------------------- Node hosts automatically advertise a browser proxy if `browser.enabled` is not disabled on the node. This lets the agent use browser automation on that node without extra configuration. Disable it on the node if needed: Copy { nodeHost: { browserProxy: { enabled: false } } } [โ€‹](https://docs.clawd.bot/cli/node#run-foreground) Run (foreground) ----------------------------------------------------------------------- Copy clawdbot node run --host --port 18789 Options: * `--host `: Gateway WebSocket host (default: `127.0.0.1`) * `--port `: Gateway WebSocket port (default: `18789`) * `--tls`: Use TLS for the gateway connection * `--tls-fingerprint `: Expected TLS certificate fingerprint (sha256) * `--node-id `: Override node id (clears pairing token) * `--display-name `: Override the node display name [โ€‹](https://docs.clawd.bot/cli/node#service-background) Service (background) ------------------------------------------------------------------------------- Install a headless node host as a user service. Copy clawdbot node install --host --port 18789 Options: * `--host `: Gateway WebSocket host (default: `127.0.0.1`) * `--port `: Gateway WebSocket port (default: `18789`) * `--tls`: Use TLS for the gateway connection * `--tls-fingerprint `: Expected TLS certificate fingerprint (sha256) * `--node-id `: Override node id (clears pairing token) * `--display-name `: Override the node display name * `--runtime `: Service runtime (`node` or `bun`) * `--force`: Reinstall/overwrite if already installed Manage the service: Copy clawdbot node status clawdbot node stop clawdbot node restart clawdbot node uninstall Use `clawdbot node run` for a foreground node host (no service). Service commands accept `--json` for machine-readable output. [โ€‹](https://docs.clawd.bot/cli/node#pairing) Pairing ------------------------------------------------------- The first connection creates a pending node pair request on the Gateway. Approve it via: Copy clawdbot nodes pending clawdbot nodes approve The node host stores its node id, token, display name, and gateway connection info in `~/.clawdbot/node.json`. [โ€‹](https://docs.clawd.bot/cli/node#exec-approvals) Exec approvals --------------------------------------------------------------------- `system.run` is gated by local exec approvals: * `~/.clawdbot/exec-approvals.json` * [Exec approvals](https://docs.clawd.bot/tools/exec-approvals) * `clawdbot approvals --node ` (edit from the Gateway) [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/cli/node.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/node) โŒ˜I --- # Devices - Clawdbot [Skip to main content](https://docs.clawd.bot/cli/devices#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [clawdbot devices](https://docs.clawd.bot/cli/devices#clawdbot-devices) * [Commands](https://docs.clawd.bot/cli/devices#commands) * [clawdbot devices list](https://docs.clawd.bot/cli/devices#clawdbot-devices-list) * [clawdbot devices approve ](https://docs.clawd.bot/cli/devices#clawdbot-devices-approve-%3Crequestid%3E) * [clawdbot devices reject ](https://docs.clawd.bot/cli/devices#clawdbot-devices-reject-%3Crequestid%3E) * [clawdbot devices rotate --device --role \[--scope \]](https://docs.clawd.bot/cli/devices#clawdbot-devices-rotate-device-%3Cid%3E-role-%3Crole%3E-%5B-scope-%3Cscope-%3E%5D) * [clawdbot devices revoke --device --role ](https://docs.clawd.bot/cli/devices#clawdbot-devices-revoke-device-%3Cid%3E-role-%3Crole%3E) * [Common options](https://docs.clawd.bot/cli/devices#common-options) * [Notes](https://docs.clawd.bot/cli/devices#notes) [โ€‹](https://docs.clawd.bot/cli/devices#clawdbot-devices) `clawdbot devices` ============================================================================== Manage device pairing requests and device-scoped tokens. [โ€‹](https://docs.clawd.bot/cli/devices#commands) Commands ------------------------------------------------------------ ### [โ€‹](https://docs.clawd.bot/cli/devices#clawdbot-devices-list) `clawdbot devices list` List pending pairing requests and paired devices. Copy clawdbot devices list clawdbot devices list --json ### [โ€‹](https://docs.clawd.bot/cli/devices#clawdbot-devices-approve-%3Crequestid%3E) `clawdbot devices approve ` Approve a pending device pairing request. Copy clawdbot devices approve ### [โ€‹](https://docs.clawd.bot/cli/devices#clawdbot-devices-reject-%3Crequestid%3E) `clawdbot devices reject ` Reject a pending device pairing request. Copy clawdbot devices reject ### [โ€‹](https://docs.clawd.bot/cli/devices#clawdbot-devices-rotate-device-%3Cid%3E-role-%3Crole%3E-[-scope-%3Cscope-%3E]) `clawdbot devices rotate --device --role [--scope ]` Rotate a device token for a specific role (optionally updating scopes). Copy clawdbot devices rotate --device --role operator --scope operator.read --scope operator.write ### [โ€‹](https://docs.clawd.bot/cli/devices#clawdbot-devices-revoke-device-%3Cid%3E-role-%3Crole%3E) `clawdbot devices revoke --device --role ` Revoke a device token for a specific role. Copy clawdbot devices revoke --device --role node [โ€‹](https://docs.clawd.bot/cli/devices#common-options) Common options ------------------------------------------------------------------------ * `--url `: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured). * `--token `: Gateway token (if required). * `--password `: Gateway password (password auth). * `--timeout `: RPC timeout. * `--json`: JSON output (recommended for scripting). [โ€‹](https://docs.clawd.bot/cli/devices#notes) Notes ------------------------------------------------------ * Token rotation returns a new token (sensitive). Treat it like a secret. * These commands require `operator.pairing` (or `operator.admin`) scope. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/cli/devices.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/devices) โŒ˜I --- # Config - Clawdbot [Skip to main content](https://docs.clawd.bot/cli/config#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [clawdbot config](https://docs.clawd.bot/cli/config#clawdbot-config) * [Examples](https://docs.clawd.bot/cli/config#examples) * [Paths](https://docs.clawd.bot/cli/config#paths) * [Values](https://docs.clawd.bot/cli/config#values) [โ€‹](https://docs.clawd.bot/cli/config#clawdbot-config) `clawdbot config` =========================================================================== Config helpers: get/set/unset values by path. Run without a subcommand to open the configure wizard (same as `clawdbot configure`). [โ€‹](https://docs.clawd.bot/cli/config#examples) Examples ----------------------------------------------------------- Copy clawdbot config get browser.executablePath clawdbot config set browser.executablePath "/usr/bin/google-chrome" clawdbot config set agents.defaults.heartbeat.every "2h" clawdbot config set agents.list[0].tools.exec.node "node-id-or-name" clawdbot config unset tools.web.search.apiKey [โ€‹](https://docs.clawd.bot/cli/config#paths) Paths ----------------------------------------------------- Paths use dot or bracket notation: Copy clawdbot config get agents.defaults.workspace clawdbot config get agents.list[0].id Use the agent list index to target a specific agent: Copy clawdbot config get agents.list clawdbot config set agents.list[1].tools.exec.node "node-id-or-name" [โ€‹](https://docs.clawd.bot/cli/config#values) Values ------------------------------------------------------- Values are parsed as JSON5 when possible; otherwise they are treated as strings. Use `--json` to require JSON5 parsing. Copy clawdbot config set agents.defaults.heartbeat.every "0m" clawdbot config set gateway.port 19001 --json clawdbot config set channels.whatsapp.groups '["*"]' --json Restart the gateway after edits. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/cli/config.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/cli/config) โŒ˜I --- # Firecrawl - Clawdbot [Skip to main content](https://docs.clawd.bot/tools/firecrawl#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [Firecrawl](https://docs.clawd.bot/tools/firecrawl#firecrawl) * [Get an API key](https://docs.clawd.bot/tools/firecrawl#get-an-api-key) * [Configure Firecrawl](https://docs.clawd.bot/tools/firecrawl#configure-firecrawl) * [Stealth / bot circumvention](https://docs.clawd.bot/tools/firecrawl#stealth-%2F-bot-circumvention) * [How web\_fetch uses Firecrawl](https://docs.clawd.bot/tools/firecrawl#how-web_fetch-uses-firecrawl) [โ€‹](https://docs.clawd.bot/tools/firecrawl#firecrawl) Firecrawl ================================================================== Clawdbot can use **Firecrawl** as a fallback extractor for `web_fetch`. It is a hosted content extraction service that supports bot circumvention and caching, which helps with JS-heavy sites or pages that block plain HTTP fetches. [โ€‹](https://docs.clawd.bot/tools/firecrawl#get-an-api-key) Get an API key ---------------------------------------------------------------------------- 1. Create a Firecrawl account and generate an API key. 2. Store it in config or set `FIRECRAWL_API_KEY` in the gateway environment. [โ€‹](https://docs.clawd.bot/tools/firecrawl#configure-firecrawl) Configure Firecrawl -------------------------------------------------------------------------------------- Copy { tools: { web: { fetch: { firecrawl: { apiKey: "FIRECRAWL_API_KEY_HERE", baseUrl: "https://api.firecrawl.dev", onlyMainContent: true, maxAgeMs: 172800000, timeoutSeconds: 60 } } } } } Notes: * `firecrawl.enabled` defaults to true when an API key is present. * `maxAgeMs` controls how old cached results can be (ms). Default is 2 days. [โ€‹](https://docs.clawd.bot/tools/firecrawl#stealth-/-bot-circumvention) Stealth / bot circumvention ------------------------------------------------------------------------------------------------------ Firecrawl exposes a **proxy mode** parameter for bot circumvention (`basic`, `stealth`, or `auto`). Clawdbot always uses `proxy: "auto"` plus `storeInCache: true` for Firecrawl requests. If proxy is omitted, Firecrawl defaults to `auto`. `auto` retries with stealth proxies if a basic attempt fails, which may use more credits than basic-only scraping. [โ€‹](https://docs.clawd.bot/tools/firecrawl#how-web_fetch-uses-firecrawl) How `web_fetch` uses Firecrawl ---------------------------------------------------------------------------------------------------------- `web_fetch` extraction order: 1. Readability (local) 2. Firecrawl (if configured) 3. Basic HTML cleanup (last fallback) See [Web tools](https://docs.clawd.bot/tools/web) for the full web tool setup. [Suggest edits](https://github.com/clawdbot/clawdbot/edit/main/docs/tools/firecrawl.mdx) [Raise issue](https://github.com/clawdbot/clawdbot/issues/new?title=Issue%20on%20docs&body=Path:%20/tools/firecrawl) โŒ˜I --- # Acp - Clawdbot [Skip to main content](https://docs.clawd.bot/cli/acp#content-area) [Clawdbot home page![light logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)![dark logo](https://mintcdn.com/clawdhub/4rYvG-uuZrMK_URE/assets/pixel-lobster.svg?fit=max&auto=format&n=4rYvG-uuZrMK_URE&q=85&s=da2032e9eac3b5d9bfe7eb96ca6a8a26)](https://docs.clawd.bot/) Search... โŒ˜K Search... Navigation On this page * [acp](https://docs.clawd.bot/cli/acp#acp) * [Usage](https://docs.clawd.bot/cli/acp#usage) * [ACP client (debug)](https://docs.clawd.bot/cli/acp#acp-client-debug) * [How to use this](https://docs.clawd.bot/cli/acp#how-to-use-this) * [Selecting agents](https://docs.clawd.bot/cli/acp#selecting-agents) * [Zed editor setup](https://docs.clawd.bot/cli/acp#zed-editor-setup) * [Session mapping](https://docs.clawd.bot/cli/acp#session-mapping) * [Options](https://docs.clawd.bot/cli/acp#options) * [acp client options](https://docs.clawd.bot/cli/acp#acp-client-options) [โ€‹](https://docs.clawd.bot/cli/acp#acp) acp ============================================== Run the ACP (Agent Client Protocol) bridge that talks to a Clawdbot Gateway. This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket. It keeps ACP sessions mapped to Gateway session keys. [โ€‹](https://docs.clawd.bot/cli/acp#usage) Usage -------------------------------------------------- Copy clawdbot acp # Remote Gateway clawdbot acp --url wss://gateway-host:18789 --token # Attach to an existing session key clawdbot acp --session agent:main:main # Attach by label (must already exist) clawdbot acp --session-label "support inbox" # Reset the session key before the first prompt clawdbot acp --session agent:main:main --reset-session [โ€‹](https://docs.clawd.bot/cli/acp#acp-client-debug) ACP client (debug) -------------------------------------------------------------------------- Use the built-in ACP client to sanity-check the bridge without an IDE. It spawns the ACP bridge and lets you type prompts interactively. Copy clawdbot acp client # Point the spawned bridge at a remote Gateway clawdbot acp client --server-args --url wss://gateway-host:18789 --token # Override the server command (default: clawdbot) clawdbot acp client --server "node" --server-args dist/entry.js acp --url ws://127.0.0.1:19001 [โ€‹](https://docs.clawd.bot/cli/acp#how-to-use-this) How to use this ---------------------------------------------------------------------- Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive a Clawdbot Gateway session. 1. Ensure the Gateway is running (local or remote). 2. Configure the Gateway target (config or flags). 3. Point your IDE to run `clawdbot acp` over stdio. Example config (persisted): Copy clawdbot config set gateway.remote.url wss://gateway-host:18789 clawdbot config set gateway.remote.token Example direct run (no config write): Copy clawdbot acp --url wss://gateway-host:18789 --token [โ€‹](https://docs.clawd.bot/cli/acp#selecting-agents) Selecting agents ------------------------------------------------------------------------ ACP does not pick agents directly. It routes by the Gateway session key. Use agent-scoped session keys to target a specific agent: Copy clawdbot acp --session agent:main:main clawdbot acp --session agent:design:main clawdbot acp --session agent:qa:bug-123 Each ACP session maps to a single Gateway session key. One agent can have many sessions; ACP defaults to an isolated `acp:` session unless you override the key or label. [โ€‹](https://docs.clawd.bot/cli/acp#zed-editor-setup) Zed editor setup ------------------------------------------------------------------------ Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zedโ€™s Settings UI): Copy { "agent_servers": { "Clawdbot ACP": { "type": "custom", "command": "clawdbot", "args": ["acp"], "env": {} } } } To target a specific Gateway or agent: Copy { "agent_servers": { "Clawdbot ACP": { "type": "custom", "command": "clawdbot", "args": [\ "acp",\ "--url", "wss://gateway-host:18789",\ "--token", "",\ "--session", "agent:design:main"\ ], "env": {} } } } In Zed, open the Agent panel and select โ€œClawdbot ACPโ€ to start a thread. [โ€‹](https://docs.clawd.bot/cli/acp#session-mapping) Session mapping ---------------------------------------------------------------------- By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix. To reuse a known session, pass a session key or label: * `--session `: use a specific Gateway session key. * `--session-label