AQBot

简体中文

English

简体中文

English

外观

API 网关 ​

什么是 API 网关？ ​

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

网关支持以下兼容格式：

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

使用场景

如果你已经在 AQBot 中配置了多个服务商和密钥，API 网关可以让其他开发工具直接复用这些配置，省去重复配置的麻烦。同时，网关提供统一的用量统计和访问控制。

快速上手 ​

启用网关 ​

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

网络安全

如果将主机设置为 0.0.0.0，网关将对所有网络接口开放。请确保你了解其安全风险，并配合 API 密钥和防火墙使用。

测试连通性 ​

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

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

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

API 密钥管理 ​

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

生成新密钥 ​

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

密钥安全

密钥仅在创建时完整显示一次。请立即复制保存，之后只能看到密钥前缀。

撤销 / 停用密钥 ​

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

描述备注 ​

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

程序策略 ​

通过程序策略，你可以对连接到网关的不同程序设置精细的访问控制。

模型白名单 ​

为每个程序指定允许使用的服务商和模型。未在白名单中的模型将被拒绝访问。

默认模型 ​

为程序指定默认的服务商和模型。当客户端请求不指定模型时，使用此默认配置。

速率限制 ​

为每个程序设置每分钟的最大请求次数。超过限制的请求将返回 429 状态码。

配置项说明
程序名称连接程序的标识名称
允许的服务商该程序可以使用哪些服务商
允许的模型该程序可以使用哪些模型
默认服务商/模型未指定时使用的默认值
速率限制每分钟最大请求数

SSL/TLS ​

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

自动自签名证书 ​

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

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

自定义证书 ​

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

配置选项 ​

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

自签名证书信任

使用自签名证书时，客户端可能会报告证书不受信任的警告。大部分 CLI 工具可以通过设置环境变量来跳过证书验证（见下方配置模板）。

用量统计 ​

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

请求量面板 ​

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

Token 用量 ​

按不同维度查看 Token 消耗：

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

TIP

通过用量统计，你可以了解哪个工具消耗最多资源，合理分配 API 配额。

请求日志 ​

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

每条日志包含以下信息：

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

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

配置模板 ​

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

Claude Code CLI ​

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

claude

TIP

NODE_TLS_REJECT_UNAUTHORIZED=0 用于跳过自签名证书验证。如果你使用了受信任的证书，可以移除此设置。

OpenAI Codex CLI ​

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

codex

OpenCode ​

bash
export OPENAI_BASE_URL=http://127.0.0.1:39876/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:39876

gemini

自定义客户端 ​

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

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

接入外部工具 ​

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

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

统一管理的优势

通过 API 网关统一管理，你可以：

  • 在 AQBot 中集中管理所有服务商密钥，其他工具只需一个网关密钥
  • 通过程序策略控制每个工具可以访问的模型
  • 在用量统计中查看所有工具的使用情况
  • 利用多密钥轮询提高可靠性