OpenClaw 스타일 AI 에이전트 직접 구축하기

OpenClaw의 정체

OpenClaw는 자체 호스팅하는 개인용 AI 에이전트입니다. 사용자의 서버에서 직접 실행하며, 기존에 사용하는 채팅 앱과 연결할 수 있습니다. 이 에이전트는 셸 명령어를 실행하고, 브라우저를 제어하며, 파일을 읽고 쓰고, 사용자가 보낸 메시지에 따라 동작합니다. MIT 라이선스를 따르는 로컬 우선(local-first) 소프트웨어이며, 2026년 중반 기준으로 GitHub에서 380,000개 이상의 스타를 받아 해당 플랫폼에서 가장 많은 스타를 받은 프로젝트 중 하나입니다. 복잡한 겉모습과 달리, 실제로는 합리적인 방식으로 연결된 몇 가지 작은 구성 요소로 이루어져 있습니다. 이 글에서는 이러한 도구가 어떻게 구축되는지, 그리고 주의해야 할 위험 요소는 무엇인지 이해할 수 있도록 각 구성 요소를 살펴봅니다.

시작하기 전에 한 가지 경고를 드립니다. 이는 아래의 모든 설계 선택에 영향을 미칩니다. 2026년 3월, OpenClaw는 4일 동안 9개의 보안 취약점이 공개되었으며, 여기에는 10점 만점에 9.9점을 받은 치명적인 권한 상승 결함(CVE-2026-32922)이 포함되어 있었습니다. 이 프로젝트는 운영자인 사용자가 직접 보안을 강화하도록 설계되었습니다. 어떤 명령어든 실행할 수 있는 에이전트는 그 에이전트가 실행되는 서버의 보안 수준과 사용자가 설정한 제한 범위만큼만 안전합니다. 이 점을 염두에 두고 읽어 주시기 바랍니다.

게이트웨이 데몬: 단일 프로세스, 비공개 유지

중심에는 보통 게이트웨이라 불리는 단일 장기 실행 프로세스가 있습니다. 이것이 제어 평면 역할을 합니다. 메시지를 수신하고, 수행할 작업을 결정하며, 도구를 실행하고, 응답을 반환합니다. 다른 모든 구성 요소는 이 프로세스에 연결됩니다.

게이트웨이에서 가장 중요한 점은 수신 대기 위치입니다. OpenClaw는 기본적으로 127.0.0.1 루프백 주소에 바인딩하므로, 의도적으로 노출하지 않는 한 인터넷에서 접근할 수 없습니다. 이 상태를 유지하십시오. 이 프로세스는 명령을 실행하는 핵심 역할을 하므로, 게이트웨이가 노출되면 이를 발견한 누구에게나 서버에 대한 원격 거점을 제공하는 셈이 됩니다. 노트북에서 접근해야 할 때는 포트를 개방하는 대신 VPN이나 SSH 터널을 사용하십시오. 접근할 수 없는 포트는 누구도 공격할 수 없습니다.

채널 커넥터: 메시지 수신 및 응답 송신

개인용 에이전트는 사용 중인 애플리케이션에서 직접 대화할 수 있을 때 비로소 유용합니다. 이것이 바로 채널 커넥터의 역할입니다. 각 커넥터는 Telegram, WhatsApp, Slack, Discord와 같은 특정 플랫폼의 봇 API나 웹훅을 사용하여 해당 플랫폼과 통신합니다.

모든 커넥터의 구조는 동일합니다. 커넥터는 플랫폼에 봇을 등록하고, 플랫폼을 폴링하거나 플랫폼이 푸시하는 웹훅을 수신하여 들어오는 메시지를 받습니다. 그 후 해당 메시지를 게이트웨이로 전달하고, 게이트웨이의 응답을 동일한 API를 통해 다시 게시합니다. 커넥터는 얇은 변환 계층입니다. 커넥터는 "Telegram 메시지가 도착함"이라는 신호를 "에이전트를 위한 텍스트가 여기 있음"으로 변환하고, 다시 그 반대로도 변환합니다. 자체 커넥터를 구축하는 작업은 대부분 특정 플랫폼의 봇 문서를 읽고 해당 플랫폼의 메시지 형식을 게이트웨이의 형식에 매핑하는 과정으로 이루어집니다.

두뇌와 도구 루프

게이트웨이 내부에는 이 시스템을 단순 챗봇이 아닌 에이전트로 만드는 핵심 요소가 있습니다. 바로 루프입니다.

메시지가 도착하면 게이트웨이는 해당 메시지를 언어 모델로 전송합니다. 이때 모델이 사용할 수 있는 도구 목록도 함께 전달합니다. 모델은 메시지를 읽고 직접 답변할지, 아니면 도구를 호출할지 결정합니다. 모델이 도구를 호출하면 게이트웨이는 해당 도구를 실행하고 결과를 캡처하여 다시 모델로 보냅니다. 모델은 결과를 확인하고 다시 판단합니다. 이 과정은 모델이 더 이상 할 일이 없다고 판단하여 최종 답변을 생성할 때까지 반복됩니다.

이 루프가 에이전트의 핵심 개념이며, 에이전트가 채팅 앱에 있든 터미널에 있든 동일하게 작동합니다. 도구를 이 루프에 표준 방식으로 연결하는 방법은 Model Context Protocol을 통한 도구 연결에서 확인할 수 있으며, 모델 측면의 내용은 자체 하드웨어에서 모델 직접 실행하기를 통해 보완할 수 있습니다.

도구 모음은 핵심이자 위험 요소입니다

OpenClaw의 강력함은 도구에서 나옵니다. 셸 명령을 실행하는 도구, 브라우저를 제어하는 도구, 파일을 읽고 쓰는 도구가 그 예입니다. 앞서 언급한 루프에 이러한 도구에 대한 접근 권한을 부여하면, 사용자가 키보드로 할 수 있는 거의 모든 작업을 수행할 수 있습니다. 이러한 확장성이 이 제품의 전부이자, 동시에 모든 위험의 원인이기도 합니다.

채팅 앱을 통해 전달되는 지시에 따라 임의의 명령을 실행할 수 있는 에이전트는 거대한 공격 표면을 형성합니다. 잘못된 지시, 브라우저 도구가 방문하는 웹 페이지에 숨겨진 프롬프트 인젝션 공격, 또는 2026년 3월의 결함과 같은 버그는 "내 일정 읽어줘"라는 명령을 "내 파일 삭제해"로 변질시킬 수 있습니다. 따라서 제한 사항은 선택 사항이 아닙니다. 에이전트는 sudo 권한이 없는 전용 비특권 사용자로 실행하여 침해 시 권한 상승이 불가능하도록 해야 합니다. 위험한 도구는 승인 단계를 거치도록 설정하여 에이전트가 파괴적인 작업을 수행하기 전에 사용자에게 확인을 요청하게 하십시오. 도구 실행을 샌드박스화하여 제어 불능 상태의 명령을 격리하십시오. 모델의 API 키를 분리하여 유출 시 공격자가 계정을 탈취하지 못하도록 하십시오. 같은 서버에 존재하는 다른 비밀 정보에 대해서도 고려해야 합니다. Vaultwarden의 실제 취약점은 암호화 방식이 아니라 관리자 토큰과 백업 파일이며, 셸 접근 권한을 가진 에이전트는 이 두 가지 모두에 접근할 수 있기 때문입니다.

셸 명령을 실행하는 기능을 노출하기 전에, 기본 사항을 신중하게 검토하십시오. 자신의 서버를 위한 체크리스트를 생성하고, 다음 순서대로 수행하십시오.

비특권 사용자 관련 내용은 비특권 사용자로 서비스 실행하기에서 자세히 다루며, 실제 프로젝트를 위한 전체 안전 설정 가이드는 VPS에서 안전하게 OpenClaw 실행하기에서 확인할 수 있습니다.

일반 파일로 저장하는 메모리

대부분의 사용자는 에이전트의 메모리가 데이터베이스에 저장될 것이라고 예상합니다. 하지만 OpenClaw는 그렇지 않습니다. OpenClaw는 메모리를 디스크상의 일반 Markdown 파일로 저장하며, 이러한 방식은 채택할 가치가 충분합니다.

파일은 단순합니다. 마이그레이션할 스키마도, 계속 실행해야 할 서비스도, 새로 배워야 할 쿼리 언어도 없습니다. 파일은 직접 확인이 가능합니다. 폴더를 열어 에이전트가 사용자에 대해 무엇을 알고 있는지 정확히 읽을 수 있고, 파일을 수정하여 잘못된 메모를 바로잡거나 파일을 삭제하여 메모를 제거할 수 있습니다. 또한 이식성이 뛰어납니다. 에이전트를 새 서버로 옮기는 작업은 단순히 디렉터리를 복사하는 것으로 충분하기 때문입니다. 1인용 개인 에이전트의 경우 텍스트 파일 폴더만으로도 충분하며, 시스템 전체를 이해하기 쉽게 유지해 줍니다.

Skills: 기능을 추가하는 이식성 있는 방법

내장 도구 외에도 OpenClaw는 커뮤니티가 핵심 코드를 수정하지 않고도 기능을 확장할 수 있도록 이식성 있는 skill 형식을 사용합니다. skill은 에이전트에게 새로운 작업을 가르치는 명령어와 때로는 코드가 포함된 독립적인 번들입니다. 에이전트는 작업이 호출될 때 skill을 로드합니다. 웹 검색은 사용자들이 가장 먼저 추가하는 기능이며, 해당 skill을 직접 운영하는 SearXNG 인스턴스로 지정하면 상용 검색 API를 거치지 않으면서도 skill의 신뢰 경계가 어디에 있는지 명확히 할 수 있습니다. skill이 반환하는 모든 결과는 타인이 작성한 텍스트이기 때문입니다.

이러한 형식의 가치는 기능을 공유할 수 있다는 점에 있습니다. 누군가 특정 작업을 위한 skill을 작성하여 배포하면, 다른 사용자들이 이를 가져와 바로 사용할 수 있습니다. 이러한 편리함은 양날의 검이기도 합니다. skill은 에이전트가 주저 없이 실행하는 타인의 코드이기 때문입니다. 따라서 직접 작성하지 않은 모든 코드는 로드하기 전에 직접 호스팅하는 보안 스캐너를 통과시키는 것이 좋습니다. 에이전트를 직접 구축한다면, 작고 명확한 확장 형식을 초기에 정의해 두는 것이 나중에 모든 기능을 핵심 코드에 하드코딩하는 수고를 덜어줍니다.

직접 모델 가져오기

OpenClaw는 모델에 구애받지 않습니다. 자체 언어 모델을 포함하여 배포하지 않습니다. 대신 사용자가 선택한 모델에 연결하며, 이는 호스팅된 API일 수도 있고 직접 실행하는 모델일 수도 있습니다.

이러한 구분은 비용, 개인정보 보호, 제어 측면에서 중요합니다. 호스팅된 API는 하드웨어를 관리할 필요 없이 가장 강력한 모델을 제공하지만, 토큰당 비용이 발생하며 프롬프트가 서버 외부로 전송됩니다. Ollama와 같은 도구로 직접 호스팅하는 모델은 모든 메시지를 자신의 서버 내에 유지하며, 하드웨어 및 전력 비용만 발생하지만 더 작거나 느린 모델을 사용해야 할 수도 있습니다. 많은 사용자가 이 두 방식을 혼합하여 사용합니다. 에이전트를 완전히 비공개로 유지하려면 VPS에서 모델 직접 호스팅하기가 마지막 격차를 해소하는 방법이며, Hermes Agent 또한 비교해 볼 만한 또 다른 자체 호스팅 에이전트입니다.

직접 구축해야 할까요?

이 모든 것을 직접 구축할 수 있습니다. 구성 요소는 특별할 것이 없습니다. 데몬, 몇 가지 채팅 커넥터, 모델과 도구 루프, Markdown 폴더, 그리고 플러그인 형식이 전부입니다. 이러한 요소를 이해하는 것은 매우 유용합니다. 사용하는 모든 에이전트의 원리를 파악하게 해주며, 위험이 어디에 존재하는지 정확히 알려주기 때문입니다.

대부분의 사용자에게 정직한 답은 직접 다시 만들기보다 실제 시스템을 실행하고 보안을 강화하는 것이다. OpenClaw는 이미 커넥터, 루프, 스킬 형식을 해결했으며 실제 보안 검토도 거쳤다. 직접 올바르게 처리해야 하는 부분은 자체 서버에서의 설정과 보안 강화이므로, 여기에 시간을 쓰는 편이 낫다. 먼저 학습 경로를 원한다면 에이전트 소스 코드를 아무 배경 지식 없이 읽기보다 개념을 단계별로 익혀 나가는 방식이 더 효과적이다. 각 단계에서 실제로 구축한 결과물이 하나씩 남기 때문이다. 학습을 위해 작은 것을 하나 구축한다. 사용을 위해 실제 시스템을 실행하고 보안을 강화한다.

일반적인 기반 지식은 VPS에서 나만의 AI 에이전트 구축하기에 있으며, Claude를 활용한 에이전트 구축에서는 특정 모델을 두뇌로 사용하여 동일한 개념을 설명합니다.

FAQ

OpenClaw와 같은 에이전트를 만드는 것이 어렵습니까?

개별 구성 요소는 어렵지 않습니다. 게이트웨이 프로세스, 채팅 커넥터, 모델 및 도구 루프, 그리고 파일 폴더는 각각 독립적으로 보면 간단합니다. 어려운 점은 이를 안전하게 구현하는 것입니다. 채팅 메시지에서 셸 명령을 실행하는 에이전트는 심각한 보안 표면을 가지며, 샌드박싱, 권한 설정, 비특권 사용자 설정 등을 올바르게 구현하는 것이 기능을 연결하는 것보다 더 많은 노력이 필요합니다.

OpenClaw는 왜 메모리를 데이터베이스 대신 Markdown 파일로 저장합니까?

단일 사용자용 개인 에이전트에게는 파일만으로도 충분하며 훨씬 간단하기 때문입니다. 실행해야 할 데이터베이스 서비스가 없고, 메모리를 직접 읽고 수정하기 쉬우며, 에이전트를 다른 서버로 옮기는 작업도 디렉터리를 복사하는 것만으로 가능합니다. 데이터베이스는 더 큰 규모에서 가치를 발휘하며, 여기에는 적합하지 않습니다.

개인 AI 에이전트에서 가장 위험한 부분은 무엇입니까?

셸 명령 실행, 브라우저 제어, 파일 쓰기와 같이 에이전트가 행동할 수 있게 해주는 도구들입니다. 이것들은 에이전트를 만드는 이유인 동시에 사용자에게 피해를 줄 수 있는 원인이기도 합니다. 9.9점의 치명적인 취약점을 포함하여 4일 동안 9개의 문제가 발견된 OpenClaw의 2026년 3월 보안 사고는 도구 계층을 신중하게 다뤄야 한다는 가장 명확한 근거입니다. 비특권 사용자로 실행하고, 파괴적인 작업은 제한하며, 실행 환경을 샌드박스화하십시오.

에이전트를 만들기 위해 자체 언어 모델이 필요합니까?

아닙니다. OpenClaw와 같은 에이전트는 모델에 구애받지 않으므로 원하는 모델을 연결할 수 있습니다. 가장 강력한 모델을 위한 호스팅된 API를 사용할 수도 있고, 완전한 개인 정보 보호를 위해 직접 실행하는 모델을 사용할 수도 있습니다. Ollama를 사용하여 자체 호스팅하면 더 작은 모델을 실행하는 대신 모든 메시지를 자신의 서버에 보관할 수 있습니다.