zclaw_openfang/docs/deployment/windows.md

Windows 部署指南

本指南详细说明 ZCLAW 在 Windows 平台上的部署流程。

系统要求

组件	最低要求	推荐配置
操作系统	Windows 10 64-bit (1809+)	Windows 11 64-bit
处理器	Intel Core i5 / AMD Ryzen 5	Intel Core i7 / AMD Ryzen 7
内存	8 GB	16 GB
磁盘空间	500 MB	1 GB
网络	宽带连接	稳定宽带

构建步骤

1. 准备构建环境

# 安装 Rust (如果未安装)
winget install Rustlang.Rust.MSVC

# 安装 Node.js (如果未安装)
winget install OpenJS.NodeJS.LTS

# 安装 pnpm
npm install -g pnpm

# 验证安装
rustc --version
node --version
pnpm --version

2. 获取源代码

git clone <repository-url>
cd ZCLAW

3. 安装依赖

# 根目录依赖
pnpm install

# 桌面端依赖
cd desktop
pnpm install

4. 执行构建

cd desktop

# 开发构建（快速）
pnpm tauri:dev

# 生产构建
pnpm tauri:build

# 完整打包（包含运行时）
pnpm tauri:build:bundled

5. 查看构建产物

# 可执行文件
dir src-tauri\target\release\ZClaw.exe

# NSIS 安装包
dir src-tauri\target\release\bundle\nsis\

安装选项

NSIS 安装包

优点：

• 自动处理依赖
• 创建开始菜单快捷方式
• 支持卸载

步骤：

1. 双击 ZCLAW-Setup-{version}-x64.exe
2. 选择安装位置（默认：C:\Program Files\ZCLAW）
3. 选择是否创建桌面快捷方式
4. 点击「安装」
5. 完成后启动 ZCLAW

便携版

优点：

• 无需安装
• 可放在 U 盘运行
• 不修改系统设置

步骤：

1. 复制以下文件到目标目录：
   • ZClaw.exe
   • resources/ 目录（如有）
2. 双击 ZClaw.exe 运行

配置

用户数据目录

ZCLAW 在以下位置存储用户数据：

%USERPROFILE%\.zclaw\
├── zclaw.toml     # 主配置文件
├── .env              # 环境变量（可选）
├── data/
│   └── zclaw.db   # SQLite 数据库
└── logs/
    └── app.log       # 应用日志

防火墙配置

如果遇到网络问题，请确保 ZCLAW 可以通过 Windows 防火墙：

1. 打开「Windows Defender 防火墙」
2. 点击「允许应用通过防火墙」
3. 点击「更改设置」→「允许其他应用」
4. 添加 ZClaw.exe
5. 确保勾选「专用」和「公用」

杀毒软件排除

某些杀毒软件可能误报，建议添加排除项：

Windows Defender：

1. 打开「Windows 安全中心」
2. 选择「病毒和威胁防护」
3. 点击「管理设置」
4. 滚动到「排除项」→「添加或删除排除项」
5. 添加 ZCLAW 安装目录

常见问题

启动闪退

可能原因：

1. 缺少 Visual C++ 运行库
2. 配置文件损坏
3. 端口被占用

解决方案：

# 安装 VC++ 运行库
winget install Microsoft.VCRedist.2015+.x64

# 重置配置
Remove-Item -Recurse -Force "$env:USERPROFILE\.zclaw"

# 检查端口占用
netstat -ano | findstr :50051

更新后无法启动

解决方案：

1. 完全卸载旧版本
2. 删除 %LOCALAPPDATA%\ZClaw 目录
3. 重新安装新版本

权限问题

症状：无法保存设置

解决方案：

# 检查目录权限
icacls "$env:USERPROFILE\.zclaw"

# 修复权限
icacls "$env:USERPROFILE\.zclaw" /grant:r "%USERNAME%:(OI)(CI)F"

卸载

通过安装程序卸载

1. 打开「设置」→「应用」→「已安装的应用」
2. 找到 ZCLAW
3. 点击「卸载」

手动卸载

1. 删除安装目录（默认：C:\Program Files\ZCLAW）
2. 删除用户数据（可选）：

   Remove-Item -Recurse -Force "$env:USERPROFILE\.zclaw"
   

3. 删除快捷方式

性能优化

启动速度

# 禁用开机自启（如果不需要）
# 在任务管理器 → 启动 中禁用 ZCLAW

内存使用

• 关闭不使用的对话标签页
• 定期清理历史记录
• 减少保留的上下文长度

日志收集

用于问题排查：

# 查看最新日志
Get-Content "$env:USERPROFILE\.zclaw\logs\app.log" -Tail 50

# 导出日志
Copy-Item "$env:USERPROFILE\.zclaw\logs" -Destination "C:\temp\zclaw-logs" -Recurse