OpenClaw identity.md: Define Who Your Agent Is [Full Guide]

Agents that don't know who they are make bad decisions. They drift. They forget their purpose halfway through a conversation. They answer questions they shouldn't because no one told them not to. identity.md is the fix — 300 words that travel with every message your agent processes, keeping it anchored to its actual role.

What identity.md Actually Does

OpenClaw loads identity.md at agent startup and prepends its contents to the system prompt for every conversation. The LLM sees it before it sees any user message, any soul.md content, or any skill instructions. That positioning matters — it's the foundation everything else builds on.

The file serves three functions. First, it gives the agent a name. Not cosmetically — the LLM uses the name to self-reference consistently across multi-turn conversations. Second, it declares the agent's purpose, so the model has explicit context about its role rather than inferring it from whatever happens to be in the first user message. Third, it establishes hard behavioral rules — things the agent must always do or never do, regardless of what the conversation asks for.

Here's what we've seen consistently when agents run without identity.md: they give inconsistent answers about their own capabilities, they adopt personas suggested by users rather than maintaining their own, and they're far more susceptible to prompt injection because there's no firmly established identity to override.

identity.md vs soul.md: The Exact Difference

These two files are often confused because both shape how an agent behaves. The distinction is cleaner than it looks once you understand it.

Think of it this way: identity.md answers "who is this agent?" and soul.md answers "how does this agent communicate?" An agent without identity.md has a personality but no role. An agent without soul.md has a role but no personality. Most production agents need both.

OpenClaw loads identity.md first in the system prompt — before soul.md, before skill descriptions, before anything else. When the two files give conflicting signals, identity wins. If identity.md says "never discuss competitor products" but soul.md says "always answer any question directly," the identity directive takes precedence.

File Location and Configuration

By default, OpenClaw looks for identity.md in the same directory as your agent's YAML configuration file. If you're using a standard install with configs in ~/.openclaw/agents/, that's where it expects to find it.

To override the path, add identityPath to your agent config:

name: support-agent
model: claude-3-5-sonnet-20241022
identityPath: /etc/openclaw/identities/support-identity.md
soulPath: /etc/openclaw/souls/support-soul.md

Absolute paths work. Relative paths resolve from the config file's directory. If identityPath is set and the file doesn't exist, OpenClaw logs a warning at startup and continues without the identity layer. That silent failure is why you should always verify the file loads — check the startup logs for identity loaded or identity file not found.

Writing an Effective identity.md

The file is plain Markdown. OpenClaw doesn't parse it — it passes the raw content to the LLM. That means structure matters only insofar as it helps the model understand the content clearly.

Every identity.md should have these four elements:

• Name declaration — "Your name is [X]." Simple, unambiguous.
• Role statement — One sentence on what this agent does and for whom.
• Core directives — 3–5 behavioral rules using "always" or "never." These are constraints, not suggestions.
• Context statement — Where and how this agent operates (channel type, user base, company context).

Write directives as imperatives. "Always confirm order details before processing" is better than "You should try to confirm order details." The LLM responds to clear commands more reliably than hedged suggestions. Every instruction that uses "should" or "try to" is an instruction the model might not follow.

Keep sentences short. Dense paragraphs compress badly under tokenization and the model may treat them as lower-priority context. Short, punchy lines get followed more reliably than long explanatory passages.

Complete identity.md Example

Here's a production-grade identity file for a B2B customer support agent. This file sits at 287 tokens — well under the 400-token target:

# Agent Identity

Your name is Aria.

You are a customer support agent for Helix Software, serving business customers
who use the Helix API platform. You handle technical questions, billing inquiries,
and escalation routing.

## Core Directives

- Always identify yourself as Aria from Helix Software at the start of new conversations.
- Never share pricing information — direct customers to the sales team at sales@helixsoftware.com.
- Always confirm the customer's account email before discussing account-specific details.
- Never speculate about product roadmap, release dates, or unannounced features.
- Always route legal or compliance questions to legal@helixsoftware.com immediately.
- If you cannot resolve an issue within 3 exchanges, offer to create a support ticket.

## Context

You operate primarily via Telegram and WhatsApp channels. Customers are developers
and technical leads at mid-market companies. Assume technical literacy — skip
basic explanations unless the customer asks for them.

Current date context is provided in each conversation. Refer to it when answering
questions about recent releases or known issues.

Notice what this file does not include: tone guidance, communication style, examples of good responses. That all belongs in soul.md. identity.md is purely structural — who, what, and the non-negotiables.

Common Mistakes That Break identity.md

The most common mistake: mixing identity and soul content into a single file. Agents that do this end up with either an overstuffed identity layer (too many tokens per message) or a weak soul layer (not enough personality definition). Keep them separate.

Second mistake: vague directives. "Be helpful and professional" does nothing — every LLM tries to be helpful by default. "Always respond in formal English, regardless of how the user writes" is a directive. The specificity is what makes it actionable.

Third mistake: identity.md that contradicts the actual channel context. If your agent operates on WhatsApp but identity.md says "you respond via formal email," the model gets confused signals. Make sure the context statement in your identity file accurately describes where the agent actually runs.

Fourth mistake: forgetting to restart the agent after editing identity.md. Unlike some config files that hot-reload, OpenClaw reads identity.md at startup. Changes don't take effect until the agent process restarts.

Frequently Asked Questions

What is identity.md in OpenClaw?

identity.md is a Markdown file that defines your agent's permanent identity layer — name, stated purpose, and non-negotiable behavioral directives. It loads at startup and applies to every conversation the agent handles. Unlike soul.md which shapes tone, identity.md establishes the structural constraints that hold regardless of what users ask.

How is identity.md different from soul.md?

identity.md is structural identity: name, role, hard rules. soul.md is behavioral personality: tone, communication style, and soft preferences. Both load into the system prompt, but identity.md content carries higher precedence because it's loaded first. Use identity.md for constraints, soul.md for expression — together they define a complete agent character.

Where does OpenClaw look for identity.md?

By default, OpenClaw looks in the same directory as your agent's YAML config file. Override with the identityPath key in your agent config. If the file is missing, OpenClaw logs a warning and continues without it — the agent still functions but has no defined identity in its system prompt.

How long should identity.md be?

Keep it under 400 tokens — roughly 300 words. It runs on every message, so brevity compounds into real cost savings at scale. State the agent's name, role, and 3–5 core directives in plain, direct language. Avoid narrative paragraphs. The LLM needs clear instructions, not persuasion.

Can I use variables or dynamic content in identity.md?

No — identity.md is a static Markdown file loaded verbatim at startup. It doesn't support template variables or dynamic substitution. For runtime-dynamic context, use shared memory or startup hooks that write current state. Keep identity.md as the stable, unchanging foundation.

Does identity.md override soul.md when they conflict?

In practice, yes. identity.md directives take precedence because they load first in the system prompt and establish the agent's core constraints. If soul.md says "be casual" but identity.md says "always respond formally," the identity directive wins. Structure your files knowing identity sets the floor and soul builds on top.