Claude inference hooks: 모든 프롬프트 앞에 허용 또는 거부 검사를

inference hooks의 작동 방식

조직(또는 조직의 보안 벤더)이 AI 보안 서버, 즉 HTTPS 엔드포인트를 운영해요. 누군가 프롬프트를 보내면 Anthropic은 대화 기록을 Standard Webhooks 방식으로 서명해 그 엔드포인트에 POST하고 판정을 기다려요. allow면 추론이 그대로 진행되고, deny면 요청이 모델에 닿지 않으며 사용자에게는 여러분이 보낸 사유와 관리자가 미리 정해 둔 안내 문구가 표시돼요.

• 이벤트는 두 가지예요. prompt는 관리 대상인 추론 요청 전마다, tool_call은 Validate tool calls(도구 호출 검증)가 켜져 있을 때 Claude 응답 속 도구 호출이 실행되기 전에 전송돼요.
• 조직 전체에 한 번만 설정하면 돼요. claude.ai, Claude Desktop과 모바일, Claude Code(CLI 포함), Cowork, Claude for Microsoft 365, Claude Tag, Claude in Chrome에 적용돼요.
• 서버가 보는 내용은 대화 기록 텍스트, 도구 호출과 그 결과, 첨부 파일에서 추출한 텍스트예요. 원본 파일이나 이미지 바이트, 시스템 프롬프트, 도구 정의는 절대 전송되지 않아요.
• 판정은 allow 아니면 deny뿐이에요. 프롬프트를 고쳐 쓰거나 마스킹하는 기능은 지원하지 않아요.
• 모든 거부는 조직의 Activity Feed(활동 피드)에 기록돼요.

inference hooks vs Claude Code hooks vs Compliance API

이름은 비슷하지만 세 가지는 서로 다른 도구예요. Claude Code hooks는 프로젝트별 또는 사용자별로 설정하고 개발자 컴퓨터에서 실행돼요. inference hooks는 조직이 한 번 설정하고 Anthropic 쪽에서 실행돼요.

inference hooks 설정 방법

Owner 또는 Primary owner 역할(Admin으로는 부족해요)과 443 포트를 쓰는 공개 HTTPS 엔드포인트가 필요해요. ngrok 같은 터널은 차단되니 테스트 서버도 직접 관리하는 도메인에 올려 두세요.

1. 기능 허용하기

   claude.ai에서 Organization settings → Data and privacy(조직 설정 → 데이터 및 개인정보)를 열고 Inference hooks 아래의 Allow for your organization(조직에 허용)을 켜세요. 이것만으로는 검사가 시작되지 않아요. Enforce verdicts(판정 적용)는 꺼진 상태로 남아요.

2. 엔드포인트를 추가하고 서명 시크릿 보관하기

   Configure(구성)를 누르고 https:// URL을 입력해 저장하세요. 처음 저장할 때 webhook 서명 시크릿이 한 번만 표시돼요. 서버가 모든 요청을 검증하는 데 쓰니 꼭 보관해 두세요.

3. 헤더를 추가하고 테스트하기

   서버가 Anthropic의 요청인지 인증할 수 있도록 정적 헤더를 최대 16개까지 추가한 뒤 Test connection(연결 테스트)을 누르세요. 합성 프롬프트를 보내고 판정 결과와 왕복 시간을 알려 줘요.

4. 판정을 HTTP 200 JSON으로 반환하기

   모든 요청에 HTTP 200과 action으로 응답하세요. 200이 아닌 상태 코드는 거부가 아니라 장애로 처리돼요.

   // 요청 허용
   { "action": "allow" }
   
   // 거부: deny_reason은 사용자에게 표시되고(최대 500자),
   // reference_id는 컴플라이언스 활동 피드에만 기록됨
   {
     "action": "deny",
     "deny_reason": "이 프롬프트에 고객 카드 정보가 포함된 것으로 보입니다.",
     "reference_id": "scan_01HXPT4R9V"
   }

5. 장애 처리 방식과 타임아웃 정하기

   Block the request(요청 차단)는 fail closed, Allow the request(요청 허용)는 fail open이에요. 판정 타임아웃은 1~10,000ms이고 기본값은 5,000이에요. 판정이 늦으면 연결 불가로 간주돼요. 실패가 반복되면 서킷 브레이커가 작동해 서버가 복구될 때까지 장애 처리 설정을 적용해요.

6. 단계적으로 도입한 뒤 적용하기

   판정만 보내고 아무것도 차단하지 않는 Shadow mode(섀도 모드)로 시작해, 일부 비율의 요청만 검사하고 필요하면 사용자 지정 역할을 제외한 다음 Enforce verdicts를 켜세요. 변경 사항은 약 1분 안에 모든 서버에 반영돼요.

출처: Claude Platform 문서, Inference hooks

제한 사항과 주의할 점

• Enterprise 전용이에요. Team, Pro, Max에서는 쓸 수 없고, Claude Platform(API) 조직이나 Amazon Bedrock, Google Cloud에서도 쓸 수 없어요.
• 문서 스크린숏처럼 이미지로만 된 콘텐츠는 검사되지 않아요. 원본 바이트는 전송되지 않기 때문이에요.
• 거부된 메시지는 대화 기록에 남아 이후 메시지를 보낼 때마다 다시 전송돼요. Claude Code에서는 /rewind로 그 메시지를 가져온 프롬프트까지 되돌리거나 /clear로 새로 시작하세요.
• Anthropic 자체의 일부 백그라운드 모델 호출은 관리 대상이 아니에요. 호스팅되는 Claude Security 스캔, GitHub 풀 리퀘스트의 Code Review, 스마트 리포트 등이 그래요. Claude Code에서 로컬로 /code-review를 실행하는 경우는 관리 대상이에요.
• 음성 모드에서는 도구 호출 일부가 전송되지 않으니, 거기서는 hooks를 유일한 통제 수단으로 삼지 마세요.
• 같은 발표에서 Claude, Cowork, Claude Code 설정을 Anthropic 권장 구성과 비교해 주는 보안 센터(베타)와, 베타 버전의 중앙 관리 및 접근 제어도 추가됐어요.

스스로 일하는 에이전트에게 이게 중요한 이유

Claude Code가 사람 없이, 일정에 따라 또는 백그라운드에서 일할 때는 프롬프트가 전송되기 전에 하나하나 읽는 사람이 없어요. inference hooks가 있으면 에이전트가 어디서 실행되든 회사가 모든 요청과 도구 호출에 인라인 검사를 하나 걸 수 있고, 섀도 모드로 보안 팀이 실제로 차단하기 전에 정책을 다듬을 수 있어요. 한 컴퓨터에서 프로젝트 단위로 거는 가드레일에는 여전히 Claude Code 자체의 hooks와 권한 규칙이 적용돼요. 권한 모드는 Claude Code 플랜 모드를 참고하세요.

내가 없는 동안에도 일하는 AI 직원에게 가드레일을

Crewmark는 Claude Code, Codex, DeepSeek Harness, OpenCode 세션을 직무, 목표, 근무 시간을 가진 AI 직원으로 바꾸고, 하트비트로 깨워서 보드의 다음 이슈를 가져가게 해요. Claude Enterprise 요금제라면 inference hooks가 다른 사람과 똑같이 이 직원의 프롬프트도 검사해요.

1. 내 승인이 필요한 일 정하기

   게시, 병합, 결제처럼 위험한 작업 전에는 직원이 먼저 물어보고, 나는 하나의 받은편지함에서 승인해요.

2. 기록은 보드에 남기기

   이슈마다 직원의 댓글과 상태 변경이 남아서, 직원이 한 일을 보안 팀의 로그와 나란히 놓고 검토할 수 있어요.

3. 하트비트가 일을 시작하게 하기

   근무 시간에는 직원이 같은 대화 안에서 15분, 30분 또는 60분마다 깨어나요. Claude Code를 능동적으로 만드는 방법과 AI 직원이란도 읽어 보세요.

Claude inference hooks FAQ