관리자추론 훅

Inference hooks 구성

Copy page



Claude Enterprise 조직에 Inference hooks를 허용하고, AI 보안 서버를 연결하며, 적용, 실패 처리 및 롤아웃을 제어합니다.

Inference hooks는 조직의 프롬프트를 사용자가 선택한 AI 보안 서버로 전송하고, Claude가 각 요청을 처리하기 전에 허용 또는 거부 "verdict"(판정)를 받을 때까지 요청을 보류합니다. 이 페이지에서는 기능을 켜고, 서버를 연결하고, 적용을 제어하는 과정을 안내합니다. Inference hooks가 무엇이며 언제 사용하는지 알아보려면 Inference hooks 개요를 참조하세요. AI 보안 서버 자체를 구축하려면 Inference hooks 통합 개발을 참조하세요.

시작하기 전에

다음이 필요합니다:

• claude.ai의 organization:manage 권한. 기본 제공되는 Admin, Owner, Primary owner 역할과 이 권한이 부여된 모든 사용자 지정 역할이 이 권한을 보유합니다.
• 판정 요청을 수락하는 AI 보안 서버 HTTPS 엔드포인트: 공개적으로 라우팅 가능한 호스트의 포트 443에 있는 https:// URL이며, 리디렉션 없이 도달 가능해야 합니다. 리버스 터널 호스트(ngrok 및 유사한 터널 서비스)는 지원되지 않습니다. Anthropic의 네트워크 정책이 이를 차단합니다. 터널을 통해 테스트하지 마세요. 직접 제어하는 도메인에서 서버를 호스팅하세요. 전체 호스팅 요구 사항을 확인하고 서버를 구축하여 서명된 요청을 검증하려면 Inference hooks 통합 개발을 참조하세요.

Inference hooks 설정

적용 상태에는 세 가지가 있습니다: 꺼짐(Enforce verdicts가 꺼져 있음: AI 보안 서버에 전혀 연결하지 않으며 프롬프트가 검사되지 않음), 섀도(Enforce verdicts가 켜져 있고 Mode가 Shadow mode로 설정됨: AI 보안 서버가 프롬프트를 수신하고 판정을 반환하지만 아무것도 차단되지 않음), 적용 중(Enforce verdicts가 켜져 있고 Mode가 Allow the request 또는 Block the request로 설정됨: 거부 판정이 요청을 차단함). 다음 단계는 새 구성을 꺼짐 상태에서 적용 중 상태로 전환합니다.

1. 1

   조직에 Inference hooks 허용

   claude.ai > Organization settings > Data and privacy로 이동하여 Inference hooks 섹션을 찾으세요. Allow for your organization을 켜세요.

   이 설정을 켜면 Inference hooks 설정 페이지가 잠금 해제되며 항상 Enforce verdicts가 강제로 꺼지므로, 기능을 허용하는 것만으로는 검사가 시작되지 않습니다. 이전에 적용이 켜져 있던 구성이라도 마지막 단계에서 Enforce verdicts를 다시 켤 때까지 검사되지 않은 상태로 유지됩니다.

2. 2

   Inference hooks 설정 페이지 열기

   Data and privacy에 머무른 채로 Inference hooks 섹션을 열어 Inference hooks 설정 페이지로 이동하세요. 이 페이지는 설정 탐색 메뉴의 독립 항목이 아니라 Data and privacy 아래에 있으므로 브레드크럼은 Data and privacy / Inference hooks로 표시됩니다. 엔드포인트를 저장하기 전까지 페이지에는 프롬프트가 아직 검사되지 않고 있다는 경고가 표시되며, Enforce verdicts는 Requires endpoint 배지와 함께 꺼진 상태로 유지됩니다.

3. 3

   엔드포인트 구성

   Configure를 클릭하여 Configure endpoint 대화 상자를 열고 다음을 입력하세요:

   • Endpoint URL: 판정 요청을 수신하는 https:// URL. https:// URL만 허용됩니다.
   • Custom request headers: AI 보안 서버가 호출자를 인증할 수 있도록 모든 판정 요청과 함께 전송되는 최대 16개의 정적 헤더. 헤더 값은 암호화되어 저장되며 다시 표시되지 않습니다. 저장 후에는 헤더 이름만 표시됩니다. 값은 쓰기 전용이므로 헤더에 대한 변경 사항을 저장하려면 모든 값을 다시 입력해야 합니다. 엔드포인트 URL을 변경하면 자격 증명이 새 대상으로 전송되지 않도록 저장된 모든 헤더 값이 지워지므로, URL 변경 후 다시 입력하세요. 헤더 이름은 _ 대신 -를 사용하는 표준 HTTP 토큰 문자를 사용해야 하며, 예약된 이름(Content-* 및 Host와 같은 요청 프레이밍 헤더, 프록시 및 쿠키 헤더, X-Forwarded-*와 같은 클라이언트 주소 헤더, webhook-* 서명 헤더, X-Anthropic-* 접두사)과 충돌해서는 안 됩니다. 값은 출력 가능한 ASCII여야 합니다.

   대화 상자는 이 두 필드와 Test connection만 다룹니다. 실패 처리에 대해서는 묻지 않으며, 이는 6단계에서 선택합니다. 엔드포인트가 저장되면 버튼은 Edit으로 표시됩니다.

4. 4

   연결 테스트

   Test connection을 클릭하세요. Claude는 저장된 값이 아니라 현재 양식에 있는 URL과 헤더로 합성 테스트 프롬프트를 전송하므로, 테스트 전에 저장된 헤더 값을 다시 입력하세요. 성공하면 결과에 AI 보안 서버가 테스트 프롬프트에 대해 허용 또는 거부 판정을 반환했는지가 보고되며, 이를 통해 적용을 시작하기 전에 모든 것을 거부하는 기본값을 발견할 수 있습니다.

   일반적인 실패 결과:

   결과	확인할 사항
   URL 거부됨	URL이 구조 검사에 실패했습니다. 포트 443의 https:// URL을 사용하세요.
   사설 또는 내부 IP	호스트가 사설 또는 내부 주소로 확인됩니다. 공개적으로 라우팅 가능한 호스트를 사용하세요.
   시간 초과	AI 보안 서버가 제한 시간 내에 판정을 반환하지 않았습니다.
   전송 오류	DNS 확인, TLS 핸드셰이크 또는 연결이 실패했습니다.
   200이 아닌 상태	AI 보안 서버가 200이 아닌 상태로 응답했습니다. 판정은 HTTP 200으로 반환되어야 합니다. 리디렉션은 따르지 않으며 실패로 간주됩니다.
   구문 분석할 수 없는 응답	AI 보안 서버가 응답했지만 본문이 유효한 판정이 아닙니다.

5. 5

   저장 및 서명 시크릿 보관

   엔드포인트 구성을 저장하세요. 첫 번째 저장 시 웹훅 서명 시크릿이 생성되어 한 번만 표시됩니다. 대화 상자를 닫기 전에 복사하여 안전하게 보관하세요. 시크릿은 나중에 다시 조회할 수 없으며 교체만 가능합니다.

   AI 보안 서버는 이 시크릿을 사용하여 수신하는 모든 요청의 서명을 검증합니다. 검증 절차는 서명 검증을 참조하세요.

6. 6

   실패 처리 및 제한 시간 선택

   Failure handling 아래에서 Mode를 설정하여 AI 보안 서버에 도달할 수 없거나 판정이 시간 초과될 때 어떻게 할지 선택하세요:

   • Block the request: AI 보안 서버가 판정을 전달할 수 없을 때 추론을 중지합니다(fail closed).
   • Allow the request: 검사 없이 요청이 모델로 진행되도록 합니다(fail open).

   드롭다운의 세 번째 옵션인 Shadow mode는 실패 정책이 아니라 롤아웃 도구입니다. 섀도 모드를 참조하세요.

   그런 다음 **Prompt verdict timeout (ms)**를 설정하세요: 1~10,000ms이며 기본값은 5,000ms입니다. 이 예산은 전체 교환 과정을 포함하며, 더 느린 판정은 도달할 수 없는 서버로 간주되므로 서버가 안정적으로 충족할 수 있는 가장 낮은 값을 설정하세요.

   이 섹션의 변경 사항은 변경하는 즉시 저장됩니다. 첫 번째 저장 시 기본값은 Allow the request와 5,000ms입니다.

7. 7

   롤아웃 비율 선택

   Rollout 아래에서 **Requests inspected (%)**를 설정하여 AI 보안 서버를 가동하는 동안 일정 비율의 요청에 대해 검사를 실행하세요. 값의 범위는 0~100입니다. 100은 모든 것을 검사하고 0은 검사를 끕니다.

   각 요청은 전체 대화 턴에 대해 한 번 추첨되므로, 단일 대화가 턴에 따라 부분적으로 검사될 수 있습니다. 샘플링된 비율 밖의 요청은 실패 처리가 Block the request로 설정되어 있어도 검사 없이 진행됩니다.

8. 8

   Enforce verdicts 켜기

   처음에는 아무도 차단하지 않고 실제 트래픽에 대해 판정을 평가하려면 적용을 켜기 전에 Mode를 Shadow mode로 설정하세요(6단계). 섀도 모드를 참조하세요.

   Enforce verdicts를 켜서 관리 대상인 모든 프롬프트에 대해 AI 보안 서버의 판정으로 Claude를 게이팅한 다음, 실패 처리 선택 사항을 다시 보여주는 대화 상자에서 확인하세요. 변경 사항이 모든 Anthropic 서버에 도달하는 데 약 1분 정도 걸립니다. 이미 진행 중인 요청은 이전 설정에 따라 완료됩니다. 이 설정을 끄면 역시 약 1분 이내에 프롬프트가 AI 보안 서버로 전송되지 않으며, 구성은 유지됩니다.

섀도 모드

섀도 모드는 아무것도 차단하지 않고 실제 트래픽에 대해 훅을 실행합니다. AI 보안 서버는 적용 중일 때와 정확히 동일하게 관리 대상 프롬프트를 수신하고 판정을 반환하지만 아무것도 차단되지 않습니다. 서버가 거부하거나 서버에 도달할 수 없는 경우에도 모든 요청이 모델로 진행되며, 최종 사용자에게는 아무것도 표시되지 않습니다. 적용을 시작하기 전에 조직의 실제 트래픽에 대해 정책을 조정하는 데 사용하세요.

섀도 모드를 사용하려면 Failure handling 아래에서 Mode를 Shadow mode로 설정한 다음, 프롬프트가 AI 보안 서버로 흐르도록 Enforce verdicts를 켜세요. 활성화되어 있는 동안 설정 페이지에는 Shadow mode — not blocking 배지가 표시됩니다. 섀도 모드를 종료하려면 Mode를 다시 Allow the request 또는 Block the request로 설정하세요. 적용이 켜져 있으면 판정이 다시 적용됩니다.

제외

Exclusions 아래에서 Inference hooks의 적용을 받지 않는 구성원의 역할을 선택하세요. 해당 구성원의 프롬프트는 AI 보안 서버로 전송되지 않습니다. 조직에서 생성한 사용자 지정 역할만 제외할 수 있으며, 기본 제공 역할은 제공되지 않습니다. 플레이스홀더가 Select roles to exclude로 표시되는 역할 선택기에서 역할을 선택하고, 역할 관리 페이지(Manage roles)에서 각 역할을 보유한 사람을 관리하세요. 제외를 변경하려면 ID 관리 권한이 필요합니다. 목록은 기본적으로 비어 있으며, 제외된 역할이 없으면 모든 관리 대상 요청이 검사됩니다.

제외는 사용자의 대화형 세션에 적용됩니다. 머신 자격 증명으로 인증된 트래픽은 항상 검사됩니다. Claude가 요청자의 역할 멤버십을 확인할 수 없는 경우, 요청은 검사 없이 진행되는 대신 재시도 가능한 오류와 함께 fail closed 처리됩니다. 제외 목록의 변경 사항은 감사 추적에 기록됩니다.

사용자 지정 차단 프롬프트 메시지

Custom blocked prompt message 아래에서 AI 보안 서버가 요청을 거부할 때 최종 사용자에게 표시되는 오류에 추가되는 최대 500자의 사용자 지정 텍스트를 설정하세요(일반적으로 문의할 담당자 또는 예외를 요청할 곳). 최종 메시지는 AI 보안 서버의 요청별 deny_reason(있는 경우), 빈 줄, 그리고 이 텍스트로 구성됩니다. 사용자 지정 텍스트가 구성되지 않은 경우 기본 제공 메시지가 사용자에게 관리자에게 문의하도록 안내합니다. 추가 메시지를 완전히 꺼서 사용자에게 deny_reason만 표시되도록 할 수도 있습니다.

AI 보안 서버 모니터링

Inference hooks 설정 페이지의 엔드포인트 상태 영역에는 다음이 표시됩니다:

• Endpoint status: Healthy, Tripped, Not enforcing 또는 엔드포인트가 저장되기 전에는 Not configured.
• Failures per minute: 지난 2분 동안의 웹훅 실패 평균.
• Block rate: AI 보안 서버의 판정 중 거부 비율로, 롤아웃 비율이 100 미만일 때 표시됩니다.
• Circuit breaker tripped: 서킷 브레이커가 마지막으로 작동한 시점(작동한 적이 있는 경우).
• Recent errors: 각 항목은 타임스탬프, 오류 유형, 한 줄 사유로 축약됩니다. 항목에는 요청 내용이나 엔드포인트 URL이 포함되지 않습니다.

이 패널은 최선 노력(best-effort) 방식입니다. Anthropic이 카운터를 읽을 수 없는 경우 자체 오류 대신 실패 0건과 오류 없음을 표시하므로, 정상으로 보이는 패널 자체가 AI 보안 서버가 정상이라는 증거는 아닙니다. Failures per minute는 서킷 브레이커를 작동시키지 않는 네트워크 및 DNS 오류를 포함한 모든 실패를 집계하므로, Circuit breaker tripped가 비어 있는 동안에도 높을 수 있습니다.

서킷 브레이커

AI 보안 서버에 기인하는 지속적인 웹훅 실패는 "circuit breaker"(서킷 브레이커)를 작동시켜 적용을 중지합니다. 서버에 더 이상 연결하지 않으며, Failure handling 선택 사항이 검사 대상인 모든 요청에 적용됩니다. Block the request가 선택된 경우 브레이커가 재설정될 때까지 조직의 사용자가 차단됩니다. 브레이커가 작동하면 관리자에게도 claude.ai 알림 센터에서 알림이 전송됩니다.

각 작동은 조직의 Activity Feed에도 inference_hooks_circuit_breaker_tripped 활동으로 기록되므로, 보안 팀이나 벤더가 피드를 수집하는 SIEM과 같이 이미 운영 중인 모니터링에서 작동에 대한 경보를 설정할 수 있습니다. 영향을 받은 요청당 하나가 아니라 작동당 하나의 활동이 기록됩니다. 기록하려면 조직에 Compliance API가 활성화되어 있어야 합니다. Compliance API 설정을 참조하세요.

복구하려면 서버를 수정한 다음 Enforce verdicts를 다시 켜서 브레이커를 재설정하세요.

브레이커는 자체적으로 재설정될 수도 있습니다. 작동 후 10분부터 Anthropic은 서버가 복구되었는지 테스트합니다. 최대 약 1분에 한 번, 조직의 일반 트래픽에서 하나의 요청이 검사를 위해 서버로 전송되며, 해당 요청은 서버의 응답 여부와 관계없이 사용자를 위해 진행됩니다. 서버가 허용이든 거부든 유효한 판정으로 응답하면 브레이커가 재설정되고 적용이 재개됩니다. 그 외의 결과는 웹훅 실패입니다. 브레이커는 작동 상태로 유지되고 테스트가 계속됩니다.

자동 복구는 작동 이후 Inference hooks 설정이 변경되지 않은 동안에만 실행됩니다. 작동 후 서명 시크릿 교체를 포함하여 Inference hooks 설정을 변경하면 테스트가 중지되고 브레이커가 더 이상 자체적으로 재설정되지 않습니다. 서버가 수정되면 Enforce verdicts를 다시 켜세요. 자동 복구는 작동에만 적용됩니다. Enforce verdicts를 직접 끈 경우 다시 켤 때까지 적용은 꺼진 상태로 유지됩니다.

서명 시크릿 교체

Request signing 아래의 Rotate secret을 클릭하여 서명 시크릿을 교체하세요. 교체는 즉시 전환됩니다. 새 시크릿이 생성되어 한 번만 표시되고, 이전 시크릿은 더 이상 조회할 수 없으며, 어떤 요청도 두 시크릿으로 동시에 서명되지 않으므로 의존할 수 있는 중복 기간이 없습니다.

이전 시크릿으로 서명된 요청이 교체 후 잠시 동안 도착할 수 있습니다. AI 보안 서버가 전환을 처리하는 방법은 서명 검증에서 다룹니다.

감사 추적

Inference hooks 활동은 조직의 Activity Feed에 기록됩니다. 구성 변경, 거부, 서킷 브레이커 작동, 실패 처리 설정에 따라 검사 없이 진행된 요청이 포함됩니다. 서킷 브레이커가 작동한 동안에는 요청별 Inference hooks 활동이 기록되지 않으며, 작동 활동이 해당 기간에 대한 피드의 기록입니다. 거부 기록에는 각 거부를 자체 시스템의 일치하는 기록과 연결할 수 있는 식별자가 포함됩니다.

Inference hooks 끄기

끄기에는 두 가지 수준이 있습니다:

• Inference hooks 설정 페이지에서 Enforce verdicts 끄기: 약 1분 이내에 조직의 프롬프트가 AI 보안 서버로 전송되지 않습니다. 이미 진행 중인 요청은 이전 설정에 따라 완료됩니다. 설정 페이지는 계속 사용할 수 있으므로 AI 보안 서버 작업 중 적용을 일시 중지하는 데 사용하세요.
• Data and privacy 설정에서 Allow for your organization 끄기: 프롬프트가 더 이상 검사되지 않으며, 다시 켤 때까지 Inference hooks 설정을 사용할 수 없게 됩니다. 어느 경우든 엔드포인트 구성, 사용자 지정 헤더, 서명 시크릿은 유지됩니다. 다시 켜면 Enforce verdicts가 강제로 꺼지고 작동한 서킷 브레이커가 해제되므로, 준비가 되면 적용을 다시 켜세요.

다음 단계