mini-openclaw/QUICKREF.md

快速参考手册

🚀 5 分钟上手

第一次使用

# 1. 一键安装
install.bat

# 2. 启动后端（新终端窗口）
start-backend.bat

# 3. 启动前端（新终端窗口）
start-frontend.bat

# 4. 打开浏览器
http://localhost:3000

日常使用

# 终端 1：后端
cd backend
venv\Scripts\activate.bat
uvicorn app:app --host 0.0.0.0 --port 8002

# 终端 2：前端
npm run dev

📡 API 快速测试

健康检查

curl http://localhost:8002
# 返回: {"name":"mini OpenClaw","version":"0.1.0","status":"running"}

聊天接口

curl -X POST http://localhost:8002/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"你好","session_id":"test","stream":false}'

会话列表

curl http://localhost:8002/api/sessions

技能列表

curl http://localhost:8002/api/skills

RAG 模式开关

# 查看状态
curl http://localhost:8002/api/config/rag-mode

# 开启 RAG
curl -X PUT http://localhost:8002/api/config/rag-mode \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

💬 对话示例

基础对话

用户: 你好
Agent: 你好！我是 mini OpenClaw，很高兴为你服务 🤖

使用技能

用户: 查询北京的天气
Agent: 
  [工具调用: read_file("skills/get_weather/SKILL.md")]
  [工具调用: fetch_url("https://wttr.in/Beijing?format=j1")]
  北京当前天气：晴，温度 25°C，湿度 40%，东南风 3 级。

执行命令

用户: 列出当前目录的文件
Agent:
  [工具调用: terminal("dir")]
  当前目录包含以下文件：
  - app.py
  - api/
  - graph/
  ...

运行代码

用户: 用 Python 计算 1 到 100 的和
Agent:
  [工具调用: python_repl("sum(range(1, 101))")]
  结果是 5050

读取文件

用户: 读取 config.json 的内容
Agent:
  [工具调用: read_file("config.json")]
  配置文件内容：
  {
    "rag_mode": false
  }

🛠️ 常用命令

后端开发

# 激活虚拟环境
cd backend
venv\Scripts\activate.bat

# 安装新依赖
pip install package_name
pip freeze > requirements.txt

# 启动开发服务器（自动重载）
uvicorn app:app --host 0.0.0.0 --port 8002 --reload

# 查看日志
# 输出会直接显示在终端

前端开发

# 安装新依赖
npm install package_name

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 运行生产版本
npm start

调试技巧

# 检查后端是否运行
curl http://localhost:8002

# 检查前端是否运行
curl http://localhost:3000

# 查看 Python 包版本
cd backend
venv\Scripts\activate.bat
pip list

# 查看 Node 包版本
npm list

# 完整测试
test.bat

📁 关键文件位置

配置文件

• backend/.env - 环境变量（API key、模型配置）
• backend/config.json - 运行时配置（RAG 模式等）

身份定义

• backend/workspace/IDENTITY.md - Agent 身份信息
• backend/workspace/AGENTS.md - 操作指南和协议

记忆系统

• backend/memory/MEMORY.md - 长期记忆
• backend/sessions/*.json - 会话历史

技能定义

• backend/skills/*/SKILL.md - 各技能的定义文件

🔧 常见问题速查

后端启动失败

问题: ModuleNotFoundError: No module named 'xxx'

# 解决：重新安装依赖
cd backend
venv\Scripts\activate.bat
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

问题: Address already in use

# 解决：端口被占用，杀掉进程或换端口
# 查找进程
netstat -ano | findstr :8002
# 杀掉进程
taskkill /PID <进程号> /F
# 或换端口启动
uvicorn app:app --host 0.0.0.0 --port 8003

前端启动失败

问题: Error: Cannot find module 'next'

# 解决：重新安装依赖
npm install --registry=https://registry.npmmirror.com

问题: 前端无法连接后端

# 检查：
# 1. 后端是否在 8002 端口运行
curl http://localhost:8002

# 2. 检查浏览器控制台的错误信息

# 3. 确认 src/lib/api.ts 中的 API_BASE 配置正确

模型调用失败

问题: AuthenticationError 或 APIError

# 检查 backend/.env 配置：
# 1. DEEPSEEK_API_KEY 是否正确
# 2. DEEPSEEK_BASE_URL 是否可访问
# 3. DEEPSEEK_MODEL 名称是否正确

# 测试网关连通性
curl http://49.232.133.151/v1/models

RAG 检索不工作

# 1. 确认 RAG 模式已开启
curl http://localhost:8002/api/config/rag-mode

# 2. 重建索引（重启后端会自动重建）
# 或通过代码手动触发：
cd backend
venv\Scripts\activate.bat
python -c "from graph.memory_indexer import get_memory_indexer; from pathlib import Path; get_memory_indexer(Path('.')).rebuild_index()"

🎯 性能优化建议

后端

• 使用 --workers 4 启动多进程：uvicorn app:app --workers 4
• 开启 uvloop：pip install uvloop
• 使用 Redis 缓存会话（TODO）

前端

• 生产环境使用 npm run build + npm start
• 开启 Next.js 静态优化
• 使用 CDN 加速静态资源

模型

• 短对话用 deepseek-v4-flash（快）
• 复杂任务用 deepseek-v4-pro（准）
• 适当调整 temperature（创造性 0.7-1.0，精确性 0-0.3）

📚 进阶主题

自定义技能

创建 backend/skills/my_skill/SKILL.md:

---
name: my_skill
description: 我的自定义技能
---

# 我的技能

## 使用场景
当用户请求 XXX 时使用

## 执行步骤
1. 步骤一
2. 步骤二
3. 步骤三

## 示例
用户：XXX
Agent：[执行流程]

重启后端即可使用。

自定义工具

创建 backend/tools/my_tool.py:

from langchain_core.tools import tool

@tool
def my_tool(input: str) -> str:
    """工具描述"""
    # 实现
    return result

在 backend/tools/__init__.py 中注册：

from .my_tool import my_tool

def get_all_tools(base_dir):
    return [
        # ... 其他工具
        my_tool,
    ]

修改系统提示

编辑 backend/workspace/IDENTITY.md 和 AGENTS.md，重启后端生效。

🔗 相关链接

• 项目文档: README.md
• 架构说明: ARCHITECTURE.md
• 开发日志: DEVLOG.md
• LangChain 文档: https://python.langchain.com/
• LlamaIndex 文档: https://docs.llamaindex.ai/
• FastAPI 文档: https://fastapi.tiangolo.com/
• Next.js 文档: https://nextjs.org/docs

💡 提示与技巧

1. 技能优先: 复杂任务先定义技能（SKILL.md），再让 Agent 调用
2. 记忆管理: 重要信息让 Agent 写入 MEMORY.md，下次对话会记得
3. 会话管理: 不同主题用不同会话，保持上下文清晰
4. RAG 模式: 知识库内容多时开启 RAG，自动检索相关信息
5. 调试模式: 查看工具调用过程，理解 Agent 的思考路径
6. 流式体验: 保持 stream: true，获得更好的交互体验