# mini-openclaw

**Repository Path**: tujiaw/mini-openclaw

## Basic Information

- **Project Name**: mini-openclaw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mini-OpenClaw

一个基于 Python 重构的、轻量级且高度透明的 AI Agent 系统。

## 项目特点

- **文件即记忆**：所有记忆以人类可读的 Markdown/JSON 文件形式存储
- **技能即插件**：通过文件夹结构管理能力，实现"拖入即用"的技能扩展
- **透明可控**：所有的 System Prompt、工具调用、记忆操作完全透明

## 技术栈

- **后端**：Python 3.10+, FastAPI, LangChain (最新版), LangGraph, LlamaIndex
- **前端**：Next.js 15+ (App Router), TypeScript, Shadcn/UI, TailwindCSS, Monaco Editor
- **存储**：本地文件系统

## 快速开始

### 1. 安装后端依赖

```bash
cd backend
pip install -r requirements.txt
```

### 2. 配置后端

```bash
cd backend
cp config.example.json config.json
# 编辑 config.json，填入 API Key、模型等（见文件内 llm 段）
```

**重要**：`config.json` 位于 `backend/` 目录，含敏感信息，勿提交到版本库。

### 3. 启动后端服务

```bash
cd backend
python run.py
```

**重要**：后端服务必须从 `backend/` 目录启动。

后端服务将在 `http://localhost:8002` 运行。

### 4. 配置前端环境变量

```bash
cd frontend
cp .env.local.example .env.local
```

### 5. 安装前端依赖

```bash
cd frontend
npm install
```

### 6. 启动前端开发服务器

```bash
cd frontend
npm run dev
```

前端界面将在 `http://localhost:3000` 运行。

## 项目结构

```
min-openclaw/
├── backend/              # 后端代码
│   ├── api/             # FastAPI 应用
│   ├── core/            # 核心模块
│   │   ├── agent.py     # Agent 核心实现
│   │   ├── config.py    # 配置管理
│   │   ├── tools.py     # 5 个核心工具
│   │   ├── memory.py    # 记忆管理
│   │   └── skills.py    # 技能管理
│   ├── skills/          # Agent Skills
│   │   └── get_weather/ # 示例技能
│   ├── workspace/       # 记忆与工作区 Markdown
│   │   ├── SOUL.md             # 核心设定
│   │   ├── IDENTITY.md         # 自我认知
│   │   ├── USER.md             # 用户画像
│   │   ├── AGENTS.md           # 行为准则
│   │   └── memory/             # 长期记忆（YYYY-MM-DD.md 分文件）
│   ├── storage/         # RAG 索引存储
│   ├── knowledge/       # 知识库文档
│   ├── data/            # 数据目录（SQLite 等）
│   ├── logs/            # 日志目录
│   ├── config.json      # 后端主配置（复制自 config.example.json）
├── frontend/            # 前端代码 (Next.js)
│   ├── src/
│   │   ├── app/         # Next.js App Router
│   │   ├── components/  # React 组件
│   │   │   ├── chat/    # 聊天相关组件
│   │   │   └── editor/  # Monaco 编辑器封装
│   │   └── lib/         # 工具函数和 API 封装
│   └── public/
└── CLAUDE.md            # 项目 PRD
```

## 核心功能

### 5 个核心工具

1. **terminal** - 执行 Shell 命令（受限环境）
2. **python_repl** - 执行 Python 代码
3. **fetch_url** - 获取网页内容
4. **read_file** - 读取本地文件
5. **search_knowledge_base** - RAG 检索

### 浏览器自动化 🌐

Mini-OpenClaw 通过专用工具 **[agent_browser](https://github.com/vercel-labs/agent-browser)** 直接调用 `agent-browser` CLI（子进程，不经通用 `terminal`）。在对话中应使用 `agent_browser` 传入与终端中 `agent-browser …` 一致的参数，例如 `open https://example.com`、`snapshot -i`、`fill @e1 "text"` 等。

#### 安装浏览器支持

```bash
# 安装 agent-browser
npm install -g agent-browser

# 初始化（下载 Chromium，约 300MB）
agent-browser install
```

详细安装说明请查看：[docs/AGENT_BROWSER_INSTALL.md](docs/AGENT_BROWSER_INSTALL.md)

#### 使用示例

```
用户：打开 Hacker News 并告诉我前三个头条

Agent 会自动：
1. 打开 https://news.ycombinator.com
2. 获取页面快照
3. 提取前三个标题
4. 返回给用户
```

### Agent Skills 系统

Skills 位于 `backend/skills/` 目录，每个技能是一个包含 `SKILL.md` 文件的文件夹。

创建新技能：
1. 在 `backend/skills/` 下创建新文件夹
2. 创建 `SKILL.md` 文件，包含 YAML frontmatter 和技能说明
3. Agent 启动时会自动发现并加载

### 记忆系统

- System Prompt 由 6 个文件动态拼接
- 所有会话历史存储为 JSON 文件
- 用户可直接编辑记忆文件来"重新编程" Agent

## API 端点

- `POST /api/chat` - 发送消息（支持 SSE 流式输出）
- `GET /api/sessions` - 获取所有会话
- `GET /api/sessions/{id}` - 获取会话详情
- `DELETE /api/sessions/{id}` - 删除会话
- `GET /api/files` - 读取文件
- `POST /api/files` - 保存文件
- `POST /api/skills/refresh` - 刷新技能列表

## 开发路线

- [x] 项目框架搭建
- [x] 核心 Agent 实现
- [x] 5 个 Core Tools 集成
- [x] Skills 系统实现
- [x] 记忆管理实现
- [x] FastAPI 后端
- [x] Next.js 前端基础界面 (IDE 风格)
- [x] agent-browser 浏览器自动化集成
- [ ] 完善 RAG 检索功能
- [ ] 添加更多示例技能
- [ ] 性能优化和测试

## 许可证

MIT