Skip to main content
支持

故障排查

定位服务、任务、连接器、IM 和群聊答疑专员的常见问题。

本章按故障现象排列。可从目录进入对应标题，也可以在页面中搜索“控制台”“登录”“自动任务”“WakerFlow”“知识库”“连接器”“更新”或“群聊答疑专员”等关键词。 按“本地服务 → 登录与网络 → 设备与 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. 打开「执行记录」，确认当前 Phase、Worker 和是否等待用户输入。
  2. 等待输入时到运行详情回答；Worker 失败时查看错误、Result 和原始事件。
  3. 核对运行参数、Waker、知识库、连接器和权限；用业务日志定位阶段，但以 Worker Result 和最终返回值判断结果。
  4. 修复后从右上角「运行」重新执行。
完成判断： 新运行中的所有必需 Worker 成功结束，执行记录显示已完成，最终返回值包含流程约定的完整字段。

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

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

知识库资料无法使用

  1. 确认账号能打开 Notebook，资料存在、处理完成且内容可查看。
  2. 在知识库首页和 Waker 详情两处核对绑定关系。
  3. 新建对话，用答案明确的问题测试，并指定依据目标 Notebook 回答。
  4. 仍不准确时移除过期或冲突版本后重新测试。
完成判断： Waker 能准确回答资料中已知事实，且回答与当前版本资料一致。 未登录时重新完成账号授权；共享 Notebook 无法编辑时检查协作者权限。

连接器不可用

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

DWS：chat_permission_grant 重复定义

如果错误文案与下面内容完全一致： 
Error: internal panic: chat_permission_grant flag redefined: params
可按 DWS 使用指南清理该用户目录下的 DWS 工具缓存： 
rm -rf ~/.dws/cache/default_default/tools/*
适用范围： 只在错误文案完全匹配时执行，不要修改命令中的目录，也不要把它当作所有连接器问题的通用修复。
执行前停止 DWS 测试任务；清理后刷新连接器页面，重新检测并完成一次只读验证。

网络诊断失败

进入「设置」→「网络诊断」，运行完整诊断后按失败项处理：
失败项优先检查
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。

群聊答疑专员异常

机器人已加入群聊，但没有收到配对申请

  1. 进入群聊答疑专员首页的快速配置，确认目标机器人显示已连接且已启用。
  2. 确认机器人已经加入目标群，并在群内重新 @机器人 发送一条消息。
  3. 回到「配对申请」，核对群聊和机器人后允许申请。
  4. 仍没有申请时，进入主导航「IM」→「会话管理」→「添加配对」：可更新 DWS 后手动搜索会话，或生成 10 分钟有效的配对码并发送到目标群。
完成判断：目标群聊显示已配对，测试消息能够进入群聊答疑专员，并出现在「答疑记录」中。

私聊求助失败并出现 403 IP 白名单错误

错误可能包含： 
HTTP 403 - IpNotInWhiteList
处理步骤：
  1. 确认报错的钉钉应用，并获取 QoderWake 服务器的实际出口 IP。
  2. 在钉钉开放平台对应应用的安全设置中加入该出口 IP。
  3. 等待生效后重新测试；不要使用本机内网地址。
完成判断： 重新求助后不再出现 IpNotInWhiteList，目标同事能够收到消息。

群聊答疑专员回答超出业务范围或混入其他口径

  1. 检查群聊答疑专员绑定的知识库，移除与当前业务无关或口径冲突的资料。
  2. 不同产品或业务口径使用独立知识库，并确认资料已经处理完成。
  3. 分别用适用问题、超出范围问题和资料不足问题进行复测。
完成判断：有可靠资料的问题可以依据当前口径回答；超出范围或资料不足的问题会说明不确定或进入专家协助流程。

回答异常，但页面没有直接报错

  1. 在「答疑记录」中按群聊、用户和时间找到问题，判断停在知识检索、专家协助还是回复阶段。
  2. 按需打开对应答疑流程的执行记录，检查业务日志、最终返回值和原始事件。
  3. 根据失败位置修改机器人、群聊配对、知识库、专家配置或答疑流程，再用测试群复测。
完成判断：知识内问题可正确答复，知识外问题会说明不确定或发起专家协助，答疑记录能够定位处理阶段。 其他常见现象：
现象处理方法完成判断
图片问题理解不准确补充文字问题和背景，指出具体区域或字段；复杂图表同时提供原始数据回答能针对指定区域
钉钉文档链接导入知识库后显示 404将受限文档导出为知识库支持的文件，上传到 Notebook 后重新验证文件处理完成，Waker 可以使用其中内容回答
快速入门
使用数字员工
能力扩展
最佳实践
配置
支持