文档中心
费用中心控制台

排查智能体实例运行问题 ​

连接 AI 助手

排查智能体开发服务平台（AgentWorks）的运行问题时，从用户看到的症状开始，按智能体实例、访问方式、能力资源和外部服务逐层检查。

如果问题是控制台中看不到资源，或操作时提示没有权限，先按排查权限问题检查成员授权。智能体调用 API 的鉴权问题则按API 调用返回未授权检查接入 Token。

调用后智能体实例仍未启动 ​

重要

仅限 AgentWorks 平台配置后台

确认和调整租户的沙箱规格分配，需要进入独立的平台配置后台。沙箱规格列表为空时，请让有后台权限的管理员检查资源分配；普通能力资源不可见或操作被拒绝时，先检查成员的访问控制策略。

创建实例后，打开 网页版对话，或通过已配置的 API 接口、飞书或 QQ 渠道发起一次无副作用的测试调用。平台会按需启动实例；调用失败，并且刷新实例列表后仍显示 待启动 时，再按以下步骤排查。

  1. 检查来源智能体模板是否仍存在。
  2. 检查模型凭证和模型是否可用。
  3. 检查所有必填实例参数。
  4. 检查引用的资源是否仍存在，以及当前账号是否有相应的访问权限。权限不足时，按排查权限问题检查授权。
  5. 检查沙箱规格和环境是否分配给租户。
  6. 检查 MCP、知识库组和技能组实例的配置与可用状态。
  7. 向部署管理员提供实例 ID、发生时间和页面错误信息，请其继续检查平台日志。

先定位第一个实例的创建或启动错误，再决定是否重新创建。

网页版对话无法连接 ​

  • 从控制台侧边栏打开 网页版对话，并在输入框旁选择目标实例。
  • 首次连接可能需要启动实例，请稍等片刻后刷新 网页版对话 并观察连接状态。
  • 刷新实例列表；调用后仍显示 待启动 时，按调用后智能体实例仍未启动继续检查。
  • 检查浏览器网络请求。
  • 检查智能体实例是否刚被重新配置。
  • 如果实例因平台维护或故障中断，在服务恢复后重新连接 网页版对话，再发送一次无副作用的测试请求。

API 调用返回未授权 ​

调用 API 使用绑定 WebSocket 渠道账号的 wst_ Token。按以下顺序检查：

  1. 确认使用管理员提供的 HTTP 与 WebSocket 地址。
  2. 确认 Token 绑定正确的渠道账号，账号和 Token 均可用且未过期。
  3. HTTP 请求使用 Authorization: Bearer ＜token＞；WebSocket 按握手鉴权提供 Token，不支持通过 auth 帧或 URL 传递 Token。
  4. 核对反向代理是否保留鉴权头与 WebSocket 子协议。

需要迁移旧调用方时，参见迁移旧版智能体接入。

同一会话无法继续 ​

先保存原请求的 user_id、chat_id、msg_id、会话 context_key 和最近事件帧的外层 seq：

  • 仍有 pending：根据中断类型，通过 RespondInterrupt 返回决定、输入或工具结果。
  • 事件流断开：重新建立连接，带保存的外层 seq 重新订阅并确认成功，再核对补收的事件；不要直接重发原消息。
  • 收到 reset：原游标已失效，可能是历史超出保留范围，也可能是游标与服务端现有记录不匹配。查询历史与待处理中断，暂存恢复期间收到的事件，再合并、去重；游标缺失时按 0 处理，不需要每次都重新订阅。具体步骤见心跳、重连与补偿。
  • 原运行是否完成不明：检查主智能体生命周期、Trace 和外部系统结果，再决定取消或继续。

运行结束、取消和清空对话上下文是不同操作。参见管理会话和中断。

长会话变慢或接近上下文上限 ​

  1. 判断后续任务是否仍需参考原对话。不需要时，网页版对话选择 开启新对话，或在支持命令的渠道发送 /session new。
  2. 需要继续原会话时，在智能体模板中开启 启用压缩。
  3. 编辑并保存测试智能体实例，使其采用新配置；不要仅保存模板。
  4. 减少工具返回中不必要的长文本，并用同一组长会话检查事实保留、工具连续性、延迟和 Token 用量。

支持命令的渠道还可以使用 /compact 请求智能体压缩当前上下文，是否执行须核对本轮结果；压缩不删除留存历史，也不代替长期记忆。参见在长会话中启用压缩。

已创建能力资源，但智能体没有使用 ​

  1. 打开来源智能体模板的 插件 页签。
  2. 确认列表中存在预期插件，并核对类型、名称和资源 ID。
  3. 如果缺少关联，编辑智能体模板，在 插件配置 中单击 添加插件，选择目标模板或实例并保存。
  4. 如果智能体模板已经更新，编辑并保存目标智能体实例，使其使用最新配置。
  5. 发送能明确触发该能力的测试输入，并在 Trace 或相应运行记录中确认实际使用的资源。

能力资源存在、插件关联已经保存和运行时实际使用是三个不同检查点，应依次确认。

排查 Skill 选择、版本、资源和执行 ​

先在 Trace 中判断问题停在哪个阶段，再检查对应配置。没有选择 Skill、使用错误版本、无法读取相关资源和缺少执行能力是四类不同问题。

智能体没有读取 Skill 说明 ​

智能体能列出 Skill 名称，不代表已经读到完整说明。没有读取目标 SKILL.md 时，先检查关联和读取工具，再检查任务是否匹配。

  1. 打开来源智能体模板的 插件 页签，确认存在目标技能组。
  2. 检查技能组选择了目标 Skill 和预期版本。
  3. 编辑来源智能体模板，在 文件系统 中确认 启用文件系统 已开启，并且选中了 read_file。只需读取 Skill 和参考文件时，建议选择 仅只读。
  4. 保存智能体模板，再创建或更新测试智能体实例，确保它采用技能组和文件工具配置。
  5. 检查目标 Skill 的名称和描述是否明确说明适用任务，并确认没有与同一技能组中的其他 Skill 高度重叠。
  6. 使用必须依赖该 Skill 才能正确完成的输入进行测试。
  7. 在 Trace 中检查 read_file 是否成功读取目标 SKILL.md，核对实际内容以及后续工具调用。

使用不会触发目标 Skill 的输入再次测试，确认智能体不会在无关请求中激活它。

Skill 激活后使用了错误版本 ​

  1. 检查技能组为目标 Skill 选择的是明确版本还是 latest。
  2. 需要验证特定版本时，选择明确版本号，不要依赖可能变化的 latest。
  3. 创建或更新测试智能体实例，使版本选择进入最新运行配置。
  4. 使用只存在于目标版本中的短语、步骤或样例测试。
  5. 分别核对智能体读取的说明和沙箱挂载的文件版本。技能组选定版本不能保证两条路径统一锁定；不一致时停止发布，参见Skill 版本验证。

Skill 已激活但资源读取失败 ​

先确认 SKILL.md 已经成功读取，再检查它引用的文件；如果只是能列出 Skill 名称，按智能体没有读取 Skill 说明检查文件系统和 read_file 配置。

  1. 确认所选版本的 SKILL.md 明确引用了需要读取的文件。
  2. 核对相对路径、文件名大小写和目录层级是否与所选版本中的文件一致。
  3. 在 Trace 中核对 read_file 的读取路径、实际内容和错误。
  4. 如果 SKILL.md 已经包含完成任务所需的全部信息，不应仅因没有额外的资源读取调用就判断 Skill 失败。

Skill 内容已加载但操作没有执行 ​

Skill 中的脚本不会因为资源被读取或挂载而自动执行。任务还需要执行命令、脚本或外部操作时：

  1. 确定应由沙箱、MCP、平台工具包还是用户工具包执行目标操作。

  2. 确认智能体模板已经关联所需能力，并且智能体实例使用最新配置。

  3. 需要沙箱执行时，按关联方式检查文件：

    • 同时使用技能组和 沙箱 - 模板：列出 /skills，找到目标 Skill 和所选版本中的文件。
    • 使用 沙箱 - 实例：列出 /skills，核对该智能体所选版本的文件。

    注意

    检查 Skill 文件是否被其他智能体覆盖

    共享沙箱只有一个 /skills 目录，后接入的智能体可能覆盖先前挂上的文件。需要不同 Skill 集合的智能体不能复用该实例，应改用 沙箱 - 模板。

  4. 确认沙箱具备所需运行时和依赖，并把输出写到可写工作目录。

  5. 使用低风险输入显式调用预期工具或命令。

  6. 在 Trace 和相应执行记录中分别核对工具调用与输出。

Skill 或技能组的版本选择刚发生变化时，先更新或重新创建非生产智能体实例并再次核对实际文件，再更新生产实例。

如果 Skill 使用正常但目标操作失败，应从相应工具的身份、权限、文件、运行时、依赖或网络限制继续排查。不要把 Skill 资源读取当作操作已经执行的证明。参见为 Skill 配置执行能力。

MCP 工具不可用 ​

先确认问题出在建立连接、读取工具列表，还是实际执行工具：

  1. 在 MCP 实例中选择 测试连接。失败时检查 Server URL、TLS 和 Headers。
  2. 连接成功后，查看 工具列表。列表加载失败或缺少工具时，检查 MCP Server 是否提供该工具，以及凭证是否允许读取工具列表。
  3. 工具已列出但智能体没有调用时，检查智能体模板的 MCP 引用、工具权限规则、待处理中断，以及实例是否已应用最新配置。
  4. 已发起调用但失败或超时时，在 Trace 和 MCP Server 日志中核对工具参数、业务权限、处理时间及返回结果，再检查 MCP 实例的 超时（秒）。

连接测试成功不代替真实工具调用验证。超时后准备重试写入、发送或删除类操作时，先到外部系统确认上次操作是否已经完成，避免重复执行。

沙箱回收后 MCP 工具返回 unknown tool ​

已关联沙箱的 MCP 工具连接在沙箱被回收并重新创建后，复用原 MCP 会话可能返回 unknown tool。看到平台诊断信息后，请继续按以下步骤重新建立工具连接并验证恢复结果。

  1. 停止继续使用原工具连接，不要盲目重试可能产生副作用的操作。
  2. 记录智能体实例 ID、沙箱资源 ID、工具名称、会话或调用任务 ID、发生时间和原始错误。
  3. 重新初始化或重新建立工具连接。只有已经确认当前接入路径会为新建会话建立全新工具连接时，才把新建会话作为恢复方式；否则重启非生产测试实例后再次加载工具列表。无法确认或仍然失败时，停止调用并联系平台支持。
  4. 在 Trace、沙箱运行记录 和 MCP Server 日志中核对原调用是否已经产生副作用。
  5. 使用无副作用的只读调用确认工具重新可用，再恢复生产请求。

不要把观察到的回收间隔写成固定 SLA。问题反复出现时，把上述关联 ID 和时间交给平台支持定位。

知识库回答缺少资料 ​

  • 确认资料已进入目标集合。
  • 检查最近入库任务并选择 日志。
  • 确认知识库组包含目标集合。
  • 检查智能体实例实际引用的组实例。
  • 调整并测试 top_k。
  • 用 Trace 确认是否发生检索。

沙箱执行失败 ​

  • 检查 沙箱运行记录。
  • 确认规格和环境匹配 Docker 或虚拟机类型。
  • 检查资源、超时和空闲回收。
  • 检查环境变量实例参数。
  • 检查 DNS、私网访问和带宽策略。
  • 检查工具调用是否被权限规则中断。

沙箱中出现其他用户或任务的文件和状态 ​

如果看到来源不明的文件、文件被覆盖或删除、非预期的 Skill，或者某个任务的资源占用、重启和清理影响其他任务，请检查是否误用了共享沙箱。

  1. 确认受影响请求实际进入的智能体实例。
  2. 分别核对这些智能体实例关联的沙箱类型和实际资源 ID；再到来源智能体模板的 插件 页签确认选择的是沙箱模板还是现有沙箱实例。进入同一个智能体实例，或不同智能体实例显示同一个实际沙箱资源 ID，表示这些请求使用同一个沙箱。
  3. 如果不是有意共享，把智能体模板改为选择 沙箱 - 模板，再创建或更新需要隔离的智能体实例。需要按渠道用户分开时，使用模板绑定和 /init。
  4. 使用两个测试用户或智能体实例分别创建名称不同的测试文件，并核对沙箱资源 ID。预期隔离时，资源 ID 应不同，且一方不能读取或修改另一方的测试文件。
  5. 如果确实需要共享，分别使用约定的工作目录和文件名，避免并发修改同一内容，并统一安排更新、重启和清理。这样只能减少冲突，不能把共享实例变成独立隔离环境。

参见选择沙箱模板或实例。

渠道用户无法初始化 ​

  • 确认渠道账号使用模板绑定。
  • 使用 /init 或 /init KEY=VALUE。
  • 检查缺失的模板参数。
  • 从单聊初始化时，确认未勾选 禁用单聊；/init 也受此限制。
  • 单聊允许名单已填写时，确认当前用户的发送者 ID 与名单中的某个 ID 完全匹配，并已保存修改。
  • 飞书群聊中发送 /init 时，确认未勾选 禁用群聊 并已保存；群 ID 在允许名单中也不能绕过禁用。
  • 群聊允许名单已填写时，确认当前群 ID 与名单条目完全匹配。带有话题 ID 的消息按话题 ID 匹配，只填写所属群 ID 不会自动放行；单聊允许名单也不能放行群聊消息。
  • 检查是否已有用户绑定。
  • 检查动态创建的智能体实例是否进入运行状态。

单聊和群聊策略设置参见飞书单聊和群聊设置和QQ 渠道账号配置。

渠道中显示失败信息 ​

记录失败消息对应的渠道账号、用户、发送时间和完整错误信息。随后在绑定的智能体实例中查找同一时间的 Trace。不要连续重复提交可能产生副作用的操作。

找到对应 Trace ​

  1. 确认失败发生在模型、工具、外部服务还是权限审批。
  2. 飞书中显示同一轮响应的多个工具调用时，分别核对每个调用的工具名称、参数、状态和结果。不要把一个失败项当作全部调用都失败，也不要仅根据卡片同时显示多项就判断工具同时执行。
  3. 涉及子代理时，打开 后台任务。如果状态为 等待审批，在主智能体所在飞书会话中处理审批卡片。
  4. 根据失败位置检查模型凭证、工具连接、审批规则或外部服务。
  5. 修复问题后，使用固定输入重新测试，并确认渠道回复、Trace 和后台任务结果一致。

没有对应 Trace ​

  1. 打开 渠道账号，确认目标账号已经启用并处于在线状态。
  2. 检查账号的绑定模式和绑定目标。实例绑定应指向仍然存在且可以运行的智能体实例。
  3. 使用模板绑定时，在 用户绑定 中确认该用户已经绑定到有效智能体实例；尚未初始化时，让用户发送 /init。
  4. 修复状态或绑定后，发送不会修改业务数据的固定测试消息，并再次检查是否产生 Trace。
  5. 仍然失败时，把渠道账号、用户、发送时间和完整错误信息交给管理员。管理员可以据此检查渠道接入和消息处理状态。

渠道已经显示失败并不表示智能体实例停止运行。是否继续接收消息取决于实例、渠道账号和接入开关的状态。

飞书审批卡片点击后没有继续 ​

点击允许或拒绝后，卡片仍停留在等待状态且没有最终回复时，不要再次点击，也不要重发原请求。工具可能尚未执行，也可能已经执行但渠道没有返回结果；先把本次结果视为无法确定。

  1. 记录渠道账号、会话、审批卡片中的工具名称和发生时间，不要记录凭证。
  2. 在绑定的智能体实例中查找同一时间的 Trace，并在 MCP 服务或实际写入的业务系统中核对是否产生结果或副作用。
  3. 会话一直无法处理新消息时，使用 /session fix 恢复后续消息处理。旧审批仍需按上一步通过 Trace、MCP 服务或实际写入的业务系统核对结果。
  4. 使用无副作用消息确认会话恢复后，停止操作旧卡片并联系平台支持。

在一项允许测试和一项拒绝测试都得到明确最终结果之前，不要把该飞书账号用于生产审批。

未知斜杠指令没有透传 ​

开启 未命中的斜杠指令透传给 Agent后，使用无副作用的虚构命令检查 Agent 回复和新的 Trace。开关显示为开启但没有这两项结果时：

  1. 把开关恢复为关闭，确认未知命令重新返回 /help。
  2. 不要继续发送可能触发模型、工具或外部写入的未知命令。
  3. 记录渠道账号、发生时间和测试命令名称，联系平台支持检查账号配置是否已经应用。

飞书消息进入非目标智能体 ​

如果 /init、用户绑定或普通回复指向非目标智能体，先检查是否有多个已启用的飞书渠道账号使用同一个 App ID。

  1. 停止向该飞书应用发送测试或业务消息。
  2. 只保留一个目标渠道账号启用，停用复用同一 App ID 的其他账号，刷新后确认它们保持离线。无法确认旧连接已经停止时，先联系平台支持。
  3. 确认旧连接已经停止后，从保留账号发送 /help 和一条无副作用消息，核对回复、用户绑定和智能体实例一致。
  4. 仍然进入非目标智能体时，停用相关账号并联系平台支持；不要反复发送 /init，以免创建更多非预期实例或用户绑定。

WebSocket 绑定目标不可选 ​

  • 在 渠道账号 中切换到 WebSocket，使用 绑定 Agent 查找已经使用该目标的账号。
  • 已停用的 WebSocket 渠道账号仍保留绑定目标。需要继续使用该目标时，重新使用现有账号；需要替换账号时，先选择 停用，再选择 删除旧账号。
  • 多个客户端连接同一个绑定目标时，在同一个渠道账号下创建多个 WebSocket Token，不要为同一个目标重复创建渠道账号。

需要重新规划渠道账号或为多个客户端分别签发 Token 时，参见创建 WebSocket 渠道账号和为客户端创建 Token。

重新启用 WebSocket 账号后仍无法连接 ​

  1. 确认已对渠道账号选择 启用。
  2. 打开 凭证管理 的 WebSocket Token。
  3. 刷新 Token 列表，逐个检查绑定到该账号的 Token 状态。渠道账号的停用或重新启用不能替代这项核对。
  4. 只启用或替换仍需使用的 Token，并停用其他仍显示为启用的 Token；让客户端重新连接并验证鉴权、心跳和消息往返。

仍然无法连接时，按连接并完成鉴权核对所用鉴权路径，再根据 WebSocket 错误处理返回的 HTTP 状态、错误帧或 Close Code。修复后重新验证消息往返。

渠道账号无法删除 ​

先选择 停用，确认状态变为 已停用，再选择 删除。如果账号刚完成停用，刷新渠道账号列表或详情页后再确认状态。删除前还应盘点用户绑定、智能体实例、客户端配置和仍在使用的 Token。

修改智能体模板后结果没有变化 ​

检查智能体实例列表是否显示 智能体模板更新，实例需手动更新。编辑并保存目标智能体实例，再重新测试。

修改智能体模板或能力模板后，请逐个更新并验证正在运行的智能体实例。