跳到正文
Ankole

常见问题与故障排查

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/faq/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

本页聚焦于故障定位,不重复介绍产品概念或第三方平台的完整配置流程。排查时请先找到最早出现的第一处异常,再对照下方对应的身份源或聊天平台标签页处理。完整的部署与首次初始化步骤以 快速开始 为准。

先判断问题在哪一层

你看到的现象 先检查
/setup 或 Console 打不开 部署环境、control-plane、function-runtime、PostgreSQL、域名解析与 HTTPS 证书
Console 或 Pod 能打开,但登录失败或通讯录不完整 企业身份源(IdP SSO)、免密邮箱验证码(SiteCredential,配置于 authn.email.mail)、principals.pod_login_policy 登录策略,以及 siteadmin / pod_admin 管理员组成员关系
Console 内 Agent 对话正常,但某个 IM 平台收不到消息 对应聊天渠道的平台配置与信号路由规则
IM 消息已进入 Ankole,但 Agent 无法生成回复 LLM Provider、Agent 模型档案与 Worker 运行状态
仅某一个外部平台异常 直接查看下方对应平台的排错标签页,切勿照搬其他平台的排查方法

所有平台都会遇到的问题

浏览器连不上 /setup 或 Console,先查什么?

现象
页面超时、拒绝连接、返回 502,或只显示空白页,尚未进入身份源、模型或聊天平台的配置环节。
判断
控制面尚未正常运行,或域名解析、反向代理、Ingress 未把请求正确转发到控制面。后续出现的各类 Provider 报错通常只是连带表现。
处理
  1. 先检查 control-plane、function-runtime、PostgreSQL 和反向代理是否均处于健康状态,并从日志里最早出现的第一处异常查起。
  2. 若绕过代理直接访问控制面正常,再逐一排查域名解析、TLS 证书以及反向代理转发地址。
  3. 切勿为了盲目试错而删除数据库或持久化卷——服务启动失败并不代表底层数据已损坏。

首次设置需要的激活码在哪里?

现象
/setup 页面提示输入激活码,但启动终端已关闭,或日志输出过多找不到对应行。
判断
激活码仅在实例首次初始化阶段有效。一旦首位 siteadmin 站点管理员完成登录,激活码便立即作废,此后应直接访问登录页。
处理
  1. 若尚未完成首次管理员登录,请前往“快速开始”切换至你的部署方式,运行对应标签页给出的日志查询命令。
  2. 在控制面日志中检索 SETUP ACTIVATION CODE,不要从浏览器缓存或数据库记录中猜测激活码。
  3. 若站点已存在 siteadmin(或租户已有 pod_admin)管理员,无需再次激活;请直接通过免密邮箱验证码(SiteCredential,基于 authn.email.mail)或已接入的企业身份源(IdP SSO)登录。

启用了适配器插件,为什么页面里仍看不到对应的 Provider?

现象
插件状态已保存为启用,但初始化向导、身份源列表或信号路由页面中仍不显示对应平台选项。
判断
首次初始化向导会列出全部已编译插件,并按当前保存的勾选结果过滤后续步骤;而初始化完成后在 Console 中修改的插件启停状态,需要等控制面下一次启动时才会加载生效。
处理
  1. 若当前仍在 /setup 向导中,请退回“插件”步骤重新保存选择,再进入下一步,此时无需重启服务。
  2. 若初始化早已完成,请单独重启控制面进程(无需重启 PostgreSQL,更不要清理数据);待启动完毕确认插件已激活后,再回到 Provider 配置页。
  3. 若重启后控制面启动失败,请先根据日志排查插件初始化报错。

所有聊天平台都收不到回复,问题还出在聊天渠道吗?

现象
无论切换频道、改发私信还是换用另一个聊天平台都没有回复,连在 Console 内直接发起的 Agent 对话也一并失败。
判断
只要 Console 原生对话同样失败,故障点通常就在所有渠道共用的下游执行链路——即 LLM Provider、Agent 模型档案或 Worker 实例,而非某个聊天平台的事件订阅权限。
处理
  1. 确认所用的 LLM Provider 已启用,且 API 凭证与模型标识真实可用。
  2. 确认该 Agent 的 primary 档案有效,实际使用的模型档案可正确解析;再检查 Console → 工作节点中对应 Worker 的报错信息。
  3. 先在 Console 内跑通一次真实的模型问答;确认回复正常后,再回到下方对应聊天平台的标签页排查外部消息入口。

计划任务没有按时触发,先查什么?

现象
计划任务已创建完成,但到达预期时间后并未启动,或界面显示的下次运行时间与预期不符。
判断
常见原因包括任务处于停用状态、时区或 Cron 表达式填写有误,或者到达触发时刻时控制面并未运行。
处理
  1. 打开该计划任务,确认开关处于启用状态,并查看界面显示的下次运行时间。
  2. 核对计划任务时区与 Cron 表达式,以界面实际换算出的触发时间为准,不要仅凭表达式心算猜测。
  3. 点击“立即运行”手动触发一次:若手动执行正常,说明问题出在定时规则;若同样失败,继续点开运行记录排查报错。

计划任务显示已运行,为什么群聊或会话里没看到结果?

现象
运行历史中已生成当次执行记录,但目标聊天群或会话并未收到 Agent 发出的消息。
判断
定时触发器本身已正常点火,卡点出在后续执行或投递环节:目标路由规则、聊天渠道凭证、Agent 模型档案或 Worker 实例。
处理
  1. 先点开当次运行记录,确认回合是否成功跑完,并查看最早出现的一条报错。
  2. 核对计划任务绑定的目标 Agent、目标会话或外部聊天渠道,以及对应的信号路由规则是否仍然有效。
  3. 确认该 Agent 的模型档案工作正常,且 Console → 工作节点中的 Worker 处于就绪状态、无失败原因。

身份源提供商排错

单点登录、员工名册与组织架构同步均由身份源提供商(IdP)负责。请先切换至企业实际接入的身份源:Slack 的 Socket Mode、Entra ID 的 Graph 变更订阅与 Google Workspace 的定时全量同步底层机制截然不同,切勿混用排查思路。

Slack 登录在授权回跳时失败

现象
Slack 在跳回 Ankole 前报错 redirect_uri 不匹配,或完成授权后落到了错误页面。
判断
Slack 应用后台登记的 Redirect URL 与 /setup 页面给出的回调地址不完全一致,或 Ankole 中误填了另一个应用的 Client ID。
处理
  1. 直接从 /setup 页面复制完整的回调地址,原样粘贴到 Slack 应用后台的 OAuth & Permissions → Redirect URLs 中。
  2. 逐字核对协议(http/https)、域名、端口、路径及末尾的 Provider ID。
  3. 保存 Slack 配置后从 Ankole 重新发起登录,不要刷新复用之前已打开的旧授权页。

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

现象
管理员可以正常进入 Console,但主体列表或权限组为空,或者看不到新加入的同事。
判断
身份源应用缺少 users:read、users:read.email 或 usergroups:read/team:read 权限,新增权限后未重新安装应用导致 Bot User OAuth Token 未包含新权限,或尚未执行过全量同步。
处理
  1. 对照“快速开始”核查并补齐 Slack 身份源所需的全部权限范围(Scope)。
  2. 每次修改权限范围后,都必须重新点击 Install to Workspace 安装应用,并将新生成的 Bot User OAuth Token 更新回 Ankole 的身份源配置。
  3. 先手动触发并验证一次全量同步;确认全量数据完整后,再排查增量实时同步。

Slack 通讯录能全量同步,但后续人员变动不实时更新

现象
首次全量同步能拉出完整名册,但后续邀请新成员、移除成员或调整用户组后,Ankole 侧没有及时更新。
判断
增量实时同步依赖 Socket Mode 长连接:若未填写 App-Level Token、令牌前缀不是 xapp-、Slack 应用未开启 Socket Mode,或控制面无法连接外网访问 Slack,变更事件都无法送达。
处理
  1. 确认身份源配置中已开启“实时同步通讯录变更”,并填入了有效的 App-Level Token。
  2. 确认 Slack 应用后台已开启 Socket Mode,且控制面所在主机可主动访问公网。
  3. 若轮换过 App-Level Token,请同步更新 Ankole 中保存的值,再观察下一次组织变更是否实时生效。

聊天渠道排错

聊天渠道专门负责接收外部 IM 消息并发回 Agent 的回复。请在下方选择信号路由规则实际连接的聊天平台(与登录采用哪种身份源无关)。

保存 Slack 路由规则时提示令牌前缀错误

现象
保存聊天渠道配置时报错 invalid_token_prefix,Socket Mode 连接尚未建立。
判断
Bot Token 与 App Token 填反了位置,或误填了其他类型的 Slack 令牌。
处理
  1. botToken 必须以 xoxb- 开头,取自 OAuth & Permissions → Bot User OAuth Token。
  2. appToken 必须以 xapp- 开头,取自 Basic Information → App-Level Tokens,且须包含 connections:write 权限。
  3. 修正两项令牌后重新保存;在凭证格式校验通过前,无需去排查事件订阅。

Slack 私聊能正常回复,但在频道里 @Agent 毫无反应

现象
机器人在一对一私信中对答正常,但在公开或私有频道中明确 @ 提及它时,消息没有进入 Ankole。
判断
机器人尚未被邀请进该频道,或者 Slack 应用漏订了 app_mention 事件、漏授了 app_mentions:read 权限。
处理
  1. 先将该机器人邀请加入目标测试频道。
  2. 在 Slack 应用后台的 Event Subscriptions 中添加 app_mention,并确认 Bot Token Scopes 中已包含 app_mentions:read。
  3. 若补充过权限范围(Scope),请重新执行 Install to Workspace,并将更新后的 Bot Token 填回 Ankole。

Slack 频道里只有 @ 消息能收到,普通群聊消息看不到

现象
addressed_only 模式工作正常,但将群聊策略切换为 observe_all 或 may_intervene 后,Agent 依然只能收到明确 @ 它的发言。
判断
Ankole 的群聊路由策略只能处理已经送达控制面的消息;若 Slack 应用尚未订阅对应会话类型的 message.* 事件,或缺少配套的 *:history 权限,Slack 根本不会推送未 @ 机器人的普通发言。
处理
  1. 先在 addressed_only 模式下确认基础收发链路完全畅通。
  2. 对照“快速开始”为目标频道类型补齐 message.channels / message.groups 等事件及对应的 history 权限。
  3. 重新安装 Slack 应用并更新 Bot Token 后,再将路由规则切换为所需的群聊模式。

仍然无法定位时

请重新复现一次问题,记录准确的触发时间、Agent UID、路由规则名称、所涉及的 Provider,以及界面提示的完整报错文本;随后仅截取该时间点前后的控制面与 Worker 日志,顺着事件名定位最早出现的第一条异常记录。

求助或提交 Issue 时,切勿附带任何 Client Secret、Bot Token、App Token、模型 API Key、完整环境变量导出或未脱敏的配置文件;请只提供脱敏后的关键日志片段与可复现步骤,不要直接上传整包原始日志。