# 企业微信配置指南

## 你可以用它做什么

按场景接入企业自建应用、群机器人或企业微信邮箱。三种配置相互独立，应先选对入口。

## 配置前准备

应用方式需要企业应用管理员；群机器人需要测试群的管理权限；邮箱方式需要本人邮箱的客户端专用密码。先明确是发群消息、使用企业应用，还是处理邮箱，再选择对应能力。

需要能够在当前 MOI 工作区创建或编辑工具配置。若没有入口或提示无权操作，请联系工作区管理员，不要借用他人的账号。

## 配置页面


```{figure} /assets/images/agents/guide-5-hd/19-wecom-mail-config.png
:alt: 企业微信邮箱配置：填写邮箱及授权码后，先测试连接再保存。
:class: agent-guide-image
:figclass: agent-guide-shot

企业微信邮箱配置：填写邮箱及授权码后，先测试连接再保存。
```

## 在 MOI 中操作

1. 进入「工具库 → 工具市场 → 企业微信」，选择自建应用、群机器人或邮箱能力。
2. 自建应用：在管理后台「我的企业 → 企业信息」获取 CorpID，在「应用管理 → 自建应用」获取 AgentID 和 Secret；填入 MOI 对应字段。需要接收消息时生成并保存 Callback Token、EncodingAESKey。
3. 保存应用实例后，从详情复制公网回调 URL，与 Token、EncodingAESKey 一起填到企业微信应用的「接收消息」设置，完成校验。按应用要求由管理员检查可见范围和可信 IP。
4. 群机器人：在测试群的机器人设置中取得 Webhook Key，填写机器人实例；不要填写到自建应用 Secret 字段。
5. 邮箱：登录企业微信邮箱网页端，进入「设置 → 邮箱绑定」，按要求完成微信绑定/安全登录，在「客户端专用密码」生成新密码，填到 MOI 的授权码字段。
6. 邮箱入口先点击测试连接，通过当前配置的测试后再保存；修改邮箱凭证后需要重新测试。其他入口保存后执行可用的连接测试。
7. 主动调用在智能体中选择对应实例；接收事件还需配置 MOI 路由规则及目标智能体/任务。

## 字段怎么填写

| 字段 | 何时需要 | 填写说明 |
| --- | --- | --- |
| 实例名称 | 三种入口必填 | 用名称明确区分「应用」「群机器人」「邮箱」。 |
| CorpID / AgentID / Secret | 自建应用使用 | 分别来自企业信息和该自建应用配置；不同应用的 Secret 不可混用。 |
| Callback Token / EncodingAESKey | 应用接收消息使用 | 可在 MOI 表单生成，随后同步到企业微信接收消息设置。 |
| Webhook Key | 群机器人必填 | 来自测试群机器人的 Webhook 配置，仅用于该机器人的群消息发送。 |
| 邮箱地址 / 授权码 | 邮箱必填 | 邮箱地址及客户端专用密码，不是企业微信登录密码。 |
| 超时时间 | 可选 | 按需设置；不确定时保持默认。 |

## 让智能体实际使用

回到目标智能体详情，在工具区域检查对应能力是否已绑定；提供实例选择时，核对目标连接。具体步骤见[绑定并验证工具](../bind-tools.md)。

应用/机器人：明确指定测试接收人或测试群，确认后发送一条测试消息，并到企业微信核对。邮箱：先查询已知测试邮件，发送仅使用自己的测试收件人。应用事件另行核对回调接收与目标任务触发；群机器人 Webhook 不等于接收群聊消息的入口。

验收时逐项确认：

- [ ] 保存成功，重新打开后配置仍存在。
- [ ] 测试连接返回成功，而不是只有「已配置」标签。
- [ ] 对话的工具调用记录显示实际调用，结果与目标平台一致。
- [ ] 如启用事件接收，还验证了事件投递和正确目标触发。

## 常见问题

| 现象 | 检查方法 |
| --- | --- |
| 应用 API 认证失败 | 核对 CorpID、AgentID、Secret 的来源和应用范围，按平台报错检查可信 IP。 |
| 回调校验失败 | 三个回调配置值必须匹配且 URL 公网可达；不要填写本地地址。 |
| 机器人消息失败 | 核对机器人是否仍在该群、Webhook Key 是否有效。 |
| 邮箱保存按钮不可用 | 先对当前邮箱和授权码执行连接测试；不要使用邮箱登录密码。 |

## 凭证维护与安全

只在 MOI 的敏感字段中输入 Key、Token、密码或私钥，不要放进提示词、截图、Issue 或 Git 仓库。配置更换前先确认有哪些智能体使用该实例；更换后重新测试，再验证一次实际任务。若凭证泄露，应到提供方撤销并生成新凭证。删除或停用配置会影响依赖它的调用，请先确认影响范围。

## 资料与核对范围

- 外部服务参数按管理员提供的实际接入信息填写，不预设可用模型、账号或服务地址。
- 接入范围与资料依据见[指南说明](index.md#tool-configuration-sources)。
- [返回工具配置指南目录](index.md)。

企业微信邮箱的[官方帮助入口](https://open.work.weixin.qq.com/help2/pc/19902)来自 MOI 内置指引，本次外部抓取不可用；获取专用密码的步骤按 MOI 当前内置文案编写。