Files

iven d3a4de2480 docs: add setup guides and error notification component

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

2026-03-21 00:17:44 +08:00

3.4 KiB

Raw Blame History

ZCLAW 快速启动指南

5 分钟内启动 ZCLAW 开发环境

前置要求

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

快速启动

Windows 用户

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

Linux/macOS 用户

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

手动启动步骤

1. 安装依赖

# 根目录依赖
pnpm install

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

2. 启动 OpenFang 后端

# 方法 A: 使用 CLI
openfang start

# 方法 B: 使用 pnpm 脚本
pnpm gateway:start

验证后端运行:

curl http://127.0.0.1:50051/api/health
# 应返回: {"status":"ok"}

3. 启动开发环境

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

# 方法 B: 仅启动桌面端（需要后端已运行）
pnpm desktop

# 方法 C: 分开启动
# 终端 1 - 启动 Gateway
pnpm dev

# 终端 2 - 启动桌面端
pnpm desktop

测试环境启动

单元测试

# 运行所有单元测试
pnpm test

# 监听模式
pnpm test:watch

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

E2E 测试

# 运行 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

解决:

# Windows - 查找并终止进程
netstat -ano | findstr "1420"
taskkill /PID <PID> /F

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

Q2: 后端连接失败

症状: Network Error 或 Connection refused

排查步骤:

# 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

解决:

# 编辑配置文件
# Windows: %USERPROFILE%\.openfang\.env
# Linux/macOS: ~/.openfang/.env

# 添加 API Key
echo "ZHIPU_API_KEY=your_key" >> ~/.openfang/.env

# 重启后端
openfang restart

Q4: Tauri 编译失败

症状: Rust 编译错误

解决:

# 更新 Rust
rustup update

# 清理并重新构建
cd desktop/src-tauri
cargo clean
cargo build

Q5: 依赖安装失败

症状: pnpm install 报错

解决:

# 清理缓存
pnpm store prune

# 删除 node_modules 重新安装
rm -rf node_modules desktop/node_modules
pnpm install

验证清单

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

后端健康检查通过: curl http://127.0.0.1:50051/api/health
桌面端窗口正常显示
可以发送消息并获得响应
可以切换 Agent
可以查看设置页面

停止服务

# 停止所有服务
pnpm start:stop

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

3.4 KiB Raw Blame History