From Source

Clone the GitHub repo and build locally. For contributors or anyone wanting to run a local checkout.

Building from source is the method for contributors, plugin developers, and anyone who wants to modify OpenClaw's internals. You clone the GitHub repo, install dependencies with pnpm, build the TypeScript source and the Control UI, then link the CLI globally so you can run `openclaw` commands from anywhere. The build process involves three steps: `pnpm install` to fetch dependencies, `pnpm ui:build` to compile the web-based Control UI (a Vite/React app), and `pnpm build` to transpile the TypeScript gateway and CLI code. On a modern machine this takes 1-3 minutes. After building, `pnpm link --global` makes the `openclaw` command available system-wide. This method is essential if you're developing new skills, plugins, or channel integrations. You get live access to the full codebase, can set breakpoints, run the test suite with `pnpm vitest run`, and iterate quickly. You can also skip the global link entirely and use `pnpm openclaw ...` from inside the repo directory for a more contained development workflow. The from-source path requires pnpm specifically (not npm or yarn) because the OpenClaw monorepo uses pnpm workspaces. You'll also need Git for cloning and staying up to date with upstream changes. This is not the recommended path for end users — it's for people who want to work on OpenClaw itself or need modifications that aren't possible through the plugin/skill system.

Tags: source, development, contributors

Use Cases

  • Contributing bug fixes or new features to the OpenClaw project
  • Developing custom plugins or channel integrations that need access to internal APIs
  • Running a patched version with custom modifications not available through the plugin system
  • Testing upcoming features on the main branch before they're released to npm
  • Academic or research purposes where source-level understanding is needed

Tips

  • Skip the global link for development: just use pnpm openclaw from inside the repo directory
  • Run pnpm vitest run to execute the test suite before submitting PRs
  • Use git pull && pnpm install && pnpm build as a single update workflow
  • Set up a separate workspace directory for your config/data so rebuilds don't affect your running instance
  • Watch the GitHub Actions CI status before pulling — occasionally main has temporary build issues
  • For rapid iteration, pnpm build --watch can rebuild on file changes (check if available)

Known Issues & Gotchas

  • You must use pnpm — npm and yarn won't work with the monorepo workspace structure
  • Run pnpm ui:build BEFORE pnpm build — the gateway build expects Control UI assets to exist
  • pnpm link --global may conflict with a previously npm-installed openclaw — uninstall the npm version first
  • The build requires 2GB+ RAM — constrained environments (1GB VPS, older Raspberry Pi) may run out of memory
  • After pulling new changes from main, you need to re-run pnpm install && pnpm ui:build && pnpm build
  • TypeScript compilation errors on main branch are rare but possible — check GitHub Actions status before pulling
  • Don't mix pnpm link --global with npm install -g — one or the other, not both

Alternatives

  • npm / pnpm
  • Installer Script
  • Docker

Community Feedback

If you're contributing, from-source is the only way. The pnpm workspace setup is clean and the build is surprisingly fast.

— Reddit r/selfhosted

Don't forget pnpm ui:build before pnpm build — the gateway expects the Control UI assets to exist or the dashboard won't load.

— GitHub Issues

For most people, npm install -g is plenty. From source is overkill unless you're actually submitting PRs or need custom patches.

— Reddit r/selfhosted

Frequently Asked Questions

Why does the build require pnpm specifically?

OpenClaw is a monorepo using pnpm workspaces to manage multiple packages (gateway, CLI, Control UI, plugins). npm and yarn don't handle pnpm workspace protocol correctly, so pnpm is required for building from source.

How do I stay updated with the latest changes?

Run git pull origin main followed by pnpm install && pnpm ui:build && pnpm build && openclaw gateway restart. This pulls the latest code, rebuilds everything, and restarts your running instance.

Can I build and run without linking globally?

Yes. From inside the repo directory, use pnpm openclaw [command] instead of linking. This keeps your source build isolated from any global npm install.

What's the difference between this and the Docker build?

Docker builds from source inside a container, giving you isolation. Building directly on your machine is faster for development iteration but exposes your host to the build dependencies. Use Docker for deployment, direct source for development.

How much disk space does a source build require?

The repo clone is about 50MB, node_modules around 500MB, and build output around 50MB. Total is roughly 600MB. The Docker image is about 1.5GB due to additional runtime dependencies.