## 使用指南

### 项目简介

AIClient2API 是一个突破客户端限制的 API 代理服务，将 Gemini、Antigravity、Qwen Code、Kiro 等原本仅限客户端内使用的免费大模型，转换为可供任何应用调用的标准 OpenAI 兼容接口。

#### 统一接入

通过标准 OpenAI 兼容协议，一次配置即可接入多种大模型

#### 突破限制

利用 OAuth 授权机制，有效突破免费 API 速率和配额限制

#### 协议转换

支持 OpenAI、Claude、Gemini 三大协议间的智能转换

#### 账号池管理

支持多账号轮询、自动故障转移和配置降级

### 操作流程图

1

#### 配置管理

在「配置管理」页面设置基本参数

- 设置 API Key
- 选择启动时初始化的模型提供商
- 配置高级选项

→
2

#### 生成授权

在「提供商池管理」页面生成 OAuth 授权

方式一：OAuth 授权

- 点击「生成授权」按钮
- 在弹窗中完成 OAuth 登录
- 凭据自动保存

或
方式二：手动上传

- 新增提供商节点
- 上传已有的授权文件
- 手动关联凭据路径

→
3

#### 管理凭据

在「凭据文件管理」页面查看和管理凭据

- 查看已生成的凭据文件
- 自动关联到提供商池
- 删除无效凭据

→
4

#### 开始使用

在「仪表盘」查看路由示例并开始调用 API

- 查看路由调用示例
- 复制 API 端点地址
- 在客户端中配置使用

### 客户端配置指南

以下是常见 AI 客户端的配置方法，将 API 端点设置为本服务地址即可使用：

#### Cherry Studio

1. 打开设置 → 模型服务商
2. 添加自定义服务商
3. 设置 API 地址为: `http://localhost:3000/{provider}/v1`
4. 填入 API Key（配置文件中的 REQUIRED_API_KEY）

#### Cline / Continue

1. 打开 VS Code 设置
2. 搜索 Cline 或 Continue 配置
3. 设置 API Base URL 为: `http://localhost:3000/{provider}/v1`
4. 填入 API Key 和模型名称

#### 通用 cURL 调用

    curl http://localhost:3000/{provider}/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "model": "模型名称",
        "messages": [{"role": "user", "content": "Hello!"}],
        "max_tokens": 1000
      }'

提示：将 {provider} 替换为实际的提供商路径，如 gemini-cli-oauth、claude-kiro-oauth 等。可在仪表盘的路由示例中查看完整路径。

### Ollama 协议使用

本项目支持 Ollama 协议，可以通过统一接口访问所有支持的模型。

#### 列出所有可用模型

    curl http://localhost:3000/ollama/api/tags \
      -H "Authorization: Bearer YOUR_API_KEY"

#### 聊天接口

    curl http://localhost:3000/ollama/api/chat \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -d '{
        "model": "[Claude] claude-sonnet-4.5",
        "messages": [{"role": "user", "content": "你好"}]
      }'

### 常见问题

Q: 请求返回 404 错误怎么办？
A: 检查接口路径是否正确。某些客户端会自动在 Base URL 后追加路径，导致路径重复。请查看控制台中的实际请求 URL，移除多余的路径部分。
Q: 请求返回 429 错误怎么办？
A: 429 表示请求频率过高。建议配置多个账号到提供商池，启用轮询机制；或配置 Fallback 链实现跨类型降级。
Q: OAuth 授权失败怎么办？
A: 确保 OAuth 回调端口可访问（Gemini: 8085, Antigravity: 8086, Kiro: 19876-19880）。Docker 用户需确保已正确映射这些端口。
Q: 流式响应中断怎么办？
A: 检查网络稳定性，增加客户端请求超时时间。如使用代理，确保代理支持长连接。