FAQ 与故障排查

先查错误码速查表，再按症状对号入座。都没命中？在应用设置里确认配置，或联系你的组织管理员。

错误码速查（开放 API）

状态码	直接原因	自查
400	参数校验失败 / authCode 无效、已使用或过期	核对参数约束；authCode 只能用一次、5 分钟过期，刷新页面会失效——让页面用 `jlt.requestAuthCode()` 换新码
401	token 缺失/过期；`app_key`/`app_secret` 不对；密钥已轮换；应用停用/组织解散	401 后丢弃缓存的 token 重新获取再重试一次；确认 secret 是最新（轮换后旧的立即失效）
402	AI 能力：应用所属组织未开通钱包	找发布方组织管理员充值开通（不是安装方）
403	scope 未授予 / 目标组织未安装 / 知识库未绑定 / 来源 IP 不在白名单	看 detail 文案：scope 找对应组织管理员开；IP 则检查后端出口 IP 是否进了白名单
404	组织/团队/应用不存在或不属于目标组织	核对 id；团队必须属于 `org_id` 指定的组织
429	触发限流	按退避重试；对照限流表排查是否有循环调用
502	上游模型调用失败	稍后重试；持续出现联系平台方
503	通知账号暂不可用（`im/send`）	稍后重试

免登相关

刷新页面后登录失败（400 authCode 无效） authCode 是一次性的，URL 上那枚在首次登录时已被消费。正确做法见完整示例：用完即从地址栏清掉，会话失效时用 jlt.requestAuthCode() 取新码重新登录。

换到的用户身份里 org_role 是什么？ 打开应用时所在组织的角色（owner/admin/member）。自建应用恒为应用所属组织；市场应用为安装方组织。应用要区分"管理员才能审批"就是看这个字段。

能力（scope）相关

明明应用申请了 contacts，为什么 403？ 两种情况：① 调用时传了安装方组织的 org_id——市场应用需要安装方管理员 在「权限」里单独授予（安装 ≠ 授权）； ② 自建应用则是管理员后来在设置里把勾去掉了。

AI 计费扣谁的组织积分？ 恒定扣应用所属（发布方）组织的钱包，跟谁在用、哪个组织安装无关。所以 ai 能力不看安装方授权，只看应用自身申请。

JSAPI 相关

所有调用 15 秒后超时 reject 页面不在机灵兔客户端里打开（普通浏览器直接访问）。先判断再降级：

if (window.jlt) { /* 在客户端里 */ } else { /* 普通网页模式 */ }

移动端页面里调 JSAPI 没反应 确认引入的是平台下发的 <script src="…/api/open/jsapi/jlt.js">（v1.2+ 才支持移动容器），并按文档在 jlt.ready 之后再发起调用（见平台差异）。

localFetch/browserExtract 报"应用未被授予本地能力" 组织管理员在应用设置「开放能力」里勾选本地能力（市场应用还需安装方在「权限」里授予）。注意本地能力仅桌面端，且每次调用都会弹窗请用户确认目标地址——用户拒绝也是这个报错路径，别把"没授权"和"用户点了拒绝"混为一谈。

browserExtract 失败提示浏览器/Node 相关错误 无头浏览器依赖桌面端的本地运行时（Node + Playwright）。让用户在客户端「设置 → 环境检查」一键准备后重试；简单页面优先用 localFetch（无依赖、更快）。

AI 工具相关

注册工具时"回调地址验证失败" 和事件订阅同一套 challenge 验证：端点要对 {"type":"url_verification","challenge":"…"} 原样回显并返回 200。curl 自测：

bash

curl -s https://your-backend/jlt/tools -H 'Content-Type: application/json' \
  -d '{"type":"url_verification","challenge":"abc"}'
# 期待 → {"challenge":"abc"}

模型调用工具一直超时 回调等待是工具注册时配的秒数（5–60）——检查你的端点是否同步做了重活（应该秒回结果，慢逻辑丢队列）；工具端点和事件端点可以共用验签代码但路径分开部署 更稳。

数据库查询返回"仅允许 SELECT 查询" 这是设计行为：db 能力永远只读（单条 SELECT/WITH、禁写关键字、行数上限、语句超时），写操作请走你自己系统的接口。

成员说"AI 不知道我的工具" 工具只在对话请求时按组织解析：确认应用勾了 ai_tools、工具未停用、该成员属于组织（自建 = 应用组织；市场 = 授予了 ai_tools 的安装方组织）。

事件订阅相关

保存回调地址时验证失败 端点必须对 {"type":"url_verification","challenge":"…"} 原样回显 challenge 并返回 200。用 curl 自测：

bash

curl -s http://localhost:3000/jlt/events \
  -H 'Content-Type: application/json' \
  -d '{"type":"url_verification","challenge":"abc"}'
# 期待 → {"challenge":"abc"}

之前能收到事件，突然收不到了 在应用设置看「待投递 N · 失败 N」：端点最近是否 5xx/超时（防火墙、发布、改路由）？修好后点**「重投失败事件」**补投。注意验证失败/重试耗尽的旧事件不会自动补发。

怎么确认事件是真的来自平台？ 验签：HmacSHA256(app_secret, "<X-Jlt-Timestamp>.<原始请求体>") 与 X-Jlt-Signature 常量时间比对，并拒绝时间戳过老的请求。完整代码见事件订阅 §4。

AI 对话组件（mountChat）相关

组件报 HTTP 502 你的后端中继没通或上游报错——看中继日志；Demo 的 /api/chat 直接透传平台错误体（截断到 300 字符），先确认 JLT_BASE/JLT_APP_KEY/JLT_APP_SECRET 环境变量都对。

组件报 HTTP 402 应用所属组织未开通钱包（ai 能力计费走你的组织钱包）——找组织管理员充值开通。

回复不逐字出现（一次性整段） 后端中继把 SSE 缓冲了（nginx 默认缓冲会攒满才发）。给中继响应加 X-Accel-Buffering: no（Demo 的代码已带），或确认代理链路没有 proxy_buffering on。

刷新后历史丢了 检查持久化接对了没有（存哪里）； IndexedDB 在隐私模式/被策略禁用时会静默降级为不存，属预期行为。

本地调试

页面地址/回调地址可以用 http 吗？ 仅 http://localhost / http://127.0.0.1 放行（开发调试）；正式环境与上架市场强制 https。注意：回调地址填的是你后端的地址，跟页面地址是两回事。

客户端内嵌的页面怎么调试？ DevTools 不方便用，建议：后端逻辑先用 curl/单测验证；页面侧加 console.log 后重新打开应用观察；免登失败时先看 URL 上是否带 jlt_auth_code 参数。

FAQ 与故障排查 ​

错误码速查（开放 API） ​

免登相关 ​

能力（scope）相关 ​

JSAPI 相关 ​

AI 工具相关 ​

事件订阅相关 ​

AI 对话组件（mountChat）相关 ​

本地调试 ​