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

# Claude Code 配置指南

> 在 Claude Code 中使用 ToAPIs 作爲 API 後端

## 準備工作

在開始之前，請確保：

1. **已安裝 Claude Code**

   通過 npm 或 pnpm 安裝 Claude Code CLI：

   ```bash theme={null}
   # npm
   npm install -g @anthropic-ai/claude-code

   # pnpm
   pnpm install -g @anthropic-ai/claude-code
   ```

   或訪問 [Claude Code 官方文檔](https://docs.anthropic.com/claude-code) 獲取最新安裝方式

2. **已獲取 ToAPIs API 密鑰**

   登錄 [ToAPIs 控制檯](https://toapis.com/console/token) 獲取您的 API 密鑰（以 `sk-` 開頭）

**提示：** 如果還沒有 ToAPIs 賬戶，請先在 [ToAPIs](https://toapis.com) 註冊並獲取 API 密鑰。

## 配置方式

Claude Code 支持多種方式配置自定義 API 端點，您可以將 ToAPIs 作爲 Anthropic API 的替代後端。

Claude Code 使用兩個不同的 JSON 文件：**onboarding 狀態** 與 **環境變量** 需分別寫入對應文件才能生效。

### 先確認 onboarding 已完成

在用戶主目錄下的 `~/.claude.json` 中設置已完成引導（若文件不存在可創建）：

```json theme={null}
{
  "hasCompletedOnboarding": true
}
```

該文件僅用於 CLI 狀態位；API 密鑰與 base URL 請寫在下面的 `settings.json` 中。

### 方式一：通過 settings.json 配置（推薦）

在 `~/.claude/settings.json`（全局）或項目根目錄的 `.claude/settings.json`（項目級）中配置環境變量，無需修改 shell 配置文件：

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxx",
    "ANTHROPIC_BASE_URL": "https://toapis.com"
  }
}
```

**全局配置**（推薦，對所有項目生效）：

```bash theme={null}
# 創建或編輯 ~/.claude/settings.json
mkdir -p ~/.claude
```

然後將上述 JSON 寫入 `~/.claude/settings.json`。

**項目級配置**（僅對當前項目生效）：

在項目根目錄創建 `.claude/settings.json`。項目級文件中不要包含 API Key，建議只在全局配置中寫 `ANTHROPIC_AUTH_TOKEN`，項目配置中只寫 `ANTHROPIC_BASE_URL`：

```json theme={null}
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://toapis.com"
  }
}
```

> **注意：** `hasCompletedOnboarding` 放在 `~/.claude.json`，`env` 放在 `~/.claude/settings.json` 或 `.claude/settings.json`，不要混寫到同一個文件中。

### 方式二：通過環境變量配置

適用於臨時使用或 CI/CD 環境。

#### macOS / Linux

在終端中臨時設置（當前會話有效）：

```bash theme={null}
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxx"
export ANTHROPIC_BASE_URL="https://toapis.com"
claude
```

永久配置，將以下內容添加到 `~/.bashrc` 或 `~/.zshrc`：

```bash theme={null}
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxx"
export ANTHROPIC_BASE_URL="https://toapis.com"
```

然後執行：

```bash theme={null}
source ~/.zshrc  # 或 source ~/.bashrc
```

#### Windows

在 PowerShell 中臨時設置：

```powershell theme={null}
$env:ANTHROPIC_AUTH_TOKEN = "sk-xxxxxxxxxxxx"
$env:ANTHROPIC_BASE_URL = "https://toapis.com"
claude
```

永久配置（系統級）：

```powershell theme={null}
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-xxxxxxxxxxxx", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://toapis.com", "User")
```

### 方式三：使用 `.env` 文件

在您的項目根目錄創建 `.env` 文件：

```bash theme={null}
ANTHROPIC_AUTH_TOKEN=sk-xxxxxxxxxxxx
ANTHROPIC_BASE_URL=https://toapis.com
```

**注意：** 請將 `.env` 添加到 `.gitignore`，避免泄露 API 密鑰。

### 配置說明

| 配置項                        | 填寫內容                                |
| -------------------------- | ----------------------------------- |
| **ANTHROPIC\_AUTH\_TOKEN** | 您的 ToAPIs API 密鑰（`sk-xxxxxxxxxxxx`） |
| **ANTHROPIC\_BASE\_URL**   | `https://toapis.com`                |

## 驗證配置

配置完成後，運行以下命令驗證連接是否正常：

```bash theme={null}
claude --version
```

然後啓動 Claude Code：

```bash theme={null}
claude
```

如果配置正確，Claude Code 將通過 ToAPIs 連接到 Claude 模型並正常響應。

## 推薦模型

通過 ToAPIs 您可以使用以下 Claude 模型：

| 模型名稱              | 模型 ID                       | 特點             |
| ----------------- | --------------------------- | -------------- |
| Claude Opus 4.6   | `claude-opus-4-6`           | 最強大，適合複雜任務     |
| Claude Sonnet 4.6 | `claude-sonnet-4-6`         | 性能與速度平衡，推薦日常使用 |
| Claude Haiku 4.5  | `claude-haiku-4-5-20251001` | 快速響應，適合簡單任務    |

切換模型可使用 `/model` 命令，或在啓動時通過 `--model` 參數指定：

```bash theme={null}
claude --model claude-sonnet-4-6
```

## 常見問題

### Q1: 出現 `Authentication error` 或 `401 Unauthorized`？

**解決方案：**

1. 檢查 `ANTHROPIC_AUTH_TOKEN` 是否正確設置，確認以 `sk-` 開頭
2. 在 [ToAPIs 控制檯](https://toapis.com/console/token) 確認密鑰未過期
3. 確認賬戶餘額充足

### Q2: 出現 `Connection refused` 或無法連接？

**解決方案：**

1. 確認 `ANTHROPIC_BASE_URL` 設置爲 `https://toapis.com`
2. 檢查網絡連接，確保能訪問 `https://toapis.com`
3. 如在國內，可能需要配置代理

### Q3: 如何查看當前環境變量配置？

```bash theme={null}
echo $ANTHROPIC_AUTH_TOKEN
echo $ANTHROPIC_BASE_URL
```

### Q4: 常見錯誤碼說明

| 錯誤信息                        | 原因          | 解決方法        |
| --------------------------- | ----------- | ----------- |
| `401 Unauthorized`          | API 密鑰無效或過期 | 重新獲取 API 密鑰 |
| `429 Too Many Requests`     | 請求頻率超限      | 稍等片刻後重試     |
| `500 Internal Server Error` | 服務器臨時故障     | 等待幾分鐘後重試    |
| `insufficient_quota`        | 賬戶餘額不足      | 前往控制檯充值     |

## 使用技巧

### 1. 在項目中快速啓動

進入項目目錄後直接運行 `claude`，Claude Code 會自動讀取項目上下文：

```bash theme={null}
cd /your/project
claude
```

### 2. 常用命令

| 命令                 | 說明             |
| ------------------ | -------------- |
| `/help`            | 查看幫助信息         |
| `/model`           | 切換模型           |
| `/clear`           | 清空當前對話         |
| `/exit` 或 `Ctrl+C` | 退出 Claude Code |

### 3. 與代碼協作

Claude Code 能夠讀取和修改項目文件，常用場景：

* **代碼審查** - 讓 Claude Code 審查您的代碼並提出改進建議
* **生成代碼** - 描述需求，Claude Code 直接生成並寫入文件
* **調試錯誤** - 粘貼錯誤信息，獲取調試建議
* **重構代碼** - 讓 Claude Code 優化代碼結構

## 支持與幫助

如果您在使用過程中遇到任何問題：

* 📚 [ToAPIs 文檔中心](https://docs.toapis.com)
* 📚 [Claude Code 官方文檔](https://docs.anthropic.com/claude-code)
* 💬 [Discord 社區](https://discord.gg/hvnszCrJ73)
* 🐦 [Twitter @toapisai](https://x.com/toapisai)

***

\[## 開始使用 ToAPIs

立即註冊 ToAPIs，獲取您的 API 密鑰，在 Claude Code 中開啓高效編程之旅！]\([https://toapis.com](https://toapis.com))