接入 OpenAI 官方 API 并为 Codex 订阅配置同型号回退

servers/tools-pve/litellm/README.md

@@ -1,5 +1,46 @@
 # tools-pve 统一模型代理
 
+## OpenAI 官方 API 与订阅回退（2026-10-29）
+
+官方 API key 由用户生成，经过明确授权，仅加入本 tools-pve 项目的 Arcane 私有
+`OPENAI_API_KEY`。不写入 Git、不复制到 HK、不替换客户端 virtual key 或 OAuth。
+官方上游固定为 `https://api.openai.com/v1`，不能因 LiteLLM provider 同为 openai
+就误归入 ZenMux。未配置 key 时不生成这些路由和 fallback。
+
+| 首选订阅路由 | 官方 API 备用路由 | 当前实际模型 |
+| --- | --- | --- |
+| `codex/gpt-luna-latest` | `openai/gpt-luna-latest` | `gpt-6-luna` |
+| `codex/gpt-sol-latest` | `openai/gpt-sol-latest` | `gpt-6.1-sol` |
+| `codex/gpt-astra-latest` | `openai/gpt-astra-latest` | `gpt-6-astra` |
+| `codex/gpt-6-sol` | `openai/gpt-6-sol` | `gpt-6-sol` |
+| `codex/gpt-5.5` | `openai/gpt-5.5` | `gpt-5.5` |
+
+原不带provider的GPT兼容别名也保留同型号fallback。renderer从chatgpt表生成
+对应的API别名，因此既有latest维护更新后，两侧不会各自残留不同型号。
+`openai/...`显式路由只走官方API，不回到订阅，不改变Grok/Claude/Google/开放模型的主备。
+订阅429、认证或暂时故障可以回退；不自动跨型号降级，失败冷却仍为60秒。
+跨后端不共享prompt cache，也不承诺中途流断线或previous_response_id跨后端续接。
+需要保留完整上下文以便调用方重试，不自动重放已经执行的工具。
+
+API专有补充：`openai/gpt-terra-latest`（目前6.1 Terra）；
+`openai/gpt-transcribe`、`openai/gpt-4o-transcribe`、
+`openai/gpt-4o-mini-transcribe`、`openai/gpt-4o-transcribe-diarize`；
+`openai/text-embedding-3-small`、`openai/text-embedding-3-large`；
+`openai/gpt-4o-mini-tts`；`openai/gpt-image-2.5-flare`、
+`openai/gpt-image-2.5-sunburst`。图像路线可配置不代表做过昂贵出图验收，
+各接口按实际测试结果记录。没有修改现有ASR热词、Hindsight embedding或客户端默认模型。
+Terra与其他API专有模型暂按models.yaml显式维护，不擅自扩张既有Hermes自动维护授权。
+
+现有lan-agents应用key增补这些API路线；Hindsight等受限key只增补其原先已允许的
+GPT路线对应备用模型，不开放图像、语音等无关能力。Claude专用key不变。
+
+赠金需绑定到此key所属API组织，并在该订阅账期末到期，不结转。赠金额度先消耗，
+余额不足后若有已购额度可继续消费；没有任何额度则返回429 credit_balance_exhausted。
+代理不能凭普通project key保证“只花赠金”，不替用户开启充值。这里提供的是
+标准API请求的主备，不把官方赠金解释为可给Codex CLI的API-key模式增加额度。
+依据：[OpenAI赠金说明](https://developers.openai.com/api/docs/guides/chatgpt-api-credits)、
+[LiteLLM回退](https://docs.litellm.ai/docs/proxy/reliability)。
+
 ## 部署状态
 
 2026-10-09：已通过 Arcane 上线，LiteLLM 1.104.2 与 PostgreSQL 均 healthy。