> ## 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](/desktop/providers/claude)。
  </Tab>

  <Tab title="Codex">
    * 添加供应商，配置写入 `~/.codex/`
    * 或使用本地 `config.toml` / `auth.json`
    * 订阅制账号可先在终端 `codex login`
    * 可追加自定义模型，以及消息 / MCP 环境变量
    * 可覆盖 Codex CLI 路径
    * 未安装时在该页点 **安装**，或按该引擎页的终端命令安装

    细节见 [Codex](/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](/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](/desktop/providers/grok)。
  </Tab>

  <Tab title="OpenCode">
    * 使用本地 `~/.config/opencode/opencode.json`（优先 `$OPENCODE_CONFIG`）
    * 或添加第三方供应商：名称、Base URL、API Key、模型列表。托管供应商走环境注入，**不改** `opencode.json`
    * 快捷预设：OpenCode Zen（官方）
    * 可覆盖 OpenCode CLI 路径，也可把该引擎移到 **未启用**
    * 未安装时在该页点 **安装**，或按该引擎页的终端命令安装

    细节见 [OpenCode](/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](/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](/desktop/providers/dsh)。
  </Tab>
</Tabs>

各引擎的完整说明在侧栏 **供应商 / CLI** 分组，检测与 PATH 排障见 [检测与安装](/desktop/providers/cli)。

<Warning>
  API Key 只存在你这台电脑上。截图或录屏前先打码。
</Warning>

## 3. 安装 CLI

客户端**不会静默代装**任何 CLI。你可以在 **CLI配置管理** 里点 **安装** / **更新**（会先出示计划，确认后再执行），也可以自己在系统终端装好，再回到设置里重新检测。

各引擎的安装命令写在对应页面，避免这里再抄一份：

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

检测失败、PATH、自定义路径见 [检测与安装](/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`。有新版本时按提示安装即可。

下一步：[发出第一条消息](/desktop/start/first-task)。