<!-- source: https://deepwiki.com/openclaw/openclaw/9-development -->

# Development

- .agents/skills/crabbox/SKILL.md
- .agents/skills/openclaw-testing/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/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
- AGENTS.md
- CONTRIBUTING.md
- docs/ci.md
- docs/help/testing.md
- docs/reference/full-release-validation.md
- extensions/discord/src/durable-delivery.test.ts
- 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/run-vitest.mjs
- scripts/test-projects.test-support.mjs
- scripts/verify.mjs
- src/agents/embedded-agent-helpers/errors-provider-structured-signals.test.ts
- src/agents/embedded-agent-helpers/provider-error-patterns.ts
- src/agents/tools/image-tool.providers.live.test.ts
- src/auto-reply/reply/completion-delivery-policy.test.ts
- src/scripts/test-projects.test.ts
- test/AGENTS.md
- test/CLAUDE.md
- 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/run-vitest.test.ts
- test/scripts/setup-pnpm-store-cache-ensure-node.test.ts
- test/scripts/test-projects.test.ts
- test/scripts/verify.test.ts
- test/vitest-projects-config.test.ts
- test/vitest-unit-fast-config.test.ts
- test/vitest/vitest.commands.config.ts
- test/vitest/vitest.config.ts
- test/vitest/vitest.full-core-unit-fast.config.ts
- test/vitest/vitest.infra.config.ts
- test/vitest/vitest.scoped-config.ts
- test/vitest/vitest.test-shards.mjs
- test/vitest/vitest.ui-paths.mjs
- test/vitest/vitest.ui.config.ts
- test/vitest/vitest.unit-fast-fake-timers.config.ts
- test/vitest/vitest.unit-fast-paths.mjs
- test/vitest/vitest.unit-support.config.ts
- test/vitest/vitest.unit-ui.config.ts

This page provides a high-level overview of guidelines for contributing to OpenClaw, the repository organization, and typical development workflows. OpenClaw is structured as a multi-platform TypeScript monorepo leveraging modern tooling and strict architectural boundaries to facilitate scalable, maintainable, and extensible development.

## Contributing

OpenClaw employs a collaborative model welcoming contributions such as bug fixes, new features, and improvements following established workflows and guidelines defined in the repository files `AGENTS.md` and `CONTRIBUTING.md`.

Key points to note:

- Pull Request Workflow: PRs are labeled with a detailed taxonomy reflecting size and affected system parts. New surfaces require updates to .github/labeler.yml AGENTS.md 21
- Code Ownership: Security-sensitive areas and significant product or architecture changes require maintainer review. Larger behavior or security changes must involve an owner review AGENTS.md 19
- Real Behavior Proof: Contributors must supply proof for fixes including source references, tests, and dependency contracts. Validation is judged against touched and sibling surfaces AGENTS.md 38
- Architectural Integrity: The core stays plugin-agnostic. Plugins interface with core only through the SDK facade at openclaw/plugin-sdk/* AGENTS.md 56-57
- Dependency Inspection: Direct dependency inspection is mandatory when touching external integrations. Most dependencies are OSS, and their source/docs/types must be read rather than assumed AGENTS.md 14-15

For in-depth contribution instructions, PR processes, labeling system, and code review practices, see the **Contributing** subpage.

Sources: [AGENTS.md14-57](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L14-L57)

## Project Structure

OpenClaw is architected as a **pnpm workspace** monorepo supporting integrated development and clear separation of concerns.

### Core Repository Layout

### Monorepo Management Highlights

- pnpm Workspaces: The repository uses pnpm for efficient dependency management across the core, apps, and extensions AGENTS.md 44
- Boundary Enforcement: Plugin production code is forbidden from directly importing core src/** or other plugin internal source code AGENTS.md 58
- Shared Packages Layer: Core logic is factored into reusable packages under packages/ , including gateway-protocol , agent-core , sdk , and llm-core AGENTS.md 44

For a full explanation of repository layout, package organization, and monorepo management conventions, please see **Project Structure**.

Sources: [AGENTS.md29-58](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1#L29-L58)

## Development Workflow

OpenClaw emphasizes an efficient developer experience, utilizing scoped testing and automated validation through the Crabbox remote execution wrapper.

### Typical Local Development Cycle

1. Initial Setup: Run pnpm install to hydrate the workspace. If dependencies are missing, scripts will report an actionable error AGENTS.md 18 test/scripts/run-vitest.test.ts 53-56
2. Validation: Use scripts/test-projects.test-support.mjs to resolve changed lanes and run targeted tests based on git diffs scripts/test-projects.test-support.mjs 49-51
3. Testing: Execute tests via Vitest using scoped configurations such as test/vitest/vitest.unit.config.ts or test/vitest/vitest.tooling.config.ts scripts/test-projects.test-support.mjs 59-118
4. Remote Validation: Leverage crabbox for remote Linux, macOS, or Windows validation to ensure CI parity and environment-specific proof .agents/skills/crabbox/SKILL.md 8-10

### Bridging Natural Language Commands to Code Entities

```

```

### CI/CD Pipeline and Test Sharding

```

```

For exhaustive details on local development setup, hot module reloading, debugging, and Windows-specific considerations, see **Development Workflow**.

Sources: [scripts/test-projects.test-support.mjs49-118](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L49-L118) [scripts/run-vitest.mjs1-21](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/run-vitest.mjs#L1-L21) [.agents/skills/crabbox/SKILL.md1-30](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/crabbox/SKILL.md?plain=1#L1-L30) [.github/workflows/ci.yml39-77](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L39-L77)

This high-level overview outlines how contributing guidelines, project structure, and development workflows integrate cohesively in the OpenClaw codebase. For greater technical depth and procedural details, refer to the linked child pages below:

- Contributing - Contribution guidelines, PR workflow, label taxonomy, and code review.
- Project Structure - Detailed repo layout, monorepo management, and package organization.
- Development Workflow - Developer setup, local runtime, hot reload, debugging, and testing practices.

Sources: [AGENTS.md](https://github.com/openclaw/openclaw/blob/fbdf5937/AGENTS.md?plain=1) [test/scripts/package-acceptance-workflow.test.ts5-22](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L5-L22) [docs/ci.md13-35](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L13-L35)
