> ## Documentation Index > Fetch the complete documentation index at: https://docs.clawup.sh/llms.txt > Use this file to discover all available pages before exploring further. # Identity Manifest Reference > identity.yaml configuration file 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`](https://github.com/stepandel/army-create) (`npx army-create`). For a step-by-step guide, see [Creating Identities](/guides/creating-identities). ## Schema ```typescript theme={null} 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>; 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 `). 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//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](/architecture/identities#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](/architecture/identities#dep-registry). | | `plugins` | string\[] | `[]` | OpenClaw plugins to configure. Each entry must match a key in the [plugin registry](/architecture/identities#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 `_SCREAMING_SNAKE_CASE` env var. See [Environment Variables](/configuration/environment#identity-requiredsecrets). | ### 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. ```yaml theme={null} 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](/guides/hooks). ## Examples ### Minimal Identity The smallest valid `identity.yaml` — only required fields: ```yaml theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} 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/.yaml` file in the identity directory — see the [Plugins guide](/guides/plugins) 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](/guides/hooks) 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. ```yaml theme={null} 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): 1. **Identity defaults** — `pluginDefaults` in `identity.yaml` 2. **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//SKILL.md` file (private skills) or valid `clawhub:` prefix (public skills)