# EasyApi (Sub2API) - AI Agent 自动化接入规范与系统文档

EasyApi 提供与 Anthropic、OpenAI 与 Gemini 兼容的高性能统一接口，支持按量付费和订阅套餐，并提供 API 密钥管理与调用用量记录与查询。

接入仅配置网关地址、协议和 API Key；不指定默认模型，不新增或覆盖客户端已有的模型设置。

> **站点名称**: EasyApi (Sub2API 统一中转网关)
> **官方门户主页**: https://easyapi.cc
> **控制台与密钥管理**: https://easyapi.cc/dashboard/keys
> **模型广场与用量计费**: https://easyapi.cc/models
> **API 网关基准地址**: `https://api.easyapi.cc` (OpenAI 协议追加 `/v1`，Anthropic 与 Gemini 协议直连根地址)

---

## 平台简介 (About EasyApi)
EasyApi（底层由 Sub2API 核心驱动）是专为主流 AI 编程工具与开发者打造的高性能、高可用 API 中转网关。
平台将主流大模型官方订阅与商业接口统一转化为标准化 API 端点，支持国内低延迟直连，提供透明真实的 Token 用量计费、周期额度与分组配额管理。

---

## 适配的三大核心 AI 编程工具与网关地址

| 工具名称 | 对应协议 | 建议网关 Base URL | 配置文件路径 |
| :--- | :--- | :--- | :--- |
| **Claude Code** | Anthropic Messages | `https://api.easyapi.cc` | `~/.claude/settings.json` |
| **OpenAI Codex CLI** | OpenAI Responses / Chat | `https://api.easyapi.cc/v1` | `~/.codex/config.toml` |
| **Google Gemini CLI** | Google Gemini 原生 | `https://api.easyapi.cc` | `~/.gemini/.env` |

---

## 详细规范子文档 (Sub-documents)
- [Claude Code 配置规范](/docs/ai/claude-code.md): Anthropic Messages 协议与 `settings.json` 增量合并说明
- [Codex CLI 配置规范](/docs/ai/codex.md): OpenAI Responses 协议与 `config.toml` 配置说明
- [Gemini CLI 配置规范](/docs/ai/gemini-cli.md): Google Gemini 原生协议与环境变量配置说明
- [常见状态码与排错指南](/docs/ai/troubleshooting.md): 401/403/429/529 状态码排查与自愈自查树
- [全量单页规范 (Full Edition)](/llms-full.txt): 一站式单页文档，适合 Agent 单次快速上下文加载

---

## 核心参数与计费规则
1. **真实网关地址**:
   - 生产环境统一网关域名为 `https://api.easyapi.cc`。
   - 前端管理门户（`https://easyapi.cc`）与后端 API 网关（`https://api.easyapi.cc`）分离。
2. **密钥获取方式**:
   - 注册/登录平台后，访问 `https://easyapi.cc/dashboard/keys` 创建或复制 API 密钥。
   - 密钥格式统一以 `sk-` 开头。
3. **计费模式**:
   - 所有模型均采用真实 Token 计费，输入与输出 Token 分开计算，具体倍率以 [模型广场](https://easyapi.cc/models) 为准。

---

## AI Agent 自动化配置准则
1. **备份优先**: 在修改任何本地客户端配置文件前，必须先自动生成 `.bak` 备份文件（如 `settings.json.bak`）。
2. **增量合并**: 仅增补或覆盖当前 EasyApi 所需节点，严禁删除或覆盖用户原有的其他 Provider、MCP 服务或已有配置。
3. **密钥安全**: 密钥格式为 `sk-...`；若用户未提供明文 Key，提示词或脚本应保留占位符或提示用户输入，禁止在交互日志中回显完整明文密钥。
4. **服务验证**: 配置完成后引导用户执行快速命令（如 `claude /status` 或运行测试提示），并核对控制台用量记录完成闭环。