이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

자율 모드

상태: 활성 범위: 현재 상태 최종 검토: 2026-08-25 담당: ax-code 런타임

자율 모드는 ax-code가 위험이 낮은 단계마다 사람의 확인을 기다리지 않고 작업을 끝내게 합니다. 켜면, 명시적으로 막히지 않은 권한 프롬프트는 자동 승인되고, 질문 대화 상자는 모범 사례 휴리스틱으로 자동 응답합니다. 권장, 기본, 흔함, 단순, 최소를 선호하고 위험하거나 과도하게 설계된 선택은 피합니다.

기본적으로 자율 모드는 켜져 있습니다. 이전에 꺼 두었다면 그 설정이 저장되고 다음 실행에서 복원됩니다.

빠른 시작

TUI에서 전환합니다.

• 프롬프트에 /autonomous을 입력하거나
• Ctrl+P을 누르고 “autonomous”를 검색하거나
• 상태 표시줄의 자율 켜짐/꺼짐 표시를 누릅니다

상태 표시줄은 현재 상태를 보여 줍니다.

• 자율 켜짐(노란 배경, 굵은 빨간 글씨) — 에이전트가 멈추지 않고 실행됩니다
• 자율 꺼짐(초록 글씨) — 에이전트가 권한/질문 프롬프트에서 멈춥니다

설정은 ax-code.json에서 세션을 가로질러 유지됩니다.

무엇이 바뀌는가

동작 방식

자율 모드는 세 계층에서 동작합니다.

진실의 원천

이 페이지는 사용자에게 보이는 동작을 요약합니다. 동작이 바뀌면 문서를 다음과 대조해 검증합니다.

• 권한 자동 승인, 루프 동작, 거부 처리, 자율 상한은 packages/ax-code/src/session/processor.ts.
• 자율 워크플로 지시는 packages/ax-code/src/session/system.ts와 packages/ax-code/src/session/prompt/ 아래의 공급자 프롬프트 파일.
• 질문 자동 응답 휴리스틱과 상향 동작은 packages/ax-code/src/question/과 packages/ax-code/test/question/question.test.ts.
• 자율 단계/파일 변경 상한은 packages/ax-code/src/session/blast-radius.ts.
• 프롬프트와 결정 원장 동작은 packages/ax-code/test/session/system.test.ts, packages/ax-code/test/session/prompt.test.ts, 관련 세션 시험.

여기의 안전 보장을 샌드박스 문서와 맞춥니다. 자율 모드는 승인 동작을 바꾸지, 격리 강제를 바꾸지 않습니다.

1. 권한 자동 승인(서버 쪽)

자율 모드는 거부를 우선하는 혼합 정책(ADR-004 / PRD v4.2.0)을 사용합니다. 도구가 권한을 위해 ctx.ask()를 호출하면 권한 모듈이 권한을 분류합니다.

• 안전 권한(read, glob, grep, list, lsp, code_intelligence, skill, todoread)은 막는 프롬프트를 만들지 않고 자동 승인합니다.
• 위험 권한(edit, bash, external_directory, task, webfetch, websearch, codesearch, …)은 규칙 집합으로 내려갑니다. 에이전트에 구성된 허용/거부 규칙이 계속 적용되고, 사용자가 정의한 거부 규칙은 항상 강제됩니다. full-access 샌드박스 모드에서는 거부 규칙을 평가한 뒤 위험 권한이 자동 승인됩니다.
• 알 수 없는 권한은 기본적으로 묻습니다(experimental.autonomous_strict_permission: false는 이전의 허용 동작을 유지합니다).

즉시 규칙 기반 승인 대신 항상 호출별 결정에 도달하는 권한: isolation_escalation(샌드박스 재정의 요청), INTERACTIVE_ONLY 권한, NEVER_AUTONOMOUS_AUTOAPPROVE 집합입니다. 한 가지 좁힘(ADR-098): full-access 샌드박스 모드에서, 대화형 전용으로 표시된 external_directory 요청 — glob, 변수, 중괄호 확장을 써서 경로를 정적으로 검증할 수 없는 bash 명령 — 도 자동 승인됩니다. 전체 접근 샌드박스에는 지킬 파일 시스템 경계가 남아 있지 않기 때문입니다. 명시적 거부 규칙은 계속 적용되고, 샌드박스가 켜진 모드(workspace-write, read-only)는 호출별 프롬프트를 유지합니다.

유휴 “한 번 허용”(기본으로 켜짐): 자동 켜짐과 샌드박스 꺼짐(full-access)은 최소 상호작용을 뜻합니다. 대기 중인 모든 권한은 15초 뒤에 한 번 자동 응답할 수 있으며, requireInteractive, 훅, 샌드박스 상향 프롬프트도 포함됩니다. 자동이 꺼져 있거나 샌드박스가 켜져 있으면 대기 프롬프트에 사람의 답이 필요합니다. WebMCP는 추가로 해당하는 브리지가 연결되어 있어야 합니다. 다른 연결된 브리지는 자격이 되지 않습니다. 명시적 거부 규칙은 계속 적용됩니다. experimental.permission_idle_once.enabled: false는 카운트다운을 끄고, permissions는 그 범위를 제한할 수 있습니다. 이전 timeout_ms 설정은 호환을 위해 받아들여지지만 고정된 15초를 더 이상 바꾸지 않습니다.

카운트다운은 서버가 소유합니다. 각 세션의 가장 오래된 요청이 기한을 받습니다. 대기 중인 요청은 맨 앞에 도달하면 새로운 15초를 받습니다. 사람의 응답은 타이머를 취소합니다. 자동을 끄거나, 샌드박스를 켜거나, 관련 WebMCP 브리지 연결을 끊으면 대기 중인 카운트다운이 취소됩니다. 자격을 복원하면 새 카운트다운이 시작됩니다. 일시적인 구성 다시 불러오기 공백은 카운트다운을 멈춥니다. 자동 응답은 현재 모드, 브리지, 거부 규칙을 다시 확인하고 지속 승인을 저장하지 않습니다. AX_CODE_PERMISSION_IDLE_ONCE_MS 내부 디버그/시험 재정의는 계속 사용할 수 있으며 Node 타이머 최대로 제한됩니다.

모드는 활성 디렉터리로 범위가 정해집니다. 중첩된 ax-code.json은 저장소 루트 설정을 재정의할 수 있습니다. 유효 모드를 바꾸려면 활성 세션의 샌드박스 전환을 사용합니다.

재정의할 수 없는 보호 경로: 자율 모드는 고정된 정책/제어 평면 경로 집합 — ax-code.json/ax-code.jsonc, .ax-code/**, .git/config, .git/refs/** — 에 쓰기도 거부합니다. 에이전트가 자신의 구성을 편집하거나, 자신의 자율 상한을 올리거나, git 훅을 심지 못하게 하기 위해서입니다. 구성 가능한 차단 경로 목록과 달리, 이것은 프로젝트나 사용자 구성으로 제거할 수 없습니다.

2. 질문 자동 응답(서버 쪽)

도구가 사용자에게 질문하면 질문 모듈이 즉시 답을 고릅니다. 권장, 기본, 안전, 표준, 흔함, 관례, 모범 사례, 단순, 최소로 표시된 옵션을 선호합니다. 실험적, 위험, 위험함, 파괴적, 고급, 복잡, 다시 쓰기, 과도한 설계로 표시된 옵션은 피합니다. 어떤 옵션에도 신호가 없으면 첫 옵션을 고릅니다. 질문 도구가 에이전트에게 권장 옵션을 먼저 두라고 지시하기 때문입니다.

3. 처리기 루프(세션 수준)

권한이 어떤 이유로 거부되면(예를 들어 명시적 거부 규칙), 처리기 루프는 멈추지 않습니다. 세션을 중단하는 대신 다음 단계로 계속합니다.

4. PRD/ADR 스타일 결정 틀

자율 모드는 시스템 프롬프트에 가벼운 워크플로 알림을 더합니다. 구현 전에 에이전트는 문제, 제약, 결정, 트레이드오프, 계획, 검증으로 작업을 틀 지어야 합니다. 여러 파일, 아키텍처, 제품에 보이는 상당한 변경에는, 저장소의 문서 패턴과 맞으면 저장소 문서를 만들거나 갱신할 수 있습니다. 사소한 변경에는 과도한 설계를 피하려고 계획 안에서 이 틀을 가볍게 유지해야 합니다.

자율과 샌드박스

자율 모드와 샌드박스 모드는 독립입니다. 둘을 동시에 쓸 수 있습니다.

기본 런타임 자세는 자율 켜짐과 샌드박스 꺼짐입니다. 네트워크가 켜진 full-access입니다. 마찰이 가장 적은 CLI 동작을 제공하지만 격리 경계는 없습니다. 신뢰하지 않거나 자리를 비운 작업에는 /sandbox, --sandbox workspace-write, AX_CODE_ISOLATION_MODE 또는 프로젝트 구성으로 제한을 켭니다.

구성

구성 파일

ax-code.json에서:

{
  "autonomous": true
}

끄려면 false로 설정합니다.

{
  "autonomous": false
}

환경 변수

AX_CODE_AUTONOMOUS=true ax-code    # force autonomous on
AX_CODE_AUTONOMOUS=false ax-code   # force autonomous off

우선순위

환경 변수 > 구성 파일 > 기본값(켜짐)

작업량 예산(모델 턴과 도구 호출)

자율 모드가 무제한 실행을 뜻하지는 않습니다. 서로 독립된 여러 상한이 적용됩니다. 아래 기본값은 제공된 상수입니다. 작업량에 더 많은 여유가 필요하면 ax-code.json에서 올리거나 내립니다.

모델 턴은 바깥 루프의 모델 요청 하나입니다. 도구 호출은 모델 턴 안의 도구 실행 하나입니다. 예산은 별개입니다. 모델 턴 하나가 여러 도구 호출을 낼 수 있습니다. steps이 들어 있는 이전 구성 이름은 계속 지원되지만, 두 단위를 서로 바꾸어 쓰게 하지는 않습니다.

일급 autonomy 객체를 선호합니다. 이전 session.*과 experimental.autonomous_caps.* 키는 별칭으로 계속 동작합니다(우선순위가 더 낮음).

바이너리 파일(실행 파일의 cp, zip의 curl -o, 그 밖의 텍스트가 아닌 쓰기)은 여전히 파일 상한에 세지만 줄은 0으로 청구합니다. 줄 상한은 텍스트 변경을 측정합니다. 셸 텍스트 쓰기는 ceil(size / 80) 추정을 유지하므로, 줄바꿈이 적다고 빽빽한 페이로드가 예산을 피하지 못합니다.

git check-ignore가 무시됨으로 보고하는 추적되지 않은 경로도 줄을 0으로 청구하고 파일은 하나로 셉니다. 검증기가 출력을 그곳으로 보낼 때의 target/ 같은 생성된 트리를 다룹니다(cargo clippy > target/review/clippy.log). 면제는 git이 0으로 끝날 때만 적용됩니다. 저장소가 없거나, git이 실패하거나, 추적된 파일은 일반적인 줄 청구를 유지하며, 무시 패턴과 이름이 맞는 추적된 파일도 포함됩니다.

프로파일

여러 필드를 한 번에 심으려면 autonomy.profile을 설정합니다(명시적 필드가 여전히 이깁니다).

/limits로 살펴보기

세션에서 **/limits**를 실행하면 해석된 예산 스택, 활성 에이전트의 유효 TUI 분모, 구성 출처, doctor 경고(예를 들어 agent.steps이 세션 구간보다 더 조일 때)를 출력합니다. 키 이름은 /limits help을 사용합니다.

TUI가 보여 주는 것: 자율 실행 중 머리글은 turn current/max · total current/max · cont current/max을 보고합니다. turn는 현재 이어가기 구간이며 활성 에이전트의 유효 속도 상한을 사용합니다. 에이전트에 상한이 있으면 min(agent.steps, session.max_steps), 아니면 구간별 한도입니다. total은 자동 이어가기 이후에도 남습니다. 활성 목표나 Super-Long 모드가 일반 이어가기 상한을 올리면 cont가 ∞을 보여 줍니다.

자동 라우팅: 키워드 라우팅이 세션을 전문 에이전트(Debug, Security, DevOps, …)로 바꿀 수 있습니다. 전문가는 agent.<name>.steps를 설정하지 않으면 Dev와 같은, 기본적으로 제한 없는 에이전트 모델 턴 정책을 공유합니다. Dev 에이전트만 원하면 "routing": { "disable": true }로 라우팅을 끕니다.

긴 실행: 여러 시간에 걸친 작업에는 /goal이나 Super-Long을 사용합니다. 일반 이어가기 상한을 올리고 더 큰 누적 천장(기본 20,000)을 사용합니다. 검증 / 일시 중지 의미는 루프 모드에 있습니다. /goal은 먼저 검토할 수 있는 계약(수용 기준 + 검증 계획)을 쓰고, 그 계획을 만들 수 없으면 실패 시 일시 중지로 닫힙니다.

한도가 실행을 멈출 때

일반 실행이 누적 모델 턴 천장에 닿기 전에, AX Code는 제한된 수렴 지시를 하나 주입합니다(최대 마지막 50턴, 작은 사용자 예산에는 줄임). 모델에게 넓은 탐색을 멈추고, 진행 중인 작업을 끝내거나 안전하게 주차하고, 겨냥한 검증을 실행하고, 끝나지 않은 작업을 정직하게 보고하라고 말합니다. 예산을 더하거나 어떤 상한도 우회하지 않습니다.

종료 예산에 도달하면 session.error에 선택적인 기계가 읽을 수 있는 code가 포함되고, 재생 session.end 이벤트는 같은 값을 stopCode로 기록합니다. 기존의 거친 종료 이유는 호환을 위해 바뀌지 않습니다. 현재 한도 코드는 다음과 같습니다.

• MODEL_TURN_SEGMENT_LIMIT
• MODEL_TURN_TOTAL_LIMIT
• AGENT_MODEL_TURN_LIMIT
• AGGREGATE_TOOL_CALL_LIMIT
• FILE_CHANGE_LIMIT
• LINE_CHANGE_LIMIT

구간 천장에서는 구성된 이어가기 예산이 남아 있는 동안 AX Code가 자동으로 이어갑니다. 그 예산이 소진되면 실행이 멈추고 메시지가 무슨 일이 있었는지 말합니다. continue 같은 새 프롬프트를 보내면 새 실행 회계가 있는 새로운 사용자 지시 실행이 시작됩니다. 멈춘 실행을 소급해서 늘리지는 않습니다. 목표가 완료, 차단, 목표/런타임 예산 경계까지 명시적이고 재개 가능해야 하면 /goal를 사용합니다. /goal은 권한, 격리, 폭발 반경, 정체, 토큰, 시간, 누적 모델 턴 안전장치를 끄지 않습니다.

예: 큰 자율 배치를 위해 예산을 올립니다

{
  "autonomous": true,
  "autonomy": {
    "profile": "long",
    "budget": {
      "model_turns": { "per_segment": 500, "total": 20000 },
      "tool_calls": {
        "per_segment": 1000,
        "rate": { "count": 40, "window_seconds": 10 },
        "per_tool": { "bash": 80, "edit": 150 }
      },
      "changes": { "files_total": 100, "lines_total": 10000 }
    },
    "stall": {
      "tool_only_turns": 50,
      "tool_only_nudge": 20,
      "failed_mutation_attempts": 30,
      "max_consecutive_errors": 3
    }
  },
  "agent": {
    "debug": { "steps": 200 }
  }
}

자율을 끌 때

• ax-code를 배울 때 — 각 단계에서 에이전트가 하는 일을 봅니다
• 민감한 작업 — 적용되기 전에 각 파일 변경을 검토합니다
• 에이전트 동작을 디버그할 때 — 에이전트가 어떤 결정을 하는 이유를 이해합니다
• 신뢰하지 않는 코드 — 익숙하지 않은 저장소에서 작업할 때 도구 호출을 검토합니다

자율을 켜 둘 때

• 일상 작업 — 에이전트를 신뢰하는 리팩터, 버그 수정, 마이그레이션
• CI/CD 파이프라인 — 작업이 이미 정책으로 제한된 헤드리스 실행
• SDK 사용 — createAgent()을 통한 프로그램적 에이전트 실행
• 큰 작업 — 권한마다 멈추면 몇 시간이 걸릴 여러 파일 변경

헤드리스 / CI 사용

헤드리스 모드(ax-code run, ax-code serve, SDK)에서는 자율 모드가 필수입니다. 프롬프트를 보여 줄 TUI가 없습니다. 서버 쪽 자동 승인이 답하지 않은 프롬프트에 걸리지 않고 에이전트가 끝까지 실행되게 합니다.

# Headless one-shot with autonomous on (default)
ax-code run "Fix all TypeScript errors in src/"

# Explicit override
AX_CODE_AUTONOMOUS=true ax-code run "Migrate API routes"

ax-code run는 기본적으로 간결한 도구 출력을 인쇄합니다. 명령 출력은 꼬리로 줄고, 편집은 diff 요약을 보여 주며, 할 일 쓰기는 한 줄 진행 횟수를 보여 줍니다. 오류는 숨기지 않습니다. 다른 출력과 같은 꼬리 상한으로 렌더링됩니다. 감사를 위해 완전한 도구 출력(전체 diff, 자르지 않은 명령 출력, 전체 할 일 목록)을 복원하려면 --full를 전달합니다.

안전 보장

자율 모드가 켜져 있어도:

1. 샌드박스는 여전히 경계를 강제합니다 — 작업 공간 밖의 쓰기는 자율 모드와 관계없이 차단됩니다
2. 격리 상향은 항상 묻습니다 — 에이전트가 샌드박스 제한을 조용히 재정의할 수 없습니다
3. 거부 규칙이 강제됩니다 — 명시적인 "deny" 권한 규칙이 여전히 도구 호출을 막습니다
4. 자율 선택이 기록됩니다 — 질문 도구 메타데이터에는 구조화된 autonomousDecisions 원장이 있고, 도구 출력에는 고른 답이 포함되어 에이전트가 나중에 보고할 수 있습니다
5. 과도한 설계를 피합니다 — 자율 이어가기는 에이전트에게 가장 단순한 일반 관행 변경을 선호하고, 구체적인 사용처가 3개 이상 없는 추상화를 피하라고 알립니다
6. 세션 스냅샷이 기록됩니다 — 모든 도구 호출이 감사/재생을 위해 기록됩니다
7. 중단은 항상 동작합니다 — Esc(인터럽트)를 누르면 에이전트가 즉시 멈춥니다