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

# 常见问题

> 处理安装、供应商、CLI 检测、冷启动和自动更新等常见问题。

按你看到的提示往下对。还是不行，把复现步骤发到 [GitHub Issues](https://github.com/zhukunpenglinyutong/desktop-cc-gui/issues)。

## 安装和打开

<AccordionGroup>
  <Accordion title="从哪里下载">
    打开 [Releases](https://github.com/zhukunpenglinyutong/desktop-cc-gui/releases)，按平台选择 `dmg` / `exe` / `AppImage`。
  </Accordion>

  <Accordion title="打开后不知道从哪开始">
    先 **添加新项目**，再在设置里配供应商，然后发第一条消息。见 [发出第一条消息](/desktop/start/first-task)。
  </Accordion>
</AccordionGroup>

## 供应商和 CLI

<AccordionGroup>
  <Accordion title="提示未配置供应商">
    打开 **设置 → CLI配置管理**，为当前引擎添加供应商、使用本地配置，或先安装对应 CLI。
  </Accordion>

  <Accordion title="CLI 一直显示未安装">
    客户端不会静默代装。可在 **CLI配置管理** 里点 **安装**（先确认计划），或先在系统终端确认命令可用，再回到设置重新检测。GUI 启动的进程可能读不到 shell `PATH`，把路径写入系统环境变量后重启客户端。详见 [检测与安装](/desktop/providers/cli)。
  </Accordion>

  <Accordion title="设置里看到 Gemini 却配不了">
    Gemini 等引擎当前在「暂未开放」分组。README 里「Gemini 默认启用」的表述已过时，以设置页为准，不要按已交付 runtime 排查。
  </Accordion>

  <Accordion title="配置文件在哪">
    供应商目录在 `~/.ccgui/config.json`。Claude 托管供应商只写这里，不改 `~/.claude/settings.json`（本地官方配置可选用）。Codex 启用后写入 `~/.codex/`。Kimi / Grok 启用第三方会写入各自 `config.toml`（先备份 `.bak`）。OpenCode 托管供应商走环境注入，不改 `opencode.json`。Pi 写 `~/.pi/agent/auth.json`。DSH 的模型和 Key 在 Web UI / `$DSH_HOME`，不进 CC GUI。客户端设置与工作区在应用 data 目录。
  </Accordion>
</AccordionGroup>

## 性能和冷启动

<AccordionGroup>
  <Accordion title="Windows 安装后前几秒点不动">
    较新版本已修复冷启动点击假死。请升级到最新版；版本记录会延后到 startup-gate-ready 后再弹出。
  </Accordion>

  <Accordion title="长会话越来越卡">
    客户端对长会话做了 DOM 窗口与增量 Markdown。仍卡时，新开会话或折叠旧消息，并升级到最新版。
  </Accordion>

  <Accordion title="界面缩放调不了">
    产品侧已永久锁定 100% UI scale，以避免 WebView 假死路径。这是预期行为。
  </Accordion>
</AccordionGroup>

## 更新

<AccordionGroup>
  <Accordion title="如何更新">
    客户端内置自动更新。也可以从 Releases 手动下载新安装包覆盖安装。
  </Accordion>
</AccordionGroup>