常见问题与故障排查
面向 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 报错通常只是连带表现。
- 处理
- 先检查 control-plane、function-runtime、PostgreSQL 和反向代理是否均处于健康状态,并从日志里最早出现的第一处异常查起。
- 若绕过代理直接访问控制面正常,再逐一排查域名解析、TLS 证书以及反向代理转发地址。
- 切勿为了盲目试错而删除数据库或持久化卷——服务启动失败并不代表底层数据已损坏。
首次设置需要的激活码在哪里?
- 现象
- /setup 页面提示输入激活码,但启动终端已关闭,或日志输出过多找不到对应行。
- 判断
- 激活码仅在实例首次初始化阶段有效。一旦首位 siteadmin 站点管理员完成登录,激活码便立即作废,此后应直接访问登录页。
- 处理
- 若尚未完成首次管理员登录,请前往“快速开始”切换至你的部署方式,运行对应标签页给出的日志查询命令。
- 在控制面日志中检索 SETUP ACTIVATION CODE,不要从浏览器缓存或数据库记录中猜测激活码。
- 若站点已存在 siteadmin(或租户已有 pod_admin)管理员,无需再次激活;请直接通过免密邮箱验证码(SiteCredential,基于 authn.email.mail)或已接入的企业身份源(IdP SSO)登录。
启用了适配器插件,为什么页面里仍看不到对应的 Provider?
- 现象
- 插件状态已保存为启用,但初始化向导、身份源列表或信号路由页面中仍不显示对应平台选项。
- 判断
- 首次初始化向导会列出全部已编译插件,并按当前保存的勾选结果过滤后续步骤;而初始化完成后在 Console 中修改的插件启停状态,需要等控制面下一次启动时才会加载生效。
- 处理
- 若当前仍在 /setup 向导中,请退回“插件”步骤重新保存选择,再进入下一步,此时无需重启服务。
- 若初始化早已完成,请单独重启控制面进程(无需重启 PostgreSQL,更不要清理数据);待启动完毕确认插件已激活后,再回到 Provider 配置页。
- 若重启后控制面启动失败,请先根据日志排查插件初始化报错。
所有聊天平台都收不到回复,问题还出在聊天渠道吗?
- 现象
- 无论切换频道、改发私信还是换用另一个聊天平台都没有回复,连在 Console 内直接发起的 Agent 对话也一并失败。
- 判断
- 只要 Console 原生对话同样失败,故障点通常就在所有渠道共用的下游执行链路——即 LLM Provider、Agent 模型档案或 Worker 实例,而非某个聊天平台的事件订阅权限。
- 处理
- 确认所用的 LLM Provider 已启用,且 API 凭证与模型标识真实可用。
- 确认该 Agent 的 primary 档案有效,实际使用的模型档案可正确解析;再检查 Console → 工作节点中对应 Worker 的报错信息。
- 先在 Console 内跑通一次真实的模型问答;确认回复正常后,再回到下方对应聊天平台的标签页排查外部消息入口。
计划任务没有按时触发,先查什么?
- 现象
- 计划任务已创建完成,但到达预期时间后并未启动,或界面显示的下次运行时间与预期不符。
- 判断
- 常见原因包括任务处于停用状态、时区或 Cron 表达式填写有误,或者到达触发时刻时控制面并未运行。
- 处理
- 打开该计划任务,确认开关处于启用状态,并查看界面显示的下次运行时间。
- 核对计划任务时区与 Cron 表达式,以界面实际换算出的触发时间为准,不要仅凭表达式心算猜测。
- 点击“立即运行”手动触发一次:若手动执行正常,说明问题出在定时规则;若同样失败,继续点开运行记录排查报错。
计划任务显示已运行,为什么群聊或会话里没看到结果?
- 现象
- 运行历史中已生成当次执行记录,但目标聊天群或会话并未收到 Agent 发出的消息。
- 判断
- 定时触发器本身已正常点火,卡点出在后续执行或投递环节:目标路由规则、聊天渠道凭证、Agent 模型档案或 Worker 实例。
- 处理
- 先点开当次运行记录,确认回合是否成功跑完,并查看最早出现的一条报错。
- 核对计划任务绑定的目标 Agent、目标会话或外部聊天渠道,以及对应的信号路由规则是否仍然有效。
- 确认该 Agent 的模型档案工作正常,且 Console → 工作节点中的 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 中。
- 逐字核对协议(http/https)、域名、端口、路径及末尾的 Provider ID。
- 保存 Slack 配置后从 Ankole 重新发起登录,不要刷新复用之前已打开的旧授权页。
Slack 登录成功,但同步不到成员或用户组
- 现象
- 管理员可以正常进入 Console,但主体列表或权限组为空,或者看不到新加入的同事。
- 判断
- 身份源应用缺少 users:read、users:read.email 或 usergroups:read/team:read 权限,新增权限后未重新安装应用导致 Bot User OAuth Token 未包含新权限,或尚未执行过全量同步。
- 处理
- 对照“快速开始”核查并补齐 Slack 身份源所需的全部权限范围(Scope)。
- 每次修改权限范围后,都必须重新点击 Install to Workspace 安装应用,并将新生成的 Bot User OAuth Token 更新回 Ankole 的身份源配置。
- 先手动触发并验证一次全量同步;确认全量数据完整后,再排查增量实时同步。
Slack 通讯录能全量同步,但后续人员变动不实时更新
- 现象
- 首次全量同步能拉出完整名册,但后续邀请新成员、移除成员或调整用户组后,Ankole 侧没有及时更新。
- 判断
- 增量实时同步依赖 Socket Mode 长连接:若未填写 App-Level Token、令牌前缀不是 xapp-、Slack 应用未开启 Socket Mode,或控制面无法连接外网访问 Slack,变更事件都无法送达。
- 处理
- 确认身份源配置中已开启“实时同步通讯录变更”,并填入了有效的 App-Level Token。
- 确认 Slack 应用后台已开启 Socket Mode,且控制面所在主机可主动访问公网。
- 若轮换过 App-Level Token,请同步更新 Ankole 中保存的值,再观察下一次组织变更是否实时生效。
聊天渠道排错
聊天渠道专门负责接收外部 IM 消息并发回 Agent 的回复。请在下方选择信号路由规则实际连接的聊天平台(与登录采用哪种身份源无关)。
保存 Slack 路由规则时提示令牌前缀错误
- 现象
- 保存聊天渠道配置时报错 invalid_token_prefix,Socket Mode 连接尚未建立。
- 判断
- Bot Token 与 App Token 填反了位置,或误填了其他类型的 Slack 令牌。
- 处理
- botToken 必须以 xoxb- 开头,取自 OAuth & Permissions → Bot User OAuth Token。
- appToken 必须以 xapp- 开头,取自 Basic Information → App-Level Tokens,且须包含 connections:write 权限。
- 修正两项令牌后重新保存;在凭证格式校验通过前,无需去排查事件订阅。
Slack 私聊能正常回复,但在频道里 @Agent 毫无反应
- 现象
- 机器人在一对一私信中对答正常,但在公开或私有频道中明确 @ 提及它时,消息没有进入 Ankole。
- 判断
- 机器人尚未被邀请进该频道,或者 Slack 应用漏订了 app_mention 事件、漏授了 app_mentions:read 权限。
- 处理
- 先将该机器人邀请加入目标测试频道。
- 在 Slack 应用后台的 Event Subscriptions 中添加 app_mention,并确认 Bot Token Scopes 中已包含 app_mentions:read。
- 若补充过权限范围(Scope),请重新执行 Install to Workspace,并将更新后的 Bot Token 填回 Ankole。
Slack 频道里只有 @ 消息能收到,普通群聊消息看不到
- 现象
- addressed_only 模式工作正常,但将群聊策略切换为 observe_all 或 may_intervene 后,Agent 依然只能收到明确 @ 它的发言。
- 判断
- Ankole 的群聊路由策略只能处理已经送达控制面的消息;若 Slack 应用尚未订阅对应会话类型的 message.* 事件,或缺少配套的 *:history 权限,Slack 根本不会推送未 @ 机器人的普通发言。
- 处理
- 先在 addressed_only 模式下确认基础收发链路完全畅通。
- 对照“快速开始”为目标频道类型补齐 message.channels / message.groups 等事件及对应的 history 权限。
- 重新安装 Slack 应用并更新 Bot Token 后,再将路由规则切换为所需的群聊模式。
仍然无法定位时
请重新复现一次问题,记录准确的触发时间、Agent UID、路由规则名称、所涉及的 Provider,以及界面提示的完整报错文本;随后仅截取该时间点前后的控制面与 Worker 日志,顺着事件名定位最早出现的第一条异常记录。
求助或提交 Issue 时,切勿附带任何 Client Secret、Bot Token、App Token、模型 API Key、完整环境变量导出或未脱敏的配置文件;请只提供脱敏后的关键日志片段与可复现步骤,不要直接上传整包原始日志。