openclaw directory CLI reference: self, peers, groups lookups
This page covers the openclaw directory command for looking up contacts, peers, groups, or the self entry. It is intended for users who need to retrieve directory data for use in other commands like message sending.
Read this when
- You want to look up contacts/groups/self ids for a channel
- You are developing a channel directory adapter
openclaw directory
For channels that offer directory functionality, lookups can target contacts, peers, groups, or the "me" (self) entry.
The output is designed for insertion into other commands, most notably openclaw message send --target ....
Common flags
--channel <name>: alias or ID of the channel (mandatory when multiple channels exist; chosen automatically if only one is configured)--account <id>: account identifier (defaults to the channel's default account)--json: output in JSON format
The standard (non-JSON) output uses id (and occasionally name) separated by a tab character.
Notes
- On many channels, results come from configuration (allowlists or predefined groups) rather than a live directory from the provider.
- WhatsApp group listings are fetched live. Gateway lookups reuse the connection the gateway already owns; a standalone command opens the linked session only when no other process holds that account, otherwise it reports that live groups are unavailable.
- A channel plugin that is already installed may not support directory operations. In that situation, the command indicates the operation is unsupported; it does not attempt to reinstall or upgrade the plugin to enable the feature.
Using results with message send
openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
ID formats by channel
| Channel | Target id format |
|---|---|
+15551234567 (DM), 1234567890-1234567890@g.us (group), 120363123456789@newsletter (Channel/Newsletter, outbound only) | |
| Signal | Configured aliases resolve to E.164/UUID DM targets or group:<id> group targets |
| Telegram | @username or a numeric chat ID; groups use numeric IDs |
| Slack | user:U… and channel:C… |
| Discord | user:<id> and channel:<id> |
| Matrix (plugin) | user:@user:server, room:!roomId:server, or #alias:server |
| Microsoft Teams (plugin) | user:<id> and conversation:<id> |
| Zalo (plugin) | User ID (Bot API) |
Zalo Personal / zalouser (plugin) | Thread ID (DM/group), obtained from zca (me, friend list, group list) |
Self ("me")
openclaw directory self --channel zalouser
Peers (contacts/users)
openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50
Groups
openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>