一、概述
功能范围与适用用户
MatchaClaw V1.0 适用于人工智能应用与桌面自动化协作软件场景。 用户进入系统后，可以围绕实际工作内容完成账号进入、业务创建、过程查看、结果确认和资料管理等操作。
个人用户：在本地桌面环境中使用 AI 智能体完成研发、资料整理、自动化操作和任务跟踪
高级用户/团队负责人：管理模型供应商、技能、插件、外部连接器和多代理团队流程
企业场景用户：软件研发、产品、运营和自动化工作场景用户，在受控权限和可追溯事件记录下运行智能体任务
功能特点总览
将智能体会话、工具调用、审批控制、任务执行、技能扩展、外部连接器和多代理团队编排统一到本地桌面应用中， 降低智能体运行环境配置成本，并通过本地运行时主机和安全通信边界提供可控、可追溯、可扩展的工作台体验。
二、系统要求
| 项目 | 最低配置 | 推荐配置 |
|---|---|---|
| 操作系统 | Windows 10、macOS 或 Linux 桌面系统 | Windows 10/11、macOS 14+ 或主流 Linux 桌面系统 |
| 运行方式 | 安装 MatchaClaw 桌面客户端并完成授权校验 | 使用预构建桌面发行版，保持本地运行时主机和智能体运行时底座运行环境可用 |
| 网络环境 | 可访问所配置的智能服务供应商、技能来源或外部连接器服务 | 稳定网络连接，并按需要配置代理、授权登录或接口密钥 |
| 硬件配置 | 双核 CPU、8GB 内存、2GB 可用磁盘空间 | 四核及以上 CPU、16GB 及以上内存、10GB 及以上可用磁盘空间 |
请确保实际运行环境满足以上要求，以保证 MatchaClaw 能够正常打开页面、提交操作和展示处理结果。
三、快速入门
3.1 首次设置与授权
入口
首次启动软件时自动进入设置向导；授权状态异常时也会跳转到设置页面。
页面内容
操作步骤
- 1.打开 MatchaClaw 桌面应用
- 2.在授权输入区域填写授权码并提交校验
- 3.查看环境检查结果，根据页面提示等待必要组件准备完成
- 4.确认设置完成后进入主界面
页面反馈
- 授权成功后显示通过提示并允许进入主界面
- 授权失败或环境异常时显示错误提示并停留在当前步骤
四、功能模块操作
智能聊天会话
入口：点击侧边栏的新聊天或进入根路径聊天工作区
使用场景
- 询问问题、生成内容、执行开发或自动化任务时使用
页面组成
操作步骤
- 1进入聊天页面后选择已有会话或创建新会话
- 2在输入框输入任务说明或问题
- 3如需提供本地资料，可通过附件入口添加文件
- 4点击发送后等待智能体回复
- 5遇到审批请求时根据内容选择同意或拒绝
- 6任务完成后查看回复、文件结果或导出会话记录
页面规则与限制
- 消息内容不能为空
- 运行时未连接时发送会被阻止或显示错误
- 涉及敏感工具调用时需要用户审批
- 附件需来自可访问的本地文件
运行概览
入口：在侧边栏点击运行概览
使用场景
- 快速查看软件当前是否正常运行、网关是否可用、近期使用情况和系统概览
页面组成
操作步骤
- 1进入运行概览页面
- 2查看网关和运行时状态
- 3查看使用统计或最近活动
- 4必要时等待状态自动刷新或手动切换统计维度
页面规则与限制
- 运行时未就绪时部分统计可能为空
- 网关异常时页面会显示已断开或错误状态
智能服务供应商配置
入口：在侧边栏点击智能服务供应商，或在设置页面进入供应商配置
使用场景
- 接入不同智能服务、更新接口密钥、使用授权登录或为不同任务选择智能服务
页面组成
操作步骤
- 1打开智能服务供应商页面
- 2选择要配置的供应商账号
- 3输入接口密钥或启动授权登录
- 4保存并校验账号连接状态
- 5在能力路由配置区域选择默认智能服务或备选智能服务
页面规则与限制
- 接口密钥不能为空或格式无效
- 授权登录需在浏览器或设备码流程中完成
- 禁用账号后该供应商不参与智能服务选择
技能管理
入口：在侧边栏点击技能
使用场景
- 扩展智能体处理特定领域任务的能力，或需要安装本地技能包时
页面组成
操作步骤
- 1进入技能页面
- 2在搜索框输入技能名称或关键词
- 3查看技能详情和依赖提示
- 4点击安装或导入本地技能
- 5根据需要启用、禁用或编辑技能配置
- 6打开使用说明或技能目录查看详细文档
页面规则与限制
- 安装技能需要可访问的来源地址
- 缺失依赖或安装失败时不能标记为可用
- 需要环境变量的技能必须补全必要配置
插件管理
入口：在侧边栏点击插件
使用场景
- 扩展智能体可调用能力、临时停用某个插件、排查插件加载异常或确认当前插件版本
页面组成
操作步骤
- 1进入插件页面
- 2查看插件目录中每个插件的名称、版本、类型和当前状态
- 3根据需要打开或关闭指定插件的启用开关
- 4等待页面刷新插件目录、加载状态和运行时可用状态
- 5如页面显示不可用或失败提示，查看错误说明后调整插件来源或重新刷新
- 6确认插件状态稳定后返回聊天、技能、团队或连接器等相关页面
页面规则与限制
- 插件清单异常或不兼容时可能无法启用
- 运行时未就绪时不能完成插件状态刷新
- 系统插件或受管理插件可能不允许用户直接关闭
- 插件启用后仍需等待运行时刷新完成才能在相关功能中使用
外部连接器管理
入口：在侧边栏点击外部连接器
使用场景
- 将本地命令、模型上下文协议服务、网络服务或软件开发工具包能力接入智能体运行环境
页面组成
操作步骤
- 1进入外部连接器页面
- 2点击新增连接器并选择类型（模型上下文协议/命令行接口/软件开发工具包/网络协议）
- 3填写命令、链接地址、环境变量或认证引用等配置
- 4保存连接器
- 5点击探测查看连接器是否可用
- 6对不再使用的连接器执行删除
页面规则与限制
- 连接器名称和类型不能为空
- 不同类型需要填写对应的命令或链接地址
- 密钥引用应使用密钥引用配置，不应直接暴露敏感值
子代理管理
入口：在侧边栏点击子代理
使用场景
- 为程序片段审查、研究、测试、文档或其他专业任务创建独立智能体
页面组成
操作步骤
- 1进入子代理页面
- 2查看已有子代理或选择模板
- 3点击新建或编辑，填写名称、描述、智能服务和工作区
- 4配置该子代理可使用的技能和工具权限
- 5生成草稿并查看配置差异
- 6确认后应用草稿或导出配置
页面规则与限制
- 子代理名称不能为空
- 智能服务选择需要来自可用智能服务列表
- 技能和工具权限配置需要符合运行时允许范围
团队创建与运行
入口：在侧边栏点击团队，然后点击创建团队
使用场景
- 让多个代理按角色协同完成复杂任务，把工作拆分为负责人、研究员、开发员、审查员等角色
页面组成
操作步骤
- 1进入团队页面
- 2点击创建团队
- 3选择从团队技能创建或手工选择子代理成员
- 4设置负责人和各角色成员
- 5查看依赖检查结果
- 6确认创建团队并进入团队运行页面
页面规则与限制
- 团队必须有可识别的负责人或核心成员
- 依赖检查存在阻塞项时需要先处理
- 成员来源需要对应可用子代理或团队技能包
任务中心与定时任务
入口：在侧边栏点击任务；定时任务也可通过定时标签页进入
使用场景
- 查看后台任务是否完成、按状态筛选任务、删除旧任务或管理定时任务
页面组成
操作步骤
- 1进入任务页面
- 2查看任务统计和当前任务列表
- 3按状态、代理、团队或日期筛选任务
- 4点击任务查看详情
- 5对不再需要的任务执行删除
- 6切换定时标签页查看定时任务
页面规则与限制
- 删除任务前需要确认
- 筛选条件为空时显示全部可见任务
- 运行时未就绪时任务列表可能无法刷新
渠道管理与网关状态
入口：在侧边栏点击渠道；网关状态也可在运行概览或托盘相关入口观察
使用场景
- 添加外部渠道、扫码配对、连接或断开渠道，并查看网关是否正常工作
页面组成
操作步骤
- 1进入渠道页面
- 2点击新增渠道并填写渠道配置
- 3对需要配对的渠道扫描二维码
- 4查看渠道已连接/连接中/已断开/错误状态
- 5必要时刷新、停用或删除渠道
- 6在网关异常时执行恢复或重启操作
页面规则与限制
- 渠道配置或凭据不能为空
- 二维码配对需在有效期内完成
- 网关未就绪时渠道连接可能失败
安全中心
入口：在侧边栏点击安全中心
使用场景
- 提高运行安全性、限制危险操作、查看审计结果或处理安全修复建议
页面组成
操作步骤
- 1进入安全中心页面
- 2选择合适的策略预设或手动调整规则
- 3运行快速审计或完整性检查
- 4查看修复建议和影响说明
- 5需要时预览、应用或回滚修复
页面规则与限制
- 危险策略变更需要明确保存
- 修复动作应先预览后应用
- 安全规则配置错误时页面会显示校验提示
系统设置与诊断
入口：在侧边栏点击系统设置；部分操作也可通过菜单栏或系统托盘进入
使用场景
- 调整显示偏好、查看日志、收集诊断包、重新校验授权、检查更新或通过托盘控制软件
页面组成
操作步骤
- 1进入系统设置页面
- 2修改主题、语言或更新设置
- 3查看日志内容或打开日志目录
- 4需要时重新校验授权
- 5遇到故障时点击收集诊断包
- 6通过托盘菜单打开主窗口、检查更新或退出应用
页面规则与限制
- 授权校验需要有效授权码
- 诊断包生成需要本地文件写入权限
- 部分开发工具入口只在允许的环境中可用
五、核心运行时组件
运行时主机
MatchaClaw 本地常驻运行时进程，负责会话、智能服务选择、插件、连接器、任务和团队运行等后台能力。
智能体运行时底座
MatchaClaw 集成并适配的智能体运行时底座，用于承接网关、配置、插件和子代理等运行时能力。
网关
用于连接界面、运行时和智能体执行环境的通信通道，负责状态、事件和任务交互。
六、典型使用流程
用户完成一次完整业务时，通常按照以下流程进行：
- 1
启动与授权
首次启动软件，进入设置向导，输入授权码并完成运行环境检查。
- 2
初始化完成
软件完成本地运行时主机、主机接口、网关和事件桥接初始化后进入主界面。
- 3
选择功能模块
在侧边栏选择聊天、运行概览、智能服务供应商、技能、插件、外部连接器、子代理、团队、任务、安全中心或系统设置等功能模块。
- 4
创建会话并交互
在聊天工作区创建会话并发送消息，系统显示 AI 回复、工具调用、审批请求、错误提示和生成文件。
- 5
结果确认与管理
查看执行结果、文件产物，通过任务中心跟踪进度，或继续配置插件/技能/连接器进行扩展。
七、常见问题 FAQ
Q首次启动后为什么不能进入主界面？
A请先在设置向导中完成授权码校验，并确认运行环境检查没有阻塞项。授权失败或运行时未准备完成时，软件会停留在设置页面并给出提示。
Q聊天页面发送消息后没有回复怎么办？
A先查看运行概览或聊天页的运行时状态，确认网关和运行时主机已连接；再检查智能服务供应商账号是否启用、接口密钥或授权登录是否有效。
Q技能或插件安装后无法使用怎么办？
A请在技能或插件页面查看安装状态、依赖提示和启用开关。缺失环境变量、依赖或运行时未刷新时，需要补全配置后重新启用或刷新目录。
Q外部连接器探测失败怎么办？
A请检查连接器类型、命令、链接地址、请求头、环境变量和密钥引用是否填写正确，并确认对应外部服务或本地程序可以访问。
Q团队运行卡在某个节点怎么办？
A进入团队运行页面查看节点状态、审批请求和错误提示。若节点等待审批，请先处理审批；若配置异常，可停止运行，调整团队图或成员配置后重新创建运行。
Q出现异常时如何提供诊断信息？
A进入系统设置页面查看日志或点击收集诊断包，生成后将诊断包路径或日志内容提供给维护人员。
八、术语表
| 术语 | 解释 |
|---|---|
| MatchaClaw | 桌面应用与产品名称，用于提供智能体会话、任务执行和多代理协作工作台。 |
| 运行时主机 | MatchaClaw 本地常驻运行时进程，负责会话、智能服务选择、插件、连接器、任务和团队运行等后台能力。 |
| 智能体运行时底座 | MatchaClaw 集成并适配的智能体运行时底座，用于承接网关、配置、插件和子代理等运行时能力。 |
| 技能 | 供智能体使用的领域能力包，通常包含特定任务的操作流程、工具说明或文档资源。 |
| 插件 | 通过智能体运行时底座的插件数据通道接入的软件扩展，可提供工具、钩子、供应商实现或运行时扩展能力。 |
| 子代理 | 具有独立名称、角色说明、智能服务、工作区、技能和工具权限配置的专门智能体。 |
| 团队运行 | 由多个角色代理按照团队图和节点规则协作完成任务的执行过程。 |
| 连接器 | 用于接入模型上下文协议、命令行接口、软件开发工具包、网络协议等外部程序或服务的配置项。 |
| 网关 | 用于连接界面、运行时和智能体执行环境的通信通道，负责状态、事件和任务交互。 |
| 能力路由 | 按照不同任务能力选择智能服务、供应商或运行端点的配置机制（聊天、图像理解、图像生成等）。 |