# Table of Contents - [Getting started - Moltbot](#getting-started-moltbot) - [Index - Moltbot](#index-moltbot) - [Bluebubbles - Moltbot](#bluebubbles-moltbot) - [Nextcloud talk - Moltbot](#nextcloud-talk-moltbot) - [Exec approvals - Moltbot](#exec-approvals-moltbot) - [Date time - Moltbot](#date-time-moltbot) - [Nostr - Moltbot](#nostr-moltbot) - [Index - Moltbot](#index-moltbot) - [Qwen - Moltbot](#qwen-moltbot) - [Migrating - Moltbot](#migrating-moltbot) - [Tlon - Moltbot](#tlon-moltbot) - [Claude max api proxy - Moltbot](#claude-max-api-proxy-moltbot) - [Vps - Moltbot](#vps-moltbot) - [Openresponses http api - Moltbot](#openresponses-http-api-moltbot) - [Tts - Moltbot](#tts-moltbot) - [Perplexity - Moltbot](#perplexity-moltbot) - [Group policy hardening - Moltbot](#group-policy-hardening-moltbot) - [Firecrawl - Moltbot](#firecrawl-moltbot) - [Webhooks - Moltbot](#webhooks-moltbot) - [Model config - Moltbot](#model-config-moltbot) - [Onboarding config protocol - Moltbot](#onboarding-config-protocol-moltbot) - [Cron add hardening - Moltbot](#cron-add-hardening-moltbot) - [Memory - Moltbot](#memory-moltbot) - [Node - Moltbot](#node-moltbot) - [Transcript hygiene - Moltbot](#transcript-hygiene-moltbot) - [Network - Moltbot](#network-moltbot) - [Brave search - Moltbot](#brave-search-moltbot) - [Devices - Moltbot](#devices-moltbot) - [Agent tools - Moltbot](#agent-tools-moltbot) - [Deepgram - Moltbot](#deepgram-moltbot) - [Manifest - Moltbot](#manifest-moltbot) - [Prose - Moltbot](#prose-moltbot) - [Config - Moltbot](#config-moltbot) - [Ollama - Moltbot](#ollama-moltbot) - [Acp - Moltbot](#acp-moltbot) - [Venice - Moltbot](#venice-moltbot) - [Logging - Moltbot](#logging-moltbot) - [Twitch - Moltbot](#twitch-moltbot) - [Oracle - Moltbot](#oracle-moltbot) - [Flags - Moltbot](#flags-moltbot) - [Digitalocean - Moltbot](#digitalocean-moltbot) --- # Getting started - Moltbot [Skip to main content](https://docs.molt.bot/start/getting-started#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Getting Started](https://docs.molt.bot/start/getting-started#getting-started) * [0) Prereqs](https://docs.molt.bot/start/getting-started#0-prereqs) * [1) Install the CLI (recommended)](https://docs.molt.bot/start/getting-started#1-install-the-cli-recommended) * [2) Run the onboarding wizard (and install the service)](https://docs.molt.bot/start/getting-started#2-run-the-onboarding-wizard-and-install-the-service) * [Auth: where it lives (important)](https://docs.molt.bot/start/getting-started#auth%3A-where-it-lives-important) * [3) Start the Gateway](https://docs.molt.bot/start/getting-started#3-start-the-gateway) * [3.5) Quick verify (2 min)](https://docs.molt.bot/start/getting-started#3-5-quick-verify-2-min) * [4) Pair + connect your first chat surface](https://docs.molt.bot/start/getting-started#4-pair-%2B-connect-your-first-chat-surface) * [WhatsApp (QR login)](https://docs.molt.bot/start/getting-started#whatsapp-qr-login) * [Telegram / Discord / others](https://docs.molt.bot/start/getting-started#telegram-%2F-discord-%2F-others) * [5) DM safety (pairing approvals)](https://docs.molt.bot/start/getting-started#5-dm-safety-pairing-approvals) * [From source (development)](https://docs.molt.bot/start/getting-started#from-source-development) * [7) Verify end-to-end](https://docs.molt.bot/start/getting-started#7-verify-end-to-end) * [Next steps (optional, but great)](https://docs.molt.bot/start/getting-started#next-steps-optional%2C-but-great) [​](https://docs.molt.bot/start/getting-started#getting-started) Getting Started =================================================================================== Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible. Fastest chat: open the Control UI (no channel setup needed). Run `moltbot dashboard` and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host. Docs: [Dashboard](https://docs.molt.bot/web/dashboard) and [Control UI](https://docs.molt.bot/web/control-ui) . Recommended path: use the **CLI onboarding wizard** (`moltbot onboard`). It sets up: * model/auth (OAuth recommended) * gateway settings * channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/…) * pairing defaults (secure DMs) * workspace bootstrap + skills * optional background service If you want the deeper reference pages, jump to: [Wizard](https://docs.molt.bot/start/wizard) , [Setup](https://docs.molt.bot/start/setup) , [Pairing](https://docs.molt.bot/start/pairing) , [Security](https://docs.molt.bot/gateway/security) . Sandboxing note: `agents.defaults.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`), so group/channel sessions are sandboxed. If you want the main agent to always run on host, set an explicit per-agent override: Copy { "routing": { "agents": { "main": { "workspace": "~/clawd", "sandbox": { "mode": "off" } } } } } [​](https://docs.molt.bot/start/getting-started#0-prereqs) 0) Prereqs ------------------------------------------------------------------------ * Node `>=22` * `pnpm` (optional; recommended if you build from source) * **Recommended:** Brave Search API key for web search. Easiest path: `moltbot configure --section web` (stores `tools.web.search.apiKey`). See [Web tools](https://docs.molt.bot/tools/web) . macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough. Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](https://docs.molt.bot/platforms/windows) . [​](https://docs.molt.bot/start/getting-started#1-install-the-cli-recommended) 1) Install the CLI (recommended) ------------------------------------------------------------------------------------------------------------------ Copy curl -fsSL https://molt.bot/install.sh | bash Installer options (install method, non-interactive, from GitHub): [Install](https://docs.molt.bot/install) . Windows (PowerShell): Copy iwr -useb https://molt.bot/install.ps1 | iex Alternative (global install): Copy npm install -g moltbot@latest Copy pnpm add -g moltbot@latest [​](https://docs.molt.bot/start/getting-started#2-run-the-onboarding-wizard-and-install-the-service) 2) Run the onboarding wizard (and install the service) -------------------------------------------------------------------------------------------------------------------------------------------------------------- Copy moltbot onboard --install-daemon What you’ll choose: * **Local vs Remote** gateway * **Auth**: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; `claude setup-token` is also supported. * **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc. * **Daemon**: background install (launchd/systemd; WSL2 uses systemd) * **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**. * **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`. Wizard doc: [Wizard](https://docs.molt.bot/start/wizard) ### [​](https://docs.molt.bot/start/getting-started#auth:-where-it-lives-important) Auth: where it lives (important) * **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials. * OAuth credentials (legacy import): `~/.clawdbot/credentials/oauth.json` * Auth profiles (OAuth + API keys): `~/.clawdbot/agents//agent/auth-profiles.json` Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host. [​](https://docs.molt.bot/start/getting-started#3-start-the-gateway) 3) Start the Gateway -------------------------------------------------------------------------------------------- If you installed the service during onboarding, the Gateway should already be running: Copy moltbot gateway status Manual run (foreground): Copy moltbot gateway --port 18789 --verbose Dashboard (local loopback): `http://127.0.0.1:18789/` If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`). ⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these channels. If you use WhatsApp or Telegram, run the Gateway with **Node**. [​](https://docs.molt.bot/start/getting-started#3-5-quick-verify-2-min) 3.5) Quick verify (2 min) ---------------------------------------------------------------------------------------------------- Copy moltbot status moltbot health moltbot security audit --deep [​](https://docs.molt.bot/start/getting-started#4-pair-+-connect-your-first-chat-surface) 4) Pair + connect your first chat surface -------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/start/getting-started#whatsapp-qr-login) WhatsApp (QR login) Copy moltbot channels login Scan via WhatsApp → Settings → Linked Devices. WhatsApp doc: [WhatsApp](https://docs.molt.bot/channels/whatsapp) ### [​](https://docs.molt.bot/start/getting-started#telegram-/-discord-/-others) Telegram / Discord / others The wizard can write tokens/config for you. If you prefer manual config, start with: * Telegram: [Telegram](https://docs.molt.bot/channels/telegram) * Discord: [Discord](https://docs.molt.bot/channels/discord) * Mattermost (plugin): [Mattermost](https://docs.molt.bot/channels/mattermost) **Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond. [​](https://docs.molt.bot/start/getting-started#5-dm-safety-pairing-approvals) 5) DM safety (pairing approvals) ------------------------------------------------------------------------------------------------------------------ Default posture: unknown DMs get a short code and messages are not processed until approved. If your first DM gets no reply, approve the pairing: Copy moltbot pairing list whatsapp moltbot pairing approve whatsapp Pairing doc: [Pairing](https://docs.molt.bot/start/pairing) [​](https://docs.molt.bot/start/getting-started#from-source-development) From source (development) ----------------------------------------------------------------------------------------------------- If you’re hacking on Moltbot itself, run from source: Copy git clone https://github.com/moltbot/moltbot.git cd moltbot pnpm install pnpm ui:build # auto-installs UI deps on first run pnpm build moltbot onboard --install-daemon If you don’t have a global install yet, run the onboarding step via `pnpm moltbot ...` from the repo. `pnpm build` also bundles A2UI assets; if you need to run just that step, use `pnpm canvas:a2ui:bundle`. Gateway (from this repo): Copy node moltbot.mjs gateway --port 18789 --verbose [​](https://docs.molt.bot/start/getting-started#7-verify-end-to-end) 7) Verify end-to-end -------------------------------------------------------------------------------------------- In a new terminal, send a test message: Copy moltbot message send --target +15555550123 --message "Hello from Moltbot" If `moltbot health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it. Tip: `moltbot status --all` is the best pasteable, read-only debug report. Health probes: `moltbot health` (or `moltbot status --deep`) asks the running gateway for a health snapshot. [​](https://docs.molt.bot/start/getting-started#next-steps-optional,-but-great) Next steps (optional, but great) ------------------------------------------------------------------------------------------------------------------- * macOS menu bar app + voice wake: [macOS app](https://docs.molt.bot/platforms/macos) * iOS/Android nodes (Canvas/camera/voice): [Nodes](https://docs.molt.bot/nodes) * Remote access (SSH tunnel / Tailscale Serve): [Remote access](https://docs.molt.bot/gateway/remote) and [Tailscale](https://docs.molt.bot/gateway/tailscale) * Always-on / VPN setups: [Remote access](https://docs.molt.bot/gateway/remote) , [exe.dev](https://docs.molt.bot/platforms/exe-dev) , [Hetzner](https://docs.molt.bot/platforms/hetzner) , [macOS remote](https://docs.molt.bot/platforms/mac/remote) [](https://docs.molt.bot/) [Wizard](https://docs.molt.bot/start/wizard) ⌘I --- # Index - Moltbot [Skip to main content](https://docs.molt.bot/platforms#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Platforms](https://docs.molt.bot/platforms#platforms) * [Choose your OS](https://docs.molt.bot/platforms#choose-your-os) * [VPS & hosting](https://docs.molt.bot/platforms#vps-%26-hosting) * [Common links](https://docs.molt.bot/platforms#common-links) * [Gateway service install (CLI)](https://docs.molt.bot/platforms#gateway-service-install-cli) [​](https://docs.molt.bot/platforms#platforms) Platforms =========================================================== Moltbot 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.molt.bot/platforms#choose-your-os) Choose your OS --------------------------------------------------------------------- * macOS: [macOS](https://docs.molt.bot/platforms/macos) * iOS: [iOS](https://docs.molt.bot/platforms/ios) * Android: [Android](https://docs.molt.bot/platforms/android) * Windows: [Windows](https://docs.molt.bot/platforms/windows) * Linux: [Linux](https://docs.molt.bot/platforms/linux) [​](https://docs.molt.bot/platforms#vps-&-hosting) VPS & hosting ------------------------------------------------------------------- * VPS hub: [VPS hosting](https://docs.molt.bot/vps) * Fly.io: [Fly.io](https://docs.molt.bot/platforms/fly) * Hetzner (Docker): [Hetzner](https://docs.molt.bot/platforms/hetzner) * GCP (Compute Engine): [GCP](https://docs.molt.bot/platforms/gcp) * exe.dev (VM + HTTPS proxy): [exe.dev](https://docs.molt.bot/platforms/exe-dev) [​](https://docs.molt.bot/platforms#common-links) Common links ----------------------------------------------------------------- * Install guide: [Getting Started](https://docs.molt.bot/start/getting-started) * Gateway runbook: [Gateway](https://docs.molt.bot/gateway) * Gateway configuration: [Configuration](https://docs.molt.bot/gateway/configuration) * Service status: `moltbot gateway status` [​](https://docs.molt.bot/platforms#gateway-service-install-cli) Gateway service install (CLI) ------------------------------------------------------------------------------------------------- Use one of these (all supported): * Wizard (recommended): `moltbot onboard --install-daemon` * Direct: `moltbot gateway install` * Configure flow: `moltbot configure` → select **Gateway service** * Repair/migrate: `moltbot doctor` (offers to install or fix the service) The service target depends on OS: * macOS: LaunchAgent (`bot.molt.gateway` or `bot.molt.`; legacy `com.clawdbot.*`) * Linux/WSL2: systemd user service (`moltbot-gateway[-].service`) [Talk](https://docs.molt.bot/nodes/talk) [Macos](https://docs.molt.bot/platforms/macos) ⌘I --- # Bluebubbles - Moltbot [Skip to main content](https://docs.molt.bot/channels/bluebubbles#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [BlueBubbles (macOS REST)](https://docs.molt.bot/channels/bluebubbles#bluebubbles-macos-rest) * [Overview](https://docs.molt.bot/channels/bluebubbles#overview) * [Quick start](https://docs.molt.bot/channels/bluebubbles#quick-start) * [Onboarding](https://docs.molt.bot/channels/bluebubbles#onboarding) * [Access control (DMs + groups)](https://docs.molt.bot/channels/bluebubbles#access-control-dms-%2B-groups) * [Mention gating (groups)](https://docs.molt.bot/channels/bluebubbles#mention-gating-groups) * [Command gating](https://docs.molt.bot/channels/bluebubbles#command-gating) * [Typing + read receipts](https://docs.molt.bot/channels/bluebubbles#typing-%2B-read-receipts) * [Advanced actions](https://docs.molt.bot/channels/bluebubbles#advanced-actions) * [Message IDs (short vs full)](https://docs.molt.bot/channels/bluebubbles#message-ids-short-vs-full) * [Block streaming](https://docs.molt.bot/channels/bluebubbles#block-streaming) * [Media + limits](https://docs.molt.bot/channels/bluebubbles#media-%2B-limits) * [Configuration reference](https://docs.molt.bot/channels/bluebubbles#configuration-reference) * [Addressing / delivery targets](https://docs.molt.bot/channels/bluebubbles#addressing-%2F-delivery-targets) * [Security](https://docs.molt.bot/channels/bluebubbles#security) * [Troubleshooting](https://docs.molt.bot/channels/bluebubbles#troubleshooting) [​](https://docs.molt.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.molt.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. * Moltbot 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.molt.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 `moltbot 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.molt.bot/channels/bluebubbles#onboarding) Onboarding ------------------------------------------------------------------------ BlueBubbles is available in the interactive setup wizard: Copy moltbot 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 moltbot channels add bluebubbles --http-url http://192.168.1.100:1234 --password [​](https://docs.molt.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: * `moltbot pairing list bluebubbles` * `moltbot pairing approve bluebubbles ` * Pairing is the default token exchange. Details: [Pairing](https://docs.molt.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.molt.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.molt.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.molt.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**: Moltbot 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.molt.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.molt.bot/channels/bluebubbles#message-ids-short-vs-full) Message IDs (short vs full) Moltbot 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.molt.bot/gateway/configuration) for template variables. [​](https://docs.molt.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.molt.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.molt.bot/channels/bluebubbles#configuration-reference) Configuration reference -------------------------------------------------------------------------------------------------- Full configuration: [Configuration](https://docs.molt.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.chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking. * `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.molt.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.molt.bot/cdn-cgi/l/email-protection) ` * If a direct handle does not have an existing DM chat, Moltbot will create one via `POST /api/v1/chat/new`. This requires the BlueBubbles Private API to be enabled. [​](https://docs.molt.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). * Localhost trust means a same-host reverse proxy can unintentionally bypass the password. If you proxy the gateway, require auth at the proxy and configure `gateway.trustedProxies`. See [Gateway security](https://docs.molt.bot/gateway/security#reverse-proxy-configuration) . * Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN. [​](https://docs.molt.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 `moltbot pairing list bluebubbles` and `moltbot 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. * Moltbot 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: `moltbot status --all` or `moltbot status --deep`. For general channel workflow reference, see [Channels](https://docs.molt.bot/channels) and the [Plugins](https://docs.molt.bot/plugins) guide. ⌘I --- # Nextcloud talk - Moltbot [Skip to main content](https://docs.molt.bot/channels/nextcloud-talk#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Nextcloud Talk (plugin)](https://docs.molt.bot/channels/nextcloud-talk#nextcloud-talk-plugin) * [Plugin required](https://docs.molt.bot/channels/nextcloud-talk#plugin-required) * [Quick setup (beginner)](https://docs.molt.bot/channels/nextcloud-talk#quick-setup-beginner) * [Notes](https://docs.molt.bot/channels/nextcloud-talk#notes) * [Access control (DMs)](https://docs.molt.bot/channels/nextcloud-talk#access-control-dms) * [Rooms (groups)](https://docs.molt.bot/channels/nextcloud-talk#rooms-groups) * [Capabilities](https://docs.molt.bot/channels/nextcloud-talk#capabilities) * [Configuration reference (Nextcloud Talk)](https://docs.molt.bot/channels/nextcloud-talk#configuration-reference-nextcloud-talk) [​](https://docs.molt.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.molt.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 moltbot plugins install @moltbot/nextcloud-talk Local checkout (when running from a git repo): Copy moltbot plugins install ./extensions/nextcloud-talk If you choose Nextcloud Talk during configure/onboarding and a git checkout is detected, Moltbot will offer the local install path automatically. Details: [Plugins](https://docs.molt.bot/plugin) [​](https://docs.molt.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 "Moltbot" "" "" --feature reaction 3. Enable the bot in the target room settings. 4. Configure Moltbot: * 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.molt.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.molt.bot/channels/nextcloud-talk#access-control-dms) Access control (DMs) --------------------------------------------------------------------------------------------- * Default: `channels.nextcloud-talk.dmPolicy = "pairing"`. Unknown senders get a pairing code. * Approve via: * `moltbot pairing list nextcloud-talk` * `moltbot pairing approve nextcloud-talk ` * Public DMs: `channels.nextcloud-talk.dmPolicy="open"` plus `channels.nextcloud-talk.allowFrom=["*"]`. [​](https://docs.molt.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.molt.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.molt.bot/channels/nextcloud-talk#configuration-reference-nextcloud-talk) Configuration reference (Nextcloud Talk) ------------------------------------------------------------------------------------------------------------------------------------- Full configuration: [Configuration](https://docs.molt.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.chunkMode`: `length` (default) or `newline` to split on blank lines (paragraph boundaries) before length chunking. * `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). ⌘I --- # Exec approvals - Moltbot [Skip to main content](https://docs.molt.bot/tools/exec-approvals#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Exec approvals](https://docs.molt.bot/tools/exec-approvals#exec-approvals) * [Where it applies](https://docs.molt.bot/tools/exec-approvals#where-it-applies) * [Settings and storage](https://docs.molt.bot/tools/exec-approvals#settings-and-storage) * [Policy knobs](https://docs.molt.bot/tools/exec-approvals#policy-knobs) * [Security (exec.security)](https://docs.molt.bot/tools/exec-approvals#security-exec-security) * [Ask (exec.ask)](https://docs.molt.bot/tools/exec-approvals#ask-exec-ask) * [Ask fallback (askFallback)](https://docs.molt.bot/tools/exec-approvals#ask-fallback-askfallback) * [Allowlist (per agent)](https://docs.molt.bot/tools/exec-approvals#allowlist-per-agent) * [Auto-allow skill CLIs](https://docs.molt.bot/tools/exec-approvals#auto-allow-skill-clis) * [Safe bins (stdin-only)](https://docs.molt.bot/tools/exec-approvals#safe-bins-stdin-only) * [Control UI editing](https://docs.molt.bot/tools/exec-approvals#control-ui-editing) * [Approval flow](https://docs.molt.bot/tools/exec-approvals#approval-flow) * [Approval forwarding to chat channels](https://docs.molt.bot/tools/exec-approvals#approval-forwarding-to-chat-channels) * [macOS IPC flow](https://docs.molt.bot/tools/exec-approvals#macos-ipc-flow) * [System events](https://docs.molt.bot/tools/exec-approvals#system-events) * [Implications](https://docs.molt.bot/tools/exec-approvals#implications) [​](https://docs.molt.bot/tools/exec-approvals#exec-approvals) Exec approvals ================================================================================ Exec approvals are the **companion app / node host guardrail** for letting a sandboxed agent run commands on a real host (`gateway` or `node`). Think of it like a safety interlock: commands are allowed only when policy + allowlist + (optional) user approval all agree. Exec approvals are **in addition** to tool policy and elevated gating (unless elevated is set to `full`, which skips approvals). Effective policy is the **stricter** of `tools.exec.*` and approvals defaults; if an approvals field is omitted, the `tools.exec` value is used. If the companion app UI is **not available**, any request that requires a prompt is resolved by the **ask fallback** (default: deny). [​](https://docs.molt.bot/tools/exec-approvals#where-it-applies) Where it applies ------------------------------------------------------------------------------------ Exec approvals are enforced locally on the execution host: * **gateway host** → `moltbot` process on the gateway machine * **node host** → node runner (macOS companion app or headless node host) macOS split: * **node host service** forwards `system.run` to the **macOS app** over local IPC. * **macOS app** enforces approvals + executes the command in UI context. [​](https://docs.molt.bot/tools/exec-approvals#settings-and-storage) Settings and storage -------------------------------------------------------------------------------------------- Approvals live in a local JSON file on the execution host: `~/.clawdbot/exec-approvals.json` Example schema: Copy { "version": 1, "socket": { "path": "~/.clawdbot/exec-approvals.sock", "token": "base64url-token" }, "defaults": { "security": "deny", "ask": "on-miss", "askFallback": "deny", "autoAllowSkills": false }, "agents": { "main": { "security": "allowlist", "ask": "on-miss", "askFallback": "deny", "autoAllowSkills": true, "allowlist": [\ {\ "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",\ "pattern": "~/Projects/**/bin/rg",\ "lastUsedAt": 1737150000000,\ "lastUsedCommand": "rg -n TODO",\ "lastResolvedPath": "/Users/user/Projects/.../bin/rg"\ }\ ] } } } [​](https://docs.molt.bot/tools/exec-approvals#policy-knobs) Policy knobs ---------------------------------------------------------------------------- ### [​](https://docs.molt.bot/tools/exec-approvals#security-exec-security) Security (`exec.security`) * **deny**: block all host exec requests. * **allowlist**: allow only allowlisted commands. * **full**: allow everything (equivalent to elevated). ### [​](https://docs.molt.bot/tools/exec-approvals#ask-exec-ask) Ask (`exec.ask`) * **off**: never prompt. * **on-miss**: prompt only when allowlist does not match. * **always**: prompt on every command. ### [​](https://docs.molt.bot/tools/exec-approvals#ask-fallback-askfallback) Ask fallback (`askFallback`) If a prompt is required but no UI is reachable, fallback decides: * **deny**: block. * **allowlist**: allow only if allowlist matches. * **full**: allow. [​](https://docs.molt.bot/tools/exec-approvals#allowlist-per-agent) Allowlist (per agent) -------------------------------------------------------------------------------------------- Allowlists are **per agent**. If multiple agents exist, switch which agent you’re editing in the macOS app. Patterns are **case-insensitive glob matches**. Patterns should resolve to **binary paths** (basename-only entries are ignored). Legacy `agents.default` entries are migrated to `agents.main` on load. Examples: * `~/Projects/**/bin/bird` * `~/.local/bin/*` * `/opt/homebrew/bin/rg` Each allowlist entry tracks: * **id** stable UUID used for UI identity (optional) * **last used** timestamp * **last used command** * **last resolved path** [​](https://docs.molt.bot/tools/exec-approvals#auto-allow-skill-clis) Auto-allow skill CLIs ---------------------------------------------------------------------------------------------- When **Auto-allow skill CLIs** is enabled, executables referenced by known skills are treated as allowlisted on nodes (macOS node or headless node host). This uses `skills.bins` over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists. [​](https://docs.molt.bot/tools/exec-approvals#safe-bins-stdin-only) Safe bins (stdin-only) ---------------------------------------------------------------------------------------------- `tools.exec.safeBins` defines a small list of **stdin-only** binaries (for example `jq`) that can run in allowlist mode **without** explicit allowlist entries. Safe bins reject positional file args and path-like tokens, so they can only operate on the incoming stream. Shell chaining and redirections are not auto-allowed in allowlist mode. Shell chaining (`&&`, `||`, `;`) is allowed when every top-level segment satisfies the allowlist (including safe bins or skill auto-allow). Redirections remain unsupported in allowlist mode. Default safe bins: `jq`, `grep`, `cut`, `sort`, `uniq`, `head`, `tail`, `tr`, `wc`. [​](https://docs.molt.bot/tools/exec-approvals#control-ui-editing) Control UI editing ---------------------------------------------------------------------------------------- Use the **Control UI → Nodes → Exec approvals** card to edit defaults, per‑agent overrides, and allowlists. Pick a scope (Defaults or an agent), tweak the policy, add/remove allowlist patterns, then **Save**. The UI shows **last used** metadata per pattern so you can keep the list tidy. The target selector chooses **Gateway** (local approvals) or a **Node**. Nodes must advertise `system.execApprovals.get/set` (macOS app or headless node host). If a node does not advertise exec approvals yet, edit its local `~/.clawdbot/exec-approvals.json` directly. CLI: `moltbot approvals` supports gateway or node editing (see [Approvals CLI](https://docs.molt.bot/cli/approvals) ). [​](https://docs.molt.bot/tools/exec-approvals#approval-flow) Approval flow ------------------------------------------------------------------------------ When a prompt is required, the gateway broadcasts `exec.approval.requested` to operator clients. The Control UI and macOS app resolve it via `exec.approval.resolve`, then the gateway forwards the approved request to the node host. When approvals are required, the exec tool returns immediately with an approval id. Use that id to correlate later system events (`Exec finished` / `Exec denied`). If no decision arrives before the timeout, the request is treated as an approval timeout and surfaced as a denial reason. The confirmation dialog includes: * command + args * cwd * agent id * resolved executable path * host + policy metadata Actions: * **Allow once** → run now * **Always allow** → add to allowlist + run * **Deny** → block [​](https://docs.molt.bot/tools/exec-approvals#approval-forwarding-to-chat-channels) Approval forwarding to chat channels ---------------------------------------------------------------------------------------------------------------------------- You can forward exec approval prompts to any chat channel (including plugin channels) and approve them with `/approve`. This uses the normal outbound delivery pipeline. Config: Copy { approvals: { exec: { enabled: true, mode: "session", // "session" | "targets" | "both" agentFilter: ["main"], sessionFilter: ["discord"], // substring or regex targets: [\ { channel: "slack", to: "U12345678" },\ { channel: "telegram", to: "123456789" }\ ] } } } Reply in chat: Copy /approve allow-once /approve allow-always /approve deny ### [​](https://docs.molt.bot/tools/exec-approvals#macos-ipc-flow) macOS IPC flow Copy Gateway -> Node Service (WS) | IPC (UDS + token + HMAC + TTL) v Mac App (UI + approvals + system.run) Security notes: * Unix socket mode `0600`, token stored in `exec-approvals.json`. * Same-UID peer check. * Challenge/response (nonce + HMAC token + request hash) + short TTL. [​](https://docs.molt.bot/tools/exec-approvals#system-events) System events ------------------------------------------------------------------------------ Exec lifecycle is surfaced as system messages: * `Exec running` (only if the command exceeds the running notice threshold) * `Exec finished` * `Exec denied` These are posted to the agent’s session after the node reports the event. Gateway-host exec approvals emit the same lifecycle events when the command finishes (and optionally when running longer than the threshold). Approval-gated execs reuse the approval id as the `runId` in these messages for easy correlation. [​](https://docs.molt.bot/tools/exec-approvals#implications) Implications ---------------------------------------------------------------------------- * **full** is powerful; prefer allowlists when possible. * **ask** keeps you in the loop while still allowing fast approvals. * Per-agent allowlists prevent one agent’s approvals from leaking into others. * Approvals only apply to host exec requests from **authorized senders**. Unauthorized senders cannot issue `/exec`. * `/exec security=full` is a session-level convenience for authorized operators and skips approvals by design. To hard-block host exec, set approvals security to `deny` or deny the `exec` tool via tool policy. Related: * [Exec tool](https://docs.molt.bot/tools/exec) * [Elevated mode](https://docs.molt.bot/tools/elevated) * [Skills](https://docs.molt.bot/tools/skills) ⌘I --- # Date time - Moltbot [Skip to main content](https://docs.molt.bot/date-time#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Date & Time](https://docs.molt.bot/date-time#date-%26-time) * [Message envelopes (local by default)](https://docs.molt.bot/date-time#message-envelopes-local-by-default) * [Examples](https://docs.molt.bot/date-time#examples) * [System prompt: Current Date & Time](https://docs.molt.bot/date-time#system-prompt%3A-current-date-%26-time) * [System event lines (local by default)](https://docs.molt.bot/date-time#system-event-lines-local-by-default) * [Configure user timezone + format](https://docs.molt.bot/date-time#configure-user-timezone-%2B-format) * [Time format detection (auto)](https://docs.molt.bot/date-time#time-format-detection-auto) * [Tool payloads + connectors (raw provider time + normalized fields)](https://docs.molt.bot/date-time#tool-payloads-%2B-connectors-raw-provider-time-%2B-normalized-fields) * [Related docs](https://docs.molt.bot/date-time#related-docs) [​](https://docs.molt.bot/date-time#date-&-time) Date & Time =============================================================== Moltbot defaults to **host-local time for transport timestamps** and **user timezone only in the system prompt**. Provider timestamps are preserved so tools keep their native semantics (current time is available via `session_status`). [​](https://docs.molt.bot/date-time#message-envelopes-local-by-default) Message envelopes (local by default) --------------------------------------------------------------------------------------------------------------- Inbound messages are wrapped with a timestamp (minute precision): Copy [Provider ... 2026-01-05 16:26 PST] message text This envelope timestamp is **host-local by default**, regardless of the provider timezone. You can override this behavior: Copy { agents: { defaults: { envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone envelopeTimestamp: "on", // "on" | "off" envelopeElapsed: "on" // "on" | "off" } } } * `envelopeTimezone: "utc"` uses UTC. * `envelopeTimezone: "local"` uses the host timezone. * `envelopeTimezone: "user"` uses `agents.defaults.userTimezone` (falls back to host timezone). * Use an explicit IANA timezone (e.g., `"America/Chicago"`) for a fixed zone. * `envelopeTimestamp: "off"` removes absolute timestamps from envelope headers. * `envelopeElapsed: "off"` removes elapsed time suffixes (the `+2m` style). ### [​](https://docs.molt.bot/date-time#examples) Examples **Local (default):** Copy [WhatsApp +1555 2026-01-18 00:19 PST] hello **User timezone:** Copy [WhatsApp +1555 2026-01-18 00:19 CST] hello **Elapsed time enabled:** Copy [WhatsApp +1555 +30s 2026-01-18T05:19Z] follow-up [​](https://docs.molt.bot/date-time#system-prompt:-current-date-&-time) System prompt: Current Date & Time ------------------------------------------------------------------------------------------------------------- If the user timezone is known, the system prompt includes a dedicated **Current Date & Time** section with the **time zone only** (no clock/time format) to keep prompt caching stable: Copy Time zone: America/Chicago When the agent needs the current time, use the `session_status` tool; the status card includes a timestamp line. [​](https://docs.molt.bot/date-time#system-event-lines-local-by-default) System event lines (local by default) ----------------------------------------------------------------------------------------------------------------- Queued system events inserted into agent context are prefixed with a timestamp using the same timezone selection as message envelopes (default: host-local). Copy System: [2026-01-12 12:19:17 PST] Model switched. ### [​](https://docs.molt.bot/date-time#configure-user-timezone-+-format) Configure user timezone + format Copy { agents: { defaults: { userTimezone: "America/Chicago", timeFormat: "auto" // auto | 12 | 24 } } } * `userTimezone` sets the **user-local timezone** for prompt context. * `timeFormat` controls **12h/24h display** in the prompt. `auto` follows OS prefs. [​](https://docs.molt.bot/date-time#time-format-detection-auto) Time format detection (auto) ----------------------------------------------------------------------------------------------- When `timeFormat: "auto"`, Moltbot inspects the OS preference (macOS/Windows) and falls back to locale formatting. The detected value is **cached per process** to avoid repeated system calls. [​](https://docs.molt.bot/date-time#tool-payloads-+-connectors-raw-provider-time-+-normalized-fields) Tool payloads + connectors (raw provider time + normalized fields) --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Channel tools return **provider-native timestamps** and add normalized fields for consistency: * `timestampMs`: epoch milliseconds (UTC) * `timestampUtc`: ISO 8601 UTC string Raw provider fields are preserved so nothing is lost. * Slack: epoch-like strings from the API * Discord: UTC ISO timestamps * Telegram/WhatsApp: provider-specific numeric/ISO timestamps If you need local time, convert it downstream using the known timezone. [​](https://docs.molt.bot/date-time#related-docs) Related docs ----------------------------------------------------------------- * [System Prompt](https://docs.molt.bot/concepts/system-prompt) * [Timezones](https://docs.molt.bot/concepts/timezone) * [Messages](https://docs.molt.bot/concepts/messages) ⌘I --- # Nostr - Moltbot [Skip to main content](https://docs.molt.bot/channels/nostr#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Nostr](https://docs.molt.bot/channels/nostr#nostr) * [Install (on demand)](https://docs.molt.bot/channels/nostr#install-on-demand) * [Onboarding (recommended)](https://docs.molt.bot/channels/nostr#onboarding-recommended) * [Manual install](https://docs.molt.bot/channels/nostr#manual-install) * [Quick setup](https://docs.molt.bot/channels/nostr#quick-setup) * [Configuration reference](https://docs.molt.bot/channels/nostr#configuration-reference) * [Profile metadata](https://docs.molt.bot/channels/nostr#profile-metadata) * [Access control](https://docs.molt.bot/channels/nostr#access-control) * [DM policies](https://docs.molt.bot/channels/nostr#dm-policies) * [Allowlist example](https://docs.molt.bot/channels/nostr#allowlist-example) * [Key formats](https://docs.molt.bot/channels/nostr#key-formats) * [Relays](https://docs.molt.bot/channels/nostr#relays) * [Protocol support](https://docs.molt.bot/channels/nostr#protocol-support) * [Testing](https://docs.molt.bot/channels/nostr#testing) * [Local relay](https://docs.molt.bot/channels/nostr#local-relay) * [Manual test](https://docs.molt.bot/channels/nostr#manual-test) * [Troubleshooting](https://docs.molt.bot/channels/nostr#troubleshooting) * [Not receiving messages](https://docs.molt.bot/channels/nostr#not-receiving-messages) * [Not sending responses](https://docs.molt.bot/channels/nostr#not-sending-responses) * [Duplicate responses](https://docs.molt.bot/channels/nostr#duplicate-responses) * [Security](https://docs.molt.bot/channels/nostr#security) * [Limitations (MVP)](https://docs.molt.bot/channels/nostr#limitations-mvp) [​](https://docs.molt.bot/channels/nostr#nostr) Nostr ======================================================== **Status:** Optional plugin (disabled by default). Nostr is a decentralized protocol for social networking. This channel enables Moltbot to receive and respond to encrypted direct messages (DMs) via NIP-04. [​](https://docs.molt.bot/channels/nostr#install-on-demand) Install (on demand) ---------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/channels/nostr#onboarding-recommended) Onboarding (recommended) * The onboarding wizard (`moltbot onboard`) and `moltbot 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.molt.bot/channels/nostr#manual-install) Manual install Copy moltbot plugins install @moltbot/nostr Use a local checkout (dev workflows): Copy moltbot plugins install --link /extensions/nostr Restart the Gateway after installing or enabling plugins. [​](https://docs.molt.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.molt.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.molt.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": "moltbot", "displayName": "Moltbot", "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.molt.bot/channels/nostr#access-control) Access control -------------------------------------------------------------------------- ### [​](https://docs.molt.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.molt.bot/channels/nostr#allowlist-example) Allowlist example Copy { "channels": { "nostr": { "privateKey": "${NOSTR_PRIVATE_KEY}", "dmPolicy": "allowlist", "allowFrom": ["npub1abc...", "npub1xyz..."] } } } [​](https://docs.molt.bot/channels/nostr#key-formats) Key formats -------------------------------------------------------------------- Accepted formats: * **Private key:** `nsec...` or 64-char hex * **Pubkeys (`allowFrom`):** `npub...` or hex [​](https://docs.molt.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.molt.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.molt.bot/channels/nostr#testing) Testing ------------------------------------------------------------ ### [​](https://docs.molt.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.molt.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.molt.bot/channels/nostr#troubleshooting) Troubleshooting ---------------------------------------------------------------------------- ### [​](https://docs.molt.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.molt.bot/channels/nostr#not-sending-responses) Not sending responses * Check relay accepts writes. * Verify outbound connectivity. * Watch for relay rate limits. ### [​](https://docs.molt.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.molt.bot/channels/nostr#security) Security -------------------------------------------------------------- * Never commit private keys. * Use environment variables for keys. * Consider `allowlist` for production bots. [​](https://docs.molt.bot/channels/nostr#limitations-mvp) Limitations (MVP) ------------------------------------------------------------------------------ * Direct messages only (no group chats). * No media attachments. * NIP-04 only (NIP-17 gift-wrap planned). ⌘I --- # Index - Moltbot [Skip to main content](https://docs.molt.bot/channels/index#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Chat Channels](https://docs.molt.bot/channels/index#chat-channels) * [Supported channels](https://docs.molt.bot/channels/index#supported-channels) * [Notes](https://docs.molt.bot/channels/index#notes) [​](https://docs.molt.bot/channels/index#chat-channels) Chat Channels ======================================================================== Moltbot 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.molt.bot/channels/index#supported-channels) Supported channels ---------------------------------------------------------------------------------- * [WhatsApp](https://docs.molt.bot/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing. * [Telegram](https://docs.molt.bot/channels/telegram) — Bot API via grammY; supports groups. * [Discord](https://docs.molt.bot/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs. * [Slack](https://docs.molt.bot/channels/slack) — Bolt SDK; workspace apps. * [Google Chat](https://docs.molt.bot/channels/googlechat) — Google Chat API app via HTTP webhook. * [Mattermost](https://docs.molt.bot/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately). * [Signal](https://docs.molt.bot/channels/signal) — signal-cli; privacy-focused. * [BlueBubbles](https://docs.molt.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.molt.bot/channels/imessage) — macOS only; native integration via imsg (legacy, consider BlueBubbles for new setups). * [Microsoft Teams](https://docs.molt.bot/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately). * [LINE](https://docs.molt.bot/channels/line) — LINE Messaging API bot (plugin, installed separately). * [Nextcloud Talk](https://docs.molt.bot/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately). * [Matrix](https://docs.molt.bot/channels/matrix) — Matrix protocol (plugin, installed separately). * [Nostr](https://docs.molt.bot/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately). * [Tlon](https://docs.molt.bot/channels/tlon) — Urbit-based messenger (plugin, installed separately). * [Twitch](https://docs.molt.bot/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately). * [Zalo](https://docs.molt.bot/channels/zalo) — Zalo Bot API; Vietnam’s popular messenger (plugin, installed separately). * [Zalo Personal](https://docs.molt.bot/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately). * [WebChat](https://docs.molt.bot/web/webchat) — Gateway WebChat UI over WebSocket. [​](https://docs.molt.bot/channels/index#notes) Notes -------------------------------------------------------- * Channels can run simultaneously; configure multiple and Moltbot will route per chat. * Fastest setup is usually **Telegram** (simple bot token). WhatsApp requires QR pairing and stores more state on disk. * Group behavior varies by channel; see [Groups](https://docs.molt.bot/concepts/groups) . * DM pairing and allowlists are enforced for safety; see [Security](https://docs.molt.bot/gateway/security) . * Telegram internals: [grammY notes](https://docs.molt.bot/channels/grammy) . * Troubleshooting: [Channel troubleshooting](https://docs.molt.bot/channels/troubleshooting) . * Model providers are documented separately; see [Model Providers](https://docs.molt.bot/providers/models) . [Tui](https://docs.molt.bot/tui) [Whatsapp](https://docs.molt.bot/channels/whatsapp) ⌘I --- # Qwen - Moltbot [Skip to main content](https://docs.molt.bot/providers/qwen#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Qwen](https://docs.molt.bot/providers/qwen#qwen) * [Enable the plugin](https://docs.molt.bot/providers/qwen#enable-the-plugin) * [Authenticate](https://docs.molt.bot/providers/qwen#authenticate) * [Model IDs](https://docs.molt.bot/providers/qwen#model-ids) * [Reuse Qwen Code CLI login](https://docs.molt.bot/providers/qwen#reuse-qwen-code-cli-login) * [Notes](https://docs.molt.bot/providers/qwen#notes) [​](https://docs.molt.bot/providers/qwen#qwen) Qwen ====================================================== Qwen provides a free-tier OAuth flow for Qwen Coder and Qwen Vision models (2,000 requests/day, subject to Qwen rate limits). [​](https://docs.molt.bot/providers/qwen#enable-the-plugin) Enable the plugin -------------------------------------------------------------------------------- Copy moltbot plugins enable qwen-portal-auth Restart the Gateway after enabling. [​](https://docs.molt.bot/providers/qwen#authenticate) Authenticate ---------------------------------------------------------------------- Copy moltbot models auth login --provider qwen-portal --set-default This runs the Qwen device-code OAuth flow and writes a provider entry to your `models.json` (plus a `qwen` alias for quick switching). [​](https://docs.molt.bot/providers/qwen#model-ids) Model IDs ---------------------------------------------------------------- * `qwen-portal/coder-model` * `qwen-portal/vision-model` Switch models with: Copy moltbot models set qwen-portal/coder-model [​](https://docs.molt.bot/providers/qwen#reuse-qwen-code-cli-login) Reuse Qwen Code CLI login ------------------------------------------------------------------------------------------------ If you already logged in with the Qwen Code CLI, Moltbot will sync credentials from `~/.qwen/oauth_creds.json` when it loads the auth store. You still need a `models.providers.qwen-portal` entry (use the login command above to create one). [​](https://docs.molt.bot/providers/qwen#notes) Notes -------------------------------------------------------- * Tokens auto-refresh; re-run the login command if refresh fails or access is revoked. * Default base URL: `https://portal.qwen.ai/v1` (override with `models.providers.qwen-portal.baseUrl` if Qwen provides a different endpoint). * See [Model providers](https://docs.molt.bot/concepts/model-providers) for provider-wide rules. ⌘I --- # Migrating - Moltbot [Skip to main content](https://docs.molt.bot/install/migrating#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Migrating Moltbot to a new machine](https://docs.molt.bot/install/migrating#migrating-moltbot-to-a-new-machine) * [Before you start (what you are migrating)](https://docs.molt.bot/install/migrating#before-you-start-what-you-are-migrating) * [1) Identify your state directory](https://docs.molt.bot/install/migrating#1-identify-your-state-directory) * [2) Identify your workspace](https://docs.molt.bot/install/migrating#2-identify-your-workspace) * [3) Understand what you will preserve](https://docs.molt.bot/install/migrating#3-understand-what-you-will-preserve) * [Migration steps (recommended)](https://docs.molt.bot/install/migrating#migration-steps-recommended) * [Step 0 — Make a backup (old machine)](https://docs.molt.bot/install/migrating#step-0-%E2%80%94-make-a-backup-old-machine) * [Step 1 — Install Moltbot on the new machine](https://docs.molt.bot/install/migrating#step-1-%E2%80%94-install-moltbot-on-the-new-machine) * [Step 2 — Copy the state dir + workspace to the new machine](https://docs.molt.bot/install/migrating#step-2-%E2%80%94-copy-the-state-dir-%2B-workspace-to-the-new-machine) * [Step 3 — Run Doctor (migrations + service repair)](https://docs.molt.bot/install/migrating#step-3-%E2%80%94-run-doctor-migrations-%2B-service-repair) * [Common footguns (and how to avoid them)](https://docs.molt.bot/install/migrating#common-footguns-and-how-to-avoid-them) * [Footgun: profile / state-dir mismatch](https://docs.molt.bot/install/migrating#footgun%3A-profile-%2F-state-dir-mismatch) * [Footgun: copying only moltbot.json](https://docs.molt.bot/install/migrating#footgun%3A-copying-only-moltbot-json) * [Footgun: permissions / ownership](https://docs.molt.bot/install/migrating#footgun%3A-permissions-%2F-ownership) * [Footgun: migrating between remote/local modes](https://docs.molt.bot/install/migrating#footgun%3A-migrating-between-remote%2Flocal-modes) * [Footgun: secrets in backups](https://docs.molt.bot/install/migrating#footgun%3A-secrets-in-backups) * [Verification checklist](https://docs.molt.bot/install/migrating#verification-checklist) * [Related](https://docs.molt.bot/install/migrating#related) [​](https://docs.molt.bot/install/migrating#migrating-moltbot-to-a-new-machine) Migrating Moltbot to a new machine ===================================================================================================================== This guide migrates a Moltbot Gateway from one machine to another **without redoing onboarding**. The migration is simple conceptually: * Copy the **state directory** (`$CLAWDBOT_STATE_DIR`, default: `~/.clawdbot/`) — this includes config, auth, sessions, and channel state. * Copy your **workspace** (`~/clawd/` by default) — this includes your agent files (memory, prompts, etc.). But there are common footguns around **profiles**, **permissions**, and **partial copies**. [​](https://docs.molt.bot/install/migrating#before-you-start-what-you-are-migrating) Before you start (what you are migrating) --------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/install/migrating#1-identify-your-state-directory) 1) Identify your state directory Most installs use the default: * **State dir:** `~/.clawdbot/` But it may be different if you use: * `--profile ` (often becomes `~/.clawdbot-/`) * `CLAWDBOT_STATE_DIR=/some/path` If you’re not sure, run on the **old** machine: Copy moltbot status Look for mentions of `CLAWDBOT_STATE_DIR` / profile in the output. If you run multiple gateways, repeat for each profile. ### [​](https://docs.molt.bot/install/migrating#2-identify-your-workspace) 2) Identify your workspace Common defaults: * `~/clawd/` (recommended workspace) * a custom folder you created Your workspace is where files like `MEMORY.md`, `USER.md`, and `memory/*.md` live. ### [​](https://docs.molt.bot/install/migrating#3-understand-what-you-will-preserve) 3) Understand what you will preserve If you copy **both** the state dir and workspace, you keep: * Gateway configuration (`moltbot.json`) * Auth profiles / API keys / OAuth tokens * Session history + agent state * Channel state (e.g. WhatsApp login/session) * Your workspace files (memory, skills notes, etc.) If you copy **only** the workspace (e.g., via Git), you do **not** preserve: * sessions * credentials * channel logins Those live under `$CLAWDBOT_STATE_DIR`. [​](https://docs.molt.bot/install/migrating#migration-steps-recommended) Migration steps (recommended) --------------------------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/install/migrating#step-0-%E2%80%94-make-a-backup-old-machine) Step 0 — Make a backup (old machine) On the **old** machine, stop the gateway first so files aren’t changing mid-copy: Copy moltbot gateway stop (Optional but recommended) archive the state dir and workspace: Copy # Adjust paths if you use a profile or custom locations cd ~ tar -czf moltbot-state.tgz .clawdbot tar -czf clawd-workspace.tgz clawd If you have multiple profiles/state dirs (e.g. `~/.clawdbot-main`, `~/.clawdbot-work`), archive each. ### [​](https://docs.molt.bot/install/migrating#step-1-%E2%80%94-install-moltbot-on-the-new-machine) Step 1 — Install Moltbot on the new machine On the **new** machine, install the CLI (and Node if needed): * See: [Install](https://docs.molt.bot/install) At this stage, it’s OK if onboarding creates a fresh `~/.clawdbot/` — you will overwrite it in the next step. ### [​](https://docs.molt.bot/install/migrating#step-2-%E2%80%94-copy-the-state-dir-+-workspace-to-the-new-machine) Step 2 — Copy the state dir + workspace to the new machine Copy **both**: * `$CLAWDBOT_STATE_DIR` (default `~/.clawdbot/`) * your workspace (default `~/clawd/`) Common approaches: * `scp` the tarballs and extract * `rsync -a` over SSH * external drive After copying, ensure: * Hidden directories were included (e.g. `.clawdbot/`) * File ownership is correct for the user running the gateway ### [​](https://docs.molt.bot/install/migrating#step-3-%E2%80%94-run-doctor-migrations-+-service-repair) Step 3 — Run Doctor (migrations + service repair) On the **new** machine: Copy moltbot doctor Doctor is the “safe boring” command. It repairs services, applies config migrations, and warns about mismatches. Then: Copy moltbot gateway restart moltbot status [​](https://docs.molt.bot/install/migrating#common-footguns-and-how-to-avoid-them) Common footguns (and how to avoid them) ----------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/install/migrating#footgun:-profile-/-state-dir-mismatch) Footgun: profile / state-dir mismatch If you ran the old gateway with a profile (or `CLAWDBOT_STATE_DIR`), and the new gateway uses a different one, you’ll see symptoms like: * config changes not taking effect * channels missing / logged out * empty session history Fix: run the gateway/service using the **same** profile/state dir you migrated, then rerun: Copy moltbot doctor ### [​](https://docs.molt.bot/install/migrating#footgun:-copying-only-moltbot-json) Footgun: copying only `moltbot.json` `moltbot.json` is not enough. Many providers store state under: * `$CLAWDBOT_STATE_DIR/credentials/` * `$CLAWDBOT_STATE_DIR/agents//...` Always migrate the entire `$CLAWDBOT_STATE_DIR` folder. ### [​](https://docs.molt.bot/install/migrating#footgun:-permissions-/-ownership) Footgun: permissions / ownership If you copied as root or changed users, the gateway may fail to read credentials/sessions. Fix: ensure the state dir + workspace are owned by the user running the gateway. ### [​](https://docs.molt.bot/install/migrating#footgun:-migrating-between-remote/local-modes) Footgun: migrating between remote/local modes * If your UI (WebUI/TUI) points at a **remote** gateway, the remote host owns the session store + workspace. * Migrating your laptop won’t move the remote gateway’s state. If you’re in remote mode, migrate the **gateway host**. ### [​](https://docs.molt.bot/install/migrating#footgun:-secrets-in-backups) Footgun: secrets in backups `$CLAWDBOT_STATE_DIR` contains secrets (API keys, OAuth tokens, WhatsApp creds). Treat backups like production secrets: * store encrypted * avoid sharing over insecure channels * rotate keys if you suspect exposure [​](https://docs.molt.bot/install/migrating#verification-checklist) Verification checklist --------------------------------------------------------------------------------------------- On the new machine, confirm: * `moltbot status` shows the gateway running * Your channels are still connected (e.g. WhatsApp doesn’t require re-pair) * The dashboard opens and shows existing sessions * Your workspace files (memory, configs) are present [​](https://docs.molt.bot/install/migrating#related) Related --------------------------------------------------------------- * [Doctor](https://docs.molt.bot/gateway/doctor) * [Gateway troubleshooting](https://docs.molt.bot/gateway/troubleshooting) * [Where does Moltbot store its data?](https://docs.molt.bot/help/faq#where-does-moltbot-store-its-data) ⌘I --- # Tlon - Moltbot [Skip to main content](https://docs.molt.bot/channels/tlon#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Tlon (plugin)](https://docs.molt.bot/channels/tlon#tlon-plugin) * [Plugin required](https://docs.molt.bot/channels/tlon#plugin-required) * [Setup](https://docs.molt.bot/channels/tlon#setup) * [Group channels](https://docs.molt.bot/channels/tlon#group-channels) * [Access control](https://docs.molt.bot/channels/tlon#access-control) * [Delivery targets (CLI/cron)](https://docs.molt.bot/channels/tlon#delivery-targets-cli%2Fcron) * [Notes](https://docs.molt.bot/channels/tlon#notes) [​](https://docs.molt.bot/channels/tlon#tlon-plugin) Tlon (plugin) ===================================================================== Tlon is a decentralized messenger built on Urbit. Moltbot 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.molt.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 moltbot plugins install @moltbot/tlon Local checkout (when running from a git repo): Copy moltbot plugins install ./extensions/tlon Details: [Plugins](https://docs.molt.bot/plugin) [​](https://docs.molt.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.molt.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.molt.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.molt.bot/channels/tlon#delivery-targets-cli/cron) Delivery targets (CLI/cron) ------------------------------------------------------------------------------------------------- Use these with `moltbot message send` or cron delivery: * DM: `~sampel-palnet` or `dm/~sampel-palnet` * Group: `chat/~host-ship/channel` or `group:~host-ship/channel` [​](https://docs.molt.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, Moltbot replies in-thread. * Media: `sendMedia` falls back to text + URL (no native upload). ⌘I --- # Claude max api proxy - Moltbot [Skip to main content](https://docs.molt.bot/providers/claude-max-api-proxy#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Claude Max API Proxy](https://docs.molt.bot/providers/claude-max-api-proxy#claude-max-api-proxy) * [Why Use This?](https://docs.molt.bot/providers/claude-max-api-proxy#why-use-this) * [How It Works](https://docs.molt.bot/providers/claude-max-api-proxy#how-it-works) * [Installation](https://docs.molt.bot/providers/claude-max-api-proxy#installation) * [Usage](https://docs.molt.bot/providers/claude-max-api-proxy#usage) * [Start the server](https://docs.molt.bot/providers/claude-max-api-proxy#start-the-server) * [Test it](https://docs.molt.bot/providers/claude-max-api-proxy#test-it) * [With Moltbot](https://docs.molt.bot/providers/claude-max-api-proxy#with-moltbot) * [Available Models](https://docs.molt.bot/providers/claude-max-api-proxy#available-models) * [Auto-Start on macOS](https://docs.molt.bot/providers/claude-max-api-proxy#auto-start-on-macos) * [Links](https://docs.molt.bot/providers/claude-max-api-proxy#links) * [Notes](https://docs.molt.bot/providers/claude-max-api-proxy#notes) * [See Also](https://docs.molt.bot/providers/claude-max-api-proxy#see-also) [​](https://docs.molt.bot/providers/claude-max-api-proxy#claude-max-api-proxy) Claude Max API Proxy ====================================================================================================== **claude-max-api-proxy** is a community tool that exposes your Claude Max/Pro subscription as an OpenAI-compatible API endpoint. This allows you to use your subscription with any tool that supports the OpenAI API format. [​](https://docs.molt.bot/providers/claude-max-api-proxy#why-use-this) Why Use This? --------------------------------------------------------------------------------------- | Approach | Cost | Best For | | --- | --- | --- | | Anthropic API | Pay per token (~15/Minput,15/M input, 15/Minput,75/M output for Opus) | Production apps, high volume | | Claude Max subscription | $200/month flat | Personal use, development, unlimited usage | If you have a Claude Max subscription and want to use it with OpenAI-compatible tools, this proxy can save you significant money. [​](https://docs.molt.bot/providers/claude-max-api-proxy#how-it-works) How It Works -------------------------------------------------------------------------------------- Copy Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription) (OpenAI format) (converts format) (uses your login) The proxy: 1. Accepts OpenAI-format requests at `http://localhost:3456/v1/chat/completions` 2. Converts them to Claude Code CLI commands 3. Returns responses in OpenAI format (streaming supported) [​](https://docs.molt.bot/providers/claude-max-api-proxy#installation) Installation -------------------------------------------------------------------------------------- Copy # Requires Node.js 20+ and Claude Code CLI npm install -g claude-max-api-proxy # Verify Claude CLI is authenticated claude --version [​](https://docs.molt.bot/providers/claude-max-api-proxy#usage) Usage ------------------------------------------------------------------------ ### [​](https://docs.molt.bot/providers/claude-max-api-proxy#start-the-server) Start the server Copy claude-max-api # Server runs at http://localhost:3456 ### [​](https://docs.molt.bot/providers/claude-max-api-proxy#test-it) Test it Copy # Health check curl http://localhost:3456/health # List models curl http://localhost:3456/v1/models # Chat completion curl http://localhost:3456/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "claude-opus-4", "messages": [{"role": "user", "content": "Hello!"}] }' ### [​](https://docs.molt.bot/providers/claude-max-api-proxy#with-moltbot) With Moltbot You can point Moltbot at the proxy as a custom OpenAI-compatible endpoint: Copy { env: { OPENAI_API_KEY: "not-needed", OPENAI_BASE_URL: "http://localhost:3456/v1" }, agents: { defaults: { model: { primary: "openai/claude-opus-4" } } } } [​](https://docs.molt.bot/providers/claude-max-api-proxy#available-models) Available Models ---------------------------------------------------------------------------------------------- | Model ID | Maps To | | --- | --- | | `claude-opus-4` | Claude Opus 4 | | `claude-sonnet-4` | Claude Sonnet 4 | | `claude-haiku-4` | Claude Haiku 4 | [​](https://docs.molt.bot/providers/claude-max-api-proxy#auto-start-on-macos) Auto-Start on macOS ---------------------------------------------------------------------------------------------------- Create a LaunchAgent to run the proxy automatically: Copy cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF' Label com.claude-max-api RunAtLoad KeepAlive ProgramArguments /usr/local/bin/node /usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js EnvironmentVariables PATH /usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin EOF launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist [​](https://docs.molt.bot/providers/claude-max-api-proxy#links) Links ------------------------------------------------------------------------ * **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy) * **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy) * **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues) [​](https://docs.molt.bot/providers/claude-max-api-proxy#notes) Notes ------------------------------------------------------------------------ * This is a **community tool**, not officially supported by Anthropic or Moltbot * Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated * The proxy runs locally and does not send data to any third-party servers * Streaming responses are fully supported [​](https://docs.molt.bot/providers/claude-max-api-proxy#see-also) See Also ------------------------------------------------------------------------------ * [Anthropic provider](https://docs.molt.bot/providers/anthropic) - Native Moltbot integration with Claude setup-token or API keys * [OpenAI provider](https://docs.molt.bot/providers/openai) - For OpenAI/Codex subscriptions ⌘I --- # Vps - Moltbot [Skip to main content](https://docs.molt.bot/vps#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [VPS hosting](https://docs.molt.bot/vps#vps-hosting) * [Pick a provider](https://docs.molt.bot/vps#pick-a-provider) * [How cloud setups work](https://docs.molt.bot/vps#how-cloud-setups-work) * [Using nodes with a VPS](https://docs.molt.bot/vps#using-nodes-with-a-vps) [​](https://docs.molt.bot/vps#vps-hosting) VPS hosting ========================================================= This hub links to the supported VPS/hosting guides and explains how cloud deployments work at a high level. [​](https://docs.molt.bot/vps#pick-a-provider) Pick a provider ----------------------------------------------------------------- * **Railway** (one‑click + browser setup): [Railway](https://docs.molt.bot/railway) * **Northflank** (one‑click + browser setup): [Northflank](https://docs.molt.bot/northflank) * **Oracle Cloud (Always Free)**: [Oracle](https://docs.molt.bot/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky) * **Fly.io**: [Fly.io](https://docs.molt.bot/platforms/fly) * **Hetzner (Docker)**: [Hetzner](https://docs.molt.bot/platforms/hetzner) * **GCP (Compute Engine)**: [GCP](https://docs.molt.bot/platforms/gcp) * **exe.dev** (VM + HTTPS proxy): [exe.dev](https://docs.molt.bot/platforms/exe-dev) * **AWS (EC2/Lightsail/free tier)**: works well too. Video guide: [https://x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547) [​](https://docs.molt.bot/vps#how-cloud-setups-work) How cloud setups work ----------------------------------------------------------------------------- * The **Gateway runs on the VPS** and owns state + workspace. * You connect from your laptop/phone via the **Control UI** or **Tailscale/SSH**. * Treat the VPS as the source of truth and **back up** the state + workspace. * Secure default: keep the Gateway on loopback and access it via SSH tunnel or Tailscale Serve. If you bind to `lan`/`tailnet`, require `gateway.auth.token` or `gateway.auth.password`. Remote access: [Gateway remote](https://docs.molt.bot/gateway/remote) Platforms hub: [Platforms](https://docs.molt.bot/platforms) [​](https://docs.molt.bot/vps#using-nodes-with-a-vps) Using nodes with a VPS ------------------------------------------------------------------------------- You can keep the Gateway in the cloud and pair **nodes** on your local devices (Mac/iOS/Android/headless). Nodes provide local screen/camera/canvas and `system.run` capabilities while the Gateway stays in the cloud. Docs: [Nodes](https://docs.molt.bot/nodes) , [Nodes CLI](https://docs.molt.bot/cli/nodes) ⌘I --- # Openresponses http api - Moltbot [Skip to main content](https://docs.molt.bot/gateway/openresponses-http-api#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [OpenResponses API (HTTP)](https://docs.molt.bot/gateway/openresponses-http-api#openresponses-api-http) * [Authentication](https://docs.molt.bot/gateway/openresponses-http-api#authentication) * [Choosing an agent](https://docs.molt.bot/gateway/openresponses-http-api#choosing-an-agent) * [Enabling the endpoint](https://docs.molt.bot/gateway/openresponses-http-api#enabling-the-endpoint) * [Disabling the endpoint](https://docs.molt.bot/gateway/openresponses-http-api#disabling-the-endpoint) * [Session behavior](https://docs.molt.bot/gateway/openresponses-http-api#session-behavior) * [Request shape (supported)](https://docs.molt.bot/gateway/openresponses-http-api#request-shape-supported) * [Items (input)](https://docs.molt.bot/gateway/openresponses-http-api#items-input) * [message](https://docs.molt.bot/gateway/openresponses-http-api#message) * [function\_call\_output (turn-based tools)](https://docs.molt.bot/gateway/openresponses-http-api#function_call_output-turn-based-tools) * [reasoning and item\_reference](https://docs.molt.bot/gateway/openresponses-http-api#reasoning-and-item_reference) * [Tools (client-side function tools)](https://docs.molt.bot/gateway/openresponses-http-api#tools-client-side-function-tools) * [Images (input\_image)](https://docs.molt.bot/gateway/openresponses-http-api#images-input_image) * [Files (input\_file)](https://docs.molt.bot/gateway/openresponses-http-api#files-input_file) * [File + image limits (config)](https://docs.molt.bot/gateway/openresponses-http-api#file-%2B-image-limits-config) * [Streaming (SSE)](https://docs.molt.bot/gateway/openresponses-http-api#streaming-sse) * [Usage](https://docs.molt.bot/gateway/openresponses-http-api#usage) * [Errors](https://docs.molt.bot/gateway/openresponses-http-api#errors) * [Examples](https://docs.molt.bot/gateway/openresponses-http-api#examples) [​](https://docs.molt.bot/gateway/openresponses-http-api#openresponses-api-http) OpenResponses API (HTTP) ============================================================================================================ Moltbot’s Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint. This endpoint is **disabled by default**. Enable it in config first. * `POST /v1/responses` * Same port as the Gateway (WS + HTTP multiplex): `http://:/v1/responses` Under the hood, requests are executed as a normal Gateway agent run (same codepath as `moltbot agent`), so routing/permissions/config match your Gateway. [​](https://docs.molt.bot/gateway/openresponses-http-api#authentication) Authentication ------------------------------------------------------------------------------------------ Uses the Gateway auth configuration. Send a bearer token: * `Authorization: Bearer ` Notes: * When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `CLAWDBOT_GATEWAY_TOKEN`). * When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `CLAWDBOT_GATEWAY_PASSWORD`). [​](https://docs.molt.bot/gateway/openresponses-http-api#choosing-an-agent) Choosing an agent ------------------------------------------------------------------------------------------------ No custom headers required: encode the agent id in the OpenResponses `model` field: * `model: "moltbot:"` (example: `"moltbot:main"`, `"moltbot:beta"`) * `model: "agent:"` (alias) Or target a specific Moltbot agent by header: * `x-moltbot-agent-id: ` (default: `main`) Advanced: * `x-moltbot-session-key: ` to fully control session routing. [​](https://docs.molt.bot/gateway/openresponses-http-api#enabling-the-endpoint) Enabling the endpoint -------------------------------------------------------------------------------------------------------- Set `gateway.http.endpoints.responses.enabled` to `true`: Copy { gateway: { http: { endpoints: { responses: { enabled: true } } } } } [​](https://docs.molt.bot/gateway/openresponses-http-api#disabling-the-endpoint) Disabling the endpoint ---------------------------------------------------------------------------------------------------------- Set `gateway.http.endpoints.responses.enabled` to `false`: Copy { gateway: { http: { endpoints: { responses: { enabled: false } } } } } [​](https://docs.molt.bot/gateway/openresponses-http-api#session-behavior) Session behavior ---------------------------------------------------------------------------------------------- By default the endpoint is **stateless per request** (a new session key is generated each call). If the request includes an OpenResponses `user` string, the Gateway derives a stable session key from it, so repeated calls can share an agent session. [​](https://docs.molt.bot/gateway/openresponses-http-api#request-shape-supported) Request shape (supported) -------------------------------------------------------------------------------------------------------------- The request follows the OpenResponses API with item-based input. Current support: * `input`: string or array of item objects. * `instructions`: merged into the system prompt. * `tools`: client tool definitions (function tools). * `tool_choice`: filter or require client tools. * `stream`: enables SSE streaming. * `max_output_tokens`: best-effort output limit (provider dependent). * `user`: stable session routing. Accepted but **currently ignored**: * `max_tool_calls` * `reasoning` * `metadata` * `store` * `previous_response_id` * `truncation` [​](https://docs.molt.bot/gateway/openresponses-http-api#items-input) Items (input) -------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/gateway/openresponses-http-api#message) `message` Roles: `system`, `developer`, `user`, `assistant`. * `system` and `developer` are appended to the system prompt. * The most recent `user` or `function_call_output` item becomes the “current message.” * Earlier user/assistant messages are included as history for context. ### [​](https://docs.molt.bot/gateway/openresponses-http-api#function_call_output-turn-based-tools) `function_call_output` (turn-based tools) Send tool results back to the model: Copy { "type": "function_call_output", "call_id": "call_123", "output": "{\"temperature\": \"72F\"}" } ### [​](https://docs.molt.bot/gateway/openresponses-http-api#reasoning-and-item_reference) `reasoning` and `item_reference` Accepted for schema compatibility but ignored when building the prompt. [​](https://docs.molt.bot/gateway/openresponses-http-api#tools-client-side-function-tools) Tools (client-side function tools) -------------------------------------------------------------------------------------------------------------------------------- Provide tools with `tools: [{ type: "function", function: { name, description?, parameters? } }]`. If the agent decides to call a tool, the response returns a `function_call` output item. You then send a follow-up request with `function_call_output` to continue the turn. [​](https://docs.molt.bot/gateway/openresponses-http-api#images-input_image) Images (`input_image`) ------------------------------------------------------------------------------------------------------ Supports base64 or URL sources: Copy { "type": "input_image", "source": { "type": "url", "url": "https://example.com/image.png" } } Allowed MIME types (current): `image/jpeg`, `image/png`, `image/gif`, `image/webp`. Max size (current): 10MB. [​](https://docs.molt.bot/gateway/openresponses-http-api#files-input_file) Files (`input_file`) -------------------------------------------------------------------------------------------------- Supports base64 or URL sources: Copy { "type": "input_file", "source": { "type": "base64", "media_type": "text/plain", "data": "SGVsbG8gV29ybGQh", "filename": "hello.txt" } } Allowed MIME types (current): `text/plain`, `text/markdown`, `text/html`, `text/csv`, `application/json`, `application/pdf`. Max size (current): 5MB. Current behavior: * File content is decoded and added to the **system prompt**, not the user message, so it stays ephemeral (not persisted in session history). * PDFs are parsed for text. If little text is found, the first pages are rasterized into images and passed to the model. PDF parsing uses the Node-friendly `pdfjs-dist` legacy build (no worker). The modern PDF.js build expects browser workers/DOM globals, so it is not used in the Gateway. URL fetch defaults: * `files.allowUrl`: `true` * `images.allowUrl`: `true` * Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts). [​](https://docs.molt.bot/gateway/openresponses-http-api#file-+-image-limits-config) File + image limits (config) -------------------------------------------------------------------------------------------------------------------- Defaults can be tuned under `gateway.http.endpoints.responses`: Copy { gateway: { http: { endpoints: { responses: { enabled: true, maxBodyBytes: 20000000, files: { allowUrl: true, allowedMimes: ["text/plain", "text/markdown", "text/html", "text/csv", "application/json", "application/pdf"], maxBytes: 5242880, maxChars: 200000, maxRedirects: 3, timeoutMs: 10000, pdf: { maxPages: 4, maxPixels: 4000000, minTextChars: 200 } }, images: { allowUrl: true, allowedMimes: ["image/jpeg", "image/png", "image/gif", "image/webp"], maxBytes: 10485760, maxRedirects: 3, timeoutMs: 10000 } } } } } } Defaults when omitted: * `maxBodyBytes`: 20MB * `files.maxBytes`: 5MB * `files.maxChars`: 200k * `files.maxRedirects`: 3 * `files.timeoutMs`: 10s * `files.pdf.maxPages`: 4 * `files.pdf.maxPixels`: 4,000,000 * `files.pdf.minTextChars`: 200 * `images.maxBytes`: 10MB * `images.maxRedirects`: 3 * `images.timeoutMs`: 10s [​](https://docs.molt.bot/gateway/openresponses-http-api#streaming-sse) Streaming (SSE) ------------------------------------------------------------------------------------------ Set `stream: true` to receive Server-Sent Events (SSE): * `Content-Type: text/event-stream` * Each event line is `event: ` and `data: ` * Stream ends with `data: [DONE]` Event types currently emitted: * `response.created` * `response.in_progress` * `response.output_item.added` * `response.content_part.added` * `response.output_text.delta` * `response.output_text.done` * `response.content_part.done` * `response.output_item.done` * `response.completed` * `response.failed` (on error) [​](https://docs.molt.bot/gateway/openresponses-http-api#usage) Usage ------------------------------------------------------------------------ `usage` is populated when the underlying provider reports token counts. [​](https://docs.molt.bot/gateway/openresponses-http-api#errors) Errors -------------------------------------------------------------------------- Errors use a JSON object like: Copy { "error": { "message": "...", "type": "invalid_request_error" } } Common cases: * `401` missing/invalid auth * `400` invalid request body * `405` wrong method [​](https://docs.molt.bot/gateway/openresponses-http-api#examples) Examples ------------------------------------------------------------------------------ Non-streaming: Copy curl -sS http://127.0.0.1:18789/v1/responses \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -H 'x-moltbot-agent-id: main' \ -d '{ "model": "moltbot", "input": "hi" }' Streaming: Copy curl -N http://127.0.0.1:18789/v1/responses \ -H 'Authorization: Bearer YOUR_TOKEN' \ -H 'Content-Type: application/json' \ -H 'x-moltbot-agent-id: main' \ -d '{ "model": "moltbot", "stream": true, "input": "hi" }' ⌘I --- # Tts - Moltbot [Skip to main content](https://docs.molt.bot/tts#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Text-to-speech (TTS)](https://docs.molt.bot/tts#text-to-speech-tts) * [Supported services](https://docs.molt.bot/tts#supported-services) * [Edge TTS notes](https://docs.molt.bot/tts#edge-tts-notes) * [Optional keys](https://docs.molt.bot/tts#optional-keys) * [Service links](https://docs.molt.bot/tts#service-links) * [Is it enabled by default?](https://docs.molt.bot/tts#is-it-enabled-by-default) * [Config](https://docs.molt.bot/tts#config) * [Minimal config (enable + provider)](https://docs.molt.bot/tts#minimal-config-enable-%2B-provider) * [OpenAI primary with ElevenLabs fallback](https://docs.molt.bot/tts#openai-primary-with-elevenlabs-fallback) * [Edge TTS primary (no API key)](https://docs.molt.bot/tts#edge-tts-primary-no-api-key) * [Disable Edge TTS](https://docs.molt.bot/tts#disable-edge-tts) * [Custom limits + prefs path](https://docs.molt.bot/tts#custom-limits-%2B-prefs-path) * [Only reply with audio after an inbound voice note](https://docs.molt.bot/tts#only-reply-with-audio-after-an-inbound-voice-note) * [Disable auto-summary for long replies](https://docs.molt.bot/tts#disable-auto-summary-for-long-replies) * [Notes on fields](https://docs.molt.bot/tts#notes-on-fields) * [Model-driven overrides (default on)](https://docs.molt.bot/tts#model-driven-overrides-default-on) * [Per-user preferences](https://docs.molt.bot/tts#per-user-preferences) * [Output formats (fixed)](https://docs.molt.bot/tts#output-formats-fixed) * [Auto-TTS behavior](https://docs.molt.bot/tts#auto-tts-behavior) * [Flow diagram](https://docs.molt.bot/tts#flow-diagram) * [Slash command usage](https://docs.molt.bot/tts#slash-command-usage) * [Agent tool](https://docs.molt.bot/tts#agent-tool) * [Gateway RPC](https://docs.molt.bot/tts#gateway-rpc) [​](https://docs.molt.bot/tts#text-to-speech-tts) Text-to-speech (TTS) ========================================================================= Moltbot can convert outbound replies into audio using ElevenLabs, OpenAI, or Edge TTS. It works anywhere Moltbot can send audio; Telegram gets a round voice-note bubble. [​](https://docs.molt.bot/tts#supported-services) Supported services ----------------------------------------------------------------------- * **ElevenLabs** (primary or fallback provider) * **OpenAI** (primary or fallback provider; also used for summaries) * **Edge TTS** (primary or fallback provider; uses `node-edge-tts`, default when no API keys) ### [​](https://docs.molt.bot/tts#edge-tts-notes) Edge TTS notes Edge TTS uses Microsoft Edge’s online neural TTS service via the `node-edge-tts` library. It’s a hosted service (not local), uses Microsoft’s endpoints, and does not require an API key. `node-edge-tts` exposes speech configuration options and output formats, but not all options are supported by the Edge service. citeturn2search0 Because Edge TTS is a public web service without a published SLA or quota, treat it as best-effort. If you need guaranteed limits and support, use OpenAI or ElevenLabs. Microsoft’s Speech REST API documents a 10‑minute audio limit per request; Edge TTS does not publish limits, so assume similar or lower limits. citeturn0search3 [​](https://docs.molt.bot/tts#optional-keys) Optional keys ------------------------------------------------------------- If you want OpenAI or ElevenLabs: * `ELEVENLABS_API_KEY` (or `XI_API_KEY`) * `OPENAI_API_KEY` Edge TTS does **not** require an API key. If no API keys are found, Moltbot defaults to Edge TTS (unless disabled via `messages.tts.edge.enabled=false`). If multiple providers are configured, the selected provider is used first and the others are fallback options. Auto-summary uses the configured `summaryModel` (or `agents.defaults.model.primary`), so that provider must also be authenticated if you enable summaries. [​](https://docs.molt.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) * [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) * [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) [​](https://docs.molt.bot/tts#is-it-enabled-by-default) Is it enabled by default? ------------------------------------------------------------------------------------ No. Auto‑TTS is **off** by default. Enable it in config with `messages.tts.auto` or per session with `/tts always` (alias: `/tts on`). Edge TTS **is** enabled by default once TTS is on, and is used automatically when no OpenAI or ElevenLabs API keys are available. [​](https://docs.molt.bot/tts#config) Config ----------------------------------------------- TTS config lives under `messages.tts` in `moltbot.json`. Full schema is in [Gateway configuration](https://docs.molt.bot/gateway/configuration) . ### [​](https://docs.molt.bot/tts#minimal-config-enable-+-provider) Minimal config (enable + provider) Copy { messages: { tts: { auto: "always", provider: "elevenlabs" } } } ### [​](https://docs.molt.bot/tts#openai-primary-with-elevenlabs-fallback) OpenAI primary with ElevenLabs fallback Copy { messages: { tts: { auto: "always", 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.molt.bot/tts#edge-tts-primary-no-api-key) Edge TTS primary (no API key) Copy { messages: { tts: { auto: "always", provider: "edge", edge: { enabled: true, voice: "en-US-MichelleNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", rate: "+10%", pitch: "-5%" } } } } ### [​](https://docs.molt.bot/tts#disable-edge-tts) Disable Edge TTS Copy { messages: { tts: { edge: { enabled: false } } } } ### [​](https://docs.molt.bot/tts#custom-limits-+-prefs-path) Custom limits + prefs path Copy { messages: { tts: { auto: "always", maxTextLength: 4000, timeoutMs: 30000, prefsPath: "~/.clawdbot/settings/tts.json" } } } ### [​](https://docs.molt.bot/tts#only-reply-with-audio-after-an-inbound-voice-note) Only reply with audio after an inbound voice note Copy { messages: { tts: { auto: "inbound" } } } ### [​](https://docs.molt.bot/tts#disable-auto-summary-for-long-replies) Disable auto-summary for long replies Copy { messages: { tts: { auto: "always" } } } Then run: Copy /tts summary off ### [​](https://docs.molt.bot/tts#notes-on-fields) Notes on fields * `auto`: auto‑TTS mode (`off`, `always`, `inbound`, `tagged`). * `inbound` only sends audio after an inbound voice note. * `tagged` only sends audio when the reply includes `[[tts]]` tags. * `enabled`: legacy toggle (doctor migrates this to `auto`). * `mode`: `"final"` (default) or `"all"` (includes tool/block replies). * `provider`: `"elevenlabs"`, `"openai"`, or `"edge"` (fallback is automatic). * If `provider` is **unset**, Moltbot prefers `openai` (if key), then `elevenlabs` (if key), otherwise `edge`. * `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 (provider/limit/summary). * `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) * `edge.enabled`: allow Edge TTS usage (default `true`; no API key). * `edge.voice`: Edge neural voice name (e.g. `en-US-MichelleNeural`). * `edge.lang`: language code (e.g. `en-US`). * `edge.outputFormat`: Edge output format (e.g. `audio-24khz-48kbitrate-mono-mp3`). * See Microsoft Speech output formats for valid values; not all formats are supported by Edge. * `edge.rate` / `edge.pitch` / `edge.volume`: percent strings (e.g. `+10%`, `-5%`). * `edge.saveSubtitles`: write JSON subtitles alongside the audio file. * `edge.proxy`: proxy URL for Edge TTS requests. * `edge.timeoutMs`: request timeout override (ms). [​](https://docs.molt.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 `messages.tts.auto` is `tagged`, these directives are required to trigger audio. 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` | `edge`) * `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.molt.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.molt.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. * **Edge TTS**: uses `edge.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`). * `node-edge-tts` accepts an `outputFormat`, but not all formats are available from the Edge service. citeturn2search0 * Output format values follow Microsoft Speech output formats (including Ogg/WebM Opus). citeturn1search0 * Telegram `sendVoice` accepts OGG/MP3/M4A; use OpenAI/ElevenLabs if you need guaranteed Opus voice notes. citeturn1search1 * If the configured Edge output format fails, Moltbot retries with MP3. OpenAI/ElevenLabs formats are fixed; Telegram expects Opus for voice-note UX. [​](https://docs.molt.bot/tts#auto-tts-behavior) Auto-TTS behavior --------------------------------------------------------------------- When enabled, Moltbot: * 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.molt.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.molt.bot/tts#slash-command-usage) Slash command usage ------------------------------------------------------------------------- There is a single command: `/tts`. See [Slash commands](https://docs.molt.bot/tools/slash-commands) for enablement details. Discord note: `/tts` is a built-in Discord command, so Moltbot registers `/voice` as the native command there. Text `/tts ...` still works. Copy /tts off /tts always /tts inbound /tts tagged /tts status /tts provider openai /tts limit 2000 /tts summary off /tts audio Hello from Moltbot Notes: * Commands require an authorized sender (allowlist/owner rules still apply). * `commands.text` or native command registration must be enabled. * `off|always|inbound|tagged` are per‑session toggles (`/tts on` is an alias for `/tts always`). * `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.molt.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.molt.bot/tts#gateway-rpc) Gateway RPC --------------------------------------------------------- Gateway methods: * `tts.status` * `tts.enable` * `tts.disable` * `tts.convert` * `tts.setProvider` * `tts.providers` ⌘I --- # Perplexity - Moltbot [Skip to main content](https://docs.molt.bot/perplexity#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Perplexity Sonar](https://docs.molt.bot/perplexity#perplexity-sonar) * [API options](https://docs.molt.bot/perplexity#api-options) * [Perplexity (direct)](https://docs.molt.bot/perplexity#perplexity-direct) * [OpenRouter (alternative)](https://docs.molt.bot/perplexity#openrouter-alternative) * [Config example](https://docs.molt.bot/perplexity#config-example) * [Switching from Brave](https://docs.molt.bot/perplexity#switching-from-brave) * [Models](https://docs.molt.bot/perplexity#models) [​](https://docs.molt.bot/perplexity#perplexity-sonar) Perplexity Sonar ========================================================================== Moltbot can use Perplexity Sonar for the `web_search` tool. You can connect through Perplexity’s direct API or via OpenRouter. [​](https://docs.molt.bot/perplexity#api-options) API options ---------------------------------------------------------------- ### [​](https://docs.molt.bot/perplexity#perplexity-direct) Perplexity (direct) * Base URL: [https://api.perplexity.ai](https://api.perplexity.ai/) * Environment variable: `PERPLEXITY_API_KEY` ### [​](https://docs.molt.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.molt.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.molt.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, Moltbot 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.molt.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.molt.bot/tools/web) for the full web\_search configuration. ⌘I --- # Group policy hardening - Moltbot [Skip to main content](https://docs.molt.bot/experiments/plans/group-policy-hardening#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Telegram Allowlist Hardening](https://docs.molt.bot/experiments/plans/group-policy-hardening#telegram-allowlist-hardening) * [Summary](https://docs.molt.bot/experiments/plans/group-policy-hardening#summary) * [What changed](https://docs.molt.bot/experiments/plans/group-policy-hardening#what-changed) * [Examples](https://docs.molt.bot/experiments/plans/group-policy-hardening#examples) * [Why it matters](https://docs.molt.bot/experiments/plans/group-policy-hardening#why-it-matters) * [Related docs](https://docs.molt.bot/experiments/plans/group-policy-hardening#related-docs) [​](https://docs.molt.bot/experiments/plans/group-policy-hardening#telegram-allowlist-hardening) Telegram Allowlist Hardening ================================================================================================================================ **Date**: 2026-01-05 **Status**: Complete **PR**: #216 [​](https://docs.molt.bot/experiments/plans/group-policy-hardening#summary) Summary -------------------------------------------------------------------------------------- Telegram allowlists now accept `telegram:` and `tg:` prefixes case-insensitively, and tolerate accidental whitespace. This aligns inbound allowlist checks with outbound send normalization. [​](https://docs.molt.bot/experiments/plans/group-policy-hardening#what-changed) What changed ------------------------------------------------------------------------------------------------ * Prefixes `telegram:` and `tg:` are treated the same (case-insensitive). * Allowlist entries are trimmed; empty entries are ignored. [​](https://docs.molt.bot/experiments/plans/group-policy-hardening#examples) Examples ---------------------------------------------------------------------------------------- All of these are accepted for the same ID: * `telegram:123456` * `TG:123456` * `tg:123456` [​](https://docs.molt.bot/experiments/plans/group-policy-hardening#why-it-matters) Why it matters ---------------------------------------------------------------------------------------------------- Copy/paste from logs or chat IDs often includes prefixes and whitespace. Normalizing avoids false negatives when deciding whether to respond in DMs or groups. [​](https://docs.molt.bot/experiments/plans/group-policy-hardening#related-docs) Related docs ------------------------------------------------------------------------------------------------ * [Group Chats](https://docs.molt.bot/concepts/groups) * [Telegram Provider](https://docs.molt.bot/channels/telegram) ⌘I --- # Firecrawl - Moltbot [Skip to main content](https://docs.molt.bot/tools/firecrawl#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Firecrawl](https://docs.molt.bot/tools/firecrawl#firecrawl) * [Get an API key](https://docs.molt.bot/tools/firecrawl#get-an-api-key) * [Configure Firecrawl](https://docs.molt.bot/tools/firecrawl#configure-firecrawl) * [Stealth / bot circumvention](https://docs.molt.bot/tools/firecrawl#stealth-%2F-bot-circumvention) * [How web\_fetch uses Firecrawl](https://docs.molt.bot/tools/firecrawl#how-web_fetch-uses-firecrawl) [​](https://docs.molt.bot/tools/firecrawl#firecrawl) Firecrawl ================================================================= Moltbot 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.molt.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.molt.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.molt.bot/tools/firecrawl#stealth-/-bot-circumvention) Stealth / bot circumvention ----------------------------------------------------------------------------------------------------- Firecrawl exposes a **proxy mode** parameter for bot circumvention (`basic`, `stealth`, or `auto`). Moltbot 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.molt.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.molt.bot/tools/web) for the full web tool setup. ⌘I --- # Webhooks - Moltbot [Skip to main content](https://docs.molt.bot/cli/webhooks#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [moltbot webhooks](https://docs.molt.bot/cli/webhooks#moltbot-webhooks) * [Gmail](https://docs.molt.bot/cli/webhooks#gmail) [​](https://docs.molt.bot/cli/webhooks#moltbot-webhooks) `moltbot webhooks` ============================================================================== Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers). Related: * Webhooks: [Webhook](https://docs.molt.bot/automation/webhook) * Gmail Pub/Sub: [Gmail Pub/Sub](https://docs.molt.bot/automation/gmail-pubsub) [​](https://docs.molt.bot/cli/webhooks#gmail) Gmail ------------------------------------------------------ Copy moltbot webhooks gmail setup --account [email protected] moltbot webhooks gmail run See [Gmail Pub/Sub documentation](https://docs.molt.bot/automation/gmail-pubsub) for details. ⌘I --- # Model config - Moltbot [Skip to main content](https://docs.molt.bot/experiments/proposals/model-config#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Model Config (Exploration)](https://docs.molt.bot/experiments/proposals/model-config#model-config-exploration) * [Motivation](https://docs.molt.bot/experiments/proposals/model-config#motivation) * [Possible direction (high level)](https://docs.molt.bot/experiments/proposals/model-config#possible-direction-high-level) * [Open questions](https://docs.molt.bot/experiments/proposals/model-config#open-questions) [​](https://docs.molt.bot/experiments/proposals/model-config#model-config-exploration) Model Config (Exploration) ==================================================================================================================== This document captures **ideas** for future model configuration. It is not a shipping spec. For current behavior, see: * [Models](https://docs.molt.bot/concepts/models) * [Model failover](https://docs.molt.bot/concepts/model-failover) * [OAuth + profiles](https://docs.molt.bot/concepts/oauth) [​](https://docs.molt.bot/experiments/proposals/model-config#motivation) Motivation -------------------------------------------------------------------------------------- Operators want: * Multiple auth profiles per provider (personal vs work). * Simple `/model` selection with predictable fallbacks. * Clear separation between text models and image-capable models. [​](https://docs.molt.bot/experiments/proposals/model-config#possible-direction-high-level) Possible direction (high level) ------------------------------------------------------------------------------------------------------------------------------ * Keep model selection simple: `provider/model` with optional aliases. * Let providers have multiple auth profiles, with an explicit order. * Use a global fallback list so all sessions fail over consistently. * Only override image routing when explicitly configured. [​](https://docs.molt.bot/experiments/proposals/model-config#open-questions) Open questions ---------------------------------------------------------------------------------------------- * Should profile rotation be per-provider or per-model? * How should the UI surface profile selection for a session? * What is the safest migration path from legacy config keys? ⌘I --- # Onboarding config protocol - Moltbot [Skip to main content](https://docs.molt.bot/experiments/onboarding-config-protocol#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Onboarding + Config Protocol](https://docs.molt.bot/experiments/onboarding-config-protocol#onboarding-%2B-config-protocol) * [Components](https://docs.molt.bot/experiments/onboarding-config-protocol#components) * [Gateway RPC](https://docs.molt.bot/experiments/onboarding-config-protocol#gateway-rpc) * [UI Hints](https://docs.molt.bot/experiments/onboarding-config-protocol#ui-hints) * [Notes](https://docs.molt.bot/experiments/onboarding-config-protocol#notes) [​](https://docs.molt.bot/experiments/onboarding-config-protocol#onboarding-+-config-protocol) Onboarding + Config Protocol ============================================================================================================================== Purpose: shared onboarding + config surfaces across CLI, macOS app, and Web UI. [​](https://docs.molt.bot/experiments/onboarding-config-protocol#components) Components ------------------------------------------------------------------------------------------ * Wizard engine (shared session + prompts + onboarding state). * CLI onboarding uses the same wizard flow as the UI clients. * Gateway RPC exposes wizard + config schema endpoints. * macOS onboarding uses the wizard step model. * Web UI renders config forms from JSON Schema + UI hints. [​](https://docs.molt.bot/experiments/onboarding-config-protocol#gateway-rpc) Gateway RPC -------------------------------------------------------------------------------------------- * `wizard.start` params: `{ mode?: "local"|"remote", workspace?: string }` * `wizard.next` params: `{ sessionId, answer?: { stepId, value? } }` * `wizard.cancel` params: `{ sessionId }` * `wizard.status` params: `{ sessionId }` * `config.schema` params: `{}` Responses (shape) * Wizard: `{ sessionId, done, step?, status?, error? }` * Config schema: `{ schema, uiHints, version, generatedAt }` [​](https://docs.molt.bot/experiments/onboarding-config-protocol#ui-hints) UI Hints -------------------------------------------------------------------------------------- * `uiHints` keyed by path; optional metadata (label/help/group/order/advanced/sensitive/placeholder). * Sensitive fields render as password inputs; no redaction layer. * Unsupported schema nodes fall back to the raw JSON editor. [​](https://docs.molt.bot/experiments/onboarding-config-protocol#notes) Notes -------------------------------------------------------------------------------- * This doc is the single place to track protocol refactors for onboarding/config. ⌘I --- # Cron add hardening - Moltbot [Skip to main content](https://docs.molt.bot/experiments/plans/cron-add-hardening#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Cron Add Hardening & Schema Alignment](https://docs.molt.bot/experiments/plans/cron-add-hardening#cron-add-hardening-%26-schema-alignment) * [Context](https://docs.molt.bot/experiments/plans/cron-add-hardening#context) * [Goals](https://docs.molt.bot/experiments/plans/cron-add-hardening#goals) * [Non-goals](https://docs.molt.bot/experiments/plans/cron-add-hardening#non-goals) * [Findings (current gaps)](https://docs.molt.bot/experiments/plans/cron-add-hardening#findings-current-gaps) * [What changed](https://docs.molt.bot/experiments/plans/cron-add-hardening#what-changed) * [Current behavior](https://docs.molt.bot/experiments/plans/cron-add-hardening#current-behavior) * [Verification](https://docs.molt.bot/experiments/plans/cron-add-hardening#verification) * [Optional Follow-ups](https://docs.molt.bot/experiments/plans/cron-add-hardening#optional-follow-ups) * [Open Questions](https://docs.molt.bot/experiments/plans/cron-add-hardening#open-questions) [​](https://docs.molt.bot/experiments/plans/cron-add-hardening#cron-add-hardening-&-schema-alignment) Cron Add Hardening & Schema Alignment ============================================================================================================================================== [​](https://docs.molt.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.molt.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.molt.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.molt.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.molt.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.molt.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.molt.bot/automation/cron-jobs) for the normalized shape and examples. [​](https://docs.molt.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.molt.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.molt.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)? ⌘I --- # Memory - Moltbot [Skip to main content](https://docs.molt.bot/experiments/research/memory#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Workspace Memory v2 (offline): research notes](https://docs.molt.bot/experiments/research/memory#workspace-memory-v2-offline-%3A-research-notes) * [Why change?](https://docs.molt.bot/experiments/research/memory#why-change) * [Design goals](https://docs.molt.bot/experiments/research/memory#design-goals) * [North star model (Hindsight × Letta)](https://docs.molt.bot/experiments/research/memory#north-star-model-hindsight-%C3%97-letta) * [Proposed architecture (Markdown source-of-truth + derived index)](https://docs.molt.bot/experiments/research/memory#proposed-architecture-markdown-source-of-truth-%2B-derived-index) * [Canonical store (git-friendly)](https://docs.molt.bot/experiments/research/memory#canonical-store-git-friendly) * [Derived store (machine recall)](https://docs.molt.bot/experiments/research/memory#derived-store-machine-recall) * [Retain / Recall / Reflect (operational loop)](https://docs.molt.bot/experiments/research/memory#retain-%2F-recall-%2F-reflect-operational-loop) * [Retain: normalize daily logs into “facts”](https://docs.molt.bot/experiments/research/memory#retain%3A-normalize-daily-logs-into-%E2%80%9Cfacts%E2%80%9D) * [Recall: queries over the derived index](https://docs.molt.bot/experiments/research/memory#recall%3A-queries-over-the-derived-index) * [Reflect: produce stable pages + update beliefs](https://docs.molt.bot/experiments/research/memory#reflect%3A-produce-stable-pages-%2B-update-beliefs) * [CLI integration: standalone vs deep integration](https://docs.molt.bot/experiments/research/memory#cli-integration%3A-standalone-vs-deep-integration) * [Why integrate into Moltbot?](https://docs.molt.bot/experiments/research/memory#why-integrate-into-moltbot) * [Why still split a library?](https://docs.molt.bot/experiments/research/memory#why-still-split-a-library) * [“S-Collide” / SuCo: when to use it (research)](https://docs.molt.bot/experiments/research/memory#%E2%80%9Cs-collide%E2%80%9D-%2F-suco%3A-when-to-use-it-research) * [Smallest useful pilot](https://docs.molt.bot/experiments/research/memory#smallest-useful-pilot) * [References](https://docs.molt.bot/experiments/research/memory#references) [​](https://docs.molt.bot/experiments/research/memory#workspace-memory-v2-offline-:-research-notes) Workspace Memory v2 (offline): research notes ==================================================================================================================================================== Target: Clawd-style workspace (`agents.defaults.workspace`, default `~/clawd`) where “memory” is stored as one Markdown file per day (`memory/YYYY-MM-DD.md`) plus a small set of stable files (e.g. `memory.md`, `SOUL.md`). This doc proposes an **offline-first** memory architecture that keeps Markdown as the canonical, reviewable source of truth, but adds **structured recall** (search, entity summaries, confidence updates) via a derived index. [​](https://docs.molt.bot/experiments/research/memory#why-change) Why change? -------------------------------------------------------------------------------- The current setup (one file per day) is excellent for: * “append-only” journaling * human editing * git-backed durability + auditability * low-friction capture (“just write it down”) It’s weak for: * high-recall retrieval (“what did we decide about X?”, “last time we tried Y?”) * entity-centric answers (“tell me about Alice / The Castle / warelay”) without rereading many files * opinion/preference stability (and evidence when it changes) * time constraints (“what was true during Nov 2025?”) and conflict resolution [​](https://docs.molt.bot/experiments/research/memory#design-goals) Design goals ----------------------------------------------------------------------------------- * **Offline**: works without network; can run on laptop/Castle; no cloud dependency. * **Explainable**: retrieved items should be attributable (file + location) and separable from inference. * **Low ceremony**: daily logging stays Markdown, no heavy schema work. * **Incremental**: v1 is useful with FTS only; semantic/vector and graphs are optional upgrades. * **Agent-friendly**: makes “recall within token budgets” easy (return small bundles of facts). [​](https://docs.molt.bot/experiments/research/memory#north-star-model-hindsight-%C3%97-letta) North star model (Hindsight × Letta) -------------------------------------------------------------------------------------------------------------------------------------- Two pieces to blend: 1. **Letta/MemGPT-style control loop** * keep a small “core” always in context (persona + key user facts) * everything else is out-of-context and retrieved via tools * memory writes are explicit tool calls (append/replace/insert), persisted, then re-injected next turn 2. **Hindsight-style memory substrate** * separate what’s observed vs what’s believed vs what’s summarized * support retain/recall/reflect * confidence-bearing opinions that can evolve with evidence * entity-aware retrieval + temporal queries (even without full knowledge graphs) [​](https://docs.molt.bot/experiments/research/memory#proposed-architecture-markdown-source-of-truth-+-derived-index) Proposed architecture (Markdown source-of-truth + derived index) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/experiments/research/memory#canonical-store-git-friendly) Canonical store (git-friendly) Keep `~/clawd` as canonical human-readable memory. Suggested workspace layout: Copy ~/clawd/ memory.md # small: durable facts + preferences (core-ish) memory/ YYYY-MM-DD.md # daily log (append; narrative) bank/ # “typed” memory pages (stable, reviewable) world.md # objective facts about the world experience.md # what the agent did (first-person) opinions.md # subjective prefs/judgments + confidence + evidence pointers entities/ Peter.md The-Castle.md warelay.md ... Notes: * **Daily log stays daily log**. No need to turn it into JSON. * The `bank/` files are **curated**, produced by reflection jobs, and can still be edited by hand. * `memory.md` remains “small + core-ish”: the things you want Clawd to see every session. ### [​](https://docs.molt.bot/experiments/research/memory#derived-store-machine-recall) Derived store (machine recall) Add a derived index under the workspace (not necessarily git tracked): Copy ~/clawd/.memory/index.sqlite Back it with: * SQLite schema for facts + entity links + opinion metadata * SQLite **FTS5** for lexical recall (fast, tiny, offline) * optional embeddings table for semantic recall (still offline) The index is always **rebuildable from Markdown**. [​](https://docs.molt.bot/experiments/research/memory#retain-/-recall-/-reflect-operational-loop) Retain / Recall / Reflect (operational loop) ------------------------------------------------------------------------------------------------------------------------------------------------- ### [​](https://docs.molt.bot/experiments/research/memory#retain:-normalize-daily-logs-into-%E2%80%9Cfacts%E2%80%9D) Retain: normalize daily logs into “facts” Hindsight’s key insight that matters here: store **narrative, self-contained facts**, not tiny snippets. Practical rule for `memory/YYYY-MM-DD.md`: * at end of day (or during), add a `## Retain` section with 2–5 bullets that are: * narrative (cross-turn context preserved) * self-contained (standalone makes sense later) * tagged with type + entity mentions Example: Copy ## Retain - W @Peter: Currently in Marrakech (Nov 27–Dec 1, 2025) for Andy’s birthday. - B @warelay: I fixed the Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md). - O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes into files. Minimal parsing: * Type prefix: `W` (world), `B` (experience/biographical), `O` (opinion), `S` (observation/summary; usually generated) * Entities: `@Peter`, `@warelay`, etc (slugs map to `bank/entities/*.md`) * Opinion confidence: `O(c=0.0..1.0)` optional If you don’t want authors to think about it: the reflect job can infer these bullets from the rest of the log, but having an explicit `## Retain` section is the easiest “quality lever”. ### [​](https://docs.molt.bot/experiments/research/memory#recall:-queries-over-the-derived-index) Recall: queries over the derived index Recall should support: * **lexical**: “find exact terms / names / commands” (FTS5) * **entity**: “tell me about X” (entity pages + entity-linked facts) * **temporal**: “what happened around Nov 27” / “since last week” * **opinion**: “what does Peter prefer?” (with confidence + evidence) Return format should be agent-friendly and cite sources: * `kind` (`world|experience|opinion|observation`) * `timestamp` (source day, or extracted time range if present) * `entities` (`["Peter","warelay"]`) * `content` (the narrative fact) * `source` (`memory/2025-11-27.md#L12` etc) ### [​](https://docs.molt.bot/experiments/research/memory#reflect:-produce-stable-pages-+-update-beliefs) Reflect: produce stable pages + update beliefs Reflection is a scheduled job (daily or heartbeat `ultrathink`) that: * updates `bank/entities/*.md` from recent facts (entity summaries) * updates `bank/opinions.md` confidence based on reinforcement/contradiction * optionally proposes edits to `memory.md` (“core-ish” durable facts) Opinion evolution (simple, explainable): * each opinion has: * statement * confidence `c ∈ [0,1]` * last\_updated * evidence links (supporting + contradicting fact IDs) * when new facts arrive: * find candidate opinions by entity overlap + similarity (FTS first, embeddings later) * update confidence by small deltas; big jumps require strong contradiction + repeated evidence [​](https://docs.molt.bot/experiments/research/memory#cli-integration:-standalone-vs-deep-integration) CLI integration: standalone vs deep integration --------------------------------------------------------------------------------------------------------------------------------------------------------- Recommendation: **deep integration in Moltbot**, but keep a separable core library. ### [​](https://docs.molt.bot/experiments/research/memory#why-integrate-into-moltbot) Why integrate into Moltbot? * Moltbot already knows: * the workspace path (`agents.defaults.workspace`) * the session model + heartbeats * logging + troubleshooting patterns * You want the agent itself to call the tools: * `moltbot memory recall "…" --k 25 --since 30d` * `moltbot memory reflect --since 7d` ### [​](https://docs.molt.bot/experiments/research/memory#why-still-split-a-library) Why still split a library? * keep memory logic testable without gateway/runtime * reuse from other contexts (local scripts, future desktop app, etc.) Shape: The memory tooling is intended to be a small CLI + library layer, but this is exploratory only. [​](https://docs.molt.bot/experiments/research/memory#%E2%80%9Cs-collide%E2%80%9D-/-suco:-when-to-use-it-research) “S-Collide” / SuCo: when to use it (research) ------------------------------------------------------------------------------------------------------------------------------------------------------------------- If “S-Collide” refers to **SuCo (Subspace Collision)**: it’s an ANN retrieval approach that targets strong recall/latency tradeoffs by using learned/structured collisions in subspaces (paper: arXiv 2411.14754, 2024). Pragmatic take for `~/clawd`: * **don’t start** with SuCo. * start with SQLite FTS + (optional) simple embeddings; you’ll get most UX wins immediately. * consider SuCo/HNSW/ScaNN-class solutions only once: * corpus is big (tens/hundreds of thousands of chunks) * brute-force embedding search becomes too slow * recall quality is meaningfully bottlenecked by lexical search Offline-friendly alternatives (in increasing complexity): * SQLite FTS5 + metadata filters (zero ML) * Embeddings + brute force (works surprisingly far if chunk count is low) * HNSW index (common, robust; needs a library binding) * SuCo (research-grade; attractive if there’s a solid implementation you can embed) Open question: * what’s the **best** offline embedding model for “personal assistant memory” on your machines (laptop + desktop)? * if you already have Ollama: embed with a local model; otherwise ship a small embedding model in the toolchain. [​](https://docs.molt.bot/experiments/research/memory#smallest-useful-pilot) Smallest useful pilot ----------------------------------------------------------------------------------------------------- If you want a minimal, still-useful version: * Add `bank/` entity pages and a `## Retain` section in daily logs. * Use SQLite FTS for recall with citations (path + line numbers). * Add embeddings only if recall quality or scale demands it. [​](https://docs.molt.bot/experiments/research/memory#references) References ------------------------------------------------------------------------------- * Letta / MemGPT concepts: “core memory blocks” + “archival memory” + tool-driven self-editing memory. * Hindsight Technical Report: “retain / recall / reflect”, four-network memory, narrative fact extraction, opinion confidence evolution. * SuCo: arXiv 2411.14754 (2024): “Subspace Collision” approximate nearest neighbor retrieval. ⌘I --- # Node - Moltbot [Skip to main content](https://docs.molt.bot/cli/node#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [moltbot node](https://docs.molt.bot/cli/node#moltbot-node) * [Why use a node host?](https://docs.molt.bot/cli/node#why-use-a-node-host) * [Browser proxy (zero-config)](https://docs.molt.bot/cli/node#browser-proxy-zero-config) * [Run (foreground)](https://docs.molt.bot/cli/node#run-foreground) * [Service (background)](https://docs.molt.bot/cli/node#service-background) * [Pairing](https://docs.molt.bot/cli/node#pairing) * [Exec approvals](https://docs.molt.bot/cli/node#exec-approvals) [​](https://docs.molt.bot/cli/node#moltbot-node) `moltbot node` ================================================================== Run a **headless node host** that connects to the Gateway WebSocket and exposes `system.run` / `system.which` on this machine. [​](https://docs.molt.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.molt.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.molt.bot/cli/node#run-foreground) Run (foreground) ---------------------------------------------------------------------- Copy moltbot 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.molt.bot/cli/node#service-background) Service (background) ------------------------------------------------------------------------------ Install a headless node host as a user service. Copy moltbot 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 moltbot node status moltbot node stop moltbot node restart moltbot node uninstall Use `moltbot node run` for a foreground node host (no service). Service commands accept `--json` for machine-readable output. [​](https://docs.molt.bot/cli/node#pairing) Pairing ------------------------------------------------------ The first connection creates a pending node pair request on the Gateway. Approve it via: Copy moltbot nodes pending moltbot nodes approve The node host stores its node id, token, display name, and gateway connection info in `~/.clawdbot/node.json`. [​](https://docs.molt.bot/cli/node#exec-approvals) Exec approvals -------------------------------------------------------------------- `system.run` is gated by local exec approvals: * `~/.clawdbot/exec-approvals.json` * [Exec approvals](https://docs.molt.bot/tools/exec-approvals) * `moltbot approvals --node ` (edit from the Gateway) ⌘I --- # Transcript hygiene - Moltbot [Skip to main content](https://docs.molt.bot/reference/transcript-hygiene#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Transcript Hygiene (Provider Fixups)](https://docs.molt.bot/reference/transcript-hygiene#transcript-hygiene-provider-fixups) * [Where this runs](https://docs.molt.bot/reference/transcript-hygiene#where-this-runs) * [Global rule: image sanitization](https://docs.molt.bot/reference/transcript-hygiene#global-rule%3A-image-sanitization) * [Provider matrix (current behavior)](https://docs.molt.bot/reference/transcript-hygiene#provider-matrix-current-behavior) * [Historical behavior (pre-2026.1.22)](https://docs.molt.bot/reference/transcript-hygiene#historical-behavior-pre-2026-1-22) [​](https://docs.molt.bot/reference/transcript-hygiene#transcript-hygiene-provider-fixups) Transcript Hygiene (Provider Fixups) ================================================================================================================================== This document describes **provider-specific fixes** applied to transcripts before a run (building model context). These are **in-memory** adjustments used to satisfy strict provider requirements. They do **not** rewrite the stored JSONL transcript on disk. Scope includes: * Tool call id sanitization * Tool result pairing repair * Turn validation / ordering * Thought signature cleanup * Image payload sanitization If you need transcript storage details, see: * [/reference/session-management-compaction](https://docs.molt.bot/reference/session-management-compaction) * * * [​](https://docs.molt.bot/reference/transcript-hygiene#where-this-runs) Where this runs ------------------------------------------------------------------------------------------ All transcript hygiene is centralized in the embedded runner: * Policy selection: `src/agents/transcript-policy.ts` * Sanitization/repair application: `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts` The policy uses `provider`, `modelApi`, and `modelId` to decide what to apply. * * * [​](https://docs.molt.bot/reference/transcript-hygiene#global-rule:-image-sanitization) Global rule: image sanitization -------------------------------------------------------------------------------------------------------------------------- Image payloads are always sanitized to prevent provider-side rejection due to size limits (downscale/recompress oversized base64 images). Implementation: * `sanitizeSessionMessagesImages` in `src/agents/pi-embedded-helpers/images.ts` * `sanitizeContentBlocksImages` in `src/agents/tool-images.ts` * * * [​](https://docs.molt.bot/reference/transcript-hygiene#provider-matrix-current-behavior) Provider matrix (current behavior) ------------------------------------------------------------------------------------------------------------------------------ **OpenAI / OpenAI Codex** * Image sanitization only. * On model switch into OpenAI Responses/Codex, drop orphaned reasoning signatures (standalone reasoning items without a following content block). * No tool call id sanitization. * No tool result pairing repair. * No turn validation or reordering. * No synthetic tool results. * No thought signature stripping. **Google (Generative AI / Gemini CLI / Antigravity)** * Tool call id sanitization: strict alphanumeric. * Tool result pairing repair and synthetic tool results. * Turn validation (Gemini-style turn alternation). * Google turn ordering fixup (prepend a tiny user bootstrap if history starts with assistant). * Antigravity Claude: normalize thinking signatures; drop unsigned thinking blocks. **Anthropic / Minimax (Anthropic-compatible)** * Tool result pairing repair and synthetic tool results. * Turn validation (merge consecutive user turns to satisfy strict alternation). **Mistral (including model-id based detection)** * Tool call id sanitization: strict9 (alphanumeric length 9). **OpenRouter Gemini** * Thought signature cleanup: strip non-base64 `thought_signature` values (keep base64). **Everything else** * Image sanitization only. * * * [​](https://docs.molt.bot/reference/transcript-hygiene#historical-behavior-pre-2026-1-22) Historical behavior (pre-2026.1.22) -------------------------------------------------------------------------------------------------------------------------------- Before the 2026.1.22 release, Moltbot applied multiple layers of transcript hygiene: * A **transcript-sanitize extension** ran on every context build and could: * Repair tool use/result pairing. * Sanitize tool call ids (including a non-strict mode that preserved `_`/`-`). * The runner also performed provider-specific sanitization, which duplicated work. * Additional mutations occurred outside the provider policy, including: * Stripping `` tags from assistant text before persistence. * Dropping empty assistant error turns. * Trimming assistant content after tool calls. This complexity caused cross-provider regressions (notably `openai-responses` `call_id|fc_id` pairing). The 2026.1.22 cleanup removed the extension, centralized logic in the runner, and made OpenAI **no-touch** beyond image sanitization. ⌘I --- # Network - Moltbot [Skip to main content](https://docs.molt.bot/network#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Network hub](https://docs.molt.bot/network#network-hub) * [Core model](https://docs.molt.bot/network#core-model) * [Pairing + identity](https://docs.molt.bot/network#pairing-%2B-identity) * [Discovery + transports](https://docs.molt.bot/network#discovery-%2B-transports) * [Nodes + transports](https://docs.molt.bot/network#nodes-%2B-transports) * [Security](https://docs.molt.bot/network#security) [​](https://docs.molt.bot/network#network-hub) Network hub ============================================================= This hub links the core docs for how Moltbot connects, pairs, and secures devices across localhost, LAN, and tailnet. [​](https://docs.molt.bot/network#core-model) Core model ----------------------------------------------------------- * [Gateway architecture](https://docs.molt.bot/concepts/architecture) * [Gateway protocol](https://docs.molt.bot/gateway/protocol) * [Gateway runbook](https://docs.molt.bot/gateway) * [Web surfaces + bind modes](https://docs.molt.bot/web) [​](https://docs.molt.bot/network#pairing-+-identity) Pairing + identity --------------------------------------------------------------------------- * [Pairing overview (DM + nodes)](https://docs.molt.bot/start/pairing) * [Gateway-owned node pairing](https://docs.molt.bot/gateway/pairing) * [Devices CLI (pairing + token rotation)](https://docs.molt.bot/cli/devices) * [Pairing CLI (DM approvals)](https://docs.molt.bot/cli/pairing) Local trust: * Local connections (loopback or the gateway host’s own tailnet address) can be auto‑approved for pairing to keep same‑host UX smooth. * Non‑local tailnet/LAN clients still require explicit pairing approval. [​](https://docs.molt.bot/network#discovery-+-transports) Discovery + transports ----------------------------------------------------------------------------------- * [Discovery & transports](https://docs.molt.bot/gateway/discovery) * [Bonjour / mDNS](https://docs.molt.bot/gateway/bonjour) * [Remote access (SSH)](https://docs.molt.bot/gateway/remote) * [Tailscale](https://docs.molt.bot/gateway/tailscale) [​](https://docs.molt.bot/network#nodes-+-transports) Nodes + transports --------------------------------------------------------------------------- * [Nodes overview](https://docs.molt.bot/nodes) * [Bridge protocol (legacy nodes)](https://docs.molt.bot/gateway/bridge-protocol) * [Node runbook: iOS](https://docs.molt.bot/platforms/ios) * [Node runbook: Android](https://docs.molt.bot/platforms/android) [​](https://docs.molt.bot/network#security) Security ------------------------------------------------------- * [Security overview](https://docs.molt.bot/gateway/security) * [Gateway config reference](https://docs.molt.bot/gateway/configuration) * [Troubleshooting](https://docs.molt.bot/gateway/troubleshooting) * [Doctor](https://docs.molt.bot/gateway/doctor) ⌘I --- # Brave search - Moltbot [Skip to main content](https://docs.molt.bot/brave-search#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Brave Search API](https://docs.molt.bot/brave-search#brave-search-api) * [Get an API key](https://docs.molt.bot/brave-search#get-an-api-key) * [Config example](https://docs.molt.bot/brave-search#config-example) * [Notes](https://docs.molt.bot/brave-search#notes) [​](https://docs.molt.bot/brave-search#brave-search-api) Brave Search API ============================================================================ Moltbot uses Brave Search as the default provider for `web_search`. [​](https://docs.molt.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.molt.bot/brave-search#config-example) Config example ------------------------------------------------------------------------ Copy { tools: { web: { search: { provider: "brave", apiKey: "BRAVE_API_KEY_HERE", maxResults: 5, timeoutSeconds: 30 } } } } [​](https://docs.molt.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.molt.bot/tools/web) for the full web\_search configuration. ⌘I --- # Devices - Moltbot [Skip to main content](https://docs.molt.bot/cli/devices#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [moltbot devices](https://docs.molt.bot/cli/devices#moltbot-devices) * [Commands](https://docs.molt.bot/cli/devices#commands) * [moltbot devices list](https://docs.molt.bot/cli/devices#moltbot-devices-list) * [moltbot devices approve ](https://docs.molt.bot/cli/devices#moltbot-devices-approve-%3Crequestid%3E) * [moltbot devices reject ](https://docs.molt.bot/cli/devices#moltbot-devices-reject-%3Crequestid%3E) * [moltbot devices rotate --device --role \[--scope \]](https://docs.molt.bot/cli/devices#moltbot-devices-rotate-device-%3Cid%3E-role-%3Crole%3E-%5B-scope-%3Cscope-%3E%5D) * [moltbot devices revoke --device --role ](https://docs.molt.bot/cli/devices#moltbot-devices-revoke-device-%3Cid%3E-role-%3Crole%3E) * [Common options](https://docs.molt.bot/cli/devices#common-options) * [Notes](https://docs.molt.bot/cli/devices#notes) [​](https://docs.molt.bot/cli/devices#moltbot-devices) `moltbot devices` =========================================================================== Manage device pairing requests and device-scoped tokens. [​](https://docs.molt.bot/cli/devices#commands) Commands ----------------------------------------------------------- ### [​](https://docs.molt.bot/cli/devices#moltbot-devices-list) `moltbot devices list` List pending pairing requests and paired devices. Copy moltbot devices list moltbot devices list --json ### [​](https://docs.molt.bot/cli/devices#moltbot-devices-approve-%3Crequestid%3E) `moltbot devices approve ` Approve a pending device pairing request. Copy moltbot devices approve ### [​](https://docs.molt.bot/cli/devices#moltbot-devices-reject-%3Crequestid%3E) `moltbot devices reject ` Reject a pending device pairing request. Copy moltbot devices reject ### [​](https://docs.molt.bot/cli/devices#moltbot-devices-rotate-device-%3Cid%3E-role-%3Crole%3E-[-scope-%3Cscope-%3E]) `moltbot devices rotate --device --role [--scope ]` Rotate a device token for a specific role (optionally updating scopes). Copy moltbot devices rotate --device --role operator --scope operator.read --scope operator.write ### [​](https://docs.molt.bot/cli/devices#moltbot-devices-revoke-device-%3Cid%3E-role-%3Crole%3E) `moltbot devices revoke --device --role ` Revoke a device token for a specific role. Copy moltbot devices revoke --device --role node [​](https://docs.molt.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.molt.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. ⌘I --- # Agent tools - Moltbot [Skip to main content](https://docs.molt.bot/plugins/agent-tools#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Plugin agent tools](https://docs.molt.bot/plugins/agent-tools#plugin-agent-tools) * [Basic tool](https://docs.molt.bot/plugins/agent-tools#basic-tool) * [Optional tool (opt‑in)](https://docs.molt.bot/plugins/agent-tools#optional-tool-opt%E2%80%91in) * [Rules + tips](https://docs.molt.bot/plugins/agent-tools#rules-%2B-tips) [​](https://docs.molt.bot/plugins/agent-tools#plugin-agent-tools) Plugin agent tools ======================================================================================= Moltbot plugins can register **agent tools** (JSON‑schema functions) that are exposed to the LLM during agent runs. Tools can be **required** (always available) or **optional** (opt‑in). Agent tools are configured under `tools` in the main config, or per‑agent under `agents.list[].tools`. The allowlist/denylist policy controls which tools the agent can call. [​](https://docs.molt.bot/plugins/agent-tools#basic-tool) Basic tool ----------------------------------------------------------------------- Copy import { Type } from "@sinclair/typebox"; export default function (api) { api.registerTool({ name: "my_tool", description: "Do a thing", parameters: Type.Object({ input: Type.String(), }), async execute(_id, params) { return { content: [{ type: "text", text: params.input }] }; }, }); } [​](https://docs.molt.bot/plugins/agent-tools#optional-tool-opt%E2%80%91in) Optional tool (opt‑in) ----------------------------------------------------------------------------------------------------- Optional tools are **never** auto‑enabled. Users must add them to an agent allowlist. Copy export default function (api) { api.registerTool( { name: "workflow_tool", description: "Run a local workflow", parameters: { type: "object", properties: { pipeline: { type: "string" }, }, required: ["pipeline"], }, async execute(_id, params) { return { content: [{ type: "text", text: params.pipeline }] }; }, }, { optional: true }, ); } Enable optional tools in `agents.list[].tools.allow` (or global `tools.allow`): Copy { agents: { list: [\ {\ id: "main",\ tools: {\ allow: [\ "workflow_tool", // specific tool name\ "workflow", // plugin id (enables all tools from that plugin)\ "group:plugins" // all plugin tools\ ]\ }\ }\ ] } } Other config knobs that affect tool availability: * Allowlists that only name plugin tools are treated as plugin opt-ins; core tools remain enabled unless you also include core tools or groups in the allowlist. * `tools.profile` / `agents.list[].tools.profile` (base allowlist) * `tools.byProvider` / `agents.list[].tools.byProvider` (provider‑specific allow/deny) * `tools.sandbox.tools.*` (sandbox tool policy when sandboxed) [​](https://docs.molt.bot/plugins/agent-tools#rules-+-tips) Rules + tips --------------------------------------------------------------------------- * Tool names must **not** clash with core tool names; conflicting tools are skipped. * Plugin ids used in allowlists must not clash with core tool names. * Prefer `optional: true` for tools that trigger side effects or require extra binaries/credentials. ⌘I --- # Deepgram - Moltbot [Skip to main content](https://docs.molt.bot/providers/deepgram#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Deepgram (Audio Transcription)](https://docs.molt.bot/providers/deepgram#deepgram-audio-transcription) * [Quick start](https://docs.molt.bot/providers/deepgram#quick-start) * [Options](https://docs.molt.bot/providers/deepgram#options) * [Notes](https://docs.molt.bot/providers/deepgram#notes) [​](https://docs.molt.bot/providers/deepgram#deepgram-audio-transcription) Deepgram (Audio Transcription) ============================================================================================================ Deepgram is a speech-to-text API. In Moltbot it is used for **inbound audio/voice note transcription** via `tools.media.audio`. When enabled, Moltbot uploads the audio file to Deepgram and injects the transcript into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**; it uses the pre-recorded transcription endpoint. Website: [https://deepgram.com](https://deepgram.com/) Docs: [https://developers.deepgram.com](https://developers.deepgram.com/) [​](https://docs.molt.bot/providers/deepgram#quick-start) Quick start ------------------------------------------------------------------------ 1. Set your API key: Copy DEEPGRAM_API_KEY=dg_... 2. Enable the provider: Copy { tools: { media: { audio: { enabled: true, models: [{ provider: "deepgram", model: "nova-3" }] } } } } [​](https://docs.molt.bot/providers/deepgram#options) Options ---------------------------------------------------------------- * `model`: Deepgram model id (default: `nova-3`) * `language`: language hint (optional) * `tools.media.audio.providerOptions.deepgram.detect_language`: enable language detection (optional) * `tools.media.audio.providerOptions.deepgram.punctuate`: enable punctuation (optional) * `tools.media.audio.providerOptions.deepgram.smart_format`: enable smart formatting (optional) Example with language: Copy { tools: { media: { audio: { enabled: true, models: [\ { provider: "deepgram", model: "nova-3", language: "en" }\ ] } } } } Example with Deepgram options: Copy { tools: { media: { audio: { enabled: true, providerOptions: { deepgram: { detect_language: true, punctuate: true, smart_format: true } }, models: [{ provider: "deepgram", model: "nova-3" }] } } } } [​](https://docs.molt.bot/providers/deepgram#notes) Notes ------------------------------------------------------------ * Authentication follows the standard provider auth order; `DEEPGRAM_API_KEY` is the simplest path. * Override endpoints or headers with `tools.media.audio.baseUrl` and `tools.media.audio.headers` when using a proxy. * Output follows the same audio rules as other providers (size caps, timeouts, transcript injection). ⌘I --- # Manifest - Moltbot [Skip to main content](https://docs.molt.bot/plugins/manifest#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Plugin manifest (moltbot.plugin.json)](https://docs.molt.bot/plugins/manifest#plugin-manifest-moltbot-plugin-json) * [Required fields](https://docs.molt.bot/plugins/manifest#required-fields) * [JSON Schema requirements](https://docs.molt.bot/plugins/manifest#json-schema-requirements) * [Validation behavior](https://docs.molt.bot/plugins/manifest#validation-behavior) * [Notes](https://docs.molt.bot/plugins/manifest#notes) [​](https://docs.molt.bot/plugins/manifest#plugin-manifest-moltbot-plugin-json) Plugin manifest (moltbot.plugin.json) ======================================================================================================================== Every plugin **must** ship a `moltbot.plugin.json` file in the **plugin root**. Moltbot uses this manifest to validate configuration **without executing plugin code**. Missing or invalid manifests are treated as plugin errors and block config validation. See the full plugin system guide: [Plugins](https://docs.molt.bot/plugin) . [​](https://docs.molt.bot/plugins/manifest#required-fields) Required fields ------------------------------------------------------------------------------ Copy { "id": "voice-call", "configSchema": { "type": "object", "additionalProperties": false, "properties": {} } } Required keys: * `id` (string): canonical plugin id. * `configSchema` (object): JSON Schema for plugin config (inline). Optional keys: * `kind` (string): plugin kind (example: `"memory"`). * `channels` (array): channel ids registered by this plugin (example: `["matrix"]`). * `providers` (array): provider ids registered by this plugin. * `skills` (array): skill directories to load (relative to the plugin root). * `name` (string): display name for the plugin. * `description` (string): short plugin summary. * `uiHints` (object): config field labels/placeholders/sensitive flags for UI rendering. * `version` (string): plugin version (informational). [​](https://docs.molt.bot/plugins/manifest#json-schema-requirements) JSON Schema requirements ------------------------------------------------------------------------------------------------ * **Every plugin must ship a JSON Schema**, even if it accepts no config. * An empty schema is acceptable (for example, `{ "type": "object", "additionalProperties": false }`). * Schemas are validated at config read/write time, not at runtime. [​](https://docs.molt.bot/plugins/manifest#validation-behavior) Validation behavior -------------------------------------------------------------------------------------- * Unknown `channels.*` keys are **errors**, unless the channel id is declared by a plugin manifest. * `plugins.entries.`, `plugins.allow`, `plugins.deny`, and `plugins.slots.*` must reference **discoverable** plugin ids. Unknown ids are **errors**. * If a plugin is installed but has a broken or missing manifest or schema, validation fails and Doctor reports the plugin error. * If plugin config exists but the plugin is **disabled**, the config is kept and a **warning** is surfaced in Doctor + logs. [​](https://docs.molt.bot/plugins/manifest#notes) Notes ---------------------------------------------------------- * The manifest is **required for all plugins**, including local filesystem loads. * Runtime still loads the plugin module separately; the manifest is only for discovery + validation. * If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm `allow-build-scripts` * `pnpm rebuild `). ⌘I --- # Prose - Moltbot [Skip to main content](https://docs.molt.bot/prose#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [OpenProse](https://docs.molt.bot/prose#openprose) * [What it can do](https://docs.molt.bot/prose#what-it-can-do) * [Install + enable](https://docs.molt.bot/prose#install-%2B-enable) * [Slash command](https://docs.molt.bot/prose#slash-command) * [Example: a simple .prose file](https://docs.molt.bot/prose#example%3A-a-simple-prose-file) * [File locations](https://docs.molt.bot/prose#file-locations) * [State modes](https://docs.molt.bot/prose#state-modes) * [Remote programs](https://docs.molt.bot/prose#remote-programs) * [Moltbot runtime mapping](https://docs.molt.bot/prose#moltbot-runtime-mapping) * [Security + approvals](https://docs.molt.bot/prose#security-%2B-approvals) [​](https://docs.molt.bot/prose#openprose) OpenProse ======================================================= OpenProse is a portable, markdown-first workflow format for orchestrating AI sessions. In Moltbot it ships as a plugin that installs an OpenProse skill pack plus a `/prose` slash command. Programs live in `.prose` files and can spawn multiple sub-agents with explicit control flow. Official site: [https://www.prose.md](https://www.prose.md/) [​](https://docs.molt.bot/prose#what-it-can-do) What it can do ----------------------------------------------------------------- * Multi-agent research + synthesis with explicit parallelism. * Repeatable approval-safe workflows (code review, incident triage, content pipelines). * Reusable `.prose` programs you can run across supported agent runtimes. [​](https://docs.molt.bot/prose#install-+-enable) Install + enable --------------------------------------------------------------------- Bundled plugins are disabled by default. Enable OpenProse: Copy moltbot plugins enable open-prose Restart the Gateway after enabling the plugin. Dev/local checkout: `moltbot plugins install ./extensions/open-prose` Related docs: [Plugins](https://docs.molt.bot/plugin) , [Plugin manifest](https://docs.molt.bot/plugins/manifest) , [Skills](https://docs.molt.bot/tools/skills) . [​](https://docs.molt.bot/prose#slash-command) Slash command --------------------------------------------------------------- OpenProse registers `/prose` as a user-invocable skill command. It routes to the OpenProse VM instructions and uses Moltbot tools under the hood. Common commands: Copy /prose help /prose run /prose run /prose run /prose compile /prose examples /prose update [​](https://docs.molt.bot/prose#example:-a-simple-prose-file) Example: a simple `.prose` file ------------------------------------------------------------------------------------------------ Copy # Research + synthesis with two agents running in parallel. input topic: "What should we research?" agent researcher: model: sonnet prompt: "You research thoroughly and cite sources." agent writer: model: opus prompt: "You write a concise summary." parallel: findings = session: researcher prompt: "Research {topic}." draft = session: writer prompt: "Summarize {topic}." session "Merge the findings + draft into a final answer." context: { findings, draft } [​](https://docs.molt.bot/prose#file-locations) File locations ----------------------------------------------------------------- OpenProse keeps state under `.prose/` in your workspace: Copy .prose/ ├── .env ├── runs/ │ └── {YYYYMMDD}-{HHMMSS}-{random}/ │ ├── program.prose │ ├── state.md │ ├── bindings/ │ └── agents/ └── agents/ User-level persistent agents live at: Copy ~/.prose/agents/ [​](https://docs.molt.bot/prose#state-modes) State modes ----------------------------------------------------------- OpenProse supports multiple state backends: * **filesystem** (default): `.prose/runs/...` * **in-context**: transient, for small programs * **sqlite** (experimental): requires `sqlite3` binary * **postgres** (experimental): requires `psql` and a connection string Notes: * sqlite/postgres are opt-in and experimental. * postgres credentials flow into subagent logs; use a dedicated, least-privileged DB. [​](https://docs.molt.bot/prose#remote-programs) Remote programs ------------------------------------------------------------------- `/prose run ` resolves to `https://p.prose.md//`. Direct URLs are fetched as-is. This uses the `web_fetch` tool (or `exec` for POST). [​](https://docs.molt.bot/prose#moltbot-runtime-mapping) Moltbot runtime mapping ----------------------------------------------------------------------------------- OpenProse programs map to Moltbot primitives: | OpenProse concept | Moltbot tool | | --- | --- | | Spawn session / Task tool | `sessions_spawn` | | File read/write | `read` / `write` | | Web fetch | `web_fetch` | If your tool allowlist blocks these tools, OpenProse programs will fail. See [Skills config](https://docs.molt.bot/tools/skills-config) . [​](https://docs.molt.bot/prose#security-+-approvals) Security + approvals ----------------------------------------------------------------------------- Treat `.prose` files like code. Review before running. Use Moltbot tool allowlists and approval gates to control side effects. For deterministic, approval-gated workflows, compare with [Lobster](https://docs.molt.bot/tools/lobster) . ⌘I --- # Config - Moltbot [Skip to main content](https://docs.molt.bot/cli/config#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [moltbot config](https://docs.molt.bot/cli/config#moltbot-config) * [Examples](https://docs.molt.bot/cli/config#examples) * [Paths](https://docs.molt.bot/cli/config#paths) * [Values](https://docs.molt.bot/cli/config#values) [​](https://docs.molt.bot/cli/config#moltbot-config) `moltbot config` ======================================================================== Config helpers: get/set/unset values by path. Run without a subcommand to open the configure wizard (same as `moltbot configure`). [​](https://docs.molt.bot/cli/config#examples) Examples ---------------------------------------------------------- Copy moltbot config get browser.executablePath moltbot config set browser.executablePath "/usr/bin/google-chrome" moltbot config set agents.defaults.heartbeat.every "2h" moltbot config set agents.list[0].tools.exec.node "node-id-or-name" moltbot config unset tools.web.search.apiKey [​](https://docs.molt.bot/cli/config#paths) Paths ---------------------------------------------------- Paths use dot or bracket notation: Copy moltbot config get agents.defaults.workspace moltbot config get agents.list[0].id Use the agent list index to target a specific agent: Copy moltbot config get agents.list moltbot config set agents.list[1].tools.exec.node "node-id-or-name" [​](https://docs.molt.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 moltbot config set agents.defaults.heartbeat.every "0m" moltbot config set gateway.port 19001 --json moltbot config set channels.whatsapp.groups '["*"]' --json Restart the gateway after edits. ⌘I --- # Ollama - Moltbot [Skip to main content](https://docs.molt.bot/providers/ollama#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [Ollama](https://docs.molt.bot/providers/ollama#ollama) * [Quick start](https://docs.molt.bot/providers/ollama#quick-start) * [Model discovery (implicit provider)](https://docs.molt.bot/providers/ollama#model-discovery-implicit-provider) * [Configuration](https://docs.molt.bot/providers/ollama#configuration) * [Basic setup (implicit discovery)](https://docs.molt.bot/providers/ollama#basic-setup-implicit-discovery) * [Explicit setup (manual models)](https://docs.molt.bot/providers/ollama#explicit-setup-manual-models) * [Custom base URL (explicit config)](https://docs.molt.bot/providers/ollama#custom-base-url-explicit-config) * [Model selection](https://docs.molt.bot/providers/ollama#model-selection) * [Advanced](https://docs.molt.bot/providers/ollama#advanced) * [Reasoning models](https://docs.molt.bot/providers/ollama#reasoning-models) * [Model Costs](https://docs.molt.bot/providers/ollama#model-costs) * [Context windows](https://docs.molt.bot/providers/ollama#context-windows) * [Troubleshooting](https://docs.molt.bot/providers/ollama#troubleshooting) * [Ollama not detected](https://docs.molt.bot/providers/ollama#ollama-not-detected) * [No models available](https://docs.molt.bot/providers/ollama#no-models-available) * [Connection refused](https://docs.molt.bot/providers/ollama#connection-refused) * [See Also](https://docs.molt.bot/providers/ollama#see-also) [​](https://docs.molt.bot/providers/ollama#ollama) Ollama ============================================================ Ollama is a local LLM runtime that makes it easy to run open-source models on your machine. Moltbot integrates with Ollama’s OpenAI-compatible API and can **auto-discover tool-capable models** when you opt in with `OLLAMA_API_KEY` (or an auth profile) and do not define an explicit `models.providers.ollama` entry. [​](https://docs.molt.bot/providers/ollama#quick-start) Quick start ---------------------------------------------------------------------- 1. Install Ollama: [https://ollama.ai](https://ollama.ai/) 2. Pull a model: Copy ollama pull llama3.3 # or ollama pull qwen2.5-coder:32b # or ollama pull deepseek-r1:32b 3. Enable Ollama for Moltbot (any value works; Ollama doesn’t require a real key): Copy # Set environment variable export OLLAMA_API_KEY="ollama-local" # Or configure in your config file moltbot config set models.providers.ollama.apiKey "ollama-local" 4. Use Ollama models: Copy { agents: { defaults: { model: { primary: "ollama/llama3.3" } } } } [​](https://docs.molt.bot/providers/ollama#model-discovery-implicit-provider) Model discovery (implicit provider) -------------------------------------------------------------------------------------------------------------------- When you set `OLLAMA_API_KEY` (or an auth profile) and **do not** define `models.providers.ollama`, Moltbot discovers models from the local Ollama instance at `http://127.0.0.1:11434`: * Queries `/api/tags` and `/api/show` * Keeps only models that report `tools` capability * Marks `reasoning` when the model reports `thinking` * Reads `contextWindow` from `model_info[".context_length"]` when available * Sets `maxTokens` to 10× the context window * Sets all costs to `0` This avoids manual model entries while keeping the catalog aligned with Ollama’s capabilities. To see what models are available: Copy ollama list moltbot models list To add a new model, simply pull it with Ollama: Copy ollama pull mistral The new model will be automatically discovered and available to use. If you set `models.providers.ollama` explicitly, auto-discovery is skipped and you must define models manually (see below). [​](https://docs.molt.bot/providers/ollama#configuration) Configuration -------------------------------------------------------------------------- ### [​](https://docs.molt.bot/providers/ollama#basic-setup-implicit-discovery) Basic setup (implicit discovery) The simplest way to enable Ollama is via environment variable: Copy export OLLAMA_API_KEY="ollama-local" ### [​](https://docs.molt.bot/providers/ollama#explicit-setup-manual-models) Explicit setup (manual models) Use explicit config when: * Ollama runs on another host/port. * You want to force specific context windows or model lists. * You want to include models that do not report tool support. Copy { models: { providers: { ollama: { // Use a host that includes /v1 for OpenAI-compatible APIs baseUrl: "http://ollama-host:11434/v1", apiKey: "ollama-local", api: "openai-completions", models: [\ {\ id: "llama3.3",\ name: "Llama 3.3",\ reasoning: false,\ input: ["text"],\ cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },\ contextWindow: 8192,\ maxTokens: 8192 * 10\ }\ ] } } } } If `OLLAMA_API_KEY` is set, you can omit `apiKey` in the provider entry and Moltbot will fill it for availability checks. ### [​](https://docs.molt.bot/providers/ollama#custom-base-url-explicit-config) Custom base URL (explicit config) If Ollama is running on a different host or port (explicit config disables auto-discovery, so define models manually): Copy { models: { providers: { ollama: { apiKey: "ollama-local", baseUrl: "http://ollama-host:11434/v1" } } } } ### [​](https://docs.molt.bot/providers/ollama#model-selection) Model selection Once configured, all your Ollama models are available: Copy { agents: { defaults: { model: { primary: "ollama/llama3.3", fallback: ["ollama/qwen2.5-coder:32b"] } } } } [​](https://docs.molt.bot/providers/ollama#advanced) Advanced ---------------------------------------------------------------- ### [​](https://docs.molt.bot/providers/ollama#reasoning-models) Reasoning models Moltbot marks models as reasoning-capable when Ollama reports `thinking` in `/api/show`: Copy ollama pull deepseek-r1:32b ### [​](https://docs.molt.bot/providers/ollama#model-costs) Model Costs Ollama is free and runs locally, so all model costs are set to $0. ### [​](https://docs.molt.bot/providers/ollama#context-windows) Context windows For auto-discovered models, Moltbot uses the context window reported by Ollama when available, otherwise it defaults to `8192`. You can override `contextWindow` and `maxTokens` in explicit provider config. [​](https://docs.molt.bot/providers/ollama#troubleshooting) Troubleshooting ------------------------------------------------------------------------------ ### [​](https://docs.molt.bot/providers/ollama#ollama-not-detected) Ollama not detected Make sure Ollama is running and that you set `OLLAMA_API_KEY` (or an auth profile), and that you did **not** define an explicit `models.providers.ollama` entry: Copy ollama serve And that the API is accessible: Copy curl http://localhost:11434/api/tags ### [​](https://docs.molt.bot/providers/ollama#no-models-available) No models available Moltbot only auto-discovers models that report tool support. If your model isn’t listed, either: * Pull a tool-capable model, or * Define the model explicitly in `models.providers.ollama`. To add models: Copy ollama list # See what's installed ollama pull llama3.3 # Pull a model ### [​](https://docs.molt.bot/providers/ollama#connection-refused) Connection refused Check that Ollama is running on the correct port: Copy # Check if Ollama is running ps aux | grep ollama # Or restart Ollama ollama serve [​](https://docs.molt.bot/providers/ollama#see-also) See Also ---------------------------------------------------------------- * [Model Providers](https://docs.molt.bot/concepts/model-providers) - Overview of all providers * [Model Selection](https://docs.molt.bot/concepts/models) - How to choose models * [Configuration](https://docs.molt.bot/gateway/configuration) - Full config reference ⌘I --- # Acp - Moltbot [Skip to main content](https://docs.molt.bot/cli/acp#content-area) [Moltbot 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.molt.bot/) Search... ⌘K Search... Navigation On this page * [acp](https://docs.molt.bot/cli/acp#acp) * [Usage](https://docs.molt.bot/cli/acp#usage) * [ACP client (debug)](https://docs.molt.bot/cli/acp#acp-client-debug) * [How to use this](https://docs.molt.bot/cli/acp#how-to-use-this) * [Selecting agents](https://docs.molt.bot/cli/acp#selecting-agents) * [Zed editor setup](https://docs.molt.bot/cli/acp#zed-editor-setup) * [Session mapping](https://docs.molt.bot/cli/acp#session-mapping) * [Options](https://docs.molt.bot/cli/acp#options) * [acp client options](https://docs.molt.bot/cli/acp#acp-client-options) [​](https://docs.molt.bot/cli/acp#acp) acp ============================================= Run the ACP (Agent Client Protocol) bridge that talks to a Moltbot 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.molt.bot/cli/acp#usage) Usage ------------------------------------------------- Copy moltbot acp # Remote Gateway moltbot acp --url wss://gateway-host:18789 --token # Attach to an existing session key moltbot acp --session agent:main:main # Attach by label (must already exist) moltbot acp --session-label "support inbox" # Reset the session key before the first prompt moltbot acp --session agent:main:main --reset-session [​](https://docs.molt.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 moltbot acp client # Point the spawned bridge at a remote Gateway moltbot acp client --server-args --url wss://gateway-host:18789 --token # Override the server command (default: moltbot) moltbot acp client --server "node" --server-args moltbot.mjs acp --url ws://127.0.0.1:19001 [​](https://docs.molt.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 Moltbot 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 `moltbot acp` over stdio. Example config (persisted): Copy moltbot config set gateway.remote.url wss://gateway-host:18789 moltbot config set gateway.remote.token Example direct run (no config write): Copy moltbot acp --url wss://gateway-host:18789 --token [​](https://docs.molt.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 moltbot acp --session agent:main:main moltbot acp --session agent:design:main moltbot 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.molt.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": { "Moltbot ACP": { "type": "custom", "command": "moltbot", "args": ["acp"], "env": {} } } } To target a specific Gateway or agent: Copy { "agent_servers": { "Moltbot ACP": { "type": "custom", "command": "moltbot", "args": [\ "acp",\ "--url", "wss://gateway-host:18789",\ "--token", "",\ "--session", "agent:design:main"\ ], "env": {} } } } In Zed, open the Agent panel and select “Moltbot ACP” to start a thread. [​](https://docs.molt.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