<!-- source: https://deepwiki.com/openclaw/openclaw/9.2-project-structure -->

# Project Structure

- docs/.generated/plugin-sdk-api-baseline.sha256
- docs/plugins/plugin-inventory.md
- docs/plugins/reference.md
- docs/plugins/sdk-migration.md
- docs/plugins/sdk-subpaths.md
- extensions/acpx/npm-shrinkwrap.json
- extensions/amazon-bedrock-mantle/npm-shrinkwrap.json
- extensions/amazon-bedrock/npm-shrinkwrap.json
- extensions/anthropic-vertex/npm-shrinkwrap.json
- extensions/codex/npm-shrinkwrap.json
- extensions/diagnostics-otel/npm-shrinkwrap.json
- extensions/discord/index.ts
- extensions/discord/npm-shrinkwrap.json
- extensions/google-meet/src/realtime-node.ts
- extensions/google-meet/src/realtime.ts
- extensions/memory-core/src/memory/provider-adapters.ts
- extensions/memory-lancedb/npm-shrinkwrap.json
- extensions/msteams/npm-shrinkwrap.json
- extensions/tsconfig.package-boundary.paths.json
- extensions/twitch/npm-shrinkwrap.json
- extensions/whatsapp/npm-shrinkwrap.json
- extensions/xai/tsconfig.json
- extensions/zalouser/npm-shrinkwrap.json
- npm-shrinkwrap.json
- package.json
- pnpm-lock.yaml
- pnpm-workspace.yaml
- scripts/changed-lanes.mjs
- scripts/check-changed.mjs
- scripts/check-plugin-sdk-exports.mjs
- scripts/ci-changed-scope.mjs
- scripts/generate-npm-shrinkwrap.mjs
- scripts/lib/bundled-plugin-build-entries.mjs
- scripts/lib/extension-package-boundary.ts
- scripts/lib/format-generated-module.mjs
- scripts/lib/plugin-sdk-entries.d.mts
- scripts/lib/plugin-sdk-entries.mjs
- scripts/lib/plugin-sdk-entrypoints.json
- scripts/lib/plugin-sdk-private-local-only-subpaths.json
- scripts/plugin-npm-publish.sh
- scripts/prepare-extension-package-boundary-artifacts.mjs
- scripts/qa-lab-up.ts
- scripts/release-check.ts
- scripts/run-node-watch-paths.mjs
- scripts/run-with-env.mjs
- scripts/test-projects-imports.mjs
- scripts/test-projects-max.mjs
- scripts/watch-node.mjs
- scripts/write-plugin-sdk-entry-dts.ts
- src/infra/tsdown-config.test.ts
- src/infra/vitest-config.test.ts
- src/infra/watch-node.test.ts
- src/plugin-sdk/entrypoints.ts
- src/plugin-sdk/memory-core-host-embedding-registry.ts
- src/plugin-sdk/realtime-voice.ts
- src/plugins/plugin-sdk-native-resolver.test.ts
- src/plugins/plugin-sdk-native-resolver.ts
- src/plugins/sdk-alias.test.ts
- src/plugins/sdk-alias.ts
- src/scripts/ci-changed-scope.test.ts
- src/talk/output-activity-tracker.test.ts
- src/talk/output-activity-tracker.ts
- test/package-manager-config.test.ts
- test/package-scripts.test.ts
- test/release-check.test.ts
- test/scripts/bundled-plugin-build-entries.test.ts
- test/scripts/changed-lanes.test.ts
- test/scripts/format-generated-module.test.ts
- test/scripts/generate-npm-shrinkwrap.test.ts
- test/scripts/prepare-extension-package-boundary-artifacts.test.ts
- test/scripts/qa-lab-up.test.ts
- test/scripts/run-with-env.test.ts
- test/scripts/watch-node.test.ts
- test/vitest/vitest.shared.config.ts
- tsconfig.json
- tsdown.config.ts

This page documents the overall project structure of the OpenClaw codebase, detailing the monorepo layout, package organization, build outputs, and key specialized subsystems. It explains the organization of the repository folders - `apps/`, `extensions/`, `src/`, `docs/`, `skills/`, and `qa/` - along with the management approach via `pnpm` workspaces.

## Monorepo Organization

OpenClaw is structured as a **monorepo** managed with **pnpm workspaces**, enabling coordinated development and versioning of multiple packages and extensions within a single repository. The workspace configuration is defined in `pnpm-workspace.yaml`, which includes the root, UI, packages, and extensions. [pnpm-workspace.yaml1-6](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-workspace.yaml#L1-L6)

### Workspace Importers and Folder Roles

- Root package ( . ) : The main openclaw package serves as the core Gateway runtime. It provides the primary CLI entrypoint ( openclaw.mjs ), including runtime tools, session and state management, and dependency coordination. package.json 1-18
- src/ : Contains the TypeScript source code for the core Gateway runtime, including infrastructure, agent logic, and session management.
- apps/ : Contains native client applications for iOS, macOS, and Android platforms. These clients integrate the core Gateway runtime and extend it with platform-specific UI layers, including integration with the Swabble wake-word daemon for voice activation and the A2UI standard for agent UI rendering.
- extensions/* : Houses over 40 stand-alone plugin packages that implement messaging channel adapters (e.g., WhatsApp, Discord, Slack), model providers, and specialized runtime capabilities. Each extension is an independent package with its own package.json . pnpm-workspace.yaml 5
- packages/* : Contains shared packages used throughout the monorepo, such as @openclaw/sdk for programmatic access to the Gateway, @openclaw/fs-safe for secure file operations, and @openclaw/proxyline for networking. pnpm-workspace.yaml 4 pnpm-lock.yaml 83-88
- vendor/ : Includes third-party or open standard implementations, mainly the a2ui Agent-to-User Interface standard.
- skills/ : A bundled skill library containing reusable skill definitions expressed as Markdown-formatted SKILL.md documents. package.json 137
- qa/ : Contains quality assurance scenario pack assets, including dialogue scenarios and test coverage suites leveraged by the qa-lab extension. package.json 103
- .pi/ : Developer harness helpers and utilities facilitating local development and testing of agent runtime logic.

### Repository Layout Diagram

```

```

Sources: [pnpm-workspace.yaml1-6](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-workspace.yaml#L1-L6) [package.json1-146](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L1-L146) [pnpm-lock.yaml83-88](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-lock.yaml#L83-L88)

## Plugin SDK and Package Boundaries

OpenClaw enforces strong architectural boundaries. The **Plugin SDK** is the primary interface for extensions to interact with the core Gateway runtime.

### Plugin SDK Package

The SDK is exposed as a set of narrow public subpaths under `openclaw/plugin-sdk/`. These are declared in `package.json` and include submodules like `core`, `runtime`, `routing`, and `health`. [package.json150-196](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L150-L196) [docs/plugins/sdk-subpaths.md9-11](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L9-L11)

### Extension Package Boundaries

- Subpath Catalog : Subpaths like plugin-sdk/plugin-entry and plugin-sdk/provider-entry provide the entry points for different plugin types. docs/plugins/sdk-subpaths.md 24-32
- Reserved Helpers : Certain subpaths like plugin-sdk/codex-native-task-runtime are reserved for specific bundled plugins. docs/plugins/sdk-subpaths.md 50-55
- Test Isolation : OpenClaw's Vitest-backed test helpers (e.g., test-env , test-fixtures ) are repo-local only and are not exported in the public package. docs/plugins/sdk-subpaths.md 43-48
- Alias Management : The system uses src/plugins/sdk-alias.ts to resolve SDK imports to either src/ (for development) or dist/ (for production) based on environment hints. src/plugins/sdk-alias.ts 11-20

### Mapping Natural Language Concepts to Code Entities

```

```

Sources: [package.json150-196](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L150-L196) [docs/plugins/sdk-subpaths.md24-32](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L24-L32) [src/plugins/sdk-alias.ts11-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/sdk-alias.ts#L11-L20)

## Build System (tsdown)

OpenClaw uses `tsdown` for Node.js builds, configured in `tsdown.config.ts`. This configuration manages the bundling of the Gateway core, the Plugin SDK, and bundled plugins. [tsdown.config.ts3-12](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L3-L12)

### Build Configuration and Entries

- Plugin SDK Entries : The build system collects entries for the Plugin SDK using buildPluginSdkEntrySources . tsdown.config.ts 9-12
- Bundled Hooks : Custom hooks located in src/hooks/bundled/*/handler.ts are automatically detected and added to the build. tsdown.config.ts 163-186
- Dependency Bundling : The system explicitly excludes certain heavy dependencies (like typescript , vitest , and @slack/bolt ) from being bundled into the output. tsdown.config.ts 192-212 Conversely, core libraries like @openclaw/fs-safe and zod are always bundled. tsdown.config.ts 214-227

### Build Artifacts Table

Sources: [tsdown.config.ts1-237](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L1-L237) [package.json149-196](https://github.com/openclaw/openclaw/blob/fbdf5937/package.json#L149-L196)

## Specialized Components

### Swabble Wake-Word Daemon

The Swabble daemon provides wake-word detection for native clients. Integration logic is housed within the `apps/` directory, allowing for seamless voice activation of the AI gateway.

### A2UI - Agent-to-User Interface Standard

OpenClaw consumes the `a2ui` standard for building rich agent interfaces. Components like `@a2ui/lit` are used as development dependencies to build the Control UI. [pnpm-lock.yaml210-212](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-lock.yaml#L210-L212)

### QA Lab and Scenario Packs

The `qa/` directory and `extensions/qa-lab` form a specialized testing harness.

- QA Runtime : qa-runtime-*.js files provide the environment for executing scenario packs. package.json 126
- Scenario Packs : Located in qa/ , these are executable dialogue suites used for regression testing and coverage analysis. package.json 103
- Shrinkwrap Guard : The scripts/generate-npm-shrinkwrap.mjs utility ensures that dependency locks across the monorepo remain consistent with the root pnpm-lock.yaml . scripts/generate-npm-shrinkwrap.mjs 50-53

### Mapping Natural Language Components to Technical Modules

```

```

Sources: [pnpm-workspace.yaml1-6](https://github.com/openclaw/openclaw/blob/fbdf5937/pnpm-workspace.yaml#L1-L6) [docs/plugins/sdk-subpaths.md1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/plugins/sdk-subpaths.md?plain=1#L1-L50) [tsdown.config.ts3-12](https://github.com/openclaw/openclaw/blob/fbdf5937/tsdown.config.ts#L3-L12) [src/plugins/sdk-alias.ts11-20](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/sdk-alias.ts#L11-L20)

This project structure supports scalable development through modular packages, strict boundaries, and comprehensive testing infrastructure. The monorepo and pnpm workspace configuration enable efficient build and test orchestration, facilitating a robust and extensible multi-channel AI gateway platform.
