You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 6671d78
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs-site/src/content/docs/guides/providers.md
+37-4Lines changed: 37 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -121,8 +121,27 @@ labels local presets separately; those normally omit both `authMode` and `apiKey
121
121
The [`retryOn429`](/reference/configuration/) same-key 429 replay applies only to API-key
122
122
providers (`authMode: "key"`). OAuth, forward, and local presets are excluded — their
123
123
credentials must never be replayed on the same token, and local runtimes have no remote key to
124
-
preserve. It is opt-in: when the option is absent the feature is off; object presence enables
125
-
it unless `enabled: false`.
124
+
preserve. It is opt-in except for documented destination-specific defaults. Canonical Mistral
125
+
Chat uses a patient retry policy (6 replays, 10-second fallback interval), within the
126
+
existing request-wide send allowance. Explicit `retryOn429` settings, including
127
+
`enabled: false`, take precedence. The Mistral preset also forwards supplied prompt-cache
128
+
keys by default; `promptCacheKey: false` disables forwarding. Cache affinity improves the
129
+
chance of reuse, but does not guarantee a cache hit or remove token-throughput limits.
130
+
131
+
Mistral uses one API-key provider for both Studio and Vibe keys. Key types and plan allowances
132
+
are described in [Mistral's API-key documentation](https://docs.mistral.ai/admin/identity-access/api-keys);
133
+
the proxy does not infer a subscription tier from the key. For every model, explicit upstream
134
+
`Retry-After` deadlines are shared between calls on the same credential and model. A 429
135
+
without a retry time can activate a conservative 60-second recovery wait when valid minute
136
+
counters show exhausted capacity, or the refused query's measured cost exceeds the remaining
137
+
tokens while fitting the full advertised allowance. This is a local recovery policy, not an
138
+
exact server-reset prediction. Healthy traffic never predicts the next query's cache or cost.
139
+
After the wait, one recovery probe runs; success restores ordinary traffic. Missing, malformed,
140
+
zero-entitlement, exhausted-monthly, or above-full-allowance evidence does not invent a reset or compact history.
retry time exceeds `retryOn429.maxIntervalMs`, the proxy returns the 429 and retry hint rather
144
+
than replaying early. Context windows and per-model compaction preferences remain independent.
126
145
127
146
When round-robin key selection is enabled, queued requests recheck key cooldowns before sending and acquire pacing capacity for any replacement key. This applies to native Chat, Messages, Responses and compact. Waiting for replacement-key capacity does not consume the upstream response-header timeout. Per-key pacing and round-robin use guarded HTTP/SSE even when upstream WebSockets are enabled; WebSocket-only steering and injection require a route without those key policies. This does not change the saved active key. An established upstream turn keeps its credential; later sends are refused if that key cools. Pre-output key rejection can recover to a healthy key within the existing request limit. Direct Images and compact requests record genuine 401/429 cooldowns without replaying that paid POST.
Inline JSON and extra positional arguments are rejected. Keep exported files private and delete or store them securely after import.
480
499
500
+
Each record may carry an optional `project_id` for an account whose Cloud Code Assist project is not discovered automatically. It must be a Google Cloud project id (6–30 lowercase letters, digits or hyphens). OpenCodex uses it only when discovery finds no project, and only after a quota check with that account's own token succeeds for it; otherwise the record fails with `missing_project` and nothing is saved. A discovered project always takes precedence.
501
+
481
502
### OAuth reliability
482
503
483
504
opencodex coordinates token refresh and Codex pool routing so concurrent requests do not race the
@@ -743,6 +764,16 @@ Create a key in the [OpenGateway dashboard](https://opengateway.ai/api-keys), th
743
764
use the configured Bearer key; the public model list does not validate that key.
744
765
On the Responses wire OpenGateway rejects replayed native custom tool calls, so the preset
745
766
lowers Codex custom tools such as code-mode `exec` to function tools before sending them.
767
+
Tool-result content arrays are sent as text, with images preserved after the paired tool-result group. Unsupported result parts, including refusals and opaque content, are rejected explicitly with a client input error before sending.
768
+
Image detail `original` maps to `high`, which the gateway accepts; image bytes remain unchanged.
769
+
The native Responses route also checks text-only empty completions before exposing them as success.
770
+
Exhausted output budgets produce `incomplete` with `max_output_tokens`; the proxy does not increase
771
+
the requested budget. A replay-safe empty completion with budget remaining may retry once, within
772
+
the existing send limit. Explicit `emptyCompletionRetry: false` or `OCX_EMPTY_COMPLETION_RETRY=0`
773
+
disables that retry. Text, refusals, tool activity, and unknown stream events prevent replay and
774
+
retain the original stream. The protection does not change other providers or their retry defaults.
775
+
Replay requires explicit `store: false`, complete input, and client-executed tools only; a hosted
776
+
tool such as `web_search` prevents automatic replay even if no tool event was observed.
746
777
747
778
**TokenLab** ([sponsor](https://github.com/lidge-jun/opencodex/blob/main/SPONSORS.md)) is an
748
779
OpenAI-compatible API gateway at [tokenlab.sh](https://tokenlab.sh/r/OPENCODEX),
@@ -857,10 +888,12 @@ when a stable upstream session is required.
857
888
858
889
**MiMo tool-call echoes.** On OpenCode Go and other Chat Completions routes, a bare
859
890
`<tool_call>` block is hidden when it duplicates one structured call to the same tool
860
-
with the same effective input. If the input differs or several calls could explain
891
+
with the same effective input. This includes MiMo wrappers such as
892
+
`<tool_call_deadbeef>` with matching closing IDs, including echoes appended to ordinary prose.
893
+
Code examples remain visible. If the input differs or several calls could explain
861
894
the block, the markup remains visible. For `mimo-v2` and dotted MiMo V2 model IDs such as
862
895
`mimo-v2.6-pro`, if the gateway instead sends exactly one empty `{}` call for a declared
863
-
freeform tool and puts its input in a standalone bare block, opencodex restores that
896
+
freeform tool and puts its input in a standalone bare or identified block, opencodex restores that
864
897
input to the call and hides the block. Hyphenated IDs such as `mimo-v2-pro` and
865
898
`mimo-v2-omni` are outside this recovery rule. Prose, quoted
866
899
examples, ordinary functions, and ambiguous responses remain unchanged. This also handles
Copy file name to clipboardExpand all lines: docs-site/src/content/docs/guides/sidecars.md
+13Lines changed: 13 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -138,6 +138,19 @@ failures after response headers have started are delivered as `response.failed`
138
138
139
139
## Vision sidecar
140
140
141
+
Mistral's `zai-glm-5-3` is enrolled by the provider preset as text-only. With the
142
+
vision sidecar enabled and available, OpenCodex describes attached images and
143
+
sends their text descriptions to GLM. The Codex catalog advertises image
144
+
attachments for this route. After an update, run `ocx sync`, then fully quit and
145
+
relaunch the Codex desktop app or reload the VS Code window. Sync without a
146
+
restart flag does not restart an existing Codex app-server, which can retain
147
+
the old model list. Alternatively, use `ocx sync --restart-codex` to sync and
148
+
restart matching Codex processes and the desktop app. Finish active work first:
149
+
this restart ends live conversations. See the [sync and restart reference](/reference/cli/lifecycle/#ocx-sync---restart-codex---restart-app-server-only).
150
+
After relaunch, select `mistral/zai-glm-5-3` and verify that image attachments
151
+
are available. No model modality override is needed. Mistral documents native input in its
Image routing is capability-aware. Before an image-bearing upstream send, opencodex resolves the selected model's effective input modalities from runtime provider evidence, explicit operator declarations, backend/registry metadata, and generated vendor metadata. A target positively known to be text-only goes through the Vision Sidecar first; the image is described **before** the main call and replaced inline with text. A target positively known to support images receives the image directly. Unknown custom models keep the existing compatibility behavior rather than being guessed text-only.
142
155
143
156
For the canonical ChatGPT Codex route, opencodex uses the `openai-codex` metadata bundle rather than public OpenAI API metadata, so backend-specific modality differences are respected. The native Chat fast path uses the same gate and cannot bypass a known text-only verdict. Without an available sidecar plan, raw images are stripped before a proven text-only backend.
전용 provider 모드의 `requires_openai_auth = true`는 Codex App/TUI의 계정 게이트 화면을 네이티브 Codex와 같은 조건으로 맞춥니다. opencodex는 `/v1/responses`도 WebSocket으로 제공합니다. 전용 provider는 `"websockets": true`일 때만 `supports_websockets = true`를 광고합니다. loopback에서는 Codex의 빌트인 provider가 먼저 WebSocket을 시도할 수 있으며, 비활성화된 proxy는 `426`을 반환해서 Codex가 HTTP/SSE로 fallback합니다.
209
221
222
+
**추론 사용량 표시 보존(다음 릴리스 반영 예정).** 정식 ChatGPT 경로를 HTTP/SSE로 받는
223
+
클라이언트에는, Bun 런타임이 제공하는 상류 WebSocket 연결 응답의 실제
224
+
`x-reasoning-included` 헤더를 전달합니다. 같은 연결을 재사용하는 요청에서도 유지합니다.
225
+
이 표시는 서버가 보고한 사용량에 이전 추론량이 이미 포함됐음을 Codex에 알립니다.
226
+
첫 Responses 이벤트 전에 받은 메타데이터가 우선하며, 이후 메타데이터는 본문에 남지만
227
+
이미 확정한 응답 헤더를 바꾸지는 못합니다. 없는 표시를 만들어 붙이거나 사용량 숫자를
228
+
수정하지 않습니다. 상류가 표시를 보내지 않는 경우와 Codex 자체의 사용량 상태 관리는
229
+
별도 문제이므로, 이 변경만으로 조기 압축 해결을 보장하지 않습니다. 클라이언트도
230
+
WebSocket으로 연결하면 상류 응답 전에 연결 승인이 끝나므로, 그 승인 헤더에 표시를
231
+
나중에 추가할 수는 없습니다.
232
+
210
233
네이티브 ChatGPT forward 요청의 로컬 재생 상태가 만료되었거나 없으면 opencodex는
211
234
upstream 요청 전에 `previous_response_not_found`를 반환합니다. Codex WebSocket 클라이언트는
212
235
일반 스트림 재시도 한도 안에서 다시 연결하고, 완료된 도구 호출과 결과를 포함한 현재 보유
0 commit comments