Workova 文档

Appearance

常见问题 ​

本页收录最常见的问题及其排查方法。每个问题按"现象 → 排查步骤 → 解决方案"组织。

页面操作不生效 ​

现象：页面能正常打开，但点击操作后没有反应或报错。

排查步骤：

  1. 确认您是否在桌面客户端中操作（而非浏览器预览）
  2. 检查桌面端 runtime 是否正常运行

解决方案：

以下能力强依赖桌面运行环境，在浏览器预览中不会真正执行：

  • 技能读写
  • 本地 MCP 服务管理
  • runtime 相关操作（Agent Run、Checkpoint 等）

INFO

如果您只是在浏览器中预览前端页面，页面结构可以查看，但涉及 Tauri 命令的操作不会执行。

登录循环 ​

现象：登录成功后又被重定向回登录页。

排查步骤：

  1. 检查是否刚修改过密码（需重新登录）
  2. 清除浏览器 / 客户端的本地存储和 Cookie
  3. 检查网络是否能正常访问后端服务

解决方案：

  • 清除本地存储后重新登录
  • 如果问题持续，检查后端 /api/v1/device/heartbeat 是否正常响应

TIP

登录后被重定向回登录页通常是会话失效导致的正常行为，不一定是 bug。

自动化未触发 ​

现象：配置了 Automation，但任务没有自动执行。

排查步骤：

  1. 确认触发器是否已启用
  2. 确认目标 Agent 或 Workflow 是否选择正确
  3. 查看运行记录中是否有对应的 Run 产生
  4. 检查触发条件是否真正满足

解决方案：

  • 如果触发器已启用但没有 Run 产生，检查触发条件的配置
  • 如果 Run 产生但执行失败，查看 Run 详情中的错误信息

MCP 服务不可用 ​

现象：MCP 服务器添加后状态显示为 failed 或 disconnected，工具不可用。

排查步骤：

  1. 确认当前是桌面运行环境（MCP 由桌面端管理）
  2. 检查服务器地址或命令是否填写正确
  3. 对于 stdio 类型，确认本地命令可以正常执行
  4. 对于 HTTP 类型，确认端点可以正常访问

解决方案：

按以下顺序操作：

  1. 点击「测试连接」确认连通性
  2. 如果测试通过，点击「连接」
  3. 连接成功后，点击「刷新工具」获取可用工具列表

WARNING

如果 last_error 显示 failed to connect，优先检查网络连通性和服务器进程状态。

技能显示不可用 ​

现象：技能列表中某个技能标记为不可用。

排查步骤：

  1. 查看技能卡片上显示的不可用原因
  2. 检查 SKILL.md 文件是否存在且格式正确
  3. 检查技能依赖的 bin / env / path 是否在当前环境中可用

解决方案：

  • 技能页面会明确展示不可用原因（缺少依赖、路径错误等），根据提示修复即可
  • 修复后可通过 skill_validate 命令重新校验

TIP

不要直接删除重建技能。先查看技能卡片上的提示信息，通常只需补齐缺失的依赖。

CLI 命令执行失败 ​

现象：通过 CLI 执行命令时报错或无响应。

排查步骤：

  1. 区分是命令本身不存在还是 runtime bridge 不可用
  2. 检查桌面端是否正在运行

解决方案：

运行以下命令确认环境状态：

bash
# 查看可用命令列表
workova contracts:list

# 检查 runtime 健康状态
workova runtime:health
  • 如果 contracts:list 无输出，说明命令注册有问题
  • 如果 runtime:health 报错，说明桌面端 runtime 未运行或 bridge 连接断开

Last updated:

Workova 官方文档

Copyright © Workova