> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 企业微信机器人

> 使用企业微信智能机器人 API 模式和长连接方式接入艾维斯，并控制 Bot ID、Secret、消息权限和测试边界。

企业微信机器人用于把艾维斯能力接入企业微信会话。推荐在企业微信客户端或管理后台中创建“智能机器人”，选择“API 模式创建”，并使用长连接方式接入。

它适合处理内部问答、工单辅助和通知场景，不用于任意历史消息导出。上线前应确认消息权限、可用范围、默认知识访问策略和审计路径。

## 适用场景

| 场景        | 建议                                     |
| --------- | -------------------------------------- |
| 团队知识问答    | 将机器人开放给已批准成员或群，并只绑定该团队可访问的 Agent 或文档集。 |
| 内部支持或工单辅助 | 使用独立机器人名称和 owner，便于运维、日志筛选和权限复核。       |
| 项目群助手     | 为项目群限定知识范围和工具范围，项目结束后关闭机器人或移除访问范围。     |
| 敏感知识问答    | 先验证成员、群和文档集权限，不把机器人配置成绕过权限的共享入口。       |

## 管理边界

| 项目 | 建议                                    |
| -- | ------------------------------------- |
| 入口 | 使用已批准的企业微信智能机器人、API 模式和长连接通道。         |
| 身份 | 将机器人绑定到明确的艾维斯工作区和 owner，不把机器人当作管理员代理。 |
| 响应 | 仅返回当前用户、群或绑定 Agent 可访问的知识和工具结果。       |
| 权限 | 只开通机器人实际需要接收的消息类型和范围。                 |
| 运维 | 记录 Bot ID、密钥轮换、消息权限、负责人和下线流程。         |

## 配置前检查

开始配置前，请确认：

1. 已具备企业微信管理员权限。
2. 已登录[企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/index)，或已在企业微信客户端中切换至管理员账号。
3. 已打开艾维斯中的企业微信机器人配置页面，准备填写 `Bot ID` 和 `Secret`。
4. 已确认机器人允许服务的群、部门、成员、工作区和默认 Agent 或知识范围。
5. 已决定使用长连接方式接入。长连接方式不需要暴露公网回调地址，但仍需要正确保存 Bot ID、Secret 和消息权限。

> `Secret` 是敏感信息。只应保存到受保护配置中，不要写入公开文档、Agent 指令、截图、工单或聊天记录。

## 进入智能机器人入口

在企业微信客户端或管理后台中进入“工作台”，打开“智能机器人”。

![企业微信工作台中的智能机器人入口](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/b8849dff59b03723f84081b9992c64feaf4df32c2fb1caaac208a36b2d0b8031/assets/aivis/wecom-bot/wecom-smart-bot-entry.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=2bdce9521358c9912e4014bb4b27e24ed5fa08976b3461e1e385ae7216e1ddb8&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 创建机器人

点击“创建机器人”，进入机器人创建流程。

![企业微信智能机器人创建入口](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/62e8ff3a8c74d785ed44388e69d96b3a0cb659aa7c4ca19b1889d609af2ad65a/assets/aivis/wecom-bot/wecom-create-bot.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=07ce3aeceaf3c2c4ff89d09dcd587f631c2671f22c7818353bf5c8dc8d2be647&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

选择“手动创建”。

![企业微信智能机器人选择手动创建](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/01a42b956b4c19fc0dba34cd19eafc91b2deeeba21a280427984b7392803f293/assets/aivis/wecom-bot/wecom-manual-create.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=aabc7ccdfe13d29d5ec6f2765cde80ba1eaf5813287f2bd4bf61b7d394103327&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

在创建方式中选择底部的“API 模式创建”。API 模式会生成当前机器人接入艾维斯所需的 `Bot ID` 和 `Secret`。

![企业微信智能机器人选择 API 模式创建](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/297573934ca20626e6e786a5e3a15e244d0d4aee2d554a41cfbba9b9136dd0cc/assets/aivis/wecom-bot/wecom-api-mode-create.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=0c6e2c1ebab361e31c53e2d199deb5115ab113803150e6146104daf5820afe28&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 配置接入方式和消息权限

接入方式推荐选择“长连接”。按页面要求完成基础配置后，继续配置机器人可接收的消息范围和消息权限。

![企业微信智能机器人配置长连接接入方式](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/094566589c675d9bf1d6612e927b51292fcc3963ee99a8bfc717133605a235ac/assets/aivis/wecom-bot/wecom-stream-connection.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=f42831485c4a701a0bac477bff6bdf452bd4eb712d45f14ec9fbea5ec19f50a6&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![企业微信智能机器人配置消息权限](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/d7b2f72ea9eca15185ce6dfedb9e3a963c1a20c7baa454d5d1ffdcc385610852/assets/aivis/wecom-bot/wecom-message-permissions.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=891f004cc2a3a6e14d427c9a09ae7e94336f279330e99e7e57f3cc12a65b277b&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

![企业微信智能机器人确认消息权限](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/a530317da5e8c9a9ddedff4af21c90e4f112f1802e1caaecea95b4137ec1bf58/assets/aivis/wecom-bot/wecom-message-permission-confirm.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=66ed7c06987fd7d097980b1c34b9504b8735baf3f0a58c01927bcbcfa0937e96&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

配置消息权限时请注意：

* 只选择机器人实际需要接收的消息类型。
* 如果机器人只用于有限范围的成员或群，不要把可用范围扩大到全企业。
* 权限变更后，需要重新完成企业微信侧保存，并回到艾维斯侧重复测试。

## 填写 Bot ID 和 Secret

复制企业微信生成的 `Bot ID` 和 `Secret`，返回艾维斯机器人配置页面，将其填入对应字段后点击“保存”。

![艾维斯机器人配置页面填写企业微信 Bot ID 和 Secret](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/2fe8b7ea9a9a85975a3d34a2b163c6cf66b4074318d2eab8a91f8ccb72a1f5d4/assets/aivis/wecom-bot/aivis-wecom-bot-credentials.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=191bf4bb595b29d20ed800f391707d427dde6c8e2d146003ae6685c76d2a5ddb&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

| 企业微信     | 艾维斯配置字段 | 说明                 |
| -------- | ------- | ------------------ |
| `Bot ID` | Bot ID  | 标识当前企业微信智能机器人。     |
| `Secret` | Secret  | 用于机器人鉴权和建立长连接。     |
| 长连接      | 接入方式    | 建议作为企业微信机器人默认接入方式。 |

配置时请注意：

* `Bot ID` 与 `Secret` 必须来自同一个企业微信智能机器人。
* 不要把企业 ID、群 ID、成员 ID、机器人名称或管理员账号填入 `Bot ID`。
* 如果重新生成了 `Secret`，需要同步更新艾维斯配置；否则机器人可能无法连接或收消息。
* 如果页面提示已保存且没有更换密钥，可以保持密钥字段为空。

## 测试企业微信机器人

测试前，请先在艾维斯机器人配置页确认：

1. 机器人开关为已启用。
2. `Bot ID` 和 `Secret` 已保存。
3. 企业微信侧已选择 API 模式和长连接接入方式。
4. 消息权限和可用范围符合当前测试场景。
5. 绑定的 Agent、知识范围和工具范围符合当前测试场景。

然后打开企业微信中的机器人会话并发送测试消息。配置正确时，机器人应能正常接收消息并返回结果。

![企业微信机器人消息收发测试成功](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/alephantai.docs.buildwithfern.com/b4297f36090e7ca65d673024140296cba9ebd8ffd59df85e5cbfd837ed10d617/assets/aivis/wecom-bot/wecom-bot-test.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260805%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260805T140540Z&X-Amz-Expires=604800&X-Amz-Signature=513554c9522d39738a728f68d61848c7a3f56bcbba7ce12abaf217ea02982254&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## 验证访问边界

完成基础回复测试后，再验证治理边界：

1. 使用授权成员发送一个应当能回答的问题，确认机器人返回正确内容。
2. 使用未授权成员、未授权群或无权访问文档集的问题进行测试，确认机器人不会返回敏感数据。
3. 在追踪或请求日志中确认来源平台、用户上下文、绑定 Agent、响应结果和错误信息可审计。
4. 更换 `Secret`、消息权限、可用范围或默认 Agent 后，重新保存配置并重复测试。

## 常见问题排查

| 现象                   | 优先检查项                                                 |
| -------------------- | ----------------------------------------------------- |
| 企业微信机器人无法连接          | `Bot ID` 与 `Secret` 是否来自同一机器人，Secret 是否被重新生成后未同步到艾维斯。 |
| 企业微信能发送消息，但艾维斯没有收到日志 | 是否使用 API 模式创建，是否选择长连接，消息权限是否保存，机器人是否在目标范围可用。          |
| 单聊或群聊无回复             | 机器人是否被加入或开放给目标会话，当前消息类型是否在企业微信消息权限中。                  |
| 艾维斯收到请求但无结果          | 绑定的 Agent、知识范围、工具范围或成员权限是否满足当前问题。                     |
| 返回无权限或资源为空           | 目标知识库、文档集、群聊或其他资源是否已向当前机器人和用户授权。                      |
| 密钥更新后仍失败             | 确认艾维斯配置已重新保存，并重启或等待长连接重新建立。                           |

## 安全与维护建议

* 仅在艾维斯配置页保存真实密钥，不把密钥写入文档、截图、工单、聊天记录或代码仓库。
* 密钥疑似泄露时，应在企业微信侧重新生成，并立即同步更新艾维斯配置。
* 权限按最小可用范围申请。只需要消息自动回复时，不要额外开通通讯录、消息归档或管理类权限。
* 机器人长期不用时，先在艾维斯侧关闭机器人，再在企业微信侧收回权限或下线机器人。
* 生产环境建议记录每次权限变更、密钥轮换、接入方式调整和验证结果。

## 相关页面

* [智能体](/aivis/agents/agents) 介绍如何配置可被机器人调用的 Agent。
* [用户、群组与角色](/aivis/governance/users-and-groups) 介绍访问边界如何应用到成员和群组。
* [追踪](/aivis/governance/tracing) 介绍如何审计机器人请求。