@eyeclaw/eyeclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EyeClaw Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @eyeclaw/eyeclaw
+
+EyeClaw channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) - Connect your local OpenClaw instance to the EyeClaw platform.
+
+## Installation
+
+```bash
+openclaw plugins install @eyeclaw/eyeclaw
+```
+
+### Windows Troubleshooting
+
+If `openclaw plugins install` fails with `spawn npm ENOENT`, install manually:
+
+```bash
+# 1. Download the package
+curl -O https://registry.npmjs.org/@eyeclaw/eyeclaw/-/eyeclaw-1.0.0.tgz
+
+# 2. Install from local file
+openclaw plugins install ./eyeclaw-1.0.0.tgz
+```
+
+## Configuration
+
+### 1. Create a Bot on EyeClaw
+
+1. Sign up at [https://eyeclaw.io](https://eyeclaw.io)
+2. Create a new bot in your dashboard
+3. Copy the Bot ID and SDK Token
+
+### 2. Configure OpenClaw
+
+```bash
+openclaw config set channels.eyeclaw.enabled true
+openclaw config set channels.eyeclaw.botId "your-bot-id"
+openclaw config set channels.eyeclaw.sdkToken "your-sdk-token"
+openclaw config set channels.eyeclaw.serverUrl "https://eyeclaw.io"
+```
+
+### 3. Start OpenClaw
+
+```bash
+openclaw start
+```
+
+You should see the connection message:
+
+```
+✅ Successfully subscribed to BotChannel
+🎉 Bot connected! Session ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+## Configuration Options
+
+```yaml
+channels:
+  eyeclaw:
+    enabled: true
+    botId: "1"
+    sdkToken: "your-sdk-token-here"
+    serverUrl: "https://eyeclaw.io"  # or self-hosted URL
+    reconnectInterval: 5000  # milliseconds (default: 5000)
+    heartbeatInterval: 30000  # milliseconds (default: 30000)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable/disable the plugin |
+| `botId` | string | - | Bot ID from EyeClaw dashboard |
+| `sdkToken` | string | - | SDK Token for authentication |
+| `serverUrl` | string | `https://eyeclaw.io` | EyeClaw server URL |
+| `reconnectInterval` | number | `5000` | Reconnect interval in ms |
+| `heartbeatInterval` | number | `30000` | Heartbeat interval in ms |
+
+## Features
+
+- **WebSocket Connection**: Real-time bidirectional communication with EyeClaw platform
+- **Auto-Reconnect**: Automatically reconnects on connection loss
+- **Heartbeat**: Keeps connection alive with periodic ping/pong
+- **Real-time Monitoring**: View bot status, logs, and sessions in EyeClaw dashboard
+- **MCP Integration**: Expose your bot as MCP plugin for platforms like Coze, Claude Desktop
+- **Session Management**: Track connection sessions with uptime and activity logs
+
+## MCP Plugin Integration
+
+Your bot automatically provides an MCP plugin URL that can be used with AI platforms:
+
+```
+https://eyeclaw.io/mcp/stream/your-bot-id?api_key=your-api-key
+```
+
+### Supported Platforms
+
+- **Coze**: Add as custom MCP plugin
+- **Claude Desktop**: Add to `claude_desktop_config.json`
+- **Other MCP-compatible platforms**: Use the stream URL
+
+## Upgrade
+
+```bash
+openclaw plugins update eyeclaw
+```
+
+## Uninstall
+
+```bash
+openclaw plugins uninstall eyeclaw
+```
+
+## Troubleshooting
+
+### Bot cannot connect
+
+1. Check your internet connection
+2. Verify `botId` and `sdkToken` are correct
+3. Ensure `serverUrl` is accessible
+4. Check OpenClaw logs: `openclaw logs`
+
+### Connection drops frequently
+
+1. Check firewall settings
+2. Verify network stability
+3. Try increasing `heartbeatInterval`:
+
+```bash
+openclaw config set channels.eyeclaw.heartbeatInterval 60000
+```
+
+### "Unauthorized" error
+
+Your SDK token may be invalid or expired. Regenerate it in the EyeClaw dashboard:
+
+1. Go to your bot settings
+2. Click "Regenerate SDK Token"
+3. Update OpenClaw config with the new token
+
+## Architecture
+
+```
+┌─────────────────┐         WebSocket         ┌──────────────────┐
+│  Local OpenClaw │◄────────────────────────►│ EyeClaw Platform │
+│    Instance     │    ActionCable/BotChannel  │   (Rails)        │
+└─────────────────┘                            └──────────────────┘
+        │                                               │
+        │                                               │
+        ▼                                               ▼
+  Execute commands                            Real-time dashboard
+  Process requests                            Status monitoring
+  Run tools                                   Activity logs
+```
+
+### How it Works
+
+1. **Plugin Initialization**: When OpenClaw starts, the plugin connects to EyeClaw via WebSocket
+2. **Authentication**: Uses SDK Token to authenticate with BotChannel
+3. **Session Creation**: Server creates a session and assigns a session ID
+4. **Heartbeat**: Plugin sends periodic pings to keep connection alive
+5. **Event Forwarding**: OpenClaw events (messages, tool execution, errors) are sent to EyeClaw
+6. **Dashboard Updates**: EyeClaw dashboard shows real-time status and logs
+
+## Development
+
+### Build from Source
+
+```bash
+cd sdk
+npm install
+npm run build
+```
+
+### Link Locally
+
+```bash
+npm link
+openclaw plugins install /path/to/eyeclaw/sdk
+```
+
+### Run TypeScript in Watch Mode
+
+```bash
+npm run watch
+```
+
+## API Reference
+
+### EyeClawClient
+
+```typescript
+import { EyeClawClient } from '@eyeclaw/eyeclaw'
+
+const client = new EyeClawClient(config, logger)
+
+// Connect to EyeClaw
+await client.connect()
+
+// Send log message
+client.sendLog('info', 'Hello from OpenClaw')
+
+// Send command result
+client.sendCommandResult('execute_tool', { result: 'success' })
+
+// Request bot status
+client.requestStatus()
+
+// Disconnect
+client.disconnect()
+```
+
+## Support
+
+- **Documentation**: [https://eyeclaw.io/docs](https://eyeclaw.io/docs)
+- **Issues**: [https://github.com/eyeclaw/eyeclaw/issues](https://github.com/eyeclaw/eyeclaw/issues)
+- **Discord**: [https://discord.gg/eyeclaw](https://discord.gg/eyeclaw)
+
+## License
+
+MIT © EyeClaw Team
+
+## Related Projects
+
+- [OpenClaw](https://github.com/openclaw/openclaw) - The AI assistant framework
+- [clawdbot-feishu](https://github.com/m1heng/clawdbot-feishu) - Feishu/Lark channel plugin (inspiration for this plugin)

package/index.ts

@@ -0,0 +1,82 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk'
+import { emptyPluginConfigSchema } from 'openclaw/plugin-sdk'
+import { EyeClawClient } from './src/client.js'
+import type { PluginConfig } from './src/types.js'
+
+let client: EyeClawClient | null = null
+
+/**
+ * EyeClaw SDK - OpenClaw Channel Plugin
+ * 
+ * Connects local OpenClaw instance to EyeClaw platform via WebSocket.
+ */
+const plugin = {
+  id: 'eyeclaw',
+  name: 'EyeClaw',
+  description: 'EyeClaw platform channel plugin',
+  configSchema: emptyPluginConfigSchema(),
+  
+  register(api: OpenClawPluginApi) {
+    const runtime = api.runtime
+    const logger = runtime.logging.getChildLogger({ plugin: 'eyeclaw' })
+    const config = runtime.config as any
+    
+    // Get EyeClaw config from channels.eyeclaw
+    const eyeclawConfig: PluginConfig = config?.channels?.eyeclaw || {}
+    
+    // Check if enabled
+    if (eyeclawConfig.enabled === false) {
+      logger.info('Plugin disabled in config')
+      return
+    }
+    
+    // Validate required fields
+    if (!eyeclawConfig.botId || !eyeclawConfig.sdkToken) {
+      logger.warn('botId and sdkToken are required')
+      logger.warn('Configure with: openclaw config set channels.eyeclaw.botId "YOUR_BOT_ID"')
+      logger.warn('Configure with: openclaw config set channels.eyeclaw.sdkToken "YOUR_SDK_TOKEN"')
+      return
+    }
+    
+    // Set defaults
+    eyeclawConfig.serverUrl = eyeclawConfig.serverUrl || 'http://localhost:3000'
+    eyeclawConfig.reconnectInterval = eyeclawConfig.reconnectInterval || 5000
+    eyeclawConfig.heartbeatInterval = eyeclawConfig.heartbeatInterval || 30000
+    
+    logger.info('🦞 Starting EyeClaw SDK...', { botId: eyeclawConfig.botId, serverUrl: eyeclawConfig.serverUrl })
+    
+    // Create logger adapter for client (simple console logger)
+    const clientLogger = {
+      debug: (msg: string) => logger.debug(msg),
+      info: (msg: string) => logger.info(msg),
+      warn: (msg: string) => logger.warn(msg),
+      error: (msg: string) => logger.error(msg),
+    }
+    
+    // Create and connect WebSocket client
+    client = new EyeClawClient(eyeclawConfig, clientLogger)
+    
+    client.connect().then(() => {
+      logger.info('✅ Successfully connected to EyeClaw platform')
+    }).catch((error: Error) => {
+      logger.error('Failed to connect to EyeClaw', { error: error.message })
+    })
+    
+    // Handle shutdown
+    const shutdown = () => {
+      if (client) {
+        logger.info('🛑 Shutting down EyeClaw SDK...')
+        client.disconnect()
+      }
+    }
+    
+    process.on('SIGINT', shutdown)
+    process.on('SIGTERM', shutdown)
+  },
+}
+
+export default plugin
+
+// Re-export for direct usage
+export { EyeClawClient } from './src/client.js'
+export * from './src/types.js'

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "eyeclaw",
+  "channels": ["eyeclaw"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@eyeclaw/eyeclaw",
+  "version": "1.0.0",
+  "description": "EyeClaw channel plugin for OpenClaw - Connect your local OpenClaw instance to EyeClaw platform",
+  "type": "module",
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "eyeclaw",
+    "plugin",
+    "channel",
+    "mcp",
+    "websocket"
+  ],
+  "author": "EyeClaw Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eyeclaw/eyeclaw.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/eyeclaw/eyeclaw/issues"
+  },
+  "homepage": "https://eyeclaw.io",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "channel": {
+      "id": "eyeclaw",
+      "label": "EyeClaw",
+      "selectionLabel": "EyeClaw Platform",
+      "blurb": "Connect local OpenClaw to EyeClaw platform via WebSocket.",
+      "order": 100
+    },
+    "install": {
+      "npmSpec": "@eyeclaw/eyeclaw",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "dependencies": {
+    "ws": "^8.16.0",
+    "@types/ws": "^8.5.10",
+    "zod": "^3.22.4"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.0",
+    "openclaw": ">=2026.2.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import chalk from 'chalk'
+
+/**
+ * EyeClaw SDK CLI
+ * 
+ * This file provides a minimal CLI interface for the plugin.
+ * The actual installation is handled by: openclaw plugins install @eyeclaw/sdk
+ */
+
+const USAGE = `
+${chalk.bold.blue('EyeClaw SDK')} - Connect your local OpenClaw to EyeClaw platform
+
+${chalk.bold('Installation:')}
+  ${chalk.cyan('openclaw plugins install @eyeclaw/sdk')}
+
+${chalk.bold('Configuration:')}
+  ${chalk.cyan('openclaw config set channels.eyeclaw.enabled true')}
+  ${chalk.cyan('openclaw config set channels.eyeclaw.botId "your-bot-id"')}
+  ${chalk.cyan('openclaw config set channels.eyeclaw.sdkToken "your-sdk-token"')}
+  ${chalk.cyan('openclaw config set channels.eyeclaw.serverUrl "https://eyeclaw.io"')}
+
+${chalk.bold('Upgrade:')}
+  ${chalk.cyan('openclaw plugins update eyeclaw')}
+
+${chalk.bold('Uninstall:')}
+  ${chalk.cyan('openclaw plugins uninstall eyeclaw')}
+
+${chalk.bold('Documentation:')}
+  ${chalk.cyan('https://eyeclaw.io/docs')}
+
+${chalk.bold('Support:')}
+  ${chalk.cyan('https://github.com/eyeclaw/eyeclaw/issues')}
+`
+
+function main() {
+  const args = process.argv.slice(2)
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE)
+    process.exit(0)
+  }
+
+  if (args.includes('--version') || args.includes('-v')) {
+    // Read version from package.json
+    const pkg = require('../package.json')
+    console.log(`v${pkg.version}`)
+    process.exit(0)
+  }
+
+  // Default: show usage
+  console.log(USAGE)
+  console.log(chalk.yellow('ℹ This is an OpenClaw plugin. Please install it using:'))
+  console.log(chalk.cyan('  openclaw plugins install @eyeclaw/sdk\n'))
+}
+
+main()

package/src/client.ts

@@ -0,0 +1,226 @@
+import WebSocket from 'ws'
+import type { PluginConfig, Logger, ChannelMessage, BotStatus } from './types.js'
+
+export class EyeClawClient {
+  private ws: WebSocket | null = null
+  private config: PluginConfig
+  private logger: Logger
+  private reconnectTimer: NodeJS.Timeout | null = null
+  private heartbeatTimer: NodeJS.Timeout | null = null
+  private sessionId: string | null = null
+  private connected = false
+
+  constructor(config: PluginConfig, logger: Logger) {
+    this.config = config
+    this.logger = logger
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) {
+      this.logger.warn('Already connected to EyeClaw')
+      return
+    }
+
+    // Add sdk_token as query parameter for connection authentication
+    const wsUrl = this.config.serverUrl.replace(/^http/, 'ws') + '/cable?sdk_token=' + encodeURIComponent(this.config.sdkToken)
+    this.logger.info(`Connecting to EyeClaw: ${wsUrl.split('?')[0]}?sdk_token=***`)
+
+    try {
+      this.ws = new WebSocket(wsUrl)
+
+      this.ws.on('open', () => this.handleOpen())
+      this.ws.on('message', (data) => this.handleMessage(data))
+      this.ws.on('error', (error) => this.handleError(error))
+      this.ws.on('close', () => this.handleClose())
+    } catch (error) {
+      this.logger.error('Failed to create WebSocket connection:', error)
+      this.scheduleReconnect()
+    }
+  }
+
+  private handleOpen(): void {
+    this.logger.info('WebSocket connected, subscribing to BotChannel...')
+    this.connected = true
+
+    // Subscribe to BotChannel (token already passed in connection URL)
+    const subscribeMessage = {
+      command: 'subscribe',
+      identifier: JSON.stringify({
+        channel: 'BotChannel',
+      }),
+    }
+
+    this.send(subscribeMessage)
+  }
+
+  private handleMessage(data: WebSocket.Data): void {
+    try {
+      const message = JSON.parse(data.toString())
+      this.logger.debug('Received message:', message)
+
+      // ActionCable protocol messages
+      if (message.type === 'ping') {
+        // Respond to ping
+        return
+      }
+
+      if (message.type === 'welcome') {
+        this.logger.info('Received welcome message from ActionCable')
+        return
+      }
+
+      if (message.type === 'confirm_subscription') {
+        this.logger.info('✅ Successfully subscribed to BotChannel')
+        this.startHeartbeat()
+        return
+      }
+
+      // Channel messages
+      if (message.message) {
+        this.handleChannelMessage(message.message)
+      }
+    } catch (error) {
+      this.logger.error('Failed to parse message:', error)
+    }
+  }
+
+  private handleChannelMessage(message: Record<string, unknown>): void {
+    const { type } = message
+
+    switch (type) {
+      case 'connected':
+        this.sessionId = message.session_id as string
+        this.logger.info(`🎉 Bot connected! Session ID: ${this.sessionId}`)
+        break
+
+      case 'pong':
+        this.logger.debug('Received pong from server')
+        break
+
+      case 'status_response':
+        this.handleStatusResponse(message as unknown as BotStatus)
+        break
+
+      case 'command_received':
+        this.logger.info('Command received by server:', message.command)
+        break
+
+      case 'log':
+        this.logger.info(`[Server Log] ${message.level}: ${message.message}`)
+        break
+
+      default:
+        this.logger.warn('Unknown message type:', type)
+    }
+  }
+
+  private handleStatusResponse(status: BotStatus): void {
+    this.logger.info('Bot status:', {
+      online: status.online,
+      status: status.status,
+      sessions: status.active_sessions,
+      uptime: `${Math.floor(status.uptime / 60)}m`,
+    })
+  }
+
+  private handleError(error: Error): void {
+    this.logger.error('WebSocket error:', error.message)
+  }
+
+  private handleClose(): void {
+    this.logger.warn('WebSocket connection closed')
+    this.connected = false
+    this.stopHeartbeat()
+    this.scheduleReconnect()
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectTimer) {
+      return
+    }
+
+    const interval = this.config.reconnectInterval || 5000
+    this.logger.info(`Reconnecting in ${interval / 1000}s...`)
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.connect()
+    }, interval)
+  }
+
+  private startHeartbeat(): void {
+    const interval = this.config.heartbeatInterval || 30000
+
+    this.heartbeatTimer = setInterval(() => {
+      this.sendChannelMessage('ping', {})
+    }, interval)
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = null
+    }
+  }
+
+  private send(message: Record<string, unknown>): void {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      this.logger.error('Cannot send message: WebSocket not connected')
+      return
+    }
+
+    this.ws.send(JSON.stringify(message))
+  }
+
+  private sendChannelMessage(action: string, data: Record<string, unknown>): void {
+    const message = {
+      command: 'message',
+      identifier: JSON.stringify({
+        channel: 'BotChannel',
+      }),
+      data: JSON.stringify({
+        action,
+        ...data,
+      }),
+    }
+
+    this.send(message)
+  }
+
+  sendLog(level: string, message: string): void {
+    this.sendChannelMessage('log', {
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+    })
+  }
+
+  sendCommandResult(command: string, result: unknown, error?: string): void {
+    this.sendChannelMessage('command_result', {
+      command,
+      result,
+      error,
+      timestamp: new Date().toISOString(),
+    })
+  }
+
+  requestStatus(): void {
+    this.sendChannelMessage('status', {})
+  }
+
+  disconnect(): void {
+    this.logger.info('Disconnecting from EyeClaw...')
+    this.connected = false
+    this.stopHeartbeat()
+
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer)
+      this.reconnectTimer = null
+    }
+
+    if (this.ws) {
+      this.ws.close()
+      this.ws = null
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+// Type definitions for OpenClaw plugin system
+// Reference: clawdbot-feishu architecture
+
+export interface PluginConfig {
+  enabled: boolean
+  botId: string
+  sdkToken: string
+  serverUrl: string
+  reconnectInterval?: number
+  heartbeatInterval?: number
+}
+
+export interface OpenClawContext {
+  config: PluginConfig
+  logger: Logger
+  emit: (event: string, data: unknown) => void
+  on: (event: string, handler: (data: unknown) => void) => void
+}
+
+export interface Logger {
+  info: (message: string) => void
+  warn: (message: string) => void
+  error: (message: string) => void
+  debug: (message: string) => void
+}
+
+export interface ChannelMessage {
+  type: string
+  content?: string
+  role?: 'user' | 'assistant'
+  timestamp?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface BotStatus {
+  online: boolean
+  status: string
+  active_sessions: number
+  total_sessions: number
+  uptime: number
+}