바로가기: 환경과 의존성 · 게이트웨이와 CrewAI 통합 단계 · 예산과 서킷 브레이커 파라미터 · 일반적인 오류 · FAQ
전제는 전용 원격 Mac(Apple Silicon)에서 장기 서비스를 유지하는 것입니다. LiteLLM·게이트웨이·스키마 재시도·관측·비용 매트릭스와 짝을 맞추고, 구매·요금은 로그인 없이 열람합니다.
환경과 의존성
호스트·파이썬. macOS 14+, 가상환경에 Python 3.11과 crewai·httpx 등을 requirements.txt로 고정합니다. 토크나이저·가중치는 로컬 SSD에 둡니다.
OpenClaw CLI. OpenAI 호환 라우팅 안내와 맞추려면 Node 22 LTS를 설치하고 openclaw gateway listen을 127.0.0.1에 바인딩하며, 대시보드에서 받은 베어러 자료는 ~/.openclaw/token 같은 경로에만 두고 서비스 유저만 읽게 합니다.
선택 추론 허브. 이기종 벤더를 하나의 OpenAI 표면 뒤에 둘 때는 LiteLLM 글처럼 LiteLLM Proxy를 OpenClaw 옆에 두고, CrewAI에는 원시 공급자 키가 나가지 않게 합니다.
운영 가드레일. 게이트웨이·프록시·워커는 계정·launchd 라벨을 분리하고 포트는 런북 한 곳에만 적습니다.
게이트웨이와 CrewAI 통합 단계
| 관심사 | CrewAI 크루 | OpenClaw 게이트웨이 |
|---|---|---|
| LLM 호출 | 에이전트·태스크가 프롬프트를 조율하고 모델명은 안정 별칭만 사용 | OpenAI 호환 트래픽 인증, 별칭→업스트림 라우트 매핑, 상관 ID 강제 |
| 부수 효과가 있는 도구 | 커스텀 도구가 짧은 타임아웃의 HTTP 클라이언트로 감쌈 | 허용 목록 라우트 노출, 페이로드 검증, 감사 트레일 병합 |
| 실패 처리 | 크루 매니저가 사용자에게 결과를 요약 | 구조화 오류 본문 반환, 파이썬이 보기 전에 비밀 제거 |
1. LLM 클라이언트 바인딩. OPENAI_API_BASE(또는 CrewAI LLM 설정)를 http://127.0.0.1:게이트웨이포트/v1로 두어 모든 에이전트가 동일 정책 표면을 씁니다.
2. 도구를 게이트웨이 URL에 등록. 문서화된 /tools/... 엔드포인트로 Bearer 헤더·토큰 파일·crew.kickoff 메타데이터의 X-Correlation-Id를 붙입니다.
3. 인자 선검증. HTTP 전에 JSON Schema나 Pydantic으로 형태를 거르고, 공급자 쿼터를 건드리지 않게 스키마 재시도 가이드와 동일한 규율을 둡니다.
4. 크루 실행 직렬화. 동일 도구를 여러 에이전트가 부르면 asyncio 세마포나 워커 풀 상한으로 폭주를 큐로 바꿉니다.
5. 오류를 봉투로 매핑. 도구 클라이언트에서 HTTP 실패를 가로채 route·code·correlation_id·hint를 정규화한 뒤 매니저가 번역할 안전 예외로 올립니다.
6. 스모크. 두 에이전트·노옵 도구로 돌린 뒤 동일 토큰으로 헬스 curl·openclaw doctor --json을 보관합니다.
# CrewAI 스타일 OpenAI 설정을 루프백으로 (예시)
# export OPENAI_API_BASE="http://127.0.0.1:18789/v1"
# export OPENAI_API_KEY="$(tr -d '\n' < ~/.openclaw/dashboard.token)"예산과 서킷 브레이커 파라미터
| 파라미터 | 시작값 | 의미 |
|---|---|---|
| 동시 도구 호출 | M4급 호스트에서 4–8 | 크루가 팬아웃될 때 FD·업스트림 RPM 폭주 방지 |
| 게이트웨이 RPM 상한 | LiteLLM 테넌트 예산에서 여유 제외 | CrewAI max_iter가 공급자 스로틀과 충돌하지 않게 |
| 브레이커 오류 비율 | 30초 창에서 오류 50% 시 개방 | 오염된 라우트가 건강한 별칭을 잡아먹지 않게 |
| 쿨다운 | 45–90초 | 업스트림이 회복되기 전 에이전트 재시도 난사 차단 |
- 토큰 회계:
tenant_id·crew_id를 게이트웨이에 붙여 비용 대조. - 지연: 연결 ~2초, 완성 읽기 ~30초, 도구 읽기(비스트림) ~8초.
- 재시도:
429·연결만 백오프;401·413는 자동 재시도 금지.
일반적인 오류
- 에이전트 전역 401 루프. 대시보드 토큰 만료 또는 잘못된 경로 export입니다. 토큰을 갱신하고 워커를 재시작한 뒤, 크루와 동일 베어러로 curl을 검증합니다.
- 브레이커 깜빡임. CrewAI 재시도가 게이트웨이 트래픽을 증폭합니다. 브레이커가 열려 있을 때는 클라이언트 재시도를 줄이고 실패 봉투를 노출합니다.
- 별칭 없음. LiteLLM과 매니페스트 간 모델명이 어긋납니다. 설정을 리로드하고 로그에서 대소문자 불일치를 grep하며, 별칭은 점검 창에 올립니다.
- 조용한 비용 급증. 동시성 무제한이 TPM을 곱했습니다. 세마포를 조이고 활성 에이전트를 줄이며 라우트별 사용 로그를 확인합니다.
FAQ
에이전트가 OpenClaw를 건너뛰고 LiteLLM만 직접 호출해도 되나요? 기술적으로는 가능하지만 감사·스키마 게이트·일관된 요약이 사라집니다. 게이트웨이 스택이 있는 루프백만 쓰세요.
여러 크루에 예산을 나누려면? 프로세스 전역 세마포 하나와 게이트웨이 테넌트 하나를 쓰고, 크루는 메타데이터 라벨로만 구분합니다. 마스터 키를 쪼개지 마세요.
실패 후 사용자에게 보여줄 문장에는 무엇이 들어가나요? hint·상관 ID·축소된 기능 설명만 인용하고, 원문 공급자 페이로드와 프롬프트는 빼세요.