How to Build Custom Agents in OpenClaw

OpenClaw reported 3.2 million monthly active users as of April 2026, but enterprise production deployments sit at roughly 15% of organizations that have experimented with the platform. One reason for the gap: most teams never move past the default single-agent setup.

A single agent works fine for personal tasks. The trouble starts when you need different behavior for different contexts. A coding assistant that also handles customer support emails will either be mediocre at both or require a prompt so long it burns tokens on irrelevant instructions. Separate agents fix this by letting each one carry its own personality, skill set, and routing rules.

The alternative is prompt-switching within one agent, which gets brittle fast. You end up maintaining conditional logic inside a single SOUL.md file, debugging identity leaks between contexts, and wondering why your "developer bot" just replied to a client inquiry with a code review. Dedicated agents are cleaner.

Before OpenClaw's agent builder, the workaround was running separate OpenClaw instances on different ports or containers. That meant duplicated configuration, no shared routing, and no way to transfer conversations between agents. The built-in agent system solves all three.

OpenClaw's agent creation workflow, documented at docs.openclaw.ai/cli/agents, builds an isolated workspace directory for each agent with its own session transcripts, authentication credentials, and configuration scope.

Start by deciding what this agent will do. Good candidates for a first custom agent are tasks with clear boundaries: a writing assistant, a code reviewer, a data analyst, or a support bot. Each gets its own workspace, which means its own memory and context window.

The creation process has two modes. Interactive mode walks you through naming, workspace path, and initial channel bindings with prompts. Non-interactive mode accepts all parameters as flags, which is what you want for automation and CI pipelines.

After creation, the agent appears in your agent list alongside the default system agent. The default agent is protected and cannot be deleted. Custom agents can be removed through the CLI, though you will need to confirm the deletion explicitly or pass a force flag.

One thing worth knowing early: workspace isolation means each agent maintains separate auth credentials. If your default agent is authenticated with an API key from Anthropic, your new agent starts unauthenticated. You will need to authenticate inside each agent's workspace or seed credentials during non-interactive setup. OAuth refresh tokens are the exception: they require a separate sign-in per agent rather than copying from the default.

Skills are what make agents useful beyond basic chat. OpenClaw's ClawHub registry hosts over 13,700 community-built skills as of early 2026, covering everything from web scraping to code generation to file management.

The skill visibility system works through OpenClaw's project configuration. You define a defaults block that applies to all agents, then override per agent in the agent list. An agent only sees the skills explicitly assigned to it (or inherited from defaults). This prevents your support bot from accidentally triggering a deployment skill, or your writer from running database queries it has no business running.

The configuration lives under the agents key in your project config. A defaults section sets the baseline skills every agent inherits. Each agent entry can override that baseline with its own skills list. If an agent's entry omits the skills field, it inherits the defaults. If it includes one, the override replaces the defaults entirely for that agent.

Skill selection matters more than skill quantity. A focused agent with three relevant skills outperforms one loaded with thirty. Each installed skill adds to the system prompt and competes for context window space. For a writing agent, you might install a grammar checker, a style guide reference, and a publishing tool. For a code reviewer, a linter integration, a git diff viewer, and a test runner.

You can browse available skills on ClawHub or via the clawhub search command. Install skills globally with clawhub install, then control which agents can see them through the configuration file.

Give your OpenClaw agents persistent, searchable storage

generous storage, no credit card, MCP-ready endpoint for reads, writes, and semantic search across every agent workspace.

Start 14-Day Trial

Channel bindings are the routing layer that determines which agent handles incoming messages. Without bindings, every message goes to main. With bindings, you can pin Telegram messages to one agent, Discord traffic to another, and WhatsApp conversations to a third.

The binding syntax uses --bind with a channel name and an optional account identifier. A channel-only binding like --bind telegram matches all Telegram traffic to the default account. An account-scoped binding like --bind telegram:ops targets a specific bot or account within that channel. This distinction matters when you run multiple bots on the same platform.

OpenClaw follows a "most specific wins" rule for routing. If you have both --bind telegram on Agent A and --bind telegram:ops on Agent B, messages from the ops account go to Agent B while everything else on Telegram goes to Agent A. You can also set a wildcard account binding as a channel-wide fallback with lower priority than specific account matches.

Bindings can be upgraded without duplication. If you initially bind an agent to an entire channel and later need account-level routing, adding the more specific binding replaces the broader one cleanly.

To see your current routing setup at a glance, run openclaw agents list --bindings or openclaw agents bindings. Both show which agent handles which channel and account combination.

Supported channels include Telegram, Discord, WhatsApp, Feishu, and local workflow mode. Local workflow mode is worth calling out: it lets agents communicate directly via an agentToAgent tool without requiring a messaging platform, which is useful for internal pipelines where agents hand off work to each other. For teams that want persistent file handoff between agents, pairing channel bindings with a shared workspace like Fastio gives each agent a durable place to read and write artifacts.

Identity configuration controls how your agent presents itself in conversations. Each agent can have a distinct name, theme color, emoji, and avatar. This is more than cosmetic: when users interact with multiple agents through the same gateway, clear identity signals prevent confusion about which agent they are talking to.

The set-identity command supports two approaches. You can pass individual flags for each property or load everything from an IDENTITY.md file in the agent's workspace root. The file-based approach is better for version control since you can commit identity definitions alongside your agent configuration.

The IDENTITY.md approach also scales better across teams. Instead of running CLI commands on every deployment, you include the identity file in your workspace template. New agents provisioned from that template inherit the identity automatically.

For avatar images, you have three options: a workspace-relative file path, a URL, or a data URI. Workspace-relative paths are the most portable since they travel with the workspace directory.

A practical pattern for multi-agent teams: prefix each agent's name with its role. "Dev: Codebot" and "Support: Helpdesk" are immediately distinguishable in a conversation list. Combine this with distinct emoji identifiers, and users can tell at a glance which agent they are addressing.

The built-in workspace isolation in OpenClaw gives each agent its own local directory. That works for session state and scratch files, but it breaks down when agents need to share artifacts or when you need to preserve output across deployments.

Local storage options include a shared filesystem (NFS, EFS) or object storage (S3, R2). Both work but require additional infrastructure and give you no built-in search, permissions, or handoff capabilities.

Fastio takes a different approach. Instead of bare storage, you get an intelligent workspace where uploaded files are automatically indexed for semantic search. Enable Intelligence Mode on a workspace, and any file an agent writes becomes queryable by other agents or by humans through the same interface. No separate vector database, no ETL pipeline.

The free tier gives agents 50 GB of storage, included credits per month, and 5 workspaces with no credit card and no expiration. For a multi-agent OpenClaw setup, that is enough to run a content pipeline, a research workflow, or a client delivery system without touching billing.

Fastio exposes its functionality through 19 MCP tools accessible via Streamable HTTP at /mcp or legacy SSE at /sse. Agents can read, write, search, lock files, manage permissions, and transfer ownership, all through the same API surface. File locks prevent conflicts when two agents target the same resource. Ownership transfer lets a builder agent set up a workspace and hand it to a client, keeping admin access for maintenance.

Where this connects to OpenClaw specifically: when your agents produce artifacts that need to survive past a session, or when multiple agents need to collaborate on shared files, having a workspace with built-in intelligence and access control saves you from stitching together S3, Pinecone, and a custom permissions layer. You can learn more about the MCP integration at mcp.fast.io or read the agent storage guide at fast.io/storage-for-agents/.