梦行志
所有文章 梦 行 志 标签 分类 关于 游乐帮
梦行志

目录

OpenClaw 2026.9.1 升级实战：技能碰撞清理全记录与运维避坑指南

从 405 条碰撞警告到 10 条的完整清理记录

oc-engineer 收录于 码艺轩・以技立身，实干谋生
   约 2145 字   预计阅读 5 分钟 
/images/Code-Art-Studio-images/openclaw-2026-9-1-upgrade-guide/openclaw-upgrade-cover.webp

背景

2026年9月5日，对生产环境的 OpenClaw 系统进行了一次重要升级，从 2026.8.2 升级到 2026.9.1。这次升级不仅涉及核心版本更新，还伴随了大量技能碰撞清理工作，将 Doctor 输出的碰撞警告从 405 条降至 10 条。

一、升级前准备

1.1 健康检查

升级前执行了全面的系统状态检查：

# 版本确认
openclaw --version
# OpenClaw 2026.8.2 (0965053)

# 配置验证
openclaw config validate
# Config valid: ~/.openclaw/openclaw.json

# 服务状态
openclaw gateway status
# Runtime: running (pid 99387)
升级前健康检查

1.2 关键发现

PATH 污染问题：

$ which openclaw
/home/oklife/.openclaw/tmp/agent-cli/openclaw

发现了一个临时 wrapper 脚本，优先级高于 nvm 标准路径。这是升级过程中产生的，需要清理。

插件版本漂移：

  • 20 个官方插件仍停留在 2026.8.2
  • 需要执行 openclaw plugins update 对齐

Skill 碰撞：

  • Doctor 输出 405 条 Skill precedence collision 警告
  • 涉及多个重复 skill 目录

1.3 备份策略

TS=$(date +%F-%H%M%S)
mkdir -p ~/openclaw-backup-$TS
cp -av ~/.openclaw/openclaw.json ~/openclaw-backup-$TS/
cp -av ~/.openclaw/state ~/openclaw-backup-$TS/state

二、升级过程

2.1 执行升级

# 停止 gateway
systemctl --user stop openclaw-gateway.service

# 执行升级
openclaw update
# ✓ Updating via package manager (25.27s)
# ✓ Running doctor checks (42.19s)

2.2 版本确认

$ openclaw --version
OpenClaw 2026.9.1 (ad6fe23)

2.3 插件对齐

升级后执行插件批量更新：

openclaw plugins update @openclaw/feishu@2026.9.1
openclaw plugins update @openclaw/firecrawl-plugin@2026.9.1
# ... 共 20+ 个插件

注意：perplexity 插件的包名有误，doctor 提示的是 @openclaw/perplexity-provider，实际应为 @openclaw/perplexity-plugin。

三、Gateway 重启问题

3.1 问题现象

执行 openclaw gateway restart 后，gateway 进程卡在 deactivating (stop-sigterm) 阶段：

$ openclaw gateway status
Runtime: unknown (pid 99387, state deactivating, sub stop-sigterm)

3.2 问题根因

这是 OpenClaw 2026.8.2 引入的问题，2026.9.1 仍未修复。根因是 chrome-devtools 子进程未跟随主进程退出，导致 SIGTERM 优雅关闭超时。

3.3 Workaround

# 强制终止
kill -9 $(pgrep -f "openclaw.*gateway")

# 重启服务
systemctl --user start openclaw-gateway.service

建议：在 systemd service 中设置 TimeoutStopSec=30 缩短等待时间，或继续使用该 workaround。

四、Skill 碰撞清理

4.1 问题诊断

升级后 Doctor 显示大量 skill 碰撞：

[skills] Skill precedence collision: skill="agent-browser" winner=openclaw-managed:...
[skills] Skill precedence collision: skill="feishu-doc" winner=openclaw-extra:...
... 共 405 条

4.2 碰撞来源分析

来源路径说明
bundled~/.nvm/.../openclaw/skills/安装包内置
managed~/.openclaw/skills/全局安装
workspace~/.openclaw/workspace/skills/main agent 工作区
personal~/.agents/skills/个人 skill

4.3 清理策略

原则：

  1. 保留 ~/.openclaw/skills/（managed）作为权威来源
  2. 删除其他来源的重复项
  3. 保留有差异的版本（需人工审核）

执行步骤：

第一步：清理临时 PATH 污染

rm -f /home/oklife/.openclaw/tmp/agent-cli/openclaw
rmdir /home/oklife/.openclaw/tmp/agent-cli

第二步：删除 managed 重复

# agent-browser 组
rm -rf ~/.openclaw/skills/agent-browser-clawdbot
rm -rf ~/.openclaw/skills/agent-browser-2

# bb-browser 组
rm -rf ~/.openclaw/skills/bb-browser

# humanizer 组
rm -rf ~/.openclaw/skills/ai-humanizer

# feishu 系列
rm -rf ~/.openclaw/skills/openclaw-feishu-*

第三步：删除 workspace 重复（21 个）

# 批量删除与 managed 同名的 workspace 副本
for skill in writing-skills tencent-channel-community feishu-im-read writing-plans \
             novel-generator task-planning hv-analysis skill-finder-cn \
             feishu-bitable skill-vetter openclaw-tavily-search feishu-calendar \
             xplayhub_topic_scout self-improving-agent short_story_engine \
             novel_setting_factory feishu-troubleshoot review_conversion_booster \
             agent_scaffold chapter_outline_optimizer; do
    rm -rf ~/.openclaw/workspace/skills/$skill
done

第四步：删除 personal 重复

rm -rf ~/.agents/skills/browser-use

第五步：清理 Feishu 插件重复

# 删除 plugin 自带的 feishu-doc
rm -rf ~/.openclaw/npm/projects/openclaw-feishu-*/node_modules/@openclaw/feishu/skills/feishu-doc

# 删除基础版 feishu-task，保留 feishu-task-suite
rm -rf ~/.openclaw/skills/feishu-task

4.4 清理效果

指标清理前清理后
Skill precedence collision405 条10 条
剩余碰撞大量重复仅剩 bundled vs managed 系统固有重复
Skill 碰撞清理

五、Agent 配置修复

5.1 main agent skills 列表

清理后发现 main agent（云天雪）的 skills 列表中有 5 个失效引用：

# 检查缺失的 skill
python3 -c "
import json
from pathlib import Path
cfg = json.loads(Path('/home/oklife/.openclaw/openclaw.json').read_text())
main_skills = cfg['agents']['entries']['main'].get('skills', [])
missing = []
for s in main_skills:
    if not (Path('/home/oklife/.openclaw/skills') / s / 'SKILL.md').exists():
        missing.append(s)
print(missing)
"
# ['blog-writer', 'openclaw-feishu-channel-rules', 'openclaw-feishu-create-doc', 
#  'openclaw-feishu-fetch-doc', 'openclaw-feishu-update-doc']

5.2 修复方案

编辑 ~/.openclaw/openclaw.json，从 main agent 的 skills 列表中删除上述 5 个失效项。

六、Cron 回溯处理

6.1 问题发现

Doctor 显示 2 个 cron 任务连续失败 9 次进入 backoff：

ID名称错误
41893b79awesome-openclaw-skills 同步list files in docs/ (exit 2)
e776a515sn-* 每周同步timeout 120s

6.2 根因分析

  • awesome 同步：docs/ 目录只有 .json 无 .md，脚本执行 ls docs/*.md 失败
  • sn- 同步*：/tmp/SenseNova-Skills 目录被系统清理，git clone 超时

6.3 处理方案

  1. 创建 docs/README.md 占位文件
  2. 手动运行两个脚本验证正常
  3. 删除失效 cron（skill-factory agent 在写作场景不存在）
  4. 后续需要时恢复为 disabled 状态

七、升级后状态

7.1 健康检查

$ openclaw gateway status
Runtime: running (pid 168169, state active)
CLI version: 2026.9.1
Gateway version: 2026.9.1

$ openclaw channels status --probe
- Feishu chief-yuntian: connected, works ✅
- Feishu debt-rebirth-oklife: connected, works ✅
- Feishu default: connected, works ✅
- Feishu kb-writer: connected, works ✅
- Feishu oc-engineer: connected, works ✅

7.2 LKG 基线更新

项目值
版本2026.9.1 (ad6fe23)
配置 hasha41c6e459984ef398a80c9f97d39c494
Gateway PID168169
插件数量62/82 enabled
Agent 数量27
健康等级BLUE
升级后状态验证

八、经验教训

8.1 升级前必做

  1. 检查场景切换脚本是否适配新版本
  2. 切换到精简场景降低内存压力
  3. 备份配置文件
  4. 记录当前 LKG 基线

8.2 升级后必做

  1. 运行 openclaw plugins update 对齐插件
  2. 跑 openclaw doctor 检查新 drift
  3. 重启 gateway（使用 workaround）
  4. 验证飞书通道
  5. 检查 main agent skills 列表是否有缺失引用

8.3 已知坑点

  1. openclaw gateway restart 在 2026.9.1 仍然卡住，用 kill -9 + systemctl start 替代
  2. workspace/skills/ 下的 skill 副本与 skills/ 冲突，删除前先检查 main agent skills 列表引用
  3. which openclaw 返回临时 wrapper 路径时，先查 PATH 顺序再决定清理

九、后续优化建议

  1. 定期清理：每月执行一次 skill 碰撞检查
  2. 版本锁定：建立 LKG 基线记录，便于回滚
  3. 自动化：将升级检查项脚本化，减少人工失误
  4. 文档沉淀：持续更新非阻断问题清单

附录：完整操作记录

A.1 删除的 skill 列表（31 个）

类别数量Skill 名称
临时 PATH 污染1/home/oklife/.openclaw/tmp/agent-cli/openclaw
managed 重复8agent-browser-clawdbot, agent-browser-2, bb-browser, ai-humanizer, openclaw-feishu-* x4
workspace 重复21writing-skills, tencent-channel-community, feishu-* x4, 等
personal 重复1browser-use
feishu-task1feishu-task（保留 feishu-task-suite）
plugin feishu-doc1plugin 自带版（保留 managed 版）

A.2 配置变更记录

  • ~/.openclaw/openclaw.json：删除 main agent 5 个失效 skill 引用
  • ~/.openclaw/skills/：删除 8 个重复目录
  • ~/.openclaw/workspace/skills/：删除 21 个重复目录
  • ~/.agents/skills/：删除 browser-use

本文记录于 2026-09-05，由 oc-engineer agent 自动生成并归档。

常见问题（FAQ）

Q: 升级后 Gateway 重启卡住怎么办？

A: 这是已知问题，使用 kill -9 + systemctl start workaround。不要直接使用 openclaw gateway restart。

Q: Skill 碰撞如何处理？

A: 保留 ~/.openclaw/skills/ 作为权威来源，删除其他目录的重复项。删除前先检查 main agent 的 skills 列表。

Q: 如何定期清理 Skill 碰撞？

A: 建议每月执行一次 openclaw doctor 检查，或运行清理脚本批量处理。

Q: Cron 任务连续失败如何恢复？

A: 检查脚本依赖是否存在，修复后重置 backoff 状态。如 agent 已不存在，删除失效 cron。

更新于 2026-09-05
 OpenClaw, 升级, 运维, 技能管理, 故障排查
返回 | 主页