Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ jobs:
sha256: "aff46539a83aff86e3c62c592bce2c50d95391f9df289afaf03a50c01d14533d"
- version: "0.164.0"
sha256: "90dd0b03b28afcb7fa733a4f73b413db2916a47347efd43fb669cc1c774ee8e4"
- version: "0.169.0"
sha256: "9af4d751fce183faedea629437d5252dbf458eeb04130cf4f97be844621ea985"
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
Expand Down Expand Up @@ -83,11 +85,17 @@ jobs:
fi
echo "CLAWROUTER_CODEX_BINARY=$RUNNER_TEMP/codex-$CODEX_VERSION/codex-x86_64-unknown-linux-musl" >> "$GITHUB_ENV"
echo "CLAWROUTER_CODEX_CATALOG_BINARY=$RUNNER_TEMP/codex-$producer_version/codex-x86_64-unknown-linux-musl" >> "$GITHUB_ENV"
if [ "$CODEX_VERSION" = 0.169.0 ]; then
echo "CLAWROUTER_CODEX_REMOTE_BINARY=$RUNNER_TEMP/codex-$CODEX_VERSION/codex-x86_64-unknown-linux-musl" >> "$GITHUB_ENV"
fi
if [ "$CODEX_VERSION" = 0.155.0 ]; then
echo "CLAWROUTER_DESKTOP_FIXTURE_OUTPUT=$RUNNER_TEMP/codex-desktop-fixture" >> "$GITHUB_ENV"
fi
- name: Fetch released Codex connection writer for upgrade proof
if: matrix.version == '0.169.0'
run: git -c maintenance.auto=false -c gc.auto=0 fetch --no-tags --depth=1 origin 608050e4e4dae5ebc93919e0759ffb4bf0664528
- name: Native client through real router and ledgers
run: node --test test/codex-router.test.mjs test/codex-native.test.mjs test/codex-connect.test.mjs
run: node --test test/codex-router.test.mjs test/codex-native.test.mjs test/codex-connect.test.mjs test/codex-remote-upgrade.test.mjs
- name: Synthetic native rehearsal saved-client contract
if: matrix.version == '0.164.0'
run: node --test test/native-rehearsal.test.mjs
Expand Down
4 changes: 2 additions & 2 deletions config/deployment-hold.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"schema": 1,
"hold": false,
"reason": "Large HTTP requires separate infrastructure/secret preparation and a rehearsed compatible recovery version before production rollout."
"hold": true,
"reason": "Remote Codex catalog release is held for isolated native cutover/recovery qualification and separately authorized production activation."
}
62 changes: 62 additions & 0 deletions docs/codex.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,68 @@ or unqualified priority tier fails before installation. Use a producer that
contains the selected model. Default search-enabled CLI setup needs 0.163.0 or
newer; older producers require `--web-search disabled`.

## Remote model metadata

For OpenAI API credentials, opt into current upstream Codex descriptors instead
of the installed CLI's bundled snapshot. Requires a router with
`GET /v1/codex/models` and Codex CLI 0.169.0 or newer:

```sh
pnpm codex:connect connect \
--router-url https://router.example.com \
--provider openai --model gpt-6-sol \
--catalog-mode remote --web-search disabled \
--codex /path/to/codex --dry-run
```

Repeat without `--dry-run` to install. Add `--target desktop` for root settings.
Existing connections retain local mode; remove and reconnect to switch modes.
Remote mode sets the provider's `model_catalog_url` to
`https://router.example.com/v1/codex/models`. Inference still uses
`/v1/native/openai/v1`. It does not set `model_catalog_json`; remove any effective
base, profile, or managed setting for that field before connecting because Codex
prioritizes it over remote discovery. Keep `features.api_key_model_discovery`
enabled (the client default). Managed setup rejects a disabled base/profile flag.
Other configuration layers and command-line overrides must also permit discovery.

The endpoint accepts an issued ClawRouter key and exactly one `client_version`
(`major.minor.patch`). It fetches
`https://chatgpt.com/backend-api/codex/models?client_version=<version>` using the
same credential preparation as native Responses inference. It currently requires
one public OpenAI API account: either the environment lane without a configured
pool, or one API-key grant without environment fallback. Subscription transports,
multi-account pools, and custom upstream origins fail explicitly. No OpenAI
credential is sent to the Codex client.

Full descriptors, instructions, unknown wrapper fields and access-program
metadata are retained. The router exports only registered models with an eligible
native HTTP Responses offer, and narrows advertised service tiers using pricing,
context coverage, and offer permissions. Unknown upstream models are omitted until
the router registers their routing and pricing. This is remote **metadata**
discovery; it does not bypass routing policies or grant upstream Daybreak access.
It does not resolve an upstream `access_program_not_enabled` inference rejection.

The cache is private to one Worker isolate, caller, authorization context, selected
credential revision and client version. Freshness is at most 10 seconds. Transient
upstream errors may use a previously validated response for at most 60 seconds
from acquisition; upstream cache controls, `Age`, and the configured hot-cache
maximum can shorten or disable reuse. Authentication failures, redirects and
invalid metadata invalidate the fallback. Responses sent to clients use
`Cache-Control: no-store`. Upstream response bodies are limited to 8 MiB and
fetch/body reads to 15 seconds; only responses up to 2 MiB are retained, with four
entries per isolate. Larger valid responses can be served without a fallback.

Remote mode uses HTTP/SSE because Codex's WebSocket setting applies to the whole
provider, while a later metadata refresh can introduce an HTTP-only model. Desktop search remains disabled; CLI search
modes use `?standalone_search=true` on the catalog URL, restricting refreshed
metadata to models with qualified native search offers and Lite support. Remote
setup keeps an audit snapshot beside its receipt, without configuring Codex to read
that snapshot. `verify` fetches current metadata and validates the selected model
and connection settings; ordinary metadata changes do not require `update`.
`update` records a new audit snapshot. Neither command makes inference calls.

Contract reference: [OpenAI gateway catalog specification](https://learn.chatgpt.com/docs/enterprise/roll-out-a-gateway#serve-a-catalog-to-clients).

<a id="opt-in-to-built-in-cli-web-search"></a>

## Built-in CLI web search
Expand Down
91 changes: 32 additions & 59 deletions scripts/codex-catalog.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,64 +4,11 @@ import { mkdir, rename, rm, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";
import { pathToFileURL } from "node:url";

// Native export owns prompts, tool contracts, and internal model references.
// The router only chooses reachable slugs and narrows advertised paid tiers.
export function buildCodexCatalog(catalog, bundled, providerId) {
if (catalog.version !== "clawrouter.client-catalog.v1" || catalog.scope?.authType !== "proxy_key" || typeof catalog.scope.credentialId !== "string" || !catalog.scope.credentialId) throw new Error("Codex setup needs a key-scoped operation catalog; update the router and fetch with the issued key");
const provider = catalog.providers?.find((item) => item.id === providerId && item.allowed === true);
if (!provider) throw new Error("selected provider is not authorized");
if (!Array.isArray(provider.offers)) throw new Error("router catalog lacks operation offers; update the router before Codex setup");
if (provider.nativeBaseUrl !== `/v1/native/${providerId}` || !Array.isArray(provider.policies) || provider.policies.length !== 1 || typeof provider.policies[0] !== "string" || !provider.policies[0]) throw new Error("selected provider needs one key-scoped native policy");
const offers = provider.offers.filter((offer) => offer.eligible === true && offer.routeKind === "native" && offer.policyId === provider.policies[0] && typeof offer.policyGeneration === "string" && offer.policyGeneration && ["exact-covered", "request-dependent"].includes(offer.affordability));
const matching = (model, route, transport) => offers.filter((offer) => typeof model.id === "string" && model.id && offer.modelId === model.id && offer.endpoint === route.endpoint && offer.route === `${provider.nativeBaseUrl}${route.path}` && offer.transport === transport);
const responses = provider.routes?.filter((route) => typeof route.endpoint === "string" && route.endpoint && typeof route.path === "string" && route.path.endsWith("/responses") && route.methods?.includes("POST") && route.requestFormat === "openai.responses" && route.responseFormat === "openai.responses" && route.streaming === "sse" && provider.models?.some((model) => model.capabilities?.includes("llm.responses") && matching(model, route, "http").length));
if (responses?.length !== 1) throw new Error("selected provider needs one eligible native HTTP Responses route");
const responseRoute = responses[0];
if (!Array.isArray(bundled.models) || !bundled.models.length) throw new Error("native Codex export contains no models");
const official = new Map(bundled.models.map((model) => [model.slug, model]));
const models = [], skipped = [], mappings = [], standaloneSearchModels = [], slugs = new Set();
let generation, supportsWebsockets = responseRoute.websocket === "openai.responses";
for (const model of provider.models ?? []) {
if (!model.capabilities?.includes("llm.responses")) continue;
const http = matching(model, responseRoute, "http");
if (!http.length) {
skipped.push({ model: model.id, reason: "no eligible native HTTP Responses offer" });
continue;
}
const upstream = model.upstream;
const descriptor = official.get(model.codexModel ?? upstream);
if (typeof upstream !== "string" || !upstream || upstream.includes("${") || !descriptor) {
skipped.push({ model: model.id, reason: "no exact native Codex descriptor" });
continue;
}
generation ??= http[0].policyGeneration;
if (http.some((offer) => offer.policyGeneration !== generation)) throw new Error("native Responses offers disagree on the key policy generation; fetch a fresh catalog");
// Codex enables WS for the entire provider/session, including internal
// models. One route-wide or main-model offer cannot qualify that flag.
supportsWebsockets &&= matching(model, responseRoute, "websocket").some((offer) => offer.policyGeneration === generation);
if (!descriptor.model_messages?.instructions_template && !descriptor.base_instructions) throw new Error(`native descriptor for ${model.id} has no instructions`);
if (slugs.has(upstream)) throw new Error(`duplicate native model route: ${upstream}`);
slugs.add(upstream);
const copy = structuredClone(descriptor);
copy.slug = upstream;
const context = descriptor.max_context_window ?? descriptor.context_window;
const cards = (model.pricing?.serviceTiers ?? []).filter((card) => card.maxInputTokens == null || (typeof context === "number" && card.maxInputTokens >= context));
const tiers = new Set(cards.flatMap((card) => [card.id, ...(card.aliases ?? [])]));
copy.service_tiers = (copy.service_tiers ?? []).filter((tier) => tiers.has(tier.id));
const advertised = new Set(copy.service_tiers.map((tier) => tier.id));
copy.additional_speed_tiers = (copy.additional_speed_tiers ?? []).filter((tier) => advertised.has(tier === "fast" ? "priority" : tier));
if (copy.default_service_tier != null && !advertised.has(copy.default_service_tier)) copy.default_service_tier = null;
const searchRoutes = (provider.routes ?? []).filter(route => route.path === "/v1/alpha/search" && route.methods?.includes("POST") && route.requestFormat === "openai.standalone_search" && route.responseFormat === "openai.standalone_search" && !route.streaming);
if (descriptor.use_responses_lite === true && model.capabilities?.includes("search.web") && searchRoutes.length === 1
&& matching(model, searchRoutes[0], "http").some(offer => offer.policyGeneration === generation)) standaloneSearchModels.push(upstream);
models.push(copy);
mappings.push({ route: model.id, upstream, descriptor: descriptor.slug });
}
if (!models.length) throw new Error("no authorized Responses model has exact native Codex metadata");
return { catalog: { models }, skipped, mappings, supportsWebsockets, standaloneSearchModels, nativeBasePath: `${provider.nativeBaseUrl}${responseRoute.path.slice(0, -"/responses".length)}` };
}
import { buildCodexCatalog } from "../shared/codex-catalog.ts";
export { buildCodexCatalog } from "../shared/codex-catalog.ts";

export async function readCodexCatalog({ routerUrl, providerId, codex = "codex", env = process.env, headers = {} }) {
export async function readCodexCatalog({ routerUrl, providerId, codex = "codex", env = process.env, headers = {}, catalogMode = "local", webSearch = "disabled" }) {
if (!["local", "remote"].includes(catalogMode) || catalogMode === "remote" && providerId !== "openai") throw new Error("remote Codex metadata currently supports only the openai provider");
let origin;
try { origin = new URL(routerUrl); } catch { throw new Error("router URL is invalid"); }
if (origin.username || origin.password || origin.search || origin.hash || origin.pathname !== "/") throw new Error("router URL must be the router origin without credentials, path, or query");
Expand Down Expand Up @@ -91,18 +38,44 @@ export async function readCodexCatalog({ routerUrl, providerId, codex = "codex",
try {
const nativeEnv = { ...env, CLAWROUTER_API_KEY: undefined };
const options = { encoding: "utf8", env: nativeEnv, maxBuffer: 16 * 1024 * 1024, timeout: 30_000, stdio: ["ignore", "pipe", "pipe"] };
bundledBytes = execFileSync(codex, ["debug", "models", "--bundled"], options);
version = execFileSync(codex, ["--version"], options).trim();
if (!/^codex-cli [\w.+-]+$/.test(version)) throw new Error("invalid producer version");
if (catalogMode === "local") bundledBytes = execFileSync(codex, ["debug", "models", "--bundled"], options);
} catch { throw new Error("native Codex bundled export failed; check --codex and producer version"); }
let catalogUrl;
if (catalogMode === "remote") {
const release = /^codex-cli (\d+)\.(\d+)\.(\d+)(?:$|[-+])/.exec(version);
if (!release || Number(release[1]) === 0 && Number(release[2]) < 169) throw new Error("remote catalog setup requires Codex CLI 0.169.0 or newer");
catalogUrl = new URL("/v1/codex/models", origin);
if (webSearch !== "disabled") catalogUrl.searchParams.set("standalone_search", "true");
const fetchUrl = new URL(catalogUrl);
fetchUrl.searchParams.set("client_version", release.slice(1, 4).join("."));
try {
const response = await fetch(fetchUrl, { headers: { ...headers, authorization: `Bearer ${key}` }, redirect: "error", signal: AbortSignal.timeout(30_000) });
if (!response.ok) { void response.body?.cancel(); throw new Error("remote catalog rejected"); }
const chunks = [];
let size = 0;
for await (const chunk of response.body) {
size += chunk.length;
if (size > 8 * 1024 * 1024) throw new Error("remote catalog too large");
chunks.push(chunk);
}
bundledBytes = Buffer.concat(chunks).toString("utf8");
} catch { throw new Error("authorized remote Codex catalog request failed; no files changed"); }
}
let router, bundled;
try { router = JSON.parse(routerBytes); bundled = JSON.parse(bundledBytes); }
catch { throw new Error("router catalog or native export is invalid JSON"); }
const result = buildCodexCatalog(router, bundled, providerId);
// Remote descriptors already use inference slugs. An alias-only policy may
// omit its source descriptor; do not try to apply codexModel a second time.
const projection = catalogMode === "remote" ? { ...router, providers: router.providers.map(provider => provider.id === providerId
? { ...provider, models: provider.models.map(model => ({ ...model, codexModel: model.upstream })) } : provider) } : router;
const result = buildCodexCatalog(projection, bundled, providerId);
const baseUrl = new URL(result.nativeBasePath, origin);
if (baseUrl.origin !== origin.origin) throw new Error("native route must stay on the router origin");
const hash = (text) => createHash("sha256").update(text).digest("hex");
return { ...result, routerUrl: origin.origin, baseUrl: baseUrl.href,
...(catalogUrl ? { catalogMode, catalogUrl: catalogUrl.href } : {}),
producer: version, bundledSha256: hash(bundledBytes), routerCatalogSha256: hash(routerBytes) };
}

Expand Down
Loading
Loading