QClaw Team Orchestrator · 常见问题 FAQ

━━━━━━━━━━━━━━━━━━━━━━━━
一、基本问题
━━━━━━━━━━━━━━━━━━━━━━━━

Q1：这个skill是做什么的？
A1：中小企业多Agent协作编排框架。提供7个角色分工模板+9个跨角色工作流+避坑体系，用户按需选择2-7个角色组合。

Q2：必须部署全部7个角色吗？
A2：不需要。选2个角色（如总调度+营销获客）就能开始工作。详见"独立部署指南"。

Q3：这个skill依赖特定Agent吗？
A3：不依赖。所有角色模板使用占位符 {AGENT_ID}，用户自行替换为自己的Agent ID。框架本身不硬编码任何特定Agent。

Q4：和旧版V2.x有什么区别？
A4：旧版是7个特定Agent的配置包（硬编码agentId），新版是通用编排框架（占位符版），每个角色可独立部署。审核者可在任意环境评估。

━━━━━━━━━━━━━━━━━━━━━━━━
二、安装部署
━━━━━━━━━━━━━━━━━━━━━━━━

Q5：怎么安装？
A5：推荐在线安装：skillhub_install install_skill qclaw-team-orchestrator。也可手动复制文件夹到 ~/.qclaw/skills/。

Q6：安装后怎么使用？
A6：1) 从knowledge/角色模板/中选择需要的角色；2) 复制SOUL.md到Agent workspace；3) 替换占位符；4) 重启Gateway。

Q7：占位符怎么替换？
A7：见 references/占位符说明.md。最简单的方式：搜索所有 {AGENT_ID} 替换为你的实际Agent ID。

Q8：需要安装哪些Skill？
A8：按角色推荐安装，不是全部必装。详见SKILL.md中的推荐Skill表。

━━━━━━━━━━━━━━━━━━━━━━━━
三、避坑专章
━━━━━━━━━━━━━━━━━━━━━━━━

Q9：最常见的坑是什么？
A9：占位符未替换（A004）。搜索所有文件确认无 { 残留。

Q10：sessions_send消息发什么？
A10：必须发"读取待办文件夹"，不能改成其他内容。各角色SOUL.md只响应这条消息。

Q11：Gateway超时是什么意思？
A11：假超时！timeout不代表消息没送达，实际已发送。1分钟后查回复文件夹确认。

Q12：微信发文件用哪个通道？
A12：个人微信用wechat-access通道。openclaw-weixin需扫码登录后才能发文件。

Q13：xlsx超链接怎么才能点击？
A13：用openpyxl.c.hyperlink API创建，不要写字符串。还需补蓝下划线样式。

Q14：怎么防止积分烧光？
A14：1) 禁用轮询（铁律A）；2) 批次操作（铁律B）；3) 调用前三问（铁律C）；4) 设日成本上限100元。

Q15：AI生成视频的字幕为什么乱码？
A15：AI生成视频中文文字必然乱码，这是已知限制。解决方案：字幕后期叠加，不在AI生成视频内写文字。

━━━━━━━━━━━━━━━━━━━━━━━━
四、角色选择
━━━━━━━━━━━━━━━━━━━━━━━━

Q16：小型公司选几个角色？
A16：引流版=总调度+营销获客（2角色），基础版=总调度+营销获客+财务精算（3角色）。

Q17：不使用企微怎么办？
A17：前台接待角色改用其他渠道（飞书/钉钉/直接对话），企微Skill不必安装。

Q18：总调度角色是必须的吗？
A18：是的。总调度是唯一协调枢纽，无论选几个角色都必须有总调度。

━━━━━━━━━━━━━━━━━━━━━━━━
五、自定义扩展
━━━━━━━━━━━━━━━━━━━━━━━━

Q19：能新增自定义角色吗？
A19：可以。复制任意角色模板，修改角色名/职责/技能清单/占位符，部署到新Agent。详见INTEGRATION.md。

Q20：工作流能自定义吗？
A20：可以。修改工作流定义中的参与角色名和步骤，适配你的角色组合。

━━━━━━━━━━━━━━━━━━━━━━━━
六、触发失败对照表
━━━━━━━━━━━━━━━━━━━━━━━━

| 现象 | 可能原因 | 修复 |
|:-----|:---------|:-----|
| 角色不响应 | 占位符未替换（A004） | 搜索替换所有占位符 |
| 角色不响应 | sessionKey格式错误 | 检查格式 agent:xxx:main |
| 角色不响应 | agentToAgent未启用 | openclaw.json设enabled=true |
| 角色不响应 | Agent冷启动（1-2分钟） | 正常等待后重试 |
| 任务重复执行 | 待办文件未删除 | 读完立即删除 |
| 文件乱码 | 非UTF-8 BOM编码 | 写文件指定UTF-8 BOM |
| xlsx超链接不可点 | 字符串而非API | 用openpyxl API |
