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

장기 작업을 위한 AX Code 운영

상태: 활성

범위: 현재 상태

최종 검토: 2026-09-13

담당: AX Code 유지관리자

AX Code는 대화형 Super-Long 실행 하나를 72시간으로 제한합니다. 며칠 또는 몇 주에 걸친 운영에는 감독되는 ax-code serve 프로세스를 실행하고 작업을 지속되는 예약 발생으로 나눕니다. 감독자는 서버를 다시 시작하고, 프로젝트 데이터베이스가 일정과 대기열 상태를 보존합니다.

지속되는 대화형 작업 공간

터미널을 닫은 뒤에도 이어져야 하는 로컬 작업에는 프로젝트 런타임을 선택합니다.

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

runtime attach도 런타임이 없으면 런타임을 시작합니다. 런타임 키는 정규화된 프로젝트 디렉터리이며, 동시에 시작해도 프로세스 하나를 재사용합니다. TUI는 실행 호스트와 연결 끊기 동작을 보여 줍니다. 연결을 끊으면 클라이언트는 닫히고 수락된 작업은 계속 실행됩니다. runtime stop는 그 프로젝트의 런타임을 종료하고 활성 작업을 중단합니다. 보통의 ax-code는 기존의 포그라운드 수명 주기를 유지합니다.

세션이 바쁜 동안 제출된 수락된 후속 작업은 서버에 저장됩니다. 기본적으로 실행 중인 턴이 끝난 뒤에 시작하므로, 관계없는 요청이 진행 중인 작업을 벗어나게 하지 않습니다. 실행 중인 턴을 고치려면 텍스트만 있는 초안으로 ctrl+s를 누릅니다(input_submit_steer, 위치는 keybinds). 그 텍스트는 활성 생성에 받아들여지고, 진행 중인 도구 호출이 정리된 뒤 다음 모델 요청 전에, 루프의 다음 단계 경계에서 사용자 메시지로 기록됩니다. 턴이 끝나는 중에 받아들여진 수정은 버려지지 않고 실행을 한 반복만큼 늘립니다. 조종은 최선의 노력입니다. 더 이상 활성이 아닌 생성이 없으면 초안은 보통 경로로 보내집니다. 훅이 거부하면 초안은 이유와 함께 작성기에 남습니다. 첨부가 있는 초안과 슬래시 명령은 항상 후속 대기열을 사용합니다. 같은 전달은 하네스 제어에 설명된 조종 API를 통해 다른 클라이언트에도 제공됩니다.

저장된 후속 작업은 나중에 조종할 수도 있습니다. 빈 작성기에서 ctrl+s를 누르면 대기열의 조종 가능한 접두부를 순서대로 올리고, 조종할 수 없는 첫 행에서 멈춥니다. 사이드바의 후속 작업 절과 /queue 대화 상자도 행마다 같은 지금 조종 동작을 제공합니다. 일시 중지된 행은 그 자리에서 조종할 수 있습니다. 턴을 중단하면 기다리는 후속 작업이 일시 중지되고, 그중 하나를 조종하면 대기열의 나머지를 재개하지 않고 그 텍스트만 전달됩니다. 후속 작업이 아닌 행(대기 중인 슬래시 명령, 셸 명령), 첨부가 있는 행, 비어 있거나 너무 큰 텍스트, 이미 실행 중이거나 끝난 행만 장벽입니다. 조종된 행은 steeredInto 감사 추적과 함께 취소되고 /queue 기록에 계속 보입니다. 활성 생성이 없으면 지금 조종은 그 행을 대기열 앞으로 우선하는 방식으로 돌아갑니다. 그래도 턴이 끝난 뒤에만 시작합니다. 작성기는 확인을 받은 뒤에만 비워집니다. 같은 세션에 다시 붙고 /queue로 검사, 일시 중지, 편집, 재개, 취소를 합니다. 편집은 먼저 항목을 일시 중지하고 첨부와 모델 선택을 보존합니다. 저장해도 재개되지 않습니다. 동시에 낡은 편집은 거부됩니다. /queue에서 Ctrl+R는 완료와 취소 기록을 포함합니다. 좁은 터미널은 클릭할 수 있는 Follow-ups 제목도 보여 줍니다. 연결이 끊긴 보기는 캐시되며 항목을 바꿀 수 없습니다. 활성 턴을 중단하면 대기 중인 후속 작업이 일시 중지되어 곧바로 다른 턴을 시작하지 않습니다. 준비되면 명시적으로 재개합니다.

백엔드가 다시 시작된 뒤, 수락되어 기다리던 후속 작업은 재개될 수 있습니다. 그 재시작으로 끊긴 보통의 진행 중 프롬프트는 실패로 표시되며, 다시 시도하기 전에 검사가 필요합니다. 대기열 기록을 복원해도 실행 중이던 셸 프로세스는 복원되지 않습니다. 잃어버린 확인은 그 클라이언트 세션 동안 바뀌지 않은 작성기에서 같은 요청 식별로 다시 시도할 수 있습니다. 저장되지 않은 초안은 수락된 작업이 아니며, 이것이 외부 효과의 정확히 한 번 실행을 보장하지는 않습니다.

이 모드는 로그인 서비스를 설치하지 않고, 멈춘 서버를 자동으로 다시 시작하지 않으며, 호스트가 잠자거나 전원이 꺼진 동안 실행하지 않습니다. 충돌 뒤에는 다시 시작하거나 붙습니다. 무인 서버 재시작에는 아래의 감독 서비스 예를 사용합니다. SSH 사용자는 깨어 있는 원격 호스트에서 런타임을 실행하고 거기에 붙어야 합니다. HTTP 포트를 공개적으로 노출하지 않습니다.

런타임 발견은 AX Code 상태 디렉터리의 runtime/ 폴더 아래에 비공개 능력과 로그를 저장합니다. 상태 출력은 능력을 생략합니다. 종료에는 저장된 PID만이 아니라 인증된, 일치하는 런타임 신원이 필요합니다. 실시간 프로세스를 쓸 수 없거나, 기록이 손상되었거나, 버전이 맞지 않으면 검사가 필요합니다. CLI는 검증되지 않은 프로세스를 죽이지 않습니다. 업그레이드 전에 건강한 런타임을 멈추고 새 실행 파일로 다시 시작합니다.

신뢰성 모델

사건	동작
기한이 된 발생이 커밋되기 전에 백엔드가 종료됨	그 발생은 기한 상태로 남습니다
일정에서 대기열로의 트랜잭션이 커밋된 뒤 백엔드가 종료됨	같은 대기 항목이 부트스트랩에서 재개됩니다
프롬프트가 시작된 뒤 백엔드가 종료됨	중단된 항목은 자동으로 재생되지 않고 실패로 표시됩니다
호스트가 여러 발생을 놓침	`run_once`는 그것들을 실행 하나로 합칩니다. `skip`는 실행하지 않고 진행합니다
대기열 실행이 마감을 넘김	실행기가 세션을 취소하고 실패한 대기열 항목을 기록합니다
감독자가 서버 종료를 봄	아래 예는 짧은 지연 뒤에 서버를 다시 시작합니다

이것은 중복에 안전한 복구이며, 임의의 외부 효과에 대한 정확히 한 번 전달이 아닙니다. 외부 시스템에 쓰는 통합은 여전히 자신의 멱등 키를 써야 합니다.

서비스를 설치하기 전에

서비스를 실행할 같은 사용자로 ax-code 실행 파일을 설치하고 시험합니다.
절대 프로젝트 경로를 하나 고릅니다. 서버 시작이 그 프로젝트를 미리 데우고 스케줄러를 시작하도록 AX_CODE_PROJECT로 설정합니다.
서버는 127.0.0.1에 둡니다. AX Code의 서버는 로컬 전용입니다.
공급자 자격 증명은 커밋된 서비스 파일이 아니라 감독자의 보호된 환경에 둡니다.
고른 예 안의 /absolute/path/... 자리 표시자를 모두 바꿉니다.

예는 Desktop 또는 SDK 클라이언트가 다시 연결할 수 있도록 고정 포트를 사용합니다.

ax-code serve --hostname=127.0.0.1 --port=4096

systemd 사용자 서비스

systemd 예를 ~/.config/systemd/user/ax-code.service로 복사하고, 절대 경로를 바꾼 뒤, 필요하면 자격 증명을 ~/.config/ax-code/server.env에 둡니다.

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

운영 정책이 사용자가 로그아웃한 동안에도 사용자 서비스 실행을 허용할 때만 loginctl enable-linger "$USER"를 사용합니다.

launchd 에이전트

launchd 예를 ~/Library/LaunchAgents/com.axcode.server.plist로 복사하고, 절대 경로를 바꾼 뒤 검증하고 적재합니다.

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd는 ProgramArguments 안의 셸 변수를 확장하지 않습니다. 절대 경로를 쓰고, 필요한 자격 증명은 운영자가 관리하는 방식으로 제공합니다.

PM2

PM2 예를 복사하고, 경로를 바꾼 뒤 시작합니다.

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

호스트를 재부팅한 뒤에도 프로세스가 돌아와야 하면 PM2의 플랫폼별 시작 지침을 따릅니다.

마감, 따라잡기, 복구

예약 작업의 기본은 catchUpPolicy: "run_once"입니다. 가동 중지 뒤에 AX Code는 제한 없는 밀린 작업을 만들지 않고 합쳐진 발생 하나를 실행합니다. 늦은 작업이 오해를 부르거나 안전하지 않을 때는 "skip"를 고릅니다.

각 예약 작업은 maxRunDurationMs를 1초부터 72시간까지 설정할 수 있습니다. 그 밖의 작업 대기열 실행은 72시간 상한을 사용합니다. 활성 항목은 30초마다 심박 타임스탬프를 갱신하고, 최종 상태와 오류 상세는 프로젝트 데이터베이스에 남습니다.

비동기 프롬프트, 명령, 셸 엔드포인트는 HTTP 202 응답으로 지속되는 대기열 항목을 반환합니다. 클라이언트는 그 id를 보관하고 GET /task-queue/:id를 completed, failed, 또는 cancelled가 될 때까지 폴링해야 합니다. 수락만으로는 완료가 아닙니다.

시작 시 지속되는 AX Code 백엔드는 예약된 대기열 항목과, 커밋되었으나 시작하지 않은 명시적으로 표시된 비동기 항목을 재개합니다. 일회성 CLI 명령은 그 항목의 소유권을 가져가지 않습니다. 이미 시작된 프롬프트 작업은 운영자가 부작용을 검사한 뒤 다시 시도할 수 있도록 재시작 설명과 함께 실패합니다.

예약 작업이 하는 일 보기

예약 작업의 모든 발생은 일어나는 동안 보이고, 그 뒤에도 감사할 수 있습니다.

시작, 완료, 실패, 건너뜀, 지속 실패의 자동 일시 중지 각각이 작업을 이름 짓는 앱 안 알림을 올립니다.
/schedule TUI 명령은 모든 작업을 상태, 일정, 다음 실행 시각, 마지막 오류와 함께 나열하고 최근 실행 기록을 엽니다. 거기서 일시 중지, 재개, 지금 실행, 삭제(확인하려면 ctrl+d를 두 번 누릅니다)를 할 수 있고, 실행이 만든 세션으로 이동할 수 있습니다. 에이전트의 list_scheduled_tasks와 list_scheduled_task_runs 도구가 같은 질문에 대화로 답합니다.
각 실행은 작업 제목이 붙은 새 세션에서 실행되므로, 알림을 놓쳐도 결과는 세션 목록의 항목 하나입니다.
다른 대화를 보는 동안 실행이 권한이나 질문 답을 요청하면, 경고 알림이 사용자를 필요로 하는 세션을 이름 짓습니다. /attention는 알려진 대기 요청을 나열하고 요청한 세션을 엽니다. 요청은 그 세션이나 적재된 조상의 보기에서 답할 수 있으며, 자식과 손자 세션도 포함됩니다. 요청을 열어도 자동으로 승인되지 않습니다.
일회성 작업은 성공한 실행 뒤에만 꺼집니다. 실패한 발생은 제한된 백오프로 다시 시도하고, 반복된 실패는 알림과 함께 작업을 일시 중지합니다. 알림이 더 이상 조용히 사라질 수 없습니다.

운영 점검

감독자의 재시작 횟수와 서버 로그를 봅니다.
다시 시도하기 전에 실패한 작업 대기열 항목과 예약 작업 오류를 검사합니다.
프로젝트 SQLite 데이터베이스와 로그에 충분한 디스크 공간이 있는지 확인합니다.
자격 증명, 모델, 서비스 경로를 바꾼 뒤 수동 지금 실행을 시험합니다.
AX Code가 SIGTERM를 받도록 감독자를 통해 멈춥니다. 예는 우아한 종료에 최대 90초를 허용합니다.

/loop는 의도적으로 프로세스 로컬이며 재시작을 견디지 못합니다. 지속되는 무인 작업에는 예약 작업을 사용합니다.

병렬 세션 탐색

터미널 열이 146 이상이면 왼쪽 탐색 사이드바가 현재 작업 공간의 세션과 적재된 자식 에이전트를 보여 줍니다. + 컨트롤로 행을 펼치고 제목을 클릭하면 열립니다. 고정된 세션은 순서와 단축 번호를 유지합니다. 전체 활동 레이블은 작업 중, 재시도, 승인, 질문을 구분합니다. 부모는 자손의 요청도 반영합니다. 이 레이블은 작업이 검증을 통과했다는 뜻이 아닙니다. 기존의 오른쪽 사이드바는 현재 세션의 맥락과 컨트롤을 유지합니다.

프로젝트 제목은 현재 디렉터리를 나타냅니다. 제목을 클릭하거나 /navigation-info를 사용하면 전체 프로젝트 경로와 현재 세션 제목을 봅니다. 최근은 적재된 세션을 보여 줍니다. 활성은 작업 중이거나 기다리는 세션 트리와 현재 세션 트리를 유지합니다. 필터는 탐색 선택기와 공유되고 기억됩니다. 키보드에서 바꾸려면 /navigation-filter를 사용합니다. 연결이 끊긴 동안에는 어떤 세션이 활성인지 추론하지 않고 캐시된 세션을 보여 줍니다. 지우기(또는 /navigation-clear)는 확인을 요청한 뒤 왼쪽 레일과 탐색 선택기에서만 역사적 행을 숨깁니다. 세션을 삭제하지는 않습니다. /sessions는 여전히 세션을 나열합니다. 현재 세션 트리, 고정된 세션, 관찰된 작업 중 또는 대기 트리는 레일에 남습니다. /sessions에서 세션을 열면 목록으로 다시 돌아옵니다.

/navigation-width 또는 탐색의 너비 동작으로 20, 24, 28, 30, 32, 36, 40열을 고릅니다(기본 28). 오른쪽 세션 사이드바도 같은 너비 동작과 /sidebar-width가 있습니다(기본 32). 두 선호는 기억되며, 본문을 지키기 위해 필요할 때 자동으로 줄어듭니다. 넓은 터미널에서 왼쪽 탐색 레일을 숨기거나 복원하려면 /navigation를 사용합니다. /sidebar는 같은 방식으로 오른쪽 세션 사이드바를 숨기거나 복원합니다. 더 좁은 터미널에서 /navigation는 세션과 에이전트 선택기를 엽니다. 보이는 세션 막대는 탐색 레일이 없을 때마다 같은 동작을 제공합니다. 알려진 요청에 입력이 필요하면 대기 동작이 나타납니다. 연결이 끊긴 동안 별표는 캐시된 수를 표시합니다. /sessions는 계속 보통의 세션 선택기를 엽니다. /attention는 모든 너비에서 사용할 수 있습니다. 연결이 끊긴 동안 그 목록은 캐시로 표시됩니다. 캐시된 항목을 여는 것은 여전히 가능하지만, 요청은 이미 다른 곳에서 답해졌을 수 있습니다. 사이드바의 알려진 요청 동작은 알려진 작업 공간 전체의 대기 요청을 열고, 세션 트리는 현재 프로젝트로 범위가 남습니다. 이 모든 보기는 연결된 인스턴스와 적재된 세션 데이터로 제한됩니다. 이 수는 다른 서버나 적재되지 않은 작업 공간의 완전한 목록이 아닙니다.

보내지 않은 초안은 실행 중인 TUI 안에서 프로젝트와 세션으로 격리됩니다. 세션을 바꾸면 텍스트, 첨부, 커서 위치, 셸 모드가 보존되고, 돌아오면 맞는 초안이 복원됩니다. 이 초안은 메모리에만 있으며 TUI를 닫으면 남지 않습니다.

선택적 완료 알림은 이제 Session idle라고 말합니다. 보고 있는 세션 하위 트리의 관찰된 작업을 따르고, 관찰된 활성 자손이 대기 요청 없이 명시적으로 유휴가 되기를 기다립니다. 연결 끊김, 재동기화, 없는 상태, 오류, 취소는 알림을 억제할 수 있습니다. 이것은 수명 주기 알림이며, 테스트가 통과했거나 목표가 완료되었다는 증거가 아닙니다.

새 작업과 설정

보통의 시작은 아래쪽 작성기와 세션 탐색이 있는 새 작업 작업면을 엽니다. 그것을 열거나 초안을 입력해도 저장된 세션은 만들어지지 않습니다. 세션은 제출할 때 만들어집니다. 기존 작업을 재개하려면 /sessions 또는 왼쪽 탐색을 사용합니다. 명시적인 --session, --continue, --prompt 동작은 계속 사용할 수 있습니다. 시작이 자동 재개를 켜지는 않습니다.

공급자 설정은 자동으로 열리지 않습니다. 공급자가 구성되지 않았으면 작업 영역의 보이는 /connect 동작을 사용합니다. 공급자는 구성되었으나 유효한 모델이 선택되지 않았으면 동작이 /models로 바뀝니다. 실패한 공급자 발견은 /status를 가리킵니다. /connect와 /providers는 구성을 고치기 위해 계속 사용할 수 있습니다. 선택된 모델은 구성 선택이며, 자격 증명이나 런타임 준비 검사가 아닙니다. 구성에 주의가 필요한 복귀 사용자에게도 같은 힌트가 나타납니다.