diff --git a/docs/ko/channels/telegram.md b/docs/ko/channels/telegram.md index a63158ee6..2f9596b45 100644 --- a/docs/ko/channels/telegram.md +++ b/docs/ko/channels/telegram.md @@ -1,30 +1,30 @@ --- read_when: - - Telegram 기능 또는 webhook 작업 중 + - Telegram 기능 또는 Webhook 작업 중 summary: Telegram 봇 지원 상태, 기능 및 구성 title: Telegram x-i18n: - generated_at: "2026-04-05T12:38:31Z" + generated_at: "2026-04-20T06:05:30Z" model: gpt-5.4 provider: openai - source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477 source_path: channels/telegram.md workflow: 15 --- # Telegram (Bot API) -상태: grammY를 통한 봇 DM 및 그룹용 프로덕션 준비 완료. 롱 폴링이 기본 모드이며 webhook 모드는 선택 사항입니다. +상태: grammY를 통해 봇 DM 및 그룹에 대해 프로덕션 준비 완료입니다. Long polling이 기본 모드이며, Webhook 모드는 선택 사항입니다. - + Telegram의 기본 DM 정책은 페어링입니다. - + 채널 전반의 진단 및 복구 플레이북입니다. - - 전체 채널 config 패턴과 예시입니다. + + 전체 채널 구성 패턴 및 예제입니다. @@ -34,7 +34,7 @@ x-i18n: Telegram을 열고 **@BotFather**와 채팅하세요(핸들이 정확히 `@BotFather`인지 확인). - `/newbot`을 실행하고 안내를 따른 뒤 토큰을 저장하세요. + `/newbot`을 실행하고, 안내에 따라 진행한 뒤 토큰을 저장하세요. @@ -53,12 +53,12 @@ x-i18n: } ``` - 환경 변수 대체: `TELEGRAM_BOT_TOKEN=...` (기본 계정만). - Telegram은 `openclaw channels login telegram`을 사용하지 **않습니다**. config/env에 토큰을 구성한 뒤 gateway를 시작하세요. + 환경 변수 대체값: `TELEGRAM_BOT_TOKEN=...` (기본 계정만 해당). + Telegram은 `openclaw channels login telegram`을 사용하지 않습니다. config/env에 토큰을 설정한 다음 Gateway를 시작하세요. - + ```bash openclaw gateway @@ -71,33 +71,33 @@ openclaw pairing approve telegram - 그룹에 봇을 추가한 다음 액세스 모델에 맞게 `channels.telegram.groups`와 `groupPolicy`를 설정하세요. + 봇을 그룹에 추가한 다음, 접근 모델에 맞게 `channels.telegram.groups` 및 `groupPolicy`를 설정하세요. -토큰 해석 순서는 계정 인식을 지원합니다. 실제로는 config 값이 환경 변수 대체보다 우선하며, `TELEGRAM_BOT_TOKEN`은 기본 계정에만 적용됩니다. +토큰 확인 순서는 계정을 인식합니다. 실제로는 config 값이 환경 변수 대체값보다 우선하며, `TELEGRAM_BOT_TOKEN`은 기본 계정에만 적용됩니다. ## Telegram 측 설정 - Telegram 봇은 기본적으로 **개인정보 보호 모드**가 활성화되어 있어, 수신할 수 있는 그룹 메시지가 제한됩니다. + Telegram 봇은 기본적으로 **Privacy Mode**가 활성화되어 있어, 수신할 수 있는 그룹 메시지가 제한됩니다. - 봇이 모든 그룹 메시지를 봐야 한다면 다음 중 하나를 수행하세요. + 봇이 모든 그룹 메시지를 볼 수 있어야 한다면, 다음 중 하나를 수행하세요. - - `/setprivacy`로 개인정보 보호 모드를 비활성화하거나 + - `/setprivacy`를 통해 개인정보 보호 모드를 비활성화하거나 - 봇을 그룹 관리자로 설정합니다. - 개인정보 보호 모드를 전환한 경우, Telegram이 변경 사항을 적용할 수 있도록 각 그룹에서 봇을 제거했다가 다시 추가하세요. + 개인정보 보호 모드를 전환한 경우, Telegram이 변경 사항을 적용하도록 각 그룹에서 봇을 제거한 뒤 다시 추가하세요. 관리자 상태는 Telegram 그룹 설정에서 제어됩니다. - 관리자 봇은 모든 그룹 메시지를 수신하므로 항상 활성화된 그룹 동작에 유용합니다. + 관리자 봇은 모든 그룹 메시지를 받으므로, 항상 활성화된 그룹 동작에 유용합니다. @@ -109,30 +109,30 @@ openclaw pairing approve telegram -## 액세스 제어 및 활성화 +## 접근 제어 및 활성화 - `channels.telegram.dmPolicy`는 다이렉트 메시지 액세스를 제어합니다. + `channels.telegram.dmPolicy`는 다이렉트 메시지 접근을 제어합니다. - `pairing` (기본값) - - `allowlist` (`allowFrom`에 발신자 ID가 최소 하나 필요) + - `allowlist` (`allowFrom`에 최소 하나의 발신자 ID가 필요) - `open` (`allowFrom`에 `"*"` 포함 필요) - `disabled` - `channels.telegram.allowFrom`은 숫자형 Telegram 사용자 ID를 받습니다. `telegram:` / `tg:` 접두사는 허용되며 정규화됩니다. - 빈 `allowFrom`과 함께 `dmPolicy: "allowlist"`를 사용하면 모든 DM이 차단되며 config 유효성 검사에서 거부됩니다. - 온보딩은 `@username` 입력을 받아 숫자형 ID로 해석합니다. - 업그레이드 후 config에 `@username` allowlist 항목이 있다면, 이를 해석하려면 `openclaw doctor --fix`를 실행하세요(최선 시도 방식이며 Telegram 봇 토큰이 필요합니다). - 이전에 페어링 저장소 allowlist 파일에 의존했다면, `openclaw doctor --fix`가 allowlist 흐름에서 해당 항목을 `channels.telegram.allowFrom`으로 복구할 수 있습니다(예: `dmPolicy: "allowlist"`에 아직 명시적 ID가 없는 경우). + `channels.telegram.allowFrom`은 숫자형 Telegram 사용자 ID를 허용합니다. `telegram:` / `tg:` 접두사는 허용되며 정규화됩니다. + `allowFrom`이 비어 있는 `dmPolicy: "allowlist"`는 모든 DM을 차단하며 config 검증에서 거부됩니다. + 설정은 숫자형 사용자 ID만 요청합니다. + 업그레이드 후 config에 `@username` allowlist 항목이 포함되어 있다면, `openclaw doctor --fix`를 실행해 이를 해결하세요(최선 노력 방식이며 Telegram 봇 토큰이 필요합니다). + 이전에 pairing-store allowlist 파일에 의존했다면, `openclaw doctor --fix`가 allowlist 흐름에서 항목을 `channels.telegram.allowFrom`으로 복구할 수 있습니다(예: `dmPolicy: "allowlist"`에 아직 명시적 ID가 없는 경우). - 단일 소유자 봇의 경우, 이전 페어링 승인에 의존하는 대신 액세스 정책을 config에 안정적으로 유지하기 위해 명시적 숫자형 `allowFrom` ID와 함께 `dmPolicy: "allowlist"`를 사용하는 것을 권장합니다. + 단일 소유자 봇의 경우, 접근 정책을 이전 페어링 승인에 의존하지 않고 config에 지속적으로 유지하려면 명시적인 숫자형 `allowFrom` ID와 함께 `dmPolicy: "allowlist"`를 사용하는 것이 좋습니다. - 흔한 혼동: DM 페어링 승인은 "이 발신자가 어디서나 인증되었다"는 의미가 아닙니다. - 페어링은 DM 액세스만 부여합니다. 그룹 발신자 인증은 여전히 명시적 config allowlist에서 옵니다. - "한 번 인증되면 DM과 그룹 명령 모두 동작"하게 하려면 숫자형 Telegram 사용자 ID를 `channels.telegram.allowFrom`에 넣으세요. + 흔한 혼동: DM 페어링 승인은 “이 발신자가 어디서나 권한이 있다”는 뜻이 아닙니다. + 페어링은 DM 접근만 부여합니다. 그룹 발신자 권한은 여전히 명시적 config allowlist에서만 옵니다. + “한 번 권한을 받으면 DM과 그룹 명령이 모두 동작”하게 하려면, 숫자형 Telegram 사용자 ID를 `channels.telegram.allowFrom`에 넣으세요. - ### 내 Telegram 사용자 ID 찾기 + ### Telegram 사용자 ID 찾기 더 안전한 방법(서드파티 봇 없음): @@ -153,28 +153,28 @@ curl "https://api.telegram.org/bot/getUpdates" 두 가지 제어가 함께 적용됩니다. - 1. **어떤 그룹이 허용되는지** (`channels.telegram.groups`) + 1. **허용되는 그룹** (`channels.telegram.groups`) - `groups` config가 없는 경우: - - `groupPolicy: "open"`일 때: 어떤 그룹이든 그룹 ID 검사 통과 가능 - - `groupPolicy: "allowlist"`(기본값)일 때: `groups` 항목(또는 `"*"`)을 추가할 때까지 그룹 차단 - - `groups`가 구성된 경우: allowlist 역할 수행(명시적 ID 또는 `"*"`) + - `groupPolicy: "open"`이면: 어떤 그룹이든 그룹 ID 검사를 통과할 수 있습니다 + - `groupPolicy: "allowlist"`(기본값)이면: `groups` 항목(또는 `"*"`)을 추가할 때까지 그룹이 차단됩니다 + - `groups`가 구성된 경우: allowlist 역할을 합니다(명시적 ID 또는 `"*"`) - 2. **그룹에서 어떤 발신자가 허용되는지** (`channels.telegram.groupPolicy`) + 2. **그룹에서 허용되는 발신자** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (기본값) - `disabled` - `groupAllowFrom`은 그룹 발신자 필터링에 사용됩니다. 설정되지 않으면 Telegram은 `allowFrom`으로 대체합니다. + `groupAllowFrom`은 그룹 발신자 필터링에 사용됩니다. 설정되지 않은 경우 Telegram은 `allowFrom`으로 대체합니다. `groupAllowFrom` 항목은 숫자형 Telegram 사용자 ID여야 합니다(`telegram:` / `tg:` 접두사는 정규화됨). - Telegram 그룹 또는 슈퍼그룹 채팅 ID를 `groupAllowFrom`에 넣지 마세요. 음수 채팅 ID는 `channels.telegram.groups` 아래에 있어야 합니다. - 숫자가 아닌 항목은 발신자 인증에서 무시됩니다. - 보안 경계(`2026.2.25+`): 그룹 발신자 인증은 DM 페어링 저장소 승인을 **상속하지 않습니다**. - 페어링은 DM 전용으로 유지됩니다. 그룹의 경우 `groupAllowFrom` 또는 그룹별/토픽별 `allowFrom`을 설정하세요. - `groupAllowFrom`이 설정되지 않으면 Telegram은 페어링 저장소가 아니라 config의 `allowFrom`으로 대체합니다. - 단일 소유자 봇의 실용적인 패턴: 사용자 ID를 `channels.telegram.allowFrom`에 설정하고, `groupAllowFrom`은 비워 두며, 대상 그룹은 `channels.telegram.groups` 아래에서 허용하세요. - 런타임 참고: `channels.telegram`이 완전히 없으면, `channels.defaults.groupPolicy`가 명시적으로 설정되지 않은 한 런타임 기본값은 fail-closed `groupPolicy="allowlist"`입니다. + Telegram 그룹 또는 슈퍼그룹 채팅 ID를 `groupAllowFrom`에 넣지 마세요. 음수 채팅 ID는 `channels.telegram.groups` 아래에 들어가야 합니다. + 숫자가 아닌 항목은 발신자 권한 부여에서 무시됩니다. + 보안 경계 (`2026.2.25+`): 그룹 발신자 인증은 DM pairing-store 승인을 상속하지 **않습니다**. + 페어링은 계속 DM 전용입니다. 그룹의 경우 `groupAllowFrom` 또는 그룹별/토픽별 `allowFrom`을 설정하세요. + `groupAllowFrom`이 설정되지 않은 경우 Telegram은 pairing store가 아니라 config의 `allowFrom`으로 대체합니다. + 단일 소유자 봇을 위한 실용적인 패턴: 사용자 ID를 `channels.telegram.allowFrom`에 설정하고, `groupAllowFrom`은 비워 두며, 대상 그룹을 `channels.telegram.groups`에서 허용하세요. + 런타임 참고: `channels.telegram`이 완전히 누락된 경우, `channels.defaults.groupPolicy`가 명시적으로 설정되지 않았다면 런타임 기본값은 fail-closed `groupPolicy="allowlist"`입니다. - 예시: 특정 그룹 하나에서 모든 멤버 허용: + 예제: 특정 그룹 하나에서 아무 멤버나 허용: ```json5 { @@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 예시: 특정 그룹 하나에서 특정 사용자만 허용: + 예제: 특정 그룹 하나 안에서 특정 사용자만 허용: ```json5 { @@ -213,7 +213,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `-1001234567890` 같은 음수 Telegram 그룹 또는 슈퍼그룹 채팅 ID는 `channels.telegram.groups` 아래에 넣으세요. - 허용된 그룹 안에서 봇을 트리거할 수 있는 사람을 제한하려면 `8734062810` 같은 Telegram 사용자 ID를 `groupAllowFrom` 아래에 넣으세요. - - 허용된 그룹의 아무 멤버나 봇과 대화할 수 있게 하려면 `groupAllowFrom: ["*"]`를 사용하세요. + - 허용된 그룹의 어떤 멤버든 봇과 대화할 수 있게 하려면 `groupAllowFrom: ["*"]`만 사용하세요. @@ -221,10 +221,10 @@ curl "https://api.telegram.org/bot/getUpdates" 그룹 응답은 기본적으로 멘션이 필요합니다. - 멘션은 다음에서 올 수 있습니다. + 멘션은 다음 중 하나로 가능합니다. - - 기본 `@botusername` 멘션 - - 또는 다음의 멘션 패턴: + - 기본 `@botusername` 멘션 또는 + - 다음의 멘션 패턴: - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` @@ -233,9 +233,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 이 명령은 세션 상태만 업데이트합니다. 영구 저장에는 config를 사용하세요. + 이는 세션 상태만 업데이트합니다. 지속성을 원하면 config를 사용하세요. - 영구 config 예시: + 영구 config 예제: ```json5 { @@ -251,7 +251,7 @@ curl "https://api.telegram.org/bot/getUpdates" 그룹 채팅 ID 가져오기: - - 그룹 메시지를 `@userinfobot` / `@getidsbot`으로 전달 + - 그룹 메시지를 `@userinfobot` / `@getidsbot`에 전달 - 또는 `openclaw logs --follow`에서 `chat.id` 읽기 - 또는 Bot API `getUpdates` 검사 @@ -260,43 +260,43 @@ curl "https://api.telegram.org/bot/getUpdates" ## 런타임 동작 -- Telegram은 gateway 프로세스가 소유합니다. -- 라우팅은 결정적입니다. Telegram 인바운드 메시지는 Telegram으로 응답합니다(모델이 채널을 선택하지 않음). -- 인바운드 메시지는 응답 메타데이터와 미디어 플레이스홀더를 포함하는 공유 채널 envelope로 정규화됩니다. +- Telegram은 Gateway 프로세스가 소유합니다. +- 라우팅은 결정적입니다. Telegram 인바운드 응답은 Telegram으로 다시 응답합니다(모델이 채널을 선택하지 않음). +- 인바운드 메시지는 응답 메타데이터와 미디어 플레이스홀더를 포함한 공유 채널 envelope로 정규화됩니다. - 그룹 세션은 그룹 ID별로 격리됩니다. 포럼 토픽은 토픽 격리를 위해 `:topic:`를 덧붙입니다. -- DM 메시지는 `message_thread_id`를 포함할 수 있습니다. OpenClaw는 이를 스레드 인식 세션 키로 라우팅하고 응답 시 스레드 ID를 유지합니다. -- 롱 폴링은 채팅별/스레드별 순서를 보장하는 grammY runner를 사용합니다. 전체 runner sink 동시성은 `agents.defaults.maxConcurrent`를 사용합니다. -- Telegram Bot API에는 읽음 확인 지원이 없습니다(`sendReadReceipts`는 적용되지 않음). +- DM 메시지는 `message_thread_id`를 포함할 수 있습니다. OpenClaw는 이를 스레드 인식 세션 키로 라우팅하고 응답 시 스레드 ID를 보존합니다. +- Long polling은 채팅별/스레드별 시퀀싱을 갖춘 grammY runner를 사용합니다. 전체 runner sink 동시성은 `agents.defaults.maxConcurrent`를 사용합니다. +- Telegram Bot API는 읽음 확인을 지원하지 않습니다(`sendReadReceipts`는 적용되지 않음). ## 기능 참조 - - OpenClaw는 부분 응답을 실시간으로 스트리밍할 수 있습니다. + + OpenClaw는 실시간으로 부분 응답을 스트리밍할 수 있습니다. - 다이렉트 채팅: 미리보기 메시지 + `editMessageText` - 그룹/토픽: 미리보기 메시지 + `editMessageText` 요구 사항: - - `channels.telegram.streaming`이 `off | partial | block | progress`여야 합니다(기본값: `partial`) - - `progress`는 Telegram에서 `partial`로 매핑됩니다(채널 간 명명 호환성용) - - 레거시 `channels.telegram.streamMode`와 불리언 `streaming` 값은 자동 매핑됩니다 + - `channels.telegram.streaming`은 `off | partial | block | progress`입니다(기본값: `partial`) + - `progress`는 Telegram에서 `partial`로 매핑됩니다(채널 간 명명 호환성) + - 레거시 `channels.telegram.streamMode` 및 불리언 `streaming` 값은 자동 매핑됩니다 텍스트 전용 응답의 경우: - - DM: OpenClaw는 동일한 미리보기 메시지를 유지하고 최종 편집을 그 자리에서 수행합니다(두 번째 메시지 없음) - - 그룹/토픽: OpenClaw는 동일한 미리보기 메시지를 유지하고 최종 편집을 그 자리에서 수행합니다(두 번째 메시지 없음) + - DM: OpenClaw는 동일한 미리보기 메시지를 유지하고 마지막에 제자리 편집을 수행합니다(두 번째 메시지 없음) + - 그룹/토픽: OpenClaw는 동일한 미리보기 메시지를 유지하고 마지막에 제자리 편집을 수행합니다(두 번째 메시지 없음) - 복합 응답(예: 미디어 payload)의 경우, OpenClaw는 일반 최종 전송으로 대체한 후 미리보기 메시지를 정리합니다. + 복합 응답(예: 미디어 페이로드)의 경우, OpenClaw는 일반 최종 전송으로 대체한 다음 미리보기 메시지를 정리합니다. - 미리보기 스트리밍은 블록 스트리밍과 별개입니다. Telegram에 대해 블록 스트리밍이 명시적으로 활성화되면 OpenClaw는 이중 스트리밍을 피하기 위해 미리보기 스트림을 건너뜁니다. + 미리보기 스트리밍은 block 스트리밍과 별개입니다. Telegram에 대해 block 스트리밍이 명시적으로 활성화된 경우, OpenClaw는 이중 스트리밍을 피하기 위해 미리보기 스트림을 건너뜁니다. - 기본 초안 전송이 사용할 수 없거나 거부되면 OpenClaw는 자동으로 `sendMessage` + `editMessageText`로 대체합니다. + 기본 draft 전송을 사용할 수 없거나 거부되면, OpenClaw는 자동으로 `sendMessage` + `editMessageText`로 대체합니다. Telegram 전용 reasoning 스트림: - - `/reasoning stream`은 생성 중 reasoning을 실시간 미리보기로 보냅니다 + - `/reasoning stream`은 생성 중 reasoning을 라이브 미리보기에 보냅니다 - 최종 답변은 reasoning 텍스트 없이 전송됩니다 @@ -304,7 +304,7 @@ curl "https://api.telegram.org/bot/getUpdates" 아웃바운드 텍스트는 Telegram `parse_mode: "HTML"`을 사용합니다. - - Markdown 유사 텍스트는 Telegram에 안전한 HTML로 렌더링됩니다. + - Markdown 비슷한 텍스트는 Telegram 안전 HTML로 렌더링됩니다. - 원시 모델 HTML은 Telegram 파싱 실패를 줄이기 위해 이스케이프됩니다. - Telegram이 파싱된 HTML을 거부하면 OpenClaw는 일반 텍스트로 재시도합니다. @@ -315,7 +315,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram 명령 메뉴 등록은 시작 시 `setMyCommands`로 처리됩니다. - 기본 네이티브 명령: + 기본 기본값: - `commands.native: "auto"`는 Telegram에 대해 기본 명령을 활성화합니다 @@ -327,7 +327,7 @@ curl "https://api.telegram.org/bot/getUpdates" telegram: { customCommands: [ { command: "backup", description: "Git 백업" }, - { command: "generate", description: "이미지 생성" }, + { command: "generate", description: "이미지 만들기" }, ], }, }, @@ -336,40 +336,40 @@ curl "https://api.telegram.org/bot/getUpdates" 규칙: - - 이름은 정규화됩니다(앞의 `/` 제거, 소문자화) - - 유효 패턴: `a-z`, `0-9`, `_`, 길이 `1..32` + - 이름은 정규화됩니다(선행 `/` 제거, 소문자화) + - 유효한 패턴: `a-z`, `0-9`, `_`, 길이 `1..32` - 사용자 지정 명령은 기본 명령을 재정의할 수 없습니다 - 충돌/중복은 건너뛰고 로그에 기록됩니다 참고: - - 사용자 지정 명령은 메뉴 항목일 뿐이며 동작을 자동 구현하지 않습니다 - - plugin/Skills 명령은 Telegram 메뉴에 표시되지 않아도 직접 입력하면 여전히 동작할 수 있습니다 + - 사용자 지정 명령은 메뉴 항목일 뿐이며, 동작을 자동 구현하지는 않습니다 + - plugin/Skills 명령은 Telegram 메뉴에 표시되지 않아도 입력하면 여전히 동작할 수 있습니다 - 네이티브 명령이 비활성화되면 기본 명령은 제거됩니다. 사용자 지정/plugin 명령은 구성된 경우 여전히 등록될 수 있습니다. + 기본 명령이 비활성화되면 내장 명령은 제거됩니다. 사용자 지정/plugin 명령은 구성된 경우 여전히 등록될 수 있습니다. 일반적인 설정 실패: - - `setMyCommands failed`와 함께 `BOT_COMMANDS_TOO_MUCH`가 표시되면, 잘라낸 후에도 Telegram 메뉴가 여전히 넘친다는 뜻입니다. plugin/skill/사용자 지정 명령을 줄이거나 `channels.telegram.commands.native`를 비활성화하세요. - - `setMyCommands failed`와 함께 네트워크/fetch 오류가 표시되면 보통 `api.telegram.org`에 대한 아웃바운드 DNS/HTTPS가 차단된 것입니다. + - `BOT_COMMANDS_TOO_MUCH`와 함께 `setMyCommands failed`가 발생하면, 트리밍 후에도 Telegram 메뉴가 여전히 넘친다는 뜻입니다. plugin/Skills/사용자 지정 명령을 줄이거나 `channels.telegram.commands.native`를 비활성화하세요. + - 네트워크/fetch 오류와 함께 `setMyCommands failed`가 발생하면 일반적으로 `api.telegram.org`에 대한 아웃바운드 DNS/HTTPS가 차단된 것입니다. - ### 장치 페어링 명령 (`device-pair` plugin) + ### 장치 페어링 명령 (`device-pair` Plugin) - `device-pair` plugin이 설치된 경우: + `device-pair` Plugin이 설치되어 있으면: 1. `/pair`가 설정 코드를 생성합니다 2. iOS 앱에 코드를 붙여넣습니다 - 3. `/pair pending`이 대기 중 요청을 나열합니다(역할/범위 포함) + 3. `/pair pending`이 대기 중인 요청 목록을 표시합니다(역할/스코프 포함) 4. 요청을 승인합니다: - - 명시적 승인에는 `/pair approve ` - - 대기 중 요청이 하나뿐이면 `/pair approve` - - 가장 최근 요청에는 `/pair approve latest` + - 명시적 승인의 경우 `/pair approve ` + - 대기 중인 요청이 하나뿐인 경우 `/pair approve` + - 가장 최근 요청의 경우 `/pair approve latest` - 설정 코드는 짧은 수명의 bootstrap 토큰을 포함합니다. 내장 bootstrap handoff는 기본 노드 토큰을 `scopes: []`로 유지합니다. handoff된 operator 토큰은 `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` 범위로 제한됩니다. Bootstrap 범위 검사는 역할 접두사를 사용하므로, 해당 operator allowlist는 operator 요청만 충족하며 비-operator 역할은 여전히 자체 역할 접두사 아래 범위가 필요합니다. + 설정 코드는 수명이 짧은 bootstrap 토큰을 포함합니다. 내장 bootstrap handoff는 기본 Node 토큰을 `scopes: []`로 유지합니다. handoff된 operator 토큰은 `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`로만 제한됩니다. Bootstrap 스코프 검사는 역할 접두사를 사용하므로, 해당 operator allowlist는 operator 요청에만 적용되며, operator가 아닌 역할은 여전히 자신의 역할 접두사 아래 스코프가 필요합니다. - 장치가 변경된 인증 세부 정보(예: 역할/범위/공개 키)로 재시도하면 이전 대기 요청은 대체되고 새 요청은 다른 `requestId`를 사용합니다. 승인 전에 `/pair pending`을 다시 실행하세요. + 장치가 변경된 인증 세부 정보(예: 역할/스코프/공개 키)로 재시도하면, 이전 대기 요청은 대체되며 새 요청은 다른 `requestId`를 사용합니다. 승인 전에 `/pair pending`을 다시 실행하세요. - 자세한 내용: [페어링](/channels/pairing#pair-via-telegram-recommended-for-ios). + 자세한 내용: [페어링](/ko/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -416,7 +416,7 @@ curl "https://api.telegram.org/bot/getUpdates" 레거시 `capabilities: ["inlineButtons"]`는 `inlineButtons: "all"`로 매핑됩니다. - 메시지 작업 예시: + 메시지 작업 예제: ```json5 { @@ -434,13 +434,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 콜백 클릭은 텍스트로 agent에 전달됩니다: + 콜백 클릭은 에이전트에 텍스트로 전달됩니다: `callback_data: ` - - Telegram 도구 작업은 다음을 포함합니다. + + Telegram 도구 작업에는 다음이 포함됩니다: - `sendMessage` (`to`, `content`, 선택적 `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) @@ -448,29 +448,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage` (`chatId`, `messageId`, `content`) - `createForumTopic` (`chatId`, `name`, 선택적 `iconColor`, `iconCustomEmojiId`) - 채널 메시지 작업은 사용하기 쉬운 별칭을 노출합니다(`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + 채널 메시지 작업은 사용하기 쉬운 별칭을 제공합니다(`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - 게이팅 제어: + 제어 게이트: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (기본값: 비활성화) - 참고: `edit`와 `topic-create`는 현재 기본적으로 활성화되어 있으며 별도의 `channels.telegram.actions.*` 토글이 없습니다. - 런타임 전송은 활성 config/secrets 스냅샷(시작/리로드 시점)을 사용하므로, 작업 경로는 전송마다 임시 SecretRef 재해석을 수행하지 않습니다. + 참고: `edit` 및 `topic-create`는 현재 기본적으로 활성화되어 있으며 별도의 `channels.telegram.actions.*` 토글이 없습니다. + 런타임 전송은 활성 config/secrets 스냅샷(시작/리로드 시점)을 사용하므로, 작업 경로는 전송마다 임시 SecretRef 재확인을 수행하지 않습니다. - 반응 제거 의미 체계: [/tools/reactions](/tools/reactions) + 반응 제거 의미 체계: [/tools/reactions](/ko/tools/reactions) - Telegram은 생성된 출력에서 명시적 응답 스레딩 태그를 지원합니다. + Telegram은 생성된 출력에서 명시적 응답 스레딩 태그를 지원합니다: - - `[[reply_to_current]]`는 트리거한 메시지에 응답합니다 - - `[[reply_to:]]`는 특정 Telegram 메시지 ID에 응답합니다 + - `[[reply_to_current]]`는 트리거한 메시지에 답장합니다 + - `[[reply_to:]]`는 특정 Telegram 메시지 ID에 답장합니다 - `channels.telegram.replyToMode`는 처리 방식을 제어합니다. + `channels.telegram.replyToMode`는 처리 방식을 제어합니다: - `off` (기본값) - `first` @@ -484,11 +484,11 @@ curl "https://api.telegram.org/bot/getUpdates" 포럼 슈퍼그룹: - 토픽 세션 키는 `:topic:`를 덧붙입니다 - - 응답과 입력 중 표시는 토픽 스레드를 대상으로 합니다 + - 응답 및 입력 중 표시 대상은 해당 토픽 스레드입니다 - 토픽 config 경로: `channels.telegram.groups..topics.` - 일반 토픽(`threadId=1`) 특수 사례: + 일반 토픽(`threadId=1`) 특수 처리: - 메시지 전송은 `message_thread_id`를 생략합니다(Telegram은 `sendMessage(...thread_id=1)`을 거부함) - 입력 중 동작에는 여전히 `message_thread_id`가 포함됩니다 @@ -496,7 +496,7 @@ curl "https://api.telegram.org/bot/getUpdates" 토픽 상속: 토픽 항목은 재정의되지 않는 한 그룹 설정을 상속합니다(`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId`는 토픽 전용이며 그룹 기본값에서 상속되지 않습니다. - **토픽별 agent 라우팅**: 각 토픽은 토픽 config에서 `agentId`를 설정하여 다른 agent로 라우팅할 수 있습니다. 이를 통해 각 토픽은 자체 격리된 workspace, 메모리, 세션을 가질 수 있습니다. 예시: + **토픽별 에이전트 라우팅**: 각 토픽은 토픽 config에서 `agentId`를 설정하여 서로 다른 에이전트로 라우팅할 수 있습니다. 이를 통해 각 토픽은 고유하게 격리된 워크스페이스, 메모리, 세션을 가집니다. 예시: ```json5 { @@ -505,9 +505,9 @@ curl "https://api.telegram.org/bot/getUpdates" groups: { "-1001234567890": { topics: { - "1": { agentId: "main" }, // General topic → main agent - "3": { agentId: "zu" }, // Dev topic → zu agent - "5": { agentId: "coder" } // Code review → coder agent + "1": { agentId: "main" }, // 일반 토픽 → main 에이전트 + "3": { agentId: "zu" }, // 개발 토픽 → zu 에이전트 + "5": { agentId: "coder" } // 코드 리뷰 → coder 에이전트 } } } @@ -516,11 +516,11 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 각 토픽은 다음과 같은 자체 세션 키를 갖게 됩니다: `agent:zu:telegram:group:-1001234567890:topic:3` + 그러면 각 토픽은 자체 세션 키를 가집니다: `agent:zu:telegram:group:-1001234567890:topic:3` - **영구 ACP 토픽 바인딩**: 포럼 토픽은 최상위 타입 지정 ACP 바인딩을 통해 ACP harness 세션을 고정할 수 있습니다. + **지속형 ACP 토픽 바인딩**: 포럼 토픽은 최상위 타입 지정 ACP 바인딩을 통해 ACP harness 세션을 고정할 수 있습니다: - - `type: "acp"` 및 `match.channel: "telegram"`이 있는 `bindings[]` + - `bindings[]`에서 `type: "acp"` 및 `match.channel: "telegram"` 사용 예시: @@ -569,23 +569,23 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 현재 이는 그룹 및 슈퍼그룹의 포럼 토픽에 한정됩니다. + 이는 현재 그룹 및 슈퍼그룹의 포럼 토픽에 한해 적용됩니다. - **채팅에서 스레드 바인딩 ACP 생성**: + **채팅에서 시작하는 스레드 바운드 ACP 생성**: - `/acp spawn --thread here|auto`는 현재 Telegram 토픽을 새 ACP 세션에 바인딩할 수 있습니다. - - 후속 토픽 메시지는 바인딩된 ACP 세션으로 직접 라우팅됩니다(`/acp steer` 불필요). - - OpenClaw는 성공적으로 바인딩한 후 생성 확인 메시지를 토픽 내에 고정합니다. + - 이후 토픽 메시지는 바인딩된 ACP 세션으로 직접 라우팅됩니다(`/acp steer` 불필요). + - OpenClaw는 바인딩이 성공하면 생성 확인 메시지를 해당 토픽에 고정합니다. - `channels.telegram.threadBindings.spawnAcpSessions=true`가 필요합니다. - 템플릿 컨텍스트에는 다음이 포함됩니다. + 템플릿 컨텍스트에는 다음이 포함됩니다: - `MessageThreadId` - `IsForum` DM 스레드 동작: - - `message_thread_id`가 있는 개인 채팅은 DM 라우팅을 유지하지만 스레드 인식 세션 키/응답 대상을 사용합니다. + - `message_thread_id`가 있는 비공개 채팅은 DM 라우팅을 유지하지만 스레드 인식 세션 키/응답 대상을 사용합니다. @@ -595,9 +595,9 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram은 음성 노트와 오디오 파일을 구분합니다. - 기본값: 오디오 파일 동작 - - agent 응답에 `[[audio_as_voice]]` 태그를 넣으면 음성 노트 전송 강제 + - 에이전트 응답에 `[[audio_as_voice]]` 태그를 넣으면 음성 노트 전송을 강제합니다 - 메시지 작업 예시: + 메시지 작업 예제: ```json5 { @@ -613,7 +613,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram은 비디오 파일과 비디오 노트를 구분합니다. - 메시지 작업 예시: + 메시지 작업 예제: ```json5 { @@ -625,7 +625,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 비디오 노트는 캡션을 지원하지 않으므로, 제공된 메시지 텍스트는 별도로 전송됩니다. + 비디오 노트는 캡션을 지원하지 않습니다. 제공된 메시지 텍스트는 별도로 전송됩니다. ### 스티커 @@ -647,7 +647,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 스티커는 반복적인 vision 호출을 줄이기 위해 가능할 때 한 번 설명하고 캐시됩니다. + 스티커는 가능한 경우 한 번만 설명되고 캐시되어 반복적인 비전 호출을 줄입니다. 스티커 작업 활성화: @@ -688,38 +688,38 @@ curl "https://api.telegram.org/bot/getUpdates" - Telegram 반응은 `message_reaction` 업데이트로 도착합니다(메시지 payload와 별개). + Telegram 반응은 `message_reaction` 업데이트로 도착합니다(메시지 페이로드와 별도). - 활성화되면 OpenClaw는 다음과 같은 시스템 이벤트를 큐에 넣습니다. + 활성화되면 OpenClaw는 다음과 같은 시스템 이벤트를 큐에 넣습니다: - - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` + - `Telegram 반응 추가됨: 👍 by Alice (@alice) on msg 42` - config: + Config: - `channels.telegram.reactionNotifications`: `off | own | all` (기본값: `own`) - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (기본값: `minimal`) 참고: - - `own`은 봇이 보낸 메시지에 대한 사용자 반응만 의미합니다(전송된 메시지 캐시를 통한 최선 시도). - - 반응 이벤트는 여전히 Telegram 액세스 제어(`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`)를 따르며, 권한 없는 발신자는 버려집니다. - - Telegram은 반응 업데이트에 스레드 ID를 제공하지 않습니다. - - 비포럼 그룹은 그룹 채팅 세션으로 라우팅 - - 포럼 그룹은 정확한 원래 토픽이 아니라 그룹 일반 토픽 세션(`:topic:1`)으로 라우팅 + - `own`은 봇이 보낸 메시지에 대한 사용자 반응만 의미합니다(전송 메시지 캐시를 통한 최선 노력). + - 반응 이벤트는 여전히 Telegram 접근 제어(`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`)를 따릅니다. 권한이 없는 발신자는 버려집니다. + - Telegram은 반응 업데이트에서 스레드 ID를 제공하지 않습니다. + - 비포럼 그룹은 그룹 채팅 세션으로 라우팅됩니다 + - 포럼 그룹은 정확한 원래 토픽이 아니라 그룹 일반 토픽 세션(`:topic:1`)으로 라우팅됩니다 - 폴링/webhook용 `allowed_updates`에는 `message_reaction`이 자동으로 포함됩니다. + polling/Webhook용 `allowed_updates`에는 `message_reaction`이 자동으로 포함됩니다. - + `ackReaction`은 OpenClaw가 인바운드 메시지를 처리하는 동안 확인 이모지를 보냅니다. - 해석 순서: + 확인 순서: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - agent identity 이모지 대체(`agents.list[].identity.emoji`, 없으면 "👀") + - 에이전트 정체성 이모지 대체값 (`agents.list[].identity.emoji`, 없으면 "👀") 참고: @@ -731,7 +731,7 @@ curl "https://api.telegram.org/bot/getUpdates" 채널 config 쓰기는 기본적으로 활성화되어 있습니다(`configWrites !== false`). - Telegram 트리거 쓰기에는 다음이 포함됩니다. + Telegram 트리거 쓰기에는 다음이 포함됩니다: - `channels.telegram.groups`를 업데이트하기 위한 그룹 마이그레이션 이벤트(`migrate_to_chat_id`) - `/config set` 및 `/config unset`(명령 활성화 필요) @@ -750,45 +750,45 @@ curl "https://api.telegram.org/bot/getUpdates" - - 기본값: 롱 폴링. + + 기본값: Long polling. - webhook 모드: + Webhook 모드: - `channels.telegram.webhookUrl` 설정 - - `channels.telegram.webhookSecret` 설정(webhook URL이 설정된 경우 필수) + - `channels.telegram.webhookSecret` 설정(`webhookUrl`이 설정된 경우 필수) - 선택적 `channels.telegram.webhookPath` (기본값 `/telegram-webhook`) - 선택적 `channels.telegram.webhookHost` (기본값 `127.0.0.1`) - 선택적 `channels.telegram.webhookPort` (기본값 `8787`) - webhook 모드의 기본 로컬 리스너는 `127.0.0.1:8787`에 바인딩됩니다. + Webhook 모드의 기본 로컬 리스너는 `127.0.0.1:8787`에 바인딩됩니다. - 공개 엔드포인트가 다르면 앞에 reverse proxy를 두고 `webhookUrl`을 공개 URL로 지정하세요. - 외부 인그레스가 의도적으로 필요한 경우 `webhookHost`(예: `0.0.0.0`)를 설정하세요. + 공개 엔드포인트가 다르다면, 앞단에 reverse proxy를 두고 `webhookUrl`을 공개 URL로 지정하세요. + 의도적으로 외부 인바운드가 필요할 때는 `webhookHost`(예: `0.0.0.0`)를 설정하세요. - - `channels.telegram.textChunkLimit` 기본값은 4000입니다. - - `channels.telegram.chunkMode="newline"`은 길이 기준 분할 전에 문단 경계(빈 줄)를 우선합니다. - - `channels.telegram.mediaMaxMb`(기본값 100)는 인바운드 및 아웃바운드 Telegram 미디어 크기를 제한합니다. - - `channels.telegram.timeoutSeconds`는 Telegram API 클라이언트 타임아웃을 재정의합니다(설정하지 않으면 grammY 기본값 적용). - - 그룹 컨텍스트 기록은 `channels.telegram.historyLimit` 또는 `messages.groupChat.historyLimit`(기본값 50)을 사용하며, `0`이면 비활성화됩니다. - - 응답/인용/전달 보조 컨텍스트는 현재 수신된 그대로 전달됩니다. - - Telegram allowlist는 주로 누가 agent를 트리거할 수 있는지 제어하며, 완전한 보조 컨텍스트 redaction 경계는 아닙니다. + - `channels.telegram.textChunkLimit`의 기본값은 4000입니다. + - `channels.telegram.chunkMode="newline"`은 길이 분할 전에 문단 경계(빈 줄)를 우선합니다. + - `channels.telegram.mediaMaxMb`(기본값 100)는 인바운드 및 아웃바운드 Telegram 미디어 크기 상한을 설정합니다. + - `channels.telegram.timeoutSeconds`는 Telegram API 클라이언트 타임아웃을 재정의합니다(설정되지 않으면 grammY 기본값 적용). + - 그룹 컨텍스트 기록은 `channels.telegram.historyLimit` 또는 `messages.groupChat.historyLimit`을 사용합니다(기본값 50). `0`은 비활성화입니다. + - reply/quote/forward 보조 컨텍스트는 현재 수신된 그대로 전달됩니다. + - Telegram allowlist는 주로 누가 에이전트를 트리거할 수 있는지 제어하며, 전체 보조 컨텍스트 마스킹 경계는 아닙니다. - DM 기록 제어: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - `channels.telegram.retry` config는 복구 가능한 아웃바운드 API 오류에 대해 Telegram 전송 헬퍼(CLI/tools/actions)에 적용됩니다. - CLI 전송 대상은 숫자형 chat ID 또는 username일 수 있습니다: + CLI 전송 대상은 숫자형 채팅 ID 또는 사용자 이름일 수 있습니다: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Telegram 투표는 `openclaw message poll`을 사용하며 포럼 토픽을 지원합니다: + Telegram poll은 `openclaw message poll`을 사용하며 포럼 토픽을 지원합니다: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -798,7 +798,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Telegram 전용 투표 플래그: + Telegram 전용 poll 플래그: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` @@ -808,62 +808,67 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ Telegram 전송은 다음도 지원합니다: - `channels.telegram.capabilities.inlineButtons`가 허용할 때 인라인 키보드용 `--buttons` - - 아웃바운드 이미지와 GIF를 압축 사진 또는 애니메이션 미디어 업로드 대신 문서로 보내기 위한 `--force-document` + - 아웃바운드 이미지와 GIF를 압축된 사진 또는 애니메이션 미디어 업로드 대신 문서로 전송하는 `--force-document` - 작업 게이팅: + 작업 게이트: - - `channels.telegram.actions.sendMessage=false`는 투표를 포함한 아웃바운드 Telegram 메시지를 비활성화합니다 - - `channels.telegram.actions.poll=false`는 일반 전송은 유지한 채 Telegram 투표 생성을 비활성화합니다 + - `channels.telegram.actions.sendMessage=false`는 poll을 포함한 아웃바운드 Telegram 메시지를 비활성화합니다 + - `channels.telegram.actions.poll=false`는 일반 전송은 유지하면서 Telegram poll 생성을 비활성화합니다 - - Telegram은 승인자 DM에서 exec 승인을 지원하며, 선택적으로 원래 채팅 또는 토픽에 승인 프롬프트를 게시할 수 있습니다. + + Telegram은 승인자 DM에서 exec 승인을 지원하며, 선택적으로 원래 채팅 또는 토픽에도 승인 프롬프트를 게시할 수 있습니다. - config 경로: + Config 경로: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers` (선택 사항. 가능하면 `allowFrom` 및 direct `defaultTo`에서 추론된 숫자형 소유자 ID로 대체) + - `channels.telegram.execApprovals.approvers` (선택 사항. 가능하면 `allowFrom` 및 직접 메시지 `defaultTo`에서 추론한 숫자형 소유자 ID로 대체) - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, 기본값: `dm`) - `agentFilter`, `sessionFilter` - 승인자는 숫자형 Telegram 사용자 ID여야 합니다. `enabled`가 설정되지 않았거나 `"auto"`이고, `execApprovals.approvers` 또는 계정의 숫자형 소유자 config(`allowFrom` 및 direct-message `defaultTo`)에서 최소 하나의 승인자를 해석할 수 있으면 Telegram은 기본 exec 승인을 자동 활성화합니다. Telegram을 기본 승인 클라이언트로 명시적으로 비활성화하려면 `enabled: false`를 설정하세요. 그렇지 않으면 승인 요청은 다른 구성된 승인 경로 또는 exec 승인 대체 정책으로 폴백됩니다. + 승인자는 숫자형 Telegram 사용자 ID여야 합니다. `enabled`가 설정되지 않았거나 `"auto"`이고, `execApprovals.approvers` 또는 계정의 숫자형 소유자 config(`allowFrom` 및 직접 메시지 `defaultTo`)에서 최소 한 명의 승인자를 확인할 수 있으면 Telegram은 기본 exec 승인을 자동 활성화합니다. Telegram을 기본 승인 클라이언트로 명시적으로 비활성화하려면 `enabled: false`를 설정하세요. 그렇지 않으면 승인 요청은 다른 구성된 승인 경로 또는 exec 승인 대체 정책으로 넘어갑니다. - Telegram은 다른 채팅 채널이 사용하는 공유 승인 버튼도 렌더링합니다. 기본 Telegram 어댑터는 주로 승인자 DM 라우팅, 채널/토픽 팬아웃, 전송 전 입력 중 힌트를 추가합니다. - 이러한 버튼이 있으면 그것이 기본 승인 UX이며, OpenClaw는 도구 결과가 채팅 승인을 사용할 수 없거나 수동 승인이 유일한 경로라고 말할 때만 수동 `/approve` 명령을 포함해야 합니다. + Telegram은 다른 채팅 채널에서 사용하는 공통 승인 버튼도 렌더링합니다. 기본 Telegram 어댑터는 주로 승인자 DM 라우팅, 채널/토픽 팬아웃, 전송 전 입력 중 힌트를 추가합니다. + 이러한 버튼이 있을 때는 그것이 기본 승인 UX가 되며, OpenClaw는 + 도구 결과에서 채팅 승인을 사용할 수 없거나 수동 승인이 유일한 경로라고 + 표시하는 경우에만 수동 `/approve` 명령을 포함해야 합니다. 전송 규칙: - - `target: "dm"`은 해석된 승인자 DM으로만 승인 프롬프트를 보냅니다 - - `target: "channel"`은 원래 Telegram 채팅/토픽으로 프롬프트를 다시 보냅니다 - - `target: "both"`는 승인자 DM과 원래 채팅/토픽 모두에 보냅니다 + - `target: "dm"`은 확인된 승인자 DM으로만 승인 프롬프트를 보냅니다 + - `target: "channel"`은 프롬프트를 원래 Telegram 채팅/토픽으로 다시 보냅니다 + - `target: "both"`는 승인자 DM과 원래 채팅/토픽 모두로 보냅니다 - 해석된 승인자만 승인 또는 거부할 수 있습니다. 비승인자는 `/approve`를 사용할 수 없고 Telegram 승인 버튼도 사용할 수 없습니다. + 확인된 승인자만 승인 또는 거부할 수 있습니다. 승인자가 아닌 사용자는 `/approve`를 사용할 수 없고 Telegram 승인 버튼도 사용할 수 없습니다. - 승인 해석 동작: + 승인 확인 동작: - - `plugin:` 접두사가 있는 ID는 항상 plugin 승인으로 해석됩니다. + - `plugin:` 접두사가 붙은 ID는 항상 plugin 승인을 통해 확인됩니다. - 다른 승인 ID는 먼저 `exec.approval.resolve`를 시도합니다. - - Telegram이 plugin 승인에도 허용되어 있고 gateway가 exec 승인이 알 수 없거나 만료되었다고 말하면, Telegram은 한 번 `plugin.approval.resolve`를 통해 재시도합니다. - - 실제 exec 승인 거부/오류는 자동으로 plugin 승인 해석으로 넘어가지 않습니다. + - Telegram도 plugin 승인에 대해 권한이 있고 Gateway가 + exec 승인이 알 수 없거나 만료되었다고 응답하면, Telegram은 + `plugin.approval.resolve`를 통해 한 번 재시도합니다. + - 실제 exec 승인 거부/오류는 자동으로 plugin + 승인 확인으로 넘어가지 않습니다. - 채널 전송은 채팅에 명령 텍스트를 표시하므로, `channel` 또는 `both`는 신뢰할 수 있는 그룹/토픽에서만 활성화하세요. 포럼 토픽에 프롬프트가 도착하면 OpenClaw는 승인 프롬프트와 승인 후 후속 메시지 모두에 대해 해당 토픽을 유지합니다. Exec 승인의 기본 만료 시간은 30분입니다. + 채널 전송은 채팅에 명령 텍스트를 표시하므로, `channel` 또는 `both`는 신뢰할 수 있는 그룹/토픽에서만 활성화하세요. 프롬프트가 포럼 토픽에 도착하면, OpenClaw는 승인 프롬프트와 승인 후 후속 메시지 모두에서 해당 토픽을 유지합니다. exec 승인의 기본 만료 시간은 30분입니다. - 인라인 승인 버튼은 또한 `channels.telegram.capabilities.inlineButtons`가 대상 표면(`dm`, `group`, 또는 `all`)을 허용하는지에 따라 달라집니다. + 인라인 승인 버튼도 `channels.telegram.capabilities.inlineButtons`가 대상 영역(`dm`, `group`, `all`)을 허용해야 합니다. - 관련 문서: [Exec 승인](/tools/exec-approvals) + 관련 문서: [Exec 승인](/ko/tools/exec-approvals) ## 오류 응답 제어 -agent가 전송 또는 공급자 오류를 만나면 Telegram은 오류 텍스트로 응답하거나 이를 숨길 수 있습니다. 이 동작은 두 개의 config 키로 제어됩니다: +에이전트가 전송 또는 provider 오류를 만났을 때, Telegram은 오류 텍스트로 응답할 수도 있고 이를 숨길 수도 있습니다. 이 동작은 두 개의 config 키로 제어됩니다. -| 키 | 값 | 기본값 | 설명 | +| 키 | 값 | 기본값 | 설명 | | ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | | `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply`는 채팅에 친화적인 오류 메시지를 보냅니다. `silent`는 오류 응답을 완전히 숨깁니다. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 동일한 채팅에 대한 오류 응답 사이의 최소 시간입니다. 장애 중 오류 스팸을 방지합니다. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | 동일한 채팅에 오류 응답을 보내는 최소 시간 간격입니다. 장애 중 오류 스팸을 방지합니다. | 계정별, 그룹별, 토픽별 재정의를 지원합니다(다른 Telegram config 키와 동일한 상속 방식). @@ -886,40 +891,40 @@ agent가 전송 또는 공급자 오류를 만나면 Telegram은 오류 텍스 ## 문제 해결 - + - - `requireMention=false`인 경우 Telegram 개인정보 보호 모드가 전체 가시성을 허용해야 합니다. + - `requireMention=false`인 경우, Telegram 개인정보 보호 모드가 전체 가시성을 허용해야 합니다. - BotFather: `/setprivacy` -> 비활성화 - - 그런 다음 그룹에서 봇을 제거했다가 다시 추가 + - 그다음 그룹에서 봇을 제거한 뒤 다시 추가 - `openclaw channels status`는 config가 멘션 없는 그룹 메시지를 기대할 때 경고를 표시합니다. - - `openclaw channels status --probe`는 명시적 숫자형 그룹 ID를 검사할 수 있습니다. 와일드카드 `"*"`는 멤버십 probe를 할 수 없습니다. + - `openclaw channels status --probe`는 명시적인 숫자형 그룹 ID를 확인할 수 있습니다. 와일드카드 `"*"`는 멤버십 probe를 할 수 없습니다. - 빠른 세션 테스트: `/activation always`. - - `channels.telegram.groups`가 존재하면, 해당 그룹이 목록에 있거나 `"*"`가 포함되어 있어야 합니다 - - 그룹 내 봇 멤버십 확인 - - 건너뛴 이유는 `openclaw logs --follow`에서 로그 검토 + - `channels.telegram.groups`가 존재하면, 그룹이 목록에 있어야 합니다(또는 `"*"` 포함) + - 그룹에 봇이 실제로 참여해 있는지 확인 + - 로그 검토: 건너뛴 이유는 `openclaw logs --follow`에서 확인 - + - - 발신자 ID를 인증하세요(페어링 및/또는 숫자형 `allowFrom`) - - 그룹 정책이 `open`이더라도 명령 인증은 여전히 적용됩니다 - - `setMyCommands failed`와 함께 `BOT_COMMANDS_TOO_MUCH`가 표시되면 기본 메뉴 항목이 너무 많다는 뜻입니다. plugin/skill/사용자 지정 명령을 줄이거나 기본 메뉴를 비활성화하세요 - - `setMyCommands failed`와 함께 네트워크/fetch 오류가 표시되면 보통 `api.telegram.org`에 대한 DNS/HTTPS 도달성 문제를 의미합니다 + - 발신자 신원을 승인하세요(페어링 및/또는 숫자형 `allowFrom`) + - 그룹 정책이 `open`이어도 명령 권한 부여는 여전히 적용됩니다 + - `BOT_COMMANDS_TOO_MUCH`와 함께 `setMyCommands failed`가 발생하면 기본 메뉴에 항목이 너무 많다는 뜻입니다. plugin/Skills/사용자 지정 명령을 줄이거나 기본 메뉴를 비활성화하세요 + - 네트워크/fetch 오류와 함께 `setMyCommands failed`가 발생하면 일반적으로 `api.telegram.org`에 대한 DNS/HTTPS 연결 문제를 의미합니다 - + - - Node 22+와 사용자 지정 fetch/proxy 조합은 AbortSignal 타입이 맞지 않으면 즉시 abort 동작을 유발할 수 있습니다. - - 일부 호스트는 `api.telegram.org`를 먼저 IPv6로 해석하므로, IPv6 아웃바운드가 깨져 있으면 간헐적인 Telegram API 실패가 발생할 수 있습니다. + - Node 22+ + 사용자 지정 fetch/proxy 조합에서는 AbortSignal 타입 불일치가 있을 경우 즉시 중단 동작이 발생할 수 있습니다. + - 일부 호스트는 `api.telegram.org`를 먼저 IPv6로 확인합니다. IPv6 아웃바운드가 불안정하면 간헐적인 Telegram API 실패가 발생할 수 있습니다. - 로그에 `TypeError: fetch failed` 또는 `Network request for 'getUpdates' failed!`가 포함되면, OpenClaw는 이제 이를 복구 가능한 네트워크 오류로 재시도합니다. - - 직접 아웃바운드/TLS가 불안정한 VPS 호스트에서는 Telegram API 호출을 `channels.telegram.proxy`를 통해 라우팅하세요: + - 직접 아웃바운드/TLS가 불안정한 VPS 호스트에서는 `channels.telegram.proxy`를 통해 Telegram API 호출을 라우팅하세요: ```yaml channels: @@ -928,7 +933,7 @@ channels: ``` - Node 22+는 기본적으로 `autoSelectFamily=true`(WSL2 제외) 및 `dnsResultOrder=ipv4first`를 사용합니다. - - 호스트가 WSL2이거나 IPv4 전용 동작이 명시적으로 더 잘 맞는 경우, family selection을 강제하세요: + - 호스트가 WSL2이거나 IPv4 전용 동작이 더 적합한 경우, family 선택을 강제하세요: ```yaml channels: @@ -937,7 +942,11 @@ channels: autoSelectFamily: false ``` - - RFC 2544 벤치마크 범위 응답(`198.18.0.0/15`)은 기본적으로 Telegram 미디어 다운로드에 이미 허용되어 있습니다. 신뢰할 수 있는 가짜 IP 또는 transparent proxy가 미디어 다운로드 중 `api.telegram.org`를 다른 private/internal/special-use 주소로 재작성하는 경우, Telegram 전용 우회를 선택적으로 활성화할 수 있습니다: + - RFC 2544 벤치마크 범위 응답(`198.18.0.0/15`)은 이미 + Telegram 미디어 다운로드에 대해 기본적으로 허용됩니다. 신뢰할 수 있는 가짜 IP 또는 + 투명 프록시가 미디어 다운로드 중 `api.telegram.org`를 다른 + private/internal/special-use 주소로 재작성하는 경우, Telegram 전용 우회를 + 명시적으로 활성화할 수 있습니다: ```yaml channels: @@ -946,20 +955,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 동일한 선택 기능은 계정별로도 사용할 수 있습니다: + - 동일한 명시적 설정을 계정별로도 사용할 수 있습니다: `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - proxy가 Telegram 미디어 호스트를 `198.18.x.x`로 해석하는 경우, 먼저 위험한 플래그를 끈 상태로 두세요. Telegram 미디어는 기본적으로 RFC 2544 벤치마크 범위를 이미 허용합니다. + - 프록시가 Telegram 미디어 호스트를 `198.18.x.x`로 확인한다면, + 먼저 dangerous 플래그를 끈 상태로 두세요. Telegram 미디어는 이미 RFC 2544 + 벤치마크 범위를 기본적으로 허용합니다. `channels.telegram.network.dangerouslyAllowPrivateNetwork`는 Telegram - 미디어 SSRF 보호를 약화시킵니다. Clash, Mihomo, Surge 가짜 IP 라우팅처럼 RFC 2544 벤치마크 범위를 벗어난 private 또는 special-use 응답을 합성하는 신뢰된 운영자 제어 proxy 환경에서만 사용하세요. 일반적인 공용 인터넷 Telegram 액세스에서는 비활성화된 상태로 두세요. + 미디어 SSRF 보호를 약화시킵니다. Clash, Mihomo, Surge의 fake-IP 라우팅처럼 + 운영자가 제어하는 신뢰된 프록시 환경에서, RFC 2544 벤치마크 + 범위를 벗어난 private 또는 special-use 응답을 합성할 때만 사용하세요. + 일반적인 공개 인터넷 Telegram 접근에서는 비활성화 상태로 두세요. - 환경 변수 재정의(임시): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - DNS 응답 검증: + - DNS 응답 확인: ```bash dig +short api.telegram.org A @@ -969,7 +983,7 @@ dig +short api.telegram.org AAAA -추가 도움말: [채널 문제 해결](/channels/troubleshooting). +추가 도움말: [채널 문제 해결](/ko/channels/troubleshooting). ## Telegram config 참조 포인터 @@ -979,87 +993,87 @@ dig +short api.telegram.org AAAA - `channels.telegram.botToken`: 봇 토큰(BotFather). - `channels.telegram.tokenFile`: 일반 파일 경로에서 토큰 읽기. 심볼릭 링크는 거부됩니다. - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (기본값: pairing). -- `channels.telegram.allowFrom`: DM allowlist(숫자형 Telegram 사용자 ID). `allowlist`는 발신자 ID가 하나 이상 필요합니다. `open`은 `"*"`가 필요합니다. `openclaw doctor --fix`는 레거시 `@username` 항목을 ID로 해석할 수 있고, allowlist 마이그레이션 흐름에서 페어링 저장소 파일의 allowlist 항목을 복구할 수 있습니다. -- `channels.telegram.actions.poll`: Telegram 투표 생성 활성화 또는 비활성화(기본값: 활성화. 여전히 `sendMessage` 필요). -- `channels.telegram.defaultTo`: 명시적 `--reply-to`가 없을 때 CLI `--deliver`이 사용하는 기본 Telegram 대상. +- `channels.telegram.allowFrom`: DM allowlist(숫자형 Telegram 사용자 ID). `allowlist`는 최소 하나의 발신자 ID가 필요합니다. `open`은 `"*"`가 필요합니다. `openclaw doctor --fix`는 레거시 `@username` 항목을 ID로 확인할 수 있으며, allowlist 마이그레이션 흐름에서 pairing-store 파일의 allowlist 항목도 복구할 수 있습니다. +- `channels.telegram.actions.poll`: Telegram poll 생성 활성화 또는 비활성화(기본값: 활성화, 여전히 `sendMessage` 필요). +- `channels.telegram.defaultTo`: 명시적인 `--reply-to`가 제공되지 않았을 때 CLI `--deliver`가 사용하는 기본 Telegram 대상. - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (기본값: allowlist). -- `channels.telegram.groupAllowFrom`: 그룹 발신자 allowlist(숫자형 Telegram 사용자 ID). `openclaw doctor --fix`는 레거시 `@username` 항목을 ID로 해석할 수 있습니다. 숫자가 아닌 항목은 인증 시 무시됩니다. 그룹 인증은 DM 페어링 저장소 대체를 사용하지 않습니다(`2026.2.25+`). +- `channels.telegram.groupAllowFrom`: 그룹 발신자 allowlist(숫자형 Telegram 사용자 ID). `openclaw doctor --fix`는 레거시 `@username` 항목을 ID로 확인할 수 있습니다. 숫자가 아닌 항목은 인증 시 무시됩니다. 그룹 인증은 DM pairing-store 대체를 사용하지 않습니다(`2026.2.25+`). - 다중 계정 우선순위: - - 두 개 이상의 계정 ID가 구성된 경우, 기본 라우팅을 명시적으로 만들기 위해 `channels.telegram.defaultAccount`를 설정하거나 `channels.telegram.accounts.default`를 포함하세요. - - 둘 다 설정하지 않으면 OpenClaw는 첫 번째 정규화된 계정 ID로 대체하며 `openclaw doctor`가 경고합니다. + - 두 개 이상의 계정 ID가 구성된 경우, 기본 라우팅을 명시하려면 `channels.telegram.defaultAccount`를 설정하거나(`channels.telegram.accounts.default` 포함) 하세요. + - 둘 다 설정되지 않은 경우, OpenClaw는 첫 번째 정규화된 계정 ID로 대체하며 `openclaw doctor`가 경고를 표시합니다. - `channels.telegram.accounts.default.allowFrom` 및 `channels.telegram.accounts.default.groupAllowFrom`은 `default` 계정에만 적용됩니다. - 이름이 있는 계정은 계정 수준 값이 설정되지 않은 경우 `channels.telegram.allowFrom` 및 `channels.telegram.groupAllowFrom`을 상속합니다. - 이름이 있는 계정은 `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`을 상속하지 않습니다. - `channels.telegram.groups`: 그룹별 기본값 + allowlist(전역 기본값에는 `"*"` 사용). - - `channels.telegram.groups..groupPolicy`: 그룹별 `groupPolicy` 재정의 (`open | allowlist | disabled`). - - `channels.telegram.groups..requireMention`: 기본 멘션 게이팅. - - `channels.telegram.groups..skills`: Skills 필터(생략 = 모든 Skills, 빈값 = 없음). + - `channels.telegram.groups..groupPolicy`: groupPolicy에 대한 그룹별 재정의(`open | allowlist | disabled`). + - `channels.telegram.groups..requireMention`: 멘션 게이팅 기본값. + - `channels.telegram.groups..skills`: Skills 필터(생략 = 모든 Skills, 빈 값 = 없음). - `channels.telegram.groups..allowFrom`: 그룹별 발신자 allowlist 재정의. - `channels.telegram.groups..systemPrompt`: 그룹용 추가 시스템 프롬프트. - - `channels.telegram.groups..enabled`: `false`이면 그룹 비활성화. + - `channels.telegram.groups..enabled`: `false`일 때 그룹 비활성화. - `channels.telegram.groups..topics..*`: 토픽별 재정의(그룹 필드 + 토픽 전용 `agentId`). - - `channels.telegram.groups..topics..agentId`: 이 토픽을 특정 agent로 라우팅(그룹 수준 및 바인딩 라우팅 재정의). -- `channels.telegram.groups..topics..groupPolicy`: `groupPolicy`의 토픽별 재정의 (`open | allowlist | disabled`). + - `channels.telegram.groups..topics..agentId`: 이 토픽을 특정 에이전트로 라우팅(그룹 수준 및 바인딩 라우팅 재정의). +- `channels.telegram.groups..topics..groupPolicy`: groupPolicy에 대한 토픽별 재정의(`open | allowlist | disabled`). - `channels.telegram.groups..topics..requireMention`: 토픽별 멘션 게이팅 재정의. -- `match.peer.id`에 정식 토픽 ID `chatId:topic:topicId`가 있는 최상위 `bindings[]` 및 `type: "acp"`: 영구 ACP 토픽 바인딩 필드([ACP Agents](/tools/acp-agents#channel-specific-settings) 참조). -- `channels.telegram.direct..topics..agentId`: DM 토픽을 특정 agent로 라우팅(포럼 토픽과 동일한 동작). +- `type: "acp"` 및 `match.peer.id`의 정식 토픽 ID `chatId:topic:topicId`를 사용하는 최상위 `bindings[]`: 지속형 ACP 토픽 바인딩 필드([ACP Agents](/ko/tools/acp-agents#channel-specific-settings) 참고). +- `channels.telegram.direct..topics..agentId`: DM 토픽을 특정 에이전트로 라우팅(포럼 토픽과 동일한 동작). - `channels.telegram.execApprovals.enabled`: 이 계정에 대해 Telegram을 채팅 기반 exec 승인 클라이언트로 활성화. -- `channels.telegram.execApprovals.approvers`: exec 요청을 승인 또는 거부할 수 있는 Telegram 사용자 ID. `channels.telegram.allowFrom` 또는 direct `channels.telegram.defaultTo`가 이미 소유자를 식별하는 경우 선택 사항. -- `channels.telegram.execApprovals.target`: `dm | channel | both` (기본값: `dm`). `channel` 및 `both`는 존재하는 경우 원래 Telegram 토픽을 유지합니다. -- `channels.telegram.execApprovals.agentFilter`: 전달된 승인 프롬프트에 대한 선택적 agent ID 필터. -- `channels.telegram.execApprovals.sessionFilter`: 전달된 승인 프롬프트에 대한 선택적 세션 키 필터(부분 문자열 또는 regex). -- `channels.telegram.accounts..execApprovals`: Telegram exec 승인 라우팅 및 승인자 인증에 대한 계정별 재정의. +- `channels.telegram.execApprovals.approvers`: exec 요청을 승인 또는 거부할 수 있는 Telegram 사용자 ID. `channels.telegram.allowFrom` 또는 직접 `channels.telegram.defaultTo`가 이미 소유자를 식별하는 경우 선택 사항입니다. +- `channels.telegram.execApprovals.target`: `dm | channel | both` (기본값: `dm`). `channel` 및 `both`는 원래 Telegram 토픽이 있으면 이를 유지합니다. +- `channels.telegram.execApprovals.agentFilter`: 전달된 승인 프롬프트에 대한 선택적 에이전트 ID 필터. +- `channels.telegram.execApprovals.sessionFilter`: 전달된 승인 프롬프트에 대한 선택적 세션 키 필터(부분 문자열 또는 정규식). +- `channels.telegram.accounts..execApprovals`: Telegram exec 승인 라우팅 및 승인자 권한 부여에 대한 계정별 재정의. - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (기본값: allowlist). - `channels.telegram.accounts..capabilities.inlineButtons`: 계정별 재정의. - `channels.telegram.commands.nativeSkills`: Telegram 기본 Skills 명령 활성화/비활성화. - `channels.telegram.replyToMode`: `off | first | all` (기본값: `off`). - `channels.telegram.textChunkLimit`: 아웃바운드 청크 크기(문자 수). -- `channels.telegram.chunkMode`: `length`(기본값) 또는 `newline`; 길이 청크 전 빈 줄(문단 경계)에서 분할. +- `channels.telegram.chunkMode`: `length`(기본값) 또는 길이 청크 분할 전에 빈 줄(문단 경계) 기준으로 분할하는 `newline`. - `channels.telegram.linkPreview`: 아웃바운드 메시지의 링크 미리보기 토글(기본값: true). -- `channels.telegram.streaming`: `off | partial | block | progress` (실시간 스트림 미리보기, 기본값: `partial`; `progress`는 `partial`로 매핑; `block`은 레거시 미리보기 모드 호환성). Telegram 미리보기 스트리밍은 그 자리에서 편집되는 단일 미리보기 메시지를 사용합니다. +- `channels.telegram.streaming`: `off | partial | block | progress` (라이브 스트림 미리보기, 기본값: `partial`; `progress`는 `partial`로 매핑; `block`은 레거시 미리보기 모드 호환성). Telegram 미리보기 스트리밍은 제자리에서 편집되는 단일 미리보기 메시지를 사용합니다. - `channels.telegram.mediaMaxMb`: 인바운드/아웃바운드 Telegram 미디어 상한(MB, 기본값: 100). -- `channels.telegram.retry`: 복구 가능한 아웃바운드 API 오류에 대한 Telegram 전송 헬퍼(CLI/tools/actions) 재시도 정책(attempts, minDelayMs, maxDelayMs, jitter). -- `channels.telegram.network.autoSelectFamily`: Node autoSelectFamily 재정의(true=활성화, false=비활성화). 기본값은 Node 22+에서 활성화이며, WSL2는 기본적으로 비활성화됩니다. -- `channels.telegram.network.dnsResultOrder`: DNS 결과 순서 재정의(`ipv4first` 또는 `verbatim`). 기본값은 Node 22+에서 `ipv4first`입니다. -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: Telegram 미디어 다운로드가 기본 RFC 2544 벤치마크 범위 허용을 벗어난 private/internal/special-use 주소로 `api.telegram.org`를 해석하는 신뢰된 가짜 IP 또는 transparent-proxy 환경용 위험한 opt-in. -- `channels.telegram.proxy`: Bot API 호출용 proxy URL(SOCKS/HTTP). -- `channels.telegram.webhookUrl`: webhook 모드 활성화(`channels.telegram.webhookSecret` 필요). -- `channels.telegram.webhookSecret`: webhook secret(`webhookUrl` 설정 시 필수). -- `channels.telegram.webhookPath`: 로컬 webhook 경로(기본값 `/telegram-webhook`). -- `channels.telegram.webhookHost`: 로컬 webhook 바인딩 호스트(기본값 `127.0.0.1`). -- `channels.telegram.webhookPort`: 로컬 webhook 바인딩 포트(기본값 `8787`). +- `channels.telegram.retry`: 복구 가능한 아웃바운드 API 오류에 대한 Telegram 전송 헬퍼(CLI/tools/actions)의 재시도 정책(attempts, minDelayMs, maxDelayMs, jitter). +- `channels.telegram.network.autoSelectFamily`: Node autoSelectFamily 재정의(true=활성화, false=비활성화). 기본적으로 Node 22+에서는 활성화되며, WSL2에서는 기본적으로 비활성화됩니다. +- `channels.telegram.network.dnsResultOrder`: DNS 결과 순서 재정의(`ipv4first` 또는 `verbatim`). 기본적으로 Node 22+에서는 `ipv4first`입니다. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: Telegram 미디어 다운로드가 기본 RFC 2544 벤치마크 범위 허용 밖의 private/internal/special-use 주소로 `api.telegram.org`를 확인하는 신뢰된 fake-IP 또는 투명 프록시 환경을 위한 위험한 opt-in. +- `channels.telegram.proxy`: Bot API 호출용 프록시 URL(SOCKS/HTTP). +- `channels.telegram.webhookUrl`: Webhook 모드 활성화(`channels.telegram.webhookSecret` 필요). +- `channels.telegram.webhookSecret`: Webhook 시크릿(`webhookUrl`이 설정된 경우 필수). +- `channels.telegram.webhookPath`: 로컬 Webhook 경로(기본값 `/telegram-webhook`). +- `channels.telegram.webhookHost`: 로컬 Webhook 바인딩 호스트(기본값 `127.0.0.1`). +- `channels.telegram.webhookPort`: 로컬 Webhook 바인딩 포트(기본값 `8787`). - `channels.telegram.actions.reactions`: Telegram 도구 반응 게이트. - `channels.telegram.actions.sendMessage`: Telegram 도구 메시지 전송 게이트. - `channels.telegram.actions.deleteMessage`: Telegram 도구 메시지 삭제 게이트. - `channels.telegram.actions.sticker`: Telegram 스티커 작업 게이트 — 전송 및 검색(기본값: false). -- `channels.telegram.reactionNotifications`: `off | own | all` — 어떤 반응이 시스템 이벤트를 트리거할지 제어(설정되지 않은 경우 기본값: `own`). -- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — agent의 반응 기능을 제어(설정되지 않은 경우 기본값: `minimal`). +- `channels.telegram.reactionNotifications`: `off | own | all` — 어떤 반응이 시스템 이벤트를 트리거하는지 제어(설정되지 않은 경우 기본값: `own`). +- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — 에이전트의 반응 기능 제어(설정되지 않은 경우 기본값: `minimal`). - `channels.telegram.errorPolicy`: `reply | silent` — 오류 응답 동작 제어(기본값: `reply`). 계정별/그룹별/토픽별 재정의 지원. -- `channels.telegram.errorCooldownMs`: 동일한 채팅에 대한 오류 응답 사이의 최소 ms(기본값: `60000`). 장애 중 오류 스팸 방지. +- `channels.telegram.errorCooldownMs`: 동일한 채팅에 대한 오류 응답 간 최소 ms(기본값: `60000`). 장애 중 오류 스팸을 방지합니다. -- [구성 참조 - Telegram](/gateway/configuration-reference#telegram) +- [구성 참조 - Telegram](/ko/gateway/configuration-reference#telegram) -Telegram 전용 주요 필드: +Telegram 전용 고신호 필드: -- 시작/인증: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile`은 일반 파일을 가리켜야 하며 심볼릭 링크는 거부됨) -- 액세스 제어: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, 최상위 `bindings[]` (`type: "acp"`) +- 시작/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile`은 일반 파일을 가리켜야 하며 심볼릭 링크는 거부됨) +- 접근 제어: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, 최상위 `bindings[]` (`type: "acp"`) - exec 승인: `execApprovals`, `accounts.*.execApprovals` - 명령/메뉴: `commands.native`, `commands.nativeSkills`, `customCommands` - 스레딩/응답: `replyToMode` -- 스트리밍: `streaming`(미리보기), `blockStreaming` +- 스트리밍: `streaming` (미리보기), `blockStreaming` - 서식/전송: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - 미디어/네트워크: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` - 작업/기능: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - 반응: `reactionNotifications`, `reactionLevel` - 오류: `errorPolicy`, `errorCooldownMs` - 쓰기/기록: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -## 관련 문서 +## 관련 항목 -- [페어링](/channels/pairing) -- [그룹](/channels/groups) -- [보안](/gateway/security) -- [채널 라우팅](/channels/channel-routing) -- [멀티 에이전트 라우팅](/concepts/multi-agent) -- [문제 해결](/channels/troubleshooting) +- [페어링](/ko/channels/pairing) +- [그룹](/ko/channels/groups) +- [보안](/ko/gateway/security) +- [채널 라우팅](/ko/channels/channel-routing) +- [다중 에이전트 라우팅](/ko/concepts/multi-agent) +- [문제 해결](/ko/channels/troubleshooting) diff --git a/docs/ko/concepts/qa-e2e-automation.md b/docs/ko/concepts/qa-e2e-automation.md index c9f29010c..7c81adb40 100644 --- a/docs/ko/concepts/qa-e2e-automation.md +++ b/docs/ko/concepts/qa-e2e-automation.md @@ -6,46 +6,38 @@ read_when: summary: qa-lab, qa-channel, 시드된 시나리오, 프로토콜 보고서를 위한 비공개 QA 자동화 구조 title: QA E2E 자동화 x-i18n: - generated_at: "2026-04-18T05:51:39Z" + generated_at: "2026-04-20T06:05:33Z" model: gpt-5.4 provider: openai - source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 + source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # QA E2E 자동화 -비공개 QA 스택은 단일 단위 테스트보다 더 현실적이고 -채널 형태에 가까운 방식으로 OpenClaw를 검증하기 위한 것입니다. +비공개 QA 스택은 단일 단위 테스트보다 더 현실적이고 채널 형태에 가까운 방식으로 OpenClaw를 검증하기 위한 것입니다. 현재 구성 요소: -- `extensions/qa-channel`: DM, 채널, 스레드, - 리액션, 수정, 삭제 기능 표면을 갖춘 합성 메시지 채널 -- `extensions/qa-lab`: 대화 내용을 관찰하고, - 수신 메시지를 주입하며, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스 -- `qa/`: 시작 작업과 기본 QA - 시나리오를 위한 리포지토리 기반 시드 자산 +- `extensions/qa-channel`: DM, 채널, 스레드, 리액션, 수정, 삭제 표면을 갖춘 합성 메시지 채널 +- `extensions/qa-lab`: 대화 내용을 관찰하고, 인바운드 메시지를 주입하며, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스 +- `qa/`: 시작 작업과 기본 QA 시나리오를 위한 리포지토리 기반 시드 자산 -현재 QA 운영자 흐름은 2분할 QA 사이트입니다: +현재 QA 운영자 흐름은 2패널 QA 사이트입니다: - 왼쪽: 에이전트가 있는 Gateway 대시보드(Control UI) -- 오른쪽: Slack 유사 대화 내용과 시나리오 계획을 보여주는 QA Lab +- 오른쪽: Slack와 유사한 대화 내용과 시나리오 계획을 보여주는 QA Lab -실행 방법: +다음으로 실행합니다: ```bash pnpm qa:lab:up ``` -이 명령은 QA 사이트를 빌드하고, Docker 기반 gateway 레인을 시작하며, -운영자 또는 자동화 루프가 에이전트에게 QA -미션을 부여하고, 실제 채널 동작을 관찰하며, 무엇이 작동했고 실패했으며 -무엇이 계속 막혀 있었는지 기록할 수 있는 QA Lab 페이지를 노출합니다. +이 명령은 QA 사이트를 빌드하고, Docker 기반 gateway 레인을 시작하며, 운영자나 자동화 루프가 에이전트에 QA 미션을 부여하고, 실제 채널 동작을 관찰하며, 무엇이 작동했고 실패했으며 계속 막혀 있었는지를 기록할 수 있는 QA Lab 페이지를 노출합니다. -매번 Docker 이미지를 다시 빌드하지 않고 QA Lab UI를 더 빠르게 반복 개발하려면, -바인드 마운트된 QA Lab 번들로 스택을 시작하세요: +매번 Docker 이미지를 다시 빌드하지 않고 더 빠르게 QA Lab UI를 반복 개발하려면, bind-mounted QA Lab 번들로 스택을 시작하세요: ```bash pnpm openclaw qa docker-build-image @@ -54,10 +46,7 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast`는 Docker 서비스를 사전 빌드된 이미지로 유지하고 -`extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 바인드 마운트합니다. `qa:lab:watch`는 -변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 바뀌면 브라우저가 -자동으로 다시 로드됩니다. +`qa:lab:up:fast`는 미리 빌드된 이미지로 Docker 서비스를 유지하고 `extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 bind-mount합니다. `qa:lab:watch`는 변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 바뀌면 브라우저가 자동으로 다시 로드됩니다. 전송 계층이 실제인 Matrix 스모크 레인을 실행하려면 다음을 사용하세요: @@ -65,14 +54,7 @@ pnpm qa:lab:watch pnpm openclaw qa matrix ``` -이 레인은 Docker에서 일회용 Tuwunel homeserver를 프로비저닝하고, 임시 -driver, SUT, observer 사용자를 등록하고, 하나의 비공개 룸을 생성한 뒤, -QA gateway child 내부에서 실제 Matrix Plugin을 실행합니다. 라이브 전송 레인은 -child 구성을 테스트 중인 전송 계층에 맞게 범위를 제한하므로, Matrix는 -child 구성에서 `qa-channel` 없이 실행됩니다. 선택한 Matrix QA 출력 디렉터리에 -구조화된 보고서 아티팩트와 결합된 stdout/stderr 로그를 기록합니다. 바깥쪽 -`scripts/run-node.mjs` 빌드/런처 출력도 함께 캡처하려면 -`OPENCLAW_RUN_NODE_OUTPUT_LOG=`를 리포지토리 로컬 로그 파일로 설정하세요. +이 레인은 Docker에서 일회용 Tuwunel 홈서버를 프로비저닝하고, 임시 드라이버, SUT, 옵저버 사용자를 등록하며, 하나의 비공개 방을 생성한 뒤, QA gateway 하위 프로세스 안에서 실제 Matrix Plugin을 실행합니다. 라이브 전송 레인은 테스트 중인 전송 계층에 맞게 하위 config 범위를 유지하므로, Matrix는 하위 config에서 `qa-channel` 없이 실행됩니다. 이 레인은 구조화된 보고서 아티팩트와 stdout/stderr 통합 로그를 선택한 Matrix QA 출력 디렉터리에 기록합니다. 외부 `scripts/run-node.mjs` 빌드/런처 출력까지 함께 수집하려면 `OPENCLAW_RUN_NODE_OUTPUT_LOG=`를 리포지토리 로컬 로그 파일로 설정하세요. 전송 계층이 실제인 Telegram 스모크 레인을 실행하려면 다음을 사용하세요: @@ -80,132 +62,100 @@ child 구성에서 `qa-channel` 없이 실행됩니다. 선택한 Matrix QA 출 pnpm openclaw qa telegram ``` -이 레인은 일회용 서버를 프로비저닝하는 대신 실제 비공개 Telegram 그룹 하나를 대상으로 합니다. -이를 위해서는 `OPENCLAW_QA_TELEGRAM_GROUP_ID`, -`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, -`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`이 필요하며, -동일한 비공개 그룹 안에 서로 다른 두 개의 봇이 있어야 합니다. SUT 봇에는 Telegram -사용자명이 있어야 하며, 봇 간 관찰은 두 봇 모두 `@BotFather`에서 -Bot-to-Bot Communication Mode를 활성화했을 때 가장 잘 작동합니다. +이 레인은 일회용 서버를 프로비저닝하는 대신 하나의 실제 비공개 Telegram 그룹을 대상으로 합니다. `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`이 필요하며, 같은 비공개 그룹에 서로 다른 두 개의 봇이 있어야 합니다. SUT 봇은 Telegram 사용자 이름을 가져야 하며, 두 봇 모두 `@BotFather`에서 Bot-to-Bot Communication Mode를 활성화했을 때 봇 간 관찰이 가장 잘 동작합니다. +어떤 시나리오라도 실패하면 명령은 0이 아닌 종료 코드를 반환합니다. 실패 종료 코드 없이 아티팩트만 원한다면 `--allow-failures`를 사용하세요. -이제 라이브 전송 레인들은 각자 고유한 시나리오 목록 형태를 만들지 않고, -더 작고 공통된 하나의 계약을 공유합니다: +이제 라이브 전송 레인은 각자 자체 시나리오 목록 구조를 만드는 대신 하나의 더 작은 계약을 공유합니다: -`qa-channel`은 여전히 폭넓은 합성 제품 동작 스위트이며, 라이브 전송 -커버리지 매트릭스의 일부는 아닙니다. +`qa-channel`은 여전히 폭넓은 합성 제품 동작 스위트이며 라이브 전송 커버리지 매트릭스에는 포함되지 않습니다. -| 레인 | 카나리 | 멘션 게이팅 | 허용 목록 차단 | 최상위 답글 | 재시작 재개 | 스레드 후속 응답 | 스레드 격리 | 리액션 관찰 | 도움말 명령 | -| -------- | ------ | ----------- | -------------- | ----------- | ----------- | ---------------- | ----------- | ----------- | ----------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| 레인 | Canary | 멘션 게이팅 | 허용 목록 차단 | 최상위 답글 | 재시작 복구 | 스레드 후속 응답 | 스레드 격리 | 리액션 관찰 | 도움말 명령 | +| -------- | ------ | ----------- | --------------- | ----------- | ----------- | ---------------- | ----------- | ----------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -이렇게 하면 `qa-channel`은 폭넓은 제품 동작 스위트로 유지되고, Matrix, -Telegram 및 미래의 라이브 전송 계층은 하나의 명시적인 전송 계약 체크리스트를 공유하게 됩니다. +이렇게 하면 `qa-channel`은 폭넓은 제품 동작 스위트로 유지되고, Matrix, Telegram 및 향후 라이브 전송 계층은 하나의 명시적인 전송 계약 체크리스트를 공유하게 됩니다. -Docker를 QA 경로에 포함하지 않고 일회용 Linux VM 레인을 실행하려면 다음을 사용하세요: +QA 경로에 Docker를 포함하지 않는 일회용 Linux VM 레인을 실행하려면 다음을 사용하세요: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -이 명령은 새 Multipass guest를 부팅하고, 의존성을 설치하고, guest 내부에서 -OpenClaw를 빌드하고, `qa suite`를 실행한 뒤, 일반 QA 보고서와 -요약을 호스트의 `.artifacts/qa-e2e/...`로 다시 복사합니다. -호스트에서 `qa suite`를 실행할 때와 동일한 시나리오 선택 동작을 재사용합니다. -호스트와 Multipass 스위트 실행은 기본적으로 여러 선택된 시나리오를 -격리된 gateway worker와 함께 병렬로 실행하며, 최대 64개 worker 또는 -선택된 시나리오 수까지만 사용합니다. worker 수를 조정하려면 `--concurrency `를, -직렬 실행하려면 `--concurrency 1`을 사용하세요. -라이브 실행은 guest에서 실용적으로 전달 가능한 지원 QA 인증 입력을 전달합니다: -환경 변수 기반 provider 키, QA 라이브 provider config 경로, -그리고 존재하는 경우 `CODEX_HOME`입니다. guest가 마운트된 워크스페이스를 통해 -다시 기록할 수 있도록 `--output-dir`은 리포지토리 루트 아래에 두세요. +이 명령은 새 Multipass 게스트를 부팅하고, 의존성을 설치하고, 게스트 내부에서 OpenClaw를 빌드하고, `qa suite`를 실행한 뒤, 일반적인 QA 보고서와 요약을 호스트의 `.artifacts/qa-e2e/...`로 다시 복사합니다. +시나리오 선택 동작은 호스트에서의 `qa suite`와 동일하게 재사용합니다. +호스트 및 Multipass 스위트 실행은 기본적으로 격리된 gateway 워커와 함께 여러 개의 선택된 시나리오를 병렬로 실행합니다. `qa-channel`의 기본 동시성은 4이며, 선택된 시나리오 수를 상한으로 합니다. 워커 수를 조정하려면 `--concurrency `를 사용하고, 직렬 실행하려면 `--concurrency 1`을 사용하세요. +어떤 시나리오라도 실패하면 명령은 0이 아닌 종료 코드를 반환합니다. 실패 종료 코드 없이 아티팩트만 원한다면 `--allow-failures`를 사용하세요. +라이브 실행은 게스트에 실용적으로 전달 가능한 지원 QA 인증 입력을 전달합니다: env 기반 provider 키, QA 라이브 provider config 경로, 그리고 존재할 경우 `CODEX_HOME`입니다. 게스트가 마운트된 워크스페이스를 통해 다시 쓸 수 있도록 `--output-dir`은 리포지토리 루트 아래에 두세요. ## 리포지토리 기반 시드 -시드 자산은 `qa/` 아래에 있습니다: +시드 자산은 `qa/`에 있습니다: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -이들은 QA 계획이 사람과 -에이전트 모두에게 보이도록 의도적으로 git에 포함되어 있습니다. +이 파일들은 QA 계획이 사람과 에이전트 모두에게 보이도록 의도적으로 git에 포함됩니다. -`qa-lab`은 범용 markdown 러너로 유지되어야 합니다. 각 시나리오 markdown 파일은 -하나의 테스트 실행에 대한 단일 진실 공급원이어야 하며, 다음을 정의해야 합니다: +`qa-lab`은 일반적인 markdown 러너로 유지되어야 합니다. 각 시나리오 markdown 파일은 한 번의 테스트 실행에 대한 기준 정보여야 하며 다음을 정의해야 합니다: - 시나리오 메타데이터 - 선택적 category, capability, lane, risk 메타데이터 - 문서 및 코드 참조 -- 선택적 Plugin 요구 사항 -- 선택적 gateway config patch +- 선택적 Plugin 요구사항 +- 선택적 gateway config 패치 - 실행 가능한 `qa-flow` -`qa-flow`를 뒷받침하는 재사용 가능한 런타임 표면은 범용적이고 -교차 관심사로 유지되어도 됩니다. 예를 들어 markdown 시나리오는 -특수 사례 러너를 추가하지 않고도, 임베디드 Control UI를 -Gateway `browser.request` seam을 통해 구동하는 브라우저 측 helper와 -전송 측 helper를 결합할 수 있습니다. +`qa-flow`를 뒷받침하는 재사용 가능한 런타임 표면은 일반적이고 여러 영역을 가로지르는 형태로 유지될 수 있습니다. 예를 들어, markdown 시나리오는 특수한 러너를 추가하지 않고도 Gateway `browser.request` seam을 통해 내장된 Control UI를 구동하는 브라우저 측 헬퍼와 전송 측 헬퍼를 조합할 수 있습니다. -시나리오 파일은 소스 트리 폴더가 아니라 제품 기능 기준으로 그룹화해야 합니다. -파일이 이동해도 시나리오 ID는 안정적으로 유지하고, 구현 추적 가능성을 위해 -`docsRefs`와 `codeRefs`를 사용하세요. +시나리오 파일은 소스 트리 폴더가 아니라 제품 capability별로 그룹화해야 합니다. 파일이 이동하더라도 시나리오 ID는 안정적으로 유지하고, 구현 추적 가능성을 위해 `docsRefs`와 `codeRefs`를 사용하세요. -기본 목록은 다음을 포괄할 수 있을 만큼 충분히 넓어야 합니다: +기본 목록은 다음을 포괄할 만큼 충분히 넓어야 합니다: - DM 및 채널 채팅 - 스레드 동작 -- 메시지 액션 생명주기 +- 메시지 액션 수명주기 - Cron 콜백 - 메모리 회상 - 모델 전환 -- 서브에이전트 핸드오프 +- 하위 에이전트 handoff - 리포지토리 읽기 및 문서 읽기 -- Lobster Invaders 같은 작은 빌드 작업 하나 +- Lobster Invaders와 같은 작은 빌드 작업 하나 -## Provider 모의 레인 +## Provider mock 레인 -`qa suite`에는 두 개의 로컬 provider 모의 레인이 있습니다: +`qa suite`에는 두 개의 로컬 provider mock 레인이 있습니다: -- `mock-openai`는 시나리오 인식 OpenClaw 모의 구현입니다. 이는 리포지토리 기반 QA와 - 동등성 게이트를 위한 기본 결정론적 모의 레인으로 유지됩니다. -- `aimock`은 실험적 프로토콜, - 픽스처, 기록/재생, 혼돈 커버리지를 위해 AIMock 기반 provider 서버를 시작합니다. 이는 - 추가 기능이며 `mock-openai` 시나리오 디스패처를 대체하지 않습니다. +- `mock-openai`는 시나리오 인지형 OpenClaw mock입니다. 리포지토리 기반 QA 및 동등성 게이트를 위한 기본 결정론적 mock 레인으로 유지됩니다. +- `aimock`은 실험적인 프로토콜, 픽스처, record/replay, chaos 커버리지를 위해 AIMock 기반 provider 서버를 시작합니다. 이는 추가적인 옵션이며 `mock-openai` 시나리오 디스패처를 대체하지 않습니다. -Provider 레인 구현은 `extensions/qa-lab/src/providers/` 아래에 있습니다. -각 provider는 자체 기본값, 로컬 서버 시작, gateway 모델 구성, -auth-profile 스테이징 필요 사항, 라이브/모의 기능 플래그를 소유합니다. 공통 suite 및 -gateway 코드는 provider 이름으로 분기하지 말고 provider 레지스트리를 통해 라우팅해야 합니다. +provider 레인 구현은 `extensions/qa-lab/src/providers/` 아래에 있습니다. 각 provider는 자체 기본값, 로컬 서버 시작, gateway 모델 config, auth-profile 스테이징 필요 사항, 라이브/mock capability 플래그를 소유합니다. 공유 스위트와 gateway 코드는 provider 이름으로 분기하는 대신 provider 레지스트리를 통해 라우팅해야 합니다. ## 전송 어댑터 -`qa-lab`은 markdown QA 시나리오를 위한 범용 전송 seam을 소유합니다. -`qa-channel`은 그 seam의 첫 번째 어댑터이지만, 설계 목표는 더 넓습니다: -미래의 실제 또는 합성 채널도 전송 전용 QA 러너를 추가하는 대신 -동일한 suite runner에 연결되어야 합니다. +`qa-lab`은 markdown QA 시나리오를 위한 일반적인 전송 seam을 소유합니다. +`qa-channel`은 그 seam 위의 첫 번째 어댑터이지만, 설계 목표는 더 넓습니다. 향후 실제 또는 합성 채널은 전송 전용 QA 러너를 추가하는 대신 같은 스위트 러너에 연결되어야 합니다. 아키텍처 수준에서의 분리는 다음과 같습니다: -- `qa-lab`은 범용 시나리오 실행, worker 동시성, 아티팩트 기록, 보고를 소유합니다. -- 전송 어댑터는 gateway 구성, 준비 상태, 인바운드 및 아웃바운드 관찰, 전송 액션, 정규화된 전송 상태를 소유합니다. -- `qa/scenarios/` 아래의 markdown 시나리오 파일이 테스트 실행을 정의하며, 이를 실행하는 재사용 가능한 런타임 표면은 `qa-lab`이 제공합니다. +- `qa-lab`은 일반적인 시나리오 실행, 워커 동시성, 아티팩트 기록, 보고를 소유합니다. +- 전송 어댑터는 gateway config, 준비 상태, 인바운드 및 아웃바운드 관찰, 전송 액션, 정규화된 전송 상태를 소유합니다. +- `qa/scenarios/` 아래의 markdown 시나리오 파일이 테스트 실행을 정의하며, `qa-lab`은 이를 실행하는 재사용 가능한 런타임 표면을 제공합니다. -새 채널 어댑터를 위한 메인테이너용 도입 가이드는 +새 채널 어댑터를 위한 유지관리자용 도입 가이드는 [Testing](/ko/help/testing#adding-a-channel-to-qa)에 있습니다. ## 보고 `qa-lab`은 관찰된 버스 타임라인에서 Markdown 프로토콜 보고서를 내보냅니다. -이 보고서는 다음에 답해야 합니다: +보고서는 다음 질문에 답해야 합니다: - 무엇이 작동했는가 - 무엇이 실패했는가 - 무엇이 계속 막혀 있었는가 - 어떤 후속 시나리오를 추가할 가치가 있는가 -문체와 스타일 검사를 위해 동일한 시나리오를 여러 라이브 모델 -ref에 대해 실행하고 판정된 Markdown 보고서를 작성하세요: +문체 및 스타일 검사를 위해, 같은 시나리오를 여러 라이브 모델 ref에 걸쳐 실행하고 평가된 Markdown 보고서를 작성하세요: ```bash pnpm openclaw qa character-eval \ @@ -224,35 +174,15 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -이 명령은 Docker가 아니라 로컬 QA gateway child 프로세스를 실행합니다. Character eval -시나리오는 `SOUL.md`를 통해 페르소나를 설정한 뒤, 채팅, -워크스페이스 도움말, 작은 파일 작업 같은 일반 사용자 턴을 실행해야 합니다. 후보 모델에는 -자신이 평가 중이라는 사실을 알려주면 안 됩니다. 이 명령은 각 전체 -대화 내용을 보존하고, 기본 실행 통계를 기록한 다음, fast mode와 -`xhigh` 추론을 사용하는 judge 모델에게 자연스러움, 분위기, 유머를 기준으로 실행 결과를 순위 매기도록 요청합니다. -provider를 비교할 때는 `--blind-judge-models`를 사용하세요: -judge 프롬프트는 여전히 모든 대화 내용과 실행 상태를 받지만, 후보 ref는 -`candidate-01` 같은 중립 레이블로 대체되며, 보고서는 파싱 후 순위를 실제 ref에 다시 매핑합니다. -후보 실행은 기본적으로 `high` thinking을 사용하며, 이를 지원하는 OpenAI 모델은 `xhigh`를 사용합니다. -특정 후보를 인라인으로 재정의하려면 -`--model provider/model,thinking=`을 사용하세요. `--thinking `은 여전히 -전역 폴백을 설정하며, 이전의 `--model-thinking ` 형식도 -호환성을 위해 유지됩니다. -OpenAI 후보 ref는 provider가 이를 지원하는 경우 우선 처리에 fast mode를 -기본 적용합니다. 특정 후보 또는 judge에 재정의가 필요하면 인라인으로 -`,fast`, `,no-fast`, 또는 `,fast=false`를 추가하세요. 모든 후보 모델에 대해 -fast mode를 강제로 켜고 싶을 때만 `--fast`를 전달하세요. 후보 및 judge 실행 시간은 -벤치마크 분석을 위해 보고서에 기록되지만, judge 프롬프트에는 -속도를 기준으로 순위를 매기지 말라고 명시되어 있습니다. -후보와 judge 모델 실행은 모두 기본적으로 동시성 16을 사용합니다. provider 제한이나 -로컬 gateway 부하 때문에 실행이 너무 불안정해지면 -`--concurrency` 또는 `--judge-concurrency`를 낮추세요. -후보 `--model`이 전달되지 않으면 character eval은 기본적으로 -`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, -`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, +이 명령은 Docker가 아니라 로컬 QA gateway 하위 프로세스를 실행합니다. character eval 시나리오는 `SOUL.md`를 통해 페르소나를 설정한 다음, 채팅, 워크스페이스 도움말, 작은 파일 작업과 같은 일반 사용자 턴을 실행해야 합니다. 후보 모델에는 자신이 평가 중이라는 사실을 알려주면 안 됩니다. 이 명령은 각 전체 대화 내용을 보존하고, 기본 실행 통계를 기록한 다음, judge 모델에게 fast 모드와 `xhigh` 추론으로 실행 결과를 자연스러움, 분위기, 유머 기준으로 순위를 매기도록 요청합니다. +provider를 비교할 때는 `--blind-judge-models`를 사용하세요. judge 프롬프트는 여전히 모든 대화 내용과 실행 상태를 받지만, 후보 ref는 `candidate-01`과 같은 중립적인 라벨로 대체되며, 보고서는 파싱 후 순위를 실제 ref로 다시 매핑합니다. +후보 실행은 기본적으로 `high` thinking을 사용하며, 이를 지원하는 OpenAI 모델은 `xhigh`를 사용합니다. 특정 후보를 인라인으로 재정의하려면 `--model provider/model,thinking=`을 사용하세요. `--thinking `은 여전히 전역 기본값을 설정하며, 이전 `--model-thinking ` 형식도 호환성을 위해 유지됩니다. +OpenAI 후보 ref는 provider가 지원하는 경우 우선순위 처리를 사용하도록 기본적으로 fast 모드를 사용합니다. 특정 후보나 judge에 대해 재정의가 필요하면 인라인으로 `,fast`, `,no-fast`, 또는 `,fast=false`를 추가하세요. 모든 후보 모델에 fast 모드를 강제로 켜려는 경우에만 `--fast`를 전달하세요. 후보 및 judge 실행 시간은 벤치마크 분석을 위해 보고서에 기록되지만, judge 프롬프트에는 속도로 순위를 매기지 말라고 명시되어 있습니다. +후보 및 judge 모델 실행은 둘 다 기본적으로 동시성 16을 사용합니다. provider 제한이나 로컬 gateway 부하로 인해 실행이 너무 불안정해지면 `--concurrency` 또는 `--judge-concurrency`를 낮추세요. +후보 `--model`이 전달되지 않으면 character eval은 기본적으로 `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5`, -그리고 `google/gemini-3.1-pro-preview`를 사용합니다. -judge `--judge-model`이 전달되지 않으면 judge는 기본적으로 +`google/gemini-3.1-pro-preview`를 사용합니다. +`--judge-model`이 전달되지 않으면 judge는 기본적으로 `openai/gpt-5.4,thinking=xhigh,fast`와 `anthropic/claude-opus-4-6,thinking=high`를 사용합니다. diff --git a/docs/ko/gateway/configuration-reference.md b/docs/ko/gateway/configuration-reference.md index c9abb5c82..cc164e653 100644 --- a/docs/ko/gateway/configuration-reference.md +++ b/docs/ko/gateway/configuration-reference.md @@ -5,10 +5,10 @@ read_when: summary: 핵심 OpenClaw 키, 기본값, 전용 하위 시스템 참조 링크를 위한 Gateway 구성 참조 title: 구성 참조 x-i18n: - generated_at: "2026-04-18T05:51:39Z" + generated_at: "2026-04-20T06:05:31Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,19 +17,19 @@ x-i18n: `~/.openclaw/openclaw.json`에 대한 핵심 구성 참조입니다. 작업 중심 개요는 [Configuration](/ko/gateway/configuration)을 참조하세요. -이 페이지는 주요 OpenClaw 구성 표면을 다루며, 하위 시스템에 자체적으로 더 깊은 참조 문서가 있는 경우 해당 문서로 연결합니다. 이 페이지는 모든 채널/Plugin 소유 명령 카탈로그나 모든 심층 메모리/QMD 설정을 한 페이지에 인라인으로 담으려 하지 않습니다. +이 페이지는 주요 OpenClaw 구성 표면을 다루며, 하위 시스템에 자체적으로 더 깊은 참조 문서가 있는 경우 해당 문서로 연결합니다. 이 페이지는 모든 채널/Plugin 소유 명령 카탈로그나 모든 심층 메모리/QMD 조정 항목을 한 페이지에 인라인으로 모두 담으려 하지 않습니다. -코드 기준 정보: +코드 기준 진실 소스: -- `openclaw config schema`는 검증 및 Control UI에 사용되는 현재 JSON Schema를 출력하며, 사용 가능한 경우 번들/Plugin/채널 메타데이터가 병합됩니다 +- `openclaw config schema`는 유효성 검사와 Control UI에 사용되는 실제 JSON Schema를 출력하며, 사용 가능한 경우 번들/Plugin/채널 메타데이터가 병합되어 포함됩니다 - `config.schema.lookup`은 드릴다운 도구용으로 경로 범위가 지정된 단일 스키마 노드를 반환합니다 -- `pnpm config:docs:check` / `pnpm config:docs:gen`은 현재 스키마 표면과 구성 문서 기준 해시를 검증합니다 +- `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) -- 채널별 명령 표면을 위한 각 채널/Plugin 페이지 +- `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, 그리고 `plugins.entries.memory-core.config.dreaming` 아래의 Dreaming 구성은 [메모리 구성 참조](/ko/reference/memory-config) +- 현재 내장 + 번들 명령 카탈로그는 [슬래시 명령어](/ko/tools/slash-commands) +- 채널별 명령 표면은 해당 채널/Plugin 페이지 구성 형식은 **JSON5**입니다(주석 + 후행 쉼표 허용). 모든 필드는 선택 사항이며, 생략하면 OpenClaw가 안전한 기본값을 사용합니다. @@ -37,29 +37,29 @@ x-i18n: ## 채널 -각 채널은 해당 구성 섹션이 존재하면 자동으로 시작됩니다(`enabled: false`인 경우 제외). +각 채널은 해당 구성 섹션이 존재하면 자동으로 시작됩니다(`enabled: false`가 아닌 한). -### DM 및 그룹 접근 +### DM 및 그룹 액세스 모든 채널은 DM 정책과 그룹 정책을 지원합니다: | DM 정책 | 동작 | | ------------------- | --------------------------------------------------------------- | -| `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 함 | -| `allowlist` | `allowFrom`(또는 페어링된 허용 저장소)에 있는 발신자만 허용 | -| `open` | 모든 수신 DM 허용(`allowFrom: ["*"]` 필요) | -| `disabled` | 모든 수신 DM 무시 | +| `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 합니다 | +| `allowlist` | `allowFrom`에 있거나(또는 페어링된 허용 저장소에 있는) 발신자만 허용합니다 | +| `open` | 모든 수신 DM을 허용합니다(`allowFrom: ["*"]` 필요) | +| `disabled` | 모든 수신 DM을 무시합니다 | | 그룹 정책 | 동작 | | --------------------- | ------------------------------------------------------ | -| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용 | -| `open` | 그룹 허용 목록 우회(멘션 게이팅은 계속 적용) | -| `disabled` | 모든 그룹/룸 메시지 차단 | +| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용합니다 | +| `open` | 그룹 허용 목록을 우회합니다(멘션 게이팅은 계속 적용됨) | +| `disabled` | 모든 그룹/룸 메시지를 차단합니다 | -`channels.defaults.groupPolicy`는 공급자의 `groupPolicy`가 설정되지 않았을 때 기본값을 설정합니다. +`channels.defaults.groupPolicy`는 provider의 `groupPolicy`가 설정되지 않았을 때 기본값을 설정합니다. 페어링 코드는 1시간 후 만료됩니다. 대기 중인 DM 페어링 요청은 **채널당 3개**로 제한됩니다. -공급자 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(기본 차단)로 대체됩니다. +provider 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(fail-closed)로 대체됩니다. ### 채널 모델 재정의 @@ -85,9 +85,9 @@ x-i18n: } ``` -### 채널 기본값과 Heartbeat +### 채널 기본값 및 Heartbeat -공급자 간에 공유되는 그룹 정책 및 Heartbeat 동작에는 `channels.defaults`를 사용하세요: +provider 전반에서 공유되는 그룹 정책 및 Heartbeat 동작에는 `channels.defaults`를 사용하세요: ```json5 { @@ -105,11 +105,11 @@ x-i18n: } ``` -- `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 출력을 렌더링합니다. +- `channels.defaults.groupPolicy`: provider 수준 `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 @@ -124,7 +124,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 파란 체크 표시(셀프 채팅 모드에서는 false) + sendReadReceipts: true, // 읽음 표시(파란 체크, self-chat 모드에서는 false) 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 (기본값: off, 미리보기 편집 속도 제한을 피하려면 명시적으로 opt-in) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,12 +226,12 @@ 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)에서 공통으로 설명합니다. +- 선택적인 `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)을 참조하세요. +- 재시도 정책: [재시도 정책](/ko/concepts/retry) 참조. ### Discord @@ -297,7 +297,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // sessions_spawn({ thread: true })에 대해 opt-in + spawnSubagentSessions: false, // sessions_spawn({ thread: true })에 대한 opt-in }, voice: { enabled: true, @@ -334,35 +334,35 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 ``` - 토큰: `channels.discord.token`, 기본 계정의 대체값으로 `DISCORD_BOT_TOKEN` 사용 가능. -- 명시적인 Discord `token`을 제공하는 직접 발신 호출은 해당 호출에 그 토큰을 사용합니다. 계정 재시도/정책 설정은 여전히 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다. -- 선택적 `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자 미만이더라도 줄 수가 많으면 분할합니다. +- 명시적인 Discord `token`을 제공하는 직접 송신 호출은 해당 호출에 그 토큰을 사용합니다. 계정 재시도/정책 설정은 여전히 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다. +- 선택적인 `channels.discord.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 전송 대상에는 `user:`(DM) 또는 `channel:`(guild 채널)를 사용하세요. 숫자 ID만 단독으로 쓰는 형식은 거부됩니다. +- Guild 슬러그는 소문자이며 공백은 `-`로 대체됩니다. 채널 키는 슬러그 처리된 이름을 사용합니다(`#` 제외). 가능하면 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`: 비활성 상태 자동 언포커스 시간(시간 단위)용 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)에서 공통으로 설명합니다. + - `enabled`: 스레드 바인딩 세션 기능(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, 바인딩된 전송/라우팅)에 대한 Discord 재정의 + - `idleHours`: 비활성 상태 자동 언포커스 시간(시간 단위)에 대한 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)에서 공통으로 설명합니다. - `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`는 런타임 가용성을 봇 presence에 매핑합니다(healthy => online, degraded => idle, exhausted => dnd). 선택적 상태 텍스트 재정의도 허용합니다. -- `channels.discord.dangerouslyAllowNameMatching`는 변경 가능한 이름/태그 매칭을 다시 활성화합니다(비상 호환성 모드). +- `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.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`: 선택적 세션 키 패턴(부분 문자열 또는 regex)입니다. - - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값)은 승인자 DM으로 보내고, `"channel"`은 원본 채널로 보내며, `"both"`는 둘 다로 보냅니다. 대상에 `"channel"`이 포함되면 버튼은 확인된 승인자만 사용할 수 있습니다. + - `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`는 변경 가능한 이메일 principal 매칭을 다시 활성화합니다(비상 호환성 모드). +- 전송 대상에는 `spaces/` 또는 `users/`를 사용하세요. +- `channels.googlechat.dangerouslyAllowNameMatching`은 변경 가능한 이메일 프린시펄 매칭을 다시 활성화합니다(비상용 호환 모드). ### Slack @@ -464,30 +464,30 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- **Socket 모드**는 `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로 구성되었지만 현재 명령/런타임 경로에서 비밀 값 해석이 불가능했음을 의미합니다. +- **Socket 모드**는 `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` 값은 자동으로 마이그레이션됩니다. -- 전달 대상에는 `user:`(DM) 또는 `channel:`를 사용하세요. +- 선택적인 `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 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"`). +- Slack 네이티브 스트리밍과 Slack 어시스턴트 스타일 `"is typing..."` 스레드 상태는 답글 스레드 대상이 필요합니다. 최상위 DM은 기본적으로 스레드 밖이므로, 스레드 스타일 미리보기 대신 `typingReaction` 또는 일반 전달을 사용합니다. +- `typingReaction`은 답변이 실행되는 동안 수신된 Slack 메시지에 임시 반응을 추가하고, 완료 시 이를 제거합니다. `"hourglass_flowing_sand"` 같은 Slack 이모지 쇼트코드를 사용하세요. +- `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 @@ -511,7 +511,7 @@ Mattermost는 Plugin으로 제공됩니다: `openclaw plugins install @openclaw/ native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // 리버스 프록시/공개 배포를 위한 선택적 명시적 URL + // 리버스 프록시/공개 배포용 선택적 명시 URL callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -521,20 +521,20 @@ Mattermost는 Plugin으로 제공됩니다: `openclaw plugins install @openclaw/ } ``` -채팅 모드: `oncall`(@-멘션 시 응답, 기본값), `onmessage`(모든 메시지), `onchar`(트리거 접두사로 시작하는 메시지). +채팅 모드: `oncall`(@멘션 시 응답, 기본값), `onmessage`(모든 메시지), `onchar`(트리거 접두사로 시작하는 메시지). Mattermost 네이티브 명령이 활성화된 경우: - `commands.callbackPath`는 전체 URL이 아니라 경로여야 합니다(예: `/api/channels/mattermost/command`). - `commands.callbackUrl`은 OpenClaw gateway 엔드포인트로 해석되어야 하며 Mattermost 서버에서 접근 가능해야 합니다. -- 네이티브 슬래시 콜백은 슬래시 명령 등록 중 Mattermost가 반환하는 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 다음과 함께 콜백을 거부합니다: +- 네이티브 슬래시 콜백은 슬래시 명령 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록에 실패했거나 활성화된 명령이 없으면 OpenClaw는 다음과 함께 콜백을 거부합니다: `Unauthorized: invalid command token.` -- 비공개/tailnet/내부 콜백 호스트의 경우 Mattermost는 `ServiceSettings.AllowedUntrustedInternalConnections`에 콜백 호스트/도메인이 포함되어야 할 수 있습니다. +- 비공개/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 @@ -555,15 +555,15 @@ Mattermost 네이티브 명령이 활성화된 경우: } ``` -**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기반). +**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). - `channels.signal.account`: 채널 시작을 특정 Signal 계정 식별자에 고정합니다. - `channels.signal.configWrites`: Signal에서 시작된 구성 쓰기를 허용하거나 거부합니다. -- 선택적 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 선택적인 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. ### BlueBubbles -BlueBubbles는 권장되는 iMessage 경로입니다(Plugin 기반, `channels.bluebubbles` 아래에 구성). +BlueBubbles는 권장되는 iMessage 경로입니다(Plugin 기반, `channels.bluebubbles` 아래에서 구성). ```json5 { @@ -578,14 +578,14 @@ BlueBubbles는 권장되는 iMessage 경로입니다(Plugin 기반, `channels.bl } ``` -- 여기에서 다루는 핵심 키 경로: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- 선택적 `channels.bluebubbles.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- `type: "acp"`인 최상위 `bindings[]` 항목은 BlueBubbles 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 BlueBubbles handle 또는 대상 문자열(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). +- 여기서 다루는 핵심 키 경로: `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). - 전체 BlueBubbles 채널 구성은 [BlueBubbles](/ko/channels/bluebubbles)에 문서화되어 있습니다. ### iMessage -OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 실행합니다. 데몬이나 포트는 필요하지 않습니다. +OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 생성합니다. 데몬이나 포트는 필요하지 않습니다. ```json5 { @@ -609,17 +609,17 @@ OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 실행합니다. 데몬이 } ``` -- 선택적 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 선택적인 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. - Messages DB에 대한 전체 디스크 접근 권한이 필요합니다. - 가능하면 `chat_id:` 대상을 사용하세요. 채팅 목록은 `imsg chats --limit 20`으로 확인할 수 있습니다. - `cliPath`는 SSH 래퍼를 가리킬 수 있습니다. SCP 첨부 파일 가져오기를 위해 `remoteHost`(`host` 또는 `user@host`)를 설정하세요. - `attachmentRoots` 및 `remoteAttachmentRoots`는 수신 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). -- SCP는 엄격한 호스트 키 검사를 사용하므로 릴레이 호스트 키가 이미 `~/.ssh/known_hosts`에 존재해야 합니다. +- SCP는 엄격한 호스트 키 검사를 사용하므로, 중계 호스트 키가 이미 `~/.ssh/known_hosts`에 존재하는지 확인하세요. - `channels.imessage.configWrites`: iMessage에서 시작된 구성 쓰기를 허용하거나 거부합니다. -- `type: "acp"`인 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 정규화된 handle 또는 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). +- `type: "acp"`를 가진 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 정규화된 핸들이나 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -630,7 +630,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix는 확장 기반이며 `channels.matrix` 아래에 구성됩니다. +Matrix는 확장 기반이며 `channels.matrix` 아래에서 구성합니다. ```json5 { @@ -661,24 +661,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`는 사설/내부 homeserver를 허용합니다. `proxy`와 이 네트워크 opt-in은 서로 독립적인 제어입니다. - `channels.matrix.defaultAccount`는 다중 계정 설정에서 선호 계정을 선택합니다. -- `channels.matrix.autoJoin`의 기본값은 `off`이므로, `autoJoin: "allowlist"`와 `autoJoinAllowlist` 또는 `autoJoin: "always"`를 설정하기 전까지 초대된 룸과 새 DM 스타일 초대는 무시됩니다. +- `channels.matrix.autoJoin`의 기본값은 `off`이므로, `autoJoin: "allowlist"`와 `autoJoinAllowlist` 또는 `autoJoin: "always"`를 설정하기 전까지는 초대된 룸과 새 DM 스타일 초대가 무시됩니다. - `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`: 선택적 세션 키 패턴(부분 문자열 또는 regex)입니다. + - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 정규식)입니다. - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값), `"channel"`(원래 룸), 또는 `"both"`. - 계정별 재정의: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 그룹화되는 방식을 제어합니다: `per-user`(기본값)는 라우팅된 peer별로 공유하고, `per-room`은 각 DM 룸을 격리합니다. +- `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 묶이는 방식을 제어합니다: `per-user`(기본값)는 라우팅된 피어별로 공유하고, `per-room`은 각 DM 룸을 격리합니다. - Matrix 상태 프로브와 라이브 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. -- 전체 Matrix 구성, 대상 지정 규칙, 설정 예제는 [Matrix](/ko/channels/matrix)에 문서화되어 있습니다. +- 전체 Matrix 구성, 대상 지정 규칙, 설정 예시는 [Matrix](/ko/channels/matrix)에 문서화되어 있습니다. ### Microsoft Teams -Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에 구성됩니다. +Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에서 구성합니다. ```json5 { @@ -693,12 +693,12 @@ Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에 구성됩니 } ``` -- 여기에서 다루는 핵심 키 경로: `channels.msteams`, `channels.msteams.configWrites`. -- 전체 Teams 구성(자격 증명, Webhook, DM/그룹 정책, 팀별/채널별 재정의)은 [Microsoft Teams](/ko/channels/msteams)에 문서화되어 있습니다. +- 여기서 다루는 핵심 키 경로: `channels.msteams`, `channels.msteams.configWrites`. +- 전체 Teams 구성(자격 증명, webhook, DM/그룹 정책, 팀별/채널별 재정의)은 [Microsoft Teams](/ko/channels/msteams)에 문서화되어 있습니다. ### IRC -IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. +IRC는 확장 기반이며 `channels.irc` 아래에서 구성합니다. ```json5 { @@ -719,13 +719,13 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -- 여기에서 다루는 핵심 키 경로: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- 선택적 `channels.irc.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 여기서 다루는 핵심 키 경로: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- 선택적인 `channels.irc.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. - 전체 IRC 채널 구성(호스트/포트/TLS/채널/허용 목록/멘션 게이팅)은 [IRC](/ko/channels/irc)에 문서화되어 있습니다. ### 다중 계정(모든 채널) -채널별로 여러 계정을 실행할 수 있습니다(각 계정은 자체 `accountId`를 가짐): +채널별로 여러 계정을 실행합니다(각각 자체 `accountId` 보유): ```json5 { @@ -748,26 +748,26 @@ 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는 기존의 일치하는 명명된/default 대상을 대신 유지할 수 있습니다. +- 기존의 채널 전용 바인딩(`accountId` 없음)은 계속 기본 계정과 일치합니다. 계정 범위 바인딩은 여전히 선택 사항입니다. +- `openclaw doctor --fix`도 계정 범위 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 이동하여 혼합된 형태를 복구합니다. 대부분의 채널은 `accounts.default`를 사용하며, Matrix는 기존의 일치하는 명명된/default 대상을 대신 유지할 수 있습니다. ### 기타 확장 채널 많은 확장 채널은 `channels.`로 구성되며 전용 채널 페이지에 문서화되어 있습니다(예: Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, Twitch). -전체 채널 색인은 [Channels](/ko/channels)를 참조하세요. +전체 채널 색인은 [채널](/ko/channels)을 참조하세요. ### 그룹 채팅 멘션 게이팅 -그룹 메시지는 기본적으로 **멘션 필요**입니다(메타데이터 멘션 또는 안전한 regex 패턴). WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. +그룹 메시지는 기본적으로 **멘션 필요**입니다(메타데이터 멘션 또는 안전한 정규식 패턴). WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. **멘션 유형:** -- **메타데이터 멘션**: 네이티브 플랫폼 @-멘션입니다. WhatsApp 셀프 채팅 모드에서는 무시됩니다. -- **텍스트 패턴**: `agents.list[].groupChat.mentionPatterns`의 안전한 regex 패턴입니다. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다. -- 멘션 게이팅은 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 하나 이상의 패턴). +- **메타데이터 멘션**: 네이티브 플랫폼 @멘션입니다. WhatsApp self-chat 모드에서는 무시됩니다. +- **텍스트 패턴**: `agents.list[].groupChat.mentionPatterns`의 안전한 정규식 패턴입니다. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다. +- 멘션 게이팅은 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 최소 1개의 패턴이 있는 경우). ```json5 { @@ -797,13 +797,13 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -해결 순서: DM별 재정의 → 공급자 기본값 → 제한 없음(모두 유지). +해결 순서: DM별 재정의 → provider 기본값 → 제한 없음(모두 유지). -지원 대상: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +지원됨: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### 셀프 채팅 모드 +#### Self-chat 모드 -`allowFrom`에 자신의 번호를 포함하면 셀프 채팅 모드가 활성화됩니다(네이티브 @-멘션은 무시하고 텍스트 패턴에만 응답): +자기 번호를 `allowFrom`에 포함하면 self-chat 모드가 활성화됩니다(네이티브 @멘션은 무시하고 텍스트 패턴에만 응답): ```json5 { @@ -829,9 +829,9 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ```json5 { commands: { - native: "auto", // 지원되는 경우 네이티브 명령 등록 - nativeSkills: "auto", // 지원되는 경우 네이티브 Skills 명령 등록 - text: true, // 채팅 메시지에서 /commands 파싱 + native: "auto", // 지원될 때 네이티브 명령 등록 + nativeSkills: "auto", // 지원될 때 네이티브 Skills 명령 등록 + text: true, // 채팅 메시지에서 /commands 구문 분석 bash: false, // ! 허용(별칭: /bash) bashForegroundMs: 2000, config: false, // /config 허용 @@ -853,28 +853,28 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. -- 이 블록은 명령 표면을 구성합니다. 현재 내장 + 번들 명령 카탈로그는 [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` 같은 채널/Plugin 소유 명령은 각 채널/Plugin 페이지와 [Slash Commands](/ko/tools/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` 같은 채널/Plugin 소유 명령은 해당 채널/Plugin 페이지와 [슬래시 명령어](/ko/tools/slash-commands)에 문서화되어 있습니다. - 텍스트 명령은 앞에 `/`가 붙은 **독립 실행형** 메시지여야 합니다. -- `native: "auto"`는 Discord/Telegram에서는 네이티브 명령을 켜고 Slack에서는 꺼 둡니다. -- `nativeSkills: "auto"`는 Discord/Telegram에서는 네이티브 Skills 명령을 켜고 Slack에서는 꺼 둡니다. +- `native: "auto"`는 Discord/Telegram에서 네이티브 명령을 켜고, Slack에서는 끕니다. +- `nativeSkills: "auto"`는 Discord/Telegram에서 네이티브 Skills 명령을 켜고, Slack에서는 끕니다. - 채널별 재정의: `channels.discord.commands.native`(bool 또는 `"auto"`). `false`는 이전에 등록된 명령을 지웁니다. -- 네이티브 skill 등록은 `channels..commands.nativeSkills`로 채널별 재정의가 가능합니다. +- `channels..commands.nativeSkills`로 채널별 네이티브 skill 등록을 재정의합니다. - `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`는 Plugin 검색, 설치, 활성화/비활성화 제어를 위한 `/plugins`를 활성화합니다. +- `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`는 Plugin 검색, 설치, 활성화/비활성화 제어용 `/plugins`를 활성화합니다. - `channels..configWrites`는 채널별 구성 변경을 제어합니다(기본값: true). -- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`)를 제어합니다. +- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기를 제어합니다(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`). - `restart: false`는 `/restart`와 gateway restart 도구 작업을 비활성화합니다. 기본값: `true`. - `ownerAllowFrom`은 소유자 전용 명령/도구를 위한 명시적 소유자 허용 목록입니다. `allowFrom`과는 별개입니다. - `ownerDisplay: "hash"`는 시스템 프롬프트에서 소유자 ID를 해시합니다. 해시를 제어하려면 `ownerDisplaySecret`을 설정하세요. -- `allowFrom`은 공급자별입니다. 설정되면 이것이 **유일한** 인증 소스가 됩니다(채널 허용 목록/페어링 및 `useAccessGroups`는 무시됨). -- `useAccessGroups: false`는 `allowFrom`이 설정되지 않은 경우 명령이 접근 그룹 정책을 우회할 수 있게 합니다. +- `allowFrom`은 provider별입니다. 설정되면 이것이 **유일한** 권한 부여 소스가 됩니다(채널 허용 목록/페어링과 `useAccessGroups`는 무시됨). +- `useAccessGroups: false`는 `allowFrom`이 설정되지 않은 경우 명령이 액세스 그룹 정책을 우회할 수 있게 합니다. - 명령 문서 맵: - - 내장 + 번들 카탈로그: [Slash Commands](/ko/tools/slash-commands) - - 채널별 명령 표면: [Channels](/ko/channels) + - 내장 + 번들 카탈로그: [슬래시 명령어](/ko/tools/slash-commands) + - 채널별 명령 표면: [채널](/ko/channels) - QQ Bot 명령: [QQ Bot](/ko/channels/qqbot) - 페어링 명령: [Pairing](/ko/channels/pairing) - LINE 카드 명령: [LINE](/ko/channels/line) @@ -898,7 +898,7 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ### `agents.defaults.repoRoot` -시스템 프롬프트의 Runtime 줄에 표시되는 선택적 리포지토리 루트입니다. 설정되지 않으면 OpenClaw가 workspace에서 위로 탐색하며 자동 감지합니다. +시스템 프롬프트의 Runtime 줄에 표시되는 선택적 저장소 루트입니다. 설정되지 않으면 OpenClaw가 워크스페이스에서 위쪽으로 탐색하며 자동 감지합니다. ```json5 { @@ -908,7 +908,7 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. ### `agents.defaults.skills` -`agents.list[].skills`를 설정하지 않은 에이전트에 대한 선택적 기본 skill 허용 목록입니다. +`agents.list[].skills`를 설정하지 않은 에이전트에 대한 선택적 기본 Skills 허용 목록입니다. ```json5 { @@ -917,20 +917,20 @@ IRC는 확장 기반이며 `channels.irc` 아래에 구성됩니다. list: [ { id: "writer" }, // github, weather 상속 { id: "docs", skills: ["docs-search"] }, // 기본값 대체 - { id: "locked-down", skills: [] }, // skill 없음 + { id: "locked-down", skills: [] }, // Skills 없음 ], }, } ``` -- 기본적으로 Skills를 제한하지 않으려면 `agents.defaults.skills`를 생략하세요. +- 기본적으로 제한 없는 Skills을 원하면 `agents.defaults.skills`를 생략하세요. - 기본값을 상속하려면 `agents.list[].skills`를 생략하세요. -- Skills 없음으로 설정하려면 `agents.list[].skills: []`를 사용하세요. +- Skills이 없도록 하려면 `agents.list[].skills: []`로 설정하세요. - 비어 있지 않은 `agents.list[].skills` 목록은 해당 에이전트의 최종 집합이며 기본값과 병합되지 않습니다. ### `agents.defaults.skipBootstrap` -workspace bootstrap 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`)의 자동 생성을 비활성화합니다. +워크스페이스 bootstrap 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`)의 자동 생성을 비활성화합니다. ```json5 { @@ -940,9 +940,9 @@ workspace bootstrap 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `U ### `agents.defaults.contextInjection` -workspace bootstrap 파일을 시스템 프롬프트에 언제 주입할지 제어합니다. 기본값: `"always"`. +워크스페이스 bootstrap 파일이 시스템 프롬프트에 주입되는 시점을 제어합니다. 기본값: `"always"`. -- `"continuation-skip"`: 안전한 후속 턴(assistant 응답이 완료된 뒤)에서는 workspace bootstrap 재주입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행과 Compaction 후 재시도에서는 여전히 컨텍스트를 다시 빌드합니다. +- `"continuation-skip"`: 안전한 이어쓰기 턴(assistant 응답 완료 후)에서는 워크스페이스 bootstrap 재주입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행과 Compaction 후 재시도에서는 계속 컨텍스트를 재구성합니다. ```json5 { @@ -952,7 +952,7 @@ workspace bootstrap 파일을 시스템 프롬프트에 언제 주입할지 제 ### `agents.defaults.bootstrapMaxChars` -잘리기 전 workspace bootstrap 파일당 최대 문자 수입니다. 기본값: `12000`. +잘리기 전 워크스페이스 bootstrap 파일당 최대 문자 수입니다. 기본값: `12000`. ```json5 { @@ -962,7 +962,7 @@ workspace bootstrap 파일을 시스템 프롬프트에 언제 주입할지 제 ### `agents.defaults.bootstrapTotalMaxChars` -모든 workspace bootstrap 파일에 걸쳐 주입되는 총 최대 문자 수입니다. 기본값: `60000`. +모든 워크스페이스 bootstrap 파일에 걸쳐 주입되는 총 최대 문자 수입니다. 기본값: `60000`. ```json5 { @@ -975,7 +975,7 @@ workspace bootstrap 파일을 시스템 프롬프트에 언제 주입할지 제 bootstrap 컨텍스트가 잘렸을 때 에이전트에 표시되는 경고 텍스트를 제어합니다. 기본값: `"once"`. -- `"off"`: 시스템 프롬프트에 경고 텍스트를 절대 주입하지 않습니다. +- `"off"`: 경고 텍스트를 시스템 프롬프트에 절대 주입하지 않습니다. - `"once"`: 고유한 잘림 시그니처마다 한 번만 경고를 주입합니다(권장). - `"always"`: 잘림이 있을 때마다 모든 실행에서 경고를 주입합니다. @@ -987,28 +987,28 @@ bootstrap 컨텍스트가 잘렸을 때 에이전트에 표시되는 경고 텍 ### 컨텍스트 예산 소유권 맵 -OpenClaw에는 대용량 프롬프트/컨텍스트 예산이 여러 개 있으며, 의도적으로 하나의 일반 설정이 아니라 하위 시스템별로 나뉘어 있습니다. +OpenClaw에는 고용량 프롬프트/컨텍스트 예산이 여러 개 있으며, 의도적으로 하나의 일반 조절 항목으로 모두 흐르지 않고 하위 시스템별로 분리되어 있습니다. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - 일반 workspace bootstrap 주입. + 일반 워크스페이스 bootstrap 주입. - `agents.defaults.startupContext.*`: - 최근 일별 `memory/*.md` 파일을 포함하는 일회성 `/new` 및 `/reset` 시작 프렐류드. + 최근 일일 `memory/*.md` 파일을 포함하는 일회성 `/new` 및 `/reset` 시작 프렐류드. - `skills.limits.*`: - 시스템 프롬프트에 주입되는 축약 Skills 목록. + 시스템 프롬프트에 주입되는 간결한 Skills 목록. - `agents.defaults.contextLimits.*`: - 범위가 제한된 런타임 발췌 및 런타임 소유 블록 주입. + 경계가 정해진 런타임 발췌 및 런타임 소유 블록 주입. - `memory.qmd.limits.*`: - 인덱싱된 메모리 검색 스니펫 및 주입 크기 조정. + 인덱싱된 memory-search 스니펫 및 주입 크기 조정. -특정 에이전트 하나에만 다른 예산이 필요할 때만 해당 에이전트별 재정의를 사용하세요: +한 에이전트에만 다른 예산이 필요할 때는 일치하는 에이전트별 재정의를 사용하세요: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -빈 `/new` 및 `/reset` 실행에 주입되는 첫 턴 시작 프렐류드를 제어합니다. +기본 `/new` 및 `/reset` 실행에 주입되는 첫 턴 시작 프렐류드를 제어합니다. ```json5 { @@ -1029,7 +1029,7 @@ OpenClaw에는 대용량 프롬프트/컨텍스트 예산이 여러 개 있으 #### `agents.defaults.contextLimits` -범위가 제한된 런타임 컨텍스트 표면에 대한 공유 기본값입니다. +경계가 있는 런타임 컨텍스트 표면에 대한 공유 기본값입니다. ```json5 { @@ -1046,14 +1046,14 @@ OpenClaw에는 대용량 프롬프트/컨텍스트 예산이 여러 개 있으 } ``` -- `memoryGetMaxChars`: 잘림 메타데이터와 계속 알림이 추가되기 전의 기본 `memory_get` 발췌 상한입니다. -- `memoryGetDefaultLines`: `lines`가 생략되었을 때의 기본 `memory_get` 줄 범위입니다. -- `toolResultMaxChars`: 저장된 결과 및 오버플로 복구에 사용되는 라이브 도구 결과 상한입니다. +- `memoryGetMaxChars`: 잘림 메타데이터 및 이어보기 알림이 추가되기 전 기본 `memory_get` 발췌 상한입니다. +- `memoryGetDefaultLines`: `lines`를 생략했을 때 기본 `memory_get` 줄 창입니다. +- `toolResultMaxChars`: 지속된 결과 및 오버플로 복구에 사용되는 라이브 도구 결과 상한입니다. - `postCompactionMaxChars`: Compaction 후 새로고침 주입 중 사용되는 AGENTS.md 발췌 상한입니다. #### `agents.list[].contextLimits` -공유 `contextLimits` 설정에 대한 에이전트별 재정의입니다. 생략된 필드는 `agents.defaults.contextLimits`에서 상속됩니다. +공유 `contextLimits` 조절 항목에 대한 에이전트별 재정의입니다. 생략된 필드는 `agents.defaults.contextLimits`에서 상속됩니다. ```json5 { @@ -1079,7 +1079,7 @@ OpenClaw에는 대용량 프롬프트/컨텍스트 예산이 여러 개 있으 #### `skills.limits.maxSkillsPromptChars` -시스템 프롬프트에 주입되는 축약 Skills 목록의 전역 상한입니다. 이는 필요 시 `SKILL.md` 파일을 읽는 동작에는 영향을 주지 않습니다. +시스템 프롬프트에 주입되는 간결한 Skills 목록의 전역 상한입니다. 이는 필요 시 `SKILL.md` 파일을 읽는 동작에는 영향을 주지 않습니다. ```json5 { @@ -1112,11 +1112,11 @@ Skills 프롬프트 예산에 대한 에이전트별 재정의입니다. ### `agents.defaults.imageMaxDimensionPx` -공급자 호출 전에 transcript/tool 이미지 블록에서 이미지의 가장 긴 변에 허용되는 최대 픽셀 크기입니다. +provider 호출 전에 transcript/tool 이미지 블록에서 가장 긴 이미지 변의 최대 픽셀 크기입니다. 기본값: `1200`. -값을 낮추면 일반적으로 스크린샷이 많은 실행에서 비전 토큰 사용량과 요청 페이로드 크기가 줄어듭니다. -값을 높이면 더 많은 시각적 세부 정보가 보존됩니다. +값이 낮을수록 일반적으로 스크린샷이 많은 실행에서 vision 토큰 사용량과 요청 페이로드 크기가 줄어듭니다. +값이 높을수록 더 많은 시각적 세부 정보가 유지됩니다. ```json5 { @@ -1126,7 +1126,7 @@ Skills 프롬프트 예산에 대한 에이전트별 재정의입니다. ### `agents.defaults.userTimezone` -시스템 프롬프트 컨텍스트용 시간대입니다(메시지 타임스탬프 아님). 호스트 시간대로 대체됩니다. +시스템 프롬프트 컨텍스트용 시간대입니다(메시지 타임스탬프 아님). 호스트 시간대를 대체값으로 사용합니다. ```json5 { @@ -1174,9 +1174,9 @@ Skills 프롬프트 예산에 대한 에이전트별 재정의입니다. primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 전역 기본 공급자 params + params: { cacheRetention: "long" }, // 전역 기본 provider params embeddedHarness: { - runtime: "auto", // auto | pi | 등록된 harness id, 예: codex + runtime: "auto", // auto | pi | 등록된 harness id(예: codex) fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1195,46 +1195,46 @@ Skills 프롬프트 예산에 대한 에이전트별 재정의입니다. - `model`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - 문자열 형식은 기본 모델만 설정합니다. - - 객체 형식은 기본 모델과 순서가 있는 장애 조치 모델을 함께 설정합니다. + - 객체 형식은 기본 모델과 순서가 있는 failover 모델을 설정합니다. - `imageModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - `image` 도구 경로에서 비전 모델 구성으로 사용됩니다. - 선택된/기본 모델이 이미지 입력을 받을 수 없을 때 대체 라우팅에도 사용됩니다. - `imageGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 이미지 생성 기능과 향후 이미지 생성 도구/Plugin 표면에서 사용됩니다. - - 일반적인 값: 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 순서대로 시도합니다. + - 공통 이미지 생성 capability와 앞으로 추가될 이미지 생성 도구/Plugin 표면에서 사용됩니다. + - 일반적인 값: Gemini 네이티브 이미지 생성용 `google/gemini-3.1-flash-image-preview`, fal용 `fal/fal-ai/flux/dev`, OpenAI Images용 `openai/gpt-image-1`. + - provider/model을 직접 선택하는 경우, 해당 provider 인증/API 키도 함께 구성하세요(예: `google/*`에는 `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`, `openai/*`에는 `OPENAI_API_KEY`, `fal/*`에는 `FAL_KEY`). + - 생략해도 `image_generate`는 인증이 설정된 provider 기본값을 추론할 수 있습니다. 먼저 현재 기본 provider를 시도한 뒤, 나머지 등록된 이미지 생성 provider를 provider ID 순서대로 시도합니다. - `musicGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 음악 생성 기능과 내장 `music_generate` 도구에서 사용됩니다. + - 공통 음악 생성 capability와 내장 `music_generate` 도구에서 사용됩니다. - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, `minimax/music-2.5+`. - - 생략하더라도 `music_generate`는 인증이 설정된 공급자 기본값을 추론할 수 있습니다. 먼저 현재 기본 공급자를 시도한 다음, 등록된 나머지 음악 생성 공급자를 공급자 ID 순서대로 시도합니다. - - 공급자/모델을 직접 선택하는 경우 해당 공급자 인증/API 키도 함께 구성하세요. + - 생략해도 `music_generate`는 인증이 설정된 provider 기본값을 추론할 수 있습니다. 먼저 현재 기본 provider를 시도한 뒤, 나머지 등록된 음악 생성 provider를 provider ID 순서대로 시도합니다. + - provider/model을 직접 선택하는 경우, 해당 provider 인증/API 키도 함께 구성하세요. - `videoGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 비디오 생성 기능과 내장 `video_generate` 도구에서 사용됩니다. + - 공통 비디오 생성 capability와 내장 `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`는 인증이 설정된 provider 기본값을 추론할 수 있습니다. 먼저 현재 기본 provider를 시도한 뒤, 나머지 등록된 비디오 생성 provider를 provider ID 순서대로 시도합니다. + - provider/model을 직접 선택하는 경우, 해당 provider 인증/API 키도 함께 구성하세요. + - 번들된 Qwen 비디오 생성 provider는 최대 출력 비디오 1개, 입력 이미지 1개, 입력 비디오 4개, 길이 10초, 그리고 provider 수준 `size`, `aspectRatio`, `resolution`, `audio`, `watermark` 옵션을 지원합니다. - `pdfModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - `pdf` 도구의 모델 라우팅에 사용됩니다. - - 생략하면 PDF 도구는 먼저 `imageModel`, 그다음 해석된 세션/기본 모델로 대체합니다. -- `pdfMaxBytesMb`: 호출 시점에 `maxBytesMb`가 전달되지 않았을 때 `pdf` 도구에 적용되는 기본 PDF 크기 제한입니다. + - `pdf` 도구에서 모델 라우팅에 사용됩니다. + - 생략하면 PDF 도구는 `imageModel`로, 그다음 해석된 세션/기본 모델로 대체됩니다. +- `pdfMaxBytesMb`: 호출 시 `maxBytesMb`를 전달하지 않았을 때 `pdf` 도구에 적용되는 기본 PDF 크기 제한입니다. - `pdfMaxPages`: `pdf` 도구의 추출 대체 모드에서 고려하는 기본 최대 페이지 수입니다. -- `verboseDefault`: 에이전트의 기본 verbose 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. +- `verboseDefault`: 에이전트의 기본 상세 출력 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. - `elevatedDefault`: 에이전트의 기본 elevated-output 수준입니다. 값: `"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)가 키별로 재정의합니다. 자세한 내용은 [Prompt Caching](/ko/reference/prompt-caching)을 참조하세요. -- `embeddedHarness`: 기본 저수준 내장 에이전트 런타임 정책입니다. 등록된 Plugin harness가 지원되는 모델을 가져가도록 하려면 `runtime: "auto"`를 사용하고, 내장 PI harness를 강제하려면 `runtime: "pi"`를, `runtime: "codex"`처럼 등록된 harness ID를 직접 지정할 수도 있습니다. 자동 PI 대체를 비활성화하려면 `fallback: "none"`을 설정하세요. -- 이 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, 대체 추가/제거 명령)는 표준 객체 형식으로 저장하며 가능하면 기존 대체 목록을 유지합니다. -- `maxConcurrent`: 세션 간 최대 병렬 에이전트 실행 수입니다(각 세션 내부는 여전히 직렬화됨). 기본값: 4. +- `model.primary`: 형식은 `provider/model`입니다(예: `openai/gpt-5.4`). provider를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 해당 정확한 모델 ID에 대한 고유한 구성 provider 일치를 시도한 후, 마지막으로 구성된 기본 provider로 대체합니다(호환성을 위한 더 이상 권장되지 않는 동작이므로 명시적인 `provider/model`을 권장). 해당 provider가 더 이상 구성된 기본 모델을 제공하지 않으면, OpenClaw는 제거된 provider의 오래된 기본값을 그대로 노출하는 대신 구성된 첫 번째 provider/model로 대체합니다. +- `models`: `/model`용 구성된 모델 카탈로그 및 허용 목록입니다. 각 항목에는 `alias`(단축 이름)와 `params`(provider별 설정, 예: `temperature`, `maxTokens`, `cacheRetention`, `context1m`)를 포함할 수 있습니다. +- `params`: 모든 모델에 적용되는 전역 기본 provider 매개변수입니다. `agents.defaults.params`에서 설정합니다(예: `{ cacheRetention: "long" }`). +- `params` 병합 우선순위(구성): `agents.defaults.params`(전역 기본값)는 `agents.defaults.models["provider/model"].params`(모델별)로 덮어써지고, 그다음 `agents.list[].params`(일치하는 에이전트 ID)가 키별로 덮어씁니다. 자세한 내용은 [Prompt Caching](/ko/reference/prompt-caching)을 참조하세요. +- `embeddedHarness`: 기본 저수준 임베디드 에이전트 런타임 정책입니다. `runtime: "auto"`를 사용하면 등록된 plugin harness가 지원하는 모델을 가져갈 수 있고, `runtime: "pi"`를 사용하면 내장 PI harness를 강제하며, `runtime: "codex"`처럼 등록된 harness ID를 지정할 수도 있습니다. 자동 PI 대체를 비활성화하려면 `fallback: "none"`을 설정하세요. +- 이러한 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, fallback 추가/제거 명령)는 정식 객체 형식으로 저장하며, 가능한 경우 기존 fallback 목록을 보존합니다. +- `maxConcurrent`: 세션 전반에서 병렬로 실행할 수 있는 최대 에이전트 수입니다(각 세션은 여전히 직렬화됨). 기본값: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness`는 어떤 저수준 실행기가 내장 에이전트 턴을 실행할지 제어합니다. -대부분의 배포에서는 기본값 `{ runtime: "auto", fallback: "pi" }`를 유지하는 것이 좋습니다. -번들 Codex 앱 서버 harness처럼 신뢰할 수 있는 Plugin이 네이티브 harness를 제공하는 경우에 사용하세요. +`embeddedHarness`는 어떤 저수준 실행기가 임베디드 에이전트 턴을 실행할지 제어합니다. +대부분의 배포에서는 기본값인 `{ runtime: "auto", fallback: "pi" }`를 유지하면 됩니다. +번들된 Codex app-server harness처럼 신뢰할 수 있는 Plugin이 네이티브 harness를 제공할 때 사용하세요. ```json5 { @@ -1250,13 +1250,13 @@ Skills 프롬프트 예산에 대한 에이전트별 재정의입니다. } ``` -- `runtime`: `"auto"`, `"pi"`, 또는 등록된 Plugin harness ID입니다. 번들 Codex Plugin은 `codex`를 등록합니다. -- `fallback`: `"pi"` 또는 `"none"`입니다. `"pi"`는 내장 PI harness를 호환성 대체로 유지합니다. `"none"`은 누락되었거나 지원되지 않는 Plugin harness 선택 시 조용히 PI를 사용하는 대신 실패하게 합니다. +- `runtime`: `"auto"`, `"pi"`, 또는 등록된 Plugin 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는 여전히 각자의 공급자/모델 설정을 사용합니다. +- Codex 전용 배포에서는 `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"`, `embeddedHarness.fallback: "none"`으로 설정하세요. +- 이는 임베디드 채팅 harness만 제어합니다. 미디어 생성, 비전, PDF, 음악, 비디오, TTS는 여전히 해당 provider/model 설정을 사용합니다. -**내장 별칭 단축 이름** (`agents.defaults.models`에 모델이 있을 때만 적용됨): +**내장 별칭 단축형** (`agents.defaults.models`에 모델이 있을 때만 적용됨): | 별칭 | 모델 | | ------------------- | -------------------------------------- | @@ -1277,7 +1277,7 @@ Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않 ### `agents.defaults.cliBackends` -텍스트 전용 대체 실행(도구 호출 없음)을 위한 선택적 CLI 백엔드입니다. API 공급자가 실패할 때 백업으로 유용합니다. +텍스트 전용 대체 실행(도구 호출 없음)을 위한 선택적 CLI 백엔드입니다. API provider가 실패할 때 백업으로 유용합니다. ```json5 { @@ -1305,13 +1305,13 @@ Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않 } ``` -- CLI 백엔드는 텍스트 우선이며 도구는 항상 비활성화됩니다. -- `sessionArg`가 설정된 경우 세션을 지원합니다. -- `imageArg`가 파일 경로를 받을 수 있으면 이미지 전달도 지원됩니다. +- CLI 백엔드는 텍스트 우선이며, 도구는 항상 비활성화됩니다. +- `sessionArg`가 설정되어 있으면 세션이 지원됩니다. +- `imageArg`가 파일 경로를 받을 수 있으면 이미지 전달이 지원됩니다. ### `agents.defaults.systemPromptOverride` -OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대체합니다. 기본 수준(`agents.defaults.systemPromptOverride`) 또는 에이전트별(`agents.list[].systemPromptOverride`)로 설정할 수 있습니다. 에이전트별 값이 우선하며, 비어 있거나 공백만 있는 값은 무시됩니다. 제어된 프롬프트 실험에 유용합니다. +OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대체합니다. 기본 수준(`agents.defaults.systemPromptOverride`) 또는 에이전트별(`agents.list[].systemPromptOverride`)로 설정할 수 있습니다. 에이전트별 값이 우선하며, 빈 문자열 또는 공백만 있는 값은 무시됩니다. 통제된 프롬프트 실험에 유용합니다. ```json5 { @@ -1336,11 +1336,11 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 model: "openai/gpt-5.4-mini", includeReasoning: false, includeSystemPromptSection: true, // 기본값: true; false이면 시스템 프롬프트에서 Heartbeat 섹션 생략 - lightContext: false, // 기본값: false; true이면 workspace bootstrap 파일 중 HEARTBEAT.md만 유지 + lightContext: false, // 기본값: false; true이면 워크스페이스 bootstrap 파일 중 HEARTBEAT.md만 유지 isolatedSession: false, // 기본값: false; true이면 각 Heartbeat를 새 세션에서 실행(대화 기록 없음) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (기본값) | block + directPolicy: "allow", // allow(기본값) | block target: "none", // 기본값: none | 옵션: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, @@ -1354,13 +1354,13 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 - `every`: 기간 문자열(ms/s/m/h)입니다. 기본값: `30m`(API 키 인증) 또는 `1h`(OAuth 인증). 비활성화하려면 `0m`으로 설정하세요. - `includeSystemPromptSection`: false이면 시스템 프롬프트에서 Heartbeat 섹션을 생략하고 bootstrap 컨텍스트에 `HEARTBEAT.md`를 주입하지 않습니다. 기본값: `true`. -- `suppressToolErrorWarnings`: true이면 Heartbeat 실행 중 도구 오류 경고 페이로드를 억제합니다. +- `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는 전체 에이전트 턴을 실행하므로 간격이 짧을수록 더 많은 토큰을 소모합니다. +- `lightContext`: true이면 Heartbeat 실행은 경량 bootstrap 컨텍스트를 사용하고 워크스페이스 bootstrap 파일 중 `HEARTBEAT.md`만 유지합니다. +- `isolatedSession`: true이면 각 Heartbeat 실행은 이전 대화 기록이 없는 새 세션에서 수행됩니다. Cron의 `sessionTarget: "isolated"`와 같은 격리 패턴입니다. Heartbeat당 토큰 비용을 약 ~100K에서 ~2-5K 토큰으로 줄입니다. +- 에이전트별: `agents.list[].heartbeat`를 설정하세요. 어떤 에이전트든 `heartbeat`를 정의하면 **해당 에이전트들만** Heartbeat를 실행합니다. +- Heartbeat는 전체 에이전트 턴을 실행하므로, 간격이 짧을수록 더 많은 토큰을 소모합니다. ### `agents.defaults.compaction` @@ -1370,19 +1370,19 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // 등록된 Compaction provider Plugin의 id(선택 사항) + provider: "my-provider", // 등록된 Compaction provider plugin의 id(선택 사항) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "배포 ID, 티켓 ID, host:port 쌍을 정확히 보존하세요.", // identifierPolicy=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) + notifyUser: true, // Compaction 시작 시 짧은 알림 전송(기본값: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "세션이 곧 Compaction됩니다. 지금 영구 메모리를 저장하세요.", - prompt: "지속되어야 할 메모리를 memory/YYYY-MM-DD.md에 기록하세요. 저장할 내용이 없으면 정확히 무음 토큰 NO_REPLY로 응답하세요.", + systemPrompt: "세션이 곧 Compaction됩니다. 지금 지속 메모리를 저장하세요.", + prompt: "지속되어야 할 메모를 memory/YYYY-MM-DD.md에 기록하세요. 저장할 내용이 없으면 정확한 무응답 토큰 NO_REPLY로 응답하세요.", }, }, }, @@ -1390,15 +1390,15 @@ OpenClaw가 조합한 전체 시스템 프롬프트를 고정 문자열로 대 } ``` -- `mode`: `default` 또는 `safeguard`(긴 기록을 위한 청크 단위 요약)입니다. [Compaction](/ko/concepts/compaction)을 참조하세요. -- `provider`: 등록된 Compaction provider Plugin의 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이 시작될 때 사용자에게 짧은 알림(예: "Compacting context...")을 보냅니다. 기본적으로는 Compaction을 조용히 유지하기 위해 비활성화되어 있습니다. -- `memoryFlush`: 자동 Compaction 전에 영구 메모리를 저장하기 위한 무음 agentic 턴입니다. workspace가 읽기 전용이면 건너뜁니다. +- `mode`: `default` 또는 `safeguard`(긴 기록에 대한 청크 기반 요약)입니다. [Compaction](/ko/concepts/compaction)을 참조하세요. +- `provider`: 등록된 Compaction provider plugin의 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이 시작될 때 사용자에게 짧은 알림을 보냅니다(예: `"Compacting context..."`). 기본적으로는 Compaction을 조용히 유지하기 위해 비활성화되어 있습니다. +- `memoryFlush`: 자동 Compaction 전에 지속 메모리를 저장하기 위한 무음 에이전트 턴입니다. 워크스페이스가 읽기 전용이면 건너뜁니다. ### `agents.defaults.contextPruning` @@ -1416,7 +1416,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 hardClearRatio: 0.5, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, + hardClear: { enabled: true, placeholder: "[오래된 도구 결과 내용이 지워졌습니다]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1426,23 +1426,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로 대체합니다. 참고: -- 이미지 블록은 절대 trim/clear되지 않습니다. -- 비율은 정확한 토큰 수가 아니라 문자 수 기준의 대략값입니다. -- `keepLastAssistants`보다 assistant 메시지가 적으면 가지치기를 건너뜁니다. +- 이미지 블록은 절대 잘리거나 지워지지 않습니다. +- 비율은 정확한 토큰 수가 아니라 문자 수 기반의 근사값입니다. +- assistant 메시지가 `keepLastAssistants`보다 적으면 제거를 건너뜁니다. -동작 세부 정보는 [Session Pruning](/ko/concepts/session-pruning)을 참조하세요. +동작 세부 사항은 [세션 가지치기](/ko/concepts/session-pruning)를 참조하세요. ### 블록 스트리밍 @@ -1460,13 +1460,13 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 } ``` -- Telegram이 아닌 채널에서는 블록 응답을 활성화하려면 명시적으로 `*.blockStreaming: true`가 필요합니다. +- Telegram이 아닌 채널에서는 블록 응답을 활성화하려면 명시적으로 `*.blockStreaming: true`를 설정해야 합니다. - 채널 재정의: `channels..blockStreamingCoalesce`(및 계정별 변형). Signal/Slack/Discord/Google Chat의 기본 `minChars`는 `1500`입니다. - `humanDelay`: 블록 응답 사이의 무작위 지연입니다. `natural` = 800–2500ms. 에이전트별 재정의: `agents.list[].humanDelay`. -동작 및 청킹 세부 정보는 [Streaming](/ko/concepts/streaming)을 참조하세요. +동작 + 청크 세부 사항은 [Streaming](/ko/concepts/streaming)을 참조하세요. -### 타이핑 표시기 +### 입력 중 표시기 ```json5 { @@ -1488,7 +1488,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 ### `agents.defaults.sandbox` -내장 에이전트를 위한 선택적 sandboxing입니다. 전체 가이드는 [Sandboxing](/ko/gateway/sandboxing)을 참조하세요. +임베디드 에이전트를 위한 선택적 샌드박싱입니다. 전체 가이드는 [샌드박싱](/ko/gateway/sandboxing)을 참조하세요. ```json5 { @@ -1534,7 +1534,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRef / 인라인 내용도 지원됨: + // SecretRef / 인라인 내용도 지원: // 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" }, @@ -1583,7 +1583,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 } ``` - + **백엔드:** @@ -1591,44 +1591,44 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 - `ssh`: 범용 SSH 기반 원격 런타임 - `openshell`: OpenShell 런타임 -`backend: "openshell"`이 선택되면 런타임별 설정은 +`backend: "openshell"`을 선택하면 런타임별 설정은 `plugins.entries.openshell.config`로 이동합니다. **SSH 백엔드 구성:** - `target`: `user@host[:port]` 형식의 SSH 대상 - `command`: SSH 클라이언트 명령(기본값: `ssh`) -- `workspaceRoot`: 범위별 workspace에 사용되는 절대 원격 루트 +- `workspaceRoot`: 범위별 워크스페이스에 사용되는 절대 원격 루트 - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH에 전달되는 기존 로컬 파일 - `identityData` / `certificateData` / `knownHostsData`: OpenClaw가 런타임에 임시 파일로 구체화하는 인라인 내용 또는 SecretRef -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH 호스트 키 정책 설정 +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH 호스트 키 정책 조절 항목 **SSH 인증 우선순위:** -- `identityData`가 `identityFile`보다 우선 -- `certificateData`가 `certificateFile`보다 우선 -- `knownHostsData`가 `knownHostsFile`보다 우선 -- SecretRef 기반 `*Data` 값은 sandbox 세션 시작 전에 활성 secrets 런타임 스냅샷에서 해석됩니다 +- `identityData`가 `identityFile`보다 우선합니다 +- `certificateData`가 `certificateFile`보다 우선합니다 +- `knownHostsData`가 `knownHostsFile`보다 우선합니다 +- SecretRef 기반 `*Data` 값은 샌드박스 세션이 시작되기 전에 활성 비밀 런타임 스냅샷에서 해석됩니다 **SSH 백엔드 동작:** -- 생성 또는 재생성 후 원격 workspace를 한 번 시드합니다 -- 이후에는 원격 SSH workspace를 표준으로 유지합니다 +- 생성 또는 재생성 후 원격 워크스페이스를 한 번 시드합니다 +- 그 후 원격 SSH 워크스페이스를 정식 상태로 유지합니다 - `exec`, 파일 도구, 미디어 경로를 SSH를 통해 라우팅합니다 - 원격 변경 사항을 호스트로 자동 동기화하지 않습니다 -- sandbox 브라우저 컨테이너는 지원하지 않습니다 +- 샌드박스 브라우저 컨테이너를 지원하지 않습니다 -**Workspace 접근:** +**워크스페이스 접근:** -- `none`: `~/.openclaw/sandboxes` 아래 범위별 sandbox workspace -- `ro`: `/workspace`의 sandbox workspace, `/agent`에 읽기 전용으로 마운트된 agent workspace -- `rw`: agent workspace를 `/workspace`에 읽기/쓰기 가능하게 마운트 +- `none`: `~/.openclaw/sandboxes` 아래 범위별 샌드박스 워크스페이스 +- `ro`: 샌드박스 워크스페이스는 `/workspace`, 에이전트 워크스페이스는 `/agent`에 읽기 전용 마운트 +- `rw`: 에이전트 워크스페이스를 `/workspace`에 읽기/쓰기 마운트 **범위:** -- `session`: 세션별 컨테이너 + workspace -- `agent`: 에이전트별 컨테이너 + workspace 1개(기본값) -- `shared`: 공유 컨테이너 및 workspace(세션 간 격리 없음) +- `session`: 세션별 컨테이너 + 워크스페이스 +- `agent`: 에이전트별 컨테이너 + 워크스페이스 1개(기본값) +- `shared`: 공유 컨테이너 및 워크스페이스(세션 간 격리 없음) **OpenShell Plugin 구성:** @@ -1645,7 +1645,7 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 remoteAgentWorkspaceDir: "/agent", gateway: "lab", // 선택 사항 gatewayEndpoint: "https://lab.example", // 선택 사항 - policy: "strict", // 선택적 OpenShell policy id + policy: "strict", // 선택적 OpenShell 정책 id providers: ["openai"], // 선택 사항 autoProviders: true, timeoutSeconds: 120, @@ -1658,32 +1658,32 @@ LLM에 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결 **OpenShell 모드:** -- `mirror`: exec 전에 로컬에서 원격으로 시드하고, exec 후 다시 동기화; 로컬 workspace가 표준으로 유지됨 -- `remote`: sandbox 생성 시 원격을 한 번 시드한 뒤, 이후에는 원격 workspace를 표준으로 유지 +- `mirror`: 실행 전에 로컬에서 원격으로 시드하고, 실행 후 다시 동기화합니다. 로컬 워크스페이스가 정식 상태로 유지됩니다 +- `remote`: 샌드박스가 생성될 때 원격을 한 번 시드한 뒤, 원격 워크스페이스를 정식 상태로 유지합니다 -`remote` 모드에서는 호스트 로컬에서 OpenClaw 외부에서 이루어진 편집이 시드 단계 이후 sandbox에 자동 동기화되지 않습니다. -전송은 SSH를 통해 OpenShell sandbox로 이루어지지만, sandbox 수명 주기와 선택적 mirror 동기화는 Plugin이 관리합니다. +`remote` 모드에서는 OpenClaw 외부에서 만든 호스트 로컬 편집 내용이 시드 단계 이후 샌드박스로 자동 동기화되지 않습니다. +전송은 OpenShell 샌드박스로의 SSH를 사용하지만, 샌드박스 수명 주기와 선택적 미러 동기화는 Plugin이 소유합니다. -**`setupCommand`**는 컨테이너 생성 후 한 번 실행됩니다(`sh -lc` 사용). 네트워크 송신, 쓰기 가능한 루트, 루트 사용자 권한이 필요합니다. +**`setupCommand`**는 컨테이너 생성 후 한 번 실행됩니다(`sh -lc` 사용). 네트워크 송신, 쓰기 가능한 루트, root 사용자가 필요합니다. -**컨테이너 기본값은 `network: "none"`**입니다 — 에이전트에 외부 접근이 필요하면 `"bridge"`(또는 사용자 지정 브리지 네트워크)로 설정하세요. -`"host"`는 차단됩니다. `"container:"`도 기본적으로 차단되며, -명시적으로 `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`(비상 모드)를 설정한 경우에만 허용됩니다. +**컨테이너는 기본적으로 `network: "none"`입니다** — 에이전트에 외부 접근이 필요하면 `"bridge"`(또는 사용자 지정 브리지 네트워크)로 설정하세요. +`"host"`는 차단됩니다. `"container:"`도 기본적으로 차단되며, 명시적으로 +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`(비상용)를 설정한 경우에만 허용됩니다. -**수신 첨부 파일**은 활성 workspace의 `media/inbound/*`에 스테이징됩니다. +**수신 첨부 파일**은 활성 워크스페이스의 `media/inbound/*`에 스테이징됩니다. -**`docker.binds`**는 추가 호스트 디렉터리를 마운트합니다. 전역 및 에이전트별 bind는 병합됩니다. +**`docker.binds`**는 추가 호스트 디렉터리를 마운트합니다. 전역 및 에이전트별 바인드는 병합됩니다. -**Sandbox 브라우저** (`sandbox.browser.enabled`): 컨테이너 안에서 실행되는 Chromium + CDP입니다. noVNC URL이 시스템 프롬프트에 주입됩니다. `openclaw.json`에서 `browser.enabled`는 필요하지 않습니다. -noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 짧은 수명의 토큰 URL을 생성합니다. +**샌드박스 브라우저**(`sandbox.browser.enabled`): 컨테이너 내부에서 실행되는 Chromium + CDP입니다. noVNC URL이 시스템 프롬프트에 주입됩니다. `openclaw.json`에서 `browser.enabled`가 필요하지 않습니다. +noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 짧은 수명의 토큰 URL을 발급합니다. -- `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`에 정의되어 있으며 컨테이너 호스트에 맞게 조정되어 있습니다: +- `allowHostControl: false`(기본값)는 샌드박스 세션이 호스트 브라우저를 대상으로 삼는 것을 차단합니다. +- `network`의 기본값은 `openclaw-sandbox-browser`(전용 브리지 네트워크)입니다. 전역 브리지 연결이 명시적으로 필요할 때만 `bridge`로 설정하세요. +- `cdpSourceRange`는 컨테이너 경계에서 CDP 유입을 CIDR 범위(예: `172.21.0.1/32`)로 선택적으로 제한합니다. +- `sandbox.browser.binds`는 추가 호스트 디렉터리를 샌드박스 브라우저 컨테이너에만 마운트합니다. 설정되면(`[]` 포함) 브라우저 컨테이너에서는 `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` @@ -1698,31 +1698,31 @@ noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (기본적으로 활성화됨) + - `--disable-extensions`(기본 활성화) - `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`는 - 기본적으로 활성화되며, WebGL/3D 사용에 필요하면 + 기본적으로 활성화되어 있으며, WebGL/3D 사용에 필요하면 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`으로 비활성화할 수 있습니다. - - 워크플로가 확장 기능에 의존한다면 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`으로 확장 기능을 다시 활성화할 수 있습니다. + - 워크플로가 확장 기능에 의존하는 경우 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`으로 + 확장 기능을 다시 활성화할 수 있습니다. - `--renderer-process-limit=2`는 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`으로 변경할 수 있으며, Chromium의 기본 프로세스 제한을 사용하려면 `0`으로 설정하세요. - `noSandbox`가 활성화된 경우 `--no-sandbox` 및 `--disable-setuid-sandbox`도 추가됩니다. - - 기본값은 컨테이너 이미지 기준선입니다. 컨테이너 기본값을 변경하려면 사용자 지정 - entrypoint가 포함된 사용자 지정 브라우저 이미지를 사용하세요. + - 기본값은 컨테이너 이미지 기준선입니다. 컨테이너 기본값을 바꾸려면 사용자 지정 + 엔트리포인트가 있는 사용자 지정 브라우저 이미지를 사용하세요. -브라우저 sandboxing 및 `sandbox.docker.binds`는 Docker 전용입니다. +브라우저 샌드박싱과 `sandbox.docker.binds`는 Docker에서만 지원됩니다. 이미지 빌드: ```bash -scripts/sandbox-setup.sh # 메인 sandbox 이미지 +scripts/sandbox-setup.sh # 메인 샌드박스 이미지 scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 ``` -### `agents.list` (에이전트별 재정의) +### `agents.list`(에이전트별 재정의) ```json5 { @@ -1735,12 +1735,12 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 또는 { primary, fallbacks } - thinkingDefault: "high", // 에이전트별 기본 thinking 수준 재정의 - reasoningDefault: "on", // 에이전트별 기본 reasoning 가시성 재정의 - fastModeDefault: false, // 에이전트별 빠른 모드 재정의 + thinkingDefault: "high", // 에이전트별 thinking 수준 재정의 + reasoningDefault: "on", // 에이전트별 reasoning 표시 재정의 + fastModeDefault: false, // 에이전트별 fast mode 재정의 embeddedHarness: { runtime: "auto", fallback: "pi" }, params: { cacheRetention: "none" }, // 일치하는 defaults.models params를 키별로 재정의 - skills: ["docs-search"], // 설정되면 agents.defaults.skills를 대체 + skills: ["docs-search"], // 설정 시 agents.defaults.skills를 대체 identity: { name: "Samantha", theme: "helpful sloth", @@ -1771,27 +1771,27 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 } ``` -- `id`: 안정적인 에이전트 ID(필수). -- `default`: 여러 개가 설정된 경우 첫 번째가 우선합니다(경고 로그 기록). 아무것도 설정되지 않으면 목록의 첫 번째 항목이 기본값입니다. -- `model`: 문자열 형식은 `primary`만 재정의하고, 객체 형식 `{ primary, fallbacks }`는 둘 다 재정의합니다(`[]`는 전역 대체 모델 비활성화). `primary`만 재정의하는 Cron 작업은 `fallbacks: []`를 설정하지 않는 한 기본 대체 모델을 계속 상속합니다. -- `params`: `agents.defaults.models`에서 선택된 모델 항목 위에 병합되는 에이전트별 스트림 params입니다. 전체 모델 카탈로그를 복제하지 않고 `cacheRetention`, `temperature`, `maxTokens` 같은 에이전트별 재정의에 사용하세요. -- `skills`: 선택적 에이전트별 skill 허용 목록입니다. 생략하면 에이전트는 설정된 경우 `agents.defaults.skills`를 상속합니다. 명시적 목록은 병합하지 않고 기본값을 대체하며, `[]`는 skill 없음입니다. -- `thinkingDefault`: 선택적 에이전트별 기본 thinking 수준(`off | minimal | low | medium | high | xhigh | adaptive`)입니다. 메시지별 또는 세션별 재정의가 없을 때 이 에이전트에 대해 `agents.defaults.thinkingDefault`를 재정의합니다. -- `reasoningDefault`: 선택적 에이전트별 기본 reasoning 가시성(`on | off | stream`)입니다. 메시지별 또는 세션별 reasoning 재정의가 없을 때 적용됩니다. -- `fastModeDefault`: 선택적 에이전트별 기본 빠른 모드 값(`true | false`)입니다. 메시지별 또는 세션별 빠른 모드 재정의가 없을 때 적용됩니다. -- `embeddedHarness`: 선택적 에이전트별 저수준 harness 정책 재정의입니다. 한 에이전트만 Codex 전용으로 만들고 다른 에이전트는 기본 PI 대체를 유지하려면 `{ runtime: "codex", fallback: "none" }`를 사용하세요. -- `runtime`: 선택적 에이전트별 런타임 기술자입니다. 에이전트가 기본적으로 ACP harness 세션을 사용해야 할 때 `type: "acp"`와 함께 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)을 사용하세요. -- `identity.avatar`: workspace 기준 상대 경로, `http(s)` URL 또는 `data:` URI입니다. -- `identity`는 기본값을 파생합니다: `emoji`에서 `ackReaction`, `name`/`emoji`에서 `mentionPatterns`. -- `subagents.allowAgents`: `sessions_spawn`용 에이전트 ID 허용 목록(`["*"]` = 모두 허용, 기본값: 동일 에이전트만). -- Sandbox 상속 가드: 요청 세션이 sandbox 상태이면 `sessions_spawn`은 sandbox 없이 실행될 대상을 거부합니다. +- `id`: 안정적인 에이전트 ID입니다(필수). +- `default`: 여러 개가 설정되면 첫 번째가 우선합니다(경고가 기록됨). 아무것도 설정되지 않으면 목록의 첫 번째 항목이 기본값입니다. +- `model`: 문자열 형식은 `primary`만 재정의하고, 객체 형식 `{ primary, fallbacks }`는 둘 다 재정의합니다(`[]`는 전역 fallback 비활성화). `primary`만 재정의하는 Cron 작업은 `fallbacks: []`를 설정하지 않는 한 여전히 기본 fallback을 상속합니다. +- `params`: `agents.defaults.models`의 선택된 모델 항목 위에 병합되는 에이전트별 스트림 params입니다. 전체 모델 카탈로그를 복제하지 않고 `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 fallback을 유지하려면 `{ runtime: "codex", fallback: "none" }`를 사용하세요. +- `runtime`: 선택적인 에이전트별 런타임 설명자입니다. 에이전트가 기본적으로 ACP harness 세션을 사용해야 하는 경우 `type: "acp"`와 함께 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)을 사용하세요. +- `identity.avatar`: 워크스페이스 기준 상대 경로, `http(s)` URL 또는 `data:` URI입니다. +- `identity`는 기본값을 파생합니다: `ackReaction`은 `emoji`에서, `mentionPatterns`는 `name`/`emoji`에서 생성됩니다. +- `subagents.allowAgents`: `sessions_spawn`용 에이전트 ID 허용 목록입니다(`["*"]` = 아무 에이전트나 허용, 기본값: 같은 에이전트만). +- 샌드박스 상속 가드: 요청 세션이 샌드박스된 경우 `sessions_spawn`은 샌드박스 없이 실행될 대상을 거부합니다. - `subagents.requireAgentId`: true이면 `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적 프로필 선택 강제, 기본값: false). --- ## 다중 에이전트 라우팅 -하나의 Gateway 안에서 여러 격리된 에이전트를 실행합니다. [Multi-Agent](/ko/concepts/multi-agent)를 참조하세요. +하나의 Gateway 안에서 여러 개의 격리된 에이전트를 실행합니다. [Multi-Agent](/ko/concepts/multi-agent)를 참조하세요. ```json5 { @@ -1808,31 +1808,31 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 } ``` -### 바인딩 일치 필드 +### 바인딩 match 필드 -- `type`(선택 사항): 일반 라우팅에는 `route`(type이 없으면 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 }` +- `acp`(선택 사항, `type: "acp"`에만 해당): `{ mode, label, cwd, backend }` -**결정적 일치 순서:** +**결정적 매치 순서:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (정확 일치, peer/guild/team 없음) -5. `match.accountId: "*"` (채널 전체) +4. `match.accountId`(정확 일치, peer/guild/team 없음) +5. `match.accountId: "*"`(채널 전체) 6. 기본 에이전트 -각 단계 안에서는 첫 번째로 일치하는 `bindings` 항목이 우선합니다. +각 계층 내에서는 처음 일치하는 `bindings` 항목이 우선합니다. -`type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 식별자(`match.channel` + account + `match.peer.id`)로 해석하며, 위의 route 바인딩 단계 순서를 사용하지 않습니다. +`type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 식별자(`match.channel` + account + `match.peer.id`)로 해석하며, 위의 route 바인딩 계층 순서를 사용하지 않습니다. -### 에이전트별 접근 프로필 +### 에이전트별 액세스 프로필 - + ```json5 { @@ -1850,7 +1850,7 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 - + ```json5 { @@ -1951,7 +1951,7 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 이 토큰 수를 초과하면 부모 스레드 포크 건너뜀(0이면 비활성화) + parentForkMaxTokens: 100000, // 이 토큰 수를 초과하면 상위 스레드 fork 건너뜀(0이면 비활성화) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1963,8 +1963,8 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 }, threadBindings: { enabled: true, - idleHours: 24, // 기본 비활성 자동 언포커스 시간(시간 단위, `0`이면 비활성화) - maxAgeHours: 0, // 기본 최대 사용 기간(시간 단위, `0`이면 비활성화) + idleHours: 24, // 기본 비활성 자동 언포커스 시간(0이면 비활성화) + maxAgeHours: 0, // 기본 하드 최대 사용 시간(0이면 비활성화) }, mainKey: "main", // 레거시(런타임은 항상 "main" 사용) agentToAgent: { maxPingPongTurns: 5 }, @@ -1978,35 +1978,35 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 -- **`scope`**: 그룹 채팅 컨텍스트에 대한 기본 세션 그룹화 전략입니다. - - `per-sender`(기본값): 채널 컨텍스트 안에서 각 발신자는 격리된 세션을 가집니다. - - `global`: 채널 컨텍스트의 모든 참여자가 하나의 세션을 공유합니다(공유 컨텍스트가 의도된 경우에만 사용). +- **`scope`**: 그룹 채팅 컨텍스트용 기본 세션 그룹화 전략입니다. + - `per-sender`(기본값): 채널 컨텍스트 내에서 각 발신자는 격리된 세션을 가집니다. + - `global`: 채널 컨텍스트의 모든 참여자가 단일 세션을 공유합니다(공유 컨텍스트가 의도된 경우에만 사용). - **`dmScope`**: DM이 그룹화되는 방식입니다. - `main`: 모든 DM이 메인 세션을 공유합니다. - `per-peer`: 채널 전체에서 발신자 ID별로 격리합니다. - `per-channel-peer`: 채널 + 발신자별로 격리합니다(다중 사용자 받은편지함에 권장). - `per-account-channel-peer`: 계정 + 채널 + 발신자별로 격리합니다(다중 계정에 권장). -- **`identityLinks`**: 채널 간 세션 공유를 위해 표준 ID를 공급자 접두사가 붙은 peer에 매핑합니다. -- **`reset`**: 기본 리셋 정책입니다. `daily`는 로컬 시간 기준 `atHour`에 리셋되고, `idle`은 `idleMinutes` 이후 리셋됩니다. 둘 다 구성된 경우 먼저 만료되는 쪽이 우선합니다. -- **`resetByType`**: 유형별 재정의(`direct`, `group`, `thread`)입니다. 레거시 `dm`도 `direct`의 별칭으로 허용됩니다. -- **`parentForkMaxTokens`**: 포크된 스레드 세션 생성 시 허용되는 부모 세션 `totalTokens`의 최대값입니다(기본값 `100000`). - - 부모 `totalTokens`가 이 값을 초과하면 OpenClaw는 부모 transcript 기록을 상속하지 않고 새 스레드 세션을 시작합니다. - - 이 보호 장치를 비활성화하고 항상 부모 포크를 허용하려면 `0`으로 설정하세요. -- **`mainKey`**: 레거시 필드입니다. 런타임은 메인 direct-chat 버킷에 항상 `"main"`을 사용합니다. -- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 동안 에이전트 사이에 허용되는 최대 응답 왕복 횟수입니다(정수, 범위: `0`–`5`). `0`은 ping-pong 체이닝을 비활성화합니다. -- **`sendPolicy`**: `channel`, `chatType`(`direct|group|channel`, 레거시 `dm` 별칭 포함), `keyPrefix`, 또는 `rawKeyPrefix`로 일치시킵니다. 첫 번째 deny가 우선합니다. +- **`identityLinks`**: 교차 채널 세션 공유를 위해 정식 ID를 provider 접두사가 붙은 피어에 매핑합니다. +- **`reset`**: 기본 reset 정책입니다. `daily`는 로컬 시간 `atHour`에 reset하고, `idle`은 `idleMinutes` 후 reset합니다. 둘 다 구성된 경우 먼저 만료되는 쪽이 우선합니다. +- **`resetByType`**: 타입별 재정의(`direct`, `group`, `thread`)입니다. 레거시 `dm`도 `direct`의 별칭으로 허용됩니다. +- **`parentForkMaxTokens`**: 포크된 스레드 세션을 생성할 때 허용되는 상위 세션 `totalTokens` 최대값입니다(기본값 `100000`). + - 상위 `totalTokens`가 이 값을 초과하면 OpenClaw는 상위 transcript 기록을 상속하는 대신 새 스레드 세션을 시작합니다. + - 이 가드를 비활성화하고 항상 상위 포크를 허용하려면 `0`으로 설정하세요. +- **`mainKey`**: 레거시 필드입니다. 런타임은 메인 직접 채팅 버킷에 항상 `"main"`을 사용합니다. +- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 중 응답-재응답 턴의 최대 횟수입니다(정수, 범위: `0`–`5`). `0`이면 핑퐁 체이닝을 비활성화합니다. +- **`sendPolicy`**: `channel`, `chatType`(`direct|group|channel`, 레거시 `dm` 별칭 포함), `keyPrefix`, 또는 `rawKeyPrefix`로 매치합니다. 첫 번째 deny가 우선합니다. - **`maintenance`**: 세션 저장소 정리 + 보존 제어입니다. - `mode`: `warn`은 경고만 출력하고, `enforce`는 정리를 적용합니다. - `pruneAfter`: 오래된 항목의 보존 기한입니다(기본값 `30d`). - `maxEntries`: `sessions.json`의 최대 항목 수입니다(기본값 `500`). - - `rotateBytes`: `sessions.json`이 이 크기를 초과하면 회전합니다(기본값 `10mb`). - - `resetArchiveRetention`: `*.reset.` transcript 아카이브의 보존 기간입니다. 기본값은 `pruneAfter`와 같으며, 비활성화하려면 `false`로 설정하세요. + - `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`: 비활성 자동 언포커스의 기본 시간(시간 단위, `0`이면 비활성화, 공급자 재정의 가능) - - `maxAgeHours`: 최대 사용 기간의 기본 시간(시간 단위, `0`이면 비활성화, 공급자 재정의 가능) + - `enabled`: 마스터 기본 스위치입니다(provider가 재정의할 수 있으며, Discord는 `channels.discord.threadBindings.enabled` 사용) + - `idleHours`: 기본 비활성 자동 언포커스 시간(시간 단위)입니다(`0`이면 비활성화, provider가 재정의 가능) + - `maxAgeHours`: 기본 하드 최대 사용 시간(시간 단위)입니다(`0`이면 비활성화, provider가 재정의 가능) @@ -2046,17 +2046,17 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 채널/계정별 재정의: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -해결 순서(가장 구체적인 것이 우선): 계정 → 채널 → 전역. `""`는 비활성화하고 상속도 중단합니다. `"auto"`는 `[{identity.name}]`를 파생합니다. +해결 순서(가장 구체적인 것이 우선): 계정 → 채널 → 전역. `""`는 비활성화하고 연쇄 적용도 중단합니다. `"auto"`는 `[{identity.name}]`에서 파생됩니다. **템플릿 변수:** -| 변수 | 설명 | 예시 | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | 짧은 모델 이름 | `claude-opus-4-6` | -| `{modelFull}` | 전체 모델 식별자 | `anthropic/claude-opus-4-6` | -| `{provider}` | 공급자 이름 | `anthropic` | -| `{thinkingLevel}` | 현재 thinking 수준 | `high`, `low`, `off` | -| `{identity.name}` | 에이전트 identity 이름 | (`"auto"`와 동일) | +| 변수 | 설명 | 예시 | +| ----------------- | -------------------- | --------------------------- | +| `{model}` | 짧은 모델 이름 | `claude-opus-4-6` | +| `{modelFull}` | 전체 모델 식별자 | `anthropic/claude-opus-4-6` | +| `{provider}` | Provider 이름 | `anthropic` | +| `{thinkingLevel}` | 현재 thinking 수준 | `high`, `low`, `off` | +| `{identity.name}` | 에이전트 identity 이름 | (`"auto"`와 동일) | 변수는 대소문자를 구분하지 않습니다. `{think}`는 `{thinkingLevel}`의 별칭입니다. @@ -2066,16 +2066,16 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 - 채널별 재정의: `channels..ackReaction`, `channels..accounts..ackReaction`. - 해결 순서: 계정 → 채널 → `messages.ackReaction` → identity 대체값. - 범위: `group-mentions`(기본값), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: Slack, Discord, Telegram에서 응답 후 확인 반응을 제거합니다. +- `removeAckAfterReply`: Slack, Discord, Telegram에서 응답 후 ack를 제거합니다. - `messages.statusReactions.enabled`: Slack, Discord, Telegram에서 수명 주기 상태 반응을 활성화합니다. - Slack과 Discord에서는 설정하지 않으면 확인 반응이 활성화된 경우 상태 반응도 계속 활성화됩니다. - Telegram에서는 수명 주기 상태 반응을 활성화하려면 명시적으로 `true`로 설정해야 합니다. + Slack과 Discord에서는 설정하지 않으면 ack 반응이 활성화되어 있을 때 상태 반응도 활성화된 상태로 유지됩니다. + Telegram에서는 수명 주기 상태 반응을 활성화하려면 이를 명시적으로 `true`로 설정하세요. -### 수신 디바운스 +### 수신 debounce -같은 발신자로부터 빠르게 들어오는 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 flush됩니다. 제어 명령은 디바운스를 우회합니다. +같은 발신자로부터 빠르게 들어오는 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 flush됩니다. 제어 명령은 debounce를 우회합니다. -### TTS (text-to-speech) +### TTS(텍스트 음성 변환) ```json5 { @@ -2116,12 +2116,12 @@ scripts/sandbox-browser-setup.sh # 선택적 브라우저 이미지 } ``` -- `auto`는 기본 자동 TTS 모드를 제어합니다: `off`, `always`, `inbound`, `tagged`. `/tts on|off`는 로컬 기본 설정을 재정의할 수 있으며, `/tts status`는 실제 적용 상태를 보여줍니다. -- `summaryModel`은 자동 요약용으로 `agents.defaults.model.primary`를 재정의합니다. +- `auto`는 기본 자동 TTS 모드를 제어합니다: `off`, `always`, `inbound`, 또는 `tagged`. `/tts on|off`는 로컬 기본 설정을 재정의할 수 있으며, `/tts status`는 실제 적용 상태를 보여줍니다. +- `summaryModel`은 자동 요약에서 `agents.defaults.model.primary`를 재정의합니다. - `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가 아닌 엔드포인트를 가리키면 OpenClaw는 이를 OpenAI 호환 TTS 서버로 처리하고 모델/voice 검증을 완화합니다. +- 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가 아닌 엔드포인트를 가리키면, OpenClaw는 이를 OpenAI 호환 TTS 서버로 간주하고 모델/음성 검증을 완화합니다. --- @@ -2153,11 +2153,11 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. - `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 객체를 받을 수 있습니다. -- `ELEVENLABS_API_KEY` 대체값은 Talk API 키가 구성되지 않은 경우에만 적용됩니다. +- Voice ID는 `ELEVENLABS_VOICE_ID` 또는 `SAG_VOICE_ID`를 대체값으로 사용합니다. +- `providers.*.apiKey`는 일반 텍스트 문자열 또는 SecretRef 객체를 받을 수 있습니다. +- `ELEVENLABS_API_KEY` 대체값은 구성된 Talk API 키가 없을 때만 적용됩니다. - `providers.*.voiceAliases`를 사용하면 Talk 지시문에서 친숙한 이름을 사용할 수 있습니다. -- `silenceTimeoutMs`는 Talk 모드가 사용자 침묵 후 transcript를 보내기까지 기다리는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 일시 정지 창을 유지합니다(`macOS와 Android에서는 700 ms, iOS에서는 900 ms`). +- `silenceTimeoutMs`는 사용자가 침묵한 후 Talk 모드가 transcript를 보내기까지 대기하는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 일시 정지 창을 유지합니다(`macOS 및 Android는 700 ms, iOS는 900 ms`). --- @@ -2167,35 +2167,35 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. `tools.profile`은 `tools.allow`/`tools.deny` 전에 기본 허용 목록을 설정합니다: -로컬 온보딩은 설정되지 않은 새 로컬 구성에 기본적으로 `tools.profile: "coding"`을 사용합니다(기존의 명시적 프로필은 유지됨). +로컬 온보딩은 새 로컬 구성에서 값이 설정되지 않은 경우 `tools.profile: "coding"`을 기본값으로 설정합니다(기존의 명시적 프로필은 유지됨). -| 프로필 | 포함 항목 | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `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` | 제한 없음(설정하지 않은 경우와 동일) | +| 프로필 | 포함 항목 | +| ---------- | -------------------------------------------------------------------------------------------------------------------------- | +| `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` | 제한 없음(설정하지 않은 것과 동일) | ### 도구 그룹 | 그룹 | 도구 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash`는 `exec`의 별칭으로 허용됨) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `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 Plugin 제외) | +| `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` -전역 도구 허용/거부 정책입니다(거부 우선). 대소문자를 구분하지 않으며 `*` 와일드카드를 지원합니다. Docker sandbox가 꺼져 있어도 적용됩니다. +전역 도구 허용/거부 정책입니다(거부가 우선). 대소문자를 구분하지 않으며 `*` 와일드카드를 지원합니다. Docker 샌드박스가 꺼져 있어도 적용됩니다. ```json5 { @@ -2221,7 +2221,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ### `tools.elevated` -샌드박스 외부에서의 elevated exec 접근을 제어합니다: +샌드박스 외부의 elevated exec 접근을 제어합니다: ```json5 { @@ -2237,9 +2237,9 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. } ``` -- 에이전트별 재정의(`agents.list[].tools.elevated`)는 더 엄격하게 제한만 할 수 있습니다. -- `/elevated on|off|ask|full`은 세션별 상태를 저장하며, 인라인 지시문은 단일 메시지에만 적용됩니다. -- Elevated `exec`는 sandboxing을 우회하고 구성된 escape 경로를 사용합니다(기본값은 `gateway`, exec 대상이 `node`이면 `node`). +- 에이전트별 재정의(`agents.list[].tools.elevated`)는 추가 제한만 할 수 있습니다. +- `/elevated on|off|ask|full`은 세션별로 상태를 저장하며, 인라인 지시문은 단일 메시지에만 적용됩니다. +- Elevated `exec`는 샌드박싱을 우회하고 구성된 탈출 경로를 사용합니다(`gateway`가 기본값이며, exec 대상이 `node`인 경우 `node` 사용). ### `tools.exec` @@ -2263,8 +2263,8 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ### `tools.loopDetection` -도구 루프 안전 점검은 기본적으로 **비활성화**되어 있습니다. 감지를 활성화하려면 `enabled: true`를 설정하세요. -설정은 전역 `tools.loopDetection`에 정의할 수 있으며, 에이전트별로 `agents.list[].tools.loopDetection`에서 재정의할 수 있습니다. +도구 루프 안전 검사는 기본적으로 **비활성화**되어 있습니다. 감지를 활성화하려면 `enabled: true`로 설정하세요. +설정은 전역 `tools.loopDetection`에 정의할 수 있고, 에이전트별로 `agents.list[].tools.loopDetection`에서 재정의할 수 있습니다. ```json5 { @@ -2286,13 +2286,13 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ``` - `historySize`: 루프 분석을 위해 유지되는 최대 도구 호출 기록 수입니다. -- `warningThreshold`: 진전 없는 반복 패턴에 대해 경고를 내보내는 임계값입니다. +- `warningThreshold`: 경고를 위한 반복 무진전 패턴 임계값입니다. - `criticalThreshold`: 심각한 루프를 차단하기 위한 더 높은 반복 임계값입니다. -- `globalCircuitBreakerThreshold`: 모든 진전 없는 실행에 대한 강제 중단 임계값입니다. -- `detectors.genericRepeat`: 동일 도구/동일 인자 호출 반복에 대해 경고합니다. -- `detectors.knownPollNoProgress`: 알려진 poll 도구(`process.poll`, `command_status` 등)의 진전 없는 반복에 대해 경고/차단합니다. -- `detectors.pingPong`: 번갈아 나타나는 진전 없는 쌍 패턴에 대해 경고/차단합니다. -- `warningThreshold >= criticalThreshold` 또는 `criticalThreshold >= globalCircuitBreakerThreshold`이면 검증에 실패합니다. +- `globalCircuitBreakerThreshold`: 모든 무진전 실행에 대한 하드 중단 임계값입니다. +- `detectors.genericRepeat`: 같은 도구/같은 인자 호출의 반복에 대해 경고합니다. +- `detectors.knownPollNoProgress`: 알려진 폴링 도구(`process.poll`, `command_status` 등)의 무진전에 대해 경고/차단합니다. +- `detectors.pingPong`: 번갈아 나타나는 무진전 쌍 패턴에 대해 경고/차단합니다. +- `warningThreshold >= criticalThreshold`이거나 `criticalThreshold >= globalCircuitBreakerThreshold`이면 유효성 검사가 실패합니다. ### `tools.web` @@ -2309,7 +2309,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. }, fetch: { enabled: true, - provider: "firecrawl", // 선택 사항; 자동 감지를 원하면 생략 + provider: "firecrawl", // 선택 사항, 자동 감지하려면 생략 maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2334,7 +2334,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: 완료된 비동기 음악/비디오를 채널로 직접 전송 + directSend: false, // opt-in: 완료된 비동기 음악/비디오를 채널에 직접 전송 }, audio: { enabled: true, @@ -2382,7 +2382,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 **비동기 완료 필드:** - `asyncCompletion.directSend`: `true`이면 완료된 비동기 `music_generate` - 및 `video_generate` 작업이 먼저 직접 채널 전달을 시도합니다. 기본값: `false` + 및 `video_generate` 작업이 먼저 직접 채널 전송을 시도합니다. 기본값: `false` (레거시 요청자 세션 깨우기/모델 전달 경로). @@ -2404,7 +2404,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 세션 도구(`sessions_list`, `sessions_history`, `sessions_send`)가 어떤 세션을 대상으로 할 수 있는지 제어합니다. -기본값: `tree`(현재 세션 + 현재 세션이 생성한 세션, 예: subagent). +기본값: `tree`(현재 세션 + 여기서 생성된 세션, 예: subagent). ```json5 { @@ -2420,10 +2420,10 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: - `self`: 현재 세션 키만. -- `tree`: 현재 세션 + 현재 세션이 생성한 세션(subagent). -- `agent`: 현재 에이전트 ID에 속한 모든 세션(같은 에이전트 ID 아래 per-sender 세션을 실행 중이면 다른 사용자도 포함될 수 있음). +- `tree`: 현재 세션 + 현재 세션에서 생성된 세션(subagent). +- `agent`: 현재 에이전트 ID에 속한 모든 세션(같은 에이전트 ID 아래 발신자별 세션을 실행하는 경우 다른 사용자도 포함될 수 있음). - `all`: 모든 세션. 에이전트 간 대상 지정에는 여전히 `tools.agentToAgent`가 필요합니다. -- Sandbox clamp: 현재 세션이 sandbox 상태이고 `agents.defaults.sandbox.sessionToolsVisibility="spawned"`이면 `tools.sessions.visibility="all"`이어도 visibility는 강제로 `tree`가 됩니다. +- 샌드박스 clamp: 현재 세션이 샌드박스 상태이고 `agents.defaults.sandbox.sessionToolsVisibility="spawned"`이면, `tools.sessions.visibility="all"`이어도 visibility는 강제로 `tree`가 됩니다. ### `tools.sessions_spawn` @@ -2434,7 +2434,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: 인라인 파일 첨부를 허용하려면 true로 설정 + enabled: false, // opt-in: true로 설정하면 인라인 파일 첨부 허용 maxTotalBytes: 5242880, // 모든 파일 합계 5 MB maxFiles: 50, maxFileBytes: 1048576, // 파일당 1 MB @@ -2448,9 +2448,9 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: - 첨부 파일은 `runtime: "subagent"`에서만 지원됩니다. ACP 런타임은 이를 거부합니다. -- 파일은 자식 workspace의 `.openclaw/attachments//` 아래에 `.manifest.json`과 함께 구체화됩니다. -- 첨부 파일 내용은 transcript 저장 시 자동으로 redaction됩니다. -- Base64 입력은 엄격한 알파벳/패딩 검사와 디코딩 전 크기 가드로 검증됩니다. +- 파일은 자식 워크스페이스의 `.openclaw/attachments//`에 `.manifest.json`과 함께 구체화됩니다. +- 첨부 파일 내용은 transcript 저장에서 자동으로 redaction됩니다. +- Base64 입력은 엄격한 알파벳/패딩 검사와 디코드 전 크기 가드로 검증됩니다. - 파일 권한은 디렉터리 `0700`, 파일 `0600`입니다. - 정리는 `cleanup` 정책을 따릅니다: `delete`는 항상 첨부 파일을 제거하고, `keep`은 `retainOnSessionKeep: true`일 때만 유지합니다. @@ -2470,9 +2470,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` @@ -2493,7 +2493,7 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 ``` - `model`: 생성된 sub-agent의 기본 모델입니다. 생략하면 sub-agent는 호출자의 모델을 상속합니다. -- `allowAgents`: 요청 에이전트가 자체 `subagents.allowAgents`를 설정하지 않았을 때 `sessions_spawn`에 대한 기본 대상 에이전트 ID 허용 목록입니다(`["*"]` = 모두 허용, 기본값: 동일 에이전트만). +- `allowAgents`: 요청 에이전트가 자체 `subagents.allowAgents`를 설정하지 않은 경우 `sessions_spawn` 대상 에이전트 ID의 기본 허용 목록입니다(`["*"]` = 아무 에이전트나 허용, 기본값: 같은 에이전트만). - `runTimeoutSeconds`: 도구 호출에서 `runTimeoutSeconds`를 생략했을 때 `sessions_spawn`의 기본 시간 제한(초)입니다. `0`은 시간 제한 없음입니다. - subagent별 도구 정책: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. @@ -2501,12 +2501,12 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 ## 사용자 지정 provider 및 base URL -OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 provider는 config 또는 `~/.openclaw/agents//agent/models.json`의 `models.providers`를 통해 추가합니다. +OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 provider는 구성 또는 `~/.openclaw/agents//agent/models.json`의 `models.providers`를 통해 추가하세요. ```json5 { models: { - mode: "merge", // merge (기본값) | replace + mode: "merge", // merge(기본값) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2531,49 +2531,49 @@ OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 prov ``` - 사용자 지정 인증이 필요하면 `authHeader: true` + `headers`를 사용하세요. -- `OPENCLAW_AGENT_DIR`(또는 레거시 환경 변수 별칭인 `PI_CODING_AGENT_DIR`)로 에이전트 구성 루트를 재정의하세요. -- 일치하는 provider ID에 대한 병합 우선순위: +- 에이전트 구성 루트는 `OPENCLAW_AGENT_DIR`로 재정의할 수 있습니다(또는 레거시 환경 변수 별칭 `PI_CODING_AGENT_DIR`). +- 일치하는 provider ID의 병합 우선순위: - 비어 있지 않은 에이전트 `models.json`의 `baseUrl` 값이 우선합니다. - - 비어 있지 않은 에이전트 `apiKey` 값은 현재 config/auth-profile 컨텍스트에서 해당 provider가 SecretRef로 관리되지 않는 경우에만 우선합니다. - - SecretRef로 관리되는 provider `apiKey` 값은 해석된 시크릿을 저장하는 대신 소스 마커(`ENV_VAR_NAME`은 env ref, `secretref-managed`는 file/exec ref)에서 새로 고쳐집니다. - - SecretRef로 관리되는 provider header 값은 소스 마커(`secretref-env:ENV_VAR_NAME`은 env ref, `secretref-managed`는 file/exec ref)에서 새로 고쳐집니다. - - 비어 있거나 없는 에이전트 `apiKey`/`baseUrl`은 config의 `models.providers`로 대체됩니다. - - 일치하는 모델의 `contextWindow`/`maxTokens`는 명시적 config와 암시적 카탈로그 값 중 더 큰 값을 사용합니다. - - 일치하는 모델의 `contextTokens`는 명시적 런타임 상한이 있으면 이를 유지합니다. 기본 모델 메타데이터를 바꾸지 않고 유효 컨텍스트를 제한할 때 사용하세요. - - config가 `models.json`을 완전히 다시 쓰게 하려면 `models.mode: "replace"`를 사용하세요. - - 마커 저장은 소스 권위를 따릅니다: 마커는 해석된 런타임 시크릿 값이 아니라 활성 소스 config 스냅샷(해석 전)에서 기록됩니다. + - 비어 있지 않은 에이전트 `apiKey` 값은 해당 provider가 현재 config/auth-profile 컨텍스트에서 SecretRef로 관리되지 않을 때만 우선합니다. + - SecretRef로 관리되는 provider `apiKey` 값은 해석된 비밀값을 유지하지 않고 소스 마커(`ENV_VAR_NAME`은 환경 변수 ref, `secretref-managed`는 file/exec ref)에서 새로 고쳐집니다. + - SecretRef로 관리되는 provider 헤더 값은 소스 마커(`secretref-env:ENV_VAR_NAME`는 환경 변수 ref, `secretref-managed`는 file/exec ref)에서 새로 고쳐집니다. + - 비어 있거나 누락된 에이전트 `apiKey`/`baseUrl`은 구성의 `models.providers`로 대체됩니다. + - 일치하는 모델의 `contextWindow`/`maxTokens`는 명시적 구성값과 암시적 카탈로그 값 중 더 높은 값을 사용합니다. + - 일치하는 모델의 `contextTokens`는 명시적인 런타임 상한이 있으면 이를 유지합니다. 네이티브 모델 메타데이터를 바꾸지 않고 실제 컨텍스트를 제한하는 데 사용하세요. + - 구성이 `models.json`을 완전히 다시 쓰게 하려면 `models.mode: "replace"`를 사용하세요. + - 마커 저장은 소스 권위 방식입니다: 마커는 해석된 런타임 비밀값이 아니라 활성 소스 구성 스냅샷(해석 전)에서 기록됩니다. ### Provider 필드 세부 정보 - `models.mode`: provider 카탈로그 동작입니다(`merge` 또는 `replace`). -- `models.providers`: provider ID를 키로 사용하는 사용자 지정 provider 맵입니다. +- `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.*.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 요청에 대한 전송 재정의입니다. +- `models.providers.*.request`: 모델 provider HTTP 요청용 전송 재정의입니다. - `request.headers`: 추가 헤더입니다(provider 기본값과 병합됨). 값은 SecretRef를 받을 수 있습니다. - - `request.auth`: 인증 전략 재정의입니다. 모드: `"provider-default"`(provider의 내장 인증 사용), `"authorization-bearer"`(`token`과 함께 사용), `"header"`(`headerName`, `value`, 선택적 `prefix`와 함께 사용). + - `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가 사설, CGNAT 또는 유사한 범위로 해석될 때 `baseUrl`에 대한 HTTPS를 허용합니다(신뢰된 자체 호스팅 OpenAI 호환 엔드포인트를 위한 운영자 opt-in). WebSocket은 헤더/TLS에는 같은 `request`를 사용하지만 해당 fetch SSRF 가드에는 사용하지 않습니다. 기본값은 `false`입니다. + - `request.allowPrivateNetwork`: `true`이면 DNS가 사설, CGNAT 또는 유사한 범위로 해석될 때 provider HTTP fetch 가드를 통해 `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`: 검색된 모델용 대체 최대 출력 토큰 수입니다. +- `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 예제 +### Provider 예시 @@ -2609,7 +2609,7 @@ OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 prov } ``` -Cerebras에는 `cerebras/zai-glm-4.7`을 사용하세요. Z.AI 직접 연결에는 `zai/glm-4.7`을 사용하세요. +Cerebras에는 `cerebras/zai-glm-4.7`을 사용하고, Z.AI 직접 연결에는 `zai/glm-4.7`을 사용하세요. @@ -2626,7 +2626,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`. @@ -2643,11 +2643,11 @@ 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` -- 일반 엔드포인트를 사용하려면 base URL 재정의를 포함한 사용자 지정 provider를 정의하세요. +- 일반 엔드포인트에는 base URL 재정의가 있는 사용자 지정 provider를 정의하세요. @@ -2686,11 +2686,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만이 아니라 엔드포인트 capability를 기준으로 이를 판단합니다. @@ -2708,11 +2706,11 @@ 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`. - + ```json5 { @@ -2747,11 +2745,11 @@ Anthropic 호환, 내장 provider입니다. 단축 명령: `openclaw onboard --a } ``` -base URL에는 `/v1`을 포함하지 않아야 합니다(Anthropic 클라이언트가 이를 추가함). 단축 명령: `openclaw onboard --auth-choice synthetic-api-key`. +base URL에는 `/v1`를 포함하지 않아야 합니다(Anthropic 클라이언트가 이를 추가함). 단축 경로: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2787,20 +2785,20 @@ 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`을 설정하지 않는 한 +모델 카탈로그의 기본값은 M2.7만 포함합니다. +Anthropic 호환 스트리밍 경로에서 OpenClaw는 `thinking`을 명시적으로 설정하지 않는 한 기본적으로 MiniMax thinking을 비활성화합니다. `/fast on` 또는 `params.fastMode: true`는 `MiniMax-M2.7`을 -`MiniMax-M2.7-highspeed`로 다시 씁니다. +`MiniMax-M2.7-highspeed`로 다시 작성합니다. -[로컬 모델](/ko/gateway/local-models)을 참조하세요. 요약: 충분한 하드웨어에서는 LM Studio Responses API를 통해 큰 로컬 모델을 실행하고, 대체 경로를 위해 호스팅 모델은 병합된 상태로 유지하세요. +[로컬 모델](/ko/gateway/local-models)을 참조하세요. 요약: 충분한 하드웨어에서 LM Studio Responses API를 통해 대형 로컬 모델을 실행하고, 대체 경로를 위해 호스팅 모델은 병합된 상태로 유지하세요. @@ -2821,7 +2819,7 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 또는 평문 문자열 + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // 또는 일반 텍스트 문자열 env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2831,14 +2829,12 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking } ``` -- `allowBundled`: 번들 Skills 전용 선택적 허용 목록입니다(관리형/workspace Skills에는 영향 없음). +- `allowBundled`: 번들 Skills에만 적용되는 선택적 허용 목록입니다(관리형/워크스페이스 Skills에는 영향 없음). - `load.extraDirs`: 추가 공유 skill 루트입니다(가장 낮은 우선순위). -- `install.preferBrew`: `true`이면 `brew`를 사용할 수 있을 때 - 다른 설치 방식으로 대체하기 전에 Homebrew 설치 관리자를 우선합니다. -- `install.nodeManager`: `metadata.openclaw.install` - 사양에 대한 Node 설치 관리자 선호도입니다(`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false`는 번들되었거나 설치되어 있어도 해당 skill을 비활성화합니다. -- `entries..apiKey`: 기본 env var를 선언하는 skill을 위한 편의 설정입니다(평문 문자열 또는 SecretRef 객체). +- `install.preferBrew`: `true`이면 `brew`를 사용할 수 있을 때 다른 설치 방식으로 대체하기 전에 Homebrew 설치를 우선합니다. +- `install.nodeManager`: `metadata.openclaw.install` 사양용 node 설치 관리자 우선순위입니다(`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false`는 번들/설치되어 있어도 해당 skill을 비활성화합니다. +- `entries..apiKey`: 기본 환경 변수를 선언하는 Skills을 위한 편의 필드입니다(일반 텍스트 문자열 또는 SecretRef 객체). --- @@ -2866,28 +2862,28 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking } ``` -- `~/.openclaw/extensions`, `/.openclaw/extensions`, `plugins.load.paths`에서 로드됩니다. -- 검색은 네이티브 OpenClaw Plugin과 호환되는 Codex 번들 및 Claude 번들을 허용하며, manifest가 없는 Claude 기본 레이아웃 번들도 포함합니다. +- `~/.openclaw/extensions`, `/.openclaw/extensions`, 그리고 `plugins.load.paths`에서 로드됩니다. +- Discovery는 네이티브 OpenClaw Plugin과 호환되는 Codex 번들 및 Claude 번들을 허용하며, 매니페스트가 없는 Claude 기본 레이아웃 번들도 포함합니다. - **구성 변경에는 gateway 재시작이 필요합니다.** - `allow`: 선택적 허용 목록입니다(목록에 있는 Plugin만 로드). `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 훅과 지원되는 번들 제공 훅 디렉터리에 적용됩니다. +- `plugins.entries..hooks.allowPromptInjection`: `false`이면 core가 `before_prompt_build`를 차단하고, 레거시 `before_agent_start`의 프롬프트 변경 필드는 무시하면서 레거시 `modelOverride`와 `providerOverride`는 유지합니다. 네이티브 Plugin hook과 지원되는 번들 제공 hook 디렉터리에 적용됩니다. - `plugins.entries..subagent.allowModelOverride`: 이 Plugin이 백그라운드 subagent 실행에 대해 실행별 `provider` 및 `model` 재정의를 요청하도록 명시적으로 신뢰합니다. -- `plugins.entries..subagent.allowedModels`: 신뢰된 subagent 재정의를 위한 선택적 표준 `provider/model` 대상 허용 목록입니다. 의도적으로 모든 모델을 허용하려는 경우에만 `"*"`를 사용하세요. -- `plugins.entries..config`: Plugin이 정의한 구성 객체입니다(사용 가능한 경우 네이티브 OpenClaw Plugin 스키마로 검증됨). +- `plugins.entries..subagent.allowedModels`: 신뢰된 subagent 재정의용 정식 `provider/model` 대상의 선택적 허용 목록입니다. 어떤 모델이든 허용하려는 의도가 명확할 때만 `"*"`를 사용하세요. +- `plugins.entries..config`: Plugin이 정의한 구성 객체입니다(가능한 경우 네이티브 OpenClaw Plugin 스키마로 검증됨). - `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 base URL입니다(기본값: `https://api.firecrawl.dev`). + - `baseUrl`: Firecrawl API 기본 URL입니다(기본값: `https://api.firecrawl.dev`). - `onlyMainContent`: 페이지에서 메인 콘텐츠만 추출합니다(기본값: `true`). - `maxAgeMs`: 최대 캐시 수명(밀리초)입니다(기본값: `172800000` / 2일). - - `timeoutSeconds`: 스크래핑 요청 시간 제한(초)입니다(기본값: `60`). + - `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 * * *"`). + - `enabled`: 마스터 dreaming 스위치입니다(기본값 `false`). + - `frequency`: 각 전체 dreaming 스윕의 Cron 주기입니다(기본값은 `"0 3 * * *"`). - 단계 정책과 임계값은 구현 세부 사항입니다(사용자 대상 구성 키 아님). - 전체 memory 구성은 [메모리 구성 참조](/ko/reference/memory-config)에 있습니다: - `agents.defaults.memorySearch.*` @@ -2895,12 +2891,12 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- 활성화된 Claude 번들 Plugin은 `settings.json`에서 내장 Pi 기본값을 제공할 수도 있습니다. OpenClaw는 이를 원시 OpenClaw 구성 패치가 아니라 정제된 에이전트 설정으로 적용합니다. -- `plugins.slots.memory`: 활성 memory Plugin ID를 선택하거나, memory Plugin을 비활성화하려면 `"none"`을 사용하세요. -- `plugins.slots.contextEngine`: 활성 context engine Plugin ID를 선택합니다. 다른 engine을 설치하고 선택하지 않으면 기본값은 `"legacy"`입니다. +- 활성화된 Claude 번들 Plugin은 `settings.json`에서 임베디드 Pi 기본값도 제공할 수 있습니다. OpenClaw는 이를 원시 OpenClaw 구성 패치가 아니라 정제된 에이전트 설정으로 적용합니다. +- `plugins.slots.memory`: 활성 memory Plugin ID를 선택하거나, memory Plugin을 비활성화하려면 `"none"`을 사용합니다. +- `plugins.slots.contextEngine`: 활성 context engine 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 명령을 권장합니다. [Plugins](/ko/tools/plugin)를 참조하세요. @@ -2915,7 +2911,7 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 신뢰된 사설 네트워크 접근에 대해서만 opt in + // dangerouslyAllowPrivateNetwork: true, // 신뢰된 사설 네트워크 접근에만 opt in // allowPrivateNetwork: true, // 레거시 별칭 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], @@ -2943,26 +2939,26 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking ``` - `evaluateEnabled: false`는 `act:evaluate`와 `wait --fn`을 비활성화합니다. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork`는 설정하지 않으면 비활성화되므로 브라우저 탐색은 기본적으로 엄격하게 유지됩니다. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork`는 설정하지 않으면 비활성화되므로, 브라우저 탐색은 기본적으로 엄격하게 유지됩니다. - 사설 네트워크 브라우저 탐색을 의도적으로 신뢰하는 경우에만 `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`를 설정하세요. -- 엄격 모드에서는 원격 CDP 프로필 엔드포인트(`profiles.*.cdpUrl`)도 도달 가능성/검색 점검 중 동일한 사설 네트워크 차단이 적용됩니다. +- 엄격 모드에서는 원격 CDP 프로필 엔드포인트(`profiles.*.cdpUrl`)도 도달 가능성/Discovery 검사 중 동일한 사설 네트워크 차단이 적용됩니다. - `ssrfPolicy.allowPrivateNetwork`는 레거시 별칭으로 계속 지원됩니다. - 엄격 모드에서는 명시적 예외를 위해 `ssrfPolicy.hostnameAllowlist`와 `ssrfPolicy.allowedHostnames`를 사용하세요. -- 원격 프로필은 attach-only입니다(시작/중지/재설정 비활성화). +- 원격 프로필은 attach-only입니다(start/stop/reset 비활성화). - `profiles.*.cdpUrl`은 `http://`, `https://`, `ws://`, `wss://`를 받을 수 있습니다. - OpenClaw가 `/json/version`을 검색하게 하려면 HTTP(S)를 사용하고, provider가 직접적인 DevTools WebSocket URL을 제공하면 WS(S)를 사용하세요. -- `existing-session` 프로필은 호스트 전용이며 CDP 대신 Chrome MCP를 사용합니다. -- `existing-session` 프로필은 Brave 또는 Edge 같은 특정 - Chromium 기반 브라우저 프로필을 대상으로 하기 위해 `userDataDir`을 설정할 수 있습니다. -- `existing-session` 프로필은 현재 Chrome MCP 경로 제한을 유지합니다: - CSS 선택자 대상 지정 대신 snapshot/ref 기반 작업, 단일 파일 업로드 - 훅, 대화상자 시간 제한 재정의 없음, `wait --load networkidle` 없음, - 그리고 `responsebody`, PDF 내보내기, 다운로드 가로채기, 배치 작업 없음. + OpenClaw가 `/json/version`을 Discovery하게 하려면 HTTP(S)를 사용하고, + provider가 직접 DevTools WebSocket URL을 제공하는 경우에는 WS(S)를 사용하세요. +- `existing-session` 프로필은 CDP 대신 Chrome MCP를 사용하며, 선택된 호스트 또는 연결된 브라우저 Node를 통해 attach할 수 있습니다. +- `existing-session` 프로필은 Brave 또는 Edge 같은 특정 Chromium 기반 브라우저 프로필을 대상으로 하기 위해 `userDataDir`을 설정할 수 있습니다. +- `existing-session` 프로필은 현재 Chrome MCP 라우트 제한을 유지합니다: + CSS 선택자 대상 지정 대신 스냅샷/ref 기반 작업, 단일 파일 업로드 + hook, 대화상자 시간 제한 재정의 없음, `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`, 창 크기 조정, 또는 디버그 플래그). --- @@ -2974,14 +2970,14 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // 이모지, 짧은 텍스트, 이미지 URL 또는 data URI + avatar: "CB", // 이모지, 짧은 텍스트, 이미지 URL, 또는 data URI }, }, } ``` -- `seamColor`: 네이티브 앱 UI chrome의 강조 색상입니다(Talk Mode 버블 틴트 등). -- `assistant`: Control UI identity 재정의입니다. 활성 에이전트 identity로 대체됩니다. +- `seamColor`: 네이티브 앱 UI 크롬의 강조 색상입니다(Talk Mode 버블 틴트 등). +- `assistant`: Control UI identity 재정의입니다. 활성 에이전트 identity를 대체값으로 사용합니다. --- @@ -2997,7 +2993,7 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking 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 참조 + // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy용, /gateway/trusted-proxy-auth 참조 allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -3017,7 +3013,7 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking // embedSandbox: "scripts", // strict | scripts | trusted // allowExternalEmbedUrls: false, // 위험: 절대 외부 http(s) embed URL 허용 // allowedOrigins: ["https://control.example.com"], // loopback이 아닌 Control UI에 필요 - // dangerouslyAllowHostHeaderOriginFallback: false, // 위험한 Host-header origin 대체 모드 + // dangerouslyAllowHostHeaderOriginFallback: false, // 위험한 Host-header origin fallback 모드 // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -3028,12 +3024,12 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // 선택 사항. 기본값은 false. + // 선택 사항. 기본값 false. allowRealIpFallback: false, tools: { - // 추가 /tools/invoke HTTP 거부 + // 추가 /tools/invoke HTTP deny deny: ["browser"], - // 기본 HTTP 거부 목록에서 도구 제거 + // 기본 HTTP deny 목록에서 도구 제거 allow: ["gateway"], }, push: { @@ -3050,43 +3046,43 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking -- `mode`: `local`(gateway 실행) 또는 `remote`(원격 gateway에 연결)입니다. `local`이 아니면 gateway는 시작을 거부합니다. -- `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"`를 사용하는 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 origin에서 반복된 실패가 다른 origin까지 - 자동으로 잠그지는 않습니다. +- **Docker 참고**: 기본 `loopback` bind는 컨테이너 내부의 `127.0.0.1`에서 수신합니다. Docker 브리지 네트워킹(`-p 18789:18789`)에서는 트래픽이 `eth0`로 들어오므로 gateway에 도달할 수 없습니다. `--network host`를 사용하거나, 모든 인터페이스에서 수신하도록 `bind: "lan"`(또는 `bind: "custom"`과 `customBindHost: "0.0.0.0"`)을 설정하세요. +- **인증**: 기본적으로 필요합니다. loopback이 아닌 bind에는 gateway 인증이 필요합니다. 실제로는 공유 토큰/비밀번호 또는 `gateway.auth.mode: "trusted-proxy"`를 사용하는 identity 인식 리버스 프록시를 의미합니다. 온보딩 마법사는 기본적으로 토큰을 생성합니다. +- `gateway.auth.token`과 `gateway.auth.password`가 모두 구성된 경우(SecretRef 포함), `gateway.auth.mode`를 `token` 또는 `password`로 명시적으로 설정하세요. 둘 다 구성되어 있고 mode가 설정되지 않으면 시작 및 서비스 설치/복구 흐름이 실패합니다. +- `gateway.auth.mode: "none"`: 명시적 무인증 모드입니다. 신뢰된 로컬 loopback 설정에서만 사용하세요. 이는 의도적으로 온보딩 프롬프트에 제공되지 않습니다. +- `gateway.auth.mode: "trusted-proxy"`: 인증을 identity 인식 리버스 프록시에 위임하고 `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에서는 이러한 브라우저 원본 lockout이 정규화된 `Origin` + 값별로 격리되므로, 하나의 localhost origin에서 반복된 실패가 + 다른 origin을 자동으로 잠그지는 않습니다. - `tailscale.mode`: `serve`(tailnet 전용, loopback bind) 또는 `funnel`(공개, 인증 필요). -- `controlUi.allowedOrigins`: Gateway WebSocket 연결용 명시적 브라우저 origin 허용 목록입니다. 브라우저 클라이언트가 loopback이 아닌 origin에서 접속해야 할 때 필요합니다. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host-header origin 정책에 의도적으로 의존하는 배포를 위해 Host-header origin 대체를 활성화하는 위험한 모드입니다. +- `controlUi.allowedOrigins`: Gateway WebSocket 연결용 명시적 브라우저 origin 허용 목록입니다. loopback이 아닌 origin에서 브라우저 클라이언트가 예상되는 경우 필요합니다. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: Host-header origin 정책에 의도적으로 의존하는 배포를 위해 Host-header 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의 base 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_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 등록에 포함하며, 등록 범위의 전송 권한을 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를 통해 명시적으로 구성되었는데 해석되지 않으면, 해석은 기본 차단 방식으로 실패합니다(원격 대체로 가려지지 않음). -- `trustedProxies`: TLS를 종료하거나 전달된 클라이언트 헤더를 주입하는 리버스 프록시 IP입니다. 제어하는 프록시만 나열하세요. loopback 항목도 같은 호스트 프록시/로컬 감지 설정(예: Tailscale Serve 또는 로컬 리버스 프록시)에는 여전히 유효하지만, loopback 요청이 `gateway.auth.mode: "trusted-proxy"` 대상이 되도록 만들지는 않습니다. -- `allowRealIpFallback`: `true`이면 `X-Forwarded-For`가 없을 때 gateway가 `X-Real-IP`를 허용합니다. 기본값은 기본 차단 동작을 위한 `false`입니다. +- `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를 통해 명시적으로 구성되었으나 해석되지 않으면, 해석은 실패 닫힘 방식으로 처리됩니다(원격 대체로 가려지지 않음). +- `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 목록에서 도구 이름을 제거합니다. @@ -3100,14 +3096,15 @@ Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 빈 허용 목록은 설정되지 않은 것으로 처리됩니다. URL 가져오기를 비활성화하려면 `gateway.http.endpoints.responses.files.allowUrl=false` + 빈 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) 참조) +- 선택적 응답 강화 헤더: + - `gateway.http.securityHeaders.strictTransportSecurity` (제어하는 HTTPS origin에만 설정, [Trusted Proxy Auth](/ko/gateway/trusted-proxy-auth#tls-termination-and-hsts) 참조) ### 다중 인스턴스 격리 -하나의 호스트에서 여러 gateway를 고유한 포트와 상태 디렉터리로 실행합니다: +고유 포트와 상태 디렉터리로 한 호스트에서 여러 gateway를 실행합니다: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3136,9 +3133,9 @@ openclaw gateway --port 19001 ``` - `enabled`: gateway 리스너에서 TLS 종료(HTTPS/WSS)를 활성화합니다(기본값: `false`). -- `autoGenerate`: 명시적 파일이 구성되지 않았을 때 로컬 자체 서명 cert/key 쌍을 자동 생성합니다. 로컬/개발 용도로만 사용하세요. +- `autoGenerate`: 명시적 파일이 구성되지 않았을 때 로컬 자체 서명 cert/key 쌍을 자동 생성합니다. 로컬/개발용으로만 사용하세요. - `certPath`: TLS 인증서 파일의 파일 시스템 경로입니다. -- `keyPath`: TLS 개인 키 파일의 파일 시스템 경로입니다. 권한을 제한해 두세요. +- `keyPath`: TLS 개인 키 파일의 파일 시스템 경로입니다. 권한을 제한해 보관하세요. - `caPath`: 클라이언트 검증 또는 사용자 지정 신뢰 체인용 선택적 CA 번들 경로입니다. ### `gateway.reload` @@ -3155,17 +3152,17 @@ openclaw gateway --port 19001 } ``` -- `mode`: 구성 편집을 런타임에 어떻게 적용할지 제어합니다. - - `"off"`: 실시간 편집을 무시합니다. 변경 사항에는 명시적 재시작이 필요합니다. +- `mode`: 런타임에 구성 편집을 적용하는 방식을 제어합니다. + - `"off"`: 라이브 편집을 무시하며, 변경 사항에는 명시적 재시작이 필요합니다. - `"restart"`: 구성 변경 시 항상 gateway 프로세스를 재시작합니다. - `"hot"`: 재시작 없이 프로세스 내에서 변경 사항을 적용합니다. - - `"hybrid"`(기본값): 먼저 hot reload를 시도하고, 필요하면 재시작으로 대체합니다. -- `debounceMs`: 구성 변경을 적용하기 전 디바운스 창(밀리초)입니다(음수가 아닌 정수). -- `deferralTimeoutMs`: 진행 중인 작업을 기다리다가 강제로 재시작하기 전까지의 최대 대기 시간(밀리초)입니다(기본값: `300000` = 5분). + - `"hybrid"`(기본값): 먼저 hot reload를 시도하고, 필요 시 재시작으로 대체합니다. +- `debounceMs`: 구성 변경 적용 전의 debounce 창(ms)입니다(음이 아닌 정수). +- `deferralTimeoutMs`: 진행 중 작업을 기다린 뒤 재시작을 강제하기까지의 최대 시간(ms)입니다(기본값: `300000` = 5분). --- -## 훅 +## Hooks ```json5 { @@ -3188,7 +3185,7 @@ openclaw gateway --port 19001 wakeMode: "now", name: "Gmail", sessionKey: "hook:gmail:{{messages[0].id}}", - messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}", + messageTemplate: "보낸사람: {{messages[0].from}}\n제목: {{messages[0].subject}}\n{{messages[0].snippet}}", deliver: true, channel: "last", model: "openai/gpt-5.4-mini", @@ -3201,10 +3198,10 @@ openclaw gateway --port 19001 인증: `Authorization: Bearer ` 또는 `x-openclaw-token: `. 쿼리 문자열 hook 토큰은 거부됩니다. -검증 및 안전 관련 참고: +유효성 검사 및 안전 참고: - `hooks.enabled=true`에는 비어 있지 않은 `hooks.token`이 필요합니다. -- `hooks.token`은 `gateway.auth.token`과 **달라야** 합니다. Gateway 토큰 재사용은 거부됩니다. +- `hooks.token`은 `gateway.auth.token`과 **달라야** 합니다. Gateway 토큰을 재사용하면 거부됩니다. - `hooks.path`는 `/`일 수 없습니다. `/hooks` 같은 전용 하위 경로를 사용하세요. - `hooks.allowRequestSessionKey=true`인 경우 `hooks.allowedSessionKeyPrefixes`를 제한하세요(예: `["hook:"]`). @@ -3213,7 +3210,7 @@ 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`를 통해 해석 @@ -3221,14 +3218,14 @@ openclaw gateway --port 19001 - `match.source`는 일반 경로에 대해 페이로드 필드와 일치합니다. - `{{messages[0].subject}}` 같은 템플릿은 페이로드에서 값을 읽습니다. - `transform`은 hook 작업을 반환하는 JS/TS 모듈을 가리킬 수 있습니다. - - `transform.module`은 상대 경로여야 하며 `hooks.transformsDir` 내부에 있어야 합니다(절대 경로와 상위 경로 탐색은 거부됨). + - `transform.module`은 상대 경로여야 하며 `hooks.transformsDir` 내부에 머물러야 합니다(절대 경로와 경로 순회는 거부됨). - `agentId`는 특정 에이전트로 라우팅하며, 알 수 없는 ID는 기본값으로 대체됩니다. - `allowedAgentIds`: 명시적 라우팅을 제한합니다(`*` 또는 생략 = 모두 허용, `[]` = 모두 거부). -- `defaultSessionKey`: 명시적인 `sessionKey`가 없는 hook 에이전트 실행에 대한 선택적 고정 세션 키입니다. -- `allowRequestSessionKey`: `/hooks/agent` 호출자가 `sessionKey`를 설정하도록 허용합니다(기본값: `false`). -- `allowedSessionKeyPrefixes`: 명시적 `sessionKey` 값(요청 + 매핑)에 대한 선택적 접두사 허용 목록입니다. 예: `["hook:"]`. -- `deliver: true`는 최종 응답을 채널로 전송하며, `channel`의 기본값은 `last`입니다. -- `model`은 이 hook 실행의 LLM을 재정의합니다(모델 카탈로그가 설정된 경우 허용되어야 함). +- `defaultSessionKey`: 명시적 `sessionKey`가 없는 hook 에이전트 실행에 대한 선택적 고정 세션 키입니다. +- `allowRequestSessionKey`: `/hooks/agent` 호출자가 `sessionKey`를 설정할 수 있게 합니다(기본값: `false`). +- `allowedSessionKeyPrefixes`: 명시적 `sessionKey` 값(요청 + 매핑)에 대한 선택적 접두사 허용 목록입니다(예: `["hook:"]`). +- `deliver: true`는 최종 응답을 채널로 전송합니다. `channel`의 기본값은 `last`입니다. +- `model`은 이 hook 실행에 대해 LLM을 재정의합니다(모델 카탈로그가 설정된 경우 허용되어야 함). @@ -3256,7 +3253,7 @@ openclaw gateway --port 19001 ``` - 구성되면 Gateway는 부팅 시 `gog gmail watch serve`를 자동 시작합니다. 비활성화하려면 `OPENCLAW_SKIP_GMAIL_WATCHER=1`을 설정하세요. -- Gateway와 함께 별도의 `gog gmail watch serve`를 실행하지 마세요. +- Gateway와 별도로 `gog gmail watch serve`를 따로 실행하지 마세요. --- @@ -3272,22 +3269,22 @@ openclaw gateway --port 19001 } ``` -- Gateway 포트 아래 HTTP로 에이전트가 편집 가능한 HTML/CSS/JS 및 A2UI를 제공합니다: +- Gateway 포트 아래 HTTP로 에이전트가 편집 가능한 HTML/CSS/JS와 A2UI를 제공합니다: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - 로컬 전용: `gateway.bind: "loopback"`(기본값)을 유지하세요. -- loopback이 아닌 bind에서는 canvas 경로에 다른 Gateway HTTP 표면과 동일하게 Gateway 인증(token/password/trusted-proxy)이 필요합니다. -- Node WebView는 일반적으로 인증 헤더를 보내지 않습니다. node가 페어링되고 연결되면 Gateway는 canvas/A2UI 접근을 위한 node 범위 capability URL을 알립니다. -- Capability URL은 활성 node WS 세션에 바인딩되며 빠르게 만료됩니다. IP 기반 대체 방식은 사용되지 않습니다. +- 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에 live-reload 클라이언트를 주입합니다. - 비어 있으면 시작용 `index.html`을 자동 생성합니다. -- A2UI도 `/__openclaw__/a2ui/`에서 제공합니다. +- `/__openclaw__/a2ui/`에서도 A2UI를 제공합니다. - 변경 사항에는 gateway 재시작이 필요합니다. -- 디렉터리가 크거나 `EMFILE` 오류가 발생하면 live reload를 비활성화하세요. +- 대형 디렉터리이거나 `EMFILE` 오류가 발생하면 live reload를 비활성화하세요. --- -## 검색 +## Discovery ### mDNS (Bonjour) @@ -3315,7 +3312,7 @@ openclaw gateway --port 19001 } ``` -`~/.openclaw/dns/` 아래에 유니캐스트 DNS-SD 존을 씁니다. 네트워크 간 검색을 위해 DNS 서버(CoreDNS 권장) + Tailscale split DNS와 함께 사용하세요. +`~/.openclaw/dns/` 아래에 유니캐스트 DNS-SD 존을 기록합니다. 교차 네트워크 Discovery를 위해 DNS 서버(CoreDNS 권장) + Tailscale 분할 DNS와 함께 사용하세요. 설정: `openclaw dns setup --apply`. @@ -3323,7 +3320,7 @@ openclaw gateway --port 19001 ## 환경 -### `env` (인라인 환경 변수) +### `env`(인라인 환경 변수) ```json5 { @@ -3341,13 +3338,13 @@ openclaw gateway --port 19001 ``` - 인라인 환경 변수는 프로세스 환경에 해당 키가 없을 때만 적용됩니다. -- `.env` 파일: CWD `.env` + `~/.openclaw/.env`(기존 변수를 덮어쓰지 않음). +- `.env` 파일: CWD `.env` + `~/.openclaw/.env`(둘 다 기존 변수를 덮어쓰지 않음). - `shellEnv`: 로그인 셸 프로필에서 누락된 예상 키를 가져옵니다. -- 전체 우선순위는 [Environment](/ko/help/environment)를 참조하세요. +- 전체 우선순위는 [환경](/ko/help/environment)을 참조하세요. ### 환경 변수 치환 -어떤 구성 문자열에서도 `${VAR_NAME}`으로 환경 변수를 참조할 수 있습니다: +모든 구성 문자열에서 `${VAR_NAME}`으로 환경 변수를 참조할 수 있습니다: ```json5 { @@ -3366,17 +3363,17 @@ openclaw gateway --port 19001 ## Secrets -SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습니다. +SecretRef는 추가적 기능입니다. 일반 텍스트 값도 계속 사용할 수 있습니다. ### `SecretRef` -하나의 객체 형태를 사용하세요: +하나의 객체 형식을 사용하세요: ```json5 { 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}$` @@ -3386,7 +3383,7 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 ### 지원되는 자격 증명 표면 -- 표준 매트릭스: [SecretRef Credential Surface](/ko/reference/secretref-credential-surface) +- 정식 매트릭스: [SecretRef 자격 증명 표면](/ko/reference/secretref-credential-surface) - `secrets apply`는 지원되는 `openclaw.json` 자격 증명 경로를 대상으로 합니다. - `auth-profiles.json` ref는 런타임 해석 및 감사 범위에도 포함됩니다. @@ -3421,12 +3418,12 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 참고: - `file` provider는 `mode: "json"`과 `mode: "singleValue"`를 지원합니다(`singleValue` 모드에서는 `id`가 `"value"`여야 함). -- `exec` provider는 절대 `command` 경로가 필요하며 stdin/stdout에서 프로토콜 페이로드를 사용합니다. -- 기본적으로 심볼릭 링크 command 경로는 거부됩니다. 심볼릭 링크 경로를 허용하면서 해석된 대상 경로를 검증하려면 `allowSymlinkCommand: true`를 설정하세요. -- `trustedDirs`가 구성된 경우 trusted-dir 검사는 해석된 대상 경로에 적용됩니다. -- `exec` 자식 환경은 기본적으로 최소화되어 있으므로 필요한 변수는 `passEnv`로 명시적으로 전달하세요. -- Secret ref는 활성화 시점에 메모리 내 스냅샷으로 해석되며, 이후 요청 경로는 스냅샷만 읽습니다. -- 활성 표면 필터링은 활성화 중 적용됩니다. 활성화된 표면의 해석되지 않은 ref는 시작/리로드를 실패시키고, 비활성 표면은 진단과 함께 건너뜁니다. +- `exec` provider는 절대 `command` 경로가 필요하며 stdin/stdout의 프로토콜 페이로드를 사용합니다. +- 기본적으로 심볼릭 링크 command 경로는 거부됩니다. 해석된 대상 경로를 검증하면서 심볼릭 링크 경로를 허용하려면 `allowSymlinkCommand: true`를 설정하세요. +- `trustedDirs`가 구성된 경우, 신뢰 디렉터리 검사는 해석된 대상 경로에 적용됩니다. +- `exec` 자식 환경은 기본적으로 최소화되어 있습니다. 필요한 변수는 `passEnv`로 명시적으로 전달하세요. +- Secret ref는 활성화 시 메모리 내 스냅샷으로 해석되며, 그 이후 요청 경로는 이 스냅샷만 읽습니다. +- 활성 표면 필터링은 활성화 중에 적용됩니다: 활성화된 표면의 해석되지 않은 ref는 시작/재로드를 실패시키고, 비활성 표면은 진단과 함께 건너뜁니다. --- @@ -3451,10 +3448,10 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 - 에이전트별 프로필은 `/auth-profiles.json`에 저장됩니다. - `auth-profiles.json`은 정적 자격 증명 모드에 대해 값 수준 ref(`api_key`용 `keyRef`, `token`용 `tokenRef`)를 지원합니다. - OAuth 모드 프로필(`auth.profiles..mode = "oauth"`)은 SecretRef 기반 auth-profile 자격 증명을 지원하지 않습니다. -- 정적 런타임 자격 증명은 메모리 내 해석된 스냅샷에서 오며, 레거시 정적 `auth.json` 항목은 발견 시 제거됩니다. +- 정적 런타임 자격 증명은 메모리 내 해석된 스냅샷에서 오며, 레거시 정적 `auth.json` 항목은 발견 시 정리됩니다. - 레거시 OAuth는 `~/.openclaw/credentials/oauth.json`에서 가져옵니다. - [OAuth](/ko/concepts/oauth)를 참조하세요. -- secrets 런타임 동작과 `audit/configure/apply` 도구: [Secrets Management](/ko/gateway/secrets). +- Secrets 런타임 동작 및 `audit/configure/apply` 도구: [Secrets Management](/ko/gateway/secrets). ### `auth.cooldowns` @@ -3476,21 +3473,15 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 } ``` -- `billingBackoffHours`: 프로필이 실제 - 청구/크레딧 부족 오류로 실패했을 때의 기본 backoff 시간(시간 단위, 기본값: `5`)입니다. 명시적인 청구 관련 텍스트는 - `401`/`403` 응답에서도 여기에 들어올 수 있지만, provider별 텍스트 - 매처는 해당 provider 범위 안에서만 유지됩니다(예: OpenRouter - `Key limit exceeded`). 재시도 가능한 HTTP `402` 사용량 창 또는 - 조직/워크스페이스 지출 한도 메시지는 대신 `rate_limit` 경로에 - 남습니다. +- `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`: 모델 대체로 전환하기 전에 과부하 오류에 대해 같은 provider의 auth-profile을 회전할 수 있는 최대 횟수입니다(기본값: `1`). `ModelNotReadyException` 같은 provider-busy 형태가 여기에 해당합니다. -- `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 형식의 텍스트도 포함됩니다. +- `billingMaxHours`: 청구 backoff 지수 증가의 상한(시간 단위)입니다(기본값: `24`). +- `authPermanentBackoffMinutes`: 높은 신뢰도의 `auth_permanent` 실패에 대한 기본 backoff 시간(분 단위)입니다(기본값: `10`). +- `authPermanentMaxMinutes`: `auth_permanent` backoff 증가의 상한(분 단위)입니다(기본값: `60`). +- `failureWindowHours`: backoff 카운터에 사용되는 롤링 창(시간 단위)입니다(기본값: `24`). +- `overloadedProfileRotations`: overloaded 오류 시 모델 fallback으로 전환하기 전 같은 provider auth-profile 회전의 최대 횟수입니다(기본값: `1`). `ModelNotReadyException` 같은 provider-busy 형태가 여기에 해당합니다. +- `overloadedBackoffMs`: overloaded provider/profile 회전을 다시 시도하기 전의 고정 지연(ms)입니다(기본값: `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 형태 텍스트도 포함됩니다. --- @@ -3512,7 +3503,7 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 - 기본 로그 파일: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - 고정 경로를 원하면 `logging.file`을 설정하세요. - `consoleLevel`은 `--verbose`일 때 `debug`로 올라갑니다. -- `maxFileBytes`: 쓰기를 억제하기 전 허용되는 최대 로그 파일 크기(바이트 단위, 양의 정수, 기본값: `524288000` = 500 MB)입니다. 프로덕션 배포에서는 외부 로그 회전을 사용하세요. +- `maxFileBytes`: 쓰기 억제가 시작되기 전 최대 로그 파일 크기(바이트)입니다(양의 정수, 기본값: `524288000` = 500 MB). 프로덕션 배포에서는 외부 로그 순환을 사용하세요. --- @@ -3549,20 +3540,20 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 } ``` -- `enabled`: 계측 출력의 마스터 토글입니다(기본값: `true`). -- `flags`: 대상 로그 출력을 활성화하는 플래그 문자열 배열입니다(`"telegram.*"` 또는 `"*"` 같은 와일드카드 지원). -- `stuckSessionWarnMs`: 세션이 처리 상태로 남아 있는 동안 정체된 세션 경고를 출력하기 위한 경과 시간 임계값(밀리초)입니다. +- `enabled`: 계측 출력용 마스터 토글입니다(기본값: `true`). +- `flags`: 대상 지정 로그 출력을 활성화하는 플래그 문자열 배열입니다(`"telegram.*"` 또는 `"*"` 같은 와일드카드 지원). +- `stuckSessionWarnMs`: 세션이 처리 상태에 머무는 동안 멈춘 세션 경고를 출력하기 위한 기준 시간(ms)입니다. - `otel.enabled`: OpenTelemetry 내보내기 파이프라인을 활성화합니다(기본값: `false`). - `otel.endpoint`: OTel 내보내기용 collector URL입니다. -- `otel.protocol`: `"http/protobuf"`(기본값) 또는 `"grpc"`입니다. +- `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`: 내장 실행에 대한 캐시 trace 스냅샷 기록을 활성화합니다(기본값: `false`). -- `cacheTrace.filePath`: 캐시 trace JSONL 출력 경로입니다(기본값: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: 캐시 trace 출력에 무엇을 포함할지 제어합니다(모두 기본값: `true`). +- `otel.serviceName`: 리소스 속성용 서비스 이름입니다. +- `otel.traces` / `otel.metrics` / `otel.logs`: trace, metrics, 또는 log 내보내기를 활성화합니다. +- `otel.sampleRate`: trace 샘플링 비율 `0`–`1`. +- `otel.flushIntervalMs`: 주기적 텔레메트리 flush 간격(ms)입니다. +- `cacheTrace.enabled`: 임베디드 실행용 캐시 추적 스냅샷을 기록합니다(기본값: `false`). +- `cacheTrace.filePath`: 캐시 추적 JSONL 출력 경로입니다(기본값: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: 캐시 추적 출력에 포함할 항목을 제어합니다(모두 기본값: `true`). --- @@ -3586,10 +3577,10 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 - `channel`: npm/git 설치용 릴리스 채널입니다 — `"stable"`, `"beta"`, 또는 `"dev"`. - `checkOnStart`: gateway 시작 시 npm 업데이트를 확인합니다(기본값: `true`). -- `auto.enabled`: 패키지 설치에 대한 백그라운드 자동 업데이트를 활성화합니다(기본값: `false`). -- `auto.stableDelayHours`: stable 채널 자동 적용 전 최소 지연 시간(시간 단위, 기본값: `6`, 최대: `168`)입니다. -- `auto.stableJitterHours`: stable 채널 롤아웃 분산을 위한 추가 시간 창(기본값: `12`, 최대: `168`)입니다. -- `auto.betaCheckIntervalHours`: beta 채널 확인 실행 간격(시간 단위, 기본값: `1`, 최대: `24`)입니다. +- `auto.enabled`: 패키지 설치에 대해 백그라운드 자동 업데이트를 활성화합니다(기본값: `false`). +- `auto.stableDelayHours`: stable 채널 자동 적용 전 최소 지연 시간(시간 단위)입니다(기본값: `6`, 최대: `168`). +- `auto.stableJitterHours`: stable 채널 롤아웃 분산용 추가 시간 창(시간 단위)입니다(기본값: `12`, 최대: `168`). +- `auto.betaCheckIntervalHours`: beta 채널 확인이 실행되는 간격(시간 단위)입니다(기본값: `1`, 최대: `24`). --- @@ -3623,20 +3614,20 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 ``` - `enabled`: 전역 ACP 기능 게이트입니다(기본값: `false`). -- `dispatch.enabled`: ACP 세션 턴 디스패치를 위한 독립 게이트입니다(기본값: `true`). ACP 명령은 계속 사용 가능하게 두면서 실행만 차단하려면 `false`로 설정하세요. -- `backend`: 기본 ACP 런타임 backend ID입니다(등록된 ACP 런타임 Plugin과 일치해야 함). -- `defaultAgent`: 생성 시 명시적 대상이 지정되지 않았을 때의 대체 ACP 대상 에이전트 ID입니다. -- `allowedAgents`: ACP 런타임 세션에 허용되는 에이전트 ID 허용 목록입니다. 비어 있으면 추가 제한이 없습니다. +- `dispatch.enabled`: ACP 세션 턴 디스패치용 독립 게이트입니다(기본값: `true`). ACP 명령은 계속 사용 가능하게 두면서 실행만 차단하려면 `false`로 설정하세요. +- `backend`: 기본 ACP 런타임 백엔드 ID입니다(등록된 ACP 런타임 Plugin과 일치해야 함). +- `defaultAgent`: 생성 시 명시적 대상을 지정하지 않았을 때 사용하는 대체 ACP 대상 에이전트 ID입니다. +- `allowedAgents`: ACP 런타임 세션에 허용되는 에이전트 ID의 허용 목록입니다. 비어 있으면 추가 제한이 없습니다. - `maxConcurrentSessions`: 동시에 활성화될 수 있는 ACP 세션의 최대 수입니다. -- `stream.coalesceIdleMs`: 스트리밍 텍스트용 유휴 flush 창(밀리초)입니다. +- `stream.coalesceIdleMs`: 스트리밍 텍스트용 idle flush 창(ms)입니다. - `stream.maxChunkChars`: 스트리밍 블록 투영을 분할하기 전 최대 청크 크기입니다. -- `stream.repeatSuppression`: 턴당 반복되는 상태/도구 줄을 억제합니다(기본값: `true`). +- `stream.repeatSuppression`: 턴별 반복 상태/도구 줄을 억제합니다(기본값: `true`). - `stream.deliveryMode`: `"live"`는 점진적으로 스트리밍하고, `"final_only"`는 턴 종료 이벤트까지 버퍼링합니다. -- `stream.hiddenBoundarySeparator`: 숨겨진 도구 이벤트 뒤에 표시되는 텍스트 앞에 넣을 구분자입니다(기본값: `"paragraph"`). -- `stream.maxOutputChars`: ACP 턴당 투영되는 assistant 출력 최대 문자 수입니다. -- `stream.maxSessionUpdateChars`: 투영되는 ACP 상태/업데이트 줄의 최대 문자 수입니다. -- `stream.tagVisibility`: 스트리밍 이벤트에 대한 태그 이름별 불리언 가시성 재정의 기록입니다. -- `runtime.ttlMinutes`: 정리 대상이 되기 전 ACP 세션 작업자의 유휴 TTL(분)입니다. +- `stream.hiddenBoundarySeparator`: 숨겨진 도구 이벤트 뒤의 표시 텍스트 앞에 넣는 구분자입니다(기본값: `"paragraph"`). +- `stream.maxOutputChars`: ACP 턴당 투영되는 assistant 출력의 최대 문자 수입니다. +- `stream.maxSessionUpdateChars`: 투영된 ACP 상태/업데이트 줄의 최대 문자 수입니다. +- `stream.tagVisibility`: 스트리밍 이벤트에 대한 태그 이름별 불리언 표시 재정의 레코드입니다. +- `runtime.ttlMinutes`: 정리 대상이 되기 전 ACP 세션 워커의 idle TTL(분 단위)입니다. - `runtime.installCommand`: ACP 런타임 환경 bootstrap 시 실행할 선택적 설치 명령입니다. --- @@ -3663,7 +3654,7 @@ SecretRef는 추가 기능입니다. 평문 값도 계속 사용할 수 있습 ## Wizard -CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 메타데이터입니다: +CLI 안내 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 메타데이터입니다: ```json5 { @@ -3685,11 +3676,11 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 --- -## Bridge (레거시, 제거됨) +## Bridge(레거시, 제거됨) -현재 빌드에는 더 이상 TCP bridge가 포함되지 않습니다. Node는 Gateway WebSocket을 통해 연결됩니다. `bridge.*` 키는 더 이상 구성 스키마의 일부가 아닙니다(제거할 때까지 검증 실패, `openclaw doctor --fix`로 알 수 없는 키를 제거할 수 있음). +현재 빌드에는 더 이상 TCP bridge가 포함되지 않습니다. Node는 Gateway WebSocket을 통해 연결됩니다. `bridge.*` 키는 더 이상 구성 스키마의 일부가 아닙니다(제거할 때까지 유효성 검사 실패, `openclaw doctor --fix`로 알 수 없는 키를 제거할 수 있음). - + ```json { @@ -3716,8 +3707,8 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // 저장된 notify:true 작업용 사용 중단 예정 대체값 - webhookToken: "replace-with-dedicated-token", // 발신 webhook 인증용 선택적 bearer token + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // outbound webhook 인증용 선택적 bearer 토큰 sessionRetention: "24h", // 기간 문자열 또는 false runLog: { maxBytes: "2mb", // 기본값 2_000_000 bytes @@ -3727,11 +3718,11 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 } ``` -- `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 token입니다. 생략하면 인증 헤더를 보내지 않습니다. -- `webhook`: 저장된 작업 중 여전히 `notify: true`가 있는 작업에만 사용되는 사용 중단 예정 레거시 대체 webhook URL(http/https)입니다. +- `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`를 가진 작업에만 사용되는 deprecated 레거시 대체 webhook URL(http/https)입니다. ### `cron.retry` @@ -3747,9 +3738,9 @@ 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`: 각 재시도 시도에 대한 backoff 지연(ms) 배열입니다(기본값: `[30000, 60000, 300000]`, 항목 수 1–10개). +- `retryOn`: 재시도를 트리거하는 오류 유형입니다 — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. 생략하면 모든 일시적 유형을 재시도합니다. 일회성 cron 작업에만 적용됩니다. 반복 작업은 별도의 실패 처리 방식을 사용합니다. @@ -3771,9 +3762,9 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 - `enabled`: cron 작업에 대한 실패 알림을 활성화합니다(기본값: `false`). - `after`: 알림이 발생하기 전 연속 실패 횟수입니다(양의 정수, 최소: `1`). -- `cooldownMs`: 동일 작업에 대해 반복 알림 사이의 최소 간격(밀리초)입니다(음수가 아닌 정수). +- `cooldownMs`: 동일 작업에 대해 반복 알림 사이에 필요한 최소 밀리초입니다(음이 아닌 정수). - `mode`: 전달 모드입니다 — `"announce"`는 채널 메시지로 보내고, `"webhook"`은 구성된 webhook으로 POST합니다. -- `accountId`: 알림 전달 범위를 제한할 선택적 계정 또는 채널 ID입니다. +- `accountId`: 알림 전달 범위를 지정하는 선택적 계정 또는 채널 ID입니다. ### `cron.failureDestination` @@ -3790,7 +3781,7 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 } ``` -- 모든 작업에 대한 cron 실패 알림의 기본 대상입니다. +- 모든 작업에 걸친 cron 실패 알림의 기본 대상입니다. - `mode`: `"announce"` 또는 `"webhook"`이며, 충분한 대상 데이터가 있으면 기본값은 `"announce"`입니다. - `channel`: announce 전달용 채널 재정의입니다. `"last"`는 마지막으로 알려진 전달 채널을 재사용합니다. - `to`: 명시적 announce 대상 또는 webhook URL입니다. webhook 모드에서는 필수입니다. @@ -3805,36 +3796,36 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 ## 미디어 모델 템플릿 변수 -`tools.media.models[].args`에서 확장되는 템플릿 placeholder: +`tools.media.models[].args`에서 확장되는 템플릿 placeholder입니다: -| 변수 | 설명 | -| ------------------ | ------------------------------------------- | -| `{{Body}}` | 전체 수신 메시지 본문 | -| `{{RawBody}}` | 원시 본문(기록/발신자 래퍼 없음) | -| `{{BodyStripped}}` | 그룹 멘션이 제거된 본문 | -| `{{From}}` | 발신자 식별자 | -| `{{To}}` | 대상 식별자 | -| `{{MessageSid}}` | 채널 메시지 ID | -| `{{SessionId}}` | 현재 세션 UUID | -| `{{IsNewSession}}` | 새 세션이 생성되었으면 `"true"` | -| `{{MediaUrl}}` | 수신 미디어 pseudo-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}}` | 수신 미디어 pseudo-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 등) | --- ## 구성 include (`$include`) -구성을 여러 파일로 분할할 수 있습니다: +구성을 여러 파일로 분리합니다: ```json5 // ~/.openclaw/openclaw.json @@ -3849,13 +3840,13 @@ CLI 안내형 설정 흐름(`onboard`, `configure`, `doctor`)이 기록하는 **병합 동작:** -- 단일 파일: 포함된 객체를 대체합니다. -- 파일 배열: 순서대로 깊은 병합됩니다(뒤 항목이 앞 항목을 재정의). -- 형제 키: include 후에 병합됩니다(include된 값을 재정의). +- 단일 파일: 포함하는 객체를 대체합니다. +- 파일 배열: 순서대로 deep-merge됩니다(뒤의 항목이 앞의 항목을 재정의). +- 형제 키: include 후 병합됩니다(include된 값을 재정의). - 중첩 include: 최대 10단계 깊이까지 허용됩니다. -- 경로: 포함하는 파일을 기준으로 해석되지만 최상위 구성 디렉터리(`openclaw.json`의 `dirname`) 내부에 있어야 합니다. 절대 경로/`../` 형식도 최종적으로 그 경계 안에서 해석되는 경우에만 허용됩니다. +- 경로: 포함하는 파일 기준으로 해석되지만 최상위 구성 디렉터리(`openclaw.json`의 `dirname`) 내부에 머물러야 합니다. 절대 경로/`../` 형식도 해당 경계 내부로 해석되는 경우에만 허용됩니다. - 오류: 누락된 파일, 파싱 오류, 순환 include에 대해 명확한 메시지를 제공합니다. --- -_관련 문서: [Configuration](/ko/gateway/configuration) · [Configuration Examples](/ko/gateway/configuration-examples) · [Doctor](/ko/gateway/doctor)_ +_관련 항목: [Configuration](/ko/gateway/configuration) · [구성 예시](/ko/gateway/configuration-examples) · [Doctor](/ko/gateway/doctor)_ diff --git a/docs/ko/help/faq.md b/docs/ko/help/faq.md index 669257bcf..065b411d1 100644 --- a/docs/ko/help/faq.md +++ b/docs/ko/help/faq.md @@ -1,23 +1,23 @@ --- read_when: - 일반적인 설정, 설치, 온보딩 또는 런타임 지원 질문에 답변하기 - - 더 깊은 디버깅에 들어가기 전에 사용자가 보고한 문제를 분류하기 -summary: OpenClaw 설정, 구성 및 사용에 관한 자주 묻는 질문 -title: FAQ + - 더 깊이 있는 디버깅에 앞서 사용자가 보고한 문제 분류하기 +summary: OpenClaw 설정, 구성 및 사용에 관해 자주 묻는 질문 +title: 자주 묻는 질문 x-i18n: - generated_at: "2026-04-12T23:28:25Z" + generated_at: "2026-04-20T06:05:32Z" model: gpt-5.4 provider: openai - source_hash: d2a78d0fea9596625cc2753e6dc8cc42c2379a3a0c91729265eee0261fe53eaa + source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 source_path: help/faq.md workflow: 15 --- -# FAQ +# 자주 묻는 질문 -빠른 답변과 실제 환경 설정(로컬 개발, VPS, 멀티 에이전트, OAuth/API 키, 모델 페일오버)에 대한 더 깊은 문제 해결을 제공합니다. 런타임 진단은 [문제 해결](/ko/gateway/troubleshooting)을 참고하세요. 전체 구성 참조는 [구성](/ko/gateway/configuration)을 참고하세요. +실제 환경 설정(로컬 개발, VPS, 멀티 에이전트, OAuth/API 키, 모델 장애 조치)을 위한 빠른 답변과 더 깊이 있는 문제 해결입니다. 런타임 진단은 [문제 해결](/ko/gateway/troubleshooting)을 참고하세요. 전체 구성 참조는 [구성](/ko/gateway/configuration)을 참고하세요. -## 문제가 생겼을 때 처음 60초 안에 할 일 +## 문제가 생겼을 때 처음 60초 1. **빠른 상태 확인(첫 번째 점검)** @@ -25,15 +25,15 @@ x-i18n: openclaw status ``` - 빠른 로컬 요약: OS + 업데이트, gateway/service 연결 가능 여부, 에이전트/세션, 제공자 구성 + 런타임 문제(gateway에 연결 가능한 경우). + 빠른 로컬 요약: OS + 업데이트, gateway/service 연결 가능 여부, agents/sessions, provider 구성 + 런타임 문제(gateway에 연결 가능한 경우). -2. **공유 가능한 보고서(안전하게 공유 가능)** +2. **공유하기 안전한 붙여넣기용 보고서** ```bash openclaw status --all ``` - 읽기 전용 진단과 로그 tail을 제공합니다(토큰은 redacted 처리됨). + 읽기 전용 진단과 로그 tail을 표시합니다(토큰은 마스킹됨). 3. **데몬 + 포트 상태** @@ -41,16 +41,16 @@ x-i18n: openclaw gateway status ``` - supervisor 런타임과 RPC 연결 가능 여부, probe 대상 URL, 그리고 서비스가 어떤 구성을 사용했을 가능성이 높은지를 보여줍니다. + supervisor 런타임과 RPC 연결 가능 여부, probe 대상 URL, 그리고 서비스가 사용했을 가능성이 높은 구성을 보여줍니다. -4. **심층 probe** +4. **심층 프로브** ```bash openclaw status --deep ``` - 지원되는 경우 채널 probe를 포함한 실시간 gateway 상태 probe를 실행합니다 - (연결 가능한 gateway 필요). [Health](/ko/gateway/health)를 참고하세요. + 지원되는 경우 channel probe를 포함한 라이브 gateway 상태 probe를 실행합니다 + (연결 가능한 gateway 필요). [상태](/ko/gateway/health)를 참고하세요. 5. **최신 로그 tail 보기** @@ -58,57 +58,56 @@ x-i18n: openclaw logs --follow ``` - RPC가 내려가 있으면 다음으로 대체하세요. + RPC가 내려가 있으면 다음으로 대체하세요: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 파일 로그는 서비스 로그와 별도입니다. [로깅](/ko/logging) 및 [문제 해결](/ko/gateway/troubleshooting)을 참고하세요. + 파일 로그는 서비스 로그와 별개입니다. [로깅](/ko/logging) 및 [문제 해결](/ko/gateway/troubleshooting)을 참고하세요. -6. **Doctor 실행(복구)** +6. **doctor 실행(복구)** ```bash openclaw doctor ``` - 구성/상태를 복구하거나 마이그레이션하고 상태 점검을 실행합니다. [Doctor](/ko/gateway/doctor)를 참고하세요. + 구성/상태를 복구·마이그레이션하고 상태 점검을 실행합니다. [Doctor](/ko/gateway/doctor)를 참고하세요. 7. **Gateway 스냅샷** ```bash openclaw health --json - openclaw health --verbose # 오류 시 대상 URL + 구성 경로를 표시합니다 + openclaw health --verbose # 오류 시 대상 URL + config 경로를 표시합니다 ``` - 실행 중인 gateway에 전체 스냅샷을 요청합니다(WS 전용). [Health](/ko/gateway/health)를 참고하세요. + 실행 중인 Gateway에 전체 스냅샷을 요청합니다(WS 전용). [상태](/ko/gateway/health)를 참고하세요. ## 빠른 시작 및 첫 실행 설정 - - **사용 중인 머신을 볼 수 있는** 로컬 AI 에이전트를 사용하세요. 이는 Discord에서 묻는 것보다 훨씬 효과적입니다. 대부분의 "막혔어요" 사례는 **로컬 구성 또는 환경 문제**이기 때문에 원격 도우미가 직접 확인할 수 없습니다. + + **내 컴퓨터를 볼 수 있는** 로컬 AI agent를 사용하세요. 이는 Discord에서 묻는 것보다 훨씬 효과적입니다. 대부분의 "막혔어요" 사례는 원격 도우미가 직접 확인할 수 없는 **로컬 구성 또는 환경 문제**이기 때문입니다. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - 이 도구들은 저장소를 읽고, 명령을 실행하고, 로그를 확인하고, 머신 수준 설정(PATH, 서비스, 권한, 인증 파일)을 고치는 데 도움을 줄 수 있습니다. 해킹 가능한(git) 설치 방식으로 **전체 소스 체크아웃**을 제공하세요. + 이런 도구는 리포지토리를 읽고, 명령을 실행하고, 로그를 확인하고, 머신 수준 설정(PATH, 서비스, 권한, 인증 파일)을 고치는 데 도움을 줄 수 있습니다. hackable (git) 설치를 통해 **전체 소스 체크아웃**을 제공하세요: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 이렇게 하면 git 체크아웃에서 OpenClaw를 설치하므로 에이전트가 코드와 문서를 읽고 - 현재 실행 중인 정확한 버전을 기준으로 추론할 수 있습니다. 나중에 설치 프로그램을 `--install-method git` 없이 다시 실행하면 언제든 안정 버전으로 돌아갈 수 있습니다. + 이렇게 하면 OpenClaw가 **git 체크아웃에서** 설치되므로, agent가 코드와 문서를 읽고 + 현재 실행 중인 정확한 버전을 기준으로 추론할 수 있습니다. 나중에 `--install-method git` 없이 설치 프로그램을 다시 실행해 언제든 stable로 되돌릴 수 있습니다. - 팁: 에이전트에게 수정 작업을 **계획하고 감독**하게 하세요(단계별로). 그런 다음 필요한 - 명령만 실행하세요. 그러면 변경 범위가 작아지고 감사하기도 쉬워집니다. + 팁: agent에게 수정 작업을 **계획하고 감독**(단계별로)하도록 요청한 다음, 필요한 명령만 실행하게 하세요. 그러면 변경이 작고 감사하기 쉬워집니다. - 실제 버그나 수정 사항을 발견했다면 GitHub 이슈를 올리거나 PR을 보내 주세요. + 실제 버그나 수정 사항을 발견했다면 GitHub issue를 등록하거나 PR을 보내주세요: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - 도움을 요청할 때는 먼저 다음 명령을 실행하고 출력 결과를 공유하세요. + 도움을 요청할 때는 먼저 다음 명령으로 시작하세요(출력을 함께 공유하세요): ```bash openclaw status @@ -118,42 +117,42 @@ x-i18n: 각 명령의 역할: - - `openclaw status`: gateway/에이전트 상태 + 기본 구성의 빠른 스냅샷 - - `openclaw models status`: 제공자 인증 + 모델 사용 가능 여부 점검 + - `openclaw status`: gateway/agent 상태 + 기본 구성의 빠른 스냅샷 + - `openclaw models status`: provider 인증 + 모델 사용 가능 여부 확인 - `openclaw doctor`: 일반적인 구성/상태 문제를 검증하고 복구 그 밖에 유용한 CLI 점검: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - 빠른 디버그 루프: [문제가 생겼을 때 처음 60초 안에 할 일](#문제가-생겼을-때-처음-60초-안에-할-일). + 빠른 디버그 루프: [문제가 생겼을 때 처음 60초](#문제가-생겼을-때-처음-60초). 설치 문서: [설치](/ko/install), [설치 프로그램 플래그](/ko/install/installer), [업데이트](/ko/install/updating). - - 일반적인 Heartbeat skip 이유: + + 일반적인 heartbeat 건너뛰기 사유: - - `quiet-hours`: 구성된 active-hours 범위 밖임 - - `empty-heartbeat-file`: `HEARTBEAT.md`가 존재하지만 비어 있거나 헤더만 있는 기본 골격만 포함함 - - `no-tasks-due`: `HEARTBEAT.md` 작업 모드가 활성화되어 있지만 어떤 작업 간격도 아직 도래하지 않음 - - `alerts-disabled`: 모든 Heartbeat 가시성이 비활성화됨(`showOk`, `showAlerts`, `useIndicator`가 모두 꺼짐) + - `quiet-hours`: 구성된 active-hours 시간대 밖 + - `empty-heartbeat-file`: `HEARTBEAT.md`가 존재하지만 빈 내용 또는 헤더만 있는 골격만 포함 + - `no-tasks-due`: `HEARTBEAT.md` task 모드가 활성화되어 있지만 아직 어떤 task interval도 도래하지 않음 + - `alerts-disabled`: heartbeat 표시가 모두 비활성화됨(`showOk`, `showAlerts`, `useIndicator`가 모두 꺼짐) - 작업 모드에서는 실제 Heartbeat 실행이 완료된 후에만 - 도래 시각이 갱신됩니다. 건너뛴 실행은 작업을 완료된 것으로 표시하지 않습니다. + task 모드에서는 실제 heartbeat 실행이 완료된 후에만 + 예정 시각이 갱신됩니다. 건너뛴 실행은 task를 완료된 것으로 표시하지 않습니다. 문서: [Heartbeat](/ko/gateway/heartbeat), [자동화 및 작업](/ko/automation). - - 저장소에서는 소스에서 실행하고 온보딩을 사용하는 방식을 권장합니다. + + 이 리포지토리는 소스에서 실행하고 온보딩을 사용하는 방식을 권장합니다: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - 이 마법사는 UI 자산도 자동으로 빌드할 수 있습니다. 온보딩 후에는 일반적으로 포트 **18789**에서 Gateway를 실행합니다. + 마법사는 UI 자산도 자동으로 빌드할 수 있습니다. 온보딩 후에는 일반적으로 **18789** 포트에서 Gateway를 실행합니다. 소스에서 실행(기여자/개발자): @@ -162,7 +161,7 @@ x-i18n: cd openclaw pnpm install pnpm build - pnpm ui:build # 첫 실행 시 UI 의존성을 자동 설치합니다 + pnpm ui:build openclaw onboard ``` @@ -170,94 +169,94 @@ x-i18n: - - 마법사는 온보딩 직후 깨끗한(토큰이 포함되지 않은) 대시보드 URL로 브라우저를 열고, 요약에도 해당 링크를 출력합니다. 그 탭을 계속 열어 두세요. 자동 실행되지 않았다면 같은 머신에서 출력된 URL을 복사해 붙여넣으세요. + + 마법사는 온보딩 직후 깔끔한(토큰이 포함되지 않은) dashboard URL로 브라우저를 열고, 요약에도 링크를 출력합니다. 그 탭을 계속 열어 두세요. 실행되지 않았다면 같은 컴퓨터에서 출력된 URL을 복사해 붙여넣으세요. - - **Localhost(같은 머신):** + + **Localhost(같은 컴퓨터):** - `http://127.0.0.1:18789/`를 엽니다. - - 공유 비밀 인증을 요구하면 구성된 토큰 또는 비밀번호를 Control UI 설정에 붙여넣으세요. - - 토큰 소스: `gateway.auth.token` (또는 `OPENCLAW_GATEWAY_TOKEN`) - - 비밀번호 소스: `gateway.auth.password` (또는 `OPENCLAW_GATEWAY_PASSWORD`) - - 아직 공유 비밀이 구성되지 않았다면 `openclaw doctor --generate-gateway-token`으로 토큰을 생성하세요. + - 공유 시크릿 인증을 요구하면, 구성된 token 또는 password를 Control UI 설정에 붙여넣습니다. + - token 소스: `gateway.auth.token`(또는 `OPENCLAW_GATEWAY_TOKEN`) + - password 소스: `gateway.auth.password`(또는 `OPENCLAW_GATEWAY_PASSWORD`) + - 아직 공유 시크릿이 구성되지 않았다면 `openclaw doctor --generate-gateway-token`으로 token을 생성하세요. - **Localhost가 아닌 경우:** + **localhost가 아닌 경우:** - - **Tailscale Serve**(권장): bind를 loopback으로 유지하고 `openclaw gateway --tailscale serve`를 실행한 뒤 `https:///`를 여세요. `gateway.auth.allowTailscale`가 `true`이면 identity header가 Control UI/WebSocket 인증을 충족합니다(공유 비밀을 붙여넣을 필요 없음, 신뢰된 gateway host를 전제로 함). HTTP API는 private-ingress `none` 또는 trusted-proxy HTTP auth를 의도적으로 사용하지 않는 한 여전히 공유 비밀 인증이 필요합니다. - 같은 클라이언트에서 동시에 잘못된 Serve 인증을 시도하면 failed-auth limiter가 기록하기 전에 직렬화되므로, 두 번째 잘못된 재시도에서는 이미 `retry later`가 표시될 수 있습니다. - - **Tailnet bind**: `openclaw gateway --bind tailnet --token ""`를 실행하거나(또는 비밀번호 인증 구성), `http://:18789/`를 열고, 대시보드 설정에 일치하는 공유 비밀을 붙여넣으세요. - - **ID 인식 reverse proxy**: Gateway를 non-loopback trusted proxy 뒤에 두고 `gateway.auth.mode: "trusted-proxy"`를 구성한 다음, proxy URL을 여세요. - - **SSH 터널**: `ssh -N -L 18789:127.0.0.1:18789 user@host` 후 `http://127.0.0.1:18789/`를 여세요. 터널을 통해서도 공유 비밀 인증은 그대로 적용되며, 요청받으면 구성된 토큰 또는 비밀번호를 붙여넣으세요. + - **Tailscale Serve**(권장): bind를 loopback으로 유지하고, `openclaw gateway --tailscale serve`를 실행한 뒤 `https:///`를 엽니다. `gateway.auth.allowTailscale`이 `true`이면 ID 헤더가 Control UI/WebSocket 인증을 충족합니다(공유 시크릿을 붙여넣을 필요 없음, 신뢰할 수 있는 gateway 호스트를 전제로 함). HTTP API는 private-ingress `none` 또는 trusted-proxy HTTP 인증을 의도적으로 사용하지 않는 한 여전히 공유 시크릿 인증이 필요합니다. + 동일한 클라이언트에서 동시에 잘못된 Serve 인증을 시도하면 실패 인증 제한기가 기록하기 전에 직렬화되므로, 두 번째 잘못된 재시도에서 이미 `retry later`가 표시될 수 있습니다. + - **Tailnet bind**: `openclaw gateway --bind tailnet --token ""`를 실행하거나(password 인증을 구성해도 됨), `http://:18789/`를 연 다음, dashboard 설정에 일치하는 공유 시크릿을 붙여넣습니다. + - **ID 인식 reverse proxy**: Gateway를 loopback이 아닌 trusted proxy 뒤에 두고, `gateway.auth.mode: "trusted-proxy"`를 구성한 다음 proxy URL을 엽니다. + - **SSH 터널**: `ssh -N -L 18789:127.0.0.1:18789 user@host` 후 `http://127.0.0.1:18789/`를 엽니다. 터널을 사용해도 공유 시크릿 인증은 그대로 적용되므로, 요청받으면 구성된 token 또는 password를 붙여넣으세요. - bind 모드와 인증 세부 정보는 [대시보드](/web/dashboard) 및 [웹 표면](/web)을 참고하세요. + bind 모드와 인증 세부 사항은 [Dashboard](/web/dashboard) 및 [웹 표면](/web)을 참고하세요. - 서로 다른 계층을 제어합니다. + 이들은 서로 다른 계층을 제어합니다: - `approvals.exec`: 승인 프롬프트를 채팅 대상에게 전달합니다 - - `channels..execApprovals`: 해당 채널이 exec 승인용 네이티브 승인 클라이언트로 동작하게 합니다 + - `channels..execApprovals`: 해당 channel이 exec 승인을 위한 네이티브 승인 클라이언트로 동작하게 합니다 - 호스트 exec 정책은 여전히 실제 승인 게이트입니다. 채팅 구성은 승인 - 프롬프트가 어디에 표시되는지와 사람들이 어떻게 응답할 수 있는지만 제어합니다. + 호스트 exec 정책이 여전히 실제 승인 게이트입니다. 채팅 구성은 승인 + 프롬프트가 어디에 나타나는지와 사용자가 어떻게 응답할 수 있는지만 제어합니다. - 대부분의 설정에서는 **둘 다** 필요하지 않습니다. + 대부분의 설정에서는 **둘 다** 필요하지 않습니다: - - 채팅이 이미 명령과 응답을 지원한다면 같은 채팅의 `/approve`가 공유 경로를 통해 동작합니다. - - 지원되는 네이티브 채널이 approver를 안전하게 추론할 수 있다면, OpenClaw는 이제 `channels..execApprovals.enabled`가 설정되지 않았거나 `"auto"`일 때 DM 우선 네이티브 승인을 자동 활성화합니다. - - 네이티브 승인 카드/버튼을 사용할 수 있으면 해당 네이티브 UI가 기본 경로이며, 에이전트는 도구 결과에 채팅 승인을 사용할 수 없거나 수동 승인이 유일한 경로라고 표시될 때만 수동 `/approve` 명령을 포함해야 합니다. - - 프롬프트를 다른 채팅이나 명시적인 운영 방에도 전달해야 할 때만 `approvals.exec`를 사용하세요. - - 승인 프롬프트를 원래 방/토픽에도 다시 게시하려는 경우에만 `channels..execApprovals.target: "channel"` 또는 `"both"`를 사용하세요. - - Plugin 승인은 또 별개입니다. 기본적으로 같은 채팅의 `/approve`를 사용하고, 선택적으로 `approvals.plugin` 전달을 사용할 수 있으며, 일부 네이티브 채널만 여기에 plugin 승인 네이티브 처리를 추가로 유지합니다. + - 채팅이 이미 명령과 응답을 지원한다면, 동일 채팅의 `/approve`가 공유 경로를 통해 작동합니다. + - 지원되는 네이티브 channel이 approver를 안전하게 추론할 수 있다면, OpenClaw는 이제 `channels..execApprovals.enabled`가 설정되지 않았거나 `"auto"`일 때 DM 우선 네이티브 승인을 자동 활성화합니다. + - 네이티브 승인 카드/버튼을 사용할 수 있을 때는 그 네이티브 UI가 기본 경로이며, agent는 도구 결과가 채팅 승인을 사용할 수 없다고 하거나 수동 승인이 유일한 경로라고 말하는 경우에만 수동 `/approve` 명령을 포함해야 합니다. + - 프롬프트도 다른 채팅이나 명시적인 운영 room으로 전달해야 할 때만 `approvals.exec`를 사용하세요. + - 승인 프롬프트를 원래 room/topic에 다시 게시하도록 명시적으로 원할 때만 `channels..execApprovals.target: "channel"` 또는 `"both"`를 사용하세요. + - Plugin 승인은 또 별개입니다. 기본적으로 동일 채팅 `/approve`, 선택적인 `approvals.plugin` 전달을 사용하며, 일부 네이티브 channel만 그 위에 plugin 승인 네이티브 처리를 유지합니다. - 짧게 말하면, 전달은 라우팅용이고 네이티브 클라이언트 구성은 더 풍부한 채널별 UX를 위한 것입니다. - [Exec Approvals](/ko/tools/exec-approvals)를 참고하세요. + 짧게 말하면: 전달은 라우팅용이고, 네이티브 클라이언트 구성은 더 풍부한 channel별 UX를 위한 것입니다. + [Exec 승인](/ko/tools/exec-approvals)을 참고하세요. - Node **>= 22**가 필요합니다. `pnpm` 사용을 권장합니다. Gateway에는 Bun을 **권장하지 않습니다**. + Node **>= 22**가 필요합니다. `pnpm`을 권장합니다. Gateway에는 Bun을 **권장하지 않습니다**. - 예. Gateway는 가볍습니다. 문서에는 개인 용도로 **512MB-1GB RAM**, **1 코어**, 약 **500MB** - 디스크면 충분하다고 되어 있으며, **Raspberry Pi 4에서 실행 가능**하다고 안내합니다. + 예. Gateway는 가볍습니다. 문서에는 개인 용도로 **512MB-1GB RAM**, **1개 코어**, 약 **500MB** + 디스크면 충분하다고 나와 있으며, **Raspberry Pi 4에서도 실행 가능**하다고 설명합니다. - 로그, 미디어, 다른 서비스 등을 위한 여유를 더 원한다면 **2GB를 권장**하지만, + 더 많은 여유 공간(로그, 미디어, 기타 서비스)이 필요하다면 **2GB를 권장**하지만, 필수 최소 사양은 아닙니다. - 팁: 소형 Pi/VPS에서 Gateway를 호스팅하고, 노트북/휴대폰에서 **Node**를 페어링해 + 팁: 작은 Pi/VPS에서 Gateway를 호스팅하고, 노트북/휴대폰에서 **nodes**를 페어링해 로컬 화면/카메라/canvas 또는 명령 실행을 사용할 수 있습니다. [Nodes](/ko/nodes)를 참고하세요. - 짧게 말하면: 작동하지만, 다소 거친 부분이 있을 수 있습니다. + 짧게 말하면: 작동은 하지만, 거친 부분이 있을 수 있습니다. - **64비트** OS를 사용하고 Node >= 22를 유지하세요. - - 로그를 보고 빠르게 업데이트할 수 있도록 **해킹 가능한(git) 설치**를 권장합니다. - - 채널/Skills 없이 시작한 뒤 하나씩 추가하세요. + - 로그를 보고 빠르게 업데이트할 수 있도록 **hackable (git) 설치**를 권장합니다. + - channels/Skills 없이 시작한 다음 하나씩 추가하세요. - 이상한 바이너리 문제가 생기면 대개 **ARM 호환성** 문제입니다. 문서: [Linux](/ko/platforms/linux), [설치](/ko/install). - - 그 화면은 Gateway에 연결 가능하고 인증이 되어 있어야 동작합니다. TUI도 첫 hatch에서 - 자동으로 "Wake up, my friend!"를 보냅니다. 그 문구가 보이는데도 **응답이 없고** - 토큰이 0으로 유지된다면, 에이전트가 실행되지 않은 것입니다. + + 이 화면은 Gateway에 연결 가능하고 인증되어 있어야 동작합니다. TUI도 첫 hatch에서 + "Wake up, my friend!"를 자동으로 보냅니다. 이 문구가 보이는데 **응답이 없고** + 토큰이 0에 머문다면, agent가 전혀 실행되지 않은 것입니다. - 1. Gateway를 다시 시작하세요. + 1. Gateway를 다시 시작하세요: ```bash openclaw gateway restart ``` - 2. 상태와 인증을 확인하세요. + 2. 상태 + 인증을 확인하세요: ```bash openclaw status @@ -265,69 +264,72 @@ x-i18n: openclaw logs --follow ``` - 3. 여전히 멈춰 있으면 다음을 실행하세요. + 3. 여전히 멈춘다면 다음을 실행하세요: ```bash openclaw doctor ``` - Gateway가 원격에 있다면 터널/Tailscale 연결이 올라와 있는지, 그리고 UI가 - 올바른 Gateway를 가리키고 있는지 확인하세요. [원격 액세스](/ko/gateway/remote)를 참고하세요. + Gateway가 원격에 있다면 터널/Tailscale 연결이 살아 있는지, 그리고 UI가 + 올바른 Gateway를 가리키는지 확인하세요. [원격 액세스](/ko/gateway/remote)를 참고하세요. - - 예. **state 디렉터리**와 **workspace**를 복사한 뒤 Doctor를 한 번 실행하세요. 이렇게 하면 - **두 위치를 모두** 복사하는 한 봇을 "완전히 동일하게"(메모리, 세션 기록, 인증, 채널 - 상태 포함) 유지할 수 있습니다. + + 예. **상태 디렉터리**와 **workspace**를 복사한 다음 Doctor를 한 번 실행하면 됩니다. 이렇게 하면 + **두 위치를 모두** 복사하는 한 봇을 "완전히 동일하게"(메모리, 세션 기록, 인증, channel + 상태 포함) 유지할 수 있습니다: - 1. 새 머신에 OpenClaw를 설치합니다. - 2. 이전 머신의 `$OPENCLAW_STATE_DIR`(기본값: `~/.openclaw`)를 복사합니다. + 1. 새 컴퓨터에 OpenClaw를 설치합니다. + 2. 이전 컴퓨터에서 `$OPENCLAW_STATE_DIR`(기본값: `~/.openclaw`)를 복사합니다. 3. workspace(기본값: `~/.openclaw/workspace`)를 복사합니다. 4. `openclaw doctor`를 실행하고 Gateway 서비스를 다시 시작합니다. - 이렇게 하면 config, auth 프로필, WhatsApp 자격 증명, 세션, 메모리가 보존됩니다. remote mode를 사용 중이라면 세션 저장소와 workspace는 gateway host가 소유한다는 점을 기억하세요. + 이렇게 하면 config, auth profile, WhatsApp 자격 증명, sessions, memory가 보존됩니다. remote mode를 사용 중이라면 + session 저장소와 workspace는 gateway 호스트가 소유한다는 점을 기억하세요. - **중요:** workspace만 GitHub에 commit/push하면 **메모리 + bootstrap 파일**은 백업되지만, **세션 기록이나 인증 정보**는 백업되지 않습니다. 이들은 `~/.openclaw/` 아래에 있습니다(예: `~/.openclaw/agents//sessions/`). + **중요:** workspace만 GitHub에 commit/push하면 + **memory + bootstrap 파일**은 백업되지만, **session 기록이나 인증 정보**는 백업되지 않습니다. 이들은 + `~/.openclaw/` 아래에 있습니다(예: `~/.openclaw/agents//sessions/`). - 관련 문서: [마이그레이션](/ko/install/migrating), [디스크에서 파일이 저장되는 위치](#디스크에서-파일이-저장되는-위치), - [에이전트 workspace](/ko/concepts/agent-workspace), [Doctor](/ko/gateway/doctor), - [remote mode](/ko/gateway/remote). + 관련 문서: [마이그레이션](/ko/install/migrating), [디스크에서 파일 위치](#디스크에서-파일-위치), + [Agent workspace](/ko/concepts/agent-workspace), [Doctor](/ko/gateway/doctor), + [Remote mode](/ko/gateway/remote). - - GitHub changelog를 확인하세요. + + GitHub changelog를 확인하세요: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - 최신 항목이 맨 위에 있습니다. 맨 위 섹션이 **Unreleased**로 표시되어 있으면, 그다음 날짜가 있는 - 섹션이 가장 최근에 배포된 버전입니다. 항목은 **Highlights**, **Changes**, **Fixes**로 그룹화되며 - (필요하면 docs/기타 섹션도 포함됩니다). + 최신 항목이 맨 위에 있습니다. 맨 위 섹션이 **Unreleased**로 표시되어 있으면, 그 다음 날짜가 있는 + 섹션이 가장 최근에 출시된 버전입니다. 항목은 **Highlights**, **Changes**, **Fixes** 기준으로 + 그룹화되어 있으며(필요한 경우 docs/기타 섹션도 포함됩니다). - + 일부 Comcast/Xfinity 연결에서는 Xfinity Advanced Security가 `docs.openclaw.ai`를 잘못 차단합니다. 이를 비활성화하거나 `docs.openclaw.ai`를 허용 목록에 추가한 뒤 다시 시도하세요. 차단 해제에 도움이 되도록 여기에서 신고해 주세요: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - 그래도 사이트에 접속할 수 없다면 문서는 GitHub에도 미러링되어 있습니다. + 여전히 사이트에 접근할 수 없다면, 문서는 GitHub에도 미러링되어 있습니다: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) - **Stable**과 **beta**는 별도의 코드 라인이 아니라 **npm dist-tag**입니다. + **Stable**과 **beta**는 별도의 코드 라인이 아니라 **npm dist-tag**입니다: - `latest` = stable - `beta` = 테스트용 초기 빌드 - 일반적으로 stable 릴리스는 먼저 **beta**에 올라간 다음, 명시적인 - 승격 단계에서 동일한 버전이 `latest`로 이동합니다. 유지관리자는 필요할 경우 - 곧바로 `latest`로 게시할 수도 있습니다. 그래서 승격 이후에는 beta와 stable이 + 보통 stable 릴리스는 먼저 **beta**에 올라가고, 이후 명시적인 + 승격 단계에서 같은 버전이 `latest`로 이동합니다. 유지 관리자는 필요할 경우 + 곧바로 `latest`에 게시할 수도 있습니다. 그래서 승격 이후에는 beta와 stable이 **같은 버전**을 가리킬 수 있습니다. - 변경 사항 보기: + 변경 사항 확인: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) 설치 원라이너와 beta와 dev의 차이는 아래 아코디언을 참고하세요. @@ -355,8 +357,8 @@ x-i18n: - - 두 가지 방법이 있습니다. + + 두 가지 방법이 있습니다: 1. **Dev 채널(git checkout):** @@ -364,17 +366,17 @@ x-i18n: openclaw update --channel dev ``` - 이렇게 하면 `main` 브랜치로 전환하고 소스에서 업데이트합니다. + 이렇게 하면 `main` 브랜치로 전환되고 소스에서 업데이트됩니다. - 2. **해킹 가능한 설치(설치 사이트에서):** + 2. **Hackable 설치(설치 사이트에서):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - 이렇게 하면 수정 가능한 로컬 저장소가 생기고, 이후 git으로 업데이트할 수 있습니다. + 이렇게 하면 편집 가능한 로컬 리포지토리가 생기고, 이후 git으로 업데이트할 수 있습니다. - 직접 깔끔하게 clone하고 싶다면 다음을 사용하세요. + 직접 깔끔하게 clone하고 싶다면 다음을 사용하세요: ```bash git clone https://github.com/openclaw/openclaw.git @@ -388,37 +390,37 @@ x-i18n: - + 대략적인 기준: - **설치:** 2-5분 - - **온보딩:** 구성하는 채널/모델 수에 따라 5-15분 + - **온보딩:** 구성하는 channels/models 수에 따라 5-15분 - 멈춘다면 [설치 프로그램이 멈췄나요?](#빠른-시작-및-첫-실행-설정)와 - [막혔습니다](#빠른-시작-및-첫-실행-설정)의 빠른 디버그 루프를 사용하세요. + 멈춘다면 [설치 프로그램이 멈췄나요?](#빠른-시작-및-첫-실행-설정) + 및 [막혔습니다](#빠른-시작-및-첫-실행-설정)의 빠른 디버그 루프를 사용하세요. - - 설치 프로그램을 **상세 출력**으로 다시 실행하세요. + + 설치 프로그램을 **자세한 출력**으로 다시 실행하세요: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - beta 설치를 상세 출력으로 실행: + verbose를 켠 beta 설치: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - 해킹 가능한(git) 설치의 경우: + hackable (git) 설치의 경우: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` - Windows(PowerShell)에서의 동등한 방법: + Windows(PowerShell) 대응 방법: ```powershell # install.ps1에는 아직 전용 -Verbose 플래그가 없습니다. @@ -431,37 +433,37 @@ x-i18n: - - Windows에서 흔한 두 가지 문제입니다. + + Windows에서 자주 발생하는 두 가지 문제: **1) npm error spawn git / git not found** - - **Git for Windows**를 설치하고 `git`이 PATH에 있도록 하세요. + - **Git for Windows**를 설치하고 `git`이 PATH에 있는지 확인하세요. - PowerShell을 닫았다가 다시 연 뒤 설치 프로그램을 다시 실행하세요. **2) 설치 후 openclaw is not recognized** - npm 전역 bin 폴더가 PATH에 없습니다. - - 경로를 확인하세요. + - 경로를 확인하세요: ```powershell npm config get prefix ``` - - 해당 디렉터리를 사용자 PATH에 추가하세요(Windows에서는 `\bin` 접미사가 필요하지 않으며, 대부분의 시스템에서는 `%AppData%\npm`입니다). - - PATH를 업데이트한 후 PowerShell을 닫았다가 다시 여세요. + - 그 디렉터리를 사용자 PATH에 추가하세요(Windows에서는 `\bin` 접미사가 필요하지 않으며, 대부분의 시스템에서는 `%AppData%\npm`입니다). + - PATH를 업데이트한 뒤 PowerShell을 닫았다가 다시 여세요. 가장 매끄러운 Windows 설정을 원한다면 네이티브 Windows 대신 **WSL2**를 사용하세요. 문서: [Windows](/ko/platforms/windows). - - 이는 보통 네이티브 Windows 셸에서 콘솔 코드 페이지가 맞지 않아서 발생합니다. + + 이는 보통 네이티브 Windows 셸의 콘솔 코드 페이지 불일치 문제입니다. 증상: - - `system.run`/`exec` 출력에서 중국어가 mojibake로 표시됨 + - `system.run`/`exec` 출력에서 중국어가 깨져 보임 - 같은 명령이 다른 터미널 프로필에서는 정상적으로 보임 PowerShell에서의 빠른 해결 방법: @@ -473,21 +475,21 @@ x-i18n: $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - 그런 다음 Gateway를 다시 시작하고 명령을 다시 시도하세요. + 그런 다음 Gateway를 다시 시작하고 명령을 다시 시도하세요: ```powershell openclaw gateway restart ``` - 최신 OpenClaw에서도 이 문제가 계속 재현된다면 다음에서 추적/신고하세요. + 최신 OpenClaw에서도 여전히 재현된다면 다음에서 추적/신고하세요: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - **해킹 가능한(git) 설치**를 사용해 전체 소스와 문서를 로컬에 둔 다음, - _그 폴더에서_ 봇(또는 Claude/Codex)에게 물어보세요. 그러면 저장소를 읽고 정확하게 답할 수 있습니다. + + **hackable (git) 설치**를 사용해 전체 소스와 문서를 로컬에 둔 다음, + 그 **폴더에서** 봇(또는 Claude/Codex)에게 물어보세요. 그러면 리포지토리를 읽고 정확하게 답할 수 있습니다. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -497,8 +499,8 @@ x-i18n: - - 짧은 답: Linux 가이드를 따른 뒤 온보딩을 실행하세요. + + 짧은 답변: Linux 가이드를 따른 뒤 온보딩을 실행하세요. - Linux 빠른 경로 + 서비스 설치: [Linux](/ko/platforms/linux). - 전체 안내: [시작하기](/ko/start/getting-started). @@ -506,39 +508,39 @@ x-i18n: - - 어떤 Linux VPS든 사용할 수 있습니다. 서버에 설치한 뒤 SSH/Tailscale로 Gateway에 접속하세요. + + 어떤 Linux VPS든 사용할 수 있습니다. 서버에 설치한 뒤 SSH/Tailscale로 Gateway에 접근하세요. 가이드: [exe.dev](/ko/install/exe-dev), [Hetzner](/ko/install/hetzner), [Fly.io](/ko/install/fly). - 원격 액세스: [Gateway remote](/ko/gateway/remote). + 원격 액세스: [Gateway 원격](/ko/gateway/remote). - 일반적인 제공자를 모아 둔 **호스팅 허브**가 있습니다. 하나를 선택해 가이드를 따르세요. + 일반적인 제공업체를 모아둔 **호스팅 허브**가 있습니다. 하나를 골라 가이드를 따르세요: - - [VPS 호스팅](/ko/vps) (모든 제공자를 한곳에 모음) + - [VPS 호스팅](/ko/vps) (모든 제공업체를 한곳에 모음) - [Fly.io](/ko/install/fly) - [Hetzner](/ko/install/hetzner) - [exe.dev](/ko/install/exe-dev) - 클라우드에서의 동작 방식: **Gateway는 서버에서 실행**되고, 노트북/휴대폰에서 - Control UI(또는 Tailscale/SSH)를 통해 접속합니다. state와 workspace는 - 서버에 있으므로 호스트를 source of truth로 취급하고 백업하세요. + 클라우드에서의 동작 방식: **Gateway는 서버에서 실행**되고, 사용자는 + 노트북/휴대폰에서 Control UI(또는 Tailscale/SSH)를 통해 접근합니다. state + workspace는 + 서버에 있으므로, 호스트를 단일 진실 공급원으로 취급하고 백업하세요. - **Node**(Mac/iOS/Android/headless)를 해당 클라우드 Gateway와 페어링하면 - Gateway는 클라우드에 유지하면서도 로컬 화면/카메라/canvas에 접근하거나 + **nodes**(Mac/iOS/Android/headless)를 이 클라우드 Gateway와 페어링해 + 로컬 화면/카메라/canvas에 접근하거나, Gateway는 클라우드에 두면서 노트북에서 명령을 실행할 수 있습니다. - 허브: [플랫폼](/ko/platforms). 원격 액세스: [Gateway remote](/ko/gateway/remote). + 허브: [플랫폼](/ko/platforms). 원격 액세스: [Gateway 원격](/ko/gateway/remote). Nodes: [Nodes](/ko/nodes), [Nodes CLI](/cli/nodes). - - 짧은 답: **가능하지만 권장하지 않습니다**. 업데이트 과정에서 - Gateway가 다시 시작될 수 있어(활성 세션이 끊김), 깨끗한 git checkout이 필요할 수 있으며, - 확인 프롬프트가 표시될 수 있습니다. 더 안전한 방법은 운영자가 셸에서 업데이트를 실행하는 것입니다. + + 짧은 답변: **가능은 하지만, 권장하지 않습니다**. 업데이트 과정에서 + Gateway가 재시작될 수 있고(활성 세션이 끊김), 깨끗한 git checkout이 필요할 수 있으며, + 확인 프롬프트가 뜰 수 있습니다. 더 안전한 방법은 운영자가 셸에서 업데이트를 실행하는 것입니다. CLI 사용: @@ -550,7 +552,7 @@ x-i18n: openclaw update --no-restart ``` - 반드시 에이전트에서 자동화해야 한다면: + 꼭 agent에서 자동화해야 한다면: ```bash openclaw update --yes --no-restart @@ -562,36 +564,37 @@ x-i18n: - `openclaw onboard`는 권장되는 설정 경로입니다. **local mode**에서는 다음을 안내합니다. + `openclaw onboard`는 권장되는 설정 경로입니다. **local mode**에서는 다음을 안내합니다: - - **모델/인증 설정**(제공자 OAuth, API 키, Anthropic setup-token, LM Studio 같은 로컬 모델 옵션 포함) + - **Model/auth 설정**(provider OAuth, API 키, Anthropic setup-token, LM Studio 같은 로컬 모델 옵션 포함) - **Workspace** 위치 + bootstrap 파일 - **Gateway 설정**(bind/port/auth/tailscale) - - **채널**(WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage 및 QQ Bot 같은 번들 채널 Plugin) - - **데몬 설치**(macOS에서는 LaunchAgent, Linux/WSL2에서는 systemd user unit) + - **Channels**(WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, 그리고 QQ Bot 같은 번들 channel plugins) + - **데몬 설치**(macOS의 LaunchAgent, Linux/WSL2의 systemd user unit) - **상태 점검** 및 **Skills** 선택 - 또한 구성된 모델을 알 수 없거나 인증이 없으면 경고를 표시합니다. + 또한 구성한 모델을 알 수 없거나 인증이 누락된 경우 경고도 표시합니다. - - 아니요. OpenClaw는 **API 키**(Anthropic/OpenAI/기타) 또는 - 데이터가 기기에 머무는 **로컬 전용 모델**로 실행할 수 있습니다. 구독(Claude - Pro/Max 또는 OpenAI Codex)은 해당 제공자를 인증하는 선택적 방법입니다. + + 아니요. OpenClaw는 **API 키**(Anthropic/OpenAI/기타)로 실행하거나 + **로컬 전용 모델**을 사용해 데이터를 기기 안에만 머물게 할 수 있습니다. 구독(Claude + Pro/Max 또는 OpenAI Codex)은 해당 provider에 인증하는 선택적 방법일 뿐입니다. - OpenClaw에서 Anthropic 사용은 실질적으로 다음과 같이 나뉩니다. + OpenClaw에서 Anthropic을 사용할 때의 실질적인 구분은 다음과 같습니다: - - **Anthropic API key**: 일반 Anthropic API 과금 + - **Anthropic API 키**: 일반 Anthropic API 과금 - **OpenClaw에서 Claude CLI / Claude 구독 인증**: Anthropic 직원이 - 이 사용이 다시 허용된다고 알려 주었고, Anthropic이 새로운 정책을 발표하지 않는 한 - OpenClaw는 이 통합에서 `claude -p` 사용을 허용된 방식으로 간주합니다 + 이 사용 방식이 다시 허용된다고 알려 주었으며, Anthropic이 새로운 + 정책을 게시하지 않는 한 OpenClaw는 이 통합에서 `claude -p` + 사용을 허용된 것으로 간주합니다 - 오래 실행되는 gateway host에서는 Anthropic API 키가 여전히 더 + 장기간 실행되는 gateway 호스트의 경우, Anthropic API 키가 여전히 더 예측 가능한 설정입니다. OpenAI Codex OAuth는 OpenClaw 같은 외부 - 도구에 대해 명시적으로 지원됩니다. + 도구용으로 명시적으로 지원됩니다. - OpenClaw는 다음과 같은 다른 호스팅형 구독 스타일 옵션도 지원합니다. + OpenClaw는 그 밖에도 다음과 같은 다른 호스팅형 구독 스타일 옵션을 지원합니다: **Qwen Cloud Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**. @@ -605,19 +608,24 @@ x-i18n: 예. - Anthropic 직원이 OpenClaw 스타일의 Claude CLI 사용이 다시 허용된다고 알려 주었기 때문에, Anthropic이 새로운 정책을 발표하지 않는 한 OpenClaw는 이 통합에서 Claude 구독 인증과 `claude -p` 사용을 허용된 방식으로 취급합니다. 가장 예측 가능한 서버 측 설정을 원한다면 대신 Anthropic API 키를 사용하세요. + Anthropic 직원이 OpenClaw 스타일의 Claude CLI 사용이 다시 허용된다고 알려 주었으므로, + Anthropic이 새로운 정책을 게시하지 않는 한 OpenClaw는 이 통합에서 Claude 구독 인증과 `claude -p` 사용을 + 허용된 것으로 간주합니다. 서버 측에서 가장 예측 가능한 설정을 원한다면 + 대신 Anthropic API 키를 사용하세요. 예. - Anthropic 직원이 이 사용이 다시 허용된다고 알려 주었기 때문에, Anthropic이 새로운 정책을 발표하지 않는 한 OpenClaw는 이 통합에서 Claude CLI 재사용과 `claude -p` 사용을 허용된 방식으로 취급합니다. + Anthropic 직원이 이 사용 방식이 다시 허용된다고 알려 주었으므로, OpenClaw는 + Anthropic이 새로운 정책을 게시하지 않는 한 이 통합에서 Claude CLI 재사용과 + `claude -p` 사용을 허용된 것으로 간주합니다. - Anthropic setup-token도 여전히 지원되는 OpenClaw 토큰 경로로 사용할 수 있지만, OpenClaw는 이제 가능할 때 Claude CLI 재사용과 `claude -p`를 더 우선합니다. - 프로덕션 또는 다중 사용자 워크로드에서는 Anthropic API 키 인증이 여전히 - 더 안전하고 예측 가능한 선택입니다. OpenClaw에서 다른 구독형 호스팅 - 옵션을 원한다면 [OpenAI](/ko/providers/openai), [Qwen / Model + Anthropic setup-token도 여전히 OpenClaw에서 지원되는 토큰 경로로 사용할 수 있지만, OpenClaw는 이제 가능할 때 Claude CLI 재사용과 `claude -p`를 우선합니다. + 프로덕션 또는 다중 사용자 워크로드의 경우, Anthropic API 키 인증이 여전히 + 더 안전하고 예측 가능한 선택입니다. OpenClaw에서 다른 구독형 호스팅 옵션을 원한다면 + [OpenAI](/ko/providers/openai), [Qwen / Model Cloud](/ko/providers/qwen), [MiniMax](/ko/providers/minimax), [GLM Models](/ko/providers/glm)를 참고하세요. @@ -625,67 +633,67 @@ x-i18n: -현재 윈도우에서 **Anthropic 할당량/속도 제한**이 소진되었다는 뜻입니다. **Claude CLI**를 -사용 중이라면 윈도우가 재설정될 때까지 기다리거나 요금제를 업그레이드하세요. **Anthropic API 키**를 -사용 중이라면 사용량/과금 현황을 Anthropic Console에서 확인하고 -필요하면 제한을 상향하세요. +현재 시간 창에서 **Anthropic 할당량/속도 제한**이 소진되었다는 뜻입니다. **Claude CLI**를 +사용 중이라면 시간 창이 재설정될 때까지 기다리거나 요금제를 업그레이드하세요. **Anthropic API 키**를 +사용 중이라면 Anthropic Console에서 +사용량/과금을 확인하고 필요에 따라 한도를 올리세요. 메시지가 구체적으로 다음과 같다면: - `Extra usage is required for long context requests`, 해당 요청은 - Anthropic의 1M context 베타(`context1m: true`)를 사용하려고 하는 것입니다. 이는 - 자격 증명이 장문맥 과금 대상일 때만 동작합니다(API 키 과금 또는 - Extra Usage가 활성화된 OpenClaw Claude-login 경로). + `Extra usage is required for long context requests`, 요청이 + Anthropic의 1M 컨텍스트 베타(`context1m: true`)를 사용하려는 것입니다. 이 기능은 + 자격 증명이 장문맥 과금 대상(API 키 과금 또는 + Extra Usage가 활성화된 OpenClaw Claude 로그인 경로)일 때만 작동합니다. - 팁: 제공자가 속도 제한에 걸렸을 때도 OpenClaw가 계속 응답할 수 있도록 **fallback model**을 설정하세요. - [모델](/cli/models), [OAuth](/ko/concepts/oauth), 그리고 + 팁: provider에 속도 제한이 걸려도 OpenClaw가 계속 응답할 수 있도록 **fallback model**을 설정하세요. + [Models](/cli/models), [OAuth](/ko/concepts/oauth), 그리고 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/ko/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)를 참고하세요. - 예. OpenClaw에는 번들된 **Amazon Bedrock (Converse)** 제공자가 있습니다. AWS 환경 마커가 있으면 OpenClaw는 스트리밍/텍스트 Bedrock 카탈로그를 자동으로 검색해 암시적 `amazon-bedrock` 제공자로 병합할 수 있습니다. 그렇지 않으면 `plugins.entries.amazon-bedrock.config.discovery.enabled`를 명시적으로 활성화하거나 수동 제공자 항목을 추가할 수 있습니다. [Amazon Bedrock](/ko/providers/bedrock) 및 [모델 제공자](/ko/providers/models)를 참고하세요. 관리형 키 흐름을 선호한다면 Bedrock 앞단에 OpenAI 호환 프록시를 두는 것도 여전히 유효한 옵션입니다. + 예. OpenClaw에는 번들된 **Amazon Bedrock (Converse)** provider가 있습니다. AWS env 마커가 존재하면 OpenClaw가 스트리밍/텍스트 Bedrock 카탈로그를 자동으로 검색하고 이를 암시적 `amazon-bedrock` provider로 병합할 수 있습니다. 그렇지 않으면 `plugins.entries.amazon-bedrock.config.discovery.enabled`를 명시적으로 활성화하거나 수동 provider 항목을 추가할 수 있습니다. [Amazon Bedrock](/ko/providers/bedrock) 및 [모델 provider](/ko/providers/models)를 참고하세요. 관리형 키 흐름을 선호한다면 Bedrock 앞단에 OpenAI 호환 프록시를 두는 것도 여전히 유효한 옵션입니다. - - OpenClaw는 OAuth(ChatGPT 로그인)를 통해 **OpenAI Code (Codex)**를 지원합니다. 온보딩에서 OAuth 흐름을 실행할 수 있으며, 적절한 경우 기본 모델을 `openai-codex/gpt-5.4`로 설정합니다. [모델 제공자](/ko/concepts/model-providers)와 [온보딩(CLI)](/ko/start/wizard)를 참고하세요. + + OpenClaw는 OAuth(ChatGPT 로그인)를 통해 **OpenAI Code (Codex)**를 지원합니다. 온보딩은 OAuth 흐름을 실행할 수 있으며, 적절한 경우 기본 모델을 `openai-codex/gpt-5.4`로 설정합니다. [모델 provider](/ko/concepts/model-providers) 및 [온보딩(CLI)](/ko/start/wizard)를 참고하세요. - - OpenClaw는 두 경로를 별도로 취급합니다. + + OpenClaw는 두 경로를 별도로 취급합니다: - `openai-codex/gpt-5.4` = ChatGPT/Codex OAuth - `openai/gpt-5.4` = 직접 OpenAI Platform API - OpenClaw에서 ChatGPT/Codex 로그인은 직접 `openai/*` 경로가 아니라 - `openai-codex/*` 경로에 연결됩니다. OpenClaw에서 직접 API 경로를 원하면 - `OPENAI_API_KEY`(또는 이에 해당하는 OpenAI provider config)를 설정하세요. - OpenClaw에서 ChatGPT/Codex 로그인을 원하면 `openai-codex/*`를 사용하세요. + OpenClaw에서는 ChatGPT/Codex 로그인은 직접적인 `openai/*` 경로가 아니라 + `openai-codex/*` 경로에 연결됩니다. OpenClaw에서 직접 API 경로를 원한다면 + `OPENAI_API_KEY`(또는 동등한 OpenAI provider 구성)를 설정하세요. + OpenClaw에서 ChatGPT/Codex 로그인을 원한다면 `openai-codex/*`를 사용하세요. - - `openai-codex/*`는 Codex OAuth 경로를 사용하며, 사용 가능한 할당량 윈도우는 - OpenAI가 관리하고 요금제에 따라 달라집니다. 실제로는 둘 다 같은 계정에 연결되어 있어도, - 이러한 제한은 ChatGPT 웹사이트/앱 경험과 다를 수 있습니다. + + `openai-codex/*`는 Codex OAuth 경로를 사용하며, 사용 가능한 할당량 시간 창은 + OpenAI가 관리하고 요금제에 따라 달라집니다. 실제로는 두 경로가 같은 계정에 + 연결되어 있어도, 그 한도는 ChatGPT 웹사이트/앱 경험과 다를 수 있습니다. - OpenClaw는 현재 확인 가능한 provider 사용량/할당량 윈도우를 + OpenClaw는 현재 보이는 provider 사용량/할당량 시간 창을 `openclaw models status`에서 보여줄 수 있지만, ChatGPT 웹의 - 권한을 직접 API 액세스로 임의 생성하거나 정규화하지는 않습니다. 직접 OpenAI Platform - 과금/제한 경로를 원하면 API 키와 함께 `openai/*`를 사용하세요. + 권한을 직접 API 접근으로 임의 생성하거나 정규화하지는 않습니다. 직접 OpenAI Platform + 과금/한도 경로를 원한다면 API 키와 함께 `openai/*`를 사용하세요. 예. OpenClaw는 **OpenAI Code (Codex) 구독 OAuth**를 완전히 지원합니다. - OpenAI는 OpenClaw 같은 외부 도구/워크플로에서의 구독 OAuth 사용을 - 명시적으로 허용합니다. 온보딩에서 이 OAuth 흐름을 실행할 수 있습니다. + OpenAI는 OpenClaw 같은 외부 도구/워크플로에서 구독 OAuth 사용을 + 명시적으로 허용합니다. 온보딩이 이 OAuth 흐름을 대신 실행할 수도 있습니다. - [OAuth](/ko/concepts/oauth), [모델 제공자](/ko/concepts/model-providers), [온보딩(CLI)](/ko/start/wizard)를 참고하세요. + [OAuth](/ko/concepts/oauth), [모델 provider](/ko/concepts/model-providers), [온보딩(CLI)](/ko/start/wizard)를 참고하세요. - Gemini CLI는 `openclaw.json`의 client id 또는 secret이 아니라 **Plugin 인증 흐름**을 사용합니다. + Gemini CLI는 `openclaw.json`의 client id나 secret이 아니라 **plugin 인증 흐름**을 사용합니다. 단계: @@ -695,81 +703,82 @@ x-i18n: 2. Plugin을 활성화합니다: `openclaw plugins enable google` 3. 로그인합니다: `openclaw models auth login --provider google-gemini-cli --set-default` 4. 로그인 후 기본 모델: `google-gemini-cli/gemini-3-flash-preview` - 5. 요청이 실패하면 gateway host에 `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_CLOUD_PROJECT_ID`를 설정합니다 + 5. 요청이 실패하면 gateway 호스트에 `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_CLOUD_PROJECT_ID`를 설정하세요 - 이렇게 하면 OAuth 토큰이 gateway host의 auth 프로필에 저장됩니다. 자세한 내용은 [모델 제공자](/ko/concepts/model-providers)를 참고하세요. + 이 과정은 OAuth 토큰을 gateway 호스트의 auth profile에 저장합니다. 자세한 내용: [모델 provider](/ko/concepts/model-providers). - - 보통은 아닙니다. OpenClaw는 긴 컨텍스트와 강한 안전성이 필요하므로, 작은 카드에서는 잘리고 누수가 생깁니다. 꼭 써야 한다면 로컬에서 가능한 한 **가장 큰** 모델 빌드(LM Studio)를 실행하고 [/gateway/local-models](/ko/gateway/local-models)를 참고하세요. 더 작은/양자화된 모델은 prompt injection 위험을 높입니다. [보안](/ko/gateway/security)을 참고하세요. + + 보통은 아니요. OpenClaw는 큰 컨텍스트와 강한 안전성이 필요합니다. 작은 카드에서는 잘리고 누출됩니다. 꼭 써야 한다면 로컬에서 실행 가능한 **가장 큰** 모델 빌드(LM Studio)를 사용하고 [/gateway/local-models](/ko/gateway/local-models)를 참고하세요. 더 작거나 양자화된 모델은 프롬프트 인젝션 위험을 높입니다. [보안](/ko/gateway/security)을 참고하세요. - 리전이 고정된 엔드포인트를 선택하세요. OpenRouter는 MiniMax, Kimi, GLM에 대해 미국 호스팅 옵션을 제공하므로, 데이터를 해당 리전에 유지하려면 미국 호스팅 변형을 선택하세요. `models.mode: "merge"`를 사용하면 선택한 리전 제공자를 유지하면서 Anthropic/OpenAI도 함께 나열해 fallback을 사용할 수 있습니다. + 리전 고정 엔드포인트를 선택하세요. OpenRouter는 MiniMax, Kimi, GLM에 대해 미국 호스팅 옵션을 제공하므로, 데이터를 해당 리전에 유지하려면 미국 호스팅 변형을 선택하세요. `models.mode: "merge"`를 사용하면 선택한 리전 provider를 존중하면서도 fallback이 가능하도록 Anthropic/OpenAI를 함께 나열할 수 있습니다. - 아니요. OpenClaw는 macOS 또는 Linux에서 실행되며(Windows는 WSL2를 통해 가능), Mac mini는 선택 사항입니다. 일부 사용자는 항상 켜져 있는 호스트로 Mac mini를 구매하지만, 작은 VPS, 홈 서버 또는 Raspberry Pi급 장치로도 충분히 가능합니다. + 아니요. OpenClaw는 macOS 또는 Linux에서 실행되며(Windows는 WSL2를 통해 지원) Mac mini는 선택 사항입니다. 일부 사용자는 + 항상 켜져 있는 호스트로 쓰기 위해 구입하지만, 작은 VPS, 홈 서버 또는 Raspberry Pi급 장치도 잘 작동합니다. - Mac이 필요한 경우는 **macOS 전용 도구**를 쓸 때뿐입니다. iMessage는 [BlueBubbles](/ko/channels/bluebubbles)를 사용하세요(권장). BlueBubbles 서버는 어떤 Mac에서든 실행할 수 있고, Gateway는 Linux나 다른 곳에서 실행할 수 있습니다. 다른 macOS 전용 도구를 쓰고 싶다면 Gateway를 Mac에서 실행하거나 macOS node를 페어링하세요. + **macOS 전용 도구**를 쓰는 경우에만 Mac이 필요합니다. iMessage에는 [BlueBubbles](/ko/channels/bluebubbles)를 사용하세요(권장). BlueBubbles 서버는 어떤 Mac에서도 실행할 수 있고, Gateway는 Linux나 다른 곳에서 실행될 수 있습니다. 다른 macOS 전용 도구를 사용하려면 Mac에서 Gateway를 실행하거나 macOS Node를 페어링하세요. - 문서: [BlueBubbles](/ko/channels/bluebubbles), [Nodes](/ko/nodes), [Mac remote mode](/ko/platforms/mac/remote). + 문서: [BlueBubbles](/ko/channels/bluebubbles), [Nodes](/ko/nodes), [Mac 원격 모드](/ko/platforms/mac/remote). - - Messages에 로그인된 **어떤 macOS 기기든** 필요합니다. 반드시 Mac mini일 필요는 없으며, - 어떤 Mac이든 가능합니다. iMessage에는 **[BlueBubbles](/ko/channels/bluebubbles)** 사용을 권장합니다. BlueBubbles 서버는 macOS에서 실행되고, Gateway는 Linux나 다른 곳에서 실행할 수 있습니다. + + Messages에 로그인된 **어떤 macOS 기기든** 필요합니다. 반드시 Mac mini일 필요는 없습니다. + iMessage에는 [BlueBubbles](/ko/channels/bluebubbles)를 사용하세요(권장). BlueBubbles 서버는 macOS에서 실행되고, Gateway는 Linux나 다른 곳에서 실행될 수 있습니다. - 일반적인 설정: + 일반적인 구성: - Gateway는 Linux/VPS에서 실행하고, BlueBubbles 서버는 Messages에 로그인된 아무 Mac에서나 실행합니다. - 가장 단순한 단일 머신 구성을 원한다면 모든 것을 Mac에서 실행합니다. 문서: [BlueBubbles](/ko/channels/bluebubbles), [Nodes](/ko/nodes), - [Mac remote mode](/ko/platforms/mac/remote). + [Mac 원격 모드](/ko/platforms/mac/remote). - + 예. **Mac mini는 Gateway를 실행**할 수 있고, MacBook Pro는 - **Node**(동반 기기)로 연결할 수 있습니다. Node는 Gateway를 실행하지 않고, - 해당 기기에서 screen/camera/canvas와 `system.run` 같은 추가 기능을 제공합니다. + **Node**(보조 기기)로 연결할 수 있습니다. Nodes는 Gateway를 실행하지 않고, + 해당 기기에서 화면/카메라/canvas 및 `system.run` 같은 추가 기능을 제공합니다. 일반적인 패턴: - - Gateway는 Mac mini에서 실행(항상 켜져 있음). - - MacBook Pro는 macOS 앱 또는 node host를 실행하고 Gateway와 페어링합니다. - - 확인은 `openclaw nodes status` / `openclaw nodes list`를 사용하세요. + - Gateway는 Mac mini에서 실행(항상 켜짐). + - MacBook Pro는 macOS 앱 또는 node 호스트를 실행하고 Gateway와 페어링합니다. + - 이를 확인하려면 `openclaw nodes status` / `openclaw nodes list`를 사용하세요. 문서: [Nodes](/ko/nodes), [Nodes CLI](/cli/nodes). - Bun은 **권장하지 않습니다**. 특히 WhatsApp과 Telegram에서 런타임 버그가 확인됩니다. - 안정적인 gateway에는 **Node**를 사용하세요. + Bun은 **권장되지 않습니다**. 특히 WhatsApp과 Telegram에서 런타임 버그가 관찰됩니다. + 안정적인 Gateway를 위해서는 **Node**를 사용하세요. - 그래도 Bun을 실험해 보고 싶다면 WhatsApp/Telegram 없이 + 그래도 Bun으로 실험해 보고 싶다면 WhatsApp/Telegram 없이 비프로덕션 gateway에서만 사용하세요. - - `channels.telegram.allowFrom`에는 **사람 발신자의 Telegram 사용자 ID**(숫자)가 들어갑니다. 봇 사용자명이 아닙니다. + + `channels.telegram.allowFrom`은 **사람 발신자의 Telegram 사용자 ID**(숫자)입니다. 봇 사용자명이 아닙니다. - 온보딩에서는 `@username` 입력을 받아 숫자 ID로 해석하지만, OpenClaw 인증은 숫자 ID만 사용합니다. + 설정에서는 숫자 사용자 ID만 받습니다. 이미 config에 레거시 `@username` 항목이 있다면, `openclaw doctor --fix`가 이를 해결하려고 시도할 수 있습니다. 더 안전한 방법(서드파티 봇 없음): - - 봇에 DM을 보낸 다음 `openclaw logs --follow`를 실행하고 `from.id`를 확인하세요. + - 봇에게 DM을 보낸 다음 `openclaw logs --follow`를 실행하고 `from.id`를 확인하세요. 공식 Bot API: - - 봇에 DM을 보낸 다음 `https://api.telegram.org/bot/getUpdates`를 호출하고 `message.from.id`를 확인하세요. + - 봇에게 DM을 보낸 다음 `https://api.telegram.org/bot/getUpdates`를 호출하고 `message.from.id`를 확인하세요. - 서드파티(개인정보 보호 측면에서 덜 바람직함): + 서드파티(프라이버시 측면에서 덜 안전함): - `@userinfobot` 또는 `@getidsbot`에 DM을 보내세요. @@ -778,14 +787,14 @@ x-i18n: - 예. **멀티 에이전트 라우팅**을 통해 가능합니다. 각 발신자의 WhatsApp **DM**(peer `kind: "direct"`, 발신자 E.164 형식 예: `+15551234567`)을 서로 다른 `agentId`에 바인딩하면, 각 사용자는 자신만의 workspace와 세션 저장소를 가지게 됩니다. 답장은 여전히 **같은 WhatsApp 계정**에서 오며, DM 접근 제어(`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`)는 WhatsApp 계정 단위로 전역 적용됩니다. [멀티 에이전트 라우팅](/ko/concepts/multi-agent)과 [WhatsApp](/ko/channels/whatsapp)을 참고하세요. + 예. **멀티 에이전트 라우팅**을 통해 가능합니다. 각 발신자의 WhatsApp **DM**(peer `kind: "direct"`, 발신자 E.164 형식 `+15551234567`)을 서로 다른 `agentId`에 바인딩하면, 각 사람은 자신만의 workspace와 session 저장소를 갖게 됩니다. 응답은 여전히 **같은 WhatsApp 계정**에서 오며, DM 액세스 제어(`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`)는 WhatsApp 계정 단위로 전역 적용됩니다. [멀티 에이전트 라우팅](/ko/concepts/multi-agent) 및 [WhatsApp](/ko/channels/whatsapp)을 참고하세요. - - 예. 멀티 에이전트 라우팅을 사용하세요. 각 에이전트에 고유한 기본 모델을 지정한 다음, 각 에이전트에 들어오는 경로(provider account 또는 특정 peer)를 바인딩하세요. 예시 구성은 [멀티 에이전트 라우팅](/ko/concepts/multi-agent)에 있습니다. [모델](/ko/concepts/models)과 [구성](/ko/gateway/configuration)도 참고하세요. + + 예. 멀티 에이전트 라우팅을 사용하세요. 각 agent에 자체 기본 모델을 지정한 다음, 인바운드 경로(provider 계정 또는 특정 peer)를 각 agent에 바인딩하면 됩니다. 예시 구성은 [멀티 에이전트 라우팅](/ko/concepts/multi-agent)에 있습니다. [모델](/ko/concepts/models) 및 [구성](/ko/gateway/configuration)도 참고하세요. - + 예. Homebrew는 Linux(Linuxbrew)를 지원합니다. 빠른 설정: ```bash @@ -795,25 +804,25 @@ x-i18n: brew install ``` - OpenClaw를 systemd로 실행하는 경우, 서비스 PATH에 `/home/linuxbrew/.linuxbrew/bin`(또는 brew prefix)이 포함되어 비로그인 셸에서도 `brew`로 설치한 도구를 찾을 수 있게 하세요. - 최근 빌드는 Linux systemd 서비스에서 일반적인 사용자 bin 디렉터리(예: `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`)도 앞에 추가하며, 설정되어 있으면 `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, `FNM_DIR`도 반영합니다. + systemd를 통해 OpenClaw를 실행한다면, 로그인 셸이 아닌 환경에서도 `brew`로 설치한 도구를 찾을 수 있도록 서비스 PATH에 `/home/linuxbrew/.linuxbrew/bin`(또는 brew prefix)을 포함하세요. + 최근 빌드는 Linux systemd 서비스에서 일반적인 사용자 bin 디렉터리(예: `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`)도 앞에 추가하며, 설정된 경우 `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, `FNM_DIR`도 반영합니다. - - - **해킹 가능한(git) 설치:** 전체 소스 체크아웃, 수정 가능, 기여자에게 가장 적합합니다. - 로컬에서 빌드를 실행하고 코드/문서를 수정할 수 있습니다. - - **npm install:** 전역 CLI 설치, 저장소 없음, “그냥 실행”하기에 가장 적합합니다. - 업데이트는 npm dist-tag에서 제공됩니다. + + - **Hackable (git) 설치:** 전체 소스 체크아웃, 편집 가능, 기여자에게 가장 적합합니다. + 빌드를 로컬에서 실행하며 코드/문서를 직접 수정할 수 있습니다. + - **npm install:** 전역 CLI 설치, 리포지토리 없음, “그냥 실행”하려는 경우에 가장 적합합니다. + 업데이트는 npm dist-tag에서 가져옵니다. 문서: [시작하기](/ko/start/getting-started), [업데이트](/ko/install/updating). - + 예. 다른 방식으로 설치한 다음 Doctor를 실행해 gateway 서비스가 새 진입점을 가리키도록 하세요. - 이렇게 해도 **데이터는 삭제되지 않습니다**. 변경되는 것은 OpenClaw 코드 설치뿐입니다. 상태 - (`~/.openclaw`)와 workspace(`~/.openclaw/workspace`)는 그대로 유지됩니다. + 이렇게 해도 **데이터는 삭제되지 않습니다**. 바뀌는 것은 OpenClaw 코드 설치뿐입니다. state + (`~/.openclaw`)와 workspace (`~/.openclaw/workspace`)는 그대로 유지됩니다. npm에서 git으로: @@ -834,67 +843,67 @@ x-i18n: openclaw gateway restart ``` - Doctor는 gateway 서비스 진입점 불일치를 감지하고 현재 설치에 맞게 서비스 구성을 다시 쓰도록 제안합니다(자동화에서는 `--repair` 사용). + Doctor는 gateway 서비스 진입점 불일치를 감지하고 현재 설치에 맞도록 서비스 구성을 다시 쓰도록 제안합니다(자동화에서는 `--repair` 사용). - 백업 팁: [백업 전략](#디스크에서-파일이-저장되는-위치)을 참고하세요. + 백업 팁: [백업 전략](#디스크에서-파일-위치)을 참고하세요. - - 짧은 답: **24/7 신뢰성이 필요하면 VPS를 사용하세요**. 가장 적은 마찰을 원하고 절전/재시작이 괜찮다면 로컬에서 실행하세요. + + 짧은 답변: **24/7 안정성이 필요하다면 VPS를 사용하세요**. 가장 적은 마찰을 원하고 절전/재시작이 괜찮다면 로컬에서 실행하세요. **노트북(로컬 Gateway)** - **장점:** 서버 비용 없음, 로컬 파일에 직접 접근 가능, 실시간 브라우저 창 사용 가능. - - **단점:** 절전/네트워크 끊김 = 연결 끊김, OS 업데이트/재부팅으로 중단됨, 깨어 있어야 함. + - **단점:** 절전/네트워크 끊김 = 연결 해제, OS 업데이트/재부팅으로 중단, 계속 깨어 있어야 함. **VPS / 클라우드** - - **장점:** 항상 켜짐, 안정적인 네트워크, 노트북 절전 문제 없음, 계속 실행 상태를 유지하기 쉬움. - - **단점:** 대개 헤드리스로 실행됨(스크린샷 사용), 원격 파일 접근만 가능, 업데이트하려면 SSH가 필요함. + - **장점:** 항상 켜짐, 안정적인 네트워크, 노트북 절전 문제 없음, 계속 실행 상태 유지가 쉬움. + - **단점:** 대개 headless로 실행됨(스크린샷 사용), 원격 파일 접근만 가능, 업데이트하려면 SSH 필요. - **OpenClaw 관련 참고:** WhatsApp/Telegram/Slack/Mattermost/Discord는 모두 VPS에서 잘 동작합니다. 실제 트레이드오프는 **헤드리스 브라우저**와 가시적인 창의 차이뿐입니다. [브라우저](/ko/tools/browser)를 참고하세요. + **OpenClaw 관련 참고:** WhatsApp/Telegram/Slack/Mattermost/Discord는 모두 VPS에서 잘 작동합니다. 실제 차이는 **headless 브라우저**인지 눈에 보이는 브라우저 창인지 정도입니다. [Browser](/ko/tools/browser)를 참고하세요. - **권장 기본값:** 이전에 gateway 연결 끊김을 겪었다면 VPS를 권장합니다. Mac을 적극적으로 사용 중이고 로컬 파일 접근이나 가시적인 브라우저가 있는 UI 자동화를 원할 때는 로컬도 매우 좋습니다. + **권장 기본값:** 이전에 gateway 연결 끊김을 겪었다면 VPS를 권장합니다. Mac을 적극적으로 사용 중이고 로컬 파일 접근이나 눈에 보이는 브라우저를 통한 UI 자동화가 필요할 때는 로컬이 아주 좋습니다. - - 필수는 아니지만, **신뢰성과 격리 측면에서 권장**됩니다. + + 필수는 아니지만, **안정성과 격리 측면에서 권장**됩니다. - - **전용 호스트(VPS/Mac mini/Pi):** 항상 켜짐, 절전/재부팅 중단이 적음, 권한이 더 깔끔함, 계속 실행 상태를 유지하기 쉬움. - - **공유 노트북/데스크톱:** 테스트와 적극적인 사용에는 전혀 문제없지만, 머신이 절전 상태에 들어가거나 업데이트할 때 일시 중단이 생길 수 있습니다. + - **전용 호스트(VPS/Mac mini/Pi):** 항상 켜짐, 절전/재부팅 중단이 적음, 권한이 더 깔끔함, 계속 실행 상태 유지가 쉬움. + - **공용 노트북/데스크톱:** 테스트와 적극적인 사용에는 전혀 문제없지만, 기기가 절전 모드에 들어가거나 업데이트되면 일시 중지가 생길 수 있습니다. - 두 장점을 모두 원한다면 Gateway는 전용 호스트에 두고, 노트북은 로컬 screen/camera/exec 도구용 **Node**로 페어링하세요. [Nodes](/ko/nodes)를 참고하세요. + 두 세계의 장점을 모두 원한다면 Gateway는 전용 호스트에 두고, 노트북은 로컬 화면/카메라/exec 도구용 **Node**로 페어링하세요. [Nodes](/ko/nodes)를 참고하세요. 보안 지침은 [보안](/ko/gateway/security)을 읽어보세요. - OpenClaw는 가볍습니다. 기본 Gateway + 하나의 채팅 채널 기준: + OpenClaw는 가볍습니다. 기본 Gateway + 하나의 채팅 channel 기준: - - **절대 최소 사양:** 1 vCPU, 1GB RAM, 약 500MB 디스크. - - **권장 사양:** 여유 공간(로그, 미디어, 여러 채널)을 위해 1-2 vCPU, 2GB RAM 이상. Node 도구와 브라우저 자동화는 리소스를 많이 사용할 수 있습니다. + - **절대 최소:** 1 vCPU, 1GB RAM, 약 500MB 디스크. + - **권장:** 여유 공간(로그, 미디어, 여러 channels)을 위해 1-2 vCPU, 2GB RAM 이상. Node 도구와 브라우저 자동화는 리소스를 많이 사용할 수 있습니다. - OS는 **Ubuntu LTS**(또는 최신 Debian/Ubuntu 계열)를 사용하세요. Linux 설치 경로는 해당 환경에서 가장 잘 테스트되어 있습니다. + OS: **Ubuntu LTS**(또는 최신 Debian/Ubuntu 계열)를 사용하세요. Linux 설치 경로는 이 환경에서 가장 잘 검증되어 있습니다. 문서: [Linux](/ko/platforms/linux), [VPS 호스팅](/ko/vps). - 예. VM은 VPS와 동일하게 취급하세요. 항상 켜져 있어야 하고, 접근 가능해야 하며, - Gateway와 활성화한 채널을 실행할 수 있을 만큼 충분한 RAM이 필요합니다. + 예. VM도 VPS와 동일하게 취급하세요. 항상 켜져 있어야 하고, 접근 가능해야 하며, + Gateway와 활성화한 channels를 실행할 충분한 RAM이 필요합니다. - 기본 지침: + 기본 가이드: - - **절대 최소 사양:** 1 vCPU, 1GB RAM. - - **권장 사양:** 여러 채널, 브라우저 자동화 또는 미디어 도구를 실행한다면 2GB RAM 이상. - - **OS:** Ubuntu LTS 또는 다른 최신 Debian/Ubuntu 계열. + - **절대 최소:** 1 vCPU, 1GB RAM. + - **권장:** 여러 channels, 브라우저 자동화 또는 미디어 도구를 실행한다면 2GB RAM 이상. + - **OS:** Ubuntu LTS 또는 기타 최신 Debian/Ubuntu. Windows를 사용 중이라면 **WSL2가 가장 쉬운 VM 스타일 설정**이며 도구 호환성도 가장 좋습니다. [Windows](/ko/platforms/windows), [VPS 호스팅](/ko/vps)을 참고하세요. - VM에서 macOS를 실행 중이라면 [macOS VM](/ko/install/macos-vm)을 참고하세요. + macOS를 VM에서 실행 중이라면 [macOS VM](/ko/install/macos-vm)을 참고하세요. @@ -902,81 +911,81 @@ x-i18n: ## OpenClaw란 무엇인가요? - - OpenClaw는 자신의 기기에서 실행하는 개인용 AI 어시스턴트입니다. 이미 사용 중인 메시징 표면(WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, 그리고 QQ Bot 같은 번들 채널 Plugin)에서 응답하며, 지원되는 플랫폼에서는 음성과 라이브 Canvas도 사용할 수 있습니다. **Gateway**는 항상 켜져 있는 컨트롤 플레인이며, 어시스턴트가 곧 제품입니다. + + OpenClaw는 사용자가 자신의 기기에서 실행하는 개인용 AI assistant입니다. 이미 사용 중인 메시징 표면(WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, 그리고 QQ Bot 같은 번들 channel plugins)에서 응답하며, 지원되는 플랫폼에서는 음성과 라이브 Canvas도 사용할 수 있습니다. **Gateway**는 항상 켜져 있는 컨트롤 플레인이며, assistant가 제품 그 자체입니다. - OpenClaw는 단순한 "Claude 래퍼"가 아닙니다. **로컬 우선 컨트롤 플레인**으로서, 이미 사용 중인 채팅 앱을 통해 접근 가능한 - 유능한 어시스턴트를 **자신의 하드웨어에서 직접** 실행할 수 있게 해 주며, - 상태를 유지하는 세션, 메모리, 도구를 제공하면서도 워크플로 제어를 호스팅된 - SaaS에 넘기지 않게 합니다. + OpenClaw는 "그냥 Claude wrapper"가 아닙니다. 이것은 **로컬 우선 컨트롤 플레인**으로, + 기존 채팅 앱을 통해 접근할 수 있는 유능한 assistant를 **자신의 하드웨어에서** + stateful sessions, memory, tools와 함께 실행할 수 있게 해 주며, + 워크플로 제어권을 호스팅된 SaaS에 넘기지 않아도 됩니다. 주요 특징: - **내 기기, 내 데이터:** 원하는 곳(Mac, Linux, VPS)에서 Gateway를 실행하고 - workspace + 세션 기록을 로컬에 유지 - - **웹 샌드박스가 아닌 실제 채널:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 등, - 지원되는 플랫폼의 모바일 음성 및 Canvas 포함 - - **모델에 종속되지 않음:** Anthropic, OpenAI, MiniMax, OpenRouter 등을 에이전트별 라우팅 - 및 페일오버와 함께 사용 가능 - - **로컬 전용 옵션:** 원한다면 로컬 모델을 실행해 **모든 데이터를 기기에만 유지** 가능 - - **멀티 에이전트 라우팅:** 채널, 계정, 작업별로 에이전트를 분리하고 각각 고유한 - workspace와 기본값 보유 - - **오픈 소스 및 해킹 가능:** 벤더 종속 없이 검사, 확장, self-host 가능 + workspace + session 기록을 로컬에 유지할 수 있습니다. + - **웹 샌드박스가 아닌 실제 channels:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 등, + 그리고 지원되는 플랫폼의 모바일 음성 및 Canvas. + - **모델 비종속:** Anthropic, OpenAI, MiniMax, OpenRouter 등을 사용하고, agent별 라우팅 + 및 장애 조치를 구성할 수 있습니다. + - **로컬 전용 옵션:** 원한다면 로컬 모델을 실행해 **모든 데이터를 기기에만 남겨둘 수 있습니다**. + - **멀티 에이전트 라우팅:** channel, 계정 또는 작업별로 별도의 agents를 두고, 각자 + workspace와 기본값을 가질 수 있습니다. + - **오픈 소스와 해킹 가능성:** 공급업체 종속 없이 살펴보고, 확장하고, 직접 호스팅할 수 있습니다. - 문서: [Gateway](/ko/gateway), [채널](/ko/channels), [멀티 에이전트](/ko/concepts/multi-agent), - [메모리](/ko/concepts/memory). + 문서: [Gateway](/ko/gateway), [Channels](/ko/channels), [멀티 에이전트](/ko/concepts/multi-agent), + [Memory](/ko/concepts/memory). - - 좋은 첫 프로젝트 예시: + + 처음 시도해 보기 좋은 작업: - 웹사이트 만들기(WordPress, Shopify 또는 간단한 정적 사이트). - 모바일 앱 프로토타입 만들기(개요, 화면, API 계획). - - 파일과 폴더 정리하기(정리, 이름 지정, 태깅). - - Gmail을 연결하고 요약 또는 후속 조치 자동화하기. + - 파일과 폴더 정리하기(정리, 이름 규칙, 태깅). + - Gmail을 연결해 요약이나 후속 작업 자동화하기. 큰 작업도 처리할 수 있지만, 단계로 나누고 - 병렬 작업에는 하위 에이전트를 사용할 때 가장 잘 작동합니다. + 병렬 작업에 sub agents를 사용하면 가장 잘 작동합니다. - 일상적인 성과는 보통 다음과 같습니다. + 일상적인 활용은 보통 다음과 같습니다: - **개인 브리핑:** 받은편지함, 캘린더, 관심 있는 뉴스 요약. - - **조사 및 초안 작성:** 이메일이나 문서를 위한 빠른 조사, 요약, 초안 작성. - - **리마인더 및 후속 조치:** Cron 또는 Heartbeat 기반 알림과 체크리스트. - - **브라우저 자동화:** 양식 작성, 데이터 수집, 반복적인 웹 작업. - - **기기 간 조정:** 휴대폰에서 작업을 보내고, Gateway가 서버에서 실행한 뒤, 결과를 채팅으로 돌려받기. + - **리서치와 초안 작성:** 빠른 조사, 요약, 이메일 또는 문서의 첫 초안. + - **리마인더와 후속 작업:** cron 또는 heartbeat 기반 알림과 체크리스트. + - **브라우저 자동화:** 양식 입력, 데이터 수집, 반복적인 웹 작업. + - **기기 간 조정:** 휴대폰에서 작업을 보내고, Gateway가 서버에서 실행한 뒤, 결과를 채팅으로 다시 받기. - - **조사, 자격 판별, 초안 작성**에는 예. 사이트를 스캔하고, 짧은 목록을 만들고, - 잠재 고객을 요약하고, 아웃리치나 광고 문안 초안을 작성할 수 있습니다. + + **리서치, 적합성 평가, 초안 작성**에는 예입니다. 사이트를 스캔하고, 후보 목록을 만들고, + 잠재 고객을 요약하고, 아웃리치 또는 광고 문구 초안을 작성할 수 있습니다. - **아웃리치나 광고 집행**에서는 사람이 개입하도록 하세요. 스팸을 피하고, 현지 법률과 - 플랫폼 정책을 따르며, 발송 전에 반드시 검토하세요. 가장 안전한 패턴은 - OpenClaw가 초안을 만들고 사용자가 승인하는 방식입니다. + **아웃리치나 광고 실행**에는 사람이 검토하는 흐름을 유지하세요. 스팸을 피하고, 현지 법률과 + 플랫폼 정책을 따르며, 발송 전에 모든 내용을 검토하세요. 가장 안전한 패턴은 + OpenClaw가 초안을 만들고 사용자가 승인하는 것입니다. 문서: [보안](/ko/gateway/security). - - OpenClaw는 IDE 대체제가 아니라 **개인용 어시스턴트**이자 조정 계층입니다. 저장소 안에서 가장 빠른 직접 코딩 루프가 필요하다면 - Claude Code나 Codex를 사용하세요. 지속적인 메모리, 기기 간 접근, 도구 오케스트레이션이 필요하다면 OpenClaw를 사용하세요. + + OpenClaw는 IDE 대체제가 아니라 **개인 assistant**이자 조정 계층입니다. + 리포지토리 안에서 가장 빠른 직접 코딩 루프가 필요하다면 Claude Code나 Codex를 사용하세요. 지속적인 memory, 기기 간 접근, 도구 오케스트레이션이 필요하다면 OpenClaw를 사용하세요. 장점: - - 세션 전반에 걸친 **지속적인 메모리 + workspace** + - 세션 간 **지속적인 memory + workspace** - **멀티플랫폼 접근**(WhatsApp, Telegram, TUI, WebChat) - **도구 오케스트레이션**(브라우저, 파일, 스케줄링, hooks) - - **항상 켜진 Gateway**(VPS에서 실행하고 어디서나 상호작용) - - 로컬 브라우저/screen/camera/exec용 **Nodes** + - **항상 켜져 있는 Gateway**(VPS에서 실행하고 어디서든 상호작용) + - 로컬 브라우저/화면/카메라/exec용 **Nodes** 쇼케이스: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -986,69 +995,69 @@ x-i18n: ## Skills 및 자동화 - - 저장소 사본을 직접 수정하는 대신 관리되는 overrides를 사용하세요. 변경 사항은 `~/.openclaw/skills//SKILL.md`에 두거나(`~/.openclaw/openclaw.json`의 `skills.load.extraDirs`로 폴더 추가 가능) 관리하세요. 우선순위는 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs` 이므로, 관리되는 override는 git을 건드리지 않고도 번들 Skills보다 우선합니다. Skill을 전역으로 설치하되 일부 에이전트에만 보이게 하려면 공유 사본은 `~/.openclaw/skills`에 두고 `agents.defaults.skills`와 `agents.list[].skills`로 가시성을 제어하세요. 업스트림에 올릴 가치가 있는 수정만 저장소에 두고 PR로 보내야 합니다. + + 리포지토리 사본을 직접 편집하는 대신 관리형 override를 사용하세요. 변경 사항은 `~/.openclaw/skills//SKILL.md`에 두거나(`~/.openclaw/openclaw.json`의 `skills.load.extraDirs`를 통해 폴더를 추가해도 됨) 관리하세요. 우선순위는 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 번들 → `skills.load.extraDirs` 이므로, 관리형 override가 git을 건드리지 않고도 번들 Skills보다 우선합니다. Skill을 전역으로 설치하되 특정 agents에만 보이게 하려면 공유 사본은 `~/.openclaw/skills`에 두고 `agents.defaults.skills`와 `agents.list[].skills`로 가시성을 제어하세요. 상향식으로 반영할 가치가 있는 수정만 리포지토리에 두고 PR로 보내야 합니다. - 예. `~/.openclaw/openclaw.json`의 `skills.load.extraDirs`를 통해 추가 디렉터리를 지정하세요(가장 낮은 우선순위). 기본 우선순위는 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`입니다. `clawhub`는 기본적으로 `./skills`에 설치하며, OpenClaw는 이를 다음 세션에서 `/skills`로 취급합니다. Skill이 특정 에이전트에만 보여야 한다면 `agents.defaults.skills` 또는 `agents.list[].skills`와 함께 사용하세요. + 예. `~/.openclaw/openclaw.json`의 `skills.load.extraDirs`를 통해 추가 디렉터리를 넣을 수 있습니다(가장 낮은 우선순위). 기본 우선순위는 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 번들 → `skills.load.extraDirs`입니다. `clawhub`는 기본적으로 `./skills`에 설치하며, OpenClaw는 다음 세션에서 이를 `/skills`로 취급합니다. Skill이 특정 agents에만 보여야 한다면 `agents.defaults.skills` 또는 `agents.list[].skills`와 함께 사용하세요. - - 현재 지원되는 패턴은 다음과 같습니다. + + 현재 지원되는 패턴은 다음과 같습니다: - - **Cron 작업:** 격리된 작업마다 `model` override를 설정할 수 있습니다. - - **하위 에이전트:** 기본 모델이 다른 별도 에이전트로 작업을 라우팅합니다. - - **온디맨드 전환:** `/model`을 사용해 현재 세션 모델을 언제든 전환합니다. + - **Cron 작업**: 격리된 작업마다 `model` override를 설정할 수 있습니다. + - **Sub-agents**: 서로 다른 기본 모델을 가진 별도 agent로 작업을 라우팅합니다. + - **온디맨드 전환**: `/model`을 사용해 현재 session 모델을 언제든 전환할 수 있습니다. - [Cron jobs](/ko/automation/cron-jobs), [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [슬래시 명령](/ko/tools/slash-commands)을 참고하세요. + [Cron 작업](/ko/automation/cron-jobs), [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [Slash 명령](/ko/tools/slash-commands)을 참고하세요. - - 길거나 병렬인 작업에는 **하위 에이전트**를 사용하세요. 하위 에이전트는 자체 세션에서 실행되고, - 요약을 반환하며, 메인 채팅의 응답성을 유지합니다. + + 오래 걸리거나 병렬인 작업에는 **sub-agents**를 사용하세요. sub-agents는 자체 session에서 실행되고, + 요약을 반환하며, 메인 채팅이 계속 응답 가능하게 유지합니다. - 봇에게 "이 작업을 위한 하위 에이전트를 생성해 줘"라고 요청하거나 `/subagents`를 사용하세요. - 채팅에서 `/status`를 사용하면 Gateway가 지금 무엇을 하고 있는지(그리고 바쁜지 여부)를 볼 수 있습니다. + 봇에게 "이 작업을 위한 sub-agent를 생성해 줘"라고 요청하거나 `/subagents`를 사용하세요. + 채팅에서 `/status`를 사용하면 Gateway가 지금 무엇을 하는지(그리고 바쁜지 여부)를 볼 수 있습니다. - 토큰 팁: 긴 작업과 하위 에이전트는 모두 토큰을 소비합니다. 비용이 걱정된다면 - `agents.defaults.subagents.model`을 통해 하위 에이전트에 더 저렴한 모델을 설정하세요. + 토큰 팁: 긴 작업과 sub-agents는 모두 토큰을 소비합니다. 비용이 걱정된다면 + `agents.defaults.subagents.model`을 통해 sub-agents용으로 더 저렴한 모델을 설정하세요. - 문서: [하위 에이전트](/ko/tools/subagents), [백그라운드 작업](/ko/automation/tasks). + 문서: [Sub-agents](/ko/tools/subagents), [백그라운드 작업](/ko/automation/tasks). - - 스레드 바인딩을 사용하세요. Discord 스레드를 하위 에이전트 또는 세션 대상에 바인딩하면 해당 스레드의 후속 메시지가 그 바인딩된 세션에 계속 유지됩니다. + + thread 바인딩을 사용하세요. Discord thread를 subagent 또는 session 대상에 바인딩하면 해당 thread의 후속 메시지가 계속 그 바인딩된 session에 유지됩니다. 기본 흐름: - - `sessions_spawn`을 `thread: true`로 실행합니다(지속적인 후속 처리를 원하면 선택적으로 `mode: "session"`도 함께 사용). + - `sessions_spawn`을 `thread: true`로 사용해 생성합니다(지속적인 후속 처리를 원하면 `mode: "session"`도 선택 가능). - 또는 `/focus `으로 수동 바인딩합니다. - - `/agents`로 바인딩 상태를 확인합니다. - - `/session idle ` 및 `/session max-age `를 사용해 자동 unfocus를 제어합니다. - - `/unfocus`로 스레드 바인딩을 해제합니다. + - `/agents`를 사용해 바인딩 상태를 확인합니다. + - `/session idle ` 및 `/session max-age `로 자동 unfocus를 제어합니다. + - `/unfocus`로 thread 연결을 해제합니다. 필요한 config: - 전역 기본값: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Discord overrides: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - 생성 시 자동 바인딩: `channels.discord.threadBindings.spawnSubagentSessions: true`로 설정합니다. + - Discord override: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - 생성 시 자동 바인딩: `channels.discord.threadBindings.spawnSubagentSessions: true`로 설정. - 문서: [하위 에이전트](/ko/tools/subagents), [Discord](/ko/channels/discord), [구성 참조](/ko/gateway/configuration-reference), [슬래시 명령](/ko/tools/slash-commands). + 문서: [Sub-agents](/ko/tools/subagents), [Discord](/ko/channels/discord), [구성 참조](/ko/gateway/configuration-reference), [Slash 명령](/ko/tools/slash-commands). - - 먼저 확인된 requester route를 점검하세요. + + 먼저 해결된 요청자 경로를 확인하세요: - - 완료 모드 하위 에이전트 전달은 바인딩된 스레드나 대화 route가 있으면 이를 우선 사용합니다. - - 완료 origin에 채널만 있으면 OpenClaw는 requester 세션의 저장된 route(`lastChannel` / `lastTo` / `lastAccountId`)로 fallback하여 직접 전달을 계속 시도합니다. - - 바인딩된 route도 없고 사용할 수 있는 저장된 route도 없으면 직접 전달이 실패할 수 있으며, 이 경우 결과는 채팅에 즉시 게시되는 대신 queued session delivery로 fallback합니다. - - 유효하지 않거나 오래된 대상도 queue fallback이나 최종 전달 실패를 유발할 수 있습니다. - - 자식의 마지막으로 보이는 assistant 응답이 정확히 무음 토큰 `NO_REPLY` / `no_reply`이거나 정확히 `ANNOUNCE_SKIP`이면, OpenClaw는 오래된 이전 진행 상황을 게시하지 않도록 의도적으로 announce를 억제합니다. - - 자식이 tool 호출만 수행한 뒤 시간 초과되었다면, announce는 원시 tool 출력을 그대로 재생하는 대신 이를 짧은 부분 진행 요약으로 축약할 수 있습니다. + - 완료 모드 subagent 전달은 바인딩된 thread나 대화 경로가 있으면 이를 우선 사용합니다. + - 완료 원본에 channel 정보만 있을 경우, OpenClaw는 요청자 session의 저장된 경로(`lastChannel` / `lastTo` / `lastAccountId`)로 대체하여 직접 전달이 계속 가능하도록 합니다. + - 바인딩된 경로나 사용할 수 있는 저장된 경로가 모두 없으면 직접 전달이 실패할 수 있으며, 그 결과는 채팅에 즉시 게시되지 않고 큐에 들어간 session 전달로 대체됩니다. + - 유효하지 않거나 오래된 대상은 여전히 큐 대체 또는 최종 전달 실패를 초래할 수 있습니다. + - child의 마지막으로 보이는 assistant 응답이 정확히 무음 토큰 `NO_REPLY` / `no_reply`이거나 정확히 `ANNOUNCE_SKIP`이면, OpenClaw는 오래된 이전 진행 상황을 게시하지 않기 위해 의도적으로 공지를 억제합니다. + - child가 도구 호출만 수행한 뒤 시간 초과되었다면, 공지는 원시 도구 출력을 다시 재생하는 대신 이를 짧은 부분 진행 요약으로 축약할 수 있습니다. 디버그: @@ -1056,19 +1065,19 @@ x-i18n: openclaw tasks show ``` - 문서: [하위 에이전트](/ko/tools/subagents), [백그라운드 작업](/ko/automation/tasks), [세션 도구](/ko/concepts/session-tool). + 문서: [Sub-agents](/ko/tools/subagents), [백그라운드 작업](/ko/automation/tasks), [Session Tools](/ko/concepts/session-tool). - - Cron은 Gateway 프로세스 안에서 실행됩니다. Gateway가 계속 실행되고 있지 않으면, + + Cron은 Gateway 프로세스 내부에서 실행됩니다. Gateway가 지속적으로 실행되고 있지 않으면 예약된 작업은 실행되지 않습니다. - 점검 목록: + 체크리스트: - - cron이 활성화되어 있는지 확인하세요(`cron.enabled`). 또한 `OPENCLAW_SKIP_CRON`이 설정되어 있지 않아야 합니다. + - cron이 활성화되어 있는지(`cron.enabled`) 그리고 `OPENCLAW_SKIP_CRON`이 설정되지 않았는지 확인하세요. - Gateway가 24/7 실행 중인지 확인하세요(절전/재시작 없음). - - 작업의 시간대 설정이 올바른지 확인하세요(`--tz` 대 호스트 시간대). + - 작업의 시간대 설정을 확인하세요(`--tz`와 호스트 시간대 비교). 디버그: @@ -1081,17 +1090,18 @@ x-i18n: - - 먼저 전달 모드를 확인하세요. + + 먼저 전달 모드를 확인하세요: - `--no-deliver` / `delivery.mode: "none"`이면 외부 메시지가 전송되지 않는 것이 정상입니다. - - announce 대상(`channel` / `to`)이 없거나 유효하지 않으면 runner가 outbound delivery를 건너뜁니다. - - 채널 인증 실패(`unauthorized`, `Forbidden`)는 runner가 전달을 시도했지만 자격 증명 때문에 막혔다는 뜻입니다. - - 무음 격리 결과(`NO_REPLY` / `no_reply`만 있음)는 의도적으로 전달 불가한 것으로 처리되므로, runner도 queued fallback delivery를 억제합니다. + - 공지 대상(`channel` / `to`)이 없거나 잘못되었으면 runner가 아웃바운드 전달을 건너뜁니다. + - channel 인증 실패(`unauthorized`, `Forbidden`)는 runner가 전달을 시도했지만 자격 증명이 이를 막았다는 뜻입니다. + - 무음 격리 결과(`NO_REPLY` / `no_reply`만 있음)는 의도적으로 전달 불가로 간주되므로, runner도 큐 대체 전달을 억제합니다. - 격리된 Cron 작업에서는 runner가 최종 전달을 담당합니다. 에이전트는 - runner가 전송할 수 있는 일반 텍스트 요약을 반환해야 합니다. `--no-deliver`는 - 그 결과를 내부에만 유지하며, 에이전트가 대신 message tool로 직접 보내게 하는 것은 아닙니다. + 격리된 cron 작업의 경우, 최종 전달은 runner가 담당합니다. agent는 + runner가 보낼 일반 텍스트 요약을 반환해야 합니다. `--no-deliver`는 + 그 결과를 내부에만 유지할 뿐이며, agent가 대신 메시지 도구로 직접 + 보내게 하지는 않습니다. 디버그: @@ -1104,23 +1114,23 @@ x-i18n: - - 보통 이는 중복 스케줄링이 아니라 라이브 모델 전환 경로 때문입니다. + + 이는 보통 중복 스케줄링이 아니라 라이브 모델 전환 경로입니다. - 격리된 Cron은 활성 실행이 `LiveSessionModelSwitchError`를 발생시키면 - 런타임 모델 handoff를 유지하고 재시도할 수 있습니다. 재시도는 전환된 - provider/model을 유지하며, 전환에 새 auth profile override가 포함되어 있었다면 Cron은 + 격리된 cron은 활성 실행이 `LiveSessionModelSwitchError`를 던질 때 + 런타임 모델 핸드오프를 유지하고 재시도할 수 있습니다. 재시도는 전환된 + provider/model을 유지하며, 전환에 새 auth profile override가 포함되어 있었다면 cron은 재시도 전에 그것도 유지합니다. 관련 선택 규칙: - - 해당되는 경우 Gmail hook 모델 override가 먼저 우선합니다. + - 해당되는 경우 Gmail hook 모델 override가 가장 먼저 우선합니다. - 그다음 작업별 `model`. - 그다음 저장된 cron-session 모델 override. - - 그다음 일반 에이전트/기본 모델 선택. + - 그다음 일반 agent/default 모델 선택. - 재시도 루프는 제한되어 있습니다. 초기 시도와 2회의 전환 재시도 후에는 - Cron이 무한 반복하지 않고 중단합니다. + 재시도 루프는 제한되어 있습니다. 초기 시도와 2회의 전환 재시도 이후에는, + cron이 무한 반복 대신 중단합니다. 디버그: @@ -1135,7 +1145,7 @@ x-i18n: 기본 `openclaw skills` 명령을 사용하거나 Skills를 workspace에 직접 넣으세요. macOS Skills UI는 Linux에서 사용할 수 없습니다. - Skills 탐색: [https://clawhub.ai](https://clawhub.ai) + Skills는 [https://clawhub.ai](https://clawhub.ai)에서 둘러볼 수 있습니다. ```bash openclaw skills search "calendar" @@ -1150,18 +1160,18 @@ x-i18n: 기본 `openclaw skills install`은 활성 workspace의 `skills/` 디렉터리에 기록합니다. 자신의 Skills를 게시하거나 - 동기화하려는 경우에만 별도의 `clawhub` CLI를 설치하세요. 여러 에이전트 간 공유 설치를 원하면 Skill을 - `~/.openclaw/skills` 아래에 두고, 표시 대상을 제한하려면 `agents.defaults.skills` 또는 + 동기화하려는 경우에만 별도의 `clawhub` CLI를 설치하세요. 여러 agent에서 공유 설치하려면 Skill을 + `~/.openclaw/skills` 아래에 두고, 어떤 agent가 볼 수 있을지 제한하려면 `agents.defaults.skills` 또는 `agents.list[].skills`를 사용하세요. - - 예. Gateway 스케줄러를 사용하세요. + + 예. Gateway 스케줄러를 사용하세요: - - 예약 또는 반복 작업에는 **Cron 작업**(재시작 후에도 유지). - - "main session" 주기 점검에는 **Heartbeat**. - - 요약을 게시하거나 채팅으로 전달하는 자율 에이전트에는 **격리 작업**. + - 예약되거나 반복되는 작업에는 **Cron 작업**(재시작 후에도 유지). + - "메인 session"의 주기적 점검에는 **Heartbeat**. + - 요약을 게시하거나 채팅으로 전달하는 자율 agent에는 **격리된 작업**. 문서: [Cron 작업](/ko/automation/cron-jobs), [자동화 및 작업](/ko/automation), [Heartbeat](/ko/gateway/heartbeat). @@ -1169,20 +1179,20 @@ x-i18n: - 직접적으로는 불가능합니다. macOS Skills는 `metadata.openclaw.os`와 필요한 바이너리로 제어되며, Skills는 **Gateway host**에서 적격할 때만 system prompt에 나타납니다. Linux에서는 gating을 override하지 않는 한 `darwin` 전용 Skills(`apple-notes`, `apple-reminders`, `things-mac` 등)는 로드되지 않습니다. + 직접적으로는 안 됩니다. macOS Skills는 `metadata.openclaw.os`와 필요한 바이너리에 의해 제한되며, Skills는 **Gateway 호스트**에서 적격일 때만 시스템 프롬프트에 나타납니다. Linux에서는 게이팅을 override하지 않는 한 `darwin` 전용 Skills(`apple-notes`, `apple-reminders`, `things-mac` 등)는 로드되지 않습니다. - 지원되는 패턴은 세 가지입니다. + 지원되는 패턴은 세 가지입니다: - **옵션 A - Mac에서 Gateway 실행(가장 간단함).** - macOS 바이너리가 있는 곳에서 Gateway를 실행한 다음, Linux에서 [remote mode](#gateway-포트가-이미-실행-중인-경우와-remote-mode) 또는 Tailscale로 연결하세요. Gateway host가 macOS이므로 Skills가 정상적으로 로드됩니다. + **옵션 A - Mac에서 Gateway 실행(가장 단순함).** + macOS 바이너리가 있는 곳에서 Gateway를 실행한 다음, Linux에서 [원격 모드](#gateway-포트가-이미-실행-중이고-remote-mode) 또는 Tailscale을 통해 연결하세요. Gateway 호스트가 macOS이므로 Skills가 정상적으로 로드됩니다. - **옵션 B - macOS Node 사용(SSH 없음).** - Linux에서 Gateway를 실행하고 macOS Node(메뉴바 앱)를 페어링한 뒤, Mac에서 **Node Run Commands**를 "Always Ask" 또는 "Always Allow"로 설정하세요. 필요한 바이너리가 node에 있으면 OpenClaw는 macOS 전용 Skills를 적격으로 취급할 수 있습니다. 에이전트는 `nodes` tool을 통해 تلك Skills를 실행합니다. "Always Ask"를 선택한 경우 프롬프트에서 "Always Allow"를 승인하면 해당 명령이 allowlist에 추가됩니다. + **옵션 B - macOS Node 사용(SSH 불필요).** + Linux에서 Gateway를 실행하고, macOS Node(메뉴 막대 앱)를 페어링한 다음 Mac에서 **Node Run Commands**를 "Always Ask" 또는 "Always Allow"로 설정하세요. 필요한 바이너리가 Node에 존재하면 OpenClaw는 macOS 전용 Skills를 적격으로 취급할 수 있습니다. agent는 `nodes` 도구를 통해 해당 Skills를 실행합니다. "Always Ask"를 선택한 경우, 프롬프트에서 "Always Allow"를 승인하면 그 명령이 허용 목록에 추가됩니다. - **옵션 C - SSH를 통해 macOS 바이너리 프록시(고급).** - Gateway는 Linux에 두되, 필요한 CLI 바이너리가 Mac에서 실행되는 SSH 래퍼로 해석되게 하세요. 그런 다음 Skill이 적격 상태를 유지하도록 Linux를 허용하도록 override합니다. + **옵션 C - SSH로 macOS 바이너리 프록시(고급).** + Gateway는 Linux에 두되, 필요한 CLI 바이너리가 Mac에서 실행되는 SSH 래퍼로 해석되도록 만드세요. 그런 다음 Skill이 적격 상태를 유지하도록 Linux를 허용하는 override를 적용합니다. - 1. 바이너리에 대한 SSH 래퍼를 만듭니다(예: Apple Notes용 `memo`). + 1. 바이너리용 SSH 래퍼를 만듭니다(예: Apple Notes용 `memo`): ```bash #!/usr/bin/env bash @@ -1190,37 +1200,36 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. 래퍼를 Linux 호스트의 `PATH`에 둡니다(예: `~/bin/memo`). - 3. Skill 메타데이터(workspace 또는 `~/.openclaw/skills`)를 override하여 Linux를 허용합니다. + 2. Linux 호스트의 `PATH`에 래퍼를 추가합니다(예: `~/bin/memo`). + 3. Skill 메타데이터(workspace 또는 `~/.openclaw/skills`)를 override하여 Linux를 허용합니다: ```markdown --- name: apple-notes - description: macOS의 memo CLI를 통해 Apple Notes를 관리합니다. + description: Manage Apple Notes via the memo CLI on macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. 새 세션을 시작해 Skills 스냅샷을 새로 고칩니다. + 4. Skills 스냅샷이 새로 고쳐지도록 새 session을 시작합니다. - - 현재는 기본 제공되지 않습니다. + + 현재 기본 제공되지는 않습니다. - 옵션: + 선택지: - **사용자 지정 Skill / Plugin:** 안정적인 API 액세스에 가장 적합합니다(Notion/HeyGen 모두 API 제공). - - **브라우저 자동화:** 코드 없이도 가능하지만 더 느리고 더 취약합니다. + - **브라우저 자동화:** 코드 없이도 가능하지만 더 느리고 취약합니다. - 클라이언트별로 컨텍스트를 유지하고 싶다면(에이전시 워크플로), - 간단한 패턴은 다음과 같습니다. + 클라이언트별 컨텍스트(에이전시 워크플로)를 유지하고 싶다면, 간단한 패턴은 다음과 같습니다: - - 클라이언트마다 하나의 Notion 페이지(컨텍스트 + 선호 사항 + 진행 중 작업). - - 세션 시작 시 에이전트에게 해당 페이지를 가져오라고 요청. + - 클라이언트마다 하나의 Notion 페이지(컨텍스트 + 선호도 + 진행 중 작업). + - session 시작 시 agent에게 해당 페이지를 가져오도록 요청. - 네이티브 통합이 필요하다면 기능 요청을 열거나, - 해당 API를 대상으로 하는 Skill을 직접 만드세요. + 네이티브 통합이 필요하다면 기능 요청을 열거나 + 해당 API를 대상으로 Skill을 만드세요. Skills 설치: @@ -1229,184 +1238,184 @@ x-i18n: openclaw skills update --all ``` - 기본 설치는 활성 workspace의 `skills/` 디렉터리에 배치됩니다. 여러 에이전트가 공유하는 Skills는 `~/.openclaw/skills//SKILL.md`에 두세요. 일부 에이전트에만 공유 설치를 보이게 하려면 `agents.defaults.skills` 또는 `agents.list[].skills`를 구성하세요. 일부 Skills는 Homebrew로 설치한 바이너리를 기대하며, Linux에서는 이는 Linuxbrew를 의미합니다(위의 Homebrew Linux FAQ 항목 참고). [Skills](/ko/tools/skills), [Skills config](/ko/tools/skills-config), [ClawHub](/ko/tools/clawhub)를 참고하세요. + 기본 설치는 활성 workspace의 `skills/` 디렉터리에 들어갑니다. 여러 agent 간 공유 Skills의 경우 `~/.openclaw/skills//SKILL.md`에 두세요. 공유 설치를 일부 agent에게만 보이게 하려면 `agents.defaults.skills` 또는 `agents.list[].skills`를 구성하세요. 일부 Skills는 Homebrew로 설치된 바이너리를 기대하며, Linux에서는 이는 Linuxbrew를 의미합니다(위의 Homebrew Linux FAQ 항목 참고). [Skills](/ko/tools/skills), [Skills 구성](/ko/tools/skills-config), [ClawHub](/ko/tools/clawhub)를 참고하세요. - - Chrome DevTools MCP를 통해 연결하는 기본 제공 `user` 브라우저 profile을 사용하세요. + + Chrome DevTools MCP를 통해 연결되는 기본 제공 `user` 브라우저 프로필을 사용하세요: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 사용자 지정 이름을 원한다면 명시적인 MCP profile을 만드세요. + 사용자 지정 이름을 원한다면 명시적인 MCP 프로필을 만드세요: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 이 경로는 호스트 로컬 전용입니다. Gateway가 다른 곳에서 실행 중이라면 브라우저 머신에서 node host를 실행하거나 원격 CDP를 사용하세요. + 이 경로는 로컬 호스트 브라우저 또는 연결된 browser Node를 사용할 수 있습니다. Gateway가 다른 곳에서 실행된다면, 브라우저 머신에서 node 호스트를 실행하거나 원격 CDP를 대신 사용하세요. - `existing-session` / `user`의 현재 제한 사항: + 현재 `existing-session` / `user`의 제한 사항: - - 작업은 CSS selector 기준이 아니라 ref 기준입니다 - - 업로드는 `ref` / `inputRef`가 필요하며 현재는 한 번에 하나의 파일만 지원합니다 - - `responsebody`, PDF 내보내기, 다운로드 가로채기, 일괄 작업은 여전히 managed browser 또는 원시 CDP profile이 필요합니다 + - 작업은 CSS selector 기반이 아니라 ref 기반입니다 + - 업로드에는 `ref` / `inputRef`가 필요하며 현재 한 번에 파일 하나만 지원합니다 + - `responsebody`, PDF 내보내기, 다운로드 가로채기, 일괄 작업은 여전히 관리형 브라우저 또는 raw CDP 프로필이 필요합니다 -## 샌드박싱과 메모리 +## 샌드박싱 및 memory - - 예. [샌드박싱](/ko/gateway/sandboxing)을 참고하세요. Docker 전용 설정(전체 gateway를 Docker에서 실행하거나 sandbox 이미지를 사용하는 경우)은 [Docker](/ko/install/docker)를 참고하세요. + + 예. [샌드박싱](/ko/gateway/sandboxing)을 참고하세요. Docker 전용 설정(전체 gateway를 Docker에서 실행하거나 샌드박스 이미지를 사용하는 경우)은 [Docker](/ko/install/docker)를 참고하세요. - 기본 이미지는 보안 우선이며 `node` 사용자로 실행되므로, - 시스템 패키지, Homebrew 또는 번들 브라우저가 포함되어 있지 않습니다. 더 완전한 설정을 원한다면: + 기본 이미지는 보안을 우선하며 `node` 사용자로 실행되므로, + 시스템 패키지, Homebrew, 번들 브라우저를 포함하지 않습니다. 더 완전한 설정을 원한다면: - - 캐시가 유지되도록 `OPENCLAW_HOME_VOLUME`으로 `/home/node`를 영속화하세요. - - `OPENCLAW_DOCKER_APT_PACKAGES`로 시스템 의존성을 이미지에 bake하세요. - - 번들된 CLI로 Playwright 브라우저를 설치하세요: + - 캐시가 유지되도록 `/home/node`를 `OPENCLAW_HOME_VOLUME`으로 영속화하세요. + - `OPENCLAW_DOCKER_APT_PACKAGES`로 시스템 의존성을 이미지에 포함시키세요. + - 번들 CLI로 Playwright 브라우저를 설치하세요: `node /app/node_modules/playwright-core/cli.js install chromium` - `PLAYWRIGHT_BROWSERS_PATH`를 설정하고 해당 경로가 영속화되도록 하세요. - 문서: [Docker](/ko/install/docker), [브라우저](/ko/tools/browser). + 문서: [Docker](/ko/install/docker), [Browser](/ko/tools/browser). - + 예. 비공개 트래픽이 **DM**이고 공개 트래픽이 **그룹**이라면 가능합니다. - `agents.defaults.sandbox.mode: "non-main"`을 사용하면 그룹/채널 세션(non-main key)은 Docker에서 실행되고, 메인 DM 세션은 호스트에서 유지됩니다. 그런 다음 `tools.sandbox.tools`를 통해 샌드박스 세션에서 사용할 수 있는 도구를 제한하세요. + `agents.defaults.sandbox.mode: "non-main"`을 사용하면 그룹/channel sessions(비메인 키)는 Docker에서 실행되고, 메인 DM session은 호스트에서 유지됩니다. 그런 다음 `tools.sandbox.tools`를 통해 샌드박스된 sessions에서 어떤 도구를 사용할 수 있을지 제한하세요. - 설정 안내 + 예시 구성: [그룹: 개인 DM + 공개 그룹](/ko/channels/groups#pattern-personal-dms-public-groups-single-agent) + 설정 안내 + 예시 config: [그룹: 개인 DM + 공개 그룹](/ko/channels/groups#pattern-personal-dms-public-groups-single-agent) - 주요 config 참조: [Gateway 구성](/ko/gateway/configuration-reference#agentsdefaultssandbox) + 핵심 config 참조: [Gateway 구성](/ko/gateway/configuration-reference#agentsdefaultssandbox) - `agents.defaults.sandbox.docker.binds`를 `["host:path:mode"]` 형식으로 설정하세요(예: `"/home/user/src:/src:ro"`). 전역 + 에이전트별 bind는 병합되며, `scope: "shared"`일 때는 에이전트별 bind가 무시됩니다. 민감한 항목에는 `:ro`를 사용하고, bind는 샌드박스 파일 시스템 경계를 우회한다는 점을 기억하세요. + `agents.defaults.sandbox.docker.binds`를 `["host:path:mode"]` 형식으로 설정하세요(예: `"/home/user/src:/src:ro"`). 전역 바인드와 agent별 바인드는 병합되며, `scope: "shared"`일 때 agent별 바인드는 무시됩니다. 민감한 항목에는 `:ro`를 사용하고, 바인드는 샌드박스 파일시스템 경계를 우회한다는 점을 기억하세요. - OpenClaw는 정규화된 경로와 가장 깊은 기존 상위를 통해 해석된 canonical 경로를 모두 기준으로 bind source를 검증합니다. 즉, 마지막 경로 세그먼트가 아직 존재하지 않더라도 symlink 상위 경로를 통한 탈출은 여전히 fail closed되며, symlink 해석 후에도 허용된 루트 검사도 계속 적용됩니다. + OpenClaw는 정규화된 경로와 가장 깊은 기존 상위를 통해 해결된 정식 경로 모두에 대해 bind 소스를 검증합니다. 즉, 마지막 경로 세그먼트가 아직 존재하지 않더라도 symlink 상위 경로를 통한 탈출은 여전히 fail-closed로 차단되며, 허용된 루트 검사도 symlink 해석 이후 계속 적용됩니다. - 예시와 안전 관련 참고 사항은 [샌드박싱](/ko/gateway/sandboxing#custom-bind-mounts) 및 [Sandbox vs Tool Policy vs Elevated](/ko/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)를 참고하세요. + 예시와 안전 관련 참고 사항은 [샌드박싱](/ko/gateway/sandboxing#custom-bind-mounts) 및 [샌드박스 vs 도구 정책 vs 승격](/ko/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)을 참고하세요. - - OpenClaw 메모리는 에이전트 workspace 안의 Markdown 파일일 뿐입니다. + + OpenClaw memory는 agent workspace 안의 Markdown 파일일 뿐입니다: - - 일일 노트는 `memory/YYYY-MM-DD.md` - - 선별된 장기 노트는 `MEMORY.md`(main/private 세션 전용) + - `memory/YYYY-MM-DD.md`의 일일 노트 + - `MEMORY.md`의 선별된 장기 노트(메인/비공개 sessions 전용) - OpenClaw는 또한 **무음 사전 Compaction 메모리 flush**를 실행하여 모델이 - 자동 Compaction 전에 오래 유지될 노트를 작성하도록 상기시킵니다. 이는 workspace가 - 쓰기 가능할 때만 실행됩니다(읽기 전용 샌드박스에서는 건너뜀). [메모리](/ko/concepts/memory)를 참고하세요. + OpenClaw는 또한 모델에 자동 Compaction 전에 + 오래 유지할 노트를 기록하도록 상기시키기 위해 **무음 사전 Compaction memory flush**를 실행합니다. 이는 workspace가 + 쓰기 가능할 때만 실행됩니다(읽기 전용 샌드박스에서는 건너뜀). [Memory](/ko/concepts/memory)를 참고하세요. - - 봇에게 **그 사실을 메모리에 기록하라고** 요청하세요. 장기 노트는 `MEMORY.md`에, + + 봇에게 **그 사실을 memory에 기록하라고** 요청하세요. 장기 노트는 `MEMORY.md`에, 단기 컨텍스트는 `memory/YYYY-MM-DD.md`에 들어갑니다. - 이 부분은 아직 계속 개선 중입니다. 모델에게 메모리를 저장하라고 상기시키면 도움이 되며, - 모델은 무엇을 해야 할지 알고 있습니다. 계속 잊어버린다면 Gateway가 매번 같은 - workspace를 사용하고 있는지 확인하세요. + 이 부분은 아직 계속 개선 중입니다. 모델에게 memory를 저장하라고 상기시키면 도움이 되며, + 모델은 무엇을 해야 할지 알 것입니다. 계속 잊어버린다면 Gateway가 실행할 때마다 같은 + workspace를 사용하는지 확인하세요. - 문서: [메모리](/ko/concepts/memory), [에이전트 workspace](/ko/concepts/agent-workspace). + 문서: [Memory](/ko/concepts/memory), [Agent workspace](/ko/concepts/agent-workspace). - - 메모리 파일은 디스크에 저장되며 직접 삭제할 때까지 유지됩니다. 제한은 - 모델이 아니라 저장 공간입니다. 다만 **세션 컨텍스트**는 여전히 모델의 - 컨텍스트 윈도우 제한을 받으므로, 긴 대화는 Compaction되거나 잘릴 수 있습니다. 그래서 - 메모리 검색이 존재합니다. 관련 있는 부분만 다시 컨텍스트로 가져옵니다. + + memory 파일은 디스크에 저장되며 직접 삭제할 때까지 유지됩니다. 한계는 모델이 아니라 + 저장 공간입니다. 하지만 **session 컨텍스트**는 여전히 모델의 + 컨텍스트 창에 의해 제한되므로, 긴 대화는 Compaction되거나 잘릴 수 있습니다. 그래서 + memory 검색이 존재합니다. 관련 부분만 다시 컨텍스트로 가져옵니다. - 문서: [메모리](/ko/concepts/memory), [컨텍스트](/ko/concepts/context). + 문서: [Memory](/ko/concepts/memory), [컨텍스트](/ko/concepts/context). - - **OpenAI 임베딩**을 사용하는 경우에만 필요합니다. Codex OAuth는 채팅/완성만 - 지원하며 **임베딩 액세스는 제공하지 않으므로**, **Codex로 로그인해도(OAuth 또는 - Codex CLI 로그인)** 시맨틱 메모리 검색에는 도움이 되지 않습니다. OpenAI 임베딩에는 + + **OpenAI embeddings**를 사용할 때만 필요합니다. Codex OAuth는 채팅/completions만 지원하며 + embeddings 접근 권한은 **부여하지 않으므로**, **Codex로 로그인해도(OAuth 또는 + Codex CLI 로그인)** 시맨틱 memory 검색에는 도움이 되지 않습니다. OpenAI embeddings에는 여전히 실제 API 키(`OPENAI_API_KEY` 또는 `models.providers.openai.apiKey`)가 필요합니다. - 제공자를 명시적으로 설정하지 않으면 OpenClaw는 API 키를 해석할 수 있을 때 - 제공자를 자동 선택합니다(auth profile, `models.providers.*.apiKey`, 또는 env vars). - OpenAI 키를 해석할 수 있으면 OpenAI를 우선하고, 그렇지 않으면 Gemini, - 그다음 Voyage, 그다음 Mistral 순입니다. 원격 키를 사용할 수 없으면 메모리 - 검색은 구성할 때까지 비활성 상태로 유지됩니다. 로컬 모델 경로가 - 구성되어 있고 존재하면 OpenClaw는 + provider를 명시적으로 설정하지 않으면, OpenClaw는 API 키를 해결할 수 있을 때 + provider를 자동 선택합니다(auth profiles, `models.providers.*.apiKey`, 또는 env vars). + OpenAI 키를 해결할 수 있으면 OpenAI를 우선하고, 그렇지 않으면 Gemini 키가 + 해결되면 Gemini, 그다음 Voyage, 그다음 Mistral을 선택합니다. 원격 키를 사용할 수 없으면 + 구성하기 전까지 memory 검색은 비활성 상태로 남습니다. 로컬 모델 경로가 + 구성되어 있고 실제로 존재하면, OpenClaw는 `local`을 우선합니다. Ollama는 `memorySearch.provider = "ollama"`를 명시적으로 설정하면 지원됩니다. - 로컬로만 유지하고 싶다면 `memorySearch.provider = "local"`(그리고 선택적으로 - `memorySearch.fallback = "none"`)을 설정하세요. Gemini 임베딩을 원한다면 + 로컬만 사용하고 싶다면 `memorySearch.provider = "local"`(그리고 선택적으로 + `memorySearch.fallback = "none"`)을 설정하세요. Gemini embeddings를 원한다면 `memorySearch.provider = "gemini"`를 설정하고 `GEMINI_API_KEY`(또는 - `memorySearch.remote.apiKey`)를 제공하세요. **OpenAI, Gemini, Voyage, Mistral, Ollama 또는 local** - 임베딩 모델을 지원합니다. 설정 세부 정보는 [메모리](/ko/concepts/memory)를 참고하세요. + `memorySearch.remote.apiKey`)를 제공하세요. **OpenAI, Gemini, Voyage, Mistral, Ollama, 또는 local** embeddings + 모델을 지원합니다. 자세한 설정은 [Memory](/ko/concepts/memory)를 참고하세요. -## 디스크에서 파일이 저장되는 위치 +## 디스크에서 파일 위치 - - 아니요. **OpenClaw의 상태는 로컬**이지만, **외부 서비스는 여전히 사용자가 보낸 내용을 볼 수 있습니다**. + + 아니요. **OpenClaw의 state는 로컬**이지만, **외부 서비스는 여전히 사용자가 보내는 내용을 볼 수 있습니다**. - - **기본적으로 로컬:** 세션, 메모리 파일, config, workspace는 Gateway host에 저장됩니다 + - **기본적으로 로컬:** sessions, memory 파일, config, workspace는 Gateway 호스트에 있습니다 (`~/.openclaw` + workspace 디렉터리). - - **필수적으로 원격:** 모델 제공자(Anthropic/OpenAI 등)로 보내는 메시지는 - 해당 API로 전송되며, 채팅 플랫폼(WhatsApp/Telegram/Slack 등)은 메시지 데이터를 - 자사 서버에 저장합니다. - - **흔적은 사용자가 제어:** 로컬 모델을 사용하면 프롬프트는 기기에 남지만, - 채널 트래픽은 여전히 해당 채널의 서버를 거칩니다. + - **필연적으로 원격:** 모델 provider(Anthropic/OpenAI 등)에 보내는 메시지는 + 해당 API로 전송되고, 채팅 플랫폼(WhatsApp/Telegram/Slack 등)은 메시지 데이터를 + 각자 서버에 저장합니다. + - **사용자가 범위를 제어:** 로컬 모델을 사용하면 프롬프트는 기기에 남지만, channel + 트래픽은 여전히 해당 channel 서버를 거칩니다. - 관련 문서: [에이전트 workspace](/ko/concepts/agent-workspace), [메모리](/ko/concepts/memory). + 관련 문서: [Agent workspace](/ko/concepts/agent-workspace), [Memory](/ko/concepts/memory). - 모든 것은 `$OPENCLAW_STATE_DIR` 아래에 있습니다(기본값: `~/.openclaw`). + 모든 것은 `$OPENCLAW_STATE_DIR` 아래에 있습니다(기본값: `~/.openclaw`): - | 경로 | 용도 | + | Path | 용도 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | 메인 config (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 레거시 OAuth import(첫 사용 시 auth profile로 복사됨) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | auth profile(OAuth, API 키, 선택적 `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/openclaw.json` | 기본 config (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 레거시 OAuth 가져오기(첫 사용 시 auth profile로 복사됨) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profile(OAuth, API 키, 선택적 `keyRef`/`tokenRef`) | | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef provider용 선택적 파일 기반 secret payload | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 레거시 호환 파일(정적 `api_key` 항목 scrubbed 처리됨) | - | `$OPENCLAW_STATE_DIR/credentials/` | provider 상태(예: `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | 에이전트별 상태(agentDir + 세션) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 대화 기록 및 상태(에이전트별) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 세션 메타데이터(에이전트별) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 레거시 호환 파일(정적 `api_key` 항목은 제거됨) | + | `$OPENCLAW_STATE_DIR/credentials/` | Provider 상태(예: `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | agent별 state(agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 대화 기록 및 state(agent별) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Session 메타데이터(agent별) | - 레거시 단일 에이전트 경로: `~/.openclaw/agent/*` (`openclaw doctor`가 마이그레이션함). + 레거시 단일 agent 경로: `~/.openclaw/agent/*` (`openclaw doctor`가 마이그레이션). - **workspace**(`AGENTS.md`, 메모리 파일, Skills 등)는 별도이며 `agents.defaults.workspace`로 구성합니다(기본값: `~/.openclaw/workspace`). + **workspace**(AGENTS.md, memory 파일, Skills 등)는 별도이며 `agents.defaults.workspace`를 통해 구성합니다(기본값: `~/.openclaw/workspace`). - - 이 파일들은 `~/.openclaw`가 아니라 **에이전트 workspace**에 둡니다. + + 이 파일들은 `~/.openclaw`가 아니라 **agent workspace**에 있어야 합니다. - - **Workspace(에이전트별):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md`(또는 `MEMORY.md`가 없을 때의 레거시 fallback인 `memory.md`), - `memory/YYYY-MM-DD.md`, 선택적인 `HEARTBEAT.md` - - **state dir (`~/.openclaw`)**: config, 채널/provider 상태, auth profile, 세션, 로그, - 공유 Skills(`~/.openclaw/skills`) + - **Workspace(agent별)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md`(또는 `MEMORY.md`가 없을 때의 레거시 대체 `memory.md`), + `memory/YYYY-MM-DD.md`, 선택적 `HEARTBEAT.md`. + - **State dir (`~/.openclaw`)**: config, channel/provider state, auth profiles, sessions, logs, + 그리고 공유 Skills(`~/.openclaw/skills`). - 기본 workspace는 `~/.openclaw/workspace`이며, 다음으로 구성할 수 있습니다. + 기본 workspace는 `~/.openclaw/workspace`이며, 다음으로 구성할 수 있습니다: ```json5 { @@ -1414,27 +1423,27 @@ x-i18n: } ``` - 재시작 후 봇이 "잊어버린다"면 Gateway가 매번 같은 - workspace를 사용하고 있는지 확인하세요(그리고 remote mode에서는 **gateway host의** - workspace를 사용하며, 로컬 노트북의 workspace가 아니라는 점을 기억하세요). + 재시작 후 봇이 "잊어버린다면", Gateway가 실행할 때마다 같은 + workspace를 사용하는지 확인하세요(그리고 기억하세요: remote mode는 로컬 노트북이 아니라 **gateway 호스트의** + workspace를 사용합니다). - 팁: 지속적인 동작이나 선호 사항을 원한다면 채팅 기록에만 의존하지 말고 - 봇에게 **AGENTS.md 또는 MEMORY.md에 기록하라**고 요청하세요. + 팁: 오래 유지할 동작이나 선호 사항이 있다면 채팅 기록에 의존하지 말고 + 봇에게 **AGENTS.md 또는 MEMORY.md에 기록하라고** 요청하세요. - [에이전트 workspace](/ko/concepts/agent-workspace)와 [메모리](/ko/concepts/memory)를 참고하세요. + [Agent workspace](/ko/concepts/agent-workspace) 및 [Memory](/ko/concepts/memory)를 참고하세요. - **에이전트 workspace**를 **비공개** git 저장소에 두고 - 비공개 위치(예: GitHub private)에 백업하세요. 이렇게 하면 메모리 + AGENTS/SOUL/USER - 파일이 보존되며, 나중에 어시스턴트의 "마음"을 복원할 수 있습니다. + **agent workspace**를 **비공개** git 리포지토리에 두고 + 비공개 위치(예: GitHub private)에 백업하세요. 이렇게 하면 memory + AGENTS/SOUL/USER + 파일을 보존할 수 있고, 나중에 assistant의 "마음"을 복원할 수 있습니다. - `~/.openclaw` 아래의 어떤 것도 commit하지 마세요(자격 증명, 세션, 토큰 또는 암호화된 secret payload). + `~/.openclaw` 아래의 어떤 것도 commit하지 마세요(credentials, sessions, tokens, 또는 암호화된 secrets payload). 전체 복원이 필요하다면 workspace와 state 디렉터리를 각각 별도로 백업하세요(위의 마이그레이션 질문 참고). - 문서: [에이전트 workspace](/ko/concepts/agent-workspace). + 문서: [Agent workspace](/ko/concepts/agent-workspace). @@ -1442,16 +1451,16 @@ x-i18n: 전용 가이드를 참고하세요: [제거](/ko/install/uninstall). - - 예. workspace는 **기본 cwd**이자 메모리 기준점이지, 강제 샌드박스는 아닙니다. - 상대 경로는 workspace 안에서 해석되지만, 절대 경로는 다른 - 호스트 위치에도 접근할 수 있습니다. 격리가 필요하면 - [`agents.defaults.sandbox`](/ko/gateway/sandboxing) 또는 에이전트별 샌드박스 설정을 사용하세요. 특정 저장소를 - 기본 작업 디렉터리로 쓰고 싶다면 해당 에이전트의 - `workspace`를 그 저장소 루트로 지정하세요. OpenClaw 저장소는 단지 소스 코드일 뿐이므로, - 에이전트가 그 안에서 작업하도록 의도한 경우가 아니라면 workspace는 별도로 유지하세요. + + 예. workspace는 **기본 cwd**이자 memory 기준점이지, 강제 샌드박스는 아닙니다. + 상대 경로는 workspace 내부에서 해석되지만, 절대 경로는 다른 + 호스트 위치에도 접근할 수 있습니다. 격리가 필요하다면 + [`agents.defaults.sandbox`](/ko/gateway/sandboxing) 또는 agent별 샌드박스 설정을 사용하세요. 특정 + 리포지토리를 기본 작업 디렉터리로 사용하고 싶다면, 해당 agent의 + `workspace`를 리포지토리 루트로 지정하세요. OpenClaw 리포지토리는 단지 소스 코드일 뿐이므로, + agent가 그 안에서 작업하도록 의도한 경우가 아니라면 workspace는 별도로 유지하세요. - 예시(저장소를 기본 cwd로 사용): + 예시(리포지토리를 기본 cwd로 사용): ```json5 { @@ -1465,30 +1474,30 @@ x-i18n: - - 세션 상태는 **gateway host**가 소유합니다. remote mode를 사용 중이라면 중요한 세션 저장소는 로컬 노트북이 아니라 원격 머신에 있습니다. [세션 관리](/ko/concepts/session)를 참고하세요. + + session state는 **gateway 호스트**가 소유합니다. remote mode라면, 중요한 session 저장소는 로컬 노트북이 아니라 원격 머신에 있습니다. [Session 관리](/ko/concepts/session)를 참고하세요. ## 기본 config - - OpenClaw는 `$OPENCLAW_CONFIG_PATH`(기본값: `~/.openclaw/openclaw.json`)에서 선택적 **JSON5** config를 읽습니다. + + OpenClaw는 `$OPENCLAW_CONFIG_PATH`(기본값: `~/.openclaw/openclaw.json`)에서 선택적 **JSON5** config를 읽습니다: ``` $OPENCLAW_CONFIG_PATH ``` - 파일이 없으면 안전한 기본값을 사용합니다(기본 workspace `~/.openclaw/workspace` 포함). + 파일이 없으면 비교적 안전한 기본값을 사용합니다(기본 workspace인 `~/.openclaw/workspace` 포함). - - non-loopback bind에는 **유효한 gateway 인증 경로**가 필요합니다. 실제로는 다음 중 하나를 의미합니다. + + loopback이 아닌 bind는 **유효한 gateway 인증 경로가 필요합니다**. 실제로는 다음을 의미합니다: - - 공유 비밀 인증: 토큰 또는 비밀번호 - - 올바르게 구성된 non-loopback ID 인식 reverse proxy 뒤의 `gateway.auth.mode: "trusted-proxy"` + - 공유 시크릿 인증: token 또는 password + - 올바르게 구성된 loopback이 아닌 ID 인식 reverse proxy 뒤의 `gateway.auth.mode: "trusted-proxy"` ```json5 { @@ -1504,32 +1513,32 @@ x-i18n: 참고: - - `gateway.remote.token` / `.password`는 그 자체로 로컬 gateway 인증을 활성화하지 않습니다. - - 로컬 호출 경로는 `gateway.auth.*`가 설정되지 않은 경우에만 `gateway.remote.*`를 fallback으로 사용할 수 있습니다. - - 비밀번호 인증의 경우 `gateway.auth.mode: "password"`와 `gateway.auth.password`(또는 `OPENCLAW_GATEWAY_PASSWORD`)를 설정하세요. - - `gateway.auth.token` / `gateway.auth.password`가 SecretRef로 명시적으로 구성되었지만 해석되지 않으면, 해석은 fail closed되며(원격 fallback으로 가려지지 않음) 종료됩니다. - - 공유 비밀 Control UI 설정은 `connect.params.auth.token` 또는 `connect.params.auth.password`(앱/UI 설정에 저장됨)를 통해 인증합니다. Tailscale Serve 또는 `trusted-proxy` 같은 신원 포함 모드는 대신 request header를 사용합니다. 공유 비밀을 URL에 넣지 마세요. - - `gateway.auth.mode: "trusted-proxy"`에서는 같은 호스트의 loopback reverse proxy도 여전히 trusted-proxy 인증을 충족하지 않습니다. trusted proxy는 구성된 non-loopback source여야 합니다. + - `gateway.remote.token` / `.password`만으로는 로컬 gateway 인증이 활성화되지 않습니다. + - 로컬 호출 경로는 `gateway.auth.*`가 설정되지 않은 경우에만 `gateway.remote.*`를 대체 수단으로 사용할 수 있습니다. + - password 인증의 경우, 대신 `gateway.auth.mode: "password"`와 `gateway.auth.password`(또는 `OPENCLAW_GATEWAY_PASSWORD`)를 설정하세요. + - `gateway.auth.token` / `gateway.auth.password`가 SecretRef를 통해 명시적으로 구성되었는데 해결되지 않으면, 해결은 fail-closed로 종료됩니다(원격 대체로 가려지지 않음). + - 공유 시크릿 Control UI 설정은 `connect.params.auth.token` 또는 `connect.params.auth.password`(앱/UI 설정에 저장됨)로 인증합니다. Tailscale Serve나 `trusted-proxy` 같은 ID 포함 모드는 대신 요청 헤더를 사용합니다. 공유 시크릿을 URL에 넣지 마세요. + - `gateway.auth.mode: "trusted-proxy"`에서는 같은 호스트의 loopback reverse proxy도 여전히 trusted-proxy 인증을 충족하지 않습니다. trusted proxy는 구성된 loopback이 아닌 소스여야 합니다. - - OpenClaw는 loopback을 포함해 기본적으로 gateway 인증을 강제합니다. 일반적인 기본 경로에서는 이는 토큰 인증을 의미합니다. 명시적인 인증 경로가 구성되지 않으면 gateway 시작 시 토큰 모드로 해석되고 자동 생성된 토큰을 `gateway.auth.token`에 저장하므로, **로컬 WS 클라이언트도 인증해야 합니다**. 이렇게 하면 다른 로컬 프로세스가 Gateway를 호출하는 것을 막을 수 있습니다. + + OpenClaw는 loopback을 포함해 기본적으로 gateway 인증을 적용합니다. 일반적인 기본 경로에서는 이것이 token 인증을 의미합니다. 명시적인 인증 경로가 구성되지 않으면 gateway 시작 시 token 모드로 결정되고 자동 생성된 token을 `gateway.auth.token`에 저장하므로, **로컬 WS 클라이언트도 인증해야 합니다**. 이는 다른 로컬 프로세스가 Gateway를 호출하지 못하게 막습니다. - 다른 인증 경로를 원한다면 비밀번호 모드(또는 non-loopback ID 인식 reverse proxy의 경우 `trusted-proxy`)를 명시적으로 선택할 수 있습니다. loopback을 **정말로** 개방하고 싶다면 config에 `gateway.auth.mode: "none"`을 명시적으로 설정하세요. Doctor는 언제든 토큰을 생성해 줄 수 있습니다: `openclaw doctor --generate-gateway-token`. + 다른 인증 경로를 원한다면 password 모드를 명시적으로 선택할 수 있고(또는 loopback이 아닌 ID 인식 reverse proxy의 경우 `trusted-proxy`), **정말로** 열린 loopback을 원한다면 config에 `gateway.auth.mode: "none"`을 명시적으로 설정하세요. Doctor는 언제든 token을 생성해 줄 수 있습니다: `openclaw doctor --generate-gateway-token`. - - Gateway는 config를 감시하며 hot-reload를 지원합니다. + + Gateway는 config를 감시하며 hot-reload를 지원합니다: - `gateway.reload.mode: "hybrid"`(기본값): 안전한 변경은 hot-apply, 중요한 변경은 재시작 - - `hot`, `restart`, `off`도 지원됨 + - `hot`, `restart`, `off`도 지원됩니다 - - config에서 `cli.banner.taglineMode`를 설정하세요. + + config에서 `cli.banner.taglineMode`를 설정하세요: ```json5 { @@ -1543,19 +1552,19 @@ x-i18n: - `off`: 태그라인 텍스트를 숨기지만 배너 제목/버전 줄은 유지합니다. - `default`: 항상 `All your chats, one OpenClaw.`를 사용합니다. - - `random`: 재미있거나 계절성 있는 태그라인을 순환합니다(기본 동작). - - 배너 자체를 완전히 숨기려면 env `OPENCLAW_HIDE_BANNER=1`을 설정하세요. + - `random`: 돌아가며 표시되는 재미있는/계절성 태그라인(기본 동작). + - 배너 자체를 전혀 표시하지 않으려면 env `OPENCLAW_HIDE_BANNER=1`을 설정하세요. - - `web_fetch`는 API 키 없이 작동합니다. `web_search`는 선택한 - provider에 따라 달라집니다. + + `web_fetch`는 API 키 없이 동작합니다. `web_search`는 선택한 + provider에 따라 달라집니다: - Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity, Tavily 같은 API 기반 provider는 일반적인 API 키 설정이 필요합니다. - - Ollama Web Search는 키가 필요 없지만, 구성된 Ollama host를 사용하며 `ollama signin`이 필요합니다. - - DuckDuckGo는 키가 필요 없지만 비공식 HTML 기반 통합입니다. - - SearXNG는 키가 필요 없고 self-host할 수 있습니다. `SEARXNG_BASE_URL` 또는 `plugins.entries.searxng.config.webSearch.baseUrl`을 구성하세요. + - Ollama Web Search는 키가 필요 없지만, 구성된 Ollama 호스트를 사용하며 `ollama signin`이 필요합니다. + - DuckDuckGo는 키가 필요 없지만, 비공식 HTML 기반 통합입니다. + - SearXNG는 키가 필요 없고/self-hosted 방식이며, `SEARXNG_BASE_URL` 또는 `plugins.entries.searxng.config.webSearch.baseUrl`을 구성하세요. **권장:** `openclaw configure --section web`를 실행하고 provider를 선택하세요. 환경 변수 대안: @@ -1593,7 +1602,7 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // 선택 사항, 자동 감지를 원하면 생략 + provider: "firecrawl", // 선택 사항; 자동 감지를 원하면 생략 }, }, }, @@ -1601,57 +1610,58 @@ x-i18n: ``` provider별 웹 검색 config는 이제 `plugins.entries..config.webSearch.*` 아래에 있습니다. - 레거시 `tools.web.search.*` provider 경로도 호환성을 위해 일시적으로 계속 로드되지만, 새 config에는 사용하지 않아야 합니다. - Firecrawl 웹 fetch fallback config는 `plugins.entries.firecrawl.config.webFetch.*` 아래에 있습니다. + 레거시 `tools.web.search.*` provider 경로도 호환성을 위해 일시적으로 계속 로드되지만, 새 config에는 사용하지 말아야 합니다. + Firecrawl 웹 가져오기 대체 config는 `plugins.entries.firecrawl.config.webFetch.*` 아래에 있습니다. 참고: - allowlist를 사용한다면 `web_search`/`web_fetch`/`x_search` 또는 `group:web`를 추가하세요. - - `web_fetch`는 기본적으로 활성화되어 있습니다(명시적으로 비활성화하지 않은 경우). - - `tools.web.fetch.provider`를 생략하면 OpenClaw는 사용 가능한 자격 증명에서 준비된 첫 fetch fallback provider를 자동 감지합니다. 현재 번들된 provider는 Firecrawl입니다. + - `web_fetch`는 기본적으로 활성화되어 있습니다(명시적으로 비활성화하지 않는 한). + - `tools.web.fetch.provider`를 생략하면, OpenClaw는 사용 가능한 자격 증명에서 준비된 첫 번째 가져오기 대체 provider를 자동 감지합니다. 현재 번들 provider는 Firecrawl입니다. - 데몬은 `~/.openclaw/.env`(또는 서비스 환경)에서 env vars를 읽습니다. 문서: [웹 도구](/ko/tools/web). - - `config.apply`는 **전체 config**를 교체합니다. 부분 객체를 보내면 다른 모든 항목이 제거됩니다. + + `config.apply`는 **전체 config**를 교체합니다. 부분 객체를 보내면 + 나머지는 모두 제거됩니다. 복구 방법: - 백업(git 또는 복사해 둔 `~/.openclaw/openclaw.json`)에서 복원하세요. - - 백업이 없다면 `openclaw doctor`를 다시 실행하고 채널/모델을 다시 구성하세요. - - 예상치 못한 동작이었다면 버그를 신고하고 마지막으로 알고 있던 config 또는 백업을 포함하세요. - - 로컬 코딩 에이전트가 로그나 기록을 바탕으로 작동하는 config를 재구성할 수 있는 경우가 많습니다. + - 백업이 없다면 `openclaw doctor`를 다시 실행하고 channels/models를 다시 구성하세요. + - 예상치 못한 일이었다면 버그를 등록하고 마지막으로 알고 있던 config 또는 백업을 포함하세요. + - 로컬 코딩 agent는 로그나 기록을 바탕으로 동작하는 config를 다시 구성할 수 있는 경우가 많습니다. 피하는 방법: - 작은 변경에는 `openclaw config set`을 사용하세요. - 대화형 편집에는 `openclaw configure`를 사용하세요. - - 정확한 경로나 필드 형태가 확실하지 않다면 먼저 `config.schema.lookup`을 사용하세요. 얕은 스키마 노드와 즉시 하위 항목 요약을 반환하므로 drill-down에 도움이 됩니다. + - 정확한 경로나 필드 형태가 확실하지 않다면 먼저 `config.schema.lookup`을 사용하세요. 얕은 스키마 노드와 즉시 하위 항목 요약을 반환하므로 단계적으로 확인할 수 있습니다. - 부분 RPC 편집에는 `config.patch`를 사용하고, `config.apply`는 전체 config 교체에만 사용하세요. - - 에이전트 실행에서 owner-only `gateway` tool을 사용 중이라면, 여전히 `tools.exec.ask` / `tools.exec.security`에 대한 쓰기(동일한 보호된 exec 경로로 정규화되는 레거시 `tools.bash.*` 별칭 포함)는 거부됩니다. + - agent 실행에서 owner-only `gateway` 도구를 사용 중이라면, `tools.exec.ask` / `tools.exec.security`에 대한 쓰기(같은 보호된 exec 경로로 정규화되는 레거시 `tools.bash.*` 별칭 포함)는 여전히 거부됩니다. 문서: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/ko/gateway/doctor). - 일반적인 패턴은 **하나의 Gateway**(예: Raspberry Pi)와 **Nodes**, **에이전트**를 함께 사용하는 것입니다. + 일반적인 패턴은 **하나의 Gateway**(예: Raspberry Pi)와 **Nodes** 및 **Agents**를 함께 사용하는 것입니다: - - **Gateway(중앙):** 채널(Signal/WhatsApp), 라우팅, 세션을 소유 - - **Nodes(기기):** Mac/iOS/Android가 주변 장치처럼 연결되어 로컬 도구(`system.run`, `canvas`, `camera`)를 노출 - - **에이전트(워커):** 특수 역할(예: "Hetzner ops", "Personal data")을 위한 별도의 두뇌/workspace - - **하위 에이전트:** 병렬 처리가 필요할 때 메인 에이전트에서 백그라운드 작업을 생성 - - **TUI:** Gateway에 연결하고 에이전트/세션 전환 + - **Gateway(중앙):** channels(Signal/WhatsApp), 라우팅, sessions를 소유합니다. + - **Nodes(기기):** Mac/iOS/Android가 주변 장치처럼 연결되어 로컬 도구(`system.run`, `canvas`, `camera`)를 노출합니다. + - **Agents(워커):** 특수 역할(예: "Hetzner ops", "Personal data")을 위한 별도의 두뇌/workspace입니다. + - **Sub-agents:** 병렬 처리가 필요할 때 메인 agent에서 백그라운드 작업을 생성합니다. + - **TUI:** Gateway에 연결하고 agents/sessions를 전환합니다. - 문서: [Nodes](/ko/nodes), [원격 액세스](/ko/gateway/remote), [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [하위 에이전트](/ko/tools/subagents), [TUI](/web/tui). + 문서: [Nodes](/ko/nodes), [원격 액세스](/ko/gateway/remote), [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [Sub-agents](/ko/tools/subagents), [TUI](/web/tui). - - 예. config 옵션입니다. + + 예. config 옵션입니다: ```json5 { @@ -1664,47 +1674,47 @@ x-i18n: } ``` - 기본값은 `false`(헤드풀)입니다. 헤드리스는 일부 사이트에서 anti-bot 검사를 더 쉽게 유발할 수 있습니다. [브라우저](/ko/tools/browser)를 참고하세요. + 기본값은 `false`(headful)입니다. headless는 일부 사이트에서 anti-bot 검사를 더 쉽게 유발할 수 있습니다. [Browser](/ko/tools/browser)를 참고하세요. - 헤드리스는 **동일한 Chromium 엔진**을 사용하며 대부분의 자동화(폼, 클릭, 스크래핑, 로그인)에 작동합니다. 주요 차이점: + Headless는 **같은 Chromium 엔진**을 사용하며 대부분의 자동화(양식, 클릭, 스크래핑, 로그인)에 동작합니다. 주요 차이점: - - 눈에 보이는 브라우저 창이 없음(시각 정보가 필요하면 스크린샷 사용) - - 일부 사이트는 헤드리스 모드의 자동화에 더 엄격함(CAPTCHA, anti-bot) - 예를 들어 X/Twitter는 헤드리스 세션을 자주 차단합니다. + - 브라우저 창이 보이지 않습니다(시각 정보가 필요하면 스크린샷 사용). + - 일부 사이트는 headless 모드의 자동화에 더 엄격합니다(CAPTCHA, anti-bot). + 예를 들어 X/Twitter는 종종 headless session을 차단합니다. - `browser.executablePath`를 Brave 바이너리(또는 다른 Chromium 기반 브라우저)로 설정하고 Gateway를 다시 시작하세요. - 전체 config 예시는 [브라우저](/ko/tools/browser#use-brave-or-another-chromium-based-browser)를 참고하세요. + `browser.executablePath`를 Brave 바이너리(또는 Chromium 기반 브라우저)로 설정하고 Gateway를 다시 시작하세요. + 전체 config 예시는 [Browser](/ko/tools/browser#use-brave-or-another-chromium-based-browser)를 참고하세요. -## 원격 gateway와 Node +## 원격 gateway와 Nodes - - Telegram 메시지는 **gateway**가 처리합니다. gateway가 에이전트를 실행한 뒤에만 - Node tool이 필요할 때 **Gateway WebSocket**을 통해 Node를 호출합니다. + + Telegram 메시지는 **gateway**가 처리합니다. gateway는 agent를 실행한 뒤, + Node 도구가 필요할 때만 **Gateway WebSocket**을 통해 Nodes를 호출합니다: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes는 들어오는 provider 트래픽을 보지 않으며, node RPC 호출만 받습니다. + Nodes는 인바운드 provider 트래픽을 보지 않으며, node RPC 호출만 받습니다. - - 짧은 답: **컴퓨터를 Node로 페어링하세요**. Gateway는 다른 곳에서 실행되지만, - Gateway WebSocket을 통해 로컬 머신의 `node.*` 도구(screen, camera, system)를 호출할 수 있습니다. + + 짧은 답변: **컴퓨터를 Node로 페어링하세요**. Gateway는 다른 곳에서 실행되지만, + Gateway WebSocket을 통해 로컬 컴퓨터의 `node.*` 도구(화면, 카메라, 시스템)를 호출할 수 있습니다. 일반적인 설정: 1. 항상 켜져 있는 호스트(VPS/홈 서버)에서 Gateway를 실행합니다. - 2. Gateway host와 컴퓨터를 같은 tailnet에 둡니다. - 3. Gateway WS에 접근 가능한지 확인합니다(tailnet bind 또는 SSH tunnel). + 2. Gateway 호스트와 컴퓨터를 같은 tailnet에 둡니다. + 3. Gateway WS에 연결할 수 있는지 확인합니다(tailnet bind 또는 SSH 터널). 4. 로컬에서 macOS 앱을 열고 **Remote over SSH** 모드(또는 직접 tailnet)로 연결해 - Node로 등록되게 합니다. - 5. Gateway에서 Node를 승인합니다. + Node로 등록할 수 있게 합니다. + 5. Gateway에서 Node를 승인합니다: ```bash openclaw devices list @@ -1713,86 +1723,86 @@ x-i18n: 별도의 TCP bridge는 필요하지 않습니다. Nodes는 Gateway WebSocket을 통해 연결됩니다. - 보안 주의: macOS Node를 페어링하면 해당 머신에서 `system.run`이 가능해집니다. 신뢰할 수 있는 기기만 - 페어링하고 [보안](/ko/gateway/security)을 검토하세요. + 보안 알림: macOS Node를 페어링하면 그 기기에서 `system.run`이 가능해집니다. 신뢰하는 기기만 + 페어링하고, [보안](/ko/gateway/security)을 검토하세요. - 문서: [Nodes](/ko/nodes), [Gateway protocol](/ko/gateway/protocol), [macOS remote mode](/ko/platforms/mac/remote), [보안](/ko/gateway/security). + 문서: [Nodes](/ko/nodes), [Gateway protocol](/ko/gateway/protocol), [macOS 원격 모드](/ko/platforms/mac/remote), [보안](/ko/gateway/security). - 기본 사항부터 확인하세요. + 기본 사항을 확인하세요: - Gateway 실행 중인지: `openclaw gateway status` - Gateway 상태: `openclaw status` - - 채널 상태: `openclaw channels status` + - Channel 상태: `openclaw channels status` - 그런 다음 인증과 라우팅을 확인하세요. + 그런 다음 인증과 라우팅을 확인하세요: - - Tailscale Serve를 사용한다면 `gateway.auth.allowTailscale`가 올바르게 설정되어 있는지 확인하세요. - - SSH tunnel로 연결한다면 로컬 tunnel이 올라와 있고 올바른 포트를 가리키는지 확인하세요. + - Tailscale Serve를 사용한다면 `gateway.auth.allowTailscale`이 올바르게 설정되어 있는지 확인하세요. + - SSH 터널로 연결한다면 로컬 터널이 살아 있고 올바른 포트를 가리키는지 확인하세요. - allowlist(DM 또는 그룹)에 본인 계정이 포함되어 있는지 확인하세요. - 문서: [Tailscale](/ko/gateway/tailscale), [원격 액세스](/ko/gateway/remote), [채널](/ko/channels). + 문서: [Tailscale](/ko/gateway/tailscale), [원격 액세스](/ko/gateway/remote), [Channels](/ko/channels). - + 예. 기본 제공되는 "봇 대 봇" bridge는 없지만, 몇 가지 - 신뢰할 수 있는 방식으로 연결할 수 있습니다. + 안정적인 방법으로 연결할 수 있습니다: - **가장 간단한 방법:** 두 봇이 모두 접근할 수 있는 일반 채팅 채널(Telegram/Slack/WhatsApp)을 사용하세요. - Bot A가 Bot B에게 메시지를 보내고, Bot B는 평소처럼 응답하게 하면 됩니다. + **가장 단순한 방법:** 두 봇이 모두 접근할 수 있는 일반 채팅 channel(Telegram/Slack/WhatsApp)을 사용하세요. + Bot A가 Bot B에 메시지를 보내고, Bot B가 평소처럼 응답하게 하면 됩니다. **CLI bridge(범용):** 스크립트를 실행해 다른 Gateway를 - `openclaw agent --message ... --deliver`로 호출하고, 다른 봇이 - 듣고 있는 채팅을 대상으로 지정하세요. 한 봇이 원격 VPS에 있다면 - SSH/Tailscale을 통해 해당 원격 Gateway를 가리키도록 CLI를 설정하세요([원격 액세스](/ko/gateway/remote) 참고). + `openclaw agent --message ... --deliver`로 호출하고, 다른 봇이 듣고 있는 채팅을 대상으로 지정하세요. + 한 봇이 원격 VPS에 있다면 SSH/Tailscale을 통해 해당 원격 Gateway를 + 가리키도록 CLI를 설정하세요([원격 액세스](/ko/gateway/remote) 참고). - 예시 패턴(대상 Gateway에 접근 가능한 머신에서 실행): + 예시 패턴(대상 Gateway에 접근할 수 있는 머신에서 실행): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 팁: 두 봇이 끝없이 반복 응답하지 않도록 가드레일을 추가하세요(멘션 전용, - 채널 allowlist, 또는 "봇 메시지에는 응답하지 않기" 규칙). + 팁: 두 봇이 끝없이 루프를 돌지 않도록 보호 장치를 추가하세요(멘션 전용, channel + allowlist 또는 "봇 메시지에는 응답하지 않기" 규칙). 문서: [원격 액세스](/ko/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/ko/tools/agent-send). - - 아니요. 하나의 Gateway가 여러 에이전트를 호스팅할 수 있으며, 각 에이전트는 자체 workspace, 기본 모델, - 라우팅을 가질 수 있습니다. 이것이 일반적인 설정이며, - 에이전트마다 VPS를 하나씩 실행하는 것보다 훨씬 저렴하고 단순합니다. + + 아니요. 하나의 Gateway가 여러 agents를 호스팅할 수 있으며, 각 agent는 자체 workspace, 기본 모델, + 라우팅을 가질 수 있습니다. 이것이 일반적인 설정이며 agent마다 + VPS 하나씩 운영하는 것보다 훨씬 저렴하고 단순합니다. - 강한 격리(보안 경계)가 필요하거나 - 공유하고 싶지 않은 매우 다른 config가 필요한 경우에만 별도의 VPS를 사용하세요. 그렇지 않다면 하나의 Gateway를 유지하고 - 여러 에이전트 또는 하위 에이전트를 사용하세요. + 하드 격리(보안 경계)가 필요하거나, 공유하고 싶지 않은 매우 + 다른 config가 필요한 경우에만 별도의 VPS를 사용하세요. 그렇지 않다면 하나의 Gateway를 유지하고 + 여러 agents 또는 sub-agents를 사용하세요. - + 예. Nodes는 원격 Gateway에서 노트북에 접근하는 일급 방식이며, - 셸 접근 이상의 기능을 제공합니다. Gateway는 macOS/Linux(Windows는 WSL2)에서 실행되며 - 가볍기 때문에(작은 VPS 또는 Raspberry Pi급 장치로 충분하며 4 GB RAM이면 넉넉함), - 일반적인 설정은 항상 켜져 있는 호스트와 노트북을 Node로 두는 방식입니다. + 셸 접근 이상을 가능하게 합니다. Gateway는 macOS/Linux(Windows는 WSL2)에서 실행되며 + 가볍기 때문에(작은 VPS나 Raspberry Pi급 장치로 충분하며 4GB RAM이면 넉넉함), + 항상 켜진 호스트와 노트북을 Node로 두는 구성이 일반적입니다. - - **인바운드 SSH가 필요 없음.** Nodes는 Gateway WebSocket으로 아웃바운드 연결하고 기기 페어링을 사용합니다. - - **더 안전한 실행 제어.** `system.run`은 해당 노트북의 Node allowlist/승인으로 제어됩니다. + - **인바운드 SSH가 필요 없습니다.** Nodes는 Gateway WebSocket으로 아웃바운드 연결하고 기기 페어링을 사용합니다. + - **더 안전한 실행 제어.** `system.run`은 해당 노트북의 node allowlist/승인으로 제어됩니다. - **더 많은 기기 도구.** Nodes는 `system.run` 외에도 `canvas`, `camera`, `screen`을 노출합니다. - - **로컬 브라우저 자동화.** Gateway는 VPS에 두고, 노트북의 node host를 통해 로컬에서 Chrome을 실행하거나, 호스트의 Chrome MCP를 통해 로컬 Chrome에 연결할 수 있습니다. + - **로컬 브라우저 자동화.** Gateway는 VPS에 두고, 노트북의 node 호스트를 통해 로컬에서 Chrome을 실행하거나, Chrome MCP를 통해 호스트의 로컬 Chrome에 연결할 수 있습니다. - SSH는 임시 셸 접근에는 괜찮지만, 지속적인 에이전트 워크플로와 + SSH는 임시 셸 접근에는 괜찮지만, 지속적인 agent 워크플로와 기기 자동화에는 Nodes가 더 단순합니다. - 문서: [Nodes](/ko/nodes), [Nodes CLI](/cli/nodes), [브라우저](/ko/tools/browser). + 문서: [Nodes](/ko/nodes), [Nodes CLI](/cli/nodes), [Browser](/ko/tools/browser). - - 아니요. 의도적으로 격리된 프로필을 실행하는 경우가 아니라면(참고: [여러 gateway](/ko/gateway/multiple-gateways)) 호스트당 **하나의 gateway**만 실행해야 합니다. Nodes는 gateway에 연결되는 주변 장치입니다(iOS/Android Node 또는 메뉴바 앱의 macOS "node mode"). 헤드리스 node host와 CLI 제어는 [Node host CLI](/cli/node)를 참고하세요. + + 아니요. 의도적으로 격리된 프로필을 실행하는 경우가 아니라면(참고: [여러 gateway](/ko/gateway/multiple-gateways)) 호스트당 **하나의 gateway**만 실행해야 합니다. Nodes는 gateway에 연결되는 주변 장치입니다(iOS/Android Nodes, 또는 메뉴 막대 앱의 macOS "node mode"). headless node 호스트와 CLI 제어는 [Node host CLI](/cli/node)를 참고하세요. `gateway`, `discovery`, `canvasHost` 변경에는 전체 재시작이 필요합니다. @@ -1803,13 +1813,13 @@ x-i18n: - `config.schema.lookup`: 쓰기 전에 하나의 config 하위 트리를 얕은 스키마 노드, 일치하는 UI 힌트, 즉시 하위 항목 요약과 함께 검사 - `config.get`: 현재 스냅샷 + 해시 가져오기 - - `config.patch`: 안전한 부분 업데이트(대부분의 RPC 편집에 권장). 가능하면 hot-reload하고 필요하면 재시작 - - `config.apply`: 전체 config를 검증하고 교체. 가능하면 hot-reload하고 필요하면 재시작 - - owner-only `gateway` 런타임 tool은 여전히 `tools.exec.ask` / `tools.exec.security` 재작성을 거부합니다. 레거시 `tools.bash.*` 별칭은 동일한 보호된 exec 경로로 정규화됩니다 + - `config.patch`: 안전한 부분 업데이트(대부분의 RPC 편집에 권장); 가능하면 hot-reload하고 필요 시 재시작 + - `config.apply`: 전체 config를 검증 후 교체; 가능하면 hot-reload하고 필요 시 재시작 + - owner-only `gateway` 런타임 도구는 여전히 `tools.exec.ask` / `tools.exec.security` 재작성을 거부합니다. 레거시 `tools.bash.*` 별칭은 같은 보호된 exec 경로로 정규화됩니다 - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1821,7 +1831,7 @@ x-i18n: - + 최소 단계: 1. **VPS에 설치 + 로그인** @@ -1832,48 +1842,48 @@ x-i18n: ``` 2. **Mac에 설치 + 로그인** - - Tailscale 앱을 사용해 같은 tailnet에 로그인합니다. + - Tailscale 앱을 사용하고 같은 tailnet에 로그인하세요. 3. **MagicDNS 활성화(권장)** - - Tailscale 관리 콘솔에서 MagicDNS를 활성화해 VPS가 안정적인 이름을 갖게 합니다. - 4. **tailnet 호스트명 사용** + - Tailscale 관리자 콘솔에서 MagicDNS를 활성화해 VPS가 안정적인 이름을 갖도록 하세요. + 4. **tailnet 호스트 이름 사용** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` - SSH 없이 Control UI를 사용하려면 VPS에서 Tailscale Serve를 사용하세요. + SSH 없이 Control UI를 사용하려면 VPS에서 Tailscale Serve를 사용하세요: ```bash openclaw gateway --tailscale serve ``` - 이렇게 하면 gateway는 loopback에 바인드된 상태를 유지하면서 Tailscale을 통해 HTTPS로 노출됩니다. [Tailscale](/ko/gateway/tailscale)을 참고하세요. + 이렇게 하면 gateway는 loopback에 바인드된 상태를 유지하면서 Tailscale을 통해 HTTPS를 노출합니다. [Tailscale](/ko/gateway/tailscale)을 참고하세요. - + Serve는 **Gateway Control UI + WS**를 노출합니다. Nodes는 같은 Gateway WS 엔드포인트를 통해 연결됩니다. 권장 설정: 1. **VPS와 Mac이 같은 tailnet에 있는지 확인합니다**. - 2. **macOS 앱을 Remote mode로 사용합니다**(SSH 대상은 tailnet 호스트명이어도 됩니다). + 2. **Remote mode에서 macOS 앱을 사용합니다**(SSH 대상은 tailnet 호스트 이름이어도 됨). 앱이 Gateway 포트를 터널링하고 Node로 연결합니다. - 3. gateway에서 Node를 승인합니다. + 3. **gateway에서 Node를 승인합니다**: ```bash openclaw devices list openclaw devices approve ``` - 문서: [Gateway protocol](/ko/gateway/protocol), [Discovery](/ko/gateway/discovery), [macOS remote mode](/ko/platforms/mac/remote). + 문서: [Gateway protocol](/ko/gateway/protocol), [Discovery](/ko/gateway/discovery), [macOS 원격 모드](/ko/platforms/mac/remote). - 두 번째 노트북에서 필요한 것이 **로컬 도구**(screen/camera/exec)뿐이라면 - **Node**로 추가하세요. 그러면 단일 Gateway를 유지할 수 있고 config 중복도 피할 수 있습니다. 로컬 Node 도구는 - 현재 macOS 전용이지만, 다른 OS로도 확장할 계획이 있습니다. + 두 번째 노트북에서 **로컬 도구**(screen/camera/exec)만 필요하다면 + **Node**로 추가하세요. 그러면 Gateway를 하나로 유지할 수 있고 중복 config도 피할 수 있습니다. 로컬 node 도구는 + 현재 macOS 전용이지만, 앞으로 다른 OS로도 확장할 계획입니다. - 강한 격리나 완전히 분리된 두 개의 봇이 필요한 경우에만 두 번째 Gateway를 설치하세요. + **강한 격리**나 완전히 분리된 두 개의 봇이 필요한 경우에만 두 번째 Gateway를 설치하세요. 문서: [Nodes](/ko/nodes), [Nodes CLI](/cli/nodes), [여러 gateway](/ko/gateway/multiple-gateways). @@ -1884,14 +1894,14 @@ x-i18n: - OpenClaw는 부모 프로세스(셸, launchd/systemd, CI 등)에서 env vars를 읽고, 추가로 다음도 로드합니다. + OpenClaw는 부모 프로세스(셸, launchd/systemd, CI 등)에서 env vars를 읽고, 추가로 다음도 로드합니다: - 현재 작업 디렉터리의 `.env` - - `~/.openclaw/.env`(즉 `$OPENCLAW_STATE_DIR/.env`)의 전역 fallback `.env` + - `~/.openclaw/.env`(즉 `$OPENCLAW_STATE_DIR/.env`)의 전역 대체 `.env` - 어느 `.env` 파일도 기존 env vars를 덮어쓰지 않습니다. + 두 `.env` 파일 모두 기존 env vars를 덮어쓰지 않습니다. - config에 인라인 env vars를 정의할 수도 있습니다(프로세스 env에 없을 때만 적용됨). + config에 인라인 env vars를 정의할 수도 있습니다(프로세스 env에 없을 때만 적용): ```json5 { @@ -1906,11 +1916,11 @@ x-i18n: - - 흔한 해결책은 두 가지입니다. + + 일반적인 해결책 두 가지: - 1. 누락된 키를 `~/.openclaw/.env`에 넣어, 서비스가 셸 env를 상속하지 않더라도 읽히게 하세요. - 2. 셸 import를 활성화합니다(선택적 편의 기능). + 1. 누락된 키를 `~/.openclaw/.env`에 넣어 서비스가 셸 env를 상속하지 않더라도 읽히게 합니다. + 2. 셸 가져오기 활성화(선택적 편의 기능): ```json5 { @@ -1923,52 +1933,52 @@ x-i18n: } ``` - 이렇게 하면 로그인 셸을 실행하고 예상되는 누락 키만 가져옵니다(덮어쓰지 않음). env var 동등값: + 이렇게 하면 로그인 셸을 실행해 예상된 누락 키만 가져옵니다(절대 덮어쓰지 않음). 대응 env var: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status`는 **shell env import**가 활성화되어 있는지를 보고합니다. "Shell env: off"는 - env vars가 없다는 뜻이 아니라, OpenClaw가 - 로그인 셸을 자동으로 로드하지 않는다는 뜻입니다. + + `openclaw models status`는 **shell env 가져오기**가 활성화되어 있는지 보고합니다. "Shell env: off"는 + env vars가 없다는 뜻이 아니라, OpenClaw가 로그인 셸을 + 자동으로 로드하지 않는다는 뜻입니다. Gateway가 서비스(launchd/systemd)로 실행되면 셸 - 환경을 상속하지 않습니다. 다음 중 하나로 해결하세요. + 환경을 상속하지 않습니다. 다음 중 하나로 해결하세요: - 1. 토큰을 `~/.openclaw/.env`에 넣습니다. + 1. token을 `~/.openclaw/.env`에 넣습니다: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. 또는 shell import를 활성화합니다(`env.shellEnv.enabled: true`). - 3. 또는 config의 `env` 블록에 추가합니다(없을 때만 적용됨). + 2. 또는 셸 가져오기(`env.shellEnv.enabled: true`)를 활성화합니다. + 3. 또는 config의 `env` 블록에 추가합니다(없을 때만 적용). - 그런 다음 gateway를 다시 시작하고 다시 확인하세요. + 그런 다음 gateway를 다시 시작하고 다시 확인하세요: ```bash openclaw models status ``` - Copilot 토큰은 `COPILOT_GITHUB_TOKEN`에서 읽으며(`GH_TOKEN` / `GITHUB_TOKEN`도 지원). + Copilot token은 `COPILOT_GITHUB_TOKEN`에서 읽으며(`GH_TOKEN` / `GITHUB_TOKEN`도 지원). [/concepts/model-providers](/ko/concepts/model-providers) 및 [/environment](/ko/help/environment)를 참고하세요. -## 세션과 여러 채팅 +## sessions와 여러 채팅 - `/new` 또는 `/reset`을 독립된 메시지로 보내세요. [세션 관리](/ko/concepts/session)를 참고하세요. + `/new` 또는 `/reset`을 단독 메시지로 보내세요. [Session 관리](/ko/concepts/session)를 참고하세요. - - 세션은 `session.idleMinutes` 이후 만료될 수 있지만, 이는 **기본적으로 비활성화**되어 있습니다(기본값 **0**). - 유휴 만료를 사용하려면 양수 값으로 설정하세요. 활성화되면 유휴 기간 이후의 **다음** - 메시지가 해당 채팅 키에 대해 새로운 세션 ID를 시작합니다. - 이것이 전사본을 삭제하는 것은 아니며, 단지 새 세션을 시작할 뿐입니다. + + session은 `session.idleMinutes` 이후 만료될 수 있지만, 이는 **기본적으로 비활성화**되어 있습니다(기본값 **0**). + 유휴 만료를 활성화하려면 양수 값으로 설정하세요. 활성화되면 유휴 기간 이후의 **다음** + 메시지가 해당 채팅 키에 대해 새 session id를 시작합니다. + 이는 transcript를 삭제하지 않고 새 session을 시작할 뿐입니다. ```json5 { @@ -1980,35 +1990,35 @@ x-i18n: - - 예. **멀티 에이전트 라우팅**과 **하위 에이전트**를 통해 가능합니다. 하나의 조정 - 에이전트와, 각자 고유한 workspace와 모델을 가진 여러 워커 에이전트를 만들 수 있습니다. + + 예. **멀티 에이전트 라우팅**과 **sub-agents**를 통해 가능합니다. 하나의 조정자 + agent와 각자 workspaces와 모델을 가진 여러 worker agents를 만들 수 있습니다. - 다만 이는 **재미있는 실험**으로 보는 것이 가장 좋습니다. 토큰을 많이 사용하고, 흔히 - 하나의 봇을 여러 세션으로 나누어 쓰는 것보다 비효율적입니다. 우리가 - 일반적으로 상정하는 모델은, 사용자가 대화하는 하나의 봇이 있고 병렬 작업을 위해 - 서로 다른 세션을 쓰는 방식입니다. 이 봇은 필요할 때 하위 에이전트를 생성할 수도 있습니다. + 다만 이것은 **재미있는 실험**으로 보는 것이 가장 적절합니다. 토큰을 많이 쓰고, + 별도 sessions를 가진 하나의 봇을 쓰는 것보다 비효율적인 경우가 많습니다. 우리가 + 상정하는 일반적인 모델은 하나의 봇과 대화하되, 병렬 작업을 위해 다른 sessions를 사용하는 방식입니다. 그 + 봇은 필요할 때 sub-agents도 생성할 수 있습니다. - 문서: [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [하위 에이전트](/ko/tools/subagents), [Agents CLI](/cli/agents). + 문서: [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [Sub-agents](/ko/tools/subagents), [Agents CLI](/cli/agents). - - 세션 컨텍스트는 모델 윈도우에 의해 제한됩니다. 긴 채팅, 큰 도구 출력, 많은 - 파일은 Compaction 또는 잘림을 유발할 수 있습니다. + + session 컨텍스트는 모델 창 크기에 의해 제한됩니다. 긴 채팅, 큰 도구 출력 또는 많은 + 파일은 Compaction이나 잘림을 유발할 수 있습니다. 도움이 되는 방법: - 봇에게 현재 상태를 요약해 파일에 기록하라고 요청하세요. - - 긴 작업 전에는 `/compact`를, 주제를 바꿀 때는 `/new`를 사용하세요. - - 중요한 컨텍스트는 workspace에 보관하고 봇에게 다시 읽게 하세요. - - 긴 작업이나 병렬 작업에는 하위 에이전트를 사용해 메인 채팅을 더 작게 유지하세요. - - 이런 일이 자주 발생하면 더 큰 컨텍스트 윈도우를 가진 모델을 선택하세요. + - 긴 작업 전에 `/compact`를 사용하고, 주제를 바꿀 때는 `/new`를 사용하세요. + - 중요한 컨텍스트는 workspace에 두고 봇에게 다시 읽게 하세요. + - 메인 채팅을 더 작게 유지하려면 긴 작업이나 병렬 작업에 sub-agents를 사용하세요. + - 이런 일이 자주 발생한다면 더 큰 컨텍스트 창을 가진 모델을 선택하세요. - reset 명령을 사용하세요. + reset 명령을 사용하세요: ```bash openclaw reset @@ -2020,7 +2030,7 @@ x-i18n: openclaw reset --scope full --yes --non-interactive ``` - 그런 다음 설정을 다시 실행하세요. + 그런 다음 설정을 다시 실행하세요: ```bash openclaw onboard --install-daemon @@ -2028,24 +2038,24 @@ x-i18n: 참고: - - 기존 config가 있으면 온보딩에서도 **Reset**을 제공합니다. [온보딩(CLI)](/ko/start/wizard)을 참고하세요. - - 프로필(`--profile` / `OPENCLAW_PROFILE`)을 사용했다면 각 state dir를 초기화하세요(기본값은 `~/.openclaw-`). - - 개발용 reset: `openclaw gateway --dev --reset`(dev 전용, dev config + credentials + sessions + workspace를 삭제). + - 온보딩은 기존 config를 발견하면 **Reset**도 제공합니다. [온보딩(CLI)](/ko/start/wizard)를 참고하세요. + - 프로필(`--profile` / `OPENCLAW_PROFILE`)을 사용했다면 각 state dir을 초기화하세요(기본값은 `~/.openclaw-`). + - 개발용 초기화: `openclaw gateway --dev --reset`(개발 전용, dev config + credentials + sessions + workspace를 삭제). - - 다음 중 하나를 사용하세요. + + 다음 중 하나를 사용하세요: - - **Compact**(대화는 유지하면서 오래된 턴을 요약): + - **Compact**(대화는 유지하되 이전 turn을 요약): ``` /compact ``` - 또는 요약을 안내하려면 `/compact `. + 또는 요약을 안내하려면 `/compact `를 사용하세요. - - **Reset**(같은 채팅 키에 대해 새 세션 ID 시작): + - **Reset**(같은 채팅 키에 대해 새 session ID 생성): ``` /new @@ -2054,22 +2064,22 @@ x-i18n: 계속 발생한다면: - - 오래된 도구 출력을 정리하도록 **세션 pruning**(`agents.defaults.contextPruning`)을 활성화하거나 조정하세요. - - 더 큰 컨텍스트 윈도우를 가진 모델을 사용하세요. + - 오래된 도구 출력을 잘라내도록 **session pruning**(`agents.defaults.contextPruning`)을 활성화하거나 조정하세요. + - 더 큰 컨텍스트 창을 가진 모델을 사용하세요. - 문서: [Compaction](/ko/concepts/compaction), [세션 pruning](/ko/concepts/session-pruning), [세션 관리](/ko/concepts/session). + 문서: [Compaction](/ko/concepts/compaction), [Session pruning](/ko/concepts/session-pruning), [Session 관리](/ko/concepts/session). - 이는 provider 검증 오류입니다. 모델이 필수 `input` 없이 `tool_use` 블록을 내보냈다는 뜻입니다. 보통 세션 기록이 오래되었거나 손상되었음을 의미하며(긴 스레드나 tool/schema 변경 후 자주 발생). + 이는 provider 검증 오류입니다. 모델이 필수 `input` 없이 `tool_use` 블록을 내보냈다는 뜻입니다. 보통 session 기록이 오래되었거나 손상되었음을 의미하며(대개 긴 thread나 도구/스키마 변경 이후 발생) 그렇습니다. - 해결 방법: `/new`를 독립된 메시지로 보내 새 세션을 시작하세요. + 해결 방법: `/new`를 사용해 새 session을 시작하세요(단독 메시지). - - Heartbeat는 기본적으로 **30분마다** 실행됩니다(**OAuth 인증 사용 시 1시간**). 조정하거나 비활성화하려면: + + heartbeat는 기본적으로 **30분마다** 실행됩니다(**OAuth 인증 사용 시 1시간마다**). 조정하거나 비활성화하세요: ```json5 { @@ -2085,14 +2095,14 @@ x-i18n: `HEARTBEAT.md`가 존재하지만 사실상 비어 있는 경우(빈 줄과 `# Heading` 같은 markdown 헤더만 있는 경우), OpenClaw는 API 호출을 아끼기 위해 heartbeat 실행을 건너뜁니다. - 파일이 없으면 heartbeat는 여전히 실행되며, 모델이 무엇을 할지 결정합니다. + 파일이 없으면 heartbeat는 여전히 실행되며 모델이 무엇을 할지 결정합니다. - 에이전트별 override는 `agents.list[].heartbeat`를 사용합니다. 문서: [Heartbeat](/ko/gateway/heartbeat). + agent별 override는 `agents.list[].heartbeat`를 사용합니다. 문서: [Heartbeat](/ko/gateway/heartbeat). - 아니요. OpenClaw는 **사용자 자신의 계정**에서 실행되므로, 사용자가 해당 그룹에 있으면 OpenClaw도 볼 수 있습니다. + 아니요. OpenClaw는 **사용자 자신의 계정**에서 실행되므로, 사용자가 그룹에 있으면 OpenClaw도 그 그룹을 볼 수 있습니다. 기본적으로 그룹 응답은 발신자를 허용할 때까지 차단됩니다(`groupPolicy: "allowlist"`). 그룹 응답을 **본인만** 트리거할 수 있게 하려면: @@ -2111,7 +2121,7 @@ x-i18n: - 옵션 1(가장 빠름): 로그를 따라가면서 그룹에 테스트 메시지를 보내세요. + 방법 1(가장 빠름): 로그를 따라가면서 그룹에 테스트 메시지를 보내세요: ```bash openclaw logs --follow --json @@ -2120,60 +2130,62 @@ x-i18n: `@g.us`로 끝나는 `chatId`(또는 `from`)를 찾으세요. 예: `1234567890-1234567890@g.us`. - 옵션 2(이미 구성/allowlist된 경우): config에서 그룹을 나열합니다. + 방법 2(이미 구성/허용 목록 설정이 되어 있다면): config에서 그룹을 나열하세요: ```bash openclaw directory groups list --channel whatsapp ``` - 문서: [WhatsApp](/ko/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). + 문서: [WhatsApp](/ko/channels/whatsapp), [Directory](/cli/directory), [로그](/cli/logs). - 흔한 원인은 두 가지입니다. + 흔한 원인은 두 가지입니다: - - 멘션 gating이 켜져 있습니다(기본값). 봇을 @멘션해야 합니다(또는 `mentionPatterns`와 일치해야 함). - - `channels.whatsapp.groups`를 `"*"` 없이 구성했고, 해당 그룹이 allowlist에 없습니다. + - 멘션 게이팅이 켜져 있습니다(기본값). 봇을 @멘션해야 하며(또는 `mentionPatterns`와 일치해야 함), + - `channels.whatsapp.groups`를 `"*"` 없이 구성했고, 해당 그룹이 허용 목록에 없습니다. [그룹](/ko/channels/groups) 및 [그룹 메시지](/ko/channels/group-messages)를 참고하세요. - - 직접 채팅은 기본적으로 main 세션으로 합쳐집니다. 그룹/채널은 자체 세션 키를 가지며, Telegram 토픽 / Discord 스레드는 별도의 세션입니다. [그룹](/ko/channels/groups) 및 [그룹 메시지](/ko/channels/group-messages)를 참고하세요. + + 직접 채팅은 기본적으로 메인 session으로 합쳐집니다. 그룹/channels는 자체 session 키를 가지며, Telegram topic / Discord thread는 별도 session입니다. [그룹](/ko/channels/groups) 및 [그룹 메시지](/ko/channels/group-messages)를 참고하세요. - - 하드 제한은 없습니다. 수십 개(심지어 수백 개)도 괜찮지만, 다음을 주의하세요. + + 하드 제한은 없습니다. 수십 개(심지어 수백 개)도 괜찮지만, 다음은 주의하세요: - - **디스크 증가:** 세션 + 전사본은 `~/.openclaw/agents//sessions/` 아래에 저장됩니다. - - **토큰 비용:** 에이전트가 많을수록 동시 모델 사용량이 늘어납니다. - - **운영 오버헤드:** 에이전트별 auth profile, workspace, 채널 라우팅. + - **디스크 증가:** sessions + transcript는 `~/.openclaw/agents//sessions/` 아래에 저장됩니다. + - **토큰 비용:** agent가 많을수록 동시 모델 사용량이 증가합니다. + - **운영 오버헤드:** agent별 auth profile, workspace, channel 라우팅. 팁: - - 에이전트당 **활성** workspace를 하나 유지하세요(`agents.defaults.workspace`). - - 디스크가 커지면 오래된 세션(JSONL 또는 저장 항목)을 정리하세요. - - `openclaw doctor`를 사용해 stray workspace와 profile 불일치를 찾아내세요. + - agent마다 하나의 **활성** workspace(`agents.defaults.workspace`)를 유지하세요. + - 디스크가 커지면 오래된 sessions(JSONL 또는 저장소 항목)를 정리하세요. + - `openclaw doctor`를 사용해 흩어진 workspace와 profile 불일치를 찾아내세요. - - 예. **멀티 에이전트 라우팅**을 사용해 여러 격리된 에이전트를 실행하고, 채널/계정/peer 기준으로 들어오는 메시지를 라우팅하세요. Slack은 채널로 지원되며 특정 에이전트에 바인딩할 수 있습니다. + + 예. **멀티 에이전트 라우팅**을 사용해 여러 개의 격리된 agents를 실행하고 + channel/account/peer별로 인바운드 메시지를 라우팅하세요. Slack은 channel로 지원되며 특정 agents에 바인딩할 수 있습니다. - 브라우저 접근은 강력하지만 "사람이 할 수 있는 모든 것"을 의미하지는 않습니다. anti-bot, CAPTCHA, MFA는 - 여전히 자동화를 막을 수 있습니다. 가장 신뢰할 수 있는 브라우저 제어를 원한다면 호스트에서 로컬 Chrome MCP를 사용하거나, 실제로 브라우저를 실행하는 머신에서 CDP를 사용하세요. + 브라우저 접근은 강력하지만 "사람이 할 수 있는 모든 것"을 의미하지는 않습니다. anti-bot, CAPTCHA, MFA가 + 자동화를 여전히 막을 수 있습니다. 가장 안정적인 브라우저 제어를 원한다면 호스트에서 로컬 Chrome MCP를 사용하거나, + 실제로 브라우저를 실행하는 머신에서 CDP를 사용하세요. - 권장 설정: + 모범 설정: - - 항상 켜져 있는 Gateway host(VPS/Mac mini). - - 역할별로 하나의 에이전트(bindings). - - 해당 에이전트에 바인딩된 Slack 채널. + - 항상 켜져 있는 Gateway 호스트(VPS/Mac mini). + - 역할별 agent 하나씩(바인딩). + - 해당 agents에 바인딩된 Slack channel. - 필요 시 Chrome MCP 또는 node를 통한 로컬 브라우저. 문서: [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [Slack](/ko/channels/slack), - [브라우저](/ko/tools/browser), [Nodes](/ko/nodes). + [Browser](/ko/tools/browser), [Nodes](/ko/nodes). @@ -2182,48 +2194,48 @@ x-i18n: - OpenClaw의 기본 모델은 다음에 설정한 값입니다. + OpenClaw의 기본 모델은 다음에 설정한 값입니다: ``` agents.defaults.model.primary ``` - 모델은 `provider/model` 형식으로 참조합니다(예: `openai/gpt-5.4`). provider를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 정확한 모델 ID에 대해 고유하게 구성된 provider 일치를 시도하며, 그 이후에야 더 이상 권장되지 않는 호환 경로로 구성된 기본 provider로 fallback합니다. 해당 provider가 더 이상 구성된 기본 모델을 제공하지 않으면, 오래되어 제거된 provider 기본값을 그대로 드러내는 대신 구성된 첫 번째 provider/model로 fallback합니다. 그래도 **명시적으로** `provider/model`을 설정하는 것이 좋습니다. + 모델은 `provider/model` 형식으로 참조됩니다(예: `openai/gpt-5.4`). provider를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 해당 정확한 모델 id에 대한 고유한 구성된 provider 일치를 찾고, 마지막으로만 더 이상 권장되지 않는 호환성 경로로 구성된 기본 provider로 대체합니다. 해당 provider가 더 이상 구성된 기본 모델을 노출하지 않으면, 제거된 provider의 오래된 기본값을 표시하는 대신 첫 번째 구성된 provider/model로 대체합니다. 그래도 여전히 `provider/model`을 **명시적으로** 설정하는 것이 좋습니다. - **권장 기본값:** provider 스택에서 사용할 수 있는 최신 세대의 가장 강력한 모델을 사용하세요. - **도구 사용 가능 또는 신뢰할 수 없는 입력을 받는 에이전트의 경우:** 비용보다 모델 성능을 우선하세요. - **일상적이고 위험도가 낮은 채팅의 경우:** 더 저렴한 fallback 모델을 사용하고 에이전트 역할별로 라우팅하세요. + **권장 기본값:** provider 스택에서 사용할 수 있는 가장 강력한 최신 세대 모델을 사용하세요. + **도구 사용 가능 또는 신뢰할 수 없는 입력을 받는 agent의 경우:** 비용보다 모델 성능을 우선하세요. + **일상적이고 부담이 적은 채팅의 경우:** 더 저렴한 fallback model을 사용하고 agent 역할별로 라우팅하세요. MiniMax 전용 문서: [MiniMax](/ko/providers/minimax) 및 [로컬 모델](/ko/gateway/local-models). - 경험칙: 중요한 작업에는 **감당 가능한 가장 좋은 모델**을 사용하고, 일상적인 채팅이나 요약에는 더 저렴한 - 모델을 사용하세요. 에이전트별로 모델을 라우팅하고 하위 에이전트를 사용해 긴 작업을 - 병렬화할 수 있습니다(각 하위 에이전트는 토큰을 소비함). [모델](/ko/concepts/models)과 - [하위 에이전트](/ko/tools/subagents)를 참고하세요. + 경험칙: 중요한 작업에는 **감당 가능한 가장 좋은 모델**을 사용하고, 일상적인 + 채팅이나 요약에는 더 저렴한 모델을 사용하세요. agent별로 모델을 라우팅하고 sub-agents를 사용해 + 긴 작업을 병렬화할 수 있습니다(sub-agent마다 토큰 사용). [모델](/ko/concepts/models) 및 + [Sub-agents](/ko/tools/subagents)를 참고하세요. - 강한 경고: 더 약하거나 과도하게 양자화된 모델은 prompt - injection과 안전하지 않은 동작에 더 취약합니다. [보안](/ko/gateway/security)을 참고하세요. + 강한 경고: 더 약하거나 과도하게 양자화된 모델은 프롬프트 + 인젝션과 안전하지 않은 동작에 더 취약합니다. [보안](/ko/gateway/security)을 참고하세요. - 추가 맥락: [모델](/ko/concepts/models). + 추가 설명: [모델](/ko/concepts/models). - **모델 명령**을 사용하거나 **모델** 필드만 수정하세요. 전체 config 교체는 피하세요. + **모델 명령**을 사용하거나 **model** 필드만 편집하세요. 전체 config 교체는 피하세요. 안전한 방법: - - 채팅에서 `/model`(빠름, 세션별) + - 채팅에서 `/model`(빠름, session별) - `openclaw models set ...`(모델 config만 업데이트) - `openclaw configure --section model`(대화형) - - `~/.openclaw/openclaw.json`에서 `agents.defaults.model` 편집 + - `~/.openclaw/openclaw.json`의 `agents.defaults.model` 편집 - 전체 config를 교체할 의도가 아니라면 부분 객체로 `config.apply`를 사용하지 마세요. - RPC 편집의 경우 먼저 `config.schema.lookup`으로 검사하고 `config.patch`를 우선하세요. lookup payload는 정규화된 경로, 얕은 스키마 문서/제약 조건, 즉시 하위 항목 요약을 제공합니다. + 전체 config를 교체하려는 의도가 아니라면 부분 객체로 `config.apply`를 사용하지 마세요. + RPC 편집의 경우 먼저 `config.schema.lookup`으로 검사하고 `config.patch`를 선호하세요. lookup payload는 정규화된 경로, 얕은 스키마 문서/제약 조건, 즉시 하위 항목 요약을 제공합니다. 부분 업데이트에 사용하세요. config를 덮어썼다면 백업에서 복원하거나 `openclaw doctor`를 다시 실행해 복구하세요. @@ -2231,41 +2243,41 @@ x-i18n: - + 예. 로컬 모델에는 Ollama가 가장 쉬운 경로입니다. 가장 빠른 설정: - 1. `https://ollama.com/download`에서 Ollama를 설치합니다 - 2. `ollama pull gemma4` 같은 로컬 모델을 가져옵니다 - 3. 클라우드 모델도 원하면 `ollama signin`을 실행합니다 - 4. `openclaw onboard`를 실행하고 `Ollama`를 선택합니다 - 5. `Local` 또는 `Cloud + Local`을 선택합니다 + 1. `https://ollama.com/download`에서 Ollama를 설치 + 2. `ollama pull gemma4` 같은 로컬 모델을 가져오기 + 3. 클라우드 모델도 원한다면 `ollama signin` 실행 + 4. `openclaw onboard`를 실행하고 `Ollama` 선택 + 5. `Local` 또는 `Cloud + Local` 선택 참고: - `Cloud + Local`은 클라우드 모델과 로컬 Ollama 모델을 함께 제공합니다 - `kimi-k2.5:cloud` 같은 클라우드 모델은 로컬 pull이 필요하지 않습니다 - - 수동 전환은 `openclaw models list`와 `openclaw models set ollama/`을 사용하세요 + - 수동 전환 시 `openclaw models list`와 `openclaw models set ollama/`을 사용하세요 - 보안 참고: 더 작거나 심하게 양자화된 모델은 prompt - injection에 더 취약합니다. 도구를 사용할 수 있는 봇에는 **큰 모델**을 강력히 권장합니다. + 보안 참고: 더 작거나 심하게 양자화된 모델은 프롬프트 + 인젝션에 더 취약합니다. 도구를 사용할 수 있는 모든 봇에는 **대형 모델**을 강력히 권장합니다. 그래도 작은 모델을 원한다면 샌드박싱과 엄격한 도구 allowlist를 활성화하세요. 문서: [Ollama](/ko/providers/ollama), [로컬 모델](/ko/gateway/local-models), - [모델 제공자](/ko/concepts/model-providers), [보안](/ko/gateway/security), + [모델 provider](/ko/concepts/model-providers), [보안](/ko/gateway/security), [샌드박싱](/ko/gateway/sandboxing). - - - 이 배포들은 서로 다를 수 있고 시간이 지나며 변경될 수 있습니다. 고정된 provider 권장은 없습니다. + + - 이러한 배포는 서로 다를 수 있고 시간에 따라 바뀔 수 있으며, 고정된 provider 권장은 없습니다. - 각 gateway의 현재 런타임 설정은 `openclaw models status`로 확인하세요. - - 보안에 민감하거나 도구를 사용하는 에이전트에는 사용 가능한 최신 세대의 가장 강력한 모델을 사용하세요. + - 보안에 민감하거나 도구를 사용하는 agent에는 사용 가능한 가장 강력한 최신 세대 모델을 사용하세요. - 독립된 메시지로 `/model` 명령을 사용하세요. + `/model` 명령을 단독 메시지로 사용하세요: ``` /model sonnet @@ -2277,56 +2289,56 @@ x-i18n: /model gemini-flash-lite ``` - 이들은 기본 제공 별칭입니다. 사용자 지정 별칭은 `agents.defaults.models`를 통해 추가할 수 있습니다. + 이는 기본 제공 별칭입니다. 사용자 지정 별칭은 `agents.defaults.models`를 통해 추가할 수 있습니다. - 사용 가능한 모델은 `/model`, `/model list`, `/model status`로 확인할 수 있습니다. + 사용 가능한 모델은 `/model`, `/model list`, `/model status`로 나열할 수 있습니다. - `/model`(및 `/model list`)은 간결한 번호 선택기를 보여줍니다. 번호로 선택하세요. + `/model`(및 `/model list`)은 간결한 번호 선택기를 보여줍니다. 번호로 선택하세요: ``` /model 3 ``` - provider에 대해 특정 auth profile을 강제로 지정할 수도 있습니다(세션별). + provider에 대해 특정 auth profile을 강제로 지정할 수도 있습니다(session별): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - 팁: `/model status`는 어떤 에이전트가 활성 상태인지, 어떤 `auth-profiles.json` 파일이 사용 중인지, 다음에 어떤 auth profile이 시도될지를 보여줍니다. - 또한 가능할 경우 구성된 provider endpoint(`baseUrl`)와 API mode(`api`)도 보여줍니다. + 팁: `/model status`는 어떤 agent가 활성 상태인지, 어떤 `auth-profiles.json` 파일을 사용 중인지, 그리고 다음에 어떤 auth profile을 시도할지를 보여줍니다. + 또한 가능한 경우 구성된 provider 엔드포인트(`baseUrl`)와 API 모드(`api`)도 표시합니다. - **`@profile`로 설정한 profile pin을 해제하려면 어떻게 하나요?** + **`@profile`로 설정한 profile 고정은 어떻게 해제하나요?** - `@profile` 접미사 없이 `/model`을 다시 실행하세요. + `@profile` 접미사 없이 `/model`을 다시 실행하세요: ``` /model anthropic/claude-opus-4-6 ``` - 기본값으로 돌아가고 싶다면 `/model`에서 기본 모델을 선택하거나(`/model ` 전송) 하세요. - 어떤 auth profile이 활성 상태인지 확인하려면 `/model status`를 사용하세요. + 기본값으로 돌아가려면 `/model`에서 기본값을 선택하거나(`/model <기본 provider/model>`을 보내도 됨), + `/model status`를 사용해 어떤 auth profile이 활성 상태인지 확인하세요. - 예. 하나를 기본값으로 설정하고 필요에 따라 전환하세요. + 예. 하나를 기본값으로 두고 필요할 때 전환하세요: - - **빠른 전환(세션별):** 일상 작업에는 `/model gpt-5.4`, Codex OAuth로 코딩할 때는 `/model openai-codex/gpt-5.4`. - - **기본값 + 전환:** `agents.defaults.model.primary`를 `openai/gpt-5.4`로 설정한 다음, 코딩할 때 `openai-codex/gpt-5.4`로 전환합니다(또는 반대로). - - **하위 에이전트:** 코딩 작업을 기본 모델이 다른 하위 에이전트로 라우팅합니다. + - **빠른 전환(session별):** 일상 작업에는 `/model gpt-5.4`, Codex OAuth를 통한 코딩에는 `/model openai-codex/gpt-5.4`. + - **기본값 + 전환:** `agents.defaults.model.primary`를 `openai/gpt-5.4`로 설정한 뒤, 코딩할 때 `openai-codex/gpt-5.4`로 전환하세요(또는 그 반대). + - **Sub-agents:** 코딩 작업을 다른 기본 모델을 가진 sub-agent로 라우팅합니다. - [모델](/ko/concepts/models)과 [슬래시 명령](/ko/tools/slash-commands)을 참고하세요. + [모델](/ko/concepts/models) 및 [Slash 명령](/ko/tools/slash-commands)을 참고하세요. - - 세션 토글 또는 config 기본값을 사용할 수 있습니다. + + session 토글 또는 config 기본값을 사용할 수 있습니다: - - **세션별:** 세션이 `openai/gpt-5.4` 또는 `openai-codex/gpt-5.4`를 사용할 때 `/fast on`을 보냅니다. - - **모델별 기본값:** `agents.defaults.models["openai/gpt-5.4"].params.fastMode`를 `true`로 설정합니다. - - **Codex OAuth도 포함:** `openai-codex/gpt-5.4`도 사용한다면 같은 플래그를 설정합니다. + - **session별:** session이 `openai/gpt-5.4` 또는 `openai-codex/gpt-5.4`를 사용할 때 `/fast on`을 보내세요. + - **모델별 기본값:** `agents.defaults.models["openai/gpt-5.4"].params.fastMode`를 `true`로 설정하세요. + - **Codex OAuth도 포함:** `openai-codex/gpt-5.4`도 사용한다면 거기에도 같은 플래그를 설정하세요. 예시: @@ -2351,41 +2363,41 @@ x-i18n: } ``` - OpenAI에서는 fast mode가 지원되는 기본 Responses 요청에서 `service_tier = "priority"`로 매핑됩니다. 세션의 `/fast` override가 config 기본값보다 우선합니다. + OpenAI에서 fast mode는 지원되는 기본 Responses 요청에서 `service_tier = "priority"`로 매핑됩니다. session `/fast` override가 config 기본값보다 우선합니다. - [Thinking and fast mode](/ko/tools/thinking)와 [OpenAI fast mode](/ko/providers/openai#openai-fast-mode)를 참고하세요. + [Thinking 및 fast mode](/ko/tools/thinking)와 [OpenAI fast mode](/ko/providers/openai#openai-fast-mode)를 참고하세요. - - `agents.defaults.models`가 설정되어 있으면, 이는 `/model`과 모든 - 세션 override의 **allowlist**가 됩니다. 그 목록에 없는 모델을 선택하면 다음이 반환됩니다. + + `agents.defaults.models`가 설정되어 있으면 이는 `/model`과 모든 + session override의 **allowlist**가 됩니다. 이 목록에 없는 모델을 선택하면 다음이 반환됩니다: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` - 이 오류는 일반 응답 **대신** 반환됩니다. 해결 방법: 모델을 + 이 오류는 정상 응답 **대신** 반환됩니다. 해결 방법: 해당 모델을 `agents.defaults.models`에 추가하거나, allowlist를 제거하거나, `/model list`에서 모델을 선택하세요. 이는 **provider가 구성되지 않았음**을 의미합니다(MiniMax provider config 또는 auth - profile을 찾지 못함). 따라서 모델을 해석할 수 없습니다. + profile을 찾지 못함). 그래서 모델을 해결할 수 없습니다. - 확인 목록: + 해결 체크리스트: - 1. 현재 OpenClaw 릴리스로 업그레이드하거나 소스의 `main`에서 실행한 뒤 gateway를 재시작하세요. - 2. MiniMax가 구성되어 있는지(마법사 또는 JSON), 또는 MiniMax auth가 - env/auth profile에 존재해 일치하는 provider가 주입될 수 있는지 확인하세요 - (`minimax`용 `MINIMAX_API_KEY`, `minimax-portal`용 `MINIMAX_OAUTH_TOKEN` 또는 저장된 MiniMax + 1. 최신 OpenClaw 릴리스로 업그레이드하거나(또는 소스 `main`에서 실행한 뒤) gateway를 다시 시작하세요. + 2. MiniMax가 구성되어 있는지(wizard 또는 JSON), 또는 MiniMax 인증이 + env/auth profile에 존재하여 일치하는 provider가 주입될 수 있는지 확인하세요 + (`minimax`에는 `MINIMAX_API_KEY`, `minimax-portal`에는 `MINIMAX_OAUTH_TOKEN` 또는 저장된 MiniMax OAuth). - 3. auth 경로에 맞는 정확한 모델 ID(대소문자 구분)를 사용하세요: - API 키 설정의 경우 `minimax/MiniMax-M2.7` 또는 `minimax/MiniMax-M2.7-highspeed`, - OAuth 설정의 경우 `minimax-portal/MiniMax-M2.7` / + 3. 인증 경로에 맞는 정확한 모델 id(대소문자 구분)를 사용하세요: + API 키 설정에는 `minimax/MiniMax-M2.7` 또는 `minimax/MiniMax-M2.7-highspeed`, + OAuth 설정에는 `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed`. - 4. 다음을 실행하세요. + 4. 다음을 실행하세요: ```bash openclaw models list @@ -2393,15 +2405,15 @@ x-i18n: 그리고 목록에서 선택하세요(또는 채팅에서 `/model list`). - [MiniMax](/ko/providers/minimax)와 [모델](/ko/concepts/models)를 참고하세요. + [MiniMax](/ko/providers/minimax) 및 [모델](/ko/concepts/models)을 참고하세요. - 예. **MiniMax를 기본값**으로 사용하고, 필요할 때 **세션별로** 모델을 전환하세요. - fallback은 **오류**용이지 "어려운 작업"용이 아니므로, `/model` 또는 별도 에이전트를 사용하세요. + 예. **MiniMax를 기본값**으로 사용하고 필요할 때 **session별로** + 모델을 전환하세요. fallback은 **오류용**이지 "어려운 작업"용이 아니므로 `/model` 또는 별도 agent를 사용하세요. - **옵션 A: 세션별 전환** + **옵션 A: session별 전환** ```json5 { @@ -2424,18 +2436,18 @@ x-i18n: /model gpt ``` - **옵션 B: 별도 에이전트** + **옵션 B: 별도 agents** - - 에이전트 A 기본값: MiniMax - - 에이전트 B 기본값: OpenAI - - 에이전트별로 라우팅하거나 `/agent`로 전환 + - Agent A 기본값: MiniMax + - Agent B 기본값: OpenAI + - agent별로 라우팅하거나 `/agent`로 전환 문서: [모델](/ko/concepts/models), [멀티 에이전트 라우팅](/ko/concepts/multi-agent), [MiniMax](/ko/providers/minimax), [OpenAI](/ko/providers/openai). - 예. OpenClaw는 몇 가지 기본 단축어를 제공합니다(`agents.defaults.models`에 해당 모델이 존재할 때만 적용). + 예. OpenClaw는 몇 가지 기본 단축어를 제공합니다(`agents.defaults.models`에 해당 모델이 존재할 때만 적용됨): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2446,12 +2458,12 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - 같은 이름의 별칭을 직접 설정하면 사용자 값이 우선합니다. + 같은 이름의 별칭을 직접 설정하면, 사용자 값이 우선합니다. - 별칭은 `agents.defaults.models..alias`에서 옵니다. 예시: + 별칭은 `agents.defaults.models..alias`에서 가져옵니다. 예시: ```json5 { @@ -2468,7 +2480,7 @@ x-i18n: } ``` - 그런 다음 `/model sonnet`(또는 지원되는 경우 `/`)이 해당 모델 ID로 해석됩니다. + 그러면 `/model sonnet`(또는 지원되는 경우 `/`)이 해당 모델 ID로 해석됩니다. @@ -2501,11 +2513,12 @@ x-i18n: } ``` - provider/model을 참조했는데 필요한 provider 키가 없으면 런타임 auth 오류가 발생합니다(예: `No API key found for provider "zai"`). + provider/model을 참조했는데 필요한 provider 키가 없으면 런타임 인증 오류가 발생합니다(예: `No API key found for provider "zai"`). - **새 에이전트를 추가한 후 provider에 대한 API 키를 찾을 수 없다고 나오는 경우** + **새 agent를 추가한 뒤 No API key found for provider가 표시됨** - 이는 보통 **새 에이전트**의 auth 저장소가 비어 있음을 의미합니다. auth는 에이전트별이며 다음 위치에 저장됩니다. + 이는 보통 **새 agent**의 auth 저장소가 비어 있다는 뜻입니다. auth는 agent별이며 + 다음 위치에 저장됩니다: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2513,117 +2526,118 @@ x-i18n: 해결 방법: - - `openclaw agents add `를 실행하고 마법사에서 auth를 구성합니다. - - 또는 메인 에이전트의 `agentDir`에 있는 `auth-profiles.json`을 새 에이전트의 `agentDir`로 복사합니다. + - `openclaw agents add `를 실행하고 wizard에서 auth를 구성합니다. + - 또는 메인 agent의 `agentDir`에서 `auth-profiles.json`을 새 agent의 `agentDir`로 복사합니다. - 여러 에이전트에서 `agentDir`를 재사용하지 마세요. auth/세션 충돌이 발생합니다. + agents 간에 `agentDir`를 재사용하지 마세요. auth/session 충돌이 발생합니다. -## 모델 페일오버와 "All models failed" +## 모델 장애 조치와 "All models failed" - - 페일오버는 두 단계로 이루어집니다. + + 장애 조치는 두 단계로 일어납니다: - 1. 같은 provider 내에서 **auth profile 순환** + 1. 같은 provider 내의 **auth profile 순환** 2. `agents.defaults.model.fallbacks`의 다음 모델로 **모델 fallback** - 실패하는 profile에는 cooldown(지수 백오프)이 적용되므로, provider가 rate limit에 걸리거나 일시적으로 실패해도 OpenClaw는 계속 응답할 수 있습니다. + 실패하는 profile에는 쿨다운이 적용되며(지수 백오프), provider에 속도 제한이 걸리거나 일시적으로 실패해도 OpenClaw는 계속 응답할 수 있습니다. - rate-limit 버킷에는 단순한 `429` 응답 외의 것도 포함됩니다. OpenClaw는 + 속도 제한 버킷에는 단순한 `429` 응답보다 더 많은 경우가 포함됩니다. OpenClaw는 `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted`, 그리고 주기적인 - 사용량 윈도우 제한(`weekly/monthly limit reached`) 같은 메시지도 - 페일오버할 가치가 있는 rate limit로 취급합니다. + 사용량 창 제한(`weekly/monthly limit reached`) 같은 메시지도 장애 조치 대상 + 속도 제한으로 취급합니다. - 일부 과금 관련 응답은 `402`가 아니며, 일부 HTTP `402` - 응답도 일시적 버킷에 남아 있습니다. provider가 - `401`이나 `403`에서 명시적인 과금 관련 텍스트를 반환하면 OpenClaw는 여전히 이를 - 과금 레인에 둘 수 있지만, provider별 텍스트 매처는 해당 provider 범위 내에만 유지됩니다 - (예: OpenRouter `Key limit exceeded`). 반대로 `402` - 메시지가 재시도 가능한 사용량 윈도우나 + 일부 과금처럼 보이는 응답은 `402`가 아니며, 일부 HTTP `402` + 응답도 그 일시적 버킷에 남습니다. provider가 + `401` 또는 `403`에서 명시적인 과금 텍스트를 반환하면 OpenClaw는 이를 여전히 + 과금 경로에 둘 수 있지만, provider별 텍스트 매처는 해당 provider 범위 안에만 + 머뭅니다(예: OpenRouter `Key limit exceeded`). 대신 `402` + 메시지가 재시도 가능한 사용량 창 또는 조직/workspace 지출 한도(`daily limit reached, resets tomorrow`, - `organization spending limit exceeded`)처럼 보이면 OpenClaw는 이를 - 장기적인 과금 비활성화가 아닌 `rate_limit`로 취급합니다. + `organization spending limit exceeded`)처럼 보이면, OpenClaw는 이를 + 장기 과금 비활성화가 아니라 `rate_limit`로 취급합니다. - 컨텍스트 초과 오류는 다릅니다. 다음과 같은 시그니처: + 컨텍스트 초과 오류는 다릅니다. 다음과 같은 시그니처는 `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, 또는 `ollama error: context length - exceeded`는 모델 fallback으로 넘어가지 않고 Compaction/재시도 경로에 남습니다. + exceeded`는 모델 fallback을 진행하는 대신 + Compaction/재시도 경로에 머뭅니다. - 일반적인 서버 오류 텍스트는 의도적으로 "unknown/error가 들어간 모든 것"보다 더 좁게 처리됩니다. OpenClaw는 - Anthropic의 순수 `An unknown error occurred`, OpenRouter의 순수 - `Provider returned error`, `Unhandled stop reason: - error` 같은 stop-reason 오류, 일시적인 서버 텍스트가 포함된 JSON `api_error` payload + 일반적인 서버 오류 텍스트는 의도적으로 "unknown/error가 들어간 모든 것"보다 + 더 좁게 다룹니다. OpenClaw는 Anthropic의 단순한 `An unknown error occurred`, + OpenRouter의 단순한 `Provider returned error`, `Unhandled stop reason: + error` 같은 stop-reason 오류, 일시적인 서버 텍스트를 포함한 JSON `api_error` payload (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`), 그리고 `ModelNotReadyException` 같은 provider busy 오류를 - provider 컨텍스트가 일치할 때 페일오버할 가치가 있는 timeout/과부하 신호로 취급합니다. - 반면 일반적인 내부 fallback 텍스트인 `LLM request failed with an unknown - error.`는 보수적으로 처리되며, 그 자체만으로는 모델 fallback을 유발하지 않습니다. + error`), 그리고 `ModelNotReadyException` 같은 provider 바쁨 오류를 + provider 컨텍스트가 일치할 때 장애 조치 대상 timeout/과부하 신호로 취급합니다. + `LLM request failed with an unknown + error.` 같은 일반 내부 fallback 텍스트는 보수적으로 유지되며, 그 자체만으로는 모델 fallback을 트리거하지 않습니다. - - 시스템이 auth profile ID `anthropic:default`를 사용하려 했지만, 예상되는 auth 저장소에서 해당 자격 증명을 찾을 수 없었다는 뜻입니다. + + 이는 시스템이 auth profile ID `anthropic:default`를 사용하려 했지만, 예상된 auth 저장소에서 해당 자격 증명을 찾지 못했다는 뜻입니다. - **확인 목록:** + **해결 체크리스트:** - **auth profile 위치 확인**(새 경로 vs 레거시 경로) - 현재: `~/.openclaw/agents//agent/auth-profiles.json` - - 레거시: `~/.openclaw/agent/*` (`openclaw doctor`가 마이그레이션) - - **Gateway가 env var를 로드했는지 확인** + - 레거시: `~/.openclaw/agent/*`(`openclaw doctor`가 마이그레이션) + - **env var가 Gateway에 로드되는지 확인** - 셸에 `ANTHROPIC_API_KEY`를 설정했지만 Gateway를 systemd/launchd로 실행하면 상속되지 않을 수 있습니다. `~/.openclaw/.env`에 넣거나 `env.shellEnv`를 활성화하세요. - - **올바른 에이전트를 편집 중인지 확인** - - 멀티 에이전트 설정에서는 `auth-profiles.json` 파일이 여러 개일 수 있습니다. - - **모델/auth 상태 점검** - - `openclaw models status`를 사용해 구성된 모델과 provider 인증 상태를 확인하세요. + - **올바른 agent를 편집 중인지 확인** + - 멀티 에이전트 설정에서는 `auth-profiles.json` 파일이 여러 개 있을 수 있습니다. + - **모델/auth 상태 기본 점검** + - `openclaw models status`를 사용해 구성된 모델과 provider 인증 여부를 확인하세요. - **“No credentials found for profile anthropic” 확인 목록** + **“No credentials found for profile anthropic” 해결 체크리스트** 이는 실행이 Anthropic auth profile에 고정되어 있지만, Gateway가 - auth 저장소에서 이를 찾을 수 없다는 뜻입니다. + auth 저장소에서 이를 찾지 못하고 있다는 뜻입니다. - **Claude CLI 사용** - - gateway host에서 `openclaw models auth login --provider anthropic --method cli --set-default`를 실행하세요. - - **대신 API 키를 사용하려는 경우** - - **gateway host**의 `~/.openclaw/.env`에 `ANTHROPIC_API_KEY`를 넣으세요. - - 없는 profile을 강제하는 pinned order를 해제하세요. + - gateway 호스트에서 `openclaw models auth login --provider anthropic --method cli --set-default`를 실행하세요. + - **대신 API 키를 사용하려면** + - **gateway 호스트의** `~/.openclaw/.env`에 `ANTHROPIC_API_KEY`를 넣으세요. + - 누락된 profile을 강제하는 고정 순서를 비우세요: ```bash openclaw models auth order clear --provider anthropic ``` - - **gateway host에서 명령을 실행 중인지 확인** + - **명령을 gateway 호스트에서 실행 중인지 확인** - remote mode에서는 auth profile이 로컬 노트북이 아니라 gateway 머신에 있습니다. - 모델 config에 Google Gemini가 fallback으로 포함되어 있거나(Gemini shorthand로 전환했거나) 하면 OpenClaw는 모델 fallback 중에 이를 시도합니다. Google 자격 증명을 구성하지 않았다면 `No API key found for provider "google"`가 표시됩니다. + 모델 config에 Google Gemini가 fallback으로 포함되어 있거나(Gemini 단축어로 전환한 경우 포함), OpenClaw는 모델 fallback 동안 이를 시도합니다. Google 자격 증명을 구성하지 않았다면 `No API key found for provider "google"`가 표시됩니다. - 해결 방법: Google auth를 제공하거나, `agents.defaults.model.fallbacks` / 별칭에서 Google 모델을 제거하거나 피해서 fallback이 그쪽으로 가지 않게 하세요. + 해결 방법: Google auth를 제공하거나, fallback이 그쪽으로 가지 않도록 `agents.defaults.model.fallbacks` / aliases에서 Google 모델을 제거하거나 피하세요. **LLM request rejected: thinking signature required (Google Antigravity)** - 원인: 세션 기록에 **서명이 없는 thinking 블록**이 포함되어 있습니다(종종 - 중단되거나 부분적으로 끝난 스트림에서 발생). Google Antigravity는 thinking 블록에 서명을 요구합니다. + 원인: session 기록에 **서명이 없는 thinking block**이 포함되어 있습니다(종종 + 중단되거나 부분적으로 스트리밍된 결과). Google Antigravity는 thinking block에 서명을 요구합니다. - 해결 방법: OpenClaw는 이제 Google Antigravity Claude에 대해 서명되지 않은 thinking 블록을 제거합니다. 그래도 계속 나타나면 **새 세션**을 시작하거나 해당 에이전트에 대해 `/thinking off`를 설정하세요. + 해결 방법: OpenClaw는 이제 Google Antigravity Claude에 대해 서명되지 않은 thinking block을 제거합니다. 그래도 계속 나타난다면 **새 session**을 시작하거나 해당 agent에 `/thinking off`를 설정하세요. -## auth profile: 무엇이며 어떻게 관리하나요 +## Auth profile: 무엇이며 어떻게 관리하나요? -관련: [/concepts/oauth](/ko/concepts/oauth) (OAuth 흐름, 토큰 저장, 다중 계정 패턴) +관련 문서: [/concepts/oauth](/ko/concepts/oauth) (OAuth 흐름, 토큰 저장소, 멀티 계정 패턴) - auth profile은 provider에 연결된 이름 있는 자격 증명 레코드(OAuth 또는 API 키)입니다. profile은 다음 위치에 있습니다. + auth profile은 provider에 연결된 이름 있는 자격 증명 기록(OAuth 또는 API 키)입니다. profile은 다음에 저장됩니다: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2631,47 +2645,47 @@ x-i18n: - - OpenClaw는 다음과 같은 provider 접두사 ID를 사용합니다. + + OpenClaw는 다음과 같은 provider 접두사 ID를 사용합니다: - - `anthropic:default` (이메일 식별자가 없을 때 흔함) - - OAuth ID의 경우 `anthropic:` + - `anthropic:default`(이메일 ID가 없을 때 흔함) + - OAuth ID용 `anthropic:` - 사용자가 선택한 사용자 지정 ID(예: `anthropic:work`) - 예. config는 profile의 선택적 메타데이터와 provider별 순서(`auth.order.`)를 지원합니다. 이는 **secret을 저장하지 않으며**, ID를 provider/mode에 매핑하고 순환 순서를 설정합니다. + 예. config는 profile에 대한 선택적 메타데이터와 provider별 순서(`auth.order.`)를 지원합니다. 이는 **secret을 저장하지 않으며**, ID를 provider/mode에 매핑하고 순환 순서를 설정합니다. - OpenClaw는 profile이 짧은 **cooldown**(rate limit/timeout/auth 실패)이나 더 긴 **disabled** 상태(과금/잔액 부족)에 있을 때 일시적으로 건너뛸 수 있습니다. 이를 확인하려면 `openclaw models status --json`을 실행하고 `auth.unusableProfiles`를 확인하세요. 조정: `auth.cooldowns.billingBackoffHours*`. + OpenClaw는 profile이 짧은 **쿨다운**(속도 제한/timeout/auth 실패) 상태이거나, 더 긴 **비활성화** 상태(과금/크레딧 부족)일 경우 일시적으로 건너뛸 수 있습니다. 이를 확인하려면 `openclaw models status --json`을 실행하고 `auth.unusableProfiles`를 확인하세요. 조정 항목: `auth.cooldowns.billingBackoffHours*`. - rate-limit cooldown은 모델 단위일 수 있습니다. 한 모델에 대해 cooldown 중인 profile이라도 - 같은 provider의 다른 형제 모델에는 여전히 사용 가능할 수 있지만, - 과금/비활성화 창은 여전히 profile 전체를 막습니다. + 속도 제한 쿨다운은 모델 범위로 적용될 수 있습니다. 한 profile이 + 한 모델에서는 쿨다운 중이어도, 같은 provider의 다른 형제 모델에서는 여전히 사용 가능할 수 있으며, + 과금/비활성화 기간은 여전히 전체 profile을 막습니다. - CLI를 통해 **에이전트별** 순서 override(해당 에이전트의 `auth-state.json`에 저장)를 설정할 수도 있습니다. + CLI를 통해 **agent별** 순서 override(해당 agent의 `auth-state.json`에 저장됨)도 설정할 수 있습니다: ```bash - # 구성된 기본 에이전트가 기본값입니다(--agent 생략 가능) + # 구성된 기본 agent를 기본값으로 사용(--agent 생략) openclaw models auth order get --provider anthropic # 순환을 단일 profile로 고정(이것만 시도) openclaw models auth order set --provider anthropic anthropic:default - # 또는 명시적 순서 설정(provider 내부 fallback) + # 또는 명시적 순서 설정(provider 내 fallback) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # override 제거(config auth.order / round-robin으로 fallback) + # override 제거(config auth.order / round-robin으로 복귀) openclaw models auth order clear --provider anthropic ``` - 특정 에이전트를 대상으로 하려면: + 특정 agent를 대상으로 하려면: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - 실제로 무엇이 시도될지 확인하려면 다음을 사용하세요. + 실제로 무엇이 시도될지 확인하려면 다음을 사용하세요: ```bash openclaw models status --probe @@ -2683,12 +2697,12 @@ x-i18n: - OpenClaw는 둘 다 지원합니다. + OpenClaw는 둘 다 지원합니다: - - **OAuth**는 종종 (해당되는 경우) 구독 액세스를 활용합니다. + - **OAuth**는 종종(해당되는 경우) 구독 기반 접근을 활용합니다. - **API 키**는 토큰당 과금을 사용합니다. - 마법사는 Anthropic Claude CLI, OpenAI Codex OAuth, API 키를 명시적으로 지원합니다. + wizard는 Anthropic Claude CLI, OpenAI Codex OAuth, API 키를 명시적으로 지원합니다. @@ -2707,19 +2721,19 @@ x-i18n: - - "running"은 **supervisor**(launchd/systemd/schtasks)의 관점이고, RPC probe는 CLI가 실제로 gateway WebSocket에 연결해 `status`를 호출한 결과이기 때문입니다. + + "running"은 **supervisor**의 관점(launchd/systemd/schtasks)이고, RPC probe는 CLI가 실제로 gateway WebSocket에 연결해 `status`를 호출하는 것이기 때문입니다. - `openclaw gateway status`를 사용하고 다음 줄을 신뢰하세요. + `openclaw gateway status`를 사용하고 다음 줄을 신뢰하세요: - - `Probe target:` (probe가 실제로 사용한 URL) - - `Listening:` (포트에 실제로 바인드된 대상) - - `Last gateway error:` (프로세스는 살아 있지만 포트가 리슨하지 않을 때 흔한 근본 원인) + - `Probe target:`(probe가 실제로 사용한 URL) + - `Listening:`(포트에 실제로 바인딩된 항목) + - `Last gateway error:`(프로세스는 살아 있지만 포트가 수신하지 않을 때의 흔한 근본 원인) - - 서비스는 한 config 파일을 사용해 실행 중인데, 사용자는 다른 config 파일을 편집하고 있기 때문입니다(대개 `--profile` / `OPENCLAW_STATE_DIR` 불일치). + + 현재 편집 중인 config 파일과 서비스가 실행 중인 config 파일이 다르기 때문입니다(대개 `--profile` / `OPENCLAW_STATE_DIR` 불일치). 해결 방법: @@ -2731,15 +2745,15 @@ x-i18n: - - OpenClaw는 시작 즉시 WebSocket 리스너를 바인딩해 런타임 잠금을 강제합니다(기본값 `ws://127.0.0.1:18789`). 바인딩이 `EADDRINUSE`로 실패하면 다른 인스턴스가 이미 리스닝 중임을 나타내는 `GatewayLockError`를 발생시킵니다. + + OpenClaw는 시작 직후 WebSocket 리스너를 바인딩해 런타임 잠금을 강제합니다(기본값 `ws://127.0.0.1:18789`). 바인딩이 `EADDRINUSE`로 실패하면 다른 인스턴스가 이미 수신 중임을 나타내는 `GatewayLockError`를 발생시킵니다. - 해결 방법: 다른 인스턴스를 중지하거나, 포트를 비우거나, `openclaw gateway --port `로 실행하세요. + 해결 방법: 다른 인스턴스를 중지하고, 포트를 비우거나, `openclaw gateway --port `로 실행하세요. - - `gateway.mode: "remote"`를 설정하고 원격 WebSocket URL을 지정하세요. 필요하면 공유 비밀 원격 자격 증명도 함께 설정할 수 있습니다. + + `gateway.mode: "remote"`를 설정하고 원격 WebSocket URL을 지정하세요. 필요하면 공유 시크릿 원격 자격 증명도 함께 넣을 수 있습니다: ```json5 { @@ -2757,56 +2771,56 @@ x-i18n: 참고: - `openclaw gateway`는 `gateway.mode`가 `local`일 때만 시작됩니다(또는 override 플래그를 전달한 경우). - - macOS 앱은 config 파일을 감시하며 이 값이 바뀌면 실시간으로 모드를 전환합니다. - - `gateway.remote.token` / `.password`는 클라이언트 측 원격 자격 증명일 뿐이며, 그 자체로 로컬 gateway 인증을 활성화하지는 않습니다. + - macOS 앱은 config 파일을 감시하며 이 값이 바뀌면 모드를 실시간으로 전환합니다. + - `gateway.remote.token` / `.password`는 클라이언트 측 원격 자격 증명일 뿐이며, 로컬 gateway 인증을 자체적으로 활성화하지는 않습니다. - gateway의 인증 경로와 UI의 인증 방식이 일치하지 않습니다. + gateway의 인증 경로와 UI의 인증 방식이 서로 맞지 않습니다. 사실(코드 기준): - - Control UI는 현재 브라우저 탭 세션과 선택된 gateway URL에 대해 토큰을 `sessionStorage`에 유지하므로, 장기 `localStorage` 토큰 지속성을 복원하지 않아도 같은 탭에서 새로고침이 계속 작동합니다. - - `AUTH_TOKEN_MISMATCH` 발생 시, gateway가 재시도 힌트(`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`)를 반환하면 신뢰된 클라이언트는 캐시된 device token으로 제한된 1회 재시도를 시도할 수 있습니다. - - 이제 해당 캐시 토큰 재시도는 device token과 함께 저장된 캐시된 승인 scope도 재사용합니다. 명시적인 `deviceToken` / 명시적인 `scopes` 호출자는 캐시된 scope를 상속하지 않고 요청한 scope 집합을 유지합니다. - - 이 재시도 경로 외에서는 connect auth 우선순위가 명시적 공유 토큰/비밀번호 우선, 그다음 명시적 `deviceToken`, 그다음 저장된 device token, 그다음 bootstrap token 순입니다. - - bootstrap token scope 검사는 역할 접두사 기반입니다. 기본 제공 bootstrap operator allowlist는 operator 요청만 충족하며, node나 다른 비-operator 역할은 해당 역할 접두사 아래의 scope가 별도로 필요합니다. + - Control UI는 현재 브라우저 탭 세션과 선택된 gateway URL에 대해 token을 `sessionStorage`에 보관하므로, 장기 `localStorage` token 저장을 복원하지 않아도 같은 탭에서 새로고침은 계속 동작합니다. + - `AUTH_TOKEN_MISMATCH`가 발생하면, gateway가 재시도 힌트(`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`)를 반환할 때 신뢰된 클라이언트는 캐시된 device token으로 제한된 한 번의 재시도를 시도할 수 있습니다. + - 이제 그 캐시 token 재시도는 device token과 함께 저장된 캐시된 승인 범위를 재사용합니다. 명시적 `deviceToken` / 명시적 `scopes` 호출자는 계속 캐시 범위를 상속하지 않고 요청한 범위 집합을 유지합니다. + - 이 재시도 경로 밖에서는 연결 인증 우선순위가 명시적 공유 token/password 우선, 그다음 명시적 `deviceToken`, 그다음 저장된 device token, 그다음 bootstrap token입니다. + - bootstrap token 범위 검사는 역할 접두사 기반입니다. 기본 bootstrap operator allowlist는 operator 요청만 충족하며, node나 다른 비-operator 역할은 여전히 자기 역할 접두사 아래 범위가 필요합니다. 해결 방법: - - 가장 빠른 방법: `openclaw dashboard`(대시보드 URL을 출력하고 복사하며, 열기를 시도하고, headless 환경이면 SSH 힌트를 표시). - - 아직 토큰이 없다면: `openclaw doctor --generate-gateway-token`. - - 원격이라면 먼저 터널링: `ssh -N -L 18789:127.0.0.1:18789 user@host` 후 `http://127.0.0.1:18789/`를 엽니다. - - 공유 비밀 모드: `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 또는 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`를 설정한 뒤, 일치하는 secret을 Control UI 설정에 붙여넣으세요. - - Tailscale Serve 모드: `gateway.auth.allowTailscale`가 활성화되어 있는지, 그리고 Tailscale identity header를 우회하는 원시 loopback/tailnet URL이 아니라 Serve URL을 열고 있는지 확인하세요. - - trusted-proxy 모드: 같은 호스트의 loopback proxy나 원시 gateway URL이 아니라, 구성된 non-loopback ID 인식 proxy를 통해 들어오고 있는지 확인하세요. - - 한 번의 재시도 후에도 불일치가 지속되면 페어링된 device token을 rotate/re-approve하세요. + - 가장 빠른 방법: `openclaw dashboard`(dashboard URL을 출력하고 복사하며, 열기를 시도함. headless면 SSH 힌트 표시). + - 아직 token이 없다면: `openclaw doctor --generate-gateway-token`. + - 원격이라면 먼저 터널링: `ssh -N -L 18789:127.0.0.1:18789 user@host` 후 `http://127.0.0.1:18789/` 열기. + - 공유 시크릿 모드: `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 또는 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`를 설정한 뒤, 일치하는 secret을 Control UI 설정에 붙여넣으세요. + - Tailscale Serve 모드: `gateway.auth.allowTailscale`이 활성화되어 있는지, 그리고 Tailscale ID 헤더를 우회하는 원시 loopback/tailnet URL이 아니라 Serve URL을 열고 있는지 확인하세요. + - trusted-proxy 모드: 같은 호스트의 loopback proxy나 원시 gateway URL이 아니라, 구성된 loopback이 아닌 ID 인식 프록시를 통해 접근하고 있는지 확인하세요. + - 한 번의 재시도 후에도 불일치가 계속되면, 페어링된 device token을 교체/재승인하세요: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - rotate 호출이 거부되었다고 나오면 다음 두 가지를 확인하세요. - - paired-device 세션은 `operator.admin`이 없는 한 **자기 자신의** device만 rotate할 수 있습니다 - - 명시적 `--scope` 값은 호출자의 현재 operator scope를 초과할 수 없습니다 - - 그래도 막히면 `openclaw status --all`을 실행하고 [문제 해결](/ko/gateway/troubleshooting)을 따르세요. 인증 세부 사항은 [대시보드](/web/dashboard)를 참고하세요. + - 이 rotate 호출이 거부되었다고 나오면 두 가지를 확인하세요: + - 페어링된 device session은 `operator.admin`이 없는 한 **자기 자신의** device만 교체할 수 있습니다 + - 명시적 `--scope` 값은 호출자의 현재 operator 범위를 초과할 수 없습니다 + - 여전히 막혔다면 `openclaw status --all`을 실행하고 [문제 해결](/ko/gateway/troubleshooting)을 따르세요. 인증 세부 사항은 [Dashboard](/web/dashboard)를 참고하세요. - - `tailnet` bind는 네트워크 인터페이스에서 Tailscale IP(100.64.0.0/10)를 선택합니다. 머신이 Tailscale에 연결되어 있지 않거나(또는 인터페이스가 내려가 있으면) 바인드할 대상이 없습니다. + + `tailnet` bind는 네트워크 인터페이스에서 Tailscale IP(100.64.0.0/10)를 선택합니다. 머신이 Tailscale에 연결되어 있지 않거나(또는 인터페이스가 내려가 있으면) 바인딩할 대상이 없습니다. 해결 방법: - 해당 호스트에서 Tailscale을 시작해 100.x 주소를 갖게 하거나, - `gateway.bind: "loopback"` / `"lan"`으로 전환하세요. - 참고: `tailnet`은 명시적입니다. `auto`는 loopback을 선호하므로, tailnet 전용 bind를 원하면 `gateway.bind: "tailnet"`을 사용하세요. + 참고: `tailnet`은 명시적입니다. `auto`는 loopback을 우선합니다. tailnet 전용 bind를 원할 때는 `gateway.bind: "tailnet"`을 사용하세요. - 보통은 아닙니다. 하나의 Gateway가 여러 메시징 채널과 에이전트를 실행할 수 있습니다. 여러 Gateway는 중복성(예: rescue bot)이나 강한 격리가 필요할 때만 사용하세요. + 보통은 아니요. 하나의 Gateway로 여러 메시징 channel과 agent를 실행할 수 있습니다. 여러 Gateway는 중복성(예: rescue bot)이나 강한 격리가 필요한 경우에만 사용하세요. - 가능하긴 하지만 다음을 분리해야 합니다. + 가능합니다. 하지만 다음을 분리해야 합니다: - `OPENCLAW_CONFIG_PATH`(인스턴스별 config) - `OPENCLAW_STATE_DIR`(인스턴스별 state) @@ -2815,39 +2829,39 @@ x-i18n: 빠른 설정(권장): - - 인스턴스마다 `openclaw --profile ...`를 사용하세요(`~/.openclaw-` 자동 생성). - - 각 profile config에 고유한 `gateway.port`를 설정하세요(또는 수동 실행 시 `--port` 전달). - - profile별 서비스를 설치하세요: `openclaw --profile gateway install`. + - 인스턴스별로 `openclaw --profile ...` 사용(`~/.openclaw-` 자동 생성). + - 각 profile config에서 고유한 `gateway.port`를 설정(또는 수동 실행에는 `--port` 전달). + - profile별 서비스 설치: `openclaw --profile gateway install`. profile은 서비스 이름에도 접미사를 붙입니다(`ai.openclaw.`; 레거시 `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). 전체 가이드: [여러 gateway](/ko/gateway/multiple-gateways). - - Gateway는 **WebSocket 서버**이며, 첫 번째 메시지로 반드시 - `connect` 프레임이 오기를 기대합니다. 다른 것이 오면 - **code 1008**(정책 위반)로 연결을 닫습니다. + + Gateway는 **WebSocket 서버**이며, 첫 번째 메시지가 반드시 + `connect` 프레임이기를 기대합니다. 다른 것이 오면 + 연결을 **code 1008**(정책 위반)로 종료합니다. 흔한 원인: - - 브라우저에서 **HTTP** URL(`http://...`)을 열었고, WS 클라이언트를 사용하지 않았음 - - 잘못된 포트나 경로를 사용했음 - - proxy 또는 tunnel이 auth header를 제거했거나 Gateway가 아닌 요청을 보냈음 + - 브라우저에서 **HTTP** URL(`http://...`)을 열었고, WS 클라이언트가 아니었습니다. + - 잘못된 포트나 경로를 사용했습니다. + - 프록시나 터널이 인증 헤더를 제거했거나 Gateway가 아닌 요청을 보냈습니다. 빠른 해결 방법: - 1. WS URL을 사용하세요: `ws://:18789`(또는 HTTPS면 `wss://...`) + 1. WS URL 사용: `ws://:18789`(HTTPS라면 `wss://...`) 2. 일반 브라우저 탭에서 WS 포트를 열지 마세요. - 3. 인증이 켜져 있다면 `connect` 프레임에 토큰/비밀번호를 포함하세요. + 3. 인증이 켜져 있으면 `connect` 프레임에 token/password를 포함하세요. - CLI 또는 TUI를 사용 중이라면 URL은 다음과 같아야 합니다. + CLI나 TUI를 사용 중이라면 URL은 다음과 같아야 합니다: ``` openclaw tui --url ws://:18789 --token ``` - 프로토콜 세부 정보: [Gateway protocol](/ko/gateway/protocol). + 프로토콜 세부 사항: [Gateway protocol](/ko/gateway/protocol). @@ -2862,7 +2876,7 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - `logging.file`로 고정 경로를 설정할 수 있습니다. 파일 로그 수준은 `logging.level`로 제어합니다. 콘솔 상세도는 `--verbose`와 `logging.consoleLevel`로 제어합니다. + `logging.file`로 고정 경로를 설정할 수 있습니다. 파일 로그 레벨은 `logging.level`로 제어합니다. 콘솔 자세도는 `--verbose`와 `logging.consoleLevel`로 제어합니다. 가장 빠른 로그 tail: @@ -2870,7 +2884,7 @@ x-i18n: openclaw logs --follow ``` - 서비스/supervisor 로그(gateway가 launchd/systemd로 실행될 때): + 서비스/supervisor 로그(gateway를 launchd/systemd로 실행할 때): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` 및 `gateway.err.log`(기본값: `~/.openclaw/logs/...`; profile 사용 시 `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` @@ -2881,23 +2895,23 @@ x-i18n: - gateway helper를 사용하세요. + gateway helper를 사용하세요: ```bash openclaw gateway status openclaw gateway restart ``` - gateway를 수동으로 실행 중이라면 `openclaw gateway --force`로 포트를 다시 차지할 수 있습니다. [Gateway](/ko/gateway)를 참고하세요. + gateway를 수동 실행 중이라면 `openclaw gateway --force`로 포트를 다시 차지할 수 있습니다. [Gateway](/ko/gateway)를 참고하세요. - Windows 설치 모드는 **두 가지**가 있습니다. + Windows에는 **두 가지 설치 모드**가 있습니다: - **1) WSL2(권장):** Gateway는 Linux 내부에서 실행됩니다. + **1) WSL2(권장):** Gateway가 Linux 안에서 실행됩니다. - PowerShell을 열고 WSL에 들어간 뒤 재시작하세요. + PowerShell을 열고 WSL에 들어간 뒤 다시 시작하세요: ```powershell wsl @@ -2905,7 +2919,7 @@ x-i18n: openclaw gateway restart ``` - 서비스를 설치하지 않았다면 포그라운드에서 시작하세요. + 서비스를 설치한 적이 없다면 포그라운드에서 시작하세요: ```bash openclaw gateway run @@ -2913,14 +2927,14 @@ x-i18n: **2) 네이티브 Windows(권장하지 않음):** Gateway가 Windows에서 직접 실행됩니다. - PowerShell을 열고 다음을 실행하세요. + PowerShell을 열고 다음을 실행하세요: ```powershell openclaw gateway status openclaw gateway restart ``` - 수동으로 실행 중이라면(서비스 없음) 다음을 사용하세요. + 수동으로 실행 중이라면(서비스 없음), 다음을 사용하세요: ```powershell openclaw gateway run @@ -2930,8 +2944,8 @@ x-i18n: - - 먼저 빠른 상태 점검부터 하세요. + + 먼저 빠른 상태 점검부터 시작하세요: ```bash openclaw status @@ -2942,56 +2956,56 @@ x-i18n: 흔한 원인: - - **gateway host**에서 모델 auth가 로드되지 않음(`models status` 확인) - - 채널 pairing/allowlist가 응답을 막고 있음(채널 config + 로그 확인) - - 올바른 토큰 없이 WebChat/대시보드가 열려 있음 + - **gateway 호스트**에 모델 인증이 로드되지 않음(`models status` 확인). + - channel 페어링/allowlist가 응답을 막고 있음(channel config + 로그 확인). + - 올바른 token 없이 WebChat/Dashboard가 열려 있음. - 원격이라면 tunnel/Tailscale 연결이 올라와 있고 - Gateway WebSocket에 도달 가능한지 확인하세요. + 원격 환경이라면 터널/Tailscale 연결이 살아 있는지, 그리고 + Gateway WebSocket에 접근 가능한지 확인하세요. - 문서: [채널](/ko/channels), [문제 해결](/ko/gateway/troubleshooting), [원격 액세스](/ko/gateway/remote). + 문서: [Channels](/ko/channels), [문제 해결](/ko/gateway/troubleshooting), [원격 액세스](/ko/gateway/remote). - - 보통 UI가 WebSocket 연결을 잃었다는 뜻입니다. 다음을 확인하세요. + + 이는 보통 UI가 WebSocket 연결을 잃었다는 뜻입니다. 다음을 확인하세요: 1. Gateway가 실행 중인가요? `openclaw gateway status` - 2. Gateway 상태는 정상인가요? `openclaw status` - 3. UI에 올바른 토큰이 있나요? `openclaw dashboard` - 4. 원격이라면 tunnel/Tailscale 링크가 살아 있나요? + 2. Gateway가 정상인가요? `openclaw status` + 3. UI에 올바른 token이 있나요? `openclaw dashboard` + 4. 원격이라면 터널/Tailscale 연결이 살아 있나요? - 그런 다음 로그를 따라가세요. + 그런 다음 로그를 tail 하세요: ```bash openclaw logs --follow ``` - 문서: [대시보드](/web/dashboard), [원격 액세스](/ko/gateway/remote), [문제 해결](/ko/gateway/troubleshooting). + 문서: [Dashboard](/web/dashboard), [원격 액세스](/ko/gateway/remote), [문제 해결](/ko/gateway/troubleshooting). - 먼저 로그와 채널 상태를 확인하세요. + 먼저 로그와 channel 상태부터 확인하세요: ```bash openclaw channels status openclaw channels logs --channel telegram ``` - 그런 다음 오류에 맞춰 보세요. + 그런 다음 오류와 대조하세요: - - `BOT_COMMANDS_TOO_MUCH`: Telegram 메뉴에 항목이 너무 많습니다. OpenClaw는 이미 Telegram 한도에 맞게 줄이고 더 적은 명령으로 재시도하지만, 일부 메뉴 항목은 여전히 제거해야 합니다. Plugin/Skill/사용자 지정 명령을 줄이거나, 메뉴가 필요 없다면 `channels.telegram.commands.native`를 비활성화하세요. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!`, 또는 유사한 네트워크 오류: VPS에 있거나 proxy 뒤에 있다면 `api.telegram.org`에 대해 outbound HTTPS가 허용되고 DNS가 동작하는지 확인하세요. + - `BOT_COMMANDS_TOO_MUCH`: Telegram 메뉴에 항목이 너무 많습니다. OpenClaw는 이미 Telegram 한도에 맞게 줄이고 더 적은 명령으로 재시도하지만, 일부 메뉴 항목은 여전히 제거해야 합니다. plugin/skill/custom 명령 수를 줄이거나, 메뉴가 필요 없다면 `channels.telegram.commands.native`를 비활성화하세요. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!`, 또는 유사한 네트워크 오류: VPS에 있거나 프록시 뒤에 있다면, `api.telegram.org`에 대해 아웃바운드 HTTPS가 허용되고 DNS가 동작하는지 확인하세요. - Gateway가 원격이라면 gateway host의 로그를 보고 있는지 확인하세요. + Gateway가 원격에 있다면 Gateway 호스트의 로그를 보고 있는지 확인하세요. - 문서: [Telegram](/ko/channels/telegram), [채널 문제 해결](/ko/channels/troubleshooting). + 문서: [Telegram](/ko/channels/telegram), [Channel 문제 해결](/ko/channels/troubleshooting). - 먼저 Gateway에 도달 가능하고 에이전트가 실행될 수 있는지 확인하세요. + 먼저 Gateway에 연결 가능하고 agent가 실행될 수 있는지 확인하세요: ```bash openclaw status @@ -2999,15 +3013,15 @@ x-i18n: openclaw logs --follow ``` - TUI에서는 `/status`로 현재 상태를 확인하세요. 채팅 - 채널에서 응답을 기대한다면 전달이 활성화되어 있는지(`/deliver on`) 확인하세요. + TUI에서는 `/status`를 사용해 현재 상태를 확인하세요. 채팅 + channel에서 응답을 기대한다면 전달이 활성화되어 있는지(`/deliver on`) 확인하세요. - 문서: [TUI](/web/tui), [슬래시 명령](/ko/tools/slash-commands). + 문서: [TUI](/web/tui), [Slash 명령](/ko/tools/slash-commands). - 서비스를 설치했다면 다음을 사용하세요. + 서비스를 설치했다면: ```bash openclaw gateway stop @@ -3015,7 +3029,7 @@ x-i18n: ``` 이렇게 하면 **감독되는 서비스**(macOS의 launchd, Linux의 systemd)를 중지/시작합니다. - Gateway가 데몬으로 백그라운드에서 실행 중일 때 사용하세요. + Gateway가 데몬으로 백그라운드 실행 중일 때 이 방법을 사용하세요. 포그라운드에서 실행 중이라면 Ctrl-C로 중지한 다음: @@ -3029,22 +3043,22 @@ x-i18n: - `openclaw gateway restart`: **백그라운드 서비스**(launchd/systemd)를 재시작합니다. - - `openclaw gateway`: 현재 터미널 세션에서 gateway를 **포그라운드**로 실행합니다. + - `openclaw gateway`: 이 터미널 세션에서 gateway를 **포그라운드**로 실행합니다. - 서비스를 설치했다면 gateway 명령을 사용하세요. 일회성 포그라운드 실행이 필요할 때는 `openclaw gateway`를 사용하세요. + 서비스를 설치했다면 gateway 명령을 사용하세요. 일회성 포그라운드 실행을 원할 때는 `openclaw gateway`를 사용하세요. - - 콘솔에서 더 자세한 정보를 보려면 `--verbose`로 Gateway를 시작하세요. 그런 다음 로그 파일에서 채널 인증, 모델 라우팅, RPC 오류를 확인하세요. + + 더 자세한 콘솔 정보를 얻으려면 `--verbose`로 Gateway를 시작하세요. 그런 다음 채널 인증, 모델 라우팅, RPC 오류를 확인하기 위해 로그 파일을 검사하세요. -## 미디어와 첨부파일 +## 미디어 및 첨부 파일 - 에이전트의 outbound attachment에는 반드시 `MEDIA:` 줄이 포함되어야 합니다(별도 줄에 단독으로). [OpenClaw assistant setup](/ko/start/openclaw) 및 [Agent send](/ko/tools/agent-send)를 참고하세요. + agent의 아웃바운드 첨부 파일에는 반드시 `MEDIA:` 줄이 포함되어야 합니다(별도 줄에 단독으로). [OpenClaw assistant 설정](/ko/start/openclaw) 및 [Agent send](/ko/tools/agent-send)를 참고하세요. CLI 전송: @@ -3052,116 +3066,115 @@ x-i18n: openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` - 또한 다음을 확인하세요. + 다음도 확인하세요: - - 대상 채널이 outbound media를 지원하고 allowlist에 의해 차단되지 않았는지 - - 파일이 provider 크기 제한 내에 있는지(이미지는 최대 2048px로 리사이즈됨) - - `tools.fs.workspaceOnly=true`이면 로컬 경로 전송이 workspace, temp/media-store, sandbox 검증 파일로 제한됨 - - `tools.fs.workspaceOnly=false`이면 에이전트가 이미 읽을 수 있는 호스트 로컬 파일을 `MEDIA:`로 전송할 수 있지만, 이는 미디어와 안전한 문서 유형(이미지, 오디오, 비디오, PDF, Office 문서)에만 허용됨. 일반 텍스트와 secret처럼 보이는 파일은 여전히 차단됨 + - 대상 channel이 아웃바운드 미디어를 지원하고 allowlist에 의해 차단되지 않았는지 + - 파일이 provider의 크기 제한 내에 있는지(이미지는 최대 2048px로 리사이즈됨) + - `tools.fs.workspaceOnly=true`는 로컬 경로 전송을 workspace, temp/media-store, 샌드박스 검증 파일로 제한합니다. + - `tools.fs.workspaceOnly=false`는 agent가 이미 읽을 수 있는 호스트 로컬 파일을 `MEDIA:`로 전송할 수 있게 하지만, 미디어와 안전한 문서 형식(이미지, 오디오, 비디오, PDF, Office 문서)에만 허용됩니다. 일반 텍스트와 secret처럼 보이는 파일은 여전히 차단됩니다. [이미지](/ko/nodes/images)를 참고하세요. -## 보안과 접근 제어 +## 보안 및 액세스 제어 - - 들어오는 DM은 신뢰할 수 없는 입력으로 취급하세요. 기본값은 위험을 줄이도록 설계되어 있습니다. + + 인바운드 DM은 신뢰할 수 없는 입력으로 취급하세요. 기본값은 위험을 줄이도록 설계되어 있습니다: - - DM이 가능한 채널의 기본 동작은 **pairing**입니다. - - 알 수 없는 발신자에게는 pairing code가 전송되며, 봇은 해당 메시지를 처리하지 않습니다. - - 승인 방법: `openclaw pairing approve --channel [--account ] ` - - 대기 중 요청은 **채널당 3개**로 제한됩니다. 코드가 도착하지 않았다면 `openclaw pairing list --channel [--account ]`로 확인하세요. - - DM을 공개적으로 열려면 명시적 opt-in이 필요합니다(`dmPolicy: "open"` 및 allowlist `"*"`). + - DM이 가능한 channel의 기본 동작은 **페어링**입니다: + - 알 수 없는 발신자는 페어링 코드를 받으며, 봇은 해당 메시지를 처리하지 않습니다. + - 다음으로 승인: `openclaw pairing approve --channel [--account ] ` + - 대기 중인 요청은 **채널당 3개**로 제한됩니다. 코드가 오지 않았다면 `openclaw pairing list --channel [--account ]`를 확인하세요. + - DM을 공개적으로 여는 것은 명시적 opt-in이 필요합니다(`dmPolicy: "open"` 및 allowlist `"*"`). - 위험한 DM 정책을 확인하려면 `openclaw doctor`를 실행하세요. + 위험한 DM 정책을 표시하려면 `openclaw doctor`를 실행하세요. - - 아닙니다. prompt injection은 누가 봇에 DM을 보내는지보다 **신뢰할 수 없는 콘텐츠**에 관한 문제입니다. - 어시스턴트가 외부 콘텐츠(웹 검색/가져오기, 브라우저 페이지, 이메일, - 문서, 첨부파일, 붙여넣은 로그)를 읽는다면, 그 콘텐츠에는 모델을 - 탈취하려는 지시가 포함될 수 있습니다. 이는 **본인만 발신자일 때도** - 일어날 수 있습니다. + + 아니요. 프롬프트 인젝션은 누가 봇에 DM을 보낼 수 있는지가 아니라 **신뢰할 수 없는 콘텐츠**에 관한 문제입니다. + assistant가 외부 콘텐츠(웹 검색/가져오기, 브라우저 페이지, 이메일, + 문서, 첨부 파일, 붙여넣은 로그)를 읽는다면, 그 콘텐츠에는 모델을 + 탈취하려는 지시가 포함될 수 있습니다. **발신자가 사용자 한 명뿐이어도** + 이런 일은 발생할 수 있습니다. - 가장 큰 위험은 도구가 활성화되어 있을 때입니다. 모델이 속아 컨텍스트를 - 유출하거나 사용자를 대신해 도구를 호출할 수 있습니다. 영향 범위를 줄이려면: + 가장 큰 위험은 도구가 활성화되어 있을 때입니다. 모델이 + 컨텍스트를 유출하거나 사용자를 대신해 도구를 호출하도록 속을 수 있기 때문입니다. 피해 범위를 줄이려면: - - 신뢰할 수 없는 콘텐츠를 요약할 때는 읽기 전용 또는 도구가 비활성화된 "reader" 에이전트를 사용 - - 도구가 활성화된 에이전트에서는 `web_search` / `web_fetch` / `browser`를 끄기 - - 디코딩된 파일/문서 텍스트도 신뢰하지 않기: OpenResponses - `input_file`과 미디어 첨부 추출은 모두 추출된 텍스트를 원시 파일 텍스트로 넘기는 대신 - 명시적 external-content 경계 마커로 감쌈 + - 신뢰할 수 없는 콘텐츠를 요약할 때는 읽기 전용 또는 도구 비활성화 "reader" agent 사용 + - 도구 사용 agent에서는 `web_search` / `web_fetch` / `browser`를 꺼두기 + - 디코딩된 파일/문서 텍스트도 신뢰할 수 없는 것으로 취급하기: OpenResponses + `input_file`과 미디어 첨부 파일 추출은 모두 추출된 텍스트를 원시 파일 텍스트로 넘기지 않고 + 명시적인 외부 콘텐츠 경계 마커로 감쌉니다 - 샌드박싱과 엄격한 도구 allowlist 사용 자세한 내용: [보안](/ko/gateway/security). - - 대부분의 설정에서는 예. 봇을 별도의 계정과 전화번호로 분리하면 - 문제가 생겼을 때 영향 범위를 줄일 수 있습니다. 또한 개인 계정에 영향을 주지 않고 - 자격 증명을 교체하거나 접근을 철회하기도 쉬워집니다. + + 대부분의 설정에서는 예. 별도의 계정과 전화번호로 봇을 격리하면 + 문제가 생겼을 때 피해 범위를 줄일 수 있습니다. 또한 개인 계정에 영향을 주지 않고 + 자격 증명을 교체하거나 액세스를 철회하기도 쉬워집니다. - 작게 시작하세요. 실제로 필요한 도구와 계정만 접근 권한을 주고, 필요할 때 - 나중에 확장하세요. + 작게 시작하세요. 실제로 필요한 도구와 계정에만 접근 권한을 주고, + 필요하면 나중에 확장하세요. - 문서: [보안](/ko/gateway/security), [Pairing](/ko/channels/pairing). + 문서: [보안](/ko/gateway/security), [페어링](/ko/channels/pairing). - - 개인 메시지에 대해 완전한 자율성을 주는 것은 **권장하지 않습니다**. 가장 안전한 패턴은 다음과 같습니다. + + 개인 메시지에 대한 완전한 자율성은 **권장하지 않습니다**. 가장 안전한 패턴은 다음과 같습니다: - - DM은 **pairing mode** 또는 엄격한 allowlist로 유지 + - DM은 **페어링 모드** 또는 엄격한 allowlist로 유지 - 사용자를 대신해 메시지를 보내게 하려면 **별도의 번호 또는 계정** 사용 - - 초안을 작성하게 한 뒤 **전송 전에 승인** + - 초안을 작성하게 한 뒤 **보내기 전에 승인** - 실험해 보고 싶다면 전용 계정에서 하고, 격리 상태를 유지하세요. - [보안](/ko/gateway/security)을 참고하세요. + 실험하고 싶다면 전용 계정에서 하고 격리 상태를 유지하세요. [보안](/ko/gateway/security)을 참고하세요. - - 예. 다만 에이전트가 채팅 전용이고 입력이 신뢰할 수 있는 경우에 한합니다. 더 작은 등급은 - 지시 하이재킹에 더 취약하므로, 도구가 활성화된 에이전트나 - 신뢰할 수 없는 콘텐츠를 읽는 경우에는 피하세요. 꼭 작은 모델을 사용해야 한다면 - 도구를 강하게 제한하고 샌드박스 안에서 실행하세요. [보안](/ko/gateway/security)을 참고하세요. + + 예. 다만 agent가 채팅 전용이고 입력이 신뢰할 수 있을 **때만** 그렇습니다. 더 작은 등급은 + 지시 탈취에 더 취약하므로, 도구 사용 agent나 + 신뢰할 수 없는 콘텐츠를 읽을 때는 피하세요. 작은 모델을 꼭 써야 한다면 + 도구를 엄격히 제한하고 샌드박스 안에서 실행하세요. [보안](/ko/gateway/security)을 참고하세요. - - pairing code는 알 수 없는 발신자가 봇에 메시지를 보내고 - `dmPolicy: "pairing"`이 활성화되어 있을 때만 전송됩니다. `/start`만으로는 코드가 생성되지 않습니다. + + 페어링 코드는 알 수 없는 발신자가 봇에 메시지를 보내고 + `dmPolicy: "pairing"`이 활성화된 경우에만 전송됩니다. `/start`만으로는 코드가 생성되지 않습니다. - 대기 중 요청 확인: + 대기 중인 요청 확인: ```bash openclaw pairing list telegram ``` - 즉시 접근하고 싶다면 발신자 ID를 allowlist에 추가하거나 해당 계정에 대해 `dmPolicy: "open"`을 설정하세요. + 즉시 접근을 원한다면 발신자 ID를 allowlist에 추가하거나 해당 계정에 대해 `dmPolicy: "open"`을 설정하세요. - - 아니요. WhatsApp의 기본 DM 정책은 **pairing**입니다. 알 수 없는 발신자는 pairing code만 받으며, 그들의 메시지는 **처리되지 않습니다**. OpenClaw는 받은 채팅이나 사용자가 명시적으로 트리거한 전송에만 응답합니다. + + 아니요. 기본 WhatsApp DM 정책은 **페어링**입니다. 알 수 없는 발신자는 페어링 코드만 받고 메시지는 **처리되지 않습니다**. OpenClaw는 받은 채팅이나 사용자가 명시적으로 트리거한 전송에만 응답합니다. - pairing 승인: + 페어링 승인: ```bash openclaw pairing approve whatsapp ``` - 대기 중 요청 목록: + 대기 중인 요청 나열: ```bash openclaw pairing list whatsapp ``` - 마법사의 전화번호 프롬프트는 사용자의 **allowlist/owner**를 설정해 본인 DM이 허용되도록 하기 위한 것입니다. 자동 전송에는 사용되지 않습니다. 개인 WhatsApp 번호로 실행한다면 해당 번호를 사용하고 `channels.whatsapp.selfChatMode`를 활성화하세요. + wizard의 전화번호 프롬프트: 사용자의 **allowlist/owner**를 설정해 자신의 DM이 허용되도록 하는 데 사용됩니다. 자동 전송 용도가 아닙니다. 개인 WhatsApp 번호에서 실행한다면 해당 번호를 사용하고 `channels.whatsapp.selfChatMode`를 활성화하세요. @@ -3170,9 +3183,9 @@ x-i18n: - 대부분의 내부 또는 도구 메시지는 해당 세션에서 **verbose**, **trace**, 또는 **reasoning**이 활성화되어 있을 때만 나타납니다. + 대부분의 내부 또는 도구 메시지는 해당 session에서 **verbose**, **trace**, **reasoning**이 활성화된 경우에만 나타납니다. - 보이는 채팅에서 다음을 설정하세요. + 보이는 채팅에서 다음을 실행하세요: ``` /verbose off @@ -3180,16 +3193,16 @@ x-i18n: /reasoning off ``` - 그래도 시끄럽다면 Control UI의 세션 설정을 확인하고 verbose를 + 그래도 시끄럽다면 Control UI의 session 설정을 확인하고 verbose를 **inherit**로 설정하세요. 또한 config에서 `verboseDefault`가 - `on`으로 설정된 봇 프로필을 사용 중이 아닌지도 확인하세요. + `on`으로 설정된 bot profile을 사용 중이 아닌지도 확인하세요. - 문서: [Thinking and verbose](/ko/tools/thinking), [보안](/ko/gateway/security#reasoning-verbose-output-in-groups). + 문서: [Thinking 및 verbose](/ko/tools/thinking), [보안](/ko/gateway/security#reasoning-verbose-output-in-groups). - - 다음 중 하나를 **독립된 메시지로** 보내세요(슬래시 없음). + + 다음 중 하나를 **단독 메시지로** 보내세요(슬래시 없음): ``` stop @@ -3213,25 +3226,25 @@ x-i18n: interrupt ``` - 이들은 슬래시 명령이 아니라 abort trigger입니다. + 이는 슬래시 명령이 아니라 중단 트리거입니다. - exec tool의 백그라운드 프로세스는 에이전트에게 다음을 실행하라고 요청할 수 있습니다. + exec 도구로 실행한 백그라운드 프로세스의 경우, agent에게 다음을 실행하라고 요청할 수 있습니다: ``` process action:kill sessionId:XXX ``` - 슬래시 명령 개요는 [슬래시 명령](/ko/tools/slash-commands)을 참고하세요. + Slash 명령 개요: [Slash 명령](/ko/tools/slash-commands)을 참고하세요. - 대부분의 명령은 `/`로 시작하는 **독립된** 메시지로 보내야 하지만, 몇몇 단축 명령(예: `/status`)은 allowlist된 발신자에게 inline으로도 작동합니다. + 대부분의 명령은 `/`로 시작하는 **단독** 메시지로 보내야 하지만, 일부 단축어(`/status` 등)는 allowlist에 있는 발신자에 한해 인라인으로도 동작합니다. - - OpenClaw는 기본적으로 **교차 provider** 메시징을 차단합니다. tool 호출이 - Telegram에 바인딩되어 있으면 명시적으로 허용하지 않는 한 Discord로 보내지 않습니다. + + OpenClaw는 기본적으로 **교차 provider** 메시징을 차단합니다. 도구 호출이 + Telegram에 바인딩되어 있으면, 명시적으로 허용하지 않는 한 Discord로 보내지 않습니다. - 에이전트에 대해 교차 provider 메시징을 활성화하세요. + agent에 대해 교차 provider 메시징 활성화: ```json5 { @@ -3246,20 +3259,20 @@ x-i18n: } ``` - config를 편집한 후 gateway를 재시작하세요. + config를 편집한 뒤 gateway를 다시 시작하세요. - - queue mode가 새 메시지가 진행 중인 실행과 어떻게 상호작용하는지 제어합니다. `/queue`로 모드를 변경하세요. + + queue 모드는 새 메시지가 실행 중인 작업과 어떻게 상호작용하는지 제어합니다. `/queue`로 모드를 바꾸세요: - - `steer` - 새 메시지가 현재 작업을 재지정 - - `followup` - 메시지를 한 번에 하나씩 실행 - - `collect` - 메시지를 묶어서 한 번만 응답(기본값) - - `steer-backlog` - 지금은 재지정하고, 이후 backlog 처리 - - `interrupt` - 현재 실행을 중단하고 새로 시작 + - `steer` - 새 메시지가 현재 작업의 방향을 바꿉니다 + - `followup` - 메시지를 한 번에 하나씩 실행합니다 + - `collect` - 메시지를 모아서 한 번에 응답합니다(기본값) + - `steer-backlog` - 지금은 방향을 바꾸고, 이후 backlog를 처리합니다 + - `interrupt` - 현재 실행을 중단하고 새로 시작합니다 - followup 모드에는 `debounce:2s cap:25 drop:summarize` 같은 옵션을 추가할 수 있습니다. + followup 모드에는 `debounce:2s cap:25 drop:summarize` 같은 옵션도 추가할 수 있습니다. @@ -3268,10 +3281,10 @@ x-i18n: - OpenClaw에서는 자격 증명과 모델 선택이 분리되어 있습니다. `ANTHROPIC_API_KEY`를 설정하거나(또는 Anthropic API 키를 auth profile에 저장하면) 인증은 활성화되지만, 실제 기본 모델은 `agents.defaults.model.primary`에 구성한 값입니다(예: `anthropic/claude-sonnet-4-6` 또는 `anthropic/claude-opus-4-6`). `No credentials found for profile "anthropic:default"`가 보인다면, 실행 중인 에이전트에 대해 Gateway가 예상되는 `auth-profiles.json`에서 Anthropic 자격 증명을 찾지 못했다는 뜻입니다. + OpenClaw에서 자격 증명과 모델 선택은 별개입니다. `ANTHROPIC_API_KEY`를 설정하거나(또는 auth profile에 Anthropic API 키를 저장하면) 인증은 활성화되지만, 실제 기본 모델은 `agents.defaults.model.primary`에 구성한 값입니다(예: `anthropic/claude-sonnet-4-6` 또는 `anthropic/claude-opus-4-6`). `No credentials found for profile "anthropic:default"`가 보인다면, 실행 중인 agent에 대해 Gateway가 예상된 `auth-profiles.json`에서 Anthropic 자격 증명을 찾지 못했다는 뜻입니다. --- -그래도 막혔다면 [Discord](https://discord.com/invite/clawd)에서 질문하거나 [GitHub 토론](https://github.com/openclaw/openclaw/discussions)을 열어 주세요. +여전히 막혔나요? [Discord](https://discord.com/invite/clawd)에서 문의하거나 [GitHub 토론](https://github.com/openclaw/openclaw/discussions)을 열어 주세요. diff --git a/docs/ko/help/testing.md b/docs/ko/help/testing.md index 10e034ade..8d3f39283 100644 --- a/docs/ko/help/testing.md +++ b/docs/ko/help/testing.md @@ -3,68 +3,69 @@ read_when: - 로컬 또는 CI에서 테스트 실행하기 - 모델/제공자 버그에 대한 회귀 테스트 추가하기 - Gateway + 에이전트 동작 디버깅하기 -summary: '테스트 키트: unit/e2e/live 스위트, Docker 실행기, 그리고 각 테스트가 다루는 내용' +summary: '테스트 키트: unit/e2e/live 스위트, Docker 러너, 그리고 각 테스트가 무엇을 다루는지' title: 테스트 x-i18n: - generated_at: "2026-04-18T05:51:42Z" + generated_at: "2026-04-20T06:05:30Z" model: gpt-5.4 provider: openai - source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a + source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc source_path: help/testing.md workflow: 15 --- # 테스트 -OpenClaw에는 세 가지 Vitest 스위트(unit/integration, e2e, live)와 소수의 Docker 실행기가 있습니다. +OpenClaw에는 세 가지 Vitest 스위트(unit/integration, e2e, live)와 소규모 Docker 러너 세트가 있습니다. -이 문서는 “어떻게 테스트하는가”에 대한 가이드입니다. +이 문서는 “어떻게 테스트하는가”에 대한 가이드입니다: -- 각 스위트가 무엇을 다루는지(그리고 의도적으로 _다루지 않는_ 것은 무엇인지) +- 각 스위트가 무엇을 다루는지(그리고 의도적으로 무엇은 다루지 않는지) - 일반적인 워크플로(로컬, 푸시 전, 디버깅)에서 어떤 명령을 실행해야 하는지 -- live 테스트가 자격 증명을 어떻게 찾고 모델/제공자를 어떻게 선택하는지 -- 실제 모델/제공자 이슈에 대한 회귀 테스트를 어떻게 추가하는지 +- live 테스트가 자격 증명을 어떻게 발견하고 모델/제공자를 어떻게 선택하는지 +- 실제 모델/제공자 이슈에 대한 회귀 테스트를 추가하는 방법 ## 빠른 시작 대부분의 날에는: -- 전체 게이트(푸시 전 예상): `pnpm build && pnpm check && pnpm test` +- 전체 게이트(푸시 전에 기대됨): `pnpm build && pnpm check && pnpm test` - 여유 있는 머신에서 더 빠른 로컬 전체 스위트 실행: `pnpm test:max` -- 직접 Vitest watch 루프: `pnpm test:watch` +- 직접 Vitest watch 루프 실행: `pnpm test:watch` - 직접 파일 지정은 이제 extension/channel 경로도 라우팅합니다: `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 도구/이미지 프로브): `pnpm test:live` -- 하나의 live 파일만 조용히 대상 지정: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live 스위트(모델 + Gateway 도구/이미지 프로브): `pnpm test:live` +- 하나의 live 파일만 조용히 대상으로 지정: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -팁: 실패하는 단 하나의 케이스만 필요할 때는 아래에 설명된 allowlist 환경 변수를 통해 live 테스트 범위를 좁히는 것을 선호하세요. +팁: 실패한 하나의 케이스만 필요할 때는 아래에 설명된 allowlist 환경 변수를 사용해 live 테스트 범위를 좁히는 것을 권장합니다. -## QA 전용 실행기 +## QA 전용 러너 -이 명령들은 QA-lab 수준의 현실성이 필요할 때 메인 테스트 스위트와 함께 사용합니다. +이 명령들은 QA-lab 현실성이 필요할 때 메인 테스트 스위트와 함께 사용합니다: - `pnpm openclaw qa suite` - - 호스트에서 repo 기반 QA 시나리오를 직접 실행합니다. - - 기본적으로 여러 선택된 시나리오를 격리된 gateway 워커와 함께 병렬 실행하며, 최대 64개 워커 또는 선택된 시나리오 수까지 사용합니다. 워커 수를 조정하려면 `--concurrency `를 사용하고, 예전 직렬 레인을 원하면 `--concurrency 1`을 사용하세요. - - 제공자 모드 `live-frontier`, `mock-openai`, `aimock`를 지원합니다. `aimock`은 시나리오 인지형 `mock-openai` 레인을 대체하지 않으면서 실험적 fixture 및 프로토콜 mock 커버리지를 위해 로컬 AIMock 기반 제공자 서버를 시작합니다. + - 호스트에서 repo-backed QA 시나리오를 직접 실행합니다. + - 기본적으로 격리된 Gateway 워커와 함께 여러 선택된 시나리오를 병렬 실행합니다. `qa-channel`은 기본적으로 동시성 4를 사용합니다(선택된 시나리오 수에 따라 제한됨). 워커 수를 조정하려면 `--concurrency `를 사용하고, 이전의 직렬 레인을 사용하려면 `--concurrency 1`을 사용하세요. + - 어떤 시나리오든 실패하면 0이 아닌 종료 코드를 반환합니다. 실패 종료 코드 없이 아티팩트가 필요하면 `--allow-failures`를 사용하세요. + - 제공자 모드 `live-frontier`, `mock-openai`, `aimock`를 지원합니다. `aimock`은 실험적인 픽스처 및 프로토콜 모의 커버리지를 위해 로컬 AIMock 기반 제공자 서버를 시작하지만, 시나리오 인지형 `mock-openai` 레인을 대체하지는 않습니다. - `pnpm openclaw qa suite --runner multipass` - 동일한 QA 스위트를 일회용 Multipass Linux VM 내부에서 실행합니다. - 호스트의 `qa suite`와 동일한 시나리오 선택 동작을 유지합니다. - `qa suite`와 동일한 제공자/모델 선택 플래그를 재사용합니다. - - live 실행은 게스트에서 실용적인 지원 QA 인증 입력을 전달합니다: - 환경 변수 기반 제공자 키, QA live 제공자 구성 경로, 그리고 존재할 경우 `CODEX_HOME`. + - Live 실행은 게스트에서 실용적인 지원 QA 인증 입력을 전달합니다: + 환경 변수 기반 제공자 키, QA live 제공자 config 경로, 그리고 존재할 경우 `CODEX_HOME`. - 출력 디렉터리는 게스트가 마운트된 워크스페이스를 통해 다시 쓸 수 있도록 repo 루트 아래에 있어야 합니다. - - 일반 QA 리포트 + 요약과 함께 Multipass 로그를 `.artifacts/qa-e2e/...` 아래에 기록합니다. + - 일반 QA 리포트 + 요약과 Multipass 로그를 `.artifacts/qa-e2e/...` 아래에 기록합니다. - `pnpm qa:lab:up` - 운영자 스타일 QA 작업을 위해 Docker 기반 QA 사이트를 시작합니다. - `pnpm openclaw qa aimock` @@ -72,62 +73,62 @@ OpenClaw에는 세 가지 Vitest 스위트(unit/integration, e2e, live)와 소 - `pnpm openclaw qa matrix` - 일회용 Docker 기반 Tuwunel 홈서버를 대상으로 Matrix live QA 레인을 실행합니다. - 이 QA 호스트는 현재 repo/dev 전용입니다. 패키징된 OpenClaw 설치에는 `qa-lab`이 포함되지 않으므로 `openclaw qa`를 노출하지 않습니다. - - repo 체크아웃은 번들된 실행기를 직접 로드하며, 별도의 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는 레인이 로컬에서 일회용 사용자를 프로비저닝하므로 공유 자격 증명 소스 플래그를 노출하지 않습니다. + - Repo 체크아웃은 번들된 러너를 직접 로드하며, 별도의 Plugin 설치 단계가 필요하지 않습니다. + - 세 개의 임시 Matrix 사용자(`driver`, `sut`, `observer`)와 하나의 비공개 room을 프로비저닝한 뒤, 실제 Matrix Plugin을 SUT 전송 수단으로 사용하는 QA Gateway 자식을 시작합니다. + - 기본적으로 고정된 안정 버전 Tuwunel 이미지 `ghcr.io/matrix-construct/tuwunel:v1.5.1`를 사용합니다. 다른 이미지를 테스트해야 할 때는 `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`로 재정의하세요. + - Matrix는 로컬에서 일회용 사용자를 프로비저닝하므로 공유 자격 증명 소스 플래그를 노출하지 않습니다. - Matrix QA 리포트, 요약, observed-events 아티팩트, 그리고 결합된 stdout/stderr 출력 로그를 `.artifacts/qa-e2e/...` 아래에 기록합니다. - `pnpm openclaw qa telegram` - - 환경 변수의 driver 및 SUT 봇 토큰을 사용해 실제 비공개 그룹을 대상으로 Telegram live QA 레인을 실행합니다. + - 환경 변수의 driver 및 SUT bot 토큰을 사용하여 실제 비공개 그룹을 대상으로 Telegram live QA 레인을 실행합니다. - `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`, `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`이 필요합니다. group id는 숫자형 Telegram chat id여야 합니다. - - 공유 풀 자격 증명을 위해 `--credential-source convex`를 지원합니다. 기본적으로 env 모드를 사용하거나, 풀 임대를 사용하려면 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`를 설정하세요. - - 같은 비공개 그룹에 있는 서로 다른 두 봇이 필요하며, SUT 봇은 Telegram 사용자 이름을 노출해야 합니다. - - 안정적인 봇 간 관찰을 위해 `@BotFather`에서 두 봇 모두에 대해 Bot-to-Bot Communication Mode를 활성화하고, driver 봇이 그룹 봇 트래픽을 관찰할 수 있도록 하세요. + - 공유 풀 자격 증명에는 `--credential-source convex`를 지원합니다. 기본적으로 env 모드를 사용하거나, 풀링된 lease를 사용하려면 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`를 설정하세요. + - 어떤 시나리오든 실패하면 0이 아닌 종료 코드를 반환합니다. 실패 종료 코드 없이 아티팩트가 필요하면 `--allow-failures`를 사용하세요. + - 같은 비공개 그룹에 있는 서로 다른 두 bot이 필요하며, SUT bot은 Telegram 사용자 이름을 노출해야 합니다. + - 안정적인 bot 간 관찰을 위해 `@BotFather`에서 두 bot 모두에 대해 Bot-to-Bot Communication Mode를 활성화하고 driver bot이 그룹 bot 트래픽을 관찰할 수 있게 하세요. - Telegram QA 리포트, 요약, observed-messages 아티팩트를 `.artifacts/qa-e2e/...` 아래에 기록합니다. -live 전송 레인은 새 전송이 드리프트하지 않도록 하나의 표준 계약을 공유합니다. +Live transport 레인은 새 transport가 드리프트하지 않도록 하나의 표준 계약을 공유합니다: -`qa-channel`은 여전히 광범위한 합성 QA 스위트이며 live 전송 커버리지 매트릭스의 일부가 아닙니다. +`qa-channel`은 여전히 광범위한 synthetic QA 스위트이며 live transport 커버리지 매트릭스의 일부는 아닙니다. -| 레인 | Canary | 멘션 게이팅 | Allowlist 차단 | 최상위 답글 | 재시작 재개 | 스레드 후속 응답 | 스레드 격리 | 반응 관찰 | 도움말 명령 | -| -------- | ------ | ----------- | -------------- | ----------- | ----------- | ---------------- | ----------- | --------- | ----------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| 레인 | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | +| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | +| 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 기반 풀에서 독점 임대를 획득하고, 레인이 실행되는 동안 해당 임대에 Heartbeat를 보내며, 종료 시 임대를 해제합니다. +`openclaw qa telegram`에 대해 `--credential-source convex`(또는 `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`)가 활성화되면, QA lab은 Convex 기반 풀에서 독점 lease를 획득하고, 레인이 실행되는 동안 해당 lease에 Heartbeat를 보내며, 종료 시 lease를 해제합니다. -참조 Convex 프로젝트 스캐폴드: +참조용 Convex 프로젝트 스캐폴드: - `qa/convex-credential-broker/` 필수 환경 변수: -- `OPENCLAW_QA_CONVEX_SITE_URL`(예: `https://your-deployment.convex.site`) -- 선택한 역할에 대한 비밀 하나: +- `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` (CI에서는 기본값 `ci`, 그 외에는 `maintainer`) 선택적 환경 변수: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS`(기본값 `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS`(기본값 `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS`(기본값 `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS`(기본값 `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX`(기본값 `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID`(선택적 추적 id) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (기본값 `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (기본값 `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (기본값 `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (기본값 `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (기본값 `/qa-credentials/v1`) +- `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://`를 사용해야 합니다. -유지관리자 관리자 명령(풀 추가/제거/목록)은 특별히 -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`가 필요합니다. +관리자 admin 명령(pool 추가/제거/목록)은 반드시 `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`를 요구합니다. -유지관리자를 위한 CLI 헬퍼: +관리자용 CLI 도우미: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -142,40 +143,40 @@ pnpm openclaw qa credentials remove --credential-id - `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`(유지관리자 비밀 전용) + - 성공: `{ status: "ok" }` (또는 빈 `2xx`) +- `POST /admin/add` (maintainer secret 전용) - 요청: `{ kind, actorId, payload, note?, status? }` - 성공: `{ status: "ok", credential }` -- `POST /admin/remove`(유지관리자 비밀 전용) +- `POST /admin/remove` (maintainer secret 전용) - 요청: `{ credentialId, actorId }` - 성공: `{ status: "ok", changed, credential }` - - 활성 임대 가드: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list`(유지관리자 비밀 전용) + - 활성 lease 보호: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (maintainer secret 전용) - 요청: `{ kind?, status?, includePayload?, limit? }` - 성공: `{ status: "ok", credentials, count }` -Telegram kind용 payload 형식: +Telegram kind의 payload 형태: - `{ groupId: string, driverToken: string, sutToken: string }` - `groupId`는 숫자형 Telegram chat id 문자열이어야 합니다. -- `admin/add`는 `kind: "telegram"`에 대해 이 형식을 검증하며 잘못된 payload를 거부합니다. +- `admin/add`는 `kind: "telegram"`에 대해 이 형태를 검증하며 잘못된 payload를 거부합니다. ### QA에 채널 추가하기 -마크다운 QA 시스템에 채널을 추가하려면 정확히 두 가지가 필요합니다. +마크다운 QA 시스템에 채널을 추가하려면 정확히 두 가지가 필요합니다: -1. 해당 채널용 전송 어댑터 -2. 채널 계약을 검증하는 시나리오 팩 +1. 해당 채널용 transport adapter +2. 채널 계약을 검증하는 scenario pack -공유 `qa-lab` 호스트가 흐름을 소유할 수 있을 때 새로운 최상위 QA 명령 루트를 추가하지 마세요. +공유 `qa-lab` 호스트가 흐름을 소유할 수 있다면 새로운 최상위 QA 명령 루트를 추가하지 마세요. -`qa-lab`은 공유 호스트 메커니즘을 소유합니다. +`qa-lab`은 공유 호스트 메커니즘을 소유합니다: - `openclaw qa` 명령 루트 - 스위트 시작 및 종료 @@ -185,37 +186,37 @@ Telegram kind용 payload 형식: - 시나리오 실행 - 이전 `qa-channel` 시나리오용 호환성 별칭 -실행기 plugin은 전송 계약을 소유합니다. +러너 Plugin은 transport 계약을 소유합니다: - `openclaw qa `가 공유 `qa` 루트 아래에 어떻게 마운트되는지 -- 해당 전송에 맞게 Gateway가 어떻게 구성되는지 +- 해당 transport에 맞게 Gateway가 어떻게 구성되는지 - 준비 상태를 어떻게 확인하는지 - 인바운드 이벤트를 어떻게 주입하는지 - 아웃바운드 메시지를 어떻게 관찰하는지 -- 전사본 및 정규화된 전송 상태를 어떻게 노출하는지 -- 전송 기반 작업을 어떻게 실행하는지 -- 전송별 재설정 또는 정리를 어떻게 처리하는지 +- 전사(transcript)와 정규화된 transport 상태를 어떻게 노출하는지 +- transport 기반 작업을 어떻게 실행하는지 +- transport별 reset 또는 정리를 어떻게 처리하는지 -새 채널의 최소 도입 기준은 다음과 같습니다. +새 채널의 최소 도입 기준은 다음과 같습니다: 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 및 실행기 실행은 별도의 엔트리포인트 뒤에 남겨두어야 합니다. +2. 공유 `qa-lab` 호스트 seam에서 transport 러너를 구현합니다. +3. transport 전용 메커니즘은 해당 러너 Plugin 또는 채널 하네스 내부에 유지합니다. +4. 경쟁하는 루트 명령을 등록하는 대신 러너를 `openclaw qa `로 마운트합니다. + 러너 Plugin은 `openclaw.plugin.json`에 `qaRunners`를 선언하고 `runtime-api.ts`에서 일치하는 `qaRunnerCliRegistrations` 배열을 내보내야 합니다. + `runtime-api.ts`는 가볍게 유지하세요. lazy CLI 및 러너 실행은 별도 엔트리포인트 뒤에 유지되어야 합니다. 5. 테마별 `qa/scenarios/` 디렉터리 아래에 마크다운 시나리오를 작성하거나 조정합니다. -6. 새 시나리오에는 일반 시나리오 헬퍼를 사용합니다. -7. repo가 의도적인 마이그레이션을 수행하는 중이 아니라면 기존 호환성 별칭이 계속 동작하도록 유지합니다. +6. 새 시나리오에는 일반적인 scenario helper를 사용합니다. +7. repo가 의도적인 마이그레이션을 수행 중이 아닌 한 기존 호환성 별칭은 계속 동작하게 유지합니다. -결정 규칙은 엄격합니다. +결정 규칙은 엄격합니다: -- 동작을 `qa-lab`에서 한 번 표현할 수 있으면 `qa-lab`에 넣습니다. -- 동작이 하나의 채널 전송에 의존하면 해당 실행기 plugin 또는 plugin 하네스에 둡니다. -- 시나리오가 둘 이상의 채널이 사용할 수 있는 새 기능을 필요로 하면 `suite.ts`에 채널별 분기를 추가하는 대신 일반 헬퍼를 추가합니다. -- 어떤 동작이 오직 하나의 전송에만 의미가 있다면, 해당 시나리오는 전송 전용으로 유지하고 시나리오 계약에서 이를 명시합니다. +- 동작을 `qa-lab`에서 한 번 표현할 수 있다면 `qa-lab`에 두세요. +- 동작이 하나의 채널 transport에 의존한다면 해당 러너 Plugin 또는 Plugin 하네스에 유지하세요. +- 하나 이상의 채널이 사용할 수 있는 새 기능이 시나리오에 필요하다면 `suite.ts`에 채널별 분기를 추가하는 대신 일반적인 helper를 추가하세요. +- 어떤 동작이 하나의 transport에만 의미가 있다면 시나리오를 transport 전용으로 유지하고 시나리오 계약에서 그것을 명시하세요. -새 시나리오에 권장되는 일반 헬퍼 이름은 다음과 같습니다. +새 시나리오에 권장되는 일반 helper 이름은 다음과 같습니다: - `waitForTransportReady` - `waitForChannelReady` @@ -230,7 +231,7 @@ Telegram kind용 payload 형식: - `formatTransportTranscript` - `resetTransport` -기존 시나리오를 위해 다음을 포함한 호환성 별칭도 계속 사용할 수 있습니다. +기존 시나리오를 위한 호환성 별칭은 계속 사용할 수 있으며, 다음을 포함합니다: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -238,131 +239,131 @@ Telegram kind용 payload 형식: - `formatConversationTranscript` - `resetBus` -새 채널 작업에는 일반 헬퍼 이름을 사용해야 합니다. -호환성 별칭은 플래그 데이 마이그레이션을 피하기 위해 존재하는 것이지, 새 시나리오 작성의 모델이 아닙니다. +새 채널 작업에는 일반 helper 이름을 사용해야 합니다. +호환성 별칭은 일괄 전환(flag day) 마이그레이션을 피하기 위해 존재하는 것이며, +새 시나리오 작성의 모델로 삼기 위한 것은 아닙니다. -## 테스트 스위트(어디서 무엇이 실행되는지) +## 테스트 스위트(어디서 무엇이 실행되는가) -스위트는 “현실성이 점점 높아지는 것”으로 생각하면 됩니다(그리고 불안정성/비용도 함께 증가합니다). +스위트는 “현실성이 점점 높아지는 것”으로 생각하면 됩니다(그리고 불안정성/비용도 함께 증가합니다): -### Unit / integration(기본값) +### Unit / integration (기본값) - 명령: `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 테스트 +- 구성: 기존 범위별 Vitest 프로젝트에 대해 10개의 순차 shard 실행(`vitest.full-*.config.ts`) +- 파일: `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` 아래의 core/unit 인벤토리와 `vitest.unit.config.ts`가 포함하는 허용된 `ui` node 테스트 - 범위: - 순수 unit 테스트 - - 프로세스 내부 integration 테스트(gateway auth, routing, tooling, parsing, config) - - 알려진 버그에 대한 결정적 회귀 테스트 + - 프로세스 내 integration 테스트(Gateway 인증, 라우팅, 도구, 파싱, config) + - 알려진 버그에 대한 결정론적 회귀 테스트 - 기대 사항: - CI에서 실행됨 - - 실제 키 불필요 + - 실제 키 필요 없음 - 빠르고 안정적이어야 함 - 프로젝트 참고: - - 범위를 지정하지 않은 `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`는 다중 샤드 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 헬퍼, `plugin-sdk` 및 유사한 순수 유틸리티 영역의 import가 가벼운 unit 테스트는 `unit-fast` 레인을 통해 라우팅되며, 이 레인은 `test/setup-openclaw-runtime.ts`를 건너뜁니다. 상태가 있거나 런타임 부담이 큰 파일은 기존 레인에 남습니다. - - 선택된 `plugin-sdk` 및 `commands` 헬퍼 소스 파일도 변경 모드 실행을 이러한 가벼운 레인의 명시적 형제 테스트에 매핑하므로, 헬퍼 편집 시 해당 디렉터리의 전체 무거운 스위트를 다시 실행하지 않아도 됩니다. - - `auto-reply`는 이제 세 개의 전용 버킷을 가집니다: 최상위 core 헬퍼, 최상위 `reply.*` integration 테스트, 그리고 `src/auto-reply/reply/**` 하위 트리. 이렇게 하면 가장 무거운 reply 하네스 작업이 가벼운 status/chunk/token 테스트에 섞이지 않습니다. -- 임베디드 실행기 참고: - - 메시지 도구 탐색 입력이나 Compaction 런타임 컨텍스트를 변경할 때는 - 두 수준의 커버리지를 모두 유지하세요. - - 순수 routing/normalization 경계에 대해서는 집중된 헬퍼 회귀 테스트를 추가하세요. - - 또한 임베디드 실행기 integration 스위트도 정상 상태를 유지해야 합니다: + - 이제 대상 지정이 없는 `pnpm test`는 하나의 거대한 네이티브 루트 프로젝트 프로세스 대신 11개의 더 작은 shard config(`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`는 다중 shard 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` 레인으로 라우팅되며, 상태 보유/런타임이 무거운 파일은 기존 레인에 남습니다. + - 선택된 `plugin-sdk`와 `commands` helper 소스 파일도 changed-mode 실행을 이러한 가벼운 레인의 명시적 sibling 테스트에 매핑하므로 helper 수정 시 해당 디렉터리의 전체 무거운 스위트를 다시 실행하지 않아도 됩니다. + - 이제 `auto-reply`는 전용 버킷 세 개를 가집니다: 최상위 core helper, 최상위 `reply.*` integration 테스트, 그리고 `src/auto-reply/reply/**` 하위 트리. 이렇게 하면 가장 무거운 reply 하네스 작업이 저렴한 status/chunk/token 테스트와 분리됩니다. +- Embedded runner 참고: + - 메시지 도구 검색 입력이나 Compaction 런타임 컨텍스트를 변경할 때는 두 수준의 커버리지를 모두 유지하세요. + - 순수 라우팅/정규화 경계에 대해서는 집중된 helper 회귀 테스트를 추가하세요. + - 또한 embedded runner integration 스위트도 건강하게 유지해야 합니다: `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`. - - 이 스위트들은 scoped id와 Compaction 동작이 실제 `run.ts` / `compact.ts` 경로를 통해 계속 흐르는지 검증합니다. 헬퍼 전용 테스트만으로는 이러한 integration 경로를 충분히 대체할 수 없습니다. -- 풀 참고: - - 기본 Vitest 구성은 이제 기본값으로 `threads`를 사용합니다. - - 공유 Vitest 구성은 또한 `isolate: false`를 고정하고 루트 프로젝트, e2e, live 구성 전반에서 비격리 실행기를 사용합니다. - - 루트 UI 레인은 `jsdom` setup 및 optimizer를 유지하지만, 이제 공유 비격리 실행기에서도 동작합니다. - - 각 `pnpm test` 샤드는 공유 Vitest 구성에서 동일한 `threads` + `isolate: false` 기본값을 상속받습니다. - - 공유 `scripts/run-vitest.mjs` 실행기는 이제 큰 로컬 실행 중 V8 컴파일 churn을 줄이기 위해 기본적으로 Vitest 자식 Node 프로세스에 `--no-maglev`도 추가합니다. 기본 V8 동작과 비교해야 하면 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`을 설정하세요. + - 이러한 스위트는 범위 지정된 id와 Compaction 동작이 여전히 실제 `run.ts` / `compact.ts` 경로를 통해 흐른다는 것을 검증합니다. helper 전용 테스트만으로는 이러한 integration 경로를 충분히 대체할 수 없습니다. +- Pool 참고: + - 기본 Vitest config는 이제 기본적으로 `threads`를 사용합니다. + - 공유 Vitest config는 또한 `isolate: false`를 고정하고 루트 프로젝트, e2e, live config 전반에서 비격리 러너를 사용합니다. + - 루트 UI 레인은 `jsdom` setup과 optimizer를 유지하지만 이제 공유 비격리 러너에서 실행됩니다. + - 각 `pnpm test` shard는 공유 Vitest config에서 동일한 `threads` + `isolate: false` 기본값을 상속합니다. + - 공유 `scripts/run-vitest.mjs` 런처는 이제 큰 로컬 실행 중 V8 컴파일 churn을 줄이기 위해 기본적으로 Vitest 하위 Node 프로세스에 `--no-maglev`도 추가합니다. 기본 V8 동작과 비교가 필요하면 `OPENCLAW_VITEST_ENABLE_MAGLEV=1`을 설정하세요. - 빠른 로컬 반복 참고: - - `pnpm test:changed`는 변경된 경로가 더 작은 스위트에 깔끔하게 매핑되면 범위 지정 레인을 통해 라우팅합니다. - - `pnpm test:max`와 `pnpm test:changed:max`도 동일한 라우팅 동작을 유지하되, 워커 상한만 더 높습니다. - - 로컬 워커 자동 스케일링은 이제 의도적으로 보수적이며 호스트 load average가 이미 높을 때도 백오프하므로, 여러 개의 동시 Vitest 실행이 기본적으로 덜 큰 피해를 주게 됩니다. - - 기본 Vitest 구성은 프로젝트/구성 파일을 `forceRerunTriggers`로 표시하므로 테스트 wiring이 바뀌어도 changed 모드 재실행의 정확성이 유지됩니다. - - 이 구성은 지원되는 호스트에서 `OPENCLAW_VITEST_FS_MODULE_CACHE`를 계속 활성화합니다. 직접 프로파일링을 위한 명시적 캐시 위치 하나를 원하면 `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`를 설정하세요. + - `pnpm test:changed`는 변경된 경로가 더 작은 스위트에 깔끔하게 매핑될 때 범위별 레인을 통해 라우팅됩니다. + - `pnpm test:max`와 `pnpm test:changed:max`도 동일한 라우팅 동작을 유지하되, 더 높은 worker 상한만 사용합니다. + - 이제 로컬 worker 자동 확장은 의도적으로 더 보수적으로 동작하며 호스트 load average가 이미 높은 경우에도 물러나므로, 여러 동시 Vitest 실행이 기본적으로 덜 큰 피해를 주게 됩니다. + - 기본 Vitest config는 프로젝트/config 파일을 `forceRerunTriggers`로 표시해 changed-mode 재실행이 테스트 wiring 변경 시에도 올바르게 유지되도록 합니다. + - 이 config는 지원되는 호스트에서 `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 max RSS를 출력합니다. -- `pnpm test:perf:changed:bench -- --worktree`는 변경된 파일 목록을 `scripts/test-projects.mjs`와 루트 Vitest 구성에 라우팅하여 현재 dirty 트리를 벤치마크합니다. + - `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 config를 통해 라우팅하여 현재 dirty tree를 벤치마크합니다. - `pnpm test:perf:profile:main`은 Vitest/Vite 시작 및 transform 오버헤드에 대한 메인 스레드 CPU 프로파일을 기록합니다. - - `pnpm test:perf:profile:runner`는 파일 병렬성을 비활성화한 unit 스위트에 대한 실행기 CPU+힙 프로파일을 기록합니다. + - `pnpm test:perf:profile:runner`는 파일 병렬화를 비활성화한 unit 스위트에 대해 러너 CPU+힙 프로파일을 기록합니다. -### E2E(Gateway 스모크) +### E2E (Gateway 스모크) - 명령: `pnpm test:e2e` - 구성: `vitest.e2e.config.ts` - 파일: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - 런타임 기본값: - - repo의 나머지와 동일하게 Vitest `threads`와 `isolate: false`를 사용합니다. - - 적응형 워커를 사용합니다(CI: 최대 2, 로컬: 기본 1). + - repo의 나머지와 일치하게 Vitest `threads`와 `isolate: false`를 사용합니다. + - 적응형 worker를 사용합니다(CI: 최대 2, 로컬: 기본 1). - 콘솔 I/O 오버헤드를 줄이기 위해 기본적으로 silent 모드로 실행됩니다. - 유용한 재정의: - - 워커 수를 강제하려면 `OPENCLAW_E2E_WORKERS=`(상한 16) + - worker 수를 강제하려면 `OPENCLAW_E2E_WORKERS=`(상한 16) - 자세한 콘솔 출력을 다시 활성화하려면 `OPENCLAW_E2E_VERBOSE=1` - 범위: - 다중 인스턴스 Gateway end-to-end 동작 - - WebSocket/HTTP 표면, node 페어링, 더 무거운 네트워킹 + - WebSocket/HTTP 표면, Node 페어링, 더 무거운 네트워킹 - 기대 사항: - CI에서 실행됨(파이프라인에서 활성화된 경우) - - 실제 키 불필요 - - unit 테스트보다 움직이는 부분이 많음(더 느릴 수 있음) + - 실제 키 필요 없음 + - unit 테스트보다 움직이는 부품이 더 많음(더 느릴 수 있음) ### 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를 통해 원격 canonical filesystem 동작을 검증 + - Docker를 통해 호스트에서 격리된 OpenShell Gateway를 시작합니다. + - 임시 로컬 Dockerfile에서 sandbox를 생성합니다. + - 실제 `sandbox ssh-config` + SSH exec를 통해 OpenClaw의 OpenShell 백엔드를 실행합니다. + - sandbox fs bridge를 통해 원격 canonical 파일시스템 동작을 검증합니다. - 기대 사항: - 옵트인 전용이며 기본 `pnpm test:e2e` 실행에는 포함되지 않음 - - 로컬 `openshell` CLI와 동작하는 Docker daemon 필요 + - 로컬 `openshell` CLI와 동작하는 Docker 데몬이 필요함 - 격리된 `HOME` / `XDG_CONFIG_HOME`을 사용한 뒤 테스트 Gateway와 sandbox를 제거함 - 유용한 재정의: - 더 넓은 e2e 스위트를 수동 실행할 때 테스트를 활성화하려면 `OPENCLAW_E2E_OPENSHELL=1` - - 기본이 아닌 CLI 바이너리나 wrapper 스크립트를 가리키려면 `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` + - 기본이 아닌 CLI 바이너리나 wrapper script를 가리키려면 `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` -### Live(실제 제공자 + 실제 모델) +### 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 동작 포착 + - “이 제공자/모델이 오늘 실제 자격 증명으로 실제로 동작하는가?” + - 제공자 포맷 변경, tool-calling 특이점, 인증 이슈, rate limit 동작 포착 - 기대 사항: - - 설계상 CI에서 안정적이지 않음(실제 네트워크, 실제 제공자 정책, quota, 장애) - - 비용이 들고 / rate limit을 사용함 - - “전부”보다는 범위를 좁힌 하위 집합 실행을 선호 -- live 실행은 누락된 API 키를 가져오기 위해 `~/.profile`을 소싱합니다. -- 기본적으로 live 실행은 여전히 `HOME`을 격리하고 config/auth 자료를 임시 테스트 홈으로 복사하므로 unit fixture가 실제 `~/.openclaw`를 변경할 수 없습니다. + - 의도적으로 CI-안정적이지 않음(실제 네트워크, 실제 제공자 정책, 할당량, 장애) + - 비용이 들고 / rate limit를 사용함 + - “전부”보다는 좁혀진 부분 집합 실행을 권장 +- Live 실행은 누락된 API 키를 가져오기 위해 `~/.profile`을 source합니다. +- 기본적으로 live 실행은 여전히 `HOME`을 격리하고 config/auth 자료를 임시 테스트 홈에 복사하므로 unit 픽스처가 실제 `~/.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 응답 시 재시도합니다. +- 이제 `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 응답 시 재시도합니다. - 진행/Heartbeat 출력: - - live 스위트는 이제 진행 라인을 stderr로 출력하므로, Vitest 콘솔 캡처가 조용한 경우에도 긴 제공자 호출이 눈에 띄게 활성 상태로 보입니다. + - 이제 live 스위트는 진행 라인을 stderr에 출력하므로 Vitest 콘솔 캡처가 조용한 경우에도 긴 제공자 호출이 눈에 보이게 활성 상태로 표시됩니다. - `vitest.live.config.ts`는 Vitest 콘솔 가로채기를 비활성화하므로 제공자/Gateway 진행 라인이 live 실행 중 즉시 스트리밍됩니다. - 직접 모델 Heartbeat는 `OPENCLAW_LIVE_HEARTBEAT_MS`로 조정합니다. - Gateway/프로브 Heartbeat는 `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`로 조정합니다. ## 어떤 스위트를 실행해야 하나요? -다음 결정표를 사용하세요. +다음 결정 표를 사용하세요: -- 로직/테스트를 편집하는 경우: `pnpm test` 실행(많이 바꿨다면 `pnpm test:coverage`도) -- Gateway 네트워킹 / WS 프로토콜 / 페어링을 건드리는 경우: `pnpm test:e2e` 추가 -- “내 봇이 죽었어요” / 제공자별 실패 / tool calling 디버깅: 범위를 좁힌 `pnpm test:live` 실행 +- 로직/테스트를 수정 중: `pnpm test` 실행(많이 변경했다면 `pnpm test:coverage`도) +- Gateway 네트워킹 / WS 프로토콜 / 페어링을 건드림: `pnpm test:e2e` 추가 +- “내 bot이 죽었다” / 제공자별 실패 / tool calling 디버깅 중: 범위를 좁힌 `pnpm test:live` 실행 ## Live: Android Node capability 스윕 @@ -370,84 +371,84 @@ Telegram kind용 payload 형식: - 스크립트: `pnpm android:test:integration` - 목표: 연결된 Android Node가 현재 광고하는 **모든 명령**을 호출하고 명령 계약 동작을 검증합니다. - 범위: - - 사전 조건/수동 setup 기반(이 스위트는 앱을 설치/실행/페어링하지 않음) + - 사전 준비/수동 설정 필요(이 스위트는 앱을 설치/실행/페어링하지 않음) - 선택된 Android Node에 대한 명령별 Gateway `node.invoke` 검증 -- 필요한 사전 setup: +- 필요한 사전 설정: - Android 앱이 이미 Gateway에 연결되고 페어링되어 있어야 함 - - 앱이 포그라운드에 유지되어야 함 - - 통과를 기대하는 capability에 대한 권한/캡처 동의가 부여되어 있어야 함 + - 앱이 포그라운드 상태로 유지되어야 함 + - 통과시키려는 capability에 필요한 권한/캡처 동의가 부여되어 있어야 함 - 선택적 대상 재정의: - `OPENCLAW_ANDROID_NODE_ID` 또는 `OPENCLAW_ANDROID_NODE_NAME` - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD` -- 전체 Android setup 세부 정보: [Android App](/ko/platforms/android) +- 전체 Android 설정 세부 정보: [Android App](/ko/platforms/android) ## Live: 모델 스모크(profile 키) -live 테스트는 실패를 격리할 수 있도록 두 계층으로 나뉩니다. +Live 테스트는 실패를 분리할 수 있도록 두 계층으로 나뉩니다: -- “직접 모델”은 주어진 키로 제공자/모델이 최소한 응답할 수 있는지를 알려줍니다. -- “Gateway 스모크”는 전체 Gateway+에이전트 파이프라인이 해당 모델에서 동작하는지를 알려줍니다(세션, 기록, 도구, sandbox 정책 등). +- “직접 모델”은 주어진 키로 제공자/모델이 응답 자체를 할 수 있는지 알려줍니다. +- “Gateway 스모크”는 해당 모델에 대해 전체 Gateway+에이전트 파이프라인(세션, 히스토리, 도구, sandbox 정책 등)이 동작하는지 알려줍니다. -### 계층 1: 직접 모델 completion(무 Gateway) +### 계층 1: 직접 모델 completion (Gateway 없음) - 테스트: `src/agents/models.profiles.live.test.ts` - 목표: - - 탐지된 모델 열거 + - 발견된 모델 나열 - `getApiKeyForModel`을 사용해 자격 증명이 있는 모델 선택 - 모델별로 작은 completion 실행(필요한 경우 대상 회귀 테스트 포함) - 활성화 방법: - - `pnpm test:live`(또는 Vitest를 직접 호출할 경우 `OPENCLAW_LIVE_TEST=1`) -- 이 스위트를 실제로 실행하려면 `OPENCLAW_LIVE_MODELS=modern`(또는 modern의 별칭인 `all`)을 설정하세요. 그렇지 않으면 `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 스윕은 기본적으로 엄선된 고신호 상한을 사용합니다. exhaustive modern 스윕을 원하면 `OPENCLAW_LIVE_MAX_MODELS=0`, 더 작은 상한을 원하면 양수를 설정하세요. + - modern 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`은 modern allowlist의 별칭입니다 + - 또는 `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."`(콤마 allowlist) + - modern/all 스윕은 기본적으로 선별된 고신호 상한을 사용합니다. exhaustive modern 스윕을 하려면 `OPENCLAW_LIVE_MAX_MODELS=0`을 설정하고, 더 작은 상한을 원하면 양수를 설정하세요. - 제공자 선택 방법: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`(쉼표 allowlist) -- 키 출처: - - 기본값: 프로필 저장소 및 환경 변수 폴백 - - **프로필 저장소**만 강제하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 설정 + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`(콤마 allowlist) +- 키의 출처: + - 기본값: profile store 및 env fallback + - **profile store**만 강제하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 설정 - 이것이 존재하는 이유: - - “제공자 API가 깨졌는가 / 키가 유효하지 않은가”를 “Gateway 에이전트 파이프라인이 깨졌는가”와 분리 - - 작고 격리된 회귀 테스트 포함(예: OpenAI Responses/Codex Responses reasoning replay + tool-call 흐름) + - “제공자 API가 고장남 / 키가 유효하지 않음”과 “Gateway 에이전트 파이프라인이 고장남”을 분리합니다 + - 작고 격리된 회귀 테스트를 담습니다(예: OpenAI Responses/Codex Responses reasoning replay + tool-call 흐름) ### 계층 2: Gateway + dev 에이전트 스모크(실제로 `@openclaw`가 하는 일) - 테스트: `src/gateway/gateway-models.profiles.live.test.ts` - 목표: - - 프로세스 내부 Gateway 시작 - - `agent:dev:*` 세션 생성/패치(실행마다 모델 재정의) - - 키가 있는 모델들을 순회하며 다음을 검증: + - 프로세스 내 Gateway 시작 + - `agent:dev:*` 세션 생성/패치(실행별 모델 재정의) + - 키가 있는 모델을 순회하며 다음을 검증: - “의미 있는” 응답(도구 없음) - - 실제 도구 호출 동작(read probe) - - 선택적 추가 도구 프로브(exec+read probe) - - OpenAI 회귀 경로(tool-call-only → 후속 응답)가 계속 동작함 + - 실제 도구 호출이 동작함(`read` 프로브) + - 선택적 추가 도구 프로브(`exec+read` 프로브) + - OpenAI 회귀 경로(tool-call-only → 후속)가 계속 동작함 - 프로브 세부 정보(실패를 빠르게 설명할 수 있도록): - - `read` probe: 테스트가 워크스페이스에 nonce 파일을 쓰고, 에이전트에게 그것을 `read`해서 nonce를 다시 에코하게 요청합니다. - - `exec+read` probe: 테스트가 에이전트에게 `exec`로 temp 파일에 nonce를 쓰고, 그다음 다시 `read`하게 요청합니다. - - image probe: 테스트가 생성된 PNG(고양이 + 무작위 코드)를 첨부하고 모델이 `cat `를 반환할 것으로 기대합니다. + - `read` 프로브: 테스트가 워크스페이스에 nonce 파일을 쓰고 에이전트에게 이를 `read`하고 nonce를 다시 응답에 포함하라고 요청합니다. + - `exec+read` 프로브: 테스트가 에이전트에게 `exec`로 임시 파일에 nonce를 쓴 다음 이를 다시 `read`하게 요청합니다. + - image 프로브: 테스트가 생성된 PNG(cat + 무작위 코드)를 첨부하고 모델이 `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 스윕은 기본적으로 엄선된 고신호 상한을 사용합니다. exhaustive modern 스윕을 원하면 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`, 더 작은 상한을 원하면 양수를 설정하세요. + - 기본값: modern allowlist(Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all`은 modern allowlist의 별칭입니다 + - 또는 범위를 좁히기 위해 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`(또는 콤마 목록) 설정 + - modern/all Gateway 스윕은 기본적으로 선별된 고신호 상한을 사용합니다. exhaustive modern 스윕을 하려면 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0`을 설정하고, 더 작은 상한을 원하면 양수를 설정하세요. - 제공자 선택 방법(“OpenRouter 전체” 방지): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`(쉼표 allowlist) -- 도구 + 이미지 프로브는 이 live 테스트에서 항상 활성화됩니다: - - `read` probe + `exec+read` probe(도구 스트레스) - - 모델이 이미지 입력 지원을 광고하면 image probe 실행 + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`(콤마 allowlist) +- 이 live 테스트에서는 tool + image 프로브가 항상 켜져 있습니다: + - `read` 프로브 + `exec+read` 프로브(도구 스트레스) + - 모델이 image input 지원을 광고하면 image 프로브 실행 - 흐름(상위 수준): - 테스트가 “CAT” + 무작위 코드가 있는 작은 PNG를 생성합니다(`src/gateway/live-image-probe.ts`) - - `agent` `attachments: [{ mimeType: "image/png", content: "" }]`를 통해 전송합니다 + - 이를 `agent` `attachments: [{ mimeType: "image/png", content: "" }]`로 전송합니다 - Gateway가 첨부 파일을 `images[]`로 파싱합니다(`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - 임베디드 에이전트가 멀티모달 사용자 메시지를 모델로 전달합니다 - - 검증: 응답에 `cat` + 해당 코드가 포함되어야 합니다(OCR 허용: 사소한 실수 허용) + - embedded 에이전트가 멀티모달 사용자 메시지를 모델로 전달합니다 + - 검증: 응답에 `cat` + 코드가 포함됨(OCR 허용 오차: 사소한 실수 허용) -팁: 자신의 머신에서 무엇을 테스트할 수 있는지(그리고 정확한 `provider/model` id)를 보려면 다음을 실행하세요. +팁: 내 머신에서 무엇을 테스트할 수 있는지(그리고 정확한 `provider/model` id)를 보려면 다음을 실행하세요: ```bash openclaw models list @@ -458,23 +459,23 @@ openclaw models list --json - 테스트: `src/gateway/gateway-cli-backend.live.test.ts` - 목표: 기본 config를 건드리지 않고 로컬 CLI 백엔드를 사용해 Gateway + 에이전트 파이프라인을 검증합니다. -- 백엔드별 스모크 기본값은 해당 백엔드를 소유하는 extension의 `cli-backend.ts` 정의에 있습니다. +- 백엔드별 스모크 기본값은 해당 소유 extension의 `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 메타데이터에서 가져옵니다. + - command/args/image 동작은 소유 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"`) + - 실제 image 첨부 파일을 보내려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`(경로는 프롬프트에 주입됨) + - 프롬프트 주입 대신 image 파일 경로를 CLI 인수로 전달하려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` + - `IMAGE_ARG`가 설정된 경우 image 인수 전달 방식을 제어하려면 `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`(또는 `"list"`) - 두 번째 턴을 보내고 resume 흐름을 검증하려면 `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` - - 기본 Claude Sonnet -> Opus 동일 세션 연속성 프로브를 비활성화하려면 `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`(선택된 모델이 전환 대상을 지원할 때 강제로 활성화하려면 `1`) - + - 기본 Claude Sonnet -> Opus 동일 세션 연속성 프로브를 비활성화하려면 `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`(선택한 모델이 전환 대상을 지원할 때 강제로 켜려면 `1`) + 예시: ```bash @@ -500,28 +501,28 @@ pnpm test:docker:live-cli-backend:gemini 참고: -- Docker 실행기는 `scripts/test-live-cli-backend-docker.sh`에 있습니다. -- repo Docker 이미지 내부에서 non-root `node` 사용자로 live CLI-backend 스모크를 실행합니다. -- 해당 extension에서 CLI 스모크 메타데이터를 해석한 다음, 일치하는 Linux CLI 패키지(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)를 `OPENCLAW_DOCKER_CLI_TOOLS_DIR`(기본값: `~/.cache/openclaw/docker-cli-tools`)의 캐시된 쓰기 가능한 prefix에 설치합니다. -- `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-key 환경 변수를 유지하지 않고 두 번의 Gateway CLI-backend 턴을 실행합니다. 이 subscription 레인은 Claude가 현재 서드파티 앱 사용을 일반 subscription 플랜 한도가 아닌 추가 사용량 청구로 라우팅하기 때문에 기본적으로 Claude MCP/tool 및 image 프로브를 비활성화합니다. -- live CLI-backend 스모크는 이제 Claude, Codex, Gemini에 대해 동일한 end-to-end 흐름을 검증합니다: 텍스트 턴, 이미지 분류 턴, 그리고 gateway CLI를 통해 검증되는 MCP `cron` 도구 호출. -- Claude의 기본 스모크는 세션을 Sonnet에서 Opus로 패치하고 재개된 세션이 이전 메모를 여전히 기억하는지도 검증합니다. +- Docker 러너는 `scripts/test-live-cli-backend-docker.sh`에 있습니다. +- 이 러너는 repo 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 setup-token`의 `CLAUDE_CODE_OAUTH_TOKEN` 또는 `claudeAiOauth.subscriptionType`이 포함된 `~/.claude/.credentials.json`을 통한 portable Claude Code subscription OAuth가 필요합니다. 먼저 Docker에서 직접 `claude -p`를 증명한 다음, Anthropic API-key env var를 유지하지 않은 채 두 번의 Gateway CLI 백엔드 턴을 실행합니다. 이 subscription 레인은 Claude가 현재 일반 subscription 플랜 제한 대신 추가 사용량 과금을 통해 서드파티 앱 사용을 라우팅하므로 Claude MCP/tool 및 image 프로브를 기본적으로 비활성화합니다. +- 이제 live CLI 백엔드 스모크는 Claude, Codex, Gemini에 대해 동일한 end-to-end 흐름을 실행합니다: 텍스트 턴, image 분류 턴, 그다음 Gateway CLI를 통해 검증되는 MCP `cron` 도구 호출. +- Claude의 기본 스모크는 또한 세션을 Sonnet에서 Opus로 패치하고 재개된 세션이 이전 메모를 여전히 기억하는지 검증합니다. ## Live: ACP bind 스모크(`/acp spawn ... --bind here`) - 테스트: `src/gateway/gateway-acp-bind.live.test.ts` -- 목표: live ACP 에이전트로 실제 ACP 대화 바인드 흐름을 검증합니다: +- 목표: live ACP 에이전트로 실제 ACP 대화 bind 흐름을 검증합니다: - `/acp spawn --bind here` 전송 - - 합성 메시지 채널 대화를 해당 위치에 바인드 + - synthetic 메시지 채널 대화를 제자리에서 bind - 같은 대화에서 일반 후속 메시지 전송 - - 후속 메시지가 바인드된 ACP 세션 전사본에 도착하는지 검증 + - 후속 메시지가 bind된 ACP 세션 transcript에 도착하는지 검증 - 활성화: - `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` - - 합성 채널: Slack DM 스타일 대화 컨텍스트 + - Synthetic 채널: Slack DM 스타일 대화 컨텍스트 - ACP 백엔드: `acpx` - 재정의: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -530,8 +531,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 전용 합성 originating-route 필드와 함께 Gateway `chat.send` 표면을 사용하므로, 테스트가 외부로 실제 전달하는 척하지 않고도 메시지 채널 컨텍스트를 첨부할 수 있습니다. - - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`가 설정되지 않은 경우 테스트는 선택한 ACP 하네스 에이전트에 대해 임베디드 `acpx` plugin의 내장 에이전트 레지스트리를 사용합니다. + - 이 레인은 관리자 전용 synthetic originating-route 필드가 있는 Gateway `chat.send` 표면을 사용하므로 테스트가 외부 전달을 가장하지 않고도 메시지 채널 컨텍스트를 연결할 수 있습니다. + - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND`가 설정되지 않은 경우 테스트는 선택된 ACP 하네스 에이전트에 대해 embedded `acpx` Plugin의 내장 에이전트 레지스트리를 사용합니다. 예시: @@ -557,27 +558,32 @@ pnpm test:docker:live-acp-bind:gemini Docker 참고: -- Docker 실행기는 `scripts/test-live-acp-bind-docker.sh`에 있습니다. -- 기본적으로 지원되는 모든 live CLI 에이전트(`claude`, `codex`, `gemini`)를 순서대로 대상으로 ACP bind 스모크를 실행합니다. -- 매트릭스 범위를 좁히려면 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, 또는 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`를 사용하세요. -- `~/.profile`을 소싱하고, 일치하는 CLI auth 자료를 컨테이너에 스테이징하고, 쓰기 가능한 npm prefix에 `acpx`를 설치한 다음, 요청된 live CLI(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)가 없으면 설치합니다. -- Docker 내부에서 실행기는 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`를 설정하므로, 소싱된 프로필의 제공자 환경 변수를 acpx가 자식 하네스 CLI에 계속 전달할 수 있습니다. +- Docker 러너는 `scripts/test-live-acp-bind-docker.sh`에 있습니다. +- 기본적으로 지원되는 모든 live CLI 에이전트(`claude`, `codex`, `gemini`)에 대해 순서대로 ACP bind 스모크를 실행합니다. +- 매트릭스를 좁히려면 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, 또는 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`를 사용하세요. +- `~/.profile`을 source하고, 일치하는 CLI auth 자료를 컨테이너에 stage한 다음, 쓰기 가능한 npm prefix에 `acpx`를 설치하고, 없으면 요청된 live CLI(`@anthropic-ai/claude-code`, `@openai/codex`, 또는 `@google/gemini-cli`)를 설치합니다. +- Docker 내부에서 러너는 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`를 설정하므로 acpx가 source된 profile의 제공자 env var를 자식 하네스 CLI에서 계속 사용할 수 있습니다. ## Live: 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` 실행 + - `codex/gpt-5.4`에 첫 번째 Gateway 에이전트 턴 전송 + - 동일한 OpenClaw 세션에 두 번째 턴을 전송하고 app-server + thread가 resume할 수 있는지 검증 + - 동일한 Gateway 명령 + 경로를 통해 `/codex status` 및 `/codex models` 실행 - 테스트: `src/gateway/gateway-codex-harness.live.test.ts` - 활성화: `OPENCLAW_LIVE_CODEX_HARNESS=1` - 기본 모델: `codex/gpt-5.4` -- 선택적 이미지 프로브: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- 선택적 image 프로브: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - 선택적 MCP/tool 프로브: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- 이 스모크는 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 설정하므로, 깨진 Codex 하네스가 조용히 PI로 폴백해서 통과할 수 없습니다. -- 인증: 셸/프로필의 `OPENAI_API_KEY`, 그리고 선택적으로 복사된 `~/.codex/auth.json` 및 `~/.codex/config.toml` +- 이 스모크는 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 설정하므로 고장난 Codex + 하네스가 조용히 PI로 fallback하여 통과할 수 없습니다. +- 인증: 셸/profile의 `OPENAI_API_KEY`, 그리고 선택적으로 복사된 + `~/.codex/auth.json` 및 `~/.codex/config.toml` 로컬 레시피: @@ -599,22 +605,22 @@ pnpm test:docker:live-codex-harness Docker 참고: -- Docker 실행기는 `scripts/test-live-codex-harness-docker.sh`에 있습니다. -- 마운트된 `~/.profile`을 소싱하고, `OPENAI_API_KEY`를 전달하며, Codex CLI - auth 파일이 있으면 복사하고, 쓰기 가능한 마운트된 npm - prefix에 `@openai/codex`를 설치한 다음, 소스 트리를 스테이징하고, Codex-harness live 테스트만 실행합니다. -- Docker는 기본적으로 이미지 및 MCP/tool 프로브를 활성화합니다. 더 좁은 범위의 디버그 실행이 필요하면 +- Docker 러너는 `scripts/test-live-codex-harness-docker.sh`에 있습니다. +- 마운트된 `~/.profile`을 source하고, `OPENAI_API_KEY`를 전달하며, Codex CLI + 인증 파일이 있으면 복사하고, `@openai/codex`를 쓰기 가능한 마운트된 npm + prefix에 설치하고, 소스 트리를 stage한 다음, Codex-harness live 테스트만 실행합니다. +- Docker는 기본적으로 image 및 MCP/tool 프로브를 활성화합니다. 더 좁은 디버그 실행이 필요하면 `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 harness +- Docker는 또한 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`을 export하며, 이는 live + 테스트 config와 일치하므로 `openai-codex/*` 또는 PI fallback이 Codex harness 회귀를 숨길 수 없습니다. ### 권장 live 레시피 -범위를 좁힌 명시적 allowlist가 가장 빠르고 가장 불안정성이 적습니다. +좁고 명시적인 allowlist가 가장 빠르고 가장 덜 불안정합니다: -- 단일 모델, 직접 실행(무 Gateway): +- 단일 모델, 직접 실행(Gateway 없음): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - 단일 모델, Gateway 스모크: @@ -623,7 +629,7 @@ Docker 참고: - 여러 제공자에 걸친 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): +- Google 중심(Gemini API 키 + Antigravity): - Gemini(API 키): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity(OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` @@ -631,85 +637,85 @@ Docker 참고: - `google/...`는 Gemini API(API 키)를 사용합니다. - `google-antigravity/...`는 Antigravity OAuth 브리지(Cloud Code Assist 스타일 에이전트 엔드포인트)를 사용합니다. -- `google-gemini-cli/...`는 머신에 있는 로컬 Gemini CLI를 사용합니다(별도 auth + tooling 특이점). -- Gemini API와 Gemini CLI의 차이: - - API: OpenClaw가 HTTP를 통해 Google의 호스팅된 Gemini API를 호출합니다(API 키 / 프로필 auth). 대부분의 사용자가 “Gemini”라고 말할 때 의미하는 것은 이것입니다. - - CLI: OpenClaw가 로컬 `gemini` 바이너리를 셸 실행합니다. 자체 auth가 있으며 다르게 동작할 수 있습니다(스트리밍/도구 지원/버전 차이). +- `google-gemini-cli/...`는 사용자 머신의 로컬 Gemini CLI를 사용합니다(별도 인증 + 도구 동작 특이점). +- Gemini API와 Gemini CLI: + - API: OpenClaw가 HTTP를 통해 Google의 호스팅된 Gemini API를 호출합니다(API 키 / profile 인증). 대부분의 사용자가 “Gemini”라고 할 때 의미하는 것은 이것입니다. + - CLI: OpenClaw가 로컬 `gemini` 바이너리를 셸로 실행합니다. 자체 인증을 가지며 다르게 동작할 수 있습니다(스트리밍/도구 지원/버전 차이). -## Live: 모델 매트릭스(무엇을 다루는가) +## Live: 모델 매트릭스(무엇을 커버하는가) -고정된 “CI 모델 목록”은 없습니다(live는 옵트인). 하지만 키가 있는 개발 머신에서 정기적으로 다루기를 **권장하는** 모델은 다음과 같습니다. +고정된 “CI 모델 목록”은 없습니다(live는 옵트인 방식). 하지만 키가 있는 개발자 머신에서 정기적으로 커버하기를 권장하는 모델은 다음과 같습니다. -### 현대 스모크 세트(tool calling + 이미지) +### 현대적 스모크 세트(tool calling + image) -이것은 계속 동작해야 한다고 기대하는 “일반 모델” 실행입니다. +이것이 우리가 계속 동작하기를 기대하는 “일반 모델” 실행입니다: -- OpenAI(non-Codex): `openai/gpt-5.4`(선택 사항: `openai/gpt-5.4-mini`) +- OpenAI(non-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 모델은 피하세요) +- 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` - MiniMax: `minimax/MiniMax-M2.7` -도구 + 이미지가 있는 Gateway 스모크 실행: +도구 + image가 포함된 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) -제공자 계열별로 최소 하나는 선택하세요. +제공자 계열별로 최소 하나는 선택하세요: -- 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`) +- 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` - MiniMax: `minimax/MiniMax-M2.7` 선택적 추가 커버리지(있으면 좋음): -- xAI: `xai/grok-4`(또는 최신 사용 가능 버전) -- Mistral: `mistral/`…(활성화된 “tools” 지원 모델 하나 선택) -- Cerebras: `cerebras/`…(접근 권한이 있는 경우) -- LM Studio: `lmstudio/`…(로컬; tool calling은 API 모드에 따라 다름) +- xAI: `xai/grok-4` (또는 최신 가용 버전) +- Mistral: `mistral/`… (활성화된 “tools” 지원 모델 중 하나 선택) +- Cerebras: `cerebras/`… (접근 권한이 있는 경우) +- LM Studio: `lmstudio/`… (로컬; tool calling은 API 모드에 따라 달라짐) -### Vision: 이미지 전송(첨부 파일 → 멀티모달 메시지) +### Vision: image 전송(attachment → 멀티모달 메시지) -이미지 프로브를 검증하려면 최소 하나의 이미지 지원 모델(Claude/Gemini/OpenAI의 vision 지원 변형 등)을 `OPENCLAW_LIVE_GATEWAY_MODELS`에 포함하세요. +image 프로브를 실행하려면 `OPENCLAW_LIVE_GATEWAY_MODELS`에 최소 하나의 image 지원 모델(Claude/Gemini/OpenAI의 vision 지원 변형 등)을 포함하세요. -### 집계자 / 대체 Gateway +### Aggregator / 대체 Gateway -키가 활성화되어 있다면 다음을 통한 테스트도 지원합니다. +키가 활성화되어 있다면 다음을 통한 테스트도 지원합니다: -- OpenRouter: `openrouter/...`(수백 개 모델; tool+image 지원 후보를 찾으려면 `openclaw models scan` 사용) -- OpenCode: Zen용 `opencode/...`, Go용 `opencode-go/...`(auth는 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (수백 개의 모델; `openclaw models scan`을 사용해 도구+image 지원 후보를 찾으세요) +- 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 endpoint): `minimax`(cloud/API), 그리고 OpenAI/Anthropic 호환 프록시(LM Studio, vLLM, LiteLLM 등) +- `models.providers`를 통해(custom endpoint): `minimax`(클라우드/API), 그리고 OpenAI/Anthropic 호환 프록시(LM Studio, vLLM, LiteLLM 등) -팁: 문서에 “모든 모델”을 하드코딩하려고 하지 마세요. 권위 있는 목록은 자신의 머신에서 `discoverModels(...)`가 반환하는 것 + 사용 가능한 키입니다. +팁: 문서에 “모든 모델”을 하드코딩하려고 하지 마세요. 권위 있는 목록은 사용자 머신에서 `discoverModels(...)`가 반환하는 것 + 사용 가능한 키입니다. ## 자격 증명(절대 커밋 금지) -live 테스트는 CLI와 동일한 방식으로 자격 증명을 탐지합니다. 실질적인 의미는 다음과 같습니다. +Live 테스트는 CLI와 동일한 방식으로 자격 증명을 찾습니다. 실질적인 의미는 다음과 같습니다: - CLI가 동작하면 live 테스트도 동일한 키를 찾아야 합니다. -- live 테스트가 “자격 증명 없음”이라고 나오면 `openclaw models list` / 모델 선택을 디버깅하는 것과 같은 방식으로 디버깅하세요. +- live 테스트가 “자격 증명 없음”이라고 하면, `openclaw models list` / 모델 선택을 디버깅하는 것과 같은 방식으로 디버깅하세요. -- 에이전트별 auth 프로필: `~/.openclaw/agents//agent/auth-profiles.json`(live 테스트에서 “프로필 키”가 의미하는 것) +- 에이전트별 auth profile: `~/.openclaw/agents//agent/auth-profiles.json`(live 테스트에서 “profile keys”가 의미하는 것이 이것입니다) - Config: `~/.openclaw/openclaw.json`(또는 `OPENCLAW_CONFIG_PATH`) -- 레거시 상태 디렉터리: `~/.openclaw/credentials/`(존재할 경우 스테이징된 live 홈으로 복사되지만, 기본 프로필 키 저장소는 아님) -- 로컬 live 실행은 기본적으로 활성 config, 에이전트별 `auth-profiles.json` 파일, 레거시 `credentials/`, 지원되는 외부 CLI auth 디렉터리를 임시 테스트 홈으로 복사합니다. 스테이징된 live 홈은 `workspace/`와 `sandboxes/`를 건너뛰며, `agents.*.workspace` / `agentDir` 경로 재정의는 제거되어 프로브가 실제 호스트 워크스페이스에 닿지 않도록 합니다. +- 레거시 상태 디렉터리: `~/.openclaw/credentials/`(존재할 경우 stage된 live 홈에 복사되지만, 메인 profile-key 저장소는 아님) +- 로컬 live 실행은 기본적으로 활성 config, 에이전트별 `auth-profiles.json` 파일, 레거시 `credentials/`, 그리고 지원되는 외부 CLI auth 디렉터리를 임시 테스트 홈에 복사합니다. stage된 live 홈은 `workspace/` 및 `sandboxes/`를 건너뛰고, `agents.*.workspace` / `agentDir` 경로 재정의는 제거되므로 프로브가 실제 호스트 워크스페이스에서 실행되지 않습니다. -환경 변수 키(예: `~/.profile`에 export됨)에 의존하려면 `source ~/.profile` 후 로컬 테스트를 실행하거나, 아래 Docker 실행기를 사용하세요(컨테이너에 `~/.profile`을 마운트할 수 있음). +env 키(예: `~/.profile`에 export된 키)에 의존하고 싶다면, `source ~/.profile` 후 로컬 테스트를 실행하거나, 아래 Docker 러너를 사용하세요(컨테이너에 `~/.profile`을 마운트할 수 있습니다). ## Deepgram live(오디오 전사) - 테스트: `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 coding plan live - 테스트: `src/agents/byteplus.live.test.ts` - 활성화: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` @@ -720,9 +726,9 @@ live 테스트는 CLI와 동일한 방식으로 자격 증명을 탐지합니다 - 테스트: `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.`가 구성되지 않은 경우 각 capability를 건너뜀 - - comfy 워크플로 제출, 폴링, 다운로드 또는 plugin 등록을 변경한 후 유용함 + - 번들된 comfy image, video, `music_generate` 경로를 실행합니다 + - `models.providers.comfy.`가 구성되지 않은 경우 각 capability를 건너뜁니다 + - comfy 워크플로 제출, 폴링, 다운로드 또는 Plugin 등록을 변경한 후 유용합니다 ## 이미지 생성 live @@ -730,24 +736,24 @@ live 테스트는 CLI와 동일한 방식으로 자격 증명을 탐지합니다 - 명령: `pnpm test:live src/image-generation/runtime.live.test.ts` - 하네스: `pnpm test:live:media image` - 범위: - - 등록된 모든 이미지 생성 제공자 plugin을 열거 - - 프로빙 전에 로그인 셸(`~/.profile`)에서 누락된 제공자 환경 변수를 로드 - - 기본적으로 저장된 auth 프로필보다 live/env API 키를 우선 사용하므로, `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 - - 사용 가능한 auth/profile/model이 없는 제공자는 건너뜀 - - 공유 런타임 capability를 통해 기본 이미지 생성 변형을 실행: + - 등록된 모든 이미지 생성 제공자 Plugin을 열거합니다 + - 프로빙 전에 로그인 셸(`~/.profile`)에서 누락된 제공자 env var를 로드합니다 + - 기본적으로 저장된 auth profile보다 live/env API 키를 우선 사용하므로 `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않습니다 + - 사용 가능한 auth/profile/model이 없는 제공자는 건너뜁니다 + - 공유 런타임 capability를 통해 기본 이미지 생성 변형을 실행합니다: - `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 동작: - - 프로필 저장소 auth를 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 선택적 인증 동작: + - profile-store 인증을 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` ## 음악 생성 live @@ -755,23 +761,23 @@ live 테스트는 CLI와 동일한 방식으로 자격 증명을 탐지합니다 - 활성화: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - 하네스: `pnpm test:live:media music` - 범위: - - 공유 번들 음악 생성 제공자 경로를 검증 - - 현재 Google과 MiniMax를 다룸 - - 프로빙 전에 로그인 셸(`~/.profile`)에서 제공자 환경 변수를 로드 - - 기본적으로 저장된 auth 프로필보다 live/env API 키를 우선 사용하므로, `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 - - 사용 가능한 auth/profile/model이 없는 제공자는 건너뜀 - - 사용 가능할 때 선언된 런타임 모드를 모두 실행: - - 프롬프트 전용 입력을 사용하는 `generate` - - 제공자가 `capabilities.edit.enabled`를 선언할 때의 `edit` + - 공유 번들 음악 생성 제공자 경로를 실행합니다 + - 현재 Google 및 MiniMax를 커버합니다 + - 프로빙 전에 로그인 셸(`~/.profile`)에서 제공자 env var를 로드합니다 + - 기본적으로 저장된 auth profile보다 live/env API 키를 우선 사용하므로 `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않습니다 + - 사용 가능한 auth/profile/model이 없는 제공자는 건너뜁니다 + - 사용 가능한 경우 선언된 두 런타임 모드를 모두 실행합니다: + - 프롬프트 전용 입력의 `generate` + - 제공자가 `capabilities.edit.enabled`를 선언한 경우의 `edit` - 현재 공유 레인 커버리지: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: 별도 Comfy live 파일, 이 공유 스윕이 아님 + - `comfy`: 별도의 Comfy live 파일이며 이 공유 스윕은 아님 - 선택적 범위 좁히기: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- 선택적 auth 동작: - - 프로필 저장소 auth를 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 선택적 인증 동작: + - profile-store 인증을 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` ## 비디오 생성 live @@ -779,216 +785,218 @@ live 테스트는 CLI와 동일한 방식으로 자격 증명을 탐지합니다 - 활성화: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - 하네스: `pnpm test:live:media video` - 범위: - - 공유 번들 비디오 생성 제공자 경로를 검증 - - 기본적으로 릴리스 안전 스모크 경로를 사용합니다: 비-FAL 제공자, 제공자당 하나의 텍스트-투-비디오 요청, 1초짜리 lobster 프롬프트, 그리고 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`에서 가져오는 제공자별 작업 상한(기본값 `180000`) - - 제공자 측 큐 지연이 릴리스 시간을 지배할 수 있으므로 기본적으로 FAL을 건너뜁니다. 명시적으로 실행하려면 `--video-providers fal` 또는 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`을 전달하세요 - - 프로빙 전에 로그인 셸(`~/.profile`)에서 제공자 환경 변수를 로드 - - 기본적으로 저장된 auth 프로필보다 live/env API 키를 우선 사용하므로, `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않음 - - 사용 가능한 auth/profile/model이 없는 제공자는 건너뜀 - - 기본적으로 `generate`만 실행 - - 선언된 transform 모드도 사용 가능할 때 실행하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 설정: - - 제공자가 `capabilities.imageToVideo.enabled`를 선언하고 선택된 제공자/모델이 공유 스윕에서 버퍼 기반 로컬 이미지 입력을 수용할 때 `imageToVideo` - - 제공자가 `capabilities.videoToVideo.enabled`를 선언하고 선택된 제공자/모델이 공유 스윕에서 버퍼 기반 로컬 비디오 입력을 수용할 때 `videoToVideo` - - 공유 스윕에서 현재 선언되어 있지만 건너뛰는 `imageToVideo` 제공자: - - `vydra`: 번들된 `veo3`는 텍스트 전용이고 번들된 `kling`은 원격 이미지 URL이 필요하기 때문 + - 공유 번들 비디오 생성 제공자 경로를 실행합니다 + - 기본적으로 릴리스에 안전한 스모크 경로를 사용합니다: FAL이 아닌 제공자, 제공자당 하나의 텍스트-투-비디오 요청, 1초 lobster 프롬프트, 그리고 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`의 제공자별 작업 상한(기본값 `180000`) + - 제공자 측 큐 지연이 릴리스 시간을 지배할 수 있으므로 기본적으로 FAL은 건너뜁니다. 명시적으로 실행하려면 `--video-providers fal` 또는 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`을 전달하세요 + - 프로빙 전에 로그인 셸(`~/.profile`)에서 제공자 env var를 로드합니다 + - 기본적으로 저장된 auth profile보다 live/env API 키를 우선 사용하므로 `auth-profiles.json`의 오래된 테스트 키가 실제 셸 자격 증명을 가리지 않습니다 + - 사용 가능한 auth/profile/model이 없는 제공자는 건너뜁니다 + - 기본적으로 `generate`만 실행합니다 + - 사용 가능한 경우 선언된 transform 모드도 실행하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`을 설정하세요: + - 제공자가 `capabilities.imageToVideo.enabled`를 선언하고 선택된 제공자/모델이 공유 스윕에서 버퍼 기반 로컬 image 입력을 허용할 때 `imageToVideo` + - 제공자가 `capabilities.videoToVideo.enabled`를 선언하고 선택된 제공자/모델이 공유 스윕에서 버퍼 기반 로컬 video 입력을 허용할 때 `videoToVideo` + - 현재 공유 스윕에서 선언되었지만 건너뛰는 `imageToVideo` 제공자: + - `vydra`: 번들된 `veo3`는 텍스트 전용이고 번들된 `kling`은 원격 image URL이 필요하기 때문입니다 - 제공자별 Vydra 커버리지: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - 이 파일은 기본적으로 `veo3` 텍스트-투-비디오와 원격 이미지 URL fixture를 사용하는 `kling` 레인을 실행합니다 + - 이 파일은 기본적으로 원격 image URL 픽스처를 사용하는 `kling` 레인과 함께 `veo3` 텍스트-투-비디오를 실행합니다 - 현재 `videoToVideo` live 커버리지: - 선택된 모델이 `runway/gen4_aleph`일 때만 `runway` - - 공유 스윕에서 현재 선언되어 있지만 건너뛰는 `videoToVideo` 제공자: - - `alibaba`, `qwen`, `xai`: 현재 이 경로들이 원격 `http(s)` / MP4 참조 URL을 필요로 하기 때문 - - `google`: 현재 공유 Gemini/Veo 레인이 로컬 버퍼 기반 입력을 사용하며, 이 경로는 공유 스윕에서 수용되지 않기 때문 - - `openai`: 현재 공유 레인에는 조직별 비디오 inpaint/remix 접근 보장이 없기 때문 + - 현재 공유 스윕에서 선언되었지만 건너뛰는 `videoToVideo` 제공자: + - `alibaba`, `qwen`, `xai`: 현재 이러한 경로는 원격 `http(s)` / MP4 참조 URL이 필요하기 때문입니다 + - `google`: 현재 공유 Gemini/Veo 레인이 로컬 버퍼 기반 입력을 사용하고 그 경로는 공유 스윕에서 허용되지 않기 때문입니다 + - `openai`: 현재 공유 레인에는 조직별 video inpaint/remix 접근 보장이 없기 때문입니다 - 선택적 범위 좁히기: - `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=""` + - 기본 스윕에 FAL을 포함한 모든 제공자를 포함하려면 `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` - 공격적인 스모크 실행을 위해 각 제공자 작업 상한을 줄이려면 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` -- 선택적 auth 동작: - - 프로필 저장소 auth를 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` +- 선택적 인증 동작: + - profile-store 인증을 강제하고 env 전용 재정의를 무시하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` ## 미디어 live 하네스 - 명령: `pnpm test:live:media` - 목적: - - 공유 이미지, 음악, 비디오 live 스위트를 repo 네이티브 단일 엔트리포인트로 실행 - - `~/.profile`에서 누락된 제공자 환경 변수를 자동 로드 - - 기본적으로 현재 사용 가능한 auth가 있는 제공자로 각 스위트 범위를 자동 축소 - - `scripts/test-live.mjs`를 재사용하므로 Heartbeat 및 quiet 모드 동작이 일관되게 유지됨 + - 하나의 repo 네이티브 엔트리포인트를 통해 공유 이미지, 음악, 비디오 live 스위트를 실행합니다 + - `~/.profile`에서 누락된 제공자 env var를 자동 로드합니다 + - 기본적으로 현재 사용 가능한 auth가 있는 제공자로 각 스위트 범위를 자동으로 좁힙니다 + - `scripts/test-live.mjs`를 재사용하므로 Heartbeat 및 조용한 모드 동작이 일관되게 유지됩니다 - 예시: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker 실행기(선택적 “Linux에서도 동작함” 확인) +## Docker 러너(선택적 “Linux에서도 동작” 확인) -이 Docker 실행기는 두 버킷으로 나뉩니다. +이 Docker 러너는 두 범주로 나뉩니다: -- live-model 실행기: `test:docker:live-models`와 `test:docker:live-gateway`는 일치하는 profile-key live 파일만 repo Docker 이미지 내부에서 실행합니다(`src/agents/models.profiles.live.test.ts` 및 `src/gateway/gateway-models.profiles.live.test.ts`). 로컬 config 디렉터리와 workspace를 마운트하고(`~/.profile`이 마운트되면 소싱도 수행) 실행합니다. 일치하는 로컬 엔트리포인트는 `test:live:models-profiles`와 `test:live:gateway-profiles`입니다. -- Docker live 실행기는 전체 Docker 스윕이 실용적으로 유지되도록 기본적으로 더 작은 스모크 상한을 사용합니다: +- Live-model 러너: `test:docker:live-models`와 `test:docker:live-gateway`는 repo Docker 이미지 내부에서 일치하는 profile-key live 파일만 실행합니다(`src/agents/models.profiles.live.test.ts` 및 `src/gateway/gateway-models.profiles.live.test.ts`). 로컬 config 디렉터리와 workspace를 마운트하고(마운트되어 있으면 `~/.profile`도 source함), 대응하는 로컬 엔트리포인트는 `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`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000`, 그리고 - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`를 사용합니다. 더 큰 exhaustive 스캔을 명시적으로 원할 때는 해당 환경 변수를 재정의하세요. -- `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`를 사용합니다. 더 큰 exhaustive 스캔이 명시적으로 필요할 때는 + 이러한 env var를 재정의하세요. +- `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 경로를 검증합니다. -live-model Docker 실행기는 또한 필요한 CLI auth 홈만 bind mount하고(또는 실행이 좁혀지지 않은 경우 지원되는 모든 것), 실행 전에 이를 컨테이너 홈으로 복사하여 외부 CLI OAuth가 호스트 auth 저장소를 변경하지 않고 토큰을 새로 고칠 수 있게 합니다. +Live-model Docker 러너는 또한 필요한 CLI auth 홈만 바인드 마운트하고(실행이 좁혀지지 않은 경우에는 지원되는 모든 홈), 실행 전에 이를 컨테이너 홈으로 복사하므로 외부 CLI OAuth가 호스트 auth 저장소를 변경하지 않고 토큰을 갱신할 수 있습니다: -- 직접 모델: `pnpm test:docker:live-models`(스크립트: `scripts/test-live-models-docker.sh`) -- ACP bind 스모크: `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`) -- 온보딩 마법사(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 채널 브리지(seed된 Gateway + stdio 브리지 + raw Claude notification-frame 스모크): `pnpm test:docker:mcp-channels`(스크립트: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins(설치 스모크 + `/plugin` 별칭 + Claude 번들 재시작 시맨틱): `pnpm test:docker:plugins`(스크립트: `scripts/e2e/plugins-docker.sh`) +- 직접 모델: `pnpm test:docker:live-models` (스크립트: `scripts/test-live-models-docker.sh`) +- ACP bind 스모크: `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`) +- 온보딩 마법사(TTY, 전체 scaffolding): `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 채널 브리지(seed된 Gateway + stdio 브리지 + 원시 Claude notification-frame 스모크): `pnpm test:docker:mcp-channels` (스크립트: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins(설치 스모크 + `/plugin` 별칭 + Claude 번들 재시작 의미론): `pnpm test:docker:plugins` (스크립트: `scripts/e2e/plugins-docker.sh`) -live-model Docker 실행기는 현재 체크아웃도 읽기 전용으로 bind mount하고 -이를 컨테이너 내부의 임시 workdir로 스테이징합니다. 이렇게 하면 런타임 -이미지를 슬림하게 유지하면서도 정확히 로컬 소스/config를 대상으로 Vitest를 실행할 수 있습니다. -스테이징 단계는 -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, 앱 로컬 `.build` 또는 -Gradle 출력 디렉터리와 같은 큰 로컬 전용 캐시와 앱 빌드 출력을 건너뛰므로, Docker live 실행이 +Live-model Docker 러너는 또한 현재 체크아웃을 읽기 전용으로 바인드 마운트하고 +컨테이너 내부의 임시 workdir에 stage합니다. 이렇게 하면 런타임 +이미지를 슬림하게 유지하면서도 정확한 로컬 소스/config로 Vitest를 실행할 수 있습니다. +stage 단계는 +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, 앱 로컬 `.build`, Gradle 출력 디렉터리와 같은 +대형 로컬 전용 캐시와 앱 빌드 출력을 건너뛰므로 Docker live 실행이 머신별 아티팩트를 복사하느라 몇 분씩 소비하지 않습니다. 또한 `OPENCLAW_SKIP_CHANNELS=1`을 설정하므로 Gateway live 프로브가 -컨테이너 내부에서 실제 Telegram/Discord 등의 채널 워커를 시작하지 않습니다. -`test:docker:live-models`는 여전히 `pnpm test:live`를 실행하므로, -해당 Docker 레인에서 Gateway -live 커버리지를 좁히거나 제외해야 할 때는 `OPENCLAW_LIVE_GATEWAY_*`도 함께 전달하세요. -`test:docker:openwebui`는 더 높은 수준의 호환성 스모크입니다. OpenAI 호환 HTTP 엔드포인트가 활성화된 -OpenClaw Gateway 컨테이너를 시작하고, -해당 Gateway를 대상으로 고정된 Open WebUI 컨테이너를 시작한 다음, -Open WebUI를 통해 로그인하고, `/api/models`가 `openclaw/default`를 노출하는지 확인한 뒤, -Open WebUI의 `/api/chat/completions` 프록시를 통해 실제 채팅 요청을 보냅니다. +컨테이너 내부에서 실제 Telegram/Discord 등 채널 워커를 시작하지 않습니다. +`test:docker:live-models`는 여전히 `pnpm test:live`를 실행하므로 +해당 Docker 레인에서 Gateway live 커버리지를 좁히거나 제외해야 할 때도 +`OPENCLAW_LIVE_GATEWAY_*`를 함께 전달하세요. +`test:docker:openwebui`는 상위 수준 호환성 스모크입니다. 이 러너는 +OpenAI 호환 HTTP 엔드포인트를 활성화한 OpenClaw Gateway 컨테이너를 시작하고, +고정된 Open WebUI 컨테이너를 해당 Gateway에 대해 시작한 다음, Open WebUI를 통해 로그인하고, +`/api/models`가 `openclaw/default`를 노출하는지 확인한 뒤, +Open WebUI의 `/api/chat/completions` 프록시를 통해 실제 chat 요청을 보냅니다. 첫 실행은 Docker가 -Open WebUI 이미지를 pull해야 할 수 있고 Open WebUI 자체의 cold-start setup을 마쳐야 할 수 있으므로 눈에 띄게 더 느릴 수 있습니다. +Open WebUI 이미지를 pull해야 할 수 있고 Open WebUI 자체가 콜드 스타트 설정을 완료해야 할 수 있으므로 눈에 띄게 더 느릴 수 있습니다. 이 레인은 사용 가능한 live 모델 키를 기대하며, -Docker화된 실행에서 이를 제공하는 기본 방법은 `OPENCLAW_PROFILE_FILE` -(기본값 `~/.profile`)입니다. -성공적인 실행은 `{ "ok": true, "model": +`OPENCLAW_PROFILE_FILE`(`~/.profile`이 기본값)이 Dockerized 실행에서 이를 제공하는 주요 방식입니다. +성공한 실행은 `{ "ok": true, "model": "openclaw/default", ... }`와 같은 작은 JSON payload를 출력합니다. -`test:docker:mcp-channels`는 의도적으로 결정적이며 실제 -Telegram, Discord 또는 iMessage 계정이 필요하지 않습니다. seed된 Gateway -컨테이너를 부팅하고, `openclaw mcp serve`를 spawn하는 두 번째 컨테이너를 시작한 다음, -라우팅된 대화 탐색, 전사본 읽기, 첨부 파일 메타데이터, -live 이벤트 큐 동작, 아웃바운드 전송 라우팅, 그리고 실제 stdio MCP 브리지 위에서 Claude 스타일 채널 + +`test:docker:mcp-channels`는 의도적으로 결정론적이며 +실제 Telegram, Discord 또는 iMessage 계정이 필요하지 않습니다. 이 러너는 seed된 Gateway +컨테이너를 부팅하고, `openclaw mcp serve`를 spawn하는 두 번째 컨테이너를 시작한 뒤, +실제 stdio MCP 브리지를 통해 라우팅된 대화 검색, transcript 읽기, attachment 메타데이터, +live 이벤트 큐 동작, 아웃바운드 전송 라우팅, 그리고 Claude 스타일 채널 + 권한 알림을 검증합니다. 알림 검사는 -raw stdio MCP 프레임을 직접 검사하므로, 이 스모크는 특정 클라이언트 SDK가 우연히 표면화하는 것뿐 아니라 -브리지가 실제로 무엇을 내보내는지도 검증합니다. +원시 stdio MCP 프레임을 직접 검사하므로, 이 스모크는 특정 클라이언트 SDK가 우연히 표면화하는 것뿐 아니라 +브리지가 실제로 무엇을 방출하는지도 검증합니다. -수동 ACP plain-language 스레드 스모크(CI 아님): +수동 ACP 자연어 thread 스모크(CI 아님): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- 이 스크립트는 회귀/디버그 워크플로를 위해 유지하세요. ACP 스레드 라우팅 검증에 다시 필요할 수 있으므로 삭제하지 마세요. +- 이 스크립트는 회귀/디버그 워크플로를 위해 유지하세요. ACP thread 라우팅 검증에 다시 필요할 수 있으므로 삭제하지 마세요. -유용한 환경 변수: +유용한 env var: -- `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`에서 소싱된 환경 변수만 검증하며, 임시 config/workspace 디렉터리를 사용하고 외부 CLI auth 마운트는 사용하지 않음 -- `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`에 마운트하고 테스트 실행 전에 source +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`로 `OPENCLAW_PROFILE_FILE`에서 source한 env var만 검증하며, 임시 config/workspace 디렉터리와 외부 CLI auth 마운트는 사용하지 않음 +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...`(기본값: `~/.cache/openclaw/docker-cli-tools`)를 `/home/node/.npm-global`에 마운트하여 Docker 내부에서 캐시된 CLI 설치에 사용 +- `$HOME` 아래 외부 CLI auth 디렉터리/파일은 `/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` -- 자격 증명이 프로필 저장소에서 오도록 보장하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`(env 제외) -- Open WebUI 스모크에 대해 Gateway가 노출할 모델을 선택하려면 `OPENCLAW_OPENWEBUI_MODEL=...` -- Open WebUI 스모크에서 사용하는 nonce-check 프롬프트를 재정의하려면 `OPENCLAW_OPENWEBUI_PROMPT=...` -- 고정된 Open WebUI 이미지 태그를 재정의하려면 `OPENWEBUI_IMAGE=...` +- 자격 증명이 profile store에서 오도록 보장하려면 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`(env가 아님) +- Open WebUI 스모크용 Gateway가 노출할 모델을 선택하려면 `OPENCLAW_OPENWEBUI_MODEL=...` +- Open WebUI 스모크에서 사용하는 nonce 확인 프롬프트를 재정의하려면 `OPENCLAW_OPENWEBUI_PROMPT=...` +- 고정된 Open WebUI image 태그를 재정의하려면 `OPENWEBUI_IMAGE=...` ## 문서 sanity -문서를 수정한 후 문서 검사를 실행하세요: `pnpm check:docs`. -인페이지 heading 검사까지 필요하면 전체 Mintlify anchor 검증을 실행하세요: `pnpm docs:check-links:anchors`. +문서 수정 후 문서 검사를 실행하세요: `pnpm check:docs`. +인페이지 heading 검사까지 필요할 때는 전체 Mintlify anchor 검증을 실행하세요: `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 tool calling(mock 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`, config + auth 쓰기 강제): `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`). -- 세션 wiring 및 config 효과를 검증하는 end-to-end wizard 흐름(`src/gateway/gateway.test.ts`). +- 세션 wiring과 config 효과를 검증하는 end-to-end 마법사 흐름(`src/gateway/gateway.test.ts`). -Skills에 대해 아직 부족한 부분([Skills](/ko/tools/skills) 참조): +Skills에 대해 아직 부족한 것([Skills](/ko/tools/skills) 참조): -- **의사결정:** 프롬프트에 Skills가 나열될 때, 에이전트가 올바른 Skill을 선택하나요(또는 관련 없는 Skill은 피하나요)? -- **준수:** 에이전트가 사용 전에 `SKILL.md`를 읽고 필수 단계/인자를 따르나요? -- **워크플로 계약:** 도구 순서, 세션 기록 이어받기, sandbox 경계를 검증하는 다중 턴 시나리오. +- **의사결정:** 프롬프트에 Skills가 나열되어 있을 때, 에이전트가 올바른 skill을 선택하는가(또는 관련 없는 skill을 피하는가)? +- **준수:** 에이전트가 사용 전에 `SKILL.md`를 읽고 필수 단계/인수를 따르는가? +- **워크플로 계약:** 도구 순서, 세션 히스토리 유지, sandbox 경계를 검증하는 다중 턴 시나리오. -향후 평가는 우선 결정적으로 유지되어야 합니다. +향후 평가는 먼저 결정론적으로 유지되어야 합니다: -- mock 제공자를 사용해 도구 호출 + 순서, skill 파일 읽기, 세션 wiring을 검증하는 시나리오 실행기 -- Skill 중심 시나리오의 소규모 스위트(사용 vs 회피, 게이팅, 프롬프트 인젝션) -- CI 안전 스위트가 마련된 이후에만 선택적 live 평가(옵트인, env 게이트) +- 도구 호출 + 순서, skill 파일 읽기, 세션 wiring을 검증하기 위해 mock 제공자를 사용하는 시나리오 러너 +- skill 중심 시나리오의 소규모 스위트(사용 vs 회피, 게이팅, 프롬프트 인젝션) +- CI 안전 스위트가 준비된 이후에만 선택적으로 제공되는 live 평가(옵트인, env 게이트 방식) -## 계약 테스트(plugin 및 channel 형상) +## 계약 테스트(Plugin 및 채널 형태) -계약 테스트는 등록된 모든 plugin과 channel이 해당 -인터페이스 계약을 준수하는지 검증합니다. 모든 탐지된 plugin을 순회하며 형상 및 동작 검증 스위트를 실행합니다. 기본 `pnpm test` unit 레인은 이러한 공유 seam 및 스모크 파일을 의도적으로 -건너뜁니다. 공유 channel 또는 제공자 표면을 건드렸다면 계약 명령을 명시적으로 실행하세요. +계약 테스트는 등록된 모든 Plugin과 채널이 +해당 인터페이스 계약을 준수하는지 검증합니다. 발견된 모든 Plugin을 순회하며 +형태와 동작에 대한 검증 스위트를 실행합니다. 기본 `pnpm test` unit 레인은 의도적으로 +이러한 공유 seam 및 스모크 파일을 건너뛰므로, 공유 채널 또는 제공자 표면을 수정할 때는 +계약 명령을 명시적으로 실행하세요. ### 명령 -- 전체 계약: `pnpm test:contracts` -- channel 계약만: `pnpm test:contracts:channels` +- 모든 계약: `pnpm test:contracts` +- 채널 계약만: `pnpm test:contracts:channels` - 제공자 계약만: `pnpm test:contracts:plugins` -### Channel 계약 +### 채널 계약 `src/channels/plugins/contracts/*.contract.test.ts`에 있습니다: -- **plugin** - 기본 plugin 형상(id, name, capability) -- **setup** - setup wizard 계약 +- **plugin** - 기본 Plugin 형태(id, name, capability) +- **setup** - setup 마법사 계약 - **session-binding** - 세션 바인딩 동작 - **outbound-payload** - 메시지 payload 구조 - **inbound** - 인바운드 메시지 처리 -- **actions** - channel 액션 핸들러 -- **threading** - 스레드 ID 처리 +- **actions** - 채널 action 핸들러 +- **threading** - thread ID 처리 - **directory** - 디렉터리/roster API -- **group-policy** - 그룹 정책 강제 +- **group-policy** - 그룹 정책 적용 ### 제공자 상태 계약 `src/plugins/contracts/*.contract.test.ts`에 있습니다. -- **status** - channel 상태 프로브 -- **registry** - plugin 레지스트리 형상 +- **status** - 채널 상태 프로브 +- **registry** - Plugin 레지스트리 형태 ### 제공자 계약 `src/plugins/contracts/*.contract.test.ts`에 있습니다: -- **auth** - auth 흐름 계약 -- **auth-choice** - auth 선택/선정 -- **catalog** - 모델 catalog API -- **discovery** - plugin 탐지 -- **loader** - plugin 로딩 +- **auth** - 인증 흐름 계약 +- **auth-choice** - 인증 선택 +- **catalog** - 모델 카탈로그 API +- **discovery** - Plugin 발견 +- **loader** - Plugin 로딩 - **runtime** - 제공자 런타임 -- **shape** - plugin 형상/인터페이스 -- **wizard** - setup wizard +- **shape** - Plugin 형태/인터페이스 +- **wizard** - setup 마법사 -### 실행 시점 +### 언제 실행할지 -- plugin-sdk 내보내기 또는 하위 경로를 변경한 후 -- channel 또는 제공자 plugin을 추가하거나 수정한 후 -- plugin 등록 또는 탐지를 리팩터링한 후 +- plugin-sdk export 또는 subpath를 변경한 후 +- 채널 또는 제공자 Plugin을 추가하거나 수정한 후 +- Plugin 등록 또는 발견을 리팩터링한 후 계약 테스트는 CI에서 실행되며 실제 API 키가 필요하지 않습니다. @@ -996,11 +1004,11 @@ Skills에 대해 아직 부족한 부분([Skills](/ko/tools/skills) 참조): live에서 발견된 제공자/모델 이슈를 수정할 때: -- 가능하면 CI 안전 회귀 테스트를 추가하세요(mock/stub 제공자, 또는 정확한 요청 형상 변환 캡처) -- 본질적으로 live 전용인 경우(rate limit, auth 정책), live 테스트는 좁고 env 변수를 통한 옵트인으로 유지하세요 -- 버그를 잡아내는 가장 작은 계층을 대상으로 하는 것을 선호하세요: +- 가능하다면 CI 안전 회귀 테스트를 추가하세요(mock/stub 제공자 사용 또는 정확한 요청 형태 변환 캡처) +- 본질적으로 live 전용(rate limit, 인증 정책)이라면 live 테스트는 좁고 env var를 통한 옵트인 방식으로 유지하세요 +- 버그를 포착하는 가장 작은 계층을 대상으로 삼는 것을 권장합니다: - 제공자 요청 변환/replay 버그 → 직접 모델 테스트 - - Gateway 세션/기록/도구 파이프라인 버그 → Gateway live 스모크 또는 CI 안전 Gateway mock 테스트 -- SecretRef traversal 가드레일: - - `src/secrets/exec-secret-ref-id-parity.test.ts`는 레지스트리 메타데이터(`listSecretTargetRegistryEntries()`)에서 SecretRef 클래스별 샘플 대상 하나를 도출한 뒤, traversal-segment exec id가 거부되는지 검증합니다. - - `src/secrets/target-registry-data.ts`에 새 `includeInPlan` SecretRef 대상 계열을 추가하면, 해당 테스트의 `classifyTargetClass`를 업데이트하세요. 이 테스트는 분류되지 않은 대상 id에서 의도적으로 실패하므로 새 클래스가 조용히 건너뛰어질 수 없습니다. + - Gateway 세션/히스토리/도구 파이프라인 버그 → Gateway live 스모크 또는 CI 안전 Gateway mock 테스트 +- SecretRef 순회 가드레일: + - `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/install/index.md b/docs/ko/install/index.md index b675e3bdf..fac3d6f61 100644 --- a/docs/ko/install/index.md +++ b/docs/ko/install/index.md @@ -1,15 +1,15 @@ --- read_when: - - Getting Started 빠른 시작 외의 설치 방법이 필요할 때 - - 클라우드 플랫폼에 배포하려는 경우 - - 업데이트, 마이그레이션 또는 제거가 필요할 때 + - 시작하기 빠른 시작 외의 설치 방법이 필요합니다. + - 클라우드 플랫폼에 배포하려고 합니다 + - 업데이트, 마이그레이션 또는 제거가 필요합니다 summary: OpenClaw 설치 — 설치 스크립트, npm/pnpm/bun, 소스에서, Docker 등 title: 설치 x-i18n: - generated_at: "2026-04-05T12:46:22Z" + generated_at: "2026-04-20T06:05:33Z" model: gpt-5.4 provider: openai - source_hash: eca17c76a2a66166b3d8cda9dc3144ab920d30ad0ed2a220eb9389d7a383ba5d + source_hash: ad0a5fdbbf13dcaf2fed6840f35aa22b2e9e458509509f98303c8d87c2556a6f source_path: install/index.md workflow: 15 --- @@ -18,7 +18,7 @@ x-i18n: ## 권장: 설치 스크립트 -가장 빠른 설치 방법입니다. OS를 감지하고, 필요하면 Node를 설치하고, OpenClaw를 설치한 뒤 온보딩을 실행합니다. +가장 빠른 설치 방법입니다. OS를 감지하고, 필요하면 Node를 설치하고, OpenClaw를 설치한 다음 온보딩을 시작합니다. @@ -33,7 +33,7 @@ x-i18n: -온보딩을 실행하지 않고 설치하려면: +온보딩을 실행하지 않고 설치하려면 다음을 사용하세요. @@ -48,31 +48,29 @@ x-i18n: -모든 플래그와 CI/자동화 옵션은 [Installer internals](/install/installer)를 참조하세요. +모든 플래그와 CI/자동화 옵션은 [설치 프로그램 내부 동작](/ko/install/installer)을 참조하세요. ## 시스템 요구 사항 -- **Node 24**(권장) 또는 Node 22.14+ — 설치 스크립트가 이를 자동 처리합니다 -- **macOS, Linux 또는 Windows** — 네이티브 Windows와 WSL2 모두 지원되며, WSL2가 더 안정적입니다. [Windows](/platforms/windows)를 참조하세요. -- `pnpm`은 소스에서 빌드할 때만 필요합니다 +- **Node 24**(권장) 또는 Node 22.14+ — 설치 스크립트가 이를 자동으로 처리합니다 +- **macOS, Linux 또는 Windows** — 기본 Windows와 WSL2를 모두 지원하며, WSL2가 더 안정적입니다. [Windows](/ko/platforms/windows)를 참조하세요. +- 소스에서 빌드하는 경우에만 `pnpm`이 필요합니다 ## 대체 설치 방법 -### 로컬 prefix 설치기(`install-cli.sh`) +### 로컬 프리픽스 설치 프로그램(`install-cli.sh`) -시스템 전체 Node 설치에 의존하지 않고 OpenClaw와 Node를 -`~/.openclaw` 같은 로컬 prefix 아래에 유지하고 싶다면 이 방법을 사용하세요: +시스템 전체 Node 설치에 의존하지 않고, `~/.openclaw` 같은 로컬 프리픽스 아래에 OpenClaw와 Node를 유지하려는 경우 이 방법을 사용하세요. ```bash curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` -기본적으로 npm 설치를 지원하며, 같은 -prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다. 전체 참조: [Installer internals](/install/installer#install-clish). +기본적으로 npm 설치를 지원하며, 동일한 프리픽스 흐름에서 git 체크아웃 설치도 지원합니다. 전체 참조는 [설치 프로그램 내부 동작](/ko/install/installer#install-clish)을 확인하세요. ### npm, pnpm 또는 bun -이미 Node를 직접 관리하고 있다면: +이미 Node를 직접 관리하고 있다면 다음을 사용하세요. @@ -89,7 +87,7 @@ prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다. 전체 ``` - pnpm은 빌드 스크립트가 있는 패키지에 대해 명시적 승인이 필요합니다. 첫 설치 후 `pnpm approve-builds -g`를 실행하세요. + pnpm은 빌드 스크립트가 있는 패키지에 대해 명시적인 승인이 필요합니다. 처음 설치한 뒤 `pnpm approve-builds -g`를 실행하세요. @@ -100,13 +98,13 @@ prefix 흐름 아래에서 git 체크아웃 설치도 지원합니다. 전체 ``` - Bun은 전역 CLI 설치 경로에서 지원됩니다. 게이트웨이 런타임에는 여전히 Node가 권장되는 daemon 런타임입니다. + Bun은 전역 CLI 설치 경로에서 지원됩니다. Gateway 런타임의 경우에는 여전히 Node를 권장 데몬 런타임으로 사용합니다. - + 전역 설치된 libvips 때문에 `sharp`가 실패하는 경우: ```bash @@ -122,12 +120,12 @@ SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw -pnpm install && pnpm ui:build && pnpm build +pnpm install && pnpm build && pnpm ui:build pnpm link --global openclaw onboard --install-daemon ``` -또는 link를 생략하고 리포지토리 내부에서 `pnpm openclaw ...`를 사용하세요. 전체 개발 워크플로는 [Setup](/start/setup)을 참조하세요. +또는 링크를 생략하고 저장소 내부에서 `pnpm openclaw ...`를 사용해도 됩니다. 전체 개발 워크플로는 [Setup](/ko/start/setup)을 참조하세요. ### GitHub main에서 설치 @@ -138,19 +136,19 @@ npm install -g github:openclaw/openclaw#main ### 컨테이너 및 패키지 관리자 - - 컨테이너화되었거나 헤드리스인 배포. + + 컨테이너화된 또는 헤드리스 배포. - - Docker의 rootless 컨테이너 대안. + + Docker의 루트리스 컨테이너 대안. - + Nix flake를 통한 선언적 설치. - - 자동화된 fleet 프로비저닝. + + 자동화된 대규모 프로비저닝. - + Bun 런타임을 통한 CLI 전용 사용. @@ -158,44 +156,44 @@ npm install -g github:openclaw/openclaw#main ## 설치 확인 ```bash -openclaw --version # CLI 사용 가능 여부 확인 -openclaw doctor # config 문제 확인 -openclaw gateway status # 게이트웨이 실행 여부 확인 +openclaw --version # CLI를 사용할 수 있는지 확인 +openclaw doctor # 구성 문제 확인 +openclaw gateway status # Gateway가 실행 중인지 확인 ``` -설치 후 관리형 시작을 원하면: +설치 후 관리형 시작을 원한다면: - macOS: `openclaw onboard --install-daemon` 또는 `openclaw gateway install`을 통한 LaunchAgent -- Linux/WSL2: 동일한 명령을 통한 systemd user 서비스 -- 네이티브 Windows: 먼저 Scheduled Task, 작업 생성이 거부되면 사용자별 Startup 폴더 로그인 항목으로 대체 +- Linux/WSL2: 동일한 명령을 통한 systemd 사용자 서비스 +- 기본 Windows: 먼저 예약된 작업, 작업 생성이 거부되면 사용자별 시작 프로그램 폴더 로그인 항목으로 대체 ## 호스팅 및 배포 -클라우드 서버 또는 VPS에 OpenClaw를 배포하세요: +클라우드 서버 또는 VPS에 OpenClaw를 배포하세요. - 모든 Linux VPS - 공통 Docker 단계 - K8s - Fly.io - Hetzner - Google Cloud - Azure - Railway - Render - Northflank + 모든 Linux VPS + 공통 Docker 단계 + K8s + Fly.io + Hetzner + Google Cloud + Azure + Railway + Render + Northflank ## 업데이트, 마이그레이션 또는 제거 - + OpenClaw를 최신 상태로 유지합니다. - + 새 머신으로 이동합니다. - + OpenClaw를 완전히 제거합니다. @@ -205,15 +203,15 @@ openclaw gateway status # 게이트웨이 실행 여부 확인 설치는 성공했지만 터미널에서 `openclaw`를 찾을 수 없는 경우: ```bash -node -v # Node가 설치되어 있나요? +node -v # Node가 설치되었나요? npm prefix -g # 전역 패키지는 어디에 설치되나요? echo "$PATH" # 전역 bin 디렉터리가 PATH에 있나요? ``` -`$(npm prefix -g)/bin`이 `$PATH`에 없다면 셸 시작 파일(`~/.zshrc` 또는 `~/.bashrc`)에 추가하세요: +`$(npm prefix -g)/bin`이 `$PATH`에 없다면, 셸 시작 파일(`~/.zshrc` 또는 `~/.bashrc`)에 추가하세요. ```bash export PATH="$(npm prefix -g)/bin:$PATH" ``` -그런 다음 새 터미널을 여세요. 자세한 내용은 [Node setup](/install/node)를 참조하세요. +그런 다음 새 터미널을 여세요. 자세한 내용은 [Node setup](/ko/install/node)을 참조하세요. diff --git a/docs/ko/platforms/windows.md b/docs/ko/platforms/windows.md index c252328fc..26f3ce6cb 100644 --- a/docs/ko/platforms/windows.md +++ b/docs/ko/platforms/windows.md @@ -1,30 +1,33 @@ --- read_when: - - Windows에 OpenClaw를 설치하는 경우 - - 네이티브 Windows와 WSL2 중에서 선택하는 경우 - - Windows companion app 상태를 확인하려는 경우 -summary: 'Windows 지원: 네이티브 및 WSL2 설치 경로, 데몬, 현재 주의 사항' + - Windows에 OpenClaw 설치하기 + - 네이티브 Windows와 WSL2 중 선택하기 + - Windows 컴패니언 앱 상태 확인하기 +summary: 'Windows 지원: 네이티브 및 WSL2 설치 경로, 데몬, 그리고 현재 주의사항' title: Windows x-i18n: - generated_at: "2026-04-05T12:49:25Z" + generated_at: "2026-04-20T06:05:37Z" model: gpt-5.4 provider: openai - source_hash: 7d9819206bdd65cf03519c1bc73ed0c7889b0ab842215ea94343262300adfd14 + source_hash: 1e7451c785a1d75c809522ad93e2c44a00b211f77f14c5c489fd0b01840d3fe2 source_path: platforms/windows.md workflow: 15 --- # Windows -OpenClaw는 **네이티브 Windows**와 **WSL2**를 모두 지원합니다. WSL2가 더 안정적인 경로이며 전체 경험을 위해 권장됩니다. CLI, Gateway, tooling이 Linux 내부에서 완전한 호환성과 함께 실행됩니다. 네이티브 Windows도 핵심 CLI와 Gateway 사용에는 동작하지만, 아래에 설명된 몇 가지 주의 사항이 있습니다. +OpenClaw는 **네이티브 Windows**와 **WSL2**를 모두 지원합니다. WSL2가 더 +안정적인 경로이며 전체 경험을 위해 권장됩니다. CLI, Gateway, 그리고 +도구들이 Linux 내부에서 완전한 호환성으로 실행됩니다. 네이티브 Windows도 +핵심 CLI와 Gateway 사용은 가능하지만, 아래에 적힌 몇 가지 주의사항이 있습니다. -네이티브 Windows companion apps는 계획되어 있습니다. +네이티브 Windows 컴패니언 앱은 계획되어 있습니다. -## WSL2 (권장) +## WSL2(권장) -- [Getting Started](/ko/start/getting-started) (WSL 내부에서 사용) -- [설치 및 업데이트](/install/updating) -- 공식 WSL2 가이드 (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) +- [시작하기](/ko/start/getting-started) (WSL 내부에서 사용) +- [설치 및 업데이트](/ko/install/updating) +- 공식 WSL2 가이드(Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install) ## 네이티브 Windows 상태 @@ -34,21 +37,21 @@ OpenClaw는 **네이티브 Windows**와 **WSL2**를 모두 지원합니다. WSL2 - `install.ps1`을 통한 웹사이트 설치 프로그램 - `openclaw --version`, `openclaw doctor`, `openclaw plugins list --json` 같은 로컬 CLI 사용 -- 다음과 같은 내장 local-agent/provider 스모크 테스트: +- 다음과 같은 임베디드 local-agent/provider 스모크 테스트: ```powershell openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK." ``` -현재 주의 사항: +현재 주의사항: -- `openclaw onboard --non-interactive`는 `--skip-health`를 전달하지 않으면 여전히 도달 가능한 로컬 gateway를 기대합니다 -- `openclaw onboard --non-interactive --install-daemon` 및 `openclaw gateway install`은 먼저 Windows Scheduled Tasks를 시도합니다 -- Scheduled Task 생성이 거부되면 OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 폴백하고 gateway를 즉시 시작합니다 -- `schtasks` 자체가 멈추거나 응답하지 않으면 OpenClaw는 이제 영원히 멈추는 대신 해당 경로를 빠르게 중단하고 폴백합니다 -- Scheduled Tasks는 더 나은 supervisor 상태를 제공하므로 사용 가능한 경우 여전히 선호됩니다 +- `openclaw onboard --non-interactive`는 여전히 `--skip-health`를 전달하지 않으면 도달 가능한 로컬 gateway를 기대합니다 +- `openclaw onboard --non-interactive --install-daemon`과 `openclaw gateway install`은 먼저 Windows 예약 작업을 시도합니다 +- 예약 작업 생성이 거부되면, OpenClaw는 사용자별 Startup 폴더 로그인 항목으로 대체하고 즉시 gateway를 시작합니다 +- `schtasks` 자체가 멈추거나 응답을 중지하면, OpenClaw는 이제 영원히 멈춰 있지 않고 해당 경로를 빠르게 중단하고 대체 경로로 전환합니다 +- 예약 작업은 더 나은 supervisor 상태를 제공하므로 가능할 때 여전히 우선적으로 사용됩니다 -네이티브 CLI만 원하고 gateway 서비스 설치는 원하지 않는다면 다음 중 하나를 사용하세요. +네이티브 CLI만 사용하고 gateway 서비스 설치는 원하지 않는다면, 다음 중 하나를 사용하세요: ```powershell openclaw onboard --non-interactive --skip-health @@ -62,12 +65,12 @@ openclaw gateway install openclaw gateway status --json ``` -Scheduled Task 생성이 차단되더라도, 폴백 서비스 모드는 현재 사용자의 Startup 폴더를 통해 로그인 후 자동 시작됩니다. +예약 작업 생성이 차단된 경우에도, 대체 서비스 모드는 현재 사용자의 Startup 폴더를 통해 로그인 후 자동 시작됩니다. ## Gateway -- [Gateway runbook](/gateway) -- [구성](/gateway/configuration) +- [Gateway 실행 가이드](/ko/gateway) +- [설정](/ko/gateway/configuration) ## Gateway 서비스 설치 (CLI) @@ -89,7 +92,7 @@ openclaw gateway install openclaw configure ``` -프롬프트가 뜨면 **Gateway service**를 선택하세요. +프롬프트가 표시되면 **Gateway service**를 선택하세요. 복구/마이그레이션: @@ -99,9 +102,9 @@ openclaw doctor ## Windows 로그인 전 Gateway 자동 시작 -헤드리스 구성에서는 아무도 Windows에 로그인하지 않아도 전체 부팅 체인이 실행되도록 해야 합니다. +헤드리스 설정의 경우, 아무도 Windows에 로그인하지 않아도 전체 부팅 체인이 실행되도록 해야 합니다. -### 1) 로그인 없이도 사용자 서비스 유지 +### 1) 로그인 없이도 사용자 서비스가 계속 실행되도록 설정 WSL 내부에서: @@ -119,13 +122,13 @@ openclaw gateway install ### 3) Windows 부팅 시 WSL 자동 시작 -관리자 권한 PowerShell에서: +관리자 권한으로 PowerShell에서: ```powershell schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM ``` -`Ubuntu`는 다음 명령으로 확인한 배포판 이름으로 교체하세요. +다음 명령으로 확인한 배포판 이름으로 `Ubuntu`를 바꾸세요: ```powershell wsl --list --verbose @@ -133,18 +136,21 @@ wsl --list --verbose ### 시작 체인 확인 -재부팅 후(Windows 로그인 전) WSL에서 다음을 확인하세요. +재부팅 후(Windows 로그인 전), WSL에서 다음을 확인하세요: ```bash systemctl --user is-enabled openclaw-gateway.service systemctl --user status openclaw-gateway.service --no-pager ``` -## 고급: WSL 서비스를 LAN에 노출(portproxy) +## 고급: LAN에서 WSL 서비스 노출하기 (portproxy) -WSL은 자체 가상 네트워크를 가집니다. 다른 머신이 **WSL 내부에서 실행 중인** 서비스(SSH, 로컬 TTS 서버, Gateway)에 도달해야 한다면, Windows 포트를 현재 WSL IP로 포워딩해야 합니다. WSL IP는 재시작 후 바뀌므로 포워딩 규칙을 새로 고쳐야 할 수 있습니다. +WSL은 자체 가상 네트워크를 사용합니다. 다른 머신이 **WSL 내부에서** +실행 중인 서비스(SSH, 로컬 TTS 서버, 또는 Gateway)에 접근해야 한다면, +Windows 포트를 현재 WSL IP로 포워딩해야 합니다. WSL IP는 재시작 후 변경되므로, +포워딩 규칙을 갱신해야 할 수 있습니다. -예시 (PowerShell **관리자 권한으로**): +예시(관리자 권한의 PowerShell): ```powershell $Distro = "Ubuntu-24.04" @@ -158,14 +164,14 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor connectaddress=$WslIp connectport=$TargetPort ``` -Windows Firewall에서 해당 포트를 허용합니다(1회): +Windows 방화벽에서 해당 포트를 허용하세요(1회만 수행): ```powershell New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound ` -Protocol TCP -LocalPort $ListenPort -Action Allow ``` -WSL 재시작 후 portproxy 새로 고침: +WSL 재시작 후 portproxy 갱신: ```powershell netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null @@ -175,16 +181,17 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0. 참고: -- 다른 머신에서의 SSH는 **Windows 호스트 IP**를 대상으로 해야 합니다(예: `ssh user@windows-host -p 2222`) -- 원격 노드는 **도달 가능한** Gateway URL(`127.0.0.1` 아님)을 가리켜야 합니다. `openclaw status --all`로 확인하세요. -- LAN 액세스에는 `listenaddress=0.0.0.0`를 사용하고, `127.0.0.1`은 로컬 전용입니다. -- 이를 자동화하려면 로그인 시 새로 고침 단계를 실행하는 Scheduled Task를 등록하세요. +- 다른 머신에서의 SSH 대상은 **Windows 호스트 IP**입니다(예: `ssh user@windows-host -p 2222`). +- 원격 Node는 **도달 가능한** Gateway URL(`127.0.0.1`이 아닌)을 가리켜야 합니다. 확인하려면 + `openclaw status --all`을 사용하세요. +- LAN 접근에는 `listenaddress=0.0.0.0`을 사용하고, `127.0.0.1`은 로컬 전용으로 유지합니다. +- 이를 자동화하고 싶다면, 로그인 시 갱신 단계를 실행하는 예약 작업을 등록하세요. ## 단계별 WSL2 설치 ### 1) WSL2 + Ubuntu 설치 -PowerShell(관리자)에서: +PowerShell(관리자)을 엽니다: ```powershell wsl --install @@ -212,7 +219,7 @@ EOF wsl --shutdown ``` -Ubuntu를 다시 열고 다음으로 확인하세요. +Ubuntu를 다시 연 뒤, 다음으로 확인하세요: ```bash systemctl --user status @@ -220,19 +227,30 @@ systemctl --user status ### 3) OpenClaw 설치 (WSL 내부) -WSL 내부에서 Linux Getting Started 흐름을 따르세요. +WSL 내부에서 일반적인 첫 설정을 하려면 Linux 시작하기 흐름을 따르세요: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install -pnpm ui:build # 첫 실행 시 UI 종속성 자동 설치 pnpm build -openclaw onboard +pnpm ui:build +pnpm openclaw onboard --install-daemon ``` -전체 가이드: [Getting Started](/ko/start/getting-started) +처음 온보딩이 아니라 소스에서 개발 중이라면, [Setup](/ko/start/setup)의 +소스 개발 루프를 사용하세요: -## Windows companion app +```bash +pnpm install +# 첫 실행 시에만(또는 로컬 OpenClaw config/workspace를 초기화한 후) +pnpm openclaw setup +pnpm gateway:watch +``` -아직 Windows companion app은 없습니다. 이를 실현하고 싶다면 contributions는 환영합니다. +전체 가이드: [시작하기](/ko/start/getting-started) + +## Windows 컴패니언 앱 + +아직 Windows 컴패니언 앱은 없습니다. 원하신다면 이를 실현하는 데 도움이 될 +기여를 환영합니다. diff --git a/docs/ko/start/setup.md b/docs/ko/start/setup.md index 7a80a1291..cface3984 100644 --- a/docs/ko/start/setup.md +++ b/docs/ko/start/setup.md @@ -1,14 +1,14 @@ --- read_when: - - 새 머신을 설정하는 경우 - - '"최신 + 최고"를 원하지만 개인 설정은 망가뜨리고 싶지 않은 경우' -summary: OpenClaw를 위한 고급 설정 및 개발 워크플로 + - 새 머신 설정하기 + - 개인 설정을 망가뜨리지 않으면서 “최신 + 최고” 상태를 원합니다 +summary: OpenClaw의 고급 설정 및 개발 워크플로우 title: 설정 x-i18n: - generated_at: "2026-04-05T12:55:46Z" + generated_at: "2026-04-20T06:05:27Z" model: gpt-5.4 provider: openai - source_hash: be4e280dde7f3a224345ca557ef2fb35a9c9db8520454ff63794ac6f8d4e71e7 + source_hash: 773cdbef5f38b069303b5e13fca5fcdc28f082746869f17b8b92aab1610b95a8 source_path: start/setup.md workflow: 15 --- @@ -16,79 +16,79 @@ x-i18n: # 설정 -처음 설정하는 경우 [Getting Started](/ko/start/getting-started)부터 시작하세요. -온보딩 세부 사항은 [Onboarding (CLI)](/ko/start/wizard)를 참조하세요. +처음 설정하는 경우 [시작하기](/ko/start/getting-started)부터 시작하세요. +온보딩 세부 정보는 [온보딩 (CLI)](/ko/start/wizard)를 참고하세요. -## 요약 +## TL;DR -- **사용자별 맞춤 설정은 리포지토리 밖에 있습니다:** `~/.openclaw/workspace`(워크스페이스) + `~/.openclaw/openclaw.json`(구성). -- **안정적인 워크플로:** macOS 앱을 설치하고, 번들된 Gateway를 실행하게 둡니다. -- **최첨단 워크플로:** `pnpm gateway:watch`로 직접 Gateway를 실행한 다음, macOS 앱이 로컬 모드에서 연결되게 둡니다. +- **맞춤 설정은 리포지토리 외부에 저장됩니다:** `~/.openclaw/workspace` (워크스페이스) + `~/.openclaw/openclaw.json` (구성). +- **안정적인 워크플로우:** macOS 앱을 설치하고, 번들된 Gateway를 실행하도록 둡니다. +- **최신 실험적 워크플로우:** `pnpm gateway:watch`로 직접 Gateway를 실행한 다음, macOS 앱이 로컬 모드에서 연결하도록 둡니다. -## 사전 요구 사항(소스에서) +## 사전 요구 사항(소스에서 실행) -- Node 24 권장(Node 22 LTS, 현재 `22.14+`, 역시 지원됨) -- `pnpm` 권장(또는 의도적으로 [Bun workflow](/ko/install/bun)를 사용하는 경우 Bun) -- Docker(선택 사항; 컨테이너화된 설정/e2e에만 필요 — [Docker](/ko/install/docker) 참조) +- Node 24 권장 (Node 22 LTS, 현재 `22.14+`,도 계속 지원됨) +- `pnpm` 권장(또는 의도적으로 [Bun 워크플로우](/ko/install/bun)를 사용하는 경우 Bun) +- Docker (선택 사항; 컨테이너 기반 설정/e2e에만 필요 — [Docker](/ko/install/docker) 참고) ## 맞춤 설정 전략(업데이트가 문제를 일으키지 않도록) -“나에게 100% 맞춤”이면서 _동시에_ 업데이트도 쉽게 하고 싶다면, 사용자 정의는 다음 위치에 유지하세요. +“나에게 100% 맞춤” _이면서_ 쉽게 업데이트하고 싶다면, 사용자 지정은 다음 위치에 유지하세요: -- **구성:** `~/.openclaw/openclaw.json` (JSON/JSON5 유사 형식) +- **구성:** `~/.openclaw/openclaw.json` (JSON/JSON5 비슷한 형식) - **워크스페이스:** `~/.openclaw/workspace` (skills, 프롬프트, 메모리; 비공개 git 리포지토리로 만드는 것을 권장) -한 번만 부트스트랩하세요. +한 번만 초기화하세요: ```bash openclaw setup ``` -이 리포지토리 내부에서는 로컬 CLI 엔트리를 사용하세요. +이 리포지토리 내부에서는 로컬 CLI 진입점을 사용하세요: ```bash openclaw setup ``` -아직 전역 설치가 없다면 `pnpm openclaw setup`으로 실행하세요(Bun workflow를 사용하는 경우 `bun run openclaw setup`). +아직 전역 설치가 없다면 `pnpm openclaw setup`으로 실행하세요(Bun 워크플로우를 사용하는 경우 `bun run openclaw setup`). ## 이 리포지토리에서 Gateway 실행 -`pnpm build` 후에는 패키지된 CLI를 직접 실행할 수 있습니다. +`pnpm build` 후에는 패키징된 CLI를 직접 실행할 수 있습니다: ```bash node openclaw.mjs gateway --port 18789 --verbose ``` -## 안정적인 워크플로(macOS 앱 우선) +## 안정적인 워크플로우(macOS 앱 우선) -1. **OpenClaw.app**을 설치하고 실행합니다(메뉴 막대). +1. **OpenClaw.app**(메뉴 막대)을 설치하고 실행합니다. 2. 온보딩/권한 체크리스트(TCC 프롬프트)를 완료합니다. -3. Gateway가 **Local**로 설정되어 실행 중인지 확인합니다(앱이 관리함). -4. 표면을 연결합니다(예: WhatsApp). +3. Gateway가 **Local**로 설정되어 실행 중인지 확인합니다(앱이 이를 관리함). +4. 표면을 연결합니다(예: WhatsApp): ```bash openclaw channels login ``` -5. 상태를 점검합니다. +5. 정상 동작 확인: ```bash openclaw health ``` -빌드에서 온보딩을 사용할 수 없는 경우: +빌드에 온보딩이 포함되어 있지 않은 경우: -- `openclaw setup`을 실행한 다음 `openclaw channels login`을 실행하고, 그다음 Gateway를 수동으로 시작하세요(`openclaw gateway`). +- `openclaw setup`을 실행한 다음 `openclaw channels login`을 실행하고, 그 후 Gateway를 수동으로 시작하세요(`openclaw gateway`). -## 최첨단 워크플로(터미널에서 Gateway 실행) +## 최신 실험적 워크플로우(터미널에서 Gateway 실행) -목표: TypeScript Gateway를 작업하고, 핫 리로드를 얻고, macOS 앱 UI는 계속 연결된 상태로 유지합니다. +목표: TypeScript Gateway를 개발하고, 핫 리로드를 사용하며, macOS 앱 UI는 계속 연결된 상태로 유지합니다. ### 0) (선택 사항) macOS 앱도 소스에서 실행 -macOS 앱도 최신 개발 상태로 사용하고 싶다면 다음을 실행하세요. +macOS 앱도 최신 실험적 상태로 사용하려면: ```bash ./scripts/restart-mac.sh @@ -98,81 +98,88 @@ macOS 앱도 최신 개발 상태로 사용하고 싶다면 다음을 실행하 ```bash pnpm install +# 첫 실행에서만 필요(또는 로컬 OpenClaw 구성/워크스페이스를 초기화한 후) +pnpm openclaw setup pnpm gateway:watch ``` -`gateway:watch`는 Gateway를 watch 모드로 실행하고, 관련 소스, -구성, 번들된 플러그인 메타데이터가 변경되면 다시 로드합니다. +`gateway:watch`는 감시 모드로 gateway를 실행하며, 관련 소스, +구성, 번들된 Plugin 메타데이터 변경 시 다시 로드합니다. +`pnpm openclaw setup`은 새 체크아웃에 대해 한 번만 수행하는 로컬 구성/워크스페이스 초기화 단계입니다. +`pnpm gateway:watch`는 `dist/control-ui`를 다시 빌드하지 않으므로, `ui/` 변경 후에는 `pnpm ui:build`를 다시 실행하거나 Control UI를 개발하는 동안 `pnpm ui:dev`를 사용하세요. -의도적으로 Bun workflow를 사용하는 경우, 동등한 명령은 다음과 같습니다. +의도적으로 Bun 워크플로우를 사용하는 경우, 동등한 명령은 다음과 같습니다: ```bash bun install +# 첫 실행에서만 필요(또는 로컬 OpenClaw 구성/워크스페이스를 초기화한 후) +bun run openclaw setup bun run gateway:watch ``` -### 2) 실행 중인 Gateway에 macOS 앱 연결 +### 2) 실행 중인 Gateway를 macOS 앱이 사용하도록 설정 **OpenClaw.app**에서: - 연결 모드: **Local** - 앱이 구성된 포트에서 실행 중인 Gateway에 연결됩니다. + 앱이 구성된 포트에서 실행 중인 gateway에 연결됩니다. ### 3) 확인 -- 앱 내 Gateway 상태에 **“Using existing gateway …”**가 표시되어야 합니다 -- 또는 CLI로 확인: +- 앱 내 Gateway 상태에 **“기존 gateway 사용 중 …”** 이라고 표시되어야 합니다. +- 또는 CLI에서: ```bash openclaw health ``` -### 흔한 함정 +### 흔히 겪는 문제 - **잘못된 포트:** Gateway WS 기본값은 `ws://127.0.0.1:18789`입니다. 앱과 CLI가 같은 포트를 사용하도록 유지하세요. - **상태가 저장되는 위치:** - - 채널/provider 상태: `~/.openclaw/credentials/` + - 채널/프로바이더 상태: `~/.openclaw/credentials/` - 모델 인증 프로필: `~/.openclaw/agents//agent/auth-profiles.json` - 세션: `~/.openclaw/agents//sessions/` - 로그: `/tmp/openclaw/` ## 자격 증명 저장소 맵 -인증을 디버깅하거나 무엇을 백업할지 결정할 때 이것을 사용하세요. +인증 문제를 디버깅하거나 무엇을 백업할지 결정할 때 사용하세요: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram bot token**: config/env 또는 `channels.telegram.tokenFile`(일반 파일만 허용; 심볼릭 링크는 거부됨) -- **Discord bot token**: config/env 또는 SecretRef(env/file/exec providers) -- **Slack 토큰**: config/env (`channels.slack.*`) +- **Telegram bot token**: config/env 또는 `channels.telegram.tokenFile` (일반 파일만 허용, symlink는 거부됨) +- **Discord bot token**: config/env 또는 SecretRef (env/file/exec providers) +- **Slack tokens**: config/env (`channels.slack.*`) - **페어링 허용 목록**: - `~/.openclaw/credentials/-allowFrom.json` (기본 계정) - - `~/.openclaw/credentials/--allowFrom.json` (비기본 계정) + - `~/.openclaw/credentials/--allowFrom.json` (기본이 아닌 계정) - **모델 인증 프로필**: `~/.openclaw/agents//agent/auth-profiles.json` -- **파일 기반 secrets payload(선택 사항)**: `~/.openclaw/secrets.json` +- **파일 기반 시크릿 페이로드(선택 사항)**: `~/.openclaw/secrets.json` - **레거시 OAuth 가져오기**: `~/.openclaw/credentials/oauth.json` - 자세한 내용: [Security](/ko/gateway/security#credential-storage-map). + 자세한 내용: [보안](/ko/gateway/security#credential-storage-map). ## 업데이트(설정을 망가뜨리지 않고) -- `~/.openclaw/workspace`와 `~/.openclaw/`를 “내 것”으로 유지하세요. 개인 프롬프트/구성을 `openclaw` 리포지토리에 넣지 마세요. -- 소스 업데이트: `git pull` + 선택한 패키지 관리자 설치 단계(기본값은 `pnpm install`, Bun workflow는 `bun install`) + 계속해서 일치하는 `gateway:watch` 명령을 사용하세요. +- `~/.openclaw/workspace`와 `~/.openclaw/`는 “내 것”으로 유지하세요. 개인 프롬프트/구성을 `openclaw` 리포지토리에 넣지 마세요. +- 소스 업데이트: `git pull` + 선택한 패키지 관리자 설치 단계(기본값은 `pnpm install`, Bun 워크플로우는 `bun install`) + 계속해서 같은 `gateway:watch` 명령을 사용하세요. ## Linux(systemd 사용자 서비스) -Linux 설치는 systemd **사용자** 서비스를 사용합니다. 기본적으로 systemd는 로그아웃/유휴 시 사용자 -서비스를 중지하므로 Gateway도 종료됩니다. 온보딩은 사용자를 위해 lingering을 활성화하려고 시도합니다(sudo를 요청할 수 있음). 여전히 꺼져 있다면 다음을 실행하세요. +Linux 설치는 systemd **사용자** 서비스를 사용합니다. 기본적으로 systemd는 +로그아웃/유휴 상태에서 사용자 서비스를 중지하므로 Gateway도 종료됩니다. 온보딩은 +사용자를 대신해 lingering을 활성화하려고 시도합니다(sudo 프롬프트가 나타날 수 있음). 여전히 비활성화되어 있으면 다음을 실행하세요: ```bash sudo loginctl enable-linger $USER ``` -항상 켜져 있어야 하거나 다중 사용자 서버라면, **사용자** 서비스 대신 **시스템** 서비스를 고려하세요 -(lingering 불필요). systemd 관련 참고 사항은 [Gateway runbook](/ko/gateway)을 참조하세요. +항상 켜져 있어야 하거나 다중 사용자 서버인 경우에는 +사용자 서비스 대신 **시스템** 서비스를 고려하세요(lingering 불필요). systemd 관련 참고 사항은 [Gateway 실행 가이드](/ko/gateway)를 확인하세요. ## 관련 문서 -- [Gateway runbook](/ko/gateway) (플래그, 감독, 포트) -- [Gateway configuration](/ko/gateway/configuration) (구성 스키마 + 예시) -- [Discord](/ko/channels/discord) 및 [Telegram](/ko/channels/telegram) (reply 태그 + replyToMode 설정) -- [OpenClaw assistant setup](/start/openclaw) -- [macOS app](/ko/platforms/macos) (gateway 수명 주기) +- [Gateway 실행 가이드](/ko/gateway) (플래그, 감독, 포트) +- [Gateway 구성](/ko/gateway/configuration) (구성 스키마 + 예시) +- [Discord](/ko/channels/discord) 및 [Telegram](/ko/channels/telegram) (답장 태그 + replyToMode 설정) +- [OpenClaw assistant 설정](/ko/start/openclaw) +- [macOS 앱](/ko/platforms/macos) (gateway 수명 주기) diff --git a/docs/ko/tools/browser.md b/docs/ko/tools/browser.md index 408b219e1..5ad836dd5 100644 --- a/docs/ko/tools/browser.md +++ b/docs/ko/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - - 에이전트가 제어하는 브라우저 자동화 추가 + - 에이전트 제어 브라우저 자동화 추가하기 - openclaw가 사용자의 Chrome에 간섭하는 이유 디버깅하기 - macOS 앱에서 브라우저 설정 및 수명 주기 구현하기 -summary: 통합 브라우저 제어 서비스 + 작업 명령 +summary: 통합 브라우저 제어 서비스 + 작업 명령어 title: 브라우저(OpenClaw 관리) x-i18n: - generated_at: "2026-04-14T13:04:24Z" + generated_at: "2026-04-20T06:05:57Z" model: gpt-5.4 provider: openai - source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- @@ -17,24 +17,25 @@ x-i18n: # 브라우저(openclaw 관리) OpenClaw는 에이전트가 제어하는 **전용 Chrome/Brave/Edge/Chromium 프로필**을 실행할 수 있습니다. -이 프로필은 개인 브라우저와 격리되어 있으며, Gateway 내부의 작은 로컬 +이 프로필은 개인 브라우저와 분리되어 있으며, Gateway 내부의 작은 로컬 제어 서비스(루프백 전용)를 통해 관리됩니다. -초보자용 설명: +초보자 관점에서 보면: -- 이것은 **별도의 에이전트 전용 브라우저**라고 생각하면 됩니다. +- 이것은 **에이전트 전용 별도 브라우저**라고 생각하면 됩니다. - `openclaw` 프로필은 개인 브라우저 프로필을 **건드리지 않습니다**. -- 에이전트는 안전한 경로에서 **탭 열기, 페이지 읽기, 클릭, 입력**을 수행할 수 있습니다. -- 기본 제공 `user` 프로필은 Chrome MCP를 통해 사용자의 실제 로그인된 Chrome 세션에 연결됩니다. +- 에이전트는 안전한 범위 안에서 **탭 열기, 페이지 읽기, 클릭, 입력**을 할 수 있습니다. +- 기본 제공 `user` 프로필은 Chrome MCP를 통해 실제 로그인된 Chrome 세션에 연결됩니다. ## 제공되는 기능 - **openclaw**라는 이름의 별도 브라우저 프로필(기본적으로 주황색 강조). -- 결정론적 탭 제어(목록/열기/포커스/닫기). -- 에이전트 작업(클릭/입력/드래그/선택), 스냅샷, 스크린샷, PDF. +- 결정론적인 탭 제어(list/open/focus/close). +- 에이전트 작업(click/type/drag/select), 스냅샷, 스크린샷, PDF. - 선택적 다중 프로필 지원(`openclaw`, `work`, `remote`, ...). -이 브라우저는 **일상적으로 사용하는 기본 브라우저가 아닙니다**. 에이전트 자동화와 검증을 위한 안전하고 격리된 표면입니다. +이 브라우저는 일상적으로 사용하는 브라우저가 **아닙니다**. 이것은 +에이전트 자동화와 검증을 위한 안전하고 분리된 표면입니다. ## 빠른 시작 @@ -45,14 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -“Browser disabled”가 표시되면 config에서 활성화하고(아래 참조) Gateway를 재시작하세요. +“Browser disabled”가 표시되면 구성에서 이를 활성화하고(아래 참고) Gateway를 +다시 시작하세요. -`openclaw browser` 명령 자체가 없거나, 에이전트가 브라우저 도구를 사용할 수 없다고 말하면 [브라우저 명령 또는 도구 누락](/ko/tools/browser#missing-browser-command-or-tool)으로 이동하세요. +`openclaw browser` 자체가 아예 없거나, 에이전트가 브라우저 도구를 +사용할 수 없다고 말하면 [브라우저 명령 또는 도구 누락](/ko/tools/browser#missing-browser-command-or-tool)으로 이동하세요. ## Plugin 제어 -기본 `browser` 도구는 이제 기본적으로 활성화되어 함께 제공되는 번들 Plugin입니다. -즉, OpenClaw의 나머지 Plugin 시스템을 제거하지 않고도 이를 비활성화하거나 교체할 수 있습니다. +기본 `browser` 도구는 이제 기본적으로 활성화되어 제공되는 번들 Plugin입니다. +즉, OpenClaw의 나머지 Plugin 시스템을 제거하지 않고도 이것을 비활성화하거나 교체할 수 있습니다: ```json5 { @@ -66,23 +69,28 @@ openclaw browser --browser-profile openclaw snapshot } ``` -동일한 `browser` 도구 이름을 제공하는 다른 Plugin을 설치하기 전에 번들 Plugin을 비활성화하세요. 기본 브라우저 경험이 작동하려면 둘 다 필요합니다. +같은 `browser` 도구 이름을 제공하는 다른 Plugin을 설치하기 전에 번들 Plugin을 비활성화하세요. 기본 브라우저 경험이 작동하려면 다음 두 가지가 모두 필요합니다: -- `plugins.entries.browser.enabled`가 비활성화되지 않은 상태 +- `plugins.entries.browser.enabled`가 비활성화되지 않아야 함 - `browser.enabled=true` -Plugin만 끄면 번들 브라우저 CLI(`openclaw browser`), Gateway 메서드(`browser.request`), 에이전트 도구, 기본 브라우저 제어 서비스가 모두 함께 사라집니다. `browser.*` config는 그대로 유지되므로 교체 Plugin이 재사용할 수 있습니다. +Plugin만 끄면 번들 브라우저 CLI(`openclaw browser`), +gateway 메서드(`browser.request`), 에이전트 도구, 기본 브라우저 제어 +서비스가 함께 모두 사라집니다. `browser.*` 구성은 교체 Plugin이 재사용할 수 있도록 그대로 유지됩니다. -이제 번들 브라우저 Plugin이 브라우저 런타임 구현도 소유합니다. -코어에는 공유 Plugin SDK 헬퍼와 이전 내부 import 경로용 호환성 re-export만 남아 있습니다. 실제로는 브라우저 Plugin 패키지를 제거하거나 교체하면, 코어가 소유한 두 번째 런타임이 남는 대신 브라우저 기능 세트 자체가 제거됩니다. +번들 브라우저 Plugin은 이제 브라우저 런타임 구현도 담당합니다. +코어에는 공유 Plugin SDK helper와 이전 내부 import 경로를 위한 호환성용 re-export만 남아 있습니다. 실질적으로는 브라우저 +Plugin 패키지를 제거하거나 교체하면 코어 소유의 두 번째 런타임이 남는 대신 브라우저 기능 세트 자체가 제거됩니다. -브라우저 config 변경은 여전히 Gateway 재시작이 필요하며, 그래야 번들 Plugin이 새 설정으로 브라우저 서비스를 다시 등록할 수 있습니다. +브라우저 구성 변경은 여전히 Gateway 재시작이 필요합니다. 그래야 번들 Plugin이 새 설정으로 브라우저 서비스를 다시 등록할 수 있습니다. ## 브라우저 명령 또는 도구 누락 -업그레이드 후 `openclaw browser`가 갑자기 알 수 없는 명령이 되거나, 에이전트가 브라우저 도구가 없다고 보고하는 경우 가장 흔한 원인은 `browser`를 포함하지 않는 제한적인 `plugins.allow` 목록입니다. +업그레이드 후 `openclaw browser`가 갑자기 알 수 없는 명령이 되거나, +에이전트가 브라우저 도구가 없다고 보고하는 경우, 가장 흔한 원인은 +`browser`를 포함하지 않는 제한적인 `plugins.allow` 목록입니다. -문제가 있는 config 예시: +문제가 있는 구성 예시: ```json5 { @@ -92,7 +100,7 @@ Plugin만 끄면 번들 브라우저 CLI(`openclaw browser`), Gateway 메서드( } ``` -Plugin 허용 목록에 `browser`를 추가하여 해결하세요. +Plugin 허용 목록에 `browser`를 추가해 해결하세요: ```json5 { @@ -106,8 +114,8 @@ Plugin 허용 목록에 `browser`를 추가하여 해결하세요. - `plugins.allow`가 설정된 경우 `browser.enabled=true`만으로는 충분하지 않습니다. - `plugins.allow`가 설정된 경우 `plugins.entries.browser.enabled=true`만으로도 충분하지 않습니다. -- `tools.alsoAllow: ["browser"]`는 번들 브라우저 Plugin을 로드하지 않습니다. 이는 Plugin이 이미 로드된 후 도구 정책만 조정합니다. -- 제한적인 Plugin 허용 목록이 필요 없다면 `plugins.allow`를 제거해도 기본 번들 브라우저 동작이 복원됩니다. +- `tools.alsoAllow: ["browser"]`는 번들 브라우저 Plugin을 로드하지 **않습니다**. 이는 Plugin이 이미 로드된 후에만 도구 정책을 조정합니다. +- 제한적인 Plugin 허용 목록이 필요 없다면 `plugins.allow`를 제거하는 것만으로도 기본 번들 브라우저 동작이 복원됩니다. 일반적인 증상: @@ -115,36 +123,38 @@ Plugin 허용 목록에 `browser`를 추가하여 해결하세요. - `browser.request`가 없습니다. - 에이전트가 브라우저 도구를 사용할 수 없거나 누락되었다고 보고합니다. -## 프로필: `openclaw` 대 `user` +## 프로필: `openclaw` vs `user` -- `openclaw`: 관리형, 격리된 브라우저(확장 프로그램 필요 없음). -- `user`: 사용자의 **실제 로그인된 Chrome** 세션용 기본 제공 Chrome MCP 연결 프로필. +- `openclaw`: 관리형, 분리된 브라우저(확장 프로그램 불필요). +- `user`: 사용자의 **실제 로그인된 Chrome** + 세션에 연결하는 기본 제공 Chrome MCP 연결 프로필. -에이전트 브라우저 도구 호출 시: +에이전트 브라우저 도구 호출의 경우: -- 기본값: 격리된 `openclaw` 브라우저를 사용합니다. -- 기존 로그인 세션이 중요하고 사용자가 컴퓨터 앞에서 연결 프롬프트를 클릭/승인할 수 있을 때는 `profile="user"`를 우선 사용하세요. +- 기본값: 분리된 `openclaw` 브라우저 사용. +- 기존 로그인 세션이 중요하고 사용자가 + attach 프롬프트를 클릭/승인할 수 있도록 컴퓨터 앞에 있는 경우 `profile="user"`를 권장합니다. - `profile`은 특정 브라우저 모드를 원할 때 사용하는 명시적 재정의입니다. -기본적으로 관리 모드를 사용하려면 `browser.defaultProfile: "openclaw"`를 설정하세요. +기본적으로 관리형 모드를 사용하려면 `browser.defaultProfile: "openclaw"`로 설정하세요. ## 구성 -브라우저 설정은 `~/.openclaw/openclaw.json`에 있습니다. +브라우저 설정은 `~/.openclaw/openclaw.json`에 저장됩니다. ```json5 { browser: { enabled: true, // 기본값: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // 신뢰된 사설 네트워크 액세스에만 opt in + // dangerouslyAllowPrivateNetwork: true, // 신뢰하는 사설 네트워크 액세스에만 명시적으로 허용 // allowPrivateNetwork: true, // 레거시 별칭 // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, // cdpUrl: "http://127.0.0.1:18792", // 레거시 단일 프로필 재정의 - remoteCdpTimeoutMs: 1500, // 원격 CDP HTTP 타임아웃(ms) - remoteCdpHandshakeTimeoutMs: 3000, // 원격 CDP WebSocket 핸드셰이크 타임아웃(ms) + remoteCdpTimeoutMs: 1500, // 원격 CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // 원격 CDP WebSocket 핸드셰이크 timeout (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -173,30 +183,32 @@ Plugin 허용 목록에 `browser`를 추가하여 해결하세요. 참고 사항: -- 브라우저 제어 서비스는 `gateway.port`에서 파생된 포트의 루프백에 바인딩됩니다. +- 브라우저 제어 서비스는 `gateway.port`에서 파생된 포트의 루프백에 바인딩됩니다 (기본값: `18791`, 즉 gateway + 2). -- Gateway 포트(`gateway.port` 또는 `OPENCLAW_GATEWAY_PORT`)를 재정의하면, +- Gateway 포트(`gateway.port` 또는 `OPENCLAW_GATEWAY_PORT`)를 재정의하면 파생된 브라우저 포트도 같은 “계열”을 유지하도록 함께 이동합니다. - `cdpUrl`이 설정되지 않으면 기본적으로 관리형 로컬 CDP 포트를 사용합니다. -- `remoteCdpTimeoutMs`는 원격(비루프백) CDP 연결 가능성 검사에 적용됩니다. -- `remoteCdpHandshakeTimeoutMs`는 원격 CDP WebSocket 연결 가능성 검사에 적용됩니다. -- 브라우저 탐색/탭 열기는 탐색 전에 SSRF 가드가 적용되며, 탐색 후 최종 `http(s)` URL에 대해서도 가능하면 다시 검사합니다. +- `remoteCdpTimeoutMs`는 원격(비루프백) CDP 도달 가능성 검사에 적용됩니다. +- `remoteCdpHandshakeTimeoutMs`는 원격 CDP WebSocket 도달 가능성 검사에 적용됩니다. +- 브라우저 탐색/탭 열기는 탐색 전에 SSRF 보호가 적용되며, 탐색 후 최종 `http(s)` URL에서도 가능한 범위 내에서 다시 검사됩니다. - 엄격한 SSRF 모드에서는 원격 CDP 엔드포인트 검색/프로브(`cdpUrl`, `/json/version` 조회 포함)도 검사됩니다. - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`는 기본적으로 비활성화되어 있습니다. 사설 네트워크 브라우저 액세스를 의도적으로 신뢰하는 경우에만 `true`로 설정하세요. - `browser.ssrfPolicy.allowPrivateNetwork`는 호환성을 위해 레거시 별칭으로 계속 지원됩니다. -- `attachOnly: true`는 “로컬 브라우저를 절대 실행하지 않고, 이미 실행 중일 때만 연결”을 의미합니다. -- `color`와 프로필별 `color`는 브라우저 UI에 색을 입혀 어떤 프로필이 활성화되어 있는지 볼 수 있게 합니다. -- 기본 프로필은 `openclaw`입니다(OpenClaw 관리형 독립 브라우저). 로그인된 사용자 브라우저를 사용하려면 `defaultProfile: "user"`를 사용하세요. -- 자동 감지 순서: 시스템 기본 브라우저가 Chromium 기반이면 그것을 사용하고, 아니면 Chrome → Brave → Edge → Chromium → Chrome Canary 순서입니다. -- 로컬 `openclaw` 프로필은 `cdpPort`/`cdpUrl`을 자동 할당합니다. 원격 CDP인 경우에만 이를 설정하세요. -- `driver: "existing-session"`은 원시 CDP 대신 Chrome DevTools MCP를 사용합니다. 이 +- `attachOnly: true`는 “로컬 브라우저를 절대 실행하지 않고, 이미 실행 중인 경우에만 연결”을 의미합니다. +- `color`와 프로필별 `color`는 브라우저 UI에 색조를 적용하여 어떤 프로필이 활성 상태인지 확인할 수 있게 해줍니다. +- 기본 프로필은 `openclaw`(OpenClaw 관리형 독립 브라우저)입니다. 로그인된 사용자 브라우저를 사용하려면 `defaultProfile: "user"`를 사용하세요. +- 자동 감지 순서: 시스템 기본 브라우저가 Chromium 기반이면 그것을 사용하고, 그렇지 않으면 Chrome → Brave → Edge → Chromium → Chrome Canary 순입니다. +- 로컬 `openclaw` 프로필은 `cdpPort`/`cdpUrl`을 자동 할당하므로, 원격 CDP가 아닌 경우에는 이것들을 설정하지 마세요. +- `driver: "existing-session"`은 raw CDP 대신 Chrome DevTools MCP를 사용합니다. 이 드라이버에는 `cdpUrl`을 설정하지 마세요. -- `browser.profiles..userDataDir`를 설정하면 기존 세션 프로필이 Brave 또는 Edge 같은 기본이 아닌 Chromium 사용자 프로필에 연결할 수 있습니다. +- 기존 세션 프로필이 Brave 또는 Edge 같은 비기본 Chromium 사용자 프로필에 + 연결되어야 하는 경우 `browser.profiles..userDataDir`을 설정하세요. ## Brave(또는 다른 Chromium 기반 브라우저) 사용 -**시스템 기본** 브라우저가 Chromium 기반(Chrome/Brave/Edge 등)이면 -OpenClaw가 자동으로 이를 사용합니다. 자동 감지를 재정의하려면 `browser.executablePath`를 설정하세요. +**시스템 기본** 브라우저가 Chromium 기반(Chrome/Brave/Edge 등)이라면 +OpenClaw가 이를 자동으로 사용합니다. 자동 감지를 재정의하려면 +`browser.executablePath`를 설정하세요: CLI 예시: @@ -230,47 +242,49 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## 로컬 제어와 원격 제어 - **로컬 제어(기본값):** Gateway가 루프백 제어 서비스를 시작하고 로컬 브라우저를 실행할 수 있습니다. -- **원격 제어(node host):** 브라우저가 있는 머신에서 node host를 실행하면 Gateway가 브라우저 작업을 해당 호스트로 프록시합니다. -- **원격 CDP:** 원격 Chromium 기반 브라우저에 연결하려면 `browser.profiles..cdpUrl`(또는 `browser.cdpUrl`)을 설정하세요. 이 경우 OpenClaw는 로컬 브라우저를 실행하지 않습니다. +- **원격 제어(Node 호스트):** 브라우저가 있는 머신에서 Node 호스트를 실행하면 Gateway가 브라우저 작업을 해당 호스트로 프록시합니다. +- **원격 CDP:** 원격 Chromium 기반 브라우저에 연결하려면 `browser.profiles..cdpUrl`(또는 `browser.cdpUrl`)을 + 설정하세요. 이 경우 OpenClaw는 로컬 브라우저를 실행하지 않습니다. -중지 동작은 프로필 모드에 따라 다릅니다. +중지 동작은 프로필 모드에 따라 다릅니다: - 로컬 관리형 프로필: `openclaw browser stop`은 - OpenClaw가 실행한 브라우저 프로세스를 중지합니다. + OpenClaw가 실행한 브라우저 프로세스를 중지합니다 - attach-only 및 원격 CDP 프로필: `openclaw browser stop`은 활성 - 제어 세션을 닫고 Playwright/CDP 에뮬레이션 재정의(뷰포트, - 색상 구성표, 로캘, 시간대, 오프라인 모드 및 유사 상태)를 해제하지만, - 브라우저 프로세스 자체는 OpenClaw가 실행한 것이 아니므로 종료하지 않습니다. + 제어 세션을 닫고 Playwright/CDP 에뮬레이션 재정의(viewport, + color scheme, locale, timezone, offline mode 및 유사한 상태)를 해제합니다. + 이 경우 OpenClaw가 브라우저 프로세스를 실행한 것은 아닙니다 -원격 CDP URL에는 인증이 포함될 수 있습니다. +원격 CDP URL에는 인증 정보를 포함할 수 있습니다: - 쿼리 토큰(예: `https://provider.example?token=`) -- HTTP Basic 인증(예: `https://user:pass@provider.example`) +- HTTP Basic auth(예: `https://user:pass@provider.example`) -OpenClaw는 `/json/*` 엔드포인트 호출 시와 -CDP WebSocket 연결 시 인증 정보를 유지합니다. 토큰은 config 파일에 커밋하지 말고 환경 변수나 시크릿 관리자 사용을 권장합니다. +OpenClaw는 `/json/*` 엔드포인트를 호출할 때와 +CDP WebSocket에 연결할 때 인증 정보를 보존합니다. 토큰은 구성 파일에 커밋하는 대신 +환경 변수나 시크릿 관리자 사용을 권장합니다. -## Node 브라우저 프록시(기본 zero-config) +## Node 브라우저 프록시(기본 제로 구성) -브라우저가 있는 머신에서 **node host**를 실행하면 OpenClaw는 -추가 브라우저 config 없이도 브라우저 도구 호출을 해당 노드로 자동 라우팅할 수 있습니다. -이것이 원격 Gateway의 기본 경로입니다. +브라우저가 있는 머신에서 **Node 호스트**를 실행하면 OpenClaw는 +추가 브라우저 구성 없이도 브라우저 도구 호출을 해당 Node로 자동 라우팅할 수 있습니다. +이것이 원격 gateway의 기본 경로입니다. 참고 사항: -- node host는 자체 로컬 브라우저 제어 서버를 **프록시 명령**으로 노출합니다. -- 프로필은 노드의 자체 `browser.profiles` config에서 가져옵니다(로컬과 동일). -- `nodeHost.browserProxy.allowProfiles`는 선택 사항입니다. 비워 두면 레거시/기본 동작이 적용되어 profile create/delete 경로를 포함한 모든 구성된 프로필이 프록시를 통해 계속 접근 가능합니다. -- `nodeHost.browserProxy.allowProfiles`를 설정하면 OpenClaw는 이를 최소 권한 경계로 취급합니다. 허용 목록에 있는 프로필만 대상으로 지정할 수 있고, 영구 프로필 create/delete 경로는 프록시 표면에서 차단됩니다. -- 원하지 않으면 비활성화하세요. - - 노드에서: `nodeHost.browserProxy.enabled=false` +- Node 호스트는 **프록시 명령**을 통해 로컬 브라우저 제어 서버를 노출합니다. +- 프로필은 Node 자체의 `browser.profiles` 구성(로컬과 동일)에서 가져옵니다. +- `nodeHost.browserProxy.allowProfiles`는 선택 사항입니다. 비워 두면 레거시/기본 동작이 적용되어, 프로필 생성/삭제 라우트를 포함한 모든 구성된 프로필이 프록시를 통해 계속 도달 가능합니다. +- `nodeHost.browserProxy.allowProfiles`를 설정하면 OpenClaw는 이를 최소 권한 경계로 취급합니다. 허용 목록에 있는 프로필만 대상으로 지정할 수 있으며, 영구 프로필 생성/삭제 라우트는 프록시 표면에서 차단됩니다. +- 원하지 않으면 비활성화하세요: + - Node에서: `nodeHost.browserProxy.enabled=false` - gateway에서: `gateway.nodes.browser.mode="off"` ## Browserless(호스팅된 원격 CDP) -[Browserless](https://browserless.io)는 HTTPS와 WebSocket을 통해 -CDP 연결 URL을 노출하는 호스팅 Chromium 서비스입니다. OpenClaw는 두 형식을 모두 사용할 수 있지만, -원격 브라우저 프로필에서는 Browserless 연결 문서에 있는 직접 WebSocket URL이 가장 간단한 옵션입니다. +[Browserless](https://browserless.io)는 +HTTPS와 WebSocket을 통해 CDP 연결 URL을 노출하는 호스팅 Chromium 서비스입니다. OpenClaw는 두 형식 모두 사용할 수 있지만, +원격 브라우저 프로필의 경우 가장 간단한 방법은 Browserless 연결 문서에 있는 직접 WebSocket URL을 사용하는 것입니다. 예시: @@ -294,27 +308,43 @@ CDP 연결 URL을 노출하는 호스팅 Chromium 서비스입니다. OpenClaw 참고 사항: - ``를 실제 Browserless 토큰으로 바꾸세요. -- Browserless 계정에 맞는 리전 엔드포인트를 선택하세요(자세한 내용은 해당 문서 참조). -- Browserless가 HTTPS 기본 URL을 제공하는 경우 직접 CDP 연결용으로 이를 - `wss://`로 변환하거나, HTTPS URL을 그대로 두고 OpenClaw가 - `/json/version`을 검색하도록 할 수 있습니다. +- Browserless 계정에 맞는 리전 엔드포인트를 선택하세요(문서 참고). +- Browserless가 HTTPS 기본 URL을 제공하는 경우, + 직접 CDP 연결을 위해 이를 `wss://`로 변환할 수도 있고 HTTPS URL을 유지한 채 OpenClaw가 + `/json/version`을 검색하도록 할 수도 있습니다. ## 직접 WebSocket CDP 제공업체 일부 호스팅 브라우저 서비스는 표준 HTTP 기반 CDP 검색(`/json/version`) 대신 -**직접 WebSocket** 엔드포인트를 노출합니다. OpenClaw는 두 방식을 모두 지원합니다. +**직접 WebSocket** 엔드포인트를 제공합니다. OpenClaw는 세 가지 +CDP URL 형식을 허용하며, 자동으로 올바른 연결 전략을 선택합니다: -- **HTTP(S) 엔드포인트** — OpenClaw는 `/json/version`을 호출해 - WebSocket 디버거 URL을 검색한 다음 연결합니다. -- **WebSocket 엔드포인트** (`ws://` / `wss://`) — OpenClaw가 `/json/version`을 건너뛰고 직접 연결합니다. 다음과 같은 서비스에 이 방식을 사용하세요: - [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com), 또는 WebSocket URL을 제공하는 모든 - 제공업체. +- **HTTP(S) 검색** — `http://host[:port]` 또는 `https://host[:port]`. + OpenClaw는 `/json/version`을 호출해 WebSocket 디버거 URL을 찾은 다음 + 연결합니다. WebSocket 폴백은 없습니다. +- **직접 WebSocket 엔드포인트** — `ws://host[:port]/devtools//` 또는 + `/devtools/browser|page|worker|shared_worker|service_worker/` 경로가 있는 `wss://...`. + OpenClaw는 WebSocket 핸드셰이크로 직접 연결하며 + `/json/version`은 완전히 건너뜁니다. +- **루트 WebSocket 주소** — `/devtools/...` 경로 없이 `ws://host[:port]` 또는 `wss://host[:port]` + (예: [Browserless](https://browserless.io), + [Browserbase](https://www.browserbase.com)). OpenClaw는 먼저 HTTP + `/json/version` 검색을 시도하며(스킴을 `http`/`https`로 정규화), + 검색 결과에 `webSocketDebuggerUrl`이 있으면 그것을 사용하고, 그렇지 않으면 OpenClaw는 + 루트 주소에서 직접 WebSocket 핸드셰이크로 폴백합니다. 이는 + Chrome 스타일 원격 디버그 포트와 WebSocket 전용 제공업체를 모두 포괄합니다. + +`/devtools/...` 경로 없이 로컬 Chrome 인스턴스를 가리키는 일반 +`ws://host:port` / `wss://host:port`도 검색 우선 +폴백을 통해 지원됩니다. Chrome은 `/json/version`이 반환한 브라우저별 +또는 대상별 특정 경로에서만 WebSocket 업그레이드를 허용하므로, 루트 주소에 대한 핸드셰이크만으로는 +실패합니다. ### Browserbase -[Browserbase](https://www.browserbase.com)는 내장 CAPTCHA 해결, 스텔스 모드, 주거용 -프록시를 갖춘 헤드리스 브라우저 실행용 클라우드 플랫폼입니다. +[Browserbase](https://www.browserbase.com)는 +내장 CAPTCHA 해결, 스텔스 모드, 주거용 프록시를 갖춘 +헤드리스 브라우저 실행용 클라우드 플랫폼입니다. ```json5 { @@ -335,77 +365,80 @@ CDP 연결 URL을 노출하는 호스팅 Chromium 서비스입니다. OpenClaw 참고 사항: -- [가입](https://www.browserbase.com/sign-up)한 뒤 [Overview dashboard](https://www.browserbase.com/overview)에서 **API Key**를 복사하세요. +- [가입](https://www.browserbase.com/sign-up)한 다음 [Overview dashboard](https://www.browserbase.com/overview)에서 + **API Key**를 복사하세요. - ``를 실제 Browserbase API 키로 바꾸세요. -- Browserbase는 WebSocket 연결 시 브라우저 세션을 자동으로 생성하므로 +- Browserbase는 WebSocket 연결 시 브라우저 세션을 자동 생성하므로 수동 세션 생성 단계가 필요하지 않습니다. - 무료 요금제는 동시 세션 1개와 월 1 브라우저 시간을 제공합니다. - 유료 요금제 한도는 [pricing](https://www.browserbase.com/pricing)을 참조하세요. + 유료 요금제 제한은 [pricing](https://www.browserbase.com/pricing)을 참고하세요. - 전체 API - 참조, SDK 가이드, 통합 예시는 [Browserbase docs](https://docs.browserbase.com)를 참조하세요. + 참조, SDK 가이드, 통합 예시는 [Browserbase docs](https://docs.browserbase.com)를 참고하세요. ## 보안 핵심 개념: -- 브라우저 제어는 루프백 전용이며, 액세스는 Gateway 인증 또는 node 페어링을 통해 이루어집니다. +- 브라우저 제어는 루프백 전용이며, 액세스는 Gateway의 인증 또는 Node 페어링을 통해 흐릅니다. - 독립형 루프백 브라우저 HTTP API는 **공유 시크릿 인증만** 사용합니다: gateway token bearer auth, `x-openclaw-password`, 또는 - 구성된 gateway password를 사용하는 HTTP Basic auth. -- Tailscale Serve identity 헤더와 `gateway.auth.mode: "trusted-proxy"`는 - 이 독립형 루프백 브라우저 API를 인증하지 않습니다. + 구성된 gateway password를 사용하는 HTTP Basic auth입니다. +- Tailscale Serve identity headers와 `gateway.auth.mode: "trusted-proxy"`는 + 이 독립형 루프백 브라우저 API를 **인증하지 않습니다**. - 브라우저 제어가 활성화되어 있고 공유 시크릿 인증이 구성되지 않은 경우, OpenClaw는 - 시작 시 `gateway.auth.token`을 자동 생성하고 이를 config에 저장합니다. -- `gateway.auth.mode`가 이미 - `password`, `none`, 또는 `trusted-proxy`인 경우에는 OpenClaw가 해당 token을 자동 생성하지 않습니다. -- Gateway와 모든 node host는 비공개 네트워크(Tailscale)에 유지하고, 공용 노출은 피하세요. -- 원격 CDP URL/token은 시크릿으로 취급하고, 환경 변수나 시크릿 관리자를 사용하는 것이 좋습니다. + 시작 시 `gateway.auth.token`을 자동 생성하여 구성에 저장합니다. +- `gateway.auth.mode`가 + 이미 `password`, `none`, 또는 `trusted-proxy`인 경우에는 OpenClaw가 해당 토큰을 자동 생성하지 않습니다. +- Gateway와 모든 Node 호스트는 비공개 네트워크(Tailscale)에 유지하고, 공개 노출은 피하세요. +- 원격 CDP URL/토큰은 시크릿으로 취급하고, 환경 변수나 시크릿 관리자를 사용하는 것이 좋습니다. 원격 CDP 팁: -- 가능하면 암호화된 엔드포인트(HTTPS 또는 WSS)와 짧은 수명의 token을 사용하세요. -- 오래 지속되는 token을 config 파일에 직접 포함하지 마세요. +- 가능하면 암호화된 엔드포인트(HTTPS 또는 WSS)와 수명이 짧은 토큰을 사용하세요. +- 수명이 긴 토큰을 구성 파일에 직접 포함하지 마세요. -## 프로필(다중 브라우저) +## 프로필(멀티 브라우저) -OpenClaw는 여러 개의 이름 있는 프로필(라우팅 config)을 지원합니다. 프로필은 다음 중 하나일 수 있습니다. +OpenClaw는 여러 개의 이름 있는 프로필(라우팅 구성)을 지원합니다. 프로필 유형은 다음과 같습니다: -- **openclaw-managed**: 자체 사용자 데이터 디렉터리와 CDP 포트를 가진 전용 Chromium 기반 브라우저 인스턴스 -- **remote**: 명시적인 CDP URL(다른 곳에서 실행 중인 Chromium 기반 브라우저) -- **existing session**: Chrome DevTools MCP 자동 연결을 통한 기존 Chrome 프로필 +- **openclaw 관리형**: 자체 사용자 데이터 디렉터리와 CDP 포트를 가진 전용 Chromium 기반 브라우저 인스턴스 +- **원격**: 명시적인 CDP URL(다른 위치에서 실행 중인 Chromium 기반 브라우저) +- **기존 세션**: Chrome DevTools MCP 자동 연결을 통한 사용자의 기존 Chrome 프로필 기본값: -- `openclaw` 프로필이 없으면 자동으로 생성됩니다. -- `user` 프로필은 Chrome MCP existing-session 연결용으로 기본 제공됩니다. -- existing-session 프로필은 `user` 외에는 opt-in이며, `--driver existing-session`으로 생성합니다. +- `openclaw` 프로필은 없으면 자동 생성됩니다. +- `user` 프로필은 Chrome MCP 기존 세션 연결용으로 기본 제공됩니다. +- 기존 세션 프로필은 `user` 외에는 명시적으로 선택해야 하며, `--driver existing-session`으로 생성합니다. - 로컬 CDP 포트는 기본적으로 **18800–18899** 범위에서 할당됩니다. - 프로필을 삭제하면 해당 로컬 데이터 디렉터리는 휴지통으로 이동합니다. -모든 제어 엔드포인트는 `?profile=`을 받으며, CLI는 `--browser-profile`을 사용합니다. +모든 제어 엔드포인트는 `?profile=`을 허용하며, CLI는 `--browser-profile`을 사용합니다. -## Chrome DevTools MCP를 통한 existing-session +## Chrome DevTools MCP를 통한 기존 세션 연결 -OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium 기반 브라우저 프로필에도 연결할 수 있습니다. 이렇게 하면 해당 브라우저 프로필에 이미 열려 있는 탭과 로그인 상태를 재사용할 수 있습니다. +OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium 기반 브라우저 프로필에 +연결할 수도 있습니다. 이 방법은 해당 브라우저 프로필에 이미 열려 있는 탭과 +로그인 상태를 그대로 재사용합니다. -공식 배경 자료 및 설정 참고 문서: +공식 배경 정보 및 설정 참고 자료: -- [Chrome for Developers: 브라우저 세션에서 Chrome DevTools MCP 사용](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) 기본 제공 프로필: - `user` -선택 사항: 다른 이름, 색상 또는 브라우저 데이터 디렉터리를 원한다면 -사용자 지정 existing-session 프로필을 직접 만들 수 있습니다. +선택 사항: 다른 이름, 색상, 브라우저 데이터 디렉터리를 원한다면 +직접 사용자 지정 기존 세션 프로필을 만들 수 있습니다. 기본 동작: -- 기본 제공 `user` 프로필은 Chrome MCP auto-connect를 사용하며, 이는 +- 기본 제공 `user` 프로필은 Chrome MCP 자동 연결을 사용하며, 이는 기본 로컬 Google Chrome 프로필을 대상으로 합니다. -Brave, Edge, Chromium 또는 기본이 아닌 Chrome 프로필에는 `userDataDir`을 사용하세요. +Brave, Edge, Chromium 또는 기본이 아닌 Chrome 프로필에는 `userDataDir`을 사용하세요: ```json5 { @@ -422,11 +455,11 @@ Brave, Edge, Chromium 또는 기본이 아닌 Chrome 프로필에는 `userDataDi } ``` -그런 다음 해당 브라우저에서 다음을 수행하세요. +그런 다음 해당 브라우저에서 다음을 수행하세요: 1. 원격 디버깅용 inspect 페이지를 엽니다. 2. 원격 디버깅을 활성화합니다. -3. 브라우저를 계속 실행한 상태로 두고 OpenClaw가 연결할 때 연결 프롬프트를 승인합니다. +3. 브라우저를 계속 실행한 상태로 두고, OpenClaw가 연결할 때 표시되는 연결 프롬프트를 승인합니다. 일반적인 inspect 페이지: @@ -434,7 +467,7 @@ Brave, Edge, Chromium 또는 기본이 아닌 Chrome 프로필에는 `userDataDi - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -실시간 연결 smoke 테스트: +실시간 연결 스모크 테스트: ```bash openclaw browser --browser-profile user start @@ -443,7 +476,7 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -성공 시 확인할 수 있는 모습: +성공 시 모습: - `status`에 `driver: existing-session`이 표시됨 - `status`에 `transport: chrome-mcp`가 표시됨 @@ -451,60 +484,66 @@ openclaw browser --browser-profile user snapshot --format ai - `tabs`에 이미 열려 있는 브라우저 탭이 나열됨 - `snapshot`이 선택된 실시간 탭의 ref를 반환함 -연결이 되지 않을 때 확인할 사항: +연결이 작동하지 않을 때 확인할 사항: - 대상 Chromium 기반 브라우저 버전이 `144+`인지 - 해당 브라우저의 inspect 페이지에서 원격 디버깅이 활성화되어 있는지 - 브라우저에 연결 동의 프롬프트가 표시되었고 이를 수락했는지 -- `openclaw doctor`는 이전 확장 프로그램 기반 브라우저 config를 마이그레이션하고 - 기본 auto-connect 프로필에 대해 Chrome이 로컬에 설치되어 있는지 확인하지만, +- `openclaw doctor`는 이전 확장 프로그램 기반 브라우저 구성을 마이그레이션하고 + 기본 자동 연결 프로필용으로 Chrome이 로컬에 설치되어 있는지 확인하지만, 브라우저 쪽 원격 디버깅을 대신 활성화해 주지는 않습니다 에이전트 사용: - 사용자의 로그인된 브라우저 상태가 필요할 때는 `profile="user"`를 사용하세요. -- 사용자 지정 existing-session 프로필을 사용하는 경우 해당 프로필 이름을 명시적으로 전달하세요. -- 이 모드는 사용자가 컴퓨터 앞에 있어 연결 - 프롬프트를 승인할 수 있을 때만 선택하세요. -- Gateway 또는 node host는 `npx chrome-devtools-mcp@latest --autoConnect`를 실행할 수 있습니다. +- 사용자 지정 기존 세션 프로필을 사용하는 경우에는 해당 명시적 프로필 이름을 전달하세요. +- 사용자가 컴퓨터 앞에서 연결 + 프롬프트를 승인할 수 있을 때만 이 모드를 선택하세요. +- Gateway 또는 Node 호스트는 `npx chrome-devtools-mcp@latest --autoConnect`를 실행할 수 있습니다 참고 사항: -- 이 경로는 로그인된 브라우저 세션 내부에서 동작할 수 있으므로 격리된 `openclaw` 프로필보다 위험도가 더 높습니다. -- 이 드라이버에 대해 OpenClaw는 브라우저를 실행하지 않고 기존 세션에만 연결합니다. -- 여기서 OpenClaw는 공식 Chrome DevTools MCP `--autoConnect` 흐름을 사용합니다. `userDataDir`이 설정된 경우 OpenClaw는 이를 그대로 전달해 해당 명시적 Chromium 사용자 데이터 디렉터리를 대상으로 지정합니다. -- existing-session 스크린샷은 페이지 캡처와 스냅샷의 `--ref` 요소 - 캡처를 지원하지만 CSS `--element` 선택자는 지원하지 않습니다. -- existing-session 페이지 스크린샷은 Playwright 없이도 Chrome MCP를 통해 작동합니다. - ref 기반 요소 스크린샷(`--ref`)도 여기서 작동하지만, `--full-page`는 +- 이 경로는 로그인된 브라우저 세션 내부에서 동작할 수 있으므로, 분리된 `openclaw` 프로필보다 + 위험성이 더 높습니다. +- OpenClaw는 이 드라이버에서 브라우저를 실행하지 않고, + 기존 세션에만 연결합니다. +- OpenClaw는 여기서 공식 Chrome DevTools MCP `--autoConnect` 흐름을 사용합니다. `userDataDir`이 설정된 경우, OpenClaw는 이를 전달하여 해당 명시적 + Chromium 사용자 데이터 디렉터리를 대상으로 삼습니다. +- 기존 세션 스크린샷은 페이지 캡처와 스냅샷의 `--ref` 요소 + 캡처는 지원하지만, CSS `--element` 선택자는 지원하지 않습니다. +- 기존 세션 페이지 스크린샷은 Chrome MCP를 통해 Playwright 없이도 동작합니다. + ref 기반 요소 스크린샷(`--ref`)도 여기서 동작하지만, `--full-page`는 `--ref` 또는 `--element`와 함께 사용할 수 없습니다. -- existing-session 작업은 관리형 브라우저 - 경로보다 여전히 더 제한적입니다. +- 기존 세션 작업은 관리형 브라우저 + 경로보다 여전히 제한이 더 많습니다: - `click`, `type`, `hover`, `scrollIntoView`, `drag`, `select`는 - CSS 선택자 대신 스냅샷 ref가 필요합니다 - - `click`은 왼쪽 버튼만 지원합니다(버튼 재정의나 수정 키 없음) + CSS 선택자 대신 snapshot ref가 필요합니다 + - `click`은 왼쪽 버튼만 지원합니다(버튼 재정의 또는 modifier 없음) - `type`은 `slowly=true`를 지원하지 않습니다. `fill` 또는 `press`를 사용하세요 - `press`는 `delayMs`를 지원하지 않습니다 - `hover`, `scrollIntoView`, `drag`, `select`, `fill`, `evaluate`는 - 호출별 타임아웃 재정의를 지원하지 않습니다 + 호출별 timeout 재정의를 지원하지 않습니다 - `select`는 현재 단일 값만 지원합니다 -- existing-session `wait --url`은 다른 브라우저 드라이버처럼 정확 일치, 부분 문자열, glob 패턴을 지원합니다. `wait --load networkidle`은 아직 지원되지 않습니다. -- existing-session 업로드 hook은 `ref` 또는 `inputRef`가 필요하고, 한 번에 하나의 파일만 지원하며, CSS `element` 대상 지정은 지원하지 않습니다. -- existing-session dialog hook은 타임아웃 재정의를 지원하지 않습니다. -- 일부 기능은 여전히 관리형 브라우저 경로가 필요합니다. 여기에는 batch - actions, PDF 내보내기, 다운로드 가로채기, `responsebody`가 포함됩니다. -- existing-session은 host-local입니다. Chrome이 다른 머신이나 - 다른 네트워크 네임스페이스에 있다면 대신 원격 CDP 또는 node host를 사용하세요. +- 기존 세션 `wait --url`은 다른 브라우저 드라이버처럼 정확 일치, 부분 문자열, glob 패턴을 + 지원합니다. `wait --load networkidle`은 아직 지원되지 않습니다. +- 기존 세션 업로드 hook은 `ref` 또는 `inputRef`가 필요하고, 한 번에 파일 하나만 지원하며, + CSS `element` 대상 지정은 지원하지 않습니다. +- 기존 세션 dialog hook은 timeout 재정의를 지원하지 않습니다. +- 일괄 작업, + PDF 내보내기, 다운로드 가로채기, `responsebody`를 포함한 일부 기능은 여전히 관리형 브라우저 경로가 필요합니다. +- 기존 세션은 선택된 호스트에서 직접 연결되거나 연결된 + 브라우저 Node를 통해 연결될 수 있습니다. Chrome이 다른 위치에 있고 브라우저 Node가 연결되어 있지 않다면, + 대신 원격 CDP 또는 Node 호스트를 사용하세요. ## 격리 보장 - **전용 사용자 데이터 디렉터리**: 개인 브라우저 프로필을 절대 건드리지 않습니다. -- **전용 포트**: 개발 워크플로와의 충돌을 방지하기 위해 `9222`를 사용하지 않습니다. -- **결정론적 탭 제어**: “마지막 탭”이 아니라 `targetId`로 탭을 대상으로 지정합니다. +- **전용 포트**: 개발 워크플로우와의 충돌을 막기 위해 `9222`를 피합니다. +- **결정론적인 탭 제어**: “마지막 탭”이 아니라 `targetId`로 탭을 지정합니다. ## 브라우저 선택 -로컬에서 실행할 때 OpenClaw는 사용 가능한 브라우저 중 첫 번째를 선택합니다. +로컬에서 실행할 때 OpenClaw는 사용 가능한 브라우저 중 첫 번째를 선택합니다: 1. Chrome 2. Brave @@ -514,7 +553,7 @@ openclaw browser --browser-profile user snapshot --format ai `browser.executablePath`로 재정의할 수 있습니다. -플랫폼: +플랫폼별 동작: - macOS: `/Applications`와 `~/Applications`를 확인합니다. - Linux: `google-chrome`, `brave`, `microsoft-edge`, `chromium` 등을 찾습니다. @@ -522,7 +561,7 @@ openclaw browser --browser-profile user snapshot --format ai ## 제어 API(선택 사항) -로컬 통합 전용으로 Gateway는 작은 루프백 HTTP API를 노출합니다. +로컬 통합 전용으로 Gateway는 작은 루프백 HTTP API를 노출합니다: - 상태/시작/중지: `GET /`, `POST /start`, `POST /stop` - 탭: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` @@ -537,24 +576,24 @@ openclaw browser --browser-profile user snapshot --format ai - 상태: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` - 설정: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device` -모든 엔드포인트는 `?profile=`을 받습니다. +모든 엔드포인트는 `?profile=`을 허용합니다. -공유 시크릿 gateway auth가 구성된 경우 브라우저 HTTP 경로에도 auth가 필요합니다. +공유 시크릿 gateway auth가 구성되어 있으면 브라우저 HTTP 라우트도 인증이 필요합니다: - `Authorization: Bearer ` - `x-openclaw-password: ` 또는 해당 password를 사용하는 HTTP Basic auth 참고 사항: -- 이 독립형 루프백 브라우저 API는 trusted-proxy 또는 - Tailscale Serve identity 헤더를 사용하지 않습니다. -- `gateway.auth.mode`가 `none` 또는 `trusted-proxy`인 경우에도 이 루프백 브라우저 - 경로는 그러한 identity 기반 모드를 상속하지 않으므로, 루프백 전용으로 유지하세요. +- 이 독립형 루프백 브라우저 API는 `trusted-proxy` 또는 + Tailscale Serve identity headers를 사용하지 않습니다. +- `gateway.auth.mode`가 `none` 또는 `trusted-proxy`인 경우에도, 이 루프백 브라우저 + 라우트는 이러한 ID 기반 모드를 상속하지 않으므로 루프백 전용으로 유지하세요. ### `/act` 오류 계약 -`POST /act`는 경로 수준 검증 및 -정책 실패에 대해 구조화된 오류 응답을 사용합니다. +`POST /act`는 라우트 수준 검증 및 +정책 실패에 대해 구조화된 오류 응답을 사용합니다: ```json { "error": "", "code": "ACT_*" } @@ -566,10 +605,10 @@ openclaw browser --browser-profile user snapshot --format ai - `ACT_INVALID_REQUEST` (HTTP 400): 작업 payload 정규화 또는 검증에 실패했습니다. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): 지원되지 않는 작업 종류에 `selector`가 사용되었습니다. - `ACT_EVALUATE_DISABLED` (HTTP 403): config에서 `evaluate`(또는 `wait --fn`)가 비활성화되어 있습니다. -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): 최상위 또는 batch의 `targetId`가 요청 대상과 충돌합니다. -- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): existing-session 프로필에서는 이 작업이 지원되지 않습니다. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): 최상위 또는 일괄 처리된 `targetId`가 요청 대상과 충돌합니다. +- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): 기존 세션 프로필에서는 이 작업이 지원되지 않습니다. -그 외 런타임 실패는 여전히 `code` +기타 런타임 실패는 여전히 `code` 필드 없이 `{ "error": "" }`를 반환할 수 있습니다. ### Playwright 요구 사항 @@ -578,7 +617,7 @@ openclaw browser --browser-profile user snapshot --format ai PDF)에는 Playwright가 필요합니다. Playwright가 설치되어 있지 않으면 해당 엔드포인트는 명확한 501 오류를 반환합니다. -Playwright 없이도 계속 작동하는 기능: +Playwright 없이도 여전히 작동하는 기능: - ARIA 스냅샷 - 탭별 CDP @@ -594,42 +633,43 @@ Playwright 없이도 계속 작동하는 기능: - CSS selector 요소 스크린샷(`--element`) - 전체 브라우저 PDF 내보내기 -요소 스크린샷은 `--full-page`도 거부합니다. 이 경로는 `fullPage is +요소 스크린샷은 `--full-page`도 거부합니다. 이 라우트는 `fullPage is not supported for element screenshots`를 반환합니다. `Playwright is not available in this gateway build`가 표시되면 전체 -Playwright 패키지(`playwright-core`가 아님)를 설치하고 gateway를 재시작하거나, +Playwright 패키지(`playwright-core`가 아님)를 설치한 뒤 gateway를 재시작하거나, 브라우저 지원이 포함된 OpenClaw를 다시 설치하세요. #### Docker Playwright 설치 -Gateway가 Docker에서 실행 중이면 `npx playwright`는 피하세요(npm override 충돌). -대신 번들 CLI를 사용하세요. +Gateway가 Docker에서 실행 중이라면 `npx playwright`는 피하세요(npm override 충돌). +대신 번들된 CLI를 사용하세요: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -브라우저 다운로드를 영구 보존하려면 `PLAYWRIGHT_BROWSERS_PATH`를 설정하고(예: -`/home/node/.cache/ms-playwright`), `/home/node`가 `OPENCLAW_HOME_VOLUME` 또는 bind mount를 통해 영구 저장되도록 하세요. 자세한 내용은 [Docker](/ko/install/docker)를 참조하세요. +브라우저 다운로드를 유지하려면 `PLAYWRIGHT_BROWSERS_PATH`를 설정하고(예: +`/home/node/.cache/ms-playwright`), `/home/node`가 `OPENCLAW_HOME_VOLUME` 또는 바인드 마운트를 통해 +유지되도록 하세요. 자세한 내용은 [Docker](/ko/install/docker)를 참고하세요. -## 작동 방식(내부) +## 동작 방식(내부) 상위 수준 흐름: - 작은 **제어 서버**가 HTTP 요청을 받습니다. - **CDP**를 통해 Chromium 기반 브라우저(Chrome/Brave/Edge/Chromium)에 연결합니다. -- 고급 작업(클릭/입력/스냅샷/PDF)에는 CDP 위에서 **Playwright**를 사용합니다. +- 고급 작업(click/type/snapshot/PDF)에는 CDP 위에서 **Playwright**를 사용합니다. - Playwright가 없으면 Playwright 비의존 작업만 사용할 수 있습니다. 이 설계는 에이전트가 안정적이고 결정론적인 인터페이스를 사용하도록 유지하면서, -로컬/원격 브라우저와 프로필을 자유롭게 바꿀 수 있게 해줍니다. +로컬/원격 브라우저와 프로필을 교체할 수 있게 해줍니다. ## CLI 빠른 참조 -모든 명령은 특정 프로필을 대상으로 지정하기 위해 `--browser-profile `을 받을 수 있습니다. -또한 모든 명령은 기계가 읽을 수 있는 출력(안정적인 payload)을 위해 `--json`도 받을 수 있습니다. +모든 명령은 특정 프로필을 대상으로 지정하기 위해 `--browser-profile `을 지원합니다. +또한 모든 명령은 기계 판독 가능한 출력(안정적인 payload)을 위해 `--json`을 지원합니다. 기본: @@ -662,9 +702,9 @@ docker compose run --rm openclaw-cli \ 수명 주기 참고: -- attach-only 및 원격 CDP 프로필의 경우에도 테스트 후 정리 명령으로는 여전히 - `openclaw browser stop`이 올바릅니다. 이 명령은 기반 - 브라우저를 종료하는 대신 활성 제어 세션을 닫고 임시 에뮬레이션 재정의를 지웁니다. +- attach-only 및 원격 CDP 프로필의 경우에도 `openclaw browser stop`은 테스트 후 + 올바른 정리 명령입니다. 이는 기본 브라우저를 종료하는 대신 활성 제어 세션을 닫고 + 임시 에뮬레이션 재정의를 해제합니다. - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` - `openclaw browser pdf` @@ -715,50 +755,51 @@ docker compose run --rm openclaw-cli \ 참고 사항: -- `upload`와 `dialog`는 **사전 준비(arming)** 호출입니다. 파일 선택기/대화상자를 트리거하는 click/press 전에 먼저 실행하세요. -- 다운로드 및 trace 출력 경로는 OpenClaw 임시 루트로 제한됩니다. - - traces: `/tmp/openclaw` (대체 경로: `${os.tmpdir()}/openclaw`) - - downloads: `/tmp/openclaw/downloads` (대체 경로: `${os.tmpdir()}/openclaw/downloads`) -- 업로드 경로는 OpenClaw 임시 uploads 루트로 제한됩니다. - - uploads: `/tmp/openclaw/uploads` (대체 경로: `${os.tmpdir()}/openclaw/uploads`) -- `upload`는 `--input-ref` 또는 `--element`를 통해 파일 입력을 직접 설정할 수도 있습니다. +- `upload`와 `dialog`는 **사전 준비** 호출입니다. 파일 선택기/대화 상자를 트리거하는 + click/press 전에 먼저 실행하세요. +- 다운로드 및 trace 출력 경로는 OpenClaw 임시 루트로 제한됩니다: + - traces: `/tmp/openclaw` (폴백: `${os.tmpdir()}/openclaw`) + - downloads: `/tmp/openclaw/downloads` (폴백: `${os.tmpdir()}/openclaw/downloads`) +- 업로드 경로는 OpenClaw 임시 uploads 루트로 제한됩니다: + - uploads: `/tmp/openclaw/uploads` (폴백: `${os.tmpdir()}/openclaw/uploads`) +- `upload`는 `--input-ref` 또는 `--element`를 통해 파일 input을 직접 설정할 수도 있습니다. - `snapshot`: - - `--format ai`(Playwright가 설치되어 있을 때 기본값): 숫자 ref(`aria-ref=""`)가 포함된 AI 스냅샷을 반환합니다. - - `--format aria`: 접근성 트리(ref 없음, 검사 전용)를 반환합니다. - - `--efficient`(또는 `--mode efficient`): 압축된 role 스냅샷 프리셋(interactive + compact + depth + 낮은 maxChars)입니다. - - config 기본값(도구/CLI 전용): 호출자가 mode를 전달하지 않을 때 효율적인 스냅샷을 사용하려면 `browser.snapshotDefaults.mode: "efficient"`를 설정하세요([Gateway configuration](/ko/gateway/configuration-reference#browser) 참조). + - `--format ai` (Playwright가 설치된 경우 기본값): 숫자 ref(`aria-ref=""`)가 포함된 AI 스냅샷을 반환합니다. + - `--format aria`: 접근성 트리를 반환합니다(ref 없음, 검사 전용). + - `--efficient`(또는 `--mode efficient`): 압축된 role 스냅샷 프리셋(interactive + compact + depth + 더 낮은 maxChars)입니다. + - config 기본값(도구/CLI 전용): 호출자가 mode를 전달하지 않을 때 efficient 스냅샷을 사용하려면 `browser.snapshotDefaults.mode: "efficient"`로 설정하세요([Gateway configuration](/ko/gateway/configuration-reference#browser) 참고). - Role 스냅샷 옵션(`--interactive`, `--compact`, `--depth`, `--selector`)은 `ref=e12` 같은 ref가 포함된 role 기반 스냅샷을 강제합니다. - `--frame "