Contributing to OpenClaw

Getting Started

Before writing any code, make sure you have the development environment set up correctly:

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/openclaw.git
cd openclaw

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\Activate.ps1    # Windows PowerShell

# Install in development mode with all dev dependencies
pip install -e ".[dev,test,docs]"

# Verify the installation works
openclaw --version
pytest tests/ -x --tb=short     # run tests, fail fast

All tests should pass on a fresh clone of main. If tests fail, open a "tests broken on main" issue before proceeding.

Types of Contributions

For anything beyond small bug fixes and documentation, open an issue to discuss before implementing. This prevents the disappointment of having a large PR rejected because it doesn't align with the project direction — the maintainers would rather discuss it upfront than review code that can't be merged.

Pull Request Process

All contributions are submitted as pull requests on GitHub. A high-quality PR includes:

• Tests for all new functionality (see Testing Guide)
• Documentation updates for any changed or added behavior
• Changelog entry in CHANGELOG.md under "Unreleased"
• Clean commit history — squash fixup commits before requesting review

# Create a feature branch
git checkout -b feat/add-database-query-tool

# Make your changes, commit with clear messages
git add -p        # stage changes interactively
git commit -m "feat(tools): add SQL database query tool with parameterized queries"

# Push and open PR
git push origin feat/add-database-query-tool
# Then open PR on GitHub

We use Conventional Commits for commit messages. Prefix with feat:, fix:, docs:, refactor:, test:, or chore: accordingly.

Code Standards

OpenClaw uses automated linting and formatting to enforce consistent code style:

# Format code
black openclaw/ tests/

# Lint
ruff check openclaw/ tests/

# Type check
mypy openclaw/ --strict

# Run all checks at once (also runs in CI)
make check

All checks must pass before a PR can be merged. The CI pipeline enforces this automatically. VSCode users can install the ms-python.black-formatter and charliermarsh.ruff extensions to get formatting and lint on save.

The Review Cycle

Expect at least one round of review feedback on any non-trivial PR. Reviewers look for correctness, test coverage, performance implications, security considerations, and consistency with the existing codebase style. Address all reviewer comments — if you disagree with a request, explain why in a reply and we'll find a resolution collaboratively. Once a core maintainer approves and CI passes, your PR will be merged, typically within a few days of final approval.

Your First Contribution: Step by Step

The best first contribution is fixing a bug labeled good first issue on GitHub. Here's a complete walkthrough of the process:

Find an issue you want to fix, add a comment saying "I'm working on this" — this prevents duplicate work. Fork the repository on GitHub if you haven't already. Clone your fork, create a branch named after the issue (fix/issue-123-tool-timeout), and reproduce the bug locally before making any changes to confirm you understand what's broken.

Read the existing implementation for the area you're changing. Understand the patterns, naming conventions, and test structure. Check existing tests for similar functionality — they're the fastest way to understand how the system works and what your fix needs to be consistent with.

Make your fix, then write tests that reproduce the bug (they should fail before your fix and pass after). Run the full unit test suite to confirm you haven't introduced regressions. Update any documentation that references the behavior you changed. Push your branch and open a pull request using the PR template on GitHub.

Documentation Contributions

Documentation improvements are among the highest-value contributions to any open-source project, and they're often overlooked in favor of code changes. The OpenClaw documentation site is a static site built from HTML files in the main repository — every page can be edited like a code file.

Good documentation contributions include: fixing inaccuracies (when documentation describes behavior that has changed), adding examples (a working code example is worth three paragraphs of prose), clarifying ambiguous explanations (if you spent 20 minutes confused by a section, others will too — fix it), and translating concepts for an audience that might not share the author's background assumptions (don't assume everyone knows what HMAC is).

Documentation PRs follow the same process as code PRs — they're reviewed for accuracy, clarity, and consistency with the rest of the docs. A documentation PR that fixes a genuine confusing spot in the docs will almost always be merged quickly.

Becoming a Maintainer

OpenClaw maintainers are community contributors who have demonstrated sustained, high-quality contributions over time. There's no formal application process — maintainer status is extended as a recognition of proven commitment and judgment. Typical path: start with documentation fixes and small bug fixes, graduate to implementing new features or fixing complex bugs, begin reviewing other contributors' PRs, and after 6-12 months of active contribution, maintainers will propose you for commit access via a GitHub team invitation.