Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
180 lines (122 loc) · 5.56 KB

CONTRIBUTING.md

File metadata and controls

180 lines (122 loc) · 5.56 KB

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

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