Operations, development and architecture docs, the reference pages and the component READMEs were rewritten against the code: every documented variable exists, and the settings operators need (runtime image, Git service, listen addresses, Runner targets, single-tenant gateway and provisioner bindings) are documented. Gaps the docs used to present as working are now stated as such: IDE workspaces do not clone the project yet (FR-H2), and in Kubernetes mode dependency installs and image builds have no network path until an egress proxy and builder access exist. The Kubernetes README describes what the provisioner creates, what the Runner needs in a target namespace, and the cluster acceptance that is still outstanding. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.9 KiB
运行级 Codex 模型代理
生产中的执行环境拿到的是代理令牌,而不是租户长期有效的 OpenAI API Key;只有控制面(经 Vault)能解密原始密钥。代理自己构造上游地址:POST 只能到 https://api.openai.com/v1/responses,GET 只能到 https://api.openai.com/v1/models。客户端指定的上游地址、重定向、任意请求头与其他 API 路由一律拒绝。
配置
| 变量 | 说明 |
|---|---|
WF_PROVIDER_PROXY_PUBLIC_URL |
代理的公开基址,以 /provider-proxy/v1 结尾;生产必须是 HTTPS,开发可以是本机 HTTP |
WF_PROVIDER_PROXY_SIGNING_KEY |
独立的签名密钥,至少 32 字符 |
WF_PROVIDER_PROXY_ALLOWED_MODELS |
运维批准的模型 ID,逗号分隔 |
WF_PROVIDER_PROXY_ENABLED=true |
开发模式下启用代理(生产始终启用) |
WF_CODEX_DEFAULT_MODEL |
Agent 配置没有指定模型时使用的默认模型 |
生产中解密原始密钥使用外部 Vault Transit(VAULT_ADDR、VAULT_TOKEN、VAULT_TRANSIT_KEY)。CodeBuddy 在生产中保持禁用,直到有同等的代理协议。
令牌与绑定
executor 通过运行上下文得到 { apiKey: 代理令牌, baseUrl, expiresAt, metering: 'proxy' }。代理令牌有独立的 issuer 与 audience,有效期不超过剩余执行预算且不超过一小时,绑定租户、运行、执行代次、租约 token、worker 身份与凭据连接的确切版本。每个请求都重新校验这些绑定;流式响应期间至少每秒复核一次,发现取消、租约过期、代次更替或凭据撤销时中止上游读取。复核有间隔,不是瞬时断网,已经发出的请求在中止后仍可能产生用量。
/provider-proxy/v1/* 路由不经过普通的 OIDC 或内部服务鉴权,由代理自己验证令牌。凭据带有 metering: proxy,执行器上报的 token 不会再计费一次。
请求与预算
- 每个运行同一时间只允许一个上游请求。发出前在租户事务中先记录请求;请求以「运行、代次、租约、连接、幂等键」为键(没有幂等键时用请求体摘要),同一个键换了请求体会被拒绝。已完成的有界响应可以重放,不再请求上游。
- 支持自包含的文本、本地
function/custom工具以及只包含这两类工具的命名空间;拒绝会话与历史响应引用、存储的提示模板、远程 MCP 与托管工具、后台执行、多模态与文件输入以及未经核实的顶层参数。代理强制store: false、默认服务等级,以及按租户与运行区分的缓存和安全标识。 - 输入预留按序列化后的文本字节加上保守的协议开销估算,
max_output_tokens不超过运行剩余的预留。这是准入估算,不是精确的分词或报价。 - 实际用量只采信上游 JSON 或 Responses SSE 结束事件中的 usage(
input_tokens + output_tokens == total_tokens),每个请求只记账一次。实际用量超出剩余预算时按实际记录,并停止后续执行。 - SSE 帧跨字节与 CRLF 边界解析、限长并在转发与缓存前脱敏;不转发上游的鉴权与错误头,非成功响应体替换为通用错误,避免回显密钥。限制:请求 2 MiB、单帧 1 MiB、响应 16 MiB、重放缓存 2 MiB、单次上游调用 120 秒。
结果未知时
POST 请求超时、流在没有可信用量的情况下结束、或客户端断开时,请求记录变为 unknown:保留它的预留额度,运行进入 ambiguous_execution 等待,之后的请求(包括新租约下的请求)都不会盲目重发。代理进程本身丢失、请求超过 15 分钟仍处于进行中时,后台维护循环同样把它标记为 unknown。
解除方式(需要 owner/admin 在 Web 中操作):
GET /v1/runs/:id/provider-requests查看该运行的模型请求及状态。POST /v1/runs/:id/provider-requests/reconcile,body{"requestId": "...", "usageTokens": 1234}:按服务商后台查到的实际用量结算;不知道实际用量时省略usageTokens,按该请求的预留额度结算。- 结算后运行可以继续,模型请求恢复可用。
请求记录中不保存原始提示词与原始凭据;重放数据属于租户的模型输出,受平台的保留策略约束。
参考:Responses create、streaming Responses。
测试
tests/provider-proxy.test.ts 使用注入的本地假上游,覆盖 audience 隔离、租户/租约/代次/连接绑定、SSE 分块、密钥脱敏、一次性计量、路由/工具/模型拒绝、取消、凭据轮换、预算准入、结果未知与人工对账。WF_CODEX_SDK_INTEGRATION=1 npx vitest run tests/integration/codex-sdk.test.ts 让固定版本的 Codex SDK/CLI 经真实代理访问本地假上游,不会调用真实模型。