let5see/clawdbot
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs: add quick setup blocks to chat providers

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-11 02:40:28 +01:00
parent 02270abc87
commit 2e2f05a0e1
12 changed files with 212 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/providers/discord.md
View File

@@ -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:<agentId>:discord:channel:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
@@ -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:<id>` (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:<channelId>` 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 <code>`.

18
docs/providers/imessage.md
View File

@@ -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/<you>/Library/Messages/chat.db"
}
}
```
## What it is
- iMessage provider backed by `imsg` on macOS.
- Deterministic routing: replies always go back to iMessage.

52
docs/providers/index.md
View File

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

33
docs/providers/models.md Normal file
View File

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

19
docs/providers/msteams.md
View File

@@ -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: "<APP_ID>",
appPassword: "<APP_PASSWORD>",
tenantId: "<TENANT_ID>",
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.

3
docs/providers/openai.md
View File

@@ -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)

20
docs/providers/signal.md
View File

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

34
docs/providers/slack.md
View File

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

23
docs/providers/telegram.md
View File

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

16
docs/providers/whatsapp.md
View File

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

3
docs/start/hubs.md
View File

@@ -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)

5
docs/web/webchat.md
View File

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