企业微信接入指南

企业微信智能机器人通过 API 长连接接入 Gateway，支持私聊、群文本、现有控制命令及后台文本结果。无需公网回调地址；任务完成后主动发送结果，不依赖触发任务的 callback 有效期。首版不支持卡片、流式回复或媒体。

开通机器人

组织前提

智能机器人只在企业团队下可用。个人团队没有工作台，也无法登录 Web 管理后台，下面两个创建入口都进不去。企业微信右下角图标显示「我」即个人团队，显示「团队」才是企业团队。个人团队可在左下角个人名称菜单选择「变更为企业账户」并补充企业信息，审核通过后即可使用；也可以在「团队 - 管理团队」中解散后重新注册企业团队。一个微信号最多创建 5 个企业（企业团队与个人团队合计），解散重建不占额外名额。

注册企业团队免费且不需要审核。企业微信认证是另一件事，需要营业执照并由第三方审核，收取每年审核服务费。长连接是出站连接，不需要域名、备案或公网 IP，因此未认证企业同样可以接入本方案。

创建入口

管理员入口为管理后台 → 智能专区 → 智能机器人 → 创建机器人；普通成员入口为客户端工作台 → 智能机器人 → 创建机器人。「安全与管理 > 管理工具」不是当前入口。

两个入口受两层权限约束：

权限	管理后台路径	默认范围
智能机器人创建权限	智能专区 → 智能机器人 → 权限管理 → 智能机器人创建权限	全公司
API 模式管理（长连接接入成员）	智能专区 → 智能机器人 → 权限管理 → API 模式管理	通讯录 ≤1000 人的企业随创建权限；>1000 人的企业默认为空

第二层默认范围为空时，成员在创建页看不到 Bot ID 和 Secret，只会提示联系管理员开通「长连接」权限；成员可在客户端提交审批申请。若整个「智能专区」下都没有智能机器人入口，按 product_mode_unavailable 处理，请管理员开通对应产品能力。

创建参数

创建页选择 手动创建 → API 模式 → 连接方式选 使用长连接，点「获取」生成 Secret 后页面同时给出 Bot ID。

机器人创建者需为超级管理员,单聊 callback 的 from.userid 才是明文;否则该字段被企业微信加密,私聊配对无法解析发送者或回复目标。请由超级管理员创建机器人,或改为绑定群聊。
可见范围必须包含 owner，否则 Gateway 的绑定探测消息无法送达
使用方式选「仅个人使用」可完成私聊配对；要绑定群聊或验证其他成员被拒绝，需改为「多人使用」

创建页的「可使用权限」是机器人调用企业微信应用能力的 MCP/CLI 通道，带独立有效期，与长连接收发消息不是同一套权限。Gateway 只使用长连接协议本身（aibot_subscribe、aibot_msg_callback、aibot_send_msg、aibot_event_callback），不经过该能力通道，长连接凭据只有 Bot ID 和 Secret。

本接入只适用于智能机器人 API 长连接。企业自建应用、普通群机器人 webhook 和 HTTP/XML 回调需使用各自的产品接口。企业微信官方入口

配置与首次配对

ims:
  wecom:
    bot_id: your-bot-id
    secret: your-bot-secret
workspaces: {}

连接地址固定为 wss://openws.work.weixin.qq.com。YAML 中的 endpoint 为未知字段，会被忽略并提示警告，不会覆盖连接地址。请保护 YAML 中的 secret，并确保目标目录已存在。直连受阻时，可在全局或 ims.wecom 下设置 proxy_url（http、socks5/socks5h；长连接不支持 https）。见配置参考。

chord-gateway -f config.yaml --pair

前台终端在启动时立即显示配对码，早于连接准备完成；机器人仍须先就绪，/bind 才会被授权。在客户端从通讯录 → 智能机器人或工作台 → 智能机器人找到该机器人并私聊；搜不到时走工作台 → 智能机器人 → 详情 → 去使用 → 发消息。发送：

/bind "/path/to/project" <pairing_code>

Gateway 会先向该聊天主动发送固定文本 Gateway binding check.。只有平台返回成功 ACK 才保存 owner 和绑定；探测失败时绑定不变，检查机器人可用范围、主动发送权限和当前配额后重新发送 /bind。

配对完成后发送 /status，再发送普通任务。owner 可以在机器人所在群发送 /bind "/path/to/project"；探测及后续回复都发送到该群。其他成员不能执行命令或批准请求，但群内所有成员都能看到回复。每个聊天显式绑定一个工作区，Gateway 自动写入编码后的 chat_bindings，无需手工构造聊天 ID。控制命令见使用指南，配对与重置见配对指南。

bot ID 不变时，轮换 secret 保留原 owner。换 bot ID 会阻断旧配对，需停服并在本机执行 chord-gateway -f config.yaml pairing reset --platform wecom，在本机控制终端输入 wecom 确认后重新配对。reset 会清除 owner、绑定和自动 session pin，保留工作区和会话文件。一个 bot 同时只能由一个本机实例使用；账号锁在拨号前取得，跨状态目录仍互斥。

回复和故障处理

回复通过 aibot_send_msg 主动发送，并明确指定单聊或群聊，避免平台按默认群聊方式解析私聊目标。Gateway 将正文作为安全文本显示，转义 Markdown 控制字符并消除尖括号 mention 语法的提醒语义；保留普通 @，使 /answer @request 1 可直接复制使用。不生成链接、图片或卡片。分段按最终内容的 1024 UTF-8 字节预算计算，保持中文和 emoji 边界，每份输出最多 32 段，超长内容附截断提示。完整内容保留在原 Chord 会话中。

Gateway 对每个聊天至少间隔 4 秒发送，账号最多每秒 2 条，burst 为 1；下一段等待上一段的成功 ACK。每份输出总预算为 5 分钟。上述为项目保守预算和节流策略，平台实际权限及额度需在目标企业实测。

诊断	处理
`auth_failed`	核对 bot ID、secret 和机器人产品模式；认证拒绝后不自动重试。
绑定探测未接受	检查目标、可用范围、发送权限及配额，解决后重新发送 `/bind`。
`platform_rejected`	保留数字错误码核查；Gateway 不猜测限流错误码，也不盲重试。
`unknown_send`	网络中断或 ACK 超时，结果未确认；先查看聊天和原会话，不自动重发正文。部分发送失败会记录已接受段数。
`identity_mismatch`	callback 的 bot ID 与配置账号不符，连接停止；先核对凭据和部署再重启。
`ingress_prepare_failed`	核查收件服务状态和配对账号；换 bot ID 后按上述步骤本机 reset，再重新配对。
`duplicate_connection`	服务端通知另一连接取代本实例，本实例停止自动重连；关闭其他部署后重启。
`acceptance_unconfirmed`	本次投递未能确认接纳；同一业务消息的早先投递可能已提交。先核查原 Chord 会话，不直接重发。
`callback_dropped`	有回调未进入公共入口：连接准备缓存溢出或断线导致投递未提交（不代表该业务消息从未接纳，平台也不保证重投），或格式非法的用户文本回调在校验阶段被拒绝。请核查原会话后决定后续操作。
`control_target_unavailable`	接收时业务状态正被占用，无法冻结原控制目标；本条消息在当前进程内被拒绝，不会稍后对新状态执行。先查看 `/status`。
私聊发送者或目标不可用	仅当机器人创建者是超级管理员时,单聊 callback 的 `from.userid` 才为明文;否则企业微信会加密该字段,Gateway 无法解析私聊发送者或目标。请由超级管理员创建机器人,或改为绑定群聊。

普通网络错误按 1/2/4/8/16/30 秒基准退避重连，并加入 ±20% 抖动；连接持续 ready 60 秒后才清零退避。订阅认证成功后即每 30 秒发送 JSON 心跳，收件准备期间也持续保活;心跳 ACK 超过 10 秒未到达即计一次丢失,连续丢失两次才关闭旧连接。连接准备缓存最多 64 条、原始帧合计 4 MiB，超限丢弃新到的投递并计数，保留已缓存消息及连接；不自动重放丢弃消息。断线期间不能发送，恢复后收到的旧 ACK 无效，旧 send 不会重发。

仅普通用户文本可作为命令或任务。带有 compat_info 的智能助理、频道或未知来源消息均不进入命令处理。普通消息无需 create_time；缺省时使用接收时间，同时兼容官方 SDK 的可选时间字段。参见官方长连接协议。

企业微信按业务 msgid 在当前进程内去重，重启后清空。未知结果不自动重发，先核查 /status 与 Chord 原会话。见投递语义。

部署验收

自动测试覆盖模拟 WebSocket 认证、ACK 关联、关闭、命令授权、绑定探测、业务消息内存去重和文本边界。这些测试不等于真实企业账号验收，需在实际部署中验证。目标企业需依次验证：认证；私聊探测、配对和 /status；owner 群绑定和其他成员拒绝；1024 字节含中文/emoji 的样本和三段正文的显示、顺序及无提醒；超过 10 分钟的任务及后台文本结果回传；另一连接踢下线后停止争抢。任何权限或预算拒绝均保留错误码，不能记作验收通过。未开通长连接产品能力时，部署验收归类为 product_mode_unavailable；主动绑定探测被拒绝时，先检查目标类型和平台错误码；只有明确的权限拒绝才归类为 proactive_send_denied，不要将寻址错误、限流或网络超时归为权限问题。这些是部署验收分类，与上表中的运行期诊断分别记录。