If you landed here after typing “how to contribute to OpenClaw open source development guide,” you probably have the repo open in another tab, wondering which file to touch first. Good. This post distills what I wish I knew before sending my first patch to OpenClaw v0.32.1 (the current mainline at the time of writing). It covers directory anatomy, dev setup, tests, contribution etiquette, and how the incoming foundation governance changes the process.
Repository layout: where the bodies are buried
OpenClaw grew fast. Understanding the tree is half the battle. Here is the high-level map you will see after a fresh clone:
$ tree -L 2 -I 'node_modules|.git'
.
├── apps
│ ├── gateway # Next.js UI (TypeScript)
│ └── daemon # Long-running agent host (TS)
├── packages
│ ├── core # Shared logic, agent kernel
│ ├── integrations # 800+ Composio wrappers
│ ├── memory # Vector + KV abstractions
│ └── sdk # Client SDK used by bots
├── scripts # CLI helpers, release scripts
├── docs # Docusaurus site (don’t miss /architecture)
├── .github # Issue templates, workflows
├── pnpm-workspace.yaml # Monorepo glue
└── tsconfig.base.json # Strict shared TS config
Three things that bite newcomers:
- Monorepo – managed with
pnpm@9and workspaces. Yarn works in a pinch but the lockfile will fight you. - E2E vs unit tests – unit tests live beside source files, E2E lives under
tests/e2eand boots an in-memory gateway + daemon. - Generated code – anything in
/packages/*/generatedis auto-built from OpenAPI/Proto; don’t edit by hand.
Setting up a local development environment
Prerequisites
- Node.js 22.2.0+ (ESM-only, no
require()fallback) - pnpm 9.x (
npm i -g pnpm) - Redis 7 (for memory tests) and Docker if you want Postgres integration
- Make (optional) – some scripts use
make test
Bootstrap commands
$ git clone https://github.com/openclaw/openclaw.git
$ cd openclaw
# install deps for all workspaces
$ pnpm install
# build TS -> ESM once; incremental rebuild handled by dev scripts
$ pnpm build
If you only plan to poke at one package, add -F @openclaw/package-name to scope installs/builds and save CPU.
Running everything
# 1. Start Redis (and Postgres if you need it)
$ docker compose up -d redis postgres
# 2. In one terminal: gateway (Next.js)
$ pnpm --filter @openclaw/gateway dev
# 3. In another: daemon with hot-reload
$ pnpm --filter @openclaw/daemon dev
# 4. Visit http://localhost:4369 (default)
The gateway will auto-detect the local daemon via WebSocket. If you see “Waiting for Claw handshake” check that both are on matching OPENCLAW_SECRET (defaults to devdevdev).
Testing & linting requirements
Every pull request triggers the ci.yml workflow: lint → unit → e2e → type-check → build. Fail any step and the PR stays red. Run locally to avoid waiting for CI:
# type-check only the packages you touched
$ pnpm tsc -b packages/core packages/gateway
# Jest unit tests with coverage
$ pnpm test --filter ./packages/core
# Playwright E2E (headless Chrome)
$ pnpm e2e
Coverage threshold is 80% lines; fall below and CI blocks merge. Tests live beside source files so PR diff stats stay honest.
Contribution guidelines: from issue to merged PR
1. Search before you file
Duplicate issues burn maintainer energy. GitHub’s “similiar issues” helps, but also grep the codebase; a lot of TODOs live in comments.
2. Open an issue (feature, bug, or RFC)
Use the provided template. If you skip the repro steps, expect a friendly nudge to add them before anyone labels the issue.
3. Get the green light
For changes over ~20 LOC, wait for a maintainer (“/cc @openclaw/maintainers”) to tag good-first-issue or accepted. Unsolicited large PRs often stall.
4. Fork & code
Fork the repo, create a branch (git checkout -b feat/emoji-reactor), commit with pnpm commit which uses commitlint@18 to enforce Conventional Commits.
5. Push & open PR
PR title should follow <type>: <scope> <subject>. Examples:
fix: gateway crash on empty tool responsefeat(memory): pluggable embedding provider
6. Link issue & fill checklist
PR description starts with Closes #1234. Then tick the markdown checklist: tests added, docs updated, bump notes added.
7. Review & CI
At least one maintainer review + passing CI is required. Two for code touching /packages/core.
8. Merge strategy
Squash-merge only. Keep the tree linear; rebase if GitHub says “can’t automatically merge.”
AI/vibe-coded PRs: what that README joke actually means
The README ends with “AI/vibe-coded PRs welcome!” – a nod to fans who submit stylistic improvements generated by LLMs. They are welcome as long as they meet three rules:
- Substantive – not just renaming variables or re-ordering imports.
- Explain the prompt – add a comment summarizing what you asked the model to do.
- Pass the tests – the robot code must live by the same CI as human code.
We’ve merged AI-authored documentation tweaks, YAML fixes, even a first draft of the Signal transport. If you want to try, declare authorship clearly (Co-Authored-By tag) to stay license-compliant.
Architectural hotspots worth knowing before editing
This is the “advanced” cluster after all. A few files see the most foot traffic and warrant extra scrutiny:
| Path | Why it matters |
|---|---|
/packages/core/src/agent/index.ts | Main agent loop, tool invocation orchestration, and error boundaries. |
/packages/core/src/providers/* | LLM provider interfaces; shared by browser and server paths. |
/packages/daemon/src/runtime/sandbox.ts | Shell & browser sandbox. Security sensitive. |
/apps/gateway/pages/api/* | Next.js API routes – attack surface for user input. |
Touching any of these will trigger the security-review label and require two maintainer approvals plus an automated npm audit gate.
Transition to foundation governance
On May 3, 2024 Peter announced that OpenClaw is moving to a non-profit foundation, similar to CNCF or Apache, “to keep the claws out of any single company” (his words). What’s changing for contributors?
- CLA becomes DCO – No more signing a PDF. Instead, add
Signed-off-by: Your Name <email@domain>to commits. - New maintainer tiers – Core, Review, Triage. If you consistently review PRs, you can request the Review badge without direct write access.
- Decision log – Architectural decisions go to
/docs/adr/. Include an ADR in your PR if you change something big. - Release cadence – Monthly minor releases, quarterly LTS, each tagged and signed by the foundation’s key.
The transition is in flight; expect the DCO bot to start blocking unsigned commits as early as next week. Update your ~/.gitconfig now:
[commit]
gpgsign = true
# Automatically add Signed-off-by
template = ~/.gitmessage-dco
Sample workflow: trivial bugfix to merged in 30 minutes
- Find an issue: #1337 “typo in telegram transport”.
- Fork & clone:
git clone git@github.com:youruser/openclaw.git - Create branch:
git checkout -b fix/telegram-typo - Edit: correct variable name in
/packages/integrations/src/telegram.ts - Test:
pnpm test --filter @openclaw/integrations(all green) - Commit:
$ git commit -a -s -m "fix(integrations): correct TelegramBotApi typo" - Push & PR: GitHub auto-links to fork; open PR.
- Wait for CI: 6 min average.
- Review: Maintainer approves, squash-merge.
- Changelog: Your commit auto-lands in next release notes.
Total wall clock last week: 28 minutes. The longest part was CI.
Community culture & where to ask questions
- Discord – #contributors is active, but thread your questions. Maintainers skim during Euro daytime (UTC+1).
- GitHub Discussions – Better for design questions; searchable and persists.
- Weekly dev call – Fridays 16:00 UTC on Jitsi. Agenda in
/docs/meeting-notes. - Code of Conduct – We use Contributor Covenant 2.1. Short version: be kind, no AI hate, no gatekeeping.
People notice and appreciate well-researched questions. Link to the line numbers and include stack traces. “It doesn’t work” rarely gets a reply.
Takeaway: your next step
Pick any good-first-issue, clone, run pnpm install, and push a signed commit. If CI passes, you’ll likely see your name in the next release notes – and maybe an invite to join the Review tier. Happy hacking.