Re-land #8350: docs(providers): add custom gateway verification guide

docs-site/src/content/docs/guides/custom-gateway.md

@@ -0,0 +1,90 @@
+---
+title: Verify a custom remote gateway
+description: Check a custom Chat Completions gateway from discovery through a bounded completion.
+---
+
+Before registering a gateway, obtain its authorized Chat Completions base URL, API key, and
+supported model IDs from its operator. For example, `https://api.example.com/v1` is a placeholder,
+not a working endpoint. Start the proxy if it is not already running, then choose **Custom** in the
+dashboard, name it `my-gateway`, select `openai-chat`, and enter the authorized URL and key in the
+form. Save it without putting the key in commands or shared examples. A saved provider is not yet
+proof that discovery or inference works.
+
+Check the boundaries separately, using the configured local port if it differs from the default:
+
+```sh
+curl -fsS http://127.0.0.1:10100/healthz
+ocx ready
+ocx provider test my-gateway
+ocx models live --provider my-gateway --json
+```
+
+Health and readiness describe the proxy; they do not prove the upstream can generate text. The
+provider test without `--model` checks discovery, not inference. `applicable: false` can mean there
+is no live discovery endpoint for a static catalog; it is not a successful inference test. A public
+model list also need not validate the key. If discovery fails or no model appears, check the URL,
+credentials, upstream access, and provider configuration before selecting a model.
+
+A gateway can serve completions without a model-list endpoint. If its operator supplies a supported
+raw ID, configure `liveModels: false` and `models: ["vendor/model"]` on the existing provider,
+preserving its other fields and replacing the example ID with the supplied value. See
+[static model catalogs](/reference/configuration/providers/#static-model-allowlists).
+
+Before editing `config.json` directly, save your work and wait for active requests to finish;
+stopping the proxy can interrupt them. Stop the proxy through its owner: quit OpenCodex Desktop
+from its tray, run `ocx service stop` for a service install, or run `ocx stop` for an unsupervised
+proxy. Confirm it is stopped, then edit and save the file without running other configuration
+writers. Start it again through the same owner: reopen Desktop, run `ocx service start`, or run the
+original `ocx start` command with its launch options, including `--port` if supplied. For a
+foreground start, leave it running in its terminal and run `ocx sync` and the remaining checks from
+another terminal. Then inspect the live catalog again. Alternatively, test the supplied raw ID directly
+with the cost-confirmed completion command below; that test does not require a catalog row.
+
+In the live catalog inspect the actual `id`, `namespaced`, `disabled`, and
+`initialSelectionPending` fields. Initial selection can leave models off or pending; see
+[initial model selection](/reference/configuration/providers/#initial-model-selection).
+Resolve pending initial selection before enabling a row. For visibility commands, combine the
+provider name with the row's **raw `id`**, preserving any slashes inside that ID:
+
+```sh
+ocx models enable 'my-gateway/<raw-upstream-id>'
+```
+
+For example, a raw `id` of `vendor/model` needs the selector `my-gateway/vendor/model`.
+The client-facing `namespaced` slug may instead be `my-gateway/vendor-model`; substituting that
+encoded slug can leave a raw disabled entry in place. Enabling one model does not disable others.
+If only that model should be visible from this gateway, disable each other enabled gateway row
+using its raw `id` in the same selector format, then inspect the list again:
+
+```sh
+ocx models disable 'my-gateway/<other-raw-upstream-id>'
+ocx models live --provider my-gateway --json
+```
+
+Check that the intended row has `disabled: false` and the other intended exclusions are disabled.
+A bare native model ID can select a different route. Use exact values rather than display names or
+guessed reasoning suffixes: a suffix may be a distinct upstream model ID, while reasoning effort
+is a separate setting. See the [CLI reference](/reference/cli/providers-accounts/) for details.
+
+When needed, run `ocx sync` to update the client catalog, then confirm the model appears in the
+Codex model picker. A running client can retain an older in-memory list. Preserve active work and,
+if the picker remains stale, fully quit and reopen Codex. Alternatively, after explicit approval,
+use [`ocx system codex-restart --yes`](/reference/cli/agents/): it can
+interrupt the session and discard unsaved drafts, selections, or pending approval prompts.
+Outside the direct config-file edit above, restarting a client or proxy is not the default recovery step.
+
+To verify one actual completion on a supported key-auth remote configuration, pass the **raw
+upstream `id`** from the row or gateway operator unchanged, without adding the provider prefix:
+
+```sh
+ocx provider test my-gateway --model '<raw-upstream-id>'
+```
+
+This sends one bounded request, consumes quota, and may incur charges. Confirm the default-No prompt
+only after approving that cost; non-interactive or JSON use requires `--yes`. An
+`applicable: false` completion result sends no completion and is not a pass, even if the command
+exits zero. Before counting a successful test as a pass, check that the reported wire model
+matches the intended upstream ID; an alias can resolve to a different model. In JSON output this
+is `wireModel`. A successful text completion does not establish tool calling, structured output,
+continuation behavior, or the model's actual identity; upstream-reported identity is metadata. For
+later compatibility issues, reproduce the affected protocol separately with a sanitized fixture.

docs-site/src/content/docs/guides/providers.md

@@ -1835,6 +1835,8 @@ references are preserved. Flattening is lossy: branch constraints
 disappear and later property definitions win, so tools must validate arguments. Existing Zen and
 Azure schema compatibility rules remain in effect.
 
+See [Verify a custom remote gateway](/guides/custom-gateway/) for the setup and validation checklist.
+
 ## Approval reviewer per provider
 
 Codex asks a second model to review approval requests, and takes that reviewer from

docs-site/src/content/docs/ko/guides/custom-gateway.md

@@ -0,0 +1,85 @@
+---
+title: 사용자 지정 원격 게이트웨이 검증
+description: 모델 목록 조회부터 제한된 응답 생성까지 사용자 지정 게이트웨이를 확인합니다.
+---
+
+등록 전에 운영자로부터 사용이 허가된 Chat Completions 베이스 URL, API 키, 지원 모델 ID를 확보하세요.
+예를 들어 `https://api.example.com/v1`은 실제 엔드포인트가 아닌 자리표시자입니다. 프록시가 꺼져 있다면
+시작한 다음 대시보드에서 **Custom**을 선택하고 이름을 `my-gateway`, 어댑터를 `openai-chat`으로 정한 뒤
+허가된 URL과 키를 입력하고 저장하세요. 키를 명령이나 공유 예시에 넣지 마세요. 저장 성공만으로 모델 목록 조회나
+추론 성공이 증명되지는 않습니다.
+
+각 단계를 따로 확인하세요. 기본 포트가 아니면 설정한 로컬 포트를 사용합니다.
+
+```sh
+curl -fsS http://127.0.0.1:10100/healthz
+ocx ready
+ocx provider test my-gateway
+ocx models live --provider my-gateway --json
+```
+
+Health와 readiness는 프록시 상태이며 업스트림의 텍스트 생성 성공을 뜻하지 않습니다. `--model` 없는
+provider test는 추론이 아닌 모델 목록 조회를 검사합니다. 정적 카탈로그에 실시간 모델 조회 엔드포인트가 없으면
+`applicable: false`가 나올 수 있으며 이는 추론 성공이 아닙니다. 공개 모델 목록의 성공도 키 유효성을
+증명하지 않을 수 있습니다. 모델 목록 조회가 실패하거나 모델이 없다면 선택 전에 URL, 자격 증명, 업스트림 접근 권한과
+프로바이더 설정을 확인하세요.
+
+게이트웨이는 모델 목록 엔드포인트가 없어도 응답을 생성할 수 있습니다. 운영자가 지원하는 원본 ID를 제공했다면
+기존 프로바이더의 다른 필드는 유지하고 `liveModels: false`, `models: ["vendor/model"]`을 설정하세요.
+예시 ID는 제공받은 정확한 값으로 바꿉니다. [정적 모델 설정](/ko/reference/configuration/providers/)을 참고하세요.
+
+`config.json`을 직접 수정하기 전에 작업을 저장하고 진행 중인 요청이 끝날 때까지 기다리세요. 프록시를 중지하면
+진행 중인 요청이 중단될 수 있습니다. 관리 주체에 따라 Desktop 트레이에서 OpenCodex를 종료하거나, 서비스 설치는
+`ocx service stop`, 감독되지 않는 프록시는 `ocx stop`으로 중지하세요. 중지된 것을 확인한 뒤 다른 설정 쓰기 작업을
+실행하지 않는 상태에서 파일을 수정하고 저장합니다. 같은 관리 주체로 다시 시작하세요: Desktop을 다시 열거나,
+`ocx service start`를 실행하거나, 기존 `ocx start` 명령과 실행 옵션을 사용합니다. 직접 지정한 `--port`도
+포함합니다. 포그라운드 시작 명령은 해당 터미널에서 계속 실행하고 다른 터미널에서 `ocx sync`와 나머지 검사를
+실행하세요. 그다음 live 카탈로그를 다시 확인합니다. 또는 아래 비용 확인을 거치는 응답 생성 명령에
+제공받은 원본 ID를 직접 사용할 수 있습니다. 이 테스트에는 카탈로그 행이 필요하지 않습니다.
+
+live 카탈로그에서 실제 `id`, `namespaced`, `disabled`, `initialSelectionPending`을 확인하세요.
+초기 선택에 따라 모델이 꺼져 있거나 대기 상태일 수 있습니다. [초기 모델 선택](/ko/reference/configuration/providers/)을
+참고하세요. 행을 켜기 전에 초기 선택의 대기 상태를 해소합니다. 표시 관리 명령의 선택자는 프로바이더 이름과 행의
+**원본 `id`**를 조합하며, ID 내부의 슬래시를 그대로 유지합니다.
+
+```sh
+ocx models enable 'my-gateway/<원본-업스트림-ID>'
+```
+
+예를 들어 원본 `id`가 `vendor/model`이면 선택자는 `my-gateway/vendor/model`입니다.
+클라이언트용 `namespaced` 값은 `my-gateway/vendor-model`처럼 인코딩될 수 있습니다. 이를 대신 사용하면
+원본 ID로 저장된 비활성 항목이 해제되지 않을 수 있습니다. 모델 하나를 켜도 다른 모델은 꺼지지 않습니다.
+이 게이트웨이에서 해당 모델만 표시하려면 같은 선택자 형식에 각 행의 원본 `id`를 넣어 다른 활성 모델을 끄고
+목록을 다시 확인하세요.
+
+```sh
+ocx models disable 'my-gateway/<다른-원본-업스트림-ID>'
+ocx models live --provider my-gateway --json
+```
+
+원하는 행은 `disabled: false`이고 제외하려는 다른 행은 비활성 상태인지 확인하세요. 접두사 없는 네이티브 모델 ID는
+다른 경로를 선택할 수 있습니다. 표시 이름이나 추측한 reasoning 접미사 대신 정확한 값을 쓰세요. 접미사는 별도
+업스트림 모델 ID일 수 있으며 reasoning 강도는 별도 설정입니다. 자세한 내용은
+[CLI 레퍼런스](/ko/reference/cli/providers-accounts/)를 참고하세요.
+
+필요하면 `ocx sync`로 클라이언트 카탈로그에 반영한 뒤 Codex 모델 선택기에 해당 모델이 나타나는지 확인하세요.
+실행 중인 클라이언트는 이전 목록을 메모리에 유지할 수 있습니다. 진행 중인 작업을 보존하고 목록이 계속 오래된 상태라면
+Codex를 완전히 종료한 뒤 다시 여세요. 또는 명시적으로 승인한 뒤
+[`ocx system codex-restart --yes`](/ko/reference/cli/agents/)를 사용할 수 있습니다.
+이 명령은 세션을 중단하고 저장하지 않은 초안, 선택 또는 대기 중인 승인 요청을 잃게 할 수 있습니다.
+위의 설정 파일 직접 수정 외에는 클라이언트나 프록시 재시작이 기본 복구 단계가 아닙니다.
+
+지원되는 키 인증 원격 설정에서 실제 응답 생성 요청 하나를 검증하려면 행이나 게이트웨이 운영자로부터 얻은
+**업스트림 원본 `id`**를 프로바이더 접두사를 추가하지 않고 그대로 사용합니다.
+
+```sh
+ocx provider test my-gateway --model '<원본-업스트림-ID>'
+```
+
+이 명령은 제한된 요청 하나를 보내며 쿼터를 사용하고 요금이 발생할 수 있습니다. 비용을 승인한 뒤에만 기본값이
+No인 확인 질문에 동의하세요. 비대화형 또는 JSON 사용에는 `--yes`가 필요합니다. 응답 생성 테스트의
+`applicable: false`는 요청을 보내지 않았다는 뜻이며 종료 코드가 0이어도 통과가 아닙니다. 성공한 테스트를 통과로
+판정하기 전에 보고된 wire 모델이 의도한 업스트림 ID와 일치하는지 확인하세요. 별칭이 다른 모델로 해석될 수 있습니다.
+JSON 출력에서는 `wireModel`입니다. 텍스트 생성 성공
+한 번은 도구 호출, 구조화 출력, 연속 호출 또는 모델의 실제 정체를 증명하지 않습니다. 업스트림이 보고한
+모델명은 메타데이터입니다. 이후 호환성 문제는 비식별 fixture로 해당 프로토콜을 따로 재현하세요.

docs-site/src/content/docs/ko/guides/providers.md

@@ -561,6 +561,7 @@ opencodex를 로컬 OpenAI 호환 서버로 향하게 하세요 — 보통은 
 (`headers`, `noReasoningModels`, `noVisionModels`, `models`, …)는
 [설정 레퍼런스](/ko/reference/configuration/)를 참고하세요.
 
+설정과 검증 단계는 [사용자 지정 원격 게이트웨이 검증](/ko/guides/custom-gateway/)을 참고하세요.
 
 ### Antigravity 쿼터 조회 실패 확인