> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> 在 macOS、Windows 原生环境与 WSL 2 中配置 Claude Code，通过 Anthropic Messages API 使用 Yelu AI API。

Claude Code 可以通过 Yelu 转发 Anthropic Messages 请求。网关根地址应配置为 `https://api.yelu.ai`，Claude Code 会自动追加 `/v1/messages`。

<Info>
  请使用 [`GET /v1/models`](/zh/api-reference/models) 返回的模型。以下命令使用 Yelu 网关支持的 `claude-sonnet-4-6`；该模型是否可用仍取决于当前 Key 的权限。
</Info>

## 配置速览

| 配置项                | 值                           |
| ------------------ | --------------------------- |
| Base URL           | `https://api.yelu.ai`       |
| 凭证环境变量             | `ANTHROPIC_AUTH_TOKEN`      |
| Claude Code 发送的请求头 | `Authorization: Bearer ...` |
| API 格式             | Anthropic Messages          |
| 示例模型               | `claude-sonnet-4-6`         |

不要在 `ANTHROPIC_BASE_URL` 后添加 `/v1`，否则最终路径会错误地变成 `/v1/v1/messages`。

## macOS

### 1. 安装 Claude Code

推荐使用原生安装器：

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://claude.ai/install.sh | bash
claude --version
```

也可以使用 Homebrew：

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
brew install --cask claude-code
```

### 2. 配置当前终端

从 Yelu 控制台复制 API Key，然后执行：

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
read -s "YELU_API_KEY?Yelu API key: "
echo
export YELU_API_KEY
export ANTHROPIC_AUTH_TOKEN="$YELU_API_KEY"
export ANTHROPIC_BASE_URL="https://api.yelu.ai"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
```

输入内容不会写入 Shell History；变量在关闭终端后失效。

### 3. 持久化非敏感配置

把以下内容加入 `~/.zshrc`：

```bash ~/.zshrc theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ANTHROPIC_BASE_URL="https://api.yelu.ai"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
```

重新加载配置：

```bash macOS theme={"theme":{"light":"github-light","dark":"github-dark"}}
source ~/.zshrc
```

登录时从 macOS Keychain 或其他 Secret Manager 加载 `YELU_API_KEY`，再设置 `ANTHROPIC_AUTH_TOKEN="$YELU_API_KEY"`。不要把 Key 提交到仓库或写入共享 Shell Profile。

## Windows

### 原生 PowerShell

无需以管理员身份启动 PowerShell：

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
irm https://claude.ai/install.ps1 | iex
claude --version
```

为当前 PowerShell Session 配置 Key，输入时不回显：

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
$secret = Read-Host "Yelu API key" -AsSecureString
$env:YELU_API_KEY = [System.Net.NetworkCredential]::new("", $secret).Password
$env:ANTHROPIC_AUTH_TOKEN = $env:YELU_API_KEY
$env:ANTHROPIC_BASE_URL = "https://api.yelu.ai"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1"
```

持久化非敏感配置：

```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.yelu.ai", "User")
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1", "User")
```

修改用户环境变量后需要打开一个新终端。Key 建议从 Windows Credential Manager 或其他 Secret Manager 加载，也可以每次启动时输入。用户环境变量并不是专用的密钥存储。

Git for Windows 不是必需项。如果已经安装但 Claude Code 找不到 Git Bash，请在 `%USERPROFILE%\.claude\settings.json` 中加入：

```json Claude settings theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}
```

### WSL 2

如果代码仓库和工具链位于 Linux，或需要 Claude Code Sandboxing，请选择 WSL 2。在 WSL 终端内安装和配置，不要在 PowerShell 中执行这些 Linux 命令：

```bash WSL 2 theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://claude.ai/install.sh | bash
read -rsp "Yelu API key: " YELU_API_KEY; echo
export YELU_API_KEY
export ANTHROPIC_AUTH_TOKEN="$YELU_API_KEY"
export ANTHROPIC_BASE_URL="https://api.yelu.ai"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
claude --version
```

WSL 的持久化配置应写入 Linux 发行版内的 `~/.bashrc` 或 `~/.zshrc`。Windows 用户环境变量不能可靠替代 WSL 内的 Shell 变量。

## 可选 Settings 文件

Claude Code 在 macOS 读取 `~/.claude/settings.json`，在 Windows 读取 `%USERPROFILE%\.claude\settings.json`。以下全局配置只持久化地址和模型发现，不存储 Key：

```json Claude settings theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.yelu.ai",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}
```

项目私有配置可使用 `.claude/settings.local.json`，并确保该文件已被 Git 忽略。不要把 Key 写入会提交到仓库的 `.claude/settings.json`。

## 验证网关

先直接测试 API：

<CodeGroup>
  ```bash macOS / WSL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
    -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 16,
      "messages": [{"role": "user", "content": "Reply with: ready"}]
    }'
  ```

  ```powershell Windows PowerShell theme={"theme":{"light":"github-light","dark":"github-dark"}}
  $body = @{
    model = "claude-sonnet-4-6"
    max_tokens = 16
    messages = @(@{ role = "user"; content = "Reply with: ready" })
  } | ConvertTo-Json -Depth 4

  Invoke-RestMethod -Method Post `
    -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
    -Headers @{
      Authorization = "Bearer $env:ANTHROPIC_AUTH_TOKEN"
      "anthropic-version" = "2023-06-01"
    } `
    -ContentType "application/json" `
    -Body $body
  ```
</CodeGroup>

随后从同一个终端启动：

```bash Terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude --model claude-sonnet-4-6
```

在 Claude Code 内执行 `/status`，`Anthropic base URL` 应显示 `https://api.yelu.ai`，凭证来源应为 `ANTHROPIC_AUTH_TOKEN`。使用 `/model` 可切换当前 Yelu 账号开放的其他模型。

## 更新与诊断

```bash Terminal theme={"theme":{"light":"github-light","dark":"github-dark"}}
claude update
claude doctor
claude --debug
```

| 现象                        | 解决方法                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `401 Unauthorized`        | 确认同一个终端内存在有效的 `ANTHROPIC_AUTH_TOKEN`。                                              |
| 请求仍发送到 Anthropic          | 执行 `/status`，修正 `ANTHROPIC_BASE_URL` 后从已配置终端重启 Claude Code。                        |
| `/v1/v1/messages` 或 `404` | 从 Base URL 中移除 `/v1`。                                                              |
| Unknown model             | 使用 `/model` 或 [`GET /v1/models`](/zh/api-reference/models) 选择当前 Key 可用的 Claude 模型。 |
| 模型未出现在列表                  | 更新 Claude Code，并通过 `claude --debug` 查看 `[gatewayDiscovery]` 日志。                    |
| Windows 新变量未生效            | 设置用户环境变量后关闭并重新打开终端。                                                                |

## 下一步

继续查看 [Claude Code 示例](/zh/examples/claude-code)，完成仓库分析、实现、审查和自动化任务。

## 官方参考

* [Claude Code Advanced setup](https://code.claude.com/docs/en/getting-started)
* [连接 Claude Code 与 LLM Gateway](https://code.claude.com/docs/en/llm-gateway-connect)
* [Claude Code Gateway Protocol](https://code.claude.com/docs/en/llm-gateway-protocol)