docs: finalize sub2api post-task routing notes

This commit is contained in:
Codex
2026-06-09 08:44:50 +00:00
parent a39402f766
commit 8decc7d187
6 changed files with 23 additions and 9 deletions
+2
View File
@@ -107,6 +107,8 @@ HWLAB 与 AgentRun 协同修复必须按 `docs/reference/agentrun.md` 的职责
HWLAB v0.2 provider profile 必须通过已部署的 HWLAB Cloud API/CLI 管理,正式入口是 `hwlab-cli client provider-profiles`。不要把手工 patch `agentrun-v01` Secret、直接调用 AgentRun manager 或临时 runner job 当作正式配置路径或关闭证据;这些只可作为基础设施定位证据。标准执行面是 `G14:/root/hwlab-v02`,调用前锁定 `HWLAB_RUNTIME_NAMESPACE=hwlab-v02``HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666``HWLAB_RUNTIME_ENDPOINT_LOCKED=1``HWLAB_API_KEY``/root/.config/hwlab-v02/master-server-admin-api-key.env` 加载。
当明确需要把当前 operator 的 Codex 凭据作为 AgentRun 动态 profile 提供给 HWLAB Code Agent 或 CaseRun 使用时,固定操作手册在 `$hwlab-code-agent``AgentRun 动态 sub2api profile` 小节。该场景是 AgentRun runtime profile 投影,不替代上面的 HWLAB provider-profiles 正式配置路径;默认 profile 名为 `sub2api`、模型为 `gpt-5.5`,优先使用 G14 k3s 内 Sub2API ClusterIP 作为 `base_url`,并只记录 SecretRef、keyPresence、hash suffix 和原入口验收结果。
`config.toml` 和 Codex `auth.json` 是两个独立输入。`set-config <profile> --config-stdin` 写入 profile 的 Codex 配置文本;`set-auth-json <profile> --auth-json-stdin` 写入完整 Codex auth JSON object,并在 AgentRun runtime Secret 中作为 `auth.json` key 保留。`set-key --key-stdin` 只用于单值 API key profile;当输入本来就是 Codex `auth.json` 时,不得再把它压扁、拆成单个 key、改走 legacy API-key-only 路径或保留旧断言阻塞提交。遇到 CLI 不支持完整 auth JSON、输出不可见或缺少 hash/keyPresence 等证据时,先补 HWLAB CLI/API 和 AgentRun provider-profile 能力,再继续试机。
标准命令形态如下,文件名可按实际 profile 替换:
+3 -1
View File
@@ -27,7 +27,7 @@
- `pool.apiKeySecretName` and `pool.apiKeySecretKey` name the k3s Secret that stores the single consumer API key.
- `pool.defaultTempUnschedulable` declares Sub2API account-level temporary unschedulable rules. Keep 429/overload/capacity failures in this YAML policy so the scheduler can cool down a failing account and choose another candidate instead of hard-pinning one provider.
- `profiles.entries` selects local Codex profile files from `~/.codex/` and maps them to Sub2API account names.
- `profiles.entries[].capacity` optionally overrides `pool.defaultAccountCapacity` for one account. Capacity is a YAML-controlled routing input; HY is intentionally declared as `capacity: 20` in this file, and code constants, Secrets, ad-hoc runtime patches, or stale tests must not override that source of truth.
- `profiles.entries[].capacity` optionally overrides `pool.defaultAccountCapacity` for one account. Capacity is a YAML-controlled routing input; omit it unless that account needs a deliberate per-account concurrency override. Code constants, Secrets, ad-hoc runtime patches, or stale tests must not override YAML source of truth.
- `profiles.entries[].tempUnschedulable` may override the pool default for one account. The CLI renders it into Sub2API credentials as `temp_unschedulable_enabled` and `temp_unschedulable_rules`; rules match HTTP status plus response-body keywords and place only that account into a temporary unschedulable cooldown.
- `profiles.entries[].openaiResponsesWebSocketsV2Mode` is the account-level Responses WebSocket v2 switch for OpenAI-compatible upstreams that require WebSocket transport. Allowed values are `off`, `ctx_pool`, and `passthrough`; omit the field unless that upstream needs it.
- `profiles.entries[].upstreamUserAgent` is an optional account-level upstream request User-Agent override. Use it only for upstreams that require a Codex CLI compatible User-Agent; keep the value YAML-controlled and newline-free.
@@ -36,6 +36,8 @@
Enable account-level WebSocket v2 only for upstream profiles that have passed a direct Codex WSv2 probe. Treat this as a YAML-declared capability set, not a hard scheduling pin to one profile; `codex-pool validate` must show at least one current `webSocketsV2.schedulableEnabled` account, and runtime smoke remains the availability proof. The same validation reports each managed account's runtime WebSocket v2 mode and whether it matches YAML, so stale `ctx_pool` settings cannot silently keep routing Codex WS sessions to an upstream that closes with `no available account`.
Do not encode current availability assumptions as account capacity or tests. HY is a WSv2-capable candidate in the current pool, not a privileged fallback target; if an account needs higher concurrency, that must be a deliberate YAML override backed by fresh runtime evidence and a test that still preserves multi-account scheduling.
Do not enable Sub2API `pool_mode` for UniDesk-managed Codex accounts. `pool_mode` retries the same selected account path, while UniDesk's desired failover behavior is to mark the failing account temporarily unschedulable and let Sub2API choose another account from the group. `codex-pool validate` reports each managed account's temporary-unschedulable runtime alignment and should be used after `codex-pool sync --confirm`.
The request path is: