安装指南 — OnlyClaw 小龙虾 AI 助手

总览

OnlyClaw 由后端 API、Web 前端、移动端（UniApp）和桌面端（Python）四部分组成。根据你要使用的端，需要安装不同的依赖。

依赖速查表

组件	用途	必须?	版本要求
PHP	后端 API 服务	必须	≥ 7.4
MySQL	数据库存储	必须	≥ 8.0（推荐 9.x）
Python	桌面端运行	桌面端需要	≥ 3.8
Node.js	移动端开发构建	移动端需要	≥ 14
HBuilderX	UniApp IDE	移动端开发需要	最新版
现代浏览器	Web 端访问	Web 端需要	Chrome / Edge / Firefox

Python 依赖包速查表

包名	用途	必须?
`PyQt5`	桌面端 UI 框架	桌面端必须
`PyQtWebEngine`	内嵌浏览器组件	桌面端必须
`requests`	HTTP 请求库	桌面端必须
`mss`	屏幕截图捕获	录屏功能需要
`opencv-python`	视频编码写入	录屏功能需要
`pyperclip`	剪贴板操作	微信监控需要

PHP 安装

PHP 是 OnlyClaw 后端的运行环境，负责处理所有 API 请求、数据库操作和 AI 接口调用。

Windows 安装

下载 PHP

访问 PHP for Windows 官方下载页：

下载地址 https://windows.php.net/download/

选择 VS16 x64 Thread Safe 版本（推荐 PHP 8.2.x 或 8.3.x）
下载 ZIP 压缩包（如 php-8.3.6-Win32-vs16-x64.zip）
文件大小约 25-30 MB

版本选择提示 OnlyClaw 要求 PHP ≥ 7.4，推荐使用 PHP 8.2 或 8.3。选择 Thread Safe 版本以获得更好的性能。

解压并配置

解压到目录（如 C:\tools\php），然后：

复制 php.ini-development 为 php.ini
编辑 php.ini，取消注释以下扩展：

php.ini

; 必须启用的扩展
extension=pdo_mysql
extension=curl
extension=json
extension=mbstring
extension=openssl
extension=fileinfo

; 可选：文件上传大小限制
upload_max_filesize = 50M
post_max_size = 50M

添加到 PATH

将 PHP 目录添加到系统环境变量 PATH 中：

右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
在「系统变量」中找到 Path，点击「编辑」
点击「新建」，添加 PHP 目录路径（如 C:\tools\php）
点击「确定」保存所有对话框
打开新的命令行窗口（必须新开窗口），运行验证命令

CMD

# 验证 PHP 安装
php -v
# 预期输出类似：
# PHP 8.3.6 (cli) (built: Apr 10 2024 14:21:20) (ZTS Visual C++ 2019 x64)
# Copyright (c) The PHP Group
# ...

# 验证必要扩展
php -m | findstr pdo_mysql
# 预期输出：pdo_mysql

php -m | findstr curl
# 预期输出：curl

# 检查所有扩展
php -m
# 确保列表中包含：pdo_mysql, curl, json, mbstring, openssl, fileinfo

macOS 安装

Bash

# 使用 Homebrew 安装
brew install php

# 验证安装
php -v

Linux (Ubuntu/Debian) 安装

Bash

# 更新包管理器
sudo apt update

# 安装 PHP 及必要扩展
sudo apt install php php-cli php-mysql php-curl php-json php-mbstring php-xml php-zip

# 验证安装
php -v

必需的 PHP 扩展

扩展	用途	说明
`pdo_mysql`	数据库连接	PDO 方式连接 MySQL，所有数据库操作依赖此扩展
`curl`	HTTP 请求	调用 AI API 接口（流式和非流式）依赖此扩展
`json`	JSON 处理	API 请求/响应的 JSON 编解码
`mbstring`	多字节字符串	中文等多字节字符的正确处理
`openssl`	加密	HTTPS 请求和 JWT 签名
`fileinfo`	文件类型检测	上传文件时自动检测 MIME 类型

MySQL 安装

MySQL 是 OnlyClaw 的数据存储引擎，存储用户、对话、笔记、任务、记忆等所有数据。

Windows 安装

下载 MySQL

访问 MySQL Community Server 官方下载页：

下载地址 https://dev.mysql.com/downloads/mysql/

选择操作系统为 Windows
选择 Windows (x86, 64-bit), ZIP Archive（推荐免安装版）
或选择 Windows (x86, 64-bit), MSI Installer（图形化安装向导）
推荐版本：MySQL 8.0.x 或 9.x
文件大小约 200-300 MB

下载提示 页面底部有 "No thanks, just start my download" 链接，点击即可直接下载，无需登录。

解压并配置

解压到目录（如 C:\tools\mysql\mysql-9.6.0-winx64），创建配置文件 my.ini：

INI

[mysqld]
basedir=C:/tools/mysql/mysql-9.6.0-winx64
datadir=C:/tools/mysql/mysql-9.6.0-winx64/data
port=3306
character-set-server=utf8mb4
collation-server=utf8mb4_unicode_ci

[client]
default-character-set=utf8mb4

初始化并启动

CMD

# 初始化数据库（生成 data 目录和初始密码）
mysqld --initialize --console
# 记下输出中的临时密码，如: A temporary password is generated for root@localhost: xxx

# 安装为 Windows 服务
mysqld --install MySQL

# 启动服务
net start MySQL

# 登录并修改密码
mysql -u root -p
# 输入临时密码后执行：
ALTER USER 'root'@'localhost' IDENTIFIED BY '你的新密码';
FLUSH PRIVILEGES;

添加到 PATH

将 MySQL 的 bin 目录（如 C:\tools\mysql\mysql-9.6.0-winx64\bin）添加到系统 PATH 环境变量。

右键「此电脑」→「属性」→「高级系统设置」→「环境变量」
在「系统变量」中找到 Path，点击「编辑」
点击「新建」，添加 MySQL 的 bin 目录路径
点击「确定」保存

CMD

# 验证 MySQL 安装
mysql --version
# 预期输出类似：
# mysql  Ver 9.6.0 for Win64 on x86_64 (MySQL Community Server - GPL)

# 测试连接
mysql -u root -p -e "SELECT VERSION();"
# 输入密码后应显示 MySQL 版本号

# 查看服务状态（Windows 服务管理器）
sc query MySQL
# 或使用命令行
net start | findstr MySQL

macOS 安装

Bash

# 使用 Homebrew 安装
brew install mysql

# 启动 MySQL 服务
brew services start mysql

# 安全初始化（设置 root 密码等）
mysql_secure_installation

Linux (Ubuntu/Debian) 安装

Bash

# 安装 MySQL
sudo apt update
sudo apt install mysql-server

# 启动服务
sudo systemctl start mysql
sudo systemctl enable mysql

# 安全初始化
sudo mysql_secure_installation

Python 安装

Python 是桌面端的运行环境，用于运行桌面宠物和原生 UI 应用。仅桌面端需要。

Windows 安装

下载 Python

访问 Python 官方下载页：

下载地址 https://www.python.org/downloads/

点击黄色大按钮 "Download Python 3.x.x" 下载最新版本
或点击下方 "Windows installer (64-bit)" 链接
推荐版本：Python 3.10 或 3.11（兼容性最好）
文件大小约 25-30 MB

安装时重要选项

必须勾选 "Add Python to PATH"（添加到环境变量）
选择 "Customize installation"（自定义安装）
确保 "pip" 选项被勾选
建议勾选 "Install for all users"

验证安装

CMD

# 验证 Python
python --version
# 应输出: Python 3.8.x 或更高

# 验证 pip
pip --version
# 应输出: pip 23.x.x

安装依赖包

打开命令行，执行以下命令安装所有桌面端依赖：

CMD

# 核心依赖（桌面端必须）
pip install PyQt5 PyQtWebEngine requests

# 录屏功能依赖
pip install mss opencv-python

# 剪贴板监控（微信监控功能需要）
pip install pyperclip

验证依赖安装

逐个验证每个依赖包是否安装成功：

Python

# 方法一：在 Python 交互环境中测试
python
>>> import PyQt5
>>> print("PyQt5 OK")
>>> import requests
>>> print("requests OK")
>>> import mss
>>> print("mss OK")
>>> import cv2
>>> print("opencv OK")
>>> import pyperclip
>>> print("pyperclip OK")
>>> exit()

# 方法二：使用 pip 查看已安装的包
pip list | findstr PyQt5
# 预期输出：PyQt5           5.15.x

pip list | findstr requests
# 预期输出：requests        2.31.x

# 方法三：检查包版本
python -c "import PyQt5; print(PyQt5.QtCore.PYQT_VERSION_STR)"
# 预期输出：5.15.9 或更高

python -c "import requests; print(requests.__version__)"
# 预期输出：2.31.0 或更高

验证技巧 如果 import 报错 "ModuleNotFoundError"，说明该包未安装成功。尝试使用国内镜像重新安装： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名

依赖包说明

包名	版本	大小	用途	安装命令
`PyQt5`	5.15+	~50MB	桌面端 UI 框架，提供窗口、按钮、输入框等所有界面组件	`pip install PyQt5`
`PyQtWebEngine`	5.15+	~80MB	内嵌 Chromium 浏览器组件，用于在桌面应用中显示网页内容	`pip install PyQtWebEngine`
`requests`	2.28+	~100KB	HTTP 请求库，用于调用 OnlyClaw API 接口	`pip install requests`
`mss`	9.0+	~50KB	高性能屏幕截图库，用于录屏功能的屏幕捕获	`pip install mss`
`opencv-python`	4.8+	~50MB	计算机视觉库，用于录屏功能的视频编码和写入	`pip install opencv-python`
`pyperclip`	1.8+	~20KB	跨平台剪贴板操作库，用于微信聊天监控的消息捕获	`pip install pyperclip`

💡 国内加速 如果下载速度慢，可以使用国内镜像源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyQt5 PyQtWebEngine requests mss opencv-python pyperclip

macOS / Linux 安装

Bash

# macOS 使用 Homebrew 安装 Python
brew install python3

# Linux 安装 Python
sudo apt install python3 python3-pip

# 安装依赖包（所有系统通用）
pip3 install PyQt5 PyQtWebEngine requests mss opencv-python pyperclip

Node.js 安装

Node.js 用于 UniApp 移动端的开发和构建。仅移动端开发需要。

Windows 安装

下载 Node.js

访问 Node.js 官方下载页：

下载地址 https://nodejs.org/

首页会自动推荐 LTS（长期支持版），直接点击绿色按钮下载
选择 Windows Installer (.msi) 64-bit
推荐版本：Node.js 18.x 或 20.x LTS
文件大小约 30-40 MB

安装选项

勾选 "Add to PATH"（自动添加到环境变量）
勾选 "Install necessary tools"（安装编译工具，可选）
其他选项保持默认即可

验证安装

打开新的命令行窗口，运行以下命令验证：

CMD

# 验证 Node.js
node --version
# 预期输出：v18.x.x 或 v20.x.x

# 验证 npm（随 Node.js 自动安装）
npm --version
# 预期输出：9.x.x 或 10.x.x

# 验证 npx（npm 包执行器）
npx --version
# 预期输出：与 npm 版本相同

# 测试 npm 是否能正常下载包
npm list -g --depth=0
# 列出全局安装的包

配置 npm 镜像（可选，国内加速）

CMD

# 设置淘宝镜像源
npm config set registry https://registry.npmmirror.com

macOS / Linux 安装

Bash

# macOS
brew install node

# Linux (Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

HBuilderX 安装

HBuilderX 是 DCloud 推出的 IDE，是 UniApp 移动端开发的官方推荐工具。仅移动端开发需要。

安装步骤

下载 HBuilderX

访问 HBuilderX 官方下载页：

下载地址 https://www.dcloud.io/hbuilderx.html

选择 App 开发版（包含 UniApp 开发插件，约 400-500 MB）
或选择 标准版（约 200 MB，需手动安装插件）
下载 ZIP 压缩包，解压到任意目录即可使用，无需安装
解压后运行 HBuilderX.exe 启动

版本选择 开发 OnlyClaw 移动端必须选择 App 开发版，它内置了 UniApp 编译器和相关插件。

安装 UniApp 插件

首次打开 HBuilderX 后，需要安装必要的插件：

点击菜单 「工具」→「插件安装」
在插件列表中找到并安装以下插件：

插件名称	必须?	用途
uni-app(Vue2)编译器	必须	编译 UniApp 项目为各平台代码
App真机运行插件	真机调试需要	连接手机进行真机调试
微信开发者工具插件	微信小程序需要	调用微信开发者工具编译小程序
App云打包插件	发布 App 需要	云端打包生成安装包

App 开发版 如果下载的是 App 开发版，"uni-app(Vue2)编译器" 通常已内置，无需额外安装。

导入项目

点击「文件」→「打开目录」
选择 OnlyClaw 项目中的 uniapp/ 目录
等待索引完成

ℹ️ 微信小程序 如果要发布到微信小程序，还需要下载并安装微信开发者工具。

快速启动

Windows 一键启动（Web 端）

下载项目

将 OnlyClaw 项目文件放到本地目录，例如 D:\AIcode\OnlyClaw。确保目录结构完整，包含 api/、web/、database/ 等文件夹。

创建数据库

打开命令行（CMD 或 PowerShell），登录 MySQL 并创建数据库：

SQL

-- 登录 MySQL（使用 root 用户）
mysql -u root -p
# 输入 root 密码后进入 MySQL 命令行

-- 创建数据库（使用 utf8mb4 支持中文和 emoji）
CREATE DATABASE claw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建专用用户（推荐，安全性更好）
CREATE USER 'claw'@'localhost' IDENTIFIED BY 'your_password';
-- 将 'your_password' 替换为你的密码

-- 授权用户访问 claw 数据库
GRANT ALL PRIVILEGES ON claw.* TO 'claw'@'localhost';
FLUSH PRIVILEGES;

-- 验证数据库创建成功
SHOW DATABASES;
-- 应该能看到 claw 数据库

-- 退出 MySQL
exit;

密码设置 请将 your_password 替换为你自己的密码，并记住这个密码，后续配置需要用到。

导入表结构

在命令行中执行以下命令导入数据库表结构：

CMD

# 进入项目目录
cd D:\AIcode\OnlyClaw

# 导入表结构（使用刚创建的 claw 用户）
mysql -u claw -p claw < database/schema.sql
# 输入 claw 用户的密码

# 验证表创建成功
mysql -u claw -p claw -e "SHOW TABLES;"
# 预期输出应包含：users, ai_providers, conversations, messages, notes, tasks, solutions, settings, files, memories

修改数据库配置

编辑 api/config/database.php 文件，修改数据库连接信息：

PHP

<?php
define('DB_HOST', '127.0.0.1');      // 数据库主机
define('DB_PORT', '3306');            // 数据库端口
define('DB_NAME', 'claw');            // 数据库名
define('DB_USER', 'claw');            // 你的数据库用户名
define('DB_PASS', 'your_password');   // 你的数据库密码
?>

将 DB_USER 和 DB_PASS 修改为你在上一步创建的用户名和密码。

启动服务

双击项目根目录的 start.bat 文件，自动完成所有启动步骤：

停止所有旧的 PHP 进程
检查 MySQL 是否在运行，如果没有则自动启动
启动 PHP 内置服务器，监听 8080 端口

启动成功后，命令行窗口会显示：

Text

============================
  访问地址:
  http://127.0.0.1:8080/web/
============================
  按 Ctrl+C 停止
============================

在浏览器中访问 http://127.0.0.1:8080/web/ 即可使用 OnlyClaw。

手动启动（任意系统）

Bash

# 1. 进入项目目录
cd /path/to/OnlyClaw

# 2. 导入数据库表结构
mysql -u claw -p claw < database/schema.sql

# 3. 启动 PHP 内置服务器
php -S 127.0.0.1:8080 api/router.php

# 4. 浏览器访问
# Web: http://127.0.0.1:8080/web/
# API: http://127.0.0.1:8080/api/

start.bat 详解

Windows 一键启动脚本会自动执行以下操作：

停止所有旧的 PHP 进程（taskkill /F /IM php.exe）
检查 MySQL 是否在运行，如果没有则自动启动
启动 PHP 内置服务器，监听 8080 端口
显示访问地址和停止提示

项目结构

Text

OnlyClaw/
├── start.bat                      # Windows 一键启动（MySQL + PHP 服务器）
├── database/
│   ├── schema.sql                 # 全部数据库表 DDL
│   └── init_data.sql              # 种子数据（已注释，可选导入）
│
├── api/                           # PHP 后端 API
│   ├── index.php                  # 入口文件 + 路由注册
│   ├── router.php                 # PHP 内置服务器路由文件
│   ├── config/
│   │   └── database.php           # 数据库连接配置
│   ├── controllers/               # 控制器（处理业务逻辑）
│   │   ├── AuthController.php     # 认证：注册、登录、用户信息
│   │   ├── ChatController.php     # 对话：创建对话、发送消息、SSE 流式
│   │   ├── NoteController.php     # 笔记：CRUD、搜索、拖拽排序
│   │   ├── TaskController.php     # 任务：CRUD、筛选、到期提醒
│   │   ├── FileController.php     # 文件：上传、下载、预览、删除
│   │   ├── SolutionController.php # 方案：AI 生成、列表、评分
│   │   ├── SettingsController.php # 设置：读写用户设置
│   │   ├── ProviderController.php # AI 配置：增删改查、测试连接
│   │   └── MemoryController.php   # 记忆：CRUD、搜索、自动提取、上下文
│   ├── services/
│   │   ├── AIService.php          # AI 统一服务（调用各模型 API）
│   │   └── ContextBuilder.php     # 上下文构建器（检索+注入+Token预算）
│   ├── utils/
│   │   ├── response.php           # JSON 响应、CORS 头、SSE 推送
│   │   └── jwt.php                # JWT 签发和验证（HS256）
│   ├── middleware/
│   │   └── auth.php               # 认证中间件（解析 Token）
│   └── storage/
│       └── uploads/               # 用户上传文件存储目录
│
├── web/                           # Web 端 SPA
│   ├── index.html                 # 主页面
│   ├── css/
│   │   └── style.css              # 全局样式（~1560 行）
│   └── js/
│       ├── api.js                 # API 请求封装
│       ├── app.js                 # 主应用逻辑、路由、登录注册
│       ├── chat.js                # AI 对话模块
│       ├── notes.js               # 笔记模块
│       ├── tasks.js               # 任务模块
│       ├── files.js               # 文件模块
│       ├── memory.js              # 记忆模块
│       └── settings.js            # 设置和方案模块
│
├── uniapp/                        # 移动端（UniApp + Vue 2）
│   ├── pages/
│   │   ├── login/                 # 登录注册页
│   │   ├── chat/                  # AI 对话页
│   │   ├── notes/                 # 笔记列表 + 编辑器
│   │   ├── tasks/                 # 任务列表 + 编辑器
│   │   ├── files/                 # 文件管理页
│   │   └── settings/              # 设置 + 记忆管理
│   ├── App.vue                    # 应用入口
│   ├── main.js                    # 主配置
│   ├── manifest.json              # 应用配置
│   └── pages.json                 # 页面路由配置
│
└── desktop/                       # 桌面端（Python + PyQt5）
    ├── pet.py                     # 桌面宠物入口（生命周期管理）
    ├── desktop_app.py             # 主应用（所有 UI 页面 + 35+ 工具）
    ├── pet.svg                    # 小龙虾 SVG 矢量图
    ├── wechat_icon.svg            # 微信功能图标
    ├── bookmarks.json             # 书签数据文件
    ├── run.bat                    # 桌面端启动脚本
    └── video/                     # 录屏文件输出目录

数据库配置

OnlyClaw 使用 MySQL 数据库，共 10 张核心表。所有子表通过外键关联到 users 表，删除用户时自动级联删除所有相关数据。

数据库表一览

表名	说明	关键字段	特殊索引
`users`	用户表	username, password_hash, nickname, avatar	username UNIQUE
`ai_providers`	AI 配置表	provider_type, api_key, api_url, model_name, is_default, is_primary	—
`conversations`	对话表	user_id, provider_id, title, system_prompt	—
`messages`	消息表	conversation_id, role, content(mediumtext), tokens_used	—
`notes`	笔记表	title, content(mediumtext), category, tags, is_pinned, sort_order	FULLTEXT(title, content)
`tasks`	任务表	title, description, status, priority, due_date, completed_at	—
`solutions`	解决方案表	title, problem, solution(mediumtext), tags, rating(0-5)	—
`settings`	设置表	setting_key, setting_value	UNIQUE(user_id, setting_key)
`files`	文件表	original_name, stored_name, mime_type, file_size, category	—
`memories`	记忆表	memory_type, title, content, importance, access_count, expires_at, is_active	FULLTEXT(title, content)

默认设置

新用户注册后，系统自动创建以下默认设置：

键	默认值	说明
`theme`	light	主题（支持 10 种主题）
`language`	zh-CN	界面语言
`auto_save`	1	自动保存开关
`stream_response`	1	SSE 流式响应开关
`page_size`	20	列表每页显示条数

AI 配置

OnlyClaw 支持多种 AI 模型，注册登录后在「设置」页面中配置。所有模型均通过 OpenAI 兼容格式调用。

支持的 AI 模型

类型标识	模型	API 地址示例	说明
`mimo`	小米 MIMO	`https://api.mimo.ai/v1`	国产模型，有特殊请求头处理，支持深度思考模式
`deepseek`	DeepSeek	`https://api.deepseek.com/v1`	深度求索模型，推理能力强
`openai`	OpenAI	`https://api.openai.com/v1`	GPT 系列模型，通用能力出色
`custom`	自定义	任意兼容地址	任何兼容 OpenAI 格式的第三方 API

配置步骤

注册并登录

首次访问 Web 端时，点击「注册」创建账号，然后登录。

进入设置页面

点击左侧边栏底部的「设置」图标（齿轮），进入设置页面。

添加 AI 配置

在「AI 配置管理」区域，点击「添加配置」，填写以下信息：

字段	说明	示例
模型类型	选择 AI 提供商	deepseek
API 地址	API 的 base URL（以 /v1 结尾）	`https://api.deepseek.com/v1`
API Key	你的 API 密钥	`sk-xxxxxxxxxxxx`
模型名称	具体的模型标识	`deepseek-chat`

各模型配置示例

DeepSeek — API: https://api.deepseek.com/v1，模型: deepseek-chat
OpenAI — API: https://api.openai.com/v1，模型: gpt-3.5-turbo 或 gpt-4
小米 MIMO — API: https://api.mimo.ai/v1，模型: mimo-chat

测试连接

点击配置右侧的「测试」按钮，系统会发送一个简单请求验证配置是否正确：

测试成功 — 显示绿色提示 "连接成功"，并显示模型返回的测试回复
测试失败 — 显示红色错误信息，检查 API 地址和 Key 是否正确

设为主模型

点击配置右侧的「设为主模型」按钮，该配置将成为默认使用的 AI 模型。新对话会自动使用主模型。

多模型管理 可以添加多个 AI 配置，在对话中随时切换。不同对话可以使用不同的模型。

⚠️ 注意事项

确保 API Key 有足够的额度，否则 AI 不会回复
小米 MIMO 类型会自动添加 api-key 请求头并使用 max_completion_tokens 参数
可以在对话中随时切换模型，每个对话可以使用不同的模型
支持同时配置多个 AI 提供商，方便在不同场景下切换

Web 端使用

Web 端是最完整的客户端，包含所有功能模块，使用浏览器直接访问即可。

访问地址

Web 端：http://localhost:8080/web/
API 地址：http://localhost:8080/api/

侧边栏导航

登录后，左侧边栏包含以下模块：

图标模块功能说明

💬 AI 对话创建对话、发送消息、流式响应、模型切换、自动创建笔记/任务/方案

📝 笔记笔记列表、搜索、新建/编辑/删除、分类筛选、标签管理、置顶

📁 文件文件列表、拖拽上传、上传进度、分类筛选、在线预览、下载

✅ 任务任务列表、状态筛选、优先级管理、截止日期、到期提醒

💡 解决方案 AI 生成方案、方案列表、星级评分

🧠 记忆记忆列表、类型筛选、搜索、新建/编辑/删除、统计数据

⚙️ 设置 AI 配置管理、主题切换、流式响应开关、个人信息

首次使用流程

注册账号

打开 Web 端（http://127.0.0.1:8080/web/），会看到登录页面：

点击页面上的「注册」链接

填写用户名（字母或数字，3-20 位）

填写密码（至少 6 位）

点击「注册」按钮

注册成功后自动跳转到登录页面

使用刚注册的账号登录

配置 AI

登录后，进入设置页面配置 AI 模型：

点击左侧边栏底部的「设置」图标（齿轮）

在「AI 配置管理」区域，点击「添加配置」

选择模型类型（如 DeepSeek）

填写 API 地址（如 https://api.deepseek.com/v1）

填写 API Key（从 AI 服务商获取）

填写模型名称（如 deepseek-chat）

点击「测试」验证配置是否正确

测试成功后，点击「设为主模型」

开始对话

配置完成后，开始使用 AI 对话：

点击左侧边栏的「AI 对话」图标

点击对话列表上方的「新建对话」按钮

输入对话标题（可选）

在底部输入框输入你的问题

按 Enter 发送，AI 会实时流式回复

快速体验 试试在对话中说"帮我添加一个任务：明天开会"，系统会自动创建任务。

移动端部署

基于 UniApp (Vue 2) 的移动端应用，支持 H5、微信小程序和 App。

开发环境搭建

安装 Node.js

参考上方「Node.js 安装」章节，确保以下命令正常输出：

CMD
node --version # 预期输出：v18.x.x 或 v20.x.x npm --version # 预期输出：9.x.x 或 10.x.x

安装 HBuilderX

参考上方「HBuilderX 安装」章节，下载并安装 App 开发版。首次启动后安装必要的插件。

打开项目

在 HBuilderX 中：

点击菜单 「文件」→「打开目录」

浏览到 OnlyClaw 项目中的 uniapp/ 目录

点击「选择文件夹」打开项目

等待 HBuilderX 索引项目文件（首次可能需要 1-2 分钟）

修改 API 地址

在项目中找到 API 配置文件，将基础地址修改为你的服务器地址：

JavaScript
// 找到 API 配置文件（通常在 common/ 或 utils/ 目录下） // 修改 BASE_URL 为你的服务器地址 // 本地开发 const BASE_URL = 'http://127.0.0.1:8080/api'; // 局域网访问（将 192.168.x.x 替换为你的电脑 IP） const BASE_URL = 'http://192.168.1.100:8080/api'; // 公网访问（如有公网 IP 或域名） const BASE_URL = 'https://your-domain.com/api';

注意微信小程序要求使用 HTTPS 和已备案的域名，本地开发时请使用 H5 模式测试。

运行项目

在 HBuilderX 中选择运行方式：

运行方式操作步骤适用场景

H5（浏览器）点击「运行」→「运行到浏览器」本地开发调试，最简单

微信小程序点击「运行」→「运行到小程序模拟器」→「微信开发者工具」微信小程序开发

App（真机）点击「运行」→「运行到手机或模拟器」原生 App 开发

页面结构

页面文件功能

登录注册 login.vue 表单切换，Token 存储

AI 对话 chat.vue 对话侧栏覆盖层、模型选择器、任务提醒 banner、快捷操作

笔记 notes.vue + editor.vue 笔记列表 + 搜索，独立编辑器页面

任务 tasks.vue + editor.vue 任务列表 + 筛选，独立编辑器页面

文件 files.vue 文件列表 + 分类筛选，uni.chooseFile 上传，图片预览

设置 settings.vue AI 配置管理、主题、流式开关、用户信息、退出

记忆 memories.vue 记忆列表、类型筛选、添加/编辑弹窗

底部导航

移动端采用 5 tab 底部导航：对话、笔记、任务、文件、设置。记忆管理在设置页面中。

桌面端部署

基于 Python + PyQt5 的桌面应用，包含桌面宠物、35+ 工具、微信聊天监控、截图录屏等专属功能。

安装步骤

安装 Python

参考上方「Python 安装」章节，确保以下命令正常输出：

CMD
# 验证 Python 版本（需要 3.8 或更高） python --version # 预期输出：Python 3.10.x 或更高 # 验证 pip 版本 pip --version # 预期输出：pip 23.x.x 或更高

安装 Python 依赖

打开命令行，进入桌面端目录，执行以下命令安装依赖：

CMD
# 进入桌面端目录 cd D:\AIcode\OnlyClaw\desktop # 核心依赖（必须安装，桌面端运行所需） pip install PyQt5 PyQtWebEngine requests # 录屏功能依赖（可选，如需录屏功能） pip install mss opencv-python numpy # 微信监控功能依赖（可选，如需微信聊天监控） pip install pyperclip

国内加速 如果下载速度慢，使用清华镜像源： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyQt5 PyQtWebEngine requests mss opencv-python pyperclip

验证依赖安装

运行以下命令验证所有依赖安装成功：

Python
# 在 Python 中测试导入 python -c "import PyQt5; import requests; import mss; import cv2; import pyperclip; print('所有依赖安装成功！')" # 如果没有报错，说明安装成功 # 如果报错 ModuleNotFoundError，请重新安装对应的包

确保后端运行

桌面端通过 API 与后端通信，必须先启动 PHP 服务器：

双击项目根目录的 start.bat

或手动运行：php -S 127.0.0.1:8080 api/router.php

确保 http://127.0.0.1:8080/api/ 可以访问

启动桌面端

双击 desktop/run.bat 启动桌面宠物，或手动运行：

CMD
# 进入桌面端目录 cd D:\AIcode\OnlyClaw\desktop # 启动桌面宠物 python pet.py

启动成功后，桌面右下角会出现一个红色小龙虾图标。双击图标打开主窗口，右键图标显示功能菜单。

桌面宠物操作

操作说明

左键拖拽移动宠物位置

右键点击弹出菜单：登录、显示主窗口、退出

双击显示/隐藏主窗口

桌面端功能模块

登录后进入主界面，包含以下标签页：

对话 — AI 对话，侧栏显示对话列表，支持模型选择

笔记 — 笔记列表 + 弹窗编辑器

任务 — 任务列表 + 筛选按钮 + 优先级色块

文件 — 文件列表 + QFileDialog 上传 + 分类筛选

工具 — 35+ 实用工具（详见功能介绍页）

设置 — AI 配置管理、用户信息、退出

Catppuccin Mocha 暗色主题

桌面端默认使用 Catppuccin Mocha 暗色主题，主色调 #1e1e2e，护眼且美观。

日志文件

桌面端运行日志写入 desktop/pet_log.txt，遇到问题时可以查看此文件排查。

常见问题

Q: 数据库连接失败？

错误信息通常为 "Connection refused" 或 "Access denied"。检查以下几点：

MySQL 服务是否已启动 — 打开 Windows 服务管理器（services.msc），找到 MySQL 服务，确保状态为「正在运行」

配置文件是否正确 — 检查 api/config/database.php 中的主机、端口、用户名、密码

数据库是否已创建 — 登录 MySQL 执行 SHOW DATABASES;，确认 claw 数据库存在

用户权限 — 确认用户有 claw 数据库的访问权限：SHOW GRANTS FOR 'claw'@'localhost';

CMD
# 测试数据库连接 mysql -u claw -p claw -e "SELECT 1;" # 如果成功返回 1，说明连接正常 # 查看 MySQL 服务状态 sc query MySQL # 或 net start | findstr MySQL

Q: AI 不回复？

排查步骤：

测试连接 — 进入设置，点击 AI 配置的「测试」按钮，验证连接是否正常

检查 API Key — 确保 API Key 有效且有足够额度

检查 API 地址 — 确保地址正确，注意末尾是否有 /v1

检查网络 — 确保服务器能访问 AI 服务商的 API 地址

查看错误信息 — 如果测试失败，注意查看错误信息中的具体提示

Q: 流式响应不工作？

如果 AI 回复需要等待很久才一次性显示，可能是流式响应未生效：

确保设置中 stream_response 为 1（开启状态）

部分 AI 模型不支持流式输出，系统会在 5 秒后自动降级为普通请求

某些网络代理或防火墙可能不支持 SSE（Server-Sent Events），尝试关闭代理

检查浏览器控制台是否有错误信息

Q: 文件上传失败？

检查以下几点：

目录权限 — 确保 api/storage/uploads/ 目录有写入权限

文件大小 — 单文件不能超过 50MB

PHP 配置 — 检查 php.ini 中的 upload_max_filesize 和 post_max_size 是否设为 50M 或更大

磁盘空间 — 确保服务器磁盘有足够空间

Q: 桌面端无法启动？

排查步骤：

检查 Python — 运行 python --version 确保已安装 Python 3.8+

检查依赖 — 运行 pip list 查看是否安装了 PyQt5、requests 等包

重新安装依赖 — 运行 pip install PyQt5 PyQtWebEngine requests

查看日志 — 查看 desktop/pet_log.txt 日志文件排查具体错误

Q: 桌面端无法登录？

排查步骤：

后端是否运行 — 确保 PHP 服务器正在运行（start.bat 或 php -S 127.0.0.1:8080 api/router.php）

是否已注册 — 确保已在 Web 端注册过账号（桌面端暂无注册功能）

API 地址 — 检查 API 地址是否正确（默认 http://127.0.0.1:8080/api/）

网络连接 — 尝试在浏览器中访问 http://127.0.0.1:8080/api/ 确认后端响应

Q: 录屏功能不工作？

排查步骤：

检查依赖 — 确保已安装 mss 和 opencv-python：pip install mss opencv-python

检查目录 — 确保 desktop/video/ 目录存在，如果不存在手动创建

编解码器 — 如果报错缺少编解码器，尝试安装系统级的 ffmpeg

权限问题 — 确保对 video 目录有写入权限

Q: 微信监控无法捕获消息？

排查步骤：

微信前台 — 确保微信客户端在前台运行（不能最小化）

复制操作 — 消息内容需要先选中再复制到剪贴板（Ctrl+C）

检查依赖 — 确保已安装 pyperclip：pip install pyperclip

监控状态 — 确保监控工具已点击「开始监控」按钮

Q: 移动端如何修改 API 地址？

在 HBuilderX 中打开 uniapp/ 项目，找到 API 配置文件（通常在 common/ 或 utils/ 目录下），修改 BASE_URL 为你的服务器地址即可。

Q: 如何修改端口？

修改 start.bat 中的 php -S 127.0.0.1:8080 为其他端口（如 9090），同时需要：

更新桌面端的 API 地址配置

更新移动端的 API 地址配置

确保新端口未被其他程序占用：netstat -ano | findstr :9090

Q: 如何备份数据？

数据全部存储在 MySQL 数据库中，使用 mysqldump 备份：

Bash
# 备份数据库（包含所有表和数据） mysqldump -u claw -p claw > backup_$(date +%Y%m%d).sql # 恢复数据库 mysql -u claw -p claw < backup_20260512.sql # 只备份表结构（不含数据） mysqldump -u claw -p --no-data claw > schema_backup.sql

Q: 如何更新 OnlyClaw？

更新步骤：

备份数据库（参考上方备份方法）

下载最新版本的代码

替换 api/、web/、desktop/、uniapp/ 目录

如果有数据库结构变更，执行新的 schema.sql

重启 PHP 服务器

图标	模块	功能说明
💬	AI 对话	创建对话、发送消息、流式响应、模型切换、自动创建笔记/任务/方案
📝	笔记	笔记列表、搜索、新建/编辑/删除、分类筛选、标签管理、置顶
📁	文件	文件列表、拖拽上传、上传进度、分类筛选、在线预览、下载
✅	任务	任务列表、状态筛选、优先级管理、截止日期、到期提醒
💡	解决方案	AI 生成方案、方案列表、星级评分
🧠	记忆	记忆列表、类型筛选、搜索、新建/编辑/删除、统计数据
⚙️	设置	AI 配置管理、主题切换、流式响应开关、个人信息

运行方式	操作步骤	适用场景
H5（浏览器）	点击「运行」→「运行到浏览器」	本地开发调试，最简单
微信小程序	点击「运行」→「运行到小程序模拟器」→「微信开发者工具」	微信小程序开发
App（真机）	点击「运行」→「运行到手机或模拟器」	原生 App 开发

页面	文件	功能
登录注册	`login.vue`	表单切换，Token 存储
AI 对话	`chat.vue`	对话侧栏覆盖层、模型选择器、任务提醒 banner、快捷操作
笔记	`notes.vue` + `editor.vue`	笔记列表 + 搜索，独立编辑器页面
任务	`tasks.vue` + `editor.vue`	任务列表 + 筛选，独立编辑器页面
文件	`files.vue`	文件列表 + 分类筛选，`uni.chooseFile` 上传，图片预览
设置	`settings.vue`	AI 配置管理、主题、流式开关、用户信息、退出
记忆	`memories.vue`	记忆列表、类型筛选、添加/编辑弹窗

操作	说明
左键拖拽	移动宠物位置
右键点击	弹出菜单：登录、显示主窗口、退出
双击	显示/隐藏主窗口