故障排查

QoderWake 常见故障现象排查指南，涵盖控制台、登录、Waker、自动任务、WakerFlow、知识库、连接器、网络诊断、更新、日志与反馈。

本章按故障现象排列。可从目录进入对应标题，也可以在页面中搜索”控制台""登录""自动任务""WakerFlow""知识库""连接器""更新”或”Q仔”等关键词。

按”本地服务 → 登录与网络 → 设备与 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. 打开原任务查看错误，并发送一条最小测试消息；仍失败时再检查目录、模型、连接器和权限。

新建一条最小测试消息后，任务能从排队中进入执行中，并最终返回回复或明确错误即表示 Waker 工作正常。

​

自动任务没有运行

1. 确认任务已启用，并核对时间、时区、事件/API 请求、有效期和运行次数。
2. 使用本机目录时，确认触发时设备开机、服务运行且未休眠。
3. 查看运行历史，区分”未触发”和”已运行但失败”；修复后先手动运行，再等待真实触发。

运行历史新增一条记录，开始时间和触发方式符合预期，并且能打开该次运行的完整结果即表示正常。

​

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

1. 打开「执行记录」，确认当前 Phase、Worker 和是否等待用户输入。
2. 等待输入时到运行详情回答；Worker 失败时查看错误、Result 和原始事件。
3. 核对运行参数、Waker、知识库、连接器和权限；用业务日志定位阶段，但以 Worker Result 和最终返回值判断结果。
4. 修复后从右上角「运行」重新执行。

新运行中的所有必需 Worker 成功结束，执行记录显示已完成，最终返回值包含流程约定的完整字段即表示正常。

​

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

1. 清空类型、群组、Waker 和状态筛选，并在列表/泳道视图之间切换。
2. 群组任务展开父任务，并回到原入口确认任务确实已创建。
3. 重新进入看板；来源读取失败时运行网络诊断并检查权限。

清空筛选后能找到目标任务，状态与原任务详情一致，并可正常跳转到来源页面即表示正常。

​

连接器不可用

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

3. 执行 qoderwake status，再到「更新应用」核对版本。

重启后运行版本与已安装版本一致，页面不再显示”需要重启”即表示正常。

只运行 qoderwake update 而不重启时，当前服务仍可能使用旧版本。

​

查看日志并提交反馈

​

定位日志

默认主日志位置：

${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。

​

采集问题证据

记录发生时间与时区、版本和操作系统、任务名称或 ID、复现步骤、错误文案及 traceId/sessionId；不要提交凭据。

​

提交反馈

qoderwake feedback --email "你的邮箱" --message "问题描述"

与某个 Waker 相关时增加 --waker-id <wakerId>。

命令返回 feedback id 即表示提交成功。保存该 ID，后续沟通时可用于定位反馈记录。

提交反馈需要有效登录；问题描述参数是 --message。