diff --git a/docs/providers/discord.md b/docs/providers/discord.md index 1777fcf53..a3778f85e 100644 --- a/docs/providers/discord.md +++ b/docs/providers/discord.md @@ -8,6 +8,25 @@ read_when: Status: ready for DM and guild text channels via the official Discord bot gateway. +## Quick setup (beginner) +1) Create a Discord bot and copy the bot token. +2) Set the token for Clawdbot: + - Env: `DISCORD_BOT_TOKEN=...` + - Or config: `discord.token: "..."`. +3) Invite the bot to your server with message permissions. +4) Start the gateway. +5) DM access is pairing by default; approve the pairing code on first contact. + +Minimal config: +```json5 +{ + discord: { + enabled: true, + token: "YOUR_BOT_TOKEN" + } +} +``` + ## Goals - Talk to Clawdbot via Discord DMs or guild channels. - Direct chats collapse into the agent's main session (default `agent:main:main`); guild channels stay isolated as `agent::discord:channel:` (display names use `discord:#`). @@ -18,8 +37,8 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa 1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token. 2. Invite the bot to your server with the permissions required to read/send messages where you want to use it. 3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdbot/clawdbot.json`). -4. Run the gateway; it auto-starts the Discord provider only when a `discord` config section exists **and** the token is set (unless `discord.enabled = false`). - - If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`. +4. Run the gateway; it auto-starts the Discord provider when a token is available (env or config) and `discord.enabled` is not `false`. + - If you prefer env vars, set `DISCORD_BOT_TOKEN` (a config block is optional). 5. Direct chats: use `user:` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session. Bare numeric IDs are ambiguous and rejected. 6. Guild channels: use `channel:` for delivery. Mentions are required by default and can be set per guild or per channel. 7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code (expires after 1 hour); approve via `clawdbot pairing approve discord `. diff --git a/docs/providers/imessage.md b/docs/providers/imessage.md index 8a3202428..c22cdfd65 100644 --- a/docs/providers/imessage.md +++ b/docs/providers/imessage.md @@ -9,6 +9,24 @@ read_when: Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio). +## Quick setup (beginner) +1) Ensure Messages is signed in on this Mac. +2) Install `imsg`: + - `brew install steipete/tap/imsg` +3) Configure Clawdbot with `imessage.cliPath` and `imessage.dbPath`. +4) Start the gateway and approve any macOS prompts (Automation + Full Disk Access). + +Minimal config: +```json5 +{ + imessage: { + enabled: true, + cliPath: "/usr/local/bin/imsg", + dbPath: "/Users//Library/Messages/chat.db" + } +} +``` + ## What it is - iMessage provider backed by `imsg` on macOS. - Deterministic routing: replies always go back to iMessage. diff --git a/docs/providers/index.md b/docs/providers/index.md index f99d60188..271853677 100644 --- a/docs/providers/index.md +++ b/docs/providers/index.md @@ -1,40 +1,28 @@ --- -summary: "All supported providers (models + messaging) in one place" +summary: "Messaging platforms Clawdbot can connect to" read_when: - - You want a single hub for every provider we document - - You want model providers vs chat providers split clearly + - You want to choose a chat provider for Clawdbot + - You need a quick overview of supported messaging platforms --- -# Providers hub +# Chat Providers -This hub covers **model providers** (LLMs) and **messaging/chat providers** (WhatsApp, Telegram, etc). -For model selection rules, see [/concepts/models](/concepts/models). For the full provider catalog, see -[/concepts/model-providers](/concepts/model-providers). +Clawdbot can talk to you on any chat app you already use. Each provider connects via the Gateway. +Text is supported everywhere; media and reactions vary by provider. -## Model providers +## Supported providers -- [OpenAI (API + Codex)](/providers/openai) -- [Anthropic (API + Claude CLI)](/providers/anthropic) -- [OpenRouter](/providers/openrouter) -- [OpenCode Zen](/providers/opencode) -- [Z.AI](/providers/zai) -- [GLM models](/providers/glm) +- [WhatsApp](/providers/whatsapp) — Most popular; uses Baileys and requires QR pairing. +- [Telegram](/providers/telegram) — Bot API via grammY; supports groups. +- [Discord](/providers/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs. +- [Slack](/providers/slack) — Bolt SDK; workspace apps. +- [Signal](/providers/signal) — signal-cli; privacy-focused. +- [iMessage](/providers/imessage) — macOS only; native integration. +- [Microsoft Teams](/providers/msteams) — Bot Framework; enterprise support. +- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket. -Full list (xAI, Groq, Mistral, etc.): [/concepts/model-providers](/concepts/model-providers) +## Notes -## Messaging + chat providers - -- [WhatsApp](/providers/whatsapp) -- [Telegram](/providers/telegram) -- [Telegram (grammY notes)](/providers/grammy) -- [Slack](/providers/slack) -- [Discord](/providers/discord) -- [Signal](/providers/signal) -- [iMessage](/providers/imessage) -- [Location parsing](/providers/location) -- [Provider troubleshooting](/providers/troubleshooting) - -## Ingress + web - -- [WebChat](/web/webchat) -- [Webhooks](/automation/webhook) -- [Gmail Pub/Sub](/automation/gmail-pubsub) +- Providers can run simultaneously; configure multiple and Clawdbot will route per chat. +- Group behavior varies by provider; see [Groups](/concepts/groups). +- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security). +- Model providers are documented separately; see [Model Providers](/providers/models). diff --git a/docs/providers/models.md b/docs/providers/models.md new file mode 100644 index 000000000..eba0accf5 --- /dev/null +++ b/docs/providers/models.md @@ -0,0 +1,33 @@ +--- +summary: "Model providers (LLMs) supported by Clawdbot" +read_when: + - You want to choose a model provider + - You want quick setup examples for LLM auth + model selection +--- +# Model Providers + +Clawdbot can use many LLM providers. Pick one, authenticate, then set the default +model as `provider/model`. + +## Quick start (two steps) + +1) Authenticate with the provider (usually via `clawdbot onboard`). +2) Set the default model: + +```json5 +{ + agents: { defaults: { model: { primary: "anthropic/claude-opus-4-5" } } } +} +``` + +## Supported providers (starter set) + +- [OpenAI (API + Codex)](/providers/openai) +- [Anthropic (API + Claude CLI)](/providers/anthropic) +- [OpenRouter](/providers/openrouter) +- [OpenCode Zen](/providers/opencode) +- [Z.AI](/providers/zai) +- [GLM models](/providers/glm) + +For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration, +see [Model providers](/concepts/model-providers). diff --git a/docs/providers/msteams.md b/docs/providers/msteams.md index 7e12a16af..f46f3f5e3 100644 --- a/docs/providers/msteams.md +++ b/docs/providers/msteams.md @@ -12,6 +12,25 @@ Updated: 2026-01-08 Status: text + DM attachments are supported; channel/group attachments require Microsoft Graph permissions. Polls are sent via Adaptive Cards. +## Quick setup (beginner) +1) Create an **Azure Bot** (App ID + client secret + tenant ID). +2) Configure Clawdbot with those credentials. +3) Expose `/api/messages` (port 3978 by default) via a public URL or tunnel. +4) Install the Teams app package and start the gateway. + +Minimal config: +```json5 +{ + msteams: { + enabled: true, + appId: "", + appPassword: "", + tenantId: "", + webhook: { port: 3978, path: "/api/messages" } + } +} +``` + ## Goals - Talk to Clawdbot via Teams DMs, group chats, or channels. - Keep routing deterministic: replies always go back to the provider they arrived on. diff --git a/docs/providers/openai.md b/docs/providers/openai.md index 996df6531..442d7f3ae 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -7,7 +7,8 @@ read_when: # OpenAI OpenAI provides developer APIs for GPT models. Codex supports **ChatGPT sign-in** for subscription -access or **API key** sign-in for usage-based access. The Codex CLI caches login details in +access or **API key** sign-in for usage-based access. Codex cloud requires ChatGPT sign-in, while +the Codex CLI supports either sign-in method. The Codex CLI caches login details in `~/.codex/auth.json` (or your OS credential store), which Clawdbot can reuse. ## Option A: OpenAI API key (OpenAI Platform) diff --git a/docs/providers/signal.md b/docs/providers/signal.md index b33de0262..6140efa7b 100644 --- a/docs/providers/signal.md +++ b/docs/providers/signal.md @@ -9,6 +9,26 @@ read_when: Status: external CLI integration. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE. +## Quick setup (beginner) +1) Use a **separate Signal number** for the bot (recommended). +2) Install `signal-cli` (Java required). +3) Link the bot device and start the daemon: + - `signal-cli link -n "Clawdbot"` +4) Configure Clawdbot and start the gateway. + +Minimal config: +```json5 +{ + signal: { + enabled: true, + account: "+15551234567", + cliPath: "signal-cli", + dmPolicy: "pairing", + allowFrom: ["+15557654321"] + } +} +``` + ## What it is - Signal provider via `signal-cli` (not embedded libsignal). - Deterministic routing: replies always go back to Signal. diff --git a/docs/providers/slack.md b/docs/providers/slack.md index 2b180a922..1b8b61ddf 100644 --- a/docs/providers/slack.md +++ b/docs/providers/slack.md @@ -5,6 +5,22 @@ read_when: "Setting up Slack or debugging Slack socket mode" # Slack (socket mode) +## Quick setup (beginner) +1) Create a Slack app and enable **Socket Mode**. +2) Create an **App Token** (`xapp-...`) and **Bot Token** (`xoxb-...`). +3) Set tokens for Clawdbot and start the gateway. + +Minimal config: +```json5 +{ + slack: { + enabled: true, + appToken: "xapp-...", + botToken: "xoxb-..." + } +} +``` + ## Setup 1) Create a Slack app (From scratch) in https://api.slack.com/apps. 2) **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`). @@ -24,6 +40,24 @@ Use the manifest below so scopes and events stay in sync. Multi-account support: use `slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. +## Clawdbot config (minimal) + +Set tokens via env vars (recommended): +- `SLACK_APP_TOKEN=xapp-...` +- `SLACK_BOT_TOKEN=xoxb-...` + +Or via config: + +```json5 +{ + slack: { + enabled: true, + appToken: "xapp-...", + botToken: "xoxb-..." + } +} +``` + ## History context - `slack.historyLimit` (or `slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt. - Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50). diff --git a/docs/providers/telegram.md b/docs/providers/telegram.md index ee72954f4..cfb70ad4e 100644 --- a/docs/providers/telegram.md +++ b/docs/providers/telegram.md @@ -8,6 +8,25 @@ read_when: Status: production-ready for bot DMs + groups via grammY. Long-polling by default; webhook optional. +## Quick setup (beginner) +1) Create a bot with **@BotFather** and copy the token. +2) Set the token: + - Env: `TELEGRAM_BOT_TOKEN=...` + - Or config: `telegram.botToken: "..."`. +3) Start the gateway. +4) DM access is pairing by default; approve the pairing code on first contact. + +Minimal config: +```json5 +{ + telegram: { + enabled: true, + botToken: "123:abc", + dmPolicy: "pairing" + } +} +``` + ## What it is - A Telegram Bot API provider owned by the Gateway. - Deterministic routing: replies go back to Telegram; the model never chooses providers. @@ -37,9 +56,11 @@ Example: } ``` +Env option: `TELEGRAM_BOT_TOKEN=...` (works for the default account). + Multi-account support: use `telegram.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. -3) Start the gateway. Telegram starts when a `telegram` config section exists and a token is resolved. +3) Start the gateway. Telegram starts when a token is resolved (env or config). 4) DM access defaults to pairing. Approve the code when the bot is first contacted. 5) For groups: add the bot, decide privacy/admin behavior (below), then set `telegram.groups` to control mention gating + allowlists. diff --git a/docs/providers/whatsapp.md b/docs/providers/whatsapp.md index b416892ec..e425adb17 100644 --- a/docs/providers/whatsapp.md +++ b/docs/providers/whatsapp.md @@ -8,6 +8,22 @@ read_when: Status: WhatsApp Web via Baileys only. Gateway owns the session(s). +## Quick setup (beginner) +1) Use a **separate phone number** if possible (recommended). +2) Configure WhatsApp in `~/.clawdbot/clawdbot.json`. +3) Run `clawdbot providers login` to scan the QR code (Linked Devices). +4) Start the gateway. + +Minimal config: +```json5 +{ + whatsapp: { + dmPolicy: "allowlist", + allowFrom: ["+15551234567"] + } +} +``` + ## Goals - Multiple WhatsApp accounts (multi-account) in one Gateway process. - Deterministic routing: replies return to WhatsApp, no model routing. diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 7fcdf4bb0..17d3a89da 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -58,7 +58,8 @@ Use these hubs to discover every page, including deep dives and reference docs t ## Providers + ingress -- [Model providers hub](/providers) +- [Chat providers hub](/providers) +- [Model providers hub](/providers/models) - [WhatsApp](/providers/whatsapp) - [Telegram](/providers/telegram) - [Telegram (grammY notes)](/providers/grammy) diff --git a/docs/web/webchat.md b/docs/web/webchat.md index 112b8d609..3f0ae351a 100644 --- a/docs/web/webchat.md +++ b/docs/web/webchat.md @@ -13,6 +13,11 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket. - Uses the same sessions and routing rules as other providers. - Deterministic routing: replies always go back to WebChat. +## Quick start +1) Start the gateway. +2) Open the WebChat UI (macOS/iOS app) or the Control UI chat tab. +3) Ensure gateway auth is configured if you are not on loopback. + ## How it works (behavior) - The UI connects to the Gateway WebSocket and uses `chat.history` + `chat.send`. - History is always fetched from the gateway (no local file watching).