@rethinking-studio/clawcontrol 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# ClawControl
+
+配合 [ClawAI](https://apps.apple.com/app/id6759418062) iOS 应用的 OpenClaw 插件。通过该插件，你可以在手机上远程连接并控制本地的 OpenClaw。
+
+## 使用前准备
+
+想使用 iOS 端远程连接 OpenClaw，需要先安装并配置本插件。
+
+1. 安装插件到 OpenClaw
+2. 运行 `openclaw channels add`，选择 ClawControl 进行配置
+3. 按提示生成配对码，用 ClawAI App 扫码完成配对
+4. 配对成功后即可在手机上使用
+
+## 应用下载
+
+[iOS App Store - ClawAI](https://apps.apple.com/app/id6759418062)
+
+## 安装
+
+```bash
+openclaw plugins install @rethinking-studio/clawcontrol
+```
+
+或从 GitHub 克隆后本地安装：
+
+```bash
+git clone https://github.com/Rethinking-studio/clawcontrol.git
+openclaw plugins install ./clawcontrol
+```

package/index.ts

@@ -0,0 +1,480 @@
+/**
+ * ClawControl Channel Plugin for OpenClaw
+ *
+ * 功能：
+ * 1. 提供 clawcontrol 渠道，iOS 端可通过 WebSocket 与之通信
+ * 2. 使用 OpenClaw 的 registerChannel API，不会阻塞 CLI
+ */
+
+import os from 'os';
+import type { ChannelPlugin, ChannelOnboardingAdapter } from 'openclaw/plugin-sdk';
+import * as wsModule from './src/websocket.js';
+import * as cli from './src/cli.js';
+import * as chat from './src/chat.js';
+
+// 渠道 ID
+const CHANNEL_ID = 'clawcontrol';
+
+// 配置类型
+interface ClawControlConfig {
+  enabled?: boolean;
+  backendUrl?: string;
+  apiToken?: string;
+  deviceId?: string;
+  deviceName?: string;
+}
+
+interface ClawControlAccount {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  name: string;
+  backendUrl?: string;
+  apiToken?: string;
+  deviceId?: string;
+  deviceName?: string;
+}
+
+// 解析配置
+function resolveClawControlAccount(cfg: any): ClawControlAccount {
+  const channelConfig = cfg?.channels?.clawcontrol as ClawControlConfig | undefined;
+  const hasToken = !!channelConfig?.apiToken;
+
+  return {
+    accountId: 'default',
+    enabled: channelConfig?.enabled ?? false,
+    configured: hasToken,
+    name: channelConfig?.deviceName || 'ClawControl',
+    backendUrl: channelConfig?.backendUrl,
+    apiToken: channelConfig?.apiToken,
+    deviceId: channelConfig?.deviceId,
+    deviceName: channelConfig?.deviceName,
+  };
+}
+
+// ClawControl Onboarding 适配器
+const clawcontrolOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel: CHANNEL_ID,
+  getStatus: async ({ cfg }) => {
+    const account = resolveClawControlAccount(cfg);
+    const configured = account.configured;
+    const statusLines: string[] = [];
+
+    if (!configured) {
+      statusLines.push('ClawControl: needs token');
+    } else {
+      statusLines.push(`ClawControl: configured (device: ${account.name || 'unknown'})`);
+    }
+
+    return {
+      channel: CHANNEL_ID,
+      configured,
+      statusLines,
+      selectionHint: configured ? 'configured' : 'needs token',
+      quickstartScore: configured ? 2 : 0,
+    };
+  },
+  configure: async ({ cfg, prompter }) => {
+    const account = resolveClawControlAccount(cfg);
+    const defaultUrl = 'https://clawai.rethinkingstudio.com';
+    const baseUrl = (
+      process.env.CLAWCONTROL_BACKEND_URL ||
+      (account.backendUrl && !account.backendUrl.includes('localhost') ? account.backendUrl : null) ||
+      defaultUrl
+    ).replace(/\/$/, '');
+
+    const proceed = await prompter.confirm({
+      message: '是否现在生成配对码？',
+      initialValue: true,
+    });
+    if (!proceed) {
+      return { cfg };
+    }
+
+    await prompter.note('Creating pairing token...');
+
+    let createRes: Response;
+    try {
+      createRes = await fetch(`${baseUrl}/plugin/create-pairing-token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ backendUrl: baseUrl }),
+      });
+    } catch (e: any) {
+      const code = e?.cause?.code ?? e?.code;
+      const msg = code === 'ECONNREFUSED'
+        ? `Cannot connect to ${baseUrl} - is the backend running? Default: https://clawai.rethinkingstudio.com`
+        : code === 'ENOTFOUND'
+        ? `DNS lookup failed for ${baseUrl} - check network. Set CLAWCONTROL_BACKEND_URL if using different backend`
+        : e?.message || String(e);
+      throw new Error(`Fetch failed: ${msg}`);
+    }
+
+    if (!createRes.ok) {
+      const err = await createRes.text();
+      throw new Error(`Failed to create pairing token: ${err}`);
+    }
+
+    const { pairingToken, expiresIn } = (await createRes.json()) as { pairingToken: string; expiresIn: number };
+
+    const qrContent = JSON.stringify({ backendUrl: baseUrl, pairingToken });
+
+    await prompter.note(
+      `Scan the QR code below with ClawControl iOS App (expires in ${expiresIn}s):`
+    );
+
+    const qrcode = await import('qrcode-terminal');
+    qrcode.default.generate(qrContent, { small: true });
+
+    console.log('\nOr manually enter pairing code:', pairingToken);
+    console.log('Waiting for scan...\n');
+
+    const pollInterval = 2000;
+    const deadline = Date.now() + expiresIn * 1000;
+    let apiToken: string | null = null;
+
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, pollInterval));
+      const statusRes = await fetch(`${baseUrl}/plugin/pairing-status?pairingToken=${encodeURIComponent(pairingToken)}`);
+      const status = (await statusRes.json()) as { status: string; claimed?: boolean; apiToken?: string };
+      if (status.claimed && status.apiToken) {
+        apiToken = status.apiToken;
+        break;
+      }
+      if (status.status === 'invalid' || status.status === 'expired') {
+        throw new Error('Pairing token expired or invalid');
+      }
+    }
+
+    if (!apiToken) {
+      throw new Error('Pairing timed out. Please try again.');
+    }
+
+    const deviceId = `clawcontrol-${Date.now()}`;
+    const deviceName = os.hostname();
+
+    const next = {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        clawcontrol: {
+          enabled: true,
+          backendUrl: baseUrl,
+          apiToken,
+          deviceId,
+          deviceName,
+        },
+      },
+    };
+
+    return {
+      cfg: next,
+      statusLines: [`ClawControl: configured (device: ${deviceName})`],
+    };
+  },
+  disable: (cfg) => {
+    const next = { ...cfg } as any;
+    delete next.channels?.clawcontrol;
+    return next;
+  },
+};
+
+// 执行 CLI 命令的辅助函数
+function execCommand(command: string): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const { exec } = require('child_process');
+    exec(command, { timeout: 30000 }, (error: any, stdout: string, stderr: string) => {
+      if (error) {
+        reject(new Error(stderr || error.message));
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+// 导出 ChannelPlugin
+export const clawcontrolPlugin: ChannelPlugin<ClawControlAccount> = {
+  id: CHANNEL_ID,
+  meta: {
+    id: CHANNEL_ID,
+    label: 'ClawControl',
+    selectionLabel: 'ClawControl (iOS)',
+    docsPath: '/channels/clawcontrol',
+    docsLabel: 'clawcontrol',
+    blurb: 'Control OpenClaw from your iOS device',
+    aliases: ['ios', 'clawcontrol'],
+    order: 100,
+  },
+  capabilities: {
+    chatTypes: ['direct'],
+    polls: false,
+    threads: false,
+    media: false,
+    reactions: false,
+    edit: false,
+    reply: false,
+  },
+  reload: { configPrefixes: ['channels.clawcontrol'] },
+  onboarding: clawcontrolOnboardingAdapter,
+  configSchema: {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        enabled: { type: 'boolean' },
+        backendUrl: { type: 'string' },
+        apiToken: { type: 'string' },
+        deviceId: { type: 'string' },
+        deviceName: { type: 'string' },
+      },
+    },
+  },
+  config: {
+    listAccountIds: (cfg) => ['default'],
+    resolveAccount: (cfg, accountId) => resolveClawControlAccount(cfg),
+    defaultAccountId: () => 'default',
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const current = cfg?.channels?.clawcontrol as ClawControlConfig | undefined;
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          clawcontrol: {
+            ...current,
+            enabled,
+          },
+        },
+      };
+    },
+    deleteAccount: ({ cfg, accountId }) => {
+      const next = { ...cfg } as any;
+      delete next.channels?.clawcontrol;
+      return next;
+    },
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      enabled: account.enabled,
+      configured: account.configured,
+      name: account.name,
+    }),
+    resolveAllowFrom: () => [],
+    formatAllowFrom: (params) => {
+      const raw = params?.allowFrom;
+      console.log('[ClawControl formatAllowFrom] raw=', JSON.stringify(raw), 'type=', typeof raw, 'isArray=', Array.isArray(raw));
+      if (Array.isArray(raw)) return raw.map(String);
+      if (raw != null) return [String(raw)];
+      return [];
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: 'default',
+      running: false,
+      connected: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastConnectedAt: null,
+      lastDisconnect: null,
+      lastError: null,
+      port: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      connected: snapshot.connected ?? false,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastConnectedAt: snapshot.lastConnectedAt ?? null,
+      lastDisconnect: snapshot.lastDisconnect ?? null,
+      lastError: snapshot.lastError ?? null,
+      port: snapshot.port ?? null,
+    }),
+    probeAccount: async () => {
+      const ws = wsModule.getWs();
+      const isConnected = ws?.readyState === 1;
+      return {
+        ok: isConnected,
+        connected: isConnected,
+        readyState: ws?.readyState,
+      };
+    },
+    buildAccountSnapshot: (account, runtime, probe) => {
+      const status = wsModule.getConnectionStatus();
+      return {
+        accountId: account.accountId,
+        enabled: account.enabled,
+        configured: account.configured,
+        name: account.name,
+        running: runtime?.running ?? false,
+        connected: status.connected,
+        lastStartAt: runtime?.lastStartAt ?? null,
+        lastStopAt: runtime?.lastStopAt ?? null,
+        lastConnectedAt: status.lastConnectedAt,
+        lastDisconnect: status.lastDisconnect,
+        lastError: status.lastError,
+        port: runtime?.port ?? null,
+        probe,
+      };
+    },
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = resolveClawControlAccount(ctx.cfg);
+
+      if (!account.configured || !account.apiToken || !account.backendUrl) {
+        ctx.log?.info('ClawControl not configured, skipping WebSocket connection');
+        return;
+      }
+
+      ctx.setStatus({
+        accountId: ctx.accountId,
+        running: true,
+        connected: false,
+        lastStartAt: Date.now(),
+        lastError: null,
+      });
+      ctx.log?.info('Starting ClawControl WebSocket connection...');
+
+      try {
+        wsModule.startWebSocket(
+          account.backendUrl,
+          account.apiToken,
+          account.deviceId || 'clawcontrol-plugin',
+          (status) => {
+            ctx.setStatus({
+              accountId: ctx.accountId,
+              running: true,
+              connected: status.connected,
+              lastConnectedAt: status.lastConnectedAt,
+              lastDisconnect: status.lastDisconnect,
+              lastError: status.lastError,
+            });
+          }
+        ).catch((error) => {
+          ctx.log?.error('ClawControl WebSocket error:', error);
+        });
+
+        await new Promise(resolve => setTimeout(resolve, 1000));
+
+        const ws = wsModule.getWs();
+        if (ws?.readyState === 1) {
+          ctx.setStatus({
+            accountId: ctx.accountId,
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+            lastError: null,
+          });
+          ctx.log?.info('ClawControl WebSocket connected');
+        } else {
+          ctx.setStatus({
+            accountId: ctx.accountId,
+            running: true,
+            connected: false,
+            lastError: 'WebSocket connection failed',
+          });
+        }
+
+        ctx.abortSignal.addEventListener('abort', () => {
+          wsModule.stopWebSocket();
+        });
+
+        await wsModule.neverResolve();
+      } catch (error) {
+        ctx.setStatus({
+          accountId: ctx.accountId,
+          running: false,
+          connected: false,
+          lastError: String(error),
+        });
+        ctx.log?.error('Failed to connect ClawControl WebSocket:', error);
+      }
+    },
+    stopAccount: async (ctx) => {
+      ctx.log?.info('Stopping ClawControl WebSocket connection...');
+      await wsModule.stopWebSocket();
+      ctx.setStatus({
+        accountId: ctx.accountId,
+        running: false,
+        connected: false,
+        lastStopAt: Date.now(),
+      });
+    },
+  },
+};
+
+// 导出 register 函数
+export function register(api: any) {
+  if (api.runtime) {
+    chat.setChatRuntime(api.runtime);
+  }
+  api.registerChannel({ plugin: clawcontrolPlugin });
+
+  // Gateway 方法 - 供 iOS 端通过 backend 调用
+  api.registerGatewayMethod('clawcontrol.config.get', async ({ respond }: any) => {
+    const result = await cli.getCurrentModel();
+    respond(true, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.config.set', async ({ respond }: any, params: any) => {
+    const result = await cli.setModel(params.model);
+    respond(result.success || false, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.models.list', async ({ respond }: any) => {
+    const result = await cli.listModels();
+    respond(true, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.status', async ({ respond }: any) => {
+    const status = wsModule.getConnectionStatus();
+    respond(true, {
+      connected: status.connected,
+      lastConnectedAt: status.lastConnectedAt,
+    });
+  });
+
+  api.registerGatewayMethod('clawcontrol.usage', async ({ respond }: any) => {
+    const result = await cli.getUsage();
+    respond(true, result);
+  });
+
+  // Cron 接口
+  api.registerGatewayMethod('clawcontrol.cron.list', async ({ respond }: any) => {
+    const result = cli.listCronJobs();
+    respond(true, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.cron.add', async ({ respond }: any, params: any) => {
+    const result = cli.addCronJob(params.job);
+    respond(true, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.cron.update', async ({ respond }: any, params: any) => {
+    const result = cli.updateCronJob(params.id, params.patch);
+    respond(true, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.cron.remove', async ({ respond }: any, params: any) => {
+    const result = cli.removeCronJob(params.id);
+    respond(true, result);
+  });
+
+  api.registerGatewayMethod('clawcontrol.cron.run', async ({ respond }: any, params: any) => {
+    const result = await cli.runCronJob(params.id);
+    respond(true, result);
+  });
+}
+
+// 默认导出
+const plugin = {
+  id: CHANNEL_ID,
+  name: 'ClawControl',
+  description: 'iOS control panel for OpenClaw via WebSocket',
+  version: '1.0.0',
+  register,
+};
+
+export default plugin;

package/openclaw.plugin.json

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rethinking-studio/clawcontrol",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "OpenClaw plugin for ClawAI iOS app - remote control OpenClaw from your phone",
+  "main": "index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rethinking-studio/clawcontrol.git"
+  },
+  "keywords": ["openclaw", "clawcontrol", "ios", "clawai"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.0"
+  },
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "channel": {
+      "id": "clawcontrol",
+      "label": "ClawControl",
+      "selectionLabel": "ClawControl (iOS)",
+      "docsPath": "/channels/clawcontrol",
+      "blurb": "Control OpenClaw from your iOS device",
+      "order": 100,
+      "aliases": ["ios", "clawcontrol", "clawcontrol-ios"]
+    },
+    "install": {
+      "npmSpec": "@rethinking-studio/clawcontrol",
+      "localPath": "./plugin",
+      "defaultChoice": "local"
+    }
+  }
+}

package/src/chat.ts

@@ -0,0 +1,123 @@
+/**
+ * Chat 消息收发 - 调用 OpenClaw dispatch 并推送事件到 Backend
+ */
+
+let pluginRuntime: any = null;
+let sendToBackend: ((msg: object) => void) | null = null;
+
+export function setChatRuntime(runtime: any) {
+  pluginRuntime = runtime;
+}
+
+export function setChatSendFn(fn: (msg: object) => void) {
+  sendToBackend = fn;
+}
+
+function send(msg: object) {
+  sendToBackend?.(msg);
+}
+
+export async function handleChatSend(
+  requestId: string,
+  message: string,
+  sessionKey: string
+): Promise<void> {
+  if (!pluginRuntime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+    send({
+      type: 'chat.event',
+      id: requestId,
+      state: 'error',
+      errorMessage: 'OpenClaw runtime not available',
+    });
+    return;
+  }
+
+  const loadConfig = pluginRuntime?.config?.loadConfig;
+  if (!loadConfig) {
+    send({
+      type: 'chat.event',
+      id: requestId,
+      state: 'error',
+      errorMessage: 'Config loader not available',
+    });
+    return;
+  }
+
+  const runId = `clawcontrol-${requestId}-${Date.now()}`;
+
+  try {
+    const cfg = loadConfig();
+    const sessionKeyResolved = sessionKey?.trim() || 'main';
+
+    // 先发 ACK
+    send({
+      type: 'chat.ack',
+      id: requestId,
+      runId,
+      status: 'started',
+    });
+
+    const dispatcherOptions = {
+      deliver: async (payload: { text?: string }, info: { kind: string }) => {
+        const text = payload.text?.trim();
+        if (!text) return;
+        const state = info.kind === 'final' ? 'final' : 'streaming';
+        send({
+          type: 'chat.event',
+          id: requestId,
+          runId,
+          state,
+          text,
+        });
+      },
+      onError: (err: unknown) => {
+        send({
+          type: 'chat.event',
+          id: requestId,
+          runId,
+          state: 'error',
+          errorMessage: err instanceof Error ? err.message : String(err),
+        });
+      },
+    };
+
+    const ctx = {
+      Body: message,
+      BodyForAgent: message,
+      RawBody: message,
+      CommandBody: message,
+      SessionKey: sessionKeyResolved,
+      Provider: 'clawcontrol',
+      Surface: 'clawcontrol',
+      OriginatingChannel: 'clawcontrol',
+      ChatType: 'direct',
+      CommandAuthorized: true,
+      MessageSid: runId,
+      SenderId: 'clawcontrol-web',
+      SenderName: 'ClawControl',
+    };
+
+    await pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx,
+      cfg,
+      dispatcherOptions,
+      replyOptions: { disableBlockStreaming: false },
+    });
+
+    // 若 deliver 未发 final，补发一个
+    send({
+      type: 'chat.event',
+      id: requestId,
+      runId,
+      state: 'final',
+    });
+  } catch (err) {
+    send({
+      type: 'chat.event',
+      id: requestId,
+      runId,
+      state: 'error',
+      errorMessage: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/cli.ts

@@ -0,0 +1,188 @@
+/**
+ * CLI 命令封装
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import { randomUUID } from 'crypto';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const execAsync = promisify(exec);
+
+const CRON_JOBS_FILE = join(process.env.HOME || '', '.openclaw', 'cron', 'jobs.json');
+const OPENCLAW_CONFIG_FILE = join(process.env.HOME || '', '.openclaw', 'openclaw.json');
+
+function readJsonFile(filePath: string): any {
+  try {
+    if (existsSync(filePath)) {
+      return JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    return null;
+  } catch (e) {
+    return null;
+  }
+}
+
+export async function listModels(): Promise<any> {
+  try {
+    const { stdout } = await execAsync('openclaw models list --json', { encoding: 'utf-8' });
+    return JSON.parse(stdout);
+  } catch (e: any) {
+    return { models: [], error: e.message };
+  }
+}
+
+export async function getCurrentModel(): Promise<any> {
+  try {
+    const { stdout } = await execAsync('openclaw models list --json', { encoding: 'utf-8' });
+    const data = JSON.parse(stdout);
+    const defaultModel = (data.models || []).find((m: any) =>
+      (m.tags || []).includes('default')
+    );
+    return {
+      currentModel: defaultModel || null,
+      model: defaultModel || null,
+    };
+  } catch (e: any) {
+    return { currentModel: null, model: null, error: e.message };
+  }
+}
+
+export async function getUsage(): Promise<any> {
+  try {
+    const { stdout } = await execAsync('openclaw status --usage --json', { encoding: 'utf-8' });
+    return JSON.parse(stdout);
+  } catch (e: any) {
+    return { error: e.message };
+  }
+}
+
+export async function setModel(model: string): Promise<any> {
+  try {
+    const configPatch = JSON.stringify({ primary: model });
+    await execAsync(`openclaw config set agents.defaults.model '${configPatch}' --json`);
+    return { success: true };
+  } catch (e: any) {
+    return { success: false, error: e.message };
+  }
+}
+
+// 直接读取 cron jobs 文件，不通过 CLI（避免死锁）
+export function listCronJobs(): any {
+  const data = readJsonFile(CRON_JOBS_FILE);
+  if (data && data.jobs) {
+    return { jobs: data.jobs };
+  }
+  return { jobs: [] };
+}
+
+// 添加 cron job - 直接写入文件
+export function addCronJob(job: {
+  name?: string;
+  message?: string;
+  every?: string;
+  cron?: string;
+  disabled?: boolean;
+}): any {
+  try {
+    const data = readJsonFile(CRON_JOBS_FILE) || { version: 1, jobs: [] };
+    const newJob = {
+      name: job.name || 'Untitled',
+      description: job.name || '',
+      enabled: !job.disabled,
+      schedule: job.every ? {
+        kind: 'every',
+        everyMs: parseDuration(job.every),
+        anchorMs: Date.now()
+      } : {
+        kind: 'cron',
+        expr: job.cron || '* * * * *'
+      },
+      sessionTarget: 'main',
+      wakeMode: 'now',
+      payload: {
+        kind: 'systemEvent',
+        text: job.message || job.name || ''
+      },
+      id: generateId(),
+      createdAtMs: Date.now(),
+      updatedAtMs: Date.now(),
+      state: {
+        nextRunAtMs: Date.now()
+      }
+    };
+    data.jobs.push(newJob);
+    writeFileSync(CRON_JOBS_FILE, JSON.stringify(data, null, 2));
+    return { job: newJob };
+  } catch (e: any) {
+    return { error: e.message };
+  }
+}
+
+// 更新 cron job
+export function updateCronJob(id: string, patch: { enabled?: boolean; name?: string }): any {
+  try {
+    const data = readJsonFile(CRON_JOBS_FILE) || { version: 1, jobs: [] };
+    const jobIndex = data.jobs.findIndex((j: any) => j.id === id);
+    if (jobIndex === -1) {
+      return { error: 'Job not found' };
+    }
+    if (patch.enabled !== undefined) {
+      data.jobs[jobIndex].enabled = patch.enabled;
+    }
+    if (patch.name) {
+      data.jobs[jobIndex].name = patch.name;
+      data.jobs[jobIndex].description = patch.name;
+    }
+    data.jobs[jobIndex].updatedAtMs = Date.now();
+    writeFileSync(CRON_JOBS_FILE, JSON.stringify(data, null, 2));
+    return { job: data.jobs[jobIndex] };
+  } catch (e: any) {
+    return { error: e.message };
+  }
+}
+
+// 删除 cron job
+export function removeCronJob(id: string): any {
+  try {
+    const data = readJsonFile(CRON_JOBS_FILE) || { version: 1, jobs: [] };
+    const jobIndex = data.jobs.findIndex((j: any) => j.id === id);
+    if (jobIndex === -1) {
+      return { error: 'Job not found' };
+    }
+    data.jobs.splice(jobIndex, 1);
+    writeFileSync(CRON_JOBS_FILE, JSON.stringify(data, null, 2));
+    return { success: true };
+  } catch (e: any) {
+    return { error: e.message };
+  }
+}
+
+// 运行 cron job - 需要通过 CLI 执行
+export async function runCronJob(id: string): Promise<any> {
+  try {
+    const { stdout } = await execAsync(`openclaw cron run ${id} --json`, { encoding: 'utf-8' });
+    return JSON.parse(stdout);
+  } catch (e: any) {
+    return { error: e.message };
+  }
+}
+
+// 辅助函数
+function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+)(m|h|d)$/);
+  if (!match) return 3600000;
+  const value = parseInt(match[1]);
+  const unit = match[2];
+  switch (unit) {
+    case 'm': return value * 60 * 1000;
+    case 'h': return value * 60 * 60 * 1000;
+    case 'd': return value * 24 * 60 * 60 * 1000;
+    default: return value * 60 * 1000;
+  }
+}
+
+function generateId(): string {
+  return randomUUID();
+}

package/src/handlers.ts

@@ -0,0 +1,102 @@
+/**
+ * Backend 请求处理
+ */
+
+import * as cli from './cli.js';
+import * as chat from './chat.js';
+import type WebSocket from 'ws';
+
+let ws: WebSocket | null = null;
+
+export function setWs(wsInstance: WebSocket) {
+  ws = wsInstance;
+}
+
+export async function handleBackendRequest(action: string, params: any, requestId: string) {
+  console.log('[ClawControl] Handling request:', action, 'id:', requestId);
+
+  // chat.send 走推送流程，不发 response
+  if (action === 'chat.send') {
+    const message = params?.message?.trim();
+    const sessionKey = params?.sessionKey || 'main';
+    if (!message) {
+      ws?.send(JSON.stringify({
+        type: 'chat.event',
+        id: requestId,
+        state: 'error',
+        errorMessage: 'message required',
+      }));
+      return;
+    }
+    await chat.handleChatSend(requestId, message, sessionKey);
+    return;
+  }
+
+  let result: any = {};
+  let success = true;
+  let error: string | undefined;
+
+  try {
+    switch (action) {
+      case 'getModels':
+      case 'clawcontrol.models.list':
+        result = await cli.listModels();
+        break;
+
+      case 'getCurrentModel':
+      case 'clawcontrol.config.get':
+        result = await cli.getCurrentModel();
+        break;
+
+      case 'setModel':
+        result = await cli.setModel(params.model);
+        break;
+
+      case 'getUsage':
+        result = await cli.getUsage();
+        break;
+
+      case 'cronList':
+      case 'clawcontrol.cron.list':
+        result = cli.listCronJobs();
+        break;
+
+      case 'cronAdd':
+      case 'clawcontrol.cron.add':
+        result = cli.addCronJob(params.job);
+        break;
+
+      case 'cronUpdate':
+      case 'clawcontrol.cron.update':
+        result = cli.updateCronJob(params.id, params.patch);
+        break;
+
+      case 'cronRemove':
+      case 'clawcontrol.cron.remove':
+        result = cli.removeCronJob(params.id);
+        break;
+
+      case 'cronRun':
+      case 'clawcontrol.cron.run':
+        result = await cli.runCronJob(params.id);
+        break;
+
+      default:
+        success = false;
+        error = `Unknown action: ${action}`;
+    }
+  } catch (e: any) {
+    success = false;
+    error = e.message;
+  }
+
+  // 发送响应
+  console.log('[ClawControl] Sending response:', { id: requestId, success, result });
+  ws?.send(JSON.stringify({
+    type: 'response',
+    id: requestId,
+    success,
+    data: result,
+    error,
+  }));
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * ClawControl Plugin - Core
+ */
+
+export * from './cli.js';
+export * from './websocket.js';
+export * from './handlers.js';

package/src/websocket.ts

@@ -0,0 +1,182 @@
+/**
+ * WebSocket 连接管理
+ */
+
+import WebSocket from 'ws';
+import { handleBackendRequest, setWs } from './handlers.js';
+import * as chat from './chat.js';
+
+export interface ConnectionStatus {
+  connected: boolean;
+  lastConnectedAt: number | null;
+  lastDisconnect: { at: number; status: number; error?: string } | null;
+  lastError: string | null;
+}
+
+// 连接状态
+let connectionStatus: ConnectionStatus = {
+  connected: false,
+  lastConnectedAt: null,
+  lastDisconnect: null,
+  lastError: null,
+};
+
+// WebSocket 客户端实例
+let ws: WebSocket | null = null;
+
+// 重连相关
+let reconnectTimer: NodeJS.Timeout | null = null;
+let currentBackendUrl = '';
+let currentApiToken = '';
+let currentDeviceId = '';
+
+type StatusChangeCallback = (status: ConnectionStatus) => void;
+
+// 一个永远不 resolved 的 Promise，用于让 gateway 保持 channel 运行
+function neverResolve(): Promise<never> {
+  return new Promise(() => {});
+}
+
+export function startWebSocket(
+  backendUrl: string,
+  apiToken: string,
+  deviceId: string,
+  onStatusChange?: StatusChangeCallback
+): Promise<void> {
+  // 保存当前配置用于重连
+  currentBackendUrl = backendUrl;
+  currentApiToken = apiToken;
+  currentDeviceId = deviceId;
+
+  // 如果已有连接，先关闭
+  if (ws) {
+    ws.close();
+    ws = null;
+  }
+
+  return new Promise((resolve, reject) => {
+    const wsUrl = backendUrl.replace('http', 'ws') + '/ws';
+    ws = new WebSocket(wsUrl);
+
+    const timeout = setTimeout(() => {
+      reject(new Error('WebSocket connection timeout'));
+    }, 10000);
+
+    ws.on('open', () => {
+      clearTimeout(timeout);
+      console.log('[ClawControl] WebSocket connected');
+      connectionStatus = {
+        connected: true,
+        lastConnectedAt: Date.now(),
+        lastDisconnect: null,
+        lastError: null,
+      };
+      onStatusChange?.(connectionStatus);
+
+      // 设置 ws 实例供 handlers 使用
+      setWs(ws);
+      chat.setChatSendFn((msg) => ws?.send(JSON.stringify(msg)));
+
+      // 发送认证消息
+      ws?.send(JSON.stringify({
+        type: 'auth',
+        token: apiToken,
+        deviceId: deviceId || 'clawcontrol-plugin',
+        isPlugin: true,
+      }));
+      resolve();
+    });
+
+    ws.on('message', async (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        console.log('[ClawControl] Received message:', msg.type, msg.action || '');
+
+        // 处理 backend 发送的请求
+        if (msg.type === 'request' && msg.action) {
+          await handleBackendRequest(msg.action, msg.params, msg.id);
+        }
+      } catch {}
+    });
+
+    ws.on('close', (code, reason) => {
+      console.log('[ClawControl] WebSocket disconnected, code:', code);
+      const message = typeof reason === 'string' ? reason : (reason?.toString() || `code ${code}`);
+      connectionStatus = {
+        connected: false,
+        lastConnectedAt: connectionStatus.lastConnectedAt,
+        lastDisconnect: { at: Date.now(), status: code, error: message || undefined },
+        lastError: null,
+      };
+      onStatusChange?.(connectionStatus);
+
+      // 清除 ws 实例
+      setWs(null as any);
+      chat.setChatSendFn(() => {});
+
+      // 尝试重连
+      scheduleReconnect(onStatusChange);
+    });
+
+    ws.on('error', (error) => {
+      clearTimeout(timeout);
+      console.log('[ClawControl] WebSocket error:', error);
+      connectionStatus.lastError = 'WebSocket connection error';
+      onStatusChange?.(connectionStatus);
+      reject(new Error('WebSocket error'));
+    });
+  });
+}
+
+function scheduleReconnect(onStatusChange?: StatusChangeCallback) {
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+  }
+
+  reconnectTimer = setTimeout(() => {
+    if (currentBackendUrl && currentApiToken) {
+      console.log('[ClawControl] Attempting to reconnect...');
+      startWebSocket(currentBackendUrl, currentApiToken, currentDeviceId, onStatusChange)
+        .then(() => {
+          console.log('[ClawControl] Reconnected successfully');
+        })
+        .catch((err) => {
+          console.log('[ClawControl] Reconnect failed:', err.message);
+        });
+    }
+  }, 5000);
+}
+
+function stopReconnect() {
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+}
+
+export async function stopWebSocket(): Promise<void> {
+  stopReconnect();
+  if (ws) {
+    ws.close();
+    ws = null;
+  }
+  connectionStatus = {
+    connected: false,
+    lastConnectedAt: connectionStatus.lastConnectedAt,
+    lastDisconnect: { at: Date.now(), status: 1000, error: 'Manually stopped' },
+    lastError: null,
+  };
+  currentBackendUrl = '';
+  currentApiToken = '';
+  currentDeviceId = '';
+}
+
+export function getConnectionStatus() {
+  return connectionStatus;
+}
+
+export function getWs() {
+  return ws;
+}
+
+export { neverResolve };