From 6bad75827a205462bf863cbb33062c11d124d728 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Fri, 2 Jan 2026 11:41:08 +0000 Subject: [PATCH] docs: clarify Signal setup and env-token gating --- CHANGELOG.md | 2 ++ docs/configuration.md | 4 ++-- docs/discord.md | 3 ++- docs/signal.md | 18 ++++++++++++++++++ docs/telegram.md | 3 ++- 5 files changed, 26 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 952eea68d..067ff1fb6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ - new optional bundled allowlist: `skills.allowBundled` (only affects bundled skills) - Sessions: group keys now use `surface:group:` / `surface:channel:`; legacy `group:*` keys migrate on next message; `groupdm` keys are no longer recognized. - Discord: remove legacy `discord.allowFrom`, `discord.guildAllowFrom`, and `discord.requireMention`; use `discord.dm` + `discord.guilds`. +- Providers: Discord/Telegram no longer auto-start from env tokens alone; add `discord: { enabled: true }` / `telegram: { enabled: true }` to your config when using `DISCORD_BOT_TOKEN` / `TELEGRAM_BOT_TOKEN`. ### Features - Talk mode: continuous speech conversations (macOS/iOS/Android) with ElevenLabs TTS, reply directives, and optional interrupt-on-speech. @@ -48,6 +49,7 @@ - Gateway CLI: read `CLAWDIS_GATEWAY_PASSWORD` from environment in `callGateway()` — allows `doctor`/`health` commands to auth without explicit `--password` flag. - Auto-reply: strip stray leading/trailing `HEARTBEAT_OK` from normal replies; drop short (≤ 30 chars) heartbeat acks. - Logging: trim provider prefix duplication in Discord/Signal/Telegram runtime log lines. +- Logging/Signal: treat signal-cli "Failed …" lines as errors in gateway logs. - Discord: include recent guild context when replying to mentions and add `discord.historyLimit` to tune how many messages are captured. - Discord: include author tag + id in group context `[from:]` lines for ping-ready replies (thanks @thewilloftheshadow). - Gateway: fix TypeScript build by aligning hook mapping `channel` types and removing a dead Group DM branch in Discord monitor. diff --git a/docs/configuration.md b/docs/configuration.md index 8564e98ce..0128706b4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -145,7 +145,7 @@ Set `web.enabled: false` to keep it off by default. ### `telegram` (bot transport) -Clawdis reads `TELEGRAM_BOT_TOKEN` or `telegram.botToken` to start the provider. +Clawdis starts Telegram only when a `telegram` config section exists. The bot token is resolved from `TELEGRAM_BOT_TOKEN` or `telegram.botToken`. Set `telegram.enabled: false` to disable automatic startup. ```json5 @@ -197,7 +197,7 @@ Configure the Discord bot by setting the bot token and optional gating: } ``` -Clawdis reads `DISCORD_BOT_TOKEN` or `discord.token` to start the provider (unless `discord.enabled` is `false`). Use `user:` (DM) or `channel:` (guild channel) when specifying delivery targets for cron/CLI commands. +Clawdis starts Discord only when a `discord` config section exists. The token is resolved from `DISCORD_BOT_TOKEN` or `discord.token` (unless `discord.enabled` is `false`). Use `user:` (DM) or `channel:` (guild channel) when specifying delivery targets for cron/CLI commands. Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged channel name (no leading `#`). Prefer guild ids as keys to avoid rename ambiguity. ### `imessage` (imsg CLI) diff --git a/docs/discord.md b/docs/discord.md index 449a479ce..f482588e3 100644 --- a/docs/discord.md +++ b/docs/discord.md @@ -19,7 +19,8 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa 1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token. 2. Invite the bot to your server with the permissions required to read/send messages where you want to use it. 3. Configure Clawdis with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdis/clawdis.json`). -4. Run the gateway; it auto-starts the Discord provider when the token is set (unless `discord.enabled = false`). +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 `~/.clawdis/clawdis.json` and set `DISCORD_BOT_TOKEN`. 5. Direct chats: use `user:` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session. 6. Guild channels: use `channel:` for delivery. Mentions are required by default and can be set per guild or per channel. 7. Optional DM control: set `discord.dm.enabled = false` to ignore all DMs, or `discord.dm.allowFrom` to allow specific users (ids or names). Use `discord.dm.groupEnabled` + `discord.dm.groupChannels` to allow group DMs. diff --git a/docs/signal.md b/docs/signal.md index b386f9d6b..9c389bf99 100644 --- a/docs/signal.md +++ b/docs/signal.md @@ -30,6 +30,11 @@ You can still run Clawdis on your own Signal account if your goal is “respond ## Quickstart (bot number) 1) Install `signal-cli` (keep Java installed). + - If you use the CLI wizard, it can auto-install to `~/.clawdis/tools/signal-cli/...`. + - If you want a pinned version (example: `v0.13.22`), install manually: + - Download the release asset for your platform from GitHub (tag `v0.13.22`). + - Extract it somewhere stable (example: `~/.clawdis/tools/signal-cli/0.13.22/`). + - Set `signal.cliPath` to the extracted `signal-cli` binary path. 2) Link the bot account as a device: - Run: `signal-cli link -n "Clawdis"` - Scan QR in Signal: Settings → Linked Devices → Link New Device @@ -55,6 +60,15 @@ You can still run Clawdis on your own Signal account if your goal is “respond - Expect `signal.probe.ok=true` and `signal.probe.version`. 5) DM the bot number from your phone; Clawdis replies. +## “Do I need a separate number?” +- If you want “I text her and she texts me back”, yes: **use a separate Signal account/number for the bot**. +- Your personal account can run `signal-cli`, but you can’t self-chat (Signal loop protection; Clawdis ignores sender==account). + +If you have a second phone: +- Create/activate the bot number on that phone. +- Run `signal-cli link -n "Clawdis"` on your Mac, scan the QR on the bot phone. +- Put your personal number in `signal.allowFrom`, then DM the bot number from your personal phone. + ## Endpoints (daemon --http) - `POST /api/v1/rpc` JSON-RPC request (single or batch). - `GET /api/v1/events` SSE stream of `receive` notifications. @@ -65,6 +79,10 @@ You can still run Clawdis on your own Signal account if your goal is “respond - Include `params.account` (E164) on JSON-RPC calls. - SSE `?account=+E164` filters events; no param = all accounts. +## Troubleshooting +- Gateway log coloring: `signal-cli: ...` lines are classified by severity; red means “treat this as an error”. +- `Failed to initialize HTTP Server` typically means the daemon can’t bind the HTTP port (already in use). Stop the other daemon or change `signal.httpPort`. + ## Minimal RPC surface - `send` (recipient/groupId/username, message, attachments). - `listGroups` (map group IDs). diff --git a/docs/telegram.md b/docs/telegram.md index 06f298083..02f63d5b0 100644 --- a/docs/telegram.md +++ b/docs/telegram.md @@ -17,7 +17,8 @@ Status: ready for bot-mode use with grammY (long-polling by default; webhook sup ## How it will work (Bot API) 1) Create a bot with @BotFather and grab the token. 2) Configure Clawdis with `TELEGRAM_BOT_TOKEN` (or `telegram.botToken` in `~/.clawdis/clawdis.json`). -3) Run the gateway; it auto-starts Telegram when the bot token is set (unless `telegram.enabled = false`). +3) Run the gateway; it auto-starts Telegram only when a `telegram` config section exists **and** a bot token is set (unless `telegram.enabled = false`). + - If you prefer env vars, still add `telegram: { enabled: true }` to `~/.clawdis/clawdis.json` and set `TELEGRAM_BOT_TOKEN`. - **Long-polling** is the default. - **Webhook mode** is enabled by setting `telegram.webhookUrl` (optionally `telegram.webhookSecret` / `telegram.webhookPath`). - The webhook listener currently binds to `0.0.0.0:8787` and serves `POST /telegram-webhook` by default.