docs: 更新 API 分组说明、客户端推荐及重启终端提醒

- 文档新增 ccmax/cc2api 分组说明：cc2api 推荐优先使用（Claude 系列，无客户端限制），ccmax 仅限 Claude Code - 推荐 OpenCode、OpenClaw 作为 cc2api 客户端，GPT 模型推荐 v1/responses 端点 - Cherry Studio 兼容性说明更新：支持所有模型，仅 ccmax 分组 Claude 模型不可用 - 所有脚本重启终端提示改为中文 - 三个工具文档页及快速开始页添加重启终端 warning 框
2026-02-25 17:13:22 +08:00
parent a443b11326
commit 7c4d947400
17 changed files with 283 additions and 543 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -11,13 +11,25 @@ XCodeCLI-Shells 是一个跨平台配置工具集，用于配置 **Claude Code**
 ```
 xcodecli-shells/
 ├── setup.ps1                    # Windows 统一启动器 (安装+配置三个工具)
+├── setup.sh                     # Unix 统一启动器
 ├── setup-claude-code.ps1/.sh    # Claude Code 配置脚本 (根目录副本)
 ├── ClaudeCode/
 │   └── setup-claude-code.ps1/.sh
 ├── GeminiCLI/
 │   └── setup-gemini.ps1/.sh
-└── codex/
-    └── setup-codex.ps1/.sh
+├── codex/
+│   └── setup-codex.ps1/.sh
+└── docs/                        # VitePress 文档站点
+    ├── .vitepress/config.ts      # VitePress 配置 (导航、侧边栏、主题)
+    ├── index.md                  # 首页 (VitePress home layout, 含 Vue 交互组件)
+    ├── cherry-studio-nanobana.md # Cherry Studio 图文配置教程
+    ├── assets/                   # 文档图片资源 (截图)
+    ├── guide/
+    │   ├── index.md              # 快速开始总览页
+    │   ├── claude-code.md        # Claude Code 单独配置指南
+    │   ├── gemini-cli.md         # Gemini CLI 单独配置指南
+    │   └── codex.md              # Codex 单独配置指南
+    └── package.json              # 文档依赖 (vitepress ^1.5.0)
 ```

 ## 三个工具的配置差异
@@ -28,13 +40,22 @@ xcodecli-shells/
 | Gemini CLI  | `~/.gemini/.env`                     | ENV 文件    | `x-goog-api-key`        |
 | Codex       | `~/.codex/config.toml` + `auth.json` | TOML + JSON | `Authorization: Bearer` |

+## 工具安装方式差异
+
+| 工具 | 安装方式 | 依赖 |
+| ---- | ---- | ---- |
+| Claude Code | 官方原生脚本 `curl -fsSL https://claude.ai/install.sh \| bash` | 无需 Node.js，自动更新 |
+| Gemini CLI | `npm install -g @google/gemini-cli@latest` | **需要 Node.js >= 20** |
+| Codex | `npm install -g @openai/codex` | **需要 Node.js >= 20** |
+
 ## 统一启动器 (setup.ps1 / setup.sh)

 跨平台一站式安装配置工具：

- 检测 Node.js 环境，缺失时使用 fnm 安装
+- 检测 Node.js 环境，缺失时使用 fnm 安装 (Gemini CLI / Codex 需要)
 - 显示三个工具的安装状态
- 自动安装缺失的工具 (`npm install -g`)
+- Claude Code 使用官方原生安装脚本 (`curl -fsSL https://claude.ai/install.sh | bash`)
+- Gemini CLI / Codex 使用 `npm install -g` 安装 (需要 Node.js >= 20)
 - 下载并执行对应工具的配置脚本

 ```powershell
@@ -95,3 +116,34 @@ powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1 -ApiKey test-key

 - Claude/Codex: 检查 `response.data` 或 `response.models` 数组
 - Gemini: 检查 `response.models` 数组 (Google API 格式)
+
+## 文档站点 (docs/)
+
+基于 **VitePress** 的静态文档站点，语言为 `zh-CN`。
+
+### 开发命令
+
+```bash
+# 在 docs/ 目录下执行
+bun run dev      # 本地开发服务器
+bun run build    # 构建静态站点
+bun run preview  # 预览构建结果
+```
+
+### 站点结构
+
+| 页面          | 文件                             | 说明                                                                          |
+| ------------- | -------------------------------- | ----------------------------------------------------------------------------- |
+| 首页          | `docs/index.md`                  | VitePress home layout，含 Vue `<script setup>` 交互组件 (Tab 切换 + 一键复制) |
+| 快速开始      | `docs/guide/index.md`            | 全自动一键配置说明 + 各工具单独配置入口                                       |
+| Claude Code   | `docs/guide/claude-code.md`      | Claude Code 安装配置指南                                                      |
+| Gemini CLI    | `docs/guide/gemini-cli.md`       | Gemini CLI 安装配置指南                                                       |
+| Codex         | `docs/guide/codex.md`            | Codex 安装配置指南                                                            |
+| Cherry Studio | `docs/cherry-studio-nanobana.md` | Cherry Studio 图文教程 (仅支持 Gemini 模型)                                   |
+
+### 文档开发注意事项
+
+- 首页 `index.md` 包含 Vue SFC 代码 (`<script setup>` + `<style>`)，修改时注意保持 VitePress 兼容性
+- 图片资源放在 `docs/assets/`，文件名可含中文
+- 侧边栏和导航配置在 `.vitepress/config.ts` 中维护
+- Cherry Studio 页面强调 **仅支持 Gemini 模型**，Claude/GPT 系列不支持
--- a/ClaudeCode/setup-claude-code.ps1
+++ b/ClaudeCode/setup-claude-code.ps1
@@ -18,7 +18,6 @@ $DefaultBaseUrl = "https://api2.xcodecli.com"
 $ClaudeConfigDir = "$env:USERPROFILE\.claude"
 $ClaudeSettingsFile = "$ClaudeConfigDir\settings.json"
 $ToolCommand = "claude"
-$ToolPackage = "@anthropic-ai/claude-code"
 $ToolName = "Claude Code"

 # ========== 工具函数 ==========
@@ -69,139 +68,14 @@ function Write-Error {
    Write-Host " $Message"
 }

-# ========== Node.js 环境检测 ==========
-function Get-NodeVersion {
-    if (Test-Command "node") {
-        try {
-            $versionStr = (& node --version 2>$null) -replace 'v', ''
-            $major = [int]($versionStr -split '\.')[0]
-            return @{ Version = $versionStr; Major = $major }
-        }
-        catch { }
-    }
-    return $null
-}
-
-function Install-Fnm {
-    Write-Host ""
-    Write-Info "正在安装 fnm (Fast Node Manager)..."
-
-    try {
-        if (Test-Command "winget") {
-            Write-Info "使用 winget 安装 fnm..."
-            & winget install Schniz.fnm -e --accept-source-agreements --accept-package-agreements
-        }
-        else {
-            Write-Info "使用 PowerShell 脚本安装 fnm..."
-            Invoke-Expression "& { $(Invoke-RestMethod https://fnm.vercel.app/install.ps1) }"
-        }
-
-        Refresh-Path
-
-        if (Test-Command "fnm") {
-            Write-Success "fnm 安装成功!"
-            $fnmEnv = & fnm env --use-on-cd 2>$null
-            if ($fnmEnv) {
-                $fnmEnv | Out-String | Invoke-Expression
-            }
-            return $true
-        }
-        else {
-            Write-Warning "fnm 可能已安装，但需要重新打开终端才能生效"
-            Write-Info "请重新打开 PowerShell 后再运行此脚本"
-            return $false
-        }
-    }
-    catch {
-        Write-Error "fnm 安装失败: $($_.Exception.Message)"
-        return $false
-    }
-}
-
-function Install-NodeWithFnm {
-    Write-Info "使用 fnm 安装 Node.js 24.x..."
-
-    try {
-        & fnm install 24
-        & fnm use 24
-        & fnm default 24
-        Refresh-Path
-
-        if (Test-Command "node") {
-            $nodeInfo = Get-NodeVersion
-            Write-Success "Node.js v$($nodeInfo.Version) 安装成功!"
-            return $true
-        }
-        else {
-            Write-Warning "Node.js 可能已安装，但需要重新打开终端才能生效"
-            return $false
-        }
-    }
-    catch {
-        Write-Error "Node.js 安装失败: $($_.Exception.Message)"
-        return $false
-    }
-}
-
-function Ensure-NodeEnvironment {
-    $nodeInfo = Get-NodeVersion
-
-    if ($nodeInfo) {
-        Write-Info "检测到 Node.js v$($nodeInfo.Version)"
-
-        if ($nodeInfo.Major -lt 20) {
-            Write-Warning "Node.js 版本过低 (需要 >= 20.x)"
-
-            $upgrade = Read-Host "是否使用 fnm 安装 Node.js 24.x? (Y/n)"
-            if ($upgrade -eq "n" -or $upgrade -eq "N") {
-                Write-Error "Node.js 版本不满足要求，请手动升级后重试"
-                return $false
-            }
-
-            if (-not (Test-Command "fnm")) {
-                if (-not (Install-Fnm)) { return $false }
-            }
-
-            return Install-NodeWithFnm
-        }
-
-        return $true
-    }
-
-    Write-Warning "未检测到 Node.js"
-    Write-Info "将使用 fnm 安装 Node.js 24.x"
-
-    $install = Read-Host "是否继续? (Y/n)"
-    if ($install -eq "n" -or $install -eq "N") {
-        return $false
-    }
-
-    if (-not (Test-Command "fnm")) {
-        if (-not (Install-Fnm)) { return $false }
-    }
-
-    return Install-NodeWithFnm
-}
-
 function Install-Tool {
-    if (-not (Ensure-NodeEnvironment)) {
-        return $false
-    }
-
-    Write-Info "使用 npm 安装 $ToolName..."
-    $installCmd = "npm install -g $ToolPackage"
-    Write-Host "  执行: $installCmd" -ForegroundColor Gray
+    Write-Info "使用官方安装脚本安装 $ToolName..."
+    Write-Host "  执行: irm https://claude.ai/install.ps1 | iex" -ForegroundColor Gray

    try {
-        Invoke-Expression $installCmd
-        $exitCode = $LASTEXITCODE
+        Invoke-Expression "& { $(Invoke-RestMethod https://claude.ai/install.ps1) }"
        Refresh-Path

-        if ($exitCode -ne 0) {
-            Write-Error "安装命令返回错误码: $exitCode"
-            return $false
-        }
-
        if (Test-Command $ToolCommand) {
            Write-Success "$ToolName 安装成功!"
            return $true
@@ -529,7 +403,7 @@ function Main {
        }

        Write-Host ""
-        Write-Warning "Please restart your terminal for environment variables to take effect."
+        Write-Warning "⚠️  请重启终端使环境变量生效，然后再启动 Claude Code"
    } else {
        Write-Error "Failed to create Claude Code settings"
        exit 1
--- a/ClaudeCode/setup-claude-code.sh
+++ b/ClaudeCode/setup-claude-code.sh
@@ -18,7 +18,6 @@ DEFAULT_BASE_URL="https://api2.xcodecli.com"
 CLAUDE_CONFIG_DIR="$HOME/.claude"
 CLAUDE_SETTINGS_FILE="$CLAUDE_CONFIG_DIR/settings.json"
 TOOL_COMMAND="claude"
-TOOL_PACKAGE="@anthropic-ai/claude-code"
 TOOL_NAME="Claude Code"

 # ========== Shell 环境变量配置 ==========
@@ -83,117 +82,14 @@ print_error() {
    echo -e "${RED}[ERROR]${NC} $1"
 }

-# ========== Node.js 环境检测 ==========
-get_node_version() {
-    if command -v node >/dev/null 2>&1; then
-        node --version 2>/dev/null | sed 's/v//'
-    fi
-}
-
-get_node_major_version() {
-    local version
-    version=$(get_node_version)
-    if [ -n "$version" ]; then
-        echo "$version" | cut -d. -f1
-    fi
-}
-
-install_fnm() {
-    echo ""
-    print_info "正在安装 fnm (Fast Node Manager)..."
-
-    if curl -fsSL https://fnm.vercel.app/install | bash; then
-        # 加载 fnm 环境
-        export PATH="$HOME/.local/share/fnm:$PATH"
-        if [ -f "$HOME/.local/share/fnm/fnm" ]; then
-            eval "$(~/.local/share/fnm/fnm env)"
-        fi
-
-        if command -v fnm >/dev/null 2>&1; then
-            print_success "fnm 安装成功!"
-            return 0
-        else
-            print_warning "fnm 可能已安装，但需要重新打开终端才能生效"
-            print_info "请重新打开终端后再运行此脚本"
-            return 1
-        fi
-    else
-        print_error "fnm 安装失败"
-        return 1
-    fi
-}
-
-install_node_with_fnm() {
-    print_info "使用 fnm 安装 Node.js 24.x..."
-
-    if fnm install 24 && fnm use 24 && fnm default 24; then
-        # 刷新 PATH
-        eval "$(fnm env)"
-
-        if command -v node >/dev/null 2>&1; then
-            local version
-            version=$(get_node_version)
-            print_success "Node.js v$version 安装成功!"
-            return 0
-        else
-            print_warning "Node.js 可能已安装，但需要重新打开终端才能生效"
-            return 1
-        fi
-    else
-        print_error "Node.js 安装失败"
-        return 1
-    fi
-}
-
-ensure_node_environment() {
-    local version major
-
-    version=$(get_node_version)
-    if [ -n "$version" ]; then
-        major=$(get_node_major_version)
-        print_info "检测到 Node.js v$version"
-
-        if [ "$major" -lt 20 ]; then
-            print_warning "Node.js 版本过低 (需要 >= 20.x)"
-
-            read -p "是否使用 fnm 安装 Node.js 24.x? (Y/n): " -r
-            if [[ $REPLY =~ ^[Nn]$ ]]; then
-                print_error "Node.js 版本不满足要求，请手动升级后重试"
-                return 1
-            fi
-
-            if ! command -v fnm >/dev/null 2>&1; then
-                install_fnm || return 1
-            fi
-
-            install_node_with_fnm || return 1
-        fi
-
-        return 0
-    fi
-
-    print_warning "未检测到 Node.js"
-    print_info "将使用 fnm 安装 Node.js 24.x"
-
-    read -p "是否继续? (Y/n): " -r
-    if [[ $REPLY =~ ^[Nn]$ ]]; then
-        return 1
-    fi
-
-    if ! command -v fnm >/dev/null 2>&1; then
-        install_fnm || return 1
-    fi
-
-    install_node_with_fnm || return 1
-}
-
 install_tool() {
-    ensure_node_environment || return 1
+    print_info "使用官方安装脚本安装 $TOOL_NAME..."
+    echo "  执行: curl -fsSL https://claude.ai/install.sh | bash"

-    print_info "使用 npm 安装 $TOOL_NAME..."
-    echo "  执行: npm install -g $TOOL_PACKAGE"
+    if bash -c 'set -o pipefail; curl -fsSL https://claude.ai/install.sh | bash'; then
+        export PATH="$HOME/.local/bin:$PATH"
+        hash -r 2>/dev/null || true

-    if npm install -g "$TOOL_PACKAGE"; then
        if command -v "$TOOL_COMMAND" >/dev/null 2>&1; then
            print_success "$TOOL_NAME 安装成功!"
            return 0
@@ -565,7 +461,7 @@ EOF
        fi

        echo
-        print_warning "Please restart your terminal or run 'source $(get_shell_rc)' for environment variables to take effect."
+        print_warning "⚠️  请重启终端（或执行 'source $(get_shell_rc)'）使环境变量生效，然后再启动 Claude Code"
    else
        print_error "Failed to create Claude Code settings"
        exit 1
--- a/GeminiCLI/setup-gemini.ps1
+++ b/GeminiCLI/setup-gemini.ps1
@@ -530,7 +530,7 @@ function Main {
        }

        Write-Host ""
-        Write-Warning "Please restart your terminal for environment variables to take effect."
+        Write-Warning "⚠️  请重启终端使环境变量生效，然后再启动 Gemini CLI"
    } else {
        Write-Error "Failed to create Gemini CLI settings"
        exit 1
--- a/GeminiCLI/setup-gemini.sh
+++ b/GeminiCLI/setup-gemini.sh
@@ -534,7 +534,7 @@ EOF
    fi

    echo
-    print_warning "Please restart your terminal or run 'source $(get_shell_rc)' for environment variables to take effect."
+    print_warning "⚠️  请重启终端（或执行 'source $(get_shell_rc)'）使环境变量生效，然后再启动 Gemini CLI"
 }

 # Run main function
--- a/codex/setup-codex.ps1
+++ b/codex/setup-codex.ps1
@@ -539,7 +539,7 @@ function Main {
        Show-Settings

        Write-Host ""
-        Write-Warning "Please restart your terminal for environment variables to take effect."
+        Write-Warning "⚠️  请重启终端使环境变量生效，然后再启动 Codex"
    } else {
        Write-Error "Failed to create Codex settings"
        exit 1
--- a/codex/setup-codex.sh
+++ b/codex/setup-codex.sh
@@ -553,7 +553,7 @@ main() {
    show_current_settings

    echo ""
-    print_warning "Please restart your terminal or run 'source $(get_shell_rc)' for environment variables to take effect."
+    print_warning "⚠️  请重启终端（或执行 'source $(get_shell_rc)'）使环境变量生效，然后再启动 Codex"
 }

 # Run main function
--- a/docs/cherry-studio-nanobana.md
+++ b/docs/cherry-studio-nanobana.md
@@ -81,13 +81,13 @@ Cherry Studio 是一款支持多服务商集成的 AI 对话客户端，目前

 ## 六、提醒

-> ⚠️ **特别注意以下模型的使用：**
+> ⚠️ **注意：** Cherry Studio 支持所有模型，但 **ccmax 分组的 Claude 模型不可用**（ccmax 只能用于 Claude Code）。请使用 cc2api 等其他分组。

-| 模型                 | 建议                                   |
-| -------------------- | -------------------------------------- |
-| **Claude 系列**      | 不要在这里用，去 Claude Code (CC) 使用 |
-| **GPT 5.1/5.2 系列** | 只能在 Codex 内使用                    |
-| **Gemini 系列**      | ✅ 推荐使用                            |
+| 模型 | 备注 |
+| --- | --- |
+| **Gemini 系列** | ✅ 完美支持 |
+| **Claude 系列** | ✅ 使用 **cc2api** 等分组即可（勿用 ccmax 分组） |
+| **GPT 系列** | ✅ 支持；推荐 `v1/responses` 端点 |

 ---

@@ -97,4 +97,4 @@ Cherry Studio 是一款支持多服务商集成的 AI 对话客户端，目前
 2. 添加提供商：名称填 `XCodeCLI`，类型选 `Gemini`
 3. 填写 API Key 和地址 `https://api2.xcodecli.com`
 4. 生成高清图时：关闭流式输出 + 配置自定义参数
-5. 优先使用 Gemini 系列模型，暂不支持 Claude、GPT 系列模型
+5. Cherry Studio 支持所有模型，但 ccmax 分组的 Claude 模型不可用；GPT 模型推荐使用 `v1/responses` 端点
--- a/docs/guide/claude-code.md
+++ b/docs/guide/claude-code.md
@@ -19,6 +19,14 @@ $key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/ra
 :::

 > 请将命令中的 `你的密钥` 替换为你的实际 API 密钥。
+::: warning ⚠️ 配置完成后请重启终端
+脚本会自动配置环境变量（`ANTHROPIC_AUTH_TOKEN` 等），但需要**重启终端**才能生效。
+
+- **macOS / Linux**：重新打开终端，或执行 `source ~/.zshrc`（或 `source ~/.bashrc`）
+- **Windows**：重新打开 PowerShell 窗口
+
+如果不重启，Claude Code 首次启动时可能无法读取 API 密钥。
+:::

 ## 手动配置说明

--- a/docs/guide/codex.md
+++ b/docs/guide/codex.md
@@ -19,6 +19,12 @@ $key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/ra
 :::

 > 请将命令中的 `你的密钥` 替换为你的实际 API 密钥。
+::: warning ⚠️ 配置完成后请重启终端
+脚本会自动配置环境变量，但需要**重启终端**才能生效。
+
+- **macOS / Linux**：重新打开终端，或执行 `source ~/.zshrc`（或 `source ~/.bashrc`）
+- **Windows**：重新打开 PowerShell 窗口
+:::

 ## 手动配置说明

--- a/docs/guide/gemini-cli.md
+++ b/docs/guide/gemini-cli.md
@@ -19,6 +19,12 @@ $key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/ra
 :::

 > 请将命令中的 `你的密钥` 替换为你的实际 API 密钥。
+::: warning ⚠️ 配置完成后请重启终端
+脚本会自动配置环境变量，但需要**重启终端**才能生效。
+
+- **macOS / Linux**：重新打开终端，或执行 `source ~/.zshrc`（或 `source ~/.bashrc`）
+- **Windows**：重新打开 PowerShell 窗口
+:::

 ## 手动配置说明

--- a/docs/guide/index.md
+++ b/docs/guide/index.md
@@ -32,6 +32,13 @@ $key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/ra

 > 💡 **提示**：请将命令中的 `你的密钥` 替换为你的实际 API 密钥。

+::: warning ⚠️ 配置完成后请重启终端
+脚本会自动写入环境变量，但需要**重启终端**才能生效。否则工具首次启动时可能无法读取 API 密钥。
+
+- **macOS / Linux**：重新打开终端，或执行 `source ~/.zshrc`（或 `source ~/.bashrc`）
+- **Windows**：重新打开 PowerShell 窗口
+:::
+
 ### 脚本执行流程

 1. **环境检测**：检查 Node.js 等必要运行时。如果缺失，脚本会尝试引导安装（如 fnm）。
@@ -56,3 +63,35 @@ $key='你的密钥'; iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/ra
 2. `https://api.xcodecli.com` (备用)

 所有的工具都会统一配置使用同一个有效的 API 端点。
+
+## API 分组说明
+
+XCodeCLI 提供两个 API 分组，适用于不同的使用场景：
+
+### cc2api — 推荐使用
+
+- **包含模型**：Claude 系列
+- **适用客户端**：无限制，所有支持 OpenAI 兼容 API 的客户端均可使用（包括 Claude Code）
+- **特点**：**所有客户端优先选择此分组**
+
+推荐搭配以下客户端使用：
+
+| 客户端 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| **[OpenCode](https://opencode.ai/)** | 终端 AI 编码代理 | 开源，支持 75+ LLM 供应商，Claude Code 的最佳替代方案。提供终端、桌面端和 IDE 插件 |
+| **[OpenClaw](https://openclaw.ai/)** | 个人 AI 助手 | 开源，连接 WhatsApp / Telegram / Slack 等消息平台，支持浏览器自动化、邮件、日历等操作 |
+| **[Cherry Studio](https://www.cherry-ai.com/)** | 可视化对话客户端 | 多服务商集成，详见 [配置教程](/cherry-studio-nanobana) |
+
+::: tip 💡 GPT 系列模型
+GPT 系列模型推荐使用 `v1/responses` 端点以获得最佳效果。
+:::
+
+### ccmax — 仅限 Claude Code
+
+- **包含模型**：Claude 系列（与 cc2api 相同）
+- **适用客户端**：**只能**用于 Claude Code
+- **何时使用**：Claude Code 使用 cc2api 遇到兼容性问题时再切换
+
+::: danger ⚠️ 注意
+ccmax **只能**用于 Claude Code，请勿用于其他客户端。
+:::
--- a/docs/index.md
+++ b/docs/index.md
@@ -69,7 +69,7 @@ function copyCommand() {
  </div>
 </div>

-<p class="tip">💡 提示：运行前请将命令中的 <code>你的密钥</code> 替换为实际 API Key</p>
+<p class="tip">💡 提示：运行前请将命令中的 <code>你的密钥</code> 替换为实际 API Key。<strong>配置完成后请重启终端</strong>，否则工具可能无法读取 API 密钥。</p>

 </div>

@@ -79,13 +79,9 @@ function copyCommand() {

 <p class="desc">在 Cherry Studio 中使用 XCodeCLI 服务，享受可视化的对话体验。</p>

-::: danger ⚠️ 重要提示：模型兼容性
-**Cherry Studio 仅支持 Gemini 系列模型！**
-
- ❌ **Claude 模型**：暂不支持在 Cherry Studio 中使用（请在 Claude Code 内使用）
- ❌ **GPT 模型**：暂不支持在 Cherry Studio 中使用（请在 Codex 内使用）
- ✅ **Gemini 模型**：完美支持
-  :::
+::: tip 💡 Cherry Studio 模型兼容性
+Cherry Studio 支持所有模型，但注意 **ccmax 分组的 Claude 模型不可用**（ccmax 只能用于 Claude Code）。Claude 模型请使用 **cc2api** 分组。
+:::

 ### 配置参数

@@ -105,6 +101,37 @@ function copyCommand() {

 <div class="setup-section">

+## 2.5 API 分组说明
+
+<p class="desc">XCodeCLI 提供多个 API 分组，适用于不同的使用场景。</p>
+
+::: warning 🔑 分组区别
+- **cc2api 分组（推荐）**：提供 Claude 系列模型，无客户端限制，可自由搭配各种客户端
+- **ccmax 分组**：提供 Claude 系列模型，但**只能用于 Claude Code**
+:::
+
+### cc2api — 推荐使用
+
+cc2api 分组包含 **Claude 系列模型**，无客户端限制。推荐搭配以下工具：
+
+| 客户端 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| **[OpenCode](https://opencode.ai/)** | 终端 AI 编码代理 | 开源，支持 75+ LLM 供应商，可作为 Claude Code 的替代方案。支持终端、桌面端和 IDE 插件 |
+| **[OpenClaw](https://openclaw.ai/)** | 个人 AI 助手 | 开源，连接 WhatsApp / Telegram / Slack 等消息平台，支持浏览器自动化、邮件、日历等操作 |
+| **[Cherry Studio](https://www.cherry-ai.com/)** | 可视化对话客户端 | 支持多服务商集成，详见 [配置教程](/cherry-studio-nanobana) |
+
+::: tip 💡 GPT 系列模型
+GPT 系列模型推荐使用 `v1/responses` 端点以获得最佳效果。
+:::
+
+### ccmax — 仅限 Claude Code
+
+ccmax 分组同样提供 Claude 系列模型，但**只能**用于 Claude Code，不支持其他客户端。如果你使用 Claude Code 且 cc2api 遇到兼容性问题，可尝试切换到 ccmax。
+
+</div>
+
+<div class="setup-section">
+
 ## 3. 参考信息

 ### CLI 配置文件位置
--- a/setup-claude-code.ps1
+++ b/setup-claude-code.ps1
@@ -18,7 +18,6 @@ $DefaultBaseUrl = "https://api2.xcodecli.com"
 $ClaudeConfigDir = "$env:USERPROFILE\.claude"
 $ClaudeSettingsFile = "$ClaudeConfigDir\settings.json"
 $ToolCommand = "claude"
-$ToolPackage = "@anthropic-ai/claude-code"
 $ToolName = "Claude Code"

 # ========== 工具函数 ==========
@@ -69,139 +68,14 @@ function Write-Error {
    Write-Host " $Message"
 }

-# ========== Node.js 环境检测 ==========
-function Get-NodeVersion {
-    if (Test-Command "node") {
-        try {
-            $versionStr = (& node --version 2>$null) -replace 'v', ''
-            $major = [int]($versionStr -split '\.')[0]
-            return @{ Version = $versionStr; Major = $major }
-        }
-        catch { }
-    }
-    return $null
-}
-
-function Install-Fnm {
-    Write-Host ""
-    Write-Info "正在安装 fnm (Fast Node Manager)..."
-
-    try {
-        if (Test-Command "winget") {
-            Write-Info "使用 winget 安装 fnm..."
-            & winget install Schniz.fnm -e --accept-source-agreements --accept-package-agreements
-        }
-        else {
-            Write-Info "使用 PowerShell 脚本安装 fnm..."
-            Invoke-Expression "& { $(Invoke-RestMethod https://fnm.vercel.app/install.ps1) }"
-        }
-
-        Refresh-Path
-
-        if (Test-Command "fnm") {
-            Write-Success "fnm 安装成功!"
-            $fnmEnv = & fnm env --use-on-cd 2>$null
-            if ($fnmEnv) {
-                $fnmEnv | Out-String | Invoke-Expression
-            }
-            return $true
-        }
-        else {
-            Write-Warning "fnm 可能已安装，但需要重新打开终端才能生效"
-            Write-Info "请重新打开 PowerShell 后再运行此脚本"
-            return $false
-        }
-    }
-    catch {
-        Write-Error "fnm 安装失败: $($_.Exception.Message)"
-        return $false
-    }
-}
-
-function Install-NodeWithFnm {
-    Write-Info "使用 fnm 安装 Node.js 24.x..."
-
-    try {
-        & fnm install 24
-        & fnm use 24
-        & fnm default 24
-        Refresh-Path
-
-        if (Test-Command "node") {
-            $nodeInfo = Get-NodeVersion
-            Write-Success "Node.js v$($nodeInfo.Version) 安装成功!"
-            return $true
-        }
-        else {
-            Write-Warning "Node.js 可能已安装，但需要重新打开终端才能生效"
-            return $false
-        }
-    }
-    catch {
-        Write-Error "Node.js 安装失败: $($_.Exception.Message)"
-        return $false
-    }
-}
-
-function Ensure-NodeEnvironment {
-    $nodeInfo = Get-NodeVersion
-
-    if ($nodeInfo) {
-        Write-Info "检测到 Node.js v$($nodeInfo.Version)"
-
-        if ($nodeInfo.Major -lt 20) {
-            Write-Warning "Node.js 版本过低 (需要 >= 20.x)"
-
-            $upgrade = Read-Host "是否使用 fnm 安装 Node.js 24.x? (Y/n)"
-            if ($upgrade -eq "n" -or $upgrade -eq "N") {
-                Write-Error "Node.js 版本不满足要求，请手动升级后重试"
-                return $false
-            }
-
-            if (-not (Test-Command "fnm")) {
-                if (-not (Install-Fnm)) { return $false }
-            }
-
-            return Install-NodeWithFnm
-        }
-
-        return $true
-    }
-
-    Write-Warning "未检测到 Node.js"
-    Write-Info "将使用 fnm 安装 Node.js 24.x"
-
-    $install = Read-Host "是否继续? (Y/n)"
-    if ($install -eq "n" -or $install -eq "N") {
-        return $false
-    }
-
-    if (-not (Test-Command "fnm")) {
-        if (-not (Install-Fnm)) { return $false }
-    }
-
-    return Install-NodeWithFnm
-}
-
 function Install-Tool {
-    if (-not (Ensure-NodeEnvironment)) {
-        return $false
-    }
-
-    Write-Info "使用 npm 安装 $ToolName..."
-    $installCmd = "npm install -g $ToolPackage"
-    Write-Host "  执行: $installCmd" -ForegroundColor Gray
+    Write-Info "使用官方安装脚本安装 $ToolName..."
+    Write-Host "  执行: irm https://claude.ai/install.ps1 | iex" -ForegroundColor Gray

    try {
-        Invoke-Expression $installCmd
-        $exitCode = $LASTEXITCODE
+        Invoke-Expression "& { $(Invoke-RestMethod https://claude.ai/install.ps1) }"
        Refresh-Path

-        if ($exitCode -ne 0) {
-            Write-Error "安装命令返回错误码: $exitCode"
-            return $false
-        }
-
        if (Test-Command $ToolCommand) {
            Write-Success "$ToolName 安装成功!"
            return $true
@@ -529,7 +403,7 @@ function Main {
        }

        Write-Host ""
-        Write-Warning "Please restart your terminal for environment variables to take effect."
+        Write-Warning "⚠️  请重启终端使环境变量生效，然后再启动 Claude Code"
    } else {
        Write-Error "Failed to create Claude Code settings"
        exit 1
--- a/setup-claude-code.sh
+++ b/setup-claude-code.sh
@@ -18,7 +18,6 @@ DEFAULT_BASE_URL="https://api2.xcodecli.com"
 CLAUDE_CONFIG_DIR="$HOME/.claude"
 CLAUDE_SETTINGS_FILE="$CLAUDE_CONFIG_DIR/settings.json"
 TOOL_COMMAND="claude"
-TOOL_PACKAGE="@anthropic-ai/claude-code"
 TOOL_NAME="Claude Code"

 # ========== Shell 环境变量配置 ==========
@@ -83,117 +82,14 @@ print_error() {
    echo -e "${RED}[ERROR]${NC} $1"
 }

-# ========== Node.js 环境检测 ==========
-get_node_version() {
-    if command -v node >/dev/null 2>&1; then
-        node --version 2>/dev/null | sed 's/v//'
-    fi
-}
-
-get_node_major_version() {
-    local version
-    version=$(get_node_version)
-    if [ -n "$version" ]; then
-        echo "$version" | cut -d. -f1
-    fi
-}
-
-install_fnm() {
-    echo ""
-    print_info "正在安装 fnm (Fast Node Manager)..."
-
-    if curl -fsSL https://fnm.vercel.app/install | bash; then
-        # 加载 fnm 环境
-        export PATH="$HOME/.local/share/fnm:$PATH"
-        if [ -f "$HOME/.local/share/fnm/fnm" ]; then
-            eval "$(~/.local/share/fnm/fnm env)"
-        fi
-
-        if command -v fnm >/dev/null 2>&1; then
-            print_success "fnm 安装成功!"
-            return 0
-        else
-            print_warning "fnm 可能已安装，但需要重新打开终端才能生效"
-            print_info "请重新打开终端后再运行此脚本"
-            return 1
-        fi
-    else
-        print_error "fnm 安装失败"
-        return 1
-    fi
-}
-
-install_node_with_fnm() {
-    print_info "使用 fnm 安装 Node.js 24.x..."
-
-    if fnm install 24 && fnm use 24 && fnm default 24; then
-        # 刷新 PATH
-        eval "$(fnm env)"
-
-        if command -v node >/dev/null 2>&1; then
-            local version
-            version=$(get_node_version)
-            print_success "Node.js v$version 安装成功!"
-            return 0
-        else
-            print_warning "Node.js 可能已安装，但需要重新打开终端才能生效"
-            return 1
-        fi
-    else
-        print_error "Node.js 安装失败"
-        return 1
-    fi
-}
-
-ensure_node_environment() {
-    local version major
-
-    version=$(get_node_version)
-    if [ -n "$version" ]; then
-        major=$(get_node_major_version)
-        print_info "检测到 Node.js v$version"
-
-        if [ "$major" -lt 20 ]; then
-            print_warning "Node.js 版本过低 (需要 >= 20.x)"
-
-            read -p "是否使用 fnm 安装 Node.js 24.x? (Y/n): " -r
-            if [[ $REPLY =~ ^[Nn]$ ]]; then
-                print_error "Node.js 版本不满足要求，请手动升级后重试"
-                return 1
-            fi
-
-            if ! command -v fnm >/dev/null 2>&1; then
-                install_fnm || return 1
-            fi
-
-            install_node_with_fnm || return 1
-        fi
-
-        return 0
-    fi
-
-    print_warning "未检测到 Node.js"
-    print_info "将使用 fnm 安装 Node.js 24.x"
-
-    read -p "是否继续? (Y/n): " -r
-    if [[ $REPLY =~ ^[Nn]$ ]]; then
-        return 1
-    fi
-
-    if ! command -v fnm >/dev/null 2>&1; then
-        install_fnm || return 1
-    fi
-
-    install_node_with_fnm || return 1
-}
-
 install_tool() {
-    ensure_node_environment || return 1
+    print_info "使用官方安装脚本安装 $TOOL_NAME..."
+    echo "  执行: curl -fsSL https://claude.ai/install.sh | bash"

-    print_info "使用 npm 安装 $TOOL_NAME..."
-    echo "  执行: npm install -g $TOOL_PACKAGE"
+    if bash -c 'set -o pipefail; curl -fsSL https://claude.ai/install.sh | bash'; then
+        export PATH="$HOME/.local/bin:$PATH"
+        hash -r 2>/dev/null || true

-    if npm install -g "$TOOL_PACKAGE"; then
        if command -v "$TOOL_COMMAND" >/dev/null 2>&1; then
            print_success "$TOOL_NAME 安装成功!"
            return 0
@@ -565,7 +461,7 @@ EOF
        fi

        echo
-        print_warning "Please restart your terminal or run 'source $(get_shell_rc)' for environment variables to take effect."
+        print_warning "⚠️  请重启终端（或执行 'source $(get_shell_rc)'）使环境变量生效，然后再启动 Claude Code"
    else
        print_error "Failed to create Claude Code settings"
        exit 1
--- a/setup.ps1
+++ b/setup.ps1
@@ -200,39 +200,65 @@ function Install-Tool {
        [hashtable]$Tool
    )

-    # 确保 Node.js 环境就绪
-    if (-not (Ensure-NodeEnvironment)) {
-        return $false
+    if ($Tool.Command -eq "claude") {
+        # Claude Code: 使用官方原生安装脚本
+        Write-Info "使用官方安装脚本安装 $($Tool.Name)..."
+        Write-Host "  执行: irm https://claude.ai/install.ps1 | iex" -ForegroundColor Gray
+
+        try {
+            Invoke-Expression "& { $(Invoke-RestMethod https://claude.ai/install.ps1) }"
+            Refresh-Path
+
+            if (Test-Command $Tool.Command) {
+                Write-Success "$($Tool.Name) 安装成功!"
+                return $true
+            }
+            else {
+                Write-Warning "$($Tool.Name) 可能已安装，但需要重新打开终端才能生效"
+                $continue = Read-Host "是否继续进行配置? (Y/n)"
+                return ($continue -ne "n" -and $continue -ne "N")
+            }
+        }
+        catch {
+            Write-Error "安装失败: $($_.Exception.Message)"
+            return $false
+        }
    }
-
-    Write-Info "使用 npm 安装 $($Tool.Name)..."
-    $installCmd = "npm install -g $($Tool.Package)"
-    Write-Host "  执行: $installCmd" -ForegroundColor Gray
-
-    try {
-        Invoke-Expression $installCmd
-        $exitCode = $LASTEXITCODE
-        Refresh-Path
-
-        if ($exitCode -ne 0) {
-            Write-Error "安装命令返回错误码: $exitCode"
+    else {
+        # Gemini CLI / Codex: 使用 npm 安装 (需要 Node.js)
+        if (-not (Ensure-NodeEnvironment)) {
            return $false
        }

-        if (Test-Command $Tool.Command) {
-            Write-Success "$($Tool.Name) 安装成功!"
-            return $true
+        Write-Info "使用 npm 安装 $($Tool.Name)..."
+        $installCmd = "npm install -g $($Tool.Package)"
+        Write-Host "  执行: $installCmd" -ForegroundColor Gray
+
+        try {
+            Invoke-Expression $installCmd
+            $exitCode = $LASTEXITCODE
+            Refresh-Path
+
+            if ($exitCode -ne 0) {
+                Write-Error "安装命令返回错误码: $exitCode"
+                return $false
+            }
+
+            if (Test-Command $Tool.Command) {
+                Write-Success "$($Tool.Name) 安装成功!"
+                return $true
+            }
+            else {
+                Write-Warning "$($Tool.Name) 可能已安装，但需要重新打开终端才能生效"
+                $continue = Read-Host "是否继续进行配置? (Y/n)"
+                return ($continue -ne "n" -and $continue -ne "N")
+            }
        }
-        else {
-            Write-Warning "$($Tool.Name) 可能已安装，但需要重新打开终端才能生效"
-            $continue = Read-Host "是否继续进行配置? (Y/n)"
-            return ($continue -ne "n" -and $continue -ne "N")
+        catch {
+            Write-Error "安装失败: $($_.Exception.Message)"
+            return $false
        }
    }
-    catch {
-        Write-Error "安装失败: $($_.Exception.Message)"
-        return $false
-    }
 }

 # ========== 远程配置脚本调用 ==========
--- a/setup.sh
+++ b/setup.sh
@@ -364,17 +364,41 @@ install_tool() {
    local tool_pkg=$(get_tool_pkg "$tool_num")

    info "安装 $tool_name..."
-    local install_cmd="npm install -g $tool_pkg"

-    echo -e "  执行: ${CYAN}$install_cmd${NC}"
-
-    if eval "$install_cmd"; then
-        hash -r 2>/dev/null || true
-        success "$tool_name 安装成功!"
-        return 0
+    if [ "$tool_num" = "1" ]; then
+        # Claude Code: 使用官方原生安装脚本
+        local install_cmd="curl -fsSL https://claude.ai/install.sh | bash"
+        echo -e "  执行: ${CYAN}$install_cmd${NC}"
+        if bash -c 'set -o pipefail; curl -fsSL https://claude.ai/install.sh | bash'; then
+            export PATH="$HOME/.local/bin:$PATH"
+            hash -r 2>/dev/null || true
+            local tool_cmd=$(get_tool_cmd "$tool_num")
+            if command -v "$tool_cmd" >/dev/null 2>&1; then
+                success "$tool_name 安装成功!"
+                return 0
+            else
+                warning "$tool_name 可能已安装，但需要重新打开终端才能生效"
+                return 0
+            fi
+        else
+            error "$tool_name 安装失败 (请检查 https://claude.ai 是否可达)"
+            return 1
+        fi
    else
-        error "$tool_name 安装失败"
-        return 1
+        # Gemini CLI / Codex: 使用 npm 安装 (需要 Node.js)
+        if ! ensure_node_environment; then
+            return 1
+        fi
+        local install_cmd="npm install -g $tool_pkg"
+        echo -e "  执行: ${CYAN}$install_cmd${NC}"
+        if eval "$install_cmd"; then
+            hash -r 2>/dev/null || true
+            success "$tool_name 安装成功!"
+            return 0
+        else
+            error "$tool_name 安装失败"
+            return 1
+        fi
    fi
 }

@@ -387,7 +411,22 @@ configure_tool() {

    info "配置 $tool_name..."

-    if API_KEY="$api_key" bash -c "$(curl -fsSL "$setup_url")"; then
+    # 先下载脚本到临时文件，避免 curl 失败时空脚本静默执行
+    local tmp_script
+    tmp_script=$(mktemp) || { error "无法创建临时文件"; return 1; }
+    trap "rm -f '$tmp_script'" RETURN
+
+    if ! curl -fsSL "$setup_url" -o "$tmp_script"; then
+        error "下载 $tool_name 配置脚本失败 (请检查网络连接)"
+        return 1
+    fi
+
+    if [ ! -s "$tmp_script" ]; then
+        error "下载的配置脚本为空"
+        return 1
+    fi
+
+    if API_KEY="$api_key" bash "$tmp_script"; then
        success "$tool_name 配置完成!"
        return 0
    else
@@ -514,10 +553,7 @@ main() {
    info "API 密钥: ${api_key:0:8}..."
    echo ""

-    # 确保 Node.js 环境就绪
-    if ! ensure_node_environment; then
-        exit 1
-    fi
+    # Node.js 环境检查已移至 install_tool 内部 (仅 Gemini CLI / Codex 需要)

    echo ""
    echo -e "${CYAN}========================================${NC}"