대상: Gateway는 돌아가는데 MCP 도구가 안 보이거나 호출이 타임아웃하거나 Skills가 재시작 후 사라집니다. 기대 결과: 부트스트랩은설치 가이드와Docker 프로덕션 런북에, 영속성은볼륨·Skills 권한 글에 맡깁니다. 본 런북은선언 → 프로세스 가시성 → Gateway 등록 → 모델·도구·채널 트리아지를 다룹니다.구성: 여섯 가지 함정, 표 둘, 설정 스케치, 경고, 여섯 단계, KPI 세 가지, 마무리 안내입니다.
MCP는 Gateway와 자식 프로세스 또는 원격 엔드포인트 사이의JSON-RPC 세션입니다. 설정 행이 있다고 자식이 뜨는 것은 아니고, 뜬다고 스키마가 돌아오는 것도 아닙니다. 자주 있는 여섯 가지 오해는 다음과 같습니다.
~/.zshrc의 PATH나 API 키를 보지 못합니다.AGENTS.md와 bootstrap 문구가 겹침: MCP와 Skills에 중복 지시가 있으면 컨텍스트가 부풉니다. 경계는Skills 조정 체크리스트에 맞춰 나눕니다.openclaw doctor는설치 후 doctor 가이드 순서로 실행하고, 본 글은 또 다른 설치 튜토리얼이 아니라 도구 등록 증거 사슬을 더합니다.
MCP 서버마다 한 장짜리 「최소 재현 카드」를 둡니다. 읽기 질의 하나, 반드시 거절돼야 할 부정 테스트 하나, 로그에서 찾을 토큰 세 개를 적어 온콜이 긴 프롬프트를 다 읽지 않고 설정 퇴행을 비교합니다. 카드에허용된 이그레스와 데이터 분류를 적어 사고 때 기록 없이 토큰 범위를 넓히지 않습니다.
필드 이름은 OpenClaw 버전마다 다릅니다. 본 표는작업 순서를 고정합니다.
| 증상 | 먼저 모을 것 | 유력 원인 | 감사 가능한 조치 |
|---|---|---|---|
| 도구 목록이 비거나 일부만 | Gateway 로그, 자식 종료 코드 | 바이너리 누락, cwd, permission denied | 절대 경로 command·args·cwd. 자식을 Gateway와동일 사용자로 실행 |
| 첫 호출만 느리고 이후 정상 | 콜드 스타트 시간, 패키지 가져오기 로그 | npx -y 또는 런타임 JIT | 프리웜, 이미지에서 버전 고정, 첫 호출 타임아웃 완화 |
| 지속적 타임아웃 | 자식 생존, CPU, FD 사용 | 데드락, 블로킹 IO | 허용 범위에서 샘플·트레이스, 읽기 전용 도구로 A/B |
| 「도구가 등록되지 않음」 | 스키마 로그, 프로토콜 버전 | 구현 불일치 | MCP 버전 맞춤, 마이너 고정, 상류 변경 로그 확인 |
능력 매트릭스를 공개해 한 워크플로를 세 가지 방식으로 설명하지 않습니다.
| 출처 | 적합한 용도 | 버전 관리 | 리스크 |
|---|---|---|---|
| ClawHub·마켓 | 빠른 실험 | 커밋 또는 semver 범위 고정, 주간 diff | 상류 드리프트. 회귀 테스트 필요 |
저장소 SKILL.md·비공개 팩 | 규정 준수가 무거운 흐름 | PR로 본선에 함께 배포 | 유지 부담. MCP 범위와 정렬 |
| MCP(기록 시스템) | DB, 티켓, 내부 HTTP API | 독립 릴리스 주기 | 과도한 토큰. 허용 목록 유지 |
# 구조 스케치일 뿐입니다. 실제 키, 중첩, 핫 리로드는 현행 OpenClaw 문서를 따릅니다.
# 목표: Gateway가 고정 사용자로 stdio MCP 서버를 기동합니다.
#
# mcpServers:
# internal-readonly-lookup:
# command: /usr/local/bin/node
# args: ["/opt/mcp-servers/lookup/dist/index.js"]
# env:
# LOOKUP_API_TOKEN: "${LOOKUP_TOKEN_READONLY}"
#
# ClawHub Skill: 팀 skills 디렉터리에 추출·클론한 뒤 skill 인덱스를 새로고침하거나
# 버전 문서의 reload 명령을 실행합니다.
경고: MCP는 어시스턴트를 프로덕션 데이터에 연결합니다. 최소 권한과 감사 추적이 「일단 돌아가게」보다 낫습니다. 읽기·쓰기 서버를 나누고 토큰을 나누며 허용 목록 발췌를 변경 티켓에 붙입니다.
PATH, cwd, bind 마운트를 문서화합니다.memory_search나 문서 도구로 옮겨 컨텍스트 성장을 억제합니다.AGENTS.md에 같은 동작이 적힌 횟수. 하나를 넘으면 서명 면제가 필요합니다.원격 Mac이나 클라우드 호스트에서는 디스크와 로그 로테이션이 임시 파일을 작은 시스템 볼륨에 쓰는 MCP 자식에 영향을 주어 모델 설정이 같아도 타임아웃이 무작위처럼 보일 수 있습니다. 도구 설정과 호스트 운용을 함께 봅니다.
HTTP·SSE MCP 앞단에는 리버스 프록시 유휴 타임아웃, Upgrade 처리, TLS 종료를 포함합니다. Gateway 로그에 핸드셰이크 성공이 있어도 엣지가 499·504를 줄 수 있습니다. OpenClaw 타임아웃만 올리기 전에Nginx·Caddy 리버스 프록시 가이드를 대조합니다.
커뮤니티 성격의 참고(벤치마크 아님): 무거운 MCP 서버 세 개와 넓은 검색을 같이 쓰면 대기열 지터가 분 단위로 커질 수 있습니다. SLA에는 능력 매트릭스와 허용 목록이 무한 플러그인보다 낫습니다.
절전, VPN 끊김, 경로 드리프트로 자식 프로세스와 skill 인덱스가 예측하기 어려워집니다. 실제 업무 데이터를 연결하려면24시간 가동, 영구 경로, 감사 가능한 권한이 필요합니다.
멀티 리전 선택이나 유연한 약관이 없는 자가 관리 장비는 공유 호스트로 기울기 쉽고 콜드 스타트와 로그 IO가 경쟁합니다. Gateway를디스크와 이그레스가 예측 가능한 전용 Apple Silicon에 두는 것은 전문 Mac 클라우드에서 흔한 선택입니다.MACCOME은 지역별Mac mini M4·M4 Pro를 유연한 대여 조건으로 제공하며 Gateway와 빌드 팜의 안정적 기반이 됩니다. 주문 전 공개 요금과 고객센터 SLA를 확인하십시오.
이 런북의 세 가지 검사를 이미지를 전 플릿에 올리기 전에 원격 Mac에서 시험해 「로컬에서는 되는데 프로덕션에서는 타임아웃」 루프를 줄입니다. Gateway를 인터넷에 노출하면 TLS, 속도 제한, IP 허용 목록을 같은 변경에 넣고 나중 패치로 미루지 않습니다.
자주 묻는 질문
채널 온보딩 글과 어떻게 짝을 이루나요?
채널 글은 Slack·Discord·Telegram OAuth를 다루고 본문은 도구 발견을 다룹니다. 메시지는 Gateway에 닿는데 도구만 실패하면 표 1에서 증거를 모은 뒤 「연결됐지만 조용함」류로 돌아갑니다.
롤백에 무엇을 포함하나요?
MCP 항목을 제거하고 재시작 순서를 기록하고 읽기 전용 검증 질의를 돌리고 대시보드에서 도구 수가 기준선으로 돌아왔는지 확인합니다. 과금 정합은대여 요금으로 맞춥니다.
컨테이너와 베어메탈 경로가 다르면 어떻게 하나요?
런타임마다 절대 경로 매트릭스를 유지하고 모델이 채팅에서 경로를 추측하지 않게 합니다.고객센터와 Docker 볼륨 글을 함께 확인합니다.