IDENTITY.md is the 📝OpenClaw configuration file that defines an agent's factual identity — its name, role, creator, organizational affiliation, and the boundaries of its operational authority. It answers "Who are you?" while 📝SOUL.md answers "How should you behave?"

IDENTITY.md resides at the workspace root (e.g., ~/.openclaw/workspace/IDENTITY.md) and is loaded during agent initialization via 📝BOOTSTRAP.md. The file ensures that an agent understands its primary function and stays within its intended job description — a structural constraint that keeps role drift in check across long-running sessions and multi-agent systems.

Key Facts

File type: Markdown configuration file
Location: Workspace root (~/.openclaw/workspace/IDENTITY.md)
Loaded by: BOOTSTRAP.md during agent initialization
Parent system: OpenClaw
Purpose: Factual identity and role boundaries (not behavioral tone — that belongs in SOUL.md)

How It Works

IDENTITY.md contains structured fields that the agent reads to establish its self-concept:

Name — the agent's display name (the only practically required field)
Role — what the agent does (e.g., "Lead Architect," "Executive Assistant," "Research Analyst")
Created by — the team or individual who built the agent
Organization — company or project affiliation
Version — agent configuration version
Languages — programming languages the agent specializes in
Channels — preferred or assigned communication channels (Slack, WhatsApp, Discord, etc.)

The CLI command openclaw agents set-identity --from-identity reads the file and writes its fields into the agent's runtime configuration. Identity can also be set directly via flags:

openclaw agents set-identity --agent main --name "BrianBot" --emoji "🤖"

The critical design principle is separation of concerns: IDENTITY.md holds facts, SOUL.md holds personality. Putting behavioral instructions in IDENTITY.md dilutes its purpose. An agent's identity is "I am a Lead Architect for One Studio" — its soul is "I communicate directly, prefer structural framing, and match the gravity of the subject."

Why It Matters

In single-agent systems, identity boundaries are a convenience. In multi-agent systems like 📝Brian Bot's 57-agent ecosystem, they become structural. Each agent needs to know what it is and — critically — what it is not. IDENTITY.md prevents a research agent from taking deployment actions, a social media agent from modifying code, or a customer support agent from making architectural decisions. The file is the line between "this agent can help with that" and "that's outside my role."

This pattern of structured, file-based identity definition is what makes OpenClaw's agent architecture version-controllable and templatable. New agents inherit identity scaffolding from templates. Existing agents evolve through file edits, not prompt rewrites.

FAQ

What is the difference between IDENTITY.md and SOUL.md?

SOUL.md defines how the agent behaves — personality, tone, values, humor. IDENTITY.md defines what the agent is — name, role, boundaries, affiliations. An agent's identity is its job description; its soul is its personality.

Is IDENTITY.md required?

The file is not strictly required to launch an agent, but without it the agent has no way to identify itself when asked "who are you?" The name field is practically required for any agent that interacts with humans.

How does IDENTITY.md relate to CLAUDE.md?

📝CLAUDE.md serves a similar role-definition function in 📝Claude Code — project instructions that shape how the agent operates. IDENTITY.md is OpenClaw-specific and part of a broader file system (SOUL, IDENTITY, TOOLS, SKILLS, MEMORY, USER, HEARTBEAT, BOOTSTRAP) that together compose a full agent definition.

Can multiple agents share the same IDENTITY.md?

Agents can share templates, but each running agent should have its own identity configuration. Two agents with identical identities in the same system would create ambiguity in routing and accountability.

📝OpenClaw — the open-source AI assistant platform this file belongs to
📝Markdown-File Agent Definition — the design pattern IDENTITY.md belongs to
📝SOUL.md — temperament, values, and conversational personality
📝BOOTSTRAP.md — the initialization file that loads IDENTITY.md
📝TOOLS.md — available APIs, functions, and integrations
📝SKILLS.md — installable capability modules
📝Collaborative Augmentation — the broader framework for agent-human collaboration