diff --git a/docs/ko/channels/slack.md b/docs/ko/channels/slack.md index 549cfa6c9..9b0801dde 100644 --- a/docs/ko/channels/slack.md +++ b/docs/ko/channels/slack.md @@ -4,27 +4,27 @@ read_when: summary: Slack 설정 및 런타임 동작(Socket Mode + HTTP Request URL) title: Slack x-i18n: - generated_at: "2026-04-07T05:56:20Z" + generated_at: "2026-04-08T05:56:46Z" model: gpt-5.4 provider: openai - source_hash: 2b8fd2cc6c638ee82069f0af2c2b6f6f49c87da709b941433a0343724a9907ea + source_hash: cad132131ddce688517def7c14703ad314441c67aacc4cc2a2a721e1d1c01942 source_path: channels/slack.md workflow: 15 --- # Slack -상태: Slack 앱 통합을 통한 DM + 채널용 프로덕션 준비 완료. 기본 모드는 Socket Mode이며, HTTP Request URL도 지원됩니다. +상태: Slack 앱 통합을 통한 DM 및 채널에서 프로덕션 사용 가능. 기본 모드는 Socket Mode이며, HTTP Request URL도 지원됩니다. - Slack DM은 기본적으로 페어링 모드입니다. + Slack DM은 기본적으로 페어링 모드를 사용합니다. - 기본 명령 동작 및 명령 카탈로그. + 네이티브 명령 동작 및 명령 카탈로그. - 채널 전반의 진단 및 복구 플레이북. + 채널 전반 진단 및 복구 플레이북. @@ -38,8 +38,8 @@ x-i18n: - **from a manifest**를 선택하고 앱용 워크스페이스를 선택합니다 - 아래의 [예시 매니페스트](#manifest-and-scope-checklist)를 붙여넣고 계속 진행하여 생성합니다 - - `connections:write`가 포함된 **App-Level Token**(`xapp-...`)을 생성합니다 - - 앱을 설치하고 표시된 **Bot Token**(`xoxb-...`)을 복사합니다 + - `connections:write` 권한이 있는 **App-Level Token**(`xapp-...`)을 생성합니다 + - 앱을 설치하고 표시되는 **Bot Token**(`xoxb-...`)을 복사합니다 @@ -66,7 +66,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -85,7 +85,7 @@ openclaw gateway - **from a manifest**를 선택하고 앱용 워크스페이스를 선택합니다 - [예시 매니페스트](#manifest-and-scope-checklist)를 붙여넣고 생성 전에 URL을 업데이트합니다 - 요청 검증용 **Signing Secret**을 저장합니다 - - 앱을 설치하고 표시된 **Bot Token**(`xoxb-...`)을 복사합니다 + - 앱을 설치하고 표시되는 **Bot Token**(`xoxb-...`)을 복사합니다 @@ -106,14 +106,14 @@ openclaw gateway ``` - 멀티 계정 HTTP에는 고유한 webhook 경로를 사용하세요 + 멀티 계정 HTTP에는 고유한 웹훅 경로를 사용하세요 - 등록이 충돌하지 않도록 각 계정에 서로 다른 `webhookPath`(기본값 `/slack/events`)를 지정하세요. + 각 계정에 서로 다른 `webhookPath`(기본값 `/slack/events`)를 지정하여 등록이 충돌하지 않도록 하세요. - + ```bash openclaw gateway @@ -293,11 +293,11 @@ openclaw gateway 발신 메시지가 기본 Slack 앱 ID 대신 활성 에이전트 ID(사용자 지정 사용자 이름 및 아이콘)를 사용하도록 하려면 `chat:write.customize` 봇 스코프를 추가하세요. - 이모지 아이콘을 사용하는 경우 Slack은 `:emoji_name:` 문법을 기대합니다. + 이모지 아이콘을 사용하는 경우 Slack은 `:emoji_name:` 구문을 기대합니다. - - `channels.slack.userToken`을 구성하는 경우 일반적인 읽기 스코프는 다음과 같습니다: + + `channels.slack.userToken`을 구성하는 경우, 일반적인 읽기 스코프는 다음과 같습니다: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -315,8 +315,8 @@ openclaw gateway - Socket Mode에는 `botToken` + `appToken`이 필요합니다. - HTTP 모드에는 `botToken` + `signingSecret`이 필요합니다. - `botToken`, `appToken`, `signingSecret`, `userToken`은 일반 텍스트 - 문자열 또는 SecretRef 객체를 허용합니다. -- 구성 토큰이 환경 변수 대체값보다 우선합니다. + 문자열 또는 SecretRef 객체를 받을 수 있습니다. +- 구성 토큰은 환경 변수 대체값보다 우선합니다. - `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 환경 변수 대체값은 기본 계정에만 적용됩니다. - `userToken`(`xoxp-...`)은 구성 전용이며(환경 변수 대체값 없음), 기본값은 읽기 전용 동작(`userTokenReadOnly: true`)입니다. @@ -326,22 +326,22 @@ openclaw gateway 필드(`botToken`, `appToken`, `signingSecret`, `userToken`)를 추적합니다. - 상태는 `available`, `configured_unavailable`, `missing`입니다. - `configured_unavailable`은 계정이 SecretRef - 또는 다른 비인라인 시크릿 소스를 통해 구성되었지만, 현재 명령/런타임 경로에서 - 실제 값을 확인할 수 없었다는 뜻입니다. + 또는 다른 비인라인 비밀 소스를 통해 구성되었지만, 현재 명령/런타임 경로에서 + 실제 값을 확인할 수 없었음을 의미합니다. - HTTP 모드에서는 `signingSecretStatus`가 포함되며, Socket Mode에서는 필요한 쌍이 `botTokenStatus` + `appTokenStatus`입니다. -작업/디렉터리 읽기에서는 구성된 경우 사용자 토큰이 우선될 수 있습니다. 쓰기에서는 봇 토큰이 계속 우선이며, 사용자 토큰 쓰기는 `userTokenReadOnly: false`이고 봇 토큰을 사용할 수 없는 경우에만 허용됩니다. +작업/디렉터리 읽기에서는 구성된 경우 user token이 우선될 수 있습니다. 쓰기에서는 bot token이 계속 우선이며, user-token 쓰기는 `userTokenReadOnly: false`이고 bot token을 사용할 수 없을 때만 허용됩니다. ## 작업 및 게이트 Slack 작업은 `channels.slack.actions.*`로 제어됩니다. -현재 Slack 도구에서 사용 가능한 작업 그룹: +현재 Slack 도구에서 사용할 수 있는 작업 그룹: -| 그룹 | 기본값 | +| 그룹 | 기본값 | | ---------- | ------- | | messages | 활성화됨 | | reactions | 활성화됨 | @@ -359,7 +359,7 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. - `pairing` (기본값) - `allowlist` - - `open` (`channels.slack.allowFrom`에 `"*"`가 포함되어야 함, 레거시: `channels.slack.dm.allowFrom`) + - `open` (`channels.slack.allowFrom`에 `"*"`가 포함되어야 함; 레거시: `channels.slack.dm.allowFrom`) - `disabled` DM 플래그: @@ -373,15 +373,15 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. 멀티 계정 우선순위: - `channels.slack.accounts.default.allowFrom`은 `default` 계정에만 적용됩니다. - - 이름 있는 계정은 자체 `allowFrom`이 설정되지 않은 경우 `channels.slack.allowFrom`을 상속합니다. - - 이름 있는 계정은 `channels.slack.accounts.default.allowFrom`을 상속하지 않습니다. + - 이름이 있는 계정은 자체 `allowFrom`이 설정되지 않은 경우 `channels.slack.allowFrom`을 상속합니다. + - 이름이 있는 계정은 `channels.slack.accounts.default.allowFrom`을 상속하지 않습니다. - DM에서의 페어링은 `openclaw pairing approve slack `를 사용합니다. + DM의 페어링에는 `openclaw pairing approve slack `를 사용합니다. - `channels.slack.groupPolicy`는 채널 처리 방식을 제어합니다: + `channels.slack.groupPolicy`는 채널 처리를 제어합니다: - `open` - `allowlist` @@ -389,13 +389,13 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. 채널 허용 목록은 `channels.slack.channels` 아래에 있으며 안정적인 채널 ID를 사용해야 합니다. - 런타임 참고: `channels.slack`이 완전히 없으면(환경 변수 전용 설정), 런타임은 `groupPolicy="allowlist"`로 대체되고 경고를 기록합니다(`channels.defaults.groupPolicy`가 설정되어 있어도 마찬가지). + 런타임 참고: `channels.slack`이 완전히 없으면(환경 변수 전용 설정), 런타임은 `groupPolicy="allowlist"`로 대체하고 경고를 기록합니다(`channels.defaults.groupPolicy`가 설정되어 있어도 마찬가지). 이름/ID 확인: - 채널 허용 목록 항목과 DM 허용 목록 항목은 토큰 액세스가 허용되면 시작 시 확인됩니다 - - 확인되지 않은 채널 이름 항목은 구성된 그대로 유지되지만 기본적으로 라우팅에서 무시됩니다 - - 인바운드 인증 및 채널 라우팅은 기본적으로 ID 우선이며, 직접 사용자 이름/슬러그 일치는 `channels.slack.dangerouslyAllowNameMatching: true`가 필요합니다 + - 확인되지 않은 채널 이름 항목은 구성된 상태로 유지되지만 기본적으로 라우팅에서는 무시됩니다 + - 인바운드 인증 및 채널 라우팅은 기본적으로 ID 우선이며, 직접 사용자 이름/슬러그 매칭에는 `channels.slack.dangerouslyAllowNameMatching: true`가 필요합니다 @@ -404,11 +404,11 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. 멘션 소스: - - 명시적 앱 멘션(`<_@botId>`이 아니라 `<@botId>`) - - 멘션 정규식 패턴(`agents.list[].groupChat.mentionPatterns`, 대체값 `messages.groupChat.mentionPatterns`) - - 봇에게 답글을 단 스레드의 암시적 동작(`thread.requireExplicitMention`이 `true`이면 비활성화) + - 명시적 앱 멘션 (`<@botId>`) + - 멘션 정규식 패턴 (`agents.list[].groupChat.mentionPatterns`, 대체값 `messages.groupChat.mentionPatterns`) + - 암묵적인 bot 답글 스레드 동작 (`thread.requireExplicitMention`이 `true`이면 비활성화됨) - 채널별 제어(`channels.slack.channels.`; 이름은 시작 시 확인 또는 `dangerouslyAllowNameMatching`을 통해서만 사용): + 채널별 제어(`channels.slack.channels.`; 이름은 시작 시 확인 또는 `dangerouslyAllowNameMatching`을 통해서만 가능): - `requireMention` - `users` (허용 목록) @@ -417,25 +417,25 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. - `systemPrompt` - `tools`, `toolsBySender` - `toolsBySender` 키 형식: `id:`, `e164:`, `username:`, `name:`, 또는 `"*"` 와일드카드 - (레거시 접두사 없는 키도 여전히 `id:`에만 매핑됨) + (레거시 접두사 없는 키는 여전히 `id:`에만 매핑됨) -## 스레딩, 세션 및 답글 태그 +## 스레딩, 세션, 답글 태그 - DM은 `direct`로, 채널은 `channel`로, MPIM은 `group`으로 라우팅됩니다. -- 기본 `session.dmScope=main`에서는 Slack DM이 에이전트 기본 세션으로 합쳐집니다. +- 기본 `session.dmScope=main`에서는 Slack DM이 에이전트 메인 세션으로 통합됩니다. - 채널 세션: `agent::slack:channel:`. -- 스레드 답글은 해당하는 경우 스레드 세션 접미사(`:thread:`)를 만들 수 있습니다. -- `channels.slack.thread.historyScope` 기본값은 `thread`이며 `thread.inheritParent` 기본값은 `false`입니다. -- `channels.slack.thread.initialHistoryLimit`는 새 스레드 세션이 시작될 때 가져오는 기존 스레드 메시지 수를 제어합니다(기본값 `20`, 비활성화하려면 `0`으로 설정). -- `channels.slack.thread.requireExplicitMention`(기본값 `false`): `true`이면 암시적 스레드 멘션을 억제하므로 봇이 이미 스레드에 참여했더라도 스레드 내부의 명시적 `@bot` 멘션에만 응답합니다. 이 설정이 없으면 봇이 참여한 스레드의 답글은 `requireMention` 게이트를 우회합니다. +- 스레드 답글은 해당되는 경우 스레드 세션 접미사(`:thread:`)를 만들 수 있습니다. +- `channels.slack.thread.historyScope`의 기본값은 `thread`이며, `thread.inheritParent`의 기본값은 `false`입니다. +- `channels.slack.thread.initialHistoryLimit`은 새 스레드 세션이 시작될 때 가져올 기존 스레드 메시지 수를 제어합니다(기본값 `20`; 비활성화하려면 `0` 설정). +- `channels.slack.thread.requireExplicitMention`(기본값 `false`): `true`이면 암묵적인 스레드 멘션을 억제하므로, bot이 이미 스레드에 참여했더라도 스레드 안의 명시적 `@bot` 멘션에만 응답합니다. 이 설정이 없으면 bot이 참여한 스레드의 답글은 `requireMention` 게이트를 우회합니다. 답글 스레딩 제어: - `channels.slack.replyToMode`: `off|first|all|batched` (기본값 `off`) -- `channels.slack.replyToModeByChatType`: `direct|group|channel`별 설정 +- `channels.slack.replyToModeByChatType`: `direct|group|channel`별 - direct 채팅용 레거시 대체값: `channels.slack.dm.replyToMode` 수동 답글 태그가 지원됩니다: @@ -443,47 +443,51 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. - `[[reply_to_current]]` - `[[reply_to:]]` -참고: `replyToMode="off"`는 명시적 `[[reply_to_*]]` 태그를 포함한 Slack의 **모든** 답글 스레딩을 비활성화합니다. 이는 `"off"` 모드에서도 명시적 태그가 계속 존중되는 Telegram과 다릅니다. 이 차이는 플랫폼의 스레딩 모델을 반영합니다. Slack 스레드는 메시지를 채널에서 숨기지만, Telegram 답글은 기본 채팅 흐름에서 계속 보입니다. +참고: `replyToMode="off"`는 명시적 `[[reply_to_*]]` 태그를 포함해 Slack의 **모든** 답글 스레딩을 비활성화합니다. 이는 `"off"` 모드에서도 명시적 태그가 계속 적용되는 Telegram과 다릅니다. 이 차이는 플랫폼별 스레딩 모델을 반영합니다. Slack 스레드는 메시지를 채널에서 숨기지만, Telegram 답글은 메인 채팅 흐름에서 계속 표시됩니다. ## 확인 반응 -`ackReaction`은 OpenClaw가 인바운드 메시지를 처리하는 동안 확인용 이모지를 보냅니다. +`ackReaction`은 OpenClaw가 인바운드 메시지를 처리하는 동안 확인 이모지를 보냅니다. 확인 순서: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 에이전트 ID 이모지 대체값(`agents.list[].identity.emoji`, 없으면 `"👀"`) +- 에이전트 ID 이모지 대체값 (`agents.list[].identity.emoji`, 없으면 `"👀"`) 참고: -- Slack은 쇼트코드(예: `"eyes"`)를 기대합니다. -- Slack 계정별 또는 전역으로 반응을 비활성화하려면 `""`를 사용하세요. +- Slack은 shortcode를 기대합니다(예: `"eyes"`). +- Slack 계정 또는 전역에서 반응을 비활성화하려면 `""`를 사용하세요. ## 텍스트 스트리밍 -`channels.slack.streaming`은 라이브 미리보기 동작을 제어합니다: +`channels.slack.streaming`은 실시간 미리보기 동작을 제어합니다: -- `off`: 라이브 미리보기 스트리밍을 비활성화합니다. -- `partial` (기본값): 미리보기 텍스트를 최신 부분 출력으로 교체합니다. -- `block`: 청크 단위 미리보기 업데이트를 추가합니다. -- `progress`: 생성 중에는 진행 상태 텍스트를 표시하고, 완료 후 최종 텍스트를 보냅니다. +- `off`: 실시간 미리보기 스트리밍 비활성화. +- `partial` (기본값): 미리보기 텍스트를 최신 부분 출력으로 교체. +- `block`: 청크 단위 미리보기 업데이트를 추가. +- `progress`: 생성 중에는 진행 상태 텍스트를 표시하고, 이후 최종 텍스트를 전송. -`channels.slack.nativeStreaming`은 `streaming`이 `partial`일 때 Slack 기본 텍스트 스트리밍을 제어합니다(기본값: `true`). +`channels.slack.streaming.nativeTransport`는 `channels.slack.streaming.mode`가 `partial`일 때 Slack 네이티브 텍스트 스트리밍을 제어합니다(기본값: `true`). -- 기본 텍스트 스트리밍이 표시되려면 답글 스레드를 사용할 수 있어야 합니다. 스레드 선택은 계속 `replyToMode`를 따릅니다. 스레드가 없으면 일반 초안 미리보기가 사용됩니다. -- 미디어 및 비텍스트 페이로드는 일반 전송으로 대체됩니다. -- 스트리밍이 답글 중간에 실패하면 OpenClaw는 남은 페이로드를 일반 전송으로 대체합니다. +- 네이티브 텍스트 스트리밍과 Slack assistant 스레드 상태를 표시하려면 답글 스레드를 사용할 수 있어야 합니다. 스레드 선택은 여전히 `replyToMode`를 따릅니다. +- 채널 및 그룹 채팅 루트는 네이티브 스트리밍을 사용할 수 없을 때 일반 초안 미리보기를 계속 사용할 수 있습니다. +- 최상위 Slack DM은 기본적으로 스레드 밖이므로 스레드 스타일 미리보기가 표시되지 않습니다. 그곳에서 표시 가능한 진행 상태가 필요하면 스레드 답글 또는 `typingReaction`을 사용하세요. +- 미디어 및 비텍스트 페이로드는 일반 전달로 대체됩니다. +- 스트리밍이 답글 중간에 실패하면 OpenClaw는 남은 페이로드를 일반 전달로 대체합니다. -Slack 기본 텍스트 스트리밍 대신 초안 미리보기를 사용하려면: +Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기 사용: ```json5 { channels: { slack: { - streaming: "partial", - nativeStreaming: false, + streaming: { + mode: "partial", + nativeTransport: false, + }, }, }, } @@ -491,12 +495,13 @@ Slack 기본 텍스트 스트리밍 대신 초안 미리보기를 사용하려 레거시 키: -- `channels.slack.streamMode` (`replace | status_final | append`)는 `channels.slack.streaming`으로 자동 마이그레이션됩니다. -- 불리언 `channels.slack.streaming`은 `channels.slack.nativeStreaming`으로 자동 마이그레이션됩니다. +- `channels.slack.streamMode` (`replace | status_final | append`)는 자동으로 `channels.slack.streaming.mode`로 마이그레이션됩니다. +- 불리언 `channels.slack.streaming`은 자동으로 `channels.slack.streaming.mode` 및 `channels.slack.streaming.nativeTransport`로 마이그레이션됩니다. +- 레거시 `channels.slack.nativeStreaming`은 자동으로 `channels.slack.streaming.nativeTransport`로 마이그레이션됩니다. ## 입력 중 반응 대체 동작 -`typingReaction`은 OpenClaw가 답글을 처리하는 동안 인바운드 Slack 메시지에 임시 반응을 추가한 뒤, 실행이 끝나면 제거합니다. 이는 기본 `"is typing..."` 상태 표시기를 사용하는 스레드 답글 외부에서 특히 유용합니다. +`typingReaction`은 OpenClaw가 답글을 처리하는 동안 인바운드 Slack 메시지에 임시 반응을 추가하고, 실행이 끝나면 제거합니다. 이는 기본 `"is typing..."` 상태 표시기를 사용하는 스레드 답글 밖에서 특히 유용합니다. 확인 순서: @@ -505,50 +510,50 @@ Slack 기본 텍스트 스트리밍 대신 초안 미리보기를 사용하려 참고: -- Slack은 쇼트코드(예: `"hourglass_flowing_sand"`)를 기대합니다. -- 이 반응은 최선의 노력으로 처리되며, 답글 또는 실패 경로가 완료되면 자동으로 정리하려고 시도합니다. +- Slack은 shortcode를 기대합니다(예: `"hourglass_flowing_sand"`). +- 이 반응은 최선형(best-effort)이며, 답글 또는 실패 경로가 완료된 후 자동으로 정리되도록 시도합니다. -## 미디어, 청크 분할 및 전송 +## 미디어, 청크 분할 및 전달 - Slack 파일 첨부는 Slack이 호스팅하는 비공개 URL에서 다운로드되며(토큰 인증 요청 흐름), 가져오기가 성공하고 크기 제한을 만족하면 미디어 저장소에 기록됩니다. + Slack 파일 첨부 파일은 Slack이 호스팅하는 비공개 URL에서 다운로드되며(토큰 인증 요청 흐름), 가져오기에 성공하고 크기 제한을 충족하면 미디어 저장소에 기록됩니다. - 런타임 인바운드 크기 제한은 `channels.slack.mediaMaxMb`로 재정의하지 않으면 기본적으로 `20MB`입니다. + 런타임 인바운드 크기 제한의 기본값은 `20MB`이며, `channels.slack.mediaMaxMb`로 재정의할 수 있습니다. - - 텍스트 청크는 `channels.slack.textChunkLimit`(기본값 4000)을 사용합니다 + - 텍스트 청크는 `channels.slack.textChunkLimit`을 사용합니다(기본값 4000) - `channels.slack.chunkMode="newline"`은 문단 우선 분할을 활성화합니다 - 파일 전송은 Slack 업로드 API를 사용하며 스레드 답글(`thread_ts`)을 포함할 수 있습니다 - - 아웃바운드 미디어 한도는 구성된 경우 `channels.slack.mediaMaxMb`를 따르며, 그렇지 않으면 채널 전송은 미디어 파이프라인의 MIME 종류 기본값을 사용합니다 + - 아웃바운드 미디어 제한은 구성된 경우 `channels.slack.mediaMaxMb`를 따르며, 그렇지 않으면 채널 전송은 미디어 파이프라인의 MIME 종류 기본값을 사용합니다 - + 권장되는 명시적 대상: - - DM용 `user:` - - 채널용 `channel:` + - DM의 경우 `user:` + - 채널의 경우 `channel:` - 사용자 대상으로 보낼 때 Slack DM은 Slack 대화 API를 통해 열립니다. + 사용자 대상으로 전송할 때 Slack DM은 Slack 대화 API를 통해 열립니다. ## 명령 및 슬래시 동작 -- Slack에서는 기본 명령 자동 모드가 **꺼짐**입니다(`commands.native: "auto"`는 Slack 기본 명령을 활성화하지 않음). -- `channels.slack.commands.native: true`(또는 전역 `commands.native: true`)로 기본 Slack 명령 핸들러를 활성화하세요. -- 기본 명령이 활성화되면 Slack에 일치하는 슬래시 명령(`/` 이름)을 등록하세요. 단, 예외가 하나 있습니다: +- Slack에서는 네이티브 명령 자동 모드가 **비활성화**되어 있습니다(`commands.native: "auto"`는 Slack 네이티브 명령을 활성화하지 않음). +- `channels.slack.commands.native: true`(또는 전역 `commands.native: true`)로 네이티브 Slack 명령 핸들러를 활성화하세요. +- 네이티브 명령이 활성화되면 Slack에 일치하는 슬래시 명령(`/` 이름)을 등록합니다. 단, 예외가 하나 있습니다: - 상태 명령에는 `/agentstatus`를 등록하세요(Slack은 `/status`를 예약함) -- 기본 명령이 활성화되지 않은 경우 `channels.slack.slashCommand`를 통해 구성된 단일 슬래시 명령을 실행할 수 있습니다. -- 기본 인자 메뉴는 이제 렌더링 전략을 자동으로 조정합니다: +- 네이티브 명령이 활성화되지 않은 경우 `channels.slack.slashCommand`를 통해 단일 구성된 슬래시 명령을 실행할 수 있습니다. +- 네이티브 인수 메뉴는 이제 렌더링 전략을 동적으로 조정합니다: - 최대 5개 옵션: 버튼 블록 - 6-100개 옵션: 정적 선택 메뉴 - - 100개 초과 옵션: 인터랙티비티 옵션 핸들러를 사용할 수 있을 때 비동기 옵션 필터링이 포함된 외부 선택 - - 인코딩된 옵션 값이 Slack 한도를 초과하면 흐름은 버튼으로 대체됩니다 -- 긴 옵션 페이로드의 경우 슬래시 명령 인자 메뉴는 선택한 값을 디스패치하기 전에 확인 대화상자를 사용합니다. + - 100개 초과 옵션: interactivity 옵션 핸들러를 사용할 수 있으면 비동기 옵션 필터링이 가능한 외부 선택 + - 인코딩된 옵션 값이 Slack 제한을 초과하면 흐름은 버튼으로 대체됩니다 +- 긴 옵션 페이로드의 경우, 슬래시 명령 인수 메뉴는 선택한 값을 디스패치하기 전에 확인 대화상자를 사용합니다. 기본 슬래시 명령 설정: @@ -563,11 +568,11 @@ Slack 기본 텍스트 스트리밍 대신 초안 미리보기를 사용하려 그리고 여전히 대상 대화 세션(`CommandTargetSessionKey`)에 대해 명령 실행을 라우팅합니다. -## 인터랙티브 답글 +## 대화형 답글 -Slack은 에이전트가 작성한 인터랙티브 답글 컨트롤을 렌더링할 수 있지만, 이 기능은 기본적으로 비활성화되어 있습니다. +Slack은 에이전트가 작성한 대화형 답글 컨트롤을 렌더링할 수 있지만, 이 기능은 기본적으로 비활성화되어 있습니다. -전역으로 활성화하려면: +전역으로 활성화: ```json5 { @@ -581,7 +586,7 @@ Slack은 에이전트가 작성한 인터랙티브 답글 컨트롤을 렌더링 } ``` -또는 하나의 Slack 계정에만 활성화하려면: +또는 하나의 Slack 계정에만 활성화: ```json5 { @@ -599,43 +604,43 @@ Slack은 에이전트가 작성한 인터랙티브 답글 컨트롤을 렌더링 } ``` -활성화되면 에이전트는 Slack 전용 답글 지시문을 출력할 수 있습니다: +활성화되면 에이전트는 Slack 전용 답글 지시자를 출력할 수 있습니다: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -이 지시문은 Slack Block Kit으로 컴파일되며 기존 Slack 상호작용 이벤트 경로를 통해 클릭 또는 선택을 다시 라우팅합니다. +이 지시자는 Slack Block Kit로 컴파일되며 클릭 또는 선택을 기존 Slack 상호작용 이벤트 경로를 통해 다시 라우팅합니다. 참고: -- 이것은 Slack 전용 UI입니다. 다른 채널은 Slack Block Kit 지시문을 자체 버튼 시스템으로 변환하지 않습니다. -- 인터랙티브 콜백 값은 OpenClaw가 생성한 불투명 토큰이며, 에이전트가 작성한 원시 값이 아닙니다. -- 생성된 인터랙티브 블록이 Slack Block Kit 제한을 초과하면 OpenClaw는 잘못된 blocks 페이로드를 보내는 대신 원래 텍스트 답글로 대체합니다. +- 이것은 Slack 전용 UI입니다. 다른 채널은 Slack Block Kit 지시자를 자체 버튼 시스템으로 변환하지 않습니다. +- 대화형 콜백 값은 에이전트가 작성한 원시 값이 아니라 OpenClaw가 생성한 불투명 토큰입니다. +- 생성된 대화형 블록이 Slack Block Kit 제한을 초과하면 OpenClaw는 잘못된 블록 페이로드를 전송하는 대신 원래 텍스트 답글로 대체합니다. -## Slack의 실행 승인 +## Slack의 exec 승인 -Slack은 Web UI나 터미널로 대체되는 대신, 인터랙티브 버튼과 상호작용을 사용하는 기본 승인 클라이언트로 동작할 수 있습니다. +Slack은 Web UI 또는 터미널로 대체되는 대신, 대화형 버튼과 상호작용을 갖춘 네이티브 승인 클라이언트로 동작할 수 있습니다. -- 실행 승인은 기본 DM/채널 라우팅에 `channels.slack.execApprovals.*`를 사용합니다. -- 플러그인 승인은 요청이 이미 Slack에 도착했고 승인 ID 종류가 `plugin:`인 경우 동일한 Slack 기본 버튼 표면을 통해 계속 확인될 수 있습니다. -- 승인자 권한 부여는 계속 강제됩니다. 승인자로 식별된 사용자만 Slack을 통해 요청을 승인하거나 거부할 수 있습니다. +- exec 승인은 네이티브 DM/채널 라우팅에 `channels.slack.execApprovals.*`를 사용합니다. +- 승인 요청이 이미 Slack에 도착했고 승인 ID 종류가 `plugin:`인 경우, plugin 승인은 동일한 Slack 네이티브 버튼 표면을 통해 계속 해결될 수 있습니다. +- 승인자 권한 부여는 계속 적용됩니다. 승인자로 식별된 사용자만 Slack을 통해 요청을 승인하거나 거부할 수 있습니다. 이 기능은 다른 채널과 동일한 공유 승인 버튼 표면을 사용합니다. Slack 앱 설정에서 `interactivity`가 활성화되면 승인 프롬프트는 대화에 직접 Block Kit 버튼으로 렌더링됩니다. -이 버튼이 있으면 기본 승인 UX가 되며, OpenClaw는 +이 버튼이 있으면 그것이 기본 승인 UX이며, OpenClaw는 도구 결과에서 채팅 승인을 사용할 수 없거나 수동 승인이 유일한 경로라고 표시하는 경우에만 수동 `/approve` 명령을 포함해야 합니다. 구성 경로: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (선택 사항, 가능하면 `commands.ownerAllowFrom`으로 대체) +- `channels.slack.execApprovals.approvers` (선택 사항; 가능한 경우 `commands.ownerAllowFrom`으로 대체) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, 기본값: `dm`) - `agentFilter`, `sessionFilter` Slack은 `enabled`가 설정되지 않았거나 `"auto"`이고 최소 하나의 -승인자가 확인되면 기본 실행 승인을 자동으로 활성화합니다. Slack을 기본 승인 클라이언트로 명시적으로 비활성화하려면 `enabled: false`로 설정하세요. -승인자가 확인될 때 기본 승인을 강제로 켜려면 `enabled: true`로 설정하세요. +승인자가 확인되면 네이티브 exec 승인을 자동 활성화합니다. Slack을 네이티브 승인 클라이언트로 명시적으로 비활성화하려면 `enabled: false`를 설정하세요. +승인자가 확인될 때 네이티브 승인을 강제로 켜려면 `enabled: true`를 설정하세요. -명시적인 Slack 실행 승인 구성 없이 기본 동작: +명시적인 Slack exec 승인 구성이 없는 기본 동작: ```json5 { @@ -645,8 +650,8 @@ Slack은 `enabled`가 설정되지 않았거나 `"auto"`이고 최소 하나의 } ``` -승인자를 재정의하거나 필터를 추가하거나 -origin-chat 전송을 사용하려는 경우에만 명시적인 Slack 기본 구성이 필요합니다: +승인자를 재정의하거나, 필터를 추가하거나, +origin-chat 전달을 선택하려는 경우에만 명시적인 Slack 네이티브 구성이 필요합니다: ```json5 { @@ -662,22 +667,23 @@ origin-chat 전송을 사용하려는 경우에만 명시적인 Slack 기본 구 } ``` -공유 `approvals.exec` 전달은 별개입니다. 실행 승인 프롬프트를 다른 채팅이나 명시적인 대역 외 대상으로도 -라우팅해야 할 때만 사용하세요. 공유 `approvals.plugin` 전달도 별개이며, Slack 기본 버튼은 해당 요청이 이미 -Slack에 도착한 경우 플러그인 승인을 계속 확인할 수 있습니다. +공유 `approvals.exec` 전달은 별개입니다. exec 승인 프롬프트를 다른 채팅이나 명시적인 대역 외 대상에도 +라우팅해야 할 때만 사용하세요. 공유 `approvals.plugin` 전달도 별개입니다. +Slack 네이티브 버튼은 해당 요청이 이미 Slack에 도착한 경우 +plugin 승인을 계속 해결할 수 있습니다. -동일 채팅의 `/approve`도 이미 명령을 지원하는 Slack 채널 및 DM에서 작동합니다. 전체 승인 전달 모델은 [실행 승인](/ko/tools/exec-approvals)을 참조하세요. +동일 채팅의 `/approve`는 이미 명령을 지원하는 Slack 채널 및 DM에서도 작동합니다. 전체 승인 전달 모델은 [Exec approvals](/ko/tools/exec-approvals)를 참조하세요. ## 이벤트 및 운영 동작 - 메시지 수정/삭제/스레드 브로드캐스트는 시스템 이벤트로 매핑됩니다. - 반응 추가/제거 이벤트는 시스템 이벤트로 매핑됩니다. -- 멤버 참가/이탈, 채널 생성/이름 변경, 핀 추가/제거 이벤트는 시스템 이벤트로 매핑됩니다. +- 멤버 참여/나감, 채널 생성/이름 변경, 핀 추가/제거 이벤트는 시스템 이벤트로 매핑됩니다. - `channel_id_changed`는 `configWrites`가 활성화된 경우 채널 구성 키를 마이그레이션할 수 있습니다. -- 채널 주제/목적 메타데이터는 신뢰할 수 없는 컨텍스트로 취급되며 라우팅 컨텍스트에 주입될 수 있습니다. -- 스레드 시작 메시지와 초기 스레드 기록 컨텍스트 시드는 해당하는 경우 구성된 발신자 허용 목록으로 필터링됩니다. -- 블록 작업 및 모달 상호작용은 풍부한 페이로드 필드가 있는 구조화된 `Slack interaction: ...` 시스템 이벤트를 생성합니다: - - 블록 작업: 선택된 값, 레이블, 피커 값, `workflow_*` 메타데이터 +- 채널 topic/purpose 메타데이터는 신뢰할 수 없는 컨텍스트로 처리되며 라우팅 컨텍스트에 주입될 수 있습니다. +- 스레드 시작자 및 초기 스레드 기록 컨텍스트 시딩은 해당되는 경우 구성된 발신자 허용 목록에 따라 필터링됩니다. +- 블록 작업 및 모달 상호작용은 풍부한 페이로드 필드가 포함된 구조화된 `Slack interaction: ...` 시스템 이벤트를 출력합니다: + - 블록 작업: 선택된 값, 레이블, picker 값, `workflow_*` 메타데이터 - 라우팅된 채널 메타데이터 및 폼 입력이 포함된 모달 `view_submission` 및 `view_closed` 이벤트 ## 구성 참조 포인터 @@ -686,23 +692,23 @@ Slack에 도착한 경우 플러그인 승인을 계속 확인할 수 있습니 - [구성 참조 - Slack](/ko/gateway/configuration-reference#slack) - 신호가 높은 Slack 필드: - - 모드/인증: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` + 핵심 Slack 필드: + - mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - DM 액세스: `dm.enabled`, `dmPolicy`, `allowFrom` (레거시: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - 호환성 토글: `dangerouslyAllowNameMatching` (비상용, 필요하지 않으면 꺼두세요) + - 호환성 토글: `dangerouslyAllowNameMatching` (긴급 우회용; 필요하지 않으면 끄기) - 채널 액세스: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - 스레딩/기록: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - - 전송: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming` + - 전달: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` - 운영/기능: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## 문제 해결 - 순서대로 확인하세요: + 다음을 순서대로 확인하세요: - `groupPolicy` - - 채널 허용 목록(`channels.slack.channels`) + - 채널 허용 목록 (`channels.slack.channels`) - `requireMention` - 채널별 `users` 허용 목록 @@ -717,10 +723,10 @@ openclaw doctor - 확인할 항목: + 다음을 확인하세요: - `channels.slack.dm.enabled` - - `channels.slack.dmPolicy`(또는 레거시 `channels.slack.dm.policy`) + - `channels.slack.dmPolicy` (또는 레거시 `channels.slack.dm.policy`) - 페어링 승인 / 허용 목록 항목 ```bash @@ -729,37 +735,37 @@ openclaw pairing list slack - - Slack 앱 설정에서 봇 + 앱 토큰 및 Socket Mode 활성화를 확인하세요. + + Slack 앱 설정에서 bot + app token 및 Socket Mode 활성화를 확인하세요. `openclaw channels status --probe --json`에 `botTokenStatus` 또는 - `appTokenStatus: "configured_unavailable"`이 표시되면 Slack 계정은 - 구성되어 있지만 현재 런타임이 SecretRef 기반 - 값을 확인할 수 없었다는 뜻입니다. + `appTokenStatus: "configured_unavailable"`가 표시되면 Slack 계정은 + 구성되어 있지만 현재 런타임이 SecretRef 기반 값을 + 확인할 수 없었다는 뜻입니다. - + 다음을 확인하세요: - signing secret - - webhook 경로 - - Slack Request URL(Events + Interactivity + Slash Commands) - - HTTP 계정별 고유한 `webhookPath` + - webhook path + - Slack Request URL (Events + Interactivity + Slash Commands) + - HTTP 계정별 고유 `webhookPath` - 계정 스냅샷에 `signingSecretStatus: "configured_unavailable"`이 - 나타나면 HTTP 계정은 구성되어 있지만 현재 런타임이 + 계정 스냅샷에 `signingSecretStatus: "configured_unavailable"`가 + 표시되면 HTTP 계정은 구성되어 있지만 현재 런타임이 SecretRef 기반 signing secret을 확인할 수 없었다는 뜻입니다. - - 의도한 구성이 다음 중 무엇인지 확인하세요: + + 의도한 방식이 다음 중 무엇인지 확인하세요: - - Slack에 일치하는 슬래시 명령이 등록된 기본 명령 모드(`channels.slack.commands.native: true`) - - 또는 단일 슬래시 명령 모드(`channels.slack.slashCommand.enabled: true`) + - Slack에 일치하는 슬래시 명령이 등록된 네이티브 명령 모드 (`channels.slack.commands.native: true`) + - 또는 단일 슬래시 명령 모드 (`channels.slack.slashCommand.enabled: true`) - 또한 `commands.useAccessGroups` 및 채널/사용자 허용 목록도 확인하세요. + 또한 `commands.useAccessGroups`와 채널/사용자 허용 목록도 확인하세요. diff --git a/docs/ko/concepts/memory.md b/docs/ko/concepts/memory.md index 935339fdc..902a0a4af 100644 --- a/docs/ko/concepts/memory.md +++ b/docs/ko/concepts/memory.md @@ -1,128 +1,130 @@ --- read_when: - - 메모리가 어떻게 작동하는지 이해하고 싶습니다 - - 어떤 메모리 파일을 작성해야 하는지 알고 싶습니다 -summary: OpenClaw가 세션 전반에 걸쳐 항목을 기억하는 방법 + - 메모리가 어떻게 작동하는지 이해하고 싶을 때 + - 어떤 메모리 파일을 작성해야 하는지 알고 싶을 때 +summary: OpenClaw가 세션 전반에 걸쳐 정보를 기억하는 방식 title: 메모리 개요 x-i18n: - generated_at: "2026-04-06T03:06:41Z" + generated_at: "2026-04-08T05:55:50Z" model: gpt-5.4 provider: openai - source_hash: d19d4fa9c4b3232b7a97f7a382311d2a375b562040de15e9fe4a0b1990b825e7 + source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af source_path: concepts/memory.md workflow: 15 --- # 메모리 개요 -OpenClaw는 에이전트의 -워크스페이스에 **일반 Markdown 파일**을 작성하여 항목을 기억합니다. 모델은 디스크에 저장된 것만 -"기억"합니다 -- 숨겨진 상태는 없습니다. +OpenClaw는 에이전트의 작업 공간에 **일반 Markdown 파일**을 작성하여 정보를 기억합니다. 모델은 디스크에 저장된 내용만 "기억"하며, 숨겨진 상태는 없습니다. ## 작동 방식 -에이전트에는 메모리 관련 파일이 세 개 있습니다: +에이전트에는 메모리와 관련된 파일이 세 가지 있습니다: -- **`MEMORY.md`** -- 장기 메모리. 지속되는 사실, 선호도, 그리고 - 결정 사항입니다. 모든 DM 세션 시작 시 로드됩니다. -- **`memory/YYYY-MM-DD.md`** -- 일일 노트. 누적되는 컨텍스트와 관찰 내용입니다. - 오늘과 어제의 노트가 자동으로 로드됩니다. -- **`DREAMS.md`** (실험적, 선택 사항) -- 사람이 검토할 수 있는 Dream Diary 및 dreaming 스윕 - 요약입니다. +- **`MEMORY.md`** -- 장기 메모리. 오래 유지되는 사실, 선호, 결정 사항입니다. 모든 DM 세션 시작 시 로드됩니다. +- **`memory/YYYY-MM-DD.md`** -- 일일 노트. 진행 중인 컨텍스트와 관찰 내용을 담습니다. 오늘과 어제의 노트는 자동으로 로드됩니다. +- **`DREAMS.md`** (실험적, 선택 사항) -- 사람이 검토할 수 있도록 만든 Dream Diary 및 dreaming sweep 요약입니다. -이 파일들은 에이전트 워크스페이스(기본값 `~/.openclaw/workspace`)에 있습니다. +이 파일들은 에이전트 작업 공간(기본값: `~/.openclaw/workspace`)에 있습니다. -에이전트가 무언가를 기억하길 원한다면 이렇게 요청하면 됩니다: "Remember that I -prefer TypeScript." 그러면 적절한 파일에 기록합니다. +에이전트가 무언가를 기억하길 원한다면 그냥 이렇게 요청하면 됩니다: "내가 TypeScript를 선호한다고 기억해." 그러면 적절한 파일에 기록합니다. ## 메모리 도구 에이전트에는 메모리를 다루기 위한 두 가지 도구가 있습니다: -- **`memory_search`** -- 원래 표현과 문구가 달라도 - 시맨틱 검색을 사용해 관련 노트를 찾습니다. -- **`memory_get`** -- 특정 메모리 파일이나 줄 범위를 읽습니다. +- **`memory_search`** -- 원문과 표현이 달라도 시맨틱 검색을 사용해 관련 노트를 찾습니다. +- **`memory_get`** -- 특정 메모리 파일 또는 줄 범위를 읽습니다. -두 도구 모두 활성 메모리 plugin이 제공합니다(기본값: `memory-core`). +두 도구 모두 활성 메모리 plugin(기본값: `memory-core`)에서 제공합니다. + +## Memory Wiki companion plugin + +지속 메모리가 단순한 원시 노트보다 관리되는 지식 베이스처럼 동작하길 원한다면, 번들된 `memory-wiki` plugin을 사용하세요. + +`memory-wiki`는 지속 지식을 다음 요소를 갖춘 위키 볼트로 컴파일합니다: + +- 결정론적 페이지 구조 +- 구조화된 주장과 근거 +- 모순 및 최신성 추적 +- 생성된 대시보드 +- 에이전트/런타임 소비자를 위한 컴파일된 다이제스트 +- `wiki_search`, `wiki_get`, `wiki_apply`, `wiki_lint` 같은 위키 네이티브 도구 + +이 plugin은 활성 메모리 plugin을 대체하지 않습니다. 활성 메모리 plugin은 여전히 회상, 승격, dreaming을 담당합니다. `memory-wiki`는 그 옆에 출처 정보가 풍부한 지식 계층을 추가합니다. + +자세한 내용은 [Memory Wiki](/ko/plugins/memory-wiki)를 참조하세요. ## 메모리 검색 -임베딩 provider가 구성되어 있으면 `memory_search`는 **하이브리드 -검색**을 사용합니다 -- 벡터 유사도(의미적 의미)와 키워드 일치 -(ID 및 코드 심볼 같은 정확한 용어)를 결합합니다. 지원되는 provider의 API 키만 있으면 -즉시 사용할 수 있습니다. +임베딩 provider가 구성되어 있으면 `memory_search`는 **하이브리드 검색**을 사용합니다. 즉, 벡터 유사도(의미적 의미)와 키워드 매칭(ID 및 코드 심볼 같은 정확한 용어)을 결합합니다. 지원되는 provider 중 하나의 API 키만 있으면 별도 설정 없이 바로 동작합니다. -OpenClaw는 사용 가능한 API 키를 바탕으로 임베딩 provider를 자동 감지합니다. OpenAI, Gemini, Voyage 또는 Mistral 키가 -구성되어 있으면 메모리 검색이 자동으로 활성화됩니다. +OpenClaw는 사용 가능한 API 키를 바탕으로 임베딩 provider를 자동 감지합니다. OpenAI, Gemini, Voyage 또는 Mistral 키가 구성되어 있으면 메모리 검색이 자동으로 활성화됩니다. -검색 동작 방식, 조정 옵션, provider 설정에 대한 자세한 내용은 -[메모리 검색](/ko/concepts/memory-search)을 참조하세요. +검색 작동 방식, 튜닝 옵션, provider 설정에 대한 자세한 내용은 [Memory Search](/ko/concepts/memory-search)를 참조하세요. ## 메모리 백엔드 - -SQLite 기반입니다. 키워드 검색, 벡터 유사도, 하이브리드 검색을 즉시 사용할 수 있습니다. -추가 종속성이 없습니다. + +SQLite 기반입니다. 키워드 검색, 벡터 유사도, 하이브리드 검색을 별도 설정 없이 사용할 수 있습니다. 추가 의존성이 필요하지 않습니다. -리랭킹, 쿼리 확장, 워크스페이스 외부 디렉터리 인덱싱 기능을 제공하는 로컬 우선 사이드카입니다. +재순위 지정, 쿼리 확장, 작업 공간 외부 디렉터리 인덱싱 기능을 갖춘 로컬 우선 사이드카입니다. -사용자 모델링, 시맨틱 검색, 멀티 에이전트 인식을 갖춘 AI 네이티브 크로스 세션 메모리입니다. -Plugin 설치가 필요합니다. +사용자 모델링, 시맨틱 검색, 멀티 에이전트 인식을 지원하는 AI 네이티브 교차 세션 메모리입니다. plugin 설치가 필요합니다. + + + +## 지식 위키 계층 + + + +주장, 대시보드, bridge mode, Obsidian 친화적 워크플로를 갖춘 출처 정보가 풍부한 위키 볼트로 지속 메모리를 컴파일합니다. ## 자동 메모리 플러시 -[compaction](/ko/concepts/compaction)이 대화를 요약하기 전에 OpenClaw는 -에이전트에게 중요한 컨텍스트를 메모리 파일에 저장하라고 상기시키는 -조용한 턴을 실행합니다. 이것은 기본적으로 켜져 있으므로 아무것도 구성할 필요가 없습니다. +[compaction](/ko/concepts/compaction)이 대화를 요약하기 전에 OpenClaw는 에이전트에게 중요한 컨텍스트를 메모리 파일에 저장하라고 상기시키는 무음 턴을 실행합니다. 이것은 기본적으로 활성화되어 있으므로 별도로 설정할 필요가 없습니다. -메모리 플러시는 compaction 중 컨텍스트 손실을 방지합니다. 대화에 중요한 사실이 있지만 아직 파일에 -기록되지 않았다면, 요약이 일어나기 전에 자동으로 저장됩니다. +메모리 플러시는 compaction 중 컨텍스트 손실을 방지합니다. 대화에 중요한 사실이 있지만 아직 파일에 기록되지 않았다면, 요약이 이루어지기 전에 자동으로 저장됩니다. -## dreaming (실험적) +## Dreaming (실험적) -dreaming은 메모리를 위한 선택적 백그라운드 통합 패스입니다. 단기 신호를 수집하고, -후보 항목의 점수를 매기며, 자격을 갖춘 항목만 장기 메모리(`MEMORY.md`)로 승격합니다. +Dreaming은 메모리를 위한 선택적 백그라운드 통합 패스입니다. 단기 신호를 수집하고, 후보를 점수화하며, 기준을 충족한 항목만 장기 메모리(`MEMORY.md`)로 승격합니다. -장기 메모리의 신호 품질을 높게 유지하도록 설계되었습니다: +장기 메모리의 신호 대 잡음비를 높게 유지하도록 설계되었습니다: - **옵트인**: 기본적으로 비활성화되어 있습니다. -- **예약 실행**: 활성화되면 `memory-core`가 전체 dreaming 스윕을 위한 - 반복 cron 작업 하나를 자동으로 관리합니다. -- **임곗값 적용**: 승격은 점수, 회상 빈도, 쿼리 - 다양성 게이트를 통과해야 합니다. -- **검토 가능**: 단계 요약과 다이어리 항목이 `DREAMS.md`에 기록되어 - 사람이 검토할 수 있습니다. +- **예약 실행**: 활성화되면 `memory-core`가 전체 dreaming sweep을 위한 반복 cron 작업 하나를 자동으로 관리합니다. +- **임곗값 기반**: 승격은 점수, 회상 빈도, 쿼리 다양성 게이트를 통과해야 합니다. +- **검토 가능**: 단계별 요약과 다이어리 항목이 사람이 검토할 수 있도록 `DREAMS.md`에 기록됩니다. -단계 동작, 점수화 신호, Dream Diary 세부 사항은 -[Dreaming (experimental)](/concepts/dreaming)을 참조하세요. +단계 동작, 점수화 신호, Dream Diary 세부 정보는 [Dreaming (experimental)](/ko/concepts/dreaming)을 참조하세요. ## CLI ```bash openclaw memory status # 인덱스 상태와 provider 확인 openclaw memory search "query" # 명령줄에서 검색 -openclaw memory index --force # 인덱스 재구축 +openclaw memory index --force # 인덱스 다시 빌드 ``` ## 추가 읽을거리 - [Builtin Memory Engine](/ko/concepts/memory-builtin) -- 기본 SQLite 백엔드 - [QMD Memory Engine](/ko/concepts/memory-qmd) -- 고급 로컬 우선 사이드카 -- [Honcho Memory](/ko/concepts/memory-honcho) -- AI 네이티브 크로스 세션 메모리 -- [Memory Search](/ko/concepts/memory-search) -- 검색 파이프라인, provider, 그리고 - 조정 -- [Dreaming (experimental)](/concepts/dreaming) -- 단기 회상에서 장기 메모리로의 - 백그라운드 승격 -- [Memory configuration reference](/ko/reference/memory-config) -- 모든 구성 설정 +- [Honcho Memory](/ko/concepts/memory-honcho) -- AI 네이티브 교차 세션 메모리 +- [Memory Wiki](/ko/plugins/memory-wiki) -- 컴파일된 지식 볼트 및 위키 네이티브 도구 +- [Memory Search](/ko/concepts/memory-search) -- 검색 파이프라인, provider, 튜닝 +- [Dreaming (experimental)](/ko/concepts/dreaming) -- 단기 회상에서 장기 메모리로의 백그라운드 승격 +- [Memory configuration reference](/ko/reference/memory-config) -- 모든 구성 옵션 - [Compaction](/ko/concepts/compaction) -- compaction이 메모리와 상호작용하는 방식 diff --git a/docs/ko/concepts/model-providers.md b/docs/ko/concepts/model-providers.md index 314ab7d02..46ca326f6 100644 --- a/docs/ko/concepts/model-providers.md +++ b/docs/ko/concepts/model-providers.md @@ -1,14 +1,14 @@ --- read_when: - - provider별 모델 설정 참고 자료가 필요합니다 - - 모델 provider용 예시 구성 또는 CLI 온보딩 명령이 필요합니다 -summary: 예시 구성과 CLI 흐름이 포함된 모델 provider 개요 + - provider별 모델 설정 참조가 필요합니다 + - 모델 provider용 예시 config 또는 CLI 온보딩 명령이 필요합니다 +summary: 예시 config와 CLI 흐름이 포함된 모델 provider 개요 title: 모델 provider x-i18n: - generated_at: "2026-04-08T02:15:37Z" + generated_at: "2026-04-08T05:57:21Z" model: gpt-5.4 provider: openai - source_hash: 26b36a2bc19a28a7ef39aa8e81a0050fea1d452ac4969122e5cdf8755e690258 + source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 source_path: concepts/model-providers.md workflow: 15 --- @@ -16,24 +16,25 @@ x-i18n: # 모델 provider 이 페이지는 **LLM/모델 provider**를 다룹니다(WhatsApp/Telegram 같은 채팅 채널은 아님). -모델 선택 규칙은 [/concepts/models](/ko/concepts/models)을 참조하세요. +모델 선택 규칙은 [/concepts/models](/ko/concepts/models)을 참고하세요. ## 빠른 규칙 - 모델 ref는 `provider/model`을 사용합니다(예: `opencode/claude-opus-4-6`). -- `agents.defaults.models`를 설정하면 허용 목록이 됩니다. +- `agents.defaults.models`를 설정하면 allowlist가 됩니다. - CLI 도우미: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- 대체 런타임 규칙, 쿨다운 프로브, 세션 오버라이드 지속성은 [/concepts/model-failover](/ko/concepts/model-failover)에 문서화되어 있습니다. +- 폴백 런타임 규칙, 쿨다운 프로브, 세션 override 지속성은 + [/concepts/model-failover](/ko/concepts/model-failover)에 설명되어 있습니다. - `models.providers.*.models[].contextWindow`는 네이티브 모델 메타데이터입니다. `models.providers.*.models[].contextTokens`는 유효 런타임 상한입니다. -- Provider plugin은 `registerProvider({ catalog })`를 통해 모델 카탈로그를 주입할 수 있습니다. +- Provider plugin은 `registerProvider({ catalog })`를 통해 모델 catalog를 주입할 수 있습니다. OpenClaw는 그 출력을 `models.providers`에 병합한 뒤 `models.json`을 기록합니다. -- Provider 매니페스트는 `providerAuthEnvVars`를 선언할 수 있으므로 일반적인 env 기반 - 인증 프로브가 plugin 런타임을 로드할 필요가 없습니다. 남아 있는 core env-var - 맵은 이제 non-plugin/core provider와 Anthropic API-key-first 온보딩 같은 일부 - 일반 우선순위 사례에만 사용됩니다. -- Provider plugin은 다음을 통해 provider 런타임 동작도 소유할 수 있습니다. +- Provider manifest는 `providerAuthEnvVars`를 선언할 수 있으므로 일반적인 env 기반 + 인증 프로브가 plugin 런타임을 로드할 필요가 없습니다. 남아 있는 코어 env-var + 맵은 이제 non-plugin/core provider와 Anthropic API-key-first 온보딩 같은 + 일부 일반 우선순위 사례에만 사용됩니다. +- Provider plugin은 다음을 통해 provider 런타임 동작도 직접 소유할 수 있습니다. `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -51,114 +52,198 @@ x-i18n: `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, 그리고 `onModelSelected`. -- 참고: provider 런타임 `capabilities`는 공유 러너 메타데이터입니다(provider - 계열, transcript/tooling 특이사항, transport/cache 힌트). 이것은 plugin이 - 무엇을 등록하는지 설명하는 [public capability model](/ko/plugins/architecture#public-capability-model)과는 - 다릅니다(텍스트 추론, 음성 등). +- 참고: provider 런타임 `capabilities`는 공유 runner 메타데이터입니다(provider + 계열, transcript/tooling 특이사항, transport/cache 힌트). 이것은 + plugin이 무엇을 등록하는지 설명하는 [공개 capability 모델](/ko/plugins/architecture#public-capability-model) + 과는 다릅니다(텍스트 추론, 음성 등). -## plugin 소유 provider 동작 +## Plugin 소유 provider 동작 -Provider plugin은 이제 대부분의 provider별 로직을 소유할 수 있으며, OpenClaw는 +Provider plugin은 이제 대부분의 provider별 로직을 소유할 수 있고, OpenClaw는 일반 추론 루프를 유지합니다. 일반적인 분리는 다음과 같습니다. -- `auth[].run` / `auth[].runNonInteractive`: provider는 `openclaw onboard`, `openclaw models auth`, 헤드리스 설정용 온보딩/로그인 흐름을 소유 -- `wizard.setup` / `wizard.modelPicker`: provider는 인증 선택 레이블, 레거시 별칭, 온보딩 허용 목록 힌트, 온보딩/모델 picker의 설정 항목을 소유 -- `catalog`: provider가 `models.providers`에 나타남 -- `normalizeModelId`: provider가 조회 또는 표준화 전에 레거시/preview 모델 id를 정규화 -- `normalizeTransport`: provider가 일반 모델 조립 전에 transport 계열 `api` / `baseUrl`을 정규화하며, OpenClaw는 먼저 일치한 provider를 확인한 뒤 실제로 transport를 변경하는 plugin이 나올 때까지 다른 hook 지원 provider plugin을 확인 -- `normalizeConfig`: provider가 런타임에서 사용하기 전에 `models.providers.` 구성을 정규화하며, OpenClaw는 먼저 일치한 provider를 확인한 뒤 실제로 구성을 변경하는 plugin이 나올 때까지 다른 hook 지원 provider plugin을 확인합니다. 어떤 provider hook도 구성을 재작성하지 않으면 번들된 Google 계열 도우미가 계속 지원되는 Google provider 항목을 정규화합니다. -- `applyNativeStreamingUsageCompat`: provider가 config provider용 엔드포인트 기반 네이티브 streaming-usage 호환 재작성을 적용 -- `resolveConfigApiKey`: provider가 전체 런타임 인증 로딩을 강제하지 않고 config provider용 env-marker 인증을 해석. `amazon-bedrock`도 여기서 내장 AWS env-marker 해석기를 가지며, Bedrock 런타임 인증은 AWS SDK 기본 체인을 사용함 -- `resolveSyntheticAuth`: provider가 평문 시크릿을 저장하지 않고 local/self-hosted 또는 기타 config 기반 인증 가용성을 노출할 수 있음 -- `shouldDeferSyntheticProfileAuth`: provider가 저장된 synthetic 프로필 플레이스홀더를 env/config 기반 인증보다 낮은 우선순위로 표시할 수 있음 -- `resolveDynamicModel`: provider가 아직 로컬 정적 카탈로그에 없는 모델 id를 허용 -- `prepareDynamicModel`: provider가 동적 해석을 다시 시도하기 전에 메타데이터 새로 고침이 필요함 -- `normalizeResolvedModel`: provider가 transport 또는 base URL 재작성이 필요함 -- `contributeResolvedModelCompat`: provider가 다른 호환 transport를 통해 들어온 경우에도 해당 벤더 모델용 compat 플래그를 제공 -- `capabilities`: provider가 transcript/tooling/provider-family 특이사항을 게시 -- `normalizeToolSchemas`: provider가 내장 러너가 보기 전에 tool schema를 정리 -- `inspectToolSchemas`: provider가 정규화 후 transport별 schema 경고를 노출 -- `resolveReasoningOutputMode`: provider가 네이티브 또는 태그 기반 reasoning-output 계약을 선택 -- `prepareExtraParams`: provider가 모델별 요청 파라미터를 기본화 또는 정규화 -- `createStreamFn`: provider가 일반 스트림 경로를 완전한 커스텀 transport로 대체 -- `wrapStreamFn`: provider가 요청 헤더/본문/모델 compat 래퍼를 적용 -- `resolveTransportTurnState`: provider가 턴별 네이티브 transport 헤더 또는 메타데이터를 제공 -- `resolveWebSocketSessionPolicy`: provider가 네이티브 WebSocket 세션 헤더 또는 세션 쿨다운 정책을 제공 -- `createEmbeddingProvider`: provider plugin에 속해야 하는 경우 provider가 메모리 임베딩 동작을 소유하며 core 임베딩 스위치보드는 소유하지 않음 -- `formatApiKey`: provider가 저장된 인증 프로필을 transport가 기대하는 런타임 `apiKey` 문자열로 포맷 -- `refreshOAuth`: 공유 `pi-ai` 갱신기로 충분하지 않을 때 provider가 OAuth 갱신을 소유 -- `buildAuthDoctorHint`: OAuth 갱신 실패 시 provider가 복구 안내를 추가 -- `matchesContextOverflowError`: 일반 휴리스틱이 놓치는 provider별 context-window 초과 오류를 provider가 인식 -- `classifyFailoverReason`: provider가 provider별 원시 transport/API 오류를 속도 제한 또는 과부하 같은 failover 이유로 매핑 +- `auth[].run` / `auth[].runNonInteractive`: provider가 `openclaw onboard`, `openclaw models auth`, 헤드리스 설정을 위한 온보딩/로그인 + 흐름을 소유 +- `wizard.setup` / `wizard.modelPicker`: provider가 인증 선택 라벨, + 레거시 alias, 온보딩 allowlist 힌트, 온보딩/모델 picker의 설정 항목을 소유 +- `catalog`: provider가 `models.providers`에 표시됨 +- `normalizeModelId`: provider가 조회 또는 canonicalization 전에 + 레거시/preview 모델 id를 정규화 +- `normalizeTransport`: provider가 일반 모델 조립 전에 transport 계열 `api` / `baseUrl`을 + 정규화합니다. OpenClaw는 먼저 일치하는 provider를 확인한 다음, + transport를 실제로 변경할 때까지 다른 hook 가능 provider plugin도 확인합니다. +- `normalizeConfig`: provider가 런타임 사용 전에 `models.providers.` config를 + 정규화합니다. OpenClaw는 먼저 일치하는 provider를 확인한 다음, + config를 실제로 변경할 때까지 다른 hook 가능 provider plugin도 확인합니다. 어떤 + provider hook도 config를 다시 쓰지 않으면, 번들된 Google 계열 도우미가 계속해서 + 지원되는 Google provider 항목을 정규화합니다. +- `applyNativeStreamingUsageCompat`: provider가 config provider에 대해 + 엔드포인트 기반 네이티브 스트리밍 사용량 호환성 재작성을 적용 +- `resolveConfigApiKey`: provider가 config provider에 대해 전체 런타임 인증을 강제로 로드하지 않고 + env-marker 인증을 해결합니다. + `amazon-bedrock`도 Bedrock 런타임 인증이 + AWS SDK 기본 체인을 사용하더라도, 여기에서 내장 AWS env-marker resolver를 가집니다. +- `resolveSyntheticAuth`: provider가 평문 비밀을 저장하지 않고도 + 로컬/셀프호스트 또는 기타 config 기반 인증 가용성을 노출할 수 있음 +- `shouldDeferSyntheticProfileAuth`: provider가 저장된 synthetic profile + placeholder를 env/config 기반 인증보다 낮은 우선순위로 표시할 수 있음 +- `resolveDynamicModel`: provider가 로컬 정적 catalog에 아직 없는 모델 id를 + 허용 +- `prepareDynamicModel`: provider가 동적 해결을 다시 시도하기 전에 + 메타데이터 새로고침이 필요 +- `normalizeResolvedModel`: provider가 transport 또는 base URL 재작성이 필요 +- `contributeResolvedModelCompat`: provider가 다른 호환 transport를 통해 들어온 경우에도 + 해당 vendor 모델에 대한 compat 플래그를 제공 +- `capabilities`: provider가 transcript/tooling/provider 계열 특이사항을 게시 +- `normalizeToolSchemas`: provider가 내장 runner가 보기 전에 + tool schema를 정리 +- `inspectToolSchemas`: provider가 정규화 후 transport별 schema 경고를 표시 +- `resolveReasoningOutputMode`: provider가 네이티브 대 태그 기반 + reasoning-output 계약을 선택 +- `prepareExtraParams`: provider가 모델별 요청 param의 기본값을 적용하거나 정규화 +- `createStreamFn`: provider가 일반 stream 경로를 완전히 + 커스텀 transport로 대체 +- `wrapStreamFn`: provider가 요청 헤더/본문/모델 compat wrapper를 적용 +- `resolveTransportTurnState`: provider가 턴별 네이티브 transport + 헤더 또는 메타데이터를 제공 +- `resolveWebSocketSessionPolicy`: provider가 네이티브 WebSocket 세션 + 헤더 또는 세션 쿨다운 정책을 제공 +- `createEmbeddingProvider`: provider가 코어 embedding switchboard 대신 + provider plugin에 속하는 메모리 embedding 동작을 소유 +- `formatApiKey`: provider가 저장된 인증 profile을 transport가 기대하는 + 런타임 `apiKey` 문자열로 포맷 +- `refreshOAuth`: 공유 `pi-ai` + refresher로 충분하지 않을 때 provider가 OAuth 새로고침을 소유 +- `buildAuthDoctorHint`: OAuth 새로고침이 실패할 때 provider가 + 복구 안내를 추가 +- `matchesContextOverflowError`: provider가 일반 heuristic이 놓치는 + provider별 컨텍스트 창 초과 오류를 인식 +- `classifyFailoverReason`: provider가 provider별 원시 transport/API + 오류를 rate limit 또는 overload 같은 failover reason으로 매핑 - `isCacheTtlEligible`: provider가 어떤 업스트림 모델 id가 prompt-cache TTL을 지원하는지 결정 -- `buildMissingAuthMessage`: provider가 일반 인증 저장소 오류를 provider별 복구 힌트로 대체 -- `suppressBuiltInModel`: provider가 오래된 업스트림 행을 숨기고 직접 해석 실패 시 벤더 소유 오류를 반환할 수 있음 -- `augmentModelCatalog`: provider가 발견 및 구성 병합 후 synthetic/final 카탈로그 행을 추가 +- `buildMissingAuthMessage`: provider가 일반 인증 저장소 오류를 + provider별 복구 힌트로 대체 +- `suppressBuiltInModel`: provider가 오래된 업스트림 행을 숨기고 + 직접 해결 실패에 대해 vendor 소유 오류를 반환할 수 있음 +- `augmentModelCatalog`: provider가 발견 및 config 병합 후 + synthetic/final catalog 행을 추가 - `isBinaryThinking`: provider가 이진 on/off thinking UX를 소유 -- `supportsXHighThinking`: provider가 선택한 모델에 `xhigh`를 사용하도록 설정 +- `supportsXHighThinking`: provider가 선택한 모델에서 `xhigh`를 사용하도록 설정 - `resolveDefaultThinkingLevel`: provider가 모델 계열의 기본 `/think` 정책을 소유 -- `applyConfigDefaults`: provider가 인증 모드, env 또는 모델 계열을 기준으로 구성 구체화 중 provider별 전역 기본값을 적용 -- `isModernModelRef`: provider가 live/smoke 선호 모델 매칭을 소유 -- `prepareRuntimeAuth`: provider가 구성된 자격 증명을 짧은 수명의 런타임 토큰으로 변환 -- `resolveUsageAuth`: provider가 `/usage` 및 관련 상태/보고 표면용 사용량/할당량 자격 증명을 해석 -- `fetchUsageSnapshot`: provider가 사용량 엔드포인트 조회/파싱을 소유하고 core는 여전히 요약 셸과 포맷을 소유 -- `onModelSelected`: provider가 텔레메트리 또는 provider 소유 세션 기록 유지 같은 선택 후 부작용을 실행 +- `applyConfigDefaults`: provider가 인증 모드, env 또는 모델 계열에 따라 + config materialization 중 provider별 전역 기본값을 적용 +- `isModernModelRef`: provider가 라이브/스모크 선호 모델 매칭을 소유 +- `prepareRuntimeAuth`: provider가 구성된 자격 증명을 짧은 수명의 + 런타임 토큰으로 변환 +- `resolveUsageAuth`: provider가 `/usage` + 및 관련 상태/리포팅 화면을 위한 사용량/할당량 자격 증명을 해결 +- `fetchUsageSnapshot`: provider가 사용량 엔드포인트 fetch/parsing을 소유하고 + 코어는 여전히 요약 셸과 포맷팅을 소유 +- `onModelSelected`: provider가 텔레메트리 또는 provider 소유 세션 bookkeeping 같은 + 선택 후 부수 효과를 실행 -현재 번들된 예시는 다음과 같습니다. +현재 번들 예시: -- `anthropic`: Claude 4.6 전방 호환 fallback, 인증 복구 힌트, 사용량 엔드포인트 조회, cache-TTL/provider-family 메타데이터, 인증 인식 전역 구성 기본값 -- `amazon-bedrock`: Bedrock 전용 throttle/not-ready 오류에 대한 provider 소유 context-overflow 매칭 및 failover 이유 분류, 그리고 Anthropic 트래픽의 Claude 전용 replay-policy 가드를 위한 공유 `anthropic-by-model` 재생 계열 포함 -- `anthropic-vertex`: Anthropic-message 트래픽에 대한 Claude 전용 replay-policy 가드 -- `openrouter`: 패스스루 모델 id, 요청 래퍼, provider capability 힌트, 프록시 Gemini 트래픽의 Gemini thought-signature 정리, `openrouter-thinking` 스트림 계열을 통한 프록시 reasoning 주입, 라우팅 메타데이터 전달, cache-TTL 정책 -- `github-copilot`: 온보딩/디바이스 로그인, 전방 호환 모델 fallback, Claude-thinking transcript 힌트, 런타임 토큰 교환, 사용량 엔드포인트 조회 -- `openai`: GPT-5.4 전방 호환 fallback, 직접 OpenAI transport 정규화, Codex 인식 missing-auth 힌트, Spark 숨김, synthetic OpenAI/Codex 카탈로그 행, thinking/live-model 정책, usage-token 별칭 정규화(`input` / `output` 및 `prompt` / `completion` 계열), 네이티브 OpenAI/Codex 래퍼를 위한 공유 `openai-responses-defaults` 스트림 계열, provider-family 메타데이터, `gpt-image-1`용 번들 이미지 생성 provider 등록, `sora-2`용 번들 비디오 생성 provider 등록 -- `google` 및 `google-gemini-cli`: Gemini 3.1 전방 호환 fallback, 네이티브 Gemini 재생 검증, 부트스트랩 재생 정리, 태그 기반 reasoning-output 모드, 최신 모델 매칭, Gemini image-preview 모델용 번들 이미지 생성 provider 등록, Veo 모델용 번들 비디오 생성 provider 등록; Gemini CLI OAuth는 또한 사용량 표면용 인증 프로필 토큰 포맷, usage-token 파싱, 할당량 엔드포인트 조회를 소유 -- `moonshot`: 공유 transport, plugin 소유 thinking 페이로드 정규화 -- `kilocode`: 공유 transport, plugin 소유 요청 헤더, reasoning 페이로드 정규화, 프록시-Gemini thought-signature 정리, cache-TTL 정책 -- `zai`: GLM-5 전방 호환 fallback, `tool_stream` 기본값, cache-TTL 정책, binary-thinking/live-model 정책, 사용량 인증 + 할당량 조회; 알 수 없는 `glm-5*` id는 번들된 `glm-4.7` 템플릿에서 synthetic 생성 -- `xai`: 네이티브 Responses transport 정규화, Grok fast 변형용 `/fast` 별칭 재작성, 기본 `tool_stream`, xAI 전용 tool-schema / reasoning-payload 정리, `grok-imagine-video`용 번들 비디오 생성 provider 등록 +- `anthropic`: Claude 4.6 forward-compat 폴백, 인증 복구 힌트, 사용량 + 엔드포인트 fetch, cache-TTL/provider 계열 메타데이터, 인증 인식 전역 + config 기본값 +- `amazon-bedrock`: Bedrock별 throttle/not-ready 오류에 대한 provider 소유 + 컨텍스트 초과 매칭 및 failover + reason 분류, 그리고 Anthropic 트래픽에서 Claude 전용 replay-policy + 가드를 위한 공유 `anthropic-by-model` 재생 계열 +- `anthropic-vertex`: Anthropic-message + 트래픽에서 Claude 전용 replay-policy 가드 +- `openrouter`: pass-through 모델 id, 요청 wrapper, provider capability + 힌트, 프록시 Gemini 트래픽에서 Gemini thought-signature 정리, + `openrouter-thinking` stream 계열을 통한 프록시 reasoning 주입, + 라우팅 메타데이터 전달, cache-TTL 정책 +- `github-copilot`: 온보딩/디바이스 로그인, forward-compat 모델 폴백, + Claude-thinking transcript 힌트, 런타임 토큰 교환, 사용량 엔드포인트 + fetch +- `openai`: GPT-5.4 forward-compat 폴백, 직접 OpenAI transport + 정규화, Codex 인식 missing-auth 힌트, Spark 숨김, synthetic + OpenAI/Codex catalog 행, thinking/live-model 정책, usage-token alias + 정규화(`input` / `output` 및 `prompt` / `completion` 계열), 네이티브 OpenAI/Codex + wrapper를 위한 공유 `openai-responses-defaults` stream 계열, + provider 계열 메타데이터, `gpt-image-1`용 번들 이미지 생성 provider + 등록, `sora-2`용 번들 비디오 생성 provider + 등록 +- `google` 및 `google-gemini-cli`: Gemini 3.1 forward-compat 폴백, + 네이티브 Gemini replay 검증, bootstrap replay 정리, 태그 기반 + reasoning-output 모드, modern-model 매칭, Gemini image-preview 모델용 + 번들 이미지 생성 provider 등록, Veo 모델용 번들 + 비디오 생성 provider 등록; Gemini CLI OAuth는 또한 + 사용량 화면용 인증 profile 토큰 포맷팅, usage-token parsing, 할당량 엔드포인트 + fetch를 소유 +- `moonshot`: 공유 transport, plugin 소유 thinking payload 정규화 +- `kilocode`: 공유 transport, plugin 소유 요청 헤더, reasoning payload + 정규화, 프록시 Gemini thought-signature 정리, cache-TTL + 정책 +- `zai`: GLM-5 forward-compat 폴백, `tool_stream` 기본값, cache-TTL + 정책, binary-thinking/live-model 정책, 사용량 인증 + 할당량 fetch; + 알 수 없는 `glm-5*` id는 번들된 `glm-4.7` 템플릿에서 합성됨 +- `xai`: 네이티브 Responses transport 정규화, Grok fast variant용 + `/fast` alias 재작성, 기본 `tool_stream`, xAI별 tool-schema / + reasoning-payload 정리, `grok-imagine-video`용 번들 비디오 생성 provider + 등록 - `mistral`: plugin 소유 capability 메타데이터 -- `opencode` 및 `opencode-go`: plugin 소유 capability 메타데이터와 프록시-Gemini thought-signature 정리 -- `alibaba`: `alibaba/wan2.6-t2v` 같은 직접 Wan 모델 ref용 plugin 소유 비디오 생성 카탈로그 -- `byteplus`: plugin 소유 카탈로그와 Seedance text-to-video/image-to-video 모델용 번들 비디오 생성 provider 등록 -- `fal`: FLUX 이미지 모델용 호스팅된 타사 이미지 생성 provider 등록과 호스팅된 타사 비디오 모델용 번들 비디오 생성 provider 등록 +- `opencode` 및 `opencode-go`: plugin 소유 capability 메타데이터와 + 프록시 Gemini thought-signature 정리 +- `alibaba`: `alibaba/wan2.6-t2v` 같은 직접 Wan 모델 ref용 + plugin 소유 비디오 생성 catalog +- `byteplus`: plugin 소유 catalog와 Seedance 텍스트-비디오/이미지-비디오 모델용 + 번들 비디오 생성 provider 등록 +- `fal`: 호스팅된 서드파티용 번들 비디오 생성 provider 등록, + FLUX 이미지 모델용 이미지 생성 provider 등록, + 그리고 호스팅된 서드파티 비디오 모델용 번들 + 비디오 생성 provider 등록 - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, `volcengine`: - plugin 소유 카탈로그만 제공 -- `qwen`: 텍스트 모델용 plugin 소유 카탈로그와 멀티모달 표면용 공유 media-understanding 및 비디오 생성 provider 등록; Qwen 비디오 생성은 `wan2.6-t2v` 및 `wan2.7-r2v` 같은 번들 Wan 모델과 함께 표준 DashScope 비디오 엔드포인트를 사용 -- `runway`: `gen4.5` 같은 네이티브 Runway 작업 기반 모델용 plugin 소유 비디오 생성 provider 등록 -- `minimax`: plugin 소유 카탈로그, Hailuo 비디오 모델용 번들 비디오 생성 provider 등록, `image-01`용 번들 이미지 생성 provider 등록, 하이브리드 Anthropic/OpenAI replay-policy 선택, 사용량 인증/스냅샷 로직 -- `together`: plugin 소유 카탈로그와 Wan 비디오 모델용 번들 비디오 생성 provider 등록 -- `xiaomi`: plugin 소유 카탈로그와 사용량 인증/스냅샷 로직 + plugin 소유 catalog만 제공 +- `qwen`: 텍스트 모델용 plugin 소유 catalog와 멀티모달 화면용 + 공유 media-understanding 및 비디오 생성 provider 등록; + Qwen 비디오 생성은 `wan2.6-t2v` 및 `wan2.7-r2v` 같은 번들 Wan 모델과 함께 + Standard DashScope 비디오 엔드포인트를 사용 +- `runway`: `gen4.5` 같은 네이티브 Runway 태스크 기반 모델용 + plugin 소유 비디오 생성 provider 등록 +- `minimax`: plugin 소유 catalog, Hailuo 비디오 모델용 번들 비디오 생성 provider + 등록, `image-01`용 번들 이미지 생성 provider + 등록, 하이브리드 Anthropic/OpenAI replay-policy + 선택, 사용량 인증/스냅샷 로직 +- `together`: plugin 소유 catalog와 Wan 비디오 모델용 번들 비디오 생성 provider + 등록 +- `xiaomi`: plugin 소유 catalog와 사용량 인증/스냅샷 로직 번들된 `openai` plugin은 이제 `openai`와 `openai-codex` 두 provider id를 모두 소유합니다. -여기까지가 여전히 OpenClaw의 일반 transport에 맞는 provider입니다. 완전히 커스텀 요청 실행기가 필요한 provider는 별도의 더 깊은 확장 표면입니다. +여기까지는 여전히 OpenClaw의 일반 transport에 맞는 provider를 다룹니다. 완전히 +커스텀 요청 실행기가 필요한 provider는 별도의 더 깊은 확장 표면입니다. ## API 키 로테이션 - 선택된 provider에 대해 일반 provider 로테이션을 지원합니다. -- 여러 키를 다음을 통해 구성합니다. - - `OPENCLAW_LIVE__KEY`(단일 live override, 가장 높은 우선순위) - - `_API_KEYS`(쉼표 또는 세미콜론으로 구분된 목록) +- 여러 키를 다음으로 구성합니다: + - `OPENCLAW_LIVE__KEY`(단일 라이브 override, 최우선) + - `_API_KEYS`(쉼표 또는 세미콜론 목록) - `_API_KEY`(기본 키) - `_API_KEY_*`(번호가 붙은 목록, 예: `_API_KEY_1`) -- Google provider의 경우 `GOOGLE_API_KEY`도 fallback으로 포함됩니다. +- Google provider의 경우 `GOOGLE_API_KEY`도 폴백으로 포함됩니다. - 키 선택 순서는 우선순위를 유지하고 값을 중복 제거합니다. - 요청은 rate-limit 응답에서만 다음 키로 재시도됩니다(예: `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` 또는 주기적 usage-limit 메시지). -- rate-limit이 아닌 실패는 즉시 실패하며 키 로테이션을 시도하지 않습니다. + `workers_ai ... quota limit exceeded`, 또는 주기적인 usage-limit 메시지). +- rate-limit가 아닌 실패는 즉시 실패하며 키 로테이션을 시도하지 않습니다. - 모든 후보 키가 실패하면 마지막 시도의 최종 오류가 반환됩니다. -## 내장 provider (pi-ai 카탈로그) +## 내장 provider (pi-ai catalog) -OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아무** -`models.providers` 구성도 필요하지 않습니다. 인증만 설정하고 모델을 선택하면 됩니다. +OpenClaw는 pi‑ai catalog를 함께 제공합니다. 이 provider는 +`models.providers` config가 **필요하지 않습니다**. +인증만 설정하고 모델을 선택하면 됩니다. ### OpenAI @@ -167,17 +252,19 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - 선택적 로테이션: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, 그리고 `OPENCLAW_LIVE_OPENAI_KEY`(단일 override) - 예시 모델: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- 기본 transport는 `auto`입니다(WebSocket 우선, SSE fallback). -- 모델별로 `agents.defaults.models["openai/"].params.transport`를 통해 override할 수 있습니다(`"sse"`, `"websocket"`, 또는 `"auto"`). -- OpenAI Responses WebSocket 워밍업은 기본적으로 `params.openaiWsWarmup`(`true`/`false`)을 통해 활성화됩니다. -- OpenAI priority processing은 `agents.defaults.models["openai/"].params.serviceTier`를 통해 활성화할 수 있습니다. -- `/fast`와 `params.fastMode`는 직접 `openai/*` Responses 요청을 `api.openai.com`의 `service_tier=priority`로 매핑합니다. -- 공유 `/fast` 토글 대신 명시적 tier를 원하면 `params.serviceTier`를 사용하세요. +- 기본 transport는 `auto`입니다(WebSocket 우선, SSE 폴백) +- 모델별 override는 `agents.defaults.models["openai/"].params.transport`로 설정합니다(`"sse"`, `"websocket"`, 또는 `"auto"`) +- OpenAI Responses WebSocket 워밍업은 기본적으로 `params.openaiWsWarmup`으로 활성화됩니다(`true`/`false`) +- OpenAI priority processing은 `agents.defaults.models["openai/"].params.serviceTier`로 활성화할 수 있습니다 +- `/fast`와 `params.fastMode`는 직접 `openai/*` Responses 요청을 `api.openai.com`의 `service_tier=priority`로 매핑합니다 +- 공유 `/fast` 토글 대신 명시적 tier를 원하면 `params.serviceTier`를 사용하세요 - 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, - `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 `api.openai.com`으로 가는 네이티브 OpenAI 트래픽에만 적용됩니다. -- 네이티브 OpenAI 경로는 또한 Responses `store`, prompt-cache 힌트, - OpenAI reasoning-compat 페이로드 형태도 유지하며, 프록시 경로는 그렇지 않습니다. -- `openai/gpt-5.3-codex-spark`는 live OpenAI API가 이를 거부하므로 OpenClaw에서 의도적으로 숨겨집니다. Spark는 Codex 전용으로 취급됩니다. + `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 + `api.openai.com`으로 가는 네이티브 OpenAI 트래픽에만 적용됩니다 +- 네이티브 OpenAI 경로는 Responses `store`, prompt-cache 힌트, + OpenAI reasoning-compat payload shaping도 유지하지만, + 프록시 경로는 그렇지 않습니다 +- `openai/gpt-5.3-codex-spark`는 라이브 OpenAI API가 이를 거부하기 때문에 OpenClaw에서 의도적으로 숨겨집니다. Spark는 Codex 전용으로 처리됩니다 ```json5 { @@ -192,9 +279,9 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - 선택적 로테이션: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, 그리고 `OPENCLAW_LIVE_ANTHROPIC_KEY`(단일 override) - 예시 모델: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- 직접 공개 Anthropic 요청은 공유 `/fast` 토글과 `params.fastMode`도 지원하며, `api.anthropic.com`으로 전송되는 API-key 및 OAuth 인증 트래픽을 포함합니다. OpenClaw는 이를 Anthropic `service_tier`(`auto` 대 `standard_only`)로 매핑합니다. -- Anthropic 참고: Anthropic 직원들이 OpenClaw 방식의 Claude CLI 사용이 다시 허용된다고 알려왔기 때문에, Anthropic이 새 정책을 게시하지 않는 한 OpenClaw는 Claude CLI 재사용과 `claude -p` 사용을 이 통합에 대해 허용된 것으로 취급합니다. -- Anthropic setup-token은 여전히 지원되는 OpenClaw 토큰 경로로 남아 있지만, 이제 OpenClaw는 가능할 때 Claude CLI 재사용과 `claude -p`를 우선합니다. +- 직접 공개 Anthropic 요청은 공유 `/fast` 토글과 `params.fastMode`도 지원하며, 여기에는 `api.anthropic.com`으로 전송되는 API-key 및 OAuth 인증 트래픽이 포함됩니다. OpenClaw는 이를 Anthropic `service_tier`(`auto` 대 `standard_only`)로 매핑합니다 +- Anthropic 참고: Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔으므로, Anthropic이 새 정책을 게시하지 않는 한 OpenClaw는 이 통합에 대해 Claude CLI 재사용과 `claude -p` 사용을 허용된 것으로 처리합니다. +- Anthropic setup-token은 여전히 지원되는 OpenClaw 토큰 경로로 제공되지만, OpenClaw는 이제 가능하면 Claude CLI 재사용과 `claude -p`를 우선합니다. ```json5 { @@ -208,16 +295,17 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - 인증: OAuth (ChatGPT) - 예시 모델: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` 또는 `openclaw models auth login --provider openai-codex` -- 기본 transport는 `auto`입니다(WebSocket 우선, SSE fallback). -- 모델별로 `agents.defaults.models["openai-codex/"].params.transport`를 통해 override할 수 있습니다(`"sse"`, `"websocket"`, 또는 `"auto"`). -- `params.serviceTier`도 네이티브 Codex Responses 요청(`chatgpt.com/backend-api`)에서 전달됩니다. +- 기본 transport는 `auto`입니다(WebSocket 우선, SSE 폴백) +- 모델별 override는 `agents.defaults.models["openai-codex/"].params.transport`로 설정합니다(`"sse"`, `"websocket"`, 또는 `"auto"`) +- `params.serviceTier`도 네이티브 Codex Responses 요청(`chatgpt.com/backend-api`)에서 전달됩니다 - 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 - `chatgpt.com/backend-api`로 가는 네이티브 Codex 트래픽에만 첨부됩니다. -- 직접 `openai/*`와 동일한 `/fast` 토글 및 `params.fastMode` 구성을 공유하며, OpenClaw는 이를 `service_tier=priority`로 매핑합니다. -- `openai-codex/gpt-5.3-codex-spark`는 Codex OAuth 카탈로그가 이를 노출할 때 계속 사용할 수 있습니다. 사용 권한에 따라 달라집니다. -- `openai-codex/gpt-5.4`는 네이티브 `contextWindow = 1050000`과 기본 런타임 `contextTokens = 272000`을 유지합니다. 런타임 상한은 `models.providers.openai-codex.models[].contextTokens`로 override하세요. -- 정책 참고: OpenAI Codex OAuth는 OpenClaw 같은 외부 도구/워크플로에 대해 명시적으로 지원됩니다. + `chatgpt.com/backend-api`로 가는 네이티브 Codex 트래픽에만 + 첨부됩니다 +- 직접 `openai/*`와 같은 `/fast` 토글 및 `params.fastMode` config를 공유하며, OpenClaw는 이를 `service_tier=priority`로 매핑합니다 +- `openai-codex/gpt-5.3-codex-spark`는 Codex OAuth catalog가 이를 노출할 때 계속 사용할 수 있습니다. entitlement에 따라 달라집니다 +- `openai-codex/gpt-5.4`는 네이티브 `contextWindow = 1050000`과 기본 런타임 `contextTokens = 272000`을 유지합니다. 런타임 상한은 `models.providers.openai-codex.models[].contextTokens`로 override하세요 +- 정책 참고: OpenAI Codex OAuth는 OpenClaw 같은 외부 도구/워크플로우에 대해 명시적으로 지원됩니다. ```json5 { @@ -261,40 +349,40 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - Provider: `google` - 인증: `GEMINI_API_KEY` -- 선택적 로테이션: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` fallback, 그리고 `OPENCLAW_LIVE_GEMINI_KEY`(단일 override) +- 선택적 로테이션: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` 폴백, 그리고 `OPENCLAW_LIVE_GEMINI_KEY`(단일 override) - 예시 모델: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` -- 호환성: `google/gemini-3.1-flash-preview`를 사용하는 레거시 OpenClaw 구성은 `google/gemini-3-flash-preview`로 정규화됩니다. +- 호환성: `google/gemini-3.1-flash-preview`를 사용하는 레거시 OpenClaw config는 `google/gemini-3-flash-preview`로 정규화됩니다 - CLI: `openclaw onboard --auth-choice gemini-api-key` - 직접 Gemini 실행은 `agents.defaults.models["google/"].params.cachedContent` - (또는 레거시 `cached_content`)도 허용하여 provider 네이티브 - `cachedContents/...` 핸들을 전달합니다. Gemini 캐시 적중은 OpenClaw `cacheRead`로 표시됩니다. + (또는 레거시 `cached_content`)도 허용하며, provider 네이티브 + `cachedContents/...` 핸들을 전달합니다. Gemini cache hit는 OpenClaw `cacheRead`로 표시됩니다 ### Google Vertex 및 Gemini CLI - Provider: `google-vertex`, `google-gemini-cli` -- 인증: Vertex는 gcloud ADC를 사용하고 Gemini CLI는 자체 OAuth 흐름을 사용합니다. -- 주의: OpenClaw의 Gemini CLI OAuth는 비공식 통합입니다. 일부 사용자는 타사 클라이언트를 사용한 뒤 Google 계정 제한을 보고했습니다. 진행하기로 한다면 Google 약관을 검토하고 중요하지 않은 계정을 사용하세요. +- 인증: Vertex는 gcloud ADC 사용, Gemini CLI는 자체 OAuth 흐름 사용 +- 주의: OpenClaw에서의 Gemini CLI OAuth는 비공식 통합입니다. 일부 사용자는 서드파티 클라이언트를 사용한 뒤 Google 계정 제한을 보고했습니다. 진행하기로 선택했다면 Google 약관을 검토하고 중요하지 않은 계정을 사용하세요. - Gemini CLI OAuth는 번들된 `google` plugin의 일부로 제공됩니다. - - 먼저 Gemini CLI를 설치합니다. + - 먼저 Gemini CLI를 설치하세요: - `brew install gemini-cli` - 또는 `npm install -g @google/gemini-cli` - 활성화: `openclaw plugins enable google` - 로그인: `openclaw models auth login --provider google-gemini-cli --set-default` - 기본 모델: `google-gemini-cli/gemini-3-flash-preview` - - 참고: `openclaw.json`에 client id 또는 secret을 붙여 넣지 **않습니다**. CLI 로그인 흐름은 - 토큰을 gateway host의 인증 프로필에 저장합니다. - - 로그인 후 요청이 실패하면 gateway host에 `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_CLOUD_PROJECT_ID`를 설정하세요. - - Gemini CLI JSON 응답은 `response`에서 파싱되며, 사용량은 `stats`로 fallback하고 - `stats.cached`는 OpenClaw `cacheRead`로 정규화됩니다. + - 참고: `openclaw.json`에 client id나 secret을 붙여 넣지 **않습니다**. CLI 로그인 흐름은 + 게이트웨이 호스트의 인증 profile에 토큰을 저장합니다. + - 로그인 후 요청이 실패하면 게이트웨이 호스트에서 `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_CLOUD_PROJECT_ID`를 설정하세요. + - Gemini CLI JSON 응답은 `response`에서 파싱되며, 사용량은 + `stats`로 폴백되고, `stats.cached`는 OpenClaw `cacheRead`로 정규화됩니다. ### Z.AI (GLM) - Provider: `zai` - 인증: `ZAI_API_KEY` -- 예시 모델: `zai/glm-5` +- 예시 모델: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - - 별칭: `z.ai/*` 및 `z-ai/*`는 `zai/*`로 정규화됩니다. - - `zai-api-key`는 일치하는 Z.AI 엔드포인트를 자동 감지하며, `zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`은 특정 표면을 강제로 사용합니다. + - Alias: `z.ai/*` 및 `z-ai/*`는 `zai/*`로 정규화됩니다 + - `zai-api-key`는 일치하는 Z.AI 엔드포인트를 자동 감지하며, `zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`은 특정 표면을 강제합니다 ### Vercel AI Gateway @@ -309,38 +397,39 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - 인증: `KILOCODE_API_KEY` - 예시 모델: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` -- 정적 fallback 카탈로그는 `kilocode/kilo/auto`를 포함하며, live - `https://api.kilo.ai/api/gateway/models` 조회는 런타임 - 카탈로그를 더 확장할 수 있습니다. -- `kilocode/kilo/auto` 뒤의 정확한 업스트림 라우팅은 OpenClaw에 하드코딩되지 않고 - Kilo Gateway가 소유합니다. +- 기본 URL: `https://api.kilo.ai/api/gateway/` +- 정적 폴백 catalog는 `kilocode/kilo/auto`를 포함하며, 라이브 + `https://api.kilo.ai/api/gateway/models` 발견을 통해 런타임 + catalog가 더 확장될 수 있습니다. +- `kilocode/kilo/auto` 뒤의 정확한 업스트림 라우팅은 OpenClaw에 + 하드코딩되어 있지 않고 Kilo Gateway가 소유합니다. -설정 세부 정보는 [/providers/kilocode](/ko/providers/kilocode)를 참조하세요. +설정 세부 사항은 [/providers/kilocode](/ko/providers/kilocode)를 참고하세요. ### 기타 번들 provider plugin - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - 예시 모델: `openrouter/auto` -- OpenClaw는 요청이 실제로 `openrouter.ai`를 대상으로 할 때만 OpenRouter 문서화 앱 attribution 헤더를 적용합니다. -- OpenRouter 전용 Anthropic `cache_control` 마커도 임의 프록시 URL이 아니라 - 검증된 OpenRouter 경로에서만 활성화됩니다. -- OpenRouter는 프록시 스타일 OpenAI 호환 경로를 유지하므로 네이티브 - OpenAI 전용 요청 형태 지정(`serviceTier`, Responses `store`, - prompt-cache 힌트, OpenAI reasoning-compat 페이로드)은 전달되지 않습니다. -- Gemini 기반 OpenRouter ref는 프록시-Gemini thought-signature 정리만 유지하며, - 네이티브 Gemini 재생 검증과 부트스트랩 재작성은 비활성 상태로 유지됩니다. +- OpenClaw는 요청이 실제로 `openrouter.ai`를 대상으로 할 때만 + OpenRouter 문서의 앱 attribution 헤더를 적용합니다 +- OpenRouter 전용 Anthropic `cache_control` 마커도 + 임의의 프록시 URL이 아니라 검증된 OpenRouter 경로에만 적용됩니다 +- OpenRouter는 프록시 스타일 OpenAI 호환 경로에 남아 있으므로 네이티브 + OpenAI 전용 요청 shaping(`serviceTier`, Responses `store`, + prompt-cache 힌트, OpenAI reasoning-compat payload)은 전달되지 않습니다 +- Gemini 기반 OpenRouter ref는 프록시 Gemini thought-signature 정리만 + 유지하며, 네이티브 Gemini replay 검증과 bootstrap 재작성은 비활성화됩니다 - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - 예시 모델: `kilocode/kilo/auto` -- Gemini 기반 Kilo ref는 동일한 프록시-Gemini thought-signature - 정리 경로를 유지하며, `kilocode/kilo/auto` 및 기타 프록시 reasoning 미지원 - 힌트는 프록시 reasoning 주입을 건너뜁니다. +- Gemini 기반 Kilo ref도 동일한 프록시 Gemini thought-signature + 정리 경로를 유지하며, `kilocode/kilo/auto` 및 다른 proxy-reasoning-unsupported + 힌트는 프록시 reasoning 주입을 건너뜁니다 - MiniMax: `minimax`(API 키) 및 `minimax-portal`(OAuth) -- 인증: `minimax`는 `MINIMAX_API_KEY`, `minimax-portal`은 `MINIMAX_OAUTH_TOKEN` 또는 `MINIMAX_API_KEY` +- 인증: `minimax`에는 `MINIMAX_API_KEY`; `minimax-portal`에는 `MINIMAX_OAUTH_TOKEN` 또는 `MINIMAX_API_KEY` - 예시 모델: `minimax/MiniMax-M2.7` 또는 `minimax-portal/MiniMax-M2.7` -- MiniMax 온보딩/API 키 설정은 명시적 M2.7 모델 정의를 - `input: ["text", "image"]`와 함께 기록합니다. 번들 provider 카탈로그는 - 해당 provider 구성이 구체화될 때까지 채팅 ref를 텍스트 전용으로 유지합니다. +- MiniMax 온보딩/API 키 설정은 명시적인 M2.7 모델 정의를 + `input: ["text", "image"]`와 함께 기록합니다. 번들된 provider catalog는 해당 provider config가 materialize될 때까지 + 채팅 ref를 텍스트 전용으로 유지합니다 - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - 예시 모델: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` 또는 `KIMICODE_API_KEY`) @@ -366,12 +455,12 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - 예시 모델: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - 네이티브 번들 xAI 요청은 xAI Responses 경로를 사용합니다. + - 네이티브 번들 xAI 요청은 xAI Responses 경로를 사용합니다 - `/fast` 또는 `params.fastMode: true`는 `grok-3`, `grok-3-mini`, - `grok-4`, `grok-4-0709`를 해당 `*-fast` 변형으로 재작성합니다. - - `tool_stream`은 기본적으로 활성화됩니다. - `agents.defaults.models["xai/"].params.tool_stream`를 `false`로 설정하면 - 비활성화됩니다. + `grok-4`, `grok-4-0709`를 해당 `*-fast` variant로 재작성합니다 + - `tool_stream`은 기본 활성화되어 있습니다. + 비활성화하려면 + `agents.defaults.models["xai/"].params.tool_stream`을 `false`로 설정하세요 - Mistral: `mistral` (`MISTRAL_API_KEY`) - 예시 모델: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` @@ -380,21 +469,22 @@ OpenClaw는 pi‑ai 카탈로그를 제공합니다. 이러한 provider는 **아 - Cerebras의 GLM 모델은 `zai-glm-4.7` 및 `zai-glm-4.6` id를 사용합니다. - OpenAI 호환 base URL: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) -- Hugging Face Inference 예시 모델: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. [Hugging Face (Inference)](/ko/providers/huggingface)를 참조하세요. +- Hugging Face Inference 예시 모델: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. [Hugging Face (Inference)](/ko/providers/huggingface)를 참고하세요. -## `models.providers`를 통한 provider (custom/base URL) +## `models.providers`를 통한 provider (커스텀/base URL) -`models.providers`(또는 `models.json`)를 사용해 **custom** provider 또는 -OpenAI/Anthropic 호환 프록시를 추가하세요. +**커스텀** provider 또는 +OpenAI/Anthropic 호환 프록시를 추가하려면 `models.providers`(또는 `models.json`)를 사용하세요. -아래의 번들 provider plugin 중 다수는 이미 기본 카탈로그를 게시합니다. +아래의 많은 번들 provider plugin은 이미 기본 catalog를 게시합니다. 기본 base URL, 헤더 또는 모델 목록을 override하려는 경우에만 -명시적 `models.providers.` 항목을 사용하세요. +명시적인 `models.providers.` 항목을 사용하세요. ### Moonshot AI (Kimi) -Moonshot은 번들 provider plugin으로 제공됩니다. 기본적으로 내장 provider를 사용하고, -base URL 또는 모델 메타데이터를 override해야 할 때만 명시적 `models.providers.moonshot` 항목을 추가하세요. +Moonshot은 번들 provider plugin으로 제공됩니다. 기본적으로 내장 provider를 +사용하고, base URL 또는 모델 메타데이터를 override해야 할 때만 +명시적인 `models.providers.moonshot` 항목을 추가하세요. - Provider: `moonshot` - 인증: `MOONSHOT_API_KEY` @@ -448,13 +538,13 @@ Kimi Coding은 Moonshot AI의 Anthropic 호환 엔드포인트를 사용합니 } ``` -레거시 `kimi/k2p5`는 여전히 호환성 모델 id로 허용됩니다. +레거시 `kimi/k2p5`는 호환성 모델 id로 계속 허용됩니다. ### Volcano Engine (Doubao) -Volcano Engine(화산엔진, 火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 액세스를 제공합니다. +Volcano Engine(화산엔진)은 중국에서 Doubao 및 기타 모델에 대한 액세스를 제공합니다. -- Provider: `volcengine`(코딩: `volcengine-plan`) +- Provider: `volcengine` (coding: `volcengine-plan`) - 인증: `VOLCANO_ENGINE_API_KEY` - 예시 모델: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -467,12 +557,13 @@ Volcano Engine(화산엔진, 火山引擎)은 중국에서 Doubao 및 기타 모 } ``` -온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 `volcengine/*` -카탈로그도 동시에 등록됩니다. +온보딩은 기본적으로 coding 표면을 사용하지만, 일반 `volcengine/*` +catalog도 동시에 등록됩니다. 온보딩/모델 구성 picker에서 Volcengine 인증 선택은 -`volcengine/*` 및 `volcengine-plan/*` 행을 모두 우선합니다. 아직 해당 모델이 로드되지 않았다면, -OpenClaw는 비어 있는 provider 범위 picker를 표시하는 대신 필터링되지 않은 카탈로그로 fallback합니다. +`volcengine/*`와 `volcengine-plan/*` 행을 모두 우선합니다. 해당 모델이 아직 로드되지 않았다면 +OpenClaw는 provider 범위 picker가 비어 보이지 않도록 +필터링되지 않은 catalog로 폴백합니다. 사용 가능한 모델: @@ -482,7 +573,7 @@ OpenClaw는 비어 있는 provider 범위 picker를 표시하는 대신 필터 - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) -코딩 모델(`volcengine-plan`): +Coding 모델(`volcengine-plan`): - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -490,11 +581,11 @@ OpenClaw는 비어 있는 provider 범위 picker를 표시하는 대신 필터 - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (국제) +### BytePlus (International) BytePlus ARK는 국제 사용자를 위해 Volcano Engine과 동일한 모델에 대한 액세스를 제공합니다. -- Provider: `byteplus`(코딩: `byteplus-plan`) +- Provider: `byteplus` (coding: `byteplus-plan`) - 인증: `BYTEPLUS_API_KEY` - 예시 모델: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -507,12 +598,13 @@ BytePlus ARK는 국제 사용자를 위해 Volcano Engine과 동일한 모델에 } ``` -온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 `byteplus/*` -카탈로그도 동시에 등록됩니다. +온보딩은 기본적으로 coding 표면을 사용하지만, 일반 `byteplus/*` +catalog도 동시에 등록됩니다. 온보딩/모델 구성 picker에서 BytePlus 인증 선택은 -`byteplus/*` 및 `byteplus-plan/*` 행을 모두 우선합니다. 아직 해당 모델이 로드되지 않았다면, -OpenClaw는 비어 있는 provider 범위 picker를 표시하는 대신 필터링되지 않은 카탈로그로 fallback합니다. +`byteplus/*`와 `byteplus-plan/*` 행을 모두 우선합니다. 해당 모델이 아직 로드되지 않았다면 +OpenClaw는 provider 범위 picker가 비어 보이지 않도록 +필터링되지 않은 catalog로 폴백합니다. 사용 가능한 모델: @@ -520,7 +612,7 @@ OpenClaw는 비어 있는 provider 범위 picker를 표시하는 대신 필터 - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) -코딩 모델(`byteplus-plan`): +Coding 모델(`byteplus-plan`): - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -558,22 +650,22 @@ Synthetic는 `synthetic` provider 뒤에서 Anthropic 호환 모델을 제공합 ### MiniMax -MiniMax는 custom 엔드포인트를 사용하므로 `models.providers`를 통해 구성합니다. +MiniMax는 커스텀 엔드포인트를 사용하므로 `models.providers`를 통해 구성합니다. -- MiniMax OAuth(글로벌): `--auth-choice minimax-global-oauth` -- MiniMax OAuth(CN): `--auth-choice minimax-cn-oauth` -- MiniMax API 키(글로벌): `--auth-choice minimax-global-api` -- MiniMax API 키(CN): `--auth-choice minimax-cn-api` -- 인증: `minimax`는 `MINIMAX_API_KEY`, `minimax-portal`은 `MINIMAX_OAUTH_TOKEN` 또는 - `MINIMAX_API_KEY` +- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` +- MiniMax API 키 (Global): `--auth-choice minimax-global-api` +- MiniMax API 키 (CN): `--auth-choice minimax-cn-api` +- 인증: `minimax`에는 `MINIMAX_API_KEY`, `minimax-portal`에는 + `MINIMAX_OAUTH_TOKEN` 또는 `MINIMAX_API_KEY` -설정 세부 정보, 모델 옵션, 구성 스니펫은 [/providers/minimax](/ko/providers/minimax)를 참조하세요. +설정 세부 사항, 모델 옵션, config snippet은 [/providers/minimax](/ko/providers/minimax)를 참고하세요. -MiniMax의 Anthropic 호환 스트리밍 경로에서 OpenClaw는 -명시적으로 설정하지 않으면 기본적으로 thinking을 비활성화하며, `/fast on`은 +MiniMax의 Anthropic 호환 스트리밍 경로에서는 OpenClaw가 thinking을 +명시적으로 설정하지 않는 한 기본적으로 비활성화하며, `/fast on`은 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 재작성합니다. -plugin 소유 capability 분리: +Plugin 소유 capability 분리: - 텍스트/채팅 기본값은 `minimax/MiniMax-M2.7`에 유지 - 이미지 생성은 `minimax/image-01` 또는 `minimax-portal/image-01` @@ -590,7 +682,7 @@ Ollama는 번들 provider plugin으로 제공되며 Ollama의 네이티브 API - 설치: [https://ollama.com/download](https://ollama.com/download) ```bash -# Ollama를 설치한 다음 모델을 가져옵니다: +# Ollama를 설치한 다음 모델을 pull하세요: ollama pull llama3.3 ``` @@ -602,27 +694,27 @@ ollama pull llama3.3 } ``` -`OLLAMA_API_KEY`로 opt-in하면 Ollama는 로컬의 `http://127.0.0.1:11434`에서 감지되며, -번들 provider plugin이 Ollama를 직접 -`openclaw onboard`와 모델 picker에 추가합니다. 온보딩, 클라우드/로컬 모드, custom 구성은 [/providers/ollama](/ko/providers/ollama)를 -참조하세요. +Ollama는 `OLLAMA_API_KEY`로 opt in하면 로컬 `http://127.0.0.1:11434`에서 +감지되며, 번들 provider plugin이 Ollama를 직접 +`openclaw onboard`와 모델 picker에 추가합니다. 온보딩, cloud/local 모드, +커스텀 구성은 [/providers/ollama](/ko/providers/ollama)를 참고하세요. ### vLLM -vLLM은 로컬/self-hosted OpenAI 호환 -서버용 번들 provider plugin으로 제공됩니다. +vLLM은 로컬/셀프호스트 OpenAI 호환 +서버를 위한 번들 provider plugin으로 제공됩니다. - Provider: `vllm` - 인증: 선택 사항(서버에 따라 다름) - 기본 base URL: `http://127.0.0.1:8000/v1` -로컬에서 auto-discovery를 opt-in하려면(서버가 인증을 강제하지 않는 경우 아무 값이나 가능): +로컬에서 자동 감지를 opt in하려면(서버가 인증을 강제하지 않으면 아무 값이나 가능): ```bash export VLLM_API_KEY="vllm-local" ``` -그런 다음 모델을 설정합니다(`/v1/models`가 반환하는 ID 중 하나로 교체): +그런 다음 모델을 설정하세요(`/v1/models`가 반환하는 ID 중 하나로 교체): ```json5 { @@ -632,25 +724,25 @@ export VLLM_API_KEY="vllm-local" } ``` -자세한 내용은 [/providers/vllm](/ko/providers/vllm)을 참조하세요. +자세한 내용은 [/providers/vllm](/ko/providers/vllm)을 참고하세요. ### SGLang -SGLang은 빠른 self-hosted -OpenAI 호환 서버용 번들 provider plugin으로 제공됩니다. +SGLang은 빠른 셀프호스트 +OpenAI 호환 서버를 위한 번들 provider plugin으로 제공됩니다. - Provider: `sglang` - 인증: 선택 사항(서버에 따라 다름) - 기본 base URL: `http://127.0.0.1:30000/v1` -로컬에서 auto-discovery를 opt-in하려면(서버가 인증을 강제하지 -않는 경우 아무 값이나 가능): +로컬에서 자동 감지를 opt in하려면(서버가 인증을 +강제하지 않으면 아무 값이나 가능): ```bash export SGLANG_API_KEY="sglang-local" ``` -그런 다음 모델을 설정합니다(`/v1/models`가 반환하는 ID 중 하나로 교체): +그런 다음 모델을 설정하세요(`/v1/models`가 반환하는 ID 중 하나로 교체): ```json5 { @@ -660,7 +752,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -자세한 내용은 [/providers/sglang](/ko/providers/sglang)을 참조하세요. +자세한 내용은 [/providers/sglang](/ko/providers/sglang)을 참고하세요. ### 로컬 프록시(LM Studio, vLLM, LiteLLM 등) @@ -699,21 +791,21 @@ export SGLANG_API_KEY="sglang-local" 참고: -- custom provider의 경우 `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`는 선택 사항입니다. - 생략하면 OpenClaw는 다음 기본값을 사용합니다. +- 커스텀 provider의 경우 `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`는 선택 사항입니다. + 생략하면 OpenClaw는 기본적으로 다음 값을 사용합니다: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 권장: 프록시/모델 한계에 맞는 명시적 값을 설정하세요. -- 네이티브가 아닌 엔드포인트의 `api: "openai-completions"`(호스트가 `api.openai.com`이 아닌 비어 있지 않은 `baseUrl`)에 대해서는, OpenClaw가 지원되지 않는 `developer` 역할로 인한 provider 400 오류를 피하기 위해 `compat.supportsDeveloperRole: false`를 강제합니다. -- 프록시 스타일 OpenAI 호환 경로는 네이티브 OpenAI 전용 요청 형태 지정도 건너뜁니다. - 즉 `service_tier` 없음, Responses `store` 없음, prompt-cache 힌트 없음, - OpenAI reasoning-compat 페이로드 형태 지정 없음, 숨겨진 OpenClaw attribution +- 권장: 프록시/모델 한도에 맞는 명시적 값을 설정하세요. +- 비네이티브 엔드포인트(`api.openai.com`이 아닌 호스트를 가진 비어 있지 않은 `baseUrl`)의 `api: "openai-completions"`에 대해 OpenClaw는 지원되지 않는 `developer` 역할로 인한 provider 400 오류를 피하기 위해 `compat.supportsDeveloperRole: false`를 강제로 적용합니다. +- 프록시 스타일 OpenAI 호환 경로도 네이티브 OpenAI 전용 요청 + shaping을 건너뜁니다: `service_tier` 없음, Responses `store` 없음, prompt-cache 힌트 없음, + OpenAI reasoning-compat payload shaping 없음, 숨겨진 OpenClaw attribution 헤더 없음. -- `baseUrl`이 비어 있거나 생략되면 OpenClaw는 기본 OpenAI 동작을 유지합니다(`api.openai.com`으로 해석됨). -- 안전을 위해 명시적 `compat.supportsDeveloperRole: true`도 네이티브가 아닌 `openai-completions` 엔드포인트에서는 여전히 override됩니다. +- `baseUrl`이 비어 있거나 생략되면 OpenClaw는 기본 OpenAI 동작을 유지합니다(`api.openai.com`으로 해결됨). +- 안전을 위해 비네이티브 `openai-completions` 엔드포인트에서는 명시적인 `compat.supportsDeveloperRole: true`도 여전히 override됩니다. ## CLI 예시 @@ -723,11 +815,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -전체 구성 예시는 [/gateway/configuration](/ko/gateway/configuration)도 참조하세요. +전체 구성 예시는 [/gateway/configuration](/ko/gateway/configuration)도 참고하세요. ## 관련 항목 -- [Models](/ko/concepts/models) — 모델 구성 및 별칭 -- [Model Failover](/ko/concepts/model-failover) — fallback 체인 및 재시도 동작 -- [Configuration Reference](/ko/gateway/configuration-reference#agent-defaults) — 모델 구성 키 +- [Models](/ko/concepts/models) — 모델 구성 및 alias +- [Model Failover](/ko/concepts/model-failover) — 폴백 체인과 재시도 동작 +- [Configuration Reference](/ko/gateway/configuration-reference#agent-defaults) — 모델 config 키 - [Providers](/ko/providers) — provider별 설정 가이드 diff --git a/docs/ko/concepts/qa-e2e-automation.md b/docs/ko/concepts/qa-e2e-automation.md index d2f8a2ab9..d56b6b8bf 100644 --- a/docs/ko/concepts/qa-e2e-automation.md +++ b/docs/ko/concepts/qa-e2e-automation.md @@ -1,15 +1,15 @@ --- read_when: - - qa-lab 또는 qa-channel을 확장할 때 - - 리포지토리 기반 QA 시나리오를 추가할 때 - - Gateway 대시보드를 중심으로 더 높은 현실성의 QA 자동화를 구축할 때 -summary: qa-lab, qa-channel, 시드된 시나리오, 프로토콜 보고서를 위한 비공개 QA 자동화 형태 + - qa-lab 또는 qa-channel 확장 시 + - 리포지토리 기반 QA 시나리오 추가 시 + - Gateway 대시보드 주변에 더 높은 현실성의 QA 자동화를 구축할 때 +summary: qa-lab, qa-channel, 시드된 시나리오, 프로토콜 보고서를 위한 비공개 QA 자동화 구조 title: QA E2E 자동화 x-i18n: - generated_at: "2026-04-08T02:14:01Z" + generated_at: "2026-04-08T05:55:40Z" model: gpt-5.4 provider: openai - source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27 + source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 source_path: concepts/qa-e2e-automation.md workflow: 15 --- @@ -23,15 +23,15 @@ x-i18n: - `extensions/qa-channel`: DM, 채널, 스레드, 반응, 수정, 삭제 표면을 갖춘 합성 메시지 채널 -- `extensions/qa-lab`: 트랜스크립트를 관찰하고, +- `extensions/qa-lab`: 대화 기록을 관찰하고, 인바운드 메시지를 주입하며, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스 - `qa/`: 시작 작업과 기준 QA 시나리오를 위한 리포지토리 기반 시드 자산 -현재 QA 운영자 흐름은 2개 패널로 구성된 QA 사이트입니다: +현재 QA 운영자 흐름은 2패널 QA 사이트입니다: - 왼쪽: 에이전트가 있는 Gateway 대시보드(Control UI) -- 오른쪽: Slack와 비슷한 트랜스크립트와 시나리오 계획을 보여주는 QA Lab +- 오른쪽: Slack과 유사한 대화 기록 및 시나리오 계획을 보여주는 QA Lab 다음으로 실행합니다: @@ -40,11 +40,11 @@ pnpm qa:lab:up ``` 이 명령은 QA 사이트를 빌드하고, Docker 기반 gateway 레인을 시작하며, 운영자 또는 자동화 루프가 에이전트에 QA -미션을 부여하고, 실제 채널 동작을 관찰하며, 무엇이 작동했고 무엇이 실패했으며 무엇이 -여전히 막혀 있는지 기록할 수 있는 QA Lab 페이지를 노출합니다. +미션을 전달하고, 실제 채널 동작을 관찰하며, 무엇이 성공했고 실패했으며 +무엇이 계속 막혀 있었는지 기록할 수 있는 QA Lab 페이지를 노출합니다. 매번 Docker 이미지를 다시 빌드하지 않고 더 빠르게 QA Lab UI를 반복 개발하려면, -바인드 마운트된 QA Lab 번들과 함께 스택을 시작하세요: +바인드 마운트된 QA Lab 번들로 스택을 시작하세요: ```bash pnpm openclaw qa docker-build-image @@ -53,18 +53,19 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast`는 Docker 서비스를 사전 빌드된 이미지로 유지하고 +`qa:lab:up:fast`는 사전 빌드된 이미지에서 Docker 서비스를 유지하고 `extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 바인드 마운트합니다. `qa:lab:watch`는 -변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 변경되면 브라우저가 자동으로 다시 로드됩니다. +변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 바뀌면 브라우저가 자동으로 다시 로드됩니다. ## 리포지토리 기반 시드 시드 자산은 `qa/`에 있습니다: -- `qa/scenarios.md` +- `qa/scenarios/index.md` +- `qa/scenarios/*.md` -이 항목들은 QA 계획이 사람과 -에이전트 모두에게 보이도록 의도적으로 git에 포함되어 있습니다. 기준 목록은 다음을 포괄할 만큼 충분히 넓어야 합니다: +이들은 QA 계획이 사람과 +에이전트 모두에게 보이도록 의도적으로 git에 포함됩니다. 기준 목록은 다음을 포괄할 만큼 충분히 넓게 유지되어야 합니다: - DM 및 채널 채팅 - 스레드 동작 @@ -74,12 +75,12 @@ pnpm qa:lab:watch - 모델 전환 - 서브에이전트 핸드오프 - 리포지토리 읽기 및 문서 읽기 -- Lobster Invaders와 같은 작은 빌드 작업 하나 +- Lobster Invaders 같은 작은 빌드 작업 하나 ## 보고 `qa-lab`은 관찰된 버스 타임라인에서 Markdown 프로토콜 보고서를 내보냅니다. -보고서는 다음 질문에 답해야 합니다: +이 보고서는 다음에 답해야 합니다: - 무엇이 작동했는가 - 무엇이 실패했는가 @@ -88,6 +89,6 @@ pnpm qa:lab:watch ## 관련 문서 -- [테스팅](/ko/help/testing) +- [테스트](/ko/help/testing) - [QA 채널](/ko/channels/qa-channel) - [대시보드](/web/dashboard) diff --git a/docs/ko/concepts/streaming.md b/docs/ko/concepts/streaming.md index 862e94f1c..36516195f 100644 --- a/docs/ko/concepts/streaming.md +++ b/docs/ko/concepts/streaming.md @@ -1,31 +1,31 @@ --- read_when: - - 채널에서 스트리밍 또는 청킹이 어떻게 동작하는지 설명할 때 + - 채널에서 스트리밍 또는 청킹이 작동하는 방식을 설명할 때 - 블록 스트리밍 또는 채널 청킹 동작을 변경할 때 - - 중복/조기 블록 답장 또는 채널 미리보기 스트리밍을 디버깅할 때 + - 중복되거나 이른 블록 답장 또는 채널 미리보기 스트리밍을 디버깅할 때 summary: 스트리밍 + 청킹 동작(블록 답장, 채널 미리보기 스트리밍, 모드 매핑) -title: 스트리밍 및 청킹 +title: 스트리밍과 청킹 x-i18n: - generated_at: "2026-04-05T12:41:12Z" + generated_at: "2026-04-08T05:55:57Z" model: gpt-5.4 provider: openai - source_hash: 44b0d08c7eafcb32030ef7c8d5719c2ea2d34e4bac5fdad8cc8b3f4e9e9fad97 + source_hash: a8e847bb7da890818cd79dec7777f6ae488e6d6c0468e948e56b6b6c598e0000 source_path: concepts/streaming.md workflow: 15 --- # 스트리밍 + 청킹 -OpenClaw에는 서로 분리된 두 개의 스트리밍 계층이 있습니다: +OpenClaw에는 서로 분리된 두 가지 스트리밍 계층이 있습니다. -- **블록 스트리밍(채널):** assistant가 작성하는 동안 완료된 **블록**을 전송합니다. 이는 일반 채널 메시지이며(토큰 델타 아님). -- **미리보기 스트리밍(Telegram/Discord/Slack):** 생성 중 임시 **미리보기 메시지**를 업데이트합니다. +- **블록 스트리밍(채널):** 어시스턴트가 작성하는 동안 완료된 **블록**을 내보냅니다. 이는 일반 채널 메시지이며(토큰 델타가 아님)입니다. +- **미리보기 스트리밍(Telegram/Discord/Slack):** 생성 중에 임시 **미리보기 메시지**를 업데이트합니다. -현재 채널 메시지에는 **진정한 토큰 델타 스트리밍이 없습니다**. 미리보기 스트리밍은 메시지 기반입니다(전송 + 편집/추가). +현재 채널 메시지에는 **진정한 토큰 델타 스트리밍이 없습니다**. 미리보기 스트리밍은 메시지 기반입니다(`send` + `edits/appends`). ## 블록 스트리밍(채널 메시지) -블록 스트리밍은 assistant 출력이 준비되는 대로 거친 청크 단위로 전송합니다. +블록 스트리밍은 어시스턴트 출력이 준비되는 대로 비교적 큰 청크로 전송합니다. ``` Model output @@ -39,77 +39,77 @@ Model output 범례: -- `text_delta/events`: 모델 스트림 이벤트(비스트리밍 모델에서는 드물 수 있음). +- `text_delta/events`: 모델 스트림 이벤트(스트리밍하지 않는 모델의 경우 드물 수 있음). - `chunker`: 최소/최대 경계 + 분할 선호도를 적용하는 `EmbeddedBlockChunker`. - `channel send`: 실제 발신 메시지(블록 답장). **제어 항목:** -- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"`(기본값 꺼짐). +- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (기본값: off). - 채널 재정의: 채널별로 `"on"`/`"off"`를 강제하는 `*.blockStreaming`(및 계정별 변형). - `agents.defaults.blockStreamingBreak`: `"text_end"` 또는 `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. -- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }`(전송 전에 스트리밍된 블록 병합). +- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (전송 전에 스트리밍된 블록 병합). - 채널 하드 상한: `*.textChunkLimit`(예: `channels.whatsapp.textChunkLimit`). -- 채널 청크 모드: `*.chunkMode`(`length`가 기본값, `newline`은 길이 기준 청킹 전에 빈 줄(문단 경계)에서 분할). -- Discord 소프트 상한: `channels.discord.maxLinesPerMessage`(기본값 17)는 UI 잘림을 방지하기 위해 긴 답장을 분할합니다. +- 채널 청크 모드: `*.chunkMode`(`length`가 기본값, `newline`은 길이 기반 청킹 전에 빈 줄(문단 경계)에서 분할). +- Discord 소프트 상한: `channels.discord.maxLinesPerMessage`(기본값 17)는 UI 잘림을 피하기 위해 긴 답장을 분할합니다. **경계 의미:** -- `text_end`: chunker가 방출하는 즉시 스트림 블록을 전송하고 각 `text_end`에서 flush합니다. -- `message_end`: assistant 메시지가 끝날 때까지 기다린 뒤 버퍼된 출력을 flush합니다. +- `text_end`: chunker가 내보내는 즉시 블록을 스트리밍하고, 각 `text_end`에서 flush합니다. +- `message_end`: 어시스턴트 메시지가 끝날 때까지 기다린 뒤, 버퍼링된 출력을 flush합니다. -`message_end`도 버퍼된 텍스트가 `maxChars`를 초과하면 여전히 chunker를 사용하므로 마지막에 여러 청크를 방출할 수 있습니다. +`message_end`도 버퍼링된 텍스트가 `maxChars`를 초과하면 여전히 chunker를 사용하므로, 끝에서 여러 청크를 내보낼 수 있습니다. ## 청킹 알고리즘(하한/상한) -블록 청킹은 `EmbeddedBlockChunker`로 구현됩니다: +블록 청킹은 `EmbeddedBlockChunker`에서 구현됩니다. -- **하한:** 버퍼가 `minChars` 이상이 되기 전에는 방출하지 않습니다(강제되는 경우 제외). -- **상한:** 가능하면 `maxChars` 전에 분할합니다. 강제되는 경우 `maxChars`에서 분할합니다. +- **하한:** 버퍼가 `minChars` 이상이 될 때까지 내보내지 않습니다(강제되는 경우 제외). +- **상한:** `maxChars` 이전에서 분할을 우선 시도하며, 강제되면 `maxChars`에서 분할합니다. - **분할 선호도:** `paragraph` → `newline` → `sentence` → `whitespace` → 강제 분할. -- **코드 펜스:** 펜스 내부에서는 절대 분할하지 않습니다. `maxChars`에서 강제 분할될 때는 Markdown 유효성을 유지하기 위해 펜스를 닫고 다시 엽니다. +- **코드 펜스:** 펜스 내부에서는 절대 분할하지 않으며, `maxChars`에서 강제 분할할 때는 Markdown 유효성을 유지하기 위해 펜스를 닫았다가 다시 엽니다. -`maxChars`는 채널 `textChunkLimit`로 제한되므로 채널별 상한을 초과할 수 없습니다. +`maxChars`는 채널 `textChunkLimit`에 맞춰 제한되므로, 채널별 상한을 초과할 수 없습니다. -## 병합(coalescing, 스트리밍된 블록 병합) +## 코얼레싱(스트리밍된 블록 병합) -블록 스트리밍이 활성화되면 OpenClaw는 **연속된 블록 청크를 병합한 후** -전송할 수 있습니다. 이렇게 하면 진행형 출력을 유지하면서도 +블록 스트리밍이 활성화되면, OpenClaw는 연속된 블록 청크를 **병합** +한 뒤 전송할 수 있습니다. 이렇게 하면 점진적 출력을 유지하면서도 “한 줄짜리 스팸”을 줄일 수 있습니다. -- 병합은 flush 전에 **유휴 간격**(`idleMs`)을 기다립니다. +- 코얼레싱은 flush 전에 **유휴 간격**(`idleMs`)을 기다립니다. - 버퍼는 `maxChars`로 제한되며, 이를 초과하면 flush됩니다. - `minChars`는 충분한 텍스트가 누적될 때까지 작은 조각이 전송되지 않도록 합니다 - (최종 flush는 항상 남은 텍스트를 전송). -- 결합자는 `blockStreamingChunk.breakPreference`에서 파생됩니다 + (최종 flush는 항상 남은 텍스트를 전송합니다). +- 연결자는 `blockStreamingChunk.breakPreference`에서 파생됩니다 (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → 공백). -- `*.blockStreamingCoalesce`를 통한 채널 재정의도 사용할 수 있습니다(계정별 config 포함). -- 재정의되지 않은 경우 Signal/Slack/Discord의 기본 coalesce `minChars`는 1500으로 올라갑니다. +- `*.blockStreamingCoalesce`를 통한 채널 재정의가 가능합니다(계정별 구성 포함). +- 재정의하지 않으면 Signal/Slack/Discord의 기본 coalesce `minChars`는 1500으로 상향 조정됩니다. ## 블록 간 사람 같은 페이싱 -블록 스트리밍이 활성화되면 블록 답장 사이에 **무작위 일시 정지**를 추가할 수 있습니다 -(첫 번째 블록 이후). 이렇게 하면 여러 버블로 나뉜 응답이 -더 자연스럽게 느껴집니다. +블록 스트리밍이 활성화되면, 블록 답장 사이에 **무작위 지연**을 추가할 수 +있습니다(첫 번째 블록 이후). 이렇게 하면 여러 말풍선으로 된 응답이 더 +자연스럽게 느껴집니다. -- config: `agents.defaults.humanDelay`(에이전트별 재정의: `agents.list[].humanDelay`). +- 설정: `agents.defaults.humanDelay`(에이전트별 재정의: `agents.list[].humanDelay`). - 모드: `off`(기본값), `natural`(800–2500ms), `custom`(`minMs`/`maxMs`). - **블록 답장**에만 적용되며, 최종 답장이나 도구 요약에는 적용되지 않습니다. -## "청크로 스트리밍할지 전부 보낼지" +## "청크 스트리밍 또는 전체 전송" -이는 다음에 매핑됩니다: +이는 다음에 매핑됩니다. -- **청크 스트리밍:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`(작성하면서 전송). Telegram이 아닌 채널은 `*.blockStreaming: true`도 필요합니다. -- **마지막에 전부 스트리밍:** `blockStreamingBreak: "message_end"`(한 번 flush, 매우 길면 여러 청크 가능). -- **블록 스트리밍 없음:** `blockStreamingDefault: "off"`(최종 답장만 전송). +- **청크 스트리밍:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"`(생성하면서 내보냄). Telegram이 아닌 채널은 `*.blockStreaming: true`도 필요합니다. +- **끝에서 전체 스트리밍:** `blockStreamingBreak: "message_end"`(한 번 flush, 매우 길면 여러 청크일 수 있음). +- **블록 스트리밍 없음:** `blockStreamingDefault: "off"`(최종 답장만). -**채널 참고:** 블록 스트리밍은 `*.blockStreaming`이 -명시적으로 `true`로 설정되지 않으면 **비활성화**됩니다. 채널은 블록 답장 없이도 -실시간 미리보기(`channels..streaming`)를 스트리밍할 수 있습니다. +**채널 참고:** 블록 스트리밍은 `*.blockStreaming`이 명시적으로 `true`로 +설정되지 않으면 **비활성화** 상태입니다. 채널은 블록 답장 없이도 +라이브 미리보기(`channels..streaming`)를 스트리밍할 수 있습니다. -config 위치 참고: `blockStreaming*` 기본값은 루트 config가 아니라 +설정 위치 참고: `blockStreaming*` 기본값은 루트 설정이 아니라 `agents.defaults` 아래에 있습니다. ## 미리보기 스트리밍 모드 @@ -120,12 +120,12 @@ config 위치 참고: `blockStreaming*` 기본값은 루트 config가 아니라 - `off`: 미리보기 스트리밍 비활성화. - `partial`: 최신 텍스트로 교체되는 단일 미리보기. -- `block`: 청크/추가 단계로 업데이트되는 미리보기. -- `progress`: 생성 중 진행/상태 미리보기, 완료 시 최종 답변. +- `block`: 청크/추가 단계로 미리보기를 업데이트. +- `progress`: 생성 중 진행률/상태 미리보기를 표시하고, 완료 시 최종 답변 전송. ### 채널 매핑 -| 채널 | `off` | `partial` | `block` | `progress` | +| Channel | `off` | `partial` | `block` | `progress` | | -------- | ----- | --------- | ------- | ----------------- | | Telegram | ✅ | ✅ | ✅ | `partial`로 매핑 | | Discord | ✅ | ✅ | ✅ | `partial`로 매핑 | @@ -133,13 +133,14 @@ config 위치 참고: `blockStreaming*` 기본값은 루트 config가 아니라 Slack 전용: -- `channels.slack.nativeStreaming`은 `streaming=partial`일 때 Slack 기본 스트리밍 API 호출을 전환합니다(기본값: `true`). +- `channels.slack.streaming.nativeTransport`는 `channels.slack.streaming.mode="partial"`일 때 Slack 기본 스트리밍 API 호출 사용 여부를 전환합니다(기본값: `true`). +- Slack 기본 스트리밍과 Slack 어시스턴트 스레드 상태는 답장 스레드 대상이 있어야 합니다. 최상위 DM에서는 해당 스레드 스타일 미리보기가 표시되지 않습니다. 레거시 키 마이그레이션: -- Telegram: `streamMode` + 불리언 `streaming`은 자동으로 `streaming` enum으로 마이그레이션됩니다. -- Discord: `streamMode` + 불리언 `streaming`은 자동으로 `streaming` enum으로 마이그레이션됩니다. -- Slack: `streamMode`는 자동으로 `streaming` enum으로 마이그레이션되며, 불리언 `streaming`은 자동으로 `nativeStreaming`으로 마이그레이션됩니다. +- Telegram: `streamMode`와 불리언 `streaming`은 `streaming` enum으로 자동 마이그레이션됩니다. +- Discord: `streamMode`와 불리언 `streaming`은 `streaming` enum으로 자동 마이그레이션됩니다. +- Slack: `streamMode`는 `streaming.mode`로 자동 마이그레이션되고, 불리언 `streaming`은 `streaming.mode`와 `streaming.nativeTransport`로 자동 마이그레이션되며, 레거시 `nativeStreaming`은 `streaming.nativeTransport`로 자동 마이그레이션됩니다. ### 런타임 동작 @@ -147,7 +148,7 @@ Telegram: - DM과 그룹/토픽 전반에서 `sendMessage` + `editMessageText` 미리보기 업데이트를 사용합니다. - Telegram 블록 스트리밍이 명시적으로 활성화된 경우 미리보기 스트리밍은 건너뜁니다(이중 스트리밍 방지). -- `/reasoning stream`은 reasoning을 미리보기에 쓸 수 있습니다. +- `/reasoning stream`은 추론 내용을 미리보기에 쓸 수 있습니다. Discord: @@ -157,12 +158,12 @@ Discord: Slack: -- `partial`은 사용 가능한 경우 Slack 기본 스트리밍(`chat.startStream`/`append`/`stop`)을 사용할 수 있습니다. +- `partial`은 가능할 때 Slack 기본 스트리밍(`chat.startStream`/`append`/`stop`)을 사용할 수 있습니다. - `block`은 추가형 초안 미리보기를 사용합니다. -- `progress`는 상태 미리보기 텍스트를 사용한 뒤 완료 시 최종 답변을 전송합니다. +- `progress`는 상태 미리보기 텍스트를 사용한 뒤, 최종 답변을 전송합니다. ## 관련 -- [Messages](/concepts/messages) — 메시지 수명 주기 및 전달 -- [Retry](/concepts/retry) — 전달 실패 시 재시도 동작 -- [Channels](/channels) — 채널별 스트리밍 지원 +- [메시지](/ko/concepts/messages) — 메시지 수명 주기와 전달 +- [재시도](/ko/concepts/retry) — 전달 실패 시 재시도 동작 +- [채널](/ko/channels) — 채널별 스트리밍 지원 diff --git a/docs/ko/gateway/configuration-reference.md b/docs/ko/gateway/configuration-reference.md index 2e0aac356..bcd90124d 100644 --- a/docs/ko/gateway/configuration-reference.md +++ b/docs/ko/gateway/configuration-reference.md @@ -1,56 +1,70 @@ --- read_when: - - 정확한 필드 수준의 config 의미 또는 기본값이 필요합니다 - - 채널, 모델, gateway 또는 도구 config 블록을 검증하고 있습니다 -summary: 모든 OpenClaw config 키, 기본값, 채널 설정에 대한 완전한 참조 -title: Configuration Reference + - 정확한 필드 수준의 구성 의미 또는 기본값이 필요할 때 + - 채널, 모델, gateway 또는 tool 구성 블록을 검증하고 있을 때 +summary: 핵심 OpenClaw 키, 기본값, 그리고 전용 서브시스템 참조 링크를 위한 Gateway 구성 참조 +title: 구성 참조 x-i18n: - generated_at: "2026-04-08T02:20:03Z" + generated_at: "2026-04-08T06:01:03Z" model: gpt-5.4 provider: openai - source_hash: 2c7991b948cbbb7954a3e26280089ab00088e7f4878ec0b0540c3c9acf222ebb + source_hash: 2f9ab34fb56897a77cb038d95bea21e8530d8f0402b66d1ee97c73822a1e8fd4 source_path: gateway/configuration-reference.md workflow: 15 --- -# Configuration Reference +# 구성 참조 -`~/.openclaw/openclaw.json`에서 사용할 수 있는 모든 필드입니다. 작업 중심 개요는 [Configuration](/ko/gateway/configuration)을 참고하세요. +`~/.openclaw/openclaw.json`에 대한 핵심 구성 참조입니다. 작업 중심 개요는 [Configuration](/ko/gateway/configuration)을 참고하세요. -Config 형식은 **JSON5**입니다(주석 + 후행 쉼표 허용). 모든 필드는 선택 사항이며, 생략하면 OpenClaw가 안전한 기본값을 사용합니다. +이 페이지는 주요 OpenClaw 구성 표면을 다루며, 서브시스템에 별도의 더 깊은 참조가 있는 경우 해당 링크를 제공합니다. 이 페이지는 모든 채널/플러그인 소유 명령 카탈로그나 모든 심층 메모리/QMD 노브를 한 페이지에 인라인으로 넣으려는 것은 **아닙니다**. + +코드 기준 진실: + +- `openclaw config schema`는 검증과 Control UI에 사용되는 실제 JSON Schema를 출력하며, 사용 가능한 경우 번들/플러그인/채널 메타데이터가 병합됩니다 +- `config.schema.lookup`는 드릴다운 도구용으로 경로 범위가 지정된 단일 스키마 노드를 반환합니다 +- `pnpm config:docs:check` / `pnpm config:docs:gen`는 현재 스키마 표면과 구성 문서 기준 해시를 검증합니다 + +전용 심층 참조: + +- `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations`, 그리고 `plugins.entries.memory-core.config.dreaming` 아래의 dreaming 구성을 위한 [Memory configuration reference](/ko/reference/memory-config) +- 현재 내장 + 번들 명령 카탈로그를 위한 [Slash Commands](/ko/tools/slash-commands) +- 채널별 명령 표면에 대한 각 채널/플러그인 소유 페이지 + +구성 형식은 **JSON5**입니다(주석 + 후행 쉼표 허용). 모든 필드는 선택 사항이며, 생략되면 OpenClaw가 안전한 기본값을 사용합니다. --- ## 채널 -각 채널은 config 섹션이 존재하면 자동으로 시작됩니다(`enabled: false`가 아닌 경우). +각 채널은 해당 구성 섹션이 존재하면 자동으로 시작됩니다(`enabled: false`가 아닌 경우). -### DM 및 그룹 접근 +### DM 및 그룹 액세스 -모든 채널은 DM 정책과 그룹 정책을 지원합니다. +모든 채널은 DM 정책과 그룹 정책을 지원합니다: -| DM 정책 | 동작 | -| -------------------- | --------------------------------------------------------------- | -| `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 함 | -| `allowlist` | `allowFrom`(또는 페어링된 허용 저장소)에 있는 발신자만 허용 | -| `open` | 모든 인바운드 DM 허용(`allowFrom: ["*"]` 필요) | -| `disabled` | 모든 인바운드 DM 무시 | +| DM 정책 | 동작 | +| ------------------ | --------------------------------------------------------------- | +| `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 함 | +| `allowlist` | `allowFrom`(또는 페어링된 허용 저장소)에 있는 발신자만 허용 | +| `open` | 모든 수신 DM 허용(`allowFrom: ["*"]` 필요) | +| `disabled` | 모든 수신 DM 무시 | -| 그룹 정책 | 동작 | -| ---------------------- | -------------------------------------------------------- | -| `allowlist` (기본값) | 구성된 allowlist와 일치하는 그룹만 허용 | -| `open` | 그룹 allowlist 우회(여전히 멘션 게이팅은 적용됨) | -| `disabled` | 모든 그룹/룸 메시지 차단 | +| 그룹 정책 | 동작 | +| --------------------- | -------------------------------------------------------- | +| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용 | +| `open` | 그룹 허용 목록 우회(멘션 게이팅은 계속 적용) | +| `disabled` | 모든 그룹/룸 메시지 차단 | -`channels.defaults.groupPolicy`는 provider의 `groupPolicy`가 설정되지 않았을 때 기본값을 설정합니다. +`channels.defaults.groupPolicy`는 공급자의 `groupPolicy`가 설정되지 않았을 때 기본값을 설정합니다. 페어링 코드는 1시간 후 만료됩니다. 대기 중인 DM 페어링 요청은 **채널당 3개**로 제한됩니다. -provider 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(fail-closed)로 대체됩니다. +공급자 블록이 완전히 누락된 경우(`channels.` 부재), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(fail-closed)로 대체됩니다. ### 채널 모델 재정의 -`channels.modelByChannel`을 사용해 특정 채널 ID를 모델에 고정할 수 있습니다. 값은 `provider/model` 또는 구성된 모델 별칭을 받습니다. 채널 매핑은 세션에 아직 모델 재정의가 없을 때 적용됩니다(예: `/model`로 설정된 경우). +특정 채널 ID를 모델에 고정하려면 `channels.modelByChannel`을 사용하세요. 값은 `provider/model` 또는 구성된 모델 별칭을 받습니다. 이 채널 매핑은 세션에 이미 모델 재정의가 없는 경우(예: `/model`로 설정된 경우) 적용됩니다. ```json5 { @@ -73,7 +87,7 @@ provider 블록이 완전히 누락된 경우(`channels.` 없음), 런 ### 채널 기본값 및 heartbeat -provider 전반에서 공유되는 그룹 정책과 heartbeat 동작에는 `channels.defaults`를 사용하세요. +공급자 간 공유 그룹 정책 및 heartbeat 동작에는 `channels.defaults`를 사용하세요: ```json5 { @@ -91,11 +105,11 @@ provider 전반에서 공유되는 그룹 정책과 heartbeat 동작에는 `chan } ``` -- `channels.defaults.groupPolicy`: provider 수준 `groupPolicy`가 설정되지 않은 경우의 대체 그룹 정책입니다. -- `channels.defaults.contextVisibility`: 모든 채널의 기본 보조 컨텍스트 표시 모드입니다. 값: `all`(기본값, 인용/스레드/기록 컨텍스트 전체 포함), `allowlist`(allowlist된 발신자의 컨텍스트만 포함), `allowlist_quote`(allowlist와 같지만 명시적 인용/답글 컨텍스트 유지). 채널별 재정의: `channels..contextVisibility`. +- `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.heartbeat.showAlerts`: heartbeat 출력에 성능 저하/오류 상태를 포함합니다. +- `channels.defaults.heartbeat.useIndicator`: 압축된 표시기 스타일 heartbeat 출력을 렌더링합니다. ### WhatsApp @@ -110,7 +124,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // 파란 체크 표시(셀프 채팅 모드에서는 false) + sendReadReceipts: true, // 파란 체크(셀프 채팅 모드에서는 false) groups: { "*": { requireMention: true }, }, @@ -132,7 +146,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` - + ```json5 { @@ -150,9 +164,9 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 아웃바운드 명령은 `default` 계정이 있으면 기본적으로 그 계정을 사용하고, 없으면 첫 번째로 구성된 계정 ID(정렬 기준)를 사용합니다. -- 선택적 `channels.whatsapp.defaultAccount`는 구성된 계정 ID와 일치할 때 이 대체 기본 계정 선택을 재정의합니다. -- 레거시 단일 계정 Baileys auth 디렉터리는 `openclaw doctor`에 의해 `whatsapp/default`로 마이그레이션됩니다. +- 아웃바운드 명령은 `default` 계정이 있으면 기본적으로 해당 계정을 사용하고, 그렇지 않으면 정렬된 첫 번째 구성 계정 ID를 사용합니다. +- 선택적 `channels.whatsapp.defaultAccount`는 구성된 계정 ID와 일치하는 경우 해당 대체 기본 계정 선택을 재정의합니다. +- 레거시 단일 계정 Baileys 인증 디렉터리는 `openclaw doctor`에 의해 `whatsapp/default`로 마이그레이션됩니다. - 계정별 재정의: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -171,24 +185,24 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 "*": { requireMention: true }, "-1001234567890": { allowFrom: ["@admin"], - systemPrompt: "Keep answers brief.", + systemPrompt: "응답은 짧게 유지하세요.", topics: { "99": { requireMention: false, skills: ["search"], - systemPrompt: "Stay on topic.", + systemPrompt: "주제를 벗어나지 마세요.", }, }, }, }, customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Git 백업" }, + { command: "generate", description: "이미지 생성" }, ], 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, @@ -211,12 +225,12 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 봇 토큰: `channels.telegram.botToken` 또는 `channels.telegram.tokenFile`(일반 파일만 허용, symlink는 거부), 기본 계정의 대체값으로 `TELEGRAM_BOT_TOKEN`도 사용됩니다. -- 선택적 `channels.telegram.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- 멀티 계정 설정(계정 ID 2개 이상)에서는 대체 라우팅을 피하기 위해 명시적 기본값(`channels.telegram.defaultAccount` 또는 `channels.telegram.accounts.default`)을 설정하세요. 누락되었거나 잘못되었으면 `openclaw doctor`가 경고합니다. -- `configWrites: false`는 Telegram에서 시작된 config 쓰기(슈퍼그룹 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`를 사용합니다(직접 채팅과 그룹 채팅 모두에서 동작). +- 봇 토큰: `channels.telegram.botToken` 또는 `channels.telegram.tokenFile`(일반 파일만 허용, symlink는 거부), 기본 계정에는 `TELEGRAM_BOT_TOKEN`이 대체값으로 사용됩니다. +- 선택적 `channels.telegram.defaultAccount`는 구성된 계정 ID와 일치하는 경우 기본 계정 선택을 재정의합니다. +- 다중 계정 구성(계정 ID 2개 이상)에서는 대체 라우팅을 피하려면 명시적 기본값(`channels.telegram.defaultAccount` 또는 `channels.telegram.accounts.default`)을 설정하세요. 누락되거나 잘못된 경우 `openclaw doctor`가 경고합니다. +- `configWrites: false`는 Telegram에서 시작된 구성 쓰기(슈퍼그룹 ID 마이그레이션, `/config set|unset`)를 차단합니다. +- `type: "acp"`를 가진 최상위 `bindings[]` 항목은 포럼 주제에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에는 정규 `chatId:topic:topicId` 사용). 필드 의미는 [ACP Agents](/ko/tools/acp-agents#channel-specific-settings)에서 공유됩니다. +- Telegram 스트림 미리보기는 `sendMessage` + `editMessageText`를 사용합니다(직접 채팅과 그룹 채팅 모두에서 작동). - 재시도 정책: [Retry policy](/ko/concepts/retry)를 참고하세요. ### Discord @@ -264,7 +278,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 requireMention: true, users: ["987654321098765432"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "짧게만 답하세요.", }, }, }, @@ -283,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, @@ -319,36 +333,36 @@ 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자 미만이어도 긴 메시지를 분할합니다. -- `channels.discord.threadBindings`는 Discord 스레드 바운드 라우팅을 제어합니다. - - `enabled`: 스레드 바운드 세션 기능(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, 그리고 바운드 전달/라우팅)에 대한 Discord 재정의 - - `idleHours`: 비활동 자동 unfocus의 시간 단위 Discord 재정의(`0`은 비활성화) - - `maxAgeHours`: 하드 최대 사용 기간의 시간 단위 Discord 재정의(`0`은 비활성화) - - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` 자동 스레드 생성/바인딩을 위한 opt-in 스위치 -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 채널 및 스레드에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에 channel/thread id 사용). 필드 의미는 [ACP Agents](/ko/tools/acp-agents#channel-specific-settings)에서 공통으로 설명합니다. +- 토큰: `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자를 넘지 않아도 긴 메시지를 분할합니다. +- `channels.discord.threadBindings`는 Discord 스레드 바운드 라우팅을 제어합니다: + - `enabled`: 스레드 바운드 세션 기능(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, 바운드 전달/라우팅)에 대한 Discord 재정의 + - `idleHours`: 비활성 자동 unfocus 시간 단위 재정의(`0`은 비활성화) + - `maxAgeHours`: 하드 최대 사용 기간 시간 단위 재정의(`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`와 boolean `streaming` 값은 자동 마이그레이션됩니다. -- `channels.discord.autoPresence`는 런타임 가용성을 봇 존재 상태에 매핑합니다(healthy => online, degraded => idle, exhausted => dnd). 선택적으로 상태 텍스트 재정의도 가능합니다. -- `channels.discord.dangerouslyAllowNameMatching`는 변경 가능한 이름/태그 매칭을 다시 활성화합니다(break-glass 호환 모드). +- `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에 매핑합니다(정상 => online, 성능 저하 => idle, 소진 => dnd) 그리고 선택적 상태 텍스트 재정의를 허용합니다. +- `channels.discord.dangerouslyAllowNameMatching`는 변경 가능한 이름/태그 매칭을 다시 활성화합니다(비상 호환 모드). - `channels.discord.execApprovals`: Discord 네이티브 exec 승인 전달 및 승인자 권한 부여. - - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). auto 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 해석할 수 있을 때 exec 승인이 활성화됩니다. - - `approvers`: exec 요청을 승인할 수 있는 Discord 사용자 ID입니다. 생략하면 `commands.ownerAllowFrom`을 대체값으로 사용합니다. - - `agentFilter`: 선택적 agent ID allowlist입니다. 생략하면 모든 agent에 대한 승인이 전달됩니다. - - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 regex). - - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값)은 승인자 DM으로, `"channel"`은 원래 채널로, `"both"`는 둘 다 보냅니다. target에 `"channel"`이 포함되면 버튼은 해석된 승인자만 사용할 수 있습니다. - - `cleanupAfterResolve`: `true`이면 승인, 거절 또는 타임아웃 후 승인 DM을 삭제합니다. + - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). auto 모드에서는 승인자를 `approvers` 또는 `commands.ownerAllowFrom`에서 해석할 수 있을 때 exec 승인이 활성화됩니다. + - `approvers`: exec 요청을 승인할 수 있는 Discord 사용자 ID입니다. 생략되면 `commands.ownerAllowFrom`을 대체값으로 사용합니다. + - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 생략하면 모든 에이전트에 대한 승인을 전달합니다. + - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 regex)입니다. + - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값)은 승인자 DM으로, `"channel"`은 원래 채널로, `"both"`는 둘 다로 보냅니다. target에 `"channel"`이 포함되면 버튼은 해석된 승인자만 사용할 수 있습니다. + - `cleanupAfterResolve`: `true`이면 승인, 거부, 타임아웃 후 승인 DM을 삭제합니다. -**반응 알림 모드:** `off`(없음), `own`(봇 메시지, 기본값), `all`(모든 메시지), `allowlist`(모든 메시지에서 `guilds..users` 기준). +**반응 알림 모드:** `off`(없음), `own`(봇의 메시지, 기본값), `all`(모든 메시지), `allowlist`(`guilds..users`의 모든 메시지). ### Google Chat @@ -381,9 +395,9 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 - 서비스 계정 JSON: 인라인(`serviceAccount`) 또는 파일 기반(`serviceAccountFile`)입니다. - 서비스 계정 SecretRef도 지원됩니다(`serviceAccountRef`). -- 환경 변수 대체값: `GOOGLE_CHAT_SERVICE_ACCOUNT` 또는 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- env 대체값: `GOOGLE_CHAT_SERVICE_ACCOUNT` 또는 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - 전달 대상에는 `spaces/` 또는 `users/`를 사용하세요. -- `channels.googlechat.dangerouslyAllowNameMatching`는 변경 가능한 이메일 principal 매칭을 다시 활성화합니다(break-glass 호환 모드). +- `channels.googlechat.dangerouslyAllowNameMatching`는 변경 가능한 이메일 principal 매칭을 다시 활성화합니다(비상 호환 모드). ### Slack @@ -405,7 +419,7 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 allowBots: false, users: ["U123"], skills: ["docs"], - systemPrompt: "Short answers only.", + systemPrompt: "짧게만 답하세요.", }, }, historyLimit: 50, @@ -433,8 +447,10 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (미리보기 모드) - nativeStreaming: true, // streaming=partial일 때 Slack 네이티브 스트리밍 API 사용 + streaming: { + mode: "partial", // off | partial | block | progress + nativeTransport: true, // mode=partial일 때 Slack 네이티브 스트리밍 API 사용 + }, mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,39 +464,34 @@ WhatsApp은 gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- **Socket mode**에는 `botToken`과 `appToken`이 모두 필요합니다(기본 계정 환경 변수 대체값으로 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). +- **Socket mode**에는 `botToken`과 `appToken`이 모두 필요합니다(기본 계정 env 대체값은 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). - **HTTP mode**에는 `botToken`과 `signingSecret`(루트 또는 계정별)이 필요합니다. -- `botToken`, `appToken`, `signingSecret`, `userToken`은 일반 텍스트 - 문자열 또는 SecretRef 객체를 받을 수 있습니다. -- Slack 계정 스냅샷은 - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, HTTP mode에서는 - `signingSecretStatus` 같은 자격 증명별 source/status 필드를 노출합니다. - `configured_unavailable`은 해당 계정이 - SecretRef를 통해 구성되었지만 현재 명령/런타임 경로에서는 - 비밀 값이 해석되지 않았음을 의미합니다. -- `configWrites: false`는 Slack에서 시작된 config 쓰기를 차단합니다. -- 선택적 `channels.slack.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- `channels.slack.streaming`은 정식 스트림 모드 키입니다. 레거시 `streamMode`와 boolean `streaming` 값은 자동 마이그레이션됩니다. +- `botToken`, `appToken`, `signingSecret`, `userToken`은 일반 텍스트 문자열 또는 SecretRef 객체를 받을 수 있습니다. +- Slack 계정 스냅샷은 `botTokenSource`, `botTokenStatus`, `appTokenStatus`, 그리고 HTTP mode에서는 `signingSecretStatus`와 같은 자격 증명별 소스/상태 필드를 노출합니다. `configured_unavailable`은 해당 계정이 SecretRef를 통해 구성되었지만 현재 명령/런타임 경로에서 비밀 값을 해석할 수 없었음을 의미합니다. +- `configWrites: false`는 Slack에서 시작된 구성 쓰기를 차단합니다. +- 선택적 `channels.slack.defaultAccount`는 구성된 계정 ID와 일치하는 경우 기본 계정 선택을 재정의합니다. +- `channels.slack.streaming.mode`는 정규 Slack 스트림 모드 키입니다. `channels.slack.streaming.nativeTransport`는 Slack의 네이티브 스트리밍 전송을 제어합니다. 레거시 `streamMode`, 불리언 `streaming`, `nativeStreaming` 값은 자동 마이그레이션됩니다. - 전달 대상에는 `user:`(DM) 또는 `channel:`를 사용하세요. -**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). +**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist`에서 가져옴). -**스레드 세션 격리:** `thread.historyScope`는 스레드별(기본값) 또는 채널 전체 공유입니다. `thread.inheritParent`는 부모 채널 전사를 새 스레드로 복사합니다. +**스레드 세션 격리:** `thread.historyScope`는 스레드별(기본값) 또는 채널 전체 공유입니다. `thread.inheritParent`는 부모 채널 대화 기록을 새 스레드로 복사합니다. -- `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 assistant 스타일의 "입력 중..." 스레드 상태는 답글 스레드 대상을 요구합니다. 최상위 DM은 기본적으로 스레드 밖으로 유지되므로, 스레드 스타일 미리보기 대신 `typingReaction` 또는 일반 전달을 사용합니다. +- `typingReaction`은 답글이 실행되는 동안 수신 Slack 메시지에 임시 반응을 추가하고, 완료 시 제거합니다. `"hourglass_flowing_sand"`와 같은 Slack 이모지 shortcode를 사용하세요. +- `channels.slack.execApprovals`: Slack 네이티브 exec 승인 전달 및 승인자 권한 부여. 스키마는 Discord와 동일합니다: `enabled` (`true`/`false`/`"auto"`), `approvers`(Slack 사용자 ID), `agentFilter`, `sessionFilter`, `target` (`"dm"`, `"channel"`, 또는 `"both"`). | 작업 그룹 | 기본값 | 참고 | -| ------------ | ------- | ---------------------- | -| reactions | 활성화됨 | 반응 + 반응 목록 | -| messages | 활성화됨 | 읽기/보내기/편집/삭제 | -| pins | 활성화됨 | 고정/고정 해제/목록 | -| memberInfo | 활성화됨 | 멤버 정보 | -| emojiList | 활성화됨 | 사용자 지정 이모지 목록 | +| ----------- | ------- | ---------------------- | +| reactions | 활성화 | 반응 추가 + 반응 목록 | +| messages | 활성화 | 읽기/보내기/편집/삭제 | +| pins | 활성화 | 고정/해제/목록 | +| memberInfo | 활성화 | 멤버 정보 | +| emojiList | 활성화 | 커스텀 이모지 목록 | ### Mattermost -Mattermost는 plugin으로 제공됩니다: `openclaw plugins install @openclaw/mattermost`. +Mattermost는 플러그인으로 제공됩니다: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -510,21 +521,19 @@ Mattermost는 plugin으로 제공됩니다: `openclaw plugins install @openclaw/ } ``` -채팅 모드: `oncall`(@-mention 시 응답, 기본값), `onmessage`(모든 메시지), `onchar`(트리거 접두사로 시작하는 메시지). +채팅 모드: `oncall`(@-멘션 시 응답, 기본값), `onmessage`(모든 메시지), `onchar`(트리거 접두사로 시작하는 메시지). Mattermost 네이티브 명령이 활성화되면: - `commands.callbackPath`는 전체 URL이 아니라 경로여야 합니다(예: `/api/channels/mattermost/command`). -- `commands.callbackUrl`은 OpenClaw gateway 엔드포인트로 해석되어야 하며 Mattermost 서버에서 도달 가능해야 합니다. -- 네이티브 슬래시 callback은 슬래시 명령 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 callback을 - `Unauthorized: invalid command token.`으로 거부합니다. -- 비공개/tailnet/내부 callback 호스트의 경우 Mattermost는 - `ServiceSettings.AllowedUntrustedInternalConnections`에 callback 호스트/도메인이 포함되도록 요구할 수 있습니다. +- `commands.callbackUrl`은 OpenClaw gateway 엔드포인트로 해석되어야 하며 Mattermost 서버에서 접근 가능해야 합니다. +- 네이티브 slash callback은 slash 명령 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 `Unauthorized: invalid command token.`으로 callback을 거부합니다. +- 비공개/tailnet/내부 callback 호스트의 경우, Mattermost는 callback 호스트/도메인을 포함하도록 `ServiceSettings.AllowedUntrustedInternalConnections`가 필요할 수 있습니다. 전체 URL이 아니라 호스트/도메인 값을 사용하세요. -- `channels.mattermost.configWrites`: Mattermost에서 시작된 config 쓰기를 허용하거나 거부합니다. -- `channels.mattermost.requireMention`: 채널에서 답변하기 전에 `@mention`을 요구합니다. -- `channels.mattermost.groups..requireMention`: 채널별 멘션 게이팅 재정의(기본값은 `"*"`). -- 선택적 `channels.mattermost.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- `channels.mattermost.configWrites`: Mattermost에서 시작된 구성 쓰기를 허용하거나 거부합니다. +- `channels.mattermost.requireMention`: 채널에서 응답하기 전에 `@mention`을 요구합니다. +- `channels.mattermost.groups..requireMention`: 채널별 멘션 게이팅 재정의(`"*"`는 기본값). +- 선택적 `channels.mattermost.defaultAccount`는 구성된 계정 ID와 일치하는 경우 기본 계정 선택을 재정의합니다. ### Signal @@ -545,15 +554,15 @@ Mattermost 네이티브 명령이 활성화되면: } ``` -**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). +**반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist`에서 가져옴). -- `channels.signal.account`: 채널 시작을 특정 Signal 계정 식별자로 고정합니다. -- `channels.signal.configWrites`: Signal에서 시작된 config 쓰기를 허용하거나 거부합니다. -- 선택적 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- `channels.signal.account`: 채널 시작을 특정 Signal 계정 식별자에 고정합니다. +- `channels.signal.configWrites`: Signal에서 시작된 구성 쓰기를 허용하거나 거부합니다. +- 선택적 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치하는 경우 기본 계정 선택을 재정의합니다. ### BlueBubbles -BlueBubbles는 권장되는 iMessage 경로입니다(plugin 기반, `channels.bluebubbles` 아래에 구성). +BlueBubbles는 권장되는 iMessage 경로입니다(플러그인 기반, `channels.bluebubbles` 아래에서 구성). ```json5 { @@ -561,21 +570,21 @@ BlueBubbles는 권장되는 iMessage 경로입니다(plugin 기반, `channels.bl bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, group controls, 고급 actions: + // serverUrl, password, webhookPath, 그룹 제어 및 고급 작업: // /channels/bluebubbles 참고 }, }, } ``` -- 여기서 다루는 핵심 키 경로: `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 handle 또는 대상 문자열(`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)를 실행합니다. daemon이나 포트는 필요하지 않습니다. +OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 생성합니다. 데몬이나 포트는 필요하지 않습니다. ```json5 { @@ -599,17 +608,17 @@ OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 실행합니다. daemon이 } ``` -- 선택적 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 선택적 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치하는 경우 기본 계정 선택을 재정의합니다. - Messages DB에 대한 Full Disk Access가 필요합니다. -- `chat_id:` 대상을 권장합니다. 채팅 목록은 `imsg chats --limit 20`으로 확인하세요. -- `cliPath`는 SSH wrapper를 가리킬 수 있습니다. SCP 첨부 파일 가져오기를 위해 `remoteHost`(`host` 또는 `user@host`)를 설정하세요. -- `attachmentRoots` 및 `remoteAttachmentRoots`는 인바운드 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). -- SCP는 엄격한 host-key 확인을 사용하므로, relay 호스트 키가 이미 `~/.ssh/known_hosts`에 있어야 합니다. -- `channels.imessage.configWrites`: iMessage에서 시작된 config 쓰기를 허용하거나 거부합니다. -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에는 정규화된 handle 또는 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공통 필드 의미: [ACP Agents](/ko/tools/acp-agents#channel-specific-settings). +- `chat_id:` 대상을 선호하세요. 채팅을 나열하려면 `imsg chats --limit 20`을 사용하세요. +- `cliPath`는 SSH wrapper를 가리킬 수 있으며, SCP 첨부 파일 가져오기를 위해 `remoteHost`(`host` 또는 `user@host`)를 설정하세요. +- `attachmentRoots` 및 `remoteAttachmentRoots`는 수신 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). +- SCP는 strict host-key checking을 사용하므로, 릴레이 호스트 키가 이미 `~/.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). - + ```bash #!/usr/bin/env bash @@ -620,7 +629,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix는 extension 기반이며 `channels.matrix` 아래에 구성됩니다. +Matrix는 확장 기반이며 `channels.matrix` 아래에서 구성됩니다. ```json5 { @@ -650,25 +659,25 @@ Matrix는 extension 기반이며 `channels.matrix` 아래에 구성됩니다. } ``` -- 토큰 인증은 `accessToken`을, 비밀번호 인증은 `userId` + `password`를 사용합니다. -- `channels.matrix.proxy`는 Matrix HTTP 트래픽을 명시적인 HTTP(S) 프록시를 통해 라우팅합니다. 이름이 있는 계정은 `channels.matrix.accounts..proxy`로 이를 재정의할 수 있습니다. +- 토큰 인증은 `accessToken`을 사용하고, 비밀번호 인증은 `userId` + `password`를 사용합니다. +- `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.defaultAccount`는 다중 계정 구성에서 선호 계정을 선택합니다. +- `channels.matrix.autoJoin`의 기본값은 `off`이므로, `autoJoin: "allowlist"`와 `autoJoinAllowlist`를 설정하거나 `autoJoin: "always"`를 설정하기 전까지 초대된 룸과 새 DM 스타일 초대는 무시됩니다. - `channels.matrix.execApprovals`: Matrix 네이티브 exec 승인 전달 및 승인자 권한 부여. - - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). auto 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 해석할 수 있을 때 exec 승인이 활성화됩니다. + - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). auto 모드에서는 승인자를 `approvers` 또는 `commands.ownerAllowFrom`에서 해석할 수 있을 때 exec 승인이 활성화됩니다. - `approvers`: exec 요청을 승인할 수 있는 Matrix 사용자 ID(예: `@owner:example.org`)입니다. - - `agentFilter`: 선택적 agent ID allowlist입니다. 생략하면 모든 agent에 대한 승인이 전달됩니다. - - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 regex). - - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값), `"channel"`(원래 room), 또는 `"both"`. + - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 생략하면 모든 에이전트에 대한 승인을 전달합니다. + - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 regex)입니다. + - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값), `"channel"`(원래 룸), 또는 `"both"`. - 계정별 재정의: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 묶이는 방식을 제어합니다: `per-user`(기본값)는 라우팅된 peer 기준으로 공유하고, `per-room`은 각 DM room을 분리합니다. -- Matrix 상태 probe와 실시간 directory 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. +- `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 그룹화되는 방식을 제어합니다: `per-user`(기본값)는 라우팅된 peer 기준으로 공유하고, `per-room`은 각 DM 룸을 격리합니다. +- Matrix 상태 프로브와 라이브 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. - 전체 Matrix 구성, 대상 지정 규칙, 설정 예시는 [Matrix](/ko/channels/matrix)에 문서화되어 있습니다. ### Microsoft Teams -Microsoft Teams는 extension 기반이며 `channels.msteams` 아래에 구성됩니다. +Microsoft Teams는 확장 기반이며 `channels.msteams` 아래에서 구성됩니다. ```json5 { @@ -676,19 +685,19 @@ Microsoft Teams는 extension 기반이며 `channels.msteams` 아래에 구성됩 msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, team/channel 정책: + // appId, appPassword, tenantId, webhook, 팀/채널 정책: // /channels/msteams 참고 }, }, } ``` -- 여기서 다루는 핵심 키 경로: `channels.msteams`, `channels.msteams.configWrites`. -- 전체 Teams config(자격 증명, webhook, DM/그룹 정책, 팀별/채널별 재정의)는 [Microsoft Teams](/ko/channels/msteams)에 문서화되어 있습니다. +- 여기에서 다루는 핵심 키 경로: `channels.msteams`, `channels.msteams.configWrites`. +- 전체 Teams 구성(자격 증명, webhook, DM/그룹 정책, 팀별/채널별 재정의)은 [Microsoft Teams](/ko/channels/msteams)에 문서화되어 있습니다. ### IRC -IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. +IRC는 확장 기반이며 `channels.irc` 아래에서 구성됩니다. ```json5 { @@ -709,13 +718,13 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -- 여기서 다루는 핵심 키 경로: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- 선택적 `channels.irc.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- 전체 IRC 채널 구성(host/port/TLS/channels/allowlists/멘션 게이팅)은 [IRC](/ko/channels/irc)에 문서화되어 있습니다. +- 여기에서 다루는 핵심 키 경로: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- 선택적 `channels.irc.defaultAccount`는 구성된 계정 ID와 일치하는 경우 기본 계정 선택을 재정의합니다. +- 전체 IRC 채널 구성(호스트/포트/TLS/채널/허용 목록/멘션 게이팅)은 [IRC](/ko/channels/irc)에 문서화되어 있습니다. -### 멀티 계정(모든 채널) +### 다중 계정(모든 채널) -채널당 여러 계정을 실행할 수 있습니다(각각 고유한 `accountId` 사용). +채널별로 여러 계정을 실행합니다(각각 고유한 `accountId` 사용): ```json5 { @@ -723,11 +732,11 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. telegram: { accounts: { default: { - name: "Primary bot", + name: "주 봇", botToken: "123456:ABC...", }, alerts: { - name: "Alerts bot", + name: "알림 봇", botToken: "987654:XYZ...", }, }, @@ -736,28 +745,28 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -- `accountId`가 생략되면 `default`가 사용됩니다(CLI + 라우팅). -- 환경 변수 토큰은 **default** 계정에만 적용됩니다. +- `default`는 `accountId`가 생략되었을 때 사용됩니다(CLI + 라우팅). +- env 토큰은 **default** 계정에만 적용됩니다. - 기본 채널 설정은 계정별로 재정의되지 않는 한 모든 계정에 적용됩니다. -- 각 계정을 서로 다른 agent로 라우팅하려면 `bindings[].match.accountId`를 사용하세요. -- 단일 계정 최상위 채널 config 상태에서 `openclaw channels add`(또는 채널 온보딩)를 통해 non-default 계정을 추가하면, OpenClaw는 먼저 계정 범위의 최상위 단일 계정 값을 채널 계정 맵으로 승격해 원래 계정이 계속 동작하게 합니다. 대부분의 채널은 이를 `channels..accounts.default`로 옮기고, Matrix는 대신 기존의 일치하는 named/default 대상을 유지할 수 있습니다. -- 기존의 채널 전용 바인딩(`accountId` 없음)은 계속 기본 계정과 일치하며, 계정 범위 바인딩은 여전히 선택 사항입니다. -- `openclaw doctor --fix`도 혼합된 형태를 복구하여, 해당 채널에 대해 선택된 승격 계정으로 계정 범위 최상위 단일 계정 값을 이동합니다. 대부분의 채널은 `accounts.default`를 사용하고, Matrix는 기존의 일치하는 named/default 대상을 유지할 수 있습니다. +- `bindings[].match.accountId`를 사용해 각 계정을 다른 에이전트로 라우팅하세요. +- 아직 단일 계정 최상위 채널 구성 상태에서 `openclaw channels add`(또는 채널 온보딩)를 통해 비기본 계정을 추가하면, OpenClaw는 먼저 계정 범위의 최상위 단일 계정 값을 채널 계정 맵으로 승격하여 원래 계정이 계속 작동하게 합니다. 대부분의 채널은 이를 `channels..accounts.default`로 옮기며, Matrix는 기존의 일치하는 명명/default 대상을 대신 유지할 수 있습니다. +- 기존 채널 전용 바인딩(`accountId` 없음)은 기본 계정과 계속 일치하며, 계정 범위 바인딩은 여전히 선택 사항입니다. +- `openclaw doctor --fix`도 계정 범위의 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 옮겨 혼합 형태를 복구합니다. 대부분의 채널은 `accounts.default`를 사용하고, Matrix는 기존의 일치하는 명명/default 대상을 유지할 수 있습니다. -### 기타 extension 채널 +### 기타 확장 채널 -많은 extension 채널은 `channels.`로 구성되며 전용 채널 페이지에 문서화되어 있습니다(예: Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, Twitch). -전체 채널 색인은 [Channels](/ko/channels)를 참고하세요. +많은 확장 채널은 `channels.`로 구성되며 전용 채널 페이지에 문서화되어 있습니다(예: Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat, Twitch). +전체 채널 인덱스는 [Channels](/ko/channels)를 참고하세요. ### 그룹 채팅 멘션 게이팅 -그룹 메시지는 기본적으로 **멘션 필요**입니다(메타데이터 멘션 또는 안전한 regex 패턴). WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. +그룹 메시지는 기본적으로 **멘션 필요**(메타데이터 멘션 또는 안전한 regex 패턴)입니다. WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. **멘션 유형:** -- **메타데이터 멘션**: 플랫폼 네이티브 @-멘션. WhatsApp 셀프 채팅 모드에서는 무시됩니다. -- **텍스트 패턴**: `agents.list[].groupChat.mentionPatterns`의 안전한 regex 패턴입니다. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다. -- 멘션 게이팅은 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 최소 1개의 패턴). +- **메타데이터 멘션**: 네이티브 플랫폼 @-멘션. WhatsApp 셀프 채팅 모드에서는 무시됩니다. +- **텍스트 패턴**: `agents.list[].groupChat.mentionPatterns`의 안전한 regex 패턴. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다. +- 멘션 게이팅은 감지가 가능한 경우에만 적용됩니다(네이티브 멘션 또는 패턴이 최소 하나 이상). ```json5 { @@ -770,7 +779,7 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -`messages.groupChat.historyLimit`은 전역 기본값을 설정합니다. 채널은 `channels..historyLimit`(또는 계정별)로 재정의할 수 있습니다. 비활성화하려면 `0`으로 설정하세요. +`messages.groupChat.historyLimit`는 전역 기본값을 설정합니다. 채널은 `channels..historyLimit`(또는 계정별)로 재정의할 수 있습니다. 비활성화하려면 `0`으로 설정하세요. #### DM 기록 제한 @@ -787,13 +796,13 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -해결 순서: DM별 재정의 → provider 기본값 → 제한 없음(모두 유지). +해석 순서: DM별 재정의 → 공급자 기본값 → 제한 없음(모두 유지). 지원 대상: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### 셀프 채팅 모드 -자신의 번호를 `allowFrom`에 포함하면 셀프 채팅 모드가 활성화됩니다(네이티브 @-멘션은 무시하고 텍스트 패턴에만 응답). +자기 번호를 `allowFrom`에 포함해 셀프 채팅 모드를 활성화합니다(네이티브 @-멘션은 무시하고, 텍스트 패턴에만 응답함): ```json5 { @@ -819,13 +828,19 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. ```json5 { commands: { - native: "auto", // 지원되는 경우 네이티브 명령 등록 - text: true, // 채팅 메시지에서 /commands 파싱 + native: "auto", // 지원될 때 네이티브 명령 등록 + nativeSkills: "auto", // 지원될 때 네이티브 skill 명령 등록 + text: true, // 채팅 메시지에서 /commands 구문 분석 bash: false, // ! 허용(별칭: /bash) bashForegroundMs: 2000, config: false, // /config 허용 + mcp: false, // /mcp 허용 + plugins: false, // /plugins 허용 debug: false, // /debug 허용 - restart: false, // /restart + gateway 재시작 도구 허용 + restart: true, // /restart + gateway 재시작 tool 허용 + ownerAllowFrom: ["discord:123456789012345678"], + ownerDisplay: "raw", // raw | hash + ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -835,24 +850,40 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. } ``` - + -- 텍스트 명령은 앞에 `/`가 있는 **독립 실행형** 메시지여야 합니다. -- `native: "auto"`는 Discord/Telegram의 네이티브 명령을 켜고, Slack은 끈 상태로 둡니다. -- 채널별 재정의: `channels.discord.commands.native` (bool 또는 `"auto"`). `false`는 이전에 등록된 명령을 제거합니다. -- `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`는 일반 write 범위 operator 클라이언트에서도 계속 사용할 수 있습니다. -- `channels..configWrites`는 채널별 config 변경을 제어합니다(기본값: true). -- 멀티 계정 채널에서는 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`)를 제어합니다. -- `allowFrom`은 provider별입니다. 설정하면 이것이 **유일한** 권한 부여 source가 됩니다(채널 allowlist/페어링과 `useAccessGroups`는 무시됨). -- `useAccessGroups: false`는 `allowFrom`이 설정되지 않은 경우 명령이 access-group 정책을 우회할 수 있게 합니다. +- 이 블록은 명령 표면을 구성합니다. 현재 내장 + 번들 명령 카탈로그는 [Slash Commands](/ko/tools/slash-commands)를 참고하세요. +- 이 페이지는 전체 명령 카탈로그가 아니라 **구성 키 참조**입니다. QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone`, Talk `/voice`와 같은 채널/플러그인 소유 명령은 해당 채널/플러그인 페이지와 [Slash Commands](/ko/tools/slash-commands)에 문서화되어 있습니다. +- 텍스트 명령은 선행 `/`가 있는 **독립 실행형** 메시지여야 합니다. +- `native: "auto"`는 Discord/Telegram에서 네이티브 명령을 켜고, Slack에서는 끕니다. +- `nativeSkills: "auto"`는 Discord/Telegram에서 네이티브 skill 명령을 켜고, Slack에서는 끕니다. +- 채널별 재정의: `channels.discord.commands.native`(bool 또는 `"auto"`). `false`는 이전에 등록된 명령을 지웁니다. +- 네이티브 skill 등록은 `channels..commands.nativeSkills`로 채널별 재정의할 수 있습니다. +- `channels.telegram.customCommands`는 추가 Telegram 봇 메뉴 항목을 추가합니다. +- `bash: true`는 호스트 셸용 `! `를 활성화합니다. `tools.elevated.enabled`가 필요하며 발신자가 `tools.elevated.allowFrom.`에 있어야 합니다. +- `config: true`는 `/config`를 활성화합니다(`openclaw.json` 읽기/쓰기). gateway `chat.send` 클라이언트의 경우, 영구 `/config set|unset` 쓰기에는 `operator.admin`도 필요하며, 읽기 전용 `/config show`는 일반 쓰기 범위 operator 클라이언트에도 계속 제공됩니다. +- `mcp: true`는 `mcp.servers` 아래 OpenClaw 관리 MCP 서버 구성을 위한 `/mcp`를 활성화합니다. +- `plugins: true`는 플러그인 검색, 설치, 활성화/비활성화 제어를 위한 `/plugins`를 활성화합니다. +- `channels..configWrites`는 채널별 구성 변경을 제어합니다(기본값: true). +- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`)를 제어합니다. +- `restart: false`는 `/restart`와 gateway 재시작 tool 작업을 비활성화합니다. 기본값: `true`. +- `ownerAllowFrom`은 소유자 전용 명령/tool을 위한 명시적 소유자 허용 목록입니다. `allowFrom`과는 별개입니다. +- `ownerDisplay: "hash"`는 시스템 프롬프트에서 소유자 ID를 해시합니다. 해싱을 제어하려면 `ownerDisplaySecret`을 설정하세요. +- `allowFrom`은 공급자별입니다. 설정되면 이것이 **유일한** 권한 부여 소스가 됩니다(채널 허용 목록/페어링 및 `useAccessGroups`는 무시됨). +- `useAccessGroups: false`는 `allowFrom`이 설정되지 않았을 때 명령이 액세스 그룹 정책을 우회하도록 허용합니다. +- 명령 문서 맵: + - 내장 + 번들 카탈로그: [Slash Commands](/ko/tools/slash-commands) + - 채널별 명령 표면: [Channels](/ko/channels) + - QQ Bot 명령: [QQ Bot](/ko/channels/qqbot) + - 페어링 명령: [Pairing](/ko/channels/pairing) + - LINE 카드 명령: [LINE](/ko/channels/line) + - memory dreaming: [Dreaming](/ko/concepts/dreaming) --- -## Agent 기본값 +## 에이전트 기본값 ### `agents.defaults.workspace` @@ -866,7 +897,7 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. ### `agents.defaults.repoRoot` -선택적 저장소 루트로, system prompt의 Runtime 줄에 표시됩니다. 설정하지 않으면 OpenClaw가 workspace에서 위로 올라가며 자동 탐지합니다. +시스템 프롬프트의 Runtime 줄에 표시되는 선택적 리포지토리 루트입니다. 설정되지 않으면 OpenClaw가 workspace에서 위쪽으로 이동하며 자동 감지합니다. ```json5 { @@ -876,7 +907,7 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. ### `agents.defaults.skills` -`agents.list[].skills`를 설정하지 않은 agent에 대한 선택적 기본 Skills allowlist입니다. +`agents.list[].skills`를 설정하지 않은 에이전트를 위한 선택적 기본 skill 허용 목록입니다. ```json5 { @@ -885,17 +916,16 @@ IRC는 extension 기반이며 `channels.irc` 아래에 구성됩니다. list: [ { id: "writer" }, // github, weather 상속 { id: "docs", skills: ["docs-search"] }, // 기본값 대체 - { id: "locked-down", skills: [] }, // Skills 없음 + { id: "locked-down", skills: [] }, // skill 없음 ], }, } ``` -- 기본적으로 Skills 제한 없이 사용하려면 `agents.defaults.skills`를 생략하세요. +- 기본적으로 제한 없는 skill을 원하면 `agents.defaults.skills`를 생략하세요. - 기본값을 상속하려면 `agents.list[].skills`를 생략하세요. -- Skills가 없게 하려면 `agents.list[].skills: []`로 설정하세요. -- 비어 있지 않은 `agents.list[].skills` 목록은 해당 agent의 최종 집합이며, - 기본값과 병합되지 않습니다. +- skill이 없게 하려면 `agents.list[].skills: []`를 설정하세요. +- 비어 있지 않은 `agents.list[].skills` 목록은 해당 에이전트의 최종 집합이며, 기본값과 병합되지 않습니다. ### `agents.defaults.skipBootstrap` @@ -909,9 +939,9 @@ workspace bootstrap 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `U ### `agents.defaults.contextInjection` -workspace bootstrap 파일을 system prompt에 주입하는 시점을 제어합니다. 기본값은 `"always"`입니다. +workspace bootstrap 파일이 시스템 프롬프트에 삽입되는 시점을 제어합니다. 기본값은 `"always"`입니다. -- `"continuation-skip"`: 안전한 이어가기 턴(assistant 응답 완료 후)에서는 workspace bootstrap 재주입을 건너뛰어 prompt 크기를 줄입니다. Heartbeat 실행과 compaction 후 재시도는 여전히 컨텍스트를 다시 구성합니다. +- `"continuation-skip"`: 안전한 연속 턴(완료된 assistant 응답 이후)에서는 workspace bootstrap 재삽입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행과 compaction 이후 재시도는 여전히 컨텍스트를 다시 빌드합니다. ```json5 { @@ -921,7 +951,7 @@ workspace bootstrap 파일을 system prompt에 주입하는 시점을 제어합 ### `agents.defaults.bootstrapMaxChars` -잘리기 전 각 workspace bootstrap 파일의 최대 문자 수입니다. 기본값: `20000`. +잘리기 전 workspace bootstrap 파일당 최대 문자 수입니다. 기본값: `20000`. ```json5 { @@ -931,7 +961,7 @@ workspace bootstrap 파일을 system prompt에 주입하는 시점을 제어합 ### `agents.defaults.bootstrapTotalMaxChars` -모든 workspace bootstrap 파일에 걸쳐 주입되는 총 최대 문자 수입니다. 기본값: `150000`. +모든 workspace bootstrap 파일에 걸쳐 삽입되는 총 최대 문자 수입니다. 기본값: `150000`. ```json5 { @@ -941,12 +971,12 @@ workspace bootstrap 파일을 system prompt에 주입하는 시점을 제어합 ### `agents.defaults.bootstrapPromptTruncationWarning` -bootstrap 컨텍스트가 잘렸을 때 agent에 보이는 경고 텍스트를 제어합니다. +bootstrap 컨텍스트가 잘렸을 때 에이전트에게 보이는 경고 텍스트를 제어합니다. 기본값: `"once"`. -- `"off"`: system prompt에 경고 텍스트를 절대 주입하지 않습니다. -- `"once"`: 고유한 잘림 시그니처마다 한 번만 경고를 주입합니다(권장). -- `"always"`: 잘림이 존재하는 모든 실행에서 경고를 주입합니다. +- `"off"`: 시스템 프롬프트에 경고 텍스트를 절대 삽입하지 않습니다. +- `"once"`: 고유한 잘림 시그니처당 한 번 경고를 삽입합니다(권장). +- `"always"`: 잘림이 존재하면 매 실행마다 경고를 삽입합니다. ```json5 { @@ -956,10 +986,10 @@ bootstrap 컨텍스트가 잘렸을 때 agent에 보이는 경고 텍스트를 ### `agents.defaults.imageMaxDimensionPx` -provider 호출 전 transcript/tool 이미지 블록에서 가장 긴 이미지 변의 최대 픽셀 크기입니다. +공급자 호출 전에 대화 기록/tool 이미지 블록에서 가장 긴 이미지 변의 최대 픽셀 크기입니다. 기본값: `1200`. -값을 낮추면 일반적으로 vision 토큰 사용량과 요청 페이로드 크기가 줄어들고, 특히 스크린샷이 많은 실행에 유리합니다. +값을 낮추면 일반적으로 스크린샷이 많은 실행에서 vision 토큰 사용량과 요청 페이로드 크기가 줄어듭니다. 값을 높이면 더 많은 시각적 디테일이 보존됩니다. ```json5 @@ -970,7 +1000,7 @@ provider 호출 전 transcript/tool 이미지 블록에서 가장 긴 이미지 ### `agents.defaults.userTimezone` -system prompt 컨텍스트용 시간대입니다(메시지 타임스탬프에는 적용되지 않음). 호스트 시간대를 대체값으로 사용합니다. +시스템 프롬프트 컨텍스트용 시간대입니다(메시지 타임스탬프용 아님). 호스트 시간대를 대체값으로 사용합니다. ```json5 { @@ -980,7 +1010,7 @@ system prompt 컨텍스트용 시간대입니다(메시지 타임스탬프에는 ### `agents.defaults.timeFormat` -system prompt의 시간 형식입니다. 기본값: `auto`(OS 환경설정). +시스템 프롬프트의 시간 형식입니다. 기본값: `auto`(OS 환경설정). ```json5 { @@ -1035,41 +1065,41 @@ system prompt의 시간 형식입니다. 기본값: `auto`(OS 환경설정). - `model`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - 문자열 형식은 primary 모델만 설정합니다. - - 객체 형식은 primary와 정렬된 failover 모델을 함께 설정합니다. + - 객체 형식은 primary와 순서가 있는 failover 모델을 설정합니다. - `imageModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - `image` 도구 경로에서 vision-model config로 사용됩니다. + - `image` tool 경로의 vision 모델 구성으로 사용됩니다. - 선택된/기본 모델이 이미지 입력을 받을 수 없을 때 대체 라우팅에도 사용됩니다. - `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`. - - 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 순서대로 시도합니다. + - 공유 이미지 생성 기능과 이미지를 생성하는 향후 tool/플러그인 표면에서 사용됩니다. + - 일반적인 값: 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 ID 순으로 나머지 등록된 이미지 생성 provider를 시도합니다. - `musicGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 음악 생성 기능과 내장 `music_generate` 도구에서 사용됩니다. - - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, `minimax/music-2.5+`. - - 생략해도 `music_generate`는 인증이 있는 provider 기본값을 추론할 수 있습니다. 현재 기본 provider를 먼저 시도한 뒤, 남은 등록된 음악 생성 provider를 provider-id 순서대로 시도합니다. - - provider/model을 직접 선택하면 해당 provider 인증/API 키도 구성하세요. + - 공유 음악 생성 기능과 내장 `music_generate` tool에서 사용됩니다. + - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, 또는 `minimax/music-2.5+`. + - 생략해도 `music_generate`는 인증이 설정된 provider 기본값을 추론할 수 있습니다. 먼저 현재 기본 provider를 시도하고, 그다음 provider ID 순으로 나머지 등록된 음악 생성 provider를 시도합니다. + - provider/model을 직접 선택하면 일치하는 provider 인증/API 키도 구성하세요. - `videoGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받을 수 있습니다. - - 공유 비디오 생성 기능과 내장 `video_generate` 도구에서 사용됩니다. - - 일반적인 값: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, `qwen/wan2.7-r2v`. - - 생략해도 `video_generate`는 인증이 있는 provider 기본값을 추론할 수 있습니다. 현재 기본 provider를 먼저 시도한 뒤, 남은 등록된 비디오 생성 provider를 provider-id 순서대로 시도합니다. - - provider/model을 직접 선택하면 해당 provider 인증/API 키도 구성하세요. - - 번들 Qwen 비디오 생성 provider는 현재 최대 1개의 출력 비디오, 1개의 입력 이미지, 4개의 입력 비디오, 10초 길이, 그리고 provider 수준 `size`, `aspectRatio`, `resolution`, `audio`, `watermark` 옵션을 지원합니다. + - 공유 비디오 생성 기능과 내장 `video_generate` tool에서 사용됩니다. + - 일반적인 값: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, 또는 `qwen/wan2.7-r2v`. + - 생략해도 `video_generate`는 인증이 설정된 provider 기본값을 추론할 수 있습니다. 먼저 현재 기본 provider를 시도하고, 그다음 provider ID 순으로 나머지 등록된 비디오 생성 provider를 시도합니다. + - 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 크기 제한입니다. -- `pdfMaxPages`: `pdf` 도구의 추출 대체 모드에서 고려하는 기본 최대 페이지 수입니다. -- `verboseDefault`: agent의 기본 verbose 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. -- `elevatedDefault`: agent의 기본 elevated-output 수준입니다. 값: `"off"`, `"on"`, `"ask"`, `"full"`. 기본값: `"on"`. -- `model.primary`: 형식은 `provider/model`입니다(예: `openai/gpt-5.4`). provider를 생략하면 OpenClaw는 먼저 별칭을, 다음으로 정확한 모델 ID에 대한 고유한 구성된 provider 일치를, 마지막으로 구성된 기본 provider를 시도합니다(더 이상 권장되지 않는 호환 동작이므로 명시적 `provider/model`을 권장). 해당 provider가 더 이상 구성된 기본 모델을 노출하지 않으면, OpenClaw는 오래된 제거된 provider 기본값을 그대로 드러내는 대신 첫 번째 구성된 provider/model로 대체합니다. -- `models`: `/model`용 구성된 모델 카탈로그 및 allowlist입니다. 각 항목에는 `alias`(단축 이름)와 `params`(provider별 설정, 예: `temperature`, `maxTokens`, `cacheRetention`, `context1m`)를 포함할 수 있습니다. -- `params`: 모든 모델에 적용되는 전역 기본 provider 매개변수입니다. `agents.defaults.params`에 설정합니다(예: `{ cacheRetention: "long" }`). -- `params` 병합 우선순위(config): `agents.defaults.params`(전역 기반) 위에 `agents.defaults.models["provider/model"].params`(모델별), 그 위에 `agents.list[].params`(일치하는 agent id)가 키별로 덮어씁니다. 자세한 내용은 [Prompt Caching](/ko/reference/prompt-caching)을 참고하세요. -- 이 필드를 변경하는 config writer(예: `/models set`, `/models set-image`, fallback 추가/제거 명령)는 가능한 경우 정규 객체 형식으로 저장하고 기존 fallback 목록을 유지합니다. -- `maxConcurrent`: 세션 전반에서 병렬 agent 실행의 최대 수입니다(각 세션은 여전히 직렬화됨). 기본값: 4. + - `pdf` tool의 모델 라우팅에 사용됩니다. + - 생략하면 PDF tool은 `imageModel`, 그다음 해석된 세션/기본 모델로 대체됩니다. +- `pdfMaxBytesMb`: 호출 시점에 `maxBytesMb`가 전달되지 않았을 때 `pdf` tool의 기본 PDF 크기 제한입니다. +- `pdfMaxPages`: `pdf` tool의 추출 대체 모드에서 고려하는 기본 최대 페이지 수입니다. +- `verboseDefault`: 에이전트의 기본 verbose 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. +- `elevatedDefault`: 에이전트의 기본 elevated-output 수준입니다. 값: `"off"`, `"on"`, `"ask"`, `"full"`. 기본값: `"on"`. +- `model.primary`: 형식은 `provider/model`(예: `openai/gpt-5.4`)입니다. provider를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 정확히 그 모델 ID에 대해 고유하게 구성된 provider 일치를 찾으며, 그 후에야 구성된 기본 provider로 대체됩니다(더 이상 권장되지 않는 호환 동작이므로 명시적 `provider/model`을 권장). 해당 provider가 더 이상 구성된 기본 모델을 노출하지 않으면, OpenClaw는 오래된 제거된 provider 기본값을 표시하는 대신 첫 번째 구성된 provider/model으로 대체됩니다. +- `models`: `/model`용 구성된 모델 카탈로그 및 허용 목록입니다. 각 항목은 `alias`(단축키)와 `params`(예: `temperature`, `maxTokens`, `cacheRetention`, `context1m` 같은 provider별 값)를 포함할 수 있습니다. +- `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)을 참고하세요. +- 이러한 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, fallback 추가/제거 명령)는 정규 객체 형식으로 저장하고 가능하면 기존 fallback 목록을 보존합니다. +- `maxConcurrent`: 세션 전반에서 병렬 에이전트 실행의 최대 수입니다(각 세션은 여전히 직렬화됨). 기본값: 4. -**내장 별칭 shorthand** (`agents.defaults.models`에 모델이 있을 때만 적용): +**내장 별칭 단축키** (`agents.defaults.models`에 모델이 있을 때만 적용): | 별칭 | 모델 | | ------------------- | -------------------------------------- | @@ -1084,13 +1114,13 @@ system prompt의 시간 형식입니다. 기본값: `auto`(OS 환경설정). 구성한 별칭은 항상 기본값보다 우선합니다. -Z.AI GLM-4.x 모델은 `--thinking off`를 설정하거나 `agents.defaults.models["zai/"].params.thinking`을 직접 정의하지 않는 한 자동으로 thinking 모드를 활성화합니다. -Z.AI 모델은 도구 호출 스트리밍을 위해 기본적으로 `tool_stream`을 활성화합니다. 비활성화하려면 `agents.defaults.models["zai/"].params.tool_stream`을 `false`로 설정하세요. -Anthropic Claude 4.6 모델은 명시적 thinking 수준이 없을 때 기본적으로 `adaptive` thinking을 사용합니다. +Z.AI GLM-4.x 모델은 `--thinking off`를 설정하거나 `agents.defaults.models["zai/"].params.thinking`을 직접 정의하지 않는 한 thinking 모드를 자동으로 활성화합니다. +Z.AI 모델은 기본적으로 tool 호출 스트리밍을 위해 `tool_stream`을 활성화합니다. 비활성화하려면 `agents.defaults.models["zai/"].params.tool_stream`을 `false`로 설정하세요. +Anthropic Claude 4.6 모델은 명시적 thinking 수준이 설정되지 않았을 때 기본적으로 `adaptive` thinking을 사용합니다. ### `agents.defaults.cliBackends` -도구 호출이 없는 텍스트 전용 fallback 실행용 선택적 CLI backend입니다. API provider 실패 시 백업으로 유용합니다. +텍스트 전용 대체 실행(도구 호출 없음)을 위한 선택적 CLI 백엔드입니다. API provider가 실패할 때 백업으로 유용합니다. ```json5 { @@ -1118,9 +1148,9 @@ Anthropic Claude 4.6 모델은 명시적 thinking 수준이 없을 때 기본적 } ``` -- CLI backend는 텍스트 우선이며, 도구는 항상 비활성화됩니다. -- `sessionArg`가 설정된 경우 세션을 지원합니다. -- `imageArg`가 파일 경로를 받을 수 있으면 이미지 전달을 지원합니다. +- CLI 백엔드는 텍스트 우선이며, 도구는 항상 비활성화됩니다. +- `sessionArg`가 설정되면 세션이 지원됩니다. +- `imageArg`가 파일 경로를 받을 수 있으면 이미지 전달이 지원됩니다. ### `agents.defaults.heartbeat` @@ -1131,16 +1161,16 @@ Anthropic Claude 4.6 모델은 명시적 thinking 수준이 없을 때 기본적 agents: { defaults: { heartbeat: { - every: "30m", // 0m이면 비활성화 + every: "30m", // 0m은 비활성화 model: "openai/gpt-5.4-mini", includeReasoning: false, lightContext: false, // 기본값: false; true이면 workspace bootstrap 파일 중 HEARTBEAT.md만 유지 - isolatedSession: false, // 기본값: false; true이면 각 heartbeat를 새 세션(대화 기록 없음)에서 실행 + isolatedSession: false, // 기본값: false; true이면 각 heartbeat를 새 세션에서 실행(대화 기록 없음) session: "main", to: "+15555550123", directPolicy: "allow", // allow (기본값) | block target: "none", // 기본값: none | 옵션: last | whatsapp | telegram | discord | ... - prompt: "Read HEARTBEAT.md if it exists...", + prompt: "HEARTBEAT.md가 있으면 읽으세요...", ackMaxChars: 300, suppressToolErrorWarnings: false, }, @@ -1149,13 +1179,13 @@ Anthropic Claude 4.6 모델은 명시적 thinking 수준이 없을 때 기본적 } ``` -- `every`: 기간 문자열(ms/s/m/h). 기본값: API-key 인증은 `30m`, OAuth 인증은 `1h`. 비활성화하려면 `0m`으로 설정하세요. -- `suppressToolErrorWarnings`: true이면 heartbeat 실행 중 도구 오류 경고 payload를 숨깁니다. -- `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로 줄입니다. -- agent별: `agents.list[].heartbeat`를 설정하세요. 어떤 agent라도 `heartbeat`를 정의하면 **그 agent들만** heartbeat를 실행합니다. -- heartbeat는 전체 agent 턴을 실행하므로, 간격이 짧을수록 더 많은 토큰을 사용합니다. +- `every`: 기간 문자열(ms/s/m/h). 기본값: `30m`(API 키 인증) 또는 `1h`(OAuth 인증). 비활성화하려면 `0m`으로 설정하세요. +- `suppressToolErrorWarnings`: true일 때 heartbeat 실행 중 tool 오류 경고 페이로드를 억제합니다. +- `directPolicy`: 직접/DM 전달 정책입니다. `allow`(기본값)는 직접 대상 전달을 허용합니다. `block`은 직접 대상 전달을 억제하고 `reason=dm-blocked`를 출력합니다. +- `lightContext`: true일 때 heartbeat 실행은 경량 bootstrap 컨텍스트를 사용하며 workspace bootstrap 파일 중 `HEARTBEAT.md`만 유지합니다. +- `isolatedSession`: true일 때 각 heartbeat는 이전 대화 기록 없이 새 세션에서 실행됩니다. cron `sessionTarget: "isolated"`와 동일한 격리 패턴입니다. heartbeat당 토큰 비용을 약 100K에서 약 2-5K 토큰으로 줄입니다. +- 에이전트별: `agents.list[].heartbeat`를 설정하세요. 어떤 에이전트든 `heartbeat`를 정의하면 heartbeat는 **해당 에이전트들만** 실행됩니다. +- Heartbeat는 전체 에이전트 턴을 실행하므로, 간격이 짧을수록 더 많은 토큰을 사용합니다. ### `agents.defaults.compaction` @@ -1169,15 +1199,15 @@ Anthropic Claude 4.6 모델은 명시적 thinking 수준이 없을 때 기본적 timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // identifierPolicy=custom일 때 사용 - postCompactionSections: ["Session Startup", "Red Lines"], // []이면 재주입 비활성화 + identifierInstructions: "배포 ID, 티켓 ID, host:port 쌍을 정확히 보존하세요.", // identifierPolicy=custom일 때 사용 + postCompactionSections: ["Session Startup", "Red Lines"], // []는 재삽입 비활성화 model: "openrouter/anthropic/claude-sonnet-4-6", // 선택적 compaction 전용 모델 재정의 notifyUser: true, // compaction 시작 시 짧은 알림 전송(기본값: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "세션이 compaction에 가까워지고 있습니다. 오래 유지할 기억을 지금 저장하세요.", + prompt: "지속될 메모가 있으면 memory/YYYY-MM-DD.md에 작성하고, 저장할 것이 없으면 정확한 무음 토큰 NO_REPLY로 답하세요.", }, }, }, @@ -1185,19 +1215,19 @@ Anthropic Claude 4.6 모델은 명시적 thinking 수준이 없을 때 기본적 } ``` -- `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"]`이며, 비활성화하려면 `[]`로 설정하세요. 설정하지 않았거나 명시적으로 이 기본 쌍을 사용하면, 레거시 fallback으로 이전 `Every Session`/`Safety` 제목도 허용됩니다. -- `model`: compaction 요약에만 사용하는 선택적 `provider/model-id` 재정의입니다. 메인 세션은 하나의 모델을 유지하되 compaction 요약은 다른 모델에서 실행하고 싶을 때 사용하세요. 설정하지 않으면 compaction은 세션의 primary 모델을 사용합니다. -- `notifyUser`: `true`이면 compaction 시작 시 사용자에게 짧은 알림을 보냅니다(예: "Compacting context..."). 기본적으로는 조용히 실행되도록 비활성화되어 있습니다. -- `memoryFlush`: 자동 compaction 전에 내구성 있는 memory를 저장하는 조용한 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은 세션의 primary 모델을 사용합니다. +- `notifyUser`: `true`일 때 compaction이 시작되면 사용자에게 짧은 알림(예: "컨텍스트를 압축하는 중...")을 보냅니다. 기본적으로는 compaction을 조용히 유지하기 위해 비활성화되어 있습니다. +- `memoryFlush`: 자동 compaction 전에 지속될 메모리를 저장하기 위한 무음 agentic 턴입니다. workspace가 읽기 전용이면 건너뜁니다. ### `agents.defaults.contextPruning` -LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결과**를 정리합니다. 디스크의 세션 기록은 수정하지 않습니다. +LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 tool 결과**를 가지치기합니다. 디스크의 세션 기록은 **수정하지 않습니다**. ```json5 { @@ -1211,7 +1241,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: "[이전 tool 결과 내용이 지워졌습니다]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1221,23 +1251,23 @@ LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 -- `mode: "cache-ttl"`은 pruning 패스를 활성화합니다. -- `ttl`은 마지막 cache touch 이후 pruning을 다시 실행할 수 있는 주기를 제어합니다. -- Pruning은 먼저 너무 큰 도구 결과를 soft-trim하고, 필요 시 더 오래된 도구 결과를 hard-clear합니다. +- `mode: "cache-ttl"`는 가지치기 패스를 활성화합니다. +- `ttl`은 마지막 캐시 터치 이후 다시 가지치기를 실행할 수 있는 빈도를 제어합니다. +- 가지치기는 먼저 과도하게 큰 tool 결과를 soft-trim하고, 필요하면 더 오래된 tool 결과를 hard-clear합니다. -**Soft-trim**은 시작 + 끝 부분을 유지하고 중간에 `...`를 삽입합니다. +**Soft-trim**은 시작과 끝을 유지하고 가운데에 `...`를 삽입합니다. -**Hard-clear**는 전체 도구 결과를 placeholder로 대체합니다. +**Hard-clear**는 전체 tool 결과를 placeholder로 교체합니다. 참고: -- 이미지 블록은 절대 trim/clear되지 않습니다. -- 비율은 정확한 토큰 수가 아니라 문자 수 기준(대략적)입니다. -- `keepLastAssistants`보다 적은 assistant 메시지만 있으면 pruning은 건너뜁니다. +- 이미지 블록은 절대 잘리거나 지워지지 않습니다. +- 비율은 토큰 수가 아니라 문자 수 기준의 근사값입니다. +- `keepLastAssistants`보다 적은 assistant 메시지만 존재하면 가지치기를 건너뜁니다. -동작 세부 사항은 [Session Pruning](/ko/concepts/session-pruning)을 참고하세요. +동작 세부 정보는 [Session Pruning](/ko/concepts/session-pruning)을 참고하세요. ### 블록 스트리밍 @@ -1255,13 +1285,13 @@ LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 } ``` -- Telegram이 아닌 채널은 블록 답변을 활성화하려면 명시적으로 `*.blockStreaming: true`가 필요합니다. -- 채널 재정의: `channels..blockStreamingCoalesce`(및 계정별 변형). Signal/Slack/Discord/Google Chat의 기본값은 `minChars: 1500`입니다. -- `humanDelay`: 블록 답변 사이의 무작위 지연입니다. `natural` = 800–2500ms. agent별 재정의: `agents.list[].humanDelay`. +- Telegram이 아닌 채널은 블록 답글을 활성화하려면 명시적인 `*.blockStreaming: true`가 필요합니다. +- 채널 재정의: `channels..blockStreamingCoalesce`(및 계정별 변형). Signal/Slack/Discord/Google Chat은 기본값으로 `minChars: 1500`을 사용합니다. +- `humanDelay`: 블록 답글 사이의 무작위 지연입니다. `natural` = 800–2500ms. 에이전트별 재정의: `agents.list[].humanDelay`. 동작 및 청크 세부 사항은 [Streaming](/ko/concepts/streaming)을 참고하세요. -### 타이핑 표시기 +### 입력 중 표시기 ```json5 { @@ -1274,7 +1304,7 @@ LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 } ``` -- 기본값: 직접 채팅/멘션은 `instant`, 멘션되지 않은 그룹 채팅은 `message`. +- 기본값: 직접 채팅/멘션에는 `instant`, 멘션 없는 그룹 채팅에는 `message`. - 세션별 재정의: `session.typingMode`, `session.typingIntervalSeconds`. [Typing Indicators](/ko/concepts/typing-indicators)를 참고하세요. @@ -1283,7 +1313,7 @@ LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 ### `agents.defaults.sandbox` -내장 agent를 위한 선택적 sandboxing입니다. 전체 가이드는 [Sandboxing](/ko/gateway/sandboxing)을 참고하세요. +임베디드 에이전트용 선택적 sandboxing입니다. 전체 가이드는 [Sandboxing](/ko/gateway/sandboxing)을 참고하세요. ```json5 { @@ -1378,54 +1408,53 @@ LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 } ``` - + -**Backend:** +**백엔드:** - `docker`: 로컬 Docker 런타임(기본값) -- `ssh`: 범용 SSH 기반 원격 런타임 +- `ssh`: 일반 SSH 기반 원격 런타임 - `openshell`: OpenShell 런타임 -`backend: "openshell"`을 선택하면 런타임별 설정은 -`plugins.entries.openshell.config`로 이동합니다. +`backend: "openshell"`을 선택하면 런타임별 설정은 `plugins.entries.openshell.config`로 이동합니다. -**SSH backend config:** +**SSH 백엔드 구성:** - `target`: `user@host[:port]` 형식의 SSH 대상 - `command`: SSH 클라이언트 명령(기본값: `ssh`) -- `workspaceRoot`: 스코프별 workspace에 사용하는 절대 원격 루트 +- `workspaceRoot`: 범위별 workspace에 사용되는 절대 원격 루트 - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH에 전달되는 기존 로컬 파일 -- `identityData` / `certificateData` / `knownHostsData`: OpenClaw가 런타임에 임시 파일로 물질화하는 인라인 내용 또는 SecretRef -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH host-key 정책 관련 설정 +- `identityData` / `certificateData` / `knownHostsData`: OpenClaw가 런타임에 임시 파일로 구체화하는 인라인 내용 또는 SecretRef +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH host-key 정책 노브 **SSH 인증 우선순위:** -- `identityData`가 `identityFile`보다 우선 -- `certificateData`가 `certificateFile`보다 우선 -- `knownHostsData`가 `knownHostsFile`보다 우선 -- SecretRef 기반 `*Data` 값은 sandbox 세션 시작 전에 활성 secrets 런타임 스냅샷에서 해석됩니다 +- `identityData`가 `identityFile`보다 우선합니다 +- `certificateData`가 `certificateFile`보다 우선합니다 +- `knownHostsData`가 `knownHostsFile`보다 우선합니다 +- SecretRef 기반 `*Data` 값은 sandbox 세션 시작 전에 활성 비밀 런타임 스냅샷에서 해석됩니다 -**SSH backend 동작:** +**SSH 백엔드 동작:** -- 생성 또는 재생성 후 원격 workspace를 한 번 시드함 -- 그다음 원격 SSH workspace를 canonical 상태로 유지함 -- `exec`, 파일 도구, media 경로를 SSH를 통해 라우팅함 -- 원격 변경 내용을 호스트로 자동 동기화하지 않음 -- sandbox browser 컨테이너는 지원하지 않음 +- 생성 또는 재생성 후 원격 workspace를 한 번 시드합니다 +- 그 후 원격 SSH workspace를 정규 상태로 유지합니다 +- `exec`, 파일 tool, media 경로를 SSH를 통해 라우팅합니다 +- 원격 변경 내용을 호스트로 자동 동기화하지 않습니다 +- sandbox browser 컨테이너는 지원하지 않습니다 -**Workspace 접근:** +**Workspace 액세스:** -- `none`: `~/.openclaw/sandboxes` 아래 스코프별 sandbox workspace -- `ro`: `/workspace`에 sandbox workspace, `/agent`에 agent workspace를 읽기 전용으로 마운트 -- `rw`: `/workspace`에 agent workspace를 읽기/쓰기 마운트 +- `none`: `~/.openclaw/sandboxes` 아래 범위별 sandbox workspace +- `ro`: `/workspace`의 sandbox workspace, `/agent`에 읽기 전용으로 마운트된 agent workspace +- `rw`: agent workspace를 `/workspace`에 읽기/쓰기 가능하게 마운트 -**Scope:** +**범위:** - `session`: 세션별 컨테이너 + workspace -- `agent`: agent별 컨테이너 + workspace 1개(기본값) -- `shared`: 공유 컨테이너 및 workspace(세션 간 격리 없음) +- `agent`: 에이전트별 하나의 컨테이너 + workspace(기본값) +- `shared`: 공유 컨테이너와 workspace(세션 간 격리 없음) -**OpenShell plugin config:** +**OpenShell 플러그인 구성:** ```json5 { @@ -1440,7 +1469,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, @@ -1453,30 +1482,30 @@ LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 **OpenShell 모드:** -- `mirror`: exec 전 로컬에서 원격으로 시드하고, exec 후 다시 동기화; 로컬 workspace가 canonical 상태로 유지됨 -- `remote`: sandbox 생성 시 한 번만 원격으로 시드하고, 그 후 원격 workspace를 canonical 상태로 유지함 +- `mirror`: exec 전에 로컬에서 원격으로 시드하고, exec 후 다시 동기화; 로컬 workspace가 정규 상태를 유지 +- `remote`: sandbox 생성 시 한 번 원격으로 시드한 뒤, 원격 workspace를 정규 상태로 유지 -`remote` 모드에서는 OpenClaw 외부에서 호스트 로컬에 가해진 편집 내용이 시드 단계 이후 sandbox로 자동 동기화되지 않습니다. -전송은 OpenShell sandbox로의 SSH를 사용하지만, sandbox lifecycle과 선택적 mirror sync는 plugin이 소유합니다. +`remote` 모드에서는 OpenClaw 외부에서 호스트 로컬에 가해진 편집은 시드 단계 이후 sandbox로 자동 동기화되지 않습니다. +전송은 OpenShell sandbox로의 SSH이지만, 플러그인이 sandbox 생명주기와 선택적 미러 동기화를 소유합니다. -**`setupCommand`**는 컨테이너 생성 후 한 번만 실행됩니다(`sh -lc` 사용). 네트워크 egress, 쓰기 가능한 루트, 루트 사용자 권한이 필요합니다. +**`setupCommand`**는 컨테이너 생성 후 한 번 실행됩니다(`sh -lc`를 통해). 네트워크 송신, 쓰기 가능한 루트, root 사용자가 필요합니다. -**컨테이너 기본값은 `network: "none"`**이며, agent에 아웃바운드 접근이 필요하면 `"bridge"`(또는 사용자 지정 bridge 네트워크)로 설정하세요. -`"host"`는 차단됩니다. `"container:"`는 기본적으로 차단되며, 명시적으로 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`를 설정한 경우에만 허용됩니다(break-glass). +**컨테이너 기본값은 `network: "none"`**입니다 — 에이전트에 아웃바운드 액세스가 필요하면 `"bridge"`(또는 사용자 지정 bridge 네트워크)로 설정하세요. +`"host"`는 차단됩니다. `"container:"`는 기본적으로 차단되며, +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`를 명시적으로 설정한 경우에만 허용됩니다(비상용). -**인바운드 첨부 파일**은 활성 workspace의 `media/inbound/*`에 staging됩니다. +**수신 첨부 파일**은 활성 workspace의 `media/inbound/*`에 스테이징됩니다. -**`docker.binds`**는 추가 호스트 디렉터리를 마운트하며, 전역 및 agent별 bind는 병합됩니다. +**`docker.binds`**는 추가 호스트 디렉터리를 마운트합니다. 전역 및 에이전트별 bind는 병합됩니다. -**Sandboxed browser** (`sandbox.browser.enabled`): 컨테이너의 Chromium + CDP입니다. noVNC URL이 system prompt에 주입됩니다. `openclaw.json`에서 `browser.enabled`가 필요하지 않습니다. -noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 짧은 수명의 토큰 URL을 발급합니다. +**Sandboxed browser** (`sandbox.browser.enabled`): 컨테이너의 Chromium + CDP. noVNC URL이 시스템 프롬프트에 삽입됩니다. `openclaw.json`에서 `browser.enabled`가 필요하지 않습니다. +noVNC 관찰자 액세스는 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 짧은 수명의 토큰 URL을 발급합니다. -- `allowHostControl: false`(기본값)는 sandboxed 세션이 호스트 browser를 대상으로 삼지 못하게 합니다. +- `allowHostControl: false`(기본값)는 sandbox된 세션이 호스트 browser를 대상으로 하는 것을 차단합니다. - `network`의 기본값은 `openclaw-sandbox-browser`(전용 bridge 네트워크)입니다. 전역 bridge 연결이 명시적으로 필요할 때만 `bridge`로 설정하세요. -- `cdpSourceRange`는 선택적으로 컨테이너 가장자리에서 CDP ingress를 CIDR 범위(예: `172.21.0.1/32`)로 제한합니다. -- `sandbox.browser.binds`는 추가 호스트 디렉터리를 sandbox browser 컨테이너에만 마운트합니다. 설정되면(`[]` 포함) browser 컨테이너에는 `docker.binds` 대신 이것이 사용됩니다. -- 시작 기본값은 `scripts/sandbox-browser-entrypoint.sh`에 정의되어 있으며 컨테이너 호스트에 맞게 조정되어 있습니다. +- `cdpSourceRange`는 선택적으로 컨테이너 가장자리에서 CDP 인바운드를 CIDR 범위로 제한합니다(예: `172.21.0.1/32`). +- `sandbox.browser.binds`는 추가 호스트 디렉터리를 sandbox browser 컨테이너에만 마운트합니다. 설정되면(`[]` 포함) browser 컨테이너에 대해 `docker.binds`를 대체합니다. +- 시작 기본값은 `scripts/sandbox-browser-entrypoint.sh`에 정의되어 있으며 컨테이너 호스트에 맞게 조정되어 있습니다: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1493,20 +1522,16 @@ noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (기본적으로 활성화됨) - - `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`는 - 기본적으로 활성화되어 있으며, WebGL/3D 사용에 필요하면 - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`으로 비활성화할 수 있습니다. - - 워크플로에 확장 프로그램이 필요하면 - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`으로 다시 활성화할 수 있습니다. - - `--renderer-process-limit=2`는 - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`으로 변경할 수 있으며, `0`이면 Chromium 기본 제한을 사용합니다. - - `noSandbox`가 활성화된 경우 `--no-sandbox` 및 `--disable-setuid-sandbox`도 추가됩니다. - - 기본값은 컨테이너 이미지 기준선입니다. 컨테이너 기본값을 변경하려면 사용자 지정 browser 이미지와 사용자 지정 entrypoint를 사용하세요. + - `--disable-extensions` (기본 활성화) + - `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`는 기본적으로 활성화되며, WebGL/3D 사용에 필요하면 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`으로 비활성화할 수 있습니다. + - 워크플로가 확장 기능에 의존하는 경우 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`으로 다시 활성화합니다. + - `--renderer-process-limit=2`는 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`으로 변경할 수 있습니다. Chromium 기본 프로세스 제한을 사용하려면 `0`으로 설정하세요. + - 그리고 `noSandbox`가 활성화된 경우 `--no-sandbox` 및 `--disable-setuid-sandbox`. + - 기본값은 컨테이너 이미지 기준선이며, 컨테이너 기본값을 변경하려면 사용자 지정 진입점이 있는 사용자 지정 browser 이미지를 사용하세요. -Browser sandboxing과 `sandbox.docker.binds`는 현재 Docker에서만 지원됩니다. +browser sandboxing과 `sandbox.docker.binds`는 현재 Docker 전용입니다. 이미지 빌드: @@ -1515,7 +1540,7 @@ scripts/sandbox-setup.sh # 메인 sandbox 이미지 scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 ``` -### `agents.list` (agent별 재정의) +### `agents.list` (에이전트별 재정의) ```json5 { @@ -1524,18 +1549,18 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 { id: "main", default: true, - name: "Main Agent", + name: "메인 에이전트", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // 또는 { primary, fallbacks } - thinkingDefault: "high", // agent별 thinking 수준 재정의 - reasoningDefault: "on", // agent별 reasoning 표시 재정의 - fastModeDefault: false, // agent별 fast mode 재정의 + thinkingDefault: "high", // 에이전트별 thinking 수준 재정의 + reasoningDefault: "on", // 에이전트별 reasoning 가시성 재정의 + fastModeDefault: false, // 에이전트별 fast mode 재정의 params: { cacheRetention: "none" }, // 일치하는 defaults.models params를 키별로 재정의 - skills: ["docs-search"], // 설정 시 agents.defaults.skills를 대체 + skills: ["docs-search"], // 설정되면 agents.defaults.skills를 대체 identity: { name: "Samantha", - theme: "helpful sloth", + theme: "도움이 되는 나무늘보", emoji: "🦥", avatar: "avatars/samantha.png", }, @@ -1563,26 +1588,26 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 } ``` -- `id`: 안정적인 agent id(필수)입니다. -- `default`: 여러 개가 설정되면 첫 번째가 우선합니다(경고 기록). 아무것도 설정되지 않으면 목록의 첫 번째 항목이 기본값입니다. +- `id`: 안정적인 에이전트 ID(필수). +- `default`: 여러 개가 설정되면 첫 번째가 우선합니다(경고 기록). 아무것도 설정되지 않으면 첫 번째 목록 항목이 기본값입니다. - `model`: 문자열 형식은 `primary`만 재정의하고, 객체 형식 `{ primary, fallbacks }`는 둘 다 재정의합니다(`[]`는 전역 fallback 비활성화). `primary`만 재정의하는 cron 작업은 `fallbacks: []`를 설정하지 않는 한 기본 fallback을 계속 상속합니다. -- `params`: 선택한 모델 항목의 `agents.defaults.models` 위에 병합되는 agent별 스트림 params입니다. `cacheRetention`, `temperature`, `maxTokens` 같은 agent별 재정의에 사용하세요. 전체 모델 카탈로그를 복제할 필요가 없습니다. -- `skills`: 선택적 agent별 Skills allowlist입니다. 생략하면 agent는 설정된 경우 `agents.defaults.skills`를 상속합니다. 명시적 목록은 기본값과 병합되지 않고 대체하며, `[]`는 Skills 없음입니다. -- `thinkingDefault`: 선택적 agent별 기본 thinking 수준(`off | minimal | low | medium | high | xhigh | adaptive`)입니다. 메시지별 또는 세션별 재정의가 없을 때 이 agent에 대해 `agents.defaults.thinkingDefault`를 덮어씁니다. -- `reasoningDefault`: 선택적 agent별 기본 reasoning 표시(`on | off | stream`)입니다. 메시지별 또는 세션별 reasoning 재정의가 없을 때 적용됩니다. -- `fastModeDefault`: 선택적 agent별 기본 fast mode 값(`true | false`)입니다. 메시지별 또는 세션별 fast-mode 재정의가 없을 때 적용됩니다. -- `runtime`: 선택적 agent별 런타임 descriptor입니다. agent가 기본적으로 ACP harness 세션을 사용해야 한다면 `type: "acp"`와 함께 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)을 사용하세요. -- `identity.avatar`: workspace 상대 경로, `http(s)` URL, 또는 `data:` URI입니다. +- `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`: 선택적 에이전트별 기본 fast mode 값(`true | false`)입니다. 메시지별 또는 세션 fast-mode 재정의가 없을 때 적용됩니다. +- `runtime`: 선택적 에이전트별 런타임 설명자입니다. 에이전트가 기본적으로 ACP 하네스 세션을 사용해야 할 때 `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`용 agent id allowlist입니다(`["*"]` = 아무거나; 기본값: 같은 agent만). -- Sandbox 상속 보호: 요청 세션이 sandbox 안에서 실행 중이면, `sessions_spawn`는 sandbox 없이 실행될 대상은 거부합니다. +- `subagents.allowAgents`: `sessions_spawn`용 에이전트 ID 허용 목록(`["*"]` = 아무거나, 기본값: 동일 에이전트만). +- Sandbox 상속 가드: 요청자 세션이 sandbox 상태이면, `sessions_spawn`은 sandbox 없이 실행될 대상을 거부합니다. - `subagents.requireAgentId`: true이면 `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적 프로필 선택 강제, 기본값: false). --- -## 멀티 agent 라우팅 +## 다중 에이전트 라우팅 -하나의 Gateway 안에서 여러 개의 격리된 agent를 실행합니다. [Multi-Agent](/ko/concepts/multi-agent)를 참고하세요. +하나의 Gateway 안에서 여러 격리된 에이전트를 실행합니다. [Multi-Agent](/ko/concepts/multi-agent)를 참고하세요. ```json5 { @@ -1599,31 +1624,31 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 } ``` -### 바인딩 일치 필드 +### 바인딩 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 }` -**결정적 일치 순서:** +**결정적 match 순서:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (정확히 일치, peer/guild/team 없음) +4. `match.accountId` (정확 일치, peer/guild/team 없음) 5. `match.accountId: "*"` (채널 전체) -6. 기본 agent +6. 기본 에이전트 -각 계층 안에서는 첫 번째로 일치하는 `bindings` 항목이 우선합니다. +각 계층 내에서는 첫 번째로 일치하는 `bindings` 항목이 우선합니다. `type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 식별자(`match.channel` + account + `match.peer.id`)로 해석하며, 위의 route 바인딩 계층 순서를 사용하지 않습니다. -### Agent별 접근 프로필 +### 에이전트별 액세스 프로필 - + ```json5 { @@ -1641,7 +1666,7 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 - + ```json5 { @@ -1670,7 +1695,7 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 - + ```json5 { @@ -1716,7 +1741,7 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 -우선순위 세부 사항은 [Multi-Agent Sandbox & Tools](/ko/tools/multi-agent-sandbox-tools)를 참고하세요. +우선순위 세부 정보는 [Multi-Agent Sandbox & Tools](/ko/tools/multi-agent-sandbox-tools)를 참고하세요. --- @@ -1742,7 +1767,7 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 이 토큰 수를 넘는 부모 스레드 fork는 건너뜀(0이면 비활성화) + parentForkMaxTokens: 100000, // 이 토큰 수를 초과하면 부모 스레드 포크 건너뜀(0은 비활성화) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1754,7 +1779,7 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 }, threadBindings: { enabled: true, - idleHours: 24, // 기본 비활동 자동 unfocus 시간 (`0`은 비활성화) + idleHours: 24, // 기본 비활성 자동 unfocus 시간 (`0`은 비활성화) maxAgeHours: 0, // 기본 하드 최대 사용 기간 시간 (`0`은 비활성화) }, mainKey: "main", // 레거시(런타임은 항상 "main" 사용) @@ -1767,37 +1792,37 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 } ``` - + -- **`scope`**: 그룹 채팅 컨텍스트를 위한 기본 세션 그룹화 전략입니다. +- **`scope`**: 그룹 채팅 컨텍스트의 기본 세션 그룹화 전략입니다. - `per-sender`(기본값): 채널 컨텍스트 내에서 각 발신자가 격리된 세션을 가집니다. - `global`: 채널 컨텍스트의 모든 참가자가 하나의 세션을 공유합니다(공유 컨텍스트가 의도된 경우에만 사용). -- **`dmScope`**: DM을 그룹화하는 방식입니다. +- **`dmScope`**: DM이 그룹화되는 방식입니다. - `main`: 모든 DM이 메인 세션을 공유합니다. - - `per-peer`: 채널 간에 발신자 id별로 격리합니다. - - `per-channel-peer`: 채널 + 발신자별로 격리합니다(멀티 사용자 inbox에 권장). - - `per-account-channel-peer`: 계정 + 채널 + 발신자별로 격리합니다(멀티 계정에 권장). -- **`identityLinks`**: 채널 간 세션 공유를 위한 provider 접두 peer에 대한 정규 ID 매핑입니다. -- **`reset`**: 기본 reset 정책입니다. `daily`는 로컬 시간 `atHour`에 reset하고, `idle`은 `idleMinutes` 후 reset합니다. 둘 다 구성되면 먼저 만료되는 쪽이 우선합니다. + - `per-peer`: 채널 간 발신자 ID별로 격리합니다. + - `per-channel-peer`: 채널 + 발신자별로 격리합니다(다중 사용자 inbox에 권장). + - `per-account-channel-peer`: 계정 + 채널 + 발신자별로 격리합니다(다중 계정에 권장). +- **`identityLinks`**: 채널 간 세션 공유를 위한 정규 ID를 provider 접두사가 있는 peer에 매핑합니다. +- **`reset`**: 기본 리셋 정책입니다. `daily`는 로컬 시간 `atHour`에 리셋되고, `idle`은 `idleMinutes` 후 리셋됩니다. 둘 다 구성된 경우 먼저 만료되는 쪽이 우선합니다. - **`resetByType`**: 타입별 재정의(`direct`, `group`, `thread`)입니다. 레거시 `dm`도 `direct`의 별칭으로 허용됩니다. -- **`parentForkMaxTokens`**: fork된 스레드 세션 생성 시 허용되는 부모 세션 `totalTokens` 최대값입니다(기본값 `100000`). - - 부모 `totalTokens`가 이 값을 넘으면 OpenClaw는 부모 transcript 기록을 상속하지 않고 새 스레드 세션을 시작합니다. - - 이 보호를 끄고 항상 부모 fork를 허용하려면 `0`으로 설정하세요. -- **`mainKey`**: 레거시 필드입니다. 런타임은 이제 메인 direct-chat 버킷에 항상 `"main"`을 사용합니다. -- **`agentToAgent.maxPingPongTurns`**: agent 간 교환 중 reply-back 턴의 최대 횟수입니다(정수, 범위: `0`–`5`). `0`이면 ping-pong chaining이 비활성화됩니다. -- **`sendPolicy`**: `channel`, `chatType` (`direct|group|channel`, 레거시 `dm` 별칭 허용), `keyPrefix`, `rawKeyPrefix`로 일치시킵니다. 첫 번째 deny가 우선합니다. +- **`parentForkMaxTokens`**: 포크된 스레드 세션 생성 시 허용되는 부모 세션 `totalTokens` 최대값입니다(기본값 `100000`). + - 부모 `totalTokens`가 이 값을 초과하면 OpenClaw는 부모 대화 기록을 상속하지 않고 새 스레드 세션을 시작합니다. + - 이 가드를 비활성화하고 항상 부모 포크를 허용하려면 `0`으로 설정하세요. +- **`mainKey`**: 레거시 필드입니다. 런타임은 이제 메인 직접 채팅 버킷에 항상 `"main"`을 사용합니다. +- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 중 에이전트 사이에서 허용되는 최대 응답 왕복 횟수입니다(정수, 범위: `0`–`5`). `0`은 ping-pong 체이닝을 비활성화합니다. +- **`sendPolicy`**: `channel`, `chatType`(`direct|group|channel`, 레거시 `dm` 별칭 포함), `keyPrefix`, `rawKeyPrefix`로 일치시킵니다. 첫 번째 deny가 우선합니다. - **`maintenance`**: 세션 저장소 정리 + 보존 제어입니다. - - `mode`: `warn`은 경고만 기록하고, `enforce`는 실제 정리를 수행합니다. - - `pruneAfter`: 오래된 항목의 기준 나이(기본값 `30d`). - - `maxEntries`: `sessions.json`의 최대 항목 수(기본값 `500`). - - `rotateBytes`: `sessions.json`이 이 크기를 넘으면 회전합니다(기본값 `10mb`). - - `resetArchiveRetention`: `*.reset.` transcript archive 보존 기간입니다. 기본값은 `pruneAfter`를 따르며, 비활성화하려면 `false`로 설정하세요. + - `mode`: `warn`은 경고만 출력하고, `enforce`는 정리를 적용합니다. + - `pruneAfter`: 오래된 항목의 보존 기간 기준입니다(기본값 `30d`). + - `maxEntries`: `sessions.json`의 최대 항목 수입니다(기본값 `500`). + - `rotateBytes`: `sessions.json`이 이 크기를 초과하면 회전합니다(기본값 `10mb`). + - `resetArchiveRetention`: `*.reset.` 대화 기록 아카이브의 보존 기간입니다. 기본값은 `pruneAfter`이며, 비활성화하려면 `false`로 설정하세요. - `maxDiskBytes`: 선택적 세션 디렉터리 디스크 예산입니다. `warn` 모드에서는 경고를 기록하고, `enforce` 모드에서는 가장 오래된 아티팩트/세션부터 제거합니다. - - `highWaterBytes`: 예산 정리 후 목표치입니다. 기본값은 `maxDiskBytes`의 `80%`입니다. -- **`threadBindings`**: 스레드 바운드 세션 기능에 대한 전역 기본값입니다. - - `enabled`: 마스터 기본 스위치(provider가 재정의 가능, Discord는 `channels.discord.threadBindings.enabled` 사용) - - `idleHours`: 비활동 자동 unfocus의 기본 시간(`0`은 비활성화, provider가 재정의 가능) - - `maxAgeHours`: 하드 최대 사용 기간의 기본 시간(`0`은 비활성화, provider가 재정의 가능) + - `highWaterBytes`: 예산 정리 후의 선택적 목표치입니다. 기본값은 `maxDiskBytes`의 `80%`입니다. +- **`threadBindings`**: 스레드 바운드 세션 기능의 전역 기본값입니다. + - `enabled`: 마스터 기본 스위치(provider가 재정의 가능; Discord는 `channels.discord.threadBindings.enabled` 사용) + - `idleHours`: 기본 비활성 자동 unfocus 시간(`0`은 비활성화; provider가 재정의 가능) + - `maxAgeHours`: 기본 하드 최대 사용 기간 시간(`0`은 비활성화; provider가 재정의 가능) @@ -1823,7 +1848,7 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 }, }, inbound: { - debounceMs: 2000, // 0이면 비활성화 + debounceMs: 2000, // 0은 비활성화 byChannel: { whatsapp: 5000, slack: 1500, @@ -1837,34 +1862,34 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 채널/계정별 재정의: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -해결 순서(가장 구체적인 항목 우선): account → channel → global. `""`는 비활성화하고 상위 단계 탐색도 중단합니다. `"auto"`는 `[{identity.name}]`를 파생합니다. +해석 순서(가장 구체적인 것이 우선): 계정 → 채널 → 전역. `""`는 비활성화하며 상위 단계 전파도 중단합니다. `"auto"`는 `[{identity.name}]`을 파생합니다. **템플릿 변수:** -| 변수 | 설명 | 예시 | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | 짧은 모델 이름 | `claude-opus-4-6` | -| `{modelFull}` | 전체 모델 식별자 | `anthropic/claude-opus-4-6` | -| `{provider}` | Provider 이름 | `anthropic` | -| `{thinkingLevel}` | 현재 thinking 수준 | `high`, `low`, `off` | -| `{identity.name}` | Agent 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}`의 별칭입니다. -### 확인 반응 +### Ack 반응 -- 기본값은 활성 agent의 `identity.emoji`, 없으면 `"👀"`입니다. 비활성화하려면 `""`로 설정하세요. +- 기본값은 활성 에이전트의 `identity.emoji`, 없으면 `"👀"`입니다. 비활성화하려면 `""`를 설정하세요. - 채널별 재정의: `channels..ackReaction`, `channels..accounts..ackReaction`. -- 해결 순서: account → channel → `messages.ackReaction` → identity fallback. +- 해석 순서: 계정 → 채널 → `messages.ackReaction` → identity 대체값. - 범위: `group-mentions`(기본값), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: Slack, Discord, Telegram에서 답변 후 ack를 제거합니다. -- `messages.statusReactions.enabled`: Slack, Discord, Telegram에서 lifecycle 상태 반응을 활성화합니다. - Slack과 Discord에서는 설정하지 않으면 ack 반응이 활성화된 경우 상태 반응도 활성화된 상태로 유지됩니다. - Telegram에서는 lifecycle 상태 반응을 활성화하려면 명시적으로 `true`로 설정해야 합니다. +- `removeAckAfterReply`: Slack, Discord, Telegram에서 답글 후 ack를 제거합니다. +- `messages.statusReactions.enabled`: Slack, Discord, Telegram에서 수명 주기 상태 반응을 활성화합니다. + Slack과 Discord에서는 설정하지 않으면 ack 반응이 활성화된 경우 상태 반응도 활성화된 상태를 유지합니다. + Telegram에서는 수명 주기 상태 반응을 활성화하려면 명시적으로 `true`로 설정해야 합니다. -### 인바운드 디바운스 +### 수신 debounce -같은 발신자가 빠르게 보낸 텍스트 전용 메시지를 하나의 agent 턴으로 묶습니다. 미디어/첨부 파일은 즉시 flush됩니다. 제어 명령은 디바운싱을 우회합니다. +같은 발신자의 빠른 연속 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 flush됩니다. 제어 명령은 debounce를 우회합니다. ### TTS (text-to-speech) @@ -1907,12 +1932,12 @@ scripts/sandbox-browser-setup.sh # 선택적 browser 이미지 } ``` -- `auto`는 자동 TTS를 제어합니다. `/tts off|always|inbound|tagged`는 세션별로 재정의합니다. +- `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 엔드포인트를 재정의합니다. 해결 순서는 config, 그다음 `OPENAI_TTS_BASE_URL`, 마지막으로 `https://api.openai.com/v1`입니다. -- `openai.baseUrl`이 OpenAI가 아닌 엔드포인트를 가리키면 OpenClaw는 이를 OpenAI 호환 TTS 서버로 취급하고 모델/voice 검증을 완화합니다. +- `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 서버로 간주하고 모델/음성 검증을 완화합니다. --- @@ -1943,35 +1968,35 @@ 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`를 대체값으로 사용합니다. +- 레거시 평면 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 키가 없을 때만 적용됩니다. -- `providers.*.voiceAliases`를 사용하면 Talk 지시에서 친숙한 이름을 사용할 수 있습니다. -- `silenceTimeoutMs`는 사용자가 말을 멈춘 후 transcript를 보내기 전까지 Talk 모드가 기다리는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 pause 창을 유지합니다(`macOS와 Android는 700 ms, iOS는 900 ms`). +- `ELEVENLABS_API_KEY` 대체값은 Talk API 키가 구성되지 않았을 때만 적용됩니다. +- `providers.*.voiceAliases`를 사용하면 Talk 지시문에서 친숙한 이름을 사용할 수 있습니다. +- `silenceTimeoutMs`는 Talk 모드가 사용자 침묵 후 대본을 전송하기 전에 얼마나 기다릴지 제어합니다. 설정하지 않으면 플랫폼 기본 일시정지 창을 유지합니다(`macOS 및 Android에서는 700 ms, iOS에서는 900 ms`). --- ## 도구 -### 도구 프로필 +### Tool 프로필 -`tools.profile`은 `tools.allow`/`tools.deny` 전에 적용되는 기본 allowlist를 설정합니다. +`tools.profile`은 `tools.allow`/`tools.deny` 이전에 기본 허용 목록을 설정합니다: -로컬 온보딩은 새 로컬 config에서 설정되지 않은 경우 기본값으로 `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` | 제한 없음(설정하지 않은 것과 동일) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | 제한 없음(설정 안 함과 동일) | -### 도구 그룹 +### Tool 그룹 | 그룹 | 도구 | | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash`는 `exec`의 별칭으로 허용됨) | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash`는 `exec`의 별칭으로 허용됨) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | @@ -1982,11 +2007,11 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | 모든 내장 도구(provider plugin 제외) | +| `group:openclaw` | 모든 내장 tool(provider plugin 제외) | ### `tools.allow` / `tools.deny` -전역 도구 허용/거부 정책입니다(deny가 우선). 대소문자를 구분하지 않으며 `*` wildcard를 지원합니다. Docker sandbox가 꺼져 있어도 적용됩니다. +전역 tool 허용/거부 정책입니다(deny 우선). 대소문자를 구분하지 않으며 `*` 와일드카드를 지원합니다. Docker sandbox가 꺼져 있어도 적용됩니다. ```json5 { @@ -1996,7 +2021,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ### `tools.byProvider` -특정 provider 또는 모델에 대해 도구를 추가로 제한합니다. 순서: 기본 프로필 → provider 프로필 → allow/deny. +특정 provider 또는 모델에 대해 tool을 추가로 제한합니다. 순서: 기본 프로필 → provider 프로필 → allow/deny. ```json5 { @@ -2012,7 +2037,7 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. ### `tools.elevated` -sandbox 외부에서 elevated exec 접근을 제어합니다. +sandbox 외부의 elevated exec 액세스를 제어합니다: ```json5 { @@ -2028,9 +2053,9 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. } ``` -- agent별 재정의(`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`는 sandboxing을 우회하며 구성된 이스케이프 경로(`gateway`가 기본값, exec 대상이 `node`일 때는 `node`)를 사용합니다. ### `tools.exec` @@ -2054,8 +2079,8 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. ### `tools.loopDetection` -도구 루프 안전 검사는 기본적으로 **비활성화**되어 있습니다. 감지를 활성화하려면 `enabled: true`로 설정하세요. -설정은 전역 `tools.loopDetection`에 정의하고 agent별 `agents.list[].tools.loopDetection`에서 재정의할 수 있습니다. +Tool 루프 안전 검사는 기본적으로 **비활성화**되어 있습니다. 감지를 활성화하려면 `enabled: true`를 설정하세요. +설정은 전역 `tools.loopDetection`에 정의할 수 있으며 에이전트별로 `agents.list[].tools.loopDetection`에서 재정의할 수 있습니다. ```json5 { @@ -2076,13 +2101,13 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. } ``` -- `historySize`: 루프 분석을 위해 유지되는 최대 도구 호출 기록 수입니다. -- `warningThreshold`: 경고를 발생시키는 반복적 무진전 패턴 임계값입니다. -- `criticalThreshold`: 치명적 루프를 차단하는 더 높은 반복 임계값입니다. -- `globalCircuitBreakerThreshold`: 어떤 무진전 실행이든 강제 중단하는 하드 스톱 임계값입니다. -- `detectors.genericRepeat`: 같은 도구/같은 인자를 반복 호출하면 경고합니다. -- `detectors.knownPollNoProgress`: 알려진 poll 도구(`process.poll`, `command_status` 등)에서 무진전 상태를 경고/차단합니다. -- `detectors.pingPong`: 번갈아 나타나는 무진전 쌍 패턴을 경고/차단합니다. +- `historySize`: 루프 분석을 위해 유지되는 최대 tool 호출 기록 수입니다. +- `warningThreshold`: 경고를 위한 반복적 무진전 패턴 임계값입니다. +- `criticalThreshold`: 심각한 루프를 차단하기 위한 더 높은 반복 임계값입니다. +- `globalCircuitBreakerThreshold`: 모든 무진전 실행에 대한 하드 중단 임계값입니다. +- `detectors.genericRepeat`: 같은 tool/같은 인자 호출 반복 시 경고합니다. +- `detectors.knownPollNoProgress`: 알려진 poll tool(`process.poll`, `command_status` 등)에 대한 무진전 시 경고/차단합니다. +- `detectors.pingPong`: 교대하는 무진전 쌍 패턴에 대해 경고/차단합니다. - `warningThreshold >= criticalThreshold` 또는 `criticalThreshold >= globalCircuitBreakerThreshold`이면 검증이 실패합니다. ### `tools.web` @@ -2093,7 +2118,7 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. web: { search: { enabled: true, - apiKey: "brave_api_key", // 또는 BRAVE_API_KEY 환경 변수 + apiKey: "brave_api_key", // 또는 BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, @@ -2117,7 +2142,7 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. ### `tools.media` -인바운드 media 이해(image/audio/video)를 구성합니다. +수신 미디어 이해(image/audio/video)를 구성합니다: ```json5 { @@ -2125,7 +2150,7 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: 완료된 async music/video를 채널로 직접 전송 + directSend: false, // opt-in: 완료된 비동기 music/video를 채널로 직접 전송 }, audio: { enabled: true, @@ -2149,7 +2174,7 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. } ``` - + **Provider 항목** (`type: "provider"` 또는 생략): @@ -2159,8 +2184,8 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. **CLI 항목** (`type: "cli"`): -- `command`: 실행할 executable -- `args`: 템플릿이 적용된 인자(`{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` 등 지원) +- `command`: 실행할 실행 파일 +- `args`: 템플릿 인자(`{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` 등 지원) **공통 필드:** @@ -2168,13 +2193,11 @@ sandbox 외부에서 elevated exec 접근을 제어합니다. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: 항목별 재정의. - 실패하면 다음 항목으로 대체됩니다. -Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환경 변수 → `models.providers.*.apiKey`. +Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. **비동기 완료 필드:** -- `asyncCompletion.directSend`: `true`이면 완료된 async `music_generate` - 및 `video_generate` 작업이 먼저 직접 채널 전달을 시도합니다. 기본값은 `false`이며 - (레거시 요청 세션 wake/model-delivery 경로)입니다. +- `asyncCompletion.directSend`: `true`이면 완료된 비동기 `music_generate` 및 `video_generate` 작업이 먼저 직접 채널 전달을 시도합니다. 기본값은 `false`(레거시 requester-session wake/model-delivery 경로)입니다. @@ -2193,9 +2216,9 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 ### `tools.sessions` -세션 도구(`sessions_list`, `sessions_history`, `sessions_send`)로 어떤 세션을 대상으로 할 수 있는지 제어합니다. +세션 tool(`sessions_list`, `sessions_history`, `sessions_send`)이 어떤 세션을 대상으로 할 수 있는지 제어합니다. -기본값: `tree`(현재 세션 + 이 세션이 생성한 세션, 예: subagent). +기본값: `tree` (현재 세션 + 그것이 생성한 세션, 예: subagent). ```json5 { @@ -2212,9 +2235,9 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 - `self`: 현재 세션 키만. - `tree`: 현재 세션 + 현재 세션이 생성한 세션(subagent). -- `agent`: 현재 agent id에 속한 모든 세션(같은 agent id 아래에서 per-sender 세션을 실행하면 다른 사용자 세션도 포함될 수 있음). -- `all`: 모든 세션. 에이전트 간 대상 지정에는 여전히 `tools.agentToAgent`가 필요합니다. -- Sandbox clamp: 현재 세션이 sandbox 안에 있고 `agents.defaults.sandbox.sessionToolsVisibility="spawned"`이면, `tools.sessions.visibility="all"`이라도 강제로 `tree`가 됩니다. +- `agent`: 현재 에이전트 ID에 속한 모든 세션(같은 에이전트 ID 아래에서 발신자별 세션을 실행하는 경우 다른 사용자도 포함될 수 있음). +- `all`: 모든 세션. 에이전트 간 대상 지정은 여전히 `tools.agentToAgent`가 필요합니다. +- Sandbox clamp: 현재 세션이 sandbox 상태이고 `agents.defaults.sandbox.sessionToolsVisibility="spawned"`이면 `tools.sessions.visibility="all"`이어도 visibility는 `tree`로 강제됩니다. ### `tools.sessions_spawn` @@ -2225,11 +2248,11 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: true로 설정하면 인라인 파일 첨부 허용 - maxTotalBytes: 5242880, // 전체 파일 합계 5 MB + enabled: false, // opt-in: 인라인 파일 첨부를 허용하려면 true로 설정 + maxTotalBytes: 5242880, // 모든 파일 합계 5 MB maxFiles: 50, maxFileBytes: 1048576, // 파일당 1 MB - retainOnSessionKeep: false, // cleanup="keep"일 때 첨부 파일 유지 + retainOnSessionKeep: false, // cleanup="keep"일 때 첨부 보존 }, }, }, @@ -2239,15 +2262,15 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: - 첨부 파일은 `runtime: "subagent"`에서만 지원됩니다. ACP 런타임은 이를 거부합니다. -- 파일은 자식 workspace의 `.openclaw/attachments//`에 `.manifest.json`과 함께 materialize됩니다. -- 첨부 파일 내용은 transcript 저장에서 자동으로 redaction됩니다. -- Base64 입력은 엄격한 alphabet/padding 검사와 디코딩 전 크기 보호를 통해 검증됩니다. -- 파일 권한은 디렉터리 `0700`, 파일 `0600`입니다. +- 파일은 자식 workspace의 `.openclaw/attachments//`에 `.manifest.json`과 함께 구체화됩니다. +- 첨부 파일 내용은 대화 기록 저장에서 자동으로 redaction됩니다. +- Base64 입력은 엄격한 알파벳/패딩 검사와 디코드 전 크기 가드로 검증됩니다. +- 파일 권한은 디렉터리에 `0700`, 파일에 `0600`입니다. - 정리는 `cleanup` 정책을 따릅니다: `delete`는 항상 첨부 파일을 제거하고, `keep`은 `retainOnSessionKeep: true`일 때만 유지합니다. ### `tools.experimental` -실험적인 내장 도구 플래그입니다. 런타임별 자동 활성화 규칙이 적용되지 않는 한 기본적으로 꺼져 있습니다. +실험적 내장 tool 플래그입니다. 런타임별 자동 활성화 규칙이 적용되는 경우를 제외하면 기본적으로 꺼져 있습니다. ```json5 { @@ -2261,9 +2284,9 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 참고: -- `planTool`: 사소하지 않은 다단계 작업 추적을 위한 구조화된 `update_plan` 도구를 활성화합니다. -- 기본값: OpenAI가 아닌 provider에서는 `false`. OpenAI 및 OpenAI Codex 실행에서는 자동으로 활성화됩니다. -- 활성화되면 system prompt에도 사용 지침이 추가되어, 모델이 상당한 작업에만 이를 사용하고 동시에 최대 한 단계만 `in_progress`로 유지하도록 합니다. +- `planTool`: 중요하고 여러 단계가 있는 작업 추적용 구조화된 `update_plan` tool을 활성화합니다. +- 기본값: OpenAI가 아닌 provider에서는 `false`. OpenAI와 OpenAI Codex 실행은 설정되지 않은 경우 자동으로 활성화합니다. 이 자동 활성화를 끄려면 `false`로 설정하세요. +- 활성화되면 시스템 프롬프트에도 사용 지침이 추가되어 모델이 실질적인 작업에만 사용하고 동시에 최대 하나의 단계만 `in_progress`로 유지하게 됩니다. ### `agents.defaults.subagents` @@ -2284,15 +2307,15 @@ Provider 인증은 표준 순서를 따릅니다: `auth-profiles.json` → 환 ``` - `model`: 생성된 sub-agent의 기본 모델입니다. 생략하면 sub-agent는 호출자의 모델을 상속합니다. -- `allowAgents`: 요청 agent가 자체 `subagents.allowAgents`를 설정하지 않았을 때 `sessions_spawn`용 대상 agent id 기본 allowlist입니다(`["*"]` = 아무거나, 기본값: 같은 agent만). -- `runTimeoutSeconds`: 도구 호출에서 `runTimeoutSeconds`를 생략했을 때 `sessions_spawn`의 기본 타임아웃(초)입니다. `0`은 무제한입니다. -- subagent별 도구 정책: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `allowAgents`: 요청 에이전트가 자체 `subagents.allowAgents`를 설정하지 않았을 때 `sessions_spawn`용 기본 대상 에이전트 ID 허용 목록입니다(`["*"]` = 아무거나, 기본값: 동일 에이전트만). +- `runTimeoutSeconds`: tool 호출에서 `runTimeoutSeconds`를 생략했을 때 `sessions_spawn`의 기본 타임아웃(초)입니다. `0`은 타임아웃 없음입니다. +- subagent별 tool 정책: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## 사용자 지정 provider 및 base URL -OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 provider는 config의 `models.providers` 또는 `~/.openclaw/agents//agent/models.json`을 통해 추가할 수 있습니다. +OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 provider는 구성의 `models.providers` 또는 `~/.openclaw/agents//agent/models.json`을 통해 추가합니다. ```json5 { @@ -2321,47 +2344,47 @@ OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 prov } ``` -- 사용자 지정 인증이 필요하면 `authHeader: true` + `headers`를 사용하세요. -- agent config 루트는 `OPENCLAW_AGENT_DIR`(또는 레거시 환경 변수 별칭 `PI_CODING_AGENT_DIR`)로 재정의할 수 있습니다. -- 일치하는 provider ID에 대한 병합 우선순위: - - 비어 있지 않은 agent `models.json`의 `baseUrl` 값이 우선합니다. - - 비어 있지 않은 agent `apiKey` 값은 현재 config/auth-profile 컨텍스트에서 해당 provider가 SecretRef 관리 대상이 아닐 때만 우선합니다. - - SecretRef 관리 provider의 `apiKey` 값은 해석된 비밀을 저장하는 대신 source marker(`ENV_VAR_NAME`는 env ref, `secretref-managed`는 file/exec ref)에서 새로고침됩니다. - - SecretRef 관리 provider header 값도 source marker(`secretref-env:ENV_VAR_NAME`는 env ref, `secretref-managed`는 file/exec ref)에서 새로고침됩니다. - - 비어 있거나 없는 agent `apiKey`/`baseUrl`은 config의 `models.providers`를 대체값으로 사용합니다. - - 일치하는 모델의 `contextWindow`/`maxTokens`는 명시적 config 값과 암시적 catalog 값 중 더 큰 값을 사용합니다. - - 일치하는 모델의 `contextTokens`는 명시적 런타임 cap이 있으면 이를 유지합니다. 모델의 네이티브 메타데이터를 바꾸지 않고 유효 컨텍스트를 제한하려면 이것을 사용하세요. - - config가 `models.json`을 완전히 덮어써야 한다면 `models.mode: "replace"`를 사용하세요. - - Marker 저장은 source-authoritative입니다: marker는 해석된 런타임 비밀 값이 아니라 활성 source config 스냅샷(해석 전)에서 기록됩니다. +- 사용자 지정 인증 요구사항에는 `authHeader: true` + `headers`를 사용하세요. +- 에이전트 구성 루트는 `OPENCLAW_AGENT_DIR`(또는 레거시 환경 변수 별칭 `PI_CODING_AGENT_DIR`)로 재정의할 수 있습니다. +- 일치하는 provider ID의 병합 우선순위: + - 비어 있지 않은 에이전트 `models.json` `baseUrl` 값이 우선합니다. + - 비어 있지 않은 에이전트 `apiKey` 값은 해당 provider가 현재 구성/auth-profile 컨텍스트에서 SecretRef 관리가 아닐 때만 우선합니다. + - SecretRef 관리 provider `apiKey` 값은 해석된 비밀을 유지하는 대신 소스 마커(`env` ref의 경우 `ENV_VAR_NAME`, file/exec ref의 경우 `secretref-managed`)에서 새로 고쳐집니다. + - SecretRef 관리 provider header 값은 소스 마커(`env` ref의 경우 `secretref-env:ENV_VAR_NAME`, file/exec ref의 경우 `secretref-managed`)에서 새로 고쳐집니다. + - 비어 있거나 누락된 에이전트 `apiKey`/`baseUrl`은 구성의 `models.providers`로 대체됩니다. + - 일치하는 모델 `contextWindow`/`maxTokens`는 명시적 구성값과 암시적 카탈로그 값 중 더 큰 값을 사용합니다. + - 일치하는 모델 `contextTokens`는 존재하는 경우 명시적 런타임 캡을 보존합니다. 모델의 네이티브 메타데이터를 변경하지 않고 실제 컨텍스트를 제한하려면 이를 사용하세요. + - 구성이 `models.json`을 완전히 다시 쓰게 하려면 `models.mode: "replace"`를 사용하세요. + - 마커 유지 저장은 소스 권위적입니다: 마커는 해석된 런타임 비밀 값이 아니라 활성 소스 구성 스냅샷(해석 전)에서 기록됩니다. -### Provider 필드 세부 사항 +### Provider 필드 세부 정보 - `models.mode`: provider 카탈로그 동작(`merge` 또는 `replace`). - `models.providers`: provider id를 키로 하는 사용자 지정 provider 맵. -- `models.providers.*.api`: 요청 adapter (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` 등). -- `models.providers.*.apiKey`: provider 자격 증명(SecretRef/env substitution 권장). +- `models.providers.*.api`: 요청 어댑터(`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` 등). +- `models.providers.*.apiKey`: provider 자격 증명(SecretRef/env 치환 권장). - `models.providers.*.auth`: 인증 전략(`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions`에서 요청에 `options.num_ctx` 삽입(기본값: `true`). -- `models.providers.*.authHeader`: 필요할 때 자격 증명을 `Authorization` 헤더로 강제 전달. -- `models.providers.*.baseUrl`: 업스트림 API base URL. -- `models.providers.*.headers`: proxy/tenant 라우팅용 추가 정적 헤더. -- `models.providers.*.request`: model-provider HTTP 요청용 전송 재정의. - - `request.headers`: 추가 헤더(provider 기본값과 병합). 값은 SecretRef 허용. - - `request.auth`: 인증 전략 재정의. 모드: `"provider-default"`(provider 내장 인증 사용), `"authorization-bearer"`(`token` 사용), `"header"`(`headerName`, `value`, 선택적 `prefix` 사용). - - `request.proxy`: HTTP 프록시 재정의. 모드: `"env-proxy"`(`HTTP_PROXY`/`HTTPS_PROXY` 환경 변수 사용), `"explicit-proxy"`(`url` 사용). 두 모드 모두 선택적 `tls` 하위 객체를 받을 수 있습니다. +- `models.providers.*.injectNumCtxForOpenAICompat`: Ollama + `openai-completions`에서 요청에 `options.num_ctx` 주입(기본값: `true`). +- `models.providers.*.authHeader`: 필요할 때 `Authorization` 헤더에서 자격 증명을 강제 전송. +- `models.providers.*.baseUrl`: 업스트림 API 기본 URL. +- `models.providers.*.headers`: 프록시/테넌트 라우팅용 추가 정적 헤더. +- `models.providers.*.request`: 모델 provider HTTP 요청용 전송 재정의. + - `request.headers`: 추가 헤더(provider 기본값과 병합). 값은 SecretRef를 받을 수 있습니다. + - `request.auth`: 인증 전략 재정의. 모드: `"provider-default"`(provider 내장 인증 사용), `"authorization-bearer"`(`token` 포함), `"header"`(`headerName`, `value`, 선택적 `prefix` 포함). + - `request.proxy`: HTTP 프록시 재정의. 모드: `"env-proxy"`(`HTTP_PROXY`/`HTTPS_PROXY` env vars 사용), `"explicit-proxy"`(`url` 포함). 두 모드 모두 선택적 `tls` 하위 객체를 받을 수 있습니다. - `request.tls`: 직접 연결용 TLS 재정의. 필드: `ca`, `cert`, `key`, `passphrase`(모두 SecretRef 허용), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: 명시적 provider 모델 카탈로그 항목. -- `models.providers.*.models.*.contextWindow`: 네이티브 모델 컨텍스트 윈도우 메타데이터. -- `models.providers.*.models.*.contextTokens`: 선택적 런타임 컨텍스트 cap. 모델의 네이티브 `contextWindow`보다 더 작은 유효 컨텍스트 예산을 원할 때 사용하세요. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: 선택적 호환성 힌트. `api: "openai-completions"`이고 비어 있지 않은 비네이티브 `baseUrl`(호스트가 `api.openai.com`이 아님)일 경우, OpenClaw는 런타임에 이를 강제로 `false`로 설정합니다. 비어 있거나 생략된 `baseUrl`은 기본 OpenAI 동작을 유지합니다. -- `models.providers.*.models.*.compat.requiresStringContent`: 문자열 전용 OpenAI 호환 chat 엔드포인트를 위한 선택적 호환성 힌트. `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`: 탐지 새로고침 polling 간격. -- `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 호환 chat 엔드포인트용 선택적 호환성 힌트. `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 예시 @@ -2399,7 +2422,7 @@ OpenClaw는 내장 모델 카탈로그를 사용합니다. 사용자 지정 prov } ``` -Cerebras에는 `cerebras/zai-glm-4.7`을, Z.AI direct에는 `zai/glm-4.7`을 사용하세요. +Cerebras에는 `cerebras/zai-glm-4.7`을 사용하고, Z.AI 직접 연결에는 `zai/glm-4.7`을 사용하세요. @@ -2416,7 +2439,7 @@ Cerebras에는 `cerebras/zai-glm-4.7`을, Z.AI direct에는 `zai/glm-4.7`을 사 } ``` -`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`. @@ -2433,11 +2456,11 @@ Cerebras에는 `cerebras/zai-glm-4.7`을, Z.AI direct에는 `zai/glm-4.7`을 사 } ``` -`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를 정의하세요. @@ -2476,10 +2499,9 @@ Cerebras에는 `cerebras/zai-glm-4.7`을, Z.AI direct에는 `zai/glm-4.7`을 사 } ``` -중국 엔드포인트는 `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 하나만이 아니라 엔드포인트 기능을 기준으로 이를 판단합니다. @@ -2497,7 +2519,7 @@ Cerebras에는 `cerebras/zai-glm-4.7`을, Z.AI direct에는 `zai/glm-4.7`을 사 } ``` -Anthropic 호환 내장 provider입니다. 단축 명령: `openclaw onboard --auth-choice kimi-code-api-key`. +Anthropic 호환 내장 provider입니다. 단축키: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2536,11 +2558,11 @@ Anthropic 호환 내장 provider입니다. 단축 명령: `openclaw onboard --au } ``` -Base URL에는 `/v1`를 포함하지 않아야 합니다(Anthropic 클라이언트가 이를 뒤에 붙임). 단축 명령: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL은 `/v1`을 생략해야 합니다(Anthropic 클라이언트가 이를 추가함). 단축키: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2576,19 +2598,17 @@ Base URL에는 `/v1`를 포함하지 않아야 합니다(Anthropic 클라이언 } ``` -`MINIMAX_API_KEY`를 설정하세요. 단축 명령: +`MINIMAX_API_KEY`를 설정하세요. 단축키: `openclaw onboard --auth-choice minimax-global-api` 또는 `openclaw onboard --auth-choice minimax-cn-api`. 모델 카탈로그는 이제 기본적으로 M2.7만 사용합니다. -Anthropic 호환 스트리밍 경로에서, OpenClaw는 명시적으로 `thinking`을 설정하지 않으면 기본적으로 MiniMax thinking을 비활성화합니다. `/fast on` 또는 -`params.fastMode: true`는 `MiniMax-M2.7`을 -`MiniMax-M2.7-highspeed`로 재작성합니다. +Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 `thinking`을 설정하지 않는 한 기본적으로 MiniMax thinking을 비활성화합니다. `/fast on` 또는 `params.fastMode: true`는 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 다시 씁니다. -[Local Models](/ko/gateway/local-models)를 참고하세요. 요약하면: 충분한 하드웨어에서 LM Studio Responses API로 대형 로컬 모델을 실행하고, fallback을 위해 호스팅 모델은 병합해 두세요. +[Local Models](/ko/gateway/local-models)를 참고하세요. 요약: 충분한 하드웨어에서 LM Studio Responses API를 통해 대형 로컬 모델을 실행하고, 대체를 위해 호스팅된 모델은 병합된 상태로 유지하세요. @@ -2619,16 +2639,16 @@ Anthropic 호환 스트리밍 경로에서, OpenClaw는 명시적으로 `thinkin } ``` -- `allowBundled`: 번들된 Skills 전용의 선택적 allowlist입니다(관리형/workspace Skills에는 영향 없음). -- `load.extraDirs`: 추가 공유 Skills 루트(가장 낮은 우선순위). -- `install.preferBrew`: `brew`를 사용할 수 있으면 다른 설치 방식으로 대체하기 전에 Homebrew 설치를 우선합니다. -- `install.nodeManager`: `metadata.openclaw.install` 사양에 대한 node 설치기 선호도(`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false`는 번들/설치되어 있더라도 해당 Skill을 비활성화합니다. -- `entries..apiKey`: 기본 env var를 선언하는 Skills를 위한 편의 필드입니다(일반 텍스트 문자열 또는 SecretRef 객체). +- `allowBundled`: 번들 skill만을 위한 선택적 허용 목록입니다(관리형/workspace skill에는 영향 없음). +- `load.extraDirs`: 추가 공유 skill 루트(가장 낮은 우선순위). +- `install.preferBrew`: `brew`를 사용할 수 있을 때 다른 설치 방식으로 대체되기 전에 Homebrew 설치 프로그램을 우선합니다. +- `install.nodeManager`: `metadata.openclaw.install` 명세용 node 설치 프로그램 선호도 (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false`는 번들/설치된 skill이라도 비활성화합니다. +- `entries..apiKey`: 기본 env var를 선언하는 skill을 위한 편의 필드입니다(일반 텍스트 문자열 또는 SecretRef 객체). --- -## Plugins +## 플러그인 ```json5 { @@ -2653,183 +2673,45 @@ Anthropic 호환 스트리밍 경로에서, OpenClaw는 명시적으로 `thinkin ``` - `~/.openclaw/extensions`, `/.openclaw/extensions`, 그리고 `plugins.load.paths`에서 로드됩니다. -- 탐지는 네이티브 OpenClaw plugin뿐 아니라 호환되는 Codex 번들 및 Claude 번들도 허용하며, manifest가 없는 Claude 기본 레이아웃 번들도 포함합니다. -- **Config 변경에는 gateway 재시작이 필요합니다.** -- `allow`: 선택적 allowlist입니다(목록에 있는 plugin만 로드). `deny`가 우선합니다. -- `plugins.entries..apiKey`: plugin 수준 API 키 편의 필드입니다(plugin이 지원하는 경우). -- `plugins.entries..env`: plugin 범위 env var 맵. -- `plugins.entries..hooks.allowPromptInjection`: `false`이면 코어는 `before_prompt_build`를 차단하고 레거시 `before_agent_start`의 prompt 변경 필드를 무시하되, 레거시 `modelOverride`와 `providerOverride`는 유지합니다. 네이티브 plugin hook과 지원되는 번들 제공 hook 디렉터리에 적용됩니다. -- `plugins.entries..subagent.allowModelOverride`: 이 plugin이 백그라운드 subagent 실행에 대해 `provider` 및 `model` 재정의를 요청할 수 있도록 명시적으로 신뢰합니다. -- `plugins.entries..subagent.allowedModels`: 신뢰된 subagent 재정의에 대한 정규 `provider/model` 대상의 선택적 allowlist입니다. 모든 모델을 허용하려는 의도가 명확할 때만 `"*"`를 사용하세요. -- `plugins.entries..config`: plugin이 정의하는 config 객체입니다(가능하면 네이티브 OpenClaw plugin 스키마로 검증됨). +- 검색은 네이티브 OpenClaw 플러그인과 호환 가능한 Codex 번들 및 Claude 번들을 허용하며, manifest가 없는 Claude 기본 레이아웃 번들도 포함합니다. +- **구성 변경에는 gateway 재시작이 필요합니다.** +- `allow`: 선택적 허용 목록(목록에 있는 플러그인만 로드). `deny`가 우선합니다. +- `plugins.entries..apiKey`: 플러그인 수준 API 키 편의 필드(플러그인이 지원하는 경우). +- `plugins.entries..env`: 플러그인 범위 env var 맵. +- `plugins.entries..hooks.allowPromptInjection`: `false`이면 core가 `before_prompt_build`를 차단하고 레거시 `before_agent_start`의 프롬프트 변경 필드를 무시하며, 레거시 `modelOverride` 및 `providerOverride`는 유지합니다. 네이티브 plugin hook과 지원되는 번들 제공 hook 디렉터리에 적용됩니다. +- `plugins.entries..subagent.allowModelOverride`: 이 플러그인이 백그라운드 subagent 실행에 대해 실행별 `provider` 및 `model` 재정의를 요청하도록 명시적으로 신뢰합니다. +- `plugins.entries..subagent.allowedModels`: 신뢰된 subagent 재정의용 정규 `provider/model` 대상의 선택적 허용 목록입니다. 어떤 모델이든 의도적으로 허용하려는 경우에만 `"*"`를 사용하세요. +- `plugins.entries..config`: 플러그인 정의 구성 객체(사용 가능한 경우 네이티브 OpenClaw plugin 스키마로 검증됨). - `plugins.entries.firecrawl.config.webFetch`: Firecrawl web-fetch provider 설정. - - `apiKey`: Firecrawl API 키(SecretRef 허용). `plugins.entries.firecrawl.config.webSearch.apiKey`, 레거시 `tools.web.fetch.firecrawl.apiKey`, 또는 `FIRECRAWL_API_KEY` 환경 변수를 대체값으로 사용합니다. + - `apiKey`: Firecrawl API 키(SecretRef 허용). `plugins.entries.firecrawl.config.webSearch.apiKey`, 레거시 `tools.web.fetch.firecrawl.apiKey`, 또는 `FIRECRAWL_API_KEY` env var를 대체값으로 사용합니다. - `baseUrl`: Firecrawl API base URL(기본값: `https://api.firecrawl.dev`). - - `onlyMainContent`: 페이지의 main content만 추출합니다(기본값: `true`). - - `maxAgeMs`: 최대 cache age(밀리초, 기본값: `172800000` / 2일). - - `timeoutSeconds`: scrape 요청 타임아웃(초, 기본값: `60`). -- `plugins.entries.xai.config.xSearch`: xAI X Search(Grok 웹 검색) 설정. + - `onlyMainContent`: 페이지에서 메인 콘텐츠만 추출합니다(기본값: `true`). + - `maxAgeMs`: 최대 캐시 사용 기간(밀리초)입니다(기본값: `172800000` / 2일). + - `timeoutSeconds`: 스크래핑 요청 타임아웃(초)입니다(기본값: `60`). +- `plugins.entries.xai.config.xSearch`: xAI X Search (Grok 웹 검색) 설정. - `enabled`: X Search provider를 활성화합니다. - `model`: 검색에 사용할 Grok 모델(예: `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: memory dreaming(실험적) 설정입니다. 단계와 임계값은 [Dreaming](/ko/concepts/dreaming)을 참고하세요. - - `enabled`: dreaming 마스터 스위치(기본값 `false`). - - `frequency`: 각 전체 dreaming sweep의 cron cadence(기본값 `"0 3 * * *"`). - - phase policy와 임계값은 구현 세부 사항이며 사용자 대상 config 키가 아닙니다. -- 활성화된 Claude 번들 plugin은 `settings.json`에 포함된 Pi 기본값을 기여할 수 있으며, OpenClaw는 이를 raw OpenClaw config patch가 아니라 정제된 agent 설정으로 적용합니다. -- `plugins.slots.memory`: 활성 memory plugin id를 선택하거나 `"none"`으로 memory plugin을 비활성화합니다. -- `plugins.slots.contextEngine`: 활성 context engine plugin id를 선택합니다. 다른 engine을 설치하고 선택하지 않으면 기본값은 `"legacy"`입니다. +- `plugins.entries.memory-core.config.dreaming`: memory dreaming(실험적) 설정. 단계와 임계값은 [Dreaming](/ko/concepts/dreaming)을 참고하세요. + - `enabled`: 마스터 dreaming 스위치(기본값 `false`). + - `frequency`: 각 전체 dreaming 스윕의 cron 주기(기본값은 `"0 3 * * *"`). + - 단계 정책과 임계값은 구현 세부 사항입니다(사용자 대상 구성 키 아님). +- 전체 memory 구성은 [Memory configuration reference](/ko/reference/memory-config)에 있습니다: + - `agents.defaults.memorySearch.*` + - `memory.backend` + - `memory.citations` + - `memory.qmd.*` + - `plugins.entries.memory-core.config.dreaming` +- 활성화된 Claude 번들 플러그인은 `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)를 참고하세요. --- -## Browser +## 브라우저 -```json5 -{ - browser: { - enabled: true, - evaluateEnabled: true, - defaultProfile: "user", - ssrfPolicy: { - dangerouslyAllowPrivateNetwork: true, // 기본 trusted-network 모드 - // allowPrivateNetwork: true, // 레거시 별칭 - // hostnameAllowlist: ["*.example.com", "example.com"], - // allowedHostnames: ["localhost"], - }, - profiles: { - openclaw: { cdpPort: 18800, color: "#FF4500" }, - work: { cdpPort: 18801, color: "#0066CC" }, - user: { driver: "existing-session", attachOnly: true, color: "#00AA00" }, - brave: { - driver: "existing-session", - attachOnly: true, - userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser", - color: "#FB542B", - }, - remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" }, - }, - color: "#FF4500", - // headless: false, - // noSandbox: false, - // extraArgs: [], - // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", - // attachOnly: false, - }, -} -``` - -- `evaluateEnabled: false`는 `act:evaluate`와 `wait --fn`을 비활성화합니다. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork`는 설정하지 않으면 기본값이 `true`입니다(trusted-network 모델). -- 엄격한 public-only browser 탐색을 원하면 `ssrfPolicy.dangerouslyAllowPrivateNetwork: false`로 설정하세요. -- 엄격 모드에서는 원격 CDP profile 엔드포인트(`profiles.*.cdpUrl`)도 도달 가능성/탐지 검사 중 동일한 private-network 차단 대상이 됩니다. -- `ssrfPolicy.allowPrivateNetwork`는 여전히 레거시 별칭으로 지원됩니다. -- 엄격 모드에서는 명시적 예외에 `ssrfPolicy.hostnameAllowlist`와 `ssrfPolicy.allowedHostnames`를 사용하세요. -- 원격 profile은 attach-only입니다(start/stop/reset 비활성화). -- `profiles.*.cdpUrl`은 `http://`, `https://`, `ws://`, `wss://`를 받을 수 있습니다. - `/json/version`을 OpenClaw가 탐지하게 하려면 HTTP(S)를, - provider가 직접 DevTools WebSocket URL을 제공한다면 WS(S)를 사용하세요. -- `existing-session` profile은 호스트 전용이며 CDP 대신 Chrome MCP를 사용합니다. -- `existing-session` profile은 Brave나 Edge 같은 특정 - Chromium 기반 browser profile을 대상으로 하기 위해 `userDataDir`을 설정할 수 있습니다. -- `existing-session` profile은 현재 Chrome MCP 경로 제한을 유지합니다: - CSS selector 대상 지정 대신 snapshot/ref 기반 action, - 단일 파일 업로드 hook, dialog timeout 재정의 없음, `wait --load networkidle` 없음, - `responsebody`, PDF 내보내기, 다운로드 가로채기, batch actions 없음. -- 로컬 관리형 `openclaw` profile은 `cdpPort`와 `cdpUrl`을 자동 할당합니다. - 원격 CDP에만 `cdpUrl`을 명시적으로 설정하세요. -- 자동 탐지 순서: 기본 browser가 Chromium 기반이면 먼저 → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Control service: local loopback 전용(gateway.port에서 파생된 포트, 기본값 `18791`). -- `extraArgs`는 로컬 Chromium 시작에 추가 launch flag를 덧붙입니다(예: - `--disable-gpu`, 창 크기 설정, 디버그 플래그). - ---- - -## UI - -```json5 -{ - ui: { - seamColor: "#FF4500", - assistant: { - name: "OpenClaw", - avatar: "CB", // emoji, 짧은 텍스트, 이미지 URL, 또는 data URI - }, - }, -} -``` - -- `seamColor`: 네이티브 앱 UI chrome의 강조 색상입니다(Talk Mode 버블 tint 등). -- `assistant`: Control UI identity 재정의입니다. 활성 agent identity를 대체값으로 사용합니다. - ---- - -## Gateway - -```json5 -{ - gateway: { - mode: "local", // local | remote - port: 18789, - bind: "loopback", - auth: { - mode: "token", // none | token | password | trusted-proxy - token: "your-token", - // password: "your-password", // 또는 OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // mode=trusted-proxy용; /gateway/trusted-proxy-auth 참고 - allowTailscale: true, - rateLimit: { - maxAttempts: 10, - windowMs: 60000, - lockoutMs: 300000, - exemptLoopback: true, - }, - }, - tailscale: { - mode: "off", // off | serve | funnel - resetOnExit: false, - }, - controlUi: { - enabled: true, - basePath: "/openclaw", - // root: "dist/control-ui", - // allowedOrigins: ["https://control.example.com"], // non-loopback Control UI에는 필수 - // dangerouslyAllowHostHeaderOriginFallback: false, // 위험한 Host-header origin fallback 모드 - // allowInsecureAuth: false, - // dangerouslyDisableDeviceAuth: false, - }, - remote: { - url: "ws://gateway.tailnet:18789", - transport: "ssh", // ssh | direct - token: "your-token", - // password: "your-password", - }, - trustedProxies: ["10.0.0.1"], - // 선택 사항. 기본값 false. - allowRealIpFallback: false, - tools: { - // 추가 /tools/invoke HTTP deny - deny: ["browser"], - // 기본 HTTP deny 목록에서 도구 제거 - allow: ["gateway"], - }, - push: { - apns: { - relay: { - baseUrl: "https://relay.example.com", - timeoutMs: 10000, - }, - }, - }, - }, -} -``` - - - -- `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`), `tail \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/ko/gateway/configuration.md b/docs/ko/gateway/configuration.md index 1397dd37e..e9cc68ff4 100644 --- a/docs/ko/gateway/configuration.md +++ b/docs/ko/gateway/configuration.md @@ -1,36 +1,36 @@ --- read_when: - - OpenClaw를 처음 설정하는 중 - - 일반적인 구성 패턴을 찾는 중 - - 특정 config 섹션으로 이동하는 중 + - 처음으로 OpenClaw 설정하기 + - 일반적인 구성 패턴 찾기 + - 특정 구성 섹션으로 이동하기 summary: '구성 개요: 일반적인 작업, 빠른 설정, 전체 참조 링크' -title: Configuration +title: 구성 x-i18n: - generated_at: "2026-04-05T12:42:55Z" + generated_at: "2026-04-08T05:56:44Z" model: gpt-5.4 provider: openai - source_hash: a39a7de09c5f9540785ec67f37d435a7a86201f0f5f640dae663054f35976712 + source_hash: 199a1e515bd4003319e71593a2659bb883299a76ff67e273d92583df03c96604 source_path: gateway/configuration.md workflow: 15 --- -# Configuration +# 구성 -OpenClaw는 `~/.openclaw/openclaw.json`에서 선택적 **JSON5** config를 읽습니다. +OpenClaw는 `~/.openclaw/openclaw.json`에서 선택적인 **JSON5** 구성을 읽습니다. -파일이 없으면 OpenClaw는 안전한 기본값을 사용합니다. config를 추가하는 일반적인 이유는 다음과 같습니다. +파일이 없으면 OpenClaw는 안전한 기본값을 사용합니다. 구성을 추가하는 일반적인 이유는 다음과 같습니다. - 채널을 연결하고 누가 봇에 메시지를 보낼 수 있는지 제어 - 모델, 도구, 샌드박싱 또는 자동화(cron, hooks) 설정 - 세션, 미디어, 네트워킹 또는 UI 조정 -사용 가능한 모든 필드는 [full reference](/gateway/configuration-reference)를 참조하세요. +사용 가능한 모든 필드는 [전체 참조](/ko/gateway/configuration-reference)에서 확인하세요. -**구성이 처음이신가요?** 대화형 설정에는 `openclaw onboard`로 시작하거나, 완전한 복사-붙여넣기 config는 [Configuration Examples](/gateway/configuration-examples) 가이드를 확인하세요. +**구성이 처음이신가요?** 대화형 설정을 위해 `openclaw onboard`로 시작하거나, 완전한 복사-붙여넣기 구성은 [구성 예시](/ko/gateway/configuration-examples) 가이드를 확인하세요. -## 최소 config +## 최소 구성 ```json5 // ~/.openclaw/openclaw.json @@ -40,16 +40,16 @@ OpenClaw는 `~/.openclaw/openclaw.json`에서 선택적 ```bash openclaw onboard # 전체 온보딩 흐름 - openclaw configure # config 마법사 + openclaw configure # 구성 마법사 ``` - + ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" @@ -58,63 +58,57 @@ OpenClaw는 `~/.openclaw/openclaw.json`에서 선택적 [http://127.0.0.1:18789](http://127.0.0.1:18789)을 열고 **Config** 탭을 사용하세요. - Control UI는 사용 가능한 경우 field - `title` / `description` 문서 메타데이터와 plugin 및 channel 스키마를 포함해 라이브 config 스키마에서 폼을 렌더링하며, - 탈출구로 **Raw JSON** 편집기도 제공합니다. 드릴다운 - UI 및 기타 도구용으로 gateway는 - `config.schema.lookup`도 노출하여 경로 범위 스키마 노드 하나와 직접 자식 요약을 가져올 수 있습니다. + Control UI는 라이브 config 스키마로부터 폼을 렌더링하며, 사용 가능한 경우 + 필드 `title` / `description` 문서 메타데이터와 plugin 및 channel 스키마를 포함하고, + 탈출구로 사용할 수 있는 **Raw JSON** 편집기도 제공합니다. 드릴다운 UI와 + 기타 도구를 위해 gateway는 `config.schema.lookup`도 제공하며, + 경로 범위가 지정된 스키마 노드 하나와 즉시 하위 요약을 가져올 수 있습니다. - `~/.openclaw/openclaw.json`을 직접 편집하세요. Gateway는 파일을 감시하며 변경 사항을 자동으로 적용합니다([hot reload](#config-hot-reload) 참조). + `~/.openclaw/openclaw.json`을 직접 편집하세요. Gateway는 파일을 감시하고 변경 사항을 자동으로 적용합니다([핫 리로드](#config-hot-reload) 참조). ## 엄격한 검증 -OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 수 없는 키, 잘못된 타입, 또는 유효하지 않은 값이 있으면 Gateway는 **시작을 거부**합니다. 루트 수준의 유일한 예외는 편집기가 JSON Schema 메타데이터를 붙일 수 있도록 하는 `$schema`(문자열)입니다. +OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 수 없는 키, 잘못된 타입, 유효하지 않은 값이 있으면 Gateway는 **시작을 거부합니다**. 루트 수준의 유일한 예외는 편집기가 JSON Schema 메타데이터를 연결할 수 있도록 하는 `$schema`(문자열)입니다. -스키마 도구 참고: +스키마 도구 참고 사항: -- `openclaw config schema`는 Control UI와 - config 검증에서 사용하는 동일한 JSON Schema 계열을 출력합니다. -- Field `title` 및 `description` 값은 편집기 및 폼 도구를 위해 - 스키마 출력에도 포함됩니다. -- 중첩 객체, 와일드카드(`*`), 배열 항목(`[]`) 항목도 - 일치하는 field 문서가 있는 경우 동일한 문서 메타데이터를 상속합니다. -- `anyOf` / `oneOf` / `allOf` 구성 분기도 동일한 문서 - 메타데이터를 상속하므로 union/intersection 변형에서도 같은 field 도움말을 유지합니다. -- `config.schema.lookup`은 정규화된 config 경로 하나와 얕은 - 스키마 노드(`title`, `description`, `type`, `enum`, `const`, 공통 경계값, - 및 유사한 검증 필드), 일치하는 UI 힌트 메타데이터, 드릴다운 도구용 즉시 자식 - 요약을 반환합니다. -- 런타임 plugin/channel 스키마는 gateway가 현재 - manifest 레지스트리를 로드할 수 있을 때 병합됩니다. +- `openclaw config schema`는 Control UI와 config 검증에서 사용하는 것과 동일한 JSON Schema 계열을 출력합니다. +- 해당 스키마 출력은 `openclaw.json`의 표준 기계 판독 계약으로 취급하세요. 이 개요와 구성 참조는 이를 요약한 것입니다. +- 필드 `title` 및 `description` 값은 편집기와 폼 도구를 위해 스키마 출력에 포함됩니다. +- 중첩 객체, 와일드카드(`*`), 배열 항목(`[]`) 항목은 일치하는 필드 문서가 존재하는 경우 동일한 문서 메타데이터를 상속합니다. +- `anyOf` / `oneOf` / `allOf` 구성 분기 역시 동일한 문서 메타데이터를 상속하므로, union/intersection 변형도 같은 필드 도움말을 유지합니다. +- `config.schema.lookup`은 정규화된 config 경로 하나와 얕은 스키마 노드(`title`, `description`, `type`, `enum`, `const`, 일반적인 경계값 및 유사한 검증 필드), 일치하는 UI 힌트 메타데이터, 그리고 드릴다운 도구를 위한 즉시 하위 요약을 반환합니다. +- runtime plugin/channel 스키마는 gateway가 현재 manifest 레지스트리를 로드할 수 있을 때 병합됩니다. +- `pnpm config:docs:check`는 문서용 config 기준 아티팩트와 현재 스키마 표면 간의 드리프트를 감지합니다. -검증 실패 시: +검증에 실패하면: -- Gateway는 부팅되지 않습니다 -- 진단 명령만 동작합니다(`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) -- 정확한 문제를 보려면 `openclaw doctor`를 실행하세요 -- 수정을 적용하려면 `openclaw doctor --fix`(또는 `--yes`)를 실행하세요 +- Gateway가 부팅되지 않음 +- 진단 명령만 작동함(`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) +- 정확한 문제를 확인하려면 `openclaw doctor` 실행 +- 수정을 적용하려면 `openclaw doctor --fix`(또는 `--yes`) 실행 ## 일반적인 작업 - - 각 채널은 `channels.` 아래에 자체 config 섹션을 가집니다. 설정 단계는 전용 채널 페이지를 참조하세요. + + 각 채널은 `channels.` 아래에 자체 구성 섹션을 가집니다. 설정 단계는 전용 채널 페이지를 참조하세요. - - [WhatsApp](/channels/whatsapp) — `channels.whatsapp` - - [Telegram](/channels/telegram) — `channels.telegram` - - [Discord](/channels/discord) — `channels.discord` - - [Feishu](/channels/feishu) — `channels.feishu` - - [Google Chat](/channels/googlechat) — `channels.googlechat` - - [Microsoft Teams](/channels/msteams) — `channels.msteams` - - [Slack](/channels/slack) — `channels.slack` - - [Signal](/channels/signal) — `channels.signal` - - [iMessage](/channels/imessage) — `channels.imessage` - - [Mattermost](/channels/mattermost) — `channels.mattermost` + - [WhatsApp](/ko/channels/whatsapp) — `channels.whatsapp` + - [Telegram](/ko/channels/telegram) — `channels.telegram` + - [Discord](/ko/channels/discord) — `channels.discord` + - [Feishu](/ko/channels/feishu) — `channels.feishu` + - [Google Chat](/ko/channels/googlechat) — `channels.googlechat` + - [Microsoft Teams](/ko/channels/msteams) — `channels.msteams` + - [Slack](/ko/channels/slack) — `channels.slack` + - [Signal](/ko/channels/signal) — `channels.signal` + - [iMessage](/ko/channels/imessage) — `channels.imessage` + - [Mattermost](/ko/channels/mattermost) — `channels.mattermost` 모든 채널은 동일한 DM 정책 패턴을 공유합니다. @@ -134,7 +128,7 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 - 기본 모델과 선택적 폴백을 설정하세요. + 기본 모델과 선택적 폴백을 설정합니다. ```json5 { @@ -153,30 +147,30 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 } ``` - - `agents.defaults.models`는 모델 카탈로그를 정의하며 `/model`의 allowlist 역할도 합니다. + - `agents.defaults.models`는 모델 카탈로그를 정의하며 `/model`의 허용 목록 역할도 합니다. - 모델 참조는 `provider/model` 형식을 사용합니다(예: `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx`는 기록/도구 이미지 다운스케일링을 제어합니다(기본값 `1200`). 값이 낮을수록 스크린샷이 많은 실행에서 비전 토큰 사용량이 줄어드는 경우가 많습니다. - - 채팅에서 모델 전환은 [Models CLI](/concepts/models)를, 인증 회전 및 폴백 동작은 [Model Failover](/concepts/model-failover)를 참조하세요. - - 커스텀/self-hosted providers는 참조 문서의 [Custom providers](/gateway/configuration-reference#custom-providers-and-base-urls)를 참조하세요. + - `agents.defaults.imageMaxDimensionPx`는 transcript/tool 이미지 축소 크기 조정을 제어합니다(기본값 `1200`). 값을 낮추면 스크린샷이 많은 실행에서 일반적으로 비전 토큰 사용량이 줄어듭니다. + - 채팅에서 모델 전환은 [Models CLI](/ko/concepts/models), 인증 순환 및 폴백 동작은 [Model Failover](/ko/concepts/model-failover)를 참조하세요. + - 사용자 지정/자체 호스팅 provider는 참조 문서의 [사용자 지정 provider](/ko/gateway/configuration-reference#custom-providers-and-base-urls)를 참조하세요. - DM 액세스는 채널별 `dmPolicy`로 제어됩니다. + DM 접근은 채널별로 `dmPolicy`를 통해 제어됩니다. - - `"pairing"` (기본값): 알 수 없는 발신자는 승인할 일회용 페어링 코드를 받습니다 - - `"allowlist"`: `allowFrom`(또는 페어링 allow 저장소)에 있는 발신자만 허용 + - `"pairing"` (기본값): 알 수 없는 발신자는 승인을 위한 일회성 페어링 코드를 받음 + - `"allowlist"`: `allowFrom`(또는 페어링된 허용 저장소)에 있는 발신자만 허용 - `"open"`: 모든 수신 DM 허용(`allowFrom: ["*"]` 필요) - `"disabled"`: 모든 DM 무시 - 그룹의 경우 `groupPolicy` + `groupAllowFrom` 또는 채널별 allowlist를 사용하세요. + 그룹의 경우 `groupPolicy` + `groupAllowFrom` 또는 채널별 허용 목록을 사용하세요. - 채널별 세부 사항은 [full reference](/gateway/configuration-reference#dm-and-group-access)를 참조하세요. + 채널별 세부 사항은 [전체 참조](/ko/gateway/configuration-reference#dm-and-group-access)를 참조하세요. - - 그룹 메시지는 기본적으로 **mention 필요**입니다. 에이전트별로 패턴을 구성하세요. + + 그룹 메시지는 기본적으로 **멘션 필요**입니다. 에이전트별 패턴을 구성하세요. ```json5 { @@ -198,15 +192,14 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 } ``` - - **메타데이터 mention**: 네이티브 @mention(WhatsApp 탭-투-멘션, Telegram @bot 등) + - **메타데이터 멘션**: 네이티브 @멘션(WhatsApp 탭하여 멘션, Telegram @bot 등) - **텍스트 패턴**: `mentionPatterns`의 안전한 정규식 패턴 - - 채널별 재정의 및 self-chat mode는 [full reference](/gateway/configuration-reference#group-chat-mention-gating)를 참조하세요. + - 채널별 재정의와 self-chat 모드는 [전체 참조](/ko/gateway/configuration-reference#group-chat-mention-gating)를 참조하세요. - 공유 기준선에는 `agents.defaults.skills`를 사용하고, 특정 - 에이전트 재정의에는 `agents.list[].skills`를 사용하세요. + 공유 기준선에는 `agents.defaults.skills`를 사용하고, 특정 에이전트는 `agents.list[].skills`로 재정의하세요. ```json5 { @@ -223,11 +216,10 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 } ``` - - 기본적으로 Skills를 제한하지 않으려면 `agents.defaults.skills`를 생략하세요. + - 기본적으로 제한 없는 Skills를 원하면 `agents.defaults.skills`를 생략하세요. - 기본값을 상속하려면 `agents.list[].skills`를 생략하세요. - - Skills를 사용하지 않으려면 `agents.list[].skills: []`를 설정하세요. - - [Skills](/tools/skills), [Skills config](/tools/skills-config), 그리고 - [Configuration Reference](/gateway/configuration-reference#agentsdefaultsskills)를 참조하세요. + - Skills가 없도록 하려면 `agents.list[].skills: []`를 설정하세요. + - [Skills](/ko/tools/skills), [Skills config](/ko/tools/skills-config), 그리고 [구성 참조](/ko/gateway/configuration-reference#agentsdefaultsskills)를 참조하세요. @@ -256,13 +248,13 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 - 전역적으로 상태 모니터 재시작을 비활성화하려면 `gateway.channelHealthCheckMinutes: 0`을 설정하세요. - `channelStaleEventThresholdMinutes`는 검사 간격보다 크거나 같아야 합니다. - - 전역 모니터를 끄지 않고 특정 채널 또는 account의 자동 재시작을 비활성화하려면 `channels..healthMonitor.enabled` 또는 `channels..accounts..healthMonitor.enabled`를 사용하세요. - - 운영 디버깅은 [Health Checks](/gateway/health), 모든 field는 [full reference](/gateway/configuration-reference#gateway)를 참조하세요. + - 전역 모니터를 끄지 않고 특정 채널 또는 계정의 자동 재시작만 끄려면 `channels..healthMonitor.enabled` 또는 `channels..accounts..healthMonitor.enabled`를 사용하세요. + - 운영 디버깅은 [상태 검사](/ko/gateway/health), 모든 필드는 [전체 참조](/ko/gateway/configuration-reference#gateway)를 참조하세요. - 세션은 대화 연속성과 격리를 제어합니다. + 세션은 대화의 연속성과 격리를 제어합니다. ```json5 { @@ -283,9 +275,9 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 ``` - `dmScope`: `main` (공유) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: 스레드 바인딩 세션 라우팅용 전역 기본값(Discord는 `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` 지원). - - 범위, identity 링크, 전송 정책은 [Session Management](/concepts/session)를 참조하세요. - - 모든 field는 [full reference](/gateway/configuration-reference#session)를 참조하세요. + - `threadBindings`: 스레드 바인딩 세션 라우팅의 전역 기본값(Discord는 `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` 지원). + - 범위, identity 링크, send 정책은 [세션 관리](/ko/concepts/session)를 참조하세요. + - 모든 필드는 [전체 참조](/ko/gateway/configuration-reference#session)를 참조하세요. @@ -307,12 +299,12 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 먼저 이미지를 빌드하세요: `scripts/sandbox-setup.sh` - 전체 가이드는 [Sandboxing](/gateway/sandboxing), 모든 옵션은 [full reference](/gateway/configuration-reference#agentsdefaultssandbox)를 참조하세요. + 전체 가이드는 [샌드박싱](/ko/gateway/sandboxing), 모든 옵션은 [전체 참조](/ko/gateway/configuration-reference#agentsdefaultssandbox)를 참조하세요. - - Relay 기반 push는 `openclaw.json`에서 구성합니다. + + relay 기반 푸시는 `openclaw.json`에서 구성합니다. gateway config에 다음을 설정하세요. @@ -338,37 +330,37 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com ``` - 이것이 하는 일: + 이 설정의 역할: - gateway가 외부 relay를 통해 `push.test`, wake nudges, reconnect wakes를 보낼 수 있게 합니다. - - 페어링된 iOS 앱이 전달한 registration 범위 send grant를 사용합니다. gateway에는 배포 전역 relay 토큰이 필요하지 않습니다. - - 각 relay 기반 registration을 iOS 앱이 페어링한 gateway identity에 바인딩하므로 다른 gateway가 저장된 registration을 재사용할 수 없습니다. - - 로컬/수동 iOS 빌드는 direct APNs를 계속 사용합니다. Relay 기반 전송은 relay를 통해 등록한 공식 배포 빌드에만 적용됩니다. - - registration과 send 트래픽이 동일한 relay 배포에 도달하도록, 공식/TestFlight iOS 빌드에 내장된 relay base URL과 일치해야 합니다. + - 페어링된 iOS 앱이 전달한 등록 범위 send grant를 사용합니다. gateway에는 배포 전체 범위의 relay 토큰이 필요하지 않습니다. + - 각 relay 기반 등록을 iOS 앱이 페어링한 gateway identity에 바인딩하므로, 다른 gateway는 저장된 등록을 재사용할 수 없습니다. + - 로컬/수동 iOS 빌드는 direct APNs를 유지합니다. relay 기반 전송은 relay를 통해 등록된 공식 배포 빌드에만 적용됩니다. + - 등록 및 전송 트래픽이 동일한 relay 배포에 도달하도록, 공식/TestFlight iOS 빌드에 내장된 relay base URL과 일치해야 합니다. - 엔드투엔드 흐름: + 종단 간 흐름: 1. 동일한 relay base URL로 컴파일된 공식/TestFlight iOS 빌드를 설치합니다. - 2. gateway에 `gateway.push.apns.relay.baseUrl`을 구성합니다. - 3. iOS 앱을 gateway에 페어링하고 node 및 operator 세션이 모두 연결되도록 합니다. - 4. iOS 앱은 gateway identity를 가져오고, App Attest와 앱 영수증을 사용해 relay에 등록한 뒤, relay 기반 `push.apns.register` 페이로드를 페어링된 gateway에 게시합니다. - 5. gateway는 relay handle과 send grant를 저장한 뒤, 이를 `push.test`, wake nudges, reconnect wakes에 사용합니다. + 2. gateway에서 `gateway.push.apns.relay.baseUrl`을 구성합니다. + 3. iOS 앱을 gateway에 페어링하고 node 세션과 operator 세션이 모두 연결되도록 합니다. + 4. iOS 앱은 gateway identity를 가져오고, App Attest와 앱 영수증을 사용해 relay에 등록한 다음, relay 기반 `push.apns.register` 페이로드를 페어링된 gateway에 게시합니다. + 5. gateway는 relay 핸들과 send grant를 저장하고, 이를 `push.test`, wake nudges, reconnect wakes에 사용합니다. - 운영 참고: + 운영 참고 사항: - - iOS 앱을 다른 gateway로 전환하면 앱을 다시 연결하여 새 gateway에 바인딩된 새 relay registration을 게시하게 하세요. - - 다른 relay 배포를 가리키는 새 iOS 빌드를 배포하면, 앱은 이전 relay origin을 재사용하는 대신 캐시된 relay registration을 새로 고칩니다. + - iOS 앱을 다른 gateway로 전환하는 경우, 앱이 해당 gateway에 바인딩된 새 relay 등록을 게시할 수 있도록 다시 연결하세요. + - 다른 relay 배포를 가리키는 새 iOS 빌드를 배포하는 경우, 앱은 이전 relay origin을 재사용하는 대신 캐시된 relay 등록을 갱신합니다. 호환성 참고: - - `OPENCLAW_APNS_RELAY_BASE_URL`과 `OPENCLAW_APNS_RELAY_TIMEOUT_MS`는 여전히 임시 env 재정의로 작동합니다. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`는 loopback 전용 개발용 탈출구로 유지됩니다. HTTP relay URL을 config에 영구 저장하지 마세요. + - `OPENCLAW_APNS_RELAY_BASE_URL` 및 `OPENCLAW_APNS_RELAY_TIMEOUT_MS`는 여전히 임시 env 재정의로 동작합니다. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`는 계속 loopback 전용 개발용 탈출구로 남아 있으며, config에 HTTP relay URL을 영구 저장해서는 안 됩니다. - 엔드투엔드 흐름은 [iOS App](/platforms/ios#relay-backed-push-for-official-builds), relay 보안 모델은 [Authentication and trust flow](/platforms/ios#authentication-and-trust-flow)를 참조하세요. + 종단 간 흐름은 [iOS 앱](/ko/platforms/ios#relay-backed-push-for-official-builds), relay 보안 모델은 [인증 및 신뢰 흐름](/ko/platforms/ios#authentication-and-trust-flow)을 참조하세요. - + ```json5 { agents: { @@ -384,8 +376,8 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 - `every`: 기간 문자열(`30m`, `2h`). 비활성화하려면 `0m` 설정. - `target`: `last` | `none` | `` (예: `discord`, `matrix`, `telegram`, `whatsapp`) - - `directPolicy`: `allow` (기본값) 또는 DM 스타일 heartbeat 대상에는 `block` - - 전체 가이드는 [Heartbeat](/gateway/heartbeat)를 참조하세요. + - `directPolicy`: DM 스타일 heartbeat 대상에 대해 `allow`(기본값) 또는 `block` + - 전체 가이드는 [Heartbeat](/ko/gateway/heartbeat)를 참조하세요. @@ -404,13 +396,13 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 } ``` - - `sessionRetention`: 완료된 격리 실행 세션을 `sessions.json`에서 정리합니다(기본값 `24h`; 비활성화하려면 `false`). - - `runLog`: 크기와 보존 줄 수를 기준으로 `cron/runs/.jsonl` 정리. - - 기능 개요와 CLI 예시는 [Cron jobs](/automation/cron-jobs)를 참조하세요. + - `sessionRetention`: 완료된 격리 실행 세션을 `sessions.json`에서 정리합니다(기본값 `24h`; 비활성화하려면 `false` 설정). + - `runLog`: 크기와 유지할 줄 수 기준으로 `cron/runs/.jsonl`을 정리합니다. + - 기능 개요와 CLI 예시는 [Cron 작업](/ko/automation/cron-jobs)을 참조하세요. - + Gateway에서 HTTP webhook 엔드포인트를 활성화합니다. ```json5 @@ -435,20 +427,20 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 ``` 보안 참고: - - 모든 hook/webhook 페이로드 콘텐츠는 신뢰되지 않은 입력으로 취급하세요. + - 모든 hook/webhook 페이로드 콘텐츠는 신뢰할 수 없는 입력으로 취급하세요. - 전용 `hooks.token`을 사용하세요. 공유 Gateway 토큰을 재사용하지 마세요. - Hook 인증은 헤더 전용입니다(`Authorization: Bearer ...` 또는 `x-openclaw-token`). 쿼리 문자열 토큰은 거부됩니다. - - `hooks.path`는 `/`가 될 수 없습니다. webhook 유입은 `/hooks` 같은 전용 하위 경로에 두세요. - - tightly scoped debugging이 아닌 한, 안전하지 않은 콘텐츠 우회 플래그(`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`)는 비활성화 상태로 유지하세요. - - `hooks.allowRequestSessionKey`를 활성화한다면 `hooks.allowedSessionKeyPrefixes`도 함께 설정해 호출자가 선택한 session key 범위를 제한하세요. - - hook 기반 에이전트에는 강한 최신 모델 티어와 엄격한 도구 정책(예: 가능한 경우 메시징 전용 + 샌드박싱)을 권장합니다. + - `hooks.path`는 `/`가 될 수 없습니다. webhook 수신은 `/hooks` 같은 전용 하위 경로에 유지하세요. + - 엄격히 범위가 제한된 디버깅이 아닌 한, 안전하지 않은 콘텐츠 우회 플래그(`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`)는 비활성화된 상태로 유지하세요. + - `hooks.allowRequestSessionKey`를 활성화하는 경우, 호출자가 선택하는 세션 키의 범위를 제한하도록 `hooks.allowedSessionKeyPrefixes`도 설정하세요. + - hook 기반 에이전트에는 가능한 경우 강력한 최신 모델 등급과 엄격한 도구 정책(예: 메시징 전용 + 샌드박싱)을 권장합니다. - 모든 매핑 옵션과 Gmail 통합은 [full reference](/gateway/configuration-reference#hooks)를 참조하세요. + 모든 매핑 옵션과 Gmail 통합은 [전체 참조](/ko/gateway/configuration-reference#hooks)를 참조하세요. - 별도의 workspaces와 세션을 가진 여러 격리 에이전트를 실행합니다. + 별도의 워크스페이스와 세션을 사용하는 여러 격리된 에이전트를 실행합니다. ```json5 { @@ -465,12 +457,12 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 } ``` - 바인딩 규칙과 에이전트별 액세스 프로필은 [Multi-Agent](/concepts/multi-agent) 및 [full reference](/gateway/configuration-reference#multi-agent-routing)를 참조하세요. + 바인딩 규칙과 에이전트별 액세스 프로필은 [다중 에이전트](/ko/concepts/multi-agent)와 [전체 참조](/ko/gateway/configuration-reference#multi-agent-routing)를 참조하세요. - - 큰 configs를 정리하려면 `$include`를 사용하세요. + + 큰 구성을 정리하려면 `$include`를 사용하세요. ```json5 // ~/.openclaw/openclaw.json @@ -484,27 +476,27 @@ OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 ``` - **단일 파일**: 포함하는 객체를 대체 - - **파일 배열**: 순서대로 깊은 병합(나중 항목 우선) - - **형제 키**: include 뒤에 병합됨(포함된 값 재정의) + - **파일 배열**: 순서대로 깊은 병합(나중 것이 우선) + - **형제 키**: include 이후 병합됨(포함된 값 재정의) - **중첩 include**: 최대 10단계까지 지원 - - **상대 경로**: 포함하는 파일 기준으로 해석 - - **오류 처리**: 누락 파일, 파싱 오류, 순환 include에 대해 명확한 오류 제공 + - **상대 경로**: 포함하는 파일을 기준으로 해석 + - **오류 처리**: 누락된 파일, 구문 분석 오류, 순환 include에 대해 명확한 오류 제공 -## Config 핫 리로드 +## config 핫 리로드 -Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동 적용합니다 — 대부분의 설정에는 수동 재시작이 필요하지 않습니다. +Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동으로 적용합니다 — 대부분의 설정에는 수동 재시작이 필요하지 않습니다. ### 리로드 모드 -| 모드 | 동작 | -| ---------------------- | ------------------------------------------------------------------------------------ | -| **`hybrid`** (기본값) | 안전한 변경은 즉시 핫 적용합니다. 중요한 변경은 자동으로 재시작합니다. | -| **`hot`** | 안전한 변경만 핫 적용합니다. 재시작이 필요할 때 경고를 기록하며 직접 처리해야 합니다. | -| **`restart`** | 안전 여부와 관계없이 모든 config 변경 시 Gateway를 재시작합니다. | -| **`off`** | 파일 감시를 비활성화합니다. 변경은 다음 수동 재시작 때 적용됩니다. | +| 모드 | 동작 | +| ---------------------- | --------------------------------------------------------------------------------------- | +| **`hybrid`** (기본값) | 안전한 변경은 즉시 핫 적용합니다. 중요한 변경은 자동으로 재시작합니다. | +| **`hot`** | 안전한 변경만 핫 적용합니다. 재시작이 필요하면 경고를 기록하며, 처리는 사용자가 해야 합니다. | +| **`restart`** | 안전 여부와 관계없이 모든 config 변경 시 Gateway를 재시작합니다. | +| **`off`** | 파일 감시를 비활성화합니다. 변경 사항은 다음 수동 재시작 시 적용됩니다. | ```json5 { @@ -516,44 +508,42 @@ Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동 ### 핫 적용되는 항목과 재시작이 필요한 항목 -대부분의 필드는 다운타임 없이 핫 적용됩니다. `hybrid` 모드에서는 재시작이 필요한 변경도 자동 처리됩니다. +대부분의 필드는 다운타임 없이 핫 적용됩니다. `hybrid` 모드에서는 재시작이 필요한 변경이 자동으로 처리됩니다. -| 범주 | 필드 | 재시작 필요? | -| ------------------- | -------------------------------------------------------------------- | ------------ | -| Channels | `channels.*`, `web` (WhatsApp) — 모든 내장 및 extension 채널 | 아니요 | -| Agent & models | `agent`, `agents`, `models`, `routing` | 아니요 | -| Automation | `hooks`, `cron`, `agent.heartbeat` | 아니요 | -| Sessions & messages | `session`, `messages` | 아니요 | -| Tools & media | `tools`, `browser`, `skills`, `audio`, `talk` | 아니요 | -| UI & misc | `ui`, `logging`, `identity`, `bindings` | 아니요 | -| Gateway server | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **예** | -| Infrastructure | `discovery`, `canvasHost`, `plugins` | **예** | +| 범주 | 필드 | 재시작 필요? | +| ------------------- | -------------------------------------------------------------------- | --------------- | +| 채널 | `channels.*`, `web` (WhatsApp) — 모든 내장 및 extension 채널 | 아니요 | +| 에이전트 및 모델 | `agent`, `agents`, `models`, `routing` | 아니요 | +| 자동화 | `hooks`, `cron`, `agent.heartbeat` | 아니요 | +| 세션 및 메시지 | `session`, `messages` | 아니요 | +| 도구 및 미디어 | `tools`, `browser`, `skills`, `audio`, `talk` | 아니요 | +| UI 및 기타 | `ui`, `logging`, `identity`, `bindings` | 아니요 | +| Gateway 서버 | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **예** | +| 인프라 | `discovery`, `canvasHost`, `plugins` | **예** | -`gateway.reload`와 `gateway.remote`는 예외입니다 — 이를 변경해도 **재시작이 트리거되지 않습니다**. +`gateway.reload`와 `gateway.remote`는 예외입니다 — 이를 변경해도 재시작이 트리거되지 않습니다. -## Config RPC (프로그래밍 방식 업데이트) +## config RPC (프로그래밍 방식 업데이트) -컨트롤 플레인 쓰기 RPC(`config.apply`, `config.patch`, `update.run`)는 `deviceId+clientIp` 기준으로 **60초당 3요청**으로 속도 제한됩니다. 제한되면 RPC는 `retryAfterMs`와 함께 `UNAVAILABLE`을 반환합니다. +control-plane 쓰기 RPC(`config.apply`, `config.patch`, `update.run`)는 `deviceId+clientIp`당 **60초마다 3회 요청**으로 속도 제한됩니다. 제한되면 RPC는 `retryAfterMs`와 함께 `UNAVAILABLE`을 반환합니다. -안전한/기본 흐름: +안전한 기본 흐름: -- `config.schema.lookup`: 얕은 - 스키마 노드, 일치하는 힌트 메타데이터, 즉시 자식 요약이 포함된 하나의 경로 범위 config 서브트리를 검사 +- `config.schema.lookup`: 얕은 스키마 노드, 일치하는 힌트 메타데이터, 즉시 하위 요약이 포함된 경로 범위 config 하위 트리 하나 검사 - `config.get`: 현재 스냅샷 + 해시 가져오기 - `config.patch`: 권장되는 부분 업데이트 경로 -- `config.apply`: 전체 config 교체 전용 -- `update.run`: 명시적인 self-update + 재시작 +- `config.apply`: 전체 config 교체 시에만 사용 +- `update.run`: 명시적 자체 업데이트 + 재시작 -전체 config를 교체하는 것이 아니라면 `config.schema.lookup` -다음 `config.patch`를 우선 사용하세요. +전체 config를 교체하는 것이 아니라면 `config.schema.lookup` 후 `config.patch`를 우선 사용하세요. - 전체 config를 검증 + 기록하고 한 번에 Gateway를 재시작합니다. + 전체 config를 검증 + 기록하고 Gateway를 한 단계로 재시작합니다. `config.apply`는 **전체 config**를 교체합니다. 부분 업데이트에는 `config.patch`, 단일 키에는 `openclaw config set`을 사용하세요. @@ -561,13 +551,13 @@ Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동 매개변수: - - `raw` (string) — 전체 config용 JSON5 페이로드 + - `raw` (string) — 전체 config에 대한 JSON5 페이로드 - `baseHash` (선택 사항) — `config.get`의 config 해시(config가 존재하면 필수) - - `sessionKey` (선택 사항) — 재시작 후 wake-up ping용 세션 키 - - `note` (선택 사항) — restart sentinel용 메모 - - `restartDelayMs` (선택 사항) — 재시작 전 지연(기본값 2000) + - `sessionKey` (선택 사항) — 재시작 후 wake-up ping을 위한 세션 키 + - `note` (선택 사항) — 재시작 센티널용 메모 + - `restartDelayMs` (선택 사항) — 재시작 전 지연 시간(기본값 2000) - 이미 재시작이 보류/진행 중인 동안의 재시작 요청은 병합되며, 재시작 주기 사이에는 30초 쿨다운이 적용됩니다. + 재시작 요청은 이미 보류 중/진행 중인 요청이 있으면 합쳐지며, 재시작 주기 사이에는 30초 쿨다운이 적용됩니다. ```bash openclaw gateway call config.get --params '{}' # payload.hash 캡처 @@ -581,10 +571,10 @@ Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동 - 기존 config에 부분 업데이트를 병합합니다(JSON merge patch 의미론). + 기존 config에 부분 업데이트를 병합합니다(JSON merge patch 의미 체계). - 객체는 재귀적으로 병합 - - `null`은 키 삭제 + - `null`은 키를 삭제 - 배열은 교체 매개변수: @@ -593,7 +583,7 @@ Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동 - `baseHash` (필수) — `config.get`의 config 해시 - `sessionKey`, `note`, `restartDelayMs` — `config.apply`와 동일 - 재시작 동작은 `config.apply`와 동일합니다: 보류 중 재시작 병합 + 재시작 주기 간 30초 쿨다운. + 재시작 동작은 `config.apply`와 동일합니다. 보류 중인 재시작은 합쳐지며 재시작 주기 사이에는 30초 쿨다운이 적용됩니다. ```bash openclaw gateway call config.patch --params '{ @@ -607,12 +597,12 @@ Gateway는 `~/.openclaw/openclaw.json`을 감시하고 변경 사항을 자동 ## 환경 변수 -OpenClaw는 부모 프로세스의 env와 다음 위치를 읽습니다. +OpenClaw는 상위 프로세스의 env vars와 함께 다음도 읽습니다. -- 현재 작업 디렉터리의 `.env`(있을 경우) -- `~/.openclaw/.env` (전역 폴백) +- 현재 작업 디렉터리의 `.env`(존재하는 경우) +- `~/.openclaw/.env`(전역 폴백) -어느 파일도 기존 env vars를 재정의하지 않습니다. config에서 인라인 env vars를 설정할 수도 있습니다. +두 파일 모두 기존 env vars를 재정의하지 않습니다. config에서 인라인 env vars도 설정할 수 있습니다. ```json5 { @@ -623,8 +613,8 @@ OpenClaw는 부모 프로세스의 env와 다음 위치를 읽습니다. } ``` - - 활성화되어 있고 예상 키가 설정되지 않은 경우, OpenClaw는 로그인 셸을 실행해 누락된 키만 가져옵니다. + + 활성화되어 있고 예상 키가 설정되지 않은 경우, OpenClaw는 로그인 셸을 실행하고 누락된 키만 가져옵니다. ```json5 { @@ -637,8 +627,8 @@ OpenClaw는 부모 프로세스의 env와 다음 위치를 읽습니다. Env var 동등값: `OPENCLAW_LOAD_SHELL_ENV=1` - - `${VAR_NAME}`을 사용해 모든 config 문자열 값에서 env vars를 참조할 수 있습니다. + + `${VAR_NAME}`으로 모든 config 문자열 값에서 env vars를 참조할 수 있습니다. ```json5 { @@ -649,7 +639,7 @@ Env var 동등값: `OPENCLAW_LOAD_SHELL_ENV=1` 규칙: -- 대문자 이름만 매칭됨: `[A-Z_][A-Z0-9_]*` +- 대문자 이름만 일치: `[A-Z_][A-Z0-9_]*` - 누락되었거나 비어 있는 vars는 로드 시 오류를 발생시킴 - 리터럴 출력은 `$${VAR}`로 이스케이프 - `$include` 파일 내부에서도 동작 @@ -658,7 +648,7 @@ Env var 동등값: `OPENCLAW_LOAD_SHELL_ENV=1` - SecretRef 객체를 지원하는 필드에는 다음을 사용할 수 있습니다. + SecretRef 객체를 지원하는 필드에서는 다음을 사용할 수 있습니다. ```json5 { @@ -690,16 +680,16 @@ Env var 동등값: `OPENCLAW_LOAD_SHELL_ENV=1` } ``` -SecretRef 세부 사항(`env`/`file`/`exec`용 `secrets.providers` 포함)은 [Secrets Management](/gateway/secrets)에 있습니다. -지원되는 자격 증명 경로는 [SecretRef Credential Surface](/reference/secretref-credential-surface)에 나열되어 있습니다. +SecretRef 세부 사항(`env`/`file`/`exec`용 `secrets.providers` 포함)은 [Secrets Management](/ko/gateway/secrets)에 있습니다. +지원되는 자격 증명 경로는 [SecretRef Credential Surface](/ko/reference/secretref-credential-surface)에 나열되어 있습니다. -전체 우선순위와 소스는 [Environment](/help/environment)를 참조하세요. +전체 우선순위와 소스는 [환경](/ko/help/environment)를 참조하세요. ## 전체 참조 -필드별 완전한 참조는 **[Configuration Reference](/gateway/configuration-reference)**를 참조하세요. +완전한 필드별 참조는 **[구성 참조](/ko/gateway/configuration-reference)**를 확인하세요. --- -_관련 문서: [Configuration Examples](/gateway/configuration-examples) · [Configuration Reference](/gateway/configuration-reference) · [Doctor](/gateway/doctor)_ +_관련 항목: [구성 예시](/ko/gateway/configuration-examples) · [구성 참조](/ko/gateway/configuration-reference) · [Doctor](/ko/gateway/doctor)_ diff --git a/docs/ko/plugins/memory-wiki.md b/docs/ko/plugins/memory-wiki.md new file mode 100644 index 000000000..44e68f248 --- /dev/null +++ b/docs/ko/plugins/memory-wiki.md @@ -0,0 +1,362 @@ +--- +read_when: + - 단순한 MEMORY.md 노트를 넘어서는 지속적인 지식을 원할 때 + - 번들된 memory-wiki plugin을 구성하고 있을 때 + - wiki_search, wiki_get 또는 브리지 모드를 이해하고 싶을 때 +summary: 'memory-wiki: 출처, 클레임, 대시보드, 브리지 모드를 갖춘 컴파일된 지식 볼트' +title: 메모리 위키 +x-i18n: + generated_at: "2026-04-08T05:56:05Z" + model: gpt-5.4 + provider: openai + source_hash: b78dd6a4ef4451dae6b53197bf0c7c2a2ba846b08e4a3a93c1026366b1598d82 + source_path: plugins/memory-wiki.md + workflow: 15 +--- + +# 메모리 위키 + +`memory-wiki`는 지속 가능한 메모리를 컴파일된 지식 볼트로 바꿔 주는 번들 plugin입니다. + +이 plugin은 활성 메모리 plugin을 **대체하지 않습니다**. 활성 메모리 plugin은 여전히 +회상, 승격, 인덱싱, dreaming을 담당합니다. `memory-wiki`는 그 옆에서 +작동하며, 지속 가능한 지식을 탐색 가능한 위키로 컴파일해 결정적인 페이지, +구조화된 클레임, 출처, 대시보드, 기계가 읽을 수 있는 다이제스트를 제공합니다. + +메모리가 Markdown 파일 더미처럼 작동하기보다 유지 관리되는 지식 계층처럼 +작동하길 원한다면 이것을 사용하세요. + +## 추가되는 기능 + +- 결정적인 페이지 레이아웃을 갖춘 전용 위키 볼트 +- 단순한 산문이 아닌 구조화된 클레임 및 증거 메타데이터 +- 페이지 수준의 출처, 신뢰도, 모순, 미해결 질문 +- 에이전트/런타임 소비자를 위한 컴파일된 다이제스트 +- 위키 전용 search/get/apply/lint 도구 +- 활성 메모리 plugin의 공개 아티팩트를 가져오는 선택적 브리지 모드 +- 선택적 Obsidian 친화적 렌더 모드 및 CLI 통합 + +## 메모리와의 관계 + +이 구분은 다음과 같이 생각하면 됩니다: + +| 계층 | 담당 | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| 활성 메모리 plugin (`memory-core`, QMD, Honcho 등) | 회상, 시맨틱 검색, 승격, dreaming, 메모리 런타임 | +| `memory-wiki` | 컴파일된 위키 페이지, 출처가 풍부한 종합, 대시보드, 위키 전용 search/get/apply | + +활성 메모리 plugin이 공유 회상 아티팩트를 노출하면 OpenClaw는 +`memory_search corpus=all`로 한 번에 두 계층을 모두 검색할 수 있습니다. + +위키 전용 순위 지정, 출처, 또는 직접 페이지 접근이 필요할 때는 +대신 위키 전용 도구를 사용하세요. + +## 볼트 모드 + +`memory-wiki`는 세 가지 볼트 모드를 지원합니다: + +### `isolated` + +자체 볼트, 자체 소스, `memory-core`에 대한 의존성 없음. + +위키를 자체적으로 큐레이션된 지식 저장소로 사용하고 싶다면 이 모드를 사용하세요. + +### `bridge` + +활성 메모리 plugin의 공개 메모리 아티팩트와 메모리 이벤트를 +공개 plugin SDK 경계를 통해 읽습니다. + +메모리 plugin의 내보낸 아티팩트를 private plugin 내부 구현에 접근하지 않고 +위키에서 컴파일하고 정리하고 싶다면 이 모드를 사용하세요. + +브리지 모드는 다음을 인덱싱할 수 있습니다: + +- 내보낸 메모리 아티팩트 +- dream 보고서 +- 일일 노트 +- 메모리 루트 파일 +- 메모리 이벤트 로그 + +### `unsafe-local` + +로컬 private 경로를 위한, 동일 머신에서만 사용하는 명시적 탈출구입니다. + +이 모드는 의도적으로 실험적이며 이식성이 없습니다. 신뢰 경계를 이해하고, +브리지 모드로는 제공할 수 없는 로컬 파일 시스템 접근이 꼭 필요할 때만 +사용하세요. + +## 볼트 레이아웃 + +plugin은 다음과 같은 볼트를 초기화합니다: + +```text +/ + AGENTS.md + WIKI.md + index.md + inbox.md + entities/ + concepts/ + syntheses/ + sources/ + reports/ + _attachments/ + _views/ + .openclaw-wiki/ +``` + +관리되는 콘텐츠는 생성된 블록 내부에 유지됩니다. 사람이 작성한 노트 블록은 보존됩니다. + +주요 페이지 그룹은 다음과 같습니다: + +- `sources/`: 가져온 원본 자료와 브리지 기반 페이지 +- `entities/`: 지속적인 사물, 사람, 시스템, 프로젝트, 객체 +- `concepts/`: 아이디어, 추상화, 패턴, 정책 +- `syntheses/`: 컴파일된 요약과 유지 관리되는 롤업 +- `reports/`: 생성된 대시보드 + +## 구조화된 클레임과 증거 + +페이지는 자유 형식 텍스트만이 아니라 구조화된 `claims` frontmatter를 가질 수 있습니다. + +각 클레임에는 다음이 포함될 수 있습니다: + +- `id` +- `text` +- `status` +- `confidence` +- `evidence[]` +- `updatedAt` + +증거 항목에는 다음이 포함될 수 있습니다: + +- `sourceId` +- `path` +- `lines` +- `weight` +- `note` +- `updatedAt` + +이것이 위키를 수동적인 노트 덤프가 아니라 신념 계층처럼 작동하게 만듭니다. +클레임은 추적, 점수화, 이의 제기, 소스로의 해결이 가능합니다. + +## 컴파일 파이프라인 + +컴파일 단계는 위키 페이지를 읽고, 요약을 정규화한 뒤, 안정적인 +기계 지향 아티팩트를 다음 경로에 출력합니다: + +- `.openclaw-wiki/cache/agent-digest.json` +- `.openclaw-wiki/cache/claims.jsonl` + +이 다이제스트는 에이전트와 런타임 코드가 Markdown 페이지를 직접 +스크래핑하지 않아도 되도록 존재합니다. + +컴파일된 출력은 다음에도 사용됩니다: + +- search/get 흐름을 위한 1차 위키 인덱싱 +- 소유 페이지로의 claim-id 조회 +- 간결한 프롬프트 보조 정보 +- 보고서/대시보드 생성 + +## 대시보드와 상태 보고서 + +`render.createDashboards`가 활성화되면, 컴파일은 `reports/` 아래에 +대시보드를 유지합니다. + +기본 제공 보고서는 다음과 같습니다: + +- `reports/open-questions.md` +- `reports/contradictions.md` +- `reports/low-confidence.md` +- `reports/claim-health.md` +- `reports/stale-pages.md` + +이 보고서는 다음과 같은 항목을 추적합니다: + +- 모순 노트 클러스터 +- 경쟁하는 클레임 클러스터 +- 구조화된 증거가 없는 클레임 +- 신뢰도가 낮은 페이지와 클레임 +- 오래되었거나 최신성 정보를 알 수 없는 항목 +- 해결되지 않은 질문이 있는 페이지 + +## 검색 및 조회 + +`memory-wiki`는 두 가지 검색 백엔드를 지원합니다: + +- `shared`: 가능할 때 공유 메모리 검색 흐름 사용 +- `local`: 위키를 로컬에서 검색 + +또한 세 가지 corpus를 지원합니다: + +- `wiki` +- `memory` +- `all` + +중요한 동작: + +- `wiki_search`와 `wiki_get`은 가능할 때 컴파일된 다이제스트를 1차 단계로 사용합니다 +- claim id는 소유 페이지로 다시 해석될 수 있습니다 +- 이의 제기됨/오래됨/최신 클레임이 순위에 영향을 줍니다 +- 출처 라벨은 결과까지 유지될 수 있습니다 + +실용적인 규칙: + +- 폭넓은 한 번의 회상 패스에는 `memory_search corpus=all`을 사용하세요 +- 위키 전용 순위 지정, 출처, 페이지 수준의 신념 구조가 중요할 때는 `wiki_search` + `wiki_get`을 사용하세요 + +## 에이전트 도구 + +plugin은 다음 도구를 등록합니다: + +- `wiki_status` +- `wiki_search` +- `wiki_get` +- `wiki_apply` +- `wiki_lint` + +각 도구의 역할: + +- `wiki_status`: 현재 볼트 모드, 상태, Obsidian CLI 사용 가능 여부 +- `wiki_search`: 위키 페이지를 검색하고, 구성된 경우 공유 메모리 corpus도 검색 +- `wiki_get`: id/path로 위키 페이지를 읽거나 공유 메모리 corpus로 폴백 +- `wiki_apply`: 자유 형식 페이지 수술 없이 좁은 범위의 종합/메타데이터 변경 수행 +- `wiki_lint`: 구조 검사, 출처 공백, 모순, 미해결 질문 확인 + +또한 이 plugin은 비독점적 메모리 corpus 보조 기능도 등록하므로, 활성 메모리 +plugin이 corpus 선택을 지원할 경우 공유 `memory_search`와 `memory_get`이 +위키에 도달할 수 있습니다. + +## 프롬프트 및 컨텍스트 동작 + +`context.includeCompiledDigestPrompt`가 활성화되면, 메모리 프롬프트 섹션은 +`agent-digest.json`의 간결한 컴파일 스냅샷을 덧붙입니다. + +그 스냅샷은 의도적으로 작고 신호 대비 잡음이 적습니다: + +- 상위 페이지만 +- 상위 클레임만 +- 모순 개수 +- 질문 개수 +- 신뢰도/최신성 한정자 + +이 옵션은 프롬프트 형태를 바꾸며, 메모리 보조 정보를 명시적으로 소비하는 +컨텍스트 엔진이나 레거시 프롬프트 조립에 주로 유용하기 때문에 opt-in입니다. + +## 구성 + +구성은 `plugins.entries.memory-wiki.config` 아래에 두세요: + +```json5 +{ + plugins: { + entries: { + "memory-wiki": { + enabled: true, + config: { + vaultMode: "isolated", + vault: { + path: "~/.openclaw/wiki/main", + renderMode: "obsidian", + }, + obsidian: { + enabled: true, + useOfficialCli: true, + vaultName: "OpenClaw Wiki", + openAfterWrites: false, + }, + bridge: { + enabled: false, + readMemoryArtifacts: true, + indexDreamReports: true, + indexDailyNotes: true, + indexMemoryRoot: true, + followMemoryEvents: true, + }, + ingest: { + autoCompile: true, + maxConcurrentJobs: 1, + allowUrlIngest: true, + }, + search: { + backend: "shared", + corpus: "wiki", + }, + context: { + includeCompiledDigestPrompt: false, + }, + render: { + preserveHumanBlocks: true, + createBacklinks: true, + createDashboards: true, + }, + }, + }, + }, + }, +} +``` + +주요 토글: + +- `vaultMode`: `isolated`, `bridge`, `unsafe-local` +- `vault.renderMode`: `native` 또는 `obsidian` +- `bridge.readMemoryArtifacts`: 활성 메모리 plugin의 공개 아티팩트 가져오기 +- `bridge.followMemoryEvents`: 브리지 모드에서 이벤트 로그 포함 +- `search.backend`: `shared` 또는 `local` +- `search.corpus`: `wiki`, `memory`, 또는 `all` +- `context.includeCompiledDigestPrompt`: 메모리 프롬프트 섹션에 간결한 다이제스트 스냅샷 추가 +- `render.createBacklinks`: 결정적인 관련 블록 생성 +- `render.createDashboards`: 대시보드 페이지 생성 + +## CLI + +`memory-wiki`는 최상위 CLI 표면도 제공합니다: + +```bash +openclaw wiki status +openclaw wiki doctor +openclaw wiki init +openclaw wiki ingest ./notes/alpha.md +openclaw wiki compile +openclaw wiki lint +openclaw wiki search "alpha" +openclaw wiki get entity.alpha +openclaw wiki apply synthesis "Alpha Summary" --body "..." --source-id source.alpha +openclaw wiki bridge import +openclaw wiki obsidian status +``` + +전체 명령 참조는 [CLI: 위키](/cli/wiki)를 참조하세요. + +## Obsidian 지원 + +`vault.renderMode`가 `obsidian`이면, plugin은 Obsidian 친화적인 +Markdown을 작성하고 선택적으로 공식 `obsidian` CLI를 사용할 수 있습니다. + +지원되는 워크플로는 다음과 같습니다: + +- 상태 프로빙 +- 볼트 검색 +- 페이지 열기 +- Obsidian 명령 호출 +- 일일 노트로 이동 + +이 기능은 선택 사항입니다. 위키는 Obsidian 없이 native 모드에서도 계속 작동합니다. + +## 권장 워크플로 + +1. 회상/승격/dreaming에는 활성 메모리 plugin을 계속 사용하세요. +2. `memory-wiki`를 활성화하세요. +3. 브리지 모드를 명시적으로 원하지 않는 한 `isolated` 모드로 시작하세요. +4. 출처가 중요할 때는 `wiki_search` / `wiki_get`을 사용하세요. +5. 좁은 범위의 종합 또는 메타데이터 업데이트에는 `wiki_apply`를 사용하세요. +6. 의미 있는 변경 후에는 `wiki_lint`를 실행하세요. +7. 오래됨/모순 가시성이 필요하다면 대시보드를 켜세요. + +## 관련 문서 + +- [메모리 개요](/ko/concepts/memory) +- [CLI: memory](/cli/memory) +- [CLI: 위키](/cli/wiki) +- [Plugin SDK 개요](/ko/plugins/sdk-overview) diff --git a/docs/ko/providers/glm.md b/docs/ko/providers/glm.md index 142e71a49..014a9b0b3 100644 --- a/docs/ko/providers/glm.md +++ b/docs/ko/providers/glm.md @@ -1,58 +1,58 @@ --- read_when: - OpenClaw에서 GLM 모델을 사용하려는 경우 - - 모델 명명 규칙과 설정 방법이 필요한 경우 -summary: GLM 모델 패밀리 개요 + OpenClaw에서 사용하는 방법 + - 모델 명명 규칙과 설정이 필요한 경우 +summary: GLM 모델 패밀리 개요와 OpenClaw에서 사용하는 방법 title: GLM 모델 x-i18n: - generated_at: "2026-04-05T12:51:52Z" + generated_at: "2026-04-08T05:55:48Z" model: gpt-5.4 provider: openai - source_hash: 59622edab5094d991987f9788fbf08b33325e737e7ff88632b0c3ac89412d4c7 + source_hash: 79a55acfa139847b4b85dbc09f1068cbd2febb1e49f984a23ea9e3b43bc910eb source_path: providers/glm.md workflow: 15 --- # GLM 모델 -GLM은 Z.AI 플랫폼에서 제공되는 **모델 패밀리**(회사가 아님)입니다. OpenClaw에서 GLM -모델은 `zai` 제공자와 `zai/glm-5` 같은 모델 ID를 통해 사용합니다. +GLM은 Z.AI 플랫폼을 통해 사용할 수 있는 **모델 패밀리**(회사가 아님)입니다. OpenClaw에서 GLM +모델은 `zai` provider와 `zai/glm-5` 같은 모델 ID를 통해 액세스합니다. ## CLI 설정 ```bash -# 엔드포인트 자동 감지가 포함된 일반 API 키 설정 +# 엔드포인트 자동 감지를 사용하는 일반 API 키 설정 openclaw onboard --auth-choice zai-api-key -# Coding Plan Global, Coding Plan 사용자에게 권장 +# 코딩 플랜 Global, 코딩 플랜 사용자에게 권장 openclaw onboard --auth-choice zai-coding-global -# Coding Plan CN(중국 지역), Coding Plan 사용자에게 권장 +# 코딩 플랜 CN(중국 리전), 코딩 플랜 사용자에게 권장 openclaw onboard --auth-choice zai-coding-cn # 일반 API openclaw onboard --auth-choice zai-global -# 일반 API CN(중국 지역) +# 일반 API CN(중국 리전) openclaw onboard --auth-choice zai-cn ``` -## 설정 스니펫 +## 구성 스니펫 ```json5 { env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5" } } }, + agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, } ``` `zai-api-key`를 사용하면 OpenClaw가 키에서 일치하는 Z.AI 엔드포인트를 감지하고 -올바른 기본 URL을 자동으로 적용할 수 있습니다. 특정 Coding Plan 또는 일반 API 표면을 -강제로 사용하려면 명시적인 지역 선택지를 사용하세요. +올바른 기본 URL을 자동으로 적용할 수 있습니다. 특정 코딩 플랜 또는 일반 API 표면을 강제하려는 경우 +명시적인 지역 선택지를 사용하세요. ## 현재 번들된 GLM 모델 -OpenClaw는 현재 번들된 `zai` 제공자에 다음 GLM 참조를 시드합니다: +OpenClaw는 현재 번들된 `zai` provider에 다음 GLM ref를 시드합니다: - `glm-5.1` - `glm-5` @@ -71,5 +71,5 @@ OpenClaw는 현재 번들된 `zai` 제공자에 다음 GLM 참조를 시드합 ## 참고 - GLM 버전과 제공 여부는 변경될 수 있으므로 최신 정보는 Z.AI 문서를 확인하세요. -- 기본 번들 모델 참조는 `zai/glm-5`입니다. -- 제공자에 대한 자세한 내용은 [/providers/zai](/providers/zai)를 참고하세요. +- 기본 번들 모델 ref는 `zai/glm-5.1`입니다. +- provider 세부 정보는 [/providers/zai](/ko/providers/zai)를 참조하세요. diff --git a/docs/ko/providers/zai.md b/docs/ko/providers/zai.md index baa146d84..39a6f9dde 100644 --- a/docs/ko/providers/zai.md +++ b/docs/ko/providers/zai.md @@ -1,32 +1,34 @@ --- read_when: - OpenClaw에서 Z.AI / GLM 모델을 사용하려는 경우 - - 간단한 `ZAI_API_KEY` 설정이 필요한 경우 -summary: OpenClaw에서 Z.AI(GLM 모델)를 사용합니다 + - 간단한 ZAI_API_KEY 설정이 필요한 경우 +summary: OpenClaw에서 Z.AI(GLM 모델) 사용하기 title: Z.AI x-i18n: - generated_at: "2026-04-05T12:53:32Z" + generated_at: "2026-04-08T05:55:56Z" model: gpt-5.4 provider: openai - source_hash: 48006cdd580484f0c62e2877b27a6a68d7bc44795b3e97a28213d95182d9acf9 + source_hash: 66cbd9813ee28d202dcae34debab1b0cf9927793acb00743c1c62b48d9e381f9 source_path: providers/zai.md workflow: 15 --- # Z.AI -Z.AI는 **GLM** 모델용 API 플랫폼입니다. GLM용 REST API를 제공하며 인증에는 API 키를 사용합니다. Z.AI 콘솔에서 API 키를 생성하세요. OpenClaw는 Z.AI API 키와 함께 `zai` provider를 사용합니다. +Z.AI는 **GLM** 모델용 API 플랫폼입니다. GLM용 REST API를 제공하며 인증에는 API 키를 +사용합니다. Z.AI 콘솔에서 API 키를 생성하세요. OpenClaw는 Z.AI API 키와 함께 `zai` provider를 +사용합니다. ## CLI 설정 ```bash -# 엔드포인트 자동 감지가 포함된 일반 API 키 설정 +# 엔드포인트 자동 감지를 사용하는 일반 API 키 설정 openclaw onboard --auth-choice zai-api-key -# Coding Plan Global, Coding Plan 사용자에게 권장 +# 코딩 플랜 Global, 코딩 플랜 사용자에게 권장 openclaw onboard --auth-choice zai-coding-global -# Coding Plan CN(중국 리전), Coding Plan 사용자에게 권장 +# 코딩 플랜 CN(중국 리전), 코딩 플랜 사용자에게 권장 openclaw onboard --auth-choice zai-coding-cn # 일반 API @@ -41,16 +43,17 @@ openclaw onboard --auth-choice zai-cn ```json5 { env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5" } } }, + agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, } ``` `zai-api-key`를 사용하면 OpenClaw가 키에서 일치하는 Z.AI 엔드포인트를 감지하고 -올바른 기본 URL을 자동으로 적용할 수 있습니다. 특정 Coding Plan 또는 일반 API 표면을 강제로 사용하려는 경우에는 명시적인 리전 선택을 사용하세요. +올바른 기본 URL을 자동으로 적용할 수 있습니다. 특정 코딩 플랜 또는 일반 API 표면을 강제하려는 경우 +명시적인 지역 선택지를 사용하세요. ## 번들된 GLM 카탈로그 -OpenClaw는 현재 번들된 `zai` provider에 다음 모델을 시드합니다: +OpenClaw는 현재 번들된 `zai` provider를 다음으로 시드합니다: - `glm-5.1` - `glm-5` @@ -68,9 +71,11 @@ OpenClaw는 현재 번들된 `zai` provider에 다음 모델을 시드합니다: ## 참고 -- GLM 모델은 `zai/`로 제공됩니다(예: `zai/glm-5`). -- 기본 번들 모델 참조: `zai/glm-5` -- 알 수 없는 `glm-5*` id도 현재 GLM-5 제품군 형태와 일치하는 경우 `glm-4.7` 템플릿에서 provider 소유 메타데이터를 합성하여 번들 provider 경로에서 계속 정방향 해석됩니다. -- Z.AI tool-call 스트리밍에는 기본적으로 `tool_stream`이 활성화되어 있습니다. 비활성화하려면 `agents.defaults.models["zai/"].params.tool_stream`을 `false`로 설정하세요. -- 모델 제품군 개요는 [/providers/glm](/providers/glm)을 참조하세요. +- GLM 모델은 `zai/`로 사용할 수 있습니다(예: `zai/glm-5`). +- 기본 번들 모델 ref: `zai/glm-5.1` +- 알 수 없는 `glm-5*` ID도 현재 GLM-5 패밀리 형태와 일치하는 경우 + `glm-4.7` 템플릿에서 provider 소유 메타데이터를 합성하여 번들된 provider 경로에서 계속 해석됩니다. +- Z.AI 도구 호출 스트리밍을 위해 `tool_stream`은 기본적으로 활성화되어 있습니다. + 비활성화하려면 `agents.defaults.models["zai/"].params.tool_stream`을 `false`로 설정하세요. +- 모델 패밀리 개요는 [/providers/glm](/ko/providers/glm)를 참조하세요. - Z.AI는 API 키와 함께 Bearer 인증을 사용합니다. diff --git a/docs/ko/refactor/qa.md b/docs/ko/refactor/qa.md index c9114037c..c98fc1c8f 100644 --- a/docs/ko/refactor/qa.md +++ b/docs/ko/refactor/qa.md @@ -1,85 +1,88 @@ --- x-i18n: - generated_at: "2026-04-08T02:18:32Z" + generated_at: "2026-04-08T05:56:30Z" model: gpt-5.4 provider: openai - source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8 + source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd source_path: refactor/qa.md workflow: 15 --- # QA 리팩터링 -상태: 기반 마이그레이션이 완료되었습니다. +상태: 기반 마이그레이션이 적용되었습니다. ## 목표 -OpenClaw QA를 분리된 정의 모델에서 단일 신뢰 가능한 정보원으로 옮깁니다. +OpenClaw QA를 분리된 정의 모델에서 단일 진실 공급원으로 이동합니다: - 시나리오 메타데이터 - 모델에 전송되는 프롬프트 - 설정 및 정리 -- 하니스 로직 -- 단언 및 성공 기준 -- 아티팩트 및 리포트 힌트 +- 하네스 로직 +- 단언과 성공 기준 +- 아티팩트 및 보고서 힌트 -목표하는 최종 상태는 대부분의 동작을 TypeScript에 하드코딩하는 대신 강력한 시나리오 정의 파일을 로드하는 일반적인 QA 하니스입니다. +목표하는 최종 상태는 대부분의 동작을 TypeScript에 하드코딩하는 대신, 강력한 시나리오 정의 파일을 로드하는 범용 QA 하네스입니다. ## 현재 상태 -현재의 기본 신뢰 가능한 정보원은 `qa/scenarios.md`에 있습니다. +이제 주된 진실 공급원은 `qa/scenarios/index.md`와 `qa/scenarios/*.md` 아래의 시나리오별 파일 하나씩입니다. -구현 완료: +구현됨: -- `qa/scenarios.md` - - 정식 QA 팩 - - 운영자 신원 +- `qa/scenarios/index.md` + - 정식 QA 팩 메타데이터 + - 운영자 식별 정보 - 시작 미션 +- `qa/scenarios/*.md` + - 시나리오별 Markdown 파일 하나 - 시나리오 메타데이터 - 핸들러 바인딩 + - 시나리오별 실행 설정 - `extensions/qa-lab/src/scenario-catalog.ts` - - 마크다운 팩 파서 + zod 검증 + - Markdown 팩 파서 + zod 검증 - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - - 마크다운 팩에서 계획 렌더링 + - Markdown 팩에서 계획 렌더링 - `extensions/qa-lab/src/qa-agent-workspace.ts` - 생성된 호환성 파일과 `QA_SCENARIOS.md` 시드 - `extensions/qa-lab/src/suite.ts` - - 마크다운으로 정의된 핸들러 바인딩을 통해 실행 가능한 시나리오 선택 -- QA bus 프로토콜 + UI - - 이미지/비디오/오디오/파일 렌더링을 위한 일반적인 인라인 첨부 파일 + - Markdown으로 정의된 핸들러 바인딩을 통해 실행 가능한 시나리오 선택 +- QA 버스 프로토콜 + UI + - 이미지/비디오/오디오/파일 렌더링을 위한 범용 인라인 첨부 -여전히 분리되어 있는 표면: +남아 있는 분리된 표면: - `extensions/qa-lab/src/suite.ts` - - 여전히 대부분의 실행 가능한 사용자 지정 핸들러 로직을 소유 + - 여전히 대부분의 실행 가능한 커스텀 핸들러 로직을 소유 - `extensions/qa-lab/src/report.ts` - - 여전히 런타임 출력에서 리포트 구조를 도출 + - 여전히 런타임 출력에서 보고서 구조를 도출 -따라서 신뢰 가능한 정보원 분리는 해결되었지만, 실행은 여전히 완전히 선언적이기보다는 대부분 핸들러 기반입니다. +즉, 진실 공급원 분리는 해결되었지만, 실행은 아직 완전한 선언형이 아니라 대부분 핸들러 기반입니다. -## 실제 시나리오 표면의 형태 +## 실제 시나리오 표면의 모습 -현재 suite를 읽어보면 몇 가지 뚜렷한 시나리오 클래스가 보입니다. +현재 suite를 읽어 보면 몇 가지 뚜렷한 시나리오 클래스가 보입니다. ### 단순 상호작용 -- 채널 기준선 -- DM 기준선 -- 스레드 후속 조치 +- 채널 베이스라인 +- DM 베이스라인 +- 스레드 후속 응답 - 모델 전환 -- 승인 후속 처리 -- 반응/편집/삭제 +- 승인 후속 진행 +- 반응/수정/삭제 ### 구성 및 런타임 변경 - config patch skill 비활성화 -- config apply 재시작 wake-up -- config 재시작 capability 전환 -- 런타임 인벤토리 드리프트 검사 +- config apply 재시작 웨이크업 +- config 재시작 기능 전환 +- 런타임 인벤토리 드리프트 확인 -### 파일 시스템 및 repo 단언 +### 파일 시스템 및 리포지토리 단언 -- source/docs 탐색 리포트 +- source/docs 발견 보고서 - Lobster Invaders 빌드 - 생성된 이미지 아티팩트 조회 @@ -87,10 +90,10 @@ OpenClaw QA를 분리된 정의 모델에서 단일 신뢰 가능한 정보원 - 메모리 회상 - 채널 컨텍스트에서의 메모리 도구 -- 메모리 실패 fallback -- 세션 메모리 순위 +- 메모리 실패 폴백 +- 세션 메모리 랭킹 - 스레드 메모리 격리 -- 메모리 dreaming 스윕 +- 메모리 dreaming sweep ### 도구 및 plugin 통합 @@ -99,36 +102,36 @@ OpenClaw QA를 분리된 정의 모델에서 단일 신뢰 가능한 정보원 - skill 핫 설치 - 네이티브 이미지 생성 - 이미지 왕복 -- 첨부 파일의 이미지 이해 +- 첨부에서의 이미지 이해 -### 다중 턴 및 다중 액터 +### 멀티턴 및 멀티 액터 -- subagent handoff -- subagent fanout synthesis -- 재시작 복구 스타일 흐름 +- 서브에이전트 핸드오프 +- 서브에이전트 팬아웃 합성 +- 재시작 복구 스타일 플로우 -이 범주는 DSL 요구 사항을 결정하므로 중요합니다. 프롬프트 + 예상 텍스트의 평면 목록만으로는 충분하지 않습니다. +이 범주들은 DSL 요구사항을 결정하기 때문에 중요합니다. 프롬프트 + 기대 텍스트의 평면 목록만으로는 충분하지 않습니다. ## 방향 -### 단일 신뢰 가능한 정보원 +### 단일 진실 공급원 -작성된 신뢰 가능한 정보원으로 `qa/scenarios.md`를 사용합니다. +작성되는 진실 공급원으로 `qa/scenarios/index.md`와 `qa/scenarios/*.md`를 사용합니다. -이 팩은 다음 특성을 유지해야 합니다. +팩은 다음 상태를 유지해야 합니다: - 리뷰에서 사람이 읽기 쉬움 - 기계가 파싱 가능함 - 다음을 구동할 만큼 충분히 풍부함: - suite 실행 - - QA 워크스페이스 부트스트랩 + - QA 작업 공간 부트스트랩 - QA Lab UI 메타데이터 - docs/discovery 프롬프트 - - 리포트 생성 + - 보고서 생성 -### 선호하는 작성 형식 +### 선호되는 작성 형식 -최상위 형식으로는 마크다운을 사용하고, 그 안에 구조화된 YAML을 넣습니다. +최상위 형식은 Markdown을 사용하고, 그 안에 구조화된 YAML을 둡니다. 권장 형태: @@ -139,12 +142,12 @@ OpenClaw QA를 분리된 정의 모델에서 단일 신뢰 가능한 정보원 - tags - docs refs - code refs - - 모델/프로바이더 override + - model/provider 재정의 - prerequisites -- 본문 섹션 +- 설명 섹션 - objective - notes - - 디버깅 힌트 + - debugging hints - fenced YAML 블록 - setup - steps @@ -157,7 +160,7 @@ OpenClaw QA를 분리된 정의 모델에서 단일 신뢰 가능한 정보원 - 순수 YAML보다 더 풍부한 컨텍스트 - 엄격한 파싱과 zod 검증 -순수 JSON은 중간 생성 형식으로만 허용됩니다. +원시 JSON은 중간 생성 형태로만 허용됩니다. ## 제안하는 시나리오 파일 형태 @@ -232,11 +235,11 @@ Verify generated media is reattached on the follow-up turn. ``` ```` -## DSL이 지원해야 하는 러너 기능 +## DSL이 다뤄야 하는 러너 기능 -현재 suite를 기준으로 보면, 일반적인 러너는 프롬프트 실행 이상의 기능이 필요합니다. +현재 suite를 기준으로 보면, 범용 러너는 단순한 프롬프트 실행 이상의 기능이 필요합니다. -### 환경 및 설정 액션 +### 환경 및 설정 작업 - `bus.reset` - `gateway.waitHealthy` @@ -245,14 +248,14 @@ Verify generated media is reattached on the follow-up turn. - `thread.create` - `workspace.writeSkill` -### 에이전트 턴 액션 +### 에이전트 턴 작업 - `agent.send` - `agent.wait` - `bus.injectInbound` - `bus.injectOutbound` -### 구성 및 런타임 액션 +### 구성 및 런타임 작업 - `config.get` - `config.patch` @@ -261,7 +264,7 @@ Verify generated media is reattached on the follow-up turn. - `tools.effective` - `skills.status` -### 파일 및 아티팩트 액션 +### 파일 및 아티팩트 작업 - `file.write` - `file.read` @@ -270,7 +273,7 @@ Verify generated media is reattached on the follow-up turn. - `artifact.captureGeneratedImage` - `artifact.capturePath` -### 메모리 및 cron 액션 +### 메모리 및 cron 작업 - `memory.indexForce` - `memory.searchCli` @@ -280,7 +283,7 @@ Verify generated media is reattached on the follow-up turn. - `cron.waitCompletion` - `sessionTranscript.write` -### MCP 액션 +### MCP 작업 - `mcp.callTool` @@ -308,128 +311,129 @@ DSL은 저장된 출력과 이후 참조를 지원해야 합니다. - 스레드를 만든 뒤 `threadId` 재사용 - 세션을 만든 뒤 `sessionKey` 재사용 -- 이미지를 생성한 뒤 다음 턴에 파일 첨부 -- wake marker 문자열을 생성한 뒤 나중에 나타나는지 단언 +- 이미지를 생성한 뒤 다음 턴에 해당 파일 첨부 +- 웨이크 마커 문자열을 생성한 뒤 나중에 나타나는지 단언 필요한 기능: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- 경로, 세션 키, 스레드 id, 마커, 도구 출력에 대한 타입 지정 참조 +- 경로, 세션 키, 스레드 id, 마커, 도구 출력을 위한 타입 지정 참조 -변수 지원이 없으면 하니스는 계속 시나리오 로직을 TypeScript 쪽으로 새어나가게 됩니다. +변수 지원이 없으면 하네스는 계속해서 시나리오 로직을 TypeScript로 다시 새어 나가게 됩니다. ## 이스케이프 해치로 남겨야 할 것 -완전히 순수한 선언형 러너는 1단계에서는 현실적이지 않습니다. +1단계에서 완전히 순수한 선언형 러너는 현실적이지 않습니다. -일부 시나리오는 본질적으로 오케스트레이션 비중이 큽니다. +일부 시나리오는 본질적으로 오케스트레이션 비중이 큽니다: -- 메모리 dreaming 스윕 -- config apply 재시작 wake-up -- config 재시작 capability 전환 +- memory dreaming sweep +- config apply 재시작 웨이크업 +- config 재시작 기능 전환 - 타임스탬프/경로 기준 생성 이미지 아티팩트 해석 - discovery-report 평가 -이런 항목은 당분간 명시적인 사용자 지정 핸들러를 사용해야 합니다. +이들은 우선 명시적인 커스텀 핸들러를 사용해야 합니다. 권장 규칙: -- 85-90% 선언형 -- 어려운 나머지 부분에는 명시적 `customHandler` 단계 사용 -- 이름이 있고 문서화된 사용자 지정 핸들러만 허용 -- 시나리오 파일 안에 익명 인라인 코드는 금지 +- 85-90%는 선언형 +- 어려운 나머지를 위해 명시적인 `customHandler` 단계 사용 +- 이름이 있고 문서화된 커스텀 핸들러만 허용 +- 시나리오 파일에 익명 인라인 코드는 허용하지 않음 -이렇게 하면 일반 엔진을 깔끔하게 유지하면서도 계속 진전할 수 있습니다. +이렇게 하면 범용 엔진을 깔끔하게 유지하면서도 계속 진전할 수 있습니다. ## 아키텍처 변경 ### 현재 -시나리오 마크다운은 이미 다음의 신뢰 가능한 정보원입니다. +시나리오 Markdown은 이미 다음의 진실 공급원입니다: - suite 실행 -- 워크스페이스 부트스트랩 파일 +- 작업 공간 부트스트랩 파일 - QA Lab UI 시나리오 카탈로그 -- 리포트 메타데이터 +- 보고서 메타데이터 - discovery 프롬프트 생성된 호환성 항목: -- 시드된 워크스페이스에는 여전히 `QA_KICKOFF_TASK.md`가 포함됨 -- 시드된 워크스페이스에는 여전히 `QA_SCENARIO_PLAN.md`가 포함됨 -- 시드된 워크스페이스에는 이제 `QA_SCENARIOS.md`도 포함됨 +- 시드된 작업 공간에는 여전히 `QA_KICKOFF_TASK.md`가 포함됨 +- 시드된 작업 공간에는 여전히 `QA_SCENARIO_PLAN.md`가 포함됨 +- 시드된 작업 공간에는 이제 `QA_SCENARIOS.md`도 포함됨 ## 리팩터링 계획 ### 1단계: 로더 및 스키마 -완료됨. +완료. -- `qa/scenarios.md` 추가 -- 이름 있는 마크다운 YAML 팩 콘텐츠용 파서 추가 +- `qa/scenarios/index.md` 추가 +- 시나리오를 `qa/scenarios/*.md`로 분리 +- 이름 있는 Markdown YAML 팩 콘텐츠용 파서 추가 - zod로 검증 - 소비자를 파싱된 팩으로 전환 -- repo 수준의 `qa/seed-scenarios.json` 및 `qa/QA_KICKOFF_TASK.md` 제거 +- 리포지토리 수준의 `qa/seed-scenarios.json` 및 `qa/QA_KICKOFF_TASK.md` 제거 -### 2단계: 일반 엔진 +### 2단계: 범용 엔진 - `extensions/qa-lab/src/suite.ts`를 다음으로 분리: - - 로더 - - 엔진 - - 액션 레지스트리 - - 단언 레지스트리 - - 사용자 지정 핸들러 -- 기존 helper 함수를 엔진 연산으로 유지 + - loader + - engine + - action registry + - assertion registry + - custom handlers +- 기존 헬퍼 함수를 엔진 작업으로 유지 결과물: -- 엔진이 단순 선언형 시나리오를 실행함 +- 엔진이 단순한 선언형 시나리오를 실행함 -대부분 프롬프트 + 대기 + 단언으로 구성된 시나리오부터 시작: +우선 대부분 프롬프트 + 대기 + 단언으로 구성된 시나리오부터 시작: -- 스레드 후속 조치 -- 첨부 파일의 이미지 이해 -- skill 가시성 및 호출 -- 채널 기준선 +- 스레드 후속 응답 +- 첨부에서의 이미지 이해 +- skill 가시성과 호출 +- 채널 베이스라인 결과물: -- 일반 엔진을 통해 전달되는 첫 실제 마크다운 정의 시나리오 출시 +- 최초의 실제 Markdown 정의 시나리오가 범용 엔진을 통해 제공됨 ### 4단계: 중간 난이도 시나리오 마이그레이션 - 이미지 생성 왕복 - 채널 컨텍스트에서의 메모리 도구 -- 세션 메모리 순위 -- subagent handoff -- subagent fanout synthesis +- 세션 메모리 랭킹 +- 서브에이전트 핸드오프 +- 서브에이전트 팬아웃 합성 결과물: -- 변수, 아티팩트, 도구 단언, 요청 로그 단언이 실제로 검증됨 +- 변수, 아티팩트, 도구 단언, request-log 단언이 검증됨 -### 5단계: 어려운 시나리오는 사용자 지정 핸들러에 유지 +### 5단계: 어려운 시나리오는 커스텀 핸들러에 유지 -- 메모리 dreaming 스윕 -- config apply 재시작 wake-up -- config 재시작 capability 전환 +- memory dreaming sweep +- config apply 재시작 웨이크업 +- config 재시작 기능 전환 - 런타임 인벤토리 드리프트 결과물: -- 동일한 작성 형식이지만 필요 시 명시적인 custom-step 블록 사용 +- 동일한 작성 형식이지만, 필요 시 명시적인 custom-step 블록 사용 ### 6단계: 하드코딩된 시나리오 맵 삭제 -팩 범위가 충분히 좋아지면: +팩 커버리지가 충분히 좋아지면: -- `extensions/qa-lab/src/suite.ts`에서 대부분의 시나리오별 TypeScript 분기 제거 +- `extensions/qa-lab/src/suite.ts`에서 대부분의 시나리오별 TypeScript 분기를 제거 ## 가짜 Slack / 리치 미디어 지원 -현재 QA bus는 텍스트 우선입니다. +현재 QA 버스는 텍스트 우선입니다. 관련 파일: @@ -439,17 +443,17 @@ DSL은 저장된 출력과 이후 참조를 지원해야 합니다. - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -현재 QA bus가 지원하는 항목: +오늘날 QA 버스가 지원하는 항목: - 텍스트 - 반응 - 스레드 -아직 인라인 미디어 첨부 파일은 모델링하지 않습니다. +아직 인라인 미디어 첨부는 모델링하지 않습니다. ### 필요한 전송 계약 -일반적인 QA bus 첨부 파일 모델을 추가합니다. +범용 QA 버스 첨부 모델을 추가합니다: ```ts type QaBusAttachment = { @@ -468,67 +472,67 @@ type QaBusAttachment = { }; ``` -그다음 다음 항목에 `attachments?: QaBusAttachment[]`를 추가합니다. +그 다음 다음 항목들에 `attachments?: QaBusAttachment[]`를 추가합니다: - `QaBusMessage` - `QaBusInboundMessageInput` - `QaBusOutboundMessageInput` -### 왜 먼저 일반화해야 하나 +### 왜 먼저 범용으로 해야 하는가 Slack 전용 미디어 모델을 만들지 마세요. 대신: -- 하나의 일반 QA 전송 모델 -- 그 위에 여러 렌더러 +- 하나의 범용 QA 전송 모델 +- 그 위에 여러 렌더러를 구축 - 현재 QA Lab 채팅 - 향후 가짜 Slack 웹 - - 그 외 다른 가짜 전송 뷰 + - 기타 다른 가짜 전송 뷰 -이렇게 하면 중복 로직을 방지하고 미디어 시나리오를 전송 방식에 독립적으로 유지할 수 있습니다. +이렇게 하면 로직 중복을 방지하고 미디어 시나리오가 전송 수단에 독립적으로 유지됩니다. ### 필요한 UI 작업 -QA UI를 업데이트해 다음을 렌더링합니다. +QA UI를 업데이트하여 다음을 렌더링합니다: - 인라인 이미지 미리보기 - 인라인 오디오 플레이어 - 인라인 비디오 플레이어 -- 파일 첨부 chip +- 파일 첨부 칩 -현재 UI는 이미 스레드와 반응을 렌더링할 수 있으므로, 첨부 파일 렌더링도 동일한 메시지 카드 모델 위에 얹으면 됩니다. +현재 UI는 이미 스레드와 반응을 렌더링할 수 있으므로, 첨부 렌더링은 동일한 메시지 카드 모델 위에 계층화할 수 있어야 합니다. -### 미디어 전송이 가능하게 하는 시나리오 작업 +### 미디어 전송으로 가능해지는 시나리오 작업 -첨부 파일이 QA bus를 통해 흐르게 되면 더 풍부한 가짜 채팅 시나리오를 추가할 수 있습니다. +첨부가 QA 버스를 통해 흐르기 시작하면 더 풍부한 가짜 채팅 시나리오를 추가할 수 있습니다: -- 가짜 Slack의 인라인 이미지 응답 -- 오디오 첨부 파일 이해 -- 비디오 첨부 파일 이해 -- 혼합 첨부 파일 순서 -- 미디어를 유지한 스레드 응답 +- 가짜 Slack에서의 인라인 이미지 응답 +- 오디오 첨부 이해 +- 비디오 첨부 이해 +- 혼합 첨부 순서 +- 미디어가 유지되는 스레드 응답 ## 권장 사항 -다음 구현 단위는 다음이어야 합니다. +다음 구현 단위는 다음이어야 합니다: -1. 마크다운 시나리오 로더 + zod 스키마 추가 -2. 마크다운에서 현재 카탈로그 생성 -3. 몇 가지 단순 시나리오를 먼저 마이그레이션 -4. 일반 QA bus 첨부 파일 지원 추가 -5. QA UI에서 인라인 이미지 렌더링 -6. 그다음 오디오와 비디오로 확장 +1. Markdown 시나리오 로더 + zod 스키마 추가 +2. 현재 카탈로그를 Markdown에서 생성 +3. 먼저 몇 가지 단순한 시나리오 마이그레이션 +4. 범용 QA 버스 첨부 지원 추가 +5. QA UI에 인라인 이미지 렌더링 +6. 그 다음 오디오와 비디오로 확장 -이것이 두 목표를 모두 입증하는 가장 작은 경로입니다. +이것이 두 목표를 모두 입증하는 가장 작은 경로입니다: -- 일반적인 마크다운 정의 QA +- 범용 Markdown 정의 QA - 더 풍부한 가짜 메시징 표면 ## 열린 질문 -- 시나리오 파일이 변수 보간이 포함된 임베디드 마크다운 프롬프트 템플릿을 허용해야 하는지 -- setup/cleanup이 이름 있는 섹션이어야 하는지 아니면 단순히 순서가 있는 액션 목록이면 되는지 -- 아티팩트 참조를 스키마에서 강한 타입으로 둘지 문자열 기반으로 둘지 -- 사용자 지정 핸들러가 하나의 레지스트리에 있어야 하는지, 표면별 레지스트리여야 하는지 -- 생성된 JSON 호환성 파일을 마이그레이션 중에도 계속 체크인 상태로 유지해야 하는지 +- 시나리오 파일에서 변수 보간이 포함된 내장 Markdown 프롬프트 템플릿을 허용해야 하는지 여부 +- setup/cleanup을 이름 있는 섹션으로 둘지, 아니면 단순한 순서형 작업 목록으로 둘지 여부 +- 아티팩트 참조를 스키마에서 강한 타입으로 둘지, 아니면 문자열 기반으로 둘지 여부 +- 커스텀 핸들러를 하나의 레지스트리에 둘지, 아니면 surface별 레지스트리로 나눌지 여부 +- 생성된 JSON 호환성 파일을 마이그레이션 중에도 계속 체크인 상태로 유지해야 하는지 여부 diff --git a/docs/ko/tools/slash-commands.md b/docs/ko/tools/slash-commands.md index 29ce6fedb..819c18cfb 100644 --- a/docs/ko/tools/slash-commands.md +++ b/docs/ko/tools/slash-commands.md @@ -1,36 +1,36 @@ --- read_when: - - 채팅 명령을 사용하거나 구성할 때 - - 명령 라우팅 또는 권한을 디버깅할 때 -summary: 'Slash commands: 텍스트 vs 네이티브, 구성, 지원 명령' -title: Slash Commands + - 채팅 명령을 사용하거나 구성하는 경우 + - 명령 라우팅 또는 권한을 디버그하는 경우 +summary: '슬래시 명령: 텍스트 대 네이티브, 구성, 지원되는 명령' +title: 슬래시 명령 x-i18n: - generated_at: "2026-04-06T03:14:22Z" + generated_at: "2026-04-08T05:57:08Z" model: gpt-5.4 provider: openai - source_hash: 417e35b9ddd87f25f6c019111b55b741046ea11039dde89210948185ced5696d + source_hash: 4a7ee7f1a8012058279b9e632889b291d4e659e4ec81209ca8978afbb9ad4b96 source_path: tools/slash-commands.md workflow: 15 --- -# Slash Commands +# 슬래시 명령 -명령은 Gateway에서 처리됩니다. 대부분의 명령은 `/`로 시작하는 **독립 실행형** 메시지로 보내야 합니다. -host 전용 bash 채팅 명령은 `! `를 사용합니다(` /bash `는 별칭). +명령은 Gateway에서 처리됩니다. 대부분의 명령은 `/`로 시작하는 **독립형** 메시지로 보내야 합니다. +호스트 전용 bash 채팅 명령은 `! `를 사용합니다(`/bash `는 별칭). -서로 관련된 두 가지 시스템이 있습니다. +서로 관련된 두 시스템이 있습니다: -- **Commands**: 독립 실행형 `/...` 메시지 -- **Directives**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue` - - Directives는 모델이 메시지를 보기 전에 제거됩니다. - - 일반 채팅 메시지(지시어만 있는 메시지가 아님)에서는 “인라인 힌트”로 처리되며 세션 설정을 유지하지 않습니다. - - 지시어만 있는 메시지(메시지에 지시어만 포함됨)에서는 세션에 유지되며 확인 응답을 보냅니다. - - Directives는 **권한 있는 발신자**에게만 적용됩니다. `commands.allowFrom`이 설정되어 있으면 그것만 - directives와 commands에 사용되는 허용 목록이 되며, 그렇지 않으면 권한은 채널 허용 목록/페어링 + `commands.useAccessGroups`에서 옵니다. - 권한이 없는 발신자에게는 directives가 일반 텍스트로 처리됩니다. +- **명령**: 독립형 `/...` 메시지 +- **지시어**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue` + - 지시어는 모델이 메시지를 보기 전에 제거됩니다. + - 일반 채팅 메시지에서는(지시어만 있는 메시지가 아님) “인라인 힌트”로 취급되며 세션 설정을 유지하지 않습니다. + - 지시어만 있는 메시지에서는(메시지가 지시어만 포함하는 경우) 세션에 유지되며 확인 응답을 반환합니다. + - 지시어는 **권한이 있는 발신자**에게만 적용됩니다. `commands.allowFrom`이 설정되어 있으면 이것만 + 사용되는 허용 목록이며, 그렇지 않으면 권한 부여는 채널 허용 목록/페어링과 `commands.useAccessGroups`에서 옵니다. + 권한이 없는 발신자에게는 지시어가 일반 텍스트로 처리됩니다. -또한 몇 가지 **인라인 단축키**도 있습니다(allowlist에 있거나 권한 있는 발신자만): `/help`, `/commands`, `/status`, `/whoami` (`/id`). -이들은 즉시 실행되고, 모델이 메시지를 보기 전에 제거되며, 남은 텍스트는 정상 흐름으로 계속 진행됩니다. +몇 가지 **인라인 바로가기**도 있습니다(허용 목록에 있거나 권한이 있는 발신자만): `/help`, `/commands`, `/status`, `/whoami` (`/id`). +이들은 즉시 실행되고, 모델이 메시지를 보기 전에 제거되며, 남은 텍스트는 일반 흐름을 계속 따릅니다. ## 구성 @@ -46,7 +46,10 @@ host 전용 bash 채팅 명령은 `! `를 사용합니다(` /bash `는 mcp: false, plugins: false, debug: false, - restart: false, + restart: true, + ownerAllowFrom: ["discord:123456789012345678"], + ownerDisplay: "raw", + ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -56,150 +59,184 @@ host 전용 bash 채팅 명령은 `! `를 사용합니다(` /bash `는 } ``` -- `commands.text`(기본값 `true`)는 채팅 메시지에서 `/...` 파싱을 활성화합니다. - - 네이티브 명령이 없는 표면(WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams)에서는 이를 `false`로 설정해도 텍스트 명령은 계속 동작합니다. +- `commands.text`(기본값 `true`)는 채팅 메시지에서 `/...` 구문 분석을 활성화합니다. + - 네이티브 명령이 없는 표면에서는(WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) 이를 `false`로 설정해도 텍스트 명령은 계속 동작합니다. - `commands.native`(기본값 `"auto"`)는 네이티브 명령을 등록합니다. - - 자동: Discord/Telegram에서는 켜짐, Slack에서는 꺼짐(Slack slash command를 추가하기 전까지), 네이티브 지원이 없는 공급자에서는 무시됨. - - 공급자별 재정의를 위해 `channels.discord.commands.native`, `channels.telegram.commands.native`, 또는 `channels.slack.commands.native`를 설정하세요(bool 또는 `"auto"`). + - 자동: Discord/Telegram에서는 켜짐, Slack에서는 꺼짐(슬래시 명령을 추가할 때까지), 네이티브 지원이 없는 provider에서는 무시됩니다. + - provider별로 재정의하려면 `channels.discord.commands.native`, `channels.telegram.commands.native`, 또는 `channels.slack.commands.native`를 설정하세요(bool 또는 `"auto"`). - `false`는 시작 시 Discord/Telegram에서 이전에 등록된 명령을 지웁니다. Slack 명령은 Slack 앱에서 관리되며 자동으로 제거되지 않습니다. -- `commands.nativeSkills`(기본값 `"auto"`)는 지원되는 경우 **skill** 명령을 네이티브로 등록합니다. - - 자동: Discord/Telegram에서는 켜짐, Slack에서는 꺼짐(Slack은 skill별로 slash command를 하나씩 만들어야 함). - - 공급자별 재정의를 위해 `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, 또는 `channels.slack.commands.nativeSkills`를 설정하세요(bool 또는 `"auto"`). -- `commands.bash`(기본값 `false`)는 host 셸 명령을 실행하는 `! `를 활성화합니다(` /bash `는 별칭이며 `tools.elevated` allowlist가 필요). -- `commands.bashForegroundMs`(기본값 `2000`)는 bash가 백그라운드 모드로 전환되기 전에 얼마나 기다릴지 제어합니다(`0`이면 즉시 백그라운드 전환). +- `commands.nativeSkills`(기본값 `"auto"`)는 지원될 때 **skill** 명령을 네이티브로 등록합니다. + - 자동: Discord/Telegram에서는 켜짐, Slack에서는 꺼짐(Slack은 skill마다 슬래시 명령을 하나씩 만들어야 합니다). + - provider별로 재정의하려면 `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, 또는 `channels.slack.commands.nativeSkills`를 설정하세요(bool 또는 `"auto"`). +- `commands.bash`(기본값 `false`)는 `! `로 호스트 셸 명령을 실행할 수 있게 합니다(`/bash `는 별칭이며 `tools.elevated` 허용 목록 필요). +- `commands.bashForegroundMs`(기본값 `2000`)는 bash가 백그라운드 모드로 전환하기 전에 얼마나 기다릴지 제어합니다(`0`이면 즉시 백그라운드 처리). - `commands.config`(기본값 `false`)는 `/config`를 활성화합니다(`openclaw.json` 읽기/쓰기). -- `commands.mcp`(기본값 `false`)는 `/mcp`를 활성화합니다(`mcp.servers` 아래의 OpenClaw 관리 MCP config 읽기/쓰기). -- `commands.plugins`(기본값 `false`)는 `/plugins`를 활성화합니다(plugin 탐색/상태와 설치 + 활성화/비활성화 제어). +- `commands.mcp`(기본값 `false`)는 `/mcp`를 활성화합니다(`mcp.servers` 아래의 OpenClaw 관리 MCP 구성을 읽기/쓰기). +- `commands.plugins`(기본값 `false`)는 `/plugins`를 활성화합니다(plugin 검색/상태와 설치 + 활성화/비활성화 제어). - `commands.debug`(기본값 `false`)는 `/debug`를 활성화합니다(런타임 전용 재정의). -- `commands.allowFrom`(선택 사항)은 명령 권한 부여를 위한 공급자별 허용 목록을 설정합니다. 구성되면 이것이 - commands와 directives의 유일한 권한 부여 소스가 되며(채널 허용 목록/페어링과 `commands.useAccessGroups` - 는 무시됨). 전역 기본값에는 `"*"`를 사용하고, 공급자별 키가 있으면 그것이 우선합니다. -- `commands.useAccessGroups`(기본값 `true`)는 `commands.allowFrom`이 설정되지 않았을 때 commands에 대해 허용 목록/정책을 적용합니다. +- `commands.restart`(기본값 `true`)는 `/restart`와 gateway 재시작 도구 동작을 활성화합니다. +- `commands.ownerAllowFrom`(선택 사항)은 소유자 전용 명령/도구 표면에 대한 명시적 소유자 허용 목록을 설정합니다. 이는 `commands.allowFrom`과 별개입니다. +- `commands.ownerDisplay`는 시스템 프롬프트에서 소유자 ID가 어떻게 표시되는지 제어합니다: `raw` 또는 `hash`. +- `commands.ownerDisplaySecret`는 `commands.ownerDisplay="hash"`일 때 사용되는 HMAC 시크릿을 선택적으로 설정합니다. +- `commands.allowFrom`(선택 사항)은 명령 권한 부여를 위한 provider별 허용 목록을 설정합니다. 구성되면 이것이 명령과 지시어의 + 유일한 권한 부여 소스가 됩니다(채널 허용 목록/페어링과 `commands.useAccessGroups`는 무시됨). 전역 기본값에는 `"*"`를 사용하고, provider별 키가 이를 재정의합니다. +- `commands.useAccessGroups`(기본값 `true`)는 `commands.allowFrom`이 설정되지 않았을 때 명령에 대해 허용 목록/정책을 적용합니다. ## 명령 목록 -텍스트 + 네이티브(활성화된 경우): +현재 소스 오브 트루스: -- `/help` -- `/commands` -- `/tools [compact|verbose]` (현재 에이전트가 지금 바로 사용할 수 있는 것을 표시; `verbose`는 설명 추가) -- `/skill [input]` (이름으로 skill 실행) -- `/status` (현재 상태 표시; 사용 가능한 경우 현재 모델 공급자의 공급자 사용량/할당량 포함) -- `/tasks` (현재 세션의 백그라운드 작업 나열; agent-local 폴백 횟수와 함께 활성/최근 작업 세부 정보 표시) -- `/allowlist` (허용 목록 항목 나열/추가/제거) -- `/approve ` (exec 승인 프롬프트 해결; 사용 가능한 결정은 대기 중 승인 메시지를 사용) -- `/context [list|detail|json]` (“context” 설명; `detail`은 파일별 + 도구별 + skill별 + 시스템 프롬프트 크기 표시) -- `/btw ` (현재 세션에 대한 일회성 사이드 질문을 미래 세션 컨텍스트를 바꾸지 않고 수행; [/tools/btw](/ko/tools/btw) 참고) -- `/export-session [path]` (별칭: `/export`) (전체 시스템 프롬프트와 함께 현재 세션을 HTML로 내보내기) -- `/whoami` (발신자 id 표시; 별칭: `/id`) -- `/session idle ` (포커스된 스레드 바인딩의 비활성 자동 언포커스 관리) -- `/session max-age ` (포커스된 스레드 바인딩의 하드 max-age 자동 언포커스 관리) -- `/subagents list|kill|log|info|send|steer|spawn` (현재 세션에 대한 서브에이전트 실행 검사, 제어, 생성) -- `/acp spawn|cancel|steer|close|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|sessions` (ACP 런타임 세션 검사 및 제어) -- `/agents` (이 세션에 스레드 바인딩된 에이전트 나열) -- `/focus ` (Discord: 이 스레드 또는 새 스레드를 세션/서브에이전트 대상에 바인딩) -- `/unfocus` (Discord: 현재 스레드 바인딩 제거) -- `/kill ` (이 세션의 실행 중인 하나 또는 모든 서브에이전트를 즉시 중단, 확인 메시지 없음) -- `/steer ` (실행 중인 서브에이전트를 즉시 조향: 가능하면 실행 중에, 아니면 현재 작업을 중단하고 조향 메시지로 재시작) -- `/tell ` (`/steer`의 별칭) -- `/config show|get|set|unset` (config를 디스크에 지속 저장, 소유자 전용; `commands.config: true` 필요) -- `/mcp show|get|set|unset` (OpenClaw MCP server config 관리, 소유자 전용; `commands.mcp: true` 필요) -- `/plugins list|show|get|install|enable|disable` (탐색된 plugin 검사, 새 plugin 설치, 활성화 전환; 쓰기는 소유자 전용; `commands.plugins: true` 필요) - - `/plugin`은 `/plugins`의 별칭입니다. - - `/plugin install `은 `openclaw plugins install`과 동일한 plugin spec을 받습니다: 로컬 경로/아카이브, npm 패키지, 또는 `clawhub:`. - - 활성화/비활성화 쓰기 후에도 재시작 힌트로 응답합니다. watched foreground gateway에서는 OpenClaw가 쓰기 직후 자동으로 재시작할 수 있습니다. -- `/debug show|set|unset|reset` (런타임 재정의, 소유자 전용; `commands.debug: true` 필요) -- `/usage off|tokens|full|cost` (응답별 사용량 푸터 또는 로컬 비용 요약) -- `/tts off|always|inbound|tagged|status|provider|limit|summary|audio` (TTS 제어; [/tts](/ko/tools/tts) 참고) - - Discord: 네이티브 명령은 `/voice`입니다(Discord는 `/tts` 예약). 텍스트 `/tts`는 계속 동작합니다. -- `/stop` -- `/restart` -- `/dock-telegram` (별칭: `/dock_telegram`) (응답을 Telegram으로 전환) -- `/dock-discord` (별칭: `/dock_discord`) (응답을 Discord로 전환) -- `/dock-slack` (별칭: `/dock_slack`) (응답을 Slack으로 전환) -- `/activation mention|always` (그룹 전용) -- `/send on|off|inherit` (소유자 전용) -- `/reset` 또는 `/new [model]` (선택적 모델 힌트, 나머지는 그대로 전달됨) -- `/think ` (모델/공급자별 동적 선택지; 별칭: `/thinking`, `/t`) -- `/fast status|on|off` (인수를 생략하면 현재 유효한 fast-mode 상태 표시) -- `/verbose on|full|off` (별칭: `/v`) -- `/reasoning on|off|stream` (별칭: `/reason`; on이면 `Reasoning:`으로 시작하는 별도 메시지를 보냄, `stream` = Telegram draft 전용) -- `/elevated on|off|ask|full` (별칭: `/elev`; `full`은 exec 승인을 건너뜀) -- `/exec host= security= ask= node=` (현재 값을 보려면 `/exec` 전송) -- `/model ` (별칭: `/models`; 또는 `agents.defaults.models.*.alias`의 `/`) -- `/queue ` (`debounce:2s cap:25 drop:summarize` 같은 옵션 포함; 현재 설정을 보려면 `/queue` 전송) -- `/bash ` (host 전용; `! `의 별칭; `commands.bash: true` + `tools.elevated` allowlist 필요) -- `/dreaming [on|off|status|help]` (전역 dreaming 전환 또는 상태 표시; [Dreaming](/concepts/dreaming) 참고) +- 코어 내장 명령은 `src/auto-reply/commands-registry.shared.ts`에서 옵니다 +- 생성된 dock 명령은 `src/auto-reply/commands-registry.data.ts`에서 옵니다 +- plugin 명령은 plugin `registerCommand()` 호출에서 옵니다 +- gateway에서 실제 사용 가능 여부는 여전히 구성 플래그, 채널 표면, 설치/활성화된 plugins에 따라 달라집니다 -텍스트 전용: +### 코어 내장 명령 -- `/compact [instructions]` ([/concepts/compaction](/ko/concepts/compaction) 참고) -- `! ` (host 전용; 한 번에 하나씩; 장기 실행 작업에는 `!poll` + `!stop` 사용) -- `!poll` (출력/상태 확인; 선택적으로 `sessionId` 허용; `/bash poll`도 동작) -- `!stop` (실행 중인 bash 작업 중지; 선택적으로 `sessionId` 허용; `/bash stop`도 동작) +현재 사용 가능한 내장 명령: + +- `/new [model]`은 새 세션을 시작합니다. `/reset`은 reset 별칭입니다. +- `/compact [instructions]`는 세션 컨텍스트를 압축합니다. [/concepts/compaction](/ko/concepts/compaction)을 참조하세요. +- `/stop`은 현재 실행을 중단합니다. +- `/session idle ` 및 `/session max-age `는 스레드 바인딩 만료를 관리합니다. +- `/think `는 thinking 수준을 설정합니다. 별칭: `/thinking`, `/t`. +- `/verbose on|off|full`은 자세한 출력 표시를 전환합니다. 별칭: `/v`. +- `/fast [status|on|off]`는 fast 모드를 표시하거나 설정합니다. +- `/reasoning [on|off|stream]`은 reasoning 표시 여부를 전환합니다. 별칭: `/reason`. +- `/elevated [on|off|ask|full]`은 elevated 모드를 전환합니다. 별칭: `/elev`. +- `/exec host= security= ask= node=`는 exec 기본값을 표시하거나 설정합니다. +- `/model [name|#|status]`는 모델을 표시하거나 설정합니다. +- `/models [provider] [page] [limit=|size=|all]`는 provider 또는 provider의 모델을 나열합니다. +- `/queue `는 큐 동작(`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`)과 `debounce:2s cap:25 drop:summarize` 같은 옵션을 관리합니다. +- `/help`는 짧은 도움말 요약을 표시합니다. +- `/commands`는 생성된 명령 카탈로그를 표시합니다. +- `/tools [compact|verbose]`는 현재 에이전트가 지금 사용할 수 있는 것을 보여줍니다. +- `/status`는 가능한 경우 provider 사용량/할당량을 포함한 런타임 상태를 보여줍니다. +- `/tasks`는 현재 세션의 활성/최근 백그라운드 작업을 나열합니다. +- `/context [list|detail|json]`는 컨텍스트가 어떻게 조립되는지 설명합니다. +- `/export-session [path]`는 현재 세션을 HTML로 내보냅니다. 별칭: `/export`. +- `/whoami`는 발신자 ID를 보여줍니다. 별칭: `/id`. +- `/skill [input]`은 이름으로 skill을 실행합니다. +- `/allowlist [list|add|remove] ...`는 허용 목록 항목을 관리합니다. 텍스트 전용. +- `/approve `은 exec 승인 프롬프트를 해결합니다. +- `/btw `은 미래 세션 컨텍스트를 바꾸지 않고 곁가지 질문을 합니다. [/tools/btw](/ko/tools/btw)를 참조하세요. +- `/subagents list|kill|log|info|send|steer|spawn`은 현재 세션의 서브에이전트 실행을 관리합니다. +- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help`는 ACP 세션 및 런타임 옵션을 관리합니다. +- `/focus `은 현재 Discord 스레드 또는 Telegram 토픽/대화를 세션 대상으로 바인딩합니다. +- `/unfocus`는 현재 바인딩을 제거합니다. +- `/agents`는 현재 세션의 스레드 바인딩된 에이전트를 나열합니다. +- `/kill `은 하나 또는 모든 실행 중인 서브에이전트를 중단합니다. +- `/steer `는 실행 중인 서브에이전트에 steering을 보냅니다. 별칭: `/tell`. +- `/config show|get|set|unset`은 `openclaw.json`을 읽거나 씁니다. 소유자 전용. `commands.config: true` 필요. +- `/mcp show|get|set|unset`은 `mcp.servers` 아래의 OpenClaw 관리 MCP 서버 구성을 읽거나 씁니다. 소유자 전용. `commands.mcp: true` 필요. +- `/plugins list|inspect|show|get|install|enable|disable`은 plugin 상태를 조회하거나 변경합니다. `/plugin`은 별칭입니다. 쓰기는 소유자 전용. `commands.plugins: true` 필요. +- `/debug show|set|unset|reset`은 런타임 전용 구성 재정의를 관리합니다. 소유자 전용. `commands.debug: true` 필요. +- `/usage off|tokens|full|cost`는 응답별 사용량 푸터를 제어하거나 로컬 비용 요약을 출력합니다. +- `/tts on|off|status|provider|limit|summary|audio|help`는 TTS를 제어합니다. [/tools/tts](/ko/tools/tts)를 참조하세요. +- `/restart`는 활성화되어 있을 때 OpenClaw를 재시작합니다. 기본값: 활성화됨. 비활성화하려면 `commands.restart: false`를 설정하세요. +- `/activation mention|always`는 그룹 활성화 모드를 설정합니다. +- `/send on|off|inherit`는 전송 정책을 설정합니다. 소유자 전용. +- `/bash `는 호스트 셸 명령을 실행합니다. 텍스트 전용. 별칭: `! `. `commands.bash: true` 및 `tools.elevated` 허용 목록 필요. +- `!poll [sessionId]`는 백그라운드 bash 작업을 확인합니다. +- `!stop [sessionId]`는 백그라운드 bash 작업을 중지합니다. + +### 생성된 dock 명령 + +Dock 명령은 네이티브 명령 지원이 있는 채널 plugins에서 생성됩니다. 현재 번들된 세트: + +- `/dock-discord`(별칭: `/dock_discord`) +- `/dock-mattermost`(별칭: `/dock_mattermost`) +- `/dock-slack`(별칭: `/dock_slack`) +- `/dock-telegram`(별칭: `/dock_telegram`) + +### 번들된 plugin 명령 + +번들된 plugins는 더 많은 슬래시 명령을 추가할 수 있습니다. 이 리포지토리의 현재 번들 명령: + +- `/dreaming [on|off|status|help]`는 메모리 dreaming을 전환합니다. [Dreaming](/ko/concepts/dreaming)을 참조하세요. +- `/pair [qr|status|pending|approve|cleanup|notify]`는 디바이스 페어링/설정 흐름을 관리합니다. [Pairing](/ko/channels/pairing)을 참조하세요. +- `/phone status|arm [duration]|disarm`은 고위험 phone 노드 명령을 일시적으로 활성화합니다. +- `/voice status|list [limit]|set `는 Talk 음성 구성을 관리합니다. Discord에서 네이티브 명령 이름은 `/talkvoice`입니다. +- `/card ...`는 LINE 리치 카드 프리셋을 전송합니다. [LINE](/ko/channels/line)을 참조하세요. +- QQBot 전용 명령: + - `/bot-ping` + - `/bot-version` + - `/bot-help` + - `/bot-upgrade` + - `/bot-logs` + +### 동적 skill 명령 + +사용자가 호출할 수 있는 skills도 슬래시 명령으로 노출됩니다: + +- `/skill [input]`은 항상 일반 진입점으로 동작합니다. +- skill/plugin이 등록하면 `/prose` 같은 직접 명령으로도 나타날 수 있습니다. +- 네이티브 skill 명령 등록은 `commands.nativeSkills`와 `channels..commands.nativeSkills`로 제어됩니다. 참고: -- 명령은 명령과 인수 사이에 선택적으로 `:`를 받을 수 있습니다(예: `/think: high`, `/send: on`, `/help:`). -- `/new `은 모델 별칭, `provider/model`, 또는 공급자 이름(퍼지 매칭)을 받습니다. 일치하지 않으면 텍스트는 메시지 본문으로 처리됩니다. -- 전체 공급자 사용량 분석은 `openclaw status --usage`를 사용하세요. +- 명령은 명령과 인수 사이에 선택적 `:`를 받을 수 있습니다(예: `/think: high`, `/send: on`, `/help:`). +- `/new `은 모델 별칭, `provider/model`, 또는 provider 이름(퍼지 매치)을 받을 수 있으며, 일치하는 것이 없으면 텍스트는 메시지 본문으로 처리됩니다. +- 전체 provider 사용량 분석에는 `openclaw status --usage`를 사용하세요. - `/allowlist add|remove`는 `commands.config=true`가 필요하며 채널 `configWrites`를 따릅니다. -- 멀티 계정 채널에서는 config 대상 `/allowlist --account `와 `/config set channels..accounts....`도 대상 계정의 `configWrites`를 따릅니다. +- 다중 계정 채널에서 구성 대상 `/allowlist --account `와 `/config set channels..accounts....`도 대상 계정의 `configWrites`를 따릅니다. - `/usage`는 응답별 사용량 푸터를 제어합니다. `/usage cost`는 OpenClaw 세션 로그에서 로컬 비용 요약을 출력합니다. -- `/restart`는 기본적으로 활성화됩니다. 비활성화하려면 `commands.restart: false`를 설정하세요. -- Discord 전용 네이티브 명령: `/vc join|leave|status`는 음성 채널을 제어합니다(`channels.discord.voice`와 네이티브 명령 필요, 텍스트로는 사용 불가). +- `/restart`는 기본적으로 활성화되어 있습니다. 비활성화하려면 `commands.restart: false`를 설정하세요. +- `/plugins install `은 `openclaw plugins install`과 동일한 plugin spec을 받습니다: 로컬 경로/아카이브, npm 패키지, 또는 `clawhub:`. +- `/plugins enable|disable`는 plugin 구성을 업데이트하며 재시작을 요청할 수 있습니다. +- Discord 전용 네이티브 명령: `/vc join|leave|status`는 음성 채널을 제어합니다(`channels.discord.voice` 및 네이티브 명령 필요, 텍스트로는 사용 불가). - Discord 스레드 바인딩 명령(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`)은 유효한 스레드 바인딩이 활성화되어 있어야 합니다(`session.threadBindings.enabled` 및/또는 `channels.discord.threadBindings.enabled`). -- ACP 명령 참조와 런타임 동작: [ACP Agents](/ko/tools/acp-agents). -- `/verbose`는 디버깅과 추가 가시성을 위한 것입니다. 일반 사용에서는 **꺼둔 상태**를 유지하세요. -- `/fast on|off`는 세션 재정의를 유지합니다. 이를 지우고 config 기본값으로 되돌리려면 Sessions UI의 `inherit` 옵션을 사용하세요. -- `/fast`는 공급자별입니다. OpenAI/OpenAI Codex는 이를 네이티브 Responses 엔드포인트에서 `service_tier=priority`로 매핑하는 반면, `api.anthropic.com`으로 보내는 OAuth 인증 트래픽을 포함한 직접 공개 Anthropic 요청은 이를 `service_tier=auto` 또는 `standard_only`로 매핑합니다. [OpenAI](/ko/providers/openai) 및 [Anthropic](/ko/providers/anthropic)을 참고하세요. -- 도구 실패 요약은 관련이 있을 때 계속 표시되지만, 자세한 실패 텍스트는 `/verbose`가 `on` 또는 `full`일 때만 포함됩니다. -- `/reasoning`(및 `/verbose`)은 그룹 설정에서 위험할 수 있습니다. 노출 의도가 없던 내부 reasoning 또는 도구 출력을 드러낼 수 있습니다. 특히 그룹 채팅에서는 꺼 두는 것이 좋습니다. -- `/model`은 새로운 세션 모델을 즉시 유지합니다. -- 에이전트가 유휴 상태이면 다음 실행에서 즉시 사용됩니다. -- 실행이 이미 진행 중이면 OpenClaw는 live 전환을 보류로 표시하고 깔끔한 재시도 지점에서만 새 모델로 재시작합니다. -- 도구 활동이나 응답 출력이 이미 시작되었다면, 보류 중인 전환은 나중 재시도 기회나 다음 사용자 턴까지 대기할 수 있습니다. -- **빠른 경로:** allowlist에 있는 발신자의 명령 전용 메시지는 즉시 처리됩니다(큐 + 모델 우회). -- **그룹 멘션 게이팅:** allowlist에 있는 발신자의 명령 전용 메시지는 멘션 요구 사항을 우회합니다. -- **인라인 단축키(allowlist에 있는 발신자만):** 일부 명령은 일반 메시지 안에 포함되어도 동작하며 모델이 남은 텍스트를 보기 전에 제거됩니다. - - 예: `hey /status`는 상태 응답을 트리거하고, 남은 텍스트는 정상 흐름으로 계속 진행됩니다. +- ACP 명령 참조 및 런타임 동작: [ACP 에이전트](/ko/tools/acp-agents). +- `/verbose`는 디버깅과 추가 가시성을 위한 것입니다. 일반 사용에서는 **꺼짐**으로 유지하세요. +- `/fast on|off`는 세션 재정의를 유지합니다. 이를 지우고 구성 기본값으로 되돌리려면 Sessions UI의 `inherit` 옵션을 사용하세요. +- `/fast`는 provider별입니다: OpenAI/OpenAI Codex는 이를 네이티브 Responses 엔드포인트에서 `service_tier=priority`에 매핑하고, `api.anthropic.com`으로 전송되는 OAuth 인증 트래픽을 포함한 직접 공개 Anthropic 요청은 이를 `service_tier=auto` 또는 `standard_only`에 매핑합니다. [OpenAI](/ko/providers/openai)와 [Anthropic](/ko/providers/anthropic)을 참조하세요. +- 도구 실패 요약은 관련 있을 때 여전히 표시되지만, 자세한 실패 텍스트는 `/verbose`가 `on` 또는 `full`일 때만 포함됩니다. +- `/reasoning`(및 `/verbose`)은 그룹 설정에서 위험할 수 있습니다. 노출하려 하지 않았던 내부 reasoning 또는 도구 출력을 드러낼 수 있습니다. 특히 그룹 채팅에서는 꺼둔 상태를 유지하는 것이 좋습니다. +- `/model`은 새 세션 모델을 즉시 유지합니다. +- 에이전트가 유휴 상태이면 다음 실행에서 바로 사용합니다. +- 이미 실행이 활성 상태이면 OpenClaw는 라이브 전환을 보류 중으로 표시하고 깔끔한 재시도 시점에만 새 모델로 재시작합니다. +- 도구 활동이나 응답 출력이 이미 시작된 경우, 보류 중인 전환은 이후 재시도 기회나 다음 사용자 턴까지 대기열에 남을 수 있습니다. +- **빠른 경로:** 허용 목록에 있는 발신자의 명령 전용 메시지는 즉시 처리됩니다(큐 + 모델 우회). +- **그룹 멘션 게이팅:** 허용 목록에 있는 발신자의 명령 전용 메시지는 멘션 요구 사항을 우회합니다. +- **인라인 바로가기(허용 목록에 있는 발신자만):** 일부 명령은 일반 메시지에 포함되어 있어도 동작하며, 모델이 나머지 텍스트를 보기 전에 제거됩니다. + - 예: `hey /status`는 상태 응답을 트리거하고, 남은 텍스트는 일반 흐름을 계속 따릅니다. - 현재: `/help`, `/commands`, `/status`, `/whoami` (`/id`) -- 권한 없는 명령 전용 메시지는 조용히 무시되며, 인라인 `/...` 토큰은 일반 텍스트로 처리됩니다. -- **Skill commands:** `user-invocable` skills는 slash command로 노출됩니다. 이름은 `a-z0-9_`로 정리되며(최대 32자), 충돌 시 숫자 접미사가 붙습니다(예: `_2`). - - `/skill [input]`은 이름으로 skill을 실행합니다(skill별 명령에 대한 네이티브 명령 제한이 있을 때 유용). - - 기본적으로 skill 명령은 정상 요청으로 모델에 전달됩니다. - - skills는 선택적으로 `command-dispatch: tool`을 선언하여 명령을 도구로 직접 라우팅할 수 있습니다(결정적, 모델 없음). - - 예: `/prose` (OpenProse plugin) — [OpenProse](/ko/prose) 참고 -- **네이티브 명령 인수:** Discord는 동적 옵션에 autocomplete를 사용합니다(필수 인수를 생략하면 버튼 메뉴도 사용). Telegram과 Slack은 명령이 선택지를 지원하고 인수를 생략하면 버튼 메뉴를 표시합니다. +- 권한이 없는 명령 전용 메시지는 조용히 무시되며, 인라인 `/...` 토큰은 일반 텍스트로 처리됩니다. +- **Skill 명령:** `user-invocable` skills는 슬래시 명령으로 노출됩니다. 이름은 `a-z0-9_`로 정리되며(최대 32자), 충돌 시 숫자 접미사가 붙습니다(예: `_2`). + - `/skill [input]`은 이름으로 skill을 실행합니다(네이티브 명령 제한 때문에 skill별 명령이 불가능할 때 유용). + - 기본적으로 skill 명령은 일반 요청으로 모델에 전달됩니다. + - skill은 선택적으로 `command-dispatch: tool`을 선언하여 명령을 직접 도구로 라우팅할 수 있습니다(결정적이며 모델 없음). + - 예: `/prose`(OpenProse plugin) — [OpenProse](/ko/prose)를 참조하세요. +- **네이티브 명령 인수:** Discord는 동적 옵션에 자동완성을 사용합니다(필수 인수를 생략하면 버튼 메뉴도 사용). Telegram과 Slack은 명령이 선택지를 지원하고 인수를 생략하면 버튼 메뉴를 표시합니다. ## `/tools` -`/tools`는 config 질문이 아니라 런타임 질문에 답합니다. 즉, **이 에이전트가 지금 -이 대화에서 실제로 무엇을 사용할 수 있는가**입니다. +`/tools`는 구성 질문이 아니라 런타임 질문에 답합니다: **이 에이전트가 지금 +이 대화에서 무엇을 사용할 수 있는가**. -- 기본 `/tools`는 compact하며 빠르게 훑어보기에 최적화되어 있습니다. +- 기본 `/tools`는 간결하며 빠르게 훑어보기에 최적화되어 있습니다. - `/tools verbose`는 짧은 설명을 추가합니다. - 인수를 지원하는 네이티브 명령 표면은 `compact|verbose`와 같은 모드 전환을 노출합니다. -- 결과는 세션 범위이므로 에이전트, 채널, 스레드, 발신자 권한, 모델을 변경하면 출력이 - 달라질 수 있습니다. -- `/tools`에는 core 도구, 연결된 - plugin 도구, 채널 소유 도구를 포함하여 런타임에서 실제 도달 가능한 도구가 포함됩니다. +- 결과는 세션 범위이므로 에이전트, 채널, 스레드, 발신자 권한, 또는 모델을 변경하면 + 출력이 바뀔 수 있습니다. +- `/tools`는 코어 도구, 연결된 + plugin 도구, 채널 소유 도구를 포함해 런타임에서 실제로 도달 가능한 도구를 포함합니다. -프로필 및 재정의 편집은 `/tools`를 정적 카탈로그처럼 다루기보다 -Control UI Tools 패널이나 config/catalog 표면을 사용하세요. +프로필 및 재정의 편집은 `/tools`를 정적 카탈로그처럼 취급하는 대신 +Control UI Tools 패널 또는 구성/카탈로그 표면을 사용하세요. ## 사용량 표면(어디에 무엇이 표시되는지) -- **공급자 사용량/할당량**(예: “Claude 80% left”)은 사용량 추적이 활성화되어 있을 때 현재 모델 공급자에 대해 `/status`에 표시됩니다. OpenClaw는 공급자 기간을 `% left`로 정규화합니다. MiniMax의 경우 남은 양만 나타내는 퍼센트 필드는 표시 전에 반전되며, `model_remains` 응답은 채팅 모델 항목과 모델 태그가 붙은 플랜 레이블을 우선 사용합니다. -- `/status`의 **토큰/캐시 줄**은 live 세션 스냅샷이 빈약할 때 최신 transcript 사용량 항목으로 폴백할 수 있습니다. 기존의 0이 아닌 live 값은 여전히 우선하며, transcript 폴백은 저장된 총계가 없거나 더 작을 때 활성 런타임 모델 레이블과 더 큰 프롬프트 지향 총량도 복구할 수 있습니다. -- **응답별 토큰/비용**은 `/usage off|tokens|full`로 제어됩니다(일반 응답에 덧붙여짐). +- **Provider 사용량/할당량**(예: “Claude 80% left”)은 사용량 추적이 활성화되어 있을 때 현재 모델 provider의 `/status`에 표시됩니다. OpenClaw는 provider 윈도우를 `% left`로 정규화합니다. MiniMax의 경우 남은 비율 전용 필드는 표시 전에 반전되며, `model_remains` 응답은 모델 태그가 있는 플랜 라벨과 함께 채팅 모델 항목을 우선합니다. +- `/status`의 **토큰/캐시 줄**은 라이브 세션 스냅샷이 희소할 때 최신 대화 기록 사용량 항목으로 대체될 수 있습니다. 기존의 0이 아닌 라이브 값이 여전히 우선하며, 대화 기록 대체는 저장된 총계가 없거나 더 작을 때 활성 런타임 모델 라벨과 더 큰 프롬프트 지향 총계도 복구할 수 있습니다. +- **응답별 토큰/비용**은 `/usage off|tokens|full`로 제어됩니다(일반 응답에 추가됨). - `/model status`는 사용량이 아니라 **모델/인증/엔드포인트**에 관한 것입니다. -## 모델 선택(`/model`) +## 모델 선택(``/model`) -`/model`은 directive로 구현됩니다. +`/model`은 지시어로 구현됩니다. -예시: +예: ``` /model @@ -212,16 +249,16 @@ Control UI Tools 패널이나 config/catalog 표면을 사용하세요. 참고: -- `/model`과 `/model list`는 compact하고 번호가 매겨진 선택기(모델 패밀리 + 사용 가능한 공급자)를 표시합니다. -- Discord에서는 `/model`과 `/models`가 공급자 및 모델 드롭다운과 Submit 단계가 있는 대화형 선택기를 엽니다. -- `/model <#>`는 해당 선택기에서 선택합니다(가능하면 현재 공급자를 우선함). -- `/model status`는 자세한 보기를 표시하며, 사용 가능한 경우 구성된 공급자 엔드포인트(`baseUrl`)와 API 모드(`api`)를 포함합니다. +- `/model`과 `/model list`는 간결한 번호형 선택기(모델 패밀리 + 사용 가능한 providers)를 보여줍니다. +- Discord에서 `/model`과 `/models`는 provider 및 모델 드롭다운과 Submit 단계를 포함한 대화형 선택기를 엽니다. +- `/model <#>`는 해당 선택기에서 선택합니다(가능하면 현재 provider를 우선). +- `/model status`는 구성된 provider 엔드포인트(`baseUrl`)와 가능한 경우 API 모드(`api`)를 포함한 자세한 보기를 보여줍니다. ## 디버그 재정의 -`/debug`를 사용하면 **런타임 전용** config 재정의(메모리, 디스크 아님)를 설정할 수 있습니다. 소유자 전용입니다. 기본적으로 비활성화되어 있으며 `commands.debug: true`로 활성화하세요. +`/debug`는 **런타임 전용** 구성 재정의(메모리, 디스크 아님)를 설정할 수 있게 합니다. 소유자 전용. 기본적으로 비활성화되어 있으며 `commands.debug: true`로 활성화합니다. -예시: +예: ``` /debug show @@ -233,14 +270,14 @@ Control UI Tools 패널이나 config/catalog 표면을 사용하세요. 참고: -- 재정의는 새 config 읽기에 즉시 적용되지만 `openclaw.json`에 기록되지는 않습니다. -- 모든 재정의를 지우고 디스크의 config로 돌아가려면 `/debug reset`을 사용하세요. +- 재정의는 새 구성 읽기에 즉시 적용되지만 `openclaw.json`에는 쓰지 않습니다. +- 모든 재정의를 지우고 디스크의 구성으로 돌아가려면 `/debug reset`을 사용하세요. -## Config 업데이트 +## 구성 업데이트 -`/config`는 디스크의 config(`openclaw.json`)에 기록합니다. 소유자 전용입니다. 기본적으로 비활성화되어 있으며 `commands.config: true`로 활성화하세요. +`/config`는 디스크의 구성(`openclaw.json`)에 씁니다. 소유자 전용. 기본적으로 비활성화되어 있으며 `commands.config: true`로 활성화합니다. -예시: +예: ``` /config show @@ -252,14 +289,14 @@ Control UI Tools 패널이나 config/catalog 표면을 사용하세요. 참고: -- config는 기록 전에 검증되며, 유효하지 않은 변경은 거부됩니다. +- 쓰기 전에 구성이 검증되며, 잘못된 변경은 거부됩니다. - `/config` 업데이트는 재시작 후에도 유지됩니다. ## MCP 업데이트 -`/mcp`는 `mcp.servers` 아래의 OpenClaw 관리 MCP server 정의를 기록합니다. 소유자 전용입니다. 기본적으로 비활성화되어 있으며 `commands.mcp: true`로 활성화하세요. +`/mcp`는 `mcp.servers` 아래의 OpenClaw 관리 MCP 서버 정의를 씁니다. 소유자 전용. 기본적으로 비활성화되어 있으며 `commands.mcp: true`로 활성화합니다. -예시: +예: ```text /mcp show @@ -270,14 +307,14 @@ Control UI Tools 패널이나 config/catalog 표면을 사용하세요. 참고: -- `/mcp`는 Pi 소유 프로젝트 설정이 아니라 OpenClaw config에 저장합니다. -- 실제로 어떤 전송이 실행 가능한지는 런타임 어댑터가 결정합니다. +- `/mcp`는 Pi 소유 프로젝트 설정이 아니라 OpenClaw 구성에 저장합니다. +- 어떤 전송을 실제로 실행할 수 있는지는 런타임 어댑터가 결정합니다. ## Plugin 업데이트 -`/plugins`를 통해 운영자는 탐색된 plugin을 검사하고 config에서 활성화를 전환할 수 있습니다. 읽기 전용 흐름에서는 `/plugin`을 별칭으로 사용할 수 있습니다. 기본적으로 비활성화되어 있으며 `commands.plugins: true`로 활성화하세요. +`/plugins`는 운영자가 검색된 plugins를 검사하고 구성에서 활성화 여부를 전환할 수 있게 합니다. 읽기 전용 흐름에서는 `/plugin`을 별칭으로 사용할 수 있습니다. 기본적으로 비활성화되어 있으며 `commands.plugins: true`로 활성화합니다. -예시: +예: ```text /plugins @@ -289,40 +326,41 @@ Control UI Tools 패널이나 config/catalog 표면을 사용하세요. 참고: -- `/plugins list`와 `/plugins show`는 현재 작업공간과 디스크상의 config를 기준으로 실제 plugin 탐색을 사용합니다. -- `/plugins enable|disable`는 plugin config만 업데이트하며 plugin을 설치하거나 제거하지는 않습니다. -- 활성화/비활성화 변경 후 적용하려면 gateway를 재시작하세요. +- `/plugins list`와 `/plugins show`는 현재 워크스페이스와 디스크 구성을 대상으로 실제 plugin 검색을 사용합니다. +- `/plugins enable|disable`는 plugin 구성만 업데이트하며 plugin을 설치하거나 제거하지 않습니다. +- 활성화/비활성화 변경 후에는 적용을 위해 gateway를 재시작하세요. ## 표면 참고 -- **텍스트 명령**은 정상 채팅 세션에서 실행됩니다(DM은 `main`을 공유하고, 그룹은 자체 세션을 가짐). -- **네이티브 명령**은 격리된 세션을 사용합니다. +- **텍스트 명령**은 일반 채팅 세션에서 실행됩니다(DM은 `main`을 공유하고, 그룹은 자체 세션을 가짐). +- **네이티브 명령**은 격리된 세션을 사용합니다: - Discord: `agent::discord:slash:` - - Slack: `agent::slack:slash:` (접두사는 `channels.slack.slashCommand.sessionPrefix`로 구성 가능) - - Telegram: `telegram:slash:` (`CommandTargetSessionKey`를 통해 채팅 세션을 대상으로 지정) + - Slack: `agent::slack:slash:`(접두사는 `channels.slack.slashCommand.sessionPrefix`로 구성 가능) + - Telegram: `telegram:slash:`(`CommandTargetSessionKey`를 통해 채팅 세션을 대상으로 함) - **`/stop`**은 활성 채팅 세션을 대상으로 하므로 현재 실행을 중단할 수 있습니다. -- **Slack:** `channels.slack.slashCommand`는 단일 `/openclaw` 스타일 명령용으로 여전히 지원됩니다. `commands.native`를 활성화하면 내장 명령마다 Slack slash command를 하나씩 만들어야 합니다(`/help`와 같은 이름). Slack용 명령 인수 메뉴는 ephemeral Block Kit 버튼으로 전달됩니다. - - Slack 네이티브 예외: Slack이 `/status`를 예약했기 때문에 `/status`가 아니라 `/agentstatus`를 등록하세요. 텍스트 `/status`는 Slack 메시지에서 계속 동작합니다. +- **Slack:** `channels.slack.slashCommand`는 단일 `/openclaw` 스타일 명령에 대해 여전히 지원됩니다. `commands.native`를 활성화하면 내장 명령마다 하나의 Slack 슬래시 명령을 만들어야 합니다(`/help`와 같은 이름). Slack용 명령 인수 메뉴는 임시 Block Kit 버튼으로 전달됩니다. + - Slack 네이티브 예외: Slack이 `/status`를 예약하므로 `/status`가 아니라 `/agentstatus`를 등록하세요. 텍스트 `/status`는 Slack 메시지에서 여전히 동작합니다. -## BTW 사이드 질문 +## BTW 곁가지 질문 -`/btw`는 현재 세션에 대한 빠른 **사이드 질문**입니다. +`/btw`는 현재 세션에 대한 빠른 **곁가지 질문**입니다. -일반 채팅과 달리 다음과 같습니다. +일반 채팅과 달리: - 현재 세션을 배경 컨텍스트로 사용하고, - 별도의 **도구 없는** 원샷 호출로 실행되며, -- 미래 세션 컨텍스트를 변경하지 않고, -- transcript 기록에 쓰이지 않으며, -- 일반 assistant 메시지 대신 live 사이드 결과로 전달됩니다. +- 미래 세션 컨텍스트를 바꾸지 않고, +- 대화 기록 히스토리에 기록되지 않으며, +- 일반 어시스턴트 메시지 대신 라이브 곁가지 결과로 전달됩니다. -따라서 `/btw`는 주요 -작업은 계속 진행하면서 일시적인 설명이 필요할 때 유용합니다. +따라서 `/btw`는 메인 +작업을 계속 진행하면서 일시적인 명확화가 필요할 때 유용합니다. -예시: +예: ```text -/btw what are we doing right now? +/btw 지금 우리는 무엇을 하고 있나요? ``` -전체 동작과 클라이언트 UX 세부 사항은 [BTW Side Questions](/ko/tools/btw)를 참고하세요. +전체 동작과 클라이언트 UX 세부 정보는 [BTW 곁가지 질문](/ko/tools/btw)을 +참조하세요. diff --git a/docs/ko/tools/tts.md b/docs/ko/tools/tts.md index b95663400..37cbd815d 100644 --- a/docs/ko/tools/tts.md +++ b/docs/ko/tools/tts.md @@ -1,57 +1,57 @@ --- read_when: - - 답장에 text-to-speech를 활성화하는 경우 - - TTS provider 또는 제한을 구성하는 경우 - - '`/tts` 명령을 사용하는 경우' -summary: 발신 답장을 위한 text-to-speech(TTS) -title: Text-to-Speech + - 답장에 텍스트 음성 변환을 활성화할 때 + - TTS 제공자나 제한을 구성할 때 + - '`/tts` 명령을 사용할 때' +summary: 발신 답장용 텍스트 음성 변환(TTS) +title: 텍스트 음성 변환 x-i18n: - generated_at: "2026-04-05T12:59:11Z" + generated_at: "2026-04-08T05:56:50Z" model: gpt-5.4 provider: openai - source_hash: 8487c8acef7585bd4eb5e3b39e2a063ebc6b5f0103524abdcbadd3a7781ffc46 + source_hash: 6e0fbcaf61282733c134f682e05a71f94d2169c03a85131ce9ad233c71a1e533 source_path: tools/tts.md workflow: 15 --- -# Text-to-speech (TTS) +# 텍스트 음성 변환(TTS) -OpenClaw는 ElevenLabs, Microsoft, MiniMax, 또는 OpenAI를 사용해 발신 답장을 오디오로 변환할 수 있습니다. +OpenClaw는 ElevenLabs, Microsoft, MiniMax 또는 OpenAI를 사용해 발신 답장을 오디오로 변환할 수 있습니다. 이 기능은 OpenClaw가 오디오를 보낼 수 있는 모든 곳에서 작동합니다. -## 지원되는 서비스 +## 지원 서비스 -- **ElevenLabs** (기본 또는 fallback provider) -- **Microsoft** (기본 또는 fallback provider; 현재 번들 구현은 `node-edge-tts` 사용) -- **MiniMax** (기본 또는 fallback provider; T2A v2 API 사용) -- **OpenAI** (기본 또는 fallback provider; 요약에도 사용) +- **ElevenLabs**(주 제공자 또는 대체 제공자) +- **Microsoft**(주 제공자 또는 대체 제공자, 현재 번들 구현은 `node-edge-tts` 사용) +- **MiniMax**(주 제공자 또는 대체 제공자, T2A v2 API 사용) +- **OpenAI**(주 제공자 또는 대체 제공자, 요약에도 사용) -### Microsoft speech 참고 사항 +### Microsoft 음성 참고 사항 -번들된 Microsoft speech provider는 현재 `node-edge-tts` 라이브러리를 통해 Microsoft Edge의 온라인 -neural TTS 서비스를 사용합니다. 이는 로컬이 아닌 호스팅 서비스이며, -Microsoft 엔드포인트를 사용하고 API 키가 필요하지 않습니다. -`node-edge-tts`는 speech 구성 옵션과 출력 형식을 제공하지만, -모든 옵션이 서비스에서 지원되는 것은 아닙니다. `edge`를 사용하는 레거시 구성 및 directive 입력은 -여전히 작동하며 `microsoft`로 정규화됩니다. +번들된 Microsoft 음성 제공자는 현재 `node-edge-tts` 라이브러리를 통해 +Microsoft Edge의 온라인 신경망 TTS 서비스를 사용합니다. 이는 호스팅된 +서비스이며(로컬 아님), Microsoft 엔드포인트를 사용하고, API 키가 필요하지 +않습니다. `node-edge-tts`는 음성 구성 옵션과 출력 형식을 제공하지만, +모든 옵션이 서비스에서 지원되는 것은 아닙니다. `edge`를 사용하는 레거시 +구성과 directive 입력도 계속 작동하며 `microsoft`로 정규화됩니다. -이 경로는 공개 웹 서비스이며 게시된 SLA나 quota가 없으므로, -best-effort로 취급하세요. 보장된 한도와 지원이 필요하다면 OpenAI +이 경로는 공개 웹 서비스이며 게시된 SLA나 할당량이 없으므로, +best-effort로 취급해야 합니다. 보장된 제한과 지원이 필요하다면 OpenAI 또는 ElevenLabs를 사용하세요. ## 선택적 키 -OpenAI, ElevenLabs, 또는 MiniMax를 사용하려면: +OpenAI, ElevenLabs 또는 MiniMax를 사용하려면: -- `ELEVENLABS_API_KEY` (또는 `XI_API_KEY`) +- `ELEVENLABS_API_KEY`(또는 `XI_API_KEY`) - `MINIMAX_API_KEY` - `OPENAI_API_KEY` -Microsoft speech에는 API 키가 **필요하지 않습니다**. +Microsoft 음성은 API 키가 **필요하지 않습니다**. -여러 provider가 구성된 경우 선택된 provider가 먼저 사용되고, 나머지는 fallback 옵션이 됩니다. +여러 제공자가 구성되어 있으면, 선택된 제공자를 먼저 사용하고 나머지는 대체 옵션으로 사용합니다. 자동 요약은 구성된 `summaryModel`(또는 `agents.defaults.model.primary`)을 사용하므로, -요약을 활성화한다면 해당 provider도 인증되어 있어야 합니다. +요약을 활성화했다면 해당 제공자도 인증되어 있어야 합니다. ## 서비스 링크 @@ -63,20 +63,20 @@ Microsoft speech에는 API 키가 **필요하지 않습니다**. - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) - [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -## 기본적으로 활성화되어 있나요? +## 기본으로 활성화되어 있나요? -아니요. 자동 TTS는 기본적으로 **꺼져 있습니다**. 구성에서 -`messages.tts.auto`로 활성화하거나 세션별로 `/tts always`(별칭: `/tts on`)로 활성화하세요. +아니요. 자동 TTS는 기본적으로 **비활성화**되어 있습니다. 구성에서 +`messages.tts.auto`로 활성화하거나, 로컬에서 `/tts on`으로 활성화하세요. -`messages.tts.provider`가 설정되지 않으면 OpenClaw는 registry 자동 선택 순서에서 -구성된 첫 번째 speech provider를 선택합니다. +`messages.tts.provider`가 설정되지 않은 경우, OpenClaw는 레지스트리 자동 선택 순서에서 +구성된 첫 번째 음성 제공자를 선택합니다. ## 구성 TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. 전체 스키마는 [Gateway configuration](/ko/gateway/configuration)에 있습니다. -### 최소 구성(활성화 + provider) +### 최소 구성(활성화 + 제공자) ```json5 { @@ -89,7 +89,7 @@ TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. } ``` -### OpenAI 기본 + ElevenLabs fallback +### OpenAI 주 제공자 + ElevenLabs 대체 제공자 ```json5 { @@ -130,7 +130,7 @@ TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. } ``` -### Microsoft 기본(API 키 없음) +### Microsoft 주 제공자(API 키 없음) ```json5 { @@ -153,7 +153,7 @@ TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. } ``` -### MiniMax 기본 +### MiniMax 주 제공자 ```json5 { @@ -177,7 +177,7 @@ TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. } ``` -### Microsoft speech 비활성화 +### Microsoft 음성 비활성화 ```json5 { @@ -232,7 +232,7 @@ TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. } ``` -그런 다음 다음을 실행하세요: +그다음 실행: ``` /tts summary off @@ -243,60 +243,62 @@ TTS 구성은 `openclaw.json`의 `messages.tts` 아래에 있습니다. - `auto`: 자동 TTS 모드(`off`, `always`, `inbound`, `tagged`). - `inbound`는 수신 음성 메시지 뒤에만 오디오를 보냅니다. - `tagged`는 답장에 `[[tts]]` 태그가 포함될 때만 오디오를 보냅니다. -- `enabled`: 레거시 토글입니다(doctor가 이를 `auto`로 마이그레이션함). +- `enabled`: 레거시 토글(`doctor`가 이를 `auto`로 마이그레이션). - `mode`: `"final"`(기본값) 또는 `"all"`(도구/블록 답장 포함). -- `provider`: `"elevenlabs"`, `"microsoft"`, `"minimax"`, 또는 `"openai"` 같은 speech provider id입니다(fallback은 자동). -- `provider`가 **설정되지 않으면**, OpenClaw는 registry 자동 선택 순서에서 구성된 첫 번째 speech provider를 사용합니다. -- 레거시 `provider: "edge"`도 여전히 작동하며 `microsoft`로 정규화됩니다. -- `summaryModel`: 자동 요약용 선택적 저비용 모델입니다. 기본값은 `agents.defaults.model.primary`입니다. +- `provider`: `"elevenlabs"`, `"microsoft"`, `"minimax"`, `"openai"` 같은 음성 제공자 ID(대체는 자동). +- `provider`가 **설정되지 않은** 경우, OpenClaw는 레지스트리 자동 선택 순서에서 구성된 첫 번째 음성 제공자를 사용합니다. +- 레거시 `provider: "edge"`도 계속 작동하며 `microsoft`로 정규화됩니다. +- `summaryModel`: 자동 요약용 선택적 저비용 모델, 기본값은 `agents.defaults.model.primary`. - `provider/model` 또는 구성된 모델 별칭을 허용합니다. -- `modelOverrides`: 모델이 TTS directive를 출력할 수 있도록 허용합니다(기본적으로 활성화). - - `allowProvider`의 기본값은 `false`입니다(provider 전환은 opt-in). -- `providers.`: speech provider id를 키로 하는 provider 소유 설정입니다. -- 레거시 직접 provider 블록(`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`)은 로드 시 `messages.tts.providers.`로 자동 마이그레이션됩니다. -- `maxTextLength`: TTS 입력의 하드 상한(문자 수)입니다. 초과하면 `/tts audio`가 실패합니다. -- `timeoutMs`: 요청 timeout(ms)입니다. -- `prefsPath`: 로컬 prefs JSON 경로(provider/limit/summary)를 재정의합니다. -- `apiKey` 값은 env vars(`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`)로 fallback됩니다. -- `providers.elevenlabs.baseUrl`: ElevenLabs API 기본 URL을 재정의합니다. -- `providers.openai.baseUrl`: OpenAI TTS 엔드포인트를 재정의합니다. +- `modelOverrides`: 모델이 TTS directive를 내보내도록 허용합니다(기본적으로 활성화). + - `allowProvider` 기본값은 `false`입니다(제공자 전환은 opt-in). +- `providers.`: 음성 제공자 ID를 키로 하는 제공자 소유 설정. +- 레거시 직접 제공자 블록(`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`)은 로드 시 `messages.tts.providers.`로 자동 마이그레이션됩니다. +- `maxTextLength`: TTS 입력의 하드 상한(문자 수). 초과하면 `/tts audio`는 실패합니다. +- `timeoutMs`: 요청 타임아웃(ms). +- `prefsPath`: 로컬 prefs JSON 경로 재정의(provider/limit/summary). +- `apiKey` 값은 env vars(`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`)로 대체될 수 있습니다. +- `providers.elevenlabs.baseUrl`: ElevenLabs API 기본 URL 재정의. +- `providers.openai.baseUrl`: OpenAI TTS 엔드포인트 재정의. - 확인 순서: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 기본값이 아닌 값은 OpenAI 호환 TTS 엔드포인트로 취급되므로 사용자 지정 모델 및 voice 이름이 허용됩니다. + - 기본값이 아닌 값은 OpenAI 호환 TTS 엔드포인트로 취급되므로, 사용자 지정 모델 및 음성 이름을 허용합니다. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` - - `speed`: `0.5..2.0` (1.0 = 보통) + - `speed`: `0.5..2.0`(1.0 = 보통) - `providers.elevenlabs.applyTextNormalization`: `auto|on|off` -- `providers.elevenlabs.languageCode`: 2자리 ISO 639-1 (예: `en`, `de`) -- `providers.elevenlabs.seed`: 정수 `0..4294967295` (best-effort 결정성) -- `providers.minimax.baseUrl`: MiniMax API 기본 URL을 재정의합니다(기본값 `https://api.minimax.io`, env: `MINIMAX_API_HOST`). -- `providers.minimax.model`: TTS 모델입니다(기본값 `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). -- `providers.minimax.voiceId`: 음성 식별자입니다(기본값 `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). -- `providers.minimax.speed`: 재생 속도 `0.5..2.0` (기본값 1.0). -- `providers.minimax.vol`: 볼륨 `(0, 10]` (기본값 1.0, 0보다 커야 함). -- `providers.minimax.pitch`: 피치 시프트 `-12..12` (기본값 0). -- `providers.microsoft.enabled`: Microsoft speech 사용을 허용합니다(기본값 `true`, API 키 없음). -- `providers.microsoft.voice`: Microsoft neural voice 이름입니다(예: `en-US-MichelleNeural`). -- `providers.microsoft.lang`: 언어 코드입니다(예: `en-US`). -- `providers.microsoft.outputFormat`: Microsoft 출력 형식입니다(예: `audio-24khz-48kbitrate-mono-mp3`). - - 유효한 값은 Microsoft Speech output formats를 참조하세요. 번들된 Edge 기반 전송에서는 일부 형식만 지원됩니다. -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: 퍼센트 문자열입니다(예: `+10%`, `-5%`). +- `providers.elevenlabs.languageCode`: 2글자 ISO 639-1(예: `en`, `de`) +- `providers.elevenlabs.seed`: 정수 `0..4294967295`(best-effort 결정성) +- `providers.minimax.baseUrl`: MiniMax API 기본 URL 재정의(기본값 `https://api.minimax.io`, env: `MINIMAX_API_HOST`). +- `providers.minimax.model`: TTS 모델(기본값 `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). +- `providers.minimax.voiceId`: 음성 식별자(기본값 `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). +- `providers.minimax.speed`: 재생 속도 `0.5..2.0`(기본값 1.0). +- `providers.minimax.vol`: 볼륨 `(0, 10]`(기본값 1.0, 0보다 커야 함). +- `providers.minimax.pitch`: 피치 이동 `-12..12`(기본값 0). +- `providers.microsoft.enabled`: Microsoft 음성 사용 허용(기본값 `true`, API 키 없음). +- `providers.microsoft.voice`: Microsoft 신경망 음성 이름(예: `en-US-MichelleNeural`). +- `providers.microsoft.lang`: 언어 코드(예: `en-US`). +- `providers.microsoft.outputFormat`: Microsoft 출력 형식(예: `audio-24khz-48kbitrate-mono-mp3`). + - 유효한 값은 Microsoft Speech output formats를 참조하세요. 번들된 Edge 기반 전송에서 모든 형식을 지원하는 것은 아닙니다. +- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: 퍼센트 문자열(예: `+10%`, `-5%`). - `providers.microsoft.saveSubtitles`: 오디오 파일과 함께 JSON 자막을 기록합니다. -- `providers.microsoft.proxy`: Microsoft speech 요청용 프록시 URL입니다. -- `providers.microsoft.timeoutMs`: 요청 timeout 재정의(ms)입니다. -- `edge.*`: 동일한 Microsoft 설정에 대한 레거시 별칭입니다. +- `providers.microsoft.proxy`: Microsoft 음성 요청용 프록시 URL. +- `providers.microsoft.timeoutMs`: 요청 타임아웃 재정의(ms). +- `edge.*`: 동일한 Microsoft 설정에 대한 레거시 별칭. ## 모델 기반 재정의(기본적으로 활성화) -기본적으로 모델은 단일 답장에 대해 TTS directive를 출력할 **수 있습니다**. -`messages.tts.auto`가 `tagged`인 경우 오디오를 트리거하려면 이 directive가 필요합니다. +기본적으로 모델은 단일 답장에 대해 TTS directive를 내보낼 수 **있습니다**. +`messages.tts.auto`가 `tagged`일 때는 오디오를 트리거하려면 이러한 directive가 필요합니다. -활성화되어 있으면 모델은 단일 답장의 voice를 재정의하기 위한 `[[tts:...]]` directive와, -오디오에만 나타나야 하는 표현 태그(웃음, 노래 큐 등)를 제공하기 위한 선택적 `[[tts:text]]...[[/tts:text]]` 블록을 출력할 수 있습니다. +활성화되면 모델은 단일 답장의 음성을 재정의하기 위해 `[[tts:...]]` directive를 내보낼 수 있고, +선택적으로 `[[tts:text]]...[[/tts:text]]` 블록을 사용해 +표현 태그(웃음, 노래 신호 등)를 제공할 수 있습니다. 이러한 내용은 +오디오에만 나타나야 합니다. -`provider=...` directive는 `modelOverrides.allowProvider: true`가 아닌 한 무시됩니다. +`provider=...` directive는 `modelOverrides.allowProvider: true`가 아니면 무시됩니다. -예시 답장 payload: +답장 payload 예시: ``` Here you go. @@ -307,14 +309,14 @@ Here you go. 사용 가능한 directive 키(활성화된 경우): -- `provider` (등록된 speech provider id, 예: `openai`, `elevenlabs`, `minimax`, 또는 `microsoft`; `allowProvider: true` 필요) -- `voice` (OpenAI voice) 또는 `voiceId` (ElevenLabs / MiniMax) -- `model` (OpenAI TTS 모델, ElevenLabs model id, 또는 MiniMax 모델) +- `provider`(등록된 음성 제공자 ID, 예: `openai`, `elevenlabs`, `minimax`, `microsoft`; `allowProvider: true` 필요) +- `voice`(OpenAI 음성) 또는 `voiceId`(ElevenLabs / MiniMax) +- `model`(OpenAI TTS 모델, ElevenLabs 모델 ID 또는 MiniMax 모델) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` -- `vol` / `volume` (MiniMax 볼륨, 0-10) -- `pitch` (MiniMax 피치, -12 ~ 12) -- `applyTextNormalization` (`auto|on|off`) -- `languageCode` (ISO 639-1) +- `vol` / `volume`(MiniMax 볼륨, 0-10) +- `pitch`(MiniMax 피치, -12 ~ 12) +- `applyTextNormalization`(`auto|on|off`) +- `languageCode`(ISO 639-1) - `seed` 모든 모델 재정의 비활성화: @@ -331,7 +333,7 @@ Here you go. } ``` -선택적 allowlist(provider 전환은 허용하면서 다른 조절 항목은 계속 구성 가능): +선택적 allowlist(제공자 전환을 활성화하면서 다른 설정은 구성 가능하게 유지): ```json5 { @@ -347,77 +349,75 @@ Here you go. } ``` -## 사용자별 환경설정 +## 사용자별 기본 설정 -슬래시 명령은 로컬 재정의를 `prefsPath`(기본값: +슬래시 명령은 로컬 재정의를 `prefsPath`에 기록합니다(기본값: `~/.openclaw/settings/tts.json`, `OPENCLAW_TTS_PREFS` 또는 -`messages.tts.prefsPath`로 재정의 가능)에 기록합니다. +`messages.tts.prefsPath`로 재정의 가능). 저장되는 필드: - `enabled` - `provider` -- `maxLength` (요약 임곗값, 기본값 1500자) -- `summarize` (기본값 `true`) +- `maxLength`(요약 임계값, 기본값 1500자) +- `summarize`(기본값 `true`) -이 값들은 해당 호스트에서 `messages.tts.*`를 재정의합니다. +이 값들은 해당 호스트의 `messages.tts.*`를 재정의합니다. ## 출력 형식(고정) - **Feishu / Matrix / Telegram / WhatsApp**: Opus 음성 메시지(ElevenLabs의 `opus_48000_64`, OpenAI의 `opus`). - - 48kHz / 64kbps는 음성 메시지에 적절한 절충안입니다. + - 48kHz / 64kbps는 음성 메시지에 적합한 절충안입니다. - **기타 채널**: MP3(ElevenLabs의 `mp3_44100_128`, OpenAI의 `mp3`). - - 44.1kHz / 128kbps는 음성 명료도를 위한 기본 균형값입니다. -- **MiniMax**: MP3(`speech-2.8-hd` 모델, 32kHz 샘플 레이트). 음성 노트 형식을 기본 지원하지 않으므로, 보장된 Opus 음성 메시지가 필요하면 OpenAI 또는 ElevenLabs를 사용하세요. -- **Microsoft**: `microsoft.outputFormat`을 사용합니다(기본값 `audio-24khz-48kbitrate-mono-mp3`). - - 번들 전송은 `outputFormat`을 허용하지만, 모든 형식을 서비스에서 사용할 수 있는 것은 아닙니다. + - 44.1kHz / 128kbps는 음성 명료도를 위한 기본 균형입니다. +- **MiniMax**: MP3(`speech-2.8-hd` 모델, 32kHz 샘플링 속도). 음성 노트 형식은 기본 지원되지 않으므로, Opus 음성 메시지가 반드시 필요하면 OpenAI 또는 ElevenLabs를 사용하세요. +- **Microsoft**: `microsoft.outputFormat` 사용(기본값 `audio-24khz-48kbitrate-mono-mp3`). + - 번들된 전송은 `outputFormat`을 허용하지만, 모든 형식을 서비스에서 사용할 수 있는 것은 아닙니다. - 출력 형식 값은 Microsoft Speech output formats를 따릅니다(Ogg/WebM Opus 포함). - - Telegram `sendVoice`는 OGG/MP3/M4A를 허용합니다. 보장된 Opus 음성 메시지가 필요하면 OpenAI/ElevenLabs를 사용하세요. - - 구성된 Microsoft 출력 형식이 실패하면 OpenClaw는 MP3로 다시 시도합니다. + - Telegram `sendVoice`는 OGG/MP3/M4A를 허용합니다. Opus 음성 메시지가 반드시 필요하면 OpenAI/ElevenLabs를 사용하세요. + - 구성된 Microsoft 출력 형식이 실패하면 OpenClaw는 MP3로 재시도합니다. -OpenAI/ElevenLabs 출력 형식은 채널별로 고정됩니다(위 참고). +OpenAI/ElevenLabs 출력 형식은 채널별로 고정됩니다(위 참조). ## 자동 TTS 동작 -활성화되면 OpenClaw는: +활성화되면 OpenClaw는 다음과 같이 동작합니다. -- 답장에 이미 미디어 또는 `MEDIA:` directive가 있으면 TTS를 건너뜁니다. -- 너무 짧은 답장(< 10자)은 건너뜁니다. -- 긴 답장은 활성화된 경우 `agents.defaults.model.primary`(또는 `summaryModel`)를 사용해 요약합니다. +- 답장에 이미 미디어 또는 `MEDIA:` directive가 포함되어 있으면 TTS를 건너뜁니다. +- 매우 짧은 답장(< 10자)은 건너뜁니다. +- 활성화된 경우 긴 답장을 `agents.defaults.model.primary`(또는 `summaryModel`)를 사용해 요약합니다. - 생성된 오디오를 답장에 첨부합니다. -답장이 `maxLength`를 초과하고 요약이 꺼져 있거나(또는 -summary model용 API 키가 없으면), 오디오는 -건너뛰고 일반 텍스트 답장을 전송합니다. +답장이 `maxLength`를 초과하고 요약이 비활성화되어 있거나(또는 +요약 모델에 대한 API 키가 없는 경우), 오디오는 +건너뛰고 일반 텍스트 답장을 보냅니다. ## 흐름도 ``` Reply -> TTS enabled? - no -> 텍스트 전송 - yes -> 미디어 / MEDIA: / 짧은 답장인가? - yes -> 텍스트 전송 - no -> 길이 > 제한? - no -> TTS -> 오디오 첨부 - yes -> 요약 활성화됨? - no -> 텍스트 전송 - yes -> 요약(summaryModel 또는 agents.defaults.model.primary) - -> TTS -> 오디오 첨부 + no -> send text + yes -> has media / MEDIA: / short? + yes -> send text + no -> length > limit? + no -> TTS -> attach audio + yes -> summary enabled? + no -> send text + yes -> summarize (summaryModel or agents.defaults.model.primary) + -> TTS -> attach audio ``` ## 슬래시 명령 사용법 명령은 하나뿐입니다: `/tts`. -활성화 세부 사항은 [Slash commands](/tools/slash-commands)를 참조하세요. +활성화 세부 정보는 [Slash commands](/ko/tools/slash-commands)를 참조하세요. -Discord 참고: `/tts`는 Discord 기본 명령이므로 OpenClaw는 -거기에서 네이티브 명령으로 `/voice`를 등록합니다. 텍스트 `/tts ...`는 여전히 작동합니다. +Discord 참고: `/tts`는 Discord 기본 명령이므로, OpenClaw는 +그곳에서 `/voice`를 네이티브 명령으로 등록합니다. 텍스트 `/tts ...`도 계속 작동합니다. ``` /tts off -/tts always -/tts inbound -/tts tagged +/tts on /tts status /tts provider openai /tts limit 2000 @@ -427,21 +427,23 @@ Discord 참고: `/tts`는 Discord 기본 명령이므로 OpenClaw는 참고 사항: -- 명령에는 인증된 발신자가 필요합니다(allowlist/owner 규칙은 계속 적용됨). +- 명령에는 인증된 발신자가 필요합니다(allowlist/owner 규칙이 계속 적용됨). - `commands.text` 또는 네이티브 명령 등록이 활성화되어 있어야 합니다. -- `off|always|inbound|tagged`는 세션별 토글입니다(`/tts on`은 `/tts always`의 별칭). -- `limit` 및 `summary`는 메인 구성이 아니라 로컬 prefs에 저장됩니다. +- 구성 `messages.tts.auto`는 `off|always|inbound|tagged`를 허용합니다. +- `/tts on`은 로컬 TTS 기본 설정을 `always`로 기록하고, `/tts off`는 `off`로 기록합니다. +- `inbound` 또는 `tagged` 기본값을 원하면 구성을 사용하세요. +- `limit`과 `summary`는 메인 구성이 아니라 로컬 prefs에 저장됩니다. - `/tts audio`는 일회성 오디오 답장을 생성합니다(TTS를 켜지 않음). -- `/tts status`는 최신 시도에 대한 fallback 가시성을 포함합니다: - - 성공 fallback: `Fallback: -> ` 및 `Attempts: ...` - - 실패: `Error: ...` 및 `Attempts: ...` - - 상세 진단: `Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 및 ElevenLabs API 실패는 이제 파싱된 provider 오류 세부 정보와 요청 id(제공된 경우)를 포함하며, 이는 TTS 오류/로그에 표시됩니다. +- `/tts status`에는 최신 시도에 대한 대체 가시성이 포함됩니다. + - 성공적인 대체: `Fallback: -> ` + `Attempts: ...` + - 실패: `Error: ...` + `Attempts: ...` + - 자세한 진단: `Attempt details: provider:outcome(reasonCode) latency` +- OpenAI 및 ElevenLabs API 실패는 이제 파싱된 제공자 오류 상세 정보와 요청 ID(제공자가 반환한 경우)를 포함하며, 이는 TTS 오류/로그에 표시됩니다. ## 에이전트 도구 -`tts` 도구는 텍스트를 speech로 변환하고 -답장 전달용 오디오 첨부 파일을 반환합니다. 채널이 Feishu, Matrix, Telegram, 또는 WhatsApp인 경우 +`tts` 도구는 텍스트를 음성으로 변환하고 +답장 전달을 위한 오디오 첨부 파일을 반환합니다. 채널이 Feishu, Matrix, Telegram 또는 WhatsApp인 경우, 오디오는 파일 첨부가 아니라 음성 메시지로 전달됩니다. ## Gateway RPC