diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 4bbd67e81..f9fd7ca9f 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,15 @@ { "repository": "openclaw/openclaw", - "sha": "83aad863fd779b70d1a82a6d5f68d0e382de90eb", - "syncedAt": "2026-05-08T01:06:39.872Z" + "sha": "10f9a758b62db3d0e4dca7f3b15724ba71dd1677", + "sources": { + "openclaw": { + "repository": "openclaw/openclaw", + "sha": "10f9a758b62db3d0e4dca7f3b15724ba71dd1677" + }, + "clawhub": { + "repository": "openclaw/clawhub", + "sha": "86898837fb3aa9f7370d8b15a1c2bb50e7aa9793" + } + }, + "syncedAt": "2026-05-08T01:56:32.638Z" } diff --git a/docs/.i18n/zh-Hans-navigation.json b/docs/.i18n/zh-Hans-navigation.json index 1f2a7b1ae..4380ee2ca 100644 --- a/docs/.i18n/zh-Hans-navigation.json +++ b/docs/.i18n/zh-Hans-navigation.json @@ -203,7 +203,6 @@ "zh-CN/tools/slash-commands", "zh-CN/tools/skills", "zh-CN/tools/skills-config", - "zh-CN/tools/clawhub", "zh-CN/tools/plugin" ] }, diff --git a/docs/automation/taskflow.md b/docs/automation/taskflow.md index db9c6390e..76e75376a 100644 --- a/docs/automation/taskflow.md +++ b/docs/automation/taskflow.md @@ -90,7 +90,7 @@ Recommended data provenance fields for every collected item: Have the workflow reject or mark stale items before summarization. The LLM step should receive only structured JSON and should be asked to preserve `sourceUrl`, `retrievedAt`, and `asOf` in its output. Use [LLM Task](/tools/llm-task) when you need a schema-validated model step inside the workflow. -For reusable team or community workflows, package the CLI, `.lobster` files, and any setup notes as a skill or plugin and publish it through [ClawHub](/tools/clawhub). Keep workflow-specific guardrails in that package unless the plugin API is missing a needed generic capability. +For reusable team or community workflows, package the CLI, `.lobster` files, and any setup notes as a skill or plugin and publish it through [ClawHub](/clawhub). Keep workflow-specific guardrails in that package unless the plugin API is missing a needed generic capability. ## Sync modes diff --git a/docs/clawhub/acceptable-usage.md b/docs/clawhub/acceptable-usage.md new file mode 100644 index 000000000..57051d10f --- /dev/null +++ b/docs/clawhub/acceptable-usage.md @@ -0,0 +1,68 @@ +--- +summary: "Marketplace policy: what ClawHub allows and what it will not host." +read_when: + - Reviewing uploads for abuse or policy violations + - Writing moderation docs or reviewer runbooks + - Deciding whether a skill should be hidden or a user banned +--- + +# Acceptable Usage + +This page describes the kinds of skills and content ClawHub is okay with, and the abuse workflows it will not host. + +These rules are intentionally practical. We care most about end-to-end abuse workflows, not just isolated keywords. If a skill is built to evade defenses, abuse platforms, scam people, invade privacy, or enable non-consensual behavior, it does not belong on ClawHub. + +## Recent patterns we are explicitly okay with + +- Frontend and design-system work that uses real components, semantic tokens, accessible states, and tested user flows. +- shadcn/ui composition that uses installed source components, project aliases, and documented variants instead of one-off markup. +- UI5 JavaScript-to-TypeScript conversion that preserves comments, uses concrete UI5 types, and keeps generated control interfaces reviewable. +- Defensive security review, moderation tooling, and abuse-detection prompts that show evidence and keep human approval boundaries clear. +- Consent-based workflow automation for personal or team accounts with explicit credentials, transparent setup, and dry-run or preview modes. +- Documentation, migration runbooks, developer utilities, and test fixtures scoped to the software they support. + +## Not okay + +- Security-bypass or unauthorized-access workflows. + - Examples: auth bypass, account takeover, CAPTCHA bypass, Cloudflare or anti-bot evasion, rate-limit bypass, stealth scraping designed to defeat protections, live call or agent takeover, reusable session theft, auto-approving pairing flows for unapproved users. + +- Platform abuse and ban evasion. + - Examples: stealth accounts after bans, account warming/farming, fake engagement, karma or follower cultivation, multi-account automation, mass posting, spam bots, marketplace or social automation built to avoid detection. + +- Fraud, scams, and deceptive financial workflows. + - Examples: fake certificates, fake invoices, deceptive payment flows, scam outreach, fake social proof, tools that enable spending or charging without clear human approval and transparent controls, or synthetic-identity workflows built to create accounts for fraud. + +- Privacy-invasive scraping, enrichment, or surveillance. + - Examples: scraping contact details at scale for spam, doxxing, stalking, lead extraction paired with unsolicited outreach, covert monitoring, face search or biometric matching used without clear consent, or buying, publishing, downloading, or operationalizing leaked data or breach dumps. + +- Non-consensual impersonation or deceptive identity manipulation. + - Examples: face swap, digital twins, fake personas, cloned influencers, or other identity-manipulation tooling used to impersonate or mislead. + +- Explicit sexual content and safety-disabled adult generation. + - Examples: NSFW image/video/content generation, adult-content wrappers around third-party APIs, or skills whose primary purpose is explicit sexual content. + +- Hidden, unsafe, or misleading execution requirements. + - Examples: obfuscated install commands, `curl | sh`, undeclared secret requirements, undeclared private-key use, remote `npx @latest` execution without clear reviewability, misleading metadata that hides what the skill really needs to run. + +## Recent patterns we are explicitly not okay with + +- “Create stealth seller accounts after marketplace bans.” +- “Modify Telegram pairing so unapproved users automatically receive pairing codes.” +- “Cultivate Reddit/Twitter accounts with undetectable automation.” +- “Generate professional certificates or invoices for arbitrary use.” +- “Generate NSFW content with safety checks disabled.” +- “Scrape leads, enrich contacts, and launch cold outreach at scale.” +- “Buy, publish, or download leaked data or breach dumps.” +- “Bulk-create email or social accounts with synthetic identities or CAPTCHA solving.” + +## Notes for reviewers + +- Context matters. The same topic can be legitimate in a narrow defensive or consent-based setting and unacceptable when packaged as an abuse workflow. +- We should bias toward action when a skill is clearly optimized for evasion, deception, or non-consensual use. +- Repeated uploads in these categories are grounds for hiding content and banning the account. + +## Enforcement + +- We may hide, remove, or hard-delete violating skills. +- We may revoke tokens, soft-delete associated content, and ban repeat or severe offenders. +- We do not guarantee warning-first enforcement for obvious abuse. diff --git a/docs/clawhub/api.md b/docs/clawhub/api.md new file mode 100644 index 000000000..6ccec2cee --- /dev/null +++ b/docs/clawhub/api.md @@ -0,0 +1,118 @@ +--- +summary: "Public REST API (v1) overview and conventions." +read_when: + - Building API clients + - Adding endpoints or schemas +--- + +# API v1 + +Base: `https://clawhub.ai` + +OpenAPI: `/api/v1/openapi.json` + +## Public catalog reuse + +You can build a third-party catalog, directory, or search surface on top of ClawHub's public read APIs. Public skill metadata and skill files are published under ClawHub's skill license rules, while the API itself is rate-limited and should be consumed responsibly. + +Guidelines: + +- Use public read endpoints such as `GET /api/v1/skills`, `GET /api/v1/search`, and `GET /api/v1/skills/{slug}` for catalog listings. +- Cache responses and respect `429`, `Retry-After`, and rate-limit headers instead of polling aggressively. +- Link back to the canonical ClawHub skill URL when displaying listings so users can inspect the source registry record. +- Use canonical page URLs in the form `https://clawhub.ai//`. +- Do not imply that ClawHub endorses, verifies, or operates the third-party site. +- Do not mirror hidden, private, or moderation-blocked content by bypassing public API filters or auth boundaries. + +## Auth + +- Public read: no token required. +- Write + account: `Authorization: Bearer clh_...`. + +## Rate limits + +Auth-aware enforcement: + +- Anonymous requests: per IP. +- Authenticated requests (valid Bearer token): per user bucket. +- Missing/invalid token falls back to IP enforcement. + +- Read: 600/min per IP, 2400/min per key +- Write: 45/min per IP, 180/min per key + +Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After` (on 429). + +Semantics: + +- `X-RateLimit-Reset`: Unix epoch seconds (absolute reset time) +- `RateLimit-Reset`: delay seconds until reset +- `Retry-After`: delay seconds to wait on `429` + +Example `429`: + +```http +HTTP/2 429 +x-ratelimit-limit: 20 +x-ratelimit-remaining: 0 +x-ratelimit-reset: 1771404540 +ratelimit-limit: 20 +ratelimit-remaining: 0 +ratelimit-reset: 34 +retry-after: 34 +``` + +Client handling: + +- Prefer `Retry-After` when present. +- Otherwise use `RateLimit-Reset` or derive delay from `X-RateLimit-Reset`. +- Add jitter to retries. + +## Endpoints + +Public read: + +- `GET /api/v1/search?q=...` + - Optional filters: `highlightedOnly=true`, `nonSuspiciousOnly=true` + - Legacy alias: `nonSuspicious=true` +- `GET /api/v1/skills?limit=&cursor=&sort=` + - `sort`: `updated` (default), `createdAt` (`newest`), `downloads`, `stars` (`rating`), `installsCurrent` (`installs`), `installsAllTime`, `trending` + - `cursor` applies to non-`trending` sorts + - Optional filter: `nonSuspiciousOnly=true` + - Legacy alias: `nonSuspicious=true` + - With `nonSuspiciousOnly=true`, cursor-based pages may contain fewer than `limit` items; use `nextCursor` to continue. +- `GET /api/v1/skills/{slug}` +- `GET /api/v1/skills/{slug}/moderation` +- `GET /api/v1/skills/{slug}/versions?limit=&cursor=` +- `GET /api/v1/skills/{slug}/versions/{version}` +- `GET /api/v1/skills/{slug}/scan?version=&tag=` +- `GET /api/v1/skills/{slug}/file?path=&version=&tag=` +- `GET /api/v1/resolve?slug=&hash=` +- `GET /api/v1/download?slug=&version=&tag=` +- `GET /api/v1/packages/{name}/versions/{version}/artifact` +- `GET /api/v1/packages/{name}/versions/{version}/artifact/download` +- `GET /api/npm/{package}` +- `GET /api/npm/{package}/-/{tarball}.tgz` + +Auth required: + +- `POST /api/v1/skills` (publish, multipart preferred) +- `DELETE /api/v1/skills/{slug}` +- `DELETE /api/v1/packages/{name}` +- `POST /api/v1/skills/{slug}/undelete` +- `POST /api/v1/skills/{slug}/rename` +- `POST /api/v1/skills/{slug}/merge` +- `POST /api/v1/skills/{slug}/transfer` +- `POST /api/v1/skills/{slug}/transfer/accept` +- `POST /api/v1/skills/{slug}/transfer/reject` +- `POST /api/v1/skills/{slug}/transfer/cancel` +- `GET /api/v1/transfers/incoming` +- `GET /api/v1/transfers/outgoing` +- `GET /api/v1/whoami` + +Admin only: + +- `POST /api/v1/users/reserve` reserves root slugs and private no-release package placeholders for an owner handle. + +## Legacy + +Legacy `/api/*` and `/api/cli/*` still available. See `DEPRECATIONS.md`. diff --git a/docs/clawhub/auth.md b/docs/clawhub/auth.md new file mode 100644 index 000000000..868873bee --- /dev/null +++ b/docs/clawhub/auth.md @@ -0,0 +1,73 @@ +--- +summary: "ClawHub sign-in, API tokens, CLI login, token storage, and revocation." +read_when: + - Signing in to ClawHub + - Using the ClawHub CLI + - Debugging 401s +--- + +# Auth + +ClawHub uses GitHub for web sign-in. The CLI uses ClawHub API tokens created +through that signed-in account. + +## Web sign-in + +Use GitHub to sign in at [clawhub.ai](https://clawhub.ai). + +Deleted, banned, or disabled accounts cannot complete normal ClawHub sign-in. +If sign-in returns you to a logged-out state, your account may not be in good +standing. + +## CLI login + +The default CLI login flow opens your browser: + +```bash +clawhub login +clawhub whoami +``` + +What happens: + +1. The CLI starts a temporary callback server on `127.0.0.1`. +2. Your browser opens the ClawHub sign-in page. +3. After GitHub sign-in, ClawHub creates an API token. +4. The browser redirects back to the local callback. +5. The CLI stores the token in your ClawHub config file. + +If your browser cannot reach the local callback because of firewall, VPN, or +proxy rules, use the headless token flow. + +## Headless login + +Create a token in the ClawHub web UI, then pass it to the CLI: + +```bash +clawhub login --token clh_... +``` + +Use this flow for servers, CI jobs, or terminal-only environments. + +## Token storage + +Default config paths: + +- macOS: `~/Library/Application Support/clawhub/config.json` +- Linux/XDG: `$XDG_CONFIG_HOME/clawhub/config.json` or `~/.config/clawhub/config.json` +- Windows: `%APPDATA%\\clawhub\\config.json` + +Override the path with: + +```bash +export CLAWHUB_CONFIG_PATH=/path/to/config.json +``` + +## Revocation + +You can revoke API tokens in the ClawHub web UI. + +Revoked, invalid, or missing tokens return `401 Unauthorized`. Sign in again +with `clawhub login` or provide a fresh token with `clawhub login --token`. + +Deleted, banned, or disabled accounts cannot continue using existing API tokens. diff --git a/docs/clawhub/cli.md b/docs/clawhub/cli.md new file mode 100644 index 000000000..6cfc83b48 --- /dev/null +++ b/docs/clawhub/cli.md @@ -0,0 +1,558 @@ +--- +summary: "CLI reference: commands, flags, config, lockfile, sync behavior." +read_when: + - Using the ClawHub CLI + - Debugging install, update, publish, or sync +--- + +# CLI + +CLI package: `clawhub`, bin: `clawhub`. + +Install it globally with npm or pnpm: + +```bash +npm i -g clawhub +# or +pnpm add -g clawhub +``` + +Then verify it: + +```bash +clawhub --help +clawhub login +clawhub whoami +``` + +## Global flags + +- `--workdir `: working directory (default: cwd; falls back to Clawdbot workspace if configured) +- `--dir `: install dir under workdir (default: `skills`) +- `--site `: base URL for browser login (default: `https://clawhub.ai`) +- `--registry `: API base URL (default: discovered, else `https://clawhub.ai`) +- `--no-input`: disable prompts + +Env equivalents: + +- `CLAWHUB_SITE` (legacy `CLAWDHUB_SITE`) +- `CLAWHUB_REGISTRY` (legacy `CLAWDHUB_REGISTRY`) +- `CLAWHUB_WORKDIR` (legacy `CLAWDHUB_WORKDIR`) + +### HTTP proxy + +The CLI respects standard HTTP proxy environment variables for systems behind +corporate proxies or restricted networks: + +- `HTTPS_PROXY` / `https_proxy` +- `HTTP_PROXY` / `http_proxy` +- `NO_PROXY` / `no_proxy` + +When any of these variables is set, the CLI routes outbound requests through +the specified proxy. `HTTPS_PROXY` is used for HTTPS requests, `HTTP_PROXY` +for plain HTTP. `NO_PROXY` / `no_proxy` is respected to bypass the proxy for +specific hosts or domains. + +This is required on systems where direct outbound connections are blocked +(e.g. Docker containers, Hetzner VPS with proxy-only internet, corporate +firewalls). + +Example: + +```bash +export HTTPS_PROXY=http://proxy.example.com:3128 +export NO_PROXY=localhost,127.0.0.1 +clawhub search "my query" +``` + +When no proxy variable is set, behavior is unchanged (direct connections). + +## Config file + +Stores your API token + cached registry URL. + +- macOS: `~/Library/Application Support/clawhub/config.json` +- Linux/XDG: `$XDG_CONFIG_HOME/clawhub/config.json` or `~/.config/clawhub/config.json` +- Windows: `%APPDATA%\\clawhub\\config.json` +- Legacy fallback: if `clawhub/config.json` does not exist yet but `clawdhub/config.json` does, the CLI reuses the legacy path +- override: `CLAWHUB_CONFIG_PATH` (legacy `CLAWDHUB_CONFIG_PATH`) + +## Commands + +### `login` / `auth login` + +- Default: opens browser to `/cli/auth` and completes via loopback callback. +- Headless: `clawhub login --token clh_...` + +### `whoami` + +- Verifies the stored token via `/api/v1/whoami`. + +### `star ` / `unstar ` + +- Adds/removes a skill from your highlights. +- Calls `POST /api/v1/stars/` and `DELETE /api/v1/stars/`. +- `--yes` skips confirmation. + +### `search ` + +- Calls `/api/v1/search?q=...`. +- Search favors exact slug/name token matches before download popularity. A standalone slug token such as `map` matches `personal-map` more strongly than the substring inside `amap`. +- Downloads are a small popularity prior, not a guarantee of top placement. +- If a skill should appear but does not, run `clawhub inspect ` while logged in to check owner-visible moderation diagnostics before renaming metadata. + +### `explore` + +- Lists newest skills via `/api/v1/skills?limit=...&sort=createdAt` (sorted by `createdAt` desc). +- Flags: + - `--limit ` (1-200, default: 25) + - `--sort newest|updated|downloads|rating|installs|installsAllTime|trending` (default: newest) + - `--json` (machine-readable output) +- Output: ` v ` (summary truncated to 50 chars). + +### `inspect ` + +- Fetches skill metadata and version files without installing. +- `--version `: inspect a specific version (default: latest). +- `--tag `: inspect a tagged version (e.g. `latest`). +- `--versions`: list version history (first page). +- `--limit `: max versions to list (1-200). +- `--files`: list files for the selected version. +- `--file `: fetch raw file content (text files only; 200KB limit). +- `--json`: machine-readable output. + +### `install ` + +- Resolves latest version via `/api/v1/skills/`. +- Downloads zip via `/api/v1/download`. +- Extracts into `//`. +- Writes: + - `/.clawhub/lock.json` (legacy `.clawdhub`) + - `/.clawhub/origin.json` (legacy `.clawdhub`) + +### `uninstall ` + +- Removes `//` and deletes the lockfile entry. +- Interactive: asks for confirmation. +- Non-interactive (`--no-input`): requires `--yes`. + +### `list` + +- Reads `/.clawhub/lock.json` (legacy `.clawdhub`). + +### `update [slug]` / `update --all` + +- Computes fingerprint from local files. +- If fingerprint matches a known version: no prompt. +- If fingerprint does not match: + - refuses by default + - overwrites with `--force` (or prompt, if interactive) + +### `skill publish ` + +- Publishes via `POST /api/v1/skills` (multipart). +- Requires semver: `--version 1.2.3`. +- `--owner ` publishes under an org/user publisher handle when the + actor has publisher access. +- Publishing a skill means it is released under `MIT-0` on ClawHub. +- Published skills are free to use, modify, and redistribute without attribution. +- ClawHub does not support paid skills or per-skill pricing. +- Legacy alias: `publish `. + +### `delete ` + +- Soft-delete a skill (owner, moderator, or admin). +- Calls `DELETE /api/v1/skills/{slug}`. +- `--reason ` records a moderation note on the skill and audit log. +- `--note ` is an alias for `--reason`. +- `--yes` skips confirmation. + +### `undelete ` + +- Restore a hidden skill (owner, moderator, or admin). +- Calls `POST /api/v1/skills/{slug}/undelete`. +- `--reason ` records a moderation note on the skill and audit log. +- `--note ` is an alias for `--reason`. +- `--yes` skips confirmation. + +### `hide ` + +- Hide a skill (owner, moderator, or admin). +- Alias for `delete`. + +### `unhide ` + +- Unhide a skill (owner, moderator, or admin). +- Alias for `undelete`. + +### `skill rename ` + +- Rename an owned skill and keep the previous slug as a redirect alias. +- Calls `POST /api/v1/skills/{slug}/rename`. +- `--yes` skips confirmation. + +### `skill merge ` + +- Merge one owned skill into another owned skill. +- The source slug stops listing publicly and becomes a redirect alias to the target. +- Calls `POST /api/v1/skills/{sourceSlug}/merge`. +- `--yes` skips confirmation. + +### `transfer` + +- Ownership transfer workflow. +- Subcommands: + - `transfer request [--message "..."] [--yes]` + - `transfer list [--outgoing]` + - `transfer accept [--yes]` + - `transfer reject [--yes]` + - `transfer cancel [--yes]` +- Endpoints: + - `POST /api/v1/skills/{slug}/transfer` + - `POST /api/v1/skills/{slug}/transfer/accept` + - `POST /api/v1/skills/{slug}/transfer/reject` + - `POST /api/v1/skills/{slug}/transfer/cancel` + - `GET /api/v1/transfers/incoming` + - `GET /api/v1/transfers/outgoing` + +### `package explore [query...]` + +- Browses or searches the unified package catalog via `GET /api/v1/packages` and `GET /api/v1/packages/search`. +- Use this for plugins and other package-family entries; top-level `search` remains the skill search surface. +- Flags: + - `--family skill|code-plugin|bundle-plugin` + - `--official` + - `--executes-code` + - `--target `, `--os `, `--arch `, `--libc ` + - `--requires-browser`, `--requires-desktop`, `--requires-native-deps` + - `--requires-external-service`, `--external-service ` + - `--binary `, `--os-permission ` + - `--artifact-kind legacy-zip|npm-pack` + - `--npm-mirror` + - `--limit ` (1-100, default: 25) + - `--json` + +Examples: + +```bash +clawhub package explore --family code-plugin +clawhub package explore --family code-plugin --os darwin --requires-desktop +clawhub package explore --family code-plugin --artifact-kind npm-pack +clawhub package explore --npm-mirror +clawhub package explore episodic-claw --family code-plugin +``` + +### `package inspect ` + +- Fetches package metadata without installing. +- Use this for plugin metadata, compatibility, verification, source, and version/file inspection. +- `--version `: inspect a specific version (default: latest). +- `--tag `: inspect a tagged version (e.g. `latest`). +- `--versions`: list version history (first page). +- `--limit `: max versions to list (1-100). +- `--files`: list files for the selected version. +- `--file `: fetch raw file content (text files only; 200KB limit). +- `--json`: machine-readable output. + +### `package download ` + +- Resolves a package version through + `GET /api/v1/packages/{name}/versions/{version}/artifact`. +- Downloads the artifact from the resolver's `downloadUrl`. +- Verifies ClawHub SHA-256 for all artifacts. +- For ClawPack npm-pack artifacts, also verifies npm `sha512` integrity, + npm shasum, and the tarball's `package.json` name/version. +- Legacy ZIP versions download through the legacy ZIP route. +- Flags: + - `--version `: download a specific version. + - `--tag `: download a tagged version (default: `latest`). + - `-o, --output `: output file or directory. + - `--force`: overwrite an existing output file. + - `--json`: machine-readable output. + +Examples: + +```bash +clawhub package download @openclaw/example-plugin --tag latest +clawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/ +``` + +### `package verify ` + +- Computes ClawHub SHA-256, npm `sha512` integrity, and npm shasum for a local + artifact. +- With `--package`, resolves expected metadata from ClawHub and compares the + local file against the published artifact metadata. +- With direct digest flags, verifies without a network lookup. +- Flags: + - `--package `: package name to resolve expected artifact metadata. + - `--version ` or `--tag `: expected package version. + - `--sha256 `: expected ClawHub SHA-256. + - `--npm-integrity `: expected npm integrity. + - `--npm-shasum `: expected npm shasum. + - `--json`: machine-readable output. + +Examples: + +```bash +clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3 +clawhub package verify ./example-plugin-1.2.3.tgz --sha256 +``` + +### `package delete ` + +- Soft-deletes a package and all releases. +- Requires the package owner, an org publisher owner/admin, platform moderator, + or platform admin. +- Flags: + - `--yes`: skip confirmation. + - `--json`: machine-readable output. + +Example: + +```bash +clawhub package delete @openclaw/example-plugin --yes +``` + +### `package report` + +- Authenticated command for reporting a package to moderators. +- Calls `POST /api/v1/packages/{name}/report`. +- Reports are package-level, optionally tied to a version, and become visible + to moderators for review. +- Reports do not auto-hide packages or block downloads by themselves. +- Flags: + - `--version `: optional package version to attach to the report. + - `--reason `: required report reason. + - `--json`: machine-readable output. + +Example: + +```bash +clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload" +``` + +### `package appeal` + +- Owner/publisher command for appealing release moderation. +- Calls `POST /api/v1/packages/{name}/appeal`. +- Appeals are accepted for quarantined, revoked, suspicious, or malicious + releases. +- Flags: + - `--version `: required package version. + - `--message `: required appeal message. + - `--json`: machine-readable output. + +Example: + +```bash +clawhub package appeal @openclaw/example-plugin --version 1.2.3 --message "linked source release explains the native binary" +``` + +### `package moderation-status` + +- Owner command for checking package moderation visibility. +- Calls `GET /api/v1/packages/{name}/moderation`. +- Shows current package scan state, open report count, latest release manual + moderation state, download block state, and moderation reasons. +- Flags: + - `--json`: machine-readable output. + +Example: + +```bash +clawhub package moderation-status @openclaw/example-plugin +``` + +### `package readiness ` + +- Checks whether a package is ready for future OpenClaw consumption. +- Calls `GET /api/v1/packages/{name}/readiness`. +- Reports blockers for official status, ClawPack availability, artifact digest, + source provenance, OpenClaw compatibility, host targets, environment metadata, + and scan state. +- Flags: + - `--json`: machine-readable output. + +Example: + +```bash +clawhub package readiness @openclaw/example-plugin +``` + +### `package migration-status ` + +- Shows operator-oriented migration status for a package that may replace a + bundled OpenClaw plugin. +- Calls the same computed readiness endpoint as `package readiness`, but prints + migration-focused status, latest version, official-package state, checks, and + blockers. +- Flags: + - `--json`: machine-readable output. + +Example: + +```bash +clawhub package migration-status @openclaw/example-plugin +``` + +### `package publish ` + +- Publishes a code plugin or bundle plugin via `POST /api/v1/packages`. +- `` accepts: + - Local folder path: `./my-plugin` + - Local ClawPack npm-pack tarball: `./my-plugin-1.2.3.tgz` + - GitHub repo: `owner/repo` or `owner/repo@ref` + - GitHub URL: `https://github.com/owner/repo` +- Metadata is auto-detected from `package.json`, `openclaw.plugin.json`, and + real OpenClaw bundle markers such as `.codex-plugin/plugin.json`, + `.claude-plugin/plugin.json`, and `.cursor-plugin/plugin.json`. +- `.tgz` sources are treated as ClawPack. The CLI uploads the exact npm-pack + bytes and uses the extracted `package/` contents only for validation and + metadata prefill. +- Code-plugin folders are packed into a ClawPack npm tarball before upload so + OpenClaw installs can verify the exact artifact. Bundle-plugin folders still + use the extracted-file publish path. +- For GitHub sources, source attribution is auto-populated from the repo, resolved commit, ref, and subpath. +- For local folders, source attribution is auto-detected from local git when the origin remote points at GitHub. +- External code plugins must declare `openclaw.compat.pluginApi` and + `openclaw.build.openclawVersion` explicitly. + Top-level `package.json.version` is not used as a fallback for publish validation. +- `--dry-run` previews the resolved publish payload without uploading. +- `--json` emits machine-readable output for CI. +- `--owner ` publishes under a user or org publisher handle when the actor has publisher access. +- Existing flags (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) still work as overrides. +- Private GitHub repos require `GITHUB_TOKEN`. + +#### Recommended local flow + +Use `--dry-run` first so you can confirm the resolved package metadata and +source attribution before creating a live release: + +```bash +npm pack +clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-run +clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin +``` + +#### Local folder flow + +For code plugins, folder publish builds and uploads a ClawPack artifact from +the package folder: + +```bash +clawhub package publish ./my-plugin --family code-plugin --dry-run +clawhub package publish ./my-plugin --family code-plugin +``` + +#### Minimal `package.json` for `--family code-plugin` + +External code plugins need a small amount of OpenClaw metadata in +`package.json`. This minimal manifest is enough for a successful publish: + +```json +{ + "name": "@myorg/openclaw-my-plugin", + "version": "1.0.0", + "type": "module", + "openclaw": { + "extensions": ["./index.ts"], + "compat": { + "pluginApi": ">=2026.3.24-beta.2" + }, + "build": { + "openclawVersion": "2026.3.24-beta.2" + } + } +} +``` + +Required fields: + +- `openclaw.compat.pluginApi` +- `openclaw.build.openclawVersion` + +Notes: + +- `package.json.version` is your package release version, but it is not used as + a fallback for OpenClaw compatibility/build validation. +- `openclaw.hostTargets` and `openclaw.environment` are optional metadata. + ClawHub may surface them when present, but they are not required for publish. +- `openclaw.compat.minGatewayVersion` and + `openclaw.build.pluginSdkVersion` are optional extras if you want to publish + more detailed compatibility metadata. +- If you are using an older `clawhub` CLI release, upgrade before publishing so + the local preflight checks run before upload. + +#### GitHub Actions + +ClawHub also ships an official reusable workflow at +[`/.github/workflows/package-publish.yml`](https://github.com/openclaw/clawhub/blob/86898837fb3aa9f7370d8b15a1c2bb50e7aa9793/.github/workflows/package-publish.yml) +for plugin repos. + +Typical caller setup: + +```yaml +name: Package Publish + +on: + pull_request: + workflow_dispatch: + push: + tags: + - "v*" + +jobs: + dry-run: + if: github.event_name == 'pull_request' + uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0 + with: + dry_run: true + + publish: + if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/') + permissions: + contents: read + id-token: write + uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0 + with: + dry_run: false + secrets: + clawhub_token: ${{ secrets.CLAWHUB_TOKEN }} +``` + +Notes: + +- The reusable workflow defaults `source` to the caller repo. +- For monorepos, pass `source_path` so the workflow publishes the plugin + package folder, for example `source_path: extensions/codex`. +- Pin the reusable workflow to a stable tag or full commit SHA. Do not run release publishing from `@main`. +- `pull_request` should use `dry_run: true` so CI stays non-polluting. +- Real publishes should be limited to trusted events such as `workflow_dispatch` or tag pushes. +- Trusted publishing without a secret only works on `workflow_dispatch`; tag pushes still need `clawhub_token`. +- Keep `clawhub_token` available for first publish, untrusted packages, or break-glass publishes. +- The workflow uploads the JSON result as an artifact and exposes it as workflow outputs. + +### `sync` + +- Scans for local skill folders and publishes new/changed ones. +- Roots can be any folder: a skills directory or a single skill folder with `SKILL.md`. +- Auto-adds Clawdbot skill roots when `~/.clawdbot/clawdbot.json` is present: + - `agent.workspace/skills` (main agent) + - `routing.agents.*.workspace/skills` (per-agent) + - `~/.clawdbot/skills` (shared) + - `skills.load.extraDirs` (shared packs) +- Respects `CLAWDBOT_CONFIG_PATH` / `CLAWDBOT_STATE_DIR` and `OPENCLAW_CONFIG_PATH` / `OPENCLAW_STATE_DIR`. +- Flags: + - `--root ` extra scan roots + - `--all` upload without prompting + - `--dry-run` show plan only + - `--bump patch|minor|major` (default: patch) + - `--changelog ` (non-interactive) + - `--tags a,b,c` (default: latest) + - `--concurrency ` (default: 4) + +Telemetry: + +- Sent during `sync` when logged in, unless `CLAWHUB_DISABLE_TELEMETRY=1` (legacy `CLAWDHUB_DISABLE_TELEMETRY=1`). +- Details: `docs/telemetry.md`. diff --git a/docs/clawhub/how-it-works.md b/docs/clawhub/how-it-works.md new file mode 100644 index 000000000..f117bb0a5 --- /dev/null +++ b/docs/clawhub/how-it-works.md @@ -0,0 +1,102 @@ +--- +summary: "How ClawHub listings, versions, installs, publishing, scans, and updates work." +read_when: + - Understanding listings, versions, installs, publishing, and moderation +--- + +# How ClawHub Works + +ClawHub is the registry layer for OpenClaw skills and plugins. It gives users a +place to discover packages, gives publishers a place to release versions, and +gives OpenClaw enough metadata to install and update those packages safely. + +## Registry records + +Each public listing is a registry record with: + +- an owner and slug or package name +- one or more published versions +- metadata, summary, files, and source attribution +- changelog and tag information such as `latest` +- download, install, star, and comment signals +- security scan and moderation status + +The listing page is the canonical place for users to inspect what a skill or +plugin claims to do before installing it. + +## Skills + +A skill is a versioned text bundle centered on `SKILL.md`. It can include +supporting files, examples, templates, and scripts. + +ClawHub reads the `SKILL.md` frontmatter to understand the skill name, +description, requirements, environment variables, and metadata. Accurate +metadata matters because it helps users decide whether to install the skill and +helps automated scans detect mismatches between declared and observed behavior. + +See [Skill format](/clawhub/skill-format). + +## Plugins + +Plugins are packaged OpenClaw extensions. ClawHub stores package metadata, +compatibility information, source links, artifacts, and version records. + +When OpenClaw installs a plugin from ClawHub, it checks advertised compatibility +metadata before installing. Package records can include API compatibility, +minimum gateway version, host targets, environment requirements, and artifact +digests. + +Use an explicit ClawHub install source when you want the registry to be the +source of truth: + +```bash +openclaw plugins install clawhub: +``` + +## Publishing + +Publishing creates a new immutable version record. Publishers use the `clawhub` +CLI for authenticated registry workflows: + +```bash +clawhub skill publish ./my-skill +clawhub package publish --family code-plugin --dry-run +clawhub package publish --family code-plugin +``` + +Use dry runs to preview the resolved payload before upload. Public pages then +surface the published metadata, files, source attribution, and scan status. + +## Installs and updates + +OpenClaw install commands use ClawHub as a package source: + +```bash +openclaw skills install +openclaw plugins install clawhub: +``` + +OpenClaw records install source metadata so updates can resolve the same +registry package later. The ClawHub CLI also supports direct skill install and +update workflows for users who want registry-managed skill folders outside a +full OpenClaw workspace. + +## Security state + +ClawHub is open to publishing, but releases are still subject to upload gates, +automated checks, user reports, and moderator action. + +Public pages show scan summaries when available. Content that is held, hidden, +or blocked may disappear from public search and install flows while remaining +visible to the owner for diagnostics or appeal. + +See [Security + moderation](/clawhub/security) and +[Acceptable usage](/clawhub/acceptable-usage). + +## API access + +ClawHub exposes public read APIs for discovery, search, package details, and +downloads. Third-party catalogs may use these APIs when they link back to the +canonical ClawHub listing, respect rate limits, and avoid implying endorsement. + +See [Public API](/clawhub/api) and [HTTP API](/clawhub/http-api). diff --git a/docs/clawhub/http-api.md b/docs/clawhub/http-api.md new file mode 100644 index 000000000..69ba038ae --- /dev/null +++ b/docs/clawhub/http-api.md @@ -0,0 +1,1361 @@ +--- +summary: "HTTP API reference (public + CLI endpoints + auth)." +read_when: + - Adding/changing endpoints + - Debugging CLI ↔ registry requests +--- + +# HTTP API + +Base URL: `https://clawhub.ai` (default). + +All v1 paths are under `/api/v1/...`. +Legacy `/api/...` and `/api/cli/...` remain for compatibility (see `DEPRECATIONS.md`). +OpenAPI: `/api/v1/openapi.json`. + +## Public catalog reuse + +Third-party directories may use the public read endpoints to list or search ClawHub skills. Please cache results, honor `429`/`Retry-After`, link users back to the canonical ClawHub listing (`https://clawhub.ai//`), and avoid implying ClawHub endorsement of the third-party site. Do not attempt to mirror hidden, private, or moderation-blocked content outside the public API surface. + +Web slug shortcuts resolve across registry families, but API clients should use +the canonical URLs returned by read endpoints instead of reconstructing route +precedence. + +## Rate limits + +Enforcement model: + +- Anonymous requests: enforced per IP. +- Authenticated requests (valid Bearer token): enforced per user bucket. +- If token is missing/invalid, behavior falls back to IP enforcement. +- Authenticated write endpoints should not return a bare `Unauthorized` when + the server knows the reason. Missing tokens, invalid/revoked tokens, and + deleted/banned/disabled accounts should each get actionable text so CLI + clients can tell users what blocked them. + +- Read: 600/min per IP, 2400/min per key +- Write: 45/min per IP, 180/min per key +- Download: 30/min per IP, 180/min per key (`/api/v1/download`) + +Headers: + +- Legacy compatibility: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` +- Standardized: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` +- On `429`: `Retry-After` + +Header semantics: + +- `X-RateLimit-Reset`: absolute Unix epoch seconds +- `RateLimit-Reset`: seconds until reset (delay) +- `Retry-After`: seconds to wait before retry (delay) on `429` + +Example `429` response: + +```http +HTTP/2 429 +content-type: text/plain; charset=utf-8 +x-ratelimit-limit: 20 +x-ratelimit-remaining: 0 +x-ratelimit-reset: 1771404540 +ratelimit-limit: 20 +ratelimit-remaining: 0 +ratelimit-reset: 34 +retry-after: 34 + +Rate limit exceeded +``` + +Client guidance: + +- If `Retry-After` exists, wait that many seconds before retry. +- Use jittered backoff to avoid synchronized retries. +- If `Retry-After` is missing, fallback to `RateLimit-Reset` (or compute from `X-RateLimit-Reset`). + +IP source: + +- Uses `cf-connecting-ip` (Cloudflare) for client IP by default. +- ClawHub uses trusted forwarding headers to identify client IPs at the edge. +- If no trusted client IP is available, anonymous download requests use an endpoint-scoped fallback bucket instead of one global `ip:unknown` bucket. Anonymous read/write requests still use the shared unknown bucket so missing-IP routing remains visible and conservative. + +## Public endpoints (no auth) + +### `GET /api/v1/search` + +Query params: + +- `q` (required): query string +- `limit` (optional): integer +- `highlightedOnly` (optional): `true` to filter to highlighted skills +- `nonSuspiciousOnly` (optional): `true` to hide suspicious (`flagged.suspicious`) skills +- `nonSuspicious` (optional): legacy alias for `nonSuspiciousOnly` + +Response: + +```json +{ + "results": [ + { + "score": 0.123, + "slug": "gifgrep", + "displayName": "GifGrep", + "summary": "…", + "version": "1.2.3", + "updatedAt": 1730000000000 + } + ] +} +``` + +Notes: + +- Results are returned in relevance order (embedding similarity + exact slug/name token boosts + popularity prior from downloads). +- Relevance is stronger than popularity. A precise slug or display-name token match can outrank a looser match with many more downloads. +- ASCII text is tokenized on word and punctuation boundaries. For example, `personal-map` contains a standalone `map` token, while `amap-jsapi-skill` contains `amap`, `jsapi`, and `skill`; searching for `map` therefore gives `personal-map` a stronger lexical match than `amap-jsapi-skill`. +- Downloads are used as a small log-scaled prior and tie-breaker, not as the primary ranking signal. High-download skills can rank lower when the query text is a weaker match. +- Suspicious or hidden moderation state can remove a skill from public search depending on caller filters and current moderation status. + +Publisher discoverability guidance: + +- Put the terms users will literally search for in the display name, summary, and tags. Use a standalone slug token only when it is also a stable identity you want to keep. +- Do not rename a slug just to chase one query unless the new slug is a better long-term canonical name. Old slugs become redirect aliases, but the canonical URL, displayed slug, and future search digests use the new slug. +- Rename aliases preserve resolution for old URLs and installs that resolve through the registry, but search ranking is based on the canonical skill metadata after the rename has indexed. Existing stats stay with the skill. +- If a skill is unexpectedly invisible, check moderation state first with `clawhub inspect ` while logged in before changing ranking-related metadata. + +### `GET /api/v1/skills` + +Query params: + +- `limit` (optional): integer (1–200) +- `cursor` (optional): pagination cursor for any non-`trending` sort +- `sort` (optional): `updated` (default), `createdAt` (alias: `newest`), `downloads`, `stars` (alias: `rating`), `installsCurrent` (alias: `installs`), `installsAllTime`, `trending` +- `nonSuspiciousOnly` (optional): `true` to hide suspicious (`flagged.suspicious`) skills +- `nonSuspicious` (optional): legacy alias for `nonSuspiciousOnly` + +Notes: + +- `trending` ranks by installs in the last 7 days (telemetry-based). +- `createdAt` is stable for new-skill crawls; `updated` changes when existing skills are republished. +- When `nonSuspiciousOnly=true`, cursor-based sorts may return fewer than `limit` items on a page because suspicious skills are filtered after page retrieval. +- Use `nextCursor` to continue pagination when present. A short page does not by itself mean end-of-results. + +Response: + +```json +{ + "items": [ + { + "slug": "gifgrep", + "displayName": "GifGrep", + "summary": "…", + "tags": { "latest": "1.2.3" }, + "stats": {}, + "createdAt": 0, + "updatedAt": 0, + "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" }, + "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] } + } + ], + "nextCursor": null +} +``` + +### `GET /api/v1/skills/{slug}` + +Response: + +```json +{ + "skill": { + "slug": "gifgrep", + "displayName": "GifGrep", + "summary": "…", + "tags": { "latest": "1.2.3" }, + "stats": {}, + "createdAt": 0, + "updatedAt": 0 + }, + "latestVersion": { "version": "1.2.3", "createdAt": 0, "changelog": "…" }, + "metadata": { "os": ["macos"], "systems": ["aarch64-darwin"] }, + "owner": { "handle": "steipete", "displayName": "Peter", "image": null }, + "moderation": { + "isSuspicious": false, + "isMalwareBlocked": false, + "verdict": "clean", + "reasonCodes": [], + "summary": null, + "engineVersion": "v2.0.0", + "updatedAt": 0 + } +} +``` + +Notes: + +- Old slugs created by owner rename/merge flows resolve to the canonical skill. +- `metadata.os`: OS restrictions declared in skill frontmatter (e.g. `["macos"]`, `["linux"]`). `null` if not declared. +- `metadata.systems`: Nix system targets (e.g. `["aarch64-darwin", "x86_64-linux"]`). `null` if not declared. +- `metadata` is `null` if the skill has no platform metadata. +- `moderation` is included only when the skill is flagged or the owner is viewing it. + +### `GET /api/v1/skills/{slug}/moderation` + +Returns structured moderation state. + +Response: + +```json +{ + "moderation": { + "isSuspicious": true, + "isMalwareBlocked": false, + "verdict": "suspicious", + "reasonCodes": ["suspicious.dynamic_code_execution"], + "summary": "Detected: suspicious.dynamic_code_execution", + "engineVersion": "v2.0.0", + "updatedAt": 0, + "legacyReason": null, + "evidence": [ + { + "code": "suspicious.dynamic_code_execution", + "severity": "critical", + "file": "index.ts", + "line": 3, + "message": "Dynamic code execution detected.", + "evidence": "" + } + ] + } +} +``` + +Notes: + +- Owners and moderators can access moderation details for hidden skills. +- Public callers only get `200` for already-flagged visible skills. +- Evidence is redacted for public callers and only includes raw snippets for owners/moderators. + +### `POST /api/v1/skills/{slug}/report` + +Report a skill for moderator review. Reports are skill-level, optionally linked +to a version, and feed the skill report queue. + +Auth: + +- Requires an API token. + +Request: + +```json +{ "reason": "Suspicious install step", "version": "1.2.3" } +``` + +Response: + +```json +{ + "ok": true, + "reported": true, + "alreadyReported": false, + "reportId": "skillReports:...", + "skillId": "skills:...", + "reportCount": 1 +} +``` + +### `POST /api/v1/skills/{slug}/appeal` + +Skill owner/publisher endpoint for appealing moderation on a skill. + +Auth: + +- Requires an API token for the skill owner or publisher member. + +Request: + +```json +{ "version": "1.2.3", "message": "The flagged command is documented setup." } +``` + +Appeals are accepted for hidden, removed, suspicious, malicious, or +scanner-flagged skill outcomes. ClawHub keeps one open appeal per skill. + +Response: + +```json +{ + "ok": true, + "submitted": true, + "alreadyOpen": false, + "appealId": "skillAppeals:...", + "skillId": "skills:...", + "status": "open" +} +``` + +### `GET /api/v1/skills/-/reports` + +Moderator/admin endpoint for skill report intake. + +Query params: + +- `status` (optional): `open` (default), `confirmed`, `dismissed`, or `all` +- `limit` (optional): integer (1-200) +- `cursor` (optional): pagination cursor + +Response: + +```json +{ + "items": [ + { + "reportId": "skillReports:...", + "skillId": "skills:...", + "skillVersionId": "skillVersions:...", + "slug": "gifgrep", + "displayName": "GifGrep", + "version": "1.2.3", + "reason": "Suspicious install step", + "status": "open", + "createdAt": 1730000000000, + "reporter": { + "userId": "users:...", + "handle": "reporter", + "displayName": "Reporter" + }, + "triagedAt": null, + "triagedBy": null, + "triageNote": null + } + ], + "nextCursor": null, + "done": true +} +``` + +### `POST /api/v1/skills/-/reports/{reportId}/triage` + +Moderator/admin endpoint for resolving or reopening skill reports. + +Request: + +```json +{ "status": "confirmed", "note": "Reviewed and hid affected version.", "finalAction": "hide" } +``` + +`note` is required for `confirmed` and `dismissed`; it may be omitted when +setting `status` back to `open`. Pass `finalAction: "hide"` with a triaged +report to hide the skill in the same auditable workflow. + +### `GET /api/v1/skills/-/appeals` + +Moderator/admin endpoint for skill appeal intake. + +Query params: + +- `status` (optional): `open` (default), `accepted`, `rejected`, or `all` +- `limit` (optional): integer (1-200) +- `cursor` (optional): pagination cursor + +### `POST /api/v1/skills/-/appeals/{appealId}/resolve` + +Moderator/admin endpoint for accepting, rejecting, or reopening a skill appeal. +`note` is required for `accepted` and `rejected`; it may be omitted when setting +`status` back to `open`. Pass `finalAction: "restore"` with an accepted appeal +to make the skill available again. + +### `GET /api/v1/skills/{slug}/versions` + +Query params: + +- `limit` (optional): integer +- `cursor` (optional): pagination cursor + +### `GET /api/v1/skills/{slug}/versions/{version}` + +Returns version metadata + files list. + +- `version.security` includes normalized scan verification status and scanner details + (VirusTotal + LLM), when available. + +### `GET /api/v1/skills/{slug}/scan` + +Returns security scan verification details for a skill version. + +Query params: + +- `version` (optional): specific version string. +- `tag` (optional): resolve a tagged version (for example `latest`). + +Notes: + +- If neither `version` nor `tag` is provided, uses the latest version. +- Includes normalized verification status plus scanner-specific details. +- `security.capabilityTags` includes deterministic capability/risk labels such as + `crypto`, `requires-wallet`, `can-make-purchases`, `can-sign-transactions`, + `requires-oauth-token`, and `posts-externally` when detected. +- `security.hasScanResult` is `true` only when a scanner produced a definitive verdict (`clean`, `suspicious`, or `malicious`). +- `moderation` is a current skill-level moderation snapshot derived from the latest version. +- When querying a historical version, check `moderation.matchesRequestedVersion` and `moderation.sourceVersion` before treating `moderation` and `security` as the same version context. + +### `GET /api/v1/skills/{slug}/file` + +Returns raw text content. + +Query params: + +- `path` (required) +- `version` (optional) +- `tag` (optional) + +Notes: + +- Defaults to latest version. +- File size limit: 200KB. + +### `GET /api/v1/packages` + +Unified catalog endpoint for: + +- skills +- code plugins +- bundle plugins + +Query params: + +- `limit` (optional): integer (1–100) +- `cursor` (optional): pagination cursor +- `family` (optional): `skill`, `code-plugin`, or `bundle-plugin` +- `channel` (optional): `official`, `community`, or `private` +- `isOfficial` (optional): `true` or `false` +- `executesCode` (optional): `true` or `false` +- `capabilityTag` (optional): capability filter for plugin packages +- `target` / `hostTarget` (optional): shorthand for `host:` +- `os`, `arch`, `libc` (optional): shorthand for host capability filters +- `requiresBrowser`, `requiresDesktop`, `requiresNativeDeps`, + `requiresExternalService`, `requiresBinary`, `requiresOsPermission` + (optional): `true`/`1` shorthand for environment requirement tags +- `externalService`, `binary`, `osPermission` (optional): shorthand for named + environment requirement tags +- `artifactKind` (optional): `legacy-zip` or `npm-pack` +- `npmMirror` (optional): `true`/`1` to show ClawPack-backed package versions + available through the npm mirror + +Notes: + +- `GET /api/v1/code-plugins` and `GET /api/v1/bundle-plugins` remain fixed-family aliases. +- Skill entries stay backed by the skill registry and can still be published only through `POST /api/v1/skills`. +- `POST /api/v1/packages` is still only for code-plugin and bundle-plugin releases. +- Anonymous callers only see public package channels. +- Authenticated callers can see private packages for publishers they belong to in list/search results. +- `channel=private` only returns packages the authenticated caller can read. + +### `GET /api/v1/packages/search` + +Unified catalog search across skills + plugin packages. + +Query params: + +- `q` (required): query string +- `limit` (optional): integer (1–100) +- `family` (optional): `skill`, `code-plugin`, or `bundle-plugin` +- `channel` (optional): `official`, `community`, or `private` +- `isOfficial` (optional): `true` or `false` +- `executesCode` (optional): `true` or `false` +- `capabilityTag` (optional): capability filter for plugin packages +- `target` / `hostTarget`, `os`, `arch`, `libc`, `requiresBrowser`, + `requiresDesktop`, `requiresNativeDeps`, `requiresExternalService`, + `requiresBinary`, `requiresOsPermission`, `externalService`, `binary`, and + `osPermission` are accepted as shorthands for common capability tags +- `artifactKind` (optional): `legacy-zip` or `npm-pack` +- `npmMirror` (optional): `true`/`1` to search ClawPack-backed package versions + available through the npm mirror + +Notes: + +- Anonymous callers only see public package channels. +- Authenticated callers can search private packages for publishers they belong to. +- `channel=private` only returns packages the authenticated caller can read. +- Artifact filters are backed by indexed capability tags: + `artifact:legacy-zip`, `artifact:npm-pack`, and `npm-mirror:available`. + +### `GET /api/v1/packages/{name}` + +Returns package detail metadata. + +Notes: + +- Skills can also resolve through this route in the unified catalog. +- Private packages return `404` unless the caller can read the owning publisher. + +### `DELETE /api/v1/packages/{name}` + +Soft-deletes a package and all releases. + +Notes: + +- Requires an API token for the package owner, an org publisher owner/admin, + platform moderator, or platform admin. + +### `GET /api/v1/packages/{name}/versions` + +Returns version history. + +Query params: + +- `limit` (optional): integer (1–100) +- `cursor` (optional): pagination cursor + +Notes: + +- Private packages return `404` unless the caller can read the owning publisher. + +### `GET /api/v1/packages/{name}/versions/{version}` + +Returns one package version, including file metadata, compatibility, +capabilities, verification, artifact metadata, and scan data. + +Notes: + +- `version.artifact.kind` is `legacy-zip` for old-world package archives or + `npm-pack` for ClawPack-backed releases. +- ClawPack releases include npm-compatible `npmIntegrity`, `npmShasum`, and + `npmTarballName` fields. +- `version.sha256hash`, `version.vtAnalysis`, `version.llmAnalysis`, and `version.staticScan` are included when scan data exists. +- Private packages return `404` unless the caller can read the owning publisher. + +### `GET /api/v1/packages/{name}/versions/{version}/artifact` + +Returns the explicit artifact resolver metadata for a package version. + +Notes: + +- Legacy package versions return a `legacy-zip` artifact and a legacy ZIP + `downloadUrl`. +- ClawPack versions return an `npm-pack` artifact, npm integrity fields, a + `tarballUrl`, and the legacy ZIP compatibility URL. +- This is the OpenClaw resolver surface; it avoids guessing archive format from + a shared URL. + +### `GET /api/v1/packages/{name}/versions/{version}/artifact/download` + +Downloads the version artifact through the explicit resolver path. + +Notes: + +- ClawPack versions stream the exact uploaded npm-pack `.tgz` bytes. +- Legacy ZIP versions redirect to `/api/v1/packages/{name}/download?version=`. +- Uses the download rate bucket. + +### `GET /api/v1/packages/{name}/readiness` + +Returns computed readiness for future OpenClaw consumption. + +Readiness checks cover: + +- official channel status +- latest version availability +- ClawPack npm-pack artifact availability +- artifact digest +- source repo and commit provenance +- OpenClaw compatibility metadata +- host targets +- scan state + +Response: + +```json +{ + "package": { + "name": "@openclaw/example-plugin", + "displayName": "Example Plugin", + "family": "code-plugin", + "isOfficial": true, + "latestVersion": "1.2.3" + }, + "ready": false, + "checks": [ + { + "id": "clawpack", + "label": "ClawPack artifact", + "status": "fail", + "message": "Latest version is legacy ZIP-only." + } + ], + "blockers": ["clawpack"] +} +``` + +### `GET /api/v1/packages/migrations` + +Moderator endpoint for listing official OpenClaw plugin migration rows. + +Auth: + +- Requires an API token for a moderator or admin user. + +Query params: + +- `phase` (optional): `planned`, `published`, `clawpack-ready`, + `legacy-zip-only`, `metadata-ready`, `blocked`, `ready-for-openclaw`, or + `all` (default). +- `limit` (optional): integer (1-100) +- `cursor` (optional): pagination cursor + +Response: + +```json +{ + "items": [ + { + "migrationId": "officialPluginMigrations:...", + "bundledPluginId": "core.search", + "packageName": "@openclaw/search-plugin", + "packageId": "packages:...", + "owner": "platform", + "sourceRepo": "openclaw/openclaw", + "sourcePath": "plugins/search", + "sourceCommit": "abc123", + "phase": "blocked", + "blockers": ["missing ClawPack"], + "hostTargetsComplete": true, + "scanClean": false, + "moderationApproved": false, + "runtimeBundlesReady": false, + "notes": null, + "createdAt": 1760000000000, + "updatedAt": 1760000000000 + } + ], + "nextCursor": null, + "done": true +} +``` + +### `POST /api/v1/packages/migrations` + +Admin endpoint for creating or updating an official plugin migration row. + +Auth: + +- Requires an API token for an admin user. + +Request body: + +```json +{ + "bundledPluginId": "core.search", + "packageName": "@openclaw/search-plugin", + "owner": "platform", + "sourceRepo": "openclaw/openclaw", + "sourcePath": "plugins/search", + "sourceCommit": "abc123", + "phase": "blocked", + "blockers": ["missing ClawPack"], + "hostTargetsComplete": true, + "scanClean": false, + "moderationApproved": false, + "runtimeBundlesReady": false, + "notes": "waiting on publisher upload" +} +``` + +Notes: + +- `bundledPluginId` is normalized to lowercase and is the stable upsert key. +- `packageName` is npm-name normalized; the package can be missing for planned + migrations. +- This tracks migration readiness only. It does not mutate OpenClaw or generate + ClawPacks. + +### `GET /api/v1/packages/moderation/queue` + +Moderator/admin endpoint for package release review queues. + +Auth: + +- Requires an API token for a moderator or admin user. + +Query params: + +- `status` (optional): `open` (default), `blocked`, `manual`, or `all` +- `limit` (optional): integer (1-100) +- `cursor` (optional): pagination cursor + +Status meanings: + +- `open`: suspicious, malicious, pending, quarantined, revoked, or reported releases. +- `blocked`: quarantined, revoked, or malicious releases. +- `manual`: any release with a manual moderation override. +- `all`: any release with a manual override, non-clean scan state, or package report. + +Response: + +```json +{ + "items": [ + { + "packageId": "packages:...", + "releaseId": "packageReleases:...", + "name": "@openclaw/example-plugin", + "displayName": "Example Plugin", + "family": "code-plugin", + "channel": "community", + "isOfficial": false, + "version": "1.2.3", + "createdAt": 1730000000000, + "artifactKind": "npm-pack", + "scanStatus": "malicious", + "moderationState": "quarantined", + "moderationReason": "manual review", + "sourceRepo": "openclaw/example-plugin", + "sourceCommit": "abc123", + "reportCount": 2, + "lastReportedAt": 1730000001000, + "reasons": ["manual:quarantined", "scan:malicious", "reports:2"] + } + ], + "nextCursor": null, + "done": true +} +``` + +### `POST /api/v1/packages/{name}/report` + +Report a package for moderator review. Reports are package-level, optionally +linked to a version. They feed the moderation queue but do not auto-hide or +block downloads by themselves; moderators should use release moderation to +approve, quarantine, or revoke artifacts. + +Auth: + +- Requires an API token. + +Request: + +```json +{ "reason": "Suspicious native binary", "version": "1.2.3" } +``` + +Response: + +```json +{ + "ok": true, + "reported": true, + "alreadyReported": false, + "packageId": "packages:...", + "releaseId": "packageReleases:...", + "reportCount": 1 +} +``` + +### `POST /api/v1/packages/{name}/appeal` + +Package owner/publisher endpoint for appealing moderation on a release. + +Auth: + +- Requires an API token for the package owner or publisher member. + +Request: + +```json +{ + "version": "1.2.3", + "message": "The native binary is signed and matches the linked source release." +} +``` + +Appeals are accepted only for releases that are quarantined, revoked, +suspicious, or malicious. ClawHub keeps one open appeal per release. + +Response: + +```json +{ + "ok": true, + "submitted": true, + "alreadyOpen": false, + "appealId": "packageAppeals:...", + "packageId": "packages:...", + "releaseId": "packageReleases:...", + "status": "open" +} +``` + +### `GET /api/v1/packages/appeals` + +Moderator/admin endpoint for package appeal intake. + +Auth: + +- Requires an API token for a moderator or admin user. + +Query params: + +- `status` (optional): `open` (default), `accepted`, `rejected`, or `all` +- `limit` (optional): integer (1-100) +- `cursor` (optional): pagination cursor + +Response: + +```json +{ + "items": [ + { + "appealId": "packageAppeals:...", + "packageId": "packages:...", + "releaseId": "packageReleases:...", + "name": "@openclaw/example-plugin", + "displayName": "Example Plugin", + "family": "code-plugin", + "version": "1.2.3", + "message": "The native binary is signed.", + "status": "open", + "createdAt": 1730000000000, + "submitter": { + "userId": "users:...", + "handle": "publisher", + "displayName": "Publisher" + }, + "resolvedAt": null, + "resolvedBy": null, + "resolutionNote": null + } + ], + "nextCursor": null, + "done": true +} +``` + +### `POST /api/v1/packages/appeals/{appealId}/resolve` + +Moderator/admin endpoint for accepting, rejecting, or reopening an appeal. + +Request: + +```json +{ "status": "accepted", "note": "False positive confirmed.", "finalAction": "approve" } +``` + +`note` is required for `accepted` and `rejected`; it may be omitted when +setting `status` back to `open`. Pass `finalAction: "approve"` with an accepted +appeal to approve the affected release in the same auditable workflow. + +Response: + +```json +{ + "ok": true, + "appealId": "packageAppeals:...", + "packageId": "packages:...", + "releaseId": "packageReleases:...", + "status": "rejected" +} +``` + +### `GET /api/v1/packages/reports` + +Moderator/admin endpoint for package report intake. + +Auth: + +- Requires an API token for a moderator or admin user. + +Query params: + +- `status` (optional): `open` (default), `confirmed`, `dismissed`, or `all` +- `limit` (optional): integer (1-100) +- `cursor` (optional): pagination cursor + +Response: + +```json +{ + "items": [ + { + "reportId": "packageReports:...", + "packageId": "packages:...", + "releaseId": "packageReleases:...", + "name": "@openclaw/example-plugin", + "displayName": "Example Plugin", + "family": "code-plugin", + "version": "1.2.3", + "reason": "Suspicious native binary", + "status": "open", + "createdAt": 1730000000000, + "reporter": { + "userId": "users:...", + "handle": "reporter", + "displayName": "Reporter" + }, + "triagedAt": null, + "triagedBy": null, + "triageNote": null + } + ], + "nextCursor": null, + "done": true +} +``` + +### `GET /api/v1/packages/{name}/moderation` + +Owner/moderator endpoint for package moderation visibility. + +Auth: + +- Requires an API token for the package owner, publisher member, moderator, or + admin user. + +Response: + +```json +{ + "package": { + "packageId": "packages:...", + "name": "@openclaw/example-plugin", + "displayName": "Example Plugin", + "family": "code-plugin", + "channel": "community", + "isOfficial": false, + "reportCount": 2, + "lastReportedAt": 1730000001000, + "scanStatus": "malicious" + }, + "latestRelease": { + "releaseId": "packageReleases:...", + "version": "1.2.3", + "artifactKind": "npm-pack", + "scanStatus": "malicious", + "moderationState": "quarantined", + "moderationReason": "manual review", + "blockedFromDownload": true, + "reasons": ["manual:quarantined", "scan:malicious", "reports:2"], + "createdAt": 1730000000000 + } +} +``` + +### `POST /api/v1/packages/reports/{reportId}/triage` + +Moderator/admin endpoint for resolving or reopening package reports. + +Request: + +```json +{ + "status": "confirmed", + "note": "Reviewed and quarantined affected release.", + "finalAction": "quarantine" +} +``` + +`note` is required for `confirmed` and `dismissed`; it may be omitted when +setting `status` back to `open`. Pass `finalAction: "quarantine"` or +`finalAction: "revoke"` with a confirmed report to apply release moderation in the +same auditable workflow. + +Response: + +```json +{ + "ok": true, + "reportId": "packageReports:...", + "packageId": "packages:...", + "status": "confirmed", + "reportCount": 0 +} +``` + +### `POST /api/v1/packages/{name}/versions/{version}/moderation` + +Moderator/admin endpoint for package release review. + +Request: + +```json +{ "state": "quarantined", "reason": "Suspicious native payload." } +``` + +Supported states: + +- `approved`: manually reviewed and allowed. +- `quarantined`: blocked pending follow-up. +- `revoked`: blocked after a release was previously trusted. + +Quarantined and revoked releases return `403` from artifact download routes. +Every change writes an audit log entry. + +### `POST /api/v1/packages/backfill/artifacts` + +Admin-only maintenance endpoint for labeling older package releases with +explicit artifact-kind metadata. + +Request body: + +```json +{ + "cursor": null, + "batchSize": 100, + "dryRun": true +} +``` + +Response: + +```json +{ + "ok": true, + "scanned": 100, + "updated": 12, + "nextCursor": "cursor...", + "done": false, + "dryRun": true +} +``` + +Notes: + +- Defaults to dry-run. +- Releases without ClawPack storage are labeled `legacy-zip`. +- Existing ClawPack-backed rows missing `artifactKind` are repaired as + `npm-pack`. +- This does not generate ClawPacks or mutate artifact bytes. + +### `GET /api/v1/packages/{name}/file` + +Returns raw text content for a package file. + +Query params: + +- `path` (required) +- `version` (optional) +- `tag` (optional) + +Notes: + +- Defaults to the latest release. +- Uses the read rate bucket, not the download bucket. +- Binary files return `415`. +- File size limit: 200KB. +- Pending VirusTotal scans do not block reads; malicious releases may still be withheld elsewhere. +- Private packages return `404` unless the caller can read the owning publisher. + +### `GET /api/v1/packages/{name}/download` + +Downloads the legacy deterministic ZIP archive for a package release. + +Query params: + +- `version` (optional) +- `tag` (optional) + +Notes: + +- Defaults to the latest release. +- Skills redirect to `GET /api/v1/download`. +- Plugin/package archives are zip files with a `package/` root so old OpenClaw + clients keep working. +- This route stays ZIP-only. It does not stream ClawPack `.tgz` files. +- Responses include `ETag`, `Digest`, `X-ClawHub-Artifact-Type`, and + `X-ClawHub-Artifact-Sha256` headers for resolver integrity checks. +- Registry-only metadata is not injected into the downloaded archive. +- Pending VirusTotal scans do not block downloads; malicious releases return `403`. +- Private packages return `404` unless the caller is the owner. + +### `GET /api/npm/{package}` + +Returns an npm-compatible packument for ClawPack-backed package versions. + +Notes: + +- Only versions with uploaded ClawPack npm-pack tarballs are listed. +- Legacy ZIP-only versions are intentionally omitted. +- `dist.tarball`, `dist.integrity`, and `dist.shasum` use npm-compatible + fields so users can point npm at the mirror if they choose. +- Scoped package packuments support both `/api/npm/@scope/name` and npm's + encoded `/api/npm/@scope%2Fname` request path. + +### `GET /api/npm/{package}/-/{tarball}.tgz` + +Streams the exact uploaded ClawPack tarball bytes for npm mirror clients. + +Notes: + +- Uses the download rate bucket. +- Download headers include ClawHub SHA-256 plus npm integrity/shasum metadata. +- Moderation and private package access checks still apply. + +### `GET /api/v1/resolve` + +Used by the CLI to map a local fingerprint to a known version. + +Query params: + +- `slug` (required) +- `hash` (required): 64-char hex sha256 of the bundle fingerprint + +Response: + +```json +{ "slug": "gifgrep", "match": { "version": "1.2.2" }, "latestVersion": { "version": "1.2.3" } } +``` + +### `GET /api/v1/download` + +Downloads a zip of a skill version. + +Query params: + +- `slug` (required) +- `version` (optional): semver string +- `tag` (optional): tag name (e.g. `latest`) + +Notes: + +- If neither `version` nor `tag` is provided, the latest version is used. +- Soft-deleted versions return `410`. +- Download stats are counted as unique identities per hour (`userId` when API token is valid, otherwise IP). + +## Auth endpoints (Bearer token) + +All endpoints require: + +``` +Authorization: Bearer clh_... +``` + +### `GET /api/v1/whoami` + +Validates token and returns the user handle. + +### `POST /api/v1/skills` + +Publishes a new version. + +- Preferred: `multipart/form-data` with `payload` JSON + `files[]` blobs. +- JSON body with `files` (storageId-based) is also accepted. +- Optional payload field: `ownerHandle`. When present, the API resolves that + publisher server-side and requires the actor to have publisher access. + +### `POST /api/v1/packages` + +Publishes a code-plugin or bundle-plugin release. + +- Requires Bearer token auth. +- Preferred: `multipart/form-data` with `payload` JSON + `files[]` blobs. +- JSON body with `files` (storageId-based) is also accepted. +- Optional payload field: `ownerHandle`. When present, only admins may publish on behalf of that owner. + +Validation highlights: + +- `family` must be `code-plugin` or `bundle-plugin`. +- Plugin packages require `openclaw.plugin.json`. ClawPack `.tgz` uploads must + contain it at `package/openclaw.plugin.json`. +- Code plugins require `package.json`, source repo metadata, source commit + metadata, config schema metadata, `openclaw.compat.pluginApi`, and + `openclaw.build.openclawVersion`. +- `openclaw.hostTargets` and `openclaw.environment` are optional metadata. +- Only trusted publishers may publish to the `official` channel. +- On-behalf publishes still validate official-channel eligibility against the target owner account. + +### `DELETE /api/v1/skills/{slug}` / `POST /api/v1/skills/{slug}/undelete` + +Soft-delete / restore a skill (owner, moderator, or admin). + +Optional JSON body: + +```json +{ "reason": "Held for moderation pending legal review." } +``` + +When present, `reason` is stored as the skill moderation note and copied into the audit log. + +Status codes: + +- `200`: ok +- `401`: unauthorized +- `403`: forbidden +- `404`: skill/user not found +- `500`: internal server error + +### `POST /api/v1/users/publisher` + +Admin-only. Ensures an org publisher exists for a handle. If the handle still points at a +legacy shared user/personal publisher, the endpoint migrates it into an org publisher first. + +- Body: `{ "handle": "openclaw", "displayName": "OpenClaw", "trusted": true }` +- Response: `{ "ok": true, "publisherId": "...", "handle": "openclaw", "created": true, "migrated": false, "trusted": true }` + +### `POST /api/v1/users/reserve` + +Admin-only. Reserves root slugs and package names for a rightful owner without publishing a +release. Package names become private placeholder packages with no release rows, so the same +owner can later publish the real code-plugin or bundle-plugin release into that name. + +- Body: `{ "handle": "openclaw", "slugs": ["diffs"], "packageNames": ["@openclaw/diffs"], "reason": "reserved for official OpenClaw plugin" }` +- Response: `{ "ok": true, "succeeded": 2, "failed": 0, "results": [{ "kind": "slug", "name": "diffs", "ok": true, "action": "reserved" }] }` + +### Owner slug management endpoints + +- `POST /api/v1/skills/{slug}/rename` + - Body: `{ "newSlug": "new-canonical-slug" }` + - Response: `{ "ok": true, "slug": "new-canonical-slug", "previousSlug": "old-slug" }` +- `POST /api/v1/skills/{slug}/merge` + - Body: `{ "targetSlug": "canonical-target-slug" }` + - Response: `{ "ok": true, "sourceSlug": "old-slug", "targetSlug": "canonical-target-slug" }` + +Notes: + +- Both endpoints require API token auth and only work for the skill owner. +- `rename` preserves the previous slug as a redirect alias. +- `merge` hides the source listing and redirects the source slug to the target listing. + +### Transfer ownership endpoints + +- `POST /api/v1/skills/{slug}/transfer` + - Body: `{ "toUserHandle": "target_handle", "message": "optional" }` + - Response: `{ "ok": true, "transferId": "skillOwnershipTransfers:...", "toUserHandle": "target_handle", "expiresAt": 1730000000000 }` +- `POST /api/v1/skills/{slug}/transfer/accept` +- `POST /api/v1/skills/{slug}/transfer/reject` +- `POST /api/v1/skills/{slug}/transfer/cancel` + - Response (accept/reject/cancel): `{ "ok": true, "skillSlug": "demo-skill?" }` +- `GET /api/v1/transfers/incoming` +- `GET /api/v1/transfers/outgoing` + - Response shape: `{ "transfers": [{ "_id": "...", "skill": { "slug": "demo", "displayName": "Demo" }, "fromUser"|"toUser": { "handle": "..." }, "message": "...", "requestedAt": 0, "expiresAt": 0 }] }` + +### `POST /api/v1/users/ban` + +Ban a user and hard-delete owned skills (moderator/admin only). + +Body: + +```json +{ "handle": "user_handle", "reason": "optional ban reason" } +``` + +or + +```json +{ "userId": "users_...", "reason": "optional ban reason" } +``` + +Response: + +```json +{ "ok": true, "alreadyBanned": false, "deletedSkills": 3 } +``` + +### `POST /api/v1/users/unban` + +Unban a user and restore eligible skills (admin only). + +Body: + +```json +{ "handle": "user_handle", "reason": "optional unban reason" } +``` + +or + +```json +{ "userId": "users_...", "reason": "optional unban reason" } +``` + +Response: + +```json +{ "ok": true, "alreadyUnbanned": false, "restoredSkills": 3 } +``` + +### `POST /api/v1/users/role` + +Change a user role (admin only). + +Body: + +```json +{ "handle": "user_handle", "role": "moderator" } +``` + +or + +```json +{ "userId": "users_...", "role": "admin" } +``` + +Response: + +```json +{ "ok": true, "role": "moderator" } +``` + +### `GET /api/v1/users` + +List or search users (admin only). + +Query params: + +- `q` (optional): search query +- `query` (optional): alias for `q` +- `limit` (optional): max results (default 20, max 200) + +Response: + +```json +{ + "items": [ + { + "userId": "users_...", + "handle": "user_handle", + "displayName": "User", + "name": "User", + "role": "moderator" + } + ], + "total": 1 +} +``` + +### `POST /api/v1/stars/{slug}` / `DELETE /api/v1/stars/{slug}` + +Add/remove a star (highlights). Both endpoints are idempotent. + +Responses: + +```json +{ "ok": true, "starred": true, "alreadyStarred": false } +``` + +```json +{ "ok": true, "unstarred": true, "alreadyUnstarred": false } +``` + +## Legacy CLI endpoints (deprecated) + +Still supported for older CLI versions: + +- `GET /api/cli/whoami` +- `POST /api/cli/upload-url` +- `POST /api/cli/publish` +- `POST /api/cli/telemetry/sync` +- `POST /api/cli/skill/delete` +- `POST /api/cli/skill/undelete` + +See `DEPRECATIONS.md` for removal plan. + +## Registry discovery (`/.well-known/clawhub.json`) + +The CLI can discover registry/auth settings from the site: + +- `/.well-known/clawhub.json` (JSON, preferred) +- `/.well-known/clawdhub.json` (legacy) + +Schema: + +```json +{ "apiBase": "https://clawhub.ai", "authBase": "https://clawhub.ai", "minCliVersion": "0.0.5" } +``` + +If you self-host, serve this file (or set `CLAWHUB_REGISTRY` explicitly; legacy `CLAWDHUB_REGISTRY`). diff --git a/docs/clawhub/index.md b/docs/clawhub/index.md new file mode 100644 index 000000000..53dbdc155 --- /dev/null +++ b/docs/clawhub/index.md @@ -0,0 +1,177 @@ +--- +summary: "Public ClawHub overview for discovery, install, publish, security, and the clawhub CLI." +read_when: + - Explaining what ClawHub is + - Searching for, installing, or updating skills or plugins + - Publishing skills or plugins to the registry + - Choosing between openclaw and clawhub CLI flows +title: "ClawHub" +sidebarTitle: "ClawHub" +--- + +# ClawHub + +ClawHub is the public registry for OpenClaw skills and plugins. + +- Use native `openclaw` commands to search, install, and update skills and to install plugins from ClawHub. +- Use the separate `clawhub` CLI for registry auth, publishing, delete/undelete, rescans, and sync workflows. + +Site: [clawhub.ai](https://clawhub.ai) + +## Quick start + +Search and install skills with OpenClaw: + +```bash +openclaw skills search "calendar" +openclaw skills install +openclaw skills update --all +``` + +Search and install plugins with OpenClaw: + +```bash +openclaw plugins search "calendar" +openclaw plugins install clawhub: +openclaw plugins update --all +``` + +Install the ClawHub CLI when you want registry-authenticated workflows such as +publish, sync, delete/undelete, or owner-requested rescans: + +```bash +npm i -g clawhub +# or +pnpm add -g clawhub +``` + +## What ClawHub hosts + +| Surface | What it stores | Typical command | +| -------------- | ------------------------------------------------------------ | -------------------------------------------- | +| Skills | Versioned text bundles with `SKILL.md` plus supporting files | `openclaw skills install ` | +| Code plugins | OpenClaw plugin packages with compatibility metadata | `openclaw plugins install clawhub:` | +| Bundle plugins | Packaged plugin bundles for OpenClaw distribution | `clawhub package publish ` | +| Souls | `SOUL.md` bundles shown on onlycrabs.ai | Web and API publish flows | + +ClawHub tracks semver versions, tags such as `latest`, changelogs, files, +downloads, stars, and security scan summaries. Public pages show current registry +state so users can inspect a skill or plugin before installing it. + +## Native OpenClaw flows + +Native OpenClaw commands install into the active OpenClaw workspace and persist +source metadata so later update commands can stay on ClawHub. + +Use `clawhub:` when a plugin install should resolve through ClawHub. +Bare npm-safe plugin specs may resolve through npm during launch cutovers, and +`npm:` stays npm-only when a source must be explicit. + +Plugin installs validate advertised `pluginApi` and `minGatewayVersion` +compatibility before archive install runs. When a package version publishes a +ClawPack artifact, OpenClaw prefers the exact uploaded npm-pack `.tgz`, verifies +the ClawHub digest header and downloaded bytes, and records artifact metadata for +later updates. + +## ClawHub CLI + +The ClawHub CLI is for registry-authenticated work: + +```bash +clawhub login +clawhub whoami +clawhub search "postgres backups" +clawhub skill publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 +clawhub package explore --family code-plugin +clawhub package inspect episodic-claw +clawhub package publish your-org/your-plugin --dry-run +clawhub package publish your-org/your-plugin +clawhub sync --all +``` + +The CLI also has skill install/update commands for direct registry workflows: + +```bash +clawhub install +clawhub update +clawhub update --all +clawhub list +``` + +Those commands install skills into `./skills` under the current working directory +and record installed versions in `.clawhub/lock.json`. + +## Publishing + +Publish skills from a local folder containing `SKILL.md`: + +```bash +clawhub skill publish +``` + +Common publish options: + +- `--slug `: skill slug. +- `--name `: display name. +- `--version `: semver version. +- `--changelog `: changelog text. +- `--tags `: comma-separated tags, defaulting to `latest`. + +Publish plugins from a local folder, `owner/repo`, `owner/repo@ref`, or a GitHub +URL: + +```bash +clawhub package publish +``` + +Use `--dry-run` to build the exact publish plan without uploading, and `--json` +for CI-friendly output. + +Code plugins must include the required OpenClaw compatibility metadata in +`package.json`, including `openclaw.compat.pluginApi` and +`openclaw.build.openclawVersion`. See [CLI](/clawhub/cli) for the full command +reference and [Skill format](/clawhub/skill-format) for skill metadata. + +## Security and moderation + +ClawHub is open by default: anyone can upload, but publishing requires a GitHub +account old enough to pass the upload gate. Public detail pages summarize the +latest scan state before install or download. + +ClawHub runs automated checks on published skills and plugin releases. Scan-held +or blocked releases may disappear from public catalog and install surfaces while +remaining visible to their owner in `/dashboard`. + +Owners can request limited rescans for false-positive recovery: + +```bash +clawhub skill rescan +clawhub package rescan +``` + +Signed-in users can report skills and packages. Moderators can review reports, +hide or restore content, resolve appeals, and ban abusive accounts. See +[Acceptable usage](/clawhub/acceptable-usage) and +[Security + moderation](/clawhub/security) for policy and enforcement details. + +## Telemetry and environment + +When you run `clawhub sync` while logged in, the CLI sends a minimal snapshot so +ClawHub can compute install counts. Disable this with: + +```bash +export CLAWHUB_DISABLE_TELEMETRY=1 +``` + +Useful environment overrides: + +| Variable | Effect | +| ----------------------------- | ------------------------------------------------- | +| `CLAWHUB_SITE` | Override the site URL used for browser login. | +| `CLAWHUB_REGISTRY` | Override the registry API URL. | +| `CLAWHUB_CONFIG_PATH` | Override where the CLI stores token/config state. | +| `CLAWHUB_WORKDIR` | Override the default working directory. | +| `CLAWHUB_DISABLE_TELEMETRY=1` | Disable telemetry on `sync`. | + +See [Telemetry](/clawhub/telemetry), [HTTP API](/clawhub/http-api), and +[Troubleshooting](/clawhub/troubleshooting) for deeper reference material. diff --git a/docs/clawhub/quickstart.md b/docs/clawhub/quickstart.md new file mode 100644 index 000000000..a0e378586 --- /dev/null +++ b/docs/clawhub/quickstart.md @@ -0,0 +1,144 @@ +--- +summary: "Start using ClawHub: find, install, update, and publish skills or plugins." +read_when: + - First time using ClawHub + - Installing a skill or plugin from the registry + - Publishing to ClawHub +--- + +# Quickstart + +ClawHub is a registry for OpenClaw skills and plugins. + +Use OpenClaw when you are installing things into OpenClaw. Use the `clawhub` CLI +when you are signing in, publishing, managing your own listings, or using +registry-specific workflows. + +## Find and install a skill + +Search from OpenClaw: + +```bash +openclaw skills search "calendar" +``` + +Install a skill: + +```bash +openclaw skills install +``` + +Update installed skills: + +```bash +openclaw skills update --all +``` + +OpenClaw records where the skill came from so later updates can continue to +resolve through ClawHub. + +## Find and install a plugin + +Search from OpenClaw: + +```bash +openclaw plugins search "calendar" +``` + +Install a ClawHub-hosted plugin with an explicit ClawHub source: + +```bash +openclaw plugins install clawhub: +``` + +Update installed plugins: + +```bash +openclaw plugins update --all +``` + +Use the `clawhub:` prefix when you want OpenClaw to resolve the package through +ClawHub rather than npm or another source. + +## Sign in for publishing + +Install the ClawHub CLI: + +```bash +npm i -g clawhub +# or +pnpm add -g clawhub +``` + +Sign in with GitHub: + +```bash +clawhub login +clawhub whoami +``` + +Headless environments can use an API token from the ClawHub web UI: + +```bash +clawhub login --token clh_... +``` + +## Publish a skill + +A skill is a folder with a required `SKILL.md` file and optional supporting +files. + +```bash +clawhub skill publish ./my-skill \ + --slug my-skill \ + --name "My Skill" \ + --version 1.0.0 \ + --changelog "Initial release" +``` + +Before publishing, check the metadata in `SKILL.md`. Declare required +environment variables, tools, and permissions so users can understand what the +skill needs before they install it. See [Skill format](/clawhub/skill-format). + +## Publish a plugin + +Publish a plugin from a local folder, a GitHub repo, a GitHub ref, or an +existing archive: + +```bash +clawhub package publish --family code-plugin --dry-run +clawhub package publish --family code-plugin +``` + +Use `--dry-run` first to preview the resolved package metadata, compatibility +fields, source attribution, and upload plan without publishing. + +Code plugins must include OpenClaw compatibility metadata in `package.json`, +including `openclaw.compat.pluginApi` and `openclaw.build.openclawVersion`. + +## Sync skills you maintain + +`sync` scans skill folders and publishes new or changed skills that are not +already synchronized. + +```bash +clawhub sync --all --dry-run +clawhub sync --all +``` + +When you are signed in, `sync` may also send a minimal install snapshot for +aggregate install counts. See [Telemetry](/clawhub/telemetry) for what is reported +and how to opt out. + +## Inspect before installing + +Before installing, use the ClawHub web page or CLI detail commands to inspect +metadata, source links, versions, changelogs, and scan status: + +```bash +clawhub inspect +clawhub package inspect +``` + +Public listings show the latest scan state. Releases that are held or blocked by +moderation may be hidden from search and install surfaces until resolved. diff --git a/docs/clawhub/screenshots/markdown-html-passthrough/after.png b/docs/clawhub/screenshots/markdown-html-passthrough/after.png new file mode 100644 index 000000000..27c807dba Binary files /dev/null and b/docs/clawhub/screenshots/markdown-html-passthrough/after.png differ diff --git a/docs/clawhub/screenshots/markdown-html-passthrough/before.png b/docs/clawhub/screenshots/markdown-html-passthrough/before.png new file mode 100644 index 000000000..f3667ce42 Binary files /dev/null and b/docs/clawhub/screenshots/markdown-html-passthrough/before.png differ diff --git a/docs/clawhub/security.md b/docs/clawhub/security.md new file mode 100644 index 000000000..3ac18084f --- /dev/null +++ b/docs/clawhub/security.md @@ -0,0 +1,118 @@ +--- +summary: "ClawHub trust, scan, reporting, appeal, and moderation behavior." +read_when: + - Understanding ClawHub scan and moderation outcomes + - Reporting a skill or package + - Recovering from a held, hidden, or blocked listing +--- + +# Security + Moderation + +ClawHub is open to publishing, but public listings still pass through trust, +scan, reporting, and moderation controls. The goal is practical: help users +inspect what they install, give publishers a recovery path for false positives, +and keep abusive packages out of public discovery. + +See also [Acceptable usage](/clawhub/acceptable-usage). + +## What users can inspect + +Before installing a skill or plugin, check its ClawHub listing for: + +- owner and source attribution +- latest version and changelog +- required environment variables or permissions +- compatibility metadata for plugins +- scan or moderation status +- reports, comments, stars, downloads, and install signals where shown + +Install only content you understand and trust. + +## Scan states + +ClawHub may show scan or moderation outcomes on public pages and owner-visible +diagnostics. + +Common outcomes include: + +- `clean`: no blocking issue was found. +- `suspicious`: the release needs caution or review. +- `malicious`: the release is considered unsafe. +- `pending`: checks have not finished yet. +- `held`, `quarantined`, `revoked`, or `hidden`: the release is not fully + available on public install surfaces. + +Exact wording may vary by surface, but the practical meaning is the same: if a +release is held or blocked, users should not install it until the owner resolves +the issue or moderation restores it. + +## Skills + +Skill scans look at the published skill bundle, metadata, declared +requirements, and suspicious instructions. + +ClawHub pays special attention to mismatches between what a skill declares and +what it appears to do. For example, a skill that references a required API key +should declare that requirement in `SKILL.md` so users can see it before +installing. + +See [Skill format](/clawhub/skill-format). + +## Plugins + +Plugin releases include package metadata, source attribution, compatibility +fields, and artifact integrity information. + +OpenClaw checks compatibility before installing ClawHub-hosted plugins. Package +records may also expose digest metadata so OpenClaw can verify downloaded +artifacts. + +## Reports + +Signed-in users can report skills, packages, and comments. + +Reports should be specific and actionable. Abuse of reporting can itself lead to +account action. + +Report examples: + +- misleading metadata +- undeclared credential or permission requirements +- suspicious install instructions +- scam comments or impersonation +- content that violates [Acceptable usage](/clawhub/acceptable-usage) + +## Appeals and rescans + +Owners can request a rescan when they believe a skill or package was incorrectly +held or flagged: + +```bash +clawhub skill rescan +clawhub package rescan +``` + +For moderated content, owners may be able to submit an appeal from the +owner-visible ClawHub surfaces. Appeals should explain what changed or why the +flag is incorrect. + +## Bans and account standing + +Accounts that violate ClawHub policy may lose publishing access. Severe abuse +can result in account bans, token revocation, hidden content, or removed +listings. + +Deleted, banned, or disabled accounts cannot use ClawHub API tokens. If CLI auth +starts failing after account action, sign in to the web UI to review account +state or contact maintainers through the expected project support channel. + +## Publisher guidance + +To reduce false positives and improve user trust: + +- keep names, summaries, tags, and changelogs accurate +- declare required environment variables and permissions +- avoid obfuscated install commands +- link to source when possible +- use dry runs before publishing plugins +- respond clearly if users or moderators ask about package behavior diff --git a/docs/clawhub/skill-format.md b/docs/clawhub/skill-format.md new file mode 100644 index 000000000..feda9faf0 --- /dev/null +++ b/docs/clawhub/skill-format.md @@ -0,0 +1,191 @@ +--- +summary: "Skill folder format, required files, allowed file types, limits." +read_when: + - Publishing skills + - Debugging publish/sync failures +--- + +# Skill format + +## On disk + +A skill is a folder. + +Required: + +- `SKILL.md` (or `skill.md`) + +Optional: + +- any supporting _text-based_ files (see “Allowed files”) +- `.clawhubignore` (ignore patterns for publish/sync, legacy `.clawdhubignore`) +- `.gitignore` (also honored) + +Local install metadata (written by the CLI): + +- `/.clawhub/origin.json` (legacy `.clawdhub`) + +Workdir install state (written by the CLI): + +- `/.clawhub/lock.json` (legacy `.clawdhub`) + +## `SKILL.md` + +- Markdown with optional YAML frontmatter. +- The server extracts metadata from frontmatter during publish. +- `description` is used as the skill summary in the UI/search. + +## Frontmatter metadata + +Skill metadata is declared in the YAML frontmatter at the top of your `SKILL.md`. This tells the registry (and security analysis) what your skill needs to run. + +### Basic frontmatter + +```yaml +--- +name: my-skill +description: Short summary of what this skill does. +version: 1.0.0 +--- +``` + +### Runtime metadata (`metadata.openclaw`) + +Declare your skill's runtime requirements under `metadata.openclaw` (aliases: `metadata.clawdbot`, `metadata.clawdis`). + +```yaml +--- +name: my-skill +description: Manage tasks via the Todoist API. +metadata: + openclaw: + requires: + env: + - TODOIST_API_KEY + bins: + - curl + primaryEnv: TODOIST_API_KEY +--- +``` + +Use `requires.env` for environment variables that must be present before the skill can run. Use `envVars` when you need per-variable metadata, including optional variables with `required: false`. + +### Full field reference + +| Field | Type | Description | +| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `requires.env` | `string[]` | Required environment variables your skill expects. | +| `requires.bins` | `string[]` | CLI binaries that must all be installed. | +| `requires.anyBins` | `string[]` | CLI binaries where at least one must exist. | +| `requires.config` | `string[]` | Config file paths your skill reads. | +| `primaryEnv` | `string` | The main credential env var for your skill. | +| `envVars` | `array` | Environment variable declarations with `name`, optional `required`, and optional `description`. Set `required: false` for optional env vars. | +| `always` | `boolean` | If `true`, skill is always active (no explicit install needed). | +| `skillKey` | `string` | Override the skill's invocation key. | +| `emoji` | `string` | Display emoji for the skill. | +| `homepage` | `string` | URL to the skill's homepage or docs. | +| `os` | `string[]` | OS restrictions (e.g. `["macos"]`, `["linux"]`). | +| `install` | `array` | Install specs for dependencies (see below). | +| `nix` | `object` | Nix plugin spec (see README). | +| `config` | `object` | Clawdbot config spec (see README). | + +### Install specs + +If your skill needs dependencies installed, declare them in the `install` array: + +```yaml +metadata: + openclaw: + install: + - kind: brew + formula: jq + bins: [jq] + - kind: node + package: typescript + bins: [tsc] +``` + +Supported install kinds: `brew`, `node`, `go`, `uv`. + +### Optional environment variables + +Declare optional environment variables under `metadata.openclaw.envVars` and set `required: false`. Do not add optional entries to `requires.env`, because `requires.env` means the skill cannot run without them. + +```yaml +metadata: + openclaw: + primaryEnv: TODOIST_API_KEY + envVars: + - name: TODOIST_API_KEY + required: true + description: Todoist API token used for authenticated requests. + - name: TODOIST_PROJECT_ID + required: false + description: Optional default project ID when the user does not specify one. +``` + +### Why this matters + +ClawHub's security analysis checks that what your skill declares matches what it actually does. If your code references `TODOIST_API_KEY` but your frontmatter doesn't declare it under `requires.env`, `primaryEnv`, or `envVars`, the analysis will flag a metadata mismatch. Keeping declarations accurate helps your skill pass review and helps users understand what they're installing. + +### Example: complete frontmatter + +```yaml +--- +name: todoist-cli +description: Manage Todoist tasks, projects, and labels from the command line. +version: 1.2.0 +metadata: + openclaw: + requires: + env: + - TODOIST_API_KEY + bins: + - curl + primaryEnv: TODOIST_API_KEY + envVars: + - name: TODOIST_API_KEY + required: true + description: Todoist API token. + - name: TODOIST_PROJECT_ID + required: false + description: Optional default project ID. + emoji: "\u2705" + homepage: https://github.com/example/todoist-cli +--- +``` + +## Allowed files + +Only “text-based” files are accepted by publish. + +- Extension allowlist is in `packages/schema/src/textFiles.ts` (`TEXT_FILE_EXTENSIONS`). +- Content types starting with `text/` are treated as text; plus a small allowlist (JSON/YAML/TOML/JS/TS/Markdown/SVG). + +Limits (server-side): + +- Total bundle size: 50MB. +- Embedding text includes `SKILL.md` + up to ~40 non-`.md` files (best-effort cap). + +## Slugs + +- Derived from folder name by default. +- Must be lowercase and URL-safe: `^[a-z0-9][a-z0-9-]*$`. + +## Versioning + tags + +- Each publish creates a new version (semver). +- Tags are string pointers to a version; `latest` is commonly used. + +## License + +- All skills published on ClawHub are licensed under `MIT-0`. +- Anyone may use, modify, and redistribute published skills, including commercially. +- Attribution is not required. +- Do not add conflicting license terms in `SKILL.md`; ClawHub does not support per-skill license overrides. + +## Paid skills + +- ClawHub does not support paid skills, per-skill pricing, paywalls, or revenue sharing. +- Do not add pricing metadata to `SKILL.md`; it is not part of the skill format and will not make a published skill paid. +- If your skill integrates with a paid third-party service, document the external cost and required account clearly in the skill instructions and env declarations (`requires.env` for required variables, or `envVars` with `required: false` for optional variables). diff --git a/docs/clawhub/soul-format.md b/docs/clawhub/soul-format.md new file mode 100644 index 000000000..4a7c202d1 --- /dev/null +++ b/docs/clawhub/soul-format.md @@ -0,0 +1,37 @@ +--- +summary: "Soul bundle format, required files, limits." +read_when: + - Publishing souls + - Debugging soul publish failures +--- + +# Soul format + +## On disk + +A soul is a single file: + +- `SOUL.md` (or `soul.md`) + +For now, onlycrabs.ai rejects any extra files. + +## `SOUL.md` + +- Markdown with optional YAML frontmatter. +- The server extracts metadata from frontmatter during publish. +- `description` is used as the soul summary in the UI/search. + +## Limits + +- Total bundle size: 50MB. +- Embedding text includes `SOUL.md` only. + +## Slugs + +- Derived from folder name by default. +- Must be lowercase and URL-safe: `^[a-z0-9][a-z0-9-]*$`. + +## Versioning + tags + +- Each publish creates a new version (semver). +- Tags are string pointers to a version; `latest` is commonly used. diff --git a/docs/clawhub/telemetry.md b/docs/clawhub/telemetry.md new file mode 100644 index 000000000..3a033b6ea --- /dev/null +++ b/docs/clawhub/telemetry.md @@ -0,0 +1,91 @@ +--- +summary: "Install telemetry collected via `clawhub sync` + opt-out." +read_when: + - Working on telemetry / privacy controls + - Questions about what data is collected +--- + +# Telemetry + +ClawHub uses **minimal telemetry** to compute **install counts** (what’s actually in use) and to power better sorting/filtering. +This is based on the CLI `clawhub sync` command. + +## When telemetry is collected + +Telemetry is only sent when: + +- You are **logged in** in the CLI (we already require auth for sync/publish flows). +- You run `clawhub sync`. +- Telemetry is **not disabled** (see “How to disable” below). + +If you are not logged in, nothing is reported. + +## What we collect + +On each `clawhub sync`, the CLI reports a **full snapshot** of what it found, grouped by scan root (“folder/root”). + +For each root we store: + +- `rootId`: a **SHA-256 hash** of the canonical root path (server never sees the raw path). +- `label`: a human-readable label derived from the last two path segments (home paths are shown with `~`). +- `firstSeenAt`, `lastSeenAt`, optional `expiredAt`. + +For each skill found under a root we store: + +- `skillId` (resolved by slug; only skills that exist in the registry are tracked). +- `firstSeenAt`, `lastSeenAt`. +- `lastVersion` (best-effort; currently the registry-matched version if known). +- optional `removedAt` when a previously-reported install disappears from a root. + +### What we do _not_ collect + +- No raw absolute folder paths (only hashed `rootId` + a short display label). +- No file contents. +- No per-run logs, prompts, or other CLI output. +- No tracking for skills that aren’t uploaded to the registry (unknown slugs are ignored). + +## Install counts + +We maintain two counters per skill: + +- `installsCurrent`: unique users who currently have the skill installed in at least one active root. +- `installsAllTime`: unique users who have ever reported the skill installed. + +### Multiple roots + +If you sync from multiple folders, we treat each scan root independently. A skill is “currently installed” if it exists in **any** active root. + +### Uninstall detection + +Because `sync` reports the full set per root: + +- If a skill disappears from a root on the next sync, we mark it removed for that root. +- If the skill is removed from all of your roots, it no longer counts toward `installsCurrent`. +- `installsAllTime` never decreases unless you delete telemetry (see below). + +### Staleness (120 days) + +Roots that don’t report telemetry for **120 days** are marked stale and their installs stop counting toward `installsCurrent`. +This is evaluated lazily (on the next telemetry report) to avoid background jobs. + +## Transparency + user controls + +ClawHub provides a private “Installed” tab on your own profile: + +- Shows the exact roots + installed skills we store. +- Includes a **JSON export** view. +- Includes a **Delete telemetry** action to remove all stored telemetry for your account. + +Everyone else only sees **aggregated install counters**; no one else can see your roots/folders. + +Deleting your account also deletes your telemetry data. + +## How to disable telemetry + +Set the environment variable: + +```bash +export CLAWHUB_DISABLE_TELEMETRY=1 +``` + +With this set, the CLI will not send telemetry during `clawhub sync`. diff --git a/docs/clawhub/troubleshooting.md b/docs/clawhub/troubleshooting.md new file mode 100644 index 000000000..8b5980bb8 --- /dev/null +++ b/docs/clawhub/troubleshooting.md @@ -0,0 +1,140 @@ +--- +summary: "Troubleshooting ClawHub sign-in, install, publish, sync, update, and API issues." +read_when: + - ClawHub CLI or OpenClaw registry commands fail + - A package cannot be installed, published, or updated +--- + +# Troubleshooting + +## `clawhub login` opens a browser but never completes + +The CLI starts a short-lived local callback server during browser login. + +- Make sure your browser can reach `http://127.0.0.1:/callback`. +- Check local firewall, VPN, and proxy rules if the callback never arrives. +- In headless environments, create an API token in the ClawHub web UI and run: + +```bash +clawhub login --token clh_... +``` + +## `whoami` or `publish` returns `Unauthorized` (401) + +- Sign in again with `clawhub login`. +- If you use a custom config path, confirm `CLAWHUB_CONFIG_PATH` points at the + file that contains your current token. +- If you use an API token, confirm it was not revoked in the web UI. + +## Search or install returns `Rate limit exceeded` (429) + +Read the retry information in the response: + +- `Retry-After`: seconds to wait before retrying. +- `RateLimit-Remaining` and `RateLimit-Limit`: your current budget. +- `RateLimit-Reset` or `X-RateLimit-Reset`: reset timing. + +If many users share one egress IP, anonymous IP limits can be hit even when each +person only sends a few requests. Sign in where possible and retry after the +reported delay. + +## Search or install fails behind a proxy + +The CLI respects standard proxy variables: + +```bash +export HTTPS_PROXY=http://proxy.example.com:3128 +clawhub search "my query" +``` + +Supported names include `HTTPS_PROXY`, `HTTP_PROXY`, `https_proxy`, and +`http_proxy`. + +## A skill does not appear in search + +- Check the exact slug or owner page if you know it. +- Confirm the release is public and not held by scan or moderation. +- If you own the skill, sign in and inspect it: + +```bash +clawhub inspect +``` + +Owner-visible diagnostics may explain scan, upload-gate, or moderation state. + +## Publish fails because required metadata is missing + +For skills, check `SKILL.md` frontmatter. Required environment variables and +tools should be declared so users and scanners can understand the package. + +For plugins, check `package.json` compatibility metadata. Code-plugin publishes +need OpenClaw compatibility fields such as `openclaw.compat.pluginApi` and +`openclaw.build.openclawVersion`. + +Preview the publish payload first: + +```bash +clawhub package publish --family code-plugin --dry-run +``` + +## Publish fails with a GitHub owner or source error + +ClawHub uses GitHub identity and source attribution to connect packages to their +publishers. + +- Make sure you are signed in with the GitHub account that owns or can publish + the package. +- Check that the source URL is public or accessible to ClawHub. +- For GitHub sources, use `owner/repo`, `owner/repo@ref`, or a full GitHub URL. + +## `sync` says no skills were found + +`sync` looks for folders containing `SKILL.md` or `skill.md`. + +Point it at the roots you want to scan: + +```bash +clawhub sync --root /path/to/skills +``` + +Preview first if you are unsure what will publish: + +```bash +clawhub sync --all --dry-run --no-input +``` + +## `update` refuses because of local changes + +The local files do not match any version ClawHub knows about. Choose one: + +- Keep local edits and skip the update. +- Overwrite with the published version: + +```bash +clawhub update --force +``` + +- Publish your edited copy as a new slug or fork. + +## A plugin install fails in OpenClaw + +- Use an explicit ClawHub source: + +```bash +openclaw plugins install clawhub: +``` + +- Check the package detail page for scan status and compatibility metadata. +- Confirm your OpenClaw version satisfies the package's advertised + compatibility range. +- If the package is hidden, held, or blocked, it may not be installable until + the owner resolves the issue. + +## Public API requests fail + +- Respect `429` retry headers and cache public list/search responses. +- Link users back to the canonical ClawHub listing. +- Do not mirror hidden, private, held, or moderation-blocked content outside the + public API surface. + +See [HTTP API](/clawhub/http-api) for endpoint details. diff --git a/docs/cli/plugins.md b/docs/cli/plugins.md index 217eaa34e..dd7c813df 100644 --- a/docs/cli/plugins.md +++ b/docs/cli/plugins.md @@ -129,7 +129,7 @@ is available, then fall back to `latest`. This CLI flag applies to plugin install/update flows. Gateway-backed skill dependency installs use the matching `dangerouslyForceUnsafeInstall` request override, while `openclaw skills install` remains a separate ClawHub skill download/install flow. - If a plugin you published on ClawHub is blocked by a registry scan, use the publisher steps in [ClawHub](/tools/clawhub). + If a plugin you published on ClawHub is blocked by a registry scan, use the publisher steps in [ClawHub](/clawhub/security). @@ -417,4 +417,4 @@ Marketplace list accepts a local marketplace path, a `marketplace.json` path, a - [Building plugins](/plugins/building-plugins) - [CLI reference](/cli) -- [Community plugins](/plugins/community) +- [ClawHub](/clawhub) diff --git a/docs/cli/skills.md b/docs/cli/skills.md index a39491347..e2775899f 100644 --- a/docs/cli/skills.md +++ b/docs/cli/skills.md @@ -15,7 +15,7 @@ Related: - Skills system: [Skills](/tools/skills) - Skills config: [Skills config](/tools/skills-config) -- ClawHub installs: [ClawHub](/tools/clawhub) +- ClawHub installs: [ClawHub](/clawhub/cli) ## Commands diff --git a/docs/docs.json b/docs/docs.json index 90626e6d1..3ff31795b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -393,16 +393,16 @@ "destination": "/channels/pairing" }, { - "source": "/clawhub", - "destination": "/tools/clawhub" + "source": "/clawdhub", + "destination": "/clawhub" }, { - "source": "/clawdhub", - "destination": "/tools/clawhub" + "source": "/tools/clawhub", + "destination": "/clawhub" }, { "source": "/tools/clawdhub", - "destination": "/tools/clawhub" + "destination": "/clawhub" }, { "source": "/configuration", @@ -1257,7 +1257,6 @@ "tools/creating-skills", "tools/skills-config", "tools/slash-commands", - "tools/clawhub", "prose" ] }, @@ -1340,6 +1339,40 @@ } ] }, + { + "tab": "ClawHub", + "groups": [ + { + "group": "Overview", + "pages": [ + "clawhub/index", + "clawhub/quickstart", + "clawhub/how-it-works" + ] + }, + { + "group": "Using ClawHub", + "pages": [ + "clawhub/cli", + "clawhub/publishing", + "clawhub/skill-format", + "clawhub/soul-format", + "clawhub/auth", + "clawhub/telemetry", + "clawhub/troubleshooting" + ] + }, + { + "group": "API and trust", + "pages": [ + "clawhub/api", + "clawhub/http-api", + "clawhub/security", + "clawhub/acceptable-usage" + ] + } + ] + }, { "tab": "Models", "groups": [ @@ -2068,7 +2101,6 @@ "zh-CN/tools/slash-commands", "zh-CN/tools/skills", "zh-CN/tools/skills-config", - "zh-CN/tools/clawhub", "zh-CN/tools/plugin" ] }, @@ -2749,7 +2781,6 @@ "zh-TW/tools/creating-skills", "zh-TW/tools/skills-config", "zh-TW/tools/slash-commands", - "zh-TW/tools/clawhub", "zh-TW/prose" ] }, @@ -3627,7 +3658,6 @@ "ja-JP/tools/creating-skills", "ja-JP/tools/skills-config", "ja-JP/tools/slash-commands", - "ja-JP/tools/clawhub", "ja-JP/prose" ] }, @@ -4505,7 +4535,6 @@ "es/tools/creating-skills", "es/tools/skills-config", "es/tools/slash-commands", - "es/tools/clawhub", "es/prose" ] }, @@ -5383,7 +5412,6 @@ "pt-BR/tools/creating-skills", "pt-BR/tools/skills-config", "pt-BR/tools/slash-commands", - "pt-BR/tools/clawhub", "pt-BR/prose" ] }, @@ -6261,7 +6289,6 @@ "ko/tools/creating-skills", "ko/tools/skills-config", "ko/tools/slash-commands", - "ko/tools/clawhub", "ko/prose" ] }, @@ -7139,7 +7166,6 @@ "de/tools/creating-skills", "de/tools/skills-config", "de/tools/slash-commands", - "de/tools/clawhub", "de/prose" ] }, @@ -8017,7 +8043,6 @@ "fr/tools/creating-skills", "fr/tools/skills-config", "fr/tools/slash-commands", - "fr/tools/clawhub", "fr/prose" ] }, @@ -8895,7 +8920,6 @@ "ar/tools/creating-skills", "ar/tools/skills-config", "ar/tools/slash-commands", - "ar/tools/clawhub", "ar/prose" ] }, @@ -9773,7 +9797,6 @@ "it/tools/creating-skills", "it/tools/skills-config", "it/tools/slash-commands", - "it/tools/clawhub", "it/prose" ] }, @@ -10651,7 +10674,6 @@ "vi/tools/creating-skills", "vi/tools/skills-config", "vi/tools/slash-commands", - "vi/tools/clawhub", "vi/prose" ] }, @@ -11529,7 +11551,6 @@ "nl/tools/creating-skills", "nl/tools/skills-config", "nl/tools/slash-commands", - "nl/tools/clawhub", "nl/prose" ] }, @@ -12407,7 +12428,6 @@ "tr/tools/creating-skills", "tr/tools/skills-config", "tr/tools/slash-commands", - "tr/tools/clawhub", "tr/prose" ] }, @@ -13285,7 +13305,6 @@ "uk/tools/creating-skills", "uk/tools/skills-config", "uk/tools/slash-commands", - "uk/tools/clawhub", "uk/prose" ] }, @@ -14163,7 +14182,6 @@ "id/tools/creating-skills", "id/tools/skills-config", "id/tools/slash-commands", - "id/tools/clawhub", "id/prose" ] }, @@ -15041,7 +15059,6 @@ "pl/tools/creating-skills", "pl/tools/skills-config", "pl/tools/slash-commands", - "pl/tools/clawhub", "pl/prose" ] }, diff --git a/docs/help/faq.md b/docs/help/faq.md index 63f56c25f..6467f2408 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -409,7 +409,7 @@ lives on the [First-run FAQ](/help/faq-first-run). openclaw skills update --all ``` - Native installs land in the active workspace `skills/` directory. For shared skills across agents, place them in `~/.openclaw/skills//SKILL.md`. If only some agents should see a shared install, configure `agents.defaults.skills` or `agents.list[].skills`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills), [Skills config](/tools/skills-config), and [ClawHub](/tools/clawhub). + Native installs land in the active workspace `skills/` directory. For shared skills across agents, place them in `~/.openclaw/skills//SKILL.md`. If only some agents should see a shared install, configure `agents.defaults.skills` or `agents.list[].skills`. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See [Skills](/tools/skills), [Skills config](/tools/skills-config), and [ClawHub](/clawhub). diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index efd88963f..27e34a4d2 100644 --- a/docs/plugins/building-plugins.md +++ b/docs/plugins/building-plugins.md @@ -14,7 +14,7 @@ generation, video generation, web fetch, web search, agent tools, or any combination. You do not need to add your plugin to the OpenClaw repository. Publish to -[ClawHub](/tools/clawhub) and users install with +[ClawHub](/clawhub) and users install with `openclaw plugins install clawhub:`. Bare package specs still install from npm during the launch cutover. diff --git a/docs/plugins/community.md b/docs/plugins/community.md index 1e777e879..aebc7b44a 100644 --- a/docs/plugins/community.md +++ b/docs/plugins/community.md @@ -8,7 +8,7 @@ title: "Community plugins" Community plugins are third-party packages that extend OpenClaw with new channels, tools, providers, or other capabilities. They are built and maintained -by the community, usually published on [ClawHub](/tools/clawhub), and installable +by the community, usually published on [ClawHub](/clawhub), and installable with a single command. Npm remains the launch default for bare package specs while ClawHub pack installs roll out. @@ -152,7 +152,7 @@ We welcome community plugins that are useful, documented, and safe to operate. Your plugin must be installable via `openclaw plugins install \`. - Publish to [ClawHub](/tools/clawhub) unless you specifically need npm-only + Publish to [ClawHub](/clawhub) unless you specifically need npm-only distribution. See [Building Plugins](/plugins/building-plugins) for the full guide. diff --git a/docs/plugins/manage-plugins.md b/docs/plugins/manage-plugins.md index 5d882a76e..da26ad61c 100644 --- a/docs/plugins/manage-plugins.md +++ b/docs/plugins/manage-plugins.md @@ -187,6 +187,6 @@ forces npm resolution. - [Plugins](/tools/plugin) - overview and troubleshooting - [`openclaw plugins`](/cli/plugins) - full CLI reference -- [ClawHub](/tools/clawhub) - publish and registry operations +- [ClawHub](/clawhub/cli) - publish and registry operations - [Building plugins](/plugins/building-plugins) - create a plugin package - [Plugin manifest](/plugins/manifest) - manifest and package metadata diff --git a/docs/plugins/sdk-setup.md b/docs/plugins/sdk-setup.md index 1324c6934..2ccc6b8cd 100644 --- a/docs/plugins/sdk-setup.md +++ b/docs/plugins/sdk-setup.md @@ -492,7 +492,7 @@ The `ChannelSetupWizard` type supports `credentials`, `textInputs`, `dmPolicy`, ## Publishing and installing -**External plugins:** publish to [ClawHub](/tools/clawhub), then install: +**External plugins:** publish to [ClawHub](/clawhub), then install: diff --git a/docs/plugins/zalouser.md b/docs/plugins/zalouser.md index 91e75d802..9885aab35 100644 --- a/docs/plugins/zalouser.md +++ b/docs/plugins/zalouser.md @@ -83,4 +83,4 @@ Channel message actions also support `react` for message reactions. ## Related - [Building plugins](/plugins/building-plugins) -- [Community plugins](/plugins/community) +- [ClawHub](/clawhub) diff --git a/docs/start/hubs.md b/docs/start/hubs.md index 7d00a56fd..45b939f78 100644 --- a/docs/start/hubs.md +++ b/docs/start/hubs.md @@ -167,7 +167,7 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Plugin manifest](/plugins/manifest) - [Agent tools](/plugins/building-plugins#registering-agent-tools) - [Plugin bundles](/plugins/bundles) -- [Community plugins](/plugins/community) +- [ClawHub](/clawhub) - [Capability cookbook](/tools/capability-cookbook) - [Voice call plugin](/plugins/voice-call) - [Zalo user plugin](/plugins/zalouser) @@ -175,7 +175,7 @@ Use these hubs to discover every page, including deep dives and reference docs t ## Workspace + templates - [Skills](/tools/skills) -- [ClawHub](/tools/clawhub) +- [ClawHub](/clawhub) - [Skills config](/tools/skills-config) - [Default AGENTS](/reference/AGENTS.default) - [Templates: AGENTS](/reference/templates/AGENTS) diff --git a/docs/tools/clawhub.md b/docs/tools/clawhub.md index 987efaefe..f63db895d 100644 --- a/docs/tools/clawhub.md +++ b/docs/tools/clawhub.md @@ -1,470 +1,5 @@ --- -summary: "ClawHub: public registry for OpenClaw skills and plugins, native install flows, and the clawhub CLI" -read_when: - - Searching for, installing, or updating skills or plugins - - Publishing skills or plugins to the registry - - Configuring the clawhub CLI or its environment overrides -title: "ClawHub" -sidebarTitle: "ClawHub" +summary: "Redirect to /clawhub" +title: "ClawHub (redirect)" +redirect: /clawhub --- - -ClawHub is the public registry for **OpenClaw skills and plugins**. - -- Use native `openclaw` commands to search, install, and update skills, and to install plugins from ClawHub. -- Use the separate `clawhub` CLI for registry auth, publish, delete/undelete, and sync workflows. - -Site: [clawhub.ai](https://clawhub.ai) - -## Quick start - - - - ```bash - openclaw skills search "calendar" - ``` - - - ```bash - openclaw skills install - ``` - - - Start a new OpenClaw session - it picks up the new skill. - - - For registry-authenticated workflows (publish, sync, manage), install - the separate `clawhub` CLI: - - ```bash - npm i -g clawhub - # or - pnpm add -g clawhub - ``` - - - - -## Native OpenClaw flows - - - - ```bash - openclaw skills search "calendar" - openclaw skills install - openclaw skills update --all - ``` - - Native `openclaw` commands install into your active workspace and - persist source metadata so later `update` calls can stay on ClawHub. - - - - ```bash - openclaw plugins search "calendar" - openclaw plugins install clawhub: - openclaw plugins update --all - ``` - - `plugins search` queries the ClawHub plugin catalog and prints install-ready - package names. Use `clawhub:` when you want ClawHub resolution. - Bare npm-safe plugin specs install from npm during the launch cutover: - - ```bash - openclaw plugins install openclaw-codex-app-server - ``` - - `npm:` is also npm-only and is useful when a spec could otherwise - be ambiguous: - - ```bash - openclaw plugins install npm:openclaw-codex-app-server - ``` - - Plugin installs validate advertised `pluginApi` and - `minGatewayVersion` compatibility before archive install runs, so - incompatible hosts fail closed early instead of partially installing - the package. When a package version publishes a ClawPack artifact, - OpenClaw prefers the exact uploaded npm-pack `.tgz`, verifies the ClawHub - digest header and downloaded bytes, and records the artifact kind, npm - integrity, npm shasum, tarball name, and ClawPack digest metadata for later - updates. Older package versions without ClawPack metadata still use the - legacy package archive verification path. - - - - - -`openclaw plugins install clawhub:...` only accepts installable plugin -families. If a ClawHub package is actually a skill, OpenClaw stops and -points you at `openclaw skills install ` instead. - -Anonymous ClawHub plugin installs also fail closed for private packages. -Community or other non-official channels can still install, but OpenClaw -warns so operators can review source and verification before enabling -them. - - -## What ClawHub is - -- A public registry for OpenClaw skills and plugins. -- A versioned store of skill bundles and metadata. -- A discovery surface for search, tags, and usage signals. - -A typical skill is a versioned bundle of files that includes: - -- A `SKILL.md` file with the primary description and usage. -- Optional configs, scripts, or supporting files used by the skill. -- Metadata such as tags, summary, and install requirements. - -ClawHub uses metadata to power discovery and safely expose skill -capabilities. The registry tracks usage signals (stars, downloads) to -improve ranking and visibility. Each publish creates a new semver -version, and the registry keeps version history so users can audit -changes. - -## Workspace and skill loading - -The separate `clawhub` CLI also installs skills into `./skills` under -your current working directory. If an OpenClaw workspace is configured, -`clawhub` falls back to that workspace unless you override `--workdir` -(or `CLAWHUB_WORKDIR`). OpenClaw loads workspace skills from -`/skills` and picks them up in the **next** session. - -If you already use `~/.openclaw/skills` or bundled skills, workspace -skills take precedence. For more detail on how skills are loaded, -shared, and gated, see [Skills](/tools/skills). - -## Service features - -| Feature | Notes | -| ------------------------ | ------------------------------------------------------------------- | -| Public browsing | Skills and their `SKILL.md` content are publicly viewable. | -| Search | Embedding-powered (vector search), not just keywords. | -| Versioning | Semver, changelogs, and tags (including `latest`). | -| Downloads | Zip per version. | -| Stars and comments | Community feedback. | -| Security scan summaries | Detail pages show the latest scan state before install or download. | -| Scanner detail pages | VirusTotal, ClawScan, and static-analysis results have deep links. | -| Owner recovery dashboard | Publishers can see scan-held owned content from `/dashboard`. | -| Owner-requested rescans | Owners can request limited rescans for false-positive recovery. | -| Moderation | Approvals and audits. | -| CLI-friendly API | Suitable for automation and scripting. | - -## Security and moderation - -ClawHub is open by default - anyone can upload skills, but a GitHub -account must be **at least one week old** to publish. This slows down -abuse without blocking legitimate contributors. - - - - ClawHub runs automated security checks on published skills and plugin - releases. Public detail pages summarize the current result, and scanner - rows link to dedicated detail pages for VirusTotal, ClawScan, and static - analysis. - - Scan-held or blocked releases may be unavailable on public catalog and - install surfaces while still visible to their owner in `/dashboard`. - - - - - Any signed-in user can report a skill. - - Report reasons are required and recorded. - - Each user can have up to 20 active reports at a time. - - Skills with more than 3 unique reports are auto-hidden by default. - - - - - Moderators can view hidden skills, unhide them, delete them, or ban users. - - Abusing the report feature can result in account bans. - - Interested in becoming a moderator? Ask in the OpenClaw Discord and contact a moderator or maintainer. - - - - -## ClawHub CLI - -You only need this for registry-authenticated workflows such as -publish/sync. - -### Global options - - - Working directory. Default: current dir; falls back to OpenClaw workspace. - - - Skills directory, relative to workdir. - - - Site base URL (browser login). - - - Registry API base URL. - - - Disable prompts (non-interactive). - - - Print CLI version. - - -### Commands - - - - ```bash - clawhub login # browser flow - clawhub login --token - clawhub logout - clawhub whoami - ``` - - Login options: - - - `--token ` - paste an API token. - - `--label - - ```bash - clawhub search "query" - ``` - - Searches skills. For plugin/package discovery, use `clawhub package explore`. - - - `--limit ` - max results. - - - - ```bash - clawhub package explore --family code-plugin - clawhub package explore "episodic-claw" --family code-plugin - clawhub package inspect episodic-claw - ``` - - `package explore` and `package inspect` are the ClawHub CLI surfaces for plugin/package discovery and metadata inspection. Native OpenClaw installs still use `openclaw plugins install clawhub:`. - - Options: - - - `--family skill|code-plugin|bundle-plugin` - filter package family. - - `--official` - show only official packages. - - `--executes-code` - show only packages that execute code. - - `--version ` / `--tag ` - inspect a specific package version. - - `--versions`, `--files`, `--file ` - inspect package history and files. - - `--json` - machine-readable output. - - - - ```bash - clawhub install - clawhub update - clawhub update --all - clawhub list - ``` - - Options: - - - `--version ` - install or update to a specific version (single slug only on `update`). - - `--force` - overwrite if the folder already exists, or when local files do not match any published version. - - `clawhub list` reads `.clawhub/lock.json`. - - - - ```bash - clawhub skill publish - ``` - - Options: - - - `--slug ` - skill slug. - - `--name ` - display name. - - `--version ` - semver version. - - `--changelog ` - changelog text (can be empty). - - `--tags ` - comma-separated tags (default: `latest`). - - - - ```bash - clawhub package publish - ``` - - `` can be a local folder, `owner/repo`, `owner/repo@ref`, or a - GitHub URL. - - Options: - - - `--dry-run` - build the exact publish plan without uploading anything. - - `--json` - emit machine-readable output for CI. - - `--source-repo`, `--source-commit`, `--source-ref` - optional overrides when auto-detection is not enough. - - - - ```bash - clawhub skill rescan - clawhub skill rescan --yes --json - - clawhub package rescan - clawhub package rescan --yes --json - ``` - - Rescan commands require a logged-in owner token and target the latest - published skill version or plugin release. In non-interactive runs, pass - `--yes`. - - JSON responses include the target kind, name, version, rescan status, and - remaining/max request counts for that version or release. - - - - ```bash - clawhub delete --yes - clawhub undelete --yes - ``` - - - ```bash - clawhub sync - ``` - - Options: - - - `--root ` - extra scan roots. - - `--all` - upload everything without prompts. - - `--dry-run` - show what would be uploaded. - - `--bump ` - `patch|minor|major` for updates (default: `patch`). - - `--changelog ` - changelog for non-interactive updates. - - `--tags ` - comma-separated tags (default: `latest`). - - `--concurrency ` - registry checks (default: `4`). - - - - -## Common workflows - - - - ```bash - clawhub search "postgres backups" - ``` - - - ```bash - clawhub package explore --family code-plugin - clawhub package explore "memory" --family code-plugin - clawhub package inspect episodic-claw - ``` - - - ```bash - clawhub install my-skill-pack - ``` - - - ```bash - clawhub update --all - ``` - - - ```bash - clawhub skill publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest - ``` - - - ```bash - clawhub sync --all - ``` - - - ```bash - clawhub package publish your-org/your-plugin --dry-run - clawhub package publish your-org/your-plugin - clawhub package publish your-org/your-plugin@v1.0.0 - clawhub package publish https://github.com/your-org/your-plugin - ``` - - - -### Plugin package metadata - -Code plugins must include the required OpenClaw metadata in -`package.json`: - -```json -{ - "name": "@myorg/openclaw-my-plugin", - "version": "1.0.0", - "type": "module", - "openclaw": { - "extensions": ["./src/index.ts"], - "runtimeExtensions": ["./dist/index.js"], - "compat": { - "pluginApi": ">=2026.3.24-beta.2", - "minGatewayVersion": "2026.3.24-beta.2" - }, - "build": { - "openclawVersion": "2026.3.24-beta.2", - "pluginSdkVersion": "2026.3.24-beta.2" - } - } -} -``` - -Published packages should ship **built JavaScript** and point -`runtimeExtensions` at that output. Git checkout installs can still fall -back to TypeScript source when no built files exist, but built runtime -entries avoid runtime TypeScript compilation in startup, doctor, and -plugin loading paths. - -## Versioning, lockfile, and telemetry - - - - - Each publish creates a new **semver** `SkillVersion`. - - Tags (like `latest`) point to a version; moving tags lets you roll back. - - Changelogs are attached per version and can be empty when syncing or publishing updates. - - - - Updates compare the local skill contents to registry versions using a - content hash. If local files do not match any published version, the - CLI asks before overwriting (or requires `--force` in - non-interactive runs). - - - `clawhub sync` scans your current workdir first. If no skills are - found, it falls back to known legacy locations (for example - `~/openclaw/skills` and `~/.openclaw/skills`). This is designed to - find older skill installs without extra flags. - - - - Installed skills are recorded in `.clawhub/lock.json` under your workdir. - - Auth tokens are stored in the ClawHub CLI config file (override via `CLAWHUB_CONFIG_PATH`). - - - - When you run `clawhub sync` while logged in, the CLI sends a minimal - snapshot to compute install counts. You can disable this entirely: - - ```bash - export CLAWHUB_DISABLE_TELEMETRY=1 - ``` - - - - -## Environment variables - -| Variable | Effect | -| ----------------------------- | ----------------------------------------------- | -| `CLAWHUB_SITE` | Override the site URL. | -| `CLAWHUB_REGISTRY` | Override the registry API URL. | -| `CLAWHUB_CONFIG_PATH` | Override where the CLI stores the token/config. | -| `CLAWHUB_WORKDIR` | Override the default workdir. | -| `CLAWHUB_DISABLE_TELEMETRY=1` | Disable telemetry on `sync`. | - -## Related - -- [Community plugins](/plugins/community) -- [Plugins](/tools/plugin) -- [Skills](/tools/skills) diff --git a/docs/tools/creating-skills.md b/docs/tools/creating-skills.md index 624c0e223..d23b1caff 100644 --- a/docs/tools/creating-skills.md +++ b/docs/tools/creating-skills.md @@ -116,5 +116,5 @@ The YAML frontmatter supports these fields: - [Skills reference](/tools/skills) — loading, precedence, and gating rules - [Skills config](/tools/skills-config) — `skills.*` config schema -- [ClawHub](/tools/clawhub) — public skill registry +- [ClawHub](/clawhub) — public skill registry - [Building Plugins](/plugins/building-plugins) — plugins can ship skills diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index e5c70c1e8..2dfe5f3d1 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -13,7 +13,7 @@ agent harnesses, tools, skills, speech, realtime transcription, realtime voice, media-understanding, image generation, video generation, web fetch, web search, and more. Some plugins are **core** (shipped with OpenClaw), others are **external**. Most external plugins are published and discovered through -[ClawHub](/tools/clawhub). Npm remains supported for direct installs and for a +[ClawHub](/clawhub). Npm remains supported for direct installs and for a temporary set of OpenClaw-owned plugin packages while that migration finishes. ## Quick start @@ -279,7 +279,7 @@ current OpenClaw or a local checkout until a newer npm package is published. -Looking for third-party plugins? See [Community Plugins](/plugins/community). +Looking for third-party plugins? See [ClawHub](/clawhub). ## Configuration @@ -728,4 +728,4 @@ For full typed hook behavior, see [SDK overview](/plugins/sdk-overview#hook-deci - [Plugin manifest](/plugins/manifest) - manifest schema - [Registering tools](/plugins/building-plugins#registering-agent-tools) - add agent tools in a plugin - [Plugin internals](/plugins/architecture) - capability model and load pipeline -- [Community plugins](/plugins/community) - third-party listings +- [ClawHub](/clawhub) - third-party plugin discovery diff --git a/docs/tools/skills.md b/docs/tools/skills.md index 626cde60d..6e5fe577d 100644 --- a/docs/tools/skills.md +++ b/docs/tools/skills.md @@ -125,7 +125,7 @@ its proposals. Full guide: [Skill Workshop plugin](/plugins/skill-workshop). [ClawHub](https://clawhub.ai) is the public skills registry for OpenClaw. Use native `openclaw skills` commands for discover/install/update, or the separate `clawhub` CLI for publish/sync workflows. Full guide: -[ClawHub](/tools/clawhub). +[ClawHub](/clawhub). | Action | Command | | ---------------------------------- | -------------------------------------- | @@ -475,7 +475,7 @@ schema: [Skills config](/tools/skills-config). ## Related -- [ClawHub](/tools/clawhub) - public skills registry +- [ClawHub](/clawhub) - public skills registry - [Creating skills](/tools/creating-skills) - building custom skills - [Plugins](/tools/plugin) - plugin system overview - [Skill Workshop plugin](/plugins/skill-workshop) - generate skills from agent work