openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh ko translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-14 06:01:01 +00:00
parent af3f63135c
commit 186fbb3279
2 changed files with 115 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
docs/ko/gateway/local-models.md
View File

@ -1,28 +1,28 @@
---
read_when:
- 자신의 GPU 머신에서 모델을 서빙하려는 경우
- LM Studio 또는 OpenAI 호환 프록시를 연결하는 경우
- 가장 안전한 로컬 모델 가이드가 필요한 경우
summary: 로컬 LLM(LM Studio, vLLM, LiteLLM, 사용자 지정 OpenAI 엔드포인트)에서 OpenClaw 실행하기
- 자체 GPU 머신에서 모델을 제공하려고 합니다.
- LM Studio 또는 OpenAI 호환 프록시를 연결하고 있습니다.
- 가장 안전한 로컬 모델 가이드가 필요합니다.
summary: 로컬 LLM에서 OpenClaw 실행하기(LM Studio, vLLM, LiteLLM, 사용자 지정 OpenAI 엔드포인트)
title: 로컬 모델
x-i18n:
generated_at: "2026-04-13T08:50:33Z"
generated_at: "2026-04-14T06:00:25Z"
model: gpt-5.4
provider: openai
source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a
source_hash: 1544c522357ba4b18dfa6d05ea8d60c7c6262281b53863d9aee7002464703ca7
source_path: gateway/local-models.md
workflow: 15
---
# 로컬 모델
로컬에서도 가능하지만, OpenClaw는 **큰 컨텍스트**와 프롬프트 인젝션에 대한 **강력한 방어**를 기대합니다. 작은 GPU 카드에서는 컨텍스트가 잘리고 안전성이 약해집니다. 목표는 높게 잡으세요: **최소 2대의 풀옵션 Mac Studio 또는 그에 준하는 GPU 장비(약 $30k 이상)**. **24 GB** GPU 1대로도 가능하긴 하지만, 더 가벼운 프롬프트에서만 가능하며 지연 시간도 더 높습니다. 실행 가능한 범위에서 **가장 크고 전체 크기의 모델 변형**을 사용하세요. 과도하게 양자화된 체크포인트나 “small” 모델은 프롬프트 인젝션 위험을 높입니다([보안](/ko/gateway/security) 참고).
로컬에서도 가능하지만, OpenClaw는 **큰 컨텍스트**와 **프롬프트 인젝션에 대한 강력한 방어**를 기대합니다. 성능이 낮은 GPU는 컨텍스트를 잘라내고 안전성을 약화시킵니다. 높은 사양을 목표로 하세요: **최소 2대의 풀사양 Mac Studio 또는 이에 준하는 GPU 장비(약 $30k 이상)**. 단일 **24GB** GPU는 더 가벼운 프롬프트에서만 동작하며 지연 시간도 더 높습니다. 실행 가능한 범위에서 **가장 크고 완전한 모델 변형**을 사용하세요. 과도하게 양자화된 체크포인트나 “small” 체크포인트는 프롬프트 인젝션 위험을 높입니다([보안](/ko/gateway/security) 참고).
가장 마찰이 적은 로컬 설정을 원한다면 [LM Studio](/ko/providers/lmstudio) 또는 [Ollama](/ko/providers/ollama)로 시작한 뒤 `openclaw onboard`를 실행하세요. 이 페이지는 더 높은 사양의 로컬 스택과 사용자 지정 OpenAI 호환 로컬 서버를 위한 의견이 반영된 가이드입니다.
가장 마찰이 적은 로컬 설정을 원한다면 [LM Studio](/ko/providers/lmstudio) 또는 [Ollama](/ko/providers/ollama)로 시작하고 `openclaw onboard`를 실행하세요. 이 페이지는 더 고급 로컬 스택과 사용자 지정 OpenAI 호환 로컬 서버를 위한 권장 가이드입니다.
## 권장: LM Studio + 대형 로컬 모델 (Responses API)
## 권장: LM Studio + 대형 로컬 모델(Responses API)
현재 기준으로 가장 좋은 로컬 스택입니다. LM Studio에 대형 모델(예: 전체 크기의 Qwen, DeepSeek, 또는 Llama 빌드)을 로드하고, 로컬 서버(기본값 `http://127.0.0.1:1234`)를 활성화한 뒤, Responses API를 사용해 추론과 최종 텍스트를 분리하세요.
현재 기준으로 가장 좋은 로컬 스택입니다. LM Studio에 대형 모델(예: 풀사이즈 Qwen, DeepSeek, 또는 Llama 빌드)을 로드하고, 로컬 서버(기본값 `http://127.0.0.1:1234`)를 활성화한 다음, Responses API를 사용해 추론과 최종 텍스트를 분리하세요.
```json5
{
@ -62,13 +62,13 @@ x-i18n:
**설정 체크리스트**
- LM Studio 설치: [https://lmstudio.ai](https://lmstudio.ai)
- LM Studio에서 **사용 가능한 가장 큰 모델 빌드**를 다운로드하고(“small”/강한 양자화 변형은 피하세요), 서버를 시작한 다음 `http://127.0.0.1:1234/v1/models`에 해당 모델이 표시되는지 확인합니다.
- `my-local-model`을 LM Studio에 표시된 실제 모델 ID로 바꾸세요.
- LM Studio에서 **사용 가능한 가장 큰 모델 빌드**를 다운로드하고(“small” 또는 심하게 양자화된 변형은 피하세요), 서버를 시작한 뒤 `http://127.0.0.1:1234/v1/models`에 해당 모델이 표시되는지 확인하세요.
- `my-local-model`을 LM Studio에 표시되는 실제 모델 ID로 바꾸세요.
- 모델을 계속 로드된 상태로 유지하세요. 콜드 로드는 시작 지연을 추가합니다.
- LM Studio 빌드가 다르면 `contextWindow`와 `maxTokens`를 조정하세요.
- LM Studio 빌드가 다르다면 `contextWindow`와 `maxTokens`를 조정하세요.
- WhatsApp에서는 최종 텍스트만 전송되도록 Responses API를 사용하세요.
로컬로 실행하더라도 호스팅 모델 구성은 유지하세요. `models.mode: "merge"`를 사용하면 폴백이 계속 사용 가능합니다.
로컬로 실행하더라도 호스팅 모델 설정은 유지하세요. `models.mode: "merge"`를 사용하면 폴백을 계속 사용할 수 있습니다.
### 하이브리드 구성: 호스팅 모델을 기본으로, 로컬 모델을 폴백으로
@ -113,16 +113,16 @@ x-i18n:
### 로컬 우선, 호스팅 모델을 안전망으로 사용
기본 모델과 폴백 순서를 바꾸면 됩니다. 동일한 providers 블록과 `models.mode: "merge"`를 유지하면 로컬 머신이 내려갔을 때 Sonnet 또는 Opus로 폴백할 수 있습니다.
기본 모델과 폴백 순서를 바꾸면 됩니다. 같은 providers 블록과 `models.mode: "merge"`를 유지하면 로컬 장비가 다운되었을 때 Sonnet 또는 Opus로 폴백할 수 있습니다.
### 지역별 호스팅 / 데이터 라우팅
- 호스팅되는 MiniMax/Kimi/GLM 변형도 OpenRouter에서 지역 고정 엔드포인트(예: 미국 호스팅)로 제공됩니다. 선택한 관할 구역 내에서 트래픽을 유지하려면 해당 지역 변형을 선택하고, Anthropic/OpenAI 폴백은 계속 사용할 수 있도록 `models.mode: "merge"`를 유지하세요.
- 완전한 로컬 전용이 가장 강력한 프라이버시 경로입니다. 호스팅된 지역 라우팅은 공급자 기능이 필요하지만 데이터 흐름을 통제하고 싶을 때의 중간 지점입니다.
- 호스팅된 MiniMax/Kimi/GLM 변형도 지역 고정 엔드포인트(예: 미국 호스팅)를 통해 OpenRouter에서 사용할 수 있습니다. 트래픽을 원하는 관할 구역 내에 유지하려면 해당 지역 변형을 선택하고, Anthropic/OpenAI 폴백을 계속 사용할 수 있도록 `models.mode: "merge"`를 유지하세요.
- 로컬 전용이 가장 강력한 개인정보 보호 경로입니다. 호스팅 지역 라우팅은 공급자 기능이 필요하지만 데이터 흐름도 통제하고 싶을 때의 중간 지점입니다.
## 기타 OpenAI 호환 로컬 프록시
vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 게이트웨이도 OpenAI 스타일의 `/v1` 엔드포인트를 노출하면 사용할 수 있습니다. 위의 provider 블록을 여러분의 엔드포인트와 모델 ID로 바꾸세요.
vLLM, LiteLLM, OAI-proxy, 또는 사용자 지정 Gateway도 OpenAI 스타일 `/v1` 엔드포인트를 제공하면 사용할 수 있습니다. 위 provider 블록을 자신의 엔드포인트와 모델 ID로 바꾸세요.
```json5
{
@ -152,23 +152,24 @@ vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 게이트웨이도 OpenAI 스
호스팅 모델을 폴백으로 계속 사용할 수 있도록 `models.mode: "merge"`를 유지하세요.
로컬/프록시 `/v1` 백엔드의 동작 참고 사항:
로컬/프록시 `/v1` 백엔드에 대한 동작 참고 사항:
- OpenClaw는 이를 네이티브 OpenAI 엔드포인트가 아니라 프록시 스타일의 OpenAI 호환 경로로 처리합니다.
- 여기에는 OpenAI 전용 요청 형태 조정이 적용되지 않습니다. 즉, `service_tier`, Responses `store`, OpenAI 추론 호환 페이로드 조정, 프롬프트 캐시 힌트가 없습니다.
- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)도 이러한 사용자 지정 프록시 URL에는 주입되지 않습니다.
- OpenClaw는 이를 네이티브 OpenAI 엔드포인트가 아니라 프록시 스타일의 OpenAI 호환 라우트로 처리합니다.
- 네이티브 OpenAI 전용 요청 구성은 여기에는 적용되지 않습니다. 즉, `service_tier`, Responses `store`, OpenAI 추론 호환 페이로드 구성, 프롬프트 캐시 힌트는 사용되지 않습니다.
- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)는 이러한 사용자 지정 프록시 URL에 주입되지 않습니다.
더 엄격한 OpenAI 호환 백엔드를 위한 호환성 참고 사항:
더 엄격한 OpenAI 호환 백엔드에 대한 호환성 참고 사항:
- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 `messages[].content`만 허용합니다. 그런 엔드포인트에는 `models.providers.<provider>.models[].compat.requiresStringContent: true`를 설정하세요.
- 더 작거나 더 엄격한 일부 로컬 백엔드는, 특히 도구 스키마가 포함될 때 OpenClaw의 전체 에이전트 런타임 프롬프트 형태에서 불안정할 수 있습니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에서는 동작하지만 일반적인 OpenClaw 에이전트 턴에서는 실패한다면, 먼저 `models.providers.<provider>.models[].compat.supportsTools: false`를 시도하세요.
- 백엔드가 더 큰 OpenClaw 실행에서만 계속 실패한다면, 남은 문제는 보통 OpenClaw의 전송 계층이 아니라 업스트림 모델/서버 용량 또는 백엔드 버그입니다.
- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 `messages[].content`만 허용합니다. 이런 엔드포인트에는 `models.providers.<provider>.models[].compat.requiresStringContent: true`를 설정하세요.
- 일부 더 작거나 더 엄격한 로컬 백엔드는 OpenClaw의 전체 에이전트 런타임 프롬프트 형태, 특히 tool 스키마가 포함된 경우에 불안정할 수 있습니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에서는 동작하지만 일반적인 OpenClaw 에이전트 턴에서는 실패한다면, 먼저 `models.providers.<provider>.models[].compat.supportsTools: false`를 시도하세요.
- 더 큰 OpenClaw 실행에서만 백엔드가 계속 실패한다면, 남은 문제는 대개 OpenClaw의 전송 계층이 아니라 업스트림 모델/서버 용량 또는 백엔드 버그입니다.
## 문제 해결
- Gateway가 프록시에 연결 가능한가요? `curl http://127.0.0.1:1234/v1/models`.
- Gateway가 프록시에 연결할 수 있나요? `curl http://127.0.0.1:1234/v1/models`
- LM Studio 모델이 언로드되었나요? 다시 로드하세요. 콜드 스타트는 “멈춘 것처럼 보이는” 흔한 원인입니다.
- 컨텍스트 오류가 나나요? `contextWindow`를 낮추거나 서버 제한을 올리세요.
- OpenClaw는 감지된 컨텍스트 윈도우가 **32k** 미만이면 경고하고 **16k** 미만이면 차단합니다. 이 사전 점검에 걸린다면 서버/모델의 컨텍스트 한도를 늘리거나 더 큰 모델을 선택하세요.
- 컨텍스트 오류가 발생하나요? `contextWindow`를 낮추거나 서버 한도를 높이세요.
- OpenAI 호환 서버가 `messages[].content ... expected a string`을 반환하나요? 해당 모델 항목에 `compat.requiresStringContent: true`를 추가하세요.
- 작은 직접 `/v1/chat/completions` 호출은 동작하지만 `openclaw infer model run`이 Gemma 또는 다른 로컬 모델에서 실패하나요? 먼저 `compat.supportsTools: false`로 도구 스키마를 비활성화한 뒤 다시 테스트하세요. 서버가 더 큰 OpenClaw 프롬프트에서만 계속 충돌한다면, 이를 업스트림 서버/모델 제한으로 취급하세요.
- 안전성: 로컬 모델은 공급자 측 필터를 건너뜁니다. 프롬프트 인젝션의 영향 범위를 제한하려면 에이전트 범위를 좁게 유지하고 Compaction을 켜 두세요.
- 작은 직접 `/v1/chat/completions` 호출은 동작하지만 `openclaw infer model run`이 Gemma 또는 다른 로컬 모델에서 실패하나요? 먼저 `compat.supportsTools: false`로 tool 스키마를 비활성화한 뒤 다시 테스트하세요. 이후에도 더 큰 OpenClaw 프롬프트에서만 서버가 크래시한다면, 업스트림 서버/모델의 한계로 간주하세요.
- 안전성: 로컬 모델은 공급자 측 필터를 건너뜁니다. 프롬프트 인젝션 영향 범위를 제한하려면 에이전트 범위를 좁게 유지하고 Compaction을 켜 두세요.

198
docs/ko/reference/RELEASING.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 공개 릴리스 채널 정의를 찾고 있습니다
- 버전 명명과 출시 주기를 찾고 있습니다
- 버전 명명 및 출시 주기를 찾고 있습니다
summary: 공개 릴리스 채널, 버전 명명, 및 출시 주기
title: 릴리스 정책
x-i18n:
generated_at: "2026-04-14T02:08:44Z"
generated_at: "2026-04-14T06:00:23Z"
model: gpt-5.4
provider: openai
source_hash: fdc32839447205d74ba7a20a45fbac8e13b199174b442a1e260e3fce056c63da
source_hash: 3eaf9f1786b8c9fd4f5a9c657b623cb69d1a485958e1a9b8f108511839b63587
source_path: reference/RELEASING.md
workflow: 15
---
@ -17,9 +17,9 @@ x-i18n:
OpenClaw에는 세 가지 공개 릴리스 레인이 있습니다.
- stable: 기본적으로 npm `beta`에 게시되는 태그된 릴리스이며, 명시적으로 요청된 경우 npm `latest`에 게시됩니다
- beta: npm `beta`에 게시되는 프리릴리스 태그입니다
- dev: `main`의 이동하는 헤드입니다
- stable: 기본적으로 npm `beta`에 게시되는 태그 릴리스이며, 명시적으로 요청된 경우 npm `latest`에 게시됩니다.
- beta: npm `beta`에 게시되는 프리릴리스 태그
- dev: `main`의 이동하는 최신 헤드
## 버전 명명
@ -29,141 +29,111 @@ OpenClaw에는 세 가지 공개 릴리스 레인이 있습니다.
- Git 태그: `vYYYY.M.D-N`
- Beta 프리릴리스 버전: `YYYY.M.D-beta.N`
- Git 태그: `vYYYY.M.D-beta.N`
- 월이나 일에 0을 앞에 붙이지 마세요
- `latest`는 현재 승격된 stable npm 릴리스를 의미합니다
- `beta`는 현재 beta 설치 대상을 의미합니다
- Stable 및 stable 수정 릴리스는 기본적으로 npm `beta`에 게시되며, 릴리스 운영자는 명시적으로 `latest`를 대상으로 지정하거나 나중에 검증된 beta 빌드를 승격할 수 있습니다
- 모든 OpenClaw 릴리스는 npm 패키지와 macOS 앱을 함께 배포합니다
- 월이나 일은 0으로 채우지 마세요.
- `latest`는 현재 승격된 stable npm 릴리스를 의미합니다.
- `beta`는 현재 beta 설치 대상을 의미합니다.
- Stable 및 stable 수정 릴리스는 기본적으로 npm `beta`에 게시됩니다. 릴리스 운영자는 명시적으로 `latest`를 대상으로 지정하거나, 검증된 beta 빌드를 나중에 승격할 수 있습니다.
- 모든 OpenClaw 릴리스는 npm 패키지와 macOS 앱을 함께 제공합니다.
## 릴리스 주기
- 릴리스는 beta 우선으로 진행됩니다
- Stable은 최신 beta가 검증된 후에만 이어집니다
- 자세한 릴리스 절차, 승인, 자격 증명 및 복구 참고 사항은
maintainer 전용입니다
- 릴리스는 beta 우선으로 진행됩니다.
- Stable은 최신 beta가 검증된 후에만 이어집니다.
- 자세한 릴리스 절차, 승인, 자격 증명, 복구 참고 사항은
maintainer 전용입니다.
## 릴리스 사전 점검
- pack 검증 단계에 필요한 `dist/*` 릴리스 아티팩트와 Control UI 번들이 존재하도록 `pnpm release:check` 전에 `pnpm build && pnpm ui:build`를 실행하세요
- 모든 태그된 릴리스 전에 `pnpm release:check`를 실행하세요
- 이제 릴리스 검사는 별도의 수동 워크플로에서 실행됩니다:
- pack 검증 단계에서 예상되는 `dist/*` 릴리스 아티팩트와 Control UI 번들이 존재하도록 `pnpm release:check` 전에 `pnpm build && pnpm ui:build`를 실행하세요.
- 모든 태그 릴리스 전에 `pnpm release:check`를 실행하세요.
- 릴리스 검사는 이제 별도의 수동 워크플로에서 실행됩니다.
`OpenClaw Release Checks`
- 이 분리는 의도된 것입니다. 실제 npm 릴리스 경로는 짧고,
결정적이며 아티팩트 중심으로 유지하고, 더 느린 라이브 검사는
자체 레인에 두어 게시를 지연시키거나 차단하지 않도록 합니다
- 릴리스 검사 워크플로는 워크플로 로직과 시크릿이 정본 상태를 유지하도록
`main` 워크플로 ref에서 디스패치되어야 합니다
- 이 워크플로는 기존 릴리스 태그 또는 현재 전체
40자 `main` 커밋 SHA 중 하나를 허용합니다
- 커밋 SHA 모드에서는 현재 `origin/main` HEAD만 허용되며,
이전 릴리스 커밋에는 릴리스 태그를 사용하세요
- `OpenClaw NPM Release` 검증 전용 사전 점검도 푸시된 태그 없이
현재 전체 40자 `main` 커밋 SHA를 허용합니다
- 이 SHA 경로는 검증 전용이며 실제 게시로 승격될 수 없습니다
- SHA 모드에서는 워크플로가 패키지 메타데이터 확인을 위해서만
`v<package.json version>`을 합성하며, 실제 게시에는 여전히 실제 릴리스 태그가 필요합니다
- 두 워크플로 모두 실제 게시 및 승격 경로는 GitHub 호스팅 러너에서 유지하고,
상태를 변경하지 않는 검증 경로는 더 큰
Blacksmith Linux 러너를 사용할 수 있습니다
- 이 워크플로는
결정적이며, 아티팩트 중심으로 유지하고, 더 느린 라이브 검사는
별도 레인에 유지하여 게시를 지연시키거나 차단하지 않도록 합니다.
- 릴리스 검사는 워크플로 로직과 비밀 정보가 정식 상태를 유지하도록 `main` 워크플로 ref에서 디스패치되어야 합니다.
- 이 워크플로는 기존 릴리스 태그 또는 현재 전체 40자 `main` 커밋 SHA 중 하나를 받을 수 있습니다.
- 커밋 SHA 모드에서는 현재 `origin/main` HEAD만 허용합니다. 이전 릴리스 커밋에는 릴리스 태그를 사용하세요.
- `OpenClaw NPM Release` 검증 전용 사전 점검도 푸시된 태그 없이 현재 전체 40자 `main` 커밋 SHA를 받을 수 있습니다.
- 이 SHA 경로는 검증 전용이며 실제 게시로 승격할 수 없습니다.
- SHA 모드에서 워크플로는 패키지 메타데이터 검사에만 `v<package.json version>`을 합성합니다. 실제 게시에는 여전히 실제 릴리스 태그가 필요합니다.
- 두 워크플로 모두 실제 게시 및 승격 경로는 GitHub 호스팅 러너에서 유지하고, 상태를 변경하지 않는 검증 경로는 더 큰 Blacksmith Linux 러너를 사용할 수 있습니다.
- 해당 워크플로는
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
를 `OPENAI_API_KEY` 및 `ANTHROPIC_API_KEY` 워크플로 시크릿 둘 다를 사용해 실행합니다
- npm 릴리스 사전 점검은 더 이상 별도의 릴리스 검사 레인을 기다리지 않습니다
- 승인 전에
`RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(또는 해당하는 beta/수정 태그) 를 실행하세요
- npm 게시 후, 새 임시 prefix에서 게시된 레지스트리 설치 경로를 검증하려면
를 `OPENAI_API_KEY` 및 `ANTHROPIC_API_KEY` 워크플로 비밀 정보를 모두 사용하여 실행합니다.
- npm 릴리스 사전 점검은 더 이상 별도의 릴리스 검사 레인을 기다리지 않습니다.
- 승인 전에 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(또는 해당하는 beta/수정 태그) 를 실행하세요.
- npm 게시 후에는
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(또는 해당하는 beta/수정 버전) 를 실행하세요
- 이제 maintainer 릴리스 자동화는 사전 점검 후 승격 방식을 사용합니다:
- 실제 npm 게시에는 성공한 npm `preflight_run_id`가 필요합니다
- stable npm 릴리스는 기본적으로 `beta`를 대상으로 합니다
- stable npm 게시에서는 워크플로 입력을 통해 명시적으로 `latest`를 대상으로 지정할 수 있습니다
- stable npm을 `beta`에서 `latest`로 승격하는 기능은 신뢰된 `OpenClaw NPM Release` 워크플로의 명시적 수동 모드로 여전히 제공됩니다
- 직접 stable 게시에서는 이미 게시된 stable 버전에 `latest`와 `beta`를 모두 가리키는 명시적 dist-tag 동기화 모드도 실행할 수 있습니다
- 이러한 dist-tag 모드에는 npm `dist-tag` 관리가 신뢰된 게시와 별개이므로 `npm-release` 환경에 유효한 `NPM_TOKEN`이 여전히 필요합니다
- 공개 `macOS Release`는 검증 전용입니다
(또는 해당하는 beta/수정 버전) 를 실행하여 새 임시 prefix에서 게시된 레지스트리 설치 경로를 검증하세요.
- 이제 maintainer 릴리스 자동화는 사전 점검 후 승격 방식을 사용합니다.
- 실제 npm 게시에는 성공한 npm `preflight_run_id`가 필요합니다.
- stable npm 릴리스는 기본적으로 `beta`를 대상으로 합니다.
- stable npm 게시에서는 워크플로 입력을 통해 명시적으로 `latest`를 대상으로 지정할 수 있습니다.
- `beta`에서 `latest`로의 stable npm 승격은 신뢰된 `OpenClaw NPM Release` 워크플로에서 여전히 명시적인 수동 모드로 사용할 수 있습니다.
- 직접 stable 게시에서는 이미 게시된 stable 버전에 `latest`와 `beta`를 모두 가리키는 명시적 dist-tag 동기화 모드도 실행할 수 있습니다.
- 이러한 dist-tag 모드에도 npm `dist-tag` 관리는 신뢰된 게시와 별개이므로 `npm-release` 환경에 유효한 `NPM_TOKEN`이 여전히 필요합니다.
- 공개 `macOS Release`는 검증 전용입니다.
- 실제 비공개 mac 게시에는 성공한 비공개 mac
`preflight_run_id` 및 `validate_run_id`가 필요합니다
- 실제 게시 경로는 아티팩트를 다시 빌드하는 대신 준비된 아티팩트를 승격합니다
- `YYYY.M.D-N`과 같은 stable 수정 릴리스의 경우, 게시 후 검증기는
동일한 임시 prefix 업그레이드 경로를 `YYYY.M.D`에서 `YYYY.M.D-N`까지도 확인하므로
릴리스 수정으로 인해 이전 전역 설치가 기본 stable 페이로드에
조용히 머무르는 일이 없도록 합니다
- npm 릴리스 사전 점검은 tarball에 `dist/control-ui/index.html`과 비어 있지 않은 `dist/control-ui/assets/` 페이로드가 모두 포함되지 않으면 실패로 종료되므로
빈 브라우저 대시보드를 다시 배포하지 않도록 합니다
- 릴리스 작업이 CI 계획, extension 타이밍 매니페스트 또는
extension 테스트 매트릭스에 영향을 주었다면, 승인 전에
릴리스 노트가 오래된 CI 레이아웃을 설명하지 않도록 `.github/workflows/ci.yml`의 planner 소유
`checks-node-extensions` 워크플로 매트릭스 출력을 재생성하고 검토하세요
- Stable macOS 릴리스 준비 상태에는 업데이터 관련 표면도 포함됩니다:
- GitHub 릴리스에는 패키징된 `.zip`, `.dmg`, `.dSYM.zip`이 포함되어야 합니다
- 게시 후 `main`의 `appcast.xml`은 새 stable zip을 가리켜야 합니다
- 패키징된 앱은 디버그가 아닌 번들 ID, 비어 있지 않은 Sparkle 피드 URL,
그리고 해당 릴리스 버전에 대한 정규 Sparkle 빌드 하한 이상인 `CFBundleVersion`을 유지해야 합니다
`preflight_run_id` 및 `validate_run_id`가 필요합니다.
- 실제 게시 경로는 아티팩트를 다시 빌드하는 대신 준비된 아티팩트를 승격합니다.
- `YYYY.M.D-N`과 같은 stable 수정 릴리스의 경우, 게시 후 검증기는 `YYYY.M.D`에서 `YYYY.M.D-N`으로의 동일한 임시 prefix 업그레이드 경로도 검사하므로 릴리스 수정이 이전 전역 설치를 기본 stable 페이로드에 조용히 남겨두는 일이 없도록 합니다.
- npm 릴리스 사전 점검은 tarball에 `dist/control-ui/index.html`과 비어 있지 않은 `dist/control-ui/assets/` 페이로드가 모두 포함되지 않으면 폐쇄적으로 실패하므로 빈 브라우저 대시보드를 다시 배포하지 않도록 합니다.
- `pnpm test:install:smoke`도 후보 업데이트 tarball에 대해 npm pack `unpackedSize` 예산을 강제하므로 설치 프로그램 e2e가 릴리스 게시 경로 전에 우발적인 pack 비대화를 포착합니다.
- 릴리스 작업이 CI 계획, 확장 타이밍 매니페스트 또는 확장 테스트 매트릭스에 영향을 주었다면 승인 전에 `.github/workflows/ci.yml`의 planner 소유 `checks-node-extensions` 워크플로 매트릭스 출력을 재생성하고 검토하세요. 그래야 릴리스 노트가 오래된 CI 레이아웃을 설명하지 않게 됩니다.
- Stable macOS 릴리스 준비 상태에는 업데이터 표면도 포함됩니다.
- GitHub 릴리스에는 패키징된 `.zip`, `.dmg`, `.dSYM.zip`이 최종적으로 포함되어야 합니다.
- `main`의 `appcast.xml`은 게시 후 새 stable zip을 가리켜야 합니다.
- 패키징된 앱은 디버그가 아닌 번들 ID, 비어 있지 않은 Sparkle 피드 URL, 그리고 해당 릴리스 버전에 대한 정식 Sparkle 빌드 기준 이상인 `CFBundleVersion`을 유지해야 합니다.
## NPM 워크플로 입력
`OpenClaw NPM Release`는 다음과 같은 운영자 제어 입력을 받습니다.
- `tag`: `v2026.4.2`, `v2026.4.2-1`, 또는
`v2026.4.2-beta.1` 같은 필수 릴리스 태그입니다. `preflight_only=true`일 때는 검증 전용 사전 점검을 위해 현재 전체
40자 `main` 커밋 SHA도 사용할 수 있습니다
`v2026.4.2-beta.1`과 같은 필수 릴리스 태그입니다. `preflight_only=true`일 때는 검증 전용 사전 점검을 위해 현재 전체 40자 `main` 커밋 SHA도 사용할 수 있습니다.
- `preflight_only`: 검증/빌드/패키지 전용이면 `true`, 실제 게시 경로이면 `false`
- `preflight_run_id`: 실제 게시 경로에서 필수이며, 워크플로가 성공한 사전 점검 실행에서 준비된 tarball을 재사용하도록 합니다
- `npm_dist_tag`: 게시 경로의 npm 대상 태그이며, 기본값은 `beta`입니다
- `promote_beta_to_latest`: 게시를 건너뛰고 이미 게시된
stable `beta` 빌드를 `latest`로 이동하려면 `true`
- `sync_stable_dist_tags`: 게시를 건너뛰고 이미 게시된 stable 버전에 `latest`와
`beta`를 모두 가리키게 하려면 `true`
- `preflight_run_id`: 실제 게시 경로에서 필수이며, 워크플로가 성공한 사전 점검 실행의 준비된 tarball을 재사용하도록 합니다.
- `npm_dist_tag`: 게시 경로용 npm 대상 태그이며, 기본값은 `beta`입니다.
- `promote_beta_to_latest`: 게시를 건너뛰고 이미 게시된 stable `beta` 빌드를 `latest`로 이동하려면 `true`
- `sync_stable_dist_tags`: 게시를 건너뛰고 이미 게시된 stable 버전에 `latest`와 `beta`를 모두 가리키게 하려면 `true`
`OpenClaw Release Checks`는 다음과 같은 운영자 제어 입력을 받습니다.
- `ref`: 검증할 기존 릴리스 태그 또는 현재 전체 40자 `main` 커밋
SHA
- `ref`: 검증할 기존 릴리스 태그 또는 현재 전체 40자 `main` 커밋 SHA
규칙:
- Stable 및 수정 태그는 `beta` 또는 `latest` 중 어느 쪽으로도 게시될 수 있습니다
- Beta 프리릴리스 태그는 `beta`로만 게시될 수 있습니다
- 전체 커밋 SHA 입력은 `preflight_only=true`일 때만 허용됩니다
- 릴리스 검사 커밋 SHA 모드도 현재 `origin/main` HEAD를 요구합니다
- 실제 게시 경로는 사전 점검에서 사용한 것과 동일한 `npm_dist_tag`를 사용해야 하며,
워크플로는 게시를 계속하기 전에 해당 메타데이터를 검증합니다
- Stable 및 수정 태그는 `beta` 또는 `latest` 중 하나에 게시할 수 있습니다.
- Beta 프리릴리스 태그는 `beta`에만 게시할 수 있습니다.
- 전체 커밋 SHA 입력은 `preflight_only=true`일 때만 허용됩니다.
- 릴리스 검사 커밋 SHA 모드도 현재 `origin/main` HEAD를 요구합니다.
- 실제 게시 경로는 사전 점검 중 사용한 것과 동일한 `npm_dist_tag`를 사용해야 하며, 워크플로는 게시를 계속하기 전에 해당 메타데이터를 검증합니다.
- 승격 모드는 stable 또는 수정 태그, `preflight_only=false`,
비어 있는 `preflight_run_id`, 그리고 `npm_dist_tag=beta`를 사용해야 합니다
- dist-tag 동기화 모드는 stable 또는 수정 태그,
`preflight_only=false`, 비어 있는 `preflight_run_id`, `npm_dist_tag=latest`,
그리고 `promote_beta_to_latest=false`를 사용해야 합니다
빈 `preflight_run_id`, 그리고 `npm_dist_tag=beta`를 사용해야 합니다.
- Dist-tag 동기화 모드는 stable 또는 수정 태그,
`preflight_only=false`, 빈 `preflight_run_id`, `npm_dist_tag=latest`,
및 `promote_beta_to_latest=false`를 사용해야 합니다.
- 승격 및 dist-tag 동기화 모드에도 유효한 `NPM_TOKEN`이 필요합니다.
npm `dist-tag add`는 여전히 일반 npm 인증이 필요하기 때문이며,
신뢰된 게시가 적용되는 것은 패키지 게시 경로뿐입니다
`npm dist-tag add`에는 여전히 일반 npm 인증이 필요하기 때문이며,
신뢰된 게시가 적용되는 것은 패키지 게시 경로뿐입니다.
## Stable npm 릴리스 순서
stable npm 릴리스를 만들 때:
stable npm 릴리스를 배포할 때:
1. `preflight_only=true`로 `OpenClaw NPM Release`를 실행합니다
- 태그가 아직 없으면 현재 전체 `main` 커밋 SHA를 사용하여
사전 점검 워크플로의 검증 전용 드라이 런을 수행할 수 있습니다
2. 일반적인 beta 우선 흐름에는 `npm_dist_tag=beta`를 선택하고,
의도적으로 직접 stable 게시를 원하는 경우에만 `latest`를 선택합니다
3. 라이브 프롬프트 캐시 커버리지를 원한다면 동일한 태그 또는
현재 전체 `main` 커밋 SHA로 `OpenClaw Release Checks`를 별도로 실행합니다
- 이는 라이브 커버리지를 계속 사용할 수 있게 하면서도
게시 워크플로와 오래 걸리거나 불안정한 검사를 다시 결합하지 않기 위한 의도적인 분리입니다
4. 성공한 `preflight_run_id`를 저장합니다
5. `preflight_only=false`, 동일한 `tag`, 동일한 `npm_dist_tag`,
그리고 저장한 `preflight_run_id`로 `OpenClaw NPM Release`를 다시 실행합니다
6. 릴리스가 `beta`에 도착했다면, 나중에 동일한 stable `tag`,
`promote_beta_to_latest=true`, `preflight_only=false`,
비어 있는 `preflight_run_id`, 그리고 `npm_dist_tag=beta`로
`OpenClaw NPM Release`를 실행하여 게시된 해당 빌드를 `latest`로 이동할 수 있습니다
7. 릴리스가 의도적으로 `latest`에 직접 게시되었고 `beta`도
동일한 stable 빌드를 따라야 한다면, 동일한 stable `tag`,
`sync_stable_dist_tags=true`, `promote_beta_to_latest=false`,
`preflight_only=false`, 비어 있는 `preflight_run_id`, 그리고 `npm_dist_tag=latest`로
`OpenClaw NPM Release`를 실행합니다
1. `preflight_only=true`로 `OpenClaw NPM Release`를 실행합니다.
- 태그가 아직 없으면 사전 점검 워크플로의 검증 전용 드라이 런을 위해 현재 전체 `main` 커밋 SHA를 사용할 수 있습니다.
2. 일반적인 beta 우선 흐름에는 `npm_dist_tag=beta`를 선택하고, 직접 stable 게시를 의도한 경우에만 `latest`를 선택합니다.
3. 라이브 프롬프트 캐시 범위를 원한다면 동일한 태그 또는 전체 현재 `main` 커밋 SHA로 `OpenClaw Release Checks`를 별도로 실행합니다.
- 장시간 실행되거나 불안정할 수 있는 검사를 게시 워크플로에 다시 결합하지 않으면서도 라이브 범위를 계속 사용할 수 있도록 이것은 의도적으로 분리되어 있습니다.
4. 성공한 `preflight_run_id`를 저장합니다.
5. `preflight_only=false`, 동일한 `tag`, 동일한 `npm_dist_tag`, 저장한 `preflight_run_id`로 `OpenClaw NPM Release`를 다시 실행합니다.
6. 릴리스가 `beta`에 게시되었다면, 나중에 동일한 stable `tag`, `promote_beta_to_latest=true`, `preflight_only=false`,
빈 `preflight_run_id`, 그리고 `npm_dist_tag=beta`로 `OpenClaw NPM Release`를 실행하여 해당 게시된 빌드를 `latest`로 이동합니다.
7. 릴리스가 의도적으로 `latest`에 직접 게시되었고 `beta`도 동일한 stable 빌드를 따라야 한다면, 동일한 stable `tag`, `sync_stable_dist_tags=true`, `promote_beta_to_latest=false`,
`preflight_only=false`, 빈 `preflight_run_id`, 그리고 `npm_dist_tag=latest`로 `OpenClaw NPM Release`를 실행합니다.
승격 및 dist-tag 동기화 모드에는 여전히 `npm-release`
환경 승인과 해당 워크플로 실행에서 접근 가능한 유효한 `NPM_TOKEN`이 필요합니다.
@ -179,6 +149,6 @@ stable npm 릴리스를 만들 때:
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
maintainer는 실제 런북을 위해
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)의
비공개 릴리스 문서를 사용합니다.
maintainer는 실제 실행 절차를 위해
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
의 비공개 릴리스 문서를 사용합니다.