LobsterAI — All-in-One Personal Assistant Agent

A 24/7 personal assistant Agent that gets things done, built by NetEase Youdao

English · 中文

---

LobsterAI is an all-in-one personal assistant Agent developed by NetEase Youdao. It works around the clock to handle your everyday tasks — data analysis, making presentations, generating videos, writing documents, searching the web, sending emails, scheduling tasks, and more.

At its core is Cowork mode — it executes tools, manipulates files, and runs commands in a local or sandboxed environment, all under your supervision. You can also reach the Agent via WeChat, WeCom, DingTalk, Feishu, QQ, Telegram, Discord, and more — getting work done from your phone anytime, anywhere.

Key Features

• All-in-One Productivity Assistant — Data analysis, PPT creation, video generation, document writing, web search, email — covers the full range of daily work
• Local + Sandbox Execution — Run tasks directly on your machine or in an OpenClaw sandbox environment
• Built-in Skills — Office document generation, web search, Playwright automation, Remotion video generation, and more
• Windows Built-in Python Runtime — Windows packages bundle a ready-to-use Python interpreter runtime; Python skill dependencies can be installed on demand
• Scheduled Tasks — Create recurring tasks via conversation or the GUI — daily news digests, inbox cleanup, periodic report generation, and more
• Persistent Memory — Automatically extracts user preferences and personal facts from conversations, remembers your habits across sessions, and gets smarter the more you use it
• Mobile via IM — Control your Agent remotely from your phone through WeChat, WeCom, DingTalk, Feishu, QQ, Telegram, Discord, and more
• Permission Gating — All tool invocations require explicit user approval before execution
• Cross-Platform — macOS (Intel + Apple Silicon), Windows, Linux desktop, plus mobile coverage via IM
• Local Data — SQLite storage keeps your chat history and configuration on your device

How It Works

Quick Start

Prerequisites

• Node.js >= 24 < 25
• npm

Install & Develop

# Clone the repository
git clone https://github.com/netease-youdao/LobsterAI.git
cd LobsterAI

# Install dependencies
npm install

# Start development (Vite dev server + Electron with hot reload)
npm run electron:dev

The dev server runs at http://localhost:5175 by default.

Develop with OpenClaw Agent Engine

LobsterAI can use OpenClaw as its agent engine. The required OpenClaw version is pinned in package.json under openclaw.version.

# First run: automatically clones and builds OpenClaw (may take several minutes)
npm run electron:dev:openclaw

# Subsequent runs: skips build if the pinned version hasn't changed
npm run electron:dev:openclaw

By default, OpenClaw source is cloned/managed at ../openclaw (relative to this repo). Override with:

OPENCLAW_SRC=/path/to/openclaw npm run electron:dev:openclaw

To force a rebuild even when the version hasn't changed:

OPENCLAW_FORCE_BUILD=1 npm run electron:dev:openclaw

To skip the automatic version checkout (e.g., when developing OpenClaw locally):

OPENCLAW_SKIP_ENSURE=1 npm run electron:dev:openclaw

Production Build

# TypeScript compilation + Vite bundle
npm run build

# ESLint check
npm run lint

Packaging & Distribution

Uses electron-builder to produce platform-specific installers. Output goes to release/.

# macOS (.dmg)
npm run dist:mac

# macOS - Intel only
npm run dist:mac:x64

# macOS - Apple Silicon only
npm run dist:mac:arm64

# macOS - Universal (both architectures)
npm run dist:mac:universal

# Windows (.exe NSIS installer)
npm run dist:win

# Linux (.AppImage & .deb)
npm run dist:linux

Desktop packaging (macOS / Windows / Linux) bundles a prebuilt OpenClaw runtime under Resources/cfmind. The pinned OpenClaw version (package.json → openclaw.version) is automatically fetched and built during packaging — no manual setup needed. The build is cached: if the runtime for the pinned version already exists locally, the build step is skipped automatically.

You can also build OpenClaw runtime manually:

# Build runtime for current host platform (auto-detect mac/win/linux + arch)
npm run openclaw:runtime:host

# Build explicit targets
npm run openclaw:runtime:mac-arm64
npm run openclaw:runtime:win-x64
npm run openclaw:runtime:linux-x64

Override OpenClaw source path with an environment variable when needed:

OPENCLAW_SRC=/path/to/openclaw npm run dist:win

Windows builds bundle a portable Python runtime under resources/python-win (included as installer resource python-win), so end users do not need to install Python manually. The bundled runtime is interpreter-focused and does not preinstall LobsterAI skill Python packages; those can be installed at runtime on demand. By default, packaging downloads the official Python embeddable runtime from python.org if no prebuilt archive is provided. For offline/non-network builds, provide a prebuilt runtime archive explicitly.

Offline/runtime source options for packaging:

• LOBSTERAI_PORTABLE_PYTHON_ARCHIVE: Local prebuilt runtime archive path (recommended for offline CI/CD)
• LOBSTERAI_PORTABLE_PYTHON_URL: Download URL for the prebuilt runtime archive
• LOBSTERAI_WINDOWS_EMBED_PYTHON_VERSION / LOBSTERAI_WINDOWS_EMBED_PYTHON_URL / LOBSTERAI_WINDOWS_GET_PIP_URL: Optional overrides for Windows-host bootstrap sources

Architecture

LobsterAI uses Electron's strict process isolation. All cross-process communication goes through IPC.

Process Model

Main Process (src/main/main.ts):

• Window lifecycle management
• SQLite persistence
• OpenClaw agent engine (primary) + CoworkEngineRouter dispatch layer
• IM Gateways — WeChat, WeCom, DingTalk, Feishu, QQ, Telegram, Discord, POPO remote access
• 40+ IPC channel handlers
• Security: context isolation enabled, node integration disabled, sandbox enabled

Preload Script (src/main/preload.ts):

• Exposes window.electron API via contextBridge
• Includes cowork namespace for session management and stream events

Renderer Process (src/renderer/):

• React 18 + Redux Toolkit + Tailwind CSS
• All UI and business logic
• Communicates with main process exclusively through IPC

Directory Structure

src/
├── main/                           # Electron main process
│   ├── main.ts                     # Entry point, IPC handlers
│   ├── preload.ts                  # Security bridge
│   ├── sqliteStore.ts              # SQLite storage
│   ├── coworkStore.ts              # Session/message CRUD
│   ├── skillManager.ts             # Skill management
│   ├── im/                         # IM gateways (WeChat/WeCom/DingTalk/Feishu/QQ/Telegram/Discord/POPO)
│   └── libs/
│       ├── agentEngine/
│       │   ├── coworkEngineRouter.ts    # Dispatch layer (routes sessions to the active engine)
│       │   ├── openclawRuntimeAdapter.ts # Primary OpenClaw gateway adapter
│       │   └── claudeRuntimeAdapter.ts  # Legacy built-in adapter (deprecated)
│       ├── coworkRunner.ts          # Legacy built-in executor (deprecated)
│       ├── openclawEngineManager.ts # OpenClaw runtime lifecycle (install/start/status)
│       ├── openclawConfigSync.ts    # Syncs cowork config → OpenClaw config files
│       └── coworkMemoryExtractor.ts # Memory extraction
│
├── renderer/                        # React frontend
│   ├── App.tsx                     # Root component
│   ├── types/                      # TypeScript definitions
│   ├── store/slices/               # Redux state slices
│   ├── services/                   # Business logic (API/IPC/i18n)
│   └── components/
│       ├── cowork/                 # Cowork UI components
│       ├── artifacts/              # Artifact renderers
│       ├── skills/                 # Skill management UI
│       ├── im/                     # IM integration UI
│       └── Settings.tsx            # Settings panel
│
SKILLs/                              # Skill definitions
├── skills.config.json              # Skill enable/disable and ordering
├── web-search/                     # Web search
├── docx/                           # Word document generation
├── xlsx/                           # Excel spreadsheets
├── pptx/                           # PowerPoint presentations
├── pdf/                            # PDF processing
├── remotion/                       # Video generation
├── playwright/                     # Web automation
└── ...                             # More skills

Cowork System

Cowork is the core feature of LobsterAI — an AI working session system powered by OpenClaw as the primary agent engine. Designed for productivity scenarios, it can autonomously complete complex tasks like data analysis, document generation, and information retrieval.

Execution Modes

Mode	Description
auto	Automatically selects based on context
local	Direct local execution, full speed

Stream Events

Cowork uses IPC events for real-time bidirectional communication:

• message — New message added to the session
• messageUpdate — Incremental streaming content update
• permissionRequest — Tool execution requires user approval
• complete — Session execution finished
• error — Execution error occurred

Permission Control

All tool invocations involving file system access, terminal commands, or network requests require explicit user approval in the CoworkPermissionModal. Both single-use and session-level approvals are supported.

Skills System

LobsterAI ships with 29 built-in skills covering productivity, creative, investment research, and automation scenarios, configured via SKILLs/skills.config.json:

Skill	Function	Typical Use Case
web-search	Web search	Information retrieval, research
docx	Word document generation	Reports, proposals
xlsx	Excel spreadsheet generation	Data analysis, dashboards
pptx	PowerPoint creation	Presentations, business reviews
pdf	PDF processing	Document parsing, format conversion
remotion	Video generation (Remotion)	Promo videos, data visualization animations
seedance	AI video generation (Seedance)	Text-to-video, image-to-video
seedream	AI image generation (Seedream)	Text-to-image, image editing and fusion
playwright	Web automation	Browser tasks, automated testing
canvas-design	Canvas drawing and design	Posters, chart design
frontend-design	Frontend UI design	Prototyping, page design
develop-web-game	Web game development	Quick game prototypes
stock-analyzer	Stock deep analysis	A-share research, valuation and financials
stock-announcements	Stock announcement retrieval	Listed company filings, disclosure lookup
stock-explorer	Stock information explorer	Basic stock info, market overview
content-planner	Content planning	Topic strategy, content calendar creation
article-writer	Article writing	Multi-style long-form content, social media posts
daily-trending	Daily trending	Hot topic aggregation, trend tracking
films-search	Film/TV resource search	Movie and series cloud-drive download links
music-search	Music resource search	Song and album cloud-drive download links
technology-news-search	Tech news search	Programming, AI, and IT industry updates (disabled by default)
weather	Weather queries	Weather information
local-tools	Local system tools	File management, system operations
imap-smtp-email	Email send/receive	Email processing, auto-replies
create-plan	Plan authoring	Project planning, task breakdown
youdaonote	Youdao Note	Note management, to-dos, web clipping
skill-vetter	Skill security audit	Safety check before installing third-party skills
skill-creator	Custom skill creation	Extend new capabilities

Custom skills can be created via skill-creator and hot-loaded at runtime.

Scheduled Tasks

LobsterAI supports scheduled tasks that let the Agent automatically execute recurring work on a set schedule.

How to Create

• Conversational — Tell the Agent in natural language (e.g., "collect tech news for me every morning at 9 AM"), and it will create the scheduled task automatically
• GUI — Add tasks manually in the Scheduled Tasks management panel with a visual interface for configuring timing and task content

Typical Scenarios

Scenario	Example
News Collection	Automatically gather industry news and generate a summary every morning
Inbox Cleanup	Periodically check your inbox, categorize emails, and summarize important ones
Data Reports	Generate a weekly business data analysis report
Content Monitoring	Regularly check specific websites for changes and send notifications
Work Reminders	Generate to-do lists or meeting notes on a schedule

Scheduled tasks are powered by Cron expressions, supporting minute, hourly, daily, weekly, and monthly intervals. When a task fires, it automatically starts a Cowork session. Results can be viewed on the desktop or pushed to your phone via IM.

IM Integration — Mobile Remote Control

LobsterAI can bridge the Agent to multiple IM platforms. Send a message from your phone via IM to remotely trigger the desktop Agent — command your personal assistant anytime, anywhere.

Platform	Protocol	Description
WeChat	OpenClaw gateway	WeChat account integration, supports DMs and group chats
WeCom	OpenClaw gateway	WeCom app bot, supports DMs and group chats
DingTalk	OpenClaw gateway	Enterprise bot, supports multiple instances
Feishu	OpenClaw gateway	Feishu/Lark app bot, supports multiple instances
QQ	OpenClaw gateway	QQ bot (official Bot API), supports multiple instances
Telegram	OpenClaw gateway	Bot API, supports webhook and polling
Discord	OpenClaw gateway	Discord bot, supports servers and DMs
NetEase IM	node-nim V2 SDK	NetEase IM P2P messaging
NetEase Bee	node-nim V2 SDK	NetEase Bee personal digital assistant
NetEase POPO	OpenClaw gateway	NetEase POPO enterprise IM, supports WebSocket and Webhook

Configure the corresponding platform Token/Secret in the Settings panel to enable. Once set up, you can send instructions directly to the Agent from your phone IM (e.g., "analyze this dataset", "make a weekly summary PPT"), and the Agent will execute on the desktop and return results.

Persistent Memory

LobsterAI's memory system is built on OpenClaw and persists information as files in the working directory, so the Agent remembers your preferences and context across sessions.

Memory File Structure

File	Purpose
MEMORY.md	Durable facts, preferences, and decisions — loaded automatically at session start
memory/YYYY-MM-DD.md	Daily notes — preserves recent context
USER.md	User profile (name, occupation, habits, long-term info)
SOUL.md	Agent personality and behavioral principles

How Memories Are Written

• Explicit instructions — Say "remember that…" or "from now on reply in English," and the Agent calls the write tool to save to MEMORY.md before acknowledging — no silent "mental notes"
• Agent-initiated — The Agent can proactively write important findings, configurations, or environment notes to memory files during task execution, without explicit prompting
• GUI management — Add, edit, or delete entries in MEMORY.md directly from the Settings panel; keyword search is supported

How It Works

At the start of every session, OpenClaw reads SOUL.md, USER.md, today's and yesterday's memory/YYYY-MM-DD.md, and MEMORY.md in sequence, injecting them as context. This lets the Agent pick up where it left off without you needing to re-explain preferences.

Memory writes go through file tools — there is no background extraction or inference. Content is fully under user or Agent control.

Data Storage

All data is stored in a local SQLite database (lobsterai.sqlite in the user data directory).

Table	Purpose
kv	App configuration key-value pairs
cowork_config	Cowork settings (working directory, system prompt, execution mode)
cowork_sessions	Session metadata
cowork_messages	Message history
user_memories	User memory entries
user_memory_sources	Memory source tracking
agents	Custom Agent configurations
mcp_servers	MCP server configurations
im_config	IM gateway config (tokens/secrets per platform)
im_session_mappings	Mapping between IM conversations and Cowork sessions
scheduled_task_meta	Scheduled task metadata (origin and binding info)

Security Model

LobsterAI enforces security at multiple layers:

• Process Isolation — Context isolation enabled, node integration disabled
• Permission Gating — Tool invocations require explicit user approval
• Sandbox Execution — Optional OpenClaw sandbox for isolated execution
• Content Security — HTML sandbox, DOMPurify, Mermaid strict mode
• Workspace Boundaries — File operations restricted to the designated working directory
• IPC Validation — All cross-process calls are type-checked

Tech Stack

Layer	Technology
Framework	Electron 40
Frontend	React 18 + TypeScript
Build	Vite 5
Styling	Tailwind CSS 3
State	Redux Toolkit
AI Engine	OpenClaw (primary)
Storage	better-sqlite3
Markdown	react-markdown + remark-gfm + rehype-katex
Diagrams	Mermaid
Security	DOMPurify
IM	@larksuiteoapi/node-sdk · nim-web-sdk-ng · @wecom/wecom-aibot-sdk · OpenClaw gateway (DingTalk / Telegram / Discord / QQ etc.)

Configuration

App Configuration

App-level config is stored in the SQLite kv table, editable through the Settings panel.

Cowork Configuration

Cowork session config includes:

• Working Directory — Root directory for Agent operations
• System Prompt — Customize Agent behavior
• Execution Mode — auto / local

Internationalization

Currently English and Chinese are supported. Switch languages in the Settings panel.

OpenClaw Version Management

LobsterAI pins its OpenClaw dependency to a specific release version, declared in package.json:

{
  "openclaw": {
    "version": "v2026.3.2",
    "repo": "https://github.com/openclaw/openclaw.git"
  }
}

How It Works

Step	What happens	When
Version ensure	Clones or checks out the pinned tag in ../openclaw	Before every runtime build
Build cache check	Compares pinned version with runtime-build-info.json	Before every runtime build
Full build	pnpm install → build → ui:build → pack to asar	Only when version changed

Updating OpenClaw Version

1. Change openclaw.version in package.json to the desired release tag
2. Run npm run electron:dev:openclaw or npm run dist:win — the new version is fetched and built automatically
3. Commit the package.json change

Environment Variables

Variable	Description	Default
OPENCLAW_SRC	Path to OpenClaw source directory	../openclaw
OPENCLAW_FORCE_BUILD	Set to 1 to force rebuild even if version matches	—
OPENCLAW_SKIP_ENSURE	Set to 1 to skip automatic version checkout	—
LOBSTERAI_SQLITE_BACKUP_ALWAYS_ON_STARTUP	Set to 1 or true to force an automatic backup on every app startup for QA/testing	—

Development Guidelines

• TypeScript strict mode, functional components + Hooks
• 2-space indentation, single quotes, semicolons
• Components: PascalCase; functions/variables: camelCase; Redux slices: *Slice.ts
• Tailwind CSS preferred; avoid custom CSS
• Commit messages follow type: short imperative summary (e.g., feat: add artifact toolbar)

Testing

Unit tests use Vitest and are co-located with the source files they cover.

# run all tests
npm test

# run tests for a specific module (Vitest filename filter)
npm test -- logger
npm test -- cowork

New test files go next to the source file they test, using the .test.ts extension:

src/main/
├── foo.ts
└── foo.test.ts

Example (src/main/logger.test.ts):

import { test, expect } from 'vitest';

test('log file pattern matches daily name', () => {
  expect(/^main-\d{4}-\d{2}-\d{2}\.log$/.test('main-2026-03-20.log')).toBe(true);
});

Avoid importing Electron-only APIs (e.g. electron-log) in tests — inline any logic that depends on them instead.

Community

Join our WeChat group to get help, share feedback, and stay up to date:

Contributing

1. Fork this repository
2. Create your feature branch (git checkout -b feature/your-feature)
3. Commit your changes (git commit -m 'feat: add something')
4. Push to the branch (git push origin feature/your-feature)
5. Open a Pull Request

Please include in your PR description: a summary of changes, linked issue (if any), screenshots for UI changes, and notes on any Electron-specific behavior changes.

License

MIT License

Star History

---

Built and maintained by NetEase Youdao.