--- title: Inference hooks 구성 url: https://platform.claude.com/docs/ko/manage-claude/inference-hooks-configuration description: Claude Enterprise 조직에 Inference hooks를 허용하고, AI 보안 서버를 연결하며, 적용, 실패 처리 및 롤아웃을 제어합니다. --- Inference hooks는 베타 단계이며 Claude Enterprise 조직에서 사용할 수 있습니다. 이를 구성하려면 `organization:manage` 권한이 필요하며, 이 권한은 Owner 및 Primary owner 역할만 보유합니다. Inference hooks는 조직의 프롬프트를 사용자가 선택한 AI 보안 서버로 전송하고, Claude가 각 요청을 처리하기 전에 허용 또는 거부 "verdict"(판정)를 받을 때까지 요청을 보류합니다. 이 페이지에서는 기능을 켜고, 서버를 연결하고, 적용을 제어하는 과정을 안내합니다. Inference hooks가 무엇이며 언제 사용하는지 알아보려면 [Inference hooks 개요](https://platform.claude.com/docs/ko/manage-claude/inference-hooks)를 참조하세요. AI 보안 서버 자체를 구축하려면 [Inference hooks 통합 개발](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-endpoint)을 참조하세요. ## 시작하기 전에 다음이 필요합니다: * claude.ai의 `organization:manage` 권한. 이 권한은 **Owner** 및 **Primary owner** 역할만 보유합니다. **Admin** 역할에는 이 권한이 없습니다. * 판정 요청을 수락하는 AI 보안 서버 HTTPS 엔드포인트: 공개적으로 라우팅 가능한 호스트의 443 포트에 있고, 리디렉션 없이 접근할 수 있는 `https://` URL이어야 합니다. 리버스 터널 호스트(ngrok 및 유사한 터널 서비스)는 지원되지 않습니다. Anthropic의 네트워크 정책이 이를 차단합니다. 터널을 통해 테스트하지 말고, 직접 관리하는 도메인에서 서버를 호스팅하세요. 전체 [호스팅 요구 사항](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-endpoint#receive-a-request)과 서버 구축 및 서명된 요청 검증 방법은 [Inference hooks 통합 개발](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-endpoint)을 참조하세요. ## Inference hooks 설정 적용 상태에는 세 가지가 있습니다: **꺼짐**(**Enforce verdicts**가 꺼져 있음: AI 보안 서버에 전혀 연결하지 않으며 프롬프트가 검사되지 않음), **섀도**(**Enforce verdicts**가 켜져 있고 **Mode**가 **Shadow mode**로 설정됨: AI 보안 서버가 프롬프트를 수신하고 판정을 반환하지만 아무것도 차단되지 않음), **적용 중**(**Enforce verdicts**가 켜져 있고 **Mode**가 **Allow the request** 또는 **Block the request**로 설정됨: 거부 판정이 요청을 차단함). 다음 단계는 새 구성을 꺼짐 상태에서 적용 중 상태로 전환합니다. claude.ai > **Organization settings** > **Data and privacy**로 이동하여 **Inference hooks** 섹션을 찾으세요. **Allow for your organization**을 켜세요. 이 설정을 켜면 Inference hooks 설정 페이지가 잠금 해제되며 항상 **Enforce verdicts**가 강제로 꺼지므로, 기능을 허용하는 것만으로는 검사가 시작되지 않습니다. 이전에 적용이 켜져 있던 구성이라도 마지막 단계에서 **Enforce verdicts**를 다시 켤 때까지 검사되지 않은 상태로 유지됩니다. **Data and privacy**에 머무른 채로 **Inference hooks** 섹션을 열어 Inference hooks 설정 페이지로 이동하세요. 이 페이지는 설정 탐색 메뉴의 독립 항목이 아니라 Data and privacy 아래에 있으므로 브레드크럼은 **Data and privacy / Inference hooks**로 표시됩니다. 엔드포인트를 저장하기 전까지 페이지에는 프롬프트가 아직 검사되지 않고 있다는 경고가 표시되며, **Enforce verdicts**는 **Requires endpoint** 배지와 함께 꺼진 상태로 유지됩니다. **Configure**를 클릭하여 **Set up endpoint** 대화 상자를 열고 **Endpoint URL**을 입력하세요. 이는 판정 요청을 받는 `https://` URL입니다. `https://` URL만 허용됩니다. 이 시점에서 대화 상자는 다른 항목을 요구하지 않습니다. 사용자 지정 요청 헤더는 5단계에서, 실패 처리는 6단계에서 설정합니다. **Next**를 클릭하여 저장하세요. 엔드포인트가 저장되면 버튼이 **Edit**로 바뀝니다. 처음 저장하면 웹훅 "signing secret"(서명 시크릿)이 생성되고 한 번만 표시됩니다. **Next**를 클릭하기 전에 이를 복사하여 안전하게 보관하세요. 시크릿은 나중에 다시 조회할 수 없으며 [교체](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-configuration#rotate-your-signing-secret)만 가능합니다. AI 보안 서버는 이 시크릿을 사용하여 다음 단계의 연결 테스트를 포함해 수신하는 모든 요청의 서명을 검증합니다. 검증 절차는 [서명 검증](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-endpoint#verify-the-signature)을 참조하세요. 서명 시크릿 대화 상자에서 **Next**를 클릭하면 엔드포인트 대화 상자가 다시 열리며, 이제 두 가지 컨트롤이 추가로 표시됩니다: * **Custom request headers:** AI 보안 서버가 호출자를 인증할 수 있도록 모든 판정 요청과 함께 전송되는 최대 16개의 정적 헤더입니다. 헤더 값은 암호화되어 저장되며 다시 표시되지 않습니다. 저장 후에는 헤더 이름만 표시됩니다. 값은 쓰기 전용이므로 헤더에 대한 변경 사항을 저장하려면 모든 값을 다시 입력해야 합니다. 엔드포인트 URL을 변경하면 자격 증명이 새 대상으로 전송되지 않도록 저장된 모든 헤더 값이 지워지므로, URL을 변경한 후에는 값을 다시 입력하세요. 헤더 이름은 `_` 대신 `-`를 사용하는 표준 HTTP 토큰 문자를 사용해야 하며, 예약된 이름(`Content-*` 및 `Host` 같은 요청 프레이밍 헤더, 프록시 및 쿠키 헤더, `X-Forwarded-*` 같은 클라이언트 주소 헤더, `webhook-*` 서명 헤더, `X-Anthropic-*` 접두사)과 충돌해서는 안 됩니다. 값은 출력 가능한 ASCII 문자여야 합니다. * **Test connection:** Claude는 저장된 값이 아니라 현재 양식에 입력된 URL과 헤더로 합성 테스트 프롬프트를 전송하므로, 테스트하기 전에 저장된 헤더 값을 다시 입력하세요. 성공하면 결과에 AI 보안 서버가 테스트 프롬프트에 대해 허용 판정을 반환했는지 거부 판정을 반환했는지가 표시되므로, 적용을 시작하기 전에 모든 것을 거부하는 기본 설정을 발견할 수 있습니다. 입력한 헤더를 저장하려면 **Save**를 클릭하세요. 일반적인 실패 결과: | 결과 | 확인할 사항 | | ----------------------- | ---------------------------------------------------------------------------------------------- | | URL rejected | URL이 구조 검사를 통과하지 못했습니다. 443 포트의 `https://` URL을 사용하세요. | | Private or internal IP | URL의 호스트가 사설 또는 내부 IP 주소, IPv6 주소 또는 `localhost`입니다. 공개적으로 라우팅 가능한 호스트를 사용하세요. | | Timeout | AI 보안 서버가 제한 시간 내에 판정을 반환하지 않았습니다. | | Transport error | DNS 확인, TLS 핸드셰이크 또는 연결이 실패했거나, 호스트 이름이 사설 주소로 확인됩니다. | | Non-200 status | AI 보안 서버가 200 이외의 상태로 응답했습니다. 판정은 HTTP 200으로 반환되어야 하며, 리디렉션은 따르지 않고 실패로 간주됩니다. | | Unparseable response | AI 보안 서버가 응답했지만 본문이 유효한 판정이 아닙니다. | | Signing secret required | 조직에 서명 시크릿이 없어 테스트가 서명 없이 전송됩니다. **Request signing** 아래의 **Generate secret**을 클릭한 후 다시 테스트하세요. | **Failure handling** 아래에서 **Mode**를 설정하여 AI 보안 서버에 도달할 수 없거나 판정이 시간 초과될 때 어떻게 할지 선택하세요: * **Block the request:** AI 보안 서버가 판정을 전달할 수 없을 때 추론을 중지합니다(fail closed). * **Allow the request:** 검사 없이 요청이 모델로 진행되도록 합니다(fail open). 드롭다운의 세 번째 옵션인 **Shadow mode**는 실패 정책이 아니라 롤아웃 도구입니다. [섀도 모드](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-configuration#shadow-mode)를 참조하세요. 그런 다음 **Prompt verdict timeout (ms)**를 설정하세요: 1\~10,000ms이며 기본값은 5,000ms입니다. 이 예산은 전체 교환 과정을 포함하며, 더 느린 판정은 도달할 수 없는 서버로 간주되므로 서버가 안정적으로 충족할 수 있는 가장 낮은 값을 설정하세요. 이 섹션의 변경 사항은 변경하는 즉시 저장됩니다. 첫 번째 저장 시 기본값은 **Allow the request**와 5,000ms입니다. **Rollout** 아래에서 **Requests inspected (%)**를 설정하여 AI 보안 서버를 가동하는 동안 일정 비율의 요청에 대해 검사를 실행하세요. 값의 범위는 0\~100입니다. 100은 모든 것을 검사하고 0은 검사를 끕니다. 각 요청은 전체 대화 턴에 대해 한 번 추첨되므로, 단일 대화가 턴에 따라 부분적으로 검사될 수 있습니다. 샘플링된 비율 밖의 요청은 실패 처리가 **Block the request**로 설정되어 있어도 검사 없이 진행됩니다. 처음에는 아무도 차단하지 않고 실제 트래픽에 대해 판정을 평가하려면 적용을 켜기 전에 **Mode**를 **Shadow mode**로 설정하세요(6단계). [섀도 모드](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-configuration#shadow-mode)를 참조하세요. **Enforce verdicts**를 켜서 관리 대상인 모든 프롬프트에 대해 AI 보안 서버의 판정에 따라 Claude를 제어한 다음, 실패 처리 선택 사항을 다시 보여주는 대화 상자에서 확인하세요. 변경 사항이 모든 Anthropic 서버에 반영되기까지 약 1분이 걸립니다. 이미 처리 중인 요청은 이전 설정으로 완료됩니다. 이 설정을 끄면 역시 약 1분 이내에 프롬프트가 AI 보안 서버로 전송되지 않으며, 구성은 유지됩니다. **Enforce verdicts** 아래에 있는 **Validate tool calls**는 Claude의 각 응답에 포함된 도구 호출도 AI 보안 서버로 전송하고, 도구 호출이 실행되기 전에 판정을 기다립니다. [도구 호출 프레임](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-endpoint#the-tool-call-frame)을 참조하세요. 새 구성에서는 기본적으로 켜져 있습니다. **Enforce verdicts**가 꺼져 있는 동안에는 효과가 없으며, **Enforce verdicts**와 마찬가지로 변경 사항이 모든 Anthropic 서버에 반영되기까지 약 1분이 걸립니다. ## 섀도 모드 섀도 모드는 아무것도 차단하지 않고 실제 트래픽에 대해 훅을 실행합니다. AI 보안 서버는 적용 중일 때와 똑같이 관리 대상 프롬프트를 받아 판정을 반환하지만, 아무것도 차단되지 않습니다. 서버가 요청을 거부하거나 서버에 연결할 수 없는 경우에도 모든 요청이 모델로 진행되며, 최종 사용자에게는 아무것도 표시되지 않습니다. 적용을 시작하기 전에 조직의 실제 트래픽을 기준으로 정책을 조정하는 데 사용하세요. **Validate tool calls**가 켜져 있으면 섀도 모드에서도 서버가 도구 호출 프레임을 받으며, 어떤 도구 호출도 차단되지 않습니다. 섀도 모드를 사용하려면 **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 관리 권한이 필요합니다. 목록은 기본적으로 비어 있으며, 제외된 역할이 없으면 모든 관리 대상 요청이 검사됩니다. 제외는 사용자의 대화형 세션에 적용됩니다. 제외 목록의 변경 사항은 조직의 [Activity Feed](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed)에 역할 권한 변경(`rbac_role_permission_added` 및 `rbac_role_permission_removed`)으로 기록됩니다. ## 사용자 지정 차단 프롬프트 메시지 **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:** 각 항목에는 실패가 발생한 시점, 오류 유형 및 범주가 표시됩니다. 범주는 엔드포인트 또는 엔드포인트 연결에 문제가 있는 경우 `webhook_error`, Anthropic 시스템 내부의 실패인 경우 `relay_error`입니다. 항목에는 요청 내용이나 엔드포인트 URL이 포함되지 않습니다. 목록에는 가장 최근 실패 10개가 유지되며, 마지막 실패 후 1시간이 지나면 지워집니다. **Recent errors**의 오류 유형은 다음을 의미합니다: | 표시되는 오류 | 의미 | 서킷 브레이커 집계 여부 | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | `DlpWebhookTimeoutError` · `webhook_error` | AI 보안 서버가 설정한 **Prompt verdict timeout (ms)** 내에 판정을 반환하지 않았습니다. | 예 | | `DlpWebhookStatusError` · `webhook_error` | AI 보안 서버가 리디렉션 등 200 이외의 HTTP 상태로 응답했습니다. | 예 | | `DlpWebhookResponseError` · `webhook_error` | AI 보안 서버가 200으로 응답했지만 본문이 유효한 판정이 아니거나 64 KiB보다 큽니다. | 예 | | `DlpWebhookTransportError` · `webhook_error` | 완전한 응답이 도착하기 전에 연결이 실패하거나 끊어졌습니다. 예를 들어 호스트 이름이 확인되지 않았거나 사설 주소로 확인되었거나, 연결이 거부 또는 재설정되었거나, TLS 핸드셰이크가 실패한 경우입니다. Anthropic 측의 네트워크 문제도 이렇게 표시될 수 있습니다. | 아니요 | | `DlpWebhookDisallowedAddressError` · `webhook_error` | 엔드포인트 URL의 호스트가 사설 또는 내부 IP 주소, IPv6 주소 또는 `localhost`입니다. 이러한 주소로 확인되는 호스트 이름은 대신 전송 오류로 표시됩니다. | 예 | | `DlpWebhookBlockedError` · `webhook_error` | 엔드포인트 URL이 포트 443의 `https://` URL이 아니거나 구문 분석할 수 없어 요청이 전송되지 않았습니다. | 아니요 | | `DlpWebhookRelayError` · `relay_error` | Anthropic 시스템 내부에서 실패가 발생했으며, 일반적으로 AI 보안 서버에는 연결되지 않았습니다. | 아니요 | 섀도 모드에서는 어떤 오류도 서킷 브레이커에 집계되지 않습니다. 이 패널은 최선 노력(best-effort) 방식입니다. Anthropic이 카운터를 읽을 수 없는 경우 자체 오류 대신 실패 0건과 오류 없음을 표시하므로, 정상으로 보이는 패널 자체가 AI 보안 서버가 정상이라는 증거는 아닙니다. **Failures per minute**는 서킷 브레이커를 작동시키지 않는 네트워크 및 DNS 오류를 포함한 모든 실패를 집계하므로, **Circuit breaker tripped**가 비어 있는 동안에도 높을 수 있습니다. ## 서킷 브레이커 AI 보안 서버에 기인하는 지속적인 웹훅 실패는 "circuit breaker"(서킷 브레이커)를 작동시켜 적용을 중지합니다. 서버에 더 이상 연결하지 않으며, **Failure handling** 선택 사항이 검사 대상인 모든 요청에 적용됩니다. **Block the request**가 선택된 경우 브레이커가 재설정될 때까지 조직의 사용자가 차단됩니다. 브레이커가 작동하면 관리자에게도 claude.ai 알림 센터에서 알림이 전송됩니다. 각 작동은 조직의 [Activity Feed](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed)에도 `inference_hooks_circuit_breaker_tripped` 활동으로 기록되므로, 보안 팀이나 벤더가 피드를 수집하는 SIEM과 같이 이미 운영 중인 모니터링에서 작동에 대한 경보를 설정할 수 있습니다. 영향을 받은 요청당 하나가 아니라 작동당 하나의 활동이 기록됩니다. 기록하려면 조직에 Compliance API가 활성화되어 있어야 합니다. [Compliance API 설정](https://platform.claude.com/docs/ko/manage-claude/compliance-api-access)을 참조하세요. 복구하려면 서버를 수정한 다음 **Enforce verdicts**를 다시 켜서 브레이커를 재설정하세요. 차단기는 자동으로 재설정될 수도 있습니다. 작동 후 10분이 지나면 Anthropic은 백그라운드에서 서버에 테스트 요청을 보내 서버가 복구되었는지 확인하며, 이 확인은 최대 약 1분에 한 번 수행됩니다. 이 과정에는 사용자 요청이 관여하지 않습니다. 서버가 허용 또는 거부의 유효한 판정으로 응답하면 차단기가 재설정되고 적용이 재개됩니다. 그렇지 않으면 차단기는 작동 상태로 유지되며 확인이 계속됩니다. 자동 복구는 작동 이후 Inference hooks 설정이 변경되지 않은 경우에만 실행됩니다. 작동 후 서명 시크릿 교체를 포함하여 Inference hooks 설정을 변경하면 확인이 중지되고 차단기가 더 이상 자동으로 재설정되지 않으므로, 서버가 수정되면 **Enforce verdicts**를 다시 켜세요. 자동 복구는 작동에만 적용됩니다. 사용자가 직접 **Enforce verdicts**를 끈 경우에는 다시 켤 때까지 적용이 꺼진 상태로 유지됩니다. ## 서명 시크릿 교체 서명 시크릿을 교체하려면 **Request signing** 아래의 **Rotate secret**을 클릭하세요. 조직에 아직 시크릿이 없는 경우 같은 버튼이 **Generate secret**으로 표시되며 첫 번째 시크릿을 생성합니다. 교체는 즉시 전환됩니다. 새 시크릿이 생성되어 한 번만 표시되고, 이전 시크릿은 더 이상 조회할 수 없으며, 어떤 요청도 두 시크릿으로 동시에 서명되지 않으므로 의존할 수 있는 중첩 기간이 없습니다. 이전 시크릿으로 서명된 요청이 교체 후 잠시 동안 도착할 수 있습니다. AI 보안 서버가 전환을 처리하는 방법은 [서명 검증](https://platform.claude.com/docs/ko/manage-claude/inference-hooks-endpoint#verify-the-signature)에서 다룹니다. ## 감사 추적 Inference hooks 활동은 조직의 [Activity Feed](https://platform.claude.com/docs/ko/manage-claude/compliance-activity-feed)에 기록됩니다. 여기에는 구성 변경, 거부, 서킷 브레이커 작동, 그리고 판정을 얻을 수 없어 검사 없이 진행된 요청이 포함됩니다. 마지막 유형은 **Enforce verdicts**가 켜져 있고 **Mode**가 **Allow the request**인 경우에만 기록됩니다. 그 사유는 `endpoint_timeout`, AI 보안 서버 호출 시 발생한 기타 문제의 경우 `endpoint_error`, Anthropic 측 실패의 경우 `internal_error`입니다. **Block the request** 또는 **Shadow mode**에서는 실패한 요청이 개별적으로 기록되지 않습니다. 서킷 브레이커의 자동 복구는 어떤 모드에서도 기록되지 않습니다. 서킷 브레이커가 작동 중인 동안에는 요청별 Inference hooks 활동이 기록되지 않으며, 작동 활동이 해당 기간에 대한 피드의 기록이 됩니다. 거부 기록에는 각 거부를 자체 시스템의 해당 기록과 연결할 수 있는 식별자가 포함됩니다. ## Inference hooks 끄기 끄기에는 두 가지 수준이 있습니다: * Inference hooks 설정 페이지에서 **Enforce verdicts** 끄기: 약 1분 이내에 조직의 프롬프트가 AI 보안 서버로 전송되지 않습니다. 이미 진행 중인 요청은 이전 설정에 따라 완료됩니다. 설정 페이지는 계속 사용할 수 있으므로 AI 보안 서버 작업 중 적용을 일시 중지하는 데 사용하세요. * **Data and privacy** 설정에서 **Allow for your organization** 끄기: 프롬프트가 더 이상 검사되지 않으며, 다시 켤 때까지 Inference hooks 설정을 사용할 수 없게 됩니다. 어느 경우든 엔드포인트 구성, 사용자 지정 헤더, 서명 시크릿은 유지됩니다. 다시 켜면 **Enforce verdicts**가 강제로 꺼지고 작동한 서킷 브레이커가 해제되므로, 준비가 되면 적용을 다시 켜세요. ## 다음 단계 AI 보안 서버 구축: 요청 및 판정 스키마, 서명 검증, 운영 의미론. Inference hooks가 무엇인지, 판정 왕복이 어떻게 작동하는지, AI 보안 서버로 무엇이 전송되는지 알아봅니다.