문서 변경 이력

OpenClaw 한국어 가이드 업데이트 내역입니다.

Unreleased (예정)

추가 예정

• 서브 에이전트 심화 문서
• 실전 사용 사례 모음
• 비디오 튜토리얼
• 성능 최적화 가이드

Version 2026.4.21 (2026-04-22)

가이드 반영 파일

52-multi-model.md, 42-memory-system.md, 31-cron.md, 12-telegram.md, 17-bluebubbles.md, 26-teams.md, 61-cli-commands.md, 53-security.md — 18개 stable 릴리즈(v2026.3.22~v2026.4.21) 변경사항 일괄 반영.

OpenClaw 릴리즈 변경사항

변경사항

• OpenAI/images: 번들 이미지 생성 provider 기본값을 gpt-image-2로 변경, 2K/4K OpenAI 사이즈 힌트 지원 추가.

버그 수정

• Auth/commands: enforceOwnerForCommands=true + ownerAllowFrom 미설정 시 wildcard allowFrom 또는 빈 owner 후보 목록을 owner 권한으로 허용하지 않도록 강화. (#69774)
• Slack: threadTs 공급 시 런타임 아웃바운드 전송에서 thread 별칭 보존. (#62947)
• Browser: 잘못된 ax<N> 접근성 참조를 타임아웃 없이 즉시 거부. (#69924)
• npm/install: node-domexception 별칭을 루트 package.json overrides에 미러링하여 deprecated 의존성 체인 경고 제거.

Version 2026.4.20 (2026-04-21)

변경사항

• Cron: 런타임 실행 상태를 jobs-state.json으로 분리하여 jobs.json은 git 추적용 job 정의로 안정적으로 유지. (#63105)
• Moonshot/Kimi: 번들 기본값을 kimi-k2.6으로 변경, kimi-k2.5 호환성 유지. (#69477)
• Moonshot/Kimi: kimi-k2.6에서 thinking.keep = "all" 허용, 다른 Moonshot 모델 또는 tool_choice 고정 시 제거. (#68816)
• BlueBubbles/groups: 그룹별 systemPrompt 설정을 인바운드 컨텍스트 GroupSystemPrompt로 전달, "*" 와일드카드 폴백 지원. (#69198)
• Sessions/Maintenance: 기본 항목 상한 및 연령 정리 강제 적용, 로드 시 과다 저장소 정리로 OOM 방지. (#69404)

버그 수정

• BlueBubbles: 아웃바운드 전송 타임아웃 기본값 10초→30초 상향, macOS 26(Tahoe) Private API iMessage 전송 중단 방지. (#69193)
• Telegram: 폴링 감시 임계값 기본값 90초→120초 상향, 장시간 작업에서 중단(stalled) 오인 감소. (#57737)

Version 2026.4.15 (2026-04-16)

변경사항

• Anthropic/models: 기본 Anthropic 선택, opus 별칭, Claude CLI 기본값을 Claude Opus 4.7로 변경.
• Google/TTS: 번들 google 플러그인에 Gemini TTS 지원 추가 (음성 선택, WAV 응답 출력, PCM 텔레포니 출력). (#67515)
• Memory/LanceDB: memory-lancedb에 클라우드 스토리지 지원 추가로 원격 오브젝트 스토리지에서 영구 메모리 인덱스 운용 가능. (#63502)
• GitHub Copilot/memory search: 메모리 검색용 GitHub Copilot 임베딩 provider 추가. (#61718)
• Packaging/plugins: 번들 플러그인 런타임 의존성을 소유 extension으로 로컬화하여 배포 패키지 경량화. (#67099)

보안 수정

• Gateway/tools: 클라이언트 제공 tool 이름이 내장 tool과 충돌 시 400 invalid_request_error 반환, 내장 tool 로컬 미디어 신뢰 상속 방지. (#67303)

Version 2026.4.14 (2026-04-14)

변경사항

• OpenAI Codex/models: gpt-5.4-pro 전방 호환 지원 추가 (Codex 가격/한도 및 목록/상태 가시성 포함). (#66453)
• Telegram/forum topics: 포럼 서비스 메시지에서 토픽 이름을 학습하여 에이전트 컨텍스트 및 플러그인 훅 메타데이터에 표시. (#65973)

버그 수정

• Models/Codex: codex provider 카탈로그 출력에 apiKey 포함하여 models.json의 모든 custom 모델이 자동 드롭되는 문제 수정. (#66180)
• Tools/image+pdf: provider/model 참조 정규화로 Ollama 비전 모델이 거부되는 문제 수정. (#59943)
• Slack/interactions: 블록 액션 및 모달 이벤트에 allowFrom 허용 목록 적용, 허용 목록 없는 채널에서 open-by-default 동작 유지. (#66028)

Version 2026.4.12 (2026-04-13)

변경사항

• Memory/Active Memory: 메인 응답 직전 전용 메모리 서브 에이전트를 실행하는 새 선택적 Active Memory 플러그인 추가 (message/recent/full contextMode 설정 지원, /verbose 검사, 프롬프트 오버라이드 튜닝). (#63286)
• CLI/exec policy: openclaw exec-policy 명령 추가 (show, preset, set 서브커맨드로 tools.exec.* 설정과 로컬 exec 승인 파일 동기화). (#64050)
• Gateway: commands.list RPC 추가로 원격 게이트웨이 클라이언트에서 런타임 명령 탐색 지원. (#62656)
• Models/providers: 신뢰할 수 있는 자체 호스팅 OpenAI 호환 엔드포인트를 위한 per-provider models.providers.*.request.allowPrivateNetwork 추가. (#63671)

Version 2026.4.11 (2026-04-12)

변경사항

• Dreaming/memory-wiki: ChatGPT import 수집 + Imported Insights, Memory Palace 다이어리 서브탭 추가로 Dreaming에서 가져온 대화 및 위키 페이지 직접 검사 가능. (#64505)
• Microsoft Teams: 리액션 지원, 리액션 목록 조회, Graph API 페이지네이션, 리액션 전송을 위한 위임 OAuth(delegated OAuth) 설정 추가 (기존 application-auth 읽기 경로 유지). (#51646)
• Tools/video_generate: URL 전용 에셋 전달, 타입화된 providerOptions, 참조 오디오 입력, per-asset 역할 힌트, adaptive 가로세로비 지원 추가. (#61987, #61988)
• Feishu: 문서 댓글 세션에 컨텍스트 파싱, 댓글 리액션, 타이핑 피드백 추가. (#63785)
• Plugins: 플러그인 매니페스트에서 활성화 및 설정 디스크립터 선언 지원으로 코어 하드코딩 없이 설정 플로우 기술 가능. (#64780)

버그 수정

• OpenAI/Codex OAuth: authorize URL 범위 재작성 중단으로 새 Codex 로그인 시 invalid_scope 오류 해결. (#64713)
• Audio transcription: OpenAI 호환 멀티파트 요청에만 DNS 핀 비활성화, OpenAI/Groq/Mistral 전사 기능 복구. (#64766)

Version 2026.4.10 (2026-04-11)

변경사항

• Models/Codex: 번들 Codex provider 및 app-server harness 추가 (codex/gpt-* 모델은 Codex 관리 인증·네이티브 스레드·모델 탐색·압축 사용, openai/gpt-*는 기존 OpenAI 경로 유지). (#64298)
• Microsoft Teams: pin, unpin, read, react 및 리액션 목록 조회 메시지 액션 추가. (#53432)
• Tools/video generation: Seedance 2.0 모델 참조 및 provider별 duration, resolution, audio, seed 메타데이터 필드 추가.

Version 2026.4.9 (2026-04-09)

변경사항

• Memory/dreaming: 과거 일일 노트를 Dreams와 영구 메모리로 재생하는 grounded REM backfill 레인 추가 (rem-harness --path 지원, 다이어리 커밋/리셋 플로우, 내구성 있는 팩트 추출).
• Plugins/provider-auth: provider 매니페스트에서 providerAuthAliases 선언 지원으로 provider 변형 간 환경 변수 및 인증 프로파일 공유 가능.
• iOS: apps/ios/version.json에 CalVer 버전 핀 설정, pnpm ios:version:pin -- --from-gateway 릴리즈 워크플로우 추가. (#63001)

보안 수정

• Browser/security: 상호작용 기반 메인 프레임 내비게이션 후 차단 대상 안전 검사 재실행으로 SSRF 우회 방지. (#63226)
• Security/dotenv: 신뢰할 수 없는 워크스페이스 .env 파일에서 런타임 제어 환경 변수 및 브라우저 제어 오버라이드 차단. (#62660, #62663)
• Gateway/node exec events: 원격 노드 exec 이벤트를 신뢰할 수 없는 시스템 이벤트로 표시하여 노드 출력으로 인한 프롬프트 인젝션 방지. (#62659)

Version 2026.4.8 (2026-04-08)

버그 수정

• Telegram/setup: npm 빌드에서 dist/extensions/telegram/src/* 파일 누락으로 게이트웨이 시작 실패하는 문제 수정.
• Bundled channels/setup: BlueBubbles, Feishu, Google Chat, IRC, Matrix, Mattermost, Teams, Nextcloud Talk, Slack, Zalo 채널 시작 시 누락 파일 문제 수정.
• Slack: Socket Mode WebSocket 연결에 HTTP(S) 프록시 설정 적용 (NO_PROXY 제외 포함). (#62878)
• Network/fetch guard: 신뢰할 수 있는 env-proxy 모드 활성화 시 대상 DNS 핀 설정 건너뜀으로 프록시 전용 샌드박스에서 아웃바운드 해결 가능. (#59007)

Version 2026.4.7 (2026-04-08)

변경사항

• CLI/infer: provider 기반 추론 워크플로우를 위한 openclaw infer 허브 추가 (모델, 미디어, 웹, 임베딩 작업 지원).
• Memory/wiki: 번들 memory-wiki 스택 복원 (플러그인, CLI, 동기화/쿼리/적용 도구, 구조화된 claim/evidence 필드, 신선도 가중 검색 포함).
• Plugins/webhooks: 번들 webhook 수신 플러그인 추가로 외부 자동화에서 per-route 공유 시크릿 엔드포인트를 통한 TaskFlow 구동 가능. (#61892)
• Gateway/sessions: 영구 compaction 체크포인트 + Sessions UI 브랜치/복원 액션 추가로 압축 이전 세션 상태 검사 및 복구 지원. (#62146)
• Providers/Google: Gemma 4 모델 지원 추가 및 Google 폴백 해결 경로 수정. (#61507)
• Providers/Arcee AI: 번들 Arcee AI provider 플러그인 추가 (Trinity 카탈로그, OpenRouter 지원). (#62068)
• Agents/system prompt: agents.defaults.systemPromptOverride 추가로 프롬프트 실험 및 heartbeat 프롬프트 섹션 제어 지원.

Version 2026.4.5 (2026-04-06)

Breaking 변경사항

• Config: 레거시 공개 설정 별칭 제거 (talk.voiceId, talk.apiKey, browser.ssrfPolicy.allowPrivateNetwork 등). openclaw doctor --fix로 마이그레이션. (#60726)

변경사항

• Agents/video generation: 내장 video_generate 도구 추가로 에이전트가 설정된 provider를 통해 비디오 생성 및 응답에 직접 반환 가능.
• Tools/music generation: 내장 music_generate 도구 추가 (번들 Google Lyria, MiniMax provider 포함, Comfy 워크플로우 지원).
• Providers: 번들 Qwen, Fireworks AI, StepFun provider 추가 및 MiniMax TTS, Ollama 웹 검색, MiniMax Search 통합. (#60032 외)
• Amazon Bedrock: 번들 Mantle 지원 및 추론 프로파일 자동 탐색 추가. (#61296)
• Control UI/multilingual: 한국어 포함 12개 언어 다국어 Control UI 지원 추가.
• Control UI/skills: ClawHub 검색·상세·설치 플로우를 Skills 패널에서 직접 제공. (#60134)

Version 2026.4.2 (2026-04-02)

Breaking 변경사항

• Plugins/xAI: x_search 설정을 plugins.entries.xai.config.xSearch.*로 이전, 인증 표준화. openclaw doctor --fix로 마이그레이션. (#59674)
• Plugins/web fetch: Firecrawl web_fetch 설정을 plugins.entries.firecrawl.config.webFetch.*로 이전. openclaw doctor --fix로 마이그레이션. (#59465)

변경사항

• Tasks/Task Flow: 코어 Task Flow 기반 복원 (managed/mirrored 동기화 모드, 영구 flow 상태/리비전 추적, openclaw flows 검사/복구 프리미티브). (#58930)
• Tasks/Task Flow: 관리형 자식 태스크 생성 및 sticky 취소 인텐트 추가. (#59610)
• Android/assistant: Android 어시스턴트 진입점 및 Google Assistant App Actions 메타데이터 추가. (#59596)
• Plugins/hooks: before_agent_reply 훅 추가로 플러그인이 LLM을 우회한 합성 응답 삽입 가능. (#20067)

Version 2026.4.1 (2026-04-01)

변경사항

• Tasks/chat: /tasks 명령으로 현재 세션의 백그라운드 태스크 보드 표시 (최근 태스크 상세, 에이전트 로컬 폴백 카운트 포함).
• Web search/SearXNG: 번들 SearXNG provider 플러그인 추가 (web_search용, 설정 가능한 호스트 지원). (#57317)
• Amazon Bedrock/Guardrails: Bedrock Guardrails 지원 추가. (#58588)
• Cron/tools allowlist: openclaw cron --tools로 job별 도구 허용 목록 설정 지원. (#58504)
• Agents/failover: 동일 provider 인증 프로필 재시도 상한 추가, auth.cooldowns.rateLimitedProfileRotations 설정 노출. (#58707)
• Telegram/errors: errorPolicy 및 errorCooldownMs 설정으로 계정·채팅·토픽별 반복 전송 오류 억제 지원. (#51914)
• ZAI/models: glm-5.1, glm-5v-turbo를 번들 Z.AI provider 카탈로그에 추가. (#58793)

Version 2026.3.31 (2026-03-31)

Breaking 변경사항

• Nodes/exec: CLI 및 에이전트 nodes 도구에서 중복 nodes.run 셸 래퍼 제거, 노드 셸 실행은 exec host=node로 통일.
• Plugin SDK: 레거시 provider 호환 서브패스 및 번들 provider 설정 shim 제거, openclaw/plugin-sdk/* 엔트리포인트 사용 권장.
• Skills/install and Plugins/install: 위험 코드 critical 발견 시 기본 설치 실패, 계속하려면 --dangerously-force-unsafe-install 명시 필요.
• Gateway/auth: trusted-proxy에서 혼합 공유 토큰 설정 거부, 로컬 직접 폴백에 설정된 토큰 필요.
• Gateway/node commands: 노드 페어링 승인 전까지 노드 명령 비활성화. (#57777)

변경사항

• Agents/LLM: 임베디드 runner 요청에 설정 가능한 유휴 스트림 타임아웃 추가로 중단된 모델 스트림 정리. (#55072)
• Agents/MCP: MCP 도구에 serverName__toolName 형식 provider 안전 이름 적용, streamable-http 전송 선택 및 per-server 연결 타임아웃 지원. (#49505)
• ACP/plugins: 기본 비활성화 ACPX 플러그인 도구 MCP 브리지 설정 추가, 글로벌 설치 및 stdio MCP 세션 신뢰성 개선. (#56867)
• Android/notifications: 패키지 필터링이 포함된 알림 전달 제어 추가.

Version 2026.3.28 (2026-03-29)

Breaking 변경사항

• Providers/Qwen: 레거시 qwen-portal-auth OAuth 통합 제거. openclaw onboard --auth-choice modelstudio-api-key로 마이그레이션. (#52709)
• Config/Doctor: 2개월 이상 된 자동 설정 마이그레이션 제거, 아주 오래된 레거시 키는 로드 또는 doctor 실행 시 마이그레이션 대신 검증 오류 발생.

변경사항

• xAI/tools: 번들 xAI provider를 Responses API로 이전, x_search 1등급 지원 추가 및 xAI 플러그인 자동 활성화. (#56048)
• MiniMax: image-01 모델용 이미지 생성 provider 추가 (가로세로비 제어, image-to-image 편집 지원). (#54487)
• Plugins/hooks: before_tool_call 훅에 비동기 requireApproval 추가로 도구 실행 일시 중단 및 exec 승인 오버레이·Telegram 버튼·/approve 명령을 통한 사용자 승인 요청 지원. (#55339)
• OpenAI/apply_patch: OpenAI 및 OpenAI Codex 모델에서 apply_patch 기본 활성화.
• Plugins/CLI backends: Gemini CLI 백엔드 지원 추가, Claude CLI/Codex CLI/Gemini CLI를 플러그인 레이어로 이전. 수동 plugins.allow 항목 불필요.

Version 2026.3.24 (2026-03-25)

변경사항

• Microsoft Teams: 공식 Teams SDK로 마이그레이션, AI 에이전트 UX 모범 사례 적용 (1:1 DM 스트리밍 응답, 프롬프트 스타터 포함 환영 카드, 피드백/성찰, 안내형 상태 업데이트, 타이핑 표시, 네이티브 AI 레이블링). (#51808)
• Microsoft Teams: 전송된 메시지 편집·삭제 기능 추가. (#49925)
• CLI/containers: --container 및 OPENCLAW_CONTAINER 환경 변수 추가로 실행 중인 Docker/Podman OpenClaw 컨테이너 내에서 명령 실행 지원. (#52651)
• Gateway/OpenAI compatibility: /v1/models, /v1/embeddings 추가, /v1/chat/completions·/v1/responses에서 명시적 모델 오버라이드 전달.
• Discord/auto threads: autoThreadName: "generated" 옵션으로 LLM 생성 스레드 이름 비동기 적용 지원. (#43366)
• Skills/install metadata: 번들 스킬(coding-agent, gh-issues, openai-whisper-api 등)에 원클릭 설치 레시피 추가. (#53411)

Version 2026.3.23 (2026-03-23)

변경사항

• ModelStudio/Qwen: 중국 및 글로벌 Qwen API 키용 표준 DashScope 엔드포인트 추가, provider 그룹명을 Qwen (Alibaba Cloud Model Studio)로 변경. (#43878)
• UI/clarity: 버튼 프리미티브 통합, Knot 테마를 WCAG 2.1 AA 대비의 블랙-레드 팔레트로 개선, CSP script-src에 인라인 스크립트 SHA-256 해시 추가. (#53272, #53307)

버그 수정

• Plugins/bundled runtimes: npm 전역 설치에서 누락된 번들 플러그인 런타임 사이드카 파일 복구 (WhatsApp, Matrix 등).
• Auth/OpenAI tokens: Configure/Onboard 플로우에서 새로 저장된 자격 증명이 오래된 인메모리 값으로 되돌아가는 문제 수정. (#53207 수정)
• Plugins/ClawHub: 설치 시 현재 런타임 버전에 맞춰 플러그인 API 호환성 검사, 구식 1.2.0 상수로 인한 설치 실패 수정. (#53157)

Version 2026.3.22 (2026-03-23)

Breaking 변경사항

• Plugins/install: npm-safe 이름에 대해 ClawHub를 npm보다 우선 검색, ClawHub에 없는 경우에만 npm 폴백.
• Browser/Chrome MCP: 레거시 Chrome 확장 릴레이 경로 및 번들 확장 에셋 제거. openclaw doctor --fix로 existing-session/user로 마이그레이션.
• Tools/image generation: 번들 nano-banana-pro 스킬 래퍼 제거. 대신 agents.defaults.imageGenerationModel.primary 사용.
• Plugins/SDK: 공개 플러그인 SDK 표면을 openclaw/plugin-sdk/*로 변경, openclaw/extension-api 제거 (호환 심 없음).
• Config/env: 레거시 CLAWDBOT_* 및 MOLTBOT_* 환경 변수 호환 이름 제거.

변경사항

• Skills/skills 명령: ClawHub 네이티브 검색·설치·업데이트 플로우 지원 추가.
• Chat command//btw: 현재 세션 컨텍스트 변경 없이 빠른 답변을 얻는 사이드 질문 채팅 명령 추가.
• Plugins/Matrix: 공식 matrix-js-sdk 기반 새 Matrix 플러그인 추가. 기존 공개 Matrix 플러그인 사용자는 마이그레이션 가이드 참고.

Version 1.0.0 (2026-03-16)

한국어 가이드 마이그레이션

한국어 가이드 최초 마이그레이션 — 54개 파일

기존 openclaw-guide/docs/에서 src/content/guides/openclaw/로 54개 가이드 파일 마이그레이션 완료.

마이그레이션된 섹션

• 시작하기 (oc-getting-started): 설치, 첫 메시지, 기본 개념
• 채널 - 주요 (oc-channels-main): Slack, Telegram, Discord, WhatsApp
• 채널 - 추가 (oc-channels-more): BlueBubbles, Line, Telegram Groups, Kakao, IRC, Feishu, Google Chat, Zalo, Instagram, Mattermost, Nextcloud, YouTube, VoIP/SIP, Teams, Discord Advanced
• 자동화 (oc-automation): Heartbeat, Cron, Use Cases
• 스킬 (oc-skills): 개요, 기본 사용, 커스텀 개발, 라이브러리
• 워크스페이스 (oc-workspace): 구조, 메모리 시스템, 모범 사례
• 고급 (oc-advanced): 서브 에이전트, 브라우저 자동화, 멀티 모델, 보안
• 참고 (oc-reference): CLI 명령어, 설정 파일, 환경 변수
• 문제 해결 (oc-troubleshooting): 일반 오류
• 부록 (oc-appendix): 용어 사전, 변경 이력, 외부 자료

Version 0.1.0 (2026-02-23)

초기 릴리스

초기 한국어 가이드 문서 공개

추가된 문서

시작하기 (01-getting-started)

• installation.md - 설치 가이드 (Desktop, Docker, CLI)
• first-message.md - 첫 메시지 보내기
• basic-concepts.md - 기본 개념 (Gateway, Session, Agent)

채널 설정 (02-channels)

• overview.md - 채널 개요 및 선택 가이드
• slack.md - Slack 설정 가이드
• telegram.md - Telegram 설정 가이드
• discord.md - Discord 설정 가이드

자동화 (03-automation)

• heartbeat.md - Heartbeat 기능 가이드
• cron.md - Cron 스케줄링 가이드
• use-cases.md - 실전 활용 예시

스킬 (04-skills)

• overview.md - 스킬 개요
• using-skills.md - 기본 스킬 사용법
• creating-skills.md - 커스텀 스킬 개발
• skill-library.md - 유용한 스킬 모음

워크스페이스 & 메모리 (05-workspace-memory)

• workspace.md - 워크스페이스 구조
• memory-system.md - 메모리 시스템 (QMD)
• best-practices.md - 모범 사례

고급 기능 (06-advanced)

• sub-agents.md - 서브 에이전트
• browser-automation.md - 브라우저 자동화 (Playwright)
• multi-model.md - 다중 모델 설정
• security.md - 보안 가이드

참고 문서 (07-reference)

• cli-commands.md - CLI 명령어 참조
• configuration.md - 설정 파일 참조

문제 해결 (08-troubleshooting)

• common-errors.md - 일반적인 오류 20개

부록 (09-appendix)

• glossary.md - 용어 사전
• changelog.md - 변경 이력 (이 문서)
• resources.md - 외부 자료 링크

특징

번역 원칙:

• Core Brand 용어 영어 유지 (OpenClaw, Gateway, ClawHub)
• 기술 개념 한국어 + 영어 병기 (워크스페이스(workspace))
• UI 요소 한국어 관습 따름 (설정, 채널)
• CLI 명령어 영어 유지

문서 스타일:

• Progressive Disclosure 패턴 적용
• Diátaxis Framework 기반 구조
• 코드 예시 포함
• 다이어그램/표 포함

변경 유형

피드백

문서 개선을 위한 피드백을 환영합니다!

• GitHub Issues: 버그 신고 및 기능 요청
• GitHub Pull Requests: 직접 기여
• Discord: OpenClaw 한국어 채널