sususu/xcodecli-shells
Private
Public Access
1
0
Fork 0
Code Activity
Files
dbea04aa17f42992f40da030e75d38a3d831f44c
xcodecli-shells/CLAUDE.md

5.9 KiB
Raw Blame History

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 包含:

{
  "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)

$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)

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)

# 基本使用（自动选择可用端点）
.\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)

# 基本使用（自动选择可用端点）
./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 -ExecutionPolicy Bypass -File setup-claude-code.ps1

Bash 权限问题

chmod +x setup-claude-code.sh

环境变量问题

Windows

检查用户环境变量是否正确设置：

[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", [EnvironmentVariableTarget]::User)

Unix/Linux/macOS

检查环境变量：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

总结

XCodeCLI-Shells 现在提供智能化的配置体验：

  • 零配置URL: 无需手动指定API端点，自动发现可用服务
  • 一键安装: 支持从远程直接下载执行
  • 智能降级: 在连接失败时提供多种选择
  • 跨平台一致性: Windows 和 Unix/Linux/macOS 脚本功能完全一致
  • 用户友好: 清晰的错误提示和帮助信息

通过这些改进，用户只需要关心 API 密钥，其他配置都由脚本智能处理。

View Git Blame Copy Permalink