Building the web image showed that `next build` failed. - The console imported runtime values from the contracts entry point. - Turbopack cannot follow the NodeNext `.js` imports inside that entry, which also carries zod and every schema into the browser. - Only `next dev` had ever run before, and the console used to import types only. The fix: - The executor catalog moves to an entry without imports, exported as @wishforge/contracts/providers. The console takes its values from there. - providerBaseUrl moves to its own module. - A test keeps value imports of the entry point out of the console. With the console's default budget of 50,000 tokens, every Codex run stopped after one model request: - The proxy reserves one token per request byte, and a Codex request is already about 50 KB. - The executor then reported a bare 429 as a provider failure. The fix: - A request the remaining budget cannot cover now puts the run into the `budget` wait, with what it needs and what remains. - The console defaults to 300,000 tokens and explains the reservation. The run page also marked the stage a successful run ended in as not yet done; it now shows it as complete. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
52 lines
5.7 KiB
Markdown
52 lines
5.7 KiB
Markdown
# 运行级 Codex 模型代理
|
||
|
||
生产中的执行环境拿到的是代理令牌,而不是租户长期有效的 OpenAI API Key;只有控制面(经 Vault)能解密原始密钥。
|
||
|
||
- **上游**:代理自己构造上游地址,POST 只能到 `<上游>/responses`,GET 只能到 `<上游>/models`。上游默认是 `https://api.openai.com/v1`,运维可以用 `WF_OPENAI_BASE_URL` 换成 OpenAI 兼容的模型网关(必须支持 Responses 接口)。
|
||
- **拒绝**:客户端指定的上游地址、重定向、任意请求头与其他 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 配置没有指定模型时使用的默认模型;使用网关时应设为网关提供的模型 |
|
||
| `WF_OPENAI_BASE_URL` | 可选,OpenAI 兼容网关的基址(如 `https://ai-gateway.example/v1`),必须是 HTTPS 且不含凭据;只由运维配置,租户无法指定 |
|
||
|
||
生产中解密原始密钥使用外部 Vault Transit(`VAULT_ADDR`、`VAULT_TOKEN`、`VAULT_TRANSIT_KEY`)。CodeBuddy 与 Claude Code 在生产中保持禁用,直到有同等的代理协议(`providerCatalog` 中的 `proxied`)。
|
||
|
||
## 令牌与绑定
|
||
|
||
executor 通过运行上下文得到 `{ apiKey: 代理令牌, baseUrl, expiresAt, metering: 'proxy' }`。代理令牌有独立的 issuer 与 audience,有效期不超过剩余执行预算且不超过一小时,绑定租户、运行、执行代次、租约 token、worker 身份与凭据连接的确切版本。每个请求都重新校验这些绑定;流式响应期间至少每秒复核一次,发现取消、租约过期、代次更替或凭据撤销时中止上游读取。复核有间隔,不是瞬时断网,已经发出的请求在中止后仍可能产生用量。
|
||
|
||
`/provider-proxy/v1/*` 路由不经过普通的 OIDC 或内部服务鉴权,由代理自己验证令牌。凭据带有 `metering: proxy`,执行器上报的 token 不会再计费一次。
|
||
|
||
## 请求与预算
|
||
|
||
- 每个运行同一时间只允许一个上游请求。发出前在租户事务中先记录请求;请求以「运行、代次、租约、连接、幂等键」为键,同一个键换了请求体会被拒绝。只有 `Idempotency-Key` 头算幂等键:Codex 的 `x-client-request-id` 是它的会话 ID,同一会话的每个请求都一样;没有幂等键时用请求体摘要。已完成的有界响应可以重放,不再请求上游。
|
||
- 支持自包含的文本、本地 `function`/`custom` 工具以及只包含这两类工具的命名空间;拒绝会话与历史响应引用、存储的提示模板、远程 MCP 与托管工具、后台执行、多模态与文件输入以及未经核实的顶层参数。代理强制 `store: false`、默认服务等级,以及按租户与运行区分的缓存和安全标识。
|
||
- 输入预留按序列化后的文本字节加上保守的协议开销估算(一个字节记一个 token),`max_output_tokens` 不超过运行剩余的预留。这是准入估算,不是精确的分词或报价。Codex 一次请求带着指令与工具定义,约 5 万字节并逐轮增长,所以运行预算要留出这部分余量。剩余预算不够下一次请求的预留时,代理拒绝该请求,并让运行进入 `budget` 等待,写明需要与剩余的数量。
|
||
- 实际用量只采信上游 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 中操作):
|
||
|
||
1. `GET /v1/runs/:id/provider-requests` 查看该运行的模型请求及状态。
|
||
2. `POST /v1/runs/:id/provider-requests/reconcile`,body `{"requestId": "...", "usageTokens": 1234}`:按服务商后台查到的实际用量结算;不知道实际用量时省略 `usageTokens`,按该请求的预留额度结算。
|
||
3. 结算后运行可以继续,模型请求恢复可用。
|
||
|
||
请求记录中不保存原始提示词与原始凭据;重放数据属于租户的模型输出,受平台的保留策略约束。
|
||
|
||
参考:[Responses create](https://developers.openai.com/api/reference/resources/responses/methods/create)、[streaming Responses](https://developers.openai.com/api/docs/guides/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 经真实代理访问本地假上游,不会调用真实模型。
|