NanoClaw
基于 LLM 大语言模型的 AI 对话应用，支持工具调用、思维链、流式回复和工作目录隔离。
功能特性
- 多轮对话 - 支持上下文管理的多轮对话
- 工具调用 - 网页搜索、代码执行、文件操作等 13 个内置工具
- 思维链 - 支持链式思考推理（DeepSeek R1 / GLM thinking）
- 工作目录 - 项目级文件隔离，安全操作
- Token 统计 - 按日/周/月统计使用量
- 流式响应 - 实时 SSE 流式输出，穿插显示思考/文本/工具调用
- 代码编辑器 - 基于 CodeMirror 6，支持 15+ 语言语法高亮和暗色主题
- 多数据库 - 支持 MySQL、SQLite、PostgreSQL
- 多用户/单用户 - 支持单用户免登录和多用户 JWT 认证两种模式
快速开始
1. 安装依赖
conda create -n claw python=3.12
conda activate claw
pip install -e .
2. 配置
复制并编辑 config.yml：
# Port
backend_port: 3000
frontend_port: 4000
# Max agentic loop iterations (tool call rounds)
max_iterations: 15
# Sub-agent settings (multi_agent tool)
sub_agent:
max_iterations: 3 # Max tool-call rounds per sub-agent
max_concurrency: 3 # ThreadPoolExecutor max workers
# Available models
# Each model must have its own id, name, api_url, api_key
models:
- id: deepseek-chat
name: DeepSeek V3
api_url: https://api.deepseek.com/chat/completions
api_key: sk-xxx
- id: glm-5
name: GLM-5
api_url: https://open.bigmodel.cn/api/paas/v4/chat/completions
api_key: xxx
default_model: deepseek-chat
# Database Configuration
# Supported types: mysql, sqlite, postgresql
db_type: sqlite
# MySQL/PostgreSQL Settings (ignored for sqlite)
# db_host: localhost
# db_port: 3306
# db_user: root
# db_password: "123456"
# db_name: nano_claw
# SQLite Settings (ignored for mysql/postgresql)
db_sqlite_file: nano_claw.db
# Workspace Configuration
workspace_root: ./workspaces
# Authentication (optional, defaults to single-user mode)
# auth_mode: single # "single" (default) or "multi"
# jwt_secret: nano-claw-default-secret-change-in-production
说明：api_key 支持环境变量替换，例如 api_key: ${DEEPSEEK_API_KEY}。
3. 启动后端
python -m backend.run
4. 启动前端
cd frontend
npm install
npm run dev
项目结构
backend/
├── __init__.py # 应用工厂，数据库初始化，load_config()
├── config.py # 配置加载与验证
├── models.py # SQLAlchemy 数据模型
├── run.py # 入口文件
├── routes/ # API 路由
│ ├── auth.py # 认证（登录/注册/JWT/profile）
│ ├── conversations.py # 会话 CRUD
│ ├── messages.py # 消息 CRUD + 聊天（SSE 流式）
│ ├── models.py # 模型列表
│ ├── projects.py # 项目管理 + 文件操作
│ ├── stats.py # Token 使用统计
│ └── tools.py # 工具列表
├── services/ # 业务逻辑
│ ├── chat.py # 聊天补全服务（SSE 流式 + 多轮工具调用）
│ └── llm_client.py # OpenAI 兼容 LLM API 客户端
├── tools/ # 工具系统
│ ├── core.py # 核心类（ToolDefinition/ToolRegistry）
│ ├── factory.py # @tool 装饰器 + register_tool()
│ ├── executor.py # 工具执行器（缓存、去重、上下文注入）
│ ├── services.py # 辅助服务（搜索/抓取/计算）
│ └── builtin/ # 内置工具
│ ├── crawler.py # 网页搜索、抓取
│ ├── data.py # 计算器、文本、JSON 处理
│ ├── weather.py # 天气查询（模拟）
│ ├── file_ops.py # 文件操作（6 个工具，project_id 自动注入）
│ ├── agent.py # 多智能体（子 Agent 并发执行，工具权限隔离）
│ └── code.py # Python 代码执行（沙箱）
└── utils/ # 辅助函数
├── helpers.py # 通用函数（ok/err/build_messages 等）
└── workspace.py # 工作目录工具（路径验证、项目目录管理）
frontend/
└── src/
├── api/ # API 请求层（request + SSE 流解析）
├── components/ # Vue 组件（12 个）
├── composables/ # 组合式函数（主题/模态框/Toast）
└── utils/ # 工具模块（Markdown 渲染/代码高亮/图标）
工作目录系统
概述
工作目录系统为文件操作提供安全隔离，确保 AI 只能访问指定项目目录内的文件。
使用流程
- 创建项目 - 在侧边栏点击"新建项目"或上传文件夹
- 选择项目 - 在对话中选择当前工作目录
- 文件操作 - AI 自动在项目目录内执行文件操作（
project_id 由后端自动注入，对 AI 透明）
安全机制
- 所有文件工具的
project_id 由后端自动注入，AI 不可见也不可伪造
- 后端强制验证路径在项目目录内
- 阻止目录遍历攻击（如
../../../etc/passwd）
API 概览
认证
| 方法 |
路径 |
说明 |
GET |
/api/auth/mode |
获取当前认证模式 |
POST |
/api/auth/login |
用户登录 |
POST |
/api/auth/register |
用户注册 |
GET |
/api/auth/profile |
获取当前用户信息 |
PATCH |
/api/auth/profile |
更新当前用户信息 |
会话管理
| 方法 |
路径 |
说明 |
GET/POST |
/api/conversations |
会话列表 / 创建会话 |
GET |
/api/conversations/:id |
会话详情 |
PATCH |
/api/conversations/:id |
更新会话 |
DELETE |
/api/conversations/:id |
删除会话 |
消息管理
| 方法 |
路径 |
说明 |
GET |
/api/conversations/:id/messages |
消息列表 |
POST |
/api/conversations/:id/messages |
发送消息（SSE 流式） |
DELETE |
/api/conversations/:id/messages/:mid |
删除消息 |
POST |
/api/conversations/:id/regenerate/:mid |
重新生成消息 |
项目管理
| 方法 |
路径 |
说明 |
GET/POST |
/api/projects |
项目列表 / 创建项目 |
GET/PUT/DELETE |
/api/projects/:id |
项目详情 / 更新 / 删除 |
POST |
/api/projects/upload |
上传文件夹作为项目 |
GET |
/api/projects/:id/files |
列出项目文件 |
GET/PUT/PATCH/DELETE |
/api/projects/:id/files/:path |
文件 CRUD |
POST |
/api/projects/:id/directories |
创建目录 |
POST |
/api/projects/:id/search |
搜索文件内容 |
其他
| 方法 |
路径 |
说明 |
GET |
/api/models |
获取可用模型列表 |
GET |
/api/tools |
获取工具列表 |
GET |
/api/stats/tokens |
Token 使用统计 |
内置工具
| 分类 |
工具 |
说明 |
| 爬虫 |
web_search, fetch_page, crawl_batch |
网页搜索和抓取 |
| 数据处理 |
calculator, text_process, json_process |
数学计算和文本处理 |
| 代码执行 |
execute_python |
沙箱环境执行 Python |
| 文件操作 |
file_read, file_write, file_delete, file_list, file_exists, file_mkdir |
project_id 自动注入 |
| 天气 |
get_weather |
天气查询（模拟） |
| 智能体 |
multi_agent |
派生子 Agent 并发执行（禁止递归，工具权限与主 Agent 一致） |
文档
- 后端设计 - 架构设计、数据模型、API 文档、SSE 事件
- 工具系统 - 工具开发指南、安全设计
技术栈
- 后端: Python 3.10+, Flask, SQLAlchemy, requests
- 前端: Vue 3, Vite 6, CodeMirror 6, marked, highlight.js, KaTeX
- LLM: 支持任何 OpenAI 兼容 API（DeepSeek、GLM、OpenAI、Moonshot、Qwen 等）
ViperEkura
2a6c82b3ba