注册账号

打开浏览器访问控制台，完成账号注册。全程约 2 分钟。

1访问控制台

打开 https://clearapi.dev，进入控制台首页。

控制台首页

2点击注册

点击右上角「注册」，进入账号创建页。

点击右上角「注册」按钮

3完成注册

填写用户名、密码和确认密码（如有兑换码可填入「兑换码」栏，选填），点击「注册」完成账号创建。注册成功后自动跳转登录页。

确认信息，完成注册

创建 API 密钥

登录后创建 API 密钥，用于后续配置 Claude Code。

1登录账号

使用注册的邮箱和密码登录控制台。

输入邮箱和密码登录

2进入密钥管理

点击左侧菜单「API 密钥管理」。

左侧菜单 → API 密钥管理

3创建密钥

点击「创建 API 密钥」按钮。

点击「创建 API 密钥」

4配置密钥（关键）

填写名称（如 claude-code），务必选择「API 密钥分组」后再提交。

⚠️ 常见错误：忘记选择「API 密钥分组」会导致密钥无法使用。请确保从下拉菜单中选择了分组。

填写名称 + 选择分组 → 提交

5复制密钥

密钥创建成功后立即复制保存。此密钥只显示一次，关闭后无法再查看。

点击复制按钮保存密钥（sk- 开头）

密钥以 sk- 开头，请立即复制并妥善保存。

兑换额度

如果你有兑换码，可以在控制台兑换额度。

1进入钱包页面

登录后点击左侧菜单「钱包」或首页入口进入钱包页面。

从主页进入钱包页面

2输入兑换码

在兑换区域输入兑换码，点击兑换。额度会自动添加到账户。

输入兑换码完成兑换

小白安装使用配置（电脑、移动端）

零基础、不想碰命令行？这里是最省事的上手路径：电脑端用 CC-Switch 图形化工具一键配好，再装 VS Code 插件；手机端装个聊天 App 填入密钥即可。

① 用 CC-Switch 一键配好密钥（推荐）

CC-Switch 是图形化配置工具，免去手动编辑 settings.json，最适合新手。装好后填一次 ClearAPI 的地址和密钥即可，全程点几下鼠标。

1下载并安装 CC-Switch

按你的系统（Windows / macOS / Linux）下载安装包，双击安装。提供 GitHub 官方源和国内加速源两个入口。

⬇ 前往下载页面（含各系统安装包）→

2新建一个配置，填入 ClearAPI 参数

打开 CC-Switch，新建一个 Claude 类型的配置，按下表填写：

ClearAPI · Claude Code 配置

接口地址
Base URLhttps://clearapi.dev

API 密钥
API Keysk-你创建的密钥

主模型 Model可留空；想锁定最强模型可填 claude-opus-4-8

CC-Switch 编辑供应商：填写名称、请求地址 https://clearapi.dev 和 API Key

编辑供应商：① 随意填写名称 → ② 请求地址填 https://clearapi.dev、API Key 填你的 sk- 密钥（API 格式选 Anthropic Messages 原生，主模型可留空）

密钥就是前置教程里创建的那把 sk- 开头的 API 密钥。还没有？回到创建 API 密钥。

3保存并启用

点保存 → 启用该配置，CC-Switch 会自动帮你写好 Claude Code 的配置文件。之后打开终端输入 claude 就能直接用，无需再手动设置任何环境变量。

CC-Switch 显示配置已启用，即代表 Claude Code 已连上 ClearAPI。

📘

CC-Switch 完整图文教程

含每个系统的下载按钮、分步截图、多配置切换等详细说明。

查看完整教程 →

② 在 VS Code 里使用 Claude Code

配好密钥后，在 VS Code 装上官方插件，就能在编辑器里直接用 Claude Code，无需切到终端。Cursor 同理（同一个插件）。

前提条件：先完成上面 ① 的 CC-Switch 配置（或传统方式的环境变量配置）。插件依赖这些配置连接 ClearAPI 服务。

VS Code

1打开扩展商店

打开 VS Code，点击左侧边栏的扩展图标（四个方块），或按快捷键 Ctrl+Shift+X（macOS: Command+Shift+X）。

2搜索并安装插件

在搜索框中输入 Claude Code，找到 Anthropic 官方发布的插件，点击「Install」安装。

在扩展商店搜索 "Claude Code" 并点击 Install 安装

3重启 VS Code

安装完成后完全关闭并重新打开 VS Code（确保环境变量被正确加载）。

4打开 Claude Code

重启后，点击编辑器右上角的烟花图标即可打开 Claude Code 面板。

安装成功后可以在扩展列表中看到 Claude Code

⚠️ 出现登录页面？如果打开后看到登录界面，说明环境变量未正确生效。请检查 settings.json 文件路径是否正确，或重启 VS Code。

如果提示需要重启扩展，请完全关闭并重新打开 VS Code

Cursor

1安装插件

打开 Cursor，点击左侧扩展图标，搜索 Claude Code（与 VS Code 是同一个插件），点击安装。

在 Cursor 扩展商店搜索并安装 Claude Code 插件

2重启 Cursor

安装完成后完全关闭并重新打开 Cursor。

3使用 Claude Code

重启后，点击右上角烟花图标，或点击项目右上角三个点菜单 → 选择「Claude Code: Open」。

在 Cursor 设置中可以看到 Claude Code: Open 选项

配置路径提醒：
Windows: %USERPROFILE%\.claude\settings.json
macOS/Linux: ~/.claude/settings.json

在手机上使用 ClearAPI（移动端 App）

没有电脑也能用 ClearAPI。在手机上装一个支持「自定义 API 接口」的聊天 App，填入我们的中转地址和密钥即可对话——iOS / Android / 桌面 / 网页版全通用。下面以 ChatBox 为主线逐字段详细演示（约 3 分钟），并给出 NextChat 等其他 App 的接入差异。

💡 ClearAPI 是标准网关，同时兼容两套协议：OpenAI 协议（绝大多数 App 走这条）和 Anthropic / Claude 原生协议。两者用的都是你在创建 API 密钥拿到的同一把 sk-，移动端和电脑端通用，无需重新申请、也不用注册任何第三方账号。

第一步：下载 App（扫码或点链接）

下面四款都是支持「自定义接口」的主流客户端，都能接入 ClearAPI。手机摄像头扫二维码即可打开对应的官方下载页；电脑端可直接点下方链接。新手推荐 ChatBox（全平台、最易上手）。

ChatBox

iOS · Android · Win · Mac · Linux · Web

官网下载 App Store Google Play 安卓 APK 使用文档

NextChat

iOS · Android · Win · Mac · Linux · Web

GitHub 发布页项目主页网页版

Cherry Studio

Windows · macOS · Linux（桌面）

官网下载使用文档 GitHub

Pal Chat

iOS（iPhone / iPad）

App Store

二维码均指向各 App 官方下载页 / 商店页，请认准官网，谨防第三方修改版。下载安装后，按下面的方案逐字段填入 ClearAPI 的接入参数即可。

先记住这张接入参数表

不管用哪个 App，填的都是下面这套参数（OpenAI 兼容协议和 Anthropic 原生协议地址和密钥完全一样，新手不用区分）：

ClearAPI 官方接入参数（与电脑端完全一致）

Base URL
（两套协议通用）https://clearapi.dev

API 密钥
API Keysk-你创建的密钥（两套协议通用）

模型 Model手动填写模型 ID，见下方常用模型清单

💡 关于 /v1：Base URL 统一填 https://clearapi.dev 即可，绝大多数 App 会自动补全 /v1。个别 App（如 ChatBox 的「OpenAI API 兼容」自定义提供方）需要你手动带上 /v1，下面每个方案都会明确标出。
实在拿不准：先不带 /v1 试，报 404 再加上 /v1 试，两种里总有一种通。

方案一：ChatBox（推荐，逐字段详解）

ChatBox 是跨平台 AI 客户端，iOS / Android / Windows / macOS / 网页版界面一致。下面每一步都按官方界面措辞演示。

1下载并打开 ChatBox

用上方「第一步：下载 App」里的 ChatBox 二维码 / 链接安装（iOS / Android / 桌面 / 网页版均可）。首次打开可跳过自带的免费模型引导，我们要接入自己的 ClearAPI。

2进入「设置 → 模型提供方」

打开 App 后：

电脑 / 网页版：直接点左下角「设置」（齿轮图标）。
手机版：先点左上角菜单按钮（☰）展开侧边栏，再点底部「设置」。

进入设置后，找到左侧的「模型提供方」（部分版本叫「AI Provider / 模型设置」），点击它。

3点底部「添加」，新建一个自定义提供方

在模型提供方列表底部点「添加」。弹窗里：

名称：随便填，建议 ClearAPI，方便日后辨认。
API 模式 / 提供方类型：选 「OpenAI API 兼容」（OpenAI API Compatible）。

点「添加」确认创建，然后进入这个新提供方的详情页填下面的字段。

4逐字段填写（关键，照抄即可）

ClearAPI · OpenAI API 兼容提供方

名称 NameClearAPI

API 模式OpenAI API 兼容

API 域名 / 主机
API Hosthttps://clearapi.dev

API 路径
API Path留空，无需填写

API 密钥
API Keysk-你的密钥

💡 就这么简单：API 域名填 https://clearapi.dev，系统会自动补全 /v1。「API 路径」留空即可，不要手动填 /v1/chat/completions 之类。

密钥就是前置教程里创建的那把 sk- 开头的 API 密钥，移动端和电脑端用的是同一把，不用重新申请。还没有？回到创建 API 密钥。官方逐步带图说明见 ChatBox OpenAI 配置文档 →。

5新建模型，手填模型 ID

同一页里找到「模型」区域，点「新建 / 添加模型」，在「模型 ID」处手动输入要用的模型（移动端不会自动拉取列表，必须手填，且区分大小写和连字符，填错会提示模型不存在）。例如先填 claude-sonnet-4-6。想要多个模型就重复「新建」逐个添加，常用 ID 见下方清单。

6回到对话页，验证

保存设置，回到对话界面，顶部模型选择器切到刚加的 ClearAPI 模型，发一句「你好」。能正常收到回复就说明配置成功。

收到回复 = 打通了。现在你可以在手机上随时用 ClearAPI 对话，额度与电脑端共用同一个账户。

常用模型 ID（手填用）

移动端添加模型时需要手动输入模型 ID。以下是常用的对话模型，复制粘贴即可：

模型 ID	说明
`claude-opus-4-8`	最强，复杂推理与编程首选
`claude-sonnet-4-6`	均衡，日常对话推荐
`claude-haiku-4-5-20251001`	轻快，简单任务省额度
`gpt-5.5`	OpenAI 旗舰
`gemini-3.1-pro-preview`	Google Gemini Pro
`gemini-3-flash-preview`	Gemini 快速版

模型 ID 必须和服务端完全一致（区分大小写、连字符）。完整可用列表以控制台「模型」页为准；额度按所选模型的费率扣除。

方案二：NextChat（开源，逐步演示）

NextChat 是热门开源客户端，支持 Web / PWA / Windows / macOS / Linux。它的接口规则和 ChatBox 正好相反——地址要忽略 /v1，下面按官方界面演示。

1打开设置，勾选「自定义接口」

打开 NextChat，点左下角「设置」。在设置页找到模型服务相关区域，勾选「自定义接口」（Custom Endpoint），展开下面的配置项。

2逐字段填写

ClearAPI · NextChat 自定义接口

模型服务商OpenAI

接口地址
Endpointhttps://clearapi.dev

API Keysk-你的密钥

自定义模型名claude-sonnet-4-6，多个用英文逗号隔开

⚠️ NextChat 与 ChatBox 相反：接口地址不带 /v1。按官方说明「填写地址时需忽略 v1 版本」，所以这里填到 https://clearapi.dev 为止，NextChat 会自动补全版本路径。多个模型在「自定义模型名」里用英文逗号分隔，如 claude-sonnet-4-6,claude-opus-4-8,gpt-5.5。

3在对话里选模型

回到「新的聊天」，点对话框上方/内的「设置」，把「模型」切到你刚加的 ClearAPI 模型，发条消息验证即可。

方案三：其他兼容 App 一览

任何支持「自定义接口地址 / 自定义 Base URL」的客户端都能接入 ClearAPI，参数就是文首那张表。常见 App 的填法差异：

App	平台	接口地址填法
ChatBox	iOS / Android / 桌面 / Web	自定义「OpenAI API 兼容」提供方，API 域名 `https://clearapi.dev`（路径留空，系统自动补全）
NextChat	桌面 / Web / PWA	自定义接口，接口地址 `https://clearapi.dev`
Pal Chat	iOS	轻量，「API Host」填 `https://clearapi.dev`
Cherry Studio	Windows / macOS / Linux	添加「OpenAI」类型提供商，API 地址 `https://clearapi.dev`

💡 统一填 https://clearapi.dev 即可，系统会自动补全 /v1，所有 App 通用。

移动端常见问题

现象	原因与解决
404 / Not Found	多半是 `/v1` 带错。按上表在「带 /v1 / 不带 /v1」之间切换；ChatBox 自定义提供方还要确认「API 路径」留空。
401 / 鉴权失败 / Invalid key	密钥填错或粘贴时带了空格。重新从创建 API 密钥复制完整 `sk-`，确认前后无空格。
提示「模型不存在」	模型 ID 拼写不符（大小写 / 连字符）。从本页常用模型清单原样复制，不要手敲。
有回复但很快报额度	该模型费率较高或令牌额度有限。换更省的模型（如 `claude-haiku-4-5-20251001`），或回控制台查令牌额度。
连不上 / 一直转圈	检查手机网络能否访问 `clearapi.dev`；若开了系统代理/VPN，尝试切换或关闭后重试。

ClearAPI 同时兼容 Anthropic / Claude 原生协议。在 ChatBox 添加提供方时，选 「Claude / Anthropic」 类型，把默认 API Host（https://api.anthropic.com）改成 https://clearapi.dev（不带 /v1，原生协议路径不同），密钥仍填你的 sk-，模型选 Claude 系列。

日常对话两种协议效果一致，新手优先用方案一的「OpenAI 兼容」（全模型通用、最不易配错）。官方带图说明：ChatBox Claude 配置文档 →

想在手机上写代码用 Claude Code？纯手机 App 更适合对话、问答、文案；移动端跑 Claude Code 建议走「SSH 连到电脑/服务器再跑 claude」的方式。

传统 Claude Code 安装配置（电脑端）

手动安装 Node.js + Claude Code CLI 并配置环境变量的完整流程，适合想了解底层原理或需要精细控制的用户。约 5 分钟。觉得繁琐的新手，建议直接看上方「小白安装使用配置」用 CC-Switch 一键搞定。

💡 本节是传统/进阶路径（命令行 + 手动改配置文件）。只想快速上手？用小白安装使用配置的 CC-Switch 图形化方式更简单。

1. 安装 Node.js

Claude Code 需要 Node.js 18+ 环境。首先检查你的电脑是否已安装 Node.js。

打开终端

按键盘 Win + R 打开"运行"窗口，输入 cmd，点击"确定"或按回车键打开命令提示符。

按 Win+R 打开运行窗口，输入 cmd 回车打开命令提示符

检查是否已安装 Node.js

在命令提示符中输入以下命令检查：

检查 Node.js 版本

node --version
npm --version

如果显示版本号（如 v24.x.x），说明已安装，可跳过安装步骤

如果提示"不是内部或外部命令"，说明未安装，请按下方步骤安装。

方法一：官网下载安装（推荐新手）

1. 打开浏览器访问 https://nodejs.org

2. 点击绿色的 LTS（长期支持版）下载按钮

Node.js 官网 — 点击 LTS 版本的下载按钮

3. 下载完成后双击 .msi 安装文件，保持所有默认选项，一路点击 Next 完成安装

安装过程中保持默认选项，一直点击 Next 即可

4. 安装完成后，关闭并重新打开命令提示符（重要！），再次验证：

验证安装

node --version
npm --version

两条命令都输出版本号即安装成功。如仍提示"不是内部或外部命令"，请重启电脑后再试。

方法二：命令行安装（适合有经验的用户）

winget 安装

winget install OpenJS.NodeJS.LTS

或 Chocolatey 安装

choco install nodejs-lts

2. 安装 Claude Code

打开 PowerShell（按 Win+R 输入 powershell 回车），执行以下任一命令安装：

在 PowerShell 中执行 npm install 安装 Claude Code

方法一：WinGet 安装（推荐）

winget install Anthropic.ClaudeCode

方法二：官方脚本（PowerShell）

irm https://claude.ai/install.ps1 | iex

方法三：npm 安装

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

⚠️ 必要依赖：Claude Code 在 Windows 上需要 Git for Windows。安装时保持默认选项，确保 Git Bash 可用。

Git 安装时保持默认目录，确保勾选 "Add to PATH"

安装完成后，关闭并重新打开 PowerShell，验证安装：

验证安装

claude --version

3. 配置环境变量

💡 懒人方案：使用 CC-Switch 桌面工具可一键完成以下配置，无需手动编辑文件。

配置 API 密钥和中转地址，让 Claude Code 连接到 ClearAPI 服务。提供三种方式，任选其一：

在 %USERPROFILE%\.claude\ 目录下创建 settings.json：

创建配置目录和文件

mkdir "$env:USERPROFILE\.claude" -Force
notepad "$env:USERPROFILE\.claude\settings.json"

在打开的记事本中粘贴以下内容，保存后关闭：

settings.json 内容

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_BASE_URL": "https://clearapi.dev/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

将 sk-你的密钥 替换为你在前置教程中创建的实际 API 密钥（sk- 开头的字符串）。

在 PowerShell 中执行以下命令永久设置环境变量：

PowerShell 永久设置

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://clearapi.dev/", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-你的密钥", "User")
[System.Environment]::SetEnvironmentVariable("CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC", "1", "User")

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

验证环境变量

echo $env:ANTHROPIC_BASE_URL

通过 Windows 系统界面设置环境变量（适合不熟悉命令行的用户）：

第一步：按 Win+R 打开运行窗口，输入 sysdm.cpl，回车打开系统属性

Win+R 输入 sysdm.cpl 打开系统属性窗口

第二步：点击「高级」选项卡 → 点击底部的「环境变量」按钮

点击"高级"选项卡 → "环境变量"按钮，打开环境变量设置窗口

第三步：在「用户变量」区域点击「新建」，依次添加以下三个变量：

点击"新建"，输入变量名和变量值

变量名	变量值
`ANTHROPIC_BASE_URL`	`https://clearapi.dev/`
`ANTHROPIC_AUTH_TOKEN`	`sk-你的密钥`
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	`1`

同样方式添加 ANTHROPIC_AUTH_TOKEN 变量，值为你的 API 密钥

第四步：全部点击「确定」关闭窗口，然后重新打开 PowerShell（必须重开才能生效）

⚠️ 重要：设置环境变量后必须重新打开终端窗口，否则新变量不会生效。

4. 启动使用

配置完成后，打开 PowerShell，进入你的项目目录并启动 Claude Code：

启动 Claude Code

cd 你的项目目录
claude

首次启动会显示欢迎界面，按提示操作即可进入对话模式：

Claude Code 首次启动 — 选择终端主题风格

安全确认 — 确认项目目录可信后即可开始使用

Claude Code 正常工作中 — 看到对话界面说明配置成功

看到以上界面并能正常对话，说明配置成功！你现在可以开始使用 Claude Code 了。

🚀

想让 Claude Code 更强？安装社区插件

一行命令解锁 63 个专业代理、深度研究、自动代码审查、多模型协作省 Token 等高级能力。查看插件推荐 →

1. 安装 Node.js

Claude Code 需要 Node.js 18+ 环境。首先打开终端检查是否已安装。

打开终端

按 Command + 空格 打开 Spotlight 搜索，输入 Terminal（或"终端"），回车打开终端应用。也可以在「应用程序 → 实用工具 → 终端」中找到。

检查是否已安装 Node.js

检查版本

node --version
npm --version

终端显示版本号说明已安装成功

如果提示 command not found，说明未安装，请按下方步骤安装。

方法一：Homebrew 安装（推荐）

如果还没有 Homebrew，先安装

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装 Node.js

brew install node

Node.js 官网 macOS 下载页面 — 推荐使用 nvm 安装

方法二：官网下载

1. 访问 https://nodejs.org，下载 LTS 版本的 macOS Installer（.pkg）

2. 双击下载的 .pkg 文件，按提示完成安装

方法三：nvm（版本管理器）

安装 nvm 并安装 Node.js

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
nvm install --lts

2. 安装 Claude Code

在终端中执行以下任一命令安装 Claude Code：

方法一：官方脚本（推荐）

curl -fsSL https://claude.ai/install.sh | sh

方法二：npm 安装

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

使用 npm 安装 Claude Code（如遇权限问题加 sudo）

安装完成后验证：

验证安装

claude --version

显示版本号（如 2.0.69）说明安装成功

3. 配置环境变量

💡 懒人方案：使用 CC-Switch 桌面工具可一键完成以下配置，无需手动编辑文件。

配置 API 密钥和中转地址。提供两种方式，任选其一：

在终端中执行以下命令创建配置文件：

创建配置文件

mkdir -p ~/.claude && nano ~/.claude/settings.json

在 nano 编辑器中粘贴以下内容（按 Command+V 粘贴）：

settings.json 内容

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_BASE_URL": "https://clearapi.dev/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

粘贴完成后，按 Ctrl+O 保存（按回车确认文件名），再按 Ctrl+X 退出 nano。

将 sk-你的密钥 替换为你的实际 API 密钥。

将环境变量写入 shell 配置文件（~/.zshrc）：

打开 .zshrc 编辑

nano ~/.zshrc

在 .zshrc 文件末尾添加环境变量配置

在文件末尾添加以下三行：

添加到 .zshrc 末尾

export ANTHROPIC_BASE_URL="https://clearapi.dev/"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"

按 Ctrl+O 保存，Ctrl+X 退出，然后执行：

使配置生效

source ~/.zshrc

执行 source 命令使环境变量立即生效

验证

echo $ANTHROPIC_BASE_URL

4. 启动使用

配置完成后，在终端中进入项目目录并启动：

启动 Claude Code

cd 你的项目目录
claude

看到 Claude Code 欢迎界面并能正常对话，说明配置成功！

🚀

想让 Claude Code 更强？安装社区插件

一行命令解锁 63 个专业代理、深度研究、自动代码审查、多模型协作省 Token 等高级能力。查看插件推荐 →

1. 安装 Node.js

Claude Code 需要 Node.js 18+ 环境。首先打开终端检查是否已安装。

打开终端

按 Ctrl+Alt+T 打开终端（大多数 Linux 发行版通用快捷键）。也可以在应用菜单中搜索"Terminal"。

检查是否已安装 Node.js

检查版本

node --version
npm --version

如果显示版本号（v18.x.x 或更高），可跳过安装步骤。如果提示 command not found，请按下方步骤安装。

方法一：NodeSource（推荐 Ubuntu/Debian）

Ubuntu / Debian

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS / RHEL / Fedora

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo yum install -y nodejs

方法二：nvm（版本管理器，通用）

安装 nvm 并安装 Node.js

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

安装完成后验证：

验证安装

node --version
npm --version

2. 安装 Claude Code

在终端中执行以下任一命令安装：

方法一：官方脚本（推荐）

curl -fsSL https://claude.ai/install.sh | sh

方法二：npm 安装

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

安装完成后验证：

验证安装

claude --version

如果提示权限错误，使用 sudo 或配置 npm 全局目录到用户目录（见下方排查部分）。

3. 配置环境变量

💡 懒人方案：使用 CC-Switch 桌面工具可一键完成以下配置，无需手动编辑文件。

配置 API 密钥和中转地址。提供两种方式，任选其一：

在终端中执行以下命令创建配置文件：

创建配置文件

mkdir -p ~/.claude && nano ~/.claude/settings.json

在 nano 编辑器中粘贴以下内容：

settings.json 内容

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_BASE_URL": "https://clearapi.dev/",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

按 Ctrl+O 保存（回车确认），Ctrl+X 退出。

将 sk-你的密钥 替换为你的实际 API 密钥。

将环境变量写入 shell 配置文件：

写入 ~/.bashrc（bash 用户）

echo 'export ANTHROPIC_BASE_URL="https://clearapi.dev/"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"' >> ~/.bashrc
echo 'export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"' >> ~/.bashrc
source ~/.bashrc

如果你使用 zsh，将 .bashrc 替换为 .zshrc。

验证

echo $ANTHROPIC_BASE_URL

4. 启动使用

配置完成后，在终端中进入项目目录并启动：

启动 Claude Code

cd 你的项目目录
claude

看到 Claude Code 欢迎界面并能正常对话，说明配置成功！

🚀

想让 Claude Code 更强？安装社区插件

一行命令解锁 63 个专业代理、深度研究、自动代码审查、多模型协作省 Token 等高级能力。查看插件推荐 →

配置 Opus 4.8

想用最新最强的 Opus 4.8 模型？只需两步：升级 Claude Code 到最新版，再写入 settings.json 指定模型。约 3 分钟。

Opus 4.8 需要较新版本的 Claude Code 才能识别。如果你跳过升级直接配置，可能会提示模型不存在或自动回退到旧模型。

1升级 Claude Code 到最新版本

在终端中执行以下命令升级。根据你当初的安装方式选择对应命令：

方法一：内置命令升级（通用，推荐）

claude update

方法二：npm 安装的用户

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

方法三：官方脚本安装的用户（macOS / Linux）

curl -fsSL https://claude.ai/install.sh | sh

升级完成后验证版本：

验证版本

claude --version

确认版本号已更新到最新。Windows 用 WinGet 安装的用户可执行 winget upgrade Anthropic.ClaudeCode 升级。

2配置 settings.json 指定 Opus 4.8

打开你的配置文件（Windows 路径 %USERPROFILE%\.claude\settings.json，macOS / Linux 路径 ~/.claude/settings.json），替换为以下内容：

settings.json 内容

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_BASE_URL": "https://clearapi.dev"
  },
  "includeCoAuthoredBy": false,
  "skipDangerousModePermissionPrompt": true,
  "theme": "light"
}

将 sk-你的密钥 替换为你在前置教程中创建的实际 API 密钥（sk- 开头的字符串）。

各字段含义：

字段	作用
`ANTHROPIC_AUTH_TOKEN`	你的 ClearAPI API 密钥（sk- 开头）
`ANTHROPIC_BASE_URL`	API 中转地址，固定为 `https://clearapi.dev`

3验证生效

保存文件后重启 Claude Code，进入对话界面输入 /status 查看当前模型，确认显示为 Opus 4.8：

查看当前模型

/status

看到当前模型为 claude-opus-4-8 即配置成功，现在你正在使用最新的 Opus 4.8。

高手进阶必备

装好基础环境后，再用社区插件把 Claude Code 从单一工具升级为完整的 AI 开发团队——这是高手拉开差距的地方。以下两款插件均为开源项目，GitHub 星标合计超 23 万。

前置条件：Claude Code 已安装且可正常对话（版本 ≥ 2.1，终端运行 claude --version 确认）。

插件对比（截至 2026 年 6 月）

维度	ECC · 204K+ ⭐	OMC · 35K+ ⭐
设计哲学	全能工具箱 — 249 技能按需取用，覆盖 12 语言生态	编排引擎 — 多代理团队协作，智能模型路由
核心优势	标准化开发流程（TDD/审查/安全扫描）、持续学习、跨工具兼容	苏格拉底式需求分析、团队并行开发、自动省 Token
多模型协作	✅ 支持（/ccg:execute 多模型协作交付）	✅ 原生支持（Claude + Gemini + Codex 三模型并行）
Token 策略	选择性安装控制上下文开销	Ecomode 路由到 Haiku/Sonnet 省 30-50%
跨工具兼容	Claude Code / Cursor / Codex / OpenCode / Gemini / Zed	Claude Code 为主，另有 oh-my-codex 姊妹项目
代理数量	63 个专业代理	32+ 个专业代理
适用项目	大型项目、完整功能开发、多语言全栈、团队规范化	需要并行加速、省 Token、多模型协作的项目
额外 API Key	可选（多模型协作时需要）	可选（不配也能用，配了解锁并行加速）

Anthropic 黑客松冠军。63 个专业代理、249 个技能、79 个命令，覆盖 12 语言生态。从项目初始化、深度研究、TDD 到多模型协作交付，提供完整的标准化开发流程。支持 Claude Code、Cursor、Codex、OpenCode、Gemini、Zed 等主流 AI 工具。适合大型项目、完整功能开发、多语言全栈和团队规范化场景。

步骤 1：克隆仓库（国内镜像）

git clone https://ghproxy.net/https://github.com/affaan-m/ECC.git ~/.claude/plugins/everything-claude-code

步骤 2：运行安装脚本

cd ~/.claude/plugins/everything-claude-code && bash install.sh

步骤 3：重启 Claude Code，运行配置向导

/configure-ecc

选择性安装：/configure-ecc 会引导你选择需要的技能模块（如只装 Python + TDD），避免全量安装占用过多上下文窗口。

Teams-first 多代理编排系统，零学习曲线。通过苏格拉底式追问深度分析需求，Team 模式自动分工并行开发，Ecomode 智能路由到便宜模型省 30-50% Token。支持 Claude + Gemini + Codex 三模型协同，适合需要并行加速、控制成本、多模型协作的项目。

步骤 1：克隆仓库（国内镜像）

git clone https://ghproxy.net/https://github.com/Yeachan-Heo/oh-my-claudecode.git ~/.claude/plugins/oh-my-claudecode

步骤 2：重启 Claude Code，运行初始化向导

/omc-setup

纯 Claude 也能用：即使不配置 Gemini/Codex Key，OMC 也能正常工作（退化为单模型编排）。配置多模型后才解锁并行加速和 Ecomode 省钱功能。

备用镜像：如果 ghproxy.net 无法访问，可替换为 https://ghproxy.homeboyc.cn/ 或 https://gh-proxy.com/。用法相同，在 GitHub 地址前加上镜像前缀即可。

Token 影响与适用场景

	ECC	OMC
启动 Token 开销	中等（选择性安装可控制在 5K-15K tokens）	较低（核心框架轻量）
运行时 Token	正常消耗，多模型协作时按需调用外部模型	Ecomode 自动路由到便宜模型，节省 30-50%
最佳场景	大型项目完整开发、多语言全栈、团队规范化流程、跨工具统一配置	需要并行加速、控制 Token 预算、多模型团队协作
不太适合	简单脚本、一次性小任务（功能过于丰富）	纯单文件小修改（编排开销大于收益）

选择建议：需要标准化开发流程（TDD → 审查 → 安全扫描 → 交付）和跨工具兼容，选 ECC。需要苏格拉底式需求分析、团队并行开发和自动省 Token，选 OMC。两者也可同时安装，互不冲突。

ECC 常用命令

命令	用途
`/init`	初始化项目 CLAUDE.md，自动分析代码库生成文档
`/deep-research`	多源深度研究，自动搜索网络并生成带引文报告
`/plan`	分析需求 → 评估风险 → 生成分步实施计划
`/ccg:execute`	按计划执行实施，多模型协作交付
`/ccg:feat`	智能功能开发 — 自动识别需求，规划/讨论/实施全流程
`/tdd`	测试驱动开发（先写测试再实现）
`/code-review`	自动审核代码（本地变更或 GitHub PR）
`/security-review`	安全漏洞扫描

OMC 常用命令

命令	用途
`/omc-setup`	初始化或更新 OMC 配置
`/socratic`	苏格拉底式思考 — 通过追问引导深度分析需求
`/align`	自动对齐 — 确保实现与需求/设计一致
`/teams`	Teams 模式 — 多代理团队协作开发，角色自动分工
`/ultrawork`	多代理并行执行（加速大型任务）
`/ecomode`	省 Token 模式（路由到 Haiku/Sonnet）
`/omc-doctor`	诊断插件问题并修复

常见报错排查

遇到问题？点击展开对应的解决方案。每个问题都附有错误截图帮助你确认问题。

错误表现：

PowerShell 提示 "claude" 无法识别为 cmdlet

原因：Claude Code 的可执行文件路径不在系统 PATH 环境变量中。

解决步骤：

1. 检查 npm 全局安装路径：

检查 npm 全局路径

npm config get prefix

2. 确认该路径在系统 PATH 中：

检查 PATH 环境变量是否包含 npm 全局路径（如 D:\nodejs）

推荐解决：卸载 npm 版本，改用 WinGet 安装（自动配置 PATH）：

推荐方案

# 先卸载 npm 版本
npm uninstall -g @anthropic-ai/claude-code

# 用 WinGet 重新安装（自动配置 PATH）
winget install Anthropic.ClaudeCode

安装完成后必须重新打开 PowerShell，新的 PATH 才会生效。

错误表现：

Windows 提示 claude.exe 无法运行

npm 因执行策略被禁止运行

原因：Node.js 或 npm 安装不完整，或版本过低。

解决步骤：

1. 完全卸载当前 Node.js（控制面板 → 程序和功能 → 卸载 Node.js）

2. 删除残留目录：C:\Users\用户名\AppData\Roaming\npm

3. 重新从 nodejs.org 下载最新 LTS 版本安装

4. 重启电脑后重新安装 Claude Code

错误表现：

Claude Code 提示需要 git-bash 环境

原因：Claude Code 在 Windows 上依赖 Git for Windows 提供的 Git Bash 环境。

解决步骤：

1. 下载安装 Git for Windows：https://git-scm.com/download/win

2. 安装时保持默认选项，特别注意勾选 "Add to PATH"：

Git 安装保持默认目录和选项

3. 安装完成后关闭并重新打开 PowerShell

验证 Git 安装

git --version

错误表现：

提示 403 Your client is not authorized

原因：旧的登录状态或 OAuth token 干扰了 API Key 认证。

解决步骤：

在 Claude Code 中执行登出

/logout

然后重新启动 Claude Code：

重新启动

claude

如果仍然报错，尝试删除 ~/.claude/credentials.json 文件后重启。

错误表现：

提示 Unable to connect to Anthropic services / 地区不支持

原因：环境变量未正确配置，请求没有通过 ClearAPI 中转服务，直接发送到了 Anthropic 官方（有地区限制）。

排查步骤：

1. 检查 ANTHROPIC_BASE_URL 是否设置为 https://clearapi.dev/（注意末尾有斜杠）

2. 重新打开终端（环境变量修改后必须重启终端才生效）

3. 验证环境变量是否生效：

Windows PowerShell

echo $env:ANTHROPIC_BASE_URL

macOS / Linux

echo $ANTHROPIC_BASE_URL

如果输出为空，说明环境变量未生效。请重新按教程配置。

使用 settings.json 方式配置可以避免环境变量不生效的问题，推荐优先使用。

之前配置过其他中转站的 URL 和 Key，导致冲突。

⚠️ 注意：以下操作会删除 Claude Code 本地数据（聊天记录、MCP 配置）。如需保留，请使用下方的替代方案。

彻底清理（Windows PowerShell）

Remove-Item "$env:USERPROFILE\.claude" -Recurse -Force

彻底清理（macOS / Linux）

rm -rf ~/.claude

清理后重新打开终端，按教程重新配置环境变量。

替代方案（保留聊天记录）：只删除 ~/.claude/settings.json 和 ~/.claude/config.json，然后重新配置。

同时检查系统中是否残留旧环境变量：

Windows 检查

Get-ChildItem Env: | findstr ANTHROPIC
Get-ChildItem Env: | findstr CLAUDE

macOS / Linux 检查

env | grep -E "CLAUDE|ANTHROPIC"

Windows 默认禁止运行未签名的 PowerShell 脚本。

修改执行策略

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

系统提示确认时输入 Y 回车。

Windows：以管理员身份运行 PowerShell

# 右键开始菜单 → Windows PowerShell（管理员）
npm install -g @anthropic-ai/claude-code

macOS / Linux：使用 sudo

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

或配置 npm 全局目录到用户目录（无需 sudo）：

配置用户级全局目录

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

这类错误通常是临时性的，重新打开程序即可解决。

如果持续出现，请检查：

• 账户额度是否充足

• API 密钥是否有效（未被删除或过期）

• 网络连接是否正常

更新

# WinGet (Windows)
winget upgrade Anthropic.ClaudeCode

# 官方脚本 (macOS/Linux)
curl -fsSL https://claude.ai/install.sh | sh

# npm 方式
claude update

卸载

# npm 卸载
npm uninstall -g @anthropic-ai/claude-code

# 清理配置（可选）
# Windows: Remove-Item "$env:USERPROFILE\.claude" -Recurse -Force
# macOS/Linux: rm -rf ~/.claude

Claude Code 命令速查

常用斜杠命令、CLI 参数和快捷键。

斜杠命令

命令	用途
`/help`	获取使用帮助
`/status`	查看账户和系统状态
`/config`	查看/修改配置
`/cost`	显示 Token 使用统计
`/clear`	清除对话历史
`/compact`	压缩对话（释放上下文空间）
`/init`	初始化项目 CLAUDE.md
`/memory`	编辑 CLAUDE.md 记忆文件
`/review`	请求代码审查
`/doctor`	检查安装健康状况
`/login`	切换账户
`/logout`	登出当前账户
`/bug`	报告错误
`/vim`	切换 Vim 模式

CLI 命令

命令	描述	示例
`claude`	启动交互式会话	`claude`
`claude "query"`	带初始提示启动	`claude "explain this project"`
`claude -p "query"`	非交互模式（输出后退出）	`claude -p "fix the bug"`
`claude -c`	继续最近的对话	`claude -c`
`claude -r <id>`	恢复指定会话	`claude -r abc123`
`claude update`	更新 Claude Code	`claude update`

常用参数

参数	描述
`--print, -p`	非交互模式运行
`--continue, -c`	继续最近对话
`--resume, -r`	通过 ID 恢复会话
`--verbose`	启用详细日志
`--max-turns`	限制代理轮次
`--output-format`	输出格式（text/json/stream-json）
`--system-prompt`	覆盖系统提示（仅 -p 模式）
`--allowedTools`	允许的工具列表

快捷键

快捷键	描述
`Ctrl+C`	取消当前输入或生成
`Ctrl+D`	退出 Claude Code
`Ctrl+L`	清除终端屏幕
`↑ / ↓`	导航命令历史
`Esc + Esc`	编辑上一条消息
`\ + Enter`	多行输入（通用）
`Option+Enter`	多行输入（macOS）
`Shift+Enter`	多行输入（需 /terminal-setup）

其他工具

除 Claude Code 外，我们也支持以下 AI CLI 工具。

⚡

1对1 教学辅导

如果你希望更系统、更高效地掌握这些 AI 工具，我们提供跟进式 1对1 人工教学辅导：覆盖应用安装、上手使用到常用命令，针对 Claude Code、Hermes 等多个 AI 工具进行讲解，并在使用过程中持续答疑。辅导内容会根据你的基础和实际需求安排。

真人辅导 · 持续跟进

系统掌握 AI 工具的使用

采用真人 1对1 形式，按你的实际场景（编程开发 / 项目实践 / 办公提效）安排教学节奏，使用中遇到的问题可持续沟通，帮助你建立完整的使用能力。

¥500

每月 / 持续辅导

辅导内容

📦

应用安装与环境配置

从环境准备开始：Node.js 运行环境、Claude Code、Hermes 等 CLI 工具的安装，以及 API 密钥、环境变量、配置文件的正确设置，逐项确认安装与配置无误。

Windows / macOS / LinuxCC-Switch 配置移动端接入

🎯

使用方法讲解

讲解工具的实际使用方式：与 AI 高效交互的方法、让其理解项目上下文、生成与修改代码、执行自动化任务，将工具用法转化为可落地的操作能力。

实操演示按需安排边练边学

⌨️

常用命令与技巧

系统梳理常用斜杠命令、CLI 参数、快捷键与配置技巧，并延伸到进阶用法（插件、子代理、自动化工作流），帮助你提升使用效率。

命令速查进阶插件效率技巧

🛠️

多个 AI 工具覆盖

涵盖 Claude Code、Hermes，以及 Codex、Gemini CLI、OpenCode 等主流 AI 工具，结合不同场景说明各自适用范围与组合方式。

Claude CodeHermesCodex / Gemini

💬

持续答疑

使用过程中遇到报错、卡点或不确定的操作，可随时沟通。辅导以持续跟进的方式进行，会关注你的学习进度与实际问题。

报错排查持续沟通进度跟进

🚀

结合实际需求

根据你的具体目标（编写脚本、项目开发、文档处理、办公提效等）安排教学内容，使所学能够直接应用到实际工作中。

编程开发项目实践办公提效

开通流程

微信咨询

添加微信，说明你的基础情况与学习方向。

确定方案

根据你的需求与水平，确定辅导重点与节奏。

开始辅导

¥500/月，开始 1对1 跟进式辅导，覆盖安装、使用与答疑。

微信二维码
（待放置）

添加微信咨询

关于 AI 工具的安装、使用、报错等问题，或希望了解辅导详情，可添加微信沟通，将尽快回复。

微信号待填写