gproxy v4.0.0

GPROXY 4.0.0

The first stable GPROXY 4 release: a shared gateway for CLI, Application and Workers, a unified Console, and automatic migration from v3.

This release brings together the changes since v3.0.22. Review the migration and
compatibility sections before upgrading an existing deployment.

English

Application and Console

• The desktop and mobile Application now uses Tauri and shares the gateway implementation with the CLI and Cloudflare Workers. Its three-step first-run wizard configures the instance, creates the administrator, and optionally imports v4 configuration. Desktop integration includes the system tray and autostart; Android includes background-service controls and system file export.
• Personal pages and administration now live in one Console, with navigation and management scope based on the signed-in user's permissions. CLI and Workers serve it at /console/; the Application manages its instance through in-app IPC, while its HTTP port serves gateway requests.
• The Console has channel-specific provider forms, a provider workspace, resizable navigation, paginated configuration lists, searchable selectors and log filters, grouped user/key lists, and improved mobile and keyboard interaction. Credential actions include bulk import from JSON/JSONL or one API key per line, login links, model tests, and direct health and enablement controls.

Models and routing

• A route's name is now the model name clients request. For example, create a fast route and use model: "fast"; a separate public-model mapping is no longer required. Members select a provider and upstream model, with fallback tiers and weights; the route sets the attempt budget. Route strategies include round-robin, weighted selection, and failover.
• Route session affinity can keep a conversation on the same provider/model, independently of credential affinity within that provider. Credential selection also supports preferring the account whose observed quota resets earliest.
• Model metadata, provider model lists, and prices can be managed in the Console. Live OpenRouter metadata import complements the bundled catalog and preserves existing non-empty custom values. Model listings use callable route/provider names, and provider-prefixed requests stay on the selected provider. Model tests also work with channels that only support streaming HTTP generation.

Protocols and upstream channels

• The conversion layer has been rebuilt around OpenAI Chat, Responses, Claude, and Gemini. It improves tool calls and tool-result replay, reasoning/signature handling, and multi-turn conversations across protocols. Current wire types include OpenAI Responses multi-agent events and Claude Sonnet 5.5 thinking updates; the bundled model catalog has also been refreshed.
• OpenCode Zen and OpenCode Go now have separate channels and quota behavior. Bedrock chooses the API by model: Anthropic models use its native interface, while supported non-Anthropic models use Chat Completions. Vercel AI Gateway, NVIDIA NIM, and Cloudflare AI Gateway retain dedicated adapters.
• Claude refusal fallback extends to Azure, Vertex, and Bedrock. Where the upstream does not provide native fallback, the gateway can retry the configured fallback models on the same credential, recording each actual call separately. This does not retry every HTTP error.
• Claude Code has an optional low-priority mode. Upstream support still depends on the account; exhausting the five-hour window need not remove that credential from rotation in this mode, while weekly limits still apply.

Rewrite rules and outbound connections

• Rewrite rules now use an explicit order within reusable sets, including system text, cache breakpoints, JSON set/delete/merge, regular-expression replacement, and headers. New providers receive a same-name default rule set. The Console retains rule-set navigation, readable rule cards, and client compatibility presets.
• Rules can target request or response bodies and headers, or request query parameters, with operation, model, incoming-header, and stream-event filters. Stream bodies are rewritten as complete events. Model variant behavior is configured through visible rewrite rules instead of the old automatic suffix behavior.
• Request-client profiles and proxies have separate controls at the global, provider, and credential levels. The Console exposes browser presets, custom TLS/HTTP settings, inheritance/direct/proxy choices, and egress checks. Provider operation overrides show channel defaults, can be reset, and support full endpoint URLs with a {model} placeholder. Fingerprint support depends on the selected transport and host.

Credential quotas and account diagnostics

• The Console separates upstream allowance, local credential limits, and user spending budgets. Credential quota views show individual windows, reset times, cycle spend, and usage trends within each cycle, with older observations available on demand.
• Codex reset credits can be inspected and selected individually, including their expiration dates. Claude Code exposes supported weekly/grant reset choices; Antigravity reports its shared model pools and five-hour/weekly windows. Reset availability is determined by the upstream account.
• Quota-query diagnostics expose a copyable, redacted upstream response and feedback details, including failed queries. Local limit resets and upstream allowance resets are presented as separate actions.

Permissions, usage, and billing

• User and API-key permission rules can match model patterns as well as provider and operation, so restricting a user to selected models no longer requires a separate provider. API keys have an independent management-access switch. Credential visibility follows the key's user/organization/team bindings.
• USD spending budgets can be scoped to users, keys, organizations, and teams, with model filters and windows. Pricing and settlement now share the core's calculation, including conditional rates and context/service tiers. Actual costs settle after upstream calls finish; concurrent or in-flight calls can exceed a budget.
• Usage is recorded per physical upstream call, with token/cache breakdowns, media and tool quantities, cost, and attribution stored independently of capture logs. Unreported quantities remain distinguishable from zero. Listing models and other non-usage operations do not create generation usage or consume generation limits.
• Downstream requests, upstream attempts, usage, and administrative audit records have separate views, with configurable capture bodies and history retention. The Console links requests to their upstream attempts and shows usage summaries, grouping, and trends from a shared aggregate query. Audit recording can be switched off independently of usage and request logging.

Updates and integration

• The update page can select and persist GitHub or CNB as the release source, shows download progress, and explains source failures or unavailable v4 channels. Tokenizer vocabulary downloads also show progress and can be managed in the Console.
• The Rust implementation is split into protocol, channel, execution core, storage, SDK, application, and host layers. gproxy-sdk provides an embeddable handle for configuration, credential login, routing, calls, and queries; CLI, Tauri, and Workers use the same application layer. These v4 Rust and management APIs are still changing.

Upgrading from v3

Stop v3, back up the database, master key, and startup configuration, then start
v4 with the same database and key. Supported SQLite, PostgreSQL, MySQL, and D1
databases migrate automatically; PostgreSQL/MySQL require a build with the
corresponding driver.

• Accounts, password hashes, API-key authentication digests, supported provider/routing/pricing/permission configuration, and historical usage are imported. Existing passwords and API keys remain usable. Historical charges are preserved without repricing or settling quotas again.
• SQLite migration keeps a .v3-*.bak database backup and replaces the source only after successful conversion. PostgreSQL, MySQL, and D1 retain old tables under gproxy_v3_* and checkpoint progress so an interrupted migration can resume.
• Review the migration report for skipped configurations and changed semantics before restoring traffic. Old capture logs, request/audit history, and browser sessions are not imported; the history remains in the backup or archived tables, and browser users sign in again.

See Migrating v3 to v4.

Compatibility changes

• Public model names are folded into routes. The old alias/variant configuration and management API payloads are not interchangeable with v4; review client model names, rewritten parameters, and automation.
• Permission evaluation now uses prioritized user/key rules with model matching. Review migrated access rules, credential ownership, and budgets; v3's permission inheritance and budget pre-reservation behavior should not be assumed.
• Edge deployment currently targets Cloudflare Workers only; the v3 Netlify Edge deployment is not carried forward. Workers supports Responses WebSocket, Realtime and channel service sockets. On an empty database, set GPROXY_ADMIN_PASSWORD and optionally GPROXY_ADMIN_USER to create the first administrator.

Downloads

CLI/server packages (gproxy-*) and Application packages (gproxy-tauri-*) are
separate. Choose the matching platform and architecture from the release assets.

Platform	CLI	Application
Linux GNU	ZIP, DEB; x86_64, ARM64, RISC-V 64	ZIP, DEB; x86_64, ARM64, RISC-V 64
Linux musl	ZIP, DEB; x86_64, ARM64, RISC-V 64	—
Windows	ZIP, MSIX; x86_64, ARM64	ZIP, MSIX; x86_64, ARM64
macOS	ZIP, DMG; Intel, Apple Silicon	ZIP, DMG; Intel, Apple Silicon
Android	ZIP, Termux DEB; x86_64, ARM64	Signed APK; x86_64, ARM64
OpenHarmony / HarmonyOS NEXT	Native ZIP; x86_64, ARM64	Experimental unsigned HAP; ARM64

Cloudflare Workers bundles and GNU/musl container images are also provided.
Windows MSIX attachments are unsigned Microsoft Store submission packages; use
the ZIP for a portable installation. macOS apps use ad-hoc signing and are not
notarized. The HarmonyOS HAP requires signing, has not been verified on a physical
device, and has no background service. See
Installation.

简体中文

4.0.0 是 GPROXY 4 的首个稳定版。 本说明整理相对 v3.0.22 的新增与改进。
升级已有实例前，请阅读下方迁移步骤与兼容性变化。

Application 与统一控制台

• 桌面和移动端 Application 改用 Tauri，与 CLI、Cloudflare Workers 共用网关实现。首次启动通过三步向导设置实例、创建管理员，并可选导入 v4 配置。桌面端支持系统托盘和开机自启，Android 提供后台服务控制和系统文件导出。
• 个人页与管理页合并到一个控制台，按当前用户权限显示导航和管理范围。CLI 与 Workers 的入口是 /console/；Application 通过应用内 IPC 管理实例，HTTP 端口用于网关请求。
• 控制台提供按渠道生成的供应商表单、供应商工作区、可拖动宽度的导航、配置列表分页、可搜索的选择器与日志筛选，以及按用户分组的密钥列表，并改进移动端和键盘操作。凭证支持 JSON/JSONL 或每行一把 API Key 的批量导入、登录链接、模型测试，以及直接操作健康状态和启停。

模型与路由

• 路由名称直接作为客户端模型名。例如创建 fast 路由后，请求填写 model: "fast"，无需再建一层公开模型映射。成员配置供应商、上游模型、回退层级和权重，路由设置尝试次数，支持轮询、加权和故障转移策略。
• 路由会话亲和可让同一段对话优先复用供应商与模型，供应商内部的凭证亲和独立配置。凭证选择还支持优先使用观测到的额度重置时间最早的账号。
• 控制台可管理模型元数据、供应商模型目录和价格；除内置目录外，还可在线导入 OpenRouter 元数据，并保留已有的非空自定义值。模型列表使用可调用的路由名或供应商名，供应商前缀请求固定到对应供应商。模型测试兼容只提供 HTTP 流式生成的渠道。

协议与上游渠道

• 重做 OpenAI Chat、Responses、Claude 和 Gemini 之间的转换，改进工具调用与结果回传、思维内容与签名处理，以及跨协议的多轮对话衔接。协议类型已跟进 OpenAI Responses 多智能体事件和 Claude Sonnet 5.5 思维配置，内置模型目录也已更新。
• OpenCode Zen 与 OpenCode Go 拆成独立渠道，分别处理计费和额度。Bedrock 按模型选择接口：Anthropic 模型使用原生接口，支持的非 Anthropic 模型使用 Chat Completions。Vercel AI Gateway、NVIDIA NIM 和 Cloudflare AI Gateway 继续使用专用适配器。
• Claude 拒绝响应的模型回退扩展到 Azure、Vertex 和 Bedrock；上游未提供原生回退时，网关可在同一凭证上尝试配置的后备模型，并分别记录实际调用。这不是对所有 HTTP 错误进行重试。
• Claude Code 增加可选的低优先级模式。是否接受仍由上游账号决定；启用后，五小时窗口用完不必立即将凭证移出轮换，周限额仍然生效。

重写规则与出站连接

• 重写规则统一按规则集内的显式顺序执行，涵盖系统提示词、缓存断点、JSON 设置/删除/合并、正则替换和请求头。新建供应商自动创建同名默认规则集，控制台保留规则集导航、可读规则卡片和客户端兼容预设。
• 规则可处理请求或响应的正文、头部，以及请求查询参数，并按操作、模型、入站请求头和流事件筛选。流式正文按完整事件改写；模型变体的参数行为改为可见的重写规则，不再沿用旧的自动后缀行为。
• 请求客户端配置与代理分别管理，可在全局、供应商、凭证层配置。控制台提供浏览器预设、自定义 TLS/HTTP 参数、继承/直连/代理选择和出口测试。供应商操作覆盖可查看并恢复渠道默认值，完整端点 URL 支持 {model} 占位符；指纹能力取决于传输后端与宿主。

凭证额度与账号诊断

• 控制台区分上游账号额度、凭证本地限额和用户费用预算。凭证额度页展示各个窗口、重置时间、周期内费用和用量趋势，也可继续加载较早的观测记录。
• Codex 重置卡可逐张查看和选择，包含到期时间；Claude Code 展示上游支持的周额度与 grant 重置选项；Antigravity 按共享模型池展示五小时和周窗口。能否重置以上游账号实际返回为准。
• 额度查询可查看并复制脱敏后的上游响应和反馈信息，也覆盖查询失败的情况。本地限额重置与上游额度重置在界面上分别操作。

权限、用量与费用

• 用户和 API Key 的权限规则可同时匹配模型模式、供应商和操作，限制可用模型不再需要专门拆分供应商。API Key 增加独立的管理权限开关，凭证可见范围按密钥绑定的用户、组织和团队确定。
• 用户、密钥、组织和团队可配置按模型、按周期的 USD 费用预算。计价和结算使用核心内同一份计算结果，支持条件费率、上下文阶梯和服务档位。实际费用在上游调用完成后结算，在途与并发请求可能使最终花费超过预算。
• 用量按每次真实上游调用记录，token 与缓存明细、媒体和工具数量、费用及归属独立于抓包保存，未报告的数量与零值区分。列出模型等非用量操作不会生成推理用量，也不会占用生成限额。
• 下游请求、上游尝试、用量和管理审计分别展示，可配置抓包正文与历史保留策略，也可从请求追查关联的上游尝试。用量汇总、分组和趋势图共用一次聚合查询；审计记录开关独立于用量与请求日志。

更新与开发集成

• 更新页可选择并保存 GitHub 或 CNB 发布源，显示下载进度，并说明源访问失败或 v4 渠道暂无版本等情况。分词器词表可在控制台管理，下载也有进度反馈。
• Rust 实现拆分为协议、渠道、执行核心、存储、SDK、应用与宿主层。gproxy-sdk 提供可嵌入的配置、凭证登录、路由、调用和查询接口，CLI、Tauri 与 Workers 共用应用层。v4 的 Rust API 和管理 API 仍在调整中。

从 v3 升级

停止 v3，备份数据库、主密钥与启动配置，再使用原数据库和主密钥启动 v4。
支持的 SQLite、PostgreSQL、MySQL 和 D1 数据库会自动迁移；PostgreSQL/MySQL
需要使用包含对应驱动的构建。

• 导入账户、密码哈希、API Key 认证摘要、支持的供应商/路由/价格/权限配置及历史用量。原密码与 API Key 继续可用，历史费用保留原结算结果，不重新计价或重复结算配额。
• SQLite 成功转换后才替换源库，并保留 .v3-*.bak 备份。PostgreSQL、MySQL 和 D1 将旧表保留为 gproxy_v3_*，记录迁移进度，中断后可继续。
• 恢复流量前检查迁移报告中的跳过项和语义变化。旧抓包、请求/审计历史和浏览器会话不导入；历史记录留在备份或归档表中，浏览器需要重新登录。

详见从 v3 迁移到 v4。

兼容性变化

• 公开模型名合入路由；旧别名/变体配置和管理 API 数据结构不能直接当作 v4 配置使用，需要核对客户端模型名、参数重写和自动化脚本。
• 权限改为按优先级匹配用户/密钥规则，并支持模型筛选。升级后检查权限、凭证归属和预算，不应继续假定 v3 的权限继承与预算预扣行为。
• Edge 当前只提供 Cloudflare Workers，不再沿用 v3 的 Netlify Edge 部署。Workers 支持 Responses WebSocket、Realtime 和渠道 service socket；空数据库通过 GPROXY_ADMIN_PASSWORD 和可选的 GPROXY_ADMIN_USER 创建首个管理员。

下载与安装

CLI/服务器程序（gproxy-*）与 Application（gproxy-tauri-*）分别提供，请从附件选择对应系统和架构。

平台	CLI	Application
Linux GNU	ZIP、DEB；x86_64、ARM64、RISC-V 64	ZIP、DEB；x86_64、ARM64、RISC-V 64
Linux musl	ZIP、DEB；x86_64、ARM64、RISC-V 64	—
Windows	ZIP、MSIX；x86_64、ARM64	ZIP、MSIX；x86_64、ARM64
macOS	ZIP、DMG；Intel、Apple Silicon	ZIP、DMG；Intel、Apple Silicon
Android	ZIP、Termux DEB；x86_64、ARM64	已签名 APK；x86_64、ARM64
OpenHarmony / HarmonyOS NEXT	原生 ZIP；x86_64、ARM64	实验性未签名 HAP；ARM64

同时提供 Cloudflare Workers 包和 GNU/musl 容器镜像。Windows MSIX 附件是未签名的
Microsoft Store 提交包，便携使用可选择 ZIP；macOS 应用使用 ad-hoc 签名，尚未公证；
鸿蒙 HAP 需要签名，尚未真机验证，也不提供后台服务。详见
安装文档。

Built once by GitHub Actions. CLI (gproxy-*) and Application (gproxy-tauri-*) packages are separate.