들어가며
OpenClaw 3.2가 출시됐습니다. 3.1을 올린 지 얼마나 됐다고… 벌써 3.2네요.
이번 버전의 핵심 테마를 세 줄로 요약하면:
- PDF가 드디어 1등 시민 — 네이티브 Anthropic/Google 지원 포함 전용 툴 신설
- 시크릿 관리, 이제 진짜 완전체 — 64개 전 항목에 SecretRef 확장 완료
- 플러그인 SDK 대폭 강화 — 외부 확장이 OpenClaw 내장을 직접 활용하는 시대
1. 📄 PDF 툴 — 드디어 1급 시민으로!
이번 3.2에서 개인적으로 가장 반가운 변화입니다. (Thanks @tyler6204)
기존에는 PDF를 다루려면 별도 처리를 거쳐야 했는데, 이제 전용 pdf 툴이 1급 시민으로 추가됩니다.
주요 특징:
- Anthropic / Google 네이티브 지원: 해당 모델들은 PDF를 직접 읽고 이해합니다. 따로 텍스트로 뽑아낼 필요 없음.
- 비네이티브 모델 폴백: 다른 모델들은 텍스트/이미지 추출 폴백으로 처리.
- 세밀한 기본값 설정:
agents.defaults.pdfModel: PDF 분석에 쓸 기본 모델 지정agents.defaults.pdfMaxBytesMb: 최대 파일 크기 제한agents.defaults.pdfMaxPages: 최대 페이지 수 제한
저처럼 논문이나 명세서 PDF를 에이전트에게 던져주고 분석시키는 분들한테 이건 게임 체인저입니다. “이 PDF 요약해줘” 한 줄로 끝나는 시대가 됐습니다. 📑
2. 🔐 시크릿 관리 — 이제 진짜 완전체 (64개 전 항목)
2.26에서 외부 시크릿 관리를 처음 도입했는데, 이번 3.2에서 사실상 완성됩니다. (Thanks @joshavant)
SecretRef 적용 범위를 사용자 공급 자격증명 전 항목(64개)으로 확장했습니다.
포함 범위:
- 런타임 컬렉터(Runtime Collectors)
openclaw secrets plan / apply / audit전체 플로우- 온보딩 SecretInput UX
- 관련 문서 전면 업데이트
그리고 중요한 동작 변경이 하나 있습니다:
- 활성 서피스에서 미해석 ref → 즉시 실패(fail-fast): API 키가 없으면 조용히 넘어가지 않고 바로 에러를 냅니다.
- 비활성 서피스 → 비차단 진단(non-blocking diagnostics): 안 쓰는 설정의 ref 오류는 경고로만 표시.
평문 API 키를 openclaw.json에 박아두셨던 분들, 이번에는 진짜로 시크릿 관리로 이전할 때가 된 것 같습니다. 저도 슬슬… 🙈
3. 📨 Telegram — 세 가지 굵직한 업데이트
이번 3.2에서 Telegram 관련 변경이 세 가지 들어왔습니다.
스트리밍 기본값이 partial로 전환
기존에는 Telegram 채널의 스트리밍이 기본값 off였는데, 이제 partial이 기본값으로 바뀝니다. (Thanks @obviyus)
즉, 새로 Telegram 채널을 세팅하면 설정 없이도 바로 라이브 프리뷰 스트리밍이 됩니다. 네이티브 draft 기능이 없는 경우엔 메시지 편집(edit) 방식으로 자동 폴백.
체감 차이가 꽤 납니다. 긴 답변이 한 번에 탁 나타나는 게 아니라 타이핑하듯 흘러들어오는 것과 그냥 기다리는 것은 UX가 완전히 다릅니다.
DM 스트리밍 — sendMessageDraft 활용
Telegram DM에서 프리뷰 스트리밍에 sendMessageDraft를 사용합니다. 또한 DM reasoning-stream 모드에서 reasoning 레인과 answer 레인이 분리됩니다. 생각하는 과정과 최종 답변이 뒤섞이지 않게 됩니다.
음성 메시지 언급 감지 선택적 스킵
그룹/토픽에서 음성 노트가 왔을 때 기존에는 무조건 mentions 확인을 위해 사전 트랜스크립션을 수행했는데, 이제 disableAudioPreflight: true 설정으로 이 과정을 건너뛸 수 있습니다. (Thanks @yangnim21029)
텍스트 기반 언급 확인만으로 충분한 운영 환경에서는 불필요한 STT API 호출을 아낄 수 있습니다.
4. 📎 sessions_spawn — 이제 파일 첨부 가능
서브에이전트를 스폰할 때 파일을 바로 붙여서 넘길 수 있게 됩니다. (Thanks @napetrov)
sessions_spawn 서브에이전트 런타임 전용:
base64/utf8인코딩 지원- 트랜스크립트 내 첨부파일 내용 자동 리댁션(redaction)
- 생애주기 종료 시 자동 정리(cleanup)
tools.sessions_spawn.attachments로 용량/수량 제한 설정 가능
예를 들어 코딩 서브에이전트에게 task와 함께 소스 파일을 직접 넘기는 게 가능해집니다. 멀티 에이전트 워크플로우를 짜는 분들한테는 꽤 편리한 업데이트입니다.
5. 🤖 MiniMax-M2.5-highspeed — 새 모델 합류
MiniMax-M2.5-highspeed가 내장 프로바이더 카탈로그와 온보딩 플로우, MiniMax OAuth 플러그인 기본값에 공식 추가됩니다.
기존 MiniMax-M2.5-Lightning 사용 중인 분들은 그대로 호환되니 설정 변경 없이 그냥 써도 됩니다. 고속 모델이 필요하다면 이제 highspeed를 선택하시면 됩니다.
6. 🔧 openclaw config validate — 시작 전에 검사부터
드디어 추가됐습니다. (Thanks @Sid-Qin)
openclaw config validate
openclaw config validate --json
게이트웨이를 실제로 띄우기 전에 설정 파일의 유효성을 미리 검사합니다. --json 플래그로 상세한 오류 경로도 확인 가능합니다.
기존에는 설정 실수가 있어도 게이트웨이 시작 시점에야 알 수 있었는데, 이제 배포 전에 미리 잡을 수 있습니다. CI/CD 파이프라인에 넣기 딱 좋은 명령어입니다.
7. 🧠 메모리 — Ollama 임베딩 지원
저처럼 로컬 LLM을 적극 활용하는 분들한테 반가운 소식입니다. (Thanks @nico-hoff)
이제 메모리 검색 임베딩을 Ollama로 처리할 수 있습니다:
memorySearch:
provider: "ollama"
fallback: "ollama"
models.providers.ollama 설정을 그대로 따르기 때문에 별도 추가 설정이 거의 필요 없습니다. 임베딩까지 로컬에서 다 돌리면 API 비용이 또 한 번 줄어듭니다. 🤑
8. 🔌 플러그인 SDK — 대규모 확장
이번 3.2에서 플러그인 개발자들을 위한 업데이트가 대거 들어왔습니다.
채널 런타임 접근 (channelRuntime) (Thanks @guxiaobo)
외부 채널 플러그인이 이제 ChannelGatewayContext의 channelRuntime을 통해 OpenClaw 내부 헬퍼(reply/routing/session/text/media/commands)를 직접 호출할 수 있습니다. 내부 임포트 없이 외부에서 완전한 채널 기능을 구현 가능.
STT API 노출 (Thanks @benthecarman)
api.runtime.stt.transcribeAudioFile(...) 추가. 플러그인이 OpenClaw의 설정된 오디오 프로바이더를 직접 활용해서 로컬 오디오 파일을 트랜스크립션할 수 있습니다.
세션 라이프사이클 훅에 sessionKey 포함 (Thanks @tempeste)
session_start / session_end 훅 이벤트에 sessionKey가 포함됩니다. 플러그인이 라이프사이클 콜백과 라우팅 ID를 연결해서 추적하는 게 가능해집니다.
메시지 라이프사이클 훅 확장 (Thanks @Drickon)
새 훅 이벤트 추가:
message:transcribed— 트랜스크립션 완료 후message:preprocessed— 전처리 완료 후- 아웃바운드
message:sent에isGroup,groupId컨텍스트 추가
requestHeartbeatNow (Thanks @AustinEral)
runtime.system.requestHeartbeatNow(...)로 플러그인이 특정 세션을 즉시 깨울 수 있게 됩니다. 시스템 이벤트를 큐에 넣은 직후 바로 처리를 트리거하고 싶을 때 유용합니다.
이벤트 구독 API 신설 (Thanks @scifantastic)
runtime.events.onAgentEvent, runtime.events.onSessionTranscriptUpdate 추가. 한 리스너가 오류를 내도 전체 팬아웃이 깨지지 않도록 격리 처리됩니다.
9. 🛠️ 기타 눈에 띄는 변경사항
Diffs 툴 — PDF 출력 지원 (Thanks @gumadeiras)
Diff 결과를 PDF로 저장 가능해졌습니다. fileQuality, fileScale, fileMaxWidth로 품질/스케일 커스터마이징도 지원합니다. 메시징 채널이 이미지를 압축하는 환경에서는 PDF가 권장 옵션으로 소개됩니다.
오디오 에코 트랜스크립션 (Thanks @AytuncYildizli)
음성 메시지를 트랜스크립션한 결과를 에이전트에게 넘기기 전에 사용자에게 먼저 보내주는 옵션이 추가됩니다:
tools:
media:
audio:
echoTranscript: true
echoFormat: "text"
“내 말이 이렇게 받아쓰여졌습니다” 확인이 가능해지는 겁니다. 기본값은 비활성.
아웃바운드 어댑터 sendPayload 통합 (Thanks @nohat)
Discord, Slack, WhatsApp, Zalo, Zalouser 등 주요 채널에 sendPayload 공통 지원이 추가됩니다. 멀티미디어 반복 전송과 청크 단위 텍스트 폴백을 통일된 방식으로 처리할 수 있게 됩니다.
Zalo Personal 플러그인 네이티브 전환
Zalo Personal(@openclaw/zalouser)이 외부 CLI 전송 방식에서 zca-js 네이티브 인프로세스 통합으로 전면 재구축됐습니다. QR/로그인, 송수신 플로우가 모두 OpenClaw 내부에서 처리됩니다.
배너 태그라인 커스터마이징
cli:
banner:
taglineMode: random # random | default | off
시작 시 보이는 재치있는 문구를 랜덤으로 바꿀지, 기본 고정 문구를 쓸지, 아예 끌지 설정 가능합니다. 소소하지만 매번 시작할 때마다 다른 문구 보는 게 은근히 재미있을 것 같습니다. 😄
마무리
3.2는 도구 성숙 + 플러그인 생태계 확장 + Telegram UX 개선이 핵심인 릴리즈입니다.
PDF 툴의 1급 시민화는 논문, 명세서, 계약서 등을 에이전트에게 바로 넘기는 워크플로우를 크게 단순화합니다. 시크릿 관리 64개 완전 통합은 보안 운영 측면에서 3.x 시리즈의 완성이라고 볼 수 있습니다. Telegram 스트리밍 기본값 전환은 새로 세팅하는 분들이 바로 체감할 수 있는 UX 변화고요.
플러그인 SDK 확장 폭을 보면 OpenClaw가 단순 봇 프레임워크를 넘어 진짜 에이전트 플랫폼으로 가고 있다는 느낌이 확실히 납니다.
업데이트는 언제나처럼:
openclaw update
치고 들어가시길. 🚀
