d3a4de2480
- Add OpenFang Kernel configuration guide (docs/setup/OPENFANG-SETUP.md) - Add Chinese models configuration guide (docs/setup/chinese-models.md) - Add quick start guide (docs/quick-start.md) - Add quick start scripts for Windows and Linux/macOS - Add ErrorNotification component for centralized error display These additions help users: - Quickly set up development environment - Configure OpenFang backend correctly - Configure Chinese LLM providers (GLM, Qwen, Kimi, MiniMax) - See error notifications in a consistent UI Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
234 lines
3.4 KiB
Markdown
234 lines
3.4 KiB
Markdown
# ZCLAW 快速启动指南
|
|
|
|
> 5 分钟内启动 ZCLAW 开发环境
|
|
|
|
---
|
|
|
|
## 前置要求
|
|
|
|
| 工具 | 最低版本 | 检查命令 |
|
|
|------|----------|----------|
|
|
| Node.js | 18.x | `node -v` |
|
|
| pnpm | 8.x | `pnpm -v` |
|
|
| Rust | 1.70+ | `rustc --version` |
|
|
| OpenFang | - | `openfang --version` |
|
|
|
|
---
|
|
|
|
## 快速启动
|
|
|
|
### Windows 用户
|
|
|
|
```powershell
|
|
# 在项目根目录执行
|
|
.\scripts\quick-start-dev.ps1
|
|
```
|
|
|
|
### Linux/macOS 用户
|
|
|
|
```bash
|
|
# 在项目根目录执行
|
|
./scripts/quick-start.sh
|
|
```
|
|
|
|
---
|
|
|
|
## 手动启动步骤
|
|
|
|
### 1. 安装依赖
|
|
|
|
```bash
|
|
# 根目录依赖
|
|
pnpm install
|
|
|
|
# 桌面端依赖
|
|
cd desktop && pnpm install && cd ..
|
|
```
|
|
|
|
### 2. 启动 OpenFang 后端
|
|
|
|
```bash
|
|
# 方法 A: 使用 CLI
|
|
openfang start
|
|
|
|
# 方法 B: 使用 pnpm 脚本
|
|
pnpm gateway:start
|
|
```
|
|
|
|
验证后端运行:
|
|
```bash
|
|
curl http://127.0.0.1:50051/api/health
|
|
# 应返回: {"status":"ok"}
|
|
```
|
|
|
|
### 3. 启动开发环境
|
|
|
|
```bash
|
|
# 方法 A: 一键启动（推荐）
|
|
pnpm start:dev
|
|
|
|
# 方法 B: 仅启动桌面端（需要后端已运行）
|
|
pnpm desktop
|
|
|
|
# 方法 C: 分开启动
|
|
# 终端 1 - 启动 Gateway
|
|
pnpm dev
|
|
|
|
# 终端 2 - 启动桌面端
|
|
pnpm desktop
|
|
```
|
|
|
|
---
|
|
|
|
## 测试环境启动
|
|
|
|
### 单元测试
|
|
|
|
```bash
|
|
# 运行所有单元测试
|
|
pnpm test
|
|
|
|
# 监听模式
|
|
pnpm test:watch
|
|
|
|
# 桌面端测试
|
|
cd desktop && pnpm test
|
|
```
|
|
|
|
### E2E 测试
|
|
|
|
```bash
|
|
# 运行 E2E 测试
|
|
pnpm test:e2e
|
|
|
|
# 带界面运行
|
|
cd desktop && pnpm test:e2e:ui
|
|
```
|
|
|
|
---
|
|
|
|
## 开发端口说明
|
|
|
|
| 服务 | 端口 | 说明 |
|
|
|------|------|------|
|
|
| OpenFang 后端 | 50051 | API 和 WebSocket 服务 |
|
|
| Vite 开发服务器 | 1420 | 前端热重载 |
|
|
| Tauri 窗口 | - | 桌面应用窗口 |
|
|
|
|
---
|
|
|
|
## 常见问题排查
|
|
|
|
### Q1: 端口被占用
|
|
|
|
**症状**: `Port 1420 is already in use` 或 `Port 50051 is already in use`
|
|
|
|
**解决**:
|
|
```powershell
|
|
# Windows - 查找并终止进程
|
|
netstat -ano | findstr "1420"
|
|
taskkill /PID <PID> /F
|
|
|
|
# Linux/macOS
|
|
lsof -i :1420
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Q2: 后端连接失败
|
|
|
|
**症状**: `Network Error` 或 `Connection refused`
|
|
|
|
**排查步骤**:
|
|
```bash
|
|
# 1. 检查后端是否运行
|
|
curl http://127.0.0.1:50051/api/health
|
|
|
|
# 2. 检查端口监听
|
|
netstat -ano | findstr "50051"
|
|
|
|
# 3. 重启后端
|
|
openfang restart
|
|
```
|
|
|
|
### Q3: API Key 未配置
|
|
|
|
**症状**: `Missing API key: No LLM provider configured`
|
|
|
|
**解决**:
|
|
```bash
|
|
# 编辑配置文件
|
|
# Windows: %USERPROFILE%\.openfang\.env
|
|
# Linux/macOS: ~/.openfang/.env
|
|
|
|
# 添加 API Key
|
|
echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env
|
|
|
|
# 重启后端
|
|
openfang restart
|
|
```
|
|
|
|
### Q4: Tauri 编译失败
|
|
|
|
**症状**: Rust 编译错误
|
|
|
|
**解决**:
|
|
```bash
|
|
# 更新 Rust
|
|
rustup update
|
|
|
|
# 清理并重新构建
|
|
cd desktop/src-tauri
|
|
cargo clean
|
|
cargo build
|
|
```
|
|
|
|
### Q5: 依赖安装失败
|
|
|
|
**症状**: pnpm install 报错
|
|
|
|
**解决**:
|
|
```bash
|
|
# 清理缓存
|
|
pnpm store prune
|
|
|
|
# 删除 node_modules 重新安装
|
|
rm -rf node_modules desktop/node_modules
|
|
pnpm install
|
|
```
|
|
|
|
---
|
|
|
|
## 验证清单
|
|
|
|
启动成功后，验证以下功能:
|
|
|
|
- [ ] 后端健康检查通过: `curl http://127.0.0.1:50051/api/health`
|
|
- [ ] 桌面端窗口正常显示
|
|
- [ ] 可以发送消息并获得响应
|
|
- [ ] 可以切换 Agent
|
|
- [ ] 可以查看设置页面
|
|
|
|
---
|
|
|
|
## 停止服务
|
|
|
|
```bash
|
|
# 停止所有服务
|
|
pnpm start:stop
|
|
|
|
# 或手动停止
|
|
# Ctrl+C 终止运行中的进程
|
|
```
|
|
|
|
---
|
|
|
|
## 相关文档
|
|
|
|
- [完整开发文档](./DEVELOPMENT.md)
|
|
- [故障排查指南](./knowledge-base/troubleshooting.md)
|
|
- [配置说明](./knowledge-base/configuration.md)
|
|
|
|
---
|
|
|
|
**最后更新**: 2026-03-21
|