How to Add Agents in OpenClaw: The Complete agents add Guide

Adding Your First Agent

The openclaw agents add command is how you create new agents in your OpenClaw workspace. Each agent gets its own directory with a SOUL.md file that defines its identity, rules, and capabilities. Here is the basic flow:

# Add a new agent with a name
openclaw agents add content-writer

# OpenClaw creates:
#   agents/content-writer/
#   agents/content-writer/SOUL.md

# Start chatting with your new agent
openclaw agent --agent content-writer --message "Hello"

# Or open an interactive session
openclaw agent --agent content-writer

That's it. One command creates the agent. The generated SOUL.md is a starter template that you should customize with your specific requirements. For a deep dive into writing effective SOUL.md files, see our complete SOUL.md guide.

The agents add Command: Full Syntax

The command accepts several options to configure your agent during creation:

openclaw agents add <agent-name> [options]

Options:
  --model <provider>    Set the model provider
                        (anthropic, openai, google, ollama)
  --workspace <path>    Target workspace directory
  --template <name>     Use a pre-built template

Examples:
  openclaw agents add seo-analyst
  openclaw agents add researcher --model ollama
  openclaw agents add pm --template coordinator

The agent name should be descriptive and use lowercase with hyphens. Good names: content-writer, seo-analyst, data-reporter. Avoid generic names like agent1. For the full CLI reference, see our OpenClaw CLI cheat sheet.

Setting Up Authentication

After adding an agent, you need to configure which language model it will use. OpenClaw supports multiple providers:

openclaw models auth paste-token --provider anthropic
# Paste your API key when prompted

openclaw models auth paste-token --provider openai
# Paste your API key when prompted

openclaw models auth paste-token --provider google
# Paste your API key when prompted

# No API key needed — just install Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1

For a zero-cost setup with Ollama, read our guide to running OpenClaw with Ollama.

Customizing Your Agent's SOUL.md

The SOUL.md file is where you define everything about your agent. After running openclaw agents add, open the generated file and customize it:

# ContentWriter

## Role
You are a content marketing specialist. You write
blog posts, social media copy, and email campaigns
for a SaaS product.

## Personality
- Tone: Professional but approachable
- Style: Clear, concise, scannable
- Always back claims with data or examples

## Rules
- ALWAYS respond in English
- Target 1,200-1,800 words for blog posts
- Include H2 headers every 200-300 words
- NEVER use clickbait titles
- Include a meta description (max 155 chars)

## Tools — USE THEM
- Use Browser to research topics before writing
- Use Slack to notify when a draft is ready

## Handoffs
- Ask @SEOAnalyst for keyword research
- Hand off finished drafts to @SEOAnalyst

The key to a good agent is being specific. Vague instructions like "be helpful" produce generic results. Specific rules like "Target 1,200-1,800 words" and "Include H2 headers every 200-300 words" produce consistent, high-quality output. For more templates and examples, check our 10 ready-to-use SOUL.md templates.

Adding Multiple Agents

Most teams run 3-10 agents that specialize in different tasks. Here is how to build a content team:

# Add each agent
openclaw agents add pm
openclaw agents add content-writer
openclaw agents add seo-analyst
openclaw agents add researcher
openclaw agents add social-media

# List all agents
openclaw agents list

# Your workspace now looks like:
# agents/
#   pm/SOUL.md
#   content-writer/SOUL.md
#   seo-analyst/SOUL.md
#   researcher/SOUL.md
#   social-media/SOUL.md

Once you have multiple agents, you can enable agent-to-agent communication so they collaborate autonomously. Learn how in our agent-to-agent communication guide and agent teams guide.

Managing Your Agents

After adding agents, here are the commands you will use most:

# List all agents in your workspace
openclaw agents list

# Send a message to a specific agent
openclaw agent --agent seo-analyst --message "Analyze keywords for AI agents"

# Restart the gateway (picks up SOUL.md changes)
openclaw gateway restart

# Check agent status
openclaw gateway status

# Remove an agent
rm -rf agents/<agent-name>

Troubleshooting Common Issues

Skip the Manual Setup: Use CrewClaw

If you want to skip the manual SOUL.md writing, CLI commands, and configuration steps, CrewClaw generates complete agent packages visually. Pick a role, configure integrations, and download a ready-to-deploy package. Your SOUL.md, tools configuration, and workspace setup are all handled automatically.

Frequently Asked Questions