📚 Claude Code 使用指南

Claude Code 是 Anthropic 官方推出的 AI 編程助手，支持通過 cch 代理服務使用。本指南將幫助您在不同操作系統上完成安裝和配置。

macOS

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：使用 Homebrew（推薦）

# 更新 Homebrew
brew update
# 安装 Node.js
brew install node

方法二：官網下載

  1. 訪問 https://nodejs.org/ https://nodejs.org/
  2. 下載適合 macOS 的 LTS 版本（需 v18 或更高）
  3. 打開下載的 .pkg 文件，按照安裝嚮導完成

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 claude claude

官方推薦使用 Native 安裝方式，具有以下優勢：

  • 單個可執行文件，無需 Node.js 依賴
  • 自動更新機制更穩定
  • 啟動速度更快

方法一：Homebrew（推薦）

brew install --cask claude-code

自動更新說明

通過 Homebrew 安裝的 Claude Code 會在 brew 目錄外自動更新，除非使用 DISABLE_AUTOUPDATER 環境變量顯式禁用。

方法二：curl 腳本

# 安装稳定版（默认）
curl -fsSL https://claude.ai/install.sh | bash

# 安装最新版
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 安装指定版本
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

驗證安裝

安裝完成後，運行以下命令驗證：

claude --version

如果顯示版本號，恭喜！Claude Code 已成功安裝。

提示

安裝前請確保移除任何過期的別名或符號鏈接。使用 claude doctor 命令可以檢查安裝類型和版本。

連接 cch 服務

方法一：settings.json 配置（推薦）

配置文件路徑：

~/.claude/settings.json

路徑說明

  • Windows：C:/Users/你的用戶名/.claude
  • Linux 或 macOS：~/.claude
  • 如果 settings.json 文件不存在，請自行創建

編輯 settings.json 文件，添加以下內容：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "當前站點地址",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

重要提示

  • 將 your-api-key-here 替換為您的實際 API 密鑰
  • 密鑰獲取方式：登錄控制台 → API 密鑰管理 → 創建密鑰

方法二：環境變量配置

臨時設置（當前會話）：

export ANTHROPIC_BASE_URL="當前站點地址"
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"

永久設置：

添加到您的 shell 配置文件（$~/.zshrc 或 ~/.bash_profile）：

echo 'export ANTHROPIC_BASE_URL="當前站點地址"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

驗證配置

配置完成後，驗證環境變量是否設置成功：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

預期輸出示例：

當前站點地址
sk_xxxxxxxxxxxxxxxxxx

注意

如果輸出為空或顯示變量名本身，說明環境變量設置失敗，請重新按照上述步驟設置。

VS Code 擴展配置

設定檔路徑：~/.claude

  1. 在 VS Code 擴展中搜索並安裝 Claude Code for VS Code
  2. 在 ~/.claude 目錄下創建 config.json 文件（如果沒有）
  3. 添加以下內容：
// Path: ~/.claude
{
  "primaryApiKey": "any-value"
}

注意

  • 是 config.json，不是 settings.json
  • primaryApiKey 字段值可以為任意內容，只要存在即可

啟動 claude

在項目目錄下運行：

cd /path/to/your/project
claude

首次啟動時，claude 會進行初始化配置。

常見問題

1. 命令未找到

# 檢查 npm 全局安裝路徑並添加到 PATH（如果不在）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API 連接失敗

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

# 测试网络连接
curl -I 當前站點地址

3. 更新 claude

npm install -g @anthropic-ai/claude-code

Windows

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：官網下載（推薦）

  1. 訪問 https://nodejs.org/ https://nodejs.org/
  2. 下載 LTS 版本（需 v18 或更高）
  3. 雙擊 .msi 文件，按嚮導安裝（保持默認設置）

方法二：使用包管理器

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

提示

建議使用 PowerShell 而不是 CMD，以獲得更好的體驗

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 claude claude

官方推薦使用 Native 安裝方式，具有以下優勢：

  • 單個可執行文件，無需 Node.js 依賴
  • 自動更新機制更穩定
  • 啟動速度更快

方法一：PowerShell

# 安裝穩定版（默認）
irm https://claude.ai/install.ps1 | iex

# 安裝最新版
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# 安裝指定版本
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

方法二：CMD

REM 安裝穩定版（默認）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

REM 安裝最新版
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd

REM 安裝指定版本
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd

驗證安裝

安裝完成後，運行以下命令驗證：

claude --version

如果顯示版本號，恭喜！Claude Code 已成功安裝。

提示

安裝前請確保移除任何過期的別名或符號鏈接。使用 claude doctor 命令可以檢查安裝類型和版本。

連接 cch 服務

方法一：settings.json 配置（推薦）

配置文件路徑：

C:\Users\你的用户名\.claude\settings.json

路徑說明

  • Windows：C:/Users/你的用戶名/.claude
  • Linux 或 macOS：~/.claude
  • 如果 settings.json 文件不存在，請自行創建

編輯 settings.json 文件，添加以下內容：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "當前站點地址",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

重要提示

  • 將 your-api-key-here 替換為您的實際 API 密鑰
  • 密鑰獲取方式：登錄控制台 → API 密鑰管理 → 創建密鑰

方法二：環境變量配置

臨時設置（當前會話）：

$env:ANTHROPIC_BASE_URL = "當前站點地址"
$env:ANTHROPIC_AUTH_TOKEN = "your-api-key-here"

永久設置（用戶級）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "當前站點地址", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your-api-key-here", [System.EnvironmentVariableTarget]::User)

設置後需要重新打開 PowerShell 窗口才能生效。

驗證配置

配置完成後，驗證環境變量是否設置成功：

在 PowerShell 中執行：

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN

在 CMD 中執行：

echo %ANTHROPIC_BASE_URL%
echo %ANTHROPIC_AUTH_TOKEN%

預期輸出示例：

當前站點地址
sk_xxxxxxxxxxxxxxxxxx

注意

如果輸出為空或顯示變量名本身，說明環境變量設置失敗，請重新按照上述步驟設置。

VS Code 擴展配置

設定檔路徑：C:\Users\你的用户名\.claude

  1. 在 VS Code 擴展中搜索並安裝 Claude Code for VS Code
  2. 在 ~/.claude 目錄下創建 config.json 文件（如果沒有）
  3. 添加以下內容：
// Path: C:\Users\你的用户名\.claude
{
  "primaryApiKey": "any-value"
}

注意

  • 是 config.json，不是 settings.json
  • primaryApiKey 字段值可以為任意內容，只要存在即可

啟動 claude

在項目目錄下運行：

cd C:\path\to\your\project
claude

首次啟動時，claude 會進行初始化配置。

常見問題

1. 命令未找到

  • 確保 npm 全局路徑（通常是 C:\Users\你的用戶名\AppData\Roaming\npm）已添加到系統 PATH
  • 重新打開 PowerShell 窗口

2. API 連接失敗

# 检查环境变量
echo $env:ANTHROPIC_AUTH_TOKEN

# 测试网络连接
Test-NetConnection -ComputerName 當前站點地址 -Port 443

3. 更新 claude

npm install -g @anthropic-ai/claude-code

Linux

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：使用官方倉庫（推薦）

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系統包管理器

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 claude claude

官方推薦使用 Native 安裝方式，具有以下優勢：

  • 單個可執行文件，無需 Node.js 依賴
  • 自動更新機制更穩定
  • 啟動速度更快

curl 腳本安裝

# 安裝穩定版（默認）
curl -fsSL https://claude.ai/install.sh | bash

# 安裝最新版
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 安裝指定版本
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Alpine Linux 特殊說明

基於 musl/uClibc 的發行版（如 Alpine Linux）需要安裝額外依賴：

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

驗證安裝

安裝完成後，運行以下命令驗證：

claude --version

如果顯示版本號，恭喜！Claude Code 已成功安裝。

提示

安裝前請確保移除任何過期的別名或符號鏈接。使用 claude doctor 命令可以檢查安裝類型和版本。

連接 cch 服務

方法一：settings.json 配置（推薦）

配置文件路徑：

~/.claude/settings.json

路徑說明

  • Windows：C:/Users/你的用戶名/.claude
  • Linux 或 macOS：~/.claude
  • 如果 settings.json 文件不存在，請自行創建

編輯 settings.json 文件，添加以下內容：

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "當前站點地址",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

重要提示

  • 將 your-api-key-here 替換為您的實際 API 密鑰
  • 密鑰獲取方式：登錄控制台 → API 密鑰管理 → 創建密鑰

方法二：環境變量配置

臨時設置（當前會話）：

export ANTHROPIC_BASE_URL="當前站點地址"
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"

永久設置：

添加到您的 shell 配置文件（$~/.bashrc 或 ~/.zshrc）：

echo 'export ANTHROPIC_BASE_URL="當前站點地址"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

驗證配置

配置完成後，驗證環境變量是否設置成功：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

預期輸出示例：

當前站點地址
sk_xxxxxxxxxxxxxxxxxx

注意

如果輸出為空或顯示變量名本身，說明環境變量設置失敗，請重新按照上述步驟設置。

VS Code 擴展配置

設定檔路徑：~/.claude

  1. 在 VS Code 擴展中搜索並安裝 Claude Code for VS Code
  2. 在 ~/.claude 目錄下創建 config.json 文件（如果沒有）
  3. 添加以下內容：
// Path: ~/.claude
{
  "primaryApiKey": "any-value"
}

注意

  • 是 config.json，不是 settings.json
  • primaryApiKey 字段值可以為任意內容，只要存在即可

啟動 claude

在項目目錄下運行：

cd /path/to/your/project
claude

首次啟動時，claude 會進行初始化配置。

常見問題

1. 命令未找到

# 檢查 npm 全局安裝路徑並添加到 PATH（如果不在）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. API 連接失敗

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

# 测试网络连接
curl -I 當前站點地址

3. 更新 claude

npm install -g @anthropic-ai/claude-code

📚 Codex CLI 使用指南

Codex 是 OpenAI 官方的命令行 AI 編程助手，支持通過 cch 代理使用。注意：Codex 使用 OpenAI 兼容格式，端點需要包含 /v1 路徑。

macOS

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：使用 Homebrew（推薦）

# 更新 Homebrew
brew update
# 安装 Node.js
brew install node

方法二：官網下載

  1. 訪問 https://nodejs.org/ https://nodejs.org/
  2. 下載適合 macOS 的 LTS 版本（需 v18 或更高）
  3. 打開下載的 .pkg 文件，按照安裝嚮導完成

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 codex codex

執行：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

驗證安裝：

codex --version

連接 cch 服務

方法一：配置文件方式（推薦）

  1. 打開文件資源管理器，找到 ~/.codex 文件夾（不存在則創建）
  2. 創建 config.toml 文件
  3. 使用文本編輯器打開，添加以下內容：
model_provider = "cch"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"
disable_response_storage = true
sandbox_mode = "workspace-write"

[features]
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
unified_exec = false
streamable_shell = false
rmcp_client = true

[model_providers.cch]
name = "cch"
base_url = "當前站點地址/v1"
wire_api = "responses"
env_key = "CCH_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true
  1. 創建 auth.json 文件，添加：
{
  "OPENAI_API_KEY": "your-api-key-here"
}

重要提示

  • 將 your-api-key-here 替換為您的 cch API 密鑰
  • 注意：Codex 使用 OpenAI 兼容格式，端點包含 /v1 路徑

方法二：環境變量配置

設置環境變量：

echo 'export CCH_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

VS Code 擴展配置

  1. 在 VS Code 擴展中搜索並安裝 Codex – OpenAI's coding agent
  2. 確保已按照上述步驟配置好 config.toml 和 auth.json
  3. 設置環境變量 CCH_API_KEY

重要

env_key 只能是環境變量名稱（如 CCH_API_KEY），不能是完整的密鑰。如果直接填寫密鑰，會報錯找不到令牌或令牌配置錯誤。

啟動 codex

在項目目錄下運行：

cd /path/to/your/project
codex

首次啟動時，codex 會進行初始化配置。

常見問題

1. 命令未找到

# 檢查 npm 全局安裝路徑並添加到 PATH（如果不在）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API 連接失敗

# 检查环境变量
echo $CCH_API_KEY

# 测试网络连接
curl -I 當前站點地址

3. 更新 codex

npm i -g @openai/codex --registry=https://registry.npmmirror.com

Windows

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：官網下載（推薦）

  1. 訪問 https://nodejs.org/ https://nodejs.org/
  2. 下載 LTS 版本（需 v18 或更高）
  3. 雙擊 .msi 文件，按嚮導安裝（保持默認設置）

方法二：使用包管理器

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

提示

建議使用 PowerShell 而不是 CMD，以獲得更好的體驗

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 codex codex

以管理員身份運行 PowerShell，執行：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

驗證安裝：

codex --version

連接 cch 服務

方法一：配置文件方式（推薦）

  1. 打開文件資源管理器，找到 C:\Users\你的用户名\.codex 文件夾（不存在則創建）
  2. 創建 config.toml 文件
  3. 使用文本編輯器打開，添加以下內容：
model_provider = "cch"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"
disable_response_storage = true
sandbox_mode = "workspace-write"
windows_wsl_setup_acknowledged = true

[features]
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
unified_exec = false
streamable_shell = false
rmcp_client = true

[model_providers.cch]
name = "cch"
base_url = "當前站點地址/v1"
wire_api = "responses"
env_key = "CCH_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true
  1. 創建 auth.json 文件，添加：
{
  "OPENAI_API_KEY": "your-api-key-here"
}

重要提示

  • 將 your-api-key-here 替換為您的 cch API 密鑰
  • 注意：Codex 使用 OpenAI 兼容格式，端點包含 /v1 路徑

方法二：環境變量配置

在 PowerShell 中運行：

[System.Environment]::SetEnvironmentVariable("CCH_API_KEY", "your-api-key-here", [System.EnvironmentVariableTarget]::User)

設置後需要重新打開 PowerShell 窗口才能生效。

VS Code 擴展配置

  1. 在 VS Code 擴展中搜索並安裝 Codex – OpenAI's coding agent
  2. 確保已按照上述步驟配置好 config.toml 和 auth.json
  3. 設置環境變量 CCH_API_KEY

重要

env_key 只能是環境變量名稱（如 CCH_API_KEY），不能是完整的密鑰。如果直接填寫密鑰，會報錯找不到令牌或令牌配置錯誤。

啟動 codex

在項目目錄下運行：

cd C:\path\to\your\project
codex

首次啟動時，codex 會進行初始化配置。

常見問題

1. 命令未找到

  • 確保 npm 全局路徑（通常是 C:\Users\你的用戶名\AppData\Roaming\npm）已添加到系統 PATH
  • 重新打開 PowerShell 窗口

2. API 連接失敗

# 检查环境变量
echo $env:CCH_API_KEY

# 测试网络连接
Test-NetConnection -ComputerName 當前站點地址 -Port 443

3. 更新 codex

npm i -g @openai/codex --registry=https://registry.npmmirror.com

Linux

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：使用官方倉庫（推薦）

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系統包管理器

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 codex codex

執行：

npm i -g @openai/codex --registry=https://registry.npmmirror.com

驗證安裝：

codex --version

連接 cch 服務

方法一：配置文件方式（推薦）

  1. 打開文件資源管理器，找到 ~/.codex 文件夾（不存在則創建）
  2. 創建 config.toml 文件
  3. 使用文本編輯器打開，添加以下內容：
model_provider = "cch"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"
disable_response_storage = true
sandbox_mode = "workspace-write"

[features]
plan_tool = true
apply_patch_freeform = true
view_image_tool = true
web_search_request = true
unified_exec = false
streamable_shell = false
rmcp_client = true

[model_providers.cch]
name = "cch"
base_url = "當前站點地址/v1"
wire_api = "responses"
env_key = "CCH_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true
  1. 創建 auth.json 文件，添加：
{
  "OPENAI_API_KEY": "your-api-key-here"
}

重要提示

  • 將 your-api-key-here 替換為您的 cch API 密鑰
  • 注意：Codex 使用 OpenAI 兼容格式，端點包含 /v1 路徑

方法二：環境變量配置

設置環境變量：

echo 'export CCH_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

VS Code 擴展配置

  1. 在 VS Code 擴展中搜索並安裝 Codex – OpenAI's coding agent
  2. 確保已按照上述步驟配置好 config.toml 和 auth.json
  3. 設置環境變量 CCH_API_KEY

重要

env_key 只能是環境變量名稱（如 CCH_API_KEY），不能是完整的密鑰。如果直接填寫密鑰，會報錯找不到令牌或令牌配置錯誤。

啟動 codex

在項目目錄下運行：

cd /path/to/your/project
codex

首次啟動時，codex 會進行初始化配置。

常見問題

1. 命令未找到

# 檢查 npm 全局安裝路徑並添加到 PATH（如果不在）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. API 連接失敗

# 检查环境变量
echo $CCH_API_KEY

# 测试网络连接
curl -I 當前站點地址

3. 更新 codex

npm i -g @openai/codex --registry=https://registry.npmmirror.com

📚 Gemini CLI 使用指南

Gemini CLI 是 Google 官方的 AI 編程助手命令行工具，支持通過 cch 代理服務使用。本指南將幫助您在不同操作系統上完成安裝和配置。

macOS

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：使用 Homebrew（推薦）

# 更新 Homebrew
brew update
# 安装 Node.js
brew install node

方法二：官網下載

  1. 訪問 https://nodejs.org/ https://nodejs.org/
  2. 下載適合 macOS 的 LTS 版本（需 v18 或更高）
  3. 打開下載的 .pkg 文件，按照安裝嚮導完成

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 gemini gemini

確保您已安裝 Node.js 18 或更高版本，然後全局安裝 Gemini CLI：

npm install -g @google/gemini-cli

驗證安裝：

gemini --version

連接 cch 服務

方法一：配置文件方式（推薦）

創建配置目錄

Gemini CLI 的配置文件位於 ~/.gemini/ 目錄。

macOS / Linux：

mkdir -p ~/.gemini
創建 .env 配置文件

在 ~/.gemini/ 目錄下創建 .env 文件：

macOS / Linux：

nano ~/.gemini/.env

添加以下內容：

GOOGLE_GEMINI_BASE_URL=當前站點地址
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview
創建 settings.json 配置文件

在 ~/.gemini/ 目錄下創建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

這個配置文件啟用了 IDE 集成，並設置認證方式為 API Key。

參數說明

  • GOOGLE_GEMINI_BASE_URL: cch API 基礎地址
  • GEMINI_API_KEY: 您在 cch 控制台創建的 API 密鑰
  • GEMINI_MODEL: 使用的模型（默認為 gemini-2.5-pro）

重要提示

  • 將 YOUR_API_KEY_HERE 替換為您的實際 API 密鑰
  • 密鑰獲取方式：登錄控制台 → API 密鑰管理 → 創建密鑰

方法二：環境變量配置

如果您只想臨時使用，可以通過環境變量配置：

macOS / Linux：

export GOOGLE_GEMINI_BASE_URL="當前站點地址"
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-pro"

環境變量只在當前終端會話中有效。如需持久化配置，請使用配置文件方式。

啟動和驗證

啟動 Gemini CLI

進入您的項目目錄並啟動 Gemini CLI：

cd /path/to/your/project
gemini

首次啟動時，Gemini CLI 會讀取配置文件中的設置。

驗證配置

在 Gemini CLI 中嘗試發送一個簡單的請求測試連接：

你好，請幫我創建一個 Python 的 hello world 程序

如果 Gemini CLI 正常響應，說明配置成功！

使用 Agent Mode

Gemini CLI 支持 Agent Mode，可以自動規劃和執行複雜任務：

gemini --agent

在 Agent Mode 下，Gemini 會：

  • 自動分析任務需求
  • 制定執行計劃
  • 逐步執行並驗證結果
  • 根據反饋調整策略

常見問題

1. 命令未找到

# 檢查 npm 全局安裝路徑並添加到 PATH（如果不在）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. API 連接失敗

  • 檢查環境變量或配置文件中的 GEMINI_API_KEY 是否設置正確
  • 驗證 GOOGLE_GEMINI_BASE_URL 是否正確
  • 測試網絡連接

3. 更新 gemini

npm install -g @google/gemini-cli

Windows

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：官網下載（推薦）

  1. 訪問 https://nodejs.org/ https://nodejs.org/
  2. 下載 LTS 版本（需 v18 或更高）
  3. 雙擊 .msi 文件，按嚮導安裝（保持默認設置）

方法二：使用包管理器

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

提示

建議使用 PowerShell 而不是 CMD，以獲得更好的體驗

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 gemini gemini

確保您已安裝 Node.js 18 或更高版本，然後全局安裝 Gemini CLI：

npm install -g @google/gemini-cli

驗證安裝：

gemini --version

連接 cch 服務

方法一：配置文件方式（推薦）

創建配置目錄

Gemini CLI 的配置文件位於 ~/.gemini/ 目錄。

Windows (PowerShell)：

mkdir $env:USERPROFILE\.gemini
創建 .env 配置文件

在 ~/.gemini/ 目錄下創建 .env 文件：

Windows：在 %USERPROFILE%\.gemini\ 目錄下創建 .env 文件

添加以下內容：

GOOGLE_GEMINI_BASE_URL=當前站點地址
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview
創建 settings.json 配置文件

在 ~/.gemini/ 目錄下創建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

這個配置文件啟用了 IDE 集成，並設置認證方式為 API Key。

參數說明

  • GOOGLE_GEMINI_BASE_URL: cch API 基礎地址
  • GEMINI_API_KEY: 您在 cch 控制台創建的 API 密鑰
  • GEMINI_MODEL: 使用的模型（默認為 gemini-2.5-pro）

重要提示

  • 將 YOUR_API_KEY_HERE 替換為您的實際 API 密鑰
  • 密鑰獲取方式：登錄控制台 → API 密鑰管理 → 創建密鑰

方法二：環境變量配置

如果您只想臨時使用，可以通過環境變量配置：

Windows (PowerShell)：

$env:GOOGLE_GEMINI_BASE_URL="當前站點地址"
$env:GEMINI_API_KEY="your-api-key-here"
$env:GEMINI_MODEL="gemini-2.5-pro"

Windows (CMD)：

set GOOGLE_GEMINI_BASE_URL=當前站點地址
set GEMINI_API_KEY=your-api-key-here
set GEMINI_MODEL=gemini-3-pro-preview

環境變量只在當前終端會話中有效。如需持久化配置，請使用配置文件方式。

啟動和驗證

啟動 Gemini CLI

進入您的項目目錄並啟動 Gemini CLI：

cd C:\path\to\your\project
gemini

首次啟動時，Gemini CLI 會讀取配置文件中的設置。

驗證配置

在 Gemini CLI 中嘗試發送一個簡單的請求測試連接：

你好，請幫我創建一個 Python 的 hello world 程序

如果 Gemini CLI 正常響應，說明配置成功！

使用 Agent Mode

Gemini CLI 支持 Agent Mode，可以自動規劃和執行複雜任務：

gemini --agent

在 Agent Mode 下，Gemini 會：

  • 自動分析任務需求
  • 制定執行計劃
  • 逐步執行並驗證結果
  • 根據反饋調整策略

常見問題

1. 命令未找到

  • 確保 npm 全局路徑（通常是 C:\Users\你的用戶名\AppData\Roaming\npm）已添加到系統 PATH
  • 重新打開 PowerShell 窗口

2. API 連接失敗

  • 檢查環境變量或配置文件中的 GEMINI_API_KEY 是否設置正確
  • 驗證 GOOGLE_GEMINI_BASE_URL 是否正確
  • 測試網絡連接

3. 更新 gemini

npm install -g @google/gemini-cli

Linux

環境準備：安裝 Node.js

claude 需要 Node.js 環境才能運行（需 v18 或更高版本）。

方法一：使用官方倉庫（推薦）

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs

方法二：使用系統包管理器

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

安裝完成後，打開終端/命令行，輸入以下命令驗證：

node --version
npm --version

如果顯示版本號，說明安裝成功了！

安裝 gemini gemini

確保您已安裝 Node.js 18 或更高版本，然後全局安裝 Gemini CLI：

npm install -g @google/gemini-cli

驗證安裝：

gemini --version

連接 cch 服務

方法一：配置文件方式（推薦）

創建配置目錄

Gemini CLI 的配置文件位於 ~/.gemini/ 目錄。

macOS / Linux：

mkdir -p ~/.gemini
創建 .env 配置文件

在 ~/.gemini/ 目錄下創建 .env 文件：

macOS / Linux：

nano ~/.gemini/.env

添加以下內容：

GOOGLE_GEMINI_BASE_URL=當前站點地址
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview
創建 settings.json 配置文件

在 ~/.gemini/ 目錄下創建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

這個配置文件啟用了 IDE 集成，並設置認證方式為 API Key。

參數說明

  • GOOGLE_GEMINI_BASE_URL: cch API 基礎地址
  • GEMINI_API_KEY: 您在 cch 控制台創建的 API 密鑰
  • GEMINI_MODEL: 使用的模型（默認為 gemini-2.5-pro）

重要提示

  • 將 YOUR_API_KEY_HERE 替換為您的實際 API 密鑰
  • 密鑰獲取方式：登錄控制台 → API 密鑰管理 → 創建密鑰

方法二：環境變量配置

如果您只想臨時使用，可以通過環境變量配置：

macOS / Linux：

export GOOGLE_GEMINI_BASE_URL="當前站點地址"
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-pro"

環境變量只在當前終端會話中有效。如需持久化配置，請使用配置文件方式。

啟動和驗證

啟動 Gemini CLI

進入您的項目目錄並啟動 Gemini CLI：

cd /path/to/your/project
gemini

首次啟動時，Gemini CLI 會讀取配置文件中的設置。

驗證配置

在 Gemini CLI 中嘗試發送一個簡單的請求測試連接：

你好，請幫我創建一個 Python 的 hello world 程序

如果 Gemini CLI 正常響應，說明配置成功！

使用 Agent Mode

Gemini CLI 支持 Agent Mode，可以自動規劃和執行複雜任務：

gemini --agent

在 Agent Mode 下，Gemini 會：

  • 自動分析任務需求
  • 制定執行計劃
  • 逐步執行並驗證結果
  • 根據反饋調整策略

常見問題

1. 命令未找到

# 檢查 npm 全局安裝路徑並添加到 PATH（如果不在）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. API 連接失敗

  • 檢查環境變量或配置文件中的 GEMINI_API_KEY 是否設置正確
  • 驗證 GOOGLE_GEMINI_BASE_URL 是否正確
  • 測試網絡連接

3. 更新 gemini

npm install -g @google/gemini-cli

📚 Droid CLI 使用指南

Droid 是 Factory AI 開發的交互式終端 AI 編程助手，支持通過 cch 代理服務使用。使用前必須先註冊並登錄 Droid 官方賬號。

macOS

安裝 droid droid

執行：

curl -fsSL https://app.factory.ai/cli | sh

連接 cch 服務

前置步驟：必須先登錄 Droid 官方賬號

  1. 運行 droid 命令
  2. 按提示通過瀏覽器登錄 Factory 官方賬號
  3. 登錄成功後，才能繼續配置自定義模型

配置自定義模型

配置文件路徑：

~/.factory/config.json

編輯配置文件，添加以下內容：

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [cch]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "當前站點地址",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5-Codex [cch]",
      "model": "gpt-5-codex",
      "base_url": "當前站點地址/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

重要說明

  • 將 your-api-key-here 替換為您的 cch API 密鑰
  • Anthropic 格式：使用 當前站點地址（無 /v1）
  • OpenAI 格式：使用 當前站點地址/v1（需要 /v1）

切換模型

  1. 重啟 Droid
  2. 輸入 /model 命令
  3. 選擇 GPT-5-Codex [cch] 或 Sonnet 4.5 [cch]
  4. 開始使用！

啟動 droid

在項目目錄下運行以下命令：

cd /path/to/your/project
droid

首次啟動時，droid 會進行初始化配置。

常見問題

1. 找不到命令

# 檢查 npm 全局安裝路徑，並添加到 PATH（如果尚未添加）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 更新 droid

重新運行安裝腳本即可更新到最新版本。

Windows

安裝 droid droid

在 PowerShell 中執行：

irm https://app.factory.ai/cli/windows | iex

連接 cch 服務

前置步驟：必須先登錄 Droid 官方賬號

  1. 運行 droid 命令
  2. 按提示通過瀏覽器登錄 Factory 官方賬號
  3. 登錄成功後，才能繼續配置自定義模型

配置自定義模型

配置文件路徑：

%USERPROFILE%\.factory\config.json

編輯配置文件，添加以下內容：

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [cch]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "當前站點地址",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5-Codex [cch]",
      "model": "gpt-5-codex",
      "base_url": "當前站點地址/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

重要說明

  • 將 your-api-key-here 替換為您的 cch API 密鑰
  • Anthropic 格式：使用 當前站點地址（無 /v1）
  • OpenAI 格式：使用 當前站點地址/v1（需要 /v1）

切換模型

  1. 重啟 Droid
  2. 輸入 /model 命令
  3. 選擇 GPT-5-Codex [cch] 或 Sonnet 4.5 [cch]
  4. 開始使用！

啟動 droid

在項目目錄下運行以下命令：

cd C:\path\to\your\project
droid

首次啟動時，droid 會進行初始化配置。

常見問題

1. 找不到命令

  • 確保 npm 全局路徑（通常為 C:\Users\your-username\AppData\Roaming\npm）已添加到系統 PATH
  • 重新打開 PowerShell 窗口

2. 更新 droid

重新運行安裝腳本即可更新到最新版本。

Linux

安裝 droid droid

執行：

curl -fsSL https://app.factory.ai/cli | sh

提示

Linux 用戶需確保已安裝 xdg-utils：

sudo apt-get install xdg-utils

連接 cch 服務

前置步驟：必須先登錄 Droid 官方賬號

  1. 運行 droid 命令
  2. 按提示通過瀏覽器登錄 Factory 官方賬號
  3. 登錄成功後，才能繼續配置自定義模型

配置自定義模型

配置文件路徑：

~/.factory/config.json

編輯配置文件，添加以下內容：

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [cch]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "當前站點地址",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5-Codex [cch]",
      "model": "gpt-5-codex",
      "base_url": "當前站點地址/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

重要說明

  • 將 your-api-key-here 替換為您的 cch API 密鑰
  • Anthropic 格式：使用 當前站點地址（無 /v1）
  • OpenAI 格式：使用 當前站點地址/v1（需要 /v1）

切換模型

  1. 重啟 Droid
  2. 輸入 /model 命令
  3. 選擇 GPT-5-Codex [cch] 或 Sonnet 4.5 [cch]
  4. 開始使用！

啟動 droid

在項目目錄下運行以下命令：

cd /path/to/your/project
droid

首次啟動時，droid 會進行初始化配置。

常見問題

1. 找不到命令

# 檢查 npm 全局安裝路徑，並添加到 PATH（如果尚未添加）
npm config get prefix

# 添加到 PATH（如果不在）
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

2. 更新 droid

重新運行安裝腳本即可更新到最新版本。

📚 常用命令

啟動 Claude Code 後，您可以使用以下常用命令：

  • /help - 查看幫助信息
  • /clear - 清空對話歷史，開啟新對話
  • /compact - 總結當前對話
  • /cost - 查看當前對話已使用的金額
  • /model - 切換模型（Droid 專用）
  • 更多命令查看 官方文檔 更多命令查看 官方文檔

🔍 通用故障排查

安裝失敗

  • 檢查網絡連接是否正常
  • 確保有管理員權限（Windows）或使用 sudo（macOS / Linux）
  • 嘗試使用代理或鏡像源（npm 可使用 --registry 參數）

API 密鑰無效

  • 確認密鑰已正確複製（無多餘空格）
  • 檢查密鑰是否在有效期內
  • 驗證賬戶權限是否正常
  • 確認使用了正確的端點格式（Anthropic 無 /v1，OpenAI 有 /v1）

端點配置錯誤

  • Claude Code / Droid Anthropic 模型：使用 當前站點地址（無 /v1）
  • Codex / Droid OpenAI 模型：使用 當前站點地址/v1（必須包含 /v1）