# KeyVia - AI Agent 自动化接入规范与系统文档

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

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

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

---

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

---

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

| 工具名称 | 对应协议 | 建议网关 Base URL | 配置文件路径 |
| :--- | :--- | :--- | :--- |
| **Claude Code** | Anthropic Messages | `https://api.keyvia.cc` | `~/.claude/settings.json` |
| **OpenAI Codex CLI** | OpenAI Responses / Chat | `https://api.keyvia.cc/v1` | `~/.codex/config.toml` |
| **Google Gemini CLI** | Google Gemini 原生 | `https://api.keyvia.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.keyvia.cc`。
   - 前端管理门户（`https://keyvia.cc`）与后端 API 网关（`https://api.keyvia.cc`）分离。
2. **密钥获取方式**:
   - 注册/登录平台后，访问 `https://keyvia.cc/dashboard/keys` 创建或复制 API 密钥。
   - 密钥格式统一以 `sk-` 开头。
3. **计费模式**:
   - Token 计费模型按输入、输出等计费项分别计算；按次或其他模型以各条目标注的单位为准，具体倍率以 [模型广场](https://keyvia.cc/models) 为准。

---

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


## Chatbox

[Chatbox 接入指南](https://keyvia.cc/docs/chatbox)：选择已有的 OpenAI 或 Claude 服务，直接修改 API Host，无需添加自定义提供商。API Host 填 `https://api.keyvia.cc/v1`；API Key 填 KeyVia 密钥，不加 Bearer 前缀。选择该 Key 可用的模型，保留完整模型 ID，不自动覆盖已有模型设置。

Claude 模式的 API Host 请填写 `https://api.keyvia.cc/v1`（`/v1` 很重要，必须保留，否则无法使用）。

若出现 Failed to fetch 或网络错误，先确认 API Host 包含 /v1，再检查网络连接和跨域预检。向客服提供 App 版本、错误信息和请求时间，不要发送 Key。

安全报告：https://keyvia.cc/security
English website: https://keyvia.cc/en