12.1. OpenClaw / NanoClaw 마이그레이션 가이드¶

이 가이드는 OpenClaw 또는 NanoClaw에서 Backend.AI GO Squad로 전환하는 사용자를 위한 문서입니다. 개념 매핑, 설정 이전, 동작 차이점, 단계별 이전 튜토리얼, 자주 묻는 질문을 다룹니다.

개념 매핑¶

Backend.AI GO Squad는 NanoClaw의 그룹-에이전트 모델을 현대적인 멀티 에이전트 워크스페이스로 재설계했습니다. 아래 표는 NanoClaw의 각 개념을 Squad 상응 개념에 매핑합니다.

역할 매핑¶

NanoClaw는 자유 형식 역할 문자열을 사용했습니다. Backend.AI GO Squad는 전문화된 기본값을 가진 구조화된 역할을 제공합니다.

설정 이전¶

환경 설정¶

NanoClaw 그룹 설정이 .env 또는 group-config.json에 저장된 경우, Backend.AI GO 설정으로 매핑됩니다.

NanoClaw .env 또는 설정 파일:

NANOCLAW_GROUP_NAME=my-dev-team
NANOCLAW_MODEL=claude-3-5-sonnet
NANOCLAW_MAX_ITERATIONS=20
NANOCLAW_TIMEOUT_MS=120000
NANOCLAW_CONTAINER_IMAGE=nanoclaw-runner:latest
NANOCLAW_ALLOW_NETWORK=false

Backend.AI GO Squad 상응 설정:

1. 사이드바에서 Squad를 열고 새 Squad를 클릭합니다.
2. 1단계 기본 정보에서 Squad 이름을 설정합니다.
3. 각 에이전트 설정 패널에서 모델을 선택하거나, modelPreference가 설정된 에이전트 프로필을 사용합니다.
4. 최대 반복 횟수와 타임아웃은 설정 > 에이전트(전역 기본값)에서 설정하거나, settingsOverrides가 있는 에이전트 프로필을 통해 에이전트별로 설정합니다.
5. 컨테이너 이미지는 Squad 편집기에서 에이전트별로 실행 모드 > 컨테이너 > 이미지에서 설정합니다.

설정 > 에이전트 (전역 기본값):

최대 반복 횟수: 20       ← NANOCLAW_MAX_ITERATIONS
타임아웃: 120000 ms      ← NANOCLAW_TIMEOUT_MS

그룹 폴더¶

NanoClaw 그룹 폴더는 공유 파일과 에이전트 메모리를 저장했습니다. Backend.AI GO Squad에서 상응하는 것은 Squad 워크스페이스입니다.

NanoClaw 그룹 폴더 구조:

~/nanoclaw-groups/my-dev-team/
├── CLAUDE.md            ← 그룹 수준 지침
├── memory/
│   ├── agent-alice.md
│   └── agent-bob.md
├── workspace/
│   └── ...프로젝트 파일...
└── tasks/
    └── task-001.json

Backend.AI GO Squad 워크스페이스 구조:

~/my-squads/my-dev-team/        ← Squad 워크스페이스 디렉터리
├── .squad-config.json          ← Squad 매니페스트 (자동 생성)
├── plans/                      ← 작업 플랜
├── tasks/                      ← 작업 상태 파일
├── agents/
│   ├── alice/
│   │   └── memory.md           ← 에이전트별 메모리
│   └── bob/
│       └── memory.md
├── ipc/                        ← 호스트-컨테이너 IPC (컨테이너 모드 전용)
│   ├── input/
│   ├── messages/
│   └── tasks/
└── ...프로젝트 파일...

이전하려면 기존 프로젝트 파일을 새 워크스페이스 디렉터리에 복사합니다. 메모리 파일은 agents/{에이전트-이름}/memory.md에 복사할 수 있습니다.

CLAUDE.md 이전¶

NanoClaw는 그룹 수준과 폴더 수준 모두에서 에이전트 지침을 위해 CLAUDE.md 파일을 사용했습니다.

그룹 수준 CLAUDE.md → Squad 에이전트 시스템 프롬프트

그룹 수준 CLAUDE.md의 내용을 Squad 편집기의 각 에이전트 시스템 프롬프트 필드에 붙여넣습니다. 에이전트마다 다른 지침 파일이 있었다면, 각 에이전트에 해당 내용을 붙여넣습니다.

폴더 수준 CLAUDE.md → Cowork 폴더 지침

폴더별 컨텍스트를 위해 폴더 수준 CLAUDE.md를 사용한 경우(예: 폴더의 내용 설명), 대신 Cowork 폴더 지침을 사용합니다.

1. 사이드바에서 Cowork를 엽니다.
2. 폴더 지침으로 이동합니다.
3. 폴더 경로를 추가하고 내용을 붙여넣습니다.

폴더 지침은 에이전트가 해당 디렉터리에 접근할 때마다 자동으로 에이전트의 컨텍스트에 주입됩니다.

채널 설정¶

채널 설정은 NanoClaw와 Backend.AI GO 간에 동일합니다. 기존 채널 자격 증명을 그대로 사용할 수 있습니다.

채널 이전 방법:

1. Backend.AI GO에서 설정 > 채널을 엽니다.
2. 채널 유형(Telegram, Slack, Discord, WhatsApp)을 선택합니다.
3. NanoClaw에서 사용한 것과 동일한 자격 증명을 입력합니다.
4. 연결을 클릭하고 상태가 연결됨으로 표시되는지 확인합니다.

발신자 허용 목록 이전¶

NanoClaw의 allowlist.json은 Backend.AI GO의 발신자 허용 목록으로 직접 매핑됩니다.

NanoClaw allowlist.json:

{
  "telegram": ["123456789", "987654321"],
  "slack": ["U01234ABCD"]
}

Backend.AI GO:

1. 설정 > 채널 > [채널 이름]을 엽니다.
2. 발신자 허용 목록을 클릭합니다.
3. NanoClaw 허용 목록의 각 발신자 ID 또는 사용자 이름을 입력합니다.

채널-Squad 매핑¶

NanoClaw에서는 채널이 이름으로 그룹을 트리거했습니다. Backend.AI GO에서는 채널을 특정 Squad에 매핑합니다.

1. 설정 > 채널을 열고 연결된 채널을 선택합니다.
2. Squad 매핑 아래에서 이 채널의 메시지를 처리할 Squad를 선택합니다.
3. 선택적으로 초기 메시지를 받을 Squad 내 기본 에이전트를 설정합니다.

고급 라우팅 규칙은 채널-Squad 매핑 가이드를 참조하세요.

동작 차이점¶

컨테이너 이미지¶

NanoClaw는 컨테이너 기반 이미지로 nanoclaw-runner를 사용했습니다. Backend.AI GO는 aigo-agent-runner를 사용합니다.

Backend.AI GO 에이전트 러너 이미지를 빌드하려면 컨테이너 실행 가이드를 따르세요.

IPC 프로토콜¶

NanoClaw 에이전트는 호스트-컨테이너 통신에 stdio 기반 IPC를 사용했습니다. Backend.AI GO는 워크스페이스 IPC 디렉터리를 통한 파일 기반 IPC를 사용합니다.

NanoClaw의 stdio IPC를 읽는 사용자 정의 도구가 있다면, 파일 기반 IPC 형식을 사용하도록 업데이트해야 합니다. IPC 디렉터리 구조는 src-tauri/src/container/ipc.rs를 참조하세요.

계획 수립 및 실행¶

NanoClaw는 각 에이전트가 암묵적으로 자체 단계를 결정하는 방식에 의존했습니다. Backend.AI GO Squad는 구조화된 작업 그래프를 생성하는 명시적인 Planner 에이전트를 도입합니다.

추가 기능¶

Backend.AI GO Squad에는 NanoClaw에 없는 기능이 포함됩니다.

단계별 이전 튜토리얼¶

이 섹션은 my-dev-team이라는 샘플 NanoClaw 그룹을 Backend.AI GO Squad로 이전하는 과정을 안내합니다.

1단계: 기존 설정 목록 작성¶

이전 전에 NanoClaw 설정에서 다음 항목을 수집합니다.

• 그룹 설정 파일 (.env, group-config.json 또는 동등한 파일)
• 그룹 멤버 목록 (이름, 역할, 시스템 프롬프트)
• 그룹 수준 CLAUDE.md 내용
• 채널 자격 증명 및 허용 목록
• 그룹 워크스페이스 폴더 위치

2단계: Backend.AI GO 설치¶

go.backend.ai에서 최신 Backend.AI GO를 다운로드하고 설치합니다. 처음 실행 시 초기 설정 마법사를 완료하고 모델이 로드되어 실행 중인지 확인합니다.

3단계: 컨테이너 런타임 설정 (선택 사항)¶

NanoClaw 설정에서 컨테이너를 사용한 경우, 먼저 컨테이너 런타임을 설치합니다. 인프로세스(비컨테이너) 실행을 사용한 경우 이 단계를 건너뜁니다.

1. 컨테이너 실행 가이드를 따릅니다.
2. 에이전트 러너 이미지를 빌드합니다: Backend.AI GO 소스 디렉터리에서 make build-agent-runner를 실행하거나 빌드 스크립트를 따릅니다.
3. 설정 > 컨테이너 > 사용 가능한 이미지에 이미지가 표시되는지 확인합니다.

4단계: Squad 생성¶

1. 사이드바에서 Squad를 클릭합니다.
2. 새 Squad를 클릭하고 커스텀을 선택합니다(기존 설정과 일치시키기 위해 템플릿이 아닌).
3. 그룹 이름을 Squad 이름으로 입력합니다. 다음을 클릭합니다.
4. 워크스페이스 단계에서 기존 NanoClaw 그룹 폴더를 선택하거나 새 디렉터리를 생성합니다. 같은 폴더를 재사용하면 Backend.AI GO가 기존 파일을 건드리지 않고 .squad-config.json 매니페스트를 추가합니다. 다음을 클릭합니다.
5. 에이전트 단계에서 각 그룹 멤버에 대해 에이전트 추가를 클릭합니다.
   • 에이전트 이름을 그룹 멤버 이름으로 설정합니다.
   • 가장 가까운 역할을 선택합니다(Planner, Developer, Reviewer, Writer, Custom).
   • 그룹 멤버의 CLAUDE.md 내용 또는 시스템 프롬프트를 시스템 프롬프트에 붙여넣습니다.
   • NanoClaw에서 에이전트가 사용한 것과 동일한 도구를 활성화합니다.
   • 에이전트에 메모리 파일이 있었다면 메모리를 활성화합니다.
   • 컨테이너를 사용하는 경우 실행 모드를 컨테이너로 설정하고 이미지로 aigo-agent-runner:latest를 입력합니다.
6. 에이전트 하나를 Planner로 지정합니다(Planner로 지정 체크). 일반적으로 그룹 리더입니다.
7. 다음을 클릭하고 설정을 검토한 후 생성을 클릭합니다.

5단계: 메모리 파일 이전¶

NanoClaw 에이전트에 메모리 파일이 있었다면:

1. 파일 관리자에서 Squad의 워크스페이스 디렉터리를 엽니다.
2. 각 에이전트에 대해 NanoClaw 메모리 파일을 agents/{에이전트-이름}/memory.md로 복사합니다.
3. 에이전트는 다음 실행 시 이 메모리를 자동으로 로드합니다.

6단계: 채널 설정¶

1. 설정 > 채널을 엽니다.
2. NanoClaw와 동일한 자격 증명으로 각 채널을 추가합니다.
3. Squad 매핑 아래에서 각 채널을 4단계에서 생성한 Squad에 매핑합니다.
4. NanoClaw 허용 목록의 모든 발신자 ID를 발신자 허용 목록에 추가합니다.

7단계: 예산 한도 설정 (선택 사항이지만 권장)¶

1. Squad를 열고 편집을 클릭합니다.
2. 예산 섹션으로 이동합니다.
3. 워크로드에 적합한 토큰 한도를 설정합니다. 시작점으로, NanoClaw 실행에서의 총 토큰 사용량을 Squad 총 예산으로 사용합니다.

8단계: 테스트 작업 실행¶

1. Squad를 열고 실행을 클릭합니다.
2. 간단한 테스트 요청을 입력합니다(예: "이름과 역할을 확인하며 인사하세요.").
3. 생성된 플랜을 검토하고 승인을 클릭합니다.
4. 모니터링 탭에서 실행을 모니터링합니다.
5. 모든 에이전트가 성공적으로 완료되고 출력이 워크스페이스에 나타나는지 확인합니다.

9단계: 채널 연동 확인¶

채널을 설정한 경우, 허용된 발신자로부터 테스트 메시지를 보냅니다. Squad가 메시지를 수신하고 동일한 채널을 통해 응답해야 합니다.

자주 묻는 질문¶

컨테이너 이미지를 다시 빌드해야 하나요?¶

네. NanoClaw는 Backend.AI GO와 호환되지 않는 nanoclaw-runner 이미지를 사용했습니다. 제공된 빌드 스크립트를 사용하여 aigo-agent-runner를 빌드해야 합니다. NanoClaw 이미지에 커스텀 의존성을 추가했다면, 빌드 전에 Backend.AI GO Dockerfile.agent-runner에 추가하세요.

NanoClaw 그룹 워크스페이스를 그대로 재사용할 수 있나요?¶

네. Squad 설정 마법사에서 기존 워크스페이스 디렉터리를 선택하면 기존 파일을 건드리지 않고 폴더에 .squad-config.json 매니페스트가 추가됩니다. 프로젝트 파일과 메모리 파일은 그대로 유지됩니다.

NanoClaw 그룹에 멤버가 10명 이상 있었습니다. Squad가 지원하나요?¶

네. Backend.AI GO Squad는 Squad당 최대 20명의 에이전트를 지원합니다. 팀이 매우 큰 경우, Squad를 기본 Squad와 채널 라우팅으로 트리거되는 보조 Squad로 나누는 것을 고려하세요.

NanoClaw의 CLAUDE.md 계층 구조는 어떻게 처리하나요?¶

• 그룹 수준 CLAUDE.md → 에이전트 시스템 프롬프트 (Squad 편집기에서 에이전트별로)
• 하위 디렉터리의 프로젝트 수준 CLAUDE.md 파일 → 폴더 지침 (Cowork 설정에서)

에이전트가 실행 중에 CLAUDE.md 파일을 동적으로 발견해야 한다면, 시스템 프롬프트에 다음과 같은 메모를 추가합니다: "방문하는 디렉터리에서 CLAUDE.md 파일을 찾아 해당 지침을 따르세요."

작성한 NanoClaw stdio IPC 도구는 어떻게 되나요?¶

Stdio 기반 IPC 도구는 Backend.AI GO의 파일 기반 IPC와 호환되지 않습니다. IPC 디렉터리(workspace/ipc/)에서 JSON 파일을 쓰고 읽도록 도구를 업데이트해야 합니다. 파일 형식은 컨테이너 실행 가이드에 문서화되어 있습니다.

NanoClaw 설정을 자동으로 변환하는 가져오기 도구가 있나요?¶

현재 자동화된 가져오기 도구는 없습니다. 이 가이드에 설명된 수동 이전은 일반적인 NanoClaw 그룹의 경우 15~30분 정도 소요됩니다.

Backend.AI GO와 NanoClaw를 동시에 실행할 수 있나요?¶

네. 두 애플리케이션은 별도의 데이터 디렉터리와 별도의 컨테이너 이미지를 사용합니다. 전환 중에 두 애플리케이션을 모두 실행하여 완전히 전환하기 전에 출력을 비교할 수 있습니다.

채널 메시지가 Squad에 도달하지 않습니다. 무엇을 확인해야 하나요?¶

1. 설정 > 채널에서 채널이 연결됨으로 표시되는지 확인합니다.
2. 발신자 ID가 발신자 허용 목록에 있는지 확인합니다.
3. 채널이 Squad 매핑에서 올바른 Squad에 매핑되어 있는지 확인합니다.
4. 설정 > 채널 > [채널 이름] > 로그에서 채널 로그를 검토합니다.

NanoClaw의 --headless 모드에 해당하는 것은 무엇인가요?¶

Backend.AI GO의 헤드리스 모드를 사용합니다. --headless 플래그로 앱을 시작하거나 설정 > 고급 > 헤드리스 모드에서 활성화합니다. Management API는 NanoClaw의 헤드리스 API에 상응하는 REST 엔드포인트를 제공합니다. 헤드리스 모드 가이드를 참조하세요.

도움을 받으려면 어떻게 해야 하나요?¶

• 앱 내: 설정 > 도움말을 열어 문서 및 커뮤니티 포럼 링크를 확인합니다.
• 문서: go.backend.ai/ko/manual/
• 커뮤니티: GitHub의 Backend.AI GO 토론