What Are Agents?
Agents are the core of your OpenClaw setup. Each agent is a specialised AI assistant that handles messages from specific communication channels. You can have multiple agents — one for customer support, another for your development team, and a casual assistant for general questions.
Multi-Agent Routing
Route messages from different channels, teams, or groups to specialised agents
Custom Personas
Give each agent a unique personality, tone, and behaviour through workspace files
Model Flexibility
Assign different AI models to different agents — use Claude for support, GPT for coding
Tool Policies
Control what each agent can do — from minimal chat to full coding and file access
Step 1: Open the Agents Dashboard
Navigate to the Agents page in SetupClaw APP.
- aOpen SetupClaw APP
- bClick "Agents" in the sidebar navigation
- cThe Agents dashboard shows all your configured agents, their status, and routing bindings
Step 2: Create a New Agent
Use the Agent Builder wizard to create a new agent in 6 steps.
- aClick "Create Agent" on the Agents dashboard
- bStep 1 — Purpose: Describe what this agent should do (e.g., "Handle customer support queries")
- cStep 2 — Template: Choose from 4 built-in templates (Support, Developer, Casual, Professional)
- dStep 3 — Config: Set the agent name, ID, emoji, AI model, and tool profile
- eStep 4 — Channels: Select which channels this agent should respond to
- fStep 5 — Persona: Edit the SOUL.md file to define the agent's personality and behaviour
- gStep 6 — Deploy: Review and deploy your agent
Step 3: Configure Route Bindings
Route bindings determine which messages go to which agent. They use a priority-based matching system.
- aOn the agent card, click "Bindings"
- bAdd a binding by selecting a channel (e.g., Feishu, DingTalk, Discord)
- cOptionally narrow the binding: specific account, group, DM, or team
- dBindings are matched in priority order: exact peer > guild+roles > account > channel > default
The "main" agent is the default fallback — any message that doesn't match a specific binding goes here.
Step 4: Customise the Persona
Each agent has a workspace with 8 markdown files that define its behaviour.
- aOn the agent card, click "Persona"
- bEdit the workspace files using the tabbed editor
| File | Purpose | Required |
|---|---|---|
SOUL.md | Core personality, values, and communication style | Optional |
AGENTS.md | Workspace guidelines, session rules, and red lines | Optional |
IDENTITY.md | Name, emoji, avatar, and visual theme | Optional |
TOOLS.md | Tool usage notes and configuration hints | Optional |
USER.md | User context and preferences | Optional |
HEARTBEAT.md | Periodic task checklist for automated check-ins | Optional |
MEMORY.md | Long-term curated memories (DM sessions only) | Optional |
BOOTSTRAP.md | First-run onboarding (auto-deleted after setup) | Optional |
Step 5: Set Tool Policies
Control what each agent can do by setting a tool profile.
- aOn the agent card, click "Tools"
- bChoose a tool profile: Minimal (chat only), Coding (code execution), Messaging (send messages), or Full (all capabilities)
- cOptionally add specific tools to the allow or deny list
- dEnable sandbox mode for untrusted code execution
- eToggle elevated permissions if the agent needs admin access
Step 6: Monitor Agent Health
The Agents dashboard shows real-time status for all your agents.
- aGreen badge = agent is active and healthy
- bYellow badge = agent is degraded (missing workspace files or offline channels)
- cRed badge = agent is offline (model not reachable or gateway down)
- dCheck the System Health panel for gateway status, channel connectivity, and memory index
- eView the Activity & Usage panel for token counts and daily costs
Built-in Agent Templates
Support Agent
Professional customer-facing assistant with empathetic communication style
Developer Assistant
Technical coding assistant with full tool access and code execution
Casual Assistant
Friendly general-purpose assistant for everyday questions
Professional Assistant
Formal business assistant for executive communication
Advanced Features
Sub-Agents
Configure agents that can call other agents for specialised tasks. Set up a supervisor agent that delegates to support and escalation agents.
Heartbeat Tasks
Schedule periodic automated tasks. Your agent can check emails, scan for updates, or run reports on a schedule.
Memory Search
Enable long-term memory using vector-based search. Your agent remembers conversations and can recall relevant context.
Model Fallbacks
Set a chain of fallback models. If Claude is unavailable, the agent automatically falls back to GPT, then to Gemini.