# 企业微信配置指南

在 MOI 中获取二维码，使用企业微信扫码并确认授权，再保存连接配置，即可将智能体接入企业微信智能机器人。长连接由 MOI 管理，无需配置公网域名、回调 URL 或工具实例。

## 开始前准备

- 目标智能体已创建，并能在 MOI 中正常对话。
- 准备可登录的企业微信账号，用于扫码并确认授权。
- 当前工作区有可用的智能体对话模型。

## 1. 打开 IM 双向通信

1. 在顶部切换到**智能体**，再在左侧点击**智能体**，打开智能体列表。
2. 找到目标智能体卡片，点击右上角的**⋯**菜单，选择**IM 双向通信**。

```{figure} /assets/images/agents/guide-5-hd/im-connection-entry.png
:alt: 在 MOMO 超级智能体卡片的更多操作菜单中选择 IM 双向通信。
:class: agent-guide-image
:figclass: agent-guide-shot

图中以 MOMO 超级智能体为例；为其他智能体连接企业微信时，从对应卡片打开同一入口。
```

## 2. 选择连接方式并保存配置

可以扫码授权，也可以使用已有智能机器人的 Bot ID 和 Secret 手动连接。两种方式任选一种。

### 扫码授权

1. 在配置窗口的**平台**中选择**企业微信智能机器人**。
2. 点击**获取企业微信二维码**。
3. 使用企业微信扫描二维码，并按提示确认授权。
4. 返回 MOI，等待**扫码授权成功，请继续连接**的提示。
5. 在**运行模型**中选择当前工作区可用的模型。
6. 点击**保存并继续**。

```{figure} /assets/images/agents/guide-5-hd/wecom-im-qr-setup.png
:alt: 企业微信智能机器人配置窗口中提供获取企业微信二维码按钮和运行模型选择框。
:class: agent-guide-image
:figclass: agent-guide-shot

获取企业微信二维码，扫码授权后选择运行模型并保存。
```

扫码授权用于获取连接所需的信息；点击**保存并继续**后，MOI 才会保存配置并开始建立长连接。二维码过期时，点击**重新获取二维码**再次扫码。

### 使用已有机器人凭据连接

#### 在企业微信获取 Bot ID 和 Secret

1. 打开企业微信客户端，在左侧点击**机器人**，再点击**管理机器人**。

   ```{figure} /assets/images/agents/guide-5-hd/wecom-bot-management-entry.png
   :alt: 企业微信客户端的机器人页面，标出了左侧机器人入口和管理机器人按钮。
   :class: agent-guide-image
   :figclass: agent-guide-shot

   从企业微信客户端进入机器人管理页面。
   ```

2. 在**我的机器人**列表中找到要连接的 API 模式机器人，点击该行的**详情**。

   ```{figure} /assets/images/agents/guide-5-hd/wecom-bot-management-list.png
   :alt: 企业微信管理机器人列表中，API 模式机器人的详情入口已标出，名称和成员信息已脱敏。
   :class: agent-guide-image
   :figclass: agent-guide-shot

   打开要连接的机器人的详情。
   ```

3. 在**机器人详情**中打开**API 配置**。

   ```{figure} /assets/images/agents/guide-5-hd/wecom-bot-api-entry.png
   :alt: 企业微信机器人详情页中的 API 配置入口。
   :class: agent-guide-image
   :figclass: agent-guide-shot

   从机器人详情进入 API 配置。
   ```

4. 在**API 配置**中分别点击复制按钮，获取同一个机器人的 **Bot ID** 和 **Secret**。

   ```{figure} /assets/images/agents/guide-5-hd/wecom-bot-api-credentials.png
   :alt: 企业微信 API 配置页提供 Bot ID 和 Secret 及各自的复制按钮，凭据值已遮盖。
   :class: agent-guide-image
   :figclass: agent-guide-shot

   从同一个机器人的 API 配置中复制 Bot ID 和 Secret。图中凭据已脱敏。
   ```

Secret 是连接凭据，只填写在 MOI 的连接表单中，不要发送到聊天或放入公开截图。

#### 在 MOI 填写凭据

1. 返回目标智能体的 **IM 双向通信**配置窗口，平台选择**企业微信智能机器人**。
2. 如果窗口显示扫码入口，点击**更多连接方式**；如果已经显示 Bot ID 和 Secret，直接填写从企业微信复制的两个值。
3. 在**运行模型**中选择当前工作区可用的模型。
4. 点击**保存并继续**，进入长连接状态页面。

```{figure} /assets/images/agents/guide-5-hd/wecom-im-manual-credentials.png
:alt: MOI 企业微信智能机器人连接表单，包含 Bot ID、Secret 和运行模型；Bot ID 已遮盖。
:class: agent-guide-image
:figclass: agent-guide-shot

图中为已有连接的编辑状态：Bot ID 不可修改，Secret 留空表示保留现有值。首次连接时填写从企业微信取得的凭据。
```

编辑已有连接时，只有需要更换 Secret 才填写新值。图中的运行模型仅为示例，请选择当前工作区可用的模型。

## 3. 查看连接状态并验证对话

保存后，窗口进入**启用平台长连接**步骤。先确认显示**配置已保存**和**MOI 接收已启用**，再等待状态由**正在连接**变为**连接已建立**。

```{figure} /assets/images/agents/guide-5-hd/wecom-im-established.png
:alt: MOI 显示配置已保存、MOI 接收已启用、连接已建立和等待首条真实消息。
:class: agent-guide-image
:figclass: agent-guide-shot

图中长连接已建立，尚未收到真实消息。连接建立后还需要发送消息验证。
```

**等待首条真实消息**表示 MOI 尚未从该机器人收到消息。按以下步骤验证：

1. 在企业微信中打开已连接的智能机器人，发送一条测试消息。
2. 等待智能体在同一个企业微信会话中回复。
3. 回到 MOI，重新打开该智能体的**IM 双向通信**，确认接收状态已变为**已收到真实消息**。

```{figure} /assets/images/agents/guide-5-hd/wecom-im-conversation-example.png
:alt: 企业微信对话效果示例，用户发送再讲一个，机器人在同一会话中回复笑话。
:class: agent-guide-image
:figclass: agent-guide-shot

企业微信对话效果示例：发送消息后，智能体在原会话中回复。实际回复取决于所连接的智能体。
```

如果已显示**连接已建立**但没有回复，先检查是否向已连接的机器人发送了消息，再核对 MOI 是否已收到消息。其他连接异常见[连接状态与问题排查](troubleshoot.md)。

## 下一步

- [连接后的使用方式](usage.md)
- [连接状态与问题排查](troubleshoot.md)