OpenClaw MCP 서버 설정: MCP 클라이언트와 채널 연결하기

OpenClaw를 MCP 서버로 사용하기

이 섹션은 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로 노출해요.

라이프사이클:

MCP 클라이언트가 openclaw mcp serve를 실행해요.
브리지가 Gateway에 연결돼요.
라우팅된 세션이 MCP 대화 및 transcript/history 도구가 돼요.
브리지가 연결된 동안 실시간 이벤트가 메모리에 큐로 쌓여요.
Claude 채널 모드가 활성화되면, 동일한 세션에서 Claude 전용 푸시 알림도 받을 수 있어요.

중요한 동작:

실시간 큐 상태는 브리지가 연결될 때 시작돼요.
이전 기록은 messages_read로 읽을 수 있어요.
Claude 푸시 알림은 MCP 세션이 유지되는 동안에만 존재해요.
클라이언트 연결이 끊기면 브리지가 종료되고 실시간 큐도 사라져요.

클라이언트 모드 선택하기

브리지를 두 가지 방식으로 사용할 수 있어요.

일반 MCP 클라이언트: 표준 MCP 도구만 사용해요. conversations_list, messages_read, events_poll, events_wait, messages_send와 승인 도구들을 활용하세요.
Claude Code: 표준 MCP 도구에 Claude 전용 채널 어댑터를 더해 사용해요. --claude-channel-mode on을 설정하거나 기본값인 auto를 그대로 두면 돼요.

현재 auto는 on과 동일하게 작동해요. 아직 클라이언트 기능을 감지하는 로직은 없거든요.

AI Setup Assistant

다음 단계

`serve`가 제공하는 기능

브릿지는 기존 Gateway 세션 라우트 메타데이터를 활용해서 채널 기반의 대화 내용을 노출해요. OpenClaw가 다음과 같은 알려진 라우트 정보와 함께 세션 상태를 보유하고 있을 때 대화가 나타나요:

channel
수신자(recipient) 또는 목적지(destination) 메타데이터
선택 사항인 accountId
선택 사항인 threadId

이를 통해 MCP 클라이언트는 한 곳에서 다음과 같은 작업들을 할 수 있어요:

최근 라우팅된 대화 목록 확인
최근 트랜스크립트 히스토리 읽기
새로운 인바운드 이벤트 대기
동일한 라우트를 통해 답장 전송
브릿지가 연결된 동안 도착하는 승인 요청 확인

사용법

# Local Gateway
openclaw mcp serve

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

# Remote Gateway with password auth
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# Enable verbose bridge logs
openclaw mcp serve --verbose

# Disable Claude-specific push notifications
openclaw mcp serve --claude-channel-mode off

브릿지 도구

현재 브릿지는 다음과 같은 MCP 도구들을 제공해요:

conversations_list
conversation_get
messages_read
attachments_fetch
events_poll
events_wait
messages_send
permissions_list_open
permissions_respond

`conversations_list`

Gateway 세션 상태에 라우트 메타데이터가 이미 존재하는 최근 세션 기반 대화들을 나열해요.

유용한 필터:

limit
search
channel
includeDerivedTitles
includeLastMessage

`conversation_get`

session_key를 사용해 대화 하나를 반환해요.

`messages_read`

세션 기반 대화 하나에 대한 최근 트랜스크립트 메시지를 읽어요.

`attachments_fetch`

트랜스크립트 메시지에서 텍스트가 아닌 콘텐츠 블록을 추출해요. 이는 트랜스크립트 콘텐츠에 대한 메타데이터 뷰이며, 독립적인 영구 첨부 파일 저장소는 아니에요.

`events_poll`

숫자 커서(cursor) 이후의 대기 중인 라이브 이벤트를 읽어요.

`events_wait`

다음 일치하는 이벤트가 도착하거나 타임아웃이 만료될 때까지 롱 폴링(Long-polling)을 수행해요.

Claude 전용 푸시 프로토콜 없이 일반 MCP 클라이언트가 실시간에 가까운 메시지 전달이 필요할 때 이 도구를 사용하세요.

`messages_send`

세션에 이미 기록된 동일한 라우트를 통해 텍스트를 다시 보내요.

현재 동작 방식:

기존 대화 라우트가 필요해요.
세션의 채널, 수신자, account id, thread id를 사용해요.
텍스트만 전송할 수 있어요.

`permissions_list_open`

브릿지가 Gateway에 연결된 이후 관찰한 대기 중인 exec/plugin 승인 요청 목록을 나열해요.

`permissions_respond`

대기 중인 exec/plugin 승인 요청을 다음 중 하나로 해결해요:

allow-once
allow-always
deny

이벤트 모델

브릿지는 연결되어 있는 동안 메모리 내 이벤트 큐를 유지해요.

현재 이벤트 유형:

message
exec_approval_requested
exec_approval_resolved
plugin_approval_requested
plugin_approval_resolved
claude_permission_request

중요한 제한 사항:

큐는 라이브 전용이에요. MCP 브릿지가 시작될 때 함께 시작돼요.
events_poll과 events_wait는 그 자체로 오래된 Gateway 히스토리를 다시 재생하지 않아요.
영구적인 백로그는 messages_read를 통해 읽어야 해요.

Claude 채널 알림

Bridge는 Claude 전용 채널 알림 기능을 제공할 수 있어요. 이건 Claude Code 채널 어댑터의 OpenClaw 버전이라고 보면 돼요. 표준 MCP 도구는 그대로 사용할 수 있으면서, 실시간으로 들어오는 메시지를 Claude 전용 MCP 알림으로 받을 수 있죠.

Flags:

--claude-channel-mode off: 표준 MCP 도구만 사용
--claude-channel-mode on: Claude 채널 알림 활성화
--claude-channel-mode auto: 현재 기본값이며, on과 동일하게 동작

Claude 채널 모드가 활성화되면 서버는 Claude 실험적 기능을 알리고 다음 항목들을 보낼 수 있게 돼요:

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

현재 Bridge의 동작 방식은 이렇습니다:

들어오는 user 트랜스크립트 메시지는 notifications/claude/channel로 전달돼요.
MCP를 통해 수신된 Claude 권한 요청은 메모리에서 추적돼요.
연결된 대화에서 나중에 yes abcde 또는 no abcde를 보내면, Bridge가 이를 notifications/claude/channel/permission으로 변환해요.
이 알림들은 라이브 세션에서만 유효해요. MCP 클라이언트 연결이 끊기면 푸시 대상이 사라집니다.

이 기능은 의도적으로 클라이언트별로 특화되어 있어요. 일반적인 MCP 클라이언트라면 표준 폴링 도구에 의존하는 것이 좋습니다.

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는 다음 옵션들을 지원해요:

--url <url>: Gateway WebSocket URL
--token <token>: Gateway 토큰
--token-file <path>: 파일에서 토큰 읽기
--password <password>: Gateway 비밀번호
--password-file <path>: 파일에서 비밀번호 읽기
--claude-channel-mode <auto|on|off>: Claude 알림 모드
-v, --verbose: stderr에 상세 로그 출력

가능하다면 비밀 정보를 직접 입력하는 방식보다 --token-file이나 --password-file을 사용하는 것을 추천해요.

보안 및 신뢰 경계

이 브릿지는 라우팅을 새로 만들어내지 않아요. Gateway가 이미 어떻게 라우팅해야 하는지 알고 있는 대화들만 노출할 뿐이죠.

이것은 다음과 같은 의미예요:

발신자 허용 목록(allowlist), 페어링, 채널 수준의 신뢰 설정은 여전히 기존 OpenClaw 채널 설정을 따라요.
messages_send는 이미 저장된 경로를 통해서만 답장을 보낼 수 있어요.
승인 상태는 현재 브릿지 세션 동안에만 실시간 메모리에 유지돼요.
브릿지 인증에는 다른 원격 Gateway 클라이언트를 사용할 때와 똑같이 신뢰할 수 있는 Gateway 토큰이나 비밀번호 제어 기능을 사용해야 해요.

만약 conversations_list에서 특정 대화가 보이지 않는다면, 대부분 MCP 설정 문제는 아닐 거예요. 보통은 해당 Gateway 세션에 경로 메타데이터가 없거나 불완전해서 발생하는 문제예요.

테스트

OpenClaw는 이 브릿지를 위해 결정론적인(deterministic) Docker 스모크 테스트를 제공해요:

pnpm test:docker:mcp-channels

이 스모크 테스트는 다음과 같은 과정을 거쳐요:

시드 데이터가 포함된 Gateway 컨테이너를 시작해요
openclaw mcp serve를 실행하는 두 번째 컨테이너를 시작해요
대화 검색, 트랜스크립트 읽기, 첨부 파일 메타데이터 읽기, 실시간 이벤트 큐 동작, 아웃바운드 전송 라우팅을 확인해요
실제 stdio MCP 브릿지를 통해 Claude 스타일의 채널 및 권한 알림을 검증해요

실제 Telegram, Discord 또는 iMessage 계정을 테스트에 직접 연결하지 않고도 브릿지가 제대로 작동하는지 확인할 수 있는 가장 빠른 방법이에요.

더 광범위한 테스트 컨텍스트는 Testing 문서를 참고하세요.

트러블슈팅

대화 목록이 반환되지 않는 경우

보통 Gateway 세션이 아직 라우팅 가능한 상태가 아님을 의미해요. 해당 세션에 채널/제공자(provider), 수신자, 그리고 선택 사항인 계정/스레드 라우트 메타데이터가 저장되어 있는지 확인해 보세요.

`events_poll` 또는 `events_wait`에서 이전 메시지가 누락되는 경우

이는 예상된 동작이에요. 실시간 큐는 브릿지가 연결되는 시점에 시작되거든요. 이전 트랜스크립트 내역을 읽으려면 messages_read를 사용하세요.

Claude 알림이 나타나지 않는 경우

다음 항목들을 모두 체크해 보세요:

클라이언트가 stdio MCP 세션을 계속 열어두고 있는지 확인하세요
--claude-channel-mode가 on 또는 auto로 설정되어 있는지 확인하세요
클라이언트가 Claude 전용 알림 메서드를 실제로 처리할 수 있는지 확인하세요
인바운드 메시지가 브릿지 연결 이후에 발생했는지 확인하세요

승인 요청(Approvals)이 보이지 않는 경우

permissions_list_open은 브릿지가 연결되어 있는 동안 감지된 승인 요청만 보여줘요. 이 API는 영구적인 승인 내역을 보관하고 제공하는 용도가 아니에요.

OpenClaw를 MCP 클라이언트 레지스트리로 사용하기

이 경로는 openclaw mcp list, show, set, unset 명령어를 다뤄요.

이 명령어들은 OpenClaw를 MCP로 노출하는 게 아니라, OpenClaw 설정 내 mcp.servers에 있는 OpenClaw 소유의 MCP 서버 정의를 관리해요.

저장된 정의들은 나중에 OpenClaw가 실행하거나 구성할 런타임(예: 내장된 Pi나 다른 런타임 어댑터)을 위한 것이에요. OpenClaw가 정의를 중앙에서 관리하기 때문에, 각 런타임이 별도의 MCP 서버 목록을 중복해서 유지할 필요가 없어요.

중요한 동작 방식은 다음과 같아요:

이 명령어들은 OpenClaw 설정만 읽거나 써요.
대상 MCP 서버에 실제로 연결하지 않아요.
명령어, URL, 또는 원격 transport가 지금 연결 가능한지 확인하지 않아요.
실행 시점에 어떤 transport 형태를 실제로 지원할지는 런타임 어댑터가 결정해요.

저장된 MCP 서버 정의

OpenClaw는 OpenClaw가 관리하는 MCP 정의가 필요한 곳을 위해 설정 파일에 가벼운 MCP 서버 레지스트리를 저장해요.

명령어:

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

예시:

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"}'
openclaw mcp unset context7

설정 형태 예시:

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

Stdio transport

로컬 자식 프로세스를 실행하고 stdin/stdout으로 통신해요.

필드	설명
`command`	실행할 파일 (필수)
`args`	커맨드라인 인자 배열
`env`	추가 환경 변수
`cwd` / `workingDirectory`	프로세스의 작업 디렉토리

SSE / HTTP transport

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

필드	설명
`url`	원격 서버의 HTTP 또는 HTTPS URL (필수)
`headers`	선택 사항인 HTTP 헤더의 키-값 맵 (예: auth tokens)
`connectionTimeout`	서버별 연결 타임아웃 (ms 단위, 선택 사항)

예시:

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

url(사용자 정보) 및 headers에 포함된 민감한 값은 로그와 상태 출력에서 마스킹 처리돼요.

Streamable HTTP transport

streamable-http는 sse 및 stdio와 함께 사용할 수 있는 추가 transport 옵션이에요. 원격 MCP 서버와의 양방향 통신을 위해 HTTP 스트리밍을 사용해요.

필드	설명
`url`	원격 서버의 HTTP 또는 HTTPS URL (필수)
`transport`	이 transport를 선택하려면 `"streamable-http"`로 설정하세요
`headers`	선택 사항인 HTTP 헤더의 키-값 맵 (예: auth tokens)
`connectionTimeout`	서버별 연결 타임아웃 (ms 단위, 선택 사항)

예시:

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

이 명령어들은 저장된 설정만 관리해요. 채널 브리지를 시작하거나, 라이브 MCP 클라이언트 세션을 열거나, 대상 서버가 연결 가능한지 확인하지는 않아요.

현재 제한 사항

이 페이지는 현재 배포된 브리지의 상태를 설명해요.

현재 제한 사항은 다음과 같아요:

대화 검색(Conversation discovery)은 기존 Gateway 세션 경로 메타데이터에 의존해요.
Claude 전용 어댑터 외에는 범용 push 프로토콜이 없어요.
메시지 수정이나 반응(react) 도구는 아직 지원하지 않아요.
HTTP/SSE/streamable-http transport는 단일 원격 서버에만 연결되며, 아직 멀티플렉싱 업스트림은 지원하지 않아요.
permissions_list_open에는 브리지가 연결된 동안 관찰된 승인 사항만 포함돼요.

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.