OpenClaw 踩坑记:一个命名引发的血案

有时候，最复杂的问题，答案却最简单。

问题起因

今天决定把 OpenClaw 的飞书插件从社区版 feishu 迁移到官方版 openclaw-lark。

为什么要折腾这次迁移？

社区版插件虽然能跑，但有几个痛点：

基于这些原因，决定迁移到官方插件。

配置多账号飞书通道时，沿用了agent之前的命名：

• main - 主账号

• default - 个人助理账号

• family - 家庭账号

• fullstack-dev - 开发助手账号

配置完成后，诡异的事情发生了。

问题现象

4个飞书机器人，根据官方教程进行推进，没有私自改任何配置，总结来说，就是4个agent的配置都是一模一样的。

但是

default这个账号异常诡异，如果我禁用原feishu插件，其他三个agent的飞书channel正常，但是default这个账号发送消息没有反应，飞书的开发者后台长链接测试失败。如果我不禁用原feishu插件，4个agent的飞书channel都正常，但是都是走原来的feishu插件，不实行的openclaw-lark插件。

解决过程：走了无数弯路

第一站：检查飞书开放平台配置

对比了正常工作的 main agent和default agent应用的配置：

• 回调 URL ✅ 一致

• 验证 Token ✅ 一致

• 加密 Key ✅ 一致

• 订阅事件 ✅ 一致

• 应用版本 ✅ 已发布

结论：飞书侧配置没问题。

第二站：检查 OpenClaw 配置文件

用 openclaw config get 逐一对比 4 个账号的配置：

openclaw config get channels.feishu.accounts.mainopenclaw config get channels.feishu.accounts.defaultopenclaw config get channels.feishu.accounts.familyopenclaw config get channels.feishu.accounts.fullstack-dev

结论：4 个账号配置完全一致，没有任何差异。

第三站：检查 Keychain 中的 OAuth token

检查 macOS Keychain 中存储的飞书用户授权 token：

security find-generic-password -s "openclaw-feishu-uat" -a "cli_xxx:ou_xxx" -w

发现 default 账号对应的应用没有 token 记录。

但问题是：其他账号也没有，它们却能正常工作。

第四站：各种尝试

• 清理旧插件残留配置

• 重新创建飞书应用

• 重新配置事件订阅

• 检查 allowFrom 白名单

• 检查 bindings 绑定关系

• ...

全部无效。

最终解决方案

另一位 AI 助手（Gemini）指出：default 是 OpenClaw 的保留标识符。

问题根因

在 OpenClaw 内部，default 有特殊含义：

• DEFAULT_ACCOUNT_ID - 插件 SDK 中的默认账号常量

• default agent - 可能有特殊的默认路由逻辑

• openclaw-lark 插件内部对 default 有硬编码处理

当使用 default 作为 accountId/agentId 时，与内部保留标识符冲突，导致：

• 账号配置解析错误

• 消息路由混乱

• 事件处理异常

修复步骤

1. 修改配置文件

# 修改 agentIdopenclaw config set agents.list.default.id cheng# 修改 accountId（飞书账号配置）openclaw config set channels.feishu.accounts.cheng.appId cli_xxxxxxxxxxxxxxxxopenclaw config set channels.feishu.accounts.cheng.appSecret xxxxxxxxxxxxxxxxxx# 修改 bindingsopenclaw config set bindings[].agentId cheng  # 需要手动编辑 JSON

2. 修改飞书开放平台配置

• 更新回调 URL（如有变化）

• 重新测试长连接

3. 重启Gateway

openclaw gateway restart

4. 验证

• 飞书开放平台长连接测试 ✅ 通过

• 飞书中发消息 ✅ 收到回复

经验教训

1. 避免使用保留标识符

❌ 不要使用：

• default - 系统默认标识符

• main - 可能与主 agent 冲突

• 其他可能的保留字：system, admin, root 等

✅ 推荐使用：

• 自定义名称：cheng, personal, assistant, work

• 有意义的名称：hr-bot, dev-helper, family-assistant

2. 排查顺序很重要

下次遇到类似问题，应该按这个顺序检查：

1. 标识符是否与保留字冲突 ← 今天的最重要教训

2. 飞书开放平台配置（事件订阅、回调 URL）

3. OpenClaw 配置一致性

4. 插件冲突

5. OAuth token 状态

3. 多账号配置的命名规范

建议建立统一的命名规范：

accounts:  personal:    # 个人助理  work:        # 工作助手  family:      # 家庭助手  dev:         # 开发助手  # 避免使用 default/main 等保留字

4. 官方插件的兼容性

从社区版插件迁移到官方版插件时：

• 注意配置结构的差异

• 注意保留标识符的变化

• 先在测试环境验证

后记

这个问题表面看是个命名问题，本质上还是不懂软件工程某些「潜规则」导致的，如果没有好用的AI，我可能一直解决不了了。但是，如果是一个多年经验的工程师，可能逐渐排除原因后很快就能解决，或者从一开始给agent命名的时候就不会用这个软件工程中极其敏感的名字来命名。

AI是很强大，但是当前数字世界中绝大多数的东西还是人类创造的。

过往文章：

AI怎么学习UI设计

做一个B端系统，如何高效地与AI人机协作