## Summary The channels section of the settings dialog drew a hashed letter tile for every entrance. It now draws each app's own icon, in the list row and in the picked channel's header, and every entrance is named in both of the web UI's locales. **Icons.** `ui-web/src/assets/channels/` holds eleven files: - Nine are the icons the vendors publish on their App Store listings (China storefront for Feishu, DingTalk, WeCom, WeChat and QQ; US for Slack, Telegram, Discord and WhatsApp), resampled from the 512px artwork to 96x96 PNG. For the five Chinese apps the listing is where a colour icon was found: the permissively licensed icon sets checked (lobe-icons, `@cherrystudio/ui`, SVG Logos, Simple Icons and the brand sets on Iconify) carry them only as single-colour glyphs. - `matrix.svg` and `mochat.svg` are the files matrix.org and MoChat serve as their own marks, copied byte for byte. - Mail is a protocol rather than a brand, so it gets a neutral envelope drawn in the component. `scripts/refresh_channel_marks.py` names the listing or URL behind every file and regenerates the directory; `LICENSES/README.md` records the basis for showing them (the vendors' marks, identifying the row they sit on, as with AMD's). `ChannelMark` is keyed by channel id, never by the row's name, and falls back to the letter tile for an id with no mark and for a file that fails to load. The asset digest helper moves out of `ProviderMark.tsx` into `lib/assetStamp.ts` so both marks share it and a refreshed icon is not served from cache. **Names.** Six brands bypassed the message catalogue with one verbatim spelling, and `gui.chan.mochat` held the Chinese name in its English slot. Every entrance now has a `gui.chan.<id>` entry in both locales (Slack, QQ, Telegram, Discord, WhatsApp and Matrix keep their Latin names in Chinese, as their own Chinese builds do), the verbatim path is gone (`ConnChannel.key` is required), and the English name is MoChat. The adapter's `display_name`, which the CLI prints, and the two channels docs pages also say MoChat. The TUI's generated catalogue is regenerated. **Guards.** `tests/test_ui_channel_marks.py` holds the mark table equal to the adapters, the shipped files and the refresh script, and the PNGs to 96x96. `catalogue.test.ts` holds every entrance to both locales and to English in the English slot. `tests/test_channels_display_names.py` holds the CLI and the web UI to one English name per channel. `scripts/gates/channel-mark-css.test.mjs` reads the expected box off `.pmtile`'s own rule, since the mark stands in for that per-container-sized tile. **Also in this PR.** `.pre-commit-config.yaml` adds `channels/` to the end-of-file fixer's exclude beside `providers/` and `agents/`: matrix.org writes `matrix.svg` without a trailing newline, and appending one would end the byte-for-byte copy. **Existing tests whose meaning changed.** `test_channels_mochat.py` now expects the MoChat display name; `source.test.ts` now expects every row, a brand included, to be named through the message catalogue; the `ConnectionsPage` fixtures move from `name:` to `key:` (the stand-in translator hands a key back as its text, so no query changed); the DOM snapshot shows the mark in place of `.pmtile`. **Deliberately unchanged.** Adapter docstrings, log lines and class names keep "Mochat" (identifiers and developer text, not a name a reader is shown). The TUI draws no channel list, so it gets no icons. The refresh script needs the network and is run by hand; neither CI nor the build runs it. **Weight.** Eleven files, about 66 KB, copied into `dist/assets` and the wheel. Nine commits: the feature, then one per finding of the pre-submit sweep. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Suites ran before the last commit, which changes only `.pre-commit-config.yaml` and was checked with pre-commit. - `npx vitest run --no-file-parallelism` in `ui-web/` (with `NODE_OPTIONS=--localstorage-file=<file>`, needed under node 26): 202 files, 2790 tests, 2788 passed, 2 failed. The two are the "when storage refuses" cases in `src/features/desk/palette.test.ts` and `store.test.ts`, which fail at every revision under this machine's node 26 and pass under CI's node 22; this branch touches neither. - `npm run gen:check`, `npm run lint` (0 errors, the 4 existing warnings), `npm run type-check` in `ui-web/`: pass. `npm run type-check` and `node scripts/gen-i18n.mjs --check` in `ui-tui/`: pass. - `npm run build`, `python3 ui-web/build.py`, `check-page.mjs`, `check-css.mjs`, `check-class-namespace.mjs`: all OK. - `uv run pytest -q` with all extras: 25778 passed, 114 skipped, 1 failed: `tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`, which fails the same way on a checkout without this branch (this machine has npm on four PATH entries, which defeats its no-npm case). - `ruff check` and `ruff format --check` over the Makefile's lint targets: clean. `lint-imports`: 10 kept, 0 broken. `ty check` on the changed modules: clean. - `uv run --isolated --frozen --group docs mkdocs build -f docs-site/mkdocs.yml --strict`: exit 0; both channels pages render MoChat. - `pre-commit run --from-ref origin/main --to-ref HEAD`: every hook passes except prettier (ui-tui), which flags only `src/__tests__/instanceModeCommand.test.ts`, unchanged here (last touched by #669); CI's pre-commit job skips that hook, having no `node_modules`. - `scripts/check_commit_messages.py origin/main..HEAD` and commitlint: pass. - Red first and mutants: every new case failed before its implementation. Mutants, each reverted with the tree clean after: no `onError` fallback, a failure kept as a boolean, marks keyed by name, the asset digest dropped, `qq` dropped from the table, the English name set back to "Mochat", `.channel-mark` resized, and a slot-specific `.pmtile` box. Each turned the tests written for it red: 1, 1, 3, 1, 3 Python guards, the display-name guard, and the CSS gate twice. - Browser, headless Chrome over the built page with `?stub=1`: all twelve rows draw a 38x38 mark with its file loaded and the digest in its URL, and no letter tile is left. The letter tile measures the same 38x38 with an 11px radius in both slots. English reads Feishu, Email, WeChat, WhatsApp, Telegram, Discord, MoChat, WeCom, Slack, DingTalk, QQ, Matrix. After Settings > General > Chinese, MoChat shows its Chinese name and the six brands keep their Latin names. Matrix's mark follows the theme switch on a light OS. - `raven channels list` from this tree: `mochat | MoChat`. - `scripts/refresh_channel_marks.py` run twice: the second run reproduced every PNG byte for byte, and the two SVGs are `cmp`-identical to a separate fetch. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk User-visible: the channels section shows app icons where it showed letter tiles, and MoChat's English name changes from its Chinese name (web UI) and from "Mochat" (CLI). The other eleven names read as before. No config, RPC or stored data changes; `ConnChannel.name` was internal to `ui-web`. Rollback is reverting the squash commit. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5-5[1m]) <noreply@anthropic.com>
8.5 KiB
Channels and Messaging
Channels let people reach Raven through a messaging platform. Agent integrations let Raven delegate to another agent. These are separate directions: configuring an OpenClaw agent does not configure Raven's WhatsApp channel, and enabling Telegram does not create another agent.
Message path
Platform message
-> channel adapter: sender/group checks and media handling
-> Intake: TurnRequest
-> Gateway / Spine: conversation scheduling
-> Agent Loop: tools, memory, delegation
-> DeliveryHub / ChannelOutletAdapter
-> originating channel and chat
A resident gateway owns channel connections. A one-shot raven agent -m
invocation is not a persistent messaging bot. Use Self-Hosting
for service deployment, or Launch WebUI for the background host.
Available adapters
The table reflects shipped ChannelSpec declarations, not a live test of your
account. “Files out” means the adapter advertises attachment delivery; it says
nothing by itself about every inbound media format or platform size limit.
| Config name | Platform / connection | Main setup | Files out |
|---|---|---|---|
telegram |
Telegram bot | Bot token | Yes |
discord |
Discord Gateway / REST | Bot token and platform bot permissions | Yes |
slack |
Slack Socket Mode / Web API | Bot token and app token | Yes |
whatsapp |
WhatsApp via Node bridge | Interactive QR linking; bridge configuration | No |
weixin |
Personal WeChat via iLink | Interactive QR linking | Yes |
wecom |
WeCom AI bot WebSocket | Bot id and secret | No |
feishu |
Feishu/Lark long connection | App id and app secret | Yes |
dingtalk |
DingTalk | Client id and client secret | Yes |
matrix |
Matrix sync | Homeserver, user id, access token | Yes |
qq |
QQ bot | App id and secret | No |
email |
IMAP / SMTP | Receiving and sending account settings | No |
mochat |
MoChat | Service configuration and claw token | No |
Use the installed version's commands to inspect fields without guessing:
raven channels list
raven channels show telegram
raven channels show slack
raven channels status
For a source installation, optional channel SDKs are installed with
uv sync --extra channels. QR-backed WhatsApp also needs its Node bridge;
dependency readiness does not replace platform authentication.
Set up a first channel
- Create the bot/app or account on the platform and grant only the scopes it needs. Obtain the correct sender id for your allowlist.
- Use onboarding/WebUI configuration or merge a channel section into the existing Raven config. Preserve provider settings and other channels.
- Check
raven channels get <name>; secrets are redacted by default. - Start or restart the resident gateway and inspect channel status and logs.
- Send one plain-text message from an allowed sender. Verify the reply and then test any needed group or attachment behaviour.
Example config fragment for a private Telegram bot:
{
"channels": {
"telegram": {
"enabled": true,
"token": "REPLACE_WITH_BOT_TOKEN",
"allowFrom": ["123456789"],
"workspace": "/absolute/path/to/bot-work",
"groupPolicy": "mention"
}
}
}
Replace the token, sender id, and directory before enabling. Never commit a real token. Prefer the setup UI or a protected local config over a command containing secrets in shell history.
With credentials already configured, CLI changes can be made explicitly:
raven channels enable telegram --allow-from 123456789 --group-policy mention
raven channels get telegram
raven gateway
The last command starts a foreground host; if a host already runs, restart that
host rather than launching a competing one. CLI configuration writes print a
restart reminder. channels enable <name> without fields may show field help
rather than enable anything, and “enabled” is an intent flag, not a health check.
Sender and group policy
allowFrom chooses who may invoke the host. It is separate from tool
permissions, group mention rules, and platform OAuth scopes.
- Specific ids allow only matching senders; use strings for identifiers.
["*"]allows everyone who can reach the channel. The schema defaults to this broad value, so set an explicit list for a private deployment.[]denies everyone; gateway startup refuses an enabled channel with an empty allowlist. Disable the channel instead of using an empty active config.- CLI enable asks before an implicit wildcard on a terminal, and refuses it unattended unless the wildcard is explicitly supplied.
Identity matching is platform-specific. Telegram accepts its adapter's id/username forms; other platforms may use account ids, open ids, or JIDs. Do not substitute a display name or a room id for a sender id.
Group rules are not uniform: Telegram, Discord, and Feishu expose
groupPolicy; Slack adds group/DM settings; Matrix also supports group
allowlisting. Inspect channels show <name>. A mention does not override a
sender refusal, and authorizing one person in a group does not make every
participant authorized.
Sessions and working directories
The normal conversation address derives from the channel and chat id. An adapter may provide a more specific key: Slack can scope a group conversation to its thread. Do not assume every sender gets a private memory/session when they share a room or thread.
channels.<name>.workspace chooses the channel's user working directory.
When unset, the channel default is under ~/.raven/tmp/<channel> (adjusted for
the instance home). It must not point into protected Agent home state such as
memory, skills, or transcripts. This directory is not an OS sandbox and does
not itself restrict what an external agent can reach.
Use dedicated directories and narrow sender policies where people should not share files. Review Permissions and Security before giving a public or team channel an agent that can edit files or run commands.
Media and delivery limits
Inbound downloads, transcription, and outbound attachments are separate capabilities. Some adapters use the shared transcription helper and its configured provider; WeCom can consume platform-supplied voice transcription. Receiving audio does not guarantee transcription credentials are configured.
The current channel outlet sends final replies rather than edit-in-place token streams. Browser/TUI streaming and DAG visualizations are not reproduced as a full messaging-platform UI.
If an outlet cannot attach files, it sends a “Files ready” notice naming the files and asks the user to open the same session in Raven UI or TUI. That notice is not a download link, and a successful model answer is not proof of successful file upload. Platform permissions, formats, size limits, and transient transport errors still apply to file-capable adapters.
QR login and lifecycle
Only adapters declaring interactive login use channels login. Today that is
WhatsApp and personal WeChat:
raven channels login whatsapp
raven channels login weixin
These commands pair real accounts and must run in an interactive terminal.
Token-based channels use channels set or the configuration UI instead.
WeCom is enterprise WeChat and does not use the personal weixin QR flow.
raven channels disable <name> preserves stored credentials; restart the host
to apply the CLI change. Disabling is not credential revocation. Revoke leaked
credentials at the platform and replace the local values as well.
Troubleshooting
| Symptom | First check |
|---|---|
| Enabled but not running | Optional SDK, required credentials, gateway logs |
| Direct messages work, groups do not | Bot platform permissions, mention/group policy, sender id |
| Incoming text produces no turn | Allowlist and Intake/gateway wiring |
| Turn finishes but no reply arrives | Outbound credentials/scopes, destination chat, transport error |
| Audio produces no usable text | Adapter media support and transcription configuration |
| “Files ready” but no attachment | Outbound file capability; open the session in Raven UI/TUI |
| QR command fails without a prompt | Interactive terminal, supported adapter, bridge/account state |
| Config edit appears ignored | Restart the actual resident host; inspect its config/home selection |
Use raven gateway status, raven channels status, and raven doctor.
Do not post raw tokens, QR login data, or private message payloads with logs.
Developers adding an adapter should read
Protocol and Backend Integration.