基于 Python + React 实现 AI 智能体框架 PyClaw

耶耶布丁

371人浏览 · 2026-05-15 18:36:57

耶耶布丁 · 2026-05-15 18:36:57 发布

摘要

本文是AI 智能体方向综合实训的完整复盘，从零实现了一款轻量、可本地运行的 AI 智能体框架 PyClaw。项目采用前后端分离架构，后端基于 Python 实现智能体核心、网关服务与工具调用，前端基于 React 18 开发 Web 可视化管理面板，通过 WebSocket 实现实时通信。

文章包含项目架构、核心模块实现、关键代码、踩坑总结、运行教程，并已将完整前后端源码开源至 Gitee，适合实训学习、课程设计、大模型应用开发参考。

一、项目背景与介绍

在大模型快速普及的今天，传统对话式 AI 已无法满足复杂任务需求。让 AI 自主思考、自主执行、自主反馈成为新的技术方向。

本实训项目基于 Python 构建 PyClaw 智能体框架，实现 LLM 工具调用、任务闭环执行、多渠道消息接入，并配套开发 React Web 管理子系统，完成从命令行到可视化界面的全流程实训目标。

项目亮点

本地优先、无需云端依赖
支持 LLM 自主思考 + 工具调用
前后端分离，WebSocket 实时通信
配套 React 可视化管理面板
完整工程结构，可直接运行、可扩展

项目开源地址（Gitee）

https://gitee.com/zhai-zhaoyang/pyclaw-intelligent-agent

二、整体技术架构

项目采用三层解耦架构，结构清晰、易于理解与扩展：

前端交互层：React + WebSocket 实现聊天界面、登录、状态展示
网关服务层：统一消息调度、WebSocket 服务、会话管理
智能体执行层：LLM 调用、工具集、记忆系统、龙虾循环

核心技术栈

后端：Python、Asyncio、Pydantic、WebSocket
前端：React 18、Hooks、CSS
通信：WebSocket 全双工实时通信
托管：Gitee 代码托管

三、核心模块实现

3.1 Agent 智能体循环（核心）

采用经典 Think → Act → Observe → Reflect 执行闭环：

Think：LLM 分析任务、规划步骤
Act：调用文件、命令、网络、定时等工具
Observe：收集执行结果
Reflect：判断任务是否完成
Repeat：多轮迭代直至结束

3.2 Gateway 网关服务

作为系统中枢，提供三大能力：

统一消息入口（CLI / Web / IM）
WebSocket 长连接服务（端口 18790）
会话管理、心跳、消息转发

3.3 Web 管理子系统（React）

严格按照实训要求实现：

用户登录模块
WebSocket 连接管理
实时对话界面
消息发送 / 接收 / 展示
连接状态监控

前端核心代码

jsx

useEffect(() => {
  const socket = new WebSocket('ws://127.0.0.1:18790');
  socket.onopen = () => setConnected(true);
  socket.onmessage = (e) => {
    const data = JSON.parse(e.data);
    setMessages(prev => [...prev, { sender: 'bot', content: data.content }]);
  };
  return () => socket.close();
}, []);

四、项目完整结构（已开源）

plaintext

pyclaw-intelligent-agent/
├── pyclaw/            # 智能体核心框架
├── webui/             # React 前端管理面板
├── workspace/         # 配置文件
├── pyproject.toml     # 依赖管理
├── LICENSE
└── README.md

五、实训踩坑总结（必看）

5.1 终端 Agent 输出两遍相同消息

原因：回调输出 + 主函数打印重复
解决：删除其中一处输出即可

5.2 create-react-app 内存溢出

报错：Zone Allocation failed
解决：set NODE_OPTIONS=--max-old-space-size=4096

5.3 WebSocket 连接失败

原因：Gateway 未启动 / 端口错误
解决：先运行 pyclaw gateway 再启动前端

六、快速运行教程

1. 克隆源码

bash

运行

git clone https://gitee.com/zhai-zhaoyang/pyclaw-intelligent-agent.git
cd pyclaw-intelligent-agent

2. 启动后端网关

bash

运行

pyclaw gateway

3. 启动 React 前端

bash

运行

cd webui
npm install
npm start

4. 访问系统

浏览器打开：http://localhost:3000

默认登录账号：admin / 123456

七、收获与总结

AI 智能体（Agent）工作原理与龙虾循环
Python 异步编程与消息队列
React Hooks 开发前端管理系统
WebSocket 实时通信机制
前后端分离项目架构设计
Gitee 项目托管与开源规范

本项目可直接作为课程设计、实训报告、大模型应用开发案例，后续可扩展多用户权限、技能商店、Docker 部署、多 IM 接入等能力。

八、运行截图说明

React 前端登录页面
WebSocket 连接成功界面
与 AI 智能体对话界面
因为博主自己配置的龙虾密码忘记了，暂时没有办法展示网关连接成功的演示，当时也没有截图保存，等后续把密码重置，重新配置之后再进行更新演示（PS：AI智能体问答只能先用飞书Open claw来演滥竽充数了嘿嘿）