서버 및 런타임 구성

서버 설정은 로컬 프록시가 어떻게 수신하고, 원격 트래픽을 어떻게 보호하며, 리소스를 어떻게 관리하고, provider 요청과 함께 돌아가는 보조 기능을 어떻게 실행할지 제어합니다.

Server fields

필드	형식	기본값	의미
port	number	10100	프록시 수신 포트입니다.
hostname?	string	"127.0.0.1"	바인드 주소입니다. 루프백이 아닌 바인드에는 데이터 admission 토큰이 필요하며, OPENCODEX_API_AUTH_TOKEN → OCX_API_TOKEN_FILE → 설치된 owner-only service-api-token 순서로 결정됩니다. 손으로 내보낼 값은 없습니다. Remote access를 보세요.
proxy?	string	—	송신용 HTTP(S) 또는 SOCKS5 프록시 URL(socks5://host:port) 또는 ${ENV_VAR}입니다. HTTP URL은 해당 변수가 비어 있을 때 HTTP_PROXY / HTTPS_PROXY에 적용됩니다. SOCKS5 URL은 내장 SOCKS5 터널을 사용하고 ALL_PROXY에도 적용되며(ocx start --socks5), 이 프로세스에서 상속된 HTTP(S)_PROXY를 지웁니다. 루프백은 NO_PROXY에 그대로 남습니다.
emptyCompletionRetry?	boolean	false	텍스트나 도구 호출이 없는 Responses 턴을, 터미널 이벤트 전에 스트림이 종료된 경우를 포함해 동일한 요청으로 한 번 재시도하도록 선택합니다. 재시도에는 비용이 발생할 수 있습니다. OCX_EMPTY_COMPLETION_RETRY=0은 설정을 바꾸지 않고 비활성화하며, combo 및 routed-compaction turn은 제외됩니다.
dropCodexSafetyBuffering?	boolean	false	Canonical Codex Responses 응답의 선택적 safety-buffering 헤더 두 개와 SSE 힌트를 제거합니다. 공급자의 안전 정책이나 거절 응답은 바뀌지 않습니다. Native WS 메타데이터와 compact는 제외됩니다.
stallTimeoutSec?	number	300(public) / 비활성(local)	스트림이 끊기기까지 유효한 업스트림 진행이 없는 시간(초, Responses 및 네이티브 Chat). 미설정 시 로컬 업스트림(loopback, private, .local/.lan 이름)은 비활성이 기본이고 공개 업스트림은 300초. 양수 값은 둘 다에 적용(최소 1초), 0은 무응답 watchdog을 전면 비활성화한다. canonical ChatGPT SSE를 비스트리밍 JSON으로 접는 Responses 요청에는 이 watchdog이 꺼져도 별도의 15분 전체 상한이 남는다. /v1/responses/compact의 보류 바디 읽기도 이 예산을 공유하지만 로컬 업스트림에서도 기본은 300초. 명시 값(0 포함)이 우선한다.
connectTimeoutMs?	number	200000(public) / 비활성(local)	요청 전송부터 업스트림이 첫 응답 헤더를 반환할 때까지의 시도별 기한(DNS/TCP/TLS 및 헤더 대기). 본문 생성 전에 끝나며, 본문 스트림을 제어하는 stallTimeoutSec와는 무관합니다. 미설정 시 로컬 업스트림(loopback, private, .local/.lan 이름)은 비활성이 기본이고 공개 업스트림은 200초. 양수 값은 둘 다에 적용, 0(또는 임의의 비양수 값)은 헤더 기한을 전면 비활성화합니다. 비활성 덕분에 로컬 모델이 큰 프롬프트에서 수 분간 prompt prefill을 해도 첫 헤더 시계가 정상 요청을 끊지 않습니다.
shutdownTimeoutMs?	number	5000	진행 중인 turn을 중단하기 전에 허용하는 정상 종료 드레인 기한입니다.
websockets?	boolean	false	클라이언트용 Responses WebSocket 경로를 광고하고 허용합니다. false이면 클라이언트는 HTTP/SSE를 사용하며, 적격 canonical ChatGPT 업스트림 WS 최적화는 비활성화하지 않습니다.
corsAllowOrigins?	string[]	[]	CORS에서 추가로 허용할 정확한 origin입니다. 루프백 origin은 항상 허용됩니다. chrome-extension://<extension-id> 같은 authority 기반 브라우저 확장 origin을 지원하며, *는 와일드카드가 아닙니다. Firefox와 Safari는 확장 UUID를 (설치/브라우저 실행 때마다) 새로 만드므로 origin이 바뀌면 항목을 갱신하세요.
apiKeys?	OcxApiKey[]	[]	비루프백 바인드에서 데이터 플레인 요청만 허용하는 생성된 ocx_… 자격 증명입니다. 관리 API는 허가하지 않으며, 관리 접근에는 관리 API 레퍼런스에 설명된 별도의 자격 증명을 사용합니다. 대시보드에서 관리합니다.
storageCleanupPolicy?	StorageCleanupPolicy	disabled	선택적으로 활성화하는 보관 세션 정리 정책입니다. 절대 암묵적으로 활성화되지 않습니다.
appOwnedMemoryBudgetMb?	number	256	제거 가능한 앱 소유 로그, 캐시, blob, continuation payload에 대한 MiB 단위 상한입니다. 범위는 64–4096이며 RSS 상한은 아닙니다.
metricsExport.enabled?	boolean	false	인증된 GET /api/metrics에서 프로세스 로컬 집계 요청 메트릭을 활성화합니다. 재시작이 필요하며, 비활성화 상태에서는 404를 반환하고 exporter 동작을 시작하지 않습니다.
serviceHealthRecovery.enabled?	boolean	false	백그라운드 서비스용 선택적 복구입니다. 작은 감시 프로세스가 /healthz를 확인하고, 프록시가 살아 있지만 연속 프로브에 약 1분 동안 전혀 응답하지 않으면 종료해 서비스 관리자(작업 스케줄러, launchd, systemd, WinSW)가 다시 시작하게 합니다. 관리되는 서비스 자식 프로세스에서만 시작되며, 멈춘 프로세스가 처리 중이던 요청은 재전송하지 않습니다. 시간당 최대 3회. 재시작이 필요합니다. 자동 복구에는 숫자 바인드 주소(또는 기본 localhost/와일드카드 매핑)가 필요합니다. DNS 바인드 이름은 모니터링하지 않습니다. 기록된 주소 또는 포트가 변경되면 모니터링이 중지됩니다.
codexAutoStart?	boolean	true	Codex shim이 Codex를 실행하기 전에 ocx ensure를 돌리도록 허용합니다. false이면 ensure는 아무 작업도 하지 않습니다.
codexShimAutoRestore?	boolean	true	완료된 외부 Codex 업데이트가 설치된 shim을 교체한 뒤 복원합니다. 환경 변수로 끌 수 있습니다: OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0.
nativeMainRefresh?	"codex" | "opencodex"	auto	CODEX_HOME의 네이티브 메인 ChatGPT 로그인을 갱신할 주체를 고릅니다. 키링 조회 결과는 해당 조회에만 적용됩니다. 토큰이 없으면 해당 자격 증명 준비는 실패하며, 다음 조회가 같은 토큰을 반환해도 사용할 수 있습니다. 영구 거부 상태는 저장하지 않으며 이미 준비된 요청은 완료할 수 있습니다. 파일 기반 동작은 유지됩니다. 자동 선택을 포함한 전체 동작은 Server fields(영문)를 참조하세요.
syncResumeHistory?	boolean	true	되돌릴 수 있는 Codex App history 호환성입니다. 원래 메타데이터는 ocx stop / ocx restore가 백업하고 복원합니다.
shadowCallIntercept?	{ enabled?: boolean; model?: string; sourceModels?: string[] }	off	인식된 Codex 보조/섀도 호출을 요청에 설정된 reasoning effort를 유지한 채 선택한 모델로 다시 보냅니다. 기본 source prefix는 gpt-6-luna, gpt-5.6-luna입니다. 0.144.x 이하의 이전 클라이언트는 gpt-5.4-mini를 사용했으며 sourceModels로 복원할 수 있습니다.
webSearchSidecar?	OcxWebSearchSidecarConfig	on when usable	웹 검색 사이드카 옵션입니다.
visionSidecar?	OcxVisionSidecarConfig	on when usable	이미지 설명 사이드카 옵션입니다.
images?	OcxImagesConfig	automatic OpenAI selection	Codex image_gen용 독립형 Images 릴레이 옵션입니다.

오래된 개발 빌드가 백업 지원이 생기기 전에 resume-history 메타데이터를 바꿨다면, native-provider 복구를 강제로 수행하려면 ocx recover-history --legacy-openai --yes를 실행합니다. 이 명령은 정상적인 dedicated-provider history를 포함해 사용자 메시지가 있는 모든 opencodex row를 재태깅합니다. 실행하기 전에 lifecycle reference의 전체 범위 경고를 확인하세요.

네이티브 Chat 시간 초과와 완료

네이티브 Chat도 업스트림 출력을 기다릴 때 stallTimeoutSec를 사용합니다. 비어 있지 않은 텍스트, 추론, 거부 내용, 도구 업데이트 및 완료 이벤트는 대기 시간을 갱신하지만 연결 유지 주석, 역할만 있는 이벤트, 사용량만 있는 이벤트는 갱신하지 않습니다. 느린 클라이언트의 읽기를 기다리는 동안에는 시간이 차감되지 않습니다. 시간 초과 시 upstream_stall_timeout이 발생하며 스트리밍 요청은 오류 이벤트를, 비스트리밍 요청은 HTTP 502를 받습니다. 종료 결과 전에 취소하면 부분 답변을 성공으로 반환하지 않고 취소 오류를 반환합니다. 비스트리밍 Chat은 LF, CRLF 및 여러 줄 data SSE 형식을 지원합니다.

Remote access

기본 127.0.0.1 바인드는 루프백 전용입니다. 0.0.0.0이나 tailnet IP처럼 루프백이 아닌 주소는 /api/*와 데이터 플레인 모두에서 토큰 인증이 필요합니다.

토큰을 직접 만들 필요는 없습니다. 루프백이 아닌 바인드에서 ocx service install이 다음 순서로 토큰을 준비합니다: 설치하는 셸의 OPENCODEX_API_AUTH_TOKEN → 기존 owner-only service-api-token 파일 → 무작위 32바이트 새 값. 결과는 0600으로 기록되고 실행 래퍼(launchd plist, systemd unit, Windows 래퍼)가 시작할 때 그 파일을 읽으므로, 값이 서비스 정의나 argv에 들어가지 않습니다. 포그라운드 ocx start도 같은 우선순위(환경 변수 → OCX_API_TOKEN_FILE → 설치된 service-api-token)를 적용하므로 토큰을 내보내지 않아도 루프백이 아닌 hostname에 바인드합니다.

관리자 토큰은 나타날 수 있는 두 곳 모두에서 거부합니다. 환경 변수이거나 재사용하는 service-api-token 파일이며, 메시지는 그 자리에 맞는 해결책을 알려 줍니다. 변수를 unset하거나, 파일을 삭제하고 ocx service repair를 실행하세요. 두 검사는 루프백 단축 경로보다 앞에서 실행됩니다. 실행 래퍼가 hostname과 무관하게 파일을 OPENCODEX_API_AUTH_TOKEN으로 읽기 때문에, 관리자 토큰이 든 파일은 루프백 바인드에서도 관리 API를 닫아 버립니다. 허브에서는 ocx status가 이 상태를 admin-collision (file)로 보고합니다.

값을 직접 관리하려는 운영자는 여전히 변수를 설정할 수 있습니다:

export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
ocx start

클라이언트는 다음을 보내야 합니다:

x-opencodex-api-key: your-secret-token

엔드포인트	Authorization: Bearer	x-opencodex-api-key	x-api-key
/v1/responses	허용되지 않음	필수	허용되지 않음
/v1/chat/completions	허용되지 않음	필수	허용되지 않음
/v1/messages	허용됨	허용됨	허용됨
/v1/messages/count_tokens	허용됨	허용됨	허용됨
/v1/models	허용됨	허용됨	허용됨

Responses와 Chat Completions는 Authorization을 향후 Codex Direct 패스스루 용도로 예약해 두므로, 여기서는 전용 admission 헤더만 허용됩니다. 대시보드에서 생성한 apiKeys는 시작 후 환경 토큰을 대체할 수 있으며, 후보 값은 상수 시간으로 비교합니다.

Messages와 count_tokens는 라우팅 클라이언트 호환성을 위해 세 admission 형식을 계속 허용합니다. 하지만 비루프백 바인드의 네이티브 Anthropic 패스스루는 프록시 admission을 x-opencodex-api-key로만 받고, Authorization과 x-api-key를 Anthropic 자격 증명용으로 예약합니다. 이 provider 헤더에 들어간 프록시 admission secret은 upstream 전달 전에 제거됩니다.

LAN exposure

0.0.0.0 바인드는 프록시와 설정된 provider 접근을 LAN에 노출합니다. 신뢰할 수 있는 네트워크에서 강한 토큰과 함께만 사용합니다.

토큰을 받을 수 없는 로컬 클라이언트

루프백이 아닌 바인드는 로컬 호출자에게도 자격 증명을 요구합니다. 그래서 한 가지 경우가 깨집니다. 호스트 프로세스가 Codex 진입점을 직접 resolve해서 띄운 codex app-server는 생성된 codex shim을 거치지 않으므로 OPENCODEX_API_AUTH_TOKEN을 물려받지 못하고, 모든 모델 호출이 스트림이 열리기 전에 401로 실패합니다.

unauthenticatedLoopbackListener는 자격 증명 없이 허용하는 두 번째 리스너를 127.0.0.1에 엽니다. 메인 리스너는 그대로입니다. 원격 호출자는 여전히 토큰이 필요합니다. port는 선택 사항이고, 있는지 없는지가 두 형태를 가릅니다.

port를 생략하면 companion 형태입니다. 리스너가 프록시 포트와 같은 번호로 127.0.0.1에 바인드합니다.

{
  "hostname": "100.76.170.81",
  "port": 10100,
  "unauthenticatedLoopbackListener": { "enabled": true }
}

원격 클라이언트는 자격 증명과 함께 100.76.170.81:10100을, 로컬 프로세스는 자격 증명 없이 127.0.0.1:10100을 호출합니다. 로컬 통합이 이미 기록하는 주소가 바로 그것이라서, 공개 바인드에 닿을 수 없는 호스트에서도 ocx claude, Claude Desktop, Cursor, system-env 주입이 그대로 동작합니다.

companion 형태는 hostname이 루프백도 와일드카드도 아닌 구체 주소일 때만 허용됩니다. 127.0.0.1, localhost, 0.0.0.0에서는 공개 리스너가 이미 그 루프백 주소를 쓰고 있으므로, opencodex가 두 번째 바인드를 실패하게 두지 않고 쓰는 시점과 시작 시점에 거부합니다. 그런 바인드에서는 리스너가 필요 없습니다. 루프백 바인드는 이미 로컬 호출자를 허용합니다.

port를 지정하면 두 표면이 서로 다른 포트에 놓입니다.

{
  "hostname": "0.0.0.0",
  "port": 10100,
  "unauthenticatedLoopbackListener": { "enabled": true, "port": 10200 }
}

이때 ocx sync는 관리되는 Codex provider 블록에 base_url = "http://127.0.0.1:10200/v1"을 기록하고 auth 헤더를 생략합니다. port는 프록시 포트와 달라야 하며 OS가 자동 할당하지 않습니다. 임시 포트는 재시작마다 바뀌는데 이미 실행 중인 app-server는 예전 base_url을 들고 있기 때문입니다.

어느 형태든 이 필드를 바꾸면 프록시를 재시작하세요. 소켓은 시작할 때 한 번 바인드되고 내보내는 클라이언트 값도 그때 결정된 포트로 기록되므로, 실행 중인 프록시는 예전 답을 유지합니다.

이 리스너는 POST /v1/responses와 그 WebSocket 업그레이드, POST /v1/responses/compact, POST /v1/messages, POST /v1/chat/completions, POST /v1/alpha/search, GET /v1/models, 실시간 음성 표면만 제공합니다. POST /v1/messages/count_tokens를 포함해 /api/*, /healthz, /readyz, 대시보드는 모두 404입니다. ocx claude의 탐색 호출 같은 로컬 관리 읽기는 관리 자격 증명을 들고 인증된 관리 표면으로 갑니다.

인증 없는 표면입니다

컴퓨터의 모든 프로세스가 이 리스너를 사용할 수 있습니다. 계정 쿼터와 유료 provider 비용을 소모합니다.

runtimeRole: "hub"에서는 이 필드가 허브가 자기 자신의 로컬 클라이언트 설정을 고칠지 결정하는 게이트이기도 합니다. 리스너가 꺼져 있으면 ocx sync, ocx ensure, ocx restore back이 허브 자신의 Codex/Grok/Claude 쓰기를 건너뛰고, clientIntegrations 토글이 아니라 unauthenticatedLoopbackListener를 지목해 이유를 밝힙니다.

SSH port forwarding

원격 사용에 원격 바인드는 필요하지 않습니다. 루프백으로 유지한 채 포워딩하면 됩니다:

ssh -L 20100:localhost:10100 you@remote

로컬 포트는 무엇이든 사용할 수 있습니다. Host가 localhost, 127.0.0.1, 또는 ::1로 해석되는 요청은 포트와 무관하게 루프백으로 유지되므로 http://localhost:20100/v1이 동작합니다. 클라이언트에 그 base URL을 설정하십시오. ocx는 관리되는 클라이언트 config에 기본 로컬 127.0.0.1 주소만 기록합니다.

provider OAuth 콜백은 고정된 원격 포트에서 수신합니다. 원격 머신에서 로그인하거나 그 포트도 함께 포워딩합니다:

ssh -L 20100:localhost:10100 -L 1455:localhost:1455 you@remote

Forwarded loopback is unauthenticated

일반 ssh -L은 로컬 루프백에서만 수신하므로 기본 비인증 바인드에는 안전합니다. ssh -g -L, 광범위한 컨테이너 퍼블리싱, 또는 클라이언트 쪽을 0.0.0.0에 노출하는 포워딩 모드는 사용하지 마십시오. 확신이 없으면 ssh -L 127.0.0.1:20100:localhost:10100처럼 명시적으로 바인드합니다.

Storage cleanup

storageCleanupPolicy는 기본적으로 비활성화되어 있습니다. 활성화하면 아카이브된 바이트가 trigger.archivedBytesOver를 넘은 뒤 startup, daily, weekly, 또는 manual 시점에 실행됩니다. 가장 오래된 아카이브를 골라 target.reduceToBytes 또는 target.removeOldestPercent 방향으로 줄입니다. mode의 기본값은 quarantine이며, permanent는 명시적인 파괴적 선택으로만 사용합니다. 이 정책은 lastRun과 nextRun을 저장합니다. Storage 페이지에서 또는 GET/PUT /api/storage/cleanup-policy로 설정할 수 있으며, 수동 실행은 POST /api/storage/cleanup-policy/run으로 트리거합니다.

Claude Code (claudeCode)

이 설정은 /v1/messages, /v1/messages/count_tokens, ocx claude 실행기, 그리고 Claude 대시보드 페이지를 제어합니다.

키	형식	기본값	설명
claudeCode.bodyStallSec?	number	90	읽기가 대기 중일 때의 native-passthrough 본문 비활성 시간 한도입니다. 전체 지속 시간이 아니라는 점에 유의합니다. 최소 1이며, 정확히 0이면 비활성화됩니다.
claudeCode.bodyMaxBytes?	number	67108864	스트리밍 및 버퍼링된 응답에 대한 누적 native-passthrough 본문 상한입니다. 정확히 0이면 비활성화됩니다.
claudeCode.authMode?	"proxy" | "subscription"	auto	실행 시 ANTHROPIC_AUTH_TOKEN을 어떻게 다룰지입니다. 자동은 매 실행마다 인증을 감지하며, 명시 값은 절대 덮어쓰지 않습니다.
claudeCode.authModeMigratedAt?	string	unset	내부적인 일회성 업그레이드 마커입니다. 수동으로 설정하지 마십시오.
claudeCode.subagentEffort?	"low" | "medium" | "high" | "xhigh" | "max"	inherit	생성된 ~/.claude/agents/ocx-*.md에 쓰이는 노력 수준입니다. Codex 지침과 프록시 상한과는 별개입니다. 다시 생성하려면 ocx claude로 재시작합니다.

자동 인증은 저장된 Claude 인증이 있으면 subscription을, 없으면 proxy를 선택합니다. 감지가 불명확할 때는 경고와 함께 subscription을 선택합니다. Claude Code 인증 모드를 보십시오.

Shadow calls

Codex는 제목과 커밋 메시지 같은 작업에 작은 보조 모델을 사용합니다. 인식된 source-model prefix를 다른 구성된 모델로 돌리려면 shadowCallIntercept를 활성화합니다. 대체 호출은 요청에 설정된 reasoning effort를 유지합니다. 클라이언트가 다른 helper id를 사용할 때만 sourceModels를 설정합니다.

한정되지 않은 모델 ID가 sourceModels와 일치하면 가로채기 대상이지만, x-codex-turn-metadata에 request_kind: "turn"과 thread_source: "user"가 함께 명시된 사용자 턴은 선택한 모델을 유지합니다. 연결 헤더 x-openai-subagent: collab_spawn(HTTP 요청 또는 WebSocket 핸드셰이크) 또는 메타데이터의 subagent_kind: "thread_spawn"으로 표시된 자식도 모델을 유지합니다. WebSocket에서 턴 메타데이터는 각 프레임의 client_metadata["x-codex-turn-metadata"]만 사용하며 핸드셰이크의 턴 메타데이터는 이후 프레임을 분류하지 않습니다. 메타데이터가 없거나 잘못된 형식이면 기존 가로채기 동작을 유지합니다. 헬퍼도 request_kind: "turn"을 사용할 수 있으므로 이 필드만으로는 예외가 되지 않습니다. 이 규칙은 구체적 모델 대상과 콤보 대상에 모두 적용됩니다.

{
  "shadowCallIntercept": {
    "enabled": true,
    "model": "gpt-5.5",
    "sourceModels": ["gpt-6-luna", "gpt-5.6-luna"]
  }
}

대상을 쓸 수 없을 때

대체 대상은 운영자가 고른 단 하나의 목적지이므로, 더 이상 해석되지 않는 대상은 다른 곳으로 보내지 않고 보조 호출을 실패시킵니다. 대상의 프로바이더가 비활성화되거나 삭제되었거나 콤보가 사라졌다면, 가로챈 요청은 업스트림에 아무것도 보내기 전에 409와 오류 코드 intercept_target_unavailable을 반환합니다. 요청 로그에도 같은 코드가 남습니다. 요청은 네이티브 보조 모델로 그대로 넘어가지 않고 기본 프로바이더로 폴백하지도 않습니다. 둘 다 사용자가 고르지 않은 목적지, 자격 증명, 비용으로 바꾸기 때문입니다. 콤보나 라우팅 프로필 대상은 계속 자기 멤버 사이에서 페일오버합니다. provider/model처럼 한정된 대상인데 프로바이더 부분이 설정된 어떤 것도 가리키지 않으면 같은 방식으로 처리하고, 설정 API는 이를 저장하지 않습니다. 기본 프로바이더를 통해 해석되는 한정되지 않은 모델 ID는 그대로 유효합니다.

대상이 해석되는 프로바이더를 비활성화(disabled: true를 담은 PATCH /api/providers?name=<provider>)하거나 삭제해도 작업은 성공하며, 응답에 dependentShadowIntercept: { model, enabled }가 추가되고 대시보드에 경고가 표시됩니다. 프로바이더를 다시 켜거나 다른 대상을 고르면 가로채기가 다시 동작합니다.

Sidecars

images (OcxImagesConfig)

필드	형식	기본값	의미
provider?	string	automatic OpenAI selection	/v1/images/generations와 /v1/images/edits에 사용하는 명시적인 custom API-key openai-responses provider입니다. registry-managed ids는 거부됩니다.
timeoutMs?	number	300000	단일 standalone Images 요청 하나에 대한 전체 요청 제한 시간입니다.

명시적으로 선택하면 provider가 없거나, 비활성화되어 있거나, 호환되지 않거나, 사용할 수 있는 키가 없을 때는 닫힌 상태로 실패하며, 다른 유료 업스트림으로 절대 폴백하지 않습니다. 이 엔드포인트는 Codex가 기대하는 OpenAI Images API 경로와 응답 형식을 구현해야 합니다.

webSearchSidecar (OcxWebSearchSidecarConfig)

필드	형식	기본값	의미
enabled?	boolean	on when usable	주 스위치입니다. false이면 OpenCodex는 web_search 가로채기를 멈추고 Codex 통합이 ~/.codex/config.toml에 web_search = "disabled"를 씁니다.
backend?	"openai" | "anthropic" | "xai" | "gemini" | "exa"	openai	명시값이 우선입니다. 생략하면 항상 openai입니다. anthropic과 xai는 명시적으로 설정할 때만 실행되며, gemini와 exa는 executor가 제공될 때까지 예약 상태입니다.
model?	string	backend-dependent	OpenAI는 gpt-5.6-luna, Anthropic은 claude-sonnet-5, xAI는 grok-4.6입니다. 레거시로 명시된 gpt-5.4-mini는 시작 시 마이그레이션됩니다.
exaApiKey?	string	없음	exa 백엔드용 운영자 키입니다. 쓰기 전용이며 관리 API 조회에서는 저장된 값을 반환하지 않습니다.
xSearch?	object	생략	xAI 전용 x_search opt-in입니다. enabled, 서로 배타적인 allowedXHandles / excludedXHandles 배열(최대 20개), ISO fromDate / toDate(YYYY-MM-DD)를 지원합니다.
reasoning?	string	low	사이드카 노력 수준입니다. minimal은 web search와 함께 거부됩니다.
maxSearchesPerTurn?	number	3	메인 모델 턴당 허용되는 실제 검색 수입니다.
routedModelStallTimeoutMs?	number	200000	설정 파일 전용 routed-model 원시 본문 비활성 기한입니다. 정수 1–2147483647이며, 비어 있지 않은 모든 청크가 이를 다시 시작합니다.
timeoutMs?	number	60000	한 번의 hosted search에 대한 기한입니다.

OpenAI 백엔드는 ChatGPT 로그인과 활성화된 ChatGPT forward provider를 요구합니다. Claude-inbound routed replay는 메인 ChatGPT 인증을 내부 요청에 주입합니다. Anthropic 백엔드는 활성화된 Anthropic OAuth provider에서 현재 저장된 자격 증명을 사용합니다. 명시적으로 선택한 Anthropic 백엔드에 사용할 수 있는 계정이 없으면 폴백하지 않고 닫힌 상태로 실패합니다. Anthropic 실행기는 자체 web_search_20250305 도구를 사용합니다. xAI 백엔드는 사용 가능한 저장된 Grok OAuth 계정을 요구하고 hosted web_search를 사용하며, xSearch.enabled가 true이면 hosted x_search를 추가합니다. 잘못된 xSearch 관리 입력은 400을 반환하고, 잘못 저장된 블록은 계획 단계에서 닫힌 상태로 실패합니다. gemini와 exa는 자격 증명 탐색이나 폴백으로 절대 활성화되지 않으며 운영자가 명시적으로 선택해야 합니다. exaApiKey는 쓰기에서 허용되지만 관리 응답에서는 생략됩니다.

검색에는 네 가지 시계가 작동합니다: 기본 stallTimeoutSec, connectTimeoutMs, routed-model 비활성 시간, 그리고 hosted-search 제한 시간입니다. 실제 bridge watchdog은 이들 중 최댓값에 30초를 더한 값입니다. Routed stall은 비활성 가드이지, 전체 생성 기한이 아닙니다.

visionSidecar (OcxVisionSidecarConfig)

필드	형식	기본값	의미
enabled?	boolean	on when usable	주 이미지 설명 스위치입니다.
backend?	"openai" | "anthropic"	auto	명시값이 우선하며, 미설정 시 사용 가능한 저장된 Anthropic OAuth 자격 증명을 우선하고 없으면 openai를 사용합니다.
model?	string	backend-dependent	OpenAI는 gpt-5.6-luna, Anthropic은 claude-sonnet-5입니다.
reasoning?	"low" | "medium" | "high" | "xhigh" | "max"	"low"	OpenAI Responses 추론 강도입니다. Anthropic은 무시합니다.
maxDescriptionsPerTurn?	number	8	메인 턴당 허용되는 새 설명 캐시 미스 수입니다. 0이면 호출이 비활성화되며, 잘못된 값은 기본값을 사용합니다.
timeoutMs?	number	45000	사이드카 fetch 제한 시간입니다. 정수 1–2147483647.

지원되는 수준은 업스트림 제공자의 역량과 선택한 모델이 공개한 추론 사다리에 따라 제한됩니다. Vision은 provider의 noVisionModels에 속한 모델로 보낸 이미지에만 활성화됩니다. OpenAI는 검색과 같은 로그인/forward 요건을 갖고 있으며, 명시적으로 선택한 Anthropic은 사용할 수 있는 자격 증명이 없으면 닫힌 상태로 실패합니다. 성공한 data: 설명은 backend, model, detail, image bytes, 그리고 정규화된 메시지 컨텍스트를 키로 하는 bounded cache를 사용합니다. OpenAI 키에는 reasoning effort도 포함됩니다(Anthropic 키에는 없습니다). 히트와 같은 턴의 중복은 한도를 소모하지 않습니다. 원격 https: 이미지와 실패했거나 비어 있는 설명은 캐시하지 않습니다.

Anthropic OAuth 사이드카는 opencodex의 기존 Claude Code OAuth fingerprint를 재사용합니다. 의도한 계정과 워크로드로 소크 테스트를 수행합니다.

Remote Hub 키와 기본값

runtimeRole 기본값은 standalone입니다. 허브는 hub.managementPublicOrigin, 로컬에만 열리는 hub.managementIngress(없으면 enabled:false), 정확한 remoteGui.allowedTailscaleUsers(없으면 빈 목록)를 사용합니다. 클라이언트 데이터 키는 config.json이 아니라 service-api-token에 저장되며 교체 중에는 service-api-token.prev가 잠시 생길 수 있습니다. 사용량 기록은 서로 복제하지 않습니다.

키	형식	없을 때 기본값	역할
hub.managementPublicOrigin	string	없음	허브가 광고하는, 브라우저가 실제로 닿는 관리 Origin입니다. runtimeRole이 hub일 때 /readyz가 managementUrl로 보고합니다. 설정하지 않으면 요청이 도착한 Origin으로 대체하므로, 다른 프런트엔드 뒤의 클라이언트가 닿을 수 없는 주소를 받을 수 있습니다.
hub.dataPublicOrigin	string	없음	원격 클라이언트가 데이터 플레인으로 호출해야 하는 정식 Origin입니다(예: tailnet 바인드 앞의 TLS 프런트엔드가 공개하는 HTTPS Origin). 광고용 값이며 바인드 주소가 아니고, 바꿔도 소켓은 움직이지 않습니다. ocx hub invite가 출력하는 ocx connect 줄의 위치 인자 URL로 쓰이고, 없으면 http://<hostname>:<port>로 대체합니다. 그 대체값은 원격 컴퓨터가 TLS로 닿지 못할 LAN/tailnet 주소이므로 프런트엔드가 있는 허브라면 설정하세요. 대부분의 선택 키와 달리 잘못된 값은 조용히 버리지 않고 쓰는 시점에 거부합니다. 바인드 주소로 대체되는 것이 바로 이 필드가 막으려는 상황입니다.
hub.managementIngress	{enabled:false} 또는 {enabled:true, port}	{enabled:false}	로컬 HTTPS 프런트엔드용 관리 전용 리스너입니다. hostname은 설정할 수 없고, 켜면 항상 127.0.0.1에 바인드하며 GUI·세션 부트스트랩·관리 API 경로만 허용합니다. 데이터 플레인 경로는 dispatch 전에 거부합니다.
remoteGui.allowedTailscaleUsers	string[]	[](아무도 없음)	자동 원격 GUI 세션을 발급받을 수 있는 정확한 Tailscale 로그인 ID입니다. Tailscale-User-Login 헤더는 별도 관리 인그레스에서만 신뢰합니다. 빈 목록은 실수가 아니라 안전한 기본값입니다. 정확히 비교하므로 오타는 조용히 거부됩니다.

dataPublicOrigin과 managementPublicOrigin은 서로 독립적인 광고이며, 실제 배포에서는 서로 다른 소켓입니다. 관리는 443에 공개하는 루프백 전용 인그레스이고, 데이터는 자체 HTTPS 포트에 공개하는 tailnet 바인드입니다. 둘은 ocx hub invite가 출력하는 명령의 두 조각이고, 그중 managementPublicOrigin이 더 엄격합니다. pairing grant가 이 값을 grant 자신의 server origin으로 기록하고 교환 시 비교하므로, ocx hub invite --management-url은 설정값을 확인할 수만 있고 다른 값은 거부합니다. --data-url은 아무것도 바인드되어 있지 않으므로 실제로 덮어쓰기입니다. dataPublicOrigin과 --data-url이 모두 없으면 invite는 바인드 주소로 대체하는데, 루프백이나 와일드카드 바인드에서는 그것이 이 컴퓨터 자신의 루프백이 되므로 상대가 쓸 수 없는 주소를 광고하는 대신 거부합니다.

허브가 자기 로컬 클라이언트까지 서비스하려면 unauthenticatedLoopbackListener도 설정합니다. port 없는 companion 형태가 허브를 단일 포트 배포로 만들어 주며, 공개 리스너가 이미 127.0.0.1:<port>를 쓰는 루프백·와일드카드 hostname에서는 거부됩니다.

remoteGui.allowInsecureHttp는 이전 strict-schema 설정을 계속 읽기 위해서만 남겨 둔 폐기된 no-op입니다. 설정에서 제거하세요. 페어링 grant는 loopback 또는 인증된 HTTPS에서만 허용되며, 이 값을 true로 설정해도 평문 HTTP 페어링은 다시 활성화되지 않습니다.

Codex 할당량 네트워크 진단

메인 Codex 계정 행의 quotaRefresh는 할당량 조회 결과를 분류하는 진단값입니다. 남은 할당량이나 모델 접근 권한을 뜻하지 않으며, 캐시를 쓰거나 조회하지 않았다면 생략될 수 있습니다. 요청은 명령을 입력한 터미널이 아니라 실행 중인 프록시 서비스의 환경을 따릅니다. proxy를 지정하지 않으면 기존 환경을 유지하고, "auto"는 시작 시 Windows 또는 macOS의 정적 HTTP/HTTPS 설정을 읽습니다. macOS에서는 상속된 프록시가 있으면 읽지 않습니다. macOS에서는 유효한 *.<domain>을 .<domain>으로 바꿉니다. *.local은 foo.local과 최상위 이름 local을 직접 연결하지만 xlocal은 제외합니다. 169.254/16, 169.254.0.0/16, fe80::/10은 진단 메시지와 함께 생략하므로 링크 로컬 IP 주소는 프록시를 사용합니다. IP 주소와 *는 허용하지만 다른 CIDR, glob, 단순 호스트명 예외는 환경 변경 전에 탐색을 거부합니다. PAC/WPAD, SOCKS 전용 설정과 실행 중 변경은 자동으로 반영하지 않습니다. TUN에서 성공했다고 HTTP 프록시 경로도 정상이라는 뜻은 아닙니다. 명령과 상태값은 네트워크 진단(영문)에서 확인하세요.

Forced Claude Code subagent model

The Subagents page offers Force all subagents onto one model, off by default. Select an exposed roster-style id, such as combo/tev-auto, then enable the switch. The roster is offered first; unavailable saved roster entries cannot be force targets.

ocx agent subagents force combo/tev-auto sets claudeCode.subagentModelForce; ocx agent subagents force - clears it. ocx agent status reports the setting. GET /api/subagent-models returns force, forceAvailable, and forceStatus; PUT accepts { "force": "combo/tev-auto" } or { "force": null } without changing the roster. Omitting force leaves it unchanged. Invalid or unexposed targets are rejected on write; stale targets are reported and skipped at launch.

This takes effect on the next routed ocx claude launch, injecting CLAUDE_CODE_SUBAGENT_MODEL as an explicit proxy alias (with [1m] only for an authoritative million-token window; native Claude targets use a reversible native alias) and CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Each nonempty shell-exported variable independently wins. Native launches inject neither variable; plain claude is not affected. No plugin files or settings.json are modified by this setting.

Claude Code 2.1.257 or newer is required for FORCE. Plugin and built-in agents (including Explore/Plan) and per-call model arguments are overridden. Forks and subagent skills with model: inherit keep the main conversation model. The main loop and Haiku/small-fast sidecars are unaffected. Existing roster files remain available.

The dashboard warns about old or unknown CLI versions, unavailable targets, and either variable already present in settings.json → env (which overrides launch env). Detection is read-only and server-local: it cannot inspect another launch shell, another machine, or project-local settings. An unknown result is not proof of force support.

과거 풀 사용량의 연속성

제공자 풀 한도는 실제로 선택된 제공자에 적용합니다. 요청 로그의 계정 표시 이름과는 구분합니다. 현재 설정된 제공자 P는 잔액을 읽을 때 자신의 솔트 풀 별칭인 h(pool, P)와 자동으로 연결됩니다. 같은 별칭에 남아 있는 과거 잔액도 여기에 속합니다. 제공자마다 독립적인 한도를 쓰려고 자기 매핑을 직접 넣거나 솔트로 해시를 계산할 필요는 없습니다.

다른 과거 표시 이름이나 계정 순번이 붙은 라벨은 자동으로 연결하지 않습니다. 소유자를 확인한 과거 이력은 config.json 최상위의 spendPoolAliases에 매핑을 넣으세요. 키는 같은 설치의 과거 풀 별칭인 32자리 소문자 16진수이고, 값은 현재 설정에 있는 확인된 제공자의 정확한 ID입니다. ID 앞뒤에 공백을 넣지 마세요. 현재 이름이나 계정 순서만 보고 소유자를 추측하지 마세요. 저널과 솔트는 비공개로 보관하세요.

자동 연결과 명시적 매핑은 잔액을 읽을 때만 적용합니다. 원래 잔액을 옮기거나 저널에 식별 연결 정보를 저장하지 않습니다. 명시적 매핑을 삭제하면 그 이력은 다시 소유자 미확인 상태가 됩니다. 단, 현재 설정된 제공자 자신의 별칭이면 자동 연결이 남습니다. 각 잔액은 연결된 제공자 그룹에 한 번만 계산합니다. 연결되지 않은 양수 잔액은 모든 후보 풀에 한 번씩 보수적으로 더합니다. 설정된 제공자 자신의 솔트 별칭을 다른 제공자에 연결하면 거부합니다. 제공자를 추가할 때도 검사하며, 검증 과정에서 새 솔트를 만들지는 않습니다. 매핑이 잘못돼도 기존 한도는 유지합니다.

휴면 상태인 미확인 이력은 마지막 활동이 spend.retentionDays보다 오래됐을 때만 만료됩니다. 용량이 부족해도 양수 이력을 먼저 지우지 않습니다. 진행 중인 예약과 seed는 0토큰이어도 보존하며, 삭제 기록이 저장된 뒤에만 허용 여부를 판단하는 잔액을 줄입니다. 한도가 적용되는 요청은 대상·키별 첫 전송 전에 일반 추적 용량으로 예약해야 합니다. 재시도는 같은 범위를 씁니다. L은 요청 전체가 공유하는 물리 전송 횟수 한도이며 요청이 시작할 때 고정됩니다. 기본은 4회이고, 기존 OAuth 요청 프로필은 최대 18회까지 허용합니다. 모든 물리 전송이 이 유한한 한도를 함께 씁니다.

한도 적용 여부, 적용할 루트·계정·제공자 풀의 토큰 한도, L은 요청이 시작할 때 정합니다. 설정을 바꾸면 변경 후 시작하는 요청에만 적용됩니다. 이미 실행 중인 요청은 재시도와 후속 전송에서도 시작할 때의 정책을 유지합니다. 한도를 켜거나 낮춰도 실행 중인 요청을 더 제한하지 않고, 높이거나 없애도 더 허용하지 않습니다. 관측 모드로 시작한 요청은 끝날 때까지 관측 모드를 유지합니다. 최종 정산은 보고가 끝날 때까지 기다립니다. 전송 ID를 지워도 잔액은 남습니다. 적용되는 한도가 없으면 기존 관측 동작을 유지하며, 추적 용량이 찼을 때 기록을 생략하는 동작도 그대로입니다.

Claude CLI·CodeBuddy·Qoder는 CLI 호출 한 번을 전송 한 번으로 셉니다. 실행 전 일반 예약이 필요하며, 예약하지 못하면 실행을 거부합니다. CLI 내부 재시도·도구 턴은 요청 전체 전송 횟수 한도에 따로 세지 않지만 비용은 보고된 실제 사용량으로 정산하며, 최초 추정량을 넘은 비용도 기록합니다.

2.80.0으로 롤백: 계약 C

새 기록은 기존 v1 형식과 pool 별칭을 씁니다. 수정하지 않은 2.80.0도 자신의 라벨별 규칙대로 읽고 압축·보존할 수 있습니다. 최신 저널과 솔트를 유지하세요. 롤백 후 제공자별 통합 집계가 유지되거나, 같은 요청을 처음부터 2.80.0에서 처리했을 때와 남은 한도가 같다는 보장은 없습니다. 다시 업그레이드하면 남아 있는 원래 잔액에 현재 설정된 제공자의 자동 연결과 명시적 매핑을 적용합니다. 별도의 실행 차단 장치나 조정 명령은 필요하지 않습니다. 미공개 실험 버전의 pool-current / poolContinuity 이력은 계약 C에서 제외합니다. 원래 잔액을 미확인 이력으로 보존하고 일반 보존 기간이 지난 뒤 만료시키며, 즉시 변환하거나 삭제하지 않습니다.

완전하지만 잘못된 기록(마지막 줄의 null 포함)이 있으면 한도가 적용되는 요청을 거부합니다. 압축은 유효한 잔액을 보존하며 계속할 수 있습니다. 실행 중 거부 상태는 재시작 뒤 깨끗한 저널을 읽을 때까지 남습니다. 쓰다 끊긴 마지막 JSON 줄은 기존 복구 규칙을 따릅니다. 세부 조건과 오류 코드는 영문 원문을 참조하세요.

로컬 업스트림 타임아웃 분류

로컬 분류는 타임아웃 정책이며 네트워크 접근 권한을 부여하지 않습니다. DNS 조회 없이 HTTP(S) 목적지를 분류합니다. 정확한 localhost(대소문자 무관, 끝의 점 허용), 0.0.0.0, IPv4 loopback(127/8), RFC 1918 private 및 link-local(169.254/16), IPv6 loopback·link-local(fe80::/10)·unique-local(fc00::/7), IPv4-mapped 주소, .local/.lan 이름이 로컬입니다. 다른 DNS 이름은 loopback으로 해석되더라도 공개 기본값을 유지합니다. 잘못된 목적지, 지원하지 않는 스킴, localhost.example도 공개 기본값을 유지합니다.

헤더 제한을 꺼도 클라이언트 취소와 상위 전체 기한은 유지됩니다. 명시적인 양수 stallTimeoutSec는 로컬 바디 무응답을 제한합니다. 로컬 헤더·stall 설정이 모두 없으면 헤더 이전의 자동 제한은 없습니다. 네이티브 Chat/Messages 로컬 JSON 읽기는 stall 예산을 쓰며 공개 JSON 읽기는 기존 max(connectTimeoutMs ?? 200000, 5000)을 유지합니다. Compact 바디의 기본 300초와 이미지/검색 사이드카 예산도 유지됩니다.

선택 설정 opencodeClientExport의 headerTimeoutMs, chunkTimeoutMs, timeoutMs는 양수 밀리초 또는 비활성화 값 false를 받습니다. 생략 시 OpenCode 기본값을 유지하고 잘못된 필드는 내보내지 않습니다. V1 options와 V2 settings의 provider 전체에 적용됩니다. 느린 로컬 모델을 참고하세요.