ClawAgent 使用指南

ClawAgent 提供了一套完整的企业级 AIGC 营销推广工具，支持短视频生成、数字人口播、AI 商拍、模特试衣、商品场景图生成、多平台账号管理、视频翻译、对口型、带货视频生成等功能。

⚠️ 安全与隐私警告

使用本 skill 前请知悉：

1. 敏感凭证：Token 是敏感凭证，建议使用临时或最低权限 Token。
2. 数据上报：不支持的功能可能会上报到远程服务器，上报前会征得您的同意。
3. 文件上传：本地文件会上传到云存储 (OSS)，请勿上传包含敏感内容的文件（如身份证、私人视频等），除非您信任服务提供者。
4. 网络连接：本 skill 会与远程服务器通信，详细信息请查看 [隐私政策]。

⚙️ 快速配置

首次安装使用时，需要先完成本地安装和注册，详见 references/auth.md。

🎯 场景路由表

根据任务场景，选择对应的参考文档：

📁 文件目录结构

ClawAgent-skill/
├── SKILL.md                        # 入口文件（本文件），全局导航与核心规则
├── setup.py                        # 本地安装脚本
├── upload_file.py                  # 文件上传脚本（云存储、OSS）
├── references/                     # 参考文档（按品类/功能划分）
│   ├── auth.md                     # 鉴权与授权流程
│   ├── workflows.md                # 公共接口 + 常见工作流
│   ├── model_try_clothes.md        # 模特试穿试戴
│   ├── shoes_dressing.md           # 鞋靴试穿
│   ├── model_produce.md            # 模特生成
│   ├── business_product_scene.md   # 商品场景图
│   ├── business_poster.md          # 商品海报生成
│   ├── ice_design_image_xhs.md     # 红笔记内容生成
│   ├── ai_clone_video.md           # AI视频创作
│   ├── video_publish.md            # AI发布视频
│   ├── image_publish.md            # AI发布图文
│   ├── ice_voice_video.md         # 视频对口型
│   ├── image_song.md              # 照片唱歌
│   ├── ai_mixed_script.md        # 智能成片
│   └── 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: 响应数据对象，结构因接口不同而异，固定包含以下字段：
• _id: 调用链追踪 ID

异常处理规则

当 code != 0 时，表示调用失败，按以下规则处理：

1. 读取 msg 字段：获取错误原因（msg 可能较简短，需结合上下文理解）
2. 自主判断：根据 msg 内容和错误场景，分析失败原因并给出解决方案
3. 自动重试：如果是临时性错误（如网络超时、服务繁忙），可自动重试 1-2 次
4. 引导用户：如果是参数错误、权限问题、算力不足等，主动告知用户具体原因和操作建议
5. 不要静默失败：必须将错误信息和处理建议反馈给用户

异常返回示例：

{
  "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 ~ 等命令搜索整个磁盘查找文件。\

允许搜索范围：仅限在「当前工作目录」「下载目录」「用户明确指定的目录」这三个范围内搜索。

文件处理规范

文件来源识别与处理

当用户提供文件时，按以下流程处理：

1. 公网URL：
• 必须先验证URL可访问性（在调用任何MCP工具之前）
• 执行验证命令：curl -I --max-time 5 -L
• 判断结果：
• HTTP 200：URL有效，直接调用MCP工具，不要执行上传脚本
• HTTP 403/401：告知用户"该链接需要登录或权限，请提供公开链接或本地文件"
• HTTP 404：告知用户"链接已失效，请检查后重试或提供本地文件"
• 超时/连接失败：告知用户"链接无法访问，请检查网络或提供本地文件"
2. 本地文件路径：
• 见文件上传规则
3. 引用文件（@image、@file等）：
• 告知用户："检测到您引用了文件，请先将文件保存到本地，然后提供完整路径"
• 引导用户：右键文件 → "显示在访达中" → 复制完整路径
4. 对话中直接上传的图片（用户在聊天界面发送图片）：
• 必须告知用户："检测到您发送了图片，但我无法直接访问对话中的图片文件"
• 引导用户按以下步骤操作：
5. 右键点击图片 → "保存到下载文件夹"或"另存为..."
6. 复制保存后的完整文件路径（如 /Users/yourname/Downloads/image.jpg）
7. 将路径发送给我，我会帮您上传处理

绝对禁止（适用于所有文件来源）：

• ❌ 编造或猜测URL/文件路径（如 https://example.com/image.jpg 或 /Users/xxx/Downloads/image.jpg）
• ❌ 使用示例URL、占位符URL或不存在的路径
• ❌ 在未验证可访问性/存在性的情况下直接调用工具

文件上传规则

> 重要：ClawAgent接口需要公网可访问的URL，不接收本地文件。所有本地文件必须先上传再加载。

用户提供本地文件需要传入ClawAgent接口时，必须先上传到云存储获取公网URL：

上传步骤

1. 使用上传脚本：执行 python upload_file.py <本地文件路径>（脚本位于 skill 根目录）
2. 获取输出结果：脚本输出格式为 KEY:VALUE，提取 FILE_URL 和 FILE_SIZE
3. 传入AI接口：将 FILE_URL 填入对应参数（如 image_url、video_url 等）调用目标工具

管道自动处理

当工具调用返回 {"error": "need_upload", ...} 时（表示文件无法访问），直接通过管道传给上传脚本：

echo '<上面的JSON>' | python upload_file.py

上传完成后会输出 TOOL_NAME，使用得到的 FILE_URL 调用该工具继续即可。

核心规则

• 不支持的能力需用户同意后上报：当用户请求的功能在工具列表中找不到对应支持时，必须先征得用户同意后再调用 report_unsupported_feature 上报。详见 references/unsupported_feature_reporting.md
• 文件/URL验证规则：见文件处理规范中的"绝对禁止"条款

问题定位指南

常见错误码

排查步骤

1. 匹配错误码：先查上方错误码表，按对应方案处理
2. 确认工具可用：mcporter list ClawAgent 查看可用工具列表及参数定义
3. 确认授权状态：如有鉴权相关错误，重新执行 references/auth.md 中的授权流程
4. 查阅品类参考文档：根据场景路由表找到对应参考文档，确认工具调用规范和参数约束

SKILL 更新

每天使用 SKILL 时，建议检查更新。按照如下的步骤执行：

更新检查规则（重要）

核心原则：版本检查应当透明，必须告知用户正在检查更新并获得同意。

更新检查流程

1. 查看当前版本：读取本文件顶部 frontmatter 中的 version 字段（格式：MAJOR.MINOR.PATCH）
2. 告知用户并征求意见：向用户说明正在检查更新，询问是否愿意执行版本检查

```

💡 提示：检测到有新版本可用，是否检查更新？

```

1. 用户同意后查询最新版本：用户确认后，执行以下命令

```bash

mcporter call "ClawAgent" "check_skill_update" --args '{"version": "<当前版本号>"}'

```

返回参数说明：

• latest: 最新版本号（格式：MAJOR.MINOR.PATCH）
• release_note: 版本发布说明
• instruction: 更新操作指令

1. 版本比较与处理：
• 如果 version < latest（有新版本）：
• 向用户展示版本差异和 release_note
• 询问用户是否执行更新
• 用户确认后，严格遵循 instruction 指令执行更新
• 更新完成后，重新读取 version 字段验证更新结果
• 如果 version >= latest（已是最新）：
• 向用户简要说明"当前已是最新版本"
• 直接继续处理用户的实际请求

异常处理

• 查询失败：如果更新检查命令执行失败，告知用户错误信息，建议稍后重试
• 更新失败：如果按照 instruction 执行后更新失败，告知用户具体错误信息，建议手动更新
• 用户拒绝：如果用户选择不检查或不更新，直接继续处理用户请求，不做任何提示