chore(i18n): refresh ko translations

docs/ko/concepts/qa-e2e-automation.md

@@ -6,46 +6,38 @@ read_when:
 summary: qa-lab, qa-channel, 시드된 시나리오, 프로토콜 보고서를 위한 비공개 QA 자동화 구조
 title: QA E2E 자동화
 x-i18n:
-    generated_at: "2026-04-18T05:51:39Z"
+    generated_at: "2026-04-20T06:05:33Z"
     model: gpt-5.4
     provider: openai
-    source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
+    source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7
     source_path: concepts/qa-e2e-automation.md
     workflow: 15
 ---
 
 # QA E2E 자동화
 
-비공개 QA 스택은 단일 단위 테스트보다 더 현실적이고
-채널 형태에 가까운 방식으로 OpenClaw를 검증하기 위한 것입니다.
+비공개 QA 스택은 단일 단위 테스트보다 더 현실적이고 채널 형태에 가까운 방식으로 OpenClaw를 검증하기 위한 것입니다.
 
 현재 구성 요소:
 
-- `extensions/qa-channel`: DM, 채널, 스레드,
-  리액션, 수정, 삭제 기능 표면을 갖춘 합성 메시지 채널
-- `extensions/qa-lab`: 대화 내용을 관찰하고,
-  수신 메시지를 주입하며, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스
-- `qa/`: 시작 작업과 기본 QA
-  시나리오를 위한 리포지토리 기반 시드 자산
+- `extensions/qa-channel`: DM, 채널, 스레드, 리액션, 수정, 삭제 표면을 갖춘 합성 메시지 채널
+- `extensions/qa-lab`: 대화 내용을 관찰하고, 인바운드 메시지를 주입하며, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스
+- `qa/`: 시작 작업과 기본 QA 시나리오를 위한 리포지토리 기반 시드 자산
 
-현재 QA 운영자 흐름은 2분할 QA 사이트입니다:
+현재 QA 운영자 흐름은 2패널 QA 사이트입니다:
 
 - 왼쪽: 에이전트가 있는 Gateway 대시보드(Control UI)
-- 오른쪽: Slack 유사 대화 내용과 시나리오 계획을 보여주는 QA Lab
+- 오른쪽: Slack와 유사한 대화 내용과 시나리오 계획을 보여주는 QA Lab
 
-실행 방법:
+다음으로 실행합니다:
 
 ```bash
 pnpm qa:lab:up
 ```
 
-이 명령은 QA 사이트를 빌드하고, Docker 기반 gateway 레인을 시작하며,
-운영자 또는 자동화 루프가 에이전트에게 QA
-미션을 부여하고, 실제 채널 동작을 관찰하며, 무엇이 작동했고 실패했으며
-무엇이 계속 막혀 있었는지 기록할 수 있는 QA Lab 페이지를 노출합니다.
+이 명령은 QA 사이트를 빌드하고, Docker 기반 gateway 레인을 시작하며, 운영자나 자동화 루프가 에이전트에 QA 미션을 부여하고, 실제 채널 동작을 관찰하며, 무엇이 작동했고 실패했으며 계속 막혀 있었는지를 기록할 수 있는 QA Lab 페이지를 노출합니다.
 
-매번 Docker 이미지를 다시 빌드하지 않고 QA Lab UI를 더 빠르게 반복 개발하려면,
-바인드 마운트된 QA Lab 번들로 스택을 시작하세요:
+매번 Docker 이미지를 다시 빌드하지 않고 더 빠르게 QA Lab UI를 반복 개발하려면, bind-mounted QA Lab 번들로 스택을 시작하세요:
 
 ```bash
 pnpm openclaw qa docker-build-image
@@ -54,10 +46,7 @@ pnpm qa:lab:up:fast
 pnpm qa:lab:watch
 ```
 
-`qa:lab:up:fast`는 Docker 서비스를 사전 빌드된 이미지로 유지하고
-`extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 바인드 마운트합니다. `qa:lab:watch`는
-변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 바뀌면 브라우저가
-자동으로 다시 로드됩니다.
+`qa:lab:up:fast`는 미리 빌드된 이미지로 Docker 서비스를 유지하고 `extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 bind-mount합니다. `qa:lab:watch`는 변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 바뀌면 브라우저가 자동으로 다시 로드됩니다.
 
 전송 계층이 실제인 Matrix 스모크 레인을 실행하려면 다음을 사용하세요:
 
@@ -65,14 +54,7 @@ pnpm qa:lab:watch
 pnpm openclaw qa matrix
 ```
 
-이 레인은 Docker에서 일회용 Tuwunel homeserver를 프로비저닝하고, 임시
-driver, SUT, observer 사용자를 등록하고, 하나의 비공개 룸을 생성한 뒤,
-QA gateway child 내부에서 실제 Matrix Plugin을 실행합니다. 라이브 전송 레인은
-child 구성을 테스트 중인 전송 계층에 맞게 범위를 제한하므로, Matrix는
-child 구성에서 `qa-channel` 없이 실행됩니다. 선택한 Matrix QA 출력 디렉터리에
-구조화된 보고서 아티팩트와 결합된 stdout/stderr 로그를 기록합니다. 바깥쪽
-`scripts/run-node.mjs` 빌드/런처 출력도 함께 캡처하려면
-`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>`를 리포지토리 로컬 로그 파일로 설정하세요.
+이 레인은 Docker에서 일회용 Tuwunel 홈서버를 프로비저닝하고, 임시 드라이버, SUT, 옵저버 사용자를 등록하며, 하나의 비공개 방을 생성한 뒤, QA gateway 하위 프로세스 안에서 실제 Matrix Plugin을 실행합니다. 라이브 전송 레인은 테스트 중인 전송 계층에 맞게 하위 config 범위를 유지하므로, Matrix는 하위 config에서 `qa-channel` 없이 실행됩니다. 이 레인은 구조화된 보고서 아티팩트와 stdout/stderr 통합 로그를 선택한 Matrix QA 출력 디렉터리에 기록합니다. 외부 `scripts/run-node.mjs` 빌드/런처 출력까지 함께 수집하려면 `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>`를 리포지토리 로컬 로그 파일로 설정하세요.
 
 전송 계층이 실제인 Telegram 스모크 레인을 실행하려면 다음을 사용하세요:
 
@@ -80,132 +62,100 @@ child 구성에서 `qa-channel` 없이 실행됩니다. 선택한 Matrix QA 출
 pnpm openclaw qa telegram
 ```
 
-이 레인은 일회용 서버를 프로비저닝하는 대신 실제 비공개 Telegram 그룹 하나를 대상으로 합니다.
-이를 위해서는 `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
-`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`,
-`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`이 필요하며,
-동일한 비공개 그룹 안에 서로 다른 두 개의 봇이 있어야 합니다. SUT 봇에는 Telegram
-사용자명이 있어야 하며, 봇 간 관찰은 두 봇 모두 `@BotFather`에서
-Bot-to-Bot Communication Mode를 활성화했을 때 가장 잘 작동합니다.
+이 레인은 일회용 서버를 프로비저닝하는 대신 하나의 실제 비공개 Telegram 그룹을 대상으로 합니다. `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`이 필요하며, 같은 비공개 그룹에 서로 다른 두 개의 봇이 있어야 합니다. SUT 봇은 Telegram 사용자 이름을 가져야 하며, 두 봇 모두 `@BotFather`에서 Bot-to-Bot Communication Mode를 활성화했을 때 봇 간 관찰이 가장 잘 동작합니다.
+어떤 시나리오라도 실패하면 명령은 0이 아닌 종료 코드를 반환합니다. 실패 종료 코드 없이 아티팩트만 원한다면 `--allow-failures`를 사용하세요.
 
-이제 라이브 전송 레인들은 각자 고유한 시나리오 목록 형태를 만들지 않고,
-더 작고 공통된 하나의 계약을 공유합니다:
+이제 라이브 전송 레인은 각자 자체 시나리오 목록 구조를 만드는 대신 하나의 더 작은 계약을 공유합니다:
 
-`qa-channel`은 여전히 폭넓은 합성 제품 동작 스위트이며, 라이브 전송
-커버리지 매트릭스의 일부는 아닙니다.
+`qa-channel`은 여전히 폭넓은 합성 제품 동작 스위트이며 라이브 전송 커버리지 매트릭스에는 포함되지 않습니다.
 
-| 레인     | 카나리 | 멘션 게이팅 | 허용 목록 차단 | 최상위 답글 | 재시작 재개 | 스레드 후속 응답 | 스레드 격리 | 리액션 관찰 | 도움말 명령 |
-| -------- | ------ | ----------- | -------------- | ----------- | ----------- | ---------------- | ----------- | ----------- | ----------- |
-| Matrix   | x      | x           | x              | x           | x           | x                | x           | x           |             |
-| Telegram | x      |             |                |             |             |                  |             |             | x           |
+| 레인     | Canary | 멘션 게이팅 | 허용 목록 차단 | 최상위 답글 | 재시작 복구 | 스레드 후속 응답 | 스레드 격리 | 리액션 관찰 | 도움말 명령 |
+| -------- | ------ | ----------- | --------------- | ----------- | ----------- | ---------------- | ----------- | ----------- | ------------ |
+| Matrix   | x      | x           | x               | x           | x           | x                | x           | x           |              |
+| Telegram | x      |             |                 |             |             |                  |             |             | x            |
 
-이렇게 하면 `qa-channel`은 폭넓은 제품 동작 스위트로 유지되고, Matrix,
-Telegram 및 미래의 라이브 전송 계층은 하나의 명시적인 전송 계약 체크리스트를 공유하게 됩니다.
+이렇게 하면 `qa-channel`은 폭넓은 제품 동작 스위트로 유지되고, Matrix, Telegram 및 향후 라이브 전송 계층은 하나의 명시적인 전송 계약 체크리스트를 공유하게 됩니다.
 
-Docker를 QA 경로에 포함하지 않고 일회용 Linux VM 레인을 실행하려면 다음을 사용하세요:
+QA 경로에 Docker를 포함하지 않는 일회용 Linux VM 레인을 실행하려면 다음을 사용하세요:
 
 ```bash
 pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
 ```
 
-이 명령은 새 Multipass guest를 부팅하고, 의존성을 설치하고, guest 내부에서
-OpenClaw를 빌드하고, `qa suite`를 실행한 뒤, 일반 QA 보고서와
-요약을 호스트의 `.artifacts/qa-e2e/...`로 다시 복사합니다.
-호스트에서 `qa suite`를 실행할 때와 동일한 시나리오 선택 동작을 재사용합니다.
-호스트와 Multipass 스위트 실행은 기본적으로 여러 선택된 시나리오를
-격리된 gateway worker와 함께 병렬로 실행하며, 최대 64개 worker 또는
-선택된 시나리오 수까지만 사용합니다. worker 수를 조정하려면 `--concurrency <count>`를,
-직렬 실행하려면 `--concurrency 1`을 사용하세요.
-라이브 실행은 guest에서 실용적으로 전달 가능한 지원 QA 인증 입력을 전달합니다:
-환경 변수 기반 provider 키, QA 라이브 provider config 경로,
-그리고 존재하는 경우 `CODEX_HOME`입니다. guest가 마운트된 워크스페이스를 통해
-다시 기록할 수 있도록 `--output-dir`은 리포지토리 루트 아래에 두세요.
+이 명령은 새 Multipass 게스트를 부팅하고, 의존성을 설치하고, 게스트 내부에서 OpenClaw를 빌드하고, `qa suite`를 실행한 뒤, 일반적인 QA 보고서와 요약을 호스트의 `.artifacts/qa-e2e/...`로 다시 복사합니다.
+시나리오 선택 동작은 호스트에서의 `qa suite`와 동일하게 재사용합니다.
+호스트 및 Multipass 스위트 실행은 기본적으로 격리된 gateway 워커와 함께 여러 개의 선택된 시나리오를 병렬로 실행합니다. `qa-channel`의 기본 동시성은 4이며, 선택된 시나리오 수를 상한으로 합니다. 워커 수를 조정하려면 `--concurrency <count>`를 사용하고, 직렬 실행하려면 `--concurrency 1`을 사용하세요.
+어떤 시나리오라도 실패하면 명령은 0이 아닌 종료 코드를 반환합니다. 실패 종료 코드 없이 아티팩트만 원한다면 `--allow-failures`를 사용하세요.
+라이브 실행은 게스트에 실용적으로 전달 가능한 지원 QA 인증 입력을 전달합니다: env 기반 provider 키, QA 라이브 provider config 경로, 그리고 존재할 경우 `CODEX_HOME`입니다. 게스트가 마운트된 워크스페이스를 통해 다시 쓸 수 있도록 `--output-dir`은 리포지토리 루트 아래에 두세요.
 
 ## 리포지토리 기반 시드
 
-시드 자산은 `qa/` 아래에 있습니다:
+시드 자산은 `qa/`에 있습니다:
 
 - `qa/scenarios/index.md`
 - `qa/scenarios/<theme>/*.md`
 
-이들은 QA 계획이 사람과
-에이전트 모두에게 보이도록 의도적으로 git에 포함되어 있습니다.
+이 파일들은 QA 계획이 사람과 에이전트 모두에게 보이도록 의도적으로 git에 포함됩니다.
 
-`qa-lab`은 범용 markdown 러너로 유지되어야 합니다. 각 시나리오 markdown 파일은
-하나의 테스트 실행에 대한 단일 진실 공급원이어야 하며, 다음을 정의해야 합니다:
+`qa-lab`은 일반적인 markdown 러너로 유지되어야 합니다. 각 시나리오 markdown 파일은 한 번의 테스트 실행에 대한 기준 정보여야 하며 다음을 정의해야 합니다:
 
 - 시나리오 메타데이터
 - 선택적 category, capability, lane, risk 메타데이터
 - 문서 및 코드 참조
-- 선택적 Plugin 요구 사항
-- 선택적 gateway config patch
+- 선택적 Plugin 요구사항
+- 선택적 gateway config 패치
 - 실행 가능한 `qa-flow`
 
-`qa-flow`를 뒷받침하는 재사용 가능한 런타임 표면은 범용적이고
-교차 관심사로 유지되어도 됩니다. 예를 들어 markdown 시나리오는
-특수 사례 러너를 추가하지 않고도, 임베디드 Control UI를
-Gateway `browser.request` seam을 통해 구동하는 브라우저 측 helper와
-전송 측 helper를 결합할 수 있습니다.
+`qa-flow`를 뒷받침하는 재사용 가능한 런타임 표면은 일반적이고 여러 영역을 가로지르는 형태로 유지될 수 있습니다. 예를 들어, markdown 시나리오는 특수한 러너를 추가하지 않고도 Gateway `browser.request` seam을 통해 내장된 Control UI를 구동하는 브라우저 측 헬퍼와 전송 측 헬퍼를 조합할 수 있습니다.
 
-시나리오 파일은 소스 트리 폴더가 아니라 제품 기능 기준으로 그룹화해야 합니다.
-파일이 이동해도 시나리오 ID는 안정적으로 유지하고, 구현 추적 가능성을 위해
-`docsRefs`와 `codeRefs`를 사용하세요.
+시나리오 파일은 소스 트리 폴더가 아니라 제품 capability별로 그룹화해야 합니다. 파일이 이동하더라도 시나리오 ID는 안정적으로 유지하고, 구현 추적 가능성을 위해 `docsRefs`와 `codeRefs`를 사용하세요.
 
-기본 목록은 다음을 포괄할 수 있을 만큼 충분히 넓어야 합니다:
+기본 목록은 다음을 포괄할 만큼 충분히 넓어야 합니다:
 
 - DM 및 채널 채팅
 - 스레드 동작
-- 메시지 액션 생명주기
+- 메시지 액션 수명주기
 - Cron 콜백
 - 메모리 회상
 - 모델 전환
-- 서브에이전트 핸드오프
+- 하위 에이전트 handoff
 - 리포지토리 읽기 및 문서 읽기
-- Lobster Invaders 같은 작은 빌드 작업 하나
+- Lobster Invaders와 같은 작은 빌드 작업 하나
 
-## Provider 모의 레인
+## Provider mock 레인
 
-`qa suite`에는 두 개의 로컬 provider 모의 레인이 있습니다:
+`qa suite`에는 두 개의 로컬 provider mock 레인이 있습니다:
 
-- `mock-openai`는 시나리오 인식 OpenClaw 모의 구현입니다. 이는 리포지토리 기반 QA와
-  동등성 게이트를 위한 기본 결정론적 모의 레인으로 유지됩니다.
-- `aimock`은 실험적 프로토콜,
-  픽스처, 기록/재생, 혼돈 커버리지를 위해 AIMock 기반 provider 서버를 시작합니다. 이는
-  추가 기능이며 `mock-openai` 시나리오 디스패처를 대체하지 않습니다.
+- `mock-openai`는 시나리오 인지형 OpenClaw mock입니다. 리포지토리 기반 QA 및 동등성 게이트를 위한 기본 결정론적 mock 레인으로 유지됩니다.
+- `aimock`은 실험적인 프로토콜, 픽스처, record/replay, chaos 커버리지를 위해 AIMock 기반 provider 서버를 시작합니다. 이는 추가적인 옵션이며 `mock-openai` 시나리오 디스패처를 대체하지 않습니다.
 
-Provider 레인 구현은 `extensions/qa-lab/src/providers/` 아래에 있습니다.
-각 provider는 자체 기본값, 로컬 서버 시작, gateway 모델 구성,
-auth-profile 스테이징 필요 사항, 라이브/모의 기능 플래그를 소유합니다. 공통 suite 및
-gateway 코드는 provider 이름으로 분기하지 말고 provider 레지스트리를 통해 라우팅해야 합니다.
+provider 레인 구현은 `extensions/qa-lab/src/providers/` 아래에 있습니다. 각 provider는 자체 기본값, 로컬 서버 시작, gateway 모델 config, auth-profile 스테이징 필요 사항, 라이브/mock capability 플래그를 소유합니다. 공유 스위트와 gateway 코드는 provider 이름으로 분기하는 대신 provider 레지스트리를 통해 라우팅해야 합니다.
 
 ## 전송 어댑터
 
-`qa-lab`은 markdown QA 시나리오를 위한 범용 전송 seam을 소유합니다.
-`qa-channel`은 그 seam의 첫 번째 어댑터이지만, 설계 목표는 더 넓습니다:
-미래의 실제 또는 합성 채널도 전송 전용 QA 러너를 추가하는 대신
-동일한 suite runner에 연결되어야 합니다.
+`qa-lab`은 markdown QA 시나리오를 위한 일반적인 전송 seam을 소유합니다.
+`qa-channel`은 그 seam 위의 첫 번째 어댑터이지만, 설계 목표는 더 넓습니다. 향후 실제 또는 합성 채널은 전송 전용 QA 러너를 추가하는 대신 같은 스위트 러너에 연결되어야 합니다.
 
 아키텍처 수준에서의 분리는 다음과 같습니다:
 
-- `qa-lab`은 범용 시나리오 실행, worker 동시성, 아티팩트 기록, 보고를 소유합니다.
-- 전송 어댑터는 gateway 구성, 준비 상태, 인바운드 및 아웃바운드 관찰, 전송 액션, 정규화된 전송 상태를 소유합니다.
-- `qa/scenarios/` 아래의 markdown 시나리오 파일이 테스트 실행을 정의하며, 이를 실행하는 재사용 가능한 런타임 표면은 `qa-lab`이 제공합니다.
+- `qa-lab`은 일반적인 시나리오 실행, 워커 동시성, 아티팩트 기록, 보고를 소유합니다.
+- 전송 어댑터는 gateway config, 준비 상태, 인바운드 및 아웃바운드 관찰, 전송 액션, 정규화된 전송 상태를 소유합니다.
+- `qa/scenarios/` 아래의 markdown 시나리오 파일이 테스트 실행을 정의하며, `qa-lab`은 이를 실행하는 재사용 가능한 런타임 표면을 제공합니다.
 
-새 채널 어댑터를 위한 메인테이너용 도입 가이드는
+새 채널 어댑터를 위한 유지관리자용 도입 가이드는
 [Testing](/ko/help/testing#adding-a-channel-to-qa)에 있습니다.
 
 ## 보고
 
 `qa-lab`은 관찰된 버스 타임라인에서 Markdown 프로토콜 보고서를 내보냅니다.
-이 보고서는 다음에 답해야 합니다:
+보고서는 다음 질문에 답해야 합니다:
 
 - 무엇이 작동했는가
 - 무엇이 실패했는가
 - 무엇이 계속 막혀 있었는가
 - 어떤 후속 시나리오를 추가할 가치가 있는가
 
-문체와 스타일 검사를 위해 동일한 시나리오를 여러 라이브 모델
-ref에 대해 실행하고 판정된 Markdown 보고서를 작성하세요:
+문체 및 스타일 검사를 위해, 같은 시나리오를 여러 라이브 모델 ref에 걸쳐 실행하고 평가된 Markdown 보고서를 작성하세요:
 
 ```bash
 pnpm openclaw qa character-eval \
@@ -224,35 +174,15 @@ pnpm openclaw qa character-eval \
   --judge-concurrency 16
 ```
 
-이 명령은 Docker가 아니라 로컬 QA gateway child 프로세스를 실행합니다. Character eval
-시나리오는 `SOUL.md`를 통해 페르소나를 설정한 뒤, 채팅,
-워크스페이스 도움말, 작은 파일 작업 같은 일반 사용자 턴을 실행해야 합니다. 후보 모델에는
-자신이 평가 중이라는 사실을 알려주면 안 됩니다. 이 명령은 각 전체
-대화 내용을 보존하고, 기본 실행 통계를 기록한 다음, fast mode와
-`xhigh` 추론을 사용하는 judge 모델에게 자연스러움, 분위기, 유머를 기준으로 실행 결과를 순위 매기도록 요청합니다.
-provider를 비교할 때는 `--blind-judge-models`를 사용하세요:
-judge 프롬프트는 여전히 모든 대화 내용과 실행 상태를 받지만, 후보 ref는
-`candidate-01` 같은 중립 레이블로 대체되며, 보고서는 파싱 후 순위를 실제 ref에 다시 매핑합니다.
-후보 실행은 기본적으로 `high` thinking을 사용하며, 이를 지원하는 OpenAI 모델은 `xhigh`를 사용합니다.
-특정 후보를 인라인으로 재정의하려면
-`--model provider/model,thinking=<level>`을 사용하세요. `--thinking <level>`은 여전히
-전역 폴백을 설정하며, 이전의 `--model-thinking <provider/model=level>` 형식도
-호환성을 위해 유지됩니다.
-OpenAI 후보 ref는 provider가 이를 지원하는 경우 우선 처리에 fast mode를
-기본 적용합니다. 특정 후보 또는 judge에 재정의가 필요하면 인라인으로
-`,fast`, `,no-fast`, 또는 `,fast=false`를 추가하세요. 모든 후보 모델에 대해
-fast mode를 강제로 켜고 싶을 때만 `--fast`를 전달하세요. 후보 및 judge 실행 시간은
-벤치마크 분석을 위해 보고서에 기록되지만, judge 프롬프트에는
-속도를 기준으로 순위를 매기지 말라고 명시되어 있습니다.
-후보와 judge 모델 실행은 모두 기본적으로 동시성 16을 사용합니다. provider 제한이나
-로컬 gateway 부하 때문에 실행이 너무 불안정해지면
-`--concurrency` 또는 `--judge-concurrency`를 낮추세요.
-후보 `--model`이 전달되지 않으면 character eval은 기본적으로
-`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
-`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
+이 명령은 Docker가 아니라 로컬 QA gateway 하위 프로세스를 실행합니다. character eval 시나리오는 `SOUL.md`를 통해 페르소나를 설정한 다음, 채팅, 워크스페이스 도움말, 작은 파일 작업과 같은 일반 사용자 턴을 실행해야 합니다. 후보 모델에는 자신이 평가 중이라는 사실을 알려주면 안 됩니다. 이 명령은 각 전체 대화 내용을 보존하고, 기본 실행 통계를 기록한 다음, judge 모델에게 fast 모드와 `xhigh` 추론으로 실행 결과를 자연스러움, 분위기, 유머 기준으로 순위를 매기도록 요청합니다.
+provider를 비교할 때는 `--blind-judge-models`를 사용하세요. judge 프롬프트는 여전히 모든 대화 내용과 실행 상태를 받지만, 후보 ref는 `candidate-01`과 같은 중립적인 라벨로 대체되며, 보고서는 파싱 후 순위를 실제 ref로 다시 매핑합니다.
+후보 실행은 기본적으로 `high` thinking을 사용하며, 이를 지원하는 OpenAI 모델은 `xhigh`를 사용합니다. 특정 후보를 인라인으로 재정의하려면 `--model provider/model,thinking=<level>`을 사용하세요. `--thinking <level>`은 여전히 전역 기본값을 설정하며, 이전 `--model-thinking <provider/model=level>` 형식도 호환성을 위해 유지됩니다.
+OpenAI 후보 ref는 provider가 지원하는 경우 우선순위 처리를 사용하도록 기본적으로 fast 모드를 사용합니다. 특정 후보나 judge에 대해 재정의가 필요하면 인라인으로 `,fast`, `,no-fast`, 또는 `,fast=false`를 추가하세요. 모든 후보 모델에 fast 모드를 강제로 켜려는 경우에만 `--fast`를 전달하세요. 후보 및 judge 실행 시간은 벤치마크 분석을 위해 보고서에 기록되지만, judge 프롬프트에는 속도로 순위를 매기지 말라고 명시되어 있습니다.
+후보 및 judge 모델 실행은 둘 다 기본적으로 동시성 16을 사용합니다. provider 제한이나 로컬 gateway 부하로 인해 실행이 너무 불안정해지면 `--concurrency` 또는 `--judge-concurrency`를 낮추세요.
+후보 `--model`이 전달되지 않으면 character eval은 기본적으로 `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
 `moonshot/kimi-k2.5`,
-그리고 `google/gemini-3.1-pro-preview`를 사용합니다.
-judge `--judge-model`이 전달되지 않으면 judge는 기본적으로
+`google/gemini-3.1-pro-preview`를 사용합니다.
+`--judge-model`이 전달되지 않으면 judge는 기본적으로
 `openai/gpt-5.4,thinking=xhigh,fast`와
 `anthropic/claude-opus-4-6,thinking=high`를 사용합니다.
 

docs/ko/install/index.md

@@ -1,15 +1,15 @@
 ---
 read_when:
-    - Getting Started 빠른 시작 외의 설치 방법이 필요할 때
-    - 클라우드 플랫폼에 배포하려는 경우
-    - 업데이트, 마이그레이션 또는 제거가 필요할 때
+    - 시작하기 빠른 시작 외의 설치 방법이 필요합니다.
+    - 클라우드 플랫폼에 배포하려고 합니다
+    - 업데이트, 마이그레이션 또는 제거가 필요합니다
 summary: OpenClaw 설치 — 설치 스크립트, npm/pnpm/bun, 소스에서, Docker 등
 title: 설치
 x-i18n:
-    generated_at: "2026-04-05T12:46:22Z"
+    generated_at: "2026-04-20T06:05:33Z"
     model: gpt-5.4
     provider: openai
-    source_hash: eca17c76a2a66166b3d8cda9dc3144ab920d30ad0ed2a220eb9389d7a383ba5d
+    source_hash: ad0a5fdbbf13dcaf2fed6840f35aa22b2e9e458509509f98303c8d87c2556a6f
     source_path: install/index.md
     workflow: 15
 ---
@@ -18,7 +18,7 @@ x-i18n:
 
 ## 권장: 설치 스크립트
 
-가장 빠른 설치 방법입니다. OS를 감지하고, 필요하면 Node를 설치하고, OpenClaw를 설치한 뒤 온보딩을 실행합니다.
+가장 빠른 설치 방법입니다. OS를 감지하고, 필요하면 Node를 설치하고, OpenClaw를 설치한 다음 온보딩을 시작합니다.
 
 <Tabs>
   <Tab title="macOS / Linux / WSL2">
@@ -33,7 +33,7 @@ x-i18n:
   </Tab>
 </Tabs>
 
-온보딩을 실행하지 않고 설치하려면:
+온보딩을 실행하지 않고 설치하려면 다음을 사용하세요.
 
 <Tabs>
   <Tab title="macOS / Linux / WSL2">
@@ -48,31 +48,29 @@ x-i18n:
   </Tab>
 </Tabs>
 
-모든 플래그와 CI/자동화 옵션은 [Installer internals](/install/installer)를 참조하세요.
+모든 플래그와 CI/자동화 옵션은 [설치 프로그램 내부 동작](/ko/install/installer)을 참조하세요.
 
 ## 시스템 요구 사항
 
-- **Node 24**(권장) 또는 Node 22.14+ — 설치 스크립트가 이를 자동 처리합니다
-- **macOS, Linux 또는 Windows** — 네이티브 Windows와 WSL2 모두 지원되며, WSL2가 더 안정적입니다. [Windows](/platforms/windows)를 참조하세요.
-- `pnpm`은 소스에서 빌드할 때만 필요합니다
+- **Node 24**(권장) 또는 Node 22.14+ — 설치 스크립트가 이를 자동으로 처리합니다
+- **macOS, Linux 또는 Windows** — 기본 Windows와 WSL2를 모두 지원하며, WSL2가 더 안정적입니다. [Windows](/ko/platforms/windows)를 참조하세요.
+- 소스에서 빌드하는 경우에만 `pnpm`이 필요합니다
 
 ## 대체 설치 방법
 
-### 로컬 prefix 설치기(`install-cli.sh`)
+### 로컬 프리픽스 설치 프로그램(`install-cli.sh`)
 
-시스템 전체 Node 설치에 의존하지 않고 OpenClaw와 Node를
-`~/.openclaw` 같은 로컬 prefix 아래에 유지하고 싶다면 이 방법을 사용하세요:
+시스템 전체 Node 설치에 의존하지 않고, `~/.openclaw` 같은 로컬 프리픽스 아래에 OpenClaw와 Node를 유지하려는 경우 이 방법을 사용하세요.
 
 ```bash
 curl -fsSL https://openclaw.ai/install-cli.sh | bash
 ```
 
-기본적으로 npm 설치를 지원하며, 같은
-prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다. 전체 참조: [Installer internals](/install/installer#install-clish).
+기본적으로 npm 설치를 지원하며, 동일한 프리픽스 흐름에서 git 체크아웃 설치도 지원합니다. 전체 참조는 [설치 프로그램 내부 동작](/ko/install/installer#install-clish)을 확인하세요.
 
 ### npm, pnpm 또는 bun
 
-이미 Node를 직접 관리하고 있다면:
+이미 Node를 직접 관리하고 있다면 다음을 사용하세요.
 
 <Tabs>
   <Tab title="npm">
@@ -89,7 +87,7 @@ prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다. 전체
     ```
 
     <Note>
-    pnpm은 빌드 스크립트가 있는 패키지에 대해 명시적 승인이 필요합니다. 첫 설치 후 `pnpm approve-builds -g`를 실행하세요.
+    pnpm은 빌드 스크립트가 있는 패키지에 대해 명시적인 승인이 필요합니다. 처음 설치한 뒤 `pnpm approve-builds -g`를 실행하세요.
     </Note>
 
   </Tab>
@@ -100,13 +98,13 @@ prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다. 전체
     ```
 
     <Note>
-    Bun은 전역 CLI 설치 경로에서 지원됩니다. 게이트웨이 런타임에는 여전히 Node가 권장되는 daemon 런타임입니다.
+    Bun은 전역 CLI 설치 경로에서 지원됩니다. Gateway 런타임의 경우에는 여전히 Node를 권장 데몬 런타임으로 사용합니다.
     </Note>
 
   </Tab>
 </Tabs>
 
-<Accordion title="문제 해결: sharp 빌드 오류(npm)">
+<Accordion title="문제 해결: `sharp` 빌드 오류 (npm)">
   전역 설치된 libvips 때문에 `sharp`가 실패하는 경우:
 
 ```bash
@@ -122,12 +120,12 @@ SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
 ```bash
 git clone https://github.com/openclaw/openclaw.git
 cd openclaw
-pnpm install && pnpm ui:build && pnpm build
+pnpm install && pnpm build && pnpm ui:build
 pnpm link --global
 openclaw onboard --install-daemon
 ```
 
-또는 link를 생략하고 리포지토리 내부에서 `pnpm openclaw ...`를 사용하세요. 전체 개발 워크플로는 [Setup](/start/setup)을 참조하세요.
+또는 링크를 생략하고 저장소 내부에서 `pnpm openclaw ...`를 사용해도 됩니다. 전체 개발 워크플로는 [Setup](/ko/start/setup)을 참조하세요.
 
 ### GitHub main에서 설치
 
@@ -138,19 +136,19 @@ npm install -g github:openclaw/openclaw#main
 ### 컨테이너 및 패키지 관리자
 
 <CardGroup cols={2}>
-  <Card title="Docker" href="/install/docker" icon="container">
-    컨테이너화되었거나 헤드리스인 배포.
+  <Card title="Docker" href="/ko/install/docker" icon="container">
+    컨테이너화된 또는 헤드리스 배포.
   </Card>
-  <Card title="Podman" href="/install/podman" icon="container">
-    Docker의 rootless 컨테이너 대안.
+  <Card title="Podman" href="/ko/install/podman" icon="container">
+    Docker의 루트리스 컨테이너 대안.
   </Card>
-  <Card title="Nix" href="/install/nix" icon="snowflake">
+  <Card title="Nix" href="/ko/install/nix" icon="snowflake">
     Nix flake를 통한 선언적 설치.
   </Card>
-  <Card title="Ansible" href="/install/ansible" icon="server">
-    자동화된 fleet 프로비저닝.
+  <Card title="Ansible" href="/ko/install/ansible" icon="server">
+    자동화된 대규모 프로비저닝.
   </Card>
-  <Card title="Bun" href="/install/bun" icon="zap">
+  <Card title="Bun" href="/ko/install/bun" icon="zap">
     Bun 런타임을 통한 CLI 전용 사용.
   </Card>
 </CardGroup>
@@ -158,44 +156,44 @@ npm install -g github:openclaw/openclaw#main
 ## 설치 확인
 
 ```bash
-openclaw --version      # CLI 사용 가능 여부 확인
-openclaw doctor         # config 문제 확인
-openclaw gateway status # 게이트웨이 실행 여부 확인
+openclaw --version      # CLI를 사용할 수 있는지 확인
+openclaw doctor         # 구성 문제 확인
+openclaw gateway status # Gateway가 실행 중인지 확인
 ```
 
-설치 후 관리형 시작을 원하면:
+설치 후 관리형 시작을 원한다면:
 
 - macOS: `openclaw onboard --install-daemon` 또는 `openclaw gateway install`을 통한 LaunchAgent
-- Linux/WSL2: 동일한 명령을 통한 systemd user 서비스
-- 네이티브 Windows: 먼저 Scheduled Task, 작업 생성이 거부되면 사용자별 Startup 폴더 로그인 항목으로 대체
+- Linux/WSL2: 동일한 명령을 통한 systemd 사용자 서비스
+- 기본 Windows: 먼저 예약된 작업, 작업 생성이 거부되면 사용자별 시작 프로그램 폴더 로그인 항목으로 대체
 
 ## 호스팅 및 배포
 
-클라우드 서버 또는 VPS에 OpenClaw를 배포하세요:
+클라우드 서버 또는 VPS에 OpenClaw를 배포하세요.
 
 <CardGroup cols={3}>
-  <Card title="VPS" href="/vps">모든 Linux VPS</Card>
-  <Card title="Docker VM" href="/install/docker-vm-runtime">공통 Docker 단계</Card>
-  <Card title="Kubernetes" href="/install/kubernetes">K8s</Card>
-  <Card title="Fly.io" href="/install/fly">Fly.io</Card>
-  <Card title="Hetzner" href="/install/hetzner">Hetzner</Card>
-  <Card title="GCP" href="/install/gcp">Google Cloud</Card>
-  <Card title="Azure" href="/install/azure">Azure</Card>
-  <Card title="Railway" href="/install/railway">Railway</Card>
-  <Card title="Render" href="/install/render">Render</Card>
-  <Card title="Northflank" href="/install/northflank">Northflank</Card>
+  <Card title="VPS" href="/ko/vps">모든 Linux VPS</Card>
+  <Card title="Docker VM" href="/ko/install/docker-vm-runtime">공통 Docker 단계</Card>
+  <Card title="Kubernetes" href="/ko/install/kubernetes">K8s</Card>
+  <Card title="Fly.io" href="/ko/install/fly">Fly.io</Card>
+  <Card title="Hetzner" href="/ko/install/hetzner">Hetzner</Card>
+  <Card title="GCP" href="/ko/install/gcp">Google Cloud</Card>
+  <Card title="Azure" href="/ko/install/azure">Azure</Card>
+  <Card title="Railway" href="/ko/install/railway">Railway</Card>
+  <Card title="Render" href="/ko/install/render">Render</Card>
+  <Card title="Northflank" href="/ko/install/northflank">Northflank</Card>
 </CardGroup>
 
 ## 업데이트, 마이그레이션 또는 제거
 
 <CardGroup cols={3}>
-  <Card title="업데이트" href="/install/updating" icon="refresh-cw">
+  <Card title="업데이트" href="/ko/install/updating" icon="refresh-cw">
     OpenClaw를 최신 상태로 유지합니다.
   </Card>
-  <Card title="마이그레이션" href="/install/migrating" icon="arrow-right">
+  <Card title="마이그레이션" href="/ko/install/migrating" icon="arrow-right">
     새 머신으로 이동합니다.
   </Card>
-  <Card title="제거" href="/install/uninstall" icon="trash-2">
+  <Card title="제거" href="/ko/install/uninstall" icon="trash-2">
     OpenClaw를 완전히 제거합니다.
   </Card>
 </CardGroup>
@@ -205,15 +203,15 @@ openclaw gateway status # 게이트웨이 실행 여부 확인
 설치는 성공했지만 터미널에서 `openclaw`를 찾을 수 없는 경우:
 
 ```bash
-node -v           # Node가 설치되어 있나요?
+node -v           # Node가 설치되었나요?
 npm prefix -g     # 전역 패키지는 어디에 설치되나요?
 echo "$PATH"      # 전역 bin 디렉터리가 PATH에 있나요?
 ```
 
-`$(npm prefix -g)/bin`이 `$PATH`에 없다면 셸 시작 파일(`~/.zshrc` 또는 `~/.bashrc`)에 추가하세요:
+`$(npm prefix -g)/bin`이 `$PATH`에 없다면, 셸 시작 파일(`~/.zshrc` 또는 `~/.bashrc`)에 추가하세요.
 
 ```bash
 export PATH="$(npm prefix -g)/bin:$PATH"
 ```
 
-그런 다음 새 터미널을 여세요. 자세한 내용은 [Node setup](/install/node)를 참조하세요.
+그런 다음 새 터미널을 여세요. 자세한 내용은 [Node setup](/ko/install/node)을 참조하세요.

docs/ko/platforms/windows.md

@@ -1,30 +1,33 @@
 ---
 read_when:
-    - Windows에 OpenClaw를 설치하는 경우
-    - 네이티브 Windows와 WSL2 중에서 선택하는 경우
-    - Windows companion app 상태를 확인하려는 경우
-summary: 'Windows 지원: 네이티브 및 WSL2 설치 경로, 데몬, 현재 주의 사항'
+    - Windows에 OpenClaw 설치하기
+    - 네이티브 Windows와 WSL2 중 선택하기
+    - Windows 컴패니언 앱 상태 확인하기
+summary: 'Windows 지원: 네이티브 및 WSL2 설치 경로, 데몬, 그리고 현재 주의사항'
 title: Windows
 x-i18n:
-    generated_at: "2026-04-05T12:49:25Z"
+    generated_at: "2026-04-20T06:05:37Z"
     model: gpt-5.4
     provider: openai
-    source_hash: 7d9819206bdd65cf03519c1bc73ed0c7889b0ab842215ea94343262300adfd14
+    source_hash: 1e7451c785a1d75c809522ad93e2c44a00b211f77f14c5c489fd0b01840d3fe2
     source_path: platforms/windows.md
     workflow: 15
 ---
 
 # Windows
 
-OpenClaw는 **네이티브 Windows**와 **WSL2**를 모두 지원합니다. WSL2가 더 안정적인 경로이며 전체 경험을 위해 권장됩니다. CLI, Gateway, tooling이 Linux 내부에서 완전한 호환성과 함께 실행됩니다. 네이티브 Windows도 핵심 CLI와 Gateway 사용에는 동작하지만, 아래에 설명된 몇 가지 주의 사항이 있습니다.
+OpenClaw는 **네이티브 Windows**와 **WSL2**를 모두 지원합니다. WSL2가 더
+안정적인 경로이며 전체 경험을 위해 권장됩니다. CLI, Gateway, 그리고
+도구들이 Linux 내부에서 완전한 호환성으로 실행됩니다. 네이티브 Windows도
+핵심 CLI와 Gateway 사용은 가능하지만, 아래에 적힌 몇 가지 주의사항이 있습니다.
 
-네이티브 Windows companion apps는 계획되어 있습니다.
+네이티브 Windows 컴패니언 앱은 계획되어 있습니다.
 
-## WSL2 (권장)
+## WSL2(권장)
 
-- [Getting Started](/ko/start/getting-started) (WSL 내부에서 사용)
-- [설치 및 업데이트](/install/updating)
-- 공식 WSL2 가이드 (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
+- [시작하기](/ko/start/getting-started) (WSL 내부에서 사용)
+- [설치 및 업데이트](/ko/install/updating)
+- 공식 WSL2 가이드(Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
 
 ## 네이티브 Windows 상태
 
@@ -34,21 +37,21 @@ OpenClaw는 **네이티브 Windows**와 **WSL2**를 모두 지원합니다. WSL2
 
 - `install.ps1`을 통한 웹사이트 설치 프로그램
 - `openclaw --version`, `openclaw doctor`, `openclaw plugins list --json` 같은 로컬 CLI 사용
-- 다음과 같은 내장 local-agent/provider 스모크 테스트:
+- 다음과 같은 임베디드 local-agent/provider 스모크 테스트:
 
 ```powershell
 openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
 ```
 
-현재 주의 사항:
+현재 주의사항:
 
-- `openclaw onboard --non-interactive`는 `--skip-health`를 전달하지 않으면 여전히 도달 가능한 로컬 gateway를 기대합니다
-- `openclaw onboard --non-interactive --install-daemon` 및 `openclaw gateway install`은 먼저 Windows Scheduled Tasks를 시도합니다
-- Scheduled Task 생성이 거부되면 OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 폴백하고 gateway를 즉시 시작합니다
-- `schtasks` 자체가 멈추거나 응답하지 않으면 OpenClaw는 이제 영원히 멈추는 대신 해당 경로를 빠르게 중단하고 폴백합니다
-- Scheduled Tasks는 더 나은 supervisor 상태를 제공하므로 사용 가능한 경우 여전히 선호됩니다
+- `openclaw onboard --non-interactive`는 여전히 `--skip-health`를 전달하지 않으면 도달 가능한 로컬 gateway를 기대합니다
+- `openclaw onboard --non-interactive --install-daemon`과 `openclaw gateway install`은 먼저 Windows 예약 작업을 시도합니다
+- 예약 작업 생성이 거부되면, OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 대체하고 즉시 gateway를 시작합니다
+- `schtasks` 자체가 멈추거나 응답을 중지하면, OpenClaw는 이제 영원히 멈춰 있지 않고 해당 경로를 빠르게 중단하고 대체 경로로 전환합니다
+- 예약 작업은 더 나은 supervisor 상태를 제공하므로 가능할 때 여전히 우선적으로 사용됩니다
 
-네이티브 CLI만 원하고 gateway 서비스 설치는 원하지 않는다면 다음 중 하나를 사용하세요.
+네이티브 CLI만 사용하고 gateway 서비스 설치는 원하지 않는다면, 다음 중 하나를 사용하세요:
 
 ```powershell
 openclaw onboard --non-interactive --skip-health
@@ -62,12 +65,12 @@ openclaw gateway install
 openclaw gateway status --json
 ```
 
-Scheduled Task 생성이 차단되더라도, 폴백 서비스 모드는 현재 사용자의 Startup 폴더를 통해 로그인 후 자동 시작됩니다.
+예약 작업 생성이 차단된 경우에도, 대체 서비스 모드는 현재 사용자의 Startup 폴더를 통해 로그인 후 자동 시작됩니다.
 
 ## Gateway
 
-- [Gateway runbook](/gateway)
-- [구성](/gateway/configuration)
+- [Gateway 실행 가이드](/ko/gateway)
+- [설정](/ko/gateway/configuration)
 
 ## Gateway 서비스 설치 (CLI)
 
@@ -89,7 +92,7 @@ openclaw gateway install
 openclaw configure
 ```
 
-프롬프트가 뜨면 **Gateway service**를 선택하세요.
+프롬프트가 표시되면 **Gateway service**를 선택하세요.
 
 복구/마이그레이션:
 
@@ -99,9 +102,9 @@ openclaw doctor
 
 ## Windows 로그인 전 Gateway 자동 시작
 
-헤드리스 구성에서는 아무도 Windows에 로그인하지 않아도 전체 부팅 체인이 실행되도록 해야 합니다.
+헤드리스 설정의 경우, 아무도 Windows에 로그인하지 않아도 전체 부팅 체인이 실행되도록 해야 합니다.
 
-### 1) 로그인 없이도 사용자 서비스 유지
+### 1) 로그인 없이도 사용자 서비스가 계속 실행되도록 설정
 
 WSL 내부에서:
 
@@ -119,13 +122,13 @@ openclaw gateway install
 
 ### 3) Windows 부팅 시 WSL 자동 시작
 
-관리자 권한 PowerShell에서:
+관리자 권한으로 PowerShell에서:
 
 ```powershell
 schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
 ```
 
-`Ubuntu`는 다음 명령으로 확인한 배포판 이름으로 교체하세요.
+다음 명령으로 확인한 배포판 이름으로 `Ubuntu`를 바꾸세요:
 
 ```powershell
 wsl --list --verbose
@@ -133,18 +136,21 @@ wsl --list --verbose
 
 ### 시작 체인 확인
 
-재부팅 후(Windows 로그인 전) WSL에서 다음을 확인하세요.
+재부팅 후(Windows 로그인 전), WSL에서 다음을 확인하세요:
 
 ```bash
 systemctl --user is-enabled openclaw-gateway.service
 systemctl --user status openclaw-gateway.service --no-pager
 ```
 
-## 고급: WSL 서비스를 LAN에 노출(portproxy)
+## 고급: LAN에서 WSL 서비스 노출하기 (portproxy)
 
-WSL은 자체 가상 네트워크를 가집니다. 다른 머신이 **WSL 내부에서 실행 중인** 서비스(SSH, 로컬 TTS 서버, Gateway)에 도달해야 한다면, Windows 포트를 현재 WSL IP로 포워딩해야 합니다. WSL IP는 재시작 후 바뀌므로 포워딩 규칙을 새로 고쳐야 할 수 있습니다.
+WSL은 자체 가상 네트워크를 사용합니다. 다른 머신이 **WSL 내부에서**
+실행 중인 서비스(SSH, 로컬 TTS 서버, 또는 Gateway)에 접근해야 한다면,
+Windows 포트를 현재 WSL IP로 포워딩해야 합니다. WSL IP는 재시작 후 변경되므로,
+포워딩 규칙을 갱신해야 할 수 있습니다.
 
-예시 (PowerShell **관리자 권한으로**):
+예시(관리자 권한의 PowerShell):
 
 ```powershell
 $Distro = "Ubuntu-24.04"
@@ -158,14 +164,14 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor
   connectaddress=$WslIp connectport=$TargetPort
 ```
 
-Windows Firewall에서 해당 포트를 허용합니다(1회):
+Windows 방화벽에서 해당 포트를 허용하세요(1회만 수행):
 
 ```powershell
 New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
   -Protocol TCP -LocalPort $ListenPort -Action Allow
 ```
 
-WSL 재시작 후 portproxy 새로 고침:
+WSL 재시작 후 portproxy 갱신:
 
 ```powershell
 netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
@@ -175,16 +181,17 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.
 
 참고:
 
-- 다른 머신에서의 SSH는 **Windows 호스트 IP**를 대상으로 해야 합니다(예: `ssh user@windows-host -p 2222`)
-- 원격 노드는 **도달 가능한** Gateway URL(`127.0.0.1` 아님)을 가리켜야 합니다. `openclaw status --all`로 확인하세요.
-- LAN 액세스에는 `listenaddress=0.0.0.0`를 사용하고, `127.0.0.1`은 로컬 전용입니다.
-- 이를 자동화하려면 로그인 시 새로 고침 단계를 실행하는 Scheduled Task를 등록하세요.
+- 다른 머신에서의 SSH 대상은 **Windows 호스트 IP**입니다(예: `ssh user@windows-host -p 2222`).
+- 원격 Node는 **도달 가능한** Gateway URL(`127.0.0.1`이 아닌)을 가리켜야 합니다. 확인하려면
+  `openclaw status --all`을 사용하세요.
+- LAN 접근에는 `listenaddress=0.0.0.0`을 사용하고, `127.0.0.1`은 로컬 전용으로 유지합니다.
+- 이를 자동화하고 싶다면, 로그인 시 갱신 단계를 실행하는 예약 작업을 등록하세요.
 
 ## 단계별 WSL2 설치
 
 ### 1) WSL2 + Ubuntu 설치
 
-PowerShell(관리자)에서:
+PowerShell(관리자)을 엽니다:
 
 ```powershell
 wsl --install
@@ -212,7 +219,7 @@ EOF
 wsl --shutdown
 ```
 
-Ubuntu를 다시 열고 다음으로 확인하세요.
+Ubuntu를 다시 연 뒤, 다음으로 확인하세요:
 
 ```bash
 systemctl --user status
@@ -220,19 +227,30 @@ systemctl --user status
 
 ### 3) OpenClaw 설치 (WSL 내부)
 
-WSL 내부에서 Linux Getting Started 흐름을 따르세요.
+WSL 내부에서 일반적인 첫 설정을 하려면 Linux 시작하기 흐름을 따르세요:
 
 ```bash
 git clone https://github.com/openclaw/openclaw.git
 cd openclaw
 pnpm install
-pnpm ui:build # 첫 실행 시 UI 종속성 자동 설치
 pnpm build
-openclaw onboard
+pnpm ui:build
+pnpm openclaw onboard --install-daemon
 ```
 
-전체 가이드: [Getting Started](/ko/start/getting-started)
+처음 온보딩이 아니라 소스에서 개발 중이라면, [Setup](/ko/start/setup)의
+소스 개발 루프를 사용하세요:
 
-## Windows companion app
+```bash
+pnpm install
+# 첫 실행 시에만(또는 로컬 OpenClaw config/workspace를 초기화한 후)
+pnpm openclaw setup
+pnpm gateway:watch
+```
 
-아직 Windows companion app은 없습니다. 이를 실현하고 싶다면 contributions는 환영합니다.
+전체 가이드: [시작하기](/ko/start/getting-started)
+
+## Windows 컴패니언 앱
+
+아직 Windows 컴패니언 앱은 없습니다. 원하신다면 이를 실현하는 데 도움이 될
+기여를 환영합니다.

docs/ko/start/setup.md

@@ -1,14 +1,14 @@
 ---
 read_when:
-    - 새 머신을 설정하는 경우
-    - '"최신 + 최고"를 원하지만 개인 설정은 망가뜨리고 싶지 않은 경우'
-summary: OpenClaw를 위한 고급 설정 및 개발 워크플로
+    - 새 머신 설정하기
+    - 개인 설정을 망가뜨리지 않으면서 “최신 + 최고” 상태를 원합니다
+summary: OpenClaw의 고급 설정 및 개발 워크플로우
 title: 설정
 x-i18n:
-    generated_at: "2026-04-05T12:55:46Z"
+    generated_at: "2026-04-20T06:05:27Z"
     model: gpt-5.4
     provider: openai
-    source_hash: be4e280dde7f3a224345ca557ef2fb35a9c9db8520454ff63794ac6f8d4e71e7
+    source_hash: 773cdbef5f38b069303b5e13fca5fcdc28f082746869f17b8b92aab1610b95a8
     source_path: start/setup.md
     workflow: 15
 ---
@@ -16,79 +16,79 @@ x-i18n:
 # 설정
 
 <Note>
-처음 설정하는 경우 [Getting Started](/ko/start/getting-started)부터 시작하세요.
-온보딩 세부 사항은 [Onboarding (CLI)](/ko/start/wizard)를 참조하세요.
+처음 설정하는 경우 [시작하기](/ko/start/getting-started)부터 시작하세요.
+온보딩 세부 정보는 [온보딩 (CLI)](/ko/start/wizard)를 참고하세요.
 </Note>
 
-## 요약
+## TL;DR
 
-- **사용자별 맞춤 설정은 리포지토리 밖에 있습니다:** `~/.openclaw/workspace`(워크스페이스) + `~/.openclaw/openclaw.json`(구성).
-- **안정적인 워크플로:** macOS 앱을 설치하고, 번들된 Gateway를 실행하게 둡니다.
-- **최첨단 워크플로:** `pnpm gateway:watch`로 직접 Gateway를 실행한 다음, macOS 앱이 로컬 모드에서 연결되게 둡니다.
+- **맞춤 설정은 리포지토리 외부에 저장됩니다:** `~/.openclaw/workspace` (워크스페이스) + `~/.openclaw/openclaw.json` (구성).
+- **안정적인 워크플로우:** macOS 앱을 설치하고, 번들된 Gateway를 실행하도록 둡니다.
+- **최신 실험적 워크플로우:** `pnpm gateway:watch`로 직접 Gateway를 실행한 다음, macOS 앱이 로컬 모드에서 연결하도록 둡니다.
 
-## 사전 요구 사항(소스에서)
+## 사전 요구 사항(소스에서 실행)
 
-- Node 24 권장(Node 22 LTS, 현재 `22.14+`, 역시 지원됨)
-- `pnpm` 권장(또는 의도적으로 [Bun workflow](/ko/install/bun)를 사용하는 경우 Bun)
-- Docker(선택 사항; 컨테이너화된 설정/e2e에만 필요 — [Docker](/ko/install/docker) 참조)
+- Node 24 권장 (Node 22 LTS, 현재 `22.14+`,도 계속 지원됨)
+- `pnpm` 권장(또는 의도적으로 [Bun 워크플로우](/ko/install/bun)를 사용하는 경우 Bun)
+- Docker (선택 사항; 컨테이너 기반 설정/e2e에만 필요 — [Docker](/ko/install/docker) 참고)
 
 ## 맞춤 설정 전략(업데이트가 문제를 일으키지 않도록)
 
-“나에게 100% 맞춤”이면서 _동시에_ 업데이트도 쉽게 하고 싶다면, 사용자 정의는 다음 위치에 유지하세요.
+“나에게 100% 맞춤” _이면서_ 쉽게 업데이트하고 싶다면, 사용자 지정은 다음 위치에 유지하세요:
 
-- **구성:** `~/.openclaw/openclaw.json` (JSON/JSON5 유사 형식)
+- **구성:** `~/.openclaw/openclaw.json` (JSON/JSON5 비슷한 형식)
 - **워크스페이스:** `~/.openclaw/workspace` (skills, 프롬프트, 메모리; 비공개 git 리포지토리로 만드는 것을 권장)
 
-한 번만 부트스트랩하세요.
+한 번만 초기화하세요:
 
 ```bash
 openclaw setup
 ```
 
-이 리포지토리 내부에서는 로컬 CLI 엔트리를 사용하세요.
+이 리포지토리 내부에서는 로컬 CLI 진입점을 사용하세요:
 
 ```bash
 openclaw setup
 ```
 
-아직 전역 설치가 없다면 `pnpm openclaw setup`으로 실행하세요(Bun workflow를 사용하는 경우 `bun run openclaw setup`).
+아직 전역 설치가 없다면 `pnpm openclaw setup`으로 실행하세요(Bun 워크플로우를 사용하는 경우 `bun run openclaw setup`).
 
 ## 이 리포지토리에서 Gateway 실행
 
-`pnpm build` 후에는 패키지된 CLI를 직접 실행할 수 있습니다.
+`pnpm build` 후에는 패키징된 CLI를 직접 실행할 수 있습니다:
 
 ```bash
 node openclaw.mjs gateway --port 18789 --verbose
 ```
 
-## 안정적인 워크플로(macOS 앱 우선)
+## 안정적인 워크플로우(macOS 앱 우선)
 
-1. **OpenClaw.app**을 설치하고 실행합니다(메뉴 막대).
+1. **OpenClaw.app**(메뉴 막대)을 설치하고 실행합니다.
 2. 온보딩/권한 체크리스트(TCC 프롬프트)를 완료합니다.
-3. Gateway가 **Local**로 설정되어 실행 중인지 확인합니다(앱이 관리함).
-4. 표면을 연결합니다(예: WhatsApp).
+3. Gateway가 **Local**로 설정되어 실행 중인지 확인합니다(앱이 이를 관리함).
+4. 표면을 연결합니다(예: WhatsApp):
 
 ```bash
 openclaw channels login
 ```
 
-5. 상태를 점검합니다.
+5. 정상 동작 확인:
 
 ```bash
 openclaw health
 ```
 
-빌드에서 온보딩을 사용할 수 없는 경우:
+빌드에 온보딩이 포함되어 있지 않은 경우:
 
-- `openclaw setup`을 실행한 다음 `openclaw channels login`을 실행하고, 그다음 Gateway를 수동으로 시작하세요(`openclaw gateway`).
+- `openclaw setup`을 실행한 다음 `openclaw channels login`을 실행하고, 그 후 Gateway를 수동으로 시작하세요(`openclaw gateway`).
 
-## 최첨단 워크플로(터미널에서 Gateway 실행)
+## 최신 실험적 워크플로우(터미널에서 Gateway 실행)
 
-목표: TypeScript Gateway를 작업하고, 핫 리로드를 얻고, macOS 앱 UI는 계속 연결된 상태로 유지합니다.
+목표: TypeScript Gateway를 개발하고, 핫 리로드를 사용하며, macOS 앱 UI는 계속 연결된 상태로 유지합니다.
 
 ### 0) (선택 사항) macOS 앱도 소스에서 실행
 
-macOS 앱도 최신 개발 상태로 사용하고 싶다면 다음을 실행하세요.
+macOS 앱도 최신 실험적 상태로 사용하려면:
 
 ```bash
 ./scripts/restart-mac.sh
@@ -98,81 +98,88 @@ macOS 앱도 최신 개발 상태로 사용하고 싶다면 다음을 실행하
 
 ```bash
 pnpm install
+# 첫 실행에서만 필요(또는 로컬 OpenClaw 구성/워크스페이스를 초기화한 후)
+pnpm openclaw setup
 pnpm gateway:watch
 ```
 
-`gateway:watch`는 Gateway를 watch 모드로 실행하고, 관련 소스,
-구성, 번들된 플러그인 메타데이터가 변경되면 다시 로드합니다.
+`gateway:watch`는 감시 모드로 gateway를 실행하며, 관련 소스,
+구성, 번들된 Plugin 메타데이터 변경 시 다시 로드합니다.
+`pnpm openclaw setup`은 새 체크아웃에 대해 한 번만 수행하는 로컬 구성/워크스페이스 초기화 단계입니다.
+`pnpm gateway:watch`는 `dist/control-ui`를 다시 빌드하지 않으므로, `ui/` 변경 후에는 `pnpm ui:build`를 다시 실행하거나 Control UI를 개발하는 동안 `pnpm ui:dev`를 사용하세요.
 
-의도적으로 Bun workflow를 사용하는 경우, 동등한 명령은 다음과 같습니다.
+의도적으로 Bun 워크플로우를 사용하는 경우, 동등한 명령은 다음과 같습니다:
 
 ```bash
 bun install
+# 첫 실행에서만 필요(또는 로컬 OpenClaw 구성/워크스페이스를 초기화한 후)
+bun run openclaw setup
 bun run gateway:watch
 ```
 
-### 2) 실행 중인 Gateway에 macOS 앱 연결
+### 2) 실행 중인 Gateway를 macOS 앱이 사용하도록 설정
 
 **OpenClaw.app**에서:
 
 - 연결 모드: **Local**
-  앱이 구성된 포트에서 실행 중인 Gateway에 연결됩니다.
+  앱이 구성된 포트에서 실행 중인 gateway에 연결됩니다.
 
 ### 3) 확인
 
-- 앱 내 Gateway 상태에 **“Using existing gateway …”**가 표시되어야 합니다
-- 또는 CLI로 확인:
+- 앱 내 Gateway 상태에 **“기존 gateway 사용 중 …”** 이라고 표시되어야 합니다.
+- 또는 CLI에서:
 
 ```bash
 openclaw health
 ```
 
-### 흔한 함정
+### 흔히 겪는 문제
 
 - **잘못된 포트:** Gateway WS 기본값은 `ws://127.0.0.1:18789`입니다. 앱과 CLI가 같은 포트를 사용하도록 유지하세요.
 - **상태가 저장되는 위치:**
-  - 채널/provider 상태: `~/.openclaw/credentials/`
+  - 채널/프로바이더 상태: `~/.openclaw/credentials/`
   - 모델 인증 프로필: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
   - 세션: `~/.openclaw/agents/<agentId>/sessions/`
   - 로그: `/tmp/openclaw/`
 
 ## 자격 증명 저장소 맵
 
-인증을 디버깅하거나 무엇을 백업할지 결정할 때 이것을 사용하세요.
+인증 문제를 디버깅하거나 무엇을 백업할지 결정할 때 사용하세요:
 
 - **WhatsApp**: `~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
-- **Telegram bot token**: config/env 또는 `channels.telegram.tokenFile`(일반 파일만 허용; 심볼릭 링크는 거부됨)
-- **Discord bot token**: config/env 또는 SecretRef(env/file/exec providers)
-- **Slack 토큰**: config/env (`channels.slack.*`)
+- **Telegram bot token**: config/env 또는 `channels.telegram.tokenFile` (일반 파일만 허용, symlink는 거부됨)
+- **Discord bot token**: config/env 또는 SecretRef (env/file/exec providers)
+- **Slack tokens**: config/env (`channels.slack.*`)
 - **페어링 허용 목록**:
   - `~/.openclaw/credentials/<channel>-allowFrom.json` (기본 계정)
-  - `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (비기본 계정)
+  - `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (기본이 아닌 계정)
 - **모델 인증 프로필**: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
-- **파일 기반 secrets payload(선택 사항)**: `~/.openclaw/secrets.json`
+- **파일 기반 시크릿 페이로드(선택 사항)**: `~/.openclaw/secrets.json`
 - **레거시 OAuth 가져오기**: `~/.openclaw/credentials/oauth.json`
-  자세한 내용: [Security](/ko/gateway/security#credential-storage-map).
+  자세한 내용: [보안](/ko/gateway/security#credential-storage-map).
 
 ## 업데이트(설정을 망가뜨리지 않고)
 
-- `~/.openclaw/workspace`와 `~/.openclaw/`를 “내 것”으로 유지하세요. 개인 프롬프트/구성을 `openclaw` 리포지토리에 넣지 마세요.
-- 소스 업데이트: `git pull` + 선택한 패키지 관리자 설치 단계(기본값은 `pnpm install`, Bun workflow는 `bun install`) + 계속해서 일치하는 `gateway:watch` 명령을 사용하세요.
+- `~/.openclaw/workspace`와 `~/.openclaw/`는 “내 것”으로 유지하세요. 개인 프롬프트/구성을 `openclaw` 리포지토리에 넣지 마세요.
+- 소스 업데이트: `git pull` + 선택한 패키지 관리자 설치 단계(기본값은 `pnpm install`, Bun 워크플로우는 `bun install`) + 계속해서 같은 `gateway:watch` 명령을 사용하세요.
 
 ## Linux(systemd 사용자 서비스)
 
-Linux 설치는 systemd **사용자** 서비스를 사용합니다. 기본적으로 systemd는 로그아웃/유휴 시 사용자
-서비스를 중지하므로 Gateway도 종료됩니다. 온보딩은 사용자를 위해 lingering을 활성화하려고 시도합니다(sudo를 요청할 수 있음). 여전히 꺼져 있다면 다음을 실행하세요.
+Linux 설치는 systemd **사용자** 서비스를 사용합니다. 기본적으로 systemd는
+로그아웃/유휴 상태에서 사용자 서비스를 중지하므로 Gateway도 종료됩니다. 온보딩은
+사용자를 대신해 lingering을 활성화하려고 시도합니다(sudo 프롬프트가 나타날 수 있음). 여전히 비활성화되어 있으면 다음을 실행하세요:
 
 ```bash
 sudo loginctl enable-linger $USER
 ```
 
-항상 켜져 있어야 하거나 다중 사용자 서버라면, **사용자** 서비스 대신 **시스템** 서비스를 고려하세요
-(lingering 불필요). systemd 관련 참고 사항은 [Gateway runbook](/ko/gateway)을 참조하세요.
+항상 켜져 있어야 하거나 다중 사용자 서버인 경우에는
+사용자 서비스 대신 **시스템** 서비스를 고려하세요(lingering 불필요). systemd 관련 참고 사항은 [Gateway 실행 가이드](/ko/gateway)를 확인하세요.
 
 ## 관련 문서
 
-- [Gateway runbook](/ko/gateway) (플래그, 감독, 포트)
-- [Gateway configuration](/ko/gateway/configuration) (구성 스키마 + 예시)
-- [Discord](/ko/channels/discord) 및 [Telegram](/ko/channels/telegram) (reply 태그 + replyToMode 설정)
-- [OpenClaw assistant setup](/start/openclaw)
-- [macOS app](/ko/platforms/macos) (gateway 수명 주기)
+- [Gateway 실행 가이드](/ko/gateway) (플래그, 감독, 포트)
+- [Gateway 구성](/ko/gateway/configuration) (구성 스키마 + 예시)
+- [Discord](/ko/channels/discord) 및 [Telegram](/ko/channels/telegram) (답장 태그 + replyToMode 설정)
+- [OpenClaw assistant 설정](/ko/start/openclaw)
+- [macOS 앱](/ko/platforms/macos) (gateway 수명 주기)