OpenClaw MCP 서버

npm version License: MIT GHCR Website

🦞 OpenClaw AI 어시스턴트 통합을 위한 MCP(Model Context Protocol) 서버입니다.

데모

제작 동기

안녕하세요! 저는 메시징 채널에만 의존하여 OpenClaw와 통신하고 싶지 않았기 때문에 이 MCP 서버를 만들었습니다. 제가 정말 흥미롭게 생각하는 부분은 OpenClaw를 Claude 웹 UI에 연결하는 기능입니다. 본질적으로 제 채팅이 Claw 봇에게 작업을 위임할 수 있고, 그러면 봇이 Claude Code를 실행하여 문제를 해결하는 등 나머지 모든 것을 처리하게 됩니다.

AI 어시스턴트가 다른 AI 어시스턴트를 조정하는 것이라고 생각하면 됩니다. 꽤 멋지지 않나요?

빠른 시작

Docker (권장)

사전 빌드된 이미지는 릴리스될 때마다 GitHub Container Registry에 게시됩니다.

docker pull ghcr.io/freema/openclaw-mcp:latest

docker-compose.yml 생성:

services:
  mcp-bridge:
    image: ghcr.io/freema/openclaw-mcp:latest
    container_name: openclaw-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - OPENCLAW_URL=http://host.docker.internal:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_MODEL=openclaw
      - AUTH_ENABLED=true
      - MCP_CLIENT_ID=openclaw
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
      - CORS_ORIGINS=https://claude.ai
    extra_hosts:
      - "host.docker.internal:host-gateway"
    read_only: true
    security_opt:
      - no-new-privileges

보안 비밀 생성 및 시작:

export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
docker compose up -d

그런 다음 Claude.ai에서 MCP_CLIENT_ID=openclaw 및 MCP_CLIENT_SECRET을 사용하여 서버를 가리키는 사용자 지정 MCP 커넥터를 추가합니다.

팁: 프로덕션 환경에서는 latest 대신 특정 버전을 고정하세요: ghcr.io/freema/openclaw-mcp:1.1.0

로컬 (Claude Desktop)

npx openclaw-mcp

Claude Desktop 설정에 추가:

{
  "mcpServers": {
    "openclaw": {
      "command": "npx",
      "args": ["openclaw-mcp"],
      "env": {
        "OPENCLAW_URL": "http://127.0.0.1:18789",
        "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
        "OPENCLAW_MODEL": "openclaw",
        "OPENCLAW_TIMEOUT_MS": "300000"
      }
    }
  }
}

원격 (Claude.ai) - Docker 미사용

AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
  MCP_ISSUER_URL=https://mcp.your-domain.com \
  CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
  npx openclaw-mcp --transport sse --port 3000

중요: 리버스 프록시(Caddy, nginx 등) 뒤에서 실행할 때는 MCP_ISSUER_URL(또는 --issuer-url)을 공개 HTTPS URL로 설정해야 합니다. 그렇지 않으면 OAuth 메타데이터가 http://localhost:3000을 알리게 되어 클라이언트가 인증에 실패하게 됩니다.

자세한 내용은 설치 가이드를 참조하세요.

아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                         Your Server                             │
│                                                                 │
│  ┌─────────────────┐      ┌─────────────────────────┐          │
│  │   OpenClaw      │      │    OpenClaw MCP         │          │
│  │   Gateway       │◄────►│    Bridge Server        │          │
│  │   :18789        │      │    :3000                │          │
│  │                 │      │                         │          │
│  │  OpenAI-compat  │      │  - OAuth 2.1 auth       │          │
│  │  /v1/chat/...   │      │  - CORS protection      │          │
│  └─────────────────┘      │  - Input validation     │          │
│                           └──────────┬──────────────┘          │
│                                      │                          │
└──────────────────────────────────────┼──────────────────────────┘
                                       │ HTTPS + OAuth 2.1
                                       ▼
                              ┌─────────────────┐
                              │   Claude.ai     │
                              │   (MCP Client)  │
                              └─────────────────┘

사용 가능한 도구

동기식 도구

도구	설명
`openclaw_chat`	OpenClaw에 메시지를 보내고 응답을 받음
`openclaw_status`	OpenClaw 게이트웨이 상태 확인
`openclaw_instances`	구성된 모든 OpenClaw 인스턴스 나열

비동기식 도구 (장기 실행 작업용)

도구	설명
`openclaw_chat_async`	메시지를 대기열에 넣고 즉시 task_id를 받음
`openclaw_task_status`	작업 진행 상황 확인 및 결과 수신
`openclaw_task_list`	필터링을 사용하여 모든 작업 나열
`openclaw_task_cancel`	보류 중인 작업 취소

다중 인스턴스 모드

단일 MCP 서버에서 여러 OpenClaw 게이트웨이를 조정하세요. 하나의 브리지로 여러 Claw를 관리하세요. 프로덕션, 스테이징, 개발 등 원하는 이름으로 요청을 라우팅할 수 있습니다(lobster-supreme 및 the-claw-abides와 같은 이름도 완벽하게 유효합니다).

┌──────────────────────────────────────────────────────────────────────┐
│                        Claude.ai / Claude Desktop                    │
│                              (MCP Client)                            │
└──────────────────────┬───────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     OpenClaw MCP Bridge Server                        │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  Instance     │  │  Instance     │  │  Instance     │              │
│  │  Registry     │  │  Resolver     │  │  Validator    │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                  │                        │
│  ┌──────┴─────────────────┴──────────────────┴───────┐               │
│  │              Per-Instance OpenClaw Clients          │              │
│  │     (separate auth, timeout, URL per instance)     │              │
│  └────────┬──────────────┬──────────────┬────────────┘               │
└───────────┼──────────────┼──────────────┼────────────────────────────┘
            │              │              │
            ▼              ▼              ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  🦞 prod     │ │  🦞 staging  │ │  🦞 dev      │
   │  (default)   │ │              │ │              │
   │  :18789      │ │  :18789      │ │  :18789      │
   │  OpenClaw GW │ │  OpenClaw GW │ │  OpenClaw GW │
   └──────────────┘ └──────────────┘ └──────────────┘

설정

OPENCLAW_INSTANCES='[
  {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
  {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
  {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
]'

사용법

모든 도구는 특정 게이트웨이를 대상으로 하는 선택적 instance 매개변수를 허용합니다:

# Chat with staging instance
openclaw_chat message="Deploy status?" instance="staging"

# Check health of prod
openclaw_status instance="prod"

# List all configured instances
openclaw_instances

# Async task targeting dev
openclaw_chat_async message="Run tests" instance="dev"

instance가 생략되면 기본 인스턴스가 사용됩니다. 각 인스턴스는 고유한 인증 토큰, 시간 제한 및 URL을 가지며 완전히 격리됩니다.

주요 기능

무중단 업그레이드 — 기존 단일 인스턴스 배포는 구성 변경 없이 작동합니다.
인스턴스별 격리 — 별도의 인증 토큰, 시간 제한 및 URL 사용.
동적 라우팅 — Claude가 요청별로 올바른 인스턴스를 선택합니다.
작업 추적 — 비동기 작업이 대상 인스턴스를 기억합니다.
보안 — 토큰은 openclaw_instances를 통해 노출되지 않습니다.

전체 참조는 구성 — 다중 인스턴스 모드를 참조하세요.

문서

설치 — Claude Desktop 및 Claude.ai 설정
구성 — 환경 변수 및 옵션
배포 — Docker 및 프로덕션 설정
위협 모델 — Claude가 트리거할 수 있는 것과 없는 것, 신뢰 경계 및 공격 표면
로깅 — 기록되는 내용, 위치 및 절대 기록되지 않는 내용
개발 — 기여 및 도구 추가
보안 — 보안 정책 및 모범 사례

보안

⚠️ 프로덕션 환경에서는 항상 인증을 활성화하세요!

# Generate secure client secret
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)

# Run with auth enabled
AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
  openclaw-mcp --transport sse

액세스를 제한하려면 CORS를 구성하세요:

CORS_ORIGINS=https://claude.ai,https://your-app.com

모든 보안 옵션은 구성을 참조하세요.

요구 사항

Node.js ≥ 20
HTTP API가 활성화된 상태로 실행 중인 OpenClaw 게이트웨이:

// openclaw.json
{ "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }

라이선스

MIT

작성자

Tomáš Grasl 제작

openclaw-mcp