Claude Code 安装与常见问题

快速上手 Claude Code，解决安装和使用过程中的常见问题

安装指南

选择您的操作系统，按照详细步骤完成 Claude Code 的安装配置

🪟
Windows 安装教程

系统要求

  • Windows 10 或 Windows 11
  • Node.js 18 或更高版本
  • 稳定的网络连接

1 安装 Node.js 和 git

访问 Node.js 官网，下载并安装最新版本的 Node.js。
同时安装 git，访问 git 官网 下载并安装。

💡 安装提示

下载后双击安装包，按照安装向导完成安装。安装完成后可以通过以下命令验证：

CMD / PowerShell 
node -v

2 安装 Claude Code

打开命令提示符或 PowerShell，运行以下命令安装 Claude Code：

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

3 验证安装

运行以下命令验证 Claude Code 是否安装成功：

CMD / PowerShell 
claude --version

4 配置 API 密钥

4.1 获取 Auth Token

访问 pipidan API 控制台 进行以下操作：

  • 点击控制台 → API 令牌页面
  • 点击「添加令牌」
  • 令牌分组请选择：cc（务必选择此分组，否则可能计费异常）
  • 令牌名称：随意填写
  • 额度建议：设置为无限额度
  • 其他选项保持默认
4.2 配置环境变量
⚠️ 重要提示

请将下方的 sk-xxx 替换为您的实际 API 密钥！

方法一：使用 PowerShell 设置环境变量（推荐）

PowerShell 
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxx", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.pipidan.xyz", "User")

方法二：修改配置文件 ~/.claude/settings.json【例如："C:\Users\你的用户名\.claude\settings.json"，如果不存在文件夹和settings.json，则手动创建】：

JSON 
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "你的专属令牌key",
    "ANTHROPIC_BASE_URL": "https://api.pipidan.xyz",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
    "API_TIMEOUT_MS": "600000"
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}
🔄 重启终端

设置环境变量后，需要重启终端才能生效。

5 启动 Claude Code

进入您的项目目录，然后启动 Claude Code：

CMD / PowerShell 
cd your-project-folder
 claude
🎉 首次使用

首次启动时需要完成一些初始配置：

  • 选择主题样式
  • 确认安全须知
  • 配置终端设置
  • 信任工作目录

🍎
macOS 安装教程

系统要求

  • macOS 10.15 (Catalina) 或更高版本
  • Node.js 18 或更高版本
  • 稳定的网络连接

1 安装 Homebrew（推荐）

如果还没有安装 Homebrew，可以通过以下命令安装：

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

# 执行完毕后，会有下述提示（Next step），请按命令行中的提示继续执行
echo >> /Users/mac/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/mac/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2 安装 Node.js

使用 Homebrew 安装 Node.js：

Terminal 
brew install node

3 安装 Claude Code

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

4 配置 API 密钥

4.1 获取 Auth Token

访问 pipidan API 控制台 进行以下操作：

  • 点击控制台 → API 令牌页面
  • 点击「添加令牌」
  • 令牌分组请选择：cc（务必选择此分组，否则可能出现付费异常）
  • 令牌名称：随意填写
  • 额度建议：设置为无限额度
  • 其他选项保持默认
4.2 配置环境变量
⚠️ 重要提示

请将下方的 sk-xxx 替换为您的实际 API 密钥！

方法一：使用 Bash（推荐）
Terminal 
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bash_profile
echo 'export ANTHROPIC_BASE_URL="https://api.pipidan.xyz"' >> ~/.bash_profile
source ~/.bash_profile
方法二：使用 Zsh（如果使用 Oh My Zsh）
Terminal 
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.pipidan.xyz"' >> ~/.zshrc
source ~/.zshrc
🔄 重启终端

永久设置后需要重启终端才能生效。

5 启动 Claude Code

配置完成后，先进入到工程目录：

Terminal 
cd your-project-folder

运行以下命令启动：

Terminal 
claude
🎉 首次使用

首次启动时需要完成一些初始配置：

  • 选择喜欢的主题（回车）
  • 确认安全须知（回车）
  • 使用默认 Terminal 配置（回车）
  • 信任工作目录（回车）
  • 开始编程！🚀

🐧
Linux 安装教程

系统要求

  • Ubuntu 18.04+, CentOS 7+, Debian 9+ 或其他主流发行版
  • Node.js 18 或更高版本
  • 稳定的网络连接

1 安装 Node.js

Ubuntu/Debian:

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

CentOS/RHEL/Fedora:

Terminal 
sudo dnf install nodejs npm
# 或者对于较老的系统
sudo yum install nodejs npm

2 安装 Claude Code

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

3 配置 API 密钥

3.1 获取 Auth Token

访问 pipidan API 控制台 进行以下操作：

  • 点击控制台 → API 令牌页面
  • 点击「添加令牌」
  • 令牌分组请选择：cc（务必选择此分组，否则可能出现付费异常）
  • 令牌名称：随意填写
  • 额度建议：设置为无限额度
  • 其他选项保持默认
3.2 配置环境变量
⚠️ 重要提示

请将下方的 sk-xxx 替换为您的实际 API 密钥！

Terminal 
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.pipidan.xyz"' >> ~/.bashrc
source ~/.bashrc
🔄 重启终端

设置环境变量后，需要重启终端才能生效。

4 启动 Claude Code

配置完成后，先进入到工程目录：

Terminal 
cd your-project-folder

运行以下命令启动：

Terminal 
claude
🎉 首次使用

首次启动时需要完成一些初始配置：

  • 选择喜欢的主题（回车）
  • 确认安全须知（回车）
  • 使用默认 Terminal 配置（回车）
  • 信任工作目录（回车）
  • 开始编程！🚀

快速开始

安装完成后，这里是一些快速上手的小贴士

🚀 基本命令

启动 Claude Code

Terminal 
claude

检查版本

Terminal 
claude --version

更新到最新版

Terminal 
claude update

⚡ 常用功能

切换模型

在 Claude Code 中输入 /model 来切换不同的AI模型

💡 推荐使用 Sonnet 模型，性价比最高

查看帮助

在 Claude Code 中输入 /help 查看所有可用命令

💡 还可以输入 ? 快捷键

退出程序

按两次 Ctrl+C 或 Ctrl+D 退出

💡 也可以输入 /exit 命令

💡 最佳实践

  • 📁

    在项目根目录启动

    确保在包含代码文件的项目目录中启动 Claude Code，这样 AI 能更好地理解你的项目结构和上下文信息。

  • 🎯

    描述清晰具体

    尽量提供详细的需求描述，包括期望的功能、使用的技术栈、预期效果等，这能帮助 AI 给出更准确的建议。

  • 🔍

    善用代码审查

    让 Claude 帮你审查代码质量、找出潜在问题和优化建议，充分利用 AI 的代码分析能力提升开发效率。

环境变量说明

详细了解 Claude Code 所需的环境变量配置

🔑 必需环境变量

ANTHROPIC_AUTH_TOKEN

您的 API 认证令牌，用于访问 Claude 服务

格式： sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
获取方式： 从 pipidan API 控制台生成
注意： 必须选择 "cc" 分组

ANTHROPIC_BASE_URL

API 服务的基础URL地址

推荐值： https://api.pipidan.xyz
作用： 指定 Claude Code 连接的API服务器
说明： 必须与您的API令牌对应的服务保持一致

⚙️ 配置方法

方法一：临时设置（当前会话有效）

适用于测试或临时使用，关闭终端后失效

Windows (CMD):

CMD 
set ANTHROPIC_AUTH_TOKEN=sk-xxx
set ANTHROPIC_BASE_URL=https://api.pipidan.xyz

Windows (PowerShell):

PowerShell 
$env:ANTHROPIC_AUTH_TOKEN="sk-xxx"
$env:ANTHROPIC_BASE_URL="https://api.pipidan.xyz"

macOS/Linux:

Terminal 
export ANTHROPIC_AUTH_TOKEN="sk-xxx"
export ANTHROPIC_BASE_URL="https://api.pipidan.xyz"

方法二：永久设置（推荐）

设置后永久生效，推荐使用此方法

Windows（系统环境变量）：

  1. 右键点击 "此电脑" → 选择 "属性"
  2. 点击 "高级系统设置"
  3. 在 "系统属性" 窗口中点击 "环境变量"
  4. ⭐ 重要：在 "系统变量" 部分点击 "新建"（多人共享电脑可选择 "用户变量"）
  5. 添加以下两个变量：
    • 变量名：ANTHROPIC_AUTH_TOKEN，变量值：您的API密钥
    • 变量名：ANTHROPIC_BASE_URL，变量值：https://api.pipidan.xyz
  6. 点击 "确定" 保存

macOS/Linux（Bash）：

Terminal 
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.bashrc
echo 'export ANTHROPIC_BASE_URL="https://api.pipidan.xyz"' >> ~/.bashrc
source ~/.bashrc

macOS（Zsh）：

Terminal 
echo 'export ANTHROPIC_AUTH_TOKEN="sk-xxx"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.pipidan.xyz"' >> ~/.zshrc
source ~/.zshrc

✅ 验证配置

设置完成后，可以通过以下命令验证环境变量是否正确配置：

Windows:

CMD/PowerShell 
echo %ANTHROPIC_AUTH_TOKEN%
echo %ANTHROPIC_BASE_URL%

macOS/Linux:

Terminal 
echo $ANTHROPIC_AUTH_TOKEN
echo $ANTHROPIC_BASE_URL
💡 提示

如果显示了正确的值（而不是空白），说明环境变量配置成功

常见问题

Claude Code 使用过程中的常见问题和解决方案

!
Invalid API Key · Please run /login 怎么解决？
这表明 Claude Code 没有检测到环境变量。不要使用 /login 命令，只需参考上面的安装配置部分正确设置环境变量即可。
⚠
显示 offline 是什么原因？
Claude Code 会通过检查网络连接来判断状态。显示 offline 通常不影响正常使用，可能是网络环境限制导致的。
🌐
为什么浏览网页的 Fetch 会失败？
这通常是网络连接问题。建议检查网络稳定性，必要时使用更稳定的网络环境。
❓
如何退出 Claude Code？
按两次 Ctrl+C 或者两次 Ctrl+D 即可退出。
🔄
如何更新 Claude Code？
一行命令搞定：claude update
⚡
出现 529、549 报错怎么解决？
这是服务器负载过高导致的临时错误。建议：
• 稍等几分钟后重试
• 尝试切换到 Sonnet 模型（使用 /model 命令）
• 如持续出现可联系技术支持
🤖
推荐使用哪个模型？
推荐使用 Sonnet 模型：
• 性价比最高：比 Opus 便宜约 5 倍
• 性能优秀：智能程度与 Opus 基本相同
• 切换方法：在 Claude Code 中输入 /model 命令选择