OpenAI API Proxy
A Checkpoint With Power and Risk
OpenAI API 代理：一个同时拥有控制力与风险的检查点
An OpenAI API proxy sits between clients and the OpenAI API. It can centralize keys and policy, but it also sees sensitive payloads and becomes part of the availability, security and correctness boundary.
OpenAI API 代理位于客户端与 OpenAI API 之间。它能集中管理密钥与策略，但也能看到敏感请求数据，并成为可用性、安全与正确性边界的一部分。
TL;DR
Clients send requests to the proxy, which forwards them upstream and returns the response.
Key isolation, validation, rate limits, logging, policy and bounded retries can live in one place.
The proxy may access prompts, files, tool arguments, outputs, usage and provider credentials.
Document mutations, retention, failure behavior, native IDs and direct rollback.
客户端向代理发送请求，代理转发到上游并返回响应。
密钥隔离、验证、限流、日志、策略与有界重试可集中实现。
代理可能访问提示词、文件、工具参数、输出、用量与供应商凭证。
记录修改、保留、故障行为、原生 ID 与直连回滚。
Proxy, gateway and compatibility endpoint 代理、网关与兼容端点
A transparent proxy may forward the OpenAI contract with minimal change. A compatibility proxy may translate requests to other upstreams. A gateway adds broader identity, policy, quotas, routing, cache and observability. Products can combine these roles, so the important question is what code touches the request and why.
透明代理可能几乎不修改地转发 OpenAI 契约；兼容代理可能把请求转换给其他上游；网关则增加更广泛的身份、策略、配额、路由、缓存与可观测。产品可组合这些角色，因此关键问题是哪些代码为何触碰请求。
The proxy becomes a high-value secret and data boundary. Evaluate who operates it, how credentials are stored, where payloads flow, what is logged, which fields are modified, and what happens when the proxy or upstream fails.
代理成为高价值密钥与数据边界。需评估谁运营、凭证如何存储、请求数据流向哪里、记录什么日志、修改哪些字段，以及代理或上游失败时会发生什么。
Proxy responsibilities and risks 代理职责与风险
| Control 控制 | Best fit 最适合 | Verify before choosing 选择前验证 |
|---|---|---|
| Key isolation 密钥隔离 | Keep provider keys out of clients and scope proxy identities. 让供应商密钥离开客户端，并约束代理身份。 | Secret concentration increases blast radius; use least privilege, rotation and audit. 密钥集中扩大爆炸半径；采用最小权限、轮换与审计。 |
| Validation and policy 验证与策略 | Reject malformed, unauthorized or disallowed requests before upstream execution. 在上游执行前拒绝异常、未授权或禁止请求。 | Define fail-open versus fail-closed behavior and preserve error evidence. 定义 Fail-open 与 Fail-closed 行为，并保留错误证据。 |
| Logging and observability 日志与可观测 | Correlate clients, requests, upstream IDs, latency, usage and failures. 关联客户端、请求、上游 ID、延迟、用量与故障。 | Redact sensitive content, control retention and limit operator access. 脱敏敏感内容、控制保留并限制运维访问。 |
| Retries and limits 重试与限制 | Protect upstream capacity and recover from approved transient failures. 保护上游容量并从批准的瞬态故障恢复。 | Nested retries can amplify load, cost and duplicate tool side effects. 嵌套重试会放大负载、成本与重复工具副作用。 |
| Request transforms 请求转换 | Inject approved defaults, metadata or compatibility mapping. 注入批准的默认值、元数据或兼容映射。 | Hidden mutation can change safety, output, cost and debugging behavior. 隐藏修改会改变安全、输出、成本与调试行为。 |
Evaluate the proxy as a security product 把代理当作安全产品评估
Identify ownership, region, network path, updates, dependencies and support boundary.
Document encryption, logging, redaction, retention, training use and deletion.
Version every header, field, prompt, tool, stream, error and usage transformation.
Test direct or alternate access, credential rotation and proxy-unavailable behavior.
识别所有权、区域、网络路径、更新、依赖与支持边界。
记录加密、日志、脱敏、保留、训练使用与删除。
版本化每个 Header、字段、提示词、工具、流、错误与用量转换。
测试直连或备用访问、凭证轮换与代理不可用行为。
Threat-model and failure-test the proxy 为代理做威胁建模与故障测试
- Map trust boundaries, payload classes, credentials and every storage location.
- Diff proxied and direct requests, streams, errors, usage and native IDs.
- Inject proxy timeout, restart, partial stream, upstream 429 and credential failure.
- Verify retries cannot duplicate non-idempotent tool or external actions.
- Exercise emergency bypass, key rotation and incident evidence export.
- 映射信任边界、请求数据类别、凭证与每个存储位置。
- 对比代理与直连的请求、流、错误、用量与原生 ID。
- 注入代理超时、重启、部分流、上游 429 与凭证故障。
- 验证重试不能重复非幂等工具或外部动作。
- 演练紧急旁路、密钥轮换与事故证据导出。
Make the checkpoint explicit 显式表达检查点
Clients authenticate to the proxy with scoped identities. The proxy authorizes the workload, validates the OpenAI-shaped request, applies versioned and observable transforms, enforces budgets and forwards with a protected upstream credential. The response retains native IDs and transformation evidence. Direct rollback is isolated and tested.
客户端用受限身份向代理认证；代理授权工作负载、验证 OpenAI 形状请求、应用版本化且可观测的转换、执行预算，并用受保护的上游凭证转发。响应保留原生 ID 与转换证据；直连回滚被隔离并经过测试。
Production rule: a proxy may simplify client access only after its additional trust and failure modes are accepted.
生产规则：只有接受代理新增的信任与故障模式后，才能用它简化客户端访问。
A model proxy is not an external capability catalog 模型代理不是外部能力目录
The proxy governs OpenAI-shaped inference traffic. QVeris complements it by discovering and calling external APIs, tools, services and live data. Keep tool identities and side-effect evidence distinct from the model proxy, then connect both through the parent workflow trace.
代理治理 OpenAI 形状的推理流量；QVeris 补充外部 API、工具、服务与实时数据的发现和调用。让工具身份与副作用证据独立于模型代理，再通过父工作流调用链连接两者。
Keep the proxy policy smaller than the API 让代理 Policy 小于 API 本身
A safe proxy should authenticate the caller, resolve an allowlisted model alias, enforce request limits, attach trace context, and forward to a configured upstream. It should not accept arbitrary upstream URLs, raw provider keys, or unbounded request bodies from clients.
安全代理应认证调用方、解析 Allowlist 中的模型别名、限制请求、附加调用链上下文并转发到已配置 Upstream。它不应接受客户端提供的任意 Upstream URL、原始供应商密钥或无限请求 Body。
POST /v1/chat/completions
authenticate(caller_token)
require(content_length <= 1_000_000)
alias = require_allowlisted(request.model)
policy = load_versioned_policy(caller, alias)
upstream = policy.endpoint # server-side configuration only
key = secret_store.get(policy.key_ref)
trace_id = new_trace_id()
response = forward(upstream, key, request, trace_id, timeout=30s)
log(trace_id, caller, alias, response.model, response.usage, response.status)
return redact_and_normalize(response)
- Strip hop-by-hop headers and never log authorization or full sensitive prompts.
- Define exactly one retry owner and prevent duplicate non-idempotent tool effects.
- Test SSRF, redirect, oversized body, invalid JSON, timeout, and upstream error cases.
- 移除 Hop-by-Hop Header，绝不记录 Authorization 或完整敏感提示词。
- 明确唯一重试负责人，并防止非幂等工具 Effect 重复。
- 测试 SSRF、重定向、超大 Body、无效 JSON、超时与 Upstream Error。
Verified implementation reference: OWASP API Security.
实施参考已根据官方资料核验：OWASP API Security。
Define the Production Contract for an OpenAI API proxy定义OpenAI API 代理的生产契约
For OpenAI API Proxy, protocol similarity lowers integration effort, but it does not guarantee behavioral parity. Put a versioned application contract between product code and the provider path so change remains testable and reversible.
针对“OpenAI API 代理”，协议相似可以降低集成工作量，却不能保证行为等价。应在产品代码与供应商路径之间建立版本化应用契约，让变更保持可测试、可回滚。
Document authentication termination, path and header forwarding, request transformation, streaming, usage, rate limits, logging, data redaction, retries, and provider errors. Mark each item as required, optional, provider-native, or unsupported, and assign an owner for any transformation that changes its meaning.
记录认证终止、路径与请求头转发、请求转换、流式、用量、限流、日志、数据脱敏、重试和供应商错误。把每一项标记为必需、可选、供应商原生或不支持，并为任何改变语义的转换明确负责人。
To validate OpenAI API Proxy, create fixtures for short and long prompts, Unicode, streaming, JSON schema, parallel tools, refusals, cancellation, malformed input, and rate limits. Check required fields and event order instead of accepting one plausible text answer.
验证“OpenAI API 代理”时，为短与长提示词、Unicode、流式、JSON Schema、并行工具、拒绝、取消、畸形输入和限流建立 Fixture，检查必需字段与事件顺序，而不是接受一个看似合理的文本答案。
When operating OpenAI API Proxy, trace internal request ID, resolved model and provider, model version, transformations, retries, latency, token classes, cost source, policy result, and output validation. Redact secrets without deleting the context needed to reproduce failure.
运营“OpenAI API 代理”时，追踪内部请求 ID、解析后的模型与供应商、模型版本、转换、重试、延迟、Token 类别、成本来源、策略结果和输出校验，在脱敏密钥的同时保留复现失败所需上下文。
Before rolling out OpenAI API Proxy, shadow representative traffic, classify semantic differences, canary by reversible workload, monitor task completion and tail behavior, and keep the previous route available until rollback and return-to-primary have been rehearsed.
上线“OpenAI API 代理”前，运行代表性影子流量，分类语义差异，按可逆工作负载进行金丝雀发布，监控任务完成与长尾行为，并在演练回滚和恢复主路径之前保留原有路由。
FAQ
No. It is an intermediary operated by you or a third party, with its own controls and risks.
To isolate keys, centralize policy, apply limits, add evidence or bridge a compatible client contract.
Request mutations, retry behavior, data handling, upstream identity, native IDs and final error causes.
不是。它是由你或第三方运营的中间层，拥有自己的控制与风险。
为了隔离密钥、集中策略、应用限制、增加证据或桥接兼容客户端契约。
请求修改、重试行为、数据处理、上游身份、原生 ID 与最终错误原因。