Agentlas 설치·사용법: Claude Code·Codex 멀티 에이전트 가이드

조사하고, 글을 쓰고, 마지막으로 “틀린 내용 없는지 검토해 줘”라고 요청해 본 적 있으신가요? 결과는 매끄러운데 출처를 열어 보면 가격이 옛날 정보이거나, 예시 명령이 현재 버전과 맞지 않을 때가 있습니다.

이럴 때 바꿔 볼 것은 AI에게 맡기는 일의 구조입니다. 조사 담당이 근거를 남기고, 작성 담당이 그 근거로 글을 만들고, 검증 담당이 원문과 결과를 다시 대조하도록 만드는 것이죠.

Agentlas OS는 기존 AI 도구에 연결해 전문 에이전트를 만들고, 작업에 배치하고, 결과를 검증하는 오픈소스 엔진입니다. 새로운 모델 자체를 제공하는 서비스는 아닙니다. 모델과 실행 환경은 별도로 연결합니다.

Agentlas란? OS·Desktop·Hub·Cloud 차이부터 보기

Agentlas를 이해하려면 네 이름을 구분하면 됩니다.

엔진 이름으로 Hephaestus도 등장합니다. 설치나 진단 명령에서 이 이름을 만나도 다른 제품을 잘못 설치한 것은 아닙니다. Desktop이 없어도 독립 Terminal에서 작업할 수 있으며, Web의 Cloud가 사용자 대신 모델 추론을 실행하는 구조는 아닙니다.

현재 최신 버전은? Agentlas OS v1.2.71 기준

2026년 10월 31일 확인한 최신 Agentlas OS 릴리스는 v1.2.71입니다. 한국 시간 10월 30일 공개됐으며, 프로젝트 경로가 포함된 기억을 다른 프로젝트에서 재사용하지 않도록 분류하는 메모리 개선이 안내됐습니다. Desktop과 OS는 릴리스 버전이 별도이므로 같은 번호로 비교하면 안 됩니다.

공식 문서에도 갱신 시차가 있습니다. 이 글의 설치 명령은 v1.2.71 README를 기준으로 제시합니다. 이후 버전은 참고 출처의 최신 릴리스 목록에서 확인할 수 있습니다.

왜 역할을 나눠야 할까요?

조사·작성·검증의 입력과 완료 기준을 분리하면, 무엇을 근거로 어떤 결과를 만들었는지 확인하기 쉬워집니다. 다만 역할을 나눴다는 사실만으로 오류가 사라지지는 않습니다.

예를 들어 AI 도구 소개 글을 만든다고 해 보겠습니다.

• 조사 담당: 현재 설치 명령과 요금 정책을 공식 출처에서 확인합니다.
• 작성 담당: 확인된 사실을 독자의 문제와 연결해 설명합니다.
• 검증 담당: 글의 명령·가격·지원 범위를 원문과 대조합니다.

조사 결과가 “무료”라는 한 단어로만 전달되면 작성 담당은 “모든 기능을 무료로 쓴다”고 확대 해석할 수 있습니다. 반대로 “공개 패키지 호출료 없음, 모델 사용료 별도”라고 전달하면 글의 경계가 분명해집니다. 팀 구성보다 먼저 설계할 것은 인수인계할 자료입니다.

한 대화창의 자기 검토도 도움이 됩니다. “같은 AI의 자기 검토는 반드시 실패한다”는 주장은 이 글에서 확인한 공식 자료로 입증되지 않았습니다. 여기서 권하는 방식은 작성자의 설명을 그대로 믿는 대신, 검증 담당에게 원문과 확인 기준을 따로 주는 것입니다.

어떤 작업에 적합할까요?

다음은 도구의 성능 보장이 아니라, 역할을 나누기 좋은 작업을 고르는 실무 기준입니다.

에이전트를 많이 부르는 것부터 시작하지 마세요. 작은 작업 하나에서 품질과 소요 시간, 모델 사용량을 비교하는 편이 도입 판단에 도움이 됩니다.

Agentlas는 어떻게 전문가 팀을 구성하나요?

Network에 목표와 범위를 전달하면, 호스트의 AI가 실제 후보를 검토하고 작업에 필요한 구성을 준비합니다. Local은 현재 기기에 등록된 에이전트, Cloud는 내 비공개 패키지, Hub는 공개 전문가와 팀입니다. 검색 범위를 제한할 수 있습니다.

공식 README는 후보를 인기순으로 세우지 않으며, 선택 이유를 기록한다고 설명합니다. 계획·작업·종합·검증은 별도 호출로 진행되고, 완료 판단 전에 독립 검증을 요구하는 구조를 제시합니다. 여기서 독립은 작업·검증 호출을 분리하는 구조에 관한 설명입니다. 서로 다른 회사나 모델이 반드시 검증한다는 뜻은 아니며, 모든 작업에서 정확도가 높아진다는 독립 성능 측정 결과도 아닙니다.

또한 Hub에서 가져오는 것은 실행 가능한 패키지와 지침입니다. 연결한 호스트가 자신의 모델·파일·권한으로 실행합니다. 이미 내부 관리 구조가 있는 팀은 그 구조를 유지하고, 개별 에이전트를 직접 배치하는 경우도 있습니다. “항상 정해진 수의 에이전트를 동시에 실행한다”고 이해하면 맞지 않습니다.

인기순을 사용하지 않는다는 설명과 작업 적합도를 판단하지 않는다는 말은 다릅니다. 공식 오케스트레이션 문서는 검색어·의미 기반 매칭과 호스트 AI의 판단도 설명합니다. 따라서 “어떤 점수나 자동 판단도 전혀 없다”고 확대 해석하지 마세요.

‘검증 통과’는 어디까지 믿을 수 있나요?

통과한 검사가 다룬 범위까지 확인됐다는 뜻입니다. 공식 Stormbreaker 문서는 결과를 다음처럼 구분합니다.

예를 들어 “Markdown 파일을 생성했다”는 검사를 통과해도 “본문의 모든 가격이 최신이다”까지 증명되지는 않습니다. 처음부터 사실 검증을 완료 기준에 넣어야 합니다.

Agentlas는 무료인가요? 모델 비용은 별도입니다

공개 Hub 패키지 호출은 무료지만, 실행에 쓰는 모델과 외부 도구의 비용은 따로 볼 필요가 있습니다. 최신 공식 안내는 공개 에이전트 게시·호출에 에이전트 가격이나 대여료, Agentlas 크레딧 구매가 필요 없다고 명시합니다.

요금 페이지는 로컬 에이전트 호출에 Agentlas 호출료가 없다고 설명하는 한편, 비공개 Cloud 용량과 Alive Agent 같은 기능을 포함한 유료 요금제도 안내합니다. 따라서 “Agentlas 전체가 무조건 무료”나 “Claude 사용량만 있으면 모든 연결 도구를 무료로 쓴다”는 표현은 피해야 합니다.

예전 소개에서 본 “팀 호출 10크레딧”을 현재 공개 Hub 정책으로 그대로 적용하면 안 됩니다. 설치·실행 직전에는 공식 요금 안내를 다시 확인하세요.

Agentlas 설치 전 무엇을 확인해야 하나요?

통합 설치기는 현재 열어 둔 도구 하나만 설정하지 않습니다. 컴퓨터에서 감지한 지원 호스트에 연결 설정을 추가하므로, 설치 전 변경 범위를 살펴보는 것이 좋습니다.

공식 README는 런타임을 ~/.agentlas/, 실행용 래퍼를 ~/.local/bin/에 두고, Claude Code·Codex·Cursor 등의 설정에 연결 항목을 등록한다고 설명합니다. 기존 설정 파일도 수정될 수 있습니다. 일반 설정 전체에 자동 백업이 생긴다고 가정하면 안 됩니다.

다음 순서로 준비하세요.

1. 사용 중인 AI 도구의 설정 파일을 별도로 백업합니다.
2. 첫 작업은 중요한 프로젝트 대신 테스트 폴더에서 진행합니다.
3. Git 프로젝트라면 작업 전 상태를 확인하고 필요한 변경을 저장합니다.
4. 설치 보고서와 진단 결과를 읽은 뒤 작은 작업 하나를 실행합니다.

Git 상태를 확인하는 명령입니다. 설치 전후 모두 실행하면 추적 중인 변경과 새 파일을 살펴볼 수 있습니다.

git status --short
git diff --stat
git diff -- .gitignore

git diff에는 추적되지 않은 새 파일의 내용이 나오지 않습니다. git status --short에 표시되는 새 파일도 함께 확인하세요. 또한 이 명령들은 현재 프로젝트 상태를 확인합니다. 홈 폴더의 도구 설정 백업을 대신하지 않습니다.

프로젝트 안의 변경은 실행 환경과 작업에 따라 달라질 수 있습니다. 특정 파일이 항상 생긴다고 가정하기보다 첫 실행 전후 상태를 직접 비교하세요.

Agentlas 설치 방법: Claude Code·Codex 진입점 구분하기

1. macOS·Linux: 스크립트를 내려받아 확인하기

공식 설치 문서는 스크립트를 먼저 다운로드하고 내용을 확인한 뒤 실행하는 방법을 안내합니다. 아래 첫 명령은 다운로드만 합니다. 편집기로 파일을 열어 변경 범위를 읽어 보세요.

curl -fsSL https://raw.githubusercontent.com/agentlas-ai/Agentlas-OS/main/scripts/install-all-runtimes.sh -o agentlas-os-install.sh

검토 후 설치를 진행할 때 실행합니다.

bash agentlas-os-install.sh

공식 설치 스크립트에는 릴리스 아카이브의 SHA-256을 확인하는 절차가 있습니다. 따라서 현재 버전을 두고 “체크섬 검증이 전혀 없다”고 쓰면 부정확합니다. 다만 체크섬 확인이 설정 변경의 적절성까지 판단해 주지는 않습니다.

Windows에서 이 Bash 명령을 쓰려면 공식 문서가 안내하는 Git Bash 환경을 사용하세요. PowerShell에 Bash 명령을 그대로 넣는 방식은 아닙니다. 창 기반 작업을 원하면 공식 Desktop 설치 경로를 선택할 수도 있습니다.

2. Claude Code 플러그인 경로 선택하기

공식 문서의 Claude Code 플러그인 설치 예시입니다. 운영체제 터미널에서 실행합니다.

claude plugin marketplace add https://github.com/agentlas-ai/Agentlas-OS --sparse .claude-plugin claude/plugins
claude plugin install hephaestus@agentlas-core-engine

v1.2.71 README는 플러그인만 설치한 경우 /hephaestus:agentlas 진입점을 안내합니다. 통합 설치기의 /hep-network 같은 단축 명령과 구분하세요. 설치 후 실제 명령 목록을 확인하고, 플러그인 진입점에서 Network 작업을 요청하면 됩니다.

3. Codex 플러그인 설치하기

공식 v1.2.71 README의 Codex 설치 명령입니다. Codex 대화창이 아니라 운영체제 터미널에서 실행하세요.

codex plugin marketplace add agentlas-ai/Agentlas-OS --ref v1.2.71
codex plugin add hephaestus@agentlas-core-engine

설치 후 스킬 목록에서 $hephaestus-network를 선택해 요청합니다. 목록에 없다면 플러그인 목록을 새로 고치거나 클라이언트를 다시 불러오세요. 이미 이전 버전이 설치됐다면 기존 등록 정보와 버전도 확인하세요.

4. 설치 상태를 진단하고 호스트별 명령 확인하기

통합 설치 후 호스트를 다시 시작하고 진단합니다.

hephaestus doctor

독립 Terminal의 agentlas doctor와 구분하세요. 같은 이름으로 모든 실행 환경을 진단한다고 가정하지 않는 것이 좋습니다.

아래 실습 프롬프트는 해당 진입점을 선택한 뒤 전달하는 요청 본문입니다. 모든 환경에서 슬래시 명령을 똑같이 입력하는 예제가 아닙니다.

전역 지침 변경 범위와 백업 방식은 참고 출처의 공식 README에 정리돼 있습니다.

실전 예제 1: 조사·작성·검증을 나눠 블로그 초안 만들기

첫 실습은 공개 발행 없이 파일로 확인할 수 있는 결과를 만드는 것이 좋습니다. 공식 첫 작업 가이드도 작은 일과 열어 볼 수 있는 산출물부터 검증하도록 안내합니다.

아래는 특정 Hub 팀의 실재나 이름에 의존하지 않는 요청입니다. 주제만 바꿔 복사하세요.

목표: [주제]를 처음 접하는 독자를 위한 한국어 블로그 초안을 만들어 줘.

입력: 내가 첨부한 brief.md와 그 안의 공식 문서 URL. 부족하면 먼저 알려 줘.
출력 위치: 현재 프로젝트의 outputs/agentlas-blog/ 폴더.

먼저 설치된 Agentlas Network 기능과 사용 가능한 모델·도구를 확인해 줘.
가능한 전문가 후보를 실제로 조회한 뒤 다음 업무를 배치해 줘.
에이전트 이름을 지어내거나, 실행하지 않은 역할을 실행했다고 보고하지 마.

업무와 인수인계:
1. 조사: 최신 공식 문서에서 사실·출처 URL·확인 날짜·제약을 정리한다.
2. 작성: 조사 자료를 바탕으로 정의, 필요한 이유, 사용 예시를 설명한다.
3. 검증: 본문 주장을 원문과 대조하고 오류·과장·근거 부족을 기록한다.

범위:
- 최초 탐색은 Local로 제한한다.
- 내 비공개 Cloud는 로그인과 접근 가능 여부를 확인한 뒤 포함한다.
- 공개 Hub가 필요하면 사용할 패키지와 필요한 권한을 먼저 보여 준다.
- 외부 발행, 메시지 전송, 유료 결제는 하지 않는다.

산출물:
- research.md: 주장별 근거표
- draft.md: 블로그 초안
- review.md: 주장별 통과·수정 필요·확인 불가 판정

완료 기준:
- 설치·가격·지원 환경 설명에는 직접 뒷받침하는 공식 링크가 있다.
- 실제 실행하지 않은 예제는 문서 기반 예제라고 표시한다.
- 검증 담당은 작성 담당의 요약만 읽지 말고 원문도 확인한다.
- 검증 중 오류를 발견하면 수정본을 만들고 해당 항목을 다시 확인한다.
- 결과 파일 경로와 남은 검증 항목을 보고한다.
- 도구나 권한 부족으로 실행할 수 없는 단계는 정확히 구분한다.

이 프롬프트의 핵심은 “전문가처럼 해 줘”라는 표현이 아닙니다. 누가 무엇을 넘기고, 어떤 기준으로 통과시키는지를 적었다는 점입니다.

근거표는 이런 모양이면 좋습니다

아래는 독자가 결과를 검토하기 위한 작성 양식입니다. Agentlas가 요구하는 설정 파일 형식은 아닙니다.

{
  "claim": "검증할 문장",
  "source_url": "공식 원문 URL",
  "checked_at": "YYYY-MM-DD",
  "scope": "적용 버전 또는 요금제",
  "verdict": "수정 필요",
  "reason": "문장이 원문의 적용 범위보다 넓음"
}

검증 결과가 “전체적으로 좋습니다” 한 줄이라면 다음처럼 다시 요청하세요.

글에서 설치, 가격, 지원 환경, 성능을 설명하는 문장을 모두 추출해 줘.
각 문장마다 원문 URL, 원문이 실제로 뒷받침하는 범위,
통과·수정 필요·확인 불가 판정을 표로 작성해 줘.
접근하지 못한 출처를 읽었다고 보고하지 말고,
수정이 필요하면 대체 문장도 제안해 줘.

실전 예제 2: 블로그를 인스타그램 카드뉴스로 바꾸기

콘텐츠 재가공은 원문에서 주장과 근거를 유지한 채 형식을 바꾸는 작업으로 시작하면 좋습니다. 아래 예제는 특정 “인스타 마케팅 팀”의 현재 제공 기능을 보장하는 설명이 아닙니다. 독자가 직접 사용할 수 있도록 설계한 업무 요청입니다.

첨부한 draft.md를 인스타그램 카드뉴스 7장으로 재구성해 줘.
원문이 첨부되지 않았다면 진행 전에 알려 줘.
출력 위치는 현재 프로젝트의 outputs/instagram/ 폴더로 한다.
최초 후보 탐색은 Local로 제한하고, Cloud·Hub 확대가 필요하면 먼저 알려 줘.

Agentlas Network로 기획, 카피, 이미지 브리프, 검증 업무를 배치해 줘.
실제로 사용 가능한 후보와 도구를 확인한 뒤 진행해 줘.

카드 구성:
1장: 독자가 겪는 문제
2장: 도구의 한 문장 정의
3장: 필요한 이유
4장: 작동 방식
5장: 바로 해 볼 예시
6장: 비용과 설치 전 확인 사항
7장: 오늘 실행할 한 가지

규칙:
- 원문에 없는 기능과 성능 수치를 추가하지 않는다.
- AI 제품·모델·회사 이름은 공식 영어 표기로 쓴다.
- 무료 범위와 모델 사용료를 구분한다.
- 이미지 생성 도구가 없으면 이미지 브리프까지만 만든다.
- 이미지가 만들어지지 않았는데 생성 완료라고 보고하지 않는다.
- 계정 로그인, 예약, 업로드, 공개 게시는 진행하지 않는다.

산출물:
cards.md, image-briefs.md, caption.md, review.md
각 카드의 주장에 대응하는 원문 위치와 출처를 함께 남긴다.

제작 단계에서 이미지 도구나 브라우저 권한이 없으면 그 단계가 막힐 수 있습니다. “팀을 준비했다”와 “이미지 파일이 생성됐다”, “게시가 끝났다”는 서로 다른 상태입니다. 공식 가이드 역시 외부 작업은 답변뿐 아니라 실제 목적지에서도 확인하라고 안내합니다.

막혔을 때 무엇부터 확인하나요?

설치 → 모델 연결 → 도구 권한 → 산출물 → 검증 결과 순서로 좁혀 보세요. “연결됨” 표시와 실제 작업 완료는 구분해야 합니다.

Cloud 접근 실패를 공개 Hub 사용 허가로 해석하면 안 됩니다. 또한 같은 작업의 후속 요청은 기존에 준비한 구성을 재사용할 수 있지만, 구성이 보존된다는 것이 에이전트가 계속 실행 중이라는 뜻은 아닙니다.

자주 묻는 질문

처음에는 ‘작은 결과 하나와 근거표’부터 만드세요

Agentlas를 써 보고 싶다면 가장 자주 하는 작업 하나를 고르세요. 그다음 입력, 역할별 산출물, 통과 기준을 세 줄로 적어 보세요. 예를 들어 “공식 문서 3개를 읽고, 설명 초안과 주장별 근거표를 만들고, 설치·비용 문장을 원문과 대조한다”로 시작할 수 있습니다.

에이전트가 몇 명인지보다 중요한 것은 결과를 열어 보고 판단할 수 있느냐입니다. 첫 실행에서 초안과 근거표, 확인되지 않은 항목을 함께 받았다면 다음 작업을 맡길 기준도 생깁니다.

역할과 작업 흐름을 더 정리하고 싶다면 스킬·워크플로우·에이전트 차이를, 멀티 에이전트 도구를 더 살펴보고 싶다면 Ruflo 설치·사용법을 함께 읽어 보세요.