승인 모드

승인 모드 (Approval Modes)

에이전트가 파일을 고치거나 셸 명령을 실행할 때마다 일일이 확인받는 건 안전하지만 답답할 수 있어요. 반대로 아무 확인 없이 막 실행하게 두는 건 위험하고요. Deep Agents Code는 이 감독 수준을 **승인 모드(approval mode)**로 조절할 수 있게 해줘요. 기본값인 Manual부터, 알아서 판단하는 Auto, 아무 검토 없이 실행하는 YOLO까지 세 가지가 있어요. 여기서 각 모드가 무엇을 하고 어떻게 켜는지 살펴볼게요.

출처: 공식문서

무엇이 승인 대상인가

기본적으로 Deep Agents Code는 잠재적으로 결과가 큰 작업을 실행하기 전에 승인을 요청해요. 이걸 gated action(게이트된 작업)이라고 부르며, 다음을 포함해요.

  • 파일 편집·삭제 (write_file, edit_file, delete)
  • 셸 명령 실행 (execute)
  • 웹 요청 (web_search, fetch_url)
  • 서브에이전트에게 작업 위임 (task)

ls, read_file, glob, grep 같은 읽기 전용 도구는 항상 프롬프트 없이 실행돼요. 승인 모드는 이러한 게이트된 작업에 대해 세션마다 감독 수준을 정해요.

모드 고르기

모드 하는 일
Manual (기본값) 모든 게이트된 작업 전에 승인 요청
Auto 일상적인 작업은 자동 승인; 불확실한 것은 모델이 검토; 반복 거부·실패 후엔 다시 사람에게
YOLO 게이트된 작업을 검토 없이 실행

Auto는 로컬 코딩 에이전트를 위한 권한 부여 휴리스틱입니다. 샌드박스 격리, 운영체제 경계, 또는 모델 생성 작업이 안전하다는 보장이 아닙니다.

Auto 켜기

Auto는 대화형(interactive)·비샌드박스 세션에서만 사용할 수 있어요.

Auto로 시작하기

dcode -y

또는 ~/.deepagents/config.toml에서 기본값으로 설정해요:

[startup]
mode = "auto"

세션 중에는 Shift+Tab으로 Auto로 순환할 수도 있어요.

YOLO 켜기

YOLO는 게이트된 작업을 검토 없이 실행해요. 에이전트가 물어보지 않고 어떤 작업이든 할 수 있다는 점을 수용할 때만 쓰세요.

YOLO로 시작하기

dcode --yolo

프롬프트가 나오면 일회성 위험 인지를 수락해요. 이 인지는 로컬에 저장되므로 이후 실행에서는 다시 보이지 않아요.

또는 ~/.deepagents/config.toml에서 기본값으로 설정해요:

[startup]
mode = "yolo"

Shift+Tab으로 YOLO → Manual → Auto → YOLO 순으로 순환할 수 있어요. 순환에서 YOLO를 제외하려면 startup.yolo_switcher = false로 설정하세요.

Auto가 동작하는 방식

Auto는 Manual과 같은 게이트된 작업 규칙을 유지하지만, 검토 방식을 바꿔요. 두 단계로 이뤄져요:

  1. 일상 작업은 자동 실행됩니다. src/parser.py 같은 소스 파일 쓰기나 git status 같은 읽기 전용 Git 명령은 프롬프트 없이 진행돼요. .github/workflows/ci.yml 같은 민감 대상이나 git commit 같은 변경 명령은 다음 단계로 넘어가요.
  2. 나머지는 모델이 검토합니다. 명확히 일상적이지 않은 것은 활성 모델이 그 작업이 요청한 결과와 일치하는지 확인해요. 그 결과에 합리적으로 필요한 일반적인 단계는 각 구현 세부를 언급하지 않았어도 진행될 수 있어요. 미구성 대상에 로컬 콘텐츠를 보내는 것 같은 고위험 효과는 여전히 명시적 승인을 필요로 해요. 모델이 호출을 거부하면 에이전트는 오류 결과를 받고 계획을 수정할 수 있어요.

반복된 거부나 분류기 실패 후에는 Auto가 멈추고, 다음 배치에 대해 일반 승인 프롬프트를 보여준 다음 Auto 모드로 계속돼요.

Auto 결정 흐름

flowchart TD
    A[Model proposes tool calls] --> B{Covered by the approval policy?}
    B -->|No| X[Existing tool behavior is unchanged]
    B -->|Yes| S{Still in Auto, with readable history?}
    S -->|No| J[Open the approval UI]
    S -->|Yes| C{Narrow deterministic allow?}
    C -->|Yes| R[Execute without a classifier call]
    C -->|No| D[Build one structured decision batch]
    D --> H{Already reviewed, or earlier denials or failures require human review?}
    H -->|Yes| J
    H -->|No| E[Active model reviews effects against the user request]
    E -->|Allow| R
    E -->|Deny| Q{Total-denial threshold reached?}
    Q -->|No| F[Return a sanitized error result]
    Q -->|Yes| J
    E -->|Unavailable or invalid| G[Return a compact unavailable result]
    F --> I[Agent can revise its plan]
    G --> I
    J -->|Approve| R
    J -->|Reject| K[Return a rejection result]
    J -->|Switch to Manual| L[Persist Manual, then review the full gated batch]
    R --> M[Reconcile the result and continue]
    K --> M
    I --> M
    L --> M

분류기 모델 선택하기

Auto 분류기를 설정하지 않으면 Deep Agents Code는 메인 모델의 제공자에 따라 더 낮은 지연시간의 기본값을 선택해요.

메인 모델 제공자 기본 분류기
Anthropic anthropic:claude-sonnet-5
Google AI google_genai:gemini-3.8-flash
Google Vertex AI google_vertexai:gemini-3.8-flash
OpenAI openai:gpt-5.6-luna
OpenAI Codex openai_codex:gpt-5.6-luna

다른 제공자의 경우 분류기에 메인 에이전트 모델을 사용해요. Auto 검토 중 비용과 지연을 조절하려면 다른 모델을 선택할 수 있어요.

분류기 모델은 다음 어느 곳에서든 설정할 수 있어요:

TUI 명령: /auto model으로 대화형 모델 피커를 열어 현재 세션의 분류기 모델을 선택해요. 직접 지정하려면 인자로 전달하세요:

/auto model openai:gpt-5.6-luna
/auto model clear

/auto model clear로 메인 모델 상속으로 돌아가요.

CLI 플래그

dcode -y --auto-classifier-model openai:gpt-5.6-luna

--auto-classifier-model은 대화형 TUI 세션에서만 받아들여져요.

환경 변수

export DEEPAGENTS_CODE_AUTO_CLASSIFIER_MODEL="openai:gpt-5.6-luna"

프로젝트 .env 는 DEEPAGENTS_CODE_AUTO_CLASSIFIER_MODEL을 설정할 수 없습니다. 셸 export, ~/.deepagents/.env, CLI 플래그, /auto model만 동작합니다.

config.toml

[models]
auto_classifier = "openai:gpt-5.6-luna"

우선순위 순서

  1. /auto model TUI 명령: 현재 세션에 즉시 적용됩니다.
  2. --auto-classifier-model 플래그: 시작 시 분류기를 설정합니다 (대화형 TUI 세션만).
  3. DEEPAGENTS_CODE_AUTO_CLASSIFIER_MODEL 환경 변수: 시작 시 적용됩니다.
  4. config.toml의 [models].auto_classifier: 영구 기본값입니다.
  5. 제공자 기본값: 메인 모델이 지원 제공자를 쓸 때 위 목록의 낮은 지연 모델을 사용합니다.
  6. 상속(Inherit): 내장 기본값이 없는 제공자는 메인 에이전트 모델을 사용합니다.

설정하지 않은 값은 다음 소스로 넘어가요. /auto model clear이나 빈 CLI 플래그로 분류기를 명시적으로 지우면 제공자 기본값 대신 메인 에이전트 모델을 선택해요.

TUI는 Auto가 켜질 때와 /auto model 출력 안에서 어떤 모델이 검토 중인지 표시해요.

부작용 전 재검증 (Revalidate before side effects)

결정 계획은 스레드, 모드, 배치, 정확한 게이트된 호출에 묶여 있어요. 상태가 없거나 유효하지 않거나, 모드 레이스가 있거나, 재생(replay)이면 사람 검토로 돌아가요. 예를 들어 분류기 검토 중에 Manual로 전환하면, 이전 Auto 결정이 조용히 실행될 수 없어요. 대신 일반 승인 UI가 열려요.

범위와 한계 이해하기

  • Manual 승인 메뉴는 현재 스레드에 Auto를 활성화할 수 있어요. 임계값 폴백은 Auto를 켠 채 영구히 Manual로 전환하거나 일회성 검토를 수행할 수 있어요.
  • 활성 모델은 독립적인 보안 권위자가 아니에요. MCP 읽기 전용 어노테이션은 의도적인 베타 트레이드오프로 신뢰됩니다.
  • 부모 수준의 Auto 검토는 위임된 서브에이전트 내부에서 수행되는 작업이나, 더 넓게 명시적으로 설정된 js_eval 팬아웃을 다루지 않아요. 모델 제공자와 트레이싱 백엔드는 TUI가 숨기더라도 분류기 입력·출력을 여전히 관찰할 수 있어요.

Auto와 YOLO가 어디서 쓰이는가

Auto와 YOLO는 대화형 모드 기능이에요. Auto는 대화형·비샌드박스 세션에서만 가능하고, 원격 --sandbox는 Manual로 강제해요. YOLO도 대화형 전용이며 샌드박스와 무관하게 위험 인지가 필요해요. 헤드리스 실행은 fail-closed MCP 라우팅과 셸 접근용 --shell-allow-list를 사용해요.

비대화형 모드(-n 또는 파이프된 stdin)에서는 -y/--auto-approve와 --yolo가 무시돼요.

세션 간 마지막 모드 기억하기

플래그나 설정된 모드가 없으면 Deep Agents Code는 마지막에 선택한 Manual 또는 Auto 모드를 복원해요. YOLO는 명시적으로 선택해야 해요. Startup approval mode를 참고하세요.

더 알아보기 (Learn more)

  • CLI reference — 승인 모드 관련 명령과 플래그.
  • Configuration — 모드와 분류기 설정을 더 자세히 다루는 문서.
  • Remote sandboxes — 원격 실행 환경에서 승인 동작의 차이점.