MCP

openclaw mcp에는 두 가지 역할이 있습니다:

• openclaw mcp serve로 OpenClaw를 MCP 서버로 실행
• list, show, set, unset으로 OpenClaw가 소유한 outbound MCP 서버 정의 관리

다시 말해:

• serve는 OpenClaw가 MCP 서버로 동작하는 것입니다
• list / show / set / unset은 OpenClaw 런타임이 나중에 사용할 수 있는 다른 MCP 서버를 위한 MCP 클라이언트 측 레지스트리로 OpenClaw가 동작하는 것입니다

OpenClaw가 코딩 하네스 세션을 직접 호스트하고 해당 런타임을 ACP를 통해 라우팅해야 하는 경우 openclaw acp를 사용하세요.

# MCP 서버로서의 OpenClaw

이 경로는 openclaw mcp serve입니다.

# serve를 사용해야 하는 경우

다음과 같은 경우 openclaw mcp serve를 사용하세요:

• Codex, Claude Code 또는 다른 MCP 클라이언트가 OpenClaw 기반 채널 대화와 직접 통신해야 하는 경우
• 라우팅된 세션이 있는 로컬 또는 원격 OpenClaw Gateway가 이미 있는 경우
• 채널별 브리지를 따로 실행하는 대신 OpenClaw의 여러 채널 백엔드에서 작동하는 하나의 MCP 서버를 원하는 경우

OpenClaw가 코딩 런타임 자체를 호스트하고 에이전트 세션을 OpenClaw 내부에 유지해야 하는 경우에는 대신 openclaw acp를 사용하세요.

# 작동 방식

openclaw mcp serve는 stdio MCP 서버를 시작합니다. MCP 클라이언트가 해당 프로세스를 소유합니다. 클라이언트가 stdio 세션을 열어 두는 동안, 브리지는 WebSocket을 통해 로컬 또는 원격 OpenClaw Gateway에 연결하고 라우팅된 채널 대화를 MCP로 노출합니다.

# 클라이언트 모드 선택

같은 브리지를 두 가지 방식으로 사용할 수 있습니다:

# serve가 노출하는 것

브리지는 기존 Gateway 세션 라우트 메타데이터를 사용하여 채널 기반 대화를 노출합니다. OpenClaw에 다음과 같은 알려진 라우트가 포함된 세션 상태가 이미 있으면 대화가 표시됩니다:

• channel
• 수신자 또는 대상 메타데이터
• 선택적 accountId
• 선택적 threadId

이를 통해 MCP 클라이언트는 한 곳에서 다음을 수행할 수 있습니다:

• 최근 라우팅된 대화 나열
• 최근 transcript history 읽기
• 새 inbound 이벤트 대기
• 같은 라우트를 통해 응답 다시 보내기
• 브리지가 연결되어 있는 동안 도착하는 승인 요청 보기

# 사용법

openclaw mcp serve

openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

openclaw mcp serve --verbose
openclaw mcp serve --claude-channel-mode off

# 브리지 도구

현재 브리지는 다음 MCP 도구를 노출합니다:

# 이벤트 모델

브리지는 연결되어 있는 동안 메모리 내 이벤트 큐를 유지합니다.

현재 이벤트 유형:

• message
• exec_approval_requested
• exec_approval_resolved
• plugin_approval_requested
• plugin_approval_resolved
• claude_permission_request

# Claude 채널 알림

브리지는 Claude 전용 채널 알림도 노출할 수 있습니다. 이는 Claude Code 채널 어댑터에 해당하는 OpenClaw 기능입니다. 표준 MCP 도구는 계속 사용할 수 있지만, 라이브 inbound 메시지도 Claude 전용 MCP 알림으로 도착할 수 있습니다.

Claude 채널 모드가 활성화되면 서버는 Claude 실험적 기능을 알리고 다음을 내보낼 수 있습니다:

• notifications/claude/channel
• notifications/claude/channel/permission

현재 브리지 동작:

• inbound user transcript 메시지는 notifications/claude/channel로 전달됩니다
• MCP를 통해 받은 Claude 권한 요청은 메모리에서 추적됩니다
• 연결된 대화가 나중에 yes abcde 또는 no abcde를 보내면, 브리지는 이를 notifications/claude/channel/permission으로 변환합니다
• 이러한 알림은 라이브 세션 전용입니다. MCP 클라이언트 연결이 끊기면 푸시 대상이 없습니다

이는 의도적으로 클라이언트 전용입니다. 일반 MCP 클라이언트는 표준 polling 도구에 의존해야 합니다.

# MCP 클라이언트 구성

stdio 클라이언트 구성 예시:

{
  "mcpServers": {
    "openclaw": {
      "command": "openclaw",
      "args": [
        "mcp",
        "serve",
        "--url",
        "wss://gateway-host:18789",
        "--token-file",
        "/path/to/gateway.token"
      ]
    }
  }
}

대부분의 일반 MCP 클라이언트에서는 표준 도구 표면부터 사용하고 Claude 모드는 무시하세요. Claude 전용 알림 메서드를 실제로 이해하는 클라이언트에만 Claude 모드를 켜세요.

# 옵션

openclaw mcp serve는 다음을 지원합니다:

# 보안 및 신뢰 경계

브리지는 라우팅을 새로 만들어 내지 않습니다. Gateway가 이미 라우팅 방법을 알고 있는 대화만 노출합니다.

즉:

• 발신자 allowlist, 페어링, 채널 수준 신뢰는 여전히 기본 OpenClaw 채널 구성에 속합니다
• messages_send는 기존에 저장된 라우트를 통해서만 응답할 수 있습니다
• 승인 상태는 현재 브리지 세션에 대해서만 라이브/메모리 내 상태입니다
• 브리지 인증은 다른 원격 Gateway 클라이언트에 신뢰할 때 사용할 것과 동일한 Gateway 토큰 또는 비밀번호 제어를 사용해야 합니다

대화가 conversations_list에 없으면 일반적인 원인은 MCP 구성이 아닙니다. 기본 Gateway 세션에 라우트 메타데이터가 없거나 불완전한 것입니다.

# 테스트

OpenClaw는 이 브리지를 위한 결정적 Docker smoke를 제공합니다:

pnpm test:docker:mcp-channels

이 smoke는 다음을 수행합니다:

• 시드된 Gateway 컨테이너를 시작합니다
• openclaw mcp serve를 생성하는 두 번째 컨테이너를 시작합니다
• 대화 검색, transcript 읽기, 첨부 파일 메타데이터 읽기, 라이브 이벤트 큐 동작, outbound 전송 라우팅을 검증합니다
• 실제 stdio MCP 브리지를 통해 Claude 스타일 채널 및 권한 알림을 검증합니다

이는 실제 Telegram, Discord 또는 iMessage 계정을 테스트 실행에 연결하지 않고 브리지가 작동함을 증명하는 가장 빠른 방법입니다.

더 넓은 테스트 맥락은 테스트를 참조하세요.

# 문제 해결

# MCP 클라이언트 레지스트리로서의 OpenClaw

이 경로는 openclaw mcp list, show, set, unset용입니다.

이 명령들은 MCP를 통해 OpenClaw를 노출하지 않습니다. 이 명령들은 OpenClaw 구성의 mcp.servers 아래에 있는 OpenClaw 소유 MCP 서버 정의를 관리합니다.

저장된 정의는 내장 Pi 및 기타 런타임 어댑터처럼 OpenClaw가 나중에 실행하거나 구성하는 런타임을 위한 것입니다. OpenClaw는 해당 런타임이 자체 중복 MCP 서버 목록을 유지할 필요가 없도록 정의를 중앙에 저장합니다.

런타임 어댑터는 이 공유 레지스트리를 하위 클라이언트가 기대하는 형태로 정규화할 수 있습니다. 예를 들어 내장 Pi는 OpenClaw transport 값을 직접 사용하지만, Claude Code와 Gemini는 http, sse, stdio 같은 CLI 네이티브 type 값을 받습니다.

# 저장된 MCP 서버 정의

OpenClaw는 OpenClaw가 관리하는 MCP 정의를 원하는 표면을 위해 구성에 경량 MCP 서버 레지스트리도 저장합니다.

명령:

• openclaw mcp list
• openclaw mcp show [name]
• openclaw mcp set <name> <json>
• openclaw mcp unset <name>

참고:

• list는 서버 이름을 정렬합니다.
• 이름 없이 show를 실행하면 구성된 전체 MCP 서버 객체를 출력합니다.
• set은 명령줄에서 하나의 JSON 객체 값을 기대합니다.
• Streamable HTTP MCP 서버에는 transport: "streamable-http"를 사용하세요. openclaw mcp set은 호환성을 위해 CLI 네이티브 type: "http"도 동일한 표준 구성 형태로 정규화합니다.
• 지정된 서버가 없으면 unset은 실패합니다.

예시:

openclaw mcp list
openclaw mcp show context7 --json
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
openclaw mcp set docs '{"url":"https://mcp.example.com","transport":"streamable-http"}'
openclaw mcp unset context7

예시 구성 형태:

{
  "mcp": {
    "servers": {
      "context7": {
        "command": "uvx",
        "args": ["context7-mcp"]
      },
      "docs": {
        "url": "https://mcp.example.com",
        "transport": "streamable-http"
      }
    }
  }
}

# Stdio 전송

로컬 자식 프로세스를 실행하고 stdin/stdout을 통해 통신합니다.

# SSE / HTTP 전송

HTTP Server-Sent Events를 통해 원격 MCP 서버에 연결합니다.

예시:

{
  "mcp": {
    "servers": {
      "remote-tools": {
        "url": "https://mcp.example.com",
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

url의 민감한 값(userinfo)과 headers는 로그 및 상태 출력에서 수정 처리됩니다.

# Streamable HTTP 전송

streamable-http는 sse 및 stdio와 함께 사용할 수 있는 추가 전송 옵션입니다. 원격 MCP 서버와의 양방향 통신에 HTTP 스트리밍을 사용합니다.

OpenClaw 구성은 transport: "streamable-http"를 표준 표기로 사용합니다. CLI 네이티브 MCP type: "http" 값은 openclaw mcp set을 통해 저장할 때 허용되며 기존 구성에서는 openclaw doctor --fix로 복구되지만, 내장 Pi가 직접 사용하는 것은 transport입니다.

예시:

{
  "mcp": {
    "servers": {
      "streaming-tools": {
        "url": "https://mcp.example.com/stream",
        "transport": "streamable-http",
        "connectionTimeoutMs": 10000,
        "headers": {
          "Authorization": "Bearer <token>"
        }
      }
    }
  }
}

# 현재 제한 사항

이 페이지는 현재 제공되는 브리지를 문서화합니다.

현재 제한 사항:

• 대화 검색은 기존 Gateway 세션 경로 메타데이터에 의존합니다
• Claude 전용 어댑터 외에는 범용 푸시 프로토콜이 없습니다
• 메시지 편집 또는 반응 도구는 아직 없습니다
• HTTP/SSE/streamable-http 전송은 단일 원격 서버에 연결합니다. 아직 다중화된 업스트림은 없습니다
• permissions_list_open은 브리지가 연결된 동안 관찰된 승인만 포함합니다

# 관련 항목

• CLI 참조
• Plugins