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

루프 모드와 예약 작업

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

AX Code에는 서로 조합할 수 있는 자동화 기본 요소가 세 가지 있습니다.

/loop — 반복 프롬프트

/loop <interval> <prompt>   start (interval like 30s, 5m, 1h)
/loop status                show runs, busy-skips, and the prompt
/loop stop                  stop the loop

예:

/loop 5m check CI for new failures and fix any you find
/loop 30m drain the review queue

규칙:

• 간격의 범위는 30초에서 24시간입니다. 세션마다 루프는 하나입니다. 새로 시작하면 이전 루프가 바뀝니다.
• 세션이 바쁠 때 울린 틱은 건너뛰고 횟수에 넣습니다. 대기열에 넣지 않습니다. 루프가 턴을 쌓을 수는 없습니다.
• 모든 틱은 평범한 프롬프트 턴입니다. 권한, 질문, 자율 상한, 완료 게이트가 모두 적용됩니다. 자율이 꺼져 있으면 틱은 첫 권한 프롬프트에 그냥 멈춥니다.
• 루프당 500회라는 단단한 상한이 있습니다. 그 뒤 루프는 알림과 함께 스스로 멈춥니다.
• 루프는 백엔드 프로세스 안에만 있습니다. 다시 시작해도 남지 않습니다. 오래 가는 일정은 아래의 예약 작업을 사용합니다.

/goal과 /loop를 짝짓기

/goal가 목표를 소유합니다(“테스트가 모두 통과하고, 열린 검토 지적이 없습니다”). /loop가 계속 확인하는 심장 박동을 제공합니다. 목표를 먼저 만들면 전용 계획 작성기가 실행되어, 검토할 수 있는 계약을 .ax-code/goals/ 아래에 저장합니다. 프로젝트가 git 워크트리가 아니면 AX 데이터 디렉터리에 저장합니다. 계획이 실패하면 목표는 일시 중지된 채로 남고, /goal resume가 다시 시도합니다. 이 목표의 diff를 재는 Git 범위 검사는 계획 시점의 HEAD({BASELINE})를 쓰며, 목표가 그 원격을 지목하지 않는 한 origin/main는 쓰지 않습니다. 목표 완료는 계속 검증 게이트를 통과해야 합니다. 에이전트는 검증 실행이 통과하지 않은 채, 편집 뒤에 목표를 완료로 표시할 수 없습니다. 계획이 있으면 모든 인수 기준에 대한 증거도 제시해야 합니다.

/goal keep main green: fix any CI failure the loop finds
/loop 10m check CI status and act on failures

목표 보증은 선택입니다

/goal <objective>는 즉시 시작합니다. 얼어 있는 인수 계약을 붙이지 않으므로, 완료는 에이전트가 유지하는 작업 계획(남은 할 일)과 마지막 변경 뒤의 통과한 검증으로 판단됩니다. /goal view와 목표 대화 상자의 “목표 세부 보기”가 이를 명시합니다. “보증 계약 없음”이므로, 상태를 추측할 필요가 없습니다.

/goal --assure <objective>는 계획 작성기를 먼저 실행합니다. 인수 기준, 소스 참조, 실행할 수 있는 검사를 얼립니다. 그러면 완료에는 필수 검사마다 현재의 성공 영수증도 필요합니다. verify_project와 그 goalCheck id입니다. 목표가 말하는 “완료”가 설명에 그치지 않고 증명 가능해야 할 때 사용합니다.

--assure는 어느 순서든 예산 플래그와 결합합니다(/goal --assure --budget 500000 <objective>). /goal replace <objective>는 교체되는 목표에 유효한 계약이 있으면 보증을 유지하므로, 교체가 이미 보증된 목표를 조용히 약하게 만들 수 없습니다.

목표 예산과 상한

활성 목표는 실행마다의 자동 연속 상한(session.max_continuations)을 올립니다. 실행은 목표가 완료되거나, 막히거나, 일시 중지되거나, 예산에 걸릴 때까지 계속됩니다. 대신 그것을 묶는 것은 다음과 같습니다.

• 토큰 예산(/goal --budget N …). 소진되면 에이전트는 마무리 턴을 한 번 받고, 그 뒤 목표는 budget_limited가 됩니다.
• 시간 예산(/goal --time-budget 30m …). 초, 분(m), 또는 시간(h) 단위의 벽시계 한도입니다. 토큰 예산과 어느 순서로든 결합할 수 있습니다. 토큰 예산이 보지 못하는 경과한 작업을 묶습니다. 원격 학습 작업, 긴 도구 호출, 공급자가 멈추는 경우입니다. 한도에 걸리면 같은 마무리 턴과 budget_limited 전이가 적용됩니다.
• 누적 단계 상한. 활성 목표 실행은 max_steps × 40 총 단계(기본 20,000)라는 Super-Long 안전망을 공유합니다. 보통의 자율 상한인 max_steps × (max_continuations + 1)를 쓰지 않습니다. session.max_total_steps로 덮어씁니다.
• 파멸 루프 감지, 영향 범위 상한, 도구만 있는 턴의 차단기는 내내 계속 적용됩니다.

목표 CLI(헤드리스)

같은 목표 제어를 TUI 밖, ax-code goal 아래에서 쓸 수 있습니다.

• ax-code goal status [--json] — 현재 목표를 보여 줍니다. -s/--session로 세션을 고릅니다. 기본값은 프로젝트에서 재개할 수 있는 하나의 목표이며, 선택이 모호하면 오류가 납니다.
• ax-code goal pause / ax-code goal clear — 일시 중지하거나 지웁니다.
• ax-code goal resume — 목표를 재개하고, 자리가 잡힐 때까지 헤드리스로 진행합니다. --attach가 없으면 프로세스 안에서 프로젝트를 띄웁니다. --attach http://localhost:4111가 있으면 실행 중인 서버를 진행합니다. 종료 코드는 헤드리스 목표 계약을 따릅니다. 0는 완료, 3는 막힘, 4는 예산 제한, 6는 일시 중지 또는 끝나지 않음, 1는 세션 오류, 124는 유휴 시간 초과입니다(--idle-timeout-ms, 기본 10분). 이벤트는 JSONL로 stdout에 흐릅니다. --event-log PATH도 이를 기록합니다. 마지막 Goal <status>: <objective> 줄은 stderr로 갑니다.

목표 실행이 단계 상한에 가까워지면 에이전트는 한 번의 수렴 경고를 받습니다. 목표를 검증하고 완료하거나, 깨끗한 인계를 남기라는 내용입니다. 그래도 상한에 도달하면 목표는 실패한 것이 아니라 일시 중지되며, /goal resume로 다시 이어서 할 수 있습니다. 여유가 더 필요하면 먼저 session.max_total_steps를 올립니다.

예약 작업 — 오래 남고, 대화로 설정합니다

에이전트에게 직접 요청합니다. schedule_task, list_scheduled_tasks, manage_scheduled_task 도구를 사용합니다.

• “14:30에 배포를 확인하라고 알려 줍니다.”
• “평일 오전 9시마다 새로운 CI 실패를 요약합니다.”
• “예약 작업을 나열합니다.” / “CI 요약 작업을 일시 중지합니다.”

에이전트가 만들고 관리하는 일정 변경은 schedule 권한을 요청합니다. 읽기 전용 실행은 일정을 바꾸거나 발화시킬 수 없습니다. 사람이 없는 헤드리스 생성에는 명시적인 ax-code schedule 명령을 쓰거나, 에이전트에 명시적인 schedule 권한 허가를 구성합니다. 넓은 와일드카드 허가는 일정 변경을 인가하지 않습니다.

같은 작업은 TUI를 열지 않고 셸에서 관리할 수 있습니다.

ax-code schedule list                 # status, next run, schedule, id, title
ax-code schedule show <id>            # details plus the five most recent runs
ax-code schedule runs <id>            # run history: fired, failed, skipped and why
ax-code schedule pause|resume <id>
ax-code schedule delete <id>
ax-code schedule run <id>             # trigger now; requires a live runtime

pause/resume/delete는 프로젝트의 관리형 런타임이 돌고 있으면 그 런타임을 거칩니다. 효과는 즉시이고, TUI도 실시간으로 갱신됩니다. 그렇지 않으면 프로젝트 데이터베이스에 직접 씁니다. run에는 살아있는 백엔드가 필요합니다. ax-code runtime start로 하나를 시작합니다. 한 번 돌고 끝나는 CLI 프로세스가, 끝낼 수 없는 작업을 맡으면 안 되기 때문입니다. 모든 읽기 하위 명령은 --json를 받습니다.

일정은 한 번의 실행, 매일 또는 매주 시각, 필드가 다섯 개인 cron 식을 지원하며, 각각 선택적인 IANA 시간대를 가질 수 있습니다. 작업은 프로젝트 데이터베이스에 남고, 그 프로젝트의 AX Code 백엔드가 실행 중일 때 발화합니다. 스케줄러는 60초마다 훑고, 선점은 원자적입니다. 백엔드가 여러 개 열려 있어도 작업은 한 번만 발화합니다. 일정 진행과 오래 남는 큐 삽입은 하나의 데이터베이스 트랜잭션을 공유하므로, 크래시가 복구할 작업을 남기지 않은 채 한 회차를 진행시킬 수 없습니다. ax-code run와 ax-code stats 같은 일회성 명령은 기한이 된 작업을 맡지 않습니다. 그 작업을 보내려면 ax-code runtime start로 지속되는 백엔드를 시작합니다.

놓친 회차의 기본값은 catchUpPolicy: "run_once"입니다. 멈춘 뒤에 AX Code는 밀린 일을 한 번의 실행으로 합칩니다. 오래된 작업을 실행하지 않고 일정만 진행해야 하면 "skip"를 사용합니다. 작업은 1초에서 72시간까지 maxRunDurationMs를 둘 수도 있습니다. 시간이 초과된 실행은 취소되고 실패로 기록됩니다.

프로세스와 호스트가 다시 시작되어도 동작하게 하려면 감독자 아래에서 백엔드를 실행합니다. systemd, launchd, PM2 예시와 정확한 복구의 의미는 장기 실행 작업을 보십시오.

오래 두는 무인 실행

여러 시간에 걸친 자율 세션을 위해 Super-Long 모드는 실행 기한(최대 72시간), 요청 속도 조절, 컴팩션 조정을 더합니다. 선언된 능력이 장기 에이전트 작업을 지원하는 모델에서는 자동으로 켜집니다. Alibaba 경로의 Qwen 3.7 이상 Max와 Plus, z.ai 경로의 GLM 5.x처럼 맥락이 100만인 추론 모델이 해당합니다. 세션마다, 프로젝트마다, 또는 AX_CODE_SUPER_LONG로 강제할 수 있습니다. 실행 참여는 기록됩니다(super-long run engaged). 공급자 속도 조절은 실행이 시작된 뒤의 유예 창이 지나야 시작합니다. 기본은 2시간이며 super_long.pacing_grace_minutes입니다. 그래서 에이전트 실행의 생산적인 초반은 도구 호출 처리량을 온전히 유지하고, 긴 꼬리는 모델이 선언한 속도 제한 등급에 맞춰 조절됩니다.