OpenClaw 2026.3.2 릴리즈 노트 분석 - PDF 도구, SecretRef 확대, 보안 대폭 강화

한 줄 요약

PDF 도구 신설, SecretRef 전면 확대, 보안 강화가 대거 포함된 릴리즈로, 신규 설치 시 도구 프로필이 messaging으로 바뀌는 브레이킹 체인지가 있다.

---

주요 변경사항

PDF 도구 추가

pdf라는 퍼스트클래스 도구가 새로 생겼다. Anthropic과 Google의 네이티브 PDF 지원을 활용하고, 네이티브를 지원하지 않는 모델에서는 텍스트 추출 폴백이 동작한다. agents.defaults.pdfModel, pdfMaxBytesMb, pdfMaxPages 등으로 설정할 수 있다.

PDF를 직접 분석해야 하는 워크플로우가 있다면 별도 스크립트 없이 도구 하나로 해결 가능해졌다.

SecretRef 전면 확대

사용자 자격증명을 다루는 64개 표면 전체에 SecretRef 지원이 확장됐다. 런타임 수집기, openclaw secrets 계획/적용/감사 흐름, 온보딩 UX까지 포함된다. 미해결 참조는 활성 표면에서 즉시 실패하고, 비활성 표면에서는 비차단 진단으로 보고된다.

시크릿 관리를 체계적으로 쓰고 있다면 이제 거의 모든 곳에서 SecretRef를 쓸 수 있다는 의미다.

서브에이전트 파일 첨부 지원

sessions_spawn에 인라인 파일 첨부 기능이 추가됐다. base64/utf8 인코딩을 지원하고, 트랜스크립트에서 내용이 자동 삭제되며, tools.sessions_spawn.attachments로 제한을 설정할 수 있다. 서브에이전트 런타임에서만 동작한다.

서브에이전트에 파일을 넘겨야 할 때 임시 파일을 만들 필요 없이 바로 전달할 수 있게 됐다.

MiniMax-M2.5-highspeed 모델 지원

기존 MiniMax-M2.5-Lightning의 후속 모델인 MiniMax-M2.5-highspeed가 빌트인 카탈로그에 추가됐다. 기존 Lightning 설정은 호환성을 위해 유지된다.

Telegram 스트리밍 기본값 변경

channels.telegram.streaming 기본값이 off에서 partial로 바뀌었다. 새로 세팅하는 Telegram 채널에서 별도 설정 없이 실시간 프리뷰 스트리밍이 활성화된다. DM에서는 sendMessageDraft를 활용한 프리뷰 스트리밍도 추가됐다.

CLI 설정 검증 커맨드

openclaw config validate 명령이 새로 생겼다. --json 옵션도 지원한다. 게이트웨이를 시작하기 전에 설정 파일의 유효성을 미리 확인할 수 있고, 시작 시 잘못된 키 경로를 상세하게 보여준다.

설정 오류로 게이트웨이가 안 뜨는 상황을 미리 잡아낼 수 있다.

Ollama 메모리 임베딩 지원

memorySearch.provider와 memorySearch.fallback에 "ollama"를 지정할 수 있게 됐다. models.providers.ollama 설정을 그대로 활용한다.

로컬 LLM으로 메모리 검색까지 처리하고 싶은 경우 유용하다.

Zalo Personal 플러그인 리빌드

@openclaw/zalouser 플러그인이 외부 CLI 의존성을 버리고 zca-js를 직접 사용하는 네이티브 방식으로 재구축됐다. 업그레이드 후 openclaw channels login --channel zalouser로 세션을 갱신해야 한다.

플러그인 SDK 채널 확장성 개선

ChannelGatewayContext에 channelRuntime이 노출되면서, 외부 채널 플러그인이 내부 import 없이 공유 런타임 헬퍼(응답/라우팅/세션/텍스트/미디어/커맨드)에 접근할 수 있게 됐다.

플러그인 개발자에게 중요한 변경이다.

플러그인 런타임 STT/이벤트/세션 훅 확장

api.runtime.stt.transcribeAudioFile(...): 플러그인에서 로컬 오디오 파일을 직접 트랜스크립션할 수 있다.

runtime.system.requestHeartbeatNow(...): 이벤트 큐잉 후 즉시 세션을 깨울 수 있다.

runtime.events.onAgentEvent, onSessionTranscriptUpdate: 확장 측 이벤트 구독이 가능해졌다.

session_start/session_end 훅에 sessionKey가 포함됐다.

message:transcribed, message:preprocessed 내부 훅 이벤트가 추가됐다.

---

브레이킹 체인지

도구 프로필 기본값 변경

신규 로컬 설치 시 tools.profile이 messaging으로 기본 설정된다. 기존에는 코딩/시스템 도구가 전부 활성화됐지만, 이제는 명시적으로 설정해야 한다.

기존 설치에는 영향 없다. 신규 설치 후 코딩 도구가 안 보이면 tools.profile을 확인하면 된다.

ACP 디스패치 기본 활성화

ACP 디스패치가 명시적으로 비활성화(acp.dispatch.enabled=false)하지 않는 한 기본 활성화된다. ACP 턴 라우팅을 일시 중지하면서 /acp 컨트롤은 유지하고 싶다면 acp.dispatch.enabled=false를 설정하면 된다.

플러그인 HTTP 핸들러 등록 방식 변경

api.registerHttpHandler(...)가 제거됐다. 플러그인은 api.registerHttpRoute({ path, auth, match, handler })로 명시적 HTTP 라우트를 등록해야 한다.

플러그인 개발자는 반드시 마이그레이션이 필요하다.

Zalo Personal CLI 의존성 제거

@openclaw/zalouser가 외부 zca 호환 CLI 바이너리에 더 이상 의존하지 않는다. 업그레이드 후 openclaw channels login --channel zalouser를 실행해야 한다.

---

보안 강화 (주요 항목)

이번 릴리즈에는 다수의 보안 강화가 포함됐다. 주요 항목만 정리한다.

게이트웨이 보안: 루프백 origin 검증 강화, 플러그인 라우트 인증 필수화, WS 보안 기본값 강화

웹훅 요청 처리: 인증 전 body 파싱 차단, slow-body DoS 방어

노드 카메라 URL: SSRF 가드 적용, off-node fetch 방지

설정 백업: 0600 퍼미션 강제, 고아 백업 파일 정리

프롬프트 스푸핑: 런타임 이벤트의 사용자 역할 주입 차단, [System Message] 마커 무력화

샌드박스: 부트스트랩 심링크 탈출 차단, ACP 샌드박스 경계 바이패스 차단

SSRF: web_fetch와 citation-redirect URL의 DNS 피닝 유지

운영 환경에서는 가능한 빨리 업그레이드하는 것이 좋다.

---

주요 버그 수정

Slack Bolt 4.6+ 호환성: 잘못된 이벤트 등록으로 인한 시작 크래시 수정

Feishu 다중 에이전트 그룵: 중복 응답 방지, 인바운드 직렬화, 타이핑 알림 중복 억제

Discord 병렬 디스패치: 채널 간 병렬 발송 복원, 채널 내 순서 유지

Telegram 모델 피커: 64바이트 콜백 잘림 방지

Webchat NO_REPLY 유출: 스트리밍 시 NO 부분 유출 방지

게이트웨이 TLS + 서브에이전트: Docker/LAN 환경에서 sessions_spawn 복원

macOS LaunchAgent: npm 업그레이드 시 퍼미션 보존

크론 HEARTBEAT_OK: 사용자에게 전달되던 HEARTBEAT_OK 노이즈 억제

OpenRouter x-ai 호환성: Grok 모델에서 reasoning.effort 주입 제거

---

마이그레이션 주의사항

신규 설치 시 tools.profile이 messaging으로 설정된다. 코딩 도구가 필요하면 명시적으로 변경해야 한다.

ACP 디스패치가 기본 활성화된다. 비활성화가 필요하면 acp.dispatch.enabled=false 설정.

플러그인 개발자: registerHttpHandler → registerHttpRoute 마이그레이션 필수.

Zalo Personal 사용자: 업그레이드 후 openclaw channels login --channel zalouser 실행.

---

참고 링크

릴리즈 페이지

공식 문서

ACP 에이전트 문서