docs: overhaul docs IA and multilingual navigation

2026-02-18 16:53:26 +08:00 · 2026-02-18 16:53:26 +08:00 · 93e5383cb2
commit 93e5383cb2
parent 5e800c38f1
40 changed files with 2495 additions and 198 deletions
--- a/docs/channels-reference.md
+++ b/docs/channels-reference.md
@ -0,0 +1,105 @@
+# 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>
+```
+
+## 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)