2026_OPENCLAW
MCP_SKILLS_
GATEWAY_
TOKEN_RUNBOOK.

MCP와 커스텀 Skill을 붙이면 도구 설명이 컨텍스트를 잡아먹거나 Gateway 재시작 후에도 옛 스냅샷처럼 보일 수 있습니다. 워크스페이스 우선순위, Gateway 동작, MCP schema 토큰 예산, launchd PATH·OAuth, 원격 Mac 7×24 체크를 표로 정리합니다. 관련: 온보딩·Gateway, Docker 운영, 오류 가이드.

개발 도구 체인

1. 함정의 본질: MCP·Skills는 파일 두 개가 아니다

(1) 로드 순서가 불투명:워크스페이스 /skills、사용자 디렉터리、번들 Skills 우선순위를 모르면 디스크는 바꿨는데 에이전트는 예전 내용을 읽습니다。(2) Gateway 메모리 스냅샷:버전에 따라 스킬 메타데이터가 RAM에 남아 불완전 재시작으로는 디스크 변경이 반영되지 않을 수 있습니다。(3) MCP schema 부피:여러 서버를 한꺼번에 연결하면 도구 설명만으로 16k~32k 창을 채워 거절·환각이 늘어납니다。(4) 데몬 PATH:launchd 작업은 최소 PATH를 물려 nvm/fnm 심이 사라져 터미널과 Gateway 환경이 갈라집니다。원격 Mac 24/7에서는 터미널을 항상 열어두지 않아 이 차이를 놓치기 쉽습니다。

2. Skills 디렉터리 우선순위 표

배포 채널마다 경로 문자열이 달라질 수 있습니다。아래는일반적인 상위 덮어쓰기 직관이며,실제 절대 경로는 설치한 빌드의 공식 문서와 Gateway 로그로 반드시 대조하세요。

층(높음→낮음)용도확인
워크스페이스 /skills 또는 프로젝트 내팀 워크플로·저장소 전용Gateway cwd가 기대한 workspace인지
사용자 skills개인 실험YAML frontmatter 들여쓰기 오류로 파일 전체가 무시될 수 있음
번들 기본값제품 기본 스킬업그레이드 후 changelog 먼저 확인

3. MCP: 최소 폐루프와 토큰 예산

MCP 서버를 하나만 연결해 인증·헬스·최소 도구 호출까지 검증한 뒤 확장합니다。서버를 추가할 때마다 직렬화된 도구 정의 길이를 로그나 프롬프트 차이로 추적하세요。system+tools가 한계에 가까우면 채널별 프로필로 도구 면을 줄이거나, 서브에이전트에 지연 로딩하거나, 더 큰 컨텍스트 모델로 바꿉니다。서버 수만 늘리고 “모델이 약하다”고 단정하면 원인을 놓치기 쉽습니다。

4. 실행 가능한 5단계 검증

1단계:Gateway 로그에서 workspace 루트와 Skills 스캔 범위를 기록합니다。2단계:단일 SKILL에 눈에 띄는 문자열을 넣고 Gateway를 완전 재시작한 뒤 대화에 반영되는지 스모크 테스트합니다。3단계:MCP를 모두 끄고 하나만 켠 상태의 tools 토큰을 기준으로 잡은 다음 하나씩 다시 켭니다。4단계launchctl print 등으로 데몬 환경·PATH를 대화형 셸과 비교합니다。5단계:스테이징에서 OAuth를 의도적으로 만료시키고 실패가 로그에 드러나는지, 조용히 사라지는지 확인합니다。

# 헬스 예시(포트는 환경에 맞게) curl -sS http://127.0.0.1:18789/health 2>/dev/null || echo "adjust-endpoint"

5. Gateway 재시작 후에도 옛 동작: 증상 매트릭스

증상유력 원인조치
SKILL 수정이 안 보임다른 경로가 우선검색 경로 로그 출력·고유 문자열 grep
도구 수가 들쭉날쭉MCP 연결 실패가 삼켜짐디버그 로그·서버 단독 활성화
간헐적 도구 누락토큰 만료·리프레시 실패재인증·리프레시가 데몬 환경에서 도는지
사용자 문장은 짧은데 컨텍스트 포화큰 schema 누적MCP 축소·세션 분할·모델 교체

운영 기준치(벤더 스펙 아님):

  • 16k급에서 필터 없는 MCP 설명 합이 10k 토큰+는 흔함.
  • 상주 호스트는 plist에 node/python 절대 경로를 명시.
  • IM·Webhook 등 새 채널마다 노출 도구 집합을 재감사.

6. 심층: 도구 거버넌스가 운용 핵심이 되는 이유

2026년 MCP는 외부 연동을 일회성 스크립트에서 재조합 가능한 플랫폼 능력으로 바꿨고, 대가로 컨텍스트와 권한 표면이 함께 커집니다。LLM은 매 턴 도구를 다시 스케줄하므로 schema와 정책이 어긋나면 토큰 낭비와 권한 사고가 동시에 납니다。Apple Silicon Mac은 Gateway 상주에 조용하지만 통합 메모리는 멀티채널·장시간 세션에서 압박을 받습니다。단순히 탭을 늘린 것과 부하 형태가 다릅니다—도구 정의가 system 쪽에 오래 머무르기 때문입니다。

변경이 잦은 개발은 노트북에, 프로덕션 Gateway+MCP는 전용 머신에 두면 변경 빈도와 폭발 반경을 분리합니다。노트북은 실험에 좋지만 절전·개인 앱·불안정한 업링크와 SLA가 섞이기 쉽습니다。

업링크 안정·데몬 위생·24/7 감시가 병목이면 MACGPU 원격 Mac에 OpenClaw를 올리면 같은 macOS/Metal 스택을 유지하면서 PATH와 가동을 예측하기 쉬워집니다。사용량 과금은 고정 용량 전에 카나리아에 적합합니다。노트북만 쓰는 구성은 학습·로컬 디버그엔 타당하지만, 그래픽·상시 AI 워크플로에서는 전용 원격이 SLA를 잡기 쉽습니다—이는 마케팅이 아니라 배치 기술 판단입니다。