OpenClaw Upstream Workflow

Use this whenever modifying OpenClaw itself.

Source of truth

Upstream working clone: external/openclaw-upstream/
Install path (~/.npm-global/lib/node_modules/openclaw/dist) is runtime output, not long-term source.

Standard flow

Quick preflight helper (recommended):

scripts/openclaw-upstream-preflight.sh fix/<short-topic>

Equivalent manual flow:

cd external/openclaw-upstream
git fetch --all --prune
git checkout main
git pull --rebase
git checkout -b fix/<short-topic>

Then:

Implement in src/ (and docs/tests as needed).
Run targeted tests first; run broader suite if change touches shared paths.
Commit with Conventional Commit format.
Rebase onto latest main before push/PR:
- git fetch origin && git rebase origin/main
Push branch and open PR.

Merge policy

Preferred PR strategy: Rebase and merge
Avoid merge commits unless explicitly required for a special case

Post-merge branch cleanup (required)

After PR merge, delete the branch on both remote and local:

# from repo root

git checkout main
git pull --rebase

# delete remote branch

git push origin --delete <branch-name>

# delete local branch

git branch -d <branch-name>

If branch was not merged cleanly and Git blocks deletion, inspect first; only then force-delete local branch with:

git branch -D <branch-name>

Branch naming

fix/... for bugfixes
feat/... for new behavior
chore/... for maintenance
keep names short and specific (fix/tui-hide-internal-runtime-context)

Update hygiene

Check runtime version: openclaw update status
If local compatibility patch exists, update with:

scripts/openclaw-update-safe.sh

After runtime update, re-sync upstream clone before new changes:

cd external/openclaw-upstream && git fetch --all --prune && git checkout main && git pull --rebase

Emergency dist hotfix policy

If a dist-file hotfix is unavoidable:

keep it scripted (scripts/...), idempotent, and reversible
document it (patches/.../README.md)
land the proper upstream source fix and PR as soon as possible

2.1 KiB Raw Blame History