Claude Code HTTP Hooks: 웹앱으로 AI 에이전트 제어하기

Claude Code HTTP Hooks: 웹앱으로 AI 에이전트 제어하기

••4분 읽기•원문 보기

Claude Code 쓰면서 "이 작업 승인 여부를 웹 대시보드에서 관리할 수 있으면 좋겠는데..."라고 생각해본 적 있으세요?

이제 가능합니다. Claude Code에 HTTP Hook 기능이 추가되었습니다.

HTTP Hook이 뭔가요?

기존 커맨드 훅(Command Hook)은 강력하지만 복잡했습니다:

  • 쉘 스크립트 작성 필요
  • 보안 관리 까다로움
  • 상태 공유 어려움

HTTP Hook은 이걸 완전히 바꿉니다:

Claude Code 이벤트 발생
 ↓
HTTP POST → 웹 서버 (localhost도 가능)
 ↓
웹 서버가 응답 (승인/거부/수정)
 ↓
Claude Code가 응답에 따라 행동

왜 이게 중요한가?

1. 웹앱으로 제어 가능

// Express.js 예시
app.post('/claude-hook', (req, res) => {
 const { event, context } = req.body;
 
 if (event.type === 'file_write') {
 // 파일 쓰기 승인 여부를 웹 대시보드에서 확인
 if (isDangerousPath(event.path)) {
 res.json({ approved: false, reason: 'Sensitive file' });
 } else {
 res.json({ approved: true });
 }
 }
});

이제 브라우저에서 실시간으로:

  • Claude Code가 뭘 하려는지 확인
  • 승인/거부 버튼 클릭
  • 로그 확인 및 저장

2. 팀 단위 권한 관리

데이터베이스 ←→ 웹 서버 ←→ Claude Code
  • 중앙 DB로 권한 관리: 누가 어떤 작업을 승인했는지 추적
  • 팀원과 공유: 같은 웹앱으로 여러 Claude Code 인스턴스 제어
  • 감사 기록: 모든 이벤트를 DB에 저장

3. 복잡한 로직도 쉽게

쉘 스크립트로는 어려웠던 것들:

  • REST API 호출
  • 데이터베이스 쿼리
  • 복잡한 조건문
  • 실시간 알림

웹 서버에서는:

  • 모든 npm 패키지 사용 가능
  • Prisma, TypeORM 등으로 DB 연동
  • TypeScript로 타입 안전하게
  • Slack/Discord 웹훅 바로 연동

실전 활용 예시

예시 1: 민감한 파일 보호

// hooks/file-protection.ts
const PROTECTED_PATHS = [
 '.env',
 'secrets/',
 'config/production.yml'
];
 
app.post('/hook', async (req, res) => {
 if (req.body.event.type === 'file_write') {
 const path = req.body.event.path;
 
 if (PROTECTED_PATHS.some(p => path.includes(p))) {
 // Slack으로 알림 전송
 await slackNotify({
 text: ` Claude Code가 민감한 파일 수정 시도: ${path}`,
 channel: '#security'
 });
 
 return res.json({
 approved: false,
 message: '민감한 파일은 수동 승인이 필요합니다.'
 });
 }
 }
 
 res.json({ approved: true });
});

예시 2: 비용 관리

// hooks/cost-tracking.ts
app.post('/hook', async (req, res) => {
 const { event, context } = req.body;
 
 // API 호출 비용 추적
 if (event.type === 'api_call') {
 const cost = estimateCost(event.model, event.tokens);
 
 await db.usage.create({
 data: {
 userId: context.user,
 model: event.model,
 tokens: event.tokens,
 cost: cost
 }
 });
 
 // 일일 한도 체크
 const todayTotal = await db.usage.sum({ where: { 
 userId: context.user,
 date: new Date()
 }});
 
 if (todayTotal > DAILY_LIMIT) {
 return res.json({
 approved: false,
 message: '오늘 일일 한도를 초과했습니다.'
 });
 }
 }
 
 res.json({ approved: true });
});

예시 3: 작업 승인 대시보드

// 실시간 승인 대시보드
app.get('/dashboard', (req, res) => {
 res.render('dashboard', {
 pendingActions: await getPendingActions()
 });
});
 
// 웹소켓으로 실시간 이벤트 전송
io.on('connection', (socket) => {
 socket.on('approve', async (eventId) => {
 await approveEvent(eventId);
 io.emit('event_approved', eventId);
 });
});

로컬호스트도 가능!

가장 좋은 점:

# 1. 로컬에서 웹 서버 실행
npm run dev # http://localhost:3000
 
# 2. Claude Code 설정
claude-code --http-hook=http://localhost:3000/hook

외부 서버 필요 없음. 개발 머신에서 바로 테스트 가능합니다.

기존 커맨드 훅과 비교

기능커맨드 훅HTTP 훅
설정 난이도높음 (스크립트)낮음 (웹 API)
복잡한 로직어려움쉬움
팀 공유어려움쉬움
실시간 대시보드불가능가능
보안 관리복잡함명확함 (HTTP)
디버깅어려움쉬움 (로그/UI)

시작하기

  1. 공식 문서 확인 Claude Code Hooks Reference

  2. 간단한 서버로 시작
import express from 'express';
 
const app = express();
app.use(express.json());
 
app.post('/hook', (req, res) => {
console.log('Event:', req.body);
res.json({ approved: true });
});
 
app.listen(3000);
  1. Claude Code 연결
claude-code --http-hook=http://localhost:3000/hook

마무리하며

HTTP Hook는 Claude Code를 "혼자 쓰는 도구"에서 "팀이 관리하는 인프라"로 바꿔줍니다.

특히:

  • 민감한 작업이 많은 프로덕션 환경
  • 여러 사람이 Claude Code를 쓰는 팀
  • 승인 프로세스가 필요한 조직

에서 정말 유용할 것 같습니다.

여러분은 어떤 Hook을 만들어보고 싶으신가요?


이 글은 Geeknews에서 발견한 내용을 정리한 것입니다. 원본은 여기에서 확인할 수 있습니다.

광고

T
TomAI 코딩 도구를 매일 쓰는 개발자

Claude Code, OpenCode 같은 AI 코딩 도구를 직접 쓰면서 AI 업계의 변화를 개발자 관점에서 기록합니다. 단순 번역이 아니라 써본 경험과 해석을 함께 남기려고 해요.

AI 소식릴리스

Claude Code 2.1.248→251: 릴리스 노트의 첫 줄이 '제한 모드'다 — 통제 기능이 앞에 온다는 말은 사실인가

8월 27일과 28일에 나온 Claude Code 2.1.248과 2.1.251의 첫 항목은 각각 --restricted 플래그와 모델 전환을 막는 훅이에요. '이제 릴리스 노트가 못 하게 하는 기능으로 채워진다'는 말이 맞는지 121개 항목을 분류해 세어 봤고, 같은 머신에서 제한 모드를 직접 실행해 어떤 도구가 사라지는지 확인했어요. SDK 1.1.0·1.2.0도 한 문답으로 다뤄요.

AI 소식칼럼

서브에이전트 2,393개, 로그 731GiB — 에이전트 폭주의 청구서가 도착했다

지난주 '멈추는 능력이 제품이 됐다'고 썼는데, 일주일 만에 물증이 나왔어요. Codex CLI 사용자의 홈 디렉토리에 쌓인 731.5GiB의 세션 로그, 그리고 같은 주에 OpenCode·Claude Code·oh-my-opencode가 일제히 추가한 깊이 제한·스폰 캡·대기 규율. 폭주는 이제 이론이 아니라 디스크와 청구서의 문제예요.

AI 소식칼럼

에이전트가 8시간 폭주한 뒤 — 자율이 기본값이 되자 '멈추는 능력'이 제품이 됐다

Claude Code는 Auto 모드를 기본으로 풀고, Gemini는 백그라운드 실행을 API에 넣고, oh-my-opencode는 8시간 폭주 사고를 부검했어요. 저는 이 세 발표가 같은 문장이라고 봐요. 자율 실행이 기본값이 된 지금, 경쟁력은 '시작하는 능력'이 아니라 '멈추는 능력'으로 옮겨갔어요.