erp-ass/docs/CLAUDE_API_CONFIG.md

Claude API 配置指南

概述

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

配置方法

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

在 .env 文件中配置：

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

2. 使用代理服务

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

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

3. 使用自托管服务

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

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

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

AWS Bedrock (通过代理)

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 兼容)

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

   ANTHROPIC_BASE_URL: str | None = None  # Optional custom base URL
   

2. API 客户端初始化: backend/app/core/ai_engine.py

   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 文档
• OpenRouter 文档
• 项目 README