​

mcp

• openclaw mcp serve로 OpenClaw를 MCP 서버로 실행
• list, show, set, unset으로 OpenClaw 소유의 아웃바운드 MCP 서버 정의 관리

• serve는 OpenClaw가 MCP 서버로 동작하는 경우입니다
• list / show / set / unset은 OpenClaw가 나중에 자체 런타임에서 소비할 수 있는 다른 MCP 서버들을 위한 클라이언트 측 레지스트리로 동작하는 경우입니다

​

OpenClaw를 MCP 서버로 사용

​

serve를 사용해야 하는 경우

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

​

작동 방식

1. MCP 클라이언트가 openclaw mcp serve를 실행합니다
2. 브리지가 Gateway에 연결합니다
3. 라우팅된 세션이 MCP 대화와 transcript/history 도구가 됩니다
4. 브리지가 연결되어 있는 동안 라이브 이벤트가 메모리에 대기열로 저장됩니다
5. Claude 채널 모드가 활성화되어 있으면 동일한 세션이 Claude 전용 푸시 알림도 받을 수 있습니다

• 라이브 큐 상태는 브리지가 연결될 때 시작됩니다
• 이전 transcript 기록은 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를 그대로 두세요.

​

serve가 노출하는 항목

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

• 최근 라우팅된 대화 나열
• 최근 transcript 기록 읽기
• 새 수신 이벤트 대기
• 같은 경로를 통해 응답 다시 보내기
• 브리지가 연결된 동안 도착한 승인 요청 보기

​

사용법

# 로컬 Gateway
openclaw mcp serve

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

# 비밀번호 인증을 사용하는 원격 Gateway
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password

# 자세한 브리지 로그 활성화
openclaw mcp serve --verbose

# Claude 전용 푸시 알림 비활성화
openclaw mcp serve --claude-channel-mode off

​

브리지 도구

• conversations_list
• conversation_get
• messages_read
• attachments_fetch
• events_poll
• events_wait
• messages_send
• permissions_list_open
• permissions_respond

​

conversations_list

• limit
• search
• channel
• includeDerivedTitles
• includeLastMessage

​

conversation_get

​

messages_read

​

attachments_fetch

​

events_poll

​

events_wait

​

messages_send

• 기존 대화 경로가 필요합니다
• 세션의 채널, 수신자, 계정 id, 스레드 id를 사용합니다
• 텍스트만 전송합니다

​

permissions_list_open

​

permissions_respond

• 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 기록을 재생하지 않습니다
• 영구 backlog는 messages_read로 읽어야 합니다

​

Claude 채널 알림

• --claude-channel-mode off: 표준 MCP 도구만
• --claude-channel-mode on: Claude 채널 알림 활성화
• --claude-channel-mode auto: 현재 기본값이며 on과 동일한 브리지 동작

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

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

​

MCP 클라이언트 config

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

​

옵션

• --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에 자세한 로그 출력

​

보안 및 신뢰 경계

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

​

테스트

pnpm test:docker:mcp-channels

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

​

문제 해결

​

반환되는 대화가 없음

​

events_poll 또는 events_wait가 이전 메시지를 놓침

​

Claude 알림이 표시되지 않음

• 클라이언트가 stdio MCP 세션을 계속 열어 두고 있는지
• --claude-channel-mode가 on 또는 auto인지
• 클라이언트가 실제로 Claude 전용 알림 메서드를 이해하는지
• 수신 메시지가 브리지가 연결된 이후에 발생했는지

​

승인이 표시되지 않음

​

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

• 이 명령들은 OpenClaw config만 읽거나 씁니다
• 대상 MCP 서버에 연결하지 않습니다
• 명령, URL 또는 원격 전송이 현재 실제로 도달 가능한지 검증하지 않습니다
• 런타임 어댑터는 실행 시점에 실제로 지원하는 전송 형태를 결정합니다

​

저장된 MCP 서버 정의

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

• list는 서버 이름을 정렬합니다.
• 이름 없이 show를 실행하면 구성된 전체 MCP 서버 객체를 출력합니다.
• set은 명령줄에서 하나의 JSON 객체 값을 기대합니다.
• 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"}'
openclaw mcp unset context7

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

​

Stdio 전송

​

SSE / HTTP 전송

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

​

Streamable HTTP 전송

{
  "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에는 브리지가 연결되어 있는 동안 관찰한 승인만 포함됩니다