---
read_when:
    - 클라우드 워커 프로비저닝, 워커 모드 또는 세션 핸드오프 설계 및 구현
    - '`environments.*`, 워커 프로토콜, 트랜스크립트 수집 또는 추론 프록시 RPC 변경'
    - 원격 에이전트 실행의 보안 태세 검토
summary: Gateway 프록시 추론과 실시간 사이드바 스트리밍을 사용하여 SSH로 접근 가능한 임시 머신에서 에이전트 세션을 실행합니다.
title: 클라우드 작업자 계획
x-i18n:
    generated_at: "2026-07-12T00:56:26Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 134c3f6e486837607225d95d12a3153525b14237b362b9f9957313d9bc379dc4
    source_path: plan/cloud-workers.md
    workflow: 16
---

## 상태

제안, 개정판 3. 구현되지 않음. 2026-07에 방향 합의. 개정판 2에는 적대적 검토 결과(전용 워커 프로토콜, 배치/환경 상태 머신, Git 인식 인바운드 동기화, 단방향 v1 핸드오프, 제어된 이그레스 보안 표현)를 반영했다. 개정판 3에서는 동기화 소유권 모델(워커가 커밋을 작성하고 Gateway가 이를 채택해 게시)을 확정하고, Git을 사용하지 않는 일반 동기화 모드를 추가하며, 워커 실행을 박스 내부 전체 권한으로 수정하고, 인터넷 정책을 프로비저닝 시점으로 옮기고, 에이전트 디스패치를 마일스톤 3으로 복원한다.

## 문제

OpenClaw 에이전트 세션은 단일 머신의 Gateway 프로세스 내에서 루프, 도구 및 추론을 실행한다. 컴퓨팅 자원은 해당 머신의 한계에 묶이고, 장기 작업은 머신을 계속 점유하며, 병렬 작업은 동일한 자원을 두고 경쟁한다. 호스팅 제품(Cursor 클라우드 에이전트, 웹의 Claude Code, Codex 클라우드)은 작업별 임시 클라우드 샌드박스로 이 문제를 해결하지만, 공급업체 인프라와 공급업체에 대한 신뢰가 필요하다.

이미 여분의 머신을 보유했거나 저렴하게 임대할 수 있는 운영자도 다음과 같이 지정할 방법이 없다. 이 세션을 저쪽에서 실행하고, 다른 세션처럼 내 사이드바에 표시하며, 완료 후 머신을 폐기하라.

## 목표

- 전체 에이전트 세션(루프 + 도구)을 임시 원격 머신("클라우드 워커")에서 실행하면서, 세션이 로컬 세션과 완전히 동일하게 Control UI에 표시되고 스트리밍되도록 한다.
- 워커에 상시 자격 증명(공급자 인증, 포지 토큰)을 두지 않고 직접 네트워크 이그레스를 허용하지 않는다. 박스에는 접근 가능한 sshd만 있으면 된다.
- 프로비저닝, 동기화, 실행, 수집, 폐기를 완전히 자동화하고 공급자를 교체 가능하게 한다(첫 번째 공급자: Crabbox 형태의 임대 CLI).
- 트랜스크립트, 세션 ID 또는 요청 바이트가 동일하게 유지되는 경우의 공급자 캐시 친화성을 잃지 않으면서, 턴 경계에서 Gateway가 실행 중인 작업을 워커로 디스패치한다. 결과를 안전하게 다시 가져온다.
- 사람(UI)과 에이전트(도구) 모두 작업을 클라우드 워커로 디스패치할 수 있다.
- 며칠 동안 지속되는 세션을 지원한다. 수명은 하드코딩된 제한이 아니라 정책으로 정한다.

## 비목표(v1)

- 워커에서 외부 코딩 하네스(Claude Code, Codex CLI)를 사용하지 않는다. 워커 세션은 OpenClaw의 내장 러너만 실행한다. 하네스는 자체 자격 증명을 사용하여 자체적으로 추론하므로, 하네스 지원은 v2에서 명시적으로 활성화하는 기능이다.
- 최적 N개 선택 또는 병렬 시도 팬아웃을 지원하지 않는다.
- VPN/테일넷에 의존하지 않는다. 전송에는 SSH만 사용한다.
- 새 샌드박스 런타임을 추가하지 않는다. 워커 머신 자체가 격리 경계이며, 추후 박스 내부에 OS 샌드박싱을 계층적으로 추가할 수 있다.
- v1에서는 대칭형 라이브 마이그레이션을 지원하지 않는다. 디스패치는 로컬 → 워커 방향이다. 워커 → 로컬 방향은 세션이 중지되고 작업 공간 조정이 완료되어야 한다. 향후 동일한 배리어 메커니즘을 기반으로 양방향 라이브 핸드오프를 구축한다.
- Gateway에 JSON 보조 상태를 두지 않는다. 환경, 배치, 커서 및 권한 부여 상태는 SQLite에 저장한다.

## 선행 사례(차용하는 것과 반대로 적용하는 것)

- Cursor 클라우드 에이전트: 에이전트 루프는 해당 클라우드에서 실행되고, VM은 도구 실행 대상이며, 추가 전용 대화 저장소가 모든 클라이언트로 스트리밍되고, 설치 후 스냅샷을 사용해 빠르게 시작하며, 자체 호스팅 워커는 아웃바운드 전용 워커 프로세스다. "대화의 단일 진실 공급원은 오케스트레이터에 유지한다"는 원칙과 스트리밍 모델을 차용하되, 루프 배치는 반대로 적용한다(아래 결정 참조).
- Codex 클라우드: 네트워크가 연결된 설정 단계 후 비밀 정보를 제거한 오프라인 에이전트 단계로 이어지는 2단계 런타임을 사용하며, 빠른 후속 작업을 위해 컨테이너 상태를 캐시한다. 이 단계 분리를 이그레스 보안 방식으로 차용하고, 캐시 개념은 v2의 웜 이미지에 활용한다.
- 웹의 Claude Code: 세션별 VM, 자격 증명을 격리하는 Git 프록시(실제 토큰은 샌드박스에 들어가지 않으며 푸시는 세션 브랜치로 제한됨), 설정 후 파일 시스템 스냅샷, 푸시된 브랜치와 재생된 기록을 사용하는 텔레포트 핸드오프를 제공한다. 자격 증명 격리와 핸드오프 구성을 차용하되, 아웃바운드 동기화에는 Gateway의 rsync를 사용하므로 변경 사항이 커밋되지 않은 작업 트리도 처리할 수 있고 박스 근처 어디에도 포지 토큰이 존재하지 않는다.
- Copilot 코딩 에이전트: 패키지 레지스트리 허용 목록을 사용하는 기본 거부 이그레스 정책을 적용한다. 정상 실행 상태에서의 기본 정책은 추론과 웹 검색이 SSH 터널을 통해 제공되므로 더 강력하다(직접 이그레스가 전혀 없음). 다만 이것을 "이그레스 없음"이 아니라 "제어된 이그레스"라고 부르는 이유는 보안 섹션을 참조한다.

## 아키텍처 결정: 루프는 워커에서, 추론은 Gateway를 통해

세 가지 배치를 검토했다.

1. 루프는 Gateway에 유지하고 워커가 도구를 실행한다(Cursor 모델). 가장 안전한 장애 영역이다. 트랜스크립트, 추론, 승인 및 재시작 복구가 모두 로컬에 유지되며, 검토자가 첫 번째 마일스톤으로 선호한 방식이다. 그러나 제품 아키텍처로는 기각했다. OpenClaw의 실행 외 도구는 프로세스 내부 파일 시스템 작업이므로 모든 파일 읽기/편집/grep이 네트워크 왕복이 되거나, 도구 표면을 대규모로 리팩터링하여 거친 작업 공간 RPC로 바꿔야 한다. 런타임 동작은 호출이 빈번하고 지연 시간의 영향을 크게 받는다. 이미 구축된 부분(Node로 실행을 오프로드하는 기능)에서는 이 방식의 취지를 재사용하지만, 도구 원격화 계층은 구축하지 않는다.
2. 루프와 추론을 모두 워커에서 실행한다. 장애 영역은 가장 단순하지만, OAuth 프로필을 포함한 모델 자격 증명을 폐기 예정인 머신으로 보내야 하고, Gateway가 정책/라우팅/감사 제어권을 잃으며, 마이그레이션 시 공급자를 호출하는 ID가 변경되어 공급자 캐시가 무효화된다.
3. 루프와 도구는 워커에서 실행하고 모델 호출은 Gateway를 통해 프록시한다. 이 방식을 선택했다. 도구 호출마다 왕복하는 대신 모델 턴마다 한 번 왕복하며, 도구는 코드와 가까운 곳에서 실행된다. Gateway는 인증 프로필, 공급자 라우팅 및 정책의 단일 소유자로 유지되고, 워커에는 비밀 정보가 없다.

옵션 3의 비용은 각 모델 턴이 동기식으로 Gateway에 의존한다는 점이므로, 내구성 규칙은 사후 고려 사항이 아니라 결정의 일부다.

- 턴 도중 Gateway가 손실되면 활성 공급자 호출이 실패한다. 해당 턴은 실패로 표시되고 재연결 후 새 턴으로 재시도된다. 진행 중인 공급자 스트림을 투명하게 재생하지 않는다(이중 과금/이중 도구 호출 위험).
- 모든 워커↔Gateway 작업은 내구성 있는 ID를 포함한다(워커 프로토콜 참조). 따라서 재연결 시 작업이 방치되지 않고 재개되거나 캐시된 최종 결과를 가져온다.
- Gateway는 용량 관리 대상 구성 요소다. 동시 워커 제한, 흐름 제어 및 부하 차단은 v1 범위에 포함된다(용량 참조).

Gateway가 트랜스크립트를 저장하고 모든 공급자 트래픽의 출발점 역할을 모두 담당하므로 세션은 위치와 독립적이다. 루프를 Gateway와 워커 사이에서 이동해도 공급자 측이나 UI 데이터 경로는 전혀 변경되지 않는다. 이 특성 덕분에 디스패치와 회수가 저렴하다.

## 구성 요소

### 1. 환경 상태 머신 + 공급자 계약

Gateway 프로토콜의 `environments.*`는 현재 상태만 나타내는 투영이다. 내구성 있는 핵심은 RPC 형태보다 먼저 설계되는 SQLite 소유 환경 레코드와 상태 머신이다.

`요청됨 → 프로비저닝 중 → 부트스트래핑 중 → 준비됨 → (연결됨|유휴) → 드레이닝 중 → 폐기 중 → 폐기됨 | 실패 | 고립됨`

- 프로비저닝은 충돌에 안전하다. 결정적 작업 ID와 함께 공급자 호출 전에 의도 행을 영구 저장하므로, Gateway가 재시작되어도 중복 프로비저닝하거나 유료 머신을 고립시키는 대신 진행 중인 임대를 채택할 수 있다.
- 재시작 조정과 고립 리소스 정리기(공급자 `inspect`와 로컬 레코드 비교)는 강화 작업이 아니라 v1 요구 사항이다.

공급자 계약(Plugin으로 구현하며, 코어에는 공급자 이름이나 정책을 두지 않음):

```ts
type WorkerProvider = {
  id: string;
  provision(profile: WorkerProfile, opId: string): Promise<WorkerLease>; // → ssh host/port/user/key material
  inspect(lease: { leaseId: string; profile: WorkerProfile }): Promise<LeaseStatus>; // adopt/health/orphan sweep
  renew?(leaseId: string): Promise<void>; // long-lived sessions vs provider TTLs
  destroy(lease: { leaseId: string; profile: WorkerProfile }): Promise<void>; // idempotent, returns only on proof of teardown
};
```

RPC: `environments.create`, `environments.destroy`, 확장된 `environments.list/status`(공급자, 임대 ID, 상태, 사용 기간, 유휴 시간, 연결된 세션). 첫 번째 공급자는 Crabbox 형태의 임대 CLI 래퍼(제품 경로)와 개발 전용으로 표시된 정적 SSH 호스트 공급자다. 공유 호스트의 워커는 관련 없는 호스트 데이터를 읽을 수 있으므로, 정적 호스트는 기본 보안 방식이 아니라 기능 개발용이다.

### 2. 워커 부트스트랩: 박스에 OpenClaw 설치

별도의 워커 아티팩트를 만들지 않으며 npm 가용성에도 의존하지 않는다.

- 모든 모드의 표준 설치 방식은 Gateway에서 생성한 콘텐츠 해시 기반 워커 번들(Gateway 자체 빌드 출력을 tarball로 패키징)이다. 이 번들을 SSH로 전송하여 박스에 설치한다. 구조적으로 개발 빌드와 미출시 커밋도 지원한다.
- Gateway가 출시된 버전을 실행할 때는 `npm i -g openclaw@<exact gateway version>`을 최적화로 사용할 수 있다. `latest`는 절대 사용하지 않는다.
- 부트스트랩은 멱등적이다. 일치하는 번들 해시가 있는 웜 임대는 설치를 건너뛴다. 초기 상태의 머신에는 네트워크가 연결된 도구 체인 단계(Node 런타임)가 필요할 수 있다. 이는 설정 단계의 일부이며 이후에는 닫힌다.
- 핸드셰이크는 워커 빌드 해시, 프로토콜 기능 집합 및 런타임 호환성을 검증한다. 기존 Gateway 버전/프로토콜 검사는 이에 충분하지 않다(SSH 터널을 사용하는 Node는 정확한 버전 거부 검사에서 제외됨). 따라서 워커 허용 절차에서 자체적으로 정확한 빌드 검사를 수행한다.

워커 모드(`openclaw worker`)는 포크가 아니라 진입점이다. 연결 처리와 내장 에이전트 러너를 사용하며, 세션 영속화와 모델 호출은 Gateway RPC를 기반으로 한다. Gateway 기능을 시작해서는 안 된다. 채널을 시작하지 않고, 세션 도구 집합 외의 Plugin을 자동 시작하지 않으며, 폐기 가능한 상태 디렉터리를 사용하고, 로컬 인증 프로필을 두지 않는다.

### 3. 전송: 모든 통신에 SSH 사용

Gateway가 연결을 소유하며 워커에는 sshd 외에 아무것도 필요하지 않다.

- Gateway는 공급자 임대에서 받은 자격 증명으로 워커에 SSH 연결을 열고, 프로비저닝 출력에서 받은 호스트 키를 고정한다. `StrictHostKeyChecking=no`는 사용하지 않는다. 이후 워커 로컬 소켓을 Gateway의 WS 엔드포인트로 전달하는 역방향 터널을 구성한다.
- 제어/모델 트래픽과 작업 공간 전송은 동일하게 고정된 신뢰 자료를 사용하는 별도의 SSH 연결을 사용하므로, rsync가 토큰 스트림의 선두 차단을 일으키지 않는다.
- 터널 수명 주기(연결 유지, 백오프를 적용한 재연결)는 Gateway의 환경 런타임이 소유한다. 터널의 일시적 끊김은 세션 수준에서 드러나지 않는다. 아래의 내구성 있는 프로토콜 상태를 통해 워커가 다시 연결하여 재개할 수 있다.

### 4. 워커 프로토콜(Node 프로토콜과 분리된 전용 프로토콜)

현재 Node 접점을 대상으로 한 적대적 검토 결과 단순 재사용은 제외되었다. 대기 중인 Node 호출은 연결과 함께 사라지는 프로세스 로컬 Promise이고, Node 멱등성 키는 파싱되지만 중복 제거에 사용되지 않는다. 결정적으로, 연결된 Node는 에이전트 실행 요청을 포함한 일반 Node 이벤트를 내보낼 수 있으므로 "Node 종류 + 기능 상한"은 인그레스 보안 경계가 아니다. 따라서 워커에는 폐쇄형 버전 관리 RPC/이벤트 허용 목록을 적용하는 인증된 `worker` 역할을 부여한다. 워커 연결은 어떤 레거시 Node 이벤트 핸들러에도 접근할 수 없다.

ID 및 자격 증명: 프로비저닝 과정에서 환경 ID, 워커 키, 번들 해시, 허용된 단일 세션, 허용된 RPC 집합 및 만료 시각에 바인딩된 단기 워커 자격 증명을 발급한다. SSH로 검증된 페어링도 계속 적용하지만(박스를 프로비저닝했고 키를 보유함), 권한 부여는 선언된 Node 표면이 아니라 발급된 자격 증명을 기반으로 한다.

내구성 있는 작업 의미 체계(기존 ACP 런타임과 해당 이벤트 원장의 형태를 차용: 안정적 핸들, 세션별 직렬화, 내구성 있는 `(session, seq)` 재생):

- 모든 작업의 범위는 `(sessionId, lifecycleRevision, runId, ownerEpoch, streamKind, seq)`다.
- 소유권 에포크는 오래된 워커를 차단한다. 대체 워커가 에포크를 증가시키며, 이전 에포크에서 늦게 도착한 결과는 결정적으로 거부된다.
- 영속화된 ACK 커서와 SQLite에 캐시된 최종 결과를 사용하여 최소 한 번 전달하며, 중복 제거는 결정적으로 수행한다. 정확히 한 번 전달은 보장하지 않는다.
- 취소, 닫기, 재개 및 최종 결과를 위한 명시적 프레임을 제공하며, 스트림에는 크레딧/윈도 기반 흐름 제어를 적용한다.
- 프로토콜 기능 협상은 일반 Node 프로토콜 버전과 독립적이다.

### 5. 세션 백엔드 RPC

서로 다른 두 계약 — 현재 코드베이스는 영속적인 트랜스크립트 변경(세션 관리자 소유, 부모/리프 상태를 포함하는 JSONL 트리)과 프로세스 로컬 라이브 이벤트(스트리밍 델타, 도구 수명 주기, 승인)를 분리하며, 워커 프로토콜은 이 분리를 유지해야 합니다.

- 영속적 트랜스크립트 커밋: 워커는 `runEpoch`와 기준 리프 비교 후 교환을 포함하는 의미론적 추가 배치를 제출하고, Gateway 세션 관리자가 항목 ID와 부모 ID를 생성합니다. 워커는 신뢰되는 트랜스크립트 행, 항목 ID, 부모 ID 또는 외부 세션 ID를 절대 제공할 수 없습니다.
- 재생 가능한 라이브 이벤트: 워커 시퀀스 번호, Gateway ACK, 제한된 보존 범위, 지연 이벤트 펜싱을 갖춘 형식화된 이벤트 유니온입니다. 기존 에이전트 이벤트 팬아웃에 전달되어 채팅 보기, 도구 행, 읽지 않음/상태 로직이 로컬 세션과 동일하게 동작합니다.

추론 프록시: 기존 런타임 프록시 스트림 클라이언트(`src/agents/runtime/proxy.ts`)의 이벤트 어휘를 재사용하되 신뢰 경계를 이동합니다. 워커는 세션/실행 ID, 승인된 모델 참조, 컨텍스트, 제한된 생성 옵션만 전송합니다. Gateway는 자체 카탈로그에서 제공자, 엔드포인트, 인증, 헤더, 라우팅, 비용 정책을 확인합니다. 워커가 제공한 모델 객체(예: 공격자가 제어하는 `baseUrl`)는 거부됩니다. 요청 크기 제한, 취소, 감사, 최종 결과 재생이 적용됩니다. Gateway 상주 도구(웹 검색)는 Gateway에서 실행되고 동일한 채널을 통해 결과를 반환합니다.

### 6. 작업 공간 동기화

동기화 기준점은 배치에 대한 독점 소유권을 가진 Gateway 로컬 작업 공간입니다. Git 작업 공간의 경우 전용 관리형 워크트리(기존 관리형 워크트리 메타데이터인 브랜치, 기준점, 스냅샷 소유권이 기반)가 사용되며, 비 Git 작업 공간의 경우 Gateway 소유 대상 디렉터리가 사용됩니다. 사용자의 실제 체크아웃은 절대 사용하지 않습니다. 세션이 원격으로 배치된 동안의 독점 소유권 덕분에 인바운드 동기화는 구조적으로 충돌하지 않습니다.

소유권 분리 — 커밋과 게시:

- 워커 측 에이전트는 자신의 복사본에서 일반적으로 커밋을 작성합니다(`git commit`은 로컬에서 자격 증명 없이 수행되는 작업이며, 작성자 ID는 Gateway 구성에서 투영됩니다). 해당 커밋은 Gateway가 채택하기 전까지 비활성 객체입니다.
- 신뢰가 필요한 모든 작업은 Gateway가 수행합니다. 여기에는 인바운드 커밋이 기록된 기준점을 기반으로 하는지 확인, 로컬 워크트리의 빨리 감기, 푸시, PR 생성, 선택적 서명/재서명이 포함되며, 모두 Gateway 로컬 자격 증명으로 수행됩니다. 워커는 Git 또는 포지 자격 증명을 보유하지 않으며 원격 저장소에 접근하지 않습니다.

작업 공간이 Git 저장소인지에 따라 두 가지 동기화 모드 중 하나를 선택합니다.

- Git 모드. 아웃바운드: 터널의 SSH ID를 통해 워크트리를 rsync하며(커밋되지 않은 파일과 대상에 해당하는 추적되지 않은 파일 포함, crabbox 방식의 포함/제외, `.worktreeinclude` 준수), 변경 불가능한 기준 매니페스트(콘텐츠 해시 + 기준 커밋)로 기록합니다. 인바운드: 새 커밋은 기록된 기준점에 대한 Git 번들 또는 임시 참조로 반환됩니다. 추적되지 않은 아티팩트는 크기/유형/심볼릭 링크 포함 범위 검사를 갖춘 명시적 매니페스트를 통해 반환됩니다. 채택 시 기준점의 조상 관계를 확인하고 분기가 발생하면 중단하므로 어느 쪽도 조용히 덮어쓰지 않습니다. 삭제, 이름 변경, 서브모듈, 심볼릭 링크 이탈은 rsync 휴리스틱이 아니라 매니페스트 규칙으로 처리됩니다.
- 일반 모드(Git 없음 — 예: 해당 박스에서 프로젝트를 처음부터 빌드하는 경우). 아웃바운드는 동일한 rsync + 기준 매니페스트를 사용합니다. 인바운드는 삭제 전파를 포함하여 매니페스트 차이를 반영한 미러를 Gateway 소유 대상 디렉터리로 돌려보냅니다. Git 모드와 같은 이유로 안전합니다. 독점 소유권 때문에 충돌할 동시 로컬 편집이 없으며, 기준 매니페스트는 여전히 예상치 못한 로컬 변경을 감지하여 덮어쓰는 대신 중단합니다.

체크포인트는 장기간 세션을 임대 손실로부터 보호합니다. 주기적인 인바운드 체크포인트(Git 모드에서는 세션 브랜치 커밋, 일반 모드에서는 매니페스트 스냅샷)를 생성하며, 주기는 프로필 정책입니다(기본값은 턴 기반).

### 7. 배치 상태 머신, 세션 및 UI

런타임 배치는 느슨한 두 행 필드가 아니라 세션을 키로 사용하는 SQLite 소유 상태 머신입니다.

`local → requested → provisioning → syncing → starting → active(worker) → draining → reconciling → local | reclaimed | failed`

환경 ID, 전환 세대, 활성 소유자 에포크, 작업 공간 기준 매니페스트, 워커 번들 해시, 마지막 ACK 커서를 영속화합니다. 턴 허용 과정에서 두 루프 중 하나가 턴을 시작하기 전에 배치를 원자적으로 점유하므로, 오래된 스냅샷을 기준으로 허용된 로컬 메시지가 워커 턴과 경쟁할 수 없습니다. 항상 정확히 하나의 루프만 세션을 소유합니다.

UI:

- 워커 세션은 배치 메타데이터가 추가된 일반 세션 행입니다. 정상 저장소에 존재하고 `sessions.list`를 통해 나열되며 기존 구독을 통해 스트리밍됩니다. 사이드바와 채팅에는 새로운 데이터 경로가 필요하지 않고 표시 요소만 추가하면 됩니다. 워커 배지와 배치/환경 상태(`provisioning / syncing / running / idle / reconciling / reclaimed`)가 이에 해당합니다.
- 생성 UX: 세션 대상 표시줄(세션 사이드바 재설계)에 Gateway 및 Node와 함께 클라우드 워커 대상이 추가됩니다. 구성된 제공자 프로필이 필요하며, 구성되기 전에는 이 기능이 표시되지 않습니다.
- 에이전트 디스패치: 세션 도구를 통해 에이전트가 사람이 하는 것처럼 작업을 클라우드 워커로 넘길 수 있습니다(워커 기반 하위 세션, 하위 에이전트 방식). 사람 디스패치와 동일한 마일스톤에서 제공되며 같은 옵트인 제공자 구성으로 제한됩니다. 재귀는 구조적으로 제한됩니다(v1에서는 워커 세션이 다른 워커를 디스패치할 수 없음). 지출 제어는 할당량 시스템이 아니라 환경별 회계/감사를 통해 수행됩니다.

## 디스패치 및 인계

v1은 의도적으로 비대칭입니다.

- 로컬 → 워커(디스패치): 아래의 마이그레이션 장벽을 통과하고, 워커를 프로비저닝하거나 재사용한 뒤 동기화하고 배치를 전환합니다. 다음 턴은 원격에서 실행됩니다.
- 워커 → 로컬(되가져오기): 세션을 중지하고(동일한 장벽에 따라 워커 드레이닝), 인바운드 조정을 완료한 뒤 배치를 로컬로 전환합니다. 라이브 마이그레이션이 아닙니다.
- 대칭형 라이브 인계(활성 작업 중인 세션을 중지하지 않고 양방향으로 이동)는 동일한 장벽과 조정 메커니즘을 재사용하며, 장애 주입 테스트에서 장벽이 검증된 후 제공됩니다.

마이그레이션 장벽("턴 경계"만으로는 부족함 — 승인, 백그라운드 프로세스, 잠금 해제 후의 트랜스크립트 병합이 경계를 걸칠 수 있음):

1. 새 턴 허용을 중지합니다(배치 점유).
2. 활성 실행을 취소하거나 드레이닝합니다.
3. 대기 중인 실행 승인과 실행 권한을 취소합니다.
4. 트랜스크립트 부수 기록과 라이브 이벤트 ACK를 드레이닝합니다.
5. 워커 자식 프로세스를 종료합니다.
6. 소유자 에포크를 증가시켜 이전 소유자를 펜싱합니다.
7. 작업 공간을 조정합니다(인바운드, 충돌 인식).
8. 새 소유자를 활성화합니다.

캐시 친화성: 두 배치 모두에서 제공자 요청이 Gateway에서 시작되므로, 직렬화된 제공자 요청이 동등하게 유지될 때 캐시 친화성이 보존됩니다. 즉, 도구 순서, 시스템 지침, 제공자 래퍼, 캐시 메타데이터가 동일해야 하며, 이들은 Gateway 측에 유지됩니다. 이는 가정이 아니라 테스트 가능한 속성입니다. 워커 루프를 도입하는 마일스톤에는 지원되는 각 제공자 전송 방식에 대해 로컬/워커 배치 간 바이트 동등성 테스트가 포함됩니다.

## 보안 모델

정확히 말하면 워커에는 직접적인 네트워크 이그레스와 상시 제공자/포지 자격 증명이 없습니다. 그러나 "이그레스 없음"은 아닙니다. 추론과 Gateway 실행 도구는 제어된 이그레스 채널입니다(프롬프트 인젝션을 당한 워커도 작업 공간 바이트를 모델 컨텍스트나 웹 검색 쿼리에 포함할 수 있음). 따라서 다음이 적용됩니다.

- 제어된 이그레스 회계: 추론 프록시와 Gateway 도구에 환경별 감사 및 운영자가 확인할 수 있는 회계를 적용합니다. 속도/바이트 제한은 지출 할당량 시스템이 아니라 프로토콜 흐름 제어(용량)로 존재합니다.
- 워커에서 Gateway로의 인그레스는 폐쇄형 워커 프로토콜 허용 목록입니다. 트랜스크립트 쓰기는 구조적으로 제한됩니다(Gateway가 생성한 ID, 바인딩된 단일 세션).
- 워커 실행은 박스 내부에서 모든 권한을 가집니다. 박스는 폐기 가능하고 자격 증명이 없으므로 명령별 승인은 보호 효과 없이 불편만 더합니다. 보호되는 경계는 인바운드 조정과 감사입니다. 실행은 Gateway Node 승인 경로를 절대 통과하지 않습니다.
- 인터넷 정책은 프로비저닝 시 제공자가 결정합니다. 환경 프로필이 박스 생성 시 결정하며(방화벽/보안 그룹/이그레스 차단 네트워크), 선택적으로 네트워크가 연결된 설정 단계를 제공자가 에이전트 단계 전에 종료할 수 있습니다. 코어는 런타임 네트워크 토글을 구현하지 않습니다.
- 프로비저닝 시 박스 위생: 클라우드 메타데이터 엔드포인트를 차단하거나 부재를 확인하고, 인스턴스 프로필과 상속된 SSH 에이전트 및 Docker 소켓이 없어야 하며, 깨끗한 환경/홈을 사용합니다. SSH 호스트 키는 프로비저닝 출력값을 기준으로 고정합니다.
- Gateway 측에서 수행되는 모든 작업(푸시, PR, 제공자 호출)의 승인과 정책은 계속 Gateway에서 실행됩니다.

침해된 워커 세션의 피해 범위는 동기화된 작업 공간 복사본과 감사되는 프록시 채널이 허용하는 범위로 제한됩니다. 자격 증명도, 직접 네트워크도, 허용 목록 외의 Gateway 접근 표면도 없습니다.

## 용량

Gateway는 N개 워커의 모든 프롬프트와 토큰 스트림을 중계하므로, v1에서는 운영 환경에서 뒤늦게 파악하는 대신 용량 모델을 명시합니다. Gateway별 동시 워커 제한, 스트림별 크레딧 윈도우(현재 이벤트 스트림 큐는 무제한이고 Node 소켓 버퍼 상한은 느린 소비자를 강제 종료하므로 둘 다 수정 없이 사용하기에는 부적합), 버스트를 위한 제한된 디스크 스풀링, UI에 표시되는 역압 상태와 함께하는 부하 차단이 포함됩니다. 작업 공간 전송은 별도의 SSH 채널을 계속 사용합니다.

## 수명 주기

- 유휴 자동 중지와 TTL은 고정 상수가 아니라 제공자 프로필 정책입니다. 기본값은 명시적인 연결 유지와 함께 넉넉하게 설정됩니다. 며칠 동안 지속되는 작업은 일급 기능이며(임대 기반 백엔드에는 제공자 `renew`가 존재), 턴이 진행 중이거나 최근 활동이 있는 세션은 절대 회수되지 않습니다.
- 워커 사망 또는 회수 시 배치가 `reclaimed`로 이동하고 세션 행은 유지됩니다. 다음 메시지가 새 워커를 프로비저닝하고 마지막 체크포인트에서 다시 동기화합니다. 대화는 절대 손실되지 않지만(Gateway 측 저장소), 마지막 체크포인트 이후의 작업 공간 변경 사항은 손실되며 UI에 이를 표시합니다.
- 첫날부터 웜 임대 재사용을 지원합니다(이를 지원하는 제공자에 한함). 부트스트랩 이후의 이미지 스냅샷은 v2의 빠른 시작 경로입니다.

## 구성 표면

최소한으로 옵트인합니다. 제공자 프로필 블록(제공자 ID, 자격 증명/CLI 참조, 동기화 규칙, 수명 정책, 예산, 선택적 설정 단계)과 세션별 배치 선택만 포함합니다. 새 환경 변수는 없습니다. 구성되지 않은 설치 환경에서는 아무것도 표시되지 않습니다.

## 마일스톤

구현은 작고 독립적으로 병합 가능한 PR로 반영됩니다. 아래의 각 마일스톤은 하나의 변경이 아니라 일련의 PR입니다.

1. 기반: 환경 상태 머신 + 제공자 계약 + crabbox 형태 제공자(개발 하네스로서 정적 SSH), 워커 번들 부트스트랩 + 허용 핸드셰이크, SSH 터널 + 호스트 키 고정, 관리형 워크트리 스냅샷 + 아웃바운드 동기화(Git + 일반 모드). 고아 항목 정리 + 재시작 시 채택.
2. 워커 프로토콜 + 워커 루프: 인증된 워커 역할, 영속 작업/에포크/ACK 커서, 트랜스크립트 커밋 + 라이브 이벤트 계약, Gateway에서 확인한 모델을 사용하는 추론 프록시, 흐름 제어. 제공자 하나, 새 세션에 대한 사람 디스패치만 지원하며 인계는 지원하지 않습니다. 장애 주입 테스트(터널 분할, Gateway 재시작, 워커 사망)를 통과해야 완료됩니다.
3. 디스패치 + 되가져오기 + 에이전트 디스패치: 마이그레이션 장벽, UI 대상 표시줄에 연결된 배치 상태 머신, 인바운드 조정 + 체크포인트, 환경별 감사, 용량 제한, 에이전트 디스패치 도구(워커 세션은 재귀 불가). 프롬프트 캐시 바이트 동등성 테스트.
4. 마일스톤 3의 장애 주입 검증 이후 대칭형 라이브 인계.

향후: 환경별 자격 증명 주입 옵트인 방식으로 워커에서 ACP 하네스 지원, 스냅샷/웜 이미지 빠른 시작, 팬아웃(N개 임대, 동일한 프롬프트), 박스 내부 OS 샌드박싱, 아티팩트 스키마를 통한 더 풍부한 아티팩트 수집.

## 미해결 질문

- 워커의 Plugin/Skills 가용성: 저장소에 포함된 Skills는 워크스페이스와 함께 자동으로 동기화되며, Gateway에서 구성한 에이전트 Skills/Plugin은 명시적으로 동기화하거나 제외하도록 결정해야 합니다(어느 쪽이든 도구/Plugin 매니페스트는 승인 핸드셰이크에 포함됩니다).
- 체크포인트 주기의 기본값: 대화량이 매우 많은 세션에서 턴 기반 또는 시간 기반.
- 환경 프로필과 멀티 에이전트 라우팅의 상호작용 방식(에이전트별 기본 프로필 또는 세션별 선택만 허용).