Skip to Content
文档UnitaryLab CLI 用户手册排障指南

排障指南

概述

本章按照常见问题现象组织排障思路，适用于以下场景：

  • CLI 命令无法识别，或启动后立即报错。
  • 登录失败、Token 过期、工具调用返回 401/403。
  • 模型调用失败、API Key 配置错误、请求触发速率限制。
  • 启动后行为与预期不一致（例如模型列表异常、工作目录错误、技能缺失等）。

建议优先验证以下三个基础条件是否正常：

  • CLI 命令可正常执行
  • LLM 服务可正常访问
  • 当前登录态有效

确认以上基础能力正常后，再针对具体现象进行进一步排查。

通用排障流程

遇到异常时，建议按以下顺序逐项检查：

  1. 检查 CLI 是否可用

在 shell 中执行：

unitarylab --help

确认 CLI 能正常启动，并正确输出子命令列表。

  1. 检查登录状态

执行：

unitarylab whoami

确认当前 Token 仍处于有效期内。

  1. 检查 LLM 配置

执行：

unitarylab configure

重新完成一遍配置流程，CLI 会自动进行连通性校验。

也可以在会话中执行：

/config
  1. 让 Agent 执行自检

进入会话后，可以直接描述当前现象，例如：

我刚才让你保存文件，但终端没有任何输出，能否帮我分析可能原因？

Agent 会尝试基于当前可用工具进行自检与分析。

  1. 确认命令是否发生变化

执行：

/help

确认当前版本中的命令名称与参数格式是否发生变化。

命令无法识别

现象

在 shell 中执行：

unitarylab

提示：

command not found

可能原因

  • CLI 尚未正确安装。
  • 可执行文件目录未加入 PATH。
  • 当前 shell 与安装环境不一致（例如安装在某个 venv 中，但运行时使用的是其他环境）。

排查步骤

  1. 确认当前 shell、Python 环境与 PATH 配置符合预期。
  2. 检查 CLI 是否安装在当前环境中。
  3. 联系内部发布渠道，确认当前版本的推荐安装方式。

安装流程的详细说明将在 快速开始 中补充。

启动后自动进入 configure

现象

执行 unitarylab 后，没有进入对话界面，而是直接要求填写：

  • Provider
  • API Base
  • API Key

原因说明

CLI 未检测到完整的 LLM 配置。常见原因包括：

  • 首次使用，尚未初始化配置文件。
  • 本地配置文件被删除、覆盖或损坏。
  • 使用了 --dotenv <path>，但目标路径中不存在有效配置。

完成配置后，CLI 会自动进入对话界面。

登录相关问题

提示「请先运行 unitarylab login」

现象

执行：

unitarylab

或：

unitarylab start

时，CLI 立即中断并提示需要登录。

可能原因

  • 首次使用，尚未登录。
  • Token 已过期（剩余有效期不足 60 秒时会被视为过期）。
  • 最近执行过：
unitarylab logout

解决方案

执行：

unitarylab login

如果当前环境为非终端（例如 CI、容器或后台进程），CLI 不会自动弹出登录流程。请先在交互式终端中完成登录。

工具调用返回 401 / 403

现象

Agent 在调用远端工具时返回类似错误：

状态码：401，响应：{"code": ..., "message": "..."}

原因说明

这是 CLI 的预期行为。

对于 401 / 403 错误，CLI 不会自动重试或隐式刷新登录态，而是将原始错误透传给模型，由模型提示用户重新登录。

解决方案

在会话中执行：

/login

或退出后执行：

unitarylab login

重新登录后，重新发送上一轮请求即可。

LLM 配置相关问题

模型返回 401 / invalid API key

现象

发送请求后，模型立即返回 API Key 相关错误。

处理方式

在终端环境下，CLI 会自动询问是否立即重新配置。

确认后，会进入与 configure 相同的配置流程。配置完成后，可直接重发上一轮请求。

如果当前环境不支持交互式输入，请返回 shell 执行：

unitarylab configure

模型列表存在错误项

现象

/model 或 /models list 中出现：

  • 已废弃模型
  • 无效模型 ID
  • 示例占位符模型
  • 无法正常调用的模型

例如：

your-model-id
example

排查步骤

  1. 查看当前模型列表：
/models list
  1. 删除错误模型：
/models remove <id>
  1. 重新从 Provider 拉取模型列表：
/models refresh

CLI 会自动拒绝写入明显的占位符 ID。如果这些 ID 仍然存在，通常说明它们是通过手动编辑配置文件加入的。

使用 Custom Provider 后仍出现 DashScope 默认模型

现象

切换到 Custom Provider 后，模型列表中仍然存在 DashScope 的默认示例模型。

原因说明

CLI 在启动时会检测 Provider 与模型来源是否一致，并输出 warn 提示。

解决方案

推荐以下两种处理方式：

  1. 重新执行：
/config

CLI 会基于当前 Provider 重新拉取或重新配置模型列表。

  1. 手动删除无关模型：
/models remove <id>

工作目录与会话相关问题

/cd 后 shell 目录未变化

现象

在会话中执行：

/cd <path>

后，Agent 的路径发生变化，但 shell 当前目录没有变化。

原因说明

这是预期行为。

CLI 中的 /cd 仅修改 Agent 的逻辑工作目录，不会修改宿主 shell 的 os.getcwd()。

如果需要同时修改 shell 当前目录，请在 shell 中单独执行：

cd <path>

详见：会话与工作目录指南

恢复会话后工作目录不符合预期

原因说明

CLI 会自动恢复该会话最后一次使用的工作目录。

如果你在多个目录之间频繁切换，恢复后的目录可能与当前预期不一致。

解决方案

进入会话后先执行：

/pwd

确认当前目录。

如有需要，再执行：

/cd <path>

切换到目标目录。

技能相关问题

/skills 列表为空或缺少预期技能

现象

执行：

/skills

后，未看到预期中的技能。

可能原因

  • 当前发行版与之前版本的技能集不同。
  • 技能目录未成功加载。

解决方案

  1. 在进程中输入：
/<技能名>

后按 Tab，查看自动补全结果，确认当前可用技能。

  1. 联系内部发布渠道，确认当前发行版是否包含目标技能。

调用技能后 Agent 未按预期下钻

现象

调用索引技能后，Agent 没有继续沿技能引用链进入子技能。

建议做法

尽量明确指定目标技能，例如：

请使用 cryptography/shor 技能完成下面的任务

或者直接调用具体技能：

/shor

以跳过索引层。

联系技术支持

如果以上步骤仍无法解决问题，建议整理以下信息后提交反馈：

  • unitarylab --help 输出结果（用于确认版本与命令集）

  • unitarylab whoami 输出结果（请勿包含敏感信息）

  • 会话启动时的自检信息（版本、环境、操作系统、耗时等）

  • 完整复现路径：

    • 执行了哪些命令
    • 每一步的输出内容
    • 最终错误信息

请勿提交 API Key、密码等敏感凭据。 如果日志中包含敏感信息，请先完成脱敏处理后再提交。

最后更新于
技能调用指南概览