Contributing

better-openclaw is open source and welcomes contributions. Whether you're fixing a bug, adding a service, improving docs, or building a new feature — here's how to get started.

Quick Start for Contributors

# 1. Fork the repository on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/better-openclaw.git
cd better-openclaw

# 3. Install dependencies
pnpm install

# 4. Build all packages
pnpm build

# 5. Run the development server (web)
pnpm --filter web dev

# 6. Run the CLI in dev mode
pnpm --filter cli dev -- test-stack --preset minimal --dry-run

Project Structure

better-openclaw/
├── packages/
│   ├── core/              # Shared logic: services, skills, validation
│   │   ├── src/
│   │   │   ├── services/  # Service definitions
│   │   │   ├── skills/    # Skill pack definitions
│   │   │   ├── presets/   # Preset configurations
│   │   │   ├── generator/ # Stack generation engine
│   │   │   └── validator/ # Configuration validation
│   │   └── package.json
│   ├── cli/               # CLI tool (create-better-openclaw)
│   │   ├── src/
│   │   │   ├── wizard/    # Interactive prompts
│   │   │   ├── commands/  # Command handlers
│   │   │   └── index.ts   # Entry point
│   │   └── package.json
│   └── web/               # Next.js website + API
│       ├── src/
│       │   ├── app/       # Next.js App Router pages
│       │   ├── components/# React components
│       │   └── lib/       # Utilities
│       └── package.json
├── pnpm-workspace.yaml
├── package.json
└── turbo.json

Development Setup

Prerequisites

  • Node.js 20+
  • pnpm 9+ (npm install -g pnpm)
  • Docker (for testing generated stacks)

Running Locally

# Install all dependencies
pnpm install

# Build the core package (required by CLI and web)
pnpm --filter @better-openclaw/core build

# Start the web dev server
pnpm --filter web dev
# → http://localhost:3000

# Run the CLI
pnpm --filter cli dev -- my-stack --preset researcher --dry-run

# Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter @better-openclaw/core test

# Lint
pnpm lint

# Type check
pnpm typecheck

Watch Mode

For rapid iteration, run the core package in watch mode while developing:

# Terminal 1: Watch core for changes
pnpm --filter @better-openclaw/core dev

# Terminal 2: Run web dev server (auto-reloads with core changes)
pnpm --filter web dev

Contribution Types

Adding a New Service

See the Adding Services guide for the full walkthrough. In summary:

  1. Create a new file in packages/core/src/services/[category]/
  2. Implement the ServiceDefinition interface
  3. Register it in the category index and main service registry
  4. Test with --dry-run and then with docker compose up
  5. Submit a PR

Adding a Skill Pack

  1. Create skill YAML files in packages/core/src/skills/[pack-name]/
  2. Create the pack definition in packages/core/src/skills/[pack-name]/index.ts
  3. Register in the skill pack index
  4. Add required service mappings
  5. Test with the CLI

Bug Fixes

  1. Check existing issues first
  2. Create an issue if one doesn't exist
  3. Reference the issue number in your PR
  4. Add a test case that reproduces the bug

Documentation

  • Docs pages live in packages/web/src/app/docs/
  • Each page is a Next.js page component
  • Follow the existing patterns (metadata export, semantic HTML, prose classes)

Pull Request Guidelines

Before Submitting

  • Run the full test suite: pnpm test
  • Check types: pnpm typecheck
  • Lint your code: pnpm lint
  • Build everything: pnpm build
  • Test manually if you changed generation logic

PR Format

## What

Brief description of the change.

## Why

Why this change is needed.

## How

Implementation approach / key decisions.

## Testing

- [ ] Unit tests pass
- [ ] Manual testing done
- [ ] Dry-run output verified
- [ ] Docker compose up works (if applicable)

## Related Issues

Closes #123

Commit Messages

Follow Conventional Commits:

feat(core): add Meilisearch service definition
fix(cli): handle missing Docker on wizard start
docs(web): add skill packs reference page
chore: update dependencies

Code Style

  • TypeScript with strict mode
  • Prettier for formatting (runs automatically on commit via lint-staged)
  • ESLint for linting
  • Prefer const over let
  • Prefer named exports
  • Add JSDoc comments for public APIs

Development Tips

Testing Service Definitions

# Quick test: dry-run a stack with your new service
pnpm --filter cli dev -- test-stack \
  --services your-new-service,redis \
  --dry-run

# Full test: actually generate and run
pnpm --filter cli dev -- test-stack \
  --services your-new-service,redis \
  --yes

cd test-stack
docker compose up -d
docker compose ps
docker compose logs your-new-service

Debugging the Web App

# Run in dev mode with verbose logging
DEBUG=* pnpm --filter web dev

# Check the API endpoint locally
curl http://localhost:3000/api/v1/services | jq

Getting Help

License

better-openclaw is MIT licensed. By contributing, you agree that your contributions will be licensed under the same MIT License.