Hubstudio Skill 如何安装与OpenClaw Skills中使用

HubStudio 本地 API 的技能项目，目标是让你可以用统一方式完成：

API 能力检索（有哪些接口、每个接口做什么）
请求参数校验（必填项、类型、约束）
自动化调用（浏览器环境、云手机、账号、分组等）
常见问题排查（HTTP 成功但业务失败、环境无法启动等）

项目核心定位：把 openapi.yaml 的接口能力，转成可查询、可执行、可自动化的工程化工具链。

项目提供的 Skill 能力

1) 全量接口查询能力

基于 openapi.yaml 提供 HubStudio 全量接口定义
当前生成命令总数：56（见 commands.generated.json）
覆盖业务域：
- 浏览器环境
- 云手机
- 环境管理
- 平台账号管理
- 分组管理

你可以快速回答类似问题：

“打开环境接口叫什么？请求体怎么写？”
“批量开启云手机需要哪些字段？”
“某接口返回字段 debuggingPort 是什么含义？”

2) 请求/响应字段解释能力

Skill 可以按接口粒度解释：

请求参数（query/header/body）
必填字段与可选字段
字段类型与含义
响应 code/msg/data 结构

这使得你可以在自动化流程里先做参数检查，再发请求，减少无效调用。

3) 本地 CLI 执行能力（开箱即用）

项目内置 hubstudio.js，可直接调用 HubStudio 本地 API：

node hubstudio.js help
node hubstudio.js list
node hubstudio.js browserStart 1502764609
node hubstudio.js browserStatus 1502764609
node hubstudio.js browserStop 1502764609

也支持生成命令直调：

node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609"}'

4) 浏览器自动化接入能力（Playwright）

项目已提供端到端示例脚本：playwright_hubstudio_baidu_demo.js，可完成：

启动 HubStudio 环境
获取 debuggingPort
使用 Playwright 通过 CDP 连接该浏览器
打开百度并搜索 HubStudio
点击第一条结果并提取正文
生成摘要文件并关闭环境

执行命令：

node playwright_hubstudio_baidu_demo.js

输出结果示例文件：

summary_hubstudio_baidu_playwright.txt

5) ADB 连接辅助能力（云手机）

项目提供云手机 ADB 连接专项说明：ADB_CONNECTION_GUIDE.md，用于：

开启 ADB
查询连接信息
根据 Android 版本选择连接模式
验证 adb devices

项目文件说明

SKILL.md：Skill 主说明（使用指引、调用建议、FAQ）
openapi.yaml：HubStudio OpenAPI 源定义
reference.md：从 OpenAPI 生成的本地接口参考文档
commands.generated.json：从 OpenAPI 生成的 CLI 命令映射
hubstudio.js：统一命令行入口（别名 + 生成命令）
playwright_hubstudio_baidu_demo.js：Playwright 端到端自动化示例
ADB_CONNECTION_GUIDE.md：云手机 ADB 接入指南
OPENCLAW_AGENT_BROWSER_TUTORIAL.md：面向新手的实操教程（当前已切换为 Playwright 流程）

快速开始（建议流程）

1. 环境准备

# 先进入项目根目录（README 所在目录）
cd ./
node --version
openclaw --version

2. 安装依赖（如需运行 Playwright 示例）

npm init -y
npm install playwright

3. 验证 HubStudio API 可用

node hubstudio.js browserStatus 1502764609

若返回 code: 0 说明 API 可正常调用。

4. 运行示例

node playwright_hubstudio_baidu_demo.js

OpenClaw 安装指南：配置 Workspace Skills

本步骤旨在将当前的 hubstudio 项目注册为 OpenClaw 的技能包（Skills）。

前置准备

请确保你已经：
安装了 OpenClaw 主程序。
克隆或下载了 hubstudio 项目代码，并在终端中进入了该项目根目录。

macOS

这些系统原生支持 Bash/Zsh，直接使用以下命令即可。

创建目录结构

bash
mkdir -p "HOME/.openclaw/workspace/skills"

选择安装方式

方式 A：软链接（推荐 - 开发调试用）

特点：修改当前代码后，OpenClaw 立即生效，无需重新复制。适合开发者。

bash
ln -sfn "./" "HOME/.openclaw/workspace/skills/hubstudio"

方式 B：复制文件（稳定版用）

特点：固定当前版本，后续修改当前目录不会影响 OpenClaw。适合普通用户。

rm -rf "HOME/.openclaw/workspace/skills/hubstudio"
cp -R "./" "HOME/.openclaw/workspace/skills/hubstudio"

验证安装

bash
ls -l "HOME/.openclaw/workspace/skills/"

如果看到 hubstudio 指向当前目录（方式 A）或是一个普通文件夹（方式 B），则安装成功。

Windows 系统

Windows 原生命令与 Linux 不同。你有两种执行环境可选：Git Bash（推荐，命令与 Mac 一致）或 PowerShell（系统自带）。

选项 A：使用 Git Bash (强烈推荐)

如果你安装了 Git for Windows：
在项目文件夹内右键，选择 "Open Git Bash here"。
直接复制上方 [macOS / Linux 用户] 部分的命令运行即可，完全通用，无需修改。

选项 B：手动下载解压

从HubStudio Skill 项目源码: <https://github.com/hubstudio-Max/hubstudio-skill>下载Zip源码，解压到 %USERPROFILE%.openclaw\workspace\skills\ 目录下

常见问题与提示

Windows 报错 "UnauthorizedAccess" 或 "拒绝访问"？
原因：创建软链接需要系统权限。
解决：
关闭当前终端。
在开始菜单搜索 PowerShell，右键选择 “以管理员身份运行”。
重新执行命令。
或者，直接选择方式 B（复制模式），通常不需要管理员权限。

路径斜杠问题
macOS/Linux 使用正斜杠 /。
Windows PowerShell 兼容正斜杠 /，上述脚本已做兼容处理，可直接运行。

如何卸载？

只需删除对应的文件夹即可：

Mac/Linux:
    bash
    rm -rf "HOME/.openclaw/workspace/skills/hubstudio"
    Windows (PowerShell):
    powershell
    Remove-Item "$HOME.openclawworkspaceskillshubstudio" -Recurse -Force

完成以上步骤后，重启 OpenClaw，它应该就能识别到 hubstudio 技能包了！

响应判定规范（非常重要）

HubStudio 常见返回结构：

{
  "code": 0,
  "msg": "Success",
  "data": {}
}

判定规则：

HTTP 200 不代表业务成功
以 code 为准：
- code = 0：成功
- code != 0：业务失败（参数、权限、资源状态等）

参数校验模式（团队统一建议）

hubstudio.js 已内置 OpenAPI 驱动的参数强校验，支持两种模式：

strict=true（默认）
- 开启必填、类型、范围、格式、枚举校验
- 拒绝未知字段（如拼错字段名）
strict=false
- 必填、类型、范围、格式、枚举仍然校验
- 仅放过未知字段（用于调试或灰度联调）

1) 默认严格模式（推荐生产）

node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609"}'

2) 临时切换宽松模式（仅用于排障）

node hubstudio.js postV1BrowserStart --strict false --body '{"containerCode":"1502764609","x":1}'

3) 通过环境变量统一设置模式

# 关闭严格模式（当前 shell 会话生效）
export HUBSTUDIO_STRICT_VALIDATION=false
node hubstudio.js postV1BrowserStart --body '{"containerCode":"1502764609","x":1}'

# 恢复严格模式
export HUBSTUDIO_STRICT_VALIDATION=true

4) 校验失败返回格式（标准化）

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "command": "postV1BrowserStart",
    "fieldErrors": [
      {
        "field": "body.containerCode",
        "reason": "required field missing or empty",
        "expected": "required",
        "actualType": "missing"
      }
    ]
  }
}

5) 团队使用建议

日常开发与生产执行统一用默认严格模式
只在定位线上疑难问题时，短时使用 --strict false
排障结束后务必恢复严格模式，避免脏字段长期进入调用链

典型使用场景

批量管理浏览器环境（开关、状态、窗口排列）
云手机应用安装/启动/停止自动化
ADB 开启与连接状态查询
将 HubStudio 接口能力接入 OpenClaw/脚本工作流
用 Playwright 基于 HubStudio 环境做网页自动化

常见问题

1) 接口返回 200 但任务没成功

请检查返回体中的 code 和 msg，不要只看 HTTP 状态码。

2) 启动环境失败

优先检查：

HubStudio 客户端是否登录
是否开通VIP
containerCode 是否存在且属于当前账号
本地服务地址是否是 http://127.0.0.1:6873 端口可能存在变动需要检查

3) 自动化脚本连接不上浏览器

请确认：

browserStart 后返回了 debuggingPort
环境未提前关闭
本机端口未被拦截

参考文档

OpenClaw Getting Started: <https://docs.openclaw.ai/start/getting-started>
HubStudio API Docs: <https://api-docs.hubstudio.cn/>
HubStudio Skill 项目源码: <https://github.com/hubstudio-Max/hubstudio-skill>

2026-03-05