Caveman 게이트웨이 설정

이 리포지토리를 Caveman 게이트웨이에 연결합니다. Caveman은 바이트 보존형 LLM 프록시입니다. 기록 모드에서는 앱이 전송하는 내용과 비용을 측정하며, 그 외에는 아무것도 변경하지 않습니다. 당신의 작업은 최소한의 검증된 통합입니다. 리팩터링이 아닙니다.

이 프롬프트를 보낸 사람이 다음 네 가지 값을 제공합니다. 다음과 같이 참조하세요:

• GATEWAY — 게이트웨이 기본 URL (예: https://gateway.caveman.so 또는 http://127.0.0.1:8787)
• CAVE_API_KEY — 게이트웨이 인증 시크릿 (API 키처럼 취급: 환경 변수로만, 절대 커밋하지 않고, 전체를 출력하지 않음)
• PROVIDER_KEYS — stored (제공자 키는 Caveman Cloud에 암호화되어 저장됨) 또는 byok (이 앱이 요청마다 자체 제공자 키를 전송)
• DASHBOARD — 대시보드 기본 URL (예: https://app.caveman.so)

값이 하나라도 누락되면 중단하고 요청하세요. URL을 추측하거나 키를 생성하지 마세요.

규칙 (비협상)

1. 일관된 통합. 모든 라이브 LLM 호출 지점을 기존 구성과 책임 있는 연결 지점을 통해 연결합니다. 정확성을 위해 필요한 각 계층을 건드립니다. 무분별한 리팩터링이나 포맷팅 정리는 하지 않으며, 소유권을 명확히 하거나 수명 주기 비용을 낮출 때만 추상화를 추가합니다.
2. 시크릿은 환경 변수에만. CAVE_API_KEY는 리포지토리가 이미 사용하는 환경 파일(.env, .env.local, ...)에 넣습니다. 해당 파일이 gitignore되어 있지 않으면 .gitignore에 추가하고 명시합니다. 절대로 키를 소스 코드에 하드코딩하지 마세요.
3. 실제 관찰한 것만 보고. 최종 보고서에는 실제 검증 응답의 HTTP 상태와 사용량 숫자만 표시하며, 절대 성공을 가정하지 않습니다. 검증이 실패하면 해당 실패 템플릿을 대신 보고합니다.
4. 기록 모드만. 측정을 추가하는 것입니다. 최적화를 활성화하지 않으며, 비용 절감을 주장하지 않습니다. 검증된 비용 절감은 $0입니다. 최적화 도구가 명시적으로 켜지고 평가 게이트를 통과할 때까지입니다.
5. 제공자 키는 당신의 관심사가 아닙니다. PROVIDER_KEYS: stored에서는 제공자 키를 절대 볼 수 없습니다. byok의 경우, 앱의 기존 제공자 키는 그대로 유지됩니다.

1단계 — 모든 라이브 LLM 호출 지점 찾기

의존성 파일(package.json, requirements.txt, pyproject.toml, go.mod, lockfiles)을 읽고 소스에서 LLM 클라이언트를 검색합니다:

• SDK 임포트: openai, @anthropic-ai/sdk, anthropic, ai + @ai-sdk/* (Vercel), langchain*, litellm, google-genai / @google/genai, crewai, pydantic_ai, openai-agents / agents
• api.openai.com, api.anthropic.com, generativelanguage.googleapis.com에 대한 원시 HTTP 호출
• 기존 기본 URL 환경 변수: OPENAI_BASE_URL, OPENAI_API_BASE, ANTHROPIC_BASE_URL, GEMINI_BASE_URL, GOOGLE_GEMINI_BASE_URL

찾은 내용을 변경하기 전에 나열하세요 (파일:줄 위치). LLM 호출 지점을 찾지 못하면 중단하고 이 파일 끝에 있는 "연결할 것이 없음" 템플릿을 보고하세요. 통합을 임의로 만들지 마세요.

2단계 — 앱 슬러그 선택

한 개의 슬러그가 게이트웨이 경로에서 이 앱을 식별합니다: GATEWAY/w/<app>. 패키지/모듈 이름에서 파생하세요 (예: support-bot, acme-api). 문법: 처음은 소문자 [a-z0-9], 그 다음은 [a-z0-9._-], 최대 64자. 이 앱의 모든 지출은 대시보드에서 해당 슬러그 아래 그룹화됩니다.

3단계 — 각 호출 지점 연결

패턴은 항상 동일합니다: 기본 URL → /w/<app>가 포함된 게이트웨이, 그리고 하나의 인증 헤더. 게이트웨이 인증은 x-cave-api-key: CAVE_API_KEY입니다 (Authorization: Bearer CAVE_API_KEY도 헤더가 불편한 경우 작동합니다). PROVIDER_KEYS: byok의 경우 x-cave-upstream-key: <앱이 이미 사용하는 제공자 키>도 보냅니다.

연결을 안전하게 만드는 두 가지 사실(둘 다 게이트웨이에서 강제하며, 희망 사항이 아님): 게이트웨이는 업스트림 인증 헤더를 처음부터 다시 빌드하므로 클라이언트의 Authorization/x-api-key 값이 제공자에게 전달되지 않습니다. stored 모드에서는 업스트림 인증이 서버 측에서 암호화된 연결에서 제공됩니다. 따라서 stored 모드에서 SDK가 api-key 매개변수를 요구하는 경우, Cave 키로 설정하세요. 게이트웨이를 인증하고 그 이상 전달되지 않습니다.

정확한 형태 (각 호출 지점에 맞는 것을 사용하세요 — 이는 제품의 공개된 레시피이며 제안이 아닙니다):

OpenAI SDK (TS) — 채팅 완성(Chat Completions)과 응답(Responses) 모두 다음을 통해 라우팅:

const client = new OpenAI({
  baseURL: `${process.env.CAVE_GATEWAY_URL}/w/<app>/openai/v1`,
  apiKey: process.env.OPENAI_API_KEY,           // byok: 변경 없음 · stored: CAVE_API_KEY 사용
  defaultHeaders: {
    "x-cave-api-key": process.env.CAVE_API_KEY!,
    // byok 전용:
    "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
  },
});

OpenAI SDK (Python) — 동일한 형태: base_url=f"{gw}/w/<app>/openai/v1", default_headers={"x-cave-api-key": ..., "x-cave-upstream-key": ...}.

Anthropic SDK (TS/Python) — SDK가 자체적으로 /v1/messages를 추가합니다. x-cave-api-key 헤더는 두 모드 모두에서 필수입니다 (이 SDK의 자체 키 매개변수는 x-api-key를 사용하며, 이는 게이트웨이 인증 헤더가 아닙니다):

client = anthropic.Anthropic(
    base_url=f"{os.environ['CAVE_GATEWAY_URL']}/w/<app>",
    api_key=os.environ["ANTHROPIC_API_KEY"],      # byok: 변경 없음 · stored: CAVE_API_KEY 사용
    default_headers={
        "x-cave-api-key": os.environ["CAVE_API_KEY"],
        # byok 전용:
        "x-cave-upstream-key": os.environ["ANTHROPIC_API_KEY"],
    },
)

Vercel AI SDK — createOpenAICompatible({ baseURL: ${gw}/w//openai/v1, headers: { "x-cave-api-key": ... } }); Anthropic 모델은 createAnthropic({ baseURL: ${gw}/w//v1, headers: { ... } })를 통해.

LangChain / LangGraph — ChatOpenAI(base_url=f"{gw}/w/<app>/openai/v1", default_headers={...}); ChatAnthropic(base_url=f"{gw}/w/<app>", default_headers={...}). LangGraph는 전달된 모델을 그대로 상속합니다.

LiteLLM — 호출별로 api_base=f"{gw}/w/<app>/openai/v1" + extra_headers={...}, 또는 LiteLLM 프록시 config.yaml에서 전체 플릿에 적용.

원시 HTTP / 기타 — 호스트를 교체하고 제공자의 기본 경로를 유지: GATEWAY/w/<app>/v1/chat/completions (OpenAI 프로토콜) 또는 GATEWAY/w/<app>/v1/messages (Anthropic 프로토콜), 헤더를 추가합니다.

구체적으로, 슬러그가 support-bot이고 호스팅된 게이트웨이인 경우, OpenAI SDK 기본 URL은 https://gateway.caveman.so/w/support-bot/openai/v1입니다. 그리고 stored 모드에서는 x-cave-upstream-key 줄을 완전히 제거하세요. byok 전용입니다.

나열되지 않은 프레임워크(google-genai, crewai, pydantic-ai, openai-agents)의 경우, <docs origin>/docs/integrations/에서 해당 페이지를 가져오세요. 동일한 출처에서 이 스킬이 왔으며, 따라 하세요.

리포지토리의 환경 파일에 추가 (그리고 코드에서 참조 — 리터럴 사용 금지):

CAVE_GATEWAY_URL=<GATEWAY>
CAVE_API_KEY=<CAVE_API_KEY>

4단계 — 하나의 실제 요청으로 검증

사용자가 설정 프롬프트를 붙여넣어 정확히 이 작업을 승인했습니다: 하나의 작은 검증 요청. 지금 보내세요. 허가를 구하기 위해 멈추지 마세요. 망설여서 검증되지 않은 통합은 작은 요청 하나보다 더 나쁜 결과입니다. 검증과 보고를 자율적으로 완료하는 것이 이 스킬의 목적입니다.

방금 구축한 연결을 통해 하나의 최소 요청을 보내세요. 앱에 그에 맞는 스크립트가 있다면 앱 자체의 가장 저렴한 경로를 사용하고, 그렇지 않으면 방금 연결한 프로토콜과 일치하는 경로에 curl을 사용하고 앱 자체 모델과 작은 제한(max_tokens ≤ 32)을 사용하세요:

# OpenAI 프로토콜 연결:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/chat/completions" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"<리포지토리가 이미 사용하는 모델>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# Anthropic 프로토콜 연결:
curl -sS "$CAVE_GATEWAY_URL/w/<app>/v1/messages" \
  -H "x-cave-api-key: $CAVE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"<리포지토리가 이미 사용하는 모델>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

(byok: -H "x-cave-upstream-key: $PROVIDER_KEY"를 추가하세요.) 이것은 실제 청구 가능한 제공자 요청입니다. 그것이 요점입니다: 실제 트래픽, 실제 측정.

응답을 읽으세요. 성공 = usage 블록이 있는 HTTP 200. 그 외 = 아래 일치하는 실패 템플릿.

5단계 — 보고

실제로 수행하고 본 내용으로 채워진 다음 모양으로 정확히 끝내세요:

## Caveman이 이 리포지토리에서 활성화됨

연결됨: <n>개 파일에서 <n>개 호출 지점
  - <파일> — <한 줄 변경 사항>
앱 슬러그: <app> — 이 앱의 지출은 이 아래 그룹화됨
검증됨: HTTP 200 · 모델 <model> · <in> 입력 / <out> 출력 토큰 (하나의 실제 요청)
모드: 기록 — 측정만 함. 모델에 표시되는 바이트 변경 없음, 최적화 비활성화.
최적화 도구를 켜고 평가 게이트를 통과할 때까지 검증된 비용 절감액은 $0입니다. 그 정직함이 제품입니다.

달러 확인: <DASHBOARD>/traces — 귀하의 요청이 최상위 행이며, 공개 카탈로그에서 가격이 책정됩니다. <DASHBOARD>/getting-started가 "첫 번째 요청 수신됨"으로 전환됩니다.

워크플로우별로 지출을 나누고 싶으세요(예: support-reply 대 nightly-digest), 앱별로만 나누는 것이 아닌가요? "워크플로우 검색"이라고 말씀하세요 — <docs origin>/docs/discover-workflows.md를 가져와 각 호출 지점을 수행하는 작업별로 레이블을 지정하겠습니다.

실패 템플릿 (그대로 사용, 채워 넣고 — 절대 부드럽게 하지 마세요)

• 연결할 것이 없음: "이 리포지토리에서 LLM 호출 지점을 찾지 못했습니다 (SDK, 원시 제공자 HTTP, 기본 URL 환경 변수 검색). 이 리포지토리가 LLM 코드를 제공하기보다 코딩 에이전트를 실행하는 경우, 대신 caveman wrap <agent>를 사용하세요 — /getting-started를 참조하세요."
• 게이트웨이에 연결할 수 없음: "검증 요청이 GATEWAY에 도달할 수 없습니다 (). 연결은 설정되었지만 검증되지 않았습니다 — 게이트웨이에 연결할 수 있을 때까지 아무것도 측정되지 않습니다. URL과 네트워크를 확인한 다음 위의 검증 curl을 다시 실행하세요."
• 401 cave_invalid_api_key: "게이트웨이가 CAVE_API_KEY를 거부했습니다. /getting-started에서 새 키를 발급하고 환경 파일을 업데이트하세요. 연결 자체는 변경되지 않았습니다."
• 404 cave_route_not_found: "게이트웨이가 일치하는 경로를 찾지 못했습니다 — 일반적으로 /w/ 슬러그 형식 오류 (처음은 소문자 [a-z0-9], 그 다음은 [a-z0-9._-], 최대 64자) 또는 SDK의 프로토콜과 일치하지 않는 경로입니다. URL을 수정하고 다시 검증하세요."
• 제공자 오류 (게이트웨이를 통한 4xx/5xx): 상태 + 본문을 그대로 보고합니다. 게이트웨이는 연결 가능하고 인증은 통과했으며, 업스트림 호출이 실패했습니다 — 일반적으로 앱 자체의 제공자 키 또는 모델 이름 문제입니다.

이러한 경우 절대 성공을 보고하지 마세요. 검증되지 않은 통합은 검증되지 않은 것으로 보고됩니다.