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

# Development Workflow

- docs/help/testing.md
- extensions/discord/src/durable-delivery.test.ts
- extensions/discord/src/monitor/model-picker-preferences-migrations.test.ts
- extensions/discord/src/monitor/model-picker-preferences-migrations.ts
- extensions/discord/src/monitor/model-picker-preferences.test.ts
- extensions/discord/src/monitor/model-picker-preferences.ts
- extensions/discord/src/monitor/thread-bindings.lifecycle.test.ts
- extensions/discord/src/monitor/thread-bindings.manager.ts
- extensions/discord/src/monitor/thread-bindings.state.ts
- extensions/qa-lab/runtime-api.ts
- scripts/anthropic-prompt-probe.ts
- scripts/bench-gateway-restart.ts
- scripts/bench-gateway-startup.ts
- scripts/build-all.mjs
- scripts/debug-claude-usage.ts
- scripts/dev/discord-acp-plain-language-smoke.ts
- scripts/dev/realtime-talk-live-smoke.ts
- scripts/e2e/telegram-bot-api.ts
- scripts/e2e/telegram-user-credential-io.ts
- scripts/e2e/telegram-user-credential-paths.ts
- scripts/e2e/telegram-user-credential.ts
- scripts/firecrawl-compare.ts
- scripts/lib/bounded-response.mjs
- scripts/lib/bounded-response.ts
- scripts/lib/dev-tooling-safety.ts
- scripts/lib/gateway-bench-child.ts
- scripts/lib/static-extension-assets.mjs
- scripts/run-vitest.mjs
- scripts/runtime-postbuild.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/embedded-agent-runner/run/attempt-system-prompt.test.ts
- src/agents/embedded-agent-runner/run/attempt.cwd-split.test.ts
- src/auto-reply/reply/completion-delivery-policy.test.ts
- src/cli/program/config-guard.test.ts
- src/cli/program/config-guard.ts
- src/gateway/gateway-cli-backend.connect.test.ts
- src/gateway/gateway-cli-backend.live-helpers.test.ts
- src/gateway/gateway-cli-backend.live-helpers.ts
- src/gateway/gateway-cli-backend.live-probe-helpers.test.ts
- src/gateway/gateway-cli-backend.live-probe-helpers.ts
- src/gateway/live-agent-probes.test.ts
- src/gateway/live-agent-probes.ts
- src/gateway/minimal-gateway.test-helpers.ts
- src/gateway/probe.close-drain.test.ts
- src/gateway/probe.test.ts
- src/gateway/probe.ts
- src/gateway/server-methods/subagent-followup.test-helpers.ts
- src/gateway/server.silent-scope-upgrade-reconnect.poc.test.ts
- src/infra/exec-wrapper-trust-plan.test.ts
- src/plugin-sdk/approval-reaction-runtime.test.ts
- src/plugin-sdk/approval-reaction-runtime.ts
- src/scripts/test-projects.test.ts
- test/AGENTS.md
- test/CLAUDE.md
- test/scripts/bench-gateway-child-test-support.ts
- test/scripts/bench-gateway-restart.test.ts
- test/scripts/bench-gateway-startup.test.ts
- test/scripts/build-all.test.ts
- test/scripts/dev-tooling-safety.test.ts
- test/scripts/firecrawl-compare.test.ts
- test/scripts/run-vitest.test.ts
- test/scripts/runtime-postbuild.test.ts
- test/scripts/telegram-bot-api.test.ts
- test/scripts/telegram-user-credential.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-ui.config.ts

This document details the development workflow for OpenClaw contributors, covering local development setup, running the Gateway in development mode, debugging and profiling techniques, recommended testing practices, and Windows-specific process considerations.

## Local Development Setup

OpenClaw uses a TypeScript-centric monorepo managed with `pnpm`. Development workflows rely on Node.js for the runtime and scripting.

### Setup and Build Process

Initialize the repository with:

```

```

The build process is managed by `scripts/build-all.mjs`, which orchestrates several critical steps to ensure the Gateway and its extensions are ready for execution [scripts/build-all.mjs73-162](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L73-L162)

- Asset Preparation : plugins:assets:build and plugins:assets:copy stage bundled plugin assets into the distribution directory scripts/build-all.mjs 74-118
- Core Compilation : tsdown compiles the TypeScript source into dist/ scripts/build-all.mjs 75
- SDK Generation : build:plugin-sdk:dts and write-plugin-sdk-entry-dts generate the type definitions and entry points for the extension system scripts/build-all.mjs 89-108
- Post-Build Logic : runtime-postbuild handles metadata synchronization and environment preparation scripts/build-all.mjs 81

Sources: [scripts/build-all.mjs73-162](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L73-L162) [scripts/runtime-postbuild.mjs1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/runtime-postbuild.mjs#L1-L10)

## Running the Gateway in Development Mode

### Gateway Execution and Watch Mode

For iterative development, the Gateway is typically run via a launcher that monitors source changes. The build system includes a `gatewayWatch` profile designed for this purpose [scripts/build-all.mjs184-190](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L184-L190)

- Build Stamps : The system uses scripts/build-stamp.mjs and scripts/runtime-postbuild-stamp.mjs to track build freshness scripts/build-all.mjs 82-87
- CLI Metadata : write-cli-startup-metadata ensures that the CLI has the necessary information to boot the Gateway in development scripts/build-all.mjs 153-156

### Development Safety

OpenClaw includes helpers to prevent the accidental leakage of secrets during development and logging [scripts/lib/dev-tooling-safety.ts10-17](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/lib/dev-tooling-safety.ts#L10-L17)

- Redaction : Functions like redactJsonValueForDevToolLog and previewForDevToolLog scrub API keys and home paths from terminal output test/scripts/dev-tooling-safety.test.ts 20-36
- Strict Parsing : parseStrictIntegerOption and parseBooleanEnv ensure that development flags are correctly interpreted test/scripts/dev-tooling-safety.test.ts 38-53

Sources: [scripts/build-all.mjs184-190](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L184-L190) [test/scripts/dev-tooling-safety.test.ts20-53](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/dev-tooling-safety.test.ts#L20-L53) [scripts/lib/dev-tooling-safety.ts10-17](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/lib/dev-tooling-safety.ts#L10-L17)

## Debugging and Profiling

### Gateway Restart Benchmarking

Developers can use `scripts/bench-gateway-restart.ts` to profile Gateway startup performance and resource usage during restarts [scripts/bench-gateway-restart.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/bench-gateway-restart.ts#L1-L10)

- Trace Metrics : The script enables OPENCLAW_GATEWAY_STARTUP_TRACE and OPENCLAW_GATEWAY_RESTART_TRACE to collect timing data, RSS memory usage, and heap stats test/scripts/bench-gateway-restart.test.ts 152-163
- Resource Monitoring : It parses logs for activeHandlesCount and activeTimersCount to identify resource leaks test/scripts/bench-gateway-restart.test.ts 180-195
- LSOF Integration : On supported platforms, it uses lsof to count open file descriptors test/scripts/bench-gateway-restart.test.ts 139-150

### Health Probes

The Gateway includes a `probe.ts` utility for diagnostic checks [src/gateway/probe.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/probe.ts#L1-L10)

- Startup Probes : Verifies that the control plane is responsive after a boot or restart src/gateway/probe.test.ts 1-10
- Drain Logic : Tests for graceful shutdown and connection draining src/gateway/probe.close-drain.test.ts 1-10

Sources: [scripts/bench-gateway-restart.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/bench-gateway-restart.ts#L1-L10) [test/scripts/bench-gateway-restart.test.ts139-195](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/bench-gateway-restart.test.ts#L139-L195) [src/gateway/probe.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/probe.ts#L1-L10)

## Testing Best Practices

Testing is tiered between fast unit tests, project-scoped integration tests, and live provider checks.

### Vitest Project Routing

OpenClaw uses a custom test runner (`scripts/test-projects.mjs`) to route specific files to the correct Vitest configuration [scripts/test-projects.test-support.mjs1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L1-L50)

### Changed Lane Detection

To speed up local iteration, `scripts/test-projects.mjs` can detect changed files via Git and only run relevant tests [scripts/test-projects.test-support.mjs49-51](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L49-L51)

- Lane Mapping : Maps source changes in packages/ to their corresponding test files test/scripts/test-projects.test.ts 180-190
- Broad Mode : If core configurations (like vitest.shared.config.ts ) change, it can trigger a broader test run test/scripts/test-projects.test.ts 192-198

Sources: [scripts/test-projects.test-support.mjs1-132](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L1-L132) [test/scripts/test-projects.test.ts180-198](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/test-projects.test.ts#L180-L198) [scripts/run-vitest.mjs20-35](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/run-vitest.mjs#L20-L35)

## Windows-Specific Considerations

### Process Management

On Windows, the `scripts/run-vitest.mjs` runner implements specific logic to handle Node.js child processes and `node_modules` resolution.

- Junction Links : If PNPM_CONFIG_MODULES_DIR is set, the runner creates directory junctions to link hydrated dependencies into the workspace test/scripts/run-vitest.test.ts 62-97
- Signal Handling : Windows does not support the same signal-based restart mechanisms as POSIX (e.g., SIGUSR1 ). The benchmark scripts include guards to prevent execution of unsupported restart modes on win32 test/scripts/bench-gateway-restart.test.ts 52-58
- Heap Management : The build system adds extra heap headroom ( --max-old-space-size=8192 ) when running TypeScript declaration builds on Windows to prevent OOM errors scripts/build-all.mjs 12-13 test/scripts/build-all.test.ts 135-165

Sources: [test/scripts/run-vitest.test.ts62-97](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/run-vitest.test.ts#L62-L97) [test/scripts/bench-gateway-restart.test.ts52-58](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/bench-gateway-restart.test.ts#L52-L58) [scripts/build-all.mjs12-13](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L12-L13) [test/scripts/build-all.test.ts135-165](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/build-all.test.ts#L135-L165)

## Summary Diagrams

### Development Lifecycle: Natural Language to Code Entities

This diagram bridges developer intent to the specific scripts and tools used in the OpenClaw workflow.

```

```

Sources: [scripts/build-all.mjs1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/build-all.mjs#L1-L10) [scripts/test-projects.test-support.mjs1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L1-L10) [scripts/run-vitest.mjs1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/run-vitest.mjs#L1-L10) [scripts/bench-gateway-restart.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/bench-gateway-restart.ts#L1-L10)

### Test Execution Flow

This diagram shows how a test file is routed through the project-specific Vitest configurations.

```

```

Sources: [test/scripts/test-projects.test.ts7-25](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/test-projects.test.ts#L7-L25) [scripts/test-projects.test-support.mjs59-132](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/test-projects.test-support.mjs#L59-L132) [scripts/run-vitest.mjs140-172](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/run-vitest.mjs#L140-L172)
