作者：海风

日期：2026-03-19

环境：云服务器 / OpenClaw 2026.3.8 / Node 24.14.0 / 飞书 Agent

关键词： OpenClaw、飞书机器人、备份恢复、配置丢失、排障实录

注：文中人名、Agent 名称、API 密钥、模型配置等均已做脱敏处理，以化名和占位符代替。

前言

我用 OpenClaw 搭建了一个飞书 AI Agent「小助手」，跑在云服务器 上，接入了大模型，日常帮我查行情、推新闻、聊天解闷。运行得好好的，直到我想 "做个备份，以防万一"。

结果这个"以防万一"，变成了整整 5 个小时的排障马拉松。

这篇文章完整记录了整个翻车过程和最终的解决方案，希望能帮到同样在用 OpenClaw 的朋友们。

一、起因：一个看似简单的备份操作

系统升级到 OpenClaw 2026.3.8 后运行正常，飞书 Agent 在线服务。我决定做一次备份，心想万一以后升级出问题还能回滚。

于是执行了 OpenClaw 内置的备份恢复命令：

openclaw-restore.sh latest --yes

然后……飞书 Agent 就再也不回消息了。

二、第一个坑：备份文件不完整

现象

Gateway 启动后，日志里完全看不到任何 feishu 或 Registered 相关的输出。飞书插件像是从未存在过一样。

排查

检查恢复出来的 openclaw.json，发现配置文件严重残缺：

python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
for key in ['channels','models','env','plugins','agents']:
    print(f'{key}: {key in cfg}')
"

输出让人崩溃：

channels: False    # 飞书凭据没了！
models: False      # 模型配置没了！
env: False         # API Key 没了！
plugins: True      # 只剩这个壳子
agents: True       # 但 agents.list 是空的

内置的备份工具只保存了配置的骨架，飞书的 appId、appSecret、WebSocket 模式、模型 provider、环境变量等关键字段全部丢失。

教训 1： 永远不要盲目信任内置的备份恢复工具。恢复之后第一件事是验证配置的完整性，而不是直接重启服务。

三、第二个坑：运行中的 Gateway 会覆盖配置

现象

好在我发现系统自动创建了一个 .broken 目录，里面保存了恢复前的完整旧配置：

ls /root/.openclaw.broken-20260319-104242/openclaw.json

验证旧配置是完整的：

channels.feishu.mode: websocket   ✅
channels.feishu.appId: cli_xxxx... ✅
models: True ✅
env: True ✅

太好了！直接 cp 回去不就行了吗？

cp /root/.openclaw.broken-20260319-104242/openclaw.json /root/.openclaw/openclaw.json

然后验证……

channels.feishu: None   # ???又没了！！！

反复试了好几次，每次 cp 之后验证都是空的。这完全不合逻辑——直到我意识到 Gateway 还在运行。

运行中的 Gateway 进程会监控 openclaw.json，检测到文件变化后，会用自己内存中的（残缺的）配置重新写入磁盘，覆盖我们手动做的修改。

这就是今天最大的坑：我在 Gateway 运行的情况下反复修改配置，每次都被覆盖，绕了好几个小时。

教训 2：修改 openclaw.json 之前，必须先执行 openclaw gateway stop！ 这是铁律，不可跳过。

四、第三个坑：插件路径不存在

现象

停掉 Gateway 后，成功恢复了完整配置。但 plugins.installs.feishu 的路径指向了一个不存在的目录：

{
  "plugins": {
    "installs": {
      "feishu": {
        "source": "npm",
        "spec": "@openclaw/feishu",
        "installPath": "/root/.openclaw/extensions/feishu",
        "version": "2026.2.25"
      }
    }
  }
}

验证：

ls /root/.openclaw/extensions/feishu
# ls: cannot access '/root/.openclaw/extensions/feishu': No such file or directory

find / -name "package.json" -path "*/feishu/*" 2>/dev/null
# 没有任何输出

原因

旧版本的 feishu 插件是通过 npm 安装到 ~/.openclaw/extensions/feishu 的，但这个目录在某次操作中被清除了。

尝试通过 npm 重装

npm install -g @openclaw/feishu@2026.3.8   # ETARGET - 版本不存在
npm install -g @openclaw/feishu@2026.3.13  # 依赖冲突失败
npm install -g @openclaw/feishu@2026.3.7   # 目录结构不对

npm 安装全部失败。

柳暗花明

但是！我发现 OpenClaw 2026.3.8 内置了 feishu 插件：

ls /usr/lib/node_modules/openclaw/extensions/feishu/
# index.ts  node_modules  openclaw.plugin.json  package.json  skills  src

完整、可用！只需要把配置指向这里。

五、第四个坑：source 字段的合法值

现象

既然是内置插件，那 source 设置为 "builtin" 应该没问题吧？

"feishu": {
  "source": "builtin",
  "installPath": "/usr/lib/node_modules/openclaw/extensions/feishu"
}

重启后 Gateway 疯狂报错，进入 crash loop：

Config invalid
plugins.installs.feishu.source: Invalid input (allowed: "npm", "archive", "path")
Gateway aborted: config is invalid.

每隔约 14 秒崩溃重启一次。

OpenClaw 只接受三种 source 类型："npm"、"archive"、"path"，没有 "builtin" 这个选项。对于内置插件，正确的做法是用 "path" 并指向内置路径。

教训 3： 不要想当然地猜配置值。查不到文档就试 openclaw doctor --fix，或者查看错误提示中给出的合法值列表。

六、最终解决方案

经过反复折腾，最终总结出正确的修复流程：

第 1 步：停止 Gateway（最关键！）

openclaw gateway stop

第 2 步：合并旧配置中缺失的字段

不再用 cp 整个覆盖（怕覆盖掉中间修正过的值），而是用 Python 脚本精准合并：

python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
with open('/root/.openclaw.broken-20260319-104242/openclaw.json') as f:
    old = json.load(f)

# 从旧配置补回所有缺失的关键字段
for key in ['channels','env','models','tools','messages','session','hooks']:
    if key in old:
        cfg[key] = old[key]

# agents 特殊处理：保留当前 model 设置
saved_model = cfg.get('agents',{}).get('defaults',{}).get('model')
cfg['agents'] = old['agents']
if saved_model:
    cfg['agents']['defaults']['model'] = saved_model

with open('/root/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2)
print('Done.')
"

第 3 步：修正插件路径

python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
cfg['plugins']['installs']['feishu']['source'] = 'path'
cfg['plugins']['installs']['feishu']['installPath'] = '/usr/lib/node_modules/openclaw/extensions/feishu'
with open('/root/.openclaw/openclaw.json', 'w') as f:
    json.dump(cfg, f, indent=2)
print('Done.')
"

第 4 步：验证配置完整性

python3 -c "
import json
with open('/root/.openclaw/openclaw.json') as f:
    cfg = json.load(f)
print('channels.feishu.mode:', cfg.get('channels',{}).get('feishu',{}).get('mode'))
print('feishu.source:', cfg.get('plugins',{}).get('installs',{}).get('feishu',{}).get('source'))
print('feishu.installPath:', cfg.get('plugins',{}).get('installs',{}).get('feishu',{}).get('installPath'))
print('has models:', 'models' in cfg)
print('has env:', 'env' in cfg)
print('model:', cfg.get('agents',{}).get('defaults',{}).get('model'))
"

期望输出：

channels.feishu.mode: websocket
feishu.source: path
feishu.installPath: /usr/lib/node_modules/openclaw/extensions/feishu
has models: True
has env: True
model: your-provider/your-model

第 5 步：启动并验证

openclaw gateway install --force && openclaw gateway restart
sleep 20
tail -n 50 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -i "feishu\\|Registered\\|WebSocket"

看到以下输出就是成功了：

feishu_doc: Registered feishu_doc, feishu_app_scopes
feishu_chat: Registered feishu_chat tool
feishu_wiki: Registered feishu_wiki tool
feishu_drive: Registered feishu_drive tool
feishu_bitable: Registered bitable tools
starting feishu[default] (mode: websocket)
feishu[default]: bot open_id resolved: ou_xxxxxxxxxxxx...  
feishu[default]: WebSocket client started

飞书 Agent 重新上线！

七、根因分析

问题 根因 解决
恢复后飞书不回消息 内置备份工具只保存部分配置字段 从 .broken 旧配置合并缺失字段
配置改了又被覆盖 Gateway 运行中会监控并重写配置文件 先 openclaw gateway stop 再改
插件加载失败 installPath 指向已删除的 npm 安装目录 改用内置路径 /usr/lib/node_modules/openclaw/extensions/feishu
Gateway crash loop source: "builtin" 不是合法值 改为 source: "path"

八、正确的全盘备份方案

吃了这次亏后，我写了一套真正靠谱的全盘备份恢复脚本，核心思路：

备份

  • 先 openclaw gateway stop
  • tar czf 打包整个 ~/.openclaw/ 目录
  • 自动检查配置完整性
  • 自动清理旧备份（保留最近 10 份）
  • 重启 Gateway

恢复

  • 先 openclaw gateway stop
  • 备份当前配置到 .pre-restore-* 目录
  • 解压恢复
  • 自动修正已知问题（gateway.mode、installPath）
  • 配置完整性检查
  • 重启并等待 20 秒验证飞书连接

定时备份

# crontab -e 添加：
0 3 * * * /root/openclaw-full-backup.sh >> /root/openclaw-backups/backup.log 2>&1

完整脚本代码见我的另一篇文档，这里不再赘述。

九、第五个坑：Agent 恢复连接却完全失忆

现象

Gateway 修好了，飞书连上了，满心欢喜地发消息测试：

你叫什么名字？

回答：

我是你的AI助手……根据我读取的 SOUL.md 和 IDENTITY.md，我正在形成自己的身份。

完全不认识自己。不知道自己叫什么，不知道主人是谁，不知道 TuShare 已配好。5 小时修好了连接，Agent 却变成了一个"新生儿"。

排查

检查工作区文件，AGENT.md 和 MEMORY.md 都在：

ls -la ~/.openclaw/workspace/*.md

-rw-r--r-- AGENT.md    (134行) ← 从 .broken 恢复的
-rw-r--r-- MEMORY.md   (84行)  ← 从 .broken 恢复的
-rw-r--r-- AGENTS.md   (212行) ← 从 .broken 恢复的

文件都在，内容也对，为什么 Agent 不认？

仔细看 Agent 的回复："根据我读取的 SOUL.md 和 IDENTITY.md" —— 它在读 SOUL.md，不是 AGENT.md！

根因：新版框架换了配置文件

扫描工作区所有 .md 文件后真相大白：

find ~/.openclaw/workspace -name '*.md' -exec ls -la {} \\;
文件 状态 说明
SOUL.md ❌ 通用模板 "You're not a chatbot. You're becoming someone."
IDENTITY.md ❌ 空模板 "Fill this in during your first conversation"
USER.md ⚠️ 基本信息 只知道主人称呼
AGENTS.md ❌ 被覆盖 原来 212 行调度规则被替换成通用模板
MEMORY.md ✅ 已恢复 我们从 .broken 恢复的
AGENT.md ✅ 已恢复 我们从 .broken 恢复的，但新框架根本不读它
BOOTSTRAP.md 🆕 新增 首次运行引导
HEARTBEAT.md 🆕 新增 心跳配置
TOOLS.md 🆕 新增 工具笔记

OpenClaw 2026.3.8 换了一套全新的配置框架：

  • 旧框架：AGENT.md（一个文件搞定一切）
  • 新框架：SOUL.md（核心规则）+ IDENTITY.md（身份）+ USER.md（用户信息）+ AGENTS.md（调度规则）

我们辛辛苦苦从 .broken 目录恢复的 AGENT.md，新版系统根本不看它。而 AGENTS.md 虽然也恢复了，但 Gateway 启动时又用通用模板覆盖了。

教训 4： 系统升级可能改变配置文件架构。恢复旧文件前，先搞清楚新版本到底读哪些文件。旧文件存在 ≠ 被系统使用。

十、记忆恢复：将旧配置迁移到新框架

既然新框架读的是 SOUL.md / IDENTITY.md / USER.md，那就把 AGENT.md 的内容拆分写进去。

第 1 步：停止 Gateway

openclaw gateway stop

第 2 步：写入 SOUL.md（核心规则）

把 AGENT.md 中的硬性规则、工具使用规则、回答风格迁移过来：

cat > ~/.openclaw/workspace/SOUL.md << 'EOF'
# 小助手 — 核心规则

## 🔴 硬性规则（违反即失败）

### 1. 严禁编造任何金融数据
- 绝不允许凭记忆、推测或训练数据回答任何金融相关数字
- 包括但不限于：股票价格、指数点位、涨跌幅、成交量、市盈率
- 即使用户催促也绝不能跳过工具调用而直接编造数据
- 对话中的截图、转述数字都不能作为金融数据回答依据

### 2. 金融数据必须通过工具获取
- 股票/指数/行情 → TuShare Skill
- 市场新闻/舆情 → SearXNG Skill
- 网页内容 → Jina Reader Skill
- 工具失败 → 如实告知，绝不编造替代数据

### 3. 不要重复询问已配置好的信息
- TuShare Token 已在环境变量中，直接调用
- SearXNG 在 localhost:8080，直接调用
- 不确定就查 MEMORY.md，别问用户

### 4. 诚实优先
- 不知道就说不知道，不编造

## 🟢 工具使用
- TuShare Skill：股票代码、行情、K线、财务
- SearXNG Skill（localhost:8080）：搜索、查新闻
- Jina Reader Skill（r.jina.ai）：读网页
- ❌ 禁止 bocha-web-search（已弃用）

## 🟡 回答风格
- 简洁准确不废话
- 金融数据必须注明来源
- 非交易时间说明数据时间点
- 发现异常数据主动提醒

## 📝 记忆管理
- 重要信息先查 MEMORY.md
- 没有则追加记录
- 不要每次都问已告诉过的信息
EOF
echo "✅ SOUL.md 写入完成"

第 3 步：写入 IDENTITY.md（身份定义）

cat > ~/.openclaw/workspace/IDENTITY.md << 'EOF'
# <你的 Agent 名字> — 身份

- 名字：<你的 Agent 名字>
- emoji：🤖（选一个你喜欢的）
- 角色：运行在飞书上的 AI 助手，由 OpenClaw 驱动
- 性格：专业、简洁、诚实、有耐心
- 语言：中文（除非用户要求其他语言）
- 主力模型：<your-primary-model>（直连或通过 API 代理）
- 推送脚本模型：<your-coding-model>
- 图像识别：<your-vision-model>
EOF
echo "✅ IDENTITY.md 写入完成"

第 4 步：写入 USER.md（用户信息）

cat > ~/.openclaw/workspace/USER.md << 'EOF'
# 用户信息

## 基本信息
- 称呼：<你的称呼>
- 角色：<你的角色，例如：量化投资爱好者、技术运维>

## 环境
- 服务器：<你的云服务器>
- OpenClaw 版本：2026.3.8
- 飞书 Agent 接入（WebSocket 长连接）

## 偏好
- <你的偏好，例如：简洁专业、不要废话>
- <数据准确性要求>
- 每日推送：<自定义推送时间和内容>

## 历史教训（必读！）
# 记录 Agent 曾犯的错误，防止重蹈覆辙
1. ❌ 曾编造数据 → 必须通过工具获取真实数据
2. ❌ 曾反复询问已配置的信息 → 查 MEMORY.md，不要问用户
3. ❌ 曾使用错误的工具 → 指定正确的工具和优先级
EOF
echo "✅ USER.md 写入完成"

第 5 步：写入 AGENTS.md（调度规则）

将原来 212 行的调度规则重新写入（替换被覆盖的通用模板）。内容见本文档第三节「3.5 AGENTS.md」。

第 6 步：验证并重启

# 验证文件
for f in SOUL.md IDENTITY.md USER.md AGENTS.md MEMORY.md; do
    if [ -f ~/.openclaw/workspace/$f ]; then
        lines=$(wc -l < ~/.openclaw/workspace/$f)
        head -1 ~/.openclaw/workspace/$f | xargs -I{} echo "✅ $f ($lines行) → {}"
    else
        echo "❌ $f 不存在"
    fi
done

# 重启
openclaw gateway restart

验证结果

在飞书中测试：

你叫什么名字？TuShare token 配好了吗？

回答：

我叫小助手 🤖
TuShare Token 已配置好，在环境变量 TUSHARE_TOKEN 中，可以直接调用。需要查什么股票数据吗？

🎉 记忆恢复成功！ Agent 重新认识了自己。

教训 5： 升级后的框架迁移不是简单的文件复制。需要理解新框架的文件结构，把旧内容按新的分工拆分到对应文件中。AGENT.md 的内容需要拆成 SOUL.md（规则）+ IDENTITY.md（身份）+ USER.md（用户信息）三个文件。

十一、未完成：四个子 Agent 仍然缺失

记忆恢复后，检查四个子 Agent 的状态：

for agent in researcher coder writer trader; do
    if [ -f ~/.openclaw/agents/$agent/agent/AGENT.md ]; then
        echo "✅ $agent"
    else
        echo "❌ $agent 不存在"
    fi
done

❌ researcher 不存在
❌ coder 不存在
❌ writer 不存在
❌ trader 不存在

四个子 Agent（researcher 研究助手、coder 编程助手、writer 文档助手、trader 交易助手）的 AGENT.md 文件在 .broken 备份目录中也不存在，需要根据配置文档重建。这部分工作留待后续完成，不影响Agent 的日常对话功能，只是复杂任务的子 Agent 分派暂时不可用。

十二、新旧框架对照表

功能 旧框架（≤ 2026.2.x） 新框架（2026.3.8）
系统提示词 / 人格规则 AGENT.md（一个文件全包） SOUL.md（核心规则）
身份定义 AGENT.md 开头部分 IDENTITY.md（独立文件）
用户信息 MEMORY.md 中混合 USER.md（独立文件）
调度规则 AGENTS.md AGENTS.md（保持不变）
长期记忆 MEMORY.md MEMORY.md（保持不变）
首次运行引导 无 BOOTSTRAP.md（新增）
心跳配置 无 HEARTBEAT.md（新增）
工具笔记 无 TOOLS.md（新增）

十三、完整时间线

时间 事件 结果
14:00 执行 openclaw-restore.sh 备份恢复 ❌ 配置残缺，飞书断连
14:30 发现 .broken 目录有旧配置 ⚠️ 但 Gateway 运行中会覆盖
15:00 反复 cp 配置被覆盖，排查数小时 ❌ 浪费大量时间
16:00 发现必须先 stop Gateway ✅ 配置不再被覆盖
16:30 修复插件路径 + source 字段 ✅ Gateway 不再 crash loop
17:00 飞书重新连接成功 ✅ 但 Agent 完全失忆
17:10 从 .broken 恢复 AGENT.md/MEMORY.md ⚠️ 文件存在但 Agent 不认
17:15 发现新框架读 SOUL.md 而非 AGENT.md 💡 关键发现
17:25 将内容迁移到 SOUL.md/IDENTITY.md/USER.md ✅ Agent 恢复记忆
17:30 检查子 Agent ❌ 4 个子 Agent 全部缺失，待重建

十四、经验总结

操作铁律

  1. 改配置前必须先 stop Gateway —— 这是今天最痛的教训，绕了好几个小时
  2. 恢复后必须验证配置完整性 —— 不要假设备份是完整的
  3. 不要猜配置值 —— 看错误提示，看文档，用 openclaw doctor --fix
  4. 升级后先搞清新框架读哪些文件 —— 旧文件存在 ≠ 被使用
  5. 配置迁移不是文件复制 —— 需要理解新框架结构，按新分工拆分内容

备份铁律

  1. 不要依赖内置备份工具 —— 自己打包整个 ~/.openclaw/ 目录最可靠
  2. 备份前检查、恢复后验证 —— 两头都要卡
  3. 设置定时备份 + 旧备份自动清理 —— 养成习惯
  4. 备份时记录当前框架版本和文件清单 —— 恢复时才知道要还原哪些文件

OpenClaw 小知识

  • 内置插件路径：/usr/lib/node_modules/openclaw/extensions/
  • plugins.installs.*.source 合法值："npm"、"archive"、"path"（没有 "builtin"）
  • 飞书 WebSocket 长连接模式需要在飞书开发者后台设置「使用长连接接收事件/回调」
  • openclaw gateway install --force 可以自动清理部分无效配置条目

2026.3.8 新框架知识

  • 新版不再读取 AGENT.md，改为 SOUL.md + IDENTITY.md + USER.md
  • SOUL.md：核心人格规则（相当于旧 AGENT.md 的硬性规则部分）
  • IDENTITY.md：身份定义（名字、角色、emoji、模型信息）
  • USER.md：用户信息（主人资料、偏好、历史教训）
  • AGENTS.md：调度规则（与旧版相同，但 Gateway 启动可能覆盖为通用模板）
  • BOOTSTRAP.md、HEARTBEAT.md、TOOLS.md：新增的框架文件
  • 重要：Gateway 启动时会检测并可能重置新框架文件为模板，修改后需要在 Gateway 停止状态下进行

结语

一个"简单的备份操作"，最终变成了 5 个小时的排障之旅。但也正因为踩了这些坑，才真正理解了 OpenClaw 的配置管理机制，写出了更可靠的备份方案。

希望这篇文章能帮到正在用 OpenClaw + 飞书搭建 AI Agent 的朋友们。如果你也遇到了类似的问题，欢迎评论区交流。

记住：改配置前先 stop，备份要全盘，恢复要验证，升级要搞清新框架。

本文基于 OpenClaw 2026.3.8 版本，部署在云服务器（Linux）上，飞书 Agent 使用 WebSocket 长连接模式。

Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

生活风暴 - 点击防御大作战鸿蒙PC Electron框架完整开发指南

avatar AtomGit开源社区
cover

JavaScript高级④｜类（class）与面向对象，ES6现代写法

avatar AtomGit开源社区
cover

Java 集合进阶：ConcurrentHashMap、HashSet、LinkedHashMap、TreeMap 和 fail-fast 一篇讲清

avatar AtomGit开源社区