openclaw-nerve-cockpit

name	openclaw-nerve-cockpit
description	Real-time web cockpit for OpenClaw providing voice conversations, agent fleet control, kanban boards, workspace management, and usage visibility
triggers	["set up nerve for openclaw","add voice control to my openclaw agent","create an openclaw dashboard","manage multiple openclaw agents with nerve","configure nerve kanban board","integrate nerve with openclaw gateway","troubleshoot nerve installation","add charts to openclaw responses"]

OpenClaw Nerve Cockpit

Skill by ara.so — Hermes Skills collection.

Nerve is a real-time web cockpit for OpenClaw that transforms agent interaction from chat-only to full operational control. It provides voice conversations, multi-agent fleet management, automated kanban boards, workspace/file control, sub-agent sessions, inline charts, and comprehensive usage visibility.

What Nerve Does

Nerve sits between your browser and the OpenClaw Gateway, providing:

• Fleet Control: Manage multiple agents from one interface, each with its own workspace, memory, identity, and skills
• Voice Interface: Push-to-talk, wake word, local Whisper transcription, multilingual commands, multiple TTS providers
• Full Context: Live workspace browser, tabbed editor, memory editing, config editing, skills inspection
• Operations Layer: Session trees, cron scheduling, kanban task boards, review flows, proposal inbox, model overrides
• Rich Output: Charts, diffs, previews, syntax-highlighted code, structured tool rendering, streaming UI
• Observability: Token usage, cost tracking, context meter, agent logs, event logs

Architecture

Browser ─── Nerve (:3080) ─── OpenClaw Gateway (:18789)
 │           │
 ├─ WS ──────┤ proxied to gateway
 ├─ SSE ─────┤ file watchers, real-time sync
 └─ REST ────┘ files, memories, TTS, models

Frontend: React 19, Tailwind CSS 4, shadcn/ui, Vite 7
Backend: Hono 4 on Node.js 22+

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/install.sh | bash

The installer handles dependencies, clone, build, and launches the setup wizard with guided access modes (localhost, LAN, Tailscale tailnet IP, Tailscale Serve).

Manual Install

git clone https://github.com/daggerhashimoto/openclaw-nerve.git
cd openclaw-nerve
npm install
npm run setup
npm run prod

Install from Next Branch (Latest Features)

curl -fsSL https://raw.githubusercontent.com/daggerhashimoto/openclaw-nerve/master/install.sh | bash -s -- --branch next

Or switch existing install:

cd ~/nerve
git fetch origin
git switch next || git switch -c next --track origin/next
git pull --ff-only
npm install
npm run build
npm run prod

Key Commands

# Development
npm run dev                    # Start frontend (Vite on :3080)
PORT=3081 npm run dev:server   # Start backend (explicit split-port dev)

# Production
npm run prod                   # Build and run production server

# Management
npm run setup                  # Interactive setup wizard
npm run update -- --yes        # Auto-update with rollback on failure
npm run build                  # Build frontend and backend

# Utilities
npm run lint                   # Lint TypeScript files
npm run type-check             # TypeScript type checking

Configuration

Nerve uses a .env file in the project root. Key variables:

Core Settings

# Server binding
HOST=127.0.0.1                 # Bind to localhost (default)
# HOST=0.0.0.0                 # Bind to all interfaces (enables network access)
PORT=3080                      # Server port

# OpenClaw Gateway
GATEWAY_URL=http://localhost:18789
GATEWAY_TOKEN=                 # Optional: if gateway requires auth

# Security (required when HOST=0.0.0.0)
PASSWORD_HASH=                 # bcrypt hash of UI password
SESSION_SECRET=                # Random string for session signing (32+ chars)
TRUSTED_CONNECTION=false       # Set true for server-side gateway token injection

Voice Settings

# Voice input
WHISPER_MODEL_PATH=/path/to/whisper/model  # Local Whisper model
WAKE_WORD=nerve                            # Wake word for voice activation
LANGUAGE=en                                # Transcription language

# TTS Provider (choose one)
TTS_PROVIDER=openai            # Options: openai, elevenlabs, edge
OPENAI_API_KEY=                # Required if TTS_PROVIDER=openai
ELEVENLABS_API_KEY=            # Required if TTS_PROVIDER=elevenlabs
TTS_VOICE=alloy                # Voice ID for chosen provider

Advanced Settings

# Multi-agent setup
AGENT_CONFIG_DIR=/path/to/agents  # Directory with per-agent configs

# Performance
WS_PING_INTERVAL=30000         # WebSocket ping interval (ms)
FILE_WATCH_DEBOUNCE=300        # File watcher debounce (ms)

# Logging
LOG_LEVEL=info                 # Options: debug, info, warn, error

Generating PASSWORD_HASH

// scripts/hash-password.ts
import bcrypt from 'bcrypt';

const password = process.argv[2];
if (!password) {
  console.error('Usage: tsx scripts/hash-password.ts <password>');
  process.exit(1);
}

const hash = await bcrypt.hash(password, 10);
console.log(hash);

Run:

npx tsx scripts/hash-password.ts mypassword

Deployment Modes

Local (Default)

Run Nerve and Gateway on the same machine. Best for reliability and simplicity.

HOST=127.0.0.1
PORT=3080
GATEWAY_URL=http://localhost:18789

LAN Access

Expose Nerve on your local network.

HOST=0.0.0.0
PORT=3080
PASSWORD_HASH=<bcrypt_hash>
SESSION_SECRET=<random_32_char_string>
GATEWAY_URL=http://localhost:18789

Tailscale Access

Expose via Tailscale tailnet IP or Tailscale Serve.

# Via tailnet IP
HOST=0.0.0.0
PORT=3080
PASSWORD_HASH=<bcrypt_hash>
SESSION_SECRET=<random_32_char_string>

# Via Tailscale Serve (alternative)
HOST=127.0.0.1
PORT=3080
# Run: tailscale serve https / http://127.0.0.1:3080

Hybrid

Nerve local, Gateway in cloud.

HOST=127.0.0.1
PORT=3080
GATEWAY_URL=https://your-gateway.example.com
GATEWAY_TOKEN=<gateway_token>

Full Cloud

Both Nerve and Gateway in cloud.

HOST=0.0.0.0
PORT=3080
PASSWORD_HASH=<bcrypt_hash>
SESSION_SECRET=<random_32_char_string>
GATEWAY_URL=https://your-gateway.example.com
GATEWAY_TOKEN=<gateway_token>

Agent Markers for Rich Output

Nerve recognizes special markers in agent responses to render rich UI components.

Charts

{{CHART_START}}
{
  "type": "line",
  "data": {
    "labels": ["Jan", "Feb", "Mar", "Apr"],
    "datasets": [{
      "label": "Revenue",
      "data": [12000, 19000, 15000, 25000]
    }]
  }
}
{{CHART_END}}

Supported chart types: line, bar, pie, doughnut, radar, scatter

Kanban Tasks

{{KANBAN_START}}
{
  "title": "Implement user authentication",
  "description": "Add JWT-based auth to API endpoints",
  "priority": "high",
  "tags": ["security", "backend"],
  "assignee": "agent-1"
}
{{KANBAN_END}}

TTS Control

{{TTS_START}}
This text will be read aloud using the configured TTS provider.
{{TTS_END}}

Code Diffs

{{DIFF_START}}
- const old = "previous version";
+ const updated = "new version";
{{DIFF_END}}

Code Examples

Creating a Custom Backend Route

// server/routes/custom.ts
import { Hono } from 'hono';
import type { AppContext } from '../types';

const custom = new Hono<AppContext>();

// Protected route (requires auth when HOST=0.0.0.0)
custom.get('/agent-status', async (c) => {
  const gatewayUrl = c.env.GATEWAY_URL;
  const token = c.env.GATEWAY_TOKEN;
  
  const response = await fetch(`${gatewayUrl}/api/agents`, {
    headers: token ? { Authorization: `Bearer ${token}` } : {},
  });
  
  const agents = await response.json();
  
  return c.json({
    total: agents.length,
    active: agents.filter(a => a.status === 'active').length,
    agents,
  });
});

export default custom;

Register in server/index.ts:

import custom from './routes/custom';

app.route('/api/custom', custom);

Adding a Frontend Component

// src/components/AgentStatusCard.tsx
import { useEffect, useState } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';

interface AgentStatus {
  total: number;
  active: number;
}

export function AgentStatusCard() {
  const [status, setStatus] = useState<AgentStatus | null>(null);

  useEffect(() => {
    const fetchStatus = async () => {
      const response = await fetch('/api/custom/agent-status');
      const data = await response.json();
      setStatus(data);
    };

    fetchStatus();
    const interval = setInterval(fetchStatus, 5000);
    return () => clearInterval(interval);
  }, []);

  if (!status) return <div>Loading...;

   (
    
  );
}

WebSocket Event Handling

// src/hooks/useGatewayWebSocket.ts
import { useEffect, useRef, useState } from 'react';

interface GatewayMessage {
  type: string;
  payload: unknown;
}

export function useGatewayWebSocket(agentId: string) {
  const [messages, setMessages] = useState<GatewayMessage[]>([]);
  const wsRef = useRef<WebSocket | null>(null);

  useEffect(() => {
    const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
    const ws = new WebSocket(`${protocol}//${window.location.host}/ws/gateway`);

    ws.onopen = () => {
      ws.send(JSON.stringify({ type: 'subscribe', agentId }));
    };

    ws.onmessage = (event) => {
      const message = JSON.parse(event.);
      ( [...prev, message]);
    };

    ws. =  {
      .(, error);
    };

    wsRef. = ws;

      {
      ws.();
    };
  }, [agentId]);

   { messages, : wsRef. };
}

Server-Side Event Streaming

// server/routes/events.ts
import { Hono } from 'hono';
import { streamSSE } from 'hono/streaming';
import type { AppContext } from '../types';

const events = new Hono<AppContext>();

events.get('/file-changes', async (c) => {
  return streamSSE(c, async (stream) => {
    const watcher = watchWorkspace(c.env.WORKSPACE_PATH);
    
    watcher.on('change', (file) => {
      stream.writeSSE({
        data: JSON.stringify({ type: 'file_changed', file }),
      });
    });

    // Keep connection alive
    const ping = setInterval(() => {
      stream.writeSSE({ data: 'ping' });
    }, 30000);

    // Cleanup on disconnect
    stream.onAbort(() => {
      clearInterval(ping);
      watcher.close();
    });
  });
});

  events;

Custom TTS Provider Integration

// server/services/tts/custom-provider.ts
import type { TTSProvider, TTSOptions } from './types';

export class CustomTTSProvider implements TTSProvider {
  private apiKey: string;
  private endpoint: string;

  constructor(apiKey: string, endpoint: string) {
    this.apiKey = apiKey;
    this.endpoint = endpoint;
  }

  async synthesize(text: string, options: TTSOptions): Promise<Buffer> {
    const response = await fetch(this.endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.({
        text,
        : options. || ,
        : options. || ,
      }),
    });

     (!response.) {
        ();
    }

     .( response.());
  }

  (): [] {
     [, , ];
  }
}

Common Patterns

Multi-Agent Setup

Create agent-specific config files:

mkdir -p ~/.config/nerve/agents

// ~/.config/nerve/agents/researcher.json
{
  "id": "researcher",
  "name": "Research Agent",
  "workspace": "/path/to/research-workspace",
  "memory": "/path/to/research-memory.json",
  "identity": "You are a research specialist focused on gathering and analyzing information.",
  "skills": ["web-search", "data-analysis", "summarization"],
  "model": "claude-3-5-sonnet-20241022"
}

# In .env
AGENT_CONFIG_DIR=/home/user/.config/nerve/agents

Cron Task Scheduling

// Add to agent identity or system message
"You can schedule recurring tasks using cron syntax. Example:
{{CRON_START}}
{
  \"schedule\": \"0 9 * * *\",
  \"task\": \"Generate daily report\",
  \"agent\": \"researcher\"
}
{{CRON_END}}"

Review Flow Integration

// Agent proposes changes for review
"{{PROPOSAL_START}}
{
  \"type\": \"code_change\",
  \"file\": \"src/app.ts\",
  \"description\": \"Refactor authentication logic\",
  \"diff\": \"...\"
}
{{PROPOSAL_END}}"

Context Pressure Monitoring

// src/hooks/useContextMeter.ts
export function useContextMeter(sessionId: string) {
  const [context, setContext] = useState({
    used: 0,
    limit: 200000,
    percentage: 0,
  });

  useEffect(() => {
    const checkContext = async () => {
      const response = await fetch(`/api/sessions/${sessionId}/context`);
      const data = await response.json();
      setContext({
        used: data.tokens,
        limit: data.limit,
        percentage: (data.tokens / data.limit) * 100,
      });
    };

    checkContext();
    const interval = setInterval(checkContext, 10000);
    return () => clearInterval(interval);
  }, [sessionId]);

  return context;
}

Troubleshooting

Gateway Connection Issues

# Check gateway is running
curl http://localhost:18789/health

# Verify Nerve can reach gateway
# Check GATEWAY_URL in .env
# If using GATEWAY_TOKEN, verify it's correct

WebSocket Connection Fails

// Check browser console for:
// - CORS errors (ensure gateway allows origin)
// - Authentication failures (check PASSWORD_HASH)
// - Network tab shows 101 Switching Protocols

// Server-side debugging:
// Set LOG_LEVEL=debug in .env
// Check server/logs/websocket.log

Voice Transcription Not Working

# Verify Whisper model path
ls -la $WHISPER_MODEL_PATH

# Check microphone permissions in browser
# Chrome: Settings > Privacy and security > Site Settings > Microphone

# Test with different model sizes
# WHISPER_MODEL_PATH=/path/to/ggml-base.en.bin  # Faster
# WHISPER_MODEL_PATH=/path/to/ggml-large-v3.bin # More accurate

File Watcher Not Updating

# Increase OS file watch limit (Linux)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Adjust debounce in .env
FILE_WATCH_DEBOUNCE=500  # Increase if updates too frequent

Authentication Failures (HOST=0.0.0.0)

# Regenerate password hash
npx tsx scripts/hash-password.ts newpassword

# Update .env with new hash
PASSWORD_HASH=<new_hash>

# Ensure SESSION_SECRET is set and >= 32 chars
SESSION_SECRET=$(openssl rand -base64 32)

Update Fails to Roll Back

# Manual rollback
cd ~/nerve
git reflog  # Find previous commit
git reset --hard HEAD@{1}
npm install
npm run build
npm run prod

Port Already in Use

# Find process using port
lsof -i :3080
# or
netstat -tuln | grep 3080

# Kill process
kill -9 <PID>

# Or use different port
PORT=3081 npm run prod

Resources

• Documentation: docs/
• Architecture: docs/ARCHITECTURE.md
• Security: docs/SECURITY.md
• Discord: discord.gg/Sh9ZGtctva
• Homepage: nerve.zone