# AIClient-2-API：统一多模型 AI 代理的终极指南

## TL;DR

AIClient-2-API 是一款基于 Node.js 的轻量级代理服务，支持 Gemini、OpenAI、Claude、Kiro 等多家大模型的统一 OpenAI 兼容接口，具备灵活的配置、丰富的认证方式与完备的日志与健康检查机制，助力开发者轻松切换与扩展模型服务。

## 目录

  1. 为何选择 AIClient-2-API
  2. 核心优势概览
  3. 项目架构与设计模式
  4. 关键功能详解
  5. 安装与快速上手
  6. 高级用法与最佳实践
  7. 参考文献

## 为何选择 AIClient-2-API

在多模型 API 激增的时代，维护不同厂商的接入配置与接口差异，耗时且易出错。AIClient-2-API 通过统一 OpenAI 兼容接口，让您只需一套配置，即可在 Gemini、OpenAI、Claude、Kiro 等多种模型间自由切换，大幅提升开发效率与可维护性。

## 核心优势概览

  • 多模型统一访问：一套 /v1/chat/completions 接口，兼容 Gemini、OpenAI、Claude、Kimi K2、GLM-4.5 等主流大模型。
  • 绕过官方限额：支持 Gemini CLI OAuth 授权，突破官方免费额度限制。
  • 丰富认证方式：Bearer Token、GCP API Key、URL 参数等多种认证方式灵活选用。
  • 可插拔的模块化设计：基于策略模式与适配器模式，轻松添加新服务提供商。
  • 完善的日志与健康检查：请求日志可输出至控制台或文件，内置 /health 接口实时监控服务状态。

## 项目架构与设计模式

  1. src/api-server.js：项目入口，负责解析命令行参数、加载配置并启动 HTTP 服务。
  2. src/adapter.js：适配器层，屏蔽各服务差异，提供统一调用接口。
  3. src/provider-strategies.js：策略工厂，按协议（OpenAI/Gemini/Claude）解析请求与格式化响应。
  4. src/convert.js：核心格式转换模块，实现无损协议转换。
  5. src/common.js：公共工具库，存放常量及辅助函数。
  6. src/{gemini,openai,claude}/：各服务具体实现目录，独立维护调用逻辑与测试用例。

采用适配器模式、策略模式、工厂模式与单例模式，确保代码高内聚、低耦合，并具备卓越的可扩展性。

## 关键功能详解

  • 多认证方式支持：

    • Authorization: Bearer <key>
    • x-goog-api-key / x-api-key
    • URL Query 参数

  • OpenAI 完全兼容接口：

    • /v1/models、/v1/chat/completions
    • Streaming 支持 ("stream": true)

  • 原生 Gemini & Claude 接口：

    • Gemini 原生 /v1beta/…，支持多模态输入
    • Claude 原生 /v1/messages，兼容工具调用

  • 高可配置性：

    • config.json 或命令行参数灵活设定 MODEL_PROVIDER、端口、Host、日志模式等

  • 日志与健康检查：

    • /health 接口返回服务状态与配置信息
    • 可选控制台或文件日志

## 安装与快速上手

  1. 环境准备

    • Node.js ≥ 20.0.0

  2. 安装依赖

    git clone <repo-url>
cd AIClient-2-API
npm install

  3. 撰写 config.json

    {
  "REQUIRED_API_KEY": "your_api_key",
  "SERVER_PORT": 3000,
  "MODEL_PROVIDER": "gemini-cli-oauth",
  "OPENAI_API_KEY": "sk-…",
  "CLAUDE_API_KEY": "sk-…"
}

  4. 启动服务

    node src/api-server.js

  5. 调用示例

    curl http://localhost:3000/v1/chat/completions \
  -H "Authorization: Bearer your_api_key" \
  -d '{"model":"gemini-2.5-flash","messages":[{"role":"user","content":"Hello"}]}'

## 高级用法与最佳实践

  • 动态系统提示：通过 SYSTEM_PROMPT_FILE_PATH + SYSTEM_PROMPT_MODE（override/append）统一管理系统级指令。

  • 请求监控与审计：开启文件日志模式，持续记录 Prompt，助力私有数据集构建与审计合规。

  • 二次开发指南：

    1. 在 src 下新增服务目录，遵循 ApiServiceAdapter 接口；
    2. 在 adapter.js 注册新适配器；
    3. 在 provider-strategies.js 增加解析策略。

## 参考文献

  1. Node.js 官方文档：https://nodejs.org/
  2. GNU GPL v3 许可证：https://www.gnu.org/licenses/gpl-3.0
  3. Google Gemini CLI 项目（启发来源）
  4. Anthropic Claude API 文档