chore(sync): mirror docs from openclaw/openclaw@10f9a758b6
This commit is contained in:
openclaw-docs-sync[bot]
parent
15ea487772
commit
97ccb272b8
@ -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"
|
||||
}
|
||||
|
||||
@ -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"
|
||||
]
|
||||
},
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
68
docs/clawhub/acceptable-usage.md
Normal file
68
docs/clawhub/acceptable-usage.md
Normal file
@ -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.
|
||||
118
docs/clawhub/api.md
Normal file
118
docs/clawhub/api.md
Normal file
@ -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/<owner>/<slug>`.
|
||||
- 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`.
|
||||
73
docs/clawhub/auth.md
Normal file
73
docs/clawhub/auth.md
Normal file
@ -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.
|
||||
558
docs/clawhub/cli.md
Normal file
558
docs/clawhub/cli.md
Normal file
@ -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 <dir>`: working directory (default: cwd; falls back to Clawdbot workspace if configured)
|
||||
- `--dir <dir>`: install dir under workdir (default: `skills`)
|
||||
- `--site <url>`: base URL for browser login (default: `https://clawhub.ai`)
|
||||
- `--registry <url>`: 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 `<site>/cli/auth` and completes via loopback callback.
|
||||
- Headless: `clawhub login --token clh_...`
|
||||
|
||||
### `whoami`
|
||||
|
||||
- Verifies the stored token via `/api/v1/whoami`.
|
||||
|
||||
### `star <slug>` / `unstar <slug>`
|
||||
|
||||
- Adds/removes a skill from your highlights.
|
||||
- Calls `POST /api/v1/stars/<slug>` and `DELETE /api/v1/stars/<slug>`.
|
||||
- `--yes` skips confirmation.
|
||||
|
||||
### `search <query...>`
|
||||
|
||||
- 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 <slug>` 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 <n>` (1-200, default: 25)
|
||||
- `--sort newest|updated|downloads|rating|installs|installsAllTime|trending` (default: newest)
|
||||
- `--json` (machine-readable output)
|
||||
- Output: `<slug> v<version> <age> <summary>` (summary truncated to 50 chars).
|
||||
|
||||
### `inspect <slug>`
|
||||
|
||||
- Fetches skill metadata and version files without installing.
|
||||
- `--version <version>`: inspect a specific version (default: latest).
|
||||
- `--tag <tag>`: inspect a tagged version (e.g. `latest`).
|
||||
- `--versions`: list version history (first page).
|
||||
- `--limit <n>`: max versions to list (1-200).
|
||||
- `--files`: list files for the selected version.
|
||||
- `--file <path>`: fetch raw file content (text files only; 200KB limit).
|
||||
- `--json`: machine-readable output.
|
||||
|
||||
### `install <slug>`
|
||||
|
||||
- Resolves latest version via `/api/v1/skills/<slug>`.
|
||||
- Downloads zip via `/api/v1/download`.
|
||||
- Extracts into `<workdir>/<dir>/<slug>`.
|
||||
- Writes:
|
||||
- `<workdir>/.clawhub/lock.json` (legacy `.clawdhub`)
|
||||
- `<skill>/.clawhub/origin.json` (legacy `.clawdhub`)
|
||||
|
||||
### `uninstall <slug>`
|
||||
|
||||
- Removes `<workdir>/<dir>/<slug>` and deletes the lockfile entry.
|
||||
- Interactive: asks for confirmation.
|
||||
- Non-interactive (`--no-input`): requires `--yes`.
|
||||
|
||||
### `list`
|
||||
|
||||
- Reads `<workdir>/.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 <path>`
|
||||
|
||||
- Publishes via `POST /api/v1/skills` (multipart).
|
||||
- Requires semver: `--version 1.2.3`.
|
||||
- `--owner <handle>` 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 <path>`.
|
||||
|
||||
### `delete <slug>`
|
||||
|
||||
- Soft-delete a skill (owner, moderator, or admin).
|
||||
- Calls `DELETE /api/v1/skills/{slug}`.
|
||||
- `--reason <text>` records a moderation note on the skill and audit log.
|
||||
- `--note <text>` is an alias for `--reason`.
|
||||
- `--yes` skips confirmation.
|
||||
|
||||
### `undelete <slug>`
|
||||
|
||||
- Restore a hidden skill (owner, moderator, or admin).
|
||||
- Calls `POST /api/v1/skills/{slug}/undelete`.
|
||||
- `--reason <text>` records a moderation note on the skill and audit log.
|
||||
- `--note <text>` is an alias for `--reason`.
|
||||
- `--yes` skips confirmation.
|
||||
|
||||
### `hide <slug>`
|
||||
|
||||
- Hide a skill (owner, moderator, or admin).
|
||||
- Alias for `delete`.
|
||||
|
||||
### `unhide <slug>`
|
||||
|
||||
- Unhide a skill (owner, moderator, or admin).
|
||||
- Alias for `undelete`.
|
||||
|
||||
### `skill rename <slug> <new-slug>`
|
||||
|
||||
- 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 <source-slug> <target-slug>`
|
||||
|
||||
- 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 <slug> <handle> [--message "..."] [--yes]`
|
||||
- `transfer list [--outgoing]`
|
||||
- `transfer accept <slug> [--yes]`
|
||||
- `transfer reject <slug> [--yes]`
|
||||
- `transfer cancel <slug> [--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 <target>`, `--os <os>`, `--arch <arch>`, `--libc <libc>`
|
||||
- `--requires-browser`, `--requires-desktop`, `--requires-native-deps`
|
||||
- `--requires-external-service`, `--external-service <name>`
|
||||
- `--binary <name>`, `--os-permission <name>`
|
||||
- `--artifact-kind legacy-zip|npm-pack`
|
||||
- `--npm-mirror`
|
||||
- `--limit <n>` (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 <name>`
|
||||
|
||||
- Fetches package metadata without installing.
|
||||
- Use this for plugin metadata, compatibility, verification, source, and version/file inspection.
|
||||
- `--version <version>`: inspect a specific version (default: latest).
|
||||
- `--tag <tag>`: inspect a tagged version (e.g. `latest`).
|
||||
- `--versions`: list version history (first page).
|
||||
- `--limit <n>`: max versions to list (1-100).
|
||||
- `--files`: list files for the selected version.
|
||||
- `--file <path>`: fetch raw file content (text files only; 200KB limit).
|
||||
- `--json`: machine-readable output.
|
||||
|
||||
### `package download <name>`
|
||||
|
||||
- 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 <version>`: download a specific version.
|
||||
- `--tag <tag>`: download a tagged version (default: `latest`).
|
||||
- `-o, --output <path>`: 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 <file>`
|
||||
|
||||
- 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 <name>`: package name to resolve expected artifact metadata.
|
||||
- `--version <version>` or `--tag <tag>`: expected package version.
|
||||
- `--sha256 <hex>`: expected ClawHub SHA-256.
|
||||
- `--npm-integrity <sri>`: expected npm integrity.
|
||||
- `--npm-shasum <sha1>`: 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 <hex>
|
||||
```
|
||||
|
||||
### `package delete <name>`
|
||||
|
||||
- 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 <version>`: optional package version to attach to the report.
|
||||
- `--reason <text>`: 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 <version>`: required package version.
|
||||
- `--message <text>`: 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 <name>`
|
||||
|
||||
- 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 <name>`
|
||||
|
||||
- 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 <source>`
|
||||
|
||||
- Publishes a code plugin or bundle plugin via `POST /api/v1/packages`.
|
||||
- `<source>` 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 <handle>` 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 <dir...>` extra scan roots
|
||||
- `--all` upload without prompting
|
||||
- `--dry-run` show plan only
|
||||
- `--bump patch|minor|major` (default: patch)
|
||||
- `--changelog <text>` (non-interactive)
|
||||
- `--tags a,b,c` (default: latest)
|
||||
- `--concurrency <n>` (default: 4)
|
||||
|
||||
Telemetry:
|
||||
|
||||
- Sent during `sync` when logged in, unless `CLAWHUB_DISABLE_TELEMETRY=1` (legacy `CLAWDHUB_DISABLE_TELEMETRY=1`).
|
||||
- Details: `docs/telemetry.md`.
|
||||
102
docs/clawhub/how-it-works.md
Normal file
102
docs/clawhub/how-it-works.md
Normal file
@ -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:<package>
|
||||
```
|
||||
|
||||
## 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 <source> --family code-plugin --dry-run
|
||||
clawhub package publish <source> --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 <skill-slug>
|
||||
openclaw plugins install clawhub:<package>
|
||||
```
|
||||
|
||||
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).
|
||||
1361
docs/clawhub/http-api.md
Normal file
1361
docs/clawhub/http-api.md
Normal file
File diff suppressed because it is too large
Load Diff
177
docs/clawhub/index.md
Normal file
177
docs/clawhub/index.md
Normal file
@ -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 <skill-slug>
|
||||
openclaw skills update --all
|
||||
```
|
||||
|
||||
Search and install plugins with OpenClaw:
|
||||
|
||||
```bash
|
||||
openclaw plugins search "calendar"
|
||||
openclaw plugins install clawhub:<package>
|
||||
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 <slug>` |
|
||||
| Code plugins | OpenClaw plugin packages with compatibility metadata | `openclaw plugins install clawhub:<package>` |
|
||||
| Bundle plugins | Packaged plugin bundles for OpenClaw distribution | `clawhub package publish <source>` |
|
||||
| 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:<package>` when a plugin install should resolve through ClawHub.
|
||||
Bare npm-safe plugin specs may resolve through npm during launch cutovers, and
|
||||
`npm:<package>` 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 <slug>
|
||||
clawhub update <slug>
|
||||
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 <path>
|
||||
```
|
||||
|
||||
Common publish options:
|
||||
|
||||
- `--slug <slug>`: skill slug.
|
||||
- `--name <name>`: display name.
|
||||
- `--version <version>`: semver version.
|
||||
- `--changelog <text>`: changelog text.
|
||||
- `--tags <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 <source>
|
||||
```
|
||||
|
||||
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 <slug>
|
||||
clawhub package rescan <name>
|
||||
```
|
||||
|
||||
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.
|
||||
144
docs/clawhub/quickstart.md
Normal file
144
docs/clawhub/quickstart.md
Normal file
@ -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 <skill-slug>
|
||||
```
|
||||
|
||||
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:<package>
|
||||
```
|
||||
|
||||
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 <source> --family code-plugin --dry-run
|
||||
clawhub package publish <source> --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 <skill-slug>
|
||||
clawhub package inspect <package>
|
||||
```
|
||||
|
||||
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.
|
||||
BIN
docs/clawhub/screenshots/markdown-html-passthrough/after.png
Normal file
BIN
docs/clawhub/screenshots/markdown-html-passthrough/after.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
BIN
docs/clawhub/screenshots/markdown-html-passthrough/before.png
Normal file
BIN
docs/clawhub/screenshots/markdown-html-passthrough/before.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 394 KiB |
118
docs/clawhub/security.md
Normal file
118
docs/clawhub/security.md
Normal file
@ -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 <slug>
|
||||
clawhub package rescan <name>
|
||||
```
|
||||
|
||||
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
|
||||
191
docs/clawhub/skill-format.md
Normal file
191
docs/clawhub/skill-format.md
Normal file
@ -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):
|
||||
|
||||
- `<skill>/.clawhub/origin.json` (legacy `.clawdhub`)
|
||||
|
||||
Workdir install state (written by the CLI):
|
||||
|
||||
- `<workdir>/.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).
|
||||
37
docs/clawhub/soul-format.md
Normal file
37
docs/clawhub/soul-format.md
Normal file
@ -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.
|
||||
91
docs/clawhub/telemetry.md
Normal file
91
docs/clawhub/telemetry.md
Normal file
@ -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`.
|
||||
140
docs/clawhub/troubleshooting.md
Normal file
140
docs/clawhub/troubleshooting.md
Normal file
@ -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:<port>/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 <skill-slug>
|
||||
```
|
||||
|
||||
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 <source> --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 <slug> --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:<package>
|
||||
```
|
||||
|
||||
- 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.
|
||||
@ -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).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Hook packs and npm specs">
|
||||
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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"
|
||||
]
|
||||
},
|
||||
|
||||
@ -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/<name>/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/<name>/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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
@ -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:<package-name>`. Bare package specs still
|
||||
install from npm during the launch cutover.
|
||||
|
||||
|
||||
@ -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.
|
||||
<Steps>
|
||||
<Step title="Publish to ClawHub or npm">
|
||||
Your plugin must be installable via `openclaw plugins install \<package-name\>`.
|
||||
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.
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="npm">
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
<Steps>
|
||||
<Step title="Search">
|
||||
```bash
|
||||
openclaw skills search "calendar"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Install">
|
||||
```bash
|
||||
openclaw skills install <skill-slug>
|
||||
```
|
||||
</Step>
|
||||
<Step title="Use">
|
||||
Start a new OpenClaw session - it picks up the new skill.
|
||||
</Step>
|
||||
<Step title="Publish (optional)">
|
||||
For registry-authenticated workflows (publish, sync, manage), install
|
||||
the separate `clawhub` CLI:
|
||||
|
||||
```bash
|
||||
npm i -g clawhub
|
||||
# or
|
||||
pnpm add -g clawhub
|
||||
```
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Native OpenClaw flows
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Skills">
|
||||
```bash
|
||||
openclaw skills search "calendar"
|
||||
openclaw skills install <skill-slug>
|
||||
openclaw skills update --all
|
||||
```
|
||||
|
||||
Native `openclaw` commands install into your active workspace and
|
||||
persist source metadata so later `update` calls can stay on ClawHub.
|
||||
|
||||
</Tab>
|
||||
<Tab title="Plugins">
|
||||
```bash
|
||||
openclaw plugins search "calendar"
|
||||
openclaw plugins install clawhub:<package>
|
||||
openclaw plugins update --all
|
||||
```
|
||||
|
||||
`plugins search` queries the ClawHub plugin catalog and prints install-ready
|
||||
package names. Use `clawhub:<package>` 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:<package>` 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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`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 <slug>` 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.
|
||||
</Note>
|
||||
|
||||
## 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
|
||||
`<workspace>/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.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Security scans">
|
||||
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`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Reporting">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Moderation">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## ClawHub CLI
|
||||
|
||||
You only need this for registry-authenticated workflows such as
|
||||
publish/sync.
|
||||
|
||||
### Global options
|
||||
|
||||
<ParamField path="--workdir <dir>" type="string">
|
||||
Working directory. Default: current dir; falls back to OpenClaw workspace.
|
||||
</ParamField>
|
||||
<ParamField path="--dir <dir>" type="string" default="skills">
|
||||
Skills directory, relative to workdir.
|
||||
</ParamField>
|
||||
<ParamField path="--site <url>" type="string">
|
||||
Site base URL (browser login).
|
||||
</ParamField>
|
||||
<ParamField path="--registry <url>" type="string">
|
||||
Registry API base URL.
|
||||
</ParamField>
|
||||
<ParamField path="--no-input" type="boolean">
|
||||
Disable prompts (non-interactive).
|
||||
</ParamField>
|
||||
<ParamField path="-V, --cli-version" type="boolean">
|
||||
Print CLI version.
|
||||
</ParamField>
|
||||
|
||||
### Commands
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Auth (login / logout / whoami)">
|
||||
```bash
|
||||
clawhub login # browser flow
|
||||
clawhub login --token <token>
|
||||
clawhub logout
|
||||
clawhub whoami
|
||||
```
|
||||
|
||||
Login options:
|
||||
|
||||
- `--token <token>` - paste an API token.
|
||||
- `--label <label>` - label stored for browser login tokens (default: `CLI token`).
|
||||
- `--no-browser` - do not open a browser (requires `--token`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Search">
|
||||
```bash
|
||||
clawhub search "query"
|
||||
```
|
||||
|
||||
Searches skills. For plugin/package discovery, use `clawhub package explore`.
|
||||
|
||||
- `--limit <n>` - max results.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Browse / inspect plugins">
|
||||
```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:<package>`.
|
||||
|
||||
Options:
|
||||
|
||||
- `--family skill|code-plugin|bundle-plugin` - filter package family.
|
||||
- `--official` - show only official packages.
|
||||
- `--executes-code` - show only packages that execute code.
|
||||
- `--version <version>` / `--tag <tag>` - inspect a specific package version.
|
||||
- `--versions`, `--files`, `--file <path>` - inspect package history and files.
|
||||
- `--json` - machine-readable output.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Install / update / list">
|
||||
```bash
|
||||
clawhub install <slug>
|
||||
clawhub update <slug>
|
||||
clawhub update --all
|
||||
clawhub list
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--version <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`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Publish skills">
|
||||
```bash
|
||||
clawhub skill publish <path>
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--slug <slug>` - skill slug.
|
||||
- `--name <name>` - display name.
|
||||
- `--version <version>` - semver version.
|
||||
- `--changelog <text>` - changelog text (can be empty).
|
||||
- `--tags <tags>` - comma-separated tags (default: `latest`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Publish plugins">
|
||||
```bash
|
||||
clawhub package publish <source>
|
||||
```
|
||||
|
||||
`<source>` 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Request rescans">
|
||||
```bash
|
||||
clawhub skill rescan <slug>
|
||||
clawhub skill rescan <slug> --yes --json
|
||||
|
||||
clawhub package rescan <name>
|
||||
clawhub package rescan <name> --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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Delete / undelete (owner or admin)">
|
||||
```bash
|
||||
clawhub delete <slug> --yes
|
||||
clawhub undelete <slug> --yes
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Sync (scan local + publish new or updated)">
|
||||
```bash
|
||||
clawhub sync
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--root <dir...>` - extra scan roots.
|
||||
- `--all` - upload everything without prompts.
|
||||
- `--dry-run` - show what would be uploaded.
|
||||
- `--bump <type>` - `patch|minor|major` for updates (default: `patch`).
|
||||
- `--changelog <text>` - changelog for non-interactive updates.
|
||||
- `--tags <tags>` - comma-separated tags (default: `latest`).
|
||||
- `--concurrency <n>` - registry checks (default: `4`).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Common workflows
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Search">
|
||||
```bash
|
||||
clawhub search "postgres backups"
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Find a plugin">
|
||||
```bash
|
||||
clawhub package explore --family code-plugin
|
||||
clawhub package explore "memory" --family code-plugin
|
||||
clawhub package inspect episodic-claw
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Install">
|
||||
```bash
|
||||
clawhub install my-skill-pack
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Update all">
|
||||
```bash
|
||||
clawhub update --all
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Publish a single skill">
|
||||
```bash
|
||||
clawhub skill publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Sync many skills">
|
||||
```bash
|
||||
clawhub sync --all
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Publish a plugin from GitHub">
|
||||
```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
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 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
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Versioning and tags">
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Local changes vs registry versions">
|
||||
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).
|
||||
</Accordion>
|
||||
<Accordion title="Sync scanning and fallback roots">
|
||||
`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.
|
||||
</Accordion>
|
||||
<Accordion title="Storage and lockfile">
|
||||
- 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`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Telemetry (install counts)">
|
||||
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
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user