# 票据网关 v1.5.0：简单入门

**插件 1.5.0 自动连接可用服务，升级保留原网关地址、安装身份、账号选择和余额，无需手动选择服务地址。** 本版修复大请求在原生路由、拦截和执行阶段的封装问题；业务正文上限仍为 64 MiB，超限时在业务发送前返回明确的 413 `request_too_large`。无需修改 CPA 源码或程序。最低支持版本仍为 1.4.0，受支持的旧客户端可以继续使用，不强制升级。

适用于 **票据网关（网关执行）** 插件，插件 ID 为 `cliproxy-ticket-gateway`。
如果管理员已经装好插件，你只需看第 3 节，把 CPA 地址和业务 API Key 填进客户端。
需要 AI 代为安装或排错时，可交给它首页提供的 [AI 接入文档](/docs/ai-integration.md)。

## 1. 准备与安装

需要：可用的 CPA、票据网关地址、CPA 中的 Codex 账号，以及用于激活的 CDK。
**网关地址由服务提供者告知，没有预填默认值。** 不要把管理密码或 CDK 当作业务 API Key。

根据运行 CPA 的机器或容器选择发布包：

| CPA 系统与架构 | 网关执行版 |
| --- | --- |
| Linux x86_64 / AMD64 | [cliproxy-ticket-gateway-1.5.0-linux-amd64.tar.gz](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/cliproxy-ticket-gateway-1.5.0-linux-amd64.tar.gz) |
| Linux aarch64 / ARM64 | [cliproxy-ticket-gateway-1.5.0-linux-arm64.tar.gz](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/cliproxy-ticket-gateway-1.5.0-linux-arm64.tar.gz) |
| Windows x86_64 / AMD64 | [cliproxy-ticket-gateway-1.5.0-windows-amd64.zip](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/cliproxy-ticket-gateway-1.5.0-windows-amd64.zip) |
| macOS Apple Silicon / ARM64 | [cliproxy-ticket-gateway-1.5.0-darwin-arm64.tar.gz](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/cliproxy-ticket-gateway-1.5.0-darwin-arm64.tar.gz) |
| macOS Intel / AMD64 | [cliproxy-ticket-gateway-1.5.0-darwin-amd64.tar.gz](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/cliproxy-ticket-gateway-1.5.0-darwin-amd64.tar.gz) |

本指南对应 **1.5.0**，下载地址为 [版本发布目录](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/)。选择与 CPA 系统和架构匹配的网关执行版包，按包内说明安装。
下载后先核对 [SHA256SUMS](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/SHA256SUMS)；包内验证记录见 `release-candidate.json`，不要使用来源不明的文件。

Mac 包要求 macOS 13 或更新系统。按 **CPA 进程架构**选择：M 系列原生进程用 ARM64，Intel 或通过 Rosetta 运行的 Intel 进程用 AMD64。Mac 校验值也提供在 [SHA256SUMS.macos](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/SHA256SUMS.macos)，安装细节见 [Mac 安装说明](https://ticket.codingmiao.site/downloads/cliproxy-ticket/1.5.0/MACOS.md)。双架构的构建、ABI、依赖、签名与宿主验收范围以本次发布清单为准；不要沿用旧版本的运行验收结论。
兼容目标为 CPA v8.0.8；Linux glibc 最低版本以本次发布记录为准，不适用于纯 musl 环境。
各平台的编译、原生 ABI、宿主加载和实际业务验证结果以随附清单为准；ARM64 若使用 QEMU 验证，会单独注明。

1. 升级前备份现有插件配置与数据，并核对当前服务支持情况。已有 CPA 就使用原实例；受支持的旧客户端无需强制升级。
2. 解压并校验安装包，把 Linux 的 `cliproxy-ticket-gateway.so`、Windows 的 `cliproxy-ticket-gateway.dll` 或 macOS 的 `cliproxy-ticket-gateway.dylib` **复制为普通文件**到 CPA 插件目录。Mac 可用 `shasum -a 256 -c SHA256SUMS` 校验包内文件。
3. 保持文件名不变，不使用符号链接；确认架构匹配、CPA 能读取文件。
4. 按随包配置示例合并设置，并保留配置、插件和数据目录的持久挂载。
5. 让管理员按现有方式重新加载或重启目标 CPA 服务。不要删除数据卷或重启无关服务。

## 2. 在 CPA 菜单中设置

1. 登录 **CPA 自己的管理页面**，勾选“记住登录”。
2. 打开 **票据网关（网关执行）**，确认显示 v1.5.0；无需再输入一遍插件管理密钥。
3. 手动填写服务提供者给出的票据网关 HTTPS 源地址。
   不要在后面加 `/v1` 或内部接口路径。
4. 首次按页面提示生成安装身份，填写可持久保存的插件数据目录，然后保存。
5. 在账号列表中勾选可用 Codex 账号，填写要使用的**原始模型名**，选择个人模式或中转模式，保存并同步。默认是个人模式。
6. 点击激活或充值，输入管理员授权使用的 CDK。兑换结果不确定时，保留原操作再核对，别重复兑换。

页面显示可用余额、累计充值、已消费、预留金额和生效倍率。按 token 时，客户端独立倍率覆盖全局默认，留空时继承；请求按受理时倍率结算，并发成功可能使余额短暂为负。按次时使用受理时固定单价，不叠乘倍率，并预留一笔足够支付的费用。管理员可限定支持的业务模型，该限制不影响打票、采集和预热。

安装身份、密钥和数据目录在升级后都要保留，否则原授权可能无法识别。
服务端业务请求沿用账号代理或全局代理，不使用 UUID 代理。未配置代理时由服务器直连；配置的代理无法连接且业务尚未发送时，自动尝试服务器直连。服务器直连是最后兜底，仍失败时直接返回错误，不转到 CPA 本机执行。可能已发送或结果未知的业务不会自动重发。
服务连接暂时不可用时，插件会自动恢复后续请求的连接，期间可能需要等待重新准备。无需清空数据目录、更换安装身份或再次激活；已经发出或结果未知的请求不会自动重放。
账号自动刷新期间保留正确绑定；同步未确认时先恢复同步，取消请求不再等待其他同步完成。
v1.5.0 保留了相同有效配置重载不重复释放的修复。账号、网关等执行配置改变或已暂停后的恢复仍需确认旧租约释放；单独修改 N/M 或计费方式会原地更新策略，失败会保留安全错误码；不要通过清空数据目录、重建身份或再次充值处理。
账号代理优先于全局代理，显式 none/direct 表示服务器直连。代理地址应从执行服务器可达；故障代理的直连降级仍受取消和超时限制。插件身份、余额和已选账号继续保留，无需再次激活。

无需单独设置验证模型。
本版会在发送验证前重新检查票据有效期，减少排队后使用过期票据的无效请求。按 token 时按完整成功业务的实际输入、缓存输入与输出 token 结算，缺失用量时等待核对；按次时按确认成功的请求结算固定费用。失败、等待和探测不产生成功请求费用。Codex 上游额度单独统计，取消验证不能保证上游完全不计用量。

## 2.1 轮询与计费选项

评分系统内置并自动运行，无需安装评分插件或手工调权重。个人模式按评分选择初始或替代账号，继续保留健康的当前账号。中转模式可设置“并发账号数 N”：默认 0 表示全部已选账号，此时不显示 M；N>0 时仅 N 个账号持续准备票据，其余自动进入备选。“连续无票冷却 M 分钟”默认 5 分钟；满足条件的账号自动降级，由备选补位，并按内置评分自动安排恢复机会。

N 只限制打票准备，不限制已有请求或丢弃有效票据。健康会话继续使用原账号，调整 N/M 或计费方式保留安装身份、会话与缓存键。实际缓存命中仍取决于模型、提示词前缀和上游。

计费方式默认“按 token”，也可选择“按成功请求”。按次费用由管理员设置，默认每次成功请求 $0.01，页面显示服务端确认的当前价格。按次请求受理时预留该次费用，成功扣除一次，确定失败释放，结果未知继续保留预留；票据准备和失败探测不扣请求费。固定单价不再叠乘 token 倍率。计费方式和价格按请求受理时固定，修改设置不重新定价进行中的请求。

## 3. 在 AI 客户端里使用

| 客户端设置 | 应填写什么 |
| --- | --- |
| API Base URL | **CPA 地址加 `/v1`**，例如 `https://cpa.example.com/v1` |
| API Key | CPA 分配给你的**业务 API Key** |
| 模型 | 插件里已配置且账号支持的原始名称，例如 `gpt-6-astra` |

客户端连接 CPA，不直接连接票据网关。不要添加 `ticket/` 等模型前缀。
已验证的调用方式为 `POST /v1/responses`，请求体示例：

```json
{
  "model": "gpt-6-astra",
  "input": "只回复 OK",
  "stream": true
}
```

请求头使用 `Authorization: Bearer <CPA业务API Key>`，不要提交示例中的尖括号文字。
不使用流式时把 `stream` 改为 `false`。不确定客户端是否支持 Responses 时，请管理员核对。
模型列表可见不代表账号有权限；未配置到插件的模型可能走 CPA 原来的服务。

同一对话应继续使用客户端原有的稳定会话标识；自定义接入可在连续多轮请求中保持相同 `session_id` 请求头或 `prompt_cache_key` 正文字段。不同对话使用不同标识，不要每轮随机生成。中转模式会优先复用仍可服务的原账号；个人模式继续保持单一活跃账号。缓存还取决于实际模型、提示词前缀和上游状态，不保证固定命中率。

## 4. 常见情况

| 情况 | 怎么处理 |
| --- | --- |
| 提示客户端需要升级 | 升级 CPA 实际加载的插件到 1.5.0；保留安装身份、配置与数据目录，无需重新兑换 CDK。 |
| 提示计费协议不兼容 | 联系管理员核对服务端与插件的协议兼容性，保留安装身份和数据目录，不要再次激活。 |
| 没有插件菜单 | 检查文件名、架构、插件启用与持久挂载，再确认 CPA 已重新加载。 |
| 重启时报 `release_unconfirmed` | 确认已加载 v1.5.0，保留原安装身份与 `data_dir`，让管理员查看安全错误码；真实连接或租约冲突仍需处理。 |
| 一直准备中或等待 | 查看该账号下方的具体原因；尚未获得可用票据时，请求会继续等待。持续失败时，向管理员提供安装 ID、发生时间和错误提示。 |
| 服务连接变化后新请求等待 | 插件会自动恢复连接并同步，可能需要重新准备。已经发出或结果未知的请求交由管理员核对，不自动重发。 |
| 票据准备超时（`probe_timeout`） | 票据准备或验证未在时限内完成。稍后刷新；持续出现请联系管理员检查验证记录。这个提示不能单独证明网络断线。 |
| 验证时票据状态变化（`probe_state_replaced`） | 上游返回的票据状态与本次验证使用的状态不一致，票据未通过验证。等待重新准备，持续出现请联系管理员排查。 |
| 票据验证返回 429（`probe_http_429`） | 上游限制了验证请求，请等待冷却。持续出现请核对上游账号的额度与限制；这与网关 CDK 余额分别统计。 |
| 票据验证授权失败或被拒绝（401 / 403） | 401 请检查账号登录状态；403 请联系管理员核对上游拒绝原因，不能仅凭状态码判断账号被封。 |
| 票据验证连接失败、回复无效或路由变化 | 按具体提示等待重新准备；持续出现时，请管理员检查上游连接、代理和验证记录。 |
| 备用显示“不使用” | 个人模式不准备备用票据，这是正常策略。 |
| 提示网关不支持打票策略 | 请服务提供者确认所选策略可用；保留原设置和安装身份。 |
| 代理不可用且直连仍失败 | 让管理员核对服务端连接与服务器出口；不要重复提交结果未知的请求。 |
| 等待时 Codex 上游额度仍变化 | 分别核对上游用量与本地 CDK 账本，并向管理员提供插件版本、发生时间和安全错误码。 |
| 授权失败或额度不足 | 核对安装身份和余额；业务客户端仍使用 CPA API Key。 |
| 模型或请求不支持 | 核对账号权限、原始模型名和客户端 Responses 支持，不直接认定账号被封。 |
| 刚成功但余额没变化 | 业务响应与结算确认可能先后到达。先刷新余额，持续未更新时请管理员核对，勿重复提交已经成功的请求。 |

文档更新：2026-10-10。本指南对应客户端 1.5.0；服务连接由插件自动处理，受支持的 1.4.0 及后续旧客户端继续兼容，无需强制升级。以随附发布清单核对。历史安装包保持原样。

上述具体错误提示包含在 v1.5.0 客户端中。若仍显示“操作暂未完成”，先核对 CPA 实际加载的插件版本，再由管理员查询该账号的具体错误码。

## 1.5.0 使用说明

- 默认个人模式和全部账号中转模式现在可以直接点击保存；输入不合法时页面会显示原因。
- 暂时不可用的账号由插件后台持续检查。冷却结束或原生 CPA 刷新凭据后会自动尝试恢复；已确认授权永久失效的凭据会自动排除。原生账号文件会保留，重新授权后可恢复。
- 用户主动停用的原生账号不会被插件擅自启用。页面只有在确实需要重新授权、启用或修改配置时才提示对应操作。
- 使用 `/v1/responses` 或 `/v1/chat/completions`，流式与非流式均走同一票据网关；工具结果请求应携带完整调用历史。
- Chat 流式请求需要最终用量时设置 `stream_options.include_usage: true`。中断或失败可能没有最终用量；空 Token 或 `$0` 不能单独视为成功，应查看错误详情。
- 等待期间的心跳只表示连接保持。后续错误仍会结束请求，已经发送的业务不会自动重放。

### Chat Completions 支持范围

支持完整文本消息历史、function tools 与工具结果、流式/非流式、reasoning_effort 和 service_tier。需要流式最终用量时传入 `stream_options.include_usage: true`。

本版每次请求只生成一个 choice。`n > 1`、旧版 functions/function_call、无法保留语义的采样或输出上限参数会在发送前返回明确错误；请按错误信息删除不受支持的参数。不要把这些参数被忽略视为支持。完整参数兼容范围以实际错误及本版发布说明为准。

Chat 参数范围：支持文本、用户图片 URL、函数工具、`text`/`json_schema` 输出格式以及用量选项；`n>1`、`store:true`、`json_object`、旧式 function_call 和底层 Codex 无法表示的采样/停止/最大 Token 控制会在发送前返回明确 400，不会静默丢弃或改走原生账号。

## 账号与更新

客户端 1.5.0 保留已有账号与更新设置；各项选项按服务支持情况生效：

- 账号优先级数字越小越优先，同一优先级内自动选择表现更好的账号；正在进行的回答不会因调分中断。
- 中转模式可手动填写“并发账号数”，也可选择自动模式。自动模式勾选 1～3 个账号时每次使用 1 个，超过 3 个按账号数量自动计算；例如 30 个账号同时使用 5 个，可轮换 6 轮。
- 账号按“全部、可用、待用、OpenAI 限流、额度用完、需要处理、未启用”分组；待用账号直接显示“正在准备”“暂时不用”或“重试中”。
- 页面自动检查新版本，只有点击“立即更新”后才安装。更新会等待当前请求结束；失败时保留可恢复的原版本。第一次从旧插件升级建议按普通流程更新并重启 CPA 一次，保留原数据目录和安装身份。

### 更新时保留可用账号

从客户端 1.4.3 开始，页面手动更新会等待当前回答完成并交接现有账号连接；只有新版确认接管后才显示“更新成功”。未完成交接时保留失败提示，不通过重新激活或清空数据强行更新。首次从1.4.2或更早版本升级，旧版没有交接能力，仍需按普通升级流程重启一次。