Grok Build 안내

opencodex는 로컬 포트에서 OpenAI 호환 POST /v1/chat/completions(및 /v1/responses)를 제공합니다. Grok Build는 OpenAI 호환 서버를 상대로 사용자 정의 모델을 지원합니다. 이 통합은 opencodex가 노출하는 전체 카탈로그를 Grok Build에 자동 등록합니다. 수동으로 설정 파일을 편집할 필요가 없습니다.

자동 등록

~/.grok가 있으면 ocx start(그리고 ocx ensure / ocx restart)가 ~/.grok/config.toml에 관리 블록을 씁니다:

# >>> opencodex managed block — do not edit (removed by `ocx stop`) >>>
[model.ocx-gpt-5-6-sol]
model = "gpt-5.6-sol"
base_url = "http://127.0.0.1:10100/v1"
api_backend = "chat_completions"
api_key = "opencodex-loopback"
name = "OCX gpt-5.6-sol"
# ... one [model.ocx-*] table per visible model ...
# <<< opencodex managed block <<<

추가형: 펜스 밖에 있는 사용자 설정은 절대 건드리지 않습니다. 기존 파일에 처음 넣기 전에 한 번만 ~/.grok/config.toml.bak-opencodex에 백업을 남깁니다.
멱등적: ocx start를 실행할 때마다(자동 시작이 켜진 상태에서는 ocx ensure도) 현재 카탈로그로 펜스 블록을 다시 씁니다.
종료 시 제거: ocx stop, ocx eject, ocx uninstall, 그리고 서비스가 아닌 데몬을 정상 종료할 때는 펜스 블록을 지우고 파일을 바이트 단위까지 원래대로 복원합니다. 서비스 관리자 아래에서는 종료가 ocx stop/ocx uninstall을 거칩니다(서비스 모드 프로세스는 재생성될 때도 블록을 의도적으로 유지합니다).
충돌 안전: 이미 사용자 정의 [model.*] 테이블에 정의된 별칭은 존중합니다(opencodex는 자체 항목에 접미사를 붙입니다). 손상된 펜스(시작 표시는 있는데 끝 표시는 없는 경우)는 자동 변경을 거부하고 수동 복구를 요청합니다.

그다음 Grok Build에서 모델을 고릅니다:

grok models          # lists ocx-* entries alongside native grok models
grok -m ocx-anthropic-claude-opus-4-8 -p "hello"
# or in the TUI: /model ocx-anthropic-claude-opus-4-8

인증 참고

Grok Build는 루프백에서도 사용자 정의 모델에 비어 있지 않은 API 키를 요구합니다. 주입되는 항목에는 자리표시자(opencodex-loopback)가 들어갑니다. opencodex는 루프백 연결의 admission key를 무시하므로 실제 비밀값은 들어가지 않습니다.

자동 등록은 루프백 전용입니다. opencodex가 비루프백 호스트에 바인드하면, 모든 인터페이스를 노출하는 와일드카드 0.0.0.0와 ::를 포함해 요청은 실제 admission token을 필요로 하고, 관리 블록은 그 값을 안전하게 담을 수 없습니다. 토큰을 그대로 쓰면 비밀값이 ~/.grok/config.toml에 들어가고, 다음 ocx start/ensure/restart 때 그 자리에 있던 값이 덮어써집니다. 그래서 opencodex는 그런 경우 아무 것도 쓰지 않고(이전에 루프백 바인드가 남긴 블록도 제거합니다), 사용자는 관리 마커 바깥에서 모델을 직접 설정해야 합니다. 이 위치에서는 opencodex가 어떤 일을 해도 그 설정을 덮어쓸 수 없습니다. 정확한 테이블은 수동 설정을 보시고, base_url(실제로 grok가 도달할 수 있는 호스트)과 api_key(사용자의 OPENCODEX_API_AUTH_TOKEN)를 함께 설정합니다.

여기서는 api_key를 env_key로 바꾸지 마십시오. model_provider를 설정하지 않은 상태에서 env_key가 해결되지 않아도 요청은 멈추지 않습니다. Grok가 사용자의 xAI 세션 토큰으로 넘어가서 항목이 가리키는 base_url로 보냅니다. LAN 배포에서는 그 base_url이 xAI가 아닌 평문 HTTP 엔드포인트입니다.

주입된 모델별 api_key는 이 모델들에 대한 Grok의 자격 증명 체인에서 가장 먼저 사용되므로, opencodex를 대상으로 하는 요청에는 추가 Grok 로그인이 필요하지 않습니다. xAI에 직접 접속하는 네이티브 grok 모델과 모든 하니스 기능에는 평소 쓰던 grok login / XAI_API_KEY 구성을 그대로 유지합니다.

수동 설정 (자동 등록 없음)

직접 ~/.grok/config.toml를 관리하거나 opencodex가 비루프백 호스트에 바인드되어 있다면, # >>> opencodex managed block 마커 바깥에 모델별 테이블을 직접 필드 형태로 작성합니다:

[model.ocx-opus]
model = "anthropic/claude-opus-4-8"
base_url = "http://127.0.0.1:10100/v1"
api_backend = "chat_completions"
api_key = "opencodex-loopback"

네트워크에서 닿을 수 있는 프록시라면 base_url을 grok가 실제로 연결할 수 있는 주소로 두고 승인 토큰을 사용합니다:

[model.ocx-opus]
model = "anthropic/claude-opus-4-8"
base_url = "http://192.168.1.10:10100/v1"   # the reachable host, not 127.0.0.1
api_backend = "chat_completions"
api_key = "your-OPENCODEX_API_AUTH_TOKEN"

[model_providers.<id>] 상속에 엔드포인트를 맡기지 마십시오. Grok Build 0.2.101 기준으로 상속된 base_url은 추론 라우팅에 적용되지 않습니다(요청은 기본 xAI 프록시로 넘어가고 401로 실패합니다). 직접 넣은 모델별 필드는 정상적으로 라우팅됩니다.

점이 들어간 별칭은 반드시 따옴표로 감쌉니다. 대괄호만 쓴 [model.grok-4.5]는 id grok-4.5가 아니라 세 구간짜리 키 경로입니다. 생성된 별칭은 이런 이유로 점을 아예 쓰지 않습니다.

알려진 제한

Responses 백엔드와 keep-alive: 상위 업스트림이 조용한 동안 opencodex는 /v1/responses 스트림에 response.heartbeat keep-alive를 보냅니다. Grok Build의 Responses 디코더는 알 수 없는 이벤트 타입을 거부하므로, 수동으로 설정한 api_backend = "responses" 모델은 느린 업스트림에서 턴 도중 실패할 수 있습니다. 자동 등록된 항목은 api_backend = "chat_completions"로 고정되며, 원시 heartbeat 프레임을 노출하지 않습니다.
서비스 설치된 ocx restart: opencodex가 서비스 관리자 아래에서 실행될 때 ocx restart는 현재 서비스를 멈추고 unmanaged 프로세스로 바꿉니다. 서비스 지속성(auto-restart, start-at-login)은 다음 ocx service 설정 전까지 사라지며, 그 unmanaged 프로세스가 죽으면 다음 ocx start/ocx ensure가 갱신하기 전까지 관리 블록이 죽은 프록시를 가리킬 수 있습니다.
설정 읽기 시점: 가장 예측 가능한 결과를 얻으려면 opencodex를 먼저 시작하고 그다음 grok를 실행합니다. Grok Build는 ~/.grok/config.toml을 감시하다가 [model] 테이블이 실제로 바뀔 때 다시 불러옵니다(내용을 기준으로 비교하는 약 1초 디바운스). 그래서 새로 고친 블록은 재시작 없이 열린 세션에도 들어갑니다. Grok가 무엇을 파싱했는지 확인하려면 grok inspect를 실행합니다. 이 명령은 로드한 설정 원본을 나열하고 거부한 필드가 있으면 경고합니다. 해석된 모델 목록은 출력하지 않습니다. TOML 오류 하나만으로도 사용자 설정 레이어 전체가 무효가 되므로, opencodex가 파일을 원자적으로 쓰는 이유도 여기에 있습니다. Grok는 절반만 써진 설정을 보지 않습니다.
카탈로그 업데이트: 펜스 블록은 주입 시점의 카탈로그를 반영합니다. 공급자나 모델을 추가한 뒤에는 ocx ensure를 실행하거나 프록시를 재시작해 갱신합니다.