클라이언트 연동고급 사용자업데이트

Claude Code 자동화 설정: 확인과 대기 줄이기

permissions.defaultMode를 auto로 설정하고 Bash 시간 초과와 작업 공간 디렉터리를 함께 지정하면, Claude Code가 대부분의 도구 호출을 스스로 판단하고 실제로 결정이 필요한 순간에만 멈춥니다. 이 페이지에서는 ~/.claude/settings.json에 그대로 복사할 수 있는 설정을 제공하고, 각 항목이 어떤 실제 문제를 해결하는지 설명합니다.

설정은 클라이언트 동작에만 영향을 주며 모델 기능, 과금 규칙, API Key 권한은 바뀌지 않습니다. 클라이언트를 아직 설치하지 않았다면 먼저 Claude Code 설치 안내에 따라 설치와 키 설정을 마친 뒤 이 페이지로 돌아와 사용 환경을 조정하세요.

먼저 세 가지 “불편함”을 구분하기

대부분은 문제가 계속 확인을 눌러야 하는 데 있다고 생각하지만, 실제로 살펴보면 시간이 걸리는 원인은 대개 다른 세 곳에 있습니다. 설정을 한꺼번에 따라 하기보다 원인을 먼저 찾고 나서 고치는 편이 더 효과적입니다.

증상실제 원인관련 설정
명령마다 몇 초씩 기다림자동 모드 판정이 매번 실행됨allow 규칙으로 자주 쓰는 명령을 판정에서 제외
명령 실행 중 시간 초과 실패Bash 기본 제한 시간은 120초, 최대 600초BASH_DEFAULT_TIMEOUT_MS
프로젝트 외부 파일을 읽을 때 다시 묻음경로가 작업 디렉터리 안에 없음additionalDirectories

그중 첫 번째를 가장 잘 이해해 둘 만합니다. allow 규칙에 걸린 도구 호출은 판정 과정을 거치지 않으므로, 규칙을 보강하면 질문도 줄고 대기 시간도 줄어듭니다. 가장 효율이 좋은 조정입니다.

설정 요약

아래 내용을 ~/.claude/settings.json에 기록하세요. <꺾쇠괄호>가 있는 부분은 본인의 값으로 바꿔야 합니다. 설정 파일은 // 주석을 허용하지만, 사용하는 버전이 이를 지원하지 않는다면 주석을 지우고 순수 JSON으로 저장하면 됩니다.

json
{
  "permissions": {
    "defaultMode": "auto",
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Read(//home/<사용자 이름>/.ssh/**)"
    ],
    "ask": [
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(rm -rf*)"
    ],
    "additionalDirectories": [
      "/home/<사용자 이름>/deploy"
    ]
  },
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "300000",
    "BASH_MAX_TIMEOUT_MS": "1800000"
  }
}

이 사이트의 Claude Code 접속을 사용한다면 env의 ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL과 모델 변수는 DeepSeek 연결 안내 또는 해당 모델 페이지에 따라 입력하고, 이 페이지의 BASH_* 항목과 혼동하지 마세요.

항목별 설명

permissions.defaultMode 를 auto로 설정하면 새 세션이 곧바로 자동 모드로 시작되며, 클라이언트가 각 도구 호출의 허용과 차단을 판단합니다. 대화형 화면에서 Shift + Tab을 눌러 순환 전환할 수도 있고, 시작할 때 claude --permission-mode auto를 사용할 수도 있습니다.

permissions.allow 는 좁은 규칙부터 넓은 규칙까지 지정할 수 있으며, 예를 들어 Bash(git status), Bash(go test *) 등이 있습니다. 넓은 규칙에는 대가가 따른다는 점에 유의하세요. Bash(bash *), Bash(ssh *), Bash(curl *) 같은 표기는 사실상 “임의 명령 실행 허용”에 가깝고 판정을 완전히 건너뛰게 만듭니다. 넓은 규칙이 정말 필요하다면 반드시 deny나 ask로 안전장치를 함께 두어야 합니다.

permissions.deny와 permissions.ask 의 우선순위는 deny가 ask보다, ask가 allow보다 높으므로 넓은 allow 규칙을 덮어쓸 수 있습니다. deny는 무조건 거부이고, ask는 allow에 걸리더라도 반드시 확인을 요구합니다. 자격 증명 디렉터리는 deny에, 파괴적인 명령은 ask에 넣는 것을 권장합니다.

additionalDirectories 는 작업 디렉터리 밖에 있지만 자주 읽고 써야 하는 경로를 등록하는 데 사용합니다. 등록하지 않으면 작업 공간 밖 파일을 처음 읽을 때 추가로 한 번 묻습니다.

BASH_DEFAULT_TIMEOUT_MS와 BASH_MAX_TIMEOUT_MS 의 기본값은 120초와 600초입니다. 컴파일, 빌드, 다른 머신을 대상으로 한 작업은 상한에 닿기 쉬우며, 한 번 시간 초과가 나면 전체를 다시 실행해야 합니다. 예제에서는 5분과 30분으로 늘렸으며 실제 작업 소요 시간에 맞춰 조정하면 됩니다.

안전 규칙을 판정보다 확실하게 만들기

자동 모드의 판단은 모델이 수행하므로 확률적인 결론입니다. 반면 훅(hook)은 결정론적인 규칙입니다. 이미 겪은 문제를 훅으로 적어 두면 모델이 매번 기억해 주기를 기대하지 않아도 됩니다.

훅 스크립트는 단순한 규약을 따릅니다. 종료 코드 0은 허용, 종료 코드 2는 차단과 함께 표준 오류 내용을 모델에 전달한다는 뜻입니다. 스크립트는 절대 중단되지 않아야 합니다. 한 번 예외가 발생하면 모든 명령이 막히므로 전체를 예외 처리로 감싼 뒤 허용하도록 해야 합니다.

python
#!/usr/bin/env python3
"""명령 실행 전 검사: 0은 허용, 2는 차단하고 사유를 반환합니다."""
import json, re, sys


def main():
    try:
        payload = json.load(sys.stdin)
        if payload.get("tool_name") != "Bash":
            sys.exit(0)
        cmd = (payload.get("tool_input") or {}).get("command") or ""
        if re.search(r"\brm\s+-rf\s+/(\s|$)", cmd):
            sys.stderr.write("BLOCKED: 루트 디렉터리 삭제를 거부했습니다\n")
            sys.exit(2)
    except SystemExit:
        raise
    except Exception:
        pass
    sys.exit(0)


if __name__ == "__main__":
    main()

저장한 뒤 settings.json에 절대 경로를 등록하세요.

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "/绝对路径/guard-bash.py" }]
      }
    ]
  }
}

훅으로 작성하기에 적합한 대표적인 상황은 루트 디렉터리 삭제나 와일드카드 삭제, 프로덕션 데이터베이스에서 삭제 또는 비우기 구문 실행, 명령줄에 키를 그대로 적는 경우입니다.

변경 사항이 적용되었는지 확인

변경 후에는 작업 중인 세션을 건드리지 않고 임시 세션으로 확인하면 됩니다.

bash
claude --permission-mode auto --debug-file /tmp/cc.debug -p 'echo hi'
grep -E 'verifyAutoModeGateAccess|Skipping auto mode classifier|classifier_request_finished' /tmp/cc.debug

canEnterAuto=true는 자동 모드를 사용할 수 있음을 뜻합니다. Skipping auto mode classifier가 나타나면 해당 명령이 allow 규칙에 걸려 판정을 건너뛰었다는 의미이고, durationMs 값은 아직 규칙으로 처리되지 않은 명령이 만든 대기 비용입니다.

흔한 오해 두 가지

첫째, 자동 모드는 보안 경계가 아닙니다. 판단은 설정한 모델 위에서 실행되므로 편의 기능으로만 보고, 보안은 여전히 deny, ask 규칙과 훅에 의존해야 합니다.

둘째, 비표준 모델 이름은 컨텍스트 압축에 영향을 줍니다. 클라이언트가 모델 이름을 인식하지 못하면 안내를 표시하고 가정한 창 크기로 자동 압축을 수행합니다. 실제 창이 더 작으면 압축이 늦게 발동해 결국 요청이 실패할 수 있습니다. 해결 방법은 CLAUDE_CODE_MAX_CONTEXT_TOKENS를 설정하거나, modelPicker에서 해당 항목에 behavesAs를 추가해 실제 창 값을 넣는 것입니다. 잘못 채우는 것이 아예 채우지 않는 것보다 나쁩니다.

권장 조정 순서

먼저 defaultMode와 Bash 시간 초과만 추가해 일주일 정도 사용하세요. 그다음 /permissions에서 거부된 기록을 살펴보고 자주 쓰이면서 안전한 명령을 allow에 보강하세요. 이후 deny와 ask로 안전장치를 추가하고, 마지막에 훅과 넓은 규칙을 검토하세요. 한 번에 모두 바꾸면 문제의 출처가 가려지기 쉬우므로, 단계별로 조정하면 어떤 항목이 실제 대기를 해결했는지 분명히 알 수 있습니다.

설정 후에도 인증이나 연결 오류가 자주 나타난다면 연결 및 복구를 확인하세요. 계정, 잔액, 사용량 문제는 가격, 잔액, 사용량을 참고하세요.