loki-mode 5.42.2 → 5.46.0

package/docs/openclaw-integration.md

@@ -0,0 +1,572 @@
+# OpenClaw Integration
+
+Multi-agent coordination protocol integration for Loki Mode (v5.38.0).
+
+## Overview
+
+OpenClaw is a standardized protocol for multi-agent coordination across different AI systems. Loki Mode's OpenClaw bridge enables:
+
+- **Cross-system orchestration** - Coordinate Loki Mode agents with other agent frameworks
+- **Standardized communication** - Common message format for agent-to-agent communication
+- **Shared task queues** - Distribute work across multiple orchestrators
+- **State synchronization** - Keep agent state consistent across systems
+
+Compatible with:
+- AutoGPT
+- MetaGPT
+- CrewAI
+- LangGraph agents
+- Custom agent frameworks implementing the OpenClaw protocol
+
+## Quick Start
+
+```bash
+# Enable OpenClaw bridge
+export LOKI_OPENCLAW_ENABLED=true
+export LOKI_OPENCLAW_ENDPOINT=http://openclaw-server:8080
+
+# Start with OpenClaw integration
+loki start --openclaw ./prd.md
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOKI_OPENCLAW_ENABLED` | `false` | Enable OpenClaw bridge |
+| `LOKI_OPENCLAW_ENDPOINT` | - | OpenClaw server endpoint URL (required) |
+| `LOKI_OPENCLAW_AGENT_ID` | `loki-{pid}` | Unique agent ID for this Loki instance |
+| `LOKI_OPENCLAW_NAMESPACE` | `default` | Namespace for multi-tenant deployments |
+| `LOKI_OPENCLAW_HEARTBEAT` | `30` | Heartbeat interval in seconds |
+| `LOKI_OPENCLAW_TIMEOUT` | `120` | Message timeout in seconds |
+
+### Configuration File
+
+```yaml
+# .loki/config.yaml
+openclaw:
+  enabled: true
+  endpoint: http://openclaw-server:8080
+  agent_id: loki-primary
+  namespace: production
+  heartbeat_interval: 30
+  message_timeout: 120
+  features:
+    task_sharing: true
+    state_sync: true
+    capabilities_discovery: true
+```
+
+## OpenClaw Protocol
+
+### Message Format
+
+OpenClaw uses JSON messages over HTTP/WebSocket:
+
+```json
+{
+  "protocol_version": "1.0",
+  "message_type": "task_offer",
+  "agent_id": "loki-12345",
+  "namespace": "default",
+  "timestamp": "2026-02-15T14:30:00Z",
+  "payload": {
+    "task_id": "task-abc123",
+    "task_type": "code_review",
+    "priority": "high",
+    "deadline": "2026-02-15T16:00:00Z",
+    "requirements": {
+      "model": "opus",
+      "skills": ["code_review", "security_audit"]
+    }
+  }
+}
+```
+
+### Message Types
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `register` | Loki → OpenClaw | Agent registration with capabilities |
+| `heartbeat` | Loki → OpenClaw | Keep-alive signal |
+| `task_offer` | OpenClaw → Loki | Task offered for execution |
+| `task_accept` | Loki → OpenClaw | Accept task offer |
+| `task_reject` | Loki → OpenClaw | Reject task offer |
+| `task_update` | Loki → OpenClaw | Progress update |
+| `task_complete` | Loki → OpenClaw | Task completion |
+| `state_sync` | Bidirectional | State synchronization |
+| `capability_query` | OpenClaw → Loki | Query agent capabilities |
+
+## Agent Registration
+
+When OpenClaw bridge starts, Loki Mode registers with the OpenClaw server:
+
+```json
+{
+  "message_type": "register",
+  "agent_id": "loki-12345",
+  "payload": {
+    "name": "Loki Mode",
+    "version": "5.42.2",
+    "provider": "claude",
+    "capabilities": [
+      "full_stack_development",
+      "code_review",
+      "testing",
+      "deployment",
+      "business_operations"
+    ],
+    "agent_types": [
+      "eng-frontend", "eng-backend", "eng-qa",
+      "ops-devops", "ops-sre", "biz-marketing"
+    ],
+    "max_concurrent_tasks": 10,
+    "supported_models": ["opus", "sonnet", "haiku"]
+  }
+}
+```
+
+## Task Coordination
+
+### Receiving Tasks
+
+Loki Mode receives tasks from OpenClaw:
+
+```json
+{
+  "message_type": "task_offer",
+  "payload": {
+    "task_id": "external-task-123",
+    "task_type": "code_review",
+    "description": "Review authentication module",
+    "files": ["src/auth.py", "tests/test_auth.py"],
+    "priority": "high",
+    "deadline": "2026-02-15T16:00:00Z"
+  }
+}
+```
+
+Loki Mode evaluates and responds:
+
+```json
+{
+  "message_type": "task_accept",
+  "payload": {
+    "task_id": "external-task-123",
+    "assigned_agent": "review-code",
+    "estimated_duration": 600
+  }
+}
+```
+
+### Offering Tasks
+
+Loki Mode can offer tasks to other agents via OpenClaw:
+
+```json
+{
+  "message_type": "task_offer",
+  "payload": {
+    "task_id": "loki-task-456",
+    "task_type": "data_analysis",
+    "description": "Analyze user behavior logs",
+    "requirements": {
+      "skills": ["data_science", "ml"],
+      "estimated_cost": 0.50
+    }
+  }
+}
+```
+
+## State Synchronization
+
+### Shared State
+
+Loki Mode synchronizes key state with OpenClaw:
+
+- Active agents and their status
+- Task queue (pending, in-progress, completed)
+- Session metadata (iteration, cost, uptime)
+- Resource utilization (memory, CPU, tokens)
+
+```json
+{
+  "message_type": "state_sync",
+  "payload": {
+    "session_status": "running",
+    "iteration": 42,
+    "agents_active": 12,
+    "tasks_pending": 5,
+    "tasks_in_progress": 8,
+    "tasks_completed": 127,
+    "cost_usd": 2.34
+  }
+}
+```
+
+### Conflict Resolution
+
+When state conflicts occur:
+
+1. **Last-write-wins** - Default strategy
+2. **Merge** - For additive operations (task queue append)
+3. **Reject** - For conflicting updates (agent status)
+
+## Capability Discovery
+
+Other agents can query Loki Mode's capabilities:
+
+```json
+{
+  "message_type": "capability_query",
+  "payload": {
+    "query_type": "supports_task_type",
+    "task_type": "frontend_development"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "message_type": "capability_response",
+  "payload": {
+    "supported": true,
+    "agent_types": ["eng-frontend"],
+    "confidence": 0.95,
+    "estimated_cost": 0.10
+  }
+}
+```
+
+## API Endpoints
+
+Loki Mode exposes OpenClaw endpoints on the dashboard server:
+
+```bash
+# Get OpenClaw status
+GET http://localhost:57374/api/openclaw/status
+
+# Send message to OpenClaw server
+POST http://localhost:57374/api/openclaw/send
+{
+  "message_type": "task_offer",
+  "payload": {...}
+}
+
+# Query capabilities
+GET http://localhost:57374/api/openclaw/capabilities
+
+# Get received messages
+GET http://localhost:57374/api/openclaw/messages?limit=50
+```
+
+## CLI Commands
+
+```bash
+# Check OpenClaw connection status
+loki openclaw status
+
+# Send test message
+loki openclaw test
+
+# List received messages
+loki openclaw messages
+
+# Query registered agents
+loki openclaw agents
+
+# Disconnect from OpenClaw
+loki openclaw disconnect
+```
+
+## Examples
+
+### Multi-System Workflow
+
+```
+MetaGPT (Planning)
+    ↓
+    Sends task via OpenClaw
+    ↓
+Loki Mode (Implementation)
+    ↓
+    Sends result via OpenClaw
+    ↓
+AutoGPT (Testing)
+    ↓
+    Sends report via OpenClaw
+    ↓
+CrewAI (Deployment)
+```
+
+### Task Distribution
+
+```yaml
+# Distribute tasks across multiple Loki instances
+openclaw:
+  enabled: true
+  endpoint: http://openclaw-lb:8080
+  features:
+    task_sharing: true
+
+# Loki instance 1 (frontend)
+agents:
+  - eng-frontend
+  - eng-mobile
+
+# Loki instance 2 (backend)
+agents:
+  - eng-backend
+  - eng-database
+
+# Loki instance 3 (ops)
+agents:
+  - ops-devops
+  - ops-sre
+```
+
+### Cross-Framework Integration
+
+```python
+# AutoGPT sending task to Loki via OpenClaw
+import requests
+
+openclaw_url = "http://openclaw-server:8080/tasks"
+task = {
+    "task_type": "code_review",
+    "description": "Review API implementation",
+    "files": ["api/routes.py"],
+    "target_agent": "loki-12345"
+}
+
+response = requests.post(openclaw_url, json=task)
+print(f"Task sent: {response.json()}")
+
+# Wait for completion
+task_id = response.json()["task_id"]
+while True:
+    status = requests.get(f"{openclaw_url}/{task_id}").json()
+    if status["status"] == "completed":
+        print(f"Result: {status['result']}")
+        break
+    time.sleep(10)
+```
+
+## OpenClaw Server Setup
+
+### Docker Deployment
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  openclaw-server:
+    image: openclaw/server:latest
+    ports:
+      - "8080:8080"
+    environment:
+      - OPENCLAW_LOG_LEVEL=info
+      - OPENCLAW_AUTH_ENABLED=false
+    volumes:
+      - openclaw-data:/data
+
+  loki-mode-1:
+    image: asklokesh/loki-mode:latest
+    environment:
+      - LOKI_OPENCLAW_ENABLED=true
+      - LOKI_OPENCLAW_ENDPOINT=http://openclaw-server:8080
+      - LOKI_OPENCLAW_AGENT_ID=loki-frontend
+    depends_on:
+      - openclaw-server
+
+  loki-mode-2:
+    image: asklokesh/loki-mode:latest
+    environment:
+      - LOKI_OPENCLAW_ENABLED=true
+      - LOKI_OPENCLAW_ENDPOINT=http://openclaw-server:8080
+      - LOKI_OPENCLAW_AGENT_ID=loki-backend
+    depends_on:
+      - openclaw-server
+
+volumes:
+  openclaw-data:
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: openclaw-server
+spec:
+  selector:
+    app: openclaw
+  ports:
+    - port: 8080
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: openclaw-server
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: openclaw
+  template:
+    metadata:
+      labels:
+        app: openclaw
+    spec:
+      containers:
+      - name: openclaw
+        image: openclaw/server:latest
+        ports:
+        - containerPort: 8080
+        env:
+        - name: OPENCLAW_REDIS_URL
+          value: redis://redis:6379
+```
+
+## Security
+
+### Authentication
+
+```bash
+# Enable OpenClaw authentication
+export LOKI_OPENCLAW_AUTH_TOKEN=your-secret-token
+
+# Or use mutual TLS
+export LOKI_OPENCLAW_TLS_CERT=/path/to/client-cert.pem
+export LOKI_OPENCLAW_TLS_KEY=/path/to/client-key.pem
+export LOKI_OPENCLAW_TLS_CA=/path/to/ca-cert.pem
+```
+
+### Authorization
+
+```yaml
+openclaw:
+  authorization:
+    enabled: true
+    allowed_agents:
+      - autogpt-production
+      - metagpt-staging
+    allowed_namespaces:
+      - production
+      - staging
+```
+
+### Encryption
+
+```bash
+# Use HTTPS for OpenClaw endpoint
+export LOKI_OPENCLAW_ENDPOINT=https://openclaw-server:8443
+
+# Enable message encryption
+export LOKI_OPENCLAW_ENCRYPT_MESSAGES=true
+export LOKI_OPENCLAW_ENCRYPTION_KEY=your-encryption-key
+```
+
+## Monitoring
+
+### Metrics
+
+OpenClaw bridge exposes metrics:
+
+```
+loki_openclaw_connected{agent_id="loki-12345"} 1
+loki_openclaw_messages_sent_total{type="task_offer"} 42
+loki_openclaw_messages_received_total{type="task_accept"} 38
+loki_openclaw_tasks_completed_total 35
+loki_openclaw_latency_seconds{operation="send"} 0.015
+```
+
+### Health Checks
+
+```bash
+# Check OpenClaw connection
+curl http://localhost:57374/api/openclaw/health
+
+# Response
+{
+  "connected": true,
+  "server": "http://openclaw-server:8080",
+  "last_heartbeat": "2026-02-15T14:30:00Z",
+  "latency_ms": 15,
+  "messages_pending": 0
+}
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+```bash
+# Test OpenClaw server connectivity
+curl http://openclaw-server:8080/health
+
+# Check Loki OpenClaw status
+loki openclaw status
+
+# View connection logs
+loki enterprise audit tail --event openclaw.connect
+
+# Reconnect manually
+loki openclaw reconnect
+```
+
+### Message Delivery Failures
+
+```bash
+# Check message queue
+loki openclaw messages --status failed
+
+# Retry failed messages
+loki openclaw retry
+
+# View OpenClaw logs
+docker logs openclaw-server
+```
+
+### Performance Issues
+
+```bash
+# Check message latency
+curl http://localhost:57374/metrics | grep loki_openclaw_latency
+
+# Monitor message queue size
+loki openclaw status | grep messages_pending
+
+# Increase heartbeat interval to reduce traffic
+export LOKI_OPENCLAW_HEARTBEAT=60
+```
+
+## Best Practices
+
+1. **Use namespaces** to isolate environments (dev, staging, production)
+2. **Enable authentication** in production deployments
+3. **Monitor message latency** and set appropriate timeouts
+4. **Implement retry logic** for transient failures
+5. **Use task priorities** for critical workloads
+6. **Set up health checks** for automatic reconnection
+7. **Log all OpenClaw messages** for audit trail
+
+## Limitations
+
+- OpenClaw protocol is still evolving (v1.0 spec)
+- Not all agent frameworks support OpenClaw yet
+- Message size limited to 1MB
+- Synchronous task completion only (async planned for v2.0)
+- No built-in conflict resolution for complex state updates
+
+## See Also
+
+- [Agent Types](../references/agent-types.md) - 41 Loki Mode agent types
+- [GitHub Integration](../skills/github-integration.md) - Issue and PR automation
+- [Enterprise Features](../wiki/Enterprise-Features.md) - Multi-project orchestration
+- [API Reference](../wiki/API-Reference.md) - Complete API documentation