# 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