OpenClaw 스타일 AI agent 구축 방법

OpenClaw의 실체

OpenClaw는 self-hosted 방식의 개인용 AI agent입니다. 사용자의 서버에서 실행하며, 기존에 사용하는 chat app과 연결할 수 있습니다. 이 agent는 shell command를 실행하고, browser를 제어하며, 파일을 읽고 쓸 수 있고, 전송된 message에 따라 동작합니다. MIT-license를 따르며 local-first 방식입니다. 2026년 중반 기준 GitHub stars가 380,000개를 넘었으며, 이는 platform 내에서 가장 많은 stars를 받은 프로젝트 중 하나임을 의미합니다. 겉으로 보기에는 복잡해 보이지만, 실제로는 합리적인 방식으로 연결된 소규모 부품들의 집합입니다. 이 포스트는 이러한 부품들을 살펴봄으로써, 이와 같은 도구가 어떻게 구축되는지, 그리고 주의해야 할 위험 요소가 무엇인지 설명합니다.

설계 방식에 영향을 미치는 중요한 경고를 먼저 전달합니다. 2026년 3월, OpenClaw는 4일 만에 9개의 security issue가 공개되었습니다. 여기에는 10점 만점에 9.9점을 받은 critical privilege-escalation flaw (CVE-2026-32922)가 포함되어 있습니다. 이 프로젝트는 운영자인 사용자가 직접 hardening하도록 설계되었습니다. 모든 command를 실행할 수 있는 agent의 안전성은 실행되는 환경과 설정된 제한 사항에 달려 있습니다. 내용을 읽을 때 이 점을 유념하십시오.

gateway daemon: 단일 프로세스 및 프라이버시 유지

중심에는 보통 gateway라고 불리는 단일 long-running process가 있습니다. 이것이 control plane 역할을 합니다. message를 수신하고, 동작을 결정하며, tool을 실행하고, reply를 다시 보냅니다. 다른 모든 요소는 이 프로세스에 연결됩니다.

gateway에서 가장 중요한 사실은 listening 위치입니다. 기본적으로 OpenClaw는 loopback address인 127.0.0.1에 bind되므로, 사용자가 직접 노출시키지 않는 한 internet에서 접근할 수 없습니다. 이 상태를 유지하십시오. gateway는 command를 실행하는 핵심 프로세스이므로, 만약 노출될 경우 발견하는 누구에게나 server에 대한 remote foothold를 제공하게 됩니다. laptop에서 접속해야 할 때는 port를 개방하는 대신 VPN이나 SSH tunnel을 사용하십시오. 접근할 수 없는 port는 공격받을 수 없습니다.

channel connectors: message 수신 및 reply 송신

개인용 agent는 이미 사용 중인 app을 통해 대화할 수 있어야 유용합니다. channel connector가 이 역할을 수행합니다. 각 connector는 Telegram, WhatsApp, Slack, Discord와 같은 특정 platform의 bot API 또는 webhooks를 사용하여 해당 platform과 통신합니다.

모든 connector의 구조는 동일합니다. connector가 platform에 bot을 등록하고, incoming message를 수신(platform을 polling하거나 platform이 push하는 webhook을 수신)한 뒤, 해당 message를 gateway에 전달합니다. 그 후 gateway의 reply를 동일한 API를 통해 다시 게시합니다. connector는 단순한 translation layer입니다. "Telegram message가 도착함"을 "agent를 위한 text"로 변환하고, 그 반대 과정도 수행합니다. 직접 구축하는 것은 특정 platform의 bot documentation을 읽고 message format을 gateway의 format에 매핑하는 작업입니다.

brain 및 tool loop

gateway 내부에는 이 프로세스를 chatbot이 아닌 agent로 만드는 부분이 있습니다. 이것은 loop 구조입니다.

message가 도착하면, gateway는 이를 language model에 전달하며 이때 model이 사용할 수 있는 tool 목록을 함께 보냅니다. model은 message를 읽고 직접 답변할지, 혹은 tool을 호출할지 결정합니다. tool을 호출하면 gateway가 해당 tool을 실행하고, 결과를 캡처하여 model에 다시 보냅니다. model은 결과를 확인하고 다시 결정합니다. 이 과정은 model이 더 이상 할 일이 없어 최종 reply를 생성할 때까지 반복됩니다.

이 loop가 agent의 핵심 개념이며, agent가 chat app에서 동작하든 terminal에서 동작하든 동일한 loop를 사용합니다. tool을 이 loop에 표준 방식으로 연결하는 방법에 대해서는 connecting tools through the Model Context Protocol를, model 측면에 대해서는 running the model itself on your own hardware를 참고하십시오.

tool set: 핵심 기능이자 위험 요소

tool은 OpenClaw를 강력하게 만드는 요소입니다. shell command를 실행하는 tool, browser를 제어하는 tool, 파일을 읽고 쓰는 tool 등이 있습니다. 위에서 설명한 loop에 이러한 권한을 부여하면, 사용자가 keyboard로 할 수 있는 거의 모든 일을 수행할 수 있습니다. 이러한 확장성이 제품의 핵심 가치인 동시에 전체 리스크이기도 합니다.

chat app에서 전달된 instruction에 따라 모든 command를 실행할 수 있는 agent는 매우 넓은 attack surface를 가집니다. 잘못된 instruction, browser tool이 방문하는 webpage에 숨겨진 prompt-injection attack, 또는 2026년 3월에 발생한 bug와 같은 결함은 "내 일정 읽기"를 "내 파일 삭제하기"로 바꿀 수 있습니다. 따라서 제한 사항 설정은 선택 사항이 아닙니다. agent는 sudo 권한이 없는 전용 unprivileged user로 실행하여 compromise 발생 시 권한 상승을 방지하십시오. 파괴적인 동작을 하기 전에 agent가 승인을 요청하도록 위험한 tool에는 approval step을 설정하십시오. runaway command가 격리되도록 tool execution을 sandbox 하십시오. model의 API key를 격리하여 leak 발생 시 공격자가 계정을 탈취하지 못하게 하십시오.

shell command를 실행하는 요소를 노출하기 전에, 기본 사항을 철저히 수행하십시오. 본인의 환경을 위한 checklist를 아래와 같이 생성하여 처음부터 끝까지 수행하십시오.

unprivileged-user 설정에 대한 상세 내용은 running services as an unprivileged user에 있으며, 실제 프로젝트를 위한 전체 safe-setup 가이드는 running OpenClaw safely on a VPS에 있습니다.

plain files 형태의 memory

대부분의 사람은 agent의 memory가 database에 저장될 것이라고 예상합니다. OpenClaw는 그렇지 않습니다. OpenClaw는 memory를 disk에 plain Markdown files 형태로 저장하며, 이 방식은 권장할 만합니다.

파일은 단순합니다. migration할 schema가 없고, 계속 실행 중이어야 하는 service가 없으며, 별도의 query language를 배울 필요도 없습니다. 또한 검사가 용이합니다. 폴더를 열어 agent가 사용자에 대해 무엇을 알고 있는지 정확히 읽을 수 있고, 파일을 수정하여 잘못된 정보를 바로잡거나 파일을 삭제하여 memory를 지울 수 있습니다. 또한 이식성도 좋습니다. agent를 새로운 server로 옮기는 것은 단순히 디렉토리를 복사하는 일이기 때문입니다. 단일 사용자용 개인 agent에게는 텍스트 파일로 구성된 폴더만으로 충분하며, 이는 시스템 전체를 이해하기 쉽게 유지해 줍니다.

Skills: 능력을 추가하는 이식 가능한 방법

내장된 tool 외에도, OpenClaw는 커뮤니티가 core를 변경하지 않고도 기능을 확장할 수 있도록 이식 가능한 skill format을 사용합니다. skill은 agent에게 새로운 task를 가르치는 instruction과 (경우에 따라) code가 포함된 self-contained bundle입니다. agent는 task 수행 시 필요한 경우 skill을 로드합니다.

이러한 format의 장점은 능력을 공유할 수 있다는 점입니다. 누군가 특정 작업을 위한 skill을 작성하여 게시하면, 다른 사용자들이 이를 바로 사용할 수 있습니다. 직접 agent를 구축한다면, 초기 단계에 작고 명확한 extension format을 정의함으로써 나중에 모든 기능을 core에 hard-coding해야 하는 상황을 방지할 수 있습니다.

Bring your own model

OpenClaw는 model-agnostic입니다. 자체 language model을 포함하고 있지 않습니다. 대신 사용자가 선택한 모델에 연결하며, 이는 hosted API이거나 직접 실행하는 model일 수 있습니다.

이 구분은 비용, privacy, control 측면에서 중요합니다. hosted API를 사용하면 하드웨어 관리 없이 강력한 model을 사용할 수 있지만, token당 비용이 발생하며 prompt가 server를 떠나게 됩니다. Ollama와 같은 도구로 실행하는 self-hosted model은 모든 message를 자신의 box에 유지하며, 더 작거나 느린 model을 실행하는 비용(하드웨어 및 전력)만 발생합니다. 많은 사용자가 이 두 방식을 혼용합니다. agent를 완전히 프라이빗하게 유지하고 싶다면, self-hosting the model on your VPS가 마지막 간극을 메워주는 방법이며, Hermes Agent는 비교해 볼 만한 또 다른 self-hosted agent입니다.

직접 구축해야 하는가?

이 모든 것을 직접 구축할 수 있습니다. 구성 요소들은 생소한 것이 아닙니다. daemon, 몇 개의 chat connector, model-and-tools loop, Markdown 폴더, 그리고 plugin format입니다. 이 요소들을 이해하는 것은 매우 유용합니다. 사용하게 될 모든 agent의 구조를 명확히 알 수 있고, 위험이 어디에 있는지 정확히 파악할 수 있기 때문입니다.

하지만 대부분의 사람에게 정직한 답변은, 직접 재발명하기보다는 실제 제품을 실행하고 hardening하는 것입니다. OpenClaw는 이미 connector, loop, skill format 문제를 해결했으며, 실제 보안 검증을 거쳤습니다. 사용자의 노력은 본인이 직접 완벽하게 수행해야 하는 부분, 즉 자신의 server에서의 setup과 hardening에 집중하는 것이 더 효율적입니다. 학습을 위해서는 작은 것을 직접 만들어 보십시오. 실제 사용을 위해서는 실제 제품을 실행하고 보안을 강화하십시오.

일반적인 기초는 building your own AI agent on a VPS에 있으며, building an agent with Claude는 특정 model을 brain으로 사용하는 동일한 개념을 보여줍니다.

FAQ

OpenClaw와 같은 agent를 만드는 것이 어려운가요?

개별 구성 요소는 어렵지 않습니다. gateway process, chat connector, model-and-tools loop, 그리고 파일 폴더는 각각 그 자체로 단순합니다. 어려운 점은 이를 안전하게 구현하는 것입니다. chat message를 통해 shell command를 실행하는 agent는 심각한 security surface를 가지므로, sandboxing, permissions, unprivileged-user 설정을 올바르게 구성하는 것이 기능을 연결하는 것보다 더 많은 노력이 필요합니다.

왜 OpenClaw는 database 대신 Markdown 파일로 memory를 저장하나요?

단일 사용자용 개인 agent에게는 파일 방식이 충분하며 훨씬 단순하기 때문입니다. 실행할 database service가 필요 없고, memory를 수동으로 읽고 수정하기 쉬우며, agent를 다른 server로 옮기는 것도 단순히 디렉토리를 복사하는 일입니다. database는 대규모 시스템에는 적합하지만, 여기에는 필요하지 않습니다.

개인용 AI agent에서 가장 위험한 부분은 무엇인가요?

agent가 동작하게 만드는 tool입니다. 즉, shell command 실행, browser 제어, 파일 쓰기입니다. 이것들이 agent를 만드는 이유인 동시에 사용자를 해칠 수 있는 이유입니다. 9.9점의 critical issue를 포함하여 4일 만에 9개의 issue가 발생한 OpenClaw의 2026년 3월 보안 이벤트는, tool layer를 주의 깊게 다뤄야 한다는 가장 명확한 근거입니다. unprivileged user로 실행하고, 파괴적인 동작에 승인 단계를 두며, execution을 sandbox 하십시오.

구축을 위해 개인용 language model이 필요한가요?

아니요. OpenClaw와 같은 agent는 model-agnostic하므로 원하는 모델을 연결하면 됩니다. 강력한 모델을 위해 hosted API를 사용할 수도 있고, 완전한 privacy를 위해 직접 실행하는 model을 사용할 수도 있습니다. Ollama를 통한 self-hosting은 더 작은 모델을 실행하는 비용으로 모든 message를 자신의 server에 유지할 수 있게 해줍니다.