lightclaw 0.1.20

Self-hosted AI personal assistant with multi-channel chat, smart memory, and extensible skills.

Changelog

本文件记录项目的所有重要变更。

格式遵循 Keep a Changelog，版本号遵循 语义化版本规范。

[Unreleased]

[0.1.20] - 2026-06-02

修复

• 启动飞书 bot creator 前清理残留 Chromium 进程与单实例锁
• 修复飞书 bot creator 反 headless 检测问题，每次扫码前清理会话

变更

• 内置渠道改为懒加载，加速服务启动

[0.1.18] - 2026-05-28

修复

• 修复 token budget 动态调整时丢弃图片内容的问题，保留多模态输入逻辑

[0.1.17] - 2026-05-25

变更

• 锁定 pydantic 依赖为稳定版本，避免不兼容的预发布版本引入问题

[0.1.16] - 2026-05-25

新增

• 浏览器工具迁移到 harness-browser，统一 agent 与 dashboard 的会话共享
• 新增 browser_orckit 纯 CDP 浏览器工具，基于 harness-browser

修复

• 修复打开 dashboard 面板时覆盖 agent 当前标签页的问题，保留 agent 标签页
• 修复今日 token 统计与自定义时间范围 token 统计错误
• 修复时区错乱问题
• 默认关闭 MEMORY.md 超长压缩，防止压缩篡改 MEMORY.md 格式

变更

• 优化记忆蒸馏提示词及输出文件格式
• 优化应用镜像制作脚本

[0.1.15] - 2026-05-20

新增

• 定时任务支持为每个任务独立配置模型
• 新增环境变量开关，支持禁用 MEMORY.md 自动压缩
• 新增 CVM 迁移仪表盘技能（cvm migration dashboard）
• 新增集群诊断和 CVM AI 医生技能（cluster doctor、cvm ai doctor）

修复

• 修复关闭信号处理，避免定时任务调度时异常退出
• 跳过仅含模板占位内容的 HEARTBEAT.md，避免浪费 token

变更

• 优化定时任务调度配置的交互体验

[0.1.14] - 2026-05-18

新增

• 新增 Chrome 扩展功能，支持侧边栏面板与后端通信
• 新增 lightclaw_assistant 技能，提供 LightClaw 使用帮助与引导

修复

• 修复 session 注入不带时间戳的问题

变更

• 技能卡片 UI 全面重构，布局与样式优化
• 欢迎屏幕新增快捷功能入口与动效优化
• Token 用量页面展示优化
• 前端国际化（i18n）文案补充与更新

[0.1.13] - 2026-05-15

新增

• 升级提示中展示 PyPI CHANGELOG 发布说明
• 欢迎界面重新设计，UI 细节优化
• 新增 /bgtokenusage 斜杠命令及后台 token 消耗 API
• 主动记忆引入混合评分 + 触发计数惩罚，提升候选多样性
• 主动推送支持事件感知时间分桶，4 分支提示词，延迟回填
• 三态事件时间提取器，支持将来时语义
• Qdrant 可续跑回填脚本，补全事件时间字段
• Dashboard 快捷指令菜单新增 /topics 和 /token
• 新增按话题/会话级 token 流水账系统（UsageLedger）
• 全项目时区统一为 Asia/Shanghai（CST）
• 新增 PyPI 自动发布 skill

修复

• 修复新建对话出现幽灵话题（#?）的显示 bug
• 修复飞书首次运行浏览器启动可靠性问题
• 会话文件加载增加 UTF-8 容错与自愈机制
• 修复主动消息中 thinking block 残留及 delta 去重问题
• Cron 任务默认超时由 120s 调整为 600s
• 一键更新仅升级 lightclaw 自身，不再连带升级所有依赖
• 微信 markdown 过滤器适配 iLink 渲染兼容性
• 记录主动触达反馈，避免重复追问
• 修复后台内存任务 token 串流到用户会话的 bug（ContextVar 分桶）
• 修复主分支合并后 /bgtokenusage 命令丢失问题

变更

• 主动推送：无 embedding 时降级为 FTS 候选搜索
• 主动推送默认触发间隔调整

LightClaw

Self-hosted AI personal assistant — affordable, personalized, and ready to go.

简体中文 · English

---

LightClaw is an open-source, self-hosted AI personal assistant built with Python. Compared to similar projects, it focuses on three key differentiators: Cost-efficient — significantly lower token consumption; Personalized — built-in multi-layer memory system that learns your preferences over time; Ready to use — 6 deeply optimized scenes out of the box, zero-config to get started.

Chat with LightClaw through Feishu, QQ, WeChat or the built-in Web Dashboard. All capabilities are driven by an extensible Skills system and the MCP (Model Context Protocol).

✨ Highlights

	Feature	Description
💰	Cost-efficient	Smart multi-model routing dispatches cheap models for simple tasks, large models only when needed. Aggressive context trimming and memory compression slash token costs by an order of magnitude.
🧠	Memory System	Long-term memory extraction, user profiling, and conversation summaries — the assistant gets smarter the more you use it.
🎮	Built-in Scenes	6 production-ready scenes: WeChat Official Account operations, stock market analysis, news tracking, low-code development, AI video generation, and smart education.
🔌	Multi-channel	Feishu · QQ · DingTalk · Discord · Web Dashboard — one assistant across all your chat platforms.
🧩	Extensible Skills	5 built-in skills + community SkillHub marketplace + MCP protocol for unlimited tool integration.
🏠	Local-first	All data stays in ~/.lightclaw/. Supports fully offline mode with local LLMs (Ollama / LLaMA-CPP / MLX).

🏗️ Tech Stack

Layer	Technologies
Language	Python 3.11+
Agent Framework	LangChain + LangGraph (ReAct Agent)
API Server	FastAPI + Uvicorn
Frontend	React + TypeScript + Vite + Ant Design
Memory	Qdrant + SQLite FTS5 + Structured Fact System
LLM Providers	OpenAI · DashScope (Qwen) · Ollama · LLaMA-CPP · MLX
Scheduling	APScheduler
Browser Automation	Playwright
MCP	Model Context Protocol (stdio + HTTP + SSE)
Build / Lint	setuptools · ruff · pytest · pre-commit

🚀 Quick Start

Prerequisites

• Python 3.11 – 3.13
• uv (recommended) or pip

1. Install

# macOS / Linux — one-line installer
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/install.sh | bash

After installation, open a new terminal or reload your shell:

source ~/.zshrc   # Zsh
# or
source ~/.bashrc  # Bash

2. Initialize

lightclaw init

The interactive wizard walks you through: language → LLM provider → API key → model selection.

3. Run

# Start the server
lightclaw run

# Bind to a custom host/port
lightclaw run --host 0.0.0.0 --port 80

# Or register as a system service (auto-start on boot)
lightclaw start --host 0.0.0.0 --port 80

Open your browser and start chatting!

🎮 Built-in Scenes

LightClaw ships with 6 deeply optimized Scenes — each is a complete agent configuration package including a dedicated persona, specialized skills, and fine-tuned behavior rules.

Scene	Description	Example Prompt
✍️ WeChat Official Account	End-to-end content pipeline: trending topic discovery → research → AI writing → one-click publish	"Write an article about today's AI news and publish it"
📈 Stock Market	Market watcher with technical analysis (MA/MACD/RSI/BOLL), powered by 1090+ akshare data APIs	"What's happening in the A-share market today?"
📰 News & Trends	Real-time aggregation from 70+ platforms (Weibo, Zhihu, HN, GitHub Trending, etc.)	"Summarize today's tech news"
💻 Low-code Dev	Full-stack development assistant: requirements → code generation → preview → deploy	"Build me a personal blog with dark mode"
🎬 Video Production	Text-to-video pipeline: script → storyboard → image generation → video synthesis	"Turn this story into a short video"
🎓 Smart Education	Personalized AI tutor: study plans, lectures, exercises, mistake tracking, spaced repetition	"Create a 30-day plan to learn linear algebra"

🧩 Built-in Skills

Global Skills (always available)

Skill	Description
cron	Scheduled task management — create, list, pause, resume, delete. Supports text messages and agent-powered responses across all channels.
pdf	Full PDF processing — extract text/tables, merge, split, rotate, watermark, encrypt, OCR, form filling.
file-reader	Read local text files (.txt, .md, .json, .yaml, .csv, .log, code). Auto-summarizes large files.
skill-creator	Create, modify, evaluate, and benchmark custom skills.
install-skill	Search and install community skills from SkillHub.

Native Tools (always on)

Tool	Description
execute_shell_command	Run shell commands
read_file / write_file / edit_file	File operations
browser_use	Playwright browser automation
desktop_screenshot	Desktop / window screenshot
send_file_to_user	Send files through the active channel
get_current_time	Get current system time

⚙️ Configuration

All config lives in ~/.lightclaw/lightclaw.json. Manage it via CLI or edit directly.

# View/switch LLM models
lightclaw models
lightclaw models switch

# Install chat channels
lightclaw channels install

# Manage skills
lightclaw skills
lightclaw skills install

# Manage cron jobs
lightclaw cron list
lightclaw cron create --help

# Manage environment variables
lightclaw env

Supported LLM Providers

Provider	Description	API Key Required
OpenAI	GPT-4o, GPT-4, GPT-3.5, etc.	✅
DashScope	Alibaba Qwen series	✅
Ollama	Local Ollama server	❌
LLaMA-CPP	Local GGUF model inference	❌
MLX	macOS Apple Silicon local inference	❌

Supported Channels

Channel	Credentials Needed
Feishu	App ID, App Secret
QQ	Bot AppID, Token
DingTalk	App Key, App Secret
Discord	Bot Token
Web Dashboard	Enabled by default

📖 CLI Reference

Command	Description
lightclaw init	Initialize workspace at ~/.lightclaw/
lightclaw config	Interactive re-configuration
lightclaw run	Start LightClaw (API + Dashboard + channels)
lightclaw start	Register & start as system service
lightclaw stop	Stop system service
lightclaw restart	Restart system service
lightclaw channels install	Install chat channels
lightclaw skills install	Install skills
lightclaw models	Manage LLM providers
lightclaw cron	Manage scheduled tasks
lightclaw chats	Manage conversation history
lightclaw env	Manage environment variables
lightclaw clean	Clean temp files and caches
lightclaw uninstall	Uninstall and clean workspace

🖥️ Web Dashboard

After starting LightClaw, access the dashboard at http://localhost:80.

Features:

• 💬 Chat — Real-time conversation with LightClaw
• 📋 Sessions — Browse conversation history
• ⚙️ Settings — Configure providers, models, channels
• 🧩 Skills — Enable/disable skills
• ⏰ Cron — Visual cron job management
• 🔗 MCP — Manage MCP tool services
• 📊 Env — Manage environment variables

📁 Project Structure

~/.lightclaw/                          ← Data directory
├── lightclaw.json                     # Core config
├── auth.json                          # Authentication
├── jobs.json                          # Cron job definitions
├── chats.json                         # Conversation metadata
├── logs/                              # Runtime logs
└── workspace/                         ← Agent workspace
    ├── .env                           # Persistent env vars
    ├── AGENTS.md                      # Agent behavior rules
    ├── SOUL.md                        # Core identity & principles
    ├── MEMORY.md                      # Long-term memory
    ├── USER.md                        # User profile & agent self-portrait
    ├── skills/                        # All skills
    ├── memory/                        # Message DB & summaries
    ├── sessions/                      # Session state
    └── uploads/                       # User uploads

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                    LightClaw App                     │
│                                                     │
│  Web Dashboard (port 80) ◄── REST ──► FastAPI       │
│                                                     │
│  Channel Integrations (Feishu, QQ, DingTalk, etc.)  │
│                                                     │
│  Agent Engine: ReAct Agent → Skill Hub → LLM        │
│                                                     │
│  Config / Memory / Jobs (stored at ~/.lightclaw/)   │
└─────────────────────────────────────────────────────┘

User (via channel) → ChannelManager → Runner → ReAct Agent
                                                    ↓
                                              LLM Provider
                                                    ↓
                                             Skill Executor
                                                    ↓
                                          Response → Channel

🔒 Security & Privacy

• Local-first: All data (config, memory, chats, uploads) stored locally at ~/.lightclaw/ — never uploaded to third-party servers.
• Minimal data to LLM: Only current conversation context and trimmed memory summaries are sent to LLM providers. Config, other channel chats, and the full message DB are never sent.
• Fully offline mode: Use local models (Ollama / LLaMA-CPP / MLX) for zero API calls and complete data isolation.
• Access control: Web Dashboard supports password authentication. Credentials stored as hashes, never plaintext.
• Skill vetting: Community skills in SkillHub undergo security and compliance review before publication.

🛠️ Development

Frontend (Dashboard)

cd dashboard
npm install
npm run dev       # Dev server at http://localhost:80
npm run build     # Production build
npm run lint      # ESLint + TypeScript check
npm run format    # Prettier

Backend

# Install dev dependencies
uv sync --extra dev

# Lint & format
ruff check . --fix
ruff format .

# Run tests
pytest
pytest -xvs       # Verbose, stop on first failure

# Type checking
mypy src/lightclaw/

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Ensure code passes ruff check and ruff format
4. Add tests for new functionality
5. Submit a Pull Request

Please read the coding standards in CLAUDE.md for detailed guidelines.

📋 Changelog

v0.0.1 (2026-03-17)

• 🎉 Initial public release — first open-source version of LightClaw
• 🎮 6 built-in scenes: WeChat Official Account, Stock Market, News & Trends, Low-code Dev, Video Production, Smart Education
• 🧠 Multi-layer memory system: long-term memory + user profiling + conversation summaries
• 💰 Smart multi-model routing for cost-efficient token consumption
• 🔌 Multi-channel support: Feishu, QQ, DingTalk, Discord, Web Dashboard
• 🧩 5 built-in skills + SkillHub marketplace + MCP protocol integration
• 🏠 Local-first architecture with full offline mode support (Ollama / LLaMA-CPP / MLX)
• 🖥️ Web Dashboard with chat, session management, settings, skill management, and cron jobs
• 📄 Added MIT License

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Made with ❤️ by the OrcaKit team