【OpenClaw 自定义 Skill】agent-manager 重大更新:支持新版绑定架构、迁移工具与完整测试

🤖 agent-manager 技能迎来架构级升级！新增绑定迁移工具、配置管理工具库和单元测试体系，让多 Agent 管理更加稳健可靠。

⏱️ 阅读时间：约 6 分钟

💡 前置要求：已了解 agent-manager 基本概念，正在使用或准备使用多 Agent + 飞书绑定功能

✨ 更新了什么？

随着 OpenClaw 在 v2026.5 版本引入新的配置结构，agent-manager 技能也进行了全面升级。这次更新主要集中在 绑定架构重构 与 代码质量提升 两个方面：

核心改进：

• 支持 OpenClaw 新版顶层 bindings 结构
• 原子化配置文件写入，防止文件损坏
• 验证脚本支持严格模式，可集成 CI 流程
• 迁移脚本支持 dry-run 预览，安全可逆
• 管理脚本代码减少约 40%

1️⃣ 绑定架构升级：从遗留结构到顶层 Bindings

变化背景

旧版 OpenClaw 的飞书绑定配置存放在 channels.feishu.bindings 中，是一个简单的键值对结构：

{
  "channels": {
    "feishu": {
      "bindings": {
        "sales_bot": "sales-assistant"
      }
    }
  }
}

新版 OpenClaw 将 bindings 提升到配置文件的顶层，并支持更丰富的匹配规则：

{
  "bindings": [
    {
      "agentId": "sales-assistant",
      "match": {
        "channel": "feishu",
        "accountId": "sales_bot"
      }
    }
  ]
}

这一改变让绑定关系更加清晰、可扩展，也为将来支持更多通道（Telegram、Discord 等）提供了统一基础。

迁移工具

为了让老用户平滑过渡，新增了 migrate_feishu_bindings.py 迁移脚本：

# 先预览迁移内容（dry-run，不会写文件）
python3 scripts/migrate_feishu_bindings.py --config ~/.openclaw/openclaw.json

# 确认无误后执行迁移（并删除旧字段）
python3 scripts/migrate_feishu_bindings.py --config ~/.openclaw/openclaw.json --write --remove-legacy

迁移脚本的工作方式：

• 自动发现：读取 channels.feishu.bindings 中的旧绑定关系
• 自动转换：将键值对转换为标准顶层 bindings 数组格式
• 智能去重：检测已有绑定，避免重复添加
• 可选清理：支持迁移后自动删除旧字段

2️⃣ 新增工具库：openclaw_config.py

这是本次重构的基础模块，将之前散落在各脚本中的 openclaw.json 操作集中管理，并引入了更安全的写入机制。

三大亮点：

使用示例：

from openclaw_config import load_openclaw_config, ensure_binding, save_openclaw_config

config = load_openclaw_config()
ensure_binding(config, agent_id="my-agent", channel="feishu", account_id="my_bot")
save_openclaw_config(config)

得益于此，manage_agent.py 中的配置操作从手动打开/序列化/写入，简化为两行函数调用，代码量减少了约 40%。

3️⃣ 绑定验证脚本升级

verify_bindings.py 进行了重写，新增了多项实用能力：

• 🔍 支持顶层 bindings 读取 — 优先读取新版结构，兼容旧版遗留格式
• 🔍 严格模式（--strict） — 发现问题时返回非零退出码，可集成到 CI 流水线
• 🔍 缺失项检测 — 自动发现 account 不存在、App ID 缺失等问题
• 🔍 汇总统计 — 输出绑定总数和问题数量

# 基础验证
python3 scripts/verify_bindings.py

# 严格模式（CI 中使用）
python3 scripts/verify_bindings.py --config ~/.openclaw/openclaw.json --strict

输出示例：

🔍 Current Feishu Bot Bindings:
--------------------------------------------------
Account: sales_bot
  └─ App ID: cli_xxxxxx
  └─ Agent:  sales-assistant

Account: data_bot
  └─ App ID: ❌ Missing
  └─ Agent:  data-analyst

Summary: 2 binding(s), 1 issue(s)

4️⃣ 单元测试体系

新增 test_verify_bindings.py（133 行），使用 Python 内置 unittest 框架，覆盖了：

• ✅ 顶层 bindings 读取
• ✅ 旧版遗留结构降级读取
• ✅ 缺失 account 时的错误报告
• ✅ 严格模式退出码验证
• ✅ 测试自动创建临时文件，不污染用户环境

对于 OpenClaw Skill 开发者来说，这是一个很好的参考范例—— Skill 脚本也应当有完善的测试保障，而不是跑一次算一次。

5️⃣ 国际化文档

新增 README.en.md，提供英文版使用指南，方便国际用户快速上手。

• 与中文 README 保持同步
• 后续将持续维护中英双语文档

📖 现有用户升级指南

如果你已经在使用 agent-manager，建议按以下步骤更新：

# 1. 更新技能代码
cd ~/.openclaw/workspace/skills/agent-manager
git pull origin main

# 2. 迁移绑定结构
python3 scripts/migrate_feishu_bindings.py --config ~/.openclaw/openclaw.json --write --remove-legacy

# 3. 验证绑定状态
python3 scripts/verify_bindings.py --strict

# 4. 重启网关
openclaw gateway restart

💡 提示： 迁移脚本默认使用 dry-run 模式，不会修改你的配置文件。加上 --write 后才会实际写入。

✅ 总结

这次 agent-manager 的更新是一次深度的架构升级，而非简单的功能堆叠：

• 顺应平台演进 — 支持 OpenClaw 新版配置结构，确保技能与平台同步
• 平滑迁移体验 — 提供迁移工具，老用户无需手动改配置
• 代码质量提升 — 单元测试、原子写入、代码复用让脚本更健壮
• 国际化起步 — 英文文档降低使用门槛

如果你之前还没有体验过 agent-manager，可以查看之前的介绍文章了解更多——一行命令创建一个专属 Agent，让多 Agent 管理变得如此简单。

📦 仓库地址：https://gitee.com/wowofighting/agent-manager.git