관리추론 훅

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 권한. 이 권한은 소유자 및 주 소유자 역할만 보유합니다. 관리자 역할에는 이 권한이 없습니다.
• 판정 요청을 수락하는 AI 보안 서버 HTTPS 엔드포인트: 공개적으로 라우팅 가능한 호스트의 443 포트에 있고, 리디렉션 없이 접근할 수 있는 https:// URL이어야 합니다. 리버스 터널 호스트(ngrok 및 유사한 터널 서비스)는 지원되지 않습니다. Anthropic의 네트워크 정책이 이를 차단합니다. 터널을 통해 테스트하지 말고, 직접 관리하는 도메인에서 서버를 호스팅하세요. 전체 호스팅 요구 사항과 서버 구축 및 서명된 요청 검증 방법은 Inference hooks 통합 개발을 참조하세요.

Inference hooks 설정

적용 상태에는 세 가지가 있습니다:

• 꺼짐: 판정 적용이 꺼져 있으면 AI 보안 서버에 연결하지 않으며 프롬프트가 검사되지 않습니다.
• 섀도: 판정 적용이 켜져 있고 모드가 섀도 모드로 설정되어 있으면 AI 보안 서버가 프롬프트를 수신하고 판정을 반환하지만, 아무것도 차단되지 않습니다.
• 적용 중: 판정 적용이 켜져 있고 모드가 요청 허용 또는 요청 차단으로 설정되어 있으면 거부 판정이 요청을 차단합니다.

다음 단계는 새 구성을 꺼짐 상태에서 적용 중 상태로 전환합니다.

1. 1

   조직에 Inference hooks 허용

   claude.ai > 조직 설정 > 데이터 및 개인정보 보호로 이동하여 추론 후크 섹션을 찾으세요. 조직에 허용을 켜세요.

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

2. 2

   추론 후크 설정 페이지 열기

   데이터 및 개인정보 보호에서 추론 후크 섹션을 열어 Inference hooks 설정 페이지로 이동하세요. 이 페이지는 설정 탐색 메뉴의 별도 항목이 아닌 데이터 및 개인정보 보호 아래에 있으므로, 이동 경로는 데이터 및 개인정보 보호 / 추론 후크로 표시됩니다. 엔드포인트를 저장하기 전까지는 페이지에 프롬프트가 아직 검사되지 않고 있다는 경고가 표시되며, 판정 적용은 엔드포인트 필요 배지와 함께 꺼진 상태로 유지됩니다.

3. 3

   엔드포인트 구성

   구성을 클릭하여 엔드포인트 설정 대화 상자를 열고 엔드포인트 URL을 입력하세요. 이는 판정 요청을 수신하는 https:// URL입니다. https:// URL만 허용됩니다.

   이 시점에서 대화 상자는 다른 것을 요구하지 않습니다. 사용자 정의 요청 헤더는 5단계에서, 실패 처리는 6단계에서 설정합니다. 다음을 클릭하여 저장하세요. 엔드포인트가 저장되면 버튼이 편집으로 표시됩니다.

4. 4

   서명 시크릿 저장

   처음 저장하면 웹훅 “signing secret”(서명 시크릿)이 생성되고 한 번만 표시됩니다. 다음을 클릭하기 전에 이를 복사하여 안전하게 보관하세요. 시크릿은 나중에 다시 조회할 수 없으며 교체만 가능합니다.

   AI 보안 서버는 이 시크릿을 사용하여 다음 단계의 연결 테스트를 포함해 수신하는 모든 요청의 서명을 검증합니다. 검증 절차는 서명 검증을 참조하세요.

5. 5

   요청 헤더 추가 및 연결 테스트

   서명 시크릿 대화 상자에서 다음을 클릭하면 엔드포인트 대화 상자가 다시 열리며, 이제 두 가지 컨트롤이 추가로 표시됩니다:

   • 사용자 지정 요청 헤더: AI 보안 서버가 호출자를 인증할 수 있도록 모든 판정 요청과 함께 전송되는 최대 16개의 정적 헤더입니다. 헤더 값은 암호화되어 저장되며 다시 표시되지 않습니다. 저장 후에는 헤더 이름만 표시됩니다. 값은 쓰기 전용이므로 헤더에 대한 변경 사항을 저장하려면 모든 값을 다시 입력해야 합니다. 엔드포인트 URL을 변경하면 자격 증명이 새 대상으로 전송되지 않도록 저장된 모든 헤더 값이 지워지므로, URL을 변경한 후에는 값을 다시 입력하세요. 헤더 이름은 _ 대신 -를 사용하는 표준 HTTP 토큰 문자를 사용해야 하며, 예약된 이름(Content-* 및 Host 같은 요청 프레이밍 헤더, 프록시 및 쿠키 헤더, X-Forwarded-* 같은 클라이언트 주소 헤더, webhook-* 서명 헤더, X-Anthropic-* 접두사)과 충돌해서는 안 됩니다. 값은 출력 가능한 ASCII 문자여야 합니다.
   • 연결 테스트: Claude는 저장된 값이 아니라 현재 양식에 입력된 URL과 헤더로 합성 테스트 프롬프트를 전송하므로, 테스트하기 전에 저장된 헤더 값을 다시 입력하세요. 성공하면 결과에 AI 보안 서버가 테스트 프롬프트에 대해 허용 판정을 반환했는지 거부 판정을 반환했는지가 표시되므로, 적용을 시작하기 전에 모든 것을 거부하는 기본 설정을 발견할 수 있습니다. 또한 Anthropic이 해당 테스트 요청 하나에 대해 새 연결에서 연결 핸드셰이크를 포함하여 측정한 왕복 시간도 표시됩니다.

   입력한 헤더를 저장하려면 저장을 클릭하세요.

   일반적인 실패 결과:

   결과	확인할 사항
   URL 거부됨	URL이 구조 검사를 통과하지 못했습니다. 443 포트의 https:// URL을 사용하세요.
   사설 또는 내부 IP	URL의 호스트가 사설 또는 내부 IP 주소, IPv6 주소 또는 localhost입니다. 공개적으로 라우팅 가능한 호스트를 사용하세요.
   타임아웃	AI 보안 서버가 제한 시간 내에 판정을 반환하지 않았습니다.
   전송 오류	DNS 확인, TLS 핸드셰이크 또는 연결이 실패했거나, 호스트 이름이 사설 주소로 확인됩니다.
   200 이외의 상태	AI 보안 서버가 200 이외의 상태로 응답했습니다. 판정은 HTTP 200으로 반환되어야 하며, 리디렉션은 따르지 않고 실패로 간주됩니다.
   파싱할 수 없는 응답	AI 보안 서버가 응답했지만 본문이 유효한 판정이 아닙니다.
   서명 시크릿 필요	조직에 서명 시크릿이 없어 테스트가 서명 없이 전송됩니다. 요청 서명 아래의 시크릿 생성을 클릭한 후 다시 테스트하세요.

6. 6

   실패 처리 및 제한 시간 선택

   오류 처리 아래에서 모드를 설정하여 AI 보안 서버에 연결할 수 없거나 판정이 시간 초과될 때 어떻게 처리할지 선택하세요:

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

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

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

   이 섹션의 변경 사항은 변경하는 즉시 저장됩니다. 첫 번째 저장 시 기본값은 요청 허용과 5,000ms입니다.

7. 7

   롤아웃 비율 선택

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

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

8. 8

   판정 적용 켜기

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

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

   판정 적용 아래에 있는 Validate tool calls(도구 호출 검증) 설정은 Claude의 각 응답에 포함된 도구 호출도 AI 보안 서버로 전송하고, 도구 호출이 실행되기 전에 판정을 기다립니다. 도구 호출 프레임을 참조하세요. 새 구성에서는 기본적으로 켜져 있습니다. 판정 적용이 꺼져 있는 동안에는 효과가 없으며, 판정 적용과 마찬가지로 변경 사항이 모든 Anthropic 서버에 반영되기까지 약 1분이 걸립니다.

섀도 모드

섀도 모드는 아무것도 차단하지 않고 실제 트래픽에 대해 훅을 실행합니다. AI 보안 서버는 적용 중일 때와 똑같이 관리 대상 프롬프트를 받아 판정을 반환하지만, 아무것도 차단되지 않습니다. 서버가 요청을 거부하거나 서버에 연결할 수 없는 경우에도 모든 요청이 모델로 진행되며, 최종 사용자에게는 아무것도 표시되지 않습니다. 적용을 시작하기 전에 조직의 실제 트래픽을 기준으로 정책을 조정하는 데 사용하세요. Validate tool calls가 켜져 있으면 섀도 모드에서도 서버가 도구 호출 프레임을 받으며, 어떤 도구 호출도 차단되지 않습니다.

섀도 모드를 사용하려면 오류 처리 아래에서 모드를 섀도 모드로 설정한 다음, 프롬프트가 AI 보안 서버로 흐르도록 판정 적용을 켜세요. 활성화되어 있는 동안 설정 페이지에는 섀도 모드 — 차단 없음 배지가 표시됩니다. 섀도 모드를 종료하려면 모드를 다시 요청 허용 또는 요청 차단으로 설정하세요. 적용이 켜져 있으면 판정이 다시 적용됩니다.

제외 항목

Who is inspected(검사 대상) 아래에서 Limit by role(역할별 제한) 스위치를 켠 상태로, Inference hooks의 적용을 받지 않을 구성원의 역할을 선택하세요. 해당 구성원의 프롬프트는 AI 보안 서버로 전송되지 않습니다. 조직에서 생성한 사용자 지정 역할만 제외할 수 있으며, 기본 제공 역할은 선택지에 없습니다. 자리 표시자가 제외할 역할 선택으로 표시된 역할 선택기에서 역할을 선택하고, 역할 관리 페이지(역할 관리)에서 각 역할을 보유한 사용자를 관리하세요. 제외 항목을 변경하려면 ID 관리 권한이 필요합니다. 목록은 기본적으로 비어 있으며, 제외된 역할이 없으면 검사가 Only selected roles(선택한 역할만) 옵션으로 설정되지 않은 한 관리 대상인 모든 요청이 검사됩니다.

제외는 사용자의 대화형 세션에 적용됩니다. 제외 목록의 변경 사항은 조직의 Activity Feed에 역할 권한 변경(rbac_role_permission_added 및 rbac_role_permission_removed)으로 기록됩니다.

선택한 역할만 검사

Who is inspected 섹션의 모든 항목은 하나의 스위치인 Limit by role 뒤에 있습니다. 스위치를 켜면 검사가 Everyone except excluded roles로 시작되며, 위에서 설명한 대로 그 아래에서 제외할 역할을 선택합니다.

먼저 조직의 일부에서 Inference hooks를 시험해 보려면 Limit by role을 켜고, 검사를 Only selected roles로 설정한 다음, 열리는 대화 상자에서 역할을 선택하세요. 그 이후로는 사용자 지정 역할로 설정되어 있고 선택된 역할이 할당된 구성원만 검사됩니다. 사용자 또는 소유자 같은 다른 역할로 설정된 구성원은 선택된 역할이 할당되어 있더라도 검사되지 않습니다. 여기에는 소유자 또는 주 소유자로 설정된 경우의 본인도 포함됩니다. 전환하기 전에 제외된 역할을 모두 제거하세요. 조직은 제외 또는 선택된 역할 중 하나만 사용할 수 있으며, 둘 다 사용할 수는 없습니다. 전환 후에는 검사 아래의 역할 선택기에서 역할을 추가하거나 제거하세요. 다시 모든 사용자를 검사하려면 Limit by role을 끄세요. 확인하면 제외된 역할이 모두 제거되고 Only selected roles가 꺼집니다.

Only selected roles가 설정되어 있는 동안:

• 기능 액세스가 모든 기능 또는 모두 일반 제공인 사용자 지정 역할도 다른 역할과 마찬가지로 선택한 경우에만 포함됩니다.
• 사용자 지정 역할로 설정된 구성원 중 선택된 역할이 할당된 구성원이 없으면 어떤 구성원도 검사되지 않습니다.
• API 키로 이루어진 요청이나 Slack의 Claude Tag 대화처럼 구성원이 연결되지 않은 요청은 검사되지 않습니다.

검사 설정 변경과 검사 대상 역할 변경은 조직의 Activity Feed에 기록됩니다.

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

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

AI 보안 서버 모니터링

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

• 엔드포인트 상태: 정상, 차단됨, 미적용, 또는 엔드포인트가 저장되기 전에는 구성되지 않음.
• 분당 실패 수: 최근 2분 동안의 webhook 실패 횟수의 평균.
• 차단율: AI 보안 서버 판정 중 거부가 차지하는 비율로, 롤아웃 비율이 100 미만일 때 표시됩니다.
• 서킷 브레이커 작동됨: 차단기가 작동한 적이 있는 경우 마지막으로 작동한 시점.
• 최근 오류: 각 항목에는 실패가 발생한 시점, 오류 유형 및 카테고리가 표시됩니다. 카테고리는 엔드포인트 또는 엔드포인트와의 연결에 문제가 있는 경우 webhook_error, Anthropic 시스템 내부의 실패인 경우 relay_error입니다. DlpWebhookStatusError 항목에는 AI 보안 서버가 반환한 HTTP 상태와 Anthropic이 전송한 요청 본문의 크기(예: HTTP 413 · 1.3 MB)도 표시될 수 있습니다. 항목에는 요청 내용이나 엔드포인트 URL이 절대 포함되지 않습니다. 목록에는 가장 최근의 실패 10개가 유지되며, 마지막 실패 후 1시간이 지나면 지워집니다.

최근 오류의 오류 유형은 다음을 의미합니다:

섀도 모드에서는 어떤 오류도 서킷 브레이커에 집계되지 않습니다.

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

서킷 브레이커

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

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

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

차단기는 자동으로 재설정될 수도 있습니다. 작동 후 10분이 지나면 Anthropic은 백그라운드에서 서버에 테스트 요청을 보내 서버가 복구되었는지 확인하며, 이 확인은 최대 약 1분에 한 번 수행됩니다. 이 과정에는 사용자 요청이 관여하지 않습니다. 서버가 허용 또는 거부의 유효한 판정으로 응답하면 차단기가 재설정되고 적용이 재개됩니다. 그렇지 않으면 차단기는 작동 상태로 유지되며 확인이 계속됩니다.

자동 복구는 작동 이후 Inference hooks 설정이 변경되지 않은 경우에만 실행됩니다. 작동 후 서명 시크릿 교체를 포함하여 Inference hooks 설정을 변경하면 확인이 중지되고 차단기가 더 이상 자동으로 재설정되지 않으므로, 서버가 수정되면 판정 적용을 다시 켜세요. 자동 복구는 작동에만 적용됩니다. 사용자가 직접 판정 적용을 끈 경우에는 다시 켤 때까지 적용이 꺼진 상태로 유지됩니다.

서명 시크릿 교체

서명 시크릿을 교체하려면 요청 서명 아래의 시크릿 교체를 클릭하세요. 조직에 아직 시크릿이 없는 경우 같은 버튼이 시크릿 생성으로 표시되며 첫 번째 시크릿을 생성합니다. 교체는 즉시 전환됩니다. 새 시크릿이 생성되어 한 번만 표시되고, 이전 시크릿은 더 이상 조회할 수 없으며, 어떤 요청도 두 시크릿으로 동시에 서명되지 않으므로 의존할 수 있는 중첩 기간이 없습니다.

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

감사 추적

Inference hooks 활동은 조직의 Activity Feed에 기록됩니다. 여기에는 구성 변경, 거부, 서킷 브레이커 작동, 그리고 판정을 얻을 수 없어 검사 없이 진행된 요청이 포함됩니다. 마지막 유형은 판정 적용이 켜져 있고 모드가 요청 허용인 경우에만 기록됩니다. 그 사유는 endpoint_timeout, AI 보안 서버 호출 시 발생한 기타 문제의 경우 endpoint_error, Anthropic 측 실패의 경우 internal_error입니다. 요청 차단 또는 섀도 모드에서는 실패한 요청이 개별적으로 기록되지 않습니다. 서킷 브레이커의 자동 복구는 어떤 모드에서도 기록되지 않습니다. 서킷 브레이커가 작동 중인 동안에는 요청별 Inference hooks 활동이 기록되지 않으며, 작동 활동이 해당 기간에 대한 피드의 기록이 됩니다. 거부 기록에는 각 거부를 자체 시스템의 해당 기록과 연결할 수 있는 식별자가 포함됩니다.

Inference hooks 끄기

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

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

다음 단계