OpenClaw · 게이트웨이 · /v1/models · OpenAI 호환 · 모노레포 · 원격 Mac · 2026
2026 OpenClaw 프론트 실전:
원격 Mac에서 게이트웨이 /v1/models를 OpenAI 호환 클라이언트에 맞추고, 모노레포 변경 경로별 스모크 절차를 재현한다
2026.04.20
프론트·API 게이트
약 9분
대상: OpenClaw 게이트웨이 뒤에서 OpenAI 호환 클라이언트를 유지하려는 팀. 본문은 설치·라우트·별칭·셸·PR만 다루며 호스팅 Deploy Hook 글과 역할을 나눕니다. 연계: OpenAPI·curl 스모크, 빌드 메트릭 PR, Import Maps·ESM 검수.
01 왜 /v1/models가 조용히 깨지나
클라이언트는 목록을 캐시하고 채팅만 먼저 검증하는 경우가 많습니다. data 형식·프록시 경로·별칭 테이블 복제가 틀어지면 UI만 늦게 깨집니다. 원격 Mac에서 동일 환경으로 재현해야 합니다.
02 OpenAI 호환 클라이언트 기대 vs 게이트웨이 책임
표를 먼저 통과시키세요.
| 항목 | OpenAI 호환 클라이언트 | 게이트웨이 |
|---|---|---|
| 엔드포인트 | 채팅과 동일한 baseURL에서 GET /v1/models. |
TLS·인증 미들웨어를 채팅과 동일 순서로 적용해 curl과 SDK가 같게 보이게 한다. |
| 인증 | 기본적으로 Authorization: Bearer …. |
비밀이 없을 때 조기 401; 리다이렉트 루프로 메서드가 바뀌지 않게 한다. |
| 형태 | { "object":"list", "data":[ { "id", "object", "created", "owned_by" } ] }를 가정. |
클라이언트가 필터링하는 필드를 제거하지 말고 확장은 문서화한다. |
| 별칭 | 사용자 라벨을 공급자 id에 매핑. |
별칭 맵을 게이트웨이 설정 옆에 버전 관리해 조용한 포크를 막는다. |
03 HowTo: 설치·게이트웨이 라우트·모델 별칭·모노레포 변경 경로
- 설치: 루트에서 lockfile대로
npm ci/pnpm install, CI와 동일 런타임 버전 고정. - 환경:
GATEWAY_BASE또는OPENAI_BASE_URL,OPENAI_API_KEY, 필요 시PROVIDER_*를 한 세션에. - 라우트:
GET /v1/models를 앱에서 채팅과 같은 베이스·미들웨어 순서로. - 별칭: 게이트웨이 설정과 공유 패키지 한 곳에서만 해석.
- 경로→스모크:
packages/gateway·프록시·공유 인증 변경은 전체 models 프로브; 문서만이면 생략 가능(예제 env 수정 시 제외). - 산출물:
models_smoke.json에 상태·ms·정렬id.
04 실행 가능한 프로브(원격 Mac 셸)
BASE는 슬래시 없이 통일합니다.
#!/usr/bin/env bash
set -euo pipefail
BASE="${OPENAI_BASE_URL:?}" KEY="${OPENAI_API_KEY:?}"
curl -sS -H "Authorization: Bearer ${KEY}" "${BASE%/}/v1/models" -o models_smoke.json
jq -e '.object=="list" and (.data|type=="array")' models_smoke.json
jq -r '.data[].id' models_smoke.json | sort > current_models.txt- ▸헤더 감사:
curl -sSI "$BASE/v1/models"로 토큰 없을 때401인지, 의도치 않은 302인지 확인합니다. - ▸diff 게이트: 이전 커밋에서 저장한
prior_models.txt와git diff --no-index로 목록 변화를 봅니다. - ▸리팩터 후 탐색:
rg "v1/models" packages apps -n로 Express·Fastify 마운트 누락을 잡습니다. - ▸선택 채팅 스모크: 동일
BASE로 한 번의 채팅 호출을 추가하면 GET만 살아 있는 가짜 정상을 걸러냅니다.
05 PR 워크플로·필수 체크 연결
CI에 gateway-models 필수 검사·models_smoke.json 아티팩트·별칭 PR에는 area:models. 요약은 티켓에 멱등 첨부. 캐시·SW 자동화·호스팅 훅과 보완 관계입니다.
06 인용 가능한 체크
베이스 URL: SDK 설정이 게이트웨이 루트에서 끝나야 하며 /v1를 이중으로 붙이지 않습니다.
정렬된 id: 사전순으로 내보내면 설정 병합 실수로 생긴 중복이 드러납니다.
모노레포 범위: 게이트웨이·인증 변경은 models 스모크 필수, 순수 문서는 예외(단 env 예제 변경은 제외).
07 FAQ
401
Bearer·세션 export·공백 제거 후 시크릿과 대조.
200·빈 data
로그·업스트림 직접 curl로 분리.
스모크 범위
미들웨어는 models+가벼운 채팅; 문서만이면 생략 가능.