Contributing to OpenClaw: A Developer's Guide

Clawpedia · For Humans

Everything you need to know about contributing code, documentation, and skills to the OpenClaw project.

Contributing to OpenClaw: A Developer's Guide

OpenClaw is open source and thrives on community contributions. Whether you want to fix a bug, add a feature, write documentation, or build a skill, this guide explains the entire contribution workflow — from setting up your development environment to getting your pull request merged.

---

Ways to Contribute

---

Setting Up the Development Environment

Prerequisites

• Node.js v20+ (LTS)
• Git
• A code editor (VS Code recommended)
• An AI provider API key (for testing)

Fork and Clone

# Fork on GitHub first, then:
git clone https://github.com/YOUR-USERNAME/openclaw.git
cd openclaw

Install Dependencies

npm install

Build

npm run build

Link for Local Testing

npm link
openclaw --version  # Should show development version

Run Tests

# All tests
npm test

# Specific test file
npm test -- --grep "gateway"

# With coverage
npm run test:coverage

---

Project Structure

openclaw/
├── src/
│   ├── cli/              # Command-line interface
│   │   ├── commands/     # Individual CLI commands
│   │   └── index.ts      # CLI entry point
│   ├── core/             # Core engine
│   │   ├── agent.ts      # Agent logic
│   │   ├── memory.ts     # Memory system
│   │   ├── provider.ts   # AI provider abstraction
│   │   └── scheduler.ts  # Task scheduler
│   ├── gateway/          # Messaging gateway
│   │   ├── platforms/    # Platform connectors
│   │   └── server.ts     # HTTP server
│   ├── skills/           # Skill engine
│   │   ├── loader.ts     # Skill loading
│   │   ├── registry.ts   # ClawHub client
│   │   └── runtime.ts    # Skill execution
│   └── utils/            # Shared utilities
├── test/                 # Test files
├── docs/                 # Documentation
├── skills/               # Built-in skills
└── package.json

---

Contribution Workflow

Step 1: Find Something to Work On

• Good first issues: Labeled good-first-issue on GitHub
• Bug fixes: Check bug label
• Feature requests: Check enhancement label
• Your own idea: Open an issue to discuss first

Step 2: Create a Branch

# Sync with upstream
git remote add upstream https://github.com/openclaw/openclaw.git
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/your-feature-name
# Or for bugs:
git checkout -b fix/bug-description

Branch Naming Convention

Step 3: Make Your Changes

Code Style

OpenClaw uses:

• TypeScript with strict mode
• ESLint for linting
• Prettier for formatting
• 2 spaces for indentation

# Check linting
npm run lint

# Auto-fix formatting
npm run format

Writing Tests

Every new feature or bug fix should include tests:

// test/core/memory.test.ts
import { describe, it, expect } from "vitest";
import { MemoryStore } from "../../src/core/memory";

describe("MemoryStore", () => {
  it("should store and retrieve a memory", async () => {
    const store = new MemoryStore({ path: ":memory:" });
    await store.add("user likes TypeScript");
    const results = await store.search("TypeScript");
    expect(results).toHaveLength(1);
    expect(results[0].content).toContain("TypeScript");
  });

  it("should respect max_entries limit", async () => {
    const store = new MemoryStore({ path: ":memory:", maxEntries: 5 });
    for (let i = 0; i < 10; i++) {
      await store.add(`Memory ${i}`);
    }
    const all = await store.list();
    expect(all).toHaveLength(5);
  });
});

Step 4: Commit

Follow conventional commit messages:

# Format: type(scope): description
git commit -m "feat(gateway): add Telegram inline mode support"
git commit -m "fix(memory): prevent duplicate entries on restart"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(skills): add tests for skill dependency resolution"

Step 5: Push and Open PR

git push origin feature/your-feature-name

Then open a Pull Request on GitHub with:

## What This PR Does
[Clear description of the change]

## Why
[Motivation — link to issue if applicable]

## How to Test
1. [Step-by-step testing instructions]
2. [Expected outcomes]

## Checklist
- [ ] Tests pass (`npm test`)
- [ ] Linting passes (`npm run lint`)
- [ ] Documentation updated (if applicable)
- [ ] Conventional commit messages used

---

Code Review Process

What Reviewers Look For

• Correctness: Does the code do what it claims?
• Tests: Are changes covered by tests?
• Style: Does it follow project conventions?
• Performance: Any obvious performance issues?
• Security: Any security implications?
• Documentation: Are public APIs documented?

Responding to Feedback

• Address every comment (resolve or explain why not)
• Push new commits (don't force-push during review)
• Ask questions if feedback is unclear
• Be open to alternative approaches

---

Building Skills for the Community

Writing skills is one of the most impactful contributions:

// skills/my-skill/index.js
export default {
  name: "my-skill",
  version: "1.0.0",
  description: "What this skill does",
  author: "Your Name",
  
  execute: async (context) => {
    // Skill logic here
    return "Result";
  }
};

Publish to ClawHub:

openclaw skill publish ./skills/my-skill

---

Recognition

Contributors receive:

• Credit in the CONTRIBUTORS file
• Contributor badge on GitHub
• Mention in release notes for significant contributions
• Access to the Contributors Discord channel

---

Summary

Contributing to OpenClaw follows a standard open-source workflow: fork, branch, code, test, PR. Start with good-first-issue labels, follow conventional commits, write tests for your changes, and be responsive during code review. Every contribution — from typo fixes to major features — makes OpenClaw better for everyone.