📚 Claude Code Usage Guide

Claude Code is Anthropic's official AI programming assistant that supports integration through the cch proxy service. This guide will help you complete installation and configuration on different operating systems.

macOS

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using Homebrew (recommended)

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

Method 2: Download from official website

  1. Visit https://nodejs.org/ https://nodejs.org/
  2. Download the LTS version for macOS (v18 or higher required)
  3. Open the downloaded .pkg file and follow the installation wizard

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install claude claude

Officially recommended installation method with the following advantages:

  • Single executable file, no Node.js dependency
  • More stable auto-update mechanism
  • Faster startup speed

Method 1: Homebrew (recommended)

brew install --cask claude-code

Auto-update information

Claude Code installed via Homebrew will auto-update outside the brew directory unless explicitly disabled with the DISABLE_AUTOUPDATER environment variable.

Method 2: curl script

# 安装稳定版（默认）
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

Verify Installation

After installation, run the following command to verify:

claude --version

If the version number is displayed, congratulations! Claude Code has been successfully installed.

Tip

Before installation, make sure to remove any outdated aliases or symbolic links. Use the claude doctor command to check the installation type and version.

Connect to cch service

Method 1: settings.json configuration (recommended)

Configuration file path:

~/.claude/settings.json

Path explanation

  • Windows: C:/Users/your-username/.claude
  • Linux or macOS: ~/.claude
  • If the settings.json file does not exist, please create it

Edit the settings.json file and add the following content:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "Current site address",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Important note

  • Replace your-api-key-here with your actual API key
  • How to obtain key: Log in to console → API key management → Create key

Method 2: Environment variable configuration

Temporary setting (current session):

export ANTHROPIC_BASE_URL="Current site address"
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"

Permanent setting:

Add to your shell configuration file ($~/.zshrc 或 ~/.bash_profile):

echo 'export ANTHROPIC_BASE_URL="Current site address"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Verify configuration

After configuration, verify that the environment variables are set correctly:

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

Expected output example:

Current site address
sk_xxxxxxxxxxxxxxxxxx

Note

If the output is empty or shows the variable name itself, it means the environment variable setting failed. Please repeat the steps above.

VS Code Extension Configuration

Configuration file location: ~/.claude

  1. Search for and install Claude Code for VS Code in VS Code extensions
  2. Create a config.json file in the ~/.claude directory (if it doesn't exist)
  3. Add the following content:
// Path: ~/.claude
{
  "primaryApiKey": "any-value"
}

Note

  • It's config.json, not settings.json
  • The primaryApiKey field value can be anything as long as it exists

Start claude

Run the following command in your project directory:

cd /path/to/your/project
claude

During the first startup, claude will perform initial configuration.

Common questions

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. API connection failed

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

# 测试网络连接
curl -I Current site address

3. Update claude

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

Windows

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Download from official website (recommended)

  1. Visit https://nodejs.org/ https://nodejs.org/
  2. Download the LTS version (v18 or higher required)
  3. Double-click the .msi file and follow the installation wizard (keep default settings)

Method 2: Using package manager

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

Tip

It's recommended to use PowerShell instead of CMD for a better experience

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install claude claude

Officially recommended installation method with the following advantages:

  • Single executable file, no Node.js dependency
  • More stable auto-update mechanism
  • Faster startup speed

Method 1: PowerShell

# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Method 2: CMD

REM Install stable version (default)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

REM Install latest version
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd latest && del install.cmd

REM Install specific version
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd

Verify Installation

After installation, run the following command to verify:

claude --version

If the version number is displayed, congratulations! Claude Code has been successfully installed.

Tip

Before installation, make sure to remove any outdated aliases or symbolic links. Use the claude doctor command to check the installation type and version.

Connect to cch service

Method 1: settings.json configuration (recommended)

Configuration file path:

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

Path explanation

  • Windows: C:/Users/your-username/.claude
  • Linux or macOS: ~/.claude
  • If the settings.json file does not exist, please create it

Edit the settings.json file and add the following content:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "Current site address",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Important note

  • Replace your-api-key-here with your actual API key
  • How to obtain key: Log in to console → API key management → Create key

Method 2: Environment variable configuration

Temporary setting (current session):

$env:ANTHROPIC_BASE_URL = "Current site address"
$env:ANTHROPIC_AUTH_TOKEN = "your-api-key-here"

Permanent setting (user-level):

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "Current site address", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your-api-key-here", [System.EnvironmentVariableTarget]::User)

You need to reopen the PowerShell window for the settings to take effect.

Verify configuration

After configuration, verify that the environment variables are set correctly:

Execute in PowerShell:

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN

Execute in CMD:

echo %ANTHROPIC_BASE_URL%
echo %ANTHROPIC_AUTH_TOKEN%

Expected output example:

Current site address
sk_xxxxxxxxxxxxxxxxxx

Note

If the output is empty or shows the variable name itself, it means the environment variable setting failed. Please repeat the steps above.

VS Code Extension Configuration

Configuration file location: C:\Users\你的用户名\.claude

  1. Search for and install Claude Code for VS Code in VS Code extensions
  2. Create a config.json file in the ~/.claude directory (if it doesn't exist)
  3. Add the following content:
// Path: C:\Users\你的用户名\.claude
{
  "primaryApiKey": "any-value"
}

Note

  • It's config.json, not settings.json
  • The primaryApiKey field value can be anything as long as it exists

Start claude

Run the following command in your project directory:

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

During the first startup, claude will perform initial configuration.

Common questions

1. Command not found

  • Make sure the npm global path (usually C:\Users\your-username\AppData\Roaming\npm) has been added to the system PATH
  • Reopen the PowerShell window

2. API connection failed

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

# 测试网络连接
Test-NetConnection -ComputerName Current site address -Port 443

3. Update claude

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

Linux

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using official repository (recommended)

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

Method 2: Using system package manager

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

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install claude claude

Officially recommended installation method with the following advantages:

  • Single executable file, no Node.js dependency
  • More stable auto-update mechanism
  • Faster startup speed

curl script installation

# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Alpine Linux special notes

Distributions based on musl/uClibc (such as Alpine Linux) need to install additional dependencies:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Verify Installation

After installation, run the following command to verify:

claude --version

If the version number is displayed, congratulations! Claude Code has been successfully installed.

Tip

Before installation, make sure to remove any outdated aliases or symbolic links. Use the claude doctor command to check the installation type and version.

Connect to cch service

Method 1: settings.json configuration (recommended)

Configuration file path:

~/.claude/settings.json

Path explanation

  • Windows: C:/Users/your-username/.claude
  • Linux or macOS: ~/.claude
  • If the settings.json file does not exist, please create it

Edit the settings.json file and add the following content:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "Current site address",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Important note

  • Replace your-api-key-here with your actual API key
  • How to obtain key: Log in to console → API key management → Create key

Method 2: Environment variable configuration

Temporary setting (current session):

export ANTHROPIC_BASE_URL="Current site address"
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"

Permanent setting:

Add to your shell configuration file ($~/.bashrc 或 ~/.zshrc):

echo 'export ANTHROPIC_BASE_URL="Current site address"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Verify configuration

After configuration, verify that the environment variables are set correctly:

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

Expected output example:

Current site address
sk_xxxxxxxxxxxxxxxxxx

Note

If the output is empty or shows the variable name itself, it means the environment variable setting failed. Please repeat the steps above.

VS Code Extension Configuration

Configuration file location: ~/.claude

  1. Search for and install Claude Code for VS Code in VS Code extensions
  2. Create a config.json file in the ~/.claude directory (if it doesn't exist)
  3. Add the following content:
// Path: ~/.claude
{
  "primaryApiKey": "any-value"
}

Note

  • It's config.json, not settings.json
  • The primaryApiKey field value can be anything as long as it exists

Start claude

Run the following command in your project directory:

cd /path/to/your/project
claude

During the first startup, claude will perform initial configuration.

Common questions

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. API connection failed

# 检查环境变量
echo $ANTHROPIC_AUTH_TOKEN

# 测试网络连接
curl -I Current site address

3. Update claude

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

📚 Codex CLI Usage Guide

Codex is OpenAI's official command-line AI programming assistant that supports integration through the cch proxy. Note: Codex uses OpenAI-compatible format, the endpoint needs to include the /v1 path.

macOS

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using Homebrew (recommended)

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

Method 2: Download from official website

  1. Visit https://nodejs.org/ https://nodejs.org/
  2. Download the LTS version for macOS (v18 or higher required)
  3. Open the downloaded .pkg file and follow the installation wizard

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install codex codex

Execute:

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

Verify installation:

codex --version

Connect to cch service

Method 1: Configuration file method (recommended)

  1. Open file explorer, find the ~/.codex folder (create if it doesn't exist)
  2. Create a config.toml file
  3. Open with text editor and add the following content:
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 = "Current site address/v1"
wire_api = "responses"
env_key = "CCH_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true
  1. Create an auth.json file and add:
{
  "OPENAI_API_KEY": "your-api-key-here"
}

Important note

  • Replace your-api-key-here with your cch API key
  • Note: Codex uses OpenAI-compatible format, endpoint includes the /v1 path

Method 2: Environment variable configuration

Set environment variables:

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

VS Code Extension Configuration

  1. Search for and install Codex – OpenAI's coding agent in VS Code extensions
  2. Make sure you have configured config.toml and auth.json according to the steps above
  3. Set the CCH_API_KEY environment variable

Important

env_key can only be an environment variable name (such as CCH_API_KEY), not the complete key. If you directly fill in the key, it will report an error that the token is not found or the token configuration is incorrect.

Start codex

Run the following command in your project directory:

cd /path/to/your/project
codex

During the first startup, codex will perform initial configuration.

Common questions

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. API connection failed

# 检查环境变量
echo $CCH_API_KEY

# 测试网络连接
curl -I Current site address

3. Update codex

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

Windows

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Download from official website (recommended)

  1. Visit https://nodejs.org/ https://nodejs.org/
  2. Download the LTS version (v18 or higher required)
  3. Double-click the .msi file and follow the installation wizard (keep default settings)

Method 2: Using package manager

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

Tip

It's recommended to use PowerShell instead of CMD for a better experience

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install codex codex

Run PowerShell as administrator,Execute:

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

Verify installation:

codex --version

Connect to cch service

Method 1: Configuration file method (recommended)

  1. Open file explorer, find the C:\Users\你的用户名\.codex folder (create if it doesn't exist)
  2. Create a config.toml file
  3. Open with text editor and add the following content:
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 = "Current site address/v1"
wire_api = "responses"
env_key = "CCH_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true
  1. Create an auth.json file and add:
{
  "OPENAI_API_KEY": "your-api-key-here"
}

Important note

  • Replace your-api-key-here with your cch API key
  • Note: Codex uses OpenAI-compatible format, endpoint includes the /v1 path

Method 2: Environment variable configuration

Run in PowerShell:

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

You need to reopen the PowerShell window for the settings to take effect.

VS Code Extension Configuration

  1. Search for and install Codex – OpenAI's coding agent in VS Code extensions
  2. Make sure you have configured config.toml and auth.json according to the steps above
  3. Set the CCH_API_KEY environment variable

Important

env_key can only be an environment variable name (such as CCH_API_KEY), not the complete key. If you directly fill in the key, it will report an error that the token is not found or the token configuration is incorrect.

Start codex

Run the following command in your project directory:

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

During the first startup, codex will perform initial configuration.

Common questions

1. Command not found

  • Make sure the npm global path (usually C:\Users\your-username\AppData\Roaming\npm) has been added to the system PATH
  • Reopen the PowerShell window

2. API connection failed

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

# 测试网络连接
Test-NetConnection -ComputerName Current site address -Port 443

3. Update codex

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

Linux

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using official repository (recommended)

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

Method 2: Using system package manager

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

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install codex codex

Execute:

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

Verify installation:

codex --version

Connect to cch service

Method 1: Configuration file method (recommended)

  1. Open file explorer, find the ~/.codex folder (create if it doesn't exist)
  2. Create a config.toml file
  3. Open with text editor and add the following content:
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 = "Current site address/v1"
wire_api = "responses"
env_key = "CCH_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true
  1. Create an auth.json file and add:
{
  "OPENAI_API_KEY": "your-api-key-here"
}

Important note

  • Replace your-api-key-here with your cch API key
  • Note: Codex uses OpenAI-compatible format, endpoint includes the /v1 path

Method 2: Environment variable configuration

Set environment variables:

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

VS Code Extension Configuration

  1. Search for and install Codex – OpenAI's coding agent in VS Code extensions
  2. Make sure you have configured config.toml and auth.json according to the steps above
  3. Set the CCH_API_KEY environment variable

Important

env_key can only be an environment variable name (such as CCH_API_KEY), not the complete key. If you directly fill in the key, it will report an error that the token is not found or the token configuration is incorrect.

Start codex

Run the following command in your project directory:

cd /path/to/your/project
codex

During the first startup, codex will perform initial configuration.

Common questions

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. API connection failed

# 检查环境变量
echo $CCH_API_KEY

# 测试网络连接
curl -I Current site address

3. Update codex

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

📚 Gemini CLI Usage Guide

Gemini CLI is Google's official AI programming assistant command-line tool that supports integration through the cch proxy service. This guide will help you complete installation and configuration on different operating systems.

macOS

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using Homebrew (recommended)

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

Method 2: Download from official website

  1. Visit https://nodejs.org/ https://nodejs.org/
  2. Download the LTS version for macOS (v18 or higher required)
  3. Open the downloaded .pkg file and follow the installation wizard

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install gemini gemini

Make sure you have Node.js 18 or higher installed, then globally install Gemini CLI:

npm install -g @google/gemini-cli

Verify installation:

gemini --version

Connect to cch service

Method 1: Configuration File (Recommended)

Create configuration directory

Gemini CLI configuration files are located in the ~/.gemini/ directory.

macOS / Linux:

mkdir -p ~/.gemini
Create .env configuration file

Create the .env file in the ~/.gemini/ directory:

macOS / Linux:

nano ~/.gemini/.env

Add the following content:

GOOGLE_GEMINI_BASE_URL=Current site address
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview
Create settings.json configuration file

Create the settings.json file in the ~/.gemini/ directory:

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

This configuration file enables IDE integration and sets the authentication method to API Key.

Parameter description

  • GOOGLE_GEMINI_BASE_URL: cch API base URL
  • GEMINI_API_KEY: Your API key created in the cch console
  • GEMINI_MODEL: Model to use (default is gemini-2.5-pro)

Important

  • Replace YOUR_API_KEY_HERE with your actual API key
  • How to obtain the key: Log in to the console → API Key Management → Create Key

Method 2: Environment Variable Configuration

If you only want to use it temporarily, you can configure it via environment variables:

macOS / Linux:

export GOOGLE_GEMINI_BASE_URL="Current site address"
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-pro"

Environment variables are only valid for the current terminal session. For persistent configuration, use the configuration file method.

Startup and Verification

Start Gemini CLI

Navigate to your project directory and start Gemini CLI:

cd /path/to/your/project
gemini

On first startup, Gemini CLI will read the settings in the configuration file.

Verify Configuration

Try sending a simple request in Gemini CLI to test the connection:

Hello, please help me create a Python hello world program

If Gemini CLI responds normally, the configuration is successful!

Using Agent Mode

Gemini CLI supports Agent Mode, which can automatically plan and execute complex tasks:

gemini --agent

In Agent Mode, Gemini will:

  • Automatically analyze task requirements
  • Develop execution plans
  • Execute step by step and verify results
  • Adjust strategies based on feedback

Common Issues

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. API connection failed

  • Check if GEMINI_API_KEY in the environment variables or configuration file is set correctly
  • Verify if GOOGLE_GEMINI_BASE_URL is correct
  • Test network connection

3. Update gemini

npm install -g @google/gemini-cli

Windows

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Download from official website (recommended)

  1. Visit https://nodejs.org/ https://nodejs.org/
  2. Download the LTS version (v18 or higher required)
  3. Double-click the .msi file and follow the installation wizard (keep default settings)

Method 2: Using package manager

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

Tip

It's recommended to use PowerShell instead of CMD for a better experience

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install gemini gemini

Make sure you have Node.js 18 or higher installed, then globally install Gemini CLI:

npm install -g @google/gemini-cli

Verify installation:

gemini --version

Connect to cch service

Method 1: Configuration File (Recommended)

Create configuration directory

Gemini CLI configuration files are located in the ~/.gemini/ directory.

Windows (PowerShell):

mkdir $env:USERPROFILE\.gemini
Create .env configuration file

Create the .env file in the ~/.gemini/ directory:

Windows: Create the .env file in the %USERPROFILE%\.gemini\ directory

Add the following content:

GOOGLE_GEMINI_BASE_URL=Current site address
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview
Create settings.json configuration file

Create the settings.json file in the ~/.gemini/ directory:

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

This configuration file enables IDE integration and sets the authentication method to API Key.

Parameter description

  • GOOGLE_GEMINI_BASE_URL: cch API base URL
  • GEMINI_API_KEY: Your API key created in the cch console
  • GEMINI_MODEL: Model to use (default is gemini-2.5-pro)

Important

  • Replace YOUR_API_KEY_HERE with your actual API key
  • How to obtain the key: Log in to the console → API Key Management → Create Key

Method 2: Environment Variable Configuration

If you only want to use it temporarily, you can configure it via environment variables:

Windows (PowerShell):

$env:GOOGLE_GEMINI_BASE_URL="Current site address"
$env:GEMINI_API_KEY="your-api-key-here"
$env:GEMINI_MODEL="gemini-2.5-pro"

Windows (CMD):

set GOOGLE_GEMINI_BASE_URL=Current site address
set GEMINI_API_KEY=your-api-key-here
set GEMINI_MODEL=gemini-3-pro-preview

Environment variables are only valid for the current terminal session. For persistent configuration, use the configuration file method.

Startup and Verification

Start Gemini CLI

Navigate to your project directory and start Gemini CLI:

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

On first startup, Gemini CLI will read the settings in the configuration file.

Verify Configuration

Try sending a simple request in Gemini CLI to test the connection:

Hello, please help me create a Python hello world program

If Gemini CLI responds normally, the configuration is successful!

Using Agent Mode

Gemini CLI supports Agent Mode, which can automatically plan and execute complex tasks:

gemini --agent

In Agent Mode, Gemini will:

  • Automatically analyze task requirements
  • Develop execution plans
  • Execute step by step and verify results
  • Adjust strategies based on feedback

Common Issues

1. Command not found

  • Make sure the npm global path (usually C:\Users\your-username\AppData\Roaming\npm) has been added to the system PATH
  • Reopen the PowerShell window

2. API connection failed

  • Check if GEMINI_API_KEY in the environment variables or configuration file is set correctly
  • Verify if GOOGLE_GEMINI_BASE_URL is correct
  • Test network connection

3. Update gemini

npm install -g @google/gemini-cli

Linux

Environment Setup: Install Node.js

claude requires Node.js runtime (v18 or higher).

Method 1: Using official repository (recommended)

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

Method 2: Using system package manager

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

# CentOS/RHEL/Fedora
sudo dnf install nodejs npm

After installation, open terminal/command line and run the following commands to verify:

node --version
npm --version

If version numbers are displayed, the installation was successful!

Install gemini gemini

Make sure you have Node.js 18 or higher installed, then globally install Gemini CLI:

npm install -g @google/gemini-cli

Verify installation:

gemini --version

Connect to cch service

Method 1: Configuration File (Recommended)

Create configuration directory

Gemini CLI configuration files are located in the ~/.gemini/ directory.

macOS / Linux:

mkdir -p ~/.gemini
Create .env configuration file

Create the .env file in the ~/.gemini/ directory:

macOS / Linux:

nano ~/.gemini/.env

Add the following content:

GOOGLE_GEMINI_BASE_URL=Current site address
GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-3-pro-preview
Create settings.json configuration file

Create the settings.json file in the ~/.gemini/ directory:

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

This configuration file enables IDE integration and sets the authentication method to API Key.

Parameter description

  • GOOGLE_GEMINI_BASE_URL: cch API base URL
  • GEMINI_API_KEY: Your API key created in the cch console
  • GEMINI_MODEL: Model to use (default is gemini-2.5-pro)

Important

  • Replace YOUR_API_KEY_HERE with your actual API key
  • How to obtain the key: Log in to the console → API Key Management → Create Key

Method 2: Environment Variable Configuration

If you only want to use it temporarily, you can configure it via environment variables:

macOS / Linux:

export GOOGLE_GEMINI_BASE_URL="Current site address"
export GEMINI_API_KEY="your-api-key-here"
export GEMINI_MODEL="gemini-2.5-pro"

Environment variables are only valid for the current terminal session. For persistent configuration, use the configuration file method.

Startup and Verification

Start Gemini CLI

Navigate to your project directory and start Gemini CLI:

cd /path/to/your/project
gemini

On first startup, Gemini CLI will read the settings in the configuration file.

Verify Configuration

Try sending a simple request in Gemini CLI to test the connection:

Hello, please help me create a Python hello world program

If Gemini CLI responds normally, the configuration is successful!

Using Agent Mode

Gemini CLI supports Agent Mode, which can automatically plan and execute complex tasks:

gemini --agent

In Agent Mode, Gemini will:

  • Automatically analyze task requirements
  • Develop execution plans
  • Execute step by step and verify results
  • Adjust strategies based on feedback

Common Issues

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. API connection failed

  • Check if GEMINI_API_KEY in the environment variables or configuration file is set correctly
  • Verify if GOOGLE_GEMINI_BASE_URL is correct
  • Test network connection

3. Update gemini

npm install -g @google/gemini-cli

📚 Droid CLI Usage Guide

Droid is an interactive terminal AI programming assistant developed by Factory AI that supports integration through the cch proxy service. You must register and log in to your Droid official account before use.

macOS

Install droid droid

Execute:

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

Connect to cch service

Prerequisite: Must log in to Droid official account first

  1. Run the droid command
  2. Follow the prompts to log in to Factory official account via browser
  3. After successful login, you can continue to configure custom models

Configure custom models

Configuration file path:

~/.factory/config.json

Edit the configuration file and add the following content:

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [cch]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "Current site address",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5-Codex [cch]",
      "model": "gpt-5-codex",
      "base_url": "Current site address/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

Important notes

  • Replace your-api-key-here with your cch API key
  • Anthropic format: Use Current site address (no /v1)
  • OpenAI format: Use Current site address/v1 (requires /v1)

Switch models

  1. Restart Droid
  2. Enter the /model command
  3. Select GPT-5-Codex [cch] or Sonnet 4.5 [cch]
  4. Start using!

Start droid

Run the following command in your project directory:

cd /path/to/your/project
droid

During the first startup, droid will perform initial configuration.

Common questions

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. Update droid

Re-run the installation script to update to the latest version.

Windows

Install droid droid

Execute in PowerShell:

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

Connect to cch service

Prerequisite: Must log in to Droid official account first

  1. Run the droid command
  2. Follow the prompts to log in to Factory official account via browser
  3. After successful login, you can continue to configure custom models

Configure custom models

Configuration file path:

%USERPROFILE%\.factory\config.json

Edit the configuration file and add the following content:

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [cch]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "Current site address",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5-Codex [cch]",
      "model": "gpt-5-codex",
      "base_url": "Current site address/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

Important notes

  • Replace your-api-key-here with your cch API key
  • Anthropic format: Use Current site address (no /v1)
  • OpenAI format: Use Current site address/v1 (requires /v1)

Switch models

  1. Restart Droid
  2. Enter the /model command
  3. Select GPT-5-Codex [cch] or Sonnet 4.5 [cch]
  4. Start using!

Start droid

Run the following command in your project directory:

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

During the first startup, droid will perform initial configuration.

Common questions

1. Command not found

  • Make sure the npm global path (usually C:\Users\your-username\AppData\Roaming\npm) has been added to the system PATH
  • Reopen the PowerShell window

2. Update droid

Re-run the installation script to update to the latest version.

Linux

Install droid droid

Execute:

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

Tip

Linux users need to ensure xdg-utils is installed:

sudo apt-get install xdg-utils

Connect to cch service

Prerequisite: Must log in to Droid official account first

  1. Run the droid command
  2. Follow the prompts to log in to Factory official account via browser
  3. After successful login, you can continue to configure custom models

Configure custom models

Configuration file path:

~/.factory/config.json

Edit the configuration file and add the following content:

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [cch]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "Current site address",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5-Codex [cch]",
      "model": "gpt-5-codex",
      "base_url": "Current site address/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

Important notes

  • Replace your-api-key-here with your cch API key
  • Anthropic format: Use Current site address (no /v1)
  • OpenAI format: Use Current site address/v1 (requires /v1)

Switch models

  1. Restart Droid
  2. Enter the /model command
  3. Select GPT-5-Codex [cch] or Sonnet 4.5 [cch]
  4. Start using!

Start droid

Run the following command in your project directory:

cd /path/to/your/project
droid

During the first startup, droid will perform initial configuration.

Common questions

1. Command not found

# Check the npm global installation path and add it to PATH (if not already there)
npm config get prefix

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

2. Update droid

Re-run the installation script to update to the latest version.

📚 Common commands

After starting Claude Code, you can use the following common commands:

  • /help - View help information
  • /clear - Clear chat history and start a new conversation
  • /compact - Summarize the current conversation
  • /cost - View the amount spent in the current conversation
  • /model - Switch models (Droid-specific)
  • For more commands, see the official documentation For more commands, see the official documentation

🔍 General troubleshooting

Installation failed

  • Check if network connection is normal
  • Make sure you have administrator privileges (Windows) or use sudo (macOS / Linux)
  • Try using a proxy or mirror source (npm can use the --registry parameter)

API key is invalid

  • Confirm the key has been copied correctly (no extra spaces)
  • Check if the key is within the validity period
  • Verify that account permissions are normal
  • Confirm the correct endpoint format is used (Anthropic no /v1, OpenAI has /v1)

Endpoint configuration error

  • Claude Code / Droid Anthropic model: Use Current site address (no /v1)
  • Codex / Droid OpenAI model: Use Current site address/v1 (must include /v1)