# OpenClaw MCP 래퍼 서버

> 발견일: 2026-03-01
> 개발: task-35.1 (1팀 헤르메스)
> 파일: `/home/jay/workspace/mcp/openclaw-mcp-server.py` (217줄)

## 결론
`openclaw agent` CLI를 MCP 프로토콜로 감싸면 Claude Code에서 GLM-5를 **네이티브 도구**로 사용 가능하다.
이를 통해 Claude 팀장(Sonnet)이 Task tool(Haiku) + MCP(GLM-5)로 **하이브리드 오케스트레이션**이 가능해진다.

## 아키텍처

```
Claude Code 세션
  ├── Task tool → Claude 모델 (opus/sonnet/haiku)
  └── openclaw_agent MCP tool → OpenClaw Gateway → Z.AI GLM-5
```

### 데이터 흐름
1. Claude Code가 MCP 서버 프로세스 시작 (python3 stdio)
2. `tools/call` JSON-RPC 요청 → MCP 서버 수신
3. MCP 서버가 `openclaw agent --agent <id> -m "<msg>" --json` subprocess 실행
4. OpenClaw Gateway가 Z.AI API 호출 → GLM-5 응답
5. MCP 서버가 JSON 응답에서 텍스트 추출 → MCP tool result로 반환
6. Claude Code가 결과 수신

## 기술 상세

### MCP 서버 스펙
- **프로토콜**: JSON-RPC 2.0, MCP protocolVersion `"2024-11-05"`
- **전송**: stdio (stdin 읽기 → stdout 쓰기)
- **의존성**: 표준 라이브러리만 (외부 패키지 없음)
- **지원 메서드**: `initialize`, `tools/list`, `tools/call`, notification 무시

### 노출 도구: `openclaw_agent`
- **파라미터**:
  - `message` (string, 필수): 에이전트에 보낼 메시지
  - `agent` (string, 선택, 기본 "main"): 에이전트 ID
  - `timeout` (number, 선택): 타임아웃(초)
- **내부 동작**: `subprocess.run(["openclaw", "agent", "--agent", agent, "-m", message, "--json"])`
- **응답 텍스트 추출 우선순위**: response → text → message → content → 원문

### 설정
```json
// ~/.claude/settings.json
{
  "mcpServers": {
    "openclaw": {
      "command": "python3",
      "args": ["/home/jay/workspace/mcp/openclaw-mcp-server.py"]
    }
  }
}
```

## 성능 측정 (2026-03-01)
- 간단한 질의("1+1=?"): GLM-5 응답 **3.7~5초**
- 동기 호출 (subprocess 블로킹): 결과 즉시 반환
- GLM-5 입력 토큰: ~40,000 (시스템 프롬프트 포함, AGENTS.md 등)

## 검증 결과
| 테스트 | 결과 |
|--------|------|
| initialize | PASS — protocolVersion "2024-11-05" 정상 |
| tools/list | PASS — openclaw_agent 도구 노출 |
| tools/call (실제 GLM 호출) | PASS — GLM-5 정확한 응답 반환 |
| 모델 메타데이터 | `"provider": "zai", "model": "glm-5"` 확인 가능 |

## 제약사항
- OpenClaw Gateway가 실행 중이어야 함 (`systemctl --user status openclaw-gateway`)
- MCP 서버는 Claude Code **세션 시작 시** 로드됨 → 설정 변경 후 재시작 필요
- cokacdir 봇 세션에서의 MCP 로딩 여부는 task-36.1로 테스트 중 (미확인)

## 활용 시나리오
1. **3팀 하이브리드**: 라 팀장(Sonnet)이 GLM-5(MCP) + Haiku(Task) 팀원 오케스트레이션
2. **비용 최적화**: 단순 작업은 GLM-5(Z.AI 구독), 복잡 작업은 Sonnet(Anthropic API)
3. **세컨드 오피니언**: Claude가 풀지 못하는 문제를 GLM-5에게 시도