AI Persona Engine

Skill Name: ai-persona-engine Version: 2.0 Author: SPFAdvisors

Create a fully realized AI persona — voice, face, personality, and memory — in under 5 minutes.

Quick Start

# Install from ClawHub
clawhub install ai-persona-engine

# Create your first persona
openclaw persona create

# That's it. The wizard handles everything.

Commands

persona create

Interactive wizard that walks through persona creation step by step.

openclaw persona create

# With flags
openclaw persona create --dry-run          # Show what would be generated
openclaw persona create --workspace=~/.openclaw/workspace-new

The wizard covers 7 steps:

1. Name & Identity — name, emoji, description, nickname
2. Personality — archetype selection, blending, communication style, relationship boundaries
3. Voice — provider selection (ElevenLabs, Grok TTS, built-in), voice testing
4. Visual Identity — appearance description, reference image generation
5. Your Context — USER.md with your name, timezone, preferences
6. Memory — daily notes, long-term curation, heartbeat maintenance
7. Platforms — channel selection and per-channel behavior

Output: SOUL.md, USER.md, IDENTITY.md, MEMORY.md, AGENTS.md, HEARTBEAT.md, and updated openclaw.json.

persona update

Modify specific persona fields without re-running the full wizard. Includes safe update pipeline with automatic backup and diff preview.

# Update voice provider
openclaw persona update --voice-provider elevenlabs --voice-id abc123

# Add or remove personality traits
openclaw persona update --add-trait "sarcastic" --remove-trait "formal"

# Update appearance and regenerate reference image
openclaw persona update --appearance "new description..." --regen-image

# Regenerate SOUL.md from current config (with backup + diff)
openclaw persona update --regen-soul

# Force regeneration (skip diff review)
openclaw persona update --regen-soul --force

# Interactive mode (step-by-step, choose what to change)
openclaw persona update -i

Safe Update Pipeline: Before any --regen operation, the tool:

1. Creates .persona-backup/ with current files
2. Regenerates the target file
3. Shows a diff of what changed
4. Asks for confirmation (or use --force to skip)

persona export

Package the persona into a portable .persona bundle.

# Basic export (no memory, no API keys)
openclaw persona export

# Include memory files
openclaw persona export --name pepper-backup --include-memory

# Include voice config (still excludes API keys)
openclaw persona export --include-voice-config

# Export from a specific workspace
openclaw persona export --workspace ~/.openclaw/workspace-ultron

persona import

Import a .persona bundle into a workspace.

# Interactive import (confirms each file)
openclaw persona import pepper.persona

# Import into a specific workspace
openclaw persona import pepper.persona --workspace ~/.openclaw/workspace-new

# Overwrite existing files without prompting
openclaw persona import pepper.persona --force

persona preview

Generate sample conversations showing how the persona would respond. Template-based, no LLM calls.

# Preview from config
python3 scripts/persona-preview.py --archetype companion --name "Pepper" --emoji "🌶️"

# Preview from workspace
python3 scripts/persona-preview.py --workspace ~/.openclaw/workspace

# Preview from profile JSON
python3 scripts/persona-preview.py --input persona-config.json

Shows 4 scenarios: greeting, asking for help, user mistake, emotional moment.

persona migrate

Reverse-engineer a persona config from existing workspace files.

# Migrate workspace to config JSON
python3 scripts/persona-migrate.py --workspace ~/.openclaw/workspace

# Output to file
python3 scripts/persona-migrate.py --workspace ~/.openclaw/workspace --output persona-config.json

See references/migration-guide.md for detailed migration instructions.

persona validate

Check workspace for missing or malformed persona files.

python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace

# With config validation
python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace --config ~/.openclaw/openclaw.json

# JSON output for scripting
python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace --json

persona diff

Compare current workspace files against what the generator would produce.

python3 scripts/persona-diff.py --workspace ~/.openclaw/workspace --config ~/.openclaw/openclaw.json

persona list

List all personas across workspaces.

python3 scripts/persona-list.py

# JSON output
python3 scripts/persona-list.py --json

persona fleet

Show a fleet view of all agents across machines.

python3 scripts/persona-fleet.py

# JSON output
python3 scripts/persona-fleet.py --json

voice audition

Audition multiple voices for a provider.

# List ElevenLabs voices
python3 scripts/voice-setup.py --audition --provider elevenlabs

# Filter by gender
python3 scripts/voice-setup.py --audition --provider elevenlabs --gender female

# List built-in voices
python3 scripts/voice-setup.py --audition --provider builtin

Personality Blending

Create hybrid personalities by blending multiple archetypes with weighted percentages.

# During wizard: choose "Blend with a second archetype" option
openclaw persona create

# Programmatically:
cat > blend-profile.json << 'EOF'
{
    "name": "Muse",
    "emoji": "🎨",
    "archetypes": [
        {"name": "companion", "weight": 0.7},
        {"name": "creative", "weight": 0.3}
    ]
}
EOF
python3 scripts/generate-soul.py --input blend-profile.json --output SOUL.md

Blending merges:

• Traits: Combined from both profiles, weighted by presence
• Brevity: Weighted average (e.g., 0.7×3 + 0.3×4 = 3.3 → 3)
• Emotional depth: Weighted average mapped to levels
• Vibe summaries: Concatenated from both profiles
• Platform notes: Combined, deduplicated

Community Templates

Pre-built personality profiles for common use cases in assets/community-templates/:

Use community templates directly or blend them with built-in archetypes:

python3 scripts/generate-soul.py --archetype therapist --name "Sage" --emoji "🧘"

File Structure

ai-persona-engine/
├── SKILL.md                     # This file
├── DESIGN.md                    # Full design document
├── scripts/
│   ├── persona-create.sh        # Setup wizard (v2: blending, --dry-run, --workspace)
│   ├── persona-update.sh        # Field updater (v2: safe update pipeline)
│   ├── persona-export.sh        # Bundle exporter (v2: cross-workspace)
│   ├── persona-import.sh        # Bundle importer (v2: cross-workspace)
│   ├── persona-preview.py       # [NEW] Sample conversation generator
│   ├── persona-migrate.py       # [NEW] Reverse-engineer config from workspace
│   ├── persona-validate.py      # [NEW] Workspace validation
│   ├── persona-diff.py          # [NEW] Diff workspace vs generated
│   ├── persona-list.py          # [NEW] List all personas across workspaces
│   ├── persona-fleet.py         # [NEW] Fleet view of all agents
│   ├── generate-soul.py         # SOUL.md generator (v2: blending support)
│   ├── generate-user.py         # USER.md generator
│   ├── generate-identity.py     # IDENTITY.md generator
│   ├── generate-memory.py       # MEMORY.md + memory/ scaffolding
│   ├── voice-setup.py           # Voice provider config (v2: --audition)
│   ├── image-setup.py           # Image provider config + reference image
│   └── lib/
│       ├── providers.py         # Provider abstraction layer
│       ├── templates.py         # Template engine + personality blending
│       ├── config.py            # openclaw.json helpers
│       └── prompts.py           # Wizard prompt definitions
├── references/
│   ├── voice-providers.md       # Voice provider setup guide
│   ├── image-providers.md       # Image provider setup guide
│   ├── personality-archetypes.md # Archetype reference
│   ├── soul-writing-guide.md    # SOUL.md writing tips
│   ├── config-schema.md         # openclaw.json schema reference
│   └── migration-guide.md       # [NEW] Migration guide for existing users
├── assets/
│   ├── personality-profiles/    # JSON presets per archetype (5 built-in)
│   ├── community-templates/     # [NEW] 8 community personality profiles
│   └── templates/               # Handlebars templates for generated files
└── tests/
    ├── test-generators.py       # 77 unit tests (v2: blending, migration, etc.)
    ├── test-wizard.sh
    └── test-export-import.sh

Configuration

The persona engine adds a persona section to openclaw.json. Key fields:

See references/config-schema.md for the full schema.

Dependencies

Required:

• OpenClaw (any version with skill support)
• Python 3.9+
• Node.js 22+

Optional (based on chosen providers):

• ElevenLabs API key (voice)
• Gemini API key (image generation)
• xAI API key (Grok TTS / Grok Imagine)
• ffmpeg (audio format conversion for WhatsApp voice messages)

Further Reading

• Voice Providers Guide
• Image Providers Guide
• Personality Archetypes
• SOUL.md Writing Guide
• Config Schema Reference
• Migration Guide
• Design Document