ClawHub 内容权利通信规范化:用 Admin CLI 完成下架通知、请求方回信与审计留档

原创2026-09-24 19:37:041,927 阅读
文章标签:人工智能AI 技能后端前端CLI认证鉴权

ClawHub 内容权利通信规范化:用 Admin CLI 完成下架通知、请求方回信与审计留档

本文围绕 ClawHub 仓库内的运营技能文档 clawhub-content-rights-correspondence/SKILL.md,讲解平台运营人员如何**仅通过认证的 Admin CLI(bun run admin)**完成内容权利(Content Rights,案件 ID 形如 CHR-...)的邮件起草、预览、签署发送与精确留档。文中将同时深入 email send 与 content-rights record-correspondence 两条命令背后的参数约束、Hermit 代理链路与 RBAC 校验,帮助你安全、可审计地处理下架通知与请求方状态更新两类典型通信。

一、这套技能解决什么问题

ClawHub 是 OpenClaw 的 Skill + Plugin Registry。当第三方认为平台上发布的内容侵犯其版权或相关权利时,可以在公开侧提交内容权利请求(参见 docs/content-rights.md:请求方需要提供精确的 https://clawhub.ai/<owner>/skills/<skill> URL、姓名/组织、联系邮箱、权利说明与支持证据,由 ClawHub 员工人工审核,受影响内容可能被隐藏、恢复或保持原样)。

这些请求在内部以 CHR-... 案件(case)的形式维护在 Hermit 服务中。运营侧回复请求方、通知被下架内容的发布者,属于内容权利通信(Content Rights Correspondence)。技能文档的核心约束是:

  • 通信一律使用 ClawHub 的认证 Admin CLI 命令(bun run admin -- email send、bun run admin -- content-rights record-correspondence);
  • 禁止使用 helper 脚本、直接调用 Hermit、直接访问 R2 存储来完成通信相关操作;
  • 要求"先预览、后签署、再发送、最后留档"的完整流程。

仓库里甚至有一份专门测试该技能文档本身的测试 tests/clawhub-content-rights-correspondence.test.ts,断言文档中不得出现 send-correspondence、scripts/ 等字样(防止退回 helper 脚本时代),同时必须包含 bun run admin -- email send、--send/--confirm-user-request/--confirm-user-signoff 签署守卫,以及 record-correspondence 与 --provider-message-id、--attachment 留档要素。

二、运行前提:认证的 Admin CLI

技能文档要求"从 ClawHub 仓库根目录、使用正常的认证 Admin CLI 运行"。相关基础设施如下:

  • 仓库根目录 package.json 中定义了 "admin": "bun packages/clawhub-admin/src/cli.ts"(第 11 行),因此统一入口是 bun run admin -- <子命令>;
  • Admin CLI 复用公共 CLI 的认证、配置、HTTP 与 schema 工具,但它是独立的维护者命令面(详见 packages/clawhub-admin/README.md:该包标记为 private: true,不会发布到 npm,运行时直接使用仓库当前代码);
  • 认证方式与公共 CLI 相同:bun run admin -- login(设备流或 --token <token>),随后可用 bun run admin -- whoami 校验令牌;
  • 全局参数与环境变量(见 cli.ts 第 81-101 行):--workdir、--dir、--site、--registry、--no-input,以及 CLAWHUB_SITE、CLAWHUB_REGISTRY、CLAWHUB_WORKDIR、CLAWHUB_ADMIN_COMMIT;
  • "从仓库根目录运行"的底层依据在 resolveWorkdir/hasClawhubMarker(第 133-155 行):CLI 会检测当前目录是否存在 .clawhub/lock.json、.clawhub 目录或旧的 .clawdhub 标记,从而把工作目录解析为仓库根;
  • 本地联调建议(README):用 CLAWHUB_CONFIG_PATH 隔离配置,并把 --registry 指向 Convex HTTP actions URL(如本地 http://127.0.0.1:3211),避免污染日常 CLI 登录态。

需要强调:content-rights 后端只对 admin 角色开放(见下文 Hermit 代理链路的 requireAdminOrResponse,非管理员会收到 403),因此执行本技能前请确认令牌拥有 admin 权限。

三、两条核心命令的参数速查

3.1 email send(发送对外邮件)

注册于 cli.ts 的 registerEmailCommands(第 503-530 行),实现于 packages/clawhub-admin/src/commands/email.ts。

参数 必填 说明
--to <email> 与 --user 二选一 收件人邮箱;与 --user 互斥
--user <handle> 与 --to 二选一 收件人 ClawHub 用户 handle,由服务端解析其邮箱
--username <handle> 否 收件人用户名,用于查询或直接邮件的元数据
--recipient-handle <handle> 否 直接邮件场景的收件人元数据 handle
--subject <subject> 是 邮件主题(上限 200 字符)
--title <title> 否 通用模板中的可见标题(上限 160 字符);内容权利通信中禁用
--body-file <path> 与 --body 二选一 纯文本正文文件
--body <text> 与 --body-file 二选一 内联纯文本正文(仅适合短消息)
--action-label/--action-url(别名 --button-text/--button-link) 成对 通用模板主按钮;内容权利通信中禁用
--send 否 真正发送;缺省为 dry-run 预览
--confirm-user-request 发送时必填 确认用户明确要求发送这封邮件
--confirm-user-signoff 发送时必填 确认用户已签署最终收件人/主题/正文
--json 否 JSON 输出

3.2 content-rights get / content-rights record-correspondence(案件读取与留档)

注册于 cli.ts 的 registerContentRightsCommands(第 474-501 行),实现于 packages/clawhub-admin/src/commands/contentRights.ts。

content-rights get <caseId> [--json]:读取已有 CHR-... 案件(含案件信息、文件与事件列表)。

content-rights record-correspondence <caseId> 的参数:

参数 必填 说明
<caseId> 是(位置参数) 已有案件 ID,如 CHR-000007;CLI 会归一化为大写并校验 ^CHR-\d+$
--direction <direction> 是 inbound 或 outbound
--to <email> 是 通信收件人
--from <sender> 是 通信发件人(建议与真实发件人一致,如 ClawHub <noreply@notifications.openclaw.ai>)
--subject <subject> 是 精确的通信主题
--body-file <path> 是 精确的纯文本通信正文(不可为空)
--provider-message-id <id> 否 邮件服务商消息 ID(取自 email send 响应)
--attachment <path> 否,可重复 需归档的证据附件
--json 否 JSON 输出

四、安全规则(必须完整遵守)

技能文档列出了若干不可妥协的安全规则,以下逐条完整继承并给出实现依据:

  1. 必须已有 CHR-... 案件:本技能只处理既有案件的通信,绝不创建案件(get/record-correspondence 都要求传入已有 case id)。
  2. 先 dry-run,展示最终收件人、主题与正文:email send 默认就是 dry-run(dryRun = options.send !== true),会打印模板名 generic-one-off、收件人、主题与完整正文,并提示"To send: rerun with --send --confirm-user-request --confirm-user-signoff"。
  3. 只在用户明确签署后发送:发送时 requireSendSignoff 强制要求同时带上 --confirm-user-request 与 --confirm-user-signoff,缺少任何一个都会拒绝发送并给出原因(见 email.ts 第 105-116 行)。
  4. 邮件已发送但留档失败时不要重发:直接上报失败,由 staff 修复审计记录,避免重复邮件造成二次困扰。
  5. --attachment 文件会随通信归档,但通用邮件模板不会发送附件(附件只进 Hermit 证据库,不附在邮件里)。
  6. 通用模板自带问候语:正文文件里不要写 Hello .../Hi ...。
  7. 通用模板可能把主题渲染成可见标题:不要传 --title,正文里也不要重复标题文字。
  8. 不要使用通用邮件的 action 按钮:内容权利回复中的表单 URL 必须以纯文本形式写在正文里(这也正是下架通知正文中 https://forms.openclaw.ai/clawhub-content-rights 以纯文本出现的原因)。

五、场景一:Publisher Removal Notice(发布者下架通知)

当收到涉及 Rednote/Xiaohongshu 平台权利的内容权利请求并已下架技能后,向发布者发送下架通知。技能文档规定使用固定主题与正文,只替换其中的技能 URL:

主题:

ClawHub skill removal notice

正文(仅替换 https://clawhub.ai/<owner>/<slug>):

We removed the following ClawHub skill after receiving a content rights request involving Rednote/Xiaohongshu platform rights:

https://clawhub.ai/<owner>/<slug>

If you believe this removal was made in error, please submit a response using this form:
https://forms.openclaw.ai/clawhub-content-rights

第一步:预览(dry-run)。此时不会发送任何邮件:

bun run admin -- email send \
  --user <publisher-handle> \
  --subject "ClawHub skill removal notice" \
  --body-file /tmp/body.txt

注意预览阶段使用 --user <publisher-handle>(发布者的 ClawHub handle,服务端解析其邮箱);此命令输出收件人、模板、主题与正文,供用户核对。

第二步:签署发送。仅在用户对最终收件人、主题、正文明确签署后执行:

bun run admin -- email send \
  --user <publisher-handle> \
  --subject "ClawHub skill removal notice" \
  --body-file /tmp/body.txt \
  --send \
  --confirm-user-request \
  --confirm-user-signoff \
  --json

--json 便于脚本化读取发送响应;发送成功后响应中会带有收件人信息与邮件服务商的消息 ID(即留档时的 <providerId-from-send-response> 来源)。

第三步:精确留档。将上面实际发送的这封邮件原样记录进案件:

bun run admin -- content-rights record-correspondence CHR-000007 \
  --direction outbound \
  --to "<publisher-handle-or-email>" \
  --from "ClawHub <noreply@notifications.openclaw.ai>" \
  --subject "ClawHub skill removal notice" \
  --body-file /tmp/body.txt \
  --provider-message-id "<providerId-from-send-response>" \
  --json

--to 这里应填写实际的收件人(handle 或邮箱);--from 与真实发件人保持一致;--provider-message-id 把发送响应中的消息 ID 存入审计记录,形成"发送—留档"闭环。

六、场景二:Requester Status Updates(请求方状态更新)

对请求方(提交内容权利表单的人)发送进展更新或结案说明时,使用直接邮件(--to 邮箱),并且避免在主题中暴露内部案件 ID,除非用户明确要求这样做。

预览:

bun run admin -- email send \
  --to requester@example.com \
  --username Requester \
  --subject "Update on ClawHub content rights request" \
  --body-file /tmp/body.txt

这里 --to 与 --username 同时出现是有意为之:在 CLI 的收件人解析逻辑中(email.ts 第 61-72 行),--to 提供邮箱,--username 则作为该直接邮件的收件人元数据(recipientHandle)一并携带,让邮件以"Requester"而不是裸邮箱的形式呈现。

签署发送:

bun run admin -- email send \
  --to requester@example.com \
  --username Requester \
  --subject "Update on ClawHub content rights request" \
  --body-file /tmp/body.txt \
  --send \
  --confirm-user-request \
  --confirm-user-signoff \
  --json

留档(此时 --to 写成带名字的完整形式,便于 Hermit 记录展示):

bun run admin -- content-rights record-correspondence CHR-000007 \
  --direction outbound \
  --to "Requester Name <requester@example.com>" \
  --from "ClawHub <noreply@notifications.openclaw.ai>" \
  --subject "Update on ClawHub content rights request" \
  --body-file /tmp/body.txt \
  --provider-message-id "<providerId-from-send-response>"

验证留档是否成功:

bun run admin -- content-rights get CHR-000007 --json

返回的案件 JSON 中应能看到新追加的 correspondence 事件,确认审计记录完整。

七、底层实现:邮件发送链路

email send 的实现集中在 packages/clawhub-admin/src/commands/email.ts:

  • 固定模板:STAFF_EMAIL_TEMPLATE = "generic-one-off"(第 28 行),发送请求与 dry-run 预览都携带该模板名;
  • dry-run 默认:dryRun = options.send !== true(第 129 行),预览对象包含 template、recipient、subject、可选 title/primaryAction 与 body;非 JSON 模式会打印"Staff email dry run. No email was sent."并附完整正文;
  • 签署守卫:requireSendSignoff(第 105-116 行)在两个确认 flag 缺失时直接 fail,并提示"用户必须签署最终收件人、主题与正文后,再以 --send --confirm-user-request --confirm-user-signoff 重跑";
  • 输入校验:--subject 上限 200 字符、--title 上限 160、--body 上限 20000、action label 上限 80、action URL 上限 2000 且必须是 http(s);--to 必须是合法邮箱格式;--to 与 --user 互斥;--body-file 与 --body 互斥;action label/url 必须成对出现——这些校验把运营误操作挡在发送之前;
  • 发送请求:POST 到 ApiRoutes.users/email(即 /api/v1/users/email,见 packages/clawhub/src/schema/routes.ts 第 33 行),body 携带 template、subject、title、body、可选的 primaryActionLabel/primaryActionUrl,并强制写入 confirmUserRequest: true 与 confirmUserSignoff: true(第 169-192 行);响应通过 ApiV1StaffEmailSendResponseSchema 校验。

八、底层实现:通信留档链路(CLI → Convex → Hermit)

content-rights 命令背后是一条完整的前后端链路:

8.1 CLI 端组装

packages/clawhub-admin/src/commands/contentRights.ts:

  • normalizeCaseId(第 23-27 行):trim + 转大写,必须匹配 ^CHR-\d+$,否则直接 fail("Case id must match CHR-...");
  • 必填校验(第 76-84 行):--direction 只能是 inbound/outbound;--to/--from/--subject/--body-file 均必填;正文读取后 trim,空正文拒绝;
  • 附件处理(第 95-101 行):--attachment 可重复传入,按扩展名映射 MIME 类型(.pdf→application/pdf、.png→image/png、.jpg/.jpeg→image/jpeg、.json→application/json、.txt/.md→text/plain,其余 application/octet-stream),读取字节后以文件名构造 File 追加到 FormData;
  • 请求(第 105-111 行):POST /api/v1/content-rights/<caseId>/correspondence,FormData 字段为 direction/to/from/subject/text/可选 providerMessageId/attachments。

8.2 Convex HTTP 路由与 RBAC

  • 路由注册在 convex/http.ts:GET /api/v1/content-rights/(第 424-428 行)与 POST /api/v1/content-rights/(第 454-458 行)都挂到 contentRightsV1Handler;基础路径常量 contentRights: "/api/v1/content-rights" 见 routes.ts 第 34 行;
  • 处理器 convex/httpApiV1/contentRightsV1.ts 第 72-84 行依次执行:applyRateLimit(GET 走 read、其余走 write 限流)→ requireApiTokenUserOrResponse(API token 鉴权,失败返回 401)→ requireAdminOrResponse(convex/httpApiV1/shared.ts 第 261-268 行,内部调用 assertAdmin,非 admin 返回 403 "Admin role required.")。

8.3 Hermit 代理

proxyHermitContentRightsRequest(contentRightsV1.ts 第 31-70 行):

  • case id 再次校验 ^CHR-\d+$,不符返回 404 "Case not found";
  • GET 且路径只有一段时,转发到 Hermit 的 /api/clawhub-content-rights/cases/<caseId>;
  • POST 且第二段为 correspondence 时,读取表单并注入 actor 字段为当前 admin 的 userId(防止调用方伪造操作者),再转发到 /api/clawhub-content-rights/cases/<caseId>/correspondence;
  • Hermit 地址取环境变量 HERMIT_CONTENT_RIGHTS_BASE_URL(默认 https://forms.openclaw.ai),服务令牌取 CLAWHUB_BAN_APPEALS_TOKEN;令牌缺失返回 503 "ClawHub-Hermit service token is not configured",代理请求异常返回 502 "Hermit content rights service unavailable"。

8.4 测试证据

九、验证与常见故障处理

  • 验证留档:执行 content-rights get CHR-000007 --json,确认案件事件列表中出现了刚记录的 correspondence(含方向、收件人、主题、正文与附件)。
  • 发送后留档失败:不要重发邮件。技能规则明确要求上报失败,由 staff 修复 Hermit 审计记录,避免同一内容发送两遍。
  • 发送被拒:缺少 --send 只会得到 dry-run 预览;缺少 --confirm-user-request 或 --confirm-user-signoff 会被 requireSendSignoff 直接拒绝——这是设计好的护栏,不是 bug。
  • 案件 ID 错误:CLI 与后端都会校验 ^CHR-\d+$(大小写不敏感,统一转大写),格式不符即失败。
  • 留档参数错误:--direction 只接受 inbound/outbound;--to/--from/--subject/--body-file 缺一不可;正文为空同样拒绝。
  • 收件人冲突:--to 与 --user 同时传入会被拒绝;--body-file 与 --body 同理。

十、与其他文档的关联

  • 公开侧入口:docs/content-rights.md 面向请求方说明提交内容权利请求需要提供的材料;本技能文档则是运营侧处理这些请求时的内部通信规范,二者共同构成"请求提交 → 人工审核 → 邮件通信 → Hermit 留档"的完整闭环。
  • 回复邮件中的表单 URL(https://forms.openclaw.ai/clawhub-content-rights)正是请求方提交与申诉的入口,因此下架通知中必须以纯文本给出,方便误判的发布者走表单申诉流程。
  • Admin CLI 的完整运维命令面(用户管理、包/技能审核、org 管理等)见 packages/clawhub-admin/README.md,内容权利通信只是其中受严格约束的一个子集。

总而言之,ClawHub 内容权利通信的最佳实践可以浓缩为一条可执行流水线:用 email send 默认的 dry-run 完成起草与人工签署,用 --send --confirm-user-request --confirm-user-signoff 完成唯一一次发送,再用 content-rights record-correspondence 将包含 provider message id 与证据附件的精确副本写入 Hermit 案件,最后用 content-rights get 复核留档结果——每一步都有 CLI 校验、RBAC 与测试用例兜底,确保内容权利案件通信既高效又完全可审计。

登录后查看全文
clawhub