카탈로그는 100개 이상의 서비스를 다루지만, 모든 팀에는 목록에 없는 내부 도구나 지역 SaaS 제품이 몇 개씩 있습니다. 커스텀 커넥터가 그것을 해결합니다.
자격 증명 — API 키나 OAuth 자격 증명 — 을 등록하고 Zero에게 그 서비스를 어떻게 호출할지 알려줍니다. 그때부터 Zero는 커스텀 커넥터를 기본 제공 커넥터와 동일하게 다룹니다: 같은 감사 로그, 같은 중개 접근 프록시, 같은 민감 동작 게이트.
두 가지 유형
서비스에 맞는 유형을 고르세요.
- API 키 — 헤더에 정적 토큰으로 인증하는 모든 서비스에 적용됩니다. 가장 간단하고 빠른 경로입니다: 키를 붙여넣고, 커넥터 이름을 정하고, Zero에게 기본 URL을 알려주면 됩니다. 대부분의 내부 API와 많은 SaaS 도구가 이 방식을 씁니다.
- OAuth 2.0 — OAuth를 통해 사용자별 토큰을 발급하는 서비스용입니다. 클라이언트 ID와 시크릿을 제공하고, Zero가 요청할 수 있는 스코프를 구성하면, 필요할 때 Zero가 사용자별로 OAuth 절차를 수행합니다.
어느 것을 써야 할지 확실하지 않다면 상위 서비스의 API 문서를 확인하세요. "API key"(또는 "personal access token")라는 단어는 보통 유형 1을 뜻하고, "OAuth"(또는 "client credentials")는 보통 유형 2를 뜻합니다.
API 키 커넥터 설정하기
- 워크스페이스에서 Connectors 페이지를 엽니다.
- Add custom connector → API key를 클릭합니다.
- 다음을 입력합니다:
- Name. Zero가 프롬프트를 읽을 때 알아볼 수 있는 이름, 예:
internal-billing-api또는acme-crm. - Base URL. API의 루트:
https://api.internal.acme.com. - Auth header. 보통
Authorization: Bearer YOUR_TOKEN또는X-API-Key: YOUR_TOKEN. 서비스가 기대하는 형식에 맞추세요. - API key. 자격 증명을 붙여넣습니다. 암호화되어 저장되며 저장 후에는 절대 다시 표시되지 않습니다.
- Allowed paths (선택). Zero를 특정 엔드포인트로 제한합니다, 예:
/v1/invoices/*. 영향 범위를 줄입니다.
- Name. Zero가 프롬프트를 읽을 때 알아볼 수 있는 이름, 예:
- Save와 Test connection을 클릭합니다. Zero가 기본 URL에
GET /(또는 지정한 경로)로 핑을 보내고 응답을 보고합니다.
OAuth 2.0 커넥터 설정하기
조금 더 손이 가지만, 사용자별 인가가 중요한 서비스라면 그만한 가치가 있습니다.
- 상위 서비스에 OAuth 애플리케이션을 등록합니다. 클라이언트 ID와 클라이언트 시크릿을 받게 됩니다. 리디렉션 URI는 커넥터 추가 폼에 VM0가 표시하는 값으로 설정하세요.
- VM0에서: Add custom connector → OAuth 2.0.
- 다음을 입력합니다:
- 위와 같이 Name과 Base URL
- 상위 서비스의 OAuth 문서에서 가져온 Authorization URL과 Token URL
- Client ID와 Client secret
- Scopes. Zero가 요청할 수 있는 스코프 목록. 워크플로에 필요한 최소한만 사용하세요.
- 저장합니다. 이 커넥터가 필요한 첫 세션이 사용자별로 OAuth 흐름을 트리거합니다.
커스텀 커넥터 사용법을 Zero에게 알려주기
두 가지 방법이 있습니다. 워크플로에 맞는 쪽을 고르세요.
Zero에게 무언가를 요청할 때 인라인으로 설명하기:
"
internal-billing-api커넥터로 인보이스 #4422를 가져와. 그런 다음 PDF를 ops@acme.com으로 이메일 보내줘."
Zero는 커넥터 스펙을 불러와 어떤 엔드포인트를 호출할지 파악합니다. 커넥터에는 OpenAPI 스타일의 메타데이터가 함께 오기 때문에(많은 서비스는 자동 검색되며, 선택적으로 수동 제공 가능) 이것이 작동합니다.
이름으로 커넥터를 참조하는 스킬을 작성하기. 스킬 본문이 절차를 기술하고, 설명이 들어오는 요청과 일치하면 Zero가 자동으로 스킬을 불러옵니다. 반복되는 워크플로라면 매번 인라인으로 다시 설명하는 것보다 이 방식이 더 깔끔합니다.
"internal-billing-api에서 인보이스를 가져와 PDF를 이메일로 보내기" 라는 설명이 붙은
pull-invoice스킬 — 한 번 작성해 두면, 누군가 인보이스를 요청할 때마다 Zero가 이를 호출합니다.
OpenAPI 스펙과 인라인 스키마
Zero는 사용 가능한 엔드포인트, 메서드, 매개변수를 알 때 커스텀 커넥터를 가장 잘 다룹니다. 이를 제공하는 세 가지 방법이 있습니다.
- 자동 검색 — 서비스가
/openapi.json또는/swagger.json을 노출한다면 여기에서 검색합니다. Zero에게 URL만 알려주면 됩니다. - 스펙 업로드. OpenAPI 3 YAML/JSON을 붙여넣거나 업로드합니다. Zero가 이를 파싱하여 호출을 구성할 때 툴팁 형태의 메타데이터를 제공합니다.
- 인라인 설명. 스펙이 없는 내부 도구의 경우, 커넥터 본문에 짧은 마크다운 설명 — 엔드포인트, 메서드, 샘플 페이로드 — 을 작성할 수 있습니다. 조잡하지만 작동합니다.
스펙이 없어도 Zero는 여전히 작동합니다 — 다만 매개변수 형태를 더 많이 추측해야 합니다. 자주 쓰는 커스텀 커넥터라면 스펙이 금방 본전을 뽑아줍니다.
워크스페이스 간 공유
커스텀 커넥터는 기본적으로 워크스페이스 범위입니다. 같은 조직의 두 팀은 같은 내부 API에 대해 각자의 커스텀 커넥터를 유지할 수 있습니다. 하나의 표준 설정을 원하는 조직의 경우:
- 엔터프라이즈 조직 수준 커넥터. 엔터프라이즈 플랜에서 제공됩니다. 조직 수준에서 한 번 설정하면 그 조직 아래 모든 워크스페이스에 나타납니다. 모두가 사용하는 내부 API에 권장됩니다.
- 커넥터 패키지. 아주 큰 조직의 경우, 내부 플랫폼 팀이 커스텀 커넥터를 버전 관리되는 패키지로 게시할 수 있습니다. 워크스페이스는 이를 설치하고 업데이트를 자동으로 받습니다.
보안 및 속도 제한
- 자격 증명. 워크스페이스별 키로 저장 시 암호화됩니다. 저장 후에는 절대 표시되지 않으며 다시 입력만 가능합니다.
- 호출별 감사. 커스텀 커넥터를 통한 모든 요청은 메서드, URL, 상태 코드, 타이밍과 함께 세션 로그에 나타납니다.
- 속도 제한. 상위 서비스가 적용합니다. Zero는 429 응답을 워크스페이스에 구성된 한도까지 지수 백오프로 처리합니다.
- 허용 목록 경로. 선택 사항: Zero를 특정 URL 패턴으로 제한합니다. 커넥터 키가 과도한 권한을 가진 경우 영향 범위를 줄입니다.
- 기본값 읽기 전용. 새 커스텀 커넥터는 읽기 전용으로 표시됩니다. 쓰기 권한을 부여하려면 워크스페이스별로 명시적인 구성이 필요합니다.
흔한 함정
- 지나치게 광범위한 API 키. 서비스가 지원한다면 개인 관리자 키를 재사용하기보다 Zero용으로 범위가 제한된 키를 발급하세요. 교체와 감사가 더 쉽습니다.
- 누락된 스키마. OpenAPI 스펙이나 인라인 설명이 없으면 Zero는 매개변수 형태를 추측합니다. 간단한 경우에는 작동하지만 중첩된 객체에서는 깨집니다. 가능하면 스펙을 제공하세요.
- 테스트하지 않은 기본 URL. 설정 후에는 항상 Test connection을 클릭하세요. 이 단계에서의 401이나 404가 중요한 세션에서의 401보다 훨씬 낫습니다.
- 교체를 잊는 것. 키를 분기마다 교체하도록 캘린더 알림을 설정하세요. 커넥터 키 교체는 VM0에서 클릭 한 번입니다. 시간이 가장 많이 드는 것은 상위 서비스 쪽 교체입니다.