diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index a20421bf1..96610a5eb 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "4fbd683819837af26c5ff4a62fd3843c2b7fa57d",
-  "syncedAt": "2026-04-29T08:41:58.045Z"
+  "sha": "68ba1e7180a6393fdc7d61b71a11fc514502d1b3",
+  "syncedAt": "2026-04-29T08:43:57.503Z"
 }
diff --git a/docs/help/debugging.md b/docs/help/debugging.md
index 08f95ba5c..9d2766d28 100644
--- a/docs/help/debugging.md
+++ b/docs/help/debugging.md
@@ -216,12 +216,42 @@ For fast iteration, run the gateway under the file watcher:
 pnpm gateway:watch
 ```
 
-This maps to:
+By default, this starts or restarts a tmux session named
+`openclaw-gateway-watch-main` (or a profile/port-specific variant such as
+`openclaw-gateway-watch-dev-19001`) and auto-attaches from interactive terminals.
+Non-interactive shells, CI, and agent exec calls stay detached and print attach
+instructions instead. Attach manually when needed:
+
+```bash
+tmux attach -t openclaw-gateway-watch-main
+```
+
+The tmux pane runs the raw watcher:
 
 ```bash
 node scripts/watch-node.mjs gateway --force
 ```
 
+Use foreground mode when tmux is not wanted:
+
+```bash
+pnpm gateway:watch:raw
+# or
+OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
+```
+
+Disable auto-attach while keeping tmux management:
+
+```bash
+OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
+```
+
+The tmux wrapper carries common non-secret runtime selectors such as
+`OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`,
+`OPENCLAW_GATEWAY_PORT`, and `OPENCLAW_SKIP_CHANNELS` into the pane. Put
+provider credentials in your normal profile/config, or use raw foreground mode
+for one-off ephemeral secrets.
+
 The watcher restarts on build-relevant files under `src/`, extension source files,
 extension `package.json` and `openclaw.plugin.json` metadata, `tsconfig.json`,
 `package.json`, and `tsdown.config.ts`. Extension metadata changes restart the
@@ -229,8 +259,9 @@ gateway without forcing a `tsdown` rebuild; source and config changes still
 rebuild `dist` first.
 
 Add any gateway CLI flags after `gateway:watch` and they will be passed through on
-each restart. Re-running the same watch command for the same repo/flag set now
-replaces the older watcher instead of leaving duplicate watcher parents behind.
+each restart. Re-running the same watch command respawns the named tmux pane, and
+the raw watcher still keeps its single-watcher lock so duplicate watcher parents
+are replaced instead of piling up.
 
 ## Dev profile + dev gateway (--dev)
 
diff --git a/docs/start/setup.md b/docs/start/setup.md
index 227b5f16b..fa70dbb18 100644
--- a/docs/start/setup.md
+++ b/docs/start/setup.md
@@ -96,8 +96,12 @@ pnpm openclaw setup
 pnpm gateway:watch
 ```
 
-`gateway:watch` runs the gateway in watch mode and reloads on relevant source,
-config, and bundled-plugin metadata changes.
+`gateway:watch` starts or restarts the Gateway watch process in a named tmux
+session and auto-attaches from interactive terminals. Non-interactive shells stay
+detached and print `tmux attach -t openclaw-gateway-watch-main`; use
+`OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch` to keep an interactive run
+detached, or `pnpm gateway:watch:raw` for foreground watch mode. The watcher
+reloads on relevant source, config, and bundled-plugin metadata changes.
 `pnpm openclaw setup` is the one-time local config/workspace initialization step for a fresh checkout.
 `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.