Claude Code详细版 – 云石教程站

Claude Code 是一款运行在终端里的 AI 编程助手。本教程按 Windows / macOS / Linux 三个平台分别给出图文步骤，跟着做即可完成安装并接入云石 API。

本文同时适用于 Claude Code CLI（终端）与配套的编辑器插件。只需接入 API 的话，看「三、安装配置」中的环境变量部分即可；想少走弯路，推荐顺带装一个 CC Switch（见《CC Switch 简明使用指南》）。

一、适用版本

项目	要求	说明
Claude Code CLI	2.x（核对时实测 2.1.x）	可通过 `claude update` 自更新
Node.js	22 或更高	自 v2.1.198 起的要求；旧版本会提示 `EBADENGINE` 警告，但仍能安装运行
Windows	Windows 10 / 11	需要 Git Bash；也可改用官方原生安装脚本（不需要 Node.js）
macOS	macOS 12 及以上	支持 Intel 与 Apple Silicon
Linux	主流发行版 x64 / ARM64	Alpine 等 musl 系需先补 bash、curl、ripgrep 等依赖
云石令牌	Claude 分组	用其他分组会报模型不存在

版本核对日期：2026-09-23。Claude Code 迭代很快，实际以官方最新版为准。

二、前置条件

已注册云石账号并创建 Claude 分组的令牌（sk- 开头），获取方式见《云石新手教程》。
令牌复制完整、首尾无空格。
本机可以访问 https://yyoo.xyz。
准备好三样东西：接口地址 https://yyoo.xyz、API Key、模型名（如 claude-sonnet-4-6）。

权限说明：

安装 Claude Code 不要用 sudo（Linux / macOS）或以管理员身份运行（Windows）。用 root 装全局 npm 包会留下 root 属主目录，后续升级与自动更新都会失败。
遇到 EACCES / permission denied，正确做法是配置用户级 npm 前缀（见 6.1）或改用原生安装脚本，而不是提权。
安装过程会在用户目录写入配置（~/.claude/、~/.claude.json），这些文件含登录凭证，建议仅本人可读。
Claude Code 会读写当前项目文件、执行 shell 命令，这是它的正常工作方式；请只在可信目录中使用。

三、安装配置

3.1 Windows 端

1. 安装 Node.js 环境

Claude Code 需要 Node.js 环境才能运行。

Node.js 环境安装步骤

打开浏览器访问 https://nodejs.org/
点击 “LTS” 版本进行下载（推荐长期支持版本）
下载完成后双击 .msi 文件
按照安装向导完成安装，保持默认设置即可

Windows 注意事项

建议使用 PowerShell 而不是 CMD
如果遇到权限问题，尝试以管理员身份运行
某些杀毒软件可能会误报，需要添加白名单

验证安装是否成功

安装完成后，打开 PowerShell 或 CMD，输入以下命令：

node -v

npm -v

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

2. 安装 Git Bash

Windows 注意事项

Windows 环境下需要使用 Git Bash 安装 Claude Code。安装完成后，环境变量设置和使用 Claude Code 仍然在普通的 PowerShell 或 CMD 中进行。

下载并安装 Git for Windows

访问 https://git-scm.com/downloads/win
点击 “Download for Windows” 下载安装包
运行下载的 .exe 安装文件
在安装过程中保持默认设置，直接点击 “Next” 完成安装

验证 Git Bash 安装

安装完成后，打开 Git Bash，输入以下命令验证：

git --version

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

3. 安装 Claude Code

打开 PowerShell（或 CMD），运行以下命令：

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

这个命令会从 npm 官方仓库下载并安装最新版本的 Claude Code。

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

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

如果出现以下情况

修改配置文件，在 C 盘用户目录里面找到 .claude.json 文件，右键用记事本打开，在最后一行输入英文逗号，在下一行添加：

"hasCompletedOnboarding": true

保存，再回到 CMD 里面输入 claude，点 yes。

3.1.4 配置环境变量（接入云石 API）

Windows 下把接口地址与令牌写入用户环境变量（在 PowerShell 中执行，逐条运行）：

setx ANTHROPIC_BASE_URL "https://yyoo.xyz"
setx ANTHROPIC_AUTH_TOKEN "sk-你的令牌"

setx 设置的是永久环境变量，必须重开一个 PowerShell 窗口才会生效（只重开当前窗口内的标签页不算）。

验证是否写入成功：

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN

3.2 macOS 端

1. 安装 Claude Code CLI

打开终端：

安装 Claude Code

打开终端，运行以下命令：

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

可选项：出现提示后运行提供的命令

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

2. 设置环境变量

为了让 Claude Code 连接到第三方中转服务，需要设置环境变量。

一键设置 Claude Code 环境变量

输入命令：

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/claude-cli-setup.sh | bash

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

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

3.3 Linux 端

1. 安装 Claude Code

安装 Claude Code

打开终端，运行以下命令：

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

如果遇到权限问题，可以使用 sudo：

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

验证 Claude Code 安装

安装完成后，输入以下命令检查是否安装成功：

claude --version

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

2. 设置环境变量

为了让 Claude Code 连接到中转服务，需要设置两个环境变量。

一键修改环境变量

输入命令：

curl -fsSL https://raw.githubusercontent.com/QuantumNous/new-api-docs/refs/heads/main/helper/claude-cli-setup.sh | bash

设置 ANTHROPIC_BASE_URL 之后，所有模型都会走自定义接入点，不再消耗官方账号额度——包括在 /model 里选到的官方预设模型。这是预期行为，不是故障。

四、核心操作

4.1 Windows 端日常使用

现在你可以开始使用 Claude Code 了！

启动 Claude Code

打开 PowerShell，直接启动 Claude Code：

claude

在特定项目中使用：

# 进入你的项目目录
cd C:pathtoyourproject
# 启动 Claude Code
claude

选择模型

输入命令：

/model

按 Enter 进入，选择模型，通常使用默认设置即可。

注意：设置环境变量修改后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

4.2 macOS 端日常使用

现在你可以开始使用 Claude Code 了！

启动 Claude Code

claude

在特定项目中使用：

# 进入你的项目目录
cd /path/to/your/project
# 启动 Claude Code
claude

选择模型（可选）

输入命令：

/model

按 Enter 进入，选择官方模型，通常使用默认模型即可。

注意：设置环境变量修改 ANTHROPIC_BASE_URL 后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

4.3 Linux 端日常使用

<div class='alert alert-primary'><span class='alert-inner--text'></span></div>注意：设置环境变量修

现在你可以开始使用 Claude Code 了！

直接启动 Claude Code：

claude

在特定项目中使用：

# 进入你的项目目录
cd /path/to/your/project
# 启动 Claude Code
claude

选择模型：

/model

按 Enter 进入，选择官方模型，通常使用默认模型即可。

注意：设置环境变量修改 ANTHROPIC_BASE_URL 后，使用所有模型（包括官方预设模型）均调用自定义接入点，而不使用官方账号额度。

4.4 常用命令速查

命令	作用
`claude`	在当前目录启动 Claude Code
`claude --version`	查看已安装版本
`claude doctor`	安装与配置体检，排查问题第一步
`claude update`	手动触发更新
`npm install -g @anthropic-ai/claude-code@latest`	npm 安装方式的升级命令（务必带 `@latest`）
`/model`	会话内切换模型
`/status`	查看当前接口地址、模型与配置来源
`/logout`	退出当前登录态，用于清理冲突的环境变量/凭证

五、验证方法

步骤	操作	预期结果
1. 版本可查	`claude --version`	输出版本号，如 `2.1.211 (Claude Code)`
2. 环境自检	`claude doctor`	输出安装状态与配置校验结果，无报错项
3. 接入正确	启动后执行 `/status`	接口地址显示为 `https://yyoo.xyz`，不是官方地址
4. 端到端	发一条低风险指令：「读一下当前目录结构并总结，不要改文件」	正常流式回复并给出结构说明
5. 用量确认	登录云石后台查看使用日志	能看到刚才这次请求的模型与 Token 消耗

五步都通过，说明安装与接入都已正常。若第 3 步地址仍是官方地址，参考 6.3 检查环境变量优先级。

六、常见问题

6.1 Windows 端

1. 安装时提示 “permission denied” 错误

这通常是权限问题，尝试以下解决方法：

以管理员身份运行 PowerShell，或者配置 npm 使用用户目录：

npm config set prefix %APPDATA%npm

2. PowerShell 禁止运行脚本

如果遇到执行策略限制，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

3. 环境变量设置后不生效

配置完环境变量之后需要：

重新启动 PowerShell 或 CMD，或者注销并重新登录 Windows（也就是关机重启）。

验证设置：

echo $env:ANTHROPIC_BASE_URL

echo $env:ANTHROPIC_AUTH_TOKEN

4. 命令行启动 Claude 的时候有乱码闪烁

是因为 Windows 终端 + UTF-8 + Bash 输出混合造成的编码显示不一致而导致的。

chcp 65001

5. 所在地区不可用

配置之后如果出现以下情况（选做，没有这种情况可以跳过）

原因：缺了引导，下图为解决方案

{
  ......
  "hasCompletedOnboarding": true,
  ......
}

6. 环境变量冲突

直接输入：

/logout

然后再次启动 claude 即可：

claude

6.2 macOS 端

macOS 安全设置阻止运行

如果系统阻止运行 Claude Code：

打开 “系统偏好设置” → “安全性与隐私”
点击 “仍要打开” 或 “允许”
或者在 Terminal 中运行：sudo spctl --master-disable

6.3 Linux 端

缺少依赖库：某些 Linux 发行版需要安装额外依赖。

# Ubuntu / Debian
sudo apt install build-essential

# CentOS / RHEL
sudo dnf groupinstall "Development Tools"

环境变量不生效，检查以下几点：

确认修改了正确的配置文件（.bashrc 或 .zshrc）
重新启动终端或运行 source ~/.bashrc
验证设置：echo $ANTHROPIC_BASE_URL

6.4 三端通用问题

现象	原因与处理
报 401 / 认证失败	令牌复制不全或带空格；或令牌分组不是 Claude 分组。重新完整复制一次。
报 404 / 模型不存在	接口地址写成 `https://yyoo.xyz/v1` 或带了多余路径。Claude 系工具只填 `https://yyoo.xyz`。
改了环境变量但不生效	旧终端进程仍持有旧值。彻底关闭所有终端窗口（Windows 建议注销一次）后重开。
升级后命令找不到	切换过 Node 版本会导致全局目录变化。用 `which -a claude`（Windows：`where claude`）确认实际路径，或改用原生安装方式。
多套安装方式混用导致版本错乱	npm、官方脚本、Homebrew 混装会互相覆盖。每台机器只保留一种安装方式。

七、回滚 / 卸载

7.1 只回滚接入（回到官方账号）

清除自定义接入点环境变量：ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN（Windows 在「系统属性 → 环境变量」中删除；macOS / Linux 从 .bashrc / .zshrc 中删除对应导出行）。
重启终端，执行 /logout，再正常登录官方账号即可。

7.2 备份先于删除

# macOS / Linux
cp ~/.claude.json ~/.claude.json.bak
cp -r ~/.claude ~/.claude.bak

# Windows PowerShell
Copy-Item "$env:USERPROFILE\.claude.json" "$env:USERPROFILE\.claude.json.bak"
Copy-Item "$env:USERPROFILE\.claude" "$env:USERPROFILE\.claude.bak" -Recurse

7.3 完全卸载

安装方式	卸载操作
npm 安装	`npm uninstall -g @anthropic-ai/claude-code`
官方脚本安装	删除可执行文件 `~/.local/bin/claude`，并清理 shell 配置里对应的 PATH 导出行
Homebrew	`brew uninstall --cask claude-code`
残留配置	按需删除 `~/.claude.json` 与 `~/.claude/`（会一并清除登录态与历史记录）

删除 ~/.claude 会同时清掉登录凭证、项目历史与自定义配置，请确认已备份。

八、更新记录

日期	版本	修改内容
2026-09-23	v2.0	知识库检查修订：重排为八大章节；补上 Windows 端缺失的环境变量配置步骤（原文只有警告没有操作，Windows 用户按原文无法接入）；补充 Node.js 版本要求、权限说明、常用命令速查、验证方法、回滚/卸载与更新记录；图片改为相对路径并补充 alt 文本
2026-09-22	v1.0	首次发布：Windows / macOS / Linux 三平台图文安装指引与常见问题