<!-- source: https://deepwiki.com/openclaw/openclaw/9.1-contributing -->

# Contributing

- .agents/skills/autoreview/SKILL.md
- .agents/skills/autoreview/scripts/autoreview
- .agents/skills/autoreview/scripts/test-review-harness
- .agents/skills/autoreview/scripts/test-review-harness.ps1
- .agents/skills/autoreview/scripts/test-review-harness.py
- .agents/skills/clawdtributor/SKILL.md
- .agents/skills/crabbox/SKILL.md
- .agents/skills/openclaw-changelog-update/SKILL.md
- .agents/skills/openclaw-ghsa-maintainer/SKILL.md
- .agents/skills/openclaw-landable-bug-sweep/SKILL.md
- .agents/skills/openclaw-landable-bug-sweep/agents/openai.yaml
- .agents/skills/openclaw-pr-maintainer/SKILL.md
- .agents/skills/openclaw-refactor-docs/SKILL.md
- .agents/skills/openclaw-test-performance/SKILL.md
- .agents/skills/openclaw-testing/SKILL.md
- .agents/skills/release-openclaw-ci/SKILL.md
- .agents/skills/release-openclaw-ci/agents/openai.yaml
- .agents/skills/release-openclaw-ci/references/release-ci-notes.md
- .agents/skills/release-openclaw-ci/scripts/release-ci-summary.mjs
- .agents/skills/release-openclaw-ci/scripts/verify-provider-secrets.mjs
- .agents/skills/release-openclaw-mac/SKILL.md
- .agents/skills/release-openclaw-maintainer/SKILL.md
- .agents/skills/release-openclaw-nightly/SKILL.md
- .agents/skills/security-triage/SKILL.md
- .crabbox.yaml
- .github/actions/ensure-base-commit/action.yml
- .github/actions/setup-node-env/action.yml
- .github/actions/setup-pnpm-store-cache/action.yml
- .github/actions/setup-pnpm-store-cache/ensure-node.sh
- .github/codex/prompts/docs-agent.md
- .github/workflows/ci-build-artifacts-testbox.yml
- .github/workflows/ci-check-testbox.yml
- .github/workflows/ci.yml
- .github/workflows/crabbox-hydrate.yml
- .github/workflows/openclaw-cross-os-release-checks-reusable.yml
- .github/workflows/windows-blacksmith-testbox.yml
- .gitignore
- AGENTS.md
- CONTRIBUTING.md
- docs/ci.md
- docs/reference/full-release-validation.md
- qa/scenarios/memory/thread-memory-isolation.md
- scripts/AGENTS.md
- scripts/ci-run-timings.mjs
- scripts/crabbox-wrapper.mjs
- scripts/lib/ci-node-test-plan.mjs
- scripts/lib/docker-build.sh
- scripts/pr-lib/common.sh
- scripts/pr-lib/gates.sh
- src/agents/tools/image-tool.providers.live.test.ts
- test/scripts/ci-node-test-plan.test.ts
- test/scripts/ci-run-timings.test.ts
- test/scripts/ci-workflow-guards.test.ts
- test/scripts/crabbox-wrapper.test.ts
- test/scripts/openclaw-cross-os-release-workflow.test.ts
- test/scripts/package-acceptance-workflow.test.ts
- test/scripts/setup-pnpm-store-cache-ensure-node.test.ts
- test/vitest/vitest.unit-support.config.ts

This page covers contribution guidelines, pull request (PR) workflow, label system, and code review process for the OpenClaw project. It consolidates guidance from `CONTRIBUTING.md`, `AGENTS.md`, and automated triage systems.

## Overview

OpenClaw is a multi-platform AI gateway. Contributions are welcomed for bug fixes, performance improvements, and new features that align with the core vision of a private, extensible AI assistant.

- Bugs & small fixes: Open a PR directly for small patches or bug fixes.
- New features / architecture: Initiate discussion via GitHub Issue or Discord before large feature work. Many new features should be developed as third-party plugins using the SDK.
- Refactor-only PRs: Generally not accepted unless requested by maintainers for specific fixes AGENTS.md 19
- CI/Test-only PRs: Avoid PRs only to fix CI failures on main ; maintainers will handle these.

Sources: [CONTRIBUTING.md1-4](https://github.com/openclaw/openclaw/blob/fbdf5937/CONTRIBUTING.md?plain=1#L1-L4) [CONTRIBUTING.md92-100](https://github.com/openclaw/openclaw/blob/fbdf5937/CONTRIBUTING.md?plain=1#L92-L100) [AGENTS.md1-15](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L1-L15)

## Pull Request Workflow

### Pre-Submission Requirements

Contributors must adhere to the following before submitting PRs:

- Run the gate: Execute pnpm check:changed to run relevant tests, lint, and typechecks on diff files only.
- Verify dependencies: Read upstream dependency docs/source/types before guessing API behavior AGENTS.md 15
- Dependency Gate: If touching Codex related work, the contributor must personally inspect sibling ../codex source for exact protocol/runtime behavior AGENTS.md 14
- Use consistent wording: Use "plugin" or "plugins" in user docs, changelogs, and UI; extensions/ is kept internal AGENTS.md 20
- Real behavior proof: External PRs must include a filled Real behavior proof section in the PR body with details of environment, commands run, and evidence such as logs/screenshots docs/ci.md 52-67

### PR Limits and Automation

- Labeler automation: .github/labeler.yml auto-applies labels based on changed files for triage and CI AGENTS.md 21
- Changelog: Contributors must not edit CHANGELOG.md directly; maintainers manage entries upon merging.
- Preflight: The preflight job in ci.yml classifies the diff and turns off expensive lanes when unrelated areas change docs/ci.md 11 .github/workflows/ci.yml 39-45

Sources: [CONTRIBUTING.md100-111](https://github.com/openclaw/openclaw/blob/fbdf5937/CONTRIBUTING.md?plain=1#L100-L111) [AGENTS.md1-30](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L1-L30) [docs/ci.md11-67](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L11-L67)

## Repository Mapping & Architecture

OpenClaw enforces strict architectural boundaries to maintain modularity:

### Architecture Boundary Rules

- Core Isolation: Core code must remain plugin-agnostic. No bundled IDs or policy should exist in core when manifest/registry contracts suffice AGENTS.md 56
- Import Restrictions: Plugins must not import from core src/** or other plugin src/** . They must use public barrels ( api.ts ) or the SDK AGENTS.md 57-58
- Config Integrity: Runtime reads canonical config only. If a change invalidates existing files, a migration must be added AGENTS.md 60

Sources: [AGENTS.md44-60](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L44-L60)

## Automated Triage and Labels

OpenClaw applies deterministic labels for automated triage and to guide maintainers.

### Review Policy (ClawSweeper)

The `ClawSweeper` review policy governs how automated and human reviews are conducted. It requires reviewers to:

- Read the full root AGENTS.md before judging AGENTS.md 28
- Emit reviewMetrics for changes to config surfaces to name the count and direction of changes AGENTS.md 31
- Check sibling surfaces (e.g., both Codex and Pi-style runtimes) to ensure one-sided fixes don't break alternatives AGENTS.md 32
- Explicitly ask whether the PR is the "best fix", not merely a plausible one AGENTS.md 33

Sources: [AGENTS.md24-40](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L24-L40)

## Testing & Remote Validation

### Testing Hierarchy

- Local Tests: Use pnpm test for fast validation.
- CI Manifest: The preflight job detects docs_only , run_node , run_macos , etc., to build the CI manifest .github/workflows/ci.yml 47-62
- Remote Proof: Use Crabbox for remote Linux proof, broad tests, and CI-parity checks .agents/skills/crabbox/SKILL.md 8-10

### Automated Structured Review

OpenClaw uses a bundled `autoreview` skill to perform structured code reviews using LLM engines.

```

```

Review findings are categorized by priority (P0-P3) and type (bug, security, regression, etc.) [.agents/skills/autoreview/scripts/autoreview29-80](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/autoreview/scripts/autoreview#L29-L80)

Sources: [.agents/skills/autoreview/SKILL.md1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/autoreview/SKILL.md?plain=1#L1-L40) [.agents/skills/autoreview/scripts/autoreview1-100](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/autoreview/scripts/autoreview#L1-L100) [.agents/skills/crabbox/SKILL.md1-30](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/crabbox/SKILL.md?plain=1#L1-L30)

## Bridging Natural Language to Code Entities

### Contribution Workflow Mapping

The following diagram maps the high-level PR submission process to specific GitHub Action workflows and configuration files that handle the verification lifecycle.

```

```

Sources: [.github/workflows/ci.yml39-140](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L39-L140) [.github/actions/setup-pnpm-store-cache/action.yml1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/actions/setup-pnpm-store-cache/action.yml#L1-L40) [docs/ci.md11-50](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L11-L50)

### Extension and Core Boundary

This diagram illustrates how the system enforces separation between the Gateway core and external extensions using the internal `plugin-sdk` and manifest contracts.

```

```

Sources: [AGENTS.md44-60](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L44-L60)

This page outlines the comprehensive guidelines, workflows, and toolchain for contributing to OpenClaw. Following these rules ensures contributions are robust, maintainable, and align with the project's high-quality standards.
