Complete reference for openclaw directory, looking up yourself, listing contacts and groups, resolving per-channel ID formats, and chaining lookups into message sends.
What does Openclaw Directory do?
It’s the ID resolution layer for OpenClaw’s connected channels. When you need to send a message, create a routing binding, or target a specific user or group, you need that channel’s internal ID, not just a display name.
The directory command queries your active channels to return these IDs. Because these results are often pulled from your existing setup, you should first ensure your accounts are properly linked using the Openclaw Configure Commands and Uses guide to verify that your channel credentials and allowlists are active.
Finding the Right Subcommand
There are three lookup targets: self (your own bot or user ID), peers (individual contacts), and groups (group chats and their membership). All three require a –channel flag if you have more than one channel configured.
The most common workflow is: query peers or groups to find an ID, then use that ID with openclaw message send –target. See Integration for that complete two-step pattern. Check ID Formats before constructing a target string manually, each channel has a different format and getting it wrong results in a silent routing failure.
Common Flags
These flags can be appended to most openclaw directory commands.
| Flag | Description |
|---|---|
--channel <name> | Specifies the channel alias (e.g. slack, discord, zalouser). Required if you have multiple channels configured; automatically resolved if you only have one. |
--account <id> | Targets a specific account ID for multi-account setups. Defaults to the channel’s default account when omitted. |
| –json | Outputs results as machine-readable JSON instead of the default tab-separated id \t name text. Recommended for scripting. |
Subcommands
Three lookup targets, each with their own sub-actions and filter flags.
openclaw directory self
Retrieves the internal ID of the current bot or authenticated user for the specified channel. Useful for confirming your own ID before constructing routing rules or testing message delivery.
openclaw directory self --channel zalouser
openclaw directory peers
list
Lists available peers (individual contacts) for the specified channel. Supports filtering and result limits.
–query “<text>”–limit <n>
peers list examples
# List all peers openclaw directory peers list --channel zalouser # Filter by name or ID openclaw directory peers list --channel zalouser --query "name" # Limit to 50 results openclaw directory peers list --channel zalouser --limit 50
openclaw directory groups
list
Lists available group chats for the specified channel. Supports name filtering.
–query “<text>”
openclaw directory groups list --channel zalouser --query "work"
members
Lists the members of a specific group. Requires the –group-id flag with the group’s internal ID (from groups list).
–group-id <id>
openclaw directory groups members --channel zalouser --group-id <id>
Default Output Format
Without –json, directory outputs tab-separated rows. With –json, structured objects are returned. Choose based on whether you’re reading results interactively or piping them into a script.
Default output is id \t name (tab-separated). Pass –json for structured output when scripting. The JSON format includes additional metadata fields that aren’t present in the default text output.
Integration Use Case
The most common use case: query directory to find an ID, then use that ID with message send. A two-step pattern that eliminates hardcoded IDs from scripts.
1 Find the user ID → 2 Send the message
# Step 1: Query Slack peers, filter by "U0" prefix to find the user ID openclaw directory peers list --channel slack --query "U0" # Step 2: Use the resolved ID with message send openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
Pass –json to the directory query and pipe it through jq to extract the ID programmatically in CI scripts, rather than parsing the default tab-separated output.
Channel ID Formats
When returning IDs, OpenClaw formats them according to each channel’s requirements. Use these exact formats when constructing –target values for message send or routing rules, wrong formats result in silent delivery failures.
| Channel | DM / User ID format | Group / Channel ID format |
|---|---|---|
| +15551234567 | 1234567890-1234567890@gus | |
| Telegram | @username or numeric chat ID | numeric ID |
| Slack | user:U… | channel:C… |
| Discord | user:<id> | channel:<id> (raw numeric = channel) |
| Matrix (plugin) | user:@user:server | room:!roomId:server or #alias:server |
| Microsoft Teams (plugin) | user:<id> | conversation:<id> |
| Zalo / Zalo Personal | Internal Bot API user ID | zca thread ID (personal accounts) |
For many channels, directory results are config-backed, they return targets derived from your configured allowlists or manually defined groups, not by polling a live provider directory. This means results are scoped to what you’ve explicitly configured, and a contact that exists on the platform but isn’t in your allowlist won’t appear in the output.
