# openclaw_py

**Repository Path**: wisdomfriend/openclaw_py

## Basic Information

- **Project Name**: openclaw_py
- **Description**: 手搓python版本的openclaw
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 龙虾

## README



# openclaw_py

手搓 Python 版本的 OpenClaw（博客系列配套工程）。

## 项目简介

openclaw_py 是一个基于 Python 的 AI Agent 框架实现，旨在构建一个轻量级的 Agent 系统。项目目前处于阶段一，完成了最小闭环的核心基础设施建设，包括 FastAPI 网关、会话管理、Agent 循环占位和工具运行时。

## 当前阶段

- **阶段一：最小闭环**
  - FastAPI 网关
  - SessionManager（会话锁 + 全局并发上限）
  - Agent Loop（占位实现）
  - Tool Runtime（占位实现）

## 快速开始

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

# 激活虚拟环境 (Linux/Mac)
source .venv/bin/activate

# 激活虚拟环境 (Windows)
.venv\Scripts\activate

# 安装依赖
pip install -e ".[dev]"

# 启动服务
python run.py
```

访问以下地址：

- 健康检查：`http://127.0.0.1:7788/health`
- API 文档：`http://127.0.0.1:7788/docs`

## 目录结构

```
openclaw_py/
├─ app/
│  ├─ api/          # API 路由层
│  │  ├─ router.py
│  │  └─ routes_chat.py
│  ├─ core/         # 核心逻辑
│  │  ├─ agent.py
│  │  ├─ llm_provider.py
│  │  └─ tools.py
│  ├─ memory/       # 记忆层
│  │  └─ store.py
│  ├─ scheduler/    # 调度器
│  ├─ session/      # 会话管理
│  │  └─ manager.py
│  ├─ config.py     # 配置
│  └─ main.py      # 入口
├─ tests/           # 测试
└─ pyproject.toml   # 项目配置
```

## 核心模块

### SessionManager

会话管理器，负责管理会话生命周期和并发控制：

- 支持会话级别的锁机制，保证同一会话的请求串行处理
- 全局并发上限控制，默认 4 个并发
- 提供 `acquire` 异步上下文管理器

### Agent

AI Agent 核心类，负责处理对话逻辑：

- 支持自定义 LLM Provider
- 提供 `chat` 方法处理用户消息

### LLMProvider

LLM 提供者抽象接口：

- 定义 `complete` 方法用于生成回复
- 内置 EchoProvider 作为测试用占位实现

### ToolRegistry

工具注册表：

- 支持动态注册工具函数
- 提供 `run` 方法执行工具

### MarkdownMemoryStore

基于 Markdown 的记忆存储：

- 支持追加文本内容
- 基于文件系统的持久化存储

## API 接口

### 健康检查

```
GET /health
```

### 聊天接口

```
POST /chat
```

请求体：

```json
{
  "message": "你好",
  "session_id": "optional-session-id"
}
```

响应：

```json
{
  "reply": "回复内容",
  "session_id": "session-id"
}
```

## 下一步开发

- 接入真实 LLM Provider（OpenAI Compatible）
- 增加工具调用协议与多轮循环
- 记忆层（短期窗口 + 长期持久化）
- PostgreSQL + pgvector（阶段二）

## 技术栈

- Python 3.10+
- FastAPI
- Pydantic
- asyncio

## License

MIT License