客户端使用指南

Claude Code 使用指南

Claude Code 是 Anthropic 官方推出的 AI 编程助手，支持通过 codez 代理服务使用。本指南将帮助您在不同操作系统上完成安装和配置。

macOS

环境准备：安装 Node.js

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

方法一：使用 Homebrew（推荐）

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

方法二：官网下载

访问 https://nodejs.org/
下载适合 macOS 的 LTS 版本（需 v18 或更高）
打开下载的 .pkg 文件，按照安装向导完成

安装完成后，打开终端/命令行，输入以下命令验证：

node --version
npm --version

如果显示版本号，说明安装成功了！

安装 Claude Code

Native Install（推荐）

官方推荐使用 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 命令可以检查安装类型和版本。

NPM

使用 NPM 安装需要先安装 Node.js 18 或更高版本。适合偏好使用 NPM 管理工具的开发者。

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

警告

不要使用 sudo npm install -g，这可能导致权限问题和安全风险。如果遇到权限错误，请参考 NPM 官方解决方案。

验证安装

claude --version

如果显示版本号，恭喜！Claude Code 已成功安装。

迁移到 Native Install

如果你已通过 NPM 全局安装，可以使用以下命令迁移到 Native 安装：

claude install

部分用户可能会被自动迁移到这种安装方式。

连接 codez 服务

方法一：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": "https://codezsy.com",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

重要提示

将 your-api-key-here 替换为您的实际 API 密钥

密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

临时设置（当前会话）：

export ANTHROPIC_BASE_URL="https://codezsy.com"
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"

永久设置：

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

echo 'export ANTHROPIC_BASE_URL="https://codezsy.com"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

验证配置

配置完成后，验证环境变量是否设置成功：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

预期输出示例：

https://codezsy.com
sk_xxxxxxxxxxxxxxxxxx

注意

如果输出为空或显示变量名本身，说明环境变量设置失败，请重新按照上述步骤设置。

VS Code 扩展配置

配置文件路径：~/.claude

在 VS Code 扩展中搜索并安装 Claude Code for VS Code
在 ~/.claude 目录下创建 config.json 文件（如果没有）
添加以下内容：

{
  "primaryApiKey": "any-value",
}

注意

是 config.json，不是 settings.json

primaryApiKey 字段值可以为任意内容，只要存在即可

启动 Claude Code

在项目目录下运行：

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 https://codezsy.com/v1/messages

3. 更新 claude

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

Windows

环境准备：安装 Node.js

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

方法一：官网下载（推荐）

访问 https://nodejs.org/
下载 LTS 版本（需 v18 或更高）
双击 .msi 文件，按向导安装（保持默认设置）

方法二：使用包管理器

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

提示

建议使用 PowerShell 而不是 CMD，以获得更好的体验

安装完成后，打开终端/命令行，输入以下命令验证：

node --version
npm --version

如果显示版本号，说明安装成功了！

安装 Claude Code

Native Install（推荐）

官方推荐使用 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 命令可以检查安装类型和版本。

NPM

使用 NPM 安装需要先安装 Node.js 18 或更高版本。适合偏好使用 NPM 管理工具的开发者。

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

警告

不要使用 sudo npm install -g，这可能导致权限问题和安全风险。如果遇到权限错误，请参考 NPM 官方解决方案。

验证安装

claude --version

如果显示版本号，恭喜！Claude Code 已成功安装。

迁移到 Native Install

如果你已通过 NPM 全局安装，可以使用以下命令迁移到 Native 安装：

claude install

部分用户可能会被自动迁移到这种安装方式。

连接 codez 服务

方法一：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": "https://codezsy.com",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

重要提示

将 your-api-key-here 替换为您的实际 API 密钥

密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

临时设置（当前会话）：

$env:ANTHROPIC_BASE_URL = "https://codezsy.com"
$env:ANTHROPIC_AUTH_TOKEN = "your-api-key-here"

永久设置（用户级）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://codezsy.com", [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%

预期输出示例：

https://codezsy.com
sk_xxxxxxxxxxxxxxxxxx

注意

如果输出为空或显示变量名本身，说明环境变量设置失败，请重新按照上述步骤设置。

VS Code 扩展配置

配置文件路径：C:\Users\你的用户名.claude

在 VS Code 扩展中搜索并安装 Claude Code for VS Code
在 ~/.claude 目录下创建 config.json 文件（如果没有）
添加以下内容：

// Path: C:\Users\你的用户名\.claude
{
  "primaryApiKey": "any-value",
}

注意

是 config.json，不是 settings.json

primaryApiKey 字段值可以为任意内容，只要存在即可

启动 Claude Code

在项目目录下运行：

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 codezsy.com -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 Code

Native Install（推荐）

官方推荐使用 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 命令可以检查安装类型和版本。

NPM

使用 NPM 安装需要先安装 Node.js 18 或更高版本。适合偏好使用 NPM 管理工具的开发者。

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

警告

不要使用 sudo npm install -g，这可能导致权限问题和安全风险。如果遇到权限错误，请参考 NPM 官方解决方案。

验证安装

claude --version

如果显示版本号，恭喜！Claude Code 已成功安装。

迁移到 Native Install

如果你已通过 NPM 全局安装，可以使用以下命令迁移到 Native 安装：

claude install

部分用户可能会被自动迁移到这种安装方式。

连接 codez 服务

方法一：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": "https://codezsy.com",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

重要提示

将 your-api-key-here 替换为您的实际 API 密钥

密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

临时设置（当前会话）：

export ANTHROPIC_BASE_URL="https://codezsy.com"
export ANTHROPIC_AUTH_TOKEN="your-api-key-here"

永久设置：

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

echo 'export ANTHROPIC_BASE_URL="https://codezsy.com"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

验证配置

配置完成后，验证环境变量是否设置成功：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

预期输出示例：

https://codezsy.com
sk_xxxxxxxxxxxxxxxxxx

注意

如果输出为空或显示变量名本身，说明环境变量设置失败，请重新按照上述步骤设置。

VS Code 扩展配置

配置文件路径：~/.claude

在 VS Code 扩展中搜索并安装 Claude Code for VS Code
在 ~/.claude 目录下创建 config.json 文件（如果没有）
添加以下内容：

{
  "primaryApiKey": "any-value",
}

注意

是 config.json，不是 settings.json

primaryApiKey 字段值可以为任意内容，只要存在即可

启动 Claude Code

在项目目录下运行：

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 https://codezsy.com/v1/messages

3. 更新 claude

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

Codex CLI 使用指南

Codex 是 OpenAI 官方的命令行 AI 编程助手，支持通过 codez 代理使用。注意：Codex 使用 OpenAI 兼容格式，端点需要包含 /v1 路径。

macOS

环境准备：安装 Node.js

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

方法一：使用 Homebrew（推荐）

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

方法二：官网下载

访问 https://nodejs.org/
下载适合 macOS 的 LTS 版本（需 v18 或更高）
打开下载的 .pkg 文件，按照安装向导完成

安装完成后，打开终端/命令行，输入以下命令验证：

node --version
npm --version

如果显示版本号，说明安装成功了！

安装 Codex CLI

执行：

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

验证安装：

codex --version

连接 codez 服务

配置文件设置

打开文件资源管理器，找到 ~/.codex 文件夹（不存在则创建）
创建 config.toml 文件
使用文本编辑器打开，添加以下内容：

配置文件方式

创建 config.toml 文件（使用 auth.json 存储密钥时，无需 env_key 字段）：

model_provider = "codez"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
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.codez]
name = "codez"
base_url = "https://codezsy.com/v1"
wire_api = "responses"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

创建 auth.json 文件，添加：

{
  "OPENAI_API_KEY": "your-api-key-here"
}

提示

此方式通过 auth.json 文件存储 API 密钥，config.toml 中无需配置 env_key 字段。

环境变量方式

创建 config.toml 文件（使用环境变量时，需要配置 env_key 字段）：

model_provider = "codez"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
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.codez]
name = "codez"
base_url = "https://codezsy.com/v1"
wire_api = "responses"
env_key = "CODEZ_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

设置环境变量：

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

重要提示

将 your-api-key-here 替换为您的 codez API 密钥

注意：Codex 使用 OpenAI 兼容格式，端点包含 /v1 路径

VS Code 扩展配置

在 VS Code 扩展中搜索并安装 Codex – OpenAI’s coding agent
确保已按照上述步骤配置好 config.toml 和 auth.json
设置环境变量 CODEZ_API_KEY

重要

env_key 只能是环境变量名称（如 CODEZ_API_KEY），不能是完整的密钥。如果直接填写密钥，会报错找不到令牌或令牌配置错误。

启动 Codex CLI

在项目目录下运行：

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 $CODEZ_API_KEY

# 测试网络连接
curl -i https://codezsy.com/v1/messages

3. 更新 codex

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

Windows

环境准备：安装 Node.js

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

方法一：官网下载（推荐）

访问 https://nodejs.org/
下载 LTS 版本（需 v18 或更高）
双击 .msi 文件，按向导安装（保持默认设置）

方法二：使用包管理器

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

提示

建议使用 PowerShell 而不是 CMD，以获得更好的体验

安装完成后，打开终端/命令行，输入以下命令验证：

node --version
npm --version

如果显示版本号，说明安装成功了！

安装 Codex CLI

以管理员身份运行 PowerShell，执行：

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

验证安装：

codex --version

连接 codez 服务

配置文件设置

打开文件资源管理器，找到 C:\Users\你的用户名\.codex 文件夹（不存在则创建）
创建 config.toml 文件
使用文本编辑器打开，添加以下内容：

配置文件方式

创建 config.toml 文件（使用 auth.json 存储密钥时，无需 env_key 字段）：

model_provider = "codez"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
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.codez]
name = "codez"
base_url = "https://codezsy.com/v1"
wire_api = "responses"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

创建 auth.json 文件，添加：

{
  "OPENAI_API_KEY": "your-api-key-here"
}

提示

此方式通过 auth.json 文件存储 API 密钥，config.toml 中无需配置 env_key 字段。

环境变量方式

创建 config.toml 文件（使用环境变量时，需要配置 env_key 字段）：

model_provider = "codez"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
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.codez]
name = "codez"
base_url = "https://codezsy.com/v1"
wire_api = "responses"
env_key = "CODEZ_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

在 PowerShell 中运行：

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

设置后需要重新打开 PowerShell 窗口才能生效。

重要提示

将 your-api-key-here 替换为您的 codez API 密钥

注意：Codex 使用 OpenAI 兼容格式，端点包含 /v1 路径

VS Code 扩展配置

在 VS Code 扩展中搜索并安装 Codex – OpenAI’s coding agent
确保已按照上述步骤配置好 config.toml 和 auth.json
设置环境变量 CODEZ_API_KEY

重要

env_key 只能是环境变量名称（如 CODEZ_API_KEY），不能是完整的密钥。如果直接填写密钥，会报错找不到令牌或令牌配置错误。

启动 Codex CLI

在项目目录下运行：

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

首次启动时，codex 会进行初始化配置。

常见问题

1. 命令未找到

确保 npm 全局路径（通常是 C:\Users\你的用户名\AppData\Roaming\npm）已添加到系统 PATH
重新打开 PowerShell 窗口

2. API 连接失败

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

# 测试网络连接
Test-NetConnection -ComputerName codezsy.com -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 CLI

执行：

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

验证安装：

codex --version

连接 codez 服务

配置文件设置

打开文件资源管理器，找到 ~/.codex 文件夹（不存在则创建）
创建 config.toml 文件
使用文本编辑器打开，添加以下内容：

配置文件方式

创建 config.toml 文件（使用 auth.json 存储密钥时，无需 env_key 字段）：

model_provider = "codez"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
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.codez]
name = "codez"
base_url = "https://codezsy.com/v1"
wire_api = "responses"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

创建 auth.json 文件，添加：

{
  "OPENAI_API_KEY": "your-api-key-here"
}

提示

此方式通过 auth.json 文件存储 API 密钥，config.toml 中无需配置 env_key 字段。

环境变量方式

创建 config.toml 文件（使用环境变量时，需要配置 env_key 字段）：

model_provider = "codez"
model = "gpt-5.2"
model_reasoning_effort = "xhigh"
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.codez]
name = "codez"
base_url = "https://codezsy.com/v1"
wire_api = "responses"
env_key = "CODEZ_API_KEY"
requires_openai_auth = true

[sandbox_workspace_write]
network_access = true

设置环境变量：

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

重要提示

将 your-api-key-here 替换为您的 codez API 密钥

注意：Codex 使用 OpenAI 兼容格式，端点包含 /v1 路径

VS Code 扩展配置

在 VS Code 扩展中搜索并安装 Codex – OpenAI’s coding agent
确保已按照上述步骤配置好 config.toml 和 auth.json
设置环境变量 CODEZ_API_KEY

重要

env_key 只能是环境变量名称（如 CODEZ_API_KEY），不能是完整的密钥。如果直接填写密钥，会报错找不到令牌或令牌配置错误。

启动 Codex CLI

在项目目录下运行：

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 $CODEZ_API_KEY

# 测试网络连接
curl -i https://codezsy.com/v1/messages

3. 更新 codex

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

Gemini CLI 使用指南

Gemini CLI 是 Google 官方的 AI 编程助手命令行工具，支持通过 codez 代理服务使用。本指南将帮助您在不同操作系统上完成安装和配置。

macOS

环境准备：安装 Node.js

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

方法一：使用 Homebrew（推荐）

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

方法二：官网下载

访问 https://nodejs.org/
下载适合 macOS 的 LTS 版本（需 v18 或更高）
打开下载的 .pkg 文件，按照安装向导完成

安装完成后，打开终端/命令行，输入以下命令验证：

node --version
npm --version

如果显示版本号，说明安装成功了！

安装 Gemini CLI

确保您已安装 Node.js 18 或更高版本，然后全局安装 Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

连接 codez 服务

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

创建配置目录

Gemini CLI 的配置文件位于 ~/.gemini/ 目录。

macOS / Linux：

mkdir -p ~/.gemini

创建 .env 配置文件

在 ~/.gemini/ 目录下创建 .env 文件：

macOS / Linux：

nano ~/.gemini/.env

添加以下内容：

GOOGLE_GEMINI_BASE_URL=https://codezsy.com
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: codez API 基础地址

GEMINI_API_KEY: 您在 codez 控制台创建的 API 密钥

GEMINI_MODEL: 使用的模型（默认为 gemini-2.5-pro）

重要提示

将 YOUR_API_KEY_HERE 替换为您的实际 API 密钥

密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

如果您只想临时使用，可以通过环境变量配置：

macOS / Linux：

export GOOGLE_GEMINI_BASE_URL="https://codezsy.com"
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 或更高版本）。

方法一：官网下载（推荐）

访问 https://nodejs.org/
下载 LTS 版本（需 v18 或更高）
双击 .msi 文件，按向导安装（保持默认设置）

方法二：使用包管理器

# 使用 Chocolatey
choco install nodejs

# 或使用 Scoop
scoop install nodejs

提示

建议使用 PowerShell 而不是 CMD，以获得更好的体验

安装完成后，打开终端/命令行，输入以下命令验证：

node --version
npm --version

如果显示版本号，说明安装成功了！

安装 Gemini CLI

确保您已安装 Node.js 18 或更高版本，然后全局安装 Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

连接 codez 服务

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

创建配置目录

Gemini CLI 的配置文件位于 ~/.gemini/ 目录。

Windows (PowerShell)：

mkdir $env:USERPROFILE\.gemini

创建 .env 配置文件

在 ~/.gemini/ 目录下创建 .env 文件：

Windows：在 %USERPROFILE%.gemini\ 目录下创建 .env 文件

添加以下内容：

GOOGLE_GEMINI_BASE_URL=https://codezsy.com
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: codez API 基础地址

GEMINI_API_KEY: 您在 codez 控制台创建的 API 密钥

GEMINI_MODEL: 使用的模型（默认为 gemini-2.5-pro）

重要提示

将 YOUR_API_KEY_HERE 替换为您的实际 API 密钥

密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

如果您只想临时使用，可以通过环境变量配置：

Windows (PowerShell)：

$env:GOOGLE_GEMINI_BASE_URL="https://codezsy.com"
$env:GEMINI_API_KEY="your-api-key-here"
$env:GEMINI_MODEL="gemini-2.5-pro"

Windows (CMD)：

set GOOGLE_GEMINI_BASE_URL=https://codezsy.com
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 CLI

确保您已安装 Node.js 18 或更高版本，然后全局安装 Gemini CLI：

npm install -g @google/gemini-cli

验证安装：

gemini --version

连接 codez 服务

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

创建配置目录

Gemini CLI 的配置文件位于 ~/.gemini/ 目录。

macOS / Linux：

mkdir -p ~/.gemini

创建 .env 配置文件

在 ~/.gemini/ 目录下创建 .env 文件：

macOS / Linux：

nano ~/.gemini/.env

添加以下内容：

GOOGLE_GEMINI_BASE_URL=https://codezsy.com
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: codez API 基础地址

GEMINI_API_KEY: 您在 codez 控制台创建的 API 密钥

GEMINI_MODEL: 使用的模型（默认为 gemini-2.5-pro）

重要提示

将 YOUR_API_KEY_HERE 替换为您的实际 API 密钥

密钥获取方式：登录控制台 → API 密钥管理 → 创建密钥

方法二：环境变量配置

如果您只想临时使用，可以通过环境变量配置：

macOS / Linux：

export GOOGLE_GEMINI_BASE_URL="https://codezsy.com"
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

OpenCode 使用指南

OpenCode 是一款在终端中运行的 CLI + TUI AI 编程代理工具，也提供 IDE 插件集成。你可以将 OpenCode 指向 codez 作为统一入口来接入 Claude、GPT 与 Gemini 等模型。

macOS

安装 opencode

在 macOS 上可以选择以下任一种方式安装 OpenCode：

方式一：官方安装脚本

执行以下命令安装最新版：

curl -fsSL https://opencode.ai/install | bash

方式二：Homebrew

也可以使用 Homebrew 安装：

brew install anomalyco/tap/opencode

方式三：npm

也可以通过 npm 全局安装：

npm install -g opencode-ai

提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。

方式四：Bun

如果你使用 Bun，也可以全局安装：

bun add -g opencode-ai

连接 codez 服务

配置 opencode.json

配置文件路径：

~/.config/opencode/opencode.json

编辑配置文件，写入以下内容（只需一份配置文件即可覆盖全部模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": false,
  "model": "openai/gpt-5.2",
  "small_model": "openai/gpt-5.2-small",
  "provider": {
    "codezClaude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Claude via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1",
        "apiKey": "{env:CODEZ_API_KEY}"
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "claude-opus-4-5-20251101": {
          "name": "Claude Opus 4.5"
        }
      }
    },
    "codezGPT": {
      "npm": "@ai-sdk/openai",
      "name": "GPT via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1",
        "apiKey": "{env:CODEZ_API_KEY}",
        "store": false,
        "setCacheKey": true
      },
      "models": {
        "gpt-5.2": {
          "name": "GPT-5.2",
          "options": {
            "reasoningEffort": "xhigh",
            "store": false,
            "include": ["reasoning.encrypted_content"]
          }
        },
        "gpt-5.2-small": {
          "id": "gpt-5.2",
          "name": "GPT-5.2 Small",
          "options": {
            "reasoningEffort": "medium",
            "store": false,
            "include": ["reasoning.encrypted_content"]
          }
        }
      }
    },
    "codezGemini": {
      "npm": "@ai-sdk/google",
      "name": "Gemini via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1beta",
        "apiKey": "{env:CODEZ_API_KEY}"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview"
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview"
        }
      }
    }
  }
}

重要说明

请先在 codez 后台创建 API Key，并设置环境变量 CODEZ_API_KEY

codezClaude/openai 使用 https://codezsy.com/v1，codezGemini 使用 https://codezsy.com/v1beta

模型选择时使用 provider_id/model_id 格式（例如 openai/gpt-5.2 或 codezClaude/claude-sonnet-4-5-20250929）

选择模型

启动 OpenCode 后，在 TUI 中输入以下命令查看/选择模型：

/models

启动 opencode

在项目目录下运行：

cd /path/to/your/project
opencode

首次启动时，opencode 会加载配置并创建会话。

常见问题

1. 命令未找到

# 检查安装路径并添加到 PATH（例如 ~/.local/bin 或 npm 全局目录）
npm config get prefix

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

2. API 连接失败

# 检查环境变量
echo $CODEZ_API_KEY

# 测试网络连接
curl -i https://codezsy.com/v1/messages

3. 更新 opencode

npm install -g opencode-ai

Windows

安装 opencode

Windows 推荐使用包管理器（Chocolatey/Scoop），也可以使用 npm：

方式一：Chocolatey

使用 Chocolatey 安装：

choco install opencode

方式二：Scoop

使用 Scoop 安装：

scoop bucket add extras
scoop install extras/opencode

方式三：npm

也可以通过 npm 全局安装：

npm install -g opencode-ai

提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。

提示：官方说明 Windows 上通过 Bun 安装仍在推进。建议使用 Chocolatey/Scoop/npm，或从 GitHub Releases 下载二进制。

连接 codez 服务

配置 opencode.json

配置文件路径：

%USERPROFILE%\.config\opencode\opencode.json

编辑配置文件，写入以下内容（只需一份配置文件即可覆盖全部模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": false,
  "model": "openai/gpt-5.2",
  "small_model": "openai/gpt-5.2-small",
  "provider": {
    "codezClaude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Claude via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1",
        "apiKey": "{env:CODEZ_API_KEY}"
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "claude-opus-4-5-20251101": {
          "name": "Claude Opus 4.5"
        }
      }
    },
    "codezGPT": {
      "npm": "@ai-sdk/openai",
      "name": "GPT via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1",
        "apiKey": "{env:CODEZ_API_KEY}",
        "store": false,
        "setCacheKey": true
      },
      "models": {
        "gpt-5.2": {
          "name": "GPT-5.2",
          "options": {
            "reasoningEffort": "xhigh",
            "store": false,
            "include": ["reasoning.encrypted_content"]
          }
        },
        "gpt-5.2-small": {
          "id": "gpt-5.2",
          "name": "GPT-5.2 Small",
          "options": {
            "reasoningEffort": "medium",
            "store": false,
            "include": ["reasoning.encrypted_content"]
          }
        }
      }
    },
    "codezGemini": {
      "npm": "@ai-sdk/google",
      "name": "Gemini via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1beta",
        "apiKey": "{env:CODEZ_API_KEY}"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview"
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview"
        }
      }
    }
  }
}

重要说明

请先在 codez 后台创建 API Key，并设置环境变量 CODEZ_API_KEY

codezClaude/openai 使用 https://codezsy.com/v1，codezGemini 使用 https://codezsy.com/v1beta

模型选择时使用 provider_id/model_id 格式（例如 openai/gpt-5.2 或 codezClaude/claude-sonnet-4-5-20250929）

选择模型

启动 OpenCode 后，在 TUI 中输入以下命令查看/选择模型：

/models

启动 opencode

在项目目录下运行：

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

首次启动时，opencode 会加载配置并创建会话。

常见问题

1. 命令未找到

如果使用 npm 安装，请确保 npm 全局路径已添加到系统 PATH
重新打开终端窗口后再试

2. API 连接失败

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

# 测试网络连接
Test-NetConnection -ComputerName codezsy.com -Port 443

3. 更新 opencode

npm install -g opencode-ai

Linux

安装 opencode

在 Linux 上可以选择以下任一种方式安装 OpenCode：

方式一：官方安装脚本

执行以下命令安装最新版：

curl -fsSL https://opencode.ai/install | bash

方式二：Homebrew

也可以使用 Homebrew 安装：

brew install anomalyco/tap/opencode

方式三：npm

也可以通过 npm 全局安装：

npm install -g opencode-ai

提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。

方式四：Bun

如果你使用 Bun，也可以全局安装：

bun add -g opencode-ai

方式五：Paru（Arch Linux）

如果你使用 Arch Linux，也可以通过 paru（AUR）安装：

paru -S opencode-bin

连接 codez 服务

配置 opencode.json

配置文件路径：

~/.config/opencode/opencode.json

编辑配置文件，写入以下内容（只需一份配置文件即可覆盖全部模型）：

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "opencode",
  "autoupdate": false,
  "model": "openai/gpt-5.2",
  "small_model": "openai/gpt-5.2-small",
  "provider": {
    "codezClaude": {
      "npm": "@ai-sdk/anthropic",
      "name": "Claude via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1",
        "apiKey": "{env:CODEZ_API_KEY}"
      },
      "models": {
        "claude-haiku-4-5-20251001": {
          "name": "Claude Haiku 4.5"
        },
        "claude-sonnet-4-5-20250929": {
          "name": "Claude Sonnet 4.5"
        },
        "claude-opus-4-5-20251101": {
          "name": "Claude Opus 4.5"
        }
      }
    },
    "codezGPT": {
      "npm": "@ai-sdk/openai",
      "name": "GPT via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1",
        "apiKey": "{env:CODEZ_API_KEY}",
        "store": false,
        "setCacheKey": true
      },
      "models": {
        "gpt-5.2": {
          "name": "GPT-5.2",
          "options": {
            "reasoningEffort": "xhigh",
            "store": false,
            "include": ["reasoning.encrypted_content"]
          }
        },
        "gpt-5.2-small": {
          "id": "gpt-5.2",
          "name": "GPT-5.2 Small",
          "options": {
            "reasoningEffort": "medium",
            "store": false,
            "include": ["reasoning.encrypted_content"]
          }
        }
      }
    },
    "codezGemini": {
      "npm": "@ai-sdk/google",
      "name": "Gemini via codez",
      "options": {
        "baseURL": "https://codezsy.com/v1beta",
        "apiKey": "{env:CODEZ_API_KEY}"
      },
      "models": {
        "gemini-3-pro-preview": {
          "name": "Gemini 3 Pro Preview"
        },
        "gemini-3-flash-preview": {
          "name": "Gemini 3 Flash Preview"
        }
      }
    }
  }
}

重要说明

请先在 codez 后台创建 API Key，并设置环境变量 CODEZ_API_KEY

codezClaude/openai 使用 https://codezsy.com/v1，codezGemini 使用 https://codezsy.com/v1beta

模型选择时使用 provider_id/model_id 格式（例如 openai/gpt-5.2 或 codezClaude/claude-sonnet-4-5-20250929）

选择模型

启动 OpenCode 后，在 TUI 中输入以下命令查看/选择模型：

/models

启动 opencode

在项目目录下运行：

cd /path/to/your/project
opencode

首次启动时，opencode 会加载配置并创建会话。

常见问题

1. 命令未找到

# 检查安装路径并添加到 PATH（例如 ~/.local/bin 或 npm 全局目录）
npm config get prefix

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

2. API 连接失败

# 检查环境变量
echo $CODEZ_API_KEY

# 测试网络连接
curl -i https://codezsy.com/v1/messages

3. 更新 opencode

npm install -g opencode-ai

Droid CLI 使用指南

Droid 是 Factory AI 开发的交互式终端 AI 编程助手，支持通过 codez 代理服务使用。使用前必须先注册并登录 Droid 官方账号。

macOS

安装 Droid

执行：

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

连接 codez 服务

前置步骤：必须先登录 Droid 官方账号

运行 droid 命令

按提示通过浏览器登录 Factory 官方账号

登录成功后，才能继续配置自定义模型

配置自定义模型

配置文件路径：

~/.factory/config.json

编辑配置文件，添加以下内容：

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [codez]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "https://codezsy.com",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5.2 [codez]",
      "model": "gpt-5.2",
      "base_url": "https://codezsy.com/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

重要说明

将 your-api-key-here 替换为您的 codez API 密钥

Anthropic 格式：使用 https://codezsy.com

OpenAI 格式：使用 https://codezsy.com/v1

切换模型

重启 Droid
输入 /model 命令
选择 GPT-5-Codex [codez] 或 Sonnet 4.5 [codez]
开始使用！

启动 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

在 PowerShell 中执行：

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

连接 codez 服务

前置步骤：必须先登录 Droid 官方账号

运行 droid 命令

按提示通过浏览器登录 Factory 官方账号

登录成功后，才能继续配置自定义模型

配置自定义模型

配置文件路径：

%USERPROFILE%\.factory\config.json

编辑配置文件，添加以下内容：

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [codez]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "https://codezsy.com",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5.2 [codez]",
      "model": "gpt-5.2",
      "base_url": "https://codezsy.com/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

重要说明

将 your-api-key-here 替换为您的 codez API 密钥

Anthropic 格式：使用 https://codezsy.com（无 /v1）

OpenAI 格式：使用 https://codezsy.com/v1（需要 /v1）

切换模型

重启 Droid
输入 /model 命令
选择 GPT-5-Codex [codez] 或 Sonnet 4.5 [codez]
开始使用！

启动 Droid

在项目目录下运行：

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

首次启动时，droid 会进行初始化配置。

常见问题

1. 命令未找到

确保 npm 全局路径（通常是 C:\Users\你的用户名\AppData\Roaming\npm）已添加到系统 PATH
重新打开 PowerShell 窗口

2. 更新 droid

重新运行安装脚本即可更新到最新版本。

Linux

安装 Droid

执行：

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

提示

Linux 用户需确保已安装 xdg-utils：
终端窗口
sudo apt-get install xdg-utils

连接 codez 服务

前置步骤：必须先登录 Droid 官方账号

运行 droid 命令

按提示通过浏览器登录 Factory 官方账号

登录成功后，才能继续配置自定义模型

配置自定义模型

配置文件路径：

~/.factory/config.json

编辑配置文件，添加以下内容：

{
  "custom_models": [
    {
      "model_display_name": "Sonnet 4.5 [codez]",
      "model": "claude-sonnet-4-5-20250929",
      "base_url": "https://codezsy.com",
      "api_key": "your-api-key-here",
      "provider": "anthropic"
    },
    {
      "model_display_name": "GPT-5.2 [codez]",
      "model": "gpt-5.2",
      "base_url": "https://codezsy.com/v1",
      "api_key": "your-api-key-here",
      "provider": "openai"
    }
  ]
}

重要说明

将 your-api-key-here 替换为您的 codez API 密钥

Anthropic 格式：使用 https://codezsy.com（无 /v1）

OpenAI 格式：使用 https://codezsy.com/v1（需要 /v1）

切换模型

重启 Droid
输入 /model 命令
选择 GPT-5-Codex [codez] 或 Sonnet 4.5 [codez]
开始使用！

启动 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 模型：使用 https://codezsy.com (无 /v1)
Codex / Droid OpenAI 模型：使用 https://codezsy.com/v1 (含 /v1)