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

docs: normalize Mintlify links

Browse Source
This commit is contained in:
Peter Steinberger
2026-01-06 23:32:12 +00:00
parent e62c8fb55c
commit 3c1a2ff451
48 changed files with 889 additions and 501 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/RELEASING.md
View File

@@ -36,9 +36,9 @@ Use `pnpm` (Node 22+) from the repo root. Keep the working tree clean before tag
- [ ] Build + sign the macOS app, then zip it for distribution.
- [ ] Generate the Sparkle appcast (HTML notes via [`scripts/make_appcast.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/make_appcast.sh)) and update `appcast.xml`.
- [ ] Keep the app zip (and optional dSYM zip) ready to attach to the GitHub release.
- [ ] Follow [`docs/mac/release.md`](https://docs.clawd.bot/mac/release) for the exact commands and required env vars.
- [ ] Follow [`docs/mac/release.md`](/mac/release) for the exact commands and required env vars.
- `APP_BUILD` must be numeric + monotonic (no `-beta`) so Sparkle compares versions correctly.
- If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](https://docs.clawd.bot/mac/release)).
- If notarizing, use the `clawdbot-notary` keychain profile created from App Store Connect API env vars (see [`docs/mac/release.md`](/mac/release)).
6) **Publish (npm)**
- [ ] Confirm git status is clean; commit and push as needed.

10
docs/agent.md
View File

@@ -13,11 +13,11 @@ CLAWDBOT uses a single agent workspace directory (`agent.workspace`) as the agen
Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files.
Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace)
Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
If `agent.sandbox` is enabled, non-main sessions can override this with
per-session workspaces under `agent.sandbox.workspaceRoot` (see
[`docs/configuration.md`](https://docs.clawd.bot/configuration)).
[`docs/configuration.md`](/configuration)).
## Bootstrap files (injected)
@@ -52,7 +52,7 @@ Clawdbot loads skills from three locations (workspace wins on name conflict):
- Managed/local: `~/.clawdbot/skills`
- Workspace: `<workspace>/skills`
Skills can be gated by config/env (see `skills` in [`docs/configuration.md`](https://docs.clawd.bot/configuration)).
Skills can be gated by config/env (see `skills` in [`docs/configuration.md`](/configuration)).
## p-mono integration
@@ -91,7 +91,7 @@ message is injected before the next assistant response.
When queue mode is `followup` or `collect`, inbound messages are held until the
current turn ends, then a new agent turn starts with the queued payloads. See
[`docs/queue.md`](https://docs.clawd.bot/queue) for mode + debounce/cap behavior.
[`docs/queue.md`](/queue) for mode + debounce/cap behavior.
Block streaming sends completed assistant blocks as soon as they finish; disable
via `agent.blockStreamingDefault: "off"` if you only want the final response.
@@ -109,4 +109,4 @@ At minimum, set:
---
*Next: [Group Chats](https://docs.clawd.bot/group-messages)* 🦞
*Next: [Group Chats](/group-messages)* 🦞

8
docs/android.md
View File

@@ -47,7 +47,7 @@ From the gateway machine:
dns-sd -B _clawdbot-bridge._tcp local.
```
More debugging notes: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
More debugging notes: [`docs/bonjour.md`](/bonjour).
#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
@@ -56,7 +56,7 @@ Android NSD/mDNS discovery won’t cross networks. If your Android node and the
1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
Details and example CoreDNS config: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
Details and example CoreDNS config: [`docs/bonjour.md`](/bonjour).
### 3) Connect from Android
@@ -80,7 +80,7 @@ clawdbot nodes pending
clawdbot nodes approve <requestId>
```
Pairing details: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing).
Pairing details: [`docs/gateway/pairing.md`](/gateway/pairing).
### 5) Verify the node is connected
@@ -130,4 +130,4 @@ Camera commands (foreground only; permission-gated):
- `camera.snap` (jpg)
- `camera.clip` (mp4)
See [`docs/camera.md`](https://docs.clawd.bot/camera) for parameters and CLI helpers.
See [`docs/camera.md`](/camera) for parameters and CLI helpers.

2
docs/architecture.md
View File

@@ -46,7 +46,7 @@ Last updated: 2026-01-05
- **Clients (mac app / CLI / web admin)**
- One WS connection per client.
- Send requests (`health`, `status`, `send`, `agent`, `system-presence`, toggles) and subscribe to events (`tick`, `agent`, `presence`, `shutdown`).
- On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](https://docs.clawd.bot/macos)).
- On macOS, the app can also be invoked via deep links (`clawdbot://agent?...`) which translate into the same Gateway `agent` request path (see [`docs/macos.md`](/macos)).
- **Agent process (Pi)**
- Spawned by the Gateway on demand for `agent` calls; streams events back over the same WS connection.
- **WebChat**

4
docs/bonjour.md
View File

@@ -155,5 +155,5 @@ Bonjour/DNS-SD often escapes bytes in service instance names as decimal `\\DDD`
## Related docs
- Discovery policy and transport selection: [`docs/discovery.md`](https://docs.clawd.bot/discovery)
- Node pairing + approvals: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)
- Discovery policy and transport selection: [`docs/discovery.md`](/discovery)
- Node pairing + approvals: [`docs/gateway/pairing.md`](/gateway/pairing)

2
docs/browser.md
View File

@@ -306,4 +306,4 @@ Notes:
## Troubleshooting
For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](https://docs.clawd.bot/browser-linux-troubleshooting).
For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting](/browser-linux-troubleshooting).

20
docs/clawd.md
View File

@@ -93,7 +93,7 @@ Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideal
clawdbot setup
```
Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace)
Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
Optional: choose a different workspace with `agent.workspace` (supports `~`).
@@ -206,12 +206,12 @@ Logs live under `/tmp/clawdbot/` (default: `clawdbot-YYYY-MM-DD.log`).
## Next steps
- WebChat: [WebChat](https://docs.clawd.bot/webchat)
- Gateway ops: [Gateway runbook](https://docs.clawd.bot/gateway)
- Cron + wakeups: [Cron jobs](https://docs.clawd.bot/cron-jobs)
- macOS menu bar companion: [Clawdbot macOS app](https://docs.clawd.bot/macos)
- iOS node app: [iOS app](https://docs.clawd.bot/ios)
- Android node app: [Android app](https://docs.clawd.bot/android)
- Windows status: [Windows app](https://docs.clawd.bot/windows)
- Linux status: [Linux app](https://docs.clawd.bot/linux)
- Security: [Security](https://docs.clawd.bot/security)
- WebChat: [WebChat](/webchat)
- Gateway ops: [Gateway runbook](/gateway)
- Cron + wakeups: [Cron jobs](/cron-jobs)
- macOS menu bar companion: [Clawdbot macOS app](/macos)
- iOS node app: [iOS app](/ios)
- Android node app: [Android app](/android)
- Windows status: [Windows app](/windows)
- Linux status: [Linux app](/linux)
- Security: [Security](/security)

6
docs/configuration.md
View File

@@ -1286,7 +1286,7 @@ Convenience flags (CLI):
- `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
- `clawdbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)
See [`docs/gateway.md`](https://docs.clawd.bot/gateway) for the derived port mapping (gateway/bridge/browser/canvas).
See [`docs/gateway.md`](/gateway) for the derived port mapping (gateway/bridge/browser/canvas).
Example:
```bash
@@ -1482,7 +1482,7 @@ Template placeholders are expanded in `routing.transcribeAudio.command` (and any
## Cron (Gateway scheduler)
Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs](https://docs.clawd.bot/cron-jobs) for the feature overview and CLI examples.
Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs](/cron-jobs) for the feature overview and CLI examples.
```json5
{
@@ -1495,4 +1495,4 @@ Cron is a Gateway-owned scheduler for wakeups and scheduled jobs. See [Cron jobs
---
*Next: [Agent Runtime](https://docs.clawd.bot/agent)* 🦞
*Next: [Agent Runtime](/agent)* 🦞

8
docs/dashboard.md
View File

@@ -9,9 +9,9 @@ The Gateway dashboard is the browser Control UI served at `/` by default
(override with `gateway.controlUi.basePath`).
Key references:
- [`docs/control-ui.md`](https://docs.clawd.bot/control-ui) for usage and UI capabilities.
- [`docs/tailscale.md`](https://docs.clawd.bot/tailscale) for Serve/Funnel automation.
- [`docs/web.md`](https://docs.clawd.bot/web) for bind modes and security notes.
- [`docs/control-ui.md`](/control-ui) for usage and UI capabilities.
- [`docs/tailscale.md`](/tailscale) for Serve/Funnel automation.
- [`docs/web.md`](/web) for bind modes and security notes.
Authentication is enforced at the WebSocket handshake via `connect.params.auth`
(token or password). See `gateway.auth` in [`docs/configuration.md`](https://docs.clawd.bot/configuration).
(token or password). See `gateway.auth` in [`docs/configuration.md`](/configuration).

347
docs/discord.md
View File

@@ -5,100 +5,293 @@ read_when:
---
# Discord (Bot API)
Updated: 2026-01-06
Updated: 2025-12-07
Status: production-ready for DMs + guild channels via the Discord gateway.
Status: ready for DM and guild text channels via the official Discord bot gateway.
## What it is
- Discord bot provider owned by the Gateway.
- Deterministic routing: replies always go back to Discord.
- DMs share the agent's main session; guild channels are isolated (`discord:channel:<id>`).
## 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>`).
- Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
- Keep routing deterministic: replies always go back to the provider they arrived on.
## Setup (fast path)
1) Create a Discord application + bot.
2) Enable intents: **Message Content** (required), **Server Members** (recommended).
3) Invite the bot to your server with message permissions.
4) Configure the token (env or config) and start the gateway.
## How it works
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`.
5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session.
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; approve via `clawdbot pairing approve --provider discord <code>`.
- To keep old “open to anyone” behavior: set `discord.dm.policy="open"` and `discord.dm.allowFrom=["*"]`.
- To hard-allowlist: set `discord.dm.policy="allowlist"` and list senders in `discord.dm.allowFrom`.
- To ignore all DMs: set `discord.dm.enabled=false` or `discord.dm.policy="disabled"`.
8. Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
9. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
10. Optional native commands: set `commands.native: true` to register native commands in Discord; set `commands.native: false` to clear previously registered native commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
- Full command list + config: [Slash commands](/slash-commands)
11. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
- The `discord` tool is only exposed when the current provider is Discord.
13. Native commands use isolated session keys (`discord:slash:${userId}`) rather than the shared `main` session.
Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
## How to create your own bot
This is the “Discord Developer Portal” setup for running Clawdbot in a server (guild) channel like `#help`.
### 1) Create the Discord app + bot user
1. Discord Developer Portal → **Applications** → **New Application**
2. In your app:
- **Bot** → **Add Bot**
- Copy the **Bot Token** (this is what you put in `DISCORD_BOT_TOKEN`)
### 2) Enable the gateway intents Clawdbot needs
Discord blocks “privileged intents” unless you explicitly enable them.
In **Bot** → **Privileged Gateway Intents**, enable:
- **Message Content Intent** (required to read message text in most guilds; without it you’ll see “Used disallowed intents” or the bot will connect but not react to messages)
- **Server Members Intent** (recommended; required for some member/user lookups and allowlist matching in guilds)
You usually do **not** need **Presence Intent**.
### 3) Generate an invite URL (OAuth2 URL Generator)
In your app: **OAuth2** → **URL Generator**
**Scopes**
- ✅ `bot`
- ✅ `applications.commands` (required for native commands)
**Bot Permissions** (minimal baseline)
- ✅ View Channels
- ✅ Send Messages
- ✅ Read Message History
- ✅ Embed Links
- ✅ Attach Files
- ✅ Add Reactions (optional but recommended)
- ✅ Use External Emojis / Stickers (optional; only if you want them)
Avoid **Administrator** unless you’re debugging and fully trust the bot.
Copy the generated URL, open it, pick your server, and install the bot.
### 4) Get the ids (guild/user/channel)
Discord uses numeric ids everywhere; Clawdbot config prefers ids.
1. Discord (desktop/web) → **User Settings** → **Advanced** → enable **Developer Mode**
2. Right-click:
- Server name → **Copy Server ID** (guild id)
- Channel (e.g. `#help`) → **Copy Channel ID**
- Your user → **Copy User ID**
### 5) Configure Clawdbot
#### Token
Set the bot token via env var (recommended on servers):
- `DISCORD_BOT_TOKEN=...`
Or via config:
Example:
```json5
{
discord: {
enabled: true,
token: "YOUR_BOT_TOKEN",
dm: { policy: "pairing" },
guilds: { "*": { requireMention: true } }
token: "YOUR_BOT_TOKEN"
}
}
```
## Access control (DMs + guilds)
DMs:
- Default: `discord.dm.policy = "pairing"`.
- Unknown senders receive a pairing code; messages are ignored until approved.
- Approve via:
- `clawdbot pairing list --provider discord`
- `clawdbot pairing approve --provider discord <CODE>`
- Pairing is the default token exchange for Discord DMs. Details: https://docs.clawd.bot/pairing
#### Allowlist + channel routing
Example “single server, only allow me, only allow #help”:
Guild channels:
- `discord.groupPolicy = open | allowlist | disabled`.
- `discord.guilds` (per-guild) + `channels` (per-channel) act as allowlists.
- Mentions are required by default; override per guild/channel.
```json5
{
discord: {
enabled: true,
dm: { enabled: false },
guilds: {
"YOUR_GUILD_ID": {
users: ["YOUR_USER_ID"],
requireMention: true,
channels: {
help: { allow: true, requireMention: true }
}
}
}
}
}
```
## How it works (behavior)
- Inbound messages are normalized into the shared provider envelope.
- Optional guild context history is injected before the current message.
- Replies always route back to the same channel or DM.
Notes:
- `requireMention: true` means the bot only replies when mentioned (recommended for shared channels).
- `routing.groupChat.mentionPatterns` also count as mentions for guild messages.
- If `channels` is present, any channel not listed is denied by default.
## Commands + reply threading
- Native commands: `commands.native = true` (registers `/` commands).
- Text commands: `commands.text = true` (standalone `/...` messages).
- Threaded replies: controlled by `discord.replyToMode` using reply tags.
### 6) Verify it works
1. Start the gateway.
2. In your server channel, send: `@Krill hello` (or whatever your bot name is).
3. If nothing happens: check **Troubleshooting** below.
## Media + limits
- Files supported up to `discord.mediaMaxMb` (default 8 MB).
- Outbound chunking controlled by `discord.textChunkLimit`.
### Troubleshooting
- **“Used disallowed intents”**: enable **Message Content Intent** (and likely **Server Members Intent**) in the Developer Portal, then restart the gateway.
- **Bot connects but never replies in a guild channel**:
- Missing **Message Content Intent**, or
- The bot lacks channel permissions (View/Send/Read History), or
- Your config requires mentions and you didn’t mention it, or
- Your guild/channel allowlist denies the channel/user.
- **DMs don’t work**: `discord.dm.enabled=false`, `discord.dm.policy="disabled"`, or you haven’t been approved yet (`discord.dm.policy="pairing"`).
## Delivery targets (CLI/cron)
- DMs: `user:<id>`
- Guild channels: `channel:<channelId>`
## Capabilities & limits
- DMs and guild text channels (threads are treated as separate channels; voice not supported).
- Typing indicators sent best-effort; message chunking honors Discord’s 2k character limit.
- File uploads supported up to the configured `discord.mediaMaxMb` (default 8 MB).
- Mention-gated guild replies by default to avoid noisy bots.
- Reply context is injected when a message references another message (quoted content + ids).
- Native reply threading is **off by default**; enable with `discord.replyToMode` and reply tags.
## Configuration reference (Discord)
Full configuration: https://docs.clawd.bot/configuration
## Config
Provider options:
- `discord.enabled`: enable/disable provider startup.
- `discord.token`: bot token (env: `DISCORD_BOT_TOKEN`).
- `discord.groupPolicy`: `open | allowlist | disabled` (default: open).
- `discord.textChunkLimit`: outbound chunk size (chars).
- `discord.mediaMaxMb`: inbound/outbound media cap (MB).
- `discord.historyLimit`: number of recent guild messages injected as context.
- `discord.replyToMode`: `off | first | all`.
- `discord.actions.reactions`: enable reaction tool actions.
- `discord.actions.stickers`: enable sticker actions.
- `discord.actions.polls`: enable poll actions.
- `discord.actions.permissions`: enable permission inspection actions.
- `discord.actions.messages`: enable message read/send/edit/delete actions.
- `discord.actions.threads`: enable thread actions.
- `discord.actions.pins`: enable pin actions.
- `discord.actions.search`: enable search actions.
- `discord.actions.memberInfo`: enable member info actions.
- `discord.actions.roleInfo`: enable role info actions.
- `discord.actions.roles`: enable role management actions.
- `discord.actions.channelInfo`: enable channel info actions.
- `discord.actions.voiceStatus`: enable voice status actions.
- `discord.actions.events`: enable event actions.
- `discord.actions.moderation`: enable moderation actions.
- `discord.dm.enabled`: enable/disable DMs.
- `discord.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
- `discord.dm.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
- `discord.dm.groupEnabled`: enable group DMs.
- `discord.dm.groupChannels`: group DM allowlist.
- `discord.guilds`: per-guild rules:
- `slug`, `requireMention`, `reactionNotifications`, `users`, `channels.*`.
```json5
{
discord: {
enabled: true,
token: "abc.123",
groupPolicy: "open",
mediaMaxMb: 8,
actions: {
reactions: true,
stickers: true,
polls: true,
permissions: true,
messages: true,
threads: true,
pins: true,
search: true,
memberInfo: true,
roleInfo: true,
roles: false,
channelInfo: true,
voiceStatus: true,
events: true,
moderation: false
},
replyToMode: "off",
dm: {
enabled: true,
policy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["123456789012345678", "steipete"],
groupEnabled: false,
groupChannels: ["clawd-dm"]
},
guilds: {
"*": { requireMention: true },
"123456789012345678": {
slug: "friends-of-clawd",
requireMention: false,
reactionNotifications: "own",
users: ["987654321098765432", "steipete"],
channels: {
general: { allow: true },
help: { allow: true, requireMention: true }
}
}
}
}
}
```
Related global options:
- `routing.groupChat.mentionPatterns`.
- `commands.native`, `commands.text`, `commands.useAccessGroups`.
- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
Ack reactions are controlled globally via `messages.ackReaction` +
`messages.ackReactionScope`.
- `dm.enabled`: set `false` to ignore all DMs (default `true`).
- `dm.policy`: DM access control (`pairing` recommended). `"open"` requires `dm.allowFrom=["*"]`.
- `dm.allowFrom`: DM allowlist (user ids or names). Used by `dm.policy="allowlist"` and for `dm.policy="open"` validation.
- `dm.groupEnabled`: enable group DMs (default `false`).
- `dm.groupChannels`: optional allowlist for group DM channel ids or slugs.
- `groupPolicy`: controls guild channel handling (`open|disabled|allowlist`); `allowlist` requires channel allowlists.
- `guilds`: per-guild rules keyed by guild id (preferred) or slug.
- `guilds."*"`: default per-guild settings applied when no explicit entry exists.
- `guilds.<id>.slug`: optional friendly slug used for display names.
- `guilds.<id>.users`: optional per-guild user allowlist (ids or names).
- `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
- `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).
- `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
- `mediaMaxMb`: clamp inbound media saved to disk.
- `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20, `0` disables).
- `actions`: per-action tool gates; omit to allow all (set `false` to disable).
- `reactions` (covers react + read reactions)
- `stickers`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`
- `memberInfo`, `roleInfo`, `channelInfo`, `voiceStatus`, `events`
- `roles` (role add/remove, default `false`)
- `moderation` (timeout/kick/ban, default `false`)
Reaction notifications use `guilds.<id>.reactionNotifications`:
- `off`: no reaction events.
- `own`: reactions on the bot's own messages (default).
- `all`: all reactions on all messages.
- `allowlist`: reactions from `guilds.<id>.users` on all messages (empty list disables).
### Tool action defaults
| Action group | Default | Notes |
| --- | --- | --- |
| reactions | enabled | React + list reactions + emojiList |
| stickers | enabled | Send stickers |
| polls | enabled | Create polls |
| permissions | enabled | Channel permission snapshot |
| messages | enabled | Read/send/edit/delete |
| threads | enabled | Create/list/reply |
| pins | enabled | Pin/unpin/list |
| search | enabled | Message search (preview spec) |
| memberInfo | enabled | Member info |
| roleInfo | enabled | Role list |
| channelInfo | enabled | Channel info + list |
| voiceStatus | enabled | Voice state lookup |
| events | enabled | List/create scheduled events |
| roles | disabled | Role add/remove |
| moderation | disabled | Timeout/kick/ban |
- `replyToMode`: `off` (default), `first`, or `all`. Applies only when the model includes a reply tag.
## Reply tags
To request a threaded reply, the model can include one tag in its output:
- `[[reply_to_current]]` — reply to the triggering Discord message.
- `[[reply_to:<id>]]` — reply to a specific message id from context/history.
Current message ids are appended to prompts as `[message_id: …]`; history entries already include ids.
Behavior is controlled by `discord.replyToMode`:
- `off`: ignore tags.
- `first`: only the first outbound chunk/attachment is a reply.
- `all`: every outbound chunk/attachment is a reply.
Allowlist matching notes:
- `allowFrom`/`users`/`groupChannels` accept ids, names, tags, or mentions like `<@id>`.
- Prefixes like `discord:`/`user:` (users) and `channel:` (group DMs) are supported.
- Use `*` to allow any sender/channel.
- When `guilds.<id>.channels` is present, channels not listed are denied by default.
Native command notes:
- The registered commands mirror Clawdbot’s chat commands.
- Native commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
## Tool actions
The agent can call `discord` with actions like:
- `react` / `reactions` (add or list reactions)
- `sticker`, `poll`, `permissions`
- `readMessages`, `sendMessage`, `editMessage`, `deleteMessage`
- `threadCreate`, `threadList`, `threadReply`
- `pinMessage`, `unpinMessage`, `listPins`
- `searchMessages`, `memberInfo`, `roleInfo`, `roleAdd`, `roleRemove`, `emojiList`
- `channelInfo`, `channelList`, `voiceStatus`, `eventList`, `eventCreate`
- `timeout`, `kick`, `ban`
Discord message ids are surfaced in the injected context (`[discord message id: …]` and history lines) so the agent can target them.
Emoji can be unicode (e.g., `✅`) or custom emoji syntax like `<:party_blob:1234567890>`.
## Safety & ops
- Treat the bot token like a password; prefer the `DISCORD_BOT_TOKEN` env var on supervised hosts or lock down the config file permissions.
- Only grant the bot permissions it needs (typically Read/Send Messages).
- If the bot is stuck or rate limited, restart the gateway (`clawdbot gateway --force`) after confirming no other processes own the Discord session.

6
docs/discovery.md
View File

@@ -42,7 +42,7 @@ Target direction:
- The **gateway** advertises its bridge via Bonjour.
- Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
Troubleshooting and beacon details: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
Troubleshooting and beacon details: [`docs/bonjour.md`](/bonjour).
#### Current implementation
@@ -77,7 +77,7 @@ If the gateway can detect it is running under Tailscale, it publishes `tailnetDn
When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
See [`docs/remote.md`](https://docs.clawd.bot/remote).
See [`docs/remote.md`](/remote).
## Transport selection (client policy)
@@ -92,7 +92,7 @@ Recommended client behavior:
The gateway is the source of truth for node/client admission.
- Pairing requests are created/approved/rejected in the gateway (see [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing)).
- Pairing requests are created/approved/rejected in the gateway (see [`docs/gateway/pairing.md`](/gateway/pairing)).
- The bridge enforces:
- auth (token / keypair)
- scopes/ACLs (bridge is not a raw proxy to every gateway method)

8
docs/faq.md
View File

@@ -3,7 +3,7 @@ summary: "Frequently asked questions about Clawdbot setup, configuration, and us
---
# FAQ 🦞
Common questions from the community. For detailed configuration, see [Configuration](https://docs.clawd.bot/configuration).
Common questions from the community. For detailed configuration, see [Configuration](/configuration).
## Installation & Setup
@@ -307,7 +307,7 @@ Per-group activation can be changed by the owner:
- `/activation mention` — respond only when mentioned (default)
- `/activation always` — respond to all messages
See [Groups](https://docs.clawd.bot/groups) for details.
See [Groups](/groups) for details.
---
@@ -344,7 +344,7 @@ cat ~/.clawdbot/clawdbot.json | grep workspace
- **Telegram** — Via Bot API (grammY).
- **Discord** — Bot integration.
- **iMessage** — Via `imsg` CLI (macOS only).
- **Signal** — Via `signal-cli` (see [Signal](https://docs.clawd.bot/signal)).
- **Signal** — Via `signal-cli` (see [Signal](/signal)).
- **WebChat** — Browser-based chat UI.
### Discord: Bot works in channels but not DMs?
@@ -586,7 +586,7 @@ Quick reference (send these in chat):
Slash commands are owner-only (gated by `whatsapp.allowFrom` and command authorization on other surfaces).
Commands are only recognized when the entire message is the command (slash required; no plain-text aliases).
Full list + config: https://docs.clawd.bot/slash-commands
Full list + config: [Slash commands](/slash-commands)
### How do I switch models on the fly?

2
docs/gateway.md
View File

@@ -111,7 +111,7 @@ CLAWDBOT_CONFIG_PATH=~/.clawdbot/b.json CLAWDBOT_STATE_DIR=~/.clawdbot-b clawdbo
- `node.invoke` — invoke a command on a node (e.g. `canvas.*`, `camera.*`).
- `node.pair.*` — pairing lifecycle (`request`, `list`, `approve`, `reject`, `verify`).
See also: [`docs/presence.md`](https://docs.clawd.bot/presence) for how presence is produced/deduped and why `instanceId` matters.
See also: [`docs/presence.md`](/presence) for how presence is produced/deduped and why `instanceId` matters.
## Events
- `agent` — streamed tool/output events from the agent run (seq-tagged).

18
docs/getting-started.md
View File

@@ -17,7 +17,7 @@ Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It set
- workspace bootstrap + skills
- optional background daemon
If you want the deeper reference pages, jump to: [Wizard](https://docs.clawd.bot/wizard), [Setup](https://docs.clawd.bot/setup), [Pairing](https://docs.clawd.bot/pairing), [Security](https://docs.clawd.bot/security).
If you want the deeper reference pages, jump to: [Wizard](/wizard), [Setup](/setup), [Pairing](/pairing), [Security](/security).
## 0) Prereqs
@@ -66,7 +66,7 @@ What you’ll choose:
- **Daemon**: optional background install (launchd/systemd/Task Scheduler)
- **Runtime**: Node (recommended; required for WhatsApp) or Bun (faster, but incompatible with WhatsApp)
Wizard doc: https://docs.clawd.bot/wizard
Wizard doc: [Wizard](/wizard)
### Auth: where it lives (important)
@@ -103,13 +103,13 @@ bun run clawdbot login
Scan via WhatsApp → Settings → Linked Devices.
WhatsApp doc: https://docs.clawd.bot/whatsapp
WhatsApp doc: [WhatsApp](/whatsapp)
### Telegram / Discord / others
The wizard can write tokens/config for you. If you prefer manual config, start with:
- Telegram: https://docs.clawd.bot/telegram
- Discord: https://docs.clawd.bot/discord
- Telegram: [Telegram](/telegram)
- Discord: [Discord](/discord)
## 6) DM safety (pairing approvals)
@@ -122,7 +122,7 @@ bun run clawdbot pairing list --provider telegram
bun run clawdbot pairing approve --provider telegram <CODE>
```
Pairing doc: https://docs.clawd.bot/pairing
Pairing doc: [Pairing](/pairing)
## 7) Verify end-to-end
@@ -137,6 +137,6 @@ If `health` shows “no auth configured”, go back to the wizard and set OAuth/
## Next steps (optional, but great)
- macOS menu bar app + voice wake: https://docs.clawd.bot/macos
- iOS/Android nodes (Canvas/camera/voice): https://docs.clawd.bot/nodes
- Remote access (SSH tunnel / Tailscale Serve): https://docs.clawd.bot/remote and https://docs.clawd.bot/tailscale
- macOS menu bar app + voice wake: [macOS app](/macos)
- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/remote) and [Tailscale](/tailscale)

2
docs/groups.md
View File

@@ -127,4 +127,4 @@ The agent system prompt includes a group intro on the first turn of a new group
- Group replies always go back to the same `chat_id`.
## WhatsApp specifics
See [`docs/group-messages.md`](https://docs.clawd.bot/group-messages) for WhatsApp-only behavior (history injection, mention handling details).
See [`docs/group-messages.md`](/group-messages) for WhatsApp-only behavior (history injection, mention handling details).

2
docs/heartbeat.md
View File

@@ -96,7 +96,7 @@ bloat.
- Handle mundane tasks (triage inboxes, summarize queues, refresh notes).
- Nudge on open loops or reminders.
- Background monitoring (health checks, status polling, low-priority alerts).
- Scheduled routines (use [Cron jobs](https://docs.clawd.bot/cron-jobs) when you
- Scheduled routines (use [Cron jobs](/cron-jobs) when you
need exact schedules or isolated runs).
## Wake hook

222
docs/hubs.md
View File

@@ -9,144 +9,144 @@ Use these hubs to discover every page, including deep dives and reference docs t
## Start here
- [Index](https://docs.clawd.bot)
- [Getting Started](https://docs.clawd.bot/getting-started)
- [Onboarding](https://docs.clawd.bot/onboarding)
- [Wizard](https://docs.clawd.bot/wizard)
- [Setup](https://docs.clawd.bot/setup)
- [FAQ](https://docs.clawd.bot/faq)
- [Configuration](https://docs.clawd.bot/configuration)
- [Clawd (personal assistant)](https://docs.clawd.bot/clawd)
- [Lore](https://docs.clawd.bot/lore)
- [Index](/)
- [Getting Started](/getting-started)
- [Onboarding](/onboarding)
- [Wizard](/wizard)
- [Setup](/setup)
- [FAQ](/faq)
- [Configuration](/configuration)
- [Clawd (personal assistant)](/clawd)
- [Lore](/lore)
## Installation + distribution
- [Docker](https://docs.clawd.bot/docker)
- [Nix](https://docs.clawd.bot/nix)
- [Docker](/docker)
- [Nix](/nix)
## Core concepts
- [Architecture](https://docs.clawd.bot/architecture)
- [Agent runtime](https://docs.clawd.bot/agent)
- [Agent workspace](https://docs.clawd.bot/agent-workspace)
- [Agent loop](https://docs.clawd.bot/agent-loop)
- [Multi-agent routing](https://docs.clawd.bot/multi-agent)
- [Sessions](https://docs.clawd.bot/session)
- [Sessions (alias)](https://docs.clawd.bot/sessions)
- [Session tools](https://docs.clawd.bot/session-tool)
- [Queue](https://docs.clawd.bot/queue)
- [Slash commands](https://docs.clawd.bot/slash-commands)
- [RPC adapters](https://docs.clawd.bot/rpc)
- [TypeBox schemas](https://docs.clawd.bot/typebox)
- [Presence](https://docs.clawd.bot/presence)
- [Discovery + transports](https://docs.clawd.bot/discovery)
- [Bonjour](https://docs.clawd.bot/bonjour)
- [Provider routing](https://docs.clawd.bot/provider-routing)
- [Groups](https://docs.clawd.bot/groups)
- [Group messages](https://docs.clawd.bot/group-messages)
- [Architecture](/architecture)
- [Agent runtime](/agent)
- [Agent workspace](/agent-workspace)
- [Agent loop](/agent-loop)
- [Multi-agent routing](/multi-agent)
- [Sessions](/session)
- [Sessions (alias)](/sessions)
- [Session tools](/session-tool)
- [Queue](/queue)
- [Slash commands](/slash-commands)
- [RPC adapters](/rpc)
- [TypeBox schemas](/typebox)
- [Presence](/presence)
- [Discovery + transports](/discovery)
- [Bonjour](/bonjour)
- [Provider routing](/provider-routing)
- [Groups](/groups)
- [Group messages](/group-messages)
## Providers + ingress
- [WhatsApp](https://docs.clawd.bot/whatsapp)
- [Telegram](https://docs.clawd.bot/telegram)
- [Telegram (grammY notes)](https://docs.clawd.bot/grammy)
- [Slack](https://docs.clawd.bot/slack)
- [Discord](https://docs.clawd.bot/discord)
- [Signal](https://docs.clawd.bot/signal)
- [iMessage](https://docs.clawd.bot/imessage)
- [WebChat](https://docs.clawd.bot/webchat)
- [Webhooks](https://docs.clawd.bot/webhook)
- [Gmail Pub/Sub](https://docs.clawd.bot/gmail-pubsub)
- [WhatsApp](/whatsapp)
- [Telegram](/telegram)
- [Telegram (grammY notes)](/grammy)
- [Slack](/slack)
- [Discord](/discord)
- [Signal](/signal)
- [iMessage](/imessage)
- [WebChat](/webchat)
- [Webhooks](/webhook)
- [Gmail Pub/Sub](/gmail-pubsub)
## Gateway + operations
- [Gateway runbook](https://docs.clawd.bot/gateway)
- [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
- [Gateway lock](https://docs.clawd.bot/gateway-lock)
- [Background process](https://docs.clawd.bot/background-process)
- [Health](https://docs.clawd.bot/health)
- [Heartbeat](https://docs.clawd.bot/heartbeat)
- [Doctor](https://docs.clawd.bot/doctor)
- [Logging](https://docs.clawd.bot/logging)
- [Dashboard](https://docs.clawd.bot/dashboard)
- [Control UI](https://docs.clawd.bot/control-ui)
- [Remote access](https://docs.clawd.bot/remote)
- [Remote gateway README](https://docs.clawd.bot/remote-gateway-readme)
- [Tailscale](https://docs.clawd.bot/tailscale)
- [Security](https://docs.clawd.bot/security)
- [Troubleshooting](https://docs.clawd.bot/troubleshooting)
- [Gateway runbook](/gateway)
- [Gateway pairing](/gateway/pairing)
- [Gateway lock](/gateway-lock)
- [Background process](/background-process)
- [Health](/health)
- [Heartbeat](/heartbeat)
- [Doctor](/doctor)
- [Logging](/logging)
- [Dashboard](/dashboard)
- [Control UI](/control-ui)
- [Remote access](/remote)
- [Remote gateway README](/remote-gateway-readme)
- [Tailscale](/tailscale)
- [Security](/security)
- [Troubleshooting](/troubleshooting)
## Tools + automation
- [Tools surface](https://docs.clawd.bot/tools)
- [Bash tool](https://docs.clawd.bot/bash)
- [Elevated mode](https://docs.clawd.bot/elevated)
- [Cron jobs](https://docs.clawd.bot/cron-jobs)
- [Thinking + verbose](https://docs.clawd.bot/thinking)
- [Models](https://docs.clawd.bot/models)
- [Agent send CLI](https://docs.clawd.bot/agent-send)
- [Terminal UI](https://docs.clawd.bot/tui)
- [Browser control](https://docs.clawd.bot/browser)
- [Browser (Linux troubleshooting)](https://docs.clawd.bot/browser-linux-troubleshooting)
- [Tools surface](/tools)
- [Bash tool](/bash)
- [Elevated mode](/elevated)
- [Cron jobs](/cron-jobs)
- [Thinking + verbose](/thinking)
- [Models](/models)
- [Agent send CLI](/agent-send)
- [Terminal UI](/tui)
- [Browser control](/browser)
- [Browser (Linux troubleshooting)](/browser-linux-troubleshooting)
## Nodes, media, voice
- [Nodes overview](https://docs.clawd.bot/nodes)
- [Camera](https://docs.clawd.bot/camera)
- [Images](https://docs.clawd.bot/images)
- [Audio](https://docs.clawd.bot/audio)
- [Location command](https://docs.clawd.bot/location-command)
- [Voice wake](https://docs.clawd.bot/voicewake)
- [Talk mode](https://docs.clawd.bot/talk)
- [Nodes overview](/nodes)
- [Camera](/camera)
- [Images](/images)
- [Audio](/audio)
- [Location command](/location-command)
- [Voice wake](/voicewake)
- [Talk mode](/talk)
## Platforms
- [macOS app overview](https://docs.clawd.bot/macos)
- [macOS dev setup](https://docs.clawd.bot/mac/dev-setup)
- [macOS menu bar](https://docs.clawd.bot/mac/menu-bar)
- [macOS voice wake](https://docs.clawd.bot/mac/voicewake)
- [macOS voice overlay](https://docs.clawd.bot/mac/voice-overlay)
- [macOS WebChat](https://docs.clawd.bot/mac/webchat)
- [macOS Canvas](https://docs.clawd.bot/mac/canvas)
- [macOS child process](https://docs.clawd.bot/mac/child-process)
- [macOS health](https://docs.clawd.bot/mac/health)
- [macOS icon](https://docs.clawd.bot/mac/icon)
- [macOS logging](https://docs.clawd.bot/mac/logging)
- [macOS permissions](https://docs.clawd.bot/mac/permissions)
- [macOS remote](https://docs.clawd.bot/mac/remote)
- [macOS signing](https://docs.clawd.bot/mac/signing)
- [macOS release](https://docs.clawd.bot/mac/release)
- [macOS bun gateway](https://docs.clawd.bot/mac/bun)
- [macOS XPC](https://docs.clawd.bot/mac/xpc)
- [macOS skills](https://docs.clawd.bot/mac/skills)
- [macOS Peekaboo plan](https://docs.clawd.bot/mac/peekaboo)
- [iOS node](https://docs.clawd.bot/ios)
- [Android node](https://docs.clawd.bot/android)
- [Windows app](https://docs.clawd.bot/windows)
- [Linux app](https://docs.clawd.bot/linux)
- [Web surfaces](https://docs.clawd.bot/web)
- [macOS app overview](/macos)
- [macOS dev setup](/mac/dev-setup)
- [macOS menu bar](/mac/menu-bar)
- [macOS voice wake](/mac/voicewake)
- [macOS voice overlay](/mac/voice-overlay)
- [macOS WebChat](/mac/webchat)
- [macOS Canvas](/mac/canvas)
- [macOS child process](/mac/child-process)
- [macOS health](/mac/health)
- [macOS icon](/mac/icon)
- [macOS logging](/mac/logging)
- [macOS permissions](/mac/permissions)
- [macOS remote](/mac/remote)
- [macOS signing](/mac/signing)
- [macOS release](/mac/release)
- [macOS bun gateway](/mac/bun)
- [macOS XPC](/mac/xpc)
- [macOS skills](/mac/skills)
- [macOS Peekaboo plan](/mac/peekaboo)
- [iOS node](/ios)
- [Android node](/android)
- [Windows app](/windows)
- [Linux app](/linux)
- [Web surfaces](/web)
## Workspace + templates
- [Skills](https://docs.clawd.bot/skills)
- [ClawdHub](https://docs.clawd.bot/clawdhub)
- [Skills config](https://docs.clawd.bot/skills-config)
- [Default AGENTS](https://docs.clawd.bot/AGENTS.default)
- [Templates: AGENTS](https://docs.clawd.bot/templates/AGENTS)
- [Templates: BOOTSTRAP](https://docs.clawd.bot/templates/BOOTSTRAP)
- [Templates: IDENTITY](https://docs.clawd.bot/templates/IDENTITY)
- [Templates: SOUL](https://docs.clawd.bot/templates/SOUL)
- [Templates: TOOLS](https://docs.clawd.bot/templates/TOOLS)
- [Templates: USER](https://docs.clawd.bot/templates/USER)
- [Skills](/skills)
- [ClawdHub](/clawdhub)
- [Skills config](/skills-config)
- [Default AGENTS](/AGENTS.default)
- [Templates: AGENTS](/templates/AGENTS)
- [Templates: BOOTSTRAP](/templates/BOOTSTRAP)
- [Templates: IDENTITY](/templates/IDENTITY)
- [Templates: SOUL](/templates/SOUL)
- [Templates: TOOLS](/templates/TOOLS)
- [Templates: USER](/templates/USER)
## Experiments + proposals
- [Onboarding config protocol](https://docs.clawd.bot/onboarding-config-protocol)
- [Research: memory](https://docs.clawd.bot/research/memory)
- [Proposal: model config](https://docs.clawd.bot/proposals/model-config)
- [Onboarding config protocol](/onboarding-config-protocol)
- [Research: memory](/research/memory)
- [Proposal: model config](/proposals/model-config)
## Testing + release
- [Testing](https://docs.clawd.bot/test)
- [Release checklist](https://docs.clawd.bot/RELEASING)
- [Device models](https://docs.clawd.bot/device-models)
- [Testing](/test)
- [Release checklist](/RELEASING)
- [Device models](/device-models)

4
docs/imessage.md
View File

@@ -43,7 +43,7 @@ DMs:
- Approve via:
- `clawdbot pairing list --provider imessage`
- `clawdbot pairing approve --provider imessage <CODE>`
- Pairing is the default token exchange for iMessage DMs. Details: https://docs.clawd.bot/pairing
- Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/pairing)
Groups:
- `imessage.groupPolicy = open | allowlist | disabled`.
@@ -71,7 +71,7 @@ imsg chats --limit 20
```
## Configuration reference (iMessage)
Full configuration: https://docs.clawd.bot/configuration
Full configuration: [Configuration](/configuration)
Provider options:
- `imessage.enabled`: enable/disable provider startup.

84
docs/index.md
View File

@@ -19,8 +19,8 @@ read_when:
<p align="center">
<a href="https://github.com/clawdbot/clawdbot">GitHub</a> ·
<a href="https://github.com/clawdbot/clawdbot/releases">Releases</a> ·
<a href="https://docs.clawd.bot">Docs</a> ·
<a href="https://docs.clawd.bot/clawd">Clawd setup</a>
<a href="/">Docs</a> ·
<a href="/clawd">Clawd setup</a>
</p>
CLAWDBOT bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono).
@@ -28,8 +28,8 @@ It’s built for [Clawd](https://clawd.me), a space lobster who needed a TARDIS.
## Start here
- **New install from zero:** https://docs.clawd.bot/getting-started
- **Guided setup (recommended):** https://docs.clawd.bot/wizard (`clawdbot onboard`)
- **New install from zero:** [Getting started](/getting-started)
- **Guided setup (recommended):** [Wizard](/wizard) (`clawdbot onboard`)
## How it works
@@ -60,8 +60,8 @@ Most operations flow through the **Gateway** (`clawdbot gateway`), a single long
- **Loopback-first**: Gateway WS defaults to `ws://127.0.0.1:18789`.
- For Tailnet access, run `clawdbot gateway --bind tailnet --token ...` (token is required for non-loopback binds).
- **Bridge for nodes**: optional LAN/tailnet-facing bridge on `tcp://0.0.0.0:18790` for paired nodes (Bonjour-discoverable).
- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [`docs/configuration.md`](https://docs.clawd.bot/configuration) (`canvasHost`).
- **Remote use**: SSH tunnel or tailnet/VPN; see [`docs/remote.md`](https://docs.clawd.bot/remote) and [`docs/discovery.md`](https://docs.clawd.bot/discovery).
- **Canvas host**: HTTP file server on `canvasHost.port` (default `18793`), serving `/__clawdbot__/canvas/` for node WebViews; see [`docs/configuration.md`](/configuration) (`canvasHost`).
- **Remote use**: SSH tunnel or tailnet/VPN; see [`docs/remote.md`](/remote) and [`docs/discovery.md`](/discovery).
## Features (high level)
@@ -135,45 +135,45 @@ Example:
## Docs
- Start here:
- [Docs hubs (all pages linked)](https://docs.clawd.bot/hubs)
- [FAQ](https://docs.clawd.bot/faq) ← *common questions answered*
- [Configuration](https://docs.clawd.bot/configuration)
- [Slash commands](https://docs.clawd.bot/slash-commands)
- [Multi-agent routing](https://docs.clawd.bot/multi-agent)
- [Updating / rollback](https://docs.clawd.bot/updating)
- [Pairing (DM + nodes)](https://docs.clawd.bot/pairing)
- [Nix mode](https://docs.clawd.bot/nix)
- [Clawd personal assistant setup](https://docs.clawd.bot/clawd)
- [Skills](https://docs.clawd.bot/skills)
- [Skills config](https://docs.clawd.bot/skills-config)
- [Workspace templates](https://docs.clawd.bot/templates/AGENTS)
- [RPC adapters](https://docs.clawd.bot/rpc)
- [Gateway runbook](https://docs.clawd.bot/gateway)
- [Nodes (iOS/Android)](https://docs.clawd.bot/nodes)
- [Web surfaces (Control UI)](https://docs.clawd.bot/web)
- [Discovery + transports](https://docs.clawd.bot/discovery)
- [Remote access](https://docs.clawd.bot/remote)
- [Docs hubs (all pages linked)](/hubs)
- [FAQ](/faq) ← *common questions answered*
- [Configuration](/configuration)
- [Slash commands](/slash-commands)
- [Multi-agent routing](/multi-agent)
- [Updating / rollback](/updating)
- [Pairing (DM + nodes)](/pairing)
- [Nix mode](/nix)
- [Clawd personal assistant setup](/clawd)
- [Skills](/skills)
- [Skills config](/skills-config)
- [Workspace templates](/templates/AGENTS)
- [RPC adapters](/rpc)
- [Gateway runbook](/gateway)
- [Nodes (iOS/Android)](/nodes)
- [Web surfaces (Control UI)](/web)
- [Discovery + transports](/discovery)
- [Remote access](/remote)
- Providers and UX:
- [WebChat](https://docs.clawd.bot/webchat)
- [Control UI (browser)](https://docs.clawd.bot/control-ui)
- [Telegram](https://docs.clawd.bot/telegram)
- [Discord](https://docs.clawd.bot/discord)
- [iMessage](https://docs.clawd.bot/imessage)
- [Groups](https://docs.clawd.bot/groups)
- [WhatsApp group messages](https://docs.clawd.bot/group-messages)
- [Media: images](https://docs.clawd.bot/images)
- [Media: audio](https://docs.clawd.bot/audio)
- [WebChat](/webchat)
- [Control UI (browser)](/control-ui)
- [Telegram](/telegram)
- [Discord](/discord)
- [iMessage](/imessage)
- [Groups](/groups)
- [WhatsApp group messages](/group-messages)
- [Media: images](/images)
- [Media: audio](/audio)
- Companion apps:
- [macOS app](https://docs.clawd.bot/macos)
- [iOS app](https://docs.clawd.bot/ios)
- [Android app](https://docs.clawd.bot/android)
- [Windows app](https://docs.clawd.bot/windows)
- [Linux app](https://docs.clawd.bot/linux)
- [macOS app](/macos)
- [iOS app](/ios)
- [Android app](/android)
- [Windows app](/windows)
- [Linux app](/linux)
- Ops and safety:
- [Sessions](https://docs.clawd.bot/session)
- [Cron jobs](https://docs.clawd.bot/cron-jobs)
- [Security](https://docs.clawd.bot/security)
- [Troubleshooting](https://docs.clawd.bot/troubleshooting)
- [Sessions](/session)
- [Cron jobs](/cron-jobs)
- [Security](/security)
- [Troubleshooting](/troubleshooting)
## The name

22
docs/ios.md
View File

@@ -61,7 +61,7 @@ If browse works, but the iOS node can’t connect, try resolving one instance:
dns-sd -L "<instance name>" _clawdbot-bridge._tcp local.
```
More debugging notes: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
More debugging notes: [`docs/bonjour.md`](/bonjour).
#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
@@ -70,7 +70,7 @@ If the iOS node and the gateway are on different networks but connected via Tail
1) Set up a DNS-SD zone (example `clawdbot.internal.`) on the gateway host and publish `_clawdbot-bridge._tcp` records.
2) Configure Tailscale split DNS for `clawdbot.internal` pointing at that DNS server.
Details and example CoreDNS config: [`docs/bonjour.md`](https://docs.clawd.bot/bonjour).
Details and example CoreDNS config: [`docs/bonjour.md`](/bonjour).
### 3) Connect from the iOS node app
@@ -102,7 +102,7 @@ clawdbot nodes approve <requestId>
After approval, the iOS node receives/stores the token and reconnects authenticated.
Pairing details: [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing).
Pairing details: [`docs/gateway/pairing.md`](/gateway/pairing).
### 5) Verify the node is connected
@@ -169,7 +169,7 @@ The response includes `{ format, base64 }` image data (default `format="jpeg"`;
- **iOS in background:** all `canvas.*` commands fail fast with `NODE_BACKGROUND_UNAVAILABLE` (bring the iOS node app to foreground).
- **Return to default scaffold:** `canvas.navigate` with `{"url":""}` or `{"url":"/"}` returns to the built-in scaffold page.
- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](https://docs.clawd.bot/discovery)).
- **mDNS blocked:** some networks block multicast; use a different LAN or plan a tailnet-capable bridge (see [`docs/discovery.md`](/discovery)).
- **Wrong node selector:** `--node` can be the node id (UUID), display name (e.g. `iOS Node`), IP, or an unambiguous prefix. If it’s ambiguous, the CLI will tell you.
- **Stale pairing / Keychain cleared:** if the pairing token is missing (or iOS Keychain was wiped), the node must pair again; approve a new pending request.
- **App reinstall but no reconnect:** the node restores `instanceId` + last bridge preference from Keychain; if it still comes up “unpaired”, verify Keychain persistence on your device/simulator and re-pair once.
@@ -195,8 +195,8 @@ Non-goals (v1):
### Current repo reality (constraints we respect)
- The Gateway WebSocket server binds to `127.0.0.1:18789` ([`src/gateway/server.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/gateway/server.ts)) with an optional `CLAWDBOT_GATEWAY_TOKEN`.
- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes ([`docs/configuration.md`](https://docs.clawd.bot/configuration)).
- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](https://docs.clawd.bot/mac/canvas)).
- The Gateway exposes a Canvas file server (`canvasHost`) on `canvasHost.port` (default `18793`), so nodes can `canvas.navigate` to `http://<lanHost>:18793/__clawdbot__/canvas/` and auto-reload on file changes ([`docs/configuration.md`](/configuration)).
- macOS “Canvas” is controlled via the Gateway node protocol (`canvas.*`), matching iOS/Android ([`docs/mac/canvas.md`](/mac/canvas)).
- Voice wake forwards via `GatewayChannel` to Gateway `agent` (mac app: `VoiceWakeForwarder` → `GatewayConnection.sendAgent`).
### Recommended topology (B): Gateway-owned Bridge + loopback Gateway
@@ -237,7 +237,7 @@ Desired behavior:
- If the Swift UI is present: show alert with Approve/Reject/Later.
- If the Swift UI is not present: `clawdbot` CLI can list pending requests and approve/reject.
See [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) for the API/events and storage.
See [`docs/gateway/pairing.md`](/gateway/pairing) for the API/events and storage.
CLI (headless approvals):
- `clawdbot nodes pending`
@@ -366,7 +366,7 @@ open Clawdbot.xcodeproj
## Related docs
- [`docs/gateway.md`](https://docs.clawd.bot/gateway) (gateway runbook)
- [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) (approval + storage)
- [`docs/bonjour.md`](https://docs.clawd.bot/bonjour) (discovery debugging)
- [`docs/discovery.md`](https://docs.clawd.bot/discovery) (LAN vs tailnet vs SSH)
- [`docs/gateway.md`](/gateway) (gateway runbook)
- [`docs/gateway/pairing.md`](/gateway/pairing) (approval + storage)
- [`docs/bonjour.md`](/bonjour) (discovery debugging)
- [`docs/discovery.md`](/discovery) (LAN vs tailnet vs SSH)

4
docs/mac/canvas.md
View File

@@ -10,7 +10,7 @@ read_when:
Status: draft spec · Date: 2025-12-12
Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See [`docs/configuration.md`](https://docs.clawd.bot/configuration).
Note: for iOS/Android nodes that should render agent-edited HTML/CSS/JS over the network, prefer the Gateway `canvasHost` (serves `~/clawd/canvas` over LAN/tailnet with live reload). A2UI is also **hosted by the Gateway** over HTTP. This doc focuses on the macOS in-app canvas panel. See [`docs/configuration.md`](/configuration).
Clawdbot can embed an agent-controlled “visual workspace” panel (“Canvas”) inside the macOS app using `WKWebView`, served via a **custom URL scheme** (no loopback HTTP port required).
@@ -81,7 +81,7 @@ Canvas is exposed via the Gateway **node bridge**, so the agent can:
This should be modeled after `WebChatManager`/`WebChatSwiftUIWindowController` but targeting `clawdbot-canvas://…` URLs.
Related:
- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See [`docs/macos.md`](https://docs.clawd.bot/macos).
- For “invoke the agent again from UI” flows, prefer the macOS deep link scheme (`clawdbot://agent?...`) so *any* UI surface (Canvas, WebChat, native views) can trigger a new agent run. See [`docs/macos.md`](/macos).
## Agent commands (current)

2
docs/mac/health.md
View File

@@ -25,4 +25,4 @@ How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar
- Cache the last good snapshot and the last error separately to avoid flicker; show the timestamp of each.
## When in doubt
- You can still use the CLI flow in [`docs/health.md`](https://docs.clawd.bot/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.
- You can still use the CLI flow in [`docs/health.md`](/health) (`clawdbot status`, `clawdbot status --deep`, `clawdbot health --json`) and tail `/tmp/clawdbot/clawdbot-*.log` for `web-heartbeat` / `web-reconnect`.

4
docs/mac/signing.md
View File

@@ -9,7 +9,7 @@ This app is usually built from [`scripts/package-mac-app.sh`](https://github.com
- sets a stable debug bundle identifier: `com.clawdbot.mac.debug`
- writes the Info.plist with that bundle id (override via `BUNDLE_ID=...`)
- calls [`scripts/codesign-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/codesign-mac-app.sh) to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see [`docs/mac/permissions.md`](https://docs.clawd.bot/mac/permissions)).
- calls [`scripts/codesign-mac-app.sh`](https://github.com/clawdbot/clawdbot/blob/main/scripts/codesign-mac-app.sh) to sign the main binary, bundled CLI, and app bundle so macOS treats each rebuild as the same signed bundle and keeps TCC permissions (notifications, accessibility, screen recording, mic, speech). For stable permissions, use a real signing identity; ad-hoc is opt-in and fragile (see [`docs/mac/permissions.md`](/mac/permissions)).
- uses `CODESIGN_TIMESTAMP=auto` by default; it enables trusted timestamps for Developer ID signatures. Set `CODESIGN_TIMESTAMP=off` to skip timestamping (offline debug builds).
- inject build metadata into Info.plist: `ClawdbotBuildTimestamp` (UTC) and `ClawdbotGitCommit` (short hash) so the About pane can show build, git, and debug/release channel.
- **Packaging requires Bun**: The embedded gateway relay is compiled using `bun`. Ensure it is installed (`curl -fsSL https://bun.sh/install | bash`).
@@ -26,7 +26,7 @@ SIGN_IDENTITY="-" scripts/package-mac-app.sh # explicit ad-hoc (same cave
```
### Ad-hoc Signing Note
When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see [`docs/mac/permissions.md`](https://docs.clawd.bot/mac/permissions) for recovery steps.
When signing with `SIGN_IDENTITY="-"` (ad-hoc), the script automatically disables the **Hardened Runtime** (`--options runtime`). This is necessary to prevent crashes when the app attempts to load embedded frameworks (like Sparkle) that do not share the same Team ID. Ad-hoc signatures also break TCC permission persistence; see [`docs/mac/permissions.md`](/mac/permissions) for recovery steps.
## Build metadata for About

2
docs/mac/xpc.md
View File

@@ -21,7 +21,7 @@ read_when:
- UI automation uses a separate UNIX socket named `bridge.sock` and the PeekabooBridge JSON protocol.
- Host preference order (client-side): Peekaboo.app → Claude.app → Clawdbot.app → local execution.
- Security: bridge hosts require TeamID `Y5PE65HELJ`; DEBUG-only same-UID escape hatch is guarded by `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` (Peekaboo convention).
- See: [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo) for the Clawdbot plan and naming.
- See: [`docs/mac/peekaboo.md`](/mac/peekaboo) for the Clawdbot plan and naming.
### Mach/XPC (future direction)
- Still optional for internal app services, but **not required** for automation now that node.invoke is the surface.

2
docs/macos.md
View File

@@ -13,7 +13,7 @@ Author: steipete · Status: draft spec · Date: 2025-12-20
- Shows native notifications for Clawdbot/clawdbot events.
- Owns TCC prompts (Notifications, Accessibility, Screen Recording, Automation/AppleScript, Microphone, Speech Recognition).
- Runs (or connects to) the **Gateway** and exposes itself as a **node** so agents can reach macOS‑only features.
- Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](https://docs.clawd.bot/mac/peekaboo)).
- Hosts **PeekabooBridge** for UI automation (consumed by `peekaboo`; see [`docs/mac/peekaboo.md`](/mac/peekaboo)).
- Installs a single CLI (`clawdbot`) by symlinking the bundled binary.
## High-level design

4
docs/model-failover.md
View File

@@ -85,9 +85,9 @@ timeouts that exhausted profile rotation.
## Related config
See [`docs/configuration.md`](https://docs.clawd.bot/configuration) for:
See [`docs/configuration.md`](/configuration) for:
- `auth.profiles` / `auth.order`
- `agent.model.primary` / `agent.model.fallbacks`
- `agent.imageModel` routing
See [`docs/models.md`](https://docs.clawd.bot/models) for the broader model selection and fallback overview.
See [`docs/models.md`](/models) for the broader model selection and fallback overview.

6
docs/models.md
View File

@@ -7,7 +7,7 @@ read_when:
---
# Models CLI plan
See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
See [`docs/model-failover.md`](/model-failover) for how auth profiles rotate (OAuth vs API keys), cooldowns, and how that interacts with model fallbacks.
Goal: give clear model visibility + control (configured vs available), plus scan tooling
that prefers tool-call + image-capable models and maintains ordered fallbacks.
@@ -83,7 +83,7 @@ Output
- Image routing uses `agent.imageModel` **only when configured** and the primary
model lacks image input.
- Persist last successful provider/model to session entry; auth profile success is global.
- See [`docs/model-failover.md`](https://docs.clawd.bot/model-failover) for auth profile rotation, cooldowns, and timeout handling.
- See [`docs/model-failover.md`](/model-failover) for auth profile rotation, cooldowns, and timeout handling.
## Tests
@@ -93,5 +93,5 @@ Output
## Docs
- Update [`docs/configuration.md`](https://docs.clawd.bot/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
- Update [`docs/configuration.md`](/configuration) with `agent.models` + `agent.model` + `agent.imageModel`.
- Keep this doc current when CLI surface or scan logic changes.

4
docs/nix.md
View File

@@ -91,5 +91,5 @@ packaging and Nix builds (which do not rely on a full Xcode toolchain).
## Related
- [nix-clawdbot](https://github.com/clawdbot/nix-clawdbot) — full setup guide
- [Wizard](https://docs.clawd.bot/wizard) — non-Nix CLI setup
- [Docker](https://docs.clawd.bot/docker) — containerized setup
- [Wizard](/wizard) — non-Nix CLI setup
- [Docker](/docker) — containerized setup

2
docs/nodes.md
View File

@@ -14,7 +14,7 @@ macOS can also run in **node mode**: the menubar app connects to the Gateway’s
## Pairing + status
Pairing is gateway-owned and approval-based. See [`docs/gateway/pairing.md`](https://docs.clawd.bot/gateway/pairing) for the full flow.
Pairing is gateway-owned and approval-based. See [`docs/gateway/pairing.md`](/gateway/pairing) for the full flow.
Quick CLI:

22
docs/pairing.md
View File

@@ -14,13 +14,13 @@ It is used in two places:
1) **DM pairing** (who is allowed to talk to the bot)
2) **Node pairing** (which devices/nodes are allowed to join the gateway network)
Security context: https://docs.clawd.bot/security
Security context: [Security](/security)
## 1) DM pairing (inbound chat access)
When a provider is configured with DM policy `pairing`, unknown senders get a short code and their message is **not processed** until you approve.
Default DM policies are documented in: https://docs.clawd.bot/security
Default DM policies are documented in: [Security](/security)
### Approve a sender
@@ -64,7 +64,7 @@ Stored under `~/.clawdbot/nodes/`:
### Details
Full protocol + design notes: https://docs.clawd.bot/gateway/pairing
Full protocol + design notes: [Gateway pairing](/gateway/pairing)
### Source of truth (code)
@@ -74,12 +74,12 @@ Full protocol + design notes: https://docs.clawd.bot/gateway/pairing
## Related docs
- Security model + prompt injection: https://docs.clawd.bot/security
- Updating safely (run doctor): https://docs.clawd.bot/updating
- Security model + prompt injection: [Security](/security)
- Updating safely (run doctor): [Updating](/updating)
- Provider configs:
- Telegram: https://docs.clawd.bot/telegram
- WhatsApp: https://docs.clawd.bot/whatsapp
- Signal: https://docs.clawd.bot/signal
- iMessage: https://docs.clawd.bot/imessage
- Discord: https://docs.clawd.bot/discord
- Slack: https://docs.clawd.bot/slack
- Telegram: [Telegram](/telegram)
- WhatsApp: [WhatsApp](/whatsapp)
- Signal: [Signal](/signal)
- iMessage: [iMessage](/imessage)
- Discord: [Discord](/discord)
- Slack: [Slack](/slack)

2
docs/plans/cron-add-hardening.md
View File

@@ -43,7 +43,7 @@ Recent gateway logs show repeated `cron.add` failures with invalid parameters (m
- [x] Fix UI CronStatus type to match gateway (`jobs` instead of `jobCount`).
- [x] Update cron UI provider select to include Discord/Slack/Signal/iMessage.
- [x] Update macOS CronJobEditor provider picker + enum to include Slack/Signal/iMessage.
- [x] Document cron compatibility normalization policy in [`docs/cron-jobs.md`](https://docs.clawd.bot/cron-jobs).
- [x] Document cron compatibility normalization policy in [`docs/cron-jobs.md`](/cron-jobs).
### Phase 2 — Input normalization + tooling hardening
- [x] Add shared cron input normalization helpers (`normalizeCronJobCreate`/`normalizeCronJobPatch`).

8
docs/plans/group-policy-hardening.md
View File

@@ -69,8 +69,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
### Phase 3: Documentation Updates
**Files**:
- [`docs/groups.md`](https://docs.clawd.bot/groups)
- [`docs/telegram.md`](https://docs.clawd.bot/telegram)
- [`docs/groups.md`](/groups)
- [`docs/telegram.md`](/telegram)
**Changes**:
- Document `tg:` alias and case-insensitive prefixes for Telegram allowlists.
@@ -90,8 +90,8 @@ Follow-up hardening work ensures Telegram allowlists behave consistently across
|------|-------------|-------------|
| [`src/telegram/bot.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.ts) | Fix | Trim allowlist values; strip `telegram:` / `tg:` prefixes case-insensitively |
| [`src/telegram/bot.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/telegram/bot.test.ts) | Test | Add DM + group allowlist coverage for `TG:` prefix + whitespace |
| [`docs/groups.md`](https://docs.clawd.bot/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
| [`docs/telegram.md`](https://docs.clawd.bot/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
| [`docs/groups.md`](/groups) | Docs | Mention `tg:` alias + case-insensitive prefixes |
| [`docs/telegram.md`](/telegram) | Docs | Mention `tg:` alias + case-insensitive prefixes |
---

4
docs/remote.md
View File

@@ -8,7 +8,7 @@ read_when:
This repo supports “remote over SSH” by keeping a single Gateway (the master) running on a host (e.g., your Mac Studio) and connecting clients to it.
- For **operators (you / the macOS app)**: SSH tunneling is the universal fallback.
- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](https://docs.clawd.bot/discovery)).
- For **nodes (iOS/Android and future devices)**: prefer the Gateway **Bridge** when on the same LAN/tailnet (see [`docs/discovery.md`](/discovery)).
## The core idea
@@ -58,4 +58,4 @@ WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects direct
The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
Runbook: [`docs/mac/remote.md`](https://docs.clawd.bot/mac/remote).
Runbook: [`docs/mac/remote.md`](/mac/remote).

4
docs/rpc.md
View File

@@ -14,7 +14,7 @@ Clawdbot integrates external CLIs via JSON-RPC. Two patterns are used today.
- Health probe: `/api/v1/check`.
- Clawdbot owns lifecycle when `signal.autoStart=true`.
See [`docs/signal.md`](https://docs.clawd.bot/signal) for setup and endpoints.
See [`docs/signal.md`](/signal) for setup and endpoints.
## Pattern B: stdio child process (imsg)
- Clawdbot spawns `imsg rpc` as a child process.
@@ -27,7 +27,7 @@ Core methods used:
- `send`
- `chats.list` (probe/diagnostics)
See [`docs/imessage.md`](https://docs.clawd.bot/imessage) for setup and addressing (`chat_id` preferred).
See [`docs/imessage.md`](/imessage) for setup and addressing (`chat_id` preferred).
## Adapter guidelines
- Gateway owns the process (start/stop tied to provider lifecycle).

8
docs/security.md
View File

@@ -50,7 +50,7 @@ clawdbot pairing list --provider <provider>
clawdbot pairing approve --provider <provider> <code>
```
Details + files on disk: https://docs.clawd.bot/pairing
Details + files on disk: [Pairing](/pairing)
## Allowlists (DM + groups) — terminology
@@ -64,7 +64,7 @@ Clawdbot has two separate “who can trigger me?” layers:
- `groupPolicy="allowlist"` + `groupAllowFrom`: restrict who can trigger the bot *inside* a group session (WhatsApp/Telegram/Signal/iMessage).
- `discord.guilds` / `slack.channels`: per-surface allowlists + mention defaults.
Details: https://docs.clawd.bot/configuration and https://docs.clawd.bot/groups
Details: [Configuration](/configuration) and [Groups](/groups)
## Prompt injection (what it is, why it matters)
@@ -139,8 +139,8 @@ We're considering a `readOnlyMode` flag that prevents the AI from:
Two complementary approaches:
- **Run the full Gateway in Docker** (container boundary): https://docs.clawd.bot/docker
- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): https://docs.clawd.bot/configuration
- **Run the full Gateway in Docker** (container boundary): [Docker](/docker)
- **Per-session tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/configuration)
Note: to prevent cross-agent access, keep `perSession: true` so each session gets
its own container + workspace. `perSession: false` shares a single container.

2
docs/sessions.md
View File

@@ -5,4 +5,4 @@ read_when:
---
# Sessions
Canonical session management docs live in [`docs/session.md`](https://docs.clawd.bot/session).
Canonical session management docs live in [`docs/session.md`](/session).

14
docs/setup.md
View File

@@ -17,7 +17,7 @@ Last updated: 2026-01-01
## Prereqs (from source)
- Node `>=22`
- `pnpm`
- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](https://docs.clawd.bot/docker))
- Docker (optional; only for containerized setup/e2e — see [`docs/docker.md`](/docker))
## Tailoring strategy (so updates don’t hurt)
@@ -121,12 +121,12 @@ sudo loginctl enable-linger $USER
```
For always-on or multi-user servers, consider a **system** service instead of a
user service (no lingering needed). See [`docs/gateway.md`](https://docs.clawd.bot/gateway) for the systemd notes.
user service (no lingering needed). See [`docs/gateway.md`](/gateway) for the systemd notes.
## Related docs
- [`docs/gateway.md`](https://docs.clawd.bot/gateway) (Gateway runbook; flags, supervision, ports)
- [`docs/configuration.md`](https://docs.clawd.bot/configuration) (config schema + examples)
- [`docs/discord.md`](https://docs.clawd.bot/discord) and [`docs/telegram.md`](https://docs.clawd.bot/telegram) (reply tags + replyToMode settings)
- [`docs/clawd.md`](https://docs.clawd.bot/clawd) (personal assistant setup)
- [`docs/macos.md`](https://docs.clawd.bot/macos) (macOS app behavior; gateway lifecycle + “Attach only”)
- [`docs/gateway.md`](/gateway) (Gateway runbook; flags, supervision, ports)
- [`docs/configuration.md`](/configuration) (config schema + examples)
- [`docs/discord.md`](/discord) and [`docs/telegram.md`](/telegram) (reply tags + replyToMode settings)
- [`docs/clawd.md`](/clawd) (personal assistant setup)
- [`docs/macos.md`](/macos) (macOS app behavior; gateway lifecycle + “Attach only”)

4
docs/signal.md
View File

@@ -46,7 +46,7 @@ DMs:
- Approve via:
- `clawdbot pairing list --provider signal`
- `clawdbot pairing approve --provider signal <CODE>`
- Pairing is the default token exchange for Signal DMs. Details: https://docs.clawd.bot/pairing
- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/pairing)
Groups:
- `signal.groupPolicy = open | allowlist | disabled`.
@@ -68,7 +68,7 @@ Groups:
- Usernames: `username:<name>` (if supported by your Signal account).
## Configuration reference (Signal)
Full configuration: https://docs.clawd.bot/configuration
Full configuration: [Configuration](/configuration)
Provider options:
- `signal.enabled`: enable/disable provider startup.

4
docs/skills.md
View File

@@ -142,10 +142,10 @@ copy). Workspace skills are user-owned and override both on name conflicts.
## Config reference
See [`docs/skills-config.md`](https://docs.clawd.bot/skills-config) for the full configuration schema.
See [`docs/skills-config.md`](/skills-config) for the full configuration schema.
## Looking for more skills?
Browse [ClawdHub](https://docs.clawd.bot/clawdhub).
Browse [ClawdHub](/clawdhub).
---

278
docs/slack.md
View File

@@ -5,95 +5,221 @@ read_when: "Setting up Slack or debugging Slack socket mode"
# Slack (socket mode)
Updated: 2026-01-06
## 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-...`).
3) **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
4) **Event Subscriptions** → enable events and subscribe to:
- `message.*` (includes edits/deletes/thread broadcasts)
- `app_mention`
- `reaction_added`, `reaction_removed`
- `member_joined_channel`, `member_left_channel`
- `channel_rename`
- `pin_added`, `pin_removed`
5) Invite the bot to channels you want it to read.
6) Slash Commands → create `/clawd` if you use `slack.slashCommand`. If you enable `commands.native`, add slash commands for the built-in chat commands (same names as `/help`).
7) App Home → enable the **Messages Tab** so users can DM the bot.
Status: production-ready for DMs + channels via Slack Socket Mode.
Use the manifest below so scopes and events stay in sync.
## What it is
- Slack bot provider owned by the Gateway.
- Socket Mode only (no inbound HTTP server required).
- Deterministic routing: replies always go back to Slack.
## Manifest (optional)
Use this Slack app manifest to create the app quickly (adjust the name/command if you want).
## Setup (fast path)
1) Create a Slack app.
2) Enable **Socket Mode** and create an **App Token** (`xapp-...`).
3) Install the app to your workspace and copy the **Bot Token** (`xoxb-...`).
4) Add required scopes + events (see Slack app manifest if needed).
5) Configure tokens and start the gateway.
Example:
```json5
```json
{
slack: {
enabled: true,
botToken: "xoxb-...",
appToken: "xapp-...",
dm: { policy: "pairing" },
channels: { "#general": { allow: true, requireMention: true } }
"display_information": {
"name": "Clawdbot",
"description": "Slack connector for Clawdbot"
},
"features": {
"bot_user": {
"display_name": "Clawdbot",
"always_online": false
},
"app_home": {
"messages_tab_enabled": true,
"messages_tab_read_only_enabled": false
},
"slash_commands": [
{
"command": "/clawd",
"description": "Send a message to Clawdbot",
"should_escape": false
}
]
},
"oauth_config": {
"scopes": {
"bot": [
"chat:write",
"channels:history",
"channels:read",
"groups:history",
"groups:read",
"groups:write",
"im:history",
"im:read",
"im:write",
"mpim:history",
"mpim:read",
"mpim:write",
"users:read",
"app_mentions:read",
"reactions:read",
"reactions:write",
"pins:read",
"pins:write",
"emoji:read",
"commands",
"files:read",
"files:write"
]
}
},
"settings": {
"socket_mode_enabled": true,
"event_subscriptions": {
"bot_events": [
"app_mention",
"message.channels",
"message.groups",
"message.im",
"message.mpim",
"reaction_added",
"reaction_removed",
"member_joined_channel",
"member_left_channel",
"channel_rename",
"pin_added",
"pin_removed"
]
}
}
}
```
## Access control (DMs + channels)
DMs:
- Default: `slack.dm.policy = "pairing"`.
- Unknown senders receive a pairing code; messages are ignored until approved.
- Approve via:
- `clawdbot pairing list --provider slack`
- `clawdbot pairing approve --provider slack <CODE>`
- Pairing is the default token exchange for Slack DMs. Details: https://docs.clawd.bot/pairing
If you enable `commands.native`, add one `slash_commands` entry per command you want to expose (matching the `/help` list).
Channels:
- `slack.groupPolicy = open | allowlist | disabled`.
- `slack.channels` acts as the allowlist when `groupPolicy = allowlist`.
- Mentions are required by default unless overridden per channel.
## Scopes (current vs optional)
Slack's Conversations API is type-scoped: you only need the scopes for the
conversation types you actually touch (channels, groups, im, mpim). See
https://api.slack.com/docs/conversations-api for the overview.
## How it works (behavior)
- Inbound messages are normalized into the shared provider envelope.
- Replies always route back to the same channel or DM.
- Threading: replies to a message stay in that thread if it was a thread message.
### Required by current code
- `chat:write` (send/update/delete messages via `chat.postMessage`)
https://api.slack.com/methods/chat.postMessage
- `im:write` (open DMs via `conversations.open` for user DMs)
https://api.slack.com/methods/conversations.open
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
(`conversations.history` in [`src/slack/actions.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/actions.ts))
https://api.slack.com/methods/conversations.history
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
(`conversations.info` in [`src/slack/monitor.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/monitor.ts))
https://api.slack.com/methods/conversations.info
- `users:read` (`users.info` in [`src/slack/monitor.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/monitor.ts) + [`src/slack/actions.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/slack/actions.ts))
https://api.slack.com/methods/users.info
- `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
https://api.slack.com/methods/reactions.get
https://api.slack.com/methods/reactions.add
- `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
https://api.slack.com/scopes/pins:read
https://api.slack.com/scopes/pins:write
- `emoji:read` (`emoji.list`)
https://api.slack.com/scopes/emoji:read
- `files:write` (uploads via `files.uploadV2`)
https://api.slack.com/messaging/files/uploading
## Commands
- Text commands: `commands.text = true` (standalone `/...` messages).
- Slack slash command: configure `slack.slashCommand` (separate from `commands.native`).
### Not needed today (but likely future)
- `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
- `groups:write` (only if we add private-channel management: create/rename/invite/archive)
- `chat:write.public` (only if we want to post to channels the bot isn't in)
https://api.slack.com/scopes/chat:write.public
- `users:read.email` (only if we need email fields from `users.info`)
https://api.slack.com/changelog/2017-04-narrowing-email-access
- `files:read` (only if we start listing/reading file metadata)
## Media + limits
- Files supported up to `slack.mediaMaxMb` (default 20 MB).
- Outbound chunking controlled by `slack.textChunkLimit`.
## Config
Slack uses Socket Mode only (no HTTP webhook server). Provide both tokens:
## Delivery targets (CLI/cron)
- DMs: `user:<id>`
- Channels: `channel:<id>`
```json
{
"slack": {
"enabled": true,
"botToken": "xoxb-...",
"appToken": "xapp-...",
"groupPolicy": "open",
"dm": {
"enabled": true,
"policy": "pairing",
"allowFrom": ["U123", "U456", "*"],
"groupEnabled": false,
"groupChannels": ["G123"]
},
"channels": {
"C123": { "allow": true, "requireMention": true },
"#general": { "allow": true, "requireMention": false }
},
"reactionNotifications": "own",
"reactionAllowlist": ["U123"],
"actions": {
"reactions": true,
"messages": true,
"pins": true,
"memberInfo": true,
"emojiList": true
},
"slashCommand": {
"enabled": true,
"name": "clawd",
"sessionPrefix": "slack:slash",
"ephemeral": true
},
"textChunkLimit": 4000,
"mediaMaxMb": 20
}
}
```
## Configuration reference (Slack)
Full configuration: https://docs.clawd.bot/configuration
Tokens can also be supplied via env vars:
- `SLACK_BOT_TOKEN`
- `SLACK_APP_TOKEN`
Provider options:
- `slack.enabled`: enable/disable provider startup.
- `slack.botToken`: bot token (env: `SLACK_BOT_TOKEN`).
- `slack.appToken`: app token (env: `SLACK_APP_TOKEN`).
- `slack.groupPolicy`: `open | allowlist | disabled` (default: open).
- `slack.channels`: channel allowlist + per-channel `requireMention`.
- `slack.textChunkLimit`: outbound chunk size (chars).
- `slack.mediaMaxMb`: inbound/outbound media cap (MB).
- `slack.reactionNotifications`: `off | own | all | allowlist`.
- `slack.reactionAllowlist`: user allowlist for reaction notifications.
- `slack.actions.reactions`: enable reaction tool actions.
- `slack.actions.messages`: enable message read/send/edit/delete actions.
- `slack.actions.pins`: enable pin actions.
- `slack.actions.search`: enable search actions.
- `slack.actions.permissions`: enable permission inspection actions.
- `slack.actions.memberInfo`: enable member info actions.
- `slack.actions.channelInfo`: enable channel info actions.
- `slack.actions.emojiList`: enable emoji list actions.
- `slack.slashCommand.*`: configure the Slack slash command endpoint (`name`, `sessionPrefix`, `ephemeral`).
- `slack.dm.enabled`: enable/disable DMs.
- `slack.dm.policy`: `pairing | allowlist | open | disabled` (default: pairing).
- `slack.dm.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
- `slack.dm.groupEnabled`: enable group DMs.
- `slack.dm.groupChannels`: group DM allowlist.
Ack reactions are controlled globally via `messages.ackReaction` +
`messages.ackReactionScope`.
Related global options:
- `routing.groupChat.mentionPatterns`.
- `commands.text`, `commands.useAccessGroups`.
- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
## Sessions + routing
- DMs share the `main` session (like WhatsApp/Telegram).
- Channels map to `slack:channel:<channelId>` sessions.
- Slash commands use `slack:slash:<userId>` sessions.
- Native command registration is controlled by `commands.native`; text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
- Full command list + config: [Slash commands](/slash-commands)
## DM security (pairing)
- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code.
- Approve via: `clawdbot pairing approve --provider slack <code>`.
- To allow anyone: set `slack.dm.policy="open"` and `slack.dm.allowFrom=["*"]`.
## Group policy
- `slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
- `allowlist` requires channels to be listed in `slack.channels`.
## Delivery targets
Use these with cron/CLI sends:
- `user:<id>` for DMs
- `channel:<id>` for channels
## Tool actions
Slack tool actions can be gated with `slack.actions.*`:
| Action group | Default | Notes |
| --- | --- | --- |
| reactions | enabled | React + list reactions |
| messages | enabled | Read/send/edit/delete |
| pins | enabled | Pin/unpin/list |
| memberInfo | enabled | Member info |
| emojiList | enabled | Custom emoji list |
## Notes
- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`); `routing.groupChat.mentionPatterns` also count as mentions.
- Reaction notifications follow `slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`).
- Attachments are downloaded to the media store when permitted and under the size limit.

4
docs/telegram.md
View File

@@ -43,7 +43,7 @@ Status: production-ready for bot DMs + groups via grammY. Long-polling by defaul
- Approve via:
- `clawdbot pairing list --provider telegram`
- `clawdbot pairing approve --provider telegram <CODE>`
- Pairing is the default token exchange used for Telegram DMs. Details: https://docs.clawd.bot/pairing
- Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/pairing)
Group gating:
- `telegram.groupPolicy = open | allowlist | disabled`.
@@ -68,7 +68,7 @@ Controlled by `telegram.replyToMode`:
- Example: `clawdbot send --provider telegram --to 123456789 "hi"`.
## Configuration reference (Telegram)
Full configuration: https://docs.clawd.bot/configuration
Full configuration: [Configuration](/configuration)
Provider options:
- `telegram.enabled`: enable/disable provider startup.

2
docs/thinking.md
View File

@@ -35,7 +35,7 @@ read_when:
- When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool result back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command); the tool output itself is not forwarded. These tool summaries are sent as soon as each tool finishes (separate bubbles), not as streaming deltas. If you toggle `/verbose on|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
## Related
- Elevated mode docs live in [`docs/elevated.md`](https://docs.clawd.bot/elevated).
- Elevated mode docs live in [`docs/elevated.md`](/elevated).
## Heartbeats
- Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).

2
docs/troubleshooting.md
View File

@@ -254,4 +254,4 @@ Then set in config:
}
```
**Full guide:** See [browser-linux-troubleshooting](https://docs.clawd.bot/browser-linux-troubleshooting)
**Full guide:** See [browser-linux-troubleshooting](/browser-linux-troubleshooting)

6
docs/updating.md
View File

@@ -71,7 +71,7 @@ Typical things it does:
- Detect and migrate older gateway services (launchd/systemd/schtasks) to current Clawdbot services.
- On Linux, ensure systemd user lingering (so the Gateway survives logout).
Details: https://docs.clawd.bot/doctor
Details: [Doctor](/doctor)
## Start / stop / restart the Gateway
@@ -88,7 +88,7 @@ If you’re supervised:
- Linux systemd user service: `systemctl --user restart clawdbot-gateway.service`
- Windows: restart the `Clawdbot Gateway` Scheduled Task (Task Scheduler)
Runbook + exact service labels: https://docs.clawd.bot/gateway
Runbook + exact service labels: [Gateway runbook](/gateway)
## Rollback / pinning (when something breaks)
@@ -134,5 +134,5 @@ git pull
## If you’re stuck
- Run `clawdbot doctor` again and read the output carefully (it often tells you the fix).
- Check: https://docs.clawd.bot/troubleshooting
- Check: [Troubleshooting](/troubleshooting)
- Ask in Discord: https://discord.gg/clawd

2
docs/web.md
View File

@@ -26,7 +26,7 @@ The UI talks directly to the Gateway WS and supports:
## Webhooks
When `hooks.enabled=true`, the Gateway also exposes a small webhook endpoint on the same HTTP server.
See [`docs/configuration.md`](https://docs.clawd.bot/configuration) → `hooks` for auth + payloads.
See [`docs/configuration.md`](/configuration) → `hooks` for auth + payloads.
## Config (default-on)

2
docs/webchat.md
View File

@@ -24,7 +24,7 @@ Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.
- You do not need to run a separate WebChat server.
## Configuration reference (WebChat)
Full configuration: https://docs.clawd.bot/configuration
Full configuration: [Configuration](/configuration)
Provider options:
- No dedicated `webchat.*` block. WebChat uses the gateway endpoint + auth settings below.

201
docs/whatsapp.md
View File

@@ -5,83 +5,152 @@ read_when:
---
# WhatsApp (web provider)
Updated: 2026-01-06
Updated: 2025-12-23
Status: WhatsApp Web via Baileys. Gateway owns the session(s).
Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
## What it is
- WhatsApp Web connection managed by the Gateway.
- Deterministic routing: replies always return to WhatsApp.
- DMs share the agent's main session; groups are isolated (`whatsapp:group:<jid>`).
## Goals
- Multiple WhatsApp accounts (multi-account) in one Gateway process.
- Deterministic routing: replies return to WhatsApp, no model routing.
- Model sees enough context to understand quoted replies.
## Setup (fast path)
1) Use a real mobile number (WhatsApp blocks most VoIP numbers).
2) Run `clawdbot login` and scan the QR (Linked Devices).
3) Start the gateway; the WhatsApp provider starts when a linked session exists.
4) Lock down DMs and groups (pairing + allowlists are default-safe).
## Architecture (who owns what)
- **Gateway** owns the Baileys socket and inbox loop.
- **CLI / macOS app** talk to the gateway; no direct Baileys use.
- **Active listener** is required for outbound sends; otherwise send fails fast.
Multi-account:
- `clawdbot login --account <id>`
- Configure `whatsapp.accounts.<id>` for per-account settings.
## Getting a phone number
## Access control (DMs + groups)
DMs:
- Default: `whatsapp.dmPolicy = "pairing"`.
- Unknown senders get a pairing code and are ignored until approved.
- Approve via:
- `clawdbot pairing list --provider whatsapp`
- `clawdbot pairing approve --provider whatsapp <CODE>`
- Pairing is the default token exchange for WhatsApp DMs. Details: https://docs.clawd.bot/pairing
WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked.
Groups:
- `whatsapp.groupPolicy = open | allowlist | disabled`.
- `whatsapp.groups` sets per-group defaults and becomes an allowlist when present (use `"*"` to allow all).
- Mention gating defaults to `requireMention: true` unless overridden.
**Recommended approaches:**
- **Local eSIM** from your country's mobile carrier (most reliable)
- Austria: [hot.at](https://www.hot.at)
- UK: [giffgaff](https://www.giffgaff.com) — free SIM, no contract
- **Prepaid SIM** — cheap, just needs to receive one SMS for verification
## How it works (behavior)
- Inbound messages are normalized into the shared provider envelope with reply context.
- Group replies require a mention by default (native mentions or `routing.groupChat.mentionPatterns`).
- Recent group history can be injected for context (see `routing.groupChat.historyLimit`).
**Avoid:** TextNow, Google Voice, most "free SMS" services — WhatsApp blocks these aggressively.
## Reply delivery
- Standard WhatsApp messages (no threaded replies).
- Text chunking is applied to stay within limits.
**Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
## Media
- Images/video/audio/documents supported.
- Default cap: 5 MB per item (override via `agent.mediaMaxMb`).
- Oversize media returns a warning instead of sending.
**WhatsApp Business:** You can use WhatsApp Business on the same phone with a different number. This is a great option if you want to keep your personal WhatsApp separate — just install WhatsApp Business and register it with Clawdbot's dedicated number.
## Delivery targets (CLI/cron)
- DMs: E.164 (`+15551234567`).
- Groups: group JID (`12345-678@g.us`).
## Login + credentials
- Login command: `clawdbot login` (QR via Linked Devices).
- Multi-account login: `clawdbot login --account <id>` (`<id>` = `accountId`).
- Default account (when `--account` is omitted): `default` if present, otherwise the first configured account id (sorted).
- Credentials stored in `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`.
- Backup copy at `creds.json.bak` (restored on corruption).
- Legacy compatibility: older installs stored Baileys files directly in `~/.clawdbot/credentials/`.
- Logout: `clawdbot logout` (or `--account <id>`) deletes WhatsApp auth state (but keeps shared `oauth.json`).
- Logged-out socket => error instructs re-link.
## Configuration reference (WhatsApp)
Full configuration: https://docs.clawd.bot/configuration
## Inbound flow (DM + group)
- WhatsApp events come from `messages.upsert` (Baileys).
- Inbox listeners are detached on shutdown to avoid accumulating event handlers in tests/restarts.
- Status/broadcast chats are ignored.
- Direct chats use E.164; groups use group JID.
- **DM policy**: `whatsapp.dmPolicy` controls direct chat access (default: `pairing`).
- Pairing: unknown senders get a pairing code (approve via `clawdbot pairing approve --provider whatsapp <code>`).
- Open: requires `whatsapp.allowFrom` to include `"*"`.
- Self messages are always allowed; “self-chat mode” still requires `whatsapp.allowFrom` to include your own number.
- **Group policy**: `whatsapp.groupPolicy` controls group handling (`open|disabled|allowlist`).
- `allowlist` uses `whatsapp.groupAllowFrom` (fallback: explicit `whatsapp.allowFrom`).
- **Self-chat mode**: avoids auto read receipts and ignores mention JIDs.
- Read receipts sent for non-self-chat DMs.
Provider options:
- `whatsapp.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
- `whatsapp.allowFrom`: DM allowlist (E.164). `open` requires `"*"`.
- `whatsapp.groupPolicy`: `open | allowlist | disabled` (default: open).
- `whatsapp.groupAllowFrom`: group sender allowlist (E.164).
- `whatsapp.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
- `whatsapp.textChunkLimit`: outbound chunk size (chars).
- `whatsapp.accounts`: per-account overrides:
- `whatsapp.accounts.<id>.enabled`
- `whatsapp.accounts.<id>.authDir`
- `whatsapp.accounts.<id>.dmPolicy`
- `whatsapp.accounts.<id>.allowFrom`
- `whatsapp.accounts.<id>.groupPolicy`
- `whatsapp.accounts.<id>.groupAllowFrom`
- `whatsapp.accounts.<id>.groups`
- `whatsapp.accounts.<id>.textChunkLimit`
## Message normalization (what the model sees)
- `Body` is the current message body with envelope.
- Quoted reply context is **always appended**:
```
[Replying to +1555 id:ABC123]
<quoted text or <media:...>>
[/Replying]
```
- Reply metadata also set:
- `ReplyToId` = stanzaId
- `ReplyToBody` = quoted body or media placeholder
- `ReplyToSender` = E.164 when known
- Media-only inbound messages use placeholders:
- `<media:image|video|audio|document|sticker>`
Runtime options (WhatsApp web provider):
- `web.enabled`: enable/disable provider startup.
- `web.heartbeatSeconds`: gateway heartbeat cadence.
- `web.reconnect.*`: reconnect backoff (`initialMs`, `maxMs`, `factor`, `jitter`, `maxAttempts`).
## Groups
- Groups map to `agent:<agentId>:whatsapp:group:<jid>` sessions.
- Group policy: `whatsapp.groupPolicy = open|disabled|allowlist` (default `open`).
- Activation modes:
- `mention` (default): requires @mention or regex match.
- `always`: always triggers.
- `/activation mention|always` is owner-only and must be sent as a standalone message.
- Owner = `whatsapp.allowFrom` (or self E.164 if unset).
- **History injection**:
- Recent messages (default 50) inserted under:
`[Chat messages since your last reply - for context]`
- Current message under:
`[Current message - respond to this]`
- Sender suffix appended: `[from: Name (+E164)]`
- Group metadata cached 5 min (subject + participants).
Related global options:
- `routing.groupChat.mentionPatterns`, `routing.groupChat.historyLimit`.
- `commands.text`, `commands.useAccessGroups`.
- `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`.
## Reply delivery (threading)
- WhatsApp Web sends standard messages (no quoted reply threading in the current gateway).
- Reply tags are ignored on this provider.
## Outbound send (text + media)
- Uses active web listener; error if gateway not running.
- Text chunking: 4k max per message.
- Media:
- Image/video/audio/document supported.
- Audio sent as PTT; `audio/ogg` => `audio/ogg; codecs=opus`.
- Caption only on first media item.
- Media fetch supports HTTP(S) and local paths.
- Animated GIFs: WhatsApp expects MP4 with `gifPlayback: true` for inline looping.
- CLI: `clawdbot send --media <mp4> --gif-playback`
- Gateway: `send` params include `gifPlayback: true`
## Media limits + optimization
- Default cap: 5 MB (per media item).
- Override: `agent.mediaMaxMb`.
- Images are auto-optimized to JPEG under cap (resize + quality sweep).
- Oversize media => error; media reply falls back to text warning.
## Heartbeats
- **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
- **Agent heartbeat** is global (`agent.heartbeat.*`) and runs in the main session.
- Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) + `HEARTBEAT_OK` skip behavior.
- Delivery defaults to the last used provider (or configured target).
## Reconnect behavior
- Backoff policy: `web.reconnect`:
- `initialMs`, `maxMs`, `factor`, `jitter`, `maxAttempts`.
- If maxAttempts reached, web monitoring stops (degraded).
- Logged-out => stop and require re-link.
## Config quick map
- `whatsapp.dmPolicy` (DM policy: pairing/allowlist/open/disabled).
- `whatsapp.allowFrom` (DM allowlist).
- `whatsapp.accounts.<accountId>.*` (per-account settings + optional `authDir`).
- `whatsapp.groupAllowFrom` (group sender allowlist).
- `whatsapp.groupPolicy` (group policy).
- `whatsapp.groups` (group allowlist + mention gating defaults; use `"*"` to allow all)
- `routing.groupChat.mentionPatterns`
- `routing.groupChat.historyLimit`
- `messages.messagePrefix` (inbound prefix)
- `messages.responsePrefix` (outbound prefix)
- `agent.mediaMaxMb`
- `agent.heartbeat.every`
- `agent.heartbeat.model` (optional override)
- `agent.heartbeat.target`
- `agent.heartbeat.to`
- `session.*` (scope, idle, store, mainKey)
- `web.enabled` (disable provider startup when false)
- `web.heartbeatSeconds`
- `web.reconnect.*`
## Logs + troubleshooting
- Subsystems: `whatsapp/inbound`, `whatsapp/outbound`, `web-heartbeat`, `web-reconnect`.
- Log file: `/tmp/clawdbot/clawdbot-YYYY-MM-DD.log` (configurable).
- Troubleshooting guide: [`docs/troubleshooting.md`](/troubleshooting).
## Tests
- [`src/web/auto-reply.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/auto-reply.test.ts) (mention gating, history injection, reply flow)
- [`src/web/monitor-inbox.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/monitor-inbox.test.ts) (inbound parsing + reply context)
- [`src/web/outbound.test.ts`](https://github.com/clawdbot/clawdbot/blob/main/src/web/outbound.test.ts) (send mapping + media)

10
docs/wizard.md
View File

@@ -59,7 +59,7 @@ It does **not** install or change anything on the remote host.
3) **Workspace**
- Default `~/clawd` (configurable).
- Seeds the workspace files needed for the agent bootstrap ritual.
- Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace)
- Full workspace layout + backup guide: [`docs/agent-workspace.md`](/agent-workspace)
4) **Gateway**
- Port, bind, auth mode, tailscale exposure.
@@ -165,7 +165,7 @@ Sessions are stored under `~/.clawdbot/agents/<agentId>/sessions/`.
## Related docs
- macOS app onboarding: [`docs/onboarding.md`](https://docs.clawd.bot/onboarding)
- Config reference: [`docs/configuration.md`](https://docs.clawd.bot/configuration)
- Providers: [`docs/whatsapp.md`](https://docs.clawd.bot/whatsapp), [`docs/telegram.md`](https://docs.clawd.bot/telegram), [`docs/discord.md`](https://docs.clawd.bot/discord), [`docs/signal.md`](https://docs.clawd.bot/signal), [`docs/imessage.md`](https://docs.clawd.bot/imessage)
- Skills: [`docs/skills.md`](https://docs.clawd.bot/skills), [`docs/skills-config.md`](https://docs.clawd.bot/skills-config)
- macOS app onboarding: [`docs/onboarding.md`](/onboarding)
- Config reference: [`docs/configuration.md`](/configuration)
- Providers: [`docs/whatsapp.md`](/whatsapp), [`docs/telegram.md`](/telegram), [`docs/discord.md`](/discord), [`docs/signal.md`](/signal), [`docs/imessage.md`](/imessage)
- Skills: [`docs/skills.md`](/skills), [`docs/skills-config.md`](/skills-config)