Inference hooks 구성

Inference hooks는 조직의 프롬프트를 선택한 AI 보안 서버로 보내고, Claude가 처리하기 전에 각 요청을 허용·거부 평결로 잡아두는 기능이에요. 이 페이지는 기능을 켜고 서버를 연결하며 집행을 제어하는 과정을 안내해 드릴게요. Inference hooks가 무엇이고 언제 쓰는지는 Inference hooks 개요를 참고하세요. AI 보안 서버 자체를 구축하려면 Inference hooks 통합 개발을 참고하세요.

Inference hooks는 베타이며 Claude Enterprise 조직에서 사용할 수 있어요. 구성하려면 Owner와 Primary owner 역할만 가진 organization:manage 권한이 필요해요.

출처: 문서

본문

시작하기 전에

다음이 필요해요:

claude.ai의 organization:manage 권한 — Owner와 Primary owner 역할만 가져요. Admin 역할은 가지지 않아요.
평결 요청을 받아들이는 AI 보안 서버 HTTPS 엔드포인트: 포트 443의 https:// URL, 공개 라우팅 가능한 호스트, 리다이렉트 없이 도달 가능. 리버스 터널 호스트(ngrok 및 유사 터널 서비스)는 지원되지 않아요. Anthropic의 네트워크 정책이 차단해요. 터널로 테스트하지 말고 제어하는 도메인에 서버를 호스팅하세요. 전체 호스팅 요구 사항과 서버 구축·서명된 요청 검증은 Inference hooks 통합 개발 참고.

Inference hooks 설정

세 가지 집행 상태가 있어요: off(Enforce verdicts 해제: AI 보안 서버에 연락하지 않고 프롬프트 검사하지 않음), shadow(Enforce verdicts 켬 + Mode를 Shadow mode로: AI 보안 서버가 프롬프트를 받고 평결을 반환하며 아무것도 차단하지 않음), enforcing(Enforce verdicts 켬 + Mode를 Allow the request나 Block the request로: deny가 요청을 차단). 다음 단계는 새 구성을 off에서 enforcing으로 이끌어요.

조직에 Inference hooks 허용 — claude.ai > Organization settings > Data and privacy로 이동해 Inference hooks 섹션을 찾으세요. Allow for your organization을 켜세요. 켜면 Inference hooks 설정 페이지가 잠금 해제되고 항상 Enforce verdicts를 강제로 끄므로, 기능 허용 자체로 검사가 시작되지는 않아요. 이전에 집행이 켜져 있던 구성도 마지막 단계에서 Enforce verdicts를 다시 켤 때까지 검사되지 않은 상태로 유지돼요.
Inference hooks 설정 페이지 열기 — 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으로 읽혀요.
서명 비밀 저장 — 첫 저장이 웹훅 서명 비밀을 생성하고 한 번 보여줘요. Next를 클릭하기 전에 복사해 안전하게 저장하세요. 비밀은 나중에 조회할 수 없고 교체만 가능해요. AI 보안 서버는 받는 모든 요청의 서명을 이 비밀로 검증하며 다음 단계의 연결 테스트도 포함해요. 검증 절차는 서명 검증 참고.

요청 헤더 추가 및 연결 테스트 — 서명 비밀 대화상자에서 Next를 클릭하면 엔드포인트 대화상자가 두 개의 제어를 더 추가해 다시 열려요.

Custom request headers: 모든 평결 요청과 함께 보내는 최대 16개 정적 헤더로, AI 보안 서버가 호출자를 인증할 수 있게 해줘요. 헤더 값은 암호화되어 저장되고 다시는 표시되지 않아요. 저장 후에는 헤더 이름만 표시돼요. 값은 쓰기 전용이므로 헤더를 변경하려면 모든 값을 다시 입력해야 해요. 엔드포인트 URL을 변경하면 저장된 모든 헤더 값이 지워져 새 대상으로 자격 증명이 절대 보내지지 않아요. URL 변경 후 다시 입력하세요. 헤더 이름은 -를 써서 _ 대신 표준 HTTP 토큰 문자를 사용해야 하고, 예약 이름(요청 프레임 헤더인 Content-*·Host, 프록시·쿠키 헤더, X-Forwarded-* 같은 클라이언트 주소 헤더, webhook-* 서명 헤더, X-Anthropic-* 접두사)과 충돌하면 안 돼요. 값은 출력 가능한 ASCII여야 해요.
Test connection: Claude가 현재 양식에 있는(저장된 값이 아닌) URL·헤더로 합성 테스트 프롬프트를 보내요. 저장된 헤더 값이 있으면 테스트 전에 다시 입력하세요. 성공하면 결과가 AI 보안 서버가 테스트 프롬프트에 대해 allow·deny 중 무엇을 반환했는지 보고해요. 이는 집행을 시작하기 전에 모든 것을 거부하는 기본값을 표면화해줘요. Save를 클릭해 입력한 헤더를 저장하세요. 일반적인 실패 결과:

결과	확인할 것
URL 거부됨	URL이 구조 검사에 실패했어요. 포트 443의 `https://` URL을 사용하세요.
비공개·내부 IP	호스트가 비공개·내부 주소로 해석돼요. 공개 라우팅 가능한 호스트를 사용하세요.
시간 초과	AI 보안 서버가 시간 초과 안에 평결을 반환하지 않았어요.
전송 오류	DNS 해석, TLS 핸드셰이크, 연결이 실패했어요.
200이 아닌 상태	AI 보안 서버가 200이 아닌 상태로 응답했어요. 평결은 HTTP 200으로 와야 해요. 리다이렉트는 따르지 않고 실패로 계산돼요.
파싱 불가 응답	AI 보안 서버가 응답했지만 본문이 유효한 평결이 아니에요.
서명 비밀 필요	조직에 서명 비밀이 없어 테스트가 서명 없이 보내질 거예요. Request signing 아래 Generate secret을 클릭한 뒤 다시 테스트하세요.

실패 처리와 시간 초과 선택 — Failure handling 아래 Mode를 설정해 AI 보안 서버가 도달 불가능하거나 평결이 시간 초과될 때 무슨 일이 일어날지 선택하세요:
- Block the request: AI 보안 서버가 평결을 제공하지 못하면 추론을 멈춰요(실패 시 닫힘).
- Allow the request: 요청이 검사 없이 모델로 진행되게 해요(실패 시 열림).
드롭다운의 세 번째 옵션 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로 실패 처리가 설정돼 있어도 검사 없이 진행돼요.
Enforce verdicts 켜기 — 처음에 아무도 차단하지 않고 실시간 트래픽에 대해 평결을 평가하려면 집행을 켜기 전에 Mode를 Shadow mode(6단계)로 설정하세요. 섀도 모드 참고. Enforce verdicts를 켜면 모든 통제된 프롬프트에 대해 Claude를 AI 보안 서버의 평결로 게이팅한 뒤, 실패 처리 선택을 다시 진술하는 대화상자에서 확인하세요. 변경이 모든 Anthropic 서버에 도달하는 데 약 1분을 허용하세요. 이미 진행 중인 요청은 이전 설정으로 끝나요. 끄면 약 1분 안에 프롬프트가 AI 보안 서버로 보내지지 않게 되고 구성은 유지돼요.

섀도 모드

섀도 모드는 아무것도 차단하지 않고 후크를 실시간 트래픽으로 실행해요. AI 보안 서버는 통제된 프롬프트를 받고 집행할 때처럼 정확히 평결을 반환하지만 아무것도 차단하지 않아요. 서버가 거부하거나 도달할 수 없어도 모든 요청이 모델로 진행되고 최종 사용자는 아무것도 보지 못해요. 집행을 시작하기 전에 조직의 실제 트래픽에 맞춰 정책을 조정하는 데 사용하세요.

섀도 모드를 사용하려면 Failure handling 아래 Mode를 Shadow mode로 설정한 뒤 Enforce verdicts를 켜 프롬프트가 AI 보안 서버로 흐르게 하세요. 활성인 동안 설정 페이지는 Shadow mode — not blocking 배지를 보여줘요. 섀도 모드를 나가려면 Mode를 Allow the request나 Block the request로 되돌리세요. 집행이 켜져 있으면 평결이 다시 집행돼요.

제외 (Exclusions)

Exclusions 아래에서 구성원이 Inference hooks에 적용되지 않을 역할을 선택하세요. 그들의 프롬프트는 AI 보안 서버로 절대 보내지지 않아요. 조직이 만든 커스텀 역할만 제외할 수 있고 내장 역할은 제공되지 않아요. Select roles to exclude 자리 표시자가 있는 역할 선택기에서 선택하고, 역할 관리 페이지(Manage roles)에서 각 역할을 누가 보유하는지 관리하세요. 제외 변경에는 identity 관리 권한이 필요해요. 목록은 기본적으로 비어 있고 제외된 역할이 없으면 모든 통제된 요청이 검사돼요.

제외는 사용자의 대화형 세션에 적용돼요. 머신 자격 증명으로 인증된 트래픽은 항상 검사돼요. 제외 목록 변경은 감사 기록에 기록돼요.

커스텀 차단 프롬프트 메시지

Custom blocked prompt message 아래에서 최대 500자의 커스텀 텍스트를 설정하세요. AI 보안 서버가 요청을 거부할 때 최종 사용자가 보는 오류에 덧붙여져요(보통 연락할 사람이나 예외 요청 위치). 최종 메시지는 AI 보안 서버의 요청별 deny_reason(있을 때), 빈 줄, 이 텍스트 순서예요. 커스텀 텍스트가 없으면 내장 기본값이 사용자를 관리자에게 연락하도록 안내해요. 덧붙이는 메시지를 완전히 꺼 사용자가 deny_reason만 보게 할 수도 있어요.

AI 보안 서버 모니터링

Inference hooks 설정 페이지의 엔드포인트 상태 영역은 다음을 보여줘요:

Endpoint status: Healthy, Tripped, Not enforcing, 또는 엔드포인트 저장 전에는 Not configured.
Failures per minute: 지난 2분간의 웹훅 실패 평균.
Block rate: 롤아웃 비율이 100 미만일 때 AI 보안 서버 평결에서 거부가 차지하는 비율.
Circuit breaker tripped: 차단기가 마지막으로 작동한 시점(작동한 적 있다면).
Recent errors: 각 항목이 타임스탬프, 오류 유형, 한 줄 이유로 축소돼요. 항목에 요청 콘텐츠나 엔드포인트 URL은 절대 포함되지 않아요.

패널은 최선 노력(best-effort)이에요. Anthropic이 카운터를 읽을 수 없으면 자체 오류 대신 0 실패·오류 없음을 보여주므로, 건강해 보이는 패널 자체만으로 AI 보안 서버가 건강하다는 증거는 아니에요. Failures per minute는 회로 차단기를 작동시키지 않는 네트워크·DNS 오류를 포함한 모든 실패를 세므로 Circuit breaker tripped가 비어 있어도 높을 수 있어요.

회로 차단기

AI 보안 서버에 귀속되는 지속적 웹훅 실패가 회로 차단기를 작동시켜 집행을 멈춰요. 더 이상 서버에 연락하지 않고 Failure handling 선택이 모든 검사된 요청에 적용돼요. Block the request를 선택하면 차단기가 리셋될 때까지 조직의 사용자가 차단돼요. 차단기가 작동하면 claude.ai 알림 센터에서 관리자에게도 알림이 가요.

각 작동도 조직의 Activity Feed에 inference_hooks_circuit_breaker_tripped 활동으로 기록돼요. 그래서 보안 팀이나 벤더가 피드를 수집하는 SIEM 같은 이미 운영 중인 모니터링으로 작동에 경고할 수 있어요. 작동당 활동 하나가 기록되며 영향받은 요청당이 아니에요. 기록하려면 조직에 Compliance API가 활성화되어 있어야 해요. Compliance API 설정 참고.

복구하려면 서버를 고친 뒤 Enforce verdicts를 다시 켜 차단기를 리셋하세요.

차단기는 자체적으로도 리셋될 수 있어요. 작동 후 10분부터 Anthropic은 서버가 복구됐는지 백그라운드에서 그 서버에 테스트 요청을 보내 확인해요. 최대 대략 1분에 한 번. 사용자 요청은 관여하지 않아요. 서버가 유효한 평결(allow든 deny든)로 응답하면 차단기가 리셋되고 집행이 재개돼요. 그렇지 않으면 차단기가 작동한 채 유지되고 확인을 계속해요.

자동 복구는 작동 이후 Inference hooks 설정이 변하지 않은 동안에만 실행돼요. 작동 후 서명 비밀 교체를 포함해 어떤 Inference hooks 설정을 바꾸면 확인이 멈추고 차단기는 더 이상 자체 리셋되지 않아요. 서버가 고쳐지면 Enforce verdicts를 다시 켜세요. 자동 복구는 작동에만 적용돼요. 직접 Enforce verdicts를 껐다면 다시 켤 때까지 집행이 꺼진 채 유지돼요.

서명 비밀 교체

Request signing 아래 Rotate secret을 클릭해 서명 비밀을 교체하세요. 조직에 비밀이 아직 없으면 같은 버튼이 Generate secret으로 읽히고 첫 비밀을 만들어요. 교체는 즉시 전환(cutover)이에요. 새 비밀이 생성되어 한 번 보여지고, 이전 비밀은 더 이상 조회할 수 없으며, 어떤 요청도 두 비밀로 서명되지 않으므로 의존할 겹침 기간이 없어요.

이전 비밀로 서명된 요청은 교체 후 잠시 도착할 수 있어요. AI 보안 서버가 전환을 처리해야 하는 방법은 서명 검증이 다뤄요.

감사 기록

Inference hooks 활동은 조직의 Activity Feed에 기록돼요: 구성 변경, 거부, 회로 차단기 작동, 실패 처리 설정 아래 검사 없이 진행된 요청. 회로 차단기가 작동 중인 동안에는 요청별 Inference hooks 활동이 기록되지 않아요. 작동 활동이 그 창의 피드 기록이에요. 거부 기록은 각 거부를 자체 시스템의 일치하는 기록에 조인할 수 있는 식별자를 담아요.

Inference hooks 끄기

off에는 두 수준이 있어요:

Enforce verdicts 끔, Inference hooks 설정 페이지에서: 약 1분 안에 조직의 프롬프트가 AI 보안 서버로 보내지지 않게 돼요. 이미 진행 중인 요청은 이전 설정으로 끝나요. 설정 페이지는 계속 사용 가능하므로 AI 보안 서버를 작업하는 동안 집행을 일시 중지하는 데 사용하세요.
Allow for your organization 끔, Data and privacy 설정에서: 프롬프트가 더 이상 검사되지 않고 Inference hooks 설정이 다시 켤 때까지 사용 불가해져요. 엔드포인트 구성, 커스텀 헤더, 서명 비밀은 어느 쪽이든 유지돼요. 다시 켜면 Enforce verdicts를 강제로 끄고 작동된 회로 차단기를 지우므로 준비가 되면 집행을 다시 켜세요.

다음 단계

Inference hooks 통합 개발 — 이동 — AI 보안 서버 구축: 요청·평결 스키마, 서명 검증, 운영 의미.
Inference hooks 개요 — 이동 — Inference hooks가 무엇인지, 평결 왕복이 어떻게 작동하는지, AI 보안 서버로 무엇이 보내지는지.

Inference hooks 구성