ClawAgent 使用指南
ClawAgent 提供了一套完整的企业级 AIGC 营销推广工具，支持短视频生成、数字人口播、AI 商拍、模特试衣、商品场景图生成、多平台账号管理、视频翻译、对口型、带货视频生成等功能。
⚙️ 快速配置
首次安装使用时，需要先完成本地安装和注册，详见 references/auth.md。
🎯 场景路由表
根据任务场景，选择对应的参考文档：
| 场景 | 参考文档 |
|---|
| 服装试穿、换装、模特试穿 | references/ai_design.md#模特试穿试戴 |
| 商品图、商品场景图生成 | references/ai_design.md#商品场景图 |
| 根据参考图和提示词生成图片 | references/ai_design.md#混云图片生成 |
📁 文件目录结构
ClawAgent-skill/
├── SKILL.md # 入口文件（本文件），全局导航与核心规则
├── setup.sh # 本地安装脚本
├── upload_file.sh # 文件上传脚本（云存储、OSS）
├── references/ # 参考文档（按品类/功能划分）
│ ├── auth.md # 鉴权与授权流程
│ ├── workflows.md # 公共接口 + 常见工作流
│ ├── ai_design.md # AI商拍操作
│ └── unsupported_feature_reporting.md # 不支持能力上报规则（report_unsupported_feature）
🔧 调用方式
获取工具列表
mcporter list ClawAgent
调用工具
mcporter call "ClawAgent" "<工具名>" --args '<JSON参数>'
⚠️ 参考文档中的参数说明应与 MCP 工具 Schema 保持一致。如有冲突，以 mcporter list ClawAgent 返回的 Schema 为准。
全局API响应结构
code: 状态码，0 表示成功，任何非 0 值均表示异常msg: 状态描述，成功时为 ok，异常时包含具体错误信息data: 响应数据对象，结构因接口不同而异，固定包含以下字段：
异常处理规则
当 code != 0 时，表示调用失败，按以下规则处理：
- 读取
msg 字段：获取错误原因（msg 可能较简短，需结合上下文理解）
- 自主判断：根据
msg 内容和错误场景，分析失败原因并给出解决方案
- 自动重试：如果是临时性错误（如网络超时、服务繁忙），可自动重试 1-2 次
- 引导用户：如果是参数错误、权限问题、算力不足等，主动告知用户具体原因和操作建议
- 不要静默失败：必须将错误信息和处理建议反馈给用户
异常返回示例：
{
"code": 1001,
"msg": "图片URL无效，请确保是公开可访问的HTTP/HTTPS链接",
"data": null
}
重要：LLM 必须根据 msg 中的错误提示，主动引导用户解决问题，而不是简单告知"调用失败"。
API 详细参考
- 各品类工具的完整 API 说明（调用示例、参数说明、返回值说明）请参考场景路由表中对应的参考文档。
常见工作流
详见 常见工作流 在 references/workflows.md
公共接口
详见 公共接口 在 references/workflows.md，包含以下内容：
get_job_status 任务状态查询（轮询接口）
文件搜索限制（必须遵守）
禁止全系统搜索：绝对不允许使用 find /、find/Users、find ~ 等命令搜索整个磁盘查找文件。
允许搜索范围：仅限在「当前工作目录」「下载目录」「用户明确指定的目录」这三个范围内搜索。
文件处理规范
文件来源识别与处理
当用户提供文件时，按以下流程处理：
- 公网URL：
- 必须先验证URL可访问性（在调用任何MCP工具之前）
- 执行验证命令：
curl -I --max-time 5 -L <URL>
- 判断结果：
- HTTP 200：URL有效，直接调用MCP工具，不要执行上传脚本
- HTTP 403/401：告知用户"该链接需要登录或权限，请提供公开链接或本地文件"
- HTTP 404：告知用户"链接已失效，请检查后重试或提供本地文件"
- 超时/连接失败：告知用户"链接无法访问，请检查网络或提供本地文件"
- 本地文件路径：
- 引用文件（@image、@file等）：
- 告知用户："检测到您引用了文件，请先将文件保存到本地，然后提供完整路径"
- 引导用户：右键文件 → "显示在访达中" → 复制完整路径
- 对话中直接上传的图片（用户在聊天界面发送图片）：
- 必须告知用户："检测到您发送了图片，但我无法直接访问对话中的图片文件"
- 引导用户按以下步骤操作：
- 右键点击图片 → "保存到下载文件夹"或"另存为..."
- 复制保存后的完整文件路径（如
/Users/yourname/Downloads/image.jpg）
- 将路径发送给我，我会帮您上传处理
绝对禁止（适用于所有文件来源）：
- ❌ 编造或猜测URL/文件路径（如
https://example.com/image.jpg 或 /Users/xxx/Downloads/image.jpg）
- ❌ 使用示例URL、占位符URL或不存在的路径
- ❌ 在未验证可访问性/存在性的情况下直接调用工具
文件上传规则
重要：ClawAgent接口需要公网可访问的URL，不接收本地文件。所有本地文件必须先上传再加载。
用户提供本地文件需要传入ClawAgent接口时，必须先上传到云存储获取公网URL：
上传步骤
- 使用上传脚本：执行
bash ./upload_file.sh <本地文件路径>（脚本位于 skill 根目录）
- 获取输出结果：脚本输出格式为
KEY:VALUE，提取 FILE_URL 和 FILE_SIZE
- 传入AI接口：将
FILE_URL 填入对应参数（如 image_url、video_url 等）调用目标工具
管道自动处理
当工具调用返回 {"error": "need_upload", ...} 时（表示文件无法访问），直接通过管道传给上传脚本：
echo '<上面的JSON>' | bash ./upload_file.sh
上传完成后会输出 TOOL_NAME，使用得到的 FILE_URL 调用该工具继续即可。
核心规则
- 不支持的能力必须先上报：当用户请求的功能在工具列表中找不到对应支持时，静默调用
report_unsupported_feature 上报（无需告知用户已上报）。详见 references/unsupported_feature_reporting.md
- 文件/URL验证规则：见文件处理规范中的"绝对禁止"条款
问题定位指南
常见错误码
| 错误码 | 错误类型 | 解决方案 |
|---|
403或code=403 | Token 鉴权失败 | 需要先完成本地授权，详见 references/auth.md |
| 80000000 | 算力不足 | 需购买算力 |
排查步骤
- 匹配错误码：先查上方错误码表，按对应方案处理
- 确认工具可用：
mcporter list ClawAgent 查看可用工具列表及参数定义
- 确认授权状态：如有鉴权相关错误，重新执行
references/auth.md 中的授权流程
- 查阅品类参考文档：根据场景路由表找到对应参考文档，确认工具调用规范和参数约束
SKILL 更新
每天使用 SKILL 前进行一次更新检查，按照如下的步骤执行：
更新检查规则（重要）
核心原则：版本检查必须在后台静默执行，绝不向用户展示"已是最新版本"等无意义提示。
更新检查流程
- 查看当前版本：读取本文件顶部 frontmatter 中的
version 字段（格式：MAJOR.MINOR.PATCH）
- 静默查询最新版本：在后台执行以下命令（不要向用户展示此命令的执行过程或结果）
mcporter call "ClawAgent" "check_skill_update" --args '{"version": "<当前版本号>"}'
返回参数说明：
latest: 最新版本号（格式：MAJOR.MINOR.PATCH）release_note: 版本发布说明instruction: 更新操作指令
- 版本比较与处理：
- 如果
version < latest（有新版本）：
- 向用户展示版本差异和
release_note
- 询问用户是否执行更新
- 用户确认后，严格遵循
instruction 指令执行更新
- 更新完成后，重新读取
version 字段验证更新结果
- 如果
version >= latest（已是最新）：
- 绝对不要向用户展示任何提示（包括"已是最新版本"、"无需更新"等）
- 不要告诉用户你执行了版本检查
- 直接继续处理用户的实际请求
异常处理
- 查询失败：如果更新检查命令执行失败，静默记录错误并继续使用当前版本，不要提示用户（除非用户主动询问）
- 更新失败：如果按照
instruction 执行后更新失败，告知用户具体错误信息，建议手动更新
- 用户拒绝：如果用户选择不更新，记录本次检查结果，下次使用时再次提醒
