Skip to main content
支持

故障排查

定位服务、任务、连接器、知识库和 @Waker 的常见问题。

本章按故障现象排列。可从目录进入对应标题，也可以搜索“控制台”“登录”“自主工作”“WakerFlow”“知识库”“连接器”“更新”或“@Waker”等关键词。 按“本地服务 → 登录与网络 → 设备与 Waker → 任务配置 → 外部能力”的顺序排查。每次只修改一项并立即复测；仍未解决时采集日志、错误文案和问题发生时间。

控制台打不开

qoderwake status
qoderwake start --open
qoderwake portal --no-open
qoderwake restart
依次检查服务状态、启动服务、获取实际访问地址；仍打不开时重启。不要只使用书签中的固定端口。 完成判断：qoderwake status 显示服务正在运行，qoderwake portal --no-open 输出的地址可以打开，并且 Web Console 页面完成加载。 如果 restart 因登录无效而拒绝执行，而你确认只需要本地模式： 
qoderwake restart --force
该参数会以本地模式启动；需要远程能力时应先重新登录。

登录或远程能力不可用

  1. 执行 qoderwake whoami 检查账号；未登录或账号不正确时执行 qoderwake login。
  2. 登录后再次核对账号，并运行网络诊断。
  3. 远端设备仍不可见时，确认设备使用同一账号并在设备页刷新。
完成判断：qoderwake whoami 能显示预期账号，网络诊断中的 Gateway 认证通过，目标远端页面可以正常加载。

Waker 无响应或任务长时间不结束

  1. 在任务看板确认状态；“需要操作”时到原任务处理。
  2. 排队或长期执行中时，检查设备在线、服务运行且未休眠。
  3. 打开原任务查看错误，并发送一条最小测试消息；仍失败时再检查目录、模型、连接器和权限。
完成判断： 新建一条最小测试消息后，任务能从排队中进入执行中，并最终返回回复或明确错误。

自主工作没有运行

  1. 确认任务已启用，并核对时间、时区、事件/API 请求、有效期和运行次数。
  2. 使用本机目录时，确认触发时设备开机、服务运行且未休眠。
  3. 查看运行历史，区分“未触发”和“已运行但失败”；修复后先手动运行，再等待真实触发。
完成判断： 运行历史新增一条记录，开始时间和触发方式符合预期，并且能打开该次运行的完整结果。

WakerFlow 卡住、失败或结果不完整

  1. 打开「执行记录」，确认当前阶段、Waker 节点和是否等待用户输入。
  2. 等待输入时到运行详情回答；Waker 节点失败时查看错误、节点结果和原始事件。
  3. 核对运行参数、Waker、知识库、连接器和权限；用业务日志定位阶段，但以 Waker 节点结果和最终返回值判断结果。
  4. 修复后从右上角「运行」重新执行。
完成判断： 新运行中的所有必需 Waker 节点成功结束，执行记录显示已完成，最终返回值包含流程约定的完整字段。

任务看板没有任务或状态不更新

  1. 清空类型、群组、Waker 和状态筛选，并在列表/泳道视图之间切换。
  2. 群组任务展开父任务，并回到原入口确认任务确实已创建。
  3. 重新进入看板；来源读取失败时运行网络诊断并检查权限。
完成判断： 清空筛选后能找到目标任务，状态与原任务详情一致，并可正常跳转到来源页面。

知识库资料无法使用

  1. 打开目标知识库，确认资料存在、处理完成且正文可查看。
  2. 切换到「卡片」，确认资料已经编译为可用知识卡；未编译时先手动编译。
  3. 在知识库列表和 Waker 详情两处核对绑定关系。
  4. 新建对话，用资料中答案明确的问题测试。
  5. 仍不准确时，移除过期或冲突资料，重新编译并复测。
完成判断： Waker 能准确回答资料中已知事实，且回答与当前版本资料一致。 共享知识库无法编辑时，检查成员身份和查看、编辑或管理权限。

连接器不可用

  1. 进入 Waker 详情 →「连接器」，检查配置、授权、连接状态和工具列表。
  2. 到 Waker 的「权限」确认允许使用相关工具。
  3. 新建一条只调用该连接器的最小测试任务。
完成判断： 连接器显示可用，系统能够发现并列出工具，最小测试任务可以成功调用并返回结果。 连接器统一在 Waker 详情的「连接器」中管理。不要把 Token 或密钥粘贴到对话、知识库或日志中。

网络诊断失败

进入「设置」→「网络诊断」，运行完整诊断后按失败项处理：
失败项优先检查
Gateway 认证登录是否有效、账号是否正确、系统时间是否准确
机器注册本地服务是否运行、当前设备是否完成注册、账号是否一致
Work 回程设备是否在线、企业网络或防火墙是否拦截长连接或回程请求
同时检查系统时间、DNS、企业网络、防火墙和安全软件；必要时切换网络复测，并记录失败摘要。 完成判断： 修复后重新诊断，Gateway 认证、机器注册和 Work 回程均显示通过；随后原来的远程操作也能成功。

更新已经下载但版本没有变化

  1. 进入「设置」→「更新应用」，确认更新已经安装。
  2. 重启服务：
qoderwake restart
  1. 执行 qoderwake status，再到「更新应用」核对版本。
完成判断： 重启后运行版本与已安装版本一致，页面不再显示“需要重启”。 只运行 qoderwake update 而不重启时，当前服务仍可能使用旧版本。

查看日志并提交反馈

1. 定位日志 默认主日志位置： 
${QODERWAKE_HOME:-$HOME/.qoderwake}/logs/qoderwake.log
先根据问题选择一种检索方式： 
# 最近 200 条 warn 及以上日志
qoderwake log --level warn --limit 200

# 按关键词检索
qoderwake log --keyword "关键词" --limit 200

# 按 traceId 或 sessionId 检索
qoderwake log <traceId>
持续查看新日志使用 qoderwake log -f。位置参数 traceId、--trace-id 和 --keyword 一次只能选择一种；简化显示可增加 --clean。 2. 采集问题证据 记录发生时间与时区、版本和操作系统、任务名称或 ID、复现步骤、错误文案及 traceId/sessionId；不要提交凭据。 3. 提交反馈 
qoderwake feedback --email "你的邮箱" --message "问题描述"
与某个 Waker 相关时增加 --waker-id <wakerId>。 完成判断： 命令返回 feedback id。保存该 ID，后续沟通时可用于定位反馈记录。 提交反馈需要有效登录；问题描述参数是 --message。

@Waker 异常

机器人已加入群聊，但没有待处理申请

  1. 进入「@Waker」→「IM 连接管理」，确认机器人连接显示可用。
  2. 确认机器人已经加入目标群，并在群内重新 @ 机器人发送一条普通消息。
  3. 打开「@Waker」→「待处理申请」，检查聊天、申请人和连接身份。
  4. 仍没有申请时，检查该连接是否限制了聊天范围；页面提供配对码时，生成一次性配对码并在目标群完成配对。
  5. 批准后回到群里重新 @ 机器人执行一条只读任务。
完成判断： 目标群出现在已开通列表，消息能创建任务，并且回复返回原群。

已开通但机器人不回复

  1. 在已开通列表确认聊天为活跃且 @Waker 已启用。
  2. 检查 IM 连接是否在线，机器人是否仍在群内并具有收发消息权限。
  3. 打开聊天配置，确认至少有一个已启用的 Waker，并设置默认 Waker。
  4. 检查 Waker 的设备、项目、模型、连接器和权限。
  5. 发送一条不依赖外部工具的最小测试任务，并在任务看板查看状态。
完成判断： 测试消息进入任务看板，任务由对应 Waker 执行，结果返回原聊天。

路由到了错误的 Waker

  1. 检查每个 Waker 的名称和职责是否清晰区分。
  2. 确认默认 Waker 只承接职责不明确的请求。
  3. 将职责重叠的角色改写为明确的输入、输出和边界。
  4. 在同一测试聊天分别发送两条职责明确的任务，核对实际执行 Waker。
修改路由相关配置后不要沿用旧判断结果。使用同一组固定测试题重新验证，便于比较。

文件或最终结果没有返回 IM

  1. 打开任务详情，确认任务是否完成以及产物实际位置。
  2. 检查当前 IM 渠道是否支持原生附件或可点击链接。
  3. 如果渠道不支持附件，从 QoderWake 任务产物或团队项目中获取文件，并在聊天中返回可访问位置。
  4. 不要把密码、Token 或客户隐私作为附件发送。
完成判断： 群成员能从原聊天或明确链接找到最终产物，并且访问权限符合预期。 其他常见现象：
现象处理方法完成判断
图片问题理解不准确补充文字问题和背景，指出具体区域或字段；复杂图表同时提供原始数据回答能针对指定区域
受限网页导入知识库后为空或显示 404在有权访问的前提下导出为知识库支持的文件，上传、编译后重新验证文件处理和编译完成，Waker 可以使用其中内容回答
快速上手
工作管理
员工资源
最佳实践
配置
支持