openclaw directory CLI Reference

`openclaw directory`

For channels that offer directory support, this command looks up contacts, peers, groups, and your own identity ("me").

The output is designed for reuse in other commands, particularly openclaw message send --target ....

Common flags

--channel <name>: channel id or alias, required when several channels are set up, otherwise picked automatically if only one exists
--account <id>: account id, falling back to the channel default
--json: produce output as JSON

By default, IDs and names appear in a table. When the result list is empty, the channel and account queried are named; in JSON mode, an empty array is returned ([]). Any failure results in a nonzero exit and follows the standard { "ok": false, "error": { "type": "cli_error", "message": "..." } } envelope when JSON is selected.

Notes

On many channels, results come from configuration, such as allowlists or defined groups, rather than a live provider directory.
Before performing a live lookup, OpenClaw resolves SecretRefs only for the chosen channel and account. These resolved credentials exist solely at runtime; plugin installation and auto-enable operations keep the authored references intact without storing runtime defaults.
WhatsApp group listings are fetched live. Gateway lookups use the connection it already owns; a standalone command opens the linked session only when no other process holds that account, otherwise it reports that live groups cannot be accessed.
A channel plugin that is already installed may not support directory operations. In such a case, the command flags the unsupported operation and does not attempt a reinstall or upgrade to gain that capability.

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
WhatsApp	`+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 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), from `zca` (`me`, `friend list`, `group list`)

Self ("me")

openclaw directory self --channel zalouser

A channel may legitimately return no self identity. That counts as a successful empty result, with exit code 0, not a lookup failure. Channels lacking a self resolver state that no self identity is exposed, without pointing to account troubleshooting:

{
  "status": "unavailable",
  "channel": "telegram",
  "accountId": "default",
  "reason": "self-identity-unsupported"
}

When a channel does implement self lookup but yields no identity, the text output identifies the channel and account and recommends reviewing its configuration and authentication. JSON callers can tell this case apart by its reason:

{
  "status": "unavailable",
  "channel": "msteams",
  "accountId": "default",
  "reason": "plugin-returned-no-self-identity"
}

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>

CLI reference