mirror of
https://github.com/openclaw/clawhub.git
synced 2026-08-14 00:47:57 +00:00
docs: split ClawHub public docs from specs (#2095)
* docs: split clawhub docs source * docs: make clawhub docs product-facing * docs: refine public clawhub docs routes
This commit is contained in:
Patrick Erichsen
+1
-1
@@ -109,8 +109,8 @@
|
||||
/docs/api.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/docs/auth.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/docs/deploy.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/docs/github-import.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/docs/http-api.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/docs/security.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/docs/webhook.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/specs/github-import.md @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
/public/api/v1/openapi.json @openclaw/openclaw-secops @Patrick-Erichsen
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
name: OpenClaw Docs Sync Dispatch
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- docs/**
|
||||
- .github/workflows/openclaw-docs-sync-dispatch.yml
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
dispatch-openclaw-docs-sync:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Dispatch OpenClaw docs sync
|
||||
env:
|
||||
OPENCLAW_DOCS_SYNC_TOKEN: ${{ secrets.OPENCLAW_DOCS_SYNC_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
if [ -z "${OPENCLAW_DOCS_SYNC_TOKEN:-}" ]; then
|
||||
echo "::error::OPENCLAW_DOCS_SYNC_TOKEN is required to dispatch openclaw/openclaw docs sync."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
curl --fail-with-body --silent --show-error \
|
||||
--request POST \
|
||||
--header "Authorization: Bearer ${OPENCLAW_DOCS_SYNC_TOKEN}" \
|
||||
--header "Accept: application/vnd.github+json" \
|
||||
--header "X-GitHub-Api-Version: 2022-11-28" \
|
||||
https://api.github.com/repos/openclaw/openclaw/actions/workflows/docs-sync-publish.yml/dispatches \
|
||||
--data '{"ref":"main"}'
|
||||
@@ -5,9 +5,17 @@
|
||||
- `src/` — TanStack Start app code (routes, components, styles).
|
||||
- `convex/` — Convex backend (schema, queries/mutations/actions, HTTP routes).
|
||||
- `convex/_generated/` — generated Convex API/types; committed for builds.
|
||||
- `docs/` — product/spec docs (see `docs/spec.md`).
|
||||
- `docs/` — publishable public/operator docs for the ClawHub docs tab.
|
||||
- `specs/` — product specs, plans, regression notes, design history (see `specs/spec.md`).
|
||||
- `public/` — static assets.
|
||||
|
||||
## Durable Intent & Specs
|
||||
|
||||
- Use `specs/` to persist system/subsystem intent, invariants, and design rationale that future agents should preserve.
|
||||
- Keep intended behavior for security-sensitive flows there, especially moderation, upload gating, scanner outcomes, appeals, bans, ownership, package installability, and API trust boundaries.
|
||||
- If code changes reveal or change how a subsystem is supposed to work, update the relevant spec or add a focused spec note instead of burying the intent only in PR text or public docs.
|
||||
- Keep `docs/` user/operator-facing: explain current behavior and commands there, but put internal “why this must work this way” context in `specs/`.
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
|
||||
- `bun run dev` — local app server at `http://localhost:3000`.
|
||||
|
||||
+10
-9
@@ -128,7 +128,7 @@ bun run --cwd packages/clawhub verify
|
||||
|
||||
`bun test packages/clawhub/` is not the supported workflow. Source tests and built-artifact smoke tests are intentionally split.
|
||||
|
||||
Manual smoke tests are documented in [`docs/manual-testing.md`](docs/manual-testing.md).
|
||||
Manual smoke tests are documented in [`specs/manual-testing.md`](specs/manual-testing.md).
|
||||
|
||||
## Skill & Soul Publishing
|
||||
|
||||
@@ -208,11 +208,12 @@ See [`docs/security.md`](docs/security.md) for moderation and upload gating deta
|
||||
## Reading Order for New Contributors
|
||||
|
||||
1. This file (local setup)
|
||||
2. [`docs/quickstart.md`](docs/quickstart.md) — end-to-end workflows
|
||||
3. [`docs/architecture.md`](docs/architecture.md) — system design
|
||||
4. [`docs/skill-format.md`](docs/skill-format.md) — skill structure
|
||||
5. [`docs/cli.md`](docs/cli.md) — CLI reference
|
||||
6. [`docs/http-api.md`](docs/http-api.md) — HTTP endpoints
|
||||
7. [`docs/auth.md`](docs/auth.md) — authentication
|
||||
8. [`docs/deploy.md`](docs/deploy.md) — deployment
|
||||
9. [`docs/troubleshooting.md`](docs/troubleshooting.md) — common issues
|
||||
2. [`docs/clawhub.md`](docs/clawhub.md) — public registry overview
|
||||
3. [`docs/quickstart.md`](docs/quickstart.md) — end-to-end workflows
|
||||
4. [`docs/architecture.md`](docs/architecture.md) — system design
|
||||
5. [`docs/skill-format.md`](docs/skill-format.md) — skill structure
|
||||
6. [`docs/cli.md`](docs/cli.md) — CLI reference
|
||||
7. [`docs/http-api.md`](docs/http-api.md) — HTTP endpoints
|
||||
8. [`docs/auth.md`](docs/auth.md) — authentication
|
||||
9. [`docs/deploy.md`](docs/deploy.md) — deployment
|
||||
10. [`docs/troubleshooting.md`](docs/troubleshooting.md) — common issues
|
||||
|
||||
@@ -20,7 +20,7 @@ onlycrabs.ai is the **SOUL.md registry**: publish and share system lore the same
|
||||
<a href="https://clawhub.ai">ClawHub</a> ·
|
||||
<a href="https://onlycrabs.ai">onlycrabs.ai</a> ·
|
||||
<a href="VISION.md">Vision</a> ·
|
||||
<a href="docs/README.md">Docs</a> ·
|
||||
<a href="docs/clawhub.md">Docs</a> ·
|
||||
<a href="CONTRIBUTING.md">Contributing</a> ·
|
||||
<a href="https://discord.gg/clawd">Discord</a>
|
||||
</p>
|
||||
@@ -93,8 +93,9 @@ Details: [`docs/telemetry.md`](docs/telemetry.md).
|
||||
- `src/` — TanStack Start app (routes, components, styles).
|
||||
- `convex/` — schema + queries/mutations/actions + HTTP API routes.
|
||||
- `packages/schema/` — shared API types/routes for the CLI and app.
|
||||
- [`docs/`](docs/README.md) — project documentation (architecture, CLI, auth, deployment, and more).
|
||||
- [`docs/spec.md`](docs/spec.md) — product + implementation spec (good first read).
|
||||
- [`docs/`](docs/README.md) — publishable ClawHub public/operator docs for users, publishers, API clients, and deploy operators.
|
||||
- [`specs/`](specs/README.md) — product specs, plans, regression notes, and design history.
|
||||
- [`specs/spec.md`](specs/spec.md) — product + implementation spec (good first read for maintainers).
|
||||
|
||||
## Local dev
|
||||
|
||||
|
||||
+38
-23
@@ -1,34 +1,49 @@
|
||||
---
|
||||
summary: "Documentation index + reading order."
|
||||
summary: "Public ClawHub docs index and reading order."
|
||||
read_when:
|
||||
- New contributor onboarding
|
||||
- Looking for the right doc
|
||||
- Looking for the right public ClawHub doc
|
||||
- Deciding whether content belongs in public docs or specs
|
||||
---
|
||||
|
||||
# Docs
|
||||
|
||||
Reading order (new contributor):
|
||||
`docs/` is the publishable source for user-facing ClawHub pages that can be
|
||||
mirrored into the `ClawHub` tab on `docs.openclaw.ai`.
|
||||
|
||||
1. `README.md` (repo root): run locally.
|
||||
2. `docs/quickstart.md`: end-to-end: search → install → publish → sync.
|
||||
3. `docs/architecture.md`: how the pieces fit (TanStack Start + Convex + CLI).
|
||||
4. `docs/skill-format.md`: what a “skill” is on disk + on the registry.
|
||||
5. `docs/cli.md`: CLI reference (flags, config, lockfiles, sync rules).
|
||||
6. `docs/http-api.md`: HTTP endpoints used by the CLI + public API.
|
||||
7. `docs/auth.md`: GitHub OAuth + API tokens + CLI loopback login.
|
||||
8. `docs/deploy.md`: Convex + Vercel deployment + rewrites.
|
||||
9. `docs/troubleshooting.md`: common failure modes.
|
||||
Keep product, CLI, publisher, API, policy, security, and troubleshooting docs
|
||||
here. These pages should explain how people use ClawHub: discover, install,
|
||||
publish, inspect, report, moderate, and integrate with the registry.
|
||||
|
||||
Feature/ops docs (already present):
|
||||
Use `specs/` for repository setup, production deploy runbooks, implementation
|
||||
plans, design rationale, regression notes, maintainer validation records, and
|
||||
internal subsystem intent. If a page tells someone how to run or deploy the
|
||||
ClawHub project itself, it belongs in `specs/`, not in the public OpenClaw docs
|
||||
tab.
|
||||
|
||||
- `docs/spec.md`: product + implementation spec (data model + flows).
|
||||
- `docs/security.md`: moderation, reporting, bans, upload gating.
|
||||
- `docs/telemetry.md`: what `clawhub sync` reports; opt-out.
|
||||
- `docs/webhook.md`: Discord webhook events/payload.
|
||||
- `docs/diffing.md`: version-to-version diff UI spec.
|
||||
- `docs/manual-testing.md`: CLI smoke scripts.
|
||||
- `docs/slug-routing.md`: skill/plugin slug redirects + package URL contract.
|
||||
Reading order:
|
||||
|
||||
Docs tooling:
|
||||
1. `docs/clawhub.md`: public overview for discovery, install, publish, and trust.
|
||||
2. `docs/quickstart.md`: product quickstart for users and publishers.
|
||||
3. `docs/how-it-works.md`: listings, versions, installs, publishing, scans, and API access.
|
||||
4. `docs/cli.md`: ClawHub CLI reference.
|
||||
5. `docs/skill-format.md`: skill bundle metadata and package shape.
|
||||
6. `docs/soul-format.md`: SOUL.md bundle format.
|
||||
7. `docs/auth.md`: GitHub OAuth, API tokens, and CLI login.
|
||||
8. `docs/telemetry.md`: what `clawhub sync` reports and how to opt out.
|
||||
9. `docs/troubleshooting.md`: user-facing CLI, install, publish, sync, update, and API fixes.
|
||||
|
||||
- `docs/mintlify.md`: publish these docs with Mintlify.
|
||||
Policy, API, and trust docs:
|
||||
|
||||
- `docs/acceptable-usage.md`: marketplace policy and enforcement boundaries.
|
||||
- `docs/api.md`: public REST API overview.
|
||||
- `docs/http-api.md`: detailed HTTP API reference.
|
||||
- `docs/security.md`: moderation, reporting, bans, upload gating, and scan outcomes.
|
||||
|
||||
Maintainer records:
|
||||
|
||||
- `specs/README.md`: index for specs, plans, deployment runbooks, webhook notes, regression notes, and design records.
|
||||
|
||||
Publish flow:
|
||||
|
||||
- Changes under `docs/` dispatch the OpenClaw docs sync workflow, which mirrors this directory into the `ClawHub` tab on `docs.openclaw.ai`.
|
||||
- `specs/` is intentionally not mirrored.
|
||||
|
||||
@@ -19,7 +19,7 @@ These rules are intentionally practical. We care most about end-to-end abuse wor
|
||||
- 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.
|
||||
- Docs, migration runbooks, local developer utilities, and test fixtures scoped to the repository they support.
|
||||
- Documentation, migration runbooks, developer utilities, and test fixtures scoped to the software they support.
|
||||
|
||||
## Not okay
|
||||
|
||||
|
||||
@@ -1,62 +0,0 @@
|
||||
---
|
||||
summary: "System overview: web app + Convex backend + CLI + shared schema."
|
||||
read_when:
|
||||
- Orienting in codebase
|
||||
- Tracing a user flow across layers
|
||||
---
|
||||
|
||||
# Architecture
|
||||
|
||||
## Pieces
|
||||
|
||||
- Web app: TanStack Start (React) under `src/`.
|
||||
- Backend: Convex under `convex/` (DB, storage, actions, HTTP routes).
|
||||
- CLI: `packages/clawhub/` (published as `clawhub`, legacy `clawdhub`).
|
||||
- Shared schemas/routes: `packages/schema/` (`clawhub-schema`).
|
||||
|
||||
## Data + storage
|
||||
|
||||
- Skill “bundle” = versioned set of text files stored in Convex `_storage`.
|
||||
- Metadata extracted from `SKILL.md` frontmatter.
|
||||
- Stats stored on `skills` (downloads, installs, stars, comments, …).
|
||||
|
||||
## Main flows
|
||||
|
||||
### Browse (web)
|
||||
|
||||
- Public skill pages use TanStack Start SSR loaders for first paint, then hydrate into live Convex data.
|
||||
- The rest of the UI reads skill metadata + latest version from Convex queries/actions.
|
||||
- `SKILL.md` rendered as Markdown.
|
||||
|
||||
### Search (HTTP)
|
||||
|
||||
- `/api/v1/search?q=...` routes to Convex action for vector search.
|
||||
- Embeddings currently generated during publish.
|
||||
|
||||
### Install (CLI)
|
||||
|
||||
- Resolve latest version via `/api/v1/skills/<slug>`.
|
||||
- Download zip via `/api/v1/download?slug=...&version=...`.
|
||||
- Extract into `./skills/<slug>` (default).
|
||||
- Persist install state:
|
||||
- `./.clawhub/lock.json` (per workdir, legacy `.clawdhub`)
|
||||
- `./skills/<slug>/.clawhub/origin.json` (per skill folder, legacy `.clawdhub`)
|
||||
|
||||
### Update (CLI)
|
||||
|
||||
- Hash local files, call `/api/v1/resolve?slug=...&hash=<sha256>`.
|
||||
- If local matches a known version → use that for “current”.
|
||||
- If local doesn’t match:
|
||||
- refuse by default
|
||||
- or overwrite with `--force`
|
||||
|
||||
### Publish (CLI)
|
||||
|
||||
- Publish via `POST /api/v1/skills` (multipart; requires Bearer token).
|
||||
|
||||
### Sync (CLI)
|
||||
|
||||
- Scan roots for skill folders (contain `SKILL.md`).
|
||||
- Compute fingerprint; compare to registry state.
|
||||
- Optionally reports telemetry (see `docs/telemetry.md`).
|
||||
- Publishes new/changed skills (skips modified installed skills inside install root).
|
||||
+45
-33
@@ -1,61 +1,73 @@
|
||||
---
|
||||
summary: "Auth overview: GitHub OAuth (web) + API tokens (CLI)."
|
||||
summary: "ClawHub sign-in, API tokens, CLI login, token storage, and revocation."
|
||||
read_when:
|
||||
- Working on login/token flows
|
||||
- Signing in to ClawHub
|
||||
- Using the ClawHub CLI
|
||||
- Debugging 401s
|
||||
---
|
||||
|
||||
# Auth
|
||||
|
||||
## Web auth (GitHub OAuth)
|
||||
ClawHub uses GitHub for web sign-in. The CLI uses ClawHub API tokens created
|
||||
through that signed-in account.
|
||||
|
||||
- Convex Auth + GitHub OAuth App.
|
||||
- GitHub is the only supported login provider.
|
||||
- Disabled/banned accounts are blocked during OAuth completion and should surface a user-facing reason instead of a generic auth failure.
|
||||
- If OAuth returns without creating a session, the UI should tell users that deleted, banned, or disabled ClawHub accounts cannot sign in instead of silently returning to a logged-out state.
|
||||
- Env vars:
|
||||
- `AUTH_GITHUB_ID`
|
||||
- `AUTH_GITHUB_SECRET`
|
||||
- `CONVEX_SITE_URL` (used by auth config)
|
||||
## Web sign-in
|
||||
|
||||
Local setup steps are in the repo root `README.md`.
|
||||
Use GitHub to sign in at [clawhub.ai](https://clawhub.ai).
|
||||
|
||||
## API tokens (CLI)
|
||||
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.
|
||||
|
||||
The CLI uses a long-lived API token (Bearer token) for publish/sync/delete.
|
||||
## CLI login
|
||||
|
||||
### Browser flow (default)
|
||||
The default CLI login flow opens your browser:
|
||||
|
||||
`clawhub login` does:
|
||||
```bash
|
||||
clawhub login
|
||||
clawhub whoami
|
||||
```
|
||||
|
||||
1. Starts a loopback HTTP server on `127.0.0.1` (random port).
|
||||
2. Opens `<site>/cli/auth?redirect_uri=http://127.0.0.1:<port>/callback&state=...`.
|
||||
3. Web UI requires GitHub login, then creates a token and redirects back to the loopback server.
|
||||
4. CLI stores the token in the global config file.
|
||||
What happens:
|
||||
|
||||
### Headless flow
|
||||
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.
|
||||
|
||||
Create a token in the web UI (Settings → API tokens) and paste it:
|
||||
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_...
|
||||
```
|
||||
|
||||
### Token storage
|
||||
Use this flow for servers, CI jobs, or terminal-only environments.
|
||||
|
||||
Default global config path:
|
||||
## 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:
|
||||
Override the path with:
|
||||
|
||||
- `CLAWHUB_CONFIG_PATH=/path/to/config.json` (legacy `CLAWDHUB_CONFIG_PATH`)
|
||||
```bash
|
||||
export CLAWHUB_CONFIG_PATH=/path/to/config.json
|
||||
```
|
||||
|
||||
### Revocation
|
||||
## Revocation
|
||||
|
||||
- Tokens can be revoked in the web UI.
|
||||
- Revoked tokens return `401 Unauthorized` on CLI endpoints.
|
||||
- CLI/API auth failures should use actionable text, not a bare status word:
|
||||
missing tokens should point to `clawhub login`, revoked/invalid tokens should
|
||||
ask the user to log in again, and deleted/banned/disabled accounts should say
|
||||
that the ClawHub account is not in good standing and cannot use API tokens.
|
||||
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.
|
||||
|
||||
+177
@@ -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](./cli.md) for the full command
|
||||
reference and [Skill format](./skill-format.md) 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](./acceptable-usage.md) and
|
||||
[Security + moderation](./security.md) 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](./telemetry.md), [HTTP API](./http-api.md), and
|
||||
[Troubleshooting](./troubleshooting.md) for deeper reference material.
|
||||
+17
-9
@@ -1,20 +1,28 @@
|
||||
---
|
||||
summary: "CLI reference: commands, flags, config, lockfile, sync behavior."
|
||||
read_when:
|
||||
- Working on CLI behavior
|
||||
- Debugging install/update/sync
|
||||
- Using the ClawHub CLI
|
||||
- Debugging install, update, publish, or sync
|
||||
---
|
||||
|
||||
# CLI
|
||||
|
||||
CLI package: `packages/clawhub/` (published as `clawhub`, bin: `clawhub`).
|
||||
Platform moderator commands live in the private `packages/clawhub-mod/` package
|
||||
and are not part of the public npm CLI.
|
||||
CLI package: `clawhub`, bin: `clawhub`.
|
||||
|
||||
From this repo you can run it via the wrapper script:
|
||||
Install it globally with npm or pnpm:
|
||||
|
||||
```bash
|
||||
bun clawhub --help
|
||||
npm i -g clawhub
|
||||
# or
|
||||
pnpm add -g clawhub
|
||||
```
|
||||
|
||||
Then verify it:
|
||||
|
||||
```bash
|
||||
clawhub --help
|
||||
clawhub login
|
||||
clawhub whoami
|
||||
```
|
||||
|
||||
## Global flags
|
||||
@@ -310,8 +318,8 @@ clawhub package delete @openclaw/example-plugin --yes
|
||||
|
||||
- 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 feed
|
||||
`clawhub-mod package moderation-queue`.
|
||||
- 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.
|
||||
|
||||
@@ -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](./skill-format.md).
|
||||
|
||||
## 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](./security.md) and
|
||||
[Acceptable usage](./acceptable-usage.md).
|
||||
|
||||
## 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](./api.md) and [HTTP API](./http-api.md).
|
||||
+6
-7
@@ -9,7 +9,7 @@ read_when:
|
||||
|
||||
Base URL: `https://clawhub.ai` (default).
|
||||
|
||||
All v1 paths are under `/api/v1/...` and implemented by Convex HTTP routes (`convex/http.ts`).
|
||||
All v1 paths are under `/api/v1/...`.
|
||||
Legacy `/api/...` and `/api/cli/...` remain for compatibility (see `DEPRECATIONS.md`).
|
||||
OpenAPI: `/api/v1/openapi.json`.
|
||||
|
||||
@@ -17,9 +17,9 @@ OpenAPI: `/api/v1/openapi.json`.
|
||||
|
||||
Third-party directories may use the public read endpoints to list or search ClawHub skills. Please cache results, honor `429`/`Retry-After`, link users back to the canonical ClawHub listing (`https://clawhub.ai/<owner>/<slug>`), and avoid implying ClawHub endorsement of the third-party site. Do not attempt to mirror hidden, private, or moderation-blocked content outside the public API surface.
|
||||
|
||||
Web slug shortcuts resolve across registry families. See `docs/slug-routing.md`
|
||||
for the route precedence, collision policy, and official OpenClaw extension
|
||||
alias contract.
|
||||
Web slug shortcuts resolve across registry families, but API clients should use
|
||||
the canonical URLs returned by read endpoints instead of reconstructing route
|
||||
precedence.
|
||||
|
||||
## Rate limits
|
||||
|
||||
@@ -74,9 +74,8 @@ Client guidance:
|
||||
IP source:
|
||||
|
||||
- Uses `cf-connecting-ip` (Cloudflare) for client IP by default.
|
||||
- Set `TRUST_FORWARDED_IPS=true` to opt in to `x-forwarded-for`, `x-real-ip`, or `fly-client-ip` (non-Cloudflare deployments).
|
||||
- If no trusted client IP is available, anonymous download requests use an endpoint-scoped fallback bucket instead of one global `ip:unknown` bucket. Anonymous read/write requests still use the shared unknown bucket so missing-IP deployments remain visible and conservative.
|
||||
- If you run behind a reverse proxy/load balancer, ensure real client IP headers are preserved and trusted correctly, or rate limits may be too strict due to shared proxy IPs.
|
||||
- ClawHub uses trusted forwarding headers to identify client IPs at the edge.
|
||||
- If no trusted client IP is available, anonymous download requests use an endpoint-scoped fallback bucket instead of one global `ip:unknown` bucket. Anonymous read/write requests still use the shared unknown bucket so missing-IP routing remains visible and conservative.
|
||||
|
||||
## Public endpoints (no auth)
|
||||
|
||||
|
||||
+88
-116
@@ -1,172 +1,144 @@
|
||||
---
|
||||
summary: "Local setup + CLI smoke: login, search, install, publish, sync."
|
||||
summary: "Start using ClawHub: find, install, update, and publish skills or plugins."
|
||||
read_when:
|
||||
- First run / local dev setup
|
||||
- Verifying end-to-end flows
|
||||
- First time using ClawHub
|
||||
- Installing a skill or plugin from the registry
|
||||
- Publishing to ClawHub
|
||||
---
|
||||
|
||||
# Quickstart
|
||||
|
||||
## 0) Prereqs
|
||||
ClawHub is a registry for OpenClaw skills and plugins.
|
||||
|
||||
- Bun
|
||||
- Convex CLI (`bunx convex ...`)
|
||||
- GitHub OAuth App (for login)
|
||||
- OpenAI key (for embeddings/search)
|
||||
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.
|
||||
|
||||
## 1) Local dev (web + Convex)
|
||||
## Find and install a skill
|
||||
|
||||
Search from OpenClaw:
|
||||
|
||||
```bash
|
||||
bun install
|
||||
cp .env.local.example .env.local
|
||||
|
||||
# terminal A
|
||||
bun run dev
|
||||
|
||||
# terminal B
|
||||
bunx convex dev
|
||||
openclaw skills search "calendar"
|
||||
```
|
||||
|
||||
## 2) Auth setup (GitHub OAuth + Convex Auth keys)
|
||||
|
||||
Fill in `.env.local`:
|
||||
|
||||
- `AUTH_GITHUB_ID`
|
||||
- `AUTH_GITHUB_SECRET`
|
||||
- `VITE_CONVEX_URL`
|
||||
- `VITE_CONVEX_SITE_URL`
|
||||
- `CONVEX_SITE_URL` (same as `VITE_CONVEX_SITE_URL`)
|
||||
- `OPENAI_API_KEY`
|
||||
|
||||
Generate Convex Auth keys for your deployment:
|
||||
Install a skill:
|
||||
|
||||
```bash
|
||||
bunx auth --deployment-name <deployment> --web-server-url http://localhost:3000
|
||||
openclaw skills install <skill-slug>
|
||||
```
|
||||
|
||||
Then paste the printed `JWT_PRIVATE_KEY` + `JWKS` into `.env.local` (and ensure the deployment got them too).
|
||||
|
||||
## 3) CLI: login + basic commands
|
||||
|
||||
From this repo:
|
||||
Update installed skills:
|
||||
|
||||
```bash
|
||||
bun clawhub --help
|
||||
bun clawhub login
|
||||
bun clawhub whoami
|
||||
bun clawhub search gif --limit 5
|
||||
openclaw skills update --all
|
||||
```
|
||||
|
||||
Install a skill into `./skills/<slug>` (if Clawdbot is configured, installs into that workspace instead):
|
||||
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
|
||||
bun clawhub install <slug>
|
||||
bun clawhub list
|
||||
bun clawhub uninstall <slug> --yes
|
||||
openclaw plugins search "calendar"
|
||||
```
|
||||
|
||||
You can also install into any folder:
|
||||
Install a ClawHub-hosted plugin with an explicit ClawHub source:
|
||||
|
||||
```bash
|
||||
bun clawhub install <slug> --workdir /tmp/clawhub-demo --dir skills
|
||||
openclaw plugins install clawhub:<package>
|
||||
```
|
||||
|
||||
Update:
|
||||
Update installed plugins:
|
||||
|
||||
```bash
|
||||
bun clawhub update --all
|
||||
openclaw plugins update --all
|
||||
```
|
||||
|
||||
## 4) Publish a skill
|
||||
Use the `clawhub:` prefix when you want OpenClaw to resolve the package through
|
||||
ClawHub rather than npm or another source.
|
||||
|
||||
Create a folder containing `SKILL.md` (required) plus any supporting text files:
|
||||
## Sign in for publishing
|
||||
|
||||
Install the ClawHub CLI:
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/clawhub-skill-demo && cd /tmp/clawhub-skill-demo
|
||||
cat > SKILL.md <<'EOF'
|
||||
---
|
||||
name: Demo Skill
|
||||
description: Demo skill for local testing
|
||||
---
|
||||
|
||||
# Demo Skill
|
||||
|
||||
Hello.
|
||||
EOF
|
||||
npm i -g clawhub
|
||||
# or
|
||||
pnpm add -g clawhub
|
||||
```
|
||||
|
||||
Publish:
|
||||
Sign in with GitHub:
|
||||
|
||||
```bash
|
||||
bun clawhub skill publish . \
|
||||
--slug clawhub-demo-$(date +%s) \
|
||||
--name "Demo $(date +%s)" \
|
||||
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 \
|
||||
--tags latest \
|
||||
--changelog "Initial release"
|
||||
```
|
||||
|
||||
## 5) Publish a code plugin
|
||||
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](./skill-format.md).
|
||||
|
||||
Create a plugin folder with a `package.json` that includes the required OpenClaw
|
||||
publish metadata:
|
||||
## Publish a plugin
|
||||
|
||||
Publish a plugin from a local folder, a GitHub repo, a GitHub ref, or an
|
||||
existing archive:
|
||||
|
||||
```bash
|
||||
mkdir -p /tmp/clawhub-plugin-demo && cd /tmp/clawhub-plugin-demo
|
||||
cat > package.json <<'EOF'
|
||||
{
|
||||
"name": "@demo/openclaw-plugin-demo",
|
||||
"version": "0.1.0",
|
||||
"type": "module",
|
||||
"openclaw": {
|
||||
"extensions": ["./index.ts"],
|
||||
"hostTargets": ["darwin-arm64"],
|
||||
"environment": {},
|
||||
"compat": {
|
||||
"pluginApi": ">=2026.3.24-beta.2"
|
||||
},
|
||||
"build": {
|
||||
"openclawVersion": "2026.3.24-beta.2"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
clawhub package publish <source> --family code-plugin --dry-run
|
||||
clawhub package publish <source> --family code-plugin
|
||||
```
|
||||
|
||||
Preview the resolved publish payload first:
|
||||
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
|
||||
bun clawhub package publish . --family code-plugin --dry-run
|
||||
clawhub sync --all --dry-run
|
||||
clawhub sync --all
|
||||
```
|
||||
|
||||
Then publish:
|
||||
When you are signed in, `sync` may also send a minimal install snapshot for
|
||||
aggregate install counts. See [Telemetry](./telemetry.md) 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
|
||||
bun clawhub package publish . --family code-plugin
|
||||
clawhub inspect <skill-slug>
|
||||
clawhub package inspect <package>
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `openclaw.compat.pluginApi` and `openclaw.build.openclawVersion` are required
|
||||
for `code-plugin` publishes.
|
||||
- `package.json.version` does not replace either required OpenClaw field.
|
||||
- `openclaw.hostTargets` and `openclaw.environment` are optional compatibility
|
||||
metadata. Include them only when they add useful install context.
|
||||
- Add `openclaw.compat.minGatewayVersion` and
|
||||
`openclaw.build.pluginSdkVersion` when you want to expose fuller
|
||||
compatibility/build metadata, but they are not required for a successful
|
||||
publish.
|
||||
|
||||
## 6) Sync local skills (auto-publish new/changed)
|
||||
|
||||
`sync` scans for local skill folders and publishes the ones that aren’t “synced” yet.
|
||||
|
||||
```bash
|
||||
bun clawhub sync
|
||||
```
|
||||
|
||||
Dry run + non-interactive:
|
||||
|
||||
```bash
|
||||
bun clawhub sync --all --dry-run --no-input
|
||||
```
|
||||
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.
|
||||
|
||||
+96
-138
@@ -1,160 +1,118 @@
|
||||
---
|
||||
summary: "Security + moderation controls (reports, bans, upload gating)."
|
||||
summary: "ClawHub trust, scan, reporting, appeal, and moderation behavior."
|
||||
read_when:
|
||||
- Working on moderation or abuse controls
|
||||
- Reviewing upload restrictions
|
||||
- Troubleshooting hidden/removed skills
|
||||
- Understanding ClawHub scan and moderation outcomes
|
||||
- Reporting a skill or package
|
||||
- Recovering from a held, hidden, or blocked listing
|
||||
---
|
||||
|
||||
# Security + Moderation
|
||||
|
||||
See also: [acceptable-usage.md](./acceptable-usage.md) for the marketplace policy on prohibited skill categories.
|
||||
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.
|
||||
|
||||
## Roles + permissions
|
||||
See also [Acceptable usage](./acceptable-usage.md).
|
||||
|
||||
- user: upload skills/souls (subject to GitHub age gate), report skills/comments/packages.
|
||||
- moderator: hide/restore skills, view hidden skills, unhide, soft-delete, ban users (except admins).
|
||||
- admin: all moderator actions + hard delete skills, change owners, change roles.
|
||||
## What users can inspect
|
||||
|
||||
## Reporting + auto-hide
|
||||
Before installing a skill or plugin, check its ClawHub listing for:
|
||||
|
||||
- Reports are unique per user + target (skill/comment/package).
|
||||
- Report reason required (trimmed, max 500 chars). Abuse of reporting may result in account bans.
|
||||
- Per-user cap: 20 **active** reports.
|
||||
- Active skill report = skill exists, not soft-deleted, not `moderationStatus = removed`,
|
||||
and the owner is not banned.
|
||||
- Active comment report = comment exists, not soft-deleted, parent skill still active,
|
||||
and the comment author is not banned/deactivated.
|
||||
- Active package report = package exists, not soft-deleted, and the owner is
|
||||
not banned/deactivated.
|
||||
- Auto-hide: when unique reports exceed 3 (4th report):
|
||||
- skill report flow:
|
||||
- soft-delete skill (`softDeletedAt`)
|
||||
- set `moderationStatus = hidden`
|
||||
- set `moderationReason = auto.reports`
|
||||
- set embeddings visibility `deleted`
|
||||
- audit log entry: `skill.auto_hide`
|
||||
- comment report flow:
|
||||
- soft-delete comment (`softDeletedAt`)
|
||||
- decrement comment stat via `uncomment` stat event
|
||||
- audit log entry: `comment.auto_hide`
|
||||
- Package reports feed `clawhub-mod package moderation-queue` and audit `package.report`,
|
||||
but do not auto-hide or block downloads. Moderators can review a formal report
|
||||
with an explicit final action to quarantine or revoke the affected release.
|
||||
- Package reports can be moved to `confirmed` or `dismissed` with a moderator
|
||||
note. Only `open` reports count toward `packages.reportCount` and user active
|
||||
report limits; confirming or dismissing a report decrements the open count.
|
||||
- Skill reports now follow the same formal lifecycle: `open`, `confirmed`, or
|
||||
`dismissed`, with a single recorded `triageNote` used as the official outcome
|
||||
note. Moderators can review a formal report with an explicit final action to
|
||||
hide the affected skill. Skill report and appeal timelines are stored in
|
||||
`skillModerationEventLogs`.
|
||||
- Package owners and publisher members can read package moderation status via
|
||||
API/CLI, including open report count, latest release moderation state, and
|
||||
download-block reasons. Reporter identities and report bodies remain moderator
|
||||
intake data.
|
||||
- Package owners and publisher members can submit one open appeal per moderated
|
||||
package release. Accepted appeals can explicitly approve the affected release
|
||||
in the same auditable workflow.
|
||||
- Skill owners and publisher members can submit one open appeal for hidden,
|
||||
removed, suspicious, malicious, or scanner-flagged skill outcomes. Skill
|
||||
appeals use `open`, `accepted`, and `rejected` states with a single
|
||||
`resolutionNote` as the official outcome note.
|
||||
- Moderators can accept, reject, or reopen appeals with a resolution note.
|
||||
Accepted skill appeals can explicitly restore the skill, and accepted package
|
||||
appeals can explicitly approve the release.
|
||||
- `auditLogs` remains the global compliance/security ledger. Product-facing
|
||||
moderation timelines live in `skillModerationEventLogs` and
|
||||
`packageModerationEventLogs`.
|
||||
- Public queries hide non-active moderation statuses; moderators can still access via
|
||||
moderator-only queries and unhide/restore/delete/ban.
|
||||
- Legacy report rows with `status: "triaged"` are read as `confirmed` for
|
||||
compatibility while new writes store `confirmed`.
|
||||
- Skills directory supports an optional "Hide suspicious" filter to exclude
|
||||
active-but-flagged (`flagged.suspicious`) entries from browse/search results.
|
||||
- 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
|
||||
|
||||
## Skill moderation pipeline
|
||||
Install only content you understand and trust.
|
||||
|
||||
- New skill publishes now persist a deterministic static scan result on the version.
|
||||
- Package/plugin scan backfills now also recompute deterministic static scan results for older releases,
|
||||
so legacy plugin versions can surface OpenClaw scan findings without republishing.
|
||||
- ClawPack package releases keep static/LLM scan inputs intentionally metadata-only for now:
|
||||
`package.json`, `openclaw.plugin.json`, package/source metadata, and release facts. VirusTotal
|
||||
scans the exact uploaded `.tgz`; ClawHub does not currently run deep static/LLM scans across every
|
||||
tarball file.
|
||||
- Source-linked packages can fall back to a clean package verdict when VirusTotal only returns
|
||||
undetected engine results, provided the LLM scan is clean and static scan is non-malicious. This
|
||||
avoids indefinite pending scans when VT Code Insight never materializes.
|
||||
- Skill moderation state stores a structured snapshot:
|
||||
- `moderationVerdict`: `clean | suspicious | malicious`
|
||||
- `moderationReasonCodes[]`: canonical machine-readable reasons
|
||||
- `moderationEvidence[]`: capped file/line evidence for static findings
|
||||
- `moderationSummary`, engine version, evaluation timestamp, source version id
|
||||
- Structured moderation is rebuilt from current signals instead of appending stale scanner codes.
|
||||
- Legacy moderation flags remain in sync for existing public visibility and suspicious-skill filtering.
|
||||
- Static malware detection now hard-blocks install prompts that tell users to paste obfuscated shell payloads
|
||||
(for example base64-decoded `curl|bash` terminal commands). When triggered:
|
||||
- the uploaded skill is hidden immediately
|
||||
- the uploader is placed into manual moderation
|
||||
- all owned skills are hidden until moderator review
|
||||
## Scan states
|
||||
|
||||
## AI comment scam backfill
|
||||
ClawHub may show scan or moderation outcomes on public pages and owner-visible
|
||||
diagnostics.
|
||||
|
||||
- Moderators/admins can run a comment backfill scanner to classify scam comments with OpenAI.
|
||||
- Scanner stores per-comment moderation metadata:
|
||||
- `scamScanVerdict`: `not_scam | likely_scam | certain_scam`
|
||||
- `scamScanConfidence`: `low | medium | high`
|
||||
- explanation/evidence/model/check timestamp fields on `comments`.
|
||||
- Auto-ban trigger is intentionally strict:
|
||||
- only `certain_scam` with `high` confidence can trigger account ban.
|
||||
- moderator/admin accounts are never auto-banned by this pipeline.
|
||||
- Ban reason is bounded to 500 chars and includes concise evidence + comment/skill IDs.
|
||||
- CLI run examples:
|
||||
- one-shot: `npx convex run commentModeration:backfillCommentScamModeration '{"batchSize":25,"maxBatches":20}'`
|
||||
- background chain: `npx convex run commentModeration:scheduleCommentScamModeration '{"batchSize":25}'`
|
||||
Common outcomes include:
|
||||
|
||||
## Bans
|
||||
- `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.
|
||||
|
||||
- Banning a user:
|
||||
- hard-deletes all owned skills
|
||||
- soft-deletes all authored skill comments + soul comments
|
||||
- revokes API tokens
|
||||
- sets `deletedAt` on the user
|
||||
- Admins can manually unban (`deletedAt` + `banReason` cleared); revoked API tokens
|
||||
stay revoked and should be recreated by the user.
|
||||
- Optional ban reason is stored in `users.banReason` and audit logs.
|
||||
- Moderators cannot ban admins; nobody can ban themselves.
|
||||
- Report counters effectively reset because deleted/banned skills are no longer
|
||||
considered active in the per-user report cap.
|
||||
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.
|
||||
|
||||
## User account deletion
|
||||
## Skills
|
||||
|
||||
- User-initiated deletion is irreversible.
|
||||
- Deletion flow:
|
||||
- sets `deactivatedAt` + `purgedAt`
|
||||
- revokes API tokens
|
||||
- clears profile/contact fields
|
||||
- clears telemetry
|
||||
- Deleted accounts cannot be restored by logging in again.
|
||||
- Published skills remain public.
|
||||
Skill scans look at the published skill bundle, metadata, declared
|
||||
requirements, and suspicious instructions.
|
||||
|
||||
## Upload gate (GitHub account age)
|
||||
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.
|
||||
|
||||
- Skill + soul publish actions require GitHub account age ≥ 14 days.
|
||||
- Skill + soul comment creation also requires GitHub account age ≥ 14 days.
|
||||
- Lookup uses GitHub `created_at` fetched by the immutable GitHub numeric ID (`providerAccountId`)
|
||||
and caches on the user:
|
||||
- `githubCreatedAt` (source of truth)
|
||||
- Gate applies to web uploads, CLI publish, GitHub import, and comments.
|
||||
- If GitHub responds `403` or `429`, publish fails with:
|
||||
- `GitHub API rate limit exceeded — please try again in a few minutes`
|
||||
- To reduce rate-limit failures, set `GITHUB_TOKEN` in Convex env for authenticated
|
||||
GitHub API requests. The same token is used for trusted-publisher repository
|
||||
identity lookups.
|
||||
See [Skill format](./skill-format.md).
|
||||
|
||||
## Empty-skill cleanup (backfill)
|
||||
## Plugins
|
||||
|
||||
- Cleanup uses quality heuristics plus trust tier to identify very thin/templated
|
||||
skills.
|
||||
- Word counting is language-aware (`Intl.Segmenter` with fallback), reducing
|
||||
false positives for non-space-separated languages.
|
||||
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](./acceptable-usage.md)
|
||||
|
||||
## 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
|
||||
|
||||
+107
-61
@@ -1,94 +1,140 @@
|
||||
---
|
||||
summary: "Common setup/runtime issues (CLI + backend) and fixes."
|
||||
summary: "Troubleshooting ClawHub sign-in, install, publish, sync, update, and API issues."
|
||||
read_when:
|
||||
- Something is broken and you need a fix-fast checklist
|
||||
- ClawHub CLI or OpenClaw registry commands fail
|
||||
- A package cannot be installed, published, or updated
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## `clawhub login` opens browser but never completes
|
||||
## `clawhub login` opens a browser but never completes
|
||||
|
||||
- Ensure your browser can reach `http://127.0.0.1:<port>/callback` (local firewalls/VPNs can interfere).
|
||||
- Use headless mode:
|
||||
- create a token in the web UI (Settings → API tokens)
|
||||
- `clawhub login --token clh_...`
|
||||
The CLI starts a short-lived local callback server during browser login.
|
||||
|
||||
## `whoami` / `publish` returns `Unauthorized` (401)
|
||||
- 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:
|
||||
|
||||
- Token missing or revoked: check your config file (`CLAWHUB_CONFIG_PATH` override?).
|
||||
- Ensure requests include `Authorization: Bearer ...` (CLI does this automatically).
|
||||
|
||||
## CLI/API returns `Rate limit exceeded` (429)
|
||||
|
||||
- Read headers in the response:
|
||||
- `Retry-After` = wait seconds before retry
|
||||
- `RateLimit-Remaining` + `RateLimit-Limit` = current budget
|
||||
- `RateLimit-Reset` (or `X-RateLimit-Reset`) = reset timing
|
||||
- The CLI now includes retry hints in 429 errors (retry delay + remaining budget).
|
||||
- If many users share one egress IP (NAT/proxy), IP limit can be hit even with valid tokens.
|
||||
- For non-Cloudflare deploys behind trusted proxies, set `TRUST_FORWARDED_IPS=true` so forwarded client IPs can be used.
|
||||
- If no trusted client IP reaches ClawHub, anonymous downloads use endpoint-scoped fallback buckets, but search and write requests intentionally stay on the shared unknown-IP bucket until proxy headers are fixed.
|
||||
|
||||
## `search` / `install` fails with `fetch failed` behind a proxy
|
||||
|
||||
If your system requires an HTTP proxy for outbound connections (e.g. corporate
|
||||
firewalls, Docker containers with proxy-only internet, Hetzner VPS), the CLI
|
||||
will fail with:
|
||||
|
||||
```
|
||||
✖ fetch failed
|
||||
Error: fetch failed
|
||||
```bash
|
||||
clawhub login --token clh_...
|
||||
```
|
||||
|
||||
**Fix:** Set the standard proxy environment variables:
|
||||
## `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"
|
||||
```
|
||||
|
||||
The CLI respects `HTTPS_PROXY`, `HTTP_PROXY`, `https_proxy`, and `http_proxy`.
|
||||
Supported names include `HTTPS_PROXY`, `HTTP_PROXY`, `https_proxy`, and
|
||||
`http_proxy`.
|
||||
|
||||
## `publish` fails with `OPENAI_API_KEY is not configured`
|
||||
## A skill does not appear in search
|
||||
|
||||
- Set `OPENAI_API_KEY` in the Convex environment (not only locally).
|
||||
- Re-run `bunx convex dev` / `bunx convex deploy` after setting env.
|
||||
- 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:
|
||||
|
||||
## `publish` fails with `GitHub API rate limit exceeded`
|
||||
```bash
|
||||
clawhub inspect <skill-slug>
|
||||
```
|
||||
|
||||
- This is a GitHub publish-gate lookup hitting unauthenticated limits.
|
||||
- Set `GITHUB_TOKEN` in Convex environment to use authenticated GitHub API limits.
|
||||
- Retry publish after a short wait if the limit was already exhausted.
|
||||
Owner-visible diagnostics may explain scan, upload-gate, or moderation state.
|
||||
|
||||
## `sync` says “No skills found”
|
||||
## Publish fails because required metadata is missing
|
||||
|
||||
- `sync` looks for folders containing `SKILL.md` (or `skill.md`).
|
||||
- It scans:
|
||||
- workdir first
|
||||
- then fallback roots (legacy `~/clawdis/skills`, `~/clawdbot/skills`, etc.)
|
||||
- Provide explicit roots:
|
||||
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
|
||||
```
|
||||
|
||||
## `update` refuses due to “local changes (no match)”
|
||||
Preview first if you are unsure what will publish:
|
||||
|
||||
- Your local files don’t match any published fingerprint.
|
||||
- Options:
|
||||
- keep local edits; skip updating
|
||||
- overwrite: `clawhub update <slug> --force`
|
||||
- publish as fork: copy to new folder/slug then `clawhub skill publish ... --fork-of upstream@version`
|
||||
```bash
|
||||
clawhub sync --all --dry-run --no-input
|
||||
```
|
||||
|
||||
## `GET /api/*` works locally but not on Vercel
|
||||
## `update` refuses because of local changes
|
||||
|
||||
- Check `vercel.json` rewrite destination points at your Convex site URL.
|
||||
- Ensure `VITE_CONVEX_SITE_URL` and `CONVEX_SITE_URL` match your deployment.
|
||||
The local files do not match any version ClawHub knows about. Choose one:
|
||||
|
||||
## `deploy.yml` fails before deploy or smoke runs
|
||||
- Keep local edits and skip the update.
|
||||
- Overwrite with the published version:
|
||||
|
||||
- Ensure GitHub Actions secrets exist on the `Production` environment:
|
||||
- `CONVEX_DEPLOY_KEY`
|
||||
- Optional: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON`
|
||||
- Missing required deploy secrets now fails the preflight job immediately.
|
||||
- If the optional Playwright auth secret is missing, authenticated smoke canaries will skip; deploy should still proceed.
|
||||
```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](./http-api.md) for endpoint details.
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# Specs
|
||||
|
||||
`specs/` holds maintainer-only or non-navigated records that should not publish
|
||||
to the public ClawHub docs tab by default.
|
||||
|
||||
Use this folder for:
|
||||
|
||||
- Product and implementation specs.
|
||||
- Forward-looking plans and migration notes.
|
||||
- Regression notes and design history.
|
||||
- Maintainer validation or CI policy records.
|
||||
- Cross-repo extraction notes that reviewers need but users do not.
|
||||
|
||||
Public/user/operator docs belong in `docs/`. If a spec graduates into something
|
||||
users should read on `docs.openclaw.ai`, move or summarize the public material
|
||||
into `docs/` and leave only the design record here.
|
||||
|
||||
## Index
|
||||
|
||||
- `spec.md`: product + implementation spec for the original registry model.
|
||||
- `orgs.md`: org, publisher membership, and scoped identity plan.
|
||||
- `github-import.md`: GitHub import feature spec.
|
||||
- `diffing.md`: skill version diffing UI/API design.
|
||||
- `slug-routing.md`: internal web route precedence and plugin alias contract.
|
||||
- `ci.md`: PR check and production deploy audit-tag policy.
|
||||
- `manual-testing.md`: maintainer CLI smoke checklist.
|
||||
- `mintlify.md`: docs publishing setup notes.
|
||||
- `openclaw-docs-extraction.md`: CLAW-89 extraction classification.
|
||||
- `deploy.md`: maintainer deploy checklist for the ClawHub project.
|
||||
- `security-moderation.md`: detailed moderation implementation and scanner behavior notes.
|
||||
- `webhook.md`: Discord webhook environment and payload notes.
|
||||
- `plans/plugins.md`: long-term OpenClaw plugin hosting plan.
|
||||
- `regression-notes/`: regression guard notes.
|
||||
- `superpowers/`: install-surface design history.
|
||||
@@ -1,16 +1,16 @@
|
||||
---
|
||||
summary: "Deploy checklist: Convex backend + Vercel web app + /api rewrites."
|
||||
read_when:
|
||||
- Shipping to production
|
||||
- Debugging /api routing
|
||||
summary: "Maintainer deploy checklist: Convex backend, Vercel web app, CLI npm release, and /api rewrites."
|
||||
---
|
||||
|
||||
# Deploy
|
||||
|
||||
This is a maintainer runbook for the ClawHub project. It is intentionally kept
|
||||
under `specs/` so it does not publish into the user-facing ClawHub docs tab.
|
||||
|
||||
ClawHub is two deployables:
|
||||
|
||||
- Web app (TanStack Start) → typically Vercel.
|
||||
- Convex backend → Convex deployment (serves `/api/...` routes).
|
||||
- Web app (TanStack Start) -> typically Vercel.
|
||||
- Convex backend -> Convex deployment (serves `/api/...` routes).
|
||||
|
||||
## 1) Deploy Convex
|
||||
|
||||
@@ -71,7 +71,7 @@ CLI release notes:
|
||||
|
||||
That workflow assumes Vercel Git integration is enabled for this repo. It does
|
||||
not run `vercel deploy` directly; frontend-related steps wait for the GitHub
|
||||
commit status `Vercel – clawhub` for the selected SHA, then run smoke tests
|
||||
commit status `Vercel - clawhub` for the selected SHA, then run smoke tests
|
||||
against production.
|
||||
|
||||
Ensure Convex env is set (auth + embeddings):
|
||||
@@ -91,7 +91,7 @@ Ensure Convex env is set (auth + embeddings):
|
||||
Set env vars:
|
||||
|
||||
- `VITE_CONVEX_URL`
|
||||
- `VITE_CONVEX_SITE_URL` (Convex “site” URL)
|
||||
- `VITE_CONVEX_SITE_URL` (Convex "site" URL)
|
||||
- `CONVEX_SITE_URL` (same value; used by auth provider config)
|
||||
- `SITE_URL` (web app URL)
|
||||
- `VITE_APP_BUILD_SHA` (set to the same commit SHA stamped into Convex)
|
||||
@@ -112,60 +112,23 @@ This repo currently uses `vercel.json` rewrites:
|
||||
|
||||
For self-host:
|
||||
|
||||
- update `vercel.json` to your deployment’s Convex site URL.
|
||||
- update `vercel.json` to your deployment's Convex site URL.
|
||||
|
||||
## 4) Registry discovery
|
||||
|
||||
The CLI can discover the API base from:
|
||||
|
||||
- `/.well-known/clawhub.json` (preferred)
|
||||
- `/.well-known/clawdhub.json` (legacy)
|
||||
1. explicit CLI/env override
|
||||
2. configured registry URL
|
||||
3. site URL registry metadata
|
||||
|
||||
If you don’t serve that file, users must set:
|
||||
|
||||
```bash
|
||||
export CLAWHUB_REGISTRY=https://your-site.example
|
||||
```
|
||||
Keep production rewrites and discovery metadata aligned before release.
|
||||
|
||||
## 5) Post-deploy checks
|
||||
|
||||
```bash
|
||||
curl -i "https://<site>/api/v1/search?q=test"
|
||||
curl -i "https://<site>/api/v1/skills/gifgrep"
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
clawhub login --site https://<site>
|
||||
clawhub whoami
|
||||
```
|
||||
|
||||
Rate-limit sanity checks:
|
||||
|
||||
```bash
|
||||
curl -i "https://<site>/api/v1/download?slug=gifgrep"
|
||||
```
|
||||
|
||||
Confirm headers are present:
|
||||
|
||||
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
|
||||
- `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`
|
||||
- `Retry-After` on `429`
|
||||
|
||||
Drift checks:
|
||||
Run the contract verifier and smoke tests against production after deploy:
|
||||
|
||||
```bash
|
||||
bun run verify:convex-contract -- --prod
|
||||
PLAYWRIGHT_BASE_URL=https://clawhub.ai bunx playwright test e2e/menu-smoke.pw.test.ts e2e/upload-auth-smoke.pw.test.ts
|
||||
```
|
||||
|
||||
The Playwright smoke suite should fail on visible error UI, page errors, and
|
||||
browser console errors.
|
||||
|
||||
Proxy/IP caveat:
|
||||
|
||||
- Default IP source is `cf-connecting-ip`.
|
||||
- For non-Cloudflare trusted proxy setups, set `TRUST_FORWARDED_IPS=true`.
|
||||
- If a trusted client IP is missing, anonymous downloads fall back to endpoint-scoped buckets to avoid unrelated packages sharing one `ip:unknown` download bucket.
|
||||
- If proxy headers are not forwarded/trusted correctly, multiple users may collapse into one IP and hit false-positive rate limits.
|
||||
@@ -0,0 +1,46 @@
|
||||
# OpenClaw Docs Extraction Notes
|
||||
|
||||
Context: CLAW-89 moves canonical ClawHub-owned documentation into the ClawHub
|
||||
repo so OpenClaw's `/tools/clawhub` page is no longer the source of truth.
|
||||
|
||||
Source audited for this slice:
|
||||
|
||||
- OpenClaw `docs/tools/clawhub.md` in the sibling read-only worktree.
|
||||
- OpenClaw docs-wide `ClawHub`/`clawhub` mentions for classification patterns.
|
||||
|
||||
## Moved into ClawHub docs
|
||||
|
||||
Canonical product and registry material now lives in `docs/clawhub.md`:
|
||||
|
||||
- What ClawHub is: public registry for OpenClaw skills and plugins.
|
||||
- Native OpenClaw search/install/update examples for skills and plugins.
|
||||
- ClawHub CLI purpose and common authenticated workflows.
|
||||
- Skill and plugin publishing commands.
|
||||
- Security scan summaries, owner rescans, reporting, appeals, and moderation overview.
|
||||
- Versioning, lockfile, telemetry, and environment override guidance.
|
||||
|
||||
## Summarize or link from OpenClaw docs
|
||||
|
||||
These OpenClaw docs should eventually point to the ClawHub docs tab rather than
|
||||
restate the whole registry guide:
|
||||
|
||||
- `docs/tools/clawhub.md`: keep as a concise bridge to ClawHub docs plus OpenClaw-native install examples.
|
||||
- `docs/tools/skills.md`: keep OpenClaw skill-loading behavior inline; link to ClawHub for registry, publishing, security, and CLI details.
|
||||
- `docs/tools/plugin.md` and `docs/plugins/community.md`: keep OpenClaw install/runtime behavior inline; link to ClawHub for registry/package publishing and moderation.
|
||||
- `docs/plugins/building-plugins.md`: keep plugin authoring/runtime contract inline; link to ClawHub for publish command details.
|
||||
|
||||
## Leave in OpenClaw docs
|
||||
|
||||
These mentions are OpenClaw-owned integration/runtime material and should remain
|
||||
in OpenClaw unless the owner explicitly asks for a separate extraction:
|
||||
|
||||
- OpenClaw CLI command behavior: `openclaw skills ...`, `openclaw plugins ...`, `/plugin install ...`.
|
||||
- Plugin dependency resolution, package acceptance, Docker/E2E fixtures, release workflows, and testing references.
|
||||
- Threat model references where ClawHub is one platform component inside a broader OpenClaw security model.
|
||||
- Showcase or FAQ links that merely point users to live ClawHub pages.
|
||||
|
||||
## Reviewer check
|
||||
|
||||
For this slice, the ClawHub repo owns the new canonical source file. The
|
||||
OpenClaw worktree was read-only, so replacing OpenClaw sections with short links
|
||||
is left to the OpenClaw-side worker.
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
summary: "Security + moderation controls (reports, bans, upload gating)."
|
||||
read_when:
|
||||
- Working on moderation or abuse controls
|
||||
- Reviewing upload restrictions
|
||||
- Troubleshooting hidden/removed skills
|
||||
---
|
||||
|
||||
# Security + Moderation
|
||||
|
||||
See also: [acceptable-usage.md](./acceptable-usage.md) for the marketplace policy on prohibited skill categories.
|
||||
|
||||
## Roles + permissions
|
||||
|
||||
- user: upload skills/souls (subject to GitHub age gate), report skills/comments/packages.
|
||||
- moderator: hide/restore skills, view hidden skills, unhide, soft-delete, ban users (except admins).
|
||||
- admin: all moderator actions + hard delete skills, change owners, change roles.
|
||||
|
||||
## Reporting + auto-hide
|
||||
|
||||
- Reports are unique per user + target (skill/comment/package).
|
||||
- Report reason required (trimmed, max 500 chars). Abuse of reporting may result in account bans.
|
||||
- Per-user cap: 20 **active** reports.
|
||||
- Active skill report = skill exists, not soft-deleted, not `moderationStatus = removed`,
|
||||
and the owner is not banned.
|
||||
- Active comment report = comment exists, not soft-deleted, parent skill still active,
|
||||
and the comment author is not banned/deactivated.
|
||||
- Active package report = package exists, not soft-deleted, and the owner is
|
||||
not banned/deactivated.
|
||||
- Auto-hide: when unique reports exceed 3 (4th report):
|
||||
- skill report flow:
|
||||
- soft-delete skill (`softDeletedAt`)
|
||||
- set `moderationStatus = hidden`
|
||||
- set `moderationReason = auto.reports`
|
||||
- set embeddings visibility `deleted`
|
||||
- audit log entry: `skill.auto_hide`
|
||||
- comment report flow:
|
||||
- soft-delete comment (`softDeletedAt`)
|
||||
- decrement comment stat via `uncomment` stat event
|
||||
- audit log entry: `comment.auto_hide`
|
||||
- Package reports feed `clawhub-mod package moderation-queue` and audit `package.report`,
|
||||
but do not auto-hide or block downloads. Moderators can review a formal report
|
||||
with an explicit final action to quarantine or revoke the affected release.
|
||||
- Package reports can be moved to `confirmed` or `dismissed` with a moderator
|
||||
note. Only `open` reports count toward `packages.reportCount` and user active
|
||||
report limits; confirming or dismissing a report decrements the open count.
|
||||
- Skill reports now follow the same formal lifecycle: `open`, `confirmed`, or
|
||||
`dismissed`, with a single recorded `triageNote` used as the official outcome
|
||||
note. Moderators can review a formal report with an explicit final action to
|
||||
hide the affected skill. Skill report and appeal timelines are stored in
|
||||
`skillModerationEventLogs`.
|
||||
- Package owners and publisher members can read package moderation status via
|
||||
API/CLI, including open report count, latest release moderation state, and
|
||||
download-block reasons. Reporter identities and report bodies remain moderator
|
||||
intake data.
|
||||
- Package owners and publisher members can submit one open appeal per moderated
|
||||
package release. Accepted appeals can explicitly approve the affected release
|
||||
in the same auditable workflow.
|
||||
- Skill owners and publisher members can submit one open appeal for hidden,
|
||||
removed, suspicious, malicious, or scanner-flagged skill outcomes. Skill
|
||||
appeals use `open`, `accepted`, and `rejected` states with a single
|
||||
`resolutionNote` as the official outcome note.
|
||||
- Moderators can accept, reject, or reopen appeals with a resolution note.
|
||||
Accepted skill appeals can explicitly restore the skill, and accepted package
|
||||
appeals can explicitly approve the release.
|
||||
- `auditLogs` remains the global compliance/security ledger. Product-facing
|
||||
moderation timelines live in `skillModerationEventLogs` and
|
||||
`packageModerationEventLogs`.
|
||||
- Public queries hide non-active moderation statuses; moderators can still access via
|
||||
moderator-only queries and unhide/restore/delete/ban.
|
||||
- Legacy report rows with `status: "triaged"` are read as `confirmed` for
|
||||
compatibility while new writes store `confirmed`.
|
||||
- Skills directory supports an optional "Hide suspicious" filter to exclude
|
||||
active-but-flagged (`flagged.suspicious`) entries from browse/search results.
|
||||
|
||||
## Skill moderation pipeline
|
||||
|
||||
- New skill publishes now persist a deterministic static scan result on the version.
|
||||
- Package/plugin scan backfills now also recompute deterministic static scan results for older releases,
|
||||
so legacy plugin versions can surface OpenClaw scan findings without republishing.
|
||||
- ClawPack package releases keep static/LLM scan inputs intentionally metadata-only for now:
|
||||
`package.json`, `openclaw.plugin.json`, package/source metadata, and release facts. VirusTotal
|
||||
scans the exact uploaded `.tgz`; ClawHub does not currently run deep static/LLM scans across every
|
||||
tarball file.
|
||||
- Source-linked packages can fall back to a clean package verdict when VirusTotal only returns
|
||||
undetected engine results, provided the LLM scan is clean and static scan is non-malicious. This
|
||||
avoids indefinite pending scans when VT Code Insight never materializes.
|
||||
- Skill moderation state stores a structured snapshot:
|
||||
- `moderationVerdict`: `clean | suspicious | malicious`
|
||||
- `moderationReasonCodes[]`: canonical machine-readable reasons
|
||||
- `moderationEvidence[]`: capped file/line evidence for static findings
|
||||
- `moderationSummary`, engine version, evaluation timestamp, source version id
|
||||
- Structured moderation is rebuilt from current signals instead of appending stale scanner codes.
|
||||
- Legacy moderation flags remain in sync for existing public visibility and suspicious-skill filtering.
|
||||
- Static malware detection now hard-blocks install prompts that tell users to paste obfuscated shell payloads
|
||||
(for example base64-decoded `curl|bash` terminal commands). When triggered:
|
||||
- the uploaded skill is hidden immediately
|
||||
- the uploader is placed into manual moderation
|
||||
- all owned skills are hidden until moderator review
|
||||
|
||||
## AI comment scam backfill
|
||||
|
||||
- Moderators/admins can run a comment backfill scanner to classify scam comments with OpenAI.
|
||||
- Scanner stores per-comment moderation metadata:
|
||||
- `scamScanVerdict`: `not_scam | likely_scam | certain_scam`
|
||||
- `scamScanConfidence`: `low | medium | high`
|
||||
- explanation/evidence/model/check timestamp fields on `comments`.
|
||||
- Auto-ban trigger is intentionally strict:
|
||||
- only `certain_scam` with `high` confidence can trigger account ban.
|
||||
- moderator/admin accounts are never auto-banned by this pipeline.
|
||||
- Ban reason is bounded to 500 chars and includes concise evidence + comment/skill IDs.
|
||||
- CLI run examples:
|
||||
- one-shot: `npx convex run commentModeration:backfillCommentScamModeration '{"batchSize":25,"maxBatches":20}'`
|
||||
- background chain: `npx convex run commentModeration:scheduleCommentScamModeration '{"batchSize":25}'`
|
||||
|
||||
## Bans
|
||||
|
||||
- Banning a user:
|
||||
- hard-deletes all owned skills
|
||||
- soft-deletes all authored skill comments + soul comments
|
||||
- revokes API tokens
|
||||
- sets `deletedAt` on the user
|
||||
- Admins can manually unban (`deletedAt` + `banReason` cleared); revoked API tokens
|
||||
stay revoked and should be recreated by the user.
|
||||
- Optional ban reason is stored in `users.banReason` and audit logs.
|
||||
- Moderators cannot ban admins; nobody can ban themselves.
|
||||
- Report counters effectively reset because deleted/banned skills are no longer
|
||||
considered active in the per-user report cap.
|
||||
|
||||
## User account deletion
|
||||
|
||||
- User-initiated deletion is irreversible.
|
||||
- Deletion flow:
|
||||
- sets `deactivatedAt` + `purgedAt`
|
||||
- revokes API tokens
|
||||
- clears profile/contact fields
|
||||
- clears telemetry
|
||||
- Deleted accounts cannot be restored by logging in again.
|
||||
- Published skills remain public.
|
||||
|
||||
## Upload gate (GitHub account age)
|
||||
|
||||
- Skill + soul publish actions require GitHub account age ≥ 14 days.
|
||||
- Skill + soul comment creation also requires GitHub account age ≥ 14 days.
|
||||
- Lookup uses GitHub `created_at` fetched by the immutable GitHub numeric ID (`providerAccountId`)
|
||||
and caches on the user:
|
||||
- `githubCreatedAt` (source of truth)
|
||||
- Gate applies to web uploads, CLI publish, GitHub import, and comments.
|
||||
- If GitHub responds `403` or `429`, publish fails with:
|
||||
- `GitHub API rate limit exceeded — please try again in a few minutes`
|
||||
- To reduce rate-limit failures, set `GITHUB_TOKEN` in Convex env for authenticated
|
||||
GitHub API requests. The same token is used for trusted-publisher repository
|
||||
identity lookups.
|
||||
|
||||
## Empty-skill cleanup (backfill)
|
||||
|
||||
- Cleanup uses quality heuristics plus trust tier to identify very thin/templated
|
||||
skills.
|
||||
- Word counting is language-aware (`Intl.Segmenter` with fallback), reducing
|
||||
false positives for non-space-separated languages.
|
||||
Reference in New Issue
Block a user