@gitopenclaw/connect

The official GitOpenClaw runtime connector. Streams OpenClaw agent events to the GitOpenClaw dashboard for monitoring, alerting, and kill-switch control.

Requirements

• Node.js 18+
• GitOpenClaw Teams or Business plan
• API key from your account page

Installation

npm install -g @gitopenclaw/connect

Or from this repo:

cd packages/connect
npm install
npm link

Quick start

# Start monitoring (finds OpenClaw log automatically)
gitopenclaw-connect --key YOUR_API_KEY

# Wrap a specific agent session
gitopenclaw-connect --key YOUR_API_KEY --wrap "openclaw run my-agent"

# Check connection status
gitopenclaw-connect status --key YOUR_API_KEY

# Use env var instead of --key flag
GITOPENCLAW_API_KEY=YOUR_API_KEY gitopenclaw-connect

How it works

1. Heartbeat — sends a POST to /api/watch/status every 30 seconds. This updates your connector's "last seen" timestamp in the dashboard.
2. Kill switch polling — checks /api/watch/kill-switch every 10 seconds. If the kill switch is activated from the dashboard, the connector signals the wrapped process.
3. Event streaming — events are batched and flushed to /api/runtime-events every 2 seconds (or when 100 events accumulate).

Programmatic usage

const { GitOpenClawConnector } = require('@gitopenclaw/connect');

const connector = new GitOpenClawConnector({
  apiKey: process.env.GITOPENCLAW_API_KEY,
});

connector.onKillSwitch((active) => {
  if (active) myAgent.pause();
  else myAgent.resume();
});

connector.start();

// Send an event
connector.sendEvent({
  sessionId: 'session-abc',
  agentName: 'my-agent',
  eventType: 'file_read',
  action: 'Read file',
  detail: '/Users/me/Documents/report.pdf',
});

// Report API spend (auto-classified per model)
connector.recordSpend(1200, 340, 'gpt-4o');

Event types

| event_type | Auto severity | |---|---| | file_read | info (critical if credential path) | | file_write | info | | network_request | info (warning if suspicious domain) | | process_exec | warning | | env_read | warning | | credential_access | critical |

Privacy

Only structured event summaries are transmitted — never raw file contents. Credential values, tokens, and secrets are never sent.