agent-creator

Full workflow for creating an OpenClaw Agent. Use when the user says 'create an agent', 'make a new agent', 'add a bot', or needs to set up a new AI assistant. Covers the complete setup process including (1) adding agent config and peer bindings to openclaw.json, (2) creating workspace directory with SOUL.md persona, (3) scaffolding required folders and files, (4) copying agent runtime configs from main, (5) restarting gateway to apply changes.

Agent Creator - OpenClaw Agent Setup Tool

Automates the full end-to-end flow for creating an OpenClaw Agent.

Trigger Phrases

Activate when user says things like:

• "Create an agent"
• "Make a new bot"
• "Set up a new agent"
• "Add an AI assistant"

Full Workflow

Step 1: Gather Information

Ask the user:

1. Agent ID (lowercase, hyphens only): e.g. qisi, code-review, brainstorm
2. Agent Display Name: e.g. "Brainstorm Buddy", "Code Reviewer"
3. Purpose / Personality: What does this agent do? What's its style?
4. Group Chat Binding (optional): peer.id of a group chat, e.g. oc_xxx (kind = group)
5. Direct Chat Binding (optional): peer.id of a user, e.g. ou_xxx (kind = direct)

Step 2: Create Workspace Directory

OPENCLAW_DIR=~/.openclaw
mkdir -p $OPENCLAW_DIR/workspace-{agent_id}
mkdir -p $OPENCLAW_DIR/workspace-{agent_id}/memory
mkdir -p $OPENCLAW_DIR/workspace-{agent_id}/skills

Step 3: Write Workspace Files

Create the following files in the workspace directory:

• SOUL.md — Agent persona (see template below)
• USER.md — User info template
• AGENTS.md — Session bootstrap instructions
• HEARTBEAT.md — Heartbeat config
• TOOLS.md — Tool notes
• memory/ — Daily memory folder
• IDENTITY.md — Agent identity definition (optional)
• BOOTSTRAP.md — First-run bootstrap (optional)

AGENTS.md content (copied from ~/.openclaw/workspace/AGENTS.md):

# AGENTS.md - Your Workspace

If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it.

## Every Session

Before doing anything else:

1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
4. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`

## Memory

You wake up fresh each session. These files are your continuity:

- **Daily notes:** `memory/YYYY-MM-DD.md` — raw logs of what happened
- **Long-term:** `MEMORY.md` — your curated memories

## Safety

- Don't exfiltrate private data
- When in doubt, ask.

HEARTBEAT.md content:

# HEARTBEAT.md

# Keep this file empty to skip heartbeat API calls.

TOOLS.md content:

# TOOLS.md - Local Notes

Notes specific to this agent's setup.

Step 4: Create Agent Runtime Directory

OPENCLAW_DIR=~/.openclaw
mkdir -p $OPENCLAW_DIR/agents/{agent_id}/agent
mkdir -p $OPENCLAW_DIR/agents/{agent_id}/sessions

Step 5: Copy Agent Config from Main

OPENCLAW_DIR=~/.openclaw
cp $OPENCLAW_DIR/agents/main/agent/models.json $OPENCLAW_DIR/agents/{agent_id}/agent/
cp $OPENCLAW_DIR/agents/main/agent/auth-profiles.json $OPENCLAW_DIR/agents/{agent_id}/agent/

If the main agent config files don't exist, warn the user and ask them to provide models.json and auth-profiles.json manually.

Step 6: Update openclaw.json

Back up first:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

Read the current config and add the new agent to agents.list:

{
  "id": "{agent_id}",
  "name": "{agent_name}",
  "workspace": "~/.openclaw/workspace-{agent_id}",
  "agentDir": "~/.openclaw/agents/{agent_id}/agent"
}

Add bindings if provided. For group chat:

{
  "agentId": "{agent_id}",
  "match": {
    "channel": "feishu",
    "peer": {
      "kind": "group",
      "id": "{group_chat_id}"
    }
  }
}

For direct chat:

{
  "agentId": "{agent_id}",
  "match": {
    "channel": "feishu",
    "peer": {
      "kind": "direct",
      "id": "{user_id}"
    }
  }
}

Step 7: Install Skills (optional)

If the agent needs specific skills:

cp -r ~/.openclaw/skills/{skill-name} ~/.openclaw/workspace-{agent_id}/skills/

Step 8: Restart Gateway

openclaw gateway restart

Step 9: Verify & Report

Tell the user:

• Agent has been created successfully
• How to interact with it (@ in group chat, or DM)
• How to customize it further (edit SOUL.md, add skills, etc.)

SOUL.md Template

# SOUL.md - {Agent Name}

_{One-line purpose}_

## Core Identity

**You are "{Agent Name}"** — {detailed description}

## Principles

- {principle 1}
- {principle 2}
- {principle 3}

## Style

- {style description}

---

_{Mission statement}_

Final Directory Structure

After creation, the layout should be:

~/.openclaw/
├── agents/
│   └── {agent_id}/
│       ├── agent/
│       │   ├── auth-profiles.json
│       │   └── models.json
│       └── sessions/
└── workspace-{agent_id}/
    ├── AGENTS.md
    ├── BOOTSTRAP.md (optional)
    ├── HEARTBEAT.md
    ├── IDENTITY.md (optional)
    ├── SOUL.md
    ├── TOOLS.md
    ├── USER.md
    ├── memory/
    └── skills/ (optional)

Important Notes

• Workspace directory name should use the agent_id (English lowercase + hyphens), e.g. workspace-brainstorm
• Agent ID must be lowercase alphanumeric with hyphens only
• Group chat binding requires the bot to be manually added to the group (auto-join needs extra permissions)
• Always back up openclaw.json before modifying
• Always copy models.json and auth-profiles.json to the agents directory
• Use the helper script scripts/agent_creator.py to automate the config and directory creation