GitHub OpenClaw: Contributing to the Open Source Project

OpenClaw is open source. The full codebase lives at github.com/openclaw/openclaw and contributions from the community — bug fixes, new skills, documentation improvements, feature requests — are how the project evolves. This guide covers everything you need to go from "interested" to "merged PR."

The Repository at a Glance

github.com/openclaw/openclaw

Before contributing, spend 20 minutes reading the repo. The structure is straightforward:

openclaw/
├── src/                  ← core application code
│   ├── agent/            ← agent runtime
│   ├── gateway/          ← gateway service
│   ├── skills/           ← built-in skills
│   └── api/              ← REST API
├── docs/                 ← documentation source (Markdown)
├── scripts/              ← build and utility scripts
├── tests/                ← test suite
├── assets/
│   └── brand/            ← logo files and brand assets
├── package.json
├── CONTRIBUTING.md       ← read this before anything else
└── README.md

The src/skills/ directory is particularly relevant if you want to contribute new built-in skills. Each skill follows the same structure covered in the OpenClaw Skill creation guide.

Read CONTRIBUTING.md First

Before opening a PR, read CONTRIBUTING.md. It's short. It covers the things maintainers care about, the things that will get your PR rejected, and the local dev setup steps. Most first-time contributors who get a quick rejection skipped this file.

Key points typically covered:

• Code style and formatting requirements
• Commit message format
• Test requirements (does your change need a test?)
• Which branches to target
• How to handle breaking changes

Forking and Setting Up Locally

Fork the Repo

Click Fork on the GitHub repo page. This creates your own copy at github.com/YOUR_USERNAME/openclaw.

Clone Your Fork

git clone https://github.com/YOUR_USERNAME/openclaw.git
cd openclaw

Add the Upstream Remote

This lets you pull in changes from the main repo:

git remote add upstream https://github.com/openclaw/openclaw.git
git remote -v
# origin    https://github.com/YOUR_USERNAME/openclaw.git (fetch)
# upstream  https://github.com/openclaw/openclaw.git (fetch)

Install Dependencies

npm install

Run the Dev Setup

npm run dev

This starts OpenClaw in development mode with hot reloading. Changes to src/ files apply immediately without a full restart.

Verify It Works

openclaw --version
# or
node src/index.js --version

If you see the version number, the dev environment is working.

Running the Test Suite

Before submitting any PR, run the full test suite:

npm test

If tests fail on a clean checkout of the main branch, document that in your PR — it means there's a pre-existing issue. Your contribution should not introduce new test failures.

For specific test files:

npm test -- --grep "gateway"     # run only gateway tests
npm test -- tests/skills/        # run tests in a specific directory

The Contribution Workflow

Step 1: Create a Branch

Never work directly on main. Create a descriptive branch:

git checkout -b fix/gateway-port-binding
# or
git checkout -b feature/skill-tmux-output
# or
git checkout -b docs/update-install-guide

Branch prefixes that communicate intent:

• fix/ — bug fixes
• feature/ — new functionality
• docs/ — documentation only
• refactor/ — code changes with no behavior change
• test/ — adding or fixing tests

Step 2: Make Your Changes

Make your changes, commit frequently. Each commit should be a logical unit of work:

git add -p                        # stage hunks selectively
git commit -m "fix: resolve gateway failing to bind on IPv6 hosts"

Follow the commit message convention in CONTRIBUTING.md. Most OpenClaw projects use conventional commits:

type(scope): short description

Longer explanation if needed. What problem does this solve?
What was the old behavior, what is the new behavior?

Fixes #123

Types: fix, feat, docs, refactor, test, chore

Step 3: Keep Your Branch Current

Before submitting, pull in any upstream changes to avoid conflicts:

git fetch upstream
git rebase upstream/main

Resolve any conflicts, then verify tests still pass:

npm test

Step 4: Push and Open the PR

git push origin fix/gateway-port-binding

Then open a PR on GitHub. The UI will show your branch and prompt you to create the pull request.

PR title: Match the format of your primary commit message.

PR description: Fill out the template (if one exists). At minimum include:

• What problem this solves
• How you tested it
• Any related issues (Closes #123)

Opening Issues

Good issues get attention. Bad issues sit open for months.

For bug reports, include:

• OpenClaw version (openclaw --version)
• OS and OS version
• Node.js version (node --version)
• Exact error message (full stack trace, not just the last line)
• Steps to reproduce — numbered, exact
• Expected behavior vs. actual behavior

For feature requests, include:

• The use case driving the request (not just the feature)
• What you tried that didn't work
• Whether you'd be willing to implement it

Search before opening. The issue tracker has years of history. Your bug may already have a fix in an unreleased branch, or your feature request may already be in progress.

Use labels appropriately. If the repo has labels like bug, enhancement, documentation, good first issue, apply the right ones. Maintainers triage by label.

Good First Issues

New to the codebase? Look for issues labeled good first issue. These are scoped problems with clear acceptance criteria where a contributor who doesn't know the codebase can still make a meaningful fix.

The documentation in /docs/ is always a safe place to start — fixing typos, updating outdated examples, and improving explanations require no deep code knowledge and are consistently appreciated by maintainers.

Community and Communication

GitHub Discussions

OpenClaw uses GitHub Discussions for:

• General questions about the project
• Ideas and RFC-style proposals before they become issues
• Showcasing what you've built with OpenClaw

Before opening an issue for a question, check Discussions. Many common questions are already answered there.

Discord

The OpenClaw Discord (linked from the GitHub README) is active. It's the right place for:

• Real-time troubleshooting
• Getting feedback on a contribution before you write all the code
• Community showcase — share what you've built

Code Review Culture

OpenClaw maintainers review PRs thoroughly. Expect feedback. Expect change requests. This isn't a rejection — it's how open source works.

Respond to feedback promptly. PRs that go silent for weeks get de-prioritized. If you need more time, comment saying so.

When a reviewer asks a question, answer it even if you made the change they requested. The comment thread is documentation for future contributors reading git blame.

What the Project Needs Most

Based on the issue tracker and maintainer comments, the areas with the most opportunity for contribution:

Built-in skills. New skills that cover common use cases — calendar integration, task management, notification routing — are frequently requested and straightforward to build if you know the skill anatomy.

Documentation. Gaps in the docs are frequently noted by new users. Adding examples, clarifying confusing sections, and documenting undocumented behavior are high-value low-friction contributions.

Test coverage. Specific modules have low test coverage. If you see a file with no corresponding test file, that's an opportunity.

Bug fixes. Filter issues by bug label, find one that affects you or that you understand, and fix it. Maintainers love when contributors fix their own bugs.

Keeping Your Fork Healthy

If you maintain a fork long-term (for personal modifications, not just a contribution), keep it synced:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Stale forks that diverge significantly from main become painful to maintain. Sync weekly if you're actively working with the fork.

---

Contributing to OpenClaw means building tools you'll use yourself. The codebase is clean, the maintainers are responsive, and the skill system is specifically designed to make contribution accessible without requiring deep knowledge of the core runtime.

Want to see what a production OpenClaw deployment looks like? Study the repo structure, workflows, and verification patterns that keep a live setup stable.