docs: clarify source control-ui dev/build flow (#68814) ·...
rubencu
·
2026-04-19
·
via Recent Commits to openclaw:main
9 files changed
lines changed
| Original file line number | Diff line number | Diff line change |
|---|
@@ -212,21 +212,34 @@ Runbook: [iOS connect](https://docs.openclaw.ai/platforms/ios).
|
212212|
213213Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly.
|
214214|
215+For the dev loop:
|
216+|
215217```bash
|
216218git clone https://github.com/openclaw/openclaw.git
|
217219cd openclaw
|
218220|
219221pnpm install
|
220-pnpm ui:build # auto-installs UI deps on first run
|
221-pnpm build
|
222222|
223-pnpm openclaw onboard --install-daemon
|
223+# First run only (or after resetting local OpenClaw config/workspace)
|
224+pnpm openclaw setup
|
225+|
226+# Optional: prebuild Control UI before first startup
|
227+pnpm ui:build
|
224228|
225229# Dev loop (auto-reload on source/config changes)
|
226230pnpm gateway:watch
|
227231```
|
228232|
229-Note: `pnpm openclaw ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `openclaw` binary.
|
233+If you need a built `dist/` from the checkout (for Node, packaging, or release validation), run:
|
234+|
235+```bash
|
236+pnpm build
|
237+pnpm ui:build
|
238+```
|
239+|
240+`pnpm openclaw setup` writes the local config/workspace needed for `pnpm gateway:watch`. It is safe to re-run, but you normally only need it on first setup or after resetting local state. `pnpm gateway:watch` does not rebuild `dist/control-ui`, so rerun `pnpm ui:build` after `ui/` changes or use `pnpm ui:dev` when iterating on the Control UI. If you want this checkout to run onboarding directly, use `pnpm openclaw onboard --install-daemon`.
|
241+|
242+Note: `pnpm openclaw ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `openclaw` binary, while `pnpm gateway:watch` rebuilds the runtime on demand during the dev loop.
|
230243|
231244## Development channels
|
232245|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -160,7 +160,7 @@ Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS,
|
160160cd openclaw
|
161161pnpm install
|
162162pnpm build
|
163-pnpm ui:build # auto-installs UI deps on first run
|
163+pnpm ui:build
|
164164openclaw onboard
|
165165```
|
166166|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -115,7 +115,7 @@ For contributors or anyone who wants to run from a local checkout:
|
115115```bash
|
116116git clone https://github.com/openclaw/openclaw.git
|
117117cd openclaw
|
118-pnpm install && pnpm ui:build && pnpm build
|
118+pnpm install && pnpm build && pnpm ui:build
|
119119pnpm link --global
|
120120openclaw onboard --install-daemon
|
121121```
|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -222,15 +222,25 @@ systemctl --user status
|
222222|
223223### 3) Install OpenClaw (inside WSL)
|
224224|
225-Follow the Linux Getting Started flow inside WSL:
|
225+For a normal first-time setup inside WSL, follow the Linux Getting Started flow:
|
226226|
227227```bash
|
228228git clone https://github.com/openclaw/openclaw.git
|
229229cd openclaw
|
230230pnpm install
|
231-pnpm ui:build # auto-installs UI deps on first run
|
232231pnpm build
|
233-openclaw onboard
|
232+pnpm ui:build
|
233+pnpm openclaw onboard --install-daemon
|
234+```
|
235+|
236+If you are developing from source instead of doing first-time onboarding, use the
|
237+source dev loop from [Setup](/start/setup):
|
238+|
239+```bash
|
240+pnpm install
|
241+# First run only (or after resetting local OpenClaw config/workspace)
|
242+pnpm openclaw setup
|
243+pnpm gateway:watch
|
234244```
|
235245|
236246Full guide: [Getting Started](/start/getting-started)
|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -91,16 +91,22 @@ If you also want the macOS app on the bleeding edge:
|
9191|
9292```bash
|
9393pnpm install
|
94+# First run only (or after resetting local OpenClaw config/workspace)
|
95+pnpm openclaw setup
|
9496pnpm gateway:watch
|
9597```
|
9698|
9799`gateway:watch` runs the gateway in watch mode and reloads on relevant source,
|
98100config, and bundled-plugin metadata changes.
|
101+`pnpm openclaw setup` is the one-time local config/workspace initialization step for a fresh checkout.
|
102+`pnpm gateway:watch` does not rebuild `dist/control-ui`, so rerun `pnpm ui:build` after `ui/` changes or use `pnpm ui:dev` while developing the Control UI.
|
99103|
100104If you are intentionally using the Bun workflow, the equivalent commands are:
|
101105|
102106```bash
|
103107bun install
|
108+# First run only (or after resetting local OpenClaw config/workspace)
|
109+bun run openclaw setup
|
104110bun run gateway:watch
|
105111```
|
106112|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -278,7 +278,7 @@ See [Tailscale](/gateway/tailscale) for HTTPS setup guidance.
|
278278The Gateway serves static files from `dist/control-ui`. Build them with:
|
279279|
280280```bash
|
281-pnpm ui:build # auto-installs UI deps on first run
|
281+pnpm ui:build
|
282282```
|
283283|
284284Optional absolute base (when you want fixed asset URLs):
|
@@ -290,7 +290,7 @@ OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
290290For local development (separate dev server):
|
291291|
292292```bash
|
293-pnpm ui:dev # auto-installs UI deps on first run
|
293+pnpm ui:dev
|
294294```
|
295295|
296296Then point the UI at your Gateway WS URL (e.g. `ws://127.0.0.1:18789`).
|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -122,5 +122,5 @@ Open:
|
122122The Gateway serves static files from `dist/control-ui`. Build them with:
|
123123|
124124```bash
|
125-pnpm ui:build # auto-installs UI deps on first run
|
125+pnpm ui:build
|
126126```
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -226,7 +226,7 @@ describe("gateway run option collisions", () => {
|
226226await runGatewayCli(["gateway", "run", "--allow-unconfigured"]);
|
227227|
228228expect(gatewayLogMessages).toContain(
|
229-"Control UI assets are missing; first startup may spend a few seconds building them before the gateway binds. Prebuild with `pnpm ui:build` for a faster first boot.",
|
229+"Control UI assets are missing; first startup may spend a few seconds building them before the gateway binds. `pnpm gateway:watch` does not rebuild Control UI assets, so rerun `pnpm ui:build` after UI changes or use `pnpm ui:dev` while developing the Control UI. For a full local dist, run `pnpm build && pnpm ui:build`.",
|
230230);
|
231231});
|
232232|
|
| Original file line number | Diff line number | Diff line change |
|---|
@@ -176,7 +176,7 @@ function maybeLogPendingControlUiBuild(cfg: OpenClawConfig): void {
|
176176return;
|
177177}
|
178178gatewayLog.info(
|
179-"Control UI assets are missing; first startup may spend a few seconds building them before the gateway binds. Prebuild with `pnpm ui:build` for a faster first boot.",
|
179+"Control UI assets are missing; first startup may spend a few seconds building them before the gateway binds. `pnpm gateway:watch` does not rebuild Control UI assets, so rerun `pnpm ui:build` after UI changes or use `pnpm ui:dev` while developing the Control UI. For a full local dist, run `pnpm build && pnpm ui:build`.",
|
180180);
|
181181}
|
182182|
|
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。
