Setup & Installation
Or with the ClawHub CLI, for registry-managed skill folders outside a full OpenClaw workspace:
Version History
- Added comprehensive SKILL.md with usage instructions, API reference, CLI commands, features, and security details. - Clarified installation steps, quick start for end users and developers, and provided integration examples. - Documented file format for identity map and explained auto-registration and canonical ID mapping features. - Described security measures, including path traversal protection and thread-safe file operations. - Included links for GitHub repository, issues, and ClawHub listing.
What This Skill Does
Maps Telegram, WhatsApp, Discord, and web channel identities to a single canonical user ID per person. Without it, the same user messaging from different channels appears as separate users, fragmenting memory, access control, and per-user state. Provides both a Python API and a CLI for skill developers and end users.
Zero external dependencies and built-in thread-safe file locking mean it works anywhere Python runs without additional setup or service dependencies.
When to use it
- Unifying a user's Telegram and WhatsApp messages in a shared memory store
- Running access control checks that hold across multiple chat platforms
- Preventing duplicate user profiles when a bot operates on Discord and Telegram simultaneously
- Resolving channel-specific IDs before writing to per-user data files
- Registering workspace owner identity automatically from USER.md on first run
Example Workflow
Here's how your AI assistant might use this skill in practice.
User asks: resolve my Telegram ID to a canonical user ID
- 1Read OPENCLAW_CHANNEL and OPENCLAW_USER_ID from the session environment
- 2Call resolve_canonical_id(channel, user_id) from the identity module
- 3Look up the channel entry in identity-map.json
- 4Return the stored canonical ID, or fall back to 'stranger:{channel}:{user_id}' if no mapping exists
Canonical user ID string such as 'alice', used for all subsequent user-scoped file paths and access control checks