/v1/embeddings·RAG·CI 알림을 같은 Runbook에 묶을 운영자. 개념이 아니라 복붙 가능한 순서만 담았습니다. docs.openclaw.ai/cli의 npm 전역·onboard --install-daemon·게이트웨이 설명과 맞추세요. 연관: 계층형 모델 캐시, 게이트웨이 보안, HF Hub·CI 캐시 매트릭스.
OPENCLAW_GATEWAY_TOKEN과 launchd가 달라 자동화만 401.임베딩 실행 위치 선택
| 모드 | 이럴 때 | 트레이드오프 |
|---|---|---|
| 호스팅 API | 이그레스 안정·Mac RAM 절약 | 할당량·키 순환·허용 목록 |
| 로컬 GGUF | 비용 예측·폐쇄망 | APFS 용량·워밍 필수 |
| 루프백 사이드카 | 소규모 반복 실험 | 추가 데몬 업그레이드 부담 |
npm 전역 설치·온보딩·데몬
Node 22 LTS를 nvm·fnm 등으로 고정한 뒤 루트가 아닌 서비스 사용자로 npm install -g openclaw를 실행합니다. openclaw onboard --install-daemon으로 macOS LaunchAgent에 등록하면 SSH가 끊겨도 게이트웨이가 유지됩니다. 제공자 키는 비대화형 플래그가 허용될 때만 주입하고 로그에 남기지 마세요.
node -v
npm install -g openclaw
openclaw onboard --install-daemon비밀은 ~/.openclaw/.env.gateway chmod 600·plist 주입. 재로그인으로 PATH=launchd 정합.
memorySearch와 /v1/embeddings 프로브
openclaw.json의 agents.defaults.memorySearch에 제공자·모델·차원을 밝힙니다. 게이트웨이 Bearer와 임베딩 API는 최소 권한으로 분리합니다. 리스닝은 127.0.0.1과 문서 예시 포트(예 18765·18789)로 맞추고 외부는 리버스 프록시만 노출합니다.
OC_PORT=$(jq -r '.gateway.port // 18789' "$HOME/.openclaw/openclaw.json")
export OPENCLAW_GATEWAY_TOKEN="$(tr -d '\n' < "$HOME/.openclaw/.env.gateway")"
curl -sS "http://127.0.0.1:${OC_PORT}/v1/embeddings" \
-H "Authorization: Bearer ${OPENCLAW_GATEWAY_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"model":"text-embedding-3-small","input":"헬스체크"}' | head -c 400200·data[0].embedding 확인. 401은 토큰 diff·개행 제거·데몬 reload.
openclaw doctor·게이트웨이 상태·로그
openclaw doctor 후 openclaw gateway status --deep. launchd 로그에서 401·EADDRINUSE grep.
원격 Mac CI·벡터 의존 프리페치·알림
동일 풀 원격 Mac CI에서 HF_HOME·벤더 캐시·심볼릭 링크를 게이트웨이 plist와 동일하게 export합니다. 한산 시간대에 임베딩 가중치와 벡터 인덱스를 미리 받아 릴리스 잡은 로컬 읽기만 하게 합니다. 실패 시 관측 웹훅으로 JSON을 보내고 2·4·8초·지터·최대 세 번만 시도합니다. 429는 동시 프리페치를 줄이고 Retry-After를 따릅니다.
자주 보는 증상과 우선 조치
| 증상 | 먼저 할 일 |
|---|---|
EADDRINUSE |
lsof로 점유 확인·포트·업스트림 정렬 |
| 401 | 토큰 diff·600·reload·시간 동기 |
| 429 | 동시 프리페치↓·분리 |
ENOSPC |
df·심볼릭 대상·티어 이동 |
인용 가능한 가드레일
- 게이트웨이 Bearer 파일 600·퇴사 시 토큰 회전
- 웹훅 POST 백오프 2·4·8초·세 번 초과 시 사람 호출
- 빠른 볼륨 사용률 80% 워닝 후 임베딩 큐 조절
FAQ
가능하면 임베딩 스코프만·관리자 키는 자동화 금지.
동일 경로 검증으로 권한 버그·대용량 pull을 릴리스 밖으로.
요약. npm -g·onboard --install-daemon·memorySearch·로컬 /v1/embeddings 프로브·doctor·깊은 게이트웨이 상태·CI 캐시 정렬·경계 있는 알림 회송을 한 세트로 두면 동일 스택을 다시 만들 수 있습니다.
MacPull 원격 Mac에 게이트웨이·캐시 디스크를 두면 임베딩·RAG Runbook 고정이 쉽습니다.