---

# 📘 LiteLLM 配置指南：NewCli (AWS/Anthropic Proxy)

版本日期: 2025-12-26

适用场景: 对接自定义 Anthropic 代理（NewCli），解决路径拼接 (404)、参数不兼容 (400) 及防火墙拦截 (403) 问题。

## 1. 核心参数规范 (Critical Specs)

无论使用 UI 还是 YAML，必须严格遵守以下三条铁律：

1. **Provider (提供商)**: 必须选 `Anthropic`。
    
    - _原因_: 让 LiteLLM 自动处理 `/v1/messages` 路径拼接和 JSON 格式转换。
        
2. **Base URL (基准地址)**: `https://code.newcli.com/claude/aws`
    
    - > [!WARNING] 警告
        
    - > **严禁**在末尾加 `/v1`。LiteLLM 会自动追加，加了会导致双重路径 (`/v1/v1`) 报 **404**。
        
3. **Model ID (模型名)**: `claude-sonnet-4-5`
    
    - _原因_: 代理商白名单仅支持此 ID。
        

---

## 2. UI 配置方案 (推荐)

**入口**: LiteLLM UI (`/ui`) -> **Models** -> **+ Add Model**

### 基础信息 (General Settings)

|**字段**|**填写内容**|**说明**|
|---|---|---|
|**Model Name**|`claude-sonnet`|客户端调用的别名|
|**Select Provider**|**Anthropic**|⚠️ 必选|
|**Litellm Model Name**|`claude-sonnet-4-5`|真实模型 ID|
|**API Base URL**|`https://code.newcli.com/claude/aws`|⚠️ 末尾无 `/v1`|
|**API Key**|`sk-ant-oat01...`|填入完整 Key|

### 高级参数 (LiteLLM Params / Metadata)

> [!TIP] 关键步骤
> 
> 在 JSON 输入框填入以下内容，用于解决参数兼容性和防火墙拦截。

JSON

```
{
  "drop_params": true,
  "extra_headers": {
    "anthropic-version": "2023-06-01",
    "User-Agent": "curl/7.68.0",
    "Authorization": "Bearer ${NEWCLI_API_KEY}" 
  },
  "no_verify_ssl": true
}
```

_注：如果不使用变量，请在 `Authorization` 里直接填入 `Bearer sk-ant...`_

---

## 3. YAML 文件配置方案 (IaC)

适用于 `docker-compose` 挂载配置。

YAML

```
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: anthropic/claude-sonnet-4-5
      # ⚠️ 重点：Base URL 不带 /v1
      api_base: https://code.newcli.com/claude/aws
      # 建议使用环境变量
      api_key: os.environ/NEWCLI_API_KEY
      extra_headers:
        anthropic-version: "2023-06-01"
        # 伪装 UA 防拦截
        User-Agent: "curl/7.68.0"
        # 强制 Bearer 鉴权 (可选，视代理商严格程度)
        Authorization: "Bearer ${NEWCLI_API_KEY}"

general_settings:
  master_key: sk-1234
  database_url: postgresql://litellm:litellm@litellm-postgres:5432/litellm

litellm_settings:
  # ⚠️ 核心修复：丢弃不兼容参数（如 user, frequency_penalty），解决 400 错误
  drop_params: true
  set_verbose: true
```

---

## 4. 故障排查手册 (Troubleshooting)

|**状态码**|**错误类型**|**根本原因**|**解决方案**|
|---|---|---|---|
|**404**|`NotFoundError`|**路径重复**|检查 `api_base` 是否多写了 `/v1`。应该让 LiteLLM 自动拼接。|
|**400**|`BadRequest`|**参数冗余**|LiteLLM 传了 OpenAI 专有参数给 Anthropic。需开启 `drop_params: true`。|
|**403**|`Forbidden`|**WAF 拦截**|缺少 User-Agent 伪装。需在 header 添加 `"User-Agent": "curl/..."`。|
|**401**|`AuthError`|**鉴权失败**|Key 错误或格式不对。尝试在 `extra_headers` 强制注入 `Authorization: Bearer <key>`。|

---

## 5. 客户端调用示例

验证配置是否成功的标准命令（访问 LiteLLM 端口）：

Bash

```
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      { "role": "user", "content": "Config Test: OK?" }
    ]
  }'
```