# Claude API 配置指南

## 概述

本项目支持自定义 Anthropic API 的 base URL，允许您使用代理服务或自托管服务。

## 配置方法

### 1. 使用官方 Anthropic API（默认）

在 `.env` 文件中配置：

```bash
ANTHROPIC_API_KEY=your-api-key-here
# 不需要设置 ANTHROPIC_BASE_URL，将自动使用官方 API
```

### 2. 使用代理服务

如果您使用代理服务（例如 OpenRouter、AWS Bedrock 代理等），配置如下：

```bash
ANTHROPIC_API_KEY=your-api-key-here
ANTHROPIC_BASE_URL=https://your-proxy-service.com/v1
```

### 3. 使用自托管服务

如果您部署了自托管的 Claude API 兼容服务：

```bash
ANTHROPIC_API_KEY=your-custom-key
ANTHROPIC_BASE_URL=http://localhost:8080/v1
```

## 配置参数说明

| 参数 | 类型 | 必需 | 默认值 | 说明 |
|------|------|------|--------|------|
| `ANTHROPIC_API_KEY` | string | ✅ 是 | - | Anthropic API 密钥或自定义密钥 |
| `ANTHROPIC_BASE_URL` | string | ❌ 否 | `None` | 自定义 API 端点 URL |
| `CLAUDE_MODEL` | string | ❌ 否 | `claude-sonnet-4-6` | 使用的模型名称 |
| `CLAUDE_MAX_TOKENS` | int | ❌ 否 | `8192` | 最大生成 token 数 |
| `CLAUDE_TEMPERATURE` | float | ❌ 否 | `0.7` | 生成温度（0-2） |

## 支持的代理服务示例

### OpenRouter

```bash
ANTHROPIC_API_KEY=sk-or-xxx
ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
CLAUDE_MODEL=anthropic/claude-sonnet-4-6
```

### AWS Bedrock (通过代理)

```bash
ANTHROPIC_API_KEY=your-aws-key
ANTHROPIC_BASE_URL=https://bedrock.us-east-1.amazonaws.com
CLAUDE_MODEL=anthropic.claude-3-sonnet-20240229-v1:0
```

### Azure OpenAI (Claude 兼容)

```bash
ANTHROPIC_API_KEY=your-azure-key
ANTHROPIC_BASE_URL=https://your-resource.openai.azure.com
CLAUDE_MODEL=claude-sonnet-4-6
```

## 代码实现

配置在以下文件中实现：

1. **配置定义**: `backend/app/config.py`
   ```python
   ANTHROPIC_BASE_URL: str | None = None  # Optional custom base URL
   ```

2. **API 客户端初始化**: `backend/app/core/ai_engine.py`
   ```python
   client_kwargs = {"api_key": settings.ANTHROPIC_API_KEY}
   if settings.ANTHROPIC_BASE_URL:
       client_kwargs["base_url"] = settings.ANTHROPIC_BASE_URL
   self.client = anthropic.AsyncAnthropic(**client_kwargs)
   ```

## 验证配置

启动后端服务后，检查日志输出：

```
[INFO] Using custom Anthropic base URL: https://your-proxy.com
```

如果看到此日志，说明自定义 base URL 已生效。

## 故障排查

### 问题 1: 连接超时

**症状**: API 调用超时或连接失败

**解决方案**:
- 检查 `ANTHROPIC_BASE_URL` 是否正确
- 确认代理服务可访问
- 检查网络防火墙设置

### 问题 2: 认证失败

**症状**: 401 Unauthorized 错误

**解决方案**:
- 验证 `ANTHROPIC_API_KEY` 是否正确
- 确认代理服务的认证方式
- 检查 API key 是否有权限访问指定模型

### 问题 3: 模型不存在

**症状**: 404 Not Found - Model not found

**解决方案**:
- 确认代理服务支持您指定的 `CLAUDE_MODEL`
- 检查模型名称格式（不同服务可能使用不同的命名）

## 安全建议

1. **不要提交 `.env` 文件到 Git**
   - `.env` 文件已在 `.gitignore` 中
   - 只提交 `.env.example` 模板

2. **生产环境配置**
   - 使用环境变量或密钥管理服务
   - 不要在代码中硬编码 API key

3. **API Key 权限**
   - 使用最小权限原则
   - 定期轮换 API key
   - 监控 API 使用情况

## 相关文档

- [Anthropic API 文档](https://docs.anthropic.com/)
- [OpenRouter 文档](https://openrouter.ai/docs)
- [项目 README](./README.md)