OpenClaw 连接灏天文库 - ht-skills 使用指南

一、ht-skills 是什么？

name: ht-skills
description: 管理灏天文库文集和文档，支持新建、查询、更新、层级设置与文档移动

ht-skills 是专为 OpenClaw 设计的灏天文库管理技能，通过服务端 API 调用实现：

新建文集、新建文档：将内容直接写入灏天文库
查询文集列表、查询文档列表：快速定位已有内容
更新文集/文档、设置文档父级、移动文档到目标文集
适用于 OpenClaw 自主写文章并上传、文集创建、文档入库等场景

包含的功能

脚本	HTTP 方法	路由地址	说明
create_collection.py	POST	/api/collections	新建文集
list_collections.py	GET	/api/collections	查询文集列表
get_collection.py	GET	/api/collections/{id}	查询文集详情
update_collection.py	PATCH	/api/collections/{id}	更新文集信息
set_document_parent.py	PATCH	/api/collections/{collection_id}/documents/{document_id}/parent	设置文档父级
add_document.py	POST	/api/documents	新建文档到指定文集
list_documents.py	GET	/api/documents	查询文档列表
get_document.py	GET	/api/documents/{id}	查询文档详情
update_document.py	PATCH	/api/documents/{id}	更新文档
move_document.py	PATCH	/api/documents/{id}/collection	修改文档归属（移动到目标文集）
get_garden_limits_usage.py	GET	/api/garden/limits-usage	查询个人花园限制与当前用量
create_image_group.py	POST	/api/image-groups	创建图片分组
list_image_groups.py	GET	/api/image-groups	查询图片分组列表
update_image_group.py	PATCH	/api/image-groups/{id}	修改图片分组名称
get_image_limits_usage.py	GET	/api/images/limits-usage	查询图片上传额度与占用
upload_image.py	POST	/api/images/upload	上传图片（multipart）
list_images.py	GET	/api/images	查询当前用户图片列表
get_image.py	GET	/api/images/{id}	查询图片详情（含外链地址）

使用前需在 config.json 中配置 token（个人 API Token）；server_base_url 默认使用 https://zzht.tech，可不填写。

二、Client 端（用户 Skill）是什么？

可以把整个项目想成「前台 + 后台」：Client 端是装在你电脑或 OpenClaw 环境里的小助手程序（一堆 Python 脚本），负责按你的 Token 去请求服务端开放的接口；服务端连接着灏天文库业务规则。你在 OpenClaw 里用的 ht-skills，指的就是这个 client 打包成的技能。

Client 里有什么

scripts/：每个脚本对应一类操作（建文集、发文、查列表、传图等），OpenClaw 或你在终端里执行的就是这些文件
lib/api_client.py：统一发 HTTP 请求，自动带上 Authorization: Bearer <token>（或等价请求头），避免每个脚本重复写鉴权
config.json：填写 token 与可选的 server_base_url；也可用环境变量代替配置文件

配置方式（二选一即可）

方式	说明
`config.json`	在技能根目录复制 `config.example.json` 为 `config.json`，填写 `token`；`server_base_url` 不写则默认 `https://zzht.tech`
环境变量	`HT_SKILL_TOKEN` 必填（等同 token）；`HT_SKILL_SERVER_URL` 可选，不写则默认同上服务地址。适合不想把 Token 写进文件的场景

使用 Client 时要注意的几条规则

查文档列表：必须先知道文集 ID，调用 list_documents.py 时必须带 --collection-id；不知道 ID 时先用 list_collections.py --name "关键词" 查文集
文集列表 / 文档列表：分页参数由服务端统一限制
改文档：可以改标题、正文、排序、父文档
数据范围：普通用户只能看到和操作自己账号下的文集与文档
文本与图片：新建或修改文集、文档时服务端会做敏感词等审核；图片上传是否审核取决于服务端

本地试跑一条命令（可选）

装好依赖并配置 Token 后，在 client 目录下执行：

python scripts/list_collections.py

若能返回 JSON 文集列表，说明 Client 已正确连上服务端且 Token 有效。

三、ht-skills 技能安装教程（OpenClaw / Client）

获取 ht-skills 技能包
从 OpenClaw 技能市场或官方渠道获取 ht-skills 技能安装包，也可以从 GitHub 仓库下载。
安装技能到 OpenClaw（安装的就是 client 目录）
将仓库里的 client/ 整个文件夹复制到 OpenClaw 技能目录，例如：
~/.openclaw/workspace/skills/ht-skills/（Windows 用户请将 ~ 换成你的用户主目录对应路径）。复制完成后在 OpenClaw 里刷新技能列表。
配置 config.json 或环境变量
在技能根目录（即复制后的 ht-skills/）准备 config.json，填入：
- server_base_url：API 根地址，默认 https://zzht.tech（可不填）
- token：你的个人 API Token（见下方「个人 Token 获取」）
若使用环境变量：设置 HT_SKILL_TOKEN（必填），可选 HT_SKILL_SERVER_URL 覆盖服务地址。
验证连接
在 OpenClaw 中发起一次「列出我的文集」或类似指令，若成功返回文集列表，则配置正确。

四、灏天文库 API 限制说明

个人花园相关接口根据用户等级和会员状态进行限制。

限制参数一览

限制项	说明	与用户等级 / 会员的关系
文集数量	可创建的个人花园文集数量上限	按等级 tier 1~6 分别对应 2/4/6/8/10/12 个；会员 = 基础数 × 会员倍数（2 倍）
每文集文档数	单个文集内最大文档数	普通用户：50 篇 / 会员：150 篇
每文档字数	单篇文档最大字符数	普通用户：20,000 字 / 会员：50,000 字

用户等级 tier 对照

tier	等级范围	头衔	基础文集数
1	1-4	新手	2
2	5-9	入门	4
3	10-19	进阶	6
4	20-29	资深	8
5	30-49	专家	10
6	50+	大师	12

说明：会员用户的可建文集数 = 基础文集数 × 会员倍数。升级等级或开通会员可提升限制。

五、个人 Token 怎么获取？

调用灏天文库 API 前，必须先获取个人 API Token。Token 用于认证你的身份，请勿泄露。

登录灏天文库
访问 aiknowledge.cn 并登录你的账号。
进入个人中心
点击右上角头像，选择「个人中心」。
查看 Token
在个人中心的Token 信息区域，可以看到你的 apiToken。若尚未生成，系统会自动创建。
复制并配置
点击「复制」按钮复制 Token，粘贴到 ht-skills 的 config.json 中的 token 字段。

前往个人中心获取 Token →

刷新说明：用户每周可刷新一次 Token；若 Token 泄露，请及时刷新以失效旧 Token。