Refactor clawx (#344)

Co-authored-by: ashione <skyzlxuan@gmail.com>
2026-03-09 13:10:42 +08:00
parent 3d804a9f5e
commit 2c5c82bb74
75 changed files with 7640 additions and 3106 deletions
--- a/electron/api/context.ts
+++ b/electron/api/context.ts
@@ -0,0 +1,11 @@
+import type { BrowserWindow } from 'electron';
+import type { GatewayManager } from '../gateway/manager';
+import type { ClawHubService } from '../gateway/clawhub';
+import type { HostEventBus } from './event-bus';
+
+export interface HostApiContext {
+  gatewayManager: GatewayManager;
+  clawHubService: ClawHubService;
+  eventBus: HostEventBus;
+  mainWindow: BrowserWindow | null;
+}
--- a/electron/api/event-bus.ts
+++ b/electron/api/event-bus.ts
@@ -0,0 +1,36 @@
+import type { ServerResponse } from 'http';
+
+type EventPayload = unknown;
+
+export class HostEventBus {
+  private readonly clients = new Set<ServerResponse>();
+
+  addSseClient(res: ServerResponse): void {
+    this.clients.add(res);
+    res.on('close', () => {
+      this.clients.delete(res);
+    });
+  }
+
+  emit(eventName: string, payload: EventPayload): void {
+    const message = `event: ${eventName}\ndata: ${JSON.stringify(payload)}\n\n`;
+    for (const client of this.clients) {
+      try {
+        client.write(message);
+      } catch {
+        this.clients.delete(client);
+      }
+    }
+  }
+
+  closeAll(): void {
+    for (const client of this.clients) {
+      try {
+        client.end();
+      } catch {
+        // Ignore individual client close failures.
+      }
+    }
+    this.clients.clear();
+  }
+}
--- a/electron/api/route-utils.ts
+++ b/electron/api/route-utils.ts
@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+
+export async function parseJsonBody<T>(req: IncomingMessage): Promise<T> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  if (!raw) {
+    return {} as T;
+  }
+  return JSON.parse(raw) as T;
+}
+
+export function setCorsHeaders(res: ServerResponse): void {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE,OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+}
+
+export function sendJson(res: ServerResponse, statusCode: number, payload: unknown): void {
+  setCorsHeaders(res);
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify(payload));
+}
+
+export function sendNoContent(res: ServerResponse): void {
+  setCorsHeaders(res);
+  res.statusCode = 204;
+  res.end();
+}
+
+export function sendText(res: ServerResponse, statusCode: number, text: string): void {
+  setCorsHeaders(res);
+  res.statusCode = statusCode;
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.end(text);
+}
--- a/electron/api/routes/app.ts
+++ b/electron/api/routes/app.ts
@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { HostApiContext } from '../context';
+import { setCorsHeaders, sendNoContent } from '../route-utils';
+
+export async function handleAppRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/events' && req.method === 'GET') {
+    setCorsHeaders(res);
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+    });
+    res.write(': connected\n\n');
+    ctx.eventBus.addSseClient(res);
+    // Send a current-state snapshot immediately so renderer subscribers do not
+    // miss lifecycle transitions that happened before the SSE connection opened.
+    res.write(`event: gateway:status\ndata: ${JSON.stringify(ctx.gatewayManager.getStatus())}\n\n`);
+    return true;
+  }
+
+  if (req.method === 'OPTIONS') {
+    sendNoContent(res);
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/channels.ts
+++ b/electron/api/routes/channels.ts
@@ -0,0 +1,167 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { app } from 'electron';
+import { existsSync, cpSync, mkdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  deleteChannelConfig,
+  getChannelFormValues,
+  listConfiguredChannels,
+  saveChannelConfig,
+  setChannelEnabled,
+  validateChannelConfig,
+  validateChannelCredentials,
+} from '../../utils/channel-config';
+import { whatsAppLoginManager } from '../../utils/whatsapp-login';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+async function ensureDingTalkPluginInstalled(): Promise<{ installed: boolean; warning?: string }> {
+  const targetDir = join(homedir(), '.openclaw', 'extensions', 'dingtalk');
+  const targetManifest = join(targetDir, 'openclaw.plugin.json');
+
+  if (existsSync(targetManifest)) {
+    return { installed: true };
+  }
+
+  const candidateSources = app.isPackaged
+    ? [
+      join(process.resourcesPath, 'openclaw-plugins', 'dingtalk'),
+      join(process.resourcesPath, 'app.asar.unpacked', 'build', 'openclaw-plugins', 'dingtalk'),
+      join(process.resourcesPath, 'app.asar.unpacked', 'openclaw-plugins', 'dingtalk'),
+    ]
+    : [
+      join(app.getAppPath(), 'build', 'openclaw-plugins', 'dingtalk'),
+      join(process.cwd(), 'build', 'openclaw-plugins', 'dingtalk'),
+      join(__dirname, '../../../build/openclaw-plugins/dingtalk'),
+    ];
+
+  const sourceDir = candidateSources.find((dir) => existsSync(join(dir, 'openclaw.plugin.json')));
+  if (!sourceDir) {
+    return {
+      installed: false,
+      warning: `Bundled DingTalk plugin mirror not found. Checked: ${candidateSources.join(' | ')}`,
+    };
+  }
+
+  try {
+    mkdirSync(join(homedir(), '.openclaw', 'extensions'), { recursive: true });
+    rmSync(targetDir, { recursive: true, force: true });
+    cpSync(sourceDir, targetDir, { recursive: true, dereference: true });
+    if (!existsSync(targetManifest)) {
+      return { installed: false, warning: 'Failed to install DingTalk plugin mirror (manifest missing).' };
+    }
+    return { installed: true };
+  } catch {
+    return { installed: false, warning: 'Failed to install bundled DingTalk plugin mirror' };
+  }
+}
+
+export async function handleChannelRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/channels/configured' && req.method === 'GET') {
+    sendJson(res, 200, { success: true, channels: await listConfiguredChannels() });
+    return true;
+  }
+
+  if (url.pathname === '/api/channels/config/validate' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ channelType: string }>(req);
+      sendJson(res, 200, { success: true, ...(await validateChannelConfig(body.channelType)) });
+    } catch (error) {
+      sendJson(res, 500, { success: false, valid: false, errors: [String(error)], warnings: [] });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/channels/credentials/validate' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ channelType: string; config: Record<string, string> }>(req);
+      sendJson(res, 200, { success: true, ...(await validateChannelCredentials(body.channelType, body.config)) });
+    } catch (error) {
+      sendJson(res, 500, { success: false, valid: false, errors: [String(error)], warnings: [] });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/channels/whatsapp/start' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ accountId: string }>(req);
+      await whatsAppLoginManager.start(body.accountId);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/channels/whatsapp/cancel' && req.method === 'POST') {
+    try {
+      await whatsAppLoginManager.stop();
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/channels/config' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ channelType: string; config: Record<string, unknown> }>(req);
+      if (body.channelType === 'dingtalk') {
+        const installResult = await ensureDingTalkPluginInstalled();
+        if (!installResult.installed) {
+          sendJson(res, 500, { success: false, error: installResult.warning || 'DingTalk plugin install failed' });
+          return true;
+        }
+      }
+      await saveChannelConfig(body.channelType, body.config);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/channels/config/enabled' && req.method === 'PUT') {
+    try {
+      const body = await parseJsonBody<{ channelType: string; enabled: boolean }>(req);
+      await setChannelEnabled(body.channelType, body.enabled);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/channels/config/') && req.method === 'GET') {
+    try {
+      const channelType = decodeURIComponent(url.pathname.slice('/api/channels/config/'.length));
+      sendJson(res, 200, {
+        success: true,
+        values: await getChannelFormValues(channelType),
+      });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/channels/config/') && req.method === 'DELETE') {
+    try {
+      const channelType = decodeURIComponent(url.pathname.slice('/api/channels/config/'.length));
+      await deleteChannelConfig(channelType);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  void ctx;
+  return false;
+}
--- a/electron/api/routes/cron.ts
+++ b/electron/api/routes/cron.ts
@@ -0,0 +1,168 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+interface GatewayCronJob {
+  id: string;
+  name: string;
+  description?: string;
+  enabled: boolean;
+  createdAtMs: number;
+  updatedAtMs: number;
+  schedule: { kind: string; expr?: string; everyMs?: number; at?: string; tz?: string };
+  payload: { kind: string; message?: string; text?: string };
+  delivery?: { mode: string; channel?: string; to?: string };
+  sessionTarget?: string;
+  state: {
+    nextRunAtMs?: number;
+    lastRunAtMs?: number;
+    lastStatus?: string;
+    lastError?: string;
+    lastDurationMs?: number;
+  };
+}
+
+function transformCronJob(job: GatewayCronJob) {
+  const message = job.payload?.message || job.payload?.text || '';
+  const channelType = job.delivery?.channel;
+  const target = channelType
+    ? { channelType, channelId: channelType, channelName: channelType }
+    : undefined;
+  const lastRun = job.state?.lastRunAtMs
+    ? {
+      time: new Date(job.state.lastRunAtMs).toISOString(),
+      success: job.state.lastStatus === 'ok',
+      error: job.state.lastError,
+      duration: job.state.lastDurationMs,
+    }
+    : undefined;
+  const nextRun = job.state?.nextRunAtMs
+    ? new Date(job.state.nextRunAtMs).toISOString()
+    : undefined;
+
+  return {
+    id: job.id,
+    name: job.name,
+    message,
+    schedule: job.schedule,
+    target,
+    enabled: job.enabled,
+    createdAt: new Date(job.createdAtMs).toISOString(),
+    updatedAt: new Date(job.updatedAtMs).toISOString(),
+    lastRun,
+    nextRun,
+  };
+}
+
+export async function handleCronRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/cron/jobs' && req.method === 'GET') {
+    try {
+      const result = await ctx.gatewayManager.rpc('cron.list', { includeDisabled: true });
+      const data = result as { jobs?: GatewayCronJob[] };
+      const jobs = data?.jobs ?? [];
+      for (const job of jobs) {
+        const isIsolatedAgent =
+          (job.sessionTarget === 'isolated' || !job.sessionTarget) &&
+          job.payload?.kind === 'agentTurn';
+        const needsRepair =
+          isIsolatedAgent &&
+          job.delivery?.mode === 'announce' &&
+          !job.delivery?.channel;
+        if (needsRepair) {
+          try {
+            await ctx.gatewayManager.rpc('cron.update', {
+              id: job.id,
+              patch: { delivery: { mode: 'none' } },
+            });
+            job.delivery = { mode: 'none' };
+            if (job.state?.lastError?.includes('Channel is required')) {
+              job.state.lastError = undefined;
+              job.state.lastStatus = 'ok';
+            }
+          } catch {
+            // ignore per-job repair failure
+          }
+        }
+      }
+      sendJson(res, 200, jobs.map(transformCronJob));
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/cron/jobs' && req.method === 'POST') {
+    try {
+      const input = await parseJsonBody<{ name: string; message: string; schedule: string; enabled?: boolean }>(req);
+      const result = await ctx.gatewayManager.rpc('cron.add', {
+        name: input.name,
+        schedule: { kind: 'cron', expr: input.schedule },
+        payload: { kind: 'agentTurn', message: input.message },
+        enabled: input.enabled ?? true,
+        wakeMode: 'next-heartbeat',
+        sessionTarget: 'isolated',
+        delivery: { mode: 'none' },
+      });
+      sendJson(res, 200, result && typeof result === 'object' ? transformCronJob(result as GatewayCronJob) : result);
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/cron/jobs/') && req.method === 'PUT') {
+    try {
+      const id = decodeURIComponent(url.pathname.slice('/api/cron/jobs/'.length));
+      const input = await parseJsonBody<Record<string, unknown>>(req);
+      const patch = { ...input };
+      if (typeof patch.schedule === 'string') {
+        patch.schedule = { kind: 'cron', expr: patch.schedule };
+      }
+      if (typeof patch.message === 'string') {
+        patch.payload = { kind: 'agentTurn', message: patch.message };
+        delete patch.message;
+      }
+      sendJson(res, 200, await ctx.gatewayManager.rpc('cron.update', { id, patch }));
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/cron/jobs/') && req.method === 'DELETE') {
+    try {
+      const id = decodeURIComponent(url.pathname.slice('/api/cron/jobs/'.length));
+      sendJson(res, 200, await ctx.gatewayManager.rpc('cron.remove', { id }));
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/cron/toggle' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ id: string; enabled: boolean }>(req);
+      sendJson(res, 200, await ctx.gatewayManager.rpc('cron.update', { id: body.id, patch: { enabled: body.enabled } }));
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/cron/trigger' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ id: string }>(req);
+      sendJson(res, 200, await ctx.gatewayManager.rpc('cron.run', { id: body.id, mode: 'force' }));
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/files.ts
+++ b/electron/api/routes/files.ts
@@ -0,0 +1,200 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { dialog, nativeImage } from 'electron';
+import crypto from 'node:crypto';
+import { extname, join } from 'node:path';
+import { homedir } from 'node:os';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+const EXT_MIME_MAP: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.bmp': 'image/bmp',
+  '.ico': 'image/x-icon',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+  '.avi': 'video/x-msvideo',
+  '.mkv': 'video/x-matroska',
+  '.mp3': 'audio/mpeg',
+  '.wav': 'audio/wav',
+  '.ogg': 'audio/ogg',
+  '.flac': 'audio/flac',
+  '.pdf': 'application/pdf',
+  '.zip': 'application/zip',
+  '.gz': 'application/gzip',
+  '.tar': 'application/x-tar',
+  '.7z': 'application/x-7z-compressed',
+  '.rar': 'application/vnd.rar',
+  '.json': 'application/json',
+  '.xml': 'application/xml',
+  '.csv': 'text/csv',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.ts': 'text/typescript',
+  '.py': 'text/x-python',
+};
+
+function getMimeType(ext: string): string {
+  return EXT_MIME_MAP[ext.toLowerCase()] || 'application/octet-stream';
+}
+
+function mimeToExt(mimeType: string): string {
+  for (const [ext, mime] of Object.entries(EXT_MIME_MAP)) {
+    if (mime === mimeType) return ext;
+  }
+  return '';
+}
+
+const OUTBOUND_DIR = join(homedir(), '.openclaw', 'media', 'outbound');
+
+async function generateImagePreview(filePath: string, mimeType: string): Promise<string | null> {
+  try {
+    const img = nativeImage.createFromPath(filePath);
+    if (img.isEmpty()) return null;
+    const size = img.getSize();
+    const maxDim = 512;
+    if (size.width > maxDim || size.height > maxDim) {
+      const resized = size.width >= size.height
+        ? img.resize({ width: maxDim })
+        : img.resize({ height: maxDim });
+      return `data:image/png;base64,${resized.toPNG().toString('base64')}`;
+    }
+    const { readFile } = await import('node:fs/promises');
+    const buf = await readFile(filePath);
+    return `data:${mimeType};base64,${buf.toString('base64')}`;
+  } catch {
+    return null;
+  }
+}
+
+export async function handleFileRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  _ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/files/stage-paths' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ filePaths: string[] }>(req);
+      const fsP = await import('node:fs/promises');
+      await fsP.mkdir(OUTBOUND_DIR, { recursive: true });
+      const results = [];
+      for (const filePath of body.filePaths) {
+        const id = crypto.randomUUID();
+        const ext = extname(filePath);
+        const stagedPath = join(OUTBOUND_DIR, `${id}${ext}`);
+        await fsP.copyFile(filePath, stagedPath);
+        const s = await fsP.stat(stagedPath);
+        const mimeType = getMimeType(ext);
+        const fileName = filePath.split(/[\\/]/).pop() || 'file';
+        const preview = mimeType.startsWith('image/')
+          ? await generateImagePreview(stagedPath, mimeType)
+          : null;
+        results.push({ id, fileName, mimeType, fileSize: s.size, stagedPath, preview });
+      }
+      sendJson(res, 200, results);
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/files/stage-buffer' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ base64: string; fileName: string; mimeType: string }>(req);
+      const fsP = await import('node:fs/promises');
+      await fsP.mkdir(OUTBOUND_DIR, { recursive: true });
+      const id = crypto.randomUUID();
+      const ext = extname(body.fileName) || mimeToExt(body.mimeType);
+      const stagedPath = join(OUTBOUND_DIR, `${id}${ext}`);
+      const buffer = Buffer.from(body.base64, 'base64');
+      await fsP.writeFile(stagedPath, buffer);
+      const mimeType = body.mimeType || getMimeType(ext);
+      const preview = mimeType.startsWith('image/')
+        ? await generateImagePreview(stagedPath, mimeType)
+        : null;
+      sendJson(res, 200, {
+        id,
+        fileName: body.fileName,
+        mimeType,
+        fileSize: buffer.length,
+        stagedPath,
+        preview,
+      });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/files/thumbnails' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ paths: Array<{ filePath: string; mimeType: string }> }>(req);
+      const fsP = await import('node:fs/promises');
+      const results: Record<string, { preview: string | null; fileSize: number }> = {};
+      for (const { filePath, mimeType } of body.paths) {
+        try {
+          const s = await fsP.stat(filePath);
+          const preview = mimeType.startsWith('image/')
+            ? await generateImagePreview(filePath, mimeType)
+            : null;
+          results[filePath] = { preview, fileSize: s.size };
+        } catch {
+          results[filePath] = { preview: null, fileSize: 0 };
+        }
+      }
+      sendJson(res, 200, results);
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/files/save-image' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{
+        base64?: string;
+        mimeType?: string;
+        filePath?: string;
+        defaultFileName: string;
+      }>(req);
+      const ext = body.defaultFileName.includes('.')
+        ? body.defaultFileName.split('.').pop()!
+        : (body.mimeType?.split('/')[1] || 'png');
+      const result = await dialog.showSaveDialog({
+        defaultPath: join(homedir(), 'Downloads', body.defaultFileName),
+        filters: [
+          { name: 'Images', extensions: [ext, 'png', 'jpg', 'jpeg', 'webp', 'gif'] },
+          { name: 'All Files', extensions: ['*'] },
+        ],
+      });
+      if (result.canceled || !result.filePath) {
+        sendJson(res, 200, { success: false });
+        return true;
+      }
+      const fsP = await import('node:fs/promises');
+      if (body.filePath) {
+        await fsP.copyFile(body.filePath, result.filePath);
+      } else if (body.base64) {
+        await fsP.writeFile(result.filePath, Buffer.from(body.base64, 'base64'));
+      } else {
+        sendJson(res, 400, { success: false, error: 'No image data provided' });
+        return true;
+      }
+      sendJson(res, 200, { success: true, savedPath: result.filePath });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/gateway.ts
+++ b/electron/api/routes/gateway.ts
@@ -0,0 +1,129 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { PORTS } from '../../utils/config';
+import { getSetting } from '../../utils/store';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+export async function handleGatewayRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/app/gateway-info' && req.method === 'GET') {
+    const status = ctx.gatewayManager.getStatus();
+    const token = await getSetting('gatewayToken');
+    const port = status.port || PORTS.OPENCLAW_GATEWAY;
+    sendJson(res, 200, {
+      wsUrl: `ws://127.0.0.1:${port}/ws`,
+      token,
+      port,
+    });
+    return true;
+  }
+
+  if (url.pathname === '/api/gateway/status' && req.method === 'GET') {
+    sendJson(res, 200, ctx.gatewayManager.getStatus());
+    return true;
+  }
+
+  if (url.pathname === '/api/gateway/health' && req.method === 'GET') {
+    const health = await ctx.gatewayManager.checkHealth();
+    sendJson(res, 200, health);
+    return true;
+  }
+
+  if (url.pathname === '/api/gateway/start' && req.method === 'POST') {
+    try {
+      await ctx.gatewayManager.start();
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/gateway/stop' && req.method === 'POST') {
+    try {
+      await ctx.gatewayManager.stop();
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/gateway/restart' && req.method === 'POST') {
+    try {
+      await ctx.gatewayManager.restart();
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/gateway/control-ui' && req.method === 'GET') {
+    try {
+      const status = ctx.gatewayManager.getStatus();
+      const token = await getSetting('gatewayToken');
+      const port = status.port || PORTS.OPENCLAW_GATEWAY;
+      const urlValue = `http://127.0.0.1:${port}/?token=${encodeURIComponent(token)}`;
+      sendJson(res, 200, { success: true, url: urlValue, token, port });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/chat/send-with-media' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{
+        sessionKey: string;
+        message: string;
+        deliver?: boolean;
+        idempotencyKey: string;
+        media?: Array<{ filePath: string; mimeType: string; fileName: string }>;
+      }>(req);
+      const VISION_MIME_TYPES = new Set([
+        'image/png', 'image/jpeg', 'image/bmp', 'image/webp',
+      ]);
+      const imageAttachments: Array<{ content: string; mimeType: string; fileName: string }> = [];
+      const fileReferences: string[] = [];
+      if (body.media && body.media.length > 0) {
+        const fsP = await import('node:fs/promises');
+        for (const m of body.media) {
+          fileReferences.push(`[media attached: ${m.filePath} (${m.mimeType}) | ${m.filePath}]`);
+          if (VISION_MIME_TYPES.has(m.mimeType)) {
+            const fileBuffer = await fsP.readFile(m.filePath);
+            imageAttachments.push({
+              content: fileBuffer.toString('base64'),
+              mimeType: m.mimeType,
+              fileName: m.fileName,
+            });
+          }
+        }
+      }
+
+      const message = fileReferences.length > 0
+        ? [body.message, ...fileReferences].filter(Boolean).join('\n')
+        : body.message;
+      const rpcParams: Record<string, unknown> = {
+        sessionKey: body.sessionKey,
+        message,
+        deliver: body.deliver ?? false,
+        idempotencyKey: body.idempotencyKey,
+      };
+      if (imageAttachments.length > 0) {
+        rpcParams.attachments = imageAttachments;
+      }
+      const result = await ctx.gatewayManager.rpc('chat.send', rpcParams, 120000);
+      sendJson(res, 200, { success: true, result });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/logs.ts
+++ b/electron/api/routes/logs.ts
@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { logger } from '../../utils/logger';
+import type { HostApiContext } from '../context';
+import { sendJson } from '../route-utils';
+
+export async function handleLogRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  _ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/logs' && req.method === 'GET') {
+    const tailLines = Number(url.searchParams.get('tailLines') || '100');
+    sendJson(res, 200, { content: await logger.readLogFile(Number.isFinite(tailLines) ? tailLines : 100) });
+    return true;
+  }
+
+  if (url.pathname === '/api/logs/dir' && req.method === 'GET') {
+    sendJson(res, 200, { dir: logger.getLogDir() });
+    return true;
+  }
+
+  if (url.pathname === '/api/logs/files' && req.method === 'GET') {
+    sendJson(res, 200, { files: await logger.listLogFiles() });
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/providers.ts
+++ b/electron/api/routes/providers.ts
@@ -0,0 +1,295 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import {
+  deleteApiKey,
+  deleteProvider,
+  getAllProvidersWithKeyInfo,
+  getApiKey,
+  getDefaultProvider,
+  getProvider,
+  hasApiKey,
+  saveProvider,
+  setDefaultProvider,
+  storeApiKey,
+  type ProviderConfig,
+} from '../../utils/secure-storage';
+import {
+  getProviderConfig,
+} from '../../utils/provider-registry';
+import { deviceOAuthManager, type OAuthProviderType } from '../../utils/device-oauth';
+import { browserOAuthManager, type BrowserOAuthProviderType } from '../../utils/browser-oauth';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+import {
+  syncDefaultProviderToRuntime,
+  syncDeletedProviderApiKeyToRuntime,
+  syncDeletedProviderToRuntime,
+  syncProviderApiKeyToRuntime,
+  syncSavedProviderToRuntime,
+  syncUpdatedProviderToRuntime,
+} from '../../services/providers/provider-runtime-sync';
+import { validateApiKeyWithProvider } from '../../services/providers/provider-validation';
+import { getProviderService } from '../../services/providers/provider-service';
+import { providerAccountToConfig } from '../../services/providers/provider-store';
+import type { ProviderAccount } from '../../shared/providers/types';
+
+export async function handleProviderRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  const providerService = getProviderService();
+
+  if (url.pathname === '/api/provider-vendors' && req.method === 'GET') {
+    sendJson(res, 200, await providerService.listVendors());
+    return true;
+  }
+
+  if (url.pathname === '/api/provider-accounts' && req.method === 'GET') {
+    sendJson(res, 200, await providerService.listAccounts());
+    return true;
+  }
+
+  if (url.pathname === '/api/provider-accounts' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ account: ProviderAccount; apiKey?: string }>(req);
+      const account = await providerService.createAccount(body.account, body.apiKey);
+      await syncSavedProviderToRuntime(providerAccountToConfig(account), body.apiKey, ctx.gatewayManager);
+      sendJson(res, 200, { success: true, account });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/provider-accounts/default' && req.method === 'GET') {
+    sendJson(res, 200, { accountId: await providerService.getDefaultAccountId() ?? null });
+    return true;
+  }
+
+  if (url.pathname === '/api/provider-accounts/default' && req.method === 'PUT') {
+    try {
+      const body = await parseJsonBody<{ accountId: string }>(req);
+      await providerService.setDefaultAccount(body.accountId);
+      await syncDefaultProviderToRuntime(body.accountId, ctx.gatewayManager);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/provider-accounts/') && req.method === 'GET') {
+    const accountId = decodeURIComponent(url.pathname.slice('/api/provider-accounts/'.length));
+    sendJson(res, 200, await providerService.getAccount(accountId));
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/provider-accounts/') && req.method === 'PUT') {
+    const accountId = decodeURIComponent(url.pathname.slice('/api/provider-accounts/'.length));
+    try {
+      const body = await parseJsonBody<{ updates: Partial<ProviderAccount>; apiKey?: string }>(req);
+      const existing = await providerService.getAccount(accountId);
+      if (!existing) {
+        sendJson(res, 404, { success: false, error: 'Provider account not found' });
+        return true;
+      }
+      const nextAccount = await providerService.updateAccount(accountId, body.updates, body.apiKey);
+      await syncUpdatedProviderToRuntime(providerAccountToConfig(nextAccount), body.apiKey, ctx.gatewayManager);
+      sendJson(res, 200, { success: true, account: nextAccount });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/provider-accounts/') && req.method === 'DELETE') {
+    const accountId = decodeURIComponent(url.pathname.slice('/api/provider-accounts/'.length));
+    try {
+      const existing = await providerService.getAccount(accountId);
+      const runtimeProviderKey = existing?.vendorId === 'google' && existing.authMode === 'oauth_browser'
+        ? 'google-gemini-cli'
+        : undefined;
+      if (url.searchParams.get('apiKeyOnly') === '1') {
+        await providerService.deleteLegacyProviderApiKey(accountId);
+        await syncDeletedProviderApiKeyToRuntime(
+          existing ? providerAccountToConfig(existing) : null,
+          accountId,
+          runtimeProviderKey,
+        );
+        sendJson(res, 200, { success: true });
+        return true;
+      }
+      await providerService.deleteAccount(accountId);
+      await syncDeletedProviderToRuntime(
+        existing ? providerAccountToConfig(existing) : null,
+        accountId,
+        ctx.gatewayManager,
+        runtimeProviderKey,
+      );
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/providers' && req.method === 'GET') {
+    sendJson(res, 200, await getAllProvidersWithKeyInfo());
+    return true;
+  }
+
+  if (url.pathname === '/api/providers/default' && req.method === 'GET') {
+    sendJson(res, 200, { providerId: await getDefaultProvider() ?? null });
+    return true;
+  }
+
+  if (url.pathname === '/api/providers/default' && req.method === 'PUT') {
+    try {
+      const body = await parseJsonBody<{ providerId: string }>(req);
+      await setDefaultProvider(body.providerId);
+      await syncDefaultProviderToRuntime(body.providerId, ctx.gatewayManager);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/providers/validate' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ providerId: string; apiKey: string; options?: { baseUrl?: string } }>(req);
+      const provider = await getProvider(body.providerId);
+      const providerType = provider?.type || body.providerId;
+      const registryBaseUrl = getProviderConfig(providerType)?.baseUrl;
+      const resolvedBaseUrl = body.options?.baseUrl || provider?.baseUrl || registryBaseUrl;
+      sendJson(res, 200, await validateApiKeyWithProvider(providerType, body.apiKey, { baseUrl: resolvedBaseUrl }));
+    } catch (error) {
+      sendJson(res, 500, { valid: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/providers/oauth/start' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{
+        provider: OAuthProviderType | BrowserOAuthProviderType;
+        region?: 'global' | 'cn';
+        accountId?: string;
+        label?: string;
+      }>(req);
+      if (body.provider === 'google') {
+        await browserOAuthManager.startFlow(body.provider, {
+          accountId: body.accountId,
+          label: body.label,
+        });
+      } else {
+        await deviceOAuthManager.startFlow(body.provider, body.region, {
+          accountId: body.accountId,
+          label: body.label,
+        });
+      }
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/providers/oauth/cancel' && req.method === 'POST') {
+    try {
+      await deviceOAuthManager.stopFlow();
+      await browserOAuthManager.stopFlow();
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/providers' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ config: ProviderConfig; apiKey?: string }>(req);
+      const config = body.config;
+      await saveProvider(config);
+      if (body.apiKey !== undefined) {
+        const trimmedKey = body.apiKey.trim();
+        if (trimmedKey) {
+          await storeApiKey(config.id, trimmedKey);
+          await syncProviderApiKeyToRuntime(config.type, config.id, trimmedKey);
+        }
+      }
+      await syncSavedProviderToRuntime(config, body.apiKey, ctx.gatewayManager);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/providers/') && req.method === 'GET') {
+    const providerId = decodeURIComponent(url.pathname.slice('/api/providers/'.length));
+    if (providerId.endsWith('/api-key')) {
+      const actualId = providerId.slice(0, -('/api-key'.length));
+      sendJson(res, 200, { apiKey: await getApiKey(actualId) });
+      return true;
+    }
+    if (providerId.endsWith('/has-api-key')) {
+      const actualId = providerId.slice(0, -('/has-api-key'.length));
+      sendJson(res, 200, { hasKey: await hasApiKey(actualId) });
+      return true;
+    }
+    sendJson(res, 200, await getProvider(providerId));
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/providers/') && req.method === 'PUT') {
+    const providerId = decodeURIComponent(url.pathname.slice('/api/providers/'.length));
+    try {
+      const body = await parseJsonBody<{ updates: Partial<ProviderConfig>; apiKey?: string }>(req);
+      const existing = await getProvider(providerId);
+      if (!existing) {
+        sendJson(res, 404, { success: false, error: 'Provider not found' });
+        return true;
+      }
+      const nextConfig: ProviderConfig = { ...existing, ...body.updates, updatedAt: new Date().toISOString() };
+      await saveProvider(nextConfig);
+      if (body.apiKey !== undefined) {
+        const trimmedKey = body.apiKey.trim();
+        if (trimmedKey) {
+          await storeApiKey(providerId, trimmedKey);
+          await syncProviderApiKeyToRuntime(nextConfig.type, providerId, trimmedKey);
+        } else {
+          await deleteApiKey(providerId);
+          await syncDeletedProviderApiKeyToRuntime(existing, providerId);
+        }
+      }
+      await syncUpdatedProviderToRuntime(nextConfig, body.apiKey, ctx.gatewayManager);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/providers/') && req.method === 'DELETE') {
+    const providerId = decodeURIComponent(url.pathname.slice('/api/providers/'.length));
+    try {
+      const existing = await getProvider(providerId);
+      if (url.searchParams.get('apiKeyOnly') === '1') {
+        await deleteApiKey(providerId);
+        await syncDeletedProviderApiKeyToRuntime(existing, providerId);
+        sendJson(res, 200, { success: true });
+        return true;
+      }
+      await deleteProvider(providerId);
+      await syncDeletedProviderToRuntime(existing, providerId, ctx.gatewayManager);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/sessions.ts
+++ b/electron/api/routes/sessions.ts
@@ -0,0 +1,96 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { join } from 'node:path';
+import { getOpenClawConfigDir } from '../../utils/paths';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+export async function handleSessionRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  _ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/sessions/delete' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ sessionKey: string }>(req);
+      const sessionKey = body.sessionKey;
+      if (!sessionKey || !sessionKey.startsWith('agent:')) {
+        sendJson(res, 400, { success: false, error: `Invalid sessionKey: ${sessionKey}` });
+        return true;
+      }
+      const parts = sessionKey.split(':');
+      if (parts.length < 3) {
+        sendJson(res, 400, { success: false, error: `sessionKey has too few parts: ${sessionKey}` });
+        return true;
+      }
+      const agentId = parts[1];
+      const sessionsDir = join(getOpenClawConfigDir(), 'agents', agentId, 'sessions');
+      const sessionsJsonPath = join(sessionsDir, 'sessions.json');
+      const fsP = await import('node:fs/promises');
+      const raw = await fsP.readFile(sessionsJsonPath, 'utf8');
+      const sessionsJson = JSON.parse(raw) as Record<string, unknown>;
+
+      let uuidFileName: string | undefined;
+      let resolvedSrcPath: string | undefined;
+      if (Array.isArray(sessionsJson.sessions)) {
+        const entry = (sessionsJson.sessions as Array<Record<string, unknown>>)
+          .find((s) => s.key === sessionKey || s.sessionKey === sessionKey);
+        if (entry) {
+          uuidFileName = (entry.file ?? entry.fileName ?? entry.path) as string | undefined;
+          if (!uuidFileName && typeof entry.id === 'string') {
+            uuidFileName = `${entry.id}.jsonl`;
+          }
+        }
+      }
+      if (!uuidFileName && sessionsJson[sessionKey] != null) {
+        const val = sessionsJson[sessionKey];
+        if (typeof val === 'string') {
+          uuidFileName = val;
+        } else if (typeof val === 'object' && val !== null) {
+          const entry = val as Record<string, unknown>;
+          const absFile = (entry.sessionFile ?? entry.file ?? entry.fileName ?? entry.path) as string | undefined;
+          if (absFile) {
+            if (absFile.startsWith('/') || absFile.match(/^[A-Za-z]:\\/)) {
+              resolvedSrcPath = absFile;
+            } else {
+              uuidFileName = absFile;
+            }
+          } else {
+            const uuidVal = (entry.id ?? entry.sessionId) as string | undefined;
+            if (uuidVal) uuidFileName = uuidVal.endsWith('.jsonl') ? uuidVal : `${uuidVal}.jsonl`;
+          }
+        }
+      }
+      if (!uuidFileName && !resolvedSrcPath) {
+        sendJson(res, 404, { success: false, error: `Cannot resolve file for session: ${sessionKey}` });
+        return true;
+      }
+      if (!resolvedSrcPath) {
+        if (!uuidFileName!.endsWith('.jsonl')) uuidFileName = `${uuidFileName}.jsonl`;
+        resolvedSrcPath = join(sessionsDir, uuidFileName!);
+      }
+      const dstPath = resolvedSrcPath.replace(/\.jsonl$/, '.deleted.jsonl');
+      try {
+        await fsP.access(resolvedSrcPath);
+        await fsP.rename(resolvedSrcPath, dstPath);
+      } catch {
+        // Non-fatal; still try to update sessions.json.
+      }
+      const raw2 = await fsP.readFile(sessionsJsonPath, 'utf8');
+      const json2 = JSON.parse(raw2) as Record<string, unknown>;
+      if (Array.isArray(json2.sessions)) {
+        json2.sessions = (json2.sessions as Array<Record<string, unknown>>)
+          .filter((s) => s.key !== sessionKey && s.sessionKey !== sessionKey);
+      } else if (json2[sessionKey]) {
+        delete json2[sessionKey];
+      }
+      await fsP.writeFile(sessionsJsonPath, JSON.stringify(json2, null, 2), 'utf8');
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/settings.ts
+++ b/electron/api/routes/settings.ts
@@ -0,0 +1,98 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { applyProxySettings } from '../../main/proxy';
+import { getAllSettings, getSetting, resetSettings, setSetting, type AppSettings } from '../../utils/store';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+async function handleProxySettingsChange(ctx: HostApiContext): Promise<void> {
+  const settings = await getAllSettings();
+  await applyProxySettings(settings);
+  if (ctx.gatewayManager.getStatus().state === 'running') {
+    await ctx.gatewayManager.restart();
+  }
+}
+
+function patchTouchesProxy(patch: Partial<AppSettings>): boolean {
+  return Object.keys(patch).some((key) => (
+    key === 'proxyEnabled' ||
+    key === 'proxyServer' ||
+    key === 'proxyHttpServer' ||
+    key === 'proxyHttpsServer' ||
+    key === 'proxyAllServer' ||
+    key === 'proxyBypassRules'
+  ));
+}
+
+export async function handleSettingsRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/settings' && req.method === 'GET') {
+    sendJson(res, 200, await getAllSettings());
+    return true;
+  }
+
+  if (url.pathname === '/api/settings' && req.method === 'PUT') {
+    try {
+      const patch = await parseJsonBody<Partial<AppSettings>>(req);
+      const entries = Object.entries(patch) as Array<[keyof AppSettings, AppSettings[keyof AppSettings]]>;
+      for (const [key, value] of entries) {
+        await setSetting(key, value);
+      }
+      if (patchTouchesProxy(patch)) {
+        await handleProxySettingsChange(ctx);
+      }
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/settings/') && req.method === 'GET') {
+    const key = url.pathname.slice('/api/settings/'.length) as keyof AppSettings;
+    try {
+      sendJson(res, 200, { value: await getSetting(key) });
+    } catch (error) {
+      sendJson(res, 404, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname.startsWith('/api/settings/') && req.method === 'PUT') {
+    const key = url.pathname.slice('/api/settings/'.length) as keyof AppSettings;
+    try {
+      const body = await parseJsonBody<{ value: AppSettings[keyof AppSettings] }>(req);
+      await setSetting(key, body.value);
+      if (
+        key === 'proxyEnabled' ||
+        key === 'proxyServer' ||
+        key === 'proxyHttpServer' ||
+        key === 'proxyHttpsServer' ||
+        key === 'proxyAllServer' ||
+        key === 'proxyBypassRules'
+      ) {
+        await handleProxySettingsChange(ctx);
+      }
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/settings/reset' && req.method === 'POST') {
+    try {
+      await resetSettings();
+      await handleProxySettingsChange(ctx);
+      sendJson(res, 200, { success: true, settings: await getAllSettings() });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/skills.ts
+++ b/electron/api/routes/skills.ts
@@ -0,0 +1,90 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { getAllSkillConfigs, updateSkillConfig } from '../../utils/skill-config';
+import type { HostApiContext } from '../context';
+import { parseJsonBody, sendJson } from '../route-utils';
+
+export async function handleSkillRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/skills/configs' && req.method === 'GET') {
+    sendJson(res, 200, await getAllSkillConfigs());
+    return true;
+  }
+
+  if (url.pathname === '/api/skills/config' && req.method === 'PUT') {
+    try {
+      const body = await parseJsonBody<{
+        skillKey: string;
+        apiKey?: string;
+        env?: Record<string, string>;
+      }>(req);
+      sendJson(res, 200, await updateSkillConfig(body.skillKey, {
+        apiKey: body.apiKey,
+        env: body.env,
+      }));
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/clawhub/search' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<Record<string, unknown>>(req);
+      sendJson(res, 200, {
+        success: true,
+        results: await ctx.clawHubService.search(body),
+      });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/clawhub/install' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<Record<string, unknown>>(req);
+      await ctx.clawHubService.install(body);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/clawhub/uninstall' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<Record<string, unknown>>(req);
+      await ctx.clawHubService.uninstall(body);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/clawhub/list' && req.method === 'GET') {
+    try {
+      sendJson(res, 200, { success: true, results: await ctx.clawHubService.listInstalled() });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  if (url.pathname === '/api/clawhub/open-readme' && req.method === 'POST') {
+    try {
+      const body = await parseJsonBody<{ slug: string }>(req);
+      await ctx.clawHubService.openSkillReadme(body.slug);
+      sendJson(res, 200, { success: true });
+    } catch (error) {
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/routes/usage.ts
+++ b/electron/api/routes/usage.ts
@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from 'http';
+import { getRecentTokenUsageHistory } from '../../utils/token-usage';
+import type { HostApiContext } from '../context';
+import { sendJson } from '../route-utils';
+
+export async function handleUsageRoutes(
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  _ctx: HostApiContext,
+): Promise<boolean> {
+  if (url.pathname === '/api/usage/recent-token-history' && req.method === 'GET') {
+    const parsedLimit = Number(url.searchParams.get('limit') || '');
+    const limit = Number.isFinite(parsedLimit) ? Math.max(Math.floor(parsedLimit), 1) : undefined;
+    sendJson(res, 200, await getRecentTokenUsageHistory(limit));
+    return true;
+  }
+
+  return false;
+}
--- a/electron/api/server.ts
+++ b/electron/api/server.ts
@@ -0,0 +1,60 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { PORTS } from '../utils/config';
+import { logger } from '../utils/logger';
+import type { HostApiContext } from './context';
+import { handleAppRoutes } from './routes/app';
+import { handleGatewayRoutes } from './routes/gateway';
+import { handleSettingsRoutes } from './routes/settings';
+import { handleProviderRoutes } from './routes/providers';
+import { handleChannelRoutes } from './routes/channels';
+import { handleLogRoutes } from './routes/logs';
+import { handleUsageRoutes } from './routes/usage';
+import { handleSkillRoutes } from './routes/skills';
+import { handleFileRoutes } from './routes/files';
+import { handleSessionRoutes } from './routes/sessions';
+import { handleCronRoutes } from './routes/cron';
+import { sendJson } from './route-utils';
+
+type RouteHandler = (
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  ctx: HostApiContext,
+) => Promise<boolean>;
+
+const routeHandlers: RouteHandler[] = [
+  handleAppRoutes,
+  handleGatewayRoutes,
+  handleSettingsRoutes,
+  handleProviderRoutes,
+  handleChannelRoutes,
+  handleSkillRoutes,
+  handleFileRoutes,
+  handleSessionRoutes,
+  handleCronRoutes,
+  handleLogRoutes,
+  handleUsageRoutes,
+];
+
+export function startHostApiServer(ctx: HostApiContext, port = PORTS.CLAWX_HOST_API): Server {
+  const server = createServer(async (req, res) => {
+    try {
+      const requestUrl = new URL(req.url || '/', `http://127.0.0.1:${port}`);
+      for (const handler of routeHandlers) {
+        if (await handler(req, res, requestUrl, ctx)) {
+          return;
+        }
+      }
+      sendJson(res, 404, { success: false, error: `No route for ${req.method} ${requestUrl.pathname}` });
+    } catch (error) {
+      logger.error('Host API request failed:', error);
+      sendJson(res, 500, { success: false, error: String(error) });
+    }
+  });
+
+  server.listen(port, '127.0.0.1', () => {
+    logger.info(`Host API server listening on http://127.0.0.1:${port}`);
+  });
+
+  return server;
+}