diff --git a/docs/ko/automation/tasks.md b/docs/ko/automation/tasks.md index e6c7d8cea..7c4191200 100644 --- a/docs/ko/automation/tasks.md +++ b/docs/ko/automation/tasks.md @@ -1,43 +1,43 @@ --- read_when: - - 진행 중이거나 최근 완료된 백그라운드 작업 확인하기 + - 진행 중이거나 최근 완료된 백그라운드 작업 살펴보기 - 분리된 에이전트 실행의 전달 실패 디버깅 - 백그라운드 실행이 세션, Cron, Heartbeat와 어떻게 관련되는지 이해하기 sidebarTitle: Background tasks -summary: ACP 실행, 하위 에이전트, 격리된 Cron 작업, CLI 작업을 위한 백그라운드 작업 추적 +summary: ACP 실행, 하위 에이전트, 격리된 Cron 작업 및 CLI 작업을 위한 백그라운드 작업 추적 title: 백그라운드 작업 x-i18n: - generated_at: "2026-04-30T06:16:38Z" + generated_at: "2026-04-30T16:27:52Z" model: gpt-5.5 provider: openai - source_hash: 4bbf74f3aeea532738b56b83cd2e1a0a3734bfd453da6636b8be985a28ccc027 + source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34 source_path: automation/tasks.md workflow: 16 --- -예약을 찾고 있나요? 올바른 메커니즘을 선택하려면 [자동화와 태스크](/ko/automation)를 참조하세요. 이 페이지는 스케줄러가 아니라 백그라운드 작업의 활동 원장입니다. +예약 기능을 찾고 있나요? 올바른 메커니즘을 선택하려면 [자동화 및 작업](/ko/automation)을 참고하세요. 이 페이지는 스케줄러가 아니라 백그라운드 작업의 활동 원장입니다. -백그라운드 태스크는 **기본 대화 세션 외부에서** 실행되는 작업을 추적합니다. 여기에는 ACP 실행, 서브에이전트 생성, 격리된 cron 작업 실행, CLI에서 시작한 작업이 포함됩니다. +백그라운드 작업은 **기본 대화 세션 밖에서** 실행되는 작업을 추적합니다. 여기에는 ACP 실행, 서브에이전트 생성, 격리된 Cron 작업 실행, CLI에서 시작된 작업이 포함됩니다. -태스크는 세션, cron 작업 또는 Heartbeat를 대체하지 **않습니다**. 태스크는 분리된 작업에서 무엇이, 언제 발생했으며 성공했는지를 기록하는 **활동 원장**입니다. +작업은 세션, Cron 작업 또는 Heartbeat를 대체하지 **않습니다**. 작업은 분리된 작업에서 무슨 일이 있었는지, 언제 발생했는지, 성공했는지를 기록하는 **활동 원장**입니다. -모든 에이전트 실행이 태스크를 생성하는 것은 아닙니다. Heartbeat 턴과 일반 대화형 채팅은 생성하지 않습니다. 모든 cron 실행, ACP 생성, 서브에이전트 생성, CLI 에이전트 명령은 생성합니다. +모든 에이전트 실행이 작업을 생성하는 것은 아닙니다. Heartbeat 턴과 일반 대화형 채팅은 작업을 생성하지 않습니다. 모든 Cron 실행, ACP 생성, 서브에이전트 생성, CLI 에이전트 명령은 작업을 생성합니다. ## 요약 -- 태스크는 스케줄러가 아니라 **기록**입니다. cron과 Heartbeat는 작업이 _언제_ 실행될지 결정하고, 태스크는 _무슨 일이 있었는지_ 추적합니다. -- ACP, 서브에이전트, 모든 cron 작업, CLI 작업은 태스크를 생성합니다. Heartbeat 턴은 생성하지 않습니다. -- 각 태스크는 `queued → running → terminal`(succeeded, failed, timed_out, cancelled 또는 lost)을 거칩니다. -- Cron 태스크는 cron 런타임이 여전히 작업을 소유하는 동안 활성 상태로 유지됩니다. 인메모리 런타임 상태가 사라진 경우, 태스크 유지 관리는 태스크를 lost로 표시하기 전에 먼저 지속성 있는 cron 실행 기록을 확인합니다. -- 완료는 푸시 기반입니다. 분리된 작업은 완료 시 직접 알리거나 요청자 세션/Heartbeat를 깨울 수 있으므로, 상태 폴링 루프는 일반적으로 적절한 형태가 아닙니다. -- 격리된 cron 실행과 서브에이전트 완료는 최종 정리 장부 작업 전에 자식 세션에 대해 추적 중인 브라우저 탭/프로세스를 최선 노력으로 정리합니다. -- 격리된 cron 전달은 하위 서브에이전트 작업이 아직 정리 중일 때 오래된 중간 부모 응답을 억제하며, 전달 전에 최종 하위 출력이 도착하면 이를 우선합니다. -- 완료 알림은 채널로 직접 전달되거나 다음 Heartbeat를 위해 큐에 추가됩니다. -- `openclaw tasks list`는 모든 태스크를 표시합니다. `openclaw tasks audit`는 문제를 드러냅니다. +- 작업은 스케줄러가 아니라 **기록**입니다. Cron과 Heartbeat는 작업이 _언제_ 실행될지 결정하고, 작업은 _무슨 일이 있었는지_ 추적합니다. +- ACP, 서브에이전트, 모든 Cron 작업, CLI 작업은 작업을 생성합니다. Heartbeat 턴은 생성하지 않습니다. +- 각 작업은 `queued → running → terminal` 상태를 거칩니다(succeeded, failed, timed_out, cancelled 또는 lost). +- Cron 작업은 Cron 런타임이 아직 작업을 소유하는 동안 활성 상태로 유지됩니다. 메모리 내 런타임 상태가 사라지면, 작업 유지 관리는 작업을 lost로 표시하기 전에 먼저 내구성 있는 Cron 실행 기록을 확인합니다. +- 완료는 푸시 기반입니다. 분리된 작업은 완료 시 직접 알리거나 요청자 세션/Heartbeat를 깨울 수 있으므로, 상태 폴링 루프는 대개 적절한 형태가 아닙니다. +- 격리된 Cron 실행과 서브에이전트 완료는 최종 정리 부기 전에 하위 세션의 추적된 브라우저 탭/프로세스를 최선의 방식으로 정리합니다. +- 격리된 Cron 전달은 하위 서브에이전트 작업이 아직 비워지는 중일 때 오래된 중간 부모 응답을 억제하고, 전달 전에 최종 하위 출력이 도착하면 그 출력을 우선합니다. +- 완료 알림은 채널에 직접 전달되거나 다음 Heartbeat를 위해 대기열에 추가됩니다. +- `openclaw tasks list`는 모든 작업을 표시합니다. `openclaw tasks audit`는 문제를 드러냅니다. - 터미널 기록은 7일 동안 보관된 뒤 자동으로 정리됩니다. ## 빠른 시작 @@ -45,10 +45,10 @@ x-i18n: ```bash - # List all tasks (newest first) + # 모든 작업 나열(최신순) openclaw tasks list - # Filter by runtime or status + # 런타임 또는 상태로 필터링 openclaw tasks list --runtime acp openclaw tasks list --status running ``` @@ -56,26 +56,26 @@ x-i18n: ```bash - # Show details for a specific task (by ID, run ID, or session key) + # 특정 작업의 세부 정보 표시(ID, 실행 ID 또는 세션 키 기준) openclaw tasks show ``` ```bash - # Cancel a running task (kills the child session) + # 실행 중인 작업 취소(하위 세션 종료) openclaw tasks cancel - # Change notification policy for a task + # 작업의 알림 정책 변경 openclaw tasks notify state_changes ``` ```bash - # Run a health audit + # 상태 감사 실행 openclaw tasks audit - # Preview or apply maintenance + # 유지 관리 미리보기 또는 적용 openclaw tasks maintenance openclaw tasks maintenance --apply ``` @@ -83,7 +83,7 @@ x-i18n: ```bash - # Inspect TaskFlow state + # TaskFlow 상태 검사 openclaw tasks flow list openclaw tasks flow show openclaw tasks flow cancel @@ -91,35 +91,35 @@ x-i18n: -## 태스크를 생성하는 것 +## 작업을 생성하는 항목 -| 소스 | 런타임 유형 | 태스크 기록이 생성되는 시점 | 기본 알림 정책 | -| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| ACP 백그라운드 실행 | `acp` | 자식 ACP 세션 생성 | `done_only` | -| 서브에이전트 오케스트레이션 | `subagent` | `sessions_spawn`을 통해 서브에이전트 생성 | `done_only` | -| Cron 작업(모든 유형) | `cron` | 모든 cron 실행(기본 세션 및 격리) | `silent` | -| CLI 작업 | `cli` | Gateway를 통해 실행되는 `openclaw agent` 명령 | `silent` | -| 에이전트 미디어 작업 | `cli` | 세션 기반 `video_generate` 실행 | `silent` | +| 소스 | 런타임 유형 | 작업 기록이 생성되는 시점 | 기본 알림 정책 | +| ---------------------- | ------------ | -------------------------------------------------------- | -------------- | +| ACP 백그라운드 실행 | `acp` | 하위 ACP 세션 생성 | `done_only` | +| 서브에이전트 오케스트레이션 | `subagent` | `sessions_spawn`을 통해 서브에이전트 생성 | `done_only` | +| Cron 작업(모든 유형) | `cron` | 모든 Cron 실행(기본 세션 및 격리) | `silent` | +| CLI 작업 | `cli` | Gateway를 통해 실행되는 `openclaw agent` 명령 | `silent` | +| 에이전트 미디어 작업 | `cli` | 세션 기반 `video_generate` 실행 | `silent` | - - 기본 세션 cron 태스크는 기본적으로 `silent` 알림 정책을 사용합니다. 추적을 위한 기록은 만들지만 알림은 생성하지 않습니다. 격리된 cron 태스크도 기본값은 `silent`이지만 자체 세션에서 실행되므로 더 잘 드러납니다. + + 기본 세션 Cron 작업은 기본적으로 `silent` 알림 정책을 사용합니다. 추적용 기록은 생성하지만 알림은 생성하지 않습니다. 격리된 Cron 작업도 기본값은 `silent`이지만, 자체 세션에서 실행되므로 더 잘 드러납니다. - 세션 기반 `video_generate` 실행도 `silent` 알림 정책을 사용합니다. 여전히 태스크 기록은 생성하지만, 완료는 내부 깨우기로 원래 에이전트 세션에 다시 전달되어 에이전트가 후속 메시지를 작성하고 완성된 비디오를 직접 첨부할 수 있습니다. `tools.media.asyncCompletion.directSend`를 선택하면 비동기 `music_generate` 및 `video_generate` 완료는 요청자 세션 깨우기 경로로 폴백하기 전에 먼저 직접 채널 전달을 시도합니다. + 세션 기반 `video_generate` 실행도 `silent` 알림 정책을 사용합니다. 이 실행도 작업 기록을 생성하지만, 완료는 내부 깨우기 형태로 원래 에이전트 세션에 전달되어 에이전트가 후속 메시지를 작성하고 완성된 비디오를 직접 첨부할 수 있습니다. `tools.media.asyncCompletion.directSend`를 선택하면 비동기 `music_generate` 및 `video_generate` 완료는 요청자 세션 깨우기 경로로 폴백하기 전에 먼저 직접 채널 전달을 시도합니다. - 세션 기반 `video_generate` 태스크가 아직 활성 상태인 동안 이 도구는 보호 장치로도 작동합니다. 같은 세션에서 반복된 `video_generate` 호출은 두 번째 동시 생성을 시작하는 대신 활성 태스크 상태를 반환합니다. 에이전트 쪽에서 명시적인 진행률/상태 조회를 원할 때는 `action: "status"`를 사용하세요. + 세션 기반 `video_generate` 작업이 아직 활성 상태인 동안 이 도구는 보호 장치 역할도 합니다. 같은 세션에서 `video_generate` 호출이 반복되면 두 번째 동시 생성을 시작하는 대신 활성 작업 상태를 반환합니다. 에이전트 쪽에서 명시적인 진행률/상태 조회가 필요할 때는 `action: "status"`를 사용하세요. - - - Heartbeat 턴 — 기본 세션입니다. [Heartbeat](/ko/gateway/heartbeat)를 참조하세요. + + - Heartbeat 턴 - 기본 세션. [Heartbeat](/ko/gateway/heartbeat)를 참고하세요. - 일반 대화형 채팅 턴 - 직접 `/command` 응답 -## 태스크 수명 주기 +## 작업 수명 주기 ```mermaid stateDiagram-v2 @@ -133,52 +133,52 @@ stateDiagram-v2 running --> lost : session gone > 5 min ``` -| 상태 | 의미 | +| 상태 | 의미 | | ----------- | -------------------------------------------------------------------------- | -| `queued` | 생성되었으며 에이전트 시작을 기다리는 중 | -| `running` | 에이전트 턴이 활발히 실행 중 | -| `succeeded` | 성공적으로 완료됨 | -| `failed` | 오류와 함께 완료됨 | -| `timed_out` | 구성된 제한 시간을 초과함 | -| `cancelled` | 운영자가 `openclaw tasks cancel`을 통해 중지함 | -| `lost` | 5분의 유예 기간 후 런타임이 권위 있는 백업 상태를 잃음 | +| `queued` | 생성되었으며, 에이전트 시작을 기다리는 중 | +| `running` | 에이전트 턴이 활발히 실행 중 | +| `succeeded` | 성공적으로 완료됨 | +| `failed` | 오류와 함께 완료됨 | +| `timed_out` | 구성된 제한 시간을 초과함 | +| `cancelled` | 운영자가 `openclaw tasks cancel`로 중지함 | +| `lost` | 5분의 유예 기간 후 런타임이 권위 있는 백업 상태를 잃음 | -전환은 자동으로 발생합니다. 연결된 에이전트 실행이 끝나면 태스크 상태가 그에 맞게 업데이트됩니다. +전환은 자동으로 발생합니다. 연결된 에이전트 실행이 끝나면 작업 상태가 그에 맞게 업데이트됩니다. -에이전트 실행 완료는 활성 태스크 기록에 대한 권위 있는 기준입니다. 성공한 분리 실행은 `succeeded`로 최종화되고, 일반 실행 오류는 `failed`로 최종화되며, 제한 시간 또는 중단 결과는 `timed_out`으로 최종화됩니다. 운영자가 이미 태스크를 취소했거나 런타임이 이미 `failed`, `timed_out`, `lost` 같은 더 강한 터미널 상태를 기록한 경우, 이후의 성공 신호는 해당 터미널 상태를 낮추지 않습니다. +에이전트 실행 완료는 활성 작업 기록에 대한 권위 있는 기준입니다. 성공한 분리 실행은 `succeeded`로 최종화되고, 일반 실행 오류는 `failed`로 최종화되며, 제한 시간 또는 중단 결과는 `timed_out`으로 최종화됩니다. 운영자가 이미 작업을 취소했거나 런타임이 이미 `failed`, `timed_out`, `lost` 같은 더 강한 터미널 상태를 기록했다면, 나중에 성공 신호가 와도 해당 터미널 상태를 낮추지 않습니다. `lost`는 런타임을 인식합니다. -- ACP 태스크: 백업 ACP 자식 세션 메타데이터가 사라졌습니다. -- 서브에이전트 태스크: 대상 에이전트 저장소에서 백업 자식 세션이 사라졌습니다. -- Cron 태스크: cron 런타임이 더 이상 작업을 활성 상태로 추적하지 않으며 지속성 있는 cron 실행 기록에도 해당 실행의 터미널 결과가 표시되지 않습니다. 오프라인 CLI 감사는 자체의 빈 인프로세스 cron 런타임 상태를 권위로 취급하지 않습니다. -- CLI 태스크: 격리된 자식 세션 태스크는 자식 세션을 사용합니다. 채팅 기반 CLI 태스크는 대신 라이브 실행 컨텍스트를 사용하므로, 남아 있는 채널/그룹/직접 세션 행이 이를 계속 활성 상태로 유지하지 않습니다. Gateway 기반 `openclaw agent` 실행도 실행 결과에서 최종화되므로, 완료된 실행은 스위퍼가 `lost`로 표시할 때까지 활성 상태로 남아 있지 않습니다. +- ACP 작업: 백업 ACP 하위 세션 메타데이터가 사라졌습니다. +- 서브에이전트 작업: 백업 하위 세션이 대상 에이전트 저장소에서 사라졌습니다. +- Cron 작업: Cron 런타임이 더 이상 해당 작업을 활성 상태로 추적하지 않고, 내구성 있는 Cron 실행 기록에도 해당 실행의 터미널 결과가 표시되지 않습니다. 오프라인 CLI 감사는 자체의 빈 프로세스 내 Cron 런타임 상태를 권위로 취급하지 않습니다. +- CLI 작업: 격리된 하위 세션 작업은 하위 세션을 사용합니다. 채팅 기반 CLI 작업은 대신 라이브 실행 컨텍스트를 사용하므로, 남아 있는 채널/그룹/직접 세션 행이 이를 활성 상태로 유지하지 않습니다. Gateway 기반 `openclaw agent` 실행도 실행 결과에서 최종화되므로, 완료된 실행이 스위퍼가 `lost`로 표시할 때까지 활성 상태로 남아 있지 않습니다. ## 전달 및 알림 -태스크가 터미널 상태에 도달하면 OpenClaw가 사용자에게 알립니다. 전달 경로는 두 가지입니다. +작업이 터미널 상태에 도달하면 OpenClaw가 알립니다. 전달 경로는 두 가지입니다. -**직접 전달** — 태스크에 채널 대상(`requesterOrigin`)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 전달됩니다. 서브에이전트 완료의 경우, OpenClaw는 사용 가능한 경우 바인딩된 스레드/토픽 라우팅도 보존하며, 직접 전달을 포기하기 전에 요청자 세션에 저장된 경로(`lastChannel` / `lastTo` / `lastAccountId`)에서 누락된 `to` / 계정을 채울 수 있습니다. +**직접 전달** - 작업에 채널 대상(`requesterOrigin`)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 전달됩니다. 서브에이전트 완료의 경우, OpenClaw는 가능한 경우 바인딩된 스레드/토픽 라우팅도 보존하며, 직접 전달을 포기하기 전에 요청자 세션에 저장된 경로(`lastChannel` / `lastTo` / `lastAccountId`)에서 누락된 `to` / 계정을 채울 수 있습니다. -**세션 큐 전달** — 직접 전달이 실패하거나 origin이 설정되지 않은 경우, 업데이트는 요청자의 세션에 시스템 이벤트로 큐에 추가되고 다음 Heartbeat에서 표시됩니다. +**세션 대기열 전달** - 직접 전달이 실패하거나 origin이 설정되지 않은 경우, 업데이트는 요청자 세션의 시스템 이벤트로 대기열에 추가되고 다음 Heartbeat에서 표시됩니다. -태스크 완료는 즉시 Heartbeat 깨우기를 트리거하므로 결과를 빠르게 볼 수 있습니다. 다음 예약된 Heartbeat 틱까지 기다릴 필요가 없습니다. +작업 완료는 즉시 Heartbeat 깨우기를 트리거하므로 결과를 빠르게 볼 수 있습니다. 다음 예약된 Heartbeat 틱까지 기다릴 필요가 없습니다. -즉, 일반적인 워크플로는 푸시 기반입니다. 분리된 작업을 한 번 시작한 뒤, 런타임이 완료 시 깨우거나 알리도록 두면 됩니다. 디버깅, 개입 또는 명시적인 감사가 필요할 때만 태스크 상태를 폴링하세요. +즉, 일반적인 워크플로는 푸시 기반입니다. 분리된 작업을 한 번 시작한 뒤, 완료 시 런타임이 깨우거나 알리도록 두면 됩니다. 작업 상태는 디버깅, 개입 또는 명시적 감사가 필요할 때만 폴링하세요. ### 알림 정책 -각 태스크에 대해 얼마나 많은 알림을 받을지 제어합니다. +각 작업에 대해 얼마나 많은 알림을 받을지 제어합니다. -| 정책 | 전달되는 내용 | +| 정책 | 전달되는 내용 | | --------------------- | ----------------------------------------------------------------------- | -| `done_only` (기본값) | 터미널 상태(성공, 실패 등)만 — **이것이 기본값입니다** | -| `state_changes` | 모든 상태 전환 및 진행률 업데이트 | +| `done_only` (기본값) | 터미널 상태만(succeeded, failed 등) - **이것이 기본값입니다** | +| `state_changes` | 모든 상태 전환 및 진행률 업데이트 | | `silent` | 아무것도 없음 | -태스크가 실행 중일 때 정책을 변경합니다. +작업이 실행 중일 때 정책을 변경합니다. ```bash openclaw tasks notify state_changes @@ -192,7 +192,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - 출력 열: 태스크 ID, 종류, 상태, 전달, 실행 ID, 자식 세션, 요약. + 출력 열: 작업 ID, 종류, 상태, 전달, 실행 ID, 하위 세션, 요약. @@ -200,7 +200,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - 조회 토큰은 태스크 ID, 실행 ID 또는 세션 키를 받습니다. 타이밍, 전달 상태, 오류, 터미널 요약을 포함한 전체 기록을 표시합니다. + 조회 토큰은 작업 ID, 실행 ID 또는 세션 키를 허용합니다. 타이밍, 전달 상태, 오류, 터미널 요약을 포함한 전체 기록을 표시합니다. @@ -208,7 +208,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - ACP 및 서브에이전트 태스크의 경우, 자식 세션을 종료합니다. CLI로 추적되는 태스크의 경우 취소가 태스크 레지스트리에 기록됩니다(별도의 자식 런타임 핸들은 없습니다). 상태는 `cancelled`로 전환되며, 해당되는 경우 전달 알림이 전송됩니다. + ACP 및 서브에이전트 작업의 경우, 이는 하위 세션을 종료합니다. CLI로 추적되는 작업의 경우, 취소는 작업 레지스트리에 기록됩니다(별도의 하위 런타임 핸들은 없습니다). 상태는 `cancelled`로 전환되고, 해당되는 경우 전달 알림이 전송됩니다. @@ -221,38 +221,39 @@ openclaw tasks notify state_changes openclaw tasks audit [--json] ``` - 운영상 문제를 드러냅니다. 문제가 감지되면 발견 사항은 `openclaw status`에도 표시됩니다. + 운영 문제를 드러냅니다. 문제가 감지되면 발견 사항은 `openclaw status`에도 표시됩니다. - | 발견 항목 | 심각도 | 트리거 | + | 발견 항목 | 심각도 | 트리거 | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | - | `stale_queued` | warn | 10분 넘게 대기열에 있음 | - | `stale_running` | error | 30분 넘게 실행 중 | + | `stale_queued` | warn | 10분 넘게 대기열에 있음 | + | `stale_running` | error | 30분 넘게 실행 중 | | `lost` | warn/error | 런타임 기반 작업 소유권이 사라짐; 보존된 유실 작업은 `cleanupAfter`까지 경고로 유지된 뒤 오류가 됨 | | `delivery_failed` | warn | 전달에 실패했고 알림 정책이 `silent`가 아님 | | `missing_cleanup` | warn | 정리 타임스탬프가 없는 종료 작업 | | `inconsistent_timestamps` | warn | 타임라인 위반(예: 시작 전에 종료됨) | - + ```bash openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` - 작업과 Task Flow 상태의 조정, 정리 스탬프 지정, 가지치기를 미리 보거나 적용할 때 사용합니다. + 작업 및 Task Flow 상태의 조정, 정리 스탬프 지정, 가지치기를 미리 보거나 적용할 때 사용합니다. 조정은 런타임을 인식합니다. - - ACP/하위 에이전트 작업은 기반 자식 세션을 확인합니다. - - Cron 작업은 cron 런타임이 여전히 작업을 소유하는지 확인한 다음, `lost`로 대체하기 전에 유지된 cron 실행 로그/작업 상태에서 종료 상태를 복구합니다. 메모리 내 cron 활성 작업 집합에 대해서는 Gateway 프로세스만 권위 있는 출처입니다. 오프라인 CLI 감사는 영구 기록을 사용하지만 해당 로컬 Set이 비어 있다는 이유만으로 cron 작업을 유실로 표시하지 않습니다. + - ACP/서브에이전트 작업은 기반 하위 세션을 확인합니다. + - 하위 세션에 재시작 복구 툼스톤이 있는 서브에이전트 작업은 복구 가능한 기반 세션으로 처리되지 않고 유실된 것으로 표시됩니다. + - Cron 작업은 cron 런타임이 여전히 작업을 소유하는지 확인한 다음, `lost`로 폴백하기 전에 지속된 cron 실행 로그/작업 상태에서 종료 상태를 복구합니다. 메모리 내 cron 활성 작업 집합에 대해서는 Gateway 프로세스만 권한을 가집니다. 오프라인 CLI 감사는 지속성 있는 기록을 사용하지만, 로컬 Set이 비어 있다는 이유만으로 cron 작업을 유실로 표시하지 않습니다. - 채팅 기반 CLI 작업은 채팅 세션 행만이 아니라 소유 중인 라이브 실행 컨텍스트를 확인합니다. 완료 정리도 런타임을 인식합니다. - - 하위 에이전트 완료는 알림 정리가 계속되기 전에 자식 세션에 대해 추적된 브라우저 탭/프로세스를 최선의 방식으로 닫습니다. - - 격리된 cron 완료는 실행이 완전히 종료되기 전에 cron 세션에 대해 추적된 브라우저 탭/프로세스를 최선의 방식으로 닫습니다. - - 격리된 cron 전달은 필요할 때 하위 후속 하위 에이전트 작업이 끝날 때까지 기다리며, 이를 알리는 대신 오래된 부모 확인 텍스트를 억제합니다. - - 하위 에이전트 완료 전달은 가장 최근에 표시된 어시스턴트 텍스트를 우선 사용합니다. 비어 있으면 정리된 최신 도구/toolResult 텍스트로 대체하며, 시간 초과만 발생한 도구 호출 실행은 짧은 부분 진행 요약으로 축약될 수 있습니다. 종료된 실패 실행은 캡처된 응답 텍스트를 다시 재생하지 않고 실패 상태를 알립니다. + - 서브에이전트 완료는 알림 정리가 계속되기 전에 하위 세션에 대해 추적 중인 브라우저 탭/프로세스를 최선의 노력으로 닫습니다. + - 격리된 cron 완료는 실행이 완전히 해제되기 전에 cron 세션에 대해 추적 중인 브라우저 탭/프로세스를 최선의 노력으로 닫습니다. + - 격리된 cron 전달은 필요할 때 하위 서브에이전트 후속 작업을 기다리고, 오래된 상위 확인 텍스트를 알리는 대신 억제합니다. + - 서브에이전트 완료 전달은 가장 최근의 표시 가능한 어시스턴트 텍스트를 우선합니다. 비어 있으면 정리된 최신 tool/toolResult 텍스트로 폴백하며, 시간 초과만 있는 도구 호출 실행은 짧은 부분 진행 요약으로 축약될 수 있습니다. 종료된 실패 실행은 캡처된 응답 텍스트를 다시 재생하지 않고 실패 상태를 알립니다. - 정리 실패는 실제 작업 결과를 가리지 않습니다. @@ -263,22 +264,22 @@ openclaw tasks notify state_changes openclaw tasks flow cancel ``` - 개별 백그라운드 작업 레코드가 아니라 조율하는 Task Flow 자체가 관심 대상일 때 사용합니다. + 개별 백그라운드 작업 레코드가 아니라 조율 중인 Task Flow 자체가 관심 대상일 때 사용합니다. ## 채팅 작업 보드(`/tasks`) -모든 채팅 세션에서 `/tasks`를 사용해 해당 세션에 연결된 백그라운드 작업을 볼 수 있습니다. 보드는 활성 작업과 최근 완료된 작업을 런타임, 상태, 타이밍, 진행률 또는 오류 세부 정보와 함께 표시합니다. +모든 채팅 세션에서 `/tasks`를 사용하여 해당 세션에 연결된 백그라운드 작업을 확인할 수 있습니다. 보드는 활성 작업과 최근 완료된 작업을 런타임, 상태, 타이밍, 진행 상황 또는 오류 세부 정보와 함께 표시합니다. -현재 세션에 표시 가능한 연결 작업이 없으면 `/tasks`는 에이전트 로컬 작업 수로 대체되어 다른 세션 세부 정보를 노출하지 않고도 개요를 제공합니다. +현재 세션에 표시 가능한 연결 작업이 없으면 `/tasks`는 에이전트 로컬 작업 개수로 폴백하므로 다른 세션의 세부 정보를 노출하지 않고도 개요를 볼 수 있습니다. 전체 운영자 원장은 CLI를 사용하세요: `openclaw tasks list`. -## 상태 통합(작업 압력) +## 상태 통합(작업 부하) -`openclaw status`에는 한눈에 보는 작업 요약이 포함됩니다. +`openclaw status`에는 한눈에 볼 수 있는 작업 요약이 포함됩니다. ``` Tasks: 3 queued · 2 running · 1 issues @@ -288,36 +289,36 @@ Tasks: 3 queued · 2 running · 1 issues - **활성** — `queued` + `running` 개수 - **실패** — `failed` + `timed_out` + `lost` 개수 -- **byRuntime** — `acp`, `subagent`, `cron`, `cli`별 분석 +- **런타임별** — `acp`, `subagent`, `cron`, `cli`별 분석 -`/status`와 `session_status` 도구는 모두 정리를 인식하는 작업 스냅샷을 사용합니다. 활성 작업을 우선 표시하고, 오래된 완료 행은 숨기며, 최근 실패는 활성 작업이 남아 있지 않을 때만 표시합니다. 이렇게 하면 상태 카드가 지금 중요한 것에 집중됩니다. +`/status`와 `session_status` 도구는 모두 정리 인식 작업 스냅샷을 사용합니다. 활성 작업을 우선하고, 오래된 완료 행은 숨기며, 최근 실패는 활성 작업이 남아 있지 않을 때만 표시됩니다. 이를 통해 상태 카드가 지금 중요한 항목에 집중하도록 유지합니다. -## 저장소 및 유지 관리 +## 저장소 및 유지관리 ### 작업이 저장되는 위치 -작업 레코드는 다음 위치의 SQLite에 유지됩니다. +작업 레코드는 다음 위치의 SQLite에 지속됩니다. ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -레지스트리는 Gateway 시작 시 메모리로 로드되며, 재시작 후에도 내구성을 유지하도록 쓰기를 SQLite에 동기화합니다. -Gateway는 SQLite의 기본 자동 체크포인트 임계값과 주기적 및 종료 시 `TRUNCATE` 체크포인트를 사용해 SQLite 선행 기입 로그의 크기를 제한합니다. +레지스트리는 Gateway 시작 시 메모리로 로드되고 재시작 간 내구성을 위해 쓰기를 SQLite에 동기화합니다. +Gateway는 SQLite의 기본 자동 체크포인트 임계값과 주기적 및 종료 시 `TRUNCATE` 체크포인트를 사용하여 SQLite write-ahead log를 제한된 크기로 유지합니다. -### 자동 유지 관리 +### 자동 유지관리 스위퍼는 **60초**마다 실행되며 네 가지를 처리합니다. - 활성 작업에 여전히 권위 있는 런타임 기반 항목이 있는지 확인합니다. ACP/하위 에이전트 작업은 자식 세션 상태를 사용하고, cron 작업은 활성 작업 소유권을 사용하며, 채팅 기반 CLI 작업은 소유 중인 실행 컨텍스트를 사용합니다. 해당 기반 상태가 5분 넘게 사라지면 작업이 `lost`로 표시됩니다. + 활성 작업에 여전히 권한 있는 런타임 기반이 있는지 확인합니다. ACP/서브에이전트 작업은 하위 세션 상태를 사용하고, cron 작업은 활성 작업 소유권을 사용하며, 채팅 기반 CLI 작업은 소유 중인 실행 컨텍스트를 사용합니다. 해당 기반 상태가 5분 넘게 사라져 있으면 작업이 `lost`로 표시됩니다. - 종료되었거나 고아가 된 부모 소유 일회성 ACP 세션을 닫고, 활성 대화 바인딩이 남아 있지 않은 경우에만 오래된 종료 또는 고아 영구 ACP 세션을 닫습니다. + 종료되었거나 고아가 된 상위 소유 일회성 ACP 세션을 닫고, 활성 대화 바인딩이 남아 있지 않은 경우에만 오래된 종료 또는 고아 지속 ACP 세션을 닫습니다. - 종료 작업에 `cleanupAfter` 타임스탬프를 설정합니다(endedAt + 7일). 보존 기간 동안 유실 작업은 감사에서 계속 경고로 표시됩니다. `cleanupAfter`가 만료되거나 정리 메타데이터가 누락되면 오류가 됩니다. + 종료 작업에 `cleanupAfter` 타임스탬프를 설정합니다(endedAt + 7일). 보존 기간 동안 유실 작업은 여전히 감사에서 경고로 표시됩니다. `cleanupAfter`가 만료되었거나 정리 메타데이터가 없으면 오류가 됩니다. `cleanupAfter` 날짜가 지난 레코드를 삭제합니다. @@ -325,35 +326,35 @@ Gateway는 SQLite의 기본 자동 체크포인트 임계값과 주기적 및 -**보존:** 종료 작업 레코드는 **7일** 동안 보관된 다음 자동으로 가지치기됩니다. 구성이 필요하지 않습니다. +**보존:** 종료 작업 레코드는 **7일** 동안 보관된 뒤 자동으로 가지치기됩니다. 설정은 필요하지 않습니다. ## 작업과 다른 시스템의 관계 - [Task Flow](/ko/automation/taskflow)는 백그라운드 작업 위의 흐름 조율 계층입니다. 단일 흐름은 수명 동안 관리형 또는 미러링된 동기화 모드를 사용해 여러 작업을 조율할 수 있습니다. 개별 작업 레코드를 검사하려면 `openclaw tasks`를 사용하고, 조율하는 흐름을 검사하려면 `openclaw tasks flow`를 사용합니다. + [Task Flow](/ko/automation/taskflow)는 백그라운드 작업 위의 흐름 조율 계층입니다. 단일 흐름은 수명 동안 관리형 또는 미러링 동기화 모드를 사용하여 여러 작업을 조정할 수 있습니다. 개별 작업 레코드를 검사하려면 `openclaw tasks`를 사용하고, 조율 중인 흐름을 검사하려면 `openclaw tasks flow`를 사용합니다. 자세한 내용은 [Task Flow](/ko/automation/taskflow)를 참조하세요. - cron 작업 **정의**는 `~/.openclaw/cron/jobs.json`에 있으며, 런타임 실행 상태는 그 옆의 `~/.openclaw/cron/jobs-state.json`에 있습니다. **모든** cron 실행은 작업 레코드를 생성합니다. 메인 세션과 격리된 실행 모두에 해당합니다. 메인 세션 cron 작업은 알림을 생성하지 않고 추적하도록 기본 알림 정책이 `silent`입니다. + cron 작업 **정의**는 `~/.openclaw/cron/jobs.json`에 있으며, 런타임 실행 상태는 그 옆의 `~/.openclaw/cron/jobs-state.json`에 있습니다. **모든** cron 실행은 작업 레코드를 생성합니다. 메인 세션과 격리된 실행 모두 해당됩니다. 메인 세션 cron 작업은 알림을 생성하지 않고 추적만 하도록 기본 알림 정책이 `silent`입니다. [Cron 작업](/ko/automation/cron-jobs)을 참조하세요. - Heartbeat 실행은 메인 세션 턴입니다. 작업 레코드를 생성하지 않습니다. 작업이 완료되면 결과를 빠르게 볼 수 있도록 Heartbeat 깨우기를 트리거할 수 있습니다. + Heartbeat 실행은 메인 세션 턴이며 작업 레코드를 생성하지 않습니다. 작업이 완료되면 Heartbeat 깨우기를 트리거하여 결과를 즉시 확인할 수 있습니다. [Heartbeat](/ko/gateway/heartbeat)를 참조하세요. - 작업은 `childSessionKey`(작업이 실행되는 위치)와 `requesterSessionKey`(시작한 주체)를 참조할 수 있습니다. 세션은 대화 컨텍스트이고, 작업은 그 위의 활동 추적입니다. + 작업은 `childSessionKey`(작업이 실행되는 위치)와 `requesterSessionKey`(작업을 시작한 주체)를 참조할 수 있습니다. 세션은 대화 컨텍스트이고, 작업은 그 위의 활동 추적입니다. - 작업의 `runId`는 작업을 수행하는 에이전트 실행에 연결됩니다. 에이전트 수명 주기 이벤트(시작, 종료, 오류)는 작업 상태를 자동으로 업데이트합니다. 수명 주기를 수동으로 관리할 필요가 없습니다. + 작업의 `runId`는 작업을 수행하는 에이전트 실행에 연결됩니다. 에이전트 수명 주기 이벤트(시작, 종료, 오류)는 작업 상태를 자동으로 업데이트하므로 수명 주기를 수동으로 관리할 필요가 없습니다. diff --git a/docs/ko/channels/groups.md b/docs/ko/channels/groups.md index c6640c7ef..c03492a78 100644 --- a/docs/ko/channels/groups.md +++ b/docs/ko/channels/groups.md @@ -2,13 +2,13 @@ read_when: - 그룹 채팅 동작 또는 멘션 게이팅 변경 sidebarTitle: Groups -summary: 각 환경에서의 그룹 채팅 동작 (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) +summary: 여러 표면에서의 그룹 채팅 동작(Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) title: 그룹 x-i18n: - generated_at: "2026-04-30T06:17:28Z" + generated_at: "2026-04-30T16:27:41Z" model: gpt-5.5 provider: openai - source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998 + source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e source_path: channels/groups.md workflow: 16 --- @@ -17,13 +17,13 @@ OpenClaw는 여러 표면에서 그룹 채팅을 일관되게 처리합니다: D ## 초보자 소개(2분) -OpenClaw는 사용자의 자체 메시징 계정에서 "상주"합니다. 별도의 WhatsApp 봇 사용자는 없습니다. **사용자**가 그룹에 있으면 OpenClaw는 해당 그룹을 볼 수 있고 그곳에서 응답할 수 있습니다. +OpenClaw는 사용자의 메시징 계정 안에 "존재"합니다. 별도의 WhatsApp 봇 사용자가 있는 것이 아닙니다. **사용자**가 그룹에 있으면 OpenClaw는 해당 그룹을 볼 수 있고 그곳에서 응답할 수 있습니다. 기본 동작: - 그룹은 제한됩니다(`groupPolicy: "allowlist"`). -- 명시적으로 멘션 게이팅을 비활성화하지 않는 한 응답에는 멘션이 필요합니다. -- 그룹/채널의 일반 최종 응답은 기본적으로 비공개입니다. 보이는 룸 출력에는 `message` 도구를 사용합니다. +- 명시적으로 멘션 게이팅을 비활성화하지 않는 한, 답장에는 멘션이 필요합니다. +- 그룹/채널의 일반 최종 답장은 기본적으로 비공개입니다. 방에 보이는 출력은 `message` 도구를 사용합니다. 즉, 허용 목록에 있는 발신자는 OpenClaw를 멘션하여 트리거할 수 있습니다. @@ -32,11 +32,11 @@ OpenClaw는 사용자의 자체 메시징 계정에서 "상주"합니다. 별도 - **DM 접근**은 `*.allowFrom`으로 제어됩니다. - **그룹 접근**은 `*.groupPolicy` + 허용 목록(`*.groups`, `*.groupAllowFrom`)으로 제어됩니다. -- **응답 트리거**는 멘션 게이팅(`requireMention`, `/activation`)으로 제어됩니다. +- **답장 트리거**는 멘션 게이팅(`requireMention`, `/activation`)으로 제어됩니다. -빠른 흐름(그룹 메시지에 발생하는 일): +빠른 흐름(그룹 메시지에 일어나는 일): ``` groupPolicy? disabled -> drop @@ -45,18 +45,18 @@ requireMention? yes -> mentioned? no -> store for context only otherwise -> reply ``` -## 보이는 응답 +## 보이는 답장 -그룹/채널 룸의 경우 OpenClaw는 기본적으로 `messages.groupChat.visibleReplies: "message_tool"`을 사용합니다. -즉, 에이전트는 여전히 해당 턴을 처리하고 메모리/세션 상태를 업데이트할 수 있지만, 일반 최종 답변은 자동으로 룸에 다시 게시되지 않습니다. 보이게 말하려면 에이전트가 `message(action=send)`를 사용합니다. +그룹/채널 방의 경우 OpenClaw는 기본적으로 `messages.groupChat.visibleReplies: "message_tool"`을 사용합니다. +즉 에이전트는 여전히 턴을 처리하고 메모리/세션 상태를 업데이트할 수 있지만, 일반 최종 답변은 자동으로 방에 다시 게시되지 않습니다. 보이게 말하려면 에이전트가 `message(action=send)`를 사용합니다. -직접 채팅 및 다른 모든 소스 턴에 동일한 도구 전용 보이는 응답 동작을 전역으로 적용하려면 `messages.visibleReplies: "message_tool"`을 사용하세요. `messages.groupChat.visibleReplies`는 그룹/채널 룸에 대한 더 구체적인 재정의로 유지됩니다. +직접 채팅과 기타 모든 소스 턴에는 `messages.visibleReplies: "message_tool"`을 사용해 동일한 도구 전용 보이는 답장 동작을 전역으로 적용합니다. `messages.groupChat.visibleReplies`는 그룹/채널 방에 대한 더 구체적인 재정의로 유지됩니다. -이는 대부분의 관찰 모드 턴에서 모델이 `NO_REPLY`로 답하도록 강제하던 이전 패턴을 대체합니다. 도구 전용 모드에서 보이는 작업을 하지 않는다는 것은 단순히 메시지 도구를 호출하지 않는다는 뜻입니다. +이는 대부분의 잠복 모드 턴에서 모델이 `NO_REPLY`로 답하도록 강제하던 이전 패턴을 대체합니다. 도구 전용 모드에서는 아무것도 보이게 하지 않는다는 것은 단순히 message 도구를 호출하지 않는다는 뜻입니다. -에이전트가 도구 전용 모드에서 작업하는 동안에도 입력 표시기는 계속 전송됩니다. 이러한 턴에서는 에이전트가 메시지 도구 호출 여부를 결정하기 전에 일반 어시스턴트 메시지 텍스트가 전혀 없을 수 있으므로 기본 그룹 입력 모드가 "message"에서 "instant"로 업그레이드됩니다. 명시적인 입력 모드 설정이 여전히 우선합니다. +에이전트가 도구 전용 모드로 작업하는 동안에도 입력 중 표시기는 계속 전송됩니다. 이러한 턴에서는 에이전트가 message 도구 호출 여부를 결정하기 전에 일반 어시스턴트 메시지 텍스트가 전혀 없을 수 있으므로, 기본 그룹 입력 모드는 "message"에서 "instant"로 업그레이드됩니다. 명시적인 입력 모드 설정은 여전히 우선합니다. -그룹/채널 룸에 대해 기존의 자동 최종 응답을 복원하려면: +그룹/채널 방에서 레거시 자동 최종 답장을 복원하려면: ```json5 { @@ -68,7 +68,9 @@ otherwise -> reply } ``` -모든 소스 채팅에서 보이는 출력이 메시지 도구를 거치도록 요구하려면: +Gateway는 파일이 저장된 뒤 `messages` 설정을 핫 리로드합니다. 배포 환경에서 파일 감시 또는 설정 리로드가 비활성화된 경우에만 다시 시작하세요. + +모든 소스 채팅에서 보이는 출력이 message 도구를 거치도록 요구하려면: ```json5 { @@ -78,29 +80,29 @@ otherwise -> reply } ``` -네이티브 슬래시 명령(Discord, Telegram 및 네이티브 명령 지원이 있는 기타 표면)은 `visibleReplies: "message_tool"`을 우회하고 항상 보이게 응답하므로 채널 네이티브 명령 UI가 예상하는 응답을 받습니다. 이는 검증된 네이티브 명령 턴에만 적용됩니다. 텍스트로 입력한 `/...` 명령과 일반 채팅 턴은 여전히 구성된 그룹 기본값을 따릅니다. +네이티브 슬래시 명령(Discord, Telegram, 그리고 네이티브 명령 지원이 있는 다른 표면)은 `visibleReplies: "message_tool"`을 우회하고 항상 보이게 답장하므로 채널 네이티브 명령 UI가 기대하는 응답을 받습니다. 이는 검증된 네이티브 명령 턴에만 적용됩니다. 텍스트로 입력한 `/...` 명령과 일반 채팅 턴은 여전히 구성된 그룹 기본값을 따릅니다. -## 컨텍스트 가시성과 허용 목록 +## 컨텍스트 표시 여부와 허용 목록 -그룹 안전에는 두 가지 다른 제어가 관여합니다. +그룹 안전에는 서로 다른 두 가지 제어가 관여합니다. -- **트리거 승인**: 에이전트를 트리거할 수 있는 사람(`groupPolicy`, `groups`, `groupAllowFrom`, 채널별 허용 목록). -- **컨텍스트 가시성**: 모델에 주입되는 보조 컨텍스트(응답 텍스트, 인용, 스레드 기록, 전달된 메타데이터). +- **트리거 권한 부여**: 에이전트를 트리거할 수 있는 사람(`groupPolicy`, `groups`, `groupAllowFrom`, 채널별 허용 목록). +- **컨텍스트 표시 여부**: 모델에 주입되는 보조 컨텍스트(답장 텍스트, 인용, 스레드 기록, 전달된 메타데이터). -기본적으로 OpenClaw는 일반 채팅 동작을 우선하며 컨텍스트를 대부분 수신된 그대로 유지합니다. 즉, 허용 목록은 주로 누가 작업을 트리거할 수 있는지를 결정하며, 모든 인용 또는 과거 스니펫에 대한 범용 삭제 경계는 아닙니다. +기본적으로 OpenClaw는 일반 채팅 동작을 우선시하며 컨텍스트를 대부분 수신된 그대로 유지합니다. 이는 허용 목록이 주로 누가 작업을 트리거할 수 있는지를 결정하며, 모든 인용 또는 과거 스니펫에 대한 보편적인 삭제 경계가 아니라는 뜻입니다. - - 일부 채널은 이미 특정 경로에서 보조 컨텍스트에 발신자 기반 필터링을 적용합니다(예: Slack 스레드 시딩, Matrix 응답/스레드 조회). - - 다른 채널은 여전히 인용/응답/전달 컨텍스트를 수신된 그대로 전달합니다. + - 일부 채널은 이미 특정 경로에서 보조 컨텍스트에 발신자 기반 필터링을 적용합니다(예: Slack 스레드 시딩, Matrix 답장/스레드 조회). + - 다른 채널은 여전히 인용/답장/전달 컨텍스트를 수신된 그대로 전달합니다. - + - `contextVisibility: "all"`(기본값)은 현재의 수신된 그대로의 동작을 유지합니다. - - `contextVisibility: "allowlist"`는 보조 컨텍스트를 허용 목록의 발신자로 필터링합니다. - - `contextVisibility: "allowlist_quote"`는 `allowlist`에 명시적 인용/응답 예외 하나를 더한 것입니다. + - `contextVisibility: "allowlist"`는 보조 컨텍스트를 허용 목록에 있는 발신자로 필터링합니다. + - `contextVisibility: "allowlist_quote"`는 `allowlist`에 명시적 인용/답장 예외 하나를 더한 것입니다. - 이 강화 모델이 채널 전반에 일관되게 구현될 때까지는 표면별 차이를 예상하세요. + 이 강화 모델이 채널 전반에서 일관되게 구현될 때까지는 표면별 차이를 예상하세요. @@ -109,35 +111,35 @@ otherwise -> reply 원하는 경우... -| 목표 | 설정할 항목 | +| 목표 | 설정할 값 | | -------------------------------------------- | ---------------------------------------------------------- | -| 모든 그룹을 허용하지만 @멘션에만 응답 | `groups: { "*": { requireMention: true } }` | -| 모든 그룹 응답 비활성화 | `groupPolicy: "disabled"` | +| 모든 그룹을 허용하지만 @멘션에만 답장 | `groups: { "*": { requireMention: true } }` | +| 모든 그룹 답장 비활성화 | `groupPolicy: "disabled"` | | 특정 그룹만 | `groups: { "": { ... } }` (`"*"` 키 없음) | | 그룹에서 사용자만 트리거 가능 | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | ## 세션 키 -- 그룹 세션은 `agent:::group:` 세션 키를 사용합니다(룸/채널은 `agent:::channel:` 사용). -- Telegram 포럼 주제는 그룹 ID에 `:topic:`를 추가하여 각 주제가 자체 세션을 갖도록 합니다. -- 직접 채팅은 기본 세션을 사용합니다(구성된 경우 발신자별 세션). -- 그룹 세션에서는 Heartbeat를 건너뜁니다. +- 그룹 세션은 `agent:::group:` 세션 키를 사용합니다(방/채널은 `agent:::channel:` 사용). +- Telegram 포럼 주제는 그룹 ID에 `:topic:`를 추가하므로 각 주제는 자체 세션을 가집니다. +- 직접 채팅은 기본 세션을 사용합니다(또는 구성된 경우 발신자별 세션). +- Heartbeat는 그룹 세션에서 건너뜁니다. ## 패턴: 개인 DM + 공개 그룹(단일 에이전트) -예, "개인" 트래픽이 **DM**이고 "공개" 트래픽이 **그룹**이면 잘 작동합니다. +예, "개인" 트래픽이 **DM**이고 "공개" 트래픽이 **그룹**이라면 잘 작동합니다. -이유: 단일 에이전트 모드에서 DM은 일반적으로 **기본** 세션 키(`agent:main:main`)에 도착하는 반면, 그룹은 항상 **비기본** 세션 키(`agent:main::group:`)를 사용합니다. `mode: "non-main"`으로 샌드박싱을 활성화하면 해당 그룹 세션은 구성된 샌드박스 백엔드에서 실행되고 기본 DM 세션은 호스트에 남아 있습니다. 백엔드를 선택하지 않으면 Docker가 기본 백엔드입니다. +이유: 단일 에이전트 모드에서 DM은 일반적으로 **기본** 세션 키(`agent:main:main`)에 도착하는 반면, 그룹은 항상 **비기본** 세션 키(`agent:main::group:`)를 사용합니다. `mode: "non-main"`으로 샌드박싱을 활성화하면 해당 그룹 세션은 구성된 샌드박스 백엔드에서 실행되고, 기본 DM 세션은 호스트에 남습니다. 백엔드를 선택하지 않으면 Docker가 기본 백엔드입니다. -이렇게 하면 하나의 에이전트 "두뇌"(공유 워크스페이스 + 메모리)를 유지하면서 두 가지 실행 태세를 갖게 됩니다. +이를 통해 하나의 에이전트 "두뇌"(공유 작업 공간 + 메모리)를 사용하면서 두 가지 실행 태세를 갖게 됩니다. - **DM**: 전체 도구(호스트) - **그룹**: 샌드박스 + 제한된 도구 -진정으로 분리된 워크스페이스/페르소나가 필요하다면("개인"과 "공개"가 절대 섞이면 안 되는 경우) 두 번째 에이전트 + 바인딩을 사용하세요. [다중 에이전트 라우팅](/ko/concepts/multi-agent)을 참조하세요. +정말로 분리된 작업 공간/페르소나("개인"과 "공개"가 절대 섞이면 안 됨)가 필요하다면 두 번째 에이전트 + 바인딩을 사용하세요. [다중 에이전트 라우팅](/ko/concepts/multi-agent)을 참고하세요. @@ -166,7 +168,7 @@ otherwise -> reply ``` - "호스트 접근 없음" 대신 "그룹은 폴더 X만 볼 수 있음"을 원하나요? `workspaceAccess: "none"`을 유지하고 허용 목록 경로만 샌드박스에 마운트하세요. + "호스트 접근 없음" 대신 "그룹이 폴더 X만 볼 수 있음"을 원하나요? `workspaceAccess: "none"`을 유지하고 허용 목록 경로만 샌드박스에 마운트하세요. ```json5 { @@ -193,18 +195,18 @@ otherwise -> reply 관련 항목: -- 구성 키 및 기본값: [Gateway 구성](/ko/gateway/config-agents#agentsdefaultssandbox) -- 도구가 차단된 이유 디버깅: [샌드박스 vs 도구 정책 vs 승격](/ko/gateway/sandbox-vs-tool-policy-vs-elevated) +- 구성 키와 기본값: [Gateway 구성](/ko/gateway/config-agents#agentsdefaultssandbox) +- 도구가 차단되는 이유 디버깅: [샌드박스 vs 도구 정책 vs 승격됨](/ko/gateway/sandbox-vs-tool-policy-vs-elevated) - 바인드 마운트 세부 정보: [샌드박싱](/ko/gateway/sandboxing#custom-bind-mounts) ## 표시 레이블 -- UI 레이블은 사용 가능한 경우 `displayName`을 사용하며, `:` 형식입니다. -- `#room`은 룸/채널용으로 예약되어 있습니다. 그룹 채팅은 `g-`를 사용합니다(소문자, 공백 -> `-`, `#@+._-` 유지). +- UI 레이블은 사용 가능한 경우 `displayName`을 사용하며 `:` 형식입니다. +- `#room`은 방/채널용으로 예약되어 있습니다. 그룹 채팅은 `g-`를 사용합니다(소문자, 공백 -> `-`, `#@+._-` 유지). ## 그룹 정책 -채널별로 그룹/룸 메시지 처리 방식을 제어합니다. +채널별로 그룹/방 메시지가 처리되는 방식을 제어합니다. ```json5 { @@ -253,27 +255,28 @@ otherwise -> reply | 정책 | 동작 | | ------------- | ------------------------------------------------------------ | -| `"open"` | 그룹은 허용 목록을 우회하며, 멘션 게이팅은 계속 적용됩니다. | +| `"open"` | 그룹은 허용 목록을 우회합니다. 멘션 게이팅은 여전히 적용됩니다. | | `"disabled"` | 모든 그룹 메시지를 완전히 차단합니다. | -| `"allowlist"` | 구성된 허용 목록과 일치하는 그룹/룸만 허용합니다. | +| `"allowlist"` | 구성된 허용 목록과 일치하는 그룹/방만 허용합니다. | - `groupPolicy`는 멘션 게이팅(@멘션 필요)과 별개입니다. - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: `groupAllowFrom`을 사용합니다(대체: 명시적 `allowFrom`). - - DM 페어링 승인(`*-allowFrom` 저장소 항목)은 DM 접근에만 적용됩니다. 그룹 발신자 승인은 그룹 허용 목록에 명시적으로 남아 있습니다. + - Signal: `groupAllowFrom`은 수신 Signal 그룹 ID 또는 발신자 전화번호/UUID 중 하나와 일치할 수 있습니다. + - DM 페어링 승인(`*-allowFrom` 저장소 항목)은 DM 접근에만 적용됩니다. 그룹 발신자 권한 부여는 그룹 허용 목록에 명시적으로 남습니다. - Discord: 허용 목록은 `channels.discord.guilds..channels`를 사용합니다. - Slack: 허용 목록은 `channels.slack.channels`를 사용합니다. - - Matrix: 허용 목록은 `channels.matrix.groups`를 사용합니다. 룸 ID 또는 별칭을 권장합니다. 참여한 룸 이름 조회는 최선의 노력으로 수행되며, 해석되지 않은 이름은 런타임에 무시됩니다. 발신자를 제한하려면 `channels.matrix.groupAllowFrom`을 사용하세요. 룸별 `users` 허용 목록도 지원됩니다. + - Matrix: 허용 목록은 `channels.matrix.groups`를 사용합니다. 방 ID 또는 별칭을 선호하세요. 참여한 방 이름 조회는 최선의 노력 방식이며, 확인되지 않은 이름은 런타임에 무시됩니다. 발신자를 제한하려면 `channels.matrix.groupAllowFrom`을 사용하세요. 방별 `users` 허용 목록도 지원됩니다. - 그룹 DM은 별도로 제어됩니다(`channels.discord.dm.*`, `channels.slack.dm.*`). - Telegram 허용 목록은 사용자 ID(`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) 또는 사용자 이름(`"@alice"` 또는 `"alice"`)과 일치할 수 있습니다. 접두사는 대소문자를 구분하지 않습니다. - 기본값은 `groupPolicy: "allowlist"`입니다. 그룹 허용 목록이 비어 있으면 그룹 메시지는 차단됩니다. - - 런타임 안전: 제공자 블록이 완전히 누락된 경우(`channels.` 없음), 그룹 정책은 `channels.defaults.groupPolicy`를 상속하는 대신 실패 시 닫힘 모드(일반적으로 `allowlist`)로 대체됩니다. + - 런타임 안전: provider 블록이 완전히 누락된 경우(`channels.` 없음), 그룹 정책은 `channels.defaults.groupPolicy`를 상속하는 대신 실패 시 닫힘 모드(일반적으로 `allowlist`)로 대체됩니다. -빠른 개념 모델(그룹 메시지 평가 순서): +빠른 사고 모델(그룹 메시지 평가 순서): @@ -289,7 +292,7 @@ otherwise -> reply ## 멘션 게이팅(기본값) -그룹 메시지는 그룹별로 재정의하지 않는 한 멘션이 필요합니다. 기본값은 각 하위 시스템의 `*.groups."*"` 아래에 있습니다. +재정의하지 않는 한 그룹 메시지에는 멘션이 필요합니다. 기본값은 하위 시스템별로 `*.groups."*"` 아래에 있습니다. 봇 메시지에 답장하는 것은 채널이 답장 메타데이터를 지원할 때 암시적 멘션으로 간주됩니다. 봇 메시지를 인용하는 것도 인용 메타데이터를 노출하는 채널에서는 암시적 멘션으로 간주될 수 있습니다. 현재 기본 제공 사례에는 Telegram, WhatsApp, Slack, Discord, Microsoft Teams, ZaloUser가 포함됩니다. @@ -332,13 +335,14 @@ otherwise -> reply - `mentionPatterns`는 대소문자를 구분하지 않는 안전한 정규식 패턴입니다. 유효하지 않은 패턴과 안전하지 않은 중첩 반복 형식은 무시됩니다. - - 명시적 멘션을 제공하는 표면은 여전히 통과합니다. 패턴은 대체 수단입니다. - - 에이전트별 재정의: `agents.list[].groupChat.mentionPatterns`(여러 에이전트가 그룹을 공유할 때 유용). + - 명시적 멘션을 제공하는 표면은 여전히 통과합니다. 패턴은 폴백입니다. + - 에이전트별 재정의: `agents.list[].groupChat.mentionPatterns`(여러 에이전트가 한 그룹을 공유할 때 유용). - 멘션 게이팅은 멘션 감지가 가능할 때만 적용됩니다(네이티브 멘션 또는 `mentionPatterns`가 구성된 경우). - - 그룹 채팅 프롬프트 컨텍스트는 매 턴 해결된 무응답 지시를 전달합니다. 워크스페이스 파일은 `NO_REPLY` 메커니즘을 중복해서는 안 됩니다. - - 무응답이 허용된 그룹은 깨끗한 빈 모델 턴이나 추론만 있는 모델 턴을 `NO_REPLY`와 동일한 무응답으로 처리합니다. 직접 채팅도 직접 무응답이 명시적으로 허용된 경우에만 동일하게 처리합니다. 그렇지 않으면 빈 답장은 실패한 에이전트 턴으로 남습니다. - - Discord 기본값은 `channels.discord.guilds."*"`에 있으며 길드/채널별로 재정의할 수 있습니다. - - 그룹 기록 컨텍스트는 채널 전체에서 균일하게 래핑되며 **대기 중 항목 전용**입니다(멘션 게이팅 때문에 건너뛴 메시지). 전역 기본값에는 `messages.groupChat.historyLimit`를 사용하고 재정의에는 `channels..historyLimit`(또는 `channels..accounts.*.historyLimit`)를 사용하세요. 비활성화하려면 `0`으로 설정하세요. + - 그룹 또는 발신자를 허용 목록에 추가해도 멘션 게이팅은 비활성화되지 않습니다. 모든 메시지가 트리거되어야 한다면 해당 그룹의 `requireMention`을 `false`로 설정하세요. + - 그룹 채팅 프롬프트 컨텍스트는 매 턴마다 확인된 무음 답장 지시를 전달합니다. 워크스페이스 파일은 `NO_REPLY` 메커니즘을 중복해서는 안 됩니다. + - 무음 답장이 허용된 그룹에서는 깨끗한 빈 모델 턴이나 추론만 있는 모델 턴을 `NO_REPLY`와 동등한 무음으로 처리합니다. 직접 채팅도 직접 무음 답장이 명시적으로 허용된 경우에만 동일하게 동작합니다. 그렇지 않으면 빈 답장은 실패한 에이전트 턴으로 남습니다. + - Discord 기본값은 `channels.discord.guilds."*"`에 있습니다(길드/채널별로 재정의 가능). + - 그룹 기록 컨텍스트는 채널 전반에서 동일하게 래핑되며 **대기 중인 항목만** 포함합니다(멘션 게이팅으로 건너뛴 메시지). 전역 기본값에는 `messages.groupChat.historyLimit`을 사용하고, 재정의에는 `channels..historyLimit`(또는 `channels..accounts.*.historyLimit`)을 사용하세요. 비활성화하려면 `0`으로 설정하세요. @@ -347,23 +351,23 @@ otherwise -> reply 일부 채널 구성은 **특정 그룹/방/채널 내부에서** 사용할 수 있는 도구를 제한하는 기능을 지원합니다. -- `tools`: 전체 그룹에 대한 도구 허용/거부. -- `toolsBySender`: 그룹 내 보낸 사람별 재정의. 명시적 키 접두사를 사용하세요: `id:`, `e164:`, `username:`, `name:`, 그리고 `"*"` 와일드카드. 레거시 접두사 없는 키도 여전히 허용되며 `id:`로만 매칭됩니다. +- `tools`: 전체 그룹에 대해 도구를 허용/거부합니다. +- `toolsBySender`: 그룹 내 발신자별 재정의입니다. 명시적 키 접두사를 사용하세요: `id:`, `e164:`, `username:`, `name:`, 그리고 `"*"` 와일드카드. 레거시 접두사 없는 키도 여전히 허용되며 `id:`로만 매칭됩니다. 해결 순서(가장 구체적인 항목이 우선): - 그룹/채널 `toolsBySender` 매칭. + 그룹/채널 `toolsBySender` 일치. - + 그룹/채널 `tools`. - 기본(`"*"` ) `toolsBySender` 매칭. + 기본값(`"*"`) `toolsBySender` 일치. - 기본(`"*"` ) `tools`. + 기본값(`"*"`) `tools`. @@ -393,10 +397,10 @@ otherwise -> reply ## 그룹 허용 목록 -`channels.whatsapp.groups`, `channels.telegram.groups` 또는 `channels.imessage.groups`가 구성되면 키가 그룹 허용 목록으로 작동합니다. 모든 그룹을 허용하면서도 기본 멘션 동작을 설정하려면 `"*"`를 사용하세요. +`channels.whatsapp.groups`, `channels.telegram.groups`, 또는 `channels.imessage.groups`가 구성되면 키가 그룹 허용 목록으로 동작합니다. 모든 그룹을 허용하면서도 기본 멘션 동작을 설정하려면 `"*"`를 사용하세요. -흔한 혼동: DM 페어링 승인은 그룹 승인과 같지 않습니다. DM 페어링을 지원하는 채널에서 페어링 저장소는 DM만 잠금 해제합니다. 그룹 명령은 여전히 `groupAllowFrom` 같은 구성 허용 목록이나 해당 채널의 문서화된 구성 대체값에서 명시적 그룹 보낸 사람 승인이 필요합니다. +흔한 혼동: DM 페어링 승인은 그룹 권한 부여와 같지 않습니다. DM 페어링을 지원하는 채널의 경우 페어링 저장소는 DM만 잠금 해제합니다. 그룹 명령은 여전히 `groupAllowFrom` 같은 구성 허용 목록 또는 해당 채널의 문서화된 구성 폴백을 통한 명시적 그룹 발신자 권한 부여가 필요합니다. 일반적인 의도(복사/붙여넣기): @@ -423,7 +427,7 @@ otherwise -> reply } ``` - + ```json5 { channels: { @@ -460,7 +464,7 @@ otherwise -> reply ## 컨텍스트 필드 -그룹 수신 페이로드는 다음을 설정합니다. +그룹 인바운드 페이로드는 다음을 설정합니다. - `ChatType=group` - `GroupSubject`(알려진 경우) @@ -470,25 +474,25 @@ otherwise -> reply 채널별 참고 사항: -- BlueBubbles는 `GroupMembers`를 채우기 전에 이름 없는 macOS 그룹 참가자를 로컬 연락처 데이터베이스에서 선택적으로 보강할 수 있습니다. 이 기능은 기본적으로 꺼져 있으며 정상적인 그룹 게이팅이 통과한 뒤에만 실행됩니다. +- BlueBubbles는 `GroupMembers`를 채우기 전에 로컬 연락처 데이터베이스에서 이름이 없는 macOS 그룹 참가자를 선택적으로 보강할 수 있습니다. 이는 기본적으로 꺼져 있으며 정상적인 그룹 게이팅이 통과한 후에만 실행됩니다. -에이전트 시스템 프롬프트에는 새 그룹 세션의 첫 턴에 그룹 소개가 포함됩니다. 이 소개는 모델에게 사람처럼 응답하고, Markdown 표를 피하고, 빈 줄을 최소화하며 일반적인 채팅 간격을 따르고, 리터럴 `\n` 시퀀스를 입력하지 않도록 상기시킵니다. 채널에서 가져온 그룹 이름과 참가자 레이블은 인라인 시스템 지시가 아니라 펜스 처리된 신뢰할 수 없는 메타데이터로 렌더링됩니다. +에이전트 시스템 프롬프트에는 새 그룹 세션의 첫 턴에 그룹 소개가 포함됩니다. 이는 모델에게 사람처럼 응답하고, Markdown 표를 피하고, 빈 줄을 최소화하며 일반 채팅 간격을 따르고, 리터럴 `\n` 시퀀스를 입력하지 않도록 상기시킵니다. 채널에서 제공된 그룹 이름과 참가자 레이블은 인라인 시스템 지시가 아니라 펜스 처리된 신뢰할 수 없는 메타데이터로 렌더링됩니다. ## iMessage 세부 사항 -- 라우팅하거나 허용 목록에 넣을 때 `chat_id:`를 선호하세요. -- 채팅 나열: `imsg chats --limit 20`. -- 그룹 답장은 항상 동일한 `chat_id`로 돌아갑니다. +- 라우팅하거나 허용 목록에 추가할 때 `chat_id:`를 선호하세요. +- 채팅 목록: `imsg chats --limit 20`. +- 그룹 답장은 항상 같은 `chat_id`로 돌아갑니다. ## WhatsApp 시스템 프롬프트 -그룹 및 직접 프롬프트 해결, 와일드카드 동작, 계정 재정의 의미 체계를 포함한 표준 WhatsApp 시스템 프롬프트 규칙은 [WhatsApp](/ko/channels/whatsapp#system-prompts)을 참조하세요. +그룹 및 직접 프롬프트 해결, 와일드카드 동작, 계정 재정의 의미론을 포함한 표준 WhatsApp 시스템 프롬프트 규칙은 [WhatsApp](/ko/channels/whatsapp#system-prompts)을 참조하세요. ## WhatsApp 세부 사항 WhatsApp 전용 동작(기록 주입, 멘션 처리 세부 사항)은 [그룹 메시지](/ko/channels/group-messages)를 참조하세요. -## 관련 +## 관련 항목 - [브로드캐스트 그룹](/ko/channels/broadcast-groups) - [채널 라우팅](/ko/channels/channel-routing) diff --git a/docs/ko/channels/signal.md b/docs/ko/channels/signal.md index b9bcc4ab5..5307c69a2 100644 --- a/docs/ko/channels/signal.md +++ b/docs/ko/channels/signal.md @@ -1,35 +1,35 @@ --- read_when: - - Signal 지원 설정 - - Signal 송수신 디버깅 -summary: signal-cli를 통한 Signal 지원(JSON-RPC + SSE), 설정 경로 및 번호 모델 + - Signal 지원 설정하기 + - Signal 송신/수신 디버깅 +summary: signal-cli(JSON-RPC + SSE)를 통한 Signal 지원, 설정 경로 및 번호 모델 title: Signal x-i18n: - generated_at: "2026-04-30T06:19:24Z" + generated_at: "2026-04-30T16:27:46Z" model: gpt-5.5 provider: openai - source_hash: d450454550a86cbf0e2b7231bb149f78275a756517db1f20d7a07e3d298febee + source_hash: 111b6ebe3bde4e03c7ed432f52d663f0b471f0fc4a4bf835c1ac1972467e0b96 source_path: channels/signal.md workflow: 16 --- 상태: 외부 CLI 통합. Gateway는 HTTP JSON-RPC + SSE를 통해 `signal-cli`와 통신합니다. -## 필수 조건 +## 사전 요구 사항 - 서버에 OpenClaw가 설치되어 있어야 합니다(아래 Linux 흐름은 Ubuntu 24에서 테스트됨). - Gateway가 실행되는 호스트에서 `signal-cli`를 사용할 수 있어야 합니다. -- 인증 SMS를 한 번 받을 수 있는 전화번호가 필요합니다(SMS 등록 경로의 경우). +- 인증 SMS 한 건을 받을 수 있는 전화번호가 필요합니다(SMS 등록 경로용). - 등록 중 Signal captcha(`signalcaptchas.org`)를 위한 브라우저 접근이 필요합니다. ## 빠른 설정(초보자) 1. 봇에는 **별도의 Signal 번호**를 사용하세요(권장). -2. `signal-cli`를 설치하세요(JVM 빌드를 사용하는 경우 Java 필요). +2. `signal-cli`를 설치하세요(JVM 빌드를 사용하는 경우 Java가 필요함). 3. 설정 경로 하나를 선택하세요: - **경로 A(QR 연결):** `signal-cli link -n "OpenClaw"`를 실행하고 Signal로 스캔합니다. - **경로 B(SMS 등록):** captcha + SMS 인증으로 전용 번호를 등록합니다. -4. OpenClaw를 구성하고 Gateway를 재시작합니다. +4. OpenClaw를 구성하고 Gateway를 다시 시작합니다. 5. 첫 DM을 보내고 페어링을 승인합니다(`openclaw pairing approve signal `). 최소 구성: @@ -55,17 +55,17 @@ x-i18n: | `account` | E.164 형식의 봇 전화번호(`+15551234567`) | | `cliPath` | `signal-cli` 경로(`PATH`에 있으면 `signal-cli`) | | `dmPolicy` | DM 접근 정책(`pairing` 권장) | -| `allowFrom` | DM이 허용된 전화번호 또는 `uuid:` 값 | +| `allowFrom` | DM이 허용되는 전화번호 또는 `uuid:` 값 | -## 이것은 무엇인가 +## 이것이 무엇인가 -- `signal-cli`를 통한 Signal 채널입니다(내장 libsignal 아님). -- 결정적 라우팅: 응답은 항상 Signal로 돌아갑니다. +- `signal-cli`를 통한 Signal 채널(내장 libsignal이 아님). +- 결정적 라우팅: 답장은 항상 Signal로 돌아갑니다. - DM은 에이전트의 기본 세션을 공유하며, 그룹은 격리됩니다(`agent::signal:group:`). ## 구성 쓰기 -기본적으로 Signal은 `/config set|unset`에 의해 트리거되는 구성 업데이트 쓰기가 허용됩니다(`commands.config: true` 필요). +기본적으로 Signal은 `/config set|unset`으로 트리거된 구성 업데이트를 쓸 수 있습니다(`commands.config: true` 필요). 비활성화: @@ -77,18 +77,18 @@ x-i18n: ## 번호 모델(중요) -- Gateway는 **Signal 기기**(`signal-cli` 계정)에 연결됩니다. -- 봇을 **개인 Signal 계정**에서 실행하면, 자신의 메시지를 무시합니다(루프 보호). -- "내가 봇에게 문자를 보내면 답장한다"를 원한다면 **별도의 봇 번호**를 사용하세요. +- Gateway는 **Signal 기기**(`signal-cli` 계정)에 연결합니다. +- 봇을 **개인 Signal 계정**에서 실행하면 자신의 메시지를 무시합니다(루프 보호). +- "내가 봇에게 문자를 보내면 답장한다"를 원하면 **별도의 봇 번호**를 사용하세요. ## 설정 경로 A: 기존 Signal 계정 연결(QR) -1. `signal-cli`를 설치하세요(JVM 또는 네이티브 빌드). -2. 봇 계정을 연결하세요: +1. `signal-cli`를 설치합니다(JVM 또는 네이티브 빌드). +2. 봇 계정을 연결합니다: - `signal-cli link -n "OpenClaw"`를 실행한 다음 Signal에서 QR을 스캔합니다. 3. Signal을 구성하고 Gateway를 시작합니다. -예시: +예: ```json5 { @@ -110,9 +110,9 @@ x-i18n: 기존 Signal 앱 계정을 연결하는 대신 전용 봇 번호를 원할 때 사용하세요. -1. SMS를 받을 수 있는 번호를 준비하세요(유선전화는 음성 인증 가능). +1. SMS를 받을 수 있는 번호를 준비합니다(유선 전화는 음성 인증 가능). - 계정/세션 충돌을 피하려면 전용 봇 번호를 사용하세요. -2. Gateway 호스트에 `signal-cli`를 설치하세요: +2. Gateway 호스트에 `signal-cli`를 설치합니다: ```bash VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//') @@ -123,9 +123,9 @@ signal-cli --version ``` JVM 빌드(`signal-cli-${VERSION}.tar.gz`)를 사용하는 경우 먼저 JRE 25+를 설치하세요. -`signal-cli`를 최신 상태로 유지하세요. 업스트림은 Signal 서버 API가 변경되면 오래된 릴리스가 깨질 수 있다고 안내합니다. +`signal-cli`를 최신 상태로 유지하세요. 업스트림에서는 오래된 릴리스가 Signal 서버 API 변경으로 인해 중단될 수 있다고 안내합니다. -3. 번호를 등록하고 인증하세요: +3. 번호를 등록하고 인증합니다: ```bash signal-cli -a + register @@ -135,32 +135,32 @@ captcha가 필요한 경우: 1. `https://signalcaptchas.org/registration/generate.html`을 엽니다. 2. captcha를 완료하고 "Open Signal"에서 `signalcaptcha://...` 링크 대상을 복사합니다. -3. 가능하면 브라우저 세션과 동일한 외부 IP에서 실행하세요. -4. 즉시 다시 등록을 실행하세요(captcha 토큰은 빠르게 만료됨): +3. 가능하면 브라우저 세션과 동일한 외부 IP에서 실행합니다. +4. 즉시 등록을 다시 실행합니다(captcha 토큰은 빠르게 만료됨): ```bash signal-cli -a + register --captcha '' signal-cli -a + verify ``` -4. OpenClaw를 구성하고 Gateway를 재시작한 뒤 채널을 확인하세요: +4. OpenClaw를 구성하고 Gateway를 다시 시작한 다음 채널을 확인합니다: ```bash -# If you run the gateway as a user systemd service: +# Gateway를 사용자 systemd 서비스로 실행하는 경우: systemctl --user restart openclaw-gateway.service -# Then verify: +# 그런 다음 확인: openclaw doctor openclaw channels status --probe ``` -5. DM 발신자를 페어링하세요: +5. DM 발신자를 페어링합니다: - 봇 번호로 아무 메시지나 보냅니다. - 서버에서 코드를 승인합니다: `openclaw pairing approve signal `. - "알 수 없는 연락처"를 피하려면 휴대폰에 봇 번호를 연락처로 저장하세요. -`signal-cli`로 전화번호 계정을 등록하면 해당 번호의 기본 Signal 앱 세션 인증이 해제될 수 있습니다. 전용 봇 번호를 사용하는 것이 좋으며, 기존 휴대폰 앱 설정을 유지해야 한다면 QR 연결 모드를 사용하세요. +`signal-cli`로 전화번호 계정을 등록하면 해당 번호의 기본 Signal 앱 세션 인증이 해제될 수 있습니다. 전용 봇 번호를 선호하거나, 기존 휴대폰 앱 설정을 유지해야 한다면 QR 연결 모드를 사용하세요. 업스트림 참조: @@ -171,7 +171,7 @@ openclaw channels status --probe ## 외부 데몬 모드(httpUrl) -`signal-cli`를 직접 관리하려는 경우(느린 JVM 콜드 스타트, 컨테이너 초기화, 공유 CPU 등), 데몬을 별도로 실행하고 OpenClaw가 이를 가리키도록 설정하세요: +`signal-cli`를 직접 관리하려면(느린 JVM 콜드 스타트, 컨테이너 초기화, 공유 CPU) 데몬을 별도로 실행하고 OpenClaw가 이를 가리키도록 하세요: ```json5 { @@ -184,7 +184,7 @@ openclaw channels status --probe } ``` -이렇게 하면 OpenClaw 내부의 자동 생성과 시작 대기를 건너뜁니다. 자동 생성 시 시작이 느리다면 `channels.signal.startupTimeoutMs`를 설정하세요. +이렇게 하면 OpenClaw 내부의 자동 생성과 시작 대기를 건너뜁니다. 자동 생성 시 시작이 느린 경우 `channels.signal.startupTimeoutMs`를 설정하세요. ## 접근 제어(DM + 그룹) @@ -195,47 +195,48 @@ DM: - 승인 방법: - `openclaw pairing list signal` - `openclaw pairing approve signal ` -- 페어링은 Signal DM의 기본 토큰 교환 방식입니다. 자세한 내용: [페어링](/ko/channels/pairing) +- 페어링은 Signal DM의 기본 토큰 교환입니다. 세부 정보: [페어링](/ko/channels/pairing) - UUID 전용 발신자(`sourceUuid`에서 온)는 `channels.signal.allowFrom`에 `uuid:`로 저장됩니다. 그룹: - `channels.signal.groupPolicy = open | allowlist | disabled`. -- `channels.signal.groupAllowFrom`은 `allowlist`가 설정된 경우 그룹에서 누가 트리거할 수 있는지 제어합니다. +- `channels.signal.groupAllowFrom`은 `allowlist`가 설정된 경우 어떤 그룹 또는 발신자가 그룹 답장을 트리거할 수 있는지 제어합니다. 항목은 Signal 그룹 ID(raw, `group:`, 또는 `signal:group:`), 발신자 전화번호, `uuid:` 값, 또는 `*`일 수 있습니다. - `channels.signal.groups["" | "*"]`는 `requireMention`, `tools`, `toolsBySender`로 그룹 동작을 재정의할 수 있습니다. -- 다중 계정 설정에서 계정별 재정의에는 `channels.signal.accounts..groups`를 사용하세요. -- 런타임 참고: `channels.signal`이 완전히 없으면, 런타임은 그룹 검사에 `groupPolicy="allowlist"`로 폴백합니다(`channels.defaults.groupPolicy`가 설정되어 있어도). +- 다중 계정 설정의 계정별 재정의에는 `channels.signal.accounts..groups`를 사용하세요. +- `groupAllowFrom`을 통해 Signal 그룹을 허용 목록에 추가해도 그 자체로 멘션 게이트가 비활성화되지는 않습니다. 별도로 구성된 `channels.signal.groups[""]` 항목은 `requireMention=true`가 설정되지 않는 한 모든 그룹 메시지를 처리합니다. +- 런타임 참고: `channels.signal`이 완전히 없으면 런타임은 그룹 검사에 대해 `groupPolicy="allowlist"`로 폴백합니다(`channels.defaults.groupPolicy`가 설정되어 있더라도). ## 작동 방식(동작) - `signal-cli`는 데몬으로 실행되며, Gateway는 SSE를 통해 이벤트를 읽습니다. - 인바운드 메시지는 공유 채널 엔벌로프로 정규화됩니다. -- 응답은 항상 동일한 번호 또는 그룹으로 라우팅됩니다. +- 답장은 항상 동일한 번호 또는 그룹으로 라우팅됩니다. ## 미디어 + 제한 -- 아웃바운드 텍스트는 `channels.signal.textChunkLimit`로 청크됩니다(기본값 4000). -- 선택적 줄바꿈 청크: 길이 기반 청크 전에 빈 줄(문단 경계)에서 분할하려면 `channels.signal.chunkMode="newline"`을 설정하세요. -- 첨부 파일을 지원합니다(`signal-cli`에서 base64로 가져옴). -- `contentType`이 없을 때 음성 메모 첨부 파일은 `signal-cli` 파일 이름을 MIME 폴백으로 사용하므로, 오디오 전사가 AAC 음성 메모를 계속 분류할 수 있습니다. +- 아웃바운드 텍스트는 `channels.signal.textChunkLimit`(기본값 4000)에 맞춰 청크로 나뉩니다. +- 선택적 줄바꿈 청킹: 길이 청킹 전에 빈 줄(문단 경계)에서 나누려면 `channels.signal.chunkMode="newline"`을 설정하세요. +- 첨부 파일 지원(`signal-cli`에서 base64로 가져옴). +- `contentType`이 누락된 경우 음성 메모 첨부 파일은 `signal-cli` 파일명을 MIME 폴백으로 사용하므로, 오디오 전사가 AAC 음성 메모를 계속 분류할 수 있습니다. - 기본 미디어 한도: `channels.signal.mediaMaxMb`(기본값 8). - 미디어 다운로드를 건너뛰려면 `channels.signal.ignoreAttachments`를 사용하세요. -- 그룹 기록 컨텍스트는 `channels.signal.historyLimit`(또는 `channels.signal.accounts.*.historyLimit`)을 사용하며, `messages.groupChat.historyLimit`로 폴백합니다. 비활성화하려면 `0`으로 설정하세요(기본값 50). +- 그룹 기록 컨텍스트는 `channels.signal.historyLimit`(또는 `channels.signal.accounts.*.historyLimit`)를 사용하며, `messages.groupChat.historyLimit`로 폴백합니다. 비활성화하려면 `0`으로 설정하세요(기본값 50). ## 입력 중 표시 + 읽음 확인 -- **입력 중 표시**: OpenClaw는 `signal-cli sendTyping`을 통해 입력 중 신호를 보내고, 응답이 실행되는 동안 이를 갱신합니다. -- **읽음 확인**: `channels.signal.sendReadReceipts`가 true이면 OpenClaw는 허용된 DM에 대해 읽음 확인을 전달합니다. +- **입력 중 표시**: OpenClaw는 `signal-cli sendTyping`을 통해 입력 중 신호를 보내고, 답장이 실행되는 동안 이를 갱신합니다. +- **읽음 확인**: `channels.signal.sendReadReceipts`가 true이면 OpenClaw는 허용된 DM에 대한 읽음 확인을 전달합니다. - Signal-cli는 그룹의 읽음 확인을 노출하지 않습니다. ## 반응(메시지 도구) - `channel=signal`과 함께 `message action=react`를 사용하세요. -- 대상: 발신자 E.164 또는 UUID(페어링 출력의 `uuid:` 사용; 순수 UUID도 작동). -- `messageId`는 반응할 메시지의 Signal 타임스탬프입니다. +- 대상: 발신자 E.164 또는 UUID(페어링 출력의 `uuid:` 사용, bare UUID도 작동). +- `messageId`는 반응하려는 메시지의 Signal 타임스탬프입니다. - 그룹 반응에는 `targetAuthor` 또는 `targetAuthorUuid`가 필요합니다. -예시: +예: ``` message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥 @@ -247,20 +248,20 @@ message action=react channel=signal target=signal:group: targetAuthor=u - `channels.signal.actions.reactions`: 반응 작업을 활성화/비활성화합니다(기본값 true). - `channels.signal.reactionLevel`: `off | ack | minimal | extensive`. - - `off`/`ack`는 에이전트 반응을 비활성화합니다(메시지 도구 `react`는 오류 발생). + - `off`/`ack`는 에이전트 반응을 비활성화합니다(메시지 도구 `react`는 오류를 냅니다). - `minimal`/`extensive`는 에이전트 반응을 활성화하고 안내 수준을 설정합니다. - 계정별 재정의: `channels.signal.accounts..actions.reactions`, `channels.signal.accounts..reactionLevel`. -## 전송 대상(CLI/cron) +## 전달 대상(CLI/cron) - DM: `signal:+15551234567`(또는 일반 E.164). -- UUID DM: `uuid:`(또는 순수 UUID). +- UUID DM: `uuid:`(또는 bare UUID). - 그룹: `signal:group:`. - 사용자 이름: `username:`(Signal 계정에서 지원하는 경우). ## 문제 해결 -먼저 이 순서대로 실행하세요: +먼저 이 단계를 실행하세요: ```bash openclaw status @@ -270,7 +271,7 @@ openclaw doctor openclaw channels status --probe ``` -필요하면 DM 페어링 상태를 확인하세요: +필요한 경우 DM 페어링 상태를 확인하세요: ```bash openclaw pairing list signal @@ -278,11 +279,11 @@ openclaw pairing list signal 일반적인 실패: -- 데몬은 접근 가능하지만 응답 없음: 계정/데몬 설정(`httpUrl`, `account`)과 수신 모드를 확인하세요. -- DM 무시됨: 발신자가 페어링 승인 대기 중입니다. -- 그룹 메시지 무시됨: 그룹 발신자/멘션 게이트가 전송을 차단합니다. +- 데몬에는 연결되지만 답장이 없음: 계정/데몬 설정(`httpUrl`, `account`)과 수신 모드를 확인하세요. +- DM이 무시됨: 발신자가 페어링 승인 대기 중입니다. +- 그룹 메시지가 무시됨: 그룹 발신자/멘션 게이트가 전달을 차단합니다. - 편집 후 구성 검증 오류: `openclaw doctor --fix`를 실행하세요. -- 진단에 Signal이 없음: `channels.signal.enabled: true`를 확인하세요. +- 진단에 Signal이 누락됨: `channels.signal.enabled: true`를 확인하세요. 추가 확인: @@ -294,26 +295,26 @@ grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 분류 흐름: [/channels/troubleshooting](/ko/channels/troubleshooting). -## 보안 참고 +## 보안 참고 사항 - `signal-cli`는 계정 키를 로컬에 저장합니다(일반적으로 `~/.local/share/signal-cli/data/`). - 서버 마이그레이션 또는 재빌드 전에 Signal 계정 상태를 백업하세요. - 더 넓은 DM 접근을 명시적으로 원하지 않는 한 `channels.signal.dmPolicy: "pairing"`을 유지하세요. -- SMS 인증은 등록 또는 복구 흐름에만 필요하지만, 번호/계정 제어권을 잃으면 재등록이 복잡해질 수 있습니다. +- SMS 인증은 등록 또는 복구 흐름에만 필요하지만, 번호/계정에 대한 제어를 잃으면 재등록이 복잡해질 수 있습니다. ## 구성 참조(Signal) 전체 구성: [구성](/ko/gateway/configuration) -Provider 옵션: +제공자 옵션: - `channels.signal.enabled`: 채널 시작을 활성화/비활성화합니다. - `channels.signal.account`: 봇 계정의 E.164입니다. - `channels.signal.cliPath`: `signal-cli` 경로입니다. - `channels.signal.httpUrl`: 전체 데몬 URL입니다(호스트/포트를 재정의). -- `channels.signal.httpHost`, `channels.signal.httpPort`: 데몬 바인딩입니다(기본값 127.0.0.1:8080). -- `channels.signal.autoStart`: 데몬을 자동 생성합니다(`httpUrl`이 설정되지 않은 경우 기본값 true). -- `channels.signal.startupTimeoutMs`: 시작 대기 시간 제한(ms)입니다(상한 120000). +- `channels.signal.httpHost`, `channels.signal.httpPort`: 데몬 바인드입니다(기본값 127.0.0.1:8080). +- `channels.signal.autoStart`: 데몬을 자동으로 생성합니다(`httpUrl`이 설정되지 않은 경우 기본값 true). +- `channels.signal.startupTimeoutMs`: 시작 대기 제한 시간(ms)입니다(상한 120000). - `channels.signal.receiveMode`: `on-start | manual`. - `channels.signal.ignoreAttachments`: 첨부 파일 다운로드를 건너뜁니다. - `channels.signal.ignoreStories`: 데몬의 스토리를 무시합니다. @@ -321,18 +322,18 @@ Provider 옵션: - `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled`(기본값: pairing). - `channels.signal.allowFrom`: DM 허용 목록입니다(E.164 또는 `uuid:`). `open`에는 `"*"`가 필요합니다. Signal에는 사용자 이름이 없으므로 전화번호/UUID ID를 사용하세요. - `channels.signal.groupPolicy`: `open | allowlist | disabled`(기본값: allowlist). -- `channels.signal.groupAllowFrom`: 그룹 발신자 허용 목록입니다. -- `channels.signal.groups`: Signal 그룹 ID(또는 `"*"`)를 키로 하는 그룹별 재정의입니다. 지원 필드: `requireMention`, `tools`, `toolsBySender`. +- `channels.signal.groupAllowFrom`: 그룹 허용 목록입니다. Signal 그룹 ID(원시, `group:` 또는 `signal:group:`), 보낸 사람 E.164 번호 또는 `uuid:` 값을 허용합니다. +- `channels.signal.groups`: Signal 그룹 ID(또는 `"*"`)를 키로 하는 그룹별 재정의입니다. 지원되는 필드: `requireMention`, `tools`, `toolsBySender`. - `channels.signal.accounts..groups`: 다중 계정 설정을 위한 `channels.signal.groups`의 계정별 버전입니다. - `channels.signal.historyLimit`: 컨텍스트로 포함할 최대 그룹 메시지 수입니다(0이면 비활성화). -- `channels.signal.dmHistoryLimit`: 사용자 턴 단위의 DM 기록 제한입니다. 사용자별 재정의: `channels.signal.dms[""].historyLimit`. -- `channels.signal.textChunkLimit`: 발신 청크 크기(문자 수)입니다. -- `channels.signal.chunkMode`: 길이 기준 청크 분할 전에 빈 줄(단락 경계) 기준으로 나누려면 `length`(기본값) 또는 `newline`을 사용합니다. -- `channels.signal.mediaMaxMb`: 수신/발신 미디어 한도(MB)입니다. +- `channels.signal.dmHistoryLimit`: 사용자 턴 기준 DM 기록 제한입니다. 사용자별 재정의: `channels.signal.dms[""].historyLimit`. +- `channels.signal.textChunkLimit`: 발신 청크 크기입니다(문자). +- `channels.signal.chunkMode`: 길이 기준 청크 분할 전에 빈 줄(단락 경계)을 기준으로 분할하려면 `length`(기본값) 또는 `newline`입니다. +- `channels.signal.mediaMaxMb`: 수신/발신 미디어 상한입니다(MB). 관련 전역 옵션: -- `agents.list[].groupChat.mentionPatterns`(Signal은 기본 멘션을 지원하지 않습니다). +- `agents.list[].groupChat.mentionPatterns`(Signal은 네이티브 멘션을 지원하지 않음). - `messages.groupChat.mentionPatterns`(전역 폴백). - `messages.responsePrefix`. diff --git a/docs/ko/channels/slack.md b/docs/ko/channels/slack.md index 10f928e84..a5dc037d1 100644 --- a/docs/ko/channels/slack.md +++ b/docs/ko/channels/slack.md @@ -4,44 +4,44 @@ read_when: summary: Slack 설정 및 런타임 동작(소켓 모드 + HTTP 요청 URL) title: Slack x-i18n: - generated_at: "2026-04-30T06:19:25Z" + generated_at: "2026-04-30T16:27:39Z" model: gpt-5.5 provider: openai - source_hash: 08024bd947ddeb00a1ab3aaa3864cf31817303bbc0523902acdc539fc662e127 + source_hash: 55beddb43a6b91c6853dcf053eab713322de4da5beced7c107d73e1c066fded6 source_path: channels/slack.md workflow: 16 --- -프로덕션에서 Slack 앱 통합을 통해 DM 및 채널에 사용할 수 있습니다. 기본 모드는 Socket Mode이며, HTTP Request URLs도 지원됩니다. +DM 및 채널을 Slack 앱 통합으로 프로덕션에 바로 사용할 수 있습니다. 기본 모드는 Socket Mode이며, HTTP Request URLs도 지원됩니다. - + Slack DM은 기본적으로 페어링 모드를 사용합니다. - - 네이티브 명령 동작 및 명령 카탈로그입니다. + + 네이티브 명령 동작과 명령 카탈로그입니다. - - 크로스 채널 진단 및 복구 플레이북입니다. + + 채널 간 진단 및 복구 플레이북입니다. ## 빠른 설정 - + - + Slack 앱 설정에서 **[Create New App](https://api.slack.com/apps/new)** 버튼을 누릅니다. - - **from a manifest**를 선택하고 앱을 사용할 워크스페이스를 선택합니다 - - 아래의 [예시 매니페스트](#manifest-and-scope-checklist)를 붙여넣고 계속 진행하여 생성합니다 - - `connections:write`가 있는 **App-Level Token**(`xapp-...`)을 생성합니다 - - 앱을 설치하고 표시되는 **Bot Token**(`xoxb-...`)을 복사합니다 + - **from a manifest**를 선택하고 앱에 사용할 워크스페이스를 선택합니다 + - 아래의 [예시 매니페스트](#manifest-and-scope-checklist)를 붙여넣고 계속해서 만듭니다 + - `connections:write`가 포함된 **App-Level Token**(`xapp-...`)을 생성합니다 + - 앱을 설치하고 표시된 **Bot Token**(`xoxb-...`)을 복사합니다 - + 권장 SecretRef 설정: @@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run openclaw config patch --file ./slack.socket.patch.json5 ``` - Env 폴백(기본 계정만 해당): + Env 대체 방식(기본 계정만): ```bash SLACK_APP_TOKEN=xapp-... @@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -86,17 +86,17 @@ openclaw gateway - + Slack 앱 설정에서 **[Create New App](https://api.slack.com/apps/new)** 버튼을 누릅니다. - - **from a manifest**를 선택하고 앱을 사용할 워크스페이스를 선택합니다 - - [예시 매니페스트](#manifest-and-scope-checklist)를 붙여넣고 생성하기 전에 URL을 업데이트합니다 + - **from a manifest**를 선택하고 앱에 사용할 워크스페이스를 선택합니다 + - [예시 매니페스트](#manifest-and-scope-checklist)를 붙여넣고 만들기 전에 URL을 업데이트합니다 - 요청 검증을 위한 **Signing Secret**을 저장합니다 - - 앱을 설치하고 표시되는 **Bot Token**(`xoxb-...`)을 복사합니다 + - 앱을 설치하고 표시된 **Bot Token**(`xoxb-...`)을 복사합니다 - + 권장 SecretRef 설정: @@ -128,7 +128,7 @@ openclaw config patch --file ./slack.http.patch.json5 - + ```bash openclaw gateway @@ -140,9 +140,9 @@ openclaw gateway -## Socket Mode 전송 조정 +## Socket Mode 전송 튜닝 -OpenClaw는 Socket Mode에서 Slack SDK 클라이언트 pong 제한 시간을 기본적으로 15초로 설정합니다. 워크스페이스 또는 호스트별 조정이 필요한 경우에만 전송 설정을 재정의하세요. +OpenClaw는 Socket Mode에서 Slack SDK 클라이언트 pong 타임아웃을 기본적으로 15초로 설정합니다. 워크스페이스 또는 호스트별 튜닝이 필요할 때만 전송 설정을 재정의하세요. ```json5 { @@ -159,11 +159,11 @@ OpenClaw는 Socket Mode에서 Slack SDK 클라이언트 pong 제한 시간을 } ``` -Slack WebSocket pong/서버 ping 제한 시간이 기록되거나 이벤트 루프 고갈이 알려진 호스트에서 실행되는 Socket Mode 워크스페이스에만 사용하세요. `clientPingTimeout`은 SDK가 클라이언트 ping을 보낸 뒤 pong을 기다리는 시간이며, `serverPingTimeout`은 Slack 서버 ping을 기다리는 시간입니다. 앱 메시지와 이벤트는 애플리케이션 상태로 유지되며, 전송 활성 상태 신호가 아닙니다. +Slack websocket pong/server-ping 타임아웃이 기록되는 Socket Mode 워크스페이스나 이벤트 루프 기아가 알려진 호스트에서만 사용하세요. `clientPingTimeout`은 SDK가 클라이언트 ping을 보낸 뒤 pong을 기다리는 시간이고, `serverPingTimeout`은 Slack 서버 ping을 기다리는 시간입니다. 앱 메시지와 이벤트는 전송 생존 신호가 아니라 애플리케이션 상태로 남습니다. ## 매니페스트 및 범위 체크리스트 -기본 Slack 앱 매니페스트는 Socket Mode와 HTTP Request URLs에서 동일합니다. `settings` 블록(및 슬래시 명령 `url`)만 다릅니다. +기본 Slack 앱 매니페스트는 Socket Mode와 HTTP Request URLs에서 동일합니다. `settings` 블록(및 슬래시 명령의 `url`)만 다릅니다. 기본 매니페스트(Socket Mode 기본값): @@ -237,7 +237,7 @@ Slack WebSocket pong/서버 ping 제한 시간이 기록되거나 이벤트 루 } ``` -**HTTP Request URLs 모드**에서는 `settings`를 HTTP 변형으로 바꾸고 각 슬래시 명령에 `url`을 추가합니다. 공개 URL이 필요합니다. +**HTTP Request URLs 모드**의 경우 `settings`를 HTTP 변형으로 바꾸고 각 슬래시 명령에 `url`을 추가합니다. 공개 URL이 필요합니다. ```json { @@ -272,17 +272,17 @@ Slack WebSocket pong/서버 ping 제한 시간이 기록되거나 이벤트 루 위 기본값을 확장하는 다양한 기능을 노출합니다. - + - 단일 구성 명령 대신 여러 [네이티브 슬래시 명령](#commands-and-slash-behavior)을 세부적으로 사용할 수 있습니다. + 여러 [네이티브 슬래시 명령](#commands-and-slash-behavior)을 세부 동작이 있는 단일 구성 명령 대신 사용할 수 있습니다. - `/status` 명령은 예약되어 있으므로 `/status` 대신 `/agentstatus`를 사용하세요. - - 한 번에 25개를 초과하는 슬래시 명령을 사용할 수 없습니다. + - 한 번에 사용할 수 있는 슬래시 명령은 25개를 넘을 수 없습니다. 기존 `features.slash_commands` 섹션을 [사용 가능한 명령](/ko/tools/slash-commands#command-list)의 하위 집합으로 바꾸세요. - + ```json "slash_commands": [ @@ -399,7 +399,7 @@ Slack WebSocket pong/서버 ping 제한 시간이 기록되거나 이벤트 루 - 위 Socket Mode와 동일한 `slash_commands` 목록을 사용하고 모든 항목에 `"url": "https://gateway-host.example.com/slack/events"`를 추가하세요. 예: + 위 Socket Mode와 동일한 `slash_commands` 목록을 사용하고, 모든 항목에 `"url": "https://gateway-host.example.com/slack/events"`를 추가합니다. 예: ```json "slash_commands": [ @@ -422,13 +422,13 @@ Slack WebSocket pong/서버 ping 제한 시간이 기록되거나 이벤트 루 - - 발신 메시지에 기본 Slack 앱 ID 대신 활성 에이전트 ID(사용자 지정 사용자 이름 및 아이콘)를 사용하려면 `chat:write.customize` 봇 범위를 추가하세요. + + 발신 메시지가 기본 Slack 앱 ID 대신 활성 에이전트 ID(사용자 지정 사용자 이름과 아이콘)를 사용하도록 하려면 `chat:write.customize` 봇 범위를 추가하세요. 이모지 아이콘을 사용하는 경우 Slack은 `:emoji_name:` 구문을 기대합니다. - + `channels.slack.userToken`을 구성하는 경우 일반적인 읽기 범위는 다음과 같습니다. - `channels:history`, `groups:history`, `im:history`, `mpim:history` @@ -448,23 +448,23 @@ Slack WebSocket pong/서버 ping 제한 시간이 기록되거나 이벤트 루 - HTTP 모드에는 `botToken` + `signingSecret`이 필요합니다. - `botToken`, `appToken`, `signingSecret`, `userToken`은 일반 텍스트 문자열 또는 SecretRef 객체를 허용합니다. -- 구성 토큰은 env 폴백보다 우선합니다. -- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env 폴백은 기본 계정에만 적용됩니다. -- `userToken`(`xoxp-...`)은 구성 전용(env 폴백 없음)이며 읽기 전용 동작이 기본값입니다(`userTokenReadOnly: true`). +- 구성 토큰은 env fallback보다 우선합니다. +- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` env fallback은 기본 계정에만 적용됩니다. +- `userToken`(`xoxp-...`)은 구성 전용이며(env fallback 없음) 기본값은 읽기 전용 동작(`userTokenReadOnly: true`)입니다. 상태 스냅샷 동작: - Slack 계정 검사는 자격 증명별 `*Source` 및 `*Status` 필드(`botToken`, `appToken`, `signingSecret`, `userToken`)를 추적합니다. - 상태는 `available`, `configured_unavailable`, 또는 `missing`입니다. -- `configured_unavailable`은 계정이 SecretRef - 또는 다른 비인라인 비밀 소스를 통해 구성되었지만, 현재 명령/런타임 경로가 - 실제 값을 확인할 수 없었다는 뜻입니다. +- `configured_unavailable`은 계정이 SecretRef 또는 다른 비인라인 비밀 소스를 통해 + 구성되었지만, 현재 명령/런타임 경로에서 실제 값을 + 확인할 수 없었다는 뜻입니다. - HTTP 모드에서는 `signingSecretStatus`가 포함됩니다. Socket Mode에서는 필요한 쌍이 `botTokenStatus` + `appTokenStatus`입니다. -작업/디렉터리 읽기에는 구성된 경우 사용자 토큰이 우선될 수 있습니다. 쓰기에는 봇 토큰이 계속 우선되며, 사용자 토큰 쓰기는 `userTokenReadOnly: false`이고 봇 토큰을 사용할 수 없을 때만 허용됩니다. +작업/디렉터리 읽기의 경우 구성되어 있으면 사용자 토큰을 우선 사용할 수 있습니다. 쓰기의 경우 봇 토큰이 계속 우선됩니다. 사용자 토큰 쓰기는 `userTokenReadOnly: false`이고 봇 토큰을 사용할 수 없을 때만 허용됩니다. ## 작업 및 게이트 @@ -474,20 +474,20 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. 현재 Slack 도구에서 사용할 수 있는 작업 그룹: | 그룹 | 기본값 | -| ---------- | ------ | -| messages | 활성화 | -| reactions | 활성화 | -| pins | 활성화 | -| memberInfo | 활성화 | -| emojiList | 활성화 | +| ---------- | ------- | +| messages | 활성화됨 | +| reactions | 활성화됨 | +| pins | 활성화됨 | +| memberInfo | 활성화됨 | +| emojiList | 활성화됨 | -현재 Slack 메시지 작업에는 `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, `emoji-list`가 포함됩니다. `download-file`은 수신 파일 자리표시자에 표시되는 Slack 파일 ID를 허용하며, 이미지의 경우 이미지 미리보기를, 다른 파일 유형의 경우 로컬 파일 메타데이터를 반환합니다. +현재 Slack 메시지 작업에는 `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, `emoji-list`가 포함됩니다. `download-file`은 인바운드 파일 플레이스홀더에 표시된 Slack 파일 ID를 허용하며, 이미지의 경우 이미지 미리보기를 반환하고 다른 파일 유형의 경우 로컬 파일 메타데이터를 반환합니다. ## 액세스 제어 및 라우팅 - - `channels.slack.dmPolicy`는 DM 액세스를 제어합니다. `channels.slack.allowFrom`은 표준 DM 허용 목록입니다. + + `channels.slack.dmPolicy`는 DM 액세스를 제어합니다. `channels.slack.allowFrom`은 표준 DM allowlist입니다. - `pairing`(기본값) - `allowlist` @@ -500,43 +500,43 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. - `channels.slack.allowFrom` - `dm.allowFrom`(레거시) - `dm.groupEnabled`(그룹 DM 기본값 false) - - `dm.groupChannels`(선택적 MPIM 허용 목록) + - `dm.groupChannels`(선택적 MPIM allowlist) 다중 계정 우선순위: - `channels.slack.accounts.default.allowFrom`은 `default` 계정에만 적용됩니다. - - 이름이 지정된 계정은 자체 `allowFrom`이 설정되지 않은 경우 `channels.slack.allowFrom`을 상속합니다. - - 이름이 지정된 계정은 `channels.slack.accounts.default.allowFrom`을 상속하지 않습니다. + - 명명된 계정은 자체 `allowFrom`이 설정되지 않은 경우 `channels.slack.allowFrom`을 상속합니다. + - 명명된 계정은 `channels.slack.accounts.default.allowFrom`을 상속하지 않습니다. - 레거시 `channels.slack.dm.policy` 및 `channels.slack.dm.allowFrom`은 호환성을 위해 계속 읽습니다. `openclaw doctor --fix`는 액세스를 변경하지 않고 가능할 때 이를 `dmPolicy` 및 `allowFrom`으로 마이그레이션합니다. + 레거시 `channels.slack.dm.policy` 및 `channels.slack.dm.allowFrom`은 호환성을 위해 계속 읽습니다. `openclaw doctor --fix`는 액세스를 변경하지 않고 수행할 수 있을 때 이를 `dmPolicy` 및 `allowFrom`으로 마이그레이션합니다. - DM에서 페어링은 `openclaw pairing approve slack `를 사용합니다. + DM에서의 페어링은 `openclaw pairing approve slack `를 사용합니다. - + `channels.slack.groupPolicy`는 채널 처리를 제어합니다. - `open` - `allowlist` - `disabled` - 채널 허용 목록은 `channels.slack.channels` 아래에 있으며 구성 키로 **안정적인 Slack 채널 ID**(예: `C12345678`)를 사용해야 합니다. + 채널 allowlist는 `channels.slack.channels` 아래에 있으며, 구성 키로 **안정적인 Slack 채널 ID**(예: `C12345678`)를 사용해야 합니다. - 런타임 참고: `channels.slack`이 완전히 없는 경우(env 전용 설정), 런타임은 `groupPolicy="allowlist"`로 폴백하고 경고를 기록합니다(`channels.defaults.groupPolicy`가 설정되어 있더라도). + 런타임 참고: `channels.slack`이 완전히 누락된 경우(env 전용 설정), 런타임은 `groupPolicy="allowlist"`로 fallback하고 경고를 기록합니다(`channels.defaults.groupPolicy`가 설정되어 있어도 동일). 이름/ID 확인: - - 채널 허용 목록 항목과 DM 허용 목록 항목은 토큰 액세스가 허용할 때 시작 시 확인됩니다 + - 채널 allowlist 항목과 DM allowlist 항목은 토큰 액세스가 허용할 때 시작 시 확인됩니다 - 확인되지 않은 채널 이름 항목은 구성된 상태로 유지되지만 기본적으로 라우팅에서는 무시됩니다 - - 수신 권한 부여 및 채널 라우팅은 기본적으로 ID 우선입니다. 직접 사용자 이름/슬러그 일치를 사용하려면 `channels.slack.dangerouslyAllowNameMatching: true`가 필요합니다 + - 인바운드 권한 부여와 채널 라우팅은 기본적으로 ID 우선입니다. 직접 사용자 이름/슬러그 매칭에는 `channels.slack.dangerouslyAllowNameMatching: true`가 필요합니다 - 이름 기반 키(`#channel-name` 또는 `channel-name`)는 `groupPolicy: "allowlist"`에서 일치하지 않습니다. 채널 조회는 기본적으로 ID 우선이므로 이름 기반 키는 성공적으로 라우팅되지 않으며 해당 채널의 모든 메시지는 조용히 차단됩니다. 이는 채널 키가 라우팅에 필요하지 않아 이름 기반 키가 동작하는 것처럼 보이는 `groupPolicy: "open"`과 다릅니다. + 이름 기반 키(`#channel-name` 또는 `channel-name`)는 `groupPolicy: "allowlist"`에서 매칭되지 않습니다. 채널 조회는 기본적으로 ID 우선이므로, 이름 기반 키는 절대 성공적으로 라우팅되지 않으며 해당 채널의 모든 메시지가 조용히 차단됩니다. 이는 `groupPolicy: "open"`과 다릅니다. `groupPolicy: "open"`에서는 라우팅에 채널 키가 필요하지 않으며 이름 기반 키가 작동하는 것처럼 보입니다. - 항상 Slack 채널 ID를 키로 사용하세요. 찾는 방법: Slack에서 채널을 오른쪽 클릭 → **링크 복사** — ID(`C...`)가 URL 끝에 표시됩니다. + 항상 Slack 채널 ID를 키로 사용하세요. 찾는 방법: Slack에서 채널을 마우스 오른쪽 버튼으로 클릭 → **Copy link** — ID(`C...`)가 URL 끝에 표시됩니다. - 올바름: + 올바른 예: ```json5 { @@ -551,7 +551,7 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. } ``` - 잘못됨(`groupPolicy: "allowlist"`에서 조용히 차단됨): + 잘못된 예(`groupPolicy: "allowlist"`에서 조용히 차단됨): ```json5 { @@ -569,68 +569,70 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. - + 채널 메시지는 기본적으로 멘션 게이트가 적용됩니다. 멘션 소스: - 명시적 앱 멘션(`<@botId>`) - - 멘션 정규식 패턴(`agents.list[].groupChat.mentionPatterns`, 폴백 `messages.groupChat.mentionPatterns`) - - 암시적 봇 답글 스레드 동작(`thread.requireExplicitMention`이 `true`일 때 비활성화됨) + - 멘션 정규식 패턴(`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - 암시적 봇 스레드 답장 동작(`thread.requireExplicitMention`이 `true`일 때 비활성화) - 채널별 제어(`channels.slack.channels.`; 이름은 시작 시 확인 또는 `dangerouslyAllowNameMatching`을 통해서만 가능): + 채널별 제어(`channels.slack.channels.`; 이름은 시작 시 확인 또는 `dangerouslyAllowNameMatching`을 통해서만 사용): - `requireMention` - - `users`(허용 목록) + - `users`(allowlist) - `allowBots` - `skills` - `systemPrompt` - `tools`, `toolsBySender` - `toolsBySender` 키 형식: `id:`, `e164:`, `username:`, `name:`, 또는 `"*"` 와일드카드 - (레거시 접두사 없는 키는 여전히 `id:`로만 매핑됨) + (레거시 접두사 없는 키는 여전히 `id:`에만 매핑됨) + + `allowBots`는 채널과 비공개 채널에 대해 보수적으로 동작합니다. 봇이 작성한 룸 메시지는 보내는 봇이 해당 룸의 `users` allowlist에 명시적으로 나열되어 있거나, `channels.slack.allowFrom`의 명시적 Slack 소유자 ID가 하나 이상 현재 룸 멤버일 때만 허용됩니다. 와일드카드와 표시 이름 소유자 항목은 소유자 존재 조건을 충족하지 않습니다. 소유자 존재 여부는 Slack `conversations.members`를 사용합니다. 앱에 룸 유형에 맞는 읽기 scope가 있는지 확인하세요(공개 채널은 `channels:read`, 비공개 채널은 `groups:read`). 멤버 조회가 실패하면 OpenClaw는 봇이 작성한 룸 메시지를 드롭합니다. -## 스레딩, 세션 및 답글 태그 +## 스레딩, 세션 및 답장 태그 -- DM은 `direct`로, 채널은 `channel`로, MPIM은 `group`으로 라우팅됩니다. +- DM은 `direct`로 라우팅되고, 채널은 `channel`로, MPIM은 `group`으로 라우팅됩니다. - 기본 `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` 멘션에만 봇이 응답합니다. 이 옵션이 없으면 봇이 참여한 스레드의 답장은 `requireMention` 게이트를 우회합니다. -답글 스레딩 제어: +답장 스레딩 제어: - `channels.slack.replyToMode`: `off|first|all|batched`(기본값 `off`) - `channels.slack.replyToModeByChatType`: `direct|group|channel`별 설정 -- 직접 채팅용 레거시 폴백: `channels.slack.dm.replyToMode` +- direct 채팅의 레거시 fallback: `channels.slack.dm.replyToMode` -수동 답글 태그가 지원됩니다. +수동 답장 태그가 지원됩니다. - `[[reply_to_current]]` - `[[reply_to:]]` -`replyToMode="off"`는 명시적 `[[reply_to_*]]` 태그를 포함해 Slack의 **모든** 답글 스레딩을 비활성화합니다. 이는 `"off"` 모드에서도 명시적 태그가 계속 적용되는 Telegram과 다릅니다. Slack 스레드는 채널에서 메시지를 숨기지만 Telegram 답글은 인라인으로 계속 표시됩니다. +`replyToMode="off"`는 명시적 `[[reply_to_*]]` 태그를 포함하여 Slack의 **모든** 답장 스레딩을 비활성화합니다. 이는 `"off"` 모드에서도 명시적 태그가 계속 적용되는 Telegram과 다릅니다. Slack 스레드는 메시지를 채널에서 숨기지만, Telegram 답장은 인라인으로 계속 표시됩니다. -## 확인 반응 +## Ack 반응 -`ackReaction`은 OpenClaw가 수신 메시지를 처리하는 동안 확인 이모지를 보냅니다. +`ackReaction`은 OpenClaw가 인바운드 메시지를 처리하는 동안 확인 이모지를 보냅니다. 확인 순서: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- 에이전트 식별 이모지 폴백(`agents.list[].identity.emoji`, 없으면 "👀") +- 에이전트 ID 이모지 fallback(`agents.list[].identity.emoji`, 없으면 "👀") 참고: -- Slack은 쇼트코드(예: `"eyes"`)를 기대합니다. +- Slack은 shortcode를 기대합니다(예: `"eyes"`). - Slack 계정 또는 전역에서 반응을 비활성화하려면 `""`를 사용하세요. ## 텍스트 스트리밍 @@ -639,20 +641,20 @@ Slack 작업은 `channels.slack.actions.*`로 제어됩니다. - `off`: 실시간 미리보기 스트리밍을 비활성화합니다. - `partial`(기본값): 미리보기 텍스트를 최신 부분 출력으로 대체합니다. -- `block`: 청크 미리보기 업데이트를 추가합니다. -- `progress`: 생성 중 진행 상태 텍스트를 표시한 다음 최종 텍스트를 보냅니다. -- `streaming.preview.toolProgress`: 초안 미리보기가 활성 상태일 때 도구/진행 업데이트를 같은 편집된 미리보기 메시지로 라우팅합니다(기본값: `true`). 별도 도구/진행 메시지를 유지하려면 `false`로 설정합니다. +- `block`: 청크 단위 미리보기 업데이트를 추가합니다. +- `progress`: 생성하는 동안 진행 상태 텍스트를 표시한 뒤 최종 텍스트를 보냅니다. +- `streaming.preview.toolProgress`: 초안 미리보기가 활성화되어 있을 때 도구/진행 업데이트를 같은 편집된 미리보기 메시지로 라우팅합니다(기본값: `true`). 별도의 도구/진행 메시지를 유지하려면 `false`로 설정하세요. `channels.slack.streaming.nativeTransport`는 `channels.slack.streaming.mode`가 `partial`일 때 Slack 네이티브 텍스트 스트리밍을 제어합니다(기본값: `true`). -- 네이티브 텍스트 스트리밍과 Slack 어시스턴트 스레드 상태가 표시되려면 답글 스레드를 사용할 수 있어야 합니다. 스레드 선택은 여전히 `replyToMode`를 따릅니다. -- 네이티브 스트리밍을 사용할 수 없을 때도 채널 및 그룹 채팅 루트는 일반 초안 미리보기를 사용할 수 있습니다. -- 최상위 Slack DM은 기본적으로 스레드 밖에 있으므로 스레드 스타일 미리보기를 표시하지 않습니다. 그곳에서 보이는 진행 상태가 필요하면 스레드 답글 또는 `typingReaction`을 사용하세요. -- 미디어 및 텍스트가 아닌 페이로드는 일반 전달로 폴백합니다. -- 미디어/오류 최종 응답은 대기 중인 미리보기 편집을 취소합니다. 적격 텍스트/블록 최종 응답은 미리보기를 제자리에서 편집할 수 있을 때만 플러시됩니다. -- 스트리밍이 답글 중간에 실패하면 OpenClaw는 남은 페이로드에 대해 일반 전달로 폴백합니다. +- 네이티브 텍스트 스트리밍과 Slack 어시스턴트 스레드 상태가 나타나려면 답장 스레드를 사용할 수 있어야 합니다. 스레드 선택은 여전히 `replyToMode`를 따릅니다. +- 채널 및 그룹 채팅 루트는 네이티브 스트리밍을 사용할 수 없을 때도 일반 초안 미리보기를 사용할 수 있습니다. +- 최상위 Slack DM은 기본적으로 스레드 밖에 있으므로 스레드 스타일 미리보기를 표시하지 않습니다. 그곳에서 진행 상황을 표시하려면 스레드 답장 또는 `typingReaction`을 사용하세요. +- 미디어 및 텍스트가 아닌 payload는 일반 전달로 fallback합니다. +- 미디어/오류 최종 응답은 대기 중인 미리보기 편집을 취소합니다. 적격 텍스트/블록 최종 응답은 미리보기를 제자리에서 편집할 수 있을 때만 flush됩니다. +- 스트리밍이 답장 중간에 실패하면 OpenClaw는 남은 payload에 대해 일반 전달로 fallback합니다. -Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기를 사용합니다. +Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기를 사용하세요. ```json5 { @@ -670,12 +672,12 @@ Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기를 사용 레거시 키: - `channels.slack.streamMode`(`replace | status_final | append`)는 `channels.slack.streaming.mode`로 자동 마이그레이션됩니다. -- 불리언 `channels.slack.streaming`은 `channels.slack.streaming.mode` 및 `channels.slack.streaming.nativeTransport`로 자동 마이그레이션됩니다. +- boolean `channels.slack.streaming`은 `channels.slack.streaming.mode` 및 `channels.slack.streaming.nativeTransport`로 자동 마이그레이션됩니다. - 레거시 `channels.slack.nativeStreaming`은 `channels.slack.streaming.nativeTransport`로 자동 마이그레이션됩니다. -## 입력 중 반응 폴백 +## Typing 반응 fallback -`typingReaction`은 OpenClaw가 답글을 처리하는 동안 수신 Slack 메시지에 임시 반응을 추가한 다음, 실행이 끝나면 이를 제거합니다. 이는 기본 "입력 중..." 상태 표시기를 사용하는 스레드 답글 밖에서 가장 유용합니다. +`typingReaction`은 OpenClaw가 답장을 처리하는 동안 인바운드 Slack 메시지에 임시 반응을 추가한 뒤, 실행이 끝나면 제거합니다. 이는 기본 "is typing..." 상태 표시기를 사용하는 스레드 답장 밖에서 가장 유용합니다. 확인 순서: @@ -684,43 +686,43 @@ Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기를 사용 참고: -- Slack은 쇼트코드(예: `"hourglass_flowing_sand"`)를 기대합니다. -- 반응은 최선의 노력 방식이며, 답글 또는 실패 경로가 완료된 뒤 정리가 자동으로 시도됩니다. +- Slack은 shortcode를 기대합니다(예: `"hourglass_flowing_sand"`). +- 반응은 best-effort이며 답장 또는 실패 경로가 완료된 후 정리가 자동으로 시도됩니다. -## 미디어, 청크 분할 및 전달 +## 미디어, 청킹 및 전달 - - Slack 파일 첨부는 Slack 호스팅 비공개 URL(토큰 인증 요청 흐름)에서 다운로드되어, 가져오기가 성공하고 크기 제한이 허용하면 미디어 저장소에 기록됩니다. 파일 자리표시자에는 Slack `fileId`가 포함되어 에이전트가 `download-file`로 원본 파일을 가져올 수 있습니다. + + Slack 파일 첨부는 Slack 호스팅 비공개 URL(토큰 인증 요청 흐름)에서 다운로드되어, 가져오기에 성공하고 크기 제한이 허용할 때 미디어 저장소에 기록됩니다. 파일 플레이스홀더에는 Slack `fileId`가 포함되어 에이전트가 `download-file`로 원본 파일을 가져올 수 있습니다. - 다운로드에는 제한된 유휴 및 총 시간 제한이 사용됩니다. Slack 파일 가져오기가 멈추거나 실패하면 OpenClaw는 메시지 처리를 계속하고 파일 자리표시자로 폴백합니다. + 다운로드에는 제한된 idle 및 전체 timeout이 사용됩니다. Slack 파일 검색이 멈추거나 실패하면 OpenClaw는 메시지 처리를 계속하고 파일 플레이스홀더로 fallback합니다. - 런타임 수신 크기 상한은 `channels.slack.mediaMaxMb`로 재정의하지 않는 한 기본값이 `20MB`입니다. + 런타임 인바운드 크기 상한은 `channels.slack.mediaMaxMb`로 재정의하지 않는 한 기본값이 `20MB`입니다. - - - 텍스트 청크는 `channels.slack.textChunkLimit`를 사용합니다(기본값 4000) - - `channels.slack.chunkMode="newline"`은 문단 우선 분할을 활성화합니다 - - 파일 전송은 Slack 업로드 API를 사용하며 스레드 답글(`thread_ts`)을 포함할 수 있습니다 - - 발신 미디어 상한은 구성된 경우 `channels.slack.mediaMaxMb`를 따르며, 그렇지 않으면 채널 전송은 미디어 파이프라인의 MIME 종류 기본값을 사용합니다 + + - 텍스트 청크는 `channels.slack.textChunkLimit`를 사용합니다(기본값 4000). + - `channels.slack.chunkMode="newline"`은 단락 우선 분할을 활성화합니다. + - 파일 전송은 Slack 업로드 API를 사용하며 스레드 답글(`thread_ts`)을 포함할 수 있습니다. + - 아웃바운드 미디어 상한은 구성된 경우 `channels.slack.mediaMaxMb`를 따릅니다. 그렇지 않으면 채널 전송은 미디어 파이프라인의 MIME 종류 기본값을 사용합니다. - + 선호되는 명시적 대상: - - DM의 경우 `user:` - - 채널의 경우 `channel:` + - DM에는 `user:` + - 채널에는 `channel:` - 사용자 대상으로 전송할 때 Slack DM은 Slack 대화 API를 통해 열립니다. + 사용자 대상을 향해 보낼 때 Slack DM은 Slack 대화 API를 통해 열립니다. ## 명령 및 슬래시 동작 -슬래시 명령은 Slack에 단일 구성 명령 또는 여러 네이티브 명령으로 표시됩니다. 명령 기본값을 변경하려면 `channels.slack.slashCommand`를 구성하세요. +슬래시 명령은 Slack에서 단일 구성 명령 또는 여러 네이티브 명령으로 표시됩니다. 명령 기본값을 변경하려면 `channels.slack.slashCommand`를 구성하세요. - `enabled: false` - `name: "openclaw"` @@ -731,20 +733,20 @@ Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기를 사용 /openclaw /help ``` -네이티브 명령에는 Slack 앱의 [추가 매니페스트 설정](#additional-manifest-settings)이 필요하며, 대신 전역 구성에서 `channels.slack.commands.native: true` 또는 `commands.native: true`로 활성화합니다. +네이티브 명령에는 Slack 앱의 [추가 매니페스트 설정](#additional-manifest-settings)이 필요하며, 대신 `channels.slack.commands.native: true` 또는 전역 구성의 `commands.native: true`로 활성화됩니다. -- 네이티브 명령 자동 모드는 Slack에서 **꺼져** 있으므로 `commands.native: "auto"`는 Slack 네이티브 명령을 활성화하지 않습니다. +- Slack에서는 네이티브 명령 자동 모드가 **꺼져** 있으므로 `commands.native: "auto"`는 Slack 네이티브 명령을 활성화하지 않습니다. ```txt /help ``` -네이티브 인수 메뉴는 선택한 옵션 값을 발송하기 전에 확인 모달을 표시하는 적응형 렌더링 전략을 사용합니다. +네이티브 인수 메뉴는 선택된 옵션 값을 디스패치하기 전에 확인 모달을 표시하는 적응형 렌더링 전략을 사용합니다. - 최대 5개 옵션: 버튼 블록 - 6-100개 옵션: 정적 선택 메뉴 -- 100개 초과 옵션: 인터랙티비티 옵션 핸들러를 사용할 수 있을 때 비동기 옵션 필터링이 포함된 외부 선택 -- Slack 제한 초과: 인코딩된 옵션 값은 버튼으로 대체됨 +- 100개 초과 옵션: 상호작용 옵션 핸들러를 사용할 수 있을 때 비동기 옵션 필터링이 있는 외부 선택 +- Slack 한도 초과: 인코딩된 옵션 값은 버튼으로 폴백합니다. ```txt /think @@ -752,11 +754,11 @@ Slack 네이티브 텍스트 스트리밍 대신 초안 미리보기를 사용 슬래시 세션은 `agent::slack:slash:` 같은 격리된 키를 사용하며, 여전히 `CommandTargetSessionKey`를 사용해 명령 실행을 대상 대화 세션으로 라우팅합니다. -## 인터랙티브 답장 +## 대화형 답글 -Slack은 에이전트가 작성한 인터랙티브 답장 컨트롤을 렌더링할 수 있지만, 이 기능은 기본적으로 비활성화되어 있습니다. +Slack은 에이전트가 작성한 대화형 답글 컨트롤을 렌더링할 수 있지만, 이 기능은 기본적으로 비활성화되어 있습니다. -전역으로 활성화합니다. +전역으로 활성화: ```json5 { @@ -770,7 +772,7 @@ Slack은 에이전트가 작성한 인터랙티브 답장 컨트롤을 렌더링 } ``` -또는 한 Slack 계정에만 활성화합니다. +또는 하나의 Slack 계정에만 활성화: ```json5 { @@ -788,28 +790,28 @@ 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는 잘못된 블록 페이로드를 보내는 대신 원래 텍스트 답장으로 대체합니다. +- 대화형 콜백 값은 원시 에이전트 작성 값이 아니라 OpenClaw가 생성한 불투명 토큰입니다. +- 생성된 대화형 블록이 Slack Block Kit 한도를 초과할 경우, OpenClaw는 잘못된 블록 페이로드를 보내는 대신 원래 텍스트 답글로 폴백합니다. -## Slack의 실행 승인 +## Slack의 Exec 승인 -Slack은 Web UI나 터미널로 대체하는 대신, 인터랙티브 버튼과 상호작용이 있는 네이티브 승인 클라이언트 역할을 할 수 있습니다. +Slack은 Web UI 또는 터미널로 폴백하는 대신, 대화형 버튼과 상호작용이 있는 네이티브 승인 클라이언트로 동작할 수 있습니다. -- 실행 승인은 네이티브 DM/채널 라우팅에 `channels.slack.execApprovals.*`를 사용합니다. -- 요청이 이미 Slack에 도착했고 승인 ID 종류가 `plugin:`인 경우, Plugin 승인도 동일한 Slack 네이티브 버튼 화면을 통해 처리될 수 있습니다. -- 승인자 권한 부여는 계속 적용됩니다. 승인자로 식별된 사용자만 Slack을 통해 요청을 승인하거나 거부할 수 있습니다. +- Exec 승인은 네이티브 DM/채널 라우팅에 `channels.slack.execApprovals.*`를 사용합니다. +- 요청이 이미 Slack에 도착했고 승인 ID 종류가 `plugin:`인 경우, Plugin 승인도 동일한 Slack 네이티브 버튼 표면을 통해 처리될 수 있습니다. +- 승인자 권한 부여는 여전히 적용됩니다. 승인자로 식별된 사용자만 Slack을 통해 요청을 승인하거나 거부할 수 있습니다. -이는 다른 채널과 동일한 공유 승인 버튼 화면을 사용합니다. Slack 앱 설정에서 `interactivity`가 활성화되면 승인 프롬프트가 대화에 직접 Block Kit 버튼으로 렌더링됩니다. +이는 다른 채널과 동일한 공유 승인 버튼 표면을 사용합니다. Slack 앱 설정에서 `interactivity`가 활성화되면, 승인 프롬프트가 대화에 직접 Block Kit 버튼으로 렌더링됩니다. 이 버튼이 있으면 기본 승인 UX가 됩니다. OpenClaw는 도구 결과가 채팅 승인을 사용할 수 없다고 말하거나 수동 승인이 유일한 경로일 때만 수동 `/approve` 명령을 포함해야 합니다. @@ -817,15 +819,15 @@ Slack은 Web UI나 터미널로 대체하는 대신, 인터랙티브 버튼과 구성 경로: - `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`가 설정되지 않았거나 `"auto"`이고 하나 이상의 승인자가 확인되면 Slack은 네이티브 Exec 승인을 자동으로 활성화합니다. +Slack을 네이티브 승인 클라이언트로 명시적으로 비활성화하려면 `enabled: false`를 설정하세요. 승인자가 확인될 때 네이티브 승인을 강제로 켜려면 `enabled: true`를 설정하세요. -명시적 Slack 실행 승인 구성이 없을 때의 기본 동작: +명시적인 Slack Exec 승인 구성 없이 사용하는 기본 동작: ```json5 { @@ -835,8 +837,8 @@ Slack은 `enabled`가 설정되지 않았거나 `"auto"`이고 하나 이상의 } ``` -승인자를 재정의하거나, 필터를 추가하거나, 원본 채팅 전달을 선택하려는 경우에만 -명시적인 Slack 네이티브 구성이 필요합니다. +승인자를 재정의하거나, 필터를 추가하거나, +원본 채팅 전송을 사용하려는 경우에만 명시적인 Slack 네이티브 구성이 필요합니다. ```json5 { @@ -852,37 +854,37 @@ Slack은 `enabled`가 설정되지 않았거나 `"auto"`이고 하나 이상의 } ``` -공유 `approvals.exec` 전달은 별도입니다. 실행 승인 프롬프트도 다른 채팅이나 명시적인 대역 외 대상으로 +공유 `approvals.exec` 전달은 별개입니다. Exec 승인 프롬프트를 다른 채팅 또는 명시적인 대역 외 대상으로도 라우팅해야 할 때만 사용하세요. 공유 `approvals.plugin` 전달도 -별도입니다. 해당 요청이 이미 Slack에 도착한 경우 Slack 네이티브 버튼은 여전히 Plugin 승인을 처리할 수 있습니다. +별개입니다. 이러한 요청이 이미 Slack에 도착한 경우 Slack 네이티브 버튼은 여전히 Plugin 승인을 처리할 수 있습니다. -동일 채팅 `/approve`도 이미 명령을 지원하는 Slack 채널과 DM에서 작동합니다. 전체 승인 전달 모델은 [실행 승인](/ko/tools/exec-approvals)을 참고하세요. +동일 채팅 `/approve`도 이미 명령을 지원하는 Slack 채널과 DM에서 작동합니다. 전체 승인 전달 모델은 [Exec 승인](/ko/tools/exec-approvals)을 참고하세요. ## 이벤트 및 운영 동작 -- 메시지 수정/삭제는 시스템 이벤트로 매핑됩니다. -- 스레드 브로드캐스트("Also send to channel" 스레드 답장)는 일반 사용자 메시지로 처리됩니다. +- 메시지 편집/삭제는 시스템 이벤트로 매핑됩니다. +- 스레드 브로드캐스트("채널에도 보내기" 스레드 답글)는 일반 사용자 메시지로 처리됩니다. - 반응 추가/제거 이벤트는 시스템 이벤트로 매핑됩니다. -- 멤버 참가/나가기, 채널 생성/이름 변경, 핀 추가/제거 이벤트는 시스템 이벤트로 매핑됩니다. -- `configWrites`가 활성화된 경우 `channel_id_changed`가 채널 구성 키를 마이그레이션할 수 있습니다. +- 멤버 참여/나가기, 채널 생성/이름 변경, 핀 추가/제거 이벤트는 시스템 이벤트로 매핑됩니다. +- `configWrites`가 활성화된 경우 `channel_id_changed`는 채널 구성 키를 마이그레이션할 수 있습니다. - 채널 주제/목적 메타데이터는 신뢰할 수 없는 컨텍스트로 취급되며 라우팅 컨텍스트에 주입될 수 있습니다. - 스레드 시작 메시지와 초기 스레드 기록 컨텍스트 시딩은 적용 가능한 경우 구성된 발신자 허용 목록으로 필터링됩니다. -- 블록 액션과 모달 상호작용은 풍부한 페이로드 필드가 있는 구조화된 `Slack interaction: ...` 시스템 이벤트를 내보냅니다. - - 블록 액션: 선택된 값, 레이블, 선택기 값, `workflow_*` 메타데이터 - - 라우팅된 채널 메타데이터와 양식 입력이 포함된 모달 `view_submission` 및 `view_closed` 이벤트 +- 블록 작업과 모달 상호작용은 풍부한 페이로드 필드가 포함된 구조화된 `Slack interaction: ...` 시스템 이벤트를 내보냅니다. + - 블록 작업: 선택된 값, 레이블, 선택기 값, `workflow_*` 메타데이터 + - 라우팅된 채널 메타데이터와 폼 입력이 있는 모달 `view_submission` 및 `view_closed` 이벤트 ## 구성 참조 기본 참조: [구성 참조 - Slack](/ko/gateway/config-channels#slack). - + - 모드/인증: `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`, `streaming.nativeTransport`, `streaming.preview.toolProgress` +- 전송: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - 운영/기능: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -890,11 +892,11 @@ Slack은 `enabled`가 설정되지 않았거나 `"auto"`이고 하나 이상의 ## 문제 해결 - + 순서대로 확인하세요. - `groupPolicy` - - 채널 허용 목록(`channels.slack.channels`) — **키는 이름(`#channel-name`)이 아니라 채널 ID**(`C12345678`)여야 합니다. 채널 라우팅은 기본적으로 ID 우선이므로 `groupPolicy: "allowlist"`에서 이름 기반 키는 조용히 실패합니다. ID를 찾는 방법: Slack에서 채널을 오른쪽 클릭 → **Copy link** — URL 끝의 `C...` 값이 채널 ID입니다. + - 채널 허용 목록(`channels.slack.channels`) — **키는 채널 이름(`#channel-name`)이 아니라 채널 ID**(`C12345678`)여야 합니다. 기본적으로 채널 라우팅은 ID 우선이므로 이름 기반 키는 `groupPolicy: "allowlist"`에서 조용히 실패합니다. ID를 찾으려면 Slack에서 채널을 마우스 오른쪽 버튼으로 클릭 → **링크 복사** — URL 끝의 `C...` 값이 채널 ID입니다. - `requireMention` - 채널별 `users` 허용 목록 @@ -909,14 +911,14 @@ openclaw doctor - 확인하세요. + 확인 항목: - `channels.slack.dm.enabled` - `channels.slack.dmPolicy`(또는 레거시 `channels.slack.dm.policy`) - 페어링 승인 / 허용 목록 항목 - Slack Assistant DM 이벤트: `drop message_changed`를 언급하는 상세 로그는 일반적으로 Slack이 메시지 메타데이터에서 복구 가능한 사람 발신자 없이 - 수정된 Assistant 스레드 이벤트를 보냈음을 의미합니다 + 편집된 Assistant 스레드 이벤트를 보냈음을 의미합니다. ```bash openclaw pairing list slack @@ -929,28 +931,28 @@ openclaw pairing list slack `openclaw channels status --probe --json`에 `botTokenStatus` 또는 `appTokenStatus: "configured_unavailable"`가 표시되면 Slack 계정은 - 구성되었지만 현재 런타임이 SecretRef 기반 값을 확인할 수 없었다는 뜻입니다. + 구성되었지만 현재 런타임이 SecretRef 기반 값을 확인할 수 없다는 뜻입니다. - - 검증하세요. + + 검증 항목: - - 서명 비밀 + - 서명 시크릿 - Webhook 경로 - - Slack 요청 URL(이벤트 + 인터랙티비티 + 슬래시 명령) + - Slack 요청 URL(이벤트 + 상호작용 + 슬래시 명령) - HTTP 계정별 고유한 `webhookPath` - 계정 스냅샷에 `signingSecretStatus: "configured_unavailable"`가 표시되면 - HTTP 계정은 구성되었지만 현재 런타임이 SecretRef 기반 서명 비밀을 - 확인할 수 없었다는 뜻입니다. + 계정 스냅샷에 `signingSecretStatus: "configured_unavailable"`가 표시되면, + HTTP 계정은 구성되었지만 현재 런타임이 SecretRef 기반 서명 시크릿을 + 확인할 수 없다는 뜻입니다. - 의도한 것이 무엇인지 확인하세요. + 의도한 모드가 무엇인지 확인하세요. - - Slack에 등록된 일치하는 슬래시 명령과 함께 사용하는 네이티브 명령 모드(`channels.slack.commands.native: true`) + - Slack에 등록된 일치하는 슬래시 명령이 있는 네이티브 명령 모드(`channels.slack.commands.native: true`) - 또는 단일 슬래시 명령 모드(`channels.slack.slashCommand.enabled: true`) `commands.useAccessGroups`와 채널/사용자 허용 목록도 확인하세요. @@ -960,74 +962,74 @@ openclaw pairing list slack ## 첨부 파일 비전 참조 -Slack 파일 다운로드가 성공하고 크기 제한이 허용하는 경우 Slack은 다운로드한 미디어를 에이전트 턴에 첨부할 수 있습니다. 이미지 파일은 미디어 이해 경로를 통과하거나 비전 기능이 있는 답장 모델로 직접 전달될 수 있습니다. 다른 파일은 이미지 입력으로 처리되지 않고 다운로드 가능한 파일 컨텍스트로 유지됩니다. +Slack 파일 다운로드가 성공하고 크기 제한이 허용되면 Slack은 다운로드된 미디어를 에이전트 턴에 첨부할 수 있습니다. 이미지 파일은 미디어 이해 경로를 통하거나 비전 지원 답글 모델에 직접 전달될 수 있습니다. 다른 파일은 이미지 입력으로 처리되지 않고 다운로드 가능한 파일 컨텍스트로 유지됩니다. ### 지원되는 미디어 유형 -| 미디어 유형 | 소스 | 현재 동작 | 참고 | +| 미디어 유형 | 소스 | 현재 동작 | 참고 | | ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| JPEG / PNG / GIF / WebP 이미지 | Slack 파일 URL | 다운로드되어 비전 기능이 있는 처리를 위해 턴에 첨부됨 | 파일별 제한: `channels.slack.mediaMaxMb`(기본값 20 MB) | +| JPEG / PNG / GIF / WebP 이미지 | Slack 파일 URL | 다운로드되어 비전 지원 처리를 위해 턴에 첨부됨 | 파일별 상한: `channels.slack.mediaMaxMb`(기본값 20 MB) | | PDF 파일 | Slack 파일 URL | 다운로드되어 `download-file` 또는 `pdf` 같은 도구의 파일 컨텍스트로 노출됨 | Slack 인바운드는 PDF를 이미지 비전 입력으로 자동 변환하지 않음 | | 기타 파일 | Slack 파일 URL | 가능한 경우 다운로드되어 파일 컨텍스트로 노출됨 | 바이너리 파일은 이미지 입력으로 처리되지 않음 | -| 스레드 답장 | 스레드 시작 파일 | 답장에 직접 미디어가 없을 때 루트 메시지 파일을 컨텍스트로 하이드레이션할 수 있음 | 파일만 있는 시작 메시지는 첨부 파일 플레이스홀더를 사용함 | -| 다중 이미지 메시지 | 여러 Slack 파일 | 각 파일은 독립적으로 평가됨 | Slack 처리는 메시지당 8개 파일로 제한됨 | +| 스레드 답글 | 스레드 시작 파일 | 답글에 직접 미디어가 없을 때 루트 메시지 파일을 컨텍스트로 하이드레이션할 수 있음 | 파일만 있는 시작 메시지는 첨부 파일 플레이스홀더를 사용함 | +| 여러 이미지 메시지 | 여러 Slack 파일 | 각 파일은 독립적으로 평가됨 | Slack 처리는 메시지당 8개 파일로 제한됨 | ### 인바운드 파이프라인 파일 첨부가 있는 Slack 메시지가 도착하면: -1. OpenClaw는 봇 토큰(`xoxb-...`)을 사용해 Slack의 비공개 URL에서 파일을 다운로드합니다. -2. 성공 시 파일은 미디어 저장소에 기록됩니다. -3. 다운로드한 미디어 경로와 콘텐츠 유형이 인바운드 컨텍스트에 추가됩니다. -4. 이미지 기능이 있는 모델/도구 경로는 해당 컨텍스트의 이미지 첨부 파일을 사용할 수 있습니다. +1. OpenClaw은 봇 토큰(`xoxb-...`)을 사용해 Slack의 비공개 URL에서 파일을 다운로드합니다. +2. 성공하면 파일이 미디어 저장소에 기록됩니다. +3. 다운로드된 미디어 경로와 콘텐츠 유형이 인바운드 컨텍스트에 추가됩니다. +4. 이미지를 처리할 수 있는 모델/도구 경로는 해당 컨텍스트의 이미지 첨부 파일을 사용할 수 있습니다. 5. 이미지가 아닌 파일은 이를 처리할 수 있는 도구를 위해 파일 메타데이터 또는 미디어 참조로 계속 사용할 수 있습니다. ### 스레드 루트 첨부 파일 상속 메시지가 스레드에 도착하면(`thread_ts` 부모가 있음): -- 답장 자체에 직접 미디어가 없고 포함된 루트 메시지에 파일이 있는 경우, Slack은 루트 파일을 스레드 시작 컨텍스트로 하이드레이션할 수 있습니다. -- 직접 답장 첨부 파일은 루트 메시지 첨부 파일보다 우선합니다. -- 파일만 있고 텍스트가 없는 루트 메시지는 폴백이 여전히 해당 파일을 포함할 수 있도록 첨부 파일 플레이스홀더로 표현됩니다. +- 답글 자체에 직접 미디어가 없고 포함된 루트 메시지에 파일이 있으면, Slack은 루트 파일을 스레드 시작 컨텍스트로 하이드레이션할 수 있습니다. +- 직접 답글 첨부 파일이 루트 메시지 첨부 파일보다 우선합니다. +- 파일만 있고 텍스트가 없는 루트 메시지는 첨부 파일 자리표시자로 표현되어 폴백이 해당 파일을 계속 포함할 수 있습니다. -### 다중 첨부 파일 처리 +### 여러 첨부 파일 처리 -단일 Slack 메시지에 여러 파일 첨부가 포함된 경우: +하나의 Slack 메시지에 여러 파일 첨부가 포함된 경우: - 각 첨부 파일은 미디어 파이프라인을 통해 독립적으로 처리됩니다. - 다운로드된 미디어 참조는 메시지 컨텍스트에 집계됩니다. -- 처리 순서는 이벤트 페이로드에서 Slack의 파일 순서를 따릅니다. -- 한 첨부 파일의 다운로드 실패는 다른 첨부 파일을 차단하지 않습니다. +- 처리 순서는 이벤트 페이로드의 Slack 파일 순서를 따릅니다. +- 하나의 첨부 파일 다운로드 실패가 다른 첨부 파일을 차단하지 않습니다. ### 크기, 다운로드 및 모델 제한 -- **크기 상한**: 기본값은 파일당 20 MB입니다. `channels.slack.mediaMaxMb`로 구성할 수 있습니다. -- **다운로드 실패**: Slack에서 제공할 수 없는 파일, 만료된 URL, 접근할 수 없는 파일, 초과 크기 파일, Slack 인증/로그인 HTML 응답은 지원되지 않는 형식으로 보고되지 않고 건너뜁니다. -- **비전 모델**: 이미지 분석은 활성 응답 모델이 비전을 지원하는 경우 해당 모델을 사용하고, 그렇지 않으면 `agents.defaults.imageModel`에 구성된 이미지 모델을 사용합니다. +- **크기 제한**: 기본값은 파일당 20 MB입니다. `channels.slack.mediaMaxMb`로 구성할 수 있습니다. +- **다운로드 실패**: Slack이 제공할 수 없는 파일, 만료된 URL, 접근할 수 없는 파일, 크기 제한을 초과한 파일, Slack 인증/로그인 HTML 응답은 지원되지 않는 형식으로 보고되지 않고 건너뜁니다. +- **비전 모델**: 이미지 분석은 비전을 지원하는 경우 활성 답글 모델을 사용하거나, `agents.defaults.imageModel`에 구성된 이미지 모델을 사용합니다. ### 알려진 제한 | 시나리오 | 현재 동작 | 해결 방법 | | -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| 만료된 Slack 파일 URL | 파일을 건너뜁니다. 오류는 표시되지 않습니다 | Slack에서 파일을 다시 업로드합니다 | -| 비전 모델이 구성되지 않음 | 이미지 첨부 파일은 미디어 참조로 저장되지만 이미지로 분석되지는 않습니다 | `agents.defaults.imageModel`을 구성하거나 비전 지원 응답 모델을 사용합니다 | -| 매우 큰 이미지(기본값 기준 > 20 MB) | 크기 상한에 따라 건너뜁니다 | Slack에서 허용하는 경우 `channels.slack.mediaMaxMb`를 늘립니다 | +| 만료된 Slack 파일 URL | 파일을 건너뜁니다. 오류는 표시되지 않습니다 | Slack에 파일을 다시 업로드합니다 | +| 비전 모델이 구성되지 않음 | 이미지 첨부 파일은 미디어 참조로 저장되지만 이미지로 분석되지 않습니다 | `agents.defaults.imageModel`을 구성하거나 비전을 지원하는 답글 모델을 사용합니다 | +| 매우 큰 이미지(기본값 기준 > 20 MB) | 크기 제한에 따라 건너뜁니다 | Slack이 허용하는 경우 `channels.slack.mediaMaxMb`를 늘립니다 | | 전달/공유된 첨부 파일 | 텍스트 및 Slack 호스팅 이미지/파일 미디어는 최선의 방식으로 처리됩니다 | OpenClaw 스레드에서 직접 다시 공유합니다 | -| PDF 첨부 파일 | 파일/미디어 컨텍스트로 저장되며 이미지 비전을 통해 자동 라우팅되지 않습니다 | 파일 메타데이터에는 `download-file`을 사용하거나 PDF 분석에는 `pdf` 도구를 사용합니다 | +| PDF 첨부 파일 | 파일/미디어 컨텍스트로 저장되며, 이미지 비전을 통해 자동으로 라우팅되지 않습니다 | 파일 메타데이터에는 `download-file`을 사용하거나 PDF 분석에는 `pdf` 도구를 사용합니다 | ### 관련 문서 - [미디어 이해 파이프라인](/ko/nodes/media-understanding) - [PDF 도구](/ko/tools/pdf) -- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 첨부 파일 비전 활성화 +- 에픽: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 첨부 파일 비전 활성화 - 회귀 테스트: [#51353](https://github.com/openclaw/openclaw/issues/51353) - 라이브 검증: [#51354](https://github.com/openclaw/openclaw/issues/51354) -## 관련 항목 +## 관련 - Slack 사용자를 Gateway와 페어링합니다. + Slack 사용자를 Gateway에 페어링합니다. 채널 및 그룹 DM 동작입니다. @@ -1036,12 +1038,12 @@ Slack 파일 다운로드가 성공하고 크기 제한이 허용하는 경우 S 인바운드 메시지를 에이전트로 라우팅합니다. - 위협 모델 및 강화입니다. + 위협 모델과 강화입니다. - 구성 레이아웃 및 우선순위입니다. + 구성 레이아웃과 우선순위입니다. - 명령 카탈로그 및 동작입니다. + 명령 카탈로그와 동작입니다. diff --git a/docs/ko/channels/telegram.md b/docs/ko/channels/telegram.md index 913a8385c..948d04561 100644 --- a/docs/ko/channels/telegram.md +++ b/docs/ko/channels/telegram.md @@ -1,27 +1,27 @@ --- read_when: - Telegram 기능 또는 Webhook 작업하기 -summary: Telegram 봇 지원 상태, 기능 및 설정 +summary: Telegram 봇 지원 상태, 기능 및 구성 title: Telegram x-i18n: - generated_at: "2026-04-30T06:19:44Z" + generated_at: "2026-04-30T16:27:36Z" model: gpt-5.5 provider: openai - source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7 + source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd source_path: channels/telegram.md workflow: 16 --- -grammY를 통해 봇 DM과 그룹에서 프로덕션 준비가 완료되어 있습니다. 기본 모드는 롱 폴링이며, Webhook 모드는 선택 사항입니다. +프로덕션 환경에서 grammY를 통해 봇 DM과 그룹에 사용할 준비가 되어 있습니다. 롱 폴링이 기본 모드이며 Webhook 모드는 선택 사항입니다. - + Telegram의 기본 DM 정책은 페어링입니다. - + 교차 채널 진단 및 복구 플레이북입니다. - + 전체 채널 구성 패턴과 예시입니다. @@ -29,14 +29,14 @@ grammY를 통해 봇 DM과 그룹에서 프로덕션 준비가 완료되어 있 ## 빠른 설정 - - Telegram을 열고 **@BotFather**와 대화하세요(핸들이 정확히 `@BotFather`인지 확인하세요). + + Telegram을 열고 **@BotFather**와 채팅합니다(핸들이 정확히 `@BotFather`인지 확인). - `/newbot`을 실행하고, 안내에 따라 진행한 뒤 토큰을 저장하세요. + `/newbot`을 실행하고 안내를 따른 뒤 토큰을 저장합니다. - + ```json5 { @@ -51,12 +51,12 @@ grammY를 통해 봇 DM과 그룹에서 프로덕션 준비가 완료되어 있 } ``` - 환경 변수 폴백: `TELEGRAM_BOT_TOKEN=...`(기본 계정에만 적용). - Telegram은 `openclaw channels login telegram`을 사용하지 **않습니다**. 구성/환경 변수에 토큰을 설정한 뒤 Gateway를 시작하세요. + Env 대체값: `TELEGRAM_BOT_TOKEN=...`(기본 계정만 해당). + Telegram은 `openclaw channels login telegram`을 사용하지 **않습니다**. config/env에 토큰을 구성한 다음 Gateway를 시작하세요. - + ```bash openclaw gateway @@ -68,115 +68,115 @@ openclaw pairing approve telegram - - 봇을 그룹에 추가한 다음, 액세스 모델에 맞게 `channels.telegram.groups`와 `groupPolicy`를 설정하세요. + + 그룹에 봇을 추가한 다음, 접근 모델에 맞게 `channels.telegram.groups`와 `groupPolicy`를 설정합니다. -토큰 확인 순서는 계정을 인식합니다. 실제로는 구성 값이 환경 변수 폴백보다 우선하며, `TELEGRAM_BOT_TOKEN`은 기본 계정에만 적용됩니다. +토큰 확인 순서는 계정을 인식합니다. 실제로는 config 값이 env 대체값보다 우선하며, `TELEGRAM_BOT_TOKEN`은 기본 계정에만 적용됩니다. -## Telegram 측 설정 +## Telegram 쪽 설정 - - Telegram 봇은 기본적으로 **개인정보 보호 모드**를 사용하며, 이 모드는 봇이 수신하는 그룹 메시지를 제한합니다. + + Telegram 봇은 기본적으로 **개인정보 보호 모드**를 사용하며, 이로 인해 봇이 수신하는 그룹 메시지가 제한됩니다. - 봇이 모든 그룹 메시지를 봐야 한다면 다음 중 하나를 수행하세요. + 봇이 모든 그룹 메시지를 확인해야 하는 경우 다음 중 하나를 수행하세요. - `/setprivacy`로 개인정보 보호 모드를 비활성화하거나 - - 봇을 그룹 관리자로 만드세요. + - 봇을 그룹 관리자로 지정합니다. 개인정보 보호 모드를 전환할 때는 Telegram이 변경 사항을 적용하도록 각 그룹에서 봇을 제거한 뒤 다시 추가하세요. - - 관리자 상태는 Telegram 그룹 설정에서 제어됩니다. + + 관리자 상태는 Telegram 그룹 설정에서 제어합니다. - 관리자 봇은 모든 그룹 메시지를 수신하므로, 항상 켜진 그룹 동작에 유용합니다. + 관리자 봇은 모든 그룹 메시지를 수신하므로, 항상 켜져 있는 그룹 동작에 유용합니다. - + - 그룹 추가를 허용/거부하려면 `/setjoingroups` - - 그룹 표시 동작에는 `/setprivacy` + - 그룹 표시 범위 동작에는 `/setprivacy` -## 액세스 제어 및 활성화 +## 접근 제어 및 활성화 - - `channels.telegram.dmPolicy`는 직접 메시지 액세스를 제어합니다. + + `channels.telegram.dmPolicy`는 다이렉트 메시지 접근을 제어합니다. - `pairing`(기본값) - - `allowlist`(`allowFrom`에 발신자 ID가 하나 이상 필요) - - `open`(`allowFrom`에 `"*"`가 포함되어야 함) + - `allowlist`(`allowFrom`에 하나 이상의 발신자 ID 필요) + - `open`(`allowFrom`에 `"*"` 포함 필요) - `disabled` - `dmPolicy: "open"`과 `allowFrom: ["*"]`를 함께 사용하면 봇 사용자 이름을 찾거나 추측한 모든 Telegram 계정이 봇에 명령을 보낼 수 있습니다. 도구가 엄격히 제한된 의도적으로 공개된 봇에만 사용하세요. 단일 소유자 봇은 숫자 사용자 ID와 함께 `allowlist`를 사용해야 합니다. + `dmPolicy: "open"`과 `allowFrom: ["*"]`를 함께 사용하면 봇 사용자 이름을 찾거나 추측한 모든 Telegram 계정이 봇에 명령을 내릴 수 있습니다. 엄격하게 제한된 도구를 갖춘 의도적으로 공개된 봇에만 사용하세요. 단일 소유자 봇은 숫자 사용자 ID와 함께 `allowlist`를 사용해야 합니다. `channels.telegram.allowFrom`은 숫자 Telegram 사용자 ID를 허용합니다. `telegram:` / `tg:` 접두사는 허용되며 정규화됩니다. - 다중 계정 구성에서는 제한적인 최상위 `channels.telegram.allowFrom`이 안전 경계로 취급됩니다. 계정 수준의 `allowFrom: ["*"]` 항목은 병합 후 유효한 계정 허용 목록에 명시적 와일드카드가 여전히 포함되어 있지 않은 한 해당 계정을 공개로 만들지 않습니다. - 빈 `allowFrom`과 함께 `dmPolicy: "allowlist"`를 사용하면 모든 DM이 차단되며 구성 검증에서 거부됩니다. - 설정 과정에서는 숫자 사용자 ID만 요청합니다. - 업그레이드 후 구성에 `@username` 허용 목록 항목이 포함되어 있다면 `openclaw doctor --fix`를 실행해 이를 확인하세요(최선 노력 방식이며 Telegram 봇 토큰이 필요합니다). - 이전에 페어링 저장소 허용 목록 파일에 의존했다면, `openclaw doctor --fix`는 허용 목록 흐름에서 항목을 `channels.telegram.allowFrom`으로 복구할 수 있습니다(예: `dmPolicy: "allowlist"`에 아직 명시적 ID가 없는 경우). + 다중 계정 config에서 제한적인 최상위 `channels.telegram.allowFrom`은 안전 경계로 처리됩니다. 계정 수준 `allowFrom: ["*"]` 항목은 병합 후 유효 계정 allowlist에 명시적 와일드카드가 여전히 포함된 경우가 아니면 해당 계정을 공개로 만들지 않습니다. + 빈 `allowFrom`과 함께 `dmPolicy: "allowlist"`를 사용하면 모든 DM이 차단되며 config 검증에서 거부됩니다. + 설정에서는 숫자 사용자 ID만 요청합니다. + 업그레이드했으며 config에 `@username` allowlist 항목이 포함되어 있다면 `openclaw doctor --fix`를 실행해 이를 확인하세요(최선의 노력 방식이며 Telegram 봇 토큰 필요). + 이전에 페어링 저장소 allowlist 파일에 의존했다면, `openclaw doctor --fix`가 allowlist 흐름에서 항목을 `channels.telegram.allowFrom`으로 복구할 수 있습니다(예: `dmPolicy: "allowlist"`에 아직 명시적 ID가 없는 경우). - 단일 소유자 봇의 경우, 이전 페어링 승인에 의존하지 않고 액세스 정책을 구성에 지속적으로 유지하려면 명시적인 숫자 `allowFrom` ID와 함께 `dmPolicy: "allowlist"`를 사용하는 것을 권장합니다. + 단일 소유자 봇의 경우 이전 페어링 승인에 의존하지 않고 접근 정책을 config에 지속적으로 유지하려면 명시적 숫자 `allowFrom` ID와 함께 `dmPolicy: "allowlist"`를 선호하세요. - 흔한 혼동: DM 페어링 승인이 "이 발신자는 어디서나 인증됨"을 의미하지 않습니다. - 페어링은 DM 액세스를 부여합니다. 명령 소유자가 아직 없는 경우, 처음 승인된 페어링은 소유자 전용 명령과 실행 승인에 명시적 운영자 계정이 있도록 `commands.ownerAllowFrom`도 설정합니다. - 그룹 발신자 인증은 여전히 명시적 구성 허용 목록에서 옵니다. - "한 번 인증되면 DM과 그룹 명령이 모두 작동"하게 하려면 숫자 Telegram 사용자 ID를 `channels.telegram.allowFrom`에 넣으세요. 소유자 전용 명령의 경우 `commands.ownerAllowFrom`에 `telegram:`가 포함되어 있는지 확인하세요. + 흔한 혼동: DM 페어링 승인이 "이 발신자는 모든 곳에서 승인됨"을 의미하지는 않습니다. + 페어링은 DM 접근을 부여합니다. 아직 명령 소유자가 없는 경우, 처음 승인된 페어링은 소유자 전용 명령과 exec 승인에 명시적 운영자 계정이 있도록 `commands.ownerAllowFrom`도 설정합니다. + 그룹 발신자 승인은 여전히 명시적 config allowlist에서 가져옵니다. + "한 번 승인되면 DM과 그룹 명령이 모두 작동"하기를 원한다면 숫자 Telegram 사용자 ID를 `channels.telegram.allowFrom`에 넣으세요. 소유자 전용 명령의 경우 `commands.ownerAllowFrom`에 `telegram:`가 포함되어 있는지 확인하세요. ### Telegram 사용자 ID 찾기 - 더 안전한 방법(타사 봇 없음): + 더 안전한 방법(서드파티 봇 없음): - 1. 봇에게 DM을 보냅니다. + 1. 봇에 DM을 보냅니다. 2. `openclaw logs --follow`를 실행합니다. 3. `from.id`를 읽습니다. - 공식 Bot API 방법: + 공식 Bot API 방식: ```bash curl "https://api.telegram.org/bot/getUpdates" ``` - 타사 방법(개인정보 보호 수준 낮음): `@userinfobot` 또는 `@getidsbot`. + 서드파티 방식(개인정보 보호 수준 낮음): `@userinfobot` 또는 `@getidsbot`. - + 두 가지 제어가 함께 적용됩니다. 1. **허용되는 그룹**(`channels.telegram.groups`) - - `groups` 구성이 없는 경우: - - `groupPolicy: "open"`이면: 모든 그룹이 그룹 ID 검사를 통과할 수 있습니다. - - `groupPolicy: "allowlist"`(기본값)이면: `groups` 항목(또는 `"*"`)을 추가할 때까지 그룹이 차단됩니다. - - `groups`가 구성된 경우: 허용 목록처럼 동작합니다(명시적 ID 또는 `"*"`). + - `groups` config 없음: + - `groupPolicy: "open"`: 모든 그룹이 그룹 ID 검사를 통과할 수 있음 + - `groupPolicy: "allowlist"`(기본값): `groups` 항목(또는 `"*"`)을 추가할 때까지 그룹 차단 + - `groups` 구성됨: allowlist로 동작(명시적 ID 또는 `"*"`) 2. **그룹에서 허용되는 발신자**(`channels.telegram.groupPolicy`) - `open` - `allowlist`(기본값) - `disabled` - `groupAllowFrom`은 그룹 발신자 필터링에 사용됩니다. 설정되지 않은 경우 Telegram은 `allowFrom`으로 폴백합니다. + `groupAllowFrom`은 그룹 발신자 필터링에 사용됩니다. 설정되지 않으면 Telegram은 `allowFrom`으로 대체합니다. `groupAllowFrom` 항목은 숫자 Telegram 사용자 ID여야 합니다(`telegram:` / `tg:` 접두사는 정규화됨). - Telegram 그룹 또는 슈퍼그룹 채팅 ID를 `groupAllowFrom`에 넣지 마세요. 음수 채팅 ID는 `channels.telegram.groups` 아래에 속합니다. - 숫자가 아닌 항목은 발신자 인증에서 무시됩니다. + Telegram 그룹 또는 슈퍼그룹 채팅 ID를 `groupAllowFrom`에 넣지 마세요. 음수 채팅 ID는 `channels.telegram.groups` 아래에 둡니다. + 숫자가 아닌 항목은 발신자 승인에서 무시됩니다. 보안 경계(`2026.2.25+`): 그룹 발신자 인증은 DM 페어링 저장소 승인을 상속하지 **않습니다**. 페어링은 DM 전용으로 유지됩니다. 그룹의 경우 `groupAllowFrom` 또는 그룹별/토픽별 `allowFrom`을 설정하세요. - `groupAllowFrom`이 설정되지 않은 경우 Telegram은 페어링 저장소가 아니라 구성의 `allowFrom`으로 폴백합니다. - 단일 소유자 봇의 실용적인 패턴: 사용자 ID를 `channels.telegram.allowFrom`에 설정하고, `groupAllowFrom`은 설정하지 않은 채 대상 그룹을 `channels.telegram.groups` 아래에서 허용하세요. - 런타임 참고: `channels.telegram`이 완전히 없으면, `channels.defaults.groupPolicy`가 명시적으로 설정되지 않은 한 런타임은 기본적으로 실패 폐쇄형 `groupPolicy="allowlist"`를 사용합니다. + `groupAllowFrom`이 설정되지 않은 경우 Telegram은 페어링 저장소가 아니라 config `allowFrom`으로 대체합니다. + 단일 소유자 봇의 실용적인 패턴: 사용자 ID를 `channels.telegram.allowFrom`에 설정하고, `groupAllowFrom`은 설정하지 않은 채 대상 그룹을 `channels.telegram.groups` 아래에 허용합니다. + 런타임 참고: `channels.telegram`이 완전히 누락된 경우, `channels.defaults.groupPolicy`가 명시적으로 설정되지 않는 한 런타임은 실패 시 닫히는 `groupPolicy="allowlist"`를 기본값으로 사용합니다. - 예시: 특정 그룹 하나에서 모든 구성원 허용: + 예시: 특정 그룹 하나에서 모든 멤버 허용: ```json5 { @@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 예시: 특정 그룹 하나 안에서 특정 사용자만 허용: + 예시: 특정 그룹 하나에서 특정 사용자만 허용: ```json5 { @@ -211,18 +211,18 @@ curl "https://api.telegram.org/bot/getUpdates" ``` - 흔한 실수: `groupAllowFrom`은 Telegram 그룹 허용 목록이 아닙니다. + 흔한 실수: `groupAllowFrom`은 Telegram 그룹 allowlist가 아닙니다. - `-1001234567890` 같은 음수 Telegram 그룹 또는 슈퍼그룹 채팅 ID는 `channels.telegram.groups` 아래에 넣으세요. - 허용된 그룹 안에서 어떤 사람이 봇을 트리거할 수 있는지 제한하려면 `8734062810` 같은 Telegram 사용자 ID를 `groupAllowFrom` 아래에 넣으세요. - - 허용된 그룹의 모든 구성원이 봇과 대화할 수 있게 하려는 경우에만 `groupAllowFrom: ["*"]`를 사용하세요. + - 허용된 그룹의 모든 멤버가 봇과 대화할 수 있기를 원할 때만 `groupAllowFrom: ["*"]`를 사용하세요. - - 그룹 응답은 기본적으로 멘션이 필요합니다. + + 그룹 답장은 기본적으로 멘션이 필요합니다. 멘션은 다음에서 올 수 있습니다. @@ -236,9 +236,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `/activation always` - `/activation mention` - 이는 세션 상태만 업데이트합니다. 지속성을 위해서는 구성을 사용하세요. + 이는 세션 상태만 업데이트합니다. 지속성을 위해서는 config를 사용하세요. - 지속 구성 예시: + 지속 config 예시: ```json5 { @@ -254,7 +254,7 @@ curl "https://api.telegram.org/bot/getUpdates" 그룹 채팅 ID 가져오기: - - 그룹 메시지를 `@userinfobot` / `@getidsbot`로 전달 + - 그룹 메시지를 `@userinfobot` / `@getidsbot`으로 전달 - 또는 `openclaw logs --follow`에서 `chat.id` 읽기 - 또는 Bot API `getUpdates` 검사 @@ -264,20 +264,20 @@ curl "https://api.telegram.org/bot/getUpdates" ## 런타임 동작 - Telegram은 Gateway 프로세스가 소유합니다. -- 라우팅은 결정적입니다. Telegram 인바운드는 Telegram으로 응답합니다(모델이 채널을 선택하지 않습니다). -- 인바운드 메시지는 응답 메타데이터와 미디어 플레이스홀더가 포함된 공유 채널 엔벨로프로 정규화됩니다. +- 라우팅은 결정적입니다. Telegram 인바운드는 Telegram으로 답장합니다(모델은 채널을 선택하지 않음). +- 인바운드 메시지는 답장 메타데이터와 미디어 자리 표시자를 포함한 공유 채널 엔벌로프로 정규화됩니다. - 그룹 세션은 그룹 ID로 격리됩니다. 포럼 토픽은 토픽을 격리하기 위해 `:topic:`를 추가합니다. -- DM 메시지는 `message_thread_id`를 포함할 수 있습니다. OpenClaw는 스레드 인식 세션 키로 이를 라우팅하고 응답을 위해 스레드 ID를 보존합니다. -- 롱 폴링은 채팅별/스레드별 순서를 지정하는 grammY 러너를 사용합니다. 전체 러너 싱크 동시성은 `agents.defaults.maxConcurrent`를 사용합니다. -- 롱 폴링은 각 Gateway 프로세스 내부에서 보호되므로 한 번에 하나의 활성 폴러만 봇 토큰을 사용할 수 있습니다. 여전히 `getUpdates` 409 충돌이 보인다면 다른 OpenClaw Gateway, 스크립트 또는 외부 폴러가 같은 토큰을 사용하고 있을 가능성이 큽니다. -- 롱 폴링 감시자 재시작은 기본적으로 완료된 `getUpdates` 활성 상태가 120초 동안 없을 때 트리거됩니다. 긴 작업 중에도 배포 환경에서 잘못된 폴링 정지 재시작이 계속 발생하는 경우에만 `channels.telegram.pollingStallThresholdMs`를 늘리세요. 값은 밀리초 단위이며 `30000`부터 `600000`까지 허용됩니다. 계정별 오버라이드도 지원됩니다. -- Telegram Bot API는 읽음 확인을 지원하지 않습니다(`sendReadReceipts`는 적용되지 않음). +- DM 메시지는 `message_thread_id`를 포함할 수 있습니다. OpenClaw는 스레드 인식 세션 키로 이를 라우팅하고 답장을 위해 스레드 ID를 보존합니다. +- 롱 폴링은 채팅별/스레드별 순서 지정과 함께 grammY runner를 사용합니다. 전체 runner 싱크 동시성은 `agents.defaults.maxConcurrent`를 사용합니다. +- 롱 폴링은 각 Gateway 프로세스 내부에서 보호되므로 한 번에 하나의 활성 poller만 봇 토큰을 사용할 수 있습니다. 여전히 `getUpdates` 409 충돌이 보인다면 다른 OpenClaw Gateway, 스크립트 또는 외부 poller가 같은 토큰을 사용 중일 가능성이 높습니다. +- 롱 폴링 watchdog 재시작은 기본적으로 완료된 `getUpdates` 활성 상태가 120초 동안 없으면 트리거됩니다. 배포 환경에서 장시간 실행 작업 중에도 잘못된 폴링 중단 재시작이 계속 발생하는 경우에만 `channels.telegram.pollingStallThresholdMs`를 늘리세요. 값은 밀리초 단위이며 `30000`부터 `600000`까지 허용됩니다. 계정별 재정의가 지원됩니다. +- Telegram Bot API에는 읽음 확인 지원이 없습니다(`sendReadReceipts`는 적용되지 않음). ## 기능 참조 - - OpenClaw는 부분 응답을 실시간으로 스트리밍할 수 있습니다. + + OpenClaw는 부분 답장을 실시간으로 스트리밍할 수 있습니다. - 직접 채팅: 미리보기 메시지 + `editMessageText` - 그룹/토픽: 미리보기 메시지 + `editMessageText` @@ -286,10 +286,10 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.streaming`은 `off | partial | block | progress`입니다(기본값: `partial`). - Telegram에서 `progress`는 `partial`로 매핑됩니다(교차 채널 명명과의 호환성). - - `streaming.preview.toolProgress`는 도구/진행 상태 업데이트가 동일한 편집된 미리보기 메시지를 재사용할지 제어합니다(기본값: 미리보기 스트리밍이 활성화된 경우 `true`). + - `streaming.preview.toolProgress`는 도구/진행 상황 업데이트가 동일한 편집된 미리보기 메시지를 재사용할지 제어합니다(기본값: 미리보기 스트리밍이 활성화된 경우 `true`). - 레거시 `channels.telegram.streamMode`와 불리언 `streaming` 값은 감지됩니다. 이를 `channels.telegram.streaming.mode`로 마이그레이션하려면 `openclaw doctor --fix`를 실행하세요. - 도구 진행 미리보기 업데이트는 도구가 실행되는 동안 표시되는 짧은 "작업 중..." 줄입니다. 예를 들어 명령 실행, 파일 읽기, 계획 업데이트 또는 패치 요약이 있습니다. Telegram은 `v2026.4.22` 이상에서 릴리스된 OpenClaw 동작과 일치하도록 이를 기본적으로 활성화 상태로 유지합니다. 응답 텍스트에는 편집된 미리보기를 유지하되 도구 진행 줄은 숨기려면 다음을 설정하세요. + 도구 진행 상황 미리보기 업데이트는 도구가 실행되는 동안 표시되는 짧은 "Working..." 줄입니다. 예를 들어 명령 실행, 파일 읽기, 계획 업데이트 또는 패치 요약이 있습니다. Telegram은 `v2026.4.22` 및 이후 버전의 출시된 OpenClaw 동작과 일치하도록 이를 기본적으로 활성화합니다. 답변 텍스트용 편집 미리보기는 유지하되 도구 진행 상황 줄은 숨기려면 다음과 같이 설정하세요. ```json { @@ -306,18 +306,16 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 최종 응답만 전달하려는 경우에만 `streaming.mode: "off"`를 사용하세요. Telegram 미리보기 편집이 비활성화되고, 일반 도구/진행 상태 메시지는 독립형 "작업 중..." 메시지로 전송되는 대신 억제됩니다. 승인 프롬프트, 미디어 페이로드, 오류는 여전히 일반 최종 전달 경로를 통해 라우팅됩니다. 도구 진행 상태 줄을 숨기면서 응답 미리보기 편집만 유지하려면 `streaming.preview.toolProgress: false`를 사용하세요. + 최종 전달만 원할 때만 `streaming.mode: "off"`를 사용하세요. Telegram 미리보기 편집이 비활성화되고, 일반 도구/진행 상황 잡담은 독립 실행형 "Working..." 메시지로 전송되는 대신 억제됩니다. 승인 프롬프트, 미디어 페이로드 및 오류는 여전히 일반 최종 전달을 통해 라우팅됩니다. 도구 진행 상황 상태 줄을 숨기면서 답변 미리보기 편집만 유지하려면 `streaming.preview.toolProgress: false`를 사용하세요. - 텍스트 전용 응답의 경우: + 텍스트 전용 답장의 경우: - - 짧은 DM/그룹/토픽 미리보기: OpenClaw는 같은 미리보기 메시지를 유지하고 마지막에 제자리에서 최종 편집을 수행합니다 - - 약 1분보다 오래된 미리보기: OpenClaw는 완료된 답변을 새 최종 메시지로 보내고 미리보기를 정리하므로, Telegram의 표시 타임스탬프가 미리보기 생성 시간이 아니라 완료 시간을 반영합니다 + - 짧은 DM/그룹/토픽 미리보기: OpenClaw는 같은 미리보기 메시지를 유지하고 마지막에 제자리에서 편집합니다 + - 약 1분보다 오래된 미리보기: OpenClaw는 완료된 답변을 새 최종 메시지로 보낸 다음 미리보기를 정리하므로, Telegram의 표시 타임스탬프는 미리보기 생성 시간이 아니라 완료 시간을 반영합니다 - 복잡한 답변(예: 미디어 페이로드)의 경우 OpenClaw는 일반 최종 전달로 폴백한 다음 미리보기 메시지를 정리합니다. + 복잡한 답변(예: 미디어 페이로드)의 경우 OpenClaw는 일반 최종 전달로 대체한 다음 미리보기 메시지를 정리합니다. - 미리보기 스트리밍은 블록 스트리밍과 별개입니다. Telegram에 대해 블록 스트리밍이 명시적으로 활성화된 경우 OpenClaw는 이중 스트리밍을 피하기 위해 미리보기 스트림을 건너뜁니다. - - 네이티브 초안 전송을 사용할 수 없거나 거부되면 OpenClaw는 자동으로 `sendMessage` + `editMessageText`로 폴백합니다. + 미리보기 스트리밍은 블록 스트리밍과 별개입니다. Telegram에 블록 스트리밍이 명시적으로 활성화된 경우 OpenClaw는 이중 스트리밍을 피하기 위해 미리보기 스트림을 건너뜁니다. Telegram 전용 추론 스트림: @@ -326,18 +324,18 @@ curl "https://api.telegram.org/bot/getUpdates" - + 아웃바운드 텍스트는 Telegram `parse_mode: "HTML"`을 사용합니다. - - Markdown 스타일 텍스트는 Telegram에 안전한 HTML로 렌더링됩니다. + - Markdown과 유사한 텍스트는 Telegram에 안전한 HTML로 렌더링됩니다. - 원시 모델 HTML은 Telegram 파싱 실패를 줄이기 위해 이스케이프됩니다. - Telegram이 파싱된 HTML을 거부하면 OpenClaw는 일반 텍스트로 다시 시도합니다. - 링크 미리보기는 기본적으로 활성화되어 있으며 `channels.telegram.linkPreview: false`로 비활성화할 수 있습니다. + 링크 미리보기는 기본적으로 활성화되며 `channels.telegram.linkPreview: false`로 비활성화할 수 있습니다. - + Telegram 명령 메뉴 등록은 시작 시 `setMyCommands`로 처리됩니다. 네이티브 명령 기본값: @@ -361,46 +359,46 @@ curl "https://api.telegram.org/bot/getUpdates" 규칙: - - 이름은 정규화됩니다(앞의 `/` 제거, 소문자 변환) + - 이름은 정규화됩니다(앞의 `/` 제거, 소문자화) - 유효한 패턴: `a-z`, `0-9`, `_`, 길이 `1..32` - 사용자 지정 명령은 네이티브 명령을 재정의할 수 없습니다 - - 충돌/중복은 건너뛰고 로그에 기록됩니다 + - 충돌/중복은 건너뛰고 기록됩니다 참고: - - 사용자 지정 명령은 메뉴 항목일 뿐이며 동작을 자동으로 구현하지 않습니다 - - plugin/skill 명령은 Telegram 메뉴에 표시되지 않더라도 입력하면 계속 작동할 수 있습니다 + - 사용자 지정 명령은 메뉴 항목일 뿐이며, 동작을 자동으로 구현하지 않습니다 + - Plugin/Skill 명령은 Telegram 메뉴에 표시되지 않아도 입력하면 계속 동작할 수 있습니다 - 네이티브 명령이 비활성화되면 내장 명령이 제거됩니다. 사용자 지정/plugin 명령은 구성된 경우 여전히 등록될 수 있습니다. + 네이티브 명령이 비활성화된 경우 기본 제공 명령이 제거됩니다. 구성된 경우 사용자 지정/Plugin 명령은 계속 등록될 수 있습니다. 일반적인 설정 실패: - - `BOT_COMMANDS_TOO_MUCH`와 함께 `setMyCommands failed`가 발생하면 정리 후에도 Telegram 메뉴가 여전히 초과되었다는 뜻입니다. plugin/skill/사용자 지정 명령을 줄이거나 `channels.telegram.commands.native`를 비활성화하세요. - - 직접 Bot API curl 명령은 작동하지만 `deleteWebhook`, `deleteMyCommands` 또는 `setMyCommands`가 `404: Not Found`로 실패하면 `channels.telegram.apiRoot`가 전체 `/bot` 엔드포인트로 설정되었을 수 있습니다. `apiRoot`는 Bot API 루트만이어야 하며, `openclaw doctor --fix`는 실수로 붙은 끝의 `/bot`을 제거합니다. - - `getMe returned 401`은 Telegram이 구성된 봇 토큰을 거부했다는 뜻입니다. 현재 BotFather 토큰으로 `botToken`, `tokenFile` 또는 `TELEGRAM_BOT_TOKEN`을 업데이트하세요. OpenClaw는 폴링 전에 중지하므로 이는 Webhook 정리 실패로 보고되지 않습니다. - - 네트워크/fetch 오류와 함께 `setMyCommands failed`가 발생하면 보통 `api.telegram.org`로의 아웃바운드 DNS/HTTPS가 차단되었다는 뜻입니다. + - `BOT_COMMANDS_TOO_MUCH`와 함께 `setMyCommands failed`가 표시되면 잘라낸 뒤에도 Telegram 메뉴가 여전히 넘쳤다는 뜻입니다. Plugin/Skill/사용자 지정 명령을 줄이거나 `channels.telegram.commands.native`를 비활성화하세요. + - 직접 Bot API curl 명령은 동작하지만 `deleteWebhook`, `deleteMyCommands` 또는 `setMyCommands`가 `404: Not Found`로 실패하면 `channels.telegram.apiRoot`가 전체 `/bot` 엔드포인트로 설정되었을 수 있습니다. `apiRoot`는 Bot API 루트만이어야 하며, `openclaw doctor --fix`는 실수로 붙은 뒤쪽 `/bot`을 제거합니다. + - `getMe returned 401`은 Telegram이 구성된 봇 토큰을 거부했다는 뜻입니다. `botToken`, `tokenFile` 또는 `TELEGRAM_BOT_TOKEN`을 현재 BotFather 토큰으로 업데이트하세요. OpenClaw는 폴링 전에 중지되므로 이것은 Webhook 정리 실패로 보고되지 않습니다. + - 네트워크/페치 오류와 함께 `setMyCommands failed`가 표시되면 일반적으로 `api.telegram.org`로 나가는 DNS/HTTPS가 차단되었다는 뜻입니다. - ### 기기 페어링 명령(`device-pair` plugin) + ### 기기 페어링 명령(`device-pair` Plugin) - `device-pair` plugin이 설치되어 있으면: + `device-pair` Plugin이 설치된 경우: 1. `/pair`가 설정 코드를 생성합니다 2. iOS 앱에 코드를 붙여넣습니다 - 3. `/pair pending`이 보류 중인 요청(역할/범위 포함)을 나열합니다 + 3. `/pair pending`이 보류 중인 요청을 나열합니다(역할/범위 포함) 4. 요청을 승인합니다: - 명시적 승인은 `/pair approve ` - 보류 중인 요청이 하나뿐이면 `/pair approve` - 가장 최근 요청은 `/pair approve latest` - 설정 코드는 짧은 수명의 부트스트랩 토큰을 전달합니다. 내장 부트스트랩 전달은 기본 노드 토큰을 `scopes: []`로 유지합니다. 전달된 모든 운영자 토큰은 `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`로 제한됩니다. 부트스트랩 범위 검사는 역할 접두사가 붙으므로, 해당 운영자 허용 목록은 운영자 요청만 충족합니다. 비운영자 역할은 여전히 자체 역할 접두사 아래의 범위가 필요합니다. + 설정 코드는 수명이 짧은 부트스트랩 토큰을 포함합니다. 기본 제공 부트스트랩 인계는 기본 노드 토큰을 `scopes: []`로 유지합니다. 인계된 운영자 토큰은 `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`로 제한됩니다. 부트스트랩 범위 검사는 역할 접두사가 붙으므로 해당 운영자 허용 목록은 운영자 요청만 충족합니다. 운영자가 아닌 역할은 여전히 자체 역할 접두사 아래의 범위가 필요합니다. - 기기가 변경된 인증 세부 정보(예: 역할/범위/공개 키)로 다시 시도하면 이전 보류 요청이 대체되고 새 요청은 다른 `requestId`를 사용합니다. 승인하기 전에 `/pair pending`을 다시 실행하세요. + 기기가 인증 세부 정보(예: 역할/범위/공개 키)를 변경해 다시 시도하면 이전 보류 요청이 대체되고 새 요청은 다른 `requestId`를 사용합니다. 승인하기 전에 `/pair pending`을 다시 실행하세요. 자세한 내용: [페어링](/ko/channels/pairing#pair-via-telegram-recommended-for-ios). - + 인라인 키보드 범위 구성: ```json5 @@ -441,9 +439,9 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist`(기본값) - 레거시 `capabilities: ["inlineButtons"]`는 `inlineButtons: "all"`로 매핑됩니다. + 기존 `capabilities: ["inlineButtons"]`는 `inlineButtons: "all"`에 매핑됩니다. - 메시지 작업 예시: + 메시지 작업 예: ```json5 { @@ -461,12 +459,12 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - 콜백 클릭은 에이전트에 텍스트로 전달됩니다: + 콜백 클릭은 텍스트로 에이전트에 전달됩니다: `callback_data: ` - + Telegram 도구 작업에는 다음이 포함됩니다: - `sendMessage`(`to`, `content`, 선택 사항 `mediaUrl`, `replyToMessageId`, `messageThreadId`) @@ -475,7 +473,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `editMessage`(`chatId`, `messageId`, `content`) - `createForumTopic`(`chatId`, `name`, 선택 사항 `iconColor`, `iconCustomEmojiId`) - 채널 메시지 작업은 사용하기 편한 별칭(`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`)을 노출합니다. + 채널 메시지 작업은 사용하기 쉬운 별칭(`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`)을 노출합니다. 게이팅 제어: @@ -484,18 +482,18 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker`(기본값: 비활성화) - 참고: `edit` 및 `topic-create`는 현재 기본적으로 활성화되어 있으며 별도의 `channels.telegram.actions.*` 토글이 없습니다. - 런타임 전송은 활성 구성/시크릿 스냅샷(시작/다시 로드)을 사용하므로, 작업 경로는 전송마다 임시 SecretRef 재해석을 수행하지 않습니다. + 참고: `edit`와 `topic-create`는 현재 기본적으로 활성화되어 있으며 별도의 `channels.telegram.actions.*` 토글이 없습니다. + 런타임 전송은 활성 구성/시크릿 스냅샷(시작/다시 로드)을 사용하므로 작업 경로는 전송마다 임시 SecretRef 재해석을 수행하지 않습니다. 반응 제거 의미론: [/tools/reactions](/ko/tools/reactions) - - Telegram은 생성된 출력에서 명시적 답장 스레딩 태그를 지원합니다: + + Telegram은 생성된 출력에서 명시적 답글 스레딩 태그를 지원합니다: - - `[[reply_to_current]]`는 트리거한 메시지에 답장합니다 - - `[[reply_to:]]`는 특정 Telegram 메시지 ID에 답장합니다 + - `[[reply_to_current]]`는 트리거한 메시지에 답글을 답니다 + - `[[reply_to:]]`는 특정 Telegram 메시지 ID에 답글을 답니다 `channels.telegram.replyToMode`는 처리를 제어합니다: @@ -503,29 +501,29 @@ curl "https://api.telegram.org/bot/getUpdates" - `first` - `all` - 답장 스레딩이 활성화되어 있고 원본 Telegram 텍스트 또는 캡션을 사용할 수 있으면 OpenClaw는 네이티브 Telegram 인용 발췌를 자동으로 포함합니다. Telegram은 네이티브 인용 텍스트를 1024 UTF-16 코드 단위로 제한하므로, 더 긴 메시지는 시작 부분부터 인용되며 Telegram이 인용을 거부하면 일반 답장으로 폴백합니다. + 답글 스레딩이 활성화되어 있고 원본 Telegram 텍스트 또는 캡션을 사용할 수 있으면 OpenClaw는 네이티브 Telegram 인용 발췌를 자동으로 포함합니다. Telegram은 네이티브 인용 텍스트를 1024 UTF-16 코드 단위로 제한하므로 더 긴 메시지는 시작 부분부터 인용되고, Telegram이 인용을 거부하면 일반 답글로 대체됩니다. - 참고: `off`는 암시적 답장 스레딩을 비활성화합니다. 명시적 `[[reply_to_*]]` 태그는 여전히 적용됩니다. + 참고: `off`는 암시적 답글 스레딩을 비활성화합니다. 명시적 `[[reply_to_*]]` 태그는 여전히 적용됩니다. - + 포럼 슈퍼그룹: - 토픽 세션 키는 `:topic:`를 덧붙입니다 - - 답장과 입력 상태는 토픽 스레드를 대상으로 합니다 + - 답글과 입력 상태는 토픽 스레드를 대상으로 합니다 - 토픽 구성 경로: `channels.telegram.groups..topics.` 일반 토픽(`threadId=1`) 특수 사례: - 메시지 전송은 `message_thread_id`를 생략합니다(Telegram은 `sendMessage(...thread_id=1)`을 거부합니다) - - 입력 상태 작업은 여전히 `message_thread_id`를 포함합니다 + - 입력 작업은 여전히 `message_thread_id`를 포함합니다 - 토픽 상속: 토픽 항목은 재정의되지 않는 한 그룹 설정(`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`)을 상속합니다. + 토픽 상속: 토픽 항목은 재정의되지 않는 한 그룹 설정을 상속합니다(`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). `agentId`는 토픽 전용이며 그룹 기본값에서 상속되지 않습니다. - **토픽별 에이전트 라우팅**: 각 토픽은 토픽 구성에서 `agentId`를 설정하여 다른 에이전트로 라우팅할 수 있습니다. 이렇게 하면 각 토픽에 자체 격리된 작업 공간, 메모리, 세션이 제공됩니다. 예시: + **토픽별 에이전트 라우팅**: 각 토픽은 토픽 구성에서 `agentId`를 설정하여 다른 에이전트로 라우팅할 수 있습니다. 이렇게 하면 각 토픽에 자체 격리된 워크스페이스, 메모리, 세션이 제공됩니다. 예: ```json5 { @@ -547,26 +545,26 @@ curl "https://api.telegram.org/bot/getUpdates" 그러면 각 토픽은 자체 세션 키를 갖습니다: `agent:zu:telegram:group:-1001234567890:topic:3` - **영구 ACP 토픽 바인딩**: 포럼 토픽은 최상위 타입 지정 ACP 바인딩(`type: "acp"` 및 `match.channel: "telegram"`, `peer.kind: "group"`, 그리고 `-1001234567890:topic:42` 같은 토픽 한정 ID가 포함된 `bindings[]`)을 통해 ACP 하네스 세션을 고정할 수 있습니다. 현재 그룹/슈퍼그룹의 포럼 토픽으로 범위가 제한됩니다. [ACP 에이전트](/ko/tools/acp-agents)를 참조하세요. + **영구 ACP 토픽 바인딩**: 포럼 토픽은 최상위 typed ACP 바인딩(`type: "acp"` 및 `match.channel: "telegram"`, `peer.kind: "group"`, `-1001234567890:topic:42` 같은 토픽 한정 ID가 있는 `bindings[]`)을 통해 ACP 하니스 세션을 고정할 수 있습니다. 현재 그룹/슈퍼그룹의 포럼 토픽으로 범위가 제한됩니다. [ACP 에이전트](/ko/tools/acp-agents)를 참조하세요. - **채팅에서 스레드 바인딩 ACP 생성**: `/acp spawn --thread here|auto`는 현재 토픽을 새 ACP 세션에 바인딩합니다. 후속 메시지는 그곳으로 직접 라우팅됩니다. OpenClaw는 생성 확인을 토픽 내에 고정합니다. `channels.telegram.threadBindings.spawnAcpSessions=true`가 필요합니다. + **채팅에서 스레드 바인딩 ACP 생성**: `/acp spawn --thread here|auto`는 현재 토픽을 새 ACP 세션에 바인딩합니다. 후속 메시지는 그곳으로 직접 라우팅됩니다. OpenClaw는 생성 확인을 토픽 안에 고정합니다. `channels.telegram.threadBindings.spawnAcpSessions=true`가 필요합니다. 템플릿 컨텍스트는 `MessageThreadId`와 `IsForum`을 노출합니다. `message_thread_id`가 있는 DM 채팅은 DM 라우팅을 유지하지만 스레드 인식 세션 키를 사용합니다. - + ### 오디오 메시지 Telegram은 음성 메모와 오디오 파일을 구분합니다. - 기본값: 오디오 파일 동작 - - 에이전트 답장에 `[[audio_as_voice]]` 태그를 사용하여 음성 메모 전송을 강제합니다 - - 인바운드 음성 메모 전사본은 에이전트 컨텍스트에서 기계 생성, + - 에이전트 답변의 `[[audio_as_voice]]` 태그로 음성 메모 전송을 강제합니다 + - 인바운드 음성 메모 전사는 에이전트 컨텍스트에서 기계 생성, 신뢰할 수 없는 텍스트로 구성됩니다. 멘션 감지는 여전히 원시 - 전사본을 사용하므로 멘션 게이트가 적용된 음성 메시지가 계속 작동합니다. + 전사를 사용하므로 멘션 게이트가 적용된 음성 메시지도 계속 동작합니다. - 메시지 작업 예시: + 메시지 작업 예: ```json5 { @@ -582,7 +580,7 @@ curl "https://api.telegram.org/bot/getUpdates" Telegram은 비디오 파일과 비디오 메모를 구분합니다. - 메시지 작업 예시: + 메시지 작업 예: ```json5 { @@ -600,7 +598,7 @@ curl "https://api.telegram.org/bot/getUpdates" 인바운드 스티커 처리: - - 정적 WEBP: 다운로드 및 처리됨(플레이스홀더 ``) + - 정적 WEBP: 다운로드되어 처리됨(플레이스홀더 ``) - 애니메이션 TGS: 건너뜀 - 비디오 WEBM: 건너뜀 @@ -616,7 +614,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - 스티커는 가능한 경우 한 번 설명되고 반복적인 비전 호출을 줄이기 위해 캐시됩니다. + 스티커는 반복되는 비전 호출을 줄이기 위해 한 번 설명되고(가능한 경우) 캐시됩니다. 스티커 작업 활성화: @@ -656,8 +654,8 @@ curl "https://api.telegram.org/bot/getUpdates" - - Telegram 반응은 `message_reaction` 업데이트(메시지 페이로드와 별개)로 도착합니다. + + Telegram 반응은 `message_reaction` 업데이트로 도착합니다(메시지 페이로드와 별개). 활성화되면 OpenClaw는 다음과 같은 시스템 이벤트를 큐에 넣습니다: @@ -665,25 +663,25 @@ curl "https://api.telegram.org/bot/getUpdates" 구성: - - `channels.telegram.reactionNotifications`: `off | own | all` (기본값: `own`) - - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (기본값: `minimal`) + - `channels.telegram.reactionNotifications`: `off | own | all`(기본값: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive`(기본값: `minimal`) 참고: - - `own`은 봇이 보낸 메시지에 대한 사용자 반응만 의미합니다(보낸 메시지 캐시를 통한 최선의 방식). - - 반응 이벤트도 Telegram 접근 제어(`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`)를 계속 따릅니다. 승인되지 않은 발신자는 삭제됩니다. + - `own`은 봇이 보낸 메시지에 대한 사용자 반응만 의미합니다(보낸 메시지 캐시를 통한 최선의 지원). + - 반응 이벤트도 Telegram 접근 제어(`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`)를 그대로 따릅니다. 권한이 없는 발신자는 무시됩니다. - Telegram은 반응 업데이트에서 스레드 ID를 제공하지 않습니다. - - 포럼이 아닌 그룹은 그룹 채팅 세션으로 라우팅됩니다 - - 포럼 그룹은 정확한 원래 토픽이 아니라 그룹 일반 토픽 세션(`:topic:1`)으로 라우팅됩니다 + - 포럼이 아닌 그룹은 그룹 채팅 세션으로 라우팅됩니다. + - 포럼 그룹은 정확한 원래 토픽이 아니라 그룹 일반 토픽 세션(`:topic:1`)으로 라우팅됩니다. 폴링/Webhook의 `allowed_updates`에는 `message_reaction`이 자동으로 포함됩니다. - - `ackReaction`은 OpenClaw가 인바운드 메시지를 처리하는 동안 확인 이모지를 보냅니다. + + `ackReaction`은 OpenClaw가 수신 메시지를 처리하는 동안 확인 이모지를 보냅니다. - 해결 순서: + 확인 순서: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` @@ -693,16 +691,16 @@ curl "https://api.telegram.org/bot/getUpdates" 참고: - Telegram은 유니코드 이모지(예: "👀")를 기대합니다. - - 채널 또는 계정의 반응을 비활성화하려면 `""`를 사용하세요. + - 채널 또는 계정에서 반응을 비활성화하려면 `""`를 사용하세요. - - 채널 구성 쓰기는 기본적으로 활성화됩니다(`configWrites !== false`). + + 채널 설정 쓰기는 기본적으로 활성화됩니다(`configWrites !== false`). - Telegram에서 트리거되는 쓰기에는 다음이 포함됩니다. + Telegram으로 트리거되는 쓰기에는 다음이 포함됩니다. - - `channels.telegram.groups`를 업데이트하는 그룹 마이그레이션 이벤트(`migrate_to_chat_id`) + - `channels.telegram.groups`를 업데이트하기 위한 그룹 마이그레이션 이벤트(`migrate_to_chat_id`) - `/config set` 및 `/config unset`(명령 활성화 필요) 비활성화: @@ -719,13 +717,13 @@ curl "https://api.telegram.org/bot/getUpdates" - - 기본값은 롱 폴링입니다. Webhook 모드의 경우 `channels.telegram.webhookUrl` 및 `channels.telegram.webhookSecret`을 설정하세요. 선택적으로 `webhookPath`, `webhookHost`, `webhookPort`를 설정할 수 있습니다(기본값 `/telegram-webhook`, `127.0.0.1`, `8787`). + + 기본값은 Long polling입니다. Webhook 모드의 경우 `channels.telegram.webhookUrl` 및 `channels.telegram.webhookSecret`을 설정하세요. 선택적으로 `webhookPath`, `webhookHost`, `webhookPort`를 설정할 수 있습니다(기본값은 `/telegram-webhook`, `127.0.0.1`, `8787`). 로컬 리스너는 `127.0.0.1:8787`에 바인딩됩니다. 공개 인그레스의 경우 로컬 포트 앞에 리버스 프록시를 두거나 의도적으로 `webhookHost: "0.0.0.0"`을 설정하세요. Webhook 모드는 Telegram에 `200`을 반환하기 전에 요청 가드, Telegram 비밀 토큰, JSON 본문을 검증합니다. - 그런 다음 OpenClaw는 롱 폴링에서 사용하는 것과 동일한 채팅별/토픽별 봇 레인을 통해 업데이트를 비동기적으로 처리하므로, 느린 에이전트 턴이 Telegram의 delivery ACK를 붙잡지 않습니다. + 그런 다음 OpenClaw는 Long polling에서 사용하는 동일한 채팅별/토픽별 봇 레인을 통해 업데이트를 비동기적으로 처리하므로, 느린 에이전트 턴이 Telegram의 전달 ACK를 붙잡지 않습니다. @@ -733,15 +731,15 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.textChunkLimit` 기본값은 4000입니다. - `channels.telegram.chunkMode="newline"`은 길이 분할 전에 문단 경계(빈 줄)를 우선합니다. - `channels.telegram.mediaMaxMb`(기본값 100)는 인바운드 및 아웃바운드 Telegram 미디어 크기를 제한합니다. - - `channels.telegram.timeoutSeconds`는 Telegram API 클라이언트 타임아웃을 재정의합니다(설정하지 않으면 grammY 기본값 적용). - - `channels.telegram.pollingStallThresholdMs`의 기본값은 `120000`입니다. 폴링 중단 재시작의 오탐에 대해서만 `30000`에서 `600000` 사이로 조정하세요. - - 그룹 컨텍스트 기록은 `channels.telegram.historyLimit` 또는 `messages.groupChat.historyLimit`(기본값 50)을 사용합니다. `0`은 비활성화합니다. + - `channels.telegram.timeoutSeconds`는 Telegram API 클라이언트 타임아웃을 재정의합니다(설정하지 않으면 grammY 기본값이 적용됨). Long-polling 봇 클라이언트는 설정된 값을 45초 `getUpdates` 요청 가드보다 낮게 제한하여, 30초 폴링 창이 완료되기 전에 유휴 폴링이 중단되지 않도록 합니다. + - `channels.telegram.pollingStallThresholdMs`의 기본값은 `120000`입니다. 거짓 양성 폴링 정체 재시작이 발생할 때만 `30000`에서 `600000` 사이로 조정하세요. + - 그룹 컨텍스트 기록은 `channels.telegram.historyLimit` 또는 `messages.groupChat.historyLimit`을 사용합니다(기본값 50). `0`은 비활성화합니다. - 답장/인용/전달 보조 컨텍스트는 현재 수신된 그대로 전달됩니다. - - Telegram 허용 목록은 주로 전체 보조 컨텍스트 삭제 경계가 아니라, 누가 에이전트를 트리거할 수 있는지를 제어합니다. + - Telegram 허용 목록은 주로 누가 에이전트를 트리거할 수 있는지를 제어하며, 완전한 보조 컨텍스트 수정 경계가 아닙니다. - DM 기록 제어: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - `channels.telegram.retry` 구성은 복구 가능한 아웃바운드 API 오류에 대해 Telegram 전송 헬퍼(CLI/도구/작업)에 적용됩니다. 인바운드 최종 답장 전달도 Telegram 사전 연결 실패에 대해 제한된 안전 전송 재시도를 사용하지만, 표시되는 메시지를 중복시킬 수 있는 모호한 전송 후 네트워크 엔벌로프는 재시도하지 않습니다. + - `channels.telegram.retry` 설정은 복구 가능한 아웃바운드 API 오류에 대해 Telegram 전송 헬퍼(CLI/도구/작업)에 적용됩니다. 인바운드 최종 답장 전달도 Telegram 사전 연결 실패에 대해 제한된 안전 전송 재시도를 사용하지만, 표시되는 메시지가 중복될 수 있는 모호한 전송 후 네트워크 엔벨로프는 재시도하지 않습니다. CLI 전송 대상은 숫자 채팅 ID 또는 사용자 이름일 수 있습니다. @@ -750,7 +748,7 @@ openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Telegram 폴은 `openclaw message poll`을 사용하며 포럼 토픽을 지원합니다. + Telegram 폴링은 `openclaw message poll`을 사용하며 포럼 토픽을 지원합니다. ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -760,57 +758,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Telegram 전용 폴 플래그: + Telegram 전용 폴링 플래그: - - `--poll-duration-seconds` (5-600) + - `--poll-duration-seconds`(5-600) - `--poll-anonymous` - `--poll-public` - 포럼 토픽용 `--thread-id`(또는 `:topic:` 대상 사용) Telegram 전송은 다음도 지원합니다. - - `channels.telegram.capabilities.inlineButtons`가 허용할 때 인라인 키보드용 `buttons` 블록과 함께 `--presentation` + - `channels.telegram.capabilities.inlineButtons`가 허용하는 경우 인라인 키보드용 `buttons` 블록과 함께 `--presentation` - 봇이 해당 채팅에서 고정할 수 있을 때 고정 전달을 요청하는 `--pin` 또는 `--delivery '{"pin":true}'` - - 아웃바운드 이미지와 GIF를 압축 사진 또는 애니메이션 미디어 업로드 대신 문서로 보내는 `--force-document` + - 아웃바운드 이미지와 GIF를 압축된 사진 또는 애니메이션 미디어 업로드 대신 문서로 보내는 `--force-document` 작업 게이팅: - - `channels.telegram.actions.sendMessage=false`는 폴을 포함한 아웃바운드 Telegram 메시지를 비활성화합니다 - - `channels.telegram.actions.poll=false`는 일반 전송은 활성화한 상태로 Telegram 폴 생성을 비활성화합니다 + - `channels.telegram.actions.sendMessage=false`는 폴링을 포함한 아웃바운드 Telegram 메시지를 비활성화합니다. + - `channels.telegram.actions.poll=false`는 일반 전송은 활성화한 채 Telegram 폴링 생성을 비활성화합니다. - - Telegram은 승인자 DM에서 exec 승인을 지원하며, 선택적으로 원래 채팅 또는 토픽에 프롬프트를 게시할 수 있습니다. 승인자는 숫자 Telegram 사용자 ID여야 합니다. + + Telegram은 승인자 DM에서 실행 승인을 지원하며, 선택적으로 원래 채팅 또는 토픽에 프롬프트를 게시할 수 있습니다. 승인자는 숫자 Telegram 사용자 ID여야 합니다. - 구성 경로: + 설정 경로: - - `channels.telegram.execApprovals.enabled`(해결 가능한 승인자가 하나 이상 있으면 자동 활성화) + - `channels.telegram.execApprovals.enabled`(확인 가능한 승인자가 하나 이상 있으면 자동 활성화) - `channels.telegram.execApprovals.approvers`(`commands.ownerAllowFrom`의 숫자 소유자 ID로 폴백) - `channels.telegram.execApprovals.target`: `dm`(기본값) | `channel` | `both` - `agentFilter`, `sessionFilter` - `channels.telegram.allowFrom`, `groupAllowFrom`, `defaultTo`는 누가 봇과 대화할 수 있는지, 그리고 봇이 일반 답장을 어디로 보내는지를 제어합니다. 이것들이 누군가를 exec 승인자로 만들지는 않습니다. 아직 명령 소유자가 없을 때 처음 승인된 DM 페어링은 `commands.ownerAllowFrom`을 부트스트랩하므로, 단일 소유자 설정은 `execApprovals.approvers` 아래에 ID를 중복하지 않아도 계속 동작합니다. + `channels.telegram.allowFrom`, `groupAllowFrom`, `defaultTo`는 누가 봇과 대화할 수 있는지와 일반 답장을 어디로 보내는지를 제어합니다. 이것들이 누군가를 실행 승인자로 만들지는 않습니다. 아직 명령 소유자가 없을 때 첫 승인된 DM 페어링이 `commands.ownerAllowFrom`을 부트스트랩하므로, 단일 소유자 설정은 `execApprovals.approvers` 아래에 ID를 중복하지 않아도 계속 작동합니다. - 채널 전달은 채팅에 명령 텍스트를 표시합니다. 신뢰할 수 있는 그룹/토픽에서만 `channel` 또는 `both`를 활성화하세요. 프롬프트가 포럼 토픽에 도착하면 OpenClaw는 승인 프롬프트와 후속 응답에 해당 토픽을 유지합니다. exec 승인은 기본적으로 30분 후 만료됩니다. + 채널 전달은 채팅에 명령 텍스트를 표시합니다. 신뢰할 수 있는 그룹/토픽에서만 `channel` 또는 `both`를 활성화하세요. 프롬프트가 포럼 토픽에 도착하면 OpenClaw는 승인 프롬프트와 후속 메시지에 해당 토픽을 유지합니다. 실행 승인은 기본적으로 30분 후 만료됩니다. - 인라인 승인 버튼도 대상 표면(`dm`, `group`, 또는 `all`)을 허용하려면 `channels.telegram.capabilities.inlineButtons`가 필요합니다. `plugin:` 접두사가 붙은 승인 ID는 Plugin 승인을 통해 해결됩니다. 그 외에는 먼저 exec 승인을 통해 해결됩니다. + 인라인 승인 버튼도 대상 표면(`dm`, `group` 또는 `all`)을 허용하도록 `channels.telegram.capabilities.inlineButtons`가 필요합니다. `plugin:` 접두사가 붙은 승인 ID는 Plugin 승인을 통해 확인되고, 그 외의 ID는 먼저 실행 승인을 통해 확인됩니다. - [exec 승인](/ko/tools/exec-approvals)을 참조하세요. + [실행 승인](/ko/tools/exec-approvals)을 참조하세요. ## 오류 답장 제어 -에이전트가 전달 또는 제공자 오류를 만나면 Telegram은 오류 텍스트로 답장하거나 이를 억제할 수 있습니다. 두 구성 키가 이 동작을 제어합니다. +에이전트에 전달 또는 공급자 오류가 발생하면 Telegram은 오류 텍스트로 답장하거나 이를 억제할 수 있습니다. 이 동작은 두 설정 키로 제어합니다. -| 키 | 값 | 기본값 | 설명 | -| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------- | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply`는 친절한 오류 메시지를 채팅에 보냅니다. `silent`는 오류 답장을 완전히 억제합니다. | -| `channels.telegram.errorCooldownMs` | 숫자(ms) | `60000` | 같은 채팅에 보내는 오류 답장 사이의 최소 시간입니다. 장애 중 오류 스팸을 방지합니다. | +| 키 | 값 | 기본값 | 설명 | +| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply`는 채팅에 친절한 오류 메시지를 보냅니다. `silent`는 오류 답장을 완전히 억제합니다. | +| `channels.telegram.errorCooldownMs` | 숫자(ms) | `60000` | 같은 채팅에 대한 오류 답장 사이의 최소 시간입니다. 장애 중 오류 스팸을 방지합니다. | -계정별, 그룹별, 토픽별 재정의가 지원됩니다(다른 Telegram 구성 키와 동일한 상속). +계정별, 그룹별, 토픽별 재정의가 지원됩니다(다른 Telegram 설정 키와 동일한 상속). ```json5 { @@ -831,54 +829,55 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ ## 문제 해결 - + - - `requireMention=false`인 경우 Telegram 개인정보 보호 모드는 전체 표시를 허용해야 합니다. - - BotFather: `/setprivacy` -> 비활성화 - - 그런 다음 그룹에서 봇을 제거하고 다시 추가하세요 - - `openclaw channels status`는 구성이 멘션되지 않은 그룹 메시지를 기대할 때 경고합니다. - - `openclaw channels status --probe`는 명시적인 숫자 그룹 ID를 확인할 수 있습니다. 와일드카드 `"*"`는 멤버십 프로브를 할 수 없습니다. + - `requireMention=false`인 경우 Telegram 프라이버시 모드가 전체 표시를 허용해야 합니다. + - BotFather: `/setprivacy` -> Disable + - 그런 다음 그룹에서 봇을 제거했다가 다시 추가하세요. + - 설정이 멘션되지 않은 그룹 메시지를 기대할 때 `openclaw channels status`가 경고합니다. + - `openclaw channels status --probe`는 명시적인 숫자 그룹 ID를 확인할 수 있습니다. 와일드카드 `"*"`는 멤버십 프로브를 수행할 수 없습니다. - 빠른 세션 테스트: `/activation always`. - - `channels.telegram.groups`가 있으면 그룹이 목록에 있어야 합니다(또는 `"*"` 포함) - - 그룹의 봇 멤버십을 확인하세요 - - 건너뛴 이유는 로그에서 검토하세요: `openclaw logs --follow` + - `channels.telegram.groups`가 있으면 그룹이 나열되어 있어야 합니다(또는 `"*"` 포함). + - 그룹의 봇 멤버십을 확인하세요. + - 건너뛰기 이유는 로그에서 확인하세요: `openclaw logs --follow` - + - - 발신자 ID를 승인하세요(페어링 및/또는 숫자 `allowFrom`) - - 그룹 정책이 `open`이어도 명령 승인은 계속 적용됩니다 - - `BOT_COMMANDS_TOO_MUCH`와 함께 `setMyCommands failed`가 표시되면 네이티브 메뉴에 항목이 너무 많다는 뜻입니다. Plugin/스킬/사용자 지정 명령을 줄이거나 네이티브 메뉴를 비활성화하세요 - - `deleteMyCommands` / `setMyCommands` 시작 호출은 제한되어 있으며 요청 타임아웃 시 Telegram의 전송 폴백을 통해 한 번 재시도합니다. 지속적인 네트워크/가져오기 오류는 보통 `api.telegram.org`에 대한 DNS/HTTPS 도달성 문제를 나타냅니다 + - 발신자 ID를 승인하세요(페어링 및/또는 숫자 `allowFrom`). + - 그룹 정책이 `open`이어도 명령 권한 부여는 계속 적용됩니다. + - `BOT_COMMANDS_TOO_MUCH`와 함께 `setMyCommands failed`가 발생하면 네이티브 메뉴 항목이 너무 많다는 뜻입니다. Plugin/Skills/사용자 지정 명령을 줄이거나 네이티브 메뉴를 비활성화하세요. + - `deleteMyCommands` / `setMyCommands` 시작 호출은 제한되며 요청 타임아웃 시 Telegram의 전송 폴백을 통해 한 번 재시도합니다. 지속적인 네트워크/가져오기 오류는 일반적으로 `api.telegram.org`에 대한 DNS/HTTPS 도달성 문제를 나타냅니다. - + - - `getMe returned 401`은 구성된 봇 토큰에 대한 Telegram 인증 실패입니다. - - BotFather에서 봇 토큰을 다시 복사하거나 재생성한 다음, 기본 계정의 `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` 또는 `TELEGRAM_BOT_TOKEN`을 업데이트하세요. - - 시작 중 `deleteWebhook 401 Unauthorized`도 인증 실패입니다. 이를 "Webhook이 없음"으로 처리하면 동일한 잘못된 토큰 실패를 이후 API 호출로 미루기만 합니다. - - 폴링 시작 중 일시적인 네트워크 오류로 `deleteWebhook`이 실패하면 OpenClaw는 `getWebhookInfo`를 확인합니다. Telegram이 빈 Webhook URL을 보고하면 정리가 이미 충족된 것이므로 폴링이 계속됩니다. + - `getMe returned 401`은 설정된 봇 토큰에 대한 Telegram 인증 실패입니다. + - BotFather에서 봇 토큰을 다시 복사하거나 재생성한 다음, 기본 계정에 대해 `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts..botToken` 또는 `TELEGRAM_BOT_TOKEN`을 업데이트하세요. + - 시작 중 `deleteWebhook 401 Unauthorized`도 인증 실패입니다. 이를 "Webhook이 없음"으로 처리하면 같은 잘못된 토큰 실패가 이후 API 호출로 지연될 뿐입니다. + - 폴링 시작 중 일시적인 네트워크 오류로 `deleteWebhook`이 실패하면 OpenClaw는 `getWebhookInfo`를 확인합니다. Telegram이 빈 Webhook URL을 보고하면 정리가 이미 충족되었으므로 폴링이 계속됩니다. - Node 22+와 사용자 지정 fetch/proxy는 AbortSignal 타입이 일치하지 않으면 즉시 중단 동작을 유발할 수 있습니다. - - 일부 호스트는 `api.telegram.org`를 IPv6로 먼저 해석합니다. IPv6 이그레스가 손상되어 있으면 Telegram API 실패가 간헐적으로 발생할 수 있습니다. - - 로그에 `TypeError: fetch failed` 또는 `Network request for 'getUpdates' failed!`가 포함되어 있으면, OpenClaw는 이제 이를 복구 가능한 네트워크 오류로 보고 재시도합니다. - - 로그에 `Polling stall detected`가 포함되어 있으면, 기본적으로 OpenClaw는 완료된 long-poll 활성 상태가 120초 동안 없을 때 폴링을 다시 시작하고 Telegram 전송을 다시 빌드합니다. - - `openclaw channels status --probe`와 `openclaw doctor`는 실행 중인 폴링 계정이 시작 유예 시간 이후 `getUpdates`를 완료하지 않았거나, 실행 중인 Webhook 계정이 시작 유예 시간 이후 `setWebhook`을 완료하지 않았거나, 마지막으로 성공한 폴링 전송 활동이 오래된 경우 경고합니다. - - 장시간 실행되는 `getUpdates` 호출은 정상인데 호스트가 여전히 잘못된 폴링 정지 재시작을 보고하는 경우에만 `channels.telegram.pollingStallThresholdMs`를 늘리세요. 지속적인 정지는 일반적으로 호스트와 `api.telegram.org` 사이의 프록시, DNS, IPv6 또는 TLS 이그레스 문제를 가리킵니다. - - Telegram은 Bot API 전송에 대해 프로세스 프록시 환경 변수도 따르며, 여기에는 `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` 및 각각의 소문자 변형이 포함됩니다. `NO_PROXY` / `no_proxy`는 여전히 `api.telegram.org`를 우회할 수 있습니다. - - 서비스 환경에서 OpenClaw 관리형 프록시가 `OPENCLAW_PROXY_URL`을 통해 구성되어 있고 표준 프록시 환경 변수가 없으면, Telegram도 Bot API 전송에 해당 URL을 사용합니다. - - 직접 이그레스/TLS가 불안정한 VPS 호스트에서는 `channels.telegram.proxy`를 통해 Telegram API 호출을 라우팅하세요. + - 일부 호스트는 `api.telegram.org`를 IPv6로 먼저 해석합니다. IPv6 송신이 손상되어 있으면 간헐적인 Telegram API 실패가 발생할 수 있습니다. + - 로그에 `TypeError: fetch failed` 또는 `Network request for 'getUpdates' failed!`가 포함되어 있으면, OpenClaw는 이제 이를 복구 가능한 네트워크 오류로 재시도합니다. + - Telegram 소켓이 짧고 고정된 주기로 재활용된다면 낮은 `channels.telegram.timeoutSeconds` 값을 확인하세요. long-polling 봇 클라이언트는 `getUpdates` 요청 가드보다 낮게 구성된 값을 제한하지만, 이전 릴리스에서는 이 값이 long-poll timeout보다 낮게 설정된 경우 모든 poll이 중단될 수 있었습니다. + - 로그에 `Polling stall detected`가 포함되어 있으면, OpenClaw는 기본적으로 완료된 long-poll liveness가 120초 동안 없을 때 polling을 다시 시작하고 Telegram transport를 다시 빌드합니다. + - `openclaw channels status --probe`와 `openclaw doctor`는 실행 중인 polling 계정이 시작 유예 시간 후 `getUpdates`를 완료하지 않았거나, 실행 중인 webhook 계정이 시작 유예 시간 후 `setWebhook`을 완료하지 않았거나, 마지막으로 성공한 polling transport 활동이 오래된 경우 경고합니다. + - 오래 실행되는 `getUpdates` 호출이 정상인데도 호스트가 잘못된 polling-stall 재시작을 계속 보고하는 경우에만 `channels.telegram.pollingStallThresholdMs`를 늘리세요. 지속적인 stall은 보통 호스트와 `api.telegram.org` 사이의 proxy, DNS, IPv6 또는 TLS 송신 문제를 가리킵니다. + - Telegram은 Bot API transport에 대해 `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` 및 그 소문자 변형을 포함한 프로세스 proxy env도 따릅니다. `NO_PROXY` / `no_proxy`는 여전히 `api.telegram.org`를 우회할 수 있습니다. + - 서비스 환경에서 OpenClaw 관리 proxy가 `OPENCLAW_PROXY_URL`로 구성되어 있고 표준 proxy env가 없으면, Telegram도 Bot API transport에 해당 URL을 사용합니다. + - 직접 송신/TLS가 불안정한 VPS 호스트에서는 `channels.telegram.proxy`를 통해 Telegram API 호출을 라우팅하세요. ```yaml channels: @@ -887,7 +886,7 @@ channels: ``` - Node 22+는 기본적으로 `autoSelectFamily=true`(WSL2 제외)와 `dnsResultOrder=ipv4first`를 사용합니다. - - 호스트가 WSL2이거나 IPv4 전용 동작이 명시적으로 더 잘 작동하는 경우, 패밀리 선택을 강제하세요. + - 호스트가 WSL2이거나 IPv4 전용 동작이 명시적으로 더 잘 작동한다면 family 선택을 강제하세요. ```yaml channels: @@ -896,11 +895,7 @@ channels: autoSelectFamily: false ``` - - RFC 2544 벤치마크 범위 응답(`198.18.0.0/15`)은 기본적으로 - Telegram 미디어 다운로드에 이미 허용됩니다. 신뢰할 수 있는 fake-IP 또는 - 투명 프록시가 미디어 다운로드 중 `api.telegram.org`를 다른 - private/internal/special-use 주소로 다시 쓰는 경우, Telegram 전용 우회를 - 선택적으로 활성화할 수 있습니다. + - RFC 2544 벤치마크 범위 응답(`198.18.0.0/15`)은 기본적으로 Telegram 미디어 다운로드에 이미 허용됩니다. 신뢰할 수 있는 fake-IP 또는 투명 proxy가 미디어 다운로드 중 `api.telegram.org`를 다른 private/internal/special-use 주소로 다시 쓰는 경우, Telegram 전용 우회에 옵트인할 수 있습니다. ```yaml channels: @@ -909,20 +904,16 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - 동일한 선택적 활성화는 계정별로 + - 동일한 옵트인은 계정별로 `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`에서도 사용할 수 있습니다. - - 프록시가 Telegram 미디어 호스트를 `198.18.x.x`로 해석한다면, 먼저 - 위험 플래그를 꺼 두세요. Telegram 미디어는 이미 기본적으로 RFC 2544 - 벤치마크 범위를 허용합니다. + - proxy가 Telegram 미디어 호스트를 `198.18.x.x`로 해석한다면 먼저 dangerous 플래그를 꺼 둔 상태로 두세요. Telegram 미디어는 기본적으로 RFC 2544 벤치마크 범위를 이미 허용합니다. `channels.telegram.network.dangerouslyAllowPrivateNetwork`는 Telegram - 미디어 SSRF 보호를 약화합니다. Clash, Mihomo, Surge fake-IP 라우팅처럼 - RFC 2544 벤치마크 범위 밖의 private 또는 special-use 응답을 합성하는, - 신뢰할 수 있는 운영자 제어 프록시 환경에서만 사용하세요. 일반적인 공개 인터넷 Telegram 접근에는 꺼 두세요. + 미디어 SSRF 보호를 약화합니다. RFC 2544 벤치마크 범위 밖의 private 또는 special-use 응답을 합성하는 Clash, Mihomo, Surge fake-IP 라우팅 같은 신뢰할 수 있는 운영자 제어 proxy 환경에서만 사용하세요. 일반적인 public internet Telegram 접근에는 꺼 둔 상태로 두세요. - - 환경 재정의(임시): + - 환경 override(임시): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` @@ -940,50 +931,50 @@ dig +short api.telegram.org AAAA ## 구성 참조 -주요 참조: [구성 참조 - Telegram](/ko/gateway/config-channels#telegram). +기본 참조: [구성 참조 - Telegram](/ko/gateway/config-channels#telegram). - + -- 시작/인증: `enabled`, `botToken`, `tokenFile`, `accounts.*`(`tokenFile`은 일반 파일을 가리켜야 하며, 심볼릭 링크는 거부됩니다) -- 접근 제어: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, 최상위 `bindings[]`(`type: "acp"`) -- 실행 승인: `execApprovals`, `accounts.*.execApprovals` -- 명령/메뉴: `commands.native`, `commands.nativeSkills`, `customCommands` -- 스레딩/답장: `replyToMode` -- 스트리밍: `streaming`(미리 보기), `streaming.preview.toolProgress`, `blockStreaming` -- 형식/전달: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` -- 미디어/네트워크: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- 사용자 지정 API 루트: `apiRoot`(Bot API 루트만 해당; `/bot`을 포함하지 마세요) -- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` -- 작업/기능: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` -- 반응: `reactionNotifications`, `reactionLevel` +- 시작/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile`은 일반 파일을 가리켜야 하며 symlink는 거부됩니다) +- 접근 제어: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, 최상위 `bindings[]` (`type: "acp"`) +- exec 승인: `execApprovals`, `accounts.*.execApprovals` +- 명령/menu: `commands.native`, `commands.nativeSkills`, `customCommands` +- threading/replies: `replyToMode` +- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming` +- formatting/delivery: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- media/network: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` +- 사용자 지정 API root: `apiRoot` (Bot API root만 해당, `/bot`을 포함하지 마세요) +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- actions/capabilities: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` +- reactions: `reactionNotifications`, `reactionLevel` - 오류: `errorPolicy`, `errorCooldownMs` -- 쓰기/기록: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- writes/history: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -다중 계정 우선순위: 두 개 이상의 계정 ID가 구성된 경우 기본 라우팅을 명시하려면 `channels.telegram.defaultAccount`를 설정하거나 `channels.telegram.accounts.default`를 포함하세요. 그렇지 않으면 OpenClaw는 정규화된 첫 번째 계정 ID로 폴백하고 `openclaw doctor`가 경고합니다. 이름이 지정된 계정은 `channels.telegram.allowFrom` / `groupAllowFrom`을 상속하지만, `accounts.default.*` 값은 상속하지 않습니다. +다중 계정 우선순위: 둘 이상의 계정 ID가 구성된 경우 기본 라우팅을 명시하려면 `channels.telegram.defaultAccount`를 설정하거나 `channels.telegram.accounts.default`를 포함하세요. 그렇지 않으면 OpenClaw는 첫 번째로 정규화된 계정 ID로 fallback하고 `openclaw doctor`가 경고합니다. 이름이 있는 계정은 `channels.telegram.allowFrom` / `groupAllowFrom`을 상속하지만 `accounts.default.*` 값은 상속하지 않습니다. ## 관련 항목 - + Telegram 사용자를 Gateway에 페어링합니다. - - 그룹 및 주제 허용 목록 동작입니다. + + 그룹 및 주제 allowlist 동작입니다. - - 인바운드 메시지를 에이전트로 라우팅합니다. + + 수신 메시지를 에이전트로 라우팅합니다. - - 위협 모델 및 강화입니다. + + 위협 모델과 강화입니다. - + 그룹과 주제를 에이전트에 매핑합니다. - - 채널 간 진단입니다. + + 교차 채널 진단입니다. diff --git a/docs/ko/concepts/memory-search.md b/docs/ko/concepts/memory-search.md index a6232c870..4037fe831 100644 --- a/docs/ko/concepts/memory-search.md +++ b/docs/ko/concepts/memory-search.md @@ -1,55 +1,55 @@ --- read_when: - - memory_search가 어떻게 작동하는지 이해하려는 경우 + - memory_search가 어떻게 작동하는지 이해하려고 합니다 - 임베딩 제공자를 선택하려는 경우 - 검색 품질을 조정하려는 경우 -summary: 임베딩과 하이브리드 검색을 사용하여 메모리 검색이 관련 노트를 찾는 방식 +summary: 메모리 검색이 임베딩과 하이브리드 검색을 사용하여 관련 노트를 찾는 방법 title: 메모리 검색 x-i18n: - generated_at: "2026-04-30T06:26:23Z" + generated_at: "2026-04-30T16:27:53Z" model: gpt-5.5 provider: openai - source_hash: 3e6c44d90f49a797bda01b9a575928c128a334f89ae14fc3620e65562a866aa9 + source_hash: 7f40bbe32453a28070ffc67f19a4c06e2fe59a24237a2aef353f4b9b8260bcf2 source_path: concepts/memory-search.md workflow: 16 --- -`memory_search`는 문구가 원문과 달라도 메모리 파일에서 관련 노트를 찾습니다. 메모리를 작은 청크로 인덱싱하고 임베딩, 키워드 또는 둘 다를 사용해 검색하는 방식으로 동작합니다. +`memory_search`는 원문과 표현이 다르더라도 메모리 파일에서 관련 노트를 찾습니다. 메모리를 작은 청크로 인덱싱하고 임베딩, 키워드 또는 둘 다를 사용해 검색하는 방식으로 작동합니다. ## 빠른 시작 -GitHub Copilot 구독, OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모리 검색은 자동으로 동작합니다. 제공자를 명시적으로 설정하려면: +GitHub Copilot 구독, OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모리 검색이 자동으로 작동합니다. provider를 명시적으로 설정하려면: ```json5 { agents: { defaults: { memorySearch: { - provider: "openai", // or "gemini", "local", "ollama", etc. + provider: "openai", // 또는 "gemini", "local", "ollama" 등 }, }, }, } ``` -다중 엔드포인트 설정에서는 해당 제공자가 `api: "ollama"` 또는 다른 임베딩 어댑터 소유자를 설정하는 경우 `provider`를 `ollama-5080` 같은 사용자 지정 `models.providers.` 항목으로도 지정할 수 있습니다. +다중 엔드포인트 설정의 경우, `provider`는 해당 provider가 `api: "ollama"` 또는 다른 임베딩 어댑터 소유자를 설정할 때 `ollama-5080` 같은 사용자 지정 `models.providers.` 항목일 수도 있습니다. -API 키 없이 로컬 임베딩을 사용하려면 선택 사항인 `node-llama-cpp` 런타임 패키지를 OpenClaw 옆에 설치하고 `provider: "local"`을 사용하세요. +API 키 없이 로컬 임베딩을 사용하려면 `provider: "local"`을 설정합니다. 패키지 설치는 OpenClaw의 관리형 Plugin runtime-deps 트리에 네이티브 `node-llama-cpp` 런타임을 유지합니다. 해당 트리에 복구가 필요하면 `openclaw doctor --fix`를 실행하세요. -일부 OpenAI 호환 임베딩 엔드포인트는 검색에는 `input_type: "query"`, 인덱싱된 청크에는 `input_type: "document"` 또는 `"passage"` 같은 비대칭 레이블이 필요합니다. `memorySearch.queryInputType` 및 `memorySearch.documentInputType`으로 이를 구성하세요. [메모리 구성 참조](/ko/reference/memory-config#provider-specific-config)를 확인하세요. +일부 OpenAI 호환 임베딩 엔드포인트는 검색에는 `input_type: "query"`, 인덱싱된 청크에는 `input_type: "document"` 또는 `"passage"` 같은 비대칭 레이블이 필요합니다. 이러한 값은 `memorySearch.queryInputType` 및 `memorySearch.documentInputType`으로 구성하세요. [메모리 구성 참조](/ko/reference/memory-config#provider-specific-config)를 참조하세요. -## 지원되는 제공자 +## 지원되는 provider -| 제공자 | ID | API 키 필요 | 참고 | -| -------------- | ---------------- | ----------- | ---------------------------------------------------- | -| Bedrock | `bedrock` | 아니요 | AWS 자격 증명 체인이 확인되면 자동 감지됨 | -| Gemini | `gemini` | 예 | 이미지/오디오 인덱싱 지원 | -| GitHub Copilot | `github-copilot` | 아니요 | 자동 감지되며 Copilot 구독 사용 | -| Local | `local` | 아니요 | GGUF 모델, 약 0.6GB 다운로드 | -| Mistral | `mistral` | 예 | 자동 감지됨 | -| Ollama | `ollama` | 아니요 | 로컬, 명시적으로 설정해야 함 | -| OpenAI | `openai` | 예 | 자동 감지됨, 빠름 | -| Voyage | `voyage` | 예 | 자동 감지됨 | +| Provider | ID | API 키 필요 | 참고 사항 | +| -------------- | ---------------- | ----------- | -------------------------------------------------------- | +| Bedrock | `bedrock` | 아니요 | AWS 자격 증명 체인이 확인되면 자동 감지됨 | +| Gemini | `gemini` | 예 | 이미지/오디오 인덱싱 지원 | +| GitHub Copilot | `github-copilot` | 아니요 | 자동 감지되며 Copilot 구독 사용 | +| Local | `local` | 아니요 | GGUF 모델, 약 0.6GB 다운로드 | +| Mistral | `mistral` | 예 | 자동 감지됨 | +| Ollama | `ollama` | 아니요 | 로컬, 명시적으로 설정해야 함 | +| OpenAI | `openai` | 예 | 자동 감지됨, 빠름 | +| Voyage | `voyage` | 예 | 자동 감지됨 | ## 검색 작동 방식 @@ -66,28 +66,28 @@ flowchart LR M --> R["Top Results"] ``` -- **벡터 검색**은 의미가 비슷한 노트를 찾습니다("gateway host"가 "the machine running OpenClaw"와 일치). -- **BM25 키워드 검색**은 정확한 일치 항목을 찾습니다(ID, 오류 문자열, 구성 키). +- **벡터 검색**은 의미가 비슷한 노트를 찾습니다("gateway host"는 "OpenClaw를 실행하는 머신"과 일치). +- **BM25 키워드 검색**은 정확히 일치하는 항목(ID, 오류 문자열, 구성 키)을 찾습니다. -한 경로만 사용할 수 있는 경우(임베딩 없음 또는 FTS 없음) 다른 경로가 단독으로 실행됩니다. +하나의 경로만 사용할 수 있는 경우(임베딩 없음 또는 FTS 없음), 다른 경로 없이 해당 경로만 실행됩니다. -임베딩을 사용할 수 없을 때도 OpenClaw는 원시 정확 일치 순서로만 대체하지 않고 FTS 결과에 대해 어휘 기반 순위를 사용합니다. 이 저하 모드는 더 강한 쿼리 용어 포괄성과 관련 파일 경로를 가진 청크를 가중하여, `sqlite-vec` 또는 임베딩 제공자가 없어도 회수율을 유용하게 유지합니다. +임베딩을 사용할 수 없을 때도 OpenClaw는 원시 정확 일치 순서만으로 대체하지 않고 FTS 결과에 대해 어휘 기반 랭킹을 사용합니다. 이 성능 저하 모드는 더 강한 쿼리 용어 포함 범위와 관련 파일 경로를 가진 청크의 순위를 높여 `sqlite-vec` 또는 임베딩 provider 없이도 유용한 재현율을 유지합니다. ## 검색 품질 개선 -노트 기록이 많을 때 두 가지 선택 기능이 도움이 됩니다. +대규모 노트 기록이 있을 때 도움이 되는 두 가지 선택적 기능이 있습니다. ### 시간 감쇠 -오래된 노트는 순위 가중치가 점차 낮아져 최근 정보가 먼저 표시됩니다. 기본 반감기인 30일을 사용하면 지난달의 노트는 원래 가중치의 50%로 점수가 매겨집니다. `MEMORY.md` 같은 상시 유지 파일은 감쇠되지 않습니다. +오래된 노트는 점차 랭킹 가중치를 잃어 최신 정보가 먼저 표시됩니다. 기본 반감기 30일을 사용하면 지난달의 노트는 원래 가중치의 50% 점수를 받습니다. `MEMORY.md` 같은 에버그린 파일은 감쇠되지 않습니다. -에이전트에 여러 달 분량의 일일 노트가 있고 오래된 정보가 최근 컨텍스트보다 계속 높은 순위를 차지한다면 시간 감쇠를 활성화하세요. +에이전트에 수개월치 일일 노트가 있고 오래된 정보가 최신 컨텍스트보다 계속 높은 순위를 차지한다면 시간 감쇠를 활성화하세요. ### MMR(다양성) -중복 결과를 줄입니다. 다섯 개의 노트가 모두 같은 라우터 구성을 언급하는 경우, MMR은 상위 결과가 반복되는 대신 서로 다른 주제를 포괄하도록 합니다. +중복 결과를 줄입니다. 다섯 개의 노트가 모두 같은 라우터 구성을 언급하는 경우, MMR은 최상위 결과가 반복되지 않고 서로 다른 주제를 다루도록 보장합니다. `memory_search`가 서로 다른 일일 노트에서 거의 중복되는 스니펫을 계속 반환한다면 MMR을 활성화하세요. @@ -114,30 +114,30 @@ flowchart LR ## 멀티모달 메모리 -Gemini Embedding 2를 사용하면 Markdown과 함께 이미지 및 오디오 파일을 인덱싱할 수 있습니다. 검색 쿼리는 텍스트로 유지되지만 시각 및 오디오 콘텐츠와 일치합니다. 설정은 [메모리 구성 참조](/ko/reference/memory-config)를 확인하세요. +Gemini Embedding 2를 사용하면 Markdown과 함께 이미지 및 오디오 파일을 인덱싱할 수 있습니다. 검색 쿼리는 텍스트로 유지되지만 시각 및 오디오 콘텐츠와 매칭됩니다. 설정은 [메모리 구성 참조](/ko/reference/memory-config)를 참조하세요. ## 세션 메모리 검색 -선택적으로 세션 기록을 인덱싱하여 `memory_search`가 이전 대화를 기억하게 할 수 있습니다. 이는 `memorySearch.experimental.sessionMemory`를 통한 옵트인 기능입니다. 자세한 내용은 [구성 참조](/ko/reference/memory-config)를 확인하세요. +선택적으로 세션 대화 기록을 인덱싱하여 `memory_search`가 이전 대화를 기억하게 할 수 있습니다. 이는 `memorySearch.experimental.sessionMemory`를 통해 옵트인합니다. 자세한 내용은 [구성 참조](/ko/reference/memory-config)를 참조하세요. ## 문제 해결 **결과가 없나요?** 인덱스를 확인하려면 `openclaw memory status`를 실행하세요. 비어 있으면 `openclaw memory index --force`를 실행하세요. -**키워드 일치만 나오나요?** 임베딩 제공자가 구성되지 않았을 수 있습니다. `openclaw memory status --deep`을 확인하세요. +**키워드 일치만 나오나요?** 임베딩 provider가 구성되지 않았을 수 있습니다. `openclaw memory status --deep`을 확인하세요. -**로컬 임베딩 시간이 초과되나요?** `ollama`, `lmstudio`, `local`은 기본적으로 더 긴 인라인 배치 제한 시간을 사용합니다. 호스트가 단순히 느린 경우 `agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds`를 설정하고 `openclaw memory index --force`를 다시 실행하세요. +**로컬 임베딩이 시간 초과되나요?** `ollama`, `lmstudio`, `local`은 기본적으로 더 긴 인라인 배치 시간 제한을 사용합니다. 호스트가 단순히 느린 경우 `agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds`를 설정하고 `openclaw memory index --force`를 다시 실행하세요. **CJK 텍스트를 찾을 수 없나요?** `openclaw memory index --force`로 FTS 인덱스를 다시 빌드하세요. -## 더 읽어보기 +## 추가 자료 - [Active Memory](/ko/concepts/active-memory) -- 대화형 채팅 세션을 위한 하위 에이전트 메모리 - [메모리](/ko/concepts/memory) -- 파일 레이아웃, 백엔드, 도구 - [메모리 구성 참조](/ko/reference/memory-config) -- 모든 구성 옵션 -## 관련 항목 +## 관련 - [메모리 개요](/ko/concepts/memory) -- [Active memory](/ko/concepts/active-memory) +- [Active Memory](/ko/concepts/active-memory) - [내장 메모리 엔진](/ko/concepts/memory-builtin) diff --git a/docs/ko/concepts/messages.md b/docs/ko/concepts/messages.md index e2f9713b8..bafa5e9af 100644 --- a/docs/ko/concepts/messages.md +++ b/docs/ko/concepts/messages.md @@ -1,22 +1,22 @@ --- read_when: - - 인바운드 메시지가 응답으로 바뀌는 방식 설명 - - 세션, 큐잉 모드 또는 스트리밍 동작 명확화 - - 추론 가시성과 사용상의 영향 문서화 -summary: 메시지 흐름, 세션, 큐잉 및 추론 가시성 + - 수신 메시지가 응답으로 변환되는 방식 설명 + - 세션, 대기열 모드 또는 스트리밍 동작 명확히 하기 + - 추론 가시성과 사용 영향 문서화 +summary: 메시지 흐름, 세션, 대기열 처리, 추론 가시성 title: 메시지 x-i18n: - generated_at: "2026-04-30T06:26:53Z" + generated_at: "2026-04-30T16:27:52Z" model: gpt-5.5 provider: openai - source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e + source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9 source_path: concepts/messages.md workflow: 16 --- -OpenClaw는 세션 확인, 대기열 처리, 스트리밍, 도구 실행, 추론 가시성으로 이루어진 파이프라인을 통해 인바운드 메시지를 처리합니다. 이 페이지는 인바운드 메시지에서 답장까지의 경로를 설명합니다. +OpenClaw는 세션 해석, 큐잉, 스트리밍, 도구 실행, 추론 가시성의 파이프라인을 통해 인바운드 메시지를 처리합니다. 이 페이지는 인바운드 메시지에서 응답까지의 경로를 설명합니다. -## 메시지 흐름(개략) +## 메시지 흐름(상위 수준) ``` Inbound message @@ -26,27 +26,23 @@ Inbound message -> outbound replies (channel limits + chunking) ``` -주요 조정값은 설정에 있습니다. +주요 조정 항목은 구성에 있습니다. -- 접두사, 대기열 처리, 그룹 동작에는 `messages.*`를 사용합니다. -- 블록 스트리밍 및 청킹 기본값에는 `agents.defaults.*`를 사용합니다. -- 제한과 스트리밍 토글에는 채널 재정의(`channels.whatsapp.*`, `channels.telegram.*` 등)를 사용합니다. +- 접두사, 큐잉, 그룹 동작은 `messages.*`. +- 블록 스트리밍 및 청킹 기본값은 `agents.defaults.*`. +- 한도와 스트리밍 토글은 채널 재정의(`channels.whatsapp.*`, `channels.telegram.*` 등). -전체 스키마는 [설정](/ko/gateway/configuration)을 참고하세요. +전체 스키마는 [구성](/ko/gateway/configuration)을 참조하세요. ## 인바운드 중복 제거 -채널은 재연결 후 같은 메시지를 다시 전달할 수 있습니다. OpenClaw는 -채널/계정/피어/세션/메시지 ID를 키로 하는 단기 캐시를 유지하여 중복 -전달이 또 다른 에이전트 실행을 트리거하지 않도록 합니다. +채널은 재연결 후 같은 메시지를 다시 전달할 수 있습니다. OpenClaw는 채널/계정/피어/세션/메시지 ID를 키로 하는 단기 캐시를 유지하여 중복 전달이 또 다른 에이전트 실행을 트리거하지 않도록 합니다. ## 인바운드 디바운싱 -**같은 발신자**가 빠르게 연속으로 보낸 메시지는 `messages.inbound`를 통해 단일 -에이전트 턴으로 묶을 수 있습니다. 디바운싱은 채널 + 대화별로 범위가 지정되며 -답장 스레딩/ID에는 가장 최근 메시지를 사용합니다. +**같은 발신자**의 빠른 연속 메시지는 `messages.inbound`를 통해 단일 에이전트 턴으로 묶을 수 있습니다. 디바운싱은 채널 + 대화별로 범위가 지정되며, 응답 스레딩/ID에는 가장 최근 메시지를 사용합니다. -설정(전역 기본값 + 채널별 재정의): +구성(전역 기본값 + 채널별 재정의): ```json5 { @@ -65,98 +61,79 @@ Inbound message 참고: -- 디바운스는 **텍스트 전용** 메시지에 적용되며, 미디어/첨부 파일은 즉시 플러시됩니다. -- 제어 명령은 디바운싱을 우회하므로 독립적으로 유지됩니다. **단**, 채널이 같은 발신자의 DM 병합을 명시적으로 선택한 경우는 예외입니다(예: [BlueBubbles `coalesceSameSenderDms`](/ko/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)). 이 경우 DM 명령은 분할 전송 페이로드가 같은 에이전트 턴에 합류할 수 있도록 디바운스 기간 안에서 대기합니다. +- 디바운스는 **텍스트 전용** 메시지에 적용됩니다. 미디어/첨부 파일은 즉시 플러시됩니다. +- 제어 명령은 독립적으로 유지되도록 디바운싱을 우회합니다. 단, 채널이 같은 발신자 DM 병합을 명시적으로 선택한 경우는 **예외**입니다(예: [BlueBubbles `coalesceSameSenderDms`](/ko/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)). 이 경우 분할 전송 페이로드가 같은 에이전트 턴에 합류할 수 있도록 DM 명령은 디바운스 창 안에서 대기합니다. ## 세션과 기기 세션은 클라이언트가 아니라 Gateway가 소유합니다. -- 직접 채팅은 에이전트 기본 세션 키로 병합됩니다. -- 그룹/채널은 자체 세션 키를 가집니다. -- 세션 저장소와 transcript는 Gateway 호스트에 있습니다. +- 직접 채팅은 에이전트 기본 세션 키로 통합됩니다. +- 그룹/채널은 자체 세션 키를 갖습니다. +- 세션 저장소와 트랜스크립트는 Gateway 호스트에 있습니다. -여러 기기/채널이 같은 세션에 매핑될 수 있지만 기록이 모든 클라이언트로 완전히 -동기화되지는 않습니다. 권장 사항: 긴 대화에서는 컨텍스트 분기를 피하기 위해 -기본 기기 하나를 사용하세요. Control UI와 TUI는 항상 Gateway 기반 세션 -transcript를 표시하므로 진실 공급원입니다. +여러 기기/채널이 같은 세션에 매핑될 수 있지만, 기록이 모든 클라이언트로 완전히 동기화되지는 않습니다. 권장 사항: 긴 대화에서는 컨텍스트가 갈라지는 것을 피하기 위해 하나의 기본 기기를 사용하세요. Control UI와 TUI는 항상 Gateway 기반 세션 트랜스크립트를 표시하므로, 이것이 신뢰할 수 있는 원본입니다. 자세한 내용: [세션 관리](/ko/concepts/session). ## 도구 결과 메타데이터 -도구 결과 `content`는 모델에 보이는 결과입니다. 도구 결과 `details`는 -UI 렌더링, 진단, 미디어 전달, plugins를 위한 런타임 메타데이터입니다. +도구 결과 `content`는 모델에 표시되는 결과입니다. 도구 결과 `details`는 UI 렌더링, 진단, 미디어 전달, Plugin을 위한 런타임 메타데이터입니다. OpenClaw는 이 경계를 명시적으로 유지합니다. -- `toolResult.details`는 제공자 재생과 Compaction 입력 전에 제거됩니다. -- 저장된 세션 transcript는 제한된 `details`만 유지합니다. 너무 큰 메타데이터는 - `persistedDetailsTruncated: true`로 표시된 간결한 요약으로 대체됩니다. -- plugins와 도구는 모델이 읽어야 하는 텍스트를 `details`에만 두지 말고 `content`에 넣어야 합니다. +- `toolResult.details`는 provider 재생 및 Compaction 입력 전에 제거됩니다. +- 영구 저장된 세션 트랜스크립트는 제한된 `details`만 유지합니다. 너무 큰 메타데이터는 `persistedDetailsTruncated: true`로 표시된 간결한 요약으로 대체됩니다. +- Plugin과 도구는 모델이 읽어야 하는 텍스트를 `details`에만 두지 말고 `content`에 넣어야 합니다. ## 인바운드 본문과 기록 컨텍스트 OpenClaw는 **프롬프트 본문**과 **명령 본문**을 분리합니다. -- `Body`: 에이전트로 전송되는 프롬프트 텍스트입니다. 여기에는 채널 봉투와 - 선택적 기록 래퍼가 포함될 수 있습니다. -- `CommandBody`: 지시문/명령 구문 분석에 사용하는 원시 사용자 텍스트입니다. -- `RawBody`: `CommandBody`의 레거시 별칭입니다(호환성을 위해 유지). +- `BodyForAgent`: 현재 메시지의 기본 모델 대상 텍스트입니다. 채널 Plugin은 발신자의 현재 프롬프트 포함 텍스트에 집중되도록 유지해야 합니다. +- `Body`: 레거시 프롬프트 대체값입니다. 채널 봉투와 선택적 기록 래퍼를 포함할 수 있지만, 현재 채널은 `BodyForAgent`를 사용할 수 있을 때 이를 기본 모델 입력으로 의존해서는 안 됩니다. +- `CommandBody`: 지시문/명령 파싱을 위한 원시 사용자 텍스트입니다. +- `RawBody`: `CommandBody`의 레거시 별칭입니다(호환성을 위해 유지됨). 채널이 기록을 제공할 때는 공유 래퍼를 사용합니다. - `[Chat messages since your last reply - for context]` - `[Current message - respond to this]` -**비직접 채팅**(그룹/채널/방)의 경우 **현재 메시지 본문** 앞에는 -발신자 레이블이 붙습니다(기록 항목에 사용되는 것과 같은 스타일). 이렇게 하면 에이전트 프롬프트에서 실시간 메시지와 대기열/기록 -메시지가 일관되게 유지됩니다. +**비직접 채팅**(그룹/채널/룸)의 경우 **현재 메시지 본문**에는 발신자 레이블이 접두사로 붙습니다(기록 항목에 사용되는 것과 같은 스타일). 이렇게 하면 에이전트 프롬프트에서 실시간 메시지와 큐/기록 메시지가 일관되게 유지됩니다. -기록 버퍼는 **보류 중인 항목 전용**입니다. 여기에는 실행을 트리거하지 _않은_ -그룹 메시지(예: 멘션으로 제한된 메시지)가 포함되며, 세션 transcript에 이미 있는 -메시지는 **제외**됩니다. +기록 버퍼는 **대기 중 항목 전용**입니다. 실행을 트리거하지 _않은_ 그룹 메시지(예: 멘션 게이트 메시지)를 포함하고, 세션 트랜스크립트에 이미 있는 메시지는 **제외**합니다. -지시문 제거는 **현재 메시지** 섹션에만 적용되므로 기록은 그대로 유지됩니다. -기록을 래핑하는 채널은 `CommandBody`(또는 `RawBody`)를 원래 메시지 텍스트로 설정하고 -`Body`는 결합된 프롬프트로 유지해야 합니다. -기록 버퍼는 `messages.groupChat.historyLimit`(전역 -기본값)과 `channels.slack.historyLimit` 또는 -`channels.telegram.accounts..historyLimit` 같은 채널별 재정의로 설정할 수 있습니다(`0`으로 설정하면 비활성화). +지시문 제거는 **현재 메시지** 섹션에만 적용되므로 기록은 그대로 유지됩니다. 기록을 래핑하는 채널은 `CommandBody`(또는 `RawBody`)를 원래 메시지 텍스트로 설정하고 `Body`는 결합된 프롬프트로 유지해야 합니다. 구조화된 기록, 응답, 전달됨, 채널 메타데이터는 프롬프트 조립 중 사용자 역할의 신뢰할 수 없는 컨텍스트 블록으로 렌더링됩니다. +기록 버퍼는 `messages.groupChat.historyLimit`(전역 기본값) 및 `channels.slack.historyLimit` 또는 `channels.telegram.accounts..historyLimit` 같은 채널별 재정의로 구성할 수 있습니다(비활성화하려면 `0`으로 설정). -## 대기열 처리와 후속 작업 +## 큐잉과 후속 처리 -실행이 이미 활성 상태인 경우, 인바운드 메시지는 대기열에 넣거나 -현재 실행으로 조향하거나 후속 턴을 위해 수집할 수 있습니다. +실행이 이미 활성 상태인 경우, 인바운드 메시지는 큐에 넣거나, 현재 실행으로 유도하거나, 후속 턴을 위해 수집할 수 있습니다. -- `messages.queue`(및 `messages.queue.byChannel`)로 설정합니다. -- 기본 모드는 `steer`이며, 조향이 대기열 기반 후속 전달로 폴백될 때 - 500ms 후속 디바운스를 사용합니다. -- 모드: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt`, 그리고 - 레거시 한 번에 하나씩 처리하는 `queue` 모드입니다. +- `messages.queue`(및 `messages.queue.byChannel`)를 통해 구성합니다. +- 기본 모드는 `steer`이며, 유도가 큐에 넣은 후속 전달로 폴백될 때 500ms 후속 디바운스가 적용됩니다. +- 모드: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt`, 그리고 레거시 한 번에 하나씩 처리하는 `queue` 모드. -자세한 내용: [명령 대기열](/ko/concepts/queue) 및 [조향 대기열](/ko/concepts/queue-steering). +자세한 내용: [명령 큐](/ko/concepts/queue) 및 [Steering 큐](/ko/concepts/queue-steering). ## 채널 실행 소유권 -채널 plugins는 메시지가 세션 대기열에 들어가기 전에 순서를 보존하고, 입력을 디바운스하고, 전송 계층 -백프레셔를 적용할 수 있습니다. 에이전트 턴 자체에 별도의 제한 시간을 부과해서는 안 됩니다. 메시지가 -세션으로 라우팅되면 오래 실행되는 작업은 세션, 도구, 런타임 -수명 주기가 관장하므로 모든 채널이 느린 턴을 일관되게 보고하고 복구합니다. +채널 Plugin은 메시지가 세션 큐에 들어가기 전에 순서 보존, 입력 디바운스, 전송 백프레셔 적용을 수행할 수 있습니다. 에이전트 턴 자체에 별도의 타임아웃을 부과해서는 안 됩니다. 메시지가 세션으로 라우팅되면 장시간 실행 작업은 세션, 도구, 런타임 수명 주기에 의해 관리되므로 모든 채널이 느린 턴을 일관되게 보고하고 복구합니다. ## 스트리밍, 청킹, 배칭 -블록 스트리밍은 모델이 텍스트 블록을 생성하는 동안 부분 답장을 보냅니다. -청킹은 채널 텍스트 제한을 준수하며 fenced code를 나누지 않습니다. +블록 스트리밍은 모델이 텍스트 블록을 생성할 때 부분 응답을 전송합니다. +청킹은 채널 텍스트 제한을 준수하고 fenced code 분할을 피합니다. 주요 설정: -- `agents.defaults.blockStreamingDefault`(`on|off`, 기본값 꺼짐) +- `agents.defaults.blockStreamingDefault`(`on|off`, 기본값 off) - `agents.defaults.blockStreamingBreak`(`text_end|message_end`) - `agents.defaults.blockStreamingChunk`(`minChars|maxChars|breakPreference`) - `agents.defaults.blockStreamingCoalesce`(유휴 기반 배칭) -- `agents.defaults.humanDelay`(블록 답장 사이의 사람 같은 일시 중지) -- 채널 재정의: `*.blockStreaming` 및 `*.blockStreamingCoalesce`(Telegram이 아닌 채널은 명시적 `*.blockStreaming: true`가 필요) +- `agents.defaults.humanDelay`(블록 응답 사이의 사람 같은 일시 정지) +- 채널 재정의: `*.blockStreaming` 및 `*.blockStreamingCoalesce`(Telegram이 아닌 채널은 명시적인 `*.blockStreaming: true` 필요) 자세한 내용: [스트리밍 + 청킹](/ko/concepts/streaming). @@ -165,47 +142,39 @@ OpenClaw는 **프롬프트 본문**과 **명령 본문**을 분리합니다. OpenClaw는 모델 추론을 노출하거나 숨길 수 있습니다. - `/reasoning on|off|stream`은 가시성을 제어합니다. -- 추론 콘텐츠는 모델이 생성할 때 토큰 사용량에 계속 포함됩니다. -- Telegram은 초안 말풍선으로 추론 스트림을 지원합니다. +- 모델이 생성한 추론 콘텐츠는 여전히 토큰 사용량에 포함됩니다. +- Telegram은 추론 스트림을 초안 말풍선으로 보내는 기능을 지원합니다. 자세한 내용: [사고 + 추론 지시문](/ko/tools/thinking) 및 [토큰 사용](/ko/reference/token-use). -## 접두사, 스레딩, 답장 +## 접두사, 스레딩, 응답 아웃바운드 메시지 형식은 `messages`에 중앙화되어 있습니다. - `messages.responsePrefix`, `channels..responsePrefix`, `channels..accounts..responsePrefix`(아웃바운드 접두사 계단식 적용), 그리고 `channels.whatsapp.messagePrefix`(WhatsApp 인바운드 접두사) -- `replyToMode`와 채널별 기본값을 통한 답장 스레딩 +- `replyToMode` 및 채널별 기본값을 통한 응답 스레딩 -자세한 내용: [설정](/ko/gateway/config-agents#messages) 및 채널 문서. +자세한 내용: [구성](/ko/gateway/config-agents#messages) 및 채널 문서. -## 무음 답장 +## 무음 응답 -정확한 무음 토큰 `NO_REPLY` / `no_reply`는 “사용자에게 보이는 답장을 전달하지 않음”을 의미합니다. -턴에 생성된 TTS 오디오 같은 보류 중인 도구 미디어도 있는 경우 OpenClaw는 -무음 텍스트를 제거하지만 미디어 첨부 파일은 계속 전달합니다. -OpenClaw는 대화 유형별로 그 동작을 결정합니다. +정확한 무음 토큰 `NO_REPLY` / `no_reply`는 “사용자에게 보이는 응답을 전달하지 않음”을 의미합니다. +턴에 생성된 TTS 오디오 같은 대기 중인 도구 미디어도 있을 경우, OpenClaw는 무음 텍스트를 제거하지만 미디어 첨부 파일은 계속 전달합니다. +OpenClaw는 대화 유형에 따라 이 동작을 해석합니다. -- 직접 대화는 기본적으로 무음을 허용하지 않으며, 무음 답장만 있는 경우 - 짧은 가시적 폴백으로 다시 씁니다. +- 직접 대화는 기본적으로 무음을 허용하지 않으며, 단독 무음 응답을 짧고 표시되는 대체 응답으로 다시 작성합니다. - 그룹/채널은 기본적으로 무음을 허용합니다. - 내부 오케스트레이션은 기본적으로 무음을 허용합니다. -OpenClaw는 비직접 채팅에서 어시스턴트 답장이 있기 전에 발생하는 내부 러너 실패에도 -무음 답장을 사용하므로 그룹/채널에 Gateway 오류 상용구가 표시되지 않습니다. 직접 채팅은 기본적으로 -간결한 실패 문구를 표시하며, 원시 러너 세부 정보는 `/verbose`가 `on` 또는 `full`일 때만 표시됩니다. +OpenClaw는 비직접 채팅에서 assistant 응답이 발생하기 전에 생기는 내부 runner 실패에도 무음 응답을 사용하므로, 그룹/채널에는 Gateway 오류 상용 문구가 표시되지 않습니다. 직접 채팅은 기본적으로 간결한 실패 문구를 표시합니다. 원시 runner 세부 정보는 `/verbose`가 `on` 또는 `full`일 때만 표시됩니다. -기본값은 `agents.defaults.silentReply` 및 -`agents.defaults.silentReplyRewrite` 아래에 있으며, `surfaces..silentReply` 및 -`surfaces..silentReplyRewrite`가 표면별로 이를 재정의할 수 있습니다. +기본값은 `agents.defaults.silentReply` 및 `agents.defaults.silentReplyRewrite` 아래에 있으며, `surfaces..silentReply` 및 `surfaces..silentReplyRewrite`는 표면별로 이를 재정의할 수 있습니다. -상위 세션에 보류 중인 생성된 하위 에이전트 실행이 하나 이상 있는 경우, 무음 답장만 있는 응답은 -다시 쓰이지 않고 모든 표면에서 삭제됩니다. 따라서 하위 완료 이벤트가 실제 답장을 전달할 때까지 -상위는 조용히 유지됩니다. +상위 세션에 대기 중인 spawned 하위 에이전트 실행이 하나 이상 있는 경우, 단독 무음 응답은 다시 작성되지 않고 모든 표면에서 삭제됩니다. 그래서 자식 완료 이벤트가 실제 응답을 전달할 때까지 상위 세션은 조용히 유지됩니다. ## 관련 항목 - [스트리밍](/ko/concepts/streaming) — 실시간 메시지 전달 - [재시도](/ko/concepts/retry) — 메시지 전달 재시도 동작 -- [대기열](/ko/concepts/queue) — 메시지 처리 대기열 +- [큐](/ko/concepts/queue) — 메시지 처리 큐 - [채널](/ko/channels) — 메시징 플랫폼 통합 diff --git a/docs/ko/gateway/config-agents.md b/docs/ko/gateway/config-agents.md index dcd33e0b4..b699231c8 100644 --- a/docs/ko/gateway/config-agents.md +++ b/docs/ko/gateway/config-agents.md @@ -1,22 +1,24 @@ --- read_when: - - 에이전트 기본값 조정(모델, 사고, 작업 영역, Heartbeat, 미디어, Skills) - - 멀티 에이전트 라우팅 및 바인딩 구성 + - 에이전트 기본값 조정(모델, 추론, 작업 영역, Heartbeat, 미디어, Skills) + - 다중 에이전트 라우팅 및 바인딩 구성 - 세션, 메시지 전달 및 대화 모드 동작 조정 summary: 에이전트 기본값, 다중 에이전트 라우팅, 세션, 메시지 및 대화 구성 title: 구성 — 에이전트 x-i18n: - generated_at: "2026-04-30T06:29:18Z" + generated_at: "2026-04-30T16:27:59Z" model: gpt-5.5 provider: openai - source_hash: 61f2d33ae1d3f4ce07636ae4584b9e344fd14e8e08a2612bb1f39ed71c99c25a + source_hash: e6a38f42c35c6c6e46d6d00ad710c6c80d78703e0b7e3388f5631cf91eb17084 source_path: gateway/config-agents.md workflow: 16 --- -`agents.*`, `multiAgent.*`, `session.*`, `messages.*`, `talk.*` 아래의 에이전트 범위 구성 키입니다. 채널, 도구, Gateway 런타임 및 기타 최상위 키는 [구성 참조](/ko/gateway/configuration-reference)를 참조하세요. +`agents.*`, `multiAgent.*`, `session.*`, +`messages.*`, `talk.*` 아래의 Agent 범위 구성 키입니다. 채널, 도구, Gateway 런타임 및 기타 +최상위 키는 [구성 참조](/ko/gateway/configuration-reference)를 참조하세요. -## 에이전트 기본값 +## Agent 기본값 ### `agents.defaults.workspace` @@ -30,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -시스템 프롬프트의 런타임 줄에 표시되는 선택적 리포지토리 루트입니다. 설정하지 않으면 OpenClaw가 작업 공간에서 위쪽으로 탐색하여 자동 감지합니다. +시스템 프롬프트의 Runtime 줄에 표시되는 선택적 저장소 루트입니다. 설정하지 않으면 OpenClaw가 작업 공간에서 위로 올라가며 자동 감지합니다. ```json5 { @@ -40,29 +42,29 @@ x-i18n: ### `agents.defaults.skills` -`agents.list[].skills`를 설정하지 않은 에이전트를 위한 선택적 기본 Skills 허용 목록입니다. +`agents.list[].skills`를 설정하지 않은 Agent를 위한 선택적 기본 skill 허용 목록입니다. ```json5 { agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // github, weather 상속 - { id: "docs", skills: ["docs-search"] }, // 기본값 대체 - { id: "locked-down", skills: [] }, // skills 없음 + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` -- 기본적으로 제한 없는 skills를 사용하려면 `agents.defaults.skills`를 생략하세요. +- 기본적으로 Skills를 제한하지 않으려면 `agents.defaults.skills`를 생략하세요. - 기본값을 상속하려면 `agents.list[].skills`를 생략하세요. -- skills가 없도록 하려면 `agents.list[].skills: []`를 설정하세요. -- 비어 있지 않은 `agents.list[].skills` 목록은 해당 에이전트의 최종 집합입니다. 기본값과 병합되지 않습니다. +- Skills를 사용하지 않으려면 `agents.list[].skills: []`로 설정하세요. +- 비어 있지 않은 `agents.list[].skills` 목록은 해당 Agent의 최종 집합입니다. 기본값과 병합되지 않습니다. ### `agents.defaults.skipBootstrap` -작업 공간 부트스트랩 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`) 자동 생성을 비활성화합니다. +작업 공간 부트스트랩 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`)의 자동 생성을 비활성화합니다. ```json5 { @@ -74,8 +76,8 @@ x-i18n: 작업 공간 부트스트랩 파일을 시스템 프롬프트에 주입하는 시점을 제어합니다. 기본값: `"always"`. -- `"continuation-skip"`: 안전한 계속 턴(완료된 어시스턴트 응답 이후)은 작업 공간 부트스트랩 재주입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행 및 Compaction 이후 재시도는 여전히 컨텍스트를 다시 빌드합니다. -- `"never"`: 모든 턴에서 작업 공간 부트스트랩 및 컨텍스트 파일 주입을 비활성화합니다. 프롬프트 수명 주기를 완전히 자체적으로 소유하는 에이전트(사용자 지정 컨텍스트 엔진, 자체 컨텍스트를 빌드하는 네이티브 런타임, 또는 특수한 부트스트랩 없는 워크플로)에만 사용하세요. Heartbeat 및 Compaction 복구 턴도 주입을 건너뜁니다. +- `"continuation-skip"`: 안전한 이어서 진행 턴(완료된 assistant 응답 이후)은 작업 공간 부트스트랩 재주입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행 및 Compaction 이후 재시도는 여전히 컨텍스트를 다시 빌드합니다. +- `"never"`: 모든 턴에서 작업 공간 부트스트랩 및 컨텍스트 파일 주입을 비활성화합니다. 자신의 프롬프트 수명 주기를 완전히 소유하는 Agent(사용자 지정 컨텍스트 엔진, 자체 컨텍스트를 빌드하는 네이티브 런타임, 또는 특수한 부트스트랩 없는 워크플로)에만 사용하세요. Heartbeat 및 Compaction 복구 턴도 주입을 건너뜁니다. ```json5 { @@ -105,12 +107,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -부트스트랩 컨텍스트가 잘릴 때 에이전트에 표시되는 경고 텍스트를 제어합니다. +부트스트랩 컨텍스트가 잘렸을 때 Agent에게 표시되는 경고 텍스트를 제어합니다. 기본값: `"once"`. - `"off"`: 시스템 프롬프트에 경고 텍스트를 절대 주입하지 않습니다. -- `"once"`: 고유한 잘림 시그니처당 한 번 경고를 주입합니다(권장). -- `"always"`: 잘림이 있으면 실행할 때마다 경고를 주입합니다. +- `"once"`: 고유한 잘림 시그니처마다 경고를 한 번 주입합니다(권장). +- `"always"`: 잘림이 있을 때마다 모든 실행에서 경고를 주입합니다. ```json5 { @@ -120,29 +122,32 @@ x-i18n: ### 컨텍스트 예산 소유권 맵 -OpenClaw에는 여러 대용량 프롬프트/컨텍스트 예산이 있으며, 하나의 일반 노브로 모두 흐르게 하지 않고 의도적으로 하위 시스템별로 분리되어 있습니다. +OpenClaw에는 대용량 프롬프트/컨텍스트 예산이 여러 개 있으며, 하나의 일반적인 +노브를 모두 통과하게 하는 대신 의도적으로 하위 시스템별로 나뉩니다. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - 일반 작업 공간 부트스트랩 주입. + 일반 작업 공간 부트스트랩 주입입니다. - `agents.defaults.startupContext.*`: - 최근 일별 `memory/*.md` 파일을 포함하는 1회성 reset/startup 모델 실행 프렐류드. 단순 채팅 `/new` 및 `/reset` 명령은 모델을 호출하지 않고 확인됩니다. + 최근 일일 `memory/*.md` 파일을 포함한 일회성 reset/startup 모델 실행 프리루드입니다. + 일반 채팅 `/new` 및 `/reset` 명령은 모델을 호출하지 않고 확인 응답됩니다. - `skills.limits.*`: - 시스템 프롬프트에 주입되는 압축된 skills 목록. + 시스템 프롬프트에 주입되는 압축된 Skills 목록입니다. - `agents.defaults.contextLimits.*`: - 제한된 런타임 발췌와 런타임 소유 주입 블록. + 제한된 런타임 발췌와 런타임 소유 주입 블록입니다. - `memory.qmd.limits.*`: - 인덱싱된 메모리 검색 스니펫 및 주입 크기. + 인덱싱된 메모리 검색 스니펫 및 주입 크기입니다. -한 에이전트에 다른 예산이 필요할 때만 일치하는 에이전트별 재정의를 사용하세요. +한 Agent에 다른 예산이 필요할 때만 일치하는 Agent별 재정의를 사용하세요. - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -reset/startup 모델 실행 시 첫 번째 턴에 주입되는 시작 프렐류드를 제어합니다. -단순 채팅 `/new` 및 `/reset` 명령은 모델을 호출하지 않고 reset을 확인하므로 이 프렐류드를 로드하지 않습니다. +reset/startup 모델 실행에서 주입되는 첫 턴 시작 프리루드를 제어합니다. +일반 채팅 `/new` 및 `/reset` 명령은 모델을 호출하지 않고 reset을 확인 응답하므로, +이 프리루드를 로드하지 않습니다. ```json5 { @@ -163,7 +168,7 @@ reset/startup 모델 실행 시 첫 번째 턴에 주입되는 시작 프렐류 #### `agents.defaults.contextLimits` -제한된 런타임 컨텍스트 표면에 대한 공유 기본값입니다. +제한된 런타임 컨텍스트 표면의 공유 기본값입니다. ```json5 { @@ -180,14 +185,15 @@ reset/startup 모델 실행 시 첫 번째 턴에 주입되는 시작 프렐류 } ``` -- `memoryGetMaxChars`: 잘림 메타데이터와 계속 알림이 추가되기 전 기본 `memory_get` 발췌 상한입니다. -- `memoryGetDefaultLines`: `lines`가 생략되었을 때 기본 `memory_get` 줄 창입니다. -- `toolResultMaxChars`: 지속된 결과와 오버플로 복구에 사용되는 라이브 도구 결과 상한입니다. +- `memoryGetMaxChars`: 잘림 메타데이터와 이어서 진행 알림이 추가되기 전 기본 `memory_get` 발췌 상한입니다. +- `memoryGetDefaultLines`: `lines`가 생략되었을 때 기본 `memory_get` 줄 범위입니다. +- `toolResultMaxChars`: 지속 저장된 결과와 오버플로 복구에 사용되는 라이브 도구 결과 상한입니다. - `postCompactionMaxChars`: Compaction 이후 새로 고침 주입 중 사용되는 AGENTS.md 발췌 상한입니다. #### `agents.list[].contextLimits` -공유 `contextLimits` 노브에 대한 에이전트별 재정의입니다. 생략된 필드는 `agents.defaults.contextLimits`에서 상속됩니다. +공유 `contextLimits` 노브에 대한 Agent별 재정의입니다. 생략된 필드는 +`agents.defaults.contextLimits`에서 상속됩니다. ```json5 { @@ -213,7 +219,7 @@ reset/startup 모델 실행 시 첫 번째 턴에 주입되는 시작 프렐류 #### `skills.limits.maxSkillsPromptChars` -시스템 프롬프트에 주입되는 압축된 skills 목록의 전역 상한입니다. 이는 요청 시 `SKILL.md` 파일을 읽는 데 영향을 주지 않습니다. +시스템 프롬프트에 주입되는 압축된 Skills 목록의 전역 상한입니다. 이는 필요 시 `SKILL.md` 파일을 읽는 데 영향을 주지 않습니다. ```json5 { @@ -227,7 +233,7 @@ reset/startup 모델 실행 시 첫 번째 턴에 주입되는 시작 프렐류 #### `agents.list[].skillsLimits.maxSkillsPromptChars` -skills 프롬프트 예산에 대한 에이전트별 재정의입니다. +Skills 프롬프트 예산에 대한 Agent별 재정의입니다. ```json5 { @@ -246,11 +252,11 @@ skills 프롬프트 예산에 대한 에이전트별 재정의입니다. ### `agents.defaults.imageMaxDimensionPx` -제공자 호출 전에 트랜스크립트/도구 이미지 블록에서 이미지의 가장 긴 변에 대한 최대 픽셀 크기입니다. +provider 호출 전 transcript/도구 이미지 블록에서 가장 긴 이미지 변의 최대 픽셀 크기입니다. 기본값: `1200`. -값을 낮추면 일반적으로 스크린샷이 많은 실행에서 비전 토큰 사용량과 요청 페이로드 크기가 줄어듭니다. -값을 높이면 더 많은 시각적 세부 정보가 보존됩니다. +값이 낮을수록 일반적으로 스크린샷이 많은 실행에서 vision-token 사용량과 요청 페이로드 크기가 줄어듭니다. +값이 높을수록 더 많은 시각적 세부 정보가 보존됩니다. ```json5 { @@ -260,7 +266,7 @@ skills 프롬프트 예산에 대한 에이전트별 재정의입니다. ### `agents.defaults.userTimezone` -시스템 프롬프트 컨텍스트의 시간대입니다(메시지 타임스탬프 아님). 호스트 시간대로 대체됩니다. +시스템 프롬프트 컨텍스트의 시간대입니다(메시지 타임스탬프가 아님). 호스트 시간대로 대체됩니다. ```json5 { @@ -270,7 +276,7 @@ skills 프롬프트 예산에 대한 에이전트별 재정의입니다. ### `agents.defaults.timeFormat` -시스템 프롬프트의 시간 형식입니다. 기본값: `auto`(OS 환경설정). +시스템 프롬프트의 시간 형식입니다. 기본값: `auto`(OS 기본 설정). ```json5 { @@ -308,9 +314,9 @@ skills 프롬프트 예산에 대한 에이전트별 재정의입니다. primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // 전역 기본 제공자 params + params: { cacheRetention: "long" }, // global default provider params agentRuntime: { - id: "pi", // pi | auto | 등록된 하니스 id, 예: codex + id: "pi", // pi | auto | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -328,57 +334,57 @@ skills 프롬프트 예산에 대한 에이전트별 재정의입니다. } ``` -- `model`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 허용합니다. +- `model`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받습니다. - 문자열 형식은 기본 모델만 설정합니다. - 객체 형식은 기본 모델과 순서가 있는 장애 조치 모델을 설정합니다. -- `imageModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 허용합니다. +- `imageModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받습니다. - `image` 도구 경로에서 비전 모델 구성으로 사용됩니다. - - 선택된/기본 모델이 이미지 입력을 받을 수 없을 때 대체 라우팅에도 사용됩니다. - - 명시적인 `provider/model` 참조를 선호하세요. 기본 ID는 호환성을 위해 허용됩니다. 기본 ID가 `models.providers.*.models`에서 구성된 이미지 지원 항목과 고유하게 일치하면, OpenClaw가 해당 provider로 한정합니다. 구성된 일치 항목이 모호하면 명시적인 provider 접두사가 필요합니다. -- `imageGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 허용합니다. + - 선택한/기본 모델이 이미지 입력을 받을 수 없을 때 대체 라우팅으로도 사용됩니다. + - 명시적인 `provider/model` 참조를 권장합니다. 단순 ID는 호환성을 위해 허용됩니다. 단순 ID가 `models.providers.*.models`에 구성된 이미지 지원 항목 하나와 고유하게 일치하면 OpenClaw가 해당 제공자로 한정합니다. 구성된 일치 항목이 모호하면 명시적인 제공자 접두사가 필요합니다. +- `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-2`, 투명 배경 OpenAI PNG/WebP 출력에는 `openai/gpt-image-1.5`. - - provider/model을 직접 선택하는 경우 일치하는 provider 인증도 구성하세요(예: `google/*`에는 `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`, `openai/gpt-image-2` / `openai/gpt-image-1.5`에는 `OPENAI_API_KEY` 또는 OpenAI Codex OAuth, `fal/*`에는 `FAL_KEY`). - - 생략하면 `image_generate`는 인증 기반 provider 기본값을 여전히 추론할 수 있습니다. 현재 기본 provider를 먼저 시도한 다음, 나머지 등록된 이미지 생성 provider를 provider-id 순서로 시도합니다. -- `musicGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 허용합니다. - - 공유 음악 생성 기능과 기본 제공 `music_generate` 도구에서 사용됩니다. - - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` 또는 `minimax/music-2.6`. - - 생략하면 `music_generate`는 인증 기반 provider 기본값을 여전히 추론할 수 있습니다. 현재 기본 provider를 먼저 시도한 다음, 나머지 등록된 음악 생성 provider를 provider-id 순서로 시도합니다. - - 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` 옵션을 지원합니다. -- `pdfModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 허용합니다. + - 제공자/모델을 직접 선택하는 경우 일치하는 제공자 인증도 구성하세요. 예: `google/*`에는 `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`, `openai/gpt-image-2` / `openai/gpt-image-1.5`에는 `OPENAI_API_KEY` 또는 OpenAI Codex OAuth, `fal/*`에는 `FAL_KEY`. + - 생략하면 `image_generate`가 인증 기반 제공자 기본값을 계속 추론할 수 있습니다. 현재 기본 제공자를 먼저 시도한 다음, 나머지 등록된 이미지 생성 제공자를 제공자 ID 순서로 시도합니다. +- `musicGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받습니다. + - 공유 음악 생성 기능과 내장 `music_generate` 도구에서 사용됩니다. + - 일반적인 값: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview`, 또는 `minimax/music-2.6`. + - 생략하면 `music_generate`가 인증 기반 제공자 기본값을 계속 추론할 수 있습니다. 현재 기본 제공자를 먼저 시도한 다음, 나머지 등록된 음악 생성 제공자를 제공자 ID 순서로 시도합니다. + - 제공자/모델을 직접 선택하는 경우 일치하는 제공자 인증/API 키도 구성하세요. +- `videoGenerationModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받습니다. + - 공유 비디오 생성 기능과 내장 `video_generate` 도구에서 사용됩니다. + - 일반적인 값: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash`, 또는 `qwen/wan2.7-r2v`. + - 생략하면 `video_generate`가 인증 기반 제공자 기본값을 계속 추론할 수 있습니다. 현재 기본 제공자를 먼저 시도한 다음, 나머지 등록된 비디오 생성 제공자를 제공자 ID 순서로 시도합니다. + - 제공자/모델을 직접 선택하는 경우 일치하는 제공자 인증/API 키도 구성하세요. + - 번들 Qwen 비디오 생성 제공자는 최대 출력 비디오 1개, 입력 이미지 1개, 입력 비디오 4개, 10초 길이, 그리고 제공자 수준의 `size`, `aspectRatio`, `resolution`, `audio`, `watermark` 옵션을 지원합니다. +- `pdfModel`: 문자열(`"provider/model"`) 또는 객체(`{ primary, fallbacks }`)를 받습니다. - `pdf` 도구의 모델 라우팅에 사용됩니다. - - 생략하면 PDF 도구는 `imageModel`로, 그다음 해석된 세션/기본 모델로 대체됩니다. + - 생략하면 PDF 도구는 `imageModel`로 대체하고, 그다음 해석된 세션/기본 모델로 대체합니다. - `pdfMaxBytesMb`: 호출 시점에 `maxBytesMb`가 전달되지 않았을 때 `pdf` 도구의 기본 PDF 크기 제한입니다. -- `pdfMaxPages`: `pdf` 도구에서 추출 fallback 모드가 고려하는 기본 최대 페이지 수입니다. -- `verboseDefault`: 에이전트의 기본 상세 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. -- `reasoningDefault`: 에이전트의 기본 reasoning 표시 여부입니다. 값: `"off"`, `"on"`, `"stream"`. 에이전트별 `agents.list[].reasoningDefault`는 이 기본값을 재정의합니다. 구성된 reasoning 기본값은 메시지별 또는 세션 reasoning 재정의가 설정되지 않은 경우에만 소유자, 승인된 발신자 또는 operator-admin Gateway 컨텍스트에 적용됩니다. -- `elevatedDefault`: 에이전트의 기본 elevated-output 수준입니다. 값: `"off"`, `"on"`, `"ask"`, `"full"`. 기본값: `"on"`. -- `model.primary`: 형식은 `provider/model`입니다(예: API 키 액세스에는 `openai/gpt-5.5`, Codex OAuth에는 `openai-codex/gpt-5.5`). provider를 생략하면 OpenClaw는 먼저 alias를 시도한 다음, 해당 정확한 모델 ID와 고유하게 일치하는 구성된 provider를 시도하고, 그 후에야 구성된 기본 provider로 대체됩니다(더 이상 권장되지 않는 호환성 동작이므로 명시적인 `provider/model`을 선호하세요). 해당 provider가 구성된 기본 모델을 더 이상 노출하지 않으면 OpenClaw는 오래되어 제거된 provider 기본값을 표시하는 대신 처음 구성된 provider/model로 대체됩니다. -- `models`: `/model`에 대해 구성된 모델 카탈로그와 허용 목록입니다. 각 항목에는 `alias`(바로가기)와 `params`(provider별 항목, 예: `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`)가 포함될 수 있습니다. - - 안전한 편집: 항목을 추가하려면 `openclaw config set agents.defaults.models '' --strict-json --merge`를 사용하세요. 기존 허용 목록 항목을 제거하는 교체는 `--replace`를 전달하지 않는 한 `config set`에서 거부됩니다. - - provider 범위 configure/onboarding 흐름은 선택한 provider 모델을 이 맵에 병합하고 이미 구성된 관련 없는 provider를 보존합니다. - - 직접 OpenAI Responses 모델의 경우 서버 측 Compaction이 자동으로 활성화됩니다. `context_management` 주입을 중지하려면 `params.responsesServerCompaction: false`를 사용하고, 임계값을 재정의하려면 `params.responsesCompactThreshold`를 사용하세요. [OpenAI 서버 측 Compaction](/ko/providers/openai#server-side-compaction-responses-api)을 참조하세요. -- `params`: 모든 모델에 적용되는 전역 기본 provider 매개변수입니다. `agents.defaults.params`에서 설정합니다(예: `{ cacheRetention: "long" }`). -- `params` 병합 우선순위(구성): `agents.defaults.params`(전역 기반)는 `agents.defaults.models["provider/model"].params`(모델별)에 의해 재정의되고, 그다음 `agents.list[].params`(일치하는 에이전트 ID)가 키별로 재정의합니다. 자세한 내용은 [프롬프트 캐싱](/ko/reference/prompt-caching)을 참조하세요. -- `params.extra_body`/`params.extraBody`: OpenAI 호환 프록시를 위해 `api: "openai-completions"` 요청 본문에 병합되는 고급 pass-through JSON입니다. 생성된 요청 키와 충돌하면 extra body가 우선합니다. 네이티브가 아닌 completions 경로는 이후에도 OpenAI 전용 `store`를 제거합니다. -- `params.chat_template_kwargs`: 최상위 `api: "openai-completions"` 요청 본문에 병합되는 vLLM/OpenAI 호환 chat-template 인수입니다. thinking이 꺼진 `vllm/nemotron-3-*`의 경우 번들 vLLM Plugin이 자동으로 `enable_thinking: false`와 `force_nonempty_content: true`를 보냅니다. 명시적인 `chat_template_kwargs`는 생성된 기본값을 재정의하고, `extra_body.chat_template_kwargs`가 여전히 최종 우선순위를 가집니다. vLLM Qwen thinking 제어의 경우 해당 모델 항목에서 `params.qwenThinkingFormat`을 `"chat-template"` 또는 `"top-level"`로 설정하세요. -- `compat.supportedReasoningEfforts`: 모델별 OpenAI 호환 reasoning effort 목록입니다. 실제로 이를 허용하는 사용자 지정 엔드포인트에는 `"xhigh"`를 포함하세요. 그러면 OpenClaw가 해당 구성된 provider/model에 대해 명령 메뉴, Gateway 세션 행, 세션 패치 검증, 에이전트 CLI 검증, `llm-task` 검증에서 `/think xhigh`를 노출합니다. 백엔드가 표준 수준에 대해 provider별 값을 원하면 `compat.reasoningEffortMap`을 사용하세요. -- `params.preserveThinking`: 보존된 thinking을 위한 Z.AI 전용 옵트인입니다. 활성화되고 thinking이 켜져 있으면 OpenClaw는 `thinking.clear_thinking: false`를 보내고 이전 `reasoning_content`를 재생합니다. [Z.AI thinking 및 보존된 thinking](/ko/providers/zai#thinking-and-preserved-thinking)을 참조하세요. -- `agentRuntime`: 기본 저수준 에이전트 런타임 정책입니다. ID가 생략되면 기본값은 OpenClaw Pi입니다. 기본 제공 PI 하네스를 강제하려면 `id: "pi"`를 사용하고, 등록된 Plugin 하네스가 지원 모델을 클레임하도록 하려면 `id: "auto"`를 사용하고, `id: "codex"` 같은 등록된 하네스 ID 또는 `id: "claude-cli"` 같은 지원되는 CLI 백엔드 alias를 사용하세요. 자동 PI fallback을 비활성화하려면 `fallback: "none"`을 설정하세요. `codex` 같은 명시적 Plugin 런타임은 같은 재정의 범위에서 `fallback: "pi"`를 설정하지 않는 한 기본적으로 닫힌 방식으로 실패합니다. 모델 참조는 `provider/model`로 표준화된 상태로 유지하세요. Codex, Claude CLI, Gemini CLI 및 기타 실행 백엔드는 레거시 런타임 provider 접두사 대신 런타임 구성을 통해 선택하세요. 이것이 provider/model 선택과 어떻게 다른지는 [에이전트 런타임](/ko/concepts/agent-runtimes)을 참조하세요. -- 이러한 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, fallback 추가/제거 명령)는 표준 객체 형식으로 저장하고 가능하면 기존 fallback 목록을 보존합니다. +- `pdfMaxPages`: `pdf` 도구의 추출 대체 모드에서 고려하는 기본 최대 페이지 수입니다. +- `verboseDefault`: 에이전트의 기본 상세 출력 수준입니다. 값: `"off"`, `"on"`, `"full"`. 기본값: `"off"`. +- `reasoningDefault`: 에이전트의 기본 추론 표시 여부입니다. 값: `"off"`, `"on"`, `"stream"`. 에이전트별 `agents.list[].reasoningDefault`가 이 기본값을 재정의합니다. 구성된 추론 기본값은 메시지별 또는 세션 추론 재정의가 설정되지 않았을 때 소유자, 승인된 발신자, 또는 운영자 관리자 Gateway 컨텍스트에만 적용됩니다. +- `elevatedDefault`: 에이전트의 기본 상승 출력 수준입니다. 값: `"off"`, `"on"`, `"ask"`, `"full"`. 기본값: `"on"`. +- `model.primary`: 형식은 `provider/model`입니다. 예: API 키 액세스에는 `openai/gpt-5.5`, Codex OAuth에는 `openai-codex/gpt-5.5`. 제공자를 생략하면 OpenClaw는 먼저 별칭을 시도하고, 그다음 해당 정확한 모델 ID에 대해 고유하게 구성된 제공자 일치를 시도하며, 그 후에야 구성된 기본 제공자로 대체합니다(지원 중단된 호환성 동작이므로 명시적인 `provider/model`을 권장). 해당 제공자가 더 이상 구성된 기본 모델을 노출하지 않으면 OpenClaw는 오래된 제거된 제공자 기본값을 표시하는 대신 처음 구성된 제공자/모델로 대체합니다. +- `models`: `/model`을 위한 구성된 모델 카탈로그와 허용 목록입니다. 각 항목은 `alias`(단축 이름)와 `params`(제공자별, 예: `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`)를 포함할 수 있습니다. + - 안전한 편집: 항목을 추가하려면 `openclaw config set agents.defaults.models '' --strict-json --merge`를 사용하세요. `config set`은 `--replace`를 전달하지 않는 한 기존 허용 목록 항목을 제거하는 대체를 거부합니다. + - 제공자 범위의 구성/온보딩 흐름은 선택된 제공자 모델을 이 맵에 병합하고 이미 구성된 관련 없는 제공자는 보존합니다. + - 직접 OpenAI Responses 모델의 경우 서버 측 Compaction이 자동으로 활성화됩니다. `context_management` 삽입을 중지하려면 `params.responsesServerCompaction: false`를 사용하고, 임계값을 재정의하려면 `params.responsesCompactThreshold`를 사용하세요. [OpenAI 서버 측 Compaction](/ko/providers/openai#server-side-compaction-responses-api)을 참조하세요. +- `params`: 모든 모델에 적용되는 전역 기본 제공자 매개변수입니다. `agents.defaults.params`에 설정합니다(예: `{ cacheRetention: "long" }`). +- `params` 병합 우선순위(구성): `agents.defaults.params`(전역 기준)는 `agents.defaults.models["provider/model"].params`(모델별)로 재정의되고, 그다음 `agents.list[].params`(일치하는 에이전트 ID)가 키별로 재정의합니다. 자세한 내용은 [프롬프트 캐싱](/ko/reference/prompt-caching)을 참조하세요. +- `params.extra_body`/`params.extraBody`: OpenAI 호환 프록시의 `api: "openai-completions"` 요청 본문에 병합되는 고급 전달 JSON입니다. 생성된 요청 키와 충돌하면 추가 본문이 우선합니다. 네이티브가 아닌 completions 경로는 이후에도 OpenAI 전용 `store`를 제거합니다. +- `params.chat_template_kwargs`: 최상위 `api: "openai-completions"` 요청 본문에 병합되는 vLLM/OpenAI 호환 채팅 템플릿 인수입니다. thinking이 꺼진 `vllm/nemotron-3-*`의 경우 번들 vLLM Plugin이 자동으로 `enable_thinking: false`와 `force_nonempty_content: true`를 보냅니다. 명시적인 `chat_template_kwargs`는 생성된 기본값을 재정의하며, `extra_body.chat_template_kwargs`가 여전히 최종 우선순위를 가집니다. vLLM Qwen thinking 제어의 경우 해당 모델 항목에서 `params.qwenThinkingFormat`을 `"chat-template"` 또는 `"top-level"`로 설정하세요. +- `compat.supportedReasoningEfforts`: 모델별 OpenAI 호환 추론 노력 목록입니다. 이를 실제로 받는 사용자 지정 엔드포인트에는 `"xhigh"`를 포함하세요. 그러면 OpenClaw는 해당 구성된 제공자/모델에 대해 명령 메뉴, Gateway 세션 행, 세션 패치 검증, 에이전트 CLI 검증, `llm-task` 검증에서 `/think xhigh`를 노출합니다. 백엔드가 표준 수준에 대해 제공자별 값을 원하는 경우 `compat.reasoningEffortMap`을 사용하세요. +- `params.preserveThinking`: 보존된 thinking을 위한 Z.AI 전용 옵트인입니다. 활성화되어 있고 thinking이 켜져 있으면 OpenClaw는 `thinking.clear_thinking: false`를 보내고 이전 `reasoning_content`를 재생합니다. [Z.AI thinking 및 보존된 thinking](/ko/providers/zai#thinking-and-preserved-thinking)을 참조하세요. +- `agentRuntime`: 기본 저수준 에이전트 런타임 정책입니다. 생략된 ID는 OpenClaw Pi가 기본값입니다. 내장 PI 하네스를 강제하려면 `id: "pi"`를 사용하고, 등록된 Plugin 하네스가 지원 모델을 맡게 하려면 `id: "auto"`를 사용하세요. `id: "codex"` 같은 등록된 하네스 ID나 `id: "claude-cli"` 같은 지원 CLI 백엔드 별칭도 사용할 수 있습니다. 자동 PI 대체를 비활성화하려면 `fallback: "none"`을 설정하세요. `codex` 같은 명시적 Plugin 런타임은 같은 재정의 범위에서 `fallback: "pi"`를 설정하지 않는 한 기본적으로 닫힌 상태로 실패합니다. 모델 참조는 `provider/model`로 표준화해 유지하세요. 레거시 런타임 제공자 접두사 대신 런타임 구성을 통해 Codex, Claude CLI, Gemini CLI 및 기타 실행 백엔드를 선택하세요. 이것이 제공자/모델 선택과 어떻게 다른지는 [에이전트 런타임](/ko/concepts/agent-runtimes)을 참조하세요. +- 이러한 필드를 변경하는 구성 작성기(예: `/models set`, `/models set-image`, 대체 추가/제거 명령)는 표준 객체 형식을 저장하고 가능하면 기존 대체 목록을 보존합니다. - `maxConcurrent`: 세션 전체의 최대 병렬 에이전트 실행 수입니다(각 세션은 여전히 직렬화됨). 기본값: 4. ### `agents.defaults.agentRuntime` -`agentRuntime`은 어떤 저수준 실행기가 에이전트 턴을 실행하는지 제어합니다. 대부분의 -배포는 기본 OpenClaw Pi 런타임을 유지해야 합니다. 번들 Codex app-server 하네스처럼 신뢰할 수 있는 -Plugin이 네이티브 하네스를 제공하거나, Claude CLI 같은 지원되는 CLI 백엔드를 원할 때 사용하세요. 개념적 +`agentRuntime`은 에이전트 턴을 실행할 저수준 실행기를 제어합니다. 대부분의 +배포는 기본 OpenClaw Pi 런타임을 유지해야 합니다. 번들 Codex 앱 서버 하네스처럼 신뢰할 수 있는 +Plugin이 네이티브 하네스를 제공하거나, Claude CLI 같은 지원 CLI 백엔드를 원할 때 사용하세요. 개념적 모델은 [에이전트 런타임](/ko/concepts/agent-runtimes)을 참조하세요. ```json5 @@ -395,22 +401,22 @@ Plugin이 네이티브 하네스를 제공하거나, Claude CLI 같은 지원되 } ``` -- `id`: `"auto"`, `"pi"`, 등록된 Plugin 하네스 ID 또는 지원되는 CLI 백엔드 alias입니다. 번들 Codex Plugin은 `codex`를 등록합니다. 번들 Anthropic Plugin은 `claude-cli` CLI 백엔드를 제공합니다. -- `fallback`: `"pi"` 또는 `"none"`. `id: "auto"`에서 fallback이 생략되면 기본값은 `"pi"`이므로 어떤 Plugin 하네스도 실행을 클레임하지 않을 때도 이전 구성이 PI를 계속 사용할 수 있습니다. `id: "codex"` 같은 명시적 Plugin 런타임 모드에서는 fallback이 생략되면 기본값이 `"none"`이므로 하네스가 없을 때 조용히 PI를 사용하는 대신 실패합니다. 런타임 재정의는 더 넓은 범위의 fallback을 상속하지 않습니다. 해당 호환성 fallback을 의도적으로 원할 때는 명시적 런타임과 함께 `fallback: "pi"`를 설정하세요. 선택된 Plugin 하네스 실패는 항상 직접 표시됩니다. -- 환경 재정의: `OPENCLAW_AGENT_RUNTIME=`는 `id`를 재정의하고, `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none`은 해당 프로세스의 fallback을 재정의합니다. -- Codex 전용 배포의 경우 `model: "openai/gpt-5.5"`와 `agentRuntime.id: "codex"`를 설정하세요. 가독성을 위해 `agentRuntime.fallback: "none"`도 명시적으로 설정할 수 있습니다. 이는 명시적 Plugin 런타임의 기본값입니다. -- Claude CLI 배포의 경우 `model: "anthropic/claude-opus-4-7"`와 `agentRuntime.id: "claude-cli"`를 선호하세요. 레거시 `claude-cli/claude-opus-4-7` 모델 참조도 호환성을 위해 계속 작동하지만, 새 구성은 provider/model 선택을 표준 형식으로 유지하고 실행 백엔드를 `agentRuntime.id`에 두어야 합니다. +- `id`: `"auto"`, `"pi"`, 등록된 Plugin 하네스 ID, 또는 지원 CLI 백엔드 별칭입니다. 번들 Codex Plugin은 `codex`를 등록하며, 번들 Anthropic Plugin은 `claude-cli` CLI 백엔드를 제공합니다. +- `fallback`: `"pi"` 또는 `"none"`. `id: "auto"`에서는 대체가 생략되면 기본값이 `"pi"`이므로 어떤 Plugin 하네스도 실행을 맡지 않을 때 이전 구성이 PI를 계속 사용할 수 있습니다. `id: "codex"` 같은 명시적 Plugin 런타임 모드에서는 대체가 생략되면 기본값이 `"none"`이므로 하네스가 없을 때 PI를 조용히 사용하는 대신 실패합니다. 런타임 재정의는 더 넓은 범위의 대체 설정을 상속하지 않습니다. 해당 호환성 대체를 의도적으로 원할 때는 명시적 런타임과 함께 `fallback: "pi"`를 설정하세요. 선택된 Plugin 하네스 실패는 항상 직접 표시됩니다. +- 환경 재정의: `OPENCLAW_AGENT_RUNTIME=`는 `id`를 재정의하고, `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none`은 해당 프로세스의 대체를 재정의합니다. +- Codex 전용 배포의 경우 `model: "openai/gpt-5.5"`와 `agentRuntime.id: "codex"`를 설정하세요. 가독성을 위해 `agentRuntime.fallback: "none"`을 명시적으로 설정할 수도 있습니다. 이는 명시적 Plugin 런타임의 기본값입니다. +- Claude CLI 배포의 경우 `model: "anthropic/claude-opus-4-7"`와 `agentRuntime.id: "claude-cli"`를 권장합니다. 레거시 `claude-cli/claude-opus-4-7` 모델 참조도 호환성을 위해 계속 작동하지만, 새 구성은 제공자/모델 선택을 표준 형식으로 유지하고 실행 백엔드를 `agentRuntime.id`에 두어야 합니다. - 이전 런타임 정책 키는 `openclaw doctor --fix`에 의해 `agentRuntime`으로 다시 작성됩니다. -- 하네스 선택은 첫 번째 내장 실행 후 세션 ID별로 고정됩니다. 구성/env 변경은 새 세션이나 재설정된 세션에 영향을 주며, 기존 transcript에는 영향을 주지 않습니다. transcript 기록이 있지만 기록된 고정값이 없는 레거시 세션은 PI에 고정된 것으로 처리됩니다. `/status`는 유효 런타임을 보고합니다(예: `Runtime: OpenClaw Pi Default` 또는 `Runtime: OpenAI Codex`). -- 이는 텍스트 에이전트 턴 실행만 제어합니다. 미디어 생성, 비전, PDF, 음악, 동영상, TTS는 여전히 각각의 provider/model 설정을 사용합니다. +- 하네스 선택은 첫 임베디드 실행 이후 세션 ID별로 고정됩니다. 구성/env 변경은 기존 transcript가 아니라 새 세션 또는 재설정된 세션에 영향을 줍니다. transcript 기록은 있지만 기록된 고정 값이 없는 레거시 세션은 PI에 고정된 것으로 처리됩니다. `/status`는 예를 들어 `Runtime: OpenClaw Pi Default` 또는 `Runtime: OpenAI Codex`처럼 유효 런타임을 보고합니다. +- 이는 텍스트 에이전트 턴 실행만 제어합니다. 미디어 생성, 비전, PDF, 음악, 비디오, TTS는 계속 해당 제공자/모델 설정을 사용합니다. -**기본 제공 alias 축약형**(`agents.defaults.models`에 모델이 있는 경우에만 적용): +**내장 별칭 단축 표기**(`agents.defaults.models`에 모델이 있을 때만 적용): | 별칭 | 모델 | | ------------------- | ------------------------------------------ | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` | +| `gpt` | `openai/gpt-5.5` 또는 `openai-codex/gpt-5.5` | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | @@ -419,9 +425,9 @@ Plugin이 네이티브 하네스를 제공하거나, Claude CLI 같은 지원되 구성한 별칭은 항상 기본값보다 우선합니다. -Z.AI GLM-4.x 모델은 `--thinking off`를 설정하거나 `agents.defaults.models["zai/"].params.thinking`을 직접 정의하지 않는 한 자동으로 thinking 모드를 활성화합니다. +Z.AI GLM-4.x 모델은 `--thinking off`를 설정하거나 `agents.defaults.models["zai/"].params.thinking`을 직접 정의하지 않는 한 사고 모드를 자동으로 활성화합니다. Z.AI 모델은 도구 호출 스트리밍을 위해 기본적으로 `tool_stream`을 활성화합니다. 비활성화하려면 `agents.defaults.models["zai/"].params.tool_stream`을 `false`로 설정하세요. -Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않았을 때 기본적으로 `adaptive` thinking을 사용합니다. +Anthropic Claude 4.6 모델은 명시적인 사고 수준이 설정되지 않은 경우 기본적으로 `adaptive` 사고를 사용합니다. ### `agents.defaults.cliBackends` @@ -456,11 +462,11 @@ Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않 - CLI 백엔드는 텍스트 우선이며, 도구는 항상 비활성화됩니다. - `sessionArg`가 설정된 경우 세션이 지원됩니다. -- `imageArg`가 파일 경로를 허용하는 경우 이미지 전달이 지원됩니다. +- `imageArg`가 파일 경로를 허용하는 경우 이미지 패스스루가 지원됩니다. ### `agents.defaults.systemPromptOverride` -OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대체합니다. 기본 수준(`agents.defaults.systemPromptOverride`) 또는 에이전트별(`agents.list[].systemPromptOverride`)로 설정하세요. 에이전트별 값이 우선하며, 비어 있거나 공백만 있는 값은 무시됩니다. 제어된 프롬프트 실험에 유용합니다. +OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 바꿉니다. 기본 수준(`agents.defaults.systemPromptOverride`) 또는 에이전트별(`agents.list[].systemPromptOverride`)로 설정하세요. 에이전트별 값이 우선하며, 비어 있거나 공백만 있는 값은 무시됩니다. 제어된 프롬프트 실험에 유용합니다. ```json5 { @@ -474,7 +480,7 @@ OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대 ### `agents.defaults.promptOverlays` -모델 패밀리별로 적용되는 제공자 독립적 프롬프트 오버레이입니다. GPT-5 패밀리 모델 ID는 제공자 전반에서 공유 동작 계약을 받으며, `personality`는 친근한 상호작용 스타일 계층만 제어합니다. +모델 계열별로 적용되는 제공자 독립 프롬프트 오버레이입니다. GPT-5 계열 모델 ID는 제공자 전반의 공유 동작 계약을 받으며, `personality`는 친근한 상호작용 스타일 계층만 제어합니다. ```json5 { @@ -492,7 +498,7 @@ OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대 - `"friendly"`(기본값)와 `"on"`은 친근한 상호작용 스타일 계층을 활성화합니다. - `"off"`는 친근한 계층만 비활성화하며, 태그가 지정된 GPT-5 동작 계약은 계속 활성화됩니다. -- 이 공유 설정이 지정되지 않은 경우 레거시 `plugins.entries.openai.config.personality`도 계속 읽습니다. +- 이 공유 설정이 설정되지 않은 경우 레거시 `plugins.entries.openai.config.personality`도 여전히 읽습니다. ### `agents.defaults.heartbeat` @@ -530,10 +536,10 @@ OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대 - `timeoutSeconds`: Heartbeat 에이전트 턴이 중단되기 전에 허용되는 최대 시간(초)입니다. 설정하지 않으면 `agents.defaults.timeoutSeconds`를 사용합니다. - `directPolicy`: 직접/DM 전달 정책입니다. `allow`(기본값)는 직접 대상 전달을 허용합니다. `block`은 직접 대상 전달을 억제하고 `reason=dm-blocked`를 내보냅니다. - `lightContext`: true이면 Heartbeat 실행은 경량 부트스트랩 컨텍스트를 사용하고 워크스페이스 부트스트랩 파일 중 `HEARTBEAT.md`만 유지합니다. -- `isolatedSession`: true이면 각 Heartbeat가 이전 대화 기록이 없는 새 세션에서 실행됩니다. cron `sessionTarget: "isolated"`와 같은 격리 패턴입니다. Heartbeat당 토큰 비용을 약 100K에서 약 2-5K 토큰으로 줄입니다. -- `skipWhenBusy`: true이면 Heartbeat 실행은 추가 busy 레인, 즉 하위 에이전트 또는 중첩 명령 작업이 있을 때 지연됩니다. Cron 레인은 이 플래그가 없어도 항상 Heartbeat를 지연합니다. -- 에이전트별: `agents.list[].heartbeat`를 설정하세요. 어떤 에이전트라도 `heartbeat`를 정의하면 **해당 에이전트만** Heartbeat를 실행합니다. -- Heartbeat는 전체 에이전트 턴을 실행하므로, 더 짧은 간격은 더 많은 토큰을 소비합니다. +- `isolatedSession`: true이면 각 Heartbeat가 이전 대화 기록 없이 새 세션에서 실행됩니다. cron `sessionTarget: "isolated"`와 동일한 격리 패턴입니다. Heartbeat당 토큰 비용을 약 100K에서 약 2-5K 토큰으로 줄입니다. +- `skipWhenBusy`: true이면 Heartbeat 실행은 추가로 바쁜 레인, 즉 서브에이전트 또는 중첩 명령 작업에서 지연됩니다. Cron 레인은 이 플래그가 없어도 항상 Heartbeat를 지연합니다. +- 에이전트별: `agents.list[].heartbeat`를 설정하세요. 어떤 에이전트라도 `heartbeat`를 정의하면 **그 에이전트들만** Heartbeat를 실행합니다. +- Heartbeat는 전체 에이전트 턴을 실행합니다. 간격이 짧을수록 더 많은 토큰을 소모합니다. ### `agents.defaults.compaction` @@ -550,6 +556,7 @@ OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대 identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, + midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction @@ -568,22 +575,23 @@ OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대 } ``` -- `mode`: `default` 또는 `safeguard`(긴 기록을 위한 청크 단위 요약)입니다. [Compaction](/ko/concepts/compaction)을 참조하세요. +- `mode`: `default` 또는 `safeguard`(긴 기록에 대한 청크 요약)입니다. [Compaction](/ko/concepts/compaction)을 참조하세요. - `provider`: 등록된 Compaction 제공자 Plugin의 ID입니다. 설정하면 내장 LLM 요약 대신 제공자의 `summarize()`가 호출됩니다. 실패 시 내장 방식으로 대체됩니다. 제공자를 설정하면 `mode: "safeguard"`가 강제됩니다. [Compaction](/ko/concepts/compaction)을 참조하세요. -- `timeoutSeconds`: OpenClaw가 단일 Compaction 작업을 중단하기 전에 허용하는 최대 시간(초)입니다. 기본값: `900`. -- `keepRecentTokens`: 가장 최근 transcript 꼬리 부분을 그대로 유지하기 위한 Pi cut-point 예산입니다. 명시적으로 설정된 경우 수동 `/compact`가 이를 따르며, 그렇지 않으면 수동 Compaction은 하드 체크포인트가 됩니다. -- `identifierPolicy`: `strict`(기본값), `off` 또는 `custom`입니다. `strict`는 Compaction 요약 중 내장 opaque identifier 보존 지침을 앞에 추가합니다. -- `identifierInstructions`: `identifierPolicy=custom`일 때 사용되는 선택적 사용자 지정 identifier 보존 텍스트입니다. -- `qualityGuard`: safeguard 요약에서 잘못된 형식의 출력에 대해 재시도하는 검사입니다. safeguard 모드에서는 기본적으로 활성화되며, 감사를 건너뛰려면 `enabled: false`로 설정하세요. -- `postCompactionSections`: Compaction 후 다시 주입할 선택적 AGENTS.md H2/H3 섹션 이름입니다. 기본값은 `["Session Startup", "Red Lines"]`이며, 다시 주입을 비활성화하려면 `[]`로 설정하세요. 설정되지 않았거나 해당 기본 쌍으로 명시적으로 설정된 경우, 오래된 `Every Session`/`Safety` 제목도 레거시 대체로 허용됩니다. -- `model`: Compaction 요약에만 사용하는 선택적 `provider/model-id` 재정의입니다. 기본 세션은 한 모델을 유지하되 Compaction 요약은 다른 모델에서 실행해야 할 때 사용하세요. 설정하지 않으면 Compaction은 세션의 기본 모델을 사용합니다. -- `maxActiveTranscriptBytes`: 활성 JSONL이 임계값을 넘어서면 실행 전에 일반 로컬 Compaction을 트리거하는 선택적 바이트 임계값(`number` 또는 `"20mb"` 같은 문자열)입니다. 성공한 Compaction이 더 작은 후속 transcript로 회전할 수 있도록 `truncateAfterCompaction`이 필요합니다. 설정하지 않았거나 `0`이면 비활성화됩니다. -- `notifyUser`: `true`이면 Compaction이 시작될 때와 완료될 때 사용자에게 짧은 알림(예: "Compacting context..." 및 "Compaction complete")을 보냅니다. Compaction을 조용히 유지하기 위해 기본적으로 비활성화됩니다. -- `memoryFlush`: 자동 Compaction 전에 durable memory를 저장하기 위한 조용한 agentic 턴입니다. 이 housekeeping 턴이 로컬 모델에 머물러야 하는 경우 `model`을 `ollama/qwen3:8b` 같은 정확한 provider/model로 설정하세요. 이 재정의는 활성 세션 fallback chain을 상속하지 않습니다. 워크스페이스가 읽기 전용이면 건너뜁니다. +- `timeoutSeconds`: OpenClaw가 단일 Compaction 작업을 중단하기 전에 허용되는 최대 시간(초)입니다. 기본값: `900`. +- `keepRecentTokens`: 가장 최근 트랜스크립트 꼬리를 그대로 유지하기 위한 Pi 절단 지점 예산입니다. 수동 `/compact`는 명시적으로 설정된 경우 이를 따르며, 그렇지 않으면 수동 Compaction은 하드 체크포인트입니다. +- `identifierPolicy`: `strict`(기본값), `off` 또는 `custom`입니다. `strict`는 Compaction 요약 중 내장된 불투명 식별자 보존 지침을 앞에 추가합니다. +- `identifierInstructions`: `identifierPolicy=custom`일 때 사용되는 선택적 사용자 지정 식별자 보존 텍스트입니다. +- `qualityGuard`: safeguard 요약에 대한 잘못된 형식 출력 재시도 검사입니다. safeguard 모드에서 기본적으로 활성화되며, 감사를 건너뛰려면 `enabled: false`를 설정하세요. +- `midTurnPrecheck`: 선택적 Pi 도구 루프 압력 검사입니다. `enabled: true`이면 OpenClaw는 도구 결과가 추가된 뒤 다음 모델 호출 전 컨텍스트 압력을 검사합니다. 컨텍스트가 더 이상 맞지 않으면 프롬프트를 제출하기 전에 현재 시도를 중단하고 기존 사전 검사 복구 경로를 재사용해 도구 결과를 잘라내거나 Compaction한 뒤 재시도합니다. `default` 및 `safeguard` Compaction 모드 모두에서 작동합니다. 기본값: 비활성화. +- `postCompactionSections`: Compaction 후 다시 주입할 선택적 AGENTS.md H2/H3 섹션 이름입니다. 기본값은 `["Session Startup", "Red Lines"]`이며, 다시 주입을 비활성화하려면 `[]`로 설정하세요. 설정하지 않았거나 해당 기본 쌍으로 명시적으로 설정한 경우, 이전 `Every Session`/`Safety` 제목도 레거시 대체로 허용됩니다. +- `model`: Compaction 요약에만 적용되는 선택적 `provider/model-id` 재정의입니다. 기본 세션은 한 모델을 유지하되 Compaction 요약은 다른 모델에서 실행해야 할 때 사용하세요. 설정하지 않으면 Compaction은 세션의 기본 모델을 사용합니다. +- `maxActiveTranscriptBytes`: 활성 JSONL이 임계값을 초과해 커졌을 때 실행 전에 일반 로컬 Compaction을 트리거하는 선택적 바이트 임계값(`number` 또는 `"20mb"` 같은 문자열)입니다. 성공한 Compaction이 더 작은 후속 트랜스크립트로 회전할 수 있도록 `truncateAfterCompaction`이 필요합니다. 설정하지 않았거나 `0`이면 비활성화됩니다. +- `notifyUser`: `true`이면 Compaction이 시작될 때와 완료될 때 사용자에게 간단한 알림(예: "Compacting context..." 및 "Compaction complete")을 보냅니다. Compaction을 조용히 유지하기 위해 기본적으로 비활성화됩니다. +- `memoryFlush`: 자동 Compaction 전 지속 메모리를 저장하기 위한 조용한 에이전트 턴입니다. 이 유지관리 턴을 로컬 모델에 유지해야 할 때 `model`을 `ollama/qwen3:8b` 같은 정확한 제공자/모델로 설정하세요. 이 재정의는 활성 세션 대체 체인을 상속하지 않습니다. 워크스페이스가 읽기 전용이면 건너뜁니다. ### `agents.defaults.contextPruning` -LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 결과**를 가지치기합니다. 디스크의 세션 기록은 수정하지 **않습니다**. +LLM으로 보내기 전에 메모리 내 컨텍스트에서 **오래된 도구 결과**를 정리합니다. 디스크의 세션 기록은 수정하지 **않습니다**. ```json5 { @@ -607,23 +615,23 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 -- `mode: "cache-ttl"`는 가지치기 패스를 활성화합니다. -- `ttl`은 가지치기가 다시 실행될 수 있는 빈도(마지막 캐시 접근 이후)를 제어합니다. -- 가지치기는 먼저 지나치게 큰 도구 결과를 소프트 트림한 다음, 필요하면 더 오래된 도구 결과를 하드 클리어합니다. +- `mode: "cache-ttl"`은 정리 패스를 활성화합니다. +- `ttl`은 정리를 다시 실행할 수 있는 빈도(마지막 캐시 접근 이후)를 제어합니다. +- 정리는 먼저 크기가 큰 도구 결과를 소프트 트림한 다음, 필요한 경우 더 오래된 도구 결과를 하드 클리어합니다. -**소프트 트림**은 시작 부분과 끝 부분을 유지하고 가운데에 `...`를 삽입합니다. +**소프트 트림**은 시작 부분과 끝 부분을 유지하고 중간에 `...`을 삽입합니다. -**하드 클리어**는 전체 도구 결과를 placeholder로 대체합니다. +**하드 클리어**는 전체 도구 결과를 자리표시자로 바꿉니다. 참고: - 이미지 블록은 절대 트림되거나 클리어되지 않습니다. -- 비율은 정확한 토큰 수가 아니라 문자 기준(근사치)입니다. -- `keepLastAssistants`보다 assistant 메시지가 적으면 가지치기를 건너뜁니다. +- 비율은 문자 기준(근사치)이며, 정확한 토큰 수가 아닙니다. +- `keepLastAssistants`보다 적은 assistant 메시지만 있는 경우 정리를 건너뜁니다. -동작 세부 정보는 [세션 가지치기](/ko/concepts/session-pruning)를 참조하세요. +동작 세부 정보는 [세션 정리](/ko/concepts/session-pruning)를 참조하세요. ### 블록 스트리밍 @@ -642,8 +650,8 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 ``` - Telegram이 아닌 채널은 블록 응답을 활성화하려면 명시적인 `*.blockStreaming: true`가 필요합니다. -- 채널 재정의: `channels..blockStreamingCoalesce`(및 계정별 변형). Signal/Slack/Discord/Google Chat의 기본값은 `minChars: 1500`입니다. -- `humanDelay`: 블록 응답 사이의 무작위 일시 중지입니다. `natural` = 800-2500ms. 에이전트별 재정의: `agents.list[].humanDelay`. +- 채널 오버라이드: `channels..blockStreamingCoalesce` 및 계정별 변형. Signal/Slack/Discord/Google Chat 기본값은 `minChars: 1500`입니다. +- `humanDelay`: 블록 응답 사이의 무작위 일시 중지입니다. `natural` = 800~2500ms. 에이전트별 오버라이드: `agents.list[].humanDelay`. 동작 및 청크 처리 세부 정보는 [스트리밍](/ko/concepts/streaming)을 참조하세요. @@ -661,7 +669,7 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 ``` - 기본값: 직접 채팅/멘션에는 `instant`, 멘션되지 않은 그룹 채팅에는 `message`. -- 세션별 재정의: `session.typingMode`, `session.typingIntervalSeconds`. +- 세션별 오버라이드: `session.typingMode`, `session.typingIntervalSeconds`. [입력 표시기](/ko/concepts/typing-indicators)를 참조하세요. @@ -669,7 +677,7 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 ### `agents.defaults.sandbox` -내장 에이전트를 위한 선택적 샌드박싱입니다. 전체 가이드는 [샌드박싱](/ko/gateway/sandboxing)을 참조하세요. +임베디드 에이전트를 위한 선택적 샌드박싱입니다. 전체 가이드는 [샌드박싱](/ko/gateway/sandboxing)을 참조하세요. ```json5 { @@ -769,7 +777,7 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 **백엔드:** - `docker`: 로컬 Docker 런타임(기본값) -- `ssh`: 범용 SSH 기반 원격 런타임 +- `ssh`: 일반 SSH 기반 원격 런타임 - `openshell`: OpenShell 런타임 `backend: "openshell"`이 선택되면 런타임별 설정은 @@ -779,37 +787,37 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 - `target`: `user@host[:port]` 형식의 SSH 대상 - `command`: SSH 클라이언트 명령(기본값: `ssh`) -- `workspaceRoot`: 범위별 작업공간에 사용되는 절대 원격 루트 +- `workspaceRoot`: 범위별 워크스페이스에 사용되는 절대 원격 루트 - `identityFile` / `certificateFile` / `knownHostsFile`: OpenSSH에 전달되는 기존 로컬 파일 -- `identityData` / `certificateData` / `knownHostsData`: OpenClaw가 런타임에 임시 파일로 구체화하는 인라인 내용 또는 SecretRefs -- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH 호스트 키 정책 조정 옵션 +- `identityData` / `certificateData` / `knownHostsData`: OpenClaw가 런타임에 임시 파일로 구체화하는 인라인 콘텐츠 또는 SecretRefs +- `strictHostKeyChecking` / `updateHostKeys`: OpenSSH 호스트 키 정책 조정값 **SSH 인증 우선순위:** - `identityData`가 `identityFile`보다 우선합니다 - `certificateData`가 `certificateFile`보다 우선합니다 - `knownHostsData`가 `knownHostsFile`보다 우선합니다 -- SecretRef 기반 `*Data` 값은 샌드박스 세션이 시작되기 전에 활성 비밀 런타임 스냅샷에서 확인됩니다 +- SecretRef 기반 `*Data` 값은 샌드박스 세션이 시작되기 전에 활성 시크릿 런타임 스냅샷에서 해석됩니다 **SSH 백엔드 동작:** -- 생성 또는 재생성 후 원격 작업공간을 한 번 시드합니다 -- 그런 다음 원격 SSH 작업공간을 정본으로 유지합니다 +- 생성 또는 재생성 후 원격 워크스페이스를 한 번 시드합니다 +- 그런 다음 원격 SSH 워크스페이스를 기준으로 유지합니다 - `exec`, 파일 도구, 미디어 경로를 SSH를 통해 라우팅합니다 - 원격 변경 사항을 호스트로 자동 동기화하지 않습니다 - 샌드박스 브라우저 컨테이너를 지원하지 않습니다 -**작업공간 액세스:** +**워크스페이스 접근:** -- `none`: `~/.openclaw/sandboxes` 아래의 범위별 샌드박스 작업공간 -- `ro`: `/workspace`의 샌드박스 작업공간, 에이전트 작업공간은 `/agent`에 읽기 전용으로 마운트됨 -- `rw`: 에이전트 작업공간이 `/workspace`에 읽기/쓰기 가능으로 마운트됨 +- `none`: `~/.openclaw/sandboxes` 아래의 범위별 샌드박스 워크스페이스 +- `ro`: `/workspace`의 샌드박스 워크스페이스, `/agent`에 읽기 전용으로 마운트된 에이전트 워크스페이스 +- `rw`: `/workspace`에 읽기/쓰기 가능하게 마운트된 에이전트 워크스페이스 **범위:** -- `session`: 세션별 컨테이너 + 작업공간 -- `agent`: 에이전트별 컨테이너 + 작업공간 하나(기본값) -- `shared`: 공유 컨테이너 및 작업공간(세션 간 격리 없음) +- `session`: 세션별 컨테이너 + 워크스페이스 +- `agent`: 에이전트별 컨테이너 + 워크스페이스 1개(기본값) +- `shared`: 공유 컨테이너 및 워크스페이스(세션 간 격리 없음) **OpenShell Plugin 구성:** @@ -839,30 +847,30 @@ LLM으로 보내기 전에 인메모리 컨텍스트에서 **오래된 도구 **OpenShell 모드:** -- `mirror`: 실행 전에 로컬에서 원격으로 시드하고, 실행 후 다시 동기화합니다. 로컬 작업공간은 정본으로 유지됩니다 -- `remote`: 샌드박스가 생성될 때 원격을 한 번 시드한 뒤, 원격 작업공간을 정본으로 유지합니다 +- `mirror`: 실행 전에 로컬에서 원격으로 시드하고, 실행 후 다시 동기화합니다. 로컬 워크스페이스가 기준으로 유지됩니다 +- `remote`: 샌드박스가 생성될 때 원격을 한 번 시드한 뒤 원격 워크스페이스를 기준으로 유지합니다 `remote` 모드에서는 시드 단계 이후 OpenClaw 외부에서 수행된 호스트 로컬 편집이 샌드박스로 자동 동기화되지 않습니다. -전송은 OpenShell 샌드박스로의 SSH이지만, Plugin이 샌드박스 수명 주기와 선택적 미러 동기화를 소유합니다. +전송은 OpenShell 샌드박스로의 SSH를 사용하지만, Plugin이 샌드박스 수명 주기와 선택적 미러 동기화를 소유합니다. -**`setupCommand`**는 컨테이너 생성 후 한 번 실행됩니다(`sh -lc`를 통해). 네트워크 송신, 쓰기 가능한 루트, 루트 사용자가 필요합니다. +**`setupCommand`**는 컨테이너 생성 후 한 번 실행됩니다(`sh -lc` 경유). 네트워크 송신, 쓰기 가능한 루트, 루트 사용자가 필요합니다. -**컨테이너의 기본값은 `network: "none"`입니다**. 에이전트에 외부 액세스가 필요한 경우 `"bridge"`(또는 사용자 지정 브리지 네트워크)로 설정하세요. +**컨테이너 기본값은 `network: "none"`입니다** — 에이전트에 아웃바운드 접근이 필요하면 `"bridge"`(또는 사용자 지정 브리지 네트워크)로 설정하세요. `"host"`는 차단됩니다. `"container:"`는 명시적으로 -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`(비상용)를 설정하지 않는 한 기본적으로 차단됩니다. +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`를 설정하지 않는 한 기본적으로 차단됩니다(비상용). -**인바운드 첨부 파일**은 활성 작업공간의 `media/inbound/*`에 스테이징됩니다. +**인바운드 첨부 파일**은 활성 워크스페이스의 `media/inbound/*`에 스테이징됩니다. -**`docker.binds`**는 추가 호스트 디렉터리를 마운트합니다. 전역 바인드와 에이전트별 바인드는 병합됩니다. +**`docker.binds`**는 추가 호스트 디렉터리를 마운트합니다. 전역 바인드와 에이전트별 바인드가 병합됩니다. -**샌드박스 브라우저**(`sandbox.browser.enabled`): 컨테이너 내 Chromium + CDP입니다. noVNC URL은 시스템 프롬프트에 주입됩니다. `openclaw.json`에서 `browser.enabled`가 필요하지 않습니다. -noVNC 관찰자 액세스는 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 수명이 짧은 토큰 URL을 내보냅니다. +**샌드박스 브라우저**(`sandbox.browser.enabled`): 컨테이너의 Chromium + CDP입니다. noVNC URL이 시스템 프롬프트에 주입됩니다. `openclaw.json`에서 `browser.enabled`가 필요하지 않습니다. +noVNC 관찰자 접근은 기본적으로 VNC 인증을 사용하며, OpenClaw는 공유 URL에 비밀번호를 노출하는 대신 수명이 짧은 토큰 URL을 내보냅니다. - `allowHostControl: false`(기본값)는 샌드박스 세션이 호스트 브라우저를 대상으로 지정하지 못하게 차단합니다. -- `network`의 기본값은 `openclaw-sandbox-browser`(전용 브리지 네트워크)입니다. 전역 브리지 연결을 명시적으로 원하는 경우에만 `bridge`로 설정하세요. -- `cdpSourceRange`는 선택적으로 컨테이너 경계에서 CDP 인그레스를 CIDR 범위로 제한합니다(예: `172.21.0.1/32`). -- `sandbox.browser.binds`는 추가 호스트 디렉터리를 샌드박스 브라우저 컨테이너에만 마운트합니다. 설정되면(`[]` 포함) 브라우저 컨테이너의 `docker.binds`를 대체합니다. -- 실행 기본값은 `scripts/sandbox-browser-entrypoint.sh`에 정의되어 있으며 컨테이너 호스트에 맞게 조정되어 있습니다. +- `network` 기본값은 `openclaw-sandbox-browser`(전용 브리지 네트워크)입니다. 전역 브리지 연결을 명시적으로 원하는 경우에만 `bridge`로 설정하세요. +- `cdpSourceRange`는 선택적으로 컨테이너 경계의 CDP 인그레스를 CIDR 범위로 제한합니다(예: `172.21.0.1/32`). +- `sandbox.browser.binds`는 샌드박스 브라우저 컨테이너에만 추가 호스트 디렉터리를 마운트합니다. 설정된 경우(`[]` 포함) 브라우저 컨테이너에 대해 `docker.binds`를 대체합니다. +- 시작 기본값은 `scripts/sandbox-browser-entrypoint.sh`에 정의되어 있으며 컨테이너 호스트에 맞게 조정되어 있습니다: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -879,16 +887,15 @@ noVNC 관찰자 액세스는 기본적으로 VNC 인증을 사용하며, OpenCla - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions`(기본 활성화) + - `--disable-extensions`(기본적으로 활성화됨) - `--disable-3d-apis`, `--disable-software-rasterizer`, `--disable-gpu`는 - 기본적으로 활성화되며, WebGL/3D 사용에 필요한 경우 + 기본적으로 활성화되어 있으며 WebGL/3D 사용에 필요한 경우 `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`으로 비활성화할 수 있습니다. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`은 워크플로가 확장 프로그램에 - 의존하는 경우 확장 프로그램을 다시 활성화합니다. + - 워크플로가 확장 기능에 의존하는 경우 `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0`으로 확장 기능을 다시 활성화합니다. - `--renderer-process-limit=2`는 `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`으로 변경할 수 있습니다. Chromium의 기본 프로세스 제한을 사용하려면 `0`으로 설정하세요. - - `noSandbox`가 활성화된 경우 `--no-sandbox`가 추가됩니다. + - `noSandbox`가 활성화된 경우 `--no-sandbox`도 추가됩니다. - 기본값은 컨테이너 이미지 기준선입니다. 컨테이너 기본값을 변경하려면 사용자 지정 엔트리포인트가 있는 사용자 지정 브라우저 이미지를 사용하세요. @@ -903,14 +910,14 @@ scripts/sandbox-setup.sh # main sandbox image scripts/sandbox-browser-setup.sh # optional browser image ``` -### `agents.list`(에이전트별 재정의) +### `agents.list`(에이전트별 오버라이드) -에이전트에 자체 TTS 공급자, 음성, 모델, -스타일 또는 자동 TTS 모드를 지정하려면 `agents.list[].tts`를 사용하세요. 에이전트 블록은 전역 -`messages.tts` 위에 깊게 병합되므로, 공유 자격 증명은 한곳에 유지하면서 개별 -에이전트는 필요한 음성 또는 공급자 필드만 재정의할 수 있습니다. 활성 에이전트의 -재정의는 자동 음성 응답, `/tts audio`, `/tts status`, -그리고 `tts` 에이전트 도구에 적용됩니다. 공급자 예시와 우선순위는 +`agents.list[].tts`를 사용하여 에이전트에 자체 TTS 제공자, 음성, 모델, +스타일 또는 자동 TTS 모드를 지정하세요. 에이전트 블록은 전역 +`messages.tts` 위에 깊은 병합을 수행하므로, 개별 에이전트는 필요한 음성 또는 제공자 필드만 +오버라이드하면서 공유 자격 증명은 한곳에 유지할 수 있습니다. 활성 에이전트의 +오버라이드는 자동 음성 응답, `/tts audio`, `/tts status` 및 +`tts` 에이전트 도구에 적용됩니다. 제공자 예시와 우선순위는 [텍스트 음성 변환](/ko/tools/tts#per-agent-voice-overrides)을 참조하세요. ```json5 @@ -965,22 +972,22 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: 안정적인 에이전트 id(필수). -- `default`: 여러 개가 설정된 경우 첫 번째 항목이 우선합니다(경고가 기록됨). 설정된 항목이 없으면 목록의 첫 번째 항목이 기본값입니다. -- `model`: 문자열 형식은 모델 폴백 없이 에이전트별 기본 모델을 엄격하게 설정합니다. 객체 형식 `{ primary }`도 `fallbacks`를 추가하지 않는 한 엄격합니다. `{ primary, fallbacks: [...] }`를 사용하면 해당 에이전트에 폴백을 적용할 수 있고, `{ primary, fallbacks: [] }`를 사용하면 엄격한 동작을 명시할 수 있습니다. `primary`만 재정의하는 Cron 작업은 `fallbacks: []`를 설정하지 않는 한 여전히 기본 폴백을 상속합니다. -- `params`: `agents.defaults.models`에서 선택된 모델 항목 위에 병합되는 에이전트별 스트림 매개변수입니다. 전체 모델 카탈로그를 중복하지 않고 `cacheRetention`, `temperature`, `maxTokens` 같은 에이전트별 재정의에 사용합니다. -- `tts`: 선택 사항인 에이전트별 텍스트 음성 변환 재정의입니다. 이 블록은 `messages.tts` 위에 깊은 병합되므로 공유 제공자 자격 증명과 폴백 정책은 `messages.tts`에 두고, 제공자, 음성, 모델, 스타일, 자동 모드 같은 페르소나별 값만 여기에서 설정합니다. -- `skills`: 선택 사항인 에이전트별 Skills 허용 목록입니다. 생략하면 설정된 경우 에이전트가 `agents.defaults.skills`를 상속합니다. 명시적 목록은 기본값과 병합되지 않고 대체하며, `[]`는 Skills 없음이라는 뜻입니다. -- `thinkingDefault`: 선택 사항인 에이전트별 기본 사고 수준(`off | minimal | low | medium | high | xhigh | adaptive | max`)입니다. 메시지별 또는 세션 재정의가 설정되지 않은 경우 이 에이전트에 대해 `agents.defaults.thinkingDefault`를 재정의합니다. 선택된 제공자/모델 프로필이 유효한 값을 제어합니다. Google Gemini의 경우 `adaptive`는 제공자가 소유한 동적 사고를 유지합니다(Gemini 3/3.1에서는 `thinkingLevel` 생략, Gemini 2.5에서는 `thinkingBudget: -1`). -- `reasoningDefault`: 선택 사항인 에이전트별 기본 추론 표시 여부(`on | off | stream`)입니다. 메시지별 또는 세션 추론 재정의가 설정되지 않은 경우 이 에이전트에 대해 `agents.defaults.reasoningDefault`를 재정의합니다. -- `fastModeDefault`: 선택 사항인 에이전트별 빠른 모드 기본값(`true | false`)입니다. 메시지별 또는 세션 빠른 모드 재정의가 설정되지 않은 경우 적용됩니다. -- `agentRuntime`: 선택 사항인 에이전트별 저수준 런타임 정책 재정의입니다. `{ id: "codex" }`를 사용하면 다른 에이전트는 `auto` 모드에서 기본 PI 폴백을 유지하면서 한 에이전트만 Codex 전용으로 만들 수 있습니다. -- `runtime`: 선택 사항인 에이전트별 런타임 설명자입니다. 에이전트가 기본적으로 ACP 하네스 세션을 사용해야 하는 경우 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)과 함께 `type: "acp"`를 사용합니다. -- `identity.avatar`: 워크스페이스 상대 경로, `http(s)` URL 또는 `data:` URI입니다. -- `identity`는 기본값을 파생합니다: `emoji`에서 `ackReaction`, `name`/`emoji`에서 `mentionPatterns`. -- `subagents.allowAgents`: 명시적 `sessions_spawn.agentId` 대상에 대한 에이전트 id 허용 목록입니다(`["*"]` = 임의, 기본값: 같은 에이전트만). 자체 대상 `agentId` 호출을 허용해야 하는 경우 요청자 id를 포함합니다. -- 샌드박스 상속 가드: 요청자 세션이 샌드박스 처리된 경우 `sessions_spawn`은 샌드박스 없이 실행될 대상을 거부합니다. -- `subagents.requireAgentId`: true이면 `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적 프로필 선택 강제, 기본값: false). +- `id`: 안정적인 에이전트 ID(필수). +- `default`: 여러 개가 설정되면 첫 번째가 적용됩니다(경고가 기록됨). 아무것도 설정하지 않으면 목록의 첫 번째 항목이 기본값입니다. +- `model`: 문자열 형식은 모델 대체 없이 엄격한 에이전트별 기본 모델을 설정합니다. 객체 형식 `{ primary }`도 `fallbacks`를 추가하지 않는 한 엄격합니다. 해당 에이전트에서 대체를 사용하려면 `{ primary, fallbacks: [...] }`를 사용하고, 엄격한 동작을 명시하려면 `{ primary, fallbacks: [] }`를 사용하세요. `primary`만 재정의하는 Cron 작업은 `fallbacks: []`를 설정하지 않는 한 기본 대체 모델을 계속 상속합니다. +- `params`: `agents.defaults.models`에서 선택된 모델 항목 위에 병합되는 에이전트별 스트림 매개변수입니다. 전체 모델 카탈로그를 복제하지 않고 `cacheRetention`, `temperature`, `maxTokens` 같은 에이전트별 재정의에 사용하세요. +- `tts`: 선택적인 에이전트별 텍스트 음성 변환 재정의입니다. 이 블록은 `messages.tts` 위에 깊은 병합으로 적용되므로, 공유 제공자 자격 증명과 대체 정책은 `messages.tts`에 유지하고, 여기에는 제공자, 음성, 모델, 스타일, 자동 모드 같은 페르소나별 값만 설정하세요. +- `skills`: 선택적인 에이전트별 skill 허용 목록입니다. 생략하면 설정된 경우 에이전트가 `agents.defaults.skills`를 상속합니다. 명시적인 목록은 기본값과 병합하지 않고 대체하며, `[]`는 skills 없음을 의미합니다. +- `thinkingDefault`: 선택적인 에이전트별 기본 사고 수준(`off | minimal | low | medium | high | xhigh | adaptive | max`)입니다. 메시지별 또는 세션별 재정의가 설정되지 않았을 때 이 에이전트에 대해 `agents.defaults.thinkingDefault`를 재정의합니다. 선택된 제공자/모델 프로필이 유효한 값을 제어합니다. Google Gemini의 경우 `adaptive`는 제공자가 소유한 동적 사고를 유지합니다(Gemini 3/3.1에서는 `thinkingLevel` 생략, Gemini 2.5에서는 `thinkingBudget: -1`). +- `reasoningDefault`: 선택적인 에이전트별 기본 추론 표시 여부(`on | off | stream`)입니다. 메시지별 또는 세션별 추론 재정의가 설정되지 않았을 때 이 에이전트에 대해 `agents.defaults.reasoningDefault`를 재정의합니다. +- `fastModeDefault`: 선택적인 에이전트별 빠른 모드 기본값(`true | false`)입니다. 메시지별 또는 세션별 빠른 모드 재정의가 설정되지 않았을 때 적용됩니다. +- `agentRuntime`: 선택적인 에이전트별 저수준 런타임 정책 재정의입니다. 한 에이전트만 Codex 전용으로 만들고 다른 에이전트는 `auto` 모드에서 기본 PI 대체를 유지하려면 `{ id: "codex" }`를 사용하세요. +- `runtime`: 선택적인 에이전트별 런타임 설명자입니다. 에이전트가 ACP 하네스 세션을 기본값으로 사용해야 할 때 `runtime.acp` 기본값(`agent`, `backend`, `mode`, `cwd`)과 함께 `type: "acp"`를 사용하세요. +- `identity.avatar`: 워크스페이스 기준 상대 경로, `http(s)` URL 또는 `data:` URI입니다. +- `identity`는 기본값을 파생합니다. `emoji`에서 `ackReaction`, `name`/`emoji`에서 `mentionPatterns`를 파생합니다. +- `subagents.allowAgents`: 명시적인 `sessions_spawn.agentId` 대상에 대한 에이전트 ID 허용 목록입니다(`["*"]` = 모두, 기본값: 같은 에이전트만). 자기 자신을 대상으로 하는 `agentId` 호출을 허용해야 할 때 요청자 ID를 포함하세요. +- 샌드박스 상속 보호: 요청자 세션이 샌드박스 처리된 경우 `sessions_spawn`은 샌드박스 없이 실행될 대상을 거부합니다. +- `subagents.requireAgentId`: true이면 `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적인 프로필 선택을 강제함, 기본값: false). --- @@ -1005,9 +1012,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### 바인딩 일치 필드 -- `type`(선택 사항): 일반 라우팅은 `route`(type이 없으면 기본값은 route), 영구 ACP 대화 바인딩은 `acp`입니다. +- `type`(선택 사항): 일반 라우팅에는 `route`(type이 없으면 기본값은 route), 영구 ACP 대화 바인딩에는 `acp`. - `match.channel`(필수) -- `match.accountId`(선택 사항, `*` = 임의 계정, 생략 = 기본 계정) +- `match.accountId`(선택 사항, `*` = 모든 계정, 생략 = 기본 계정) - `match.peer`(선택 사항, `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId`(선택 사항, 채널별) - `acp`(선택 사항, `type: "acp"`에만 해당): `{ mode, label, cwd, backend }` @@ -1017,17 +1024,17 @@ scripts/sandbox-browser-setup.sh # optional browser image 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. 기본 에이전트 -각 단계 안에서는 처음 일치하는 `bindings` 항목이 우선합니다. +각 계층 내에서는 처음 일치하는 `bindings` 항목이 적용됩니다. -`type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 식별자(`match.channel` + account + `match.peer.id`)로 해석하며 위의 라우트 바인딩 단계 순서를 사용하지 않습니다. +`type: "acp"` 항목의 경우 OpenClaw는 정확한 대화 ID(`match.channel` + 계정 + `match.peer.id`)로 확인하며, 위의 라우트 바인딩 계층 순서를 사용하지 않습니다. ### 에이전트별 접근 프로필 - + ```json5 { @@ -1146,21 +1153,21 @@ scripts/sandbox-browser-setup.sh # optional browser image }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // 이 토큰 수를 초과하면 부모 스레드 포크 건너뛰기(0은 비활성화) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, - resetArchiveRetention: "30d", // 기간 또는 false - maxDiskBytes: "500mb", // 선택 사항인 하드 예산 - highWaterBytes: "400mb", // 선택 사항인 정리 대상 + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // 기본 비활성 자동 포커스 해제 시간 단위(`0`은 비활성화) - maxAgeHours: 0, // 기본 하드 최대 수명 시간 단위(`0`은 비활성화) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // 레거시(런타임은 항상 "main" 사용) + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1172,35 +1179,35 @@ scripts/sandbox-browser-setup.sh # optional browser image -- **`scope`**: 그룹 채팅 컨텍스트의 기본 세션 그룹화 전략입니다. +- **`scope`**: 그룹 채팅 컨텍스트를 위한 기본 세션 그룹화 전략입니다. - `per-sender`(기본값): 각 발신자는 채널 컨텍스트 안에서 격리된 세션을 받습니다. - - `global`: 채널 컨텍스트의 모든 참가자가 단일 세션을 공유합니다(공유 컨텍스트가 의도된 경우에만 사용). -- **`dmScope`**: DM을 그룹화하는 방식입니다. - - `main`: 모든 DM이 메인 세션을 공유합니다. - - `per-peer`: 채널을 가로질러 발신자 id별로 격리합니다. + - `global`: 채널 컨텍스트의 모든 참여자가 하나의 세션을 공유합니다(공유 컨텍스트가 의도된 경우에만 사용). +- **`dmScope`**: DM이 그룹화되는 방식입니다. + - `main`: 모든 DM이 기본 세션을 공유합니다. + - `per-peer`: 채널 전체에서 발신자 ID별로 격리합니다. - `per-channel-peer`: 채널 + 발신자별로 격리합니다(다중 사용자 받은편지함에 권장). - `per-account-channel-peer`: 계정 + 채널 + 발신자별로 격리합니다(다중 계정에 권장). -- **`identityLinks`**: 교차 채널 세션 공유를 위해 정규 id를 제공자 접두사가 붙은 peer에 매핑합니다. `/dock_discord` 같은 도킹 명령은 같은 맵을 사용해 활성 세션의 응답 경로를 다른 연결된 채널 peer로 전환합니다. [채널 도킹](/ko/concepts/channel-docking)을 참조하세요. -- **`reset`**: 기본 재설정 정책입니다. `daily`는 현지 시간 `atHour`에 재설정하고, `idle`은 `idleMinutes` 이후 재설정합니다. 둘 다 구성된 경우 먼저 만료되는 것이 우선합니다. 일일 재설정 신선도는 세션 행의 `sessionStartedAt`을 사용하고, 유휴 재설정 신선도는 `lastInteractionAt`을 사용합니다. Heartbeat, Cron 깨우기, exec 알림, Gateway 장부 처리 같은 백그라운드/시스템 이벤트 쓰기는 `updatedAt`을 업데이트할 수 있지만, daily/idle 세션을 신선하게 유지하지는 않습니다. +- **`identityLinks`**: 채널 간 세션 공유를 위해 표준 ID를 공급자 접두사가 붙은 피어에 매핑합니다. `/dock_discord` 같은 도킹 명령은 동일한 맵을 사용해 활성 세션의 응답 경로를 연결된 다른 채널 피어로 전환합니다. [채널 도킹](/ko/concepts/channel-docking)을 참조하세요. +- **`reset`**: 기본 재설정 정책입니다. `daily`는 현지 시간 `atHour`에 재설정하고, `idle`은 `idleMinutes` 이후 재설정합니다. 둘 다 구성된 경우 먼저 만료되는 쪽이 우선합니다. 일일 재설정 최신성은 세션 행의 `sessionStartedAt`을 사용하고, 유휴 재설정 최신성은 `lastInteractionAt`을 사용합니다. heartbeat, cron 깨우기, exec 알림, gateway 장부 처리 같은 백그라운드/시스템 이벤트 쓰기는 `updatedAt`을 갱신할 수 있지만, 일일/유휴 세션을 최신 상태로 유지하지는 않습니다. - **`resetByType`**: 유형별 재정의(`direct`, `group`, `thread`)입니다. 레거시 `dm`은 `direct`의 별칭으로 허용됩니다. -- **`parentForkMaxTokens`**: 포크된 스레드 세션을 만들 때 허용되는 부모 세션 `totalTokens`의 최댓값입니다(기본값 `100000`). - - 부모 `totalTokens`가 이 값보다 크면 OpenClaw는 부모 대화 기록을 상속하는 대신 새 스레드 세션을 시작합니다. - - 이 가드를 비활성화하고 항상 부모 포크를 허용하려면 `0`으로 설정합니다. +- **`parentForkMaxTokens`**: 포크된 스레드 세션을 만들 때 허용되는 부모 세션 `totalTokens`의 최대값입니다(기본값 `100000`). + - 부모 `totalTokens`가 이 값보다 크면 OpenClaw는 부모 전사 기록을 상속하는 대신 새 스레드 세션을 시작합니다. + - 이 보호 기능을 비활성화하고 항상 부모 포크를 허용하려면 `0`으로 설정하세요. - **`mainKey`**: 레거시 필드입니다. 런타임은 기본 직접 채팅 버킷에 항상 `"main"`을 사용합니다. -- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 중 에이전트 사이의 최대 응답 왕복 턴 수입니다(정수, 범위: `0`–`5`). `0`은 핑퐁 체이닝을 비활성화합니다. -- **`sendPolicy`**: `channel`, `chatType`(`direct|group|channel`, 레거시 `dm` 별칭 포함), `keyPrefix` 또는 `rawKeyPrefix`로 일치시킵니다. 첫 번째 거부가 우선합니다. +- **`agentToAgent.maxPingPongTurns`**: 에이전트 간 교환 중 에이전트 사이의 최대 왕복 응답 턴 수입니다(정수, 범위: `0`–`5`). `0`은 핑퐁 체이닝을 비활성화합니다. +- **`sendPolicy`**: `channel`, `chatType`(`direct|group|channel`, 레거시 `dm` 별칭 포함), `keyPrefix` 또는 `rawKeyPrefix`로 매칭합니다. 첫 번째 거부 규칙이 우선합니다. - **`maintenance`**: 세션 저장소 정리 + 보존 제어입니다. - `mode`: `warn`은 경고만 내보내고, `enforce`는 정리를 적용합니다. - - `pruneAfter`: 오래된 항목의 나이 기준(기본값 `30d`). - - `maxEntries`: `sessions.json`의 최대 항목 수(기본값 `500`). 런타임은 프로덕션 규모 제한을 위해 작은 high-water 버퍼와 함께 일괄 정리를 기록합니다. `openclaw sessions cleanup --enforce`는 제한을 즉시 적용합니다. + - `pruneAfter`: 오래된 항목의 연령 기준입니다(기본값 `30d`). + - `maxEntries`: `sessions.json`의 최대 항목 수입니다(기본값 `500`). 런타임 쓰기는 프로덕션 규모 제한을 위해 작은 상한 버퍼를 둔 일괄 정리를 수행합니다. `openclaw sessions cleanup --enforce`는 제한을 즉시 적용합니다. - `rotateBytes`: 사용 중단되었으며 무시됩니다. `openclaw doctor --fix`는 이전 구성에서 이를 제거합니다. - - `resetArchiveRetention`: `*.reset.` 대화 기록 아카이브의 보존 기간입니다. 기본값은 `pruneAfter`입니다. 비활성화하려면 `false`로 설정합니다. - - `maxDiskBytes`: 선택 사항인 세션 디렉터리 디스크 예산입니다. `warn` 모드에서는 경고를 기록하고, `enforce` 모드에서는 가장 오래된 아티팩트/세션부터 제거합니다. - - `highWaterBytes`: 예산 정리 후의 선택 사항인 목표값입니다. 기본값은 `maxDiskBytes`의 `80%`입니다. + - `resetArchiveRetention`: `*.reset.` 전사 아카이브의 보존 기간입니다. 기본값은 `pruneAfter`이며, 비활성화하려면 `false`로 설정하세요. + - `maxDiskBytes`: 선택적 세션 디렉터리 디스크 예산입니다. `warn` 모드에서는 경고를 기록하고, `enforce` 모드에서는 가장 오래된 아티팩트/세션부터 제거합니다. + - `highWaterBytes`: 예산 정리 후 선택적 목표값입니다. 기본값은 `maxDiskBytes`의 `80%`입니다. - **`threadBindings`**: 스레드 바인딩 세션 기능의 전역 기본값입니다. - - `enabled`: 마스터 기본 스위치(제공자가 재정의할 수 있음, Discord는 `channels.discord.threadBindings.enabled` 사용) - - `idleHours`: 기본 비활성 자동 포커스 해제 시간 단위(`0`은 비활성화, 제공자가 재정의할 수 있음) - - `maxAgeHours`: 기본 하드 최대 수명 시간 단위(`0`은 비활성화, 제공자가 재정의할 수 있음) + - `enabled`: 마스터 기본 스위치입니다(공급자가 재정의할 수 있음; Discord는 `channels.discord.threadBindings.enabled` 사용) + - `idleHours`: 기본 비활성 자동 포커스 해제 시간(시간 단위, `0`은 비활성화, 공급자가 재정의할 수 있음) + - `maxAgeHours`: 기본 강제 최대 수명(시간 단위, `0`은 비활성화, 공급자가 재정의할 수 있음) @@ -1240,7 +1247,7 @@ scripts/sandbox-browser-setup.sh # optional browser image 채널/계정별 재정의: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -해결 방식(가장 구체적인 항목이 우선): 계정 → 채널 → 전역. `""`는 비활성화하고 연쇄 적용을 중지합니다. `"auto"`는 `[{identity.name}]`에서 파생됩니다. +해결 방식(가장 구체적인 항목 우선): 계정 → 채널 → 전역. `""`는 비활성화하고 연쇄 적용을 중단합니다. `"auto"`는 `[{identity.name}]`에서 파생됩니다. **템플릿 변수:** @@ -1250,24 +1257,24 @@ scripts/sandbox-browser-setup.sh # optional browser image | `{modelFull}` | 전체 모델 식별자 | `anthropic/claude-opus-4-6` | | `{provider}` | 공급자 이름 | `anthropic` | | `{thinkingLevel}` | 현재 사고 수준 | `high`, `low`, `off` | -| `{identity.name}` | 에이전트 ID 이름 | (`"auto"`와 동일) | +| `{identity.name}` | 에이전트 정체성 이름 | (`"auto"`와 동일) | 변수는 대소문자를 구분하지 않습니다. `{think}`는 `{thinkingLevel}`의 별칭입니다. ### 확인 반응 -- 기본값은 활성 에이전트의 `identity.emoji`이며, 없으면 `"👀"`입니다. 비활성화하려면 `""`로 설정합니다. +- 기본값은 활성 에이전트의 `identity.emoji`이며, 없으면 `"👀"`입니다. 비활성화하려면 `""`로 설정하세요. - 채널별 재정의: `channels..ackReaction`, `channels..accounts..ackReaction`. -- 해결 순서: 계정 → 채널 → `messages.ackReaction` → ID 대체값. +- 해결 순서: 계정 → 채널 → `messages.ackReaction` → 정체성 대체값. - 범위: `group-mentions`(기본값), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: Slack, Discord, Telegram, WhatsApp, BlueBubbles처럼 반응을 지원하는 채널에서 답장 후 확인 반응을 제거합니다. +- `removeAckAfterReply`: Slack, Discord, Telegram, WhatsApp, BlueBubbles처럼 반응을 지원하는 채널에서 응답 후 확인 반응을 제거합니다. - `messages.statusReactions.enabled`: Slack, Discord, Telegram에서 수명 주기 상태 반응을 활성화합니다. - Slack 및 Discord에서는 설정하지 않으면 확인 반응이 활성 상태일 때 상태 반응이 활성 상태로 유지됩니다. - Telegram에서는 수명 주기 상태 반응을 활성화하려면 명시적으로 `true`로 설정합니다. + Slack과 Discord에서는 설정하지 않으면 확인 반응이 활성화된 경우 상태 반응도 활성화된 상태로 유지됩니다. + Telegram에서는 수명 주기 상태 반응을 활성화하려면 명시적으로 `true`로 설정하세요. -### 수신 디바운스 +### 인바운드 디바운스 -동일한 발신자의 빠른 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 플러시됩니다. 제어 명령은 디바운스를 우회합니다. +동일한 발신자가 빠르게 보내는 텍스트 전용 메시지를 하나의 에이전트 턴으로 일괄 처리합니다. 미디어/첨부 파일은 즉시 플러시됩니다. 제어 명령은 디바운스를 우회합니다. ### TTS(텍스트 음성 변환) @@ -1317,19 +1324,19 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto`는 기본 자동 TTS 모드인 `off`, `always`, `inbound`, `tagged`를 제어합니다. `/tts on|off`는 로컬 기본 설정을 재정의할 수 있으며, `/tts status`는 적용 중인 상태를 표시합니다. +- `auto`는 기본 자동 TTS 모드(`off`, `always`, `inbound`, `tagged`)를 제어합니다. `/tts on|off`는 로컬 환경설정을 재정의할 수 있고, `/tts status`는 유효한 상태를 표시합니다. - `summaryModel`은 자동 요약에 대해 `agents.defaults.model.primary`를 재정의합니다. -- `modelOverrides`는 기본적으로 활성화되어 있으며, `modelOverrides.allowProvider`의 기본값은 `false`(옵트인)입니다. +- `modelOverrides`는 기본적으로 활성화되어 있습니다. `modelOverrides.allowProvider`의 기본값은 `false`입니다(명시적 선택). - API 키는 `ELEVENLABS_API_KEY`/`XI_API_KEY` 및 `OPENAI_API_KEY`로 대체됩니다. -- 번들 음성 공급자는 Plugin이 소유합니다. `plugins.allow`가 설정된 경우 사용하려는 각 TTS 공급자 Plugin을 포함합니다. 예를 들어 Edge TTS에는 `microsoft`를 포함합니다. 레거시 `edge` 공급자 ID는 `microsoft`의 별칭으로 허용됩니다. -- `providers.openai.baseUrl`은 OpenAI TTS 엔드포인트를 재정의합니다. 해결 순서는 구성, `OPENAI_TTS_BASE_URL`, `https://api.openai.com/v1`입니다. +- 번들 음성 공급자는 Plugin 소유입니다. `plugins.allow`가 설정된 경우 사용하려는 각 TTS 공급자 Plugin을 포함하세요. 예를 들어 Edge TTS에는 `microsoft`를 포함합니다. 레거시 `edge` 공급자 ID는 `microsoft`의 별칭으로 허용됩니다. +- `providers.openai.baseUrl`은 OpenAI TTS 엔드포인트를 재정의합니다. 해결 순서는 구성, `OPENAI_TTS_BASE_URL`, `https://api.openai.com/v1` 순입니다. - `providers.openai.baseUrl`이 OpenAI가 아닌 엔드포인트를 가리키면 OpenClaw는 이를 OpenAI 호환 TTS 서버로 처리하고 모델/음성 검증을 완화합니다. --- -## Talk +## 대화 -Talk 모드(macOS/iOS/Android)의 기본값입니다. +대화 모드(macOS/iOS/Android)의 기본값입니다. ```json5 { @@ -1358,16 +1365,16 @@ Talk 모드(macOS/iOS/Android)의 기본값입니다. } ``` -- 여러 Talk 공급자가 구성된 경우 `talk.provider`는 `talk.providers`의 키와 일치해야 합니다. -- 레거시 평면 Talk 키(`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`)는 호환성 전용이며 `talk.providers.`로 자동 마이그레이션됩니다. +- 여러 대화 공급자가 구성된 경우 `talk.provider`는 `talk.providers`의 키와 일치해야 합니다. +- 레거시 평면 대화 키(`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`)는 호환성 전용이며 `talk.providers.`로 자동 마이그레이션됩니다. - 음성 ID는 `ELEVENLABS_VOICE_ID` 또는 `SAG_VOICE_ID`로 대체됩니다. - `providers.*.apiKey`는 일반 텍스트 문자열 또는 SecretRef 객체를 허용합니다. -- `ELEVENLABS_API_KEY` 대체값은 Talk API 키가 구성되지 않은 경우에만 적용됩니다. -- `providers.*.voiceAliases`를 사용하면 Talk 지시문에서 친숙한 이름을 사용할 수 있습니다. +- `ELEVENLABS_API_KEY` 대체값은 대화 API 키가 구성되지 않은 경우에만 적용됩니다. +- `providers.*.voiceAliases`를 사용하면 대화 지시문에서 친숙한 이름을 사용할 수 있습니다. - `providers.mlx.modelId`는 macOS 로컬 MLX 헬퍼가 사용하는 Hugging Face 저장소를 선택합니다. 생략하면 macOS는 `mlx-community/Soprano-80M-bf16`을 사용합니다. -- macOS MLX 재생은 번들 `openclaw-mlx-tts` 헬퍼가 있으면 이를 통해 실행되며, 없으면 `PATH`의 실행 파일을 통해 실행됩니다. 개발용으로는 `OPENCLAW_MLX_TTS_BIN`이 헬퍼 경로를 재정의합니다. -- `speechLocale`은 iOS/macOS Talk 음성 인식에서 사용하는 BCP 47 로캘 ID를 설정합니다. 설정하지 않으면 기기 기본값을 사용합니다. -- `silenceTimeoutMs`는 사용자 침묵 후 Talk 모드가 transcript를 보내기 전에 기다리는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 일시 중지 창(`macOS 및 Android에서는 700 ms, iOS에서는 900 ms`)이 유지됩니다. +- macOS MLX 재생은 번들 `openclaw-mlx-tts` 헬퍼가 있는 경우 이를 통해 실행되며, 없으면 `PATH`의 실행 파일을 사용합니다. `OPENCLAW_MLX_TTS_BIN`은 개발용 헬퍼 경로를 재정의합니다. +- `speechLocale`은 iOS/macOS 대화 음성 인식에 사용되는 BCP 47 로캘 ID를 설정합니다. 기기 기본값을 사용하려면 설정하지 않은 상태로 두세요. +- `silenceTimeoutMs`는 사용자가 침묵한 뒤 대화 모드가 전사를 보내기 전에 기다리는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 일시 중지 창(`macOS 및 Android에서는 700 ms, iOS에서는 900 ms`)을 유지합니다. --- diff --git a/docs/ko/gateway/config-channels.md b/docs/ko/gateway/config-channels.md index a34929e6f..73adaaa40 100644 --- a/docs/ko/gateway/config-channels.md +++ b/docs/ko/gateway/config-channels.md @@ -1,21 +1,21 @@ --- read_when: - 채널 Plugin 구성(인증, 접근 제어, 다중 계정) - - 채널별 구성 키 문제 해결 - - 다이렉트 메시지 정책, 그룹 정책 또는 멘션 게이팅 감사 -summary: '채널 구성: Slack, Discord, Telegram, WhatsApp, Matrix, iMessage 등 전반의 접근 제어, 페어링, 채널별 키' + - 채널별 설정 키 문제 해결 + - DM 정책, 그룹 정책 또는 멘션 게이팅 감사 +summary: '채널 구성: Slack, Discord, Telegram, WhatsApp, Matrix, iMessage 등 전반의 액세스 제어, 페어링, 채널별 키' title: 구성 — 채널 x-i18n: - generated_at: "2026-04-30T06:29:37Z" + generated_at: "2026-04-30T16:28:51Z" model: gpt-5.5 provider: openai - source_hash: e16ab50020711aac8e06cd234739ac7b566420cf7ce8621c0aca12c22484f07f + source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915 source_path: gateway/config-channels.md workflow: 16 --- -채널별 구성 키는 `channels.*` 아래에 있습니다. DM 및 그룹 액세스, -다중 계정 설정, 멘션 게이팅, Slack, Discord, +`channels.*` 아래의 채널별 구성 키입니다. DM 및 그룹 접근, +다중 계정 설정, 멘션 게이팅, 그리고 Slack, Discord, Telegram, WhatsApp, Matrix, iMessage 및 기타 번들 채널 Plugin의 채널별 키를 다룹니다. 에이전트, 도구, Gateway 런타임 및 기타 최상위 키는 @@ -23,34 +23,34 @@ Telegram, WhatsApp, Matrix, iMessage 및 기타 번들 채널 Plugin의 채널 ## 채널 -각 채널은 구성 섹션이 있으면 자동으로 시작됩니다(`enabled: false`인 경우 제외). +각 채널은 해당 구성 섹션이 있으면 자동으로 시작됩니다(`enabled: false`가 아닌 경우). -### DM 및 그룹 액세스 +### DM 및 그룹 접근 모든 채널은 DM 정책과 그룹 정책을 지원합니다. -| DM 정책 | 동작 | +| DM 정책 | 동작 | | ------------------- | --------------------------------------------------------------- | | `pairing` (기본값) | 알 수 없는 발신자는 일회성 페어링 코드를 받으며, 소유자가 승인해야 함 | | `allowlist` | `allowFrom`에 있거나 페어링된 허용 저장소에 있는 발신자만 허용 | -| `open` | 모든 수신 DM 허용(`allowFrom: ["*"]` 필요) | -| `disabled` | 모든 수신 DM 무시 | +| `open` | 모든 인바운드 DM 허용(`allowFrom: ["*"]` 필요) | +| `disabled` | 모든 인바운드 DM 무시 | -| 그룹 정책 | 동작 | +| 그룹 정책 | 동작 | | --------------------- | ------------------------------------------------------ | -| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용 | -| `open` | 그룹 허용 목록 우회(멘션 게이팅은 계속 적용됨) | -| `disabled` | 모든 그룹/방 메시지 차단 | +| `allowlist` (기본값) | 구성된 허용 목록과 일치하는 그룹만 허용 | +| `open` | 그룹 허용 목록 우회(멘션 게이팅은 계속 적용됨) | +| `disabled` | 모든 그룹/룸 메시지 차단 | `channels.defaults.groupPolicy`는 제공자의 `groupPolicy`가 설정되지 않았을 때 기본값을 설정합니다. 페어링 코드는 1시간 후 만료됩니다. 대기 중인 DM 페어링 요청은 **채널당 3개**로 제한됩니다. -제공자 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(닫힌 상태로 실패)로 대체됩니다. +제공자 블록이 완전히 누락된 경우(`channels.` 없음), 런타임 그룹 정책은 시작 경고와 함께 `allowlist`(실패 시 닫힘)로 대체됩니다. ### 채널 모델 재정의 -`channels.modelByChannel`을 사용해 특정 채널 ID를 모델에 고정합니다. 값은 `provider/model` 또는 구성된 모델 별칭을 허용합니다. 채널 매핑은 세션에 이미 모델 재정의가 없을 때 적용됩니다(예: `/model`을 통해 설정된 경우). +`channels.modelByChannel`을 사용하여 특정 채널 ID를 모델에 고정합니다. 값은 `provider/model` 또는 구성된 모델 별칭을 허용합니다. 채널 매핑은 세션에 이미 모델 재정의가 없을 때 적용됩니다(예: `/model`로 설정된 경우). ```json5 { @@ -73,7 +73,7 @@ Telegram, WhatsApp, Matrix, iMessage 및 기타 번들 채널 Plugin의 채널 ### 채널 기본값 및 Heartbeat -`channels.defaults`를 사용해 제공자 전반의 공유 그룹 정책 및 Heartbeat 동작을 설정합니다. +제공자 전반에서 공유되는 그룹 정책 및 Heartbeat 동작에는 `channels.defaults`를 사용합니다. ```json5 { @@ -91,11 +91,11 @@ Telegram, WhatsApp, Matrix, iMessage 및 기타 번들 채널 Plugin의 채널 } ``` -- `channels.defaults.groupPolicy`: 제공자 수준 `groupPolicy`가 설정되지 않았을 때 대체 그룹 정책입니다. -- `channels.defaults.contextVisibility`: 모든 채널의 기본 보조 컨텍스트 표시 모드입니다. 값: `all`(기본값, 인용/스레드/기록 컨텍스트 모두 포함), `allowlist`(허용 목록의 발신자 컨텍스트만 포함), `allowlist_quote`(허용 목록과 동일하지만 명시적 인용/답장 컨텍스트 유지). 채널별 재정의: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: Heartbeat 출력에 정상 채널 상태를 포함합니다. -- `channels.defaults.heartbeat.showAlerts`: Heartbeat 출력에 성능 저하/오류 상태를 포함합니다. -- `channels.defaults.heartbeat.useIndicator`: 간결한 표시기 스타일 Heartbeat 출력을 렌더링합니다. +- `channels.defaults.groupPolicy`: 제공자 수준의 `groupPolicy`가 설정되지 않았을 때의 대체 그룹 정책입니다. +- `channels.defaults.contextVisibility`: 모든 채널의 기본 보조 컨텍스트 표시 모드입니다. 값: `all`(기본값, 모든 인용/스레드/기록 컨텍스트 포함), `allowlist`(허용 목록의 발신자 컨텍스트만 포함), `allowlist_quote`(allowlist와 같지만 명시적 인용/답장 컨텍스트 유지). 채널별 재정의: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: 정상 채널 상태를 Heartbeat 출력에 포함합니다. +- `channels.defaults.heartbeat.showAlerts`: 저하/오류 상태를 Heartbeat 출력에 포함합니다. +- `channels.defaults.heartbeat.useIndicator`: 간결한 표시기 스타일의 Heartbeat 출력을 렌더링합니다. ### WhatsApp @@ -139,7 +139,7 @@ WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` - + ```json5 { @@ -157,9 +157,9 @@ WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 발신 명령은 존재하는 경우 기본적으로 `default` 계정을 사용하며, 그렇지 않으면 구성된 첫 번째 계정 ID(정렬됨)를 사용합니다. +- 아웃바운드 명령은 있으면 `default` 계정을 기본으로 사용하며, 없으면 구성된 첫 번째 계정 ID(정렬됨)를 사용합니다. - 선택 사항인 `channels.whatsapp.defaultAccount`는 구성된 계정 ID와 일치할 때 해당 대체 기본 계정 선택을 재정의합니다. -- 기존 단일 계정 Baileys 인증 디렉터리는 `openclaw doctor`에 의해 `whatsapp/default`로 마이그레이션됩니다. +- 레거시 단일 계정 Baileys 인증 디렉터리는 `openclaw doctor`에 의해 `whatsapp/default`로 마이그레이션됩니다. - 계정별 재정의: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -219,13 +219,13 @@ WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- 봇 토큰: `channels.telegram.botToken` 또는 `channels.telegram.tokenFile`(일반 파일만 허용, 심볼릭 링크 거부)이며, 기본 계정의 대체 값으로 `TELEGRAM_BOT_TOKEN`을 사용합니다. -- `apiRoot`는 Telegram Bot API 루트 전용입니다. `https://api.telegram.org/bot`이 아니라 `https://api.telegram.org` 또는 자체 호스팅/프록시 루트를 사용하세요. `openclaw doctor --fix`는 실수로 붙은 후행 `/bot` 접미사를 제거합니다. +- 봇 토큰: `channels.telegram.botToken` 또는 `channels.telegram.tokenFile`(일반 파일만, 심볼릭 링크는 거부됨), 기본 계정의 대체값으로 `TELEGRAM_BOT_TOKEN` 사용. +- `apiRoot`는 Telegram Bot API 루트만 의미합니다. `https://api.telegram.org/bot`이 아니라 `https://api.telegram.org` 또는 자체 호스팅/프록시 루트를 사용하세요. `openclaw doctor --fix`는 실수로 붙은 `/bot` 접미사를 제거합니다. - 선택 사항인 `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 에이전트](/ko/tools/acp-agents#channel-specific-settings)에서 공유됩니다. -- Telegram 스트림 미리보기는 `sendMessage` + `editMessageText`를 사용합니다(직접 채팅 및 그룹 채팅에서 작동). +- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 포럼 주제에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에서 표준 `chatId:topic:topicId` 사용). 필드 의미는 [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings)에서 공유됩니다. +- Telegram 스트림 미리보기는 `sendMessage` + `editMessageText`를 사용합니다(직접 채팅과 그룹 채팅에서 작동). - 재시도 정책: [재시도 정책](/ko/concepts/retry)을 참고하세요. ### Discord @@ -329,36 +329,36 @@ WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 ``` - 토큰: `channels.discord.token`, 기본 계정의 대체값은 `DISCORD_BOT_TOKEN`입니다. -- 명시적인 Discord `token`을 제공하는 직접 아웃바운드 호출은 해당 호출에 그 토큰을 사용합니다. 계정 재시도/정책 설정은 여전히 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다. -- 선택적 `channels.discord.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- 전달 대상에는 `user:`(DM) 또는 `channel:`(길드 채널)를 사용합니다. 숫자 ID만 단독으로 쓰면 거부됩니다. -- 길드 슬러그는 소문자이며 공백은 `-`로 대체됩니다. 채널 키는 슬러그 처리된 이름을 사용합니다(`#` 없음). 길드 ID 사용을 권장합니다. -- 봇이 작성한 메시지는 기본적으로 무시됩니다. `allowBots: true`는 이를 활성화합니다. `allowBots: "mentions"`를 사용하면 봇을 멘션한 봇 메시지만 허용합니다(자신의 메시지는 계속 필터링됨). -- `channels.discord.guilds..ignoreOtherMentions`(및 채널 재정의)는 봇이 아닌 다른 사용자나 역할을 멘션한 메시지를 삭제합니다(@everyone/@here 제외). +- 명시적 Discord `token`을 제공하는 직접 아웃바운드 호출은 해당 호출에 그 토큰을 사용합니다. 계정 재시도/정책 설정은 여전히 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다. +- 선택 사항인 `channels.discord.defaultAccount`는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다. +- 전달 대상에는 `user:`(DM) 또는 `channel:`(길드 채널)를 사용하세요. 숫자 ID만 단독으로 쓰면 거부됩니다. +- 길드 슬러그는 소문자이며 공백은 `-`로 대체됩니다. 채널 키는 슬러그 처리된 이름을 사용합니다(`#` 없음). 길드 ID를 권장합니다. +- Bot이 작성한 메시지는 기본적으로 무시됩니다. `allowBots: true`는 이를 활성화합니다. Bot을 멘션한 Bot 메시지만 허용하려면 `allowBots: "mentions"`를 사용하세요(자신의 메시지는 계속 필터링됨). +- `channels.discord.guilds..ignoreOtherMentions`(및 채널 재정의)는 Bot이 아닌 다른 사용자나 역할을 멘션하는 메시지를 버립니다(@everyone/@here 제외). - `maxLinesPerMessage`(기본값 17)는 2000자 미만이어도 긴 메시지를 분할합니다. - `channels.discord.threadBindings`는 Discord 스레드 바인딩 라우팅을 제어합니다. - - `enabled`: 스레드 바인딩 세션 기능에 대한 Discord 재정의(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, 및 바인딩된 전달/라우팅) - - `idleHours`: 비활성 자동 언포커스 시간에 대한 Discord 재정의(`0`은 비활성화) - - `maxAgeHours`: 하드 최대 수명 시간에 대한 Discord 재정의(`0`은 비활성화) + - `enabled`: 스레드 바인딩 세션 기능(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, 바인딩된 전달/라우팅)에 대한 Discord 재정의 + - `idleHours`: 비활성 자동 포커스 해제 시간(시간 단위)에 대한 Discord 재정의(`0`은 비활성화) + - `maxAgeHours`: 엄격한 최대 수명(시간 단위)에 대한 Discord 재정의(`0`은 비활성화) - `spawnSubagentSessions`: `sessions_spawn({ thread: true })` 자동 스레드 생성/바인딩을 위한 옵트인 스위치 -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 채널과 스레드에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에 채널/스레드 ID 사용). 필드 의미 체계는 [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings)에서 공유됩니다. -- `channels.discord.ui.components.accentColor`는 Discord components v2 컨테이너의 강조 색상을 설정합니다. +- 최상위 `bindings[]` 항목에 `type: "acp"`를 지정하면 채널과 스레드에 대한 영구 ACP 바인딩을 구성합니다(`match.peer.id`에 채널/스레드 id 사용). 필드 의미는 [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings)에서 공유됩니다. +- `channels.discord.ui.components.accentColor`는 Discord 컴포넌트 v2 컨테이너의 강조 색상을 설정합니다. - `channels.discord.voice`는 Discord 음성 채널 대화와 선택적 자동 참여 + LLM + TTS 재정의를 활성화합니다. - `channels.discord.voice.model`은 Discord 음성 채널 응답에 사용되는 LLM 모델을 선택적으로 재정의합니다. - `channels.discord.voice.daveEncryption` 및 `channels.discord.voice.decryptionFailureTolerance`는 `@discordjs/voice` DAVE 옵션으로 전달됩니다(기본값은 `true` 및 `24`). -- OpenClaw는 반복된 복호화 실패 후 음성 세션에서 나갔다가 다시 참여하여 음성 수신 복구도 시도합니다. -- `channels.discord.streaming`은 표준 스트림 모드 키입니다. 레거시 `streamMode` 및 불리언 `streaming` 값은 자동 마이그레이션됩니다. -- `channels.discord.autoPresence`는 런타임 가용성을 봇 상태로 매핑하고(healthy => online, degraded => idle, exhausted => dnd) 선택적 상태 텍스트 재정의를 허용합니다. -- `channels.discord.dangerouslyAllowNameMatching`은 변경 가능한 이름/태그 매칭을 다시 활성화합니다(비상 호환성 모드). +- OpenClaw는 반복된 복호화 실패 후 음성 세션을 나갔다가 다시 참여해 음성 수신 복구도 시도합니다. +- `channels.discord.streaming`은 표준 스트림 모드 키입니다. 레거시 `streamMode` 및 불리언 `streaming` 값은 자동으로 마이그레이션됩니다. +- `channels.discord.autoPresence`는 런타임 가용성을 Bot 상태(healthy => online, degraded => idle, exhausted => dnd)에 매핑하고 선택적 상태 텍스트 재정의를 허용합니다. +- `channels.discord.dangerouslyAllowNameMatching`은 변경 가능한 이름/태그 매칭을 다시 활성화합니다(긴급 호환성 모드). - `channels.discord.execApprovals`: Discord 네이티브 exec 승인 전달 및 승인자 권한 부여. - - `enabled`: `true`, `false`, 또는 `"auto"`(기본값). 자동 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. - - `approvers`: exec 요청을 승인할 수 있는 Discord 사용자 ID입니다. 생략하면 `commands.ownerAllowFrom`으로 대체됩니다. - - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 모든 에이전트의 승인을 전달하려면 생략합니다. + - `enabled`: `true`, `false` 또는 `"auto"`(기본값). auto 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. + - `approvers`: exec 요청을 승인할 수 있는 Discord 사용자 ID. 생략하면 `commands.ownerAllowFrom`으로 대체됩니다. + - `agentFilter`: 선택적 에이전트 ID 허용 목록. 생략하면 모든 에이전트의 승인을 전달합니다. - `sessionFilter`: 선택적 세션 키 패턴(부분 문자열 또는 정규식). - - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값)은 승인자 DM으로 보내고, `"channel"`은 원본 채널로 보내며, `"both"`는 둘 다로 보냅니다. 대상에 `"channel"`이 포함되면 버튼은 확인된 승인자만 사용할 수 있습니다. + - `target`: 승인 프롬프트를 보낼 위치. `"dm"`(기본값)은 승인자 DM으로 보내고, `"channel"`은 원본 채널로 보내며, `"both"`는 둘 다에 보냅니다. target에 `"channel"`이 포함되면 버튼은 확인된 승인자만 사용할 수 있습니다. - `cleanupAfterResolve`: `true`이면 승인, 거부 또는 시간 초과 후 승인 DM을 삭제합니다. -**반응 알림 모드:** `off`(없음), `own`(봇의 메시지, 기본값), `all`(모든 메시지), `allowlist`(모든 메시지에서 `guilds..users` 기준). +**반응 알림 모드:** `off`(없음), `own`(Bot의 메시지, 기본값), `all`(모든 메시지), `allowlist`(모든 메시지에서 `guilds..users` 기준). ### Google Chat @@ -392,8 +392,8 @@ WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 - 서비스 계정 JSON: 인라인(`serviceAccount`) 또는 파일 기반(`serviceAccountFile`). - 서비스 계정 SecretRef도 지원됩니다(`serviceAccountRef`). - 환경 대체값: `GOOGLE_CHAT_SERVICE_ACCOUNT` 또는 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- 전달 대상에는 `spaces/` 또는 `users/`를 사용합니다. -- `channels.googlechat.dangerouslyAllowNameMatching`은 변경 가능한 이메일 주체 매칭을 다시 활성화합니다(비상 호환성 모드). +- 전달 대상에는 `spaces/` 또는 `users/`를 사용하세요. +- `channels.googlechat.dangerouslyAllowNameMatching`은 변경 가능한 이메일 주체 매칭을 다시 활성화합니다(긴급 호환성 모드). ### Slack @@ -465,35 +465,35 @@ WhatsApp은 Gateway의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결 } ``` -- **소켓 모드**에는 `botToken`과 `appToken`이 모두 필요합니다(기본 계정 환경 대체값은 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). +- **Socket 모드**에는 `botToken`과 `appToken`이 모두 필요합니다(기본 계정 env 대체값은 `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN`). - **HTTP 모드**에는 `botToken`과 `signingSecret`이 필요합니다(루트 또는 계정별). -- `socketMode`는 Slack SDK 소켓 모드 전송 튜닝을 공개 Bolt receiver API로 전달합니다. ping/pong 시간 초과 또는 오래된 websocket 동작을 조사할 때만 사용하세요. -- `botToken`, `appToken`, `signingSecret`, `userToken`은 평문 문자열 또는 SecretRef 객체를 허용합니다. -- Slack 계정 스냅샷은 `botTokenSource`, `botTokenStatus`, `appTokenStatus` 같은 자격 증명별 출처/상태 필드와, HTTP 모드에서는 `signingSecretStatus`를 노출합니다. `configured_unavailable`은 계정이 SecretRef를 통해 구성되었지만 현재 명령/런타임 경로에서 비밀 값을 확인할 수 없었음을 의미합니다. +- `socketMode`는 Slack SDK Socket Mode 전송 튜닝을 공개 Bolt receiver API로 전달합니다. ping/pong 시간 초과 또는 오래된 websocket 동작을 조사할 때만 사용하세요. +- `botToken`, `appToken`, `signingSecret`, `userToken`은 일반 텍스트 문자열 또는 SecretRef 객체를 허용합니다. +- Slack 계정 스냅샷은 `botTokenSource`, `botTokenStatus`, `appTokenStatus`, HTTP 모드의 경우 `signingSecretStatus` 같은 자격 증명별 소스/상태 필드를 노출합니다. `configured_unavailable`은 계정이 SecretRef를 통해 구성되었지만 현재 명령/런타임 경로가 비밀 값을 확인할 수 없었음을 의미합니다. - `configWrites: false`는 Slack에서 시작된 구성 쓰기를 차단합니다. -- 선택적 `channels.slack.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- `channels.slack.streaming.mode`는 표준 Slack 스트림 모드 키입니다. `channels.slack.streaming.nativeTransport`는 Slack의 네이티브 스트리밍 전송을 제어합니다. 레거시 `streamMode`, 불리언 `streaming`, `nativeStreaming` 값은 자동 마이그레이션됩니다. -- 전달 대상에는 `user:`(DM) 또는 `channel:`를 사용합니다. +- 선택 사항인 `channels.slack.defaultAccount`는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다. +- `channels.slack.streaming.mode`는 표준 Slack 스트림 모드 키입니다. `channels.slack.streaming.nativeTransport`는 Slack의 네이티브 스트리밍 전송을 제어합니다. 레거시 `streamMode`, 불리언 `streaming`, `nativeStreaming` 값은 자동으로 마이그레이션됩니다. +- 전달 대상에는 `user:`(DM) 또는 `channel:`를 사용하세요. **반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist` 기준). -**스레드 세션 격리:** `thread.historyScope`는 스레드별(기본값)이거나 채널 전체에서 공유됩니다. `thread.inheritParent`는 부모 채널 대화 기록을 새 스레드로 복사합니다. +**스레드 세션 격리:** `thread.historyScope`는 스레드별(기본값) 또는 채널 전체 공유입니다. `thread.inheritParent`는 부모 채널 transcript를 새 스레드로 복사합니다. -- Slack 네이티브 스트리밍과 Slack assistant 스타일의 "is typing..." 스레드 상태에는 답장 스레드 대상이 필요합니다. 최상위 DM은 기본적으로 스레드 밖에 유지되므로 스레드 스타일 미리보기 대신 `typingReaction` 또는 일반 전달을 사용합니다. -- `typingReaction`은 답장이 실행되는 동안 수신 Slack 메시지에 임시 반응을 추가한 다음 완료 시 제거합니다. `"hourglass_flowing_sand"` 같은 Slack emoji 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 emoji shortcode를 사용하세요. +- `channels.slack.execApprovals`: Slack 네이티브 exec 승인 전달 및 승인자 권한 부여. Discord와 동일한 스키마입니다: `enabled`(`true`/`false`/`"auto"`), `approvers`(Slack 사용자 ID), `agentFilter`, `sessionFilter`, `target`(`"dm"`, `"channel"` 또는 `"both"`). | 작업 그룹 | 기본값 | 참고 | | ------------ | ------- | ---------------------- | -| reactions | enabled | 반응 추가 + 반응 목록 | -| messages | enabled | 읽기/보내기/편집/삭제 | -| pins | enabled | 고정/고정 해제/목록 | -| memberInfo | enabled | 멤버 정보 | -| emojiList | enabled | 사용자 지정 emoji 목록 | +| reactions | 활성화됨 | 반응 추가 + 반응 목록 | +| messages | 활성화됨 | 읽기/보내기/편집/삭제 | +| pins | 활성화됨 | 고정/고정 해제/목록 | +| memberInfo | 활성화됨 | 멤버 정보 | +| emojiList | 활성화됨 | 사용자 지정 emoji 목록 | ### Mattermost -Mattermost는 현재 OpenClaw 릴리스에서 번들 Plugin으로 제공됩니다. 이전 빌드나 사용자 지정 빌드는 `openclaw plugins install @openclaw/mattermost`로 현재 npm 패키지를 설치할 수 있습니다. npm이 OpenClaw 소유 패키지를 deprecated로 보고하면 더 최신 npm 패키지가 게시될 때까지 번들 Plugin 또는 로컬 체크아웃을 사용하세요. +Mattermost는 현재 OpenClaw 릴리스에서 번들 Plugin으로 제공됩니다. 이전 빌드나 사용자 지정 빌드는 `openclaw plugins install @openclaw/mattermost`로 현재 npm 패키지를 설치할 수 있습니다. npm이 OpenClaw 소유 패키지를 deprecated로 보고하면, 더 새로운 npm 패키지가 게시될 때까지 번들 Plugin 또는 로컬 체크아웃을 사용하세요. ```json5 { @@ -523,18 +523,18 @@ Mattermost는 현재 OpenClaw 릴리스에서 번들 Plugin으로 제공됩니 } ``` -채팅 모드: `oncall`(@-멘션에 응답, 기본값), `onmessage`(모든 메시지), `onchar`(트리거 접두사로 시작하는 메시지). +채팅 모드: `oncall`(@멘션 시 응답, 기본값), `onmessage`(모든 메시지), `onchar`(트리거 접두사로 시작하는 메시지). Mattermost 네이티브 명령이 활성화된 경우: - `commands.callbackPath`는 전체 URL이 아니라 경로여야 합니다(예: `/api/channels/mattermost/command`). -- `commands.callbackUrl`은 OpenClaw Gateway 엔드포인트로 해석되어야 하며 Mattermost 서버에서 접근 가능해야 합니다. -- 네이티브 slash callback은 slash command 등록 중 Mattermost가 반환하는 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 `Unauthorized: invalid command token.`으로 callback을 거부합니다. -- 프라이빗/tailnet/내부 callback 호스트의 경우, Mattermost는 `ServiceSettings.AllowedUntrustedInternalConnections`에 callback 호스트/도메인을 포함하도록 요구할 수 있습니다. 전체 URL이 아니라 호스트/도메인 값을 사용하세요. +- `commands.callbackUrl`은 OpenClaw Gateway 엔드포인트로 확인되어야 하며 Mattermost 서버에서 접근 가능해야 합니다. +- 네이티브 슬래시 콜백은 슬래시 명령 등록 중 Mattermost가 반환한 명령별 토큰으로 인증됩니다. 등록에 실패하거나 활성화된 명령이 없으면 OpenClaw는 `Unauthorized: invalid command token.`으로 콜백을 거부합니다. +- private/tailnet/internal 콜백 호스트의 경우, Mattermost는 `ServiceSettings.AllowedUntrustedInternalConnections`에 콜백 호스트/도메인을 포함하도록 요구할 수 있습니다. 전체 URL이 아니라 호스트/도메인 값을 사용하세요. - `channels.mattermost.configWrites`: Mattermost에서 시작된 구성 쓰기를 허용하거나 거부합니다. - `channels.mattermost.requireMention`: 채널에서 답장하기 전에 `@mention`을 요구합니다. - `channels.mattermost.groups..requireMention`: 채널별 멘션 게이트 재정의(기본값은 `"*"`). -- 선택적 `channels.mattermost.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. +- 선택 사항인 `channels.mattermost.defaultAccount`는 구성된 계정 id와 일치할 때 기본 계정 선택을 재정의합니다. ### Signal @@ -558,7 +558,7 @@ Mattermost 네이티브 명령이 활성화된 경우: **반응 알림 모드:** `off`, `own`(기본값), `all`, `allowlist`(`reactionAllowlist`에서 가져옴). - `channels.signal.account`: 채널 시작을 특정 Signal 계정 ID에 고정합니다. -- `channels.signal.configWrites`: Signal에서 시작한 구성 쓰기를 허용하거나 거부합니다. +- `channels.signal.configWrites`: Signal에서 시작된 설정 쓰기를 허용하거나 거부합니다. - 선택 사항인 `channels.signal.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. ### BlueBubbles @@ -580,12 +580,12 @@ BlueBubbles는 권장 iMessage 경로입니다(Plugin 기반, `channels.bluebubb - 여기에서 다루는 핵심 키 경로: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. - 선택 사항인 `channels.bluebubbles.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 BlueBubbles 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에서 BlueBubbles 핸들이나 대상 문자열(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공유 필드 의미: [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings). +- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 BlueBubbles 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에서 BlueBubbles 핸들 또는 대상 문자열(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공유 필드 의미 체계: [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings). - 전체 BlueBubbles 채널 구성은 [BlueBubbles](/ko/channels/bluebubbles)에 문서화되어 있습니다. ### iMessage -OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 생성합니다. 데몬이나 포트가 필요하지 않습니다. +OpenClaw는 `imsg rpc`를 실행합니다(stdio를 통한 JSON-RPC). 데몬이나 포트는 필요하지 않습니다. ```json5 { @@ -612,12 +612,12 @@ OpenClaw는 `imsg rpc`(stdio를 통한 JSON-RPC)를 생성합니다. 데몬이 - 선택 사항인 `channels.imessage.defaultAccount`는 구성된 계정 ID와 일치할 때 기본 계정 선택을 재정의합니다. - Messages DB에 대한 전체 디스크 접근 권한이 필요합니다. -- `chat_id:` 대상을 선호하세요. 채팅 목록을 보려면 `imsg chats --limit 20`을 사용하세요. +- `chat_id:` 대상을 권장합니다. 채팅 목록을 보려면 `imsg chats --limit 20`을 사용하세요. - `cliPath`는 SSH 래퍼를 가리킬 수 있습니다. SCP 첨부 파일 가져오기를 위해 `remoteHost`(`host` 또는 `user@host`)를 설정하세요. -- `attachmentRoots`와 `remoteAttachmentRoots`는 인바운드 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). -- SCP는 엄격한 호스트 키 확인을 사용하므로 릴레이 호스트 키가 이미 `~/.ssh/known_hosts`에 있는지 확인하세요. -- `channels.imessage.configWrites`: iMessage에서 시작한 구성 쓰기를 허용하거나 거부합니다. -- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에서 정규화된 핸들이나 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공유 필드 의미: [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings). +- `attachmentRoots` 및 `remoteAttachmentRoots`는 인바운드 첨부 파일 경로를 제한합니다(기본값: `/Users/*/Library/Messages/Attachments`). +- SCP는 엄격한 호스트 키 검사를 사용하므로 릴레이 호스트 키가 이미 `~/.ssh/known_hosts`에 있는지 확인하세요. +- `channels.imessage.configWrites`: iMessage에서 시작된 설정 쓰기를 허용하거나 거부합니다. +- `type: "acp"`가 있는 최상위 `bindings[]` 항목은 iMessage 대화를 영구 ACP 세션에 바인딩할 수 있습니다. `match.peer.id`에서 정규화된 핸들 또는 명시적 채팅 대상(`chat_id:*`, `chat_guid:*`, `chat_identifier:*`)을 사용하세요. 공유 필드 의미 체계: [ACP 에이전트](/ko/tools/acp-agents#channel-specific-settings). @@ -661,20 +661,20 @@ Matrix는 Plugin 기반이며 `channels.matrix` 아래에 구성됩니다. ``` - 토큰 인증은 `accessToken`을 사용하고, 비밀번호 인증은 `userId` + `password`를 사용합니다. -- `channels.matrix.proxy`는 명시적 HTTP(S) 프록시를 통해 Matrix HTTP 트래픽을 라우팅합니다. 이름이 지정된 계정은 `channels.matrix.accounts..proxy`로 이를 재정의할 수 있습니다. +- `channels.matrix.proxy`는 Matrix HTTP 트래픽을 명시적 HTTP(S) 프록시를 통해 라우팅합니다. 명명된 계정은 `channels.matrix.accounts..proxy`로 이를 재정의할 수 있습니다. - `channels.matrix.network.dangerouslyAllowPrivateNetwork`는 비공개/내부 홈서버를 허용합니다. `proxy`와 이 네트워크 옵트인은 독립적인 제어 항목입니다. - `channels.matrix.defaultAccount`는 다중 계정 설정에서 선호 계정을 선택합니다. - `channels.matrix.autoJoin`의 기본값은 `off`이므로, `autoJoinAllowlist`와 함께 `autoJoin: "allowlist"`를 설정하거나 `autoJoin: "always"`를 설정할 때까지 초대된 방과 새 DM 스타일 초대는 무시됩니다. -- `channels.matrix.execApprovals`: Matrix 네이티브 exec 승인 전달 및 승인자 권한 부여입니다. +- `channels.matrix.execApprovals`: Matrix 네이티브 exec 승인 전달 및 승인자 권한 부여. - `enabled`: `true`, `false` 또는 `"auto"`(기본값). 자동 모드에서는 `approvers` 또는 `commands.ownerAllowFrom`에서 승인자를 확인할 수 있을 때 exec 승인이 활성화됩니다. - - `approvers`: exec 요청을 승인할 수 있는 Matrix 사용자 ID(예: `@owner:example.org`)입니다. - - `agentFilter`: 선택 사항인 에이전트 ID 허용 목록입니다. 모든 에이전트의 승인을 전달하려면 생략하세요. - - `sessionFilter`: 선택 사항인 세션 키 패턴(부분 문자열 또는 정규식)입니다. + - `approvers`: exec 요청을 승인할 수 있는 Matrix 사용자 ID(예: `@owner:example.org`). + - `agentFilter`: 선택적 에이전트 ID 허용 목록입니다. 생략하면 모든 에이전트에 대한 승인을 전달합니다. + - `sessionFilter`: 선택적 세션 키 패턴(하위 문자열 또는 정규식). - `target`: 승인 프롬프트를 보낼 위치입니다. `"dm"`(기본값), `"channel"`(원본 방) 또는 `"both"`. - 계정별 재정의: `channels.matrix.accounts..execApprovals`. - `channels.matrix.dm.sessionScope`는 Matrix DM이 세션으로 그룹화되는 방식을 제어합니다. `per-user`(기본값)는 라우팅된 피어별로 공유하고, `per-room`은 각 DM 방을 격리합니다. -- Matrix 상태 프로브와 실시간 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. -- 전체 Matrix 구성, 대상 지정 규칙, 설정 예시는 [Matrix](/ko/channels/matrix)에 문서화되어 있습니다. +- Matrix 상태 프로브와 라이브 디렉터리 조회는 런타임 트래픽과 동일한 프록시 정책을 사용합니다. +- 전체 Matrix 구성, 대상 지정 규칙 및 설정 예시는 [Matrix](/ko/channels/matrix)에 문서화되어 있습니다. ### Microsoft Teams @@ -725,7 +725,7 @@ IRC는 Plugin 기반이며 `channels.irc` 아래에 구성됩니다. ### 다중 계정(모든 채널) -채널당 여러 계정을 실행합니다(각각 고유한 `accountId` 포함). +채널별로 여러 계정을 실행합니다(각각 자체 `accountId` 보유). ```json5 { @@ -750,9 +750,9 @@ IRC는 Plugin 기반이며 `channels.irc` 아래에 구성됩니다. - 환경 토큰은 **기본** 계정에만 적용됩니다. - 기본 채널 설정은 계정별로 재정의하지 않는 한 모든 계정에 적용됩니다. - 각 계정을 다른 에이전트로 라우팅하려면 `bindings[].match.accountId`를 사용하세요. -- 단일 계정 최상위 채널 구성에서 `openclaw channels add`(또는 채널 온보딩)로 기본값이 아닌 계정을 추가하면, OpenClaw는 원래 계정이 계속 작동하도록 계정 범위의 최상위 단일 계정 값을 먼저 채널 계정 맵으로 승격합니다. 대부분의 채널은 이를 `channels..accounts.default`로 이동합니다. Matrix는 대신 기존의 일치하는 이름 지정/기본 대상을 보존할 수 있습니다. -- 기존 채널 전용 바인딩(`accountId` 없음)은 계속 기본 계정과 매칭됩니다. 계정 범위 바인딩은 계속 선택 사항입니다. -- `openclaw doctor --fix`도 계정 범위의 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 이동하여 혼합 형태를 복구합니다. 대부분의 채널은 `accounts.default`를 사용합니다. Matrix는 대신 기존의 일치하는 이름 지정/기본 대상을 보존할 수 있습니다. +- 단일 계정 최상위 채널 설정을 계속 사용하는 상태에서 `openclaw channels add`(또는 채널 온보딩)를 통해 기본값이 아닌 계정을 추가하면, OpenClaw는 먼저 계정 범위 최상위 단일 계정 값을 채널 계정 맵으로 승격하여 원래 계정이 계속 작동하도록 합니다. 대부분의 채널은 이를 `channels..accounts.default`로 이동합니다. Matrix는 대신 기존의 일치하는 명명된/기본 대상을 보존할 수 있습니다. +- 기존 채널 전용 바인딩(`accountId` 없음)은 기본 계정과 계속 일치합니다. 계정 범위 바인딩은 계속 선택 사항입니다. +- `openclaw doctor --fix`도 계정 범위 최상위 단일 계정 값을 해당 채널에 대해 선택된 승격 계정으로 이동하여 혼합 형태를 복구합니다. 대부분의 채널은 `accounts.default`를 사용합니다. Matrix는 대신 기존의 일치하는 명명된/기본 대상을 보존할 수 있습니다. ### 기타 Plugin 채널 @@ -761,15 +761,17 @@ IRC는 Plugin 기반이며 `channels.irc` 아래에 구성됩니다. ### 그룹 채팅 멘션 게이팅 -그룹 메시지는 기본적으로 **멘션 필요**입니다(메타데이터 멘션 또는 안전한 정규식 패턴). WhatsApp, Telegram, Discord, Google Chat, iMessage 그룹 채팅에 적용됩니다. +그룹 메시지는 기본적으로 **멘션 필요**(메타데이터 멘션 또는 안전한 정규식 패턴)입니다. WhatsApp, Telegram, Discord, Google Chat 및 iMessage 그룹 채팅에 적용됩니다. -표시되는 답장은 별도로 제어됩니다. 그룹/채널 방의 기본값은 `messages.groupChat.visibleReplies: "message_tool"`입니다. OpenClaw는 여전히 턴을 처리하지만, 일반 최종 답장은 비공개로 유지되고 방에 표시되는 출력에는 `message(action=send)`가 필요합니다. 일반 답장이 방에 다시 게시되는 레거시 동작을 원할 때만 `"automatic"`을 설정하세요. 동일한 도구 전용 표시 답장 동작을 직접 채팅에도 적용하려면 `messages.visibleReplies: "message_tool"`을 설정하세요. +표시되는 답장은 별도로 제어됩니다. 그룹/채널 방의 기본값은 `messages.groupChat.visibleReplies: "message_tool"`입니다. OpenClaw는 여전히 해당 턴을 처리하지만, 일반 최종 답장은 비공개로 유지되고 방에 표시되는 출력은 `message(action=send)`가 필요합니다. 일반 답장을 방에 다시 게시하는 레거시 동작을 원할 때만 `"automatic"`을 설정하세요. 직접 채팅에도 동일한 도구 전용 표시 답장 동작을 적용하려면 `messages.visibleReplies: "message_tool"`을 설정하세요. + +Gateway는 파일이 저장된 뒤 `messages` 설정을 핫 리로드합니다. 배포에서 파일 감시 또는 설정 리로드가 비활성화된 경우에만 다시 시작하세요. **멘션 유형:** - **메타데이터 멘션**: 네이티브 플랫폼 @-멘션입니다. WhatsApp 셀프 채팅 모드에서는 무시됩니다. - **텍스트 패턴**: `agents.list[].groupChat.mentionPatterns`의 안전한 정규식 패턴입니다. 잘못된 패턴과 안전하지 않은 중첩 반복은 무시됩니다. -- 멘션 게이팅은 감지가 가능할 때만 적용됩니다(네이티브 멘션 또는 하나 이상의 패턴). +- 멘션 게이팅은 감지가 가능한 경우(네이티브 멘션 또는 하나 이상의 패턴)에만 적용됩니다. ```json5 { @@ -786,7 +788,7 @@ IRC는 Plugin 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -`messages.groupChat.historyLimit`는 전역 기본값을 설정합니다. 채널은 `channels..historyLimit`(또는 계정별)로 재정의할 수 있습니다. 비활성화하려면 `0`으로 설정하세요. +`messages.groupChat.historyLimit`는 전역 기본값을 설정합니다. 채널은 `channels..historyLimit`(또는 계정별 설정)로 재정의할 수 있습니다. 비활성화하려면 `0`으로 설정하세요. `messages.visibleReplies`는 전역 소스 턴 기본값입니다. `messages.groupChat.visibleReplies`는 그룹/채널 소스 턴에 대해 이를 재정의합니다. 채널 허용 목록과 멘션 게이팅은 여전히 턴 처리 여부를 결정합니다. @@ -805,13 +807,13 @@ IRC는 Plugin 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -해결 순서: DM별 재정의 → 제공자 기본값 → 제한 없음(모두 유지). +해결 순서: DM별 재정의 → 제공자 기본값 → 제한 없음(모두 보존). 지원: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### 셀프 채팅 모드 -셀프 채팅 모드를 활성화하려면 `allowFrom`에 자신의 번호를 포함하세요(네이티브 @-멘션은 무시하고 텍스트 패턴에만 응답). +셀프 채팅 모드를 활성화하려면 `allowFrom`에 본인 번호를 포함하세요(네이티브 @-멘션을 무시하고 텍스트 패턴에만 응답). ```json5 { @@ -832,54 +834,29 @@ IRC는 Plugin 기반이며 `channels.irc` 아래에 구성됩니다. } ``` -### 명령(채팅 명령 처리) - -```json5 -{ - commands: { - native: "auto", // register native commands when supported - nativeSkills: "auto", // register native skill commands when supported - text: true, // parse /commands in chat messages - bash: false, // allow ! (alias: /bash) - bashForegroundMs: 2000, - config: false, // allow /config - mcp: false, // allow /mcp - plugins: false, // allow /plugins - debug: false, // allow /debug - restart: true, // allow /restart + gateway restart tool - ownerAllowFrom: ["discord:123456789012345678"], - ownerDisplay: "raw", // raw | hash - ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", - allowFrom: { - "*": ["user1"], - discord: ["user:123"], - }, - useAccessGroups: true, - }, -} -``` - +### 명령(채팅 명령 처리)``` +__OC_I18N_900020__ -- 이 블록은 명령 표면을 구성합니다. 현재 기본 제공 + 번들 명령 카탈로그는 [슬래시 명령](/ko/tools/slash-commands)을 참조하세요. -- 이 페이지는 전체 명령 카탈로그가 아니라 **구성 키 참조**입니다. QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, 기기 페어링 `/pair`, 메모리 `/dreaming`, 휴대폰 제어 `/phone`, Talk `/voice`처럼 채널/Plugin이 소유한 명령은 해당 채널/Plugin 페이지와 [슬래시 명령](/ko/tools/slash-commands)에 문서화되어 있습니다. +- 이 블록은 명령 표면을 구성합니다. 현재 기본 제공 + 번들 명령 카탈로그는 [슬래시 명령](/tools/slash-commands)을 참조하세요. +- 이 페이지는 전체 명령 카탈로그가 아니라 **구성 키 참조**입니다. QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, 기기 페어링 `/pair`, 메모리 `/dreaming`, 전화 제어 `/phone`, Talk `/voice`처럼 채널/Plugin이 소유한 명령은 해당 채널/Plugin 페이지와 [슬래시 명령](/tools/slash-commands)에 문서화되어 있습니다. - 텍스트 명령은 앞에 `/`가 붙은 **독립형** 메시지여야 합니다. -- `native: "auto"`는 Discord/Telegram의 네이티브 명령을 켜고, Slack은 꺼진 상태로 둡니다. -- `nativeSkills: "auto"`는 Discord/Telegram의 네이티브 Skills 명령을 켜고, Slack은 꺼진 상태로 둡니다. -- 채널별로 재정의: `channels.discord.commands.native`(불리언 또는 `"auto"`). `false`는 이전에 등록된 명령을 지웁니다. +- `native: "auto"`는 Discord/Telegram의 네이티브 명령을 켜고 Slack은 꺼둡니다. +- `nativeSkills: "auto"`는 Discord/Telegram의 네이티브 Skills 명령을 켜고 Slack은 꺼둡니다. +- 채널별 재정의: `channels.discord.commands.native`(불리언 또는 `"auto"`). `false`는 이전에 등록된 명령을 지웁니다. - `channels..commands.nativeSkills`로 채널별 네이티브 Skills 등록을 재정의합니다. -- `channels.telegram.customCommands`는 추가 Telegram 봇 메뉴 항목을 추가합니다. -- `bash: true`는 호스트 셸에 대해 `! `를 활성화합니다. `tools.elevated.enabled`와 `tools.elevated.allowFrom.`에 포함된 발신자가 필요합니다. -- `config: true`는 `/config`(`openclaw.json` 읽기/쓰기)를 활성화합니다. Gateway `chat.send` 클라이언트의 경우, 영구 `/config set|unset` 쓰기에는 `operator.admin`도 필요합니다. 읽기 전용 `/config show`는 일반 쓰기 범위 operator 클라이언트에도 계속 사용할 수 있습니다. -- `mcp: true`는 `mcp.servers` 아래 OpenClaw 관리 MCP 서버 구성에 대한 `/mcp`를 활성화합니다. -- `plugins: true`는 Plugin 검색, 설치, 활성화/비활성화 제어를 위한 `/plugins`를 활성화합니다. -- `channels..configWrites`는 채널별 구성 변경을 제어합니다(기본값: true). -- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기를 제어합니다(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`). +- `channels.telegram.customCommands`는 추가 Telegram 봇 메뉴 항목을 더합니다. +- `bash: true`는 호스트 셸에 대해 `! `를 활성화합니다. `tools.elevated.enabled`가 필요하며 발신자가 `tools.elevated.allowFrom.`에 있어야 합니다. +- `config: true`는 `/config`를 활성화합니다(`openclaw.json` 읽기/쓰기). Gateway `chat.send` 클라이언트의 경우, 영구 `/config set|unset` 쓰기는 `operator.admin`도 필요합니다. 읽기 전용 `/config show`는 일반 쓰기 범위 operator 클라이언트에도 계속 사용할 수 있습니다. +- `mcp: true`는 `mcp.servers` 아래 OpenClaw 관리 MCP 서버 구성에 대해 `/mcp`를 활성화합니다. +- `plugins: true`는 Plugin 검색, 설치, 활성화/비활성화 제어를 위해 `/plugins`를 활성화합니다. +- `channels..configWrites`는 채널별 구성 변경을 게이트합니다(기본값: true). +- 다중 계정 채널의 경우 `channels..accounts..configWrites`도 해당 계정을 대상으로 하는 쓰기(예: `/allowlist --config --account ` 또는 `/config set channels..accounts....`)를 게이트합니다. - `restart: false`는 `/restart`와 Gateway 재시작 도구 작업을 비활성화합니다. 기본값: `true`. -- `ownerAllowFrom`은 소유자 전용 명령/도구를 위한 명시적 소유자 허용 목록입니다. `allowFrom`과 별개입니다. +- `ownerAllowFrom`은 소유자 전용 명령/도구를 위한 명시적 소유자 허용 목록입니다. `allowFrom`과는 별개입니다. - `ownerDisplay: "hash"`는 시스템 프롬프트에서 소유자 ID를 해시합니다. 해싱을 제어하려면 `ownerDisplaySecret`을 설정하세요. -- `allowFrom`은 제공자별로 적용됩니다. 설정된 경우 이것이 **유일한** 인증 소스입니다(채널 허용 목록/페어링 및 `useAccessGroups`는 무시됨). -- `useAccessGroups: false`는 `allowFrom`이 설정되지 않은 경우 명령이 액세스 그룹 정책을 우회하도록 허용합니다. +- `allowFrom`은 공급자별입니다. 설정하면 이것이 **유일한** 권한 부여 소스가 됩니다(채널 허용 목록/페어링 및 `useAccessGroups`는 무시됨). +- `useAccessGroups: false`는 `allowFrom`이 설정되지 않은 경우 명령이 액세스 그룹 정책을 우회할 수 있게 합니다. - 명령 문서 맵: - 기본 제공 + 번들 카탈로그: [슬래시 명령](/ko/tools/slash-commands) - 채널별 명령 표면: [채널](/ko/channels) diff --git a/docs/ko/gateway/doctor.md b/docs/ko/gateway/doctor.md index 03451780e..32b884bc2 100644 --- a/docs/ko/gateway/doctor.md +++ b/docs/ko/gateway/doctor.md @@ -1,15 +1,15 @@ --- read_when: - doctor 마이그레이션 추가 또는 수정 - - 호환성을 깨는 설정 변경 도입 + - 호환성을 깨는 설정 변경 사항 도입 sidebarTitle: Doctor -summary: 'doctor 명령: 상태 점검, 구성 마이그레이션 및 복구 단계' +summary: 'doctor 명령: 상태 검사, 구성 마이그레이션 및 복구 단계' title: 진단 x-i18n: - generated_at: "2026-04-30T06:30:46Z" + generated_at: "2026-04-30T16:28:48Z" model: gpt-5.5 provider: openai - source_hash: c27b8e85eb0a577e676f0e6e205262775ff37303453e64fc1bc2adaf8b51147c + source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e source_path: gateway/doctor.md workflow: 16 --- @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - 프롬프트 없이 기본값을 수락합니다(해당하는 경우 재시작/서비스/샌드박스 복구 단계 포함). + 프롬프트 없이 기본값을 수락합니다(해당되는 경우 재시작/서비스/샌드박스 복구 단계 포함). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - 공격적인 복구도 적용합니다(사용자 지정 supervisor 구성을 덮어씀). + 적극적인 복구도 적용합니다(사용자 지정 supervisor 구성을 덮어씀). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - 프롬프트 없이 실행하고 안전한 마이그레이션만 적용합니다(구성 정규화 + 디스크 상태 이동). 사람이 확인해야 하는 재시작/서비스/샌드박스 작업은 건너뜁니다. 레거시 상태 마이그레이션은 감지되면 자동으로 실행됩니다. + 프롬프트 없이 실행하고 안전한 마이그레이션만 적용합니다(구성 정규화 + 디스크상의 상태 이동). 사람이 확인해야 하는 재시작/서비스/샌드박스 작업은 건너뜁니다. 레거시 상태 마이그레이션은 감지되면 자동으로 실행됩니다. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - 추가 Gateway 설치(launchd/systemd/schtasks)를 찾기 위해 시스템 서비스를 스캔합니다. + 추가 gateway 설치를 찾기 위해 시스템 서비스를 스캔합니다(launchd/systemd/schtasks). @@ -76,11 +76,11 @@ cat ~/.openclaw/openclaw.json ## 수행 작업(요약) - - - git 설치의 선택적 사전 업데이트(대화형 전용). - - UI 프로토콜 최신 상태 검사(프로토콜 스키마가 더 최신이면 제어 UI를 다시 빌드). + + - git 설치에 대한 선택적 사전 업데이트(대화형만 해당). + - UI 프로토콜 최신성 검사(프로토콜 스키마가 더 최신이면 Control UI를 다시 빌드). - 상태 검사 + 재시작 프롬프트. - - Skills 상태 요약(대상/누락/차단) 및 Plugin 상태. + - Skills 상태 요약(적격/누락/차단) 및 plugin 상태. @@ -89,90 +89,91 @@ cat ~/.openclaw/openclaw.json - 레거시 Chrome 확장 프로그램 구성 및 Chrome MCP 준비 상태에 대한 브라우저 마이그레이션 검사. - OpenCode provider override 경고(`models.providers.opencode` / `models.providers.opencode-go`). - Codex OAuth shadowing 경고(`models.providers.openai-codex`). - - OpenAI Codex OAuth 프로필의 OAuth TLS 전제 조건 검사. - - 레거시 디스크 상태 마이그레이션(세션/agent dir/WhatsApp auth). - - 레거시 Plugin manifest contract key 마이그레이션(`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - 레거시 cron 저장소 마이그레이션(`jobId`, `schedule.cron`, 최상위 delivery/payload 필드, payload `provider`, 단순 `notify: true` webhook fallback jobs). - - 레거시 agent runtime-policy를 `agents.defaults.agentRuntime` 및 `agents.list[].agentRuntime`으로 마이그레이션. - - Plugin이 활성화된 경우 오래된 Plugin 구성 정리. `plugins.enabled=false`이면 오래된 Plugin 참조는 비활성 containment 구성으로 처리되어 보존됩니다. + - OpenAI Codex OAuth 프로필에 대한 OAuth TLS 필수 조건 검사. + - 레거시 디스크상 상태 마이그레이션(sessions/agent dir/WhatsApp auth). + - 레거시 plugin manifest contract 키 마이그레이션(`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - 레거시 cron 저장소 마이그레이션(`jobId`, `schedule.cron`, 최상위 delivery/payload 필드, payload `provider`, 단순 `notify: true` webhook fallback 작업). + - 레거시 agent runtime-policy를 `agents.defaults.agentRuntime` 및 `agents.list[].agentRuntime`로 마이그레이션. + - plugins가 활성화된 경우 오래된 plugin 구성 정리. `plugins.enabled=false`일 때는 오래된 plugin 참조가 비활성 containment 구성으로 취급되어 보존됩니다. - 세션 잠금 파일 검사 및 오래된 잠금 정리. - 영향을 받은 2026.4.24 빌드에서 생성된 중복 prompt-rewrite 브랜치에 대한 세션 transcript 복구. - - 상태 무결성 및 권한 검사(세션, transcript, 상태 디렉터리). - - 로컬에서 실행할 때 구성 파일 권한 검사(chmod 600). + - wedged subagent 재시작-복구 tombstone 감지. startup이 child를 restart-aborted로 계속 처리하지 않도록 오래된 aborted recovery 플래그를 지우는 `--fix` 지원 포함. + - 상태 무결성 및 권한 검사(sessions, transcripts, state dir). + - 로컬 실행 시 구성 파일 권한 검사(chmod 600). - 모델 인증 상태: OAuth 만료를 검사하고, 만료 예정 토큰을 새로 고칠 수 있으며, auth-profile cooldown/disabled 상태를 보고합니다. - 추가 workspace dir 감지(`~/openclaw`). - + - 샌드박싱이 활성화된 경우 샌드박스 이미지 복구. - - 레거시 서비스 마이그레이션 및 추가 Gateway 감지. - - Matrix 채널 레거시 상태 마이그레이션(`--fix` / `--repair` 모드). + - 레거시 서비스 마이그레이션 및 추가 gateway 감지. + - Matrix 채널 레거시 상태 마이그레이션(`--fix` / `--repair` 모드에서). - Gateway 런타임 검사(서비스가 설치되었지만 실행 중이 아님, 캐시된 launchd label). - - 채널 상태 경고(실행 중인 Gateway에서 탐색). - - 선택적 복구가 포함된 supervisor 구성 감사(launchd/systemd/schtasks). - - 설치 또는 업데이트 중 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 값을 캡처한 Gateway 서비스의 embedded proxy environment cleanup. - - Gateway 런타임 모범 사례 검사(Node vs Bun, version-manager paths). + - 채널 상태 경고(실행 중인 gateway에서 probing). + - 선택적 복구가 있는 supervisor 구성 감사(launchd/systemd/schtasks). + - 설치 또는 업데이트 중 shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` 값을 캡처한 gateway 서비스의 embedded proxy 환경 정리. + - Gateway 런타임 모범 사례 검사(Node vs Bun, version-manager 경로). - Gateway 포트 충돌 진단(기본값 `18789`). - - - 열린 DM 정책에 대한 보안 경고. - - local token mode에 대한 Gateway 인증 검사(토큰 소스가 없으면 토큰 생성을 제안하며, token SecretRef 구성을 덮어쓰지 않음). - - 디바이스 페어링 문제 감지(대기 중인 최초 pair 요청, 대기 중인 role/scope 업그레이드, 오래된 로컬 device-token cache drift, paired-record auth drift). + + - 공개 DM 정책에 대한 보안 경고. + - local token 모드에 대한 Gateway 인증 검사(토큰 소스가 없으면 토큰 생성을 제안하며, token SecretRef 구성을 덮어쓰지 않음). + - 기기 페어링 문제 감지(대기 중인 최초 페어 요청, 대기 중인 역할/범위 업그레이드, 오래된 로컬 device-token cache drift, paired-record auth drift). - - - Linux의 systemd linger 검사. - - 작업 영역 bootstrap 파일 크기 검사(context 파일의 truncation/near-limit 경고). - - shell completion 상태 검사 및 자동 설치/업그레이드. - - Memory 검색 embedding provider 준비 상태 검사(로컬 모델, remote API key 또는 QMD binary). - - 소스 설치 검사(pnpm workspace mismatch, 누락된 UI assets, 누락된 tsx binary). + + - Linux에서 systemd linger 검사. + - Workspace bootstrap 파일 크기 검사(context 파일의 잘림/한도 근접 경고). + - Shell completion 상태 검사 및 자동 설치/업그레이드. + - Memory search embedding provider 준비 상태 검사(로컬 모델, 원격 API 키 또는 QMD 바이너리). + - 소스 설치 검사(pnpm workspace mismatch, 누락된 UI assets, 누락된 tsx 바이너리). - 업데이트된 구성 + wizard metadata를 씁니다. -## Dreams UI backfill 및 reset +## Dreams UI 백필 및 재설정 -제어 UI Dreams scene에는 grounded dreaming 워크플로용 **Backfill**, **Reset**, **Clear Grounded** 작업이 포함됩니다. 이러한 작업은 gateway doctor-style RPC 메서드를 사용하지만, `openclaw doctor` CLI 복구/마이그레이션의 일부는 **아닙니다**. +Control UI Dreams 장면에는 근거 기반 dreaming 워크플로를 위한 **백필**, **재설정**, **근거 기반 항목 지우기** 작업이 포함됩니다. 이러한 작업은 gateway doctor 스타일 RPC 메서드를 사용하지만, `openclaw doctor` CLI 복구/마이그레이션의 일부는 **아닙니다**. 수행하는 작업: -- **Backfill**은 활성 작업 영역의 과거 `memory/YYYY-MM-DD.md` 파일을 스캔하고, grounded REM diary pass를 실행하며, 되돌릴 수 있는 backfill 항목을 `DREAMS.md`에 씁니다. -- **Reset**은 표시된 backfill diary 항목만 `DREAMS.md`에서 제거합니다. -- **Clear Grounded**는 과거 replay에서 왔고 아직 live recall 또는 daily support가 누적되지 않은 staged grounded-only short-term 항목만 제거합니다. +- **백필**은 활성 워크스페이스의 과거 `memory/YYYY-MM-DD.md` 파일을 스캔하고, 근거 기반 REM diary pass를 실행한 뒤, 되돌릴 수 있는 백필 항목을 `DREAMS.md`에 씁니다. +- **재설정**은 `DREAMS.md`에서 표시된 백필 diary 항목만 제거합니다. +- **근거 기반 항목 지우기**는 과거 replay에서 왔고 아직 live recall 또는 daily support가 누적되지 않은 staged grounded-only short-term 항목만 제거합니다. -자체적으로 수행하지 **않는** 작업: +그 자체로는 수행하지 **않는** 작업: - `MEMORY.md`를 편집하지 않습니다 - 전체 doctor 마이그레이션을 실행하지 않습니다 -- staged CLI path를 먼저 명시적으로 실행하지 않는 한 grounded candidates를 live short-term promotion store에 자동으로 stage하지 않습니다 +- staged CLI 경로를 먼저 명시적으로 실행하지 않는 한, 근거 기반 후보를 live short-term promotion store에 자동으로 stage하지 않습니다 -grounded historical replay가 일반 deep promotion lane에 영향을 주게 하려면 대신 CLI flow를 사용하세요. +근거 기반 과거 replay가 일반 deep promotion lane에 영향을 주도록 하려면 대신 CLI 흐름을 사용하세요. ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -이렇게 하면 `DREAMS.md`를 검토 표면으로 유지하면서 grounded durable candidates를 short-term dreaming store에 stage합니다. +이는 `DREAMS.md`를 검토 표면으로 유지하면서 근거 기반 durable 후보를 short-term dreaming store에 stage합니다. -## 세부 동작 및 근거 +## 상세 동작 및 근거 이것이 git checkout이고 doctor가 대화형으로 실행 중이면, doctor를 실행하기 전에 업데이트(fetch/rebase/build)를 제안합니다. - 구성에 레거시 값 형태가 포함된 경우(예: 채널별 override 없이 `messages.ackReaction`), doctor는 이를 현재 스키마로 정규화합니다. + 구성에 레거시 값 형태가 포함되어 있으면(예: 채널별 override 없이 `messages.ackReaction`만 있는 경우), doctor가 이를 현재 스키마로 정규화합니다. 여기에는 레거시 Talk 플랫 필드가 포함됩니다. 현재 공개 Talk 구성은 `talk.provider` + `talk.providers.`입니다. Doctor는 이전 `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` 형태를 provider map으로 다시 씁니다. - 구성에 사용 중단된 키가 포함되어 있으면, 다른 명령은 실행을 거부하고 `openclaw doctor`를 실행하라고 요청합니다. + 구성에 더 이상 사용되지 않는 키가 포함되어 있으면, 다른 명령은 실행을 거부하고 `openclaw doctor`를 실행하라고 요청합니다. Doctor는 다음을 수행합니다. @@ -180,7 +181,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - 적용한 마이그레이션을 표시합니다. - 업데이트된 스키마로 `~/.openclaw/openclaw.json`을 다시 씁니다. - Gateway도 레거시 구성 형식을 감지하면 시작 시 doctor 마이그레이션을 자동 실행하므로, 오래된 구성은 수동 개입 없이 복구됩니다. Cron 작업 저장소 마이그레이션은 `openclaw doctor --fix`가 처리합니다. + Gateway도 레거시 구성 형식을 감지하면 startup 시 doctor 마이그레이션을 자동 실행하므로, 오래된 구성은 수동 개입 없이 복구됩니다. Cron 작업 저장소 마이그레이션은 `openclaw doctor --fix`가 처리합니다. 현재 마이그레이션: @@ -205,287 +206,287 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - 이름이 지정된 `accounts`가 있지만 단일 계정 최상위 채널 값이 남아 있는 채널의 경우, 해당 account-scoped 값을 그 채널에 대해 선택된 promoted account로 이동합니다(대부분의 채널은 `accounts.default`; Matrix는 기존 matching named/default target을 보존할 수 있음) + - 이름 있는 `accounts`가 있지만 single-account 최상위 채널 값이 남아 있는 채널의 경우, 해당 account-scoped 값을 그 채널에 대해 선택된 promoted account로 이동합니다(대부분의 채널은 `accounts.default`; Matrix는 기존 일치 named/default 대상을 보존할 수 있음) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - `agents.defaults.llm` 제거. 느린 provider/model timeout에는 `models.providers..timeoutSeconds` 사용 + - `agents.defaults.llm` 제거. 느린 provider/model timeout에는 `models.providers..timeoutSeconds`를 사용하세요 - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - `browser.relayBindHost` 제거(레거시 extension relay setting) - - 레거시 `models.providers.*.api: "openai"` → `"openai-completions"` (Gateway 시작 시 `api`가 미래 또는 알 수 없는 enum 값으로 설정된 provider도 실패로 종료하지 않고 건너뜀) + - 레거시 `models.providers.*.api: "openai"` → `"openai-completions"` (gateway startup은 `api`가 future 또는 unknown enum value로 설정된 provider도 실패로 닫는 대신 건너뜁니다) - Doctor 경고에는 multi-account 채널에 대한 account-default guidance도 포함됩니다. + Doctor 경고에는 multi-account 채널에 대한 account-default 안내도 포함됩니다: - - 두 개 이상의 `channels..accounts` 항목이 `channels..defaultAccount` 또는 `accounts.default` 없이 구성된 경우, doctor는 fallback routing이 예상치 못한 계정을 선택할 수 있다고 경고합니다. - - `channels..defaultAccount`가 알 수 없는 계정 ID로 설정된 경우, doctor는 경고하고 구성된 계정 ID를 나열합니다. + - 두 개 이상의 `channels..accounts` 항목이 `channels..defaultAccount` 또는 `accounts.default` 없이 구성되어 있으면, doctor는 fallback 라우팅이 예상치 못한 계정을 선택할 수 있다고 경고합니다. + - `channels..defaultAccount`가 알 수 없는 계정 ID로 설정되어 있으면, doctor는 경고하고 구성된 계정 ID를 나열합니다. - - `models.providers.opencode`, `opencode-zen` 또는 `opencode-go`를 수동으로 추가했다면, `@mariozechner/pi-ai`의 기본 제공 OpenCode 카탈로그를 오버라이드합니다. 이로 인해 모델이 잘못된 API로 강제 라우팅되거나 비용이 0으로 설정될 수 있습니다. Doctor는 오버라이드를 제거하고 모델별 API 라우팅 및 비용을 복원할 수 있도록 경고합니다. + + `models.providers.opencode`, `opencode-zen` 또는 `opencode-go`를 수동으로 추가했다면, 이는 `@mariozechner/pi-ai`의 기본 제공 OpenCode 카탈로그를 재정의합니다. 그 결과 모델이 잘못된 API를 사용하거나 비용이 0으로 설정될 수 있습니다. doctor는 이 재정의를 제거하고 모델별 API 라우팅과 비용을 복원할 수 있도록 경고합니다. - 브라우저 구성이 아직 제거된 Chrome 확장 프로그램 경로를 가리키는 경우, doctor는 이를 현재의 호스트 로컬 Chrome MCP 연결 모델로 정규화합니다. + 브라우저 구성이 여전히 제거된 Chrome 확장 경로를 가리키는 경우, doctor는 이를 현재 호스트 로컬 Chrome MCP 연결 모델로 정규화합니다. - `browser.profiles.*.driver: "extension"`은 `"existing-session"`이 됩니다. - `browser.relayBindHost`가 제거됩니다. - 또한 `defaultProfile: "user"` 또는 구성된 `existing-session` 프로필을 사용할 때 doctor는 호스트 로컬 Chrome MCP 경로를 감사합니다. + 또한 doctor는 `defaultProfile: "user"` 또는 구성된 `existing-session` 프로필을 사용할 때 호스트 로컬 Chrome MCP 경로를 감사합니다. - - 기본 자동 연결 프로필의 경우 Google Chrome이 같은 호스트에 설치되어 있는지 확인합니다. + - 기본 자동 연결 프로필의 경우 동일한 호스트에 Google Chrome이 설치되어 있는지 확인합니다. - 감지된 Chrome 버전을 확인하고 Chrome 144 미만이면 경고합니다. - - 브라우저 검사 페이지에서 원격 디버깅을 활성화하라고 알려줍니다. 예: `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` 또는 `edge://inspect/#remote-debugging` + - 브라우저 inspect 페이지에서 원격 디버깅을 활성화하라고 알립니다. 예: `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, 또는 `edge://inspect/#remote-debugging` - Doctor는 Chrome 쪽 설정을 대신 활성화할 수 없습니다. 호스트 로컬 Chrome MCP에는 여전히 다음이 필요합니다. + doctor는 Chrome 측 설정을 대신 활성화할 수 없습니다. 호스트 로컬 Chrome MCP에는 여전히 다음이 필요합니다. - - gateway/node 호스트의 Chromium 기반 브라우저 144+ - - 로컬에서 실행 중인 브라우저 - - 해당 브라우저에서 활성화된 원격 디버깅 - - 브라우저에서 첫 연결 동의 프롬프트 승인 + - Gateway/Node 호스트의 Chromium 기반 브라우저 144+ + - 브라우저가 로컬에서 실행 중일 것 + - 해당 브라우저에서 원격 디버깅이 활성화되어 있을 것 + - 브라우저에서 첫 연결 동의 프롬프트를 승인할 것 - 여기서 준비 상태는 로컬 연결 전제 조건에만 관련됩니다. Existing-session은 현재 Chrome MCP 경로 제한을 유지합니다. `responsebody`, PDF 내보내기, 다운로드 가로채기, 배치 작업 같은 고급 경로에는 여전히 관리형 브라우저 또는 원시 CDP 프로필이 필요합니다. + 여기서의 준비 상태는 로컬 연결 전제 조건에만 관한 것입니다. Existing-session은 현재 Chrome MCP 경로 제한을 유지합니다. `responsebody`, PDF 내보내기, 다운로드 가로채기, 배치 작업 같은 고급 경로에는 여전히 관리형 브라우저 또는 raw CDP 프로필이 필요합니다. - 이 검사는 Docker, sandbox, remote-browser 또는 다른 헤드리스 흐름에는 적용되지 않습니다. 해당 흐름은 계속 원시 CDP를 사용합니다. + 이 검사는 Docker, sandbox, remote-browser 또는 다른 headless 흐름에는 적용되지 않습니다. 이들은 계속 raw CDP를 사용합니다. - OpenAI Codex OAuth 프로필이 구성된 경우, doctor는 OpenAI 인증 엔드포인트를 검사하여 로컬 Node/OpenSSL TLS 스택이 인증서 체인을 검증할 수 있는지 확인합니다. 검사가 인증서 오류로 실패하면(예: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, 만료된 인증서 또는 자체 서명 인증서), doctor는 플랫폼별 수정 안내를 출력합니다. Homebrew Node를 사용하는 macOS에서는 보통 `brew postinstall ca-certificates`가 해결 방법입니다. `--deep`을 사용하면 Gateway가 정상이어도 검사가 실행됩니다. + OpenAI Codex OAuth 프로필이 구성되어 있으면, doctor는 OpenAI 인증 엔드포인트를 검사해 로컬 Node/OpenSSL TLS 스택이 인증서 체인을 검증할 수 있는지 확인합니다. 검사가 인증서 오류로 실패하면(예: `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, 만료된 인증서 또는 자체 서명 인증서), doctor는 플랫폼별 수정 안내를 출력합니다. Homebrew Node를 사용하는 macOS에서는 일반적으로 `brew postinstall ca-certificates`로 수정합니다. `--deep`을 사용하면 Gateway가 정상이어도 검사가 실행됩니다. - - 이전에 `models.providers.openai-codex` 아래에 레거시 OpenAI 전송 설정을 추가했다면, 최신 릴리스가 자동으로 사용하는 기본 제공 Codex OAuth 제공자 경로를 가릴 수 있습니다. Doctor는 Codex OAuth와 함께 이런 오래된 전송 설정을 발견하면 경고하여, 오래된 전송 오버라이드를 제거하거나 다시 작성하고 기본 제공 라우팅/대체 동작을 복원할 수 있게 합니다. 사용자 지정 프록시와 헤더 전용 오버라이드는 계속 지원되며 이 경고를 트리거하지 않습니다. + + 이전에 `models.providers.openai-codex` 아래에 기존 OpenAI 전송 설정을 추가했다면, 최신 릴리스가 자동으로 사용하는 기본 제공 Codex OAuth 제공자 경로를 가릴 수 있습니다. doctor는 Codex OAuth와 함께 이러한 오래된 전송 설정을 발견하면 경고하여, 오래된 전송 재정의를 제거하거나 다시 작성하고 기본 제공 라우팅/fallback 동작을 되돌릴 수 있게 합니다. 사용자 지정 프록시와 헤더 전용 재정의는 계속 지원되며 이 경고를 발생시키지 않습니다. - - 번들 Codex plugin이 활성화되어 있으면, doctor는 `openai-codex/*` 기본 모델 참조가 여전히 기본 PI 러너를 통해 해석되는지도 확인합니다. 이 조합은 PI를 통해 Codex OAuth/구독 인증을 사용하려는 경우에는 유효하지만, 네이티브 Codex 앱 서버 하네스와 혼동하기 쉽습니다. Doctor는 경고하고 명시적인 앱 서버 형태인 `openai/*`와 `agentRuntime.id: "codex"` 또는 `OPENCLAW_AGENT_RUNTIME=codex`를 안내합니다. + + 번들 Codex Plugin이 활성화되어 있으면, doctor는 `openai-codex/*` 기본 모델 참조가 여전히 기본 PI runner를 통해 해석되는지도 확인합니다. 이 조합은 PI를 통한 Codex OAuth/구독 인증을 원할 때 유효하지만, 네이티브 Codex app-server 하네스와 혼동하기 쉽습니다. doctor는 경고하고 명시적인 app-server 형태를 안내합니다: `openai/*`와 `agentRuntime.id: "codex"` 또는 `OPENCLAW_AGENT_RUNTIME=codex`. 두 경로 모두 유효하므로 doctor는 이를 자동으로 복구하지 않습니다. - - `openai-codex/*` + PI는 "일반 OpenClaw 러너를 통해 Codex OAuth/구독 인증을 사용"한다는 뜻입니다. - - `openai/*` + `runtime: "codex"`는 "내장 턴을 네이티브 Codex 앱 서버를 통해 실행"한다는 뜻입니다. + - `openai-codex/*` + PI는 "일반 OpenClaw runner를 통해 Codex OAuth/구독 인증을 사용"한다는 뜻입니다. + - `openai/*` + `runtime: "codex"`는 "내장된 턴을 네이티브 Codex app-server를 통해 실행"한다는 뜻입니다. - `/codex ...`는 "채팅에서 네이티브 Codex 대화를 제어하거나 바인딩"한다는 뜻입니다. - `/acp ...` 또는 `runtime: "acp"`는 "외부 ACP/acpx 어댑터를 사용"한다는 뜻입니다. - 경고가 나타나면 의도한 경로를 선택하고 구성을 수동으로 편집하세요. PI Codex OAuth가 의도된 것이라면 경고를 그대로 두세요. + 경고가 표시되면 의도한 경로를 선택하고 구성을 수동으로 편집하세요. PI Codex OAuth를 의도한 경우에는 경고를 그대로 두세요. - - Doctor는 이전 온디스크 레이아웃을 현재 구조로 마이그레이션할 수 있습니다. + + doctor는 오래된 디스크 레이아웃을 현재 구조로 마이그레이션할 수 있습니다. - - 세션 저장소 + 트랜스크립트: + - 세션 저장소 + 대화 기록: - `~/.openclaw/sessions/`에서 `~/.openclaw/agents//sessions/`로 - 에이전트 디렉터리: - `~/.openclaw/agent/`에서 `~/.openclaw/agents//agent/`로 - WhatsApp 인증 상태(Baileys): - - 레거시 `~/.openclaw/credentials/*.json`에서(`oauth.json` 제외) + - 기존 `~/.openclaw/credentials/*.json`에서(`oauth.json` 제외) - `~/.openclaw/credentials/whatsapp//...`로(기본 계정 ID: `default`) - 이러한 마이그레이션은 최선 노력 방식이며 멱등적입니다. doctor는 백업으로 남겨둔 레거시 폴더가 있으면 경고를 내보냅니다. Gateway/CLI도 시작 시 레거시 세션과 에이전트 디렉터리를 자동으로 마이그레이션하므로, 수동 doctor 실행 없이도 기록/인증/모델이 에이전트별 경로에 배치됩니다. WhatsApp 인증은 의도적으로 `openclaw doctor`를 통해서만 마이그레이션됩니다. Talk 제공자/provider-map 정규화는 이제 구조적 동등성으로 비교하므로, 키 순서만 다른 차이는 더 이상 반복적인 무효 `doctor --fix` 변경을 트리거하지 않습니다. + 이러한 마이그레이션은 최선 노력 방식이며 멱등적입니다. doctor는 기존 폴더를 백업으로 남길 때 경고를 출력합니다. Gateway/CLI도 시작 시 기존 세션과 에이전트 디렉터리를 자동 마이그레이션하므로, 수동 doctor 실행 없이도 기록/인증/모델이 에이전트별 경로에 배치됩니다. WhatsApp 인증은 의도적으로 `openclaw doctor`를 통해서만 마이그레이션됩니다. 이제 Talk 제공자/provider-map 정규화는 구조적 동등성으로 비교하므로, 키 순서만 다른 차이는 더 이상 반복적인 무동작 `doctor --fix` 변경을 유발하지 않습니다. - - Doctor는 설치된 모든 plugin 매니페스트에서 더 이상 사용되지 않는 최상위 기능 키(`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`)를 스캔합니다. 발견되면 이를 `contracts` 객체로 옮기고 매니페스트 파일을 제자리에서 다시 작성하도록 제안합니다. 이 마이그레이션은 멱등적입니다. `contracts` 키에 이미 같은 값이 있으면 데이터를 중복하지 않고 레거시 키를 제거합니다. + + doctor는 설치된 모든 Plugin 매니페스트에서 더 이상 사용되지 않는 최상위 capability 키(`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`)를 스캔합니다. 발견되면 이를 `contracts` 객체로 옮기고 매니페스트 파일을 제자리에서 다시 작성하도록 제안합니다. 이 마이그레이션은 멱등적입니다. `contracts` 키에 이미 동일한 값이 있으면 데이터를 중복하지 않고 기존 키만 제거합니다. - - Doctor는 cron 작업 저장소(기본값은 `~/.openclaw/cron/jobs.json`, 오버라이드된 경우 `cron.store`)에서 스케줄러가 호환성을 위해 여전히 허용하는 이전 작업 형태도 확인합니다. + + doctor는 Cron 작업 저장소도 확인합니다(기본값은 `~/.openclaw/cron/jobs.json`, 재정의된 경우 `cron.store`). 이는 스케줄러가 호환성을 위해 여전히 허용하는 오래된 작업 형태를 찾기 위한 것입니다. - 현재 cron 정리에는 다음이 포함됩니다. + 현재 Cron 정리에는 다음이 포함됩니다. - `jobId` → `id` - `schedule.cron` → `schedule.expr` - 최상위 payload 필드(`message`, `model`, `thinking`, ...) → `payload` - 최상위 delivery 필드(`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - payload `provider` delivery 별칭 → 명시적 `delivery.channel` - - 단순 레거시 `notify: true` webhook 대체 작업 → `delivery.to=cron.webhook`이 포함된 명시적 `delivery.mode="webhook"` + - payload `provider` delivery 별칭 → 명시적인 `delivery.channel` + - 단순 기존 `notify: true` webhook fallback 작업 → `delivery.to=cron.webhook`이 있는 명시적인 `delivery.mode="webhook"` - Doctor는 동작 변경 없이 처리할 수 있을 때만 `notify: true` 작업을 자동 마이그레이션합니다. 작업이 레거시 notify 대체와 기존 비-webhook delivery 모드를 함께 사용하는 경우, doctor는 경고하고 해당 작업을 수동 검토용으로 남겨둡니다. + doctor는 동작을 변경하지 않고 처리할 수 있을 때만 `notify: true` 작업을 자동 마이그레이션합니다. 작업이 기존 notify fallback과 기존 non-webhook delivery 모드를 함께 사용하는 경우, doctor는 경고하고 해당 작업을 수동 검토용으로 남겨 둡니다. - Doctor는 모든 에이전트 세션 디렉터리에서 오래된 쓰기 잠금 파일, 즉 세션이 비정상 종료될 때 남은 파일을 스캔합니다. 발견된 각 잠금 파일에 대해 경로, PID, PID가 아직 살아 있는지 여부, 잠금 나이, 오래된 것으로 간주되는지 여부(죽은 PID 또는 30분 초과)를 보고합니다. `--fix` / `--repair` 모드에서는 오래된 잠금 파일을 자동으로 제거합니다. 그렇지 않으면 참고 메시지를 출력하고 `--fix`로 다시 실행하라고 안내합니다. + doctor는 모든 에이전트 세션 디렉터리에서 오래된 쓰기 잠금 파일, 즉 세션이 비정상 종료될 때 남은 파일을 스캔합니다. 발견된 각 잠금 파일에 대해 경로, PID, 해당 PID가 아직 살아 있는지 여부, 잠금 경과 시간, 오래된 것으로 간주되는지 여부(죽은 PID 또는 30분 초과)를 보고합니다. `--fix` / `--repair` 모드에서는 오래된 잠금 파일을 자동으로 제거합니다. 그렇지 않으면 메모를 출력하고 `--fix`로 다시 실행하라고 안내합니다. - - Doctor는 에이전트 세션 JSONL 파일에서 2026.4.24 프롬프트 트랜스크립트 재작성 버그로 생성된 중복 브랜치 형태를 스캔합니다. 이 형태는 OpenClaw 내부 런타임 컨텍스트가 포함된 버려진 사용자 턴과, 같은 표시 사용자 프롬프트가 포함된 활성 형제 턴으로 구성됩니다. `--fix` / `--repair` 모드에서는 doctor가 영향을 받은 각 파일을 원본 옆에 백업하고 트랜스크립트를 활성 브랜치로 다시 작성하여 Gateway 기록과 메모리 리더가 더 이상 중복 턴을 보지 않게 합니다. + + doctor는 에이전트 세션 JSONL 파일에서 2026.4.24 프롬프트 대화 기록 재작성 버그로 생성된 중복 브랜치 형태를 스캔합니다. 이는 OpenClaw 내부 런타임 컨텍스트가 있는 버려진 사용자 턴과, 동일한 표시 사용자 프롬프트를 포함하는 활성 sibling이 함께 있는 형태입니다. `--fix` / `--repair` 모드에서 doctor는 영향을 받은 각 파일을 원본 옆에 백업하고, Gateway 기록과 memory reader가 더 이상 중복 턴을 보지 않도록 대화 기록을 활성 브랜치로 다시 작성합니다. - - 상태 디렉터리는 운영상의 뇌간입니다. 이 디렉터리가 사라지면 세션, 자격 증명, 로그, 구성을 잃게 됩니다(다른 곳에 백업이 없는 한). + + 상태 디렉터리는 운영상의 핵심입니다. 이 디렉터리가 사라지면 세션, 자격 증명, 로그, 구성을 잃게 됩니다(다른 곳에 백업이 없는 경우). - Doctor는 다음을 확인합니다. + doctor는 다음을 확인합니다. - - **상태 디렉터리 누락**: 치명적인 상태 손실을 경고하고, 디렉터리를 다시 만들지 묻고, 누락된 데이터는 복구할 수 없음을 알려줍니다. - - **상태 디렉터리 권한**: 쓰기 가능성을 확인하고, 권한 복구를 제안합니다(소유자/그룹 불일치가 감지되면 `chown` 힌트를 내보냄). - - **macOS 클라우드 동기화 상태 디렉터리**: 상태가 iCloud Drive(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) 또는 `~/Library/CloudStorage/...` 아래로 해석될 때 경고합니다. 동기화 기반 경로는 더 느린 I/O와 잠금/동기화 경쟁을 일으킬 수 있기 때문입니다. - - **Linux SD 또는 eMMC 상태 디렉터리**: 상태가 `mmcblk*` 마운트 소스로 해석될 때 경고합니다. SD 또는 eMMC 기반 랜덤 I/O는 세션 및 자격 증명 쓰기에서 더 느리고 더 빨리 마모될 수 있기 때문입니다. - - **세션 디렉터리 누락**: 기록을 유지하고 `ENOENT` 크래시를 피하려면 `sessions/`와 세션 저장소 디렉터리가 필요합니다. - - **트랜스크립트 불일치**: 최근 세션 항목에 트랜스크립트 파일이 누락되어 있으면 경고합니다. - - **메인 세션 "1줄 JSONL"**: 메인 트랜스크립트가 한 줄뿐일 때 표시합니다(기록이 누적되지 않음). - - **여러 상태 디렉터리**: 여러 홈 디렉터리에 `~/.openclaw` 폴더가 있거나 `OPENCLAW_STATE_DIR`가 다른 곳을 가리키면 경고합니다(설치 간에 기록이 분리될 수 있음). - - **원격 모드 알림**: `gateway.mode=remote`이면 doctor는 원격 호스트에서 실행하라고 알려줍니다(상태가 그곳에 있음). - - **구성 파일 권한**: `~/.openclaw/openclaw.json`이 그룹/전체 사용자에게 읽기 가능하면 경고하고 `600`으로 강화할 것을 제안합니다. + - **상태 디렉터리 없음**: 치명적인 상태 손실을 경고하고, 디렉터리 재생성을 묻고, 누락된 데이터는 복구할 수 없음을 알립니다. + - **상태 디렉터리 권한**: 쓰기 가능 여부를 확인합니다. 권한 복구를 제안하고, 소유자/그룹 불일치가 감지되면 `chown` 힌트를 출력합니다. + - **macOS 클라우드 동기화 상태 디렉터리**: 상태가 iCloud Drive(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) 또는 `~/Library/CloudStorage/...` 아래로 해석되면 경고합니다. 동기화 기반 경로는 I/O가 느려지고 잠금/동기화 경합을 일으킬 수 있기 때문입니다. + - **Linux SD 또는 eMMC 상태 디렉터리**: 상태가 `mmcblk*` 마운트 소스로 해석되면 경고합니다. SD 또는 eMMC 기반 random I/O는 세션 및 자격 증명 쓰기에서 더 느리고 더 빨리 마모될 수 있기 때문입니다. + - **세션 디렉터리 없음**: 기록을 지속하고 `ENOENT` 충돌을 피하려면 `sessions/`와 세션 저장소 디렉터리가 필요합니다. + - **대화 기록 불일치**: 최근 세션 항목에 대화 기록 파일이 없으면 경고합니다. + - **기본 세션 "1-line JSONL"**: 기본 대화 기록에 한 줄만 있을 때 표시합니다(기록이 누적되지 않음). + - **여러 상태 디렉터리**: 여러 `~/.openclaw` 폴더가 홈 디렉터리 전반에 존재하거나 `OPENCLAW_STATE_DIR`가 다른 곳을 가리키면 경고합니다(설치 간 기록이 나뉠 수 있음). + - **원격 모드 알림**: `gateway.mode=remote`이면 doctor는 원격 호스트에서 실행하라고 알립니다(상태가 그곳에 있음). + - **구성 파일 권한**: `~/.openclaw/openclaw.json`이 group/world readable이면 경고하고 `600`으로 강화하도록 제안합니다. - Doctor는 인증 저장소의 OAuth 프로필을 검사하고, 토큰이 곧 만료되거나 만료되었으면 경고하며, 안전할 때 갱신할 수 있습니다. Anthropic OAuth/토큰 프로필이 오래된 경우 Anthropic API 키 또는 Anthropic 설정 토큰 경로를 제안합니다. 갱신 프롬프트는 대화형(TTY) 실행 시에만 나타납니다. `--non-interactive`는 갱신 시도를 건너뜁니다. + doctor는 인증 저장소의 OAuth 프로필을 검사하고, 토큰이 곧 만료되거나 만료된 경우 경고하며, 안전할 때 이를 갱신할 수 있습니다. Anthropic OAuth/토큰 프로필이 오래된 경우, Anthropic API 키 또는 Anthropic setup-token 경로를 제안합니다. 갱신 프롬프트는 대화형(TTY) 실행 시에만 표시됩니다. `--non-interactive`는 갱신 시도를 건너뜁니다. - OAuth 갱신이 영구적으로 실패하면(예: `refresh_token_reused`, `invalid_grant` 또는 제공자가 다시 로그인하라고 알리는 경우), doctor는 재인증이 필요하다고 보고하고 실행할 정확한 `openclaw models auth login --provider ...` 명령을 출력합니다. + OAuth 갱신이 영구적으로 실패하면(예: `refresh_token_reused`, `invalid_grant` 또는 제공자가 다시 로그인하라고 지시하는 경우), doctor는 재인증이 필요하다고 보고하고 실행할 정확한 `openclaw models auth login --provider ...` 명령을 출력합니다. - Doctor는 다음으로 인해 일시적으로 사용할 수 없는 인증 프로필도 보고합니다. + doctor는 다음으로 인해 일시적으로 사용할 수 없는 인증 프로필도 보고합니다. - - 짧은 쿨다운(속도 제한/시간 초과/인증 실패) - - 더 긴 비활성화(청구/크레딧 실패) + - 짧은 cooldown(속도 제한/timeout/인증 실패) + - 더 긴 비활성화(결제/크레딧 실패) - `hooks.gmail.model`이 설정되어 있으면, doctor는 카탈로그와 허용 목록을 기준으로 모델 참조를 검증하고, 해석되지 않거나 허용되지 않을 때 경고합니다. + `hooks.gmail.model`이 설정되어 있으면 doctor가 카탈로그와 허용 목록을 기준으로 모델 참조를 검증하고, 해석되지 않거나 허용되지 않을 때 경고합니다. - - sandboxing이 활성화된 경우, doctor는 Docker 이미지를 확인하고 현재 이미지가 없으면 빌드하거나 레거시 이름으로 전환할 것을 제안합니다. + + 샌드박싱이 활성화되어 있으면 doctor가 Docker 이미지를 확인하고 현재 이미지가 없을 때 레거시 이름으로 빌드하거나 전환하도록 제안합니다. - - Doctor는 현재 구성에서 활성 상태이거나 번들 매니페스트 기본값으로 활성화된 번들 plugin에 대해서만 런타임 종속성을 확인합니다. 예를 들면 `plugins.entries.discord.enabled: true`, 레거시 `channels.discord.enabled: true`, 구성된 `models.providers.*` / 에이전트 모델 참조, 또는 제공자 소유권 없이 기본 활성화된 번들 plugin입니다. 누락된 것이 있으면 doctor는 패키지를 보고하고 `openclaw doctor --fix` / `openclaw doctor --repair` 모드에서 설치합니다. 외부 plugin은 계속 `openclaw plugins install` / `openclaw plugins update`를 사용합니다. doctor는 임의 plugin 경로의 종속성을 설치하지 않습니다. + + Doctor는 현재 구성에서 활성화되었거나 번들 매니페스트 기본값으로 활성화된 번들 Plugin에 대해서만 런타임 의존성을 확인합니다. 예를 들어 `plugins.entries.discord.enabled: true`, 레거시 `channels.discord.enabled: true`, 구성된 `models.providers.*` / 에이전트 모델 참조, 또는 공급자 소유권이 없는 기본 활성화 번들 Plugin이 있습니다. 누락된 항목이 있으면 doctor는 패키지를 보고하고 `openclaw doctor --fix` / `openclaw doctor --repair` 모드에서 설치합니다. 외부 Plugin은 계속 `openclaw plugins install` / `openclaw plugins update`를 사용합니다. doctor는 임의의 Plugin 경로에 대한 의존성을 설치하지 않습니다. - doctor 복구 중에는 번들 런타임 종속성 npm 설치가 TTY 세션에서는 스피너 진행률을, 파이프/헤드리스 출력에서는 주기적인 줄 단위 진행률을 보고합니다. Gateway와 로컬 CLI도 번들 Plugin을 가져오기 전에 필요에 따라 활성 번들 Plugin 런타임 종속성을 복구할 수 있습니다. 이러한 설치는 Plugin 런타임 설치 루트로 범위가 제한되고, 스크립트가 비활성화된 상태로 실행되며, 패키지 잠금을 쓰지 않고, 설치 루트 잠금으로 보호되어 동시 CLI 또는 Gateway 시작이 같은 `node_modules` 트리를 동시에 변경하지 않도록 합니다. + doctor 복구 중 번들 런타임 의존성 npm 설치는 TTY 세션에서는 스피너 진행률을, 파이프/헤드리스 출력에서는 주기적인 줄 단위 진행률을 보고합니다. Gateway와 로컬 CLI도 번들 Plugin을 가져오기 전에 필요에 따라 활성 번들 Plugin 런타임 의존성을 복구할 수 있습니다. 이러한 설치는 Plugin 런타임 설치 루트로 범위가 제한되고, 스크립트가 비활성화된 상태로 실행되며, 패키지 잠금을 쓰지 않고, 설치 루트 잠금으로 보호되어 동시 CLI 또는 Gateway 시작이 같은 `node_modules` 트리를 동시에 변경하지 않도록 합니다. - doctor는 레거시 Gateway 서비스(launchd/systemd/schtasks)를 감지하고, 이를 제거한 뒤 현재 Gateway 포트를 사용해 OpenClaw 서비스를 설치하도록 제안합니다. 또한 추가 Gateway 유사 서비스를 스캔하고 정리 힌트를 출력할 수 있습니다. 프로필 이름이 지정된 OpenClaw Gateway 서비스는 일급 구성 요소로 간주되며 "추가"로 표시되지 않습니다. + Doctor는 레거시 gateway 서비스(launchd/systemd/schtasks)를 감지하고 이를 제거한 뒤 현재 gateway 포트를 사용해 OpenClaw 서비스를 설치하도록 제안합니다. 또한 추가 gateway 유사 서비스를 스캔하고 정리 힌트를 출력할 수 있습니다. 프로필 이름이 지정된 OpenClaw gateway 서비스는 일급 대상으로 간주되며 "extra"로 표시되지 않습니다. - Linux에서 사용자 수준 Gateway 서비스가 없지만 시스템 수준 OpenClaw Gateway 서비스가 있는 경우 doctor는 두 번째 사용자 수준 서비스를 자동으로 설치하지 않습니다. `openclaw gateway status --deep` 또는 `openclaw doctor --deep`으로 검사한 다음, 중복 항목을 제거하거나 시스템 supervisor가 Gateway 수명 주기를 소유하는 경우 `OPENCLAW_SERVICE_REPAIR_POLICY=external`을 설정하세요. + Linux에서 사용자 수준 gateway 서비스가 없지만 시스템 수준 OpenClaw gateway 서비스가 있으면 doctor는 두 번째 사용자 수준 서비스를 자동으로 설치하지 않습니다. `openclaw gateway status --deep` 또는 `openclaw doctor --deep`로 검사한 다음, 중복 항목을 제거하거나 시스템 supervisor가 gateway 수명 주기를 소유하는 경우 `OPENCLAW_SERVICE_REPAIR_POLICY=external`을 설정하세요. - - Matrix 채널 계정에 보류 중이거나 조치 가능한 레거시 상태 마이그레이션이 있으면 doctor는 (`--fix` / `--repair` 모드에서) 마이그레이션 전 스냅샷을 만든 다음 최선 노력 방식의 마이그레이션 단계인 레거시 Matrix 상태 마이그레이션과 레거시 암호화 상태 준비를 실행합니다. 두 단계 모두 치명적이지 않습니다. 오류는 기록되고 시작은 계속됩니다. 읽기 전용 모드(`--fix` 없이 `openclaw doctor`)에서는 이 검사를 완전히 건너뜁니다. + + Matrix 채널 계정에 보류 중이거나 실행 가능한 레거시 상태 마이그레이션이 있으면 doctor는 (`--fix` / `--repair` 모드에서) 마이그레이션 전 스냅샷을 만든 다음 최선형 마이그레이션 단계인 레거시 Matrix 상태 마이그레이션과 레거시 암호화 상태 준비를 실행합니다. 두 단계 모두 치명적이지 않습니다. 오류는 기록되고 시작은 계속됩니다. 읽기 전용 모드(`--fix` 없이 `openclaw doctor`)에서는 이 검사가 완전히 건너뜁니다. - doctor는 이제 일반 상태 검사 과정에서 기기 페어링 상태를 검사합니다. + Doctor는 이제 일반 상태 점검의 일부로 기기 페어링 상태를 검사합니다. - 보고 항목: + 보고하는 항목: - 보류 중인 최초 페어링 요청 - 이미 페어링된 기기의 보류 중인 역할 업그레이드 - 이미 페어링된 기기의 보류 중인 범위 업그레이드 - 기기 id는 여전히 일치하지만 기기 ID가 승인된 레코드와 더 이상 일치하지 않는 공개 키 불일치 복구 - - 승인된 역할에 대한 활성 토큰이 없는 페어링된 레코드 - - 범위가 승인된 페어링 기준선 밖으로 드리프트된 페어링된 토큰 - - Gateway 측 토큰 회전보다 오래되었거나 오래된 범위 메타데이터를 가진 현재 머신의 로컬 캐시 기기 토큰 항목 + - 승인된 역할에 대한 활성 토큰이 없는 페어링 레코드 + - 승인된 페어링 기준선 밖으로 범위가 드리프트된 페어링 토큰 + - gateway 측 토큰 순환보다 오래되었거나 오래된 범위 메타데이터를 포함하는 현재 머신의 로컬 캐시 기기 토큰 항목 - doctor는 페어링 요청을 자동 승인하거나 기기 토큰을 자동 회전하지 않습니다. 대신 정확한 다음 단계를 출력합니다. + Doctor는 페어링 요청을 자동 승인하거나 기기 토큰을 자동 순환하지 않습니다. 대신 정확한 다음 단계를 출력합니다. - `openclaw devices list`로 보류 중인 요청 검사 - `openclaw devices approve `로 정확한 요청 승인 - - `openclaw devices rotate --device --role `로 새 토큰 회전 + - `openclaw devices rotate --device --role `로 새 토큰 순환 - `openclaw devices remove `로 오래된 레코드 제거 및 재승인 - 이는 흔한 "이미 페어링되었지만 여전히 페어링 필요가 표시됨" 문제를 해결합니다. doctor는 이제 최초 페어링, 보류 중인 역할/범위 업그레이드, 오래된 토큰/기기 ID 드리프트를 구분합니다. + 이는 흔한 "이미 페어링되었지만 여전히 페어링 필요 메시지가 표시됨" 문제를 해결합니다. doctor는 이제 최초 페어링, 보류 중인 역할/범위 업그레이드, 오래된 토큰/기기 ID 드리프트를 구분합니다. - doctor는 공급자가 허용 목록 없이 DM에 열려 있거나 정책이 위험한 방식으로 구성된 경우 경고를 내보냅니다. + Doctor는 공급자가 허용 목록 없이 DM에 열려 있거나 정책이 위험한 방식으로 구성된 경우 경고를 내보냅니다. - systemd 사용자 서비스로 실행 중인 경우 doctor는 Gateway가 로그아웃 후에도 계속 살아 있도록 lingering이 활성화되었는지 확인합니다. + systemd 사용자 서비스로 실행 중이면 doctor는 로그아웃 후에도 gateway가 계속 살아 있도록 lingering이 활성화되어 있는지 확인합니다. - - doctor는 기본 에이전트의 워크스페이스 상태 요약을 출력합니다. + + Doctor는 기본 에이전트의 워크스페이스 상태 요약을 출력합니다. - - **Skills 상태**: 적격, 요구 사항 누락, 허용 목록 차단 Skills 수를 집계합니다. - - **레거시 워크스페이스 디렉터리**: 현재 워크스페이스와 함께 `~/openclaw` 또는 다른 레거시 워크스페이스 디렉터리가 존재할 때 경고합니다. - - **Plugin 상태**: 활성화/비활성화/오류 Plugin 수를 집계합니다. 오류가 있는 경우 Plugin ID를 나열합니다. 번들 Plugin 기능을 보고합니다. - - **Plugin 호환성 경고**: 현재 런타임과 호환성 문제가 있는 Plugin을 표시합니다. - - **Plugin 진단**: Plugin 레지스트리가 내보낸 로드 시점 경고 또는 오류를 표시합니다. + - **Skills 상태**: eligible, missing-requirements, allowlist-blocked skills 수를 계산합니다. + - **레거시 워크스페이스 디렉터리**: `~/openclaw` 또는 기타 레거시 워크스페이스 디렉터리가 현재 워크스페이스와 함께 존재할 때 경고합니다. + - **Plugin 상태**: 활성화/비활성화/오류 Plugin 수를 계산하고, 오류가 있는 Plugin ID를 나열하며, 번들 Plugin 기능을 보고합니다. + - **Plugin 호환성 경고**: 현재 런타임과 호환성 문제가 있는 Plugin에 플래그를 지정합니다. + - **Plugin 진단**: Plugin 레지스트리에서 내보낸 로드 시점 경고 또는 오류를 표시합니다. - doctor는 워크스페이스 부트스트랩 파일(예: `AGENTS.md`, `CLAUDE.md` 또는 기타 주입된 컨텍스트 파일)이 구성된 문자 예산에 근접했거나 초과했는지 확인합니다. 파일별 원시 문자 수와 주입된 문자 수, 잘림 비율, 잘림 원인(`max/file` 또는 `max/total`), 전체 예산 대비 총 주입 문자 비율을 보고합니다. 파일이 잘렸거나 한도에 가까우면 doctor는 `agents.defaults.bootstrapMaxChars` 및 `agents.defaults.bootstrapTotalMaxChars` 조정 팁을 출력합니다. + Doctor는 워크스페이스 부트스트랩 파일(예: `AGENTS.md`, `CLAUDE.md` 또는 기타 주입된 컨텍스트 파일)이 구성된 문자 예산에 가깝거나 초과했는지 확인합니다. 파일별 원시 문자 수와 주입된 문자 수, 잘림 비율, 잘림 원인(`max/file` 또는 `max/total`), 총 예산 대비 총 주입 문자 비율을 보고합니다. 파일이 잘렸거나 한도에 가까우면 doctor는 `agents.defaults.bootstrapMaxChars` 및 `agents.defaults.bootstrapTotalMaxChars` 조정 팁을 출력합니다. - `openclaw doctor --fix`가 누락된 채널 Plugin을 제거할 때, 해당 Plugin을 참조하던 매달린 채널 범위 구성도 함께 제거합니다. `channels.` 항목, 채널 이름을 지정한 Heartbeat 대상, `agents.*.models["/*"]` 재정의가 포함됩니다. 이렇게 하면 채널 런타임은 사라졌지만 구성이 여전히 Gateway에 해당 채널에 바인딩하라고 요청해 발생하는 Gateway 부팅 루프를 방지합니다. + `openclaw doctor --fix`가 누락된 채널 Plugin을 제거할 때, 해당 Plugin을 참조하던 dangling 채널 범위 구성도 제거합니다. 여기에는 `channels.` 항목, 채널 이름을 지정한 Heartbeat 대상, `agents.*.models["/*"]` 재정의가 포함됩니다. 이렇게 하면 채널 런타임은 사라졌지만 구성은 여전히 gateway에 바인딩을 요청하는 Gateway 부팅 루프를 방지합니다. - - doctor는 현재 셸(zsh, bash, fish 또는 PowerShell)에 탭 완성이 설치되어 있는지 확인합니다. + + Doctor는 현재 셸(zsh, bash, fish 또는 PowerShell)에 탭 자동 완성이 설치되어 있는지 확인합니다. - 셸 프로필이 느린 동적 완성 패턴(`source <(openclaw completion ...)`)을 사용하는 경우 doctor는 더 빠른 캐시 파일 변형으로 업그레이드합니다. - - 프로필에 완성이 구성되어 있지만 캐시 파일이 없으면 doctor가 캐시를 자동으로 재생성합니다. - - 완성이 전혀 구성되어 있지 않으면 doctor가 설치를 묻습니다(대화형 모드만 해당, `--non-interactive`에서는 건너뜀). + - 완성이 프로필에 구성되어 있지만 캐시 파일이 없으면 doctor가 캐시를 자동으로 다시 생성합니다. + - 완성이 전혀 구성되어 있지 않으면 doctor가 설치를 요청합니다(대화형 모드만 해당, `--non-interactive`에서는 건너뜀). - 캐시를 수동으로 재생성하려면 `openclaw completion --write-state`를 실행하세요. + 캐시를 수동으로 다시 생성하려면 `openclaw completion --write-state`를 실행하세요. - doctor는 로컬 Gateway 토큰 인증 준비 상태를 확인합니다. + Doctor는 로컬 gateway 토큰 인증 준비 상태를 확인합니다. - - 토큰 모드에 토큰이 필요하지만 토큰 소스가 없으면 doctor는 토큰 생성을 제안합니다. - - `gateway.auth.token`이 SecretRef로 관리되지만 사용할 수 없는 경우 doctor는 경고하고 이를 평문으로 덮어쓰지 않습니다. - - `openclaw doctor --generate-gateway-token`은 토큰 SecretRef가 구성되어 있지 않을 때만 생성을 강제합니다. + - 토큰 모드에 토큰이 필요하지만 토큰 소스가 없으면 doctor가 생성을 제안합니다. + - `gateway.auth.token`이 SecretRef로 관리되지만 사용할 수 없으면 doctor가 경고하고 이를 일반 텍스트로 덮어쓰지 않습니다. + - `openclaw doctor --generate-gateway-token`은 토큰 SecretRef가 구성되지 않은 경우에만 생성을 강제합니다. - 일부 복구 흐름은 런타임 fail-fast 동작을 약화하지 않으면서 구성된 자격 증명을 검사해야 합니다. + 일부 복구 흐름은 런타임 fail-fast 동작을 약화시키지 않고 구성된 자격 증명을 검사해야 합니다. - - `openclaw doctor --fix`는 이제 대상 구성 복구에 상태 계열 명령과 동일한 읽기 전용 SecretRef 요약 모델을 사용합니다. + - `openclaw doctor --fix`는 이제 대상 구성 복구에 status 계열 명령과 동일한 읽기 전용 SecretRef 요약 모델을 사용합니다. - 예: Telegram `allowFrom` / `groupAllowFrom` `@username` 복구는 사용 가능한 경우 구성된 봇 자격 증명을 사용하려고 시도합니다. - - Telegram 봇 토큰이 SecretRef를 통해 구성되었지만 현재 명령 경로에서 사용할 수 없는 경우, doctor는 충돌하거나 토큰이 누락되었다고 잘못 보고하는 대신 자격 증명이 구성되었지만 사용할 수 없다고 보고하고 자동 해결을 건너뜁니다. + - Telegram 봇 토큰이 SecretRef를 통해 구성되었지만 현재 명령 경로에서 사용할 수 없는 경우, doctor는 충돌하거나 토큰이 누락되었다고 잘못 보고하는 대신 자격 증명이 구성되었지만 사용할 수 없다고 보고하고 자동 해석을 건너뜁니다. - doctor는 상태 검사를 실행하고 Gateway가 비정상으로 보이면 재시작을 제안합니다. + Doctor는 상태 검사를 실행하고 gateway가 비정상으로 보일 때 재시작을 제안합니다. - doctor는 구성된 메모리 검색 임베딩 공급자가 기본 에이전트에 대해 준비되었는지 확인합니다. 동작은 구성된 백엔드와 공급자에 따라 달라집니다. + Doctor는 구성된 메모리 검색 임베딩 공급자가 기본 에이전트에 대해 준비되었는지 확인합니다. 동작은 구성된 백엔드와 공급자에 따라 달라집니다. - - **QMD 백엔드**: `qmd` 바이너리를 사용할 수 있고 시작 가능한지 프로브합니다. 그렇지 않으면 npm 패키지와 수동 바이너리 경로 옵션을 포함한 수정 안내를 출력합니다. - - **명시적 로컬 공급자**: 로컬 모델 파일 또는 인식된 원격/다운로드 가능한 모델 URL을 확인합니다. 누락된 경우 원격 공급자로 전환할 것을 제안합니다. - - **명시적 원격 공급자**(`openai`, `voyage` 등): 환경 또는 인증 저장소에 API 키가 있는지 확인합니다. 누락된 경우 조치 가능한 수정 힌트를 출력합니다. - - **자동 공급자**: 먼저 로컬 모델 가용성을 확인한 다음 자동 선택 순서에 따라 각 원격 공급자를 시도합니다. + - **QMD 백엔드**: `qmd` 바이너리가 사용 가능하고 시작 가능한지 프로브합니다. 그렇지 않으면 npm 패키지와 수동 바이너리 경로 옵션을 포함한 수정 지침을 출력합니다. + - **명시적 로컬 공급자**: 로컬 모델 파일 또는 인식된 원격/다운로드 가능 모델 URL을 확인합니다. 누락된 경우 원격 공급자로 전환할 것을 제안합니다. + - **명시적 원격 공급자**(`openai`, `voyage` 등): API 키가 환경 또는 인증 저장소에 있는지 확인합니다. 누락된 경우 실행 가능한 수정 힌트를 출력합니다. + - **자동 공급자**: 먼저 로컬 모델 가용성을 확인한 다음, 자동 선택 순서대로 각 원격 공급자를 시도합니다. - 캐시된 Gateway 프로브 결과를 사용할 수 있는 경우(검사 당시 Gateway가 정상), doctor는 그 결과를 CLI에서 볼 수 있는 구성과 상호 참조하고 불일치를 알립니다. doctor는 기본 경로에서 새 임베딩 ping을 시작하지 않습니다. 라이브 공급자 검사를 원하면 심층 메모리 상태 명령을 사용하세요. + 캐시된 gateway 프로브 결과를 사용할 수 있는 경우(검사 시점에 gateway가 정상인 경우), doctor는 그 결과를 CLI에서 볼 수 있는 구성과 교차 참조하고 불일치를 기록합니다. Doctor는 기본 경로에서 새 임베딩 ping을 시작하지 않습니다. 실시간 공급자 검사를 원하면 심층 메모리 상태 명령을 사용하세요. 런타임에서 임베딩 준비 상태를 확인하려면 `openclaw memory status --deep`를 사용하세요. - Gateway가 정상인 경우 doctor는 채널 상태 프로브를 실행하고 제안된 수정과 함께 경고를 보고합니다. + gateway가 정상이면 doctor는 채널 상태 프로브를 실행하고 제안된 수정 사항과 함께 경고를 보고합니다. - - doctor는 설치된 supervisor 구성(launchd/systemd/schtasks)에 누락되었거나 오래된 기본값(예: systemd network-online 종속성 및 재시작 지연)이 있는지 확인합니다. 불일치가 발견되면 업데이트를 권장하고 서비스 파일/작업을 현재 기본값으로 다시 쓸 수 있습니다. + + Doctor는 설치된 supervisor 구성(launchd/systemd/schtasks)에 누락되었거나 오래된 기본값(예: systemd network-online 의존성 및 재시작 지연)이 있는지 확인합니다. 불일치를 발견하면 업데이트를 권장하고 서비스 파일/작업을 현재 기본값으로 다시 쓸 수 있습니다. 참고: - - `openclaw doctor`는 supervisor 구성을 다시 쓰기 전에 묻습니다. + - `openclaw doctor`는 supervisor 설정을 다시 쓰기 전에 확인을 요청합니다. - `openclaw doctor --yes`는 기본 복구 프롬프트를 수락합니다. - `openclaw doctor --repair`는 프롬프트 없이 권장 수정 사항을 적용합니다. - - `openclaw doctor --repair --force`는 사용자 지정 supervisor 구성을 덮어씁니다. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external`은 doctor가 Gateway 서비스 수명 주기에 대해 읽기 전용으로 유지되게 합니다. 서비스 상태를 계속 보고하고 비서비스 복구를 실행하지만, 외부 supervisor가 해당 수명 주기를 소유하므로 서비스 설치/시작/재시작/부트스트랩, supervisor 구성 재작성, 레거시 서비스 정리를 건너뜁니다. - - Linux에서 doctor는 일치하는 systemd Gateway 유닛이 활성 상태인 동안 명령/엔트리포인트 메타데이터를 다시 쓰지 않습니다. 또한 중복 서비스 스캔 중 비활성 비레거시 추가 Gateway 유사 유닛을 무시하므로 동반 서비스 파일이 정리 잡음을 만들지 않습니다. - - 토큰 인증에 토큰이 필요하고 `gateway.auth.token`이 SecretRef로 관리되는 경우, doctor 서비스 설치/복구는 SecretRef를 검증하지만 확인된 평문 토큰 값을 supervisor 서비스 환경 메타데이터에 유지하지 않습니다. - - doctor는 이전 LaunchAgent, systemd 또는 Windows 예약 작업 설치가 인라인으로 포함한 관리형 `.env`/SecretRef 기반 서비스 환경 값을 감지하고, 해당 값이 supervisor 정의 대신 런타임 소스에서 로드되도록 서비스 메타데이터를 다시 씁니다. - - doctor는 `gateway.port`가 변경된 뒤에도 서비스 명령이 여전히 이전 `--port`를 고정하고 있는 경우를 감지하고 서비스 메타데이터를 현재 포트로 다시 씁니다. - - 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef가 확인되지 않으면 doctor는 조치 가능한 안내와 함께 설치/복구 경로를 차단합니다. - - `gateway.auth.token`과 `gateway.auth.password`가 모두 구성되어 있고 `gateway.auth.mode`가 설정되지 않은 경우 doctor는 모드가 명시적으로 설정될 때까지 설치/복구를 차단합니다. - - Linux 사용자 systemd 유닛의 경우 doctor 토큰 드리프트 검사는 이제 서비스 인증 메타데이터를 비교할 때 `Environment=` 및 `EnvironmentFile=` 소스를 모두 포함합니다. - - doctor 서비스 복구는 구성이 마지막으로 더 새로운 버전에서 작성된 경우 이전 OpenClaw 바이너리의 Gateway 서비스를 다시 쓰거나 중지하거나 재시작하기를 거부합니다. [Gateway 문제 해결](/ko/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)을 참조하세요. - - `openclaw gateway install --force`를 통해 언제든지 전체 재작성을 강제할 수 있습니다. + - `openclaw doctor --repair --force`는 사용자 지정 supervisor 설정을 덮어씁니다. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external`은 Gateway 서비스 수명 주기에 대해 doctor를 읽기 전용으로 유지합니다. 서비스 상태를 계속 보고하고 비서비스 복구를 실행하지만, 외부 supervisor가 해당 수명 주기를 소유하므로 서비스 설치/시작/재시작/부트스트랩, supervisor 설정 다시 쓰기, 레거시 서비스 정리를 건너뜁니다. + - Linux에서는 일치하는 systemd Gateway 유닛이 활성 상태인 동안 doctor가 명령/엔트리포인트 메타데이터를 다시 쓰지 않습니다. 또한 중복 서비스 스캔 중 비활성 비레거시 추가 Gateway 유사 유닛을 무시하므로 동반 서비스 파일이 정리 소음을 만들지 않습니다. + - 토큰 인증에 토큰이 필요하고 `gateway.auth.token`이 SecretRef로 관리되는 경우, doctor 서비스 설치/복구는 SecretRef를 검증하지만 확인된 평문 토큰 값을 supervisor 서비스 환경 메타데이터에 저장하지 않습니다. + - Doctor는 이전 LaunchAgent, systemd 또는 Windows Scheduled Task 설치가 인라인으로 포함한 관리형 `.env`/SecretRef 기반 서비스 환경 값을 감지하고, 해당 값이 supervisor 정의 대신 런타임 소스에서 로드되도록 서비스 메타데이터를 다시 씁니다. + - Doctor는 `gateway.port` 변경 후에도 서비스 명령이 여전히 이전 `--port`를 고정하고 있으면 이를 감지하고 서비스 메타데이터를 현재 포트로 다시 씁니다. + - 토큰 인증에 토큰이 필요하고 구성된 토큰 SecretRef가 확인되지 않으면, doctor는 실행 가능한 안내와 함께 설치/복구 경로를 차단합니다. + - `gateway.auth.token`과 `gateway.auth.password`가 모두 구성되어 있고 `gateway.auth.mode`가 설정되지 않은 경우, doctor는 모드가 명시적으로 설정될 때까지 설치/복구를 차단합니다. + - Linux 사용자 systemd 유닛의 경우, doctor 토큰 드리프트 검사는 이제 서비스 인증 메타데이터를 비교할 때 `Environment=`와 `EnvironmentFile=` 소스를 모두 포함합니다. + - Doctor 서비스 복구는 설정이 더 최신 버전에서 마지막으로 작성된 경우 이전 OpenClaw 바이너리의 Gateway 서비스를 다시 쓰거나 중지하거나 재시작하지 않습니다. [Gateway 문제 해결](/ko/gateway/troubleshooting#split-brain-installs-and-newer-config-guard)을 참고하세요. + - 언제든지 `openclaw gateway install --force`를 통해 전체 다시 쓰기를 강제할 수 있습니다. - Doctor는 서비스 런타임(PID, 마지막 종료 상태)을 검사하고, 서비스가 설치되어 있지만 실제로 실행 중이 아닐 때 경고합니다. 또한 Gateway 포트(기본값 `18789`)에서 포트 충돌을 확인하고 가능한 원인(Gateway가 이미 실행 중, SSH 터널)을 보고합니다. + Doctor는 서비스 런타임(PID, 마지막 종료 상태)을 검사하고 서비스가 설치되어 있지만 실제로 실행 중이 아닐 때 경고합니다. 또한 Gateway 포트(기본값 `18789`)의 포트 충돌을 확인하고 가능한 원인(Gateway가 이미 실행 중, SSH 터널)을 보고합니다. - Doctor는 Gateway 서비스가 Bun 또는 버전 관리 Node 경로(`nvm`, `fnm`, `volta`, `asdf` 등)에서 실행될 때 경고합니다. WhatsApp + Telegram 채널에는 Node가 필요하며, 버전 관리자 경로는 서비스가 셸 초기화를 로드하지 않기 때문에 업그레이드 후 깨질 수 있습니다. Doctor는 사용할 수 있는 경우 시스템 Node 설치(Homebrew/apt/choco)로 마이그레이션하도록 제안합니다. + Doctor는 Gateway 서비스가 Bun 또는 버전 관리형 Node 경로(`nvm`, `fnm`, `volta`, `asdf` 등)에서 실행될 때 경고합니다. WhatsApp + Telegram 채널에는 Node가 필요하며, 버전 관리자 경로는 서비스가 셸 초기화를 로드하지 않기 때문에 업그레이드 후 깨질 수 있습니다. Doctor는 사용 가능한 경우 시스템 Node 설치(Homebrew/apt/choco)로 마이그레이션할 것을 제안합니다. - 새로 설치되거나 복구된 서비스는 명시적인 환경 루트(`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`)와 안정적인 사용자 바이너리 디렉터리를 유지하지만, 추정된 버전 관리자 폴백 디렉터리는 해당 디렉터리가 디스크에 존재할 때만 서비스 PATH에 기록됩니다. 이렇게 하면 생성된 supervisor PATH가 Doctor가 나중에 실행하는 동일한 최소 PATH 감사와 일치하게 유지됩니다. + 새로 설치되거나 복구된 서비스는 명시적 환경 루트(`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`)와 안정적인 사용자 bin 디렉터리를 유지하지만, 추정된 버전 관리자 대체 디렉터리는 해당 디렉터리가 디스크에 존재할 때만 서비스 PATH에 기록됩니다. 이렇게 하면 생성된 supervisor PATH가 doctor가 나중에 실행하는 동일한 최소 PATH 감사와 정렬된 상태로 유지됩니다. - - Doctor는 모든 구성 변경 사항을 저장하고 Doctor 실행을 기록하도록 마법사 메타데이터에 스탬프를 찍습니다. + + Doctor는 모든 설정 변경 사항을 저장하고 doctor 실행을 기록하도록 마법사 메타데이터를 찍습니다. - - Doctor는 작업 영역 메모리 시스템이 없을 때 이를 제안하고, 작업 영역이 아직 git 아래에 있지 않은 경우 백업 팁을 출력합니다. + + Doctor는 워크스페이스 메모리 시스템이 없을 때 제안하고, 워크스페이스가 아직 git 아래에 있지 않으면 백업 팁을 출력합니다. - 작업 영역 구조와 git 백업(비공개 GitHub 또는 GitLab 권장)에 대한 전체 가이드는 [/concepts/agent-workspace](/ko/concepts/agent-workspace)를 참조하세요. + 워크스페이스 구조와 git 백업(비공개 GitHub 또는 GitLab 권장)에 대한 전체 가이드는 [/concepts/agent-workspace](/ko/concepts/agent-workspace)를 참고하세요. ## 관련 항목 -- [Gateway 실행 안내서](/ko/gateway) +- [Gateway 실행 지침서](/ko/gateway) - [Gateway 문제 해결](/ko/gateway/troubleshooting) diff --git a/docs/ko/gateway/gateway-lock.md b/docs/ko/gateway/gateway-lock.md index 67dba7f8b..f3bc6e3dd 100644 --- a/docs/ko/gateway/gateway-lock.md +++ b/docs/ko/gateway/gateway-lock.md @@ -1,42 +1,42 @@ --- read_when: - Gateway 프로세스 실행 또는 디버깅 - - 단일 인스턴스 강제 적용 조사 중 + - 단일 인스턴스 강제 적용 조사 summary: WebSocket 리스너 바인딩을 사용하는 Gateway 싱글턴 가드 title: Gateway 잠금 x-i18n: - generated_at: "2026-04-30T06:30:49Z" + generated_at: "2026-04-30T16:28:57Z" model: gpt-5.5 provider: openai - source_hash: fe61ff81106554e98de1ca04c213b76d230265cdf3e81b70897d2de00f6a0179 + source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13 source_path: gateway/gateway-lock.md workflow: 16 --- ## 이유 -- 동일한 호스트의 같은 기본 포트에서 Gateway 인스턴스가 하나만 실행되도록 보장합니다. 추가 Gateway는 격리된 프로필과 고유한 포트를 사용해야 합니다. -- 오래된 잠금 파일을 남기지 않고 충돌/SIGKILL을 견딥니다. -- 제어 포트가 이미 사용 중이면 명확한 오류와 함께 빠르게 실패합니다. +- 같은 호스트의 동일한 기본 포트에서 Gateway 인스턴스가 하나만 실행되도록 보장합니다. 추가 Gateway는 격리된 프로필과 고유한 포트를 사용해야 합니다. +- 충돌/SIGKILL 이후에도 오래된 잠금 파일을 남기지 않고 복구합니다. +- 제어 포트가 이미 점유된 경우 명확한 오류와 함께 빠르게 실패합니다. ## 메커니즘 - Gateway는 먼저 상태 잠금 디렉터리 아래의 구성별 잠금 파일을 획득하고, 구성된 포트에 기존 리스너가 있는지 검사합니다. -- 기록된 잠금 소유자가 사라졌거나, 포트가 비어 있거나, 잠금이 오래된 경우 시작 과정에서 잠금을 회수하고 계속 진행합니다. -- 그런 다음 Gateway는 배타적 TCP 리스너를 사용해 HTTP/WebSocket 리스너(기본값 `ws://127.0.0.1:18789`)를 바인딩합니다. +- 기록된 잠금 소유자가 사라졌거나, 포트가 비어 있거나, 잠금이 오래된 경우 시작 과정이 잠금을 회수하고 계속 진행합니다. +- 그런 다음 Gateway는 독점 TCP 리스너를 사용해 HTTP/WebSocket 리스너(기본값 `ws://127.0.0.1:18789`)를 바인딩합니다. - 바인딩이 `EADDRINUSE`로 실패하면 시작 과정에서 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:")`를 발생시킵니다. - 종료 시 Gateway는 HTTP/WebSocket 서버를 닫고 잠금 파일을 제거합니다. ## 오류 표면 - 다른 프로세스가 포트를 점유하고 있으면 시작 과정에서 `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:")`를 발생시킵니다. -- 그 밖의 바인딩 실패는 `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:: …")`로 표면화됩니다. +- 다른 바인딩 실패는 `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:: …")`로 표시됩니다. ## 운영 참고 사항 - 포트가 _다른_ 프로세스에 의해 점유된 경우에도 오류는 동일합니다. 포트를 비우거나 `openclaw gateway --port `로 다른 포트를 선택하세요. -- 서비스 슈퍼바이저 아래에서 정상 상태인 기존 `/healthz` 응답자를 발견한 새 Gateway 프로세스는 성공적으로 종료하고 해당 프로세스가 제어를 유지하도록 둡니다. 기존 프로세스가 정상 상태가 되지 않으면 재시도는 제한되며, 시작 과정은 무한히 반복하는 대신 명확한 잠금 오류로 실패합니다. -- macOS 앱은 Gateway를 생성하기 전에 여전히 자체적인 경량 PID 가드를 유지합니다. 런타임 잠금은 잠금 파일과 HTTP/WebSocket 바인딩으로 강제됩니다. +- 서비스 슈퍼바이저 아래에서 기존의 정상적인 `/healthz` 응답자를 발견한 새 Gateway 프로세스는 해당 프로세스가 계속 제어하도록 둡니다. systemd에서는 중복 시작 프로세스가 코드 78로 종료되므로 기본 `RestartPreventExitStatus=78`이 `Restart=always`가 잠금 또는 `EADDRINUSE` 충돌에서 반복되지 않도록 막습니다. 기존 프로세스가 정상 상태가 되지 않으면 재시도가 제한되며 시작은 무한 루프 대신 명확한 잠금 오류와 함께 실패합니다. +- macOS 앱은 Gateway를 생성하기 전에 여전히 자체 경량 PID 가드를 유지합니다. 런타임 잠금은 잠금 파일과 HTTP/WebSocket 바인딩으로 강제됩니다. ## 관련 항목 diff --git a/docs/ko/platforms/mac/remote.md b/docs/ko/platforms/mac/remote.md index 10f29e160..8bacb13b4 100644 --- a/docs/ko/platforms/mac/remote.md +++ b/docs/ko/platforms/mac/remote.md @@ -1,103 +1,102 @@ --- read_when: - - 원격 Mac 제어 설정 또는 디버깅하기 -summary: SSH를 통해 원격 OpenClaw gateway를 제어하는 macOS 앱 흐름 + - 원격 Mac 제어 설정 또는 디버깅 +summary: SSH를 통해 원격 OpenClaw Gateway를 제어하기 위한 macOS 앱 흐름 title: 원격 제어 x-i18n: - generated_at: "2026-04-26T11:34:19Z" - model: gpt-5.4 + generated_at: "2026-04-30T16:29:01Z" + model: gpt-5.5 provider: openai - source_hash: 4de4980fe378fc9b685cf7732d21a80c640088191308b8ef1d3df9f468cb5be2 + source_hash: 2c63f752c3636a253220310c7c8e57a28549704b74b2f0370bac432bae28a7d3 source_path: platforms/mac/remote.md - workflow: 15 + workflow: 16 --- # 원격 OpenClaw (macOS ⇄ 원격 호스트) -이 흐름을 사용하면 macOS 앱이 다른 호스트(데스크톱/서버)에서 실행 중인 OpenClaw gateway를 완전한 원격 제어 대상으로 사용할 수 있습니다. 이는 앱의 **SSH를 통한 원격**(원격 실행) 기능입니다. 상태 점검, Voice Wake 전달, Web Chat을 포함한 모든 기능은 _설정 → 일반_의 동일한 원격 SSH 구성을 재사용합니다. +이 흐름을 사용하면 macOS 앱이 다른 호스트(데스크톱/서버)에서 실행 중인 OpenClaw Gateway를 완전한 원격 제어처럼 사용할 수 있습니다. 앱의 **SSH를 통한 원격**(원격 실행) 기능입니다. 모든 기능(상태 확인, 음성 깨우기 전달, 웹 채팅)은 _설정 → 일반_의 동일한 원격 SSH 구성을 재사용합니다. ## 모드 -- **로컬(이 Mac)**: 모든 것이 노트북에서 실행됩니다. SSH는 사용되지 않습니다. -- **SSH를 통한 원격(기본값)**: OpenClaw 명령이 원격 호스트에서 실행됩니다. mac 앱은 `-o BatchMode`와 선택한 ID/키, 로컬 포트 포워딩을 사용해 SSH 연결을 엽니다. -- **원격 direct (ws/wss)**: SSH 터널이 없습니다. mac 앱이 gateway URL에 직접 연결합니다(예: Tailscale Serve 또는 공개 HTTPS 리버스 프록시를 통해). +- **로컬(이 Mac)**: 모든 것이 노트북에서 실행됩니다. SSH는 사용하지 않습니다. +- **SSH를 통한 원격(기본값)**: OpenClaw 명령이 원격 호스트에서 실행됩니다. Mac 앱은 선택한 ID/키와 local loopback 포트 전달을 사용해 `-o BatchMode`로 SSH 연결을 엽니다. +- **원격 직접 연결(ws/wss)**: SSH 터널을 사용하지 않습니다. Mac 앱이 Gateway URL에 직접 연결합니다(예: Tailscale Serve 또는 공개 HTTPS 리버스 프록시를 통해). ## 원격 전송 -원격 모드는 두 가지 전송을 지원합니다. +원격 모드는 두 가지 전송 방식을 지원합니다. -- **SSH 터널**(기본값): `ssh -N -L ...`을 사용해 gateway 포트를 localhost로 포워딩합니다. 이 경우 gateway는 Node의 IP를 루프백이므로 `127.0.0.1`로 보게 됩니다. -- **Direct (ws/wss)**: gateway URL에 직접 연결합니다. gateway는 실제 클라이언트 IP를 보게 됩니다. +- **SSH 터널**(기본값): `ssh -N -L ...`을 사용해 Gateway 포트를 localhost로 전달합니다. 터널이 loopback이므로 Gateway는 노드의 IP를 `127.0.0.1`로 봅니다. +- **직접 연결(ws/wss)**: Gateway URL에 바로 연결합니다. Gateway는 실제 클라이언트 IP를 봅니다. -SSH 터널 모드에서는 검색된 LAN/tailnet 호스트 이름이 -`gateway.remote.sshTarget`으로 저장됩니다. 앱은 -`gateway.remote.url`을 `ws://127.0.0.1:18789` 같은 로컬 -터널 엔드포인트로 유지하므로, CLI, Web Chat, 로컬 node-host 서비스가 -모두 동일한 안전한 loopback 전송을 사용합니다. +SSH 터널 모드에서는 발견된 LAN/tailnet 호스트 이름이 +`gateway.remote.sshTarget`으로 저장됩니다. 앱은 `gateway.remote.url`을 +로컬 터널 엔드포인트(예: `ws://127.0.0.1:18789`)로 유지하므로 CLI, 웹 채팅, +로컬 노드 호스트 서비스가 모두 동일한 안전한 loopback 전송을 사용합니다. -원격 모드의 브라우저 자동화는 네이티브 macOS 앱 Node가 아니라 CLI node host가 소유합니다. 앱은 가능하면 설치된 node host 서비스를 시작합니다. 해당 Mac에서 브라우저 제어가 필요하면 `openclaw node install ...`과 `openclaw node start`로 설치/시작하거나 (`openclaw node run ...`을 포그라운드에서 실행해도 됨), -그 브라우저 기능이 있는 Node를 대상으로 지정하세요. +원격 모드의 브라우저 자동화는 네이티브 macOS 앱 노드가 아니라 CLI 노드 호스트가 담당합니다. 앱은 가능한 경우 설치된 노드 호스트 서비스를 시작합니다. 해당 Mac에서 브라우저 제어가 필요하면 `openclaw node install ...` 및 `openclaw node start`로 설치/시작하거나(`openclaw node run ...`을 포그라운드에서 실행), 브라우저 기능을 갖춘 해당 노드를 대상으로 지정하세요. ## 원격 호스트의 사전 요구 사항 1. Node + pnpm을 설치하고 OpenClaw CLI를 빌드/설치합니다(`pnpm install && pnpm build && pnpm link --global`). -2. 비대화형 셸에서도 `openclaw`가 PATH에 있도록 합니다(필요하면 `/usr/local/bin` 또는 `/opt/homebrew/bin`에 심볼릭 링크). -3. 키 인증으로 SSH를 엽니다. LAN 밖에서 안정적인 도달 가능성을 위해 **Tailscale** IP 사용을 권장합니다. +2. 비대화형 셸에서 `openclaw`가 PATH에 있는지 확인합니다(필요한 경우 `/usr/local/bin` 또는 `/opt/homebrew/bin`에 심볼릭 링크). +3. 키 인증으로 SSH를 엽니다. LAN 외부에서도 안정적으로 연결할 수 있도록 **Tailscale** IP를 권장합니다. ## macOS 앱 설정 1. _설정 → 일반_을 엽니다. -2. **OpenClaw runs** 아래에서 **SSH를 통한 원격**을 선택하고 다음을 설정합니다. - - **Transport**: **SSH tunnel** 또는 **Direct (ws/wss)**. - - **SSH target**: `user@host` (선택적으로 `:port` 포함). - - gateway가 같은 LAN에 있고 Bonjour를 광고 중이라면 검색 목록에서 선택해 이 필드를 자동 입력할 수 있습니다. - - **Gateway URL** (Direct 전용): `wss://gateway.example.ts.net` (또는 로컬/LAN의 경우 `ws://...`). - - **Identity file** (고급): 키 경로. - - **Project root** (고급): 명령에 사용되는 원격 체크아웃 경로. - - **CLI path** (고급): 실행 가능한 `openclaw` 엔트리포인트/바이너리의 선택적 경로(광고된 경우 자동 입력됨). -3. **Test remote**를 누릅니다. 성공하면 원격에서 `openclaw status --json`이 올바르게 실행된다는 뜻입니다. 실패는 보통 PATH/CLI 문제를 의미하며, 종료 코드 127은 원격에서 CLI를 찾을 수 없다는 뜻입니다. -4. 이제 상태 점검과 Web Chat도 자동으로 이 SSH 터널을 통해 실행됩니다. +2. **OpenClaw 실행 위치**에서 **SSH를 통한 원격**을 선택하고 다음을 설정합니다. + - **전송**: **SSH 터널** 또는 **직접 연결(ws/wss)**. + - **SSH 대상**: `user@host`(선택적으로 `:port`). + - Gateway가 동일한 LAN에 있고 Bonjour를 광고하면, 발견된 목록에서 선택해 이 필드를 자동으로 채웁니다. + - **Gateway URL**(직접 연결 전용): `wss://gateway.example.ts.net`(또는 로컬/LAN의 경우 `ws://...`). + - **ID 파일**(고급): 키 경로. + - **프로젝트 루트**(고급): 명령에 사용할 원격 체크아웃 경로. + - **CLI 경로**(고급): 실행 가능한 `openclaw` 엔트리포인트/바이너리의 선택적 경로(광고되는 경우 자동 입력). +3. **원격 테스트**를 누릅니다. 성공은 원격 `openclaw status --json`이 올바르게 실행된다는 뜻입니다. 실패는 대개 PATH/CLI 문제를 의미하며, 종료 코드 127은 원격에서 CLI를 찾을 수 없다는 뜻입니다. +4. 이제 상태 확인과 웹 채팅이 이 SSH 터널을 통해 자동으로 실행됩니다. -## Web Chat +## 웹 채팅 -- **SSH 터널**: Web Chat은 포워딩된 WebSocket 제어 포트(기본값 18789)를 통해 gateway에 연결됩니다. -- **Direct (ws/wss)**: Web Chat은 구성된 gateway URL에 직접 연결됩니다. +- **SSH 터널**: 웹 채팅은 전달된 WebSocket 제어 포트(기본값 18789)를 통해 Gateway에 연결합니다. +- **직접 연결(ws/wss)**: 웹 채팅은 구성된 Gateway URL에 바로 연결합니다. - 별도의 WebChat HTTP 서버는 더 이상 없습니다. ## 권한 -- 원격 호스트에는 로컬과 같은 TCC 승인(Automation, Accessibility, Screen Recording, Microphone, Speech Recognition, Notifications)이 필요합니다. 해당 시스템에서 한 번 온보딩을 실행해 권한을 부여하세요. -- Node는 `node.list` / `node.describe`를 통해 권한 상태를 광고하므로 에이전트가 사용 가능한 기능을 알 수 있습니다. +- 원격 호스트에는 로컬과 동일한 TCC 승인(자동화, 손쉬운 사용, 화면 기록, 마이크, 음성 인식, 알림)이 필요합니다. 해당 머신에서 온보딩을 실행해 한 번만 권한을 부여하세요. +- 에이전트가 사용 가능한 항목을 알 수 있도록 노드는 `node.list` / `node.describe`를 통해 권한 상태를 광고합니다. -## 보안 참고 +## 보안 참고 사항 -- 원격 호스트에서는 loopback 바인드를 우선하고 SSH 또는 Tailscale을 통해 연결하세요. -- SSH 터널링은 엄격한 호스트 키 검사를 사용합니다. 먼저 호스트 키를 신뢰해 `~/.ssh/known_hosts`에 존재하도록 하세요. -- Gateway를 loopback이 아닌 인터페이스에 바인드한다면 유효한 Gateway 인증(토큰, 비밀번호 또는 `gateway.auth.mode: "trusted-proxy"`를 사용하는 ID 인식 리버스 프록시)을 요구하세요. +- 원격 호스트에서는 loopback 바인딩을 선호하고 SSH 또는 Tailscale을 통해 연결하세요. +- SSH 터널링은 엄격한 호스트 키 확인을 사용합니다. 먼저 호스트 키를 신뢰해 `~/.ssh/known_hosts`에 존재하도록 하세요. +- Gateway를 loopback이 아닌 인터페이스에 바인딩하는 경우 유효한 Gateway 인증(토큰, 비밀번호 또는 `gateway.auth.mode: "trusted-proxy"`를 사용하는 ID 인식 리버스 프록시)이 필요합니다. - [보안](/ko/gateway/security) 및 [Tailscale](/ko/gateway/tailscale)을 참조하세요. ## WhatsApp 로그인 흐름(원격) -- 원격 호스트에서 `openclaw channels login --verbose`를 실행하세요. 휴대폰의 WhatsApp으로 QR 코드를 스캔합니다. -- 인증이 만료되면 해당 호스트에서 로그인을 다시 실행하세요. 상태 점검이 링크 문제를 표시해 줍니다. +- **원격 호스트에서** `openclaw channels login --verbose`를 실행합니다. 휴대폰의 WhatsApp으로 QR을 스캔합니다. +- 인증이 만료되면 해당 호스트에서 로그인을 다시 실행합니다. 상태 확인에서 연결 문제가 표시됩니다. ## 문제 해결 -- **exit 127 / not found**: 비로그인 셸의 PATH에 `openclaw`가 없습니다. `/etc/paths`, 셸 rc에 추가하거나 `/usr/local/bin`/`/opt/homebrew/bin`에 심볼릭 링크하세요. -- **Health probe failed**: SSH 연결 가능 여부, PATH, 그리고 Baileys 로그인 상태(`openclaw status --json`)를 확인하세요. -- **Web Chat stuck**: 원격 호스트에서 gateway가 실행 중인지, 포워딩된 포트가 gateway WS 포트와 일치하는지 확인하세요. UI는 정상 WS 연결이 필요합니다. -- **Node IP가 127.0.0.1로 표시됨**: SSH 터널에서는 정상입니다. gateway가 실제 클라이언트 IP를 보게 하려면 **Transport**를 **Direct (ws/wss)**로 전환하세요. -- **Voice Wake**: 원격 모드에서는 트리거 문구가 자동으로 전달되므로 별도의 전달기가 필요 없습니다. +- **종료 코드 127 / 찾을 수 없음**: `openclaw`가 비로그인 셸의 PATH에 없습니다. `/etc/paths`나 셸 rc에 추가하거나 `/usr/local/bin`/`/opt/homebrew/bin`에 심볼릭 링크하세요. +- **상태 프로브 실패**: SSH 연결 가능 여부, PATH, Baileys 로그인 상태(`openclaw status --json`)를 확인하세요. +- **웹 채팅 멈춤**: 원격 호스트에서 Gateway가 실행 중인지, 전달된 포트가 Gateway WS 포트와 일치하는지 확인하세요. UI에는 정상적인 WS 연결이 필요합니다. +- **노드 IP가 127.0.0.1로 표시됨**: SSH 터널에서는 예상되는 동작입니다. Gateway가 실제 클라이언트 IP를 보게 하려면 **전송**을 **직접 연결(ws/wss)**로 전환하세요. +- **대시보드는 작동하지만 Mac 기능이 오프라인임**: 앱의 운영자/제어 연결은 정상이나 동반 노드 연결이 연결되지 않았거나 명령 표면이 누락되었다는 뜻입니다. 메뉴 막대의 기기 섹션을 열고 Mac이 `paired · disconnected` 상태인지 확인하세요. `wss://*.ts.net` Tailscale Serve 엔드포인트의 경우 앱은 인증서 교체 후 오래된 레거시 TLS 리프 핀을 감지하고, macOS가 새 인증서를 신뢰하면 오래된 핀을 지운 뒤 자동으로 다시 시도합니다. 인증서가 시스템에서 신뢰되지 않거나 호스트가 Tailscale Serve 이름이 아닌 경우 인증서를 검토하거나 **SSH를 통한 원격**으로 전환하세요. +- **음성 깨우기**: 원격 모드에서는 트리거 문구가 자동으로 전달되며, 별도의 전달자가 필요하지 않습니다. ## 알림 소리 -스크립트에서 `openclaw`와 `node.invoke`를 사용해 알림별로 소리를 선택하세요. 예: +`openclaw` 및 `node.invoke`를 사용하는 스크립트에서 알림별로 소리를 선택하세요. 예: ```bash openclaw nodes notify --node --title "Ping" --body "Remote gateway ready" --sound Glass ``` -앱에는 더 이상 전역 “기본 소리” 토글이 없습니다. 호출자가 요청별로 소리(또는 없음)를 선택합니다. +앱에는 더 이상 전역 “기본 소리” 토글이 없습니다. 호출자는 요청별로 소리를 선택하거나 선택하지 않습니다. ## 관련 항목 diff --git a/docs/ko/providers/deepseek.md b/docs/ko/providers/deepseek.md index bce4f332c..929f2f917 100644 --- a/docs/ko/providers/deepseek.md +++ b/docs/ko/providers/deepseek.md @@ -1,23 +1,23 @@ --- read_when: - - OpenClaw에서 DeepSeek를 사용하려고 합니다 - - API 키 환경 변수 또는 CLI 인증 선택 항목이 필요합니다 + - OpenClaw에서 DeepSeek를 사용하려는 경우 + - API 키 환경 변수 또는 CLI 인증 선택이 필요합니다 summary: DeepSeek 설정(인증 + 모델 선택) title: DeepSeek x-i18n: - generated_at: "2026-04-30T06:46:30Z" + generated_at: "2026-04-30T16:29:11Z" model: gpt-5.5 provider: openai - source_hash: e84d989a7cba8d259779ac02293718050ce51efe6ce2bdbfacb9e22bbfd294ef + source_hash: 6fbc7bd4de14000eaa5c42b17eb8c9312321ed02ac1667e60774ead3f1749eb4 source_path: providers/deepseek.md workflow: 16 --- -[DeepSeek](https://www.deepseek.com)는 OpenAI 호환 API와 함께 강력한 AI 모델을 제공합니다. +[DeepSeek](https://www.deepseek.com)는 OpenAI 호환 API를 갖춘 강력한 AI 모델을 제공합니다. | 속성 | 값 | | -------- | -------------------------- | -| Provider | `deepseek` | +| 제공자 | `deepseek` | | 인증 | `DEEPSEEK_API_KEY` | | API | OpenAI 호환 | | 기본 URL | `https://api.deepseek.com` | @@ -33,7 +33,7 @@ x-i18n: openclaw onboard --auth-choice deepseek-api-key ``` - 그러면 API 키를 입력하라는 메시지가 표시되고 `deepseek/deepseek-v4-flash`가 기본 모델로 설정됩니다. + 그러면 API 키 입력을 요청하고 `deepseek/deepseek-v4-flash`를 기본 모델로 설정합니다. @@ -42,7 +42,7 @@ x-i18n: ``` 실행 중인 Gateway 없이 번들된 정적 카탈로그를 확인하려면 - 다음을 사용합니다. + 다음을 사용하세요. ```bash openclaw models list --all --provider deepseek @@ -53,7 +53,7 @@ x-i18n: - 스크립트 기반 또는 헤드리스 설치의 경우 모든 플래그를 직접 전달합니다. + 스크립트 또는 헤드리스 설치의 경우 모든 플래그를 직접 전달하세요. ```bash openclaw onboard --non-interactive \ @@ -68,54 +68,41 @@ x-i18n: -Gateway가 데몬(launchd/systemd)으로 실행되는 경우 `DEEPSEEK_API_KEY`가 -해당 프로세스에서 사용 가능해야 합니다(예: `~/.openclaw/.env` 또는 +Gateway가 데몬(launchd/systemd)으로 실행되는 경우 `DEEPSEEK_API_KEY`를 +해당 프로세스에서 사용할 수 있는지 확인하세요(예: `~/.openclaw/.env` 또는 `env.shellEnv`를 통해). -## 기본 제공 카탈로그 +## 내장 카탈로그 -| 모델 ref | 이름 | 입력 | 컨텍스트 | 최대 출력 | 참고 | +| 모델 참조 | 이름 | 입력 | 컨텍스트 | 최대 출력 | 참고 | | ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ | -| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 기본 모델; V4 thinking 지원 표면 | -| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | V4 thinking 지원 표면 | -| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 non-thinking 표면 | -| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | reasoning 활성화 V3.2 표면 | +| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 기본 모델; V4 사고 가능 표면 | +| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | V4 사고 가능 표면 | +| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 비사고 표면 | +| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 추론 활성화 V3.2 표면 | -V4 모델은 DeepSeek의 `thinking` 제어를 지원합니다. OpenClaw는 도구 -호출이 포함된 thinking 세션이 계속될 수 있도록 후속 턴에서 -DeepSeek `reasoning_content`도 재생합니다. +V4 모델은 DeepSeek의 `thinking` 제어를 지원합니다. OpenClaw는 후속 턴에서 +DeepSeek `reasoning_content`도 재생하므로 도구 호출이 포함된 사고 세션을 +계속할 수 있습니다. +DeepSeek V4 모델에서 DeepSeek의 최대 `reasoning_effort`를 요청하려면 +`/think xhigh` 또는 `/think max`를 사용하세요. -## Thinking 및 도구 +## 사고와 도구 -DeepSeek V4 thinking 세션에는 대부분의 OpenAI 호환 제공자보다 더 엄격한 -재생 계약이 있습니다. thinking이 활성화된 턴에서 도구를 사용한 후에는 DeepSeek가 -해당 턴에서 재생된 어시스턴트 메시지에 후속 요청의 -`reasoning_content`가 포함되기를 기대합니다. OpenClaw는 이를 -DeepSeek Plugin 내부에서 처리하므로 일반적인 다중 턴 도구 사용은 -`deepseek/deepseek-v4-flash` 및 `deepseek/deepseek-v4-pro`에서 작동합니다. +DeepSeek V4 사고 세션은 대부분의 OpenAI 호환 제공자보다 더 엄격한 재생 계약을 가집니다. 사고가 활성화된 턴에서 도구를 사용한 후에는 DeepSeek가 후속 요청에서 해당 턴의 재생된 어시스턴트 메시지에 `reasoning_content`가 포함되기를 기대합니다. OpenClaw는 DeepSeek Plugin 내부에서 이를 처리하므로 일반적인 멀티턴 도구 사용은 `deepseek/deepseek-v4-flash` 및 `deepseek/deepseek-v4-pro`에서 작동합니다. -기존 세션을 다른 OpenAI 호환 제공자에서 DeepSeek V4 모델로 전환하는 경우, -이전 어시스턴트 도구 호출 턴에는 네이티브 -DeepSeek `reasoning_content`가 없을 수 있습니다. OpenClaw는 DeepSeek V4 thinking 요청을 위해 재생된 -어시스턴트 메시지의 누락된 필드를 채워 제공자가 `/new` 없이도 -히스토리를 수락할 수 있게 합니다. +기존 세션을 다른 OpenAI 호환 제공자에서 DeepSeek V4 모델로 전환하면 이전 어시스턴트 도구 호출 턴에 네이티브 DeepSeek `reasoning_content`가 없을 수 있습니다. OpenClaw는 DeepSeek V4 사고 요청을 위해 재생된 어시스턴트 메시지의 누락된 필드를 채워 제공자가 `/new` 없이도 기록을 수락할 수 있게 합니다. -OpenClaw에서 thinking이 비활성화된 경우(UI **없음** 선택 포함), -OpenClaw는 DeepSeek `thinking: { type: "disabled" }`를 보내고 나가는 히스토리에서 재생된 -`reasoning_content`를 제거합니다. 이렇게 하면 thinking이 비활성화된 -세션이 non-thinking DeepSeek 경로에 유지됩니다. +OpenClaw에서 사고가 비활성화된 경우(UI **없음** 선택 포함), OpenClaw는 DeepSeek `thinking: { type: "disabled" }`를 보내고 나가는 기록에서 재생된 `reasoning_content`를 제거합니다. 이렇게 하면 사고 비활성화 세션이 비사고 DeepSeek 경로에 유지됩니다. -기본 빠른 경로에는 `deepseek/deepseek-v4-flash`를 사용합니다. 더 강력한 V4 모델을 원하고 -더 높은 비용이나 지연 시간을 감수할 수 있다면 -`deepseek/deepseek-v4-pro`를 사용합니다. +기본 빠른 경로에는 `deepseek/deepseek-v4-flash`를 사용하세요. 더 강력한 V4 모델을 원하고 더 높은 비용이나 지연 시간을 감수할 수 있다면 `deepseek/deepseek-v4-pro`를 사용하세요. ## 라이브 테스트 -직접 라이브 모델 스위트에는 최신 모델 세트의 DeepSeek V4가 포함되어 있습니다. -DeepSeek V4 직접 모델 검사만 실행하려면 다음을 사용합니다. +직접 라이브 모델 제품군에는 최신 모델 세트의 DeepSeek V4가 포함됩니다. DeepSeek V4 직접 모델 검사만 실행하려면 다음을 사용하세요. ```bash OPENCLAW_LIVE_PROVIDERS=deepseek \ @@ -123,10 +110,9 @@ OPENCLAW_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \ pnpm test:live src/agents/models.profiles.live.test.ts ``` -해당 라이브 검사는 두 V4 모델이 모두 완료될 수 있는지, 그리고 thinking/도구 -후속 턴이 DeepSeek에서 요구하는 재생 페이로드를 보존하는지 확인합니다. +이 라이브 검사는 두 V4 모델이 모두 완료할 수 있는지와 사고/도구 후속 턴이 DeepSeek에 필요한 재생 페이로드를 보존하는지 확인합니다. -## 구성 예시 +## 설정 예시 ```json5 { @@ -143,9 +129,9 @@ pnpm test:live src/agents/models.profiles.live.test.ts - 제공자, 모델 ref, 장애 조치 동작 선택. + 제공자, 모델 참조, 장애 조치 동작 선택. - 에이전트, 모델, 제공자의 전체 구성 참조. + 에이전트, 모델, 제공자에 대한 전체 구성 참조. diff --git a/docs/ko/providers/openai.md b/docs/ko/providers/openai.md index 1d77c1357..18e3dacc8 100644 --- a/docs/ko/providers/openai.md +++ b/docs/ko/providers/openai.md @@ -1,84 +1,84 @@ --- read_when: - - OpenClaw에서 OpenAI 모델을 사용하려고 합니다 + - OpenClaw에서 OpenAI 모델을 사용하려는 경우 - API 키 대신 Codex 구독 인증을 사용하려는 경우 - 더 엄격한 GPT-5 에이전트 실행 동작이 필요합니다 -summary: OpenClaw에서 API 키 또는 Codex 구독을 통해 OpenAI 사용 +summary: OpenClaw에서 API 키 또는 Codex 구독으로 OpenAI 사용하기 title: OpenAI x-i18n: - generated_at: "2026-04-30T06:47:50Z" + generated_at: "2026-04-30T16:29:36Z" model: gpt-5.5 provider: openai - source_hash: be0e2cd14990a53533c800cd8d305c9c50b0fa7131f6638e7b9d8dd9f2942fe8 + source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad source_path: providers/openai.md workflow: 16 --- -OpenAI는 GPT 모델용 개발자 API를 제공하며, Codex는 OpenAI의 Codex 클라이언트를 통해 ChatGPT 플랜 코딩 에이전트로도 사용할 수 있습니다. OpenClaw는 설정을 예측 가능하게 유지하기 위해 이러한 표면을 분리합니다. +OpenAI는 GPT 모델용 개발자 API를 제공하며, Codex는 OpenAI의 Codex 클라이언트를 통해 ChatGPT 플랜 코딩 에이전트로도 사용할 수 있습니다. OpenClaw는 구성이 예측 가능하게 유지되도록 이러한 표면을 분리합니다. -OpenClaw는 세 가지 OpenAI 계열 경로를 지원합니다. 모델 접두사가 제공자/인증 경로를 선택하며, 별도의 런타임 설정이 내장 에이전트 루프를 누가 실행할지 선택합니다. +OpenClaw는 세 가지 OpenAI 계열 경로를 지원합니다. 모델 접두사는 provider/auth 경로를 선택하고, 별도의 런타임 설정은 내장 에이전트 루프를 누가 실행할지 선택합니다. - **API 키** — 사용량 기반 과금이 적용되는 직접 OpenAI Platform 액세스(`openai/*` 모델) - **PI를 통한 Codex 구독** — 구독 액세스를 사용하는 ChatGPT/Codex 로그인(`openai-codex/*` 모델) -- **Codex 앱 서버 하네스** — 네이티브 Codex 앱 서버 실행(`openai/*` 모델 및 `agents.defaults.agentRuntime.id: "codex"`) +- **Codex 앱 서버 하니스** — 네이티브 Codex 앱 서버 실행(`openai/*` 모델 및 `agents.defaults.agentRuntime.id: "codex"`) OpenAI는 OpenClaw 같은 외부 도구와 워크플로에서 구독 OAuth 사용을 명시적으로 지원합니다. -제공자, 모델, 런타임, 채널은 서로 다른 계층입니다. 이러한 레이블이 뒤섞이고 있다면 설정을 변경하기 전에 [에이전트 런타임](/ko/concepts/agent-runtimes)을 읽어 보세요. +Provider, 모델, 런타임, 채널은 별개의 계층입니다. 이러한 레이블이 서로 섞이고 있다면 구성을 변경하기 전에 [에이전트 런타임](/ko/concepts/agent-runtimes)을 읽어 보세요. ## 빠른 선택 | 목표 | 사용 | 참고 | | --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | | 직접 API 키 과금 | `openai/gpt-5.5` | `OPENAI_API_KEY`를 설정하거나 OpenAI API 키 온보딩을 실행합니다. | -| ChatGPT/Codex 구독 인증을 사용하는 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth의 기본 PI 경로입니다. 구독 설정에서 첫 번째 선택으로 가장 좋습니다. | -| 네이티브 Codex 앱 서버 동작을 사용하는 GPT-5.5 | `openai/gpt-5.5` 및 `agentRuntime.id: "codex"` | 해당 모델 참조에 대해 Codex 앱 서버 하네스를 강제합니다. | -| 이미지 생성 또는 편집 | `openai/gpt-image-2` | `OPENAI_API_KEY` 또는 OpenAI Codex OAuth 중 하나로 작동합니다. | +| ChatGPT/Codex 구독 인증으로 GPT-5.5 사용 | `openai-codex/gpt-5.5` | Codex OAuth의 기본 PI 경로입니다. 구독 설정의 첫 선택으로 가장 좋습니다. | +| 네이티브 Codex 앱 서버 동작으로 GPT-5.5 사용 | `openai/gpt-5.5` 및 `agentRuntime.id: "codex"` | 해당 모델 참조에 대해 Codex 앱 서버 하니스를 강제합니다. | +| 이미지 생성 또는 편집 | `openai/gpt-image-2` | `OPENAI_API_KEY` 또는 OpenAI Codex OAuth 둘 다에서 작동합니다. | | 투명 배경 이미지 | `openai/gpt-image-1.5` | `outputFormat=png` 또는 `webp`와 `openai.background=transparent`를 사용합니다. | ## 이름 매핑 이름은 비슷하지만 서로 바꿔 쓸 수 없습니다. -| 보이는 이름 | 계층 | 의미 | +| 표시되는 이름 | 계층 | 의미 | | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | -| `openai` | 제공자 접두사 | 직접 OpenAI Platform API 경로입니다. | -| `openai-codex` | 제공자 접두사 | 일반 OpenClaw PI 러너를 통한 OpenAI Codex OAuth/구독 경로입니다. | -| `codex` Plugin | Plugin | 네이티브 Codex 앱 서버 런타임과 `/codex` 채팅 제어를 제공하는 번들 OpenClaw Plugin입니다. | -| `agentRuntime.id: codex` | 에이전트 런타임 | 내장 턴에 대해 네이티브 Codex 앱 서버 하네스를 강제합니다. | +| `openai` | Provider 접두사 | 직접 OpenAI Platform API 경로입니다. | +| `openai-codex` | Provider 접두사 | 일반 OpenClaw PI 러너를 통한 OpenAI Codex OAuth/구독 경로입니다. | +| `codex` plugin | Plugin | 네이티브 Codex 앱 서버 런타임과 `/codex` 채팅 제어를 제공하는 번들 OpenClaw Plugin입니다. | +| `agentRuntime.id: codex` | 에이전트 런타임 | 내장 턴에 대해 네이티브 Codex 앱 서버 하니스를 강제합니다. | | `/codex ...` | 채팅 명령 세트 | 대화에서 Codex 앱 서버 스레드를 바인딩/제어합니다. | -| `runtime: "acp", agentId: "codex"` | ACP 세션 경로 | ACP/acpx를 통해 Codex를 실행하는 명시적 폴백 경로입니다. | +| `runtime: "acp", agentId: "codex"` | ACP 세션 경로 | ACP/acpx를 통해 Codex를 실행하는 명시적 폴백 경로입니다. | -즉, 설정에는 의도적으로 `openai-codex/*`와 `codex` Plugin이 모두 포함될 수 있습니다. PI를 통한 Codex OAuth를 원하면서 네이티브 `/codex` 채팅 제어도 사용할 수 있게 하려는 경우 이는 유효합니다. `openclaw doctor`는 이 조합에 대해 의도한 것인지 확인할 수 있도록 경고하지만, 다시 작성하지는 않습니다. +즉, 구성에는 의도적으로 `openai-codex/*`와 `codex` Plugin이 모두 포함될 수 있습니다. PI를 통해 Codex OAuth를 사용하면서 네이티브 `/codex` 채팅 제어도 사용할 수 있게 하려는 경우 이는 유효합니다. `openclaw doctor`는 이 조합에 대해 경고하여 의도한 것인지 확인할 수 있게 하며, 이를 다시 작성하지는 않습니다. -GPT-5.5는 직접 OpenAI Platform API 키 액세스와 구독/OAuth 경로 모두에서 사용할 수 있습니다. 직접 `OPENAI_API_KEY` 트래픽에는 `openai/gpt-5.5`를, PI를 통한 Codex OAuth에는 `openai-codex/gpt-5.5`를, 네이티브 Codex 앱 서버 하네스에는 `agentRuntime.id: "codex"`와 함께 `openai/gpt-5.5`를 사용하세요. +GPT-5.5는 직접 OpenAI Platform API 키 액세스와 구독/OAuth 경로 모두를 통해 사용할 수 있습니다. 직접 `OPENAI_API_KEY` 트래픽에는 `openai/gpt-5.5`를, PI를 통한 Codex OAuth에는 `openai-codex/gpt-5.5`를, 네이티브 Codex 앱 서버 하니스에는 `agentRuntime.id: "codex"`와 함께 `openai/gpt-5.5`를 사용하세요. -OpenAI Plugin을 활성화하거나 `openai-codex/*` 모델을 선택해도 번들 Codex 앱 서버 Plugin은 활성화되지 않습니다. OpenClaw는 `agentRuntime.id: "codex"`로 네이티브 Codex 하네스를 명시적으로 선택하거나 레거시 `codex/*` 모델 참조를 사용할 때만 해당 Plugin을 활성화합니다. -번들 `codex` Plugin이 활성화되어 있지만 `openai-codex/*`가 여전히 PI를 통해 확인되는 경우, `openclaw doctor`는 경고하고 경로는 변경하지 않습니다. +OpenAI Plugin을 활성화하거나 `openai-codex/*` 모델을 선택해도 번들된 Codex 앱 서버 Plugin은 활성화되지 않습니다. OpenClaw는 `agentRuntime.id: "codex"`로 네이티브 Codex 하니스를 명시적으로 선택하거나 레거시 `codex/*` 모델 참조를 사용할 때만 해당 Plugin을 활성화합니다. +번들된 `codex` Plugin이 활성화되어 있지만 `openai-codex/*`가 여전히 PI를 통해 해석되는 경우, `openclaw doctor`는 경고하고 경로를 변경하지 않습니다. ## OpenClaw 기능 범위 -| OpenAI 기능 | OpenClaw 표면 | 상태 | +| OpenAI 기능 | OpenClaw 표면 | 상태 | | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | -| 채팅 / Responses | `openai/` 모델 제공자 | 예 | -| Codex 구독 모델 | `openai-codex/` 및 `openai-codex` OAuth | 예 | -| Codex 앱 서버 하네스 | `openai/` 및 `agentRuntime.id: codex` | 예 | -| 서버 측 웹 검색 | 네이티브 OpenAI Responses 도구 | 예, 웹 검색이 활성화되어 있고 제공자가 고정되지 않은 경우 | +| 채팅 / Responses | `openai/` 모델 provider | 예 | +| Codex 구독 모델 | `openai-codex/` 및 `openai-codex` OAuth | 예 | +| Codex 앱 서버 하니스 | `openai/` 및 `agentRuntime.id: codex` | 예 | +| 서버 측 웹 검색 | 네이티브 OpenAI Responses 도구 | 예, 웹 검색이 활성화되어 있고 provider가 고정되지 않은 경우 | | 이미지 | `image_generate` | 예 | | 동영상 | `video_generate` | 예 | | 텍스트 음성 변환 | `messages.tts.provider: "openai"` / `tts` | 예 | -| 배치 음성 텍스트 변환 | `tools.media.audio` / 미디어 이해 | 예 | +| 일괄 음성 텍스트 변환 | `tools.media.audio` / 미디어 이해 | 예 | | 스트리밍 음성 텍스트 변환 | Voice Call `streaming.provider: "openai"` | 예 | | 실시간 음성 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 예 | -| Embeddings | 메모리 임베딩 제공자 | 예 | +| 임베딩 | 메모리 임베딩 provider | 예 | -## 메모리 Embeddings +## 메모리 임베딩 -OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenAI 호환 임베딩 엔드포인트를 사용할 수 있습니다. +OpenClaw는 `memory_search` 인덱싱 및 쿼리 임베딩에 OpenAI 또는 OpenAI 호환 임베딩 엔드포인트를 사용할 수 있습니다. ```json5 { @@ -93,21 +93,21 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA } ``` -비대칭 임베딩 레이블이 필요한 OpenAI 호환 엔드포인트의 경우 `memorySearch` 아래에 `queryInputType`과 `documentInputType`을 설정합니다. OpenClaw는 이를 제공자별 `input_type` 요청 필드로 전달합니다. 쿼리 임베딩은 `queryInputType`을 사용하고, 인덱싱된 메모리 청크와 배치 인덱싱은 `documentInputType`을 사용합니다. 전체 예시는 [메모리 설정 참조](/ko/reference/memory-config#provider-specific-config)를 참고하세요. +비대칭 임베딩 레이블이 필요한 OpenAI 호환 엔드포인트의 경우 `memorySearch` 아래에 `queryInputType` 및 `documentInputType`을 설정하세요. OpenClaw는 이를 provider별 `input_type` 요청 필드로 전달합니다. 쿼리 임베딩은 `queryInputType`을 사용하고, 인덱싱된 메모리 청크와 일괄 인덱싱은 `documentInputType`을 사용합니다. 전체 예시는 [메모리 구성 참조](/ko/reference/memory-config#provider-specific-config)를 참고하세요. ## 시작하기 -선호하는 인증 방법을 선택하고 설정 단계를 따르세요. +선호하는 인증 방식을 선택하고 설정 단계를 따르세요. - - **권장 대상:** 직접 API 액세스와 사용량 기반 과금. + + **가장 적합한 경우:** 직접 API 액세스 및 사용량 기반 과금. - + [OpenAI Platform 대시보드](https://platform.openai.com/api-keys)에서 API 키를 만들거나 복사합니다. - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -118,7 +118,7 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -127,17 +127,17 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA ### 경로 요약 - | 모델 참조 | 런타임 설정 | 경로 | 인증 | - | ---------------------- | -------------------------------- | --------------------------- | ---------------- | - | `openai/gpt-5.5` | 생략 / `agentRuntime.id: "pi"` | 직접 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | 생략 / `agentRuntime.id: "pi"` | 직접 OpenAI Platform API | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 앱 서버 하네스 | Codex 앱 서버 | + | 모델 참조 | 런타임 구성 | 경로 | 인증 | + | ---------------------- | ----------------------------------- | -------------------------- | ---------------- | + | `openai/gpt-5.5` | 생략 / `agentRuntime.id: "pi"` | 직접 OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | 생략 / `agentRuntime.id: "pi"` | 직접 OpenAI Platform API | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 앱 서버 하니스 | Codex 앱 서버 | - `openai/*`는 Codex 앱 서버 하네스를 명시적으로 강제하지 않는 한 직접 OpenAI API 키 경로입니다. 기본 PI 러너를 통한 Codex OAuth에는 `openai-codex/*`를 사용하거나, 네이티브 Codex 앱 서버 실행에는 `agentRuntime.id: "codex"`와 함께 `openai/gpt-5.5`를 사용하세요. + `openai/*`는 Codex 앱 서버 하니스를 명시적으로 강제하지 않는 한 직접 OpenAI API 키 경로입니다. 기본 PI 러너를 통한 Codex OAuth에는 `openai-codex/*`를 사용하거나, 네이티브 Codex 앱 서버 실행에는 `agentRuntime.id: "codex"`와 함께 `openai/gpt-5.5`를 사용하세요. - ### 설정 예시 + ### 구성 예시 ```json5 { @@ -147,16 +147,16 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA ``` - OpenClaw는 `openai/gpt-5.3-codex-spark`를 노출하지 않습니다. 라이브 OpenAI API 요청은 해당 모델을 거부하며, 현재 Codex 카탈로그도 이를 노출하지 않습니다. + OpenClaw는 `openai/gpt-5.3-codex-spark`를 노출하지 않습니다. 실시간 OpenAI API 요청은 해당 모델을 거부하며, 현재 Codex 카탈로그도 이를 노출하지 않습니다. - - **권장 대상:** 별도의 API 키 대신 ChatGPT/Codex 구독 사용. Codex 클라우드는 ChatGPT 로그인이 필요합니다. + + **가장 적합한 경우:** 별도의 API 키 대신 ChatGPT/Codex 구독을 사용하는 경우. Codex 클라우드에는 ChatGPT 로그인이 필요합니다. - + ```bash openclaw onboard --auth-choice openai-codex ``` @@ -167,18 +167,18 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA openclaw models auth login --provider openai-codex ``` - 헤드리스 또는 콜백에 제약이 있는 설정에서는 localhost 브라우저 콜백 대신 ChatGPT 디바이스 코드 흐름으로 로그인하도록 `--device-code`를 추가합니다. + 헤드리스 또는 콜백이 어려운 설정의 경우, localhost 브라우저 콜백 대신 ChatGPT 디바이스 코드 흐름으로 로그인하려면 `--device-code`를 추가하세요. ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -187,21 +187,18 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA ### 경로 요약 - | 모델 참조 | 런타임 설정 | 경로 | 인증 | - |-----------|----------------|-------|------| + | 모델 참조 | 런타임 구성 | 경로 | 인증 | + |-----------|-------------|------|------| | `openai-codex/gpt-5.5` | 생략 / `runtime: "pi"` | PI를 통한 ChatGPT/Codex OAuth | Codex 로그인 | - | `openai-codex/gpt-5.5` | `runtime: "auto"` | Plugin이 `openai-codex`를 명시적으로 클레임하지 않는 한 여전히 PI | Codex 로그인 | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 앱 서버 하네스 | Codex 앱 서버 인증 | + | `openai-codex/gpt-5.4-mini` | 생략 / `runtime: "pi"` | PI를 통한 ChatGPT/Codex OAuth | Codex 로그인 | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | Plugin이 명시적으로 `openai-codex`를 클레임하지 않는 한 여전히 PI | Codex 로그인 | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex 앱 서버 하니스 | Codex 앱 서버 인증 | - 인증/프로필 명령에는 계속 `openai-codex` 제공자 ID를 사용하세요. `openai-codex/*` 모델 접두사도 Codex OAuth의 명시적 PI 경로입니다. 이는 번들 Codex 앱 서버 하네스를 선택하거나 자동 활성화하지 않습니다. + 인증/프로필 명령에는 계속 `openai-codex` provider ID를 사용하세요. `openai-codex/*` 모델 접두사도 Codex OAuth의 명시적 PI 경로입니다. 이는 번들된 Codex 앱 서버 하니스를 선택하거나 자동 활성화하지 않습니다. - - `openai-codex/gpt-5.4-mini`는 지원되는 Codex OAuth 경로가 아닙니다. OpenAI API 키와 함께 `openai/gpt-5.4-mini`를 사용하거나, Codex OAuth와 함께 `openai-codex/gpt-5.5`를 사용하세요. - - - ### 설정 예시 + ### 구성 예시 ```json5 { @@ -215,30 +212,31 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA ### 상태 표시기 - Chat `/status`는 현재 세션에서 활성화된 모델 런타임을 표시합니다. - 기본 PI 하네스는 `Runtime: OpenClaw Pi Default`로 표시됩니다. 번들된 Codex 앱 서버 하네스를 선택하면 `/status`는 - `Runtime: OpenAI Codex`를 표시합니다. 기존 세션은 기록된 하네스 id를 유지하므로, `agentRuntime`을 변경한 뒤 `/status`가 - 새 PI/Codex 선택을 반영하게 하려면 `/new` 또는 `/reset`을 사용하세요. + Chat `/status`는 현재 세션에 활성화된 모델 런타임을 표시합니다. + 기본 PI 하네스는 `Runtime: OpenClaw Pi Default`로 표시됩니다. 번들로 제공되는 + Codex app-server 하네스가 선택되면 `/status`는 + `Runtime: OpenAI Codex`를 표시합니다. 기존 세션은 기록된 하네스 id를 유지하므로, + `agentRuntime`을 변경한 뒤 `/status`에 새 PI/Codex 선택을 + 반영하려면 `/new` 또는 `/reset`을 사용하세요. ### Doctor 경고 - 번들된 `codex` Plugin이 활성화된 상태에서 이 탭의 - `openai-codex/*` 경로가 선택되어 있으면, `openclaw doctor`는 모델이 - 여전히 PI를 통해 확인된다고 경고합니다. 의도한 구독 인증 경로가 - 이것이라면 config를 변경하지 마세요. 네이티브 Codex - 앱 서버 실행을 원할 때만 `openai/` 및 - `agentRuntime.id: "codex"`로 전환하세요. + 이 탭의 `openai-codex/*` 경로가 선택된 상태에서 번들 `codex` + Plugin이 활성화되어 있으면, `openclaw doctor`는 모델이 + 여전히 PI를 통해 확인된다고 경고합니다. 이것이 의도한 구독 인증 경로라면 + 구성을 변경하지 마세요. 네이티브 Codex app-server 실행을 원할 때만 + `openai/`과 `agentRuntime.id: "codex"`로 전환하세요. - ### 컨텍스트 창 한도 + ### 컨텍스트 창 상한 - OpenClaw는 모델 메타데이터와 런타임 컨텍스트 한도를 별도의 값으로 취급합니다. + OpenClaw는 모델 메타데이터와 런타임 컨텍스트 상한을 별도 값으로 취급합니다. Codex OAuth를 통한 `openai-codex/gpt-5.5`의 경우: - 네이티브 `contextWindow`: `1000000` - - 기본 런타임 `contextTokens` 한도: `272000` + - 기본 런타임 `contextTokens` 상한: `272000` - 더 작은 기본 한도는 실제 사용에서 지연 시간과 품질 특성이 더 좋습니다. `contextTokens`로 재정의하세요. + 더 작은 기본 상한은 실제 사용에서 지연 시간과 품질 특성이 더 좋습니다. `contextTokens`로 재정의하세요. ```json5 { @@ -259,48 +257,48 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA ### 카탈로그 복구 OpenClaw는 `gpt-5.5`가 있을 때 업스트림 Codex 카탈로그 메타데이터를 - 사용합니다. 계정이 인증된 상태에서 라이브 Codex 검색이 - `openai-codex/gpt-5.5` 행을 누락하면, OpenClaw는 cron, 하위 에이전트, + 사용합니다. 계정이 인증된 상태에서 실시간 Codex 검색 결과에 + `openai-codex/gpt-5.5` 행이 누락되면, OpenClaw는 cron, 하위 에이전트, 구성된 기본 모델 실행이 `Unknown model`로 실패하지 않도록 해당 OAuth 모델 행을 합성합니다. -## 네이티브 Codex 앱 서버 인증 +## 네이티브 Codex app-server 인증 -네이티브 Codex 앱 서버 하네스는 `openai/*` 모델 참조와 +네이티브 Codex app-server 하네스는 `openai/*` 모델 참조와 `agentRuntime.id: "codex"`를 사용하지만, 인증은 여전히 계정 기반입니다. OpenClaw는 다음 순서로 인증을 선택합니다. 1. 에이전트에 바인딩된 명시적 OpenClaw `openai-codex` 인증 프로필. -2. 로컬 Codex CLI ChatGPT 로그인 같은 앱 서버의 기존 계정. -3. 로컬 stdio 앱 서버 실행에만 해당하며, 앱 서버가 계정이 없다고 보고하고 여전히 - OpenAI 인증이 필요할 때 `CODEX_API_KEY`, 그다음 +2. 로컬 Codex CLI ChatGPT 로그인 같은 app-server의 기존 계정. +3. 로컬 stdio app-server 실행의 경우에만, app-server가 계정이 없다고 보고하고 + 여전히 OpenAI 인증이 필요할 때 `CODEX_API_KEY`, 그다음 `OPENAI_API_KEY`. -즉, Gateway 프로세스에 직접 OpenAI 모델이나 임베딩을 위한 `OPENAI_API_KEY`가 +즉, Gateway 프로세스에 직접 OpenAI 모델 또는 임베딩용 `OPENAI_API_KEY`가 있다는 이유만으로 로컬 ChatGPT/Codex 구독 로그인이 대체되지는 않습니다. -환경 API 키 폴백은 로컬 stdio 무계정 경로에만 해당하며, WebSocket 앱 서버 -연결로 전송되지 않습니다. 구독 스타일 Codex 프로필이 선택되면 OpenClaw는 -스폰된 stdio 앱 서버 자식 프로세스에서 `CODEX_API_KEY`와 `OPENAI_API_KEY`도 -제외하고, 앱 서버 로그인 RPC를 통해 선택한 자격 증명을 보냅니다. +환경 API 키 폴백은 로컬 stdio 무계정 경로에만 해당하며, WebSocket app-server +연결로 전송되지 않습니다. 구독 방식 Codex 프로필이 선택되면 OpenClaw는 +생성된 stdio app-server 자식 프로세스에서 `CODEX_API_KEY`와 `OPENAI_API_KEY`도 +제외하고, 선택된 자격 증명을 app-server 로그인 RPC를 통해 전송합니다. ## 이미지 생성 -번들된 `openai` Plugin은 `image_generate` 도구를 통해 이미지 생성을 등록합니다. -동일한 `openai/gpt-image-2` 모델 참조를 통해 OpenAI API 키 이미지 생성과 Codex OAuth 이미지 -생성을 모두 지원합니다. +번들 `openai` Plugin은 `image_generate` 도구를 통해 이미지 생성을 등록합니다. +동일한 `openai/gpt-image-2` 모델 참조를 통해 OpenAI API 키 이미지 생성과 +Codex OAuth 이미지 생성을 모두 지원합니다. -| 기능 | OpenAI API 키 | Codex OAuth | +| 기능 | OpenAI API 키 | Codex OAuth | | ------------------------- | ---------------------------------- | ------------------------------------ | | 모델 참조 | `openai/gpt-image-2` | `openai/gpt-image-2` | | 인증 | `OPENAI_API_KEY` | OpenAI Codex OAuth 로그인 | -| 전송 | OpenAI Images API | Codex Responses 백엔드 | +| 전송 방식 | OpenAI Images API | Codex Responses 백엔드 | | 요청당 최대 이미지 수 | 4 | 4 | -| 편집 모드 | 활성화됨(참조 이미지 최대 5개) | 활성화됨(참조 이미지 최대 5개) | -| 크기 재정의 | 2K/4K 크기 포함 지원 | 2K/4K 크기 포함 지원 | -| 종횡비 / 해상도 | OpenAI Images API로 전달되지 않음 | 안전할 때 지원되는 크기로 매핑됨 | +| 편집 모드 | 활성화됨(참조 이미지 최대 5개) | 활성화됨(참조 이미지 최대 5개) | +| 크기 재정의 | 2K/4K 크기 포함 지원 | 2K/4K 크기 포함 지원 | +| 화면비 / 해상도 | OpenAI Images API로 전달되지 않음 | 안전할 때 지원되는 크기로 매핑됨 | ```json5 { @@ -313,20 +311,20 @@ OpenClaw는 `memory_search` 인덱싱과 쿼리 임베딩에 OpenAI 또는 OpenA ``` -공유 도구 매개변수, 제공자 선택, 장애 조치 동작은 [이미지 생성](/ko/tools/image-generation)을 참조하세요. +공유 도구 매개변수, 제공자 선택, 장애 조치 동작은 [이미지 생성](/ko/tools/image-generation)을 참고하세요. `gpt-image-2`는 OpenAI 텍스트-이미지 생성과 이미지 편집 모두의 기본값입니다. -`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`는 명시적 모델 재정의로 계속 사용할 수 있습니다. -투명 배경 PNG/WebP 출력에는 `openai/gpt-image-1.5`를 사용하세요. 현재 `gpt-image-2` API는 -`background: "transparent"`를 거부합니다. +`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`도 명시적 모델 재정의로 계속 +사용할 수 있습니다. 투명 배경 PNG/WebP 출력에는 `openai/gpt-image-1.5`를 +사용하세요. 현재 `gpt-image-2` API는 `background: "transparent"`를 거부합니다. 투명 배경 요청의 경우 에이전트는 `model: "openai/gpt-image-1.5"`, `outputFormat: "png"` 또는 `"webp"`, 그리고 `background: "transparent"`로 `image_generate`를 호출해야 합니다. 이전 `openai.background` 제공자 옵션도 계속 허용됩니다. OpenClaw는 기본 `openai/gpt-image-2` 투명 요청을 `gpt-image-1.5`로 다시 작성하여 공개 OpenAI 및 OpenAI Codex OAuth 경로도 -보호합니다. Azure 및 사용자 지정 OpenAI 호환 엔드포인트는 구성된 +보호합니다. Azure와 사용자 지정 OpenAI 호환 엔드포인트는 구성된 배포/모델 이름을 유지합니다. 동일한 설정은 헤드리스 CLI 실행에도 노출됩니다. @@ -340,20 +338,20 @@ openclaw infer image generate \ --json ``` -입력 파일에서 시작할 때는 `openclaw infer image edit`에도 동일한 +입력 파일에서 시작할 때는 `openclaw infer image edit`와 함께 동일한 `--output-format` 및 `--background` 플래그를 사용하세요. `--openai-background`는 OpenAI 전용 별칭으로 계속 사용할 수 있습니다. -Codex OAuth 설치에서는 동일한 `openai/gpt-image-2` 참조를 유지하세요. -`openai-codex` OAuth 프로필이 구성되어 있으면 OpenClaw는 저장된 OAuth -액세스 토큰을 확인하고 Codex Responses 백엔드를 통해 이미지 요청을 보냅니다. +Codex OAuth 설치의 경우 동일한 `openai/gpt-image-2` 참조를 유지하세요. +`openai-codex` OAuth 프로필이 구성되어 있으면, OpenClaw는 저장된 OAuth +액세스 토큰을 확인하고 Codex Responses 백엔드를 통해 이미지 요청을 전송합니다. 해당 요청에 대해 먼저 `OPENAI_API_KEY`를 시도하거나 API 키로 조용히 -폴백하지 않습니다. 대신 직접 OpenAI Images API 경로를 원할 때는 API 키, +폴백하지 않습니다. 직접 OpenAI Images API 경로를 원할 때는 API 키, 사용자 지정 기본 URL 또는 Azure 엔드포인트로 `models.providers.openai`를 명시적으로 구성하세요. -해당 사용자 지정 이미지 엔드포인트가 신뢰할 수 있는 LAN/사설 주소에 있다면 +해당 사용자 지정 이미지 엔드포인트가 신뢰할 수 있는 LAN/비공개 주소에 있는 경우, `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`도 설정하세요. OpenClaw는 -이 옵트인이 없으면 사설/내부 OpenAI 호환 이미지 엔드포인트를 계속 차단합니다. +이 옵트인이 없으면 비공개/내부 OpenAI 호환 이미지 엔드포인트를 계속 차단합니다. 생성: @@ -373,17 +371,17 @@ Codex OAuth 설치에서는 동일한 `openai/gpt-image-2` 참조를 유지하 /tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 ``` -## 동영상 생성 +## 비디오 생성 -번들된 `openai` Plugin은 `video_generate` 도구를 통해 동영상 생성을 등록합니다. +번들 `openai` Plugin은 `video_generate` 도구를 통해 비디오 생성을 등록합니다. -| 기능 | 값 | -| ------------- | --------------------------------------------------------------------------------- | -| 기본 모델 | `openai/sora-2` | -| 모드 | 텍스트-동영상, 이미지-동영상, 단일 동영상 편집 | -| 참조 입력 | 이미지 1개 또는 동영상 1개 | -| 크기 재정의 | 지원됨 | -| 기타 재정의 | `aspectRatio`, `resolution`, `audio`, `watermark`는 도구 경고와 함께 무시됨 | +| 기능 | 값 | +| ---------------- | --------------------------------------------------------------------------------- | +| 기본 모델 | `openai/sora-2` | +| 모드 | 텍스트-비디오, 이미지-비디오, 단일 비디오 편집 | +| 참조 입력 | 이미지 1개 또는 비디오 1개 | +| 크기 재정의 | 지원됨 | +| 기타 재정의 | `aspectRatio`, `resolution`, `audio`, `watermark`는 도구 경고와 함께 무시됨 | ```json5 { @@ -396,22 +394,22 @@ Codex OAuth 설치에서는 동일한 `openai/gpt-image-2` 참조를 유지하 ``` -공유 도구 매개변수, 제공자 선택, 장애 조치 동작은 [동영상 생성](/ko/tools/video-generation)을 참조하세요. +공유 도구 매개변수, 제공자 선택, 장애 조치 동작은 [비디오 생성](/ko/tools/video-generation)을 참고하세요. -## GPT-5 프롬프트 기여 +## GPT-5 프롬프트 기여 항목 -OpenClaw는 제공자 전반의 GPT-5 계열 실행을 위해 공유 GPT-5 프롬프트 기여를 추가합니다. 모델 id별로 적용되므로 `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` 및 기타 호환 GPT-5 참조는 동일한 오버레이를 받습니다. 이전 GPT-4.x 모델에는 적용되지 않습니다. +OpenClaw는 제공자 전반의 GPT-5 계열 실행에 대해 공유 GPT-5 프롬프트 기여 항목을 추가합니다. 모델 id에 따라 적용되므로 `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` 및 기타 호환 GPT-5 참조는 동일한 오버레이를 받습니다. 이전 GPT-4.x 모델에는 적용되지 않습니다. -번들된 네이티브 Codex 하네스는 Codex 앱 서버 개발자 지침을 통해 동일한 GPT-5 동작과 Heartbeat 오버레이를 사용하므로, `agentRuntime.id: "codex"`를 통해 강제된 `openai/gpt-5.x` 세션은 하네스 프롬프트의 나머지를 Codex가 소유하더라도 동일한 후속 처리와 선제적 Heartbeat 지침을 유지합니다. +번들 네이티브 Codex 하네스는 Codex app-server 개발자 지침을 통해 동일한 GPT-5 동작과 Heartbeat 오버레이를 사용하므로, `agentRuntime.id: "codex"`를 통해 강제된 `openai/gpt-5.x` 세션은 Codex가 나머지 하네스 프롬프트를 소유하더라도 동일한 후속 조치 및 능동적 Heartbeat 지침을 유지합니다. -GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 형태, 완료 확인, 검증을 위한 태그가 지정된 동작 계약을 추가합니다. 채널별 답장 및 무음 메시지 동작은 공유 OpenClaw 시스템 프롬프트와 아웃바운드 전달 정책에 남아 있습니다. GPT-5 지침은 일치하는 모델에 대해 항상 활성화됩니다. 친근한 상호작용 스타일 계층은 별도이며 구성할 수 있습니다. +GPT-5 기여 항목은 페르소나 지속성, 실행 안전성, 도구 규율, 출력 형식, 완료 확인, 검증에 대한 태그가 지정된 동작 계약을 추가합니다. 채널별 응답 및 무음 메시지 동작은 공유 OpenClaw 시스템 프롬프트와 발신 전달 정책에 남아 있습니다. GPT-5 지침은 일치하는 모델에 대해 항상 활성화됩니다. 친근한 상호작용 스타일 계층은 별도이며 구성할 수 있습니다. -| 값 | 효과 | -| ---------------------- | ----------------------------------------- | -| `"friendly"` (기본값) | 친근한 상호작용 스타일 계층 활성화 | -| `"on"` | `"friendly"`의 별칭 | -| `"off"` | 친근한 스타일 계층만 비활성화 | +| 값 | 효과 | +| ---------------------- | ------------------------------------------- | +| `"friendly"` (기본값) | 친근한 상호작용 스타일 계층 활성화 | +| `"on"` | `"friendly"`의 별칭 | +| `"off"` | 친근한 스타일 계층만 비활성화 | @@ -435,20 +433,20 @@ GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 -값은 런타임에서 대소문자를 구분하지 않으므로 `"Off"`와 `"off"`는 둘 다 친근한 스타일 계층을 비활성화합니다. +값은 런타임에 대소문자를 구분하지 않으므로, `"Off"`와 `"off"`는 모두 친근한 스타일 계층을 비활성화합니다. 공유 `agents.defaults.promptOverlays.gpt5.personality` 설정이 지정되지 않은 경우, 레거시 `plugins.entries.openai.config.personality`는 호환성 폴백으로 계속 읽힙니다. -## 음성 및 말하기 +## 음성 및 말소리 - 번들된 `openai` Plugin은 `messages.tts` 표면에 음성 합성을 등록합니다. + 번들 `openai` Plugin은 `messages.tts` 표면에 음성 합성을 등록합니다. - | 설정 | Config 경로 | 기본값 | + | 설정 | 구성 경로 | 기본값 | |---------|------------|---------| | 모델 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | 음성 | `messages.tts.providers.openai.voice` | `coral` | @@ -478,18 +476,17 @@ GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 - - 번들된 `openai` Plugin은 OpenClaw의 미디어 이해 전사 표면을 통해 - 배치 음성-텍스트를 등록합니다. + + 번들 `openai` Plugin은 OpenClaw의 미디어 이해 전사 표면을 통해 + 배치 음성-텍스트 변환을 등록합니다. - 기본 모델: `gpt-4o-transcribe` - 엔드포인트: OpenAI REST `/v1/audio/transcriptions` - 입력 경로: 멀티파트 오디오 파일 업로드 - - Discord 음성 채널 세그먼트와 채널 오디오 첨부 파일을 포함해 - 인바운드 오디오 전사가 `tools.media.audio`를 사용하는 모든 곳에서 - OpenClaw가 지원함 + - Discord 음성 채널 세그먼트 및 채널 오디오 첨부 파일을 포함하여 + 수신 오디오 전사가 `tools.media.audio`를 사용하는 모든 곳에서 OpenClaw가 지원함 - 인바운드 오디오 전사에 OpenAI를 강제로 사용하려면: + OpenAI를 인바운드 오디오 전사에 강제로 사용하려면: ```json5 { @@ -509,30 +506,30 @@ GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 } ``` - 언어 및 프롬프트 힌트는 공유 오디오 미디어 구성이나 호출별 전사 요청에서 제공되면 OpenAI로 전달됩니다. + 공유 오디오 미디어 구성이나 호출별 전사 요청에서 제공된 경우 언어와 프롬프트 힌트가 OpenAI로 전달됩니다. - - 번들된 `openai` Plugin은 Voice Call Plugin을 위한 실시간 전사를 등록합니다. + + 번들된 `openai` Plugin은 Voice Call Plugin용 실시간 전사를 등록합니다. | 설정 | 구성 경로 | 기본값 | |---------|------------|---------| | 모델 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | - | 언어 | `...openai.language` | (설정 안 됨) | - | 프롬프트 | `...openai.prompt` | (설정 안 됨) | + | 언어 | `...openai.language` | (설정되지 않음) | + | 프롬프트 | `...openai.prompt` | (설정되지 않음) | | 무음 지속 시간 | `...openai.silenceDurationMs` | `800` | | VAD 임계값 | `...openai.vadThreshold` | `0.5` | | API 키 | `...openai.apiKey` | `OPENAI_API_KEY`로 대체 | - G.711 u-law(`g711_ulaw` / `audio/pcmu`) 오디오를 사용하여 `wss://api.openai.com/v1/realtime`에 WebSocket 연결을 사용합니다. 이 스트리밍 provider는 Voice Call의 실시간 전사 경로용입니다. Discord 음성은 현재 짧은 세그먼트를 녹음하고 대신 배치 `tools.media.audio` 전사 경로를 사용합니다. + G.711 u-law(`g711_ulaw` / `audio/pcmu`) 오디오로 `wss://api.openai.com/v1/realtime`에 WebSocket 연결을 사용합니다. 이 스트리밍 제공자는 Voice Call의 실시간 전사 경로용입니다. Discord 음성은 현재 짧은 세그먼트를 녹음하고 대신 배치 `tools.media.audio` 전사 경로를 사용합니다. - - 번들된 `openai` Plugin은 Voice Call Plugin을 위한 실시간 음성을 등록합니다. + + 번들된 `openai` Plugin은 Voice Call Plugin용 실시간 음성을 등록합니다. | 설정 | 구성 경로 | 기본값 | |---------|------------|---------| @@ -544,11 +541,11 @@ GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 | API 키 | `...openai.apiKey` | `OPENAI_API_KEY`로 대체 | - 백엔드 실시간 브리지를 위해 `azureEndpoint` 및 `azureDeployment` 구성 키를 통한 Azure OpenAI를 지원합니다. 양방향 도구 호출을 지원합니다. G.711 u-law 오디오 형식을 사용합니다. + 백엔드 실시간 브리지용 `azureEndpoint` 및 `azureDeployment` 구성 키를 통해 Azure OpenAI를 지원합니다. 양방향 도구 호출을 지원합니다. G.711 u-law 오디오 형식을 사용합니다. - Control UI Talk는 Gateway에서 발급한 임시 클라이언트 시크릿과 OpenAI Realtime API에 대한 직접 브라우저 WebRTC SDP 교환을 사용하여 OpenAI 브라우저 실시간 세션을 사용합니다. Maintainer 라이브 검증은 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`로 사용할 수 있습니다. OpenAI 구간은 Node에서 클라이언트 시크릿을 발급하고, 가짜 마이크 미디어로 브라우저 SDP offer를 생성하고, 이를 OpenAI에 게시한 뒤, 시크릿을 로깅하지 않고 SDP answer를 적용합니다. + Control UI Talk는 Gateway에서 발급한 임시 클라이언트 시크릿과 OpenAI Realtime API에 대한 직접 브라우저 WebRTC SDP 교환으로 OpenAI 브라우저 실시간 세션을 사용합니다. 유지관리자 라이브 검증은 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`로 사용할 수 있습니다. OpenAI 구간은 Node에서 클라이언트 시크릿을 발급하고, 가짜 마이크 미디어로 브라우저 SDP 제안을 생성하며, 이를 OpenAI에 게시한 다음 시크릿을 로깅하지 않고 SDP 응답을 적용합니다. @@ -556,21 +553,21 @@ GPT-5 기여는 페르소나 지속성, 실행 안전성, 도구 규율, 출력 ## Azure OpenAI 엔드포인트 -번들된 `openai` provider는 기본 URL을 재정의하여 이미지 생성을 위해 Azure OpenAI 리소스를 대상으로 지정할 수 있습니다. 이미지 생성 경로에서 OpenClaw는 `models.providers.openai.baseUrl`의 Azure 호스트 이름을 감지하고 자동으로 Azure의 요청 형식으로 전환합니다. +번들된 `openai` 제공자는 기본 URL을 재정의해 이미지 생성을 Azure OpenAI 리소스로 보낼 수 있습니다. 이미지 생성 경로에서 OpenClaw는 `models.providers.openai.baseUrl`의 Azure 호스트 이름을 감지하고 자동으로 Azure의 요청 형식으로 전환합니다. -실시간 음성은 별도의 구성 경로(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)를 사용하며 `models.providers.openai.baseUrl`의 영향을 받지 않습니다. Azure 설정은 [음성 및 말하기](#voice-and-speech) 아래의 **실시간 음성** 아코디언을 참조하세요. +실시간 음성은 별도의 구성 경로(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)를 사용하며 `models.providers.openai.baseUrl`의 영향을 받지 않습니다. 해당 Azure 설정은 [음성과 스피치](#voice-and-speech) 아래 **실시간 음성** 아코디언을 참조하세요. -다음 경우 Azure OpenAI를 사용하세요. +다음과 같은 경우 Azure OpenAI를 사용하세요. - 이미 Azure OpenAI 구독, 할당량 또는 엔터프라이즈 계약이 있는 경우 -- Azure가 제공하는 지역 데이터 레지던시 또는 규정 준수 제어가 필요한 경우 +- Azure가 제공하는 지역별 데이터 상주 또는 규정 준수 제어가 필요한 경우 - 기존 Azure 테넌시 내부에 트래픽을 유지하려는 경우 ### 구성 -번들된 `openai` provider를 통한 Azure 이미지 생성의 경우 `models.providers.openai.baseUrl`이 Azure 리소스를 가리키도록 하고 `apiKey`를 Azure OpenAI 키(OpenAI Platform 키가 아님)로 설정하세요. +번들된 `openai` 제공자를 통해 Azure 이미지 생성을 사용하려면 `models.providers.openai.baseUrl`이 Azure 리소스를 가리키도록 하고 `apiKey`를 Azure OpenAI 키(OpenAI Platform 키가 아님)로 설정하세요. ```json5 { @@ -596,18 +593,18 @@ OpenClaw는 Azure 이미지 생성 경로에서 다음 Azure 호스트 접미사 - `Authorization: Bearer` 대신 `api-key` 헤더를 보냅니다. - 배포 범위 경로(`/openai/deployments/{deployment}/...`)를 사용합니다. - 각 요청에 `?api-version=...`을 추가합니다. -- Azure 이미지 생성 호출에 600초 기본 요청 제한 시간을 사용합니다. +- Azure 이미지 생성 호출에 600초 기본 요청 타임아웃을 사용합니다. 호출별 `timeoutMs` 값은 여전히 이 기본값을 재정의합니다. 다른 기본 URL(공개 OpenAI, OpenAI 호환 프록시)은 표준 OpenAI 이미지 요청 형식을 유지합니다. -`openai` provider의 이미지 생성 경로에 대한 Azure 라우팅은 OpenClaw 2026.4.22 이상이 필요합니다. 이전 버전은 모든 사용자 지정 `openai.baseUrl`을 공개 OpenAI 엔드포인트처럼 처리하며 Azure 이미지 배포에서는 실패합니다. +`openai` 제공자의 이미지 생성 경로에 대한 Azure 라우팅에는 OpenClaw 2026.4.22 이상이 필요합니다. 이전 버전은 모든 사용자 지정 `openai.baseUrl`을 공개 OpenAI 엔드포인트처럼 처리하며 Azure 이미지 배포에 대해 실패합니다. ### API 버전 -Azure 이미지 생성 경로에 대해 특정 Azure preview 또는 GA 버전을 고정하려면 `AZURE_OPENAI_API_VERSION`을 설정하세요. +Azure 이미지 생성 경로에 대해 특정 Azure 프리뷰 또는 GA 버전을 고정하려면 `AZURE_OPENAI_API_VERSION`을 설정하세요. ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" @@ -617,7 +614,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ### 모델 이름은 배포 이름입니다 -Azure OpenAI는 모델을 배포에 바인딩합니다. 번들된 `openai` provider를 통해 라우팅되는 Azure 이미지 생성 요청의 경우, OpenClaw의 `model` 필드는 공개 OpenAI 모델 ID가 아니라 Azure 포털에서 구성한 **Azure 배포 이름**이어야 합니다. +Azure OpenAI는 모델을 배포에 바인딩합니다. 번들된 `openai` 제공자를 통해 라우팅되는 Azure 이미지 생성 요청의 경우 OpenClaw의 `model` 필드는 공개 OpenAI 모델 ID가 아니라 Azure 포털에서 구성한 **Azure 배포 이름**이어야 합니다. `gpt-image-2`를 제공하는 `gpt-image-2-prod`라는 배포를 만드는 경우: @@ -625,37 +622,37 @@ Azure OpenAI는 모델을 배포에 바인딩합니다. 번들된 `openai` provi /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 ``` -동일한 배포 이름 규칙이 번들된 `openai` provider를 통해 라우팅되는 이미지 생성 호출에도 적용됩니다. +동일한 배포 이름 규칙은 번들된 `openai` 제공자를 통해 라우팅되는 이미지 생성 호출에도 적용됩니다. ### 지역별 사용 가능 여부 -Azure 이미지 생성은 현재 일부 지역에서만 사용할 수 있습니다(예: `eastus2`, `swedencentral`, `polandcentral`, `westus3`, `uaenorth`). 배포를 만들기 전에 Microsoft의 최신 지역 목록을 확인하고, 특정 모델이 해당 지역에서 제공되는지 확인하세요. +Azure 이미지 생성은 현재 일부 지역(예: `eastus2`, `swedencentral`, `polandcentral`, `westus3`, `uaenorth`)에서만 사용할 수 있습니다. 배포를 만들기 전에 Microsoft의 최신 지역 목록을 확인하고, 특정 모델이 해당 지역에서 제공되는지 확인하세요. ### 매개변수 차이 -Azure OpenAI와 공개 OpenAI는 항상 동일한 이미지 매개변수를 허용하지는 않습니다. Azure는 공개 OpenAI가 허용하는 옵션(예: `gpt-image-2`의 특정 `background` 값)을 거부하거나 특정 모델 버전에서만 노출할 수 있습니다. 이러한 차이는 OpenClaw가 아니라 Azure와 기본 모델에서 비롯됩니다. Azure 요청이 유효성 검사 오류로 실패하면 Azure 포털에서 특정 배포 및 API 버전이 지원하는 매개변수 집합을 확인하세요. +Azure OpenAI와 공개 OpenAI가 항상 동일한 이미지 매개변수를 허용하는 것은 아닙니다. Azure는 공개 OpenAI가 허용하는 옵션(예: `gpt-image-2`의 특정 `background` 값)을 거부하거나 특정 모델 버전에서만 노출할 수 있습니다. 이러한 차이는 OpenClaw가 아니라 Azure와 기반 모델에서 비롯됩니다. Azure 요청이 검증 오류로 실패하면 Azure 포털에서 특정 배포와 API 버전이 지원하는 매개변수 집합을 확인하세요. -Azure OpenAI는 네이티브 전송 및 호환 동작을 사용하지만 OpenClaw의 숨겨진 attribution 헤더는 받지 않습니다. [고급 구성](#advanced-configuration) 아래의 **네이티브와 OpenAI 호환 경로** 아코디언을 참조하세요. +Azure OpenAI는 네이티브 전송과 호환 동작을 사용하지만 OpenClaw의 숨겨진 기여 표시 헤더는 받지 않습니다. [고급 구성](#advanced-configuration) 아래 **네이티브 vs OpenAI 호환 라우트** 아코디언을 참조하세요. -Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 온보딩 흐름이나 전용 Azure provider 구성을 사용하세요. `openai.baseUrl`만으로는 Azure API/auth 형식을 적용하지 않습니다. 별도의 `azure-openai-responses/*` provider가 있습니다. 아래의 서버 측 Compaction 아코디언을 참조하세요. +Azure에서 이미지 생성을 넘어 채팅 또는 Responses 트래픽을 사용하려면 온보딩 플로우나 전용 Azure 제공자 구성을 사용하세요. `openai.baseUrl`만으로는 Azure API/인증 형식이 적용되지 않습니다. 별도의 `azure-openai-responses/*` 제공자가 있습니다. 아래의 서버 측 Compaction 아코디언을 참조하세요. ## 고급 구성 - - OpenClaw는 `openai/*`와 `openai-codex/*` 모두에 WebSocket 우선 및 SSE fallback(`"auto"`)을 사용합니다. + + OpenClaw는 `openai/*`와 `openai-codex/*` 모두에 WebSocket 우선, SSE 대체(`"auto"`)를 사용합니다. - `"auto"` 모드에서 OpenClaw는: - - SSE로 fallback하기 전에 초기 WebSocket 실패를 한 번 재시도합니다. - - 실패 후 WebSocket을 약 60초 동안 성능 저하 상태로 표시하고 cool-down 동안 SSE를 사용합니다. - - 재시도 및 재연결을 위해 안정적인 세션 및 turn ID 헤더를 첨부합니다. + `"auto"` 모드에서 OpenClaw는 다음을 수행합니다. + - SSE로 대체하기 전에 초기 WebSocket 실패를 한 번 재시도합니다. + - 실패 후 약 60초 동안 WebSocket을 저하 상태로 표시하고 쿨다운 동안 SSE를 사용합니다. + - 재시도와 재연결을 위해 안정적인 세션 및 턴 식별 헤더를 첨부합니다. - 전송 변형 전반에서 사용량 카운터(`input_tokens` / `prompt_tokens`)를 정규화합니다. | 값 | 동작 | |-------|----------| - | `"auto"` (기본값) | WebSocket 우선, SSE fallback | + | `"auto"` (기본값) | WebSocket 우선, SSE 대체 | | `"sse"` | SSE만 강제 | | `"websocket"` | WebSocket만 강제 | @@ -682,11 +679,11 @@ Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 - - OpenClaw는 첫 turn 지연 시간을 줄이기 위해 `openai/*` 및 `openai-codex/*`에 대해 기본적으로 WebSocket warm-up을 활성화합니다. + + OpenClaw는 첫 턴 지연 시간을 줄이기 위해 `openai/*` 및 `openai-codex/*`에 대해 기본적으로 WebSocket 워밍업을 활성화합니다. ```json5 - // Disable warm-up + // 워밍업 비활성화 { agents: { defaults: { @@ -702,13 +699,13 @@ Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 - - OpenClaw는 `openai/*` 및 `openai-codex/*`에 대해 공유 빠른 모드 토글을 노출합니다. + + OpenClaw는 `openai/*` 및 `openai-codex/*`용 공유 빠른 모드 토글을 노출합니다. - **채팅/UI:** `/fast status|on|off` - **구성:** `agents.defaults.models["/"].params.fastMode` - 활성화되면 OpenClaw는 빠른 모드를 OpenAI 우선 처리(`service_tier = "priority"`)에 매핑합니다. 기존 `service_tier` 값은 보존되며, 빠른 모드는 `reasoning` 또는 `text.verbosity`를 다시 쓰지 않습니다. + 활성화되면 OpenClaw는 빠른 모드를 OpenAI 우선순위 처리(`service_tier = "priority"`)에 매핑합니다. 기존 `service_tier` 값은 보존되며, 빠른 모드는 `reasoning` 또는 `text.verbosity`를 다시 작성하지 않습니다. ```json5 { @@ -728,8 +725,8 @@ Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 - - OpenAI의 API는 `service_tier`를 통해 우선 처리를 노출합니다. OpenClaw에서 모델별로 설정하세요. + + OpenAI의 API는 `service_tier`를 통해 우선순위 처리를 노출합니다. OpenClaw에서 모델별로 설정하세요. ```json5 { @@ -746,22 +743,22 @@ Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 지원되는 값: `auto`, `default`, `flex`, `priority`. - `serviceTier`는 네이티브 OpenAI 엔드포인트(`api.openai.com`) 및 네이티브 Codex 엔드포인트(`chatgpt.com/backend-api`)에만 전달됩니다. 두 provider 중 하나를 프록시를 통해 라우팅하는 경우 OpenClaw는 `service_tier`를 그대로 둡니다. + `serviceTier`는 네이티브 OpenAI 엔드포인트(`api.openai.com`)와 네이티브 Codex 엔드포인트(`chatgpt.com/backend-api`)에만 전달됩니다. 어느 제공자든 프록시를 통해 라우팅하면 OpenClaw는 `service_tier`를 그대로 둡니다. - - 직접 OpenAI Responses 모델(`api.openai.com`의 `openai/*`)의 경우 OpenAI Plugin의 Pi-harness 스트림 래퍼는 서버 측 Compaction을 자동 활성화합니다. + + 직접 OpenAI Responses 모델(`api.openai.com`의 `openai/*`)의 경우 OpenAI Plugin의 Pi 하니스 스트림 래퍼가 서버 측 Compaction을 자동으로 활성화합니다. - - `store: true`를 강제합니다(모델 호환성이 `supportsStore: false`를 설정한 경우 제외). - - `context_management: [{ type: "compaction", compact_threshold: ... }]`를 주입합니다. + - `store: true`를 강제합니다(모델 호환성이 `supportsStore: false`를 설정하지 않은 경우). + - `context_management: [{ type: "compaction", compact_threshold: ... }]`를 삽입합니다. - 기본 `compact_threshold`: `contextWindow`의 70%(사용할 수 없는 경우 `80000`) - 이는 내장 Pi harness 경로와 임베디드 실행에서 사용하는 OpenAI provider hook에 적용됩니다. 네이티브 Codex 앱 서버 harness는 Codex를 통해 자체 context를 관리하며 `agents.defaults.agentRuntime.id`로 별도로 구성됩니다. + 이는 기본 제공 Pi 하니스 경로와 임베디드 실행에서 사용하는 OpenAI 제공자 훅에 적용됩니다. 네이티브 Codex 앱 서버 하니스는 Codex를 통해 자체 컨텍스트를 관리하며 `agents.defaults.agentRuntime.id`로 별도로 구성됩니다. - + Azure OpenAI Responses와 같은 호환 엔드포인트에 유용합니다. ```json5 @@ -814,13 +811,13 @@ Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 - `responsesServerCompaction`은 `context_management` 주입만 제어합니다. 직접 OpenAI Responses 모델은 compat가 `supportsStore: false`를 설정하지 않는 한 여전히 `store: true`를 강제합니다. + `responsesServerCompaction`은 `context_management` 삽입만 제어합니다. 직접 OpenAI Responses 모델은 compat가 `supportsStore: false`를 설정하지 않는 한 여전히 `store: true`를 강제합니다. - - `openai/*`에서 실행되는 GPT-5 계열에 대해, OpenClaw는 더 엄격한 내장 실행 계약을 사용할 수 있습니다. + + `openai/*`의 GPT-5 계열 실행에서 OpenClaw는 더 엄격한 임베디드 실행 계약을 사용할 수 있습니다. ```json5 { @@ -832,36 +829,36 @@ Azure의 채팅 또는 Responses 트래픽(이미지 생성 외)에 대해서는 } ``` - `strict-agentic`을 사용하면 OpenClaw는 다음과 같이 동작합니다. - - 도구 작업을 사용할 수 있을 때 계획만 있는 턴을 더 이상 성공적인 진행으로 취급하지 않습니다. - - 즉시 실행하도록 유도하며 해당 턴을 재시도합니다. + `strict-agentic`을 사용하면 OpenClaw는 다음을 수행합니다. + - 도구 작업을 사용할 수 있을 때 계획만 있는 턴을 더 이상 성공적인 진행으로 간주하지 않습니다. + - 지금 행동하라는 방향 지시와 함께 턴을 다시 시도합니다. - 상당한 작업에 대해 `update_plan`을 자동으로 활성화합니다. - 모델이 행동하지 않고 계속 계획만 세우면 명시적인 차단 상태를 표시합니다. - OpenAI 및 Codex GPT-5 계열 실행에만 범위가 한정됩니다. 다른 제공자와 이전 모델 계열은 기본 동작을 유지합니다. + OpenAI 및 Codex GPT-5 계열 실행에만 범위가 지정됩니다. 다른 제공자와 이전 모델 계열은 기본 동작을 유지합니다. - OpenClaw는 직접 OpenAI, Codex, Azure OpenAI 엔드포인트를 일반 OpenAI 호환 `/v1` 프록시와 다르게 취급합니다. + OpenClaw는 직접 OpenAI, Codex, Azure OpenAI 엔드포인트를 일반 OpenAI 호환 `/v1` 프록시와 다르게 처리합니다. **네이티브 경로**(`openai/*`, Azure OpenAI): - - OpenAI `none` effort를 지원하는 모델에 대해서만 `reasoning: { effort: "none" }`을 유지합니다. - - `reasoning.effort: "none"`을 거부하는 모델이나 프록시에는 비활성화된 reasoning을 생략합니다. - - 도구 스키마는 기본적으로 strict 모드를 사용합니다. - - 검증된 네이티브 호스트에만 숨겨진 어트리뷰션 헤더를 첨부합니다. + - OpenAI `none` effort를 지원하는 모델에만 `reasoning: { effort: "none" }`을 유지합니다. + - `reasoning.effort: "none"`을 거부하는 모델이나 프록시에서는 비활성화된 추론을 생략합니다. + - 기본 도구 스키마를 엄격 모드로 설정합니다. + - 검증된 네이티브 호스트에만 숨겨진 귀속 헤더를 첨부합니다. - OpenAI 전용 요청 구성(`service_tier`, `store`, reasoning-compat, prompt-cache 힌트)을 유지합니다. **프록시/호환 경로:** - 더 느슨한 compat 동작을 사용합니다. - 네이티브가 아닌 `openai-completions` 페이로드에서 Completions `store`를 제거합니다. - - OpenAI 호환 Completions 프록시에 대해 고급 `params.extra_body`/`params.extraBody` 패스스루 JSON을 허용합니다. + - OpenAI 호환 Completions 프록시에 대한 고급 `params.extra_body`/`params.extraBody` 통과 JSON을 허용합니다. - vLLM 같은 OpenAI 호환 Completions 프록시에 대해 `params.chat_template_kwargs`를 허용합니다. - - strict 도구 스키마나 네이티브 전용 헤더를 강제하지 않습니다. + - 엄격한 도구 스키마나 네이티브 전용 헤더를 강제하지 않습니다. - Azure OpenAI는 네이티브 전송 및 compat 동작을 사용하지만 숨겨진 어트리뷰션 헤더는 받지 않습니다. + Azure OpenAI는 네이티브 전송과 compat 동작을 사용하지만 숨겨진 귀속 헤더는 받지 않습니다. diff --git a/docs/ko/reference/memory-config.md b/docs/ko/reference/memory-config.md index 262d3f397..f3b430917 100644 --- a/docs/ko/reference/memory-config.md +++ b/docs/ko/reference/memory-config.md @@ -5,64 +5,64 @@ read_when: - 하이브리드 검색, MMR 또는 시간적 감쇠를 조정하려는 경우 - 멀티모달 메모리 인덱싱을 활성화하려는 경우 sidebarTitle: Memory config -summary: 메모리 검색, 임베딩 제공자, QMD, 하이브리드 검색, 멀티모달 인덱싱을 위한 모든 구성 옵션 +summary: 메모리 검색, 임베딩 제공자, QMD, 하이브리드 검색, 멀티모달 인덱싱에 대한 모든 구성 옵션 title: 메모리 구성 참조 x-i18n: - generated_at: "2026-04-30T06:49:50Z" + generated_at: "2026-04-30T16:30:06Z" model: gpt-5.5 provider: openai - source_hash: fbb21d407f7ec9ef76e68c268138892b12568137735b723579703e535d34b195 + source_hash: 58b75751a19afb883fd7646cf5f71859f95bac468b2bfd8cc79db12ae892f70f source_path: reference/memory-config.md workflow: 16 --- -이 페이지는 OpenClaw 메모리 검색의 모든 구성 옵션을 나열합니다. 개념 개요는 다음을 참조하세요. +이 페이지는 OpenClaw 메모리 검색의 모든 구성 옵션을 나열합니다. 개념 개요는 다음을 참고하세요: - - 메모리 작동 방식. + + 메모리의 작동 방식입니다. - - 기본 SQLite 백엔드. + + 기본 SQLite 백엔드입니다. - - 로컬 우선 사이드카. + + 로컬 우선 사이드카입니다. - - 검색 파이프라인과 튜닝. + + 검색 파이프라인과 튜닝입니다. - - 대화형 세션용 메모리 하위 에이전트. + + 대화형 세션을 위한 메모리 하위 에이전트입니다. 별도로 명시되지 않는 한 모든 메모리 검색 설정은 `openclaw.json`의 `agents.defaults.memorySearch` 아래에 있습니다. -**active memory** 기능 토글과 하위 에이전트 구성을 찾는 경우, 이는 `memorySearch`가 아니라 `plugins.entries.active-memory` 아래에 있습니다. +**Active Memory** 기능 토글과 하위 에이전트 구성을 찾고 있다면, 해당 설정은 `memorySearch`가 아니라 `plugins.entries.active-memory` 아래에 있습니다. -Active memory는 두 단계 게이트 모델을 사용합니다. +Active Memory는 두 단계 게이트 모델을 사용합니다: -1. Plugin이 활성화되어 있고 현재 에이전트 ID를 대상으로 해야 합니다. -2. 요청이 적합한 대화형 지속 채팅 세션이어야 합니다. +1. Plugin이 활성화되어 있고 현재 에이전트 ID를 대상으로 해야 합니다 +2. 요청이 적합한 대화형 영구 채팅 세션이어야 합니다 -활성화 모델, Plugin 소유 구성, 대화 기록 지속성, 안전한 롤아웃 패턴은 [Active Memory](/ko/concepts/active-memory)를 참조하세요. +활성화 모델, Plugin 소유 구성, 대화 기록 영속성, 안전한 롤아웃 패턴은 [Active Memory](/ko/concepts/active-memory)를 참고하세요. --- -## Provider 선택 +## 제공자 선택 -| 키 | 유형 | 기본값 | 설명 | -| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | 자동 감지됨 | `bedrock`, `deepinfra`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` 같은 임베딩 어댑터 ID입니다. `api`가 이러한 어댑터 중 하나를 가리키는 구성된 `models.providers.`일 수도 있습니다 | -| `model` | `string` | provider 기본값 | 임베딩 모델 이름 | -| `fallback` | `string` | `"none"` | 기본 어댑터가 실패할 때 사용할 대체 어댑터 ID | -| `enabled` | `boolean` | `true` | 메모리 검색 활성화 또는 비활성화 | +| 키 | 유형 | 기본값 | 설명 | +| ---------- | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | 자동 감지 | `bedrock`, `deepinfra`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` 같은 임베딩 어댑터 ID입니다. `api`가 이러한 어댑터 중 하나를 가리키는 구성된 `models.providers.`일 수도 있습니다 | +| `model` | `string` | 제공자 기본값 | 임베딩 모델 이름입니다 | +| `fallback` | `string` | `"none"` | 기본 어댑터가 실패할 때 사용할 폴백 어댑터 ID입니다 | +| `enabled` | `boolean` | `true` | 메모리 검색을 활성화하거나 비활성화합니다 | ### 자동 감지 순서 -`provider`가 설정되지 않은 경우 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다. +`provider`가 설정되지 않은 경우 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다: @@ -93,9 +93,9 @@ Active memory는 두 단계 게이트 모델을 사용합니다. `ollama`는 지원되지만 자동 감지되지 않습니다(명시적으로 설정하세요). -### 사용자 지정 provider ID +### 사용자 지정 제공자 ID -`memorySearch.provider`는 사용자 지정 `models.providers.` 항목을 가리킬 수 있습니다. OpenClaw는 임베딩 어댑터에 대해 해당 provider의 `api` 소유자를 확인하면서도 엔드포인트, 인증, 모델 접두사 처리를 위해 사용자 지정 provider ID를 유지합니다. 이를 통해 멀티 GPU 또는 멀티 호스트 설정에서 메모리 임베딩을 특정 로컬 엔드포인트 전용으로 사용할 수 있습니다. +`memorySearch.provider`는 사용자 지정 `models.providers.` 항목을 가리킬 수 있습니다. OpenClaw는 임베딩 어댑터에 대해 해당 제공자의 `api` 소유자를 확인하면서, 엔드포인트, 인증, 모델 접두사 처리를 위해 사용자 지정 제공자 ID를 보존합니다. 이를 통해 다중 GPU 또는 다중 호스트 설정에서 메모리 임베딩을 특정 로컬 엔드포인트 전용으로 사용할 수 있습니다: ```json5 { @@ -124,14 +124,14 @@ Active memory는 두 단계 게이트 모델을 사용합니다. 원격 임베딩에는 API 키가 필요합니다. Bedrock은 대신 AWS SDK 기본 자격 증명 체인을 사용합니다(인스턴스 역할, SSO, 액세스 키). -| Provider | 환경 변수 | 구성 키 | +| 제공자 | 환경 변수 | 구성 키 | | -------------- | -------------------------------------------------- | ----------------------------------- | -| Bedrock | AWS 자격 증명 체인 | API 키 필요 없음 | +| Bedrock | AWS 자격 증명 체인 | API 키가 필요하지 않음 | | DeepInfra | `DEEPINFRA_API_KEY` | `models.providers.deepinfra.apiKey` | | Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | 기기 로그인을 통한 인증 프로필 | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | 기기 로그인을 통한 인증 프로필 | | Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Ollama | `OLLAMA_API_KEY` (자리표시자) | -- | +| Ollama | `OLLAMA_API_KEY` (플레이스홀더) | -- | | OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | | Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | @@ -143,16 +143,16 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 ## 원격 엔드포인트 구성 -사용자 지정 OpenAI 호환 엔드포인트 또는 provider 기본값 재정의용: +사용자 지정 OpenAI 호환 엔드포인트 또는 제공자 기본값 재정의에 사용합니다: - 사용자 지정 API 기본 URL. + 사용자 지정 API 기본 URL입니다. - API 키 재정의. + API 키를 재정의합니다. - 추가 HTTP 헤더(provider 기본값과 병합됨). + 추가 HTTP 헤더입니다(제공자 기본값과 병합됨). ```json5 @@ -174,28 +174,28 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 --- -## Provider별 구성 +## 제공자별 구성 - | 키 | 유형 | 기본값 | 설명 | - | ---------------------- | -------- | ---------------------- | ----------------------------------------- | - | `model` | `string` | `gemini-embedding-001` | `gemini-embedding-2-preview`도 지원 | - | `outputDimensionality` | `number` | `3072` | Embedding 2의 경우: 768, 1536 또는 3072 | + | 키 | 유형 | 기본값 | 설명 | + | ---------------------- | -------- | ---------------------- | ------------------------------------------ | + | `model` | `string` | `gemini-embedding-001` | `gemini-embedding-2-preview`도 지원합니다 | + | `outputDimensionality` | `number` | `3072` | Embedding 2의 경우: 768, 1536 또는 3072 | 모델 또는 `outputDimensionality`를 변경하면 자동 전체 재색인이 트리거됩니다. - - OpenAI 호환 임베딩 엔드포인트는 provider별 `input_type` 요청 필드를 사용할 수 있습니다. 이는 쿼리 및 문서 임베딩에 서로 다른 라벨이 필요한 비대칭 임베딩 모델에 유용합니다. + + OpenAI 호환 임베딩 엔드포인트는 제공자별 `input_type` 요청 필드를 사용할 수 있습니다. 이는 쿼리와 문서 임베딩에 서로 다른 레이블이 필요한 비대칭 임베딩 모델에 유용합니다. - | 키 | 유형 | 기본값 | 설명 | - | ------------------- | -------- | --------------- | ------------------------------------------------------- | - | `inputType` | `string` | 설정되지 않음 | 쿼리 및 문서 임베딩에 공유되는 `input_type` | - | `queryInputType` | `string` | 설정되지 않음 | 쿼리 시점 `input_type`; `inputType`을 재정의 | - | `documentInputType` | `string` | 설정되지 않음 | 색인/문서 `input_type`; `inputType`을 재정의 | + | 키 | 유형 | 기본값 | 설명 | + | ------------------- | -------- | ------- | ------------------------------------------------------- | + | `inputType` | `string` | 설정되지 않음 | 쿼리 및 문서 임베딩에 공유되는 `input_type`입니다 | + | `queryInputType` | `string` | 설정되지 않음 | 쿼리 시점의 `input_type`입니다. `inputType`을 재정의합니다 | + | `documentInputType` | `string` | 설정되지 않음 | 색인/문서 `input_type`입니다. `inputType`을 재정의합니다 | ```json5 { @@ -216,11 +216,11 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 } ``` - 이러한 값을 변경하면 provider 배치 색인의 임베딩 캐시 ID에 영향을 주며, 업스트림 모델이 라벨을 다르게 처리하는 경우 메모리 재색인을 이어서 수행해야 합니다. + 이러한 값을 변경하면 제공자 배치 색인에 대한 임베딩 캐시 ID에 영향을 주며, 업스트림 모델이 레이블을 다르게 처리하는 경우 메모리 재색인을 이어서 수행해야 합니다. - Bedrock은 AWS SDK 기본 자격 증명 체인을 사용하므로 API 키가 필요 없습니다. OpenClaw가 Bedrock 지원 인스턴스 역할이 있는 EC2에서 실행되는 경우 provider와 모델만 설정하면 됩니다. + Bedrock은 AWS SDK 기본 자격 증명 체인을 사용하므로 API 키가 필요하지 않습니다. OpenClaw가 Bedrock이 활성화된 인스턴스 역할로 EC2에서 실행되는 경우 제공자와 모델만 설정하면 됩니다: ```json5 { @@ -235,29 +235,29 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 } ``` - | 키 | 유형 | 기본값 | 설명 | - | ---------------------- | -------- | ------------------------------ | ----------------------------- | - | `model` | `string` | `amazon.titan-embed-text-v2:0` | 모든 Bedrock 임베딩 모델 ID | - | `outputDimensionality` | `number` | 모델 기본값 | Titan V2의 경우: 256, 512 또는 1024 | + | 키 | 유형 | 기본값 | 설명 | + | ---------------------- | -------- | ------------------------------ | ------------------------------- | + | `model` | `string` | `amazon.titan-embed-text-v2:0` | 모든 Bedrock 임베딩 모델 ID | + | `outputDimensionality` | `number` | 모델 기본값 | Titan V2의 경우: 256, 512 또는 1024 | **지원되는 모델**(제품군 감지 및 차원 기본값 포함): - | 모델 ID | Provider | 기본 차원 | 구성 가능한 차원 | - | ------------------------------------------ | ---------- | --------- | --------------------- | - | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | - | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | - | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | - | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | - | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | - | `cohere.embed-english-v3` | Cohere | 1024 | -- | - | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | - | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | - | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | - | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | + | 모델 ID | 제공자 | 기본 차원 | 구성 가능한 차원 | + | ------------------------------------------ | ---------- | ------------ | -------------------- | + | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | + | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | + | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | + | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | + | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | + | `cohere.embed-english-v3` | Cohere | 1024 | -- | + | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | + | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | + | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | + | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | 처리량 접미사가 붙은 변형(예: `amazon.titan-embed-text-v1:2:8k`)은 기본 모델의 구성을 상속합니다. - **인증:** Bedrock 인증은 표준 AWS SDK 자격 증명 확인 순서를 사용합니다. + **인증:** Bedrock 인증은 표준 AWS SDK 자격 증명 확인 순서를 사용합니다: 1. 환경 변수(`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. SSO 토큰 캐시 @@ -265,9 +265,9 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 4. 공유 자격 증명 및 구성 파일 5. ECS 또는 EC2 메타데이터 자격 증명 - 리전은 `AWS_REGION`, `AWS_DEFAULT_REGION`, `amazon-bedrock` provider `baseUrl`에서 확인되거나 기본값으로 `us-east-1`을 사용합니다. + 리전은 `AWS_REGION`, `AWS_DEFAULT_REGION`, `amazon-bedrock` 제공자 `baseUrl`에서 확인되거나 기본값인 `us-east-1`을 사용합니다. - **IAM 권한:** IAM 역할 또는 사용자에게 다음이 필요합니다. + **IAM 권한:** IAM 역할 또는 사용자에게 다음이 필요합니다: ```json { @@ -277,40 +277,40 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 } ``` - 최소 권한 원칙을 적용하려면 `InvokeModel` 범위를 특정 모델로 제한하세요. + 최소 권한 원칙을 적용하려면 `InvokeModel`의 범위를 특정 모델로 제한하세요: ``` arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 ``` - - | 키 | 유형 | 기본값 | 설명 | - | --------------------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `local.modelPath` | `string` | 자동 다운로드 | GGUF 모델 파일 경로 | - | `local.modelCacheDir` | `string` | node-llama-cpp 기본값 | 다운로드한 모델의 캐시 디렉터리 | - | `local.contextSize` | `number \| "auto"` | `4096` | 임베딩 컨텍스트의 컨텍스트 창 크기입니다. 4096은 일반적인 청크(128-512 토큰)를 처리하면서 비가중치 VRAM을 제한합니다. 제약이 있는 호스트에서는 1024-2048로 낮추세요. `"auto"`는 모델의 학습된 최대값을 사용합니다. 8B+ 모델에는 권장되지 않습니다(Qwen3-Embedding-8B: 40,960 토큰 → 약 32GB VRAM, 4096에서는 약 8.8GB). | + + | 키 | 유형 | 기본값 | 설명 | + | --------------------- | ------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `local.modelPath` | `string` | 자동 다운로드됨 | GGUF 모델 파일 경로 | + | `local.modelCacheDir` | `string` | node-llama-cpp 기본값 | 다운로드된 모델의 캐시 디렉터리 | + | `local.contextSize` | `number \| "auto"` | `4096` | 임베딩 컨텍스트의 컨텍스트 창 크기입니다. 4096은 일반적인 청크(128~512 토큰)를 감당하면서 비가중치 VRAM을 제한합니다. 제약이 있는 호스트에서는 1024~2048로 낮추세요. `"auto"`는 모델의 학습된 최대값을 사용합니다. 8B+ 모델에는 권장되지 않습니다(Qwen3-Embedding-8B: 40,960 토큰 → 약 32GB VRAM, 4096에서는 약 8.8GB). | - 기본 모델: `embeddinggemma-300m-qat-Q8_0.gguf`(약 0.6GB, 자동 다운로드). 네이티브 빌드가 필요합니다: `pnpm approve-builds` 후 `pnpm rebuild node-llama-cpp`. + 기본 모델: `embeddinggemma-300m-qat-Q8_0.gguf`(약 0.6GB, 자동 다운로드됨). 패키징된 설치는 `provider: "local"`이 구성된 경우 관리형 Plugin 런타임 의존성을 통해 네이티브 `node-llama-cpp` 런타임을 복구합니다. 소스 체크아웃에는 여전히 네이티브 빌드 승인이 필요합니다: `pnpm approve-builds` 후 `pnpm rebuild node-llama-cpp`. - Gateway가 사용하는 것과 동일한 공급자 경로를 확인하려면 독립 실행형 CLI를 사용하세요: + Gateway가 사용하는 동일한 공급자 경로를 확인하려면 독립 실행형 CLI를 사용하세요: ```bash openclaw memory status --deep --agent main openclaw memory index --force --agent main ``` - `provider`가 `auto`이면 `local.modelPath`가 기존 로컬 파일을 가리킬 때만 `local`이 선택됩니다. `hf:` 및 HTTP(S) 모델 참조는 `provider: "local"`로 명시적으로 계속 사용할 수 있지만, 모델이 디스크에서 사용 가능해지기 전에는 `auto`가 local을 선택하게 만들지 않습니다. + `provider`가 `auto`이면 `local.modelPath`가 기존 로컬 파일을 가리킬 때만 `local`이 선택됩니다. `hf:` 및 HTTP(S) 모델 참조는 `provider: "local"`로 명시적으로 계속 사용할 수 있지만, 모델이 디스크에서 사용 가능해지기 전에는 `auto`가 local을 선택하게 하지 않습니다. -### 인라인 임베딩 타임아웃 +### 인라인 임베딩 제한 시간 - 메모리 색인 중 인라인 임베딩 배치의 타임아웃을 재정의합니다. + 메모리 인덱싱 중 인라인 임베딩 배치의 제한 시간을 재정의합니다. -설정하지 않으면 공급자 기본값을 사용합니다. `local`, `ollama`, `lmstudio` 같은 로컬/자체 호스팅 공급자는 600초이고, 호스팅 공급자는 120초입니다. 로컬 CPU 기반 임베딩 배치가 정상적으로 동작하지만 느릴 때 이 값을 늘리세요. +설정하지 않으면 공급자 기본값이 사용됩니다. `local`, `ollama`, `lmstudio` 같은 로컬/자체 호스팅 공급자는 600초이고, 호스팅 공급자는 120초입니다. 로컬 CPU 기반 임베딩 배치가 정상적으로 동작하지만 느릴 때 이 값을 늘리세요. --- @@ -319,27 +319,27 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 모두 `memorySearch.query.hybrid` 아래에 있습니다: -| 키 | 유형 | 기본값 | 설명 | -| --------------------- | --------- | ------ | --------------------------------- | +| 키 | 유형 | 기본값 | 설명 | +| --------------------- | --------- | ------ | ---------------------------- | | `enabled` | `boolean` | `true` | 하이브리드 BM25 + 벡터 검색 활성화 | -| `vectorWeight` | `number` | `0.7` | 벡터 점수 가중치(0-1) | -| `textWeight` | `number` | `0.3` | BM25 점수 가중치(0-1) | -| `candidateMultiplier` | `number` | `4` | 후보 풀 크기 배수 | +| `vectorWeight` | `number` | `0.7` | 벡터 점수의 가중치(0-1) | +| `textWeight` | `number` | `0.3` | BM25 점수의 가중치(0-1) | +| `candidateMultiplier` | `number` | `4` | 후보 풀 크기 배율 | - - | 키 | 유형 | 기본값 | 설명 | - | ------------- | --------- | ------- | ------------------------------- | - | `mmr.enabled` | `boolean` | `false` | MMR 재순위 지정 활성화 | + + | 키 | 유형 | 기본값 | 설명 | + | ------------- | --------- | ------- | ---------------------------- | + | `mmr.enabled` | `boolean` | `false` | MMR 재순위 지정 활성화 | | `mmr.lambda` | `number` | `0.7` | 0 = 최대 다양성, 1 = 최대 관련성 | - - | 키 | 유형 | 기본값 | 설명 | - | ---------------------------- | --------- | ------ | -------------------- | - | `temporalDecay.enabled` | `boolean` | `false` | 최신성 부스트 활성화 | + + | 키 | 유형 | 기본값 | 설명 | + | ---------------------------- | --------- | ------ | ----------------------- | + | `temporalDecay.enabled` | `boolean` | `false` | 최신성 부스트 활성화 | | `temporalDecay.halfLifeDays` | `number` | `30` | N일마다 점수가 절반으로 감소 | - 상시 참조 파일(`MEMORY.md`, `memory/`의 날짜 없는 파일)은 절대 감쇠되지 않습니다. + Evergreen 파일(`MEMORY.md`, `memory/`의 날짜가 없는 파일)은 절대 감쇠되지 않습니다. @@ -369,9 +369,9 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 ## 추가 메모리 경로 -| 키 | 유형 | 설명 | -| ------------ | ---------- | ---------------------------- | -| `extraPaths` | `string[]` | 색인할 추가 디렉터리 또는 파일 | +| 키 | 유형 | 설명 | +| ------------ | ---------- | --------------------------------- | +| `extraPaths` | `string[]` | 인덱싱할 추가 디렉터리 또는 파일 | ```json5 { @@ -385,24 +385,24 @@ Codex OAuth는 채팅/완성에만 적용되며 임베딩 요청을 충족하지 } ``` -경로는 절대 경로이거나 작업공간 기준 상대 경로일 수 있습니다. 디렉터리는 `.md` 파일을 찾기 위해 재귀적으로 스캔됩니다. 심볼릭 링크 처리는 활성 백엔드에 따라 달라집니다. 내장 엔진은 심볼릭 링크를 무시하지만, QMD는 기본 QMD 스캐너 동작을 따릅니다. +경로는 절대 경로 또는 작업 영역 기준 상대 경로일 수 있습니다. 디렉터리는 `.md` 파일을 찾기 위해 재귀적으로 스캔됩니다. 심볼릭 링크 처리는 활성 백엔드에 따라 달라집니다. 내장 엔진은 심볼릭 링크를 무시하지만, QMD는 기본 QMD 스캐너 동작을 따릅니다. -에이전트 범위의 교차 에이전트 트랜스크립트 검색에는 `memory.qmd.paths` 대신 `agents.list[].memorySearch.qmd.extraCollections`를 사용하세요. 이러한 추가 컬렉션은 동일한 `{ path, name, pattern? }` 형태를 따르지만 에이전트별로 병합되며, 경로가 현재 작업공간 외부를 가리킬 때 명시적인 공유 이름을 보존할 수 있습니다. 동일하게 해석된 경로가 `memory.qmd.paths`와 `memorySearch.qmd.extraCollections` 모두에 나타나면 QMD는 첫 번째 항목을 유지하고 중복 항목을 건너뜁니다. +에이전트 범위의 교차 에이전트 transcript 검색에는 `memory.qmd.paths` 대신 `agents.list[].memorySearch.qmd.extraCollections`를 사용하세요. 이러한 추가 컬렉션은 동일한 `{ path, name, pattern? }` 형태를 따르지만, 에이전트별로 병합되며 경로가 현재 작업 영역 밖을 가리킬 때 명시적인 공유 이름을 보존할 수 있습니다. 동일하게 해석된 경로가 `memory.qmd.paths`와 `memorySearch.qmd.extraCollections`에 모두 나타나면 QMD는 첫 번째 항목을 유지하고 중복 항목을 건너뜁니다. --- -## 멀티모달 메모리 (Gemini) +## 멀티모달 메모리(Gemini) -Gemini Embedding 2를 사용해 Markdown과 함께 이미지와 오디오를 색인합니다: +Gemini Embedding 2를 사용해 Markdown과 함께 이미지 및 오디오를 인덱싱합니다: -| 키 | 유형 | 기본값 | 설명 | -| ------------------------- | ---------- | ---------- | -------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | 멀티모달 색인 활성화 | +| 키 | 유형 | 기본값 | 설명 | +| ------------------------- | ---------- | ---------- | ------------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | 멀티모달 인덱싱 활성화 | | `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` 또는 `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | 색인할 최대 파일 크기 | +| `multimodal.maxFileBytes` | `number` | `10000000` | 인덱싱할 최대 파일 크기 | -`extraPaths`의 파일에만 적용됩니다. 기본 메모리 루트는 Markdown 전용으로 유지됩니다. `gemini-embedding-2-preview`가 필요합니다. `fallback`은 반드시 `"none"`이어야 합니다. +`extraPaths`의 파일에만 적용됩니다. 기본 메모리 루트는 Markdown 전용으로 유지됩니다. `gemini-embedding-2-preview`가 필요합니다. `fallback`은 `"none"`이어야 합니다. 지원 형식: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`(이미지); `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac`(오디오). @@ -411,29 +411,29 @@ Gemini Embedding 2를 사용해 Markdown과 함께 이미지와 오디오를 색 ## 임베딩 캐시 -| 키 | 유형 | 기본값 | 설명 | -| ------------------ | --------- | ------- | ------------------------------------ | -| `cache.enabled` | `boolean` | `false` | 청크 임베딩을 SQLite에 캐시합니다 | -| `cache.maxEntries` | `number` | `50000` | 최대 캐시된 임베딩 수 | +| 키 | 유형 | 기본값 | 설명 | +| ------------------ | --------- | ------- | ---------------------------------- | +| `cache.enabled` | `boolean` | `false` | SQLite에 청크 임베딩 캐시 | +| `cache.maxEntries` | `number` | `50000` | 캐시된 임베딩의 최대 개수 | -재인덱싱 또는 트랜스크립트 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하지 않도록 방지합니다. +재인덱싱 또는 transcript 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하지 않도록 합니다. --- ## 배치 인덱싱 -| 키 | 유형 | 기본값 | 설명 | -| ----------------------------- | --------- | ------ | ----------------------- | -| `remote.nonBatchConcurrency` | `number` | `4` | 병렬 인라인 임베딩 | -| `remote.batch.enabled` | `boolean` | `false` | 배치 임베딩 API 활성화 | -| `remote.batch.concurrency` | `number` | `2` | 병렬 배치 작업 | -| `remote.batch.wait` | `boolean` | `true` | 배치 완료 대기 | -| `remote.batch.pollIntervalMs` | `number` | -- | 폴링 간격 | -| `remote.batch.timeoutMinutes` | `number` | -- | 배치 제한 시간 | +| 키 | 유형 | 기본값 | 설명 | +| ----------------------------- | --------- | ------ | -------------------------- | +| `remote.nonBatchConcurrency` | `number` | `4` | 병렬 인라인 임베딩 | +| `remote.batch.enabled` | `boolean` | `false` | 배치 임베딩 API 활성화 | +| `remote.batch.concurrency` | `number` | `2` | 병렬 배치 작업 | +| `remote.batch.wait` | `boolean` | `true` | 배치 완료 대기 | +| `remote.batch.pollIntervalMs` | `number` | -- | 폴링 간격 | +| `remote.batch.timeoutMinutes` | `number` | -- | 배치 제한 시간 | `openai`, `gemini`, `voyage`에서 사용할 수 있습니다. OpenAI 배치는 일반적으로 대규모 백필에 가장 빠르고 저렴합니다. -`remote.nonBatchConcurrency`는 제공자 배치 API가 활성화되지 않았을 때 로컬/자체 호스팅 제공자와 호스팅 제공자가 사용하는 인라인 임베딩 호출을 제어합니다. Ollama는 더 작은 로컬 호스트에 과부하를 주지 않도록 비배치 인덱싱의 기본값이 `1`입니다. 더 큰 머신에서는 더 높은 값을 설정하세요. +`remote.nonBatchConcurrency`는 로컬/자체 호스팅 공급자와, 공급자 배치 API가 활성화되지 않은 경우 호스팅 공급자가 사용하는 인라인 임베딩 호출을 제어합니다. Ollama는 더 작은 로컬 호스트에 과부하가 걸리지 않도록 비배치 인덱싱의 기본값이 `1`입니다. 더 큰 머신에서는 더 높은 값을 설정하세요. 이는 인라인 임베딩 호출의 제한 시간을 제어하는 `sync.embeddingBatchTimeoutSeconds`와는 별개입니다. @@ -441,29 +441,29 @@ Gemini Embedding 2를 사용해 Markdown과 함께 이미지와 오디오를 색 ## 세션 메모리 검색(실험적) -세션 트랜스크립트를 인덱싱하고 `memory_search`를 통해 노출합니다. +세션 transcript를 인덱싱하고 `memory_search`를 통해 노출합니다: -| 키 | 유형 | 기본값 | 설명 | -| ----------------------------- | ---------- | ------------ | ----------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | 세션 인덱싱 활성화 | -| `sources` | `string[]` | `["memory"]` | 트랜스크립트를 포함하려면 `"sessions"` 추가 | -| `sync.sessions.deltaBytes` | `number` | `100000` | 재인덱싱을 위한 바이트 임계값 | -| `sync.sessions.deltaMessages` | `number` | `50` | 재인덱싱을 위한 메시지 임계값 | +| 키 | 유형 | 기본값 | 설명 | +| ----------------------------- | ---------- | ------------ | ------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | 세션 인덱싱 활성화 | +| `sources` | `string[]` | `["memory"]` | transcript를 포함하려면 `"sessions"` 추가 | +| `sync.sessions.deltaBytes` | `number` | `100000` | 재인덱싱을 위한 바이트 임계값 | +| `sync.sessions.deltaMessages` | `number` | `50` | 재인덱싱을 위한 메시지 임계값 | -세션 인덱싱은 옵트인이며 비동기적으로 실행됩니다. 결과가 약간 오래되었을 수 있습니다. 세션 로그는 디스크에 저장되므로 파일시스템 접근을 신뢰 경계로 취급하세요. +세션 인덱싱은 옵트인 방식이며 비동기적으로 실행됩니다. 결과가 약간 오래되었을 수 있습니다. 세션 로그는 디스크에 있으므로 파일 시스템 접근을 신뢰 경계로 취급하세요. --- ## SQLite 벡터 가속(sqlite-vec) -| 키 | 유형 | 기본값 | 설명 | -| ---------------------------- | --------- | ------- | --------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | 벡터 쿼리에 sqlite-vec 사용 | -| `store.vector.extensionPath` | `string` | bundled | sqlite-vec 경로 재정의 | +| 키 | 유형 | 기본값 | 설명 | +| ---------------------------- | --------- | ------ | --------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | 벡터 쿼리에 sqlite-vec 사용 | +| `store.vector.extensionPath` | `string` | 번들됨 | sqlite-vec 경로 재정의 | -sqlite-vec를 사용할 수 없는 경우 OpenClaw는 자동으로 프로세스 내 코사인 유사도로 대체합니다. +sqlite-vec를 사용할 수 없으면 OpenClaw는 자동으로 프로세스 내 코사인 유사도로 대체합니다. --- @@ -478,51 +478,51 @@ sqlite-vec를 사용할 수 없는 경우 OpenClaw는 자동으로 프로세스 ## QMD 백엔드 구성 -활성화하려면 `memory.backend = "qmd"`를 설정하세요. 모든 QMD 설정은 `memory.qmd` 아래에 있습니다. +활성화하려면 `memory.backend = "qmd"`를 설정하세요. 모든 QMD 설정은 `memory.qmd` 아래에 있습니다: -| 키 | 유형 | 기본값 | 설명 | -| ------------------------ | --------- | -------- | ---------------------------------------------------------------------------------------- | -| `command` | `string` | `qmd` | QMD 실행 파일 경로; 서비스 `PATH`가 셸과 다를 때 절대 경로를 설정하세요 | -| `searchMode` | `string` | `search` | 검색 명령: `search`, `vsearch`, `query` | -| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md` 자동 인덱싱 | -| `paths[]` | `array` | -- | 추가 경로: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | 세션 트랜스크립트 인덱싱 | -| `sessions.retentionDays` | `number` | -- | 트랜스크립트 보존 기간 | -| `sessions.exportDir` | `string` | -- | 내보내기 디렉터리 | +| 키 | 유형 | 기본값 | 설명 | +| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- | +| `command` | `string` | `qmd` | QMD 실행 파일 경로; 서비스 `PATH`가 셸과 다를 때 절대 경로를 설정하세요 | +| `searchMode` | `string` | `search` | 검색 명령: `search`, `vsearch`, `query` | +| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md`를 자동 색인 | +| `paths[]` | `array` | -- | 추가 경로: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | 세션 transcript 색인 | +| `sessions.retentionDays` | `number` | -- | Transcript 보존 기간 | +| `sessions.exportDir` | `string` | -- | 내보내기 디렉터리 | -`searchMode: "search"`는 어휘/BM25 전용입니다. OpenClaw는 해당 모드에서 `memory status --deep` 중을 포함해 semantic vector 준비 상태 프로브나 QMD embedding 유지 관리를 실행하지 않습니다. `vsearch`와 `query`는 계속 QMD vector 준비 상태와 embeddings를 요구합니다. +`searchMode: "search"`는 lexical/BM25 전용입니다. OpenClaw는 `memory status --deep` 중을 포함하여 이 모드에 대해 semantic vector readiness probe나 QMD embedding maintenance를 실행하지 않습니다. `vsearch`와 `query`는 계속 QMD vector readiness와 embedding을 필요로 합니다. -OpenClaw는 현재 QMD 컬렉션과 MCP query 형태를 선호하지만, 필요할 때 호환되는 컬렉션 패턴 플래그와 이전 MCP tool 이름을 시도하여 이전 QMD 릴리스도 계속 작동하게 합니다. QMD가 여러 컬렉션 필터 지원을 알리면 동일 소스 컬렉션은 하나의 QMD 프로세스로 검색됩니다. 이전 QMD 빌드는 컬렉션별 호환성 경로를 유지합니다. 동일 소스란 durable memory 컬렉션은 함께 그룹화되고, session transcript 컬렉션은 별도 그룹으로 남아 source diversification이 계속 두 입력을 모두 갖는다는 뜻입니다. +OpenClaw는 현재 QMD collection 및 MCP query 형태를 선호하지만, 필요할 때 호환 가능한 collection pattern flag와 이전 MCP tool 이름을 시도하여 오래된 QMD 릴리스도 계속 작동하게 합니다. QMD가 여러 collection filter 지원을 알리면 동일 소스 collection은 하나의 QMD 프로세스로 검색됩니다. 이전 QMD 빌드는 collection별 호환성 경로를 유지합니다. 동일 소스란 durable memory collection은 함께 그룹화되고, session transcript collection은 별도 그룹으로 유지되어 source diversification이 여전히 두 입력을 모두 갖는다는 뜻입니다. -QMD 모델 override는 OpenClaw config가 아니라 QMD 쪽에 유지됩니다. QMD의 모델을 전역으로 override해야 한다면 Gateway 런타임 환경에서 `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, `QMD_GENERATE_MODEL` 같은 환경 변수를 설정하세요. +QMD 모델 override는 OpenClaw config가 아니라 QMD 쪽에 유지됩니다. QMD의 모델을 전역으로 override해야 한다면 gateway runtime environment에서 `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, `QMD_GENERATE_MODEL` 같은 environment variable을 설정하세요. - - | 키 | 타입 | 기본값 | 설명 | + + | 키 | 유형 | 기본값 | 설명 | | ------------------------- | --------- | ------- | ------------------------------------- | - | `update.interval` | `string` | `5m` | 새로 고침 간격 | - | `update.debounceMs` | `number` | `15000` | 파일 변경 debounce | - | `update.onBoot` | `boolean` | `true` | 장기 실행 QMD manager가 열릴 때 새로 고침하며, opt-in 시작 새로 고침도 제어 | - | `update.startup` | `string` | `off` | 선택적 Gateway 시작 새로 고침: `off`, `idle`, 또는 `immediate` | + | `update.interval` | `string` | `5m` | 새로 고침 간격 | + | `update.debounceMs` | `number` | `15000` | 파일 변경 debounce | + | `update.onBoot` | `boolean` | `true` | 장기 실행 QMD manager가 열릴 때 새로 고침; opt-in startup refresh도 gate 처리 | + | `update.startup` | `string` | `off` | 선택적 gateway 시작 새로 고침: `off`, `idle`, 또는 `immediate` | | `update.startupDelayMs` | `number` | `120000` | `startup: "idle"` 새로 고침이 실행되기 전 지연 | | `update.waitForBootSync` | `boolean` | `false` | 초기 새로 고침이 완료될 때까지 manager 열기를 차단 | - | `update.embedInterval` | `string` | -- | 별도 embed 주기 | - | `update.commandTimeoutMs` | `number` | -- | QMD 명령 timeout | - | `update.updateTimeoutMs` | `number` | -- | QMD update 작업 timeout | - | `update.embedTimeoutMs` | `number` | -- | QMD embed 작업 timeout | + | `update.embedInterval` | `string` | -- | 별도 embed 주기 | + | `update.commandTimeoutMs` | `number` | -- | QMD 명령 timeout | + | `update.updateTimeoutMs` | `number` | -- | QMD update 작업 timeout | + | `update.embedTimeoutMs` | `number` | -- | QMD embed 작업 timeout | - - | 키 | 타입 | 기본값 | 설명 | + + | 키 | 유형 | 기본값 | 설명 | | ------------------------- | -------- | ------- | -------------------------- | - | `limits.maxResults` | `number` | `6` | 최대 검색 결과 | - | `limits.maxSnippetChars` | `number` | -- | snippet 길이 제한 | + | `limits.maxResults` | `number` | `6` | 최대 검색 결과 | + | `limits.maxSnippetChars` | `number` | -- | snippet 길이 제한 | | `limits.maxInjectedChars` | `number` | -- | 전체 injected 문자 수 제한 | - | `limits.timeoutMs` | `number` | `4000` | 검색 timeout | + | `limits.timeoutMs` | `number` | `4000` | 검색 timeout | - - 어떤 session이 QMD 검색 결과를 받을 수 있는지 제어합니다. [`session.sendPolicy`](/ko/gateway/config-agents#session)와 동일한 schema입니다. + + 어떤 세션이 QMD 검색 결과를 받을 수 있는지 제어합니다. [`session.sendPolicy`](/ko/gateway/config-agents#session)와 같은 schema입니다. ```json5 { @@ -537,24 +537,24 @@ QMD 모델 override는 OpenClaw config가 아니라 QMD 쪽에 유지됩니다. } ``` - 제공되는 기본값은 direct 및 channel session을 허용하면서도 group은 계속 거부합니다. + 제공되는 기본값은 direct 및 channel 세션을 허용하면서 group은 계속 거부합니다. 기본값은 DM 전용입니다. `match.keyPrefix`는 정규화된 session key와 일치하고, `match.rawKeyPrefix`는 `agent::`를 포함한 raw key와 일치합니다. - + `memory.citations`는 모든 backend에 적용됩니다. - | 값 | 동작 | + | 값 | 동작 | | ---------------- | --------------------------------------------------- | - | `auto` (기본값) | snippet에 `Source: ` footer 포함 | - | `on` | 항상 footer 포함 | - | `off` | footer 생략(경로는 내부적으로 agent에 계속 전달됨) | + | `auto` (기본값) | snippet에 `Source: ` footer 포함 | + | `on` | 항상 footer 포함 | + | `off` | footer 생략(path는 내부적으로 agent에 계속 전달됨) | -QMD boot refresh는 Gateway 시작 중 one-shot subprocess 경로를 사용합니다. 장기 실행 QMD manager는 memory search가 대화형 사용을 위해 열렸을 때 여전히 일반 file watcher와 interval timer를 소유합니다. +QMD boot refresh는 gateway 시작 중 one-shot subprocess 경로를 사용합니다. 장기 실행 QMD manager는 memory search가 interactive 사용을 위해 열릴 때 여전히 일반 file watcher와 interval timer를 소유합니다. ### 전체 QMD 예시 @@ -583,17 +583,17 @@ QMD boot refresh는 Gateway 시작 중 one-shot subprocess 경로를 사용합 Dreaming은 `agents.defaults.memorySearch` 아래가 아니라 `plugins.entries.memory-core.config.dreaming` 아래에서 구성됩니다. -Dreaming은 하나의 예약된 sweep으로 실행되며 내부 light/deep/REM phase를 구현 세부 사항으로 사용합니다. +Dreaming은 하나의 scheduled sweep으로 실행되며 내부 light/deep/REM phase를 구현 세부 사항으로 사용합니다. -개념적 동작과 slash command는 [Dreaming](/ko/concepts/dreaming)을 참조하세요. +개념적 동작과 slash command는 [Dreaming](/ko/concepts/dreaming)을 참고하세요. ### 사용자 설정 -| 키 | 타입 | 기본값 | 설명 | -| ----------- | --------- | ------------- | ------------------------------------------------ | -| `enabled` | `boolean` | `false` | Dreaming 전체 활성화 또는 비활성화 | -| `frequency` | `string` | `0 3 * * *` | 전체 Dreaming sweep의 선택적 Cron 주기 | -| `model` | `string` | 기본 모델 | 선택적 Dream Diary subagent 모델 override | +| 키 | 유형 | 기본값 | 설명 | +| ----------- | --------- | ------------- | ------------------------------------------------- | +| `enabled` | `boolean` | `false` | dreaming을 완전히 활성화하거나 비활성화 | +| `frequency` | `string` | `0 3 * * *` | 전체 dreaming sweep에 대한 선택적 cron 주기 | +| `model` | `string` | 기본 모델 | 선택적 Dream Diary subagent 모델 override | ### 예시 @@ -622,14 +622,14 @@ Dreaming은 하나의 예약된 sweep으로 실행되며 내부 light/deep/REM p - Dreaming은 machine state를 `memory/.dreams/`에 씁니다. - Dreaming은 사람이 읽을 수 있는 narrative output을 `DREAMS.md`(또는 기존 `dreams.md`)에 씁니다. -- `dreaming.model`은 기존 Plugin subagent trust gate를 사용합니다. 활성화하기 전에 `plugins.entries.memory-core.subagent.allowModelOverride: true`를 설정하세요. -- 구성된 모델을 사용할 수 없으면 Dream Diary는 session 기본 모델로 한 번 재시도합니다. trust 또는 allowlist 실패는 로그에 기록되며 조용히 재시도되지 않습니다. -- light/deep/REM phase 정책과 threshold는 user-facing config가 아니라 내부 동작입니다. +- `dreaming.model`은 기존 plugin subagent trust gate를 사용합니다. 활성화하기 전에 `plugins.entries.memory-core.subagent.allowModelOverride: true`를 설정하세요. +- 구성된 모델을 사용할 수 없으면 Dream Diary는 session default model로 한 번 재시도합니다. trust 또는 allowlist 실패는 기록되며 조용히 재시도되지 않습니다. +- light/deep/REM phase policy와 threshold는 사용자 대상 config가 아니라 내부 동작입니다. -## 관련 +## 관련 항목 -- [구성 reference](/ko/gateway/configuration-reference) -- [Memory 개요](/ko/concepts/memory) +- [Configuration reference](/ko/gateway/configuration-reference) +- [Memory overview](/ko/concepts/memory) - [Memory search](/ko/concepts/memory-search) diff --git a/docs/ko/reference/session-management-compaction.md b/docs/ko/reference/session-management-compaction.md index af8c477f6..76131e6aa 100644 --- a/docs/ko/reference/session-management-compaction.md +++ b/docs/ko/reference/session-management-compaction.md @@ -1,100 +1,100 @@ --- read_when: - - 세션 ID, 대화 기록 JSONL 또는 sessions.json 필드를 디버그해야 합니다 - - 자동 Compaction 동작을 변경하거나 “사전 Compaction” 정리 작업을 추가하고 있습니다 - - 메모리 플러시나 무음 시스템 턴을 구현하려는 경우 -summary: '심층 분석: 세션 저장소 + 대화 기록, 수명 주기 및 (자동)Compaction 내부 구조' + - 세션 ID, 트랜스크립트 JSONL 또는 sessions.json 필드를 디버그해야 합니다 + - 자동 Compaction 동작을 변경하거나 “Compaction 전” 정리 작업을 추가하는 경우 + - 메모리 플러시 또는 무음 시스템 턴을 구현하려는 경우 +summary: '심층 분석: 세션 저장소 + 트랜스크립트, 수명 주기, 그리고 (자동)Compaction 내부 동작' title: 세션 관리 심층 분석 x-i18n: - generated_at: "2026-04-30T06:50:09Z" + generated_at: "2026-04-30T16:30:08Z" model: gpt-5.5 provider: openai - source_hash: 1e9785723ebf9b5411440a8f3b2885a50d659f669811ba749c431a2b3aeed700 + source_hash: 5a6a7031cebd90d27784a32a0d0378ea9959249389d209f0745395f90b8a0df9 source_path: reference/session-management-compaction.md workflow: 16 --- -OpenClaw는 다음 영역 전반에서 세션을 종단 간으로 관리합니다. +OpenClaw은 다음 영역 전반에서 세션을 엔드투엔드로 관리합니다. - **세션 라우팅**(인바운드 메시지가 `sessionKey`에 매핑되는 방식) -- **세션 저장소**(`sessions.json`)와 추적 항목 -- **트랜스크립트 지속성**(`*.jsonl`)과 구조 -- **트랜스크립트 정리**(실행 전 제공자별 수정) +- **세션 저장소**(`sessions.json`)와 추적하는 항목 +- **트랜스크립트 영속성**(`*.jsonl`)과 그 구조 +- **트랜스크립트 위생**(실행 전 제공자별 보정) - **컨텍스트 제한**(컨텍스트 창과 추적 토큰) - **Compaction**(수동 및 자동 Compaction)과 Compaction 전 작업을 연결할 위치 -- **무음 하우스키핑**(사용자에게 표시되는 출력을 생성해서는 안 되는 메모리 쓰기) +- **조용한 정리 작업**(사용자에게 보이는 출력을 생성하지 않아야 하는 메모리 쓰기) -먼저 더 상위 수준의 개요를 보고 싶다면 다음부터 시작하세요. +먼저 상위 수준 개요를 보려면 다음으로 시작하세요. - [세션 관리](/ko/concepts/session) - [Compaction](/ko/concepts/compaction) - [메모리 개요](/ko/concepts/memory) - [메모리 검색](/ko/concepts/memory-search) - [세션 정리](/ko/concepts/session-pruning) -- [트랜스크립트 정리](/ko/reference/transcript-hygiene) +- [트랜스크립트 위생](/ko/reference/transcript-hygiene) --- ## 진실의 원천: Gateway -OpenClaw는 세션 상태를 소유하는 단일 **Gateway 프로세스**를 중심으로 설계되었습니다. +OpenClaw은 세션 상태를 소유하는 단일 **Gateway 프로세스**를 중심으로 설계되었습니다. -- UI(macOS 앱, 웹 Control UI, TUI)는 Gateway에 세션 목록과 토큰 수를 조회해야 합니다. +- UI(macOS 앱, 웹 Control UI, TUI)는 세션 목록과 토큰 수를 Gateway에 질의해야 합니다. - 원격 모드에서는 세션 파일이 원격 호스트에 있습니다. “로컬 Mac 파일 확인”은 Gateway가 사용하는 내용을 반영하지 않습니다. --- -## 두 가지 지속성 계층 +## 두 가지 영속성 계층 -OpenClaw는 세션을 두 계층에 지속 저장합니다. +OpenClaw은 세션을 두 계층으로 영속화합니다. 1. **세션 저장소(`sessions.json`)** - 키/값 맵: `sessionKey -> SessionEntry` - - 작고, 변경 가능하며, 편집(또는 항목 삭제)해도 안전함 + - 작고, 변경 가능하며, 편집해도 안전함(또는 항목 삭제 가능) - 세션 메타데이터(현재 세션 ID, 마지막 활동, 토글, 토큰 카운터 등)를 추적함 2. **트랜스크립트(`.jsonl`)** - - 트리 구조를 가진 추가 전용 트랜스크립트(항목에는 `id` + `parentId`가 있음) + - 트리 구조를 가진 추가 전용 트랜스크립트(항목은 `id` + `parentId`를 가짐) - 실제 대화 + 도구 호출 + Compaction 요약을 저장함 - - 이후 턴의 모델 컨텍스트를 다시 빌드하는 데 사용됨 - - 활성 트랜스크립트가 체크포인트 크기 상한을 초과하면 큰 Compaction 전 디버그 체크포인트를 건너뛰어 두 번째 거대한 `.checkpoint.*.jsonl` 사본을 피합니다. + - 이후 턴에서 모델 컨텍스트를 다시 구성하는 데 사용됨 + - 활성 트랜스크립트가 체크포인트 크기 상한을 초과하면 대용량 Compaction 전 디버그 체크포인트를 건너뛰어 두 번째 거대한 `.checkpoint.*.jsonl` 복사본을 피합니다. --- ## 디스크상의 위치 -Gateway 호스트에서 에이전트별 위치: +Gateway 호스트에서 에이전트별로: - 저장소: `~/.openclaw/agents//sessions/sessions.json` - 트랜스크립트: `~/.openclaw/agents//sessions/.jsonl` - - Telegram 주제 세션: `.../-topic-.jsonl` + - Telegram 토픽 세션: `.../-topic-.jsonl` -OpenClaw는 `src/config/sessions.ts`를 통해 이를 확인합니다. +OpenClaw은 이를 `src/config/sessions.ts`를 통해 해석합니다. --- ## 저장소 유지 관리 및 디스크 제어 -세션 지속성에는 `sessions.json`, 트랜스크립트 아티팩트, trajectory 사이드카에 대한 자동 유지 관리 제어(`session.maintenance`)가 있습니다. +세션 영속성에는 `sessions.json`, 트랜스크립트 아티팩트, 트래젝터리 사이드카에 대한 자동 유지 관리 제어(`session.maintenance`)가 있습니다. - `mode`: `warn`(기본값) 또는 `enforce` -- `pruneAfter`: 오래된 항목의 나이 기준(기본값 `30d`) +- `pruneAfter`: 오래된 항목 나이 기준(기본값 `30d`) - `maxEntries`: `sessions.json`의 항목 상한(기본값 `500`) -- `resetArchiveRetention`: `*.reset.` 트랜스크립트 아카이브의 보존 기간(기본값: `pruneAfter`와 동일, `false`는 정리 비활성화) +- `resetArchiveRetention`: `*.reset.` 트랜스크립트 아카이브 보존 기간(기본값: `pruneAfter`와 동일, `false`는 정리 비활성화) - `maxDiskBytes`: 선택적 세션 디렉터리 예산 -- `highWaterBytes`: 정리 후 선택적 목표값(기본값은 `maxDiskBytes`의 `80%`) +- `highWaterBytes`: 정리 후 선택적 목표값(기본값: `maxDiskBytes`의 `80%`) -일반 Gateway 쓰기는 프로덕션 크기 상한에 대해 `maxEntries` 정리를 배치 처리하므로, 다음 high-water 정리가 다시 줄여 쓰기 전까지 저장소가 구성된 상한을 잠시 초과할 수 있습니다. `openclaw sessions cleanup --enforce`는 여전히 구성된 상한을 즉시 적용합니다. +일반 Gateway 쓰기는 프로덕션 크기 상한에 대해 `maxEntries` 정리를 배치 처리하므로, 다음 high-water 정리가 저장소를 다시 줄여 쓰기 전까지 저장소가 구성된 상한을 잠시 초과할 수 있습니다. `openclaw sessions cleanup --enforce`는 여전히 구성된 상한을 즉시 적용합니다. -OpenClaw는 더 이상 Gateway 쓰기 중 자동 `sessions.json.bak.*` 순환 백업을 생성하지 않습니다. 레거시 `session.maintenance.rotateBytes` 키는 무시되며, `openclaw doctor --fix`는 오래된 설정에서 이를 제거합니다. +OpenClaw은 더 이상 Gateway 쓰기 중 자동 `sessions.json.bak.*` 순환 백업을 만들지 않습니다. 레거시 `session.maintenance.rotateBytes` 키는 무시되며 `openclaw doctor --fix`가 오래된 구성에서 이를 제거합니다. 디스크 예산 정리의 강제 적용 순서(`mode: "enforce"`): -1. 가장 오래된 아카이브, 고아 트랜스크립트 또는 고아 trajectory 아티팩트를 먼저 제거합니다. -2. 그래도 목표값을 초과하면 가장 오래된 세션 항목과 해당 트랜스크립트/trajectory 파일을 제거합니다. +1. 가장 오래된 아카이브, 고아 트랜스크립트, 또는 고아 트래젝터리 아티팩트를 먼저 제거합니다. +2. 그래도 목표값을 초과하면 가장 오래된 세션 항목과 해당 트랜스크립트/트래젝터리 파일을 제거합니다. 3. 사용량이 `highWaterBytes` 이하가 될 때까지 계속합니다. -`mode: "warn"`에서는 OpenClaw가 잠재적 제거 항목을 보고하지만 저장소/파일을 변경하지 않습니다. +`mode: "warn"`에서 OpenClaw은 잠재적 제거를 보고하지만 저장소/파일을 변경하지 않습니다. 필요할 때 유지 관리를 실행하세요. @@ -107,26 +107,26 @@ openclaw sessions cleanup --enforce ## Cron 세션 및 실행 로그 -격리된 Cron 실행도 세션 항목/트랜스크립트를 생성하며, 전용 보존 제어가 있습니다. +격리된 cron 실행도 세션 항목/트랜스크립트를 만들며, 전용 보존 제어가 있습니다. -- `cron.sessionRetention`(기본값 `24h`)은 세션 저장소에서 오래된 격리 Cron 실행 세션을 정리합니다(`false`는 비활성화). +- `cron.sessionRetention`(기본값 `24h`)은 세션 저장소에서 오래된 격리 cron 실행 세션을 정리합니다(`false`는 비활성화). - `cron.runLog.maxBytes` + `cron.runLog.keepLines`는 `~/.openclaw/cron/runs/.jsonl` 파일을 정리합니다(기본값: `2_000_000`바이트 및 `2000`줄). -Cron이 새 격리 실행 세션을 강제로 생성할 때, 새 행을 쓰기 전에 이전 `cron:` 세션 항목을 정리합니다. thinking/fast/verbose 설정, 레이블, 사용자가 명시적으로 선택한 모델/인증 재정의 같은 안전한 기본 설정은 유지합니다. 채널/그룹 라우팅, 전송 또는 큐 정책, 권한 상승, 원점, ACP 런타임 바인딩 같은 주변 대화 컨텍스트는 제거하여 새 격리 실행이 오래된 실행의 낡은 전달 또는 런타임 권한을 상속하지 못하게 합니다. +cron이 새 격리 실행 세션을 강제로 만들 때는 새 행을 쓰기 전에 이전 `cron:` 세션 항목을 정리합니다. thinking/fast/verbose 설정, 레이블, 명시적인 사용자 선택 모델/auth 오버라이드 같은 안전한 기본 설정은 유지합니다. 채널/그룹 라우팅, 전송 또는 큐 정책, 권한 상승, 출처, ACP 런타임 바인딩 같은 주변 대화 컨텍스트는 제거하여 새 격리 실행이 이전 실행의 오래된 전달 또는 런타임 권한을 상속하지 못하게 합니다. --- ## 세션 키(`sessionKey`) -`sessionKey`는 사용자가 속한 _대화 버킷_(라우팅 + 격리)을 식별합니다. +`sessionKey`는 _어떤 대화 버킷_에 있는지(라우팅 + 격리)를 식별합니다. 일반적인 패턴: -- 기본/직접 채팅(에이전트별): `agent::`(기본값 `main`) +- 메인/직접 채팅(에이전트별): `agent::`(기본값 `main`) - 그룹: `agent:::group:` - 방/채널(Discord/Slack): `agent:::channel:` 또는 `...:room:` - Cron: `cron:` -- Webhook: `hook:`(재정의하지 않은 경우) +- Webhook: `hook:`(오버라이드되지 않은 경우) 정식 규칙은 [/concepts/session](/ko/concepts/session)에 문서화되어 있습니다. @@ -136,15 +136,15 @@ Cron이 새 격리 실행 세션을 강제로 생성할 때, 새 행을 쓰기 각 `sessionKey`는 현재 `sessionId`(대화를 이어 가는 트랜스크립트 파일)를 가리킵니다. -경험적 규칙: +경험칙: -- **재설정**(`/new`, `/reset`)은 해당 `sessionKey`에 대한 새 `sessionId`를 생성합니다. -- **일일 재설정**(기본값: Gateway 호스트의 현지 시간 오전 4:00)은 재설정 경계 이후 다음 메시지에서 새 `sessionId`를 생성합니다. -- **유휴 만료**(`session.reset.idleMinutes` 또는 레거시 `session.idleMinutes`)는 유휴 창 이후 메시지가 도착하면 새 `sessionId`를 생성합니다. 일일 재설정과 유휴 만료가 모두 구성된 경우 먼저 만료되는 쪽이 우선합니다. -- **시스템 이벤트**(Heartbeat, Cron 깨우기, exec 알림, Gateway 장부 작업)는 세션 행을 변경할 수 있지만 일일/유휴 재설정 신선도를 연장하지 않습니다. 재설정 롤오버는 새 프롬프트를 빌드하기 전에 이전 세션에 대해 대기 중이던 시스템 이벤트 알림을 폐기합니다. -- **스레드 부모 포크 가드**(`session.parentForkMaxTokens`, 기본값 `100000`)는 부모 세션이 이미 너무 클 때 부모 트랜스크립트 포크를 건너뜁니다. 새 스레드는 새로 시작합니다. 비활성화하려면 `0`으로 설정하세요. +- **재설정**(`/new`, `/reset`)은 해당 `sessionKey`에 대한 새 `sessionId`를 만듭니다. +- **일일 재설정**(Gateway 호스트의 로컬 시간 기준 기본 오전 4:00)은 재설정 경계 이후 다음 메시지에서 새 `sessionId`를 만듭니다. +- **유휴 만료**(`session.reset.idleMinutes` 또는 레거시 `session.idleMinutes`)는 유휴 창 이후 메시지가 도착하면 새 `sessionId`를 만듭니다. 일일 + 유휴가 모두 구성된 경우 먼저 만료되는 것이 적용됩니다. +- **시스템 이벤트**(Heartbeat, cron 깨우기, exec 알림, Gateway 장부 관리)는 세션 행을 변경할 수 있지만 일일/유휴 재설정 신선도를 연장하지 않습니다. 재설정 롤오버는 새 프롬프트가 구성되기 전에 이전 세션에 대해 대기열에 있던 시스템 이벤트 알림을 버립니다. +- **스레드 부모 포크 가드**(`session.parentForkMaxTokens`, 기본값 `100000`)는 부모 세션이 이미 너무 큰 경우 부모 트랜스크립트 포크를 건너뜁니다. 새 스레드는 새로 시작합니다. 비활성화하려면 `0`으로 설정하세요. -구현 세부 정보: 이 결정은 `src/auto-reply/reply/session.ts`의 `initSessionState()`에서 이루어집니다. +구현 세부 사항: 이 결정은 `src/auto-reply/reply/session.ts`의 `initSessionState()`에서 발생합니다. --- @@ -154,16 +154,16 @@ Cron이 새 격리 실행 세션을 강제로 생성할 때, 새 행을 쓰기 주요 필드(전체 목록 아님): -- `sessionId`: 현재 트랜스크립트 ID(`sessionFile`이 설정되지 않은 한 파일명은 여기서 파생됨) +- `sessionId`: 현재 트랜스크립트 ID(`sessionFile`이 설정되지 않은 경우 파일 이름은 여기서 파생됨) - `sessionStartedAt`: 현재 `sessionId`의 시작 타임스탬프입니다. 일일 재설정 신선도는 이를 사용합니다. 레거시 행은 JSONL 세션 헤더에서 이를 파생할 수 있습니다. -- `lastInteractionAt`: 마지막 실제 사용자/채널 상호작용 타임스탬프입니다. 유휴 재설정 신선도는 이를 사용하므로 Heartbeat, Cron, exec 이벤트가 세션을 계속 살아 있게 만들지 않습니다. 이 필드가 없는 레거시 행은 복구된 세션 시작 시간을 유휴 신선도에 대한 대체값으로 사용합니다. -- `updatedAt`: 마지막 저장소 행 변경 타임스탬프로, 목록 표시, 정리, 장부 작업에 사용됩니다. 일일/유휴 재설정 신선도의 권위자는 아닙니다. -- `sessionFile`: 선택적 명시 트랜스크립트 경로 재정의 -- `chatType`: `direct | group | room`(UI와 전송 정책에 도움) +- `lastInteractionAt`: 마지막 실제 사용자/채널 상호작용 타임스탬프입니다. Heartbeat, cron, exec 이벤트가 세션을 계속 살아 있게 하지 않도록 유휴 재설정 신선도가 이를 사용합니다. 이 필드가 없는 레거시 행은 유휴 신선도에 대해 복구된 세션 시작 시간으로 폴백합니다. +- `updatedAt`: 마지막 저장소 행 변경 타임스탬프로, 목록 표시, 정리, 장부 관리에 사용됩니다. 일일/유휴 재설정 신선도의 권위가 아닙니다. +- `sessionFile`: 선택적 명시 트랜스크립트 경로 오버라이드 +- `chatType`: `direct | group | room`(UI 및 전송 정책에 도움) - `provider`, `subject`, `room`, `space`, `displayName`: 그룹/채널 레이블링을 위한 메타데이터 - 토글: - `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel` - - `sendPolicy`(세션별 재정의) + - `sendPolicy`(세션별 오버라이드) - 모델 선택: - `providerOverride`, `modelOverride`, `authProfileOverride` - 토큰 카운터(최선 노력 / 제공자 의존): @@ -172,7 +172,7 @@ Cron이 새 격리 실행 세션을 강제로 생성할 때, 새 행을 쓰기 - `memoryFlushAt`: 마지막 Compaction 전 메모리 플러시의 타임스탬프 - `memoryFlushCompactionCount`: 마지막 플러시가 실행되었을 때의 Compaction 횟수 -저장소는 편집해도 안전하지만 Gateway가 권위자입니다. 세션이 실행되면 항목을 다시 쓰거나 재수화할 수 있습니다. +저장소는 편집해도 안전하지만 Gateway가 권위입니다. 세션이 실행되는 동안 항목을 다시 쓰거나 재수화할 수 있습니다. --- @@ -189,59 +189,60 @@ Cron이 새 격리 실행 세션을 강제로 생성할 때, 새 행을 쓰기 - `message`: 사용자/어시스턴트/toolResult 메시지 - `custom_message`: 모델 컨텍스트에 _들어가는_ 확장 주입 메시지(UI에서는 숨길 수 있음) -- `custom`: 모델 컨텍스트에 들어가지 _않는_ 확장 상태 -- `compaction`: `firstKeptEntryId`와 `tokensBefore`를 포함하는 지속 저장된 Compaction 요약 -- `branch_summary`: 트리 브랜치를 탐색할 때 지속 저장되는 요약 +- `custom`: 모델 컨텍스트에 _들어가지 않는_ 확장 상태 +- `compaction`: `firstKeptEntryId` 및 `tokensBefore`가 있는 영속화된 Compaction 요약 +- `branch_summary`: 트리 브랜치를 탐색할 때 영속화된 요약 -OpenClaw는 의도적으로 트랜스크립트를 “수정”하지 않습니다. Gateway는 `SessionManager`를 사용해 이를 읽고 씁니다. +OpenClaw은 의도적으로 트랜스크립트를 “보정”하지 않습니다. Gateway는 `SessionManager`를 사용해 이를 읽고 씁니다. --- ## 컨텍스트 창과 추적 토큰 -중요한 개념은 두 가지입니다. +두 가지 서로 다른 개념이 중요합니다. 1. **모델 컨텍스트 창**: 모델별 하드 상한(모델에 보이는 토큰) -2. **세션 저장소 카운터**: `sessions.json`에 쓰이는 롤링 통계(/status와 대시보드에 사용) +2. **세션 저장소 카운터**: `sessions.json`에 기록되는 롤링 통계(/status 및 대시보드에 사용) -제한을 조정하는 경우: +제한을 튜닝하는 경우: -- 컨텍스트 창은 모델 카탈로그에서 가져옵니다(설정으로 재정의 가능). -- 저장소의 `contextTokens`는 런타임 추정/보고 값입니다. 엄격한 보장으로 간주하지 마세요. +- 컨텍스트 창은 모델 카탈로그에서 가져옵니다(구성을 통해 오버라이드 가능). +- 저장소의 `contextTokens`는 런타임 추정/보고 값입니다. 엄격한 보장으로 취급하지 마세요. 자세한 내용은 [/token-use](/ko/reference/token-use)를 참조하세요. --- -## Compaction: 정의 +## Compaction: 무엇인가 -Compaction은 오래된 대화를 트랜스크립트의 지속 저장된 `compaction` 항목으로 요약하고 최근 메시지는 그대로 유지합니다. +Compaction은 이전 대화를 트랜스크립트의 영속화된 `compaction` 항목으로 요약하고 최근 메시지는 그대로 유지합니다. -Compaction 이후의 향후 턴에는 다음이 표시됩니다. +Compaction 이후 미래 턴에서 보이는 항목: - Compaction 요약 - `firstKeptEntryId` 이후의 메시지 -Compaction은 (세션 정리와 달리) **지속적**입니다. [/concepts/session-pruning](/ko/concepts/session-pruning)을 참조하세요. +Compaction은 **영속적**입니다(세션 정리와 다름). [/concepts/session-pruning](/ko/concepts/session-pruning)을 참조하세요. ## Compaction 청크 경계 및 도구 페어링 -OpenClaw가 긴 트랜스크립트를 Compaction 청크로 나눌 때, 어시스턴트 도구 호출을 일치하는 `toolResult` 항목과 함께 유지합니다. +OpenClaw이 긴 트랜스크립트를 Compaction 청크로 나눌 때는 어시스턴트 도구 호출을 대응하는 `toolResult` 항목과 짝지어 유지합니다. -- 토큰 비율 분할이 도구 호출과 그 결과 사이에 걸리면, OpenClaw는 해당 쌍을 분리하는 대신 경계를 어시스턴트 도구 호출 메시지로 이동합니다. -- 뒤따르는 도구 결과 블록이 청크를 목표값보다 초과하게 만들 상황이면, OpenClaw는 보류 중인 해당 도구 블록을 보존하고 요약되지 않은 꼬리 부분을 그대로 유지합니다. -- 중단/오류 도구 호출 블록은 보류 중인 분할을 열린 상태로 유지하지 않습니다. +- 토큰 비율 분할이 도구 호출과 그 결과 사이에 놓이면 OpenClaw은 쌍을 분리하는 대신 경계를 어시스턴트 도구 호출 메시지로 이동합니다. +- 뒤따르는 tool-result 블록 때문에 청크가 목표를 초과하게 되는 경우 OpenClaw은 해당 대기 중인 도구 블록을 보존하고 요약되지 않은 꼬리 부분을 그대로 유지합니다. +- 중단/오류 도구 호출 블록은 대기 중인 분할을 열린 상태로 유지하지 않습니다. --- ## 자동 Compaction이 발생하는 시점(Pi 런타임) -내장 Pi 에이전트에서 자동 Compaction은 두 경우에 트리거됩니다. +내장 Pi 에이전트에서 자동 Compaction은 두 가지 경우에 트리거됩니다. -1. **오버플로 복구**: 모델이 컨텍스트 오버플로 오류(`request_too_large`, `context length exceeded`, `input exceeds the maximum +1. **오버플로 복구**: 모델이 컨텍스트 오버플로 오류를 반환함 + (`request_too_large`, `context length exceeded`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model`, `ollama error: context length -exceeded` 및 유사한 제공자 형태의 변형)를 반환함 → compact → 재시도. +exceeded`, 및 유사한 제공자 형태의 변형) → compact → retry. 2. **임계값 유지 관리**: 성공적인 턴 이후 다음 조건일 때: `contextTokens > contextWindow - reserveTokens` @@ -251,15 +252,29 @@ exceeded` 및 유사한 제공자 형태의 변형)를 반환함 → compact → - `contextWindow`는 모델의 컨텍스트 창입니다. - `reserveTokens`는 프롬프트 + 다음 모델 출력을 위해 예약된 여유 공간입니다. -이는 Pi 런타임 의미론입니다(OpenClaw는 이벤트를 소비하지만, 언제 compact할지는 Pi가 결정합니다). +이는 Pi 런타임 의미 체계입니다(OpenClaw은 이벤트를 소비하지만, Compaction 시점은 Pi가 결정합니다). -OpenClaw는 `agents.defaults.compaction.maxActiveTranscriptBytes`가 설정되어 있고 활성 트랜스크립트 파일이 해당 크기에 도달하면 다음 실행을 열기 전에 사전 로컬 Compaction을 트리거할 수도 있습니다. 이는 원시 아카이브가 아니라 로컬 재개 비용을 위한 파일 크기 가드입니다. OpenClaw는 여전히 일반적인 의미론적 Compaction을 실행하며, 압축된 요약이 새 후속 트랜스크립트가 될 수 있도록 `truncateAfterCompaction`이 필요합니다. +OpenClaw은 `agents.defaults.compaction.maxActiveTranscriptBytes`가 설정되어 있고 활성 트랜스크립트 파일이 해당 크기에 도달하면 다음 실행을 열기 전에 사전 로컬 Compaction도 트리거할 수 있습니다. 이는 원시 아카이브가 아니라 로컬 재오픈 비용을 위한 파일 크기 가드입니다. OpenClaw은 여전히 일반 의미 기반 Compaction을 실행하며, 압축된 요약이 새 후속 트랜스크립트가 될 수 있도록 `truncateAfterCompaction`이 필요합니다. + +임베디드 Pi 실행의 경우 `agents.defaults.compaction.midTurnPrecheck.enabled: true`는 +옵트인 도구 루프 가드를 추가합니다. 도구 결과가 추가된 뒤 다음 모델 호출 전에 +OpenClaw는 턴 시작 시 사용하는 것과 같은 사전 예산 로직으로 프롬프트 압력을 +추정합니다. 컨텍스트가 더 이상 맞지 않으면, 가드는 Pi의 `transformContext` 훅 안에서 +Compaction하지 않습니다. 구조화된 중간 턴 사전 확인 신호를 발생시키고, 현재 프롬프트 +제출을 중지한 다음, 외부 실행 루프가 기존 복구 경로를 사용하게 합니다. 즉, 그것만으로 +충분하면 과도하게 큰 도구 결과를 자르고, 그렇지 않으면 구성된 Compaction 모드를 +트리거한 뒤 재시도합니다. 이 옵션은 기본적으로 비활성화되어 있으며, provider 기반 +safeguard Compaction을 포함해 `default`와 `safeguard` Compaction 모드 모두에서 +작동합니다. +이는 `maxActiveTranscriptBytes`와 독립적입니다. 바이트 크기 가드는 턴이 시작되기 전에 +실행되고, 중간 턴 사전 확인은 새 도구 결과가 추가된 뒤 임베디드 Pi 도구 루프에서 +나중에 실행됩니다. --- ## Compaction 설정(`reserveTokens`, `keepRecentTokens`) -Pi의 Compaction 설정은 Pi 설정에 있습니다: +Pi의 Compaction 설정은 Pi 설정에 있습니다. ```json5 { @@ -271,55 +286,59 @@ Pi의 Compaction 설정은 Pi 설정에 있습니다: } ``` -OpenClaw는 임베디드 실행에 안전 하한도 적용합니다. +OpenClaw는 임베디드 실행에 대해 안전 하한도 적용합니다. -- `compaction.reserveTokens < reserveTokensFloor`이면 OpenClaw가 이를 올립니다. +- `compaction.reserveTokens < reserveTokensFloor`이면 OpenClaw가 값을 올립니다. - 기본 하한은 `20000` 토큰입니다. -- 하한을 비활성화하려면 `agents.defaults.compaction.reserveTokensFloor: 0`을 설정하세요. +- 하한을 비활성화하려면 `agents.defaults.compaction.reserveTokensFloor: 0`을 설정합니다. - 이미 더 높으면 OpenClaw는 그대로 둡니다. -- 수동 `/compact`는 명시적인 `agents.defaults.compaction.keepRecentTokens`를 존중하고 +- 수동 `/compact`는 명시적인 `agents.defaults.compaction.keepRecentTokens`를 존중하며 Pi의 최근 꼬리 절단 지점을 유지합니다. 명시적인 유지 예산이 없으면 - 수동 Compaction은 하드 체크포인트로 유지되며 재구성된 컨텍스트는 - 새 요약부터 시작합니다. -- 활성 transcript가 커질 때 턴 전에 로컬 Compaction을 실행하려면 - `agents.defaults.compaction.maxActiveTranscriptBytes`를 바이트 값이나 - `"20mb"` 같은 문자열로 설정하세요. 이 가드는 - `truncateAfterCompaction`도 활성화된 경우에만 작동합니다. 비활성화하려면 - 설정하지 않거나 `0`으로 설정하세요. -- `agents.defaults.compaction.truncateAfterCompaction`이 활성화되면 - OpenClaw는 Compaction 후 활성 transcript를 압축된 후속 JSONL로 회전합니다. - 이전 전체 transcript는 제자리에서 다시 쓰이는 대신 보관되며 + 수동 Compaction은 계속 하드 체크포인트로 동작하고, 재구성된 컨텍스트는 + 새 요약에서 시작합니다. +- 새 도구 결과 이후 다음 모델 호출 전에 선택적 도구 루프 사전 확인을 실행하려면 + `agents.defaults.compaction.midTurnPrecheck.enabled: true`를 설정합니다. 이는 + 트리거일 뿐이며, 요약 생성은 여전히 구성된 Compaction 경로를 사용합니다. + 이는 턴 시작 시 활성 트랜스크립트 바이트 크기 가드인 `maxActiveTranscriptBytes`와 + 독립적입니다. +- 활성 트랜스크립트가 커질 때 턴 전에 로컬 Compaction을 실행하려면 + `agents.defaults.compaction.maxActiveTranscriptBytes`를 바이트 값이나 `"20mb"` 같은 + 문자열로 설정합니다. 이 가드는 `truncateAfterCompaction`도 활성화된 경우에만 + 활성화됩니다. 비활성화하려면 설정하지 않거나 `0`으로 설정합니다. +- `agents.defaults.compaction.truncateAfterCompaction`이 활성화되면, + OpenClaw는 Compaction 후 활성 트랜스크립트를 Compaction된 후속 JSONL로 + 순환시킵니다. 이전 전체 트랜스크립트는 제자리에서 다시 쓰이는 대신 보관되며 Compaction 체크포인트에서 링크됩니다. -이유: Compaction이 불가피해지기 전에 여러 턴의 “관리 작업”(예: memory 쓰기)을 위한 충분한 여유를 남기기 위해서입니다. +이유: Compaction이 불가피해지기 전에 여러 턴에 걸친 “유지 관리”(예: 메모리 쓰기)에 충분한 여유를 남기기 위해서입니다. 구현: `src/agents/pi-settings.ts`의 `ensurePiCompactionReserveTokens()` -(`src/agents/pi-embedded-runner.ts`에서 호출됨). +(`src/agents/pi-embedded-runner.ts`에서 호출). --- -## 플러그형 Compaction 제공자 +## 플러그형 Compaction provider -Plugin은 Plugin API의 `registerCompactionProvider()`를 통해 Compaction 제공자를 등록할 수 있습니다. `agents.defaults.compaction.provider`가 등록된 제공자 id로 설정되면 safeguard Plugin은 기본 제공 `summarizeInStages` 파이프라인 대신 해당 제공자에 요약을 위임합니다. +Plugin은 Plugin API의 `registerCompactionProvider()`를 통해 Compaction provider를 등록할 수 있습니다. `agents.defaults.compaction.provider`가 등록된 provider id로 설정되면, safeguard 확장은 내장 `summarizeInStages` 파이프라인 대신 해당 provider에 요약을 위임합니다. -- `provider`: 등록된 Compaction 제공자 Plugin의 id입니다. 기본 LLM 요약을 사용하려면 설정하지 마세요. +- `provider`: 등록된 Compaction provider Plugin의 id입니다. 기본 LLM 요약을 사용하려면 설정하지 마세요. - `provider`를 설정하면 `mode: "safeguard"`가 강제됩니다. -- 제공자는 기본 경로와 동일한 Compaction 지침 및 식별자 보존 정책을 받습니다. -- safeguard는 제공자 출력 이후에도 최근 턴 및 분할 턴 접미사 컨텍스트를 보존합니다. -- 기본 제공 safeguard 요약은 이전 전체 요약을 그대로 보존하는 대신 - 새 메시지와 함께 이전 요약을 다시 정제합니다. -- safeguard 모드는 기본적으로 요약 품질 감사를 활성화합니다. 잘못된 출력에 대한 재시도 동작을 건너뛰려면 - `qualityGuard.enabled: false`를 설정하세요. -- 제공자가 실패하거나 빈 결과를 반환하면 OpenClaw는 자동으로 기본 제공 LLM 요약으로 대체합니다. -- 호출자 취소를 존중하기 위해 중단/타임아웃 신호는 다시 던져집니다(삼키지 않음). +- Providers는 내장 경로와 같은 Compaction 지침 및 식별자 보존 정책을 받습니다. +- safeguard는 provider 출력 이후에도 최근 턴 및 분할 턴 접미사 컨텍스트를 보존합니다. +- 내장 safeguard 요약은 이전 전체 요약을 그대로 보존하는 대신, 새 메시지와 함께 + 이전 요약을 다시 정제합니다. +- safeguard 모드는 기본적으로 요약 품질 감사를 활성화합니다. 잘못된 형식의 출력에 대한 + 재시도 동작을 건너뛰려면 `qualityGuard.enabled: false`를 설정합니다. +- provider가 실패하거나 빈 결과를 반환하면 OpenClaw는 자동으로 내장 LLM 요약으로 폴백합니다. +- Abort/timeout 신호는 호출자의 취소를 존중하기 위해 다시 throw됩니다(삼키지 않음). 소스: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`. --- -## 사용자에게 보이는 표면 +## 사용자에게 표시되는 표면 -다음으로 Compaction과 세션 상태를 확인할 수 있습니다. +다음을 통해 Compaction 및 세션 상태를 관찰할 수 있습니다. - `/status`(모든 채팅 세션에서) - `openclaw status`(CLI) @@ -328,71 +347,70 @@ Plugin은 Plugin API의 `registerCompactionProvider()`를 통해 Compaction 제 --- -## 무음 관리 작업(`NO_REPLY`) +## 조용한 유지 관리(`NO_REPLY`) -OpenClaw는 사용자가 중간 출력을 보지 않아야 하는 백그라운드 작업용 “무음” 턴을 지원합니다. +OpenClaw는 사용자가 중간 출력을 보지 않아야 하는 백그라운드 작업을 위해 “조용한” 턴을 지원합니다. 규칙: -- assistant는 “사용자에게 답장을 전달하지 않음”을 나타내기 위해 정확한 무음 토큰 `NO_REPLY` / +- assistant는 “사용자에게 답장을 전달하지 말라”는 의미로 정확한 조용한 토큰 `NO_REPLY` / `no_reply`로 출력을 시작합니다. - OpenClaw는 전달 계층에서 이를 제거/억제합니다. -- 정확한 무음 토큰 억제는 대소문자를 구분하지 않으므로, 전체 payload가 무음 토큰뿐이면 `NO_REPLY`와 - `no_reply`가 모두 해당됩니다. -- 이는 실제 백그라운드/비전달 턴 전용입니다. 일반적인 실행 가능한 사용자 요청을 위한 +- 정확한 조용한 토큰 억제는 대소문자를 구분하지 않으므로, 전체 페이로드가 조용한 토큰뿐일 때 + `NO_REPLY`와 `no_reply` 모두 해당합니다. +- 이는 진정한 백그라운드/미전달 턴 전용입니다. 일반적인 실행 가능한 사용자 요청에 대한 지름길이 아닙니다. -`2026.1.10`부터 OpenClaw는 partial chunk가 `NO_REPLY`로 시작할 때 -**초안/타이핑 스트리밍**도 억제하므로, 무음 작업이 턴 중간에 partial -출력을 누출하지 않습니다. +`2026.1.10`부터 OpenClaw는 부분 청크가 `NO_REPLY`로 시작할 때 **초안/입력 중 스트리밍**도 +억제하므로, 조용한 작업이 턴 중간에 부분 출력을 노출하지 않습니다. --- -## Compaction 전 "memory 플러시"(구현됨) +## Compaction 전 "메모리 플러시"(구현됨) -목표: 자동 Compaction이 발생하기 전에 durable -상태를 디스크(예: agent workspace의 `memory/YYYY-MM-DD.md`)에 쓰는 무음 agentic 턴을 실행하여 Compaction이 -중요한 컨텍스트를 지우지 못하게 합니다. +목표: 자동 Compaction이 발생하기 전에, 디스크에 지속 상태를 쓰는 조용한 agentic 턴을 +실행합니다(예: 에이전트 작업 공간의 `memory/YYYY-MM-DD.md`). 이렇게 하면 Compaction이 +중요한 컨텍스트를 지울 수 없습니다. OpenClaw는 **사전 임계값 플러시** 접근 방식을 사용합니다. 1. 세션 컨텍스트 사용량을 모니터링합니다. -2. “소프트 임계값”(Pi의 Compaction 임계값보다 낮음)을 넘으면 agent에게 무음 - “지금 memory 쓰기” 지시를 실행합니다. -3. 사용자가 아무것도 보지 않도록 정확한 무음 토큰 `NO_REPLY` / `no_reply`를 사용합니다. +2. Pi의 Compaction 임계값보다 낮은 “소프트 임계값”을 넘으면, 에이전트에 조용한 + “지금 메모리 쓰기” 지시를 실행합니다. +3. 사용자가 아무것도 보지 않도록 정확한 조용한 토큰 `NO_REPLY` / `no_reply`를 사용합니다. -Config(`agents.defaults.compaction.memoryFlush`): +설정(`agents.defaults.compaction.memoryFlush`): - `enabled`(기본값: `true`) - `model`(플러시 턴에 대한 선택적 정확한 provider/model 재정의, 예: `ollama/qwen3:8b`) - `softThresholdTokens`(기본값: `4000`) - `prompt`(플러시 턴의 사용자 메시지) -- `systemPrompt`(플러시 턴에 추가되는 추가 시스템 프롬프트) +- `systemPrompt`(플러시 턴에 추가로 덧붙이는 시스템 프롬프트) 참고: - 기본 프롬프트/시스템 프롬프트에는 전달을 억제하기 위한 `NO_REPLY` 힌트가 포함됩니다. -- `model`이 설정되면 플러시 턴은 활성 세션 fallback 체인을 상속하지 않고 해당 모델을 사용하므로, - 로컬 전용 관리 작업이 유료 대화 모델로 조용히 fallback되지 않습니다. +- `model`이 설정되면 플러시 턴은 활성 세션 폴백 체인을 상속하지 않고 해당 모델을 + 사용하므로, 로컬 전용 유지 관리가 유료 대화 모델로 조용히 폴백하지 않습니다. - 플러시는 Compaction 주기마다 한 번 실행됩니다(`sessions.json`에서 추적). -- 플러시는 임베디드 Pi 세션에서만 실행됩니다(CLI 백엔드는 건너뜀). -- 세션 workspace가 읽기 전용(`workspaceAccess: "ro"` 또는 `"none"`)이면 플러시는 건너뜁니다. -- workspace 파일 레이아웃과 쓰기 패턴은 [Memory](/ko/concepts/memory)를 참고하세요. +- 플러시는 임베디드 Pi 세션에 대해서만 실행됩니다(CLI 백엔드는 건너뜁니다). +- 세션 작업 공간이 읽기 전용인 경우(`workspaceAccess: "ro"` 또는 `"none"`) 플러시는 건너뜁니다. +- 작업 공간 파일 레이아웃과 쓰기 패턴은 [Memory](/ko/concepts/memory)를 참고하세요. -Pi는 extension API에서 `session_before_compact` 훅도 노출하지만, OpenClaw의 -플러시 로직은 현재 Gateway 측에 있습니다. +Pi도 확장 API에서 `session_before_compact` 훅을 노출하지만, OpenClaw의 플러시 로직은 +현재 Gateway 측에 있습니다. --- ## 문제 해결 체크리스트 - 세션 키가 잘못되었나요? [/concepts/session](/ko/concepts/session)에서 시작하고 `/status`의 `sessionKey`를 확인하세요. -- 저장소와 transcript가 일치하지 않나요? `openclaw status`에서 Gateway 호스트와 저장소 경로를 확인하세요. -- Compaction 스팸이 발생하나요? 다음을 확인하세요. +- 스토어와 트랜스크립트가 일치하지 않나요? `openclaw status`에서 Gateway 호스트와 스토어 경로를 확인하세요. +- Compaction이 과도하게 발생하나요? 다음을 확인하세요. - 모델 컨텍스트 창(너무 작음) - Compaction 설정(모델 창에 비해 `reserveTokens`가 너무 높으면 더 이른 Compaction이 발생할 수 있음) - 도구 결과 비대화: 세션 가지치기를 활성화/조정하세요 -- 무음 턴이 누출되나요? 답장이 `NO_REPLY`(대소문자 무시 정확 토큰)로 시작하는지, 그리고 스트리밍 억제 수정이 포함된 빌드인지 확인하세요. +- 조용한 턴이 새고 있나요? 답장이 `NO_REPLY`(대소문자를 구분하지 않는 정확한 토큰)로 시작하는지, 그리고 스트리밍 억제 수정이 포함된 빌드를 사용 중인지 확인하세요. ## 관련 diff --git a/docs/ko/tools/index.md b/docs/ko/tools/index.md index db9e657c0..a82967f1c 100644 --- a/docs/ko/tools/index.md +++ b/docs/ko/tools/index.md @@ -1,127 +1,127 @@ --- read_when: - - OpenClaw가 제공하는 도구를 이해하고 싶습니다 - - 도구를 설정하거나, 허용하거나, 거부해야 합니다 - - 기본 제공 도구, Skills, Plugin 중 무엇을 사용할지 결정하고 있습니다 -summary: 'OpenClaw 도구 및 Plugin 개요: 에이전트가 수행할 수 있는 작업과 이를 확장하는 방법' + - OpenClaw가 제공하는 도구가 무엇인지 이해하고 싶습니다 + - 도구를 구성하거나 허용 또는 거부해야 합니다 + - 내장 도구, Skills, Plugin 중에서 선택하고 있습니다 +summary: 'OpenClaw 도구 및 Plugin 개요: 에이전트가 할 수 있는 일과 확장하는 방법' title: 도구 및 Plugin x-i18n: - generated_at: "2026-04-30T06:54:31Z" + generated_at: "2026-04-30T16:30:09Z" model: gpt-5.5 provider: openai - source_hash: 62cde740188c224af03b4425c7f6dfca9a12f95603066db5925724fc6a07dcf0 + source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb source_path: tools/index.md workflow: 16 --- -에이전트가 텍스트 생성 외에 수행하는 모든 작업은 **도구**를 통해 이루어집니다. +에이전트가 텍스트 생성 이외에 수행하는 모든 일은 **도구**를 통해 이루어집니다. 도구는 에이전트가 파일을 읽고, 명령을 실행하고, 웹을 탐색하고, 메시지를 보내고, -장치와 상호작용하는 방식입니다. +기기와 상호작용하는 방식입니다. -## 도구, Skills 및 Plugin +## 도구, Skills, Plugin OpenClaw에는 함께 작동하는 세 가지 계층이 있습니다. - + 도구는 에이전트가 호출할 수 있는 타입 지정 함수입니다(예: `exec`, `browser`, - `web_search`, `message`). OpenClaw는 **내장 도구** 세트를 제공하며, + `web_search`, `message`). OpenClaw는 **기본 제공 도구** 세트를 함께 제공하며 Plugin은 추가 도구를 등록할 수 있습니다. 에이전트는 도구를 모델 API로 전송되는 구조화된 함수 정의로 봅니다. - + Skill은 시스템 프롬프트에 주입되는 마크다운 파일(`SKILL.md`)입니다. - Skills는 에이전트가 도구를 효과적으로 사용하기 위한 컨텍스트, 제약 조건, 단계별 지침을 - 제공합니다. Skills는 작업 공간, 공유 폴더에 있거나 Plugin 내부에 포함되어 제공됩니다. + Skills는 에이전트가 도구를 효과적으로 사용하는 데 필요한 컨텍스트, 제약 조건, + 단계별 지침을 제공합니다. Skills는 작업 영역, 공유 폴더에 있거나 + Plugin 안에 포함되어 제공됩니다. [Skills 참조](/ko/tools/skills) | [Skills 만들기](/ko/tools/creating-skills) - Plugin은 기능의 임의 조합을 등록할 수 있는 패키지입니다: - 채널, 모델 제공자, 도구, Skills, 음성, 실시간 전사, - 실시간 음성, 미디어 이해, 이미지 생성, 비디오 생성, - 웹 가져오기, 웹 검색 등입니다. 일부 Plugin은 **코어**(OpenClaw와 함께 제공)이고, - 다른 Plugin은 **외부**(커뮤니티가 npm에 게시)입니다. + Plugin은 채널, 모델 제공자, 도구, Skills, 음성, 실시간 전사, + 실시간 음성, 미디어 이해, 이미지 생성, 동영상 생성, 웹 가져오기, 웹 검색 등 + 여러 기능 조합을 등록할 수 있는 패키지입니다. 일부 Plugin은 **코어**이며 + OpenClaw와 함께 제공되고, 다른 Plugin은 **외부**이며 커뮤니티가 npm에 게시합니다. [Plugin 설치 및 구성](/ko/tools/plugin) | [직접 빌드하기](/ko/plugins/building-plugins) -## 내장 도구 +## 기본 제공 도구 -이 도구들은 OpenClaw와 함께 제공되며 Plugin 설치 없이 사용할 수 있습니다. +이 도구들은 OpenClaw와 함께 제공되며 Plugin을 설치하지 않아도 사용할 수 있습니다. | 도구 | 수행 작업 | 페이지 | | ------------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `exec` / `process` | 셸 명령 실행, 백그라운드 프로세스 관리 | [Exec](/ko/tools/exec), [Exec 승인](/ko/tools/exec-approvals) | -| `code_execution` | 샌드박스 처리된 원격 Python 분석 실행 | [코드 실행](/ko/tools/code-execution) | +| `code_execution` | 샌드박스된 원격 Python 분석 실행 | [코드 실행](/ko/tools/code-execution) | | `browser` | Chromium 브라우저 제어(탐색, 클릭, 스크린샷) | [브라우저](/ko/tools/browser) | | `web_search` / `x_search` / `web_fetch` | 웹 검색, X 게시물 검색, 페이지 콘텐츠 가져오기 | [웹](/ko/tools/web), [웹 가져오기](/ko/tools/web-fetch) | -| `read` / `write` / `edit` | 작업 공간의 파일 I/O | | -| `apply_patch` | 여러 hunk 파일 패치 | [Apply Patch](/ko/tools/apply-patch) | +| `read` / `write` / `edit` | 작업 영역의 파일 I/O | | +| `apply_patch` | 다중 헝크 파일 패치 | [패치 적용](/ko/tools/apply-patch) | | `message` | 모든 채널에 메시지 보내기 | [에이전트 전송](/ko/tools/agent-send) | | `canvas` | Node Canvas 구동(표시, 평가, 스냅샷) | | -| `nodes` | 페어링된 장치 검색 및 대상으로 지정 | | -| `cron` / `gateway` | 예약 작업 관리; Gateway 검사, 패치, 재시작 또는 업데이트 | | +| `nodes` | 페어링된 기기 탐색 및 대상으로 지정 | | +| `cron` / `gateway` | 예약 작업 관리, Gateway 검사, 패치, 재시작 또는 업데이트 | | | `image` / `image_generate` | 이미지 분석 또는 생성 | [이미지 생성](/ko/tools/image-generation) | | `music_generate` | 음악 트랙 생성 | [음악 생성](/ko/tools/music-generation) | -| `video_generate` | 비디오 생성 | [비디오 생성](/ko/tools/video-generation) | +| `video_generate` | 동영상 생성 | [동영상 생성](/ko/tools/video-generation) | | `tts` | 일회성 텍스트 음성 변환 | [TTS](/ko/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | 세션 관리, 상태 및 하위 에이전트 오케스트레이션 | [하위 에이전트](/ko/tools/subagents) | -| `session_status` | 경량 `/status` 스타일 재확인 및 세션 모델 override | [세션 도구](/ko/concepts/session-tool) | +| `sessions_*` / `subagents` / `agents_list` | 세션 관리, 상태, 하위 에이전트 오케스트레이션 | [하위 에이전트](/ko/tools/subagents) | +| `session_status` | 경량 `/status` 스타일 리드백 및 세션 모델 재정의 | [세션 도구](/ko/concepts/session-tool) | -이미지 작업에는 분석용으로 `image`를, 생성 또는 편집용으로 `image_generate`를 사용하세요. `openai/*`, `google/*`, `fal/*` 또는 다른 비기본 이미지 제공자를 대상으로 지정하는 경우 먼저 해당 제공자의 인증/API 키를 구성하세요. +이미지 작업에는 분석용으로 `image`를 사용하고, 생성 또는 편집용으로 `image_generate`를 사용하세요. `openai/*`, `google/*`, `fal/*` 또는 다른 기본값이 아닌 이미지 제공자를 대상으로 하는 경우 먼저 해당 제공자의 인증/API 키를 구성하세요. -음악 작업에는 `music_generate`를 사용하세요. `google/*`, `minimax/*` 또는 다른 비기본 음악 제공자를 대상으로 지정하는 경우 먼저 해당 제공자의 인증/API 키를 구성하세요. +음악 작업에는 `music_generate`를 사용하세요. `google/*`, `minimax/*` 또는 다른 기본값이 아닌 음악 제공자를 대상으로 하는 경우 먼저 해당 제공자의 인증/API 키를 구성하세요. -비디오 작업에는 `video_generate`를 사용하세요. `qwen/*` 또는 다른 비기본 비디오 제공자를 대상으로 지정하는 경우 먼저 해당 제공자의 인증/API 키를 구성하세요. +동영상 작업에는 `video_generate`를 사용하세요. `qwen/*` 또는 다른 기본값이 아닌 동영상 제공자를 대상으로 하는 경우 먼저 해당 제공자의 인증/API 키를 구성하세요. -워크플로 기반 오디오 생성에는 ComfyUI 같은 Plugin이 이를 등록한 경우 +워크플로 기반 오디오 생성에는 ComfyUI 같은 Plugin이 등록한 경우 `music_generate`를 사용하세요. 이는 텍스트 음성 변환인 `tts`와 별개입니다. -`sessions` 그룹의 경량 상태/재확인 도구는 `session_status`입니다. -현재 세션에 대한 `/status` 스타일 질문에 답하고, 선택적으로 세션별 모델 override를 -설정할 수 있습니다. `model=default`는 해당 override를 지웁니다. -`/status`와 마찬가지로 최신 transcript 사용량 항목에서 sparse 토큰/캐시 카운터와 -활성 런타임 모델 라벨을 backfill할 수 있습니다. +`sessions` 그룹의 경량 상태/리드백 도구는 `session_status`입니다. +현재 세션에 대한 `/status` 스타일 질문에 답하고, 선택적으로 세션별 모델 재정의를 +설정할 수 있습니다. `model=default`는 해당 재정의를 지웁니다. +`/status`와 마찬가지로 최신 트랜스크립트 사용량 항목에서 희소 토큰/캐시 카운터와 +활성 런타임 모델 레이블을 보충할 수 있습니다. `gateway`는 Gateway 작업을 위한 소유자 전용 런타임 도구입니다. - 편집 전 하나의 경로 범위 구성 하위 트리에 대한 `config.schema.lookup` -- 현재 구성 스냅샷 + 해시에 대한 `config.get` -- 재시작을 포함한 부분 구성 업데이트용 `config.patch` +- 현재 구성 스냅샷 + 해시용 `config.get` +- 재시작이 포함된 부분 구성 업데이트용 `config.patch` - 전체 구성 교체에만 사용하는 `config.apply` - 명시적 자체 업데이트 + 재시작용 `update.run` -부분 변경의 경우 `config.schema.lookup` 다음 `config.patch`를 선호하세요. 전체 구성을 의도적으로 교체할 때만 +부분 변경에는 `config.schema.lookup` 다음 `config.patch`를 선호하세요. 전체 구성을 의도적으로 교체할 때만 `config.apply`를 사용하세요. 더 넓은 구성 문서는 [구성](/ko/gateway/configuration) 및 [구성 참조](/ko/gateway/configuration-reference)를 읽으세요. -또한 이 도구는 `tools.exec.ask` 또는 `tools.exec.security` 변경을 거부합니다. -레거시 `tools.bash.*` 별칭은 동일하게 보호되는 exec 경로로 정규화됩니다. +이 도구는 `tools.exec.ask` 또는 `tools.exec.security` 변경도 거부합니다. +레거시 `tools.bash.*` 별칭은 동일한 보호된 exec 경로로 정규화됩니다. ### Plugin 제공 도구 -Plugin은 추가 도구를 등록할 수 있습니다. 몇 가지 예는 다음과 같습니다. +Plugin은 추가 도구를 등록할 수 있습니다. 몇 가지 예시는 다음과 같습니다. - [Diffs](/ko/tools/diffs) — diff 뷰어 및 렌더러 -- [LLM Task](/ko/tools/llm-task) — 구조화된 출력을 위한 JSON 전용 LLM 단계 -- [Lobster](/ko/tools/lobster) — 재개 가능한 승인을 갖춘 타입 지정 워크플로 런타임 -- [음악 생성](/ko/tools/music-generation) — 워크플로 기반 제공자를 포함한 공유 `music_generate` 도구 +- [LLM 작업](/ko/tools/llm-task) — 구조화된 출력을 위한 JSON 전용 LLM 단계 +- [Lobster](/ko/tools/lobster) — 재개 가능한 승인이 있는 타입 지정 워크플로 런타임 +- [음악 생성](/ko/tools/music-generation) — 워크플로 기반 제공자가 있는 공유 `music_generate` 도구 - [OpenProse](/ko/prose) — 마크다운 우선 워크플로 오케스트레이션 -- [Tokenjuice](/ko/tools/tokenjuice) — 잡음이 많은 `exec` 및 `bash` 도구 결과 압축 +- [Tokenjuice](/ko/tools/tokenjuice) — 노이즈가 많은 `exec` 및 `bash` 도구 결과 압축 ## 도구 구성 ### 허용 및 거부 목록 -구성에서 `tools.allow` / `tools.deny`를 통해 에이전트가 호출할 수 있는 도구를 제어합니다. +구성의 `tools.allow` / `tools.deny`로 에이전트가 호출할 수 있는 도구를 제어하세요. 거부는 항상 허용보다 우선합니다. ```json5 @@ -135,38 +135,40 @@ Plugin은 추가 도구를 등록할 수 있습니다. 몇 가지 예는 다음 명시적 허용 목록이 호출 가능한 도구로 해석되지 않으면 OpenClaw는 닫힌 상태로 실패합니다. 예를 들어 `tools.allow: ["query_db"]`는 로드된 Plugin이 실제로 -`query_db`를 등록한 경우에만 작동합니다. 내장 도구, Plugin 또는 번들 MCP 도구 중 -허용 목록과 일치하는 항목이 없으면, 도구 결과를 hallucinate할 수 있는 -텍스트 전용 실행으로 계속 진행하는 대신 모델 호출 전에 실행이 중단됩니다. +`query_db`를 등록한 경우에만 작동합니다. 기본 제공 도구, Plugin 또는 번들 MCP 도구 중 +허용 목록과 일치하는 것이 없으면, 도구 결과를 환각할 수 있는 +텍스트 전용 실행으로 계속하는 대신 모델 호출 전에 실행이 중지됩니다. ### 도구 프로필 -`tools.profile`은 `allow`/`deny`가 적용되기 전에 기본 허용 목록을 설정합니다. -에이전트별 override: `agents.list[].tools.profile`. +`tools.profile`은 `allow`/`deny`가 적용되기 전의 기본 허용 목록을 설정합니다. +에이전트별 재정의: `agents.list[].tools.profile`. -| 프로필 | 포함 항목 | +| 프로필 | 포함 항목 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | 더 넓은 명령/제어 접근을 위한 무제한 기준선; `tools.profile`을 설정하지 않은 것과 동일 | +| `full` | 더 넓은 명령/제어 접근을 위한 제한 없는 기준값입니다. `tools.profile`을 설정하지 않은 것과 같습니다 | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | `session_status`만 | +| `minimal` | `session_status`만 | -`tools.profile: "messaging"`은 채널 중심 에이전트를 위해 의도적으로 좁게 설정되어 있습니다. -파일시스템, 런타임, 브라우저, 캔버스, 노드, Cron, Gateway 제어 같은 -더 넓은 명령/제어 도구는 제외합니다. 더 넓은 명령/제어 접근을 위한 -무제한 기준선으로 `tools.profile: "full"`을 사용한 다음, 필요할 때 -`tools.allow` / `tools.deny`로 접근을 줄이세요. +`tools.profile: "messaging"`는 채널 중심 에이전트를 위해 의도적으로 좁게 설계되었습니다. +파일시스템, 런타임, 브라우저, 캔버스, 노드, Cron, Gateway 제어 같은 더 넓은 명령/제어 도구는 제외합니다. +더 넓은 명령/제어 접근을 위한 제한 없는 기준값으로 `tools.profile: "full"`을 사용한 다음, +필요할 때 `tools.allow` / `tools.deny`로 접근을 줄이세요. `coding`에는 경량 웹 도구(`web_search`, `web_fetch`, `x_search`)가 포함되지만 -전체 브라우저 제어 도구는 포함되지 않습니다. 브라우저 자동화는 실제 -세션과 로그인된 프로필을 구동할 수 있으므로 -`tools.alsoAllow: ["browser"]` 또는 에이전트별 +전체 브라우저 제어 도구는 포함되지 않습니다. 브라우저 자동화는 실제 세션과 +로그인된 프로필을 구동할 수 있으므로 `tools.alsoAllow: ["browser"]` 또는 에이전트별 `agents.list[].tools.alsoAllow: ["browser"]`로 명시적으로 추가하세요. -`coding` 및 `messaging` 프로필은 Plugin 키 `bundle-mcp` 아래에 구성된 번들 MCP 도구도 허용합니다. -프로필이 일반 내장 도구는 유지하되 구성된 모든 MCP 도구를 숨기게 하려면 + +제한적인 프로필(`messaging`, `minimal`)에서 `tools.exec` 또는 `tools.fs`를 구성해도 프로필의 허용 목록이 암묵적으로 넓어지지는 않습니다. 제한적인 프로필에서 해당 구성 섹션을 사용하려면 명시적 `tools.alsoAllow` 항목(예: exec용 `["exec", "process"]`, fs용 `["read", "write", "edit"]`)을 추가하세요. 구성 섹션이 있지만 일치하는 `alsoAllow` 권한이 없으면 OpenClaw는 시작 경고를 기록합니다. + + +`coding` 및 `messaging` 프로필은 Plugin 키 `bundle-mcp` 아래 구성된 번들 MCP 도구도 허용합니다. +프로필의 일반 기본 제공 도구는 유지하되 구성된 모든 MCP 도구를 숨기려면 `tools.deny: ["bundle-mcp"]`를 추가하세요. `minimal` 프로필에는 번들 MCP 도구가 포함되지 않습니다. @@ -197,21 +199,20 @@ Plugin은 추가 도구를 등록할 수 있습니다. 몇 가지 예는 다음 | `group:nodes` | nodes | | `group:agents` | agents_list | | `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | 모든 내장 OpenClaw 도구(Plugin 도구 제외) | +| `group:openclaw` | 모든 내장 OpenClaw 도구(Plugin 도구 제외) | -`sessions_history`는 범위가 제한되고 안전 필터링된 회상 보기를 반환합니다. 원시 트랜스크립트 덤프처럼 동작하는 대신, -사고 태그, `` 스캐폴딩, 일반 텍스트 도구 호출 XML +`sessions_history`는 범위가 제한되고 안전 필터링된 회상 보기를 반환합니다. 원시 기록 덤프로 +작동하는 대신, thinking 태그, `` 스캐폴딩, 일반 텍스트 도구 호출 XML 페이로드(`...`, `...`, `...`, -`...`, 잘린 도구 호출 블록 포함), -다운그레이드된 도구 호출 스캐폴딩, 유출된 ASCII/전각 모델 제어 -토큰, 어시스턴트 텍스트의 잘못된 MiniMax 도구 호출 XML을 제거한 뒤 -수정/잘림과 필요 시 과대 행 자리표시자를 적용합니다. +`...` 및 잘린 도구 호출 블록 포함), +강등된 도구 호출 스캐폴딩, 유출된 ASCII/전각 모델 제어 +토큰, 그리고 어시스턴트 텍스트의 잘못된 MiniMax 도구 호출 XML을 제거한 다음, +수정/잘라내기 및 가능한 과대 행 자리표시자를 적용합니다. -### 프로바이더별 제한 +### 제공자별 제한 사항 -전역 기본값을 변경하지 않고 특정 프로바이더의 도구를 제한하려면 -`tools.byProvider`를 사용하세요. +전역 기본값을 변경하지 않고 특정 제공자의 도구를 제한하려면 `tools.byProvider`를 사용하세요. ```json5 { diff --git a/docs/ko/tools/subagents.md b/docs/ko/tools/subagents.md index 516c9f8b0..08aac26cb 100644 --- a/docs/ko/tools/subagents.md +++ b/docs/ko/tools/subagents.md @@ -1,23 +1,23 @@ --- read_when: - - 에이전트를 통한 백그라운드 또는 병렬 작업을 원합니다 - - sessions_spawn 또는 하위 에이전트 도구 정책을 변경하는 중입니다 + - 에이전트를 통해 백그라운드 또는 병렬 작업을 수행하려는 경우 + - sessions_spawn 또는 하위 에이전트 도구 정책을 변경하고 있습니다 - 스레드에 바인딩된 하위 에이전트 세션을 구현하거나 문제를 해결하고 있습니다 sidebarTitle: Sub-agents -summary: 결과를 요청자 채팅으로 다시 알리는 격리된 백그라운드 에이전트 실행을 시작합니다 +summary: 격리된 백그라운드 에이전트 실행을 생성하고 결과를 요청자 채팅으로 다시 알립니다 title: 하위 에이전트 x-i18n: - generated_at: "2026-04-30T06:55:42Z" + generated_at: "2026-04-30T16:30:12Z" model: gpt-5.5 provider: openai - source_hash: 84386ea706873cf9f2ea03261f916c8fb01304999f2d9fa86e037e734a62bf7e + source_hash: c7c46d2c6d9ddac23653dcbfaf20df0ff5be9619035a1b115a3b49fd48fd8280 source_path: tools/subagents.md workflow: 16 --- -하위 에이전트는 기존 에이전트 실행에서 생성된 백그라운드 에이전트 실행입니다. +하위 에이전트는 기존 에이전트 실행에서 생성되는 백그라운드 에이전트 실행입니다. 각자의 세션(`agent::subagent:`)에서 실행되며, -완료되면 결과를 요청자 채팅 채널로 **알립니다**. +완료되면 요청자 채팅 채널로 결과를 **알립니다**. 각 하위 에이전트 실행은 [백그라운드 작업](/ko/automation/tasks)으로 추적됩니다. 주요 목표: @@ -28,14 +28,10 @@ x-i18n: - 오케스트레이터 패턴을 위한 구성 가능한 중첩 깊이를 지원합니다. -**비용 참고:** 기본적으로 각 하위 에이전트는 자체 컨텍스트와 토큰 사용량을 가집니다. -무겁거나 반복적인 작업에는 하위 에이전트에 더 저렴한 모델을 설정하고, -기본 에이전트는 더 높은 품질의 모델로 유지하세요. `agents.defaults.subagents.model` 또는 -에이전트별 재정의를 통해 구성합니다. 자식이 요청자의 현재 transcript를 실제로 필요로 하는 경우, -에이전트는 해당 spawn 한 번에 `context: "fork"`를 요청할 수 있습니다. +**비용 참고:** 각 하위 에이전트는 기본적으로 자체 컨텍스트와 토큰 사용량을 가집니다. 무겁거나 반복적인 작업의 경우 하위 에이전트에는 더 저렴한 모델을 설정하고, 기본 에이전트는 더 높은 품질의 모델로 유지하세요. `agents.defaults.subagents.model` 또는 에이전트별 재정의로 구성합니다. 자식이 요청자의 현재 transcript가 실제로 필요할 때는 해당 생성 한 번에 대해 에이전트가 `context: "fork"`를 요청할 수 있습니다. -## 슬래시 명령 +## Slash 명령 **현재 세션**의 하위 에이전트 실행을 검사하거나 제어하려면 `/subagents`를 사용하세요. @@ -49,14 +45,12 @@ x-i18n: /subagents spawn [--model ] [--thinking ] ``` -`/subagents info`는 실행 메타데이터(상태, 타임스탬프, 세션 id, -transcript 경로, 정리)를 표시합니다. 제한되고 안전 필터링된 회상 보기는 -`sessions_history`를 사용하세요. 원시 전체 transcript가 필요하면 디스크의 transcript 경로를 검사하세요. +`/subagents info`는 실행 메타데이터(상태, 타임스탬프, 세션 id, transcript 경로, 정리)를 표시합니다. 제한된 안전 필터링 회상 보기는 `sessions_history`를 사용하세요. 원시 전체 transcript가 필요할 때는 디스크의 transcript 경로를 검사하세요. ### 스레드 바인딩 제어 -이 명령은 지속 스레드 바인딩을 지원하는 채널에서 작동합니다. -아래의 [스레드 지원 채널](#thread-supporting-channels)을 참조하세요. +이 명령은 지속적 스레드 바인딩을 지원하는 채널에서 작동합니다. +아래 [스레드 지원 채널](#thread-supporting-channels)을 참고하세요. ```text /focus @@ -66,74 +60,66 @@ transcript 경로, 정리)를 표시합니다. 제한되고 안전 필터링된 /session max-age ``` -### Spawn 동작 +### 생성 동작 -`/subagents spawn`은 백그라운드 하위 에이전트를 사용자 명령(내부 릴레이가 아님)으로 시작하고, -실행이 완료되면 요청자 채팅으로 최종 완료 업데이트 하나를 보냅니다. +`/subagents spawn`은 내부 릴레이가 아닌 사용자 명령으로 백그라운드 하위 에이전트를 시작하고, 실행이 완료되면 요청자 채팅으로 최종 완료 업데이트 하나를 보냅니다. - - - spawn 명령은 차단하지 않으며, 즉시 실행 id를 반환합니다. - - 완료 시 하위 에이전트는 요약/결과 메시지를 요청자 채팅 채널로 알립니다. - - 완료는 푸시 기반입니다. spawn된 뒤에는 완료를 기다리기 위해 `/subagents list`, `sessions_list`, 또는 `sessions_history`를 루프로 폴링하지 마세요. 상태는 디버깅이나 개입이 필요할 때만 확인하세요. - - 완료 시 OpenClaw는 알림 정리 흐름을 계속하기 전에 해당 하위 에이전트 세션이 연 추적된 브라우저 탭/프로세스를 최선의 노력으로 닫습니다. + + - 생성 명령은 비차단입니다. 즉시 실행 id를 반환합니다. + - 완료 시 하위 에이전트는 요청자 채팅 채널로 요약/결과 메시지를 알립니다. + - 완료는 푸시 기반입니다. 생성한 뒤에는 완료를 기다리기 위해 `/subagents list`, `sessions_list`, 또는 `sessions_history`를 루프에서 폴링하지 마세요. 디버깅이나 개입을 위해 필요할 때만 상태를 검사하세요. + - 완료 시 OpenClaw는 알림 정리 흐름이 계속되기 전에 해당 하위 에이전트 세션이 연 추적된 브라우저 탭/프로세스를 최선의 노력으로 닫습니다. - - - OpenClaw는 안정적인 멱등성 키로 먼저 직접 `agent` 전달을 시도합니다. + + - OpenClaw는 안정적인 멱등성 키로 직접 `agent` 전달을 먼저 시도합니다. - 직접 전달이 실패하면 큐 라우팅으로 폴백합니다. - 큐 라우팅도 아직 사용할 수 없으면 최종 포기 전에 짧은 지수 백오프로 알림을 재시도합니다. - - 완료 전달은 해석된 요청자 경로를 유지합니다. 스레드 바인딩 또는 대화 바인딩 완료 경로가 사용 가능하면 우선합니다. 완료 원본이 채널만 제공하는 경우, OpenClaw는 요청자 세션의 해석된 경로(`lastChannel` / `lastTo` / `lastAccountId`)에서 누락된 target/account를 채워 직접 전달이 계속 작동하게 합니다. + - 완료 전달은 해석된 요청자 경로를 유지합니다. 스레드 바인딩 또는 대화 바인딩 완료 경로가 사용 가능하면 우선하며, 완료 출처가 채널만 제공하는 경우 OpenClaw는 요청자 세션의 해석된 경로(`lastChannel` / `lastTo` / `lastAccountId`)에서 누락된 대상/계정을 채워 직접 전달이 계속 작동하도록 합니다. - 요청자 세션으로의 완료 인계는 런타임에서 생성된 내부 컨텍스트(사용자가 작성한 텍스트 아님)이며 다음을 포함합니다. + 요청자 세션으로의 완료 인계는 런타임에서 생성된 내부 컨텍스트(사용자가 작성한 텍스트가 아님)이며 다음을 포함합니다. - - `Result` — 최신 표시 `assistant` 응답 텍스트. 없으면 정리된 최신 tool/toolResult 텍스트입니다. 터미널 실패 실행은 캡처된 응답 텍스트를 재사용하지 않습니다. + - `Result` — 최신으로 표시된 `assistant` 응답 텍스트, 없으면 정리된 최신 tool/toolResult 텍스트. 터미널 실패 실행은 캡처된 응답 텍스트를 재사용하지 않습니다. - `Status` — `completed successfully` / `failed` / `timed out` / `unknown`. - 간결한 런타임/토큰 통계. - - 요청자 에이전트에게 원시 내부 메타데이터를 전달하지 말고 일반 assistant 음성으로 다시 작성하라고 지시하는 전달 지침. + - 요청자 에이전트가 원시 내부 메타데이터를 전달하지 않고 일반 assistant 음성으로 다시 작성하도록 지시하는 전달 지침. - `--model`과 `--thinking`은 해당 특정 실행의 기본값을 재정의합니다. - 완료 후 세부 정보와 출력을 검사하려면 `info`/`log`를 사용하세요. - - `/subagents spawn`은 일회성 모드(`mode: "run"`)입니다. 지속 스레드 바인딩 세션에는 `thread: true` 및 `mode: "session"`과 함께 `sessions_spawn`을 사용하세요. - - ACP harness 세션(Claude Code, Gemini CLI, OpenCode, 또는 명시적 Codex ACP/acpx)의 경우, 도구가 해당 런타임을 광고할 때 `runtime: "acp"`와 함께 `sessions_spawn`을 사용하세요. 완료 또는 에이전트 간 루프를 디버깅할 때는 [ACP 전달 모델](/ko/tools/acp-agents#delivery-model)을 참조하세요. `codex` Plugin이 활성화된 경우, 사용자가 명시적으로 ACP/acpx를 요청하지 않는 한 Codex 채팅/스레드 제어는 ACP보다 `/codex ...`를 선호해야 합니다. - - OpenClaw는 ACP가 활성화되고, 요청자가 샌드박싱되지 않았으며, `acpx` 같은 백엔드 Plugin이 로드될 때까지 `runtime: "acp"`를 숨깁니다. `runtime: "acp"`는 외부 ACP harness id 또는 `runtime.type="acp"`가 있는 `agents.list[]` 항목을 기대합니다. `agents_list`의 일반 OpenClaw 구성 에이전트에는 기본 하위 에이전트 런타임을 사용하세요. + - `/subagents spawn`은 일회성 모드(`mode: "run"`)입니다. 지속적 스레드 바인딩 세션의 경우 `thread: true` 및 `mode: "session"`으로 `sessions_spawn`을 사용하세요. + - ACP 하네스 세션(Claude Code, Gemini CLI, OpenCode, 또는 명시적 Codex ACP/acpx)의 경우 도구가 해당 런타임을 광고할 때 `runtime: "acp"`로 `sessions_spawn`을 사용하세요. 완료 또는 에이전트 간 루프를 디버깅할 때는 [ACP 전달 모델](/ko/tools/acp-agents#delivery-model)을 참고하세요. `codex` Plugin이 활성화된 경우, 사용자가 ACP/acpx를 명시적으로 요청하지 않는 한 Codex 채팅/스레드 제어는 ACP보다 `/codex ...`를 선호해야 합니다. + - OpenClaw는 ACP가 활성화되고, 요청자가 샌드박스 처리되지 않았으며, `acpx` 같은 백엔드 Plugin이 로드될 때까지 `runtime: "acp"`를 숨깁니다. `runtime: "acp"`는 외부 ACP 하네스 id 또는 `runtime.type="acp"`가 있는 `agents.list[]` 항목을 기대합니다. `agents_list`의 일반 OpenClaw 구성 에이전트에는 기본 하위 에이전트 런타임을 사용하세요. ## 컨텍스트 모드 -네이티브 하위 에이전트는 호출자가 현재 transcript를 fork하도록 명시적으로 요청하지 않는 한 격리된 상태로 시작합니다. +네이티브 하위 에이전트는 호출자가 현재 transcript의 포크를 명시적으로 요청하지 않는 한 격리된 상태로 시작합니다. | 모드 | 사용 시점 | 동작 | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `isolated` | 새로운 조사, 독립 구현, 느린 도구 작업, 또는 작업 텍스트로 요약 설명할 수 있는 모든 것 | 깨끗한 자식 transcript를 생성합니다. 이것이 기본값이며 토큰 사용량을 낮게 유지합니다. | -| `fork` | 현재 대화, 이전 도구 결과, 또는 요청자 transcript에 이미 있는 섬세한 지침에 의존하는 작업 | 자식이 시작되기 전에 요청자 transcript를 자식 세션으로 분기합니다. | +| `isolated` | 새로운 조사, 독립 구현, 느린 도구 작업, 또는 작업 텍스트로 브리핑할 수 있는 모든 것 | 깨끗한 자식 transcript를 만듭니다. 이것이 기본값이며 토큰 사용량을 낮게 유지합니다. | +| `fork` | 현재 대화, 이전 도구 결과, 또는 요청자 transcript에 이미 있는 미묘한 지침에 의존하는 작업 | 자식이 시작되기 전에 요청자 transcript를 자식 세션으로 분기합니다. | -`fork`는 아껴서 사용하세요. 이는 컨텍스트에 민감한 위임을 위한 것이지, -명확한 작업 프롬프트 작성의 대체물이 아닙니다. +`fork`는 아껴서 사용하세요. 이는 컨텍스트에 민감한 위임을 위한 것이며, 명확한 작업 프롬프트 작성을 대체하지 않습니다. ## 도구: `sessions_spawn` -전역 `subagent` 레인에서 `deliver: false`로 하위 에이전트 실행을 시작한 다음, -알림 단계를 실행하고 알림 응답을 요청자 채팅 채널에 게시합니다. +전역 `subagent` 레인에서 `deliver: false`로 하위 에이전트 실행을 시작한 다음, 알림 단계를 실행하고 알림 응답을 요청자 채팅 채널에 게시합니다. -사용 가능 여부는 호출자의 유효 도구 정책에 따라 달라집니다. `coding` 및 -`full` 프로필은 기본적으로 `sessions_spawn`을 노출합니다. `messaging` 프로필은 -노출하지 않습니다. 작업을 위임해야 하는 에이전트에는 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", -"subagents"]`를 추가하거나 `tools.profile: "coding"`을 사용하세요. -채널/그룹, 제공자, 샌드박스, 에이전트별 허용/거부 정책은 프로필 단계 이후에도 -도구를 제거할 수 있습니다. 동일 세션에서 `/tools`를 사용해 유효 도구 목록을 확인하세요. +가용성은 호출자의 유효 도구 정책에 따라 달라집니다. `coding` 및 `full` 프로필은 기본적으로 `sessions_spawn`을 노출합니다. `messaging` 프로필은 그렇지 않습니다. 작업을 위임해야 하는 에이전트에는 `tools.alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"]`를 추가하거나 `tools.profile: "coding"`을 사용하세요. 채널/그룹, 공급자, 샌드박스, 에이전트별 허용/거부 정책은 프로필 단계 이후에도 도구를 제거할 수 있습니다. 유효 도구 목록을 확인하려면 같은 세션에서 `/tools`를 사용하세요. **기본값:** -- **모델:** `agents.defaults.subagents.model`(또는 에이전트별 `agents.list[].subagents.model`)을 설정하지 않으면 호출자를 상속합니다. 명시적 `sessions_spawn.model`이 여전히 우선합니다. -- **Thinking:** `agents.defaults.subagents.thinking`(또는 에이전트별 `agents.list[].subagents.thinking`)을 설정하지 않으면 호출자를 상속합니다. 명시적 `sessions_spawn.thinking`이 여전히 우선합니다. -- **실행 타임아웃:** `sessions_spawn.runTimeoutSeconds`가 생략되면, OpenClaw는 설정된 경우 `agents.defaults.subagents.runTimeoutSeconds`를 사용합니다. 그렇지 않으면 `0`(타임아웃 없음)으로 폴백합니다. +- **모델:** `agents.defaults.subagents.model`(또는 에이전트별 `agents.list[].subagents.model`)을 설정하지 않는 한 호출자를 상속합니다. 명시적 `sessions_spawn.model`이 여전히 우선합니다. +- **Thinking:** `agents.defaults.subagents.thinking`(또는 에이전트별 `agents.list[].subagents.thinking`)을 설정하지 않는 한 호출자를 상속합니다. 명시적 `sessions_spawn.thinking`이 여전히 우선합니다. +- **실행 제한 시간:** `sessions_spawn.runTimeoutSeconds`가 생략되면 OpenClaw는 설정된 경우 `agents.defaults.subagents.runTimeoutSeconds`를 사용합니다. 그렇지 않으면 `0`(제한 시간 없음)으로 폴백합니다. ### 도구 매개변수 @@ -141,79 +127,70 @@ transcript 경로, 정리)를 표시합니다. 제한되고 안전 필터링된 하위 에이전트의 작업 설명입니다. - 선택적 사람이 읽기 쉬운 레이블입니다. + 선택적 사람이 읽을 수 있는 레이블입니다. - `subagents.allowAgents`에서 허용할 때 다른 에이전트 id 아래에서 spawn합니다. + `subagents.allowAgents`에서 허용하는 경우 다른 에이전트 id 아래에 생성합니다. - `acp`는 외부 ACP harness(`claude`, `droid`, `gemini`, `opencode`, 또는 명시적으로 요청된 Codex ACP/acpx) 및 `runtime.type`이 `acp`인 `agents.list[]` 항목에만 사용합니다. + `acp`는 외부 ACP 하네스(`claude`, `droid`, `gemini`, `opencode`, 또는 명시적으로 요청된 Codex ACP/acpx)와 `runtime.type`이 `acp`인 `agents.list[]` 항목에만 사용됩니다. - ACP 전용입니다. `runtime: "acp"`일 때 기존 ACP harness 세션을 재개합니다. 네이티브 하위 에이전트 spawn에서는 무시됩니다. + ACP 전용. `runtime: "acp"`일 때 기존 ACP 하네스 세션을 재개합니다. 네이티브 하위 에이전트 생성에는 무시됩니다. - ACP 전용입니다. `runtime: "acp"`일 때 ACP 실행 출력을 부모 세션으로 스트리밍합니다. 네이티브 하위 에이전트 spawn에서는 생략하세요. + ACP 전용. `runtime: "acp"`일 때 ACP 실행 출력을 부모 세션으로 스트리밍합니다. 네이티브 하위 에이전트 생성에서는 생략하세요. - 하위 에이전트 모델을 재정의합니다. 잘못된 값은 건너뛰며, 하위 에이전트는 도구 결과에 경고를 남기고 기본 모델로 실행됩니다. + 하위 에이전트 모델을 재정의합니다. 유효하지 않은 값은 건너뛰며, 하위 에이전트는 도구 결과에 경고를 남기고 기본 모델에서 실행됩니다. 하위 에이전트 실행의 thinking 수준을 재정의합니다. - 설정된 경우 기본값은 `agents.defaults.subagents.runTimeoutSeconds`이고, 그렇지 않으면 `0`입니다. 설정되면 하위 에이전트 실행은 N초 후 중단됩니다. + 설정된 경우 기본값은 `agents.defaults.subagents.runTimeoutSeconds`이며, 그렇지 않으면 `0`입니다. 설정하면 하위 에이전트 실행이 N초 후 중단됩니다. `true`이면 이 하위 에이전트 세션에 채널 스레드 바인딩을 요청합니다. - `thread: true`이고 `mode`가 생략되면 기본값은 `session`이 됩니다. `mode: "session"`은 `thread: true`가 필요합니다. + `thread: true`이고 `mode`가 생략되면 기본값은 `session`이 됩니다. `mode: "session"`에는 `thread: true`가 필요합니다. - `"delete"`는 알림 직후 보관합니다(transcript는 이름 변경을 통해 계속 유지). + `"delete"`는 알림 직후 보관합니다(이름 변경을 통해 transcript는 계속 유지). - `require`는 대상 자식 런타임이 샌드박싱되지 않은 경우 spawn을 거부합니다. + `require`는 대상 자식 런타임이 샌드박스 처리되지 않은 경우 생성을 거부합니다. - `fork`는 요청자의 현재 transcript를 자식 세션으로 분기합니다. 네이티브 하위 에이전트 전용입니다. 자식이 현재 transcript를 필요로 할 때만 `fork`를 사용하세요. + `fork`는 요청자의 현재 transcript를 자식 세션으로 분기합니다. 네이티브 하위 에이전트 전용입니다. 자식에 현재 transcript가 필요한 경우에만 `fork`를 사용하세요. -`sessions_spawn`은 채널 전달 매개변수(`target`, -`channel`, `to`, `threadId`, `replyTo`, `transport`)를 허용하지 않습니다. 전달에는 spawn된 실행에서 -`message`/`sessions_send`를 사용하세요. +`sessions_spawn`은 채널 전달 매개변수(`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`)를 받지 않습니다. 전달에는 생성된 실행에서 `message`/`sessions_send`를 사용하세요. ## 스레드 바인딩 세션 -채널에 스레드 바인딩이 활성화된 경우, 하위 에이전트는 스레드에 바인딩된 상태를 유지할 수 있어 -해당 스레드의 후속 사용자 메시지가 같은 하위 에이전트 세션으로 계속 라우팅됩니다. +채널에 스레드 바인딩이 활성화되어 있으면 하위 에이전트는 스레드에 바인딩된 상태로 유지될 수 있으므로, 해당 스레드의 후속 사용자 메시지가 같은 하위 에이전트 세션으로 계속 라우팅됩니다. ### 스레드 지원 채널 -**Discord**는 현재 유일하게 지원되는 채널입니다. 지속 스레드 바인딩 하위 에이전트 세션(`thread: true`와 함께 `sessions_spawn`), -수동 스레드 제어(`/focus`, `/unfocus`, `/agents`, -`/session idle`, `/session max-age`) 및 어댑터 키 -`channels.discord.threadBindings.enabled`, -`channels.discord.threadBindings.idleHours`, -`channels.discord.threadBindings.maxAgeHours`, 그리고 -`channels.discord.threadBindings.spawnSubagentSessions`를 지원합니다. +**Discord**는 현재 유일하게 지원되는 채널입니다. 지속적 스레드 바인딩 하위 에이전트 세션(`thread: true`로 `sessions_spawn`), 수동 스레드 제어(`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`), 그리고 어댑터 키 `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`, `channels.discord.threadBindings.spawnSubagentSessions`를 지원합니다. ### 빠른 흐름 - - `thread: true`(그리고 선택적으로 `mode: "session"`)와 함께 `sessions_spawn`을 실행합니다. + + `thread: true`(그리고 선택적으로 `mode: "session"`)로 `sessions_spawn`. - OpenClaw는 활성 채널에서 해당 세션 대상으로 스레드를 생성하거나 바인딩합니다. + OpenClaw는 활성 채널에서 해당 세션 대상으로 스레드를 만들거나 바인딩합니다. 해당 스레드의 응답과 후속 메시지는 바인딩된 세션으로 라우팅됩니다. - + 비활성 자동 unfocus를 검사/업데이트하려면 `/session idle`을 사용하고, 하드 캡을 제어하려면 `/session max-age`를 사용하세요. @@ -224,57 +201,58 @@ transcript 경로, 정리)를 표시합니다. 제한되고 안전 필터링된 ### 수동 제어 -| 명령 | 효과 | -| ------------------ | ---------------------------------------------------------------------- | -| `/focus ` | 현재 스레드를 하위 에이전트/세션 대상에 바인딩하거나 새로 만듭니다 | -| `/unfocus` | 현재 바인딩된 스레드의 바인딩을 제거합니다 | -| `/agents` | 활성 실행과 바인딩 상태(`thread:` 또는 `unbound`)를 나열합니다 | -| `/session idle` | 유휴 자동 언포커스를 확인/업데이트합니다(포커스된 바인딩 스레드만 해당) | -| `/session max-age` | 하드 캡을 확인/업데이트합니다(포커스된 바인딩 스레드만 해당) | +| 명령 | 효과 | +| ------------------ | --------------------------------------------------------------------- | +| `/focus ` | 현재 스레드(또는 새로 생성한 스레드)를 sub-agent/세션 대상에 바인딩 | +| `/unfocus` | 현재 바인딩된 스레드의 바인딩 제거 | +| `/agents` | 활성 실행과 바인딩 상태(`thread:` 또는 `unbound`) 나열 | +| `/session idle` | 유휴 자동 언포커스 확인/업데이트(포커스된 바인딩 스레드만 해당) | +| `/session max-age` | 하드 제한 확인/업데이트(포커스된 바인딩 스레드만 해당) | ### 구성 스위치 - **전역 기본값:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. -- **채널 오버라이드 및 스폰 자동 바인딩 키**는 어댑터별로 다릅니다. 위의 [스레드를 지원하는 채널](#thread-supporting-channels)을 참조하세요. +- **채널 재정의 및 생성 시 자동 바인딩 키**는 어댑터별로 다릅니다. 위의 [스레드를 지원하는 채널](#thread-supporting-channels)을 참조하세요. -현재 어댑터 세부 정보는 [구성 참조](/ko/gateway/configuration-reference)와 +현재 어댑터 세부 정보는 [구성 참조](/ko/gateway/configuration-reference) 및 [슬래시 명령](/ko/tools/slash-commands)을 참조하세요. ### 허용 목록 - 명시적 `agentId`를 통해 대상으로 지정할 수 있는 에이전트 ID 목록입니다(`["*"]`는 모두 허용). 기본값: 요청자 에이전트만. 목록을 설정한 뒤에도 요청자가 `agentId`로 자신을 스폰할 수 있게 하려면 요청자 ID를 목록에 포함하세요. + 명시적 `agentId`를 통해 대상으로 지정할 수 있는 agent ID 목록입니다(`["*"]`는 모두 허용). 기본값: 요청자 agent만 해당합니다. 목록을 설정하면서도 요청자가 `agentId`로 자기 자신을 생성할 수 있게 하려면 요청자 ID를 목록에 포함하세요. - 요청자 에이전트가 자체 `subagents.allowAgents`를 설정하지 않았을 때 사용되는 기본 대상 에이전트 허용 목록입니다. + 요청자 agent가 자체 `subagents.allowAgents`를 설정하지 않을 때 사용되는 기본 대상 agent 허용 목록입니다. - `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적 프로필 선택을 강제). 에이전트별 오버라이드: `agents.list[].subagents.requireAgentId`. + `agentId`를 생략한 `sessions_spawn` 호출을 차단합니다(명시적 프로필 선택 강제). agent별 재정의: `agents.list[].subagents.requireAgentId`. -요청자 세션이 샌드박스 처리된 경우, `sessions_spawn`은 샌드박스 없이 실행될 대상을 거부합니다. +요청자 세션이 샌드박스 처리된 경우, `sessions_spawn`은 +샌드박스 없이 실행될 대상을 거부합니다. -### 검색 +### 탐색 -`sessions_spawn`에 현재 허용된 에이전트 ID를 확인하려면 `agents_list`를 사용하세요. 응답에는 나열된 각 에이전트의 유효 -모델과 포함된 런타임 메타데이터가 포함되어 호출자가 PI, Codex -앱 서버, 기타 구성된 네이티브 런타임을 구분할 수 있습니다. +`sessions_spawn`에 현재 허용된 agent ID를 확인하려면 `agents_list`를 사용하세요. +응답에는 나열된 각 agent의 유효 모델과 내장 런타임 메타데이터가 포함되어, +호출자가 PI, Codex app-server 및 기타 구성된 네이티브 런타임을 구분할 수 있습니다. -### 자동 보관 +### 자동 아카이브 -- 하위 에이전트 세션은 `agents.defaults.subagents.archiveAfterMinutes` 이후 자동으로 보관됩니다(기본값 `60`). -- 보관은 `sessions.delete`를 사용하고 transcript 이름을 `*.deleted.`로 변경합니다(동일 폴더). -- `cleanup: "delete"`는 알림 직후 즉시 보관합니다(이름 변경을 통해 transcript는 계속 유지). -- 자동 보관은 최선의 노력 방식입니다. Gateway가 다시 시작되면 보류 중인 타이머는 손실됩니다. -- `runTimeoutSeconds`는 자동 보관을 수행하지 않으며, 실행만 중지합니다. 세션은 자동 보관 전까지 남아 있습니다. -- 자동 보관은 depth-1 및 depth-2 세션에 동일하게 적용됩니다. -- 브라우저 정리는 보관 정리와 별개입니다. 추적된 브라우저 탭/프로세스는 transcript/세션 레코드가 유지되더라도 실행이 끝나면 최선의 노력 방식으로 닫힙니다. +- Sub-agent 세션은 `agents.defaults.subagents.archiveAfterMinutes` 이후 자동으로 아카이브됩니다(기본값 `60`). +- 아카이브는 `sessions.delete`를 사용하며 transcript 이름을 `*.deleted.`로 변경합니다(같은 폴더). +- `cleanup: "delete"`는 공지 직후 즉시 아카이브합니다(transcript는 이름 변경으로 계속 보존). +- 자동 아카이브는 최선형 작업입니다. Gateway가 다시 시작되면 대기 중인 타이머는 손실됩니다. +- `runTimeoutSeconds`는 자동 아카이브를 수행하지 않습니다. 실행만 중지합니다. 세션은 자동 아카이브 전까지 남아 있습니다. +- 자동 아카이브는 depth-1 및 depth-2 세션에 동일하게 적용됩니다. +- 브라우저 정리는 아카이브 정리와 별개입니다. 추적 중인 브라우저 탭/프로세스는 transcript/세션 레코드가 유지되더라도 실행이 끝나면 최선형으로 닫힙니다. -## 중첩 하위 에이전트 +## 중첩된 sub-agent -기본적으로 하위 에이전트는 자체 하위 에이전트를 스폰할 수 없습니다 -(`maxSpawnDepth: 1`). 한 단계의 중첩을 활성화하려면 `maxSpawnDepth: 2`를 설정하세요. 이는 **오케스트레이터 패턴**입니다: 메인 → 오케스트레이터 하위 에이전트 → -작업자 하위-하위 에이전트. +기본적으로 sub-agent는 자체 sub-agent를 생성할 수 없습니다 +(`maxSpawnDepth: 1`). 한 단계의 중첩을 활성화하려면 `maxSpawnDepth: 2`를 설정하세요. 즉 **오케스트레이터 패턴**입니다: main → orchestrator sub-agent → +worker sub-sub-agents. ```json5 { @@ -291,137 +269,136 @@ transcript 경로, 정리)를 표시합니다. 제한되고 안전 필터링된 } ``` -### Depth 수준 +### 깊이 수준 -| Depth | 세션 키 형태 | 역할 | 스폰 가능 여부 | -| ----- | --------------------------------------------- | ---------------------------------------------- | ----------------------------- | -| 0 | `agent::main` | 메인 에이전트 | 항상 | -| 1 | `agent::subagent:` | 하위 에이전트(depth 2가 허용되면 오케스트레이터) | `maxSpawnDepth >= 2`인 경우만 | -| 2 | `agent::subagent::subagent:` | 하위-하위 에이전트(리프 작업자) | 절대 불가 | +| 깊이 | 세션 키 형태 | 역할 | 생성 가능 여부 | +| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- | +| 0 | `agent::main` | 메인 agent | 항상 | +| 1 | `agent::subagent:` | Sub-agent(depth 2가 허용되면 orchestrator) | `maxSpawnDepth >= 2`인 경우만 | +| 2 | `agent::subagent::subagent:` | Sub-sub-agent(leaf worker) | 절대 불가 | -### 알림 체인 +### 공지 체인 결과는 체인을 따라 위로 전달됩니다. -1. Depth-2 작업자가 완료 → 부모(depth-1 오케스트레이터)에 알림. -2. Depth-1 오케스트레이터가 알림을 수신하고, 결과를 종합한 뒤 완료 → 메인에 알림. -3. 메인 에이전트가 알림을 수신하고 사용자에게 전달. +1. Depth-2 worker가 완료됨 → 부모(depth-1 orchestrator)에게 공지합니다. +2. Depth-1 orchestrator가 공지를 받고 결과를 종합한 뒤 완료됨 → main에 공지합니다. +3. Main agent가 공지를 받고 사용자에게 전달합니다. -각 수준은 직접 자식의 알림만 볼 수 있습니다. +각 수준은 자신의 직접 자식이 보낸 공지만 볼 수 있습니다. **운영 지침:** `sessions_list`, -`sessions_history`, `/subagents list`, 또는 `exec` sleep 명령을 중심으로 폴링 루프를 만들기보다 자식 작업을 한 번 시작하고 완료 -이벤트를 기다리세요. -`sessions_list`와 `/subagents list`는 자식 세션 관계를 -라이브 작업에 집중시킵니다. 라이브 자식은 계속 연결된 상태로 남고, 종료된 자식은 짧은 최근 창 동안 표시되며, 오래된 저장소 전용 자식 링크는 -신선도 창이 지난 뒤 무시됩니다. 이렇게 하면 재시작 후 오래된 `spawnedBy` / -`parentSessionKey` 메타데이터가 유령 자식을 되살리는 것을 방지할 수 있습니다. 이미 -최종 답변을 보낸 뒤 자식 완료 이벤트가 도착하면 올바른 후속 응답은 정확한 무음 토큰 +`sessions_history`, `/subagents list` 또는 `exec` sleep 명령을 중심으로 폴링 루프를 만들지 말고, 자식 작업을 한 번 시작한 다음 완료 이벤트를 기다리세요. +`sessions_list` 및 `/subagents list`는 자식 세션 관계를 +라이브 작업 중심으로 유지합니다. 라이브 자식은 계속 연결되어 있고, 종료된 자식은 짧은 최근 창 동안 표시되며, 오래된 저장소 전용 자식 링크는 freshness 창이 지난 뒤 무시됩니다. 이렇게 하면 재시작 후 오래된 `spawnedBy` / +`parentSessionKey` 메타데이터가 유령 자식을 되살리는 일을 방지합니다. 이미 최종 답변을 보낸 뒤 자식 완료 이벤트가 도착하면 올바른 후속 응답은 정확한 무응답 토큰 `NO_REPLY` / `no_reply`입니다. -### Depth별 도구 정책 +### 깊이별 도구 정책 -- 역할과 제어 범위는 스폰 시점에 세션 메타데이터에 기록됩니다. 이를 통해 플랫하거나 복원된 세션 키가 실수로 오케스트레이터 권한을 다시 얻지 않도록 합니다. -- **Depth 1(오케스트레이터, `maxSpawnDepth >= 2`인 경우):** 자식을 관리할 수 있도록 `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`를 받습니다. 다른 세션/시스템 도구는 계속 거부됩니다. -- **Depth 1(리프, `maxSpawnDepth == 1`인 경우):** 세션 도구 없음(현재 기본 동작). -- **Depth 2(리프 작업자):** 세션 도구 없음. `sessions_spawn`은 depth 2에서 항상 거부됩니다. 더 이상의 자식을 스폰할 수 없습니다. +- 역할과 제어 범위는 생성 시 세션 메타데이터에 기록됩니다. 이를 통해 평면화되었거나 복원된 세션 키가 실수로 orchestrator 권한을 다시 얻지 않게 합니다. +- **Depth 1(orchestrator, `maxSpawnDepth >= 2`인 경우):** 자식을 관리할 수 있도록 `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`를 받습니다. 다른 세션/시스템 도구는 계속 거부됩니다. +- **Depth 1(leaf, `maxSpawnDepth == 1`인 경우):** 세션 도구가 없습니다(현재 기본 동작). +- **Depth 2(leaf worker):** 세션 도구가 없습니다. `sessions_spawn`은 depth 2에서 항상 거부됩니다. 더 이상 자식을 생성할 수 없습니다. -### 에이전트별 스폰 제한 +### agent별 생성 제한 -각 에이전트 세션(모든 depth)은 동시에 최대 `maxChildrenPerAgent` -(기본값 `5`)개의 활성 자식을 가질 수 있습니다. 이는 단일 오케스트레이터에서 발생하는 제어 불능 팬아웃을 방지합니다. +각 agent 세션(어느 깊이든)은 동시에 최대 `maxChildrenPerAgent` +(기본값 `5`)개의 활성 자식을 가질 수 있습니다. 이는 단일 orchestrator에서 무제한 fan-out이 발생하는 것을 방지합니다. ### 연쇄 중지 -depth-1 오케스트레이터를 중지하면 모든 depth-2 자식도 자동으로 중지됩니다. +Depth-1 orchestrator를 중지하면 모든 depth-2 자식도 자동으로 중지됩니다. -- 메인 채팅의 `/stop`은 모든 depth-1 에이전트를 중지하고 해당 depth-2 자식까지 연쇄 중지합니다. -- `/subagents kill `는 특정 하위 에이전트를 중지하고 해당 자식까지 연쇄 중지합니다. -- `/subagents kill all`은 요청자의 모든 하위 에이전트를 중지하고 연쇄 중지합니다. +- 메인 채팅의 `/stop`은 모든 depth-1 agent를 중지하고 그들의 depth-2 자식까지 연쇄 중지합니다. +- `/subagents kill `는 특정 sub-agent를 중지하고 그 자식까지 연쇄 중지합니다. +- `/subagents kill all`은 요청자의 모든 sub-agent를 중지하고 연쇄 중지합니다. ## 인증 -하위 에이전트 인증은 세션 유형이 아니라 **에이전트 ID**로 결정됩니다. +Sub-agent 인증은 세션 유형이 아니라 **agent ID**로 해석됩니다. -- 하위 에이전트 세션 키는 `agent::subagent:`입니다. -- 인증 저장소는 해당 에이전트의 `agentDir`에서 로드됩니다. -- 메인 에이전트의 인증 프로필은 **fallback**으로 병합되며, 충돌 시 에이전트 프로필이 메인 프로필보다 우선합니다. +- Sub-agent 세션 키는 `agent::subagent:`입니다. +- 인증 저장소는 해당 agent의 `agentDir`에서 로드됩니다. +- 메인 agent의 인증 프로필은 **fallback**으로 병합됩니다. 충돌 시 agent 프로필이 메인 프로필보다 우선합니다. -병합은 추가 방식이므로 메인 프로필은 항상 fallback으로 사용할 수 있습니다. 에이전트별 완전 격리 인증은 아직 지원되지 않습니다. +병합은 추가 방식이므로, 메인 프로필은 항상 fallback으로 사용할 수 있습니다. +agent별 완전 격리 인증은 아직 지원되지 않습니다. -## 알림 +## 공지 -하위 에이전트는 알림 단계를 통해 보고합니다. +Sub-agent는 공지 단계를 통해 보고합니다. -- 알림 단계는 요청자 세션이 아니라 하위 에이전트 세션 내부에서 실행됩니다. -- 하위 에이전트가 정확히 `ANNOUNCE_SKIP`으로 응답하면 아무것도 게시되지 않습니다. -- 최신 어시스턴트 텍스트가 정확한 무음 토큰 `NO_REPLY` / `no_reply`이면 이전에 표시된 진행 상황이 있었더라도 알림 출력이 억제됩니다. +- 공지 단계는 요청자 세션이 아니라 sub-agent 세션 내부에서 실행됩니다. +- Sub-agent가 정확히 `ANNOUNCE_SKIP`으로 응답하면 아무것도 게시되지 않습니다. +- 최신 assistant 텍스트가 정확한 무응답 토큰 `NO_REPLY` / `no_reply`이면, 이전에 보이는 진행 상황이 있었더라도 공지 출력은 억제됩니다. -전달은 요청자 depth에 따라 달라집니다. +전달 방식은 요청자 깊이에 따라 달라집니다. -- 최상위 요청자 세션은 외부 전달(`deliver=true`)이 포함된 후속 `agent` 호출을 사용합니다. -- 중첩 요청자 하위 에이전트 세션은 내부 후속 주입(`deliver=false`)을 수신하므로 오케스트레이터가 세션 내에서 자식 결과를 종합할 수 있습니다. -- 중첩 요청자 하위 에이전트 세션이 사라진 경우, 가능하면 OpenClaw는 해당 세션의 요청자로 fallback합니다. +- 최상위 요청자 세션은 외부 전달(`deliver=true`)이 있는 후속 `agent` 호출을 사용합니다. +- 중첩된 요청자 subagent 세션은 내부 후속 주입(`deliver=false`)을 받아 orchestrator가 세션 안에서 자식 결과를 종합할 수 있습니다. +- 중첩된 요청자 subagent 세션이 사라진 경우, OpenClaw는 가능하면 해당 세션의 요청자로 fallback합니다. -최상위 요청자 세션의 경우 완료 모드 직접 전달은 먼저 바인딩된 대화/스레드 경로와 훅 오버라이드를 확인한 다음, 요청자 세션의 저장된 경로에서 누락된 채널 대상 필드를 채웁니다. -이렇게 하면 완료 원본이 채널만 식별하더라도 올바른 채팅/주제로 완료가 유지됩니다. +최상위 요청자 세션의 경우, completion-mode 직접 전달은 먼저 바인딩된 대화/스레드 경로와 hook 재정의를 해석한 다음, 누락된 채널 대상 필드를 요청자 세션에 저장된 경로로 채웁니다. +이를 통해 completion 출처가 채널만 식별하더라도 completion이 올바른 채팅/토픽에 유지됩니다. -중첩 완료 결과를 만들 때 자식 완료 집계는 현재 요청자 실행으로 범위가 제한되어, 이전 실행의 오래된 자식 출력이 현재 알림으로 누출되는 것을 방지합니다. 알림 응답은 채널 어댑터에서 사용 가능한 경우 스레드/주제 라우팅을 보존합니다. +중첩된 completion findings를 만들 때 자식 completion 집계는 현재 요청자 실행으로 범위가 지정되어, 오래된 이전 실행의 자식 출력이 현재 공지로 새어 들어가지 않도록 합니다. 공지 응답은 채널 어댑터에서 사용할 수 있는 경우 스레드/토픽 라우팅을 보존합니다. -### 알림 컨텍스트 +### 공지 컨텍스트 -알림 컨텍스트는 안정적인 내부 이벤트 블록으로 정규화됩니다. +공지 컨텍스트는 안정적인 내부 이벤트 블록으로 정규화됩니다. -| 필드 | 출처 | -| ----------- | ----------------------------------------------------------------------------------------------------------- | -| 소스 | `subagent` 또는 `cron` | -| 세션 ID | 자식 세션 키/ID | -| 유형 | 알림 유형 + 작업 레이블 | -| 상태 | 런타임 결과(`success`, `error`, `timeout`, 또는 `unknown`)에서 파생됨. 모델 텍스트에서 추론하지 **않음** | -| 결과 내용 | 최신 표시 가능 어시스턴트 텍스트, 없으면 정리된 최신 도구/toolResult 텍스트 | -| 후속 조치 | 언제 응답하고 언제 침묵을 유지할지 설명하는 지침 | +| 필드 | 출처 | +| -------------- | ------------------------------------------------------------------------------------------------------------- | +| 출처 | `subagent` 또는 `cron` | +| 세션 ID | 자식 세션 키/ID | +| 유형 | 공지 유형 + 작업 레이블 | +| 상태 | 런타임 결과에서 파생(`success`, `error`, `timeout` 또는 `unknown`) — 모델 텍스트에서 추론하지 **않음** | +| 결과 내용 | 최신 표시 assistant 텍스트, 없으면 정리된 최신 tool/toolResult 텍스트 | +| 후속 조치 | 응답할 때와 침묵을 유지할 때를 설명하는 지침 | -터미널 실패 실행은 캡처된 응답 텍스트를 다시 재생하지 않고 실패 상태를 보고합니다. 시간 초과 시 자식이 도구 호출까지만 진행한 경우, 알림은 원시 도구 출력을 다시 재생하는 대신 해당 기록을 짧은 부분 진행 요약으로 축약할 수 있습니다. +종료된 실패 실행은 캡처된 응답 텍스트를 재생하지 않고 실패 상태를 보고합니다. 타임아웃 시 자식이 도구 호출까지만 진행했다면, 공지는 원시 도구 출력을 재생하는 대신 해당 기록을 짧은 부분 진행 요약으로 축약할 수 있습니다. ### 통계 줄 -알림 payload에는 끝에 통계 줄이 포함됩니다(래핑된 경우에도). +공지 페이로드는 끝에 통계 줄을 포함합니다(줄바꿈되어 감싸진 경우에도). - 런타임(예: `runtime 5m12s`). -- 토큰 사용량(입력/출력/합계). -- 모델 가격이 구성된 경우 예상 비용(`models.providers.*.models[].cost`). -- 메인 에이전트가 `sessions_history`를 통해 기록을 가져오거나 디스크의 파일을 검사할 수 있도록 `sessionKey`, `sessionId`, transcript 경로. +- 토큰 사용량(input/output/total). +- 모델 가격이 구성된 경우 추정 비용(`models.providers.*.models[].cost`). +- 메인 agent가 `sessions_history`를 통해 기록을 가져오거나 디스크의 파일을 검사할 수 있도록 `sessionKey`, `sessionId` 및 transcript 경로. -내부 메타데이터는 오케스트레이션 전용입니다. 사용자 대상 응답은 일반 어시스턴트 어조로 다시 작성해야 합니다. +내부 메타데이터는 오케스트레이션 전용입니다. 사용자-facing 응답은 일반 assistant 음성으로 다시 작성해야 합니다. ### `sessions_history`를 선호하는 이유 `sessions_history`는 더 안전한 오케스트레이션 경로입니다. -- 어시스턴트 recall이 먼저 정규화됩니다. thinking 태그 제거, `` / `` 스캐폴딩 제거, 일반 텍스트 도구 호출 XML payload 블록(``, ``, ``, ``) 제거(깔끔하게 닫히지 않은 잘린 payload 포함), 다운그레이드된 도구 호출/결과 스캐폴딩 및 기록 컨텍스트 마커 제거, 누출된 모델 제어 토큰(`<|assistant|>`, 기타 ASCII `<|...|>`, 전각 `<｜...｜>`) 제거, 잘못 구성된 MiniMax 도구 호출 XML 제거. -- 자격 증명/토큰처럼 보이는 텍스트가 마스킹됩니다. +- Assistant recall이 먼저 정규화됩니다. thinking 태그 제거, `` / `` 스캐폴딩 제거, 일반 텍스트 tool-call XML 페이로드 블록(``, ``, ``, ``) 제거(깔끔하게 닫히지 않은 잘린 페이로드 포함), 다운그레이드된 tool-call/result 스캐폴딩 및 historical-context 마커 제거, 유출된 모델 제어 토큰(`<|assistant|>`, 기타 ASCII `<|...|>`, 전각 `<｜...｜>`) 제거, 잘못된 형식의 MiniMax tool-call XML 제거. +- credential/token처럼 보이는 텍스트가 redact됩니다. - 긴 블록은 잘릴 수 있습니다. -- 매우 큰 기록은 오래된 행을 제거하거나 지나치게 큰 행을 `[sessions_history omitted: message too large]`로 대체할 수 있습니다. -- 전체 byte-for-byte transcript가 필요할 때는 디스크의 원시 transcript 검사가 fallback입니다. +- 매우 큰 기록은 오래된 행을 제거하거나 너무 큰 행을 `[sessions_history omitted: message too large]`로 대체할 수 있습니다. +- 원시 온디스크 transcript 검사는 완전한 바이트 단위 transcript가 필요할 때의 fallback입니다. ## 도구 정책 -하위 에이전트는 먼저 부모 또는 대상 에이전트와 동일한 프로필 및 도구 정책 파이프라인을 사용합니다. 그다음 OpenClaw가 하위 에이전트 제한 계층을 적용합니다. +Sub-agent는 먼저 부모 또는 대상 agent와 동일한 프로필 및 도구 정책 파이프라인을 사용합니다. 그 후 OpenClaw가 sub-agent 제한 계층을 적용합니다. -제한적인 `tools.profile`이 없으면 하위 에이전트는 세션 도구와 시스템 도구를 제외한 **모든 도구**를 받습니다. +제한적인 `tools.profile`이 없으면, sub-agent는 **세션 도구와 시스템 도구를 제외한 모든 도구**를 받습니다. - `sessions_list` - `sessions_history` - `sessions_send` - `sessions_spawn` -여기에서도 `sessions_history`는 제한되고 정리된 recall 뷰로 유지되며, 원시 transcript 덤프가 아닙니다. +여기서도 `sessions_history`는 제한되고 정리된 recall 뷰입니다. 원시 transcript 덤프가 아닙니다. -`maxSpawnDepth >= 2`인 경우 depth-1 오케스트레이터 하위 에이전트는 자식을 관리할 수 있도록 추가로 `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`를 받습니다. +`maxSpawnDepth >= 2`인 경우, depth-1 orchestrator sub-agent는 자식을 관리할 수 있도록 추가로 `sessions_spawn`, `subagents`, `sessions_list`, +`sessions_history`를 받습니다. -### 구성으로 오버라이드 +### 구성으로 재정의 ```json5 { @@ -445,7 +422,7 @@ depth-1 오케스트레이터를 중지하면 모든 depth-2 자식도 자동으 } ``` -`tools.subagents.tools.allow`는 최종 allow-only 필터입니다. 이미 확인된 도구 집합을 좁힐 수는 있지만, `tools.profile`에서 제거된 도구를 **다시 추가할 수는** 없습니다. 예를 들어 `tools.profile: "coding"`은 `web_search`/`web_fetch`를 포함하지만 `browser` 도구는 포함하지 않습니다. coding-profile 하위 에이전트가 브라우저 자동화를 사용하게 하려면 profile 단계에서 browser를 추가하세요. +`tools.subagents.tools.allow`는 최종 허용 전용 필터입니다. 이미 확인된 도구 집합을 좁힐 수는 있지만, `tools.profile`에 의해 제거된 도구를 **다시 추가**할 수는 없습니다. 예를 들어 `tools.profile: "coding"`은 `web_search`/`web_fetch`를 포함하지만 `browser` 도구는 포함하지 않습니다. coding 프로필 하위 에이전트가 browser 자동화를 사용하도록 하려면 프로필 단계에서 browser를 추가하세요. ```json5 { @@ -456,7 +433,7 @@ depth-1 오케스트레이터를 중지하면 모든 depth-2 자식도 자동으 } ``` -하나의 에이전트에만 브라우저 자동화를 제공해야 하는 경우 에이전트별 `agents.list[].tools.alsoAllow: ["browser"]`를 사용하세요. +하나의 에이전트에만 browser 자동화를 제공해야 하는 경우 에이전트별 `agents.list[].tools.alsoAllow: ["browser"]`를 사용하세요. ## 동시성 @@ -467,31 +444,33 @@ depth-1 오케스트레이터를 중지하면 모든 depth-2 자식도 자동으 ## 활성 상태 및 복구 -OpenClaw는 `endedAt`이 없다는 사실을 하위 에이전트가 아직 살아 있다는 영구적인 증거로 취급하지 않습니다. stale-run 기간보다 오래된 종료되지 않은 실행은 `/subagents list`, 상태 요약, 하위 항목 완료 게이트, 세션별 동시성 검사에서 활성/대기 중으로 계산되지 않습니다. +OpenClaw는 `endedAt`이 없다는 것을 하위 에이전트가 아직 살아 있다는 영구적인 증거로 취급하지 않습니다. 오래된 실행 기간보다 오래된 종료되지 않은 실행은 `/subagents list`, 상태 요약, 하위 항목 완료 게이팅, 세션별 동시성 검사에서 활성/대기 중으로 계산되지 않습니다. -Gateway 재시작 후에는 하위 세션이 `abortedLastRun: true`로 표시되어 있지 않은 한, 복원된 오래된 종료되지 않은 실행이 정리됩니다. 이렇게 재시작으로 중단된 하위 세션은 하위 에이전트 고아 복구 흐름을 통해 복구할 수 있으며, 이 흐름은 중단 표시를 지우기 전에 합성 resume 메시지를 보냅니다. +Gateway 재시작 후에는 자식 세션이 `abortedLastRun: true`로 표시되어 있지 않은 한, 오래되어 종료되지 않은 복원 실행이 정리됩니다. 재시작으로 중단된 해당 자식 세션은 하위 에이전트 고아 복구 흐름을 통해 계속 복구할 수 있으며, 이 흐름은 중단 마커를 지우기 전에 합성 재개 메시지를 보냅니다. + +자동 재시작 복구는 자식 세션별로 제한됩니다. 같은 하위 에이전트 자식이 빠른 재쐐기 기간 안에 반복적으로 고아 복구 대상으로 수락되면, OpenClaw는 해당 세션에 복구 tombstone을 유지하고 이후 재시작에서 자동 재개를 중지합니다. 작업 레코드를 조정하려면 `openclaw tasks maintenance --apply`를 실행하거나, tombstoned 세션의 오래된 중단 복구 플래그를 지우려면 `openclaw doctor --fix`를 실행하세요. -하위 에이전트 생성이 Gateway `PAIRING_REQUIRED` / `scope-upgrade`로 실패하면 페어링 상태를 편집하기 전에 RPC 호출자를 확인하세요. 내부 `sessions_spawn` 조정은 직접 loopback 공유 토큰/비밀번호 인증을 통해 `client.id: "gateway-client"` 및 `client.mode: "backend"`로 연결해야 합니다. 해당 경로는 CLI의 페어링된 디바이스 scope 기준선에 의존하지 않습니다. 원격 호출자, 명시적 `deviceIdentity`, 명시적 디바이스 토큰 경로, 브라우저/node 클라이언트에는 여전히 scope 업그레이드에 대한 일반 디바이스 승인이 필요합니다. +하위 에이전트 생성이 Gateway `PAIRING_REQUIRED` / `scope-upgrade`로 실패하면, 페어링 상태를 편집하기 전에 RPC 호출자를 확인하세요. 내부 `sessions_spawn` 조정은 직접 loopback 공유 토큰/비밀번호 인증을 통해 `client.id: "gateway-client"` 및 `client.mode: "backend"`로 연결해야 합니다. 이 경로는 CLI의 페어링된 기기 범위 기준에 의존하지 않습니다. 원격 호출자, 명시적 `deviceIdentity`, 명시적 기기 토큰 경로, browser/node 클라이언트는 범위 업그레이드에 여전히 일반적인 기기 승인이 필요합니다. ## 중지 -- 요청자 채팅에서 `/stop`을 보내면 요청자 세션이 중단되고 해당 세션에서 생성된 활성 하위 에이전트 실행이 중지되며, 중첩된 하위 항목으로 전파됩니다. -- `/subagents kill `는 특정 하위 에이전트를 중지하고 해당 하위 항목으로 전파됩니다. +- 요청자 채팅에서 `/stop`을 보내면 요청자 세션이 중단되고 해당 세션에서 생성된 활성 하위 에이전트 실행이 중지되며, 중첩된 자식까지 연쇄적으로 적용됩니다. +- `/subagents kill `는 특정 하위 에이전트를 중지하고 그 자식까지 연쇄적으로 적용합니다. ## 제한 사항 -- 하위 에이전트 공지는 **최선의 노력**으로 수행됩니다. Gateway가 재시작되면 대기 중인 "announce back" 작업은 손실됩니다. -- 하위 에이전트는 여전히 같은 gateway 프로세스 리소스를 공유합니다. `maxConcurrent`를 안전 밸브로 취급하세요. -- `sessions_spawn`은 항상 비차단입니다. 즉시 `{ status: "accepted", runId, childSessionKey }`를 반환합니다. -- 하위 에이전트 컨텍스트는 `AGENTS.md` + `TOOLS.md`만 주입합니다(`SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` 없음). -- 최대 중첩 깊이는 5입니다(`maxSpawnDepth` 범위: 1–5). 대부분의 사용 사례에는 깊이 2가 권장됩니다. -- `maxChildrenPerAgent`는 세션당 활성 하위 항목 수를 제한합니다(기본값 `5`, 범위 `1–20`). +- 하위 에이전트 알림은 **최선 노력** 방식입니다. Gateway가 재시작되면 대기 중인 "announce back" 작업은 손실됩니다. +- 하위 에이전트는 여전히 동일한 Gateway 프로세스 리소스를 공유합니다. `maxConcurrent`를 안전 장치로 취급하세요. +- `sessions_spawn`은 항상 논블로킹입니다. 즉시 `{ status: "accepted", runId, childSessionKey }`를 반환합니다. +- 하위 에이전트 컨텍스트는 `AGENTS.md` + `TOOLS.md`만 주입합니다(`SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`는 제외). +- 최대 중첩 깊이는 5입니다(`maxSpawnDepth` 범위: 1~5). 대부분의 사용 사례에는 깊이 2를 권장합니다. +- `maxChildrenPerAgent`는 세션당 활성 자식 수를 제한합니다(기본값 `5`, 범위 `1~20`). ## 관련 항목 - [ACP 에이전트](/ko/tools/acp-agents) -- [에이전트 전송](/ko/tools/agent-send) +- [에이전트 보내기](/ko/tools/agent-send) - [백그라운드 작업](/ko/automation/tasks) -- [다중 에이전트 sandbox 도구](/ko/tools/multi-agent-sandbox-tools) +- [멀티 에이전트 샌드박스 도구](/ko/tools/multi-agent-sandbox-tools) diff --git a/docs/ko/tools/thinking.md b/docs/ko/tools/thinking.md index 75bd4ba6d..5e5ad189b 100644 --- a/docs/ko/tools/thinking.md +++ b/docs/ko/tools/thinking.md @@ -1,139 +1,140 @@ --- read_when: - - thinking, fast-mode 또는 verbose 지시문의 파싱이나 기본값 조정 -summary: /think, /fast, /verbose, /trace 및 추론 가시성에 대한 지시문 구문 + - thinking, fast-mode 또는 verbose 지시문 파싱이나 기본값 조정 +summary: /think, /fast, /verbose, /trace 및 추론 가시성을 위한 지시문 구문 title: 사고 수준 x-i18n: - generated_at: "2026-04-30T06:55:35Z" + generated_at: "2026-04-30T16:30:59Z" model: gpt-5.5 provider: openai - source_hash: e9fabead8d2f58fc5bce3bf8b281ad9d52da2cd02ba2777bc1597359537b7705 + source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7 source_path: tools/thinking.md workflow: 16 --- -## 기능 +## 수행 기능 -- 모든 인바운드 본문에서 인라인 지시문: `/t `, `/think:`, 또는 `/thinking `. -- 레벨(별칭): `off | minimal | low | medium | high | xhigh | adaptive | max` +- 모든 인바운드 본문의 인라인 지시문: `/t `, `/think:` 또는 `/thinking `. +- 수준(별칭): `off | minimal | low | medium | high | xhigh | adaptive | max` - minimal → “think” - low → “think hard” - medium → “think harder” - high → “ultrathink”(최대 예산) - - xhigh → “ultrathink+”(GPT-5.2+ 및 Codex 모델, Anthropic Claude Opus 4.7 effort 포함) - - adaptive → 제공자 관리형 적응형 사고(Anthropic/Bedrock의 Claude 4.6, Anthropic Claude Opus 4.7, Google Gemini 동적 사고에서 지원) - - max → 제공자 최대 추론(Anthropic Claude Opus 4.7; Ollama는 이를 자체 최고 `think` effort에 매핑) - - `x-high`, `x_high`, `extra-high`, `extra high`, `extra_high`는 `xhigh`에 매핑됩니다. - - `highest`는 `high`에 매핑됩니다. -- 제공자 참고 사항: - - 사고 메뉴와 선택기는 제공자 프로필에 의해 구동됩니다. 제공자 Plugin은 선택된 모델의 정확한 레벨 집합을 선언하며, 여기에는 이진 `on` 같은 레이블도 포함됩니다. - - `adaptive`, `xhigh`, `max`는 이를 지원하는 제공자/모델 프로필에 대해서만 표시됩니다. 지원되지 않는 레벨의 입력 지시문은 해당 모델의 유효한 옵션과 함께 거부됩니다. - - 기존에 저장된 지원되지 않는 레벨은 제공자 프로필 순위에 따라 다시 매핑됩니다. `adaptive`는 비적응형 모델에서 `medium`으로 대체되고, `xhigh`와 `max`는 선택된 모델에서 지원되는 가장 큰 비-`off` 레벨로 대체됩니다. - - Anthropic Claude 4.6 모델은 명시적 사고 레벨이 설정되지 않은 경우 기본값이 `adaptive`입니다. - - Anthropic Claude Opus 4.7은 적응형 사고를 기본값으로 사용하지 않습니다. API effort 기본값은 명시적으로 사고 레벨을 설정하지 않는 한 제공자가 소유합니다. - - Anthropic Claude Opus 4.7은 `/think xhigh`를 적응형 사고와 `output_config.effort: "xhigh"`로 매핑합니다. `/think`는 사고 지시문이고 `xhigh`는 Opus 4.7의 effort 설정이기 때문입니다. - - Anthropic Claude Opus 4.7은 `/think max`도 노출합니다. 이는 동일한 제공자 소유 최대 effort 경로에 매핑됩니다. - - Ollama 사고 지원 모델은 `/think low|medium|high|max`를 노출합니다. Ollama의 자체 API가 `low`, `medium`, `high` effort 문자열을 받기 때문에 `max`는 자체 `think: "high"`로 매핑됩니다. - - OpenAI GPT 모델은 모델별 Responses API effort 지원을 통해 `/think`를 매핑합니다. `/think off`는 대상 모델이 지원하는 경우에만 `reasoning.effort: "none"`을 보내며, 그렇지 않으면 OpenClaw는 지원되지 않는 값을 보내는 대신 비활성화된 추론 페이로드를 생략합니다. - - 사용자 지정 OpenAI 호환 카탈로그 항목은 `models.providers..models[].compat.supportedReasoningEfforts`에 `"xhigh"`를 포함하도록 설정하여 `/think xhigh`를 선택적으로 사용할 수 있습니다. 이는 아웃바운드 OpenAI 추론 effort 페이로드를 매핑하는 동일한 호환성 메타데이터를 사용하므로 메뉴, 세션 검증, 에이전트 CLI, `llm-task`가 전송 동작과 일치합니다. - - 오래된 OpenRouter Hunter Alpha 참조가 구성되어 있으면, 해당 폐기된 경로가 reasoning 필드를 통해 최종 답변 텍스트를 반환할 수 있으므로 프록시 추론 주입을 건너뜁니다. - - Google Gemini는 `/think adaptive`를 Gemini의 제공자 소유 동적 사고에 매핑합니다. Gemini 3 요청은 고정된 `thinkingLevel`을 생략하고, Gemini 2.5 요청은 `thinkingBudget: -1`을 보냅니다. 고정 레벨은 여전히 해당 모델 계열에 가장 가까운 Gemini `thinkingLevel` 또는 예산에 매핑됩니다. - - Anthropic 호환 스트리밍 경로의 MiniMax(`minimax/*`)는 모델 매개변수나 요청 매개변수에서 사고를 명시적으로 설정하지 않는 한 기본값이 `thinking: { type: "disabled" }`입니다. 이는 MiniMax의 비네이티브 Anthropic 스트림 형식에서 `reasoning_content` 델타가 누출되는 것을 방지합니다. - - Z.AI(`zai/*`)는 이진 사고(`on`/`off`)만 지원합니다. `off`가 아닌 모든 레벨은 `on`으로 처리됩니다(`low`로 매핑). - - Moonshot(`moonshot/*`)은 `/think off`를 `thinking: { type: "disabled" }`로 매핑하고, `off`가 아닌 모든 레벨을 `thinking: { type: "enabled" }`로 매핑합니다. 사고가 활성화되면 Moonshot은 `tool_choice` `auto|none`만 허용합니다. OpenClaw는 호환되지 않는 값을 `auto`로 정규화합니다. + - xhigh → “ultrathink+”(GPT-5.2+ 및 Codex 모델, 그리고 Anthropic Claude Opus 4.7 effort) + - adaptive → 공급자가 관리하는 적응형 thinking(Anthropic/Bedrock의 Claude 4.6, Anthropic Claude Opus 4.7, Google Gemini 동적 thinking에서 지원) + - max → 공급자 최대 reasoning(Anthropic Claude Opus 4.7; Ollama는 이를 자체 최상위 `think` effort로 매핑) + - `x-high`, `x_high`, `extra-high`, `extra high`, `extra_high`는 `xhigh`로 매핑됩니다. + - `highest`는 `high`로 매핑됩니다. +- 공급자 참고 사항: + - Thinking 메뉴와 선택기는 공급자 프로필 기반입니다. 공급자 Plugin은 선택된 모델의 정확한 수준 집합을 선언하며, binary `on` 같은 레이블도 포함합니다. + - `adaptive`, `xhigh`, `max`는 이를 지원하는 공급자/모델 프로필에만 표시됩니다. 지원되지 않는 수준을 입력한 지시문은 해당 모델의 유효한 옵션과 함께 거부됩니다. + - 기존에 저장된 지원되지 않는 수준은 공급자 프로필 순위에 따라 다시 매핑됩니다. `adaptive`는 비적응형 모델에서 `medium`으로 대체되고, `xhigh`와 `max`는 선택된 모델에서 지원되는 가장 큰 non-off 수준으로 대체됩니다. + - Anthropic Claude 4.6 모델은 명시적 thinking 수준이 설정되지 않은 경우 기본값이 `adaptive`입니다. + - Anthropic Claude Opus 4.7은 기본적으로 adaptive thinking을 사용하지 않습니다. 명시적으로 thinking 수준을 설정하지 않는 한 해당 API effort 기본값은 공급자 소유로 유지됩니다. + - Anthropic Claude Opus 4.7은 `/think xhigh`를 adaptive thinking과 `output_config.effort: "xhigh"`로 매핑합니다. `/think`는 thinking 지시문이고 `xhigh`는 Opus 4.7 effort 설정이기 때문입니다. + - Anthropic Claude Opus 4.7은 `/think max`도 노출하며, 동일한 공급자 소유 max effort 경로로 매핑됩니다. + - DeepSeek V4 모델은 `/think xhigh|max`를 노출합니다. 둘 다 DeepSeek `reasoning_effort: "max"`로 매핑되며, 더 낮은 non-off 수준은 `high`로 매핑됩니다. + - Ollama thinking 가능 모델은 `/think low|medium|high|max`를 노출합니다. Ollama의 네이티브 API가 `low`, `medium`, `high` effort 문자열을 허용하므로 `max`는 네이티브 `think: "high"`로 매핑됩니다. + - OpenAI GPT 모델은 모델별 Responses API effort 지원을 통해 `/think`를 매핑합니다. `/think off`는 대상 모델이 지원하는 경우에만 `reasoning.effort: "none"`을 전송합니다. 그렇지 않으면 OpenClaw는 지원되지 않는 값을 보내는 대신 비활성화된 reasoning payload를 생략합니다. + - 사용자 지정 OpenAI 호환 카탈로그 항목은 `models.providers..models[].compat.supportedReasoningEfforts`에 `"xhigh"`를 포함하도록 설정하여 `/think xhigh`를 선택할 수 있습니다. 이는 아웃바운드 OpenAI reasoning effort payload를 매핑하는 것과 동일한 호환성 메타데이터를 사용하므로 메뉴, 세션 검증, 에이전트 CLI, `llm-task`가 전송 동작과 일치합니다. + - 오래된 OpenRouter Hunter Alpha 참조가 구성되어 있으면, 해당 폐기된 경로가 reasoning 필드를 통해 최종 답변 텍스트를 반환할 수 있으므로 프록시 reasoning 주입을 건너뜁니다. + - Google Gemini는 `/think adaptive`를 Gemini의 공급자 소유 동적 thinking으로 매핑합니다. Gemini 3 요청은 고정 `thinkingLevel`을 생략하고, Gemini 2.5 요청은 `thinkingBudget: -1`을 전송합니다. 고정 수준은 여전히 해당 모델 계열에 가장 가까운 Gemini `thinkingLevel` 또는 예산으로 매핑됩니다. + - Anthropic 호환 스트리밍 경로의 MiniMax(`minimax/*`)는 모델 매개변수나 요청 매개변수에서 thinking을 명시적으로 설정하지 않는 한 기본값이 `thinking: { type: "disabled" }`입니다. 이렇게 하면 MiniMax의 비네이티브 Anthropic 스트림 형식에서 `reasoning_content` 델타가 노출되는 일을 방지합니다. + - Z.AI(`zai/*`)는 binary thinking(`on`/`off`)만 지원합니다. `off`가 아닌 모든 수준은 `on`으로 처리됩니다(`low`로 매핑). + - Moonshot(`moonshot/*`)은 `/think off`를 `thinking: { type: "disabled" }`로, `off`가 아닌 모든 수준을 `thinking: { type: "enabled" }`로 매핑합니다. thinking이 활성화되면 Moonshot은 `tool_choice` `auto|none`만 허용합니다. OpenClaw는 호환되지 않는 값을 `auto`로 정규화합니다. -## 해석 순서 +## 확인 순서 1. 메시지의 인라인 지시문(해당 메시지에만 적용). 2. 세션 재정의(지시문만 포함된 메시지를 보내 설정). -3. 에이전트별 기본값(구성의 `agents.list[].thinkingDefault`). -4. 전역 기본값(구성의 `agents.defaults.thinkingDefault`). -5. 대체값: 제공자가 선언한 기본값이 있으면 사용합니다. 그렇지 않으면 추론 가능 모델은 `medium` 또는 해당 모델에서 지원되는 가장 가까운 비-`off` 레벨로 해석되고, 비추론 모델은 `off`로 유지됩니다. +3. 에이전트별 기본값(config의 `agents.list[].thinkingDefault`). +4. 전역 기본값(config의 `agents.defaults.thinkingDefault`). +5. 대체값: 사용 가능한 경우 공급자가 선언한 기본값입니다. 그렇지 않으면 reasoning 가능 모델은 해당 모델의 `medium` 또는 가장 가까운 지원 non-`off` 수준으로 확인되고, non-reasoning 모델은 `off`로 유지됩니다. ## 세션 기본값 설정 -- 지시문만 포함된 메시지를 보냅니다(공백 허용). 예: `/think:medium` 또는 `/t high`. -- 이는 현재 세션에 고정됩니다(기본적으로 발신자별). `/think:off` 또는 세션 유휴 초기화로 지워집니다. -- 확인 응답이 전송됩니다(`Thinking level set to high.` / `Thinking disabled.`). 레벨이 유효하지 않으면(예: `/thinking big`) 힌트와 함께 명령이 거부되고 세션 상태는 변경되지 않습니다. -- 현재 사고 레벨을 보려면 인수 없이 `/think`(또는 `/think:`)를 보냅니다. +- 지시문만 포함된 메시지를 보내세요(공백 허용). 예: `/think:medium` 또는 `/t high`. +- 이는 현재 세션에 유지됩니다(기본적으로 발신자별). `/think:off` 또는 세션 유휴 재설정으로 지워집니다. +- 확인 응답이 전송됩니다(`Thinking level set to high.` / `Thinking disabled.`). 수준이 유효하지 않으면(예: `/thinking big`) 명령은 힌트와 함께 거부되고 세션 상태는 변경되지 않습니다. +- 인수 없이 `/think`(또는 `/think:`)를 보내 현재 thinking 수준을 확인하세요. ## 에이전트별 적용 -- **임베디드 Pi**: 해석된 레벨이 인프로세스 Pi 에이전트 런타임에 전달됩니다. +- **Embedded Pi**: 확인된 수준은 in-process Pi 에이전트 런타임으로 전달됩니다. ## 빠른 모드(/fast) -- 레벨: `on|off`. -- 지시문만 포함된 메시지는 세션 빠른 모드 재정의를 전환하고 `Fast mode enabled.` / `Fast mode disabled.`로 응답합니다. -- 현재 유효한 빠른 모드 상태를 보려면 모드 없이 `/fast`(또는 `/fast status`)를 보냅니다. -- OpenClaw는 빠른 모드를 다음 순서로 해석합니다. +- 수준: `on|off`. +- 지시문만 포함된 메시지는 세션 빠른 모드 재정의를 토글하고 `Fast mode enabled.` / `Fast mode disabled.`로 응답합니다. +- 모드 없이 `/fast`(또는 `/fast status`)를 보내 현재 유효한 빠른 모드 상태를 확인하세요. +- OpenClaw는 다음 순서로 빠른 모드를 확인합니다. 1. 인라인/지시문 전용 `/fast on|off` 2. 세션 재정의 3. 에이전트별 기본값(`agents.list[].fastModeDefault`) - 4. 모델별 구성: `agents.defaults.models["/"].params.fastMode` + 4. 모델별 config: `agents.defaults.models["/"].params.fastMode` 5. 대체값: `off` -- `openai/*`의 경우 빠른 모드는 지원되는 Responses 요청에서 `service_tier=priority`를 보내 OpenAI 우선 처리에 매핑됩니다. -- `openai-codex/*`의 경우 빠른 모드는 Codex Responses에 동일한 `service_tier=priority` 플래그를 보냅니다. OpenClaw는 두 인증 경로에서 하나의 공유 `/fast` 토글을 유지합니다. -- OAuth 인증 트래픽을 포함해 `api.anthropic.com`으로 보내는 직접 공개 `anthropic/*` 요청의 경우, 빠른 모드는 Anthropic 서비스 티어에 매핑됩니다. `/fast on`은 `service_tier=auto`를 설정하고, `/fast off`는 `service_tier=standard_only`를 설정합니다. -- Anthropic 호환 경로의 `minimax/*`의 경우 `/fast on`(또는 `params.fastMode: true`)은 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 다시 작성합니다. -- 명시적 Anthropic `serviceTier` / `service_tier` 모델 매개변수는 둘 다 설정된 경우 빠른 모드 기본값을 재정의합니다. OpenClaw는 여전히 비-Anthropic 프록시 기본 URL에 대해서는 Anthropic 서비스 티어 주입을 건너뜁니다. +- `openai/*`의 경우 빠른 모드는 지원되는 Responses 요청에서 `service_tier=priority`를 보내 OpenAI 우선 처리로 매핑됩니다. +- `openai-codex/*`의 경우 빠른 모드는 Codex Responses에 동일한 `service_tier=priority` 플래그를 전송합니다. OpenClaw는 두 인증 경로에서 하나의 공유 `/fast` 토글을 유지합니다. +- `api.anthropic.com`으로 전송되는 OAuth 인증 트래픽을 포함한 직접 공개 `anthropic/*` 요청의 경우, 빠른 모드는 Anthropic 서비스 티어로 매핑됩니다. `/fast on`은 `service_tier=auto`를 설정하고, `/fast off`는 `service_tier=standard_only`를 설정합니다. +- Anthropic 호환 경로의 `minimax/*`의 경우 `/fast on`(또는 `params.fastMode: true`)은 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 다시 씁니다. +- 명시적 Anthropic `serviceTier` / `service_tier` 모델 매개변수는 둘 다 설정된 경우 빠른 모드 기본값을 재정의합니다. OpenClaw는 여전히 non-Anthropic 프록시 기본 URL에 대해서는 Anthropic 서비스 티어 주입을 건너뜁니다. - `/status`는 빠른 모드가 활성화된 경우에만 `Fast`를 표시합니다. ## 상세 지시문(/verbose 또는 /v) -- 레벨: `on`(최소) | `full` | `off`(기본값). -- 지시문만 포함된 메시지는 세션 상세 로깅을 전환하고 `Verbose logging enabled.` / `Verbose logging disabled.`로 응답합니다. 유효하지 않은 레벨은 상태를 변경하지 않고 힌트를 반환합니다. +- 수준: `on`(최소) | `full` | `off`(기본값). +- 지시문만 포함된 메시지는 세션 상세 출력을 토글하고 `Verbose logging enabled.` / `Verbose logging disabled.`로 응답합니다. 유효하지 않은 수준은 상태를 변경하지 않고 힌트를 반환합니다. - `/verbose off`는 명시적 세션 재정의를 저장합니다. Sessions UI에서 `inherit`을 선택하여 지우세요. -- 인라인 지시문은 해당 메시지에만 영향을 주며, 그렇지 않으면 세션/전역 기본값이 적용됩니다. -- 현재 상세 레벨을 보려면 인수 없이 `/verbose`(또는 `/verbose:`)를 보냅니다. -- 상세 모드가 켜져 있으면 구조화된 도구 결과를 내보내는 에이전트(Pi 및 기타 JSON 에이전트)는 각 도구 호출을 사용 가능한 경우 ` : `(경로/명령) 접두사가 붙은 자체 메타데이터 전용 메시지로 다시 보냅니다. 이러한 도구 요약은 각 도구가 시작되는 즉시 전송되며(별도 말풍선), 스트리밍 델타로 전송되지 않습니다. -- 도구 실패 요약은 일반 모드에서도 계속 표시되지만, 원시 오류 세부 정보 접미사는 상세 레벨이 `on` 또는 `full`이 아닌 한 숨겨집니다. -- 상세 레벨이 `full`이면 도구 출력도 완료 후 전달됩니다(별도 말풍선, 안전한 길이로 잘림). 실행 중에 `/verbose on|full|off`를 전환하면 이후 도구 말풍선은 새 설정을 따릅니다. +- 인라인 지시문은 해당 메시지에만 영향을 줍니다. 그 외에는 세션/전역 기본값이 적용됩니다. +- 인수 없이 `/verbose`(또는 `/verbose:`)를 보내 현재 상세 수준을 확인하세요. +- verbose가 켜져 있으면 구조화된 도구 결과를 내보내는 에이전트(Pi, 기타 JSON 에이전트)는 각 도구 호출을 자체 메타데이터 전용 메시지로 다시 보내며, 사용할 수 있는 경우 ` : `가 접두사로 붙습니다(경로/명령). 이러한 도구 요약은 각 도구가 시작되는 즉시 전송되며(별도 말풍선), 스트리밍 델타로 전송되지 않습니다. +- 도구 실패 요약은 일반 모드에서도 계속 표시되지만, 원시 오류 세부 정보 접미사는 verbose가 `on` 또는 `full`이 아닌 한 숨겨집니다. +- verbose가 `full`이면 도구 출력도 완료 후 전달됩니다(별도 말풍선, 안전한 길이로 잘림). 실행 중에 `/verbose on|full|off`를 토글하면 이후 도구 말풍선은 새 설정을 따릅니다. ## Plugin 추적 지시문(/trace) -- 레벨: `on` | `off`(기본값). -- 지시문만 포함된 메시지는 세션 Plugin 추적 출력을 전환하고 `Plugin trace enabled.` / `Plugin trace disabled.`로 응답합니다. -- 인라인 지시문은 해당 메시지에만 영향을 주며, 그렇지 않으면 세션/전역 기본값이 적용됩니다. -- 현재 추적 레벨을 보려면 인수 없이 `/trace`(또는 `/trace:`)를 보냅니다. +- 수준: `on` | `off`(기본값). +- 지시문만 포함된 메시지는 세션 Plugin 추적 출력을 토글하고 `Plugin trace enabled.` / `Plugin trace disabled.`로 응답합니다. +- 인라인 지시문은 해당 메시지에만 영향을 줍니다. 그 외에는 세션/전역 기본값이 적용됩니다. +- 인수 없이 `/trace`(또는 `/trace:`)를 보내 현재 추적 수준을 확인하세요. - `/trace`는 `/verbose`보다 범위가 좁습니다. Active Memory 디버그 요약 같은 Plugin 소유 추적/디버그 줄만 노출합니다. -- 추적 줄은 `/status`에 나타날 수 있으며, 일반 어시스턴트 응답 뒤의 후속 진단 메시지로도 나타날 수 있습니다. +- 추적 줄은 `/status`와 일반 assistant 응답 뒤의 후속 진단 메시지에 나타날 수 있습니다. -## 추론 표시 여부(/reasoning) +## Reasoning 표시(/reasoning) -- 레벨: `on|off|stream`. -- 지시문만 포함된 메시지는 사고 블록을 답변에 표시할지 여부를 전환합니다. -- 활성화되면 추론은 `Reasoning:` 접두사가 붙은 **별도 메시지**로 전송됩니다. -- `stream`(Telegram 전용): 답변이 생성되는 동안 추론을 Telegram 초안 말풍선으로 스트리밍한 다음, 추론 없이 최종 답변을 보냅니다. +- 수준: `on|off|stream`. +- 지시문만 포함된 메시지는 thinking 블록을 응답에 표시할지 여부를 토글합니다. +- 활성화되면 reasoning은 `Reasoning:` 접두사가 붙은 **별도 메시지**로 전송됩니다. +- `stream`(Telegram만 해당): 응답이 생성되는 동안 reasoning을 Telegram 초안 말풍선으로 스트리밍한 다음, reasoning 없이 최종 답변을 보냅니다. - 별칭: `/reason`. -- 현재 추론 레벨을 보려면 인수 없이 `/reasoning`(또는 `/reasoning:`)을 보냅니다. -- 해석 순서: 인라인 지시문, 세션 재정의, 에이전트별 기본값(`agents.list[].reasoningDefault`), 대체값(`off`). +- 인수 없이 `/reasoning`(또는 `/reasoning:`)을 보내 현재 reasoning 수준을 확인하세요. +- 확인 순서: 인라인 지시문, 세션 재정의, 에이전트별 기본값(`agents.list[].reasoningDefault`), 대체값(`off`). -잘못된 형식의 로컬 모델 추론 태그는 보수적으로 처리됩니다. 닫힌 `...` 블록은 일반 답변에서 숨겨진 상태로 유지되며, 이미 표시된 텍스트 뒤의 닫히지 않은 추론도 숨겨집니다. 답변이 닫히지 않은 단일 여는 태그로 완전히 감싸져 있어 그렇지 않으면 빈 텍스트로 전달될 경우, OpenClaw는 잘못된 여는 태그를 제거하고 나머지 텍스트를 전달합니다. +잘못된 형식의 로컬 모델 reasoning 태그는 보수적으로 처리됩니다. 닫힌 `...` 블록은 일반 응답에서 숨겨진 상태로 유지되며, 이미 보이는 텍스트 뒤의 닫히지 않은 reasoning도 숨겨집니다. 응답이 닫히지 않은 단일 여는 태그로 완전히 감싸져 있고 그렇지 않으면 빈 텍스트로 전달될 경우, OpenClaw는 잘못된 여는 태그를 제거하고 나머지 텍스트를 전달합니다. ## 관련 항목 -- 승격 모드 문서는 [승격 모드](/ko/tools/elevated)에 있습니다. +- 상승 모드 문서는 [상승 모드](/ko/tools/elevated)에 있습니다. ## Heartbeat -- Heartbeat 프로브 본문은 구성된 Heartbeat 프롬프트입니다(기본값: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Heartbeat 메시지의 인라인 지시문은 평소처럼 적용됩니다(하지만 Heartbeat에서 세션 기본값을 변경하는 것은 피하세요). -- Heartbeat 전달은 기본적으로 최종 페이로드만 보냅니다. 별도 `Reasoning:` 메시지도(사용 가능한 경우) 보내려면 `agents.defaults.heartbeat.includeReasoning: true` 또는 에이전트별 `agents.list[].heartbeat.includeReasoning: true`를 설정하세요. +- Heartbeat 프로브 본문은 구성된 Heartbeat 프롬프트입니다(기본값: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Heartbeat 메시지의 인라인 지시문은 일반적인 방식으로 적용됩니다(단, Heartbeat에서 세션 기본값을 변경하는 것은 피하세요). +- Heartbeat 전달은 기본적으로 최종 payload만 보냅니다. 별도 `Reasoning:` 메시지도 함께 보내려면(사용 가능한 경우) `agents.defaults.heartbeat.includeReasoning: true` 또는 에이전트별 `agents.list[].heartbeat.includeReasoning: true`를 설정하세요. ## 웹 채팅 UI -- 웹 채팅 사고 선택기는 페이지가 로드될 때 인바운드 세션 저장소/구성에서 세션에 저장된 레벨을 반영합니다. -- 다른 레벨을 선택하면 `sessions.patch`를 통해 세션 재정의가 즉시 기록됩니다. 다음 전송을 기다리지 않으며 일회성 `thinkingOnce` 재정의가 아닙니다. -- 첫 번째 옵션은 항상 `Default ()`이며, 해석된 기본값은 활성 세션 모델의 제공자 사고 프로필과 `/status` 및 `session_status`가 사용하는 동일한 대체 로직에서 나옵니다. -- 선택기는 Gateway 세션 행/기본값이 반환한 `thinkingLevels`를 사용하며, `thinkingOptions`는 레거시 레이블 목록으로 유지됩니다. 브라우저 UI는 자체 제공자 정규식 목록을 보관하지 않습니다. Plugin이 모델별 레벨 집합을 소유합니다. -- `/think:`도 계속 작동하며 동일하게 저장된 세션 레벨을 업데이트하므로 채팅 지시문과 선택기가 동기화된 상태로 유지됩니다. +- 웹 채팅 thinking 선택기는 페이지 로드 시 인바운드 세션 저장소/config에서 세션의 저장된 수준을 반영합니다. +- 다른 수준을 선택하면 `sessions.patch`를 통해 세션 재정의를 즉시 기록합니다. 다음 전송을 기다리지 않으며 일회성 `thinkingOnce` 재정의가 아닙니다. +- 첫 번째 옵션은 항상 `Default ()`이며, 확인된 기본값은 활성 세션 모델의 공급자 thinking 프로필과 `/status` 및 `session_status`가 사용하는 동일한 대체 로직에서 나옵니다. +- 선택기는 Gateway 세션 행/기본값이 반환하는 `thinkingLevels`를 사용하며, `thinkingOptions`는 레거시 레이블 목록으로 유지됩니다. 브라우저 UI는 자체 공급자 regex 목록을 유지하지 않습니다. Plugin이 모델별 수준 집합을 소유합니다. +- `/think:`도 계속 작동하며 동일하게 저장된 세션 수준을 업데이트하므로 채팅 지시문과 선택기가 동기화된 상태를 유지합니다. -## 제공자 프로필 +## 공급자 프로필 -- Provider Plugin은 모델이 지원하는 수준과 기본값을 정의하기 위해 `resolveThinkingProfile(ctx)`를 노출할 수 있습니다. -- Claude 모델을 프록시하는 Provider Plugin은 직접 Anthropic 카탈로그와 프록시 카탈로그가 정렬된 상태를 유지하도록 `openclaw/plugin-sdk/provider-model-shared`의 `resolveClaudeThinkingProfile(modelId)`를 재사용해야 합니다. -- 각 프로필 수준에는 저장되는 정식 `id`(`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` 또는 `max`)가 있으며, 표시용 `label`을 포함할 수 있습니다. 이진 Provider는 `{ id: "low", label: "on" }`을 사용합니다. -- 명시적 thinking 재정의를 검증해야 하는 도구 Plugin은 `api.runtime.agent.resolveThinkingPolicy({ provider, model })`와 `api.runtime.agent.normalizeThinkingLevel(...)`을 사용해야 하며, 자체 Provider/모델 수준 목록을 유지해서는 안 됩니다. -- 구성된 사용자 지정 모델 메타데이터에 접근할 수 있는 도구 Plugin은 `resolveThinkingPolicy`에 `catalog`를 전달할 수 있으므로 `compat.supportedReasoningEfforts` 옵트인이 Plugin 측 검증에 반영됩니다. -- 게시된 레거시 훅(`supportsXHighThinking`, `isBinaryThinking`, 및 `resolveDefaultThinkingLevel`)은 호환성 어댑터로 유지되지만, 새로운 사용자 지정 수준 집합은 `resolveThinkingProfile`을 사용해야 합니다. -- Gateway 행/기본값은 `thinkingLevels`, `thinkingOptions`, 및 `thinkingDefault`를 노출하여 ACP/채팅 클라이언트가 런타임 검증에서 사용하는 것과 동일한 프로필 ID와 레이블을 렌더링하도록 합니다. +- 제공자 Plugin은 모델이 지원하는 수준과 기본값을 정의하기 위해 `resolveThinkingProfile(ctx)`를 노출할 수 있습니다. +- Claude 모델을 프록시하는 제공자 Plugin은 직접 Anthropic 카탈로그와 프록시 카탈로그가 서로 맞게 유지되도록 `openclaw/plugin-sdk/provider-model-shared`의 `resolveClaudeThinkingProfile(modelId)`을 재사용해야 합니다. +- 각 프로필 수준에는 저장된 정식 `id`(`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` 또는 `max`)가 있으며 표시용 `label`을 포함할 수 있습니다. 이진 제공자는 `{ id: "low", label: "on" }`을 사용합니다. +- 명시적 thinking 재정의를 검증해야 하는 도구 Plugin은 `api.runtime.agent.resolveThinkingPolicy({ provider, model })`와 `api.runtime.agent.normalizeThinkingLevel(...)`를 사용해야 하며, 자체 제공자/모델 수준 목록을 유지해서는 안 됩니다. +- 구성된 사용자 지정 모델 메타데이터에 접근할 수 있는 도구 Plugin은 `resolveThinkingPolicy`에 `catalog`를 전달하여 `compat.supportedReasoningEfforts` 옵트인이 Plugin 측 검증에 반영되도록 할 수 있습니다. +- 게시된 레거시 훅(`supportsXHighThinking`, `isBinaryThinking`, `resolveDefaultThinkingLevel`)은 호환성 어댑터로 유지되지만, 새 사용자 지정 수준 집합은 `resolveThinkingProfile`을 사용해야 합니다. +- Gateway 행/기본값은 `thinkingLevels`, `thinkingOptions`, `thinkingDefault`를 노출하므로 ACP/채팅 클라이언트는 런타임 검증에서 사용하는 것과 동일한 프로필 ID와 레이블을 렌더링합니다.