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

后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载本文以 ClawHubOpenClaw 的公开技能与插件注册表仓库的 CONTRIBUTING.md 为核心脉络系统讲解在本地复现完整开发环境的每一步依赖安装、.env.local配置、本地 Convex 后端与 GitHub OAuth 登录、Worktree/Codex 并行开发快路径、本地数据播种Seeding、CLI 包的独立验证流程以及提交 PR 前需要满足的静态检查、单元测试、类型构建、E2E 与 Playwright 浏览器门禁。读完本文你将能独立搭建一套可登录、可搜索、可发布技能的本地 ClawHub 环境并知道如何在改动代码后跑通最小验证闭环。一、项目定位与贡献入口ClawHub 是 OpenClaw 的公开技能注册表skill registry仓库以 Bun workspace 组织包含三个子包packages/clawhubCLI、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 前置依赖BunConvex CLI 通过bunx运行无需全局安装 ConvexNode.js v18 / 20 / 22 / 24本地 Convex 后端要求 Node 运行时v25 暂不支持Worktrunkwt用于bun run dev:worktree以及一次性/Codex worktree 场景macOS 上最快安装方式是brew install worktrunkshell 集成可选。值得注意的是根目录 package.json 的preinstall脚本为bunx --bun only-allow1.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_URLhttp://127.0.0.1:3210 VITE_CONVEX_SITE_URLhttp://127.0.0.1:3211 SITE_URLhttp://localhost:3000 # Convex Auth / HTTP routes CONVEX_SITE_URLhttp://127.0.0.1:3211 # Deployment used by bunx convex dev CONVEX_DEPLOYMENTanonymous:anonymous-clawhub端口约定本地 Convex 在3210端口提供函数端点通过3211端口的站点代理提供 HTTP 路由/api/*与 auth 回调。SITE_URL指向前端开发服务器 3000 端口。三、GitHub OAuth 应用与本地登录ClawHub 使用 GitHub OAuth 完成登录本地开发需要自建一个 OAuth App在 GitHub 开发者设置中创建新的 OAuth AppHomepage URL填http://localhost:3000Authorization 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:30003.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_ENABLED1时本地local:/anonymous:前缀部署要求CONVEX_SITE_URL指向 localhost云端 dev 部署则要求DEV_AUTH_SITE_URL为 localhost 且DEV_AUTH_SECRET长度不少于 32 并与后端一致。四、启动后端与前端4.1 先启动 Convex 后端bunx convex dev --typecheckdisable其他步骤依赖后端先跑起来所以后端要最先启动。--typecheckdisable跳过 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 stopsetup: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:worktreedev: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_SCAN1 bun run dev:workers -- --workers security-scan --once CLAWHUB_ALLOW_LOCAL_CODEX_SCAN1 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:devseed: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 devbunx convex dev --typecheckdisable依然可用缺少.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 --typecheckdisable运行或重跑bun run seed:devseed runner 会在 Convex 完成函数推送期间重试播种时遇到瞬时 Convex 写冲突seed:public-corpus会重试可重试的批量冲突重试耗尽时停止其他本地写入者并重跑bun run seed:dev分离式服务陈旧先wt --yes stop若服务器仍不能干净重启检查.codex/runtime/dev-worktree.log。八、可选环境变量优雅降级以下特性在缺少对应密钥时会优雅降级不会阻断开发变量用途OPENAI_API_KEYEmbeddings 与向量搜索缺失时退化为零向量VT_API_KEYVirusTotal 恶意软件扫描DISCORD_WEBHOOK_URLDiscord 通知九、CLI 开发与验证CLI 源码位于 packages/clawhub/其 package.json 同时注册了clawhub与clawdhub两个 bin 别名。包内依赖commander、clack/prompts、arktype、openclaw/plugin-inspector等提供 install / update / search / publish / scan / verify 等命令。针对本地实例测试 CLICLAWHUB_REGISTRYhttp://127.0.0.1:3211 CLAWHUB_SITEhttp://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 别名所有 PRbun run ci:static源码或测试改动被改动行为的聚焦测试 bun run ci:unit纯文档/配置改动或维护者要求依赖 CI 时可跳过应用运行时、Convex 或构建改动bun run ci:types-build包packages改动bun run ci:packagesHTTP/API/CLI 集成改动bun run ci:e2e-http浏览器冒烟或视觉行为改动bun run ci:playwright-smoke、bun run test:pw:local-auth和/或bun run proof:uibun 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_MODEthrottled或CLAWHUB_LOCAL_CHECK_MODEfull作为逃生通道缺少 Crabbox 认证/provider 访问时应直接报告而不是回退到会拖垮开发机的宽泛本地门禁。10.3 PR 规范保持 PR 聚焦——一个 PR 只解决一个问题使用 Conventional Commits 规范feat:、fix:、chore:、docs:等UI 改动需附带测试命令与截图写清楚改了什么、为什么改。十一、AI 生成代码、安全报告与新手阅读路径AI 生成代码是被欢迎的但提交时需要在 PR 描述中注明说明是 AI 生成/辅助、描述实际施加的测试级别、对评审者有用的 prompt并确认你理解且能维护这段代码。安全漏洞请报告到securityopenclaw.ai附上严重性评估、可复现的技术步骤与建议修复方案moderation 与上传门禁细节见 docs/security.md。新贡献者推荐阅读顺序均为仓库根目录下的相对路径本文本地环境搭建docs/clawhub.md——公开注册表概览docs/quickstart.md——端到端工作流docs/how-it-works.md——注册表行为与系统总览docs/skill-format.md——技能结构docs/cli.md——CLI 参考docs/http-api.md——HTTP 端点docs/auth.md——认证specs/deploy.md——部署docs/troubleshooting.md——常见问题按此顺序阅读可以快速建立从「能跑通本地环境」到「理解注册表架构与发布链路」的完整心智模型。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐Frigate 贡献者开发指南从本地环境搭建到提交 PR 的完整实践Frigate 贡献者开发指南从本地环境搭建到提交 PR 的完整实践 Frigate 是一套面向 IP 摄像头的实时本地目标检测 NVR 系统其代码库横跨人工智能计算机视觉音视频RxDB 贡献指南从环境搭建、测试复现到提交 PR 的完整实践路径RxDB 贡献指南从环境搭建、测试复现到提交 PR 的完整实践路径 RxDB 是一个运行在多种 JavaScript 运行时Node.js、浏览器、Deno数据库NoSQL嵌入式数据库实时数据库CodeSandbox Client 贡献指南从代码组织、本地开发环境搭建到提交 PR 的完整实践CodeSandbox Client 贡献指南从代码组织、本地开发环境搭建到提交 PR 的完整实践 本文以 CodeSandbox Client 仓库的 CO代码编辑器前端开发工具上一篇Ghost-Downloader-3用户行为分析功能使用统计下一篇SDRPlusPlus Git工作流培训新手入门到熟练掌握创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考