From 7c4d947400c08a11811aac1c7aac6798cbdccb2e Mon Sep 17 00:00:00 2001
From: sususu98 <suchangshan@foxmail.com>
Date: Wed, 25 Feb 2026 17:13:22 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20API=20=E5=88=86?=
 =?UTF-8?q?=E7=BB=84=E8=AF=B4=E6=98=8E=E3=80=81=E5=AE=A2=E6=88=B7=E7=AB=AF?=
 =?UTF-8?q?=E6=8E=A8=E8=8D=90=E5=8F=8A=E9=87=8D=E5=90=AF=E7=BB=88=E7=AB=AF?=
 =?UTF-8?q?=E6=8F=90=E9=86=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 文档新增 ccmax/cc2api 分组说明：cc2api 推荐优先使用（Claude 系列，无客户端限制），ccmax 仅限 Claude Code
- 推荐 OpenCode、OpenClaw 作为 cc2api 客户端，GPT 模型推荐 v1/responses 端点
- Cherry Studio 兼容性说明更新：支持所有模型，仅 ccmax 分组 Claude 模型不可用
- 所有脚本重启终端提示改为中文
- 三个工具文档页及快速开始页添加重启终端 warning 框
---
 CLAUDE.md                        |  60 +++++++++++++-
 ClaudeCode/setup-claude-code.ps1 | 134 +------------------------------
 ClaudeCode/setup-claude-code.sh  | 116 ++------------------------
 GeminiCLI/setup-gemini.ps1       |   2 +-
 GeminiCLI/setup-gemini.sh        |   2 +-
 codex/setup-codex.ps1            |   2 +-
 codex/setup-codex.sh             |   2 +-
 docs/cherry-studio-nanobana.md   |  14 ++--
 docs/guide/claude-code.md        |   8 ++
 docs/guide/codex.md              |   6 ++
 docs/guide/gemini-cli.md         |   6 ++
 docs/guide/index.md              |  39 +++++++++
 docs/index.md                    |  43 ++++++++--
 setup-claude-code.ps1            | 134 +------------------------------
 setup-claude-code.sh             | 116 ++------------------------
 setup.ps1                        |  78 ++++++++++++------
 setup.sh                         |  64 +++++++++++----
 17 files changed, 283 insertions(+), 543 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 20d248e..ddd0f03 100644
--- 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 系列不支持
diff --git a/ClaudeCode/setup-claude-code.ps1 b/ClaudeCode/setup-claude-code.ps1
index 3e49887..779f75c 100644
--- 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
diff --git a/ClaudeCode/setup-claude-code.sh b/ClaudeCode/setup-claude-code.sh
index 24d4d95..7f37ae7 100644
--- 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
diff --git a/GeminiCLI/setup-gemini.ps1 b/GeminiCLI/setup-gemini.ps1
index 115874f..ea585e3 100644
--- 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
diff --git a/GeminiCLI/setup-gemini.sh b/GeminiCLI/setup-gemini.sh
index de9f3ab..9ca1187 100755
--- 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
diff --git a/codex/setup-codex.ps1 b/codex/setup-codex.ps1
index 7c1887e..610ec5f 100644
--- 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
diff --git a/codex/setup-codex.sh b/codex/setup-codex.sh
index 1bea3fe..e09f241 100644
--- 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
diff --git a/docs/cherry-studio-nanobana.md b/docs/cherry-studio-nanobana.md
index 405c345..5ed77dd 100644
--- 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` 端点
diff --git a/docs/guide/claude-code.md b/docs/guide/claude-code.md
index 9484b7e..2873459 100644
--- 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 密钥。
+:::
 
 ## 手动配置说明
 
diff --git a/docs/guide/codex.md b/docs/guide/codex.md
index 1311f9a..7770dda 100644
--- 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 窗口
+:::
 
 ## 手动配置说明
 
diff --git a/docs/guide/gemini-cli.md b/docs/guide/gemini-cli.md
index b7730f6..694a78c 100644
--- 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 窗口
+:::
 
 ## 手动配置说明
 
diff --git a/docs/guide/index.md b/docs/guide/index.md
index b00ce47..5194fe2 100644
--- 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，请勿用于其他客户端。
+:::
diff --git a/docs/index.md b/docs/index.md
index c1068f2..bdc0729 100644
--- 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 配置文件位置
diff --git a/setup-claude-code.ps1 b/setup-claude-code.ps1
index 3e49887..779f75c 100644
--- 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
diff --git a/setup-claude-code.sh b/setup-claude-code.sh
index 24d4d95..7f37ae7 100644
--- 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
diff --git a/setup.ps1 b/setup.ps1
index 352e1c5..ca97a93 100644
--- 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
-    }
 }
 
 # ========== 远程配置脚本调用 ==========
diff --git a/setup.sh b/setup.sh
index d4c231d..dc94d69 100755
--- 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}"