OpenClaw RPC adapter로 외부 CLI 연결하기

외부 CLI 도구를 프로젝트에 통합해 본 적이 있다면, 프로세스 관리와 통신 방식이 제각각이라 고생했던 경험이 있을 거예요. 도구마다 실행 방식이 다르면 코드가 금방 복잡해지고 유지보수도 힘들어지죠. OpenClaw는 이 문제를 해결하기 위해 JSON-RPC를 기반으로 외부 CLI를 통합합니다.

어떤 방식으로 외부 도구를 연결하고 관리하는지, 가장 효율적인 패턴 두 가지를 정리해 드릴게요.

필요한 것

시작하기 전에 소스 문서에서 언급된 다음 사항들이 준비되어야 합니다.

• OpenClaw 설치 환경
• signal-cli (Pattern A 사용 시)
• imsg (Pattern B 사용 시, 레거시 환경)

빠른 시작

OpenClaw는 외부 CLI와의 통신을 위해 두 가지 주요 패턴을 지원합니다. 환경에 맞는 방식을 선택해 보세요.

패턴 A: HTTP daemon (signal-cli)

signal-cli처럼 HTTP 기반의 JSON-RPC를 사용하는 방식입니다. 이 방식은 별도의 데몬 프로세스로 실행됩니다.

• 이벤트 스트림: SSE (/api/v1/events)를 통해 실시간 이벤트를 받습니다.
• 상태 확인: /api/v1/check 엔드포인트로 헬스 체크를 수행합니다.
• 자동 관리: channels.signal.autoStart=true로 설정하면 OpenClaw가 직접 프로세스의 생명주기를 관리합니다.

패턴 B: stdio child process (imsg)

별도의 TCP 포트나 데몬 없이, stdio를 통해 통신하는 방식입니다. 주로 레거시 iMessage 통합에 사용됩니다.

참고: 새로운 iMessage 설정을 원하신다면 BlueBubbles를 사용하는 것을 추천해요.

OpenClaw가 imsg rpc를 자식 프로세스로 실행하며, 줄바꿈으로 구분된 JSON 객체를 stdin/stdout으로 주고받습니다. 주요 메서드는 다음과 같습니다.

• watch.subscribe: 알림 구독 (메서드: "message")
• watch.unsubscribe: 구독 해제
• send: 메시지 전송
• chats.list: 상태 확인 및 진단

가장 좋은 방법은 표시 이름(display strings) 대신 chat_id와 같은 고유 ID를 사용하는 것입니다. 그래야 연결이 끊겨도 안정적으로 식별할 수 있습니다.

문제 해결

연결 과정에서 문제가 발생한다면 다음 두 가지를 먼저 확인해 보세요.

1. 프로세스 종료 및 재시작: RPC 클라이언트는 예기치 않게 프로세스가 종료될 경우 자동으로 재시작할 수 있도록 설계되어야 합니다. Gateway가 프로세스 소유권을 가지므로 프로바이더의 생명주기와 잘 연결되어 있는지 확인하세요.
2. 응답 시간 초과: 네트워크나 프로세스 부하로 인해 타임아웃이 발생할 수 있습니다. RPC 클라이언트 설정에서 적절한 타임아웃 값이 적용되어 있는지 확인이 필요합니다.

##结尾

설정 중에 막히는 부분이 있다면 AI Setup Assistant에게 물어보세요. 실시간으로 도움을 받을 수 있습니다.

다음 단계

• Signal 설정 및 엔드포인트 알아보기
• iMessage 레거시 설정 가이드
• BlueBubbles로 최신 iMessage 통합하기