openclaw 2026.4.21 下微信通道首轮启动漏启问题排查实录与项目侧修复方案

一、问题背景

最近在 AnClaw 项目中接入 openclaw-weixin 微信通道时，遇到一个很隐蔽的问题：

• 应用启动后，微信插件看起来已经被发现；
• 但首轮启动阶段并没有真正把微信通道拉起来；
• 结果就是微信里给 AI 发消息，网关侧没有正常进入接收和回复链路；
• 等过一段时间后，又会莫名恢复正常。

这个问题在 openclaw 从 2026.3.13 升级到 2026.4.21 后开始明显出现，因此最开始很容易怀疑是：

1. 插件没有正确加载；
2. 插件 contract 不兼容；
3. gateway 启动时 WebSocket 断开重连导致时序错乱；
4. 微信 monitor 自己启动后异常退出。

但最后排查下来，真正根因并不在这些表层现象上。

---

二、问题现象

问题现象可以概括为两类：

1. 首轮启动时微信收不到消息，也不回复

应用刚启动时，其他插件已经在 gateway 启动过程中加载，但 openclaw-weixin 没有像预期那样进入正常工作态。

直观表现就是：

• 微信侧发送消息没有得到 AI 回复；
• gateway 启动日志里没有出现微信账号 runner 正常拉起后的完整链路；
• 但稍后又可能恢复。

2. 后续又会“自己好”

这个现象非常容易误导人，因为它会让人误以为：

• 插件本身其实没问题；
• 只是网络偶发抖动；
• 或者 monitor 崩了又自己恢复。

实际上，后续恢复正常并不是首轮启动成功，而是被后续兜底机制补拉起了。

---

三、第一阶段排查：先排除“插件根本没加载”

一开始先排查的是最直觉的方向：openclaw-weixin 有没有被正确发现和注册。

此前项目里确实遇到过老问题，例如：

• legacy channel entry 不符合新版本 bundled-channel-entry contract；
• 插件 manifest 存在，但启动时提示 unknown channel id；
• bundled channel entry ... missing bundled-channel-entry contract; skipping。

针对这类问题，项目已经在 scripts/package-resources.js 里做过兼容：

• 自动为老式 channel 插件生成 oneclaw-bundled-entry.mjs；
• 改写插件入口，适配 openclaw >= 2026.4.5 的 bundled channel contract。

所以这次首先确认的是：当前这轮故障不是“插件完全没被发现”。

进一步静态检查后发现：

• openclaw-weixin 的 manifest 仍然能被发现；
• oneclaw-bundled-entry.mjs 也确实存在；
• index.ts 的 register() 也会被触发；
• 日志里还会出现 setWeixinRuntime called。

乍一看，这几乎像是“插件已经加载成功”的铁证。

但这其实是后面排查中最大的误导点。

---

四、第二阶段排查：为什么 setWeixinRuntime called 不能证明插件已正常启动

继续往下读 openclaw-weixin 的 bundled shim 后，发现它并不是简单地“正式注册后再启动”。

oneclaw-bundled-entry.mjs 的逻辑大意如下：

let cachedChannelPlugin = null;

function captureChannelPlugin() {
  if (cachedChannelPlugin) return cachedChannelPlugin;

  const stubApi = {
    runtime: {},
    registrationMode: "probe",
    registerChannel({ plugin }) {
      cachedChannelPlugin = plugin;
    },
    registerTool() {},
    registerHttpRoute() {},
    registerAgentTool() {},
    registerHook() {},
    on() {},
  };

  normalized.register(stubApi);
  return cachedChannelPlugin;
}

也就是说，宿主在某些阶段会先用一个 probe 风格的 stubApi 去执行 legacy 插件的 register()，目的只是把 channel plugin 抓出来。

而 openclaw-weixin/index.ts 里又有这样一段逻辑：

register(api) {
  assertHostCompatibility(api.runtime?.version);

  if (api.runtime) {
    setWeixinRuntime(api.runtime);
  }

  api.registerChannel({ plugin: weixinPlugin });
}

于是问题就出现了：

• 只要 shim 用 stubApi 走了一次探测；
• api.runtime 哪怕只是一个空对象；
• setWeixinRuntime() 就会被调用；
• 日志里就会出现“runtime 已设置”的信息。

但这并不代表：

• 微信账号 runner 已经启动；
• startAccount() 已经执行；
• 微信 webhook / monitor 已经进入工作循环。

也就是说：

setWeixinRuntime called 只能证明插件探测路径走到了，不能证明首轮启动已经把微信通道真正拉起来了。

这一步确认之后，排查方向就从“插件根本没加载”切到了“插件被探测到了，但为什么没有进入首轮启动集合”。

---

五、第三阶段排查：首轮启动到底遍历的是谁

接下来继续看宿主的启动链，重点盯住 startChannels()。

关键点在于：startChannels() 并不是“拿配置里的 channel id 逐个启动”，而是先拿一个“已加载 channel 插件列表”，再逐个启动。

核心逻辑可以概括为：

const startChannels = async () => {
  const pending = [...listChannelPlugins()];
  for (const plugin of pending) {
    await startChannel(plugin.id);
  }
};

而 listChannelPlugins() 实际上走的是 loaded registry：

function listChannelPlugins() {
  return listLoadedChannelPlugins();
}

但另外一条链路，例如 health-monitor 或手动按 channel id 获取插件时，走的是：

function getChannelPlugin(id) {
  return getLoadedChannelPlugin(id) ?? getBundledChannelPlugin(id);
}

这两个接口有一个决定性的区别：

• listChannelPlugins() 只看 loaded plugins；
• getChannelPlugin(id) 则带 bundled fallback。

这就解释了一个关键现象：

• 首轮启动阶段，openclaw-weixin 如果没有进入 loaded registry，就一定不会被 startChannels() 启动；
• 但后续 health-monitor 按 id 补拉起时，即使它没进 loaded registry，也仍然可能通过 bundled fallback 找到并启动。

这一步让问题第一次真正闭环：

首轮漏启和后续恢复正常，并不是同一套启动路径。

---

六、第四阶段排查：为什么 openclaw-weixin 没进 startupPluginIds

到这里，问题已经收敛成：

为什么 openclaw-weixin 在首轮启动时没有进入宿主的 startup plugin 规划集合？

继续往前追 prepareGatewayPluginBootstrap()、resolveGatewayStartupPluginIds() 和 resolveConfiguredChannelPluginIds() 之后，发现 openclaw 在决定“一个 channel 算不算已配置”时，依赖的是 config-presence 这层逻辑。

而这里有一条非常关键的判定：

function hasMeaningfulChannelConfig(value) {
  if (!isRecord(value)) return false;
  return Object.keys(value).some((key) => key !== "enabled");
}

换句话说：

• channels.xxx = { enabled: true } 不算“有意义的 channel 配置”；
• 必须有 enabled 之外的字段，宿主才认为这个 channel 是 configured channel；
• 只有 configured channel，才会进入 startupPluginIds。

这时再回头看当前用户配置，就发现微信恰好踩中了这个规则：

{
  "channels": {
    "openclaw-weixin": {
      "enabled": true
    }
  }
}

微信的真正凭据并不在 channels.openclaw-weixin 里，而是在它自己的 sidecar 状态文件中：

• ~/.openclaw/openclaw-weixin/accounts.json
• ~/.openclaw/openclaw-weixin/accounts/<accountId>.json

也就是说：

• 从微信插件自己的视角看，账号和 token 都已经准备好了；
• 但从宿主 startup planner 的视角看，这个 channel 只有一个 enabled: true；
• 所以它被判定为“未配置”；
• 最终直接被排除在首轮 startup plugin 集合之外。

这就是根因。

---

七、为什么后续 health-monitor 又能把它拉起来

现在再回头看“为什么后面又好了”，逻辑就完全顺了。

因为后续链路走的不是 listLoadedChannelPlugins()，而是按 id 查插件的 fallback 路径：

• 首轮启动：依赖 loaded registry，微信没进去，所以漏掉；
• 后续兜底：按 openclaw-weixin 这个 id 去找插件，loaded 没有还能走 bundled fallback；
• 所以后面还能被 health-monitor 补拉起。

这也是为什么现象会表现为：

1. 启动时微信不工作；
2. 稍后又恢复正常；
3. 让人误以为只是网络或 monitor 自己重启。

实际上，真正的问题是：

首轮 startup planner 从一开始就没把微信当作“应启动的已配置通道”。

---

八、为什么飞书、企微、QQ 没有同类问题

定位出根因之后，我又顺手检查了飞书、企微、QQ 这些 channel，看看它们会不会也踩中同样的坑。

结论是：目前它们没有。

原因很简单，这几个 channel 的设置保存逻辑都会把关键凭据直接写进 openclaw.json 的 channels.* 下。

例如：

1. 飞书

飞书保存时会把这些字段写进 config.channels.feishu：

• appId
• appSecret
• dmPolicy
• groupPolicy
• allowFrom
• groupAllowFrom

所以它不是只有一个 enabled: true。

2. 企微

企微会把这些字段写进 config.channels.wecom：

• botId
• secret
• dmPolicy
• groupPolicy
• allowFrom
• groupAllowFrom

3. QQ Bot

QQ 会把这些字段写进 config.channels.qqbot：

• appId
• clientSecret
• markdownSupport
• allowFrom

因此这几个 channel 在宿主的 hasMeaningfulChannelConfig() 规则下，本来就会被识别为 configured channel，不会出现微信这种“只有 enabled，没有其他字段”的漏启问题。

---

九、为什么不直接改 openclaw 内部源码

定位出根因之后，一个最直接的思路是：去改 openclaw 内部的 config-presence 判定逻辑。

比如把：

Object.keys(value).some((key) => key !== "enabled")

改成：

Object.keys(value).length > 0

或者把 enabled: true 也视作 meaningful config。

但这个方案有一个很现实的问题：

• 当前项目每次打包都会重新下载 openclaw；
• 直接改下载产物，下一次 package:resources 就会被覆盖；
• 这种修法只能治标，不能治本。

因此最后选择的是更稳的方案：

不去改每次重新下载的 openclaw 内部源码，而是在当前项目侧，在启动 gateway 之前，把微信配置补齐到“宿主可以识别”的状态。

---

十、最终解决方案：在项目侧启动前补齐微信 startup config

最终采用的是“当前项目侧修复方案”的第一种做法：

方案核心

在当前项目启动 gateway 之前，检查：

1. 微信 channel 是否已启用；
2. 微信 sidecar 账号索引是否存在；
3. 是否至少有一个账号文件带有效 token；

如果以上条件都满足，则自动把下面这个字段补进 openclaw.json：

{
  "channels": {
    "openclaw-weixin": {
      "enabled": true,
      "channelConfigUpdatedAt": "2026-04-24T12:34:56.789Z"
    }
  }
}

这样一来，宿主的 hasMeaningfulChannelConfig() 就会返回 true，微信通道就会被识别为 configured channel，进入首轮启动集合。

为什么选择 channelConfigUpdatedAt

这里没有随便编一个字段，而是复用了微信插件自己已经在用的字段：

• 语义上合理；
• 兼容性更好；
• 比人为发明一个“占位字段”更稳。

---

十一、项目中的实际改动

1. 在 src/weixin-config.ts 增加启动前补齐逻辑

新增 ensureWeixinStartupConfig()：

function hasUsableWeixinToken(accountId: string): boolean {
  const accountPath = path.join(resolveAccountsDir(), `${accountId}.json`);
  try {
    if (!fs.existsSync(accountPath)) return false;
    const parsed = JSON.parse(fs.readFileSync(accountPath, "utf-8"));
    return typeof parsed?.token === "string" && parsed.token.trim() !== "";
  } catch {
    return false;
  }
}

export function ensureWeixinStartupConfig(): boolean {
  const config = readUserConfig();
  const enabled = extractWeixinConfig(config).enabled;
  if (!enabled) return false;

  const hasCredential = listWeixinAccountIds().some((accountId) => hasUsableWeixinToken(accountId));
  if (!hasCredential) return false;

  config.channels ??= {};
  const existingChannel =
    typeof config.channels[WEIXIN_CHANNEL_ID] === "object" &&
    config.channels[WEIXIN_CHANNEL_ID] !== null
      ? config.channels[WEIXIN_CHANNEL_ID]
      : {};

  if (
    existingChannel.enabled === true &&
    typeof existingChannel.channelConfigUpdatedAt === "string" &&
    existingChannel.channelConfigUpdatedAt.trim() !== ""
  ) {
    return false;
  }

  config.channels[WEIXIN_CHANNEL_ID] = {
    ...existingChannel,
    enabled: true,
    channelConfigUpdatedAt: new Date().toISOString(),
  };
  writeUserConfig(config);
  return true;
}

这个实现有几个设计点：

• 只有“已启用且有有效 token”才补；
• 没登录的用户不会被误判成应启动；
• 已经有 channelConfigUpdatedAt 时不会重复写；
• 修复逻辑完全在当前项目中，不依赖 openclaw 内部文件稳定性。

2. 在 src/main.ts 的 gateway 启动前调用

在 ensureGatewayRunning() 里增加：

try {
  if (ensureWeixinStartupConfig()) {
    log.info("[startup] synced openclaw-weixin channelConfigUpdatedAt for gateway startup");
  }
} catch (err: any) {
  log.error(`[startup] failed to sync weixin startup config: ${err?.message ?? err}`);
}

这样可以保证：

• 每次应用启动 gateway 之前都会做一次补齐；
• 即使后面重新打包、重新下载 openclaw，这个修复也仍然有效。

---

十二、验证结果

这次修复后，验证重点主要看两类结果。

1. 配置层验证

应用启动后，检查 ~/.openclaw/openclaw.json：

• 原来微信可能只有：

"openclaw-weixin": {
  "enabled": true
}

• 现在会被补成：

"openclaw-weixin": {
  "enabled": true,
  "channelConfigUpdatedAt": "..."
}

2. 启动链路验证

修复生效后，预期行为应该从：

• 首轮启动没有真正拉起微信；
• 后续靠 health-monitor 补拉起；

变成：

• 首轮 gateway 启动阶段就把微信纳入 startup 集合；
• 直接进入微信通道正常启动链路。

---

十三、这次排查中最容易走偏的几个点

这次问题之所以难查，主要有三个误导点。

1. setWeixinRuntime called 太像“已经启动成功”

实际上它只是 shim probe 阶段的副作用，不等于账号 runner 已经启动。

2. 后续会恢复正常，容易让人误判为偶发网络问题

实际上后续恢复并不是首轮启动成功，而是 health-monitor 走 bundled fallback 把它补拉起来了。

3. 插件确实能被发现，但不等于会进入首轮 startup

“可发现”与“已进入 loaded startup registry”是两回事，这也是这次问题最核心的认知点。

---

十四、结论

这次微信通道问题，表面上看像是：

• 插件没加载；
• gateway 启动时断开重连；
• monitor 自己崩了；

但真正的根因其实是：

openclaw-weixin 的有效凭据保存在 sidecar 状态文件里，而不是 channels.openclaw-weixin 下；
宿主在启动规划时又只把“含有 enabled 之外字段的 channel 配置”视为 configured channel；
因此微信通道在首轮 startup planner 中被漏掉，后续只能靠 health-monitor 再补拉起。

最终的稳妥修法不是去手改 openclaw 下载产物，而是：

在当前项目侧，在 gateway 启动前检查微信 sidecar 凭据，并自动补齐 channelConfigUpdatedAt，让宿主把微信识别为 configured channel。

这是一个典型的“插件真实状态与宿主配置判定规则不一致”导致的启动时序问题。

如果你也在做类似的 Electron 壳层、插件式网关、或 sidecar 凭据存储的项目，这个坑非常值得提前规避。

---

十五、后记

补充检查后，飞书、企微、QQ 这些 channel 没有同类问题，因为它们的关键凭据本来就直接写在 openclaw.json 的 channels.* 下，宿主能天然识别为 configured channel。

因此这次真正需要修的只有微信。

---

如果你准备把这篇文章发到 CSDN，建议标题也可以改成下面这几个版本：

1. openclaw 2026.4.21 微信通道启动后不回复？一次从现象到根因的完整排查
2. openclaw-weixin 首轮启动漏启问题排查与修复实录
3. 为什么微信插件明明加载了，却在 openclaw 启动时不工作？