ClawHub 本地开发指南：从环境搭建、Worktree 快路径到 PR 提交门禁的完整实践-平芜编程栈

后端
前端
AI 技能
AI 插件
搜索引擎

【免费下载链接】clawhub

Skill + Plugin Registry for OpenClaw

项目地址：https://gitcode.com/gh_mirrors/mo/clawhub

本文以 ClawHub（OpenClaw 的公开技能与插件注册表）仓库的 CONTRIBUTING.md 为核心脉络，系统讲解在本地复现完整开发环境的每一步：依赖安装、.env.local配置、本地 Convex 后端与 GitHub OAuth 登录、Worktree/Codex 并行开发快路径、本地数据播种（Seeding）、CLI 包的独立验证流程，以及提交 PR 前需要满足的静态检查、单元测试、类型构建、E2E 与 Playwright 浏览器门禁。读完本文，你将能独立搭建一套可登录、可搜索、可发布技能的本地 ClawHub 环境，并知道如何在改动代码后跑通最小验证闭环。

一、项目定位与贡献入口

ClawHub 是 OpenClaw 的公开技能注册表（skill registry），仓库以 Bun workspace 组织，包含三个子包：packages/clawhub（CLI）、packages/clawhub-admin（管理工具）与packages/schema（共享类型与校验契约），核心后端位于convex/目录，前端位于src/。根目录 package.json 定义了全部ci:*、seed:*、crabbox:*等脚本。

官方维护者欢迎三类贡献：Bug 修复（直接提 PR）、文档改进，以及新功能或架构级改动（后者建议先在 #clawhub Discord 频道对齐范围，避免 PR 方向返工）。对于想贡献技能的开发者，快速发布路径非常简单：

clawhub publish <path-to-skill-directory>

技能格式规范见 docs/skill-format.md，完整的「搜索—安装—发布」端到端流程见 docs/quickstart.md。

二、本地开发环境的依赖与初始化

2.1 前置依赖

Bun：Convex CLI 通过bunx运行，无需全局安装 Convex；
Node.js v18 / 20 / 22 / 24：本地 Convex 后端要求 Node 运行时（v25+ 暂不支持）；
Worktrunk（wt）：用于bun run dev:worktree以及一次性/Codex worktree 场景，macOS 上最快安装方式是brew install worktrunk（shell 集成可选）。

值得注意的是，根目录 package.json 的preinstall脚本为bunx --bun only-allow@1.2.2 bun，即强制使用 Bun 作为包管理器，因此不要用npm install或yarn替代。

2.2 安装依赖与环境变量

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

仓库中的 .env.local.example 给出了比文档更完整的变量清单，除下方 Convex 相关变量外，还包括开发登录测试（dev auth）、邮件服务（RESEND_API_KEY、CLAWHUB_SECURITY_EMAIL_FROM、CLAWHUB_NOREPLY_FROM）等可选配置。针对本地 Convex，.env.local至少需要填写：

# Frontend VITE_CONVEX_URL=http://127.0.0.1:3210 VITE_CONVEX_SITE_URL=http://127.0.0.1:3211 SITE_URL=http://localhost:3000 # Convex Auth / HTTP routes CONVEX_SITE_URL=http://127.0.0.1:3211 # Deployment used by `bunx convex dev` CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub

端口约定：本地 Convex 在3210端口提供函数端点，通过3211端口的站点代理提供 HTTP 路由（/api/*）与 auth 回调。SITE_URL指向前端开发服务器 3000 端口。

三、GitHub OAuth 应用与本地登录

ClawHub 使用 GitHub OAuth 完成登录，本地开发需要自建一个 OAuth App：

在 GitHub 开发者设置中创建新的 OAuth App；
Homepage URL填http://localhost:3000；
Authorization callback URL填http://127.0.0.1:3211/api/auth/callback/github（注意回调走的是 3211 站点代理，而不是前端端口）；
复制 Client ID 并生成 Client Secret。

随后将密钥写入 Convex 后端的环境变量存储（后端环境变量与.env.local是两套独立存储）：

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

3.1 生成 Convex Auth 的 JWT 签名密钥

保持后端运行，执行：

bunx @convex-dev/auth

该命令会为 Convex Auth 生成JWT_PRIVATE_KEY与JWKS并写入后端环境变量，同时把生成值打印出来供你保存到.env.local作为参考（对应 .env.local.example 中的JWT_PRIVATE_KEY、JWKS两行）。.env.local.example中还有一组DEV_AUTH_*变量（DEV_AUTH_ENABLED、DEV_AUTH_CONVEX_DEPLOYMENT、DEV_AUTH_SITE_URL、DEV_AUTH_SECRET），用于本地开发免 GitHub 登录的测试身份，其启用逻辑在 convex/lib/devAuth.ts 中：DEV_AUTH_ENABLED=1时，本地（local:/anonymous:前缀）部署要求CONVEX_SITE_URL指向 localhost，云端 dev 部署则要求DEV_AUTH_SITE_URL为 localhost 且DEV_AUTH_SECRET长度不少于 32 并与后端一致。

四、启动后端与前端

4.1 先启动 Convex 后端

bunx convex dev --typecheck=disable

其他步骤依赖后端先跑起来，所以后端要最先启动。--typecheck=disable跳过 Convex 函数的类型检查以加快本地迭代。

4.2 启动前端

bun run dev -- --port 3000

如果 3000 端口被占用，可以换端口，但必须同步修改两处SITE_URL：.env.local与 Convex 后端（bunx convex env set SITE_URL ...），保持前后端一致。

五、Worktree/Codex 开发快路径

当某个「源 worktree」已经拥有可用的.env.local和.convex本地 Convex 配置后，后续的一次性分支、Codex 会话或并行 worktree 可以直接走快路径：

bun run setup:worktree bun run dev:worktree wt --yes url wt --yes stop

setup:worktree（实现见 scripts/setup-worktree.ts）会寻找可用的源 worktree，并把.env.local与.convex符号链接（symlink）到当前 checkout。若自动发现选错了源，可以显式指定：

bun run setup:worktree -- --from /path/to/source/worktree CLAWHUB_WORKTREE_SOURCE=/path/to/source/worktree bun run setup:worktree

dev:worktree是 Worktrunk 入口：运行 .config/wt.toml 中的 hooks，尽量复制 .worktreeinclude 中列出的被忽略依赖（Vite 缺失时回退到bun install），在VITE_CONVEX_URL与CONVEX_DEPLOYMENT均为本地标记时一次性播种本地 fixtures 与公开语料库，刷新缓存的全局统计，并在按分支哈希的 loopback 端口启动分离式服务。用wt --yes url查看 URL。

分离式服务器把运行时状态写到.codex/runtime/下，删除 worktree 前必须先wt --yes stop。

5.1 本地 Codex worker 的显式启用

本地开发默认不启动 Codex 支持的 worker，因此dev:worktree不会消耗 Codex 配额。如需处理本地的 ClawScan（安全扫描）或 Skill Card 作业，可在该 shell 中显式选择启用：

CLAWHUB_ALLOW_LOCAL_CODEX_SCAN=1 bun run dev:workers -- --workers security-scan --once CLAWHUB_ALLOW_LOCAL_CODEX_SCAN=1 bun run dev:workers -- --workers skill-card --once

从源码看，这个开关由 scripts/codex-worker-guard.ts 中的LOCAL_CODEX_WORKER_OPT_IN = "CLAWHUB_ALLOW_LOCAL_CODEX_SCAN"定义，scripts/dev-workers.test.ts 的测试也验证了未启用时 worker 会被拒绝并提示该变量名。启用后的本地运行会使用一个被忽略的、worktree 本地的CODEX_HOME（除非显式提供）。

如果不启用这些 worker，本地的 ClawScan 与 Skill Card 作业会一直停留在 pending 状态，直到你选择启用、播种/模拟结果，或走生产工作流。

六、数据库播种（Seeding）与 QA 数据

dev:worktree在VITE_CONVEX_URL指向本地 Convex 且CONVEX_DEPLOYMENT为匿名/本地标记时，会先播种本地 QA fixtures 与已提交的公开语料库，再启动应用，并记录.codex/runtime/dev-worktree.seeded以便普通重启跳过昂贵的语料库导入；远程后端预览或部署标记不匹配时会跳过播种直接启动。

强制重新播种而不重启预览：

bun run seed:dev

seed:dev会执行 worktree setup、启动或等待本地 Convex、播种手写的本地 QA fixtures、导入已提交的公开语料库并刷新缓存的全局统计。fixtures 或 schema 变更后可以安全地重复运行。

6.1 低层播种命令

针对手工恢复或聚焦的 fixture 工作，还有更细粒度的命令：

# 仅本地 moderation/security fixtures bunx convex run --no-push devSeed:seedLocalFixtures # 仅已提交的公开语料库 bun run seed:public-corpus # 校验已提交的公开语料库 fixture bun run validate:public-corpus # 额外 50 个技能用于分页测试（可选） bunx convex run --no-push devSeedExtra:seedExtraSkillsInternal # 手工播种后刷新缓存的全局统计 bunx convex run --no-push statsMaintenance:updateGlobalStatsAction

需要重置后重新播种：

bunx convex run --no-push devSeed:seedLocalFixtures '{"reset": true}' bun run seed:public-corpus -- --reset bunx convex run --no-push statsMaintenance:updateGlobalStatsAction

注意：没有OPENAI_API_KEY时公开语料库导入仍可工作，但语义搜索质量会下降，因为 embeddings 会退化为零向量。

七、Worktree 常见问题排查

wt: command not found：先安装 Worktrunk 再重跑bun run dev:worktree；不装 Worktrunk 时，手动bun run dev+bunx convex dev --typecheck=disable依然可用；
缺少.env.local或.convex：执行bun run setup:worktree -- --from /path/to/source/worktree。源目录必须包含.env.local；对本地 Convex 部署，还要有.convex/local/default/config.json；
本地 Convex 部署不匹配：使用local:部署时，确保.env.local里的CONVEX_DEPLOYMENT与.convex/local/default/config.json中的本地部署一致；
端口不匹配：本地 Convex 通常在http://127.0.0.1:3210提供云函数、在http://127.0.0.1:3211提供 HTTP 路由与 auth 回调，需保持VITE_CONVEX_URL、VITE_CONVEX_SITE_URL、CONVEX_SITE_URL与本地配置对齐；
wt step copy-ignored报.convex无法复制：当.convex是指向源 worktree 的符号链接时会发生，Worktrunk hook 会继续，先确认.env.local、.convex、node_modules/.bin/vite存在再深入排查；
播种期间本地 Convex 函数还不可查询：保持bunx convex dev --typecheck=disable运行或重跑bun run seed:dev，seed runner 会在 Convex 完成函数推送期间重试；
播种时遇到瞬时 Convex 写冲突：seed:public-corpus会重试可重试的批量冲突；重试耗尽时停止其他本地写入者并重跑bun run seed:dev；
分离式服务陈旧：先wt --yes stop，若服务器仍不能干净重启，检查.codex/runtime/dev-worktree.log。

八、可选环境变量（优雅降级）

以下特性在缺少对应密钥时会优雅降级，不会阻断开发：

变量	用途
`OPENAI_API_KEY`	Embeddings 与向量搜索（缺失时退化为零向量）
`VT_API_KEY`	VirusTotal 恶意软件扫描
`DISCORD_WEBHOOK_URL`	Discord 通知

九、CLI 开发与验证

CLI 源码位于 packages/clawhub/，其 package.json 同时注册了clawhub与clawdhub两个 bin 别名。包内依赖commander、@clack/prompts、arktype、@openclaw/plugin-inspector等，提供 install / update / search / publish / scan / verify 等命令。

针对本地实例测试 CLI：

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

即通过环境变量把注册表指向本地 3211 站点代理、站点指向前端 3000 端口。

修改 CLI 时使用包级验证契约（注意bun test packages/clawhub/不是受支持的工作流——源码测试与构建产物冒烟测试是刻意分离的）：

bun run --cwd packages/clawhub test bun run --cwd packages/clawhub verify:build bun run --cwd packages/clawhub test:artifact bun run --cwd packages/clawhub verify

其中verify会串联执行源码测试、类型检查与构建产物测试，等价于test:src && verify:build && test:artifact。完整的手工冒烟测试清单（登录、搜索、安装、发布、删除/恢复、Playwright 菜单冒烟等）见 specs/manual-testing.md。

十、提交 PR 前的验证门禁

10.1 本地最小验证

按改动类型选择最窄但有意义的检查，然后在提交前跑对应的 CI 别名：

所有 PR：bun run ci:static
源码或测试改动：被改动行为的聚焦测试 +bun run ci:unit（纯文档/配置改动或维护者要求依赖 CI 时可跳过）
应用运行时、Convex 或构建改动：bun run ci:types-build
包（packages）改动：bun run ci:packages
HTTP/API/CLI 集成改动：bun run ci:e2e-http
浏览器冒烟或视觉行为改动：bun run ci:playwright-smoke、bun run test:pw:local-auth和/或bun run proof:ui

bun run ci:pr是本地聚合的非浏览器 PR 门禁。完整的 CI 契约见 specs/ci.md，其中详细说明了各 CI job 的分工：static做 peer 依赖校验、依赖审计、格式化、lint 与死代码检查；unit运行 Vitest 覆盖率套件；packages构建packages/schema并验证 CLI 包；types-build对应用、schema 包、CLI 包做 typecheck 后构建应用；e2e-http运行无密钥的 HTTP 与 CLI 端到端子集；playwright-smoke对公共读后端跑 chromium 浏览器冒烟；playwright-local-auth用本地匿名 Convex 后端 + dev auth 跑e2e/local-auth/下的浏览器规格。

10.2 Crabbox 远程检查

维护者可以把同样的检查放到 Crabbox 租约上远程执行，避免占用本地 CPU。ClawHub 将 Crabbox 作为面向 Agent 的命令面，Testbox 工作流只是默认 Blacksmith provider 的后端：

bun run crabbox:warmup -- --provider blacksmith-testbox bun run crabbox:run -- --provider blacksmith-testbox --shell -- "bun run lint" bun run crabbox:run -- --provider blacksmith-testbox --shell -- "bun run test" bun run crabbox:run -- --provider blacksmith-testbox --shell -- "bun run build"

复用已预热租约时给crabbox:run加--id <id-or-slug>；用完的一次性租约用bun run crabbox:stop -- --provider <provider> <id-or-slug>停止。若有意要在笔记本端跑完整检查，可用显式的CLAWHUB_LOCAL_CHECK_MODE=throttled或CLAWHUB_LOCAL_CHECK_MODE=full作为逃生通道；缺少 Crabbox 认证/provider 访问时应直接报告，而不是回退到会拖垮开发机的宽泛本地门禁。