更新 OpenClaw 从源代码以获取最新版本，同时保留本地更改。
⚠️ 重要警告
- 执行 git rebase 和 git push --force - 可能丢失未提交的本地更改
- 使用 npm i -g . 进行全局安装 - 可能需要
sudo
- 使用 systemctl --user restart - 将重启 OpenClaw 服务
- 在运行前备份配置！（见下）
要求
必须安装的二进制文件：
gitnpm / nodesystemctl（用于重启网关）
配置
环境变量（可选）
# 设置自定义项目路径
export OPENCLAW_PROJECT_DIR="/path/to/openclaw"
# 设置自定义分支（默认：main）
export OPENCLAW_BRANCH="your-feature-branch"
# 启用干运行模式（无实际更改）
export DRY_RUN="true"
或通过参数传递
./update.sh --dir /path/to/openclaw --branch your-branch
工作流
步骤 1：分析当前状态（必须首先运行）
在执行更新之前，检查：
- 当前分支是否有未提交的更改
- 当前分支是否有本地修改
- 上游是否有新提交
- 根据情况推荐最合适的更新策略
推荐策略：
| 场景 | 推荐方法 | 理由 |
|---|
| 未提交的本地更改 | 先提交/存储，然后 合并 | 安全，无丢失更改 |
| 只有干净的本地提交 | 合并 或 重置 | 合并更安全，重置保持历史清洁 |
| 准备 PR | 重置 推荐 | 保持历史整洁 |
| 常规开发更新 | 合并 推荐 | 简单，少错误 |
步骤 2：等待用户确认
在呈现推荐选项后，
必须等待用户确认才执行。
步骤 3：执行更新
# 1. 进入项目目录
cd "${OPENCLAW_PROJECT_DIR:-$HOME/projects/openclaw}"
# 2. 备份配置文件（更新前最佳实践！）
echo "=== Backing up config files ==="
...
快速脚本运行
运行
scripts/update.sh 自动完成上述所有步骤。
命令行选项
./update.sh [选项]
选项：
--dir PATH OpenClaw 项目目录（默认：$HOME/projects/openclaw）
--branch NAME Git 分支更新（默认：main）
--mode MODE 更新模式：合并或重置（如果不指定，将分析并推荐）
--dry-run 显示将执行的操作而不执行
cf. 原始文档...
注意
- 重置可能引起冲突 - 如果发生冲突，请手动解决然后继续
- 强制推送 - 重置后，如果推送到 fork，请使用
git push --force
- 服务重新安装 - 将更新 systemd 单元文件中的版本
- 用户确认重启 - 网关将不会重启，直到您确认
- 先备份！ - 更新前始终备份！
故障排除
Git 冲突 durante 重置
# 手动解决冲突，然后：
git add .
git rebase --continue
# 继续构建步骤
构建失败
# 清理并重试：
rm -rf node_modules dist
npm install
npm run build
网关无法启动
# 检查状态：
systemctl --user status openclaw-gateway
# 查看日志：
journalctl --user -u openclaw-gateway -n 50
# Safe Update
Update OpenClaw from source to the latest version while preserving local changes.
⚠️ Important Warnings
- This script performs git rebase and git push --force - may lose local changes if not properly committed
- Uses npm i -g . for global installation - may require sudo
- Uses systemctl --user restart - will restart the OpenClaw service
- Backup your config before running! (see below)
Requirements
Required binaries (must be installed):
gitnpm / nodesystemctl (for restarting gateway)
Configuration
Environment Variables (optional)
``
bash
# Set custom project path
export OPENCLAW_PROJECT_DIR="/path/to/openclaw"
# Set custom branch (default: main)
export OPENCLAW_BRANCH="your-feature-branch"
# Enable dry-run mode (no actual changes)
export DRY_RUN="true"
`
Or Pass as Arguments
`
bash
./update.sh --dir /path/to/openclaw --branch your-branch
`
Workflow
Step 1: Analyze Current State (Must Run First)
Before executing any update, check:
- Whether the current branch has uncommitted changes
- Whether the current branch has local modifications
- Whether upstream has new commits
- Recommend the most appropriate update strategy based on the situation
Recommended Strategy:
| Scenario | Recommended Method | Rationale |
|----------|-------------------|----------|
| Uncommitted local changes | Commit/stash first, then merge | Safe, no lost changes |
| Only clean local commits | merge or rebase | merge is safer, rebase keeps history clean |
| Preparing a PR | rebase recommended | Keeps history tidy |
| Routine dev update | merge recommended | Simple, less error-prone |
Step 2: Ask User for Confirmation
After presenting the recommended options, you must wait for user confirmation before executing.
Step 3: Execute Update
`
bash
# 1. Enter project directory
cd "${OPENCLAW_PROJECT_DIR:-$HOME/projects/openclaw}"
# 2. Backup config files (good practice before update!)
echo "=== Backing up config files ==="
mkdir -p ~/.openclaw/backups
BACKUP_SUFFIX=$(date +%Y%m%d-%H%M%S)
# Backup main config
cp ~/.openclaw/openclaw.json ~/.openclaw/backups/openclaw.json.bak.$BACKUP_SUFFIX
echo "✅ Backed up: openclaw.json"
# Backup auth profiles (if exists)
if [ -f ~/.openclaw/agents/main/agent/auth-profiles.json ]; then
cp ~/.openclaw/agents/main/agent/auth-profiles.json \
~/.openclaw/backups/auth-profiles.json.bak.$BACKUP_SUFFIX
echo "✅ Backed up: auth-profiles.json"
fi
echo "💡 Backups saved to: ~/.openclaw/backups/"
echo ""
# 3. Add upstream repository (if not added)
git remote add upstream https://github.com/openclaw/openclaw.git 2>/dev/null || true
# 4. Fetch upstream changes
git fetch upstream
# 5. Update target branch (use merge or rebase based on user's choice)
git checkout $BRANCH
# merge: git merge upstream/$BRANCH
# rebase: git rebase upstream/$BRANCH
# 6. View changelog
echo "=== Full Changelog ==="
CURRENT_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v$(node -e 'console.log(require("./package.json").version)')")
echo "Current version: $CURRENT_TAG"
echo ""
# 7. Build and install
npm run build
npm i -g .
# 8. Reinstall systemd service (to update version number)
echo "=== Reinstalling Gateway service ==="
openclaw daemon install --force
# 9. Check version
NEW_VERSION=$(openclaw --version)
echo "✅ Update complete! New version: $NEW_VERSION"
echo ""
# 10. Ask user whether to restart
echo "=== Gateway needs restart to apply updates ==="
echo "Confirm restart? (y/N)"
`
Quick Script
Run scripts/update.sh
to automatically complete all steps above.
Command Line Options
`
bash
./update.sh [OPTIONS]
Options:
--dir PATH OpenClaw project directory (default: $HOME/projects/openclaw)
--branch NAME Git branch to update (default: main)
--mode MODE Update mode: merge or rebase (if not specified, will analyze and recommend)
--dry-run Show what would be done without executing
--help Show this help message
`
Examples
`
bash
# Update with defaults (will analyze and recommend)
./update.sh
# Update specific branch
./update.sh --branch feat/my-branch
# Force merge mode
./update.sh --mode merge
# Force rebase mode
./update.sh --mode rebase
# Dry run (preview only)
./update.sh --dry-run
# Custom project path
./update.sh --dir /opt/openclaw --branch main
`
Notes
- Rebase may cause conflicts - if conflicts occur, resolve manually and continue
- Force push - after rebase, if pushing to fork, use
git push --force
Service reinstall - will update version in systemd unit file
User confirms restart - Gateway will not restart until you confirm
Backup first - always backup before updating!
Troubleshooting
Git Conflicts During Rebase
`
bash
# Resolve conflicts manually, then:
git add .
git rebase --continue
# Continue with build steps
`
Build Fails
`
bash
# Clean and retry:
rm -rf node_modules dist
npm install
npm run build
`
Gateway Won't Start
`
bash
# Check status:
systemctl --user status openclaw-gateway
# View logs:
journalctl --user -u openclaw-gateway -n 50
``
by