Neura Market Logo

Experimental Claw Packages: Author, Publish, and Discover

Learn how to author, publish, and discover experimental Claw packages on ClawHub. This guide covers package shape, manifest requirements, and the experimental gates for publishers and consumers.

Read this when

  • Authoring a Claw package
  • Publishing a Claw to an experimental ClawHub deployment
  • Discovering published Claws through the package API

Experimental Claw packages

A Claw is a versioned package that bundles a complete OpenClaw agent along with the reusable resources it depends on. ClawHub is responsible for storing and scanning the package, while OpenClaw manages local preview, consent, apply, update, and removal.

Publishing Claws is still experimental. The ClawHub deployment needs to set CLAWHUB_EXPERIMENTAL_CLAWS=1; otherwise, the server will reject any publication attempts. This registry gate operates independently of OpenClaw's OPENCLAW_EXPERIMENTAL_CLAWS=1 consumer gate. Hosting Claws does not enable local preview or installation, and turning on the OpenClaw CLI does not activate ClawHub publication or hosted discovery.

Package shape

A Claw that can be published is a standard package directory containing a package.json that points to its manifest:

{
  "name": "@acme/github-triage",
  "version": "1.0.0",
  "openclaw": {
    "claw": "CLAW.md"
  }
}

CLAW.md begins with the grouped Claw manifest expressed as YAML frontmatter. A non-empty Markdown body serves as the portable agent prompt; OpenClaw applies its exact UTF-8 contents as the managed SOUL.md for the new agent.

---
schemaVersion: 1
agent:
  id: github-triage
  name: GitHub Triage
  description: Reviews incoming issues.
workspace:
  files:
    - source: workspace/reference.md
      path: reference.md
packages:
  - kind: skill
    source: clawhub
    ref: "@acme/triage"
    version: 1.2.0
mcpServers: {}
cronJobs: []
---

# GitHub Triage

Reviews and classifies incoming GitHub issues.

JSON manifests are still supported. Set openclaw.claw to a package-relative JSON file like openclaw.claw.json; since JSON lacks a Markdown body, you must explicitly declare workspace.bootstrapFiles.SOUL.md when an equivalent prompt is needed.

Avoid pairing a non-empty CLAW.md body with an explicit workspace file whose portable destination is SOUL.md. ClawHub will reject this ambiguous dual source. Any headings or task lists in the body are treated as prompt text, not as package-time commands.

Each workspace.*.source must reference a file that exists within the same package. Assets like schemas, templates, examples, and images are portable ordinary workspace files; place them under paths such as assets/, schemas/, or templates/ and list them in workspace.files. Package names and versions must align with package.json, dependency versions must be pinned exactly, and MCP environment values must stay as unresolved ${ENV_VAR} references.

Bootstrap and harness profiles

An optional package-root BOOTSTRAP.md holds first-run instructions. A supporting harness seeds it once, and it stays separate from the reusable portable prompt found in the CLAW.md body. Do not declare root BOOTSTRAP.md as a workspace destination; that path is reserved for the package-root file. ClawHub includes bootstrap presence, but never its contents, in the bounded catalog summary.

Harness-specific tuning follows conventional package paths:

profiles/openclaw.yml
profiles/hermes.yml
profiles/codex.yml

The profiles/ namespace is set aside for these lowercase, single-file .yml paths. Each profile is a JSON-compatible YAML mapping. ClawHub validates the common shape and checks profiles/openclaw.yml against the shipped OpenClaw v1 consumer contract, including registered built-in tool profiles and bounded tool grants; foreign profiles are not interpreted. A harness only discovers its own profile and ignores others when applying the package. The exact published artifact and its digest still cover every profile, bootstrap instruction, and asset.

The retired metadata.openclaw.config pointer is no longer accepted. Move that file to profiles/openclaw.yml and delete the metadata entry.

OpenClaw-native extension packages belong in profiles/openclaw.yml, while portable MCP servers stay in CLAW.md:

schemaVersion: 1
agent:
  tools:
    profile: coding
    allow: [read]
extensions:
  - id: issue-tools
    kind: plugin
    format: openclaw
    source: clawhub
    ref: "@acme/issue-tools"
    version: 2.3.4

Extension ids and package references must be unique, and versions must be exact. Other harnesses may bind the same application needs using their own native profile model; the portable manifest does not impose a capability-name registry.

Validate, build, and publish

Validate the source project and build its deterministic artifact with OpenClaw:

openclaw claws validate .
openclaw claws build . --out ./github-triage-1.0.0.tgz

Preview that exact artifact without uploading it, then publish it through the existing authenticated package flow:

clawhub package publish ./github-triage-1.0.0.tgz --family claw --dry-run
clawhub package publish ./github-triage-1.0.0.tgz --family claw --wait

The CLI detects family: claw when package.json contains openclaw.claw, so --family claw is optional for a well-formed package.

Experimental Claw publication accepts only an already-built npm-pack .tgz, not a source directory or GitHub checkout. The CLI sends the local artifact SHA-256 with the request; ClawHub verifies it against the uploaded bytes before publication and returns the same digest through pending and final responses.

Publication rejects:

  • a missing, invalid, or escaping openclaw.claw path;
  • a source folder instead of a built .tgz;
  • package identity or version mismatches;
  • a missing or mismatched expected artifact SHA-256;
  • malformed CLAW.md frontmatter or manifest fields;
  • a non-empty CLAW.md body combined with an explicit SOUL.md destination;
  • missing workspace source files or portable path collisions;
  • invalid package-root bootstrap instructions or conventional harness profiles;
  • the retired metadata.openclaw.config pointer;
  • floating skill/plugin versions and resolved MCP credentials.

Accepted packages continue through ClawHub's existing ownership, moderation, static scanning, release, and artifact storage pipeline. The stored release retains the exact artifact plus a non-sensitive summary for later search and detail surfaces; downloads return those same bytes and digest, and ClawHub does not duplicate the full manifest into Convex storage.

Discover published Claws

Enabled deployments expose Claws through the existing package API:

curl "https://clawhub.ai/api/v1/packages?family=claw"
curl "https://clawhub.ai/api/v1/packages/search?q=triage&family=claw"
curl "https://clawhub.ai/api/v1/packages/@acme%2Fgithub-triage"

List and search results use the normal package summary fields. Package and version detail responses may also include clawManifestSummary, which reports the agent identity, portable resource counts, harness-profile count, OpenClaw-profile count, and native extension count without exposing the full manifest or profile contents.

When CLAWHUB_EXPERIMENTAL_CLAWS is disabled, explicit family=claw filters are rejected, unscoped list and search results omit Claws, and named Claw reads return not found. Full manifests remain in exact artifacts and are never projected through public release responses.

Consume the experimental feed

Enabled deployments publish eligible official Claws as a separate hosted feed:

curl "https://clawhub.ai/v1/feeds/claws"

This uses a dedicated experimental Claw feed contract rather than extending the stable plugin/skill catalog feed v1 schema.

Each entry provides the exact package version, artifact SHA-256, publisher trust, and clawManifestSummary. Consumers resolve and verify that artifact, unpack it as a normal Claw package directory, and pass the directory to OpenClaw for local inspection or claws add --dry-run. ClawHub does not bypass OpenClaw's preview or consent boundary.

The route returns 404 while CLAWHUB_EXPERIMENTAL_CLAWS is disabled and is not advertised in the registry discovery document until the experimental gate is removed.

Run the repeatable registry-to-OpenClaw proof against an OpenClaw Claws checkout with:

OPENCLAW_CLAWS_CHECKOUT=/path/to/openclaw \
  bunx vitest run scripts/claws-feed-openclaw-e2e.test.ts --maxWorkers=1

The proof provides a deterministic hosted feed along with a package artifact, checks both the feed and the digests of what was downloaded, unpacks the package, and runs the real OpenClaw source CLI using claws add --dry-run --json within a separate state directory.

1,116 words · updated Aug 16, 2026