LoongCode 使用文档

外观

故障排查 ​

本页收录常见故障的现象、原因与解决步骤。如果问题不在此列，建议先查看 常见问题，或尝试重启应用。

CLI 未被识别 / 任务无法启动 ​

现象： 新建任务后任务立即报错，提示找不到 claude、codex、opencode 或 kimi 命令；或依赖管理页面显示 CLI 未安装。

原因： LoongCode 在启动时通过系统 PATH 自动发现 CLI 可执行文件。若 CLI 未安装、安装在非标准路径，或安装后应用未重启，均会导致无法识别。

解决步骤：

  1. 检查 PATH 中是否有 CLI： 打开系统终端，输入 claude --version（或 codex --version / opencode --version / kimi --version / qodercli --version），若提示"命令未找到"则说明未正确安装或路径未加入 PATH。

  2. 通过依赖管理安装： 前往设置 → 依赖管理，查看 Claude / Codex / OpenCode / Kimi / Qoder CLI 的状态（五者「至少装一个」即可）；若显示未安装，点击安装按钮，等待安装完成后重启应用（Kimi Code CLI 暂不支持应用内一键安装，请按提示前往官网安装）。

  3. 手动指定 CLI 路径： 若 CLI 已安装但路径非标准，前往设置 → 常规 → CLI 命令，在对应输入框中填写可执行文件的绝对路径（如 /usr/local/bin/claude），或点击"选择文件"定位。

  4. 切换安装来源： 若安装过程中网络下载失败，可在设置 → 依赖管理 → 安装来源切换到其他来源（官方脚本 / GitHub 直连 / GitHub 加速），或配置自定义镜像前缀后重试。

首次安装指引请参阅 前置依赖。

任务报错或卡住 ​

现象： 任务运行中突然停止、长时间无响应，或对话面板显示错误信息。

原因： 常见原因包括：网络中断、API 服务不可用、对话上下文超出模型限制、CLI 进程意外退出等。

解决步骤：

  1. 停止并重试： 点击对话输入区的停止按钮结束当前回合，然后重新发送一条消息继续任务。

  2. 上下文超限： 若错误信息包含"context length"或"token limit"等关键词，说明上下文已满。自 v0.3.1 起支持自动恢复超限错误；若未自动恢复，可在对话面板底部手动点击压缩按钮执行摘要压缩后继续。开启设置 → 常规 → 自动压缩可避免此类中断。

  3. 查看错误信息： 对话面板会保留完整的错误详情。根据提示内容判断是 API Key 失效、网络问题还是其他原因，对症处理。

  4. 检查网络： 若错误持续且当前任务是 Claude 或 Codex CLI，前往设置 → 模型供应商，找到当前任务命中的那个供应商（含 Claude OAuth / Codex OAuth），在其网络代理区块中配置或移除代理，确认网络可正常访问 CLI 所需服务；OpenCode 任务的网络代理暂时只能通过系统环境本身的代理设置解决，Kimi 与 Qoder 任务固定跟随系统代理。

Qoder 任务发消息后毫无反应？先查登录态

Qoder CLI 在未登录（或凭据失效）时会直接静默退出、不输出任何内容，表现为发完消息后对话区什么都没发生。请到设置 → 模型供应商打开 Qoder OAuth 卡片确认状态灯是否为已登录，未登录就点登录完成浏览器授权后重试（v0.10.1）。

更新失败 ​

现象： 点击右上角更新徽标后，更新进度卡住或提示更新失败。

原因： Windows 自动更新依赖网络下载完整安装包，网络不稳定时可能失败。macOS 当前不提供应用内自动更新（以官方发布说明为准），需手动操作。

解决步骤：

  1. 手动下载安装包： 访问 LoongCode 官网 下载对应平台的最新安装包：

    • Windows：.exe 或 .msi 安装包
    • macOS：.dmg 文件

  2. 覆盖安装： 运行下载的安装包，直接覆盖当前版本完成升级（无需提前卸载旧版本）。

  3. macOS 用户： 应用不提供应用内更新，请按上述方式手动下载 .dmg 升级。若提示「无法验证开发者」，参见 常见问题 — macOS 无法验证开发者 处理后再启动。

Windows 下界面冻结卡死 ​

现象： 在 Windows 上应用界面完全冻结、无法操作，严重时只能从任务管理器结束进程。

原因： 旧版本存在两类已知的冻死问题，分别在不同版本中修复：

  1. 窗口切走 / 最小化后切回时硬冻死 —— 由主 WebView 遮挡计算与内嵌浏览器轮询的同步死锁引起，v0.6.1 已修复。
  2. 搜狗等中文输入法环境下，配合切窗 / 最小化恢复时偶发硬冻死 —— 由底层窗口库的键盘处理被输入法同步消息重入导致的死锁引起，v0.7.0 已修复。

解决方法： 升级到 v0.7.0 或更高版本即可同时规避以上两类问题。按照上方「更新失败」章节的步骤下载并安装最新版本即可。

依赖安装失败 ​

现象： 在依赖管理页面点击安装后，进度日志显示"失败"；或安装完成后依赖仍显示未安装。

原因： 常见原因包括网络下载失败（国内访问 GitHub 不稳定）、安装脚本执行权限不足、磁盘空间不足等。

解决步骤：

  1. 查看失败日志： 安装失败的日志会保留在依赖管理页面下方（离开页面再返回仍可查看）。根据错误信息判断具体原因。

  2. 切换安装来源： 前往设置 → 依赖管理 → 安装来源，尝试切换到其他选项：

    • 官方脚本： 使用 CLI 官方安装脚本
    • GitHub 直连： 直接从 GitHub 下载
    • GitHub 加速： 通过加速镜像下载（国内推荐）
    • 也可填写自定义镜像前缀，使用私有镜像源

  3. 配置下载代理： 若所在网络需要代理才能访问外部资源，在设置 → 依赖管理的下载代理配置中填写代理地址，然后重试安装。

  4. 点击重试： 修改来源或代理配置后，点击日志区域下方的重试按钮重新安装。

网络问题 ​

现象： 任务调用 AI 服务持续超时；依赖下载失败；API 请求报网络错误。

原因： 应用发出的网络请求（CLI 调用、依赖下载）都受系统网络环境影响。若所在网络需要代理访问外部服务，需要在应用内配置代理。CLI 调用与依赖下载走的是两套彼此独立的代理设置，需要分别检查。

解决步骤：

  1. 配置任务用到的供应商代理（Claude / Codex）： 前往设置 → 模型供应商，选中当前任务命中的供应商（含 Claude OAuth / Codex OAuth），在其网络代理区块中选择跟随系统（读取如 Clash 等工具接管的系统代理）或自定义并填写代理地址（格式：http://host:port，可选填"忽略代理的地址"）；每个供应商的代理相互独立，按需逐个配置。OpenCode 任务暂不受此设置影响，只能通过系统本身的代理环境解决；Kimi 与 Qoder 任务固定跟随系统代理。

  2. 配置依赖下载代理： 依赖安装的网络请求在设置 → 依赖管理的下载代理选项中单独配置，与供应商代理独立。

  3. 测试连通性： 配置代理后，新建一个简单任务（如发送"你好"）测试是否能正常得到 AI 响应。

  4. 检查 API Key： 若代理已正常但请求仍失败，确认设置 → 模型供应商中对应供应商的 API Key（或 OAuth 登录状态）配置正确。

下一步 ​