Agent Creator

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