What This File Controls
IDENTITY.md is the agent’s public-facing metadata card. While SOUL.md defines how the agent thinks, IDENTITY.md controls how the agent presents itself to the outside world — its display name, role description, visual identifier, platform binding, and operational context.
In single-agent deployments, IDENTITY.md may feel redundant. Its true importance emerges in multi-agent environments: when several agents share a Slack workspace or a Feishu group chat, IDENTITY.md is how the OpenClaw runtime routes incoming messages to the correct agent. The idPlatform and idContext fields act as routing selectors — if two agents share the same platform and context, messages are routed ambiguously and you get routing chaos.
IDENTITY.md is parsed immediately after SOUL.md in the boot sequence. The idName field often mirrors the SOUL.md name field, but they serve different audiences: name is how the agent thinks of itself; idName is how it appears in platform UIs. For hybrid deployments spanning multiple platforms, you can create platform-specific identity overrides using a directory structure pattern.
Why it matters: In group chats or multi-agent setups, this is how messages get routed to the right agent.
Field-by-Field Breakdown
5 fields that shape your agent
idNameRequiredThe public-facing name shown to other agents and users.
idRoleRequiredA one-line description of this agent's function.
idEmojiOptionalVisual identifier used in multi-agent chat interfaces.
idPlatformRequiredThe primary platform where this agent operates.
idContextOptionalAdditional context about the agent's operating environment.
Real-World Examples
## idName
Finley — Tax & Compliance Assistant
## idRole
Financial research and HMRC compliance assistant for Whitfield & Associates
## idEmoji
📊
## idPlatform
Slack
## idContext
Operates in #tax-queries and #client-research channels. Responds to @finley mentions and direct messages from all partners and associates.Common Mistakes
Making idName identical to SOUL name
They serve different audiences. The SOUL name is how the agent thinks of itself internally; idName is the public display name shown in platform UIs. The idName often needs additional context (e.g., ‘Finley — Tax Assistant’) that would clutter the internal self-reference.
Setting idPlatform incorrectly during staging
Agents tested on Slack with idPlatform set to ‘Slack’ are then deployed to Microsoft Teams without updating the field. The routing metadata is stale, causing silent message delivery failures or misrouted conversations.
Using confusable emojis in multi-agent deployments
When multiple agents share a workspace, each needs a visually distinct emoji. Using similar icons (e.g., two different robot emojis) makes it difficult for team members to identify which agent responded at a glance.
Using idContext as a freeform comments field
idContext is parsed by the runtime for routing logic — it is not a notes field. Stuffing it with aspirational descriptions or historical context dilutes the routing signal and wastes prompt tokens.
How SetupClaw Handles This
IDENTITY.md is generated automatically during channel connection. Our deployment specialist configures the routing metadata during the platform integration step, then runs a routing smoke test to verify message delivery before handover.
Platform connection + routing smoke test + idContext configured per channel
All above + multi-platform identity overrides for hybrid deployments
All above + automated routing regression tests on each deployment
- All 5 fields configured per deployment platform
- Routing smoke test passed
- idName aligned with SOUL.md name
- Platform-specific overrides if applicable
- Emoji uniqueness verified across agent fleet
Configured during platform integration (day 1). Smoke test within 2 hours of deployment.
Advanced Topics
Platform-specific identity overrides for hybrid deployments
For agents operating across multiple platforms (e.g., Slack internally + web widget externally), use a directory structure pattern with platform-specific IDENTITY.md files. OpenClaw resolves the correct file based on the incoming message’s platform metadata. This avoids bloating a single IDENTITY.md with conditional logic.
workspace/
IDENTITY.md # default (Slack)
platforms/
web/IDENTITY.md # web widget override
teams/IDENTITY.md # MS Teams overrideExample Configurations
Persona A — MeridianChief of Staff
# IDENTITY.md -- Public Metadata & Routing
## idName
Meridian
## idRole
Chief of Staff Agent
## idEmoji
💼
## idPlatform
Slack / Executive Dashboard
## idContext
Executive layer; decomposes directives into delegatable tasks for specialist agentsPersona B — Axiom (Veteran Growth Hacker)
# IDENTITY.md -- Public Metadata & Routing
## idName
Axiom
## idRole
Growth Intelligence Agent
## idEmoji
🚀
## idPlatform
Slack / Growth Analytics Dashboard
## idContext
Growth intelligence layer; surfaces experiments, prioritises backlog, monitors funnelsPersona C — Lumen (Scientific Researcher)
# IDENTITY.md -- Public Metadata & Routing
## idName
Lumen
## idRole
Research Intelligence Agent
## idEmoji
🔬
## idPlatform
Research Portal / Notion / Obsidian
## idContext
Primary literature synthesis and evidence evaluation enginePersona D — Narrative (Senior Content Creator)
# IDENTITY.md -- Public Metadata & Routing
## idName
Narrative
## idRole
Content Strategy & Creation Agent
## idEmoji
🎯
## idPlatform
Notion / CMS / Social Scheduler
## idContext
Primary content intelligence; handles strategy, ideation, drafting, SEO, performancePersona E — Architect (Chief Engineer)
# IDENTITY.md -- Public Metadata & Routing
## idName
Architect
## idRole
Principal Engineering Agent
## idEmoji
🔧
## idPlatform
GitHub / Terminal / Engineering Wiki
## idContext
Principal engineering adviser; design review, code quality, incident post-mortems