github.com/hxz0727/API-Switch

Release v1.0.1-0.20260725141841-788d7e87fcf5

Claude Code 多模型代理 — 一键切换 DeepSeek、Qwen、GLM、Moonshot 等国产大模型，协议自动转换，零配置即用

Homepage Go Go Documentation

Keywords
anthropic, claude-code, deepseek, mimo, qwen
Install
go get github.com/hxz0727/API-Switch

Documentation

API-Switch

Gitee 镜像: https://gitee.com/776311606/API-Switch

Claude Code 多模型代理 — 一键切换 DeepSeek、Qwen（通义千问）、GLM（智谱）、Moonshot（月之暗面）、Agnes AI 等大模型，协议自动转换，零配置即用。

接收 Anthropic 格式请求，根据模型名自动路由到对应提供商，协议自动转换，模型即切即用。

claude → api-switch → ├─ claude-*  → Anthropic API (透传)
                       ├─ gpt-4o    → 转 OpenAI 协议 → OpenAI API → 转回 Anthropic 格式
                       ├─ deepseek  → 转 OpenAI 协议 → DeepSeek API → 转回 Anthropic 格式
                       ├─ agnes     → 转 OpenAI 协议 → Agnes AI → 转回 Anthropic 格式
                       └─ qwen      → 转 OpenAI 协议 → DashScope API → 转回 Anthropic 格式

✨ 特性

  • 零配置切换模型 — api-switch use <model> 即刻切换，Claude Code 热加载
  • 多提供商支持 — Anthropic、OpenAI、DeepSeek、Qwen、Moonshot、Agnes AI 等任意 OpenAI 兼容 API
  • 协议自动转换 — Anthropic ↔ OpenAI 双向转换，含流式 SSE、工具调用、多模态图片
  • Provider 模板 — 内置 13 个厂商预设（含 Agnes AI 免费大模型），一条命令添加
  • 安全加固 — API Key 加密存储、Bearer 认证、速率限制、TLS 支持
  • 自动更新 — 启动时自动检测新版本，SHA256 校验和验证，静默下载并重启升级
  • 优雅关闭 — SIGINT/SIGTERM 信号处理，安全关闭代理服务
  • 实时监控 — Web 仪表盘 + 终端实时日志
  • 热加载配置 — 修改配置文件自动生效，无需重启
  • 一键诊断 — api-switch doctor 快速定位配置问题
  • 批量导入 — 自动拉取 API 可用模型列表
  • 端到端测试 — api-switch test [model] 验证代理是否正常工作
  • provider 连通性检测 — api-switch provider test <name> 测试厂商 API 是否可达
  • 用量统计 — api-switch usage 按天统计 Token 用量、缓存命中率
  • 国内镜像 — Gitee 同步 + goproxy.cn 加速安装

v0.9.2 — 安全审计加固版：31 个问题修复、滑动窗口限流、时序安全比对、原子配置、SSE 流稳定性

⚡ 快速开始

方式一：setup 一条命令（推荐）

# 安装
npm install -g api-switch-cc

# 查看所有内置厂商
api-switch provider known

# DeepSeek — 自动填充 base_url、type、建议模型
api-switch setup deepseek --key sk-xxx

# Agnes AI — 免费大模型，注册即用 https://platform.agnes-ai.com/
api-switch setup agnes --key sk-xxx

# 启动（自动检测更新）
api-switch serve

方式二：分步操作

# 1. 查看已知厂商
api-switch provider known

# 2. 添加提供商
api-switch provider add deepseek --key sk-xxx

# 2. 导入模型
api-switch model import deepseek

# 3. 切换模型，启动代理
api-switch use deepseek-chat
api-switch serve

之后正常使用 claude 命令即可，所有请求自动通过代理路由。

📦 安装

npm 安装（推荐）

# 全局安装（秒完成，二进制首次运行时自动安装）
npm install -g api-switch-cc

# 或直接使用（无需安装）
npx api-switch-cc serve

npm 包秒装（无 postinstall 阻塞），二进制在首次运行 api-switch 时自动安装。

# 更新到最新版
api-switch update
# 或
npm install -g api-switch-cc@latest

国内用户： npm 包会自动优先从 gitee.com 版本化镜像下载（release/vX.Y.Z/ 目录），其次尝试 GitHub，最后回退到源码编译或 go install。全程无需手动干预。

一键安装脚本

# 普通用户
curl -sSL https://raw.githubusercontent.com/hxz0727/API-Switch/master/install.sh | bash

# 国内用户（优先 Gitee 镜像）
curl -sSL https://gitee.com/776311606/API-Switch/raw/master/install.sh | bash

脚本会自动：检查/安装 Go → 克隆仓库 → 编译二进制 → 添加到 PATH。

Docker 部署

docker build -t api-switch .
docker run -d -p 8080:8080 \
  -v ~/.api-switch.yaml:/root/.api-switch.yaml \
  -v ~/.claude:/root/.claude \
  api-switch

手动编译

git clone https://github.com/hxz0727/API-Switch.git
cd API-Switch
make build              # 或 go build -o api-switch ./cmd/api-switch/
make install            # 安装到 ~/.local/bin/

🎯 命令参考

无参数运行（新手引导）

$ api-switch

API-Switch — LLM API proxy for Claude Code
================================================

快速开始：
  # 1. 添加一个供应商（支持已知厂商预设）
  api-switch provider add deepseek --key sk-xxx
  ...

Provider 管理

# 从预设模板添加（自动填充 base_url 和 type，未传 --key 会交互式输入）
api-switch provider add deepseek --key sk-xxx
api-switch provider add qwen
# → Enter API key for "qwen": _

# 支持的厂商（共 13 个，运行 api-switch provider known 查看完整列表）
# deepseek  → https://api.deepseek.com
# qwen      → https://dashscope.aliyuncs.com/compatible-mode/v1
# moonshot  → https://api.moonshot.cn/v1
# glm       → https://open.bigmodel.cn/api/paas/v4
# kimi      → https://api.moonshot.cn/v1
# yi        → https://api.lingyiwanwu.com/v1
# step      → https://api.stepfun.com/v1
# ernie     → https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat
# hunyuan   → https://api.hunyuan.cloud.tencent.com/v1
# agnes     → https://apihub.agnes-ai.com/v1        （免费，注册即用）
# apifree   → https://api.apifree.ai/agent/v1
# sensenova → https://token.sensenova.cn/v1          （商汤商量）
# nvidia    → https://integrate.api.nvidia.com/v1    （英伟达）

# 自定义提供商
api-switch provider add my-provider \
  --url https://my-api.com/v1 \
  --type openai \
  --key sk-xxx

# 查看所有提供商
api-switch provider list          # 已配置的提供商
api-switch provider known         # 查看所有内置厂商预设（13 个）

# 测试提供商连通性
api-switch provider test deepseek # 也可用 provider ping

模型管理

# 列出所有模型
api-switch model list          # 也可用 model ls

# 添加模型路由
api-switch model add deepseek-chat deepseek

# 批量导入（自动查询 API 的 /v1/models）
api-switch model import deepseek
api-switch model import openai --filter gpt-4   # 只导入 gpt-4 相关模型

# 删除模型
api-switch model remove deepseek-chat

模型切换

# 查看所有可用模型（→ 标记当前激活的）
api-switch use

# 切换到指定模型
api-switch use gpt-4o
api-switch use deepseek-chat
api-switch use qwen-plus
api-switch use agnes-2.0-flash

setup 一键配置

# 已知厂商（自动填充 type、url、建议模型）
api-switch setup deepseek --key sk-xxx

# 自定义厂商
api-switch setup --name custom --type openai --url https://... --key sk-xxx --models m1,m2

# 以上命令会自动：
#   1. 添加 provider 到配置
#   2. 添加模型到路由表
#   3. 生成 Claude Code settings.json

端到端测试

# 测试当前激活的模型
api-switch test

# 测试指定模型
api-switch test deepseek-chat
# → ✓ Response received (stop_reason=end_turn, input=56, output=10)

启动服务

# 默认 8080 端口（自动同步 settings.json）
api-switch serve

# 自定义端口 + 持久化到配置
api-switch serve -p 9090
# settings.json 和 .api-switch.yaml 自动同步

# 仅运行时使用，不保存到配置
api-switch serve -p 9090 --no-save-port

# 日志级别
api-switch serve -vv                     # debug 级别日志
api-switch serve -v                      # 带请求详情
api-switch serve -q                      # 仅显示错误
api-switch serve --no-auto-update        # 跳过自动更新检查

后台运行（Daemon）

# 启动后台服务
api-switch start

# 查看状态
api-switch status

# 查看日志
api-switch logs

# 重启
api-switch restart

# 停止
api-switch stop

用量统计

# 按天查看 Token 用量和缓存命中率
api-switch usage

# 重置统计
api-switch usage --reset

更新

# 检查更新
api-switch update --check

# 自动更新到最新版
api-switch update

# 启动时自动检测（默认开启）
api-switch serve                    # 自动检查 + 静默升级
api-switch serve --no-auto-update   # 跳过自动检查

监控与诊断

# Web 仪表盘（浏览器打开 http://localhost:8080/admin/）
api-switch monitor --web

# 终端实时监控
api-switch monitor

# 一键诊断
api-switch doctor

配置管理

api-switch config show                # 查看配置（key 脱敏）
api-switch config cat                 # 同上，别名
api-switch config set providers.openai.api_key sk-xxx
api-switch config init                # 创建默认配置

🌐 Web 仪表盘

启动服务后访问 http://localhost:8080/admin/：

  • 实时请求列表（SSE 推送）
  • 请求总数、平均耗时、模型分布统计
  • 每条请求的模型、Provider、耗时、状态

🔧 场景示例

混用 Anthropic + DeepSeek + Agnes AI

# 配置
api-switch provider add anthropic --key sk-ant-xxx --url https://api.anthropic.com --type anthropic
api-switch provider add deepseek --key sk-xxx
api-switch setup agnes --key sk-xxx     # Agnes AI 免费大模型

# 使用
api-switch use deepseek-chat   # 切换到 DeepSeek
api-switch serve
# Claude Code 会话中随时切换：
api-switch use agnes-2.0-flash  # 切到 Agnes AI（免费）
api-switch use claude-sonnet-4-20250514  # 切回 Claude

只用国产模型（Qwen + DeepSeek）

api-switch setup qwen --key sk-xxx
api-switch setup deepseek --key sk-xxx
api-switch use qwen-plus
api-switch serve

免费模型方案（Agnes AI）

# 注册获取 API Key: https://platform.agnes-ai.com/
api-switch setup agnes --key sk-xxx
api-switch use agnes-2.0-flash
api-switch serve
# 零成本使用大模型

实时切换工作流

# 终端 1（代理服务）
api-switch serve

# 终端 2（随时切换模型）
api-switch use gpt-4o           # 切换到 GPT-4o
# Claude Code 自动生效
api-switch use deepseek-chat    # 切换到 DeepSeek
# 也立即生效

📊 架构

                    ┌─ Anthropic Client (透传) ──→ Anthropic API
                    │
claude ──→ /v1/messages ──┤
       POST               │                          ┌─ 请求转换 ──┐
                           └─ OpenAI Client ──→  ──→ │  OpenAI 协议  │ ──→ OpenAI/DeepSeek/Agnes 等
                                                     └─ 响应转换 ──┘

管理端点:
  /health          → 健康检查 (JSON: models, providers, requests)
  /admin/          → Web 仪表盘
  /admin/stats     → JSON 统计
  /admin/events    → SSE 实时事件
  /admin/reload    → 热加载配置 (POST)

⚙️ 核心概念

配置文件

文件 说明
~/.api-switch.yaml API-Switch 配置（提供商、模型路由、安全设置）
~/.api-switch/.key API Key 加密密钥（自动生成，权限 0600）
~/.claude/settings.json Claude Code 配置（由 api-switch use 管理）
~/.api-switch/usage.json 用量统计数据
~/.api-switch/update-state.json 自动更新状态（上次检查时间）

服务器配置

server:
  port: 8080           # 代理端口
  auth_token: ""       # API 认证 Token（可选，设置后需 Bearer 认证）
  rate_limit: 100      # 每分钟每 IP 请求数限制（0 = 禁用）
  tls_cert: ""         # TLS 证书路径（可选）
  tls_key: ""          # TLS 密钥路径（可选）

安全功能

功能 配置 说明
API Key 加密 自动 使用 AES-256-GCM 加密存储，向后兼容明文配置
Bearer 认证 server.auth_token 设置后所有 API 请求需携带 Authorization: Bearer <token>
速率限制 server.rate_limit 每分钟每 IP 请求数限制，防止滥用
TLS/HTTPS server.tls_cert, server.tls_key 启用 HTTPS 加密传输
更新验证 自动 SHA256 校验和验证，防止供应链攻击
管理端点保护 自动 仅 localhost 可访问，检查代理头防止绕过

两种提供商类型

类型 说明
anthropic 直连 Anthropic API，无协议转换
openai 走 OpenAI 兼容协议，请求/响应自动双向转换

协议转换支持

特性 支持 说明
Text 消息 ✅ 双向转换
流式 SSE ✅ OpenAI ↔ Anthropic SSE
工具调用 ✅ tools / tool_choice / tool_use / tool_result
流式工具调用 ✅ input_json_delta streaming
多模态图片 ✅ Anthropic image block → OpenAI image_url（支持 base64 和 URL）
System 消息 ✅ 自动置顶

🩺 常见问题

如何验证代理是否正常工作？

# 一键测试（推荐）
api-switch test deepseek-chat

# 健康检查
curl http://localhost:8080/health

# 完整诊断
api-switch doctor

修改配置后需要重启吗？

不需要。API-Switch 会自动监听 ~/.api-switch.yaml 的文件变更，500ms 防抖后自动重载。也可以手动触发：

curl -X POST http://localhost:8080/admin/reload

如何查看实时流量？

# Web 仪表盘
api-switch monitor --web

# 终端实时日志
api-switch monitor

切换模型后需要重启 Claude Code 吗？

不需要。Claude Code 热加载 ~/.claude/settings.json，api-switch use 切换后立即生效。

如何更新到最新版？

# 自动更新（推荐）
api-switch update

# 或手动
npm install -g api-switch-cc@latest

如何修改端口？

# 方案一：配置文件
api-switch config set server.port 9090

# 方案二：运行时指定（推荐）
api-switch serve -p 9090
api-switch use gpt-4o    # 自动使用配置中的端口

如何更新 API Key？

api-switch config set providers.openai.api_key sk-new-key

配置热加载不生效？

确保文件是保存到原路径而非临时文件。大部分编辑器（vim/nano）直接保存可以触发。如果使用 VS Code Remote，可能需要手动触发：

curl -X POST http://localhost:8080/admin/reload

自动更新如何工作？

api-switch serve 启动时在后台检查 Gitee/GitHub Release API，24 小时内最多检查一次。发现新版本后自动下载对应平台的二进制（优先 Gitee 版本化镜像 release/vX.Y.Z/）、替换当前文件、无缝重启。api-switch update 可手动触发更新。可用 --no-auto-update 禁用。

更新优先级： Gitee 镜像 → GitHub Release → npm 更新 → go install

维护者：如何发布新版本？

# 1. 更新 CHANGELOG.md
# 2. 试运行检查前置条件
./release.sh v0.9.3 --dry-run

# 3. 正式发布
export GITEE_TOKEN=<gitee_access_token>
export NPM_TOKEN=<npm_publish_token>
./release.sh v0.9.3

发布脚本会自动完成：版本号更新 → 二进制编译校验 → SHA256 生成 → Git tag + push → Gitee release 页创建 → 二进制上传 → npm 发布 → 验证。

📁 项目结构

├── release.sh            # 自动化发布脚本 (6阶段)
├── bump.sh               # release.sh 兼容包装
cmd/api-switch/
├── main.go              # CLI 入口和命令注册
├── serve.go             # serve / daemon 命令
├── provider.go          # provider / model 管理
├── use.go               # use / setup / test 命令
├── config_cmd.go        # config 管理命令
├── update.go            # 自动更新命令
├── doctor.go            # 一键诊断命令
└── monitor.go           # 实时监控命令
internal/
├── config/
│   ├── config.go                   # 配置类型、加载、保存、路由
│   ├── config_test.go              # 配置单元测试
│   ├── claude_config.go            # Claude Code 配置管理
│   └── doctor.go                   # 一键诊断
├── daemon/
│   ├── daemon.go                   # 后台进程管理
│   ├── daemon_test.go              # daemon 单元测试
│   ├── daemon_unix.go              # Unix 进程属性
│   └── daemon_windows.go           # Windows 进程属性
├── logutil/
│   ├── logger.go                   # 分级日志
│   └── logger_test.go              # 日志单元测试
├── monitor/
│   ├── tracker.go                  # 请求事件追踪
│   └── tracker_test.go             # 追踪器单元测试
├── provider/
│   ├── anthropic.go                # Anthropic API 客户端
│   ├── openai.go                   # OpenAI API 客户端
│   └── openai_test.go              # 客户端单元测试
├── proxy/
│   ├── handler.go                  # HTTP 代理 + 请求处理 + 认证中间件
│   ├── admin.go                    # 管理端点（仪表盘、SSE、监控）
│   ├── converter.go                # Anthropic ↔ OpenAI 请求转换
│   ├── converter_test.go           # 转换器单元测试
│   ├── response.go                 # OpenAI → Anthropic 响应转换
│   ├── ratelimit.go                # 请求速率限制中间件
│   └── router.go                   # 模型路由
├── secrets/
│   ├── encrypt.go                  # API Key AES-256-GCM 加密
│   └── encrypt_test.go             # 加密单元测试
├── streaming/
│   ├── sse.go                      # SSE 流式转换
│   └── sse_test.go                 # SSE 转换单元测试
├── update/
│   ├── updater.go                  # 自动更新 + SHA256 校验
│   ├── updater_test.go             # 更新功能单元测试
│   ├── exec_unix.go                # Unix 进程重启
│   └── exec_windows.go             # Windows 进程重启
└── usage/
    ├── tracker.go                  # Token 用量追踪
    └── tracker_test.go             # 用量追踪单元测试
pkg/
├── anthropic/types.go              # Anthropic 类型定义
└── openai/types.go                 # OpenAI 类型定义

Stats

Dependencies
6
Dependent packages
0
Dependent repositories
0
Total releases
22
Latest release
First release
Stars
2
Forks
0
Watchers
0
Contributors
1
Repository size
5.59 MB
SourceRank
6

Releases

v1.0.1-0.20260725141841-788d7e87fcf5
v1.0.0
v0.9.3
v0.9.3-0.20260714095547-5df435a59cf9
v0.9.1
v0.9.1-0.20260706035709-2c62e2bba27f
v0.9.0
v0.8.0
v0.5.1-0.20260622090436-1c80e5e3cd5b
v0.5.0
See all 22 releases

Contributors

卓越之星


See all contributors

Login to resync this project