> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排查

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

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

按"本地服务 → 登录与网络 → 设备与 Waker → 任务配置 → 外部能力"的顺序排查。每次只修改一项并立即复测；仍未解决时采集日志、错误文案和问题发生时间。

## 控制台打不开

```bash theme={null}
qoderwake status
qoderwake start --open
qoderwake portal --no-open
qoderwake restart
```

依次检查服务状态、启动服务、获取实际访问地址；仍打不开时重启。不要只使用书签中的固定端口。

<Tip>
  `qoderwake status` 显示服务正在运行，`qoderwake portal --no-open` 输出的地址可以打开，并且 Web Console 页面完成加载即表示正常。
</Tip>

如果 `restart` 因登录无效而拒绝执行，而你确认只需要本地模式：

```bash theme={null}
qoderwake restart --force
```

该参数会以本地模式启动；需要远程能力时应先重新登录。

## 登录或远程能力不可用

1. 执行 `qoderwake whoami` 检查账号；未登录或账号不正确时执行 `qoderwake login`。
2. 登录后再次核对账号，并运行网络诊断。
3. 远端设备仍不可见时，确认设备使用同一账号并在设备页刷新。

<Tip>
  `qoderwake whoami` 能显示预期账号，网络诊断中的 Gateway 认证通过，目标远端页面可以正常加载即表示正常。
</Tip>

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

1. 在任务看板确认状态；"需要操作"时到原任务处理。
2. 排队或长期执行中时，检查设备在线、服务运行且未休眠。
3. 打开原任务查看错误，并发送一条最小测试消息；仍失败时再检查目录、模型、连接器和权限。

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

## 自动任务没有运行

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

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

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

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

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

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

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

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

## 连接器不可用

1. 进入 Waker 详情 →「连接器」，检查配置、授权、连接状态和工具列表。
2. 到 Waker 的「权限」确认允许使用相关工具。
3. 新建一条只调用该连接器的最小测试任务。

<Tip>
  连接器显示可用，系统能够发现并列出工具，最小测试任务可以成功调用并返回结果即表示正常。
</Tip>

连接器统一在 Waker 详情的「连接器」中管理。不要把 Token 或密钥粘贴到对话、知识库或日志中。

### DWS：chat\_permission\_grant 重复定义

如果错误文案与下面内容完全一致：

```text theme={null}
Error: internal panic: chat_permission_grant flag redefined: params
```

可按 DWS 使用指南清理该用户目录下的 DWS 工具缓存：

```bash theme={null}
rm -rf ~/.dws/cache/default_default/tools/*
```

<Warning>
  只在错误文案完全匹配时执行，不要修改命令中的目录，也不要把它当作所有连接器问题的通用修复。
</Warning>

执行前停止 DWS 测试任务；清理后刷新连接器页面，重新检测并完成一次只读验证。

## 网络诊断失败

进入「设置」→「网络诊断」，运行完整诊断后按失败项处理：

| 失败项        | 优先检查                        |
| ---------- | --------------------------- |
| Gateway 认证 | 登录是否有效、账号是否正确、系统时间是否准确      |
| 机器注册       | 本地服务是否运行、当前设备是否完成注册、账号是否一致  |
| Work 回程    | 设备是否在线、企业网络或防火墙是否拦截长连接或回程请求 |

同时检查系统时间、DNS、企业网络、防火墙和安全软件；必要时切换网络复测，并记录失败摘要。

<Tip>
  修复后重新诊断，Gateway 认证、机器注册和 Work 回程均显示通过；随后原来的远程操作也能成功即表示恢复。
</Tip>

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

1. 进入「设置」→「更新应用」，确认更新已经安装。
2. 重启服务：

```bash theme={null}
qoderwake restart
```

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

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

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

## 查看日志并提交反馈

### 定位日志

默认主日志位置：

```text theme={null}
${QODERWAKE_HOME:-$HOME/.qoderwake}/logs/qoderwake.log
```

先根据问题选择一种检索方式：

```bash theme={null}
# 最近 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`；不要提交凭据。

### 提交反馈

```bash theme={null}
qoderwake feedback --email "你的邮箱" --message "问题描述"
```

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

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

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