# ZCLAW 快速启动指南

> 5 分钟内启动 ZCLAW 开发环境

---

## 前置要求

| 工具 | 最低版本 | 检查命令 |
|------|----------|----------|
| Node.js | 18.x | `node -v` |
| pnpm | 8.x | `pnpm -v` |
| Rust | 1.70+ | `rustc --version` |

**重要**: ZCLAW 使用内部 Kernel 架构，**无需**启动外部后端服务。

---

## 快速启动

### Windows 用户

```powershell
# 在项目根目录执行
.\scripts\quick-start-dev.ps1
```

### Linux/macOS 用户

```bash
# 在项目根目录执行
./scripts/quick-start.sh
```

---

## 手动启动步骤

### 1. 安装依赖

```bash
# 根目录依赖
pnpm install

# 桌面端依赖
cd desktop && pnpm install && cd ..
```

### 2. 配置 LLM 提供商

**首次启动后**，在应用的"模型与 API"设置页面配置：

1. 点击设置图标 ⚙️
2. 进入"模型与 API"页面
3. 点击"添加自定义模型"
4. 填写配置信息：
   - 服务商：选择 Kimi / Qwen / DeepSeek / Zhipu / OpenAI 等
   - 模型 ID：如 `kimi-k2-turbo`、`qwen-plus`
   - API Key：你的 API 密钥
   - Base URL：（可选）自定义 API 端点
5. 点击"设为默认"

### 3. 启动开发环境

```bash
# 方法 A: 一键启动（推荐）
pnpm start:dev

# 方法 B: 仅启动桌面端
pnpm desktop
```

---

## 测试环境启动

### 单元测试

```bash
# 运行所有单元测试
pnpm test

# 监听模式
pnpm test:watch

# 桌面端测试
cd desktop && pnpm test
```

### E2E 测试

```bash
# 运行 E2E 测试
pnpm test:e2e

# 带界面运行
cd desktop && pnpm test:e2e:ui
```

---

## 开发端口说明

| 服务 | 端口 | 说明 |
|------|------|------|
| Vite 开发服务器 | 1420 | 前端热重载 |
| Tauri 窗口 | - | 桌面应用窗口 |

**注意**: 不再需要端口 50051，所有 Kernel 功能已内置。

---

## 支持的 LLM 提供商

| Provider | Base URL | 环境变量 |
|----------|----------|----------|
| Kimi Code | `https://api.kimi.com/coding/v1` | UI 配置 |
| 百炼/Qwen | `https://dashscope.aliyuncs.com/compatible-mode/v1` | UI 配置 |
| DeepSeek | `https://api.deepseek.com/v1` | UI 配置 |
| 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | UI 配置 |
| OpenAI | `https://api.openai.com/v1` | UI 配置 |
| Anthropic | `https://api.anthropic.com` | UI 配置 |
| Local/Ollama | `http://localhost:11434/v1` | UI 配置 |

---

## 常见问题排查

### Q1: 端口被占用

**症状**: `Port 1420 is already in use`

**解决**:
```powershell
# Windows - 查找并终止进程
netstat -ano | findstr "1420"
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :1420
kill -9 <PID>
```

### Q2: 请先在"模型与 API"设置页面配置模型

**症状**: 连接时显示"请先在'模型与 API'设置页面配置模型"

**解决**:
1. 打开应用设置
2. 进入"模型与 API"页面
3. 添加自定义模型并配置 API Key
4. 设为默认模型
5. 重新连接

### Q3: LLM 调用失败

**症状**: `Chat failed: LLM error: API error 401` 或 `404`

**排查步骤**:
1. 检查 API Key 是否正确
2. 检查 Base URL 是否正确（特别是 Kimi Code 用户）
3. 确认模型 ID 是否正确

**常见 Provider 配置**:

| Provider | 模型 ID 示例 | Base URL |
|----------|-------------|----------|
| Kimi Code | `kimi-k2-turbo` | `https://api.kimi.com/coding/v1` |
| Qwen/百炼 | `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| DeepSeek | `deepseek-chat` | `https://api.deepseek.com/v1` |
| Zhipu | `glm-4-flash` | `https://open.bigmodel.cn/api/paas/v4` |

### 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
```

---

## 验证清单

启动成功后，验证以下功能:

- [ ] 桌面端窗口正常显示
- [ ] 在"模型与 API"页面添加了自定义模型
- [ ] 可以发送消息并获得响应
- [ ] 可以切换 Agent
- [ ] 可以查看设置页面

---

## 停止服务

```bash
# 停止所有服务
pnpm start:stop

# 或手动停止
# Ctrl+C 终止运行中的进程
```

---

## 架构说明

ZCLAW 使用**内部 Kernel 架构**：

```
┌─────────────────────────────────────────────────────────────────┐
│                      ZCLAW 桌面应用                              │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐     ┌─────────────────────────────────┐   │
│  │  React 前端     │     │  Tauri 后端 (Rust)              │   │
│  │  ├─ KernelClient│────▶│  └─ zclaw-kernel                │   │
│  │  └─ Zustand     │     │     └─ LLM Drivers              │   │
│  └─────────────────┘     └─────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

**关键点**：
- 所有核心能力集成在 Tauri 应用内
- 无需启动外部后端进程
- 模型配置通过 UI 完成

---

## 相关文档

- [完整开发文档](./DEVELOPMENT.md)
- [故障排查指南](./knowledge-base/troubleshooting.md)
- [配置说明](./knowledge-base/configuration.md)

---

**最后更新**: 2026-03-22