2026-05-13 OpenClaw 멀티 에이전트 agents.json 역할 분리와 헤드리스 임대 Apple Silicon 클라우드 Mac(HK / JP / KR / SG / US)
단일 게이트웨이·단일 인격·단일 실수 삭제 스토리——OpenClaw를 명시적인 멀티 에이전트 구성으로 나누기 전까지 이어진다. 홍콩·도쿄·서울·싱가포르·미국에서 임대한 Mac mini M4에는 동일 UID에 xcodebuild 레인, 서명 트리, Slack 응답 어시스턴트가 자주 공존한다. 본문은 agents.json을 운영 계약으로 취급한다: 어떤 루트에 손댈 수 있는지, 어떤 OPENCLAW_STATE_DIR가 checkpoint를 소유하는지, 인바운드를 어떻게 단일 에이전트 정체성에 매핑하는지.워크스페이스 허용 목록, 세션 checkpoint와 게이트웨이 재시작, onboard·doctor 트리아지를 연결해 launchd 재시작 후에도 durable 상태가 섞이지 않는 개발 vs 운영 분리를 재현 가능하게 한다.
공유 임대 빌더에서 멀티 에이전트 설계가 중요한 이유
저장소를 읽을 수 있는 어시스턴트와 데몬 재시작·토큰 로테이션을 맡는 자동화는 위험 등급이 다르다. 동일 상태 디렉터리를 공유하면 중복 제거 캐시, 플러그인 매니페스트, 반쯤 쓴 JSON이 버스트 Webhook 아래에서 뒤섞인다——특히 npm 업그레이드나 launchctl kickstart 폭풍 이후에 드러난다. 설계의 중심은 폭발 반경: 역할마다 도구 표면을 좁히고 로그 접두사를 나누며 범위 확장에는 사람의 리뷰를 필수로 한다. agents.json은 인프라 코드로 취급하고 동료 검토, 배포 tarball 체크섬, 리전별 카나리아를 지킨다.
agents.json과 게이트웨이 프로세스 모델의 층
전송(HTTP, Slack, Telegram), 게이트웨이(라우팅·인증·속도 제한), 에이전트 런타임(도구 실행·모델 호출·파일 시스템 정책)의 세 층으로 본다. agents.json은 런타임에 속하며 명명된 에이전트, 기본 모델, 스킬 번들, 정책 필드를 선언한다. 게이트웨이는 기동 시 읽으므로 통제된 재시작 없이 핫 변경하면 메모리에 절반은 옛 정책이 남는다. 빌드마다 핫 리로드 가능 필드를 문서화하고 불가하면 checkpoint 가이드에 맞는 중지 순서를 따른다.
- 정체성 — 라우팅과 메트릭이 참조하는 안정적인
id. - 범위 — 모노레포 가드레일 허용 루트와 일치.
- 도구 — 명시적 allow/deny. 운영 페르소나만 서비스 제어 도구를 갖는 패턴이 일반적이다.
개발과 운영: 서로 물려받아서는 안 되는 권한
개발 어시스턴트는 읽기 위주 탐색, diff 친화적 소규모 편집, CI 체크아웃 아래로 묶인 테스트 명령에 초점을 맞춘다. 운영 자동화는 호스트 인트로스펙션을 넓혀도 되지만 대화형 프롬프트와 무제한 셸은 피한다. 인라인 프롬프트에 비밀을 박지 말고 키체인이나 plist가 가리키는 밀봉 env 파일에서 읽는다. 경계를 “일시적으로” 흐리면 어시스턴트 스레드가 운영 도구를 물려 launchd plist에 닿는 사고가 난다.
한 대에 여러 에이전트일 때 OPENCLAW_STATE_DIR 분리
~/Library/Application Support/OpenClaw/state-dev와 .../state-ops처럼 형제 트리를 접두사로 나눈다. 제품 라인을 공유하면 테넌트별 하위 디렉터리를 추가한다. 한 상태 트리를 다른 쪽으로 symlink 하지 않는다. APFS firmlink와 백업이 경계를 지울 수 있다. 에이전트별 TMPDIR로 병렬 잡의 중간 업로드 삭제 경쟁을 피한다. 이동 후에는 doctor 절차로 비대화형 셸이 의도한 경로를 해석하는지 검증한다.
# launchd 래퍼 예
#!/bin/bash
set -euo pipefail
export OPENCLAW_STATE_DIR="$HOME/.openclaw-state/ops"
exec /usr/local/bin/openclaw gateway --config "$HOME/.openclaw/ops-gateway.json"
라우팅: 상관 키, 채널, 충돌 회피
Webhook에는 안정적인 식별자를 실는다——저장소 full name + delivery id, Slack team + channel + thread ts, 서명된 내부 작업 토큰 등. 패턴마다 단일 id로 사상하고 정규식 폴스루로 운영 트래픽을 기본 어시스턴트에 잘못 보내지 않는다. 듀얼 게이트웨이에서는 업스트림 라벨 아이디어를 재사용할 수 있으나 페르소나 라우팅은 A/B 트래픽 분할과 직교시킨다. 롤아웃 초기에는 info로 라우팅 결정을 로깅하고 오류 예산이 안정되면 레벨을 내린다.
의사결정 매트릭스: 단일 에이전트 / agents.json 분할 / 게이트웨이 분할
| 신호 | 단일 에이전트 쪽 | agents.json 분할 쪽 | 게이트웨이 프로세스 분할 쪽 |
|---|---|---|---|
| 도구면 중첩 | 높은 중첩·동일 위험군 | 낮은 중첩·동일 게이트웨이 인증 | 인증 도메인 또는 TLS 인증서가 다름 |
| 릴리스 케이던스 | 주간 프롬프트 조정만 | JSON을 팀이 분리 소유 | 독립 SLO 또는 유지보수 창 |
| 상태 디렉터리 경합 | 쓰기 적음·캐시 작음 | checkpoint나 플러그인 IO가 무거움 | 컴플라이언스 감사에서 단단한 격리 필요 |
| 운영 비용 | 최소 부품 수 | 중간: 디렉터리와 라우트 검증 증가 | 최대: launchd와 헬스 프로브 두 배 |
임대 Apple Silicon에서 멀티 에이전트 OpenClaw를 펼치는 8단계
- 지난 30일간 게이트웨이에 닿은 사람·자동 진입점을 조사한다.
- 개발·운영 프로필을 담은
agents.json을 작성하고 루트는 허용 목록 지침에 맞춘다. - 형제
OPENCLAW_STATE_DIR를 소유권과 쿼터로 만든다. - 결정적 규칙과 샘플 페이로드 단위 테스트를 작성한다.
- 페르소나별 plist나 래퍼를 배포하고 스테이징에서
launchctl kickstart를 검증한다. - 잘못 라우팅되면 반드시 실패하는 합성 잡을 돌린다.
- 거부된 도구 시도와 게이트웨이 p95를 전후 비교한다.
- 롤백을 문서화: 상태 tarball과 Git 태그가 붙은 이전 JSON.
멀티 에이전트 게이트웨이 SLO 신호
| 신호 | 임계값 | 조치 |
|---|---|---|
| 라우팅 모호 비율 | 요청의 > 0.1% | 라우팅 변경 동결 후 명시 매처 추가 |
| 상태 디렉터리 교차 쓰기 | 선언 루트 밖 쓰기가 하나라도 | 게이트웨이 중지 후 checkpoint 스냅샷에서 복구 |
| Git JSON과 호스트 드리프트 | 배포되지 않은 수동 편집이 있으면 | 호스트 롤백 후 PR만 허용 |
FAQ
| 질문 | 실무 답(2026-05-13) |
|---|---|
| 개발과 운영이 동일 모델 허용 목록을 공유해도 되나요? | 비용을 한곳에서 관리하면 공급자 목록은 공유하기 쉽다. 운영에 저렴하거나 오프라인 엔드포인트가 필요하면 금지 모델 목록을 나눈다. |
사고 중 SSH로 agents.json을 핫편집해도 되나요? |
짝을 이룬 재시작 계획과 Git 태그가 있을 때만. 그렇지 않으면 라우터 쪽 플래그가 폭발 반경이 더 작다. |
멀티 에이전트 OpenClaw에 Mac mini M4 임대가 맞는 이유
빠른 NVMe와 넉넉한 unified memory로 여러 상태 트리, 병렬 모델 캐시, 동시 헬스 체크를 스왑 압박 없이 돌릴 수 있다——라우팅 변경 리허설 중에도 CI가 풀 빌드 중이어도 버틴다. 지역 용량은 요금으로 비교하고 도구 확장 전에 SSH/VNC 가이드로 안내한다.
