# LocalClaw

**Repository Path**: zhanglinglin22/local-claw

## Basic Information

- **Project Name**: LocalClaw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-22
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🦞 Claw AI - 本地轻量 AI 助手

纯本地、支持在线模型、超小体积、轻量化、开箱即用

## ✨ 特性

- ✅ 纯本地运行，无云端依赖
- ✅ 支持本地模型 API（Ollama / 本地兼容 OpenAI 格式）
- ✅ 支持在线模型 API（讯飞星火、百度千帆等）
- ✅ 超小体积，轻量化设计
- ✅ 开箱即用，无需复杂配置
- ✅ 美观的暗色主题 UI
- ✅ MCP 核心能力（联网 / 文件）
- ✅ 预制本地技能系统
- ✅ 支持深度思考模式
- ✅ 文件上传与读取（Excel、Word、PPT、PDF、文本、代码）
- ✅ 聊天历史记录管理
- ✅ 模型自由切换（本地/在线）
- ✅ 命令行识别与自动执行
- ✅ 终端自动执行开关
- ✅ 危险操作警告与自动停止
- ✅ 美化文件块样式
- ✅ 自动滚动与滚动到底部按钮
- ✅ TodoList 工具支持
- 🆕 **Electron 桌面应用** - 一键安装，无需配置 Python 环境

## 📁 项目结构

```
localClaw/
├── main.py              # 主程序（FastAPI 核心服务）
├── electron/            # Electron 桌面应用
│   ├── main.js         # Electron 主进程
│   ├── preload.js      # 预加载脚本
│   └── loading.html    # 启动加载页面
├── core/                # 核心模块（异常、日志、数据模型）
├── domain/              # 领域层（配置、模型、Agent 管理）
│   ├── agent/          # Agent 角色配置
│   ├── config/         # 配置管理
│   └── model/          # 模型管理
├── infrastructure/      # 基础设施层
│   ├── files/          # 文件读取器
│   ├── mcp/            # MCP 客户端
│   ├── search/         # 搜索引擎模块
│   └── tools/          # 本地工具集合
├── services/           # 业务服务层
│   ├── chat/          # 聊天服务
│   ├── file/          # 文件服务
│   ├── skill/         # 技能系统
│   ├── terminal/      # 终端服务
│   └── token/         # Token 管理服务
├── routes/            # API 路由层
├── templates/         # 前端 UI（Vue3 + Vite）
│   └── frontend/
│       └── src/       # 前端源代码
├── cache/             # 缓存目录
│   ├── chats/         # 聊天历史缓存
│   └── files/         # 上传文件缓存
├── requirements.txt   # Python 依赖
├── package.json       # Electron 配置
├── build-all.sh       # Mac/Linux 打包脚本
└── build-python.sh    # Python 后端打包脚本
```

## 🚀 快速开始

### 方式一：Electron 桌面应用（推荐）

1. **下载 DMG 文件**：从 `dist-electron/` 目录获取 `Claw AI-2.4.2-arm64.dmg` 文件
2. **安装应用**：双击 DMG 文件，将 Claw AI 拖入 Applications 文件夹
3. **运行应用**：在 Applications 文件夹中找到 Claw AI 并打开
4. **开始使用**：应用会自动启动后端服务并打开前端界面

### 方式二：源码运行（开发者）

#### 1. 安装依赖

```bash
pip3 install -r requirements.txt
```

#### 2. 启动服务

```bash
python3 main.py
```

#### 3. 访问界面

- 前端访问：http://localhost:13145/ui
- API 文档：http://localhost:13145/docs

## ⚙️ 模型配置

### 本地模型（Ollama）

默认配置对接 Ollama 本地模型：

- API 地址：`http://localhost:11434/v1`
- 模型名称：`qwen3.5`
- Temperature：`0.7`

### 在线模型

支持多种在线模型 API：

- **讯飞星火** - `https://spark-api-open.xf-yun.com/v1`
- **百度千帆** - `https://qianfan.baidubce.com/v2`

可在界面模型选择器中直接切换模型。

## 🎯 预置技能

- 📁 **文件管理** - 浏览和管理本地文件
- 📝 **MD 笔记** - 创建和编辑 Markdown 笔记
- 🧮 **计算器** - 执行数学计算
- 🔍 **联网搜索** - 搜索网络信息（支持 360、百度、必应）
- 💻 **代码解释** - 查看和解释代码文件
- ✅ **任务清单** - 创建和管理待办事项

## 🛠️ 可用工具

- `file_read` - 读取本地文件
- `file_write` - 写入本地文件
- `md_new` - 创建 Markdown 文件
- `md_list` - 列出 Markdown 文件
- `network_search` - 网络搜索
- `time` - 时间查询
- `calc` - 计算器
- `code_view` - 代码查看

## 📄 文件支持

支持上传和读取以下格式文件：

- Excel (.xlsx)
- Word (.docx)
- PPT (.pptx)
- PDF (.pdf)
- Markdown (.md)
- 文本文件 (.txt)

## 📋 配置说明

### 配置文件位置

所有配置文件位于 `domain/config/` 目录：

- `config.json` - 主配置文件
- `model_profiles.json` - 模型预设配置

### 主配置示例

```json
{
  "model": {
    "base_url": "http://localhost:11434/v1",
    "model_name": "千问 3.5",
    "model_type": "local",
    "temperature": 0.7,
    "api_key": ""
  },
  "models": [
    {
      "model_name": "千问 3.5",
      "model_type": "local",
      "base_url": "http://localhost:11434/v1"
    },
    {
      "model_name": "讯飞星火",
      "model_type": "online",
      "base_url": "https://spark-api-open.xf-yun.com/v1"
    }
  ],
  "mcp": {
    "network_enabled": true,
    "file_enabled": true
  },
  "rules": {
    "allowed_tools": [
      "file_read", "file_write", "md_new", "md_list",
      "network_search", "time", "calc", "code_view"
    ]
  }
}
```

## 🏗️ 技术栈

- **后端**: Python + FastAPI
- **前端**: Vue3 + Vite + Element Plus
- **桌面应用**: Electron 28
- **HTTP 客户端**: httpx
- **Markdown 渲染**: marked.js
- **文件处理**: openpyxl, python-docx, python-pptx, PyPDF2
- **打包工具**: PyInstaller + electron-builder

## 🖥️ 系统要求

### 桌面应用用户
- Mac OS 10.12+ 或 Windows 10+
- 4GB 内存以上
- 500MB 可用磁盘空间

### 开发者（源码运行）
- Python 3.8+
- Node.js 16+ (前端开发)
- 本地大模型服务（如 Ollama）
- 网络连接（用于网络搜索和在线模型）

## 🔒 安全说明

- 纯本地运行，无数据上传（使用本地模型时）
- 文件访问限制在安全目录内
- 支持工具调用白名单
- 无 API Key 也可使用（本地模型）

## 📝 更新日志

### v2.4.2
- ✅ 更新版本号为 2.4.2
- ✅ 优化 README.md 文档
- ✅ 添加项目优化文档
- ✅ 改进前端代码结构，使用更多 composables
- ✅ 修复聊天记录不显示的问题
- ✅ 优化聊天会话加载逻辑，优先加载有内容的会话
- ✅ 改进消息渲染和显示
- ✅ 移除 TIME 工具，后端直接在回答前运行时间获取代码
- ✅ 优化时间信息添加逻辑，确保每次提问都包含当前时间

### v2.4.1
- ✅ 修复 Markdown 渲染问题，支持 [markdown] 标签
- ✅ 修复 TodoList 工具渲染不完整的问题
- ✅ 修复 AI 消息加载状态问题
- ✅ 优化空行处理和列表渲染
- ✅ 改进流式传输中的数据处理

### v2.4.0
- ✅ 命令行识别与自动执行功能
- ✅ 终端自动执行开关
- ✅ 危险操作警告与自动停止
- ✅ 美化文件块样式，支持文件类型图标
- ✅ 自动滚动与滚动到底部按钮
- ✅ TodoList 工具支持
- ✅ 优化文件上传与显示
- ✅ 改进输入框 IME 处理
- ✅ 增强代码块识别
- ✅ 智能缓冲机制，避免重复输出
- ✅ 流式响应优化
- ✅ 话题变换处理优化
- ✅ 构建脚本完善
- ✅ Electron 桌面应用优化

### v2.0.0 - Electron 桌面应用版
- 🆕 **Electron 桌面应用** - 一键安装，无需 Python 环境
- 🆕 **启动加载页面** - 深色科技风主题，显示启动进度
- 🆕 **窗口控制** - 自定义关闭/最小化/最大化按钮
- 🆕 **配置文件独立** - 用户数据目录存储，与开发环境隔离
- 🆕 **自定义应用图标** - 使用 favicon 转换的.icns 图标
- 🆕 **后端打包** - Python 后端打包为独立可执行文件
- 🔧 优化上下文统计功能
- 🔧 修复 token 计算问题
- 🗑️ 清理无用文件和缓存

## 📄 许可证

MIT License

---

🦞 Have fun with Claw!