---
title: "常见问题与故障排查"
description: "按实际症状定位 Ankole 的部署、身份源、模型、Worker 和聊天渠道问题。"
url: "https://ankole.agentbull.com/zh-Hans-CN/docs/faq/"
lang: "zh-Hans-CN"
---

> 面向 AI Agent 的文档索引：https://ankole.agentbull.com/zh-Hans-CN/llms.txt

# 常见问题与故障排查

这不是产品介绍，也不重复第三方平台的完整配置步骤。请先找到最早出现的异常，再选择对应的身份源或聊天平台。完整安装与首次设置仍以 [快速开始](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md) 为准。

## 先判断问题在哪一层

| 你看到的现象 | 先检查 |
|---|---|
| `/setup` 或 Console 打不开 | 部署、控制面、域名与 HTTPS |
| Console 能打开，但登录失败或通讯录不完整 | 身份源提供商（IdP） |
| Console 中 Agent 能对话，但某个 IM 没有消息 | 该聊天渠道与信号路由 |
| IM 消息已经进入 Ankole，但 Agent 无法生成回复 | LLM Provider、模型档案与 Worker |
| 只有一个平台有问题 | 直接选择下方对应 Provider，不要照搬另一平台的处理办法 |

## 所有平台都会遇到的问题

### 浏览器连不上 /setup 或 Console，先查什么？

**现象**

页面超时、拒绝连接、返回 502，或只有空白页。此时还没有进入身份源、模型或聊天平台的配置。

**判断**

控制面没有正常运行，或域名、反向代理、Ingress 没有把请求送到控制面。后续 Provider 报错通常只是连带结果。

**处理**

1. 先确认控制面、PostgreSQL 和反向代理是否健康，只处理日志里最早出现的异常。
2. 如果直接访问控制面正常，再检查域名解析、TLS 和代理到控制面的地址。
3. 不要为了试错删除数据库或持久化卷；启动失败不代表数据已经损坏。

- [按部署方式检查服务](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#deployment)
- [怎样读日志](https://ankole.agentbull.com/zh-Hans-CN/docs/log-reading/index.md)

### 首次设置需要的 activation code 在哪里？

**现象**

/setup 要求输入 activation code，但启动终端已经关闭，或者日志太多，找不到那一行。

**判断**

控制面只在首次设置阶段使用这个 code。第一位管理员完成登录后，code 会失效，此后应直接打开 Console 登录页。

**处理**

1. 尚未完成首次登录时，到快速开始中选择自己的部署方式，运行该标签页给出的日志命令。
2. 搜索 SETUP ACTIVATION CODE，不要从浏览器缓存或数据库中猜测 code。
3. 如果实例已经有 Root 管理员，不要重新激活；请使用已经配置的身份源登录。

- [读取 activation code](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#deployment)

### 选择了适配器，为什么仍看不到对应的 Provider？

**现象**

插件已保存为启用，但初始化页面、身份源或信号路由页面里仍没有对应选项。

**判断**

首次初始化会保留所有已编译插件，并用当前保存的选择过滤后续配置项。初始化完成后，Console 中保存的插件启停状态要在下一次控制面启动时生效。

**处理**

1. 如果还在 /setup，返回“插件”步骤保存选择，再进入“管理员登录”；此时不需要重启。
2. 如果初始化已经完成，请只重启控制面，不要删除数据，也不必重启 PostgreSQL。启动后确认插件已激活，再回到 Provider 页面。
3. 如果控制面启动失败，先处理日志中的插件初始化错误。

- [在 Agent 能力库中启用 Plugin](https://ankole.agentbull.com/zh-Hans-CN/docs/skills/index.md)

### 所有聊天平台都收不到回复，问题还在聊天渠道吗？

**现象**

换了频道、私信或另一个聊天应用都没有回复，Console 中直接发起的 Agent 对话也失败。

**判断**

如果 Console 对话也失败，问题通常在所有聊天渠道共用的后半段：LLM Provider、Agent 模型档案或 Worker，而不是某个平台的事件权限。

**处理**

1. 确认 LLM Provider 已启用，凭证和模型名称可用。
2. 确认 Agent 已配置 primary、light 和 heavy，并且至少有一个 Worker 显示为 ready。
3. 先在 Console 中完成一次真实模型对话；成功后，再回到所选聊天平台的标签页排查消息入口。

- [配置模型提供商和 Agent](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#3-添加模型提供商并创建-agent)
- [Worker 状态](https://ankole.agentbull.com/zh-Hans-CN/docs/worker-management/index.md)

### 计划任务没有按时运行，先查什么？

**现象**

计划任务已创建，但到了预期时间没有开始，或下一次运行时间与预期不一致。

**判断**

常见原因是任务未启用、时区或 Cron 表达式不正确，或者控制面在触发时没有运行。

**处理**

1. 打开计划任务，确认它已启用，并核对页面显示的下一次运行时间。
2. 核对实例时区和 Cron 表达式。先看页面换算出的时间，不要只凭表达式猜测。
3. 选择“立即运行”。如果可以运行，问题在时间设置；如果仍失败，继续查看运行记录。

- [配置和检查计划任务](https://ankole.agentbull.com/zh-Hans-CN/docs/schedules/index.md)

### 计划任务显示已运行，为什么聊天里没有结果？

**现象**

运行记录已经出现，但目标聊天或会话没有收到 Agent 的消息。

**判断**

触发器已经工作，问题在后续链路：目标路由、聊天渠道、Agent 模型或可用 Worker。

**处理**

1. 先打开这次运行记录，确认任务是否成功，并读取最早的错误。
2. 核对任务指向的 Agent、会话或聊天目标，以及对应的信号路由规则。
3. 确认 Agent 的模型档案可用，并且至少有一个 Worker 处于就绪状态。

- [查看计划任务运行记录](https://ankole.agentbull.com/zh-Hans-CN/docs/schedules/index.md)
- [检查信号路由规则](https://ankole.agentbull.com/zh-Hans-CN/docs/signal-bindings/index.md)

## 身份源提供商排错

登录、通讯录和组织架构同步由 IdP 负责。先选择企业实际使用的身份源。Slack 的 Socket Mode、Entra ID 的 Graph 订阅、Google Workspace 的全量同步并不是同一种机制，不能混着排查。

**选择身份源提供商**

- Slack
- Microsoft Entra ID
- Google Workspace
- 飞书 / Lark
- 钉钉
- 企业微信

### Slack

#### Slack 登录在授权跳转处失败

**现象**

Slack 在回到 Ankole 之前提示 redirect_uri 不匹配，或授权后回到错误页面。

**判断**

Slack 应用登记的 Redirect URL 与 /setup 显示的回调地址不完全相同，或 Ankole 中填了另一套 Client ID。

**处理**

1. 从 /setup 复制完整回调地址，原样加入 Slack 的 OAuth & Permissions → Redirect URLs。
2. 逐字核对协议、域名、端口、路径和 Provider ID。
3. 保存 Slack 配置后重新发起登录，不要复用旧的授权页。

#### Slack 登录成功，但同步不到成员或用户组

**现象**

管理员能进入 Console，但主体或权限组列表为空，或者缺少新成员。

**判断**

身份源应用缺少 users:read、users:read.email 或 team:read，Bot User OAuth Token 没带上新增权限，或全量同步尚未运行。

**处理**

1. 按快速开始补齐身份源所需权限。
2. Slack scope 改动后重新 Install to Workspace，并把新的 Bot User OAuth Token 写回身份源提供商。
3. 先验证一次全量同步；只有全量正常后，才继续排查实时同步。

#### Slack 名册能全量同步，但后续变更不实时更新

**现象**

首次同步有数据，但邀请、移除成员或调整用户组后，Ankole 没有及时变化。

**判断**

实时同步依赖 Socket Mode。App-Level Token 缺失、前缀不是 xapp-、Socket Mode 未启用，或控制面不能访问 Slack。

**处理**

1. 确认身份源提供商启用了“实时同步通讯录变更”，并填入有效的 App-Level Token。
2. 确认 Slack 应用已启用 Socket Mode，控制面可以主动访问互联网。
3. 改过 App-Level Token 后更新 Ankole 中的值，再观察下一次目录变更。

- [在快速开始中配置 Slack IdP](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)

### Microsoft Entra ID

#### Microsoft 登录提示 AADSTS50011

**现象**

Microsoft 授权页提示 reply URL 不匹配，错误码通常是 AADSTS50011。

**判断**

Entra 应用注册中的 Redirect URI 与 /setup 显示的 Ankole 回调地址不完全相同。

**处理**

1. 把 /setup 显示的地址原样加入应用注册的 Web Redirect URI。
2. 核对协议、域名、端口、路径和 Provider ID，不要把 Teams 消息端点填到这里。
3. 保存后等待门户配置生效，再从 Ankole 重新开始登录。

#### Entra ID 登录成功，但目录同步为空或返回 403

**现象**

管理员可以登录，但 Ankole 看不到用户和权限组，日志里可能出现 Graph 403。

**判断**

应用缺少 Group.Read.All 或 User.Read.All，或者权限已经添加，但租户管理员尚未授予 Admin consent。

**处理**

1. 在应用注册的 API permissions 中补齐 Microsoft Graph Application permissions。
2. 由租户管理员执行 Grant admin consent；只添加权限还不够。
3. 管理员同意完成后，再运行全量同步并检查主体与权限组。

#### Entra ID 全量同步正常，但实时变更没有进来

**现象**

定时全量同步能修正数据，但组成员变化不能在几分钟内出现。

**判断**

Graph 订阅需要 Microsoft 能访问 Ankole 的公共 HTTPS directory webhook。入口、证书或“Ankole 公网地址”不正确时，通知无法送达。

**处理**

1. 确认实例的公共 HTTPS 地址可从互联网访问，证书受信任。
2. 核对“Ankole 公网地址”与实际入口；它决定 Graph 订阅的通知地址。
3. 检查订阅调和日志；入口恢复后，让控制面重建或续订 Graph 订阅。

- [在快速开始中配置 Entra ID](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)

### Google Workspace

#### Google 账号有效，为什么仍被拒绝登录？

**现象**

Google 授权成功，但 Ankole 返回 login_domain_not_allowed。

**判断**

登录账号不在“允许登录的 Workspace 域名”中，邮箱未经验证，或使用了没有 hd claim 的个人 Gmail 账号。

**处理**

1. 使用企业 Google Workspace 账号，不要使用个人 gmail.com 账号。
2. 确认账号域名出现在“允许登录的 Workspace 域名”中，拼写与大小写正确。
3. 只有企业确实使用多个 Workspace 域时，才添加多个允许域。

#### Google Workspace 登录正常，但通讯录同步为空或返回 403

**现象**

管理员可以登录 Console，但权限组和成员没有同步。

**判断**

目录同步走 Service Account，不走登录用的 OAuth Client。常见原因是没有开启全网域授权、授权范围不全，或“委派管理员邮箱”不能代表目录管理员。

**处理**

1. 确认 Service Account 已启用 Domain-wide delegation。
2. 在 Workspace 管理后台为它授权快速开始列出的 Directory API scopes。
3. 核对“委派管理员邮箱”和“服务账号 JSON 密钥”，再运行全量同步。

#### Google Workspace 的成员变化为什么不会立即出现？

**现象**

修改 Workspace 用户或权限组后，Ankole 要过一段时间才更新。

**判断**

Google Workspace 身份源目前只做全量同步，没有实时目录订阅。这是正常行为，不是 WebSocket 或 webhook 故障。

**处理**

1. 等待下一次全量同步，不要为此开放 webhook。
2. 如果下一个同步周期后仍没有变化，再检查全网域授权、授权范围和“委派管理员邮箱”。
3. 确实需要实时同步通讯录变更时，可改用支持该能力的身份源提供商。

- [在快速开始中配置 Google Workspace](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)

### 飞书 / Lark

#### 飞书登录提示回调地址不匹配

**现象**

授权页打不开，或授权后无法回到 Ankole。

**判断**

飞书会精确匹配 redirect_uri。localhost 与 127.0.0.1、不同端口、不同 Provider ID 都会得到不同的地址。

**处理**

1. 从 /setup 复制当前身份源显示的完整回调地址。
2. 把它加入应用安全设置，不要手工改写域名、路径或尾部字符。
3. 发布包含这项安全设置的新版本，并确认测试用户在可用范围内。

#### 飞书登录成功，但员工或部门没有同步

**现象**

管理员能进入 Console，但主体与权限组不完整。

**判断**

应用的通讯录权限不完整、应用可用范围没有覆盖相应员工，或新版权限尚未发布。

**处理**

1. 使用快速开始中的批量权限清单补齐通讯录读取权限。
2. 确认应用可用范围包含要同步的部门和员工。
3. 发布新版本后先验证全量同步，再检查长连接增量同步。

#### 飞书全量同步正常，但人员变更不实时更新

**现象**

首次同步有数据，后续新增、移动或删除员工没有及时反映到 Ankole。

**判断**

实时同步依赖飞书长连接和通讯录事件。控制面未连上、事件没订阅或新配置未发布时，只剩全量同步。

**处理**

1. 保持控制面运行，在飞书事件与回调页选择长连接。
2. 按快速开始订阅用户和部门变更事件，并发布应用版本。
3. 确认控制面可以主动访问飞书；长连接不需要公共入口。

- [在快速开始中配置飞书 / Lark IdP](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)

### 钉钉

#### 钉钉登录提示“应用不存在”（900103）

**现象**

打开钉钉授权页时立即报 900103，还没有进入扫码后的回调阶段。

**判断**

钉钉登录服务无法使用当前 Client ID 找到可用的企业内部应用。常见原因是填成 AgentId 或 robotCode，或者应用配置尚未发布。

**处理**

1. 确认填写的是凭证与基础信息里的 Client ID，不是 AgentId、robotCode 或群机器人 webhook token。
2. 确认应用属于当前企业，并已开通登录和通讯录所需权限。
3. 发布一个新版本，再从 Ankole 重新打开授权页。

#### 钉钉扫码后才提示回调地址错误

**现象**

授权页可以打开，也能扫码，但同意授权后才报 redirect_uri 不合法。

**判断**

钉钉在扫码授权后才校验回调地址。安全设置中登记的地址与 Ankole 实际发送的地址不完全相同。

**处理**

1. 从 /setup 复制完整回调地址。
2. 把它登记到开发配置 → 安全设置 → 重定向 URL（回调域名）。
3. 发布版本后重新扫码，不要继续使用已经打开的旧授权页。

#### 钉钉目录同步报 60011，或只能看到部分员工

**现象**

登录可以完成，但目录读取失败、成员缺失，日志中可能有 sub_code 60011。

**判断**

应用缺少用户、部门或字段读取权限，或者应用的授权范围没有覆盖对应组织。

**处理**

1. 按错误返回的申请链接和快速开始清单补齐通讯录权限。
2. 确认应用授权范围覆盖要同步的部门与员工。
3. 发布新版本，再运行全量同步；不要用调大分页来掩盖权限错误。

- [在快速开始中配置钉钉 IdP](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)

### 企业微信

#### 企业微信登录或接口调用报 60020

**现象**

扫码后回不到 Ankole，或保存配置时提示 IP 不可信、错误码 60020。

**判断**

企业微信要求服务端调用来自登记过的可信 IP。自建应用与通讯录同步各有一份可信 IP 列表，部署出口 IP 不在其中就会被拒绝。

**处理**

1. 给 Ankole 部署固定出口 IP，并写入自建应用的“企业可信 IP”。
2. 通讯录同步的可信 IP 单独配置，同样要写入。
3. 确认登录回跳域名已配置为自建应用的可信域名。

#### 企业微信能登录，但同步不到姓名或整个通讯录

**现象**

成员能扫码进入 Console，但主体没有姓名，或通讯录同步为空。

**判断**

自 2022 年 6 月起，普通应用 Secret 拿不到成员姓名等字段。同步必须使用“管理工具 → 通讯录同步”的专用 Secret。

**处理**

1. 在企业微信后台开启通讯录 API 同步，把专用 Secret 填入身份源提供商。
2. 为这个 Secret 配置它自己的可信 IP。
3. 企业微信没有实时目录事件。改动后运行一次全量同步，或等待周期同步。

- [在快速开始中配置企业微信 IdP](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#2-先设置身份源提供商)

## 聊天渠道排错

聊天渠道只负责收取 IM 消息并发回 Agent 的回复。请选择路由规则实际连接的平台；身份源来自哪个平台，不影响这里的选择。

**选择聊天渠道**

- Slack
- Microsoft Teams
- 飞书 / Lark
- 钉钉
- 企业微信

### Slack

#### Slack 路由规则提示 token 前缀错误

**现象**

保存聊天渠道时出现 invalid_token_prefix，连接尚未建立。

**判断**

Bot Token 和 App Token 填反，或使用了不属于这两类的 Slack token。

**处理**

1. Bot Token 必须以 xoxb- 开头，来自 OAuth & Permissions → Bot User OAuth Token。
2. App Token 必须以 xapp- 开头，并带 connections:write。
3. 更正后再保存；在凭证通过检查前，不必排查事件订阅。

#### Slack 私信能回复，频道里 @Agent 却没有反应

**现象**

机器人能处理私信，但频道里的明确 @ 没有进入 Ankole。

**判断**

机器人没加入该频道，或 Slack 应用没有订阅 app_mention 和授予 app_mentions:read。

**处理**

1. 把机器人邀请进测试频道。
2. 在 Event Subscriptions 中加入 app_mention，并确认 app_mentions:read 已生效。
3. scope 改动后重新 Install to Workspace，并更新 Ankole 中的 Bot Token。

#### Slack 只有 @ 消息能到达，普通群消息看不到

**现象**

addressed_only 正常，但切到 observe_all 或 may_intervene 后，Agent 仍只看到明确 @ 的消息。

**判断**

路由规则只决定 Ankole 如何处理已经收到的消息。Slack 应用还没有订阅相应 message 事件，或缺少对应频道的 history scope。

**处理**

1. 先确认 addressed_only 的完整收发链路正常。
2. 按快速开始为目标会话类型添加 message 事件和相应 history scope。
3. 重新安装应用并更新 Token 后，再切换群聊模式。

- [在快速开始中配置 Slack 聊天渠道](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#4-连接聊天渠道并创建信号路由规则)

### Microsoft Teams

#### Teams 中发了消息，Ankole 完全没有收到

**现象**

Teams 没有回复，控制面也没有对应的入站活动记录。

**判断**

Teams 通过 Bot Framework webhook 投递消息。消息端点不是公共 HTTPS、证书不受信任、路径填错，都会让请求到不了 Ankole。

**处理**

1. 确认实例有可从互联网访问的公共 HTTPS 地址和受信任证书。
2. 把 Bot Framework 的 Messaging endpoint 精确设置为快速开始给出的 Teams webhook 地址。
3. 确认机器人应用已安装到测试用户、团队或频道。

#### Teams 消息到了，但回复时报鉴权错误

**现象**

控制面收到活动，随后发送回复时出现 401、403 或 token 获取失败。

**判断**

appID、appPassword、tenantID 或 botTenancy 与 Azure Bot 注册方式不一致。

**处理**

1. 核对 appID 是应用注册的 GUID，appPassword 是仍有效的 Client Secret 值。
2. 单租户应用使用 single_tenant 和自己的 tenantID。
3. 只有 Azure Bot 注册本身允许多租户时，才选择 multi_tenant。

#### Teams 私聊能用，团队频道里 @Agent 没反应

**现象**

同一个机器人能在个人聊天中回复，但频道消息没有进入 Ankole。

**判断**

机器人没有安装到该 team 或频道，或者消息没有按 Teams 的方式明确提及机器人。

**处理**

1. 把应用安装到目标 team，并确认目标频道允许该应用。
2. 第一次测试使用明确 @ 提及，不要先测试未点名消息。
3. 确认路由规则已启用，并指向预期 Agent。

- [在快速开始中配置 Teams 聊天渠道](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#4-连接聊天渠道并创建信号路由规则)

### 飞书 / Lark

#### 飞书机器人已经创建，但任何消息都没有回复

**现象**

私信和群内 @ 都没有进入 Ankole。

**判断**

机器人能力、应用版本、可用范围、长连接或 im.message.receive_v1 中至少有一项尚未生效。

**处理**

1. 确认应用已启用机器人能力，测试用户在可用范围内，并已发布最新版。
2. 在事件与回调中选择长连接，并订阅 im.message.receive_v1。
3. 保持控制面运行，确认它可以主动访问飞书；长连接不需要公共 webhook。

#### 飞书只有 @ 消息能到达，普通群消息看不到

**现象**

addressed_only 正常，但 observe_all 或 may_intervene 仍收不到未 @ 机器人的群消息。

**判断**

飞书应用缺少 im:message.group_msg。路由规则不能读取平台没有投递的消息。

**处理**

1. 先用 addressed_only 验证机器人能收能回。
2. 在权限管理中加入 im:message.group_msg，并发布新版本。
3. 确认应用可用范围覆盖目标群成员后，再切换群聊模式。

#### 飞书能收到消息，但回复或卡片更新失败

**现象**

Agent 已经开始处理，飞书里却没有最终回复，或卡片停在旧状态。

**判断**

聊天应用缺少发消息、更新消息或读取消息资源的权限，或者新版权限尚未发布。

**处理**

1. 按快速开始补齐消息发送、更新与资源权限。
2. 发布应用版本，并确认机器人仍在会话内。
3. 从同一会话重新发一条消息，避免用已经失败的旧回合判断新权限。

- [在快速开始中配置飞书 / Lark 聊天渠道](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#4-连接聊天渠道并创建信号路由规则)

### 钉钉

#### 钉钉群里不 @Agent 就收不到消息，这是故障吗？

**现象**

私信或明确 @ 可以触发 Agent，但普通群消息不会进入 Ankole。

**判断**

不是故障。截至 2026 年 7 月，钉钉只把明确 @ 机器人的群消息交给 Agent，无法提供完整群聊记录。

**处理**

1. 群聊测试必须明确 @Agent，并把群聊模式保持为 addressed_only。
2. 如果 Agent 需要持续理解完整群聊上下文，请优先选择 Slack、Teams 或飞书 / Lark。
3. 不要把路由规则改成 observe_all；平台没有投递的消息无法由 Ankole 补回。

#### 钉钉回复一直是普通 Markdown，怎样才有流式卡片？

**现象**

Agent 可以回复，但消息始终是纯文本，没有边写边显示的 AI 卡片。

**判断**

钉钉卡片是模板托管的。路由规则的 cardTemplateId 为空、模板未发布到机器人所属应用，或钉钉拒绝了卡片内容时，回复保持普通 Markdown。

**处理**

1. 按快速开始钉钉标签页的高级设置搭建 AI 卡片模板，并把模板 id 填进路由规则的 cardTemplateId。
2. 卡片空白时，确认当前输入中、完成或出错布局包含绑定 answer 的 Markdown 组件，并重新发布模板；不要创建 flowStatus 或 flowStatusVar。
3. 同一次回复先卡片后纯文本，是卡片被永久拒绝后的预期降级；回复仍会送达，从控制面日志查 param.contentUnsafe 或 param.cardNotExist。

- [在快速开始中搭建钉钉 AI 卡片模板](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#4-连接聊天渠道并创建信号路由规则)

#### 钉钉 Stream 连接一直没有消息

**现象**

路由规则已启用，但私信和明确 @ 都没有进入 Ankole。

**判断**

Client ID 与 Client Secret 不匹配、机器人未发布或不在可用范围内，都会让 Stream 连接或事件投递失败。

**处理**

1. 核对聊天应用自己的 Client ID 和 Client Secret，不要混用身份源应用的凭证。
2. 确认机器人已启用，应用已发布，测试用户在可用范围内。
3. 确认控制面能主动访问钉钉；Stream 连接不需要公共 webhook。

#### 为什么同一个钉钉应用不能再连接第二个 Agent？

**现象**

第二条路由规则被拒绝，或同一个 Client ID 已被另一位 Agent 使用。

**判断**

当前钉钉适配器要求一个 Client ID 只连接一个 Agent；每个 Agent 也只能有一条启用的钉钉路由。

**处理**

1. 如果第二个 Agent 需要独立机器人身份，请在钉钉创建另一套企业内部应用。
2. 用新应用的 Client ID 和 Client Secret 创建新的路由规则。
3. 如果只是更换目标 Agent，请先停用旧路由，再启用新路由。

### 企业微信

#### 企业微信群里不 @ 机器人就收不到消息，这是故障吗？

**现象**

单聊和明确 @ 可以触发 Agent，普通群消息、群里的图片和文件不会进入 Ankole。

**判断**

不是故障。企业微信只把单聊消息和群里明确 @ 机器人的消息交给智能机器人，群聊 @ 消息也只带文本和图文混排。

**处理**

1. 群聊测试必须明确 @ 机器人；群聊模式只有 addressed_only。
2. 需要完整群聊上下文或群内文件时，请优先选择飞书 / Lark、Slack 或 Teams。

#### Agent 的定时提醒在企业微信里发不出去

**现象**

用户主动发消息能得到回复，但计划任务结果等主动消息没有送达。

**判断**

企业微信要求用户先在该会话给机器人发过消息，Agent 才能主动推送；全新会话无法由 Agent 先发起。

**处理**

1. 让接收人先给机器人发一条消息，解锁该会话的主动推送。
2. 收到消息后的回复窗口是 24 小时；超过后只能走主动推送路径。

#### 企业微信连接反复中断，或聊天身份对不上

**现象**

连接建立后又断开，或聊天用户始终无法与通讯录、登录身份关联。

**判断**

平台强制每个机器人只允许一条长连接，另一个程序用同一 Bot ID 会互相顶掉；非超级管理员创建的机器人，消息里的用户 ID 是加密形态。

**处理**

1. 确认没有其他程序使用同一个 Bot ID。Ankole 被顶掉后会停下等待，不会反复抢线。
2. 机器人必须由企业超级管理员创建；否则删除后用超管账号重建。

- [在快速开始中配置企业微信聊天渠道](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md#4-连接聊天渠道并创建信号路由规则)

## 仍然无法定位时

复现一次问题，记下准确时间、Agent UID、路由规则名称、所用 Provider，以及界面显示的完整错误。然后只截取同一时间附近的控制面和 Worker 日志，先按事件名查找第一处异常。

不要发送 Client Secret、Bot Token、App Token、模型 API Key、完整环境变量或未经遮蔽的配置文件。需要提交问题时，请附上已经遮蔽的日志和复现步骤，而不是整份日志包。

- [怎样阅读 Ankole 日志](https://ankole.agentbull.com/zh-Hans-CN/docs/log-reading/index.md)