OpenClaw Update Skill

---

name: openclaw-update

description: OpenClaw 版本升级评估与执行技能。工作流程：(1) 检测 agent-reach 可用性（无则引导安装），(2) 检查 GitHub releases 获取最新稳定版，(3) 对比当前版本判断是否需要更新，(4) 分析版本差距和更新日志，(5) 检查 GitHub issues 评估风险，(6) 综合评估打分并给出升级建议，(7) 备份用户配置（防止冲突），(8) 检测安装方式执行对应更新命令，(9) 自动重启 gateway，(10) 提供恢复功能。Use when 用户要求检查 OpenClaw 更新、评估是否升级、或执行版本更新。支持中英双语。

---

# OpenClaw Update Skill

Multilingual Support / 多语言支持

**Detect user language and respond accordingly:**

**检测用户语言并相应回复：**

---

Prerequisites / 前置要求

Agent-Reach Detection / Agent-Reach 检测

**Before using this skill, detect if agent-reach is available:**

# Detection command
agent-reach --version 2>&1 || echo "Not installed"

**If not installed, guide user to install:**

# Method 1: pipx install (recommended)
pipx install https://github.com/Panniantong/agent-reach/archive/main.zip
agent-reach install --env=auto

# Method 2: Check for alternative GitHub access
# Such as gh CLI, curl (not recommended, may be blocked)

**If user cannot install agent-reach:**

---

Workflow / 工作流程

Step 0: Detect Agent-Reach Availability / 检测 Agent-Reach 可用性

**Use detection script (recommended):**

python3 scripts/check_agent_reach.py

**Or manual detection:**

# Test if agent-reach is available
agent-reach read "https://github.com/openclaw/openclaw" --timeout 10 2>&1

**If successful**: Continue to next step

**If failed**:

1. Inform user agent-reach is unavailable

2. Provide installation guide (see Prerequisites or run `python3 scripts/check_agent_reach.py`)

3. Ask if user wants to continue (manual mode) or install agent-reach first

---

Step 1: Check Current Version / 检查当前版本

**Progress message:**

> 📋 **Step 1/10: Checking current version** / **正在执行第 1 步：检查当前版本**

openclaw --version

Record current version (e.g., v2026.3.2)

---

Step 2: Get Latest Version Info / 获取最新版本信息

**Progress message:**

> 📋 **Step 2/10: Fetching latest version from GitHub** / **正在执行第 2 步：从 GitHub 获取最新版本**

Use `agent-reach` to access GitHub releases page:

agent-reach read "https://github.com/openclaw/openclaw/releases"

Extract:

---

Step 3: Version Comparison / 版本对比

**Progress message:**

> 📋 **Step 3/10: Comparing versions** / **正在执行第 3 步：版本对比**

**If versions match:**

**If versions differ:**

---

Step 4: Analyze Update Content / 分析更新内容

**Progress message:**

> 📋 **Step 4/10: Analyzing release notes** / **正在执行第 4 步：分析更新日志**

For each version to update, use `agent-reach` to read detailed release notes:

agent-reach read "https://github.com/openclaw/openclaw/releases/tag/v2026.3.X"

Record:

**Strictly reference official release notes** - do not fabricate information.

---

Step 5: Check Issues / 检查 Issues

**Progress message:**

> 📋 **Step 5/10: Checking GitHub issues for risks** / **正在执行第 5 步：检查 GitHub issues 评估风险**

Access GitHub issues page to assess risks:

agent-reach read "https://github.com/openclaw/openclaw/issues"

Check:

**Critical Rule:** If dangerous issues are found, MUST stop and inform user. If major bugs are found, FORBID the update on behalf of user!

---

Step 6: Comprehensive Assessment / 综合评估

**Progress message:**

> 📋 **Step 6/10: Scoring and assessment** / **正在执行第 6 步：综合评估打分**

Score based on following dimensions (0-2 points each):

| Dimension | Scoring Criteria |

|-----------|-----------------|

| **Feature Value** | 0=No new features, 1=Minor improvements, 2=Major feature updates |

| **Security** | 0=Security issues exist, 1=No security updates, 2=Security fixes included |

| **Stability** | 0=Many bug reports, 1=Few issues, 2=Issues are clean |

| **Breaking** | 0=Has breaking changes, 1=Config adjustment needed, 2=Fully compatible |

| **Urgency** | 0=Optional update, 1=Recommended, 2=Strongly recommended |

**Total Score ≥8**: Strongly recommend update

**Total Score 6-7**: Recommend update

**Total Score 4-5**: Optional update

**Total Score <4**: Recommend postponing

**Critical Rule:** Assessment must be objective, no emotional bias!

---

Step 7: Backup User Configuration / 备份用户配置

**Progress message:**

> 📋 **Step 7/10: Backing up user configuration** / **正在执行第 7 步：备份用户配置**

**Detect OS and create unique backup name:**

# Detect OS
if [[ "$OSTYPE" == "darwin"* ]]; then
    OS="macOS"
elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
    OS="Linux"
elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
    OS="Windows"
else
    OS="Unknown"
fi

# Generate unique backup name with timestamp
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_NAME=".openclaw.backup.${TIMESTAMP}"

# Check for naming conflicts (CRITICAL RULE)
if [ -d "~/${BACKUP_NAME}" ]; then
    # Add random suffix to avoid conflict
    RANDOM_SUFFIX=$(openssl rand -hex 4)
    BACKUP_NAME=".openclaw.backup.${TIMESTAMP}.${RANDOM_SUFFIX}"
fi

# Execute backup based on OS
case "$OS" in
    "macOS"|"Linux")
        cp -r ~/.openclaw ~/${BACKUP_NAME}
        ;;
    "Windows")
        # PowerShell command
        powershell.exe -Command "Copy-Item -Recurse $env:USERPROFILE\.openclaw $env:USERPROFILE\.${BACKUP_NAME}"
        ;;
esac

echo "✅ Backup created: ~/${BACKUP_NAME}"

**Critical Rules:**

1. NEVER overwrite existing backups

2. ALWAYS use unique timestamp + random suffix

3. ALWAYS inform user of backup location at the end

---

Step 8: Detect Installation Method & Update / 检测安装方式并更新

**Progress message:**

> 📋 **Step 8/10: Detecting installation method and updating** / **正在执行第 8 步：检测安装方式并执行更新**

**Detect installation method:**

# Check for git installation
if [ -d ~/.openclaw/.git ]; then
    INSTALL_METHOD="git"
    echo "Detected: Source installation (git clone)"
else
    INSTALL_METHOD="npm"
    echo "Detected: Global installation (npm/pnpm)"
fi

# Check Gateway running method
if launchctl list | grep -q openclaw 2>/dev/null; then
    GATEWAY_MODE="launchd"
elif systemctl list-units | grep -q openclaw 2>/dev/null; then
    GATEWAY_MODE="systemd"
else
    GATEWAY_MODE="terminal"
fi

**Execute update based on installation method:**

**For Global Installation (npm/pnpm):**

# npm
npm i -g openclaw@latest

# Or pnpm
pnpm add -g openclaw@latest

# NOT recommended: Bun (WhatsApp/Telegram bugs)

**For Source Installation (git):**

openclaw update
# Or with channel
openclaw update --channel stable

**Official recommended method (re-run installer):**

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

---

Step 9: Restart Gateway / 重启 Gateway

**Progress message:**

> 📋 **Step 9/10: Restarting Gateway** / **正在执行第 9 步：重启 Gateway**

# Preferred for service-managed Gateway
openclaw gateway restart

# Then verify
openclaw doctor
openclaw health

**If restart fails:**

---

Step 10: Report & Recovery Info / 报告与恢复信息

**Progress message:**

> 📋 **Step 10/10: Generating final report** / **正在执行第 10 步：生成最终报告**

**Final report must include:**

1. Update result (success/failure)

2. Backup location (with full path)

3. Recovery instructions

4. Any issues encountered

**Recovery commands (if needed):**

# macOS / Linux
rm -rf ~/.openclaw && cp -r ~/.openclaw.backup.TIMESTAMP ~/.openclaw

# Windows PowerShell
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw
Copy-Item -Recurse $env:USERPROFILE\.openclaw.backup.TIMESTAMP $env:USERPROFILE\.openclaw

**When user wants to recover:**

---

Automated Daily Check / 自动定时检查

Setup Cron Task / 设置 Cron 任务

**After installing this skill, offer to create a cron task for automatic daily checks:**

**Progress message:**

> 🤖 **Setting up automated daily update check...** / **正在设置自动每日更新检查...**

**Create cron task that runs at 4:00 AM daily:**

# Method 1: Using OpenClaw cron (recommended)
cron add --name "openclaw-daily-update-check" \
  --schedule "0 4 * * *" \
  --command "python3 ~/.openclaw/workspace/skills/openclaw-update/scripts/cron_check.py"

**What the cron task does:**

1. Runs every day at 4:00 AM

2. Checks GitHub for latest version

3. Compares with current version

4. Checks GitHub issues for critical bugs

5. Sends system notification if update available

6. Saves detailed report to `~/.openclaw/update_check_report.txt`

7. Waits for user approval before proceeding with update

**User approval workflow:**

Cron Script Location / Cron 脚本位置

~/.openclaw/workspace/skills/openclaw-update/scripts/cron_check.py

Manual Setup Commands / 手动设置命令

**macOS / Linux:**

# Add to crontab
crontab -e

# Add this line (runs at 4:00 AM daily)
0 4 * * * /usr/bin/python3 ~/.openclaw/workspace/skills/openclaw-update/scripts/cron_check.py >> ~/.openclaw/cron_check.log 2>&1

**Windows Task Scheduler:**

# Create scheduled task
$action = New-ScheduledTaskAction -Execute "python" -Argument "~/.openclaw/workspace/skills/openclaw-update/scripts/cron_check.py"
$trigger = New-ScheduledTaskTrigger -Daily -At 4am
Register-ScheduledTask -TaskName "OpenClaw Daily Update Check" -Action $action -Trigger $trigger

Notification Examples / 通知示例

**New version available:**

╔═══════════════════════════════════════════════════════════╗
║  OpenClaw Update Available / 发现新版本                    ║
╠═══════════════════════════════════════════════════════════╣
║  Current: v2026.3.2                                       ║
║  Latest:  v2026.3.7                                       ║
║  Issues:  Issues 状态良好                                  ║
║                                                           ║
║  ✅ Backup will be created before update                  ║
║  📋 Reply "确认更新" to start update                      ║
╚═══════════════════════════════════════════════════════════╝

**Already up to date:**

✅ OpenClaw Up to Date / 已是最新版本
Current: v2026.3.7
No update needed.

**Critical issues found:**

⚠️ CRITICAL ISSUES FOUND! Update NOT recommended.
Issues: 发现多个严重问题
Please wait for next release.

---

Output Format / 输出格式

Assessment Report Template / 评估报告模板

## 📊 OpenClaw Version Assessment Report / 版本评估报告

### Version Info / 版本信息
- **Current Version / 当前版本**: v2026.3.2
- **Latest Version / 最新版本**: v2026.3.7
- **Version Gap / 版本差距**: 5 minor versions

### 🔍 Update Analysis / 更新内容分析

#### New Features / 新增功能
- Feature 1
- Feature 2

#### Bug Fixes / Bug 修复
- Fix 1
- Fix 2

#### Breaking Changes / 破坏性变更
- ⚠️ Change description (if any)

### 📈 Issues Assessment / Issues 评估
- **Open Issues / 开放 issues 数量**: X
- **Critical Bugs / 严重 bug**: None/Yes (describe)
- **Upgrade Issues / 升级问题**: None/Yes (describe)

### 🎯 Scoring / 综合评分

| Dimension / 维度 | Score / 得分 |
|-----------------|-------------|
| Feature Value / 功能价值 | X/2 |
| Security / 安全性 | X/2 |
| Stability / 稳定性 | X/2 |
| Breaking / 破坏性 | X/2 |
| Urgency / 紧迫性 | X/2 |
| **Total / 总分** | **X/10** |

### 💡 Recommendation / 更新建议

**Recommendation Index / 推荐指数**: X/10 (Strongly Recommended/Recommended/Optional/Postpone)

**Reasons / 理由**:
- ✅ Pro 1
- ✅ Pro 2
- ⚠️ Considerations

### 🛠️ Update Steps / 更新步骤

# Commands

### 💾 Backup Info / 备份信息
**Backup Location / 备份位置**: `~/.openclaw.backup.20260311_155100.a3f2b1c4`
**Recovery Command / 恢复命令**: See above

---

Critical Rules / 铁律

RED LINES - NEVER VIOLATE / 红线 - 禁止违反

1. **NEVER create backup naming conflicts** / **禁止备份文件名冲突**

- Always check for existing backups

- Use timestamp + random suffix

- Never overwrite user's existing backups

2. **NEVER run silently** / **禁止静默运行**

- Always report current step progress

- Inform user before each major action

- Report backup location at the end

3. **NO emotional assessment** / **禁止带情绪评估**

- Assessment must be objective

- Score based on facts, not feelings

- Let data drive the recommendation

4. **MUST strictly reference release notes** / **必须严格参照版本更新日志**

- Read official release notes

- Do not fabricate information

- Cite sources for all claims

5. **MUST check issues for threats** / **必须检查 issues 的威胁**

- Check GitHub issues before recommending update

- If dangerous issues found: STOP and inform user

- If major bugs found: FORBID update on behalf of user

---

Related Skills / 相关技能

---

Example Output / 示例输出

See `references/example-report.md` for complete assessment report example.