lightclaw 0.0.9

LightClaw is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, etc.) and runs scheduled tasks according to your configuration. **What it can do is driven by Skills — the possibilities are open-ended.** Built-in skills include cron, PDF/Office handling, news digest, file reading, and more; you can add custom skills. All data and tasks run on your machine; no third-party hosting.

LightClaw — 自托管 AI 个人助手

LightClaw 是一个运行在你自己设备上的 AI 个人助手。它通过多种聊天渠道（钉钉、飞书、QQ、Discord、Web Dashboard）与你对话，还能执行定时任务。所有能力由 Skills（技能） 驱动 —— 一套可扩展的模块系统，既有内置技能也支持用户自建。全部数据保存在本地，无需第三方托管。

---

📋 目录

• 功能特性
• 环境要求
• 快速开始
  • 1. 克隆仓库
  • 2. 安装 Python 环境
  • 3. 初始化工作区
  • 4. 启动 LightClaw
• 配置指南
  • 选择 LLM 模型
  • 配置聊天渠道
  • 管理技能
  • 配置定时任务
  • MCP 服务集成
• Web Dashboard
• CLI 命令参考
• 内置技能一览
• 工作区目录结构
• 系统架构
• 前端开发
• 代码质量与测试
• 常见问题
• 许可证

---

✨ 功能特性

特性	说明
多渠道支持	钉钉、飞书、QQ、Discord、Web Dashboard，一个助手多端连接
可扩展技能系统	内置 PDF/Office 处理、定时任务、新闻摘要、浏览器自动化、邮件管理等技能；支持用户自定义创建技能
多 LLM 供应商	OpenAI、DashScope（阿里千问）、Ollama、本地模型（LLaMA-CPP、MLX）等
MCP 集成	支持 Model Context Protocol 服务接入，热加载
定时任务	基于 APScheduler 的 Cron 任务管理，让助手自动执行周期性工作
系统服务	支持注册为 systemd（Linux）或 launchd（macOS）用户服务，开机自启
本地优先	所有配置、记忆、数据存储在 ~/.lightclaw/，数据不离开你的设备

---

🔧 环境要求

在开始之前，请确保你的系统满足以下条件：

依赖	版本要求	说明
Python	3.10 – 3.13	推荐使用 3.12
Node.js	18+	仅在需要前端开发时安装
操作系统	macOS / Linux / Windows	均支持，macOS 可额外使用 MLX 本地推理

---

🚀 快速开始

1. 克隆仓库

git clone [e-mail]:orcakit/lightclaw.git
cd lightclaw

2. 安装 Python 环境

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# macOS / Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 安装 LightClaw
pip install ".[dev]"

可选依赖

根据你的需求安装额外的本地推理后端：

# LLaMA-CPP 本地推理（支持 macOS / Linux / Windows）
pip install ".[llamacpp]"

# MLX 本地推理（仅 macOS Apple Silicon）
pip install ".[mlx]"

# Ollama 集成
pip install ".[ollama]"

3. 初始化工作区

首次使用时需要执行初始化，该命令会在 ~/.lightclaw/ 下创建配置文件和目录结构：

lightclaw init

初始化过程中，CLI 将以交互式向导引导你完成以下配置：

1. 选择语言：中文 / English
2. 选择 LLM 供应商：OpenAI、DashScope（阿里千问）、Ollama、本地模型等
3. 填写 API Key：根据选择的供应商输入对应的密钥
4. 选择模型：从供应商的可用模型列表中选择

4. 启动 LightClaw

# 启动应用（后端 + Web Dashboard）
lightclaw run

或通过 Python 模块启动：

python -m lightclaw run

启动后：

• 🌐 Web Dashboard：http://localhost:80
• 🔌 后端 API：http://localhost:8088

你现在可以打开浏览器访问 Web Dashboard，开始与 LightClaw 对话了！

---

⚙️ 配置指南

所有配置存储在 ~/.lightclaw/lightclaw.json 中，你可以通过 CLI 命令或直接编辑文件来修改配置。

选择 LLM 模型

LightClaw 支持多种 LLM 供应商，使用以下命令管理：

# 查看当前模型配置
lightclaw models

# 交互式切换供应商/模型
lightclaw models switch

支持的供应商：

供应商	说明	需要 API Key
OpenAI	GPT-4o、GPT-4、GPT-3.5 等	✅
DashScope	阿里千问系列	✅
Ollama	本地 Ollama 服务	❌
LLaMA-CPP	本地 GGUF 模型推理	❌
MLX	macOS Apple Silicon 本地推理	❌

配置聊天渠道

使用以下命令安装和配置聊天渠道：

# 安装渠道（交互式选择）
lightclaw channels install

各渠道的配置要求：

渠道	需要的凭证
钉钉	App Key、App Secret
飞书	App ID、App Secret
QQ	Bot AppID、Token
Discord	Bot Token
iMessage	macOS 本地 iMessage（无需额外配置）
Web Dashboard	默认启用，无需配置

管理技能

# 安装/启用技能
lightclaw skills install

# 查看已安装的技能
lightclaw skills

技能文件统一存放在 ~/.lightclaw/workspace/skills/ 目录中。技能是否启用记录在 ~/.lightclaw/lightclaw.json 的 skills.entries 里。

配置定时任务

LightClaw 支持定时让助手自动执行任务，例如"每天早上 8 点发送新闻摘要"：

# 管理定时任务
lightclaw cron

# 查看已有定时任务
lightclaw cron list

# 添加新定时任务
lightclaw cron add

定时任务定义存储在 ~/.lightclaw/jobs.json 中。

MCP 服务集成

LightClaw 支持通过 Model Context Protocol（MCP）接入外部工具服务，配置方法：

1. 在 ~/.lightclaw/lightclaw.json 中的 mcp_servers 字段添加 MCP 服务配置
2. LightClaw 支持 MCP 服务的热加载，修改配置后无需重启即可生效

---

🖥️ Web Dashboard

启动 LightClaw 后，在浏览器中访问 http://localhost:80 即可使用 Web Dashboard。

Web Dashboard 提供以下功能：

• 💬 Chat：与 LightClaw 进行实时对话
• 📋 Sessions：查看历史会话记录与消息详情
• ⚙️ 配置管理：在线修改供应商、模型、渠道等设置
• 🧩 技能管理：查看、启用、禁用技能
• ⏰ 定时任务：可视化管理 Cron 任务
• 🔗 MCP 服务：管理已接入的 MCP 工具服务
• 📊 环境变量：管理持久化的环境变量

---

📖 CLI 命令参考

命令	说明
lightclaw init	初始化 ~/.lightclaw/ 工作区，引导完成首次配置
lightclaw config	交互式重新配置（渠道、LLM、技能、环境变量）
lightclaw run	启动 LightClaw（后端 API + Web Dashboard + 所有已配置渠道）
lightclaw start	将 LightClaw 注册为系统服务并启动（systemd / launchd）
lightclaw stop	停止系统服务
lightclaw restart	重启系统服务
lightclaw channels install	安装并配置聊天渠道
lightclaw skills install	安装技能
lightclaw models	管理 LLM 模型供应商与模型选择
lightclaw cron	管理定时任务
lightclaw chats	管理对话历史
lightclaw env	管理持久化环境变量
lightclaw clean	清理临时文件和缓存
lightclaw uninstall	卸载 LightClaw 并清理工作区

全局选项：

lightclaw run --host 0.0.0.0 --port 9090   # 自定义主机和端口
lightclaw -h                                 # 查看帮助信息

---

🧩 内置技能一览

技能	功能说明
cron	创建和管理定时任务，让 LightClaw 定期自动执行指定工作
pdf	PDF 文档的提取、编辑、合并
xlsx	Excel 电子表格的读取和写入
pptx	PowerPoint 演示文稿的读取和创建
docx	Word 文档的读取和编辑
file-reader	读取文本、JSON、YAML 等格式的文件
news	获取新闻并生成摘要
browser-visible	浏览器自动化操作与网页截图
himalaya	基于 IMAP 协议的邮件管理
skill-creator	帮助你创建自定义技能的内置工具
find-skills	搜索和发现更多可用技能

提示：你可以通过 skill-creator 技能让 LightClaw 帮你创建全新的自定义技能，无需手动编写代码。

---

📁 工作区目录结构

lightclaw init 执行后会在用户目录下创建以下结构：

~/.lightclaw/
├── lightclaw.json           # 核心配置文件（供应商、模型、渠道凭证、skills.entries 等）
├── jobs.json                # 定时任务定义
├── chats.json               # 对话历史记录
├── .env                     # 持久化环境变量
├── HEARTBEAT.md             # 心跳任务定义
└── workspace/
    ├── skills/              # 所有技能（内置同步 + 用户创建）
    ├── custom_channels/     # 自定义渠道插件
    ├── uploads/             # 上传文件
    └── memory/
        ├── MEMORY.md        # 长期记忆（LightClaw 从对话中学到的信息）
        ├── PROFILE.md       # 用户画像（你的偏好和习惯）
        └── YYYY-MM-DD.md    # 每日笔记

关键文件说明

• lightclaw.json：最核心的配置文件，包含 LLM 供应商设置、API Key、模型选择、渠道凭证，以及技能启用状态 skills.entries。建议通过 CLI 命令修改，也可以直接编辑。
• workspace/memory/：LightClaw 的记忆系统。MEMORY.md 存储长期记忆，PROFILE.md 存储用户画像，每日笔记自动记录。
• workspace/skills/：所有技能都存放在这里，包括从源码同步的内置技能和你自己创建的技能。
• .env：持久化环境变量，启动时会自动加载进进程环境。

---

🏗️ 系统架构

┌──────────────────────────────────────────────────────┐
│                   LightClaw 应用                      │
│                                                      │
│  Web Dashboard (端口 80) ◄── REST ──► FastAPI (8088) │
│                                                      │
│  渠道集成 (钉钉、飞书、QQ、Discord…)                   │
│                                                      │
│  Agent 引擎: ReAct Agent → 技能中心 → LLM            │
│                                                      │
│  配置 / 记忆 / 任务 (存储在 ~/.lightclaw/)             │
└──────────────────────────────────────────────────────┘

请求处理流程：

用户 (通过渠道) → ChannelManager → Runner → ReAct Agent
                                                 ↓
                                          LLM 供应商
                                                 ↓
                                          技能执行器
                                                 ↓
                                       响应 → 返回渠道

---

🖥️ 前端开发

如果你需要参与 Web Dashboard 的前端开发：

# 进入前端项目目录
cd dashboard

# 安装依赖
npm install

# 启动开发服务器（访问 http://localhost:80）
npm run dev

# 构建生产版本
npm run build

# 代码检查（ESLint + TypeScript）
npm run lint

# 代码格式化（Prettier）
npm run format

前端技术栈：React + TypeScript + Vite + Ant Design

---

✅ 代码质量与测试

# 代码格式化（行宽 79 字符）
python -m black src/lightclaw/

# Lint 检查
flake8 src/lightclaw/

# 类型检查
mypy src/lightclaw/

# 运行 pre-commit 钩子
pre-commit run --all-files

# 运行全部测试
pytest

# 详细模式运行，遇到首个失败即停止
pytest -xvs

---

❓ 常见问题

Q: 启动时端口被占用怎么办？

使用自定义端口启动：

lightclaw run --port 9090

Q: 如何切换语言？

重新运行配置命令，或直接编辑 ~/.lightclaw/lightclaw.json 中的 language 字段。

lightclaw config

Q: 如何使用本地模型？

1. 安装对应的本地推理后端：

   pip install ".[llamacpp]"   # 或 ".[mlx]"（仅 macOS）
   

2. 通过 lightclaw models 命令切换到本地模型供应商
3. 选择或下载要使用的模型

Q: 如何将 LightClaw 设置为开机自启？

使用系统服务命令（支持 Linux systemd 和 macOS launchd）：

lightclaw start

Q: 如何创建自定义技能？

有两种方式：

1. 让 LightClaw 帮你创建：在对话中告诉 LightClaw 你需要什么技能，内置的 skill-creator 会自动生成
2. 手动创建：在 ~/.lightclaw/workspace/skills/ 目录下创建技能文件夹，包含 SKILL.md 描述文件

Q: 数据存储在哪里？

所有数据都存储在本地的 ~/.lightclaw/ 目录下，不会上传到任何第三方服务器。你可以随时备份或迁移这个目录。

---

📄 许可证

详见 LICENSE 文件。