How to Create a New Agent in OpenClaw

Building your first AI agent isn't just about writing a prompt. In the OpenClaw ecosystem, creating a new agent is a strategic process of defining identity, granting capabilities, and setting boundaries. Whether you need a research assistant, a coding partner, or a social media manager, this guide will show you exactly how to instantiate and configure a new agent from scratch.

Understanding the OpenClaw Agent Architecture

Before we run any commands, it’s important to understand what makes an OpenClaw agent. Unlike a simple ChatGPT thread, an agent in OpenClaw is a persistent entity with its own configuration, memory access, and toolset. Every agent is defined by its IDENTITY.md and SOUL.md files, which live within the agent's dedicated workspace.

The architecture follows a strict hierarchy: the Gateway manages the sessions, while the Agent Config defines the model, shell, and capabilities. When you create a new agent, you are essentially spinning up a new containerized workspace where that specific AI "resides."

Step 1: Defining the Agent Identity and Soul

The "Soul" of an agent is its core operating system. While the LLM provides the intelligence, the SOUL.md file provides the context, tone, and mission. To create a new agent, you must first draft these two critical documents.

Your IDENTITY.md should include the agent's name, its role (e.g., "Research Specialist"), and its signature emoji. The SOUL.md is more complex; it defines "How I Work." Do you want an agent that is silent until spoken to? Or one that proactively monitors your Slack channels? Defining these behaviors upfront prevents "personality drift" later on.

Step 2: Configuring the Agent Workspace

Once the identity is set, you need to configure the technical parameters. This happens in the AGENTS.md file in your main OpenClaw directory. Here, you will define:

• Model Selection: Choosing between claude-sonnet-4-6 for general tasks or deepseek-r1 for heavy reasoning.
• Capabilities: Which tools the agent can access. Does it need the browser? The 1Password CLI? Or just local file access?
• Privacy Firewall: Critical for security. Use ROUTING_RULES.md to ensure a sub-agent doesn't accidentally leak your personal data into a public-facing task.

By isolating the workspace, you ensure that a "Coding Agent" doesn't have accidental access to your "Personal Finances" folder unless explicitly granted.

Step 3: Equipping Skills via ClawHub

A new agent is only as good as the tools it can use. OpenClaw uses "Skills" to bridge the gap between AI and the real world. You can install pre-built skills using the ClawHub CLI.

For example, if you're building a content agent, you'll want to install the weather, web_search, and image_gen skills. Use the command clawhub install [skill-name] to pull the latest version directly into your agent's capability list. This modular approach allows you to keep your agents lightweight—only giving them the tools they actually need for their specific job.

Step 4: Testing and Safety Verification

Before letting your new agent run on autopilot (cron), you must put it through a verification cycle. We call this the "Preflight Injection." You should manually prompt the agent with a series of tasks to see how it handles tool calls and error states.

Check the memory/violation-log.md after your initial tests. If the agent attempted to access a restricted directory or used a tool in an unsafe way, you must update the checklists/ and ROUTING_RULES.md to prevent it from happening again. A "passed" build is the only way to move an agent from "Development" to "Production" status.

Related Reading

• Setting Up Your First OpenClaw Agent
• The Complete Guide to OpenClaw Skills and Plugins
• What is OpenClaw? An Introduction to Autonomous AI Agents

Frequently Asked Questions

How many agents can I run at once in OpenClaw?

Technically, you are limited only by your hardware (CPU/RAM) and your API rate limits. However, we recommend starting with 2-3 specialized agents rather than one "god agent" to maintain better security and focus.

Can I share memory between two different agents?

Yes, but it must be done explicitly. You can configure a shared memory directory in your openclaw.json, allowing a "Research Agent" to write findings that a "Writing Agent" can later read and process.

What is the best model for a new OpenClaw agent?

For 90% of tasks, Claude 3.5 Sonnet is the gold standard for speed and tool-use accuracy. For complex logic or math, we recommend DeepSeek R1. For simple, repetitive cron jobs, GPT-4o-mini is the most cost-effective choice.

How do I delete an agent I no longer need?

Simply remove the agent's entry from your AGENTS.md file and delete its local workspace folder. OpenClaw is designed to be ephemeral; agents are easy to spin up and just as easy to tear down.

Do I need to be a coder to create a new agent?

While OpenClaw is a developer-first tool, you don't need to be a software engineer. If you can edit a Markdown file and run basic terminal commands, you can successfully configure and deploy a custom agent.