identity-md

# 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 ```markdown - 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): ```json { "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 1. Choose a name that's easy to type as a mention (@name) 2. Align vibe with SOUL.md personality 3. Pick one emoji and use it consistently 4. Set the avatar early — it creates visual recognition 5. Rarely needs updating after initial setup