레퍼런스
설정
도구 권한, 훅 연결, 환경 변수, 상태 표시줄 템플릿을 다루는 settings.json의 Claude Code 하니스 구성입니다.
settings.json은 Claude Code 하니스 구성, 즉 훅 연결, 도구 권한, 환경 변수,
상태 표시줄 설정을 담습니다.
전체 정식 레퍼런스는 settings-reference.md에 있습니다. 이 페이지는 계약을 요약하고 더 자세한 레퍼런스를 가리킵니다.
섹션
| 섹션 | 목적 |
|---|---|
permissions | 매처별 도구 화이트리스트와 블랙리스트 |
hooks | 이벤트를 키로 하는 훅 명령 표(정식 연결) |
env | 세션별 환경 변수 |
statusLine | 호스트가 렌더링하는 상태 표시줄 템플릿 |
단일 템플릿 불변 조건
Claude Code 어댑터는 settings.json 템플릿 하나를 배포합니다. 훅 명령은 셸별
명령 문자열 대신 exec 형식(command과 args)을 사용하므로, OS 간 동작을 한
파일 안에서 검토합니다. 새 권한 항목과 훅 이벤트는 그 파일에 원자적으로
안착합니다.
여러분의 설정 파일에 병합하기
settings.json은 여러분의 파일이기도 합니다. 설치는 템플릿으로 이 파일을
교체하지 않고 템플릿을 이 파일에 병합하며, 정확히 어떤 키와 목록 항목을
추가했는지를 설치 원장(~/.apothem/state/<harness>/ledger.jsonl)에 기록합니다.
permissions.allow와permissions.deny는 합집합으로 병합됩니다. 여러분의 규칙이 앞에 그대로 남고 Apothem의 규칙이 뒤에 추가됩니다. 여러분이 작성한 거부 규칙은 항상 유지되며, Claude Code는 허용 규칙보다 거부 규칙을 먼저 적용합니다.- 여러분의 훅 핸들러는 그대로 남습니다. 핸들러는 Apothem이 하니스 루트 아래에
설치한 스크립트를 실행할 때에만 Apothem의 것으로 간주되므로, 다른
hooks/dispatch.py를 호출하는 핸들러는 여러분의 것입니다. - 재설치는 Apothem이 지난번에 추가한 것만 교체하므로, 템플릿에서 빠진 항목은 제거되고 여러분이 추가한 항목은 유지됩니다.
- 제거는 원장에 Apothem의 것으로 기록된 항목만 제거합니다. 우연히 Apothem의
규칙과 같은 규칙(예: 첫 설치 전에 여러분의
allow목록에 있던Read)은 남습니다. 파일은 Apothem이 만들었고 여러분의 것이 하나도 남지 않은 경우에만 삭제됩니다.
같은 규칙이 Apothem이 병합하는 다른 설정 파일에도 적용됩니다. 예를 들어
Qwen Code의 settings.json과 OpenCode의 opencode.json에 있는 MCP 서버 맵이
그렇습니다.