# LightClaw — 自托管 AI 个人助手

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

---

## 📋 目录

- [功能特性](#-功能特性)
- [环境要求](#-环境要求)
- [快速开始](#-快速开始)
  - [1. 克隆仓库](#1-克隆仓库)
  - [2. 安装 Python 环境](#2-安装-python-环境)
  - [3. 初始化工作区](#3-初始化工作区)
  - [4. 启动 LightClaw](#4-启动-lightclaw)
- [配置指南](#-配置指南)
  - [选择 LLM 模型](#选择-llm-模型)
  - [配置聊天渠道](#配置聊天渠道)
  - [管理技能](#管理技能)
  - [配置定时任务](#配置定时任务)
  - [MCP 服务集成](#mcp-服务集成)
- [Web Dashboard](#-web-dashboard)
- [CLI 命令参考](#-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. 克隆仓库

```bash
git clone git@git.woa.com:orcakit/lightclaw.git
cd lightclaw
```

### 2. 安装 Python 环境

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

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

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

#### 可选依赖

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

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

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

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

### 3. 初始化工作区

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

```bash
lightclaw init
```

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

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

### 4. 启动 LightClaw

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

或通过 Python 模块启动：

```bash
python -m lightclaw run
```

启动后：
- 🌐 **Web Dashboard**：`http://localhost:80`
- 🔌 **后端 API**：`http://localhost:8088`

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

---

## ⚙️ 配置指南

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

### 选择 LLM 模型

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

```bash
# 查看当前模型配置
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 本地推理 | ❌ |

### 配置聊天渠道

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

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

各渠道的配置要求：

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

### 管理技能

```bash
# 安装/启用技能
lightclaw skills install

# 查看已安装的技能
lightclaw skills
```

技能安装后会存放在 `~/.lightclaw/active_skills/` 目录中。你也可以在 `~/.lightclaw/customized_skills/` 中创建自定义技能。

### 配置定时任务

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

```bash
# 管理定时任务
lightclaw cron

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

# 添加新定时任务
lightclaw cron add
```

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

### MCP 服务集成

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

1. 在 `~/.lightclaw/config.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 并清理工作区 |

全局选项：

```bash
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/
├── config.json              # 核心配置文件（供应商、模型、渠道凭证等）
├── jobs.json                # 定时任务定义
├── chats.json               # 对话历史记录
├── envs.json                # 持久化环境变量
├── active_skills/           # 已启用的技能
├── customized_skills/       # 用户自定义技能
├── custom_channels/         # 自定义渠道插件
└── memory/
    ├── MEMORY.md            # 长期记忆（LightClaw 从对话中学到的信息）
    ├── PROFILE.md           # 用户画像（你的偏好和习惯）
    └── YYYY-MM-DD.md        # 每日笔记
```

### 关键文件说明

- **`config.json`**：最核心的配置文件，包含 LLM 供应商设置、API Key、模型选择、渠道凭证等。建议通过 CLI 命令修改，也可以直接编辑。
- **`memory/`**：LightClaw 的记忆系统。MEMORY.md 存储长期记忆，PROFILE.md 存储用户画像，每日笔记自动记录。
- **`active_skills/`**：将技能文件夹放入此目录即可启用对应技能。
- **`customized_skills/`**：你自己创建的技能存放在这里。

---

## 🏗️ 系统架构

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

**请求处理流程：**

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

---

## 🖥️ 前端开发

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

```bash
# 进入前端项目目录
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

---

## ✅ 代码质量与测试

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

# Lint 检查
flake8 src/lightclaw/

# 类型检查
mypy src/lightclaw/

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

# 运行全部测试
pytest

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

---

## ❓ 常见问题

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

使用自定义端口启动：

```bash
lightclaw run --port 9090
```

### Q: 如何切换语言？

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

```bash
lightclaw config
```

### Q: 如何使用本地模型？

1. 安装对应的本地推理后端：
   ```bash
   pip install ".[llamacpp]"   # 或 ".[mlx]"（仅 macOS）
   ```
2. 通过 `lightclaw models` 命令切换到本地模型供应商
3. 选择或下载要使用的模型

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

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

```bash
lightclaw start
```

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

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

### Q: 数据存储在哪里？

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

---

## 📄 许可证

详见 [LICENSE](LICENSE) 文件。
