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

目录

OpenClaw 2026.9.2 升级实战：从配置漂移到健康恢复

一次完整的升级流程 + 6 项配置修复经验总结

梦行志 收录于 码艺轩・以技立身，实干谋生
   约 1587 字   预计阅读 4 分钟 
/images/Code-Art-Studio-images/openclaw-2026-9-2-upgrade-troubleshooting/openclaw-2026-9-2-upgrade-troubleshooting.webp

OpenClaw 2026.9.2 升级实战：从配置漂移到健康恢复

背景

OpenClaw 是开源的多 Agent 协作平台，支持灵活的场景切换和插件系统。每次大版本升级都可能引入配置漂移（drift），需要系统性检查和修复。

本文记录从 2026.9.1 升级到 2026.9.2 的完整流程，以及发现的 6 项配置问题和修复方案。

升级前准备

1. 创建备份

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-upgrade.$(date +%Y%m%d-%H%M%S)
cp ~/.openclaw/openclaw.json.full ~/.openclaw/openclaw.json.full.pre-upgrade.$(date +%Y%m%d-%H%M%S)

# 备份 state 目录
mkdir -p ~/openclaw-backup-$(date +%Y%m%d-%H%M%S)
cp -r ~/.openclaw/state ~/openclaw-backup-$(date +%Y%m%d-%H%M%S)/

2. 切换到精简场景

升级前切换到写作场景（27 个 agent），降低内存压力：

python3 ~/.openclaw/scenes/switch-scene.py writing

验证：

jq '.agents.entries | keys | length' ~/.openclaw/openclaw.json
# 输出: 27
升级流程时序图：从备份到最终验证共8个步骤

升级步骤

Step 1: 系统级升级

sudo apt update && sudo apt upgrade -y

本次升级包含 NVIDIA 驱动更新：595.84 → 595.91.07

Step 2: 停止 Gateway

systemctl --user stop openclaw-gateway.service

优雅关闭耗时约 50 秒。

Step 3: OpenClaw 升级

openclaw update

输出示例：

Updating OpenClaw to 2026.9.2...
Successfully updated to 2026.9.2 (3928bad)

Step 4: 插件对齐

openclaw plugins update --all

输出：

20 plugins updated to 2026.9.2

Step 5: 重启 Gateway

⚠️ 已知坑点：openclaw gateway restart 在 2026.9.2 仍然卡住。

Workaround：使用 kill -9 强制终止后重启：

# 查找 gateway 进程
pgrep -f "openclaw-gateway"

# 强制终止
kill -9 <PID>

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

Step 6: 配置校验

openclaw config validate

输出：

✅ Configuration valid
✅ All plugins loaded
✅ Agent configurations OK
配置校验流程图：4项检查全部通过

发现的问题与修复

升级后运行 openclaw doctor，发现以下配置漂移问题：

问题 1: kb-writer bootstrap 超限

现象：

kb-writer workspace bootstrap file exceeds limit, truncated

根因：kb-writer 的 AGENTS.md (50K) + MEMORY.md (44K) = 94K raw，超过默认 48K 限制。

修复：

{
  "bootstrapMaxChars": 128000,
  "bootstrapTotalMaxChars": 256000
}

验证：

jq '.agents.entries["kb-writer"].bootstrapMaxChars' ~/.openclaw/openclaw.json
# 输出: 128000

问题 2: skill_workshop 权限缺失

现象：

Agent chief-yuntian: tools profile must include skill_workshop
Agent oc-engineer: tools profile must include skill_workshop

修复：

// 添加到 agents.entries.chief-yuntian.tools.alsoAllow
"skill_workshop"

// 添加到 agents.entries.oc-engineer.tools.alsoAllow
"skill_workshop"

问题 3: kb-maintenance SKILL.md 缺少 description

现象：

Skill ~.openclaw/workspace-kb-manager/skills/kb-maintenance/SKILL.md skipped: missing description

修复：添加 frontmatter：

---
description: 知识库整理维护经验技能，记录 Obsidian 死链修复、归类整理、脚本工具使用的实战经验和教训。
---

问题 4: 配置文件权限过宽

现象：

Permission 664 for ~/.openclaw/openclaw.json is too open

风险：配置文件包含敏感信息（API keys, tokens），664 权限允许同组用户读取。

修复：

chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/openclaw.json.full

⚠️ 注意：gateway 重启会将权限重置为 664，需每次重启后手动修复。

问题 5: Feishu 工具名残留

现象：

Agent kb-writer: unknown tool feishu_calendar_calendar in skills
Agent X: unknown tool feishu_oauth in tools.alsoAllow
...

根因：旧版 feishu 插件工具名已更新，但配置中仍引用旧名称。

修复：从以下位置移除残留工具名：

  • agents.entries.kb-writer.skills：移除 feishu_calendar_calendar, feishu_oauth, feishu_sheet, feishu_task_task, feishu_task_agent, feishu_task_attachment
  • 其他 agent 的 tools.alsoAllow：移除相同残留

保留的有效工具：feishu_chat（当前插件提供）

验证：

grep -c "feishu_calendar_calendar\|feishu_oauth\|feishu_sheet\|feishu_task_task\|feishu_task_agent\|feishu_task_attachment" ~/.openclaw/openclaw.json
# 输出: 0

问题 6: view_image 残留

现象：

Agent agents-orchestrator: unknown tool view_image in tools
Agent design-yuntianguang: unknown tool view_image in tools
Agent search-scout-yuntianyan: unknown tool view_image in tools

修复：从 3 个 agent 的 tools.alsoAllow 中移除 view_image。

验证：

grep -c "view_image" ~/.openclaw/openclaw.json
# 输出: 0
问题修复清单表：6项配置漂移修复方案

配置同步

将 openclaw.json 的修复同步到 openclaw.json.full，确保完整场景配置一致：

# 关键配置项对比
echo "kb-writer bootstrap:"
echo "  json:   $(jq '.agents.entries["kb-writer"].bootstrapMaxChars' ~/.openclaw/openclaw.json)"
echo "  full:   $(jq '.agents.entries["kb-writer"].bootstrapMaxChars' ~/.openclaw/openclaw.json.full)"

echo "chief-yuntian skill_workshop:"
echo "  json:   $(jq '.agents.entries["chief-yuntian"].tools.alsoAllow | index("skill_workshop")' ~/.openclaw/openclaw.json)"
echo "  full:   $(jq '.agents.entries["chief-yuntian"].tools.alsoAllow | index("skill_workshop")' ~/.openclaw/openclaw.json.full)"

输出应全部一致：

kb-writer bootstrap:
  json:   128000
  full:   128000
chief-yuntian skill_workshop:
  json:   5
  full:   5

最终验证

健康检查

openclaw doctor

输出：

=== OpenClaw Doctor Report ===
Version: 2026.9.2 (3928bad)
Config: ✅ Valid
Plugins: ✅ 20 loaded
Agents: ✅ 27 configured
Channels: ✅ 5/5 connected (Feishu)
Health: 🟢 GREEN

配置 MD5

md5sum ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.full
#bec27639a6bb63bae6ed5280b234aeaf  ~/.openclaw/openclaw.json
9319c99cba941641beb661390cd78439  ~/.openclaw/openclaw.json.full

LKG 基线记录

项目值
OpenClaw 版本2026.9.2 (3928bad)
升级日期2026-09-08
上一版2026.9.1 (ad6fe23)
配置 MD56469b625730bbdad437af7bd83a6a5ec
插件数量全部 2026.9.2
Agent 数量27（写作场景）/ 285（完整场景）
飞书通道5/5 connected, works ✅
健康等级🟢 GREEN
上一版2026.9.1 (ad6fe23)
配置 MD5bec27639a6bb63bae6ed5280b234aeaf
插件数量全部 2026.9.2
Agent 数量27（写作场景）/ 285（完整场景）
飞书通道5/5 connected, works ✅
健康等级🟢 GREEN

经验教训

升级前必做

  1. 按文档流程执行：备份 → 场景切换 → 停止服务 → 升级 → 插件对齐 → 重启
  2. 切换到精简场景（writing 27 agents）降低内存压力
  3. 备份配置文件和 state

升级后必做

  1. 运行 openclaw plugins update --all 对齐插件
  2. 跑 openclaw doctor 检查新 drift
  3. 重启 gateway（用 kill -9 workaround）
  4. 验证飞书通道
  5. 检查 kb-writer bootstrap 限制
  6. 检查 tool 权限配置
  7. 清理残留工具名
  8. 同步 openclaw.json.full
  9. 修复配置文件权限（gateway 重启会重置为 664）

已知坑点

问题workaround
openclaw gateway restart 卡住用 kill -9 + systemctl start 替代
配置文件权限被重置每次重启后手动 chmod 600
写作场景 doctor 报告"孤儿"目录正常现象，27 agent 场景不需要完整目录结构
feishu 旧工具名残留从配置中移除，保留 feishu_chat 等有效名称

参考来源

关联阅读

  • [[OpenClaw 运维日记：一次 Doctor 健康检查与 13 个问题修复实战]]
  • [[OpenClaw 场景切换与内存管理]]
  • [[kb-writer bootstrap 配置详解]]
更新于 2026-09-08
 OpenClaw, 运维, 升级, 配置管理, 排障
返回 | 主页