Mini-OpenClaw 🦀

Mini-OpenClaw 是一个以文件为核心的 AI Agent 系统，具有透明的思维链展示、技能插件机制和 RAG 知识库检索能力。

开箱即用的本地 AI 助手，使用 DeepSeek / OpenAI 驱动，所有记忆和技能以文本文件存储，完全透明可控。

---

✨ 核心特性

• 🧠 透明思维链：Agent 的每一步推理、每次工具调用都实时展示给用户
• 📁 文件优先存储：会话记录、记忆、技能全部以文件形式保存，无需数据库
• 🔧 技能插件系统：在 backend/skills/*/SKILL.md 中定义自定义工具，自动加载
• 📚 RAG 知识库：基于 LlamaIndex 的混合检索（BM25 + 向量），支持本地文档问答
• 🌊 实时流式响应：基于 NDJSON 的流式传输协议，毫秒级响应
• 🚫 无云锁定：支持 DeepSeek、OpenAI 等多种 LLM，所有数据存本地

---

🏗️ 技术栈

层级	技术
前端	React 18 + Vite + TypeScript + Tailwind CSS + shadcn/ui
后端	Python + FastAPI + LangGraph + LangChain
AI	DeepSeek Chat（主模型）+ OpenAI Embeddings（向量检索）
RAG	LlamaIndex（BM25 + 向量混合检索）
存储	纯文件系统（JSON + Markdown）

---

🚀 快速开始

1. 克隆仓库

git clone https://github.com/YOUR_USERNAME/mini-openclaw.git
cd mini-openclaw

2. 配置环境变量

cp backend/.env.example backend/.env
# 编辑 backend/.env，填入你的 API Key

3. 启动后端

# 推荐使用 conda 环境
conda create -n langgraph python=3.11
conda activate langgraph

pip install -r backend/requirements.txt

# 从项目根目录启动（Windows 用户注意端口，见下方说明）
python -m uvicorn backend.app:app --reload --port 9000

4. 启动前端

cd frontend
npm install
npm run dev

5. 访问应用

服务	地址
前端应用	http://localhost:5173
后端 API	http://localhost:9000
Swagger 文档	http://localhost:9000/docs

---

📁 项目结构

mini-openclaw/
├── backend/
│   ├── app.py               # FastAPI 入口，路由 & CORS
│   ├── config.py            # LLM 配置 & 目录路径
│   ├── graph/agent.py       # LangGraph Agent 构建 & 流式处理
│   ├── sessions/            # 会话 JSON 文件存储
│   ├── memory/MEMORY.md     # 长期记忆（自动维护）
│   ├── skills/              # 技能插件目录
│   ├── tools/               # 内置工具（终端、Python REPL、RAG 等）
│   ├── workspace/           # System Prompt 文件（SOUL.md、IDENTITY.md 等）
│   ├── knowledge/           # RAG 知识库文档
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/Index.tsx        # 主布局（三栏：侧边栏 | 聊天 | 检视器）
│   │   ├── components/
│   │   │   ├── ChatStage.tsx      # 聊天界面 + 流式思维链展示
│   │   │   ├── AppSidebar.tsx     # 会话列表 + System Prompt 查看
│   │   │   └── InspectorPanel.tsx # 记忆/技能文件编辑器
│   │   ├── lib/store.tsx          # React Context 全局状态
│   │   └── api.ts                 # API 客户端（流式 fetch）
│   └── vite.config.ts
├── DEV_NOTES.md             # 开发踩坑记录（Windows 端口问题等）
└── CLAUDE.md                # AI 编程助手指导文档

---

🔧 添加自定义技能

在 backend/skills/ 下创建新目录和 SKILL.md 文件：

---
name: My Custom Skill
description: 描述这个技能的用途
---

# 使用说明

详细描述 Agent 如何使用这个技能...

技能在下次对话时自动加载，无需重启服务。

---

⚠️ Windows 用户注意

由于 Hyper-V / WSL2 端口保留机制，端口 8000/8080/8888 可能无法绑定：

• 后端请使用 端口 9000（--port 9000）
• 前端 vite.config.ts 中 host 使用 "localhost" 而非 "::"

详细排查方法见 DEV_NOTES.md。

---

📄 许可证

本项目基于 MIT License 开源。

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建 feature 分支：git checkout -b feature/amazing-feature
3. 提交变更：git commit -m 'feat: add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 发起 Pull Request