205 lines
5.9 KiB
Markdown
205 lines
5.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
XCodeCLI-Shells 是一个智能配置工具集，用于设置 Claude Code 与 XCodeCLI API 路由器的集成。项目包含跨平台的安装脚本，支持 Windows (PowerShell) 和 Unix/Linux/macOS (Bash)，具备自动端点发现和选择功能。
|
||
|
||
## 核心架构
|
||
|
||
### 脚本功能
|
||
- **setup-claude-code.ps1**: Windows PowerShell 配置脚本
|
||
- **setup-claude-code.sh**: Unix/Linux/macOS Bash 配置脚本
|
||
|
||
两个脚本提供相同的功能:
|
||
- 验证 API 密钥格式
|
||
- **智能端点发现**: 自动测试多个 API 端点并选择可用的
|
||
- **自动 API 连接测试**: 使用 `/v1/models` 端点验证连接
|
||
- 创建 Claude Code 配置文件 (~/.claude/settings.json)
|
||
- 设置环境变量 (ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN)
|
||
- 支持环境变量传递 API 密钥 (bash 脚本)
|
||
|
||
### 配置结构
|
||
脚本生成的 settings.json 包含:
|
||
```json
|
||
{
|
||
"env": {
|
||
"ANTHROPIC_BASE_URL": "<自动选择的URL>",
|
||
"ANTHROPIC_AUTH_TOKEN": "<用户API密钥>",
|
||
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": 20000,
|
||
"DISABLE_TELEMETRY": 1,
|
||
"DISABLE_ERROR_REPORTING": 1,
|
||
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": 1,
|
||
"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": 1,
|
||
"MAX_THINKING_TOKENS": 12000
|
||
},
|
||
"model": "sonnet"
|
||
}
|
||
```
|
||
|
||
### 支持的 API 端点
|
||
脚本会按顺序测试以下端点，选择第一个可用的：
|
||
1. `https://api.xcodecli.com`
|
||
2. `https://api2.xcodecli.com`
|
||
|
||
## 常用命令
|
||
|
||
### 🚀 一行命令快速配置
|
||
|
||
#### Windows (PowerShell)
|
||
```powershell
|
||
$key='YOUR_API_KEY'
|
||
iwr -useb https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup-claude-code.ps1 | iex
|
||
```
|
||
|
||
#### Unix/Linux/macOS (Bash)
|
||
```bash
|
||
export API_KEY='YOUR_API_KEY'
|
||
curl -fsSL https://gitea.sususu.cf/sususu/xcodecli-shells/raw/branch/main/setup-claude-code.sh | bash
|
||
```
|
||
|
||
### Windows (PowerShell)
|
||
```powershell
|
||
# 基本使用（自动选择可用端点）
|
||
.\setup-claude-code.ps1 -ApiKey your-api-key
|
||
|
||
# 测试连接（测试所有端点）
|
||
.\setup-claude-code.ps1 -Test -ApiKey your-api-key
|
||
|
||
# 显示当前设置
|
||
.\setup-claude-code.ps1 -Show
|
||
|
||
# 交互模式
|
||
.\setup-claude-code.ps1
|
||
|
||
# 帮助
|
||
.\setup-claude-code.ps1 -Help
|
||
```
|
||
|
||
### Unix/Linux/macOS (Bash)
|
||
```bash
|
||
# 基本使用（自动选择可用端点）
|
||
./setup-claude-code.sh --key your-api-key
|
||
|
||
# 使用环境变量
|
||
export API_KEY='your-api-key'
|
||
./setup-claude-code.sh
|
||
|
||
# 测试连接（测试所有端点）
|
||
./setup-claude-code.sh --test --key your-api-key
|
||
|
||
# 显示当前设置
|
||
./setup-claude-code.sh --show
|
||
|
||
# 交互模式
|
||
./setup-claude-code.sh
|
||
|
||
# 帮助
|
||
./setup-claude-code.sh --help
|
||
```
|
||
|
||
## 智能特性
|
||
|
||
### 自动端点发现
|
||
脚本使用智能算法自动发现和选择最佳可用的 API 端点：
|
||
|
||
1. **端点测试**: 依次测试所有配置的端点
|
||
2. **连通性验证**: 使用 `/v1/models` 端点检查服务可用性
|
||
3. **模型验证**: 确保端点返回有效的模型列表
|
||
4. **自动选择**: 选择第一个通过所有测试的端点
|
||
5. **智能降级**: 如果所有端点都失败，提供手动选择选项
|
||
|
||
### 错误处理和恢复
|
||
- **连接失败**: 自动尝试下一个端点
|
||
- **认证失败**: 提供清晰的错误信息和解决建议
|
||
- **服务不可用**: 智能降级到默认配置
|
||
- **用户选择**: 在失败时允许用户决定是否继续
|
||
|
||
|
||
|
||
## 开发注意事项
|
||
|
||
### PowerShell 脚本特性
|
||
- 支持执行策略绕过: `powershell -ExecutionPolicy Bypass`
|
||
- 彩色输出功能 (Blue/Green/Yellow/Red)
|
||
- 环境变量持久化 (用户级别)
|
||
- JSON 配置验证
|
||
- **智能端点测试**: 自动测试多个 API 端点
|
||
- **Bearer 认证**: 使用标准 `Authorization: Bearer` 头
|
||
- **模型列表验证**: 通过 `/v1/models` 端点验证服务可用性
|
||
|
||
### Bash 脚本特性
|
||
- 依赖 jq 进行 JSON 处理
|
||
- ANSI 颜色输出
|
||
- 临时文件清理
|
||
- 错误处理和回滚机制
|
||
- **环境变量支持**: 支持 `API_KEY` 环境变量
|
||
- **智能端点测试**: 自动测试多个 API 端点
|
||
- **Bearer 认证**: 使用标准 `Authorization: Bearer` 头
|
||
- **模型列表验证**: 通过 `/v1/models` 端点验证服务可用性
|
||
|
||
### 安全考虑
|
||
- API 密钥格式验证 (仅允许字母数字、连字符、下划线)
|
||
- 配置文件自动备份 (时间戳)
|
||
- 敏感信息掩码显示
|
||
- HTTP 状态码验证
|
||
- **端点安全**: 仅测试预定义的可信端点
|
||
- **连接超时**: 自动处理网络超时情况
|
||
|
||
### 配置文件位置
|
||
- Windows: `%USERPROFILE%\.claude\settings.json`
|
||
- Unix/Linux/macOS: `~/.claude/settings.json`
|
||
|
||
## 故障排除
|
||
|
||
### 端点连接问题
|
||
如果所有端点都无法连接：
|
||
1. 检查网络连接
|
||
2. 验证 API 密钥是否有效
|
||
3. 确认防火墙设置允许访问
|
||
4. 检查代理配置
|
||
|
||
### API 密钥认证失败
|
||
如果遇到 401 认证错误：
|
||
1. 验证 API 密钥格式是否正确
|
||
2. 确认密钥是否过期
|
||
3. 检查密钥权限设置
|
||
4. 尝试重新生成密钥
|
||
|
||
### 脚本执行问题
|
||
#### PowerShell 执行策略错误
|
||
```powershell
|
||
powershell -ExecutionPolicy Bypass -File setup-claude-code.ps1
|
||
```
|
||
|
||
#### Bash 权限问题
|
||
```bash
|
||
chmod +x setup-claude-code.sh
|
||
```
|
||
|
||
### 环境变量问题
|
||
#### Windows
|
||
检查用户环境变量是否正确设置：
|
||
```powershell
|
||
[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", [EnvironmentVariableTarget]::User)
|
||
[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", [EnvironmentVariableTarget]::User)
|
||
```
|
||
|
||
#### Unix/Linux/macOS
|
||
检查环境变量：
|
||
```bash
|
||
echo $ANTHROPIC_BASE_URL
|
||
echo $ANTHROPIC_AUTH_TOKEN
|
||
```
|
||
|
||
## 总结
|
||
|
||
XCodeCLI-Shells 现在提供智能化的配置体验：
|
||
- **零配置URL**: 无需手动指定API端点，自动发现可用服务
|
||
- **一键安装**: 支持从远程直接下载执行
|
||
- **智能降级**: 在连接失败时提供多种选择
|
||
- **跨平台一致性**: Windows 和 Unix/Linux/macOS 脚本功能完全一致
|
||
- **用户友好**: 清晰的错误提示和帮助信息
|
||
|
||
通过这些改进，用户只需要关心 API 密钥，其他配置都由脚本智能处理。 |