Skip to content

quickstart.md

Latest commit

 

History

History
172 lines (129 loc) · 3.42 KB

quickstart.md

File metadata and controls

172 lines (129 loc) · 3.42 KB
summary Local setup + CLI smoke: login, search, install, publish, sync.
read_when
First run / local dev setup
Verifying end-to-end flows

Quickstart

0) Prereqs

  • Bun
  • Convex CLI (bunx convex ...)
  • GitHub OAuth App (for login)
  • OpenAI key (for embeddings/search)

1) Local dev (web + Convex)

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

# terminal A
bun run dev

# terminal B
bunx convex dev

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:

bunx auth --deployment-name <deployment> --web-server-url http://localhost:3000

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:

bun clawhub --help
bun clawhub login
bun clawhub whoami
bun clawhub search gif --limit 5

Install a skill into ./skills/<slug> (if Clawdbot is configured, installs into that workspace instead):

bun clawhub install <slug>
bun clawhub list
bun clawhub uninstall <slug> --yes

You can also install into any folder:

bun clawhub install <slug> --workdir /tmp/clawhub-demo --dir skills

Update:

bun clawhub update --all

4) Publish a skill

Create a folder containing SKILL.md (required) plus any supporting text files:

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

Publish:

bun clawhub skill publish . \
  --slug clawhub-demo-$(date +%s) \
  --name "Demo $(date +%s)" \
  --version 1.0.0 \
  --tags latest \
  --changelog "Initial release"

5) Publish a code plugin

Create a plugin folder with a package.json that includes the required OpenClaw publish metadata:

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

Preview the resolved publish payload first:

bun clawhub package publish . --family code-plugin --dry-run

Then publish:

bun clawhub package publish . --family code-plugin

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.

bun clawhub sync

Dry run + non-interactive:

bun clawhub sync --all --dry-run --no-input