[리서치] OpenClaw 아키텍처: Gateway에서 Tool·Skill·Plugin까지
이 글은 2026년 9월 1일의 OpenClaw 공식 문서와 공식 저장소를 기준으로 작성했다. OpenClaw는 빠르게 바뀌는 프로젝트이므로 세부 API와 기본값은 링크한 최신 문서를 다시 확인해야 한다.
OpenClaw를 처음 보면 메시징 채널이 많은 개인 AI assistant처럼 보인다. 하지만 서버형 agent를 설계하는 관점에서는 Gateway가 상태와 실행을 소유하고, agent loop가 한 turn을 처리하며, Tool·Skill·Plugin이 서로 다른 방식으로 capability를 확장하는 runtime으로 보는 편이 더 정확하다.
이 구분을 이해하면 “프롬프트에 지시를 더 쓸까?”, “typed tool을 만들까?”, “plugin으로 lifecycle에 개입할까?”를 같은 문제로 취급하지 않게 된다.
먼저 결론: OpenClaw는 model이 아니라 runtime이다
LLM provider는 OpenClaw가 사용하는 구성요소 중 하나다. OpenClaw가 더 넓게 책임지는 범위는 다음과 같다.
- 여러 client와 channel의 요청을 받는 Gateway
- 요청을 어느 agent와 session으로 보낼지 결정하는 routing
- context 구성, model inference, tool execution과 응답을 잇는 agent loop
- session history, queue, streaming과 persistence
- workspace context와 Skill loading
- Tool, Plugin, Hook과 automation을 통한 capability 확장
공식 문서도 embedded agent runtime이 model discovery, tool wiring, prompt assembly, session management와 channel delivery를 하나의 runtime surface로 소유한다고 설명한다. 즉 OpenClaw를 도입한다는 것은 특정 model을 선택하는 것보다 model 주위의 실행 계약을 채택하는 일에 가깝다. (Agent runtime)
Gateway: 장시간 살아 있는 control plane
Gateway architecture에 따르면 하나의 long-lived Gateway가 messaging surface와 client 연결을 소유한다. CLI, web UI와 app은 typed WebSocket API로 연결되고, node도 같은 server에 자신의 role과 capability를 선언한다.
Gateway의 책임은 단순 reverse proxy보다 넓다.
- inbound frame 검증과 인증
- client, channel, node 연결 관리
- agent run 접수와 streaming event 전달
- session routing과 상태 보관
- health, presence, heartbeat와 automation event 발행
이 구조의 장점은 client가 각자 agent state를 들고 있지 않아도 된다는 점이다. 여러 UI가 같은 session에 붙더라도 기준 상태는 Gateway에 있다. 반대로 Gateway를 외부에 노출하면 agent가 가진 tool 권한까지 공격 표면에 포함되므로, 네트워크 접근과 tool 권한을 함께 설계해야 한다.
Agent loop: 한 turn이 action과 reply가 되는 과정
Agent loop 문서는 한 run을 다음 흐름으로 설명한다.
message intake
→ session resolve
→ workspace / skills / context assembly
→ model inference
→ tool execution
→ assistant · tool · lifecycle streaming
→ reply shaping
→ transcript persistence
중요한 점은 이 흐름이 session 단위로 직렬화된다는 것이다. 같은 session에서 두 run이 동시에 history를 덮어쓰거나 tool 결과의 순서를 뒤섞지 않도록 session lane과 writer claim이 경계를 만든다.
Agent framework를 평가할 때 model 응답만 보면 이 부분을 놓친다. 실제 동작은 model뿐 아니라 context assembly, tool schema, hook, queue mode, timeout과 persistence의 합성 결과다.
Workspace와 Skill: 실행 코드가 아니라 판단의 문맥
Agent마다 workspace가 있고, AGENTS.md 같은 bootstrap/context 파일과 Skill이 prompt 구성에 참여한다. Skills 문서는 Skill을 YAML frontmatter와 Markdown body를 가진 SKILL.md instruction pack으로 정의한다.
Skill은 tool을 새로 만들지 않는다. 이미 존재하는 tool을 언제, 어떤 순서와 제약으로 사용할지 가르친다. 예를 들어 날씨 조회 tool이 이미 있다면 Skill은 다음을 담을 수 있다.
- 어떤 요청이 이 capability의 범위인지
- 먼저 확인해야 할 값이 무엇인지
- 허용·금지되는 실행 패턴
- 실패했을 때의 fallback과 사용자 확인 규칙
Workspace, managed directory, bundled package와 plugin 등 여러 위치에서 Skill을 불러올 수 있고 같은 이름이 충돌하면 loading precedence가 적용된다. 따라서 Skill은 단순 문서 파일이 아니라 배포 위치와 override 정책을 가진 prompt-side dependency다.
Tool, Skill, Plugin을 구분하는 기준
Capabilities overview는 세 경계를 명확하게 나눈다.
| 구성요소 | 해결하는 문제 | model이 보는 형태 | 적합한 사례 |
|---|---|---|---|
| Tool | 외부 세계에 실제 action을 수행 | typed function schema | API 호출, 파일 변경, 검색, 메시지 전송 |
| Skill | 기존 capability를 사용하는 절차와 판단 기준 | 필요할 때 load되는 instruction | routing 규칙, workflow, review rubric |
| Plugin | runtime에 새로운 capability와 lifecycle을 추가 | 등록한 tool·hook·provider 등의 결과 | custom integration, hook, channel, provider |
선택 기준은 비교적 단순하다.
- Agent가 실제로 무언가를 해야 한다면 Tool이다.
- Tool은 있지만 사용하는 법이 복잡하다면 Skill이다.
- 코드, credential, lifecycle hook이나 packaging이 필요하면 Plugin이다.
이 세 가지를 한곳에 몰아넣으면 유지보수가 어려워진다. 긴 운영 규칙을 tool description에 전부 넣으면 매 turn의 schema 비용이 커지고, 반대로 API validation을 Skill에만 적으면 deterministic하게 막을 수 없다.
Plugin과 Hook: core를 수정하지 않고 runtime에 개입한다
Plugin 개발 문서에 따르면 Plugin은 core를 수정하지 않고 tool, channel, provider와 hook 같은 capability를 추가한다. Tool plugin은 typed tool을 등록하고, 더 복합적인 plugin은 여러 capability를 함께 제공할 수 있다.
Plugin hooks는 agent run과 tool lifecycle에 개입하는 typed handler다. 예를 들어 다음 위치를 관찰하거나 변경할 수 있다.
- model 선택 또는 prompt build 전
- tool call 전후
- message 수신·전송 전후
- session과 Gateway lifecycle
- tool result가 transcript에 저장되기 전
Hook은 business action 자체보다 횡단 관심사에 잘 맞는다. 공통 logging, argument 보정, 정책 gate와 delivery metadata 주입이 대표적이다. 다만 callback은 durable queue가 아니므로, 반드시 보존되어야 하는 event 처리까지 단순 hook에 맡기면 안 된다.
Session: 대화 history 이상의 routing boundary
Session management에서 session은 inbound source에 따라 정해지는 실행·상태 경계다. DM, group, room, cron과 webhook은 서로 다른 기본 routing 규칙을 가진다.
Session은 다음 질문의 답을 결정한다.
- 어느 history와 context를 이어받는가?
- 동시에 들어온 run을 어느 queue에서 직렬화하는가?
- 어느 사용자·channel의 상태와 격리되는가?
- background task 결과가 어디로 돌아가는가?
특히 다중 사용자 환경에서 모든 DM을 하나의 main session으로 합치면 context가 섞일 수 있다. 서버형 agent에서는 session key 설계를 편의 기능이 아니라 tenant·conversation isolation 문제로 봐야 한다.
Automation: “나중에 실행”도 Gateway의 책임이다
Automations 문서에 따르면 scheduler는 Gateway process 안에서 job을 보존하고 agent를 깨우며 결과를 channel이나 webhook으로 전달한다. Model이 시간을 세는 것이 아니다.
따라서 예약·조건부 요청에는 두 종류의 상태가 생긴다.
- 실행해야 할 시점과 delivery를 보존하는 scheduler state
- 실행 시 판단과 tool 사용을 이어가는 agent/session state
두 상태를 섞지 않아야 재시작, timeout, 중복 실행과 delivery 실패를 다룰 수 있다. “prompt에 나중에 해 달라고 쓰기”와 automation은 전혀 다른 보장 수준을 가진다.
보안은 sandbox 하나로 끝나지 않는다
OpenClaw의 sandbox·tool policy·elevated 구분은 세 질문을 분리한다.
- Sandbox: tool이 어디에서 실행되는가?
- Tool policy: 어떤 tool이 model에게 보이고 호출 가능한가?
- Elevated: sandboxed
exec가 제한적으로 host에서 실행될 수 있는가?
서버형 agent에서 중요한 것은 최소 권한의 tool surface다. Skill에 “이 tool을 쓰지 말라”고 쓰는 것은 soft guidance일 뿐이다. 실제 차단은 tool policy와 sandbox 같은 runtime enforcement가 담당해야 한다.
아키텍처를 읽고 남는 판단 기준
OpenClaw의 핵심은 capability가 많다는 사실보다 판단, 행동, lifecycle과 상태의 경계를 각각 확장할 수 있다는 점이다.
- 판단 절차는 Skill
- 외부 action은 Tool
- runtime extension은 Plugin
- 횡단 lifecycle 제어는 Hook
- 대화와 동시성의 경계는 Session
- 지연 실행은 Automation
- 이들을 연결하고 상태를 소유하는 곳은 Gateway
다음 글에서는 이 구분을 실제 서버형 디바이스 assistant PoC에 어떻게 적용했는지, 하나의 tool과 여러 Skill을 조합한 이유와 멀티턴·event normalization에서 생긴 설계 trade-off를 정리한다.