diff --git a/AGENTS.md b/AGENTS.md
index d8acb88..819c720 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -139,7 +139,7 @@ Skills provide your tools. When you need one, check its `SKILL.md`. Keep local n
 - Do **not** rely on editing installed dist files under `~/.npm-global/.../dist` as the long-term fix path.
 - For OpenClaw code changes:
   1. `cd external/openclaw-upstream`
-  2. `git fetch --all --prune && git checkout main && git pull --rebase`
+  2. `git fetch --all --prune && git checkout main && git pull --rebase` (or run `scripts/openclaw-upstream-preflight.sh`)
   3. Create a focused branch (`fix/...`, `feat/...`, `chore/...`)
   4. Implement in `src/` and add/adjust tests
   5. Run relevant tests before commit
diff --git a/scripts/openclaw-upstream-preflight.sh b/scripts/openclaw-upstream-preflight.sh
new file mode 100755
index 0000000..6dbf721
--- /dev/null
+++ b/scripts/openclaw-upstream-preflight.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure upstream clone is synced before implementing OpenClaw code changes.
+# Usage:
+#   scripts/openclaw-upstream-preflight.sh
+#   scripts/openclaw-upstream-preflight.sh fix/my-change
+
+REPO="${OPENCLAW_UPSTREAM_REPO:-$HOME/.openclaw/workspace/external/openclaw-upstream}"
+TARGET_BRANCH="${1:-}"
+
+if [[ ! -d "$REPO/.git" ]]; then
+  echo "error: upstream repo not found at $REPO" >&2
+  echo "hint: git clone https://github.com/openclaw/openclaw $REPO" >&2
+  exit 2
+fi
+
+cd "$REPO"
+
+echo "[preflight] syncing upstream..."
+git fetch --all --prune
+git checkout main
+git pull --rebase
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "error: working tree is not clean on main; resolve before branching" >&2
+  git status --short
+  exit 3
+fi
+
+if [[ -n "$TARGET_BRANCH" ]]; then
+  if git show-ref --verify --quiet "refs/heads/$TARGET_BRANCH"; then
+    echo "[preflight] switching to existing branch: $TARGET_BRANCH"
+    git checkout "$TARGET_BRANCH"
+    echo "[preflight] rebasing $TARGET_BRANCH onto origin/main"
+    git rebase origin/main
+  else
+    echo "[preflight] creating branch: $TARGET_BRANCH"
+    git checkout -b "$TARGET_BRANCH"
+  fi
+fi
+
+MAIN_HEAD_LOCAL=$(git rev-parse --short main)
+MAIN_HEAD_REMOTE=$(git rev-parse --short origin/main)
+AB=$(git rev-list --left-right --count main...origin/main)
+CUR=$(git rev-parse --abbrev-ref HEAD)
+
+echo "[preflight] branch: $CUR"
+echo "[preflight] main local:  $MAIN_HEAD_LOCAL"
+echo "[preflight] main remote: $MAIN_HEAD_REMOTE"
+echo "[preflight] main ahead/behind (local remote): $AB"
+echo "[preflight] done"
diff --git a/scripts/openclaw-upstream-workflow.md b/scripts/openclaw-upstream-workflow.md
index ba5f75f..5119488 100644
--- a/scripts/openclaw-upstream-workflow.md
+++ b/scripts/openclaw-upstream-workflow.md
@@ -9,6 +9,14 @@ Use this whenever modifying OpenClaw itself.
 
 ## Standard flow
 
+Quick preflight helper (recommended):
+
+```bash
+scripts/openclaw-upstream-preflight.sh fix/<short-topic>
+```
+
+Equivalent manual flow:
+
 ```bash
 cd external/openclaw-upstream
 git fetch --all --prune