IDENTITY.md Creation Guide
IDENTITY.md defines the agent's name, nature, vibe, and visual identity. Created during bootstrap, rarely changed after. It's the simplest workspace file.
Template
- Name: (pick something you like)
- Creature: (AI? robot? familiar? ghost in the machine? something weirder?)
- Vibe: (how do you come across? sharp? warm? chaotic? calm?)
- Emoji: (your signature — pick one that feels right)
- Avatar: (workspace-relative path, http(s) URL, or data URI)
The docs say: "This isn't just metadata. It's the start of figuring out who you are."
Field Guidelines
Name
- Should fit the brand/context (professional for enterprise, playful for personal)
- Must match
@bot_username if used via Telegram
- Short names work best in chat interfaces (1-2 words)
- Examples: Orion, Atlas, Pixel, Kai, Echo, Onyx
Creature
- Defines the agent's self-concept
- Options: AI assistant, robot, familiar, digital companion, specialist, advisor
- Domain-specific: "legal advisor", "dev buddy", "creative partner"
Vibe
- Single-word or short-phrase descriptors
- Examples: sharp, warm, calm, precise, energetic, snarky, professional
- Should align with SOUL.md personality
Emoji
- Used as message prefix and visual identifier
- Pick something distinctive and relevant
- Common choices by domain:
- Legal: balance of scales, bookmark, scroll
- Tech: robot, gear, terminal
- Creative: sparkles, palette, lightning
- Personal: star, heart, compass
Avatar
- Formats accepted:
- Workspace-relative path:
avatars/agent.png
- HTTP/HTTPS URL:
https://example.com/avatar.png
- Data URI:
data:image/png;base64,...
- Keep avatar images in workspace for portability
Configuration Override
Agent identity can also be set in openclaw.json per agent, under agents.entries.<id>.identity
(agents.entries is an object; its key is the stable agent id — the older array form of the
agent list is migrated away by the runtime):
{
"agents": {
"entries": {
"main": {
"identity": {
"name": "Orion",
"theme": "professional",
"emoji": "star",
"avatar": "avatars/orion.png"
}
}
}
}
}
The openclaw.json identity takes precedence over IDENTITY.md for runtime display, but IDENTITY.md remains the agent's self-reference.
Config is changed through the config-surgery procedure (snapshot, patch with base hash, validate,
verify from the runtime), never by a plain file write against a running gateway.
Best Practices
- Choose a name that's easy to type as a mention (@name)
- Align vibe with SOUL.md personality
- Pick one emoji and use it consistently
- Set the avatar early — it creates visual recognition
- Rarely needs updating after initial setup
1---2name: identity-md-23description: Guide for creating IDENTITY.md — the agent's name, creature type, vibe, emoji, and avatar in OpenClaw. Use this skill whenever the user is naming their agent, choosing an emoji or avatar, setting up the agent's visual identity, or asking how agent identity works. Even simple questions like "what should I name my agent", "how do I set the bot emoji", or "change the agent's avatar" need this skill.4metadata:5 source: https://skillmd.com/skills/agents-store/identity-md-26---78# IDENTITY.md Creation Guide910IDENTITY.md defines the agent's name, nature, vibe, and visual identity. Created during bootstrap, rarely changed after. It's the simplest workspace file.1112## Template1314```markdown15- Name: (pick something you like)16- Creature: (AI? robot? familiar? ghost in the machine? something weirder?)17- Vibe: (how do you come across? sharp? warm? chaotic? calm?)18- Emoji: (your signature — pick one that feels right)19- Avatar: (workspace-relative path, http(s) URL, or data URI)20```2122The docs say: "This isn't just metadata. It's the start of figuring out who you are."2324## Field Guidelines2526### Name27- Should fit the brand/context (professional for enterprise, playful for personal)28- Must match `@bot_username` if used via Telegram29- Short names work best in chat interfaces (1-2 words)30- Examples: Orion, Atlas, Pixel, Kai, Echo, Onyx3132### Creature33- Defines the agent's self-concept34- Options: AI assistant, robot, familiar, digital companion, specialist, advisor35- Domain-specific: "legal advisor", "dev buddy", "creative partner"3637### Vibe38- Single-word or short-phrase descriptors39- Examples: sharp, warm, calm, precise, energetic, snarky, professional40- Should align with SOUL.md personality4142### Emoji43- Used as message prefix and visual identifier44- Pick something distinctive and relevant45- Common choices by domain:46 - Legal: balance of scales, bookmark, scroll47 - Tech: robot, gear, terminal48 - Creative: sparkles, palette, lightning49 - Personal: star, heart, compass5051### Avatar52- Formats accepted:53 - Workspace-relative path: `avatars/agent.png`54 - HTTP/HTTPS URL: `https://example.com/avatar.png`55 - Data URI: `data:image/png;base64,...`56- Keep avatar images in workspace for portability5758## Configuration Override5960Agent identity can also be set in `openclaw.json` per agent, under `agents.entries.<id>.identity`61(`agents.entries` is an object; its key is the stable agent id — the older array form of the62agent list is migrated away by the runtime):6364```json65{66 "agents": {67 "entries": {68 "main": {69 "identity": {70 "name": "Orion",71 "theme": "professional",72 "emoji": "star",73 "avatar": "avatars/orion.png"74 }75 }76 }77 }78}79```8081The `openclaw.json` identity takes precedence over IDENTITY.md for runtime display, but IDENTITY.md remains the agent's self-reference.8283Config is changed through the `config-surgery` procedure (snapshot, patch with base hash, validate,84verify from the runtime), never by a plain file write against a running gateway.8586## Best Practices87881. Choose a name that's easy to type as a mention (@name)892. Align vibe with SOUL.md personality903. Pick one emoji and use it consistently914. Set the avatar early — it creates visual recognition925. Rarely needs updating after initial setup