# LiteLLM Proxy — Claude Code × xAI Grok

用 [LiteLLM](https://github.com/BerriAI/litellm) 在本地架一個 proxy server，讓 **Claude Code** 透過 Anthropic API 格式呼叫 **xAI Grok** 模型。

## 架構

```
Claude Code
    │  ANTHROPIC_BASE_URL=http://localhost:4000
    ▼
LiteLLM Proxy (Docker, port 4000)
    │  model_list 路由
    ▼
xAI API (api.x.ai)
    └─ grok-4-1-fast-non-reasoning
```

## 檔案結構

```
litellm-proxy/
├── docker-compose.yml      # 啟動 LiteLLM Docker 容器
├── litellm_config.yaml     # 模型路由設定
├── .env                    # xAI API Key（不要上傳到 git！）
└── settings.json           # 本地備份用的 claude settings 範例
```

## 快速開始

### 1. 設定 API Key

編輯 `.env`：

```env
XAI_API_KEY=xai-你的金鑰
```

### 2. 啟動 Proxy

```bash
docker compose up -d
```

### 3. 設定 Claude Code

將以下內容寫入 `~/.claude/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-my-local-litellm-key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "grok-4-1-fast-reasoning",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "grok-4-1-fast-reasoning",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "grok-4-1-fast-reasoning"
  }
}
```

> `ANTHROPIC_AUTH_TOKEN` 填的是 LiteLLM 的 `master_key`，不是真實的 Anthropic 或 xAI key。

### 4. 啟動 Claude Code

```bash
claude
```

## 常用指令

| 指令 | 說明 |
|------|------|
| `docker compose up -d` | 背景啟動 proxy |
| `docker compose down` | 停止 proxy |
| `docker compose logs -f` | 查看即時 log |
| `docker compose down && docker compose up -d` | 重啟（套用新設定） |

## 設定說明

### `litellm_config.yaml`

```yaml
model_list:
  - model_name: grok-4-1-fast-reasoning   # Claude Code 看到的模型名稱
    litellm_params:
      model: xai/grok-4-1-fast-non-reasoning  # 實際送給 xAI 的模型
      api_key: os.environ/XAI_API_KEY

litellm_settings:
  master_key: sk-my-local-litellm-key  # Claude Code 用的假 API Key
  drop_params: true                    # 忽略 xAI 不支援的 Claude 專屬參數
```

**為什麼用 `non-reasoning` 模型？**
Claude Code 本身是 agentic AI，reasoning 在 Claude Code 層進行。底層模型使用 non-reasoning 版本可避免 LiteLLM 的參數轉換 bug（`reasoningEffort` camelCase 問題），速度也更快。

## 注意事項

- `.env` 內含真實 API Key，請加入 `.gitignore` 避免上傳
- 修改 `litellm_config.yaml` 後需重啟 docker 才會生效
- `~/.claude/settings.json` 修改後**立即生效**，不需重啟