Skip to main content
Back to Workspace
OpenClawFile 2 of 8 · 5 fields

IDENTITY.mdPublic metadata & routing

Controls how your agent presents itself in multi-agent environments and how messages get routed in group chats.

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

idNameRequired

The public-facing name shown to other agents and users.

idName: "e.g. Atlas Support Bot"
idRoleRequired

A one-line description of this agent's function.

idRole: "e.g. Customer Support Agent"
idEmojiOptional

Visual identifier used in multi-agent chat interfaces.

idEmoji: "e.g. 🤖"
idPlatformRequired

The primary platform where this agent operates.

idPlatform: "e.g. Slack, Feishu, WeChat"
idContextOptional

Additional context about the agent's operating environment.

idContext: "e.g. Operates in #support channel, responds to @atlas..."

Real-World Examples

FinleyManchester · 8 people · Accounting
## 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.

£770

Platform connection + routing smoke test + idContext configured per channel

£1,100

All above + multi-platform identity overrides for hybrid deployments

£2,200

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 override

Example Configurations

Persona AMeridianChief 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 agents
Persona BAxiom (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 funnels
Persona CLumen (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 engine
Persona DNarrative (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, performance
Persona EArchitect (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

Skip the complexity — let us configure your workspace

We handle all 8 files, including IDENTITY.md.

Book a Setup Call