Agents
Agents are the core building block of SwarmClaw. Each agent has a personality, provider, and set of capabilities.
Creating an Agent
Navigate to Agents in the sidebar and click New Agent.
Fields
| Field | Description |
|---|---|
| Name | Display name (e.g. "Code Reviewer") |
| Avatar Seed | Optional text seed for generated agent avatar |
| Description | Short summary of what this agent does |
| Soul | Personality text — defines voice, tone, and character |
| Emoji | Signature emoji for the agent's identity |
| Creature | Spirit animal or creature identity (e.g. "lobster", "owl") |
| Vibe | Overall energy or mood (e.g. "calm and methodical", "energetic") |
| Theme | Visual or conceptual theme (e.g. "ocean", "cyberpunk") |
| System Prompt | Technical instructions for the agent |
| OpenClaw Gateway | Per-agent toggle to connect to a local or remote OpenClaw gateway |
| Provider | Which LLM provider to use (hidden for this agent when its OpenClaw toggle is on) |
| Model | Specific model from the provider (hidden for this agent when its OpenClaw toggle is on) |
| Tools | Enable agent tools (see below) |
| Skills | Select discovered skills from ~/.claude/skills/ |
| Fallback Credentials | Backup credentials for automatic failover |
API note: use plugins as the canonical enabled-capabilities field for agents/chats. Legacy tools payloads are still accepted for backward compatibility.
Soul vs System Prompt
The soul defines who the agent is — personality, voice, quirks. It's prepended before the system prompt:
[User Preferences]
[Soul — personality/voice]
[System Prompt — technical instructions]
[Orchestrator context — if applicable]
Example soul:
You are a sharp, witty code reviewer who catches bugs others miss. You explain issues with dry humor and always suggest fixes, never just point out problems.
The system prompt is for technical instructions: what tools to use, output format, constraints.
SwarmClaw also injects a runtime date/time context block into agent prompts (UTC plus resolved local timezone) so agents treat relative time phrases like "today" or "recent" against the current runtime clock.
Default Agent
SwarmClaw ships with a default "Assistant" agent using Claude CLI. It's a general-purpose agent you can customize or replace.
Tools
Agents can be granted access to the following built-in tools:
| Tool | Description |
|---|---|
| shell | Execute shell commands on the host machine |
| files | Read, write, list, and send files |
| edit_file | Create or edit files with targeted replacements |
| process | Monitor/control long-running shell commands |
| web_search | Search the web via DuckDuckGo |
| web_fetch | Fetch and extract content from URLs |
| http_request | Make direct HTTP API requests with custom method/headers/body |
| delegate | Delegate coding work to Claude Code, Codex, OpenCode, or Gemini CLI |
| spawn_subagent | Delegate focused subtasks to another agent |
| browser | MCP browser automation (Playwright) |
| canvas | Present/hide/snapshot live HTML content in a chat-side canvas |
| git | Run structured Git operations (status, diff, commit, push, etc.) |
| memory | Store and retrieve long-term memories with search |
| image_gen | Generate images from text prompts and save upload links |
Send outbound email via SMTP (send, status) | |
| calendar | List/create/update/delete calendar events (Google or Outlook) |
| sandbox | Run JS/TS (Deno) code in an isolated sandbox |
| mcp | Connect to MCP servers for third-party tool integration |
Enable tools in the agent editor. CLI providers (Claude Code, Codex, OpenCode) and OpenClaw agents handle capabilities natively, so local Tools/Platform toggles are hidden for those providers. For LangGraph agents, tools are registered as LangGraph tool nodes.
The delegate plugin can also route work to Gemini CLI when gemini is installed and authenticated on the host.
OpenClaw Gateway
Any agent can connect to an OpenClaw gateway by toggling OpenClaw Gateway ON in the agent editor. When enabled, the provider/model selectors are hidden and replaced with gateway-specific fields:
- Gateway URL — the address of your OpenClaw gateway (e.g.
http://localhost:18789orhttps://my-vps:18789) - Gateway Token — authentication token matching the gateway's
gateway.auth.tokenconfig
Agents can inherit a named gateway profile created in Providers, choose a default profile, or use a direct URL/token override when needed. The openclaw CLI is bundled with SwarmClaw — no separate install needed.
See OpenClaw Gateway Setup for full details.
Gateway Routing Preferences
Agents and model-route targets can now prefer OpenClaw gateways by:
- Gateway tags such as
local,gpu,research,prod - Deployment use case such as
local-dev,single-vps,private-tailnet,browser-heavy, orteam-control
Use these controls when you want the scheduler to bias work toward a class of OpenClaw gateways without hard-pinning the agent to one saved profile.
Examples:
- route browser-heavy research work toward gateways tagged
browserorresearch - keep private workloads on gateways marked
private-tailnet - prefer local gateways for fast dev loops while still allowing remote fallback
Inspector Panel (OpenClaw)
In chat, OpenClaw agents expose an Inspector side panel with:
- Files — Edit
SOUL.md,IDENTITY.md,USER.md,TOOLS.md,HEARTBEAT.md,MEMORY.md,AGENTS.md - Skills — Review skill eligibility, install missing dependencies, enable/disable/remove managed skills, and configure allowlist mode (
all,none,selected) - Automations — Create and run cron jobs tied to the agent
- Advanced — Permission presets, execution approval config, and sandbox environment allowlist controls for OpenClaw gateway Docker sandboxes
The sandbox environment allowlist in this panel applies only to OpenClaw gateway Docker sandboxes. It does not affect SwarmClaw's local sandbox_exec tool.
The chat header also includes Sync History for OpenClaw chats to merge gateway chat history into the local SwarmClaw chat.
Agent Trash & Fleet Filters
Deleting an agent now performs a soft delete (moves to trash). Use the trash view in Agents to:
- Restore an agent
- Permanently delete an agent
Fleet sidebar filters let you quickly view:
- All agents
- Running agents (active chats)
- Agents with pending Approvals
Platform Tools
Agents can also manage SwarmClaw resources directly. Enable these in the Platform section of the agent editor or via the tools popover in chat:
| Tool | Description |
|---|---|
| Orchestrator | Delegate tasks to other agents via delegate_to_agent |
| Agents | Create, edit, and delete agents |
| Tasks | Create, edit, and delete tasks |
| Schedules | Create, edit, and delete schedules |
| Reminders | Set conversational wake timers (schedule_wake) |
| Skills | Create, edit, and delete skills |
| Connectors | Create, edit, and delete connectors |
| Chats | Enable sessions_tool for list/history/status/send/spawn/stop |
| Secrets | Store and retrieve encrypted reusable secrets |
Orchestrator Capability
Enable the Orchestrator toggle to let an agent delegate work to other agents. The agent gets access to delegate_to_agent which creates tasks assigned to target agents. Agents without this capability will be prompted to request access via the tool request UI.
See Tools — Orchestrator Capability for details.
Assign to Other Agents
When Tasks or Schedules platform tools are enabled, an Assign to Other Agents toggle appears. By default, agents can only assign tasks and schedules to themselves. Turn this on to let an agent assign work to any other agent in the system.
The default Assistant agent has this enabled. New agents default to self-assignment only.
See Tools — Platform Tools for details.
Fallback Credentials
Agents can have fallback credentials for automatic failover. If the primary credential fails (401, 429, or 500 errors), SwarmClaw retries with the next credential in the fallback chain. Configure these in the agent editor under Fallback Credentials.
See Providers — Model Failover and Failover for details.
Skills
Skills are markdown instruction files discovered from ~/.claude/skills/. Each skill's content is appended to the system prompt when assigned to an agent. Use the Refresh button to re-scan for new skills.
Heartbeat Autonomy
Agents running with heartbeat enabled can self-update their goals during execution. On each heartbeat tick, the agent receives its current goal, status, and recent context. It can respond with structured metadata to update:
- Goal — what the agent is working toward
- Status —
idle,progress,blocked, orok - Next action — what the agent plans to do next
This enables long-running agents to evolve their objectives without manual intervention. The agent's workspace HEARTBEAT.md file (if present) is included as additional context for heartbeat prompts.
Personality Evolution
When an agent has the manage_agents platform tool enabled and a long conversation reaches the reflection threshold (~20 messages), the agent is nudged to consider whether its personality has evolved during the interaction. If so, it can self-update its soul field using the manage_agents tool.
This enables agents to organically develop their voice and relationship dynamics over time — learning tone preferences, adjusting boundaries, and refining their communication style based on real interactions.
Identity Context
Agents can have identity fields (emoji, creature, vibe, theme) that are injected into heartbeat and mission prompts. If an IDENTITY.md file exists in the agent's workspace, its key-value pairs are merged with the agent's configured identity fields.
This gives long-running agents a consistent sense of self across heartbeat ticks and mission followups.
Orchestrator Agents
Mark an agent as an Orchestrator to enable multi-agent routing. See Orchestration.
Note: Orchestrators cannot use CLI providers (Claude Code, Codex, OpenCode) — they require LangGraph-compatible providers (Anthropic, OpenAI, Gemini, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Ollama, or custom).