AI教程

Agent2API 入门教程：把桌面端 AI 登录态接入 OpenAI 兼容网关

本文介绍 Agent2API 的工作方式、桌面端、服务端与 Docker 部署流程，并演示如何添加账号、创建网关 Key、配置 base_url，以及使用 OpenAI 兼容接口调用模型。

AI我搜编辑部2026年10月19日阅读约 9 分钟

Agent2API 入门教程：把桌面端 AI 登录态接入 OpenAI 兼容网关

Agent2API 是什么

Agent2API 是一个本地 AI API 网关，用于整合多家 AI 桌面客户端中已经登录的账号，并通过统一的 OpenAI 兼容接口对外提供模型调用能力。客户端只要支持自定义 base_url，就可以连接到 http://127.0.0.1:3065/v1，通常不需要上游 API Key，也不需要修改客户端。

项目支持 Chat、Responses 和 Messages 三种协议，并提供 /v1/models 模型列表接口。网关运行在本机或你部署的服务器上，账号额度仍来自对应账号本身。

核心功能概览

OpenAI 兼容接口：支持 /v1/chat/completions、/v1/responses、/v1/messages，Messages 还支持 count_tokens。
多提供商：内置多家提供商，包括 WorkBuddy、小浣熊、CatPaw、Qoder、Trae 等，也可以配置自定义提供商。
账号轮转：账号按照优先级排队，遇到 429 时可以切换账号，处于限额冷却期的账号不会继续被使用。
凭证维护：部分提供商支持 Token 自动续期、临期凭证批量刷新和模型目录刷新。
网络与安全：支持为账号设置独立出网代理，并通过多把网关 Key 进行权限分配。
运营管理：提供请求量、成功率、Token 消耗、缓存命中率和长期热力图等报表。
定时任务：可管理自动签到、凭证维护和模型目录刷新任务。

选择部署方式

账号管理页：全局队列、按模型限额冷却、有效期与余额

Agent2API 提供三种形态。桌面端适合个人电脑使用，支持 Windows、macOS 和 Linux，并可托盘常驻；服务端适合没有图形界面的 Windows Server 或 Linux 环境；Docker 适合已有容器环境的用户。三种方式都不要求运行时安装 Node.js。

桌面端：使用安装包启动应用，网关运行在应用进程中。
服务端：安装为系统服务，通过浏览器访问管理面板，并支持开机自启。
Docker：使用 aimodcc/agent2api:latest 镜像，支持 amd64 和 arm64。

安装与首次配置

方式一：桌面端

从项目的 Latest Releases 下载适合系统的安装包。启动后进入“账号”页面，添加一个或多个提供商账号。桌面端网关默认监听本机的 3065 端口。

方式二：Linux 服务端

添加账号：选择提供商与版本，然后走网页登录

tar -xzf agent2api-server-linux-amd64.tar.gz && cd agent2api-server-linux-amd64 && sudo bash install.sh

安装完成后，使用浏览器访问 http://127.0.0.1:3065/。如果服务运行在远程主机上，应将地址中的主机名替换为服务器 IP 或域名。

方式三：Windows Server

Expand-Archive agent2api-server-windows-amd64.zip -DestinationPath C:\agent2api-pkg
cd C:\agent2api-pkg
.\install-service.ps1

请在管理员 PowerShell 中执行上述命令。安装脚本会将服务注册到系统中。

方式四：Docker

模型管理页：按提供商查看模型清单、倍率、上下文与映射

docker run -d --name agent2api --restart unless-stopped -p 3065:3065 -v ./data:/data aimodcc/agent2api:latest

这里的 ./data:/data 用于持久化配置和账号数据。容器启动后，打开 http://127.0.0.1:3065/ 完成初始化。

初始化管理员与网关 Key

打开管理面板并注册管理员账号。
进入“网关 Key”页面，创建一把用于客户端调用的 Key。
进入“账号”页面，选择提供商和版本，然后按照页面流程完成网页登录或导入登录态。
确认账号状态、有效期和余额信息正常。
进入“模型管理”页面检查可用模型和模型映射。

如果没有配置网关 Key，项目默认拒绝 API 请求。请不要把网关 Key 暴露在公开代码、日志或不可信的客户端中。

配置账号与模型

报表概览：统计卡片、Top 账号 / 提供商、模型与提供商用量环形图

在账号管理页面可以查看账号有效期、余额、全局队列和按模型的限额冷却状态。添加多个账号后，系统会根据优先级进行调度；当某个账号触发 429 或进入冷却状态时，可以切换到其他可用账号。

模型管理页面可以按提供商查看模型清单、倍率、上下文信息与映射关系。模型列表支持在线自动拉取的提供商会定期刷新；部分平台也提供内置静态表作为兜底。

第一次 API 调用

在支持自定义 API 地址的客户端中，将 Base URL 设置为：

http://127.0.0.1:3065/v1

API Key 填入刚才创建的网关 Key。例如可以使用 sk-local 作为示例值，但实际调用时应使用面板中生成的 Key。

报表趋势：缓存命中率与 Token 消耗双轴趋势、按天 Token 柱状图

先检查网关健康状态：

curl http://127.0.0.1:3065/health

然后查看模型列表：

curl http://127.0.0.1:3065/v1/models \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

调用 Chat Completions 接口的示例：

curl http://127.0.0.1:3065/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己。"}
    ]
  }'

签到中心页：签到总览与每日签到分组

将 YOUR_GATEWAY_KEY 替换为网关 Key，将 YOUR_MODEL_ID 替换为 /v1/models 返回的模型 ID。Responses 和 Messages 协议也使用同一个网关地址，具体请求字段应遵循对应客户端或协议格式。

多账号、代理与定时任务

多账号轮转

为同一提供商添加多个账号后，可利用全局优先级队列和 429 降级机制提高可用性。建议根据账号额度、有效期和使用场景设置合理的优先级，并定期检查冷却中的账号。

出网代理

项目支持为每个账号配置独立出口。此功能适合需要为不同账号分别管理出站网络的场景，但代理可用性、合规性和账号风控风险仍需要由使用者自行评估。

定时任务

在任务管理页面可以统一管理自动签到、凭证维护和模型目录刷新，并设置任务开关与执行间隔。需要注意，不同提供商支持的能力不同，例如某些平台不支持 Token 续期、签到或余额查询。

查看报表与用量

报表页面可以查看请求数量、成功率、Token 总量、热门模型和账号排名，也可以查看提供商用量分布。趋势页面展示 24 小时缓存命中率、Token 消耗以及按天统计的数据。

如果提供商支持余额或用量查询，还可以在账号页面直接查看相关信息。签到中心则用于查看签到总览和每日签到分组。

开发与构建提示

如果需要从源码构建桌面端，环境要求包括 Rust 1.77 或更高版本、Tauri 2 工具链，以及 Node.js 18.17 或更高版本。Node.js 只用于前端构建和 Tauri 脚本，打包后的桌面端运行时不依赖 Node.js。

npm run tauri:install
npm run tauri:dev
npm run tauri:build
npm run build:icon

其中，tauri:dev 用于开发模式和热重载，tauri:build 用于构建桌面端安装包。macOS 的 DMG 只能在 macOS 上构建，不能从 Windows 交叉编译；正式产物由项目 CI 工作流生成。

凭证安全与使用边界

Agent2API 仅供学习与交流使用。它以非官方客户端形态复用你自己的账号登录态，可能不符合上游服务的使用条款，账号被限流、风控、冻结或封禁等风险由使用者自行承担。

项目会将 accessToken、refreshToken 等账号凭证以明文形式保存在本机配置目录，默认位置为 ~/.agent2api/。导出的文件同样可能包含明文凭证，因此不要将配置提交到公开仓库、上传到网盘或分享给他人。

README 明确禁止将项目用于商业用途、二次分发牟利、批量账号运营、绕过上游计费或配额限制，以及其他违反法律法规的活动。生产或商业场景应使用上游官方渠道和官方 API。使用前请阅读项目的 LICENSE 与使用声明。

结语

Agent2API 将多家桌面客户端账号统一到一个本地 OpenAI 兼容网关中。完成部署、添加账号、创建网关 Key 后，你就可以通过统一的 base_url 接入支持自定义 API 地址的工具；多账号轮转、模型管理、代理、定时任务和报表则适合进一步的本地管理需求。使用时请妥善保护凭证，并严格遵守上游服务条款和项目附加使用声明。