chore(i18n): refresh ko translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c50e47614a
commit
37f6599b1c
@ -1,44 +1,44 @@
|
||||
---
|
||||
read_when:
|
||||
- 진행 중이거나 최근 완료된 백그라운드 작업을 확인할 때
|
||||
- 분리된 에이전트 실행의 전달 실패를 디버깅할 때
|
||||
- 백그라운드 실행이 세션, cron, heartbeat와 어떻게 연결되는지 이해할 때
|
||||
summary: ACP 실행, 하위 에이전트, 격리된 cron 작업, CLI 작업에 대한 백그라운드 작업 추적
|
||||
- 진행 중이거나 최근 완료된 백그라운드 작업 검사
|
||||
- 분리된 에이전트 실행의 전달 실패 디버깅
|
||||
- 백그라운드 실행이 세션, cron, 그리고 하트비트와 어떻게 연결되는지 이해하기
|
||||
summary: ACP 실행, 하위 에이전트, 격리된 cron 작업, 그리고 CLI 작업을 위한 백그라운드 작업 추적
|
||||
title: 백그라운드 작업
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:46Z"
|
||||
generated_at: "2026-04-10T05:59:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
|
||||
source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
|
||||
source_path: automation/tasks.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 백그라운드 작업
|
||||
|
||||
> **예약을 찾고 있나요?** 적절한 메커니즘을 선택하려면 [Automation & Tasks](/ko/automation)를 참고하세요. 이 페이지는 백그라운드 작업의 **추적**을 다루며, 예약 자체를 설명하지 않습니다.
|
||||
> **일정을 찾고 있나요?** 적절한 메커니즘을 선택하려면 [Automation & Tasks](/ko/automation)를 참조하세요. 이 페이지는 백그라운드 작업의 **추적**을 다루며, 예약을 다루지 않습니다.
|
||||
|
||||
백그라운드 작업은 **주 대화 세션 외부**에서 실행되는 작업을 추적합니다:
|
||||
백그라운드 작업은 **기본 대화 세션 외부에서** 실행되는 작업을 추적합니다:
|
||||
ACP 실행, 하위 에이전트 생성, 격리된 cron 작업 실행, 그리고 CLI로 시작된 작업입니다.
|
||||
|
||||
작업은 세션, cron 작업, heartbeat를 **대체하지 않습니다**. 대신 어떤 분리된 작업이 발생했고, 언제 발생했으며, 성공했는지를 기록하는 **활동 원장**입니다.
|
||||
작업은 세션, cron 작업, 또는 하트비트를 대체하지 않습니다 — 이것들은 분리된 작업이 무엇이었는지, 언제 발생했는지, 그리고 성공했는지를 기록하는 **활동 원장**입니다.
|
||||
|
||||
<Note>
|
||||
모든 에이전트 실행이 작업을 생성하는 것은 아닙니다. Heartbeat 턴과 일반적인 대화형 채팅은 생성하지 않습니다. 모든 cron 실행, ACP 생성, 하위 에이전트 생성, CLI 에이전트 명령은 작업을 생성합니다.
|
||||
모든 에이전트 실행이 작업을 생성하는 것은 아닙니다. 하트비트 턴과 일반 대화형 채팅은 생성하지 않습니다. 모든 cron 실행, ACP 생성, 하위 에이전트 생성, 그리고 CLI 에이전트 명령은 생성합니다.
|
||||
</Note>
|
||||
|
||||
## 요약
|
||||
## TL;DR
|
||||
|
||||
- 작업은 스케줄러가 아니라 **기록**입니다. cron과 heartbeat는 작업이 _언제_ 실행될지 결정하고, 작업은 _무슨 일이 있었는지_ 추적합니다.
|
||||
- ACP, 하위 에이전트, 모든 cron 작업, CLI 작업은 작업을 생성합니다. Heartbeat 턴은 생성하지 않습니다.
|
||||
- 각 작업은 `queued → running → terminal`(succeeded, failed, timed_out, cancelled 또는 lost) 단계를 거칩니다.
|
||||
- Cron 작업은 cron 런타임이 여전히 해당 작업을 소유하는 동안 활성 상태를 유지하며, 채팅 기반 CLI 작업은 소유한 실행 컨텍스트가 아직 활성 상태일 때만 활성 상태를 유지합니다.
|
||||
- 완료는 푸시 기반입니다. 분리된 작업은 완료되면 직접 알리거나 요청자 세션/heartbeat를 깨울 수 있으므로, 상태를 폴링하는 루프는 대개 적절한 형태가 아닙니다.
|
||||
- 격리된 cron 실행과 하위 에이전트 완료는 최종 정리 bookkeeping 전에 해당 하위 세션의 추적된 브라우저 탭/프로세스를 가능한 범위에서 정리합니다.
|
||||
- 격리된 cron 전달은 하위 하위 에이전트 작업이 아직 마무리 중일 때 오래된 중간 부모 응답을 억제하며, 전달 전에 최종 하위 출력이 도착하면 이를 우선합니다.
|
||||
- 완료 알림은 채널로 직접 전달되거나 다음 heartbeat를 위해 대기열에 들어갑니다.
|
||||
- 작업은 스케줄러가 아니라 **기록**입니다 — cron과 하트비트는 작업이 _언제_ 실행될지 결정하고, 작업은 _무슨 일이 일어났는지_ 추적합니다.
|
||||
- ACP, 하위 에이전트, 모든 cron 작업, 그리고 CLI 작업은 작업을 생성합니다. 하트비트 턴은 생성하지 않습니다.
|
||||
- 각 작업은 `queued → running → terminal`(succeeded, failed, timed_out, cancelled, 또는 lost)을 거칩니다.
|
||||
- cron 작업은 cron 런타임이 여전히 해당 작업을 소유하는 동안 활성 상태를 유지합니다. 채팅 기반 CLI 작업은 소유한 실행 컨텍스트가 여전히 활성 상태인 동안에만 활성 상태를 유지합니다.
|
||||
- 완료는 푸시 기반입니다: 분리된 작업은 완료 시 직접 알리거나 요청자 세션/하트비트를 깨울 수 있으므로, 상태를 폴링하는 루프는 보통 적절한 방식이 아닙니다.
|
||||
- 격리된 cron 실행과 하위 에이전트 완료는 최종 정리 기록을 남기기 전에 자식 세션의 추적된 브라우저 탭/프로세스를 최선의 노력으로 정리합니다.
|
||||
- 격리된 cron 전달은 하위 하위 에이전트 작업이 아직 마무리 중일 때 오래된 중간 부모 응답을 억제하고, 전달 전에 최종 하위 결과가 도착하면 그것을 우선합니다.
|
||||
- 완료 알림은 채널로 직접 전달되거나 다음 하트비트를 위해 대기열에 들어갑니다.
|
||||
- `openclaw tasks list`는 모든 작업을 표시하고, `openclaw tasks audit`는 문제를 표시합니다.
|
||||
- 종료된 기록은 7일 동안 보관된 후 자동으로 정리됩니다.
|
||||
- 종료된 기록은 7일간 보관된 뒤 자동으로 정리됩니다.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
@ -50,48 +50,48 @@ openclaw tasks list
|
||||
openclaw tasks list --runtime acp
|
||||
openclaw tasks list --status running
|
||||
|
||||
# 특정 작업의 세부 정보 표시(ID, run ID 또는 session key로 조회)
|
||||
# 특정 작업의 세부 정보 표시(ID, run ID, 또는 session key로)
|
||||
openclaw tasks show <lookup>
|
||||
|
||||
# 실행 중인 작업 취소(하위 세션 종료)
|
||||
# 실행 중인 작업 취소(자식 세션 종료)
|
||||
openclaw tasks cancel <lookup>
|
||||
|
||||
# 작업의 알림 정책 변경
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
|
||||
# 상태 점검 실행
|
||||
# 상태 점검 감사 실행
|
||||
openclaw tasks audit
|
||||
|
||||
# 유지 관리 미리보기 또는 적용
|
||||
# 유지 관리 미리 보기 또는 적용
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
|
||||
# TaskFlow 상태 확인
|
||||
# TaskFlow 상태 검사
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
## 작업을 생성하는 것
|
||||
## 작업을 생성하는 항목
|
||||
|
||||
| 소스 | 런타임 유형 | 작업 레코드가 생성되는 시점 | 기본 알림 정책 |
|
||||
| ---------------------- | ----------- | ---------------------------------------------------- | -------------- |
|
||||
| ACP 백그라운드 실행 | `acp` | 하위 ACP 세션 생성 시 | `done_only` |
|
||||
| 하위 에이전트 오케스트레이션 | `subagent` | `sessions_spawn`를 통해 하위 에이전트 생성 시 | `done_only` |
|
||||
| Cron 작업(모든 유형) | `cron` | 모든 cron 실행(주 세션 및 격리 실행) | `silent` |
|
||||
| CLI 작업 | `cli` | 게이트웨이를 통해 실행되는 `openclaw agent` 명령 | `silent` |
|
||||
| 에이전트 미디어 작업 | `cli` | 세션 기반 `video_generate` 실행 | `silent` |
|
||||
| 소스 | 런타임 유형 | 작업 기록이 생성되는 시점 | 기본 알림 정책 |
|
||||
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
|
||||
| ACP 백그라운드 실행 | `acp` | 자식 ACP 세션 생성 시 | `done_only` |
|
||||
| 하위 에이전트 오케스트레이션 | `subagent` | `sessions_spawn`를 통해 하위 에이전트 생성 시 | `done_only` |
|
||||
| cron 작업(모든 유형) | `cron` | 모든 cron 실행(기본 세션 및 격리 실행) | `silent` |
|
||||
| CLI 작업 | `cli` | 게이트웨이를 통해 실행되는 `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](/ko/gateway/heartbeat) 참조
|
||||
- 일반 대화형 채팅 턴
|
||||
- 직접 `/command` 응답
|
||||
|
||||
## 작업 수명 주기
|
||||
@ -102,56 +102,56 @@ stateDiagram-v2
|
||||
queued --> running : 에이전트 시작
|
||||
running --> succeeded : 정상 완료
|
||||
running --> failed : 오류
|
||||
running --> timed_out : 시간 제한 초과
|
||||
running --> timed_out : 제한 시간 초과
|
||||
running --> cancelled : 운영자가 취소
|
||||
queued --> lost : 세션 사라짐 > 5분
|
||||
running --> lost : 세션 사라짐 > 5분
|
||||
```
|
||||
|
||||
| 상태 | 의미 |
|
||||
| 상태 | 의미 |
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| `queued` | 생성되었으며 에이전트 시작 대기 중 |
|
||||
| `running` | 에이전트 턴이 현재 실행 중 |
|
||||
| `succeeded` | 성공적으로 완료됨 |
|
||||
| `failed` | 오류와 함께 완료됨 |
|
||||
| `timed_out` | 구성된 시간 제한을 초과함 |
|
||||
| `cancelled` | 운영자가 `openclaw tasks cancel`을 통해 중지함 |
|
||||
| `lost` | 5분 유예 기간 후 런타임이 권위 있는 백업 상태를 잃음 |
|
||||
| `queued` | 생성되었으며, 에이전트 시작 대기 중 |
|
||||
| `running` | 에이전트 턴이 현재 실행 중 |
|
||||
| `succeeded` | 성공적으로 완료됨 |
|
||||
| `failed` | 오류와 함께 완료됨 |
|
||||
| `timed_out` | 구성된 제한 시간을 초과함 |
|
||||
| `cancelled` | 운영자가 `openclaw tasks cancel`을 통해 중지함 |
|
||||
| `lost` | 런타임이 5분 유예 기간 후 권위 있는 백킹 상태를 잃음 |
|
||||
|
||||
전환은 자동으로 발생합니다. 연결된 에이전트 실행이 끝나면 작업 상태도 그에 맞게 업데이트됩니다.
|
||||
전환은 자동으로 발생합니다 — 연결된 에이전트 실행이 끝나면 작업 상태가 그에 맞게 업데이트됩니다.
|
||||
|
||||
`lost`는 런타임 인지형입니다.
|
||||
`lost`는 런타임 인지형입니다:
|
||||
|
||||
- ACP 작업: 기반 ACP 하위 세션 메타데이터가 사라졌습니다.
|
||||
- 하위 에이전트 작업: 대상 에이전트 저장소에서 기반 하위 세션이 사라졌습니다.
|
||||
- Cron 작업: cron 런타임이 더 이상 해당 작업을 활성 상태로 추적하지 않습니다.
|
||||
- CLI 작업: 격리된 하위 세션 작업은 하위 세션을 사용하고, 채팅 기반 CLI 작업은 대신 활성 실행 컨텍스트를 사용하므로 남아 있는 채널/그룹/직접 세션 행이 이들을 활성 상태로 유지하지는 않습니다.
|
||||
- ACP 작업: 백킹 ACP 자식 세션 메타데이터가 사라졌습니다.
|
||||
- 하위 에이전트 작업: 백킹 자식 세션이 대상 에이전트 저장소에서 사라졌습니다.
|
||||
- cron 작업: cron 런타임이 더 이상 해당 작업을 활성 상태로 추적하지 않습니다.
|
||||
- CLI 작업: 격리된 자식 세션 작업은 자식 세션을 사용하고, 채팅 기반 CLI 작업은 그 대신 활성 실행 컨텍스트를 사용하므로, 채널/그룹/다이렉트 세션 행이 남아 있어도 활성 상태로 유지되지 않습니다.
|
||||
|
||||
## 전달 및 알림
|
||||
|
||||
작업이 종료 상태에 도달하면 OpenClaw가 알립니다. 전달 경로는 두 가지입니다.
|
||||
작업이 종료 상태에 도달하면 OpenClaw가 알립니다. 전달 경로는 두 가지입니다:
|
||||
|
||||
**직접 전달** — 작업에 채널 대상(`requesterOrigin`)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 전송됩니다. 하위 에이전트 완료의 경우, OpenClaw는 가능한 경우 연결된 스레드/토픽 라우팅도 유지하며, 직접 전달을 포기하기 전에 요청자 세션의 저장된 경로(`lastChannel` / `lastTo` / `lastAccountId`)에서 누락된 `to` / 계정을 보완할 수 있습니다.
|
||||
**직접 전달** — 작업에 채널 대상(`requesterOrigin`)이 있으면 완료 메시지가 해당 채널(Telegram, Discord, Slack 등)로 바로 전달됩니다. 하위 에이전트 완료의 경우, OpenClaw는 가능할 때 바인딩된 스레드/토픽 라우팅도 유지하며, 직접 전달을 포기하기 전에 요청자 세션에 저장된 라우트(`lastChannel` / `lastTo` / `lastAccountId`)에서 누락된 `to` / 계정을 채울 수 있습니다.
|
||||
|
||||
**세션 대기열 전달** — 직접 전달에 실패했거나 origin이 설정되지 않았으면, 업데이트는 요청자 세션의 시스템 이벤트로 대기열에 들어가며 다음 heartbeat에 표시됩니다.
|
||||
**세션 대기열 전달** — 직접 전달에 실패했거나 origin이 설정되지 않았으면, 업데이트가 요청자 세션의 시스템 이벤트로 대기열에 들어가고 다음 하트비트에서 표시됩니다.
|
||||
|
||||
<Tip>
|
||||
작업 완료는 즉시 heartbeat 깨우기를 트리거하므로 결과를 빠르게 확인할 수 있습니다. 다음 예약 heartbeat tick까지 기다릴 필요가 없습니다.
|
||||
작업 완료는 즉시 하트비트 웨이크를 트리거하므로 결과를 빠르게 볼 수 있습니다 — 다음 예약된 하트비트 틱까지 기다릴 필요가 없습니다.
|
||||
</Tip>
|
||||
|
||||
즉, 일반적인 워크플로는 푸시 기반입니다. 분리된 작업을 한 번 시작한 다음, 런타임이 완료 시 깨우거나 알리도록 두면 됩니다. 디버깅, 개입 또는 명시적 감사가 필요할 때만 작업 상태를 폴링하세요.
|
||||
즉, 일반적인 워크플로는 푸시 기반입니다: 분리된 작업을 한 번 시작한 뒤 런타임이 완료 시 깨우거나 알리도록 두세요. 디버깅, 개입, 또는 명시적인 감사를 위해 필요할 때만 작업 상태를 폴링하세요.
|
||||
|
||||
### 알림 정책
|
||||
|
||||
각 작업에 대해 어느 정도까지 알림을 받을지 제어합니다.
|
||||
각 작업에 대해 얼마나 많은 알림을 받을지 제어합니다:
|
||||
|
||||
| 정책 | 전달되는 내용 |
|
||||
| 정책 | 전달되는 내용 |
|
||||
| --------------------- | ----------------------------------------------------------------------- |
|
||||
| `done_only` (기본값) | 종료 상태(succeeded, failed 등)만 전달 — **이것이 기본값입니다** |
|
||||
| `state_changes` | 모든 상태 전환 및 진행 상황 업데이트 |
|
||||
| `silent` | 아무것도 전달하지 않음 |
|
||||
| `done_only` (기본값) | 종료 상태(succeeded, failed 등)만 — **이것이 기본값입니다** |
|
||||
| `state_changes` | 모든 상태 전환 및 진행 상황 업데이트 |
|
||||
| `silent` | 아무것도 없음 |
|
||||
|
||||
작업 실행 중에도 정책을 변경할 수 있습니다.
|
||||
작업이 실행 중일 때 정책을 변경할 수 있습니다:
|
||||
|
||||
```bash
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
@ -165,7 +165,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
|
||||
출력 열: Task ID, Kind, Status, Delivery, Run ID, Child Session, Summary.
|
||||
출력 열: 작업 ID, 종류, 상태, 전달, 실행 ID, 자식 세션, 요약.
|
||||
|
||||
### `tasks show`
|
||||
|
||||
@ -173,7 +173,7 @@ openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--j
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
조회 토큰은 task ID, run ID 또는 session key를 받을 수 있습니다. 타이밍, 전달 상태, 오류, 종료 요약을 포함한 전체 레코드를 표시합니다.
|
||||
조회 토큰은 작업 ID, 실행 ID, 또는 세션 키를 받을 수 있습니다. 시간 정보, 전달 상태, 오류, 종료 요약을 포함한 전체 기록을 표시합니다.
|
||||
|
||||
### `tasks cancel`
|
||||
|
||||
@ -181,7 +181,7 @@ openclaw tasks show <lookup>
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
ACP 및 하위 에이전트 작업의 경우 하위 세션을 종료합니다. 상태는 `cancelled`로 전환되고 전달 알림이 전송됩니다.
|
||||
ACP 및 하위 에이전트 작업의 경우 자식 세션을 종료합니다. CLI 추적 작업의 경우, 취소는 작업 레지스트리에 기록됩니다(별도의 자식 런타임 핸들은 없습니다). 상태는 `cancelled`로 전환되며, 해당하는 경우 전달 알림이 전송됩니다.
|
||||
|
||||
### `tasks notify`
|
||||
|
||||
@ -197,14 +197,14 @@ openclaw tasks audit [--json]
|
||||
|
||||
운영상 문제를 표시합니다. 문제가 감지되면 결과는 `openclaw status`에도 표시됩니다.
|
||||
|
||||
| 항목 | 심각도 | 트리거 |
|
||||
| ------------------------- | ------ | --------------------------------------------------- |
|
||||
| `stale_queued` | warn | 10분 이상 대기 상태 |
|
||||
| `stale_running` | error | 30분 이상 실행 상태 |
|
||||
| `lost` | error | 런타임 기반 작업 소유 상태가 사라짐 |
|
||||
| `delivery_failed` | warn | 전달에 실패했고 알림 정책이 `silent`가 아님 |
|
||||
| `missing_cleanup` | warn | 종료된 작업에 cleanup 타임스탬프가 없음 |
|
||||
| `inconsistent_timestamps` | warn | 타임라인 위반(예: 시작 전에 종료됨) |
|
||||
| 항목 | 심각도 | 트리거 |
|
||||
| ------------------------- | -------- | ----------------------------------------------------- |
|
||||
| `stale_queued` | warn | 10분 이상 queued 상태 |
|
||||
| `stale_running` | error | 30분 이상 running 상태 |
|
||||
| `lost` | error | 런타임 기반 작업 소유 상태가 사라짐 |
|
||||
| `delivery_failed` | warn | 전달에 실패했고 알림 정책이 `silent`가 아님 |
|
||||
| `missing_cleanup` | warn | 정리 타임스탬프가 없는 종료 작업 |
|
||||
| `inconsistent_timestamps` | warn | 타임라인 위반(예: 시작 전에 종료됨) |
|
||||
|
||||
### `tasks maintenance`
|
||||
|
||||
@ -213,20 +213,20 @@ openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
이 명령은 작업 및 Task Flow 상태에 대한 조정, cleanup stamping, 정리를 미리 보거나 적용할 때 사용합니다.
|
||||
이를 사용해 작업 및 Task Flow 상태에 대한 조정, 정리 타임스탬프 기록, 그리고 정리 작업을 미리 보거나 적용할 수 있습니다.
|
||||
|
||||
조정은 런타임 인지형입니다.
|
||||
조정은 런타임 인지형입니다:
|
||||
|
||||
- ACP/하위 에이전트 작업은 기반 하위 세션을 확인합니다.
|
||||
- Cron 작업은 cron 런타임이 여전히 해당 작업을 소유하는지 확인합니다.
|
||||
- 채팅 기반 CLI 작업은 채팅 세션 행만이 아니라 소유한 활성 실행 컨텍스트를 확인합니다.
|
||||
- ACP/하위 에이전트 작업은 백킹 자식 세션을 확인합니다.
|
||||
- cron 작업은 cron 런타임이 여전히 해당 작업을 소유하는지 확인합니다.
|
||||
- 채팅 기반 CLI 작업은 단순히 채팅 세션 행이 아니라 소유한 활성 실행 컨텍스트를 확인합니다.
|
||||
|
||||
완료 정리도 런타임 인지형입니다.
|
||||
완료 정리도 런타임 인지형입니다:
|
||||
|
||||
- 하위 에이전트 완료 시 알림 정리가 계속되기 전에 하위 세션의 추적된 브라우저 탭/프로세스를 가능한 범위에서 닫습니다.
|
||||
- 격리된 cron 완료 시 실행이 완전히 종료되기 전에 cron 세션의 추적된 브라우저 탭/프로세스를 가능한 범위에서 닫습니다.
|
||||
- 격리된 cron 전달은 필요할 경우 하위 하위 에이전트 후속 작업이 끝날 때까지 기다리며, 이를 알리는 대신 오래된 부모 확인 텍스트를 억제합니다.
|
||||
- 하위 에이전트 완료 전달은 최신의 표시 가능한 assistant 텍스트를 우선하며, 이것이 비어 있으면 정제된 최신 tool/toolResult 텍스트로 대체하고, 시간 초과만 발생한 tool-call 실행은 짧은 부분 진행 요약으로 축약될 수 있습니다.
|
||||
- 하위 에이전트 완료는 알림 정리가 계속되기 전에 자식 세션의 추적된 브라우저 탭/프로세스를 최선의 노력으로 닫습니다.
|
||||
- 격리된 cron 완료는 실행이 완전히 종료되기 전에 cron 세션의 추적된 브라우저 탭/프로세스를 최선의 노력으로 닫습니다.
|
||||
- 격리된 cron 전달은 필요할 경우 하위 하위 에이전트 후속 작업이 마무리될 때까지 기다리고, 이를 알리는 대신 오래된 부모 확인 텍스트를 억제합니다.
|
||||
- 하위 에이전트 완료 전달은 가장 최근의 표시 가능한 assistant 텍스트를 우선하며, 그것이 비어 있으면 정제된 최신 tool/toolResult 텍스트로 대체하고, 시간 초과만 발생한 도구 호출 실행은 짧은 부분 진행 요약으로 축약될 수 있습니다.
|
||||
- 정리 실패가 실제 작업 결과를 가리지는 않습니다.
|
||||
|
||||
### `tasks flow list|show|cancel`
|
||||
@ -237,86 +237,86 @@ openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
개별 백그라운드 작업 레코드 하나보다 오케스트레이션하는 Task Flow 자체가 더 중요할 때 이 명령을 사용하세요.
|
||||
개별 백그라운드 작업 기록 하나보다 이를 오케스트레이션하는 Task Flow 자체가 더 중요할 때 사용하세요.
|
||||
|
||||
## 채팅 작업 보드(`/tasks`)
|
||||
|
||||
어떤 채팅 세션에서든 `/tasks`를 사용해 해당 세션에 연결된 백그라운드 작업을 볼 수 있습니다. 보드는 런타임, 상태, 타이밍, 진행 상황 또는 오류 세부 정보를 포함해 활성 및 최근 완료된 작업을 표시합니다.
|
||||
아무 채팅 세션에서나 `/tasks`를 사용해 해당 세션에 연결된 백그라운드 작업을 볼 수 있습니다. 보드는 런타임, 상태, 시간 정보, 그리고 진행 상황 또는 오류 세부 정보와 함께 활성 작업 및 최근 완료된 작업을 표시합니다.
|
||||
|
||||
현재 세션에 표시 가능한 연결 작업이 없으면, `/tasks`는 에이전트 로컬 작업 수로 대체되어 다른 세션 세부 정보를 노출하지 않으면서도 개요를 확인할 수 있습니다.
|
||||
현재 세션에 표시 가능한 연결 작업이 없으면, `/tasks`는 에이전트 로컬 작업 수로 대체되어 다른 세션의 세부 정보를 노출하지 않고도 개요를 계속 볼 수 있습니다.
|
||||
|
||||
전체 운영자 원장은 CLI `openclaw tasks list`를 사용하세요.
|
||||
전체 운영자 원장을 보려면 CLI를 사용하세요: `openclaw tasks list`.
|
||||
|
||||
## 상태 통합(작업 압력)
|
||||
|
||||
`openclaw status`에는 한눈에 보는 작업 요약이 포함됩니다.
|
||||
`openclaw status`에는 한눈에 보는 작업 요약이 포함됩니다:
|
||||
|
||||
```
|
||||
Tasks: 3 queued · 2 running · 1 issues
|
||||
```
|
||||
|
||||
이 요약은 다음을 보고합니다.
|
||||
요약은 다음을 보고합니다:
|
||||
|
||||
- **active** — `queued` + `running` 개수
|
||||
- **failures** — `failed` + `timed_out` + `lost` 개수
|
||||
- **byRuntime** — `acp`, `subagent`, `cron`, `cli`별 분류
|
||||
|
||||
`/status`와 `session_status` 도구는 모두 cleanup 인지형 작업 스냅샷을 사용합니다. 활성 작업이 우선되며, 오래된 완료 행은 숨겨지고, 최근 실패는 활성 작업이 없을 때만 표시됩니다. 이렇게 하면 상태 카드가 현재 중요한 사항에 집중됩니다.
|
||||
`/status`와 `session_status` 도구는 모두 정리 상태를 인지하는 작업 스냅샷을 사용합니다: 활성 작업이 우선되며, 오래된 완료 행은 숨겨지고, 최근 실패는 활성 작업이 남아 있지 않을 때만 표시됩니다. 이렇게 하면 상태 카드가 지금 중요한 내용에 집중할 수 있습니다.
|
||||
|
||||
## 저장소 및 유지 관리
|
||||
|
||||
### 작업 저장 위치
|
||||
### 작업이 저장되는 위치
|
||||
|
||||
작업 레코드는 다음 SQLite에 영구 저장됩니다.
|
||||
작업 기록은 다음 위치의 SQLite에 영속 저장됩니다:
|
||||
|
||||
```
|
||||
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
|
||||
```
|
||||
|
||||
레지스트리는 게이트웨이 시작 시 메모리에 로드되고, 재시작 후에도 내구성을 유지할 수 있도록 쓰기를 SQLite와 동기화합니다.
|
||||
레지스트리는 게이트웨이 시작 시 메모리로 로드되며, 재시작 후에도 내구성을 보장하기 위해 쓰기 작업을 SQLite와 동기화합니다.
|
||||
|
||||
### 자동 유지 관리
|
||||
|
||||
스위퍼가 **60초**마다 실행되며 세 가지를 처리합니다.
|
||||
스위퍼가 **60초**마다 실행되며 세 가지를 처리합니다:
|
||||
|
||||
1. **조정** — 활성 작업에 여전히 권위 있는 런타임 백업이 있는지 확인합니다. ACP/하위 에이전트 작업은 하위 세션 상태를, cron 작업은 활성 작업 소유권을, 채팅 기반 CLI 작업은 소유한 실행 컨텍스트를 사용합니다. 이 백업 상태가 5분 이상 사라져 있으면 작업은 `lost`로 표시됩니다.
|
||||
2. **Cleanup stamping** — 종료된 작업에 `cleanupAfter` 타임스탬프를 설정합니다(`endedAt + 7일`).
|
||||
3. **정리** — `cleanupAfter` 날짜가 지난 레코드를 삭제합니다.
|
||||
1. **조정** — 활성 작업이 여전히 권위 있는 런타임 백킹을 갖고 있는지 확인합니다. ACP/하위 에이전트 작업은 자식 세션 상태를 사용하고, cron 작업은 활성 작업 소유 상태를 사용하며, 채팅 기반 CLI 작업은 소유한 실행 컨텍스트를 사용합니다. 이 백킹 상태가 5분 이상 사라져 있으면 작업은 `lost`로 표시됩니다.
|
||||
2. **정리 타임스탬프 기록** — 종료된 작업에 `cleanupAfter` 타임스탬프를 설정합니다(`endedAt + 7일`).
|
||||
3. **정리** — `cleanupAfter` 날짜가 지난 기록을 삭제합니다.
|
||||
|
||||
**보관 기간**: 종료된 작업 레코드는 **7일** 동안 보관된 후 자동으로 정리됩니다. 별도의 설정은 필요하지 않습니다.
|
||||
**보존 기간**: 종료된 작업 기록은 **7일** 동안 유지된 뒤 자동으로 정리됩니다. 별도 구성은 필요하지 않습니다.
|
||||
|
||||
## 작업이 다른 시스템과 연결되는 방식
|
||||
|
||||
### 작업과 Task Flow
|
||||
|
||||
[Task Flow](/ko/automation/taskflow)는 백그라운드 작업 위에 있는 흐름 오케스트레이션 계층입니다. 하나의 flow는 수명 주기 동안 관리형 또는 미러링된 동기화 모드를 사용해 여러 작업을 조정할 수 있습니다. 개별 작업 레코드를 확인하려면 `openclaw tasks`를, 오케스트레이션 흐름을 확인하려면 `openclaw tasks flow`를 사용하세요.
|
||||
[Task Flow](/ko/automation/taskflow)는 백그라운드 작업 위에 있는 플로우 오케스트레이션 계층입니다. 하나의 플로우는 수명 주기 동안 관리형 또는 미러링 동기화 모드를 사용해 여러 작업을 조정할 수 있습니다. 개별 작업 기록을 확인하려면 `openclaw tasks`를 사용하고, 오케스트레이션하는 플로우를 확인하려면 `openclaw tasks flow`를 사용하세요.
|
||||
|
||||
자세한 내용은 [Task Flow](/ko/automation/taskflow)를 참고하세요.
|
||||
자세한 내용은 [Task Flow](/ko/automation/taskflow)를 참조하세요.
|
||||
|
||||
### 작업과 cron
|
||||
|
||||
cron 작업 **정의**는 `~/.openclaw/cron/jobs.json`에 있습니다. **모든** cron 실행은 작업 레코드를 생성합니다. 주 세션과 격리 실행 모두 해당됩니다. 주 세션 cron 작업은 기본적으로 `silent` 알림 정책을 사용하므로 알림을 생성하지 않고도 추적됩니다.
|
||||
cron 작업 **정의**는 `~/.openclaw/cron/jobs.json`에 저장됩니다. **모든** cron 실행은 작업 기록을 생성합니다 — 기본 세션과 격리 실행 모두 해당됩니다. 기본 세션 cron 작업은 기본적으로 `silent` 알림 정책을 사용하므로 알림을 생성하지 않고 추적만 수행합니다.
|
||||
|
||||
[크론 작업](/ko/automation/cron-jobs)을 참고하세요.
|
||||
[Cron Jobs](/ko/automation/cron-jobs)를 참조하세요.
|
||||
|
||||
### 작업과 heartbeat
|
||||
### 작업과 하트비트
|
||||
|
||||
Heartbeat 실행은 주 세션 턴이며 작업 레코드를 생성하지 않습니다. 작업이 완료되면 heartbeat 깨우기를 트리거해 결과를 신속히 확인할 수 있습니다.
|
||||
하트비트 실행은 기본 세션 턴입니다 — 작업 기록을 생성하지 않습니다. 작업이 완료되면 결과를 빠르게 볼 수 있도록 하트비트 웨이크를 트리거할 수 있습니다.
|
||||
|
||||
[Heartbeat](/ko/gateway/heartbeat)를 참고하세요.
|
||||
[Heartbeat](/ko/gateway/heartbeat)를 참조하세요.
|
||||
|
||||
### 작업과 세션
|
||||
|
||||
작업은 `childSessionKey`(작업이 실행되는 위치)와 `requesterSessionKey`(작업을 시작한 주체)를 참조할 수 있습니다. 세션은 대화 컨텍스트이고, 작업은 그 위에서 동작 추적을 담당합니다.
|
||||
작업은 `childSessionKey`(작업이 실행되는 위치)와 `requesterSessionKey`(작업을 시작한 주체)를 참조할 수 있습니다. 세션은 대화 컨텍스트이고, 작업은 그 위에서 이루어지는 활동 추적입니다.
|
||||
|
||||
### 작업과 에이전트 실행
|
||||
|
||||
작업의 `runId`는 실제 작업을 수행하는 에이전트 실행과 연결됩니다. 에이전트 수명 주기 이벤트(시작, 종료, 오류)는 작업 상태를 자동으로 업데이트하므로, 수명 주기를 수동으로 관리할 필요가 없습니다.
|
||||
작업의 `runId`는 작업을 수행하는 에이전트 실행에 연결됩니다. 에이전트 수명 주기 이벤트(시작, 종료, 오류)는 작업 상태를 자동으로 업데이트하므로 수명 주기를 수동으로 관리할 필요가 없습니다.
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [Automation & Tasks](/ko/automation) — 모든 자동화 메커니즘 한눈에 보기
|
||||
- [Task Flow](/ko/automation/taskflow) — 작업 위의 흐름 오케스트레이션
|
||||
- [Task Flow](/ko/automation/taskflow) — 작업 위의 플로우 오케스트레이션
|
||||
- [Scheduled Tasks](/ko/automation/cron-jobs) — 백그라운드 작업 예약
|
||||
- [Heartbeat](/ko/gateway/heartbeat) — 주기적인 주 세션 턴
|
||||
- [Heartbeat](/ko/gateway/heartbeat) — 주기적인 기본 세션 턴
|
||||
- [CLI: Tasks](/cli/index#tasks) — CLI 명령 참조
|
||||
|
||||
580
docs/ko/concepts/active-memory.md
Normal file
580
docs/ko/concepts/active-memory.md
Normal file
@ -0,0 +1,580 @@
|
||||
---
|
||||
read_when:
|
||||
- 활성 메모리가 무엇을 위한 것인지 이해하고 싶습니다
|
||||
- 대화형 에이전트에 활성 메모리를 켜고 싶습니다
|
||||
- 어디에서나 활성화하지 않고 활성 메모리 동작을 조정하고 싶습니다
|
||||
summary: 대화형 채팅 세션에 관련 메모리를 주입하는 plugin 소유 차단 메모리 하위 에이전트
|
||||
title: 활성 메모리
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T05:59:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 활성 메모리
|
||||
|
||||
활성 메모리는 적격한 대화형 세션에서 메인 응답 전에 실행되는 선택적 plugin 소유 차단 메모리 하위 에이전트입니다.
|
||||
|
||||
이 기능이 존재하는 이유는 대부분의 메모리 시스템이 유능하지만 반응형이기 때문입니다. 메인 에이전트가 언제 메모리를 검색할지 결정하거나, 사용자가 "이걸 기억해" 또는 "메모리 검색해" 같은 말을 하길 기다립니다. 그 시점에는 메모리가 응답을 자연스럽게 느끼게 만들 수 있었던 순간이 이미 지나가 버립니다.
|
||||
|
||||
활성 메모리는 메인 응답이 생성되기 전에 시스템이 관련 메모리를 노출할 수 있는 제한된 한 번의 기회를 제공합니다.
|
||||
|
||||
## 이를 에이전트에 붙여 넣으세요
|
||||
|
||||
자체 포함형의 안전한 기본 설정으로 Active Memory를 활성화하려면 이것을 에이전트에 붙여 넣으세요:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
이 설정은 `main` 에이전트에 대해 plugin을 켜고, 기본적으로 direct-message 스타일 세션으로 제한하며, 먼저 현재 세션 모델을 상속하도록 하고, 명시적이거나 상속된 모델을 사용할 수 없는 경우에도 내장 원격 폴백을 허용합니다.
|
||||
|
||||
그다음 게이트웨이를 다시 시작하세요:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
대화에서 실시간으로 확인하려면:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## 활성 메모리 켜기
|
||||
|
||||
가장 안전한 설정은 다음과 같습니다:
|
||||
|
||||
1. plugin 활성화
|
||||
2. 하나의 대화형 에이전트를 대상으로 지정
|
||||
3. 조정하는 동안에만 로깅 유지
|
||||
|
||||
`openclaw.json`에서 다음으로 시작하세요:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
그런 다음 게이트웨이를 다시 시작하세요:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
이 의미는 다음과 같습니다:
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true`는 plugin을 켭니다
|
||||
- `config.agents: ["main"]`는 `main` 에이전트만 활성 메모리에 옵트인합니다
|
||||
- `config.allowedChatTypes: ["direct"]`는 기본적으로 direct-message 스타일 세션에서만 활성 메모리를 유지합니다
|
||||
- `config.model`이 설정되지 않은 경우, 활성 메모리는 먼저 현재 세션 모델을 상속합니다
|
||||
- `config.modelFallbackPolicy: "default-remote"`는 명시적이거나 상속된 모델을 사용할 수 없을 때 기본값으로 내장 원격 폴백을 유지합니다
|
||||
- `config.promptStyle: "balanced"`는 `recent` 모드에 대해 기본 범용 프롬프트 스타일을 사용합니다
|
||||
- 활성 메모리는 여전히 적격한 대화형 지속 채팅 세션에서만 실행됩니다
|
||||
|
||||
## 확인하는 방법
|
||||
|
||||
활성 메모리는 모델에 숨겨진 시스템 컨텍스트를 주입합니다. 클라이언트에 원시 `<active_memory_plugin>...</active_memory_plugin>` 태그를 노출하지 않습니다.
|
||||
|
||||
## 세션 토글
|
||||
|
||||
설정을 수정하지 않고 현재 채팅 세션에 대해 활성 메모리를 일시 중지하거나 다시 시작하려면 plugin 명령을 사용하세요:
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
/active-memory off
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
이것은 세션 범위입니다.
|
||||
`plugins.entries.active-memory.enabled`, 에이전트 대상 지정 또는 기타 전역 설정은 변경하지 않습니다.
|
||||
|
||||
명령이 설정을 기록하고 모든 세션에 대해 활성 메모리를 일시 중지하거나 다시 시작하게 하려면 명시적인 전역 형식을 사용하세요:
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
/active-memory off --global
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
전역 형식은 `plugins.entries.active-memory.config.enabled`를 기록합니다. 나중에 명령으로 활성 메모리를 다시 켤 수 있도록 `plugins.entries.active-memory.enabled`는 켜 둡니다.
|
||||
|
||||
라이브 세션에서 활성 메모리가 무엇을 하는지 보고 싶다면 해당 세션에 대해 상세 모드를 켜세요:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
상세 모드가 활성화되면 OpenClaw는 다음을 표시할 수 있습니다:
|
||||
|
||||
- `Active Memory: ok 842ms recent 34 chars`와 같은 활성 메모리 상태 줄
|
||||
- `Active Memory Debug: Lemon pepper wings with blue cheese.`와 같은 읽기 쉬운 디버그 요약
|
||||
|
||||
이 줄들은 숨겨진 시스템 컨텍스트를 공급하는 동일한 활성 메모리 패스에서 파생되지만, 원시 프롬프트 마크업을 노출하는 대신 사람이 읽을 수 있도록 형식화됩니다.
|
||||
|
||||
기본적으로 차단 메모리 하위 에이전트 전사는 임시이며 실행이 완료되면 삭제됩니다.
|
||||
|
||||
예시 흐름:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
어떤 윙을 주문해야 할까?
|
||||
```
|
||||
|
||||
예상되는 표시 응답 형태:
|
||||
|
||||
```text
|
||||
...일반적인 어시스턴트 응답...
|
||||
|
||||
🧩 Active Memory: ok 842ms recent 34 chars
|
||||
🔎 Active Memory Debug: 블루치즈를 곁들인 레몬 페퍼 윙.
|
||||
```
|
||||
|
||||
## 실행 시점
|
||||
|
||||
활성 메모리는 두 개의 게이트를 사용합니다:
|
||||
|
||||
1. **설정 옵트인**
|
||||
plugin이 활성화되어 있어야 하며, 현재 에이전트 ID가
|
||||
`plugins.entries.active-memory.config.agents`에 있어야 합니다.
|
||||
2. **엄격한 런타임 적격성**
|
||||
활성화되고 대상이 지정된 경우에도 활성 메모리는 적격한
|
||||
대화형 지속 채팅 세션에서만 실행됩니다.
|
||||
|
||||
실제 규칙은 다음과 같습니다:
|
||||
|
||||
```text
|
||||
plugin 활성화
|
||||
+
|
||||
에이전트 ID 대상 지정
|
||||
+
|
||||
허용된 채팅 유형
|
||||
+
|
||||
적격한 대화형 지속 채팅 세션
|
||||
=
|
||||
활성 메모리 실행
|
||||
```
|
||||
|
||||
이 중 하나라도 실패하면 활성 메모리는 실행되지 않습니다.
|
||||
|
||||
## 세션 유형
|
||||
|
||||
`config.allowedChatTypes`는 어떤 종류의 대화에서 Active Memory를 실행할 수 있는지 전체적으로 제어합니다.
|
||||
|
||||
기본값은 다음과 같습니다:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
즉, Active Memory는 기본적으로 direct-message 스타일 세션에서 실행되지만, group 또는 channel 세션에서는 명시적으로 옵트인하지 않는 한 실행되지 않습니다.
|
||||
|
||||
예시:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## 실행 위치
|
||||
|
||||
활성 메모리는 플랫폼 전체 추론 기능이 아니라 대화 강화 기능입니다.
|
||||
|
||||
| Surface | 활성 메모리 실행 여부 |
|
||||
| ------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Control UI / 웹 채팅 지속 세션 | 예, plugin이 활성화되어 있고 에이전트가 대상이면 실행 |
|
||||
| 같은 지속 채팅 경로의 다른 대화형 채널 세션 | 예, plugin이 활성화되어 있고 에이전트가 대상이면 실행 |
|
||||
| 헤드리스 원샷 실행 | 아니요 |
|
||||
| 하트비트/백그라운드 실행 | 아니요 |
|
||||
| 일반 내부 `agent-command` 경로 | 아니요 |
|
||||
| 하위 에이전트/내부 헬퍼 실행 | 아니요 |
|
||||
|
||||
## 사용해야 하는 이유
|
||||
|
||||
다음과 같은 경우 활성 메모리를 사용하세요:
|
||||
|
||||
- 세션이 지속적이고 사용자 대상일 때
|
||||
- 에이전트가 검색할 만한 의미 있는 장기 메모리를 가지고 있을 때
|
||||
- 연속성과 개인화가 원시 프롬프트 결정성보다 더 중요할 때
|
||||
|
||||
특히 다음에 잘 맞습니다:
|
||||
|
||||
- 안정적인 선호
|
||||
- 반복되는 습관
|
||||
- 자연스럽게 드러나야 하는 장기 사용자 컨텍스트
|
||||
|
||||
다음에는 적합하지 않습니다:
|
||||
|
||||
- 자동화
|
||||
- 내부 워커
|
||||
- 원샷 API 작업
|
||||
- 숨겨진 개인화가 놀랍게 느껴질 수 있는 곳
|
||||
|
||||
## 동작 방식
|
||||
|
||||
런타임 형태는 다음과 같습니다:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["사용자 메시지"] --> Q["메모리 쿼리 빌드"]
|
||||
Q --> R["Active Memory 차단 메모리 하위 에이전트"]
|
||||
R -->|NONE 또는 비어 있음| M["메인 응답"]
|
||||
R -->|관련 요약| I["숨겨진 active_memory_plugin 시스템 컨텍스트 추가"]
|
||||
I --> M["메인 응답"]
|
||||
```
|
||||
|
||||
차단 메모리 하위 에이전트가 사용할 수 있는 것은 다음뿐입니다:
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
연결 상태가 약하면 `NONE`을 반환해야 합니다.
|
||||
|
||||
## 쿼리 모드
|
||||
|
||||
`config.queryMode`는 차단 메모리 하위 에이전트가 얼마나 많은 대화를 볼지 제어합니다.
|
||||
|
||||
## 프롬프트 스타일
|
||||
|
||||
`config.promptStyle`는 차단 메모리 하위 에이전트가 메모리를 반환할지 결정할 때 얼마나 적극적이거나 엄격할지 제어합니다.
|
||||
|
||||
사용 가능한 스타일:
|
||||
|
||||
- `balanced`: `recent` 모드용 범용 기본값
|
||||
- `strict`: 가장 덜 적극적임; 인접한 컨텍스트의 영향이 매우 적기를 원할 때 가장 적합
|
||||
- `contextual`: 연속성 친화성이 가장 높음; 대화 기록이 더 중요해야 할 때 가장 적합
|
||||
- `recall-heavy`: 더 약하지만 여전히 그럴듯한 일치에도 메모리를 더 기꺼이 노출함
|
||||
- `precision-heavy`: 일치가 명확하지 않으면 적극적으로 `NONE`을 선호함
|
||||
- `preference-only`: 즐겨찾기, 습관, 루틴, 취향, 반복되는 개인 사실에 최적화됨
|
||||
|
||||
`config.promptStyle`이 설정되지 않았을 때의 기본 매핑:
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
`config.promptStyle`을 명시적으로 설정하면 그 재정의가 우선합니다.
|
||||
|
||||
예시:
|
||||
|
||||
```json5
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## 모델 폴백 정책
|
||||
|
||||
`config.model`이 설정되지 않은 경우, Active Memory는 다음 순서로 모델을 확인하려고 합니다:
|
||||
|
||||
```text
|
||||
명시적 plugin 모델
|
||||
-> 현재 세션 모델
|
||||
-> 에이전트 기본 모델
|
||||
-> 선택적 내장 원격 폴백
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy`는 마지막 단계를 제어합니다.
|
||||
|
||||
기본값:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
```
|
||||
|
||||
다른 옵션:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
|
||||
명시적이거나 상속된 모델을 사용할 수 없을 때 내장 원격 기본값으로 폴백하는 대신 Active Memory가 회상을 건너뛰게 하려면 `resolved-only`를 사용하세요.
|
||||
|
||||
## 고급 이스케이프 해치
|
||||
|
||||
이 옵션들은 의도적으로 권장 설정에 포함되지 않았습니다.
|
||||
|
||||
`config.thinking`은 차단 메모리 하위 에이전트의 사고 수준을 재정의할 수 있습니다:
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
```
|
||||
|
||||
기본값:
|
||||
|
||||
```json5
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
이것을 기본으로 활성화하지 마세요. Active Memory는 응답 경로에서 실행되므로 추가 사고 시간은 사용자에게 보이는 지연 시간을 직접 증가시킵니다.
|
||||
|
||||
`config.promptAppend`는 기본 Active Memory 프롬프트 뒤와 대화 컨텍스트 앞에 추가 운영자 지침을 더합니다:
|
||||
|
||||
```json5
|
||||
promptAppend: "일회성 이벤트보다 안정적인 장기 선호를 우선하세요."
|
||||
```
|
||||
|
||||
`config.promptOverride`는 기본 Active Memory 프롬프트를 대체합니다. OpenClaw는 그 뒤에 대화 컨텍스트를 계속 추가합니다:
|
||||
|
||||
```json5
|
||||
promptOverride: "당신은 메모리 검색 에이전트입니다. NONE 또는 하나의 간결한 사용자 사실을 반환하세요."
|
||||
```
|
||||
|
||||
프롬프트 커스터마이징은 의도적으로 다른 회상 계약을 테스트하는 경우가 아니라면 권장되지 않습니다. 기본 프롬프트는 메인 모델에 대해 `NONE` 또는 간결한 사용자 사실 컨텍스트를 반환하도록 조정되어 있습니다.
|
||||
|
||||
### `message`
|
||||
|
||||
최신 사용자 메시지만 전송됩니다.
|
||||
|
||||
```text
|
||||
최신 사용자 메시지만
|
||||
```
|
||||
|
||||
다음과 같은 경우 사용하세요:
|
||||
|
||||
- 가장 빠른 동작을 원할 때
|
||||
- 안정적인 선호 회상에 가장 강한 편향을 원할 때
|
||||
- 후속 턴에 대화 컨텍스트가 필요 없을 때
|
||||
|
||||
권장 타임아웃:
|
||||
|
||||
- `3000`~`5000`ms 정도에서 시작
|
||||
|
||||
### `recent`
|
||||
|
||||
최신 사용자 메시지와 소량의 최근 대화 꼬리가 전송됩니다.
|
||||
|
||||
```text
|
||||
최근 대화 꼬리:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
|
||||
최신 사용자 메시지:
|
||||
...
|
||||
```
|
||||
|
||||
다음과 같은 경우 사용하세요:
|
||||
|
||||
- 속도와 대화 맥락화 사이에서 더 나은 균형을 원할 때
|
||||
- 후속 질문이 종종 마지막 몇 턴에 의존할 때
|
||||
|
||||
권장 타임아웃:
|
||||
|
||||
- `15000`ms 정도에서 시작
|
||||
|
||||
### `full`
|
||||
|
||||
전체 대화가 차단 메모리 하위 에이전트로 전송됩니다.
|
||||
|
||||
```text
|
||||
전체 대화 컨텍스트:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
...
|
||||
```
|
||||
|
||||
다음과 같은 경우 사용하세요:
|
||||
|
||||
- 지연 시간보다 가장 강한 회상 품질이 더 중요할 때
|
||||
- 대화에 스레드 앞부분의 중요한 설정이 포함되어 있을 때
|
||||
|
||||
권장 타임아웃:
|
||||
|
||||
- `message` 또는 `recent`보다 상당히 늘리세요
|
||||
- 스레드 크기에 따라 `15000`ms 이상에서 시작
|
||||
|
||||
일반적으로 타임아웃은 컨텍스트 크기에 따라 증가해야 합니다:
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## 전사 지속성
|
||||
|
||||
활성 메모리 차단 메모리 하위 에이전트 실행은 차단 메모리 하위 에이전트 호출 중 실제 `session.jsonl` 전사를 생성합니다.
|
||||
|
||||
기본적으로 그 전사는 임시입니다:
|
||||
|
||||
- 임시 디렉터리에 기록됩니다
|
||||
- 차단 메모리 하위 에이전트 실행에만 사용됩니다
|
||||
- 실행이 끝나면 즉시 삭제됩니다
|
||||
|
||||
디버깅이나 검토를 위해 이러한 차단 메모리 하위 에이전트 전사를 디스크에 유지하려면 지속성을 명시적으로 켜세요:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
persistTranscripts: true,
|
||||
transcriptDir: "active-memory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
활성화되면 활성 메모리는 메인 사용자 대화 전사 경로가 아니라 대상 에이전트의 세션 폴더 아래 별도 디렉터리에 전사를 저장합니다.
|
||||
|
||||
기본 레이아웃의 개념은 다음과 같습니다:
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
상대 하위 디렉터리는 `config.transcriptDir`로 변경할 수 있습니다.
|
||||
|
||||
이 기능은 주의해서 사용하세요:
|
||||
|
||||
- 바쁜 세션에서는 차단 메모리 하위 에이전트 전사가 빠르게 누적될 수 있습니다
|
||||
- `full` 쿼리 모드는 많은 대화 컨텍스트를 중복할 수 있습니다
|
||||
- 이러한 전사에는 숨겨진 프롬프트 컨텍스트와 회상된 메모리가 포함됩니다
|
||||
|
||||
## 구성
|
||||
|
||||
모든 활성 메모리 구성은 다음 아래에 있습니다:
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
가장 중요한 필드는 다음과 같습니다:
|
||||
|
||||
| Key | Type | 의미 |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | plugin 자체를 활성화합니다 |
|
||||
| `config.agents` | `string[]` | 활성 메모리를 사용할 수 있는 에이전트 ID |
|
||||
| `config.model` | `string` | 선택적 차단 메모리 하위 에이전트 모델 참조; 설정되지 않으면 활성 메모리는 현재 세션 모델을 사용합니다 |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | 차단 메모리 하위 에이전트가 얼마나 많은 대화를 볼지 제어합니다 |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | 차단 메모리 하위 에이전트가 메모리를 반환할지 결정할 때 얼마나 적극적이거나 엄격할지 제어합니다 |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | 차단 메모리 하위 에이전트용 고급 사고 재정의; 속도를 위해 기본값은 `off` |
|
||||
| `config.promptOverride` | `string` | 고급 전체 프롬프트 대체; 일반적인 사용에는 권장되지 않음 |
|
||||
| `config.promptAppend` | `string` | 기본 또는 재정의된 프롬프트에 추가되는 고급 추가 지침 |
|
||||
| `config.timeoutMs` | `number` | 차단 메모리 하위 에이전트의 하드 타임아웃 |
|
||||
| `config.maxSummaryChars` | `number` | active-memory 요약에 허용되는 총 최대 문자 수 |
|
||||
| `config.logging` | `boolean` | 조정 중에 활성 메모리 로그를 출력합니다 |
|
||||
| `config.persistTranscripts` | `boolean` | 임시 파일을 삭제하는 대신 차단 메모리 하위 에이전트 전사를 디스크에 유지합니다 |
|
||||
| `config.transcriptDir` | `string` | 에이전트 세션 폴더 아래의 상대 차단 메모리 하위 에이전트 전사 디렉터리 |
|
||||
|
||||
유용한 조정 필드:
|
||||
|
||||
| Key | Type | 의미 |
|
||||
| ----------------------------- | -------- | ------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | active-memory 요약에 허용되는 총 최대 문자 수 |
|
||||
| `config.recentUserTurns` | `number` | `queryMode`가 `recent`일 때 포함할 이전 사용자 턴 수 |
|
||||
| `config.recentAssistantTurns` | `number` | `queryMode`가 `recent`일 때 포함할 이전 어시스턴트 턴 수 |
|
||||
| `config.recentUserChars` | `number` | 최근 사용자 턴당 최대 문자 수 |
|
||||
| `config.recentAssistantChars` | `number` | 최근 어시스턴트 턴당 최대 문자 수 |
|
||||
| `config.cacheTtlMs` | `number` | 반복되는 동일 쿼리에 대한 캐시 재사용 |
|
||||
|
||||
## 권장 설정
|
||||
|
||||
`recent`로 시작하세요.
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
조정하는 동안 라이브 동작을 확인하고 싶다면 별도의 active-memory 디버그 명령을 찾는 대신 세션에서 `/verbose on`을 사용하세요.
|
||||
|
||||
그런 다음 다음으로 이동하세요:
|
||||
|
||||
- 더 낮은 지연 시간을 원하면 `message`
|
||||
- 추가 컨텍스트가 더 느린 차단 메모리 하위 에이전트의 가치가 있다고 판단되면 `full`
|
||||
|
||||
## 디버깅
|
||||
|
||||
활성 메모리가 예상한 위치에 표시되지 않는다면:
|
||||
|
||||
1. `plugins.entries.active-memory.enabled` 아래에서 plugin이 활성화되어 있는지 확인합니다.
|
||||
2. 현재 에이전트 ID가 `config.agents`에 나열되어 있는지 확인합니다.
|
||||
3. 대화형 지속 채팅 세션을 통해 테스트하고 있는지 확인합니다.
|
||||
4. `config.logging: true`를 켜고 게이트웨이 로그를 확인합니다.
|
||||
5. `openclaw memory status --deep`로 메모리 검색 자체가 작동하는지 검증합니다.
|
||||
|
||||
메모리 적중이 너무 시끄럽다면 다음을 더 엄격하게 하세요:
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
활성 메모리가 너무 느리다면:
|
||||
|
||||
- `queryMode`를 낮추기
|
||||
- `timeoutMs`를 낮추기
|
||||
- 최근 턴 수 줄이기
|
||||
- 턴당 문자 제한 줄이기
|
||||
|
||||
## 관련 페이지
|
||||
|
||||
- [메모리 검색](/ko/concepts/memory-search)
|
||||
- [메모리 구성 참조](/ko/reference/memory-config)
|
||||
- [Plugin SDK 설정](/ko/plugins/sdk-setup)
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- '`memory_search`가 어떻게 작동하는지 이해하려는 경우'
|
||||
- 임베딩 provider를 선택하려는 경우
|
||||
- 검색 품질을 조정하려는 경우
|
||||
summary: 메모리 검색이 임베딩과 하이브리드 검색을 사용해 관련 메모를 찾는 방법
|
||||
- memory_search가 어떻게 작동하는지 이해하고 싶습니다.
|
||||
- 임베딩 공급자를 선택하고 싶습니다.
|
||||
- 검색 품질을 조정하고 싶습니다.
|
||||
summary: 메모리 검색은 임베딩과 하이브리드 검색을 사용해 관련 메모를 찾는 방식입니다.
|
||||
title: 메모리 검색
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:42Z"
|
||||
generated_at: "2026-04-10T06:00:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
|
||||
source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
|
||||
source_path: concepts/memory-search.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 메모리 검색
|
||||
|
||||
`memory_search`는 표현이 원문과 다르더라도 메모리 파일에서 관련 메모를 찾아냅니다. 이 기능은 메모리를 작은 청크로 인덱싱한 뒤, 임베딩, 키워드 또는 둘 다를 사용해 검색하는 방식으로 작동합니다.
|
||||
`memory_search`는 원래 텍스트와 표현이 다르더라도 메모리 파일에서 관련 메모를 찾습니다. 이 기능은 메모리를 작은 청크로 인덱싱한 뒤, 임베딩, 키워드 또는 둘 다를 사용해 검색하는 방식으로 동작합니다.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모리 검색은 자동으로 작동합니다. provider를 명시적으로 설정하려면 다음을 사용하세요.
|
||||
OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모리 검색은 자동으로 작동합니다. 공급자를 명시적으로 설정하려면 다음과 같이 하세요.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -36,21 +36,21 @@ OpenAI, Gemini, Voyage 또는 Mistral API 키가 구성되어 있으면 메모
|
||||
|
||||
API 키 없이 로컬 임베딩을 사용하려면 `provider: "local"`을 사용하세요(`node-llama-cpp` 필요).
|
||||
|
||||
## 지원되는 provider
|
||||
## 지원되는 공급자
|
||||
|
||||
| Provider | ID | API 키 필요 | 참고 |
|
||||
| -------- | --------- | ----------- | ---- |
|
||||
| OpenAI | `openai` | 예 | 자동 감지됨, 빠름 |
|
||||
| Gemini | `gemini` | 예 | 이미지/오디오 인덱싱 지원 |
|
||||
| Voyage | `voyage` | 예 | 자동 감지됨 |
|
||||
| Mistral | `mistral` | 예 | 자동 감지됨 |
|
||||
| Bedrock | `bedrock` | 아니요 | AWS 자격 증명 체인이 확인되면 자동 감지됨 |
|
||||
| Ollama | `ollama` | 아니요 | 로컬, 명시적으로 설정해야 함 |
|
||||
| Local | `local` | 아니요 | GGUF 모델, 약 0.6 GB 다운로드 |
|
||||
| 공급자 | ID | API 키 필요 | 참고 |
|
||||
| ------ | --------- | ----------- | ---------------------------------------------------- |
|
||||
| OpenAI | `openai` | 예 | 자동 감지, 빠름 |
|
||||
| Gemini | `gemini` | 예 | 이미지/오디오 인덱싱 지원 |
|
||||
| Voyage | `voyage` | 예 | 자동 감지 |
|
||||
| Mistral| `mistral` | 예 | 자동 감지 |
|
||||
| Bedrock| `bedrock` | 아니요 | AWS 자격 증명 체인이 해석되면 자동 감지 |
|
||||
| Ollama | `ollama` | 아니요 | 로컬, 명시적으로 설정해야 함 |
|
||||
| Local | `local` | 아니요 | GGUF 모델, 약 0.6 GB 다운로드 필요 |
|
||||
|
||||
## 검색 작동 방식
|
||||
|
||||
OpenClaw는 두 개의 검색 경로를 병렬로 실행하고 결과를 병합합니다.
|
||||
OpenClaw는 두 개의 검색 경로를 병렬로 실행한 뒤 결과를 병합합니다.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@ -63,31 +63,31 @@ flowchart LR
|
||||
M --> R["Top Results"]
|
||||
```
|
||||
|
||||
- **벡터 검색**은 의미가 비슷한 메모를 찾습니다("gateway host"는 "OpenClaw를 실행하는 머신"과 일치).
|
||||
- **BM25 키워드 검색**은 정확히 일치하는 항목을 찾습니다(ID, 오류 문자열, 구성 키).
|
||||
- **벡터 검색**은 의미가 비슷한 메모를 찾습니다("gateway host"는 "the machine running OpenClaw"와 일치할 수 있습니다).
|
||||
- **BM25 키워드 검색**은 정확히 일치하는 항목을 찾습니다(ID, 오류 문자열, 설정 키 등).
|
||||
|
||||
한 경로만 사용할 수 있는 경우(임베딩 없음 또는 FTS 없음), 다른 경로만 단독으로 실행됩니다.
|
||||
|
||||
## 검색 품질 개선
|
||||
|
||||
메모 기록이 많은 경우, 두 가지 선택적 기능이 도움이 됩니다.
|
||||
메모 기록이 많을 때 도움이 되는 선택적 기능 두 가지가 있습니다.
|
||||
|
||||
### 시간 감쇠
|
||||
|
||||
오래된 메모는 순위 가중치가 점차 낮아져 최근 정보가 먼저 표시됩니다.
|
||||
기본 반감기 30일에서는 지난달의 메모 점수가 원래 가중치의 50%가 됩니다.
|
||||
`MEMORY.md` 같은 상시 유지 파일에는 감쇠가 적용되지 않습니다.
|
||||
오래된 메모는 순위 가중치가 점차 낮아져 최근 정보가 먼저 노출됩니다.
|
||||
기본 반감기 30일 기준으로 지난달의 메모는 원래 가중치의 50% 점수를 받습니다.
|
||||
`MEMORY.md` 같은 상시 유효 파일에는 감쇠가 적용되지 않습니다.
|
||||
|
||||
<Tip>
|
||||
에이전트에 수개월치 일일 메모가 있고 오래된 정보가 최근 컨텍스트보다 계속 더 높은 순위에 오른다면 시간 감쇠를 활성화하세요.
|
||||
에이전트에 수개월치 일일 메모가 있고 오래된 정보가 최신 컨텍스트보다 계속 더 높은 순위에 오르면 시간 감쇠를 활성화하세요.
|
||||
</Tip>
|
||||
|
||||
### MMR(다양성)
|
||||
|
||||
중복 결과를 줄입니다. 다섯 개의 메모가 모두 같은 라우터 구성을 언급하더라도, MMR은 상위 결과가 반복되지 않고 서로 다른 주제를 다루도록 보장합니다.
|
||||
중복되는 결과를 줄입니다. 다섯 개의 메모가 모두 동일한 라우터 설정을 언급하더라도, MMR은 같은 내용이 반복되지 않도록 상위 결과가 서로 다른 주제를 다루게 합니다.
|
||||
|
||||
<Tip>
|
||||
`memory_search`가 서로 다른 일일 메모에서 거의 중복된 스니펫을 계속 반환한다면 MMR을 활성화하세요.
|
||||
`memory_search`가 서로 다른 일일 메모에서 거의 중복되는 스니펫을 계속 반환한다면 MMR을 활성화하세요.
|
||||
</Tip>
|
||||
|
||||
### 둘 다 활성화
|
||||
@ -112,24 +112,23 @@ flowchart LR
|
||||
## 멀티모달 메모리
|
||||
|
||||
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`를 실행해 인덱스를 확인하세요. 비어 있다면 `openclaw memory index --force`를 실행하세요.
|
||||
|
||||
**키워드 일치만 나오나요?** 임베딩 provider가 구성되지 않았을 수 있습니다. `openclaw memory status --deep`를 확인하세요.
|
||||
**키워드 일치만 되나요?** 임베딩 공급자가 구성되지 않았을 수 있습니다. `openclaw memory status --deep`로 확인하세요.
|
||||
|
||||
**CJK 텍스트를 찾을 수 없나요?** `openclaw memory index --force`로 FTS 인덱스를 다시 빌드하세요.
|
||||
**CJK 텍스트가 검색되지 않나요?** `openclaw memory index --force`로 FTS 인덱스를 다시 빌드하세요.
|
||||
|
||||
## 추가 읽을거리
|
||||
## 더 읽어보기
|
||||
|
||||
- [메모리](/ko/concepts/memory) -- 파일 레이아웃, 백엔드, 도구
|
||||
- [메모리 구성 참조](/ko/reference/memory-config) -- 모든 구성 옵션
|
||||
- [Active Memory](/ko/concepts/active-memory) -- 대화형 채팅 세션을 위한 서브 에이전트 메모리
|
||||
- [Memory](/ko/concepts/memory) -- 파일 레이아웃, 백엔드, 도구
|
||||
- [Memory configuration reference](/ko/reference/memory-config) -- 모든 구성 옵션
|
||||
|
||||
@ -1,50 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- qa-lab 또는 qa-channel 확장 시
|
||||
- 리포지토리 기반 QA 시나리오 추가 시
|
||||
- Gateway 대시보드를 중심으로 더 높은 현실성의 QA 자동화 구축 시
|
||||
summary: qa-lab, qa-channel, 시드된 시나리오, 프로토콜 보고서를 위한 비공개 QA 자동화 구성
|
||||
- qa-lab 또는 qa-channel 확장하기
|
||||
- 리포지토리 기반 QA 시나리오 추가하기
|
||||
- Gateway 대시보드를 중심으로 더 현실적인 QA 자동화 구축하기
|
||||
summary: qa-lab, qa-channel, 시드된 시나리오, 프로토콜 보고서를 위한 비공개 QA 자동화 구조
|
||||
title: QA E2E 자동화
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:48Z"
|
||||
generated_at: "2026-04-10T05:59:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
|
||||
source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# QA E2E 자동화
|
||||
|
||||
비공개 QA 스택은 단일 단위 테스트보다 더 현실적이고
|
||||
채널 형태에 가까운 방식으로 OpenClaw를 검증하도록 설계되었습니다.
|
||||
비공개 QA 스택은 단일 단위 테스트보다 더 현실적이고,
|
||||
채널 형태에 가까운 방식으로 OpenClaw를 검증하기 위한 것입니다.
|
||||
|
||||
현재 구성 요소:
|
||||
|
||||
- `extensions/qa-channel`: DM, 채널, 스레드,
|
||||
리액션, 편집, 삭제 인터페이스를 갖춘 합성 메시지 채널
|
||||
- `extensions/qa-lab`: 트랜스크립트를 관찰하고,
|
||||
인바운드 메시지를 주입하며, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스
|
||||
- `extensions/qa-lab`: 대화 기록을 관찰하고,
|
||||
인바운드 메시지를 주입하고, Markdown 보고서를 내보내기 위한 디버거 UI 및 QA 버스
|
||||
- `qa/`: 시작 작업과 기본 QA
|
||||
시나리오를 위한 리포지토리 기반 시드 자산
|
||||
|
||||
현재 QA 운영자 흐름은 2패널 QA 사이트입니다:
|
||||
현재 QA 운영자 흐름은 2개 패널로 구성된 QA 사이트입니다:
|
||||
|
||||
- 왼쪽: 에이전트가 있는 Gateway 대시보드(Control UI)
|
||||
- 오른쪽: Slack 스타일의 트랜스크립트와 시나리오 계획을 보여주는 QA Lab
|
||||
- 오른쪽: Slack과 유사한 대화 기록과 시나리오 계획을 보여주는 QA Lab
|
||||
|
||||
다음으로 실행합니다:
|
||||
다음 명령으로 실행합니다:
|
||||
|
||||
```bash
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
이 명령은 QA 사이트를 빌드하고, Docker 기반 gateway 레인을 시작하며, 운영자나 자동화 루프가 에이전트에 QA
|
||||
미션을 부여하고, 실제 채널 동작을 관찰하며, 무엇이 작동했고 실패했으며
|
||||
또는 계속 막혀 있었는지를 기록할 수 있는 QA Lab 페이지를 노출합니다.
|
||||
이 명령은 QA 사이트를 빌드하고, Docker 기반 Gateway 레인을 시작하며,
|
||||
운영자 또는 자동화 루프가 에이전트에 QA
|
||||
미션을 부여하고, 실제 채널 동작을 관찰하고, 무엇이 작동했고, 실패했고, 계속 막혀 있었는지 기록할 수 있는
|
||||
QA Lab 페이지를 노출합니다.
|
||||
|
||||
매번 Docker 이미지를 다시 빌드하지 않고 QA Lab UI를 더 빠르게 반복 개발하려면,
|
||||
bind mount된 QA Lab 번들로 스택을 시작하세요:
|
||||
매번 Docker 이미지를 다시 빌드하지 않고 더 빠르게 QA Lab UI를 반복 개발하려면,
|
||||
바인드 마운트된 QA Lab 번들로 스택을 시작하세요:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -53,9 +54,24 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast`는 사전 빌드된 이미지에서 Docker 서비스를 유지하고
|
||||
`extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 bind mount합니다. `qa:lab:watch`는
|
||||
변경 시 해당 번들을 다시 빌드하고, QA Lab 자산 해시가 변경되면 브라우저가 자동으로 다시 로드됩니다.
|
||||
`qa:lab:up:fast`는 Docker 서비스를 사전 빌드된 이미지로 유지하고
|
||||
`extensions/qa-lab/web/dist`를 `qa-lab` 컨테이너에 바인드 마운트합니다. `qa:lab:watch`는
|
||||
변경 시 해당 번들을 다시 빌드하며, QA Lab 자산 해시가 바뀌면 브라우저가 자동으로 다시 로드됩니다.
|
||||
|
||||
QA 경로에 Docker를 포함하지 않는 일회용 Linux VM 레인의 경우 다음을 실행하세요:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
이 명령은 새 Multipass 게스트를 부팅하고, 의존성을 설치하고, 게스트 내부에서 OpenClaw를 빌드하고,
|
||||
`qa suite`를 실행한 다음, 일반 QA 보고서와
|
||||
요약을 다시 호스트의 `.artifacts/qa-e2e/...`로 복사합니다.
|
||||
시나리오 선택 동작은 호스트에서의 `qa suite`와 동일하게 재사용합니다.
|
||||
라이브 실행은 게스트에서 실용적으로 사용할 수 있는 지원 QA 인증 입력을 전달합니다:
|
||||
환경 변수 기반 제공자 키, QA 라이브 제공자 구성 경로,
|
||||
그리고 존재할 경우 `CODEX_HOME`입니다. 게스트가
|
||||
마운트된 워크스페이스를 통해 다시 쓸 수 있도록 `--output-dir`은 리포지토리 루트 아래에 유지하세요.
|
||||
|
||||
## 리포지토리 기반 시드
|
||||
|
||||
@ -64,8 +80,9 @@ pnpm qa:lab:watch
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
|
||||
이 파일들은 QA 계획이 사람과
|
||||
에이전트 모두에게 보이도록 의도적으로 git에 포함됩니다. 기본 목록은 다음을 포괄할 만큼 충분히 넓게 유지되어야 합니다:
|
||||
이 항목들은 QA 계획이 사람과
|
||||
에이전트 모두에게 보이도록 의도적으로 git에 포함됩니다. 기본 목록은 다음을 포괄할 수 있을 만큼
|
||||
충분히 넓어야 합니다:
|
||||
|
||||
- DM 및 채널 채팅
|
||||
- 스레드 동작
|
||||
@ -73,22 +90,22 @@ pnpm qa:lab:watch
|
||||
- cron 콜백
|
||||
- 메모리 회상
|
||||
- 모델 전환
|
||||
- 서브에이전트 핸드오프
|
||||
- 하위 에이전트 핸드오프
|
||||
- 리포지토리 읽기 및 문서 읽기
|
||||
- Lobster Invaders 같은 작은 빌드 작업 하나
|
||||
- Lobster Invaders와 같은 작은 빌드 작업 하나
|
||||
|
||||
## 보고
|
||||
|
||||
`qa-lab`은 관찰된 버스 타임라인에서 Markdown 프로토콜 보고서를 내보냅니다.
|
||||
보고서는 다음에 답해야 합니다:
|
||||
이 보고서는 다음에 답해야 합니다:
|
||||
|
||||
- 무엇이 작동했는가
|
||||
- 무엇이 실패했는가
|
||||
- 무엇이 계속 막혀 있었는가
|
||||
- 어떤 후속 시나리오를 추가할 가치가 있는가
|
||||
|
||||
캐릭터 및 스타일 검사를 위해 동일한 시나리오를 여러 라이브 모델
|
||||
ref에서 실행하고 판단된 Markdown 보고서를 작성하세요:
|
||||
캐릭터 및 스타일 점검을 위해, 동일한 시나리오를 여러 라이브 모델 ref에 걸쳐 실행하고
|
||||
판정된 Markdown 보고서를 작성하세요:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -107,36 +124,38 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
이 명령은 Docker가 아니라 로컬 QA gateway 자식 프로세스를 실행합니다. 캐릭터 평가
|
||||
시나리오는 `SOUL.md`를 통해 페르소나를 설정한 다음, 채팅, 워크스페이스 도움말, 작은 파일 작업과 같은
|
||||
일반 사용자 턴을 실행해야 합니다. 후보 모델에는 자신이 평가되고 있다는 사실을 알려서는 안 됩니다.
|
||||
이 명령은 각 전체 트랜스크립트를 보존하고, 기본 실행 통계를 기록한 뒤, judge 모델에 fast 모드와
|
||||
`xhigh` 추론을 사용해 자연스러움, 분위기, 유머를 기준으로 실행 결과의 순위를 매기도록 요청합니다.
|
||||
제공자들을 비교할 때는 `--blind-judge-models`를 사용하세요. 이 경우 judge 프롬프트는 여전히
|
||||
모든 트랜스크립트와 실행 상태를 받지만, 후보 ref는 `candidate-01` 같은 중립적인
|
||||
레이블로 대체됩니다. 보고서는 파싱 후 순위를 실제 ref에 다시 매핑합니다.
|
||||
후보 실행은 기본적으로 `high` thinking을 사용하며, 이를 지원하는 OpenAI 모델은 `xhigh`를 사용합니다.
|
||||
특정 후보를 개별적으로 재정의하려면
|
||||
`--model provider/model,thinking=<level>`을 사용하세요. `--thinking <level>`은 여전히 전역 기본값을 설정하며,
|
||||
기존의 `--model-thinking <provider/model=level>` 형식도 호환성을 위해 유지됩니다.
|
||||
OpenAI 후보 ref는 기본적으로 fast 모드를 사용하므로, 제공자가 이를 지원하는 경우 우선 처리됩니다.
|
||||
단일 후보나 judge에 재정의가 필요하면 인라인으로 `,fast`, `,no-fast`, 또는 `,fast=false`를 추가하세요.
|
||||
모든 후보 모델에 fast 모드를 강제로 적용하려는 경우에만 `--fast`를 전달하세요. 후보와 judge의 실행 시간은
|
||||
벤치마크 분석을 위해 보고서에 기록되지만, judge 프롬프트에는 속도로 순위를 매기지 말라고 명시되어 있습니다.
|
||||
후보 및 judge 모델 실행은 모두 기본적으로 동시성 16을 사용합니다.
|
||||
제공자 제한이나 로컬 gateway 부하 때문에 실행이 너무 불안정해지면
|
||||
`--concurrency` 또는 `--judge-concurrency`를 낮추세요.
|
||||
후보 `--model`이 전달되지 않으면 character eval은 기본적으로
|
||||
이 명령은 Docker가 아니라 로컬 QA Gateway 자식 프로세스를 실행합니다. 캐릭터 평가
|
||||
시나리오는 `SOUL.md`를 통해 페르소나를 설정한 다음, 채팅, 워크스페이스 도움말,
|
||||
작은 파일 작업과 같은 일반 사용자 턴을 실행해야 합니다. 후보 모델에는
|
||||
평가 중이라는 사실을 알려주면 안 됩니다. 이 명령은 각 전체 대화 기록을 보존하고,
|
||||
기본 실행 통계를 기록한 다음, 판정 모델에 빠른 모드와
|
||||
`xhigh` 추론으로 실행 결과를 자연스러움, 분위기, 유머 기준으로 순위를 매기도록 요청합니다.
|
||||
제공자 간 비교 시에는 `--blind-judge-models`를 사용하세요. 판정 프롬프트는 여전히
|
||||
모든 대화 기록과 실행 상태를 받지만, 후보 ref는
|
||||
`candidate-01` 같은 중립적인 레이블로 대체됩니다. 이후 보고서는 파싱 후 순위를 실제 ref에 다시 매핑합니다.
|
||||
후보 실행은 기본적으로 `high` 추론을 사용하며, 이를 지원하는 OpenAI 모델의 경우 `xhigh`를 사용합니다.
|
||||
특정 후보를 개별적으로 덮어쓰려면
|
||||
`--model provider/model,thinking=<level>`을 사용하세요. `--thinking <level>`은 여전히
|
||||
전역 대체값을 설정하며, 이전의 `--model-thinking <provider/model=level>` 형식도
|
||||
호환성을 위해 유지됩니다.
|
||||
OpenAI 후보 ref는 제공자가 지원하는 경우 우선 처리에 fast 모드를 사용하도록 기본 설정됩니다.
|
||||
단일 후보 또는 판정자에 대해 재정의가 필요하면 인라인으로 `,fast`, `,no-fast`, 또는 `,fast=false`를 추가하세요.
|
||||
모든 후보 모델에 fast 모드를 강제로 적용하려는 경우에만 `--fast`를 전달하세요. 후보 및
|
||||
판정 모델 실행 시간은 벤치마크 분석을 위해 보고서에 기록되지만,
|
||||
판정 프롬프트에는 속도로 순위를 매기지 말라고 명시되어 있습니다.
|
||||
후보 및 판정 모델 실행은 둘 다 기본 동시성 16을 사용합니다. 제공자 제한 또는 로컬 Gateway
|
||||
부하로 인해 실행 결과에 노이즈가 너무 많다면 `--concurrency` 또는 `--judge-concurrency`를 낮추세요.
|
||||
후보 `--model`이 전달되지 않으면, 캐릭터 평가는 기본적으로
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5`, 그리고
|
||||
`google/gemini-3.1-pro-preview`를 사용합니다.
|
||||
`--judge-model`이 전달되지 않으면 judge는 기본적으로
|
||||
판정 `--judge-model`이 전달되지 않으면, 판정자는 기본적으로
|
||||
`openai/gpt-5.4,thinking=xhigh,fast` 및
|
||||
`anthropic/claude-opus-4-6,thinking=high`를 사용합니다.
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [테스트](/ko/help/testing)
|
||||
- [QA 채널](/ko/channels/qa-channel)
|
||||
- [QA Channel](/ko/channels/qa-channel)
|
||||
- [대시보드](/web/dashboard)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,47 +1,58 @@
|
||||
---
|
||||
read_when:
|
||||
- 메모리 검색 provider 또는 임베딩 모델을 구성하고 싶을 때
|
||||
- QMD 백엔드를 설정하고 싶을 때
|
||||
- 하이브리드 검색, MMR 또는 시간 감쇠를 조정하고 싶을 때
|
||||
- 멀티모달 메모리 인덱싱을 활성화하고 싶을 때
|
||||
summary: 메모리 검색, 임베딩 provider, QMD, 하이브리드 검색, 멀티모달 인덱싱을 위한 모든 구성 항목
|
||||
- 메모리 검색 제공자나 임베딩 모델을 구성하려고 합니다
|
||||
- QMD 백엔드를 설정하려고 합니다
|
||||
- 하이브리드 검색, MMR 또는 시간 감쇠를 조정하려고 합니다
|
||||
- 멀티모달 메모리 인덱싱을 활성화하려고 합니다
|
||||
summary: 메모리 검색, 임베딩 제공자, QMD, 하이브리드 검색, 멀티모달 인덱싱에 대한 모든 구성 옵션
|
||||
title: 메모리 구성 참조
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:12:41Z"
|
||||
generated_at: "2026-04-10T05:59:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
|
||||
source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 메모리 구성 참조
|
||||
|
||||
이 페이지는 OpenClaw 메모리 검색의 모든 구성 항목을 나열합니다.
|
||||
개념적 개요는 다음을 참고하세요.
|
||||
이 페이지에는 OpenClaw 메모리 검색의 모든 구성 옵션이 나열되어 있습니다. 개념적 개요는 다음 문서를 참조하세요.
|
||||
|
||||
- [Memory Overview](/ko/concepts/memory) -- 메모리가 동작하는 방식
|
||||
- [Builtin Engine](/ko/concepts/memory-builtin) -- 기본 SQLite 백엔드
|
||||
- [QMD Engine](/ko/concepts/memory-qmd) -- 로컬 우선 사이드카
|
||||
- [Memory Search](/ko/concepts/memory-search) -- 검색 파이프라인 및 조정
|
||||
- [메모리 개요](/ko/concepts/memory) -- 메모리가 작동하는 방식
|
||||
- [내장 엔진](/ko/concepts/memory-builtin) -- 기본 SQLite 백엔드
|
||||
- [QMD 엔진](/ko/concepts/memory-qmd) -- 로컬 우선 사이드카
|
||||
- [메모리 검색](/ko/concepts/memory-search) -- 검색 파이프라인 및 튜닝
|
||||
- [액티브 메모리](/ko/concepts/active-memory) -- 대화형 세션에 메모리 하위 에이전트를 활성화하는 방법
|
||||
|
||||
별도로 언급되지 않는 한 모든 메모리 검색 설정은
|
||||
`openclaw.json`의 `agents.defaults.memorySearch` 아래에 있습니다.
|
||||
모든 메모리 검색 설정은 별도 언급이 없는 한 `openclaw.json`의
|
||||
`agents.defaults.memorySearch` 아래에 있습니다.
|
||||
|
||||
**액티브 메모리** 기능 토글과 하위 에이전트 구성을 찾고 있다면,
|
||||
이는 `memorySearch`가 아니라 `plugins.entries.active-memory` 아래에 있습니다.
|
||||
|
||||
액티브 메모리는 2단계 게이트 모델을 사용합니다.
|
||||
|
||||
1. 플러그인이 활성화되어 있어야 하며 현재 에이전트 ID를 대상으로 해야 합니다
|
||||
2. 요청이 적격한 대화형 영구 채팅 세션이어야 합니다
|
||||
|
||||
활성화 모델, 플러그인 소유 구성, 트랜스크립트 영속성, 안전한 롤아웃 패턴은
|
||||
[액티브 메모리](/ko/concepts/active-memory)를 참조하세요.
|
||||
|
||||
---
|
||||
|
||||
## Provider 선택
|
||||
## 제공자 선택
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ---------- | --------- | -------------- | -------------------------------------------------------------------------------------- |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ---------- | --------- | -------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `provider` | `string` | 자동 감지 | 임베딩 어댑터 ID: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `model` | `string` | provider 기본값 | 임베딩 모델 이름 |
|
||||
| `fallback` | `string` | `"none"` | 기본 어댑터가 실패할 때 사용할 대체 어댑터 ID |
|
||||
| `enabled` | `boolean` | `true` | 메모리 검색 활성화 또는 비활성화 |
|
||||
| `model` | `string` | 제공자 기본값 | 임베딩 모델 이름 |
|
||||
| `fallback` | `string` | `"none"` | 기본 제공자가 실패할 때 사용할 대체 어댑터 ID |
|
||||
| `enabled` | `boolean` | `true` | 메모리 검색 활성화 또는 비활성화 |
|
||||
|
||||
### 자동 감지 순서
|
||||
|
||||
`provider`가 설정되지 않은 경우 OpenClaw는 사용 가능한 첫 항목을 선택합니다.
|
||||
`provider`가 설정되지 않으면 OpenClaw는 사용 가능한 첫 번째 항목을 선택합니다.
|
||||
|
||||
1. `local` -- `memorySearch.local.modelPath`가 구성되어 있고 파일이 존재하는 경우
|
||||
2. `openai` -- OpenAI 키를 확인할 수 있는 경우
|
||||
@ -50,36 +61,36 @@ x-i18n:
|
||||
5. `mistral` -- Mistral 키를 확인할 수 있는 경우
|
||||
6. `bedrock` -- AWS SDK 자격 증명 체인이 확인되는 경우(인스턴스 역할, 액세스 키, 프로필, SSO, 웹 아이덴티티 또는 공유 구성)
|
||||
|
||||
`ollama`도 지원되지만 자동 감지는 하지 않습니다(명시적으로 설정하세요).
|
||||
`ollama`도 지원되지만 자동 감지되지는 않습니다(명시적으로 설정해야 함).
|
||||
|
||||
### API 키 확인
|
||||
|
||||
원격 임베딩에는 API 키가 필요합니다. 대신 Bedrock은 AWS SDK 기본
|
||||
자격 증명 체인(인스턴스 역할, SSO, 액세스 키)을 사용합니다.
|
||||
|
||||
| Provider | Env var | 구성 키 |
|
||||
| -------- | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | AWS 자격 증명 체인 | API 키 필요 없음 |
|
||||
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
|
||||
| 제공자 | 환경 변수 | 구성 키 |
|
||||
| ------ | ----------------------------- | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | AWS 자격 증명 체인 | API 키 필요 없음 |
|
||||
| Ollama | `OLLAMA_API_KEY` (자리표시자) | -- |
|
||||
|
||||
Codex OAuth는 채팅/completions만 지원하며 임베딩
|
||||
Codex OAuth는 채팅/완성 요청만 지원하며 임베딩
|
||||
요청에는 사용할 수 없습니다.
|
||||
|
||||
---
|
||||
|
||||
## 원격 엔드포인트 구성
|
||||
|
||||
사용자 지정 OpenAI 호환 엔드포인트를 사용하거나 provider 기본값을 재정의하려면 다음을 사용하세요.
|
||||
사용자 지정 OpenAI 호환 엔드포인트를 사용하거나 제공자 기본값을 재정의하려면 다음을 사용하세요.
|
||||
|
||||
| 키 | 타입 | 설명 |
|
||||
| ---------------- | -------- | ---------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | 사용자 지정 API 기본 URL |
|
||||
| `remote.apiKey` | `string` | API 키 재정의 |
|
||||
| `remote.headers` | `object` | 추가 HTTP 헤더(provider 기본값과 병합됨) |
|
||||
| 키 | 유형 | 설명 |
|
||||
| ---------------- | -------- | -------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | 사용자 지정 API 기본 URL |
|
||||
| `remote.apiKey` | `string` | API 키 재정의 |
|
||||
| `remote.headers` | `object` | 추가 HTTP 헤더(제공자 기본값과 병합됨) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -102,22 +113,22 @@ Codex OAuth는 채팅/completions만 지원하며 임베딩
|
||||
|
||||
## Gemini 전용 구성
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | `gemini-embedding-2-preview`도 지원 |
|
||||
| `outputDimensionality` | `number` | `3072` | Embedding 2의 경우: 768, 1536 또는 3072 |
|
||||
|
||||
<Warning>
|
||||
모델 또는 `outputDimensionality`를 변경하면 자동으로 전체 재인덱싱이 수행됩니다.
|
||||
모델 또는 `outputDimensionality`를 변경하면 자동으로 전체 재인덱싱이 트리거됩니다.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Bedrock 임베딩 구성
|
||||
|
||||
Bedrock은 AWS SDK 기본 자격 증명 체인을 사용하므로 API 키가 필요하지 않습니다.
|
||||
Bedrock은 AWS SDK 기본 자격 증명 체인을 사용하므로 API 키가 필요 없습니다.
|
||||
OpenClaw가 Bedrock이 활성화된 인스턴스 역할이 있는 EC2에서 실행 중이라면,
|
||||
provider와 모델만 설정하면 됩니다.
|
||||
제공자와 모델만 설정하면 됩니다.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -132,47 +143,47 @@ provider와 모델만 설정하면 됩니다.
|
||||
}
|
||||
```
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 모든 Bedrock 임베딩 모델 ID |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------ |
|
||||
| `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 자격 증명 확인 순서를 사용합니다.
|
||||
|
||||
1. 환경 변수(`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
1. 환경 변수 (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
2. SSO 토큰 캐시
|
||||
3. 웹 아이덴티티 토큰 자격 증명
|
||||
4. 공유 자격 증명 및 구성 파일
|
||||
5. ECS 또는 EC2 메타데이터 자격 증명
|
||||
|
||||
리전은 `AWS_REGION`, `AWS_DEFAULT_REGION`, `amazon-bedrock`
|
||||
provider의 `baseUrl`에서 확인되며, 없으면 기본값은 `us-east-1`입니다.
|
||||
리전은 `AWS_REGION`, `AWS_DEFAULT_REGION`,
|
||||
`amazon-bedrock` 제공자의 `baseUrl`에서 확인되며, 없으면 기본값으로 `us-east-1`을 사용합니다.
|
||||
|
||||
### IAM 권한
|
||||
|
||||
IAM 역할 또는 사용자에게 다음 권한이 필요합니다.
|
||||
IAM 역할 또는 사용자에게는 다음 권한이 필요합니다.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -192,13 +203,13 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
## 로컬 임베딩 구성
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------------- |
|
||||
| `local.modelPath` | `string` | 자동 다운로드 | GGUF 모델 파일 경로 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------------ |
|
||||
| `local.modelPath` | `string` | 자동 다운로드 | GGUF 모델 파일 경로 |
|
||||
| `local.modelCacheDir` | `string` | node-llama-cpp 기본값 | 다운로드된 모델의 캐시 디렉터리 |
|
||||
|
||||
기본 모델: `embeddinggemma-300m-qat-Q8_0.gguf`(~0.6 GB, 자동 다운로드).
|
||||
네이티브 빌드가 필요합니다: `pnpm approve-builds` 후 `pnpm rebuild node-llama-cpp`.
|
||||
기본 모델: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, 자동 다운로드).
|
||||
네이티브 빌드가 필요합니다: `pnpm approve-builds` 다음 `pnpm rebuild node-llama-cpp`.
|
||||
|
||||
---
|
||||
|
||||
@ -206,28 +217,28 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
모두 `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(다양성)
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ------------- | --------- | ------ | ----------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | MMR 재순위화 활성화 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 최대 다양성, 1 = 최대 관련성 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ------------- | --------- | ------ | ------------------------------------ |
|
||||
| `mmr.enabled` | `boolean` | `false`| MMR 재순위화 활성화 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 최대 다양성, 1 = 최대 관련성 |
|
||||
|
||||
### 시간 감쇠(최신성)
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ---------------------------- | --------- | ------ | ------------------------------ |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 최신성 부스트 활성화 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | N일마다 점수가 절반으로 감소 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ---------------------------- | --------- | ------ | --------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false`| 최신성 부스트 활성화 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | N일마다 점수가 절반으로 감소 |
|
||||
|
||||
상시 유지 파일(`MEMORY.md`, `memory/` 내 날짜가 없는 파일)은 감쇠되지 않습니다.
|
||||
에버그린 파일(`MEMORY.md`, `memory/`의 날짜가 없는 파일)은 감쇠되지 않습니다.
|
||||
|
||||
### 전체 예시
|
||||
|
||||
@ -254,9 +265,9 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
## 추가 메모리 경로
|
||||
|
||||
| 키 | 타입 | 설명 |
|
||||
| ------------ | ---------- | --------------------------------- |
|
||||
| `extraPaths` | `string[]` | 인덱싱할 추가 디렉터리 또는 파일 |
|
||||
| 키 | 유형 | 설명 |
|
||||
| ------------ | ---------- | ------------------------------------- |
|
||||
| `extraPaths` | `string[]` | 인덱싱할 추가 디렉터리 또는 파일 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -270,154 +281,152 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
}
|
||||
```
|
||||
|
||||
경로는 절대 경로 또는 workspace 기준 상대 경로일 수 있습니다. 디렉터리는
|
||||
경로는 절대 경로이거나 워크스페이스 기준 상대 경로일 수 있습니다. 디렉터리는
|
||||
`.md` 파일을 재귀적으로 스캔합니다. 심볼릭 링크 처리 방식은 활성 백엔드에 따라 다릅니다.
|
||||
builtin 엔진은 심볼릭 링크를 무시하고, QMD는 기반 QMD
|
||||
스캐너 동작을 따릅니다.
|
||||
내장 엔진은 심볼릭 링크를 무시하고, QMD는 기반 QMD 스캐너의 동작을 따릅니다.
|
||||
|
||||
에이전트 범위의 교차 에이전트 transcript 검색에는
|
||||
`memory.qmd.paths` 대신 `agents.list[].memorySearch.qmd.extraCollections`를
|
||||
사용하세요. 이 추가 컬렉션은 동일한 `{ path, name, pattern? }` 형태를 따르지만,
|
||||
에이전트별로 병합되며 경로가 현재 workspace 밖을 가리킬 때도
|
||||
명시적인 공유 이름을 유지할 수 있습니다.
|
||||
같은 확인된 경로가 `memory.qmd.paths`와
|
||||
`memorySearch.qmd.extraCollections`에 모두 나타나면 QMD는 첫 번째 항목을 유지하고
|
||||
중복은 건너뜁니다.
|
||||
에이전트 범위의 교차 에이전트 트랜스크립트 검색에는
|
||||
`memory.qmd.paths` 대신 `agents.list[].memorySearch.qmd.extraCollections`를 사용하세요.
|
||||
이 추가 컬렉션은 동일한 `{ path, name, pattern? }` 형태를 따르지만,
|
||||
에이전트별로 병합되며 경로가 현재 워크스페이스 밖을 가리킬 때 명시적인 공유 이름을 유지할 수 있습니다.
|
||||
동일한 확인된 경로가 `memory.qmd.paths`와
|
||||
`memorySearch.qmd.extraCollections`에 모두 나타나면, QMD는 첫 번째 항목을 유지하고
|
||||
중복 항목은 건너뜁니다.
|
||||
|
||||
---
|
||||
|
||||
## 멀티모달 메모리(Gemini)
|
||||
|
||||
Gemini Embedding 2를 사용해 Markdown과 함께 이미지와 오디오도 인덱싱합니다.
|
||||
Gemini Embedding 2를 사용해 Markdown과 함께 이미지와 오디오를 인덱싱합니다.
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ------------------------- | ---------- | ---------- | ---------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 멀티모달 인덱싱 활성화 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` 또는 `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 인덱싱할 최대 파일 크기 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ------------------------- | ---------- | ---------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 멀티모달 인덱싱 활성화 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` 또는 `["all"]` |
|
||||
| `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`(오디오).
|
||||
(이미지); `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac` (오디오).
|
||||
|
||||
---
|
||||
|
||||
## 임베딩 캐시
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ------------------ | --------- | ------ | ----------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | SQLite에 청크 임베딩 캐시 |
|
||||
| `cache.maxEntries` | `number` | `50000` | 최대 캐시 임베딩 수 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ------------------ | --------- | ------ | ------------------------------ |
|
||||
| `cache.enabled` | `boolean` | `false`| SQLite에 청크 임베딩 캐시 |
|
||||
| `cache.maxEntries` | `number` | `50000`| 캐시할 최대 임베딩 수 |
|
||||
|
||||
재인덱싱 또는 transcript 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하는 일을 방지합니다.
|
||||
재인덱싱 또는 트랜스크립트 업데이트 중 변경되지 않은 텍스트를 다시 임베딩하는 일을 방지합니다.
|
||||
|
||||
---
|
||||
|
||||
## 배치 인덱싱
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ----------------------------- | --------- | ------ | ------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | 배치 임베딩 API 활성화 |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 병렬 배치 작업 수 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 배치 완료까지 대기 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 폴링 간격 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 배치 타임아웃 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ----------------------------- | --------- | ------ | ---------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false`| 배치 임베딩 API 활성화 |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 병렬 배치 작업 수 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 배치 완료까지 대기 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 폴링 간격 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 배치 타임아웃 |
|
||||
|
||||
`openai`, `gemini`, `voyage`에서 사용할 수 있습니다. OpenAI 배치는 일반적으로
|
||||
대규모 백필에서 가장 빠르고 저렴합니다.
|
||||
대규모 백필에서 가장 빠르고 비용도 가장 저렴합니다.
|
||||
|
||||
---
|
||||
|
||||
## 세션 메모리 검색(실험적)
|
||||
|
||||
세션 transcript를 인덱싱하고 `memory_search`를 통해 노출합니다.
|
||||
세션 트랜스크립트를 인덱싱하고 `memory_search`를 통해 노출합니다.
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ----------------------------- | ---------- | ------------ | ----------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | 세션 인덱싱 활성화 |
|
||||
| `sources` | `string[]` | `["memory"]` | transcript를 포함하려면 `"sessions"` 추가 |
|
||||
| `sources` | `string[]` | `["memory"]` | 트랜스크립트를 포함하려면 `"sessions"` 추가 |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | 재인덱싱 바이트 임계값 |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | 재인덱싱 메시지 임계값 |
|
||||
|
||||
세션 인덱싱은 opt-in이며 비동기적으로 실행됩니다. 결과는 약간
|
||||
오래되었을 수 있습니다. 세션 로그는 디스크에 있으므로 파일 시스템 접근을
|
||||
신뢰 경계로 취급하세요.
|
||||
세션 인덱싱은 옵트인 방식이며 비동기적으로 실행됩니다. 결과는 약간
|
||||
오래되었을 수 있습니다. 세션 로그는 디스크에 저장되므로 파일 시스템 접근을
|
||||
신뢰 경계로 취급해야 합니다.
|
||||
|
||||
---
|
||||
|
||||
## 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는 자동으로 프로세스 내 cosine
|
||||
similarity로 대체합니다.
|
||||
sqlite-vec를 사용할 수 없으면 OpenClaw는 자동으로 프로세스 내 코사인
|
||||
유사도로 대체합니다.
|
||||
|
||||
---
|
||||
|
||||
## 인덱스 저장소
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| --------------------- | -------- | ------------------------------------ | ----------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 인덱스 위치(`{agentId}` 토큰 지원) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer(`unicode61` 또는 `trigram`) |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| --------------------- | -------- | ------------------------------------- | ---------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 인덱스 위치(`{agentId}` 토큰 지원) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 토크나이저(`unicode61` 또는 `trigram`) |
|
||||
|
||||
---
|
||||
|
||||
## QMD 백엔드 구성
|
||||
|
||||
활성화하려면 `memory.backend = "qmd"`를 설정하세요. 모든 QMD 설정은
|
||||
활성화하려면 `memory.backend = "qmd"`로 설정합니다. 모든 QMD 설정은
|
||||
`memory.qmd` 아래에 있습니다.
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ------------------------ | --------- | -------- | ------------------------------------------------ |
|
||||
| `command` | `string` | `qmd` | QMD 실행 파일 경로 |
|
||||
| `searchMode` | `string` | `search` | 검색 명령: `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md` 자동 인덱싱 |
|
||||
| `paths[]` | `array` | -- | 추가 경로: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | 세션 transcript 인덱싱 |
|
||||
| `sessions.retentionDays` | `number` | -- | transcript 보관 기간 |
|
||||
| `sessions.exportDir` | `string` | -- | 내보내기 디렉터리 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ------------------------ | --------- | -------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | QMD 실행 파일 경로 |
|
||||
| `searchMode` | `string` | `search` | 검색 명령: `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | `MEMORY.md` + `memory/**/*.md` 자동 인덱싱 |
|
||||
| `paths[]` | `array` | -- | 추가 경로: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | 세션 트랜스크립트 인덱싱 |
|
||||
| `sessions.retentionDays` | `number` | -- | 트랜스크립트 보존 기간 |
|
||||
| `sessions.exportDir` | `string` | -- | 내보내기 디렉터리 |
|
||||
|
||||
OpenClaw는 현재 QMD 컬렉션 및 MCP 쿼리 형태를 우선 사용하지만,
|
||||
필요할 경우 레거시 `--mask` 컬렉션 플래그와
|
||||
이전 MCP 도구 이름으로 대체해 구버전 QMD도 계속 작동하도록 유지합니다.
|
||||
OpenClaw는 현재 QMD 컬렉션 및 MCP 쿼리 형태를 우선 사용하지만, 필요할 경우
|
||||
레거시 `--mask` 컬렉션 플래그와 이전 MCP 도구 이름으로 폴백하여
|
||||
오래된 QMD 릴리스도 계속 동작하도록 유지합니다.
|
||||
|
||||
QMD 모델 재정의는 OpenClaw 구성 쪽이 아니라 QMD 쪽에 유지됩니다.
|
||||
QMD 모델을 전역적으로 재정의해야 한다면 gateway
|
||||
런타임 환경에서 `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`,
|
||||
`QMD_GENERATE_MODEL` 같은 환경 변수를 설정하세요.
|
||||
QMD 모델 재정의는 OpenClaw 구성이 아니라 QMD 측에 유지됩니다. QMD의 모델을
|
||||
전역으로 재정의해야 한다면 게이트웨이 런타임 환경에서
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`, `QMD_GENERATE_MODEL` 같은
|
||||
환경 변수를 설정하세요.
|
||||
|
||||
### 업데이트 일정
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ------------------------- | --------- | ------- | ------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | 새로고침 간격 |
|
||||
| `update.interval` | `string` | `5m` | 새로 고침 간격 |
|
||||
| `update.debounceMs` | `number` | `15000` | 파일 변경 디바운스 |
|
||||
| `update.onBoot` | `boolean` | `true` | 시작 시 새로고침 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 새로고침 완료까지 시작 차단 |
|
||||
| `update.embedInterval` | `string` | -- | 별도 임베딩 주기 |
|
||||
| `update.onBoot` | `boolean` | `true` | 시작 시 새로 고침 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 새로 고침이 완료될 때까지 시작 차단 |
|
||||
| `update.embedInterval` | `string` | -- | 별도의 임베딩 주기 |
|
||||
| `update.commandTimeoutMs` | `number` | -- | QMD 명령 타임아웃 |
|
||||
| `update.updateTimeoutMs` | `number` | -- | QMD 업데이트 작업 타임아웃 |
|
||||
| `update.embedTimeoutMs` | `number` | -- | QMD 임베딩 작업 타임아웃 |
|
||||
|
||||
### 제한
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ------------------------- | -------- | ------ | ---------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | 최대 검색 결과 수 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | snippet 길이 제한 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 스니펫 길이 제한 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 총 주입 문자 수 제한 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 검색 타임아웃 |
|
||||
|
||||
### 범위
|
||||
|
||||
어떤 세션이 QMD 검색 결과를 받을 수 있는지 제어합니다. 스키마는
|
||||
[`session.sendPolicy`](/ko/gateway/configuration-reference#session)와 같습니다.
|
||||
QMD 검색 결과를 받을 수 있는 세션을 제어합니다.
|
||||
[`session.sendPolicy`](/ko/gateway/configuration-reference#session)와 동일한 스키마를 사용합니다.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -441,7 +450,7 @@ QMD 모델을 전역적으로 재정의해야 한다면 gateway
|
||||
|
||||
| 값 | 동작 |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `auto` (기본값) | snippet에 `Source: <path#line>` 바닥글 포함 |
|
||||
| `auto` (기본값) | 스니펫에 `Source: <path#line>` 바닥글 포함 |
|
||||
| `on` | 항상 바닥글 포함 |
|
||||
| `off` | 바닥글 생략(경로는 여전히 내부적으로 에이전트에 전달됨) |
|
||||
|
||||
@ -473,17 +482,17 @@ QMD 모델을 전역적으로 재정의해야 한다면 gateway
|
||||
Dreaming은 `agents.defaults.memorySearch` 아래가 아니라
|
||||
`plugins.entries.memory-core.config.dreaming` 아래에서 구성합니다.
|
||||
|
||||
Dreaming은 하나의 예약된 스윕으로 실행되며, 내부 light/deep/REM 단계는
|
||||
구현 세부 사항으로 사용됩니다.
|
||||
Dreaming은 예약된 하나의 스윕으로 실행되며 내부적인 light/deep/REM 단계를
|
||||
구현 세부 사항으로 사용합니다.
|
||||
|
||||
개념적 동작과 슬래시 명령은 [Dreaming](/concepts/dreaming)을 참고하세요.
|
||||
개념적 동작과 슬래시 명령은 [Dreaming](/ko/concepts/dreaming)을 참조하세요.
|
||||
|
||||
### 사용자 설정
|
||||
|
||||
| 키 | 타입 | 기본값 | 설명 |
|
||||
| ----------- | --------- | ----------- | ------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Dreaming 전체 활성화 또는 비활성화 |
|
||||
| `frequency` | `string` | `0 3 * * *` | 전체 dreaming 스윕에 대한 선택적 cron 주기 |
|
||||
| 키 | 유형 | 기본값 | 설명 |
|
||||
| ----------- | --------- | ----------- | ----------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Dreaming 전체를 활성화 또는 비활성화 |
|
||||
| `frequency` | `string` | `0 3 * * *` | 전체 Dreaming 스윕의 선택적 cron 주기 |
|
||||
|
||||
### 예시
|
||||
|
||||
@ -506,6 +515,6 @@ Dreaming은 하나의 예약된 스윕으로 실행되며, 내부 light/deep/REM
|
||||
|
||||
참고:
|
||||
|
||||
- Dreaming은 기계 상태를 `memory/.dreams/`에 기록합니다.
|
||||
- Dreaming은 사람이 읽을 수 있는 서사 출력을 `DREAMS.md`(또는 기존 `dreams.md`)에 기록합니다.
|
||||
- light/deep/REM 단계 정책과 임계값은 내부 동작이며 사용자 대상 config가 아닙니다.
|
||||
- Dreaming은 머신 상태를 `memory/.dreams/`에 기록합니다.
|
||||
- Dreaming은 사람이 읽을 수 있는 내러티브 출력을 `DREAMS.md`(또는 기존 `dreams.md`)에 기록합니다.
|
||||
- light/deep/REM 단계 정책과 임계값은 사용자 대상 구성이 아니라 내부 동작입니다.
|
||||
|
||||
@ -1,41 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- 에이전트가 제어하는 브라우저 자동화를 추가하는 경우
|
||||
- openclaw가 내 Chrome에 왜 간섭하는지 디버깅하는 경우
|
||||
- macOS 앱에서 브라우저 설정 + 수명 주기를 구현하는 경우
|
||||
- 에이전트 제어 브라우저 자동화 추가
|
||||
- openclaw가 사용자의 Chrome에 간섭하는 이유 디버깅하기
|
||||
- macOS 앱에서 브라우저 설정 및 수명 주기 구현하기
|
||||
summary: 통합 브라우저 제어 서비스 + 작업 명령
|
||||
title: 브라우저(OpenClaw 관리형)
|
||||
title: 브라우저(OpenClaw 관리)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:58:18Z"
|
||||
generated_at: "2026-04-10T05:59:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a
|
||||
source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 브라우저(openclaw 관리형)
|
||||
# 브라우저(openclaw 관리)
|
||||
|
||||
OpenClaw는 에이전트가 제어하는 **전용 Chrome/Brave/Edge/Chromium 프로필**을 실행할 수 있습니다.
|
||||
이 프로필은 개인 브라우저와 분리되어 있으며 Gateway 내부의 작은 로컬
|
||||
제어 서비스(루프백 전용)를 통해 관리됩니다.
|
||||
|
||||
초보자 관점에서 보면:
|
||||
초보자용 설명:
|
||||
|
||||
- 이를 **에이전트 전용 별도 브라우저**라고 생각하면 됩니다.
|
||||
- `openclaw` 프로필은 **개인 브라우저 프로필을 건드리지 않습니다**.
|
||||
- 에이전트는 안전한 범위 안에서 **탭 열기, 페이지 읽기, 클릭, 입력**을 할 수 있습니다.
|
||||
- 내장 `user` 프로필은 Chrome MCP를 통해 실제 로그인된 Chrome 세션에 연결합니다.
|
||||
- 이것은 **별도의 에이전트 전용 브라우저**라고 생각하면 됩니다.
|
||||
- `openclaw` 프로필은 사용자의 개인 브라우저 프로필에 **영향을 주지 않습니다**.
|
||||
- 에이전트는 안전하게 분리된 환경에서 **탭을 열고, 페이지를 읽고, 클릭하고, 입력할 수 있습니다**.
|
||||
- 내장된 `user` 프로필은 Chrome MCP를 통해 사용자가 실제로 로그인한 Chrome 세션에 연결됩니다.
|
||||
|
||||
## 제공 기능
|
||||
|
||||
- **openclaw**라는 이름의 별도 브라우저 프로필(기본적으로 주황색 강조).
|
||||
- **openclaw**라는 이름의 별도 브라우저 프로필(기본값은 주황색 강조).
|
||||
- 결정적인 탭 제어(목록/열기/포커스/닫기).
|
||||
- 에이전트 작업(클릭/입력/드래그/선택), 스냅샷, 스크린샷, PDF.
|
||||
- 선택적 멀티 프로필 지원(`openclaw`, `work`, `remote`, ...).
|
||||
- 선택적 다중 프로필 지원(`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
이 브라우저는 일상적으로 사용하는 메인 브라우저가 **아닙니다**. 에이전트
|
||||
자동화와 검증을 위한 안전하고 분리된 표면입니다.
|
||||
이 브라우저는 **일상적으로 사용하는 기본 브라우저가 아닙니다**. 에이전트 자동화와 검증을 위한 안전하고 격리된 표면입니다.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
@ -46,16 +45,14 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
“Browser disabled”가 나오면 config에서 활성화하고(아래 참조) Gateway를
|
||||
재시작하세요.
|
||||
“Browser disabled”가 표시되면 config에서 이를 활성화하고(아래 참조) Gateway를 다시 시작하세요.
|
||||
|
||||
`openclaw browser` 명령 자체가 없거나, 에이전트가 브라우저 도구를 사용할 수 없다고 하면
|
||||
[브라우저 명령 또는 도구 누락](/tools/browser#missing-browser-command-or-tool)으로 이동하세요.
|
||||
`openclaw browser` 자체가 완전히 없거나, 에이전트가 브라우저 도구를 사용할 수 없다고 말하면 [브라우저 명령 또는 도구 누락](/ko/tools/browser#missing-browser-command-or-tool)으로 이동하세요.
|
||||
|
||||
## plugin 제어
|
||||
## 플러그인 제어
|
||||
|
||||
기본 `browser` 도구는 이제 기본적으로 활성화된 상태로 제공되는 번들 plugin입니다.
|
||||
즉, OpenClaw의 나머지 plugin 시스템을 제거하지 않고도 이를 비활성화하거나 교체할 수 있습니다:
|
||||
기본 `browser` 도구는 이제 기본적으로 활성화된 상태로 함께 제공되는 번들 플러그인입니다.
|
||||
즉, 나머지 OpenClaw 플러그인 시스템을 제거하지 않고도 이 도구를 비활성화하거나 교체할 수 있습니다:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -69,31 +66,23 @@ openclaw browser --browser-profile openclaw snapshot
|
||||
}
|
||||
```
|
||||
|
||||
동일한 `browser` 도구 이름을 제공하는 다른 plugin을 설치하기 전에 이 번들 plugin을 비활성화하세요. 기본 브라우저 경험에는 다음 두 가지가 모두 필요합니다:
|
||||
동일한 `browser` 도구 이름을 제공하는 다른 플러그인을 설치하기 전에 번들 플러그인을 비활성화하세요. 기본 브라우저 경험에는 다음 두 가지가 모두 필요합니다:
|
||||
|
||||
- `plugins.entries.browser.enabled`가 비활성화되어 있지 않을 것
|
||||
- `browser.enabled=true`
|
||||
|
||||
plugin만 끄면 번들 브라우저 CLI(`openclaw browser`),
|
||||
gateway 메서드(`browser.request`), 에이전트 도구, 기본 브라우저 제어
|
||||
서비스가 모두 함께 사라집니다. `browser.*` config는 그대로 유지되므로
|
||||
대체 plugin이 이를 재사용할 수 있습니다.
|
||||
플러그인만 끄면 번들 브라우저 CLI(`openclaw browser`), gateway 메서드(`browser.request`), 에이전트 도구, 기본 브라우저 제어 서비스가 모두 함께 사라집니다. `browser.*` config는 그대로 유지되므로 교체 플러그인이 이를 재사용할 수 있습니다.
|
||||
|
||||
번들 브라우저 plugin은 이제 브라우저 런타임 구현도 소유합니다.
|
||||
코어에는 공유 Plugin SDK 헬퍼와 이전 내부 import 경로용 호환 re-export만 남아 있습니다.
|
||||
실제로는 브라우저 plugin 패키지를 제거하거나 교체하면
|
||||
코어 소유의 두 번째 런타임이 남는 대신 브라우저 기능 세트 자체가 제거됩니다.
|
||||
번들 브라우저 플러그인은 이제 브라우저 런타임 구현도 담당합니다.
|
||||
코어에는 공유 Plugin SDK 도우미와 이전 내부 import 경로용 호환성 re-export만 남아 있습니다. 실제로는 브라우저 플러그인 패키지를 제거하거나 교체하면 코어 소유 런타임이 따로 남는 대신 브라우저 기능 세트가 제거됩니다.
|
||||
|
||||
브라우저 config 변경은 번들 plugin이 새 설정으로 브라우저 서비스를
|
||||
다시 등록할 수 있도록 여전히 Gateway 재시작이 필요합니다.
|
||||
브라우저 config 변경 사항을 새 설정으로 번들 플러그인이 브라우저 서비스를 다시 등록할 수 있도록 하려면 여전히 Gateway 재시작이 필요합니다.
|
||||
|
||||
## 브라우저 명령 또는 도구 누락
|
||||
|
||||
업그레이드 후 `openclaw browser`가 갑자기 알 수 없는 명령이 되거나,
|
||||
에이전트가 브라우저 도구가 없다고 보고한다면 가장 흔한 원인은
|
||||
제한적인 `plugins.allow` 목록에 `browser`가 포함되어 있지 않은 경우입니다.
|
||||
업그레이드 후 `openclaw browser`가 갑자기 알 수 없는 명령이 되거나, 에이전트가 브라우저 도구가 없다고 보고하는 경우 가장 흔한 원인은 `browser`가 포함되지 않은 제한적인 `plugins.allow` 목록입니다.
|
||||
|
||||
잘못된 config 예시:
|
||||
문제가 있는 config 예시:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -103,7 +92,7 @@ gateway 메서드(`browser.request`), 에이전트 도구, 기본 브라우저
|
||||
}
|
||||
```
|
||||
|
||||
plugin allowlist에 `browser`를 추가해 해결하세요:
|
||||
플러그인 허용 목록에 `browser`를 추가해서 해결할 수 있습니다:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -115,28 +104,27 @@ plugin allowlist에 `browser`를 추가해 해결하세요:
|
||||
|
||||
중요한 참고 사항:
|
||||
|
||||
- `plugins.allow`가 설정된 경우 `browser.enabled=true`만으로는 충분하지 않습니다.
|
||||
- `plugins.allow`가 설정된 경우 `plugins.entries.browser.enabled=true`만으로도 충분하지 않습니다.
|
||||
- `tools.alsoAllow: ["browser"]`는 번들 브라우저 plugin을 로드하지 않습니다. plugin이 이미 로드된 후에만 도구 정책을 조정합니다.
|
||||
- 제한적인 plugin allowlist가 필요 없다면 `plugins.allow`를 제거하는 것만으로도 기본 번들 브라우저 동작이 복원됩니다.
|
||||
- `plugins.allow`가 설정되어 있으면 `browser.enabled=true`만으로는 충분하지 않습니다.
|
||||
- `plugins.allow`가 설정되어 있으면 `plugins.entries.browser.enabled=true`만으로도 충분하지 않습니다.
|
||||
- `tools.alsoAllow: ["browser"]`는 번들 브라우저 플러그인을 로드하지 **않습니다**. 이는 플러그인이 이미 로드된 뒤 도구 정책만 조정합니다.
|
||||
- 제한적인 플러그인 허용 목록이 필요하지 않다면 `plugins.allow`를 제거해도 기본 번들 브라우저 동작이 복원됩니다.
|
||||
|
||||
일반적인 증상:
|
||||
|
||||
- `openclaw browser`가 알 수 없는 명령입니다.
|
||||
- `browser.request`가 없습니다.
|
||||
- 에이전트가 브라우저 도구를 사용할 수 없거나 없다고 보고합니다.
|
||||
- 에이전트가 브라우저 도구를 사용할 수 없거나 누락되었다고 보고합니다.
|
||||
|
||||
## 프로필: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: 관리형, 격리된 브라우저(확장 프로그램 필요 없음).
|
||||
- `user`: 실제 **로그인된 Chrome**
|
||||
세션에 연결되는 내장 Chrome MCP attach 프로필.
|
||||
- `user`: 사용자의 **실제 로그인된 Chrome** 세션에 연결하는 내장 Chrome MCP 연결 프로필.
|
||||
|
||||
에이전트 브라우저 도구 호출 시:
|
||||
에이전트 브라우저 도구 호출의 경우:
|
||||
|
||||
- 기본값: 격리된 `openclaw` 브라우저를 사용합니다.
|
||||
- 기존 로그인 세션이 중요하고 사용자가 컴퓨터 앞에서 attach 프롬프트를 클릭/승인할 수 있다면 `profile="user"`를 선호하세요.
|
||||
- 특정 브라우저 모드가 필요할 때는 `profile`이 명시적 재정의입니다.
|
||||
- 기본값: 격리된 `openclaw` 브라우저 사용.
|
||||
- 기존 로그인 세션이 중요하고 사용자가 컴퓨터 앞에서 연결 프롬프트를 클릭/승인할 수 있을 때는 `profile="user"`를 우선 사용.
|
||||
- `profile`은 특정 브라우저 모드를 원할 때 사용하는 명시적 재정의입니다.
|
||||
|
||||
기본적으로 관리형 모드를 사용하려면 `browser.defaultProfile: "openclaw"`를 설정하세요.
|
||||
|
||||
@ -183,32 +171,33 @@ plugin allowlist에 `browser`를 추가해 해결하세요:
|
||||
}
|
||||
```
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- 브라우저 제어 서비스는 `gateway.port`에서 파생된 포트의 루프백에 바인딩됩니다
|
||||
(기본값: `18791`, 즉 gateway + 2).
|
||||
- Gateway 포트(`gateway.port` 또는 `OPENCLAW_GATEWAY_PORT`)를 재정의하면
|
||||
파생 브라우저 포트도 같은 “패밀리” 안에 있도록 함께 이동합니다.
|
||||
- `cdpUrl`이 설정되지 않으면 기본적으로 관리형 로컬 CDP 포트를 사용합니다.
|
||||
파생된 브라우저 포트도 같은 “패밀리”를 유지하도록 함께 이동합니다.
|
||||
- `cdpUrl`이 설정되지 않은 경우 관리형 로컬 CDP 포트가 기본값으로 사용됩니다.
|
||||
- `remoteCdpTimeoutMs`는 원격(비루프백) CDP 도달 가능성 검사에 적용됩니다.
|
||||
- `remoteCdpHandshakeTimeoutMs`는 원격 CDP WebSocket 도달 가능성 검사에 적용됩니다.
|
||||
- 브라우저 탐색/탭 열기는 탐색 전에 SSRF 보호가 적용되며, 탐색 후 최종 `http(s)` URL에 대해서도 최선의 노력으로 다시 검사합니다.
|
||||
- 엄격한 SSRF 모드에서는 원격 CDP 엔드포인트 탐색/프로브(`cdpUrl`, `/json/version` 조회 포함)도 검사됩니다.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`의 기본값은 `true`(신뢰 네트워크 모델)입니다. 엄격한 공용 전용 브라우징이 필요하면 `false`로 설정하세요.
|
||||
- 브라우저 탐색/탭 열기는 탐색 전에 SSRF 보호가 적용되며, 탐색 후 최종 `http(s)` URL에 대해 가능하면 다시 확인합니다.
|
||||
- 엄격한 SSRF 모드에서는 원격 CDP 엔드포인트 검색/프로브(`cdpUrl`, `/json/version` 조회 포함)도 검사됩니다.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`의 기본값은 `true`입니다(신뢰 네트워크 모델). 엄격한 공개 네트워크 전용 탐색을 원하면 `false`로 설정하세요.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork`는 호환성을 위한 레거시 별칭으로 계속 지원됩니다.
|
||||
- `attachOnly: true`는 “로컬 브라우저를 절대 실행하지 않고, 이미 실행 중일 때만 연결한다”는 의미입니다.
|
||||
- `color` 및 프로필별 `color`는 브라우저 UI에 색을 입혀 어느 프로필이 활성 상태인지 볼 수 있게 합니다.
|
||||
- 기본 프로필은 `openclaw`입니다(OpenClaw 관리형 독립 브라우저). 로그인된 사용자 브라우저를 사용하려면 `defaultProfile: "user"`를 사용하세요.
|
||||
- 자동 감지 순서: 시스템 기본 브라우저가 Chromium 기반이면 그것을 사용하고, 아니면 Chrome → Brave → Edge → Chromium → Chrome Canary 순입니다.
|
||||
- 로컬 `openclaw` 프로필은 `cdpPort`/`cdpUrl`이 자동 할당되므로, 원격 CDP가 아닌 경우에는 이를 설정하지 마세요.
|
||||
- `driver: "existing-session"`은 raw CDP 대신 Chrome DevTools MCP를 사용합니다. 이 드라이버에는 `cdpUrl`을 설정하지 마세요.
|
||||
- 기존 세션 프로필이 Brave 또는 Edge 같은 비기본 Chromium 사용자 프로필에 연결되어야 한다면 `browser.profiles.<name>.userDataDir`을 설정하세요.
|
||||
- `attachOnly: true`는 “로컬 브라우저를 절대 실행하지 않고, 이미 실행 중일 때만 연결한다”는 뜻입니다.
|
||||
- `color` 및 프로필별 `color`는 브라우저 UI에 색을 입혀 어떤 프로필이 활성화되어 있는지 확인할 수 있게 합니다.
|
||||
- 기본 프로필은 `openclaw`입니다(OpenClaw 관리 독립형 브라우저). 로그인된 사용자 브라우저를 사용하려면 `defaultProfile: "user"`를 사용하세요.
|
||||
- 자동 감지 순서: 시스템 기본 브라우저가 Chromium 기반이면 그것을 사용하고, 그렇지 않으면 Chrome → Brave → Edge → Chromium → Chrome Canary 순입니다.
|
||||
- 로컬 `openclaw` 프로필은 `cdpPort`/`cdpUrl`을 자동 할당합니다 — 원격 CDP에만 이를 설정하세요.
|
||||
- `driver: "existing-session"`은 raw CDP 대신 Chrome DevTools MCP를 사용합니다. 이
|
||||
드라이버에는 `cdpUrl`을 설정하지 마세요.
|
||||
- 기존 세션 프로필이 Brave 또는 Edge 같은 기본값이 아닌 Chromium 사용자 프로필에
|
||||
연결해야 한다면 `browser.profiles.<name>.userDataDir`를 설정하세요.
|
||||
|
||||
## Brave(또는 다른 Chromium 기반 브라우저) 사용
|
||||
|
||||
**시스템 기본** 브라우저가 Chromium 기반(Chrome/Brave/Edge 등)이면
|
||||
OpenClaw가 자동으로 이를 사용합니다. 자동 감지를 재정의하려면
|
||||
`browser.executablePath`를 설정하세요:
|
||||
사용자의 **시스템 기본** 브라우저가 Chromium 기반(Chrome/Brave/Edge 등)이면
|
||||
OpenClaw가 자동으로 이를 사용합니다. 자동 감지를 재정의하려면 `browser.executablePath`를 설정하세요:
|
||||
|
||||
CLI 예시:
|
||||
|
||||
@ -242,47 +231,45 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
## 로컬 제어 vs 원격 제어
|
||||
|
||||
- **로컬 제어(기본값):** Gateway가 루프백 제어 서비스를 시작하고 로컬 브라우저를 실행할 수 있습니다.
|
||||
- **원격 제어(node host):** 브라우저가 있는 머신에서 node host를 실행하면 Gateway가 브라우저 작업을 그 노드로 프록시합니다.
|
||||
- **원격 제어(node host):** 브라우저가 있는 머신에서 node host를 실행하면 Gateway가 브라우저 작업을 해당 호스트로 프록시합니다.
|
||||
- **원격 CDP:** 원격 Chromium 기반 브라우저에 연결하려면 `browser.profiles.<name>.cdpUrl`(또는 `browser.cdpUrl`)을 설정하세요. 이 경우 OpenClaw는 로컬 브라우저를 실행하지 않습니다.
|
||||
|
||||
중지 동작은 프로필 모드에 따라 다릅니다:
|
||||
|
||||
- 로컬 관리형 프로필: `openclaw browser stop`은
|
||||
OpenClaw가 시작한 브라우저 프로세스를 중지합니다
|
||||
- attach-only 및 원격 CDP 프로필: `openclaw browser stop`은
|
||||
OpenClaw가 브라우저 프로세스를 시작하지 않았더라도 활성 제어 세션을 닫고
|
||||
Playwright/CDP 에뮬레이션 재정의(뷰포트, 색 구성표, 로캘, 시간대, 오프라인 모드 등)를 해제합니다
|
||||
- 로컬 관리형 프로필: `openclaw browser stop`은 OpenClaw가 실행한 브라우저 프로세스를 중지합니다
|
||||
- attach-only 및 원격 CDP 프로필: `openclaw browser stop`은 활성 제어 세션을 닫고 Playwright/CDP 에뮬레이션 재정의(뷰포트,
|
||||
색 구성표, 로캘, 시간대, 오프라인 모드 및 유사한 상태)를 해제하지만,
|
||||
OpenClaw가 브라우저 프로세스를 실행한 것은 아닙니다
|
||||
|
||||
원격 CDP URL에는 인증 정보를 포함할 수 있습니다:
|
||||
|
||||
- 쿼리 토큰(예: `https://provider.example?token=<token>`)
|
||||
- HTTP Basic auth(예: `https://user:pass@provider.example`)
|
||||
- HTTP Basic 인증(예: `https://user:pass@provider.example`)
|
||||
|
||||
OpenClaw는 `/json/*` 엔드포인트 호출 시와
|
||||
CDP WebSocket 연결 시 인증 정보를 유지합니다. 토큰은 config 파일에 커밋하는 대신
|
||||
환경 변수 또는 시크릿 매니저를 사용하는 것이 좋습니다.
|
||||
OpenClaw는 `/json/*` 엔드포인트 호출 시와 CDP WebSocket 연결 시
|
||||
인증 정보를 유지합니다. 토큰은 config 파일에 커밋하는 대신 환경 변수나 시크릿 관리자 사용을 권장합니다.
|
||||
|
||||
## Node 브라우저 프록시(기본 제로 구성)
|
||||
## 노드 브라우저 프록시(기본 무설정)
|
||||
|
||||
브라우저가 있는 머신에서 **node host**를 실행 중이라면, OpenClaw는
|
||||
추가 브라우저 config 없이도 브라우저 도구 호출을 해당 노드로
|
||||
자동 라우팅할 수 있습니다. 이는 원격 게이트웨이의 기본 경로입니다.
|
||||
브라우저가 있는 머신에서 **node host**를 실행하면 OpenClaw는
|
||||
추가 브라우저 config 없이도 브라우저 도구 호출을 해당 노드로 자동 라우팅할 수 있습니다.
|
||||
이것이 원격 gateway의 기본 경로입니다.
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- node host는 로컬 브라우저 제어 서버를 **프록시 명령**으로 노출합니다.
|
||||
- node host는 **프록시 명령**을 통해 자신의 로컬 브라우저 제어 서버를 노출합니다.
|
||||
- 프로필은 노드 자체의 `browser.profiles` config(로컬과 동일)에서 가져옵니다.
|
||||
- `nodeHost.browserProxy.allowProfiles`는 선택 사항입니다. 비워 두면 레거시/기본 동작이 적용되어, 프로필 생성/삭제 라우트를 포함해 구성된 모든 프로필이 프록시를 통해 접근 가능합니다.
|
||||
- `nodeHost.browserProxy.allowProfiles`를 설정하면, OpenClaw는 이를 최소 권한 경계로 취급합니다. allowlist에 있는 프로필만 대상으로 지정할 수 있으며, 영구 프로필 생성/삭제 라우트는 프록시 표면에서 차단됩니다.
|
||||
- `nodeHost.browserProxy.allowProfiles`는 선택 사항입니다. 비워 두면 레거시/기본 동작이 적용되어, 프로필 생성/삭제 경로를 포함해 구성된 모든 프로필에 프록시를 통해 접근할 수 있습니다.
|
||||
- `nodeHost.browserProxy.allowProfiles`를 설정하면 OpenClaw는 이를 최소 권한 경계로 취급합니다. 허용 목록에 있는 프로필만 대상으로 지정할 수 있고, 영구 프로필 생성/삭제 경로는 프록시 표면에서 차단됩니다.
|
||||
- 원하지 않으면 비활성화하세요:
|
||||
- 노드에서: `nodeHost.browserProxy.enabled=false`
|
||||
- 게이트웨이에서: `gateway.nodes.browser.mode="off"`
|
||||
- gateway에서: `gateway.nodes.browser.mode="off"`
|
||||
|
||||
## Browserless(호스팅 원격 CDP)
|
||||
## Browserless(호스팅된 원격 CDP)
|
||||
|
||||
[Browserless](https://browserless.io)는 HTTPS와 WebSocket을 통해
|
||||
CDP 연결 URL을 노출하는 호스팅 Chromium 서비스입니다. OpenClaw는 두 형식을 모두 사용할 수 있지만,
|
||||
원격 브라우저 프로필에는 Browserless 연결 문서에 있는 직접 WebSocket URL을 사용하는 것이 가장 간단합니다.
|
||||
원격 브라우저 프로필에서는 Browserless의 연결 문서에 있는 직접 WebSocket URL이 가장 간단한 옵션입니다.
|
||||
|
||||
예시:
|
||||
|
||||
@ -303,29 +290,31 @@ CDP 연결 URL을 노출하는 호스팅 Chromium 서비스입니다. OpenClaw
|
||||
}
|
||||
```
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- `<BROWSERLESS_API_KEY>`를 실제 Browserless 토큰으로 바꾸세요.
|
||||
- Browserless 계정에 맞는 리전 엔드포인트를 선택하세요(자세한 내용은 해당 문서 참조).
|
||||
- Browserless가 HTTPS 기본 URL을 제공하는 경우, 직접 CDP 연결을 위해 이를 `wss://`로 변환하거나 HTTPS URL을 그대로 두고 OpenClaw가 `/json/version`을 탐색하도록 할 수 있습니다.
|
||||
- Browserless가 HTTPS 기본 URL을 제공하는 경우 이를 직접 CDP 연결용 `wss://`로
|
||||
변환해도 되고, HTTPS URL을 그대로 유지한 채 OpenClaw가
|
||||
`/json/version`을 검색하도록 해도 됩니다.
|
||||
|
||||
## 직접 WebSocket CDP provider
|
||||
## 직접 WebSocket CDP 제공자
|
||||
|
||||
일부 호스팅 브라우저 서비스는 표준 HTTP 기반 CDP 탐색(`/json/version`)이 아니라
|
||||
**직접 WebSocket** 엔드포인트를 제공합니다. OpenClaw는 둘 다 지원합니다:
|
||||
일부 호스팅 브라우저 서비스는 표준 HTTP 기반 CDP 검색(`/json/version`) 대신
|
||||
**직접 WebSocket** 엔드포인트를 제공합니다. OpenClaw는 두 방식 모두 지원합니다:
|
||||
|
||||
- **HTTP(S) 엔드포인트** — OpenClaw가 `/json/version`을 호출해
|
||||
WebSocket 디버거 URL을 탐색한 후 연결합니다.
|
||||
- **WebSocket 엔드포인트** (`ws://` / `wss://`) — OpenClaw가 직접 연결하며
|
||||
`/json/version`은 건너뜁니다. 이는
|
||||
- **HTTP(S) 엔드포인트** — OpenClaw는 `/json/version`을 호출해
|
||||
WebSocket 디버거 URL을 찾은 다음 연결합니다.
|
||||
- **WebSocket 엔드포인트** (`ws://` / `wss://`) — OpenClaw는 `/json/version`을 건너뛰고
|
||||
직접 연결합니다. 이는
|
||||
[Browserless](https://browserless.io),
|
||||
[Browserbase](https://www.browserbase.com) 또는 WebSocket URL을 직접 제공하는
|
||||
모든 provider에 사용하세요.
|
||||
[Browserbase](https://www.browserbase.com) 또는 WebSocket URL을 제공하는
|
||||
모든 서비스에 사용합니다.
|
||||
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com)는 내장 CAPTCHA 해결, stealth 모드,
|
||||
residential proxy를 제공하는 헤드리스 브라우저 실행용 클라우드 플랫폼입니다.
|
||||
[Browserbase](https://www.browserbase.com)는 내장 CAPTCHA 해결, 스텔스 모드, 주거용
|
||||
프록시를 갖춘 헤드리스 브라우저 실행용 클라우드 플랫폼입니다.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -344,61 +333,62 @@ residential proxy를 제공하는 헤드리스 브라우저 실행용 클라우
|
||||
}
|
||||
```
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- [회원 가입](https://www.browserbase.com/sign-up) 후 [Overview dashboard](https://www.browserbase.com/overview)에서 **API Key**를 복사하세요.
|
||||
- [가입](https://www.browserbase.com/sign-up)한 뒤 [Overview dashboard](https://www.browserbase.com/overview)에서
|
||||
**API Key**를 복사하세요.
|
||||
- `<BROWSERBASE_API_KEY>`를 실제 Browserbase API 키로 바꾸세요.
|
||||
- Browserbase는 WebSocket 연결 시 브라우저 세션을 자동 생성하므로
|
||||
수동 세션 생성 단계가 필요하지 않습니다.
|
||||
- 무료 등급은 동시 세션 1개와 월 1 브라우저 시간을 허용합니다.
|
||||
유료 요금제 한도는 [pricing](https://www.browserbase.com/pricing)을 참조하세요.
|
||||
수동 세션 생성 단계가 필요 없습니다.
|
||||
- 무료 플랜은 동시 세션 1개와 월 1 브라우저 시간을 제공합니다.
|
||||
유료 플랜 제한은 [pricing](https://www.browserbase.com/pricing)을 참조하세요.
|
||||
- 전체 API 참조, SDK 가이드, 통합 예시는 [Browserbase docs](https://docs.browserbase.com)를 참조하세요.
|
||||
|
||||
## 보안
|
||||
|
||||
핵심 개념:
|
||||
|
||||
- 브라우저 제어는 루프백 전용이며, 액세스는 Gateway 인증 또는 node pairing을 통해 흐릅니다.
|
||||
- 독립형 루프백 브라우저 HTTP API는 **공유 비밀 인증만** 사용합니다:
|
||||
gateway 토큰 bearer auth, `x-openclaw-password`, 또는
|
||||
구성된 gateway 비밀번호를 사용한 HTTP Basic auth.
|
||||
- Tailscale Serve identity 헤더와 `gateway.auth.mode: "trusted-proxy"`는
|
||||
이 독립형 루프백 브라우저 API를 인증하지 않습니다.
|
||||
- 브라우저 제어가 활성화되어 있고 공유 비밀 인증이 구성되지 않은 경우, OpenClaw는
|
||||
시작 시 `gateway.auth.token`을 자동 생성하고 config에 저장합니다.
|
||||
- 브라우저 제어는 루프백 전용이며, 액세스는 Gateway 인증 또는 노드 페어링을 통해 이루어집니다.
|
||||
- 독립형 루프백 브라우저 HTTP API는 **공유 시크릿 인증만** 사용합니다:
|
||||
gateway 토큰 bearer 인증, `x-openclaw-password`, 또는
|
||||
설정된 gateway 비밀번호를 사용하는 HTTP Basic 인증입니다.
|
||||
- Tailscale Serve ID 헤더와 `gateway.auth.mode: "trusted-proxy"`는
|
||||
이 독립형 루프백 브라우저 API를 **인증하지 않습니다**.
|
||||
- 브라우저 제어가 활성화되어 있고 공유 시크릿 인증이 구성되지 않은 경우 OpenClaw는
|
||||
시작 시 `gateway.auth.token`을 자동 생성하고 이를 config에 저장합니다.
|
||||
- `gateway.auth.mode`가 이미
|
||||
`password`, `none`, 또는 `trusted-proxy`인 경우에는 해당 토큰을 자동 생성하지 않습니다.
|
||||
- Gateway와 모든 node host는 비공개 네트워크(Tailscale)에 유지하고, 공용 노출은 피하세요.
|
||||
- 원격 CDP URL/토큰은 시크릿으로 취급하고, env var 또는 시크릿 매니저를 선호하세요.
|
||||
`password`, `none`, 또는 `trusted-proxy`인 경우 OpenClaw는 해당 토큰을 자동 생성하지 않습니다.
|
||||
- Gateway와 모든 node host는 비공개 네트워크(Tailscale)에 두고 공개적으로 노출하지 마세요.
|
||||
- 원격 CDP URL/토큰은 시크릿으로 취급하고 환경 변수나 시크릿 관리자를 사용하는 것이 좋습니다.
|
||||
|
||||
원격 CDP 팁:
|
||||
|
||||
- 가능하면 암호화된 엔드포인트(HTTPS 또는 WSS)와 짧은 수명의 토큰을 선호하세요.
|
||||
- 오래 유지되는 토큰을 config 파일에 직접 포함하지 마세요.
|
||||
- 가능하면 암호화된 엔드포인트(HTTPS 또는 WSS)와 짧은 수명의 토큰을 사용하세요.
|
||||
- 장기 토큰을 config 파일에 직접 포함하지 마세요.
|
||||
|
||||
## 프로필(멀티 브라우저)
|
||||
|
||||
OpenClaw는 여러 개의 이름 있는 프로필(라우팅 config)을 지원합니다. 프로필 유형:
|
||||
OpenClaw는 여러 개의 이름 있는 프로필(라우팅 config)을 지원합니다. 프로필은 다음과 같을 수 있습니다:
|
||||
|
||||
- **openclaw-managed**: 자체 사용자 데이터 디렉터리와 CDP 포트를 가진 전용 Chromium 기반 브라우저 인스턴스
|
||||
- **remote**: 명시적 CDP URL(다른 곳에서 실행 중인 Chromium 기반 브라우저)
|
||||
- **existing session**: Chrome DevTools MCP 자동 연결을 통한 기존 Chrome 프로필
|
||||
- **openclaw 관리형**: 자체 사용자 데이터 디렉터리와 CDP 포트를 가진 전용 Chromium 기반 브라우저 인스턴스
|
||||
- **원격**: 명시적인 CDP URL(다른 위치에서 실행 중인 Chromium 기반 브라우저)
|
||||
- **기존 세션**: Chrome DevTools MCP 자동 연결을 통한 기존 Chrome 프로필
|
||||
|
||||
기본값:
|
||||
|
||||
- `openclaw` 프로필은 없으면 자동 생성됩니다.
|
||||
- `user` 프로필은 Chrome MCP existing-session attach용 내장 프로필입니다.
|
||||
- existing-session 프로필은 `user` 외에는 opt-in이며, `--driver existing-session`으로 생성하세요.
|
||||
- `user` 프로필은 Chrome MCP 기존 세션 연결용으로 내장되어 있습니다.
|
||||
- 기존 세션 프로필은 `user` 외에는 opt-in입니다. `--driver existing-session`으로 생성하세요.
|
||||
- 로컬 CDP 포트는 기본적으로 **18800–18899** 범위에서 할당됩니다.
|
||||
- 프로필을 삭제하면 해당 로컬 데이터 디렉터리는 휴지통으로 이동합니다.
|
||||
|
||||
모든 제어 엔드포인트는 `?profile=<name>`을 허용하며, CLI는 `--browser-profile`을 사용합니다.
|
||||
모든 제어 엔드포인트는 `?profile=<name>`을 받으며, CLI는 `--browser-profile`을 사용합니다.
|
||||
|
||||
## Chrome DevTools MCP를 통한 existing-session
|
||||
## Chrome DevTools MCP를 통한 기존 세션
|
||||
|
||||
OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium 기반 브라우저 프로필에 연결할 수도 있습니다. 이를 통해 해당 브라우저 프로필에 이미 열려 있는 탭과 로그인 상태를 재사용할 수 있습니다.
|
||||
OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium 기반 브라우저 프로필에 연결할 수도 있습니다. 이렇게 하면 해당 브라우저 프로필에서 이미 열려 있는 탭과 로그인 상태를 재사용합니다.
|
||||
|
||||
공식 배경 자료 및 설정 참고 링크:
|
||||
공식 배경 및 설정 참고 자료:
|
||||
|
||||
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
@ -407,15 +397,15 @@ OpenClaw는 공식 Chrome DevTools MCP 서버를 통해 실행 중인 Chromium
|
||||
|
||||
- `user`
|
||||
|
||||
선택 사항: 다른 이름, 색상 또는 브라우저 데이터 디렉터리가 필요하면
|
||||
직접 custom existing-session 프로필을 만들 수 있습니다.
|
||||
선택 사항: 다른 이름, 색상 또는 브라우저 데이터 디렉터리를 원하면
|
||||
자체 사용자 지정 기존 세션 프로필을 만들 수 있습니다.
|
||||
|
||||
기본 동작:
|
||||
|
||||
- 내장 `user` 프로필은 Chrome MCP 자동 연결을 사용하며,
|
||||
- 내장된 `user` 프로필은 Chrome MCP 자동 연결을 사용하며,
|
||||
기본 로컬 Google Chrome 프로필을 대상으로 합니다.
|
||||
|
||||
Brave, Edge, Chromium 또는 비기본 Chrome 프로필에는 `userDataDir`을 사용하세요:
|
||||
Brave, Edge, Chromium 또는 기본이 아닌 Chrome 프로필에는 `userDataDir`을 사용하세요:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -436,7 +426,7 @@ Brave, Edge, Chromium 또는 비기본 Chrome 프로필에는 `userDataDir`을
|
||||
|
||||
1. 원격 디버깅용 inspect 페이지를 엽니다.
|
||||
2. 원격 디버깅을 활성화합니다.
|
||||
3. 브라우저를 계속 실행한 채 OpenClaw가 연결할 때 나타나는 연결 승인 프롬프트를 수락합니다.
|
||||
3. 브라우저를 계속 실행한 상태로 두고 OpenClaw가 연결할 때 연결 프롬프트를 승인합니다.
|
||||
|
||||
일반적인 inspect 페이지:
|
||||
|
||||
@ -444,7 +434,7 @@ Brave, Edge, Chromium 또는 비기본 Chrome 프로필에는 `userDataDir`을
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
실시간 attach 스모크 테스트:
|
||||
라이브 연결 스모크 테스트:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -453,57 +443,63 @@ openclaw browser --browser-profile user tabs
|
||||
openclaw browser --browser-profile user snapshot --format ai
|
||||
```
|
||||
|
||||
성공 시 확인할 수 있는 내용:
|
||||
성공 시 확인할 수 있는 모습:
|
||||
|
||||
- `status`에 `driver: existing-session`이 표시됨
|
||||
- `status`에 `transport: chrome-mcp`가 표시됨
|
||||
- `status`에 `running: true`가 표시됨
|
||||
- `tabs`에 이미 열려 있는 브라우저 탭이 나열됨
|
||||
- `tabs`에 이미 열려 있는 브라우저 탭이 표시됨
|
||||
- `snapshot`이 선택된 라이브 탭의 ref를 반환함
|
||||
|
||||
attach가 작동하지 않을 때 확인할 사항:
|
||||
연결이 작동하지 않을 때 확인할 사항:
|
||||
|
||||
- 대상 Chromium 기반 브라우저 버전이 `144+`인지
|
||||
- 해당 브라우저 inspect 페이지에서 원격 디버깅이 활성화되어 있는지
|
||||
- 브라우저에 연결 승인 프롬프트가 표시되었고 이를 수락했는지
|
||||
- `openclaw doctor`는 이전 확장 기반 브라우저 config를 마이그레이션하고
|
||||
- 해당 브라우저의 inspect 페이지에서 원격 디버깅이 활성화되어 있는지
|
||||
- 브라우저에 연결 동의 프롬프트가 표시되었고 이를 수락했는지
|
||||
- `openclaw doctor`는 오래된 확장 기반 브라우저 config를 마이그레이션하고
|
||||
기본 자동 연결 프로필용으로 Chrome이 로컬에 설치되어 있는지 확인하지만,
|
||||
브라우저 측 원격 디버깅까지 대신 활성화해 주지는 않습니다
|
||||
브라우저 측 원격 디버깅을 대신 활성화해 주지는 않습니다
|
||||
|
||||
에이전트 사용:
|
||||
|
||||
- 사용자의 로그인된 브라우저 상태가 필요할 때는 `profile="user"`를 사용하세요.
|
||||
- custom existing-session 프로필을 사용한다면 명시적으로 해당 프로필 이름을 전달하세요.
|
||||
- 사용자가 컴퓨터 앞에 있어 attach 프롬프트를 승인할 수 있을 때만 이 모드를 선택하세요.
|
||||
- 사용자 로그인 브라우저 상태가 필요할 때는 `profile="user"`를 사용하세요.
|
||||
- 사용자 지정 기존 세션 프로필을 사용한다면 해당 명시적 프로필 이름을 전달하세요.
|
||||
- 사용자가 컴퓨터 앞에 있어 연결 프롬프트를 승인할 수 있을 때만 이 모드를 선택하세요.
|
||||
- Gateway 또는 node host는 `npx chrome-devtools-mcp@latest --autoConnect`를 실행할 수 있습니다
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- 이 경로는 로그인된 브라우저 세션 내부에서 동작할 수 있으므로 격리된 `openclaw` 프로필보다 위험도가 높습니다.
|
||||
- 이 드라이버에서는 OpenClaw가 브라우저를 실행하지 않으며, 기존 세션에만 연결합니다.
|
||||
- OpenClaw는 여기서 공식 Chrome DevTools MCP `--autoConnect` 흐름을 사용합니다. `userDataDir`이 설정되어 있으면 해당 명시적 Chromium 사용자 데이터 디렉터리를 대상으로 하도록 이를 전달합니다.
|
||||
- existing-session 스크린샷은 페이지 캡처와 스냅샷의 `--ref` 요소 캡처는 지원하지만 CSS `--element` 선택자는 지원하지 않습니다.
|
||||
- existing-session 페이지 스크린샷은 Chrome MCP를 통해 Playwright 없이도 작동합니다.
|
||||
ref 기반 요소 스크린샷(`--ref`)도 작동하지만, `--full-page`는 `--ref` 또는 `--element`와 함께 사용할 수 없습니다.
|
||||
- existing-session 작업은 관리형 브라우저 경로보다 여전히 더 제한적입니다:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag`, `select`는 CSS 선택자 대신 스냅샷 ref가 필요합니다
|
||||
- `click`은 왼쪽 버튼만 지원합니다(버튼 재정의나 modifier 없음)
|
||||
- `type`은 `slowly=true`를 지원하지 않으며, `fill` 또는 `press`를 사용해야 합니다
|
||||
- 이 경로는 로그인된 브라우저 세션 내부에서 동작할 수 있으므로 격리된 `openclaw` 프로필보다 위험이 더 큽니다.
|
||||
- OpenClaw는 이 드라이버에 대해 브라우저를 실행하지 않으며,
|
||||
기존 세션에만 연결합니다.
|
||||
- OpenClaw는 여기서 공식 Chrome DevTools MCP `--autoConnect` 흐름을 사용합니다. `userDataDir`이 설정된 경우 OpenClaw는 이를 전달하여
|
||||
해당 명시적 Chromium 사용자 데이터 디렉터리를 대상으로 지정합니다.
|
||||
- 기존 세션 스크린샷은 페이지 캡처와 스냅샷의 `--ref` 요소
|
||||
캡처는 지원하지만 CSS `--element` 선택자는 지원하지 않습니다.
|
||||
- 기존 세션 페이지 스크린샷은 Chrome MCP를 통해 Playwright 없이 작동합니다.
|
||||
ref 기반 요소 스크린샷(`--ref`)도 작동하지만 `--full-page`는
|
||||
`--ref` 또는 `--element`와 함께 사용할 수 없습니다.
|
||||
- 기존 세션 작업은 관리형 브라우저 경로보다 여전히 제한이 많습니다:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag`, `select`는
|
||||
CSS 선택자 대신 스냅샷 ref가 필요합니다
|
||||
- `click`은 왼쪽 버튼만 지원합니다(버튼 재정의 또는 modifier 없음)
|
||||
- `type`은 `slowly=true`를 지원하지 않으며 `fill` 또는 `press`를 사용해야 합니다
|
||||
- `press`는 `delayMs`를 지원하지 않습니다
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill`, `evaluate`는 호출별 타임아웃 재정의를 지원하지 않습니다
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill`, `evaluate`는
|
||||
호출별 타임아웃 재정의를 지원하지 않습니다
|
||||
- `select`는 현재 단일 값만 지원합니다
|
||||
- existing-session `wait --url`은 다른 브라우저 드라이버처럼 정확 일치, 부분 문자열, glob 패턴을 지원합니다. `wait --load networkidle`은 아직 지원하지 않습니다.
|
||||
- existing-session 업로드 훅은 `ref` 또는 `inputRef`가 필요하고, 한 번에 한 파일만 지원하며, CSS `element` 대상 지정은 지원하지 않습니다.
|
||||
- existing-session 대화상자 훅은 타임아웃 재정의를 지원하지 않습니다.
|
||||
- 일부 기능은 여전히 관리형 브라우저 경로가 필요합니다. 예를 들면 배치 작업, PDF 내보내기, 다운로드 가로채기, `responsebody` 등이 있습니다.
|
||||
- existing-session은 호스트 로컬 전용입니다. Chrome이 다른 머신이나
|
||||
다른 네트워크 네임스페이스에 있다면 remote CDP 또는 node host를 대신 사용하세요.
|
||||
- 기존 세션 `wait --url`은 다른 브라우저 드라이버와 마찬가지로 정확 일치, 부분 문자열, glob 패턴을 지원합니다. `wait --load networkidle`은 아직 지원되지 않습니다.
|
||||
- 기존 세션 업로드 훅은 `ref` 또는 `inputRef`가 필요하고 한 번에 하나의 파일만 지원하며 CSS `element` 대상 지정은 지원하지 않습니다.
|
||||
- 기존 세션 대화상자 훅은 타임아웃 재정의를 지원하지 않습니다.
|
||||
- 배치 작업, PDF 내보내기, 다운로드 가로채기, `responsebody`를 포함한 일부 기능은 여전히 관리형 브라우저 경로가 필요합니다.
|
||||
- 기존 세션은 호스트 로컬입니다. Chrome이 다른 머신이나
|
||||
다른 네트워크 네임스페이스에 있다면 대신 원격 CDP 또는 node host를 사용하세요.
|
||||
|
||||
## 격리 보장
|
||||
|
||||
- **전용 사용자 데이터 디렉터리**: 개인 브라우저 프로필을 절대 건드리지 않습니다.
|
||||
- **전용 포트**: 개발 워크플로와의 충돌을 피하기 위해 `9222`를 사용하지 않습니다.
|
||||
- **결정적인 탭 제어**: “마지막 탭”이 아니라 `targetId`로 탭을 대상으로 지정합니다.
|
||||
- **전용 사용자 데이터 디렉터리**: 사용자의 개인 브라우저 프로필에 절대 영향을 주지 않습니다.
|
||||
- **전용 포트**: 개발 워크플로와의 충돌을 방지하기 위해 `9222`를 피합니다.
|
||||
- **결정적인 탭 제어**: “마지막 탭”이 아니라 `targetId`로 탭을 지정합니다.
|
||||
|
||||
## 브라우저 선택
|
||||
|
||||
@ -515,9 +511,9 @@ attach가 작동하지 않을 때 확인할 사항:
|
||||
4. Chromium
|
||||
5. Chrome Canary
|
||||
|
||||
`browser.executablePath`로 이를 재정의할 수 있습니다.
|
||||
`browser.executablePath`로 재정의할 수 있습니다.
|
||||
|
||||
플랫폼별:
|
||||
플랫폼:
|
||||
|
||||
- macOS: `/Applications`와 `~/Applications`를 확인합니다.
|
||||
- Linux: `google-chrome`, `brave`, `microsoft-edge`, `chromium` 등을 찾습니다.
|
||||
@ -540,35 +536,56 @@ attach가 작동하지 않을 때 확인할 사항:
|
||||
- 상태: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear`
|
||||
- 설정: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device`
|
||||
|
||||
모든 엔드포인트는 `?profile=<name>`을 허용합니다.
|
||||
모든 엔드포인트는 `?profile=<name>`을 받습니다.
|
||||
|
||||
공유 비밀 gateway 인증이 구성되어 있다면 브라우저 HTTP 라우트도 인증이 필요합니다:
|
||||
공유 시크릿 gateway 인증이 구성되어 있으면 브라우저 HTTP 경로에도 인증이 필요합니다:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` 또는 해당 비밀번호를 사용하는 HTTP Basic auth
|
||||
- `x-openclaw-password: <gateway password>` 또는 해당 비밀번호를 사용하는 HTTP Basic 인증
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- 이 독립형 루프백 브라우저 API는 `trusted-proxy` 또는
|
||||
Tailscale Serve identity 헤더를 사용하지 않습니다.
|
||||
- `gateway.auth.mode`가 `none` 또는 `trusted-proxy`인 경우에도 이 루프백 브라우저
|
||||
라우트는 그런 identity 기반 모드를 상속하지 않으므로 반드시 루프백 전용으로 유지하세요.
|
||||
Tailscale Serve ID 헤더를 사용하지 않습니다.
|
||||
- `gateway.auth.mode`가 `none` 또는 `trusted-proxy`이면 이러한 루프백 브라우저
|
||||
경로는 해당 ID 기반 모드를 상속하지 않으므로 루프백 전용으로 유지하세요.
|
||||
|
||||
### Playwright 필요 사항
|
||||
### `/act` 오류 계약
|
||||
|
||||
`POST /act`는 경로 수준 유효성 검사와 정책 실패에 대해
|
||||
구조화된 오류 응답을 사용합니다:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
```
|
||||
|
||||
현재 `code` 값:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind`가 없거나 인식되지 않습니다.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): 작업 페이로드 정규화 또는 유효성 검사에 실패했습니다.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): 지원되지 않는 작업 종류에 `selector`가 사용되었습니다.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): config에서 `evaluate`(또는 `wait --fn`)가 비활성화되어 있습니다.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): 최상위 또는 배치된 `targetId`가 요청 대상과 충돌합니다.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): 기존 세션 프로필에서는 작업이 지원되지 않습니다.
|
||||
|
||||
기타 런타임 실패는 여전히 `code` 필드 없이
|
||||
`{ "error": "<message>" }`를 반환할 수 있습니다.
|
||||
|
||||
### Playwright 요구 사항
|
||||
|
||||
일부 기능(navigate/act/AI snapshot/role snapshot, 요소 스크린샷,
|
||||
PDF)에는 Playwright가 필요합니다. Playwright가 설치되어 있지 않으면
|
||||
해당 엔드포인트는 명확한 501 오류를 반환합니다.
|
||||
PDF)에는 Playwright가 필요합니다. Playwright가 설치되지 않은 경우 해당 엔드포인트는
|
||||
명확한 501 오류를 반환합니다.
|
||||
|
||||
Playwright 없이도 작동하는 항목:
|
||||
Playwright 없이도 여전히 작동하는 기능:
|
||||
|
||||
- ARIA 스냅샷
|
||||
- 탭별 CDP
|
||||
WebSocket을 사용할 수 있는 경우 관리형 `openclaw` 브라우저의 페이지 스크린샷
|
||||
WebSocket을 사용할 수 있을 때 관리형 `openclaw` 브라우저의 페이지 스크린샷
|
||||
- `existing-session` / Chrome MCP 프로필의 페이지 스크린샷
|
||||
- 스냅샷 출력에서 `existing-session` ref 기반 스크린샷(`--ref`)
|
||||
- 스냅샷 출력의 `existing-session` ref 기반 스크린샷(`--ref`)
|
||||
|
||||
여전히 Playwright가 필요한 항목:
|
||||
여전히 Playwright가 필요한 기능:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
@ -576,16 +593,15 @@ Playwright 없이도 작동하는 항목:
|
||||
- CSS 선택자 요소 스크린샷(`--element`)
|
||||
- 전체 브라우저 PDF 내보내기
|
||||
|
||||
요소 스크린샷은 `--full-page`도 거부합니다. 해당 라우트는 `fullPage is
|
||||
요소 스크린샷은 `--full-page`도 거부하며 경로는 `fullPage is
|
||||
not supported for element screenshots`를 반환합니다.
|
||||
|
||||
`Playwright is not available in this gateway build`가 보이면 전체
|
||||
Playwright 패키지(`playwright-core`가 아님)를 설치하고 gateway를 재시작하거나,
|
||||
브라우저 지원이 포함된 OpenClaw를 다시 설치하세요.
|
||||
`Playwright is not available in this gateway build`가 표시되면 전체
|
||||
Playwright 패키지(`playwright-core`가 아님)를 설치하고 gateway를 다시 시작하거나, 브라우저 지원이 포함된 OpenClaw를 다시 설치하세요.
|
||||
|
||||
#### Docker Playwright 설치
|
||||
|
||||
Gateway가 Docker에서 실행되는 경우 `npx playwright`는 피하세요(npm override 충돌).
|
||||
Gateway가 Docker에서 실행 중이면 `npx playwright`는 피하세요(npm override 충돌).
|
||||
대신 번들 CLI를 사용하세요:
|
||||
|
||||
```bash
|
||||
@ -594,8 +610,8 @@ docker compose run --rm openclaw-cli \
|
||||
```
|
||||
|
||||
브라우저 다운로드를 유지하려면 `PLAYWRIGHT_BROWSERS_PATH`를 설정하고(예:
|
||||
`/home/node/.cache/ms-playwright`), `/home/node`가 `OPENCLAW_HOME_VOLUME` 또는
|
||||
bind mount를 통해 유지되도록 하세요. [Docker](/ko/install/docker)를 참조하세요.
|
||||
`/home/node/.cache/ms-playwright`), `/home/node`가
|
||||
`OPENCLAW_HOME_VOLUME` 또는 bind mount를 통해 유지되도록 하세요. 자세한 내용은 [Docker](/ko/install/docker)를 참조하세요.
|
||||
|
||||
## 작동 방식(내부)
|
||||
|
||||
@ -606,13 +622,13 @@ bind mount를 통해 유지되도록 하세요. [Docker](/ko/install/docker)를
|
||||
- 고급 작업(클릭/입력/스냅샷/PDF)에는 CDP 위에서 **Playwright**를 사용합니다.
|
||||
- Playwright가 없으면 Playwright 비의존 작업만 사용할 수 있습니다.
|
||||
|
||||
이 설계는 에이전트에 안정적이고 결정적인 인터페이스를 제공하면서도,
|
||||
로컬/원격 브라우저와 프로필을 자유롭게 교체할 수 있게 합니다.
|
||||
이 설계는 에이전트가 안정적이고 결정적인 인터페이스를 사용하도록 유지하면서도
|
||||
로컬/원격 브라우저와 프로필을 교체할 수 있게 합니다.
|
||||
|
||||
## CLI 빠른 참조
|
||||
|
||||
모든 명령은 특정 프로필을 대상으로 지정하기 위해 `--browser-profile <name>`을 받습니다.
|
||||
모든 명령은 기계가 읽을 수 있는 출력(안정적인 페이로드)을 위해 `--json`도 받습니다.
|
||||
모든 명령은 특정 프로필을 대상으로 `--browser-profile <name>`을 받을 수 있습니다.
|
||||
모든 명령은 기계가 읽을 수 있는 출력(안정적인 페이로드)을 위해 `--json`도 받을 수 있습니다.
|
||||
|
||||
기본:
|
||||
|
||||
@ -645,9 +661,9 @@ bind mount를 통해 유지되도록 하세요. [Docker](/ko/install/docker)를
|
||||
|
||||
수명 주기 참고:
|
||||
|
||||
- attach-only 및 원격 CDP 프로필에서는 테스트 후에도 `openclaw browser stop`이
|
||||
올바른 정리 명령입니다. 기본 브라우저를 종료하는 대신 활성 제어 세션을 닫고
|
||||
임시 에뮬레이션 재정의를 해제합니다.
|
||||
- attach-only 및 원격 CDP 프로필의 경우에도 테스트 후 정리 명령으로는
|
||||
`openclaw browser stop`이 올바릅니다. 이 명령은 실제 브라우저를 종료하는 대신
|
||||
활성 제어 세션을 닫고 임시 에뮬레이션 재정의를 지웁니다.
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
- `openclaw browser pdf`
|
||||
@ -696,26 +712,27 @@ bind mount를 통해 유지되도록 하세요. [Docker](/ko/install/docker)를
|
||||
- `openclaw browser set locale en-US`
|
||||
- `openclaw browser set device "iPhone 14"`
|
||||
|
||||
참고:
|
||||
참고 사항:
|
||||
|
||||
- `upload`와 `dialog`는 **arming** 호출입니다. 파일 선택기/대화상자를 트리거하는 클릭/press 전에 먼저 실행하세요.
|
||||
- `upload`와 `dialog`는 **사전 준비** 호출입니다. 파일 선택기/대화상자를
|
||||
트리거하는 클릭/키 입력 전에 실행하세요.
|
||||
- 다운로드 및 trace 출력 경로는 OpenClaw 임시 루트로 제한됩니다:
|
||||
- traces: `/tmp/openclaw` (폴백: `${os.tmpdir()}/openclaw`)
|
||||
- downloads: `/tmp/openclaw/downloads` (폴백: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- 업로드 경로도 OpenClaw 임시 업로드 루트로 제한됩니다:
|
||||
- uploads: `/tmp/openclaw/uploads` (폴백: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- traces: `/tmp/openclaw` (대체 경로: `${os.tmpdir()}/openclaw`)
|
||||
- downloads: `/tmp/openclaw/downloads` (대체 경로: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- 업로드 경로는 OpenClaw 임시 업로드 루트로 제한됩니다:
|
||||
- uploads: `/tmp/openclaw/uploads` (대체 경로: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload`는 `--input-ref` 또는 `--element`를 통해 파일 입력을 직접 설정할 수도 있습니다.
|
||||
- `snapshot`:
|
||||
- `--format ai`(기본값, Playwright 설치 시): 숫자 ref(`aria-ref="<n>"`)가 있는 AI 스냅샷을 반환합니다.
|
||||
- `--format ai`(기본값, Playwright 설치 시): 숫자 ref(`aria-ref="<n>"`)가 포함된 AI 스냅샷을 반환합니다.
|
||||
- `--format aria`: 접근성 트리를 반환합니다(ref 없음, 검사 전용).
|
||||
- `--efficient`(또는 `--mode efficient`): compact role 스냅샷 프리셋(interactive + compact + depth + 낮은 maxChars)입니다.
|
||||
- config 기본값(도구/CLI 전용): 호출자가 모드를 전달하지 않을 때 efficient 스냅샷을 사용하려면 `browser.snapshotDefaults.mode: "efficient"`를 설정하세요([Gateway configuration](/ko/gateway/configuration-reference#browser) 참조).
|
||||
- role 스냅샷 옵션(`--interactive`, `--compact`, `--depth`, `--selector`)은 `ref=e12` 같은 ref가 있는 role 기반 스냅샷을 강제합니다.
|
||||
- `--frame "<iframe selector>"`는 role 스냅샷을 해당 iframe으로 범위 제한합니다(`e12` 같은 role ref와 함께 사용).
|
||||
- `--interactive`는 상호작용 가능한 요소를 평면적이고 선택하기 쉽게 출력합니다(작업 구동에 가장 적합).
|
||||
- `--labels`는 ref 레이블이 오버레이된 뷰포트 전용 스크린샷을 추가합니다(`MEDIA:<path>` 출력).
|
||||
- `click`/`type` 등은 `snapshot`에서 얻은 `ref`(숫자 `12` 또는 role ref `e12`)가 필요합니다.
|
||||
작업에는 의도적으로 CSS 선택자를 지원하지 않습니다.
|
||||
- `--efficient`(또는 `--mode efficient`): 간결한 role 스냅샷 프리셋(interactive + compact + depth + 낮은 maxChars)입니다.
|
||||
- config 기본값(도구/CLI 전용): 호출자가 모드를 전달하지 않을 때 효율적인 스냅샷을 사용하려면 `browser.snapshotDefaults.mode: "efficient"`를 설정하세요([Gateway configuration](/ko/gateway/configuration-reference#browser) 참조).
|
||||
- Role 스냅샷 옵션(`--interactive`, `--compact`, `--depth`, `--selector`)은 `ref=e12` 같은 ref가 있는 role 기반 스냅샷을 강제합니다.
|
||||
- `--frame "<iframe selector>"`는 role 스냅샷을 iframe으로 범위 지정합니다(`e12` 같은 role ref와 함께 사용).
|
||||
- `--interactive`는 상호작용 가능한 요소를 평면의, 선택하기 쉬운 목록으로 출력합니다(작업 수행에 가장 적합).
|
||||
- `--labels`는 ref 라벨이 오버레이된 뷰포트 전용 스크린샷을 추가합니다(`MEDIA:<path>` 출력).
|
||||
- `click`/`type`/기타는 `snapshot`의 `ref`(숫자 `12` 또는 role ref `e12`)가 필요합니다.
|
||||
작업에는 의도적으로 CSS 선택자가 지원되지 않습니다.
|
||||
|
||||
## 스냅샷과 ref
|
||||
|
||||
@ -724,33 +741,33 @@ OpenClaw는 두 가지 “스냅샷” 스타일을 지원합니다:
|
||||
- **AI 스냅샷(숫자 ref)**: `openclaw browser snapshot`(기본값, `--format ai`)
|
||||
- 출력: 숫자 ref가 포함된 텍스트 스냅샷.
|
||||
- 작업: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- 내부적으로 이 ref는 Playwright의 `aria-ref`를 통해 확인됩니다.
|
||||
- 내부적으로 ref는 Playwright의 `aria-ref`를 통해 확인됩니다.
|
||||
|
||||
- **Role 스냅샷(`e12` 같은 role ref)**: `openclaw browser snapshot --interactive`(`--compact`, `--depth`, `--selector`, `--frame`도 가능)
|
||||
- 출력: `[ref=e12]`(선택적으로 `[nth=1]`)가 있는 role 기반 목록/트리.
|
||||
- **Role 스냅샷(`e12` 같은 role ref)**: `openclaw browser snapshot --interactive`(또는 `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- 출력: `[ref=e12]`(및 선택적으로 `[nth=1]`)가 있는 role 기반 목록/트리.
|
||||
- 작업: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- 내부적으로 이 ref는 `getByRole(...)`(`중복일 경우 nth()` 포함)로 확인됩니다.
|
||||
- `--labels`를 추가하면 `e12` 레이블이 오버레이된 뷰포트 스크린샷이 포함됩니다.
|
||||
- 내부적으로 ref는 `getByRole(...)`(중복에 대해서는 `nth()` 추가)로 확인됩니다.
|
||||
- `--labels`를 추가하면 `e12` 라벨이 오버레이된 뷰포트 스크린샷이 포함됩니다.
|
||||
|
||||
ref 동작:
|
||||
|
||||
- ref는 **탐색 간에 안정적이지 않습니다**. 실패하면 `snapshot`을 다시 실행해 새 ref를 사용하세요.
|
||||
- role 스냅샷을 `--frame`으로 찍었다면, 다음 role 스냅샷 전까지 role ref는 해당 iframe 범위로 제한됩니다.
|
||||
- ref는 **탐색 간에 안정적이지 않으므로** 실패하면 `snapshot`을 다시 실행하고 새 ref를 사용하세요.
|
||||
- role 스냅샷이 `--frame`으로 생성된 경우 role ref는 다음 role 스냅샷까지 해당 iframe 범위로 제한됩니다.
|
||||
|
||||
## wait 기능 강화
|
||||
## Wait 확장 기능
|
||||
|
||||
시간/텍스트 외에도 다양한 조건을 기다릴 수 있습니다:
|
||||
시간/텍스트 외에도 더 많은 조건을 기다릴 수 있습니다:
|
||||
|
||||
- URL 대기(Playwright glob 지원):
|
||||
- URL 대기(Playwright가 지원하는 glob 사용 가능):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
- 로드 상태 대기:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- JS predicate 대기:
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- 선택자가 보이게 될 때까지 대기:
|
||||
- 선택자가 표시될 때까지 대기:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
이들은 조합해서 사용할 수 있습니다:
|
||||
이들은 함께 조합할 수 있습니다:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -765,19 +782,19 @@ openclaw browser wait "#main" \
|
||||
작업이 실패할 때(예: “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. `click <ref>` / `type <ref>` 사용(interactive 모드에서는 role ref 권장)
|
||||
3. 여전히 실패하면: `openclaw browser highlight <ref>`로 Playwright가 무엇을 대상으로 삼는지 확인
|
||||
2. `click <ref>` / `type <ref>` 사용(대화형 모드에서는 role ref 권장)
|
||||
3. 그래도 실패하면: `openclaw browser highlight <ref>`로 Playwright가 무엇을 대상으로 하는지 확인
|
||||
4. 페이지 동작이 이상하면:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
5. 심층 디버깅이 필요하면 trace를 기록:
|
||||
5. 깊이 있는 디버깅을 위해 trace 기록:
|
||||
- `openclaw browser trace start`
|
||||
- 문제 재현
|
||||
- `openclaw browser trace stop`(`TRACE:<path>` 출력)
|
||||
- `openclaw browser trace stop` (`TRACE:<path>` 출력)
|
||||
|
||||
## JSON 출력
|
||||
|
||||
`--json`은 스크립팅 및 구조화된 도구용입니다.
|
||||
`--json`은 스크립팅과 구조화된 도구용입니다.
|
||||
|
||||
예시:
|
||||
|
||||
@ -788,16 +805,16 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
JSON의 role 스냅샷에는 `refs`와 함께 작은 `stats` 블록(lines/chars/refs/interactive)이 포함되므로 도구가 페이로드 크기와 밀도를 판단할 수 있습니다.
|
||||
JSON의 role 스냅샷에는 `refs`와 작은 `stats` 블록(lines/chars/refs/interactive)이 포함되어 있어 도구가 페이로드 크기와 밀도를 판단할 수 있습니다.
|
||||
|
||||
## 상태 및 환경 옵션
|
||||
## 상태 및 환경 설정
|
||||
|
||||
이들은 “사이트가 X처럼 동작하게 만들기” 유형의 워크플로에 유용합니다:
|
||||
이 기능들은 “사이트가 X처럼 동작하게 만들기” 워크플로에 유용합니다:
|
||||
|
||||
- 쿠키: `cookies`, `cookies set`, `cookies clear`
|
||||
- 저장소: `storage local|session get|set|clear`
|
||||
- 스토리지: `storage local|session get|set|clear`
|
||||
- 오프라인: `set offline on|off`
|
||||
- 헤더: `set headers --headers-json '{"X-Debug":"1"}'`(레거시 `set headers --json '{"X-Debug":"1"}'`도 계속 지원)
|
||||
- 헤더: `set headers --headers-json '{"X-Debug":"1"}'` (레거시 `set headers --json '{"X-Debug":"1"}'`도 계속 지원됨)
|
||||
- HTTP basic auth: `set credentials user pass`(또는 `--clear`)
|
||||
- 위치 정보: `set geo <lat> <lon> --origin "https://example.com"`(또는 `--clear`)
|
||||
- 미디어: `set media dark|light|no-preference|none`
|
||||
@ -808,15 +825,15 @@ JSON의 role 스냅샷에는 `refs`와 함께 작은 `stats` 블록(lines/chars/
|
||||
|
||||
## 보안 및 개인정보 보호
|
||||
|
||||
- openclaw 브라우저 프로필에는 로그인된 세션이 포함될 수 있으므로 민감하게 취급하세요.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` 및 `wait --fn`은
|
||||
페이지 컨텍스트에서 임의 JavaScript를 실행합니다. 프롬프트 인젝션으로
|
||||
이것이 유도될 수 있습니다. 필요 없다면 `browser.evaluateEnabled=false`로 비활성화하세요.
|
||||
- 로그인 및 안티봇 참고 사항(X/Twitter 등)은 [Browser login + X/Twitter posting](/tools/browser-login)을 참조하세요.
|
||||
- openclaw 브라우저 프로필에는 로그인된 세션이 포함될 수 있으므로 민감한 것으로 취급하세요.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate`와 `wait --fn`은
|
||||
페이지 컨텍스트에서 임의의 JavaScript를 실행합니다. 프롬프트 인젝션이
|
||||
이를 유도할 수 있습니다. 필요하지 않다면 `browser.evaluateEnabled=false`로 비활성화하세요.
|
||||
- 로그인 및 안티봇 참고 사항(X/Twitter 등)은 [브라우저 로그인 + X/Twitter 게시](/ko/tools/browser-login)를 참조하세요.
|
||||
- Gateway/node host는 비공개 상태(루프백 또는 tailnet 전용)로 유지하세요.
|
||||
- 원격 CDP 엔드포인트는 강력하므로 터널링하고 보호해야 합니다.
|
||||
- 원격 CDP 엔드포인트는 강력하므로 터널링하고 보호하세요.
|
||||
|
||||
엄격 모드 예시(기본적으로 private/internal 대상 차단):
|
||||
엄격 모드 예시(기본적으로 비공개/내부 목적지 차단):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -833,10 +850,10 @@ JSON의 role 스냅샷에는 `refs`와 함께 작은 `stats` 블록(lines/chars/
|
||||
## 문제 해결
|
||||
|
||||
Linux 전용 문제(특히 snap Chromium)는
|
||||
[브라우저 문제 해결](/tools/browser-linux-troubleshooting)을 참조하세요.
|
||||
[브라우저 문제 해결](/ko/tools/browser-linux-troubleshooting)을 참조하세요.
|
||||
|
||||
WSL2 Gateway + Windows Chrome 분리 호스트 구성은
|
||||
[WSL2 + Windows + remote Chrome CDP 문제 해결](/tools/browser-wsl2-windows-remote-cdp-troubleshooting)을 참조하세요.
|
||||
WSL2 Gateway + Windows Chrome 분리 호스트 설정은
|
||||
[WSL2 + Windows + 원격 Chrome CDP 문제 해결](/ko/tools/browser-wsl2-windows-remote-cdp-troubleshooting)을 참조하세요.
|
||||
|
||||
## 에이전트 도구 + 제어 방식
|
||||
|
||||
@ -847,19 +864,19 @@ WSL2 Gateway + Windows Chrome 분리 호스트 구성은
|
||||
매핑 방식:
|
||||
|
||||
- `browser snapshot`은 안정적인 UI 트리(AI 또는 ARIA)를 반환합니다.
|
||||
- `browser act`는 스냅샷 `ref` ID를 사용해 클릭/입력/드래그/선택을 수행합니다.
|
||||
- `browser act`는 스냅샷의 `ref` ID를 사용해 클릭/입력/드래그/선택을 수행합니다.
|
||||
- `browser screenshot`은 픽셀을 캡처합니다(전체 페이지 또는 요소).
|
||||
- `browser`는 다음을 받습니다:
|
||||
- `profile`: 이름 있는 브라우저 프로필 선택(openclaw, chrome 또는 remote CDP).
|
||||
- `target` (`sandbox` | `host` | `node`): 브라우저가 존재하는 위치 선택.
|
||||
- 이름 있는 브라우저 프로필(openclaw, chrome 또는 원격 CDP)을 선택하는 `profile`
|
||||
- 브라우저가 어디에 있는지 선택하는 `target` (`sandbox` | `host` | `node`)
|
||||
- 샌드박스 세션에서 `target: "host"`는 `agents.defaults.sandbox.browser.allowHostControl=true`가 필요합니다.
|
||||
- `target`이 생략되면: 샌드박스 세션은 기본적으로 `sandbox`, 비샌드박스 세션은 기본적으로 `host`.
|
||||
- 브라우저 기능이 있는 노드가 연결되어 있으면 `target="host"` 또는 `target="node"`로 고정하지 않는 한 도구가 자동 라우팅될 수 있습니다.
|
||||
- `target`이 생략되면 샌드박스 세션은 기본적으로 `sandbox`, 비샌드박스 세션은 기본적으로 `host`를 사용합니다.
|
||||
- 브라우저 사용 가능한 노드가 연결되어 있으면 `target="host"` 또는 `target="node"`로 고정하지 않는 한 도구가 자동으로 그 노드로 라우팅될 수 있습니다.
|
||||
|
||||
이렇게 하면 에이전트 동작이 결정적으로 유지되고 깨지기 쉬운 선택자를 피할 수 있습니다.
|
||||
이 방식은 에이전트를 결정적으로 유지하고 깨지기 쉬운 선택자를 피하게 합니다.
|
||||
|
||||
## 관련 항목
|
||||
## 관련 문서
|
||||
|
||||
- [도구 개요](/tools) — 사용 가능한 모든 에이전트 도구
|
||||
- [도구 개요](/ko/tools) — 사용 가능한 모든 에이전트 도구
|
||||
- [샌드박싱](/ko/gateway/sandboxing) — 샌드박스 환경에서의 브라우저 제어
|
||||
- [보안](/ko/gateway/security) — 브라우저 제어 위험 및 강화 방법
|
||||
- [보안](/ko/gateway/security) — 브라우저 제어 위험 및 강화
|
||||
|
||||
Loading…
Reference in New Issue
Block a user