2026년 원격 물리 Mac에서 OpenClaw로 MCP 연결: stdio와 Streamable HTTP 이중 경로 재현 튜토리얼—spawn ENOENT·프로토콜 버전 불일치·tool 타임아웃 트러블슈팅 Runbook + CLI 설정 조각 + FAQ

2. stdio vs Streamable HTTP: 언제 무엇을 쓸까

같은 호스트에서는 이동 부품을 최소화하는 전송을 고르고, 서버 공유나 프록시 인증이 필요할 때 HTTP로 승격합니다.

3. 7단계 재현 롤아웃

1. 신원·기준선 — OpenClaw 소유 사용자, LaunchAgent 라벨, launchctl print·유닛에서의 cwd를 기록합니다.
2. 게이트웨이 없이 stdio 재생 — 동일 사용자로 /bin/bash -lc 'which node; node -v'와 env 파일까지 맞춘 MCP 명령을 실행합니다.
3. stdio 설정 경화 — command 절대 경로, 명시적 args, 선택 cwd, 명시 env(아래 JSON 참고).
4. HTTP 경로(선택) — MCP HTTP를 127.0.0.1에 바인딩하고 nginx/Caddy에서 TLS 종료 후 curl -v로 Accept 협상을 확인합니다.
5. 버전 고정 — MCP SDK·서버 패키지를 OpenClaw 내부 클라이언트 라이브러리와 동일 major.minor로 핀하고 변경 로그에 둘 다 적습니다.
6. 타임아웃 예산 — 현실 입력으로 tools/call P95를 재고, 클라이언트 대기는 P95×1.5 이상으로 두되 상한을 둡니다.
7. 로그 계약 — initialize, tools/list, tools/call마다 공통 상관 ID로 JSON 한 줄씩 남깁니다.

재시작에도 살아남는 에이전트 흐름은 ZoneMac 물리 노드 OpenClaw 24/7 자동화 패턴과 이 런북을 맞추면 운영 표준이 한 줄로 이어집니다. 장시간 데몬 안정성은 OpenClaw 장시간 운용 Mac mini 안정성 가이드와 교차 검증하세요.

4. CLI·설정 JSON 조각(예시)

키 이름은 호스트·OpenClaw 스키마에 맞게 바꿉니다. 핵심은 절대 경로와 명시적 env 블록입니다.

{
  "mcpServers": {
    "repo-tools": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/usr/local/lib/mcp-servers/repo-tools/dist/main.js"],
      "cwd": "/Users/shared/mcp/repo-tools",
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/bin:/bin",
        "NODE_ENV": "production"
      }
    }
  }
}

{
  "mcpServers": {
    "legacy-npx": {
      "command": "/bin/bash",
      "args": ["-lc", "exec npx --yes @example/[email protected]"],
      "env": { "HOME": "/Users/shared" }
    }
  }
}

{
  "mcpServers": {
    "http-shared": {
      "url": "https://mcp.internal.example.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_EDGE_TOKEN}"
      }
    }
  }
}

5. 증상 런북

5.1 spawn ENOENT(stdio)

5.2 프로토콜 버전·406(Streamable HTTP)

서버·클라이언트 핸드셰이크 로그를 나란히 비교하세요. 서버가 text/event-stream을 기대하는데 프록시가 gzip만 넣고 flush하지 않으면 semver는 맞아도 “버전 불일치”로 보일 수 있습니다.

5.3 tool 타임아웃

세 타이머를 그리세요: (A) 모델·라우터 대기, (B) 게이트웨이 업스트림 데드라인, (C) MCP 서버 내부 잡 타임아웃. 가장 빡빡한 층을 먼저 조정하고, 트레이스로 큐잉이 증명될 때만 인접 층을 넓힙니다.

6. SLO 문서에 붙일 수치

• 약 4W — Apple Silicon Mac mini가 SSH·경량 게이트웨이를 유지한 유휴 전력의 대략적 스케일. x86 타워 유휴와 TCO 비교할 때 인용 가능.
• 25초 — 공유 노드에서 “빠른” tools/call P95의 경험칙 상한, 이후엔 tool 분할·부분 결과 스트리밍을 검토.
• 600초 — 대형 리포 스캔 같은 장기 유지보수 작업은 단일 블로킹 MCP 호출이 아니라 비동기 잡+폴링으로—CI 미러에서 긴 Git·npm과 같은 취급.

7. FAQ