zclaw_openfang/docs/USER_MANUAL.md

ZCLAW 用户操作手册

版本: 0.1.0 更新日期: 2026-03-15

---

目录

1. 快速开始
2. 界面概览
3. 聊天功能
4. 分身管理
5. Hands 能力包
6. 工作流调度
7. 团队协作
8. 设置配置
9. 常见问题

---

快速开始

启动应用

1. 确保已安装 Node.js 18+ 和 pnpm
2. 在项目根目录运行：

   cd desktop
   pnpm install
   pnpm dev
   

3. 浏览器访问 http://localhost:1420

连接 Gateway

1. 确保 Gateway 服务已启动（默认端口 50051）
2. 应用会自动连接到 ws://127.0.0.1:50051/ws
3. 连接状态显示在右侧面板顶部

---

界面概览

ZCLAW 界面分为三个区域：

┌─────────────┬──────────────────────┬─────────────┐
│   左侧边栏   │      中间主区域       │   右侧面板   │
│             │                      │             │
│  - 分身     │   聊天/任务/团队      │  - 状态     │
│  - Hands    │                      │  - 文件     │
│  - 工作流   │                      │  - Agent    │
│  - 团队     │                      │             │
│             │                      │             │
│  [设置按钮] │                      │             │
└─────────────┴──────────────────────┴─────────────┘

左侧边栏标签

标签	功能
分身	Agent 分身管理
Hands	自主能力包
工作流	定时任务和触发器
团队	多 Agent 协作团队

---

聊天功能

发送消息

1. 在底部输入框输入消息
2. 点击 发送消息 按钮或按 Enter 键发送
3. Agent 会流式返回回复

开始新对话

• 点击 开始新对话 按钮清空当前对话历史

选择模型

1. 点击输入框旁的模型选择按钮
2. 从下拉列表选择模型
3. 当前模型显示在右侧面板

添加附件

• 点击 添加附件 按钮上传文件

---

分身管理

查看分身列表

在左侧边栏点击 分身 标签，可看到所有已创建的 Agent 分身。

创建新分身

1. 点击 快速配置新 Agent 按钮
2. 填写表单：
   • 名称 (必填): 分身名称
   • 角色: 如"代码助手"、"写作助手"
   • 昵称: 分身对你的称呼
   • 场景标签: 用逗号分隔，如"编程, 调试"
   • 工作目录: 默认 ~/.zclaw/zclaw-workspace
   • 你的名字: 用户名称
   • 你的角色: 用户角色
   • 限制文件访问范围: 建议开启
   • 加入优化计划: 可选
3. 点击 完成配置

删除分身

1. 将鼠标悬停在分身上
2. 点击出现的 X 按钮
3. 确认删除

切换当前分身

• 点击分身列表中的任意分身即可切换

---

Hands 能力包

可用能力包

能力包	工具数	状态	用途
🌐 Browser Hand	18	就绪	网页自动化浏览
🎬 Clip Hand	7	需配置	视频剪辑生成
🔍 Collector Hand	15	就绪	情报收集监控
📊 Lead Hand	14	就绪	销售线索发现
🔮 Predictor Hand	14	就绪	未来预测分析
🧪 Researcher Hand	15	就绪	深度研究调查
📈 Trading Hand	15	就绪	市场交易分析
𝕏 Twitter Hand	15	需配置	Twitter 自动化

使用能力包

1. 点击左侧 Hands 标签
2. 点击要使用的能力包
3. 在右侧详情页点击 执行任务
4. 配置任务参数并开始执行

查看任务历史

• 在能力包详情页可查看历史执行记录

---

工作流调度

访问调度器

1. 点击左侧 工作流 标签
2. 主区域显示调度器面板

调度器标签

标签	功能
定时任务	Heartbeat 引擎管理的定时任务
事件触发器	基于事件的自动触发规则
运行历史	任务执行历史记录

创建定时任务

1. 点击 新建任务 或 创建定时任务
2. 配置任务参数
3. 设置执行周期
4. 保存任务

---

团队协作

访问团队页面

1. 点击左侧 团队 标签
2. 显示团队列表和创建按钮

创建团队

1. 点击 Create Team 按钮
2. 配置团队成员和角色
3. 设置协作模式

团队协作模式

• 多个 Agent 可以组成团队
• 支持不同的协作角色分配
• 可追踪团队任务执行状态

---

设置配置

点击左下角 设置 按钮进入设置页面。

设置分类

分类	功能
通用	Gateway 连接、外观与行为
用量统计	API 调用统计
积分详情	积分余额和使用
模型与 API	模型选择和 API 配置
MCP 服务	MCP 服务器配置
技能	技能包管理
IM 频道	即时通讯集成
工作区	项目目录配置
数据与隐私	数据处理设置
安全状态	安全配置状态
审计日志	操作审计记录
定时任务	定时任务管理
提交反馈	反馈提交
关于	版本信息

Gateway 连接

1. 输入 Gateway URL (默认: ws://127.0.0.1:50051/ws)
2. 输入认证 Token (可选)
3. 点击 保存连接设置
4. 点击 重新连接

模型切换

1. 进入 模型与 API 设置
2. 浏览可用模型列表
3. 点击 切换到此模型 按钮

工作区配置

1. 进入 工作区 设置
2. 设置默认项目目录
3. 配置文件访问限制
4. 开启/关闭自动保存和文件监听

---

常见问题

Q: Gateway 连接失败

解决方案:

1. 检查 Gateway 服务是否运行
2. 确认端口 50051 未被占用
3. 检查防火墙设置

Q: 模型切换后不生效

解决方案:

1. 点击 重新连接 按钮
2. 刷新页面
3. 开始新对话

Q: 分身创建失败

解决方案:

1. 检查 Gateway 连接状态
2. 确保所有必填字段已填写
3. 检查后端日志

Q: Hands 任务执行无响应

解决方案:

1. 检查能力包配置状态
2. 确认相关 API Key 已配置
3. 查看控制台错误信息

Q: 工作区路径显示"未解析"

解决方案:

1. 检查路径格式是否正确
2. 确保目录存在
3. 使用绝对路径

---

键盘快捷键

快捷键	功能
Enter	发送消息
Shift + Enter	换行
Escape	关闭弹窗

---

技术支持

如遇问题，请：

1. 查看浏览器控制台 (F12)
2. 检查 Gateway 服务日志
3. 提交反馈至开发团队

---

本手册基于 ZCLAW v0.1.0 编写