腾讯云 COS 技能
把腾讯云 COS 变成 OpenClaw 可直接调用的一组高频对象存储工作流。
适合这些典型任务:
- 把本地文件或整个目录快速上传到 COS
- 为图片、压缩包、构建产物生成临时访问链接
- 浏览某个前缀下的文件结构,做复制、移动、重命名、清理
- 处理视频、模型、备份包等大文件上传
- 快速判断凭证、地域、Bucket、自定义域名哪里配错了
默认做法是:
- 优先检查关键配置与目标路径
- 在需要时生成并执行简洁脚本,直接完成对象存储操作
- 结果以结构化 JSON 或简洁中文返回给用户
适用场景
当用户出现这些意图时启用:
- 把本地文件上传到腾讯云 COS
- 批量上传一个目录或多个文件到 COS
- 上传大文件并控制并发、分片大小、断点续传策略
- 获取 COS 对象的临时签名 URL
- 列出某个前缀下的文件或文件夹
- 创建、删除、移动、复制、重命名 COS 对象
- 统计某个目录下的文件数量和总大小
- 排查 COS 凭证、地域、Bucket、自定义域名配置
前置条件
要求具备可访问腾讯云 COS 的运行环境和必要配置。
如果关键配置不完整,先明确缺什么,不要猜。
脚本资源
优先使用 scripts/ 里的可执行脚本,而不是每次临时重写一遍逻辑。
可直接复用的脚本:
scripts/check_config.js - 检查关键配置是否齐全
scripts/upload_file.js - 上传单个文件
scripts/upload_batch.js - 批量上传文件或整个目录
scripts/generate_signed_url.js - 生成临时签名链接
scripts/list_objects.js - 列出对象或文件夹视图
scripts/manage_objects.js - 删除、批量删除、复制、移动、重命名、创建文件夹
scripts/upload_large_file.js - 大文件分片上传
scripts/delete_folder.js - 删除文件夹,支持递归删除
scripts/get_folder_stats.js - 统计目录文件数量、总体积和类型分布
调用方式统一为:
node projects/skills/tx-cos/scripts/<script>.js '<json>'
默认执行策略
1. 先检查配置
优先先跑 scripts/check_config.js 确认关键配置是否齐全。
如果必需项缺失,直接告诉用户缺哪几个,不继续执行上传/删除类操作。
2. 需要真实操作时,优先调用现成脚本
这个技能的目标是让代理直接完成对象存储相关工作,而不是额外引入中间层。
优先采用脚本化、输入输出明确的执行方式;只有脚本覆盖不了时,才补临时逻辑。
3. 输出要面向人类
返回结果时优先包含:
- 操作是否成功
- 对象键 / 路径
- URL / ETag / 大小 / 数量等关键信息
- 失败时给出可执行的修复建议
不要把整段 SDK 原始响应直接甩给用户,除非对方明确要原始 JSON。
常用工作流
上传单文件
适用:用户说“把这个文件传到 COS”。
执行前要先确认本地文件存在、路径是文件而不是目录。返回结果时至少包含对象键、访问地址或资源标识、以及是否上传成功。
批量上传
适用:上传整个目录、多个文件、构建产物。
建议策略:
- 先枚举文件列表
- 明确远端前缀映射规则
- 控制并发,避免一下子打爆带宽
- 汇总成功数、失败数、失败文件
如果用户没有指定对象键规则,默认保留相对路径。
大文件上传
适用:视频、模型文件、压缩包。
优先用分片上传接口,并显式设置:
SliceSize
AsyncLimit
- 进度回调
如果要做长时间上传,告诉用户:
- 文件大小
- 并发设置
- 预计风险(网络抖动、覆盖同名对象)
获取签名 URL
适用:用户要临时下载链接、分享给别人。
关键参数:
默认有效期可设为 3600 秒;如果用户没说,明确说明是临时链接。
列目录 / 文件夹视图
COS 没有真实目录,通常要用 Prefix + Delimiter: '/' 模拟文件夹。
当用户要“看看某个目录里有什么”时:
- 优先返回文件夹和文件的分组视图
- 结果过多时只展示前若干项,并提示可继续翻
删除、复制、移动、重命名
这些操作要更谨慎:
- 删除前,确认对象键或前缀范围
- 批量删除前,最好先列出将被删除的对象数量
- 移动/重命名本质通常是复制后删除,要提示这一点
- 跨 bucket 复制时,确认目标 bucket 是否由当前凭证可访问
如果用户表达不明确,比如“删一下旧文件”,先澄清范围。
安全边界
- 绝不在回复里泄露敏感凭证
- 输出配置检查结果时,只给出必要状态,不展示敏感值
- 对删除、批量删除、递归删除操作保持高警惕
- 如果涉及公开分享链接,提醒用户签名 URL 有时效,公开 Bucket 需额外确认
- 不要擅自假设 Bucket 名、地域、对象路径
故障排查
常见问题与处理:
- 凭证错误:检查访问凭证是否正确
- 地域错误:检查地域配置是否和 Bucket 实际地域一致
- Bucket 名错误:确认名称是否完整且可访问
- 本地路径不存在:先校验文件存在
- 自定义域名访问异常:先回退到默认访问域名验证
- 大文件失败:降低并发、增大分片、重试上传