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-15 14:49:49 +00:00
parent 176058bbfb
commit b95a4493de
12 changed files with 2009 additions and 1968 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
docs/ko/concepts/dreaming.md
View File

@ -1,23 +1,23 @@
---
read_when:
- 메모리 승격이 자동으로 실행되도록 하려는 경우
- 각 Dreaming 단계가 무엇을 하는지 이해하고 싶은 경우
- '`MEMORY.md`를 오염시키지 않고 통합을 조정하려는 경우'
- 메모리 승격이 자동으로 실행되기를 원합니다
- 각 Dreaming 단계가 무엇을 하는지 이해하고 싶습니다
- '`MEMORY.md`를 오염시키지 않고 통합을 조정하고 싶습니다'
summary: 가벼운 수면, 깊은 수면, REM 단계와 Dream Diary를 포함한 백그라운드 메모리 통합
title: Dreaming (실험적)
title: Dreaming
x-i18n:
generated_at: "2026-04-15T06:00:32Z"
generated_at: "2026-04-15T14:40:30Z"
model: gpt-5.4
provider: openai
source_hash: 5882a5068f2eabe54ca9893184e5385330a432b921870c38626399ce11c31e25
source_hash: a5bcaec80f62e7611ed533094ef1917bd72c885f57252824db910e1f0496adc6
source_path: concepts/dreaming.md
workflow: 15
---
# Dreaming (실험적)
# Dreaming
Dreaming은 `memory-core`의 백그라운드 메모리 통합 시스템입니다.
이 기능은 OpenClaw가 강한 단기 신호를 지속 가능한 메모리로 옮기도록 도우면서,
이 시스템은 OpenClaw가 강한 단기 신호를 지속 가능한 메모리로 옮길 수 있도록 도우면서,
그 과정이 설명 가능하고 검토 가능하도록 유지합니다.
Dreaming은 **옵트인** 방식이며 기본적으로 비활성화되어 있습니다.
@ -26,101 +26,104 @@ Dreaming은 **옵트인** 방식이며 기본적으로 비활성화되어 있습
Dreaming은 두 종류의 출력을 유지합니다.
- `memory/.dreams/`의 **기계 상태**(recall 저장소, phase 신호, 수집 체크포인트, 잠금).
- `DREAMS.md`(또는 기존 `dreams.md`)의 **사람이 읽을 수 있는 출력**과 `memory/dreaming/<phase>/YYYY-MM-DD.md` 아래의 선택적 phase 보고서 파일.
- `memory/.dreams/`의 **머신 상태**(리콜 저장소, 단계 신호, 수집 체크포인트, 잠금)
- `DREAMS.md`(또는 기존 `dreams.md`)의 **사람이 읽을 수 있는 출력**, 그리고 선택적으로 `memory/dreaming/<phase>/YYYY-MM-DD.md` 아래의 단계 보고서 파일
장기 승격은 계속해서 `MEMORY.md`에만 기록됩니다.
장기 승격은 여전히 `MEMORY.md`에만 기록됩니다.
## 단계 모델
Dreaming은 세 가지 협력 단계로 동작합니다.
Dreaming은 협력적으로 작동하는 세 가지 단계를 사용합니다.
| 단계 | 목적 | 지속 기록 |
| ----- | ---- | --------- |
| 가벼운 수면 | 최근 단기 자료를 분류하고 준비 | 아니요 |
| 깊은 수면 | 지속 가능한 후보를 점수화하고 승격 | 예 (`MEMORY.md`) |
| REM | 주제와 반복되는 아이디어를 성찰 | 아니요 |
| Light | 최근 단기 자료 정렬 및 스테이징 | 아니요 |
| Deep | 지속 가능한 후보 점수화 및 승격 | 예 (`MEMORY.md`) |
| REM | 테마와 반복되는 아이디어에 대한 성찰 | 아니요 |
이 단계들은 별도의 사용자 구성 "모드"가 아니라 내부 구현 세부 사항입니다.
이 단계들은 내부 구현 세부사항이며, 사용자가 따로 설정하는
"모드"가 아닙니다.
### 가벼운 수면 단계
### Light 단계
가벼운 수면 단계는 최근 일일 메모리 신호와 recall 추적을 수집하고, 중복을 제거한 뒤,
후보 줄을 준비합니다.
Light 단계는 최근 일일 메모리 신호와 리콜 추적을 수집하고, 이를 중복 제거한 뒤
후보 줄을 스테이징합니다.
- 가능한 경우 단기 recall 상태, 최근 일일 메모리 파일, 비식별 처리된 세션 기록을 읽습니다.
- 저장소에 인라인 출력이 포함된 경우 관리되는 `## Light Sleep` 블록을 기록합니다.
- 이후 깊은 순위 산정을 위한 강화 신호를 기록합니다.
- 절대 `MEMORY.md`에 기록하지 않습니다.
- 사용 가능한 경우 단기 리콜 상태, 최근 일일 메모리 파일, 그리고 비식별화된 세션 기록을 읽습니다.
- 저장소에 인라인 출력이 포함되어 있으면 관리되는 `## Light Sleep` 블록을 기록합니다.
- 이후 Deep 순위 산정을 위한 강화 신호를 기록합니다.
- 절대 `MEMORY.md`에는 기록하지 않습니다.
### 깊은 수면 단계
### Deep 단계
깊은 수면 단계는 무엇이 장기 메모리가 될지 결정합니다.
Deep 단계는 무엇이 장기 메모리가 될지 결정합니다.
- 가중치 기반 점수와 임계값 게이트를 사용해 후보의 순위를 매깁니다.
- 통과하려면 `minScore`, `minRecallCount`, `minUniqueQueries`가 필요합니다.
- 기록 전에 실제 일일 파일에서 스니펫을 다시 불러오므로, 오래되었거나 삭제된 스니펫은 건너뜁니다.
- 가중 점수와 임계값 게이트를 사용해 후보 순위를 매깁니다.
- 통과하려면 `minScore`, `minRecallCount`, `minUniqueQueries`를 충족해야 합니다.
- 기록 전에 라이브 일일 파일에서 스니펫을 다시 불러오므로, 오래되었거나 삭제된 스니펫은 건너뜁니다.
- 승격된 항목을 `MEMORY.md`에 추가합니다.
- `DREAMS.md`에 `## Deep Sleep` 요약을 기록하고, 선택적으로 `memory/dreaming/deep/YYYY-MM-DD.md`도 기록합니다.
- `DREAMS.md`에 `## Deep Sleep` 요약을 기록하고, 선택적으로 `memory/dreaming/deep/YYYY-MM-DD.md`를 기록합니다.
### REM 단계
REM 단계는 패턴과 성찰 신호를 추출합니다.
- 최근 단기 추적에서 주제 및 성찰 요약을 생성합니다.
- 저장소에 인라인 출력이 포함된 경우 관리되는 `## REM Sleep` 블록을 기록합니다.
- 깊은 순위 산정에 사용되는 REM 강화 신호를 기록합니다.
- 절대 `MEMORY.md`에 기록하지 않습니다.
- 최근 단기 추적에서 테마 및 성찰 요약을 생성합니다.
- 저장소에 인라인 출력이 포함되어 있으면 관리되는 `## REM Sleep` 블록을 기록합니다.
- Deep 순위 산정에 사용되는 REM 강화 신호를 기록합니다.
- 절대 `MEMORY.md`에는 기록하지 않습니다.
## 세션 기록 수집
Dreaming은 비식별 처리된 세션 기록을 Dreaming 코퍼스에 수집할 수 있습니다. 기록을
사용할 수 있으면, 일일 메모리 신호와 recall 추적과 함께 가벼운 수면 단계에 입력됩니다.
개인 정보 및 민감한 내용은 수집 전에 비식별 처리됩니다.
Dreaming은 비식별화된 세션 기록을 Dreaming 코퍼스에 수집할 수 있습니다.
기록을 사용할 수 있는 경우, 이는 일일 메모리 신호 및 리콜 추적과 함께 Light 단계에 입력됩니다.
개인 정보 및 민감한 내용은 수집 전에 비식별화됩니다.
## Dream Diary
Dreaming은 또한 `DREAMS.md`에 서술형 **Dream Diary**를 유지합니다.
각 단계에 충분한 자료가 쌓이면 `memory-core`는 최선형 백그라운드 하위 에이전트 턴을
실행하고(기본 런타임 모델 사용) 짧은 다이어리 항목을 추가합니다.
각 단계에 충분한 자료가 쌓이면 `memory-core`는 최선의 노력 방식의 백그라운드
서브에이전트 턴(기본 런타임 모델 사용)을 실행하고 짧은 일기 항목을 추가합니다.
이 다이어리는 Dreams UI에서 사람이 읽기 위한 것이며, 승격 소스가 아닙니다.
Dreaming이 생성한 다이어리/보고서 아티팩트는 단기 승격에서 제외됩니다.
근거가 있는 메모리 스니펫만 `MEMORY.md`로 승격될 수 있습니다.
이 일기는 Dreams UI에서 사람이 읽기 위한 것이며, 승격 소스가 아닙니다.
Dreaming이 생성한 일기/보고서 아티팩트는 단기
승격 대상에서 제외됩니다. 오직 근거가 있는 메모리 스니펫만
`MEMORY.md`로 승격될 수 있습니다.
검토 및 복구 작업을 위한 근거 기반의 과거 백필 경로도 있습니다.
검토 및 복구 작업을 위한 근거 기반 과거 백필 경로도 있습니다.
- `memory rem-harness --path ... --grounded`는 과거 `YYYY-MM-DD.md` 노트에서 근거 기반 다이어리 출력을 미리 봅니다.
- `memory rem-backfill --path ...`는 되돌릴 수 있는 근거 기반 다이어리 항목을 `DREAMS.md`에 기록합니다.
- `memory rem-backfill --path ... --stage-short-term`는 근거 기반의 지속 가능한 후보를 일반 깊은 단계가 이미 사용하는 것과 동일한 단기 증거 저장소에 준비합니다.
- `memory rem-backfill --rollback` 및 `--rollback-short-term`는 일반 다이어리 항목이나 실시간 단기 recall을 건드리지 않고 이러한 준비된 백필 아티팩트를 제거합니다.
- `memory rem-harness --path ... --grounded`는 과거 `YYYY-MM-DD.md` 노트에서 근거 기반 일기 출력을 미리 봅니다.
- `memory rem-backfill --path ...`는 되돌릴 수 있는 근거 기반 일기 항목을 `DREAMS.md`에 기록합니다.
- `memory rem-backfill --path ... --stage-short-term`는 근거 기반 지속 후보를 일반 Deep 단계가 이미 사용하는 동일한 단기 증거 저장소에 스테이징합니다.
- `memory rem-backfill --rollback` 및 `--rollback-short-term`은 일반 일기 항목이나 라이브 단기 리콜은 건드리지 않고 해당 스테이징된 백필 아티팩트를 제거합니다.
Control UI는 동일한 다이어리 백필/재설정 흐름을 제공하므로, 근거 기반 후보가
승격될 가치가 있는지 판단하기 전에 Dreams 장면에서 결과를 검사할 수 있습니다.
이 장면은 또한 별도의 근거 기반 레인을 표시하여 어떤 준비된 단기 항목이 과거 재생에서
나왔는지, 어떤 승격 항목이 근거 기반으로 주도되었는지 확인할 수 있게 하며, 일반
실시간 단기 상태를 건드리지 않고 근거 기반 전용 준비 항목만 지울 수 있습니다.
Control UI는 동일한 일기 백필/재설정 흐름을 제공하므로, 근거 기반 후보가
승격할 가치가 있는지 결정하기 전에 Dreams 장면에서 결과를
검토할 수 있습니다. 이 장면은 또한 별도의 근거 기반 레인도 표시하여
어떤 스테이징된 단기 항목이 과거 재생에서 왔는지, 어떤 승격된
항목이 근거 기반 주도였는지 확인할 수 있게 하며, 일반 라이브 단기 상태를
건드리지 않고 근거 기반 전용 스테이징 항목만 지울 수 있습니다.
## 깊은 순위 산정 신호
## Deep 순위 산정 신호
깊은 순위 산정은 여섯 개의 가중치 기반 기본 신호와 단계 강화 신호를 사용합니다.
Deep 순위 산정은 여섯 가지 가중 기본 신호와 단계 강화 신호를 사용합니다.
| 신호 | 가중치 | 설명 |
| ------------------- | ------ | ------------------------------------------------- |
| 빈도 | 0.24 | 항목이 누적한 단기 신호 수 |
| 관련성 | 0.30 | 항목의 평균 검색 품질 |
| 쿼리 다양성 | 0.15 | 항목이 드러난 서로 다른 쿼리/일자 맥락 |
| 쿼리 다양성 | 0.15 | 해당 항목이 드러난 고유한 쿼리/일자 맥락 |
| 최신성 | 0.15 | 시간 감쇠 기반 신선도 점수 |
| 통합 | 0.10 | 여러 날짜에 걸친 반복 강도 |
| 개념적 풍부함 | 0.06 | 스니펫/경로에서의 개념 태그 밀도 |
| 개념적 풍부함 | 0.06 | 스니펫/경로의 개념 태그 밀도 |
가벼운 수면 및 REM 단계의 적중은
Light 및 REM 단계 히트는
`memory/.dreams/phase-signals.json`에서 작은 최신성 감쇠 부스트를 추가합니다.
## 예약 실행
활성화되면 `memory-core`는 전체 Dreaming 스윕을 위한 Cron 작업 하나를 자동 관리합니다.
각 스윕은 다음 순서로 단계를 실행합니다: 가벼운 수면 -> REM -> 깊은 수면.
각 스윕은 순서대로 단계를 실행합니다: light -> REM -> deep.
기본 주기 동작:
@ -168,7 +171,7 @@ Dreaming 활성화:
}
```
## 슬래시 명령
## 슬래시 명령어
```
/dreaming status
@ -188,16 +191,16 @@ openclaw memory promote --limit 5
openclaw memory status --deep
```
수동 `memory promote`는 CLI 플래그로 재정의하지 않는 한 기본적으로 깊은 수면 단계 임계값을 사용합니다.
수동 `memory promote`는 CLI 플래그로 재정의하지 않는 한 기본적으로 Deep 단계 임계값을 사용합니다.
특정 후보가 왜 승격되거나 승격되지 않는지 설명합니다.
특정 후보가 왜 승격되거나 승격되지 않는지 설명하기:
```bash
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
```
아무것도 기록하지 않고 REM 성찰, 후보 사실, 깊은 승격 출력을 미리 봅니다.
아무것도 기록하지 않고 REM 성찰, 후보 진실, Deep 승격 출력을 미리 보기:
```bash
openclaw memory rem-harness
@ -213,23 +216,24 @@ openclaw memory rem-harness --json
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
단계 정책, 임계값, 저장소 동작은 내부 구현 세부 사항이며
사용자 대상 설정이 아닙니다.
단계 정책, 임계값, 저장소 동작은 내부 구현
세부사항이며(사용자 대상 설정이 아님)입니다.
전체 키 목록은 [메모리 구성 참조](/ko/reference/memory-config#dreaming-experimental)를 참조하세요.
전체 키 목록은
[메모리 구성 참조](/ko/reference/memory-config#dreaming)를 참조하세요.
## Dreams UI
활성화되면 Gateway의 **Dreams** 탭에는 다음이 표시됩니다.
- 현재 Dreaming 활성화 상태
- 단계별 상태와 관리되는 스윕 존재 여부
- 단계별 상태 및 관리 스윕 존재 여부
- 단기, 근거 기반, 신호, 오늘 승격 수
- 다음 예약 실행 시점
- 준비된 과거 재생 항목을 위한 별도의 근거 기반 장면 레인
- 스테이징된 과거 재생 항목을 위한 별도의 근거 기반 장면 레인
- `doctor.memory.dreamDiary`를 기반으로 하는 확장 가능한 Dream Diary 리더
## 관련 항목
## 관련 문서
- [메모리](/ko/concepts/memory)
- [메모리 검색](/ko/concepts/memory-search)

44
docs/ko/concepts/experimental-features.md Normal file
View File

@ -0,0 +1,44 @@
---
read_when:
- '``.experimental`` config 키를 보고 이것이 안정적인지 알고 싶습니다.'
- 일반 기본값과 혼동하지 않으면서 미리보기 런타임 기능을 사용해 보고 싶습니다.
- 현재 문서화된 experimental 플래그를 한곳에서 찾고 싶습니다.
summary: OpenClaw에서 experimental 플래그는 무엇을 의미하며 현재 어떤 항목이 문서화되어 있나요?
title: 실험적 기능
x-i18n:
generated_at: "2026-04-15T14:40:30Z"
model: gpt-5.4
provider: openai
source_hash: 2d1c7b3d4cd56ef8a0bdab1deb9918e9b2c9a33f956d63193246087f8633dcf3
source_path: concepts/experimental-features.md
workflow: 15
---
# 실험적 기능
OpenClaw의 실험적 기능은 **옵트인 미리보기 표면**입니다. 안정적인 기본값이나 오래 유지되는 공개 계약으로 자리 잡기 전에 실제 환경에서의 충분한 검증이 더 필요하기 때문에, 명시적인 플래그 뒤에 숨겨져 있습니다.
이를 일반 config와는 다르게 취급하세요.
- 관련 문서에서 사용해 보라고 안내하지 않는 한 **기본적으로 꺼 둡니다**.
- 안정적인 config보다 **형태와 동작이 더 빠르게 바뀔 수 있음**을 예상하세요.
- 이미 안정적인 경로가 있다면 먼저 그 경로를 우선하세요.
- OpenClaw를 널리 배포하려는 경우, experimental 플래그를 공용 기준 설정에 포함하기 전에 더 작은 환경에서 먼저 테스트하세요.
## 현재 문서화된 플래그
| 표면 | 키 | 이런 경우 사용 | 자세히 보기 |
| ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 로컬 모델 런타임 | `agents.defaults.experimental.localModelLean` | 더 작거나 더 엄격한 로컬 백엔드가 OpenClaw의 전체 기본 도구 표면을 감당하지 못하는 경우 | [로컬 모델](/ko/gateway/local-models) |
| 메모리 검색 | `agents.defaults.memorySearch.experimental.sessionMemory` | `memory_search`가 이전 세션 대화 기록을 인덱싱하도록 하고, 추가 저장소/인덱싱 비용을 감수할 의향이 있는 경우 | [메모리 config 참조](/ko/reference/memory-config#session-memory-search-experimental) |
| 구조화된 계획 도구 | `tools.experimental.planTool` | 호환되는 런타임과 UI에서 다단계 작업 추적을 위해 구조화된 `update_plan` 도구를 노출하고 싶은 경우 | [Gateway config 참조](/ko/gateway/configuration-reference#toolsexperimental) |
## 로컬 모델 린 모드
`agents.defaults.experimental.localModelLean: true`는 성능이 약한 로컬 모델 환경을 위한 완충 장치입니다. `browser`, `cron`, `message` 같은 무거운 기본 도구를 줄여, 작은 컨텍스트나 더 엄격한 OpenAI 호환 백엔드에서도 프롬프트 형태가 더 작고 덜 취약하도록 만듭니다.
이것은 의도적으로 **일반적인 경로가 아닙니다**. 백엔드가 전체 런타임을 문제없이 처리할 수 있다면, 이 옵션은 끄고 두세요.
## 실험적이라고 해서 숨겨야 하는 것은 아닙니다
기능이 실험적이라면, OpenClaw는 문서와 config 경로 자체에서 이를 분명하게 밝혀야 합니다. 반대로 해서는 안 되는 것은, 미리보기 동작을 안정적으로 보이는 기본 노브에 몰래 섞어 넣고 그것이 정상인 것처럼 가장하는 일입니다. 그렇게 하면 config 표면이 지저분해집니다.

69
docs/ko/concepts/memory-search.md
View File

@ -1,26 +1,26 @@
---
read_when:
- memory_search가 어떻게 작동하는지 이해하고 싶습니다
- 임베딩 제공자를 선택하고 싶습니다
- 검색 품질을 조정하고 싶습니다
summary: 메모리 검색이 임베딩과 하이브리드 검색을 사용해 관련 노트를 찾는 방법
- memory_search가 어떻게 작동하는지 이해하고 싶습니다.
- 임베딩 제공자를 선택하고 싶습니다.
- 검색 품질을 조정하고 싶습니다.
summary: 메모리 검색은 임베딩과 하이브리드 검색을 사용해 관련 메모를 찾습니다
title: 메모리 검색
x-i18n:
generated_at: "2026-04-12T23:28:04Z"
generated_at: "2026-04-15T14:40:32Z"
model: gpt-5.4
provider: openai
source_hash: 71fde251b7d2dc455574aa458e7e09136f30613609ad8dafeafd53b2729a0310
source_hash: f5757aa8fe8f7fec30ef5c826f72230f591ce4cad591d81a091189d50d4262ed
source_path: concepts/memory-search.md
workflow: 15
---
# 메모리 검색
`memory_search`는 메모리 파일에서 관련 노트를 찾습니다. 원문과 표현이 달라도 찾을 수 있습니다. 이 기능은 메모리를 작은 청크로 인덱싱한 다음, 임베딩, 키워드 또는 둘 다를 사용해 검색합니다.
`memory_search`는 원문의 표현이 달라도 메모리 파일에서 관련 메모를 찾습니다. 이 기능은 메모리를 작은 청크로 인덱싱한 뒤, 임베딩, 키워드 또는 둘 다를 사용해 검색하는 방식으로 동작합니다.
## 빠른 시작
OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모리 검색은 자동으로 작동합니다. 제공자를 명시적으로 설정하려면 다음과 같이 하세요.
GitHub Copilot 구독이 있거나 OpenAI, Gemini, Voyage, Mistral API 키가 구성되어 있으면 메모리 검색은 자동으로 작동합니다. 제공자를 명시적으로 설정하려면 다음과 같이 하세요.
```json5
{
@ -38,19 +38,20 @@ API 키 없이 로컬 임베딩을 사용하려면 `provider: "local"`을 사용
## 지원되는 제공자
| 제공자 | ID | API 키 필요 | 참고 |
| ------- | --------- | ----------- | ---------------------------------------------------- |
| OpenAI | `openai` | 예 | 자동 감지, 빠름 |
| Gemini | `gemini` | 예 | 이미지/오디오 인덱싱 지원 |
| Voyage | `voyage` | 예 | 자동 감지 |
| Mistral | `mistral` | 예 | 자동 감지 |
| Bedrock | `bedrock` | 아니요 | AWS 자격 증명 체인이 확인되면 자동 감지 |
| Ollama | `ollama` | 아니요 | 로컬, 명시적으로 설정해야 함 |
| Local | `local` | 아니요 | GGUF 모델, 약 0.6 GB 다운로드 |
| 제공자 | ID | API 키 필요 | 참고 |
| -------------- | ---------------- | ------------- | ---------------------------------------------------- |
| Bedrock | `bedrock` | 아니요 | AWS 자격 증명 체인이 확인되면 자동 감지됨 |
| Gemini | `gemini` | 예 | 이미지/오디오 인덱싱 지원 |
| GitHub Copilot | `github-copilot` | 아니요 | 자동 감지되며 Copilot 구독 사용 |
| Local | `local` | 아니요 | GGUF 모델, 약 0.6GB 다운로드 |
| Mistral | `mistral` | 예 | 자동 감지됨 |
| Ollama | `ollama` | 아니요 | 로컬, 명시적으로 설정해야 함 |
| OpenAI | `openai` | 예 | 자동 감지되며 빠름 |
| Voyage | `voyage` | 예 | 자동 감지됨 |
## 검색 작동 방식
OpenClaw는 두 개의 검색 경로를 병렬로 실행하고 결과를 병합합니다.
OpenClaw는 두 개의 검색 경로를 병렬로 실행한 뒤 결과를 병합합니다.
```mermaid
flowchart LR
@ -63,31 +64,31 @@ flowchart LR
M --> R["Top Results"]
```
- **벡터 검색**은 의미가 비슷한 노트를 찾습니다(예: "gateway host"는 "OpenClaw를 실행하는 머신"과 일치).
- **벡터 검색**은 의미가 비슷한 메모를 찾습니다(`"gateway host"`가 `"OpenClaw를 실행하는 머신"`과 매칭됨).
- **BM25 키워드 검색**은 정확히 일치하는 항목을 찾습니다(ID, 오류 문자열, config 키).
한 경로만 사용할 수 있는 경우(임베딩 없음 또는 FTS 없음) 다른 한 경로만 단독으로 실행됩니다.
한 경로만 사용할 수 있는 경우(임베딩 없음 또는 FTS 없음)에는 다른 한 경로만 단독으로 실행됩니다.
임베딩을 사용할 수 없을 때도 OpenClaw는 단순한 원시 exact-match 정렬로만 되돌아가지 않고 FTS 결과에 대해 어휘 기반 순위를 계속 사용합니다. 이 저하 모드에서는 쿼리 용어를 더 강하게 포괄하는 청크와 관련 파일 경로의 점수를 높여, `sqlite-vec` 또는 임베딩 제공자가 없어도 재현율을 유용하게 유지합니다.
임베딩을 사용할 수 없는 경우에도 OpenClaw는 단순한 원시 정확 일치 순서로만 되돌아가지 않고, FTS 결과에 대해 여전히 어휘 기반 순위를 적용합니다. 이 저하 모드는 쿼리 용어를 더 잘 포함하고 관련 파일 경로를 가진 청크를 우선하므로, `sqlite-vec`나 임베딩 제공자가 없어도 재현율을 유용한 수준으로 유지합니다.
## 검색 품질 개선
노트 기록이 많은 경우 도움이 되는 두 가지 선택적 기능이 있습니다.
메모 기록이 많은 경우, 두 가지 선택적 기능이 도움이 됩니다.
### 시간 감쇠
오래된 노트는 순위 가중치가 점차 줄어들어 더 최근 정보가 먼저 표시됩니다. 기본 반감기인 30일 기준으로 지난달의 노트는 원래 가중치의 50% 점수를 받습니다. `MEMORY.md` 같은 evergreen 파일에는 감쇠가 적용되지 않습니다.
오래된 메모는 순위 가중치가 점차 줄어들어 최근 정보가 먼저 표시됩니다. 기본 반감기 30일 설정에서는 지난달 메모의 점수가 원래 가중치의 50%가 됩니다. `MEMORY.md` 같은 에버그린 파일은 감쇠되지 않습니다.
<Tip>
에이전트에 수개월치 일일 노트가 있고 오래된 정보가 최신 컨텍스트보다 계속 더 높은 순위에 오르면 시간 감쇠를 활성화하세요.
에이전트에 수개월치 일일 메모가 있고 오래된 정보가 최신 컨텍스트보다 계속 상위에 노출된다면 시간 감쇠를 활성화하세요.
</Tip>
### MMR(다양성)
중복되는 결과를 줄입니다. 다섯 개의 노트가 모두 같은 라우터 구성을 언급하더라도, MMR은 같은 내용을 반복하는 대신 상위 결과가 서로 다른 주제를 다루도록 합니다.
중복 결과를 줄입니다. 메모 5개가 모두 같은 라우터 설정을 언급하더라도, MMR은 상위 결과가 반복되지 않고 서로 다른 주제를 다루도록 보장합니다.
<Tip>
`memory_search`가 서로 다른 일일 노트에서 나온 거의 중복된 스니펫을 계속 반환하면 MMR을 활성화하세요.
`memory_search`가 서로 다른 일일 메모에서 거의 중복된 스니펫을 계속 반환한다면 MMR을 활성화하세요.
</Tip>
### 둘 다 활성화
@ -111,22 +112,22 @@ flowchart LR
## 멀티모달 메모리
Gemini Embedding 2를 사용하면 Markdown과 함께 이미지 및 오디오 파일도 인덱싱할 수 있습니다. 검색 쿼리는 여전히 텍스트이지만, 시각 및 오디오 콘텐츠와 매칭됩니다. 설정 방법은 [메모리 구성 참조](/ko/reference/memory-config)를 확인하세요.
Gemini Embedding 2를 사용하면 Markdown과 함께 이미지와 오디오 파일도 인덱싱할 수 있습니다. 검색 쿼리는 여전히 텍스트이지만, 시각 및 오디오 콘텐츠와 매칭됩니다. 설정 방법은 [메모리 구성 참조](/ko/reference/memory-config)를 참고하세요.
## 세션 메모리 검색
선택적으로 세션 전사본을 인덱싱하여 `memory_search`가 이전 대화를 회상할 수 있게 할 수 있습니다. 이 기능은 `memorySearch.experimental.sessionMemory`를 통해 opt-in 방식으로 활성화됩니다. 자세한 내용은 [구성 참조](/ko/reference/memory-config)를 확인하세요.
선택적으로 세션 기록도 인덱싱해 `memory_search`가 이전 대화를 기억하도록 할 수 있습니다. 이 기능은 `memorySearch.experimental.sessionMemory`를 통해 옵트인 방식으로 활성화됩니다. 자세한 내용은 [구성 참조](/ko/reference/memory-config)를 참고하세요.
## 문제 해결
**결과가 없나요?** 인덱스를 확인하려면 `openclaw memory status`를 실행하세요. 비어 있으면 `openclaw memory index --force`를 실행하세요.
**결과가 없나요?** 인덱스를 확인하려면 `openclaw memory status`를 실행하세요. 비어 있다면 `openclaw memory index --force`를 실행하세요.
**키워드 일치만 보이나요?** 임베딩 제공자가 구성되지 않았을 수 있습니다. `openclaw memory status --deep`를 확인하세요.
**키워드 일치만 나오나요?** 임베딩 제공자가 구성되지 않았을 수 있습니다. `openclaw memory status --deep`로 확인하세요.
**CJK 텍스트를 찾을 수 없나요?** `openclaw memory index --force`로 FTS 인덱스를 다시 빌드하세요.
**CJK 텍스트를 찾지 못하나요?** `openclaw memory index --force`로 FTS 인덱스를 다시 빌드하세요.
## 추가 읽을거리
## 더 읽어보기
- [Active Memory](/ko/concepts/active-memory) -- 대화형 채팅 세션용 하위 에이전트 메모리
- [메모리](/ko/concepts/memory) -- 파일 레이아웃, 백엔드, 도구
- [Active Memory](/ko/concepts/active-memory) -- 대화형 채팅 세션을 위한 서브에이전트 메모리
- [Memory](/ko/concepts/memory) -- 파일 레이아웃, 백엔드, 도구
- [메모리 구성 참조](/ko/reference/memory-config) -- 모든 구성 옵션

110
docs/ko/concepts/memory.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 메모리가 어떻게 작동하는지 이해하고 싶을 때
- 어떤 메모리 파일에 작성해야 하는지 알고 싶을 때
summary: OpenClaw가 세션 전반에 걸쳐 정보를 기억하는 방법
- 메모리가 어떻게 작동하는지 이해하고 싶습니다
- 어떤 메모리 파일에 작성해야 하는지 알고 싶습니다
summary: OpenClaw가 세션 전반에 걸쳐 정보를 기억하는 방식
title: 메모리 개요
x-i18n:
generated_at: "2026-04-09T01:27:57Z"
generated_at: "2026-04-15T14:40:46Z"
model: gpt-5.4
provider: openai
source_hash: 2fe47910f5bf1c44be379e971c605f1cb3a29befcf2a7ee11fb3833cbe3b9059
source_hash: ad1adafe1d81f1703d24f48a9c9da2b25a0ebbd4aad4f65d8bde5df78195d55b
source_path: concepts/memory.md
workflow: 15
---
@ -19,119 +19,119 @@ OpenClaw는 에이전트의 워크스페이스에 **일반 Markdown 파일**을
## 작동 방식
에이전트에는 메모리와 관련된 파일이 세 가지 있습니다.
에이전트에는 메모리 관련 파일이 세 가지 있습니다:
- **`MEMORY.md`** -- 장기 메모리입니다. 지속되는 사실, 선호 사항, 결정 사항을 담습니다. 모든 DM 세션이 시작될 때 로드됩니다.
- **`MEMORY.md`** -- 장기 메모리입니다. 지속되는 사실, 선호도, 결정 사항을 담습니다. 모든 DM 세션이 시작될 때 로드됩니다.
- **`memory/YYYY-MM-DD.md`** -- 일일 노트입니다. 진행 중인 컨텍스트와 관찰 내용을 담습니다. 오늘과 어제의 노트는 자동으로 로드됩니다.
- **`DREAMS.md`** (실험적, 선택 사항) -- 사람의 검토를 위한 Dream Diary 및 dreaming sweep 요약을 담으며, 근거 기반의 과거 백필 항목도 포함합니다.
- **`DREAMS.md`** (선택 사항) -- 인간이 검토할 수 있도록 Dream Diary와 Dreaming 스윕 요약을 포함하며, 근거가 있는 과거 소급 항목도 포함합니다.
이 파일들은 에이전트 워크스페이스에 있습니다(기본값 `~/.openclaw/workspace`).
이 파일들은 에이전트 워크스페이스(기본값 `~/.openclaw/workspace`)에 있습니다.
<Tip>
에이전트가 무언가를 기억하길 원한다면, 그냥 이렇게 요청하면 됩니다: "내가 TypeScript를 선호한다고 기억해." 그러면 적절한 파일에 기록합니다.
에이전트가 무언가를 기억하길 원한다면, 이렇게 요청하면 됩니다: "내가 TypeScript를 선호한다고 기억해." 그러면 적절한 파일에 기록합니다.
</Tip>
## 메모리 도구
에이전트에는 메모리를 다루기 위한 두 가지 도구가 있습니다.
에이전트에는 메모리를 다루기 위한 두 가지 도구가 있습니다:
- **`memory_search`** -- 원문과 표현이 달라도 시맨틱 검색을 사용해 관련 노트를 찾습니다.
- **`memory_get`** -- 특정 메모리 파일 또는 줄 범위를 읽습니다.
- **`memory_search`** -- 원래 표현과 문구가 다르더라도 시맨틱 검색을 사용해 관련 노트를 찾습니다.
- **`memory_get`** -- 특정 메모리 파일이나 줄 범위를 읽습니다.
두 도구 모두 활성 메모리 플러그인(기본값: `memory-core`)에서 제공합니다.
두 도구 모두 활성 메모리 Plugin(기본값: `memory-core`)이 제공합니다.
## Memory Wiki 컴패니언 플러그인
## Memory Wiki 보조 Plugin
지속 메모리가 단순한 원시 노트가 아니라 관리되는 지식 베이스처럼 동작하길 원한다면, 번들된 `memory-wiki` 플러그인을 사용하세요.
지속 메모리가 단순한 원시 노트가 아니라, 유지 관리되는 지식 베이스처럼 동작하길 원한다면 번들된 `memory-wiki` Plugin을 사용하세요.
`memory-wiki`는 지속 지식을 위키 볼트로 컴파일하며, 다음을 제공합니다.
`memory-wiki`는 지속 지식을 다음과 같은 요소를 갖춘 wiki vault로 컴파일합니다:
- 결정론적인 페이지 구조
- 구조화된 주장과 증거
- 구조화된 주장과 근거
- 모순 및 최신성 추적
- 생성된 대시보드
- 에이전트/런타임 소비자를 위한 컴파일된 다이제스트
- `wiki_search`, `wiki_get`, `wiki_apply`, `wiki_lint` 같은 위키 네이티브 도구
- `wiki_search`, `wiki_get`, `wiki_apply`, `wiki_lint` 같은 wiki 네이티브 도구
이 플러그인은 활성 메모리 플러그인을 대체하지 않습니다. 활성 메모리 플러그인은 여전히 회상, 승격, dreaming을 담당합니다. `memory-wiki`는 그 옆에 출처가 풍부한 지식 계층을 추가합니다.
이 Plugin은 활성 메모리 Plugin을 대체하지 않습니다. 활성 메모리 Plugin은 여전히 회상, 승격, Dreaming을 담당합니다. `memory-wiki`는 그 옆에 출처가 풍부한 지식 계층을 추가합니다.
자세한 내용은 [Memory Wiki](/ko/plugins/memory-wiki)를 참조하세요.
## 메모리 검색
임베딩 제공자가 구성되어 있으면 `memory_search`는 **하이브리드 검색**을 사용합니다. 즉, 벡터 유사도(의미적 의미)와 키워드 매칭(ID나 코드 심볼 같은 정확한 용어)을 결합합니다. 지원되는 제공자 중 하나의 API 키만 있으면 바로 사용할 수 있습니다.
임베딩 제공자가 구성되어 있으면 `memory_search`는 **하이브리드 검색**을 사용합니다. 즉, 벡터 유사도(의미적 유사성)와 키워드 매칭(ID나 코드 심볼 같은 정확한 용어)을 결합합니다. 지원되는 제공자 중 하나의 API 키만 있으면 별도 설정 없이 바로 동작합니다.
<Info>
OpenClaw는 사용 가능한 API 키를 바탕으로 임베딩 제공자를 자동 감지합니다. OpenAI, Gemini, Voyage 또는 Mistral 키가 구성되어 있으면 메모리 검색이 자동으로 활성화됩니다.
OpenClaw는 사용 가능한 API 키를 바탕으로 임베딩 제공자를 자동 감지합니다. OpenAI, Gemini, Voyage, 또는 Mistral 키가 구성되어 있으면 메모리 검색이 자동으로 활성화됩니다.
</Info>
검색 작동 방식, 튜닝 옵션, 제공자 설정에 대한 자세한 내용은 [Memory Search](/ko/concepts/memory-search)를 참조하세요.
검색 동작 방식, 튜닝 옵션, 제공자 설정에 대한 자세한 내용은 [Memory Search](/ko/concepts/memory-search)를 참조하세요.
## 메모리 백엔드
<CardGroup cols={3}>
<Card title="내장형 (기본값)" icon="database" href="/ko/concepts/memory-builtin">
SQLite 기반입니다. 키워드 검색, 벡터 유사도, 하이브리드 검색을 즉시 사용할 수 있습니다. 추가 의존성이 필요 없습니다.
<Card title="내장(기본값)" icon="database" href="/ko/concepts/memory-builtin">
SQLite 기반입니다. 키워드 검색, 벡터 유사도, 하이브리드 검색을 즉시 사용할 수 있습니다. 추가 의존성이 필요하지 않습니다.
</Card>
<Card title="QMD" icon="search" href="/ko/concepts/memory-qmd">
재순위 지정, 쿼리 확장, 워크스페이스 외부 디렉터리 인덱싱 기능을 갖춘 로컬 우선 사이드카입니다.
재순위화, 쿼리 확장, 워크스페이스 외부 디렉터리 인덱싱 기능을 제공하는 local-first 사이드카입니다.
</Card>
<Card title="Honcho" icon="brain" href="/ko/concepts/memory-honcho">
사용자 모델링, 시맨틱 검색, 멀티 에이전트 인식을 갖춘 AI 네이티브 크로스세션 메모리입니다. 플러그인을 설치해야 합니다.
사용자 모델링, 시맨틱 검색, 멀티 에이전트 인식을 지원하는 AI 네이티브 크로스 세션 메모리입니다. Plugin 설치가 필요합니다.
</Card>
</CardGroup>
## 지식 위키 계층
## 지식 wiki 계층
<CardGroup cols={1}>
<Card title="Memory Wiki" icon="book" href="/ko/plugins/memory-wiki">
지속 메모리를 주장, 대시보드, 브리지 모드, Obsidian 친화적 워크플로를 갖춘 출처 풍부한 위키 볼트로 컴파일합니다.
지속 메모리를 주장, 대시보드, 브리지 모드, Obsidian 친화적 워크플로를 갖춘 출처가 풍부한 wiki vault로 컴파일합니다.
</Card>
</CardGroup>
## 자동 메모리 플러시
[compaction](/ko/concepts/compaction)이 대화를 요약하기 전에, OpenClaw는 에이전트에게 중요한 컨텍스트를 메모리 파일에 저장하라고 상기시키는 조용한 턴을 실행합니다. 이 기능은 기본적으로 켜져 있으므로 별도로 설정할 필요가 없습니다.
[Compaction](/ko/concepts/compaction)이 대화를 요약하기 전에, OpenClaw는 에이전트에게 중요한 컨텍스트를 메모리 파일에 저장하라고 상기시키는 조용한 턴을 실행합니다. 이것은 기본적으로 활성화되어 있으므로 별도 설정이 필요하지 않습니다.
<Tip>
메모리 플러시는 compaction 중 컨텍스트 손실을 방지합니다. 대화에 중요한 사실이 아직 파일에 기록되지 않았다면, 요약이 이루어지기 전에 자동으로 저장됩니다.
메모리 플러시는 Compaction 중 컨텍스트 손실을 방지합니다. 대화 안에 중요한 사실이 아직 파일에 기록되지 않았다면, 요약이 이루어지기 전에 자동으로 저장됩니다.
</Tip>
## Dreaming (실험적)
## Dreaming
Dreaming은 메모리를 위한 선택적 백그라운드 통합 패스입니다. 단기 신호를 수집하고, 후보를 점수화하며, 자격을 충족한 항목만 장기 메모리(`MEMORY.md`)로 승격합니다.
Dreaming은 메모리를 위한 선택적 백그라운드 통합 패스입니다. 단기 신호를 수집하고, 후보를 점수화하며, 조건을 충족하는 항목만 장기 메모리(`MEMORY.md`)로 승격합니다.
이 기능은 장기 메모리의 신호 대 잡음비를 높게 유지하도록 설계되었습니다.
장기 메모리의 신호 대 잡음비를 높게 유지하도록 설계되었습니다:
- **Opt-in**: 기본적으로 비활성화되어 있습니다.
- **예약 실행**: 활성화되면 `memory-core`가 전체 dreaming sweep을 위한 반복 cron 작업 하나를 자동으로 관리합니다.
- **임곗값 적용**: 승격은 점수, 회상 빈도, 쿼리 다양성 게이트를 통과해야 합니다.
- **선택적 활성화**: 기본적으로 비활성화되어 있습니다.
- **예약 실행**: 활성화되면 `memory-core`가 전체 Dreaming 스윕을 위한 반복 Cron 작업 하나를 자동 관리합니다.
- **임계값 기반**: 승격은 점수, 회상 빈도, 쿼리 다양성 게이트를 통과해야 합니다.
- **검토 가능**: 단계 요약과 다이어리 항목이 사람이 검토할 수 있도록 `DREAMS.md`에 기록됩니다.
단계별 동작, 점수 신호, Dream Diary 세부 정보는 [Dreaming (experimental)](/ko/concepts/dreaming)을 참조하세요.
단계별 동작, 점수화 신호, Dream Diary 세부 정보는 [Dreaming](/ko/concepts/dreaming)을 참조하세요.
## 근거 기반 백필과 라이브 승격
## 근거 기반 소급과 실시간 승격
dreaming 시스템에는 이제 밀접하게 연관된 두 가지 검토 경로가 있습니다.
이제 Dreaming 시스템에는 밀접하게 연결된 두 가지 검토 경로가 있습니다:
- **라이브 dreaming**은 `memory/.dreams/` 아래의 단기 dreaming 저장소를 기반으로 작동하며, 일반적인 딥 단계가 무엇을 `MEMORY.md`로 승격할 수 있는지 결정할 때 사용하는 방식입니다.
- **근거 기반 백필**은 과거의 `memory/YYYY-MM-DD.md` 노트를 독립적인 일일 파일로 읽고, 구조화된 검토 출력을 `DREAMS.md`에 기록합니다.
- **실시간 Dreaming**은 `memory/.dreams/` 아래의 단기 Dreaming 저장소를 기반으로 작동하며, 어떤 항목이 `MEMORY.md`로 승급할 수 있는지 판단할 때 일반적인 심화 단계에서 사용됩니다.
- **근거 기반 소급**은 과거의 `memory/YYYY-MM-DD.md` 노트를 독립적인 일별 파일로 읽고, 구조화된 검토 결과를 `DREAMS.md`에 기록합니다.
근거 기반 백필은 `MEMORY.md`를 수동으로 편집하지 않고도 오래된 노트를 다시 처리하고 시스템이 무엇을 지속적인 정보로 판단하는지 확인하고 싶을 때 유용합니다.
근거 기반 소급은 오래된 노트를 다시 재생하면서 시스템이 무엇을 지속 가능한 정보로 판단하는지 `MEMORY.md`를 직접 편집하지 않고 확인하고 싶을 때 유용합니다.
다음 명령을 사용하면:
다음을 실행하면:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
근거 기반의 지속 후보는 직접 승격되지 않습니다. 대신 일반적인 딥 단계가 이미 사용하는 것과 동일한 단기 dreaming 저장소에 스테이징됩니다. 즉, 다음을 의미합니다.
근거 기반의 지속 후보는 직접 승격되지 않습니다. 대신 일반적인 심화 단계가 이미 사용하는 동일한 단기 Dreaming 저장소에 스테이징됩니다. 즉:
- `DREAMS.md`는 계속 사람 검토용 표면으로 남습니다.
- 단기 저장소는 계속 머신 대상 순위화 표면으로 남습니다.
- `MEMORY.md`는 여전히 딥 승격에 의해서만 기록됩니다.
- `DREAMS.md`는 사람이 검토하는 표면으로 유지됩니다.
- 단기 저장소는 기계가 사용하는 순위화 표면으로 유지됩니다.
- `MEMORY.md`는 여전히 심화 승격에 의해서만 기록됩니다.
재처리가 유용하지 않았다고 판단되면, 일반 다이어리 항목이나 정상적인 회상 상태를 건드리지 않고 스테이징된 아티팩트를 제거할 수 있습니다.
재생이 유용하지 않았다고 판단되면, 일반적인 다이어리 항목이나 정상적인 회상 상태를 건드리지 않고 스테이징된 아티팩트를 제거할 수 있습니다:
```bash
openclaw memory rem-backfill --rollback
@ -149,10 +149,10 @@ openclaw memory index --force # 인덱스 다시 빌드
## 추가 읽을거리
- [Builtin Memory Engine](/ko/concepts/memory-builtin) -- 기본 SQLite 백엔드
- [QMD Memory Engine](/ko/concepts/memory-qmd) -- 고급 로컬 우선 사이드카
- [Honcho Memory](/ko/concepts/memory-honcho) -- AI 네이티브 크로스세션 메모리
- [Memory Wiki](/ko/plugins/memory-wiki) -- 컴파일된 지식 볼트 및 위키 네이티브 도구
- [Memory Search](/ko/concepts/memory-search) -- 검색 파이프라인, 제공자 및 튜닝
- [Dreaming (experimental)](/ko/concepts/dreaming) -- 단기 회상에서 장기 메모리로의 백그라운드 승격
- [QMD Memory Engine](/ko/concepts/memory-qmd) -- 고급 local-first 사이드카
- [Honcho Memory](/ko/concepts/memory-honcho) -- AI 네이티브 크로스 세션 메모리
- [Memory Wiki](/ko/plugins/memory-wiki) -- 컴파일된 지식 vault 및 wiki 네이티브 도구
- [Memory Search](/ko/concepts/memory-search) -- 검색 파이프라인, 제공자, 튜닝
- [Dreaming](/ko/concepts/dreaming) -- 단기 회상에서 장기 메모리로의 백그라운드 승격
- [Memory configuration reference](/ko/reference/memory-config) -- 모든 구성 옵션
- [Compaction](/ko/concepts/compaction) -- compaction이 메모리와 상호작용하는 방식
- [Compaction](/ko/concepts/compaction) -- Compaction이 메모리와 상호작용하는 방식

1500
docs/ko/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

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

@ -1,28 +1,28 @@
---
read_when:
- 자체 GPU 서버에서 모델을 제공하려는 경우
- 자체 GPU 머신에서 모델을 제공하려는 경우
- LM Studio 또는 OpenAI 호환 프록시를 연결하는 경우
- 가장 안전한 로컬 모델 가이드가 필요한 경우
- 가장 안전한 로컬 모델 지침이 필요한 경우
summary: 로컬 LLM(LM Studio, vLLM, LiteLLM, 사용자 지정 OpenAI 엔드포인트)에서 OpenClaw 실행하기
title: 로컬 모델
x-i18n:
generated_at: "2026-04-15T06:00:32Z"
generated_at: "2026-04-15T14:40:34Z"
model: gpt-5.4
provider: openai
source_hash: 8778cc1c623a356ff3cf306c494c046887f9417a70ec71e659e4a8aae912a780
source_hash: 7a506ff83e4c2870d3878339f646c906584454a156ecd618c360f592cf3b0011
source_path: gateway/local-models.md
workflow: 15
---
# 로컬 모델
로컬에서도 가능하지만, OpenClaw는 큰 컨텍스트와 프롬프트 인젝션에 대한 강한 방어를 전제로 합니다. 소형 카드에서는 컨텍스트가 잘리고 안전성이 약해집니다. 가능하면 높은 사양을 목표로 하세요: **최소 2대의 풀옵션 Mac Studio 또는 이에 준하는 GPU 장비(약 $30k+)**. 단일 **24 GB** GPU는 더 가벼운 프롬프트에서만 작동하며 지연 시간도 더 높습니다. 실행 가능한 범위에서 **가장 크고 / 풀사이즈인 모델 변형**을 사용하세요. 과도하게 양자화된 체크포인트나 “small” 모델은 프롬프트 인젝션 위험을 높입니다([보안](/ko/gateway/security) 참고).
로컬에서도 가능하지만, OpenClaw는 큰 컨텍스트와 프롬프트 인젝션에 대한 강력한 방어를 기대합니다. 소형 카드에서는 컨텍스트가 잘리고 안전성이 약해집니다. 기준은 높게 잡으세요: **최대 사양 Mac Studio 2대 이상 또는 동급 GPU 장비(~$30k+)**. 단일 **24 GB** 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에 대형 모델(예: 풀사이즈 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,15 +62,15 @@ x-i18n:
**설정 체크리스트**
- LM Studio 설치: [https://lmstudio.ai](https://lmstudio.ai)
- LM Studio에서 **사용 가능한 가장 큰 모델 빌드**를 다운로드하고(“small”/과도한 양자화 변형은 피하세요), 서버를 시작한 뒤 `http://127.0.0.1:1234/v1/models`에 해당 모델이 표시되는지 확인하세요.
- LM Studio에서 **사용 가능한 가장 큰 모델 빌드**를 다운로드하고(“small”/강하게 양자화된 변형은 피하세요), 서버를 시작한 뒤, `http://127.0.0.1:1234/v1/models`에 해당 모델이 표시되는지 확인하세요.
- `my-local-model`을 LM Studio에 표시되는 실제 모델 ID로 바꾸세요.
- 모델을 계속 로드한 상태로 유지하세요. 콜드 로드는 시작 지연 시간을 늘립니다.
- 모델이 로드된 상태를 유지하세요. 콜드 로드는 시작 지연을 추가합니다.
- LM Studio 빌드가 다르면 `contextWindow`/`maxTokens`를 조정하세요.
- WhatsApp에서는 최종 텍스트만 전송되도록 Responses API를 유지하세요.
- WhatsApp에서는 최종 텍스트만 전송되도록 Responses API를 사용하세요.
로컬에서 실행하더라도 호스팅 모델 설정은 유지하세요. 폴백을 계속 사용할 수 있도록 `models.mode: "merge"`를 사용하세요.
로컬로 실행하더라도 호스팅 모델은 계속 구성해 두세요. 폴백을 계속 사용할 수 있도록 `models.mode: "merge"`를 사용하세요.
### 하이브리드 설정: 호스팅 모델을 기본으로, 로컬을 폴백으로
### 하이브리드 구성: 호스팅 모델을 기본값으로, 로컬을 폴백으로
```json5
{
@ -111,18 +111,18 @@ x-i18n:
}
```
### 로컬 우선 + 호스팅 안전망
### 로컬 우선, 호스팅 안전망 유지
기본 모델과 폴백 순서를 바꾸면 됩니다. 동일한 providers 블록과 `models.mode: "merge"`를 유지하면 로컬 장비가 내려가 있을 때 Sonnet이나 Opus로 폴백할 수 있습니다.
기본값과 폴백 순서를 서로 바꾸세요. 같은 provider 블록과 `models.mode: "merge"`를 유지하면 로컬 장비가 내려가 있을 때 Sonnet 또는 Opus로 폴백할 수 있습니다.
### 지역별 호스팅 / 데이터 라우팅
- 호스팅된 MiniMax/Kimi/GLM 변형도 OpenRouter에서 지역 고정 엔드포인트(예: 미국 호스팅)로 사용할 수 있습니다. 선택한 관할 구역 안에 트래픽을 유지하려면 해당 지역 변형을 선택하고, Anthropic/OpenAI 폴백을 유지하려면 계속 `models.mode: "merge"`를 사용하세요.
- 로컬 전용 구성이 가장 강력한 개인정보 보호 방식입니다. 공급자 기능이 필요하지만 데이터 흐름도 통제하고 싶다면, 지역별 호스팅 라우팅이 중간 지점이 됩니다.
- 호스팅되는 MiniMax/Kimi/GLM 변형도 OpenRouter에서 지역 고정 엔드포인트(예: 미국 호스팅)로 제공됩니다. 선택한 관할 구역 안에 트래픽을 유지하려면 그곳에서 지역 변형을 선택하고, Anthropic/OpenAI 폴백을 유지하려면 계속 `models.mode: "merge"`를 사용하세요.
- 완전 로컬 전용이 가장 강력한 프라이버시 경로입니다. 지역 고정 호스팅은 provider 기능이 필요하지만 데이터 흐름도 통제하고 싶을 때의 중간 지점입니다.
## 기타 OpenAI 호환 로컬 프록시
vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 Gateway도 OpenAI 스타일 `/v1` 엔드포인트를 노출하면 사용할 수 있습니다. 위 provider 블록을 여러분의 엔드포인트와 모델 ID로 바꾸세요.
vLLM, LiteLLM, OAI-proxy, 또는 사용자 지정 Gateway도 OpenAI 스타일 `/v1` 엔드포인트를 노출하면 사용할 수 있습니다. 위 provider 블록을 해당 엔드포인트와 모델 ID로 바꾸세요.
```json5
{
@ -152,34 +152,24 @@ vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 Gateway도 OpenAI 스타일 `/v
호스팅 모델을 폴백으로 계속 사용할 수 있도록 `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 호환 백엔드에 대한 호환성 참고 사항:
- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 `messages[].content`만 허용합니다. 그런 엔드포인트에서는
`models.providers.<provider>.models[].compat.requiresStringContent: true`를
설정하세요.
- 일부 더 작거나 엄격한 로컬 백엔드는 OpenClaw의 전체 에이전트 런타임 프롬프트 형태에서, 특히 도구 스키마가 포함되면, 불안정하게 동작합니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에서는 작동하지만 일반적인 OpenClaw 에이전트 턴에서는 실패한다면, 먼저
`agents.defaults.localModelMode: "lean"`을 시도해 `browser`, `cron`, `message` 같은
무거운 기본 도구를 제외하세요. 그래도 실패하면
`models.providers.<provider>.models[].compat.supportsTools: false`를 시도하세요.
- 더 큰 OpenClaw 실행에서만 백엔드가 계속 실패한다면, 남은 문제는 보통 OpenClaw의 전송 계층이 아니라 업스트림 모델/서버의 용량 한계 또는 백엔드 버그입니다.
- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 `messages[].content`만 허용합니다. 이런 엔드포인트에는 `models.providers.<provider>.models[].compat.requiresStringContent: true`를 설정하세요.
- 일부 더 작거나 더 엄격한 로컬 백엔드는 OpenClaw의 전체 agent-runtime 프롬프트 형태, 특히 도구 스키마가 포함될 때 불안정할 수 있습니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에서는 동작하지만 일반적인 OpenClaw 에이전트 턴에서는 실패한다면, 먼저 `browser`, `cron`, `message` 같은 무거운 기본 도구를 제거하는 `agents.defaults.experimental.localModelLean: true`를 시도하세요. 이것은 실험적 플래그이며, 안정적인 기본 모드 설정이 아닙니다. 자세한 내용은 [실험적 기능](/ko/concepts/experimental-features)을 참고하세요. 그래도 실패하면 `models.providers.<provider>.models[].compat.supportsTools: false`를 시도하세요.
- 더 큰 OpenClaw 실행에서만 백엔드가 계속 실패한다면, 남아 있는 문제는 보통 OpenClaw의 전송 계층이 아니라 업스트림 모델/서버 용량 또는 백엔드 버그입니다.
## 문제 해결
- Gateway가 프록시에 도달할 수 있나요? `curl http://127.0.0.1:1234/v1/models`.
- LM Studio 모델이 언로드되었나요? 다시 로드하세요. 콜드 스타트는 “멈춘 것처럼 보이는” 일반적인 원인입니다.
- OpenClaw는 감지된 컨텍스트 윈도우가 **32k** 미만이면 경고하고, **16k** 미만이면 차단합니다. 이 사전 점검에 걸리면 서버/모델 컨텍스트 한도를 높이거나 더 큰 모델을 선택하세요.
- LM Studio 모델이 언로드되었나요? 다시 로드하세요. 콜드 스타트는 흔한 “멈춤” 원인입니다.
- 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을 켜 두세요.
- OpenAI 호환 서버가 `messages[].content ... expected a string`을 반환하나요? 해당 모델 항목에 `compat.requiresStringContent: true`를 추가하세요.
- 직접적인 작은 `/v1/chat/completions` 호출은 동작하지만 `openclaw infer model run`이 Gemma 또는 다른 로컬 모델에서 실패하나요? 먼저 `compat.supportsTools: false`로 도구 스키마를 비활성화한 뒤 다시 테스트하세요. 서버가 더 큰 OpenClaw 프롬프트에서만 계속 충돌한다면, 업스트림 서버/모델 한계로 간주하세요.
- 안전성: 로컬 모델은 provider 측 필터를 건너뛰므로 프롬프트 인젝션의 영향 범위를 줄이기 위해 에이전트 범위를 좁게 유지하고 Compaction을 켜 두세요.

952
docs/ko/help/testing.md
View File

File diff suppressed because it is too large Load Diff

110
docs/ko/providers/github-copilot.md
View File

@ -1,30 +1,27 @@
---
read_when:
- 모델 프로바이더로 GitHub Copilot를 사용하려고 합니다
- 모델 제공자로 GitHub Copilot을 사용하려고 합니다
- '`openclaw models auth login-github-copilot` 흐름이 필요합니다'
summary: 디바이스 흐름을 사용해 OpenClaw에서 GitHub Copilot에 로그인하기
summary: 디바이스 플로우를 사용해 OpenClaw에서 GitHub Copilot에 로그인합니다
title: GitHub Copilot
x-i18n:
generated_at: "2026-04-12T23:30:47Z"
generated_at: "2026-04-15T14:40:33Z"
model: gpt-5.4
provider: openai
source_hash: 51fee006e7d4e78e37b0c29356b0090b132de727d99b603441767d3fb642140b
source_hash: b8258fecff22fb73b057de878462941f6eb86d0c5f775c5eac4840e95ba5eccf
source_path: providers/github-copilot.md
workflow: 15
---
# GitHub Copilot
GitHub Copilot는 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요금제에 맞는 Copilot
모델에 접근할 수 있도록 해줍니다. OpenClaw는 Copilot을 모델
프로바이더로 두 가지 방식으로 사용할 수 있습니다.
GitHub Copilot은 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요금제에 맞는 Copilot 모델에 액세스할 수 있습니다. OpenClaw는 Copilot을 모델 제공자로 두 가지 방식으로 사용할 수 있습니다.
## OpenClaw에서 Copilot을 사용하는 두 가지 방법
<Tabs>
<Tab title="내장 프로바이더 (github-copilot)">
네이티브 디바이스 로그인 흐름을 사용해 GitHub 토큰을 얻은 다음, OpenClaw가 실행될 때 이를
Copilot API 토큰으로 교환합니다. VS Code가 필요하지 않기 때문에 이것이 **기본값**이자 가장 간단한 경로입니다.
<Tab title="내장 제공자 (github-copilot)">
OpenClaw가 실행될 때 GitHub 토큰을 얻기 위해 기본 디바이스 로그인 흐름을 사용한 다음, 이를 Copilot API 토큰으로 교환합니다. VS Code가 필요하지 않기 때문에 이것이 **기본값**이자 가장 간단한 방법입니다.
<Steps>
<Step title="로그인 명령 실행">
@ -32,15 +29,14 @@ GitHub Copilot는 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요
openclaw models auth login-github-copilot
```
URL에 방문해 일회용 코드를 입력하라는 메시지가 표시됩니다. 완료될 때까지
터미널을 열어 두세요.
URL로 이동하여 일회용 코드를 입력하라는 안내가 표시됩니다. 완료될 때까지 터미널을 열어 두세요.
</Step>
<Step title="기본 모델 설정">
```bash
openclaw models set github-copilot/gpt-4o
```
또는 구성에서:
또는 config에서:
```json5
{
@ -53,12 +49,10 @@ GitHub Copilot는 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요
</Tab>
<Tab title="Copilot Proxy Plugin (copilot-proxy)">
**Copilot Proxy** VS Code 확장을 로컬 브리지로 사용합니다. OpenClaw는
프록시의 `/v1` 엔드포인트와 통신하고, 그곳에서 구성한 모델 목록을 사용합니다.
로컬 브리지로 **Copilot Proxy** VS Code 확장을 사용합니다. OpenClaw는 프록시의 `/v1` 엔드포인트와 통신하고, 그곳에서 구성한 모델 목록을 사용합니다.
<Note>
이미 VS Code에서 Copilot Proxy를 실행 중이거나
이를 통해 라우팅해야 하는 경우 이 옵션을 선택하세요. Plugin을 활성화하고 VS Code 확장을 계속 실행 상태로 유지해야 합니다.
이미 VS Code에서 Copilot Proxy를 실행 중이거나 이를 통해 라우팅해야 할 때 이 방법을 선택하세요. Plugin을 활성화하고 VS Code 확장이 계속 실행 중이어야 합니다.
</Note>
</Tab>
@ -66,69 +60,95 @@ GitHub Copilot는 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요
## 선택적 플래그
| 플래그 | 설명 |
| Flag | 설명 |
| --------------- | --------------------------------------------------- |
| `--yes` | 확인 프롬프트 건너뛰기 |
| `--set-default` | 프로바이더의 권장 기본 모델도 함께 적용 |
| `--yes` | 확인 프롬프트 건너뛰기 |
| `--set-default` | 제공자가 권장하는 기본 모델도 함께 적용 |
```bash
# 확인 건너뛰기
openclaw models auth login-github-copilot --yes
# 로그인하고 한 번에 기본 모델 설정
# 한 번에 로그인하고 기본 모델 설정
openclaw models auth login --provider github-copilot --method device --set-default
```
<AccordionGroup>
<Accordion title="대화형 TTY 필요">
디바이스 로그인 흐름에는 대화형 TTY가 필요합니다. 비대화형 스크립트나 CI 파이프라인이 아니라
터미널에서 직접 실행하세요.
디바이스 로그인 흐름에는 대화형 TTY가 필요합니다. 비대화형 스크립트나 CI 파이프라인이 아니라, 터미널에서 직접 실행하세요.
</Accordion>
<Accordion title="모델 사용 가능 여부는 요금제에 따라 달라집니다">
Copilot 모델 사용 가능 여부는 GitHub 요금제에 따라 다릅니다. 어떤 모델이
거부되면 다른 ID를 시도해 보세요(예: `github-copilot/gpt-4.1`).
Copilot 모델 사용 가능 여부는 GitHub 요금제에 따라 달라집니다. 모델이 거부되면 다른 ID(예: `github-copilot/gpt-4.1`)를 시도해 보세요.
</Accordion>
<Accordion title="전송 선택">
Claude 모델 ID는 자동으로 Anthropic Messages 전송을 사용합니다. GPT,
o-series, Gemini 모델은 OpenAI Responses 전송을 유지합니다. OpenClaw는
모델 ref를 기준으로 올바른 전송을 선택합니다.
<Accordion title="전송 방식 선택">
Claude 모델 ID는 자동으로 Anthropic Messages 전송 방식을 사용합니다. GPT, o-series, Gemini 모델은 OpenAI Responses 전송 방식을 유지합니다. OpenClaw는 모델 ref를 기준으로 올바른 전송 방식을 선택합니다.
</Accordion>
<Accordion title="환경 변수 확인 순서">
OpenClaw는 다음 우선순위 순서로 환경 변수에서 Copilot 인증을 확인합니다:
<Accordion title="환경 변수 확인 우선순위">
OpenClaw는 다음 우선순위에 따라 환경 변수에서 Copilot 인증을 확인합니다:
| 우선순위 | 변수 | 참고 |
| -------- | -------------------- | ------------------------------------- |
| 1 | `COPILOT_GITHUB_TOKEN` | 가장 높은 우선순위, Copilot 전용 |
| 2 | `GH_TOKEN` | GitHub CLI 토큰(대체 경로) |
| 3 | `GITHUB_TOKEN` | 표준 GitHub 토큰(가장 낮은 우선순위) |
| Priority | Variable | Notes |
| -------- | --------------------- | -------------------------------- |
| 1 | `COPILOT_GITHUB_TOKEN` | 가장 높은 우선순위, Copilot 전용 |
| 2 | `GH_TOKEN` | GitHub CLI 토큰 (대체 수단) |
| 3 | `GITHUB_TOKEN` | 표준 GitHub 토큰 (가장 낮음) |
여러 변수가 설정되어 있으면 OpenClaw는 가장 우선순위가 높은 변수를 사용합니다.
디바이스 로그인 흐름(`openclaw models auth login-github-copilot`)은
인증 프로필 저장소에 토큰을 저장하며, 모든 환경
변수보다 우선합니다.
인증 프로필 저장소에 토큰을 저장하며 모든 환경 변수보다 우선합니다.
</Accordion>
<Accordion title="토큰 저장">
로그인은 인증 프로필 저장소에 GitHub 토큰을 저장하고, OpenClaw가 실행될 때 이를
Copilot API 토큰으로 교환합니다. 토큰을 수동으로
관리할 필요는 없습니다.
로그인은 GitHub 토큰을 인증 프로필 저장소에 저장하고, OpenClaw가 실행될 때 이를 Copilot API 토큰으로 교환합니다. 토큰을 수동으로 관리할 필요는 없습니다.
</Accordion>
</AccordionGroup>
<Warning>
대화형 TTY가 필요합니다. 로그인 명령은 헤드리스 스크립트나 CI 작업 내부가 아니라
터미널에서 직접 실행하세요.
대화형 TTY가 필요합니다. 로그인 명령은 헤드리스 스크립트나 CI 작업 내부가 아니라 터미널에서 직접 실행하세요.
</Warning>
## 관련 문서
## 메모리 검색 임베딩
GitHub Copilot은 [메모리 검색](/ko/concepts/memory-search)을 위한 임베딩 제공자로도 사용할 수 있습니다. Copilot 구독이 있고 로그인한 상태라면, OpenClaw는 별도의 API 키 없이도 이를 임베딩에 사용할 수 있습니다.
### 자동 감지
`memorySearch.provider`가 `"auto"`(기본값)일 때 GitHub Copilot은 우선순위 15로 시도됩니다. 즉, 로컬 임베딩 다음이면서 OpenAI 및 기타 유료 제공자보다 앞섭니다. GitHub 토큰을 사용할 수 있으면 OpenClaw는 Copilot API에서 사용 가능한 임베딩 모델을 찾아 자동으로 가장 적합한 모델을 선택합니다.
### 명시적 config
```json5
{
agents: {
defaults: {
memorySearch: {
provider: "github-copilot",
// 선택 사항: 자동으로 검색된 모델 재정의
model: "text-embedding-3-small",
},
},
},
}
```
### 작동 방식
1. OpenClaw가 GitHub 토큰을 확인합니다(환경 변수 또는 인증 프로필에서).
2. 이를 수명이 짧은 Copilot API 토큰으로 교환합니다.
3. Copilot `/models` 엔드포인트를 조회하여 사용 가능한 임베딩 모델을 찾습니다.
4. 가장 적합한 모델을 선택합니다(`text-embedding-3-small` 선호).
5. Copilot `/embeddings` 엔드포인트로 임베딩 요청을 보냅니다.
모델 사용 가능 여부는 GitHub 요금제에 따라 달라집니다. 사용할 수 있는 임베딩 모델이 없으면 OpenClaw는 Copilot을 건너뛰고 다음 제공자를 시도합니다.
## 관련 항목
<CardGroup cols={2}>
<Card title="모델 선택" href="/ko/concepts/model-providers" icon="layers">
프로바이더, 모델 ref, 페일오버 동작 선택하기.
제공자, 모델 ref, 장애 조치 동작 선택.
</Card>
<Card title="OAuth 및 인증" href="/ko/gateway/authentication" icon="key">
인증 세부 정보와 자격 증명 재사용 규칙.

196
docs/ko/providers/ollama.md
View File

@ -1,21 +1,21 @@
---
read_when:
- Ollama를 통해 클라우드 또는 로컬 모델로 OpenClaw를 실행하려고 합니다
- Ollama 설정 및 구성 안내가 필요합니다
- Ollama를 통해 클라우드 또는 로컬 모델로 OpenClaw를 실행하고 싶습니다.
- Ollama 설정 및 구성 안내가 필요합니다.
summary: Ollama로 OpenClaw 실행하기(클라우드 및 로컬 모델)
title: Ollama
x-i18n:
generated_at: "2026-04-12T23:31:48Z"
generated_at: "2026-04-15T14:40:45Z"
model: gpt-5.4
provider: openai
source_hash: ec796241b884ca16ec7077df4f3f1910e2850487bb3ea94f8fdb37c77e02b219
source_hash: 098e083e0fc484bddb5270eb630c55d7832039b462d1710372b6afece5cefcdf
source_path: providers/ollama.md
workflow: 15
---
# Ollama
Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있게 해주는 로컬 LLM 런타임입니다. OpenClaw는 Ollama의 네이티브 API(`/api/chat`)와 통합되며, 스트리밍과 도구 호출을 지원하고, `OLLAMA_API_KEY`(또는 인증 프로필)를 사용하면서 명시적인 `models.providers.ollama` 항목을 정의하지 않으면 로컬 Ollama 모델을 자동 검색할 수 있습니다.
OpenClaw는 호스팅된 클라우드 모델과 로컬/자체 호스팅 Ollama 서버를 위해 Ollama의 네이티브 API(`/api/chat`)와 통합됩니다. Ollama는 세 가지 모드로 사용할 수 있습니다: 접근 가능한 Ollama 호스트를 통한 `Cloud + Local`, `https://ollama.com`을 대상으로 하는 `Cloud only`, 또는 접근 가능한 Ollama 호스트를 대상으로 하는 `Local only`.
<Warning>
**원격 Ollama 사용자**: OpenClaw에서 `/v1` OpenAI 호환 URL(`http://host:11434/v1`)을 사용하지 마세요. 이렇게 하면 도구 호출이 깨지고 모델이 원시 도구 JSON을 일반 텍스트로 출력할 수 있습니다. 대신 네이티브 Ollama API URL을 사용하세요: `baseUrl: "http://host:11434"` (`/v1` 없음).
@ -27,7 +27,7 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
<Tabs>
<Tab title="온보딩(권장)">
**가장 적합한 경우:** 자동 모델 검색이 포함된 동작하는 Ollama 설정까지 가장 빠른 경로.
**적합한 경우:** 작동하는 Ollama 클라우드 또는 로컬 설정까지 가장 빠르게 진행하고 싶을 때.
<Steps>
<Step title="온보딩 실행">
@ -35,16 +35,15 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
openclaw onboard
```
provider 목록에서 **Ollama**를 선택하세요.
공급자 목록에서 **Ollama**를 선택하세요.
</Step>
<Step title="모드 선택">
- **클라우드 + 로컬** — 클라우드 호스팅 모델과 로컬 모델을 함께 사용
- **로컬** — 로컬 모델만 사용
**클라우드 + 로컬**을 선택했고 ollama.com에 로그인되어 있지 않다면, 온보딩이 브라우저 로그인 흐름을 엽니다.
- **Cloud + Local** — 로컬 Ollama 호스트와, 그 호스트를 통해 라우팅되는 클라우드 모델
- **Cloud only** — `https://ollama.com`을 통한 호스팅된 Ollama 모델
- **Local only** — 로컬 모델만 사용
</Step>
<Step title="모델 선택">
온보딩은 사용 가능한 모델을 검색하고 기본값을 제안합니다. 선택한 모델을 로컬에서 사용할 수 없으면 자동으로 가져옵니다.
`Cloud only`는 `OLLAMA_API_KEY`를 요청하고 호스팅된 클라우드 기본값을 제안합니다. `Cloud + Local`과 `Local only`는 Ollama base URL을 요청하고, 사용 가능한 모델을 검색하며, 선택한 로컬 모델이 아직 없으면 자동으로 pull합니다. `Cloud + Local`은 해당 Ollama 호스트가 클라우드 액세스를 위해 로그인되어 있는지도 확인합니다.
</Step>
<Step title="모델 사용 가능 여부 확인">
```bash
@ -61,7 +60,7 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
--accept-risk
```
선택적으로 사용자 지정 base URL 또는 모델을 지정할 수 있습니다:
필요하면 사용자 지정 base URL 또는 모델도 지정할 수 있습니다.
```bash
openclaw onboard --non-interactive \
@ -74,37 +73,35 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
</Tab>
<Tab title="수동 설정">
**가장 적합한 경우:** 설치, 모델 pull, 구성에 대한 완전한 제어.
**적합한 경우:** 클라우드 또는 로컬 설정을 완전히 제어하고 싶을 때.
<Steps>
<Step title="Ollama 설치">
[ollama.com/download](https://ollama.com/download)에서 다운로드하세요.
<Step title="클라우드 또는 로컬 선택">
- **Cloud + Local**: Ollama를 설치하고 `ollama signin`으로 로그인한 뒤, 클라우드 요청을 해당 호스트를 통해 라우팅
- **Cloud only**: `OLLAMA_API_KEY`와 함께 `https://ollama.com` 사용
- **Local only**: [ollama.com/download](https://ollama.com/download)에서 Ollama 설치
</Step>
<Step title="로컬 모델 pull">
<Step title="로컬 모델 pull (local only)">
```bash
ollama pull gemma4
# or
# 또는
ollama pull gpt-oss:20b
# or
# 또는
ollama pull llama3.3
```
</Step>
<Step title="클라우드 모델용 로그인(선택 사항)">
클라우드 모델도 사용하려면:
```bash
ollama signin
```
</Step>
<Step title="OpenClaw에서 Ollama 활성화">
API 키에는 아무 값이나 설정해도 됩니다(Ollama는 실제 키를 요구하지 않음):
`Cloud only`에는 실제 `OLLAMA_API_KEY`를 사용하세요. 호스트 기반 설정에서는 아무 자리표시자 값이나 동작합니다.
```bash
# 환경 변수 설정
# Cloud
export OLLAMA_API_KEY="your-ollama-api-key"
# Local-only
export OLLAMA_API_KEY="ollama-local"
# 또는 구성 파일에서 설정
openclaw config set models.providers.ollama.apiKey "ollama-local"
# 또는 config 파일에 설정
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
```
</Step>
<Step title="모델 확인 및 설정">
@ -113,7 +110,7 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
openclaw models set ollama/gemma4
```
또는 구성에서 기본값을 설정:
또는 config에서 기본값을 설정할 수 있습니다.
```json5
{
@ -133,19 +130,24 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
## 클라우드 모델
<Tabs>
<Tab title="클라우드 + 로컬">
클라우드 모델을 사용하면 로컬 모델과 함께 클라우드 호스팅 모델을 실행할 수 있습니다. 예로 `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`가 있으며, 이들은 로컬 `ollama pull`이 **필요하지 않습니다**.
<Tab title="Cloud + Local">
`Cloud + Local`은 로컬 모델과 클라우드 모델 모두에 대해 접근 가능한 Ollama 호스트를 제어 지점으로 사용합니다. 이것은 Ollama가 권장하는 하이브리드 흐름입니다.
설정 중에 **클라우드 + 로컬** 모드를 선택하세요. 마법사는 로그인 여부를 확인하고 필요할 때 브라우저 로그인 흐름을 엽니다. 인증을 확인할 수 없으면 마법사는 로컬 모델 기본값으로 대체합니다.
설정 중에 **Cloud + Local**을 사용하세요. OpenClaw는 Ollama base URL을 요청하고, 해당 호스트에서 로컬 모델을 검색하며, 호스트가 `ollama signin`으로 클라우드 액세스에 로그인되어 있는지 확인합니다. 호스트가 로그인되어 있으면 OpenClaw는 `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud` 같은 호스팅된 클라우드 기본값도 제안합니다.
[ollama.com/signin](https://ollama.com/signin)에서 직접 로그인할 수도 있습니다.
OpenClaw는 현재 다음 클라우드 기본값을 제안합니다: `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`.
호스트가 아직 로그인되어 있지 않으면, `ollama signin`을 실행할 때까지 OpenClaw는 설정을 local-only로 유지합니다.
</Tab>
<Tab title="로컬만">
로컬 전용 모드에서 OpenClaw는 로컬 Ollama 인스턴스에서 모델을 검색합니다. 클라우드 로그인은 필요하지 않습니다.
<Tab title="Cloud only">
`Cloud only`는 `https://ollama.com`의 Ollama 호스팅 API를 대상으로 실행됩니다.
설정 중에 **Cloud only**를 사용하세요. OpenClaw는 `OLLAMA_API_KEY`를 요청하고, `baseUrl: "https://ollama.com"`을 설정하며, 호스팅된 클라우드 모델 목록을 초기화합니다. 이 경로는 로컬 Ollama 서버나 `ollama signin`이 **필요하지 않습니다**.
</Tab>
<Tab title="Local only">
local-only 모드에서 OpenClaw는 구성된 Ollama 인스턴스에서 모델을 검색합니다. 이 경로는 로컬 또는 자체 호스팅 Ollama 서버용입니다.
OpenClaw는 현재 로컬 기본값으로 `gemma4`를 제안합니다.
@ -154,18 +156,18 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있
## 모델 검색(암시적 provider)
`OLLAMA_API_KEY`(또는 인증 프로필)를 설정하고 **`models.providers.ollama`를 정의하지 않으면**, OpenClaw는 `http://127.0.0.1:11434`의 로컬 Ollama 인스턴스에서 모델을 검색합니다.
`OLLAMA_API_KEY`(또는 auth 프로필)를 설정하고 **`models.providers.ollama`를 정의하지 않으면**, OpenClaw는 `http://127.0.0.1:11434`의 로컬 Ollama 인스턴스에서 모델을 검색합니다.
| Behavior | Detail |
| 동작 | 세부 정보 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalog query | `/api/tags` 조회 |
| Capability detection | 최선의 노력 방식의 `/api/show` 조회를 사용해 `contextWindow`를 읽고 기능(vision 포함)을 감지 |
| Vision models | `/api/show`가 `vision` 기능을 보고하는 모델은 이미지 지원 가능(`input: ["text", "image"]`)으로 표시되므로, OpenClaw가 프롬프트에 이미지를 자동 주입함 |
| Reasoning detection | 모델 이름 휴리스틱(`r1`, `reasoning`, `think`)으로 `reasoning` 표시 |
| Token limits | OpenClaw가 사용하는 기본 Ollama 최대 토큰 한도로 `maxTokens` 설정 |
| Costs | 모든 비용을 `0`으로 설정 |
| 카탈로그 쿼리 | `/api/tags` 조회 |
| 기능 감지 | 최선형 `/api/show` 조회를 사용해 `contextWindow`를 읽고 기능(vision 포함)을 감지 |
| 비전 모델 | `/api/show`에서 `vision` 기능이 보고된 모델은 이미지 지원 모델(`input: ["text", "image"]`)로 표시되므로, OpenClaw가 프롬프트에 이미지를 자동 주입함 |
| 추론 감지 | 모델 이름 휴리스틱(`r1`, `reasoning`, `think`)으로 `reasoning` 표시 |
| 토큰 제한 | OpenClaw가 사용하는 기본 Ollama 최대 토큰 한도로 `maxTokens` 설정 |
| 비용 | 모든 비용을 `0`으로 설정 |
이렇게 하면 카탈로그를 로컬 Ollama 인스턴스와 일치시킨 상태로 유지하면서 수동 모델 항목 정의를 피할 수 있습니다.
이렇게 하면 수동 모델 항목 없이도 로컬 Ollama 인스턴스와 정렬된 카탈로그를 유지할 수 있습니다.
```bash
# 사용 가능한 모델 확인
@ -173,7 +175,7 @@ ollama list
openclaw models list
```
새 모델을 추가하려면 Ollama로 pull만 하면 됩니다:
새 모델을 추가하려면 Ollama로 간단히 pull하면 됩니다.
```bash
ollama pull mistral
@ -182,45 +184,45 @@ ollama pull mistral
새 모델은 자동으로 검색되어 바로 사용할 수 있습니다.
<Note>
`models.providers.ollama`를 명시적으로 설정하면 자동 검색은 건너뛰며, 모델을 수동으로 정의해야 합니다. 아래의 명시적 구성 섹션을 참조하세요.
`models.providers.ollama`를 명시적으로 설정하면 자동 검색은 건너뛰며, 모델을 수동으로 정의해야 합니다. 아래의 명시적 config 섹션을 참고하세요.
</Note>
## 구성
<Tabs>
<Tab title="기본(암시적 검색)">
Ollama를 활성화하는 가장 간단한 방법은 환경 변수를 사용하는 것입니다:
가장 간단한 local-only 활성화 경로는 환경 변수를 사용하는 것입니다.
```bash
export OLLAMA_API_KEY="ollama-local"
```
<Tip>
`OLLAMA_API_KEY`가 설정되어 있으면 provider 항목에서 `apiKey`를 생략할 수 있으며, OpenClaw가 사용 가능 여부 확인을 위해 이를 채워 넣습니다.
`OLLAMA_API_KEY`가 설정되어 있으면 provider 항목에서 `apiKey`를 생략할 수 있으며, OpenClaw가 가용성 확인을 위해 이를 채웁니다.
</Tip>
</Tab>
<Tab title="명시적(수동 모델)">
Ollama가 다른 호스트/포트에서 실행 중이거나, 특정 컨텍스트 윈도우 또는 모델 목록을 강제하고 싶거나, 완전히 수동 모델 정의를 원하는 경우 명시적 구성을 사용하세요.
호스팅된 클라우드 설정이 필요하거나, Ollama가 다른 호스트/포트에서 실행되거나, 특정 컨텍스트 윈도우 또는 모델 목록을 강제하고 싶거나, 모델 정의를 완전히 수동으로 관리하고 싶다면 명시적 config를 사용하세요.
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434",
apiKey: "ollama-local",
baseUrl: "https://ollama.com",
apiKey: "OLLAMA_API_KEY",
api: "ollama",
models: [
{
id: "gpt-oss:20b",
name: "GPT-OSS 20B",
id: "kimi-k2.5:cloud",
name: "kimi-k2.5:cloud",
reasoning: false,
input: ["text"],
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 8192,
maxTokens: 8192 * 10
contextWindow: 128000,
maxTokens: 8192
}
]
}
@ -232,7 +234,7 @@ ollama pull mistral
</Tab>
<Tab title="사용자 지정 base URL">
Ollama가 다른 호스트나 포트에서 실행 중인 경우(명시적 구성은 자동 검색을 비활성화하므로 모델을 수동 정의해야 함):
Ollama가 다른 호스트나 포트에서 실행 중인 경우(명시적 config는 자동 검색을 비활성화하므로 모델을 수동으로 정의해야 함):
```json5
{
@ -249,7 +251,7 @@ ollama pull mistral
```
<Warning>
URL에 `/v1`을 추가하지 마세요. `/v1` 경로는 OpenAI 호환 모드를 사용하며, 이 모드에서는 도구 호출이 신뢰할 수 없습니다. 경로 접미사 없이 기본 Ollama URL을 사용하세요.
URL에 `/v1`을 추가하지 마세요. `/v1` 경로는 OpenAI 호환 모드를 사용하며, 이 경우 도구 호출이 신뢰할 수 없습니다. 경로 접미사 없이 기본 Ollama URL을 사용하세요.
</Warning>
</Tab>
@ -257,7 +259,7 @@ ollama pull mistral
### 모델 선택
구성이 완료되면 모든 Ollama 모델을 사용할 수 있습니다:
구성이 끝나면 모든 Ollama 모델을 사용할 수 있습니다.
```json5
{
@ -272,17 +274,17 @@ ollama pull mistral
}
```
## Ollama Web Search
## Ollama 웹 검색
OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합니다.
OpenClaw는 번들된 `web_search` provider로 **Ollama 웹 검색**을 지원합니다.
| Property | Detail |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| Host | 구성된 Ollama 호스트 사용(`models.providers.ollama.baseUrl`이 설정된 경우 해당 값, 아니면 `http://127.0.0.1:11434`) |
| Auth | 키 불필요 |
| Requirement | Ollama가 실행 중이어야 하며 `ollama signin`으로 로그인되어 있어야 함 |
| 속성 | 세부 정보 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| 호스트 | 구성된 Ollama 호스트를 사용함(`models.providers.ollama.baseUrl`이 설정된 경우 그 값, 아니면 `http://127.0.0.1:11434`) |
| 인증 | 키 불필요 |
| 요구 사항 | Ollama가 실행 중이어야 하며 `ollama signin`으로 로그인되어 있어야 함 |
`openclaw onboard` 또는 `openclaw configure --section web` 중에 **Ollama Web Search**를 선택하거나 다음과 같이 설정하세요:
`openclaw onboard` 또는 `openclaw configure --section web` 중에 **Ollama 웹 검색**을 선택하거나, 다음과 같이 설정하세요.
```json5
{
@ -297,7 +299,7 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
```
<Note>
전체 설정 및 동작 세부 정보는 [Ollama Web Search](/ko/tools/ollama-search)를 참조하세요.
전체 설정 및 동작 세부 정보는 [Ollama 웹 검색](/ko/tools/ollama-search)을 참고하세요.
</Note>
## 고급 구성
@ -305,10 +307,10 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
<AccordionGroup>
<Accordion title="레거시 OpenAI 호환 모드">
<Warning>
**OpenAI 호환 모드에서는 도구 호출이 신뢰할 수 없습니다.** 프록시에 OpenAI 형식이 꼭 필요하고 네이티브 도구 호출 동작에 의존하지 않는 경우에만 이 모드를 사용하세요.
**OpenAI 호환 모드에서는 도구 호출이 신뢰할 수 없습니다.** 프록시 때문에 OpenAI 형식이 꼭 필요한 경우에만 이 모드를 사용하고, 네이티브 도구 호출 동작에 의존하지 마세요.
</Warning>
대신 OpenAI 호환 엔드포인트를 사용해야 하는 경우(예: OpenAI 형식만 지원하는 프록시 뒤에 있는 경우), `api: "openai-completions"`를 명시적으로 설정하세요:
대신 OpenAI 호환 엔드포인트를 사용해야 한다면(예: OpenAI 형식만 지원하는 프록시 뒤에 있는 경우), `api: "openai-completions"`를 명시적으로 설정하세요.
```json5
{
@ -326,9 +328,9 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
}
```
이 모드는 스트리밍과 도구 호출을 동시에 지원하지 못할 수 있습니다. 모델 구성에서 `params: { streaming: false }`로 스트리밍을 비활성화해야 할 수 있습니다.
이 모드는 스트리밍과 도구 호출을 동시에 지원하지 않을 수 있습니다. 모델 config에서 `params: { streaming: false }`로 스트리밍을 비활성화해야 할 수 있습니다.
Ollama에서 `api: "openai-completions"`를 사용할 때 OpenClaw는 기본적으로 `options.num_ctx`를 주입하므로, Ollama가 조용히 4096 컨텍스트 윈도우로 대체되지 않습니다. 프록시/업스트림이 알 수 없는 `options` 필드를 거부하는 경우 이 동작을 비활성화하세요:
Ollama와 함께 `api: "openai-completions"`를 사용하면, OpenClaw는 기본적으로 `options.num_ctx`를 주입하여 Ollama가 조용히 4096 컨텍스트 윈도우로 되돌아가지 않도록 합니다. 프록시/업스트림이 알 수 없는 `options` 필드를 거부한다면 이 동작을 비활성화하세요.
```json5
{
@ -351,7 +353,7 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
<Accordion title="컨텍스트 윈도우">
자동 검색된 모델의 경우, OpenClaw는 가능하면 Ollama가 보고한 컨텍스트 윈도우를 사용하고, 그렇지 않으면 OpenClaw가 사용하는 기본 Ollama 컨텍스트 윈도우로 대체합니다.
명시적 provider 구성에서 `contextWindow`와 `maxTokens`를 재정의할 수 있습니다:
명시적 provider config에서 `contextWindow`와 `maxTokens`를 재정의할 수 있습니다.
```json5
{
@ -374,7 +376,7 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
</Accordion>
<Accordion title="추론 모델">
OpenClaw는 기본적으로 `deepseek-r1`, `reasoning`, `think` 같은 이름의 모델을 추론 가능 모델로 처리합니다.
OpenClaw는 기본적으로 `deepseek-r1`, `reasoning`, `think` 같은 이름을 가진 모델을 추론 가능 모델로 취급합니다.
```bash
ollama pull deepseek-r1:32b
@ -385,18 +387,18 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
</Accordion>
<Accordion title="모델 비용">
Ollama는 무료이며 로컬에서 실행되므로 모든 모델 비용은 $0으로 설정됩니다. 이는 자동 검색된 모델과 수동 정의된 모델 모두에 적용됩니다.
Ollama는 무료이며 로컬에서 실행되므로, 모든 모델 비용은 $0으로 설정됩니다. 이는 자동 검색된 모델과 수동으로 정의된 모델 모두에 적용됩니다.
</Accordion>
<Accordion title="메모리 임베딩">
번들 Ollama Plugin은 [메모리 검색](/ko/concepts/memory)을 위한 메모리 임베딩 provider를 등록합니다. 구성된 Ollama base URL과 API 키를 사용합니다.
번들된 Ollama Plugin은 [메모리 검색](/ko/concepts/memory)을 위한 메모리 임베딩 provider를 등록합니다. 구성된 Ollama base URL과 API 키를 사용합니다.
| Property | Value |
| 속성 | 값 |
| ------------- | ------------------- |
| Default model | `nomic-embed-text` |
| Auto-pull | 예 — 로컬에 없으면 임베딩 모델을 자동으로 pull |
| 기본 모델 | `nomic-embed-text` |
| 자동 pull | 예 — 임베딩 모델이 로컬에 없으면 자동으로 pull됨 |
메모리 검색 임베딩 provider로 Ollama를 선택하려면:
메모리 검색 임베딩 provider로 Ollama를 선택하려면 다음과 같이 설정하세요.
```json5
{
@ -411,10 +413,10 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
</Accordion>
<Accordion title="스트리밍 구성">
OpenClaw의 Ollama 통합은 기본적으로 **네이티브 Ollama API**(`/api/chat`)를 사용하며, 이는 스트리밍과 도구 호출을 동시에 완전히 지원합니다. 별도의 특별한 구성은 필요하지 않습니다.
OpenClaw의 Ollama 통합은 기본적으로 **네이티브 Ollama API**(`/api/chat`)를 사용하며, 이 방식은 스트리밍과 도구 호출을 동시에 완전히 지원합니다. 특별한 구성은 필요하지 않습니다.
<Tip>
OpenAI 호환 엔드포인트를 사용해야 하는 경우 위의 "레거시 OpenAI 호환 모드" 섹션을 참조하세요. 그 모드에서는 스트리밍과 도구 호출이 동시에 동작하지 않을 수 있습니다.
OpenAI 호환 엔드포인트를 사용해야 한다면, 위의 "레거시 OpenAI 호환 모드" 섹션을 참고하세요. 해당 모드에서는 스트리밍과 도구 호출이 동시에 동작하지 않을 수 있습니다.
</Tip>
</Accordion>
@ -424,13 +426,13 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
<AccordionGroup>
<Accordion title="Ollama가 감지되지 않음">
Ollama가 실행 중인지, `OLLAMA_API_KEY`(또는 인증 프로필)를 설정했는지, 그리고 명시적인 `models.providers.ollama` 항목을 **정의하지 않았는지** 확인하세요:
Ollama가 실행 중인지, `OLLAMA_API_KEY`(또는 auth 프로필)를 설정했는지, 그리고 명시적인 `models.providers.ollama` 항목을 **정의하지 않았는지** 확인하세요.
```bash
ollama serve
```
API에 접근 가능한지도 확인하세요:
API에 접근할 수 있는지도 확인하세요.
```bash
curl http://localhost:11434/api/tags
@ -438,8 +440,8 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
</Accordion>
<Accordion title="사용 가능한 모델이 없음">
모델이 목록에 없으면 로컬에서 모델을 pull하거나 `models.providers.ollama`에 명시적으로 정의하세요.
<Accordion title="사용 가능한 모델 없음">
모델이 목록에 없으면, 모델을 로컬에서 pull하거나 `models.providers.ollama`에 명시적으로 정의하세요.
```bash
ollama list # 설치된 항목 확인
@ -451,10 +453,10 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
</Accordion>
<Accordion title="연결 거부됨">
Ollama가 올바른 포트에서 실행 중인지 확인하세요:
Ollama가 올바른 포트에서 실행 중인지 확인하세요.
```bash
# Ollama 실행 여부 확인
# Ollama가 실행 중인지 확인
ps aux | grep ollama
# 또는 Ollama 재시작
@ -468,19 +470,19 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합
추가 도움말: [문제 해결](/ko/help/troubleshooting) 및 [FAQ](/ko/help/faq).
</Note>
## 관련
## 관련 항목
<CardGroup cols={2}>
<Card title="모델 provider" href="/ko/concepts/model-providers" icon="layers">
모든 provider, 모델 참조 및 장애 조치 동작 개요.
모든 provider, 모델 ref, 장애 조치 동작 개요.
</Card>
<Card title="모델 선택" href="/ko/concepts/models" icon="brain">
모델 선택 및 구성 방법.
모델을 선택하고 구성하는 방법.
</Card>
<Card title="Ollama Web Search" href="/ko/tools/ollama-search" icon="magnifying-glass">
<Card title="Ollama 웹 검색" href="/ko/tools/ollama-search" icon="magnifying-glass">
Ollama 기반 웹 검색의 전체 설정 및 동작 세부 정보.
</Card>
<Card title="구성" href="/ko/gateway/configuration" icon="gear">
전체 구성 참조.
전체 config 참조.
</Card>
</CardGroup>

345
docs/ko/reference/memory-config.md
View File

@ -1,96 +1,93 @@
---
read_when:
- 메모리 검색 provider 또는 임베딩 모델을 구성하려고 합니다
- QMD 백엔드를 설정하려고 합니다
- 하이브리드 검색, MMR 또는 시간 감쇠를 조정하려고 합니다
- 멀티모달 메모리 인덱싱을 활성화하려고 합니다
summary: 메모리 검색, 임베딩 provider, QMD, 하이브리드 검색, 멀티모달 인덱싱을 위한 모든 구성 옵션
- 메모리 검색 제공자나 임베딩 모델을 구성하고 싶습니다.
- QMD 백엔드를 설정하고 싶습니다.
- 하이브리드 검색, MMR 또는 시간 감쇠를 조정하고 싶습니다.
- 멀티모달 메모리 인덱싱을 활성화하고 싶습니다.
summary: 메모리 검색, 임베딩 제공자, QMD, 하이브리드 검색, 멀티모달 인덱싱을 위한 모든 구성 옵션
title: 메모리 구성 참조
x-i18n:
generated_at: "2026-04-12T23:33:47Z"
generated_at: "2026-04-15T14:40:54Z"
model: gpt-5.4
provider: openai
source_hash: 299ca9b69eea292ea557a2841232c637f5c1daf2bc0f73c0a42f7c0d8d566ce2
source_hash: 334c3c4dac08e864487047d3822c75f96e9e7a97c38be4b4e0cd9e63c4489a53
source_path: reference/memory-config.md
workflow: 15
---
# 메모리 구성 참조
이 페이지는 OpenClaw 메모리 검색의 모든 구성 옵션을 나열합니다. 개념적 개요는 다음을 참조하세요:
이 페이지에는 OpenClaw 메모리 검색의 모든 구성 옵션이 정리되어 있습니다. 개념적 개요는 다음 문서를 참고하세요.
- [메모리 개요](/ko/concepts/memory) -- 메모리 작동 방식
- [Builtin 엔진](/ko/concepts/memory-builtin) -- 기본 SQLite 백엔드
- [메모리 개요](/ko/concepts/memory) -- 메모리의 작동 방식
- [내장 엔진](/ko/concepts/memory-builtin) -- 기본 SQLite 백엔드
- [QMD 엔진](/ko/concepts/memory-qmd) -- 로컬 우선 사이드카
- [메모리 검색](/ko/concepts/memory-search) -- 검색 파이프라인 및 조정
- [Active Memory](/ko/concepts/active-memory) -- 대화형 세션용 메모리 하위 agent 활성화
- [메모리 검색](/ko/concepts/memory-search) -- 검색 파이프라인 및 튜닝
- [Active Memory](/ko/concepts/active-memory) -- 대화형 세션에서 메모리 서브에이전트 활성화
별도 명시가 없는 한, 모든 메모리 검색 설정은
`openclaw.json`의 `agents.defaults.memorySearch` 아래에 있습니다.
별도 표기가 없는 한 모든 메모리 검색 설정은 `openclaw.json`의 `agents.defaults.memorySearch` 아래에 있습니다.
**Active Memory** 기능 토글과 하위 agent 구성을 찾고 있다면,
그 설정은 `memorySearch`가 아니라 `plugins.entries.active-memory` 아래에 있습니다.
**Active Memory** 기능 토글과 서브에이전트 구성을 찾고 있다면, 그것은 `memorySearch`가 아니라 `plugins.entries.active-memory` 아래에 있습니다.
Active Memory는 2단계 게이트 모델을 사용합니다:
Active Memory는 두 단계 게이트 모델을 사용합니다.
1. Plugin이 활성화되어 있어야 하고 현재 agent ID를 대상으로 해야 합니다
2. 요청이 적격한 대화형 영속 채팅 세션이어야 합니다
1. Plugin이 활성화되어 있어야 하고 현재 에이전트 ID를 대상으로 해야 합니다.
2. 요청이 적격한 대화형 영구 채팅 세션이어야 합니다.
활성화 모델, Plugin 소유 구성, transcript 영속성, 안전한 롤아웃 패턴은
[Active Memory](/ko/concepts/active-memory)를 참조하세요.
활성화 모델, Plugin 소유 구성, 대화 기록 영속성, 안전한 롤아웃 패턴은 [Active Memory](/ko/concepts/active-memory)를 참고하세요.
---
## Provider 선택
## 제공자 선택
| Key | Type | Default | Description |
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------- |
| `provider` | `string` | 자동 감지 | 임베딩 adapter ID: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
| `model` | `string` | provider 기본값 | 임베딩 모델 이름 |
| `fallback` | `string` | `"none"` | 기본 provider 실패 시 사용할 대체 adapter ID |
| `enabled` | `boolean` | `true` | 메모리 검색 활성화 또는 비활성화 |
| 키 | 타입 | 기본값 | 설명 |
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | 자동 감지 | 임베딩 어댑터 ID: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` |
| `model` | `string` | 제공자 기본값 | 임베딩 모델 이름 |
| `fallback` | `string` | `"none"` | 기본 제공자 실패 시 사용할 대체 어댑터 ID |
| `enabled` | `boolean` | `true` | 메모리 검색 활성화 또는 비활성화 |
### 자동 감지 순서
`provider`가 설정되지 않으면 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다:
`provider`를 설정하지 않으면 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다.
1. `local` -- `memorySearch.local.modelPath`가 구성되어 있고 파일이 존재하는 경우.
2. `openai` -- OpenAI 키를 확인할 수 있는 경우.
3. `gemini` -- Gemini 키를 확인할 수 있는 경우.
4. `voyage` -- Voyage 키를 확인할 수 있는 경우.
5. `mistral` -- Mistral 키를 확인할 수 있는 경우.
6. `bedrock` -- AWS SDK 자격 증명 체인이 확인되는 경우(인스턴스 역할, 액세스 키, 프로필, SSO, web identity 또는 공유 구성).
1. `local` -- `memorySearch.local.modelPath`가 구성되어 있고 파일이 존재하는 경우
2. `github-copilot` -- GitHub Copilot 토큰을 확인할 수 있는 경우(환경 변수 또는 인증 프로필)
3. `openai` -- OpenAI 키를 확인할 수 있는 경우
4. `gemini` -- Gemini 키를 확인할 수 있는 경우
5. `voyage` -- Voyage 키를 확인할 수 있는 경우
6. `mistral` -- Mistral 키를 확인할 수 있는 경우
7. `bedrock` -- AWS SDK 자격 증명 체인이 확인되는 경우(인스턴스 역할, 액세스 키, 프로필, SSO, 웹 아이덴티티 또는 공유 구성)
`ollama`는 지원되지만 자동 감지는 되지 않습니다(명시적으로 설정해야 함).
`ollama`는 지원되지만 자동 감지되지는 않습니다(명시적으로 설정해야 함).
### API 키 확인
원격 임베딩에는 API 키가 필요합니다. 대신 Bedrock은 AWS SDK 기본
자격 증명 체인(인스턴스 역할, SSO, 액세스 키)을 사용합니다.
원격 임베딩에는 API 키가 필요합니다. 대신 Bedrock은 AWS SDK 기본 자격 증명 체인(인스턴스 역할, SSO, 액세스 키)을 사용합니다.
| Provider | Env var | Config key |
| -------- | ------------------------------ | --------------------------------- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Bedrock | AWS 자격 증명 체인 | API 키 불필요 |
| Ollama | `OLLAMA_API_KEY` (자리표시자) | -- |
| 제공자 | 환경 변수 | 구성 키 |
| -------------- | -------------------------------------------------- | --------------------------------- |
| Bedrock | AWS 자격 증명 체인 | API 키 필요 없음 |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | 장치 로그인 기반 인증 프로필 |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY` (자리표시자) | -- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
Codex OAuth는 채팅/completions만 지원하며 임베딩
요청에는 사용할 수 없습니다.
Codex OAuth는 채팅/완성만 지원하며 임베딩 요청에는 사용할 수 없습니다.
---
## 원격 엔드포인트 구성
사용자 지정 OpenAI 호환 엔드포인트 또는 provider 기본값 재정의용:
사용자 지정 OpenAI 호환 엔드포인트를 사용하거나 제공자 기본값을 재정의하려면 다음을 사용하세요.
| Key | Type | Description |
| 키 | 타입 | 설명 |
| ---------------- | -------- | -------------------------------------------------- |
| `remote.baseUrl` | `string` | 사용자 지정 API base URL |
| `remote.apiKey` | `string` | API 키 재정의 |
| `remote.headers` | `object` | 추가 HTTP 헤더(provider 기본값과 병합됨) |
| `remote.baseUrl` | `string` | 사용자 지정 API 기본 URL |
| `remote.apiKey` | `string` | API 키 재정의 |
| `remote.headers` | `object` | 추가 HTTP 헤더(제공자 기본값과 병합됨) |
```json5
{
@ -113,13 +110,13 @@ Codex OAuth는 채팅/completions만 지원하며 임베딩
## Gemini 전용 구성
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
| `model` | `string` | `gemini-embedding-001` | `gemini-embedding-2-preview`도 지원 |
| `outputDimensionality` | `number` | `3072` | Embedding 2의 경우: 768, 1536 또는 3072 |
| `model` | `string` | `gemini-embedding-001` | `gemini-embedding-2-preview`도 지원 |
| `outputDimensionality` | `number` | `3072` | Embedding 2의 경우: 768, 1536 또는 3072 |
<Warning>
`model` 또는 `outputDimensionality`를 변경하면 자동으로 전체 재인덱싱이 수행됩니다.
모델 또는 `outputDimensionality`를 변경하면 전체 재인덱싱이 자동으로 수행됩니다.
</Warning>
---
@ -127,8 +124,7 @@ Codex OAuth는 채팅/completions만 지원하며 임베딩
## Bedrock 임베딩 구성
Bedrock은 AWS SDK 기본 자격 증명 체인을 사용하므로 API 키가 필요 없습니다.
OpenClaw가 Bedrock이 활성화된 인스턴스 역할이 있는 EC2에서 실행 중이라면,
provider와 model만 설정하면 됩니다:
OpenClaw가 Bedrock이 활성화된 인스턴스 역할로 EC2에서 실행되는 경우, 제공자와 모델만 설정하면 됩니다.
```json5
{
@ -143,17 +139,16 @@ provider와 model만 설정하면 됩니다:
}
```
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ---------------------- | -------- | ------------------------------ | ------------------------------- |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 모든 Bedrock 임베딩 모델 ID |
| `outputDimensionality` | `number` | 모델 기본값 | Titan V2의 경우: 256, 512 또는 1024 |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 모든 Bedrock 임베딩 모델 ID |
| `outputDimensionality` | `number` | 모델 기본값 | Titan V2의 경우: 256, 512 또는 1024 |
### 지원 모델
### 지원되는 모델
다음 모델이 지원됩니다(패밀리 감지 및 차원
기본값 포함):
다음 모델이 지원됩니다(패밀리 감지 및 기본 차원값 포함).
| Model ID | Provider | Default Dims | Configurable Dims |
| 모델 ID | 제공자 | 기본 차원 | 설정 가능한 차원 |
| ------------------------------------------ | ---------- | ------------ | -------------------- |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
@ -166,25 +161,23 @@ provider와 model만 설정하면 됩니다:
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
처리량 접미사가 붙은 변형(예: `amazon.titan-embed-text-v1:2:8k`)은
기본 모델의 구성을 상속합니다.
처리량 접미사가 붙은 변형(예: `amazon.titan-embed-text-v1:2:8k`)은 기본 모델의 구성을 상속합니다.
### 인증
Bedrock 인증은 표준 AWS SDK 자격 증명 확인 순서를 사용합니다:
Bedrock 인증은 표준 AWS SDK 자격 증명 확인 순서를 사용합니다.
1. 환경 변수(`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
2. SSO 토큰 캐시
3. Web identity 토큰 자격 증명
3. 웹 아이덴티티 토큰 자격 증명
4. 공유 자격 증명 및 구성 파일
5. ECS 또는 EC2 메타데이터 자격 증명
리전은 `AWS_REGION`, `AWS_DEFAULT_REGION`, `amazon-bedrock`
provider `baseUrl`에서 확인되거나, 기본값으로 `us-east-1`을 사용합니다.
리전은 `AWS_REGION`, `AWS_DEFAULT_REGION`, `amazon-bedrock` 제공자의 `baseUrl`에서 확인되며, 없으면 기본값 `us-east-1`이 사용됩니다.
### IAM 권한
IAM 역할 또는 사용자에게는 다음 권한이 필요합니다:
IAM 역할 또는 사용자에게는 다음 권한이 필요합니다.
```json
{
@ -194,7 +187,7 @@ IAM 역할 또는 사용자에게는 다음 권한이 필요합니다:
}
```
최소 권한 원칙을 적용하려면 `InvokeModel`을 특정 모델로 제한하세요:
최소 권한 원칙을 적용하려면 `InvokeModel`을 특정 모델로 범위를 제한하세요.
```
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
@ -204,42 +197,42 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
## 로컬 임베딩 구성
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| --------------------- | -------- | ---------------------- | ------------------------------- |
| `local.modelPath` | `string` | 자동 다운로드 | GGUF 모델 파일 경로 |
| `local.modelCacheDir` | `string` | node-llama-cpp 기본값 | 다운로드된 모델의 캐시 디렉터리 |
| `local.modelPath` | `string` | 자동 다운로드 | GGUF 모델 파일 경로 |
| `local.modelCacheDir` | `string` | node-llama-cpp 기본값 | 다운로드된 모델의 캐시 디렉터리 |
기본 모델: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, 자동 다운로드).
기본 모델: `embeddinggemma-300m-qat-Q8_0.gguf`(~0.6GB, 자동 다운로드).
네이티브 빌드 필요: `pnpm approve-builds` 후 `pnpm rebuild node-llama-cpp`.
---
## 하이브리드 검색 구성
모두 `memorySearch.query.hybrid` 아래에 있습니다:
모두 `memorySearch.query.hybrid` 아래에 있습니다.
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| --------------------- | --------- | ------- | ---------------------------------- |
| `enabled` | `boolean` | `true` | 하이브리드 BM25 + 벡터 검색 활성화 |
| `vectorWeight` | `number` | `0.7` | 벡터 점수 가중치(0-1) |
| `textWeight` | `number` | `0.3` | BM25 점수 가중치(0-1) |
| `candidateMultiplier` | `number` | `4` | 후보 풀 크기 배수 |
| `vectorWeight` | `number` | `0.7` | 벡터 점수 가중치(0-1) |
| `textWeight` | `number` | `0.3` | BM25 점수 가중치(0-1) |
| `candidateMultiplier` | `number` | `4` | 후보 풀 크기 배수 |
### MMR(다양성)
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ------------- | --------- | ------- | ------------------------------------ |
| `mmr.enabled` | `boolean` | `false` | MMR 재순위화 활성화 |
| `mmr.lambda` | `number` | `0.7` | 0 = 최대 다양성, 1 = 최대 관련성 |
| `mmr.enabled` | `boolean` | `false` | MMR 재순위화 활성화 |
| `mmr.lambda` | `number` | `0.7` | 0 = 최대 다양성, 1 = 최대 관련성 |
### 시간 감쇠(최신성)
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ---------------------------- | --------- | ------- | ------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | 최신성 가중치 활성화 |
| `temporalDecay.halfLifeDays` | `number` | `30` | 점수가 N일마다 절반이 됨 |
| `temporalDecay.enabled` | `boolean` | `false` | 최신성 부스트 활성화 |
| `temporalDecay.halfLifeDays` | `number` | `30` | N일마다 점수가 절반으로 감소 |
상시 파일(`MEMORY.md`, `memory/`의 날짜 없는 파일)은 감쇠되지 않습니다.
에버그린 파일(`MEMORY.md`, `memory/`의 날짜가 없는 파일)은 감쇠되지 않습니다.
### 전체 예시
@ -266,9 +259,9 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
## 추가 메모리 경로
| Key | Type | Description |
| 키 | 타입 | 설명 |
| ------------ | ---------- | ---------------------------------------- |
| `extraPaths` | `string[]` | 인덱싱할 추가 디렉터리 또는 파일 |
| `extraPaths` | `string[]` | 인덱싱할 추가 디렉터리 또는 파일 |
```json5
{
@ -282,31 +275,24 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
}
```
경로는 절대 경로 또는 워크스페이스 상대 경로일 수 있습니다. 디렉터리는
`.md` 파일을 위해 재귀적으로 스캔됩니다. 심볼릭 링크 처리 방식은 활성 백엔드에 따라 다릅니다:
builtin 엔진은 심볼릭 링크를 무시하고, QMD는 기본 QMD 스캐너 동작을 따릅니다.
경로는 절대 경로이거나 워크스페이스 기준 상대 경로일 수 있습니다. 디렉터리는 `.md` 파일을 재귀적으로 스캔합니다. 심볼릭 링크 처리 방식은 활성 백엔드에 따라 다릅니다. 내장 엔진은 심볼릭 링크를 무시하고, QMD는 기본 QMD 스캐너의 동작을 따릅니다.
agent 범위의 교차 agent transcript 검색에는
`memory.qmd.paths` 대신 `agents.list[].memorySearch.qmd.extraCollections`를 사용하세요.
이 추가 컬렉션은 동일한 `{ path, name, pattern? }` 형태를 따르지만,
agent별로 병합되며 경로가 현재 워크스페이스 밖을 가리킬 때 명시적 공유 이름을 유지할 수 있습니다.
동일한 확인된 경로가 `memory.qmd.paths`와
`memorySearch.qmd.extraCollections`에 모두 나타나면, QMD는 첫 번째 항목을 유지하고
중복 항목은 건너뜁니다.
에이전트 범위의 교차 에이전트 대화 기록 검색에는 `memory.qmd.paths` 대신 `agents.list[].memorySearch.qmd.extraCollections`를 사용하세요. 이러한 추가 컬렉션은 동일한 `{ path, name, pattern? }` 형태를 따르지만, 에이전트별로 병합되며 경로가 현재 워크스페이스 외부를 가리킬 때 명시적인 공유 이름을 유지할 수 있습니다.
동일한 확인된 경로가 `memory.qmd.paths`와 `memorySearch.qmd.extraCollections`에 모두 나타나면, QMD는 첫 번째 항목을 유지하고 중복 항목은 건너뜁니다.
---
## 멀티모달 메모리(Gemini)
Gemini Embedding 2를 사용해 Markdown과 함께 이미지 및 오디오를 인덱싱합니다:
Gemini Embedding 2를 사용해 Markdown과 함께 이미지 및 오디오를 인덱싱합니다.
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ------------------------- | ---------- | ---------- | -------------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | 멀티모달 인덱싱 활성화 |
| `multimodal.enabled` | `boolean` | `false` | 멀티모달 인덱싱 활성화 |
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]`, 또는 `["all"]` |
| `multimodal.maxFileBytes` | `number` | `10000000` | 인덱싱할 최대 파일 크기 |
| `multimodal.maxFileBytes` | `number` | `10000000` | 인덱싱할 최대 파일 크기 |
`extraPaths`의 파일에만 적용됩니다. 기본 메모리 루트는 계속 Markdown 전용입니다.
`extraPaths`에 있는 파일에만 적용됩니다. 기본 메모리 루트는 계속 Markdown 전용입니다.
`gemini-embedding-2-preview`가 필요합니다. `fallback`은 반드시 `"none"`이어야 합니다.
지원 형식: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
@ -316,117 +302,109 @@ Gemini Embedding 2를 사용해 Markdown과 함께 이미지 및 오디오를
## 임베딩 캐시
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ------------------ | --------- | ------- | -------------------------------- |
| `cache.enabled` | `boolean` | `false` | SQLite에 청크 임베딩 캐시 |
| `cache.maxEntries` | `number` | `50000` | 최대 캐시 임베딩 수 |
| `cache.enabled` | `boolean` | `false` | SQLite에 청크 임베딩 캐시 |
| `cache.maxEntries` | `number` | `50000` | 최대 캐시 임베딩 수 |
재인덱싱 또는 transcript 업데이트 중 변경되지 않은 텍스트의 재임베딩을 방지합니다.
재인덱싱이나 대화 기록 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하는 일을 방지합니다.
---
## 배치 인덱싱
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ----------------------------- | --------- | ------- | -------------------------- |
| `remote.batch.enabled` | `boolean` | `false` | 배치 임베딩 API 활성화 |
| `remote.batch.concurrency` | `number` | `2` | 병렬 배치 작업 수 |
| `remote.batch.wait` | `boolean` | `true` | 배치 완료까지 대기 |
| `remote.batch.pollIntervalMs` | `number` | -- | 폴링 간격 |
| `remote.batch.timeoutMinutes` | `number` | -- | 배치 타임아웃 |
| `remote.batch.enabled` | `boolean` | `false` | 배치 임베딩 API 활성화 |
| `remote.batch.concurrency` | `number` | `2` | 병렬 배치 작업 수 |
| `remote.batch.wait` | `boolean` | `true` | 배치 완료까지 대기 |
| `remote.batch.pollIntervalMs` | `number` | -- | 폴링 간격 |
| `remote.batch.timeoutMinutes` | `number` | -- | 배치 타임아웃 |
`openai`, `gemini`, `voyage`에서 사용할 수 있습니다. OpenAI 배치는 일반적으로
대규모 백필에 가장 빠르고 비용 효율적입니다.
`openai`, `gemini`, `voyage`에서 사용할 수 있습니다. OpenAI 배치는 일반적으로 대규모 백필에서 가장 빠르고 비용도 가장 저렴합니다.
---
## 세션 메모리 검색(실험적)
세션 transcript를 인덱싱하고 이를 `memory_search`를 통해 표시합니다:
세션 대화 기록을 인덱싱하고 이를 `memory_search`를 통해 노출합니다.
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ----------------------------- | ---------- | ------------ | --------------------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | 세션 인덱싱 활성화 |
| `sources` | `string[]` | `["memory"]` | transcript를 포함하려면 `"sessions"` 추가 |
| `sync.sessions.deltaBytes` | `number` | `100000` | 재인덱싱 바이트 임계값 |
| `sync.sessions.deltaMessages` | `number` | `50` | 재인덱싱 메시지 임계값 |
| `experimental.sessionMemory` | `boolean` | `false` | 세션 인덱싱 활성화 |
| `sources` | `string[]` | `["memory"]` | 대화 기록을 포함하려면 `"sessions"` 추가 |
| `sync.sessions.deltaBytes` | `number` | `100000` | 재인덱싱 바이트 임계값 |
| `sync.sessions.deltaMessages` | `number` | `50` | 재인덱싱 메시지 수 임계값 |
세션 인덱싱은 opt-in이며 비동기적으로 실행됩니다. 결과는 약간
오래되었을 수 있습니다. 세션 로그는 디스크에 저장되므로 파일시스템 접근을
신뢰 경계로 취급하세요.
세션 인덱싱은 옵트인 방식이며 비동기로 실행됩니다. 결과가 약간 오래되었을 수 있습니다. 세션 로그는 디스크에 저장되므로 파일 시스템 접근을 신뢰 경계로 취급하세요.
---
## SQLite 벡터 가속(sqlite-vec)
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ---------------------------- | --------- | ------- | --------------------------------- |
| `store.vector.enabled` | `boolean` | `true` | 벡터 쿼리에 sqlite-vec 사용 |
| `store.vector.extensionPath` | `string` | bundled | sqlite-vec 경로 재정의 |
| `store.vector.enabled` | `boolean` | `true` | 벡터 쿼리에 sqlite-vec 사용 |
| `store.vector.extensionPath` | `string` | bundled | sqlite-vec 경로 재정의 |
sqlite-vec를 사용할 수 없으면 OpenClaw는 자동으로 프로세스 내 cosine
similarity로 대체합니다.
sqlite-vec를 사용할 수 없으면 OpenClaw는 자동으로 프로세스 내 코사인 유사도 계산으로 대체합니다.
---
## 인덱스 저장소
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 인덱스 위치(`{agentId}` 토큰 지원) |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer(`unicode61` 또는 `trigram`) |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 인덱스 위치(`{agentId}` 토큰 지원) |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 토크나이저(`unicode61` 또는 `trigram`) |
---
## QMD 백엔드 구성
활성화하려면 `memory.backend = "qmd"`를 설정하세요. 모든 QMD 설정은
`memory.qmd` 아래에 있습니다:
`memory.qmd` 아래에 있습니다.
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ------------------------ | --------- | -------- | -------------------------------------------- |
| `command` | `string` | `qmd` | QMD 실행 파일 경로 |
| `searchMode` | `string` | `search` | 검색 명령어: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md` 자동 인덱싱 |
| `paths[]` | `array` | -- | 추가 경로: `{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | 세션 transcript 인덱싱 |
| `sessions.retentionDays` | `number` | -- | transcript 보존 기간 |
| `sessions.exportDir` | `string` | -- | 내보내기 디렉터리 |
| `command` | `string` | `qmd` | QMD 실행 파일 경로 |
| `searchMode` | `string` | `search` | 검색 명령: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md` 자동 인덱싱 |
| `paths[]` | `array` | -- | 추가 경로: `{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | 세션 대화 기록 인덱싱 |
| `sessions.retentionDays` | `number` | -- | 대화 기록 보존 기간 |
| `sessions.exportDir` | `string` | -- | 내보내기 디렉터리 |
OpenClaw는 현재 QMD 컬렉션 및 MCP 쿼리 형식을 우선 사용하지만,
필요할 경우 레거시 `--mask` 컬렉션 플래그와 이전 MCP 도구 이름으로 대체하여
오래된 QMD 릴리스도 계속 동작하도록 유지합니다.
OpenClaw는 현재 QMD 컬렉션 및 MCP 쿼리 형식을 우선 사용하지만, 필요할 경우 레거시 `--mask` 컬렉션 플래그와 이전 MCP 도구 이름으로 대체해 이전 QMD 릴리스도 계속 작동하도록 유지합니다.
QMD 모델 재정의는 OpenClaw 구성이 아니라 QMD 쪽에 유지됩니다. 전역적으로
QMD 모델을 재정의해야 한다면 Gateway 런타임 환경에서
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, `QMD_GENERATE_MODEL` 같은 환경 변수를 설정하세요.
QMD 모델 재정의는 OpenClaw 구성이 아니라 QMD 측에 유지됩니다. QMD 모델을 전역으로 재정의해야 한다면 게이트웨이 런타임 환경에서 `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, `QMD_GENERATE_MODEL` 같은 환경 변수를 설정하세요.
### 업데이트 일정
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ------------------------- | --------- | ------- | ------------------------------------- |
| `update.interval` | `string` | `5m` | 새로고침 간격 |
| `update.debounceMs` | `number` | `15000` | 파일 변경 디바운스 |
| `update.onBoot` | `boolean` | `true` | 시작 시 새로고침 |
| `update.waitForBootSync` | `boolean` | `false` | 새로고침 완료까지 시작 차단 |
| `update.embedInterval` | `string` | -- | 별도 임베딩 주기 |
| `update.commandTimeoutMs` | `number` | -- | QMD 명령어 타임아웃 |
| `update.updateTimeoutMs` | `number` | -- | QMD 업데이트 작업 타임아웃 |
| `update.embedTimeoutMs` | `number` | -- | QMD 임베딩 작업 타임아웃 |
| `update.interval` | `string` | `5m` | 새로 고침 간격 |
| `update.debounceMs` | `number` | `15000` | 파일 변경 디바운스 |
| `update.onBoot` | `boolean` | `true` | 시작 시 새로 고침 |
| `update.waitForBootSync` | `boolean` | `false` | 새로 고침 완료까지 시작 차단 |
| `update.embedInterval` | `string` | -- | 별도 임베딩 주기 |
| `update.commandTimeoutMs` | `number` | -- | QMD 명령 타임아웃 |
| `update.updateTimeoutMs` | `number` | -- | QMD 업데이트 작업 타임아웃 |
| `update.embedTimeoutMs` | `number` | -- | QMD 임베딩 작업 타임아웃 |
### 제한
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ------------------------- | -------- | ------- | -------------------------- |
| `limits.maxResults` | `number` | `6` | 최대 검색 결과 수 |
| `limits.maxSnippetChars` | `number` | -- | 스니펫 길이 제한 |
| `limits.maxInjectedChars` | `number` | -- | 총 주입 문자 수 제한 |
| `limits.timeoutMs` | `number` | `4000` | 검색 타임아웃 |
| `limits.maxResults` | `number` | `6` | 최대 검색 결과 수 |
| `limits.maxSnippetChars` | `number` | -- | 스니펫 길이 제한 |
| `limits.maxInjectedChars` | `number` | -- | 전체 주입 문자 수 제한 |
| `limits.timeoutMs` | `number` | `4000` | 검색 타임아웃 |
### 범위
어떤 세션이 QMD 검색 결과를 받을 수 있는지 제어합니다. 스키마는
[`session.sendPolicy`](/ko/gateway/configuration-reference#session)와 동일합니다:
[`session.sendPolicy`](/ko/gateway/configuration-reference#session)와 같습니다.
```json5
{
@ -441,21 +419,20 @@ QMD 모델을 재정의해야 한다면 Gateway 런타임 환경에서
}
```
배포 기본값은 direct 및 channel 세션은 허용하고,
group은 계속 거부합니다.
기본 제공 설정은 direct 및 채널 세션은 허용하고, 그룹은 계속 거부합니다.
기본값은 DM 전용입니다. `match.keyPrefix`는 정규화된 세션 키와 일치하고,
기본값은 DM 전용입니다. `match.keyPrefix`는 정규화된 세션 키와 일치합니다.
`match.rawKeyPrefix`는 `agent:<id>:`를 포함한 원시 키와 일치합니다.
### 인용
`memory.citations`는 모든 백엔드에 적용됩니다:
`memory.citations`는 모든 백엔드에 적용됩니다.
| Value | Behavior |
| 값 | 동작 |
| ---------------- | --------------------------------------------------- |
| `auto` (기본값) | 스니펫에 `Source: <path#line>` 푸터 포함 |
| `on` | 항상 푸터 포함 |
| `off` | 푸터 생략(path는 여전히 내부적으로 agent에 전달됨) |
| `auto` (기본값) | 스니펫에 `Source: <path#line>` 바닥글 포함 |
| `on` | 항상 바닥글 포함 |
| `off` | 바닥글 생략(경로는 여전히 내부적으로 에이전트에 전달됨) |
### 전체 QMD 예시
@ -480,22 +457,20 @@ group은 계속 거부합니다.
---
## Dreaming(실험적)
## Dreaming
Dreaming은 `agents.defaults.memorySearch` 아래가 아니라
`plugins.entries.memory-core.config.dreaming` 아래에 구성됩니다.
Dreaming은 `agents.defaults.memorySearch`가 아니라 `plugins.entries.memory-core.config.dreaming` 아래에서 구성합니다.
Dreaming은 하나의 예약된 스윕으로 실행되며 내부적인 light/deep/REM 단계를
구현 세부 사항으로 사용합니다.
Dreaming은 예약된 한 번의 스윕으로 실행되며, 내부적인 구현 세부 사항으로 light/deep/REM 단계를 사용합니다.
개념적 동작과 슬래시 명령어는 [Dreaming](/ko/concepts/dreaming)을 참조하세요.
개념적 동작과 슬래시 명령은 [Dreaming](/ko/concepts/dreaming)을 참고하세요.
### 사용자 설정
| Key | Type | Default | Description |
| 키 | 타입 | 기본값 | 설명 |
| ----------- | --------- | ----------- | ------------------------------------------------- |
| `enabled` | `boolean` | `false` | Dreaming 전체 활성화 또는 비활성화 |
| `frequency` | `string` | `0 3 * * *` | 전체 Dreaming 스윕용 선택적 Cron 주기 |
| `enabled` | `boolean` | `false` | Dreaming 전체 활성화 또는 비활성화 |
| `frequency` | `string` | `0 3 * * *` | 전체 Dreaming 스윕의 선택적 Cron 주기 |
### 예시
@ -519,5 +494,5 @@ Dreaming은 하나의 예약된 스윕으로 실행되며 내부적인 light/dee
참고:
- Dreaming은 머신 상태를 `memory/.dreams/`에 기록합니다.
- Dreaming은 사람이 읽을 수 있는 내러티브 출력을 `DREAMS.md`(또는 기존 `dreams.md`)에 기록합니다.
- light/deep/REM 단계 정책과 임계값은 내부 동작이며 사용자 대상 구성이 아닙니다.
- Dreaming은 사람이 읽을 수 있는 서술형 출력을 `DREAMS.md`(또는 기존 `dreams.md`)에 기록합니다.
- light/deep/REM 단계 정책과 임계값은 내부 동작이며 사용자 대상 구성 항목이 아닙니다.

194
docs/ko/reference/wizard.md
View File

@ -1,16 +1,16 @@
---
read_when:
- 특정 온보딩 단계나 플래그를 찾을 때
- 비대화형 모드로 온보딩을 자동화할 때
- 온보딩 동작을 디버깅할 때
- 특정 온보딩 단계 또는 플래그 찾기
- 비대화형 모드로 온보딩 자동화하기
- 온보딩 동작 디버깅하기
sidebarTitle: Onboarding Reference
summary: 'CLI 온보딩의 전체 참조: 모든 단계, 플래그, config 필드'
summary: 'CLI 온보딩 전체 참조: 모든 단계, 플래그, config 필드'
title: 온보딩 참조
x-i18n:
generated_at: "2026-04-07T06:01:52Z"
generated_at: "2026-04-15T14:40:59Z"
model: gpt-5.4
provider: openai
source_hash: a142b9ec4323fabb9982d05b64375d2b4a4007dffc910acbee3a38ff871a7236
source_hash: 1db3ff789422617634e6624f9d12c18b6a6c573721226b9c0fa6f6b7956ef33d
source_path: reference/wizard.md
workflow: 15
---
@ -18,138 +18,137 @@ x-i18n:
# 온보딩 참조
이 문서는 `openclaw onboard`의 전체 참조입니다.
상위 수준 개요는 [온보딩(CLI)](/ko/start/wizard)을 참고하세요.
상위 수준 개요는 [온보딩 (CLI)](/ko/start/wizard)를 참조하세요.
## 흐름 세부 정보(로컬 모드)
## 흐름 세부 정보 (local 모드)
<Steps>
<Step title="기존 config 감지">
- `~/.openclaw/openclaw.json`이 있으면 **유지 / 수정 / 재설정** 중에서 선택합니다.
- 온보딩을 다시 실행해도 명시적으로 **재설정**을 선택하지 않는 한
(`--reset`을 전달하는 경우 포함) 아무것도 지워지지 않습니다.
- CLI `--reset`의 기본값은 `config+creds+sessions`이며, workspace까지 제거하려면
`--reset-scope full`을 사용하세요.
- config가 유효하지 않거나 레거시 키를 포함하고 있으면, 마법사는 중지되고
- `~/.openclaw/openclaw.json`이 있으면 **유지 / 수정 / 초기화**를 선택합니다.
- 온보딩을 다시 실행해도 명시적으로 **초기화**를 선택하지 않는 한 아무것도 지워지지 않습니다
(또는 `--reset`을 전달한 경우).
- CLI `--reset`의 기본값은 `config+creds+sessions`이며, workspace까지 제거하려면 `--reset-scope full`을 사용하세요.
- config가 유효하지 않거나 레거시 키를 포함하고 있으면, 마법사는 중단되고
계속하기 전에 `openclaw doctor`를 실행하라고 안내합니다.
- 재설정은 `trash`를 사용하며(`rm`은 절대 사용하지 않음) 다음 범위를 제공합니다:
- Config만
- Config + credentials + sessions
- 전체 재설정(workspace도 제거)
- 초기화는 `trash`를 사용하며(`rm`은 절대 사용하지 않음) 다음 범위를 제공합니다:
- config만
- config + 자격 증명 + 세션
- 전체 초기화 (workspace도 제거)
</Step>
<Step title="모델/인증">
- **Anthropic API 키**: 있으면 `ANTHROPIC_API_KEY`를 사용하고, 없으면 키를 입력받은 뒤 daemon에서 사용할 수 있도록 저장합니다.
- **Anthropic API 키**: onboarding/configure에서 선호되는 Anthropic assistant 선택지입니다.
- **Anthropic setup-token**: OpenClaw는 현재 가능할 때 Claude CLI 재사용을 선호하지만, onboarding/configure에서는 여전히 사용할 수 있습니다.
- **OpenAI Code (Codex) 구독(Codex CLI)**: `~/.codex/auth.json`이 있으면 온보딩에서 이를 재사용할 수 있습니다. 재사용된 Codex CLI 자격 증명은 계속 Codex CLI가 관리합니다. 만료되면 OpenClaw는 먼저 그 소스를 다시 읽고, provider가 이를 갱신할 수 있으면 직접 소유권을 가져오지 않고 갱신된 자격 증명을 다시 Codex 저장소에 기록합니다.
- **OpenAI Code (Codex) 구독(OAuth)**: 브라우저 흐름으로 진행되며, `code#state`를 붙여 넣습니다.
- **Anthropic API 키**: `ANTHROPIC_API_KEY`가 있으면 이를 사용하고, 없으면 키를 요청한 뒤 daemon 사용을 위해 저장합니다.
- **Anthropic API 키**: 온보딩/configure에서 선호되는 Anthropic 도우미 선택지입니다.
- **Anthropic setup-token**: 여전히 온보딩/configure에서 사용할 수 있지만, OpenClaw는 이제 가능하면 Claude CLI 재사용을 우선합니다.
- **OpenAI Code (Codex) 구독 (Codex CLI)**: `~/.codex/auth.json`이 있으면 온보딩에서 이를 재사용할 수 있습니다. 재사용된 Codex CLI 자격 증명은 계속 Codex CLI가 관리합니다. 만료되면 OpenClaw는 먼저 그 소스를 다시 읽고, 제공자가 갱신할 수 있는 경우 자격 증명을 직접 가져오지 않고 갱신된 자격 증명을 Codex 저장소에 다시 기록합니다.
- **OpenAI Code (Codex) 구독 (OAuth)**: 브라우저 흐름이며 `code#state`를 붙여 넣습니다.
- 모델이 설정되지 않았거나 `openai/*`인 경우 `agents.defaults.model`을 `openai-codex/gpt-5.4`로 설정합니다.
- **OpenAI API 키**: 있으면 `OPENAI_API_KEY`를 사용하고, 없으면 키를 입력받은 뒤 auth profile에 저장합니다.
- **OpenAI API 키**: `OPENAI_API_KEY`가 있으면 이를 사용하고, 없으면 키를 요청한 뒤 인증 프로필에 저장합니다.
- 모델이 설정되지 않았거나 `openai/*` 또는 `openai-codex/*`인 경우 `agents.defaults.model`을 `openai/gpt-5.4`로 설정합니다.
- **xAI (Grok) API 키**: `XAI_API_KEY`를 입력받고 xAI를 모델 provider로 구성합니다.
- **OpenCode**: `OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`, https://opencode.ai/auth 에서 발급)를 입력받고 Zen 또는 Go 카탈로그를 선택할 수 있게 합니다.
- **Ollama**: Ollama 기본 URL을 입력받고, **Cloud + Local** 또는 **Local** 모드를 제안하며, 사용 가능한 모델을 검색하고 필요하면 선택한 로컬 모델을 자동으로 pull합니다.
- **xAI (Grok) API 키**: `XAI_API_KEY`를 요청하고 xAI를 모델 제공자로 구성합니다.
- **OpenCode**: `OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`, 발급처: https://opencode.ai/auth)를 요청하고 Zen 또는 Go 카탈로그를 선택하게 합니다.
- **Ollama**: 먼저 **Cloud + Local**, **Cloud only**, **Local only**를 제공합니다. `Cloud only`는 `OLLAMA_API_KEY`를 요청하고 `https://ollama.com`을 사용합니다. 호스트 기반 모드는 Ollama 기본 URL을 요청하고, 사용 가능한 모델을 검색하며, 필요할 때 선택한 로컬 모델을 자동으로 pull합니다. `Cloud + Local`은 해당 Ollama 호스트가 cloud 액세스를 위해 로그인되어 있는지도 확인합니다.
- 자세한 내용: [Ollama](/ko/providers/ollama)
- **API 키**: 키를 대신 저장해 줍니다.
- **Vercel AI Gateway (멀티 모델 프록시)**: `AI_GATEWAY_API_KEY`를 입력받습니다.
- **API 키**: 키를 대신 저장합니다.
- **Vercel AI Gateway (다중 모델 프록시)**: `AI_GATEWAY_API_KEY`를 요청합니다.
- 자세한 내용: [Vercel AI Gateway](/ko/providers/vercel-ai-gateway)
- **Cloudflare AI Gateway**: Account ID, Gateway ID, `CLOUDFLARE_AI_GATEWAY_API_KEY`를 입력받습니다.
- **Cloudflare AI Gateway**: Account ID, Gateway ID, `CLOUDFLARE_AI_GATEWAY_API_KEY`를 요청합니다.
- 자세한 내용: [Cloudflare AI Gateway](/ko/providers/cloudflare-ai-gateway)
- **MiniMax**: config가 자동으로 기록되며, 호스팅 기본값은 `MiniMax-M2.7`입니다.
- **MiniMax**: config가 자동으로 작성되며, 호스팅 기본값은 `MiniMax-M2.7`입니다.
API 키 설정은 `minimax/...`를 사용하고, OAuth 설정은
`minimax-portal/...`를 사용합니다.
- 자세한 내용: [MiniMax](/ko/providers/minimax)
- **StepFun**: config가 중국 또는 글로벌 엔드포인트의 StepFun standard 또는 Step Plan용으로 자동 작성됩니다.
- Standard에는 현재 `step-3.5-flash`가 포함되며, Step Plan에는 `step-3.5-flash-2603`도 포함됩니다.
- **StepFun**: 중국 또는 글로벌 엔드포인트에서 StepFun standard 또는 Step Plan용 config가 자동으로 작성됩니다.
- 현재 Standard에는 `step-3.5-flash`가 포함되며, Step Plan에는 `step-3.5-flash-2603`도 포함됩니다.
- 자세한 내용: [StepFun](/ko/providers/stepfun)
- **Synthetic (Anthropic 호환)**: `SYNTHETIC_API_KEY`를 입력받습니다.
- **Synthetic (Anthropic 호환)**: `SYNTHETIC_API_KEY`를 요청합니다.
- 자세한 내용: [Synthetic](/ko/providers/synthetic)
- **Moonshot (Kimi K2)**: config가 자동으로 기록됩니다.
- **Kimi Coding**: config가 자동으로 기록됩니다.
- **Moonshot (Kimi K2)**: config가 자동으로 작성됩니다.
- **Kimi Coding**: config가 자동으로 작성됩니다.
- 자세한 내용: [Moonshot AI (Kimi + Kimi Coding)](/ko/providers/moonshot)
- **건너뛰기**: 아직 인증을 구성하지 않습니다.
- 감지된 옵션에서 기본 모델을 선택합니다(또는 provider/model을 직접 입력). 가장 좋은 품질과 더 낮은 prompt-injection 위험을 위해, provider 스택에서 사용할 수 있는 가장 강력한 최신 세대 모델을 선택하세요.
- 온보딩은 모델 검사를 실행하며, 구성된 모델을 알 수 없거나 인증이 없으면 경고합니다.
- API 키 저장 모드의 기본값은 평문 auth-profile 값입니다. 대신 env 기반 ref를 저장하려면 `--secret-input-mode ref`를 사용하세요(예: `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
- Auth profile은 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`에 저장됩니다(API 키 + OAuth). `~/.openclaw/credentials/oauth.json`은 레거시 가져오기 전용입니다.
- **건너뛰기**: 아직 인증이 구성되지 않습니다.
- 감지된 옵션에서 기본 모델을 선택합니다(또는 제공자/모델을 수동으로 입력합니다). 최상의 품질과 더 낮은 프롬프트 인젝션 위험을 위해 제공자 스택에서 사용할 수 있는 가장 강력한 최신 세대 모델을 선택하세요.
- 온보딩은 모델 검사를 실행하고, 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고를 표시합니다.
- API 키 저장 모드의 기본값은 평문 인증 프로필 값입니다. 대신 env 기반 ref를 저장하려면 `--secret-input-mode ref`를 사용하세요(예: `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
- 인증 프로필은 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`에 저장됩니다(API 키 + OAuth). `~/.openclaw/credentials/oauth.json`은 레거시 가져오기 전용입니다.
- 자세한 내용: [/concepts/oauth](/ko/concepts/oauth)
<Note>
헤드리스/서버 팁: 브라우저가 있는 머신에서 OAuth를 완료한 뒤,
해당 agent의 `auth-profiles.json`(예:
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`, 또는 대응하는
헤드리스/서버 팁: 브라우저가 있는 장치에서 OAuth를 완료한 다음,
해당 에이전트의 `auth-profiles.json`(예:
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 또는 대응되는
`$OPENCLAW_STATE_DIR/...` 경로)을 gateway 호스트로 복사하세요. `credentials/oauth.json`은
레거시 가져오기 소스일 뿐입니다.
</Note>
</Step>
<Step title="워크스페이스">
- 기본값은 `~/.openclaw/workspace`입니다(변경 가능).
- agent 부트스트랩 ritual에 필요한 workspace 파일을 시드합니다.
<Step title="Workspace">
- 기본값은 `~/.openclaw/workspace`입니다(구성 가능).
- 에이전트 bootstrap ritual에 필요한 workspace 파일을 시드합니다.
- 전체 workspace 레이아웃 + 백업 가이드: [Agent workspace](/ko/concepts/agent-workspace)
</Step>
<Step title="Gateway">
- 포트, bind, auth mode, tailscale 노출.
- 인증 권장 사항: loopback에서도 **Token**을 유지해 로컬 WS 클라이언트가 인증하도록 하세요.
- 토큰 모드에서 대화형 설정은 다음을 제공합니다:
- **평문 토큰 생성/저장**(기본값)
- **SecretRef 사용**(선택 사항)
- Quickstart는 온보딩 probe/dashboard bootstrap을 위해 `env`, `file`, `exec` provider 전반에서 기존 `gateway.auth.token` SecretRef를 재사용합니다.
- 해당 SecretRef가 구성되어 있지만 확인할 수 없으면, 온보딩은 런타임 인증을 조용히 약화시키는 대신 명확한 수정 메시지와 함께 조기에 실패합니다.
- 비밀번호 모드에서도 대화형 설정은 평문 또는 SecretRef 저장을 지원합니다.
- 비대화형 토큰 SecretRef 경로: `--gateway-token-ref-env <ENV_VAR>`.
- 온보딩 프로세스 환경에 비어 있지 않은 env var가 필요합니다.
- 포트, bind, 인증 모드, Tailscale 노출.
- 인증 권장 사항: local loopback에서도 **Token**을 유지해 로컬 WS 클라이언트가 인증하도록 하세요.
- token 모드에서 대화형 설정은 다음을 제공합니다:
- **평문 token 생성/저장** (기본값)
- **SecretRef 사용** (선택 사항)
- 빠른 시작은 온보딩 프로브/대시보드 bootstrap을 위해 `env`, `file`, `exec` 제공자 전반에서 기존 `gateway.auth.token` SecretRef를 재사용합니다.
- 해당 SecretRef가 구성되어 있지만 확인할 수 없으면, 온보딩은 런타임 인증을 조용히 저하시키는 대신 명확한 수정 메시지와 함께 초기에 실패합니다.
- password 모드에서 대화형 설정도 평문 또는 SecretRef 저장을 지원합니다.
- 비대화형 token SecretRef 경로: `--gateway-token-ref-env <ENV_VAR>`.
- 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다.
- `--gateway-token`과 함께 사용할 수 없습니다.
- 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하세요.
- loopback이 아닌 bind는 여전히 인증이 필요합니다.
- loopback이 아닌 bind에도 여전히 인증이 필요합니다.
</Step>
<Step title="채널">
- [WhatsApp](/ko/channels/whatsapp): 선택적 QR 로그인.
- [Telegram](/ko/channels/telegram): 봇 토큰.
- [Discord](/ko/channels/discord): 봇 토큰.
- [Google Chat](/ko/channels/googlechat): 서비스 계정 JSON + webhook audience.
- [Mattermost](/ko/channels/mattermost) (plugin): 봇 토큰 + 기본 URL.
- [Google Chat](/ko/channels/googlechat): 서비스 계정 JSON + Webhook audience.
- [Mattermost](/ko/channels/mattermost) (Plugin): 봇 토큰 + 기본 URL.
- [Signal](/ko/channels/signal): 선택적 `signal-cli` 설치 + 계정 config.
- [BlueBubbles](/ko/channels/bluebubbles): **iMessage에 권장**; 서버 URL + 비밀번호 + webhook.
- [BlueBubbles](/ko/channels/bluebubbles): **iMessage에 권장**; 서버 URL + 비밀번호 + Webhook.
- [iMessage](/ko/channels/imessage): 레거시 `imsg` CLI 경로 + DB 액세스.
- DM 보안: 기본값은 페어링입니다. 첫 번째 DM은 코드를 전송하며, `openclaw pairing approve <channel> <code>`로 승인하거나 allowlist를 사용할 수 있습니다.
- DM 보안: 기본값은 pairing입니다. 첫 DM은 코드를 전송하며, `openclaw pairing approve <channel> <code>`로 승인하거나 허용 목록을 사용할 수 있습니다.
</Step>
<Step title="웹 검색">
- Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily 같은 지원 provider를 선택합니다(또는 건너뜁니다).
- API 기반 provider는 빠른 설정을 위해 env var 또는 기존 config를 사용할 수 있고, 키가 필요 없는 provider는 provider별 사전 요구 사항을 대신 사용합니다.
- `--skip-search`로 건너뛸 수 있습니다.
- Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily 같은 지원 제공자를 선택합니다(또는 건너뜁니다).
- API 기반 제공자는 빠른 설정을 위해 환경 변수 또는 기존 config를 사용할 수 있으며, 키가 필요 없는 제공자는 각 제공자별 선행 조건을 사용합니다.
- `--skip-search`로 건너뜁니다.
- 나중에 구성: `openclaw configure --section web`.
</Step>
<Step title="데몬 설치">
<Step title="Daemon 설치">
- macOS: LaunchAgent
- 로그인된 사용자 세션이 필요합니다. 헤드리스 환경에서는 사용자 지정 LaunchDaemon을 사용하세요(기본 제공되지 않음).
- 로그인된 사용자 세션이 필요합니다. 헤드리스의 경우 사용자 지정 LaunchDaemon을 사용하세요(기본 제공되지 않음).
- Linux(및 WSL2를 통한 Windows): systemd 사용자 유닛
- 온보딩은 로그아웃 후에도 Gateway가 계속 실행되도록 `loginctl enable-linger <user>`를 활성화하려고 시도합니다.
- 온보딩은 로그아웃 후에도 Gateway가 계속 실행되도록 `loginctl enable-linger <user>` 활성화를 시도합니다.
- sudo를 요청할 수 있습니다(`/var/lib/systemd/linger`에 기록). 먼저 sudo 없이 시도합니다.
- **런타임 선택:** Node(권장; WhatsApp/Telegram에 필요). Bun은 **권장되지 않습니다**.
- 토큰 인증에 토큰이 필요하고 `gateway.auth.token`이 SecretRef로 관리되는 경우, daemon 설치는 이를 검증하지만 확인된 평문 토큰 값을 supervisor 서비스 환경 메타데이터에 저장하지는 않습니다.
- 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef가 확인되지 않으면, daemon 설치는 실행 가능한 안내와 함께 차단됩니다.
- **런타임 선택:** Node(권장, WhatsApp/Telegram에 필요). Bun은 **권장되지 않습니다**.
- token 인증에 token이 필요하고 `gateway.auth.token`이 SecretRef로 관리되는 경우, daemon 설치는 이를 검증하지만 확인된 평문 token 값을 supervisor 서비스 환경 메타데이터에 유지하지 않습니다.
- token 인증에 token이 필요하고 구성된 token SecretRef를 확인할 수 없는 경우, daemon 설치는 실행 가능한 안내와 함께 차단됩니다.
- `gateway.auth.token`과 `gateway.auth.password`가 모두 구성되어 있고 `gateway.auth.mode`가 설정되지 않은 경우, mode를 명시적으로 설정할 때까지 daemon 설치가 차단됩니다.
</Step>
<Step title="상태 점검">
- 필요하면 Gateway를 시작하고 `openclaw health`를 실행합니다.
- 팁: `openclaw status --deep`는 상태 출력에 라이브 gateway 상태 probe를 추가하며, 지원되는 경우 채널 probe도 포함합니다(reachable gateway 필요).
- 팁: `openclaw status --deep`는 상태 출력에 실시간 gateway 상태 프로브를 추가하며, 지원되는 경우 채널 프로브도 포함합니다(도달 가능한 gateway 필요).
</Step>
<Step title="Skills (권장)">
- 사용 가능한 Skills를 읽고 요구 사항을 확인합니다.
- 노드 매니저를 선택할 수 있습니다: **npm / pnpm** (bun은 권장되지 않음).
- 선택적 의존성을 설치합니다(일부는 macOS에서 Homebrew 사용).
- 노드 관리자 **npm / pnpm**을 선택하게 합니다(bun은 권장되지 않음).
- 선택적 종속성을 설치합니다(일부는 macOS에서 Homebrew 사용).
</Step>
<Step title="완료">
- 추가 기능용 iOS/Android/macOS 앱을 포함한 요약 + 다음 단계가 표시됩니다.
- 추가 기능을 위한 iOS/Android/macOS 앱을 포함해 요약과 다음 단계를 표시합니다.
</Step>
</Steps>
<Note>
GUI가 감지되지 않으면, 온보딩은 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 안내를 출력합니다.
Control UI 에셋이 없으면, 온보딩은 이를 빌드하려고 시도하며 폴백은 `pnpm ui:build`입니다(UI 의존성을 자동 설치).
GUI가 감지되지 않으면, 온보딩은 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 지침을 출력합니다.
Control UI 자산이 없으면 온보딩이 이를 빌드하려 시도하며, 대체 방법은 `pnpm ui:build`입니다(UI 종속성 자동 설치).
</Note>
## 비대화형 모드
온보딩을 자동화하거나 스크립트화하려면 `--non-interactive`를 사용하세요:
온보딩을 자동화하거나 스크립트로 실행하려면 `--non-interactive`를 사용하세요:
```bash
openclaw onboard --non-interactive \
@ -165,7 +164,7 @@ openclaw onboard --non-interactive \
기계가 읽을 수 있는 요약을 원하면 `--json`을 추가하세요.
비대화형 모드에서의 Gateway 토큰 SecretRef:
비대화형 모드에서의 Gateway token SecretRef:
```bash
export OPENCLAW_GATEWAY_TOKEN="your-token"
@ -179,13 +178,13 @@ openclaw onboard --non-interactive \
`--gateway-token`과 `--gateway-token-ref-env`는 함께 사용할 수 없습니다.
<Note>
`--json`은 **비대화형 모드**를 의미하지 않습니다. 스크립트에서는 `--non-interactive`(및 `--workspace`)를 사용하세요.
`--json`은 비대화형 모드를 의미하지 않습니다. 스크립트에서는 `--non-interactive`(및 `--workspace`)를 사용하세요.
</Note>
provider별 명령 예시는 [CLI 자동화](/ko/start/wizard-cli-automation#provider-specific-examples)에 있습니다.
이 참조 페이지는 플래그 의미와 단계 순서를 확인할 때 사용하세요.
제공자별 명령 예시는 [CLI 자동화](/ko/start/wizard-cli-automation#provider-specific-examples)에 있습니다.
플래그 의미와 단계 순서는 이 참조 페이지를 사용하세요.
### 에이전트 추가(비대화형)
### 에이전트 추가 (비대화형)
```bash
openclaw agents add work \
@ -196,23 +195,23 @@ openclaw agents add work \
--json
```
## Gateway 마법사 RPC
## Gateway wizard RPC
Gateway는 RPC를 통해 온보딩 흐름을 노출합니다(`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
Gateway는 RPC(`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`)를 통해 온보딩 흐름을 노출합니다.
클라이언트(macOS 앱, Control UI)는 온보딩 로직을 다시 구현하지 않고도 단계를 렌더링할 수 있습니다.
## Signal 설정(signal-cli)
## Signal 설정 (signal-cli)
온보딩은 GitHub 릴리스에서 `signal-cli`를 설치할 수 있습니다:
- 적절한 릴리스 에셋을 다운로드합니다.
- 적절한 릴리스 자산을 다운로드합니다.
- 이를 `~/.openclaw/tools/signal-cli/<version>/` 아래에 저장합니다.
- config에 `channels.signal.cliPath`를 기록합니다.
참고:
- JVM 빌드에는 **Java 21**이 필요합니다.
- 사용 가능한 경우 네이티브 빌드를 사용합니다.
- 가능한 경우 네이티브 빌드가 사용됩니다.
- Windows는 WSL2를 사용하며, signal-cli 설치는 WSL 내부에서 Linux 흐름을 따릅니다.
## 마법사가 기록하는 내용
@ -220,15 +219,15 @@ Gateway는 RPC를 통해 온보딩 흐름을 노출합니다(`wizard.start`, `wi
`~/.openclaw/openclaw.json`의 일반적인 필드:
- `agents.defaults.workspace`
- `agents.defaults.model` / `models.providers` (Minimax를 선택한 경우)
- `tools.profile` (로컬 온보딩은 설정되지 않은 경우 기본값으로 `"coding"`을 사용하며, 기존의 명시적 값은 유지됨)
- `agents.defaults.model` / `models.providers` (MiniMax를 선택한 경우)
- `tools.profile` (local 온보딩은 설정되지 않은 경우 기본값으로 `"coding"`을 사용하며, 기존에 명시된 값은 유지됩니다)
- `gateway.*` (mode, bind, auth, tailscale)
- `session.dmScope` (동작 세부 정보: [CLI 설정 참조](/ko/start/wizard-cli-reference#outputs-and-internals))
- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
- 프롬프트 중에 선택하는 경우 채널 allowlist(Slack/Discord/Matrix/Microsoft Teams) - 가능하면 이름이 ID로 확인됩니다.
- 프롬프트에서 선택하면 채널 허용 목록(Slack/Discord/Matrix/Microsoft Teams)도 기록됩니다(가능하면 이름이 ID로 확인됩니다).
- `skills.install.nodeManager`
- `setup --node-manager`는 `npm`, `pnpm`, `bun`을 허용합니다.
- 수동 config는 `skills.install.nodeManager`를 직접 설정하여 여전히 `yarn`을 사용할 수 있습니다.
- `setup --node-manager`는 `npm`, `pnpm`, `bun`을 받습니다.
- 수동 config에서는 `skills.install.nodeManager`를 직접 설정하여 여전히 `yarn`을 사용할 수 있습니다.
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
@ -240,13 +239,12 @@ Gateway는 RPC를 통해 온보딩 흐름을 노출합니다(`wizard.start`, `wi
WhatsApp 자격 증명은 `~/.openclaw/credentials/whatsapp/<accountId>/` 아래에 저장됩니다.
세션은 `~/.openclaw/agents/<agentId>/sessions/` 아래에 저장됩니다.
일부 채널은 plugin으로 제공됩니다. 설정 중 하나를 선택하면, 온보딩은
구성하기 전에 해당 plugin을 설치하도록(npm 또는 로컬 경로) 안내합니다.
일부 채널은 Plugin으로 제공됩니다. 설정 중 하나를 선택하면, 온보딩은 이를 구성하기 전에 설치할 수 있도록 `npm` 또는 로컬 경로를 사용한 설치를 안내합니다.
## 관련 문서
- 온보딩 개요: [온보딩(CLI)](/ko/start/wizard)
- 온보딩 개요: [온보딩 (CLI)](/ko/start/wizard)
- macOS 앱 온보딩: [온보딩](/ko/start/onboarding)
- Config 참조: [Gateway configuration](/ko/gateway/configuration)
- Providers: [WhatsApp](/ko/channels/whatsapp), [Telegram](/ko/channels/telegram), [Discord](/ko/channels/discord), [Google Chat](/ko/channels/googlechat), [Signal](/ko/channels/signal), [BlueBubbles](/ko/channels/bluebubbles) (iMessage), [iMessage](/ko/channels/imessage) (레거시)
- config 참조: [Gateway 구성](/ko/gateway/configuration)
- 제공자: [WhatsApp](/ko/channels/whatsapp), [Telegram](/ko/channels/telegram), [Discord](/ko/channels/discord), [Google Chat](/ko/channels/googlechat), [Signal](/ko/channels/signal), [BlueBubbles](/ko/channels/bluebubbles) (iMessage), [iMessage](/ko/channels/imessage) (레거시)
- Skills: [Skills](/ko/tools/skills), [Skills config](/ko/tools/skills-config)

251
docs/ko/start/wizard-cli-reference.md
View File

@ -1,116 +1,116 @@
---
read_when:
- '`openclaw onboard`의 자세한 동작이 필요한 경우'
- 온보딩 결과를 디버깅하거나 온보딩 클라이언트를 통합하는 경우
- '`openclaw onboard`의 자세한 동작이 필요합니다'
- 온보딩 결과를 디버그하거나 온보딩 클라이언트를 통합하고 있습니다
sidebarTitle: CLI reference
summary: CLI 설정 흐름, auth/모델 설정, 출력, 내부 동작에 대한 전체 참조
summary: CLI 설정 흐름, 인증/모델 설정, 출력 및 내부 동작에 대한 완전한 참조
title: CLI 설정 참조
x-i18n:
generated_at: "2026-04-06T03:12:49Z"
generated_at: "2026-04-15T14:41:06Z"
model: gpt-5.4
provider: openai
source_hash: 92f379b34a2b48c68335dae4f759117c770f018ec51b275f4f40421c6b3abb23
source_hash: 61ca679caca3b43fa02388294007f89db22d343e49e10b61d8d118cd8fbb7369
source_path: start/wizard-cli-reference.md
workflow: 15
---
# CLI 설정 참조
이 페이지는 `openclaw onboard`의 전체 참조입니다.
짧은 가이드는 [Onboarding (CLI)](/ko/start/wizard)를 참조하세요.
이 페이지는 `openclaw onboard`의 전체 참조 문서입니다.
짧은 안내는 [온보딩 (CLI)](/ko/start/wizard)를 참고하세요.
## 마법사가 하는 일
## 마법사가 수행하는 작업
로컬 모드(기본값)는 다음 과정을 안내합니다:
로컬 모드(기본값)는 다음 항목을 안내합니다.
- 모델 및 auth 설정(OpenAI Code 구독 OAuth, Anthropic Claude CLI 또는 API 키, 그리고 MiniMax, GLM, Ollama, Moonshot, StepFun, AI Gateway 옵션)
- 워크스페이스 위치 및 bootstrap 파일
- Gateway 설정(포트, bind, auth, Tailscale)
- 채널 및 provider(Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles, 기타 번들 채널 plugin)
- 데몬 설치(LaunchAgent, systemd 사용자 유닛, 또는 Startup 폴더 폴백이 있는 네이티브 Windows Scheduled Task)
- 모델 및 인증 설정(OpenAI Code 구독 OAuth, Anthropic Claude CLI 또는 API 키, 그리고 MiniMax, GLM, Ollama, Moonshot, StepFun, AI Gateway 옵션)
- 워크스페이스 위치 및 부트스트랩 파일
- Gateway 설정(포트, 바인드, 인증, Tailscale)
- 채널 및 제공자(Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles 및 기타 번들 채널 Plugin)
- 데몬 설치(LaunchAgent, systemd 사용자 유닛 또는 기본 Windows Scheduled Task와 Startup 폴더 대체 경로)
- 상태 점검
- Skills 설정
원격 모드는 이 컴퓨터가 다른 위치의 gateway에 연결되도록 구성합니다.
원격 호스트에는 아무것도 설치하거나 수정하지 않습니다.
## 로컬 흐름 세부 사항
## 로컬 흐름 세부사항
<Steps>
<Step title="기존 config 감지">
- `~/.openclaw/openclaw.json`이 있으면 유지, 수정, 또는 재설정을 선택합니다.
- 마법사를 다시 실행해도 명시적으로 재설정을 선택하지 않는 한(또는 `--reset`을 전달하지 않는 한) 아무것도 지워지지 않습니다.
- CLI `--reset`의 기본값은 `config+creds+sessions`이며, 워크스페이스도 제거하려면 `--reset-scope full`을 사용하세요.
- config가 유효하지 않거나 레거시 키를 포함하고 있으면, 마법사는 중단하고 계속하기 전에 `openclaw doctor`를 실행하라고 요청합니다.
- 재설정은 `trash`를 사용하며 다음 범위를 제공합니다:
- config만
- config + 자격 증명 + 세션
<Step title="기존 구성 감지">
- `~/.openclaw/openclaw.json`이 있으면 Keep, Modify 또는 Reset을 선택합니다.
- 마법사를 다시 실행해도 명시적으로 Reset을 선택하지 않는 한(또는 `--reset`을 전달하지 않는 한) 아무것도 지워지지 않습니다.
- CLI `--reset`의 기본값은 `config+creds+sessions`이며, 워크스페이스까지 제거하려면 `--reset-scope full`을 사용하세요.
- 구성이 유효하지 않거나 레거시 키를 포함하면, 마법사는 중단하고 계속하기 전에 `openclaw doctor`를 실행하라고 요청합니다.
- Reset은 `trash`를 사용하며 다음 범위를 제공합니다.
- 구성만
- 구성 + 자격 증명 + 세션
- 전체 재설정(워크스페이스도 제거)
</Step>
<Step title="모델 및 auth">
- 전체 옵션 매트릭스는 [Auth and model options](#auth-and-model-options)에 있습니다.
<Step title="모델 및 인증">
- 전체 옵션 매트릭스는 [인증 및 모델 옵션](#auth-and-model-options)에 있습니다.
</Step>
<Step title="워크스페이스">
- 기본값은 `~/.openclaw/workspace`입니다(변경 가능).
- 최초 실행 bootstrap ritual에 필요한 워크스페이스 파일을 시드합니다.
- 워크스페이스 레이아웃: [Agent workspace](/ko/concepts/agent-workspace).
- 기본값은 `~/.openclaw/workspace`입니다(구성 가능).
- 첫 실행 부트스트랩 의식에 필요한 워크스페이스 파일을 시드합니다.
- 워크스페이스 레이아웃: [에이전트 워크스페이스](/ko/concepts/agent-workspace).
</Step>
<Step title="Gateway">
- 포트, bind, auth 모드, Tailscale 노출 여부를 묻습니다.
- 권장 사항: loopback에서도 토큰 auth를 활성화해 로컬 WS 클라이언트가 인증하도록 유지하세요.
- 토큰 모드에서 대화형 설정은 다음을 제공합니다:
- 포트, 바인드, 인증 모드, Tailscale 노출 여부를 묻습니다.
- 권장 사항: 로컬 WS 클라이언트도 인증해야 하므로 loopback만 사용하더라도 토큰 인증을 활성화한 상태로 유지하세요.
- 토큰 모드에서 대화형 설정은 다음을 제공합니다.
- **일반 텍스트 토큰 생성/저장** (기본값)
- **SecretRef 사용** (옵트인)
- 비밀번호 모드에서도 대화형 설정은 일반 텍스트 또는 SecretRef 저장을 지원합니다.
- 비대화형 토큰 SecretRef 경로: `--gateway-token-ref-env <ENV_VAR>`.
- 온보딩 프로세스 환경에 비어 있지 않은 env var가 필요합니다.
- 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다.
- `--gateway-token`과 함께 사용할 수 없습니다.
- 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 auth를 비활성화하세요.
- loopback이 아닌 bind에도 여전히 auth가 필요합니다.
- 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하세요.
- loopback이 아닌 바인드도 여전히 인증이 필요합니다.
</Step>
<Step title="채널">
- [WhatsApp](/ko/channels/whatsapp): 선택적 QR 로그인
- [Telegram](/ko/channels/telegram): 봇 토큰
- [Discord](/ko/channels/discord): 봇 토큰
- [Google Chat](/ko/channels/googlechat): 서비스 계정 JSON + webhook audience
- [Google Chat](/ko/channels/googlechat): 서비스 계정 JSON + Webhook audience
- [Mattermost](/ko/channels/mattermost): 봇 토큰 + 기본 URL
- [Signal](/ko/channels/signal): 선택적 `signal-cli` 설치 + 계정 config
- [BlueBubbles](/ko/channels/bluebubbles): iMessage에 권장; 서버 URL + 비밀번호 + webhook
- [Signal](/ko/channels/signal): 선택적 `signal-cli` 설치 + 계정 구성
- [BlueBubbles](/ko/channels/bluebubbles): iMessage에 권장; 서버 URL + 비밀번호 + Webhook
- [iMessage](/ko/channels/imessage): 레거시 `imsg` CLI 경로 + DB 접근
- DM 보안: 기본값은 페어링입니다. 첫 DM은 코드를 보내며,
- DM 보안: 기본값은 페어링입니다. 첫 DM은 코드를 전송하며,
`openclaw pairing approve <channel> <code>`로 승인하거나 allowlist를 사용할 수 있습니다.
</Step>
<Step title="데몬 설치">
- macOS: LaunchAgent
- 로그인된 사용자 세션이 필요합니다. headless 환경에서는 커스텀 LaunchDaemon을 사용하세요(기본 제공되지 않음).
- 로그인된 사용자 세션이 필요합니다. 헤드리스 환경에서는 사용자 지정 LaunchDaemon을 사용하세요(기본 제공되지 않음).
- Linux 및 WSL2를 통한 Windows: systemd 사용자 유닛
- 마법사는 로그아웃 후에도 gateway가 유지되도록 `loginctl enable-linger <user>`를 시도합니다.
- 마법사는 로그아웃 후에도 gateway가 계속 실행되도록 `loginctl enable-linger <user>`를 시도합니다.
- sudo를 요청할 수 있습니다(`/var/lib/systemd/linger`에 기록). 먼저 sudo 없이 시도합니다.
- 네이티브 Windows: 우선 Scheduled Task
- 태스크 생성이 거부되면 OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 폴백하고 gateway를 즉시 시작합니다.
- Scheduled Task는 더 나은 supervisor 상태를 제공하므로 여전히 우선 방식입니다.
- 런타임 선택: Node(권장; WhatsApp과 Telegram에 필요). Bun은 권장되지 않습니다.
- 기본 Windows: 먼저 Scheduled Task
- 작업 생성이 거부되면, OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 대체하고 gateway를 즉시 시작합니다.
- Scheduled Task는 더 나은 supervisor 상태를 제공하므로 여전히 선호됩니다.
- 런타임 선택: Node(권장, WhatsApp 및 Telegram에 필요). Bun은 권장되지 않습니다.
</Step>
<Step title="상태 점검">
- 필요하면 gateway를 시작하고 `openclaw health`를 실행합니다.
- `openclaw status --deep`는 지원되는 경우 채널 프로브를 포함해 라이브 gateway 상태 프로브를 상태 출력에 추가합니다.
- `openclaw status --deep`는 지원되는 경우 채널 프로브를 포함한 라이브 gateway 상태 프로브를 상태 출력에 추가합니다.
</Step>
<Step title="Skills">
- 사용 가능한 Skills를 읽고 요구 사항을 확인합니다.
- node manager로 npm, pnpm, 또는 bun을 선택할 수 있습니다.
- 노드 관리자로 npm, pnpm 또는 bun을 선택할 수 있습니다.
- 선택적 의존성을 설치합니다(일부는 macOS에서 Homebrew 사용).
</Step>
<Step title="완료">
- iOS, Android, macOS 앱 옵션을 포함한 요약 및 다음 단계가 표시됩니다.
<Step title="마무리">
- 요약 및 다음 단계(iOS, Android, macOS 앱 옵션 포함)를 제공합니다.
</Step>
</Steps>
<Note>
GUI가 감지되지 않으면 마법사는 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 안내를 출력합니다.
Control UI 자산이 없으면 마법사는 이를 빌드하려고 시도하며, 폴백은 `pnpm ui:build`입니다(UI 의존성 자동 설치).
GUI가 감지되지 않으면, 마법사는 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 지침을 출력합니다.
Control UI 자산이 없으면, 마법사는 이를 빌드하려고 시도합니다. 대체 경로는 `pnpm ui:build`이며(UI 의존성을 자동 설치함)입니다.
</Note>
## 원격 모드 세부 사항
## 원격 모드 세부사항
원격 모드는 이 컴퓨터가 다른 위치의 gateway에 연결되도록 구성합니다.
@ -121,145 +121,146 @@ Control UI 자산이 없으면 마법사는 이를 빌드하려고 시도하며,
설정하는 항목:
- 원격 gateway URL (`ws://...`)
- 원격 gateway auth가 필요한 경우 토큰(권장)
- 원격 gateway 인증이 필요한 경우 토큰(권장)
<Note>
- gateway가 loopback 전용이면 SSH 터널링 또는 tailnet을 사용하세요.
- 탐지 힌트:
- 검색 힌트:
- macOS: Bonjour (`dns-sd`)
- Linux: Avahi (`avahi-browse`)
</Note>
## Auth and model options
## 인증 및 모델 옵션
<AccordionGroup>
<Accordion title="Anthropic API 키">
있으면 `ANTHROPIC_API_KEY`를 사용하고, 없으면 키를 입력받은 뒤 데몬에서 사용할 수 있도록 저장합니다.
`ANTHROPIC_API_KEY`가 있으면 이를 사용하고, 없으면 키를 요청한 뒤 데몬에서 사용할 수 있도록 저장합니다.
</Accordion>
<Accordion title="OpenAI Code 구독(Codex CLI 재사용)">
`~/.codex/auth.json`이 있으면 마법사가 이를 재사용할 수 있습니다.
재사용된 Codex CLI 자격 증명은 계속 Codex CLI가 관리합니다. 만료되면 OpenClaw는
먼저 해당 소스를 다시 읽고, provider가 이를 갱신할 수 있으면
소유권을 가져오는 대신 갱신된 자격 증명을 다시 Codex 저장소에 기록합니다.
먼저 해당 소스를 다시 읽고, 제공자가 이를 갱신할 수 있으면
자격 증명의 소유권을 가져오지 않고 갱신된 자격 증명을 다시 Codex 저장소에 기록합니다.
</Accordion>
<Accordion title="OpenAI Code 구독(OAuth)">
브라우저 흐름; `code#state`를 붙여 넣습니다.
브라우저 흐름이며 `code#state`를 붙여 넣습니다.
모델이 설정되지 않았거나 `openai/*`인 경우 `agents.defaults.model`을 `openai-codex/gpt-5.4`로 설정합니다.
</Accordion>
<Accordion title="OpenAI API 키">
있으면 `OPENAI_API_KEY`를 사용하고, 없으면 키를 입력받은 뒤 자격 증명을 auth 프로필에 저장합니다.
`OPENAI_API_KEY`가 있으면 이를 사용하고, 없으면 키를 요청한 뒤 자격 증명을 auth profile에 저장합니다.
모델이 설정되지 않았거나 `openai/*`, `openai-codex/*`인 경우 `agents.defaults.model`을 `openai/gpt-5.4`로 설정합니다.
모델이 설정되지 않았거나 `openai/*` 또는 `openai-codex/*`인 경우 `agents.defaults.model`을 `openai/gpt-5.4`로 설정합니다.
</Accordion>
<Accordion title="xAI (Grok) API 키">
`XAI_API_KEY`를 입력받고 xAI를 모델 provider로 구성합니다.
`XAI_API_KEY`를 요청하고 xAI를 모델 제공자로 구성합니다.
</Accordion>
<Accordion title="OpenCode">
`OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`)를 입력받고 Zen 또는 Go 카탈로그를 선택하게 합니다.
`OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`)를 요청하고 Zen 또는 Go 카탈로그를 선택하게 합니다.
설정 URL: [opencode.ai/auth](https://opencode.ai/auth).
</Accordion>
<Accordion title="API 키(일반)">
키를 대신 저장합니다.
</Accordion>
<Accordion title="Vercel AI Gateway">
`AI_GATEWAY_API_KEY`를 입력받습니다.
`AI_GATEWAY_API_KEY`를 요청합니다.
자세한 내용: [Vercel AI Gateway](/ko/providers/vercel-ai-gateway).
</Accordion>
<Accordion title="Cloudflare AI Gateway">
account ID, gateway ID, `CLOUDFLARE_AI_GATEWAY_API_KEY`를 입력받습니다.
계정 ID, gateway ID, `CLOUDFLARE_AI_GATEWAY_API_KEY`를 요청합니다.
자세한 내용: [Cloudflare AI Gateway](/ko/providers/cloudflare-ai-gateway).
</Accordion>
<Accordion title="MiniMax">
config가 자동으로 기록됩니다. 호스팅 기본값은 `MiniMax-M2.7`입니다. API 키 설정은
`minimax/...`를 사용하고, OAuth 설정은 `minimax-portal/...`를 사용합니다.
구성이 자동으로 기록됩니다. 호스팅 기본값은 `MiniMax-M2.7`이며, API 키 설정은
`minimax/...`를 사용하고 OAuth 설정은 `minimax-portal/...`을 사용합니다.
자세한 내용: [MiniMax](/ko/providers/minimax).
</Accordion>
<Accordion title="StepFun">
중국 또는 글로벌 엔드포인트의 StepFun standard 또는 Step Plan용 config가 자동으로 기록됩니다.
중국 또는 글로벌 엔드포인트의 StepFun standard 또는 Step Plan에 맞게 구성이 자동으로 기록됩니다.
Standard에는 현재 `step-3.5-flash`가 포함되며, Step Plan에는 `step-3.5-flash-2603`도 포함됩니다.
자세한 내용: [StepFun](/ko/providers/stepfun).
</Accordion>
<Accordion title="Synthetic (Anthropic 호환)">
`SYNTHETIC_API_KEY`를 입력받습니다.
`SYNTHETIC_API_KEY`를 요청합니다.
자세한 내용: [Synthetic](/ko/providers/synthetic).
</Accordion>
<Accordion title="Ollama (클라우드 및 로컬 오픈 모델)">
기본 URL(기본값 `http://127.0.0.1:11434`)을 입력받은 다음 Cloud + Local 또는 Local 모드를 제안합니다.
사용 가능한 모델을 탐지하고 기본값을 제안합니다.
<Accordion title="Ollama (Cloud 및 로컬 오픈 모델)">
먼저 `Cloud + Local`, `Cloud only`, `Local only`를 묻습니다.
`Cloud only`는 `OLLAMA_API_KEY`와 `https://ollama.com`을 사용합니다.
호스트 기반 모드는 기본 URL(기본값 `http://127.0.0.1:11434`)을 요청하고, 사용 가능한 모델을 검색하며, 기본값을 제안합니다.
`Cloud + Local`은 해당 Ollama 호스트가 cloud 액세스를 위해 로그인되어 있는지도 확인합니다.
자세한 내용: [Ollama](/ko/providers/ollama).
</Accordion>
<Accordion title="Moonshot 및 Kimi Coding">
Moonshot(Kimi K2) 및 Kimi Coding config가 자동으로 기록됩니다.
Moonshot (Kimi K2) 및 Kimi Coding 구성은 자동으로 기록됩니다.
자세한 내용: [Moonshot AI (Kimi + Kimi Coding)](/ko/providers/moonshot).
</Accordion>
<Accordion title="커스텀 provider">
OpenAI 호환 및 Anthropic 호환 엔드포인트와 동작합니다.
<Accordion title="사용자 지정 제공자">
OpenAI 호환 및 Anthropic 호환 엔드포인트와 함께 작동합니다.
대화형 온보딩은 다른 provider API 키 흐름과 동일한 API 키 저장 옵션을 지원합니다:
대화형 온보딩은 다른 제공자 API 키 흐름과 동일한 API 키 저장 선택지를 지원합니다.
- **지금 API 키 붙여넣기** (일반 텍스트)
- **secret reference 사용** (env ref 또는 구성된 provider ref, 사전 검증 포함)
- **시크릿 참조 사용** (환경 변수 ref 또는 구성된 provider ref, 사전 검증 포함)
비대화형 플래그:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (선택 사항; `CUSTOM_API_KEY`로 폴백)
- `--custom-api-key` (선택 사항, 없으면 `CUSTOM_API_KEY` 사용)
- `--custom-provider-id` (선택 사항)
- `--custom-compatibility <openai|anthropic>` (선택 사항; 기본값 `openai`)
- `--custom-compatibility <openai|anthropic>` (선택 사항, 기본값 `openai`)
</Accordion>
<Accordion title="건너뛰기">
auth를 구성하지 않은 상태로 둡니다.
인증을 구성하지 않은 상태로 둡니다.
</Accordion>
</AccordionGroup>
모델 동작:
- 탐지된 옵션에서 기본 모델을 선택하거나, provider와 모델을 수동으로 입력합니다.
- 온보딩이 provider auth 선택에서 시작되면 모델 선택기는
해당 provider를 자동으로 우선 적용합니다. Volcengine과 BytePlus의 경우 이 우선순위는
- 감지된 옵션에서 기본 모델을 선택하거나, 제공자와 모델을 수동으로 입력합니다.
- 온보딩이 제공자 인증 선택에서 시작되면, 모델 선택기는
해당 제공자를 자동으로 우선시합니다. Volcengine 및 BytePlus의 경우, 동일한 우선순위가
해당 coding-plan 변형(`volcengine-plan/*`,
`byteplus-plan/*`)과도 일치합니다.
- 해당 선호 provider 필터 결과가 비어 있으면, 선택기는 모델이 없다고 표시하는 대신
전체 카탈로그로 폴백합니다.
- 마법사는 모델 검사를 실행하고 구성된 모델을 알 수 없거나 auth가 없으면 경고합니다.
`byteplus-plan/*`)에도 적용됩니다.
- 이 기본 제공자 필터의 결과가 비어 있으면,
모델을 하나도 표시하지 않는 대신 전체 카탈로그로 대체합니다.
- 마법사는 모델 검사를 실행하고 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고합니다.
자격 증명 및 프로필 경로:
자격 증명 및 profile 경로:
- Auth 프로필(API 키 + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 레거시 OAuth import: `~/.openclaw/credentials/oauth.json`
- Auth profile(API 키 + OAuth): `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 레거시 OAuth 가져오기: `~/.openclaw/credentials/oauth.json`
자격 증명 저장 모드:
- 기본 온보딩 동작은 API 키를 auth 프로필에 일반 텍스트 값으로 저장합니다.
- `--secret-input-mode ref`는 일반 텍스트 키 저장 대신 reference 모드를 활성화합니다.
대화형 설정에서는 다음 중 하나를 선택할 수 있습니다:
- 기본 온보딩 동작은 API 키를 auth profile에 일반 텍스트 값으로 저장합니다.
- `--secret-input-mode ref`는 일반 텍스트 키 저장 대신 참조 모드를 활성화합니다.
대화형 설정에서는 다음 중 하나를 선택할 수 있습니다.
- 환경 변수 ref(예: `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`)
- provider 별칭 + id를 사용하는 구성된 provider ref(`file` 또는 `exec`)
- 대화형 reference 모드는 저장 전에 빠른 사전 검증을 실행합니다.
- Env ref: 현재 온보딩 환경에서 변수 이름과 비어 있지 않은 값을 검증합니다.
- Provider ref: provider config를 검증하고 요청된 id를 해석합니다.
- 사전 검증이 실패하면 온보딩이 오류를 보여 주고 다시 시도할 수 있게 합니다.
- 구성된 provider ref(`file` 또는 `exec`)와 provider 별칭 + id
- 대화형 참조 모드는 저장 전에 빠른 사전 검증을 실행합니다.
- Env ref: 변수 이름과 현재 온보딩 환경에서 비어 있지 않은 값을 검증합니다.
- Provider ref: provider 구성을 검증하고 요청한 id를 확인합니다.
- 사전 검증이 실패하면 온보딩은 오류를 표시하고 다시 시도할 수 있게 합니다.
- 비대화형 모드에서 `--secret-input-mode ref`는 env 기반만 지원합니다.
- provider env var를 온보딩 프로세스 환경에 설정하세요.
- 인라인 키 플래그(예: `--openai-api-key`)는 해당 env var가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
- 커스텀 provider의 경우 비대화형 `ref` 모드는 `models.providers.<id>.apiKey`를 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`로 저장합니다.
- 이 커스텀 provider 경우 `--custom-api-key`는 `CUSTOM_API_KEY`가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
- Gateway auth 자격 증명은 대화형 설정에서 일반 텍스트와 SecretRef 선택을 지원합니다:
- 토큰 모드: **일반 텍스트 토큰 생성/저장**(기본값) 또는 **SecretRef 사용**.
- 온보딩 프로세스 환경에 provider 환경 변수를 설정하세요.
- 인라인 키 플래그(예: `--openai-api-key`)는 해당 환경 변수가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
- 사용자 지정 제공자의 경우 비대화형 `ref` 모드는 `models.providers.<id>.apiKey`를 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`로 저장합니다.
- 이 사용자 지정 제공자 경우에는 `--custom-api-key`를 사용하려면 `CUSTOM_API_KEY`가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다.
- Gateway 인증 자격 증명은 대화형 설정에서 일반 텍스트와 SecretRef 선택을 모두 지원합니다.
- 토큰 모드: **일반 텍스트 토큰 생성/저장** (기본값) 또는 **SecretRef 사용**.
- 비밀번호 모드: 일반 텍스트 또는 SecretRef.
- 비대화형 토큰 SecretRef 경로: `--gateway-token-ref-env <ENV_VAR>`.
- 기존 일반 텍스트 설정은 변경 없이 계속 동작합니다.
- 기존 일반 텍스트 설정은 변경 없이 계속 작동합니다.
<Note>
헤드리스 및 서버 팁: 브라우저가 있는 컴퓨터에서 OAuth를 완료한 다음
해당 에이전트의 `auth-profiles.json`(예:
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`, 또는 해당하는
헤드리스 및 서버 팁: 브라우저가 있는 컴퓨터에서 OAuth를 완료한 다음, 해당 에이전트의 `auth-profiles.json`(예:
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` 또는 일치하는
`$OPENCLAW_STATE_DIR/...` 경로)을 gateway 호스트로 복사하세요. `credentials/oauth.json`은
레거시 import 소스일 뿐입니다.
레거시 가져오기 소스일 뿐입니다.
</Note>
## 출력 및 내부 동작
@ -268,28 +269,28 @@ Control UI 자산이 없으면 마법사는 이를 빌드하려고 시도하며,
- `agents.defaults.workspace`
- `agents.defaults.model` / `models.providers` (MiniMax를 선택한 경우)
- `tools.profile` (로컬 온보딩은 설정되지 않은 경우 기본값으로 `"coding"`을 사용하며, 기존 명시적 값은 유지됩니다)
- `tools.profile` (로컬 온보딩은 설정되지 않은 경우 기본값으로 `"coding"`을 사용하며, 기존의 명시적 값은 유지됨)
- `gateway.*` (mode, bind, auth, Tailscale)
- `session.dmScope` (로컬 온보딩은 설정되지 않은 경우 기본값으로 `per-channel-peer`를 사용하며, 기존 명시적 값은 유지됩니다)
- `session.dmScope` (로컬 온보딩은 설정되지 않은 경우 기본값으로 `per-channel-peer`를 사용하며, 기존의 명시적 값은 유지됨)
- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
- 프롬프트 중 옵트인하면 채널 allowlist(Slack, Discord, Matrix, Microsoft Teams)도 포함됩니다(가능하면 이름을 ID로 해석)
- 프롬프트 중 옵트인한 경우의 채널 allowlist(Slack, Discord, Matrix, Microsoft Teams) (가능하면 이름을 ID로 확인)
- `skills.install.nodeManager`
- `setup --node-manager` 플래그는 `npm`, `pnpm`, 또는 `bun`을 허용합니다.
- 수동 config에서는 나중에 `skills.install.nodeManager: "yarn"`도 설정할 수 있습니다.
- `setup --node-manager` 플래그는 `npm`, `pnpm`, `bun`을 허용합니다.
- 수동 구성에서는 나중에 `skills.install.nodeManager: "yarn"`도 설정할 수 있습니다.
- `wizard.lastRunAt`
- `wizard.lastRunVersion`
- `wizard.lastRunCommit`
- `wizard.lastRunCommand`
- `wizard.lastRunMode`
`openclaw agents add`는 `agents.list[]` 및 선택적 `bindings`를 기록합니다.
`openclaw agents add`는 `agents.list[]`와 선택적 `bindings`를 기록합니다.
WhatsApp 자격 증명은 `~/.openclaw/credentials/whatsapp/<accountId>/` 아래에 저장됩니다.
세션은 `~/.openclaw/agents/<agentId>/sessions/` 아래에 저장됩니다.
<Note>
일부 채널은 plugin으로 제공됩니다. 설정 중 선택하면 마법사는
채널 구성을 진행하기 전에 plugin 설치(npm 또는 로컬 경로)를 묻습니다.
일부 채널은 Plugin으로 제공됩니다. 설정 중 선택하면 마법사는
채널 구성을 시작하기 전에 Plugin 설치(npm 또는 로컬 경로)를 묻습니다.
</Note>
Gateway 마법사 RPC:
@ -303,15 +304,15 @@ Gateway 마법사 RPC:
Signal 설정 동작:
- 적절한 릴리스 자산을 다운로드
- `~/.openclaw/tools/signal-cli/<version>/` 아래에 저장
- config에 `channels.signal.cliPath` 기록
- JVM 빌드는 Java 21이 필요
- 가능하면 네이티브 빌드를 사용
- Windows는 WSL2를 사용하며 WSL 내부에서 Linux signal-cli 흐름을 따름
- 적절한 릴리스 자산을 다운로드합니다
- 이를 `~/.openclaw/tools/signal-cli/<version>/` 아래에 저장합니다
- 구성에 `channels.signal.cliPath`를 기록합니다
- JVM 빌드에는 Java 21이 필요합니다
- 사용 가능한 경우 네이티브 빌드가 사용됩니다
- Windows는 WSL2를 사용하며 WSL 내부에서 Linux `signal-cli` 흐름을 따릅니다
## 관련 문서
- 온보딩 허브: [Onboarding (CLI)](/ko/start/wizard)
- 자동화 및 스크립트: [CLI Automation](/ko/start/wizard-cli-automation)
- 명령 참조: [`openclaw onboard`](/cli/onboard)
- 온보딩 허브: [온보딩 (CLI)](/ko/start/wizard)
- 자동화 및 스크립트: [CLI 자동화](/ko/start/wizard-cli-automation)
- 명령어 참조: [`openclaw onboard`](/cli/onboard)