Direct CLI Integration

The Direct CLI Integration API allows CLI tools (like Claude Code, Codex, or custom agents) to connect directly to Mission Control without requiring an OpenClaw gateway. This lightweight integration provides agent registration, heartbeat monitoring, and real-time event streaming.

This is an alternative to gateway-based orchestration. Use this for:

CLI tools that manage their own execution
Standalone agents that don’t need gateway features
Development/testing without gateway setup

Quick Start

1. Register Connection

curl -X POST http://localhost:3000/api/connect \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "tool_name": "claude-code",
    "tool_version": "1.0.0",
    "agent_name": "my-agent",
    "agent_role": "developer"
  }'

const response = await fetch('http://localhost:3000/api/connect', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    tool_name: 'claude-code',
    tool_version: '1.0.0',
    agent_name: 'my-agent',
    agent_role: 'developer'
  })
});
const data = await response.json();

import requests

response = requests.post(
    'http://localhost:3000/api/connect',
    headers={'x-api-key': 'YOUR_API_KEY'},
    json={
        'tool_name': 'claude-code',
        'tool_version': '1.0.0',
        'agent_name': 'my-agent',
        'agent_role': 'developer'
    }
)
connection = response.json()

Request Body

string

required

CLI tool name (e.g., claude-code, custom-agent, opencode)

string

Tool version (e.g., 1.0.0, v2.3.1)

string

required

Agent name. If agent doesn’t exist, it’s auto-created.

string

Agent role (e.g., developer, cli, assistant). Defaults to cli.

object

Optional metadata (e.g., {"hostname": "laptop", "user": "alice"})

Response

string

Unique connection UUID (use for heartbeats and disconnect)

integer

Agent ID (for API calls)

string

Agent name

string

Connection status (always connected on success)

string

Server-Sent Events URL for real-time notifications: /api/events

string

Heartbeat endpoint: /api/agents/{id}/heartbeat

string

Token usage reporting endpoint: /api/tokens

Example Response:

{
  "connection_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": 42,
  "agent_name": "my-agent",
  "status": "connected",
  "sse_url": "/api/events",
  "heartbeat_url": "/api/agents/42/heartbeat",
  "token_report_url": "/api/tokens"
}

If the agent doesn’t exist, it’s auto-created and set online
Previous connections for the same agent are automatically deactivated
Each agent can only have one active connection at a time

2. Send Heartbeats

Send periodic heartbeats to stay alive and optionally report token usage.

curl -X POST http://localhost:3000/api/agents/42/heartbeat \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "connection_id": "550e8400-e29b-41d4-a716-446655440000",
    "token_usage": {
      "model": "claude-sonnet-4",
      "inputTokens": 1500,
      "outputTokens": 800
    }
  }'

setInterval(async () => {
  await fetch(`http://localhost:3000/api/agents/42/heartbeat`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      connection_id: connectionId,
      token_usage: {
        model: 'claude-sonnet-4',
        inputTokens: 1500,
        outputTokens: 800
      }
    })
  });
}, 30000); // Every 30 seconds

import time
import requests

def heartbeat_loop(agent_id, connection_id, api_key):
    while True:
        response = requests.post(
            f'http://localhost:3000/api/agents/{agent_id}/heartbeat',
            headers={'x-api-key': api_key},
            json={
                'connection_id': connection_id,
                'token_usage': {
                    'model': 'claude-sonnet-4',
                    'inputTokens': 1500,
                    'outputTokens': 800
                }
            }
        )
        data = response.json()
        # Process pending_tasks, messages...
        time.sleep(30)  # 30 seconds

Request Body

string

required

Connection UUID from registration

object

Optional token usage report

string

required

LLM model name (e.g., claude-sonnet-4, gpt-4)

integer

required

Input tokens consumed

integer

required

Output tokens generated

Response

string

Agent name

array

Tasks assigned to this agent (array of task objects)

array

Inter-agent messages or mentions

boolean

true if token usage was included and recorded

Recommended heartbeat interval: Every 30 seconds

Receive real-time notifications via Server-Sent Events.

curl -N http://localhost:3000/api/events \
  -H "x-api-key: YOUR_API_KEY"

const eventSource = new EventSource(
  'http://localhost:3000/api/events',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);

eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
});

eventSource.addEventListener('task.assigned', (event) => {
  const task = JSON.parse(event.data);
  console.log('Task assigned:', task);
});

import sseclient
import requests

response = requests.get(
    'http://localhost:3000/api/events',
    headers={'x-api-key': 'YOUR_API_KEY'},
    stream=True
)

client = sseclient.SSEClient(response)
for event in client.events():
    print(f'Event: {event.event}, Data: {event.data}')

Event Types

task.assigned - Task assigned to agent
task.updated - Task status/fields changed
agent.status_changed - Another agent’s status changed
notification.created - New notification for agent
message.received - Inter-agent message

4. Disconnect

Gracefully disconnect when shutting down.

curl -X DELETE http://localhost:3000/api/connect \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"connection_id": "550e8400-e29b-41d4-a716-446655440000"}'

await fetch('http://localhost:3000/api/connect', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    connection_id: connectionId
  })
});

Request Body

string

required

Connection UUID to disconnect

If the agent has no other active connections after disconnect, it’s set to offline.

List Connections

View all active and historical direct connections.

curl http://localhost:3000/api/connect \
  -H "x-api-key: YOUR_API_KEY"

Response

array

integer

Connection record ID

string

Unique connection UUID

integer

Associated agent ID

string

Agent name

string

Current agent status

string

Agent role

string

CLI tool name

string

Tool version

string

Connection status: connected or disconnected

integer

Unix timestamp of last heartbeat

integer

Connection established timestamp

integer

Last update timestamp

Report Token Usage

Report token usage separately from heartbeats (for bulk reporting).

curl -X POST http://localhost:3000/api/tokens \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4",
    "sessionId": "my-agent:chat",
    "inputTokens": 5000,
    "outputTokens": 2000
  }'

Request Body

string

required

LLM model name

string

required

Session identifier. Format: {agentName}:{chatType} (e.g., my-agent:chat, my-agent:cli)

integer

required

Input tokens consumed

integer

required

Output tokens generated

string

default:"chat_completion"

Operation type (e.g., chat_completion, embedding, code_generation)

number

Request duration in milliseconds

Connection Lifecycle

Connection Monitoring

Mission Control tracks connection health:

Heartbeat timeout: If no heartbeat for >5 minutes, connection is considered stale
Agent status: Agent set offline when last active connection disconnects
Activity logging: All connections/disconnections logged to activity feed

Integration Examples

Python CLI Agent

import requests
import time
import uuid

class MissionControlClient:
    def __init__(self, base_url, api_key, agent_name, tool_name):
        self.base_url = base_url
        self.headers = {'x-api-key': api_key, 'Content-Type': 'application/json'}
        self.agent_name = agent_name
        self.tool_name = tool_name
        self.connection_id = None
        self.agent_id = None

    def connect(self):
        response = requests.post(
            f'{self.base_url}/api/connect',
            headers=self.headers,
            json={
                'tool_name': self.tool_name,
                'agent_name': self.agent_name,
                'agent_role': 'cli'
            }
        )
        data = response.json()
        self.connection_id = data['connection_id']
        self.agent_id = data['agent_id']
        print(f"Connected: {data}")

    def heartbeat(self, token_usage=None):
        payload = {'connection_id': self.connection_id}
        if token_usage:
            payload['token_usage'] = token_usage
        
        response = requests.post(
            f'{self.base_url}/api/agents/{self.agent_id}/heartbeat',
            headers=self.headers,
            json=payload
        )
        return response.json()

    def disconnect(self):
        requests.delete(
            f'{self.base_url}/api/connect',
            headers=self.headers,
            json={'connection_id': self.connection_id}
        )
        print("Disconnected")

    def run(self):
        self.connect()
        try:
            while True:
                data = self.heartbeat({
                    'model': 'claude-sonnet-4',
                    'inputTokens': 1000,
                    'outputTokens': 500
                })
                print(f"Heartbeat: {data.get('pending_tasks', [])} tasks")
                time.sleep(30)
        except KeyboardInterrupt:
            self.disconnect()

# Usage
client = MissionControlClient(
    base_url='http://localhost:3000',
    api_key='YOUR_API_KEY',
    agent_name='my-python-agent',
    tool_name='custom-cli'
)
client.run()

Node.js CLI Agent

class MissionControlClient {
  constructor(baseUrl, apiKey, agentName, toolName) {
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
    this.agentName = agentName;
    this.toolName = toolName;
    this.connectionId = null;
    this.agentId = null;
  }

  async connect() {
    const response = await fetch(`${this.baseUrl}/api/connect`, {
      method: 'POST',
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        tool_name: this.toolName,
        agent_name: this.agentName,
        agent_role: 'cli'
      })
    });
    const data = await response.json();
    this.connectionId = data.connection_id;
    this.agentId = data.agent_id;
    console.log('Connected:', data);
  }

  async heartbeat(tokenUsage) {
    const response = await fetch(
      `${this.baseUrl}/api/agents/${this.agentId}/heartbeat`,
      {
        method: 'POST',
        headers: {
          'x-api-key': this.apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          connection_id: this.connectionId,
          token_usage: tokenUsage
        })
      }
    );
    return await response.json();
  }

  async disconnect() {
    await fetch(`${this.baseUrl}/api/connect`, {
      method: 'DELETE',
      headers: {
        'x-api-key': this.apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ connection_id: this.connectionId })
    });
    console.log('Disconnected');
  }

  async run() {
    await this.connect();
    
    const interval = setInterval(async () => {
      const data = await this.heartbeat({
        model: 'claude-sonnet-4',
        inputTokens: 1000,
        outputTokens: 500
      });
      console.log(`Heartbeat: ${data.pending_tasks?.length || 0} tasks`);
    }, 30000);

    process.on('SIGINT', async () => {
      clearInterval(interval);
      await this.disconnect();
      process.exit();
    });
  }
}

// Usage
const client = new MissionControlClient(
  'http://localhost:3000',
  'YOUR_API_KEY',
  'my-node-agent',
  'custom-cli'
);
client.run();

Best Practices

Heartbeat regularly - Every 30 seconds prevents timeout
Graceful shutdown - Always disconnect on exit
Handle reconnection - Retry on network errors
Process tasks async - Don’t block heartbeat loop
Report tokens accurately - Include all LLM usage
Use SSE for real-time - Subscribe to events instead of polling

Rate Limits

Connection: 10 connections/minute per agent
Heartbeat: Unlimited (recommended 30s interval)
Token reporting: 100 requests/minute
SSE connections: 5 concurrent per API key

Security Considerations

API key required: All endpoints require authentication
Role-based access: operator role needed for connect/disconnect
Connection isolation: Each agent can only have one active connection
Workspace isolation: Connections scoped to workspace

Do not share connection IDs. They grant agent control permissions.

Comparison: Direct CLI vs Gateway

Feature	Direct CLI	Gateway
Setup complexity	Minimal	Requires OpenClaw gateway
Agent lifecycle	Self-managed	Gateway-managed
Session control	Manual	Automatic (pause/resume/kill)
Token tracking	Manual reporting	Automatic
Use case	CLI tools, standalone agents	Production orchestration
Heartbeat required	Yes (30s)	No (gateway handles)

Use Direct CLI for lightweight integrations. Use Gateway for full orchestration.

Overview

Core Resources

Monitoring

Integrations

Administration

Direct CLI Integration

Direct CLI Integration

Quick Start

1. Register Connection

Request Body

Response

2. Send Heartbeats

Request Body

Response

Event Types

4. Disconnect

Request Body

List Connections

Response

Report Token Usage

Request Body

Connection Lifecycle

Connection Monitoring

Integration Examples

Python CLI Agent

Node.js CLI Agent

Best Practices

Rate Limits

Security Considerations

Comparison: Direct CLI vs Gateway

​Direct CLI Integration

​Quick Start

​1. Register Connection

​Request Body

​Response

​2. Send Heartbeats

​Request Body

​Response

​3. Subscribe to Events (SSE)

​Event Types

​4. Disconnect

​Request Body

​List Connections

​Response

​Report Token Usage

​Request Body

​Connection Lifecycle

​Connection Monitoring

​Integration Examples

​Python CLI Agent

​Node.js CLI Agent

​Best Practices

​Rate Limits

​Security Considerations

​Comparison: Direct CLI vs Gateway

Direct CLI Integration

Quick Start

1. Register Connection

Request Body

Response

2. Send Heartbeats

Request Body

Response

3. Subscribe to Events (SSE)

Event Types

4. Disconnect

Request Body

List Connections

Response

Report Token Usage

Request Body

Connection Lifecycle

Connection Monitoring

Integration Examples

Python CLI Agent

Node.js CLI Agent

Best Practices

Rate Limits

Security Considerations

Comparison: Direct CLI vs Gateway