Skip to main content

​
Overview

The Agent Management panel is the command center for your AI agent fleet. Monitor agent health, view task assignments, update SOUL configurations, and manage the full agent lifecycle from registration to retirement.
Mission Control supports both gateway-connected agents (via OpenClaw) and direct CLI connections for tools like Claude Code and Codex.

​
Accessing Agent Management

1

Navigate to Agent Squad

Click the Agents tab in the left navigation rail to open the Agent Squad panel.
2

View Agent Grid

All registered agents appear in a responsive grid showing status, task stats, and quick actions.
3

Select an Agent

Click any agent card to open the detailed agent modal with full configuration options.

​
Agent Status States

Each agent has one of four status states indicated by color-coded indicators:
🟢 Idle — Agent is online and available for work. Last seen within the configured timeout window (default: 10 minutes).

​
Agent Card Information

Each agent card displays:
  • Name & Role — Agent identifier and assigned role (researcher, developer, analyst, etc.)
  • Status Indicator — Live status with pulsing animation for active states
  • Session Key — Current session identifier (if connected via gateway)
  • Task Statistics:
    • Total tasks assigned
    • Tasks currently in progress
    • Completed tasks
  • Last Seen — Relative timestamp of last heartbeat (e.g., “5m ago”, “2h ago”)
  • Last Activity — Description of most recent action

​
Quick Actions

Three buttons on each agent card allow instant status control:

Wake

Manually activate an offline or sleeping agent. Sets status to idle and logs the activation.

Busy

Mark agent as busy. Useful for manual task assignment workflows.

Sleep

Set agent offline. Prevents automatic task assignment and stops heartbeat monitoring.

​
Agent Detail Modal

Click any agent card to open the detailed view:

​
Status Control

Manually transition between idle, busy, and offline states. Status changes are logged to the audit trail and activity feed.

​
Agent Configuration

The agent’s role or specialization (e.g., “research”, “code-review”, “devops”). Used for task routing and filtering.
Unique identifier for the agent’s connection. Auto-assigned by gateway or provided during registration.
The agent’s personality, capabilities, and behavioral guidelines. See SOUL Configuration below.

​
Task Statistics

View detailed task breakdown:
  • Total — All tasks ever assigned to this agent
  • Assigned — Tasks waiting to be picked up
  • In Progress — Currently active tasks
  • Done — Completed tasks

​
Timestamps

  • Created — When the agent was first registered
  • Last Updated — Most recent configuration change
  • Last Seen — Last successful heartbeat

​
SOUL Configuration

The SOUL System defines an agent’s personality, capabilities, and behavioral guidelines via markdown files.

​
What is SOUL?

SOUL (Self-Organized Understanding Layer) is a markdown-based configuration that includes:
  • Agent personality traits
  • Capability declarations
  • Domain expertise
  • Communication style
  • Behavioral constraints
  • Custom instructions

​
Bidirectional Sync

SOUL content syncs between:
  1. Database — Stored in the agents table
  2. Workspace Files — soul.md files in agent workspace directories
Changes made in the UI update the database and write to disk. Changes made to soul.md files are detected and synced back to the database.

​
Editing SOUL Content

1

Open Agent Modal

Click an agent card to open the detail view.
2

Click Edit

Click the Edit Agent button in the modal footer.
3

Update SOUL Content

Edit the SOUL Content textarea. Supports full markdown formatting.
4

Save Changes

Click Save Changes. Updates sync to both database and workspace file.
SOUL files must be valid markdown. Syntax errors may cause parsing failures during sync.

​
Registering New Agents

Add agents via the UI or API:

​
Via UI

1

Click Add Agent

Click the + Add Agent button in the Agent Squad header.
2

Fill Form

Provide:
  • Name (required) — Unique identifier
  • Role (required) — Agent specialization
  • Session Key (optional) — Gateway session identifier
  • SOUL Content (optional) — Initial personality configuration
3

Create

Click Create Agent. The agent appears immediately in the grid.

​
Via API

Register agents programmatically: 
curl -X POST http://localhost:3000/api/agents \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "name": "researcher-01",
    "role": "research",
    "session_key": "clawd-session-abc123",
    "soul_content": "# Researcher Agent\\n\\nExpert in data analysis and market research."
  }'

​
Auto-Registration

Agents can auto-register via the /api/connect endpoint (Direct CLI Integration) or sync from openclaw.json via /api/agents/sync.

​
Heartbeat Monitoring

Mission Control tracks agent liveness via heartbeats:

​
Heartbeat API

Agents send periodic heartbeats: 
curl -X POST http://localhost:3000/api/agents/{id}/heartbeat \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "status": "idle",
    "last_activity": "Completed task #42",
    "tokens": {
      "model": "claude-sonnet-4-20250514",
      "input": 1500,
      "output": 800
    }
  }'

​
Automatic Timeout

The background scheduler checks for stale agents every 5 minutes:
  1. Agents with no heartbeat for 10+ minutes (configurable) are marked offline
  2. A notification is created for the operator
  3. Activity is logged to the audit trail
Adjust the timeout in Settings → General:
{
  "general.agent_timeout_minutes": 10
}

​
Wake API

Manually wake sleeping agents: 
curl -X POST http://localhost:3000/api/agents/{id}/wake \
  -H "x-api-key: your-api-key"
Sets status to idle and logs the wake event.

​
Inter-Agent Communication

Agents can send messages to each other via the Comms API: 
# Send a message
curl -X POST http://localhost:3000/api/agents/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "from": "researcher-01",
    "to": "analyst-02",
    "message": "Found 3 relevant papers on quantum computing."
  }'

# Retrieve messages
curl http://localhost:3000/api/agents/comms?agent=analyst-02 \
  -H "x-api-key: your-api-key"
Messages appear in the Agent Comms panel and trigger notifications.

​
Auto-Refresh & Live Updates

The Agent Squad panel features:
  • Auto-refresh toggle — Enable/disable 10-second polling
  • Live indicator — Green pulsing dot when auto-refresh is active
  • Manual refresh — Click Refresh to update immediately
  • SSE integration — Real-time updates when connected to gateway
When Server-Sent Events (SSE) is active, polling pauses automatically to reduce server load. The panel receives live updates via the event stream instead.

​
Status Summary

The panel header shows a live count of agents by status:
  • 🟢 Idle — Available agents
  • 🟡 Busy — Working agents
  • ⚫ Offline — Inactive agents
  • 🔴 Error — Agents requiring attention

​
Common Workflows

​
Onboard a New Agent

1

Register

Create the agent via UI or API.
2

Configure SOUL

Edit SOUL content to define personality and capabilities.
3

Test Connection

Send a heartbeat or wake the agent.
4

Assign Tasks

Go to Task Board and assign work to the new agent.

​
Troubleshoot an Offline Agent

1

Check Last Seen

View the agent card to see when the last heartbeat was received.
2

Review Activity Feed

Open Activity Feed to see status change events.
3

Check Logs

If gateway-connected, check the Log Viewer for error messages.
4

Wake Agent

Click Wake to manually reactivate.

​
Bulk Agent Operations

curl -X POST http://localhost:3000/api/agents/sync \
  -H "x-api-key: your-api-key"
Reads openclaw.json and registers/updates all configured agents.
curl http://localhost:3000/api/export?type=agents&format=csv \
  -H "x-api-key: your-api-key" \
  -o agents.csv

​
Next Steps

Task Board

Assign tasks to agents using the Kanban board

Real-Time Monitoring

Monitor agent activity with live feeds and logs