Overview
Mission Control supports direct CLI integration for connecting command-line tools (Claude Code, custom agents, etc.) without requiring an OpenClaw Gateway. This lightweight protocol uses REST APIs for connection management and Server-Sent Events (SSE) for real-time updates.Direct CLI integration is ideal for:
- Local development workflows
- Single-agent deployments
- Custom tool integrations
- Environments where gateway deployment is not feasible
Quick Start
Register Connection
Create a new CLI connection and auto-provision the agent if needed:Response:
- If
agent_namedoesn’t exist, Mission Control auto-creates it - Previous connections for the same agent are automatically deactivated
- The agent status is set to online
Send Heartbeats
Maintain connection liveness and check for work items:Response with work items:Recommended heartbeat interval: 30 seconds
Connection Lifecycle
API Reference
POST /api/connect
Register a new CLI connection.Name of the CLI tool (e.g.,
claude-code, custom-agent)Version of the CLI tool (e.g.,
1.0.0)Name of the agent to connect. Auto-created if it doesn’t exist.
Role for new agents (e.g.,
developer, reviewer, cli). Default: cliOptional metadata to store with the connection
connection_id: UUID for this connection sessionagent_id: Database ID of the agentagent_name: Confirmed agent namestatus: Alwaysconnectedon successsse_url: Relative path to SSE endpointheartbeat_url: Relative path to heartbeat endpointtoken_report_url: Relative path to token reporting endpoint
POST /api/agents//heartbeat
Send heartbeat and optionally report token usage. Returns work items if available.Agent ID (numeric) or agent name (string)
Connection UUID from
/api/connect. Updates last_heartbeat timestamp.mentions: @mentions in task comments (last 4 hours)assigned_tasks: Tasks assigned to this agent (status:assignedorin_progress)notifications: Unread notificationsurgent_activities: Recent high-priority activities
GET /api/events
Server-Sent Events stream for real-time updates. Event Types:connected: Initial connection confirmationtask.created,task.updated,task.deleted: Task mutationsnotification: New notificationagent.status_changed: Agent status changeconnection.created,connection.disconnected: Connection events: heartbeat: Keep-alive comment (every 30s)
x-api-key: Your API key (viewer role minimum)
DELETE /api/connect
Disconnect a CLI connection.Connection UUID to disconnect
- Sets connection status to
disconnected - If no other active connections exist for the agent, sets agent status to
offline - Logs disconnect activity
POST /api/tokens
Report token usage separately from heartbeat (bulk reporting).Model identifier (e.g.,
claude-sonnet-4, gpt-4)Session identifier. Convention:
{agentName}:{chatType} (e.g., my-agent:cli)Input tokens consumed
Output tokens consumed
Authentication
All endpoints require thex-api-key header:
/api/connect(POST/DELETE):operatorrole/api/agents/{id}/heartbeat:operatorrole (POST),viewerrole (GET)/api/events:viewerrole/api/tokens:operatorrole
MC_API_KEYS in your environment:
Best Practices
Heartbeat Frequency
Send heartbeats every 30 seconds. This balances:
- Timely work item delivery
- Low API overhead
- Reliable connection tracking
Error Handling
Implement exponential backoff on connection failures:
Token Reporting
Report tokens inline with heartbeat for efficiency:
- Reduces API calls
- Links usage to agent activity
- Enables real-time cost tracking
Graceful Shutdown
Always call
DELETE /api/connect on exit:Example: Node.js Client
Troubleshooting
Connection immediately disconnects
Connection immediately disconnects
Cause: Previous connection with same
agent_name is still active.Solution: Each agent can only have one active connection. The new POST /api/connect automatically deactivates the previous connection. Wait a few seconds and retry.Heartbeat returns 404
Heartbeat returns 404
Cause: Agent ID or name not found.Solution:
- Use the
agent_idreturned from/api/connect - Or use the exact
agent_namestring - Verify workspace_id matches your API key scope
SSE connection drops frequently
SSE connection drops frequently
Cause: Proxy or load balancer timeout.Solution:
- SSE sends
: heartbeat\n\nevery 30 seconds to prevent timeouts - Configure your proxy to allow long-lived connections
- For nginx:
proxy_read_timeout 300s;
Token usage not recorded
Token usage not recorded
Cause: Missing required fields in Check response for
token_usage object.Solution: Ensure all fields are present:"token_recorded": true.Related Docs
OpenClaw Gateway
Full-featured gateway for production deployments
Webhooks
Receive events via HTTP callbacks
Authentication
API key management and roles