clawhub/CONTRIBUTING.md

Contributing to ClawHub

Welcome! ClawHub is the public skill registry for OpenClaw. We appreciate bug fixes, documentation improvements, and feature contributions.

• Questions? Ask in #clawhub on Discord.
• Bug fixes — PRs are welcome.
• New features or architectural changes — please start with a Discord conversation in #clawhub first so we can align on scope.

Local Development Setup

Prerequisites

• Bun (Convex CLI runs via bunx, no global install needed)
• Node.js v18, 20, 22, or 24 (required by the local Convex backend; v25+ is not yet supported)

Install and configure

bun install
cp .env.local.example .env.local

Edit .env.local with the following values for local Convex:

# Frontend
VITE_CONVEX_URL=http://127.0.0.1:3210
VITE_CONVEX_SITE_URL=http://127.0.0.1:3210
SITE_URL=http://localhost:3000

# Deployment used by `bunx convex dev`
CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub

GitHub OAuth App (for login)

1. Go to github.com/settings/developers and create a new OAuth App.
2. Set Homepage URL to http://localhost:3000.
3. Set Authorization callback URL to http://127.0.0.1:3210/api/auth/callback/github.
4. Copy the Client ID and generate a Client Secret.

Run the Convex backend

Start the local Convex backend first — other setup steps depend on it:

bunx convex dev --typecheck=disable

Set backend environment variables

The Convex backend has its own env var store separate from .env.local. With the backend running, open a new terminal and set the required variables:

bunx convex env set AUTH_GITHUB_ID <your-client-id>
bunx convex env set AUTH_GITHUB_SECRET <your-client-secret>
bunx convex env set SITE_URL http://localhost:3000

JWT keys (for Convex Auth)

With the backend still running, generate the signing keys:

bunx @convex-dev/auth

This sets JWT_PRIVATE_KEY and JWKS on the Convex backend and outputs values you can also save to .env.local for reference.

Run the frontend

bun run dev -- --port 3000

Change the port if 3000 is already in use, and update SITE_URL in both .env.local and the Convex backend (bunx convex env set SITE_URL ...) to match.

Seed the database

Populate sample data so the UI isn't empty:

# 3 sample skills (padel, gohome, xuezh)
bunx convex run --no-push devSeed:seedNixSkills

# 50 extra skills for pagination testing (optional)
bunx convex run --no-push devSeedExtra:seedExtraSkillsInternal

# Refresh the cached skills count (required after seeding)
bunx convex run --no-push statsMaintenance:updateGlobalStatsInternal

To reset and re-seed:

bunx convex run --no-push devSeed:seedNixSkills '{"reset": true}'

Optional environment variables

These features degrade gracefully without their keys:

Variable	Purpose
OPENAI_API_KEY	Embeddings and vector search (falls back to zero vectors)
VT_API_KEY	VirusTotal malware scanning
DISCORD_WEBHOOK_URL	Discord notifications
GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY / GITHUB_APP_INSTALLATION_ID	GitHub backup sync

CLI Development

The CLI source lives in packages/clawdhub/. Both clawhub and clawdhub are registered as bin aliases.

To test the CLI against your local instance:

CLAWHUB_REGISTRY=http://127.0.0.1:3210 CLAWHUB_SITE=http://localhost:3000 clawhub search "padel"

Manual smoke tests are documented in docs/manual-testing.md.

Skill & Soul Publishing

• Skill format reference: docs/skill-format.md
• Soul format reference: docs/soul-format.md
• End-to-end walkthrough (search, install, publish, sync): docs/quickstart.md

Quick publish:

clawhub publish <path-to-skill-directory>

Before Submitting a PR

bun run lint       # oxlint
bun run test       # Vitest (80% coverage threshold)
bun run build      # Vite + Nitro

These are the same checks that run in CI (.github/workflows/ci.yml).

PR guidelines:

• Keep PRs focused — one concern per PR.
• Use Conventional Commits: feat:, fix:, chore:, docs:, etc.
• Include test commands and screenshots for UI changes.
• Write a clear description of what changed and why.

AI-Generated Code

AI-assisted contributions are welcome. When submitting AI-generated or AI-assisted code:

• Note it in the PR description.
• Describe the level of testing you applied.
• Include prompts if useful for reviewers.
• Confirm that you understand and can maintain the code.

Security Reporting

Report vulnerabilities to security@openclaw.ai with:

• Severity assessment
• Technical reproduction steps
• Suggested remediation

See docs/security.md for moderation and upload gating details.

Reading Order for New Contributors

1. This file (local setup)
2. docs/quickstart.md — end-to-end workflows
3. docs/architecture.md — system design
4. docs/skill-format.md — skill structure
5. docs/cli.md — CLI reference
6. docs/http-api.md — HTTP endpoints
7. docs/auth.md — authentication
8. docs/deploy.md — deployment
9. docs/troubleshooting.md — common issues