常见问题与故障排查
这不是产品介绍，也不重复第三方平台的完整配置步骤。请先找到最早出现的异常，再选择对应的身份源或聊天平台。完整安装与首次设置仍以快速开始为准。
先判断问题在哪一层
| 你看到的现象 | 先检查 |
|---|---|
/setup 或 Console 打不开 |
部署、控制面、域名与 HTTPS |
| Console 能打开，但登录失败或通讯录不完整 | 身份源提供商（IdP） |
| Console 中 Agent 能对话，但某个 IM 没有消息 | 该聊天渠道与信号路由 |
| IM 消息已经进入 Ankole，但 Agent 无法生成回复 | LLM Provider、模型档案与 Worker |
| 只有一个平台有问题 | 直接选择下方对应 Provider，不要照搬另一平台的处理办法 |
所有平台都会遇到的问题
首次设置需要的 activation code 在哪里？
- 现象
- /setup 要求输入 activation code，但启动终端已经关闭，或者日志太多，找不到那一行。
- 判断
- 控制面只在首次设置阶段使用这个 code。第一位管理员完成登录后，code 会失效，此后应直接打开 Console 登录页。
- 处理
- 尚未完成首次登录时，到快速开始中选择自己的部署方式，运行该标签页给出的日志命令。
- 搜索 SETUP ACTIVATION CODE，不要从浏览器缓存或数据库中猜测 code。
- 如果实例已经有 Root 管理员，不要重新激活；请使用已经配置的身份源登录。
启用了适配器，为什么 Console 里仍看不到对应的 Provider？
- 现象
- Control Plane Plugin 已保存为启用，但身份源或信号路由页面里仍没有对应选项。
- 判断
- 插件清单在控制面启动时加载。保存只安排下一次启动要启用的插件，不会在当前进程里动态加入新的后台任务和配置项。
- 处理
- 只重启控制面，不要删除数据，也不必重启 PostgreSQL。
- 控制面重新启动后，确认插件处于已激活状态，再回到 Provider 页面。
- 如果控制面启动失败，先处理日志中的插件初始化错误。
所有聊天平台都收不到回复，问题还在聊天渠道吗？
- 现象
- 换了频道、私信或另一个聊天应用都没有回复，Console 中直接发起的 Agent 对话也失败。
- 判断
- 如果 Console 对话也失败，问题通常在所有聊天渠道共用的后半段：LLM Provider、Agent 模型档案或 Worker，而不是某个平台的事件权限。
- 处理
- 确认 LLM Provider 已启用，凭证和模型名称可用。
- 确认 Agent 已配置 primary、light 和 heavy，并且至少有一个 Worker 显示为 ready。
- 先在 Console 中完成一次真实模型对话；成功后，再回到所选聊天平台的标签页排查消息入口。
计划任务没有按时运行，先查什么？
- 现象
- 计划任务已创建，但到了预期时间没有开始，或下一次运行时间与预期不一致。
- 判断
- 常见原因是任务未启用、时区或 Cron 表达式不正确，或者控制面在触发时没有运行。
- 处理
- 打开计划任务，确认它已启用，并核对页面显示的下一次运行时间。
- 核对实例时区和 Cron 表达式。先看页面换算出的时间，不要只凭表达式猜测。
- 选择“立即运行”。如果可以运行，问题在时间设置；如果仍失败，继续查看运行记录。
计划任务显示已运行，为什么聊天里没有结果？
- 现象
- 运行记录已经出现，但目标聊天或会话没有收到 Agent 的消息。
- 判断
- 触发器已经工作，问题在后续链路：目标路由、聊天渠道、Agent 模型或可用 Worker。
- 处理
- 先打开这次运行记录，确认任务是否成功，并读取最早的错误。
- 核对任务指向的 Agent、会话或聊天目标，以及对应的信号路由规则。
- 确认 Agent 的模型档案可用，并且至少有一个 Worker 处于就绪状态。
身份源提供商排错
登录、通讯录和组织架构同步由 IdP 负责。先选择企业实际使用的身份源。Slack 的 Socket Mode、Entra ID 的 Graph 订阅、Google Workspace 的全量同步并不是同一种机制，不能混着排查。
Slack 登录在授权跳转处失败
- 现象
- Slack 在回到 Ankole 之前提示 redirect_uri 不匹配，或授权后回到错误页面。
- 判断
- Slack 应用登记的 Redirect URL 与 /setup 显示的回调地址不完全相同，或 Ankole 中填了另一套 Client ID。
- 处理
- 从 /setup 复制完整回调地址，原样加入 Slack 的 OAuth & Permissions → Redirect URLs。
- 逐字核对协议、域名、端口、路径和 Provider ID。
- 保存 Slack 配置后重新发起登录，不要复用旧的授权页。
Slack 登录成功，但同步不到成员或用户组
- 现象
- 管理员能进入 Console，但主体或权限组列表为空，或者缺少新成员。
- 判断
- 身份源应用缺少 users:read、users:read.email 或 team:read，Bot Token 没带上新增权限，或全量同步尚未运行。
- 处理
- 按快速开始补齐身份源所需权限。
- Slack scope 改动后重新 Install to Workspace，并把新的 Bot Token 写回身份源提供商。
- 先验证一次全量同步；只有全量正常后，才继续排查实时同步。
Slack 名册能全量同步，但后续变更不实时更新
- 现象
- 首次同步有数据，但邀请、移除成员或调整用户组后，Ankole 没有及时变化。
- 判断
- 实时同步依赖 Socket Mode。App Token 缺失、前缀不是 xapp-、Socket Mode 未启用，或控制面不能访问 Slack。
- 处理
- 确认身份源提供商启用了实时同步，并填入有效的 App Token。
- 确认 Slack 应用已启用 Socket Mode，控制面可以主动访问互联网。
- 改过 App Token 后更新 Ankole 中的值，再观察下一次目录变更。
聊天渠道排错
聊天渠道只负责收取 IM 消息并发回 Agent 的回复。请选择路由规则实际连接的平台；身份源来自哪个平台，不影响这里的选择。
Slack 路由规则提示 token 前缀错误
- 现象
- 保存聊天渠道时出现 invalid_token_prefix，连接尚未建立。
- 判断
- Bot Token 和 App Token 填反，或使用了不属于这两类的 Slack token。
- 处理
- Bot Token 必须以 xoxb- 开头，来自 OAuth & Permissions → Bot User OAuth Token。
- App Token 必须以 xapp- 开头，并带 connections:write。
- 更正后再保存；在凭证通过检查前，不必排查事件订阅。
Slack 私信能回复，频道里 @Agent 却没有反应
- 现象
- 机器人能处理私信，但频道里的明确 @ 没有进入 Ankole。
- 判断
- 机器人没加入该频道，或 Slack 应用没有订阅 app_mention 和授予 app_mentions:read。
- 处理
- 把机器人邀请进测试频道。
- 在 Event Subscriptions 中加入 app_mention，并确认 app_mentions:read 已生效。
- scope 改动后重新 Install to Workspace，并更新 Ankole 中的 Bot Token。
Slack 只有 @ 消息能到达，普通群消息看不到
- 现象
- addressed_only 正常，但切到 observe_all 或 may_intervene 后，Agent 仍只看到明确 @ 的消息。
- 判断
- 路由规则只决定 Ankole 如何处理已经收到的消息。Slack 应用还没有订阅相应 message 事件，或缺少对应频道的 history scope。
- 处理
- 先确认 addressed_only 的完整收发链路正常。
- 按快速开始为目标会话类型添加 message 事件和相应 history scope。
- 重新安装应用并更新 Token 后，再切换群聊模式。
仍然无法定位时
复现一次问题，记下准确时间、Agent UID、路由规则名称、所用 Provider，以及界面显示的完整错误。然后只截取同一时间附近的控制面和 Worker 日志，先按事件名查找第一处异常。
不要发送 Client Secret、Bot Token、App Token、模型 API Key、完整环境变量或未经遮蔽的配置文件。需要提交问题时，请附上已经遮蔽的日志和复现步骤，而不是整份日志包。