SkillSpace/openclaw/skills/cloud-deploy/SKILL.md

name	version	license	description
cloud-deploy	2.0.1	MIT	一键部署本地项目到云服务器。通过 API 网关模式部署，Token 认证，无需 SSH 私钥。 使用场景包括：(1) 部署前端静态页面，(2) 快速预览开发成果，(3) 分享可访问的 URL 给他人，(4) 安装服务器环境。 触发语句如："部署这个项目"、"推到云服务器上"、"给我个访问链接"、"发布这个静态页面"。 Namespace 规则：使用用户的 contactId 作为命名空间，实现用户隔离

云部署技能 (Cloud Deploy) v2.0

v2.0 重大升级：SSH 直连 → API 网关模式，Token 认证，无需私钥

核心变化（v1.0 → v2.0）

项目	v1.0	v2.0
连接方式	SSH + 私钥	HTTPS + Token
认证	私钥文件	Token（可撤销）
部署方式	rsync + 远程脚本	API 上传 + 远程执行
环境安装	SSH 手动执行	/api/exec 远程执行
安全性	私钥扩散风险	Token 独立管控
审计	无	全量日志

核心功能

• 🚀 一键部署静态页面到云服务器
• 🔑 Token 认证，首次使用自动注册
• 🛡️ 危险命令拦截 + 全量审计日志
• 👥 Namespace 自动隔离（contactId）
• 🎲 自动生成随机目录名
• 🌐 生成可访问的 URL 地址
• 🔧 支持远程执行命令（安装环境等）

配置

环境变量（首次初始化时需要）

变量	说明	必填
DEPLOY_API_URL	API 网关地址	是
DEPLOY_REGISTRATION_KEY	注册码	是
DEPLOY_AGENT_ID	Agent ID	否
DEPLOY_INSTANCE_NAME	实例名称	否

配置文件

初始化后保存在 ~/.openclaw/cloud-deploy.json：

{
  "apiUrl": "<API网关地址>",
  "registrationKey": "<注册码>",
  "token": null,
  "agentId": ""
}

部署时替换占位符：

• <API网关地址> — 部署的 API 服务地址（如 https://your-domain.com/api）
• <注册码> — 服务端配置的 registrationKey

---

工作流程

步骤 0：初始化配置（首次使用）

DEPLOY_API_URL="<API网关地址>" \
DEPLOY_REGISTRATION_KEY="<注册码>" \
bash scripts/init-config.sh

步骤 1：Token 自注册（首次使用自动执行）

触发条件：本地配置中 token 为空

bash scripts/register.sh [contactId]

注册成功后 token 自动保存到配置文件。

步骤 2：获取用户 contactId

从 user_index.json 获取当前用户的 contactId 作为 namespace。

步骤 3：部署

bash scripts/deploy.sh <项目目录> <contactId> <项目名>

脚本自动执行：打包 → 上传 → 部署 → 返回 URL

步骤 4：返回结果

✅ 部署成功！

🌐 访问地址：https://<域名>/<contactId>/<目录名>/
📂 目录名：<随机ID>-<项目名>-<时间戳>
⏱️ 部署耗时：X 秒

---

远程命令执行（安装环境等）

bash scripts/exec.sh "<命令>" [超时毫秒]

安全限制：

• 危险命令会被拦截（递归强制删除根目录、shutdown 等）
• 操作目录受限
• 每条命令都有审计日志

---

API 接口一览

接口	方法	权限	用途	脚本
/api/auth/register	POST	注册码	自注册	register.sh
/api/deploy	POST	deploy	一键部署	deploy.sh
/api/upload	POST	deploy	上传文件	upload.sh
/api/exec	POST	exec	执行命令	exec.sh
/api/deployments	GET	list	查看部署列表	list.sh
/api/deploy/{id}	DELETE	delete	删除部署	delete.sh
/api/health	GET	无	健康检查	health.sh

---

脚本说明

脚本	功能
scripts/init-config.sh	初始化配置文件（环境变量驱动）
scripts/register.sh	Token 自注册
scripts/deploy.sh	主部署脚本（打包+上传+部署）
scripts/pack.sh	打包项目为 tar.gz
scripts/exec.sh	远程执行命令
scripts/upload.sh	上传文件到指定路径
scripts/list.sh	查看部署列表
scripts/delete.sh	删除指定部署
scripts/health.sh	健康检查

---

用户交互模式

模式 1：部署静态页面（最常用）

用户：部署这个静态页面

AI：🔍 检测到项目：landing-page（静态页面）
    🔑 Token 已就绪
    👥 Namespace：<contactId>

    正在部署...
    📦 打包文件中...（15 个文件，2.3MB）
    🚀 上传并部署中...
    
    ✅ 部署成功！
    🌐 访问地址：https://<域名>/<contactId>/<目录名>/
    ⏱️ 部署耗时：5 秒

模式 2：首次使用（自动注册）

用户：部署这个项目

AI：🔍 检测到首次使用云部署，正在初始化...
    📝 配置文件已创建
    🔑 注册成功，Token 已保存
    
    继续部署...
    （后续同模式 1）

模式 3：安装环境

用户：服务器上需要装 Python

AI：🔧 正在执行远程命令...
    > sudo apt update && sudo apt install -y python3 python3-pip
    
    ✅ 执行完成（耗时 12 秒）

模式 4：查看部署列表

用户：看看已部署的项目

AI：📋 你的部署列表（共 N 个）：

    1. <目录名>
       🌐 <URL>
       ⏰ <部署时间>

模式 5：删除部署

用户：删掉第一个项目

AI：🗑️ 已删除 <目录名>
    文件已清理

---

安全设计

Token 机制

要素	说明
注册码	技能配置时注入，只用于注册
Token	每个 AI 助理独立，可单独撤销
权限	deploy / exec / list / delete
审计	每次操作都记录到服务端日志

危险命令拦截

以下命令会被服务端拦截：

• rm 递归强制删除根目录
• shutdown / reboot（关机重启）
• mkfs / dd if=（格式化磁盘）
• iptables -F / ufw disable（关闭防火墙）
• systemctl stop nginx（停止 Nginx）
• curl|bash / wget|bash（远程执行）

路径保护

/api/exec 和 /api/upload 只允许操作服务端配置的允许目录。

管理员操作（仅 owner）

操作	接口
查看所有 Token	GET /api/admin/tokens
撤销 Token	DELETE /api/admin/tokens/{prefix}
查看审计日志	GET /api/admin/audit?date=YYYY-MM-DD

---

服务端部署

API 网关服务端部署说明见 references/server-setup.md

---

目录结构

skills/cloud-deploy/
├── SKILL.md              # 技能说明（本文件）
├── README.md             # 快速入门
├── QUICKSTART.sh         # 快速启动脚本
├── scripts/              # 客户端脚本
│   ├── init-config.sh
│   ├── register.sh
│   ├── deploy.sh
│   ├── pack.sh
│   ├── exec.sh
│   ├── upload.sh
│   ├── list.sh
│   ├── delete.sh
│   ├── health.sh
│   └── legacy/           # v1.0 旧脚本（保留备查）
├── references/           # 参考文档
│   ├── server-setup.md   # 服务端部署指南
│   └── security-guide.md # 安全指南
└── assets/
    └── templates/

---

版本：v2.0.1 | 更新：2026-07-02（安全修复：注入漏洞 + 凭证泄露 + YARA 兼容） v1.0 备份：skills/cloud-deploy-v1.0-backup/