> ## 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.

# 常见问题

> 处理 Node、SDK、CLI、供应商授权、停止生成和调试日志等常见问题。

按你看到的提示往下对。还是不行，把 **输出 → CC GUI** 里的日志和复现步骤发到 [GitHub Issues](https://github.com/hpstream/vscode-cc-gui/issues)。

## 安装和打开

<AccordionGroup>
  <Accordion title="扩展市场搜不到 CCGUI">
    搜索 `CCGUI` 或 `MossX`。完整显示名是 **CCGUI / CC GUI（Claude Codex OpenCode Kimi）**，扩展 ID 是 `MossX.vscode-cc-gui`。

    也可以打开 [Marketplace 页面](https://marketplace.visualstudio.com/items?itemName=MossX.vscode-cc-gui) 再点安装。VS Code 需要 1.85 或更高版本。
  </Accordion>

  <Accordion title="安装后侧栏是空的">
    先打开一个工作区文件夹。没有项目根目录时，文件引用、会话和工作目录都缺少上下文。

    然后点 Activity Bar 的 **CC GUI**，或运行 **CC GUI: Open CC GUI**。
  </Accordion>
</AccordionGroup>

## Node.js 和 SDK

<AccordionGroup>
  <Accordion title="提示 Node.js 未找到或版本过低">
    CC GUI 需要 Node.js 20+，而且只用扩展自己的路径，不改项目终端。

    1. 另装一份 Node 20+
    2. 运行 `node -p "process.execPath"`
    3. 把完整路径填到 **设置 → 基础配置 → 环境**，或 `ccGui.nodePath`
    4. Windows 必须指向 `node.exe`

    详见 [准备环境](/vscode/start/setup)。
  </Accordion>

  <Accordion title="提示 SDK 尚未安装">
    打开 **设置 → SDK 依赖**，安装 Claude Agent SDK 或 Codex SDK。对话区的 **前往安装** 会跳到这一页。

    Codex 如果缺 CLI 完整性，也会显示为未安装，需要重新装一遍。
  </Accordion>

  <Accordion title="SDK 安装失败">
    把安装日志复制给本机终端里的 AI 或发到 GitHub。常见原因：

    * Node 路径不对
    * npm 注册表或网络被拦
    * 用户目录 `~/.codemoss/dependencies/` 没有写权限
  </Accordion>
</AccordionGroup>

## 供应商和登录

<AccordionGroup>
  <Accordion title="Claude 提示未配置供应商">
    打开 **设置 → 供应商管理 → Claude Code**，任选一种：

    * 添加带 API Key 的供应商
    * 授权读取 `~/.claude/settings.json`
    * 授权使用已有的 CLI 登录

    取消本地 settings.json 授权后，必须再启用另一份供应商，否则 Claude 会一直处于未启用状态。
  </Accordion>

  <Accordion title="订阅制账号在终端能用、扩展不能用">
    对 Claude：

    1. 终端登录成功
    2. `~/.claude/settings.json` 的 `env` 保持为空
    3. 重启 VS Code
    4. 仍不行时，再按 [Claude Code](/vscode/providers/claude) 里的代理示例加 `HTTP_PROXY`

    对 Codex：先 `codex login`，再授权读取 `~/.codex/`，然后重启 VS Code。
  </Accordion>

  <Accordion title="CLI 一直显示未安装">
    扩展不会代装 Grok / Kimi / OpenCode / Pi。先在系统终端确认 `xxx --version` 能跑，再回到 **设置 → 供应商管理 → CLI** 点 **重新检测**。

    从 Dock / 开始菜单启动的 VS Code 有时读不到终端里的 `PATH`。把安装目录写进系统环境变量，再重启 VS Code。详见 [检测与安装](/vscode/providers/cli)。
  </Accordion>
</AccordionGroup>

## 对话过程

<AccordionGroup>
  <Accordion title="点了发送没有回复">
    依次检查：

    1. 当前供应商是否已启用
    2. SDK 或 CLI 是否就绪
    3. 是否卡在权限 / 提问对话框
    4. **输出 → CC GUI** 有没有报错
  </Accordion>

  <Accordion title="停止按钮停不掉 CLI">
    0.1.3 起，停止会结束 Grok / Kimi / OpenCode / Pi 的子进程。请升级到 Marketplace 最新版。用户主动停止后，完成 toast 和提示音不会再响。
  </Accordion>

  <Accordion title="新会话里还闪旧消息">
    0.1.3 修复了延迟回写导致的残留。升级后仍出现，就再开一个编辑器标签，不要复用当前标签。
  </Accordion>

  <Accordion title="工具调用一直转圈">
    0.1.2 修复了多步工具结束后转圈不消失的问题。先升级。仍复现时打开调试日志，保留那一轮对话再提单。
  </Accordion>

  <Accordion title="底部供应商 / 模式按钮点不动">
    0.1.1 修复了工具条被裁切的问题。升级后如果还点不到，把侧栏拉宽，或把 CC GUI 开到编辑器标签里。
  </Accordion>

  <Accordion title="Grok 发出去的图模型看不到">
    0.1.2 起图片会通过 `--prompt-file` 传给 Grok。请升级，并确认附件缩略图还在输入框里。
  </Accordion>
</AccordionGroup>

## 调试

<AccordionGroup>
  <Accordion title="怎么打开调试日志和开发者工具">
    1. 打开 **设置 → 基础配置 → 行为 → 调试日志**，或勾选 `ccGui.enableDebugLog`
    2. 日志在 **查看 → 输出 → CC GUI**
    3. 视图标题栏会出现开发者工具按钮；也可运行 **CC GUI: Open Webview Developer Tools**

    调试日志默认关闭。
  </Accordion>
</AccordionGroup>