1. 项目概述

如果你正在寻找一个能深度集成到企业微信（WeCom）里，功能远超官方基础版的AI助手插件，那么 @sunnoy/wecom 就是你需要的那个“瑞士军刀”。这个插件基于OpenClaw运行时，它不是一个简单的消息转发器，而是一个为企业级场景量身打造的、具备多账号管理、动态会话隔离、增强主动推送和精细化安全控制能力的“超级通道”。简单说，它让OpenClaw这个强大的AI Agent平台，在企业微信里变得像原生应用一样好用、可控且功能强大。

我最初接触这个项目，是因为团队需要一个能同时服务内部多个部门（如技术支持、产品、运营）的AI助手，每个部门的需求和权限都不同。官方插件只解决了“从无到有”的连接问题，但在实际部署中，我们遇到了账号混乱、会话串扰、主动通知能力弱、文件发送不便等一系列痛点。 @sunnoy/wecom 插件正是为了解决这些生产环境中的实际问题而生。它基于官方插件的WebSocket长连接骨架，但在此基础上，增加了十多项关键的企业级特性，比如你可以为不同部门配置独立的机器人账号并统一管理，AI助手能为每个用户或群聊自动创建独立的工作空间，还能通过自建应用主动给特定部门或标签群发消息和文件。

接下来，我会带你深入拆解这个插件的核心设计、详细配置和实战技巧。无论你是想为团队部署一个智能客服，还是构建一个集成多种企业工具的内部助手，这篇文章都能提供从零到一的落地指南和避坑经验。我们将从最核心的“为什么需要这些增强特性”开始，逐步深入到多账号配置、动态Agent路由、消息投递策略等高级功能，并分享我在部署和调试过程中积累的一手经验。

2. 核心设计思路与架构解析

2.1 从官方插件到企业级增强：解决了哪些痛点？

要理解 @sunnoy/wecom 的价值，首先要明白官方 @wecom/wecom-openclaw-plugin 的定位。官方插件提供了一个最基础的桥梁：通过WebSocket长连接，将企业微信AI机器人的消息转发给OpenClaw，并将OpenClaw的回复流式地传回企业微信。这实现了最核心的“一问一答”功能。

然而，在企业真实使用场景中，这种基础模式很快会遇到瓶颈。 第一个痛点是账号与隔离 。一个公司往往有多个团队需要使用AI助手，比如技术部用它来查询文档和排错，市场部用它来生成文案。如果共用同一个机器人，所有对话历史、文件上传和工作区都会混在一起，导致上下文混乱，且无法为不同团队设置不同的行为策略（比如技术部允许执行 /debug 命令，市场部则不行）。官方插件不支持多账号，你只能部署多个独立的OpenClaw实例，运维成本陡增。

第二个痛点是会话与上下文的粒度 。官方插件通常会将所有私聊消息路由到同一个默认Agent。这意味着用户A和用户B的对话会相互干扰，用户A上传的文件，在用户B的会话中也可能被提及，这显然不符合隐私和上下文隔离的要求。我们需要一种机制，能自动为每个用户甚至每个群聊创建独立的AI Agent实例。

第三个痛点是消息能力的局限性 。企业微信官方AI机器人的WebSocket接口主要支持文本和图片的 被动回复 。如果你想主动向一个群发送通知、向整个部门广播消息、或者发送一个PDF报告，WebSocket通道就无能为力了。虽然企业微信提供了“自建应用”和“群机器人Webhook”两种主动发送消息的API，但官方插件并未集成，需要开发者自己写代码调用，非常繁琐。

第四个痛点是运维与管控的缺失 。如何控制哪些用户可以使用？哪些命令可以被执行？如何感知机器人是否被挤下线？如何防止短时间内消息发送过量触发企业微信的频控？这些生产环境必需的管控和监控能力，在基础插件中都是空白。

@sunnoy/wecom 插件正是针对上述每一个痛点，进行了系统性的增强。它采用了一种“分层增强”的架构思想：底层依然依赖最稳定的官方WebSocket长连接作为核心消息通道；在此之上，构建了多账号管理、动态Agent路由层；再往上，集成了自建应用API和Webhook作为主动消息能力的补充；最后，包裹了一层全面的安全、配额和运维管控策略。这种设计保证了核心通信的稳定性，同时极大地扩展了应用边界。

2.2 核心架构与数据流

该插件的架构可以清晰地分为四个层次： 连接层、路由层、能力层和管控层 。

连接层 是基石，负责与企业微信服务器建立并维护WebSocket长连接。这是消息进出的主通道，所有用户发送的文本、图片、文件等消息都通过这个连接实时推送到插件。插件也通过这个连接，将AI思考过程（ <think> ）和最终回复流式地推回给用户。这一层直接复用并优化了官方SDK ( @wecom/aibot-node-sdk ) 的连接管理、重连和心跳机制。

路由层 是大脑，负责决定一条消息该由谁来处理，以及处理结果该发回哪里。这是“动态Agent”功能的核心。当一条私聊消息抵达时，路由层会根据发送者UserID，动态生成一个唯一的Agent ID（例如 wecom-dm-zhangsan ）。OpenClaw会为这个ID创建（或复用）一个独立的Agent实例，拥有完全独立的工作区、记忆和上下文。群聊消息同理，会路由到如 wecom-group-chat123 这样的Agent。多账号模式下，还会加上账号前缀（如 wecom-support-dm-zhangsan ），实现跨账号的完全隔离。这一层确保了会话的纯净性和数据的安全性。

能力层 是四肢，扩展了消息的发送和接收能力。它包含三个子模块：

1. WebSocket通道 ：处理所有被动回复和简单的主动文本消息。
2. 自建应用API通道 ：这是功能最强大的通道。当需要主动发送消息、发送图片/文件、或按部门/标签群发时，插件会使用配置好的自建应用凭证，调用企业微信官方API。这个通道也是WebSocket断连后，补发“未送达回复”的后备方案。
3. Webhook通道 ：这是一个轻量级的群通知通道。配置好后，可以通过简单的 webhook:ops 目标，快速向特定的群机器人发送Markdown、图片或文件，常用于运维报警、日报推送等场景。

管控层 是规则，贯穿于上述所有层次。它定义了：

• 准入策略 ：谁可以私聊机器人 ( dmPolicy )，哪些群可以触发机器人 ( groupPolicy )。
• 命令白名单 ：普通用户只能执行哪些斜杠命令 ( /help , /new 等)，管理员 ( adminUsers ) 可以绕过此限制。
• 配额感知 ：内部追踪每个会话在最近24小时内的被动回复次数和主动发送次数，并在接近企业微信限制时发出警告，帮助管理员提前干预，避免触发频控。
• 媒体文件安全 ：严格定义AI回复中可以引用的本地文件路径范围 ( mediaLocalRoots )，防止任意文件读取。

整个数据流的典型路径如下：用户在企业微信发送消息 -> 企业微信服务器通过WS推送到插件 -> 路由层计算目标Agent ID -> 消息被送入对应Agent处理 -> AI生成回复（可能包含 MEDIA: 指令） -> 管控层进行安全校验 -> 能力层选择最佳通道（WS/Agent API/Webhook）将文本和媒体文件发送回用户。

实操心得：理解“通道选择”逻辑 消息如何发送出去，是新手最容易困惑的点。记住这个优先级： 对于被动回复，永远优先使用WebSocket，因为它支持流式输出，体验最好 。只有当回复中包含WS不支持的媒体类型（如文件），或WS发送失败时，才会尝试降级到Agent API。 对于你主动触发的通知或消息，则需要明确指定目标 ： webhook:name 走Webhook； party:2 或 tag:Developers 走Agent API；普通的 wecom:userid 会先尝试WS，失败再转Agent API。在设计工作流时，要根据消息类型和优先级，选择合适的发送目标。

3. 详细配置解析与实操要点

3.1 基础配置：从零连接一个机器人

安装插件后，所有配置都在OpenClaw的全局配置文件 ~/.openclaw/openclaw.json 的 channels.wecom 节点下。我们从一个最简可用的配置开始。

首先，你需要在企业微信后台创建一个 AI机器人 ，并选择 长连接模式 。这个步骤至关重要，因为2.0版本后插件已完全转向长连接，不再支持旧的HTTP回调模式。创建成功后，你会获得两个关键凭证： BotId 和 Secret 。把它们填入以下配置：

{
  "plugins": {
    "entries": {
      "wecom": {
        "enabled": true
      }
    }
  },
  "channels": {
    "wecom": {
      "enabled": true,
      "botId": "aib_xxxxxxxxxxxxxxxx", // 替换为你的BotId
      "secret": "xxxxxxxxxxxxxxxx", // 替换为你的Secret
      "welcomeMessage": "你好，我是AI助手，请问有什么可以帮您？",
      "sendThinkingMessage": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "groupChat": {
        "enabled": true,
        "requireMention": true
      }
    }
  }
}

配置项解读：

• botId & secret : 机器人长连接凭证，是插件与企业微信建立WS连接的钥匙。
• welcomeMessage : 用户首次进入私聊会话时收到的欢迎语。留空则使用Agent默认的自我介绍。
• sendThinkingMessage : 设置为 true 时，AI在思考过程中会先发送一个“思考中...”的占位符 ( <think></think> )，提升用户体验。建议开启。
• dmPolicy : 私聊准入策略。 pairing 是推荐的安全默认值，新用户需要管理员批准。
• groupPolicy & groupChat : 定义了群聊行为。 open 允许所有群触发； requireMention: true 要求群成员必须@机器人它才会响应，避免在群内刷屏。

保存配置后，重启OpenClaw Gateway服务： openclaw gateway restart 。如果一切正常，在日志中你应该能看到类似 [WeCom] WebSocket connected for bot: aib_xxx 的连接成功信息。此时，用户就可以在企业微信中找到这个机器人并开始对话了（如果使用 pairing 模式，则需要先完成配对）。

3.2 安全与准入策略深度配置

安全是企业IM集成的重中之重。插件提供了多层细粒度的控制。

私聊策略 ( dmPolicy ) 详解：

• pairing (配对模式)：这是默认也是最安全的模式。当企业内一个新用户首次私聊机器人时，他会收到一个6位数的配对码，同时该配对码会输出到OpenClaw的服务日志中。 管理员需要在服务器上执行命令 openclaw pairing approve wecom <配对码> 来批准该用户 。批准后，该用户才能正常使用。这有效防止了机器人被无关人员骚扰。
• allowlist (白名单模式)：只有配置在 allowFrom 数组中的UserID可以私聊机器人。适合小范围、已知用户的场景。配置示例： "allowFrom": ["zhangsan", "lisi"] 。
• open (开放模式)：任何在企业微信中能看到并私聊此机器人的成员，都可以直接开始对话。适用于内部全员使用的助手。
• disabled (禁用模式)：完全关闭私聊功能。

群聊策略精细化控制： 除了全局的 groupPolicy ，你还可以针对单个群进行更精细的控制。

{
  "channels": {
    "wecom": {
      // ... 其他基础配置 ...
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["wr1234567890"], // 只允许这个群触发
      "groups": {
        "wr1234567890": { // 针对这个群ID进行特殊配置
          "allowFrom": ["zhangsan", "wangwu"] // 在这个群里，只允许张三和王五触发机器人
        },
        "wr0987654321": {
          "allowFrom": ["lisi"] // 在另一个群里，只允许李四触发
        }
      }
    }
  }
}

这个配置实现了：全局只允许 wr1234567890 这个群触发机器人。并且在该群内，又进一步限制只有张三和王五两位成员@机器人才会得到响应。李四在第一个群里@机器人是无效的，但他在第二个专属群 wr0987654321 里则可以触发。这种配置非常适合跨部门项目群，只允许关键负责人与AI交互。

命令白名单 ( commands )： 为了防止用户误操作或执行危险命令，可以限制普通用户只能使用部分预设命令。

{
  "channels": {
    "wecom": {
      // ... 其他配置 ...
      "commands": {
        "enabled": true,
        "allowlist": ["/new", "/compact", "/help", "/status"] // 普通用户只能使用这4个命令
      },
      "adminUsers": ["zhangsan"] // 用户zhangsan是管理员，可以执行任何命令
    }
  }
}

当普通用户尝试执行 /system 或 /debug 等不在白名单中的命令时，机器人会礼貌地拒绝。管理员则不受此限制。

注意事项：获取正确的UserID和ChatID 上述配置中的 zhangsan 、 wr1234567890 等ID需要替换为真实值。获取方式有几种：1. 让用户私聊机器人，插件的日志会打印出其UserID。2. 在群中让机器人发送一条消息，日志中会包含该群的ChatID。3. 通过企业微信管理后台或API查询。确保使用正确的ID是配置生效的前提。

3.3 动态Agent与工作区模板配置

动态Agent是隔离和个性化的核心。默认情况下，插件会自动为每个私聊用户和每个群聊创建独立的Agent。

{
  "channels": {
    "wecom": {
      // ... 其他配置 ...
      "dynamicAgents": {
        "enabled": true, // 启用动态Agent
        "adminBypass": false // 管理员消息也走动态Agent（设为true则管理员消息路由到默认Agent）
      },
      "dm": {
        "createAgentOnFirstMessage": true // 私聊首条消息即创建独立Agent
      },
      "workspaceTemplate": "/path/to/your/template" // 工作区模板目录
    }
  }
}

工作区模板 ( workspaceTemplate ) 是一个极其有用的功能 。你可以创建一个目录，里面放置一些引导文件，例如：

• AGENTS.md : 定义该Agent可以调用的子智能体或工具。
• CLAUDE.md : 设定Claude模型的行为指令和人格。
• TOOLS.md : 说明可用的技能（Skills）。
• IDENTITY.md : 定义AI助手的身份、职责和边界。

当一个新的动态Agent（例如为李四创建的 wecom-dm-lisi ）首次被初始化时，插件会自动将这个模板目录下的所有文件 复制 到该Agent的独立工作区中。这意味着，李四从一开始就能在一个预配置了上下文、工具说明和行为准则的环境下与AI交互，体验远优于空白工作区。

实操心得：模板的“只补缺、不覆盖”策略 插件非常智能地处理模板同步。它会在每个工作区维护一个状态文件 ( .openclaw/wecom-template-state.json )。首次同步时，复制所有模板文件。之后，如果模板目录更新了（比如你改动了 TOOLS.md ），插件只会将 新增的 文件复制到工作区，而 绝不会覆盖 用户或AI在工作区中已经创建或修改过的同名文件。这完美平衡了统一管理和个性化演进的需求。例如，你可以通过模板为所有销售团队的AI助手预置产品手册，但每个助手与客户的历史沟通记录 ( MEMORY.md ) 是独立且受保护的。

3.4 增强出站能力配置：自建应用与Webhook

要实现主动发送消息、文件或按部门群发，必须配置自建应用。同时，Webhook为群通知提供了更轻量的选择。

第一步：创建并配置自建应用

1. 在企业微信管理后台“应用管理”中创建自建应用，记录下 CorpID 、 AgentId 和 Secret 。
2. 在插件配置中填入这些信息：

{
  "channels": {
    "wecom": {
      // ... 其他配置 ...
      "agent": {
        "corpId": "wwxxxxxxxxxxxxxxxx", // 企业CorpID
        "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 应用Secret
        "agentId": 1000002, // 应用AgentId
        "replyFormat": "markdown" // 回调入站回复格式，推荐markdown
      }
    }
  }
}

第二步：配置群机器人Webhook（可选）

1. 在企业微信群里添加一个“群机器人”。
2. 复制其Webhook URL（或仅复制URL中的key参数）。
3. 在配置中定义映射：

{
  "channels": {
    "wecom": {
      // ... 其他配置 ...
      "webhooks": {
        "ops": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx", // 完整URL
        "dev": "yyy" // 或者只写key
      }
    }
  }
}

配置完成后，你就可以在Skills或其他Agent中，通过指定目标 webhook:ops 或 webhook:dev 来向对应的群发送消息了。

第三步：网络与代理配置 如果你的服务器需要通过代理访问外网，或者需要自定义企业微信API地址（例如使用内网代理），可以进行如下配置：

{
  "channels": {
    "wecom": {
      // ... 其他配置 ...
      "network": {
        "egressProxyUrl": "http://your-proxy-server:8080", // 出站HTTP代理
        "apiBaseUrl": "https://qyapi.weixin.qq.com" // 一般无需修改
      }
    }
  }
}

避坑指南：自建应用“可信IP”错误 配置好自建应用后，如果主动发送消息时遇到错误码 60020 (not allow to access from your ip)，这是因为企业微信限制了自建应用API的调用来源IP。 你必须登录企业微信后台，进入该自建应用的“设置”->“权限管理”->“开发者权限”，将你部署OpenClaw的服务器的公网出口IP地址添加到“企业可信IP”白名单中 。这个步骤经常被遗漏，导致主动发送功能失效。

4. 多账号管理模式实战

对于中大型企业，为不同部门或业务线配置独立的机器人是常见需求。 @sunnoy/wecom 插件原生支持多账号管理，无需启动多个OpenClaw实例。

4.1 多账号配置结构

多账号配置的核心思想是“共享基础配置，覆盖个性配置”。在 channels.wecom 下，你可以直接定义多个账号。

{
  "channels": {
    "wecom": {
      // 【共享配置】所有账号都会继承这些顶层设置
      "defaultAccount": "internal", // 默认账号，用于CLI命令等未指定账号的场景
      "adminUsers": ["zhangsan"], // 全局管理员
      "commands": {
        "enabled": true,
        "allowlist": ["/help", "/status"]
      },
      "groupChat": {
        "enabled": true,
        "requireMention": true
      },

      // 【账号“internal”的专属配置】
      "internal": {
        "botId": "aib-internal-xxx",
        "secret": "secret-internal-xxx",
        "dmPolicy": "pairing",
        "welcomeMessage": "您好，这里是内部技术支持助手。",
        "agent": {
          "corpId": "wwxxxxxxxxxxxxxxxx",
          "corpSecret": "secret-for-app-1",
          "agentId": 1000001
        }
      },

      // 【账号“support”的专属配置】
      "support": {
        "botId": "aib-support-xxx",
        "secret": "secret-support-xxx",
        "dmPolicy": "open", // 客服对所有人开放
        "welcomeMessage": "欢迎联系客服助手！",
        "groupPolicy": "disabled", // 客服不支持群聊
        "agent": {
          "corpId": "wwxxxxxxxxxxxxxxxx", // 可以和internal用同一个企业，不同应用
          "corpSecret": "secret-for-app-2",
          "agentId": 1000002
        },
        "webhooks": {
          "notify": "key-for-support-notify-group"
        },
        "mediaLocalRoots": ["/data/support/uploads"] // 该账号独有的媒体文件根目录
      }
    }
  }
}

在这个配置中，我们定义了两个机器人账号： internal (内部技术助手) 和 support (对外客服助手)。它们共享了管理员、命令白名单和群聊@规则。但各自有不同的机器人凭证 ( botId , secret )、不同的准入策略 ( dmPolicy )、不同的欢迎语，甚至绑定了不同的自建应用 ( agent ) 用于主动发送消息。 support 账号还单独配置了一个Webhook和一个媒体文件目录。

4.2 多账号下的动态Agent与路由

在多账号模式下，动态Agent的ID生成规则会自动包含账号前缀，从而实现跨账号的完全隔离。

• 用户 wangwu 私聊 internal 机器人，创建的Agent ID为： wecom-internal-dm-wangwu
• 用户 wangwu 私聊 support 机器人，创建的Agent ID为： wecom-support-dm-wangwu
• 群 wr999888 中触发 support 机器人，创建的Agent ID为： wecom-support-group-wr999888

这意味着，即使同一个用户联系两个不同的机器人，他在两个对话中的上下文、工作区文件、记忆都是完全独立的，就像在和两个不同的助手对话一样。这种隔离对于区分“内部技术咨询”和“外部客户服务”场景至关重要。

4.3 多账号的运维与管理

多账号模式下，一些CLI命令需要指定目标账号。例如，批准配对：

# 批准用户 li-si 与 `internal` 账号的配对请求，配对码为 123456
openclaw pairing approve wecom:internal 123456

# 如果不指定账号，则使用配置中定义的 `defaultAccount` (本例中是internal)
openclaw pairing approve wecom 123456

查看插件状态时，也会按账号分别显示连接状态、配额使用情况等信息，便于分账号监控。

经验分享：如何规划多账号策略

1. 按部门/职能划分 ：这是最清晰的划分方式，如 tech , hr , sales 。每个部门管理自己的机器人配置和知识库模板。
2. 按环境划分 ：可以设置 prod (生产)、 staging (预发布)、 dev (开发) 账号，用于测试新功能而不影响线上用户。
3. 共享与独享配置 ：将通用的安全策略（如 adminUsers 、基础 commands ）放在顶层共享。将差异化的部分（如 welcomeMessage 、绑定的 agent 应用、 mediaLocalRoots ）放在各账号内部。这样管理起来最清晰。
4. 谨慎使用 defaultAccount ： defaultAccount 主要用于CLI命令的缺省值。确保它指向一个稳定、常用的账号，避免误操作。

5. 消息处理全流程与高级特性

5.1 入站消息的增强处理

插件对企业微信推送的原始消息做了大量增强处理，让AI能更好地理解上下文。

• 图文混排消息 ( mixed ) ：当用户同时发送图片和文字时，企业微信会推送 mixed 消息。插件会将其智能拆解为一条文本消息和一条独立的图片消息，并按顺序提交给AI处理，保证了信息的完整性。
• 语音消息转写 ( voice ) ：插件会自动下载语音文件，并提取企业微信服务端提供的转写文本 ( voice.content )，将文本内容送入AI。这意味着用户可以直接发送语音提问，体验更自然。
• 引用消息 ( quote ) ：当用户回复某条历史消息时，企业微信会附带引用信息。插件会解析并携带被引用消息的ID和内容摘要，一同发送给AI。这使得AI能够理解“针对你上面说的XXX，我认为...”这样的对话上下文，回复更精准。
• 消息去重 ：通过结合企业微信的 reqId 和 msgId ，插件实现了消息去重，有效防止因网络抖动等原因导致的同一条消息被重复处理。

5.2 出站回复与媒体文件发送

AI的回复处理是核心环节，插件在此做了大量优化。

流式回复与思考过程 ：当 sendThinkingMessage: true 时，AI开始思考后会立即发送一个 <think></think> 的占位消息。随后，AI的“思考过程”（即模型内部推理文本，通常被包裹在 <think>...</think> 标签中）会以流式更新的方式，实时替换这条占位消息。这个过程采用了800ms的节流控制，避免因更新过快导致SDK队列溢出或客户端渲染卡顿。最终，思考标签会被移除，只将最终结论发送给用户，从而实现了“边想边说”的流畅体验。

自动媒体文件发送 ：这是非常强大的一个特性。AI在回复中可以直接引用本地文件路径。插件会解析回复文本中的特定指令：

• MEDIA:/absolute/path/to/image.png ：发送图片。
• FILE:/absolute/path/to/report.pdf ：发送文件（支持图片、文档、压缩包等）。

例如，一个数据分析Skill运行后，可以在工作区生成一个 chart.png ，然后AI在回复中输出：“分析完成，图表如下：\n\nMEDIA:/workspace/chart.png”。插件会自动识别该指令，将图片上传到企业微信并发送给用户。

文件路径安全与 mediaLocalRoots ：出于安全考虑，AI不能任意读取服务器上的所有文件。默认只允许访问当前Agent的工作区 ( /workspace/... ) 和OpenClaw状态目录下的浏览器媒体目录。如果你需要让AI发送位于其他目录的文件（例如 /tmp/openclaw/report.pdf ），必须在配置中明确授权：

"mediaLocalRoots": ["/tmp/openclaw"]

修改此配置后，必须重启Gateway才能生效 。对于多账号，可以精细控制： "support": { "mediaLocalRoots": ["/data/support"] } 。

最佳实践：处理浏览器生成的文件 当AI使用浏览器工具访问网页并截图后，截图可能保存在一个宿主机路径。直接使用 MEDIA:/tmp/xxx/screenshot.png 可能会被沙箱安全策略拦截。 推荐的做法是，在Skill或AI指令中，先调用 stage_browser_media 这个专用函数（如果OpenClaw环境提供），将文件从浏览器暂存区安全地复制或移动到当前工作区内，然后再使用 MEDIA:/workspace/... 路径进行回复。 这符合最小权限原则，也更可靠。

5.3 主动发送与通道选择策略

当你需要主动推送消息时（例如定时任务、事件触发），需要明确指定“发送目标”，插件会根据目标格式自动选择最佳通道。

目标格式	示例	使用通道	适用场景
wecom:zhangsan	wecom:zhangsan	1. WebSocket (优先) 2. Agent API (WS失败时)	主动给单个用户发文本消息。
group:wr123456	group:wr123456	1. WebSocket (优先) 2. Agent API (WS失败时)	主动在群里发文本消息。
party:2	party:2	Agent API	向整个部门（ID为2）广播消息。
tag:Developers	tag:Developers	Agent API	向“Developers”标签下的所有成员发送消息。
webhook:ops	webhook:ops	Webhook	向配置好的“ops”群机器人发送通知（支持Markdown、图片、文件）。

通道选择逻辑详解 ：

1. WebSocket通道 ：优先级最高，因为延迟最低，且支持企业微信客户端的特殊样式（如@人）。但它只能发送文本和图片，且要求接收方必须在当前会话中。
2. Agent API通道 ：能力最全面，支持文本、图片、文件、图文、以及 部门/标签群发 。当WS发送失败、或目标格式为 party: / tag: 、或消息包含文件时，会自动使用此通道。
3. Webhook通道 ：最轻量，仅用于向特定的群机器人发送消息。发送速度很快，适合告警、日志推送等场景。但它不支持@群成员。

后备与重试机制 ：如果通过WS发送消息失败（例如连接临时中断），插件会将该消息放入一个“待重试”队列（Pending Reply）。待WS连接恢复后，会自动通过Agent API通道重新发送。这极大地提高了消息的最终可达性。

5.4 配额感知与限流提醒

企业微信对消息发送有频率限制。插件内置了一个本地的配额追踪器，帮助管理员提前感知风险。

• 被动回复配额 ：针对每个会话（每个用户或群聊），追踪过去24小时内的回复次数。企业微信对此有限制（例如每天30条）。当某个会话的回复次数接近上限（如达到24条）时，插件会在日志中输出警告。
• 主动发送配额 ：针对每个会话，追踪每日的主动发送次数（同样有限制，如10条）。接近上限时也会告警。
• 连接状态 ：插件会监控WebSocket连接状态。如果因为另一个实例登录导致当前连接被踢下线 ( disconnected_event )，会在状态中标记 displaced ，提醒管理员可能存在多实例冲突。

当前策略是“感知与告警”，而非“硬性阻断” 。插件不会在达到限额时停止发送消息，而是通过日志警告，让管理员有机会干预或优化使用模式，避免触发企业微信的官方频控导致服务被临时禁用。你可以在插件的运行状态中查看这些配额信息。

6. 自建应用回调入站配置详解

从2.1版本开始，插件新增了自建应用HTTP回调作为 可选的、与WebSocket并行的第二入站通道 。这个功能主要适用于以下场景：

1. 你已经有一个正在运行的自建应用，希望在不改动现有回调逻辑的前提下，接入OpenClaw的AI能力。
2. 你的网络环境限制，使得维护一个出向的WebSocket长连接比暴露一个HTTP回调接口更困难。
3. 你需要一个独立的、可负载均衡的HTTP端点来接收消息。

6.1 回调入站配置步骤

第一步：配置插件 在已有的自建应用配置 ( agent ) 基础上，增加 callback 字段。

{
  "channels": {
    "wecom": {
      "botId": "aib-xxx",
      "secret": "bot-secret-xxx",
      "agent": {
        "corpId": "wwxxxxxxxxxxxx",
        "corpSecret": "app-secret-xxx",
        "agentId": 1000002,
        "replyFormat": "markdown", // 回调回复的格式
        "callback": {
          "token": "YourTokenForVerification", // 用于校验的Token，任意字符串
          "encodingAESKey": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG", // 43位密钥
          "path": "/webhooks/wecom-app" // Gateway监听的URL路径
        }
      }
    }
  }
}

第二步：企业微信后台配置

1. 进入你的自建应用管理页面。
2. 找到“接收消息”配置项。
3. 点击“设置API接收”。
4. 填入以下信息：
   • URL : https://你的网关域名或IP:18789/webhooks/wecom-app (端口18789是OpenClaw Gateway默认端口，路径与配置中 path 一致)。
   • Token : 与配置中 agent.callback.token 一致。
   • EncodingAESKey : 与配置中 agent.callback.encodingAESKey 一致。
5. 点击“保存”。企业微信会向你的URL发送一个GET请求进行验证，插件会自动处理并响应成功。

第三步：重启与验证 重启OpenClaw Gateway使配置生效。现在，用户向这个自建应用发送的消息，除了可以通过WebSocket（如果也配置了机器人）接收外，也会通过HTTP POST回调到你的Gateway，并由插件路由给相应的AI Agent处理。回复消息则会通过你配置的自建应用Agent API发送回去。

6.2 回调入站与WS入站的异同

• 并行运行 ：两者互不干扰。你可以同时配置WS机器人长连接和自建应用回调，消息可以从任一路径进入。
• 消息类型 ：回调入站支持文本、图片、语音、文件、视频。WS入站同样支持这些，且额外支持“图文混排”和“引用消息”的增强解析。
• 回复方式 ：WS入站的回复通过WebSocket流式返回。 回调入站的回复，则通过自建应用API以“主动发送消息”的形式返回 ，并且可以通过 agent.replyFormat 指定为 markdown （默认）或 text 格式。
• 适用场景 ：WS是主推模式，延迟低，体验好。回调是备用或集成模式，更适合需要HTTP接口的场景。

注意事项：回调模式的消息流 在回调模式下，消息的路径是：用户 -> 企业微信服务器 -> HTTP POST -> 你的Gateway -> AI处理 -> 调用自建应用API -> 企业微信服务器 -> 用户。这比WS直接推送多了一次网络往返，且回复是“主动发送”而非“被动回复”，在某些企业微信客户端版本中，通知样式可能略有不同。对于绝大多数交互场景，WS长连接是更优选择。回调入站主要作为补充或迁移过渡方案。

7. 常见问题排查与调试技巧

即使配置正确，在实际部署中也可能遇到各种问题。这里汇总了一些常见问题的排查思路。

7.1 连接与认证问题

问题：启动后日志没有显示WebSocket连接成功。

• 检查1：凭证是否正确 。确认 botId 和 secret 是从企业微信后台“AI机器人-长连接模式”下获取的，而不是旧版回调模式的Token。
• 检查2：网络连通性 。确保运行OpenClaw的服务器可以访问 wss://openws.work.weixin.qq.com 和 https://qyapi.weixin.qq.com 。如果有防火墙或代理，需正确配置 network.egressProxyUrl 。
• 检查3：机器人模式 。登录企业微信后台，确认该机器人已切换到“长连接模式”。如果还配置着HTTP回调，需要先删除回调配置。
• 检查4：插件是否启用 。确认 plugins.entries.wecom.enabled 和 channels.wecom.enabled 都为 true 。

问题：日志中出现 disconnected_event 或 displaced 状态。

• 原因 ：同一个企业微信机器人 ( botId ) 在同一时间只能有一个活跃的WebSocket连接。如果另一个OpenClaw实例（或者同一台机器上重启了服务）用相同的凭证建立了连接，之前的连接就会被踢下线。
• 解决 ：检查是否在多处部署了相同的配置。确保生产环境只有一个活跃实例。如果是开发测试，注意重启服务会导致连接转移。

7.2 消息发送与接收问题

问题：用户发了消息，但AI没有回复。

• 检查1：准入策略 。确认用户的私聊或所在群聊没有被 dmPolicy 或 groupPolicy 禁止。如果是 pairing 模式，检查用户是否已完成配对 ( openclaw pairing approve wecom <code> )。
• 检查2：群聊@规则 。如果在群里不回复，检查 groupChat.requireMention 是否为 true 以及用户是否正确@了机器人。企业微信的@可能包含显示名，而插件匹配的是UserID。查看日志确认是否识别到了提及。
• 检查3：命令白名单 。如果用户发送的是斜杠命令（如 /system ），检查该命令是否在 commands.allowlist 中，以及用户是否在 adminUsers 列表里。
• 检查4：OpenClaw Gateway及Agent状态 。查看Gateway日志，确认消息是否被接收、路由到了哪个Agent、以及该Agent是否正常运行并返回了回复。

问题：AI回复中引用的图片或文件发送失败，提示“没有权限访问路径”。

• 原因 ：AI尝试发送的文件路径不在允许访问的目录列表中。
• 解决 ：
  1. 确认文件路径是绝对路径，并且以 MEDIA: 或 FILE: 开头。
  2. 如果文件在Agent工作区内，路径应类似 MEDIA:/workspace/myimage.png 。
  3. 如果文件在宿主机其他位置（如 /tmp/report.pdf ），必须将该文件的 父目录 （即 /tmp ）添加到 channels.wecom.mediaLocalRoots 配置数组中。
  4. 修改 mediaLocalRoots 后，必须重启OpenClaw Gateway才能生效 。
  5. 对于浏览器工具生成的文件，优先使用 stage_browser_media 函数将其转移到工作区内再引用。

问题：通过自建应用API主动发送消息失败，报错 60020 。

• 原因 ：企业微信限制了自建应用API的调用来源IP。
• 解决 ：登录企业微信后台，进入该自建应用的“设置”->“权限管理”->“开发者权限”，将你部署OpenClaw的服务器的公网IP地址添加到“企业可信IP”白名单中。

7.3 配置与功能问题

问题：如何从旧的官方插件迁移过来？

1. 备份你的 openclaw.json 配置。
2. 卸载官方插件： openclaw plugins uninstall wecom-openclaw-plugin 。
3. 安装本插件： openclaw plugins install @sunnoy/wecom 。
4. 检查配置：确保 channels.wecom 下使用的是 botId 和 secret ，并且已删除旧的 token 、 encodingAESKey 、 url 等回调相关配置。
5. 重启Gateway： openclaw gateway restart 。
6. 关键步骤 ：登录企业微信后台，将对应的AI机器人切换到“长连接模式”。

问题：动态Agent的工作区模板没有生效。

• 检查1：路径是否正确 。 workspaceTemplate 需要配置一个在服务器上真实存在的目录绝对路径。
• 检查2：查看Agent工作区 。找到对应动态Agent的工作区目录（通常在 ~/.openclaw/workspaces/ 下），检查里面是否有从模板复制过来的文件（如 AGENTS.md ）。
• 检查3：理解同步逻辑 。模板只在Agent 首次创建 时完全复制。之后，如果模板目录有更新，插件只会向工作区添加 新文件 ，而不会覆盖已有文件。检查工作区内的 .openclaw/wecom-template-state.json 文件，它记录了同步状态。

问题：想禁用动态Agent，让所有消息都路由到默认Agent，怎么做？

• 将 dynamicAgents.enabled 设置为 false 。
• 或者，使用OpenClaw的 bindings 功能，将特定的企业微信UserID或群ChatID固定绑定到你想要的某个静态Agent上。绑定规则的优先级高于动态Agent路由。

7.4 日志分析与调试建议

插件的日志是排查问题的第一手资料。建议将OpenClaw的日志级别调整为 debug 或 info 以获取更详细的信息。

• 连接日志 ：关注 [WeCom] WebSocket connected for bot: 和 [WeCom] WebSocket disconnected 消息。
• 消息流日志 ：关注 [WeCom] Received message from user: 和 [WeCom] Routing message to agent: 消息，这里会显示消息来源、内容和目标Agent ID。
• 配额警告 ：关注 [WeCom] Quota warning 之类的日志，提前了解哪些会话即将触达发送限制。
• 错误日志 ：任何 [WeCom] Error 或异常堆栈信息都需要仔细查看，它们通常直接指出了问题根源，如网络错误、API调用失败、配置错误等。

对于复杂问题，可以尝试先简化配置，只保留最基本的 botId 和 secret ，确保基础通信正常。然后再逐一添加其他功能配置（如动态Agent、自建应用、Webhook等），每加一项就测试一下，从而定位是哪个模块引起的问题。