Changelog

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

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

[Unreleased]

[0.1.32] - 2026-08-11

新增

• 新增 Octop 导出迁移脚本，包含配置、cron 任务与数据库 schema 迁移

变更

• 优化 Octop 导出设置的界面样式与文案
• 优化 Octop 导出配置中可选字段的处理逻辑，增强数据库连接管理
• 增强 Octop 导出配置中 model ID 的唯一性处理

修复

• 澄清 Octop 导出迁移后的数据归属说明

[0.1.31] - 2026-07-28

新增

• 新增导出到 Octop 功能，支持 provider 名称、迁移文案、agent ID、渠道和模型等资源导出

修复

• 修复导出到 Octop 功能的代码审查反馈问题

[0.1.30] - 2026-07-13

新增

• 新增 MiniMax (CN) 国内版 Provider，与国际版 MiniMax (Global) 分离，分别对应 minimax.com 和 minimax.io

[0.1.29] - 2026-07-01

修复

• 修复主动推送提示词中时间基准不准确的问题，在 prompt 头部前置权威时间锚点
• 修复 Windows install.bat 安装时 uv pip install 进度不可见的问题
• 修复 Windows install.bat 无法可靠将 lightclaw bin 写入用户 PATH 的问题

[0.1.28] - 2026-06-23

新增

• 新增 /help 斜杠命令，列出所有支持的命令及说明
• 增强登录认证安全能力，提升账号访问控制

[0.1.27] - 2026-06-22

新增

• 新增 OpenAI (Codex) 独立 Provider，支持 Codex OAuth 认证方式

修复

• 修复定时任务（Cron）默认模型选择异常
• 修复 Codex Responses API 系统消息兼容性问题
• 修复 QQ 频道主动推送时错误携带 Markdown 及被动回复 Markdown 永久降级问题

变更

• QQ 频道支持全通道 Markdown 渲染，完善富媒体收发能力

[0.1.23] - 2026-06-10

新增

• 重连时自动刷新一次性 ticket，修复 401 无限重连问题

[0.1.22] - 2026-06-09

变更

• 重构多账号支持与配置解析逻辑，优化 config 与 channel 模块

[0.1.21] - 2026-06-08

新增

• 新增 OpenAI 兼容的 /v1/embeddings HTTP 服务
• 优化 ACE 对新版 agent-chat 的支持

修复

• 修复引擎异常时部分历史记录未持久化的问题
• 修复设置向导中强制密码修改逻辑，加固 setup-done 端点安全性
• 修复终端二维码渲染过大导致无法扫描的问题

变更

• 优化记忆整理流程，支持 USER.md 内容分流

[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

🏗️ Tech Stack

🚀 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.

🧩 Built-in Skills

Global Skills (always available)

Native Tools (always on)

⚙️ 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

Supported Channels

📖 CLI Reference

🖥️ 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