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

# 準備環境

> 為 CC GUI 客戶端準備 runtime、供應商憑證和各引擎 CLI。

安裝客戶端後，還需要至少一條可用的 AI 執行時，以及一個專案工作區。

## 1. 理解依賴關係

客戶端本身是完整桌面應用，不需要你再裝 VS Code 或 IDEA。

對話仍依賴本機 runtime：

| 你想用誰                        | 需要什麼                   |
| --------------------------- | ---------------------- |
| Claude Code                 | 跟隨指引安裝CLI 和 進行配置       |
| Codex                       | 跟隨指引安裝CLI 和 進行配置       |
| Kimi / Grok / OpenCode / Pi | 本機對應命令可用，再配本地配置或第三方供應商 |
| DeepSeek Harness            | 本地啟動DSH 並配置完成          |

開啟 **設定 → CLI配置管理**（供應商）檢視檢測狀態與安裝說明。可用引擎與「暫未開放」會分組顯示。

<img src="https://mintcdn.com/mossx-docs/kz4nt5KFSKzkAZwe/images/desktop/providers-overview.png?fit=max&auto=format&n=kz4nt5KFSKzkAZwe&q=85&s=a6c19a6b617866f7941dfc60b7c05dfa" alt="供應商與 CLI 配置" width="100%" data-path="images/desktop/providers-overview.png" />

## 2. 配置 CLI

開啟 **設定 → CLI配置管理**。左側按 **已啟用 / 未啟用 / 暫未開放** 分組。點進一條引擎即可檢測版本、安裝或更新 CLI，並配置憑證。

可用引擎與「暫未開放」條目都會列出來。Gemini、Cursor、Copilot、Qwen 等出現在「暫未開放」時，不要按已交付 runtime 配置。

<Tabs>
  <Tab title="Claude Code">
    * 新增託管供應商：名稱、API Key、Base URL、模型對映
    * 或使用本地 `~/.claude/settings.json` / CLI 登入態
    * 官方直連走 Anthropic；第三方預設（智譜、Kimi、DeepSeek、OpenRouter 等）轉到對應端點
    * 託管 profile 寫在 `~/.ccgui/config.json`
    * 可覆蓋 Claude CLI 路徑
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [Claude Code](/zh-Hant/desktop/providers/claude)。
  </Tab>

  <Tab title="Codex">
    * 新增供應商，配置寫入 `~/.codex/`
    * 或使用本地 `config.toml` / `auth.json`
    * 訂閱制賬號可先在終端 `codex login`
    * 可追加自訂模型，以及訊息 / MCP 環境變數
    * 可覆蓋 Codex CLI 路徑
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [Codex](/zh-Hant/desktop/providers/codex)。
  </Tab>

  <Tab title="Kimi">
    * 使用本地 `~/.kimi-code/config.toml`（可用 `$KIMI_CODE_HOME` 覆蓋）
    * 或新增第三方供應商：名稱、Base URL、API Key、模型。啟用後會寫入該 `config.toml`（先備份為 `config.toml.bak`）
    * 供應商型別：Kimi Code 官方 / OpenAI 相容 / Anthropic 相容
    * 快捷預設：Kimi Code（官方）、Moonshot 開放平臺
    * 可覆蓋 Kimi CLI 路徑
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [Kimi](/zh-Hant/desktop/providers/kimi)。
  </Tab>

  <Tab title="Grok">
    * 使用本地 `~/.grok/config.toml`（可用 `$GROK_HOME` 覆蓋）
    * 或新增第三方供應商：名稱、Base URL、API Key、模型。啟用後會寫入該 `config.toml`（先備份為 `config.toml.bak`）
    * API 後端：Chat Completions / Responses / Messages（Anthropic）
    * 快捷預設：xAI（官方）
    * 可覆蓋 Grok CLI 路徑
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [Grok](/zh-Hant/desktop/providers/grok)。
  </Tab>

  <Tab title="OpenCode">
    * 使用本地 `~/.config/opencode/opencode.json`（優先 `$OPENCODE_CONFIG`）
    * 或新增第三方供應商：名稱、Base URL、API Key、模型列表。託管供應商走環境注入，**不改** `opencode.json`
    * 快捷預設：OpenCode Zen（官方）
    * 可覆蓋 OpenCode CLI 路徑，也可把該引擎移到 **未啟用**
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [OpenCode](/zh-Hant/desktop/providers/opencode)。
  </Tab>

  <Tab title="Pi">
    * 認證寫在 `~/.pi/agent/auth.json`（許可權 `0600`）
    * 可填 API Key：Anthropic、OpenAI、Gemini、DeepSeek、xAI、OpenRouter 等
    * 訂閱授權點 **登入**：客戶端開啟內建終端啟動 `pi`，再傳送 `/login anthropic` 這類命令。也可以自己在系統終端執行 `pi /login`。客戶端不代你走 OAuth，只讀 `auth.json` 狀態
    * 解析順序：`--api-key` → `auth.json` → 環境變數 → `models.json`
    * 可覆蓋 Pi CLI 路徑
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [Pi](/zh-Hant/desktop/providers/pi)。
  </Tab>

  <Tab title="DeepSeek Harness">
    * 客戶端連的是本機 DSH 宿主，不是再配一套 API Key
    * 填 **主機**（預設 `127.0.0.1`）和 **埠**（預設 `3080`）
    * 可開啟 **自動啟動主機**
    * 模型和 API Key 在 DSH Web UI 裡配，點 **開啟 DSH 設定**
    * 可覆蓋 DSH 二進位制路徑
    * 未安裝時在該頁點 **安裝**，或按該引擎頁的終端命令安裝

    細節見 [DeepSeek Harness](/zh-Hant/desktop/providers/dsh)。
  </Tab>
</Tabs>

各引擎的完整說明在側欄 **供應商 / CLI** 分組，檢測與 PATH 排障見 [檢測與安裝](/zh-Hant/desktop/providers/cli)。

<Warning>
  API Key 只存在你這臺電腦上。截圖或錄屏前先打碼。
</Warning>

## 3. 安裝 CLI

客戶端**不會靜默代裝**任何 CLI。你可以在 **CLI配置管理** 裡點 **安裝** / **更新**（會先出示計劃，確認後再執行），也可以自己在系統終端裝好，再回到設定裡重新檢測。

各引擎的安裝命令寫在對應頁面，避免這裡再抄一份：

| 引擎               | 安裝說明                                                    |
| ---------------- | ------------------------------------------------------- |
| Claude Code      | [安裝](/zh-Hant/desktop/providers/claude#安裝)              |
| Codex            | [安裝](/zh-Hant/desktop/providers/codex#安裝)               |
| Kimi             | [安裝](/zh-Hant/desktop/providers/kimi#安裝)                |
| Grok             | [安裝](/zh-Hant/desktop/providers/grok#安裝)（Windows 用 WSL） |
| OpenCode         | [安裝](/zh-Hant/desktop/providers/opencode#安裝)            |
| Pi               | [安裝](/zh-Hant/desktop/providers/pi#安裝)                  |
| DeepSeek Harness | [安裝](/zh-Hant/desktop/providers/dsh#安裝)                 |

檢測失敗、PATH、自訂路徑見 [檢測與安裝](/zh-Hant/desktop/providers/cli)。

## 4. 核心配置路徑

| 路徑                                 | 用途                   |
| ---------------------------------- | -------------------- |
| `~/.ccgui`                         | CCGUI 配置資訊           |
| `~/.claude/settings.json`          | Claude Code CLI 配置檔案 |
| `~/.codex/config.toml`、`auth.json` | Codex CLI 配置檔案       |
| `~/.kimi-code/config.toml`         | Kimi CLI 配置檔案        |
| `~/.grok/config.toml`              | Grok CLI 配置檔案        |
| `~/.config/opencode/opencode.json` | OpenCode CLI 配置檔案    |
| `~/.pi/agent/auth.json`            | Pi CLI 配置檔案          |

## 5. 新增專案工作區

客戶端用「工作區 / 專案」組織會話與檔案：

1. 開啟首頁
2. 點 **新增新專案**
3. 選擇本地資料夾
4. 確認後進入該工作區

<img src="https://mintcdn.com/mossx-docs/kz4nt5KFSKzkAZwe/images/desktop/home-workspace.png?fit=max&auto=format&n=kz4nt5KFSKzkAZwe&q=85&s=5353bc1c92edd044ecd422fafe657f24" alt="首頁工作區選擇" width="360" data-path="images/desktop/home-workspace.png" />

沒有工作區時，檔案引用、Git 面板和專案記憶都缺少根目錄。

## 6. 自動更新

客戶端內建更新器，更新源指向 GitHub Releases 的 `latest.json`。有新版本時按提示安裝即可。

下一步：[發出第一條訊息](/zh-Hant/desktop/start/first-task)。