Identity Manifest Reference

The identity.yaml manifest is the core of every identity. It declares the agent’s model, plugins, dependencies, skills, and template variables. It lives at the root of an identity directory and is read during deployment. For a step-by-step guide to creating an identity, see Creating Identities.

Schema

interface IdentityManifest {
  name: string;              // Machine-readable identifier
  displayName: string;       // Human-readable name
  role: string;              // Functional role
  emoji: string;             // GitHub shortcode (e.g., "telescope")
  description: string;       // One-line summary
  volumeSize: number;        // Default disk size in GB
  skills: string[];          // Bundled skill directory names
  templateVars: string[];    // Template variables used in workspace files
  model?: string;            // AI model identifier
  backupModel?: string;      // Fallback model
  codingAgent?: string;      // Coding agent CLI (e.g., "claude-code")
  instanceType?: string;     // Cloud instance type override
  deps?: string[];           // System dependencies
  plugins?: string[];        // OpenClaw plugins
  pluginDefaults?: Record<string, Record<string, unknown>>;
}

Required Fields

Field	Type	Description
`name`	string	Machine-readable identifier. Used in resource names and logging. Examples: `eng`, `researcher`, `pm`
`displayName`	string	Human-readable name shown in the UI and Slack messages. Examples: `Titus`, `Atlas`, `Juno`
`role`	string	Functional role identifier. Used for agent resolution (`clawup ssh <role>`). Examples: `pm`, `eng`, `tester`, `researcher`
`emoji`	string	GitHub emoji shortcode without colons. Used in the OpenClaw UI. Examples: `telescope`, `clipboard`, `building_construction`, `mag`
`description`	string	One-line summary of the agent’s purpose. Shown during `clawup init` and in status output.
`volumeSize`	number	Default persistent storage in GB. Can be overridden per-agent in the deployment manifest. Engineers typically need more (50GB) for repos; research/PM roles need less (20-30GB).
`skills`	string[]	List of skill directory names bundled with this identity. Each entry corresponds to a `skills/<name>/SKILL.md` file. Supports `clawhub:` prefix for public skills.
`templateVars`	string[]	Template variable names used in workspace files (e.g., `SOUL.md`, `USER.md`). Values are collected during `clawup init` and substituted at deploy time.

Optional Fields

Model Configuration

Field	Type	Default	Description
`model`	string	—	Primary AI model identifier. Format: `provider/model-name` (e.g., `anthropic/claude-opus-4-6`). If omitted, uses the stack-level default.
`backupModel`	string	—	Fallback model used when the primary is unavailable. Same format as `model`.
`codingAgent`	string	`claude-code`	Coding agent CLI to install on the cloud instance. Must match a key in the coding agent registry.

Infrastructure

Field	Type	Default	Description
`instanceType`	string	—	Override the default cloud instance type for agents using this identity. Provider-specific (e.g., `t3.large` for AWS, `cx32` for Hetzner).

Dependencies

Field	Type	Default	Description
`deps`	string[]	`[]`	System-level tools installed on the agent. Each entry must match a key in the dep registry.
`plugins`	string[]	`[]`	OpenClaw plugins to configure. Each entry must match a key in the plugin registry.
`pluginDefaults`	object	`{}`	Per-plugin default configuration. Keyed by plugin name, values are plugin-specific config objects. Can be overridden per-deployment via plugin config files.

Examples

Minimal Identity

The smallest valid identity.yaml — only required fields:

name: greeter
displayName: Gabi
role: greeter
emoji: wave
description: Friendly welcome bot
volumeSize: 10
skills: []
templateVars:
  - OWNER_NAME

Research Agent

A research-focused agent with Brave Search and Slack:

name: researcher
displayName: Atlas
role: researcher
emoji: telescope
description: Deep research, source analysis, report generation
volumeSize: 20
model: anthropic/claude-sonnet-4-5
codingAgent: claude-code

deps:
  - brave-search

plugins:
  - slack

pluginDefaults:
  slack:
    mode: socket
    dm:
      enabled: true
      policy: open

skills:
  - research-report

templateVars:
  - OWNER_NAME
  - TIMEZONE
  - WORKING_HOURS
  - USER_NOTES

Full-Featured Engineering Agent

A production engineer identity with all fields used:

name: eng
displayName: Titus
role: eng
emoji: building_construction
description: Lead engineering, coding, shipping
volumeSize: 50
instanceType: t3.large

model: anthropic/claude-opus-4-6
backupModel: anthropic/claude-sonnet-4-5
codingAgent: claude-code

deps:
  - gh
  - brave-search

plugins:
  - openclaw-linear
  - slack

pluginDefaults:
  openclaw-linear:
    stateActions:
      triage: remove
      backlog: add
      started: add
      completed: remove
      cancelled: remove
  slack:
    mode: socket
    userTokenReadOnly: true
    groupPolicy: open
    dm:
      enabled: true
      policy: open
      allowFrom:
        - "*"

skills:
  - eng-queue-handler
  - eng-ticket-workflow
  - eng-pr-tester
  - pr-review-resolver

templateVars:
  - OWNER_NAME
  - TIMEZONE
  - WORKING_HOURS
  - USER_NOTES
  - LINEAR_TEAM
  - GITHUB_REPO

Available Registries

Coding Agent Registry

The codingAgent field selects which coding CLI is installed.

Key	CLI Binary	Description
`claude-code`	`claude`	Claude Code CLI (default)

Each entry provides an install script, model configuration, and OpenClaw cliBackends config. Defined in packages/core/src/coding-agent-registry.ts.

Dep Registry

System-level tools declared via the deps field.

Key	What It Installs
`gh`	GitHub CLI — installed from official apt repo, authenticated with provided token
`brave-search`	Brave Search API key — config-only, sets environment variable for API access

Defined in packages/core/src/dep-registry.ts.

Plugin Registry

OpenClaw plugins declared via the plugins field.

Key	What It Does
`openclaw-linear`	Linear issue tracking — webhook-driven ticket queuing, per-agent routing rules, state management
`slack`	Slack bot integration — Socket Mode, DMs, group chats, emoji reactions

Defined in packages/core/src/plugin-registry.ts.

Plugin Defaults

The pluginDefaults field sets per-plugin configuration that ships with the identity. This is the primary way to configure how plugins behave for a specific role.

pluginDefaults:
  openclaw-linear:
    stateActions:
      backlog: add        # Add to queue when ticket enters Backlog
      started: add        # Add to queue when ticket enters Started
      completed: remove   # Remove from queue when completed
  slack:
    mode: socket
    dm:
      enabled: true
      policy: open

Override Hierarchy

Plugin configuration is resolved in this order (later wins):

Identity defaults — pluginDefaults in identity.yaml
Deployment overrides — Plugin config files at ~/.clawup/configs/<stack>/plugins/<plugin>.yaml

Identity vs Deployment Manifest

The identity.yaml and clawup.yaml serve different purposes:

Concern	`identity.yaml`	`clawup.yaml`
What the agent is	Name, personality, skills, model	—
What the agent needs	Deps, plugins, plugin defaults	Plugin/dep overrides
Where the agent runs	—	Provider, region, instance type
How much storage	Default `volumeSize`	Per-agent `volumeSize` override
Template variable names	Declared in `templateVars`	—
Template variable values	—	Owner fields (`ownerName`, `timezone`, etc.)

When both files specify plugins or deps, the deployment manifest values take precedence. This lets you override identity defaults per-deployment without forking the identity.

Validation

Clawup validates identity.yaml at deploy time. The following checks are enforced:

All required fields must be present and non-empty
name, displayName, role, emoji, description must be strings
volumeSize must be a positive number
skills and templateVars must be arrays
Each skill listed must have a corresponding skills/<name>/SKILL.md file (private skills) or valid clawhub: prefix (public skills)

Getting Started

Agents

Integrations

Configuration

Guides

Community

Identity Manifest Reference

Schema

Required Fields

Optional Fields

Model Configuration

Infrastructure

Dependencies

Examples

Minimal Identity

Research Agent

Full-Featured Engineering Agent

Available Registries

Coding Agent Registry

Dep Registry

Plugin Registry

Plugin Defaults

Override Hierarchy

Identity vs Deployment Manifest

Validation

Getting Started

Agents

Integrations

Configuration

Guides

Community

​Schema

​Required Fields

​Optional Fields

​Model Configuration

​Infrastructure

​Dependencies

​Examples

​Minimal Identity

​Research Agent

​Full-Featured Engineering Agent

​Available Registries

​Coding Agent Registry

​Dep Registry

​Plugin Registry

​Plugin Defaults

​Override Hierarchy

​Identity vs Deployment Manifest

​Validation

Schema

Required Fields

Optional Fields

Model Configuration

Infrastructure

Dependencies

Examples

Minimal Identity

Research Agent

Full-Featured Engineering Agent

Available Registries

Coding Agent Registry

Dep Registry

Plugin Registry

Plugin Defaults

Override Hierarchy

Identity vs Deployment Manifest

Validation