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

    詳見 [準備環境](/zh-Hant/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](/zh-Hant/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。詳見 [檢測與安裝](/zh-Hant/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>