공식 저장소는 현재 딥시크 하네스를 개발자 미리보기 단계로 안내하며, 호환성이 깨지는 변경이 있을 수 있다고 명시합니다. 공식 저장소의 현재 안내는 설정을 한 번에 완성하기보다 작은 단위로 다시 검증해야 한다는 근거가 됩니다. 따라서 딥시크 하네스 훅 구성은 하나의 관찰 가능한 차단 지점에서 시작하고, 실패하면 통과시키지 않는 방식으로 운영하는 편이 안전합니다. 훅을 여러 개 복사하거나 운영체제 수준의 격리 장치처럼 사용하면 안 됩니다.
이 글은 도구 호출 전후에 검사를 넣으려는 에이전트 개발자, 프로젝트와 환경별 설정을 관리하는 플랫폼 엔지니어, 원격 맥에서 중단과 재시작까지 책임지는 운영 담당자를 위한 안내입니다. 단순한 설정 예시보다 준비, 최초 연결, 확장, 원격 배포, 최종 승인 순서에 집중합니다.
[ SECTION_01 ] 시작 전 제어 목표
훅을 구성하기 전에 제어 목표를 하나만 정해야 합니다. 권한 차단, 실행 결과 기록, 에이전트 중지 조건, 추가 문맥 주입은 서로 다른 작업입니다. 첫 훅에서 네 가지를 모두 처리하면 실패 원인을 분리하기 어렵습니다.
가장 안전한 시작점은 도구 실행 전 검사입니다. 흔히 프리툴유즈라고 부르는 지점에서는 도구 이름과 입력값을 확인한 뒤 통과 또는 거부를 결정합니다. 다만 훅은 에이전트의 실행 흐름을 제어할 뿐입니다. 작업 공간 밖의 파일 접근, 비밀값 노출, 운영체제 권한 상승을 자동으로 격리하는 보안 장치는 아닙니다. 파일 권한, 계정 권한, 작업 공간 제한은 별도로 설정해야 합니다.
현재 저장소의 구조 안내와 실행 방식은 개발자 미리보기와 빠른 변경 가능성을 전제로 합니다. 따라서 다른 에이전트의 설정 파일을 그대로 복사하지 말고, 작성 시점의 프로토콜과 실행 파이프라인을 다시 대조해야 합니다.
[ SECTION_02 ] 최소 규칙의 최초 연결
첫 구성에서는 위험도가 낮고 결과를 쉽게 확인할 수 있는 도구 하나만 선택합니다. 읽기 전용 조회나 작업 공간 안의 상태 확인처럼 부작용이 적은 호출이 적합합니다.
구성 위치는 저장소의 최신 문서와 실행 코드에서 확인해야 합니다. 현재 공개 저장소에는 플러그인과 실행 구조가 빠르게 변경될 수 있다는 안내가 있으므로, 특정 경로와 설정 키를 오래된 글에서 가져오면 안 됩니다. 최신 변경 기록에서 사용 중인 버전을 먼저 확인하고, 해당 버전의 문서와 소스에서 훅 프로토콜을 대조합니다.
최초 훅은 다음 정보만 남기면 충분합니다.
- 어떤 이벤트가 발생했는지
- 어떤 도구가 선택됐는지
- 입력값의 안전한 요약
- 훅이 통과 또는 거부를 반환했는지
- 매칭되지 않은 호출이었는지
- 처리에 실패했는지
비밀값, 인증 토큰, 고객의 실제 경로는 기록하지 않습니다. 입력 전체를 남기는 방식은 나중에 로그 자체가 새로운 유출 지점이 될 수 있습니다.
딥시크 하네스 훅 구성 파일은 어디에 두어야 합니까?
정답은 고정된 다른 에이전트 경로가 아닙니다. 사용 중인 릴리스가 읽는 설정 디렉터리와 플러그인 적재 경로를 공식 저장소에서 확인해야 합니다. 저장소는 플러그인 중심 구조를 사용한다고 설명하지만, 개발자 미리보기인 만큼 특정 훅 파일명이나 위치를 보편 규칙처럼 단정하면 안 됩니다. 공식 개발 문서를 기준으로 실제 읽기 경로를 확인한 뒤 구성합니다.
[ SECTION_03 ] 실패 전략과 허용 범위
최초 연결이 끝나면 같은 규칙으로 네 가지 상황을 재현합니다. 명확한 허용, 명확한 거부, 훅 프로세스 오류, 훅 응답 지연입니다. 설정 문장만 보고 실패 시 에이전트가 계속된다고 추정하면 안 됩니다. 세션 이벤트나 실행 결과에서 실제 동작을 확인해야 합니다.
실패 결과가 분명하지 않다면 거부 상태를 유지합니다. 특히 명령 실행이나 파일 쓰기와 연결된 훅은 자동 통과로 바꾸지 않는 편이 좋습니다. 실패가 발생했는데도 도구가 실행되었다면, 해당 훅은 차단 장치가 아니라 기록 장치로만 취급하고 권한 설계를 다시 나눠야 합니다.
주의: 다른 도구의 훅은 실패 시 자동 통과하거나, 표준 출력에 특정 구조를 요구할 수 있습니다. 딥시크 하네스에 같은 동작이 있다고 가정하지 말고, 현재 버전의 입력과 출력 계약을 직접 확인해야 합니다.
훅 스크립트가 실패하면 에이전트가 계속 진행합니까?
일률적으로 답할 수 없습니다. 공식 저장소가 개발자 미리보기와 호환성 변경 가능성을 명시하고 있으므로, 실패 기본값은 소스와 실행 이벤트를 기준으로 확인해야 합니다. 실제 검증에서는 오류 종료, 응답 없음, 잘못된 출력의 세 경우를 따로 기록합니다. 결과가 불명확하면 통과시키지 않고, 원래 훅을 보존한 채 더 단순한 검사로 되돌립니다.
[ SECTION_04 ] 명령과 쓰기 작업의 확장
읽기 전용 호출이 안정된 뒤에만 명령 실행, 파일 수정, 외부 도구 연결을 한 종류씩 추가합니다. 확장할 때는 다음 경계를 함께 고정해야 합니다.
- 허용 작업 공간과 금지 경로
- 훅 프로세스가 볼 수 있는 환경 변수
- 허용할 명령 인자 형태
- 표준 출력과 오류 출력의 처리 방식
- 시간 초과 뒤의 복구 절차
- 이전 설정으로 돌아가는 방법
매칭 규칙이 너무 넓으면 정상적인 작업까지 막힙니다. 반대로 도구 이름만 보고 매칭하면 같은 기능의 변형 호출을 놓칠 수 있습니다. 명령 이름, 작업 경로, 인자 유형을 함께 확인하되 처음부터 복잡한 정규식으로 만들지 않는 것이 좋습니다.
| 선택지 | 주된 목적 | 장점 | 위험 | 권장도 |
|---|---|---|---|---|
| 실행 전 차단 | 위험 도구 허용 여부 결정 | 실패를 빠르게 멈출 수 있음 | 규칙이 넓으면 정상 작업도 중단됨 | 5점 |
| 실행 후 기록 | 결과와 오류 보관 | 원인 분석이 쉬움 | 이미 실행된 작업은 되돌리지 못함 | 4점 |
| 중지 조건 검사 | 반복 실행이나 종료 시점 확인 | 장기 작업 통제가 쉬움 | 중지 기준이 모호하면 세션이 멈춤 | 3점 |
| 문맥 보충 | 실행 전 참고 정보 추가 | 작업 설명을 풍부하게 만들 수 있음 | 민감한 정보가 전달될 수 있음 | 2점 |
평가는 보안 차단을 처음 도입하는 운영 관점의 판단입니다. 실제 선택은 도구의 부작용과 복구 가능성을 함께 따져야 합니다.
훅으로 위험한 명령을 막으려면 어떻게 해야 합니까?
명령 문자열 전체를 무조건 차단하기보다 실행 전 이벤트에서 도구 종류, 작업 공간, 인자 유형을 확인합니다. 위험한 삭제나 외부 전송처럼 되돌리기 어려운 작업은 명시적 허용 목록에 없는 한 거부하도록 설계합니다. 그래도 운영체제 권한이나 파일 권한을 대신하지는 않으므로, 훅과 계정 격리를 함께 사용해야 합니다.
[ SECTION_05 ] 원격 맥 배포와 재시작 확인
로컬에서 통과한 훅을 원격 맥으로 옮길 때는 파일만 복사하면 안 됩니다. 스크립트가 사용하는 실행 환경, 인터프리터 경로, 파일 권한, 환경 변수, 현재 작업 디렉터리를 각각 확인해야 합니다.
원격 환경에서는 다음 순서로 점검합니다.
첫째, 훅 파일이 실제 배포 경로에 존재하는지 확인합니다.
둘째, 실행 계정이 파일을 읽고 실행할 수 있는지 확인합니다.
셋째, 대화형 셸에서만 설정되는 경로에 의존하지 않는지 확인합니다.
넷째, 작업 디렉터리가 바뀌어도 매칭 규칙이 올바르게 작동하는지 확인합니다.
다섯째, 연결이 끊긴 뒤 다시 접속해도 훅과 로그가 남아 있는지 확인합니다.
여섯째, 재시작 후 허용 작업과 거부 작업을 다시 실행합니다.
원격 맥을 재시작한 뒤에도 훅이 계속 적용됩니까?
파일이 남아 있다는 사실만으로는 부족합니다. 하네스가 다시 시작될 때 같은 설정 경로를 읽고, 같은 실행 계정과 작업 공간을 사용하며, 필요한 실행 환경을 찾는지 확인해야 합니다. 재시작 전후에 동일한 허용 작업과 거부 작업을 실행하고, 이벤트 기록의 버전과 작업 경로를 비교해야 합니다.
원격 환경을 장기 작업에 사용할 계획이라면 맥 미니 대여 비용과 운영 조건도 함께 확인하는 것이 좋습니다. 훅 자체보다 재시작 복구, 접속 방식, 로그 보존 조건이 전체 운영 안정성을 좌우하기 때문입니다.
[ SECTION_06 ] 최종 승인 기록
가동 전에는 허용 작업, 거부 작업, 비정상 훅, 복구 작업을 각각 남깁니다. 각 기록에는 다음 항목을 포함합니다.
- 하네스와 훅 버전
- 실행한 작업 공간
- 발생한 이벤트 지점
- 도구와 입력 요약
- 허용 또는 거부 결과
- 실패 원인
- 이전 설정으로 돌아간 시점
- 재시작 후 재검증 결과
공식 저장소의 현재 릴리스가 개발자 미리보기라는 점을 고려하면, 승인 기록은 단순한 운영 메모가 아닙니다. 다음 업데이트에서 설정 계약이 바뀌었는지 비교하는 기준이 됩니다. 공식 변경 기록을 배포 전후에 저장해 두면 변경 원인을 좁히기 쉽습니다.
로컬에서 네 가지 테스트를 모두 통과하지 못했다면 원격 배포를 미루는 편이 낫습니다. 특히 오류와 시간 초과의 결과가 다르지 않거나, 거부 로그는 남지만 도구가 실행된다면 훅을 권한 통제 장치로 사용해서는 안 됩니다.
현재 방식이 로컬 맥에서만 동작한다면 재시작 때 설정이 빠지고, 작업 디렉터리가 달라지며, 대화형 환경에만 있는 실행 경로를 놓칠 수 있습니다. 반대로 NOVAKVM의 원격 맥 환경을 사용하면 배포 전에 스크립트 의존성, 재시작 복구, 로그 보존 조건을 별도로 확인할 수 있습니다. 이미 로컬 훅이 네 가지 테스트를 통과했다면, 원격 맥 주문과 운영 조건을 대조한 뒤 지속 작업을 열어 두는 방식이 현실적입니다. 장기 고정 부하나 직접 연결해야 하는 물리 장치가 필요한 경우에는 자가 구매가 더 적합하지만, 임시 검증과 원격 에이전트 시험이라면 필요한 기간만 맥 환경을 확보하는 편이 변경 위험을 줄일 수 있습니다.