# Claude Code 教程

Claude Code 接入教程，覆盖 KaiyunCode 中转配置、API Key、Base URL、模型选择、开发环境和常见错误处理。

Canonical: https://kaiyuncode.com/tutorials/claude-code
Markdown: https://kaiyuncode.com/tutorials/claude-code.md

## 接入要点

Claude Code 使用 Anthropic 兼容链路。KaiyunCode 的 Claude Code Base URL 填站点根地址 https://kaiyuncode.com，不要追加 /v1。

把 ANTHROPIC_AUTH_TOKEN 替换成 KaiyunCode 后台创建的 API Key，并把 ANTHROPIC_API_KEY 留空，避免 Claude Code 优先读取错误变量。

- 配置目录：Windows 为 %USERPROFILE%\.claude，macOS/Linux 为 ~/.claude。
- settings.json 放在 .claude 目录内，用于写入 ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY 和 ANTHROPIC_BASE_URL。
- .claude.json 放在用户根目录，用于标记已完成 onboarding，跳过首次登录。
- 验证方式：运行 claude，授权当前文件夹后发送“您好！”。

## 安装 Claude Code

先准备 Node.js 18+，再安装 Claude Code CLI。Windows 建议用管理员 PowerShell，macOS/Linux 用终端执行。

### Windows PowerShell

```powershell
node --version
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com/
```

### macOS

```bash
brew install node
node --version
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com/
```

### Linux

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs
node --version
npm install -g @anthropic-ai/claude-code
```

## 写入 Windows 配置

在 PowerShell 中执行下面脚本。它会写入 .claude/settings.json 和用户根目录下的 .claude.json。

### PowerShell

```powershell
# 目标目录：C:\Users\<you>\.claude
$dir = Join-Path $env:USERPROFILE ".claude"
$settingsFile = Join-Path $dir "settings.json"
$claudeJsonFile = Join-Path $env:USERPROFILE ".claude.json"

# 创建目录（存在不报错）
New-Item -ItemType Directory -Path $dir -Force | Out-Null

# 1. 写入 settings.json（API 配置）
$settingsJson = @'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "在这里替换成你的_API_KEY",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_BASE_URL": "https://kaiyuncode.com"
  }
}
'@
[System.IO.File]::WriteAllText($settingsFile, $settingsJson, (New-Object System.Text.UTF8Encoding($false)))

# 2. 写入 .claude.json（跳过登录）- 注意这个文件在用户根目录
$claudeJson = @'
{
  "hasCompletedOnboarding": true
}
'@
[System.IO.File]::WriteAllText($claudeJsonFile, $claudeJson, (New-Object System.Text.UTF8Encoding($false)))

Write-Host "配置完成！"
Write-Host " - settings.json: $settingsFile"
Write-Host " - .claude.json: $claudeJsonFile"
```

## 写入 macOS / Linux 配置

在终端中执行下面脚本。ANTHROPIC_AUTH_TOKEN 替换为你的 API Key，ANTHROPIC_BASE_URL 保持 https://kaiyuncode.com。

### Shell

```bash
# 目标目录：~/.claude
dir="$HOME/.claude"
settingsFile="$dir/settings.json"
claudeJsonFile="$HOME/.claude.json"

# 创建目录（存在不报错）
mkdir -p "$dir"

# 1. 写入 settings.json（API 配置）
cat > "$settingsFile" << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "在这里替换成你的_API_KEY",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_BASE_URL": "https://kaiyuncode.com"
  }
}
EOF

# 2. 写入 .claude.json（跳过登录）- 注意这个文件在用户根目录
cat > "$claudeJsonFile" << 'EOF'
{
  "hasCompletedOnboarding": true
}
EOF

echo "配置完成！"
echo " - settings.json: $settingsFile"
echo " - .claude.json: $claudeJsonFile"
```

## 启动验证

重新打开终端或 IDE，运行 claude。提示授权访问当前文件夹时选择 yes，然后输入“您好！”验证。

### Windows PowerShell

```powershell
claude
```

### macOS / Linux

```bash
cat "$HOME/.claude/settings.json"
claude
```

## Claude Code 常见问题

- 401 或 /login 报错通常是 API Key 或环境变量未写入成功，先检查 settings.json。
- ANTHROPIC_BASE_URL 必须是 https://kaiyuncode.com，不要写成 https://kaiyuncode.com/v1。
- .claude.json 在用户根目录，settings.json 在 .claude 目录，两个路径不要写反。
- 如果 Windows 遇到脚本执行策略报错，可用管理员权限调整 ExecutionPolicy 后重试。