Maintainer Handbook

This is the working agreement for OpenClaw maintainers. It covers the rules that are easy to miss when you only read one repo: release branches, plugin distribution, PR handling, validation, security, maintainer tooling, reports, and the repo map.

Use this as the first stop for maintainer context, then follow the linked source docs when you need the full operational detail.

Start Here

  • Read Release Branches before validating release-sensitive work. main is not always the deployed line.
  • Read Plugin Ecosystem before touching install, uninstall, plugin update, plugin packaging, or SDK behavior.
  • Read Review And Validation before handing off a PR or relying on CI.
  • Read PR Operations before processing queue items or duplicate PR clusters.
  • Read Security before touching GHSA, CVE, advisory, sandbox, auth, or hardening work.
  • Read Tooling Setup when setting up a maintainer or trial maintainer machine.
  • Read Reports And Data to understand what powers reports.openclaw.ai.
  • Read Repo Map when you need to know which repo owns a surface.

Operating Model

  • Prefer visible coordination in maintainer channels. Silent parallel work creates duplicate fixes and broken assumptions.
  • Keep release-sensitive fixes tied to the release branch that will ship them.
  • Treat plugin install and update behavior as high-blast-radius product behavior, not ordinary package plumbing.
  • Use small, scoped validation for narrow changes and Crabbox or Blacksmith Testbox for broad, slow, Docker, E2E, release, or CI-parity checks.
  • Do not rely on CI or ClawSweeper to do maintainer judgment for you. They are backstops, not brains.
  • Keep user-facing copy human. CLI, onboarding, slash command, and channel text should be readable by a non-technical operator unless the surface is explicitly developer-only.

What Warrants A Conversation

  • Anything you are unsure about.
  • Onboarding flow changes.
  • Large changes, roughly 30+ non-doc files or 5k+ LOC.
  • Adding, removing, or externalizing a plugin.
  • Root dependency changes in package.json.
  • Slash command changes to messaging channels.
  • New config items or plugin SDK seams.
  • Adding any new repositories to the OpenClaw organization. This is blocked and requires admin approval.
  • Security-related issues. Use #maintainer-security-ops.

Source Docs