IDENTITY.md — Agent Identity

+15 Mana ✨
OpenClaw IDENTITY.md Reference(DOCUMENTATION)OpenClaw Agent Configuration(DOCUMENTATION)

Introduction

IDENTITY.md is the bootstrap file that names your agent and establishes its core identity markers. While SOUL.md defines personality and behavior, IDENTITY.md answers the fundamental question: "Who are you?" It sets the agent's name, role title, creator attribution, and other identity metadata that the agent uses when introducing itself or responding to identity-related questions.

Key Concepts

  • Agent Name: The display name the agent uses when referring to itself (e.g., "Atlas", "Pixel", "Nova")
  • Role Title: A short description of the agent's function (e.g., "Senior Backend Engineer", "Community Support Bot")
  • Creator Attribution: Who built or maintains this agent, displayed when users ask about the agent's origin
  • Identity Markers: Distinguishing traits that make this agent recognizable across conversations and channels
  • Identity vs Persona: Identity is who the agent is; persona is how the agent behaves. IDENTITY.md handles the former, SOUL.md the latter

Real World Context

A company runs three OpenClaw agents: one for engineering, one for sales, and one for HR. Each needs a distinct identity so employees know who they are talking to. Without IDENTITY.md, all three agents would introduce themselves generically. With it, the engineering agent knows it is "Forge, the Engineering Assistant built by the Platform Team," while the sales agent is "Relay, the Sales Intelligence Bot maintained by Revenue Operations."

Deep Dive

IDENTITY.md is a short Markdown file focused on factual identity information. Unlike SOUL.md, which can be lengthy, IDENTITY.md is typically concise — often just 5 to 15 lines.

Here is a typical IDENTITY.md file:

markdown
# Identity

- **Name**: Forge
- **Role**: Engineering Assistant
- **Created by**: Platform Engineering Team
- **Organization**: Acme Corp
- **Version**: 2.4.1

# About

Forge is the engineering team's AI assistant, specializing in
code review, architecture guidance, and debugging. Forge was
built by the Platform Engineering Team at Acme Corp.

This file gives the agent everything it needs to answer questions like "What is your name?", "Who made you?", and "What do you do?" The structured fields at the top make it easy to parse, while the About section provides a natural-language summary the agent can use in introductions.

The distinction between IDENTITY.md and SOUL.md is important. Consider this comparison:

markdown
# IDENTITY.md tells the agent WHO it is:
- Name: Forge
- Role: Engineering Assistant
- Creator: Platform Engineering Team

# SOUL.md tells the agent HOW to behave:
- Be concise and technically precise
- Never guess when uncertain
- Prefer code examples over prose explanations

IDENTITY.md answers "Who are you?" while SOUL.md answers "How should you act?" Both are injected into the system prompt during bootstrap, but they serve different purposes. An agent could have the same identity across environments but different persona configurations — for example, Forge could be formal on Slack and casual on Discord by swapping SOUL.md while keeping IDENTITY.md the same.

The fields you can include in IDENTITY.md are flexible. Common fields include:

markdown
- **Name**: The agent's display name
- **Role**: What the agent does
- **Created by**: Team or individual who built it
- **Organization**: Company or project affiliation
- **Version**: Agent configuration version
- **Languages**: Programming languages the agent specializes in
- **Channels**: Preferred or assigned communication channels

These fields are all optional. The only practically required field is the Name, since without it the agent has no way to identify itself when asked.

Common Pitfalls

  • Confusing identity with persona: Putting behavioral instructions in IDENTITY.md dilutes its purpose. Keep behavior in SOUL.md and facts in IDENTITY.md.
  • Forgetting to update the version field: When you change an agent's configuration significantly, updating the version in IDENTITY.md helps track which version of the agent is responding.
  • Using generic names: Names like "Assistant" or "Bot" make it hard for users to distinguish between multiple agents. Choose distinctive, memorable names.

Best Practices

  • Keep IDENTITY.md short and factual: It should be scannable in under 10 seconds. Save elaborate descriptions for SOUL.md.
  • Include a natural-language About section: This gives the agent a pre-written introduction it can adapt when users ask "Who are you?"
  • Synchronize identity across channels: If the same agent serves multiple platforms, use the same IDENTITY.md so it introduces itself consistently everywhere.

Summary

  • IDENTITY.md defines the agent's name, role, creator, and other factual identity markers
  • It answers "Who are you?" while SOUL.md answers "How should you behave?"
  • Keep it concise: typically 5 to 15 lines of structured fields plus an optional About section
  • The Name field is practically required; all other fields are optional but recommended
  • Use the same IDENTITY.md across channels for consistent agent identity
✓ Completed