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 the fastest way to scaffold a new identity, use army-create (npx army-create). For a step-by-step guide, 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>>;
  hooks?: Hooks;                 // Identity-level lifecycle hooks
  requiredSecrets?: string[];  // Additional secret keys beyond plugins/deps
}

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`. Supports multiple providers — see examples below. If omitted, uses the stack-level `defaultModel`.
`backupModel`	string	—	Fallback model used when the primary is unavailable. Same format as `model`.

Supported Model Providers

Provider	Example Models
Anthropic	`anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-5`, `anthropic/claude-haiku-4-5`
OpenAI	`openai/gpt-4o`, `openai/o3`, `openai/o4-mini`
Google	`google/gemini-2.5-pro`, `google/gemini-2.5-flash`
OpenRouter	Any model available on OpenRouter
`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.

Secrets

Field	Type	Default	Description
`requiredSecrets`	string[]	`[]`	Additional secret keys this identity needs beyond what `plugins` and `deps` imply. Each entry is a camelCase key (e.g., `notionApiKey`) that maps to a `<ROLE>_SCREAMING_SNAKE_CASE` env var. See Environment Variables.

Hooks

Field	Type	Default	Description
`hooks`	`Hooks`	—	Identity-level lifecycle hooks that run for all agents using this identity.

Identity-level hooks run for every agent that uses this identity. All four hook types are available (resolve, onboard, postProvision, preStart). Identity hooks execute after swarm hooks and before plugin hooks.

hooks:
  resolve:
    SENTRY_PROJECT_SLUG: |
      curl -s https://sentry.io/api/0/projects/ \
        -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
        | jq -r '.[0].slug'
  postProvision: |
    echo "Installing engineering tools..."
    npm install -g turbo prettier
  preStart: |
    echo "Verifying repo access..."
    gh auth status

For the full reference including execution order and all hook types, see the Lifecycle Hooks guide.

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:
        - "*"

hooks:
  postProvision: |
    echo "Installing engineering tools..."
    npm install -g turbo prettier
  preStart: |
    echo "Cloning working repo..."
    cd /home/ubuntu && gh repo clone $GITHUB_REPO workspace-repo

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

# Secrets not covered by plugins/deps above
requiredSecrets:
  - sentryDsn
  - datadogApiKey

The requiredSecrets entries above will generate per-agent env vars like ENG_SENTRY_DSN and ENG_DATADOG_API_KEY during clawup init.

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)
`codex`	`codex`	OpenAI Codex CLI (`@openai/codex`)

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 — configures OpenClaw web search (`openclaw config set tools.web.search`) with provided API key

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. You can also bundle custom plugin manifests by placing a plugins/<name>.yaml file in the identity directory — see the Plugins guide for details on creating and overriding plugin manifests.

Lifecycle Hooks

Hooks are shell scripts that run at specific points during deployment. They’re available at the swarm (clawup.yaml), identity (identity.yaml), and plugin level. Hooks can auto-resolve derived secrets, run interactive onboarding, install server-side tools, and perform pre-launch configuration. See the Lifecycle Hooks guide for details.

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 — Per-agent plugins configuration in the deployment manifest (clawup.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

Supported Model Providers

Infrastructure

Dependencies

Secrets

Hooks

Examples

Minimal Identity

Research Agent

Full-Featured Engineering Agent

Available Registries

Coding Agent Registry

Dep Registry

Plugin Registry

Lifecycle Hooks

Plugin Defaults

Override Hierarchy

Identity vs Deployment Manifest

Validation

​Schema

​Required Fields

​Optional Fields

​Model Configuration

​Supported Model Providers

​Infrastructure

​Dependencies

​Secrets

​Hooks

​Examples

​Minimal Identity

​Research Agent

​Full-Featured Engineering Agent

​Available Registries

​Coding Agent Registry

​Dep Registry

​Plugin Registry

​Lifecycle Hooks

​Plugin Defaults

​Override Hierarchy

​Identity vs Deployment Manifest

​Validation

Schema

Required Fields

Optional Fields

Model Configuration

Supported Model Providers

Infrastructure

Dependencies

Secrets

Hooks

Examples

Minimal Identity

Research Agent

Full-Featured Engineering Agent

Available Registries

Coding Agent Registry

Dep Registry

Plugin Registry

Lifecycle Hooks

Plugin Defaults

Override Hierarchy

Identity vs Deployment Manifest

Validation