跳到主要内容

SkillFlaw 故障排查

本页汇总了你在使用 SkillFlaw 或参与 SkillFlaw 开发时可能遇到的常见问题与排查建议。

缺少组件​

随着 SkillFlaw 持续演进，组件经常会因能力归类调整、弃用或为新组件腾挪位置而重新分组。

如果某个组件似乎没有出现在 流程组件 或相关菜单中，请尝试以下方法：

  • 使用 Search 搜索该组件。
  • 检查其它组件分类以及 业务组件。
  • 检查旧版组件，它们默认是隐藏的。
  • 查看 Changelog，确认最近版本是否调整了组件。
  • 如果该组件属于单次使用型组件，请确认它是否已经存在于当前流程中。

如果仍然找不到该组件，请参阅 SkillFlaw GitHub Issues and Discussions。

Playground 中没有输入框​

如果 Playground 中没有消息输入框，请确认你的流程里存在 Chat Input 组件，并且它已经直接或间接连接到 Language Model 或 Agent 组件的 Input 端口。

因为 Playground 的设计目标是支持以 LLM 查询-响应形式运行的流程，例如聊天机器人或智能体，所以一个流程至少需要包含 Chat Input、Language Model/Agent 和 Chat Output 组件，才能完整支持 Playground 的对话交互界面。

更多说明请参阅在 Playground 中测试流程。

缺少 key、找不到 key 或 API key 无效​

如果你在运行流程时遇到 API key 相关错误，请尝试以下检查：

  • 对所有需要凭证的组件，确认其设置中已经填入有效凭证，例如 API Key 字段。
  • 如果你把凭证保存在 SkillFlaw 全局变量 中，请确认你选择了正确的全局变量，并且该变量中保存的是有效凭证。
  • 确认所提供的凭证仍然有效、拥有所需权限，并且在适用场景下账户余额或额度充足。例如，多数模型提供方要求账户具备可用额度才能调用其 LLM。

SkillFlaw 安装问题​

以下问题可能在安装 SkillFlaw 时出现。

从仓库安装时卡在依赖解析​

如果你使用临时的 Python 包安装命令安装仓库依赖，可能会缓慢失败，并出现如下报错：


_10
pip is looking at multiple versions of <<library>> to determine which version is compatible with other requirements. This could take a while.

遇到该问题时，请改用 从源码安装 SkillFlaw 中说明的、由仓库管理的 uv 工作流。

Linux 安装时构建必需包失败​

当你在 Linux 上安装 SkillFlaw OSS 时，如果系统包过旧或缺失，安装可能失败，例如：


_10
Resolved 455 packages in 18.92s
_10
× Failed to build `webrtcvad==2.0.10`
_10
├─▶ The build backend returned an error
_10
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit status: 1)

要解决该问题，请先安装必要的构建依赖，然后重试 SkillFlaw 安装：


_10
sudo apt-get update
_10
sudo apt-get install build-essential python3-dev

如果升级软件包后仍无法解决，请单独安装 gcc，然后再次尝试安装：


_10
sudo apt-get install gcc

webrtcvad 包导致安装失败​

如果你遇到来自 webrtcvad 包的错误，请先在虚拟环境中执行 uv pip install webrtcvad-wheels，然后重新尝试安装 SkillFlaw。

Intel Mac 需要协议缓冲编译器（protoc）​

如果你在 Intel 架构的 Mac 上安装 SkillFlaw，当未安装 Protocol Buffers Compiler（protoc）时，可能会遇到安装错误。

该要求不适用于 ARM64 的 Apple Silicon Mac。

要解决该问题，请通过 brew install protobuf 安装 protoc。

更多说明（含其它安装方式）请参阅 Protocol buffers installation documentation。

Windows 上 SkillFlaw Desktop 需要 C++ 构建工具​

在 Microsoft Windows 上安装 SkillFlaw Desktop 时，系统可能缺少所需的 C++ 编译器。如果你看到 C++ Build Tools Required! 错误，请按界面提示安装 Microsoft C++ Build Tools，或直接安装 Microsoft Visual Studio。

SkillFlaw 启动问题​

以下问题可能在启动 SkillFlaw 时出现。

找不到 skillflaw.__main__ 模块​

当你使用 skillflaw run 运行 SkillFlaw 时，可能出现如下错误：


_10
> No module named 'skillflaw.__main__'

请依次尝试以下方法：

  1. 使用 uv run skillflaw run，而不是 skillflaw run。
  2. 如果仍然无效，请用 uv pip install skillflaw -U 重新安装最新版本的 SkillFlaw。
  3. 如果还不行，请使用 uv pip install skillflaw --pre -U --force-reinstall 强制重装 SkillFlaw 及其依赖。

SkillFlaw runTraceback​

当你使用 skillflaw run 启动 SkillFlaw 时，也可能看到如下错误：


_10
> skillflaw runTraceback (most recent call last): File ".../skillflaw", line 5, in <module> from skillflaw.__main__ import mainModuleNotFoundError: No module named 'skillflaw.__main__'

这通常有两类原因：

  • 存在多个 SkillFlaw 安装：你通过 pip install skillflaw 安装了 SkillFlaw，但系统中已经存在旧版本，因此当前执行到了错误的可执行文件。

    解决方法：使用 python -m skillflaw run，而不是直接执行 skillflaw run。

    如果还不行，请尝试执行 uv pip install skillflaw --pre -U 重新安装。

  • 安装期间发生版本冲突：安装过程中的依赖版本冲突可能导致启动异常。 解决方法是执行 python -m pip install skillflaw --pre -U --force-reinstall，重新安装 SkillFlaw 及其依赖。

从终端设置的环境变量在应用内不可用​

在终端里设置的环境变量，不会自动传递给通过 Finder 或开始菜单启动的 GUI 应用，例如 SkillFlaw Desktop。 如果你要为 SkillFlaw Desktop 设置环境变量，请参阅为 SkillFlaw Desktop 设置环境变量。

访问 SkillFlaw Desktop 启动日志​

如果你在 SkillFlaw Desktop 中遇到启动问题，可能需要访问 SkillFlaw Desktop 启动日志来进一步排查。

多实例运行多个流程时出现 user not found 或 inactive​

当你在不同端口上同时运行多个本地 SkillFlaw OSS 实例（例如 localhost:7860 与 localhost:7861）时，日志中可能会出现认证错误。 例如：


_10
[07/22/25 10:57:07] INFO 2025-07-22 10:57:07 - INFO - utils - User not found or inactive.

要解决该问题，请为每个 SkillFlaw 实例分别使用独立浏览器实例或独立浏览器用户配置文件。

包未安装​

在 SkillFlaw OSS 中，你可以按照错误信息提示安装缺失的依赖。

如果你使用的是 SkillFlaw Desktop，请参阅在 SkillFlaw Desktop 中安装自定义依赖。

PostgreSQL 的 asyncpg 驱动兼容性问题​

当 SkillFlaw 使用 PostgreSQL 数据库初始化时，可能出现如下错误：


_10
sqlalchemy.exc.DBAPIError: (sqlalchemy.dialects.postgresql.asyncpg.Error) <class 'asyncpg.exceptions.DataError'>: invalid input for query argument $7: datetime.datetime(2025, 10, 31, 14, 8, 5... (can't subtract offset-naive and offset-aware datetimes)

出现该问题的原因是：asyncpg 对时区处理比 psycopg2 更严格，而 SkillFlaw 当前数据库 schema 与它并不完全兼容。

解决方法是：从当前安装中移除 asyncpg，改用 psycopg2。

必须通过 query 或 header 传入 API key​

如果你在 SkillFlaw 登录页尝试注册时遇到 An API key must be passed as query or header 错误，说明当前环境中 SKILLFLAW_AUTO_LOGIN 被设置成了 false，此时只有超级用户才能创建并激活普通用户账号。 因此，你当前会被锁定在这个 SkillFlaw 实例之外。

如果你不是管理员，则必须由超级用户先创建并激活一个普通用户账号，你才能登录。

如果你是管理员，请使用超级用户账号登录，或使用 SKILLFLAW_AUTO_LOGIN=true 重新启动 SkillFlaw。

更多说明请参阅配置安全的 SkillFlaw 服务器。

SkillFlaw 升级问题​

以下问题可能在升级 SkillFlaw 版本时出现。

关于版本管理，请参阅安装 SkillFlaw。

运行迁移时出现 Something went wrong​

在 SkillFlaw 升级过程中，如果新版本无法覆盖 SkillFlaw 缓存目录中的 skillflaw-pre.db，可能会出现如下错误：


_10
> Something went wrong running migrations. Please, run 'skillflaw migration --fix'

解决方法是：清空 SkillFlaw 缓存目录中的内容。 具体路径取决于你的操作系统、安装方式以及自定义配置。 更多说明及默认路径请参阅内存管理选项。

危险

清理缓存会删除你的设置。 如果你希望保留设置文件，请在清空缓存目录前先备份这些文件。

SkillFlaw Desktop 显示已是最新版本，但实际上已经落后​

如果你正在使用 SkillFlaw Desktop 1.4.2 或更早版本，界面可能会错误地显示“当前已经是最新版本”，即使实际上已有更新版本可用。

原因是自动更新检测能力是在 1.4.2 版本引入的；更早版本无法自动检测或应用更新。

解决方法是卸载 SkillFlaw Desktop，然后从你所在组织或当前部署流程所使用的正式分发渠道重新下载并安装最新桌面版。

升级 Pydantic/FastAPI 后冻结组件时报 422​

如果你在本地升级了 Pydantic 和 FastAPI 依赖，冻结组件时可能遇到 422 错误。

这是因为这些依赖的新版本调整了请求体处理方式。

如果你遇到该问题，请将 SkillFlaw 升级到 1.6.5 或更高版本，该版本已经包含相应修复。


_10
uv pip install skillflaw -U

SkillFlaw 卸载问题​

以下问题可能在卸载 SkillFlaw 时出现。

macOS 卸载 SkillFlaw Desktop 后缓存目录不会自动删除​

在 macOS 上，卸载 SkillFlaw Desktop 只会删除 .app 文件，不会删除 SkillFlaw 缓存目录中的内容。默认缓存目录是 ~/Library/Caches/skillflaw，其中可能包含运行过程中生成的缓存与设置文件。

如果你重新安装 SkillFlaw Desktop，它会继续使用上一次安装遗留下来的数据启动。

如果你想彻底移除 macOS 上的 SkillFlaw Desktop，还需要手动删除 ~/Library/Caches/skillflaw，或者你自行配置过的自定义缓存路径：


_10
rm -rf ~/Library/Caches/skillflaw

SkillFlaw MCP 问题​

以下问题可能在你把 SkillFlaw 作为 MCP 服务器或 MCP 客户端使用时出现。

Claude for Desktop 无法正确使用 MCP 服务器工具​

如果 Claude for Desktop 无法正确使用你的 MCP 服务器工具，请尝试在 claude_desktop_config.json 配置文件中显式指定本地 uvx 或 npx 可执行文件的绝对路径：

  1. 使用 which uvx 查找你的 uvx 路径。

    使用 which npx 查找你的 npx 路径。

  2. 在 claude_desktop_config.json 中，将该路径写入 SkillFlaw MCP 服务器配置。如下所示：


    _11
    {
    _11
    "mcpServers": {
    _11
    "PROJECT_NAME": {
    _11
    "command": "PATH_TO_UVX",
    _11
    "args": [
    _11
    "mcp-proxy",
    _11
    "http://SKILLFLAW_SERVER_ADDRESS/api/v1/mcp/streamable"
    _11
    ]
    _11
    }
    _11
    }
    _11
    }

Windows 上基于浏览器的 MCP 流程不会打开浏览器​

这是在 Windows 上使用带浏览器导航动作的 MCP 工具（如 Playwright）时的一个已知问题：工具本身可以执行成功，但浏览器标签页或窗口不会真正打开。

该问题的原因是 MCP 服务器运行在 Python 进程中，而该进程在 WSL 或 Windows 环境下无法正常拉起浏览器窗口。

解决办法是：采用 Playwright MCP 仓库 文档中描述的独立 MCP Server 方案。服务启动后，再把它作为 HTTP/SSE Server 接入 SkillFlaw。

如果你使用的是其他浏览器导航工具，请参阅对应提供方文档中的排障建议。

Windows/WSL 混合环境中 MCP 服务器显示 “No tools or prompts connected”​

如果你把 SkillFlaw Desktop 作为 MCP 服务器使用，而客户端运行在不同环境中（例如 SkillFlaw 运行在 Windows 主机上，MCP 客户端运行在 WSL 中），可能会看到 “No tools or prompts connected” 或连接失败错误。

这是因为 Windows 与 WSL 之间存在网络隔离。

WSL 无法直接访问 Windows 主机上的 localhost 服务，因此运行在 Windows 主机上的 SkillFlaw 不能通过 localhost:7860 被 WSL 客户端访问。

解决办法是让服务器与客户端运行在同一个操作环境中。

另一种方案是：把 SkillFlaw Desktop 配置为监听 Windows 默认 IP 10.255.255.254:7860，而不是 localhost，以接受来自 WSL 的访问。

流程升级后 MCP Tools 组件丢失 Tool Mode 选项​

如果你升级了一个使用 MCP Tools 组件 且启用了 Tool Mode 的现有流程，该组件在流程升级后可能丢失 Tool Mode 设置。 这会导致依赖 MCP 工具暴露给智能体的流程失效。

如果你在升级 SkillFlaw 1.7.1 或更早版本创建的流程时遇到该问题，请按以下步骤处理：

  1. 在流程中选中 MCP Tools 组件。

  2. 点击 Code 打开组件代码编辑器。

  3. 在组件模板结构里找到 inputs 下的 tool_mode 字段。 它可能缺失，或被设置成 false。

  4. 如果该字段缺失，请补上；如果已存在，请将它改为 true：


    _10
    tool_mode = True

  5. 点击 Check & Save 保存代码修改。

Embedding Model 组件中的 token 长度限制错误​

如果你的分块策略与嵌入模型的 token 化上限不匹配，就可能出现 token 长度错误。 更多说明请参阅因 chunk size 导致的 tokenization 错误。

容器化环境中的文档处理错误​

如果你在 Linux 容器化环境中使用基于 Docling 的文档处理工作流，而执行 Docling 转换的运行时缺少所需系统库，就可能遇到相关错误。

在当前 SkillFlaw 版本中，这类问题通常发生在你自管的 Docling 业务组件运行时，例如独立部署的 Docling Serve，而不是标准的 Read File 组件。

当 Docling 运行时部署在精简的 Linux 容器中时，某些系统库默认可能并未安装。如果你看到与文档或图片处理相关的错误，请在执行 Docling 转换的容器或主机中安装以下软件包：


_10
apt-get update && apt-get install -y libgl1 libglib2.0-0

这些依赖是 Docling 执行文档处理操作所必需的。如果 SkillFlaw 是通过 Docling Serve 连接到 Docling，请把这些依赖安装在 Docling Serve 一侧，并在安装后重启该服务。

自定义组件与集成问题​

如果你在排查某个第三方集成问题，请优先查看 SkillFlaw 文档中关于该集成的说明，以及对应提供方的官方文档。

如果你正在构建自定义组件，请参阅自定义 Python 组件的错误处理与日志。

自定义组件未出现在可视化编辑器中​

如果你的自定义组件没有出现在 SkillFlaw 可视化编辑器里，请依次检查以下内容：

  1. 确认组件目录结构符合要求：


    _10
    /your/custom/components/path/ # Base directory set by SKILLFLAW_COMPONENTS_PATH
    _10
    └── category_name/ # Required category subfolder that determines menu name
    _10
    ├── __init__.py # Required
    _10
    └── custom_component.py # Component file

  2. 确认每个分类目录下都包含 __init__.py 文件。 这是 Python 将该目录识别为模块所必需的。

  3. 如果你通过环境变量 SKILLFLAW_COMPONENTS_PATH 指定自定义组件路径，但组件仍未被加载，请改用命令行参数 --components-path：


    _10
    uv run skillflaw run --components-path /path/to/your/custom/components

如果你仍然无法解决，请附带目录结构与组件配置细节，在 GitHub 上提交问题。

另请参阅​