OpenClaw 2026.3 실전 고급 가이드: 새 버전 핵심 기능과 모범 사례

OpenClaw 2026.3 버전(v2026.3.7-beta.1)은 200개가 넘는 버그를 수정했으며, 공식 CHANGELOG는 거의 1만 5천 자에 달합니다. 이전에는 다중 모델 라우팅 작업을 실행할 때 샌드박스 권한 설정에서 계속 오류가 발생했지만, 새 버전에서는 첫 실행부터 순조롭게 통과했습니다. 핵심 업데이트로는 컨텍스트 사용량을 약 30% 줄이는 ContextEngine, Bundle + Provider + Plugin의 3계층으로 재구성된 플러그인 시스템, OpenShell과 SSH를 포함한 세 가지 신규 샌드박스 백엔드가 있습니다.

이 글은 OpenClaw 시리즈의 34번째 글로, ContextEngine을 사용하는 방법, 3계층 플러그인 아키텍처를 설정하는 방법, 샌드박스 백엔드를 선택하는 기준 등 2026.3 버전의 실전 핵심을 정리합니다. 이전 버전에서 업그레이드한다면 이 글을 통해 마이그레이션 포인트를 빠르게 파악할 수 있습니다.

1. 버전 개요 — 2026.3에서 달라진 점

먼저 수치부터 살펴보겠습니다. v2026.3.7-beta.1 한 버전에서만 200개가 넘는 버그가 수정되었으며, 이후 여러 패치에서 누적된 수정 사항은 포함하지 않은 수치입니다. 공식 CHANGELOG는 거의 1만 5천 자에 달했고, 모두 읽어 본 뒤 크게 몇 가지 방향으로 정리할 수 있었습니다.

ContextEngine 업그레이드. 이전 OpenClaw의 컨텍스트 관리는 다소 단순했습니다. 입력한 만큼 모두 받아들이고, 감당할 수 있는지는 모델에 달려 있었습니다. 새 버전에는 일종의 ‘지능형 가지치기’ 메커니즘이 추가되었습니다. 현재 작업에 실제로 필요한 정보를 자동으로 식별하고 나머지는 잠시 보류합니다. 제가 테스트한 결과, 동일한 50회 대화의 복잡한 작업에서 컨텍스트 사용량이 약 30% 줄었습니다.

플러그인 체계 재구성. 가장 큰 변화입니다. 기존 Skills 단일 계층 구조가 Bundle + Provider + Plugin의 3계층으로 바뀌었습니다. 쉽게 말해 플러그인을 더 모듈화한 것입니다. 이전에는 하나의 기능을 Codex에서 Claude로 옮기려면 설정을 대폭 수정해야 할 수 있었지만, 이제는 Provider만 바꾸고 핵심 로직은 그대로 둘 수 있습니다. 3장에서 설정 방법을 자세히 다룹니다.

샌드박스 백엔드 다양화. 이전에는 사실상 Docker에 종속되어 있었지만 이제 OpenShell(mirror 및 remote 모드 지원)과 SSH sandbox가 추가되었습니다. Mac 사용자이거나 Docker를 설치하고 싶지 않다면 로컬 shell을 직접 사용해 훨씬 빠르게 시작할 수 있는 OpenShell mirror 모드가 좋은 선택입니다.

사람과 AI의 협업 워크플로 강화. 흥미로운 부분입니다. 새 버전은 완전 자동화만 추구하기보다 human-in-the-loop를 강조합니다. 간단히 말하면 AI가 작업 도중 멈춰 방향이 맞는지 묻고, 사용자가 확인하면 계속 진행합니다. 처음에는 별로 필요 없는 기능이라고 생각했지만 몇 번 사용해 보니 실수를 확실히 줄일 수 있었습니다.

그리고 쉽게 지나칠 수 있는 변경 사항으로 SELinux 자동 감지가 있습니다. CentOS나 RHEL에서 이전에 샌드박스 권한 문제를 겪었다면 이제 상태를 자동으로 감지하고 설정 제안을 제공합니다.

2. 핵심 신기능 상세 설명

2.1 /btw 보조 Q&A

처음에는 이 기능을 그저 ‘대화 분기’ 정도로 생각해 크게 관심을 두지 않았습니다. 하지만 실제로 사용해 보니 매우 편리했습니다.

상황을 가정해 보겠습니다. OpenClaw에 복잡한 React 컴포넌트 리팩터링을 맡겼고 작업은 이미 10여 차례 진행되어 컨텍스트가 많이 쌓였습니다. 그런데 갑자기 ‘이 정규식은 어떻게 작성하지?’처럼 관련 없는 질문이 떠올랐습니다. 이전에는 새 대화를 열거나 현재 대화에 억지로 끼워 넣어야 했고, 그러면 컨텍스트가 엉킬 수 있었습니다.

이제 /btw 질문을 바로 입력하면 OpenClaw가 주 작업의 컨텍스트에 영향을 주지 않는 ‘보조 채널’에서 답합니다. 답변을 마치면 주 작업으로 자동 전환해 계속 진행합니다.

# 보조 Q&A 예시
/btw 이메일 주소와 일치하는 정규식을 작성해 줘

# 출력 예시
# [보조 Q&A] 이메일 정규식: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
# [주 작업 계속] 컴포넌트를 리팩터링하는 중...

이 기능은 긴 작업 도중 컨텍스트를 훼손하지 않고 질문을 ‘끼워 넣는’ 방법에 대해 제가 계속 고민하던 문제를 해결해 주었습니다.

2.2 교체 가능한 샌드박스 백엔드

샌드박스 변화는 좀 더 기술적입니다. 이전에는 Docker만 선택할 수 있었지만 이제 세 가지 옵션이 있습니다.

OpenShell mirror 모드: 로컬 shell을 직접 사용하되 실행된 명령을 ‘미러링’하여 기록합니다. 빠르게 시작하고 리소스를 적게 사용하는 것이 장점이지만 Docker보다 격리성이 낮습니다. 로컬 개발과 테스트에 적합합니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

OpenShell remote 모드: 원격 서버의 shell에 연결합니다. 작업 실행 전용 장비가 있다면 OpenClaw가 원격에서 명령을 실행하고 로컬에서는 제어만 할 수 있습니다. 팀 협업이나 통일된 환경이 필요한 상황에 적합합니다.

SSH sandbox backend: remote 모드와 비슷하지만 좀 더 ‘네이티브’한 방식이며 OpenClaw 전용 프로토콜이 필요하지 않습니다. 기존 SSH 인프라를 갖춘 환경에 적합합니다.

아래는 OpenShell mirror 설정 예시입니다. 참고: OpenClaw 런타임의 기본 설정 파일은 **~/.openclaw/openclaw.json(JSON)**입니다. 아래 YAML은 계층 구조를 이해하기 위한 예시일 뿐이며, 실제 키 이름과 구조는 Gateway 설정 및 현재 버전을 기준으로 확인하세요.

# 이해를 돕기 위한 예시이므로 그대로 붙여 넣는 권위 있는 설정으로 사용하지 마세요.
sandbox:
  type: openshell
  mode: mirror
  options:
    shell: /bin/bash  # 또는 /bin/zsh
    timeout: 300      # 명령 하나의 제한 시간(초)

Docker를 설치하고 싶지 않다면 이 mirror 모드는 매우 가벼운 선택입니다. MacBook Air에서 실행해 보니 메모리 사용량이 Docker의 절반 정도였습니다.

2.3 Firecrawl 통합

웹 페이지 수집은 줄곧 OpenClaw의 약점 중 하나였습니다. 이전 방식은 다소 거칠게 curl로 HTML을 가져와 파싱했기 때문에 크롤링 방지나 동적 렌더링을 사용하는 페이지에서는 제대로 작동하지 않았습니다.

이번에 Firecrawl을 통합하면서 상황이 크게 나아졌습니다. Firecrawl은 웹 페이지 수집 전문 서비스로, JavaScript 렌더링과 자동 페이지네이션 처리를 지원하고 구조화된 Markdown도 출력할 수 있습니다. OpenClaw는 이를 내장 도구로 래핑했습니다.

# Firecrawl 활성화
tools:
  web_scraping:
    engine: firecrawl
    api_key: ${FIRECRAWL_API_KEY}  # 환경 변수 사용 권장

실제로 복잡한 SPA 페이지(예: React 문서 사이트)를 수집해 보니, 이전에는 깔끔한 콘텐츠를 얻기 위해 프롬프트를 여러 차례 직접 작성해야 했지만 이제는 거의 한 번에 처리됩니다.

2.4 Secrets 워크플로

이 기능은 API 키의 안전한 관리를 주로 해결합니다. 이전에는 설정 파일에 키를 하드코딩하거나 환경 변수를 사용하다 실수로 Git에 커밋할 수 있었습니다.

새 Secrets 워크플로는 추가, 조회, 수정, 삭제의 전체 흐름을 지원합니다.

# 키 추가
/secrets set OPENAI_API_KEY "sk-xxx"

# 모든 키 목록 표시(이름만 표시하고 값은 숨김)
/secrets list

# 키 삭제
/secrets delete OPENAI_API_KEY

키는 로컬의 ~/.openclaw/secrets/ 디렉터리에 암호화되어 저장되며 Git은 이 디렉터리를 자동으로 무시합니다. 팀 공유 설정을 사용한다면 키를 환경 변수 형식으로 내보내 CI/CD에서 주입할 수도 있습니다.

3. 플러그인 시스템 재구성 실전

이 부분은 2026.3 버전에서 가장 크게 바뀐 영역이자 기존 사용자가 업그레이드 후 가장 혼란스러워하기 쉬운 영역입니다. 저도 새 아키텍처를 이해하는 데 주말 내내 시간을 썼습니다.

3.1 Skills에서 3계층 아키텍처로

이전 OpenClaw의 플러그인은 Skills라고 불리는 독립 기능 모듈이었습니다. 필요한 기능이 있으면 Skill 하나를 설치하고 설정해서 사용할 수 있었습니다. 단순하고 직관적이지만 문제도 적지 않았습니다.

• Skill 사이에 의존성 충돌이 생길 수 있습니다.
• 다른 AI 모델로 마이그레이션할 때 각 Skill의 호환성을 일일이 확인해야 합니다.
• 기존 Skill을 커스터마이징하려면 사실상 다시 작성해야 합니다.

새 버전의 3계층 아키텍처는 다음과 같이 구분됩니다.

Bundle(기능 번들): codex-bundle, claude-bundle처럼 최상위에 있는 ‘기능 모음’입니다. 하나의 Bundle에는 서로 관련된 Plugin과 기본 Provider 설정이 포함됩니다. 즉시 사용할 수 있는 기능 패키지라고 생각하면 됩니다.

Provider(모델 제공자): 구체적인 AI 모델과 연결을 담당하는 중간 계층입니다. 예를 들어 openrouter-provider를 사용하면 OpenRouter를 통해 수십 가지 모델에 접근할 수 있고, copilot-provider는 GitHub Copilot과 연결됩니다.

Plugin(플러그인): 구체적인 기능 로직을 구현하는 최하위 계층입니다. 예를 들어 web-search-plugin은 웹 검색을, code-review-plugin은 코드 리뷰를 담당합니다.

이 구조의 장점은 무엇일까요? 예를 들어 코드 리뷰 기능을 OpenAI 모델에서 Claude로 옮길 때 Provider 설정만 바꾸면 되고 Plugin 자체는 수정하지 않아도 됩니다.

3.2 Bundle 설정 예시

claude-bundle을 예로 들면 설정 파일은 대략 다음과 같습니다.

# bundles/claude-bundle.yaml
name: claude-bundle
version: 1.2.0
description: "Claude AI 기능 모음"

provider:
  name: anthropic
  model: claude-3-5-sonnet-20241022
  api_key: ${ANTHROPIC_API_KEY}

plugins:
  - name: code-generation
    enabled: true
  - name: code-review
    enabled: true
  - name: web-search
    enabled: false  # Claude의 자체 웹 기능을 사용하므로 불필요

settings:
  max_tokens: 4096
  temperature: 0.7

기본 설정에서 참조하기만 하면 Bundle을 활성화할 수 있습니다.

# 구조 예시(실제 설정은 openclaw.json 및 공식 문서 참고)
bundles:
  - claude-bundle
  - dev-tools-bundle  # 여러 Bundle을 동시에 활성화할 수 있음

3.3 Provider 플러그인화

Bundle의 기본 Provider를 사용하고 싶지 않다면 별도로 설정할 수 있습니다. 예를 들어 더 저렴할 수 있는 OpenRouter를 통해 Claude에 접근하는 방법은 다음과 같습니다.

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

# providers/openrouter.yaml
name: openrouter
type: http
base_url: https://openrouter.ai/api/v1
api_key: ${OPENROUTER_API_KEY}

models:
  - id: anthropic/claude-3.5-sonnet
    alias: claude-sonnet
  - id: openai/gpt-4o
    alias: gpt4

그런 다음 Bundle에서 이 Provider를 참조합니다.

# bundles/custom-claude.yaml
provider:
  ref: openrouter
  model: claude-sonnet  # 위에서 정의한 alias 사용

이 메커니즘은 비용 최적화에 특히 유용합니다. 작업 유형에 따라 서로 다른 모델 라우팅 전략을 선택할 수 있기 때문입니다. 단순한 작업에는 저렴한 모델을, 복잡한 작업에는 고급 모델을 사용할 수 있습니다. 이 부분은 시리즈 26편 《OpenClaw 비용 최적화: 모델 라우팅 전략》에서 자세히 다뤘으니 관심이 있다면 참고하세요.

3.4 ClawHub 기능 마켓플레이스

공식 기능 마켓플레이스인 ClawHub는 VS Code 확장 프로그램 마켓과 비슷합니다. OpenClaw에서 직접 검색하고 설치할 수 있습니다.

# 기능 검색
/hub search code-review

# 기능 설치
/hub install voltagent/code-review-enhanced

# 설치 목록 확인
/hub list

ClawHub의 기능은 모두 커뮤니티 검토를 거치며 버전 관리도 비교적 체계적입니다. 직접 기능을 개발해 공유하고 싶다면 hub publish 명령으로 업로드할 수 있습니다.

4. 업그레이드 및 마이그레이션 가이드

4.1 이전 버전에서 원활하게 업그레이드하기

업그레이드 자체는 간단합니다. /update를 실행하거나 OpenClaw가 자동으로 업데이트를 확인하게 하면 됩니다.

# 방법 1: 수동으로 업데이트 실행
/update

# 방법 2: 대화에서 AI에게 확인 요청
"새 버전이 있는지 확인해 줘"

주의: 업그레이드 전에 반드시 다음 작업을 완료하세요.

1. 현재 설정 백업: ~/.openclaw/ 디렉터리 전체를 복사합니다.
2. 설치된 Skills 기록: 새 버전의 플러그인 시스템은 이전 버전과 호환되지 않으므로 다시 설치해야 합니다.
3. API 키 확인: 환경 변수를 사용한다면 올바르게 설정되어 있는지 확인합니다.

업그레이드가 끝나면 OpenClaw가 기존 설정의 마이그레이션을 자동으로 시도하지만 100% 성공하지는 않습니다. Bundle과 Provider 설정은 직접 조정해야 할 가능성이 큽니다.

4.2 설정 호환성 체크리스트

업그레이드 후 다음 검사를 한 번 실행하면 문제를 빠르게 찾을 수 있습니다.

특정 항목에서 오류가 발생하면 해당 설정 파일부터 확인하세요. 흔히 발생하는 문제는 다음과 같습니다.

• Skills가 사라짐: 정상입니다. 해당 Bundle을 다시 설치해야 합니다.
• Provider 연결 실패: API 키가 올바르게 마이그레이션되었는지 확인합니다.
• 샌드박스 권한 오류: 샌드박스 초기화 명령을 다시 실행합니다.

4.3 자주 발생하는 문제와 해결 방법

문제 1: 이전 버전의 Skills 설정을 인식하지 못함

새 버전은 기존 Skills 형식을 더 이상 지원하지 않습니다. 해결 방법은 다음과 같습니다.

# 이전 버전 Skills 목록 확인(이름만 표시)
/legacy-skills list

# 기존 Skills를 새 Plugin 형식으로 변환
/migrate-skills

변환된 설정은 ~/.openclaw/plugins/migrated/ 디렉터리에 저장되며 직접 조정해야 할 수도 있습니다.

문제 2: Docker 샌드박스 시작 실패

SELinux 권한 문제일 수 있습니다. 다음 명령을 실행하세요.

# SELinux 설정 감지 및 수정
/sandbox fix-selinux

# 또는 OpenShell mirror 모드로 전환
/config set sandbox.type openshell
/config set sandbox.mode mirror

문제 3: 다중 모델 라우팅 설정 유실

저도 업그레이드할 때 이 문제를 겪었습니다. 새 Provider 아키텍처에서 라우팅 설정 방식이 바뀐 것이 원인입니다. 3장의 예시를 참고해 Provider 설정 파일을 다시 작성하면 됩니다.

5. 실전 시나리오와 모범 사례

5.1 시나리오 1: 다중 모델 라우팅 비용 최적화

개인 개발자와 소규모 팀이 가장 관심을 두는 문제입니다. OpenClaw 새 버전의 다중 모델 라우팅 메커니즘을 활용하면 ‘단순한 작업은 저렴한 모델로, 복잡한 작업은 고급 모델로’ 처리하는 전략을 실제로 구현할 수 있습니다.

기본적인 구성은 다음과 같습니다.

# router.yaml
rules:
  - name: simple-tasks
    condition: "tokens < 1000 and complexity < 0.3"
    provider: openrouter
    model: openai/gpt-3.5-turbo

  - name: complex-tasks
    condition: "tokens >= 1000 or complexity >= 0.3"
    provider: openrouter
    model: anthropic/claude-3.5-sonnet

  - name: code-review
    condition: "task_type == 'code_review'"
    provider: anthropic
    model: claude-3-5-sonnet-20241022

실제 테스트에서는 동일한 작업량의 비용을 40%~60% 절감할 수 있었습니다. 물론 구체적인 결과는 작업 분포에 따라 달라집니다.

5.2 시나리오 2: 브라우저 자동화 강화

새 버전은 ‘Live Chrome session attachment’를 지원합니다. 쉽게 말하면 이미 열려 있는 Chrome 브라우저 창을 OpenClaw가 제어하게 할 수 있습니다.

다음과 같은 상황에서 특히 유용합니다.

KiloClaw - 기업용 매니지드 OpenClaw, AI Agent 오케스트레이션 및 스마트 라우팅

시작하기 →광고

• 인증 코드를 요구하는 사이트에 이미 로그인한 경우
• 여러 페이지를 오가며 작업해야 하는 경우
• 브라우저의 Cookie와 세션 상태를 유지하고 싶은 경우

설정 방법은 다음과 같습니다.

# 구조 예시(브라우저 자동화 키 이름은 공식 문서 기준)
browser:
  mode: attach
  chrome_path: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
  user_data_dir: ~/.chrome-debug-profile
  debug_port: 9222

Chrome을 시작할 때 디버깅 인수를 추가합니다.

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=~/.chrome-debug-profile

# 그런 다음 OpenClaw에 요청합니다.
"현재 브라우저 창을 제어해 줘"

5.3 시나리오 3: 엔터프라이즈급 보안 배포

회사 환경에서 OpenClaw를 사용한다면 보안을 피할 수 없습니다. 새 버전의 여러 기능은 규정 준수 요구 사항을 충족하는 데 도움이 됩니다.

1. Secrets 암호화 저장

모든 키는 AES-256으로 암호화해 저장하며 키 자체는 디스크에 기록하지 않고 메모리에 존재합니다.

2. 감사 로그

감사 모드를 활성화하면 모든 AI 요청과 응답이 기록됩니다.

audit:
  enabled: true
  log_path: /var/log/openclaw/audit.log
  redact_secrets: true  # 키 자동 마스킹

3. 아웃바운드 트래픽 제어

OpenClaw가 특정 도메인에만 접근하도록 제한합니다.

network:
  allowlist:
    - api.anthropic.com
    - api.openai.com
    - openrouter.ai
  deny_all_others: true

4. SELinux 자동 감지

CentOS/RHEL에서 OpenClaw는 SELinux 상태를 자동으로 감지하고 설정 제안을 제공합니다.

# OpenClaw가 자동 생성한 제안
# Docker SELinux 정책을 설정하려면 다음 명령을 실행하세요.
# semanage port -a -t docker_port_t -p tcp 2375-2376

마무리

지금 막 2026.3 버전으로 업그레이드했다면 다음 다섯 가지 기능부터 사용해 보기를 권합니다.

1. /btw 보조 Q&A: 긴 작업 도중 질문을 넣어 ‘컨텍스트를 끊지 않는’ 방식을 경험해 보세요.
2. OpenShell mirror 모드: Docker의 리소스 사용량이 부담스러웠다면 꼭 사용해 볼 만합니다.
3. Firecrawl 웹 수집: 복잡한 SPA 페이지를 골라 테스트하면 차이를 바로 확인할 수 있습니다.
4. ClawHub 기능 마켓플레이스: 둘러보면서 커뮤니티가 공유한 기능을 살펴보세요.
5. Secrets 워크플로: 설정 파일에 하드코딩된 키를 옮기면 보안을 크게 강화할 수 있습니다.

OpenClaw는 때로 1~2주 만에 새 버전이 나올 정도로 빠르게 발전하는 프로젝트입니다. 사용 중 문제가 생기면 GitHub Issues에서 검색해 보세요. 같은 문제를 겪은 사람이 이미 있을 가능성이 큽니다.

이 시리즈에서는 이전에도 설정 상세 가이드, 비용 최적화, 아키텍처 분석 등을 다뤘습니다. OpenClaw를 처음 접한다면 《OpenClaw 아키텍처 가이드: 입문부터 고급까지》부터 읽으며 전체 구조를 체계적으로 이해해 보세요.