AQBot
GitHub915
简体中文
下载

API 网关

什么是 API 网关？

AQBot 内置了一个本地 API 网关服务器，可以将你在 AQBot 中配置的 AI 服务商统一暴露为标准 API 接口。其他工具和客户端（如 Claude Code、Codex CLI、Cursor 等）可以通过这个网关访问你的所有模型，无需为每个工具分别配置 API 密钥。

网关支持以下兼容格式：

  • OpenAI 兼容 — /v1/chat/completions
  • Claude 原生 — Anthropic API 格式
  • Gemini 原生 — Google AI API 格式

快速上手

启用网关

  1. 进入 设置 → API 网关
  2. 开启网关开关
  3. 配置监听参数：
    • 端口 — 网关监听的端口号，默认 8080
    • 主机 — 监听地址，默认 127.0.0.1（仅本机访问）

测试连通性

网关启动后，可以用 curl 快速验证：

bash
curl http://127.0.0.1:8080/v1/models \
  -H "Authorization: Bearer your-gateway-api-key"

如果返回了模型列表，说明网关运行正常。

API 密钥管理

网关使用独立的 API 密钥体系来控制访问权限。

生成新密钥

  1. 在 API 网关 页面中找到 密钥管理 区域
  2. 点击 生成密钥
  3. 为密钥添加描述备注（如 "Claude Code 专用"、"团队共享"）
  4. 复制并妥善保存生成的密钥

撤销 / 停用密钥

  • 停用 — 暂时禁用密钥，可随时重新启用
  • 删除 — 永久撤销密钥，使用该密钥的所有客户端将立即失去访问权限

描述备注

为每个密钥添加描述可以帮助你管理多个客户端的访问。例如区分不同工具或团队成员使用的密钥。

SSL/TLS

网关支持 HTTPS 加密通信，部分工具（如 Claude Code）要求使用 HTTPS 连接。

自动自签名证书

启用 SSL 后，AQBot 会自动生成自签名证书，无需手动操作。证书文件存储在：

text
~/.aqbot/ssl/
├── cert.pem    # 自签名证书
└── key.pem     # 私钥（Unix 系统权限 0600）

自定义证书

如果你有自己的 SSL 证书（如 Let's Encrypt 签发的证书），可以在网关设置中指定证书和私钥的路径。

配置选项

选项 说明
启用 SSL 是否开启 HTTPS
SSL 端口 HTTPS 监听端口
证书路径 cert.pem 文件路径
私钥路径 key.pem 文件路径
强制 SSL 是否将所有 HTTP 请求重定向到 HTTPS

用量统计

网关提供详细的用量统计面板，帮助你了解 API 的使用情况。

请求量面板

实时显示网关处理的请求总量、成功率和错误率。

Token 用量

按不同维度查看 Token 消耗：

  • 按密钥 — 每个 API 密钥使用了多少 Token
  • 按服务商 — 每个后端服务商处理了多少请求和 Token
  • 按日期 — 每日的 Token 使用趋势

请求日志

网关记录所有经过它的 API 请求，方便调试和审计。

每条日志包含以下信息：

字段 说明
时间 请求的时间戳
方法 HTTP 方法（GET、POST 等）
路径 请求路径
模型 请求使用的模型
服务商 转发到的后端服务商
状态码 HTTP 响应状态码
Token 输入/输出 Token 数量
延迟 请求处理耗时

支持按时间范围、状态码、模型等条件过滤日志。

自动模型路由

当多个服务商配置了相同的模型 ID（例如两家中转都提供 gpt-5.5），或在不同服务商上设置了相同的别名时，网关可以把该名称对外呈现为一个模型。

  1. 打开 API 网关 → 设置。
  2. 开启 自动模型路由。

开启后：

  • /v1/models 对共享名称只展示一条裸 id（owned_by: aqbot），同时仍保留 服务商/名称 以便钉死上游。
  • 使用裸 id 或共享别名请求时，按服务商排序选择上游，并跳过近期失败的源（限流、5xx、超时）。
  • 可重试错误的故障转移发生在流式响应开始写出之前。

关闭时（默认）保持现有冲突展示规则，且不做多源自动切换。

随时可使用 服务商公共ID/模型或别名 强制指定单一上游。

模型别名

在 设置 → 服务商 → 模型设置 中，可为模型配置一个或多个别名。网关客户端可用别名作为 model 发起请求，AQBot 会将上游请求改写为真实 model_id。多个服务商配置相同别名时，可配合自动模型路由做多源切换。

别名主要用于网关；应用内对话仍使用真实模型 ID。

配置模板

AQBot 内置了常见开发工具的配置模板，帮助你快速接入。以下是一些常用工具的配置方式：

Claude Code CLI

bash
export ANTHROPIC_BASE_URL=https://127.0.0.1:8443
export ANTHROPIC_API_KEY=your-gateway-api-key
export NODE_TLS_REJECT_UNAUTHORIZED=0
claude

OpenAI Codex CLI

bash
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
export OPENAI_API_KEY=your-gateway-api-key
codex

OpenCode

bash
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
export OPENAI_API_KEY=your-gateway-api-key
opencode

Gemini CLI

bash
export GEMINI_API_KEY=your-gateway-api-key
export GEMINI_BASE_URL=http://127.0.0.1:8080
gemini

自定义客户端

对于任何支持 OpenAI 兼容 API 的客户端，使用以下配置：

  • Base URL: http://127.0.0.1:8080/v1
  • API Key: 你的网关 API 密钥
  • 模型: 通过 /v1/models 接口查询可用模型

接入外部工具

除 CLI 工具外，许多图形化工具也支持自定义 API 端点。通用配置方式：

  1. 在工具的设置中找到 API 配置或自定义端点选项
  2. 将 Base URL 设置为 AQBot 网关地址
  3. 将 API Key 设置为网关密钥
  4. 保存后即可使用 AQBot 配置的所有模型