120 lines
4.1 KiB
Markdown
120 lines
4.1 KiB
Markdown
# ZeroClaw Channels Reference
|
|
|
|
This reference maps channel capabilities, config blocks, allowlist behavior, and setup paths.
|
|
|
|
Last verified: **February 18, 2026**.
|
|
|
|
## Quick Commands
|
|
|
|
```bash
|
|
zeroclaw channel list
|
|
zeroclaw channel start
|
|
zeroclaw channel doctor
|
|
zeroclaw channel bind-telegram <IDENTITY>
|
|
```
|
|
|
|
## In-Chat Runtime Model Switching (Telegram / Discord)
|
|
|
|
When running `zeroclaw channel start` (or daemon mode), Telegram and Discord now support sender-scoped runtime switching:
|
|
|
|
- `/models` — show available providers and current selection
|
|
- `/models <provider>` — switch provider for the current sender session
|
|
- `/model` — show current model and cached model IDs (if available)
|
|
- `/model <model-id>` — switch model for the current sender session
|
|
|
|
Notes:
|
|
|
|
- Switching clears only that sender's in-memory conversation history to avoid cross-model context contamination.
|
|
- Model cache previews come from `zeroclaw models refresh --provider <ID>`.
|
|
- These are runtime chat commands, not CLI subcommands.
|
|
|
|
## Channel Matrix
|
|
|
|
| Channel | Config section | Access control field | Setup path |
|
|
|---|---|---|---|
|
|
| `CLI` | n/a (always enabled) | n/a | Built-in |
|
|
| `Telegram` | `[channels_config.telegram]` | `allowed_users` | `zeroclaw onboard` |
|
|
| `Discord` | `[channels_config.discord]` | `allowed_users` | `zeroclaw onboard` |
|
|
| `Slack` | `[channels_config.slack]` | `allowed_users` | `zeroclaw onboard` |
|
|
| `Mattermost` | `[channels_config.mattermost]` | `allowed_users` | Manual config |
|
|
| `Webhook` | `[channels_config.webhook]` | n/a (`secret` optional) | `zeroclaw onboard` or manual |
|
|
| `iMessage` | `[channels_config.imessage]` | `allowed_contacts` | `zeroclaw onboard` (macOS) |
|
|
| `Matrix` | `[channels_config.matrix]` | `allowed_users` | `zeroclaw onboard` |
|
|
| `Signal` | `[channels_config.signal]` | `allowed_from` | Manual config |
|
|
| `WhatsApp` | `[channels_config.whatsapp]` | `allowed_numbers` | `zeroclaw onboard` |
|
|
| `Email` | `[channels_config.email]` | `allowed_senders` | Manual config |
|
|
| `IRC` | `[channels_config.irc]` | `allowed_users` | `zeroclaw onboard` |
|
|
| `Lark` | `[channels_config.lark]` | `allowed_users` | Manual config |
|
|
| `DingTalk` | `[channels_config.dingtalk]` | `allowed_users` | `zeroclaw onboard` |
|
|
| `QQ` | `[channels_config.qq]` | `allowed_users` | `zeroclaw onboard` |
|
|
|
|
## Deny-by-Default Rules
|
|
|
|
For channel allowlists, the runtime behavior is intentionally strict:
|
|
|
|
- Empty allowlist (`[]`) means **deny all**.
|
|
- Wildcard (`["*"]`) means **allow all**.
|
|
- Explicit IDs are exact matches unless channel-specific docs state otherwise.
|
|
|
|
### Telegram pairing bootstrap
|
|
|
|
Telegram has a secure bootstrap flow:
|
|
|
|
- Keep `allowed_users = []` to start in pairing mode.
|
|
- Run `zeroclaw channel bind-telegram <IDENTITY>` to add one identity safely.
|
|
- After binding, restart long-running channel processes if needed (`daemon` / `channel start`).
|
|
|
|
## Minimal Config Examples
|
|
|
|
### Telegram
|
|
|
|
```toml
|
|
[channels_config.telegram]
|
|
bot_token = "123456:ABCDEF"
|
|
allowed_users = []
|
|
```
|
|
|
|
### WhatsApp
|
|
|
|
```toml
|
|
[channels_config.whatsapp]
|
|
access_token = "EAABx..."
|
|
phone_number_id = "123456789012345"
|
|
verify_token = "your-verify-token"
|
|
allowed_numbers = ["+1234567890"]
|
|
```
|
|
|
|
### Signal
|
|
|
|
```toml
|
|
[channels_config.signal]
|
|
http_url = "http://127.0.0.1:8686"
|
|
account = "+1234567890"
|
|
allowed_from = ["+1987654321"]
|
|
ignore_attachments = true
|
|
ignore_stories = true
|
|
```
|
|
|
|
### Lark
|
|
|
|
```toml
|
|
[channels_config.lark]
|
|
app_id = "cli_xxx"
|
|
app_secret = "xxx"
|
|
allowed_users = ["ou_abc"]
|
|
receive_mode = "websocket" # or "webhook"
|
|
# port = 3100 # required only when receive_mode = "webhook"
|
|
```
|
|
|
|
## Operational Notes
|
|
|
|
- `zeroclaw channel add/remove` is intentionally not a full config mutator yet; use `zeroclaw onboard` or edit `~/.zeroclaw/config.toml`.
|
|
- `zeroclaw channel doctor` validates configured channel health and prints timeout/unhealthy status.
|
|
- If `webhook` is configured, doctor guidance points to gateway health check (`GET /health`).
|
|
|
|
## Related Docs
|
|
|
|
- [README.md (Channel allowlists)](../README.md#channel-allowlists-deny-by-default)
|
|
- [network-deployment.md](network-deployment.md)
|
|
- [mattermost-setup.md](mattermost-setup.md)
|
|
- [commands-reference.md](commands-reference.md)
|