OpenClaw 멀티에이전트 트러블슈팅을 중심으로 시리즈 마지막 편입니다. 여기까지 오셨다면 에이전트에게 성격도 주고, 기억력도 설계하고, 모델도 최적화한 상태입니다. 이제 한 단계 더 — 에이전트를 여러 개 운영하는 법과, 무언가 고장났을 때 침착하게 복구하는 법을 다루겠습니다.
Part 1: 멀티 에이전트 — 왜 하나로는 부족한가?
하나의 에이전트로 모든 걸 시키면?
처음에는 메인 에이전트 하나로 충분합니다. 그런데 쓰다 보면 이런 상황이 생깁니다:
- 블로그 글 13개 SEO 보강하라고 했는데 1시간 넘게 걸림 → 그동안 다른 질문을 못 함
- 트레이딩 봇 3시간마다 보고하라고 했는데, 메인 에이전트가 계속 바쁨
- 미팅 녹음 정리를 시켰는데 비싼 Claude로 돌아감
이럴 때 전문 에이전트를 따로 두면 됩니다.
멀티 에이전트 구조 예시
┌──────────────┐
│ Chloe │ ← 메인 에이전트 (Claude Opus)
│ (main) │ 나와 직접 대화, 판단, 지시
└──────┬───────┘
│
┌────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌─────┐ ┌──────┐ ┌──────────┐
│KING │ │ MAX │ │ MEET │
│트레 │ │분석/ │ │미팅 기록 │
│이딩 │ │전략 │ │정리 │
│봇 │ │ │ │ │
│Codex│ │GPT5.4│ │Ollama │
│ │ │ │ │(무료) │
└─────┘ └──────┘ └──────────┘각 에이전트가 자기 역할에 최적화된 모델을 쓰고, 독립적으로 작동합니다.
[스크린샷: 멀티 에이전트 아키텍처 다이어그램]
에이전트 추가하기
openclaw.json에서 설정
{
"agents": {
"list": [
{
"id": "main",
"model": "anthropic/claude-opus-4-6",
"tools": {
"profile": "full",
"alsoAllow": ["browser", "message", "gateway", "tts"]
}
},
{
"id": "king",
"name": "KING",
"workspace": "/path/to/king/workspace",
"agentDir": "/path/to/king/agent",
"model": "openai-codex/gpt-5.3-codex"
},
{
"id": "meet",
"name": "MEET",
"workspace": "/path/to/meet/workspace",
"agentDir": "/path/to/meet/agent",
"model": "ollama/qwen35b-meeting",
"tools": {
"profile": "minimal",
"alsoAllow": ["message"]
}
}
]
}
}각 항목 설명:
id— 에이전트 고유 식별자name— 표시 이름workspace— 에이전트 전용 작업 폴더agentDir— 에이전트 설정 파일 위치model— 사용할 AI 모델tools.profile— 도구 권한 수준 (full,coding,minimal)
에이전트별 텔레그램 봇 연결
각 에이전트를 별도의 텔레그램 봇에 연결할 수 있습니다.
Step 1: BotFather에서 새 봇 생성
- 텔레그램에서 @BotFather 검색
/newbot입력- 봇 이름과 아이디 설정
- 토큰 복사
Step 2: openclaw.json에 계정 추가
{
"channels": {
"telegram": {
"accounts": {
"default": {
"botToken": "메인봇_토큰",
"allowFrom": ["내_텔레그램_ID"]
},
"king": {
"botToken": "KING봇_토큰",
"allowFrom": ["내_텔레그램_ID"]
}
}
}
}
}Step 3: 바인딩으로 연결
어떤 텔레그램 봇으로 온 메시지를 어떤 에이전트가 처리할지 매핑합니다.
{
"bindings": [
{
"agentId": "main",
"match": {"channel": "telegram", "accountId": "default"}
},
{
"agentId": "king",
"match": {"channel": "telegram", "accountId": "king"}
}
]
}이제 메인 봇에 말하면 Chloe가, KING 봇에 말하면 KING이 응답합니다.
[스크린샷: 텔레그램에서 두 개의 봇과 대화하는 화면]
서브에이전트 — 무거운 작업 위임하기
메인 에이전트가 직접 하기엔 오래 걸리는 작업은 서브에이전트로 위임할 수 있습니다.
예시: 메인 에이전트에게 이렇게 말하면:
"블로그 13개 글 SEO 보강해줘"
메인 에이전트가 서브에이전트를 생성하고, 백그라운드에서 처리시킨 뒤, 완료되면 결과를 보고합니다. 그동안 나는 메인 에이전트와 다른 대화를 할 수 있습니다.
{
"agents": {
"defaults": {
"subagents": {
"maxConcurrent": 8
}
}
}
}maxConcurrent로 동시에 돌릴 수 있는 서브에이전트 수를 제한합니다.
크론(Cron) — 정기 작업 자동화
에이전트에게 정기적으로 작업을 시킬 수 있습니다.
예시: 3시간마다 트레이딩 손익 보고
/cron add
이름: KING 3시간 손익 보고
스케줄: 매 3시간
작업: 손익 현황을 확인해서 텔레그램으로 보고해줘예시: 매일 아침 뉴스 요약
텔레그램에서 에이전트에게:
"매일 아침 8시에 AI 관련 뉴스 3개 요약해서 보내줘"
에이전트가 알아서 크론을 설정합니다.
크론 관리
# 크론 목록 보기
openclaw cron list
# 크론 비활성화
openclaw cron disable [job-id]
# 크론 삭제
openclaw cron remove [job-id][스크린샷: 크론 목록과 실행 이력]
Part 2: 트러블슈팅 — 고장났을 때 살아남기
OpenClaw를 쓰다 보면 반드시(!) 한 번은 뭔가 고장납니다. 당황하지 마세요. 대부분 10분 안에 고칠 수 있습니다.
🚨 사고 #1: JSON 깨먹었을 때 (가장 흔함!)
openclaw.json을 수동으로 편집하다가 쉼표를 빼먹거나, 괄호를 잘못 닫으면… 게이트웨이가 시작을 거부합니다.
증상:
- 텔레그램 봇이 응답 안 함
openclaw gateway start하면 에러- "Invalid JSON" 또는 "Unexpected token" 에러
복구 방법 1: 백업에서 복원
# 최근 백업 찾기
ls -la ~/.openclaw/backups/
# 백업에서 복원
cp ~/.openclaw/backups/openclaw.json.bak ~/.openclaw/openclaw.json
# 게이트웨이 재시작
openclaw gateway restart💡 꿀팁: 백업 습관을 들이세요!
# 설정 수정 전에 항상 이것부터
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d)복구 방법 2: Claude Code로 고치기
터미널에서 Claude Code를 직접 호출할 수 있습니다:
npx claude --print "~/.openclaw/openclaw.json 파일이 깨진 것 같아.
JSON 문법 오류를 찾아서 고쳐줘. 현재 내용을 읽고 수정본을 보여줘."Claude Code가 파일을 읽고, JSON 오류를 찾아서 수정해줍니다.
복구 방법 3: Codex로 고치기
codex "openclaw.json 파일에 JSON 문법 오류가 있어. 파일을 확인하고 고쳐줘."Codex도 마찬가지로 파일을 분석하고 수정합니다. Codex는 PTY가 필요하니 일반 터미널에서 실행하세요.
복구 방법 4: 수동으로 JSON 검증
# JSON 문법 검증
cat ~/.openclaw/openclaw.json | python3 -m json.tool
# 에러 위치가 나옵니다:
# "Expecting ',' delimiter: line 42 column 5"
# → 42번째 줄 근처에서 쉼표가 빠졌다는 뜻그래도 못 찾겠으면 jsonlint.com에 붙여넣기 하면 오류 위치를 정확히 잡아줍니다.
[스크린샷: JSON 에러 메시지와 수정 전후 비교]
🚨 사고 #2: 텔레그램 봇이 응답 안 할 때
체크리스트:
1️⃣ 게이트웨이가 살아있나?
openclaw gateway status
# "running"이 아니면:
openclaw gateway start2️⃣ 텔레그램 플러그인 상태 확인
openclaw status
# Channels 섹션에서 Telegram이 "OK"인지 확인3️⃣ 봇 토큰이 유효한가?
- BotFather에서 봇을 삭제하고 재생성하지 않았는지 확인
- openclaw.json에서 botToken 확인
4️⃣ allowFrom에 내 ID가 있나?
{
"channels": {
"telegram": {
"allowFrom": ["내_텔레그램_ID"]
}
}
}텔레그램 ID 모르겠으면: @userinfobot 에게 메시지 보내면 알려줍니다.
5️⃣ 그래도 안 되면 게이트웨이 재설치
openclaw gateway stop
openclaw gateway install
openclaw gateway start🚨 사고 #3: 에이전트가 이상하게 행동할 때
갑자기 에이전트가 엉뚱한 말을 하거나, 이전 맥락을 까먹거나, 규칙을 안 지킬 때.
원인과 해결:
| 증상 | 원인 | 해결 |
|---|---|---|
| 맥락을 까먹음 | 컴팩션이 일어남 | 컴팩션 설정 조정 또는 /reset |
| 규칙을 안 지킴 | SOUL.md/AGENTS.md 미참조 | 워크스페이스 파일 확인 |
| 엉뚱한 응답 | 세션이 꼬임 | /reset 으로 세션 초기화 |
| 느려짐 | 컨텍스트가 너무 김 | /reset 또는 새 대화 시작 |
만능 해결책: /reset
텔레그램에서 /reset을 입력하면 현재 세션을 초기화합니다. 대화 기록은 사라지지만 워크스페이스 파일(SOUL.md 등)은 그대로이니, 에이전트의 성격과 규칙은 유지됩니다.
🚨 사고 #4: "openclaw" 명령 자체가 안 될 때
openclaw status
# command not found: openclaw해결:
# Node.js 버전 확인
node --version
# v22 이상이어야 합니다
# OpenClaw 재설치
npm install -g openclaw
# 또는
pnpm install -g openclaw
# PATH 확인
which openclaw🔧 openclaw doctor — 만능 진단 도구
뭔가 이상한데 원인을 모르겠을 때:
openclaw doctor이 명령은:
- 설정 파일 무결성 검증
- 텔레그램 연결 상태 확인
- 플러그인 상태 점검
- 세션 파일 정리 (고아 파일 제거)
- 보안 설정 감사
- 수정 제안 제공
# 자동으로 고칠 수 있는 것들은 고치기
openclaw doctor --fix[스크린샷: openclaw doctor 실행 결과 화면]
🔧 로그 확인 — 문제의 단서 찾기
# 실시간 로그 보기
openclaw logs --follow
# 최근 에러만 보기
openclaw logs --follow | grep -i error로그에서 자주 보는 패턴:
| 로그 메시지 | 의미 | 대응 |
|---|---|---|
ETELEGRAM: 401 Unauthorized | 봇 토큰 만료/무효 | 토큰 재발급 |
ECONNREFUSED | 서비스 연결 실패 | 해당 서비스 상태 확인 |
context length exceeded | 대화가 너무 길어짐 | /reset |
rate limit | API 호출 한도 초과 | 잠시 대기 또는 모델 전환 |
공황 방지 가이드 — "침착하게, 터미널을 열어라"
OpenClaw가 고장났을 때 기억할 것:
Step 1: 침착
에이전트가 응답 안 해도 데이터는 안전합니다. 워크스페이스 파일은 그냥 텍스트 파일이라 날아가지 않습니다.
Step 2: 상태 확인
openclaw status
openclaw doctor이 두 명령이면 대부분의 문제 원인을 알 수 있습니다.
Step 3: 재시작
openclaw gateway restartIT의 만능 해결책, 재시작. OpenClaw도 마찬가지입니다. 80%는 이걸로 해결됩니다.
Step 4: 외부 도움 호출
재시작으로 안 되면 터미널에서 Claude Code나 Codex를 직접 호출하세요:
# Claude Code
npx claude --print "openclaw이 안 되는데,
openclaw status 결과를 확인하고 원인을 찾아줘"
# Codex
codex "openclaw 게이트웨이가 시작 안 돼.
로그를 확인하고 해결해줘"이 코딩 에이전트들은 OpenClaw 없이도 터미널에서 독립적으로 실행되니까, OpenClaw가 죽어도 쓸 수 있습니다. 응급 복구 도구로 기억해두세요.
Step 5: 커뮤니티
- OpenClaw Discord — 커뮤니티에 질문
- GitHub Issues — 버그 리포트
- 공식 문서 — 트러블슈팅 가이드
마무리 — 여정의 시작
4편에 걸쳐 OpenClaw 최적화의 핵심을 다뤘습니다:
- 영혼 — SOUL.md, AGENTS.md로 에이전트의 성격과 규칙 설계
- 기억 — 메모리 계층 구조로 맥락 있는 AI 만들기
- 효율 — 모델 배분과 스킬로 똑똑하게 사용하기
- 확장과 복구 — 멀티 에이전트 운영과 트러블슈팅
하지만 이건 시작일 뿐입니다. OpenClaw의 진짜 매력은 쓰면 쓸수록 나만의 AI가 되어간다는 점입니다.
처음엔 어색하고, 설정 파일 깨먹고, 에이전트가 엉뚱한 말 하고, 새벽에 JSON 고치면서 "내가 왜 이걸…" 하겠지만 (ㅋㅋ), 한 달만 지나면 "이 없이 어떻게 살았지?" 하게 됩니다.
나만의 AI, 함께 만들어가는 여정을 즐기시길 바랍니다. 🦞
시리즈 전체 목록:
- 내 AI에게 영혼을 불어넣자 — 에이전트 성격 설계
- AI의 기억력을 설계하자 — 메모리 시스템 완전 정복
- 현명한 지갑 관리 — 모델 선택과 비용 최적화
- 에이전트 군단과 생존 가이드 — 멀티 에이전트 & 트러블슈팅 (이 글)
기본부터:
참고 자료: