From b95a4493deff2c68e86e9b8ef8e4a6c2ca2f076a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 15 Apr 2026 14:49:49 +0000 Subject: [PATCH] chore(i18n): refresh ko translations --- docs/ko/concepts/dreaming.md | 138 +- docs/ko/concepts/experimental-features.md | 44 + docs/ko/concepts/memory-search.md | 69 +- docs/ko/concepts/memory.md | 110 +- docs/ko/gateway/configuration-reference.md | 1500 ++++++++++---------- docs/ko/gateway/local-models.md | 68 +- docs/ko/help/testing.md | 952 +++++++------ docs/ko/providers/github-copilot.md | 110 +- docs/ko/providers/ollama.md | 196 +-- docs/ko/reference/memory-config.md | 345 +++-- docs/ko/reference/wizard.md | 194 ++- docs/ko/start/wizard-cli-reference.md | 251 ++-- 12 files changed, 2009 insertions(+), 1968 deletions(-) create mode 100644 docs/ko/concepts/experimental-features.md diff --git a/docs/ko/concepts/dreaming.md b/docs/ko/concepts/dreaming.md index 09519cbbd..61291326a 100644 --- a/docs/ko/concepts/dreaming.md +++ b/docs/ko/concepts/dreaming.md @@ -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//YYYY-MM-DD.md` 아래의 선택적 phase 보고서 파일. +- `memory/.dreams/`의 **머신 상태**(리콜 저장소, 단계 신호, 수집 체크포인트, 잠금) +- `DREAMS.md`(또는 기존 `dreams.md`)의 **사람이 읽을 수 있는 출력**, 그리고 선택적으로 `memory/dreaming//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) diff --git a/docs/ko/concepts/experimental-features.md b/docs/ko/concepts/experimental-features.md new file mode 100644 index 000000000..b19f628b3 --- /dev/null +++ b/docs/ko/concepts/experimental-features.md @@ -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 표면이 지저분해집니다. diff --git a/docs/ko/concepts/memory-search.md b/docs/ko/concepts/memory-search.md index 415bdc597..9b062f8b5 100644 --- a/docs/ko/concepts/memory-search.md +++ b/docs/ko/concepts/memory-search.md @@ -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` 같은 에버그린 파일은 감쇠되지 않습니다. -에이전트에 수개월치 일일 노트가 있고 오래된 정보가 최신 컨텍스트보다 계속 더 높은 순위에 오르면 시간 감쇠를 활성화하세요. +에이전트에 수개월치 일일 메모가 있고 오래된 정보가 최신 컨텍스트보다 계속 상위에 노출된다면 시간 감쇠를 활성화하세요. ### MMR(다양성) -중복되는 결과를 줄입니다. 다섯 개의 노트가 모두 같은 라우터 구성을 언급하더라도, MMR은 같은 내용을 반복하는 대신 상위 결과가 서로 다른 주제를 다루도록 합니다. +중복 결과를 줄입니다. 메모 5개가 모두 같은 라우터 설정을 언급하더라도, MMR은 상위 결과가 반복되지 않고 서로 다른 주제를 다루도록 보장합니다. -`memory_search`가 서로 다른 일일 노트에서 나온 거의 중복된 스니펫을 계속 반환하면 MMR을 활성화하세요. +`memory_search`가 서로 다른 일일 메모에서 거의 중복된 스니펫을 계속 반환한다면 MMR을 활성화하세요. ### 둘 다 활성화 @@ -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) -- 모든 구성 옵션 diff --git a/docs/ko/concepts/memory.md b/docs/ko/concepts/memory.md index d4c7dc1d8..68172ffd4 100644 --- a/docs/ko/concepts/memory.md +++ b/docs/ko/concepts/memory.md @@ -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`)에 있습니다. -에이전트가 무언가를 기억하길 원한다면, 그냥 이렇게 요청하면 됩니다: "내가 TypeScript를 선호한다고 기억해." 그러면 적절한 파일에 기록합니다. +에이전트가 무언가를 기억하길 원한다면, 이렇게 요청하면 됩니다: "내가 TypeScript를 선호한다고 기억해." 그러면 적절한 파일에 기록합니다. ## 메모리 도구 -에이전트에는 메모리를 다루기 위한 두 가지 도구가 있습니다. +에이전트에는 메모리를 다루기 위한 두 가지 도구가 있습니다: -- **`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 키만 있으면 별도 설정 없이 바로 동작합니다. -OpenClaw는 사용 가능한 API 키를 바탕으로 임베딩 제공자를 자동 감지합니다. OpenAI, Gemini, Voyage 또는 Mistral 키가 구성되어 있으면 메모리 검색이 자동으로 활성화됩니다. +OpenClaw는 사용 가능한 API 키를 바탕으로 임베딩 제공자를 자동 감지합니다. OpenAI, Gemini, Voyage, 또는 Mistral 키가 구성되어 있으면 메모리 검색이 자동으로 활성화됩니다. -검색 작동 방식, 튜닝 옵션, 제공자 설정에 대한 자세한 내용은 [Memory Search](/ko/concepts/memory-search)를 참조하세요. +검색 동작 방식, 튜닝 옵션, 제공자 설정에 대한 자세한 내용은 [Memory Search](/ko/concepts/memory-search)를 참조하세요. ## 메모리 백엔드 - -SQLite 기반입니다. 키워드 검색, 벡터 유사도, 하이브리드 검색을 즉시 사용할 수 있습니다. 추가 의존성이 필요 없습니다. + +SQLite 기반입니다. 키워드 검색, 벡터 유사도, 하이브리드 검색을 즉시 사용할 수 있습니다. 추가 의존성이 필요하지 않습니다. -재순위 지정, 쿼리 확장, 워크스페이스 외부 디렉터리 인덱싱 기능을 갖춘 로컬 우선 사이드카입니다. +재순위화, 쿼리 확장, 워크스페이스 외부 디렉터리 인덱싱 기능을 제공하는 local-first 사이드카입니다. -사용자 모델링, 시맨틱 검색, 멀티 에이전트 인식을 갖춘 AI 네이티브 크로스세션 메모리입니다. 플러그인을 설치해야 합니다. +사용자 모델링, 시맨틱 검색, 멀티 에이전트 인식을 지원하는 AI 네이티브 크로스 세션 메모리입니다. Plugin 설치가 필요합니다. -## 지식 위키 계층 +## 지식 wiki 계층 -지속 메모리를 주장, 대시보드, 브리지 모드, Obsidian 친화적 워크플로를 갖춘 출처 풍부한 위키 볼트로 컴파일합니다. +지속 메모리를 주장, 대시보드, 브리지 모드, Obsidian 친화적 워크플로를 갖춘 출처가 풍부한 wiki vault로 컴파일합니다. ## 자동 메모리 플러시 -[compaction](/ko/concepts/compaction)이 대화를 요약하기 전에, OpenClaw는 에이전트에게 중요한 컨텍스트를 메모리 파일에 저장하라고 상기시키는 조용한 턴을 실행합니다. 이 기능은 기본적으로 켜져 있으므로 별도로 설정할 필요가 없습니다. +[Compaction](/ko/concepts/compaction)이 대화를 요약하기 전에, OpenClaw는 에이전트에게 중요한 컨텍스트를 메모리 파일에 저장하라고 상기시키는 조용한 턴을 실행합니다. 이것은 기본적으로 활성화되어 있으므로 별도 설정이 필요하지 않습니다. -메모리 플러시는 compaction 중 컨텍스트 손실을 방지합니다. 대화에 중요한 사실이 아직 파일에 기록되지 않았다면, 요약이 이루어지기 전에 자동으로 저장됩니다. +메모리 플러시는 Compaction 중 컨텍스트 손실을 방지합니다. 대화 안에 중요한 사실이 아직 파일에 기록되지 않았다면, 요약이 이루어지기 전에 자동으로 저장됩니다. -## 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이 메모리와 상호작용하는 방식 diff --git a/docs/ko/gateway/configuration-reference.md b/docs/ko/gateway/configuration-reference.md index f4f0b9bf8..72360f51b 100644 --- a/docs/ko/gateway/configuration-reference.md +++ b/docs/ko/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - 정확한 필드 수준의 구성 의미나 기본값이 필요합니다 - - 채널, 모델, gateway 또는 도구 구성 블록을 검증하고 있습니다 -summary: 핵심 OpenClaw 키, 기본값, 그리고 전용 하위 시스템 참조 링크를 위한 Gateway 구성 참조 + - 정확한 필드 수준의 구성 의미 또는 기본값이 필요합니다 + - 채널, 모델, Gateway 또는 도구 구성 블록을 검증하고 있습니다 +summary: 핵심 OpenClaw 키, 기본값, 그리고 전용 하위 시스템 참조로의 링크를 위한 Gateway 구성 참조 title: 구성 참조 x-i18n: - generated_at: "2026-04-11T15:15:55Z" + generated_at: "2026-04-15T14:40:30Z" model: gpt-5.4 provider: openai - source_hash: 351a245bed59d852ea8582e4e9fec5017a5c623cd6f0034766cdea1b5330be3c + source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba source_path: gateway/configuration-reference.md workflow: 15 --- # 구성 참조 -`~/.openclaw/openclaw.json`용 핵심 구성 참조입니다. 작업 중심 개요는 [Configuration](/ko/gateway/configuration)을 참조하세요. +`~/.openclaw/openclaw.json`에 대한 핵심 구성 참조입니다. 작업 중심 개요는 [Configuration](/ko/gateway/configuration)을 참고하세요. -이 페이지는 주요 OpenClaw 구성 표면을 다루며, 하위 시스템에 자체적으로 더 깊은 참조가 있는 경우 해당 링크를 제공합니다. 이 페이지는 모든 채널/플러그인 소유 명령 카탈로그나 모든 심층 메모리/QMD 설정을 한 페이지에 인라인으로 넣으려 하지는 않습니다. +이 페이지는 주요 OpenClaw 구성 표면을 다루며, 하위 시스템에 더 깊은 자체 참조가 있는 경우 해당 문서로 연결합니다. 이 페이지는 모든 채널/플러그인 소유 명령 카탈로그나 모든 심층 메모리/QMD 조정 항목을 한 페이지에 인라인으로 담으려 하지 않습니다. -코드 기준 진실 소스: +코드 기준 정보: -- `openclaw config schema`는 검증 및 Control UI에 사용되는 실제 JSON 스키마를 출력하며, 사용 가능한 경우 번들/플러그인/채널 메타데이터가 병합됩니다 -- `config.schema.lookup`은 드릴다운 도구를 위해 경로 범위가 지정된 스키마 노드 하나를 반환합니다 -- `pnpm config:docs:check` / `pnpm config:docs:gen`은 현재 스키마 표면을 기준으로 구성 문서 기준선 해시를 검증합니다 +- `openclaw config schema`는 유효성 검사와 Control UI에 사용되는 현재 JSON Schema를 출력하며, 가능한 경우 번들/플러그인/채널 메타데이터가 병합됩니다 +- `config.schema.lookup`은 드릴다운 도구를 위해 경로 범위가 지정된 단일 스키마 노드를 반환합니다 +- `pnpm config:docs:check` / `pnpm config:docs:gen`은 현재 스키마 표면에 대해 구성 문서 기준선 해시를 검증합니다 -전용 심화 참조: +전용 심층 참조: -- `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, 그리고 `plugins.entries.memory-core.config.dreaming` 아래의 dreaming 구성을 위한 [메모리 구성 참조](/ko/reference/memory-config) -- 현재 내장 + 번들 명령 카탈로그를 위한 [슬래시 명령어](/ko/tools/slash-commands) -- 채널별 명령 표면을 위한 해당 채널/플러그인 페이지 +- `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, 그리고 `plugins.entries.memory-core.config.dreaming` 아래의 Dreaming 구성은 [메모리 구성 참조](/ko/reference/memory-config) 참고 +- 현재 내장 + 번들 명령 카탈로그는 [슬래시 명령어](/ko/tools/slash-commands) 참고 +- 채널별 명령 표면은 해당 채널/플러그인 페이지 참고 -구성 형식은 **JSON5**입니다(주석 + 후행 쉼표 허용). 모든 필드는 선택 사항이며, 생략하면 OpenClaw가 안전한 기본값을 사용합니다. +구성 형식은 **JSON5**입니다(주석 + 후행 쉼표 허용). 모든 필드는 선택 사항이며, 생략되면 OpenClaw가 안전한 기본값을 사용합니다. --- ## 채널 -각 채널은 구성 섹션이 존재하면 자동으로 시작됩니다(`enabled: false`가 아닌 경우). +각 채널은 해당 구성 섹션이 존재하면 자동으로 시작됩니다(`enabled: false`인 경우 제외). -### DM 및 그룹 액세스 +### DM 및 그룹 접근 모든 채널은 DM 정책과 그룹 정책을 지원합니다: -| DM 정책 | 동작 | -| ------------------- | --------------------------------------------------------------- | -| `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 합니다 | -| `allowlist` | `allowFrom`(또는 페어링된 허용 저장소)에 있는 발신자만 허용됩니다 | -| `open` | 모든 인바운드 DM 허용(`allowFrom: ["*"]` 필요) | -| `disabled` | 모든 인바운드 DM 무시 | +| DM 정책 | 동작 | +| ------------------ | --------------------------------------------------------------- | +| `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 함 | +| `allowlist` | `allowFrom`(또는 페어링된 허용 저장소)에 있는 발신자만 허용 | +| `open` | 모든 인바운드 DM 허용(`allowFrom: ["*"]` 필요) | +| `disabled` | 모든 인바운드 DM 무시 | -| 그룹 정책 | 동작 | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용합니다 | -| `open` | 그룹 허용 목록을 우회합니다(멘션 게이팅은 계속 적용됨) | -| `disabled` | 모든 그룹/룸 메시지를 차단합니다 | +| 그룹 정책 | 동작 | +| --------------------- | ------------------------------------------------------- | +| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용 | +| `open` | 그룹 허용 목록 우회(멘션 게이팅은 계속 적용됨) | +| `disabled` | 모든 그룹/룸 메시지 차단 | `channels.defaults.groupPolicy`는 공급자의 `groupPolicy`가 설정되지 않았을 때 기본값을 설정합니다. 페어링 코드는 1시간 후 만료됩니다. 대기 중인 DM 페어링 요청은 **채널당 3개**로 제한됩니다. -공급자 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 시 경고와 함께 `allowlist`(fail-closed)로 대체됩니다. +공급자 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(실패 시 닫힘)로 대체됩니다. ### 채널 모델 재정의 -특정 채널 ID를 모델에 고정하려면 `channels.modelByChannel`을 사용하세요. 값은 `provider/model` 또는 구성된 모델 별칭을 허용합니다. 이 채널 매핑은 세션에 이미 모델 재정의가 없는 경우(예: `/model`을 통해 설정된 경우)에 적용됩니다. +특정 채널 ID를 모델에 고정하려면 `channels.modelByChannel`을 사용하세요. 값은 `provider/model` 또는 구성된 모델 별칭을 받을 수 있습니다. 채널 매핑은 세션에 이미 모델 재정의가 없는 경우에 적용됩니다(예: `/model`로 설정된 경우). ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### 채널 기본값 및 하트비트 +### 채널 기본값과 Heartbeat -공급자 간에 공유되는 그룹 정책 및 하트비트 동작에는 `channels.defaults`를 사용하세요: +공급자 전반에 걸쳐 공유되는 그룹 정책 및 Heartbeat 동작에는 `channels.defaults`를 사용하세요: ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: 공급자 수준의 `groupPolicy`가 설정되지 않았을 때의 대체 그룹 정책입니다. -- `channels.defaults.contextVisibility`: 모든 채널에 대한 기본 보조 컨텍스트 가시성 모드입니다. 값: `all`(기본값, 인용/스레드/기록 컨텍스트 모두 포함), `allowlist`(허용 목록에 있는 발신자의 컨텍스트만 포함), `allowlist_quote`(`allowlist`와 같지만 명시적 인용/답장 컨텍스트는 유지). 채널별 재정의: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: 하트비트 출력에 정상 채널 상태를 포함합니다. -- `channels.defaults.heartbeat.showAlerts`: 하트비트 출력에 저하/오류 상태를 포함합니다. -- `channels.defaults.heartbeat.useIndicator`: 간결한 표시기 스타일 하트비트 출력을 렌더링합니다. +- `channels.defaults.groupPolicy`: 공급자 수준 `groupPolicy`가 설정되지 않았을 때의 대체 그룹 정책입니다. +- `channels.defaults.contextVisibility`: 모든 채널에 대한 기본 추가 컨텍스트 가시성 모드입니다. 값: `all`(기본값, 인용/스레드/기록 컨텍스트 모두 포함), `allowlist`(허용 목록에 있는 발신자의 컨텍스트만 포함), `allowlist_quote`(`allowlist`와 같지만 명시적 인용/답장 컨텍스트는 유지). 채널별 재정의: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: Heartbeat 출력에 정상 채널 상태를 포함합니다. +- `channels.defaults.heartbeat.showAlerts`: Heartbeat 출력에 저하/오류 상태를 포함합니다. +- `channels.defaults.heartbeat.useIndicator`: 간결한 표시기 스타일 Heartbeat 출력을 렌더링합니다. ### WhatsApp -WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결된 세션이 있으면 자동으로 시작됩니다. +WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결된 세션이 있으면 자동으로 시작됩니다. ```json5 { @@ -124,7 +124,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 파란 체크 표시 (셀프 채팅 모드에서는 false) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,8 +164,8 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 아웃바운드 명령은 `default` 계정이 있으면 기본적으로 해당 계정을 사용하고, 없으면 첫 번째로 구성된 계정 ID(정렬 기준)를 사용합니다. -- 선택적 `channels.whatsapp.defaultAccount`는 구성된 계정 ID와 일치할 때 이 대체 기본 계정 선택을 재정의합니다. +- 아웃바운드 명령은 `default` 계정이 있으면 기본적으로 해당 계정을 사용하고, 없으면 첫 번째로 구성된 계정 ID(정렬됨)를 사용합니다. +- 선택 사항인 `channels.whatsapp.defaultAccount`는 구성된 계정 ID와 일치할 때 이 대체 기본 계정 선택을 재정의합니다. - 레거시 단일 계정 Baileys 인증 디렉터리는 `openclaw doctor`에 의해 `whatsapp/default`로 마이그레이션됩니다. - 계정별 재정의: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (기본값: off, 미리보기 편집 속도 제한을 피하려면 명시적으로 opt in) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 봇 토큰: 기본 계정의 경우 `channels.telegram.botToken` 또는 `channels.telegram.tokenFile`(일반 파일만 허용, 심볼릭 링크는 거부)이며, 대체값으로 `TELEGRAM_BOT_TOKEN`을 사용할 수 있습니다. -- 선택적 `channels.telegram.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- 다중 계정 설정(계정 ID 2개 이상)에서는 대체 라우팅을 피하기 위해 명시적 기본값(`channels.telegram.defaultAccount` 또는 `channels.telegram.accounts.default`)을 설정하세요. 이것이 누락되었거나 잘못된 경우 `openclaw doctor`가 경고합니다. -- `configWrites: false`는 Telegram에서 시작된 구성 쓰기(슈퍼그룹 ID 마이그레이션, `/config set|unset`)를 차단합니다. -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 포럼 토픽용 영구 ACP 바인딩을 구성합니다(`match.peer.id`에서는 정식 `chatId:topic:topicId` 사용). 필드 의미는 [ACP Agents](/ko/tools/acp-agents#channel-specific-settings)에서 공통으로 설명됩니다. -- Telegram 스트림 미리보기는 `sendMessage` + `editMessageText`를 사용합니다(직접 채팅과 그룹 채팅 모두에서 작동). -- 재시도 정책: [재시도 정책](/ko/concepts/retry)을 참조하세요. +- 봇 토큰: `channels.telegram.botToken` 또는 `channels.telegram.tokenFile`(일반 파일만 허용, 심볼릭 링크는 거부됨), 기본 계정의 대체 수단으로 `TELEGRAM_BOT_TOKEN` 사용 가능. +- 선택 사항인 `channels.telegram.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 다중 계정 설정(계정 ID 2개 이상)에서는 대체 라우팅을 피하기 위해 명시적 기본값(`channels.telegram.defaultAccount` 또는 `channels.telegram.accounts.default`)을 설정하세요. 이것이 없거나 잘못되면 `openclaw doctor`가 경고합니다. +- `configWrites: false`는 Telegram 시작 구성 쓰기(슈퍼그룹 ID 마이그레이션, `/config set|unset`)를 차단합니다. +- `type: "acp"`를 가진 최상위 `bindings[]` 항목은 포럼 토픽에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에는 정식 `chatId:topic:topicId` 사용). 필드 의미는 [ACP Agents](/ko/tools/acp-agents#channel-specific-settings)에서 공통으로 설명합니다. +- Telegram 스트림 미리보기는 `sendMessage` + `editMessageText`를 사용합니다(개인 채팅과 그룹 채팅 모두에서 작동). +- 재시도 정책: [Retry policy](/ko/concepts/retry) 참고. ### Discord @@ -286,7 +286,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress는 Discord에서 partial로 매핑됨) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // sessions_spawn({ thread: true })에 대한 opt-in + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -333,36 +333,36 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 토큰: 기본 계정의 경우 `channels.discord.token`이며, 대체값으로 `DISCORD_BOT_TOKEN`을 사용할 수 있습니다. +- 토큰: `channels.discord.token`, 기본 계정의 대체 수단으로 `DISCORD_BOT_TOKEN` 사용 가능. - 명시적인 Discord `token`을 제공하는 직접 아웃바운드 호출은 해당 호출에 그 토큰을 사용합니다. 계정 재시도/정책 설정은 여전히 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다. -- 선택적 `channels.discord.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- 전달 대상에는 `user:`(DM) 또는 `channel:`(길드 채널)를 사용하세요. 숫자만 있는 ID는 거부됩니다. -- 길드 슬러그는 소문자이며 공백은 `-`로 대체됩니다. 채널 키는 슬러그화된 이름을 사용합니다(`#` 없음). 가능하면 길드 ID를 사용하세요. -- 봇이 작성한 메시지는 기본적으로 무시됩니다. `allowBots: true`로 이를 허용할 수 있으며, `allowBots: "mentions"`를 사용하면 봇을 멘션한 봇 메시지만 허용됩니다(자체 메시지는 계속 필터링됨). -- `channels.discord.guilds..ignoreOtherMentions`(및 채널 재정의)는 봇을 멘션하지 않으면서 다른 사용자나 역할을 멘션한 메시지를 삭제합니다(`@everyone`/`@here` 제외). -- `maxLinesPerMessage`(기본값 17)는 2000자 미만이더라도 줄 수가 많은 메시지를 분할합니다. +- 선택 사항인 `channels.discord.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 전달 대상에는 `user:`(DM) 또는 `channel:`(guild 채널)를 사용하세요. 숫자 ID만 단독으로 쓰는 것은 거부됩니다. +- Guild slug는 소문자이며 공백은 `-`로 대체됩니다. 채널 키는 slug 처리된 이름을 사용합니다(`#` 없음). Guild ID 사용을 권장합니다. +- 봇이 작성한 메시지는 기본적으로 무시됩니다. `allowBots: true`로 이를 활성화할 수 있으며, `allowBots: "mentions"`를 사용하면 봇을 멘션한 봇 메시지만 수락합니다(자체 메시지는 계속 필터링됨). +- `channels.discord.guilds..ignoreOtherMentions`(및 채널 재정의)는 봇을 멘션하지 않고 다른 사용자나 역할을 멘션한 메시지를 삭제합니다(`@everyone`/`@here` 제외). +- `maxLinesPerMessage`(기본값 17)는 메시지가 2000자 미만이어도 줄 수가 많으면 분할합니다. - `channels.discord.threadBindings`는 Discord 스레드 바인딩 라우팅을 제어합니다: - `enabled`: 스레드 바인딩 세션 기능(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, 그리고 바인딩된 전달/라우팅)에 대한 Discord 재정의 - - `idleHours`: 비활성 자동 unfocus의 시간 단위 Discord 재정의(`0`은 비활성화) - - `maxAgeHours`: 하드 최대 수명의 시간 단위 Discord 재정의(`0`은 비활성화) + - `idleHours`: 비활성 자동 unfocus에 대한 Discord 재정의(시간 단위, `0`이면 비활성화) + - `maxAgeHours`: 하드 최대 수명에 대한 Discord 재정의(시간 단위, `0`이면 비활성화) - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` 자동 스레드 생성/바인딩을 위한 opt-in 스위치 -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 채널과 스레드에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에 채널/스레드 ID 사용). 필드 의미는 [ACP Agents](/ko/tools/acp-agents#channel-specific-settings)에서 공통으로 설명됩니다. +- `type: "acp"`를 가진 최상위 `bindings[]` 항목은 채널 및 스레드에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에는 채널/스레드 ID 사용). 필드 의미는 [ACP Agents](/ko/tools/acp-agents#channel-specific-settings)에서 공통으로 설명합니다. - `channels.discord.ui.components.accentColor`는 Discord components v2 컨테이너의 강조 색상을 설정합니다. - `channels.discord.voice`는 Discord 음성 채널 대화와 선택적 자동 참여 + TTS 재정의를 활성화합니다. -- `channels.discord.voice.daveEncryption` 및 `channels.discord.voice.decryptionFailureTolerance`는 `@discordjs/voice` DAVE 옵션에 그대로 전달됩니다(기본값은 `true` 및 `24`). -- 또한 OpenClaw는 반복된 복호화 실패 후 음성 세션을 나갔다가 다시 참여하여 음성 수신 복구를 시도합니다. -- `channels.discord.streaming`은 정식 스트림 모드 키입니다. 레거시 `streamMode` 및 불리언 `streaming` 값은 자동으로 마이그레이션됩니다. -- `channels.discord.autoPresence`는 런타임 가용성을 봇 상태에 매핑합니다(정상 => online, 저하 => idle, 소진 => dnd) 그리고 선택적 상태 텍스트 재정의를 허용합니다. -- `channels.discord.dangerouslyAllowNameMatching`은 변경 가능한 이름/태그 매칭을 다시 활성화합니다(비상 호환성 모드). +- `channels.discord.voice.daveEncryption` 및 `channels.discord.voice.decryptionFailureTolerance`는 `@discordjs/voice` DAVE 옵션으로 그대로 전달됩니다(기본값은 각각 `true`와 `24`). +- 또한 OpenClaw는 반복적인 복호화 실패 후 음성 세션에서 나갔다가 다시 참여하여 음성 수신 복구를 시도합니다. +- `channels.discord.streaming`은 정식 스트림 모드 키입니다. 레거시 `streamMode` 및 불리언 `streaming` 값은 자동 마이그레이션됩니다. +- `channels.discord.autoPresence`는 런타임 가용성을 봇 상태에 매핑합니다(정상 => online, 저하 => idle, 소진 => dnd). 선택적 상태 텍스트 재정의도 허용합니다. +- `channels.discord.dangerouslyAllowNameMatching`는 변경 가능한 이름/태그 매칭을 다시 활성화합니다(비상 호환성 모드). - `channels.discord.execApprovals`: Discord 네이티브 exec 승인 전달 및 승인자 권한 부여. - - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). 자동 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. + - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). auto 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. - `approvers`: exec 요청을 승인할 수 있는 Discord 사용자 ID입니다. 생략하면 `commands.ownerAllowFrom`으로 대체됩니다. - - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 모든 에이전트에 대한 승인을 전달하려면 생략하세요. - - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 정규식)입니다. + - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 모든 에이전트의 승인을 전달하려면 생략하세요. + - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 정규식). - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값)은 승인자 DM으로 보내고, `"channel"`은 원래 채널로 보내며, `"both"`는 둘 다로 보냅니다. 대상에 `"channel"`이 포함되면 버튼은 확인된 승인자만 사용할 수 있습니다. - `cleanupAfterResolve`: `true`이면 승인, 거부 또는 시간 초과 후 승인 DM을 삭제합니다. -**리액션 알림 모드:** `off`(없음), `own`(봇 메시지, 기본값), `all`(모든 메시지), `allowlist`(모든 메시지에서 `guilds..users` 기준). +**반응 알림 모드:** `off`(없음), `own`(봇 메시지, 기본값), `all`(모든 메시지), `allowlist`(`guilds..users`의 사용자에 대해 모든 메시지). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 서비스 계정 JSON: 인라인(`serviceAccount`) 또는 파일 기반(`serviceAccountFile`)입니다. -- 서비스 계정 SecretRef도 지원됩니다(`serviceAccountRef`). +- 서비스 계정 JSON: 인라인(`serviceAccount`) 또는 파일 기반(`serviceAccountFile`). +- 서비스 계정 SecretRef(`serviceAccountRef`)도 지원됩니다. - 환경 변수 대체값: `GOOGLE_CHAT_SERVICE_ACCOUNT` 또는 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - 전달 대상에는 `spaces/` 또는 `users/`를 사용하세요. -- `channels.googlechat.dangerouslyAllowNameMatching`은 변경 가능한 이메일 프린시펄 매칭을 다시 활성화합니다(비상 호환성 모드). +- `channels.googlechat.dangerouslyAllowNameMatching`는 변경 가능한 이메일 주체 매칭을 다시 활성화합니다(비상 호환성 모드). ### Slack @@ -449,7 +449,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // mode=partial일 때 Slack 네이티브 스트리밍 API 사용 + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,34 +464,34 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- **소켓 모드**에는 `botToken`과 `appToken`이 모두 필요합니다(기본 계정 환경 변수 대체값은 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). -- **HTTP 모드**에는 `botToken`과 `signingSecret`(루트 또는 계정별)이 필요합니다. -- `botToken`, `appToken`, `signingSecret`, `userToken`은 평문 문자열 또는 SecretRef 객체를 받을 수 있습니다. -- Slack 계정 스냅샷은 `botTokenSource`, `botTokenStatus`, `appTokenStatus`, 그리고 HTTP 모드의 경우 `signingSecretStatus`와 같은 자격 증명별 소스/상태 필드를 노출합니다. `configured_unavailable`은 계정이 SecretRef를 통해 구성되었지만 현재 명령/런타임 경로에서 비밀 값 해석이 불가능했음을 의미합니다. -- `configWrites: false`는 Slack에서 시작된 구성 쓰기를 차단합니다. -- 선택적 `channels.slack.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- `channels.slack.streaming.mode`는 정식 Slack 스트림 모드 키입니다. `channels.slack.streaming.nativeTransport`는 Slack의 네이티브 스트리밍 전송을 제어합니다. 레거시 `streamMode`, 불리언 `streaming`, `nativeStreaming` 값은 자동으로 마이그레이션됩니다. +- **Socket mode**는 `botToken`과 `appToken`이 모두 필요합니다(기본 계정 환경 변수 대체값은 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). +- **HTTP mode**는 `botToken`과 `signingSecret`(루트 또는 계정별)이 필요합니다. +- `botToken`, `appToken`, `signingSecret`, `userToken`은 일반 텍스트 문자열 또는 SecretRef 객체를 받을 수 있습니다. +- Slack 계정 스냅샷은 `botTokenSource`, `botTokenStatus`, `appTokenStatus`, 그리고 HTTP 모드에서는 `signingSecretStatus`와 같은 자격 증명별 소스/상태 필드를 노출합니다. `configured_unavailable`은 계정이 SecretRef를 통해 구성되었지만 현재 명령/런타임 경로에서는 비밀값을 확인할 수 없음을 의미합니다. +- `configWrites: false`는 Slack 시작 구성 쓰기를 차단합니다. +- 선택 사항인 `channels.slack.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- `channels.slack.streaming.mode`는 정식 Slack 스트림 모드 키입니다. `channels.slack.streaming.nativeTransport`는 Slack의 네이티브 스트리밍 전송을 제어합니다. 레거시 `streamMode`, 불리언 `streaming`, `nativeStreaming` 값은 자동 마이그레이션됩니다. - 전달 대상에는 `user:`(DM) 또는 `channel:`를 사용하세요. -**리액션 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). +**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). -**스레드 세션 격리:** `thread.historyScope`는 스레드별(기본값) 또는 채널 공유입니다. `thread.inheritParent`는 부모 채널 대화 내용을 새 스레드에 복사합니다. +**스레드 세션 격리:** `thread.historyScope`는 스레드별(기본값) 또는 채널 전체 공유입니다. `thread.inheritParent`는 부모 채널 대화 기록을 새 스레드로 복사합니다. -- Slack 네이티브 스트리밍과 Slack 어시스턴트 스타일의 "입력 중..." 스레드 상태는 응답 스레드 대상을 필요로 합니다. 최상위 DM은 기본적으로 오프스레드 상태이므로, 스레드 스타일 미리보기 대신 `typingReaction` 또는 일반 전달을 사용합니다. -- `typingReaction`은 응답이 실행되는 동안 인바운드 Slack 메시지에 임시 리액션을 추가한 뒤 완료 시 제거합니다. `"hourglass_flowing_sand"` 같은 Slack 이모지 shortcode를 사용하세요. +- Slack 네이티브 스트리밍과 Slack assistant 스타일의 "is typing..." 스레드 상태는 응답 스레드 대상을 필요로 합니다. 최상위 DM은 기본적으로 스레드 밖에서 유지되므로 스레드 스타일 미리보기 대신 `typingReaction` 또는 일반 전달을 사용합니다. +- `typingReaction`은 응답이 실행되는 동안 인바운드 Slack 메시지에 임시 반응을 추가하고 완료 시 제거합니다. `"hourglass_flowing_sand"` 같은 Slack 이모지 shortcode를 사용하세요. - `channels.slack.execApprovals`: Slack 네이티브 exec 승인 전달 및 승인자 권한 부여. Discord와 동일한 스키마를 사용합니다: `enabled` (`true`/`false`/`"auto"`), `approvers` (Slack 사용자 ID), `agentFilter`, `sessionFilter`, `target` (`"dm"`, `"channel"`, 또는 `"both"`). -| 작업 그룹 | 기본값 | 참고 | -| ----------- | ------- | ----------------------- | -| reactions | 활성화 | 리액션 + 리액션 목록 | -| messages | 활성화 | 읽기/보내기/수정/삭제 | -| pins | 활성화 | 고정/고정 해제/목록 | -| memberInfo | 활성화 | 멤버 정보 | -| emojiList | 활성화 | 사용자 지정 이모지 목록 | +| 작업 그룹 | 기본값 | 참고 | +| ----------- | -------- | ------------------------ | +| reactions | 활성화됨 | 반응 추가 + 반응 목록 | +| messages | 활성화됨 | 읽기/보내기/수정/삭제 | +| pins | 활성화됨 | 고정/고정 해제/목록 | +| memberInfo | 활성화됨 | 멤버 정보 | +| emojiList | 활성화됨 | 사용자 정의 이모지 목록 | ### Mattermost -Mattermost는 플러그인으로 제공됩니다: `openclaw plugins install @openclaw/mattermost`. +Mattermost는 Plugin으로 제공됩니다: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -511,7 +511,7 @@ Mattermost는 플러그인으로 제공됩니다: `openclaw plugins install @ope native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 리버스 프록시/공개 배포를 위한 선택적 명시 URL + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,15 +526,13 @@ Mattermost는 플러그인으로 제공됩니다: `openclaw plugins install @ope Mattermost 네이티브 명령이 활성화된 경우: - `commands.callbackPath`는 전체 URL이 아니라 경로여야 합니다(예: `/api/channels/mattermost/command`). -- `commands.callbackUrl`은 OpenClaw gateway 엔드포인트를 가리켜야 하며 Mattermost 서버에서 접근 가능해야 합니다. -- 네이티브 슬래시 콜백은 슬래시 명령 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 다음과 함께 콜백을 거부합니다. - `Unauthorized: invalid command token.` -- 비공개/tailnet/내부 콜백 호스트의 경우 Mattermost는 `ServiceSettings.AllowedUntrustedInternalConnections`에 콜백 호스트/도메인이 포함되어야 할 수 있습니다. - 전체 URL이 아니라 호스트/도메인 값을 사용하세요. -- `channels.mattermost.configWrites`: Mattermost에서 시작된 구성 쓰기를 허용하거나 거부합니다. +- `commands.callbackUrl`은 OpenClaw Gateway 엔드포인트로 해석되어야 하며 Mattermost 서버에서 접근 가능해야 합니다. +- 네이티브 슬래시 콜백은 Mattermost가 슬래시 명령 등록 중 반환하는 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 `Unauthorized: invalid command token.`으로 콜백을 거부합니다. +- 비공개/tailnet/내부 콜백 호스트의 경우, Mattermost는 `ServiceSettings.AllowedUntrustedInternalConnections`에 콜백 호스트/도메인이 포함되어야 할 수 있습니다. 전체 URL이 아니라 호스트/도메인 값을 사용하세요. +- `channels.mattermost.configWrites`: Mattermost 시작 구성 쓰기를 허용 또는 거부합니다. - `channels.mattermost.requireMention`: 채널에서 응답하기 전에 `@mention`을 요구합니다. -- `channels.mattermost.groups..requireMention`: 채널별 멘션 게이팅 재정의입니다(기본값은 `"*"`). -- 선택적 `channels.mattermost.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- `channels.mattermost.groups..requireMention`: 채널별 멘션 게이팅 재정의(기본값은 `"*"`). +- 선택 사항인 `channels.mattermost.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. ### Signal @@ -543,7 +541,7 @@ Mattermost 네이티브 명령이 활성화된 경우: channels: { signal: { enabled: true, - account: "+15555550123", // 선택적 계정 바인딩 + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -555,15 +553,15 @@ Mattermost 네이티브 명령이 활성화된 경우: } ``` -**리액션 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). +**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). -- `channels.signal.account`: 채널 시작을 특정 Signal 계정 ID에 고정합니다. -- `channels.signal.configWrites`: Signal에서 시작된 구성 쓰기를 허용하거나 거부합니다. -- 선택적 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- `channels.signal.account`: 채널 시작을 특정 Signal 계정 식별자에 고정합니다. +- `channels.signal.configWrites`: Signal 시작 구성 쓰기를 허용하거나 거부합니다. +- 선택 사항인 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. ### BlueBubbles -BlueBubbles는 권장되는 iMessage 경로입니다(플러그인 기반, `channels.bluebubbles` 아래에 구성). +BlueBubbles는 권장되는 iMessage 경로입니다(Plugin 기반이며 `channels.bluebubbles` 아래에서 구성). ```json5 { @@ -579,13 +577,13 @@ BlueBubbles는 권장되는 iMessage 경로입니다(플러그인 기반, `chann ``` - 여기에서 다루는 핵심 키 경로: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- 선택적 `channels.bluebubbles.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 BlueBubbles 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 BlueBubbles 핸들 또는 대상 문자열(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). +- 선택 사항인 `channels.bluebubbles.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- `type: "acp"`를 가진 최상위 `bindings[]` 항목은 BlueBubbles 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 BlueBubbles 핸들 또는 대상 문자열(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). - 전체 BlueBubbles 채널 구성은 [BlueBubbles](/ko/channels/bluebubbles)에 문서화되어 있습니다. ### iMessage -OpenClaw는 `imsg rpc`를 생성합니다(stdio를 통한 JSON-RPC). 데몬이나 포트는 필요하지 않습니다. +OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 실행합니다. 데몬이나 포트는 필요하지 않습니다. ```json5 { @@ -609,15 +607,15 @@ OpenClaw는 `imsg rpc`를 생성합니다(stdio를 통한 JSON-RPC). 데몬이 } ``` -- 선택적 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 선택 사항인 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. - Messages DB에 대한 전체 디스크 접근 권한이 필요합니다. -- 가능하면 `chat_id:` 대상을 사용하세요. 채팅 목록은 `imsg chats --limit 20`으로 확인할 수 있습니다. +- `chat_id:` 대상을 사용하는 것을 권장합니다. 채팅 목록은 `imsg chats --limit 20`으로 확인하세요. - `cliPath`는 SSH 래퍼를 가리킬 수 있습니다. SCP 첨부 파일 가져오기를 위해 `remoteHost`(`host` 또는 `user@host`)를 설정하세요. -- `attachmentRoots` 및 `remoteAttachmentRoots`는 인바운드 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). +- `attachmentRoots`와 `remoteAttachmentRoots`는 인바운드 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). - SCP는 엄격한 호스트 키 확인을 사용하므로, 릴레이 호스트 키가 이미 `~/.ssh/known_hosts`에 있어야 합니다. -- `channels.imessage.configWrites`: iMessage에서 시작된 구성 쓰기를 허용하거나 거부합니다. -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 정규화된 핸들 또는 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). +- `channels.imessage.configWrites`: iMessage 시작 구성 쓰기를 허용하거나 거부합니다. +- `type: "acp"`를 가진 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 정규화된 핸들 또는 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). @@ -630,7 +628,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix는 확장 기반이며 `channels.matrix` 아래에 구성됩니다. +Matrix는 확장 기반이며 `channels.matrix` 아래에서 구성됩니다. ```json5 { @@ -661,24 +659,24 @@ Matrix는 확장 기반이며 `channels.matrix` 아래에 구성됩니다. ``` - 토큰 인증은 `accessToken`을 사용하고, 비밀번호 인증은 `userId` + `password`를 사용합니다. -- `channels.matrix.proxy`는 Matrix HTTP 트래픽을 명시적인 HTTP(S) 프록시를 통해 라우팅합니다. 이름이 있는 계정은 `channels.matrix.accounts..proxy`로 이를 재정의할 수 있습니다. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork`는 사설/내부 homeserver를 허용합니다. `proxy`와 이 네트워크 opt-in은 서로 독립적인 제어입니다. +- `channels.matrix.proxy`는 Matrix HTTP 트래픽을 명시적인 HTTP(S) 프록시를 통해 라우팅합니다. 명명된 계정은 `channels.matrix.accounts..proxy`로 이를 재정의할 수 있습니다. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork`는 비공개/내부 홈서버를 허용합니다. `proxy`와 이 네트워크 opt-in은 서로 독립적인 제어 항목입니다. - `channels.matrix.defaultAccount`는 다중 계정 설정에서 선호 계정을 선택합니다. -- `channels.matrix.autoJoin`의 기본값은 `off`이므로, `autoJoin: "allowlist"`와 `autoJoinAllowlist` 또는 `autoJoin: "always"`를 설정하기 전까지 초대된 방과 새 DM 스타일 초대는 무시됩니다. +- `channels.matrix.autoJoin`의 기본값은 `off`이므로, 초대된 룸과 새로운 DM 스타일 초대는 `autoJoin: "allowlist"`와 `autoJoinAllowlist` 또는 `autoJoin: "always"`를 설정하기 전까지 무시됩니다. - `channels.matrix.execApprovals`: Matrix 네이티브 exec 승인 전달 및 승인자 권한 부여. - - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). 자동 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. + - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). auto 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. - `approvers`: exec 요청을 승인할 수 있는 Matrix 사용자 ID(예: `@owner:example.org`)입니다. - - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 모든 에이전트에 대한 승인을 전달하려면 생략하세요. - - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 정규식)입니다. - - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값), `"channel"`(원래 방), 또는 `"both"`입니다. + - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 모든 에이전트의 승인을 전달하려면 생략하세요. + - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 정규식). + - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값), `"channel"`(원래 룸), 또는 `"both"`. - 계정별 재정의: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 묶이는 방식을 제어합니다: `per-user`(기본값)는 라우팅된 피어별로 공유하고, `per-room`은 각 DM 방을 격리합니다. -- Matrix 상태 프로브와 실시간 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. +- `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 묶이는 방식을 제어합니다: `per-user`(기본값)는 라우팅된 피어 기준으로 공유하고, `per-room`은 각 DM 룸을 분리합니다. +- Matrix 상태 프로브와 라이브 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. - 전체 Matrix 구성, 대상 지정 규칙, 설정 예시는 [Matrix](/ko/channels/matrix)에 문서화되어 있습니다. ### Microsoft Teams -Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에 구성됩니다. +Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에서 구성됩니다. ```json5 { @@ -694,11 +692,11 @@ Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에 구성됩니 ``` - 여기에서 다루는 핵심 키 경로: `channels.msteams`, `channels.msteams.configWrites`. -- 전체 Teams 구성(자격 증명, webhook, DM/그룹 정책, 팀별/채널별 재정의)은 [Microsoft Teams](/ko/channels/msteams)에 문서화되어 있습니다. +- 전체 Teams 구성(자격 증명, Webhook, DM/그룹 정책, 팀별/채널별 재정의)은 [Microsoft Teams](/ko/channels/msteams)에 문서화되어 있습니다. ### IRC -IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. +IRC는 확장 기반이며 `channels.irc` 아래에서 구성됩니다. ```json5 { @@ -720,7 +718,7 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ``` - 여기에서 다루는 핵심 키 경로: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- 선택적 `channels.irc.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 선택 사항인 `channels.irc.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. - 전체 IRC 채널 구성(호스트/포트/TLS/채널/허용 목록/멘션 게이팅)은 [IRC](/ko/channels/irc)에 문서화되어 있습니다. ### 다중 계정(모든 채널) @@ -747,27 +745,27 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ``` - `accountId`를 생략하면 `default`가 사용됩니다(CLI + 라우팅). -- 환경 변수 토큰은 **default** 계정에만 적용됩니다. -- 기본 채널 설정은 계정별로 재정의하지 않는 한 모든 계정에 적용됩니다. -- 각 계정을 다른 에이전트로 라우팅하려면 `bindings[].match.accountId`를 사용하세요. -- 단일 계정 최상위 채널 구성 상태에서 `openclaw channels add`(또는 채널 온보딩)로 비기본 계정을 추가하면, OpenClaw는 먼저 계정 범위의 최상위 단일 계정 값을 채널 계정 맵으로 승격하여 원래 계정이 계속 작동하도록 합니다. 대부분의 채널은 이를 `channels..accounts.default`로 이동하며, Matrix는 대신 기존의 일치하는 이름 지정/default 대상을 유지할 수 있습니다. -- 기존 채널 전용 바인딩(`accountId` 없음)은 계속 기본 계정과 일치합니다. 계정 범위 바인딩은 여전히 선택 사항입니다. -- `openclaw doctor --fix`도 혼합된 형태를 복구하여 계정 범위의 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 이동합니다. 대부분의 채널은 `accounts.default`를 사용하며, Matrix는 기존의 일치하는 이름 지정/default 대상을 유지할 수 있습니다. +- 환경 변수 토큰은 **기본** 계정에만 적용됩니다. +- 계정별로 재정의하지 않는 한 기본 채널 설정이 모든 계정에 적용됩니다. +- 각 계정을 서로 다른 에이전트로 라우팅하려면 `bindings[].match.accountId`를 사용하세요. +- `openclaw channels add`(또는 채널 온보딩)를 통해 기본값이 아닌 계정을 추가할 때 아직 단일 계정 최상위 채널 구성 형태라면, OpenClaw는 먼저 계정 범위의 최상위 단일 계정 값을 채널 계정 맵으로 승격하여 원래 계정이 계속 작동하도록 합니다. 대부분의 채널은 이를 `channels..accounts.default`로 이동하며, Matrix는 기존의 일치하는 named/default 대상을 대신 유지할 수 있습니다. +- 기존의 채널 전용 바인딩(`accountId` 없음)은 계속 기본 계정과 일치하며, 계정 범위 바인딩은 선택 사항으로 남습니다. +- `openclaw doctor --fix`도 혼합된 형태를 복구하여 계정 범위의 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 이동합니다. 대부분의 채널은 `accounts.default`를 사용하며, Matrix는 기존의 일치하는 named/default 대상을 대신 유지할 수 있습니다. ### 기타 확장 채널 많은 확장 채널은 `channels.`로 구성되며 전용 채널 페이지에 문서화되어 있습니다(예: Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, Twitch). -전체 채널 색인은 [Channels](/ko/channels)을 참조하세요. +전체 채널 색인은 [Channels](/ko/channels)에서 확인하세요. ### 그룹 채팅 멘션 게이팅 -그룹 메시지는 기본적으로 **멘션 필요**로 설정됩니다(메타데이터 멘션 또는 안전한 정규식 패턴). WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. +그룹 메시지는 기본적으로 **멘션 필요**입니다(메타데이터 멘션 또는 안전한 정규식 패턴). WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. **멘션 유형:** -- **메타데이터 멘션**: 플랫폼의 네이티브 @멘션입니다. WhatsApp 셀프 채팅 모드에서는 무시됩니다. +- **메타데이터 멘션**: 플랫폼 고유의 @멘션입니다. WhatsApp self-chat 모드에서는 무시됩니다. - **텍스트 패턴**: `agents.list[].groupChat.mentionPatterns`의 안전한 정규식 패턴입니다. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다. -- 멘션 게이팅은 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 패턴이 최소 하나 이상 있을 때). +- 멘션 게이팅은 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 하나 이상의 패턴이 있는 경우). ```json5 { @@ -780,7 +778,7 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -`messages.groupChat.historyLimit`은 전역 기본값을 설정합니다. 채널은 `channels..historyLimit`(또는 계정별 설정)로 이를 재정의할 수 있습니다. 비활성화하려면 `0`으로 설정하세요. +`messages.groupChat.historyLimit`는 전역 기본값을 설정합니다. 채널은 `channels..historyLimit`(또는 계정별 설정)로 이를 재정의할 수 있습니다. 비활성화하려면 `0`으로 설정하세요. #### DM 기록 제한 @@ -801,9 +799,9 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. 지원 대상: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### 셀프 채팅 모드 +#### self-chat 모드 -자신의 번호를 `allowFrom`에 포함하면 셀프 채팅 모드가 활성화됩니다(네이티브 @멘션은 무시하고 텍스트 패턴에만 응답): +자신의 번호를 `allowFrom`에 포함하면 self-chat 모드가 활성화됩니다(네이티브 @멘션은 무시하고 텍스트 패턴에만 응답): ```json5 { @@ -829,16 +827,16 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ```json5 { commands: { - native: "auto", // 지원되는 경우 네이티브 명령 등록 - nativeSkills: "auto", // 지원되는 경우 네이티브 Skills 명령 등록 - text: true, // 채팅 메시지에서 /commands 구문 분석 - bash: false, // ! 허용 (별칭: /bash) + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // /config 허용 - mcp: false, // /mcp 허용 - plugins: false, // /plugins 허용 - debug: false, // /debug 허용 - restart: true, // /restart + gateway 재시작 도구 허용 + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -853,32 +851,32 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. -- 이 블록은 명령 표면을 구성합니다. 현재 내장 + 번들 명령 카탈로그는 [슬래시 명령어](/ko/tools/slash-commands)를 참조하세요. -- 이 페이지는 전체 명령 카탈로그가 아니라 **구성 키 참조**입니다. QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, Talk `/voice` 같은 채널/플러그인 소유 명령은 해당 채널/플러그인 페이지와 [슬래시 명령어](/ko/tools/slash-commands)에 문서화되어 있습니다. -- 텍스트 명령은 앞에 `/`가 붙은 **독립 실행형** 메시지여야 합니다. -- `native: "auto"`는 Discord/Telegram의 네이티브 명령을 켜고, Slack은 끕니다. -- `nativeSkills: "auto"`는 Discord/Telegram의 네이티브 Skills 명령을 켜고, Slack은 끕니다. -- 채널별 재정의: `channels.discord.commands.native`(bool 또는 `"auto"`). `false`는 이전에 등록된 명령을 지웁니다. -- 채널별 네이티브 Skills 등록은 `channels..commands.nativeSkills`로 재정의합니다. -- `channels.telegram.customCommands`는 추가 Telegram 봇 메뉴 항목을 더합니다. +- 이 블록은 명령 표면을 구성합니다. 현재 내장 + 번들 명령 카탈로그는 [Slash Commands](/ko/tools/slash-commands)를 참고하세요. +- 이 페이지는 전체 명령 카탈로그가 아니라 **구성 키 참조**입니다. QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, Talk `/voice` 같은 채널/플러그인 소유 명령은 해당 채널/플러그인 페이지와 [Slash Commands](/ko/tools/slash-commands)에 문서화되어 있습니다. +- 텍스트 명령은 맨 앞에 `/`가 있는 **독립 실행형** 메시지여야 합니다. +- `native: "auto"`는 Discord/Telegram의 네이티브 명령을 켜고, Slack은 꺼 둡니다. +- `nativeSkills: "auto"`는 Discord/Telegram의 네이티브 Skills 명령을 켜고, Slack은 꺼 둡니다. +- 채널별 재정의: `channels.discord.commands.native`(bool 또는 `"auto"`). `false`는 이전에 등록된 명령을 제거합니다. +- `channels..commands.nativeSkills`로 채널별 네이티브 Skills 명령 등록을 재정의합니다. +- `channels.telegram.customCommands`는 추가 Telegram 봇 메뉴 항목을 추가합니다. - `bash: true`는 호스트 셸용 `! `를 활성화합니다. `tools.elevated.enabled`와 `tools.elevated.allowFrom.`에 발신자가 포함되어 있어야 합니다. -- `config: true`는 `/config`를 활성화합니다(`openclaw.json` 읽기/쓰기). gateway `chat.send` 클라이언트의 경우 영구적인 `/config set|unset` 쓰기에는 `operator.admin`도 필요합니다. 읽기 전용 `/config show`는 일반 쓰기 범위 operator 클라이언트에서도 계속 사용할 수 있습니다. -- `mcp: true`는 `mcp.servers` 아래의 OpenClaw 관리 MCP 서버 구성을 위한 `/mcp`를 활성화합니다. -- `plugins: true`는 플러그인 검색, 설치, 활성화/비활성화 제어를 위한 `/plugins`를 활성화합니다. +- `config: true`는 `/config`를 활성화합니다(`openclaw.json` 읽기/쓰기). Gateway `chat.send` 클라이언트의 경우 영구 `/config set|unset` 쓰기에는 `operator.admin`도 필요합니다. 읽기 전용 `/config show`는 일반 쓰기 범위 operator 클라이언트에서도 계속 사용할 수 있습니다. +- `mcp: true`는 `mcp.servers` 아래의 OpenClaw 관리 MCP 서버 구성용 `/mcp`를 활성화합니다. +- `plugins: true`는 Plugin 검색, 설치, 활성화/비활성화 제어를 위한 `/plugins`를 활성화합니다. - `channels..configWrites`는 채널별 구성 변경을 제어합니다(기본값: true). -- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기를 제어합니다(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`). -- `restart: false`는 `/restart`와 gateway 재시작 도구 작업을 비활성화합니다. 기본값: `true`. -- `ownerAllowFrom`은 소유자 전용 명령/도구를 위한 명시적 소유자 허용 목록입니다. `allowFrom`과는 별개입니다. -- `ownerDisplay: "hash"`는 시스템 프롬프트에서 소유자 ID를 해시 처리합니다. 해시를 제어하려면 `ownerDisplaySecret`을 설정하세요. -- `allowFrom`은 공급자별입니다. 설정되면 이것이 **유일한** 권한 부여 소스가 됩니다(채널 허용 목록/페어링과 `useAccessGroups`는 무시됨). -- `useAccessGroups: false`는 `allowFrom`이 설정되지 않았을 때 명령이 액세스 그룹 정책을 우회하도록 허용합니다. +- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`)를 제어합니다. +- `restart: false`는 `/restart`와 Gateway 재시작 도구 동작을 비활성화합니다. 기본값: `true`. +- `ownerAllowFrom`은 소유자 전용 명령/도구에 대한 명시적 소유자 허용 목록입니다. `allowFrom`과는 별개입니다. +- `ownerDisplay: "hash"`는 시스템 프롬프트에서 소유자 ID를 해시합니다. 해시 제어에는 `ownerDisplaySecret`을 설정하세요. +- `allowFrom`은 공급자별입니다. 설정되면 이것이 **유일한** 인증 소스가 됩니다(채널 허용 목록/페어링 및 `useAccessGroups`는 무시됨). +- `useAccessGroups: false`는 `allowFrom`이 설정되지 않았을 때 명령이 접근 그룹 정책을 우회할 수 있게 합니다. - 명령 문서 맵: - - 내장 + 번들 카탈로그: [슬래시 명령어](/ko/tools/slash-commands) - - 채널별 명령 표면: [채널](/ko/channels) + - 내장 + 번들 카탈로그: [Slash Commands](/ko/tools/slash-commands) + - 채널별 명령 표면: [Channels](/ko/channels) - QQ Bot 명령: [QQ Bot](/ko/channels/qqbot) - 페어링 명령: [Pairing](/ko/channels/pairing) - LINE 카드 명령: [LINE](/ko/channels/line) - - memory dreaming: [Dreaming](/ko/concepts/dreaming) + - 메모리 Dreaming: [Dreaming](/ko/concepts/dreaming) @@ -898,7 +896,7 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ### `agents.defaults.repoRoot` -시스템 프롬프트의 Runtime 줄에 표시되는 선택적 저장소 루트입니다. 설정하지 않으면 OpenClaw가 workspace에서 위로 탐색하며 자동 감지합니다. +시스템 프롬프트의 Runtime 줄에 표시되는 선택적 저장소 루트입니다. 설정하지 않으면 OpenClaw가 workspace에서 위로 올라가며 자동 감지합니다. ```json5 { @@ -908,16 +906,16 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ### `agents.defaults.skills` -`agents.list[].skills`를 설정하지 않은 에이전트에 대한 선택적 기본 skill 허용 목록입니다. +`agents.list[].skills`를 설정하지 않은 에이전트에 대한 선택적 기본 Skills 허용 목록입니다. ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // github, weather 상속 - { id: "docs", skills: ["docs-search"] }, // 기본값 대체 - { id: "locked-down", skills: [] }, // skills 없음 + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } @@ -925,7 +923,7 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. - 기본적으로 제한 없는 Skills를 사용하려면 `agents.defaults.skills`를 생략하세요. - 기본값을 상속하려면 `agents.list[].skills`를 생략하세요. -- skills가 없도록 하려면 `agents.list[].skills: []`로 설정하세요. +- Skills를 사용하지 않으려면 `agents.list[].skills: []`로 설정하세요. - 비어 있지 않은 `agents.list[].skills` 목록은 해당 에이전트의 최종 집합이며, 기본값과 병합되지 않습니다. ### `agents.defaults.skipBootstrap` @@ -940,9 +938,9 @@ workspace bootstrap 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `U ### `agents.defaults.contextInjection` -workspace bootstrap 파일을 시스템 프롬프트에 삽입하는 시점을 제어합니다. 기본값: `"always"`. +workspace bootstrap 파일이 시스템 프롬프트에 주입되는 시점을 제어합니다. 기본값: `"always"`. -- `"continuation-skip"`: 안전한 연속 턴(완료된 assistant 응답 이후)에서는 workspace bootstrap 재삽입을 건너뛰어 프롬프트 크기를 줄입니다. 하트비트 실행과 압축 후 재시도는 계속 컨텍스트를 다시 빌드합니다. +- `"continuation-skip"`: 안전한 연속 턴(완료된 assistant 응답 이후)에서는 workspace bootstrap 재주입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행 및 Compaction 후 재시도에서는 여전히 컨텍스트를 다시 구성합니다. ```json5 { @@ -952,7 +950,7 @@ workspace bootstrap 파일을 시스템 프롬프트에 삽입하는 시점을 ### `agents.defaults.bootstrapMaxChars` -잘리기 전 workspace bootstrap 파일당 최대 문자 수입니다. 기본값: `20000`. +잘리기 전 각 workspace bootstrap 파일의 최대 문자 수입니다. 기본값: `20000`. ```json5 { @@ -962,7 +960,7 @@ workspace bootstrap 파일을 시스템 프롬프트에 삽입하는 시점을 ### `agents.defaults.bootstrapTotalMaxChars` -모든 workspace bootstrap 파일에 걸쳐 삽입되는 총 최대 문자 수입니다. 기본값: `150000`. +모든 workspace bootstrap 파일 전체에 걸쳐 주입되는 총 최대 문자 수입니다. 기본값: `150000`. ```json5 { @@ -972,12 +970,12 @@ workspace bootstrap 파일을 시스템 프롬프트에 삽입하는 시점을 ### `agents.defaults.bootstrapPromptTruncationWarning` -bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트를 제어합니다. +bootstrap 컨텍스트가 잘렸을 때 에이전트에 표시되는 경고 텍스트를 제어합니다. 기본값: `"once"`. -- `"off"`: 시스템 프롬프트에 경고 텍스트를 절대 삽입하지 않습니다. -- `"once"`: 고유한 잘림 시그니처당 한 번만 경고를 삽입합니다(권장). -- `"always"`: 잘림이 존재하는 모든 실행마다 경고를 삽입합니다. +- `"off"`: 시스템 프롬프트에 경고 텍스트를 주입하지 않습니다. +- `"once"`: 고유한 잘림 시그니처마다 경고를 한 번 주입합니다(권장). +- `"always"`: 잘림이 있으면 실행할 때마다 경고를 주입합니다. ```json5 { @@ -987,11 +985,11 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 ### `agents.defaults.imageMaxDimensionPx` -공급자 호출 전에 transcript/tool 이미지 블록에서 이미지의 가장 긴 변의 최대 픽셀 크기입니다. +공급자 호출 전에 transcript/도구 이미지 블록에서 가장 긴 이미지 변의 최대 픽셀 크기입니다. 기본값: `1200`. -값이 낮을수록 일반적으로 스크린샷이 많은 실행에서 vision token 사용량과 요청 페이로드 크기가 줄어듭니다. -값이 높을수록 더 많은 시각적 디테일이 유지됩니다. +값을 낮추면 일반적으로 스크린샷이 많은 실행에서 비전 토큰 사용량과 요청 페이로드 크기가 줄어듭니다. +값을 높이면 더 많은 시각적 디테일을 유지합니다. ```json5 { @@ -1001,7 +999,7 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 ### `agents.defaults.userTimezone` -시스템 프롬프트 컨텍스트용 시간대입니다(메시지 타임스탬프 제외). 설정하지 않으면 호스트 시간대를 사용합니다. +시스템 프롬프트 컨텍스트용 시간대입니다(메시지 타임스탬프용 아님). 호스트 시간대로 대체됩니다. ```json5 { @@ -1011,7 +1009,7 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 ### `agents.defaults.timeFormat` -시스템 프롬프트의 시간 형식입니다. 기본값: `auto`(OS 기본 설정). +시스템 프롬프트의 시간 형식입니다. 기본값: `auto`(OS 환경설정). ```json5 { @@ -1049,9 +1047,9 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 전역 기본 공급자 params + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { - runtime: "auto", // auto | pi | 등록된 harness id(예: codex) + runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1075,41 +1073,41 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 - `image` 도구 경로에서 비전 모델 구성으로 사용됩니다. - 선택된/기본 모델이 이미지 입력을 받을 수 없을 때 대체 라우팅에도 사용됩니다. - `imageGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 이미지 생성 기능과 향후 이미지를 생성하는 모든 도구/플러그인 표면에서 사용됩니다. - - 일반적인 값: Gemini 네이티브 이미지 생성용 `google/gemini-3.1-flash-image-preview`, fal용 `fal/fal-ai/flux/dev`, 또는 OpenAI Images용 `openai/gpt-image-1`. - - 공급자/모델을 직접 선택하는 경우, 해당 공급자의 인증/API 키도 함께 구성하세요(예: `google/*`에는 `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`, `openai/*`에는 `OPENAI_API_KEY`, `fal/*`에는 `FAL_KEY`). - - 생략해도 `image_generate`는 인증이 설정된 공급자의 기본값을 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도하고, 그다음 나머지 등록된 이미지 생성 공급자를 공급자 ID 순서대로 시도합니다. + - 공용 이미지 생성 기능과 향후 이미지를 생성하는 모든 도구/플러그인 표면에서 사용됩니다. + - 일반적인 값: Gemini 기본 이미지 생성용 `google/gemini-3.1-flash-image-preview`, fal용 `fal/fal-ai/flux/dev`, OpenAI Images용 `openai/gpt-image-1`. + - 공급자/모델을 직접 선택하는 경우 해당 공급자의 인증/API 키도 함께 구성해야 합니다(예: `google/*`용 `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`, `openai/*`용 `OPENAI_API_KEY`, `fal/*`용 `FAL_KEY`). + - 생략해도 `image_generate`는 인증이 구성된 기본 공급자를 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도한 다음, 나머지 등록된 이미지 생성 공급자를 공급자 ID 순서대로 시도합니다. - `musicGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 음악 생성 기능과 내장 `music_generate` 도구에서 사용됩니다. - - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, 또는 `minimax/music-2.5+`. - - 생략해도 `music_generate`는 인증이 설정된 공급자의 기본값을 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도하고, 그다음 나머지 등록된 음악 생성 공급자를 공급자 ID 순서대로 시도합니다. - - 공급자/모델을 직접 선택하는 경우, 해당 공급자의 인증/API 키도 함께 구성하세요. + - 공용 음악 생성 기능과 내장 `music_generate` 도구에서 사용됩니다. + - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, `minimax/music-2.5+`. + - 생략해도 `music_generate`는 인증이 구성된 기본 공급자를 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도한 다음, 나머지 등록된 음악 생성 공급자를 공급자 ID 순서대로 시도합니다. + - 공급자/모델을 직접 선택하는 경우 해당 공급자의 인증/API 키도 함께 구성해야 합니다. - `videoGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 비디오 생성 기능과 내장 `video_generate` 도구에서 사용됩니다. - - 일반적인 값: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, 또는 `qwen/wan2.7-r2v`. - - 생략해도 `video_generate`는 인증이 설정된 공급자의 기본값을 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도하고, 그다음 나머지 등록된 비디오 생성 공급자를 공급자 ID 순서대로 시도합니다. - - 공급자/모델을 직접 선택하는 경우, 해당 공급자의 인증/API 키도 함께 구성하세요. - - 번들된 Qwen 비디오 생성 공급자는 최대 출력 비디오 1개, 입력 이미지 1개, 입력 비디오 4개, 길이 10초, 그리고 공급자 수준의 `size`, `aspectRatio`, `resolution`, `audio`, `watermark` 옵션을 지원합니다. + - 공용 비디오 생성 기능과 내장 `video_generate` 도구에서 사용됩니다. + - 일반적인 값: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, `qwen/wan2.7-r2v`. + - 생략해도 `video_generate`는 인증이 구성된 기본 공급자를 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도한 다음, 나머지 등록된 비디오 생성 공급자를 공급자 ID 순서대로 시도합니다. + - 공급자/모델을 직접 선택하는 경우 해당 공급자의 인증/API 키도 함께 구성해야 합니다. + - 번들 Qwen 비디오 생성 공급자는 출력 비디오 최대 1개, 입력 이미지 1개, 입력 비디오 4개, 길이 10초, 그리고 공급자 수준 `size`, `aspectRatio`, `resolution`, `audio`, `watermark` 옵션을 지원합니다. - `pdfModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - `pdf` 도구의 모델 라우팅에 사용됩니다. - - 생략하면 PDF 도구는 먼저 `imageModel`, 그다음 확인된 세션/기본 모델로 대체됩니다. -- `pdfMaxBytesMb`: 호출 시점에 `maxBytesMb`가 전달되지 않았을 때 `pdf` 도구에 적용되는 기본 PDF 크기 제한입니다. + - 생략하면 PDF 도구는 `imageModel`로 대체한 다음, 해결된 세션/기본 모델로 대체합니다. +- `pdfMaxBytesMb`: 호출 시 `maxBytesMb`가 전달되지 않았을 때 `pdf` 도구에 적용되는 기본 PDF 크기 제한입니다. - `pdfMaxPages`: `pdf` 도구의 추출 대체 모드에서 고려하는 기본 최대 페이지 수입니다. -- `verboseDefault`: 에이전트의 기본 verbose 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. -- `elevatedDefault`: 에이전트의 기본 elevated 출력 수준입니다. 값: `"off"`, `"on"`, `"ask"`, `"full"`. 기본값: `"on"`. -- `model.primary`: 형식은 `provider/model`입니다(예: `openai/gpt-5.4`). 공급자를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 해당 정확한 모델 ID에 대한 고유한 구성 공급자 일치를 시도하며, 마지막으로만 구성된 기본 공급자로 대체합니다(더 이상 권장되지 않는 호환성 동작이므로 명시적인 `provider/model`을 권장). 해당 공급자가 더 이상 구성된 기본 모델을 제공하지 않으면, OpenClaw는 오래된 제거된 공급자 기본값을 그대로 노출하는 대신 첫 번째 구성된 공급자/모델로 대체합니다. -- `models`: `/model`용으로 구성된 모델 카탈로그 및 허용 목록입니다. 각 항목은 `alias`(바로가기)와 `params`(공급자별 설정, 예: `temperature`, `maxTokens`, `cacheRetention`, `context1m`)를 포함할 수 있습니다. +- `verboseDefault`: 에이전트의 기본 자세한 출력 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. +- `elevatedDefault`: 에이전트의 기본 고급 출력 수준입니다. 값: `"off"`, `"on"`, `"ask"`, `"full"`. 기본값: `"on"`. +- `model.primary`: 형식은 `provider/model`입니다(예: `openai/gpt-5.4`). 공급자를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 해당 정확한 모델 ID에 대해 고유하게 구성된 공급자 일치를 시도한 후, 마지막으로 구성된 기본 공급자로 대체합니다(더 이상 권장되지 않는 호환 동작이므로 명시적인 `provider/model` 사용 권장). 해당 공급자가 더 이상 구성된 기본 모델을 제공하지 않으면, OpenClaw는 오래된 제거된 공급자 기본값을 노출하는 대신 첫 번째 구성된 공급자/모델로 대체합니다. +- `models`: `/model`용 구성된 모델 카탈로그 및 허용 목록입니다. 각 항목에는 `alias`(단축 이름)와 `params`(공급자별, 예: `temperature`, `maxTokens`, `cacheRetention`, `context1m`)를 포함할 수 있습니다. - `params`: 모든 모델에 적용되는 전역 기본 공급자 매개변수입니다. `agents.defaults.params`에 설정합니다(예: `{ cacheRetention: "long" }`). -- `params` 병합 우선순위(구성): `agents.defaults.params`(전역 기본값)는 `agents.defaults.models["provider/model"].params`(모델별)로 재정의되고, 이후 `agents.list[].params`(일치하는 에이전트 ID)가 키별로 재정의합니다. 자세한 내용은 [프롬프트 캐싱](/ko/reference/prompt-caching)을 참조하세요. -- `embeddedHarness`: 기본 저수준 임베디드 에이전트 런타임 정책입니다. 지원되는 모델에 대해 등록된 플러그인 harness가 처리하도록 하려면 `runtime: "auto"`를 사용하고, 내장 PI harness를 강제하려면 `runtime: "pi"`를 사용하며, 등록된 harness ID(예: `runtime: "codex"`)도 사용할 수 있습니다. 자동 PI 대체를 비활성화하려면 `fallback: "none"`을 설정하세요. -- 이 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, 장애 조치 추가/제거 명령)는 정식 객체 형식으로 저장하고 가능한 경우 기존 장애 조치 목록을 유지합니다. -- `maxConcurrent`: 세션 간 최대 병렬 에이전트 실행 수입니다(각 세션은 여전히 직렬화됨). 기본값: 4. +- `params` 병합 우선순위(구성): `agents.defaults.params`(전역 기본) 위에 `agents.defaults.models["provider/model"].params`(모델별)가 덮어쓰고, 그다음 `agents.list[].params`(일치하는 에이전트 ID)가 키별로 덮어씁니다. 자세한 내용은 [Prompt Caching](/ko/reference/prompt-caching)을 참고하세요. +- `embeddedHarness`: 기본 저수준 내장 에이전트 런타임 정책입니다. 등록된 플러그인 harness가 지원되는 모델을 선택하도록 하려면 `runtime: "auto"`를, 내장 Pi harness를 강제하려면 `runtime: "pi"`를, `runtime: "codex"`처럼 등록된 harness ID를 사용하세요. 자동 Pi 대체를 비활성화하려면 `fallback: "none"`으로 설정하세요. +- 이 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, 장애 조치 추가/제거 명령)는 정식 객체 형식으로 저장하며, 가능하면 기존 장애 조치 목록을 보존합니다. +- `maxConcurrent`: 세션 전체에서 동시에 실행할 수 있는 최대 병렬 에이전트 실행 수입니다(각 세션은 여전히 직렬화됨). 기본값: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness`는 어떤 저수준 실행기가 임베디드 에이전트 턴을 실행할지 제어합니다. -대부분의 배포에서는 기본값 `{ runtime: "auto", fallback: "pi" }`를 유지하는 것이 좋습니다. -번들된 Codex app-server harness처럼 신뢰할 수 있는 플러그인이 네이티브 harness를 제공할 때 사용하세요. +`embeddedHarness`는 어떤 저수준 실행기가 내장 에이전트 턴을 실행할지 제어합니다. +대부분의 배포에서는 기본값 `{ runtime: "auto", fallback: "pi" }`를 유지하면 됩니다. +번들 Codex 앱 서버 harness처럼 신뢰할 수 있는 Plugin이 네이티브 harness를 제공할 때 사용하세요. ```json5 { @@ -1125,13 +1123,13 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 } ``` -- `runtime`: `"auto"`, `"pi"`, 또는 등록된 플러그인 harness ID입니다. 번들된 Codex 플러그인은 `codex`를 등록합니다. -- `fallback`: `"pi"` 또는 `"none"`입니다. `"pi"`는 내장 PI harness를 호환성 대체값으로 유지합니다. `"none"`은 누락되었거나 지원되지 않는 플러그인 harness 선택 시 조용히 PI를 사용하는 대신 실패하게 합니다. -- 환경 변수 재정의: `OPENCLAW_AGENT_RUNTIME=`는 `runtime`을 재정의하고, `OPENCLAW_AGENT_HARNESS_FALLBACK=none`은 해당 프로세스에서 PI 대체를 비활성화합니다. +- `runtime`: `"auto"`, `"pi"`, 또는 등록된 플러그인 harness ID입니다. 번들 Codex Plugin은 `codex`를 등록합니다. +- `fallback`: `"pi"` 또는 `"none"`입니다. `"pi"`는 내장 Pi harness를 호환성 대체 경로로 유지합니다. `"none"`은 누락되었거나 지원되지 않는 Plugin harness 선택 시 조용히 Pi를 사용하는 대신 실패하게 만듭니다. +- 환경 변수 재정의: `OPENCLAW_AGENT_RUNTIME=`는 `runtime`을 재정의하고, `OPENCLAW_AGENT_HARNESS_FALLBACK=none`은 해당 프로세스에서 Pi 대체를 비활성화합니다. - Codex 전용 배포의 경우 `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"`, `embeddedHarness.fallback: "none"`으로 설정하세요. -- 이것은 임베디드 채팅 harness만 제어합니다. 미디어 생성, 비전, PDF, 음악, 비디오, TTS는 여전히 해당 공급자/모델 설정을 사용합니다. +- 이것은 내장 채팅 harness만 제어합니다. 미디어 생성, 비전, PDF, 음악, 비디오, TTS는 계속 해당 공급자/모델 설정을 사용합니다. -**내장 별칭 축약형** (`agents.defaults.models`에 모델이 있을 때만 적용): +**내장 별칭 단축 이름**(`agents.defaults.models`에 모델이 있을 때만 적용): | 별칭 | 모델 | | ------------------- | -------------------------------------- | @@ -1144,11 +1142,11 @@ bootstrap 컨텍스트가 잘릴 때 에이전트에 보이는 경고 텍스트 | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -사용자가 구성한 별칭은 항상 기본값보다 우선합니다. +구성한 별칭은 항상 기본값보다 우선합니다. Z.AI GLM-4.x 모델은 `--thinking off`를 설정하거나 `agents.defaults.models["zai/"].params.thinking`을 직접 정의하지 않는 한 자동으로 thinking 모드를 활성화합니다. Z.AI 모델은 도구 호출 스트리밍을 위해 기본적으로 `tool_stream`을 활성화합니다. 비활성화하려면 `agents.defaults.models["zai/"].params.tool_stream`을 `false`로 설정하세요. -Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않았을 때 기본적으로 `adaptive` thinking을 사용합니다. +Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않으면 기본적으로 `adaptive` thinking을 사용합니다. ### `agents.defaults.cliBackends` @@ -1181,12 +1179,12 @@ Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않 ``` - CLI 백엔드는 텍스트 우선이며, 도구는 항상 비활성화됩니다. -- `sessionArg`가 설정된 경우 세션을 지원합니다. -- `imageArg`가 파일 경로를 받을 수 있으면 이미지 전달을 지원합니다. +- `sessionArg`가 설정되면 세션이 지원됩니다. +- `imageArg`가 파일 경로를 받을 수 있으면 이미지 전달도 지원됩니다. ### `agents.defaults.systemPromptOverride` -OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대체합니다. 기본 수준(`agents.defaults.systemPromptOverride`) 또는 에이전트별(`agents.list[].systemPromptOverride`)로 설정할 수 있습니다. 에이전트별 값이 우선하며, 빈 문자열 또는 공백만 있는 값은 무시됩니다. 제어된 프롬프트 실험에 유용합니다. +OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대체합니다. 기본 수준(`agents.defaults.systemPromptOverride`) 또는 에이전트별(`agents.list[].systemPromptOverride`)로 설정할 수 있습니다. 에이전트별 값이 우선하며, 비어 있거나 공백만 있는 값은 무시됩니다. 제어된 프롬프트 실험에 유용합니다. ```json5 { @@ -1200,23 +1198,23 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 ### `agents.defaults.heartbeat` -주기적인 heartbeat 실행입니다. +주기적인 Heartbeat 실행입니다. ```json5 { agents: { defaults: { heartbeat: { - every: "30m", // 0m이면 비활성화 + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // 기본값: true; false이면 시스템 프롬프트에서 Heartbeat 섹션 생략 - lightContext: false, // 기본값: false; true이면 workspace bootstrap 파일 중 HEARTBEAT.md만 유지 - isolatedSession: false, // 기본값: false; true이면 각 heartbeat를 새 세션에서 실행(대화 기록 없음) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (기본값) | block - target: "none", // 기본값: none | 옵션: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1228,14 +1226,14 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 ``` - `every`: 기간 문자열(ms/s/m/h)입니다. 기본값: `30m`(API 키 인증) 또는 `1h`(OAuth 인증). 비활성화하려면 `0m`으로 설정하세요. -- `includeSystemPromptSection`: false이면 시스템 프롬프트에서 Heartbeat 섹션을 생략하고 bootstrap 컨텍스트에 `HEARTBEAT.md`를 삽입하지 않습니다. 기본값: `true`. -- `suppressToolErrorWarnings`: true이면 heartbeat 실행 중 도구 오류 경고 페이로드를 숨깁니다. -- `timeoutSeconds`: heartbeat 에이전트 턴이 중단되기 전까지 허용되는 최대 시간(초)입니다. 설정하지 않으면 `agents.defaults.timeoutSeconds`를 사용합니다. -- `directPolicy`: direct/DM 전달 정책입니다. `allow`(기본값)는 direct 대상 전달을 허용합니다. `block`은 direct 대상 전달을 억제하고 `reason=dm-blocked`를 출력합니다. -- `lightContext`: true이면 heartbeat 실행은 경량 bootstrap 컨텍스트를 사용하고 workspace bootstrap 파일 중 `HEARTBEAT.md`만 유지합니다. -- `isolatedSession`: true이면 각 heartbeat를 이전 대화 기록이 없는 새 세션에서 실행합니다. cron `sessionTarget: "isolated"`와 동일한 격리 패턴입니다. heartbeat당 토큰 비용을 약 100K에서 약 2~5K 토큰으로 줄입니다. -- 에이전트별 설정: `agents.list[].heartbeat`를 사용하세요. 어떤 에이전트든 `heartbeat`를 정의하면 **그 에이전트들만** heartbeat를 실행합니다. -- heartbeat는 완전한 에이전트 턴을 실행하므로, 간격이 짧을수록 더 많은 토큰을 사용합니다. +- `includeSystemPromptSection`: false이면 시스템 프롬프트에서 Heartbeat 섹션을 생략하고 bootstrap 컨텍스트에 `HEARTBEAT.md`를 주입하지 않습니다. 기본값: `true`. +- `suppressToolErrorWarnings`: true이면 Heartbeat 실행 중 도구 오류 경고 페이로드를 숨깁니다. +- `timeoutSeconds`: Heartbeat 에이전트 턴이 중단되기 전까지 허용되는 최대 시간(초)입니다. 설정하지 않으면 `agents.defaults.timeoutSeconds`를 사용합니다. +- `directPolicy`: 직접/DM 전달 정책입니다. `allow`(기본값)는 직접 대상 전달을 허용합니다. `block`은 직접 대상 전달을 막고 `reason=dm-blocked`를 출력합니다. +- `lightContext`: true이면 Heartbeat 실행은 경량 bootstrap 컨텍스트를 사용하고 workspace bootstrap 파일 중 `HEARTBEAT.md`만 유지합니다. +- `isolatedSession`: true이면 각 Heartbeat는 이전 대화 기록이 없는 새 세션에서 실행됩니다. Cron `sessionTarget: "isolated"`와 동일한 격리 패턴입니다. Heartbeat당 토큰 비용을 약 100K에서 약 2-5K 토큰으로 줄입니다. +- 에이전트별 설정: `agents.list[].heartbeat`를 설정하세요. 어떤 에이전트든 `heartbeat`를 정의하면 **그 에이전트들만** Heartbeat를 실행합니다. +- Heartbeat는 전체 에이전트 턴을 실행하므로, 간격이 짧을수록 더 많은 토큰을 사용합니다. ### `agents.defaults.compaction` @@ -1245,19 +1243,19 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 등록된 compaction provider 플러그인의 ID(선택 사항) + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "배포 ID, 티켓 ID, host:port 쌍을 정확히 보존하세요.", // identifierPolicy=custom일 때 사용 - postCompactionSections: ["Session Startup", "Red Lines"], // []이면 재삽입 비활성화 - model: "openrouter/anthropic/claude-sonnet-4-6", // 선택적 compaction 전용 모델 재정의 - notifyUser: true, // compaction 시작 시 간단한 알림 전송(기본값: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send a brief notice when compaction starts (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "세션이 곧 compaction에 도달합니다. 지금 지속될 메모리를 저장하세요.", - prompt: "lasting note가 있으면 memory/YYYY-MM-DD.md에 기록하고, 저장할 내용이 없으면 정확한 silent token NO_REPLY로 응답하세요.", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1265,19 +1263,19 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 } ``` -- `mode`: `default` 또는 `safeguard`(긴 기록에 대한 청크형 요약)입니다. [Compaction](/ko/concepts/compaction)을 참조하세요. -- `provider`: 등록된 compaction provider 플러그인의 ID입니다. 설정하면 내장 LLM 요약 대신 해당 provider의 `summarize()`가 호출됩니다. 실패 시 내장 방식으로 대체됩니다. provider를 설정하면 `mode: "safeguard"`가 강제됩니다. [Compaction](/ko/concepts/compaction)을 참조하세요. -- `timeoutSeconds`: OpenClaw가 중단하기 전 단일 compaction 작업에 허용되는 최대 시간(초)입니다. 기본값: `900`. -- `identifierPolicy`: `strict`(기본값), `off`, 또는 `custom`입니다. `strict`는 compaction 요약 중 내장된 불투명 식별자 보존 지침을 앞에 추가합니다. -- `identifierInstructions`: `identifierPolicy=custom`일 때 사용되는 선택적 사용자 지정 식별자 보존 텍스트입니다. -- `postCompactionSections`: compaction 후 다시 주입할 선택적 AGENTS.md H2/H3 섹션 이름입니다. 기본값은 `["Session Startup", "Red Lines"]`이며, 재삽입을 비활성화하려면 `[]`로 설정하세요. 설정하지 않았거나 해당 기본 쌍으로 명시적으로 설정한 경우, 이전 `Every Session`/`Safety` 제목도 레거시 대체값으로 허용됩니다. -- `model`: compaction 요약에만 적용되는 선택적 `provider/model-id` 재정의입니다. 메인 세션은 한 모델을 유지하면서 compaction 요약은 다른 모델에서 실행해야 할 때 사용합니다. 설정하지 않으면 compaction은 세션의 기본 모델을 사용합니다. -- `notifyUser`: `true`이면 compaction이 시작될 때 사용자에게 간단한 알림(예: "컨텍스트를 압축하는 중...")을 보냅니다. 기본적으로는 compaction을 조용히 유지하기 위해 비활성화되어 있습니다. -- `memoryFlush`: 자동 compaction 전에 지속될 메모리를 저장하는 무음 에이전트 턴입니다. workspace가 읽기 전용이면 건너뜁니다. +- `mode`: `default` 또는 `safeguard`(긴 기록을 위한 청크 기반 요약). [Compaction](/ko/concepts/compaction)을 참고하세요. +- `provider`: 등록된 Compaction provider Plugin의 ID입니다. 설정되면 내장 LLM 요약 대신 해당 공급자의 `summarize()`가 호출됩니다. 실패하면 내장 방식으로 대체됩니다. 공급자를 설정하면 `mode: "safeguard"`가 강제됩니다. [Compaction](/ko/concepts/compaction)을 참고하세요. +- `timeoutSeconds`: 단일 Compaction 작업에 OpenClaw가 중단하기 전까지 허용하는 최대 시간(초)입니다. 기본값: `900`. +- `identifierPolicy`: `strict`(기본값), `off`, 또는 `custom`. `strict`는 Compaction 요약 중 내장된 불투명 식별자 보존 지침을 앞에 추가합니다. +- `identifierInstructions`: `identifierPolicy=custom`일 때 사용하는 선택적 사용자 지정 식별자 보존 텍스트입니다. +- `postCompactionSections`: Compaction 후 다시 주입할 선택적 `AGENTS.md` H2/H3 섹션 이름입니다. 기본값은 `["Session Startup", "Red Lines"]`이며, 재주입을 비활성화하려면 `[]`로 설정하세요. 설정하지 않았거나 이 기본 쌍으로 명시적으로 설정한 경우, 이전 `Every Session`/`Safety` 제목도 레거시 대체값으로 허용됩니다. +- `model`: Compaction 요약 전용의 선택적 `provider/model-id` 재정의입니다. 기본 세션은 한 모델을 유지하되 Compaction 요약은 다른 모델에서 실행하려면 이것을 사용하세요. 설정하지 않으면 Compaction은 세션의 기본 모델을 사용합니다. +- `notifyUser`: `true`이면 Compaction 시작 시 사용자에게 짧은 알림을 보냅니다(예: "Compacting context..."). 기본적으로는 Compaction을 조용히 유지하기 위해 비활성화되어 있습니다. +- `memoryFlush`: 자동 Compaction 전에 지속 메모리를 저장하는 조용한 agentic 턴입니다. workspace가 읽기 전용이면 건너뜁니다. ### `agents.defaults.contextPruning` -LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결과**를 가지치기합니다. 디스크에 있는 세션 기록은 수정하지 않습니다. +LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결과**를 잘라냅니다. 디스크의 세션 기록은 수정하지 않습니다. ```json5 { @@ -1285,13 +1283,13 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // 기간(ms/s/m/h), 기본 단위: 분 + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[이전 도구 결과 내용이 지워졌습니다]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1301,23 +1299,23 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 -- `mode: "cache-ttl"`은 가지치기 패스를 활성화합니다. -- `ttl`은 마지막 캐시 터치 이후 언제 다시 가지치기를 실행할 수 있는지 제어합니다. -- 필요 시 가지치기는 먼저 큰 도구 결과를 soft-trim하고, 그다음 오래된 도구 결과를 hard-clear합니다. +- `mode: "cache-ttl"`은 잘라내기 패스를 활성화합니다. +- `ttl`은 잘라내기를 다시 실행할 수 있는 주기를 제어합니다(마지막 캐시 접근 이후). +- 잘라내기는 먼저 큰 도구 결과를 soft-trim한 다음, 필요하면 더 오래된 도구 결과를 hard-clear합니다. -**Soft-trim**은 시작 부분과 끝 부분을 유지하고 중간에 `...`를 삽입합니다. +**Soft-trim**은 시작과 끝을 유지하고 중간에 `...`를 삽입합니다. **Hard-clear**는 전체 도구 결과를 placeholder로 대체합니다. 참고: - 이미지 블록은 절대 잘리거나 지워지지 않습니다. -- 비율은 정확한 토큰 수가 아니라 문자 수 기준(대략적)입니다. -- assistant 메시지가 `keepLastAssistants`보다 적으면 가지치기를 건너뜁니다. +- 비율은 문자 기반(대략적)이며, 정확한 토큰 수가 아닙니다. +- `keepLastAssistants`보다 적은 assistant 메시지만 있으면 잘라내기를 건너뜁니다. -동작 세부 사항은 [세션 가지치기](/ko/concepts/session-pruning)를 참조하세요. +동작 세부 정보는 [Session Pruning](/ko/concepts/session-pruning)을 참고하세요. ### 블록 스트리밍 @@ -1329,17 +1327,17 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (minMs/maxMs 사용) + humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) }, }, } ``` - Telegram이 아닌 채널은 블록 응답을 활성화하려면 명시적으로 `*.blockStreaming: true`가 필요합니다. -- 채널 재정의: `channels..blockStreamingCoalesce`(및 계정별 변형). Signal/Slack/Discord/Google Chat의 기본 `minChars`는 `1500`입니다. -- `humanDelay`: 블록 응답 사이의 무작위 지연입니다. `natural` = 800–2500ms. 에이전트별 재정의: `agents.list[].humanDelay`. +- 채널 재정의: `channels..blockStreamingCoalesce`(및 계정별 변형). Signal/Slack/Discord/Google Chat의 기본값은 `minChars: 1500`입니다. +- `humanDelay`: 블록 응답 사이의 무작위 일시정지입니다. `natural` = 800–2500ms. 에이전트별 재정의: `agents.list[].humanDelay`. -동작 및 청크 세부 사항은 [Streaming](/ko/concepts/streaming)을 참조하세요. +동작 및 청크 세부 정보는 [Streaming](/ko/concepts/streaming)을 참고하세요. ### 입력 중 표시기 @@ -1354,16 +1352,16 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 } ``` -- 기본값: direct 채팅/멘션에는 `instant`, 멘션되지 않은 그룹 채팅에는 `message`입니다. +- 기본값: 직접 채팅/멘션에는 `instant`, 멘션되지 않은 그룹 채팅에는 `message`. - 세션별 재정의: `session.typingMode`, `session.typingIntervalSeconds`. -[입력 중 표시기](/ko/concepts/typing-indicators)를 참조하세요. +[Typing Indicators](/ko/concepts/typing-indicators)를 참고하세요. ### `agents.defaults.sandbox` -임베디드 에이전트를 위한 선택적 sandboxing입니다. 전체 가이드는 [Sandboxing](/ko/gateway/sandboxing)을 참조하세요. +내장 에이전트를 위한 선택적 sandboxing입니다. 전체 가이드는 [Sandboxing](/ko/gateway/sandboxing)을 참고하세요. ```json5 { @@ -1409,7 +1407,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRef / 인라인 내용도 지원: + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1463,7 +1461,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 **백엔드:** - `docker`: 로컬 Docker 런타임(기본값) -- `ssh`: 범용 SSH 기반 원격 런타임 +- `ssh`: 일반 SSH 기반 원격 런타임 - `openshell`: OpenShell 런타임 `backend: "openshell"`을 선택하면 런타임별 설정은 @@ -1475,27 +1473,27 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 - `command`: SSH 클라이언트 명령(기본값: `ssh`) - `workspaceRoot`: 범위별 workspace에 사용되는 절대 원격 루트 - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH에 전달되는 기존 로컬 파일 -- `identityData` / `certificateData` / `knownHostsData`: 런타임에 OpenClaw가 임시 파일로 구체화하는 인라인 내용 또는 SecretRef -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH 호스트 키 정책 옵션 +- `identityData` / `certificateData` / `knownHostsData`: OpenClaw가 런타임에 임시 파일로 구체화하는 인라인 내용 또는 SecretRef +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH 호스트 키 정책 제어 항목 **SSH 인증 우선순위:** - `identityData`가 `identityFile`보다 우선합니다 - `certificateData`가 `certificateFile`보다 우선합니다 - `knownHostsData`가 `knownHostsFile`보다 우선합니다 -- SecretRef 기반 `*Data` 값은 sandbox 세션이 시작되기 전에 활성 secrets 런타임 스냅샷에서 해석됩니다 +- SecretRef 기반 `*Data` 값은 sandbox 세션 시작 전에 활성 secrets 런타임 스냅샷에서 확인됩니다 **SSH 백엔드 동작:** - 생성 또는 재생성 후 원격 workspace를 한 번 시드합니다 -- 이후 원격 SSH workspace를 정식 상태로 유지합니다 +- 이후 원격 SSH workspace를 기준 상태로 유지합니다 - `exec`, 파일 도구, 미디어 경로를 SSH를 통해 라우팅합니다 - 원격 변경 사항을 호스트로 자동 동기화하지 않습니다 -- sandbox browser 컨테이너를 지원하지 않습니다 +- sandbox 브라우저 컨테이너를 지원하지 않습니다 -**Workspace 액세스:** +**Workspace 접근:** -- `none`: `~/.openclaw/sandboxes` 아래 범위별 sandbox workspace +- `none`: `~/.openclaw/sandboxes` 아래의 범위별 sandbox workspace - `ro`: `/workspace`의 sandbox workspace, `/agent`에 읽기 전용으로 마운트된 agent workspace - `rw`: `/workspace`에 읽기/쓰기로 마운트된 agent workspace @@ -1505,7 +1503,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 - `agent`: 에이전트별 컨테이너 + workspace 1개(기본값) - `shared`: 공유 컨테이너 및 workspace(세션 간 격리 없음) -**OpenShell 플러그인 구성:** +**OpenShell Plugin 구성:** ```json5 { @@ -1518,10 +1516,10 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // 선택 사항 - gatewayEndpoint: "https://lab.example", // 선택 사항 - policy: "strict", // 선택적 OpenShell 정책 ID - providers: ["openai"], // 선택 사항 + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1533,32 +1531,32 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 **OpenShell 모드:** -- `mirror`: exec 전에 로컬에서 원격으로 시드하고, exec 후 다시 동기화합니다. 로컬 workspace가 정식 상태를 유지합니다 -- `remote`: sandbox가 생성될 때 원격을 한 번 시드한 뒤, 원격 workspace를 정식 상태로 유지합니다 +- `mirror`: 실행 전 원격을 로컬에서 시드하고, 실행 후 다시 동기화합니다. 로컬 workspace가 기준 상태로 유지됩니다 +- `remote`: sandbox가 생성될 때 원격을 한 번 시드하고, 이후 원격 workspace를 기준 상태로 유지합니다 -`remote` 모드에서는 OpenClaw 외부에서 이루어진 호스트 로컬 편집은 시드 단계 이후 sandbox로 자동 동기화되지 않습니다. -전송은 OpenShell sandbox로의 SSH를 사용하지만, 플러그인이 sandbox 생명주기와 선택적 mirror 동기화를 관리합니다. +`remote` 모드에서는 OpenClaw 외부에서 수행된 호스트 로컬 편집 내용이 시드 단계 이후 sandbox로 자동 동기화되지 않습니다. +전송은 OpenShell sandbox로의 SSH이지만, sandbox 수명 주기와 선택적 미러 동기화는 Plugin이 관리합니다. **`setupCommand`**는 컨테이너 생성 후 한 번 실행됩니다(`sh -lc` 사용). 네트워크 송신, 쓰기 가능한 루트, 루트 사용자가 필요합니다. -**컨테이너의 기본값은 `network: "none"`**입니다. 에이전트에 외부 액세스가 필요하면 `"bridge"`(또는 사용자 지정 브리지 네트워크)로 설정하세요. -`"host"`는 차단됩니다. `"container:"`는 기본적으로 차단되며, -명시적으로 `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`를 설정한 경우에만 허용됩니다(비상용). +**컨테이너의 기본값은 `network: "none"`**입니다 — 에이전트가 외부 접근이 필요하면 `"bridge"`(또는 사용자 지정 브리지 네트워크)로 설정하세요. +`"host"`는 차단됩니다. `"container:"`는 기본적으로 차단되며, 명시적으로 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`를 설정한 경우에만 허용됩니다(비상용). **인바운드 첨부 파일**은 활성 workspace의 `media/inbound/*`에 스테이징됩니다. -**`docker.binds`**는 추가 호스트 디렉터리를 마운트하며, 전역 및 에이전트별 bind가 병합됩니다. +**`docker.binds`**는 추가 호스트 디렉터리를 마운트합니다. 전역 및 에이전트별 바인드는 병합됩니다. -**샌드박스 브라우저**(`sandbox.browser.enabled`): 컨테이너 안에서 Chromium + CDP를 실행합니다. noVNC URL이 시스템 프롬프트에 삽입됩니다. `openclaw.json`에서 `browser.enabled`는 필요하지 않습니다. -noVNC 관찰자 액세스는 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 짧은 수명의 토큰 URL을 출력합니다. +**Sandbox된 브라우저**(`sandbox.browser.enabled`): 컨테이너 안의 Chromium + CDP입니다. noVNC URL이 시스템 프롬프트에 주입됩니다. `openclaw.json`에서 `browser.enabled`는 필요하지 않습니다. +noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 짧은 수명의 토큰 URL을 발급합니다. -- `allowHostControl: false`(기본값)는 샌드박스 세션이 호스트 브라우저를 대상으로 하는 것을 차단합니다. -- `network`의 기본값은 `openclaw-sandbox-browser`(전용 브리지 네트워크)입니다. 전역 브리지 연결이 명시적으로 필요한 경우에만 `bridge`로 설정하세요. -- `cdpSourceRange`는 선택적으로 컨테이너 가장자리에서 CDP 인바운드를 CIDR 범위(예: `172.21.0.1/32`)로 제한합니다. -- `sandbox.browser.binds`는 추가 호스트 디렉터리를 샌드박스 브라우저 컨테이너에만 마운트합니다. 설정되면(`[]` 포함) 브라우저 컨테이너에서는 `docker.binds`를 대체합니다. +- `allowHostControl: false`(기본값)는 sandbox된 세션이 호스트 브라우저를 대상으로 삼는 것을 차단합니다. +- `network`의 기본값은 `openclaw-sandbox-browser`(전용 브리지 네트워크)입니다. 전역 브리지 연결을 명시적으로 원할 때만 `bridge`로 설정하세요. +- `cdpSourceRange`는 선택적으로 컨테이너 경계에서 CDP 인바운드를 CIDR 범위(예: `172.21.0.1/32`)로 제한합니다. +- `sandbox.browser.binds`는 추가 호스트 디렉터리를 브라우저 sandbox 컨테이너에만 마운트합니다. 설정되면(`[]` 포함) 브라우저 컨테이너에서는 `docker.binds`를 대체합니다. - 실행 기본값은 `scripts/sandbox-browser-entrypoint.sh`에 정의되어 있으며 컨테이너 호스트에 맞게 조정되어 있습니다: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -1574,21 +1572,21 @@ noVNC 관찰자 액세스는 기본적으로 VNC 인증을 사용하며, OpenCla - `--no-zygote` - `--metrics-recording-only` - `--disable-extensions`(기본적으로 활성화됨) - - `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`는 기본적으로 활성화되며, WebGL/3D 사용에 필요하면 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`으로 비활성화할 수 있습니다. - - 워크플로가 확장 프로그램에 의존하는 경우 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`이 확장 프로그램을 다시 활성화합니다. - - `--renderer-process-limit=2`는 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`으로 변경할 수 있으며, Chromium 기본 프로세스 제한을 사용하려면 `0`으로 설정하세요. - - `noSandbox`가 활성화된 경우 `--no-sandbox` 및 `--disable-setuid-sandbox`도 추가됩니다. - - 기본값은 컨테이너 이미지 기준선입니다. 컨테이너 기본값을 변경하려면 사용자 지정 엔트리포인트가 있는 사용자 지정 브라우저 이미지를 사용하세요. + - `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`는 기본적으로 활성화되어 있으며, WebGL/3D 사용에 필요하면 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`으로 비활성화할 수 있습니다. + - 워크플로가 확장 기능에 의존하면 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`으로 확장 기능을 다시 활성화합니다. + - `--renderer-process-limit=2`는 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`으로 변경할 수 있습니다. Chromium 기본 프로세스 제한을 사용하려면 `0`으로 설정하세요. + - `noSandbox`가 활성화되면 `--no-sandbox`와 `--disable-setuid-sandbox`도 추가됩니다. + - 기본값은 컨테이너 이미지 기준선입니다. 컨테이너 기본값을 변경하려면 사용자 지정 entrypoint가 있는 사용자 지정 브라우저 이미지를 사용하세요. -브라우저 샌드박싱과 `sandbox.docker.binds`는 Docker 전용입니다. +브라우저 sandboxing과 `sandbox.docker.binds`는 Docker 전용입니다. 이미지 빌드: ```bash -scripts/sandbox-setup.sh # 기본 sandbox 이미지 -scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` ### `agents.list`(에이전트별 재정의) @@ -1603,13 +1601,13 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // 또는 { primary, fallbacks } - thinkingDefault: "high", // 에이전트별 기본 thinking 수준 재정의 - reasoningDefault: "on", // 에이전트별 기본 reasoning 가시성 재정의 - fastModeDefault: false, // 에이전트별 기본 fast mode 재정의 + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // 일치하는 defaults.models params를 키별로 재정의 - skills: ["docs-search"], // 설정 시 agents.defaults.skills를 대체 + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1640,27 +1638,27 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 } ``` -- `id`: 안정적인 에이전트 ID입니다(필수). -- `default`: 여러 개가 설정되면 첫 번째가 우선합니다(경고 로그 기록). 아무것도 설정되지 않으면 첫 번째 목록 항목이 기본값입니다. -- `model`: 문자열 형식은 `primary`만 재정의하고, 객체 형식 `{ primary, fallbacks }`는 둘 다 재정의합니다(`[]`는 전역 fallbacks 비활성화). `primary`만 재정의하는 cron 작업은 `fallbacks: []`를 설정하지 않는 한 기본 fallbacks를 계속 상속합니다. -- `params`: `agents.defaults.models`의 선택된 모델 항목 위에 병합되는 에이전트별 스트림 params입니다. 전체 모델 카탈로그를 복제하지 않고 `cacheRetention`, `temperature`, `maxTokens` 같은 에이전트별 재정의에 사용하세요. -- `skills`: 선택적 에이전트별 skill 허용 목록입니다. 생략하면 설정된 경우 에이전트가 `agents.defaults.skills`를 상속합니다. 명시적 목록은 병합되지 않고 기본값을 대체하며, `[]`는 skills가 없음을 의미합니다. -- `thinkingDefault`: 선택적 에이전트별 기본 thinking 수준(`off | minimal | low | medium | high | xhigh | adaptive`)입니다. 메시지별 또는 세션별 재정의가 없을 때 이 에이전트에 대해 `agents.defaults.thinkingDefault`를 재정의합니다. -- `reasoningDefault`: 선택적 에이전트별 기본 reasoning 가시성(`on | off | stream`)입니다. 메시지별 또는 세션별 reasoning 재정의가 없을 때 적용됩니다. -- `fastModeDefault`: 선택적 에이전트별 기본 fast mode 값(`true | false`)입니다. 메시지별 또는 세션별 fast-mode 재정의가 없을 때 적용됩니다. -- `embeddedHarness`: 선택적 에이전트별 저수준 harness 정책 재정의입니다. 한 에이전트를 Codex 전용으로 만들고 다른 에이전트는 기본 PI fallback을 유지하려면 `{ runtime: "codex", fallback: "none" }`를 사용하세요. -- `runtime`: 선택적 에이전트별 런타임 디스크립터입니다. 에이전트가 기본적으로 ACP harness 세션을 사용해야 하면 `type: "acp"`와 함께 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)을 사용하세요. -- `identity.avatar`: workspace 기준 상대 경로, `http(s)` URL, 또는 `data:` URI입니다. -- `identity`는 기본값을 파생합니다: `ackReaction`은 `emoji`에서, `mentionPatterns`는 `name`/`emoji`에서 파생됩니다. -- `subagents.allowAgents`: `sessions_spawn`용 에이전트 ID 허용 목록입니다(`["*"]` = 아무 에이전트나 허용, 기본값: 동일 에이전트만). -- 샌드박스 상속 가드: 요청한 세션이 샌드박스 상태이면 `sessions_spawn`은 샌드박스 없이 실행될 대상을 거부합니다. +- `id`: 안정적인 에이전트 ID(필수). +- `default`: 여러 개가 설정되면 첫 번째가 우선합니다(경고 로그 기록). 아무것도 설정되지 않으면 목록의 첫 번째 항목이 기본값입니다. +- `model`: 문자열 형식은 `primary`만 재정의하고, 객체 형식 `{ primary, fallbacks }`는 둘 다 재정의합니다(`[]`는 전역 대체 모델 비활성화). `primary`만 재정의하는 Cron 작업은 `fallbacks: []`를 설정하지 않는 한 여전히 기본 대체 모델을 상속합니다. +- `params`: `agents.defaults.models`의 선택된 모델 항목 위에 병합되는 에이전트별 스트림 매개변수입니다. 전체 모델 카탈로그를 복제하지 않고 `cacheRetention`, `temperature`, `maxTokens` 같은 에이전트별 재정의에 사용하세요. +- `skills`: 선택적 에이전트별 Skills 허용 목록입니다. 생략하면 설정된 경우 에이전트는 `agents.defaults.skills`를 상속합니다. 명시적 목록은 기본값과 병합되지 않고 대체하며, `[]`는 Skills 없음입니다. +- `thinkingDefault`: 선택적 에이전트별 기본 thinking 수준(`off | minimal | low | medium | high | xhigh | adaptive`)입니다. 메시지별 또는 세션 재정의가 없을 때 이 에이전트에 대해 `agents.defaults.thinkingDefault`를 재정의합니다. +- `reasoningDefault`: 선택적 에이전트별 기본 reasoning 표시 수준(`on | off | stream`)입니다. 메시지별 또는 세션 reasoning 재정의가 없을 때 적용됩니다. +- `fastModeDefault`: 선택적 에이전트별 fast mode 기본값(`true | false`)입니다. 메시지별 또는 세션 fast-mode 재정의가 없을 때 적용됩니다. +- `embeddedHarness`: 선택적 에이전트별 저수준 harness 정책 재정의입니다. 한 에이전트만 Codex 전용으로 만들고 다른 에이전트는 기본 Pi 대체를 유지하려면 `{ runtime: "codex", fallback: "none" }`를 사용하세요. +- `runtime`: 선택적 에이전트별 런타임 descriptor입니다. 에이전트가 기본적으로 ACP harness 세션을 사용해야 하면 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)과 함께 `type: "acp"`를 사용하세요. +- `identity.avatar`: workspace 상대 경로, `http(s)` URL 또는 `data:` URI. +- `identity`는 기본값을 파생합니다: `emoji`에서 `ackReaction`, `name`/`emoji`에서 `mentionPatterns`. +- `subagents.allowAgents`: `sessions_spawn`용 에이전트 ID 허용 목록(`["*"]` = 아무거나, 기본값: 동일 에이전트만). +- Sandbox 상속 가드: 요청 세션이 sandbox된 경우 `sessions_spawn`은 sandbox 없이 실행될 대상을 거부합니다. - `subagents.requireAgentId`: true이면 `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적 프로필 선택 강제, 기본값: false). --- ## 다중 에이전트 라우팅 -하나의 Gateway 안에서 여러 개의 격리된 에이전트를 실행합니다. [다중 에이전트](/ko/concepts/multi-agent)를 참조하세요. +하나의 Gateway 안에서 여러 개의 격리된 에이전트를 실행합니다. [Multi-Agent](/ko/concepts/multi-agent)를 참고하세요. ```json5 { @@ -1679,12 +1677,12 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 ### 바인딩 일치 필드 -- `type`(선택 사항): 일반 라우팅용 `route`(누락 시 기본값은 route), 영구 ACP 대화 바인딩용 `acp` +- `type`(선택 사항): 일반 라우팅에는 `route`(type이 없으면 기본값은 route), 영구 ACP 대화 바인딩에는 `acp`. - `match.channel`(필수) -- `match.accountId`(선택 사항; `*` = 모든 계정, 생략 = 기본 계정) -- `match.peer`(선택 사항; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId`(선택 사항; 채널별) -- `acp`(선택 사항; `type: "acp"`일 때만): `{ mode, label, cwd, backend }` +- `match.accountId`(선택 사항, `*` = 모든 계정, 생략 = 기본 계정) +- `match.peer`(선택 사항, `{ kind: direct|group|channel, id }`) +- `match.guildId` / `match.teamId`(선택 사항, 채널별) +- `acp`(선택 사항, `type: "acp"`일 때만): `{ mode, label, cwd, backend }` **결정적 일치 순서:** @@ -1695,13 +1693,13 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 5. `match.accountId: "*"`(채널 전체) 6. 기본 에이전트 -각 단계 안에서는 첫 번째로 일치하는 `bindings` 항목이 우선합니다. +각 계층 내에서는 첫 번째로 일치하는 `bindings` 항목이 우선합니다. -`type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 ID(`match.channel` + account + `match.peer.id`)로 확인하며, 위의 route 바인딩 단계 순서는 사용하지 않습니다. +`type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 식별자(`match.channel` + account + `match.peer.id`)로 해결하며, 위의 route 바인딩 계층 순서를 사용하지 않습니다. -### 에이전트별 액세스 프로필 +### 에이전트별 접근 프로필 - + ```json5 { @@ -1748,7 +1746,7 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 - + ```json5 { @@ -1794,7 +1792,7 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 -우선순위 세부 사항은 [다중 에이전트 Sandbox 및 도구](/ko/tools/multi-agent-sandbox-tools)를 참조하세요. +우선순위 세부 정보는 [Multi-Agent Sandbox & Tools](/ko/tools/multi-agent-sandbox-tools)를 참고하세요. --- @@ -1820,22 +1818,22 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 이 토큰 수를 초과하면 부모 스레드 fork 건너뜀(0이면 비활성화) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // 기간 또는 false - maxDiskBytes: "500mb", // 선택적 하드 예산 - highWaterBytes: "400mb", // 선택적 정리 목표 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 기본 비활성 자동 unfocus 시간(`0`이면 비활성화) - maxAgeHours: 0, // 기본 하드 최대 수명 시간(`0`이면 비활성화) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // 레거시(런타임은 항상 "main" 사용) + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1847,35 +1845,35 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 -- **`scope`**: 그룹 채팅 컨텍스트의 기본 세션 그룹화 전략입니다. - - `per-sender`(기본값): 채널 컨텍스트 내에서 각 발신자가 격리된 세션을 가집니다. +- **`scope`**: 그룹 채팅 컨텍스트를 위한 기본 세션 묶기 전략입니다. + - `per-sender`(기본값): 채널 컨텍스트 안에서 각 발신자가 격리된 세션을 가집니다. - `global`: 채널 컨텍스트의 모든 참여자가 하나의 세션을 공유합니다(공유 컨텍스트가 의도된 경우에만 사용). -- **`dmScope`**: DM을 그룹화하는 방식입니다. +- **`dmScope`**: DM을 묶는 방식입니다. - `main`: 모든 DM이 메인 세션을 공유합니다. - `per-peer`: 채널 전반에서 발신자 ID별로 격리합니다. - `per-channel-peer`: 채널 + 발신자별로 격리합니다(다중 사용자 받은편지함에 권장). - `per-account-channel-peer`: 계정 + 채널 + 발신자별로 격리합니다(다중 계정에 권장). -- **`identityLinks`**: 채널 간 세션 공유를 위해 정규 ID를 공급자 접두사가 붙은 peer에 매핑합니다. -- **`reset`**: 기본 reset 정책입니다. `daily`는 로컬 시간 `atHour`에 reset되고, `idle`은 `idleMinutes` 후 reset됩니다. 둘 다 구성되면 먼저 만료되는 쪽이 적용됩니다. -- **`resetByType`**: 유형별 재정의(`direct`, `group`, `thread`)입니다. 레거시 `dm`도 `direct`의 별칭으로 허용됩니다. +- **`identityLinks`**: 채널 간 세션 공유를 위해 정식 ID를 공급자 접두사가 붙은 피어에 매핑합니다. +- **`reset`**: 기본 재설정 정책입니다. `daily`는 로컬 시간 `atHour`에 재설정하고, `idle`은 `idleMinutes` 후 재설정합니다. 둘 다 구성된 경우 먼저 만료되는 쪽이 적용됩니다. +- **`resetByType`**: 유형별 재정의(`direct`, `group`, `thread`). 레거시 `dm`도 `direct`의 별칭으로 허용됩니다. - **`parentForkMaxTokens`**: 포크된 스레드 세션을 만들 때 허용되는 부모 세션 `totalTokens`의 최대값입니다(기본값 `100000`). - - 부모 `totalTokens`가 이 값을 초과하면 OpenClaw는 부모 transcript 기록을 상속하지 않고 새 스레드 세션을 시작합니다. + - 부모 `totalTokens`가 이 값을 초과하면 OpenClaw는 부모 transcript 기록을 상속하는 대신 새 스레드 세션을 시작합니다. - 이 가드를 비활성화하고 항상 부모 포크를 허용하려면 `0`으로 설정하세요. -- **`mainKey`**: 레거시 필드입니다. 런타임은 메인 direct-chat 버킷에 항상 `"main"`을 사용합니다. -- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 중 에이전트 사이에서 허용되는 최대 응답 왕복 횟수입니다(정수, 범위: `0`–`5`). `0`이면 ping-pong 체이닝이 비활성화됩니다. +- **`mainKey`**: 레거시 필드입니다. 런타임은 항상 메인 direct-chat 버킷에 `"main"`을 사용합니다. +- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 중 응답-재응답이 가능한 최대 턴 수입니다(정수, 범위: `0`–`5`). `0`은 ping-pong 체이닝을 비활성화합니다. - **`sendPolicy`**: `channel`, `chatType`(`direct|group|channel`, 레거시 `dm` 별칭 포함), `keyPrefix`, 또는 `rawKeyPrefix`로 일치시킵니다. 첫 번째 deny가 우선합니다. - **`maintenance`**: 세션 저장소 정리 + 보존 제어입니다. - `mode`: `warn`은 경고만 출력하고, `enforce`는 정리를 적용합니다. - - `pruneAfter`: 오래된 항목의 기준 연령입니다(기본값 `30d`). - - `maxEntries`: `sessions.json`의 최대 항목 수입니다(기본값 `500`). + - `pruneAfter`: 오래된 항목에 대한 경과 시간 기준선(기본값 `30d`). + - `maxEntries`: `sessions.json`의 최대 항목 수(기본값 `500`). - `rotateBytes`: `sessions.json`이 이 크기를 초과하면 회전합니다(기본값 `10mb`). - `resetArchiveRetention`: `*.reset.` transcript 아카이브의 보존 기간입니다. 기본값은 `pruneAfter`이며, 비활성화하려면 `false`로 설정하세요. - `maxDiskBytes`: 선택적 세션 디렉터리 디스크 예산입니다. `warn` 모드에서는 경고를 기록하고, `enforce` 모드에서는 가장 오래된 아티팩트/세션부터 제거합니다. - - `highWaterBytes`: 예산 정리 후의 선택적 목표값입니다. 기본값은 `maxDiskBytes`의 `80%`입니다. + - `highWaterBytes`: 예산 정리 후 목표 크기의 선택적 값입니다. 기본값은 `maxDiskBytes`의 `80%`입니다. - **`threadBindings`**: 스레드 바인딩 세션 기능의 전역 기본값입니다. - - `enabled`: 마스터 기본 스위치입니다(공급자가 재정의 가능, Discord는 `channels.discord.threadBindings.enabled` 사용) - - `idleHours`: 비활성 자동 unfocus의 기본 시간 수입니다(`0`이면 비활성화, 공급자가 재정의 가능) - - `maxAgeHours`: 하드 최대 수명의 기본 시간 수입니다(`0`이면 비활성화, 공급자가 재정의 가능) + - `enabled`: 마스터 기본 스위치(공급자가 재정의 가능, Discord는 `channels.discord.threadBindings.enabled` 사용) + - `idleHours`: 비활성 자동 unfocus의 기본 시간(시간 단위, `0`이면 비활성화, 공급자가 재정의 가능) + - `maxAgeHours`: 하드 최대 수명의 기본 시간(시간 단위, `0`이면 비활성화, 공급자가 재정의 가능) @@ -1886,7 +1884,7 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 ```json5 { messages: { - responsePrefix: "🦞", // 또는 "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1901,7 +1899,7 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 }, }, inbound: { - debounceMs: 2000, // 0이면 비활성화 + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1913,9 +1911,9 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 ### 응답 접두사 -채널별/계정별 재정의: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +채널/계정별 재정의: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -해결 순서(가장 구체적인 항목 우선): 계정 → 채널 → 전역. `""`는 비활성화하고 상속도 중지합니다. `"auto"`는 `[{identity.name}]`를 파생합니다. +해결 순서(가장 구체적인 것이 우선): account → channel → global. `""`는 비활성화하며 상위 전파도 중단합니다. `"auto"`는 `[{identity.name}]`를 도출합니다. **템플릿 변수:** @@ -1925,24 +1923,24 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 | `{modelFull}` | 전체 모델 식별자 | `anthropic/claude-opus-4-6` | | `{provider}` | 공급자 이름 | `anthropic` | | `{thinkingLevel}` | 현재 thinking 수준 | `high`, `low`, `off` | -| `{identity.name}` | 에이전트 ID 이름 | (`"auto"`와 동일) | +| `{identity.name}` | 에이전트 identity 이름 | (`"auto"`와 동일) | 변수는 대소문자를 구분하지 않습니다. `{think}`는 `{thinkingLevel}`의 별칭입니다. -### 확인 리액션 +### 확인 반응 - 기본값은 활성 에이전트의 `identity.emoji`이고, 없으면 `"👀"`입니다. 비활성화하려면 `""`로 설정하세요. - 채널별 재정의: `channels..ackReaction`, `channels..accounts..ackReaction`. -- 해결 순서: 계정 → 채널 → `messages.ackReaction` → identity 대체값. +- 해결 순서: account → channel → `messages.ackReaction` → identity 대체값. - 범위: `group-mentions`(기본값), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: Slack, Discord, Telegram에서 응답 후 확인 리액션을 제거합니다. -- `messages.statusReactions.enabled`: Slack, Discord, Telegram에서 생명주기 상태 리액션을 활성화합니다. - Slack과 Discord에서는 설정하지 않으면 확인 리액션이 활성화된 경우 상태 리액션도 활성화된 상태로 유지됩니다. - Telegram에서는 생명주기 상태 리액션을 활성화하려면 명시적으로 `true`로 설정해야 합니다. +- `removeAckAfterReply`: Slack, Discord, Telegram에서 응답 후 확인 반응을 제거합니다. +- `messages.statusReactions.enabled`: Slack, Discord, Telegram에서 수명 주기 상태 반응을 활성화합니다. + Slack과 Discord에서는 설정하지 않으면 확인 반응이 활성 상태일 때 상태 반응도 활성 상태를 유지합니다. + Telegram에서는 수명 주기 상태 반응을 활성화하려면 명시적으로 `true`로 설정해야 합니다. ### 인바운드 디바운스 -같은 발신자가 빠르게 보낸 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 플러시됩니다. 제어 명령은 디바운스를 우회합니다. +같은 발신자가 빠르게 보낸 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 플러시됩니다. 제어 명령은 디바운싱을 우회합니다. ### TTS(텍스트 음성 변환) @@ -1985,11 +1983,11 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 } ``` -- `auto`는 기본 자동 TTS 모드를 제어합니다: `off`, `always`, `inbound`, 또는 `tagged`. `/tts on|off`는 로컬 기본 설정을 재정의할 수 있으며, `/tts status`는 실제 적용 상태를 보여줍니다. +- `auto`는 기본 자동 TTS 모드를 제어합니다: `off`, `always`, `inbound`, 또는 `tagged`. `/tts on|off`는 로컬 환경설정을 재정의할 수 있고, `/tts status`는 유효 상태를 보여줍니다. - `summaryModel`은 자동 요약에 대해 `agents.defaults.model.primary`를 재정의합니다. -- `modelOverrides`는 기본적으로 활성화되어 있으며, `modelOverrides.allowProvider`의 기본값은 `false`입니다(opt-in). +- `modelOverrides`는 기본적으로 활성화되며, `modelOverrides.allowProvider`의 기본값은 `false`(명시적 opt-in)입니다. - API 키는 `ELEVENLABS_API_KEY`/`XI_API_KEY` 및 `OPENAI_API_KEY`로 대체될 수 있습니다. -- `openai.baseUrl`은 OpenAI TTS 엔드포인트를 재정의합니다. 해결 순서는 구성, 그다음 `OPENAI_TTS_BASE_URL`, 그다음 `https://api.openai.com/v1`입니다. +- `openai.baseUrl`은 OpenAI TTS 엔드포인트를 재정의합니다. 해결 순서는 config, 그다음 `OPENAI_TTS_BASE_URL`, 그다음 `https://api.openai.com/v1`입니다. - `openai.baseUrl`이 OpenAI가 아닌 엔드포인트를 가리키면, OpenClaw는 이를 OpenAI 호환 TTS 서버로 간주하고 모델/음성 검증을 완화합니다. --- @@ -2020,13 +2018,13 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. } ``` -- 여러 Talk provider가 구성된 경우 `talk.provider`는 `talk.providers`의 키 중 하나와 일치해야 합니다. -- 레거시 플랫 Talk 키(`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`)는 호환성 전용이며 자동으로 `talk.providers.`로 마이그레이션됩니다. +- `talk.provider`는 여러 Talk provider가 구성된 경우 `talk.providers`의 키와 일치해야 합니다. +- 레거시 평면 Talk 키(`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`)는 호환성 전용이며 `talk.providers.`로 자동 마이그레이션됩니다. - Voice ID는 `ELEVENLABS_VOICE_ID` 또는 `SAG_VOICE_ID`로 대체될 수 있습니다. -- `providers.*.apiKey`는 평문 문자열 또는 SecretRef 객체를 받을 수 있습니다. +- `providers.*.apiKey`는 일반 텍스트 문자열 또는 SecretRef 객체를 받을 수 있습니다. - `ELEVENLABS_API_KEY` 대체값은 Talk API 키가 구성되지 않은 경우에만 적용됩니다. -- `providers.*.voiceAliases`를 사용하면 Talk 지시어에서 읽기 쉬운 이름을 사용할 수 있습니다. -- `silenceTimeoutMs`는 사용자가 침묵한 뒤 transcript를 보내기 전에 Talk 모드가 기다리는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 일시 중지 창이 유지됩니다(`macOS와 Android는 700ms, iOS는 900ms`). +- `providers.*.voiceAliases`를 사용하면 Talk 지시문에서 친숙한 이름을 사용할 수 있습니다. +- `silenceTimeoutMs`는 Talk 모드가 사용자 침묵 이후 transcript를 보내기 전까지 얼마나 기다릴지 제어합니다. 설정하지 않으면 플랫폼 기본 일시정지 창을 유지합니다(`macOS와 Android는 700 ms, iOS는 900 ms`). --- @@ -2034,33 +2032,33 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ### 도구 프로필 -`tools.profile`은 `tools.allow`/`tools.deny` 전에 적용되는 기본 허용 목록을 설정합니다. +`tools.profile`은 `tools.allow`/`tools.deny` 전에 기본 허용 목록을 설정합니다: -로컬 온보딩은 설정되지 않은 새 로컬 구성에 대해 기본적으로 `tools.profile: "coding"`을 설정합니다(기존의 명시적 프로필은 유지됨). +로컬 온보딩은 설정되지 않은 새 로컬 구성에 기본적으로 `tools.profile: "coding"`을 적용합니다(기존의 명시적 프로필은 유지됨). -| 프로필 | 포함 항목 | -| ---------- | -------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | `session_status`만 | +| 프로필 | 포함 항목 | +| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | `session_status`만 | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | 제한 없음(설정하지 않은 경우와 동일) | +| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | 제한 없음(설정하지 않은 것과 동일) | ### 도구 그룹 | 그룹 | 도구 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash`는 `exec`의 별칭으로 허용됨) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash`는 `exec`의 별칭으로 허용됨) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | 모든 내장 도구(provider 플러그인 제외) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | 모든 내장 도구(provider Plugin 제외) | ### `tools.allow` / `tools.deny` @@ -2090,7 +2088,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ### `tools.elevated` -샌드박스 외부의 elevated exec 액세스를 제어합니다: +sandbox 밖에서의 고급 `exec` 접근을 제어합니다: ```json5 { @@ -2107,8 +2105,8 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ``` - 에이전트별 재정의(`agents.list[].tools.elevated`)는 추가 제한만 할 수 있습니다. -- `/elevated on|off|ask|full`은 세션별 상태를 저장하며, 인라인 지시어는 단일 메시지에만 적용됩니다. -- Elevated `exec`는 sandboxing을 우회하고 구성된 escape 경로를 사용합니다(기본값은 `gateway`, exec 대상이 `node`인 경우 `node`). +- `/elevated on|off|ask|full`은 세션별로 상태를 저장하며, 인라인 지시문은 단일 메시지에만 적용됩니다. +- 고급 `exec`는 sandboxing을 우회하고 구성된 탈출 경로를 사용합니다(기본값은 `gateway`, exec 대상이 `node`이면 `node`). ### `tools.exec` @@ -2154,14 +2152,14 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. } ``` -- `historySize`: 루프 분석을 위해 유지되는 최대 도구 호출 기록 수입니다. -- `warningThreshold`: 경고를 위한 반복적인 무진전 패턴 임계값입니다. -- `criticalThreshold`: 치명적 루프를 차단하기 위한 더 높은 반복 임계값입니다. -- `globalCircuitBreakerThreshold`: 어떤 무진전 실행에도 적용되는 하드 중단 임계값입니다. -- `detectors.genericRepeat`: 동일 도구/동일 인자 호출 반복 시 경고합니다. -- `detectors.knownPollNoProgress`: 알려진 폴링 도구(`process.poll`, `command_status` 등)에서 무진전 상태를 경고/차단합니다. -- `detectors.pingPong`: 번갈아 반복되는 무진전 쌍 패턴을 경고/차단합니다. -- `warningThreshold >= criticalThreshold`이거나 `criticalThreshold >= globalCircuitBreakerThreshold`이면 검증이 실패합니다. +- `historySize`: 루프 분석을 위해 유지하는 최대 도구 호출 기록 수입니다. +- `warningThreshold`: 진행 없는 반복 패턴에 대한 경고 임계값입니다. +- `criticalThreshold`: 치명적 루프 차단을 위한 더 높은 반복 임계값입니다. +- `globalCircuitBreakerThreshold`: 진행 없는 실행에 대한 하드 중단 임계값입니다. +- `detectors.genericRepeat`: 동일 도구/동일 인수 반복 호출에 대해 경고합니다. +- `detectors.knownPollNoProgress`: 알려진 폴링 도구(`process.poll`, `command_status` 등)의 진행 없음에 대해 경고/차단합니다. +- `detectors.pingPong`: 번갈아 나타나는 진행 없음 쌍 패턴에 대해 경고/차단합니다. +- `warningThreshold >= criticalThreshold` 또는 `criticalThreshold >= globalCircuitBreakerThreshold`이면 유효성 검사가 실패합니다. ### `tools.web` @@ -2171,14 +2169,14 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. web: { search: { enabled: true, - apiKey: "brave_api_key", // 또는 BRAVE_API_KEY 환경 변수 + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // 선택 사항; 자동 감지를 원하면 생략 + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2203,7 +2201,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: 완료된 비동기 music/video를 채널로 직접 전송 + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2229,21 +2227,21 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. -**Provider 항목** (`type: "provider"` 또는 생략): +**Provider 항목**(`type: "provider"` 또는 생략): - `provider`: API provider ID(`openai`, `anthropic`, `google`/`gemini`, `groq` 등) - `model`: 모델 ID 재정의 - `profile` / `preferredProfile`: `auth-profiles.json` 프로필 선택 -**CLI 항목** (`type: "cli"`): +**CLI 항목**(`type: "cli"`): - `command`: 실행할 실행 파일 -- `args`: 템플릿화된 인자(`{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` 등 지원) +- `args`: 템플릿 인수(`{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` 등 지원) **공통 필드:** -- `capabilities`: 선택적 목록(`image`, `audio`, `video`)입니다. 기본값: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: 항목별 재정의입니다. +- `capabilities`: 선택적 목록(`image`, `audio`, `video`). 기본값: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: 항목별 재정의. - 실패하면 다음 항목으로 대체됩니다. Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환경 변수 → `models.providers.*.apiKey`. @@ -2251,7 +2249,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 **비동기 완료 필드:** - `asyncCompletion.directSend`: `true`이면 완료된 비동기 `music_generate` - 및 `video_generate` 작업이 먼저 direct 채널 전달을 시도합니다. 기본값: `false` + 및 `video_generate` 작업이 먼저 직접 채널 전달을 시도합니다. 기본값: `false` (레거시 요청자 세션 깨우기/모델 전달 경로). @@ -2273,7 +2271,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 세션 도구(`sessions_list`, `sessions_history`, `sessions_send`)가 어떤 세션을 대상으로 할 수 있는지 제어합니다. -기본값: `tree`(현재 세션 + 현재 세션이 생성한 세션, 예: subagent). +기본값: `tree`(현재 세션 + 그 세션이 생성한 세션, 예: 하위 에이전트). ```json5 { @@ -2289,10 +2287,10 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: - `self`: 현재 세션 키만. -- `tree`: 현재 세션 + 현재 세션이 생성한 세션(subagent). -- `agent`: 현재 에이전트 ID에 속한 모든 세션(같은 에이전트 ID 아래에서 발신자별 세션을 실행하는 경우 다른 사용자 포함 가능). -- `all`: 모든 세션. 에이전트 간 대상 지정은 여전히 `tools.agentToAgent`가 필요합니다. -- 샌드박스 클램프: 현재 세션이 샌드박스 상태이고 `agents.defaults.sandbox.sessionToolsVisibility="spawned"`이면, `tools.sessions.visibility="all"`이어도 가시성은 강제로 `tree`가 됩니다. +- `tree`: 현재 세션 + 현재 세션이 생성한 세션(하위 에이전트). +- `agent`: 현재 에이전트 ID에 속한 모든 세션(같은 에이전트 ID 아래에서 발신자별 세션을 실행하면 다른 사용자도 포함될 수 있음). +- `all`: 모든 세션. 에이전트 간 대상 지정에는 여전히 `tools.agentToAgent`가 필요합니다. +- Sandbox clamp: 현재 세션이 sandbox 상태이고 `agents.defaults.sandbox.sessionToolsVisibility="spawned"`이면 `tools.sessions.visibility="all"`이더라도 가시성은 `tree`로 강제됩니다. ### `tools.sessions_spawn` @@ -2303,11 +2301,11 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: 인라인 파일 첨부를 허용하려면 true로 설정 - maxTotalBytes: 5242880, // 모든 파일 합계 5 MB + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, - maxFileBytes: 1048576, // 파일당 1 MB - retainOnSessionKeep: false, // cleanup="keep"일 때 첨부 파일 유지 + maxFileBytes: 1048576, // 1 MB per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2317,9 +2315,9 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: - 첨부 파일은 `runtime: "subagent"`에서만 지원됩니다. ACP 런타임은 이를 거부합니다. -- 파일은 `.manifest.json`과 함께 자식 workspace의 `.openclaw/attachments//`에 구체화됩니다. -- 첨부 파일 내용은 transcript 저장에서 자동으로 redaction됩니다. -- Base64 입력은 엄격한 알파벳/패딩 검사와 디코드 전 크기 가드로 검증됩니다. +- 파일은 자식 workspace의 `.openclaw/attachments//`에 `.manifest.json`과 함께 구체화됩니다. +- 첨부 파일 내용은 transcript 저장 시 자동으로 redaction됩니다. +- Base64 입력은 엄격한 알파벳/패딩 검사와 디코딩 전 크기 가드로 검증됩니다. - 파일 권한은 디렉터리 `0700`, 파일 `0600`입니다. - 정리는 `cleanup` 정책을 따릅니다: `delete`는 항상 첨부 파일을 제거하고, `keep`은 `retainOnSessionKeep: true`일 때만 유지합니다. @@ -2331,7 +2329,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 { tools: { experimental: { - planTool: true, // 실험적 update_plan 활성화 + planTool: true, // enable experimental update_plan }, }, } @@ -2339,9 +2337,9 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: -- `planTool`: 중요하고 다단계인 작업 추적을 위한 구조화된 `update_plan` 도구를 활성화합니다. -- 기본값: `agents.defaults.embeddedPi.executionContract`(또는 에이전트별 재정의)가 OpenAI 또는 OpenAI Codex GPT-5 계열 실행에 대해 `"strict-agentic"`으로 설정되지 않은 한 `false`입니다. 해당 범위 밖에서도 강제로 켜려면 `true`, strict-agentic GPT-5 실행에서도 계속 끄려면 `false`로 설정하세요. -- 활성화되면 시스템 프롬프트에도 사용 지침이 추가되어, 모델이 이를 중요한 작업에만 사용하고 `in_progress` 단계는 최대 하나만 유지하도록 합니다. +- `planTool`: 사소하지 않은 다단계 작업 추적을 위한 구조화된 `update_plan` 도구를 활성화합니다. +- 기본값: `agents.defaults.embeddedPi.executionContract`(또는 에이전트별 재정의)가 OpenAI 또는 OpenAI Codex GPT-5 계열 실행에서 `"strict-agentic"`으로 설정된 경우가 아니면 `false`입니다. 해당 범위 밖에서도 도구를 강제로 켜려면 `true`, strict-agentic GPT-5 실행에서도 계속 끄려면 `false`로 설정하세요. +- 활성화되면 시스템 프롬프트에도 사용 지침이 추가되어 모델이 실질적인 작업에만 이를 사용하고 동시에 최대 한 단계만 `in_progress` 상태로 유지하게 됩니다. ### `agents.defaults.subagents` @@ -2361,21 +2359,21 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 } ``` -- `model`: 생성된 sub-agent의 기본 모델입니다. 생략하면 sub-agent는 호출자의 모델을 상속합니다. -- `allowAgents`: 요청 에이전트가 자체 `subagents.allowAgents`를 설정하지 않았을 때 `sessions_spawn` 대상 에이전트 ID의 기본 허용 목록입니다(`["*"]` = 아무 에이전트나 허용, 기본값: 동일 에이전트만). -- `runTimeoutSeconds`: 도구 호출에서 `runTimeoutSeconds`를 생략했을 때 `sessions_spawn`의 기본 timeout(초)입니다. `0`은 timeout 없음입니다. -- sub-agent별 도구 정책: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: 생성된 하위 에이전트의 기본 모델입니다. 생략하면 하위 에이전트는 호출자의 모델을 상속합니다. +- `allowAgents`: 요청 에이전트가 자체 `subagents.allowAgents`를 설정하지 않았을 때 `sessions_spawn`용 대상 에이전트 ID의 기본 허용 목록입니다(`["*"]` = 아무거나, 기본값: 동일 에이전트만). +- `runTimeoutSeconds`: 도구 호출에서 `runTimeoutSeconds`를 생략했을 때 `sessions_spawn`의 기본 제한 시간(초)입니다. `0`은 제한 없음입니다. +- 하위 에이전트별 도구 정책: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## 사용자 지정 provider 및 base URL -OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 provider는 구성의 `models.providers` 또는 `~/.openclaw/agents//agent/models.json`을 통해 추가하세요. +OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 provider는 config의 `models.providers` 또는 `~/.openclaw/agents//agent/models.json`을 통해 추가하세요. ```json5 { models: { - mode: "merge", // merge (기본값) | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2400,47 +2398,47 @@ OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 prov ``` - 사용자 지정 인증이 필요하면 `authHeader: true` + `headers`를 사용하세요. -- 에이전트 구성 루트는 `OPENCLAW_AGENT_DIR`로 재정의할 수 있습니다(또는 레거시 환경 변수 별칭 `PI_CODING_AGENT_DIR`). -- 일치하는 provider ID의 병합 우선순위: +- 에이전트 config 루트는 `OPENCLAW_AGENT_DIR`(또는 레거시 환경 변수 별칭인 `PI_CODING_AGENT_DIR`)로 재정의할 수 있습니다. +- 일치하는 provider ID에 대한 병합 우선순위: - 비어 있지 않은 에이전트 `models.json`의 `baseUrl` 값이 우선합니다. - - 비어 있지 않은 에이전트 `apiKey` 값은 해당 provider가 현재 구성/auth-profile 컨텍스트에서 SecretRef 관리 상태가 아닐 때만 우선합니다. - - SecretRef 관리 provider `apiKey` 값은 해석된 비밀 값을 유지하는 대신 소스 마커(`env` 참조에는 `ENV_VAR_NAME`, 파일/exec 참조에는 `secretref-managed`)에서 새로 갱신됩니다. - - SecretRef 관리 provider header 값은 소스 마커(`env` 참조에는 `secretref-env:ENV_VAR_NAME`, 파일/exec 참조에는 `secretref-managed`)에서 새로 갱신됩니다. - - 비어 있거나 없는 에이전트 `apiKey`/`baseUrl`은 구성의 `models.providers`로 대체됩니다. - - 일치하는 모델의 `contextWindow`/`maxTokens`는 명시적 구성 값과 암시적 카탈로그 값 중 더 큰 값을 사용합니다. - - 일치하는 모델의 `contextTokens`는 명시적 런타임 상한이 있으면 이를 유지합니다. 네이티브 모델 메타데이터를 바꾸지 않고 유효 컨텍스트를 제한할 때 사용하세요. - - 구성으로 `models.json`을 완전히 다시 쓰고 싶다면 `models.mode: "replace"`를 사용하세요. - - 마커 저장은 소스 기준 권한을 따릅니다: 마커는 해석된 런타임 비밀 값이 아니라 활성 소스 구성 스냅샷(해석 전)에서 기록됩니다. + - 비어 있지 않은 에이전트 `apiKey` 값은 해당 provider가 현재 config/auth-profile 컨텍스트에서 SecretRef 관리가 아닌 경우에만 우선합니다. + - SecretRef 관리 provider `apiKey` 값은 해결된 비밀을 유지하는 대신 소스 마커(환경 변수 ref는 `ENV_VAR_NAME`, 파일/exec ref는 `secretref-managed`)에서 새로 고쳐집니다. + - SecretRef 관리 provider 헤더 값은 소스 마커(환경 변수 ref는 `secretref-env:ENV_VAR_NAME`, 파일/exec ref는 `secretref-managed`)에서 새로 고쳐집니다. + - 비어 있거나 누락된 에이전트 `apiKey`/`baseUrl`은 config의 `models.providers`로 대체됩니다. + - 일치하는 모델의 `contextWindow`/`maxTokens`는 명시적 config 값과 암시적 카탈로그 값 중 더 높은 값을 사용합니다. + - 일치하는 모델의 `contextTokens`는 명시적 런타임 상한이 있으면 이를 유지합니다. 네이티브 모델 메타데이터를 바꾸지 않고 실효 컨텍스트를 제한하는 데 사용하세요. + - config가 `models.json`을 완전히 다시 쓰도록 하려면 `models.mode: "replace"`를 사용하세요. + - 마커 지속성은 소스 우선 원칙을 따릅니다: 마커는 해결된 런타임 비밀값이 아니라 활성 소스 config 스냅샷(해결 전)에서 기록됩니다. ### Provider 필드 세부 정보 -- `models.mode`: provider 카탈로그 동작입니다(`merge` 또는 `replace`). -- `models.providers`: provider ID를 키로 하는 사용자 지정 provider 맵입니다. -- `models.providers.*.api`: 요청 어댑터입니다(`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` 등). -- `models.providers.*.apiKey`: provider 자격 증명입니다(SecretRef/환경 변수 치환 권장). -- `models.providers.*.auth`: 인증 전략입니다(`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions`에서 요청에 `options.num_ctx`를 주입합니다(기본값: `true`). -- `models.providers.*.authHeader`: 필요할 때 `Authorization` 헤더를 통한 자격 증명 전송을 강제합니다. -- `models.providers.*.baseUrl`: 업스트림 API 기본 URL입니다. -- `models.providers.*.headers`: 프록시/테넌트 라우팅용 추가 정적 헤더입니다. -- `models.providers.*.request`: 모델 provider HTTP 요청용 전송 재정의입니다. - - `request.headers`: 추가 헤더입니다(provider 기본값과 병합됨). 값은 SecretRef를 받을 수 있습니다. - - `request.auth`: 인증 전략 재정의입니다. 모드: `"provider-default"`(provider의 내장 인증 사용), `"authorization-bearer"`(`token` 사용), `"header"`(`headerName`, `value`, 선택적 `prefix` 사용). - - `request.proxy`: HTTP 프록시 재정의입니다. 모드: `"env-proxy"`(`HTTP_PROXY`/`HTTPS_PROXY` 환경 변수 사용), `"explicit-proxy"`(`url` 사용). 두 모드 모두 선택적 `tls` 하위 객체를 받을 수 있습니다. - - `request.tls`: 직접 연결용 TLS 재정의입니다. 필드: `ca`, `cert`, `key`, `passphrase`(모두 SecretRef 허용), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: `true`이면 DNS가 사설, CGNAT 또는 유사 범위로 해석될 때 provider HTTP fetch 가드를 통해 `baseUrl`에 대한 HTTPS를 허용합니다(신뢰된 자체 호스팅 OpenAI 호환 엔드포인트를 위한 operator opt-in). WebSocket은 헤더/TLS에 동일한 `request`를 사용하지만, 해당 fetch SSRF 게이트는 사용하지 않습니다. 기본값은 `false`입니다. -- `models.providers.*.models`: 명시적 provider 모델 카탈로그 항목입니다. -- `models.providers.*.models.*.contextWindow`: 네이티브 모델 컨텍스트 윈도 메타데이터입니다. -- `models.providers.*.models.*.contextTokens`: 선택적 런타임 컨텍스트 상한입니다. 모델의 네이티브 `contextWindow`보다 더 작은 유효 컨텍스트 예산을 원할 때 사용하세요. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: 선택적 호환성 힌트입니다. `api: "openai-completions"`와 비어 있지 않은 비네이티브 `baseUrl`(`api.openai.com`이 아닌 호스트)을 함께 사용할 때 OpenClaw는 런타임에 이를 강제로 `false`로 설정합니다. `baseUrl`이 비어 있거나 생략되면 기본 OpenAI 동작을 유지합니다. -- `models.providers.*.models.*.compat.requiresStringContent`: 문자열 전용 OpenAI 호환 채팅 엔드포인트를 위한 선택적 호환성 힌트입니다. `true`이면 OpenClaw는 요청을 보내기 전에 순수 텍스트 `messages[].content` 배열을 일반 문자열로 평탄화합니다. -- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 자동 검색 설정 루트입니다. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 암시적 검색을 켜거나 끕니다. -- `plugins.entries.amazon-bedrock.config.discovery.region`: 검색에 사용할 AWS 리전입니다. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 대상 지정 검색을 위한 선택적 provider-id 필터입니다. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 검색 새로 고침의 폴링 간격입니다. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 검색된 모델의 대체 컨텍스트 윈도입니다. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 검색된 모델의 대체 최대 출력 토큰 수입니다. +- `models.mode`: provider 카탈로그 동작(`merge` 또는 `replace`). +- `models.providers`: provider ID를 키로 하는 사용자 지정 provider 맵. +- `models.providers.*.api`: 요청 어댑터(`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` 등). +- `models.providers.*.apiKey`: provider 자격 증명(SecretRef/환경 변수 치환 사용 권장). +- `models.providers.*.auth`: 인증 전략(`api-key`, `token`, `oauth`, `aws-sdk`). +- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions`용으로 요청에 `options.num_ctx`를 주입합니다(기본값: `true`). +- `models.providers.*.authHeader`: 필요할 때 `Authorization` 헤더로 자격 증명을 강제 전송합니다. +- `models.providers.*.baseUrl`: 업스트림 API base URL. +- `models.providers.*.headers`: 프록시/tenant 라우팅용 추가 정적 헤더. +- `models.providers.*.request`: model-provider HTTP 요청에 대한 전송 재정의. + - `request.headers`: 추가 헤더(provider 기본값과 병합됨). 값은 SecretRef를 받을 수 있습니다. + - `request.auth`: 인증 전략 재정의. 모드: `"provider-default"`(provider의 내장 인증 사용), `"authorization-bearer"`(`token`과 함께 사용), `"header"`(`headerName`, `value`, 선택적 `prefix`와 함께 사용). + - `request.proxy`: HTTP 프록시 재정의. 모드: `"env-proxy"`(`HTTP_PROXY`/`HTTPS_PROXY` 환경 변수 사용), `"explicit-proxy"`(`url`과 함께 사용). 두 모드 모두 선택적 `tls` 하위 객체를 받을 수 있습니다. + - `request.tls`: 직접 연결에 대한 TLS 재정의. 필드: `ca`, `cert`, `key`, `passphrase`(모두 SecretRef 지원), `serverName`, `insecureSkipVerify`. + - `request.allowPrivateNetwork`: `true`이면 provider HTTP fetch 가드를 통해 DNS가 private, CGNAT 또는 유사 범위로 해석될 때 `baseUrl`에 대한 HTTPS를 허용합니다(신뢰할 수 있는 자체 호스팅 OpenAI 호환 엔드포인트에 대한 운영자 opt-in). WebSocket은 헤더/TLS에는 동일한 `request`를 사용하지만 그 fetch SSRF 게이트는 사용하지 않습니다. 기본값 `false`. +- `models.providers.*.models`: 명시적 provider 모델 카탈로그 항목. +- `models.providers.*.models.*.contextWindow`: 네이티브 모델 컨텍스트 창 메타데이터. +- `models.providers.*.models.*.contextTokens`: 선택적 런타임 컨텍스트 상한. 모델의 네이티브 `contextWindow`보다 더 작은 유효 컨텍스트 예산을 원할 때 사용하세요. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: 선택적 호환성 힌트. 비어 있지 않은 비네이티브 `baseUrl`(호스트가 `api.openai.com`이 아님)을 가진 `api: "openai-completions"`의 경우, OpenClaw는 런타임에 이를 강제로 `false`로 설정합니다. 비어 있거나 생략된 `baseUrl`은 기본 OpenAI 동작을 유지합니다. +- `models.providers.*.models.*.compat.requiresStringContent`: 문자열 전용 OpenAI 호환 채팅 엔드포인트용 선택적 호환성 힌트. `true`이면 OpenClaw는 요청을 보내기 전에 순수 텍스트 `messages[].content` 배열을 일반 문자열로 평탄화합니다. +- `plugins.entries.amazon-bedrock.config.discovery`: Bedrock 자동 검색 설정 루트. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: 암시적 검색 켜기/끄기. +- `plugins.entries.amazon-bedrock.config.discovery.region`: 검색에 사용할 AWS 리전. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: 대상 검색을 위한 선택적 provider-id 필터. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: 검색 새로고침 폴링 간격. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: 검색된 모델에 대한 대체 컨텍스트 창. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: 검색된 모델에 대한 대체 최대 출력 토큰 수. ### Provider 예시 @@ -2495,7 +2493,7 @@ Cerebras에는 `cerebras/zai-glm-4.7`을 사용하세요. Z.AI 직접 연결에 } ``` -`OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`)를 설정하세요. Zen 카탈로그에는 `opencode/...` 참조를, Go 카탈로그에는 `opencode-go/...` 참조를 사용하세요. 바로가기: `openclaw onboard --auth-choice opencode-zen` 또는 `openclaw onboard --auth-choice opencode-go`. +`OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`)를 설정하세요. Zen 카탈로그에는 `opencode/...` 참조를, Go 카탈로그에는 `opencode-go/...` 참조를 사용하세요. 단축 경로: `openclaw onboard --auth-choice opencode-zen` 또는 `openclaw onboard --auth-choice opencode-go`. @@ -2512,7 +2510,7 @@ Cerebras에는 `cerebras/zai-glm-4.7`을 사용하세요. Z.AI 직접 연결에 } ``` -`ZAI_API_KEY`를 설정하세요. `z.ai/*` 및 `z-ai/*`는 허용되는 별칭입니다. 바로가기: `openclaw onboard --auth-choice zai-api-key`. +`ZAI_API_KEY`를 설정하세요. `z.ai/*`와 `z-ai/*`는 허용되는 별칭입니다. 단축 경로: `openclaw onboard --auth-choice zai-api-key`. - 일반 엔드포인트: `https://api.z.ai/api/paas/v4` - 코딩 엔드포인트(기본값): `https://api.z.ai/api/coding/paas/v4` @@ -2555,9 +2553,9 @@ Cerebras에는 `cerebras/zai-glm-4.7`을 사용하세요. Z.AI 직접 연결에 } ``` -중국 엔드포인트용: `baseUrl: "https://api.moonshot.cn/v1"` 또는 `openclaw onboard --auth-choice moonshot-api-key-cn`. +중국 엔드포인트의 경우: `baseUrl: "https://api.moonshot.cn/v1"` 또는 `openclaw onboard --auth-choice moonshot-api-key-cn`. -네이티브 Moonshot 엔드포인트는 공유 `openai-completions` 전송에서 스트리밍 사용 호환성을 알리며, OpenClaw는 내장 provider ID만이 아니라 해당 엔드포인트 기능을 기준으로 이를 처리합니다. +네이티브 Moonshot 엔드포인트는 공유 `openai-completions` 전송에서 스트리밍 사용 호환성을 광고하며, OpenClaw는 내장 provider ID만이 아니라 엔드포인트 기능을 기준으로 이를 판단합니다. @@ -2575,7 +2573,7 @@ Cerebras에는 `cerebras/zai-glm-4.7`을 사용하세요. Z.AI 직접 연결에 } ``` -Anthropic 호환, 내장 provider입니다. 바로가기: `openclaw onboard --auth-choice kimi-code-api-key`. +Anthropic 호환 내장 provider입니다. 단축 경로: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2614,11 +2612,11 @@ Anthropic 호환, 내장 provider입니다. 바로가기: `openclaw onboard --au } ``` -Base URL에는 `/v1`을 포함하지 않아야 합니다(Anthropic 클라이언트가 이를 추가함). 바로가기: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL에는 `/v1`을 포함하지 않아야 합니다(Anthropic 클라이언트가 이를 추가함). 단축 경로: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2654,17 +2652,17 @@ Base URL에는 `/v1`을 포함하지 않아야 합니다(Anthropic 클라이언 } ``` -`MINIMAX_API_KEY`를 설정하세요. 바로가기: +`MINIMAX_API_KEY`를 설정하세요. 단축 경로: `openclaw onboard --auth-choice minimax-global-api` 또는 `openclaw onboard --auth-choice minimax-cn-api`. -모델 카탈로그 기본값은 M2.7만 포함합니다. -Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thinking`을 설정하지 않는 한 MiniMax thinking을 기본적으로 비활성화합니다. `/fast on` 또는 `params.fastMode: true`는 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 다시 작성합니다. +모델 카탈로그는 기본적으로 M2.7만 포함합니다. +Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 명시적으로 `thinking`을 설정하지 않는 한 기본적으로 MiniMax thinking을 비활성화합니다. `/fast on` 또는 `params.fastMode: true`는 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 다시 씁니다. -[로컬 모델](/ko/gateway/local-models)을 참조하세요. 요약: 충분한 하드웨어에서 LM Studio Responses API로 대형 로컬 모델을 실행하고, 대체를 위해 호스팅 모델은 병합된 상태로 유지하세요. +[Local Models](/ko/gateway/local-models)를 참고하세요. 요약: 충분한 하드웨어에서 LM Studio Responses API를 통해 큰 로컬 모델을 실행하고, 대체 경로를 위해 호스팅 모델은 병합 상태로 유지하세요. @@ -2685,7 +2683,7 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 또는 평문 문자열 + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2695,16 +2693,16 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin } ``` -- `allowBundled`: 번들된 Skills에만 적용되는 선택적 허용 목록입니다(관리형/workspace Skills에는 영향 없음). -- `load.extraDirs`: 추가 공유 skill 루트입니다(가장 낮은 우선순위). -- `install.preferBrew`: `brew`를 사용할 수 있을 때 다른 설치 방식으로 대체하기 전에 Homebrew 설치를 우선합니다. -- `install.nodeManager`: `metadata.openclaw.install` 사양에 대한 node 설치 관리자 우선순위입니다(`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false`는 해당 skill이 번들되었거나 설치되어 있어도 비활성화합니다. -- `entries..apiKey`: 기본 환경 변수를 선언하는 Skills를 위한 편의 항목입니다(평문 문자열 또는 SecretRef 객체). +- `allowBundled`: 번들 Skills에만 적용되는 선택적 허용 목록입니다(관리형/workspace Skills는 영향 없음). +- `load.extraDirs`: 추가 공유 Skills 루트(가장 낮은 우선순위). +- `install.preferBrew`: `true`이면 `brew`를 사용할 수 있을 때 다른 설치 방식으로 대체하기 전에 Homebrew 설치를 우선합니다. +- `install.nodeManager`: `metadata.openclaw.install` 사양용 node 설치 관리자 선호도(`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false`는 번들이거나 설치되어 있어도 해당 Skill을 비활성화합니다. +- `entries..apiKey`: 기본 환경 변수를 선언하는 Skills를 위한 편의 필드입니다(일반 텍스트 문자열 또는 SecretRef 객체). --- -## 플러그인 +## Plugins ```json5 { @@ -2728,43 +2726,43 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin } ``` -- 로드 위치: `~/.openclaw/extensions`, `/.openclaw/extensions`, 그리고 `plugins.load.paths`. -- 검색은 네이티브 OpenClaw 플러그인뿐 아니라 호환되는 Codex 번들과 Claude 번들도 허용하며, 매니페스트가 없는 Claude 기본 레이아웃 번들도 포함합니다. -- **구성 변경에는 gateway 재시작이 필요합니다.** -- `allow`: 선택적 허용 목록입니다(목록에 있는 플러그인만 로드됨). `deny`가 우선합니다. -- `plugins.entries..apiKey`: 플러그인 수준 API 키 편의 필드입니다(플러그인이 지원하는 경우). -- `plugins.entries..env`: 플러그인 범위 환경 변수 맵입니다. -- `plugins.entries..hooks.allowPromptInjection`: `false`이면 core가 `before_prompt_build`를 차단하고 레거시 `before_agent_start`의 프롬프트 변경 필드를 무시하며, 레거시 `modelOverride`와 `providerOverride`는 유지합니다. 네이티브 플러그인 훅과 지원되는 번들 제공 훅 디렉터리에 적용됩니다. -- `plugins.entries..subagent.allowModelOverride`: 이 플러그인이 백그라운드 subagent 실행에 대해 실행별 `provider` 및 `model` 재정의를 요청할 수 있도록 명시적으로 신뢰합니다. -- `plugins.entries..subagent.allowedModels`: 신뢰된 subagent 재정의를 위한 정식 `provider/model` 대상의 선택적 허용 목록입니다. 어떤 모델이든 허용하려는 의도가 있는 경우에만 `"*"`를 사용하세요. -- `plugins.entries..config`: 플러그인 정의 구성 객체입니다(사용 가능한 경우 네이티브 OpenClaw 플러그인 스키마로 검증됨). -- `plugins.entries.firecrawl.config.webFetch`: Firecrawl 웹 fetch provider 설정입니다. - - `apiKey`: Firecrawl API 키입니다(SecretRef 허용). `plugins.entries.firecrawl.config.webSearch.apiKey`, 레거시 `tools.web.fetch.firecrawl.apiKey`, 또는 `FIRECRAWL_API_KEY` 환경 변수로 대체될 수 있습니다. - - `baseUrl`: Firecrawl API 기본 URL입니다(기본값: `https://api.firecrawl.dev`). - - `onlyMainContent`: 페이지에서 주요 콘텐츠만 추출합니다(기본값: `true`). - - `maxAgeMs`: 최대 캐시 보존 시간(밀리초)입니다(기본값: `172800000` / 2일). - - `timeoutSeconds`: 스크레이프 요청 timeout(초)입니다(기본값: `60`). +- `~/.openclaw/extensions`, `/.openclaw/extensions`, 그리고 `plugins.load.paths`에서 로드됩니다. +- 검색은 네이티브 OpenClaw Plugins와 호환되는 Codex 번들 및 Claude 번들을 허용하며, manifest가 없는 Claude 기본 레이아웃 번들도 포함합니다. +- **구성 변경에는 Gateway 재시작이 필요합니다.** +- `allow`: 선택적 허용 목록(목록에 있는 Plugins만 로드). `deny`가 우선합니다. +- `plugins.entries..apiKey`: Plugin 수준 API 키 편의 필드(Plugin이 지원하는 경우). +- `plugins.entries..env`: Plugin 범위 환경 변수 맵. +- `plugins.entries..hooks.allowPromptInjection`: `false`이면 core가 `before_prompt_build`를 차단하고 레거시 `before_agent_start`의 프롬프트 변경 필드를 무시하며, 레거시 `modelOverride`와 `providerOverride`는 유지합니다. 네이티브 Plugin hooks와 지원되는 번들 제공 hook 디렉터리에 적용됩니다. +- `plugins.entries..subagent.allowModelOverride`: 이 Plugin이 백그라운드 하위 에이전트 실행에 대해 실행별 `provider` 및 `model` 재정의를 요청하도록 명시적으로 신뢰합니다. +- `plugins.entries..subagent.allowedModels`: 신뢰된 하위 에이전트 재정의를 위한 정식 `provider/model` 대상의 선택적 허용 목록입니다. 어떤 모델이든 허용하려는 것이 의도적일 때만 `"*"`를 사용하세요. +- `plugins.entries..config`: Plugin이 정의한 구성 객체입니다(가능한 경우 네이티브 OpenClaw Plugin 스키마로 검증됨). +- `plugins.entries.firecrawl.config.webFetch`: Firecrawl 웹 가져오기 provider 설정입니다. + - `apiKey`: Firecrawl API 키(SecretRef 지원). `plugins.entries.firecrawl.config.webSearch.apiKey`, 레거시 `tools.web.fetch.firecrawl.apiKey`, 또는 `FIRECRAWL_API_KEY` 환경 변수로 대체될 수 있습니다. + - `baseUrl`: Firecrawl API base URL(기본값: `https://api.firecrawl.dev`). + - `onlyMainContent`: 페이지에서 본문 콘텐츠만 추출합니다(기본값: `true`). + - `maxAgeMs`: 최대 캐시 수명(밀리초)(기본값: `172800000` / 2일). + - `timeoutSeconds`: 스크래핑 요청 제한 시간(초)(기본값: `60`). - `plugins.entries.xai.config.xSearch`: xAI X Search(Grok 웹 검색) 설정입니다. - `enabled`: X Search provider를 활성화합니다. - - `model`: 검색에 사용할 Grok 모델입니다(예: `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: memory dreaming(실험적) 설정입니다. 단계와 임계값은 [Dreaming](/ko/concepts/dreaming)을 참조하세요. - - `enabled`: dreaming 마스터 스위치입니다(기본값 `false`). - - `frequency`: 각 전체 dreaming 스윕의 cron 주기입니다(기본값 `"0 3 * * *"`). + - `model`: 검색에 사용할 Grok 모델(예: `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: memory Dreaming 설정입니다. 단계와 임계값은 [Dreaming](/ko/concepts/dreaming)을 참고하세요. + - `enabled`: Dreaming 마스터 스위치(기본값 `false`). + - `frequency`: 각 전체 Dreaming 스윕에 대한 Cron 주기(기본값 `"0 3 * * *"`). - 단계 정책과 임계값은 구현 세부 사항입니다(사용자 대상 구성 키 아님). -- 전체 memory 구성은 [메모리 구성 참조](/ko/reference/memory-config)에 있습니다: +- 전체 메모리 구성은 [메모리 구성 참조](/ko/reference/memory-config)에 있습니다: - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 활성화된 Claude 번들 플러그인은 `settings.json`에서 embedded Pi 기본값도 제공할 수 있습니다. OpenClaw는 이를 원시 OpenClaw 구성 패치가 아니라 정리된 에이전트 설정으로 적용합니다. -- `plugins.slots.memory`: 활성 memory 플러그인 ID를 선택하거나, memory 플러그인을 비활성화하려면 `"none"`을 사용합니다. -- `plugins.slots.contextEngine`: 활성 context engine 플러그인 ID를 선택합니다. 다른 엔진을 설치하고 선택하지 않으면 기본값은 `"legacy"`입니다. -- `plugins.installs`: `openclaw plugins update`에서 사용하는 CLI 관리 설치 메타데이터입니다. +- 활성화된 Claude 번들 Plugins는 `settings.json`에서 내장 Pi 기본값도 제공할 수 있습니다. OpenClaw는 이를 원시 OpenClaw 구성 패치가 아니라 정제된 에이전트 설정으로 적용합니다. +- `plugins.slots.memory`: 활성 메모리 Plugin ID를 선택하거나, 메모리 Plugins를 비활성화하려면 `"none"`을 선택합니다. +- `plugins.slots.contextEngine`: 활성 컨텍스트 엔진 Plugin ID를 선택합니다. 다른 엔진을 설치하고 선택하지 않는 한 기본값은 `"legacy"`입니다. +- `plugins.installs`: `openclaw plugins update`에 사용되는 CLI 관리 설치 메타데이터입니다. - `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`를 포함합니다. - - `plugins.installs.*`는 관리 상태로 취급하세요. 수동 편집보다 CLI 명령을 우선 사용하세요. + - `plugins.installs.*`는 관리되는 상태로 취급하세요. 수동 편집보다 CLI 명령 사용을 권장합니다. -[플러그인](/ko/tools/plugin)을 참조하세요. +[Plugins](/ko/tools/plugin)를 참고하세요. --- @@ -2777,8 +2775,8 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 신뢰된 사설 네트워크 액세스에만 opt in - // allowPrivateNetwork: true, // 레거시 별칭 + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2805,21 +2803,21 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin ``` - `evaluateEnabled: false`는 `act:evaluate`와 `wait --fn`을 비활성화합니다. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork`는 설정하지 않으면 비활성화되므로, 브라우저 탐색은 기본적으로 엄격하게 유지됩니다. -- 사설 네트워크 브라우저 탐색을 의도적으로 신뢰하는 경우에만 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`로 설정하세요. -- 엄격 모드에서는 원격 CDP 프로필 엔드포인트(`profiles.*.cdpUrl`)도 도달 가능성/검색 검사 중 동일한 사설 네트워크 차단의 적용을 받습니다. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork`는 설정하지 않으면 비활성화되므로, 브라우저 탐색은 기본적으로 엄격한 상태를 유지합니다. +- 비공개 네트워크 브라우저 탐색을 의도적으로 신뢰하는 경우에만 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`를 설정하세요. +- 엄격 모드에서 원격 CDP 프로필 엔드포인트(`profiles.*.cdpUrl`)는 도달 가능성/검색 검사 중 동일한 비공개 네트워크 차단 대상이 됩니다. - `ssrfPolicy.allowPrivateNetwork`는 레거시 별칭으로 계속 지원됩니다. - 엄격 모드에서는 명시적 예외를 위해 `ssrfPolicy.hostnameAllowlist`와 `ssrfPolicy.allowedHostnames`를 사용하세요. -- 원격 프로필은 attach-only입니다(시작/중지/reset 비활성화). +- 원격 프로필은 attach-only입니다(시작/중지/재설정 비활성화). - `profiles.*.cdpUrl`은 `http://`, `https://`, `ws://`, `wss://`를 받을 수 있습니다. - OpenClaw가 `/json/version`을 검색하도록 하려면 HTTP(S)를 사용하고, provider가 직접 DevTools WebSocket URL을 제공하는 경우에는 WS(S)를 사용하세요. + OpenClaw가 `/json/version`을 검색하도록 하려면 HTTP(S)를 사용하세요. provider가 직접 DevTools WebSocket URL을 제공하는 경우 WS(S)를 사용하세요. - `existing-session` 프로필은 호스트 전용이며 CDP 대신 Chrome MCP를 사용합니다. -- `existing-session` 프로필은 특정 Chromium 기반 브라우저 프로필(예: Brave, Edge)을 대상으로 하기 위해 `userDataDir`를 설정할 수 있습니다. -- `existing-session` 프로필은 현재 Chrome MCP 경로 제한을 유지합니다: CSS 선택자 대상 지정 대신 snapshot/ref 기반 작업, 단일 파일 업로드 훅, 대화상자 timeout 재정의 없음, `wait --load networkidle` 없음, 그리고 `responsebody`, PDF 내보내기, 다운로드 가로채기, 일괄 작업 없음. +- `existing-session` 프로필은 Brave나 Edge 같은 특정 Chromium 기반 브라우저 프로필을 대상으로 삼기 위해 `userDataDir`를 설정할 수 있습니다. +- `existing-session` 프로필은 현재 Chrome MCP 경로 제한을 유지합니다: CSS 선택자 대상 지정 대신 snapshot/ref 기반 동작, 단일 파일 업로드 hooks, 대화상자 제한 시간 재정의 없음, `wait --load networkidle` 없음, 그리고 `responsebody`, PDF 내보내기, 다운로드 가로채기, 배치 동작 없음. - 로컬 관리형 `openclaw` 프로필은 `cdpPort`와 `cdpUrl`을 자동 할당합니다. 원격 CDP에만 `cdpUrl`을 명시적으로 설정하세요. -- 자동 감지 순서: 기본 브라우저가 Chromium 기반인 경우 해당 브라우저 → Chrome → Brave → Edge → Chromium → Chrome Canary. -- 제어 서비스: loopback 전용(`gateway.port`에서 파생되는 포트, 기본값 `18791`). -- `extraArgs`는 로컬 Chromium 시작에 추가 실행 플래그를 덧붙입니다(예: `--disable-gpu`, 창 크기 조정, 디버그 플래그). +- 자동 감지 순서: 기본 브라우저가 Chromium 기반이면 그것을 사용 → Chrome → Brave → Edge → Chromium → Chrome Canary. +- 제어 서비스: loopback 전용(포트는 `gateway.port`에서 파생되며 기본값은 `18791`). +- `extraArgs`는 로컬 Chromium 시작 시 추가 실행 플래그를 덧붙입니다(예: `--disable-gpu`, 창 크기 설정, 디버그 플래그). --- @@ -2831,14 +2829,14 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // 이모지, 짧은 텍스트, 이미지 URL, 또는 data URI + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` -- `seamColor`: 네이티브 앱 UI 크롬의 강조 색상입니다(Talk Mode 버블 색조 등). -- `assistant`: Control UI ID 재정의입니다. 활성 에이전트 ID를 기본값으로 사용합니다. +- `seamColor`: 네이티브 앱 UI 크롬의 강조 색상입니다(Talk Mode 버블 틴트 등). +- `assistant`: Control UI identity 재정의입니다. 활성 에이전트 identity로 대체됩니다. --- @@ -2853,8 +2851,8 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // 또는 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy용; /gateway/trusted-proxy-auth 참조 + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2872,9 +2870,9 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // 위험: 절대 외부 http(s) 임베드 URL 허용 - // allowedOrigins: ["https://control.example.com"], // loopback이 아닌 Control UI에 필요 - // dangerouslyAllowHostHeaderOriginFallback: false, // 위험한 Host-header origin fallback 모드 + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2885,12 +2883,12 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // 선택 사항. 기본값 false. + // Optional. Default false. allowRealIpFallback: false, tools: { - // 추가 /tools/invoke HTTP deny + // Additional /tools/invoke HTTP denies deny: ["browser"], - // 기본 HTTP deny 목록에서 도구 제거 + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -2907,43 +2905,43 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin -- `mode`: `local`(gateway 실행) 또는 `remote`(원격 gateway 연결)입니다. gateway는 `local`이 아니면 시작을 거부합니다. -- `port`: WS + HTTP용 단일 멀티플렉스 포트입니다. 우선순위: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `mode`: `local`(Gateway 실행) 또는 `remote`(원격 Gateway에 연결). Gateway는 `local`이 아니면 시작을 거부합니다. +- `port`: WS + HTTP용 단일 다중화 포트입니다. 우선순위: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback`(기본값), `lan`(`0.0.0.0`), `tailnet`(Tailscale IP만), 또는 `custom`. - **레거시 bind 별칭**: `gateway.bind`에는 호스트 별칭(`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`)이 아니라 bind 모드 값(`auto`, `loopback`, `lan`, `tailnet`, `custom`)을 사용하세요. -- **Docker 참고**: 기본 `loopback` bind는 컨테이너 내부의 `127.0.0.1`에서 수신합니다. Docker 브리지 네트워킹(`-p 18789:18789`)에서는 트래픽이 `eth0`로 들어오므로 gateway에 연결할 수 없습니다. `--network host`를 사용하거나, 모든 인터페이스에서 수신하도록 `bind: "lan"`(또는 `customBindHost: "0.0.0.0"`와 함께 `bind: "custom"`)을 설정하세요. -- **인증**: 기본적으로 필요합니다. loopback이 아닌 bind에는 gateway 인증이 필요합니다. 실제로는 공유 토큰/비밀번호 또는 `gateway.auth.mode: "trusted-proxy"`가 설정된 ID 인식 리버스 프록시를 의미합니다. 온보딩 마법사는 기본적으로 토큰을 생성합니다. -- `gateway.auth.token`과 `gateway.auth.password`가 모두 구성된 경우(SecretRef 포함), `gateway.auth.mode`를 `token` 또는 `password`로 명시적으로 설정하세요. 둘 다 구성되어 있는데 mode가 설정되지 않으면 시작 및 서비스 설치/복구 흐름이 실패합니다. -- `gateway.auth.mode: "none"`: 명시적 무인증 모드입니다. 신뢰된 로컬 loopback 설정에만 사용하세요. 이 옵션은 의도적으로 온보딩 프롬프트에 제공되지 않습니다. -- `gateway.auth.mode: "trusted-proxy"`: 인증을 ID 인식 리버스 프록시에 위임하고 `gateway.trustedProxies`의 ID 헤더를 신뢰합니다([Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth) 참조). 이 모드는 **loopback이 아닌** 프록시 소스를 기대합니다. 동일 호스트의 loopback 리버스 프록시는 trusted-proxy 인증 요구 사항을 충족하지 않습니다. -- `gateway.auth.allowTailscale`: `true`이면 Tailscale Serve ID 헤더가 Control UI/WebSocket 인증을 충족할 수 있습니다(`tailscale whois`로 검증). HTTP API 엔드포인트는 이 Tailscale 헤더 인증을 사용하지 않으며, gateway의 일반 HTTP 인증 모드를 따릅니다. 이 토큰 없는 흐름은 gateway 호스트가 신뢰된다는 가정에 기반합니다. `tailscale.mode = "serve"`일 때 기본값은 `true`입니다. -- `gateway.auth.rateLimit`: 선택적 인증 실패 제한기입니다. 클라이언트 IP별 및 인증 범위별로 적용됩니다(공유 비밀과 장치 토큰은 별도로 추적됨). 차단된 시도는 `429` + `Retry-After`를 반환합니다. - - 비동기 Tailscale Serve Control UI 경로에서는 동일한 `{scope, clientIp}`에 대한 실패 시도가 실패 기록 이전에 직렬화됩니다. 따라서 같은 클라이언트의 동시 잘못된 시도는 둘 다 단순 불일치로 통과하는 대신 두 번째 요청에서 제한기에 걸릴 수 있습니다. - - `gateway.auth.rateLimit.exemptLoopback`의 기본값은 `true`입니다. localhost 트래픽에도 의도적으로 속도 제한을 적용하려면(테스트 설정 또는 엄격한 프록시 배포) `false`로 설정하세요. -- 브라우저 원본 WS 인증 시도는 항상 loopback 예외가 비활성화된 상태로 제한됩니다(localhost에 대한 브라우저 기반 brute force 방어 심화). -- loopback에서는 이러한 브라우저 원본 잠금이 정규화된 `Origin` 값별로 격리되므로, 하나의 localhost origin에서 반복된 실패가 다른 origin까지 자동으로 잠그지는 않습니다. +- **Docker 참고**: 기본 `loopback` bind는 컨테이너 내부에서 `127.0.0.1`에 리슨합니다. Docker 브리지 네트워킹(`-p 18789:18789`)에서는 트래픽이 `eth0`로 들어오므로 Gateway에 도달할 수 없습니다. `--network host`를 사용하거나, 모든 인터페이스에서 리슨하도록 `bind: "lan"`(또는 `customBindHost: "0.0.0.0"`가 있는 `bind: "custom"`)을 설정하세요. +- **인증**: 기본적으로 필요합니다. loopback이 아닌 bind에는 Gateway 인증이 필요합니다. 실제로는 공유 토큰/비밀번호 또는 `gateway.auth.mode: "trusted-proxy"`를 사용하는 identity-aware 리버스 프록시를 의미합니다. 온보딩 마법사는 기본적으로 토큰을 생성합니다. +- `gateway.auth.token`과 `gateway.auth.password`가 모두 구성된 경우(SecretRef 포함), `gateway.auth.mode`를 `token` 또는 `password`로 명시적으로 설정하세요. 둘 다 구성되어 있고 mode가 설정되지 않으면 시작 및 서비스 설치/복구 흐름이 실패합니다. +- `gateway.auth.mode: "none"`: 명시적 무인증 모드입니다. 신뢰할 수 있는 로컬 loopback 설정에만 사용하세요. 이는 의도적으로 온보딩 프롬프트에서 제공되지 않습니다. +- `gateway.auth.mode: "trusted-proxy"`: 인증을 identity-aware 리버스 프록시에 위임하고 `gateway.trustedProxies`의 identity 헤더를 신뢰합니다([Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth) 참고). 이 모드는 **loopback이 아닌** 프록시 소스를 기대합니다. 같은 호스트의 loopback 리버스 프록시는 trusted-proxy 인증 조건을 충족하지 않습니다. +- `gateway.auth.allowTailscale`: `true`이면 Tailscale Serve identity 헤더가 Control UI/WebSocket 인증을 충족할 수 있습니다(`tailscale whois`로 검증). HTTP API 엔드포인트는 이 Tailscale 헤더 인증을 사용하지 않으며, 대신 Gateway의 일반 HTTP 인증 모드를 따릅니다. 이 토큰 없는 흐름은 Gateway 호스트가 신뢰된다고 가정합니다. `tailscale.mode = "serve"`일 때 기본값은 `true`입니다. +- `gateway.auth.rateLimit`: 선택적 인증 실패 제한기입니다. 클라이언트 IP별 및 인증 범위별로 적용됩니다(공유 비밀과 디바이스 토큰은 서로 독립적으로 추적됨). 차단된 시도에는 `429` + `Retry-After`가 반환됩니다. + - 비동기 Tailscale Serve Control UI 경로에서는 동일한 `{scope, clientIp}`에 대한 실패 시도가 실패 기록 전에 직렬화됩니다. 따라서 같은 클라이언트의 동시 잘못된 시도는 둘 다 일반 불일치로 통과하지 않고 두 번째 요청에서 제한기를 작동시킬 수 있습니다. + - `gateway.auth.rateLimit.exemptLoopback`의 기본값은 `true`입니다. localhost 트래픽도 의도적으로 속도 제한하려면(테스트 설정 또는 엄격한 프록시 배포) `false`로 설정하세요. +- 브라우저 출처 WS 인증 시도는 항상 loopback 면제를 비활성화한 상태로 제한됩니다(localhost에 대한 브라우저 기반 무차별 대입 방어 심화). +- loopback에서는 이러한 브라우저 출처 잠금이 정규화된 `Origin` 값별로 격리되므로, 한 localhost 출처의 반복 실패가 다른 출처를 자동으로 잠그지 않습니다. - `tailscale.mode`: `serve`(tailnet 전용, loopback bind) 또는 `funnel`(공개, 인증 필요). -- `controlUi.allowedOrigins`: Gateway WebSocket 연결용 명시적 브라우저 origin 허용 목록입니다. 브라우저 클라이언트가 loopback이 아닌 origin에서 접속할 것으로 예상되면 필요합니다. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host 헤더 origin 정책에 의도적으로 의존하는 배포를 위해 Host 헤더 origin fallback을 활성화하는 위험한 모드입니다. -- `remote.transport`: `ssh`(기본값) 또는 `direct`(ws/wss)입니다. `direct`의 경우 `remote.url`은 `ws://` 또는 `wss://`여야 합니다. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 신뢰된 사설 네트워크 IP에 대한 평문 `ws://`를 허용하는 클라이언트 측 비상 재정의입니다. 기본값은 평문 연결에 대해 여전히 loopback 전용입니다. -- `gateway.remote.token` / `.password`는 원격 클라이언트 자격 증명 필드입니다. 이것만으로 gateway 인증이 구성되지는 않습니다. -- `gateway.push.apns.relay.baseUrl`: 공식/TestFlight iOS 빌드가 relay 기반 등록을 gateway에 게시한 뒤 사용하는 외부 APNs relay의 기본 HTTPS URL입니다. 이 URL은 iOS 빌드에 컴파일된 relay URL과 일치해야 합니다. -- `gateway.push.apns.relay.timeoutMs`: gateway에서 relay로 보내는 timeout(밀리초)입니다. 기본값은 `10000`입니다. -- relay 기반 등록은 특정 gateway ID에 위임됩니다. 페어링된 iOS 앱은 `gateway.identity.get`을 가져오고, 해당 ID를 relay 등록에 포함하며, 등록 범위의 send grant를 gateway로 전달합니다. 다른 gateway는 저장된 그 등록을 재사용할 수 없습니다. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 위 relay 구성에 대한 임시 환경 변수 재정의입니다. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL을 위한 개발 전용 예외 장치입니다. 프로덕션 relay URL은 HTTPS를 유지해야 합니다. -- `gateway.channelHealthCheckMinutes`: 채널 상태 모니터 간격(분)입니다. 전역적으로 상태 모니터 재시작을 비활성화하려면 `0`으로 설정하세요. 기본값: `5`. +- `controlUi.allowedOrigins`: Gateway WebSocket 연결용 명시적 브라우저 출처 허용 목록입니다. 브라우저 클라이언트가 loopback이 아닌 출처에서 올 것으로 예상되는 경우 필요합니다. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host 헤더 출처 정책에 의도적으로 의존하는 배포를 위해 Host 헤더 출처 대체를 활성화하는 위험한 모드입니다. +- `remote.transport`: `ssh`(기본값) 또는 `direct`(ws/wss). `direct`의 경우 `remote.url`은 `ws://` 또는 `wss://`여야 합니다. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: 신뢰된 비공개 네트워크 IP에 대한 평문 `ws://`를 허용하는 클라이언트 측 비상 재정의입니다. 기본값은 평문에 대해 loopback 전용으로 유지됩니다. +- `gateway.remote.token` / `.password`는 원격 클라이언트 자격 증명 필드입니다. 이것만으로 Gateway 인증을 구성하지는 않습니다. +- `gateway.push.apns.relay.baseUrl`: 공식/TestFlight iOS 빌드가 relay 기반 등록을 Gateway에 게시한 후 사용하는 외부 APNs relay의 기본 HTTPS URL입니다. 이 URL은 iOS 빌드에 컴파일된 relay URL과 일치해야 합니다. +- `gateway.push.apns.relay.timeoutMs`: Gateway에서 relay로 보내는 제한 시간(밀리초)입니다. 기본값은 `10000`입니다. +- Relay 기반 등록은 특정 Gateway identity에 위임됩니다. 페어링된 iOS 앱은 `gateway.identity.get`을 가져오고, 해당 identity를 relay 등록에 포함하며, 등록 범위 send grant를 Gateway로 전달합니다. 다른 Gateway는 그 저장된 등록을 재사용할 수 없습니다. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: 위 relay 구성을 위한 임시 환경 변수 재정의입니다. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: loopback HTTP relay URL용 개발 전용 탈출구입니다. 운영 relay URL은 HTTPS를 유지해야 합니다. +- `gateway.channelHealthCheckMinutes`: 채널 상태 모니터 간격(분)입니다. 상태 모니터 재시작을 전역적으로 비활성화하려면 `0`으로 설정하세요. 기본값: `5`. - `gateway.channelStaleEventThresholdMinutes`: 오래된 소켓 임계값(분)입니다. `gateway.channelHealthCheckMinutes`보다 크거나 같게 유지하세요. 기본값: `30`. -- `gateway.channelMaxRestartsPerHour`: 이동 1시간 동안 채널/계정별 최대 상태 모니터 재시작 횟수입니다. 기본값: `10`. -- `channels..healthMonitor.enabled`: 전역 모니터를 유지하면서 채널별 상태 모니터 재시작 opt-out입니다. -- `channels..accounts..healthMonitor.enabled`: 다중 계정 채널의 계정별 재정의입니다. 설정되면 채널 수준 재정의보다 우선합니다. -- 로컬 gateway 호출 경로는 `gateway.auth.*`가 설정되지 않은 경우에만 `gateway.remote.*`를 대체값으로 사용할 수 있습니다. -- `gateway.auth.token` / `gateway.auth.password`가 SecretRef로 명시적으로 구성되었는데 해석되지 않으면, 해석은 fail-closed됩니다(원격 대체로 가려지지 않음). -- `trustedProxies`: TLS를 종료하거나 전달된 클라이언트 헤더를 주입하는 리버스 프록시 IP입니다. 사용자가 제어하는 프록시만 나열하세요. loopback 항목은 동일 호스트 프록시/로컬 감지 설정(예: Tailscale Serve 또는 로컬 리버스 프록시)에서는 여전히 유효하지만, loopback 요청이 `gateway.auth.mode: "trusted-proxy"`에 적합해지도록 만들지는 않습니다. -- `allowRealIpFallback`: `true`이면 `X-Forwarded-For`가 없을 때 gateway가 `X-Real-IP`를 수락합니다. fail-closed 동작을 위해 기본값은 `false`입니다. -- `gateway.tools.deny`: HTTP `POST /tools/invoke`에 대해 추가로 차단할 도구 이름입니다(기본 deny 목록 확장). -- `gateway.tools.allow`: 기본 HTTP deny 목록에서 제거할 도구 이름입니다. +- `gateway.channelMaxRestartsPerHour`: 이동하는 1시간 동안 채널/계정당 허용되는 최대 상태 모니터 재시작 횟수입니다. 기본값: `10`. +- `channels..healthMonitor.enabled`: 전역 모니터를 유지한 채 상태 모니터 재시작을 채널별로 opt-out합니다. +- `channels..accounts..healthMonitor.enabled`: 다중 계정 채널용 계정별 재정의입니다. 설정되면 채널 수준 재정의보다 우선합니다. +- 로컬 Gateway 호출 경로는 `gateway.auth.*`가 설정되지 않은 경우에만 `gateway.remote.*`를 대체값으로 사용할 수 있습니다. +- `gateway.auth.token` / `gateway.auth.password`가 SecretRef를 통해 명시적으로 구성되었으나 확인되지 않으면, 확인은 닫힌 상태로 실패합니다(원격 대체에 의해 가려지지 않음). +- `trustedProxies`: TLS를 종료하거나 전달된 클라이언트 헤더를 주입하는 리버스 프록시 IP입니다. 직접 제어하는 프록시만 나열하세요. loopback 항목은 같은 호스트 프록시/로컬 감지 설정(예: Tailscale Serve 또는 로컬 리버스 프록시)에서 여전히 유효하지만, loopback 요청이 `gateway.auth.mode: "trusted-proxy"` 대상이 되도록 만들지는 않습니다. +- `allowRealIpFallback`: `true`이면 `X-Forwarded-For`가 없을 때 Gateway가 `X-Real-IP`를 허용합니다. 기본값은 닫힌 실패 동작을 위한 `false`입니다. +- `gateway.tools.deny`: HTTP `POST /tools/invoke`용으로 추가 차단할 도구 이름입니다(기본 deny 목록 확장). +- `gateway.tools.allow`: 기본 HTTP deny 목록에서 도구 이름을 제거합니다. @@ -2951,17 +2949,17 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 사용자가 직접 `thin - Chat Completions: 기본적으로 비활성화됩니다. `gateway.http.endpoints.chatCompletions.enabled: true`로 활성화하세요. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Responses URL 입력 하드닝: +- Responses URL 입력 강화: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 빈 allowlist는 설정되지 않은 것으로 처리됩니다. URL 가져오기를 비활성화하려면 `gateway.http.endpoints.responses.files.allowUrl=false` 및/또는 `gateway.http.endpoints.responses.images.allowUrl=false`를 사용하세요. -- 선택적 응답 하드닝 헤더: - - `gateway.http.securityHeaders.strictTransportSecurity`(사용자가 제어하는 HTTPS origin에만 설정; [Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth#tls-termination-and-hsts) 참조) + 빈 허용 목록은 설정되지 않은 것으로 처리됩니다. URL 가져오기를 비활성화하려면 `gateway.http.endpoints.responses.files.allowUrl=false` 및/또는 `gateway.http.endpoints.responses.images.allowUrl=false`를 사용하세요. +- 선택적 응답 강화 헤더: + - `gateway.http.securityHeaders.strictTransportSecurity`(직접 제어하는 HTTPS 출처에만 설정하세요. [Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth#tls-termination-and-hsts) 참고) ### 다중 인스턴스 격리 -하나의 호스트에서 여러 gateway를 고유 포트와 상태 디렉터리로 실행합니다: +고유한 포트와 상태 디렉터리로 하나의 호스트에서 여러 Gateway를 실행합니다: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -2971,7 +2969,7 @@ openclaw gateway --port 19001 편의 플래그: `--dev`(`~/.openclaw-dev` + 포트 `19001` 사용), `--profile `(`~/.openclaw-` 사용). -[여러 Gateway](/ko/gateway/multiple-gateways)를 참조하세요. +[Multiple Gateways](/ko/gateway/multiple-gateways)를 참고하세요. ### `gateway.tls` @@ -2989,11 +2987,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: gateway 리스너에서 TLS 종료(HTTPS/WSS)를 활성화합니다(기본값: `false`). -- `autoGenerate`: 명시적인 파일이 구성되지 않았을 때 로컬 자체 서명 인증서/키 쌍을 자동 생성합니다. 로컬/개발용으로만 사용하세요. +- `enabled`: Gateway 리스너에서 TLS 종료(HTTPS/WSS)를 활성화합니다(기본값: `false`). +- `autoGenerate`: 명시적 파일이 구성되지 않았을 때 로컬 자체 서명 인증서/키 쌍을 자동 생성합니다. 로컬/개발용 전용입니다. - `certPath`: TLS 인증서 파일의 파일 시스템 경로입니다. -- `keyPath`: TLS 개인 키 파일의 파일 시스템 경로입니다. 권한을 제한해 두세요. -- `caPath`: 클라이언트 검증 또는 사용자 지정 신뢰 체인을 위한 선택적 CA 번들 경로입니다. +- `keyPath`: TLS 개인 키 파일의 파일 시스템 경로입니다. 권한을 제한해 유지하세요. +- `caPath`: 클라이언트 검증 또는 사용자 지정 신뢰 체인용 선택적 CA 번들 경로입니다. ### `gateway.reload` @@ -3010,12 +3008,12 @@ openclaw gateway --port 19001 ``` - `mode`: 구성 편집이 런타임에 적용되는 방식을 제어합니다. - - `"off"`: 실시간 편집을 무시합니다. 변경 사항에는 명시적 재시작이 필요합니다. - - `"restart"`: 구성 변경 시 항상 gateway 프로세스를 재시작합니다. + - `"off"`: 라이브 편집을 무시합니다. 변경 사항에는 명시적 재시작이 필요합니다. + - `"restart"`: 구성 변경 시 항상 Gateway 프로세스를 재시작합니다. - `"hot"`: 재시작 없이 프로세스 내에서 변경 사항을 적용합니다. - - `"hybrid"`(기본값): 먼저 핫 리로드를 시도하고, 필요하면 재시작으로 대체합니다. -- `debounceMs`: 구성 변경 적용 전 대기하는 디바운스 창(밀리초)입니다(음수가 아닌 정수). -- `deferralTimeoutMs`: 진행 중인 작업을 기다린 뒤 강제로 재시작하기까지의 최대 시간(밀리초)입니다(기본값: `300000` = 5분). + - `"hybrid"`(기본값): 먼저 hot reload를 시도하고, 필요하면 재시작으로 대체합니다. +- `debounceMs`: 구성 변경을 적용하기 전 디바운스 창(밀리초)입니다(음수가 아닌 정수). +- `deferralTimeoutMs`: 진행 중 작업을 기다린 뒤 재시작을 강제하기까지의 최대 시간(밀리초)입니다(기본값: `300000` = 5분). --- @@ -3055,11 +3053,11 @@ openclaw gateway --port 19001 인증: `Authorization: Bearer ` 또는 `x-openclaw-token: `. 쿼리 문자열 hook 토큰은 거부됩니다. -검증 및 안전 참고: +유효성 검사 및 안전 참고: - `hooks.enabled=true`에는 비어 있지 않은 `hooks.token`이 필요합니다. - `hooks.token`은 `gateway.auth.token`과 **달라야** 합니다. Gateway 토큰을 재사용하면 거부됩니다. -- `hooks.path`는 `/`가 될 수 없습니다. `/hooks` 같은 전용 하위 경로를 사용하세요. +- `hooks.path`는 `/`일 수 없습니다. `/hooks` 같은 전용 하위 경로를 사용하세요. - `hooks.allowRequestSessionKey=true`인 경우 `hooks.allowedSessionKeyPrefixes`를 제한하세요(예: `["hook:"]`). **엔드포인트:** @@ -3067,22 +3065,22 @@ openclaw gateway --port 19001 - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - 요청 페이로드의 `sessionKey`는 `hooks.allowRequestSessionKey=true`일 때만 허용됩니다(기본값: `false`). -- `POST /hooks/` → `hooks.mappings`를 통해 해석됨 +- `POST /hooks/` → `hooks.mappings`를 통해 해결됨 - `match.path`는 `/hooks` 뒤의 하위 경로와 일치합니다(예: `/hooks/gmail` → `gmail`). -- `match.source`는 일반 경로에 대해 페이로드 필드와 일치합니다. +- `match.source`는 일반 경로에 대한 페이로드 필드와 일치합니다. - `{{messages[0].subject}}` 같은 템플릿은 페이로드에서 값을 읽습니다. -- `transform`은 hook action을 반환하는 JS/TS 모듈을 가리킬 수 있습니다. - - `transform.module`은 상대 경로여야 하며 `hooks.transformsDir` 내부에 머물러야 합니다(절대 경로와 상위 디렉터리 탐색은 거부됨). +- `transform`은 hook 동작을 반환하는 JS/TS 모듈을 가리킬 수 있습니다. + - `transform.module`은 상대 경로여야 하며 `hooks.transformsDir` 내부에 머물러야 합니다(절대 경로와 상위 경로 이동은 거부됨). - `agentId`는 특정 에이전트로 라우팅합니다. 알 수 없는 ID는 기본값으로 대체됩니다. - `allowedAgentIds`: 명시적 라우팅을 제한합니다(`*` 또는 생략 = 모두 허용, `[]` = 모두 거부). -- `defaultSessionKey`: 명시적인 `sessionKey`가 없는 hook agent 실행에 사용할 선택적 고정 세션 키입니다. -- `allowRequestSessionKey`: `/hooks/agent` 호출자가 `sessionKey`를 설정할 수 있게 합니다(기본값: `false`). +- `defaultSessionKey`: 명시적인 `sessionKey`가 없는 hook agent 실행에 대한 선택적 고정 세션 키입니다. +- `allowRequestSessionKey`: `/hooks/agent` 호출자가 `sessionKey`를 설정하도록 허용합니다(기본값: `false`). - `allowedSessionKeyPrefixes`: 명시적 `sessionKey` 값(요청 + 매핑)에 대한 선택적 접두사 허용 목록입니다(예: `["hook:"]`). -- `deliver: true`는 최종 응답을 채널로 전송합니다. `channel`의 기본값은 `last`입니다. -- `model`은 이 hook 실행에 사용할 LLM을 재정의합니다(모델 카탈로그가 설정된 경우 허용되어야 함). +- `deliver: true`는 최종 응답을 채널로 보냅니다. `channel`의 기본값은 `last`입니다. +- `model`은 이 hook 실행에 대한 LLM을 재정의합니다(모델 카탈로그가 설정된 경우 허용되어야 함). @@ -3109,7 +3107,7 @@ openclaw gateway --port 19001 } ``` -- 구성된 경우 gateway는 부팅 시 `gog gmail watch serve`를 자동 시작합니다. 비활성화하려면 `OPENCLAW_SKIP_GMAIL_WATCHER=1`을 설정하세요. +- 구성된 경우 Gateway는 부팅 시 `gog gmail watch serve`를 자동 시작합니다. 비활성화하려면 `OPENCLAW_SKIP_GMAIL_WATCHER=1`을 설정하세요. - Gateway와 함께 별도의 `gog gmail watch serve`를 실행하지 마세요. --- @@ -3121,29 +3119,29 @@ openclaw gateway --port 19001 canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // 또는 OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Gateway 포트 아래의 HTTP를 통해 에이전트가 편집 가능한 HTML/CSS/JS와 A2UI를 제공합니다: +- Gateway 포트 아래에서 에이전트가 편집 가능한 HTML/CSS/JS와 A2UI를 HTTP로 제공합니다: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - 로컬 전용: `gateway.bind: "loopback"`(기본값)을 유지하세요. -- loopback이 아닌 bind: canvas 경로는 다른 Gateway HTTP 표면과 마찬가지로 Gateway 인증(token/password/trusted-proxy)이 필요합니다. -- Node WebView는 일반적으로 인증 헤더를 보내지 않습니다. 노드가 페어링되고 연결된 후 Gateway는 canvas/A2UI 액세스를 위한 노드 범위 capability URL을 알립니다. -- Capability URL은 활성 노드 WS 세션에 바인딩되며 빠르게 만료됩니다. IP 기반 대체는 사용되지 않습니다. -- 제공되는 HTML에 live-reload 클라이언트를 삽입합니다. -- 비어 있으면 시작용 `index.html`을 자동 생성합니다. -- A2UI도 `/__openclaw__/a2ui/`에서 제공합니다. -- 변경 사항에는 gateway 재시작이 필요합니다. -- 디렉터리가 크거나 `EMFILE` 오류가 발생하면 live reload를 비활성화하세요. +- loopback이 아닌 bind에서는 canvas 경로에 다른 Gateway HTTP 표면과 동일하게 Gateway 인증(token/password/trusted-proxy)이 필요합니다. +- Node WebView는 일반적으로 인증 헤더를 보내지 않습니다. node가 페어링되고 연결되면 Gateway는 canvas/A2UI 접근용 node 범위 capability URL을 광고합니다. +- Capability URL은 활성 node WS 세션에 바인딩되며 빠르게 만료됩니다. IP 기반 대체는 사용되지 않습니다. +- 제공되는 HTML에 라이브 리로드 클라이언트를 주입합니다. +- 비어 있을 때 시작용 `index.html`을 자동 생성합니다. +- `/__openclaw__/a2ui/`에서도 A2UI를 제공합니다. +- 변경 사항에는 Gateway 재시작이 필요합니다. +- 큰 디렉터리 또는 `EMFILE` 오류가 있는 경우 라이브 리로드를 비활성화하세요. --- ## 검색 -### mDNS(Bonjour) +### mDNS (Bonjour) ```json5 { @@ -3157,9 +3155,9 @@ openclaw gateway --port 19001 - `minimal`(기본값): TXT 레코드에서 `cliPath` + `sshPort`를 생략합니다. - `full`: `cliPath` + `sshPort`를 포함합니다. -- 호스트명 기본값은 `openclaw`입니다. `OPENCLAW_MDNS_HOSTNAME`으로 재정의하세요. +- 호스트 이름 기본값은 `openclaw`입니다. `OPENCLAW_MDNS_HOSTNAME`으로 재정의하세요. -### 광역(Wide-area, DNS-SD) +### 광역(Wide-area) (DNS-SD) ```json5 { @@ -3169,7 +3167,7 @@ openclaw gateway --port 19001 } ``` -`~/.openclaw/dns/` 아래에 유니캐스트 DNS-SD 영역을 기록합니다. 네트워크 간 검색을 위해 DNS 서버(CoreDNS 권장) + Tailscale split DNS와 함께 사용하세요. +`~/.openclaw/dns/` 아래에 유니캐스트 DNS-SD 영역을 기록합니다. 교차 네트워크 검색을 위해 DNS 서버(CoreDNS 권장) + Tailscale split DNS와 함께 사용하세요. 설정: `openclaw dns setup --apply`. @@ -3177,7 +3175,7 @@ openclaw gateway --port 19001 ## 환경 -### `env`(인라인 환경 변수) +### `env` (인라인 환경 변수) ```json5 { @@ -3195,13 +3193,13 @@ openclaw gateway --port 19001 ``` - 인라인 환경 변수는 프로세스 환경에 해당 키가 없을 때만 적용됩니다. -- `.env` 파일: CWD `.env` + `~/.openclaw/.env`(둘 다 기존 변수를 덮어쓰지 않음). +- `.env` 파일: CWD `.env` + `~/.openclaw/.env`(둘 다 기존 변수를 재정의하지 않음). - `shellEnv`: 로그인 셸 프로필에서 누락된 예상 키를 가져옵니다. -- 전체 우선순위는 [환경](/ko/help/environment)을 참조하세요. +- 전체 우선순위는 [Environment](/ko/help/environment)를 참고하세요. ### 환경 변수 치환 -`${VAR_NAME}`으로 모든 구성 문자열에서 환경 변수를 참조할 수 있습니다: +모든 구성 문자열에서 `${VAR_NAME}`으로 환경 변수를 참조할 수 있습니다: ```json5 { @@ -3211,16 +3209,16 @@ openclaw gateway --port 19001 } ``` -- 대문자 이름만 매칭됩니다: `[A-Z_][A-Z0-9_]*`. +- 일치하는 이름은 대문자만 허용됩니다: `[A-Z_][A-Z0-9_]*`. - 누락되었거나 비어 있는 변수는 구성 로드 시 오류를 발생시킵니다. -- 리터럴 `${VAR}`를 사용하려면 `$${VAR}`로 이스케이프하세요. +- 리터럴 `${VAR}`가 필요하면 `$${VAR}`로 이스케이프하세요. - `$include`와 함께 동작합니다. --- -## Secrets +## 비밀 -Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. +SecretRef는 추가적입니다. 일반 텍스트 값도 계속 동작합니다. ### `SecretRef` @@ -3230,19 +3228,19 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -검증: +유효성 검사: - `provider` 패턴: `^[a-z][a-z0-9_-]{0,63}$` -- `source: "env"` id 패턴: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id: 절대 JSON 포인터(예: `"/providers/openai/apiKey"`) -- `source: "exec"` id 패턴: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `source: "env"`의 id 패턴: `^[A-Z][A-Z0-9_]{0,127}$` +- `source: "file"`의 id: 절대 JSON 포인터(예: `"/providers/openai/apiKey"`) +- `source: "exec"`의 id 패턴: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` - `source: "exec"` ID에는 `.` 또는 `..` 슬래시 구분 경로 세그먼트가 포함되면 안 됩니다(예: `a/../b`는 거부됨) ### 지원되는 자격 증명 표면 -- 정식 매트릭스: [SecretRef 자격 증명 표면](/ko/reference/secretref-credential-surface) +- 정식 매트릭스: [SecretRef Credential Surface](/ko/reference/secretref-credential-surface) - `secrets apply`는 지원되는 `openclaw.json` 자격 증명 경로를 대상으로 합니다. -- `auth-profiles.json` ref는 런타임 해석 및 감사 범위에도 포함됩니다. +- `auth-profiles.json` 참조는 런타임 확인 및 감사 범위에도 포함됩니다. ### Secret provider 구성 @@ -3250,7 +3248,7 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. { secrets: { providers: { - default: { source: "env" }, // 선택적 명시적 env provider + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3274,13 +3272,13 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. 참고: -- `file` provider는 `mode: "json"`과 `mode: "singleValue"`를 지원합니다(`singleValue` 모드에서는 `id`가 `"value"`여야 함). +- `file` provider는 `mode: "json"`과 `mode: "singleValue"`를 지원합니다(`singleValue` 모드에서는 id가 `"value"`여야 함). - `exec` provider는 절대 `command` 경로가 필요하며 stdin/stdout의 프로토콜 페이로드를 사용합니다. -- 기본적으로 심볼릭 링크 command 경로는 거부됩니다. 해석된 대상 경로를 검증하면서 심볼릭 링크 경로를 허용하려면 `allowSymlinkCommand: true`를 설정하세요. -- `trustedDirs`가 구성된 경우 신뢰 디렉터리 검사는 해석된 대상 경로에 적용됩니다. +- 기본적으로 심볼릭 링크 명령 경로는 거부됩니다. 해결된 대상 경로를 검증하면서 심볼릭 링크 경로를 허용하려면 `allowSymlinkCommand: true`를 설정하세요. +- `trustedDirs`가 구성된 경우, 신뢰 디렉터리 검사는 해결된 대상 경로에 적용됩니다. - `exec` 자식 환경은 기본적으로 최소화되어 있습니다. 필요한 변수는 `passEnv`로 명시적으로 전달하세요. -- Secret ref는 활성화 시점에 메모리 내 스냅샷으로 해석되며, 이후 요청 경로는 해당 스냅샷만 읽습니다. -- 활성 표면 필터링은 활성화 중 적용됩니다: 활성화된 표면의 미해결 ref는 시작/리로드를 실패시키고, 비활성 표면은 진단과 함께 건너뜁니다. +- SecretRef는 활성화 시 메모리 내 스냅샷으로 확인되며, 이후 요청 경로는 스냅샷만 읽습니다. +- 활성 표면 필터링은 활성화 중 적용됩니다: 활성화된 표면에서 확인되지 않은 ref는 시작/리로드를 실패시키고, 비활성 표면은 진단과 함께 건너뜁니다. --- @@ -3305,10 +3303,10 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. - 에이전트별 프로필은 `/auth-profiles.json`에 저장됩니다. - `auth-profiles.json`은 정적 자격 증명 모드에 대해 값 수준 ref(`api_key`용 `keyRef`, `token`용 `tokenRef`)를 지원합니다. - OAuth 모드 프로필(`auth.profiles..mode = "oauth"`)은 SecretRef 기반 auth-profile 자격 증명을 지원하지 않습니다. -- 정적 런타임 자격 증명은 메모리 내 해석 스냅샷에서 오며, 레거시 정적 `auth.json` 항목은 발견 시 제거됩니다. -- 레거시 OAuth 가져오기는 `~/.openclaw/credentials/oauth.json`에서 수행됩니다. -- [OAuth](/ko/concepts/oauth)를 참조하세요. -- Secrets 런타임 동작 및 `audit/configure/apply` 도구: [Secrets Management](/ko/gateway/secrets). +- 정적 런타임 자격 증명은 메모리 내 확인된 스냅샷에서 가져오며, 레거시 정적 `auth.json` 항목은 발견되면 정리됩니다. +- 레거시 OAuth는 `~/.openclaw/credentials/oauth.json`에서 가져옵니다. +- [OAuth](/ko/concepts/oauth)를 참고하세요. +- secrets 런타임 동작과 `audit/configure/apply` 도구: [Secrets Management](/ko/gateway/secrets). ### `auth.cooldowns` @@ -3330,15 +3328,15 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. } ``` -- `billingBackoffHours`: 실제 청구/크레딧 부족 오류로 인해 프로필이 실패할 때의 기본 backoff 시간(시간 단위)입니다(기본값: `5`). 명시적인 청구 관련 텍스트는 `401`/`403` 응답에서도 여기에 들어올 수 있지만, provider별 텍스트 매처는 해당 provider 범위 안에만 유지됩니다(예: OpenRouter `Key limit exceeded`). 재시도 가능한 HTTP `402` 사용량 창 또는 조직/워크스페이스 지출 한도 메시지는 대신 `rate_limit` 경로에 남습니다. -- `billingBackoffHoursByProvider`: 청구 backoff 시간에 대한 선택적 provider별 재정의입니다. -- `billingMaxHours`: 청구 backoff 지수 증가의 상한(시간 단위)입니다(기본값: `24`). -- `authPermanentBackoffMinutes`: 신뢰도 높은 `auth_permanent` 실패에 대한 기본 backoff 시간(분 단위)입니다(기본값: `10`). -- `authPermanentMaxMinutes`: `auth_permanent` backoff 증가의 상한(분 단위)입니다(기본값: `60`). -- `failureWindowHours`: backoff 카운터에 사용되는 이동 창(시간 단위)입니다(기본값: `24`). -- `overloadedProfileRotations`: 과부하 오류 시 모델 fallback으로 전환하기 전에 허용되는 동일 provider auth-profile 회전의 최대 횟수입니다(기본값: `1`). `ModelNotReadyException` 같은 provider 바쁨 형태는 여기에 속합니다. -- `overloadedBackoffMs`: 과부하된 provider/profile 회전을 재시도하기 전의 고정 지연(밀리초)입니다(기본값: `0`). -- `rateLimitedProfileRotations`: rate-limit 오류 시 모델 fallback으로 전환하기 전에 허용되는 동일 provider auth-profile 회전의 최대 횟수입니다(기본값: `1`). 이 rate-limit 버킷에는 `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` 같은 provider 형태 텍스트가 포함됩니다. +- `billingBackoffHours`: 프로필이 실제 청구/크레딧 부족 오류로 실패할 때의 기본 백오프 시간(시간 단위, 기본값: `5`). 명시적인 청구 관련 텍스트는 `401`/`403` 응답에서도 여기에 들어갈 수 있지만, provider별 텍스트 매처는 해당 provider 범위 안에만 머뭅니다(예: OpenRouter `Key limit exceeded`). 재시도 가능한 HTTP `402` 사용량 창 또는 조직/워크스페이스 지출 한도 메시지는 대신 `rate_limit` 경로에 남습니다. +- `billingBackoffHoursByProvider`: 청구 백오프 시간에 대한 선택적 provider별 재정의입니다. +- `billingMaxHours`: 청구 백오프 지수 증가의 상한(시간 단위, 기본값: `24`). +- `authPermanentBackoffMinutes`: 신뢰도 높은 `auth_permanent` 실패에 대한 기본 백오프 시간(분 단위, 기본값: `10`). +- `authPermanentMaxMinutes`: `auth_permanent` 백오프 증가의 상한(분 단위, 기본값: `60`). +- `failureWindowHours`: 백오프 카운터에 사용되는 이동 창(시간 단위, 기본값: `24`). +- `overloadedProfileRotations`: 과부하 오류에 대해 모델 대체로 전환하기 전 동일 provider auth-profile 회전의 최대 횟수입니다(기본값: `1`). `ModelNotReadyException` 같은 provider 바쁨 형태가 여기에 포함됩니다. +- `overloadedBackoffMs`: 과부하된 provider/profile 회전을 재시도하기 전의 고정 지연 시간(밀리초, 기본값: `0`). +- `rateLimitedProfileRotations`: 속도 제한 오류에 대해 모델 대체로 전환하기 전 동일 provider auth-profile 회전의 최대 횟수입니다(기본값: `1`). 이 rate-limit 버킷에는 `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` 같은 provider 형태의 텍스트도 포함됩니다. --- @@ -3358,9 +3356,9 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. ``` - 기본 로그 파일: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- 고정 경로를 사용하려면 `logging.file`을 설정하세요. -- `--verbose`일 때 `consoleLevel`은 `debug`로 올라갑니다. -- `maxFileBytes`: 쓰기 억제가 시작되기 전 최대 로그 파일 크기(바이트 단위)입니다(양의 정수, 기본값: `524288000` = 500 MB). 프로덕션 배포에서는 외부 로그 회전을 사용하세요. +- 고정 경로를 원하면 `logging.file`을 설정하세요. +- `consoleLevel`은 `--verbose`일 때 `debug`로 올라갑니다. +- `maxFileBytes`: 쓰기를 억제하기 전 로그 파일의 최대 크기(바이트)입니다(양의 정수, 기본값: `524288000` = 500 MB). 운영 배포에서는 외부 로그 회전을 사용하세요. --- @@ -3397,19 +3395,19 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. } ``` -- `enabled`: instrumentation 출력의 마스터 토글입니다(기본값: `true`). +- `enabled`: 계측 출력의 마스터 토글입니다(기본값: `true`). - `flags`: 대상 로그 출력을 활성화하는 플래그 문자열 배열입니다(`"telegram.*"` 또는 `"*"` 같은 와일드카드 지원). -- `stuckSessionWarnMs`: 세션이 처리 상태로 남아 있는 동안 stuck-session 경고를 출력하기 위한 경과 시간 임계값(밀리초)입니다. +- `stuckSessionWarnMs`: 세션이 처리 상태에 머무는 동안 정체된 세션 경고를 출력하기 위한 경과 시간 임계값(밀리초)입니다. - `otel.enabled`: OpenTelemetry 내보내기 파이프라인을 활성화합니다(기본값: `false`). -- `otel.endpoint`: OTel 내보내기를 위한 collector URL입니다. -- `otel.protocol`: `"http/protobuf"`(기본값) 또는 `"grpc"`입니다. +- `otel.endpoint`: OTel 내보내기용 수집기 URL입니다. +- `otel.protocol`: `"http/protobuf"`(기본값) 또는 `"grpc"`. - `otel.headers`: OTel 내보내기 요청과 함께 전송되는 추가 HTTP/gRPC 메타데이터 헤더입니다. -- `otel.serviceName`: 리소스 속성에 사용할 서비스 이름입니다. -- `otel.traces` / `otel.metrics` / `otel.logs`: trace, metrics 또는 log 내보내기를 활성화합니다. -- `otel.sampleRate`: trace 샘플링 비율 `0`–`1`입니다. -- `otel.flushIntervalMs`: 주기적인 telemetry flush 간격(밀리초)입니다. -- `cacheTrace.enabled`: embedded 실행에 대한 캐시 trace 스냅샷을 기록합니다(기본값: `false`). -- `cacheTrace.filePath`: 캐시 trace JSONL 출력 경로입니다(기본값: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `otel.serviceName`: 리소스 속성용 서비스 이름입니다. +- `otel.traces` / `otel.metrics` / `otel.logs`: trace, metrics, 또는 log 내보내기를 활성화합니다. +- `otel.sampleRate`: trace 샘플링 비율 `0`–`1`. +- `otel.flushIntervalMs`: 주기적 telemetry flush 간격(밀리초)입니다. +- `cacheTrace.enabled`: 내장 실행에 대한 캐시 trace 스냅샷을 기록합니다(기본값: `false`). +- `cacheTrace.filePath`: 캐시 trace JSONL의 출력 경로입니다(기본값: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: 캐시 trace 출력에 무엇을 포함할지 제어합니다(모두 기본값: `true`). --- @@ -3433,11 +3431,11 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. ``` - `channel`: npm/git 설치용 릴리스 채널입니다 — `"stable"`, `"beta"`, 또는 `"dev"`. -- `checkOnStart`: gateway 시작 시 npm 업데이트를 확인합니다(기본값: `true`). +- `checkOnStart`: Gateway 시작 시 npm 업데이트를 확인합니다(기본값: `true`). - `auto.enabled`: 패키지 설치에 대한 백그라운드 자동 업데이트를 활성화합니다(기본값: `false`). -- `auto.stableDelayHours`: stable 채널 자동 적용 전 최소 지연 시간(시간 단위)입니다(기본값: `6`, 최대: `168`). -- `auto.stableJitterHours`: stable 채널 롤아웃 분산을 위한 추가 시간 창입니다(기본값: `12`, 최대: `168`). -- `auto.betaCheckIntervalHours`: beta 채널 확인이 실행되는 간격(시간 단위)입니다(기본값: `1`, 최대: `24`). +- `auto.stableDelayHours`: stable 채널 자동 적용 전 최소 지연 시간(시간 단위, 기본값: `6`, 최대: `168`). +- `auto.stableJitterHours`: stable 채널 롤아웃 분산용 추가 시간 창(시간 단위, 기본값: `12`, 최대: `168`). +- `auto.betaCheckIntervalHours`: beta 채널 확인 실행 주기(시간 단위, 기본값: `1`, 최대: `24`). --- @@ -3471,20 +3469,20 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. ``` - `enabled`: 전역 ACP 기능 게이트입니다(기본값: `false`). -- `dispatch.enabled`: ACP 세션 턴 디스패치를 위한 독립적인 게이트입니다(기본값: `true`). ACP 명령은 사용 가능하게 유지하면서 실행은 차단하려면 `false`로 설정하세요. -- `backend`: 기본 ACP 런타임 backend ID입니다(등록된 ACP 런타임 플러그인과 일치해야 함). -- `defaultAgent`: spawn에서 명시적 대상을 지정하지 않았을 때의 대체 ACP 대상 에이전트 ID입니다. -- `allowedAgents`: ACP 런타임 세션에 허용되는 에이전트 ID 허용 목록입니다. 비어 있으면 추가 제한이 없음을 의미합니다. -- `maxConcurrentSessions`: 동시에 활성화될 수 있는 ACP 세션의 최대 수입니다. -- `stream.coalesceIdleMs`: 스트리밍 텍스트용 유휴 flush 창(밀리초)입니다. -- `stream.maxChunkChars`: 스트리밍 블록 투영을 분할하기 전의 최대 청크 크기입니다. +- `dispatch.enabled`: ACP 세션 턴 디스패치를 위한 독립 게이트입니다(기본값: `true`). ACP 명령은 계속 사용 가능하게 두고 실행만 차단하려면 `false`로 설정하세요. +- `backend`: 기본 ACP 런타임 backend ID입니다(등록된 ACP 런타임 Plugin과 일치해야 함). +- `defaultAgent`: spawn이 명시적 대상을 지정하지 않을 때의 대체 ACP 대상 에이전트 ID입니다. +- `allowedAgents`: ACP 런타임 세션에 허용되는 에이전트 ID의 허용 목록입니다. 비어 있으면 추가 제한이 없습니다. +- `maxConcurrentSessions`: 동시에 활성 상태일 수 있는 ACP 세션의 최대 수입니다. +- `stream.coalesceIdleMs`: 스트리밍 텍스트의 유휴 flush 창(밀리초)입니다. +- `stream.maxChunkChars`: 스트리밍 블록 프로젝션을 분할하기 전 최대 청크 크기입니다. - `stream.repeatSuppression`: 턴당 반복되는 상태/도구 줄을 숨깁니다(기본값: `true`). -- `stream.deliveryMode`: `"live"`는 점진적으로 스트리밍하고, `"final_only"`는 턴 종료 이벤트까지 버퍼링합니다. -- `stream.hiddenBoundarySeparator`: 숨겨진 도구 이벤트 뒤에 가시 텍스트가 나오기 전 구분자입니다(기본값: `"paragraph"`). -- `stream.maxOutputChars`: ACP 턴당 투영되는 assistant 출력 최대 문자 수입니다. +- `stream.deliveryMode`: `"live"`는 점진적으로 스트리밍하고, `"final_only"`는 턴의 최종 이벤트까지 버퍼링합니다. +- `stream.hiddenBoundarySeparator`: 숨겨진 도구 이벤트 뒤 가시 텍스트 앞에 넣는 구분자입니다(기본값: `"paragraph"`). +- `stream.maxOutputChars`: ACP 턴당 투영되는 assistant 출력의 최대 문자 수입니다. - `stream.maxSessionUpdateChars`: 투영되는 ACP 상태/업데이트 줄의 최대 문자 수입니다. - `stream.tagVisibility`: 스트리밍 이벤트에 대한 태그 이름별 불리언 가시성 재정의 기록입니다. -- `runtime.ttlMinutes`: ACP 세션 워커가 정리 대상이 되기 전의 유휴 TTL(분 단위)입니다. +- `runtime.ttlMinutes`: ACP 세션 작업자가 정리 대상이 되기 전 유휴 TTL(분)입니다. - `runtime.installCommand`: ACP 런타임 환경 bootstrap 시 실행할 선택적 설치 명령입니다. --- @@ -3502,16 +3500,16 @@ Secret ref는 추가형입니다. 평문 값도 계속 동작합니다. ``` - `cli.banner.taglineMode`는 배너 태그라인 스타일을 제어합니다: - - `"random"`(기본값): 순환하는 재미있는/계절성 태그라인. - - `"default"`: 고정된 중립 태그라인(`모든 채팅을 하나의 OpenClaw에서.`). - - `"off"`: 태그라인 텍스트 없음(배너 제목/버전은 계속 표시). + - `"random"`(기본값): 순환하는 재미있거나 계절성 있는 태그라인. + - `"default"`: 고정된 중립 태그라인(`All your chats, one OpenClaw.`). + - `"off"`: 태그라인 텍스트 없음(배너 제목/버전은 계속 표시됨). - 전체 배너를 숨기려면(태그라인만이 아니라) 환경 변수 `OPENCLAW_HIDE_BANNER=1`을 설정하세요. --- ## 마법사 -CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 메타데이터입니다: +CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 메타데이터: ```json5 { @@ -3527,17 +3525,17 @@ CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 --- -## ID +## Identity -[에이전트 기본값](#agent-defaults)의 `agents.list` ID 필드를 참조하세요. +[Agent defaults](#agent-defaults)의 `agents.list` identity 필드를 참고하세요. --- -## Bridge(레거시, 제거됨) +## Bridge (레거시, 제거됨) -현재 빌드에는 더 이상 TCP bridge가 포함되지 않습니다. 노드는 Gateway WebSocket을 통해 연결됩니다. `bridge.*` 키는 더 이상 구성 스키마의 일부가 아니며(제거할 때까지 검증 실패, `openclaw doctor --fix`로 알 수 없는 키 제거 가능). +현재 빌드에는 더 이상 TCP bridge가 포함되지 않습니다. Node는 Gateway WebSocket을 통해 연결됩니다. `bridge.*` 키는 더 이상 구성 스키마의 일부가 아니며(제거할 때까지 유효성 검사가 실패함), `openclaw doctor --fix`로 알 수 없는 키를 제거할 수 있습니다. - + ```json { @@ -3564,22 +3562,22 @@ CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 저장된 notify:true 작업용 레거시 대체값(지원 중단) - webhookToken: "replace-with-dedicated-token", // 아웃바운드 webhook 인증용 선택적 bearer 토큰 - sessionRetention: "24h", // 기간 문자열 또는 false + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth + sessionRetention: "24h", // duration string or false runLog: { - maxBytes: "2mb", // 기본값 2_000_000 bytes - keepLines: 2000, // 기본값 2000 + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 }, }, } ``` -- `sessionRetention`: 완료된 격리 cron 실행 세션을 `sessions.json`에서 정리하기 전까지 얼마나 오래 유지할지입니다. 삭제된 cron transcript 아카이브의 정리도 함께 제어합니다. 기본값: `24h`; 비활성화하려면 `false`로 설정하세요. -- `runLog.maxBytes`: 정리 전 실행 로그 파일(`cron/runs/.jsonl`)당 최대 크기입니다. 기본값: `2_000_000` bytes. -- `runLog.keepLines`: 실행 로그 정리가 트리거될 때 유지되는 최신 줄 수입니다. 기본값: `2000`. -- `webhookToken`: cron webhook POST 전달(`delivery.mode = "webhook"`)에 사용되는 bearer 토큰입니다. 생략하면 인증 헤더를 보내지 않습니다. -- `webhook`: `notify: true`가 남아 있는 저장된 작업에만 사용되는, 지원 중단된 레거시 대체 webhook URL(http/https)입니다. +- `sessionRetention`: 완료된 격리 Cron 실행 세션을 `sessions.json`에서 정리하기 전까지 얼마나 오래 유지할지입니다. 보관된 삭제 Cron transcript 정리도 제어합니다. 기본값: `24h`; 비활성화하려면 `false`로 설정하세요. +- `runLog.maxBytes`: 정리 전 실행 로그 파일(`cron/runs/.jsonl`)당 최대 크기입니다. 기본값: `2_000_000`바이트. +- `runLog.keepLines`: 실행 로그 정리가 트리거될 때 유지할 최신 줄 수입니다. 기본값: `2000`. +- `webhookToken`: Cron Webhook POST 전달(`delivery.mode = "webhook"`)에 사용하는 bearer 토큰입니다. 생략하면 인증 헤더를 보내지 않습니다. +- `webhook`: 저장된 작업에 아직 `notify: true`가 있을 때만 사용하는 더 이상 권장되지 않는 레거시 대체 Webhook URL(http/https)입니다. ### `cron.retry` @@ -3595,11 +3593,11 @@ CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 } ``` -- `maxAttempts`: 일회성 작업에서 일시적 오류 발생 시 최대 재시도 횟수입니다(기본값: `3`; 범위: `0`–`10`). -- `backoffMs`: 각 재시도 시도에 대한 backoff 지연 배열(밀리초)입니다(기본값: `[30000, 60000, 300000]`; 1–10개 항목). -- `retryOn`: 재시도를 유발하는 오류 유형입니다 — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. 생략하면 모든 일시적 유형을 재시도합니다. +- `maxAttempts`: 일회성 작업에서 일시적 오류 시 최대 재시도 횟수입니다(기본값: `3`, 범위: `0`–`10`). +- `backoffMs`: 각 재시도 시도에 대한 백오프 지연 시간 배열(밀리초)입니다(기본값: `[30000, 60000, 300000]`, 1–10개 항목). +- `retryOn`: 재시도를 유발하는 오류 유형 — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. 생략하면 모든 일시적 유형을 재시도합니다. -이는 일회성 cron 작업에만 적용됩니다. 반복 작업은 별도의 실패 처리 방식을 사용합니다. +일회성 Cron 작업에만 적용됩니다. 반복 작업은 별도의 실패 처리 방식을 사용합니다. ### `cron.failureAlert` @@ -3617,11 +3615,11 @@ CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 } ``` -- `enabled`: cron 작업 실패 알림을 활성화합니다(기본값: `false`). -- `after`: 알림이 발생하기 전까지의 연속 실패 횟수입니다(양의 정수, 최소값: `1`). -- `cooldownMs`: 동일 작업에 대해 반복 알림 사이의 최소 시간(밀리초)입니다(음수가 아닌 정수). -- `mode`: 전달 모드입니다 — `"announce"`는 채널 메시지로 보내고, `"webhook"`은 구성된 webhook으로 POST합니다. -- `accountId`: 알림 전달 범위를 제한할 선택적 계정 또는 채널 ID입니다. +- `enabled`: Cron 작업에 대한 실패 알림을 활성화합니다(기본값: `false`). +- `after`: 알림이 발생하기 전 연속 실패 횟수입니다(양의 정수, 최소값: `1`). +- `cooldownMs`: 같은 작업에 대해 반복 알림 사이의 최소 밀리초 간격입니다(음수가 아닌 정수). +- `mode`: 전달 모드 — `"announce"`는 채널 메시지로 보내고, `"webhook"`은 구성된 Webhook으로 POST합니다. +- `accountId`: 알림 전달 범위를 지정하는 선택적 계정 또는 채널 ID입니다. ### `cron.failureDestination` @@ -3638,51 +3636,51 @@ CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 } ``` -- 모든 작업에 대한 cron 실패 알림의 기본 대상입니다. +- 모든 작업에 걸친 Cron 실패 알림의 기본 대상입니다. - `mode`: `"announce"` 또는 `"webhook"`이며, 충분한 대상 데이터가 있으면 기본값은 `"announce"`입니다. - `channel`: announce 전달용 채널 재정의입니다. `"last"`는 마지막으로 알려진 전달 채널을 재사용합니다. -- `to`: 명시적인 announce 대상 또는 webhook URL입니다. webhook 모드에서는 필수입니다. +- `to`: 명시적 announce 대상 또는 Webhook URL입니다. webhook 모드에서는 필수입니다. - `accountId`: 전달용 선택적 계정 재정의입니다. - 작업별 `delivery.failureDestination`은 이 전역 기본값을 재정의합니다. -- 전역 또는 작업별 실패 대상이 모두 설정되지 않은 경우, 이미 `announce`로 전달하는 작업은 실패 시 해당 기본 announce 대상으로 대체됩니다. +- 전역 또는 작업별 실패 대상이 모두 설정되지 않은 경우, 이미 `announce`로 전달되는 작업은 실패 시 그 기본 announce 대상을 대체값으로 사용합니다. - `delivery.failureDestination`은 작업의 기본 `delivery.mode`가 `"webhook"`인 경우를 제외하면 `sessionTarget="isolated"` 작업에서만 지원됩니다. -[크론 작업](/ko/automation/cron-jobs)을 참조하세요. 격리된 cron 실행은 [백그라운드 작업](/ko/automation/tasks)으로 추적됩니다. +[Cron Jobs](/ko/automation/cron-jobs)를 참고하세요. 격리된 Cron 실행은 [background tasks](/ko/automation/tasks)로 추적됩니다. --- ## 미디어 모델 템플릿 변수 -`tools.media.models[].args`에서 확장되는 템플릿 placeholder: +`tools.media.models[].args`에서 확장되는 템플릿 placeholder입니다: -| 변수 | 설명 | -| ------------------ | ---------------------------------------------- | -| `{{Body}}` | 전체 인바운드 메시지 본문 | -| `{{RawBody}}` | 원시 본문(기록/발신자 래퍼 없음) | -| `{{BodyStripped}}` | 그룹 멘션이 제거된 본문 | -| `{{From}}` | 발신자 식별자 | -| `{{To}}` | 대상 식별자 | -| `{{MessageSid}}` | 채널 메시지 ID | -| `{{SessionId}}` | 현재 세션 UUID | -| `{{IsNewSession}}` | 새 세션이 생성되었을 때 `"true"` | -| `{{MediaUrl}}` | 인바운드 미디어 의사 URL | -| `{{MediaPath}}` | 로컬 미디어 경로 | -| `{{MediaType}}` | 미디어 유형(image/audio/document/…) | -| `{{Transcript}}` | 오디오 transcript | -| `{{Prompt}}` | CLI 항목에 대해 해석된 미디어 프롬프트 | -| `{{MaxChars}}` | CLI 항목에 대해 해석된 최대 출력 문자 수 | -| `{{ChatType}}` | `"direct"` 또는 `"group"` | -| `{{GroupSubject}}` | 그룹 제목(best effort) | -| `{{GroupMembers}}` | 그룹 멤버 미리보기(best effort) | -| `{{SenderName}}` | 발신자 표시 이름(best effort) | -| `{{SenderE164}}` | 발신자 전화번호(best effort) | -| `{{Provider}}` | provider 힌트(whatsapp, telegram, discord 등) | +| 변수 | 설명 | +| ------------------ | ------------------------------------------- | +| `{{Body}}` | 전체 인바운드 메시지 본문 | +| `{{RawBody}}` | 원시 본문(기록/발신자 래퍼 없음) | +| `{{BodyStripped}}` | 그룹 멘션이 제거된 본문 | +| `{{From}}` | 발신자 식별자 | +| `{{To}}` | 대상 식별자 | +| `{{MessageSid}}` | 채널 메시지 ID | +| `{{SessionId}}` | 현재 세션 UUID | +| `{{IsNewSession}}` | 새 세션이 생성되었을 때 `"true"` | +| `{{MediaUrl}}` | 인바운드 미디어 의사 URL | +| `{{MediaPath}}` | 로컬 미디어 경로 | +| `{{MediaType}}` | 미디어 유형(image/audio/document/…) | +| `{{Transcript}}` | 오디오 transcript | +| `{{Prompt}}` | CLI 항목에 대해 해결된 미디어 프롬프트 | +| `{{MaxChars}}` | CLI 항목에 대해 해결된 최대 출력 문자 수 | +| `{{ChatType}}` | `"direct"` 또는 `"group"` | +| `{{GroupSubject}}` | 그룹 제목(best effort) | +| `{{GroupMembers}}` | 그룹 구성원 미리보기(best effort) | +| `{{SenderName}}` | 발신자 표시 이름(best effort) | +| `{{SenderE164}}` | 발신자 전화번호(best effort) | +| `{{Provider}}` | 공급자 힌트(whatsapp, telegram, discord 등) | --- ## 구성 include (`$include`) -구성을 여러 파일로 분리합니다: +구성을 여러 파일로 나눕니다: ```json5 // ~/.openclaw/openclaw.json @@ -3698,12 +3696,12 @@ CLI 가이드 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 **병합 동작:** - 단일 파일: 포함하고 있는 객체를 대체합니다. -- 파일 배열: 순서대로 깊은 병합됩니다(뒤의 항목이 앞의 항목을 재정의). -- 형제 키: include 이후에 병합됩니다(include된 값을 재정의). -- 중첩 include: 최대 10단계 깊이까지 허용됩니다. -- 경로: 포함하는 파일을 기준으로 해석되지만, 최상위 구성 디렉터리(`openclaw.json`의 `dirname`) 내부에 있어야 합니다. 절대 경로나 `../` 형식도 최종적으로 그 경계 내부로 해석되는 경우에만 허용됩니다. -- 오류: 누락된 파일, 구문 분석 오류, 순환 include에 대해 명확한 메시지를 제공합니다. +- 파일 배열: 순서대로 deep-merge됩니다(뒤의 값이 앞의 값을 재정의). +- 형제 키: include 이후 병합됩니다(포함된 값을 재정의). +- 중첩 include: 최대 10단계 깊이까지. +- 경로: 포함하는 파일을 기준으로 해석되지만, 최상위 구성 디렉터리(`openclaw.json`의 `dirname`) 안에 머물러야 합니다. 절대 경로/`../` 형식도 그 경계 안으로 해석되는 경우에만 허용됩니다. +- 오류: 누락된 파일, 파싱 오류, 순환 include에 대해 명확한 메시지를 제공합니다. --- -_관련 항목: [Configuration](/ko/gateway/configuration) · [구성 예시](/ko/gateway/configuration-examples) · [Doctor](/ko/gateway/doctor)_ +_관련 문서: [Configuration](/ko/gateway/configuration) · [Configuration Examples](/ko/gateway/configuration-examples) · [Doctor](/ko/gateway/doctor)_ diff --git a/docs/ko/gateway/local-models.md b/docs/ko/gateway/local-models.md index 266b7ead0..a747a2842 100644 --- a/docs/ko/gateway/local-models.md +++ b/docs/ko/gateway/local-models.md @@ -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..models[].compat.requiresStringContent: true`를 - 설정하세요. -- 일부 더 작거나 엄격한 로컬 백엔드는 OpenClaw의 전체 에이전트 런타임 프롬프트 형태에서, 특히 도구 스키마가 포함되면, 불안정하게 동작합니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에서는 작동하지만 일반적인 OpenClaw 에이전트 턴에서는 실패한다면, 먼저 - `agents.defaults.localModelMode: "lean"`을 시도해 `browser`, `cron`, `message` 같은 - 무거운 기본 도구를 제외하세요. 그래도 실패하면 - `models.providers..models[].compat.supportsTools: false`를 시도하세요. -- 더 큰 OpenClaw 실행에서만 백엔드가 계속 실패한다면, 남은 문제는 보통 OpenClaw의 전송 계층이 아니라 업스트림 모델/서버의 용량 한계 또는 백엔드 버그입니다. +- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 `messages[].content`만 허용합니다. 이런 엔드포인트에는 `models.providers..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..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을 켜 두세요. diff --git a/docs/ko/help/testing.md b/docs/ko/help/testing.md index 3ed0aaf09..2309b40f8 100644 --- a/docs/ko/help/testing.md +++ b/docs/ko/help/testing.md @@ -1,29 +1,29 @@ --- read_when: - 로컬 또는 CI에서 테스트 실행하기 - - 모델/프로바이더 버그에 대한 회귀 테스트 추가하기 + - 모델/제공자 버그에 대한 회귀 테스트 추가하기 - Gateway + 에이전트 동작 디버깅하기 -summary: '테스트 키트: unit/e2e/live 스위트, Docker 러너, 그리고 각 테스트가 다루는 내용' +summary: '테스트 키트: 단위/e2e/라이브 스위트, Docker 실행기, 그리고 각 테스트가 다루는 내용' title: 테스트 x-i18n: - generated_at: "2026-04-15T06:00:36Z" + generated_at: "2026-04-15T14:40:31Z" model: gpt-5.4 provider: openai - source_hash: fbf647a5cf13b5861a3ba0cb367dc816c57f0e9c60d3cd6320da193bfadf5609 + source_hash: ec3632cafa1f38b27510372391b84af744266df96c58f7fac98aa03763465db8 source_path: help/testing.md workflow: 15 --- # 테스트 -OpenClaw에는 세 가지 Vitest 스위트(unit/integration, e2e, live)와 소수의 Docker 러너가 있습니다. +OpenClaw에는 세 가지 Vitest 스위트(단위/통합, e2e, 라이브)와 소수의 Docker 실행기가 있습니다. -이 문서는 “우리가 테스트하는 방법” 가이드입니다: +이 문서는 “우리가 어떻게 테스트하는가”에 대한 가이드입니다. -- 각 스위트가 무엇을 다루는지(그리고 의도적으로 _다루지 않는_ 것은 무엇인지) -- 일반적인 워크플로(로컬, 푸시 전, 디버깅)에 어떤 명령을 실행해야 하는지 -- live 테스트가 자격 증명을 어떻게 찾고 모델/프로바이더를 선택하는지 -- 실제 모델/프로바이더 이슈에 대한 회귀 테스트를 추가하는 방법 +- 각 스위트가 무엇을 다루는지(그리고 의도적으로 무엇을 다루지 않는지) +- 일반적인 워크플로(로컬, 푸시 전, 디버깅)에서 어떤 명령을 실행해야 하는지 +- 라이브 테스트가 자격 증명을 어떻게 찾고 모델/제공자를 어떻게 선택하는지 +- 실제 모델/제공자 이슈에 대한 회귀 테스트를 어떻게 추가하는지 ## 빠른 시작 @@ -31,84 +31,83 @@ OpenClaw에는 세 가지 Vitest 스위트(unit/integration, e2e, live)와 소 - 전체 게이트(푸시 전에 기대됨): `pnpm build && pnpm check && pnpm test` - 여유 있는 머신에서 더 빠른 로컬 전체 스위트 실행: `pnpm test:max` -- 직접 Vitest watch 루프: `pnpm test:watch` -- 직접 파일 지정은 이제 extension/channel 경로도 라우팅합니다: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- 하나의 실패를 반복 수정하는 중이라면 먼저 대상 범위를 좁힌 실행을 우선하세요. +- 직접 Vitest 감시 루프: `pnpm test:watch` +- 직접 파일 지정은 이제 확장/채널 경로도 라우팅합니다: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- 하나의 실패를 반복 수정하는 중이라면 먼저 대상 범위를 좁힌 실행을 선호하세요. - Docker 기반 QA 사이트: `pnpm qa:lab:up` - Linux VM 기반 QA 레인: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -테스트를 수정했거나 추가 확신이 필요할 때: +테스트를 건드렸거나 더 높은 신뢰가 필요할 때: - 커버리지 게이트: `pnpm test:coverage` - E2E 스위트: `pnpm test:e2e` -실제 프로바이더/모델을 디버깅할 때(실제 자격 증명 필요): +실제 제공자/모델을 디버깅할 때(실제 자격 증명 필요): -- live 스위트(모델 + Gateway tool/image probe): `pnpm test:live` -- 하나의 live 파일만 조용히 대상으로 지정: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- 라이브 스위트(모델 + Gateway 도구/이미지 프로브): `pnpm test:live` +- 하나의 라이브 파일만 조용히 대상으로 지정: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -팁: 하나의 실패 케이스만 필요하다면 아래에 설명된 allowlist 환경 변수를 사용해 live 테스트 범위를 좁히는 편이 좋습니다. +팁: 실패하는 단일 케이스만 필요하다면, 아래에 설명된 허용 목록 환경 변수를 사용해 라이브 테스트 범위를 좁히는 것을 선호하세요. -## QA 전용 러너 +## QA 전용 실행기 -이 명령들은 QA-lab 수준의 현실성이 필요할 때 메인 테스트 스위트와 함께 사용합니다: +이 명령들은 QA-lab 수준의 현실성이 필요할 때 주 테스트 스위트 옆에서 사용합니다. - `pnpm openclaw qa suite` - 저장소 기반 QA 시나리오를 호스트에서 직접 실행합니다. - - 기본적으로 선택된 여러 시나리오를 격리된 gateway worker와 함께 병렬 실행하며, 최대 64개 worker 또는 선택된 시나리오 수까지 사용합니다. worker 수를 조정하려면 `--concurrency `를 사용하고, 이전의 직렬 레인을 원하면 `--concurrency 1`을 사용하세요. + - 기본적으로 격리된 Gateway 워커를 사용해 여러 선택된 시나리오를 병렬로 실행하며, 최대 64개 워커 또는 선택한 시나리오 수 중 작은 값까지 사용합니다. 워커 수를 조정하려면 `--concurrency `를 사용하고, 이전의 직렬 레인을 원하면 `--concurrency 1`을 사용하세요. - `pnpm openclaw qa suite --runner multipass` - 동일한 QA 스위트를 일회용 Multipass Linux VM 내부에서 실행합니다. - 호스트의 `qa suite`와 동일한 시나리오 선택 동작을 유지합니다. - - `qa suite`와 동일한 프로바이더/모델 선택 플래그를 재사용합니다. - - live 실행은 게스트에서 실용적인 지원 QA 인증 입력을 전달합니다: - 환경 변수 기반 프로바이더 키, QA live 프로바이더 설정 경로, 그리고 존재할 경우 `CODEX_HOME`. - - 게스트가 마운트된 워크스페이스를 통해 다시 쓸 수 있도록 출력 디렉터리는 저장소 루트 아래에 있어야 합니다. - - 일반 QA 리포트 + 요약과 함께 Multipass 로그를 `.artifacts/qa-e2e/...` 아래에 기록합니다. + - `qa suite`와 동일한 제공자/모델 선택 플래그를 재사용합니다. + - 라이브 실행은 게스트에 실용적으로 전달 가능한 지원되는 QA 인증 입력을 전달합니다: + 환경 변수 기반 제공자 키, QA 라이브 제공자 설정 경로, 그리고 존재할 경우 `CODEX_HOME`. + - 출력 디렉터리는 게스트가 마운트된 워크스페이스를 통해 다시 쓸 수 있도록 저장소 루트 아래에 있어야 합니다. + - 일반 QA 보고서 + 요약과 함께 Multipass 로그를 `.artifacts/qa-e2e/...` 아래에 기록합니다. - `pnpm qa:lab:up` - - 운영자 스타일 QA 작업을 위해 Docker 기반 QA 사이트를 시작합니다. + - 운영자 스타일 QA 작업을 위한 Docker 기반 QA 사이트를 시작합니다. - `pnpm openclaw qa matrix` - - 일회용 Docker 기반 Tuwunel homeserver에 대해 Matrix live QA 레인을 실행합니다. + - 일회용 Docker 기반 Tuwunel 홈서버를 대상으로 Matrix 라이브 QA 레인을 실행합니다. - 이 QA 호스트는 현재 저장소/개발 전용입니다. 패키지된 OpenClaw 설치에는 `qa-lab`이 포함되지 않으므로 `openclaw qa`를 노출하지 않습니다. - - 저장소 체크아웃은 번들된 러너를 직접 로드하며 별도의 plugin 설치 단계가 필요하지 않습니다. - - 세 개의 임시 Matrix 사용자(`driver`, `sut`, `observer`)와 하나의 비공개 방을 프로비저닝한 뒤, 실제 Matrix plugin을 SUT 전송 계층으로 사용하는 QA gateway child를 시작합니다. - - 기본적으로 고정된 안정 Tuwunel 이미지 `ghcr.io/matrix-construct/tuwunel:v1.5.1`를 사용합니다. 다른 이미지를 테스트해야 한다면 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`로 재정의하세요. - - Matrix는 로컬에서 일회용 사용자를 프로비저닝하므로 공유 자격 증명 소스 플래그를 노출하지 않습니다. - - Matrix QA 리포트, 요약, 관찰된 이벤트 아티팩트를 `.artifacts/qa-e2e/...` 아래에 기록합니다. + - 저장소 체크아웃은 번들된 실행기를 직접 로드하므로 별도의 Plugin 설치 단계가 필요하지 않습니다. + - 임시 Matrix 사용자 세 명(`driver`, `sut`, `observer`)과 비공개 방 하나를 프로비저닝한 뒤, 실제 Matrix Plugin을 SUT 전송 계층으로 사용하는 QA Gateway 자식을 시작합니다. + - 기본적으로 고정된 안정 Tuwunel 이미지 `ghcr.io/matrix-construct/tuwunel:v1.5.1`를 사용합니다. 다른 이미지를 테스트해야 할 때는 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`로 재정의하세요. + - Matrix는 레인이 로컬에서 일회용 사용자를 프로비저닝하므로 공유 자격 증명 소스 플래그를 노출하지 않습니다. + - Matrix QA 보고서, 요약, 관찰된 이벤트 아티팩트를 `.artifacts/qa-e2e/...` 아래에 기록합니다. - `pnpm openclaw qa telegram` - - 환경 변수의 driver 및 SUT bot 토큰을 사용해 실제 비공개 그룹에 대해 Telegram live QA 레인을 실행합니다. - - `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`이 필요합니다. 그룹 ID는 숫자형 Telegram chat ID여야 합니다. - - 공유 풀 자격 증명에는 `--credential-source convex`를 지원합니다. 기본적으로 env 모드를 사용하고, 풀 lease를 사용하려면 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`를 설정하세요. - - 동일한 비공개 그룹 안에 서로 다른 두 bot이 필요하며, SUT bot은 Telegram 사용자 이름을 노출해야 합니다. - - 안정적인 bot 간 관찰을 위해 `@BotFather`에서 두 bot 모두에 대해 Bot-to-Bot Communication Mode를 활성화하고, driver bot이 그룹 bot 트래픽을 관찰할 수 있게 하세요. - - Telegram QA 리포트, 요약, 관찰된 메시지 아티팩트를 `.artifacts/qa-e2e/...` 아래에 기록합니다. + - 환경 변수의 driver 및 SUT 봇 토큰을 사용해 실제 비공개 그룹을 대상으로 Telegram 라이브 QA 레인을 실행합니다. + - `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`가 필요합니다. 그룹 ID는 숫자형 Telegram 채팅 ID여야 합니다. + - 공유 풀 자격 증명을 위해 `--credential-source convex`를 지원합니다. 기본적으로는 env 모드를 사용하고, 풀링된 임대를 사용하려면 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`를 설정하세요. + - 동일한 비공개 그룹 안에 있는 서로 다른 두 개의 봇이 필요하며, SUT 봇은 Telegram 사용자 이름을 노출해야 합니다. + - 안정적인 봇 간 관찰을 위해 `@BotFather`에서 두 봇 모두에 대해 Bot-to-Bot Communication Mode를 활성화하고, driver 봇이 그룹의 봇 트래픽을 관찰할 수 있게 하세요. + - Telegram QA 보고서, 요약, 관찰된 메시지 아티팩트를 `.artifacts/qa-e2e/...` 아래에 기록합니다. -live 전송 레인은 새 전송이 드리프트하지 않도록 하나의 표준 계약을 공유합니다: +라이브 전송 레인은 새 전송 계층이 드리프트하지 않도록 하나의 표준 계약을 공유합니다. -`qa-channel`은 여전히 광범위한 synthetic QA 스위트이며 live 전송 커버리지 매트릭스의 일부는 아닙니다. +`qa-channel`은 여전히 광범위한 합성 QA 스위트이며 라이브 전송 커버리지 매트릭스의 일부는 아닙니다. -| 레인 | 카나리 | 멘션 게이팅 | allowlist 차단 | 최상위 답장 | 재시작 복구 | 스레드 후속 응답 | 스레드 격리 | 반응 관찰 | 도움말 명령 | -| -------- | ------ | ----------- | -------------- | ----------- | ----------- | ---------------- | ----------- | --------- | ----------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| 레인 | 카나리 | 멘션 게이팅 | 허용 목록 차단 | 최상위 응답 | 재시작 후 재개 | 스레드 후속 응답 | 스레드 격리 | 반응 관찰 | 도움말 명령 | +| ---- | ------ | ----------- | -------------- | ----------- | -------------- | ---------------- | ----------- | --------- | ----------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Convex를 통한 공유 Telegram 자격 증명 (v1) -`openclaw qa telegram`에 대해 `--credential-source convex`(또는 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`)가 활성화되면, -QA lab은 Convex 기반 풀에서 배타적 lease를 획득하고, 레인이 실행되는 동안 해당 lease에 Heartbeat를 보내며, 종료 시 lease를 해제합니다. +`openclaw qa telegram`에 대해 `--credential-source convex`(또는 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`)가 활성화되면 QA lab은 Convex 기반 풀에서 독점 임대를 획득하고, 레인이 실행되는 동안 해당 임대에 Heartbeat를 보내며, 종료 시 임대를 해제합니다. -참조 Convex 프로젝트 스캐폴드: +참조용 Convex 프로젝트 스캐폴드: - `qa/convex-credential-broker/` 필수 환경 변수: - `OPENCLAW_QA_CONVEX_SITE_URL` (예: `https://your-deployment.convex.site`) -- 선택한 역할에 대한 하나의 secret: +- 선택한 역할에 대한 비밀 하나: - `maintainer`용 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` - `ci`용 `OPENCLAW_QA_CONVEX_SECRET_CI` - 자격 증명 역할 선택: - CLI: `--credential-role maintainer|ci` - - 기본 환경 변수: `OPENCLAW_QA_CREDENTIAL_ROLE` (`maintainer`가 기본값) + - 환경 변수 기본값: `OPENCLAW_QA_CREDENTIAL_ROLE` (`maintainer`가 기본값) 선택적 환경 변수: @@ -120,12 +119,12 @@ QA lab은 Convex 기반 풀에서 배타적 lease를 획득하고, 레인이 실 - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (선택적 추적 ID) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1`은 로컬 전용 개발을 위해 loopback `http://` Convex URL을 허용합니다. -일반 운영에서는 `OPENCLAW_QA_CONVEX_SITE_URL`에 `https://`를 사용해야 합니다. +정상 운영에서는 `OPENCLAW_QA_CONVEX_SITE_URL`에 `https://`를 사용해야 합니다. -관리자용 admin 명령(pool 추가/제거/목록)은 -특히 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`를 필요로 합니다. +관리자용 관리 명령(풀 추가/제거/목록)은 구체적으로 +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`가 필요합니다. -관리자용 CLI 도우미: +관리자를 위한 CLI 도우미: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -133,85 +132,85 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -스크립트 및 CI 유틸리티에서 기계가 읽을 수 있는 출력을 원하면 `--json`을 사용하세요. +스크립트와 CI 유틸리티에서 기계가 읽을 수 있는 출력을 원하면 `--json`을 사용하세요. -기본 엔드포인트 계약 (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +기본 엔드포인트 계약(`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - 요청: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` - 성공: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` - - 고갈/재시도 가능: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` + - 소진/재시도 가능: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` - `POST /heartbeat` - 요청: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` - - 성공: `{ status: "ok" }` (또는 비어 있는 `2xx`) + - 성공: `{ status: "ok" }` (또는 빈 `2xx`) - `POST /release` - 요청: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - - 성공: `{ status: "ok" }` (또는 비어 있는 `2xx`) -- `POST /admin/add` (maintainer secret 전용) + - 성공: `{ status: "ok" }` (또는 빈 `2xx`) +- `POST /admin/add` (관리자 비밀 전용) - 요청: `{ kind, actorId, payload, note?, status? }` - 성공: `{ status: "ok", credential }` -- `POST /admin/remove` (maintainer secret 전용) +- `POST /admin/remove` (관리자 비밀 전용) - 요청: `{ credentialId, actorId }` - 성공: `{ status: "ok", changed, credential }` - - 활성 lease 보호: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (maintainer secret 전용) + - 활성 임대 보호: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (관리자 비밀 전용) - 요청: `{ kind?, status?, includePayload?, limit? }` - 성공: `{ status: "ok", credentials, count }` -Telegram 종류의 payload 형태: +Telegram 종류의 페이로드 형태: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId`는 숫자형 Telegram chat ID 문자열이어야 합니다. -- `admin/add`는 `kind: "telegram"`에 대해 이 형태를 검증하고 잘못된 payload를 거부합니다. +- `groupId`는 숫자형 Telegram 채팅 ID 문자열이어야 합니다. +- `admin/add`는 `kind: "telegram"`에 대해 이 형태를 검증하고 잘못된 페이로드를 거부합니다. ### QA에 채널 추가하기 -Markdown QA 시스템에 채널을 추가하려면 정확히 두 가지가 필요합니다: +마크다운 QA 시스템에 채널을 추가하려면 정확히 두 가지가 필요합니다: 1. 해당 채널용 전송 어댑터 2. 채널 계약을 검증하는 시나리오 팩 -공유 `qa-lab` 호스트가 흐름을 소유할 수 있다면 새로운 최상위 QA 명령 루트를 추가하지 마세요. +공유 `qa-lab` 호스트가 흐름을 소유할 수 있는 경우 새로운 최상위 QA 명령 루트를 추가하지 마세요. `qa-lab`은 공유 호스트 메커니즘을 소유합니다: - `openclaw qa` 명령 루트 - 스위트 시작 및 종료 -- worker 동시성 +- 워커 동시성 - 아티팩트 기록 -- 리포트 생성 +- 보고서 생성 - 시나리오 실행 -- 이전 `qa-channel` 시나리오용 호환성 별칭 +- 이전 `qa-channel` 시나리오를 위한 호환성 별칭 -러너 plugin은 전송 계약을 소유합니다: +실행기 Plugin은 전송 계약을 소유합니다: -- 공유 `qa` 루트 아래에 `openclaw qa `를 어떻게 마운트하는지 -- 해당 전송을 위해 gateway를 어떻게 설정하는지 +- `openclaw qa `가 공유 `qa` 루트 아래에 어떻게 마운트되는지 +- 해당 전송 계층에 맞게 Gateway를 어떻게 구성하는지 - 준비 상태를 어떻게 확인하는지 - 인바운드 이벤트를 어떻게 주입하는지 - 아웃바운드 메시지를 어떻게 관찰하는지 -- 트랜스크립트와 정규화된 전송 상태를 어떻게 노출하는지 -- 전송 기반 작업을 어떻게 실행하는지 -- 전송별 리셋 또는 정리를 어떻게 처리하는지 +- 전사본과 정규화된 전송 상태를 어떻게 노출하는지 +- 전송 기반 액션을 어떻게 실행하는지 +- 전송별 재설정 또는 정리를 어떻게 처리하는지 -새 채널에 대한 최소 도입 기준은 다음과 같습니다: +새 채널의 최소 도입 기준은 다음과 같습니다: 1. 공유 `qa` 루트의 소유자는 `qa-lab`으로 유지합니다. -2. 공유 `qa-lab` 호스트 시임에서 전송 러너를 구현합니다. -3. 전송별 메커니즘은 러너 plugin 또는 채널 하니스 내부에 유지합니다. -4. 경쟁하는 루트 명령을 등록하는 대신 러너를 `openclaw qa `로 마운트합니다. - 러너 plugin은 `openclaw.plugin.json`에 `qaRunners`를 선언하고 `runtime-api.ts`에서 일치하는 `qaRunnerCliRegistrations` 배열을 내보내야 합니다. - `runtime-api.ts`는 가볍게 유지하세요. 지연 CLI 및 러너 실행은 별도의 엔트리포인트 뒤에 두어야 합니다. -5. `qa/scenarios/` 아래에 markdown 시나리오를 작성하거나 조정합니다. +2. 공유 `qa-lab` 호스트 시임에서 전송 실행기를 구현합니다. +3. 전송별 메커니즘은 해당 실행기 Plugin 또는 채널 하네스 내부에 유지합니다. +4. 경쟁하는 루트 명령을 등록하는 대신 실행기를 `openclaw qa `로 마운트합니다. + 실행기 Plugin은 `openclaw.plugin.json`에 `qaRunners`를 선언하고 `runtime-api.ts`에서 일치하는 `qaRunnerCliRegistrations` 배열을 export해야 합니다. + `runtime-api.ts`는 가볍게 유지하세요. 지연 CLI 및 실행기 실행은 별도의 진입점 뒤에 남아 있어야 합니다. +5. `qa/scenarios/` 아래에 마크다운 시나리오를 작성하거나 조정합니다. 6. 새 시나리오에는 일반 시나리오 도우미를 사용합니다. -7. 저장소가 의도적인 마이그레이션을 수행 중이 아닌 한 기존 호환성 별칭은 계속 동작하게 유지합니다. +7. 저장소가 의도적인 마이그레이션을 수행 중인 경우가 아니라면 기존 호환성 별칭이 계속 작동하도록 유지합니다. -판단 규칙은 엄격합니다: +결정 규칙은 엄격합니다: -- 동작을 `qa-lab`에서 한 번만 표현할 수 있다면 `qa-lab`에 두세요. -- 동작이 하나의 채널 전송에 의존한다면 해당 러너 plugin 또는 plugin 하니스에 유지하세요. -- 시나리오에 둘 이상의 채널이 사용할 수 있는 새 기능이 필요하다면 `suite.ts`에 채널별 분기를 추가하는 대신 일반 도우미를 추가하세요. -- 동작이 하나의 전송에서만 의미가 있다면 시나리오를 전송별로 유지하고 시나리오 계약에서 이를 명확히 하세요. +- 동작을 `qa-lab`에서 한 번만 표현할 수 있다면 `qa-lab`에 넣으세요. +- 동작이 하나의 채널 전송 계층에 의존한다면 해당 실행기 Plugin 또는 Plugin 하네스에 유지하세요. +- 시나리오가 둘 이상의 채널에서 사용할 수 있는 새 기능을 필요로 한다면 `suite.ts`에 채널별 분기를 추가하는 대신 일반 도우미를 추가하세요. +- 동작이 하나의 전송 계층에서만 의미가 있다면 시나리오를 전송별로 유지하고 시나리오 계약에서 이를 명시하세요. 새 시나리오에 권장되는 일반 도우미 이름은 다음과 같습니다: @@ -228,7 +227,7 @@ Markdown QA 시스템에 채널을 추가하려면 정확히 두 가지가 필 - `formatTransportTranscript` - `resetTransport` -기존 시나리오를 위한 호환성 별칭도 계속 사용할 수 있습니다. 예를 들면: +기존 시나리오를 위해 다음과 같은 호환성 별칭도 계속 사용할 수 있습니다: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -236,243 +235,242 @@ Markdown QA 시스템에 채널을 추가하려면 정확히 두 가지가 필 - `formatConversationTranscript` - `resetBus` -새 채널 작업에는 일반 도우미 이름을 사용해야 합니다. -호환성 별칭은 일괄 전환 없는 마이그레이션을 피하기 위해 존재하는 것이지, -새 시나리오 작성의 모델이 아닙니다. +새 채널 작업에서는 일반 도우미 이름을 사용해야 합니다. +호환성 별칭은 플래그 데이 마이그레이션을 피하기 위해 존재하는 것이지, 새 시나리오 작성의 모델이 아닙니다. -## 테스트 스위트(무엇이 어디서 실행되는가) +## 테스트 스위트(무엇이 어디서 실행되는지) -스위트는 “현실성이 점점 높아지는 단계”(그리고 불안정성/비용도 점점 높아짐)로 생각하면 됩니다: +스위트는 “현실성이 점점 높아지는 것”(그리고 불안정성/비용도 함께 증가하는 것)으로 생각하세요: -### Unit / integration (기본값) +### 단위 / 통합 (기본값) -- 명령어: `pnpm test` +- 명령: `pnpm test` - 설정: 기존 범위별 Vitest 프로젝트에 대해 순차적으로 실행되는 10개의 샤드(`vitest.full-*.config.ts`) -- 파일: `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` 아래의 core/unit 인벤토리와 `vitest.unit.config.ts`가 포함하는 허용된 `ui` node 테스트 +- 파일: `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` 아래의 코어/단위 인벤토리와 `vitest.unit.config.ts`가 다루는 허용 목록 기반 `ui` Node 테스트 - 범위: - - 순수 unit 테스트 - - 프로세스 내 integration 테스트(gateway auth, routing, tooling, parsing, config) + - 순수 단위 테스트 + - 프로세스 내부 통합 테스트(Gateway 인증, 라우팅, 도구화, 파싱, 설정) - 알려진 버그에 대한 결정적 회귀 테스트 -- 기대 사항: +- 기대사항: - CI에서 실행됨 - - 실제 키 불필요 + - 실제 키가 필요하지 않음 - 빠르고 안정적이어야 함 - 프로젝트 참고: - - 범위를 지정하지 않은 `pnpm test`는 이제 하나의 거대한 네이티브 루트 프로젝트 프로세스 대신 열한 개의 더 작은 샤드 설정(`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`)을 실행합니다. 이렇게 하면 부하가 있는 머신에서 피크 RSS를 줄이고 auto-reply/extension 작업이 관련 없는 스위트를 굶기지 않게 합니다. - - `pnpm test --watch`는 다중 샤드 watch 루프가 현실적이지 않기 때문에 여전히 네이티브 루트 `vitest.config.ts` 프로젝트 그래프를 사용합니다. - - `pnpm test`, `pnpm test:watch`, `pnpm test:perf:imports`는 이제 명시적 파일/디렉터리 대상을 먼저 범위별 레인으로 라우팅하므로, `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`는 전체 루트 프로젝트 시작 비용을 치르지 않습니다. - - `pnpm test:changed`는 변경 diff가 라우팅 가능한 소스/테스트 파일만 건드릴 때 변경된 git 경로를 동일한 범위별 레인으로 확장합니다. config/setup 편집은 여전히 넓은 루트 프로젝트 재실행으로 폴백합니다. - - agents, commands, plugins, auto-reply helper, `plugin-sdk` 및 유사한 순수 유틸리티 영역의 import 경량 unit 테스트는 `test/setup-openclaw-runtime.ts`를 건너뛰는 `unit-fast` 레인을 통해 라우팅됩니다. 상태 의존적이거나 runtime이 무거운 파일은 기존 레인에 남습니다. - - 선택된 `plugin-sdk` 및 `commands` helper 소스 파일도 changed 모드 실행을 해당 경량 레인의 명시적 인접 테스트에 매핑하므로, helper 편집 시 그 디렉터리의 전체 무거운 스위트를 다시 실행하지 않아도 됩니다. - - `auto-reply`는 이제 세 개의 전용 버킷을 가집니다: 최상위 core helper, 최상위 `reply.*` integration 테스트, 그리고 `src/auto-reply/reply/**` 서브트리. 이렇게 하면 가장 무거운 reply 하니스 작업이 저렴한 status/chunk/token 테스트에 얹히지 않게 됩니다. -- 임베디드 러너 참고: - - 메시지 도구 탐색 입력이나 Compaction runtime 컨텍스트를 변경할 때는 두 수준의 커버리지를 모두 유지하세요. - - 순수 routing/normalization 경계를 위한 집중된 helper 회귀 테스트를 추가하세요. - - 또한 임베디드 러너 integration 스위트도 정상 상태를 유지해야 합니다: + - 대상 지정 없이 실행하는 `pnpm test`는 이제 하나의 거대한 네이티브 루트 프로젝트 프로세스 대신 11개의 더 작은 샤드 설정(`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`)을 실행합니다. 이렇게 하면 부하가 있는 머신에서 최대 RSS를 줄이고 auto-reply/extension 작업이 관련 없는 스위트를 굶기지 않게 합니다. + - `pnpm test --watch`는 다중 샤드 감시 루프가 실용적이지 않기 때문에 여전히 네이티브 루트 `vitest.config.ts` 프로젝트 그래프를 사용합니다. + - `pnpm test`, `pnpm test:watch`, `pnpm test:perf:imports`는 명시적인 파일/디렉터리 대상을 먼저 범위가 좁은 레인으로 라우팅하므로 `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`는 전체 루트 프로젝트 시작 비용을 치르지 않습니다. + - `pnpm test:changed`는 변경된 git 경로가 라우팅 가능한 소스/테스트 파일만 건드릴 경우 이를 동일한 범위별 레인으로 확장합니다. 설정/초기화 편집은 여전히 광범위한 루트 프로젝트 재실행으로 대체됩니다. + - 에이전트, 명령, Plugin, auto-reply 도우미, `plugin-sdk`, 그리고 유사한 순수 유틸리티 영역의 import가 가벼운 단위 테스트는 `test/setup-openclaw-runtime.ts`를 건너뛰는 `unit-fast` 레인을 통과합니다. 상태를 가지거나 런타임이 무거운 파일은 기존 레인에 남습니다. + - 선택된 `plugin-sdk` 및 `commands` 도우미 소스 파일도 변경 모드 실행을 해당 가벼운 레인의 명시적 형제 테스트에 매핑하므로, 도우미 편집 시 그 디렉터리의 전체 무거운 스위트를 다시 실행하지 않아도 됩니다. + - `auto-reply`는 이제 세 개의 전용 버킷을 가집니다: 최상위 코어 도우미, 최상위 `reply.*` 통합 테스트, 그리고 `src/auto-reply/reply/**` 하위 트리. 이렇게 하면 가장 무거운 reply 하네스 작업이 저렴한 status/chunk/token 테스트에 올라타지 않게 됩니다. +- 임베디드 실행기 참고: + - 메시지 도구 검색 입력이나 Compaction 런타임 컨텍스트를 변경할 때는 두 수준의 커버리지를 모두 유지하세요. + - 순수 라우팅/정규화 경계에 대해서는 집중된 도우미 회귀 테스트를 추가하세요. + - 또한 임베디드 실행기 통합 스위트도 건강하게 유지해야 합니다: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, 그리고 `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - 이 스위트들은 범위 지정된 ID와 Compaction 동작이 실제 `run.ts` / `compact.ts` 경로를 통해 계속 흐르는지 검증합니다. helper 전용 테스트만으로는 이러한 integration 경로를 대체하기에 충분하지 않습니다. + - 이 스위트들은 범위가 정해진 ID와 Compaction 동작이 실제 `run.ts` / `compact.ts` 경로를 통해 계속 흐르는지 검증합니다. 도우미 전용 테스트만으로는 이러한 통합 경로를 충분히 대체할 수 없습니다. - 풀 참고: - 기본 Vitest 설정은 이제 기본적으로 `threads`를 사용합니다. - - 공유 Vitest 설정은 또한 `isolate: false`를 고정하며 루트 프로젝트, e2e, live 설정 전반에서 비격리 러너를 사용합니다. - - 루트 UI 레인은 `jsdom` 설정과 optimizer를 유지하지만, 이제 공유 비격리 러너에서도 실행됩니다. - - 각 `pnpm test` 샤드는 공유 Vitest 설정에서 동일한 `threads` + `isolate: false` 기본값을 상속받습니다. - - 공유 `scripts/run-vitest.mjs` 런처는 큰 로컬 실행 중 V8 컴파일 churn을 줄이기 위해 이제 기본적으로 Vitest child Node 프로세스에 `--no-maglev`도 추가합니다. 기본 V8 동작과 비교해야 한다면 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`을 설정하세요. + - 공유 Vitest 설정은 또한 `isolate: false`를 고정하고 루트 프로젝트, e2e, 라이브 설정 전반에서 비격리 실행기를 사용합니다. + - 루트 UI 레인은 `jsdom` 설정과 최적화 구성을 유지하지만 이제 공유 비격리 실행기에서도 실행됩니다. + - 각 `pnpm test` 샤드는 공유 Vitest 설정으로부터 동일한 `threads` + `isolate: false` 기본값을 상속받습니다. + - 공유 `scripts/run-vitest.mjs` 실행기는 큰 로컬 실행 중 V8 컴파일 변동을 줄이기 위해 이제 기본적으로 Vitest 자식 Node 프로세스에 `--no-maglev`도 추가합니다. 기본 V8 동작과 비교해야 하면 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`을 설정하세요. - 빠른 로컬 반복 참고: - - `pnpm test:changed`는 변경 경로가 더 작은 스위트에 깔끔하게 매핑될 때 범위별 레인을 통해 라우팅됩니다. - - `pnpm test:max`와 `pnpm test:changed:max`는 동일한 라우팅 동작을 유지하되 worker 상한만 더 높습니다. - - 로컬 worker 자동 스케일링은 이제 의도적으로 보수적으로 동작하며, 호스트 load average가 이미 높을 때도 자동으로 물러나므로 여러 개의 동시 Vitest 실행이 기본적으로 덜 해롭습니다. - - 기본 Vitest 설정은 프로젝트/설정 파일을 `forceRerunTriggers`로 표시하므로 테스트 연결 방식이 바뀌었을 때 changed 모드 재실행이 올바르게 유지됩니다. - - 이 설정은 지원되는 호스트에서 `OPENCLAW_VITEST_FS_MODULE_CACHE`를 계속 활성화합니다. 직접 프로파일링을 위한 명시적 캐시 위치가 필요하면 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`를 설정하세요. + - `pnpm test:changed`는 변경된 경로가 더 작은 스위트에 깔끔하게 매핑될 때 범위별 레인을 통해 라우팅합니다. + - `pnpm test:max`와 `pnpm test:changed:max`도 동일한 라우팅 동작을 유지하되, 더 높은 워커 상한만 사용합니다. + - 로컬 워커 자동 확장은 이제 의도적으로 더 보수적이며 호스트의 로드 평균이 이미 높을 때도 물러나므로, 동시에 여러 Vitest 실행이 기본적으로 덜 큰 피해를 주게 됩니다. + - 기본 Vitest 설정은 프로젝트/설정 파일을 `forceRerunTriggers`로 표시하여 테스트 연결 구성이 바뀔 때 변경 모드 재실행이 올바르게 유지되도록 합니다. + - 이 설정은 지원되는 호스트에서 `OPENCLAW_VITEST_FS_MODULE_CACHE`를 계속 활성화합니다. 직접 프로파일링을 위해 명시적인 하나의 캐시 위치를 원한다면 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`를 설정하세요. - 성능 디버그 참고: - `pnpm test:perf:imports`는 Vitest import-duration 보고와 import-breakdown 출력을 활성화합니다. - - `pnpm test:perf:imports:changed`는 동일한 프로파일링 보기를 `origin/main` 이후 변경된 파일로 범위 제한합니다. -- `pnpm test:perf:changed:bench -- --ref `는 해당 커밋된 diff에 대해 라우팅된 `test:changed`와 네이티브 루트 프로젝트 경로를 비교하고 wall time과 macOS 최대 RSS를 출력합니다. -- `pnpm test:perf:changed:bench -- --worktree`는 변경된 파일 목록을 `scripts/test-projects.mjs`와 루트 Vitest 설정을 통해 라우팅하여 현재 dirty 트리를 벤치마크합니다. - - `pnpm test:perf:profile:main`은 Vitest/Vite 시작 및 transform 오버헤드에 대한 메인 스레드 CPU 프로파일을 기록합니다. - - `pnpm test:perf:profile:runner`는 파일 병렬성을 비활성화한 unit 스위트에 대해 러너 CPU+heap 프로파일을 기록합니다. + - `pnpm test:perf:imports:changed`는 동일한 프로파일링 뷰를 `origin/main` 이후 변경된 파일로 범위를 좁혀 제공합니다. +- `pnpm test:perf:changed:bench -- --ref `는 해당 커밋된 diff에 대해 라우팅된 `test:changed`와 네이티브 루트 프로젝트 경로를 비교하고 wall time 및 macOS 최대 RSS를 출력합니다. +- `pnpm test:perf:changed:bench -- --worktree`는 변경된 파일 목록을 `scripts/test-projects.mjs`와 루트 Vitest 설정을 통해 라우팅하여 현재 dirty 트리를 벤치마킹합니다. + - `pnpm test:perf:profile:main`은 Vitest/Vite 시작 및 변환 오버헤드에 대한 메인 스레드 CPU 프로파일을 기록합니다. + - `pnpm test:perf:profile:runner`는 파일 병렬 처리를 비활성화한 단위 스위트에 대해 실행기 CPU+힙 프로파일을 기록합니다. ### E2E (Gateway 스모크) -- 명령어: `pnpm test:e2e` +- 명령: `pnpm test:e2e` - 설정: `vitest.e2e.config.ts` - 파일: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- 기본 runtime: - - 저장소의 나머지와 동일하게 Vitest `threads`와 `isolate: false`를 사용합니다. - - 적응형 worker를 사용합니다(CI: 최대 2, 로컬: 기본 1). - - 콘솔 I/O 오버헤드를 줄이기 위해 기본적으로 silent 모드로 실행됩니다. +- 기본 런타임: + - 저장소의 나머지 부분과 일치하게 Vitest `threads`와 `isolate: false`를 사용합니다. + - 적응형 워커를 사용합니다(CI: 최대 2, 로컬: 기본값 1). + - 콘솔 I/O 오버헤드를 줄이기 위해 기본적으로 무음 모드로 실행됩니다. - 유용한 재정의: - - worker 수를 강제로 지정하려면 `OPENCLAW_E2E_WORKERS=`(상한 16) + - 워커 수를 강제하려면 `OPENCLAW_E2E_WORKERS=` (상한 16) - 자세한 콘솔 출력을 다시 활성화하려면 `OPENCLAW_E2E_VERBOSE=1` - 범위: - - 다중 인스턴스 Gateway 종단 간 동작 - - WebSocket/HTTP 표면, node pairing, 그리고 더 무거운 네트워킹 -- 기대 사항: - - 파이프라인에서 활성화되면 CI에서 실행됨 - - 실제 키 불필요 - - unit 테스트보다 구성 요소가 더 많음(더 느릴 수 있음) + - 다중 인스턴스 Gateway 엔드투엔드 동작 + - WebSocket/HTTP 표면, Node 페어링, 더 무거운 네트워킹 +- 기대사항: + - CI에서 실행됨(파이프라인에서 활성화된 경우) + - 실제 키가 필요하지 않음 + - 단위 테스트보다 움직이는 부품이 더 많음(더 느릴 수 있음) ### E2E: OpenShell 백엔드 스모크 -- 명령어: `pnpm test:e2e:openshell` +- 명령: `pnpm test:e2e:openshell` - 파일: `test/openshell-sandbox.e2e.test.ts` - 범위: - - Docker를 통해 호스트에서 격리된 OpenShell Gateway를 시작 - - 임시 로컬 Dockerfile로부터 sandbox 생성 - - 실제 `sandbox ssh-config` + SSH exec를 통해 OpenClaw의 OpenShell 백엔드를 검증 - - sandbox fs bridge를 통해 원격 정규 파일시스템 동작을 검증 -- 기대 사항: - - 옵트인 전용이며 기본 `pnpm test:e2e` 실행에는 포함되지 않음 - - 로컬 `openshell` CLI와 동작하는 Docker daemon이 필요 - - 격리된 `HOME` / `XDG_CONFIG_HOME`을 사용한 뒤 테스트 Gateway와 sandbox를 제거 + - Docker를 통해 호스트에서 격리된 OpenShell Gateway를 시작합니다. + - 임시 로컬 Dockerfile에서 샌드박스를 생성합니다. + - 실제 `sandbox ssh-config` + SSH exec를 통해 OpenClaw의 OpenShell 백엔드를 실행합니다. + - 샌드박스 fs 브리지를 통해 원격 정규 파일시스템 동작을 검증합니다. +- 기대사항: + - 옵트인 전용이며 기본 `pnpm test:e2e` 실행의 일부가 아님 + - 로컬 `openshell` CLI와 동작하는 Docker 데몬이 필요함 + - 격리된 `HOME` / `XDG_CONFIG_HOME`을 사용한 뒤 테스트 Gateway와 샌드박스를 제거함 - 유용한 재정의: - - 더 넓은 e2e 스위트를 수동 실행할 때 이 테스트를 활성화하려면 `OPENCLAW_E2E_OPENSHELL=1` - - 기본이 아닌 CLI 바이너리 또는 래퍼 스크립트를 가리키려면 `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` + - 더 넓은 e2e 스위트를 수동으로 실행할 때 이 테스트를 활성화하려면 `OPENCLAW_E2E_OPENSHELL=1` + - 기본이 아닌 CLI 바이너리 또는 래퍼 스크립트를 지정하려면 `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` -### Live (실제 프로바이더 + 실제 모델) +### 라이브 (실제 제공자 + 실제 모델) -- 명령어: `pnpm test:live` +- 명령: `pnpm test:live` - 설정: `vitest.live.config.ts` - 파일: `src/**/*.live.test.ts` -- 기본값: `pnpm test:live`에 의해 **활성화됨** (`OPENCLAW_LIVE_TEST=1` 설정) +- 기본값: `pnpm test:live`로 **활성화됨** (`OPENCLAW_LIVE_TEST=1` 설정) - 범위: - - “이 프로바이더/모델이 _오늘_ 실제 자격 증명으로 실제로 동작하는가?” - - 프로바이더 포맷 변경, tool-calling 특이점, auth 이슈, rate limit 동작 포착 -- 기대 사항: - - 설계상 CI 안정적이지 않음(실제 네트워크, 실제 프로바이더 정책, quota, 장애) - - 비용이 들거나 rate limit를 사용함 - - “전부”보다는 범위를 좁힌 하위 집합 실행을 선호 -- live 실행은 누락된 API 키를 가져오기 위해 `~/.profile`을 로드합니다. -- 기본적으로 live 실행은 여전히 `HOME`을 격리하고 config/auth 자료를 임시 테스트 홈으로 복사하므로 unit fixture가 실제 `~/.openclaw`를 변경할 수 없습니다. -- live 테스트가 실제 홈 디렉터리를 사용하도록 의도적으로 원할 때만 `OPENCLAW_LIVE_USE_REAL_HOME=1`을 설정하세요. -- `pnpm test:live`는 이제 더 조용한 모드를 기본으로 사용합니다. `[live] ...` 진행 출력은 유지하지만 추가 `~/.profile` 알림과 gateway bootstrap 로그/Bonjour chatter는 숨깁니다. 전체 시작 로그를 다시 보려면 `OPENCLAW_LIVE_TEST_QUIET=0`을 설정하세요. -- API 키 로테이션(프로바이더별): 쉼표/세미콜론 형식의 `*_API_KEYS` 또는 `*_API_KEY_1`, `*_API_KEY_2`(예: `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`)를 설정하거나, live별 재정의로 `OPENCLAW_LIVE_*_KEY`를 사용하세요. 테스트는 rate limit 응답 시 재시도합니다. + - “이 제공자/모델이 오늘 실제 자격 증명으로 정말 작동하는가?” + - 제공자 형식 변경, 도구 호출 특이점, 인증 이슈, 속도 제한 동작을 포착 +- 기대사항: + - 설계상 CI에서 안정적이지 않음(실제 네트워크, 실제 제공자 정책, 할당량, 장애) + - 비용이 들거나 속도 제한을 사용함 + - “전부”보다 범위를 좁힌 하위 집합 실행을 선호 +- 라이브 실행은 누락된 API 키를 가져오기 위해 `~/.profile`을 불러옵니다. +- 기본적으로 라이브 실행은 여전히 `HOME`을 격리하고 설정/인증 자료를 임시 테스트 홈으로 복사하여 단위 테스트 픽스처가 실제 `~/.openclaw`를 변경하지 못하게 합니다. +- 라이브 테스트가 실제 홈 디렉터리를 사용하도록 의도적으로 원할 때만 `OPENCLAW_LIVE_USE_REAL_HOME=1`을 설정하세요. +- `pnpm test:live`는 이제 기본적으로 더 조용한 모드를 사용합니다. `[live] ...` 진행 출력은 유지하지만 추가 `~/.profile` 알림을 숨기고 Gateway 부트스트랩 로그/Bonjour 잡음을 음소거합니다. 전체 시작 로그를 다시 보려면 `OPENCLAW_LIVE_TEST_QUIET=0`을 설정하세요. +- API 키 순환(제공자별): 쉼표/세미콜론 형식의 `*_API_KEYS` 또는 `*_API_KEY_1`, `*_API_KEY_2`(예: `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`)를 설정하거나, 라이브 전용 재정의를 위해 `OPENCLAW_LIVE_*_KEY`를 사용하세요. 테스트는 속도 제한 응답이 오면 재시도합니다. - 진행/Heartbeat 출력: - - 이제 live 스위트는 긴 프로바이더 호출이 Vitest 콘솔 캡처가 조용하더라도 눈에 띄게 활성 상태임을 보여주기 위해 stderr에 진행 줄을 출력합니다. - - `vitest.live.config.ts`는 Vitest 콘솔 가로채기를 비활성화하므로 프로바이더/gateway 진행 줄이 live 실행 중 즉시 스트리밍됩니다. + - 라이브 스위트는 이제 진행 줄을 stderr로 출력하므로 Vitest 콘솔 캡처가 조용해도 긴 제공자 호출이 눈에 띄게 활성 상태로 보입니다. + - `vitest.live.config.ts`는 Vitest 콘솔 가로채기를 비활성화하여 제공자/Gateway 진행 줄이 라이브 실행 중 즉시 스트리밍되게 합니다. - 직접 모델 Heartbeat는 `OPENCLAW_LIVE_HEARTBEAT_MS`로 조정합니다. - - Gateway/probe Heartbeat는 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`로 조정합니다. + - Gateway/프로브 Heartbeat는 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`로 조정합니다. ## 어떤 스위트를 실행해야 하나요? -다음 결정 표를 사용하세요: +이 결정표를 사용하세요: -- 로직/테스트 수정: `pnpm test` 실행(많이 변경했다면 `pnpm test:coverage`도) -- Gateway 네트워킹 / WS 프로토콜 / pairing 수정: `pnpm test:e2e` 추가 -- “내 bot이 죽었다” / 프로바이더별 실패 / tool calling 디버깅: 범위를 좁힌 `pnpm test:live` 실행 +- 로직/테스트를 수정 중: `pnpm test` 실행(`많이` 변경했다면 `pnpm test:coverage`도) +- Gateway 네트워킹 / WS 프로토콜 / 페어링을 건드림: `pnpm test:e2e` 추가 +- “내 봇이 죽었다” / 제공자별 실패 / 도구 호출 디버깅: 범위를 좁힌 `pnpm test:live` 실행 -## Live: Android Node 기능 스윕 +## 라이브: Android Node 기능 스윕 - 테스트: `src/gateway/android-node.capabilities.live.test.ts` - 스크립트: `pnpm android:test:integration` -- 목표: 연결된 Android Node가 현재 광고하는 **모든 명령**을 호출하고 명령 계약 동작을 검증 +- 목표: 연결된 Android Node가 현재 광고하는 **모든 명령을 호출**하고 명령 계약 동작을 검증합니다. - 범위: - - 사전 준비/수동 설정 필요(이 스위트는 앱을 설치/실행/pairing하지 않음) + - 사전 조건이 갖춰진/수동 설정 기반(이 스위트는 앱을 설치/실행/페어링하지 않음) - 선택된 Android Node에 대한 명령별 Gateway `node.invoke` 검증 -- 필수 사전 설정: - - Android 앱이 이미 Gateway에 연결되고 pairing되어 있어야 함 - - 앱을 foreground 상태로 유지 - - 통과를 기대하는 기능에 필요한 권한/캡처 동의를 부여 +- 필요한 사전 설정: + - Android 앱이 이미 Gateway에 연결되고 페어링되어 있어야 함 + - 앱이 포그라운드에 유지되어야 함 + - 통과시키려는 기능에 필요한 권한/캡처 동의가 부여되어 있어야 함 - 선택적 대상 재정의: - `OPENCLAW_ANDROID_NODE_ID` 또는 `OPENCLAW_ANDROID_NODE_NAME` - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD` - 전체 Android 설정 세부 정보: [Android App](/ko/platforms/android) -## Live: 모델 스모크(profile 키) +## 라이브: 모델 스모크(프로필 키) -live 테스트는 실패를 분리할 수 있도록 두 계층으로 나뉩니다: +라이브 테스트는 실패를 분리할 수 있도록 두 레이어로 나뉩니다: -- “Direct model”은 주어진 키로 프로바이더/모델이 최소한 응답할 수 있는지 알려줍니다. -- “Gateway smoke”는 전체 gateway+agent 파이프라인이 해당 모델에 대해 동작하는지(세션, 히스토리, tools, sandbox 정책 등) 알려줍니다. +- “직접 모델”은 제공자/모델이 주어진 키로 최소한 응답할 수 있는지를 알려줍니다. +- “Gateway 스모크”는 해당 모델에 대해 전체 Gateway+에이전트 파이프라인(세션, 이력, 도구, 샌드박스 정책 등)이 작동하는지를 알려줍니다. -### 계층 1: 직접 모델 completion (Gateway 없음) +### 레이어 1: 직접 모델 완료(Gateway 없음) - 테스트: `src/agents/models.profiles.live.test.ts` - 목표: - - 발견된 모델 나열 + - 발견된 모델을 열거 - `getApiKeyForModel`을 사용해 자격 증명이 있는 모델 선택 - - 모델별로 작은 completion 실행(필요 시 대상 회귀 포함) + - 모델별 작은 완료를 실행(그리고 필요한 경우 대상 회귀 테스트도 실행) - 활성화 방법: - - `pnpm test:live`(또는 Vitest를 직접 호출한다면 `OPENCLAW_LIVE_TEST=1`) -- 이 스위트를 실제로 실행하려면 `OPENCLAW_LIVE_MODELS=modern`(또는 `all`, `modern`의 별칭)을 설정해야 합니다. 그렇지 않으면 `pnpm test:live`가 Gateway 스모크에 집중하도록 건너뜁니다. + - `pnpm test:live`(또는 Vitest를 직접 호출하는 경우 `OPENCLAW_LIVE_TEST=1`) +- 이 스위트를 실제로 실행하려면 `OPENCLAW_LIVE_MODELS=modern`(또는 `all`, `modern`의 별칭)을 설정해야 합니다. 그렇지 않으면 `pnpm test:live`가 Gateway 스모크에 집중되도록 건너뜁니다. - 모델 선택 방법: - - 현대 allowlist를 실행하려면 `OPENCLAW_LIVE_MODELS=modern`(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all`은 현대 allowlist의 별칭 - - 또는 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`(쉼표로 구분한 allowlist) - - modern/all 스윕은 기본적으로 선별된 고신호 상한을 사용합니다. 현대 전체 스윕을 완전히 수행하려면 `OPENCLAW_LIVE_MAX_MODELS=0`, 더 작은 상한을 원하면 양수를 설정하세요. -- 프로바이더 선택 방법: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`(쉼표로 구분한 allowlist) -- 키 출처: - - 기본값: profile 저장소와 env 폴백 - - **profile 저장소만** 강제하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - 현대식 허용 목록(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)을 실행하려면 `OPENCLAW_LIVE_MODELS=modern` + - `OPENCLAW_LIVE_MODELS=all`은 현대식 허용 목록의 별칭 + - 또는 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (쉼표 구분 허용 목록) + - modern/all 스윕은 기본적으로 선별된 고신호 상한을 사용합니다. 완전한 modern 스윕을 원하면 `OPENCLAW_LIVE_MAX_MODELS=0`을, 더 작은 상한을 원하면 양수를 설정하세요. +- 제공자 선택 방법: + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (쉼표 구분 허용 목록) +- 키의 출처: + - 기본값: 프로필 저장소와 환경 변수 폴백 + - **프로필 저장소만** 강제하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` - 이것이 존재하는 이유: - - “프로바이더 API가 깨졌거나 키가 잘못됨”과 “Gateway agent 파이프라인이 깨짐”을 분리 - - 작고 격리된 회귀를 포함(예: OpenAI Responses/Codex Responses reasoning replay + tool-call 흐름) + - “제공자 API가 깨졌거나 키가 잘못됨”과 “Gateway 에이전트 파이프라인이 깨짐”을 분리함 + - 작고 고립된 회귀 테스트를 담음(예: OpenAI Responses/Codex Responses 추론 재생 + 도구 호출 흐름) -### 계층 2: Gateway + dev 에이전트 스모크(`@openclaw`가 실제로 하는 일) +### 레이어 2: Gateway + 개발 에이전트 스모크(`@openclaw`가 실제로 하는 일) - 테스트: `src/gateway/gateway-models.profiles.live.test.ts` - 목표: - - 프로세스 내 Gateway를 시작 + - 프로세스 내부 Gateway를 시작 - `agent:dev:*` 세션을 생성/패치(실행별 모델 재정의) - 키가 있는 모델들을 순회하며 다음을 검증: - - “의미 있는” 응답(tools 없음) - - 실제 tool 호출이 동작함(read probe) - - 선택적 추가 tool probe(exec+read probe) - - OpenAI 회귀 경로(tool-call-only → follow-up)가 계속 동작함 -- Probe 세부 정보(실패를 빠르게 설명할 수 있도록): - - `read` probe: 테스트가 워크스페이스에 nonce 파일을 쓰고, 에이전트에게 해당 파일을 `read`하고 nonce를 다시 그대로 응답하도록 요청합니다. - - `exec+read` probe: 테스트가 에이전트에게 `exec`로 임시 파일에 nonce를 쓰게 한 뒤, 다시 `read`하게 요청합니다. - - image probe: 테스트가 생성한 PNG(cat + 무작위 코드)를 첨부하고, 모델이 `cat `를 반환할 것으로 기대합니다. - - 구현 참고: `src/gateway/gateway-models.profiles.live.test.ts` 및 `src/gateway/live-image-probe.ts`. + - “의미 있는” 응답(도구 없음) + - 실제 도구 호출이 작동함(`read` 프로브) + - 선택적 추가 도구 프로브(`exec+read` 프로브) + - OpenAI 회귀 경로(`tool-call-only` → 후속 응답)가 계속 작동함 +- 프로브 세부 정보(실패를 빠르게 설명할 수 있도록): + - `read` 프로브: 테스트가 워크스페이스에 nonce 파일을 작성하고 에이전트에게 이를 `read`한 뒤 nonce를 다시 출력하라고 요청합니다. + - `exec+read` 프로브: 테스트가 에이전트에게 `exec`로 nonce를 임시 파일에 쓴 뒤, 그것을 다시 `read`하라고 요청합니다. + - 이미지 프로브: 테스트가 생성된 PNG(고양이 + 무작위 코드)를 첨부하고 모델이 `cat `를 반환하길 기대합니다. + - 구현 참조: `src/gateway/gateway-models.profiles.live.test.ts` 및 `src/gateway/live-image-probe.ts`. - 활성화 방법: - - `pnpm test:live`(또는 Vitest를 직접 호출한다면 `OPENCLAW_LIVE_TEST=1`) + - `pnpm test:live`(또는 Vitest를 직접 호출하는 경우 `OPENCLAW_LIVE_TEST=1`) - 모델 선택 방법: - - 기본값: 현대 allowlist(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all`은 현대 allowlist의 별칭 - - 또는 범위를 좁히려면 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`(또는 쉼표 목록) 설정 - - modern/all Gateway 스윕은 기본적으로 선별된 고신호 상한을 사용합니다. 현대 전체 스윕을 완전히 수행하려면 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`, 더 작은 상한을 원하면 양수를 설정하세요. -- 프로바이더 선택 방법(“OpenRouter 전부” 방지): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`(쉼표 allowlist) -- 이 live 테스트에서는 tool + image probe가 항상 활성화됩니다: - - `read` probe + `exec+read` probe(tool 스트레스) - - 모델이 이미지 입력 지원을 광고하면 image probe 실행 + - 기본값: 현대식 허용 목록(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all`은 현대식 허용 목록의 별칭 + - 또는 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`(또는 쉼표 구분 목록)로 범위를 좁힐 수 있음 + - modern/all Gateway 스윕은 기본적으로 선별된 고신호 상한을 사용합니다. 완전한 modern 스윕을 원하면 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`을, 더 작은 상한을 원하면 양수를 설정하세요. +- 제공자 선택 방법(“OpenRouter 전부” 방지): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (쉼표 구분 허용 목록) +- 도구 + 이미지 프로브는 이 라이브 테스트에서 항상 활성화됩니다: + - `read` 프로브 + `exec+read` 프로브(도구 스트레스 테스트) + - 이미지 프로브는 모델이 이미지 입력 지원을 광고할 때 실행됨 - 흐름(상위 수준): - - 테스트가 “CAT” + 무작위 코드를 넣은 작은 PNG를 생성(`src/gateway/live-image-probe.ts`) - - `agent` `attachments: [{ mimeType: "image/png", content: "" }]`를 통해 전송 - - Gateway가 첨부 파일을 `images[]`로 파싱(`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - 임베디드 에이전트가 멀티모달 사용자 메시지를 모델로 전달 - - 검증: 응답에 `cat` + 코드가 포함됨(OCR 허용 범위: 사소한 실수는 허용) + - 테스트가 “CAT” + 무작위 코드가 있는 작은 PNG를 생성함(`src/gateway/live-image-probe.ts`) + - 이를 `agent` `attachments: [{ mimeType: "image/png", content: "" }]`를 통해 전송함 + - Gateway가 첨부 파일을 `images[]`로 파싱함(`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - 임베디드 에이전트가 멀티모달 사용자 메시지를 모델에 전달함 + - 검증: 응답에 `cat` + 코드가 포함됨(OCR 허용 오차: 사소한 실수는 허용) -팁: 현재 머신에서 무엇을 테스트할 수 있는지(그리고 정확한 `provider/model` ID)를 보려면 다음을 실행하세요: +팁: 현재 머신에서 무엇을 테스트할 수 있는지(그리고 정확한 `provider/model` ID)를 확인하려면 다음을 실행하세요: ```bash openclaw models list openclaw models list --json ``` -## Live: CLI 백엔드 스모크(Claude, Codex, Gemini 또는 기타 로컬 CLI) +## 라이브: CLI 백엔드 스모크 (Claude, Codex, Gemini 또는 기타 로컬 CLI) - 테스트: `src/gateway/gateway-cli-backend.live.test.ts` -- 목표: 기본 config를 건드리지 않고 로컬 CLI 백엔드를 사용해 Gateway + 에이전트 파이프라인을 검증합니다. -- 백엔드별 스모크 기본값은 해당 extension의 `cli-backend.ts` 정의에 있습니다. +- 목표: 기본 설정을 건드리지 않고 로컬 CLI 백엔드를 사용해 Gateway + 에이전트 파이프라인을 검증합니다. +- 백엔드별 스모크 기본값은 해당 백엔드를 소유한 확장의 `cli-backend.ts` 정의에 있습니다. - 활성화: - - `pnpm test:live`(또는 Vitest를 직접 호출한다면 `OPENCLAW_LIVE_TEST=1`) + - `pnpm test:live`(또는 Vitest를 직접 호출하는 경우 `OPENCLAW_LIVE_TEST=1`) - `OPENCLAW_LIVE_CLI_BACKEND=1` - 기본값: - - 기본 프로바이더/모델: `claude-cli/claude-sonnet-4-6` - - command/args/image 동작은 해당 CLI 백엔드 plugin 메타데이터에서 가져옵니다. + - 기본 제공자/모델: `claude-cli/claude-sonnet-4-6` + - 명령/인수/이미지 동작은 해당 CLI 백엔드 Plugin 메타데이터에서 가져옵니다. - 재정의(선택 사항): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - 실제 이미지 첨부를 보내려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`(경로는 프롬프트에 주입됨) - - 프롬프트 주입 대신 CLI 인수로 이미지 파일 경로를 전달하려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` - - `IMAGE_ARG`가 설정되었을 때 이미지 인수 전달 방식을 제어하려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`(또는 `"list"`) - - 두 번째 턴을 보내고 resume 흐름을 검증하려면 `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` - - 기본 Claude Sonnet -> Opus 동일 세션 연속성 probe를 비활성화하려면 `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`(선택된 모델이 switch 대상을 지원할 때 강제로 켜려면 `1`) - + - 실제 이미지 첨부 파일을 보내려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` (경로는 프롬프트에 주입됨) + - 프롬프트 주입 대신 이미지 파일 경로를 CLI 인수로 전달하려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` + - `IMAGE_ARG`가 설정되었을 때 이미지 인수를 어떻게 전달할지 제어하려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`(또는 `"list"`) + - 두 번째 턴을 보내고 재개 흐름을 검증하려면 `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` + - 기본 Claude Sonnet -> Opus 동일 세션 연속성 프로브를 비활성화하려면 `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`(선택한 모델이 전환 대상을 지원할 때 강제로 활성화하려면 `1`) + 예시: ```bash @@ -487,7 +485,7 @@ Docker 레시피: pnpm test:docker:live-cli-backend ``` -단일 프로바이더 Docker 레시피: +단일 제공자 Docker 레시피: ```bash pnpm test:docker:live-cli-backend:claude @@ -498,28 +496,28 @@ pnpm test:docker:live-cli-backend:gemini 참고: -- Docker 러너는 `scripts/test-live-cli-backend-docker.sh`에 있습니다. -- 저장소 Docker 이미지 내부에서 비루트 `node` 사용자로 live CLI 백엔드 스모크를 실행합니다. -- 해당 extension에서 CLI 스모크 메타데이터를 해석한 뒤, 일치하는 Linux CLI 패키지(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)를 캐시 가능한 쓰기 가능 prefix `OPENCLAW_DOCKER_CLI_TOOLS_DIR`(기본값: `~/.cache/openclaw/docker-cli-tools`)에 설치합니다. -- `pnpm test:docker:live-cli-backend:claude-subscription`은 `~/.claude/.credentials.json`의 `claudeAiOauth.subscriptionType` 또는 `claude setup-token`의 `CLAUDE_CODE_OAUTH_TOKEN`을 통한 portable Claude Code subscription OAuth가 필요합니다. 먼저 Docker에서 직접 `claude -p`를 증명한 뒤, Anthropic API 키 env var를 유지하지 않은 채 두 번의 Gateway CLI 백엔드 턴을 실행합니다. 이 subscription 레인은 Claude가 현재 서드파티 앱 사용을 일반 subscription 플랜 한도 대신 추가 사용량 과금으로 라우팅하기 때문에 기본적으로 Claude MCP/tool 및 image probe를 비활성화합니다. -- live CLI 백엔드 스모크는 이제 Claude, Codex, Gemini에 대해 동일한 end-to-end 흐름을 검증합니다: 텍스트 턴, 이미지 분류 턴, 그리고 gateway CLI를 통해 검증되는 MCP `cron` tool 호출. +- Docker 실행기는 `scripts/test-live-cli-backend-docker.sh`에 있습니다. +- 저장소 Docker 이미지 내부에서 비루트 `node` 사용자로 라이브 CLI 백엔드 스모크를 실행합니다. +- 해당 백엔드를 소유한 확장에서 CLI 스모크 메타데이터를 확인한 뒤, 일치하는 Linux CLI 패키지(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)를 캐시 가능한 쓰기 가능한 접두사 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`(기본값: `~/.cache/openclaw/docker-cli-tools`)에 설치합니다. +- `pnpm test:docker:live-cli-backend:claude-subscription`은 `~/.claude/.credentials.json`의 `claudeAiOauth.subscriptionType` 또는 `claude setup-token`에서 나온 `CLAUDE_CODE_OAUTH_TOKEN`을 통한 이식 가능한 Claude Code 구독 OAuth가 필요합니다. 먼저 Docker에서 직접 `claude -p`를 증명한 뒤, Anthropic API 키 환경 변수를 유지하지 않고 두 번의 Gateway CLI 백엔드 턴을 실행합니다. 이 구독 레인은 현재 Claude가 일반 구독 플랜 한도 대신 추가 사용량 과금을 통해 서드파티 앱 사용을 라우팅하므로 기본적으로 Claude MCP/도구 및 이미지 프로브를 비활성화합니다. +- 라이브 CLI 백엔드 스모크는 이제 Claude, Codex, Gemini에 대해 동일한 엔드투엔드 흐름을 실행합니다: 텍스트 턴, 이미지 분류 턴, 그다음 Gateway CLI를 통해 검증되는 MCP `cron` 도구 호출. - Claude의 기본 스모크는 또한 세션을 Sonnet에서 Opus로 패치하고 재개된 세션이 이전 메모를 여전히 기억하는지 검증합니다. -## Live: ACP 바인드 스모크(`/acp spawn ... --bind here`) +## 라이브: ACP 바인드 스모크 (`/acp spawn ... --bind here`) - 테스트: `src/gateway/gateway-acp-bind.live.test.ts` -- 목표: live ACP 에이전트로 실제 ACP 대화 바인드 흐름을 검증합니다: +- 목표: 라이브 ACP 에이전트로 실제 ACP 대화 바인드 흐름을 검증합니다: - `/acp spawn --bind here` 전송 - - synthetic message-channel 대화를 제자리에서 바인드 + - 합성 메시지 채널 대화를 제자리에서 바인드 - 동일한 대화에서 일반 후속 메시지 전송 - - 후속 메시지가 바인드된 ACP 세션 트랜스크립트에 도달하는지 검증 + - 후속 메시지가 바인드된 ACP 세션 전사본에 도착하는지 검증 - 활성화: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - 기본값: - Docker의 ACP 에이전트: `claude,codex,gemini` - 직접 `pnpm test:live ...`용 ACP 에이전트: `claude` - - synthetic 채널: Slack DM 스타일 대화 컨텍스트 + - 합성 채널: Slack DM 스타일 대화 컨텍스트 - ACP 백엔드: `acpx` - 재정의: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -528,8 +526,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - 참고: - - 이 레인은 admin 전용 synthetic originating-route 필드를 포함한 Gateway `chat.send` 표면을 사용하므로, 외부 전달을 가장하지 않고도 테스트가 message-channel 컨텍스트를 연결할 수 있습니다. - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`가 설정되지 않은 경우, 테스트는 선택된 ACP 하니스 에이전트에 대해 임베디드 `acpx` plugin의 내장 에이전트 레지스트리를 사용합니다. + - 이 레인은 Gateway `chat.send` 표면을 사용하며, 테스트가 외부 전달을 가장하지 않고 메시지 채널 컨텍스트를 붙일 수 있도록 관리자 전용 합성 originating-route 필드를 사용합니다. + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`가 설정되지 않으면 테스트는 선택된 ACP 하네스 에이전트에 대해 내장 `acpx` Plugin의 내장 에이전트 레지스트리를 사용합니다. 예시: @@ -555,27 +553,32 @@ pnpm test:docker:live-acp-bind:gemini Docker 참고: -- Docker 러너는 `scripts/test-live-acp-bind-docker.sh`에 있습니다. -- 기본적으로 지원되는 모든 live CLI 에이전트(`claude`, `codex`, `gemini`)에 대해 순서대로 ACP 바인드 스모크를 실행합니다. +- Docker 실행기는 `scripts/test-live-acp-bind-docker.sh`에 있습니다. +- 기본적으로 지원되는 모든 라이브 CLI 에이전트(`claude`, `codex`, `gemini`)에 대해 ACP 바인드 스모크를 순차 실행합니다. - 매트릭스 범위를 좁히려면 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, 또는 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`를 사용하세요. -- `~/.profile`을 로드하고, 일치하는 CLI 인증 자료를 컨테이너에 스테이징하며, `acpx`를 쓰기 가능한 npm prefix에 설치한 다음, 요청된 live CLI(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)가 없으면 설치합니다. -- Docker 내부에서 러너는 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`를 설정하여, 로드된 profile의 프로바이더 env var를 acpx가 자식 하니스 CLI에서 계속 사용할 수 있게 합니다. +- `~/.profile`을 불러오고, 일치하는 CLI 인증 자료를 컨테이너에 준비하고, 쓰기 가능한 npm 접두사에 `acpx`를 설치한 뒤, 없으면 요청된 라이브 CLI(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)를 설치합니다. +- Docker 내부에서 실행기는 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`를 설정하여, 소스된 프로필의 제공자 환경 변수를 자식 하네스 CLI에서 계속 사용할 수 있도록 합니다. -## Live: Codex app-server 하니스 스모크 +## 라이브: Codex app-server 하네스 스모크 -- 목표: 일반 Gateway `agent` 메서드를 통해 plugin 소유 Codex 하니스를 검증합니다: - - 번들된 `codex` plugin 로드 +- 목표: 일반 Gateway + `agent` 메서드를 통해 Plugin이 소유한 Codex 하네스를 검증합니다: + - 번들된 `codex` Plugin 로드 - `OPENCLAW_AGENT_RUNTIME=codex` 선택 - - `codex/gpt-5.4`에 첫 번째 Gateway 에이전트 턴 전송 - - 동일한 OpenClaw 세션에 두 번째 턴을 보내 app-server 스레드가 재개될 수 있는지 검증 - - 동일한 Gateway 명령 경로를 통해 `/codex status`와 `/codex models` 실행 + - 첫 번째 Gateway 에이전트 턴을 `codex/gpt-5.4`에 전송 + - 동일한 OpenClaw 세션에 두 번째 턴을 전송하고 app-server + 스레드가 재개될 수 있는지 검증 + - `/codex status`와 `/codex models`를 동일한 Gateway 명령 + 경로를 통해 실행 - 테스트: `src/gateway/gateway-codex-harness.live.test.ts` - 활성화: `OPENCLAW_LIVE_CODEX_HARNESS=1` - 기본 모델: `codex/gpt-5.4` -- 선택적 image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- 선택적 MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- 이 스모크는 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 설정하므로, 깨진 Codex 하니스가 PI로 조용히 폴백되어 통과할 수 없습니다. -- 인증: 셸/profile의 `OPENAI_API_KEY`와 선택적으로 복사된 `~/.codex/auth.json`, `~/.codex/config.toml` +- 선택적 이미지 프로브: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 선택적 MCP/도구 프로브: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- 이 스모크는 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 설정하므로, + 깨진 Codex 하네스가 PI로 조용히 폴백하여 통과할 수 없습니다. +- 인증: 셸/프로필의 `OPENAI_API_KEY`, 그리고 선택적으로 복사된 + `~/.codex/auth.json` 및 `~/.codex/config.toml` 로컬 레시피: @@ -597,22 +600,28 @@ pnpm test:docker:live-codex-harness Docker 참고: -- Docker 러너는 `scripts/test-live-codex-harness-docker.sh`에 있습니다. -- 마운트된 `~/.profile`을 로드하고, `OPENAI_API_KEY`를 전달하며, 존재하는 경우 Codex CLI 인증 파일을 복사하고, `@openai/codex`를 쓰기 가능한 마운트된 npm prefix에 설치한 다음, 소스 트리를 스테이징하고 Codex 하니스 live 테스트만 실행합니다. -- Docker는 기본적으로 image 및 MCP/tool probe를 활성화합니다. 더 좁은 디버그 실행이 필요하면 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 또는 `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`을 설정하세요. -- Docker는 또한 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 내보내며, 이는 live 테스트 설정과 일치하므로 `openai-codex/*` 또는 PI 폴백이 Codex 하니스 회귀를 숨길 수 없습니다. +- Docker 실행기는 `scripts/test-live-codex-harness-docker.sh`에 있습니다. +- 마운트된 `~/.profile`을 불러오고 `OPENAI_API_KEY`를 전달하며, 존재할 경우 Codex CLI + 인증 파일을 복사하고, 쓰기 가능한 마운트된 npm + 접두사에 `@openai/codex`를 설치하고, 소스 트리를 준비한 뒤 Codex 하네스 라이브 테스트만 실행합니다. +- Docker는 기본적으로 이미지 및 MCP/도구 프로브를 활성화합니다. 더 좁은 디버그 실행이 필요할 때는 + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 또는 + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`을 설정하세요. +- Docker는 또한 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 export하여, 라이브 + 테스트 설정과 일치하게 `openai-codex/*` 또는 PI 폴백이 Codex 하네스 + 회귀를 숨기지 못하게 합니다. -### 권장 live 레시피 +### 권장 라이브 레시피 -범위를 좁힌 명시적 allowlist가 가장 빠르고 가장 덜 불안정합니다: +범위가 좁고 명시적인 허용 목록이 가장 빠르고 가장 덜 불안정합니다: -- 단일 모델, 직접(Gateway 없음): +- 단일 모델, 직접 실행(Gateway 없음): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - 단일 모델, Gateway 스모크: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- 여러 프로바이더에 걸친 tool calling: +- 여러 제공자에 걸친 도구 호출: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Google 중심(Gemini API 키 + Antigravity): @@ -623,190 +632,190 @@ Docker 참고: - `google/...`는 Gemini API(API 키)를 사용합니다. - `google-antigravity/...`는 Antigravity OAuth 브리지(Cloud Code Assist 스타일 에이전트 엔드포인트)를 사용합니다. -- `google-gemini-cli/...`는 현재 머신의 로컬 Gemini CLI를 사용합니다(별도 인증 + 도구 동작 특이점). +- `google-gemini-cli/...`는 사용자 머신의 로컬 Gemini CLI를 사용합니다(별도 인증 + 도구 관련 특이점). - Gemini API와 Gemini CLI: - - API: OpenClaw가 Google의 호스팅된 Gemini API를 HTTP로 호출합니다(API 키 / profile 인증). 대부분의 사용자가 “Gemini”라고 말할 때 의미하는 것은 이것입니다. - - CLI: OpenClaw가 로컬 `gemini` 바이너리를 셸 실행합니다. 자체 인증이 있으며 동작이 다를 수 있습니다(스트리밍/tool 지원/버전 차이). + - API: OpenClaw가 HTTP를 통해 Google의 호스팅된 Gemini API를 호출합니다(API 키 / 프로필 인증). 대부분의 사용자가 “Gemini”라고 할 때 의미하는 것이 이것입니다. + - CLI: OpenClaw가 로컬 `gemini` 바이너리를 셸로 실행합니다. 자체 인증을 가지며 동작이 다를 수 있습니다(스트리밍/도구 지원/버전 차이). -## Live: 모델 매트릭스(무엇을 커버하는가) +## 라이브: 모델 매트릭스(무엇을 커버하는가) -고정된 “CI 모델 목록”은 없습니다(live는 옵트인). 하지만 키가 있는 개발 머신에서 정기적으로 커버하기를 **권장하는** 모델은 다음과 같습니다. +고정된 “CI 모델 목록”은 없습니다(라이브는 옵트인). 하지만 키가 있는 개발 머신에서 정기적으로 커버하기를 **권장하는** 모델은 다음과 같습니다. -### 현대 스모크 세트(tool calling + 이미지) +### 현대식 스모크 세트(도구 호출 + 이미지) -이것이 우리가 계속 동작하길 기대하는 “일반 모델” 실행입니다: +이것이 우리가 계속 작동하길 기대하는 “일반 모델” 실행입니다: -- OpenAI(non-Codex): `openai/gpt-5.4` (선택 사항: `openai/gpt-5.4-mini`) +- OpenAI (비-Codex): `openai/gpt-5.4` (선택 사항: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (또는 `anthropic/claude-sonnet-4-6`) -- Google(Gemini API): `google/gemini-3.1-pro-preview` 및 `google/gemini-3-flash-preview`(이전 Gemini 2.x 모델은 피하세요) -- Google(Antigravity): `google-antigravity/claude-opus-4-6-thinking` 및 `google-antigravity/gemini-3-flash` -- Z.AI(GLM): `zai/glm-4.7` +- Google (Gemini API): `google/gemini-3.1-pro-preview` 및 `google/gemini-3-flash-preview` (이전 Gemini 2.x 모델은 피하세요) +- Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` 및 `google-antigravity/gemini-3-flash` +- Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -tools + image로 Gateway 스모크 실행: +도구 + 이미지가 포함된 Gateway 스모크 실행: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### 기준선: tool calling(Read + 선택적 Exec) +### 기준선: 도구 호출(Read + 선택적 Exec) -프로바이더 계열별로 최소 하나는 선택하세요: +제공자 계열별로 최소 하나는 선택하세요: - OpenAI: `openai/gpt-5.4` (또는 `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (또는 `anthropic/claude-sonnet-4-6`) - Google: `google/gemini-3-flash-preview` (또는 `google/gemini-3.1-pro-preview`) -- Z.AI(GLM): `zai/glm-4.7` +- Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` 선택적 추가 커버리지(있으면 좋음): - xAI: `xai/grok-4` (또는 최신 사용 가능 버전) - Mistral: `mistral/`… (활성화된 “tools” 지원 모델 하나 선택) -- Cerebras: `cerebras/`… (접근 권한이 있다면) -- LM Studio: `lmstudio/`… (로컬; tool calling은 API 모드에 따라 다름) +- Cerebras: `cerebras/`… (접근 권한이 있는 경우) +- LM Studio: `lmstudio/`… (로컬; 도구 호출은 API 모드에 따라 달라짐) ### 비전: 이미지 전송(첨부 파일 → 멀티모달 메시지) -image probe를 검증하려면 `OPENCLAW_LIVE_GATEWAY_MODELS`에 최소 하나 이상의 이미지 지원 모델(Claude/Gemini/OpenAI 비전 지원 변형 등)을 포함하세요. +이미지 프로브를 실행하려면 이미지 입력이 가능한 모델(Claude/Gemini/OpenAI의 비전 지원 변형 등)을 최소 하나 `OPENCLAW_LIVE_GATEWAY_MODELS`에 포함하세요. -### 집계자 / 대체 Gateway +### 애그리게이터 / 대체 Gateway 키가 활성화되어 있다면 다음을 통한 테스트도 지원합니다: -- OpenRouter: `openrouter/...` (수백 개의 모델; tool+image 지원 후보를 찾으려면 `openclaw models scan` 사용) -- OpenCode: Zen용 `opencode/...`, Go용 `opencode-go/...` (인증: `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (수백 개 모델; 도구+이미지 지원 후보를 찾으려면 `openclaw models scan` 사용) +- OpenCode: Zen용 `opencode/...`, Go용 `opencode-go/...` (`OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`로 인증) -live 매트릭스에 포함할 수 있는 더 많은 프로바이더(자격 증명/config가 있다면): +라이브 매트릭스에 포함할 수 있는 추가 제공자(자격 증명/설정이 있는 경우): - 내장: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- `models.providers`를 통해(custom 엔드포인트): `minimax`(cloud/API), 그리고 OpenAI/Anthropic 호환 프록시(LM Studio, vLLM, LiteLLM 등) +- `models.providers`를 통해(커스텀 엔드포인트): `minimax` (클라우드/API), 그리고 모든 OpenAI/Anthropic 호환 프록시(LM Studio, vLLM, LiteLLM 등) -팁: 문서에 “모든 모델”을 하드코딩하려 하지 마세요. 권위 있는 목록은 현재 머신에서 `discoverModels(...)`가 반환하는 것과 사용 가능한 키의 조합입니다. +팁: 문서에 “모든 모델”을 하드코딩하려 하지 마세요. 권위 있는 목록은 `discoverModels(...)`가 현재 머신에서 반환하는 것과 사용 가능한 키의 조합입니다. -## 자격 증명(절대 커밋하지 마세요) +## 자격 증명(절대 커밋 금지) -live 테스트는 CLI와 동일한 방식으로 자격 증명을 찾습니다. 실질적인 의미는 다음과 같습니다: +라이브 테스트는 CLI와 같은 방식으로 자격 증명을 찾습니다. 실질적인 의미는 다음과 같습니다: -- CLI가 동작하면 live 테스트도 동일한 키를 찾아야 합니다. -- live 테스트가 “자격 증명 없음”이라고 하면, `openclaw models list` / 모델 선택을 디버깅하는 것과 같은 방식으로 디버깅하세요. +- CLI가 작동하면 라이브 테스트도 같은 키를 찾아야 합니다. +- 라이브 테스트가 “자격 증명 없음”이라고 말한다면 `openclaw models list` / 모델 선택을 디버깅할 때와 같은 방식으로 디버깅하세요. -- 에이전트별 auth profile: `~/.openclaw/agents//agent/auth-profiles.json`(live 테스트에서 “profile 키”가 의미하는 것이 이것입니다) -- Config: `~/.openclaw/openclaw.json`(또는 `OPENCLAW_CONFIG_PATH`) -- 레거시 상태 디렉터리: `~/.openclaw/credentials/`(존재할 경우 스테이징된 live 홈으로 복사되지만, 메인 profile 키 저장소는 아님) -- 로컬 live 실행은 기본적으로 활성 config, 에이전트별 `auth-profiles.json` 파일, 레거시 `credentials/`, 그리고 지원되는 외부 CLI auth 디렉터리를 임시 테스트 홈으로 복사합니다. 스테이징된 live 홈은 `workspace/`와 `sandboxes/`를 건너뛰며, `agents.*.workspace` / `agentDir` 경로 재정의는 제거되어 probe가 실제 호스트 워크스페이스에서 벗어나게 합니다. +- 에이전트별 인증 프로필: `~/.openclaw/agents//agent/auth-profiles.json` (라이브 테스트에서 “프로필 키”라고 하는 것은 이것입니다) +- 설정: `~/.openclaw/openclaw.json` (또는 `OPENCLAW_CONFIG_PATH`) +- 레거시 상태 디렉터리: `~/.openclaw/credentials/` (존재할 경우 준비된 라이브 홈으로 복사되지만, 주 프로필 키 저장소는 아님) +- 로컬 라이브 실행은 기본적으로 활성 설정, 에이전트별 `auth-profiles.json` 파일, 레거시 `credentials/`, 지원되는 외부 CLI 인증 디렉터리를 임시 테스트 홈으로 복사합니다. 준비된 라이브 홈은 `workspace/`와 `sandboxes/`를 건너뛰고, `agents.*.workspace` / `agentDir` 경로 재정의를 제거하여 프로브가 실제 호스트 워크스페이스를 건드리지 않도록 합니다. -env 키(예: `~/.profile`에 export된 값)에 의존하려면 `source ~/.profile` 후 로컬 테스트를 실행하거나, 아래 Docker 러너를 사용하세요(컨테이너에 `~/.profile`을 마운트할 수 있습니다). +환경 변수 키(예: `~/.profile`에 export된 값)를 사용하고 싶다면, `source ~/.profile` 후에 로컬 테스트를 실행하거나 아래의 Docker 실행기를 사용하세요(컨테이너 안으로 `~/.profile`을 마운트할 수 있습니다). -## Deepgram live(오디오 전사) +## Deepgram 라이브 (오디오 전사) - 테스트: `src/media-understanding/providers/deepgram/audio.live.test.ts` - 활성화: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus 코딩 플랜 live +## BytePlus 코딩 플랜 라이브 - 테스트: `src/agents/byteplus.live.test.ts` - 활성화: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - 선택적 모델 재정의: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI 워크플로 미디어 live +## ComfyUI 워크플로 미디어 라이브 - 테스트: `extensions/comfy/comfy.live.test.ts` - 활성화: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - 범위: - - 번들된 comfy 이미지, 비디오, `music_generate` 경로를 검증 - - `models.providers.comfy.`가 구성되지 않으면 각 기능을 건너뜀 - - comfy 워크플로 제출, 폴링, 다운로드 또는 plugin 등록을 변경한 뒤 유용함 + - 번들된 comfy 이미지, 비디오, `music_generate` 경로를 실행 + - `models.providers.comfy.`가 설정되지 않은 기능은 각각 건너뜀 + - comfy 워크플로 제출, 폴링, 다운로드 또는 Plugin 등록을 변경한 후 유용함 -## 이미지 생성 live +## 이미지 생성 라이브 - 테스트: `src/image-generation/runtime.live.test.ts` -- 명령어: `pnpm test:live src/image-generation/runtime.live.test.ts` -- 하니스: `pnpm test:live:media image` +- 명령: `pnpm test:live src/image-generation/runtime.live.test.ts` +- 하네스: `pnpm test:live:media image` - 범위: - - 등록된 모든 이미지 생성 프로바이더 plugin을 나열 - - probe 전에 로그인 셸(`~/.profile`)에서 누락된 프로바이더 env var를 로드 - - 기본적으로 저장된 auth profile보다 live/env API 키를 우선 사용하므로, `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 - - 사용 가능한 auth/profile/model이 없는 프로바이더는 건너뜀 - - 공유 runtime 기능을 통해 기본 이미지 생성 변형을 실행: + - 등록된 모든 이미지 생성 제공자 Plugin을 열거 + - 프로브 전에 로그인 셸(`~/.profile`)에서 누락된 제공자 환경 변수를 로드 + - 기본적으로 저장된 인증 프로필보다 라이브/환경 변수 API 키를 우선 사용하므로 `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 + - 사용 가능한 인증/프로필/모델이 없는 제공자는 건너뜀 + - 공유 런타임 기능을 통해 기본 이미지 생성 변형을 실행: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- 현재 커버되는 번들 프로바이더: +- 현재 커버되는 번들 제공자: - `openai` - `google` - 선택적 범위 축소: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- 선택적 auth 동작: - - profile 저장소 auth를 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 선택적 인증 동작: + - 프로필 저장소 인증만 강제하고 환경 변수 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## 음악 생성 live +## 음악 생성 라이브 - 테스트: `extensions/music-generation-providers.live.test.ts` - 활성화: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- 하니스: `pnpm test:live:media music` +- 하네스: `pnpm test:live:media music` - 범위: - - 공유 번들 음악 생성 프로바이더 경로를 검증 + - 공유 번들 음악 생성 제공자 경로를 실행 - 현재 Google과 MiniMax를 커버 - - probe 전에 로그인 셸(`~/.profile`)에서 프로바이더 env var를 로드 - - 기본적으로 저장된 auth profile보다 live/env API 키를 우선 사용하므로, `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 - - 사용 가능한 auth/profile/model이 없는 프로바이더는 건너뜀 - - 사용 가능한 경우 선언된 두 runtime 모드를 모두 실행: - - 프롬프트만 입력으로 사용하는 `generate` - - 프로바이더가 `capabilities.edit.enabled`를 선언할 때의 `edit` + - 프로브 전에 로그인 셸(`~/.profile`)에서 제공자 환경 변수를 로드 + - 기본적으로 저장된 인증 프로필보다 라이브/환경 변수 API 키를 우선 사용하므로 `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 + - 사용 가능한 인증/프로필/모델이 없는 제공자는 건너뜀 + - 사용 가능한 경우 선언된 두 런타임 모드를 모두 실행: + - 프롬프트 전용 입력의 `generate` + - 제공자가 `capabilities.edit.enabled`를 선언할 때의 `edit` - 현재 공유 레인 커버리지: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: 별도 Comfy live 파일, 이 공유 스윕에는 포함되지 않음 + - `comfy`: 별도의 Comfy 라이브 파일이며, 이 공유 스윕에 포함되지 않음 - 선택적 범위 축소: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- 선택적 auth 동작: - - profile 저장소 auth를 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 선택적 인증 동작: + - 프로필 저장소 인증만 강제하고 환경 변수 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## 비디오 생성 live +## 비디오 생성 라이브 - 테스트: `extensions/video-generation-providers.live.test.ts` - 활성화: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- 하니스: `pnpm test:live:media video` +- 하네스: `pnpm test:live:media video` - 범위: - - 공유 번들 비디오 생성 프로바이더 경로를 검증 - - 기본적으로 릴리스 안전 스모크 경로를 사용: 비-FAL 프로바이더, 프로바이더당 하나의 text-to-video 요청, 1초 lobster 프롬프트, 그리고 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`의 프로바이더당 작업 상한(기본 `180000`) - - FAL은 프로바이더 측 큐 지연이 릴리스 시간을 지배할 수 있으므로 기본적으로 건너뜁니다. 명시적으로 실행하려면 `--video-providers fal` 또는 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`을 전달하세요. - - probe 전에 로그인 셸(`~/.profile`)에서 프로바이더 env var를 로드 - - 기본적으로 저장된 auth profile보다 live/env API 키를 우선 사용하므로, `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 - - 사용 가능한 auth/profile/model이 없는 프로바이더는 건너뜀 + - 공유 번들 비디오 생성 제공자 경로를 실행 + - 릴리스 안전 스모크 경로를 기본값으로 사용: FAL이 아닌 제공자, 제공자별 텍스트-비디오 요청 하나, 1초짜리 lobster 프롬프트, 그리고 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`에서 가져오는 제공자별 작업 상한(기본값 `180000`) + - 제공자 측 큐 지연이 릴리스 시간을 지배할 수 있으므로 기본적으로 FAL은 건너뜁니다. 명시적으로 실행하려면 `--video-providers fal` 또는 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`을 전달하세요. + - 프로브 전에 로그인 셸(`~/.profile`)에서 제공자 환경 변수를 로드 + - 기본적으로 저장된 인증 프로필보다 라이브/환경 변수 API 키를 우선 사용하므로 `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 + - 사용 가능한 인증/프로필/모델이 없는 제공자는 건너뜀 - 기본적으로 `generate`만 실행 - - 사용 가능한 경우 선언된 transform 모드도 실행하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 설정: - - 프로바이더가 `capabilities.imageToVideo.enabled`를 선언하고 선택된 프로바이더/모델이 공유 스윕에서 버퍼 기반 로컬 이미지 입력을 허용할 때 `imageToVideo` - - 프로바이더가 `capabilities.videoToVideo.enabled`를 선언하고 선택된 프로바이더/모델이 공유 스윕에서 버퍼 기반 로컬 비디오 입력을 허용할 때 `videoToVideo` - - 공유 스윕에서 현재 선언되었지만 건너뛰는 `imageToVideo` 프로바이더: - - 번들된 `veo3`는 텍스트 전용이고 번들된 `kling`은 원격 이미지 URL이 필요하므로 `vydra` - - 프로바이더별 Vydra 커버리지: + - 사용 가능한 경우 선언된 변환 모드도 실행하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`을 설정: + - 제공자가 `capabilities.imageToVideo.enabled`를 선언하고 선택된 제공자/모델이 공유 스윕에서 버퍼 기반 로컬 이미지 입력을 수용할 때의 `imageToVideo` + - 제공자가 `capabilities.videoToVideo.enabled`를 선언하고 선택된 제공자/모델이 공유 스윕에서 버퍼 기반 로컬 비디오 입력을 수용할 때의 `videoToVideo` + - 현재 공유 스윕에서 선언되었지만 건너뛰는 `imageToVideo` 제공자: + - `vydra`: 번들된 `veo3`는 텍스트 전용이고 번들된 `kling`은 원격 이미지 URL이 필요하기 때문 + - 제공자별 Vydra 커버리지: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - 이 파일은 기본적으로 원격 이미지 URL fixture를 사용하는 `kling` 레인과 `veo3` text-to-video를 실행합니다 - - 현재 `videoToVideo` live 커버리지: - - 선택된 모델이 `runway/gen4_aleph`일 때만 `runway` - - 공유 스윕에서 현재 선언되었지만 건너뛰는 `videoToVideo` 프로바이더: - - 현재 이 경로들이 원격 `http(s)` / MP4 참조 URL을 요구하므로 `alibaba`, `qwen`, `xai` - - 현재 공유 Gemini/Veo 레인이 버퍼 기반 로컬 입력을 사용하며 이 경로가 공유 스윕에서 허용되지 않으므로 `google` - - 현재 공유 레인에는 조직별 비디오 인페인트/리믹스 접근 보장이 없으므로 `openai` + - 이 파일은 기본적으로 `veo3` 텍스트-비디오와 원격 이미지 URL 픽스처를 사용하는 `kling` 레인을 실행함 + - 현재 `videoToVideo` 라이브 커버리지: + - 선택된 모델이 `runway/gen4_aleph`일 때의 `runway`만 + - 현재 공유 스윕에서 선언되었지만 건너뛰는 `videoToVideo` 제공자: + - `alibaba`, `qwen`, `xai`: 이 경로들은 현재 원격 `http(s)` / MP4 참조 URL이 필요하기 때문 + - `google`: 현재 공유 Gemini/Veo 레인이 로컬 버퍼 기반 입력을 사용하고, 그 경로는 공유 스윕에서 수용되지 않기 때문 + - `openai`: 현재 공유 레인에는 조직별 비디오 인페인트/리믹스 접근 보장이 없기 때문 - 선택적 범위 축소: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - 기본 스윕에서 FAL을 포함한 모든 프로바이더를 포함하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` - - 공격적인 스모크 실행을 위해 프로바이더당 작업 상한을 줄이려면 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` -- 선택적 auth 동작: - - profile 저장소 auth를 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` + - 기본 스윕의 모든 제공자(FAL 포함)를 포함하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` + - 공격적인 스모크 실행을 위해 제공자별 작업 상한을 줄이려면 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` +- 선택적 인증 동작: + - 프로필 저장소 인증만 강제하고 환경 변수 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` -## 미디어 live 하니스 +## 미디어 라이브 하네스 -- 명령어: `pnpm test:live:media` +- 명령: `pnpm test:live:media` - 목적: - - 공유 이미지, 음악, 비디오 live 스위트를 하나의 저장소 기본 엔트리포인트로 실행 - - `~/.profile`에서 누락된 프로바이더 env var를 자동 로드 - - 기본적으로 현재 사용 가능한 auth가 있는 프로바이더로 각 스위트 범위를 자동 축소 + - 공유 이미지, 음악, 비디오 라이브 스위트를 하나의 저장소 네이티브 진입점으로 실행 + - `~/.profile`에서 누락된 제공자 환경 변수를 자동 로드 + - 기본적으로 현재 사용 가능한 인증이 있는 제공자로 각 스위트 범위를 자동 축소 - `scripts/test-live.mjs`를 재사용하므로 Heartbeat 및 조용한 모드 동작이 일관되게 유지됨 - 예시: - `pnpm test:live:media` @@ -814,186 +823,185 @@ env 키(예: `~/.profile`에 export된 값)에 의존하려면 `source ~/.profil - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker 러너(선택적 “Linux에서 동작함” 확인) +## Docker 실행기(선택적 “Linux에서 작동함” 검사) -이 Docker 러너는 두 개의 범주로 나뉩니다: +이 Docker 실행기들은 두 가지 범주로 나뉩니다: -- live 모델 러너: `test:docker:live-models`와 `test:docker:live-gateway`는 저장소 Docker 이미지 내부에서 해당 profile-key live 파일만 실행합니다(`src/agents/models.profiles.live.test.ts` 및 `src/gateway/gateway-models.profiles.live.test.ts`). 이때 로컬 config 디렉터리와 워크스페이스를 마운트하고(마운트된 경우 `~/.profile`도 로드) 실행합니다. 대응되는 로컬 엔트리포인트는 `test:live:models-profiles`와 `test:live:gateway-profiles`입니다. -- Docker live 러너는 전체 Docker 스윕이 현실적으로 유지되도록 기본적으로 더 작은 스모크 상한을 사용합니다: - `test:docker:live-models`는 기본적으로 `OPENCLAW_LIVE_MAX_MODELS=12`를 사용하고, - `test:docker:live-gateway`는 기본적으로 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- 라이브 모델 실행기: `test:docker:live-models`와 `test:docker:live-gateway`는 저장소 Docker 이미지 내부에서 해당 프로필 키 라이브 파일만 실행합니다(`src/agents/models.profiles.live.test.ts`와 `src/gateway/gateway-models.profiles.live.test.ts`). 로컬 설정 디렉터리와 워크스페이스를 마운트하고(마운트된 경우 `~/.profile`도 불러옴) 실행합니다. 대응하는 로컬 진입점은 `test:live:models-profiles`와 `test:live:gateway-profiles`입니다. +- Docker 라이브 실행기는 전체 Docker 스윕이 실용적으로 유지되도록 기본적으로 더 작은 스모크 상한을 사용합니다: + `test:docker:live-models`의 기본값은 `OPENCLAW_LIVE_MAX_MODELS=12`이며, + `test:docker:live-gateway`의 기본값은 `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, 그리고 - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`를 사용합니다. 더 큰 전체 스캔을 명시적으로 원할 때는 이 환경 변수를 재정의하세요. -- `test:docker:all`은 먼저 `test:docker:live-build`를 통해 live Docker 이미지를 한 번 빌드한 뒤, 두 개의 live Docker 레인에서 이를 재사용합니다. -- 컨테이너 스모크 러너: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:plugins`는 하나 이상의 실제 컨테이너를 부팅하고 더 상위 수준의 integration 경로를 검증합니다. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`입니다. 더 큰 완전 스캔을 명시적으로 원할 때는 이러한 환경 변수를 재정의하세요. +- `test:docker:all`은 `test:docker:live-build`를 통해 라이브 Docker 이미지를 한 번 빌드한 다음, 그 이미지를 두 개의 라이브 Docker 레인에서 재사용합니다. +- 컨테이너 스모크 실행기: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:plugins`는 하나 이상의 실제 컨테이너를 부팅하고 더 높은 수준의 통합 경로를 검증합니다. -live 모델 Docker 러너는 또한 필요한 CLI auth 홈만 bind mount하거나(실행이 범위 축소되지 않은 경우 지원되는 모든 것), 실행 전에 이를 컨테이너 홈으로 복사하므로 외부 CLI OAuth가 호스트 auth 저장소를 변경하지 않고 토큰을 갱신할 수 있습니다: +라이브 모델 Docker 실행기는 또한 필요한 CLI 인증 홈만 바인드 마운트하고(또는 실행 범위를 좁히지 않은 경우 지원되는 모든 홈을 마운트하고), 실행 전에 이를 컨테이너 홈으로 복사합니다. 이렇게 하면 외부 CLI OAuth가 호스트 인증 저장소를 변경하지 않고도 토큰을 갱신할 수 있습니다: - 직접 모델: `pnpm test:docker:live-models` (스크립트: `scripts/test-live-models-docker.sh`) - ACP 바인드 스모크: `pnpm test:docker:live-acp-bind` (스크립트: `scripts/test-live-acp-bind-docker.sh`) - CLI 백엔드 스모크: `pnpm test:docker:live-cli-backend` (스크립트: `scripts/test-live-cli-backend-docker.sh`) -- Codex app-server 하니스 스모크: `pnpm test:docker:live-codex-harness` (스크립트: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + dev 에이전트: `pnpm test:docker:live-gateway` (스크립트: `scripts/test-live-gateway-models-docker.sh`) -- Open WebUI live 스모크: `pnpm test:docker:openwebui` (스크립트: `scripts/e2e/openwebui-docker.sh`) +- Codex app-server 하네스 스모크: `pnpm test:docker:live-codex-harness` (스크립트: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + 개발 에이전트: `pnpm test:docker:live-gateway` (스크립트: `scripts/test-live-gateway-models-docker.sh`) +- Open WebUI 라이브 스모크: `pnpm test:docker:openwebui` (스크립트: `scripts/e2e/openwebui-docker.sh`) - 온보딩 마법사(TTY, 전체 스캐폴딩): `pnpm test:docker:onboard` (스크립트: `scripts/e2e/onboard-docker.sh`) -- Gateway 네트워킹(두 컨테이너, WS auth + health): `pnpm test:docker:gateway-network` (스크립트: `scripts/e2e/gateway-network-docker.sh`) -- MCP 채널 브리지(시드된 Gateway + stdio 브리지 + 원시 Claude notification-frame 스모크): `pnpm test:docker:mcp-channels` (스크립트: `scripts/e2e/mcp-channels-docker.sh`) +- Gateway 네트워킹(컨테이너 두 개, WS 인증 + 상태 확인): `pnpm test:docker:gateway-network` (스크립트: `scripts/e2e/gateway-network-docker.sh`) +- MCP 채널 브리지(시드된 Gateway + stdio 브리지 + 원시 Claude 알림 프레임 스모크): `pnpm test:docker:mcp-channels` (스크립트: `scripts/e2e/mcp-channels-docker.sh`) - Plugins(설치 스모크 + `/plugin` 별칭 + Claude 번들 재시작 시맨틱): `pnpm test:docker:plugins` (스크립트: `scripts/e2e/plugins-docker.sh`) -live 모델 Docker 러너는 또한 현재 체크아웃을 읽기 전용으로 bind mount하고 -컨테이너 내부의 임시 작업 디렉터리로 스테이징합니다. 이렇게 하면 runtime -이미지는 슬림하게 유지하면서도 정확히 현재 로컬 소스/config에 대해 Vitest를 실행할 수 있습니다. -스테이징 단계는 -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, 앱 로컬 `.build`, Gradle 출력 디렉터리처럼 -대용량 로컬 전용 캐시와 앱 빌드 출력을 건너뛰므로, -Docker live 실행이 머신별 아티팩트를 복사하느라 몇 분씩 쓰지 않게 됩니다. -또한 `OPENCLAW_SKIP_CHANNELS=1`을 설정하므로 Gateway live probe가 -컨테이너 내부에서 실제 Telegram/Discord 등의 채널 worker를 시작하지 않습니다. +라이브 모델 Docker 실행기는 현재 체크아웃도 읽기 전용으로 바인드 마운트한 뒤, +컨테이너 내부의 임시 작업 디렉터리로 준비합니다. 이렇게 하면 런타임 +이미지를 가볍게 유지하면서도 정확히 로컬 소스/설정으로 Vitest를 실행할 수 있습니다. +준비 단계에서는 `.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, 그리고 앱 로컬 `.build` 또는 +Gradle 출력 디렉터리 같은 큰 로컬 전용 캐시와 앱 빌드 출력을 건너뛰므로 Docker 라이브 실행이 +머신별 아티팩트를 복사하느라 몇 분씩 소비하지 않습니다. +또한 `OPENCLAW_SKIP_CHANNELS=1`을 설정하므로 Gateway 라이브 프로브가 컨테이너 내부에서 +실제 Telegram/Discord 등의 채널 워커를 시작하지 않습니다. `test:docker:live-models`는 여전히 `pnpm test:live`를 실행하므로, -이 Docker 레인에서 Gateway live 커버리지를 좁히거나 제외해야 할 때는 +해당 Docker 레인에서 Gateway 라이브 커버리지를 좁히거나 제외해야 할 때는 `OPENCLAW_LIVE_GATEWAY_*`도 함께 전달하세요. -`test:docker:openwebui`는 더 상위 수준의 호환성 스모크입니다. 이 러너는 -OpenAI 호환 HTTP 엔드포인트가 활성화된 OpenClaw Gateway 컨테이너를 시작하고, -고정된 Open WebUI 컨테이너를 해당 Gateway에 연결해 시작한 다음, +`test:docker:openwebui`는 더 높은 수준의 호환성 스모크입니다. OpenAI 호환 HTTP 엔드포인트가 활성화된 +OpenClaw Gateway 컨테이너를 시작하고, 해당 Gateway를 대상으로 고정된 Open WebUI 컨테이너를 시작하며, Open WebUI를 통해 로그인하고, `/api/models`가 `openclaw/default`를 노출하는지 검증한 뒤, Open WebUI의 `/api/chat/completions` 프록시를 통해 실제 채팅 요청을 전송합니다. -첫 실행은 Docker가 Open WebUI 이미지를 pull해야 하거나 -Open WebUI 자체의 콜드 스타트 설정을 끝내야 할 수 있으므로 눈에 띄게 느릴 수 있습니다. -이 레인은 사용 가능한 live 모델 키를 기대하며, -Docker 실행에서는 `OPENCLAW_PROFILE_FILE` -(기본값 `~/.profile`)이 이를 제공하는 기본 방법입니다. -성공적인 실행은 `{ "ok": true, "model": -"openclaw/default", ... }`와 같은 작은 JSON payload를 출력합니다. -`test:docker:mcp-channels`는 의도적으로 결정적이며 -실제 Telegram, Discord, iMessage 계정이 필요하지 않습니다. 시드된 Gateway -컨테이너를 부팅하고, `openclaw mcp serve`를 시작하는 두 번째 컨테이너를 띄운 다음, -실제 stdio MCP 브리지를 통해 라우팅된 대화 탐색, 트랜스크립트 읽기, 첨부 파일 메타데이터, -live 이벤트 큐 동작, outbound 전송 라우팅, Claude 스타일 채널 + -권한 알림을 검증합니다. 알림 검사는 원시 stdio MCP 프레임을 직접 -검사하므로, 이 스모크는 특정 클라이언트 SDK가 우연히 노출하는 내용이 아니라 -브리지가 실제로 내보내는 내용을 검증합니다. +처음 실행은 Docker가 Open WebUI 이미지를 풀해야 하거나 +Open WebUI가 자체 콜드 스타트 설정을 마쳐야 할 수 있으므로 눈에 띄게 느릴 수 있습니다. +이 레인은 사용 가능한 라이브 모델 키를 기대하며, +Dockerized 실행에서 이를 제공하는 기본 방법은 `OPENCLAW_PROFILE_FILE` +(기본값 `~/.profile`)입니다. +성공한 실행은 `{ "ok": true, "model": +"openclaw/default", ... }`와 같은 작은 JSON 페이로드를 출력합니다. +`test:docker:mcp-channels`는 의도적으로 결정적이며 실제 +Telegram, Discord, 또는 iMessage 계정이 필요하지 않습니다. 시드된 Gateway +컨테이너를 부팅하고, `openclaw mcp serve`를 실행하는 두 번째 컨테이너를 시작한 뒤, +라우팅된 대화 탐색, 전사본 읽기, 첨부 파일 메타데이터, +라이브 이벤트 큐 동작, 아웃바운드 전송 라우팅, 그리고 Claude 스타일의 채널 + +권한 알림을 실제 stdio MCP 브리지를 통해 검증합니다. 알림 검사는 +원시 stdio MCP 프레임을 직접 검사하므로, 특정 클라이언트 SDK가 우연히 +표면화하는 것만이 아니라 브리지가 실제로 무엇을 내보내는지를 검증합니다. -수동 ACP plain-language thread 스모크(CI 아님): +수동 ACP 자연어 스레드 스모크(CI 아님): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- 이 스크립트는 회귀/디버그 워크플로를 위해 유지하세요. ACP 스레드 라우팅 검증에 다시 필요할 수 있으므로 삭제하지 마세요. +- 이 스크립트는 회귀/디버그 워크플로용으로 유지하세요. ACP 스레드 라우팅 검증에 다시 필요할 수 있으므로 삭제하지 마세요. 유용한 환경 변수: -- `OPENCLAW_CONFIG_DIR=...` (기본값: `~/.openclaw`) → `/home/node/.openclaw`에 마운트 -- `OPENCLAW_WORKSPACE_DIR=...` (기본값: `~/.openclaw/workspace`) → `/home/node/.openclaw/workspace`에 마운트 -- `OPENCLAW_PROFILE_FILE=...` (기본값: `~/.profile`) → `/home/node/.profile`에 마운트되며 테스트 실행 전 로드됨 -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (기본값: `~/.cache/openclaw/docker-cli-tools`) → Docker 내부 캐시된 CLI 설치를 위해 `/home/node/.npm-global`에 마운트 -- `$HOME` 아래 외부 CLI auth 디렉터리/파일은 `/host-auth...` 아래에 읽기 전용으로 마운트된 뒤 테스트 시작 전 `/home/node/...`로 복사됨 +- `OPENCLAW_CONFIG_DIR=...` (기본값: `~/.openclaw`)를 `/home/node/.openclaw`에 마운트 +- `OPENCLAW_WORKSPACE_DIR=...` (기본값: `~/.openclaw/workspace`)를 `/home/node/.openclaw/workspace`에 마운트 +- `OPENCLAW_PROFILE_FILE=...` (기본값: `~/.profile`)를 `/home/node/.profile`에 마운트하고 테스트 실행 전에 불러옴 +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`을 사용하면 `OPENCLAW_PROFILE_FILE`에서 불러온 환경 변수만 검증하며, 임시 설정/워크스페이스 디렉터리를 사용하고 외부 CLI 인증 마운트는 사용하지 않음 +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (기본값: `~/.cache/openclaw/docker-cli-tools`)를 `/home/node/.npm-global`에 마운트하여 Docker 내부 CLI 설치를 캐시 +- `$HOME` 아래의 외부 CLI 인증 디렉터리/파일은 `/host-auth...` 아래에 읽기 전용으로 마운트된 뒤, 테스트 시작 전에 `/home/node/...`로 복사됨 - 기본 디렉터리: `.minimax` - 기본 파일: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - 범위를 좁힌 프로바이더 실행은 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`에서 추론된 필요한 디렉터리/파일만 마운트 - - 수동 재정의: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, 또는 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 같은 쉼표 목록 + - 범위를 좁힌 제공자 실행은 `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`에서 추론된 필요한 디렉터리/파일만 마운트 + - 수동 재정의: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none`, 또는 `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` 같은 쉼표 구분 목록 - 실행 범위를 좁히려면 `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` -- 컨테이너 내부에서 프로바이더를 필터링하려면 `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` +- 컨테이너 내부 제공자를 필터링하려면 `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` - 재빌드가 필요 없는 재실행에서 기존 `openclaw:local-live` 이미지를 재사용하려면 `OPENCLAW_SKIP_DOCKER_BUILD=1` -- 자격 증명이 profile 저장소에서 오도록 보장하려면(환경 변수 아님) `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 자격 증명이 프로필 저장소에서 오도록 보장하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` (환경 변수 사용 안 함) - Open WebUI 스모크를 위해 Gateway가 노출할 모델을 선택하려면 `OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUI 스모크가 사용하는 nonce 검증 프롬프트를 재정의하려면 `OPENCLAW_OPENWEBUI_PROMPT=...` +- Open WebUI 스모크에서 사용하는 nonce 확인 프롬프트를 재정의하려면 `OPENCLAW_OPENWEBUI_PROMPT=...` - 고정된 Open WebUI 이미지 태그를 재정의하려면 `OPENWEBUI_IMAGE=...` -## 문서 기본 검증 +## 문서 점검 -문서를 수정한 후 문서 검사를 실행하세요: `pnpm check:docs`. -페이지 내 heading 검사까지 필요할 때는 전체 Mintlify 앵커 검증을 실행하세요: `pnpm docs:check-links:anchors`. +문서를 수정한 후 문서 검사 실행: `pnpm check:docs`. +페이지 내부 헤딩 검사까지 필요할 때는 전체 Mintlify 앵커 검증 실행: `pnpm docs:check-links:anchors`. ## 오프라인 회귀(CI 안전) -실제 프로바이더 없이도 가능한 “실제 파이프라인” 회귀입니다: +실제 제공자 없이도 “실제 파이프라인” 회귀를 검증하는 테스트입니다: -- Gateway tool calling(mock OpenAI, 실제 Gateway + 에이전트 루프): `src/gateway/gateway.test.ts` (케이스: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Gateway wizard(WS `wizard.start`/`wizard.next`, config + auth 기록 강제): `src/gateway/gateway.test.ts` (케이스: "runs wizard over ws and writes auth token config") +- Gateway 도구 호출(모의 OpenAI, 실제 Gateway + 에이전트 루프): `src/gateway/gateway.test.ts` (케이스: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway 마법사(WS `wizard.start`/`wizard.next`, 설정 + 인증 강제 저장): `src/gateway/gateway.test.ts` (케이스: "runs wizard over ws and writes auth token config") ## 에이전트 신뢰성 평가(Skills) -우리는 이미 “에이전트 신뢰성 평가”처럼 동작하는 몇 가지 CI 안전 테스트를 보유하고 있습니다: +이미 “에이전트 신뢰성 평가”처럼 동작하는 몇 가지 CI 안전 테스트가 있습니다: -- 실제 Gateway + 에이전트 루프를 통한 mock tool-calling(`src/gateway/gateway.test.ts`). -- 세션 연결과 config 효과를 검증하는 end-to-end wizard 흐름(`src/gateway/gateway.test.ts`). +- 실제 Gateway + 에이전트 루프를 통한 모의 도구 호출(`src/gateway/gateway.test.ts`) +- 세션 연결과 설정 효과를 검증하는 엔드투엔드 마법사 흐름(`src/gateway/gateway.test.ts`) -Skills에 대해 여전히 부족한 것([Skills](/ko/tools/skills) 참고): +Skills에 대해 아직 부족한 것([Skills](/ko/tools/skills) 참고): -- **의사결정:** 프롬프트에 skills가 나열되었을 때, 에이전트가 올바른 skill을 선택하는가(또는 관련 없는 것은 피하는가)? +- **의사결정:** 프롬프트에 Skills가 나열되었을 때 에이전트가 올바른 Skill을 선택하는가(또는 관련 없는 Skill을 피하는가)? - **준수:** 에이전트가 사용 전에 `SKILL.md`를 읽고 필요한 단계/인수를 따르는가? -- **워크플로 계약:** tool 순서, 세션 히스토리 유지, sandbox 경계를 검증하는 다중 턴 시나리오. +- **워크플로 계약:** 도구 순서, 세션 이력 유지, 샌드박스 경계를 검증하는 다중 턴 시나리오 -향후 평가는 우선 결정적으로 유지되어야 합니다: +향후 평가는 먼저 결정성을 유지해야 합니다: -- mock 프로바이더를 사용해 tool 호출 + 순서, skill 파일 읽기, 세션 연결을 검증하는 시나리오 러너 -- skill 중심 시나리오의 소규모 스위트(사용 vs 회피, 게이팅, 프롬프트 인젝션) -- CI 안전 스위트가 마련된 뒤에만 선택적으로 live 평가(옵트인, 환경 변수 게이트) +- 모의 제공자를 사용해 도구 호출 + 순서, Skill 파일 읽기, 세션 연결을 검증하는 시나리오 실행기 +- Skill 중심의 소규모 시나리오 스위트(사용 vs 회피, 게이팅, 프롬프트 인젝션) +- 선택적 라이브 평가(옵트인, 환경 변수 게이트)는 CI 안전 스위트가 갖춰진 후에만 추가 ## 계약 테스트(Plugin 및 채널 형태) -계약 테스트는 등록된 모든 plugin과 채널이 해당 -인터페이스 계약을 준수하는지 검증합니다. 발견된 모든 plugin을 순회하며 -형태 및 동작 검증 모음을 실행합니다. 기본 `pnpm test` unit 레인은 의도적으로 -이러한 공유 시임 및 스모크 파일을 건너뛰므로, 공유 채널 또는 프로바이더 표면을 건드렸다면 +계약 테스트는 등록된 모든 Plugin과 채널이 해당 +인터페이스 계약을 준수하는지 검증합니다. 발견된 모든 Plugin을 순회하고 +형태 및 동작 검증 스위트를 실행합니다. 기본 `pnpm test` 단위 레인은 의도적으로 +이러한 공유 시임 및 스모크 파일을 건너뛰므로, 공유 채널 또는 제공자 표면을 건드렸다면 계약 명령을 명시적으로 실행하세요. -### 명령어 +### 명령 - 모든 계약: `pnpm test:contracts` - 채널 계약만: `pnpm test:contracts:channels` -- 프로바이더 계약만: `pnpm test:contracts:plugins` +- 제공자 계약만: `pnpm test:contracts:plugins` ### 채널 계약 -`src/channels/plugins/contracts/*.contract.test.ts`에 위치: +`src/channels/plugins/contracts/*.contract.test.ts`에 있습니다: -- **plugin** - 기본 plugin 형태(id, 이름, 기능) +- **plugin** - 기본 Plugin 형태(id, name, capabilities) - **setup** - 설정 마법사 계약 - **session-binding** - 세션 바인딩 동작 -- **outbound-payload** - 메시지 payload 구조 +- **outbound-payload** - 메시지 페이로드 구조 - **inbound** - 인바운드 메시지 처리 -- **actions** - 채널 작업 핸들러 +- **actions** - 채널 액션 핸들러 - **threading** - 스레드 ID 처리 -- **directory** - 디렉터리/명단 API -- **group-policy** - 그룹 정책 강제 +- **directory** - 디렉터리/로스터 API +- **group-policy** - 그룹 정책 적용 -### 프로바이더 상태 계약 +### 제공자 상태 계약 -`src/plugins/contracts/*.contract.test.ts`에 위치합니다. +`src/plugins/contracts/*.contract.test.ts`에 있습니다. -- **status** - 채널 상태 probe -- **registry** - Plugin registry 형태 +- **status** - 채널 상태 프로브 +- **registry** - Plugin 레지스트리 형태 -### 프로바이더 계약 +### 제공자 계약 -`src/plugins/contracts/*.contract.test.ts`에 위치: +`src/plugins/contracts/*.contract.test.ts`에 있습니다: -- **auth** - auth 흐름 계약 -- **auth-choice** - auth 선택 +- **auth** - 인증 흐름 계약 +- **auth-choice** - 인증 선택 계약 - **catalog** - 모델 카탈로그 API -- **discovery** - Plugin 발견 +- **discovery** - Plugin 탐색 - **loader** - Plugin 로딩 -- **runtime** - 프로바이더 runtime +- **runtime** - 제공자 런타임 - **shape** - Plugin 형태/인터페이스 - **wizard** - 설정 마법사 -### 실행 시점 +### 실행해야 할 때 -- plugin-sdk export 또는 subpath를 변경한 후 -- 채널 또는 프로바이더 plugin을 추가하거나 수정한 후 -- plugin 등록 또는 발견을 리팩터링한 후 +- `plugin-sdk` export 또는 하위 경로를 변경한 후 +- 채널 또는 제공자 Plugin을 추가하거나 수정한 후 +- Plugin 등록 또는 탐색을 리팩터링한 후 계약 테스트는 CI에서 실행되며 실제 API 키가 필요하지 않습니다. -## 회귀 추가하기(가이드) +## 회귀 테스트 추가하기(가이드) -live에서 발견된 프로바이더/모델 이슈를 수정할 때: +라이브에서 발견된 제공자/모델 이슈를 수정할 때: -- 가능하다면 CI 안전 회귀를 추가하세요(mock/stub 프로바이더 또는 정확한 요청 형태 변환 캡처) -- 본질적으로 live 전용이라면(rate limit, auth 정책), live 테스트는 좁고 옵트인 상태로 유지하고 env var로 게이트하세요 -- 버그를 잡아내는 가장 작은 계층을 대상으로 삼는 편이 좋습니다: - - 프로바이더 요청 변환/재생 버그 → 직접 모델 테스트 - - Gateway 세션/히스토리/tool 파이프라인 버그 → Gateway live 스모크 또는 CI 안전 Gateway mock 테스트 +- 가능하면 CI 안전 회귀 테스트를 추가하세요(모의/스텁 제공자 또는 정확한 요청 형태 변환 캡처) +- 본질적으로 라이브 전용인 경우(속도 제한, 인증 정책), 라이브 테스트는 좁고 환경 변수 기반 옵트인으로 유지하세요 +- 버그를 잡는 가장 작은 레이어를 대상으로 하는 것을 선호하세요: + - 제공자 요청 변환/재생 버그 → 직접 모델 테스트 + - Gateway 세션/이력/도구 파이프라인 버그 → Gateway 라이브 스모크 또는 CI 안전 Gateway 모의 테스트 - SecretRef 순회 가드레일: - - `src/secrets/exec-secret-ref-id-parity.test.ts`는 레지스트리 메타데이터(`listSecretTargetRegistryEntries()`)에서 SecretRef 클래스별 샘플 타깃 하나를 도출한 뒤, 순회 세그먼트 exec ID가 거부되는지 검증합니다. - - `src/secrets/target-registry-data.ts`에 새 `includeInPlan` SecretRef 타깃 계열을 추가한다면, 해당 테스트의 `classifyTargetClass`를 업데이트하세요. 이 테스트는 분류되지 않은 타깃 ID에서 의도적으로 실패하므로 새 클래스가 조용히 건너뛰어질 수 없습니다. + - `src/secrets/exec-secret-ref-id-parity.test.ts`는 레지스트리 메타데이터(`listSecretTargetRegistryEntries()`)에서 SecretRef 클래스별 샘플 대상 하나를 도출한 뒤, 순회 세그먼트 exec ID가 거부되는지 검증합니다. + - `src/secrets/target-registry-data.ts`에 새 `includeInPlan` SecretRef 대상 계열을 추가한다면, 해당 테스트의 `classifyTargetClass`를 업데이트하세요. 이 테스트는 분류되지 않은 대상 ID에서 의도적으로 실패하므로 새 클래스가 조용히 건너뛰어질 수 없습니다. diff --git a/docs/ko/providers/github-copilot.md b/docs/ko/providers/github-copilot.md index 15869024b..7f7d96c03 100644 --- a/docs/ko/providers/github-copilot.md +++ b/docs/ko/providers/github-copilot.md @@ -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을 사용하는 두 가지 방법 - - 네이티브 디바이스 로그인 흐름을 사용해 GitHub 토큰을 얻은 다음, OpenClaw가 실행될 때 이를 - Copilot API 토큰으로 교환합니다. VS Code가 필요하지 않기 때문에 이것이 **기본값**이자 가장 간단한 경로입니다. + + OpenClaw가 실행될 때 GitHub 토큰을 얻기 위해 기본 디바이스 로그인 흐름을 사용한 다음, 이를 Copilot API 토큰으로 교환합니다. VS Code가 필요하지 않기 때문에 이것이 **기본값**이자 가장 간단한 방법입니다. @@ -32,15 +29,14 @@ GitHub Copilot는 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요 openclaw models auth login-github-copilot ``` - URL에 방문해 일회용 코드를 입력하라는 메시지가 표시됩니다. 완료될 때까지 - 터미널을 열어 두세요. + URL로 이동하여 일회용 코드를 입력하라는 안내가 표시됩니다. 완료될 때까지 터미널을 열어 두세요. ```bash openclaw models set github-copilot/gpt-4o ``` - 또는 구성에서: + 또는 config에서: ```json5 { @@ -53,12 +49,10 @@ GitHub Copilot는 GitHub의 AI 코딩 도우미입니다. GitHub 계정과 요 - **Copilot Proxy** VS Code 확장을 로컬 브리지로 사용합니다. OpenClaw는 - 프록시의 `/v1` 엔드포인트와 통신하고, 그곳에서 구성한 모델 목록을 사용합니다. + 로컬 브리지로 **Copilot Proxy** VS Code 확장을 사용합니다. OpenClaw는 프록시의 `/v1` 엔드포인트와 통신하고, 그곳에서 구성한 모델 목록을 사용합니다. - 이미 VS Code에서 Copilot Proxy를 실행 중이거나 - 이를 통해 라우팅해야 하는 경우 이 옵션을 선택하세요. Plugin을 활성화하고 VS Code 확장을 계속 실행 상태로 유지해야 합니다. + 이미 VS Code에서 Copilot Proxy를 실행 중이거나 이를 통해 라우팅해야 할 때 이 방법을 선택하세요. Plugin을 활성화하고 VS Code 확장이 계속 실행 중이어야 합니다. @@ -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 ``` - 디바이스 로그인 흐름에는 대화형 TTY가 필요합니다. 비대화형 스크립트나 CI 파이프라인이 아니라 - 터미널에서 직접 실행하세요. + 디바이스 로그인 흐름에는 대화형 TTY가 필요합니다. 비대화형 스크립트나 CI 파이프라인이 아니라, 터미널에서 직접 실행하세요. - Copilot 모델 사용 가능 여부는 GitHub 요금제에 따라 다릅니다. 어떤 모델이 - 거부되면 다른 ID를 시도해 보세요(예: `github-copilot/gpt-4.1`). + Copilot 모델 사용 가능 여부는 GitHub 요금제에 따라 달라집니다. 모델이 거부되면 다른 ID(예: `github-copilot/gpt-4.1`)를 시도해 보세요. - - Claude 모델 ID는 자동으로 Anthropic Messages 전송을 사용합니다. GPT, - o-series, Gemini 모델은 OpenAI Responses 전송을 유지합니다. OpenClaw는 - 모델 ref를 기준으로 올바른 전송을 선택합니다. + + Claude 모델 ID는 자동으로 Anthropic Messages 전송 방식을 사용합니다. GPT, o-series, Gemini 모델은 OpenAI Responses 전송 방식을 유지합니다. OpenClaw는 모델 ref를 기준으로 올바른 전송 방식을 선택합니다. - - OpenClaw는 다음 우선순위 순서로 환경 변수에서 Copilot 인증을 확인합니다: + + 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`)은 - 인증 프로필 저장소에 토큰을 저장하며, 모든 환경 - 변수보다 우선합니다. + 인증 프로필 저장소에 토큰을 저장하며 모든 환경 변수보다 우선합니다. - 로그인은 인증 프로필 저장소에 GitHub 토큰을 저장하고, OpenClaw가 실행될 때 이를 - Copilot API 토큰으로 교환합니다. 토큰을 수동으로 - 관리할 필요는 없습니다. + 로그인은 GitHub 토큰을 인증 프로필 저장소에 저장하고, OpenClaw가 실행될 때 이를 Copilot API 토큰으로 교환합니다. 토큰을 수동으로 관리할 필요는 없습니다. -대화형 TTY가 필요합니다. 로그인 명령은 헤드리스 스크립트나 CI 작업 내부가 아니라 -터미널에서 직접 실행하세요. +대화형 TTY가 필요합니다. 로그인 명령은 헤드리스 스크립트나 CI 작업 내부가 아니라 터미널에서 직접 실행하세요. -## 관련 문서 +## 메모리 검색 임베딩 + +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을 건너뛰고 다음 제공자를 시도합니다. + +## 관련 항목 - 프로바이더, 모델 ref, 페일오버 동작 선택하기. + 제공자, 모델 ref, 장애 조치 동작 선택. 인증 세부 정보와 자격 증명 재사용 규칙. diff --git a/docs/ko/providers/ollama.md b/docs/ko/providers/ollama.md index 4f1cc1c0a..e5604dce0 100644 --- a/docs/ko/providers/ollama.md +++ b/docs/ko/providers/ollama.md @@ -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`. **원격 Ollama 사용자**: OpenClaw에서 `/v1` OpenAI 호환 URL(`http://host:11434/v1`)을 사용하지 마세요. 이렇게 하면 도구 호출이 깨지고 모델이 원시 도구 JSON을 일반 텍스트로 출력할 수 있습니다. 대신 네이티브 Ollama API URL을 사용하세요: `baseUrl: "http://host:11434"` (`/v1` 없음). @@ -27,7 +27,7 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있 - **가장 적합한 경우:** 자동 모델 검색이 포함된 동작하는 Ollama 설정까지 가장 빠른 경로. + **적합한 경우:** 작동하는 Ollama 클라우드 또는 로컬 설정까지 가장 빠르게 진행하고 싶을 때. @@ -35,16 +35,15 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있 openclaw onboard ``` - provider 목록에서 **Ollama**를 선택하세요. + 공급자 목록에서 **Ollama**를 선택하세요. - - **클라우드 + 로컬** — 클라우드 호스팅 모델과 로컬 모델을 함께 사용 - - **로컬** — 로컬 모델만 사용 - - **클라우드 + 로컬**을 선택했고 ollama.com에 로그인되어 있지 않다면, 온보딩이 브라우저 로그인 흐름을 엽니다. + - **Cloud + Local** — 로컬 Ollama 호스트와, 그 호스트를 통해 라우팅되는 클라우드 모델 + - **Cloud only** — `https://ollama.com`을 통한 호스팅된 Ollama 모델 + - **Local only** — 로컬 모델만 사용 - 온보딩은 사용 가능한 모델을 검색하고 기본값을 제안합니다. 선택한 모델을 로컬에서 사용할 수 없으면 자동으로 가져옵니다. + `Cloud only`는 `OLLAMA_API_KEY`를 요청하고 호스팅된 클라우드 기본값을 제안합니다. `Cloud + Local`과 `Local only`는 Ollama base URL을 요청하고, 사용 가능한 모델을 검색하며, 선택한 로컬 모델이 아직 없으면 자동으로 pull합니다. `Cloud + Local`은 해당 Ollama 호스트가 클라우드 액세스를 위해 로그인되어 있는지도 확인합니다. ```bash @@ -61,7 +60,7 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있 --accept-risk ``` - 선택적으로 사용자 지정 base URL 또는 모델을 지정할 수 있습니다: + 필요하면 사용자 지정 base URL 또는 모델도 지정할 수 있습니다. ```bash openclaw onboard --non-interactive \ @@ -74,37 +73,35 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있 - **가장 적합한 경우:** 설치, 모델 pull, 구성에 대한 완전한 제어. + **적합한 경우:** 클라우드 또는 로컬 설정을 완전히 제어하고 싶을 때. - - [ollama.com/download](https://ollama.com/download)에서 다운로드하세요. + + - **Cloud + Local**: Ollama를 설치하고 `ollama signin`으로 로그인한 뒤, 클라우드 요청을 해당 호스트를 통해 라우팅 + - **Cloud only**: `OLLAMA_API_KEY`와 함께 `https://ollama.com` 사용 + - **Local only**: [ollama.com/download](https://ollama.com/download)에서 Ollama 설치 - + ```bash ollama pull gemma4 - # or + # 또는 ollama pull gpt-oss:20b - # or + # 또는 ollama pull llama3.3 ``` - - 클라우드 모델도 사용하려면: - - ```bash - ollama signin - ``` - - 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" ``` @@ -113,7 +110,7 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있 openclaw models set ollama/gemma4 ``` - 또는 구성에서 기본값을 설정: + 또는 config에서 기본값을 설정할 수 있습니다. ```json5 { @@ -133,19 +130,24 @@ Ollama는 내 컴퓨터에서 오픈 소스 모델을 쉽게 실행할 수 있 ## 클라우드 모델 - - 클라우드 모델을 사용하면 로컬 모델과 함께 클라우드 호스팅 모델을 실행할 수 있습니다. 예로 `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, `glm-5.1:cloud`가 있으며, 이들은 로컬 `ollama pull`이 **필요하지 않습니다**. + + `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로 유지합니다. - - 로컬 전용 모드에서 OpenClaw는 로컬 Ollama 인스턴스에서 모델을 검색합니다. 클라우드 로그인은 필요하지 않습니다. + + `Cloud only`는 `https://ollama.com`의 Ollama 호스팅 API를 대상으로 실행됩니다. + + 설정 중에 **Cloud only**를 사용하세요. OpenClaw는 `OLLAMA_API_KEY`를 요청하고, `baseUrl: "https://ollama.com"`을 설정하며, 호스팅된 클라우드 모델 목록을 초기화합니다. 이 경로는 로컬 Ollama 서버나 `ollama signin`이 **필요하지 않습니다**. + + + + + 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 새 모델은 자동으로 검색되어 바로 사용할 수 있습니다. -`models.providers.ollama`를 명시적으로 설정하면 자동 검색은 건너뛰며, 모델을 수동으로 정의해야 합니다. 아래의 명시적 구성 섹션을 참조하세요. +`models.providers.ollama`를 명시적으로 설정하면 자동 검색은 건너뛰며, 모델을 수동으로 정의해야 합니다. 아래의 명시적 config 섹션을 참고하세요. ## 구성 - Ollama를 활성화하는 가장 간단한 방법은 환경 변수를 사용하는 것입니다: + 가장 간단한 local-only 활성화 경로는 환경 변수를 사용하는 것입니다. ```bash export OLLAMA_API_KEY="ollama-local" ``` - `OLLAMA_API_KEY`가 설정되어 있으면 provider 항목에서 `apiKey`를 생략할 수 있으며, OpenClaw가 사용 가능 여부 확인을 위해 이를 채워 넣습니다. + `OLLAMA_API_KEY`가 설정되어 있으면 provider 항목에서 `apiKey`를 생략할 수 있으며, OpenClaw가 가용성 확인을 위해 이를 채웁니다. - 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 - Ollama가 다른 호스트나 포트에서 실행 중인 경우(명시적 구성은 자동 검색을 비활성화하므로 모델을 수동 정의해야 함): + Ollama가 다른 호스트나 포트에서 실행 중인 경우(명시적 config는 자동 검색을 비활성화하므로 모델을 수동으로 정의해야 함): ```json5 { @@ -249,7 +251,7 @@ ollama pull mistral ``` - URL에 `/v1`을 추가하지 마세요. `/v1` 경로는 OpenAI 호환 모드를 사용하며, 이 모드에서는 도구 호출이 신뢰할 수 없습니다. 경로 접미사 없이 기본 Ollama URL을 사용하세요. + URL에 `/v1`을 추가하지 마세요. `/v1` 경로는 OpenAI 호환 모드를 사용하며, 이 경우 도구 호출이 신뢰할 수 없습니다. 경로 접미사 없이 기본 Ollama URL을 사용하세요. @@ -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**를 지원합 ``` -전체 설정 및 동작 세부 정보는 [Ollama Web Search](/ko/tools/ollama-search)를 참조하세요. +전체 설정 및 동작 세부 정보는 [Ollama 웹 검색](/ko/tools/ollama-search)을 참고하세요. ## 고급 구성 @@ -305,10 +307,10 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합 - **OpenAI 호환 모드에서는 도구 호출이 신뢰할 수 없습니다.** 프록시에 OpenAI 형식이 꼭 필요하고 네이티브 도구 호출 동작에 의존하지 않는 경우에만 이 모드를 사용하세요. + **OpenAI 호환 모드에서는 도구 호출이 신뢰할 수 없습니다.** 프록시 때문에 OpenAI 형식이 꼭 필요한 경우에만 이 모드를 사용하고, 네이티브 도구 호출 동작에 의존하지 마세요. - 대신 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**를 지원합 자동 검색된 모델의 경우, OpenClaw는 가능하면 Ollama가 보고한 컨텍스트 윈도우를 사용하고, 그렇지 않으면 OpenClaw가 사용하는 기본 Ollama 컨텍스트 윈도우로 대체합니다. - 명시적 provider 구성에서 `contextWindow`와 `maxTokens`를 재정의할 수 있습니다: + 명시적 provider config에서 `contextWindow`와 `maxTokens`를 재정의할 수 있습니다. ```json5 { @@ -374,7 +376,7 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합 - 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**를 지원합 - Ollama는 무료이며 로컬에서 실행되므로 모든 모델 비용은 $0으로 설정됩니다. 이는 자동 검색된 모델과 수동 정의된 모델 모두에 적용됩니다. + Ollama는 무료이며 로컬에서 실행되므로, 모든 모델 비용은 $0으로 설정됩니다. 이는 자동 검색된 모델과 수동으로 정의된 모델 모두에 적용됩니다. - 번들 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**를 지원합 - OpenClaw의 Ollama 통합은 기본적으로 **네이티브 Ollama API**(`/api/chat`)를 사용하며, 이는 스트리밍과 도구 호출을 동시에 완전히 지원합니다. 별도의 특별한 구성은 필요하지 않습니다. + OpenClaw의 Ollama 통합은 기본적으로 **네이티브 Ollama API**(`/api/chat`)를 사용하며, 이 방식은 스트리밍과 도구 호출을 동시에 완전히 지원합니다. 특별한 구성은 필요하지 않습니다. - OpenAI 호환 엔드포인트를 사용해야 하는 경우 위의 "레거시 OpenAI 호환 모드" 섹션을 참조하세요. 그 모드에서는 스트리밍과 도구 호출이 동시에 동작하지 않을 수 있습니다. + OpenAI 호환 엔드포인트를 사용해야 한다면, 위의 "레거시 OpenAI 호환 모드" 섹션을 참고하세요. 해당 모드에서는 스트리밍과 도구 호출이 동시에 동작하지 않을 수 있습니다. @@ -424,13 +426,13 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합 - 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**를 지원합 - - 모델이 목록에 없으면 로컬에서 모델을 pull하거나 `models.providers.ollama`에 명시적으로 정의하세요. + + 모델이 목록에 없으면, 모델을 로컬에서 pull하거나 `models.providers.ollama`에 명시적으로 정의하세요. ```bash ollama list # 설치된 항목 확인 @@ -451,10 +453,10 @@ OpenClaw는 번들 `web_search` provider로 **Ollama Web Search**를 지원합 - 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). -## 관련 +## 관련 항목 - 모든 provider, 모델 참조 및 장애 조치 동작 개요. + 모든 provider, 모델 ref, 장애 조치 동작 개요. - 모델 선택 및 구성 방법. + 모델을 선택하고 구성하는 방법. - + Ollama 기반 웹 검색의 전체 설정 및 동작 세부 정보. - 전체 구성 참조. + 전체 config 참조. diff --git a/docs/ko/reference/memory-config.md b/docs/ko/reference/memory-config.md index f8447ec1e..95b2bb3d1 100644 --- a/docs/ko/reference/memory-config.md +++ b/docs/ko/reference/memory-config.md @@ -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 | -`model` 또는 `outputDimensionality`를 변경하면 자동으로 전체 재인덱싱이 수행됩니다. +모델 또는 `outputDimensionality`를 변경하면 전체 재인덱싱이 자동으로 수행됩니다. --- @@ -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::`를 포함한 원시 키와 일치합니다. ### 인용 -`memory.citations`는 모든 백엔드에 적용됩니다: +`memory.citations`는 모든 백엔드에 적용됩니다. -| Value | Behavior | +| 값 | 동작 | | ---------------- | --------------------------------------------------- | -| `auto` (기본값) | 스니펫에 `Source: ` 푸터 포함 | -| `on` | 항상 푸터 포함 | -| `off` | 푸터 생략(path는 여전히 내부적으로 agent에 전달됨) | +| `auto` (기본값) | 스니펫에 `Source: ` 바닥글 포함 | +| `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 단계 정책과 임계값은 내부 동작이며 사용자 대상 구성 항목이 아닙니다. diff --git a/docs/ko/reference/wizard.md b/docs/ko/reference/wizard.md index 368a37578..df4ef12e4 100644 --- a/docs/ko/reference/wizard.md +++ b/docs/ko/reference/wizard.md @@ -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 모드) - - `~/.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도 제거) - - **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//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//agent/auth-profiles.json`에 저장됩니다(API 키 + OAuth). `~/.openclaw/credentials/oauth.json`은 레거시 가져오기 전용입니다. - 자세한 내용: [/concepts/oauth](/ko/concepts/oauth) - 헤드리스/서버 팁: 브라우저가 있는 머신에서 OAuth를 완료한 뒤, - 해당 agent의 `auth-profiles.json`(예: - `~/.openclaw/agents//agent/auth-profiles.json`, 또는 대응하는 + 헤드리스/서버 팁: 브라우저가 있는 장치에서 OAuth를 완료한 다음, + 해당 에이전트의 `auth-profiles.json`(예: + `~/.openclaw/agents//agent/auth-profiles.json` 또는 대응되는 `$OPENCLAW_STATE_DIR/...` 경로)을 gateway 호스트로 복사하세요. `credentials/oauth.json`은 레거시 가져오기 소스일 뿐입니다. - - - 기본값은 `~/.openclaw/workspace`입니다(변경 가능). - - agent 부트스트랩 ritual에 필요한 workspace 파일을 시드합니다. + + - 기본값은 `~/.openclaw/workspace`입니다(구성 가능). + - 에이전트 bootstrap ritual에 필요한 workspace 파일을 시드합니다. - 전체 workspace 레이아웃 + 백업 가이드: [Agent workspace](/ko/concepts/agent-workspace) - - 포트, 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가 필요합니다. + - 포트, 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 `. + - 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다. - `--gateway-token`과 함께 사용할 수 없습니다. - 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하세요. - - loopback이 아닌 bind는 여전히 인증이 필요합니다. + - loopback이 아닌 bind에도 여전히 인증이 필요합니다. - [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 `로 승인하거나 allowlist를 사용할 수 있습니다. + - DM 보안: 기본값은 pairing입니다. 첫 DM은 코드를 전송하며, `openclaw pairing approve `로 승인하거나 허용 목록을 사용할 수 있습니다. - - 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`. - + - macOS: LaunchAgent - - 로그인된 사용자 세션이 필요합니다. 헤드리스 환경에서는 사용자 지정 LaunchDaemon을 사용하세요(기본 제공되지 않음). + - 로그인된 사용자 세션이 필요합니다. 헤드리스의 경우 사용자 지정 LaunchDaemon을 사용하세요(기본 제공되지 않음). - Linux(및 WSL2를 통한 Windows): systemd 사용자 유닛 - - 온보딩은 로그아웃 후에도 Gateway가 계속 실행되도록 `loginctl enable-linger `를 활성화하려고 시도합니다. + - 온보딩은 로그아웃 후에도 Gateway가 계속 실행되도록 `loginctl enable-linger ` 활성화를 시도합니다. - 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 설치가 차단됩니다. - 필요하면 Gateway를 시작하고 `openclaw health`를 실행합니다. - - 팁: `openclaw status --deep`는 상태 출력에 라이브 gateway 상태 probe를 추가하며, 지원되는 경우 채널 probe도 포함합니다(reachable gateway 필요). + - 팁: `openclaw status --deep`는 상태 출력에 실시간 gateway 상태 프로브를 추가하며, 지원되는 경우 채널 프로브도 포함합니다(도달 가능한 gateway 필요). - 사용 가능한 Skills를 읽고 요구 사항을 확인합니다. - - 노드 매니저를 선택할 수 있습니다: **npm / pnpm** (bun은 권장되지 않음). - - 선택적 의존성을 설치합니다(일부는 macOS에서 Homebrew 사용). + - 노드 관리자 **npm / pnpm**을 선택하게 합니다(bun은 권장되지 않음). + - 선택적 종속성을 설치합니다(일부는 macOS에서 Homebrew 사용). - - 추가 기능용 iOS/Android/macOS 앱을 포함한 요약 + 다음 단계가 표시됩니다. + - 추가 기능을 위한 iOS/Android/macOS 앱을 포함해 요약과 다음 단계를 표시합니다. -GUI가 감지되지 않으면, 온보딩은 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 안내를 출력합니다. -Control UI 에셋이 없으면, 온보딩은 이를 빌드하려고 시도하며 폴백은 `pnpm ui:build`입니다(UI 의존성을 자동 설치). +GUI가 감지되지 않으면, 온보딩은 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 지침을 출력합니다. +Control UI 자산이 없으면 온보딩이 이를 빌드하려 시도하며, 대체 방법은 `pnpm ui:build`입니다(UI 종속성 자동 설치). ## 비대화형 모드 -온보딩을 자동화하거나 스크립트화하려면 `--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`는 함께 사용할 수 없습니다. -`--json`은 **비대화형 모드**를 의미하지 않습니다. 스크립트에서는 `--non-interactive`(및 `--workspace`)를 사용하세요. +`--json`은 비대화형 모드를 의미하지 않습니다. 스크립트에서는 `--non-interactive`(및 `--workspace`)를 사용하세요. -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//` 아래에 저장합니다. - 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//` 아래에 저장됩니다. 세션은 `~/.openclaw/agents//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) diff --git a/docs/ko/start/wizard-cli-reference.md b/docs/ko/start/wizard-cli-reference.md index 9b4b3164e..c977be14b 100644 --- a/docs/ko/start/wizard-cli-reference.md +++ b/docs/ko/start/wizard-cli-reference.md @@ -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에 연결되도록 구성합니다. 원격 호스트에는 아무것도 설치하거나 수정하지 않습니다. -## 로컬 흐름 세부 사항 +## 로컬 흐름 세부사항 - - - `~/.openclaw/openclaw.json`이 있으면 유지, 수정, 또는 재설정을 선택합니다. - - 마법사를 다시 실행해도 명시적으로 재설정을 선택하지 않는 한(또는 `--reset`을 전달하지 않는 한) 아무것도 지워지지 않습니다. - - CLI `--reset`의 기본값은 `config+creds+sessions`이며, 워크스페이스도 제거하려면 `--reset-scope full`을 사용하세요. - - config가 유효하지 않거나 레거시 키를 포함하고 있으면, 마법사는 중단하고 계속하기 전에 `openclaw doctor`를 실행하라고 요청합니다. - - 재설정은 `trash`를 사용하며 다음 범위를 제공합니다: - - config만 - - config + 자격 증명 + 세션 + + - `~/.openclaw/openclaw.json`이 있으면 Keep, Modify 또는 Reset을 선택합니다. + - 마법사를 다시 실행해도 명시적으로 Reset을 선택하지 않는 한(또는 `--reset`을 전달하지 않는 한) 아무것도 지워지지 않습니다. + - CLI `--reset`의 기본값은 `config+creds+sessions`이며, 워크스페이스까지 제거하려면 `--reset-scope full`을 사용하세요. + - 구성이 유효하지 않거나 레거시 키를 포함하면, 마법사는 중단하고 계속하기 전에 `openclaw doctor`를 실행하라고 요청합니다. + - Reset은 `trash`를 사용하며 다음 범위를 제공합니다. + - 구성만 + - 구성 + 자격 증명 + 세션 - 전체 재설정(워크스페이스도 제거) - - - 전체 옵션 매트릭스는 [Auth and model options](#auth-and-model-options)에 있습니다. + + - 전체 옵션 매트릭스는 [인증 및 모델 옵션](#auth-and-model-options)에 있습니다. - - 기본값은 `~/.openclaw/workspace`입니다(변경 가능). - - 최초 실행 bootstrap ritual에 필요한 워크스페이스 파일을 시드합니다. - - 워크스페이스 레이아웃: [Agent workspace](/ko/concepts/agent-workspace). + - 기본값은 `~/.openclaw/workspace`입니다(구성 가능). + - 첫 실행 부트스트랩 의식에 필요한 워크스페이스 파일을 시드합니다. + - 워크스페이스 레이아웃: [에이전트 워크스페이스](/ko/concepts/agent-workspace). - - 포트, bind, auth 모드, Tailscale 노출 여부를 묻습니다. - - 권장 사항: loopback에서도 토큰 auth를 활성화해 로컬 WS 클라이언트가 인증하도록 유지하세요. - - 토큰 모드에서 대화형 설정은 다음을 제공합니다: + - 포트, 바인드, 인증 모드, Tailscale 노출 여부를 묻습니다. + - 권장 사항: 로컬 WS 클라이언트도 인증해야 하므로 loopback만 사용하더라도 토큰 인증을 활성화한 상태로 유지하세요. + - 토큰 모드에서 대화형 설정은 다음을 제공합니다. - **일반 텍스트 토큰 생성/저장** (기본값) - **SecretRef 사용** (옵트인) - 비밀번호 모드에서도 대화형 설정은 일반 텍스트 또는 SecretRef 저장을 지원합니다. - 비대화형 토큰 SecretRef 경로: `--gateway-token-ref-env `. - - 온보딩 프로세스 환경에 비어 있지 않은 env var가 필요합니다. + - 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다. - `--gateway-token`과 함께 사용할 수 없습니다. - - 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 auth를 비활성화하세요. - - loopback이 아닌 bind에도 여전히 auth가 필요합니다. + - 모든 로컬 프로세스를 완전히 신뢰하는 경우에만 인증을 비활성화하세요. + - loopback이 아닌 바인드도 여전히 인증이 필요합니다. - [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 `로 승인하거나 allowlist를 사용할 수 있습니다. - macOS: LaunchAgent - - 로그인된 사용자 세션이 필요합니다. headless 환경에서는 커스텀 LaunchDaemon을 사용하세요(기본 제공되지 않음). + - 로그인된 사용자 세션이 필요합니다. 헤드리스 환경에서는 사용자 지정 LaunchDaemon을 사용하세요(기본 제공되지 않음). - Linux 및 WSL2를 통한 Windows: systemd 사용자 유닛 - - 마법사는 로그아웃 후에도 gateway가 유지되도록 `loginctl enable-linger `를 시도합니다. + - 마법사는 로그아웃 후에도 gateway가 계속 실행되도록 `loginctl enable-linger `를 시도합니다. - 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은 권장되지 않습니다. - 필요하면 gateway를 시작하고 `openclaw health`를 실행합니다. - - `openclaw status --deep`는 지원되는 경우 채널 프로브를 포함해 라이브 gateway 상태 프로브를 상태 출력에 추가합니다. + - `openclaw status --deep`는 지원되는 경우 채널 프로브를 포함한 라이브 gateway 상태 프로브를 상태 출력에 추가합니다. - 사용 가능한 Skills를 읽고 요구 사항을 확인합니다. - - node manager로 npm, pnpm, 또는 bun을 선택할 수 있습니다. + - 노드 관리자로 npm, pnpm 또는 bun을 선택할 수 있습니다. - 선택적 의존성을 설치합니다(일부는 macOS에서 Homebrew 사용). - - - iOS, Android, macOS 앱 옵션을 포함한 요약 및 다음 단계가 표시됩니다. + + - 요약 및 다음 단계(iOS, Android, macOS 앱 옵션 포함)를 제공합니다. -GUI가 감지되지 않으면 마법사는 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 안내를 출력합니다. -Control UI 자산이 없으면 마법사는 이를 빌드하려고 시도하며, 폴백은 `pnpm ui:build`입니다(UI 의존성 자동 설치). +GUI가 감지되지 않으면, 마법사는 브라우저를 여는 대신 Control UI용 SSH 포트 포워딩 지침을 출력합니다. +Control UI 자산이 없으면, 마법사는 이를 빌드하려고 시도합니다. 대체 경로는 `pnpm ui:build`이며(UI 의존성을 자동 설치함)입니다. -## 원격 모드 세부 사항 +## 원격 모드 세부사항 원격 모드는 이 컴퓨터가 다른 위치의 gateway에 연결되도록 구성합니다. @@ -121,145 +121,146 @@ Control UI 자산이 없으면 마법사는 이를 빌드하려고 시도하며, 설정하는 항목: - 원격 gateway URL (`ws://...`) -- 원격 gateway auth가 필요한 경우 토큰(권장) +- 원격 gateway 인증이 필요한 경우 토큰(권장) - gateway가 loopback 전용이면 SSH 터널링 또는 tailnet을 사용하세요. -- 탐지 힌트: +- 검색 힌트: - macOS: Bonjour (`dns-sd`) - Linux: Avahi (`avahi-browse`) -## Auth and model options +## 인증 및 모델 옵션 - 있으면 `ANTHROPIC_API_KEY`를 사용하고, 없으면 키를 입력받은 뒤 데몬에서 사용할 수 있도록 저장합니다. + `ANTHROPIC_API_KEY`가 있으면 이를 사용하고, 없으면 키를 요청한 뒤 데몬에서 사용할 수 있도록 저장합니다. `~/.codex/auth.json`이 있으면 마법사가 이를 재사용할 수 있습니다. 재사용된 Codex CLI 자격 증명은 계속 Codex CLI가 관리합니다. 만료되면 OpenClaw는 - 먼저 해당 소스를 다시 읽고, provider가 이를 갱신할 수 있으면 - 소유권을 가져오는 대신 갱신된 자격 증명을 다시 Codex 저장소에 기록합니다. + 먼저 해당 소스를 다시 읽고, 제공자가 이를 갱신할 수 있으면 + 자격 증명의 소유권을 가져오지 않고 갱신된 자격 증명을 다시 Codex 저장소에 기록합니다. - 브라우저 흐름; `code#state`를 붙여 넣습니다. + 브라우저 흐름이며 `code#state`를 붙여 넣습니다. 모델이 설정되지 않았거나 `openai/*`인 경우 `agents.defaults.model`을 `openai-codex/gpt-5.4`로 설정합니다. - 있으면 `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`로 설정합니다. - `XAI_API_KEY`를 입력받고 xAI를 모델 provider로 구성합니다. + `XAI_API_KEY`를 요청하고 xAI를 모델 제공자로 구성합니다. - `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). 키를 대신 저장합니다. - `AI_GATEWAY_API_KEY`를 입력받습니다. + `AI_GATEWAY_API_KEY`를 요청합니다. 자세한 내용: [Vercel AI Gateway](/ko/providers/vercel-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). - config가 자동으로 기록됩니다. 호스팅 기본값은 `MiniMax-M2.7`입니다. API 키 설정은 - `minimax/...`를 사용하고, OAuth 설정은 `minimax-portal/...`를 사용합니다. + 구성이 자동으로 기록됩니다. 호스팅 기본값은 `MiniMax-M2.7`이며, API 키 설정은 + `minimax/...`를 사용하고 OAuth 설정은 `minimax-portal/...`을 사용합니다. 자세한 내용: [MiniMax](/ko/providers/minimax). - 중국 또는 글로벌 엔드포인트의 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). - `SYNTHETIC_API_KEY`를 입력받습니다. + `SYNTHETIC_API_KEY`를 요청합니다. 자세한 내용: [Synthetic](/ko/providers/synthetic). - - 기본 URL(기본값 `http://127.0.0.1:11434`)을 입력받은 다음 Cloud + Local 또는 Local 모드를 제안합니다. - 사용 가능한 모델을 탐지하고 기본값을 제안합니다. + + 먼저 `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). - Moonshot(Kimi K2) 및 Kimi Coding config가 자동으로 기록됩니다. + Moonshot (Kimi K2) 및 Kimi Coding 구성은 자동으로 기록됩니다. 자세한 내용: [Moonshot AI (Kimi + Kimi Coding)](/ko/providers/moonshot). - - OpenAI 호환 및 Anthropic 호환 엔드포인트와 동작합니다. + + 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`) + - `--custom-compatibility ` (선택 사항, 기본값 `openai`) - auth를 구성하지 않은 상태로 둡니다. + 인증을 구성하지 않은 상태로 둡니다. 모델 동작: -- 탐지된 옵션에서 기본 모델을 선택하거나, provider와 모델을 수동으로 입력합니다. -- 온보딩이 provider auth 선택에서 시작되면 모델 선택기는 - 해당 provider를 자동으로 우선 적용합니다. Volcengine과 BytePlus의 경우 이 우선순위는 +- 감지된 옵션에서 기본 모델을 선택하거나, 제공자와 모델을 수동으로 입력합니다. +- 온보딩이 제공자 인증 선택에서 시작되면, 모델 선택기는 + 해당 제공자를 자동으로 우선시합니다. Volcengine 및 BytePlus의 경우, 동일한 우선순위가 해당 coding-plan 변형(`volcengine-plan/*`, - `byteplus-plan/*`)과도 일치합니다. -- 해당 선호 provider 필터 결과가 비어 있으면, 선택기는 모델이 없다고 표시하는 대신 - 전체 카탈로그로 폴백합니다. -- 마법사는 모델 검사를 실행하고 구성된 모델을 알 수 없거나 auth가 없으면 경고합니다. + `byteplus-plan/*`)에도 적용됩니다. +- 이 기본 제공자 필터의 결과가 비어 있으면, + 모델을 하나도 표시하지 않는 대신 전체 카탈로그로 대체합니다. +- 마법사는 모델 검사를 실행하고 구성된 모델을 알 수 없거나 인증이 누락된 경우 경고합니다. -자격 증명 및 프로필 경로: +자격 증명 및 profile 경로: -- Auth 프로필(API 키 + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` -- 레거시 OAuth import: `~/.openclaw/credentials/oauth.json` +- Auth profile(API 키 + OAuth): `~/.openclaw/agents//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..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..apiKey`를 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`로 저장합니다. + - 이 사용자 지정 제공자 경우에는 `--custom-api-key`를 사용하려면 `CUSTOM_API_KEY`가 설정되어 있어야 하며, 그렇지 않으면 온보딩이 즉시 실패합니다. +- Gateway 인증 자격 증명은 대화형 설정에서 일반 텍스트와 SecretRef 선택을 모두 지원합니다. + - 토큰 모드: **일반 텍스트 토큰 생성/저장** (기본값) 또는 **SecretRef 사용**. - 비밀번호 모드: 일반 텍스트 또는 SecretRef. - 비대화형 토큰 SecretRef 경로: `--gateway-token-ref-env `. -- 기존 일반 텍스트 설정은 변경 없이 계속 동작합니다. +- 기존 일반 텍스트 설정은 변경 없이 계속 작동합니다. -헤드리스 및 서버 팁: 브라우저가 있는 컴퓨터에서 OAuth를 완료한 다음 -해당 에이전트의 `auth-profiles.json`(예: -`~/.openclaw/agents//agent/auth-profiles.json`, 또는 해당하는 +헤드리스 및 서버 팁: 브라우저가 있는 컴퓨터에서 OAuth를 완료한 다음, 해당 에이전트의 `auth-profiles.json`(예: +`~/.openclaw/agents//agent/auth-profiles.json` 또는 일치하는 `$OPENCLAW_STATE_DIR/...` 경로)을 gateway 호스트로 복사하세요. `credentials/oauth.json`은 -레거시 import 소스일 뿐입니다. +레거시 가져오기 소스일 뿐입니다. ## 출력 및 내부 동작 @@ -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//` 아래에 저장됩니다. 세션은 `~/.openclaw/agents//sessions/` 아래에 저장됩니다. -일부 채널은 plugin으로 제공됩니다. 설정 중 선택하면 마법사는 -채널 구성을 진행하기 전에 plugin 설치(npm 또는 로컬 경로)를 묻습니다. +일부 채널은 Plugin으로 제공됩니다. 설정 중 선택하면 마법사는 +채널 구성을 시작하기 전에 Plugin 설치(npm 또는 로컬 경로)를 묻습니다. Gateway 마법사 RPC: @@ -303,15 +304,15 @@ Gateway 마법사 RPC: Signal 설정 동작: -- 적절한 릴리스 자산을 다운로드 -- `~/.openclaw/tools/signal-cli//` 아래에 저장 -- config에 `channels.signal.cliPath` 기록 -- JVM 빌드는 Java 21이 필요 -- 가능하면 네이티브 빌드를 사용 -- Windows는 WSL2를 사용하며 WSL 내부에서 Linux signal-cli 흐름을 따름 +- 적절한 릴리스 자산을 다운로드합니다 +- 이를 `~/.openclaw/tools/signal-cli//` 아래에 저장합니다 +- 구성에 `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)