企业官网建设流程全解析

• 后端
• 前端
• AI 技能
• AI 插件
• 搜索引擎

ClawHub 的 Claw 支持实现了合并后的 OpenClaw RFC 0016、实验性 portable-core 增补（RFC #48）与应用层后续（RFC #52）的注册表侧契约：一个 Claw 包用分组化的CLAW.mdschema 描述一个完整的新 Agent。本文以 specs/claws.md 为主线，结合 specs/experimental-claw-feed.md 与仓库源码，完整讲解可移植 manifest、harness 配置文件（profile）、实验门控、严格 v1 验证、摘要存储模型、精确制品（exact-artifact）发布管线与托管 Feed 契约，并给出可复制的完整示例包。读完后你将掌握：如何按规范构造并发布一个 Claw 包、ClawHub 在注册表侧验证什么、为什么发布必须是"仅精确制品"、以及如何通过 Conformance 向量与--dry-run证明注册表与 OpenClaw 消费者侧的行为一致。

一、定位与职责边界：ClawHub 管什么、OpenClaw 管什么

Claw 包描述的是一个完整的新 Agent，采用分组化CLAW.mdschema（groupedCLAW.mdschema）。在 ClawHub 与 OpenClaw 的分工上，注册表侧拥有：

• 发布（publication）
• 所有权（ownership）
• 发现（discovery）
• 包详情 API（package detail APIs）
• 托管 Feed 导出（hosted feed export）

而 OpenClaw 在本地仍是以下环节的权威方：本地规划（local planning）、同意（consent）、变更（mutation）、来源（provenance）、更新（update）与移除（removal）。也就是说，ClawHub 负责让一个 Agent 包"可被发现、可被验证、可被精确下载"，而"应用层如何消费"完全由 OpenClaw 的本地消费者契约决定。这条边界贯穿全文的每个设计决策：注册表验证永远不比对 pinned 消费者契约更宽松。

二、可移植 Manifest：CLAW.mdFrontmatter、分组 JSON 与隐含SOUL.md

2.1 YAML frontmatter 是可移植 manifest

Claw 包的可移植清单（portable manifest）是CLAW.md的YAML frontmatter。一个CLAW.md包信封（package envelope）可以仅由 frontmatter 构成；当正文包含非空白文本时，正文原文就是隐含的受管SOUL.md工作区文件（implicit managedSOUL.mdworkspace file）；空或纯空白正文则不产生任何隐含文件。

关键约束：manifest 不得声明一个等于、包含或被该隐含SOUL.md路径所包含的工作区目标（即不能显式声明一个与隐含 SOUL.md 冲突的 workspace destination）。

分组 JSON（grouped JSON）形式则完全不同：

• 没有正文，不产生隐含文件；
• 可以显式声明SOUL.md。

2.2 可移植 Agent 对象只携带身份与意图

"可移植 Agent 对象"（portable agent object）只承载identity（身份）与 purpose（意图）。任何 harness 特定的设置都放在包内约定路径profiles/<harness>.yml的包本地 profile 中；manifest 中不含任何 profile 指针。

metadata.openclaw.config已被退役：ClawHub 直接拒绝并给出迁移指引（见下文诊断码claw_v1_legacy_profile_pointer）。

2.3 Manifest 的字段结构（源码级）

packages/schema/src/claws.ts 中的ClawManifestSchema（ArkType 定义）给出了 v1 manifest 的完整字段：

值得注意的 schema 细节：stdio MCP server 支持command、transport: "stdio"?、args、env、toolFilter、timeout、connectTimeout；remote server 支持url、transport: "sse"|"streamable-http"、auth: "oauth"?。toolFilter仅接受include/exclude字符串数组，且按严格 v1 契约只接受精确工具名加*通配符。

三、Profile 系统：profiles/命名空间与openclaw.yml的 profile-v1 结构

3.1 命名空间保留与结构约束

Profile只存在于 Claw 包内部。ClawHub 对profiles/命名空间做出以下保留与强制约束：

• 仅接受小写、单文件的 harness profile（profiles/<harness>.yml）；
• 每个 profile 必须是有界（bounded）的 UTF-8 JSON 兼容 YAML mapping；
• 拒绝：alias、anchor、tag、merge key、非字符串 mapping key、非有限值（non-finite values，如 NaN/Infinity）；
• 应用 harness 时只发现自己的 profile（profiles/openclaw.yml只被 OpenClaw 消费，其余 harness 互不干扰）。

3.2profiles/openclaw.yml的严格 profile-v1 验证

ClawHub 验证profiles/openclaw.yml时遵循严格 profile-v1 结构，其基准是内置 profile 注册表（built-in profile registry），该注册表由一致性制品（conformance artifact，见第五节）pin 住。验证方式：

• 不安装任何扩展；
• 不声称与该 pinned 消费者之外的任何东西兼容；
• 外国（foreign）profile 仍做结构化验证但不做解释（structurally validated but uninterpreted）。

验证范围覆盖：注册的内置 profile、有界工具授权（bounded tool grants）、扩展引用（extension references）、心跳设置（heartbeat settings）及其跨字段规则。ClawHub 对profiles/openclaw.yml的验证绝不比 pinned 的 OpenClaw v1 消费者契约更宽松。

3.3 一致性向量：fixtures/claws/conformance-v1/cases.json

fixtures/claws/conformance-v1/cases.json 记录了消费者契约的提交点（consumer.commit为f8c0e1b8325b1fc36e039cf357a2c4602f76d5aa，repository 为openclaw/openclaw），并保存了代表性的接受/拒绝行为，让注册表与消费者在仓库边界之外保持一致。几个典型用例：

• minimal（agent.tools.profile: minimal）：消费者接受、注册表接受；
• unbounded coding（仅profile: coding，无 allow 约束）：消费者拒绝、注册表拒绝——"unbounded" 不允许；
• dynamic MCP bundle（allow: [bundle-mcp]）：双方拒绝；
• overlong concrete MCP tool（过长的server__tool名）：双方拒绝；
• 心跳用例：every: 30m+activeHours+timeoutSeconds被接受；已退役的skipWhenBusy被拒绝；
• 扩展用例：精确版本的 OpenClaw 扩展（version: 2.3.4）被接受；version: latest这种浮动版本被拒绝；
• metadata 用例：空{}被接受；带openclaw.config指针的注册表拒绝（消费者接受，但注册表承担了更严格的迁移职责）。

这套向量同时是"严格 v1 契约"的可执行体现：字符串不会被 trim 成合法、MCP 包选择器必须解析到精确版本、进程环境键遵循 OpenClaw 的 host 级安全策略、工具过滤器只接受精确名加*通配符。核心原则一句话：注册表验证绝不能接受一个 OpenClaw 客户端会拒绝的声明。

四、BOOTSTRAP.md与其他普通资源

包根目录可选的BOOTSTRAP.md承载经过审核的首次运行说明（first-run instructions）。约束包括：

• 必须是有界的、非空的 UTF-8 文本；
• 不能同时通过可移植工作区文件映射（workspace.files）指向它；
• 它的存在性计入有界 manifest 摘要（bounded manifest summary），但其内容只存在于精确的不可变制品（immutable artifact）中，不复制进 Convex 存储。

Schemas、模板、示例、fixtures 与静态资源不需要任何特殊注册表角色：它们就是普通的已声明workspace.files，由制品摘要（artifact digest）覆盖。

五、实验契约与功能门控

5.1 两个独立的门控

• 后端 Claw 发布与读取面（read surfaces）要求CLAWHUB_EXPERIMENTAL_CLAWS=1；
• 这个托管门控独立于OpenClaw 本地的OPENCLAW_EXPERIMENTAL_CLAWS=1消费者门控——任何一方都不能开启另一方。

源码层面，convex/lib/experimentalClaws.ts 的实现非常直接：

export function experimentalClawsEnabled(env: Record<string, string | undefined> = process.env) { return env.CLAWHUB_EXPERIMENTAL_CLAWS === "1"; } export function isClawFamilyPubliclyVisible( family: string, env: Record<string, string | undefined> = process.env, ) { return family !== "claw" || experimentalClawsEnabled(env); }

即：只有family === "claw"且门控开启时，该 family 才对外可见。

5.2 门控的语义红线

• 门控不是用户同意（user consent），绝不能绕过验证、审核、所有权或扫描器检查；
• 关闭门控的部署不得接受 Claw 发布，也不得通过 Claw 专属发现面暴露 Claws；
• 门控生效期间，公开的 Claw schema 与 API可能变更；移除门控需要单独的兼容性与迁移决策。

六、分阶段实现路线

原规范给出了清晰的六个落地阶段（按 PR 顺序）：

1. 添加共享分组 manifest 契约、安全摘要与存储模型（PR #3089）；
2. 添加功能门控的认证发布、包内容验证、CLI 创作支持与创作文档（PR #3090）；
3. 添加功能门控的搜索、详情与 API 面（PR #3091）；
4. 添加单独门控的托管 Claws Feed，以及通过 OpenClawclaws add --dry-run的可重复发布包证明（PR #3092）；
5. 验证可移植CLAW.mdprompt 正文，将其投影为受管SOUL.md能力元数据，并证明 Feed 到 OpenClaw 的映射（PR #3262，堆叠在 PR #3092 之后）；
6. 采用约定式 harness profile、包根 bootstrap、原生 OpenClaw 扩展与普通应用资产（PR #3328）。

托管投影使用独立的实验性 Claw Feed 契约（详见 specs/experimental-claw-feed.md），不是稳定 plugin/skill catalog feed v1 schema 的扩展。

七、环境策略一致性：OPENCLAW_CLAW_HOST_ENV_POLICY_V1

OPENCLAW_CLAW_HOST_ENV_POLICY_V1是跨仓库的版本化兼容性制品，承载 OpenClaw 的进程环境策略。它记录：

• 精确的 OpenClaw 源路径（source path）；
• 消费者提交（consumer commit）；
• 源文件 SHA-256。

ClawHub 从该制品派生被封禁键（blocked-key）查找表，并把每个键/前缀都作为一致性向量运行。策略变更要求：要么发布一个新的、经过审核的制品版本，要么对现有实验性 v1 契约做有意的更新。这保证了注册表侧的invalidEnvironmentKey/blockedEnvironmentKey等判断始终对齐消费者侧的真实策略。

八、诊断码：稳定、可分支、带 phase

Manifest 拒绝以稳定的claw_v1_*诊断码暴露，phase 恒为schema，并附字段路径与人类可读消息。消费者可以基于 code + phase 分支处理；消息只是解释性文本，不是标识符。

packages/schema/src/claws.ts 定义了完整的 code 集合，例如：

• claw_v1_invalid_manifest_shape
• claw_v1_invalid_agent_id
• claw_v1_non_canonical_string
• claw_v1_empty_list
• claw_v1_legacy_profile_pointer（对应退役的metadata.openclaw.config）
• claw_v1_reserved_workspace_target/claw_v1_unsafe_path/claw_v1_duplicate_workspace_destination
• claw_v1_invalid_avatar/claw_v1_undeclared_avatar
• claw_v1_invalid_package_reference/claw_v1_invalid_package_version/claw_v1_duplicate_package
• claw_v1_invalid_mcp_server_id/claw_v1_invalid_mcp_url/claw_v1_mcp_url_credentials/claw_v1_unpinned_mcp_package
• claw_v1_invalid_tool_filter/claw_v1_duplicate_tool_filter
• claw_v1_invalid_environment_key/claw_v1_blocked_environment_key/claw_v1_invalid_environment_reference
• claw_v1_invalid_timeout/claw_v1_invalid_cron_job_id等

九、存储模型：只存"有界摘要"，不存完整 manifest

9.1 摘要 schema 的双端一致

持久化的版本文档（durable version document）只保存有界的 manifest 摘要（bounded manifest summary）。其字段结构由createClawManifestSummarySchema同时构建于：

• 公开的 ArkType 契约（packages/schema/src/claws.ts）；
• Convex 存储验证器（convex/schema.ts 处使用）。

ClawManifestSummary类型（同文件 L102-L111）为：

type ClawManifestSummary = { schemaVersion: 1; agent: { id: string; name?: string; description?: string }; workspace: { bootstrapFiles: string[]; fileCount: number }; packages: { skillCount: number; pluginCount: number }; profiles?: { count: number; hasOpenClaw: boolean }; extensions?: { count: number }; mcpServerCount: number; cronJobCount: number; };

注意长度上限在 schema 层被显式约束：CLAW_SUMMARY_AGENT_NAME_MAX_CHARS = 128、CLAW_SUMMARY_AGENT_DESCRIPTION_MAX_CHARS = 1_024（L6-L7）。Convex 无法表达这些文本长度上限，所以发布流程必须在入库前通过共享 schema 完成摘要的验证或推导。

9.2 摘要只暴露 footprint

新摘要额外暴露的是profile / 扩展足迹（footprint）：harness profile 总数、约定式 OpenClaw profile 数、OpenClaw 原生扩展计数。它永不暴露 profile 内容。同样，workspace.bootstrapFiles只记录文件名列表，BOOTSTRAP.md的存在性进摘要、内容只在精确制品中。这一设计保证了：Convex 存储的可检索面最小化，而权威数据始终是那条精确字节的不可变制品。

十、发布管线：复用现有包管线，但"仅精确制品"

10.1package.json与 manifest 路径

Claws 走现有的包发布管线（package publication pipeline）。package.json声明包身份、版本与package 相对路径的openclaw.clawmanifest 路径。发布时：

• 解析CLAW.mdYAML frontmatter 或 JSON 兼容形式；
• 验证分组 manifest、被引用的工作区文件、约定式 harness profile 与可选的包根 bootstrap；
• 非空 Markdown 正文即可移植 Agent prompt，映射为受管SOUL.md；发布拒绝"正文 + 任何显式 SOUL.md 工作区声明"的组合；
• release 保留精确制品与有界派生摘要（含隐含 prompt 与 bootstrap 的存在性），不把完整 manifest、prompt 正文、profile 或 bootstrap 内容复制进 Convex 存储；
• 服务端在门控关闭时、于任何变更（mutation）之前拒绝family: claw；门控开启也不绕过所有权、审核、扫描或发布不变式。

10.2 exact-artifact-only：只有 tgz 能发布

实验性 Claw 发布是仅精确制品（exact-artifact-only）：

• 发布者必须提交已构建好的 npm-pack.tgz；源文件夹、GitHub checkout、解压文件载荷、以及旧版 public-action 路径都不能发布 Claw release；
• 发布者提供该 tarball 的规范小写 SHA-256。ClawHub 在变更前从上传字节重算摘要，缺失或不匹配即拒绝；
• 验证通过的 tarball 摘要贯穿：分阶段扫描、finalize、发布状态响应与精确字节下载，作为制品身份的凭据；
• 分阶段重试身份包括：actor、owner、包名、版本与已验证制品摘要。只有精确重试才能复用同一活动 pending attempt 或活动已发布 release；不同 actor/owner/摘要、终态 attempt、或已删除/封禁/隔离/撤销/恶意 release 一律视为版本冲突；
• 重试兼容性仅限于 Claws。现有非 Claw 包行为与历史 attempt 恢复保持不变（除非其自身契约已携带所需的确切制品元数据）。

10.3 可复制的发布示例包

仓库中的 fixtures/claws/hosted-e2e/package 是一个完整的托管 E2E 示例，展示了规范要求的全部要素。package.json：

{ "name": "@openclaw/hosted-e2e", "version": "1.0.0", "type": "module", "openclaw": { "claw": "CLAW.md" } }

CLAW.md（frontmatter + 正文 prompt）：

--- schemaVersion: 1 agent: id: hosted-e2e name: Hosted E2E workspace: bootstrapFiles: HEARTBEAT.md: source: HEARTBEAT.md files: - source: assets/incident.schema.json path: assets/incident.schema.json packages: [] mcpServers: {} cronJobs: [] --- # Hosted E2E Use the published Claw package without mutating local state during proof.

profiles/openclaw.yml（profile-v1，最小工具授权 + 工作区限定 + 自然人类延迟）：

schemaVersion: 1 agent: tools: profile: minimal fs: workspaceOnly: true humanDelay: { mode: natural }

以及BOOTSTRAP.md（"Ask which services the user owns before beginning."）与HEARTBEAT.md（"Check the hosted Claw fixture heartbeat."）。该示例同时出现在 conformance-v1/cases.json 的projectArtifact中，被消费者与注册表双方接受。

十一、托管 Feed 契约与 Registry→OpenClaw 证明

11.1 Feed 契约要点

Claws Feed 是独立的实验性 wire 契约（完整定义见 specs/experimental-claw-feed.md），不向稳定 catalog feed schema v1 添加type: "claw"。契约要点：

• 路由：/api/v1/feeds/claws，代理为/v1/feeds/claws；
• Feed id：clawhub-official-claws；实验性 schema 版本1；
• 门控：CLAWHUB_EXPERIMENTAL_CLAWS=1；条目类型仅claw；
• 安装坐标：规范包名 + 精确 release 版本；
• 完整性：sha256:<不可变制品 sha256>；
• 元数据：有界的clawManifestSummary，绝不携带完整 manifest；
• 启用与禁用两种状态下都用Cache-Control: no-store且无 surrogate cache，切换门控不会在边缘留下已启用的响应；禁用时在读取任何持久化发布状态之前直接返回404，无未版本化的 Vercel 重定向，实验期间也不在/.well-known/openclaw-registry.json中做广告。

Feed 解析器拒绝：通用 plugin/skill 条目、未知 feed id、未知字段、非法时间戳、不支持的 schema 版本、非官方发布者，以及没有恰好一个安装候选的条目。该候选必须匹配条目的 package/version，且使用小写sha256:加恰好 64 个十六进制字符。

11.2 证明边界：scripts/claws-feed-openclaw-e2e.test.ts

scripts/claws-feed-openclaw-e2e.test.ts 是注册表到 OpenClaw 的桥接证明：解析实验性 Feed → 选择恰好一个 ClawHub 候选 → 用 Feed 摘要核对制品元数据与下载字节 → 有界安全解包 → 把包目录交给真实 OpenClaw 的claws add --dry-run --json命令在隔离状态下执行。它证明的是：ClawHub 广告的包能产生一个非变更（non-mutating）的 OpenClaw 计划。它不声称 OpenClaw 自身能解析 ClawHub Feed URL——消费者侧集成是另一条独立的依赖轨道。

配套细节：合法 TGZ fixture 与发布走同一条npm pack --ignore-scripts路径；非法链接/特殊条目 fixture 使用确定性 ustar 字节而非宿主tar实现；ClawHub CI 检出声明的 OpenClaw 契约 SHA 并安装其冻结依赖来运行该桥接，变更该 SHA 即一次显式兼容性更新。下载上限 64 MiB；TGZ 解析复用 npm-pack 路径（强制规范package/路径、仅常规文件/目录、10,000 条目、展开内容 50 MiB、可移植重复拒绝）；Legacy ZIP 解包沿用相同的条目/展开大小/路径/可移植冲突边界，支持package/或归档根两种布局。

十二、总结：从"可移植声明"到"可证明消费"

回看整条链路，Claw 支持的架构可以浓缩为三条原则：

1. 声明最小化：可移植 manifest 只描述身份与意图，harness 细节全部下沉到profiles/，正文 prompt 成为隐含SOUL.md——包是"可移植的 Agent 描述"，不是"某特定运行时的配置快照"；
2. 验证与消费对齐：conformance-v1/cases.json与OPENCLAW_CLAW_HOST_ENV_POLICY_V1让注册表验证永远不宽于 pinned 消费者契约，claw_v1_*码让拒绝可程序化处理；
3. 存储最小化、制品权威化：Convex 只存有界摘要，完整内容只存在于精确不可变制品；发布必须提交自构建 tgz 与规范 SHA-256，下载、扫描、重试、Feed 完整性全部锚定这一摘要。

对希望参与实验或消费 Claws 的开发者，推荐按以下路径深入：先阅读 specs/claws.md 与 specs/experimental-claw-feed.md，再对照 fixtures/claws/hosted-e2e/package 与 fixtures/claws/conformance-v1/cases.json 理解合法/非法形态，最后在启用了CLAWHUB_EXPERIMENTAL_CLAWS=1的环境中以npm pack --ignore-scripts产出的 tgz 走发布管线，并用claws add --dry-run验证消费者侧计划。注意：门控生效期间 schema 与 API 可能变化，任何跨仓库的消费者契约 SHA 更新都应视为显式兼容性决策。

• 后端
• 前端
• AI 技能
• AI 插件
• 搜索引擎