chore(i18n): refresh ko translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
a491ec7f19
commit
ccf1bfff30
@ -3,20 +3,20 @@ read_when:
|
||||
- 백그라운드 작업 또는 웨이크업 예약하기
|
||||
- 외부 트리거(웹훅, Gmail)를 OpenClaw에 연결하기
|
||||
- 예약된 작업에 heartbeat와 cron 중 무엇을 사용할지 결정하기
|
||||
summary: Gateway 스케줄러용 예약된 작업, 웹훅, Gmail PubSub 트리거
|
||||
summary: Gateway 스케줄러를 위한 예약 작업, 웹훅, Gmail PubSub 트리거
|
||||
title: 예약된 작업
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:44:26Z"
|
||||
generated_at: "2026-04-12T05:58:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665
|
||||
source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f
|
||||
source_path: automation/cron-jobs.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 예약된 작업 (Cron)
|
||||
|
||||
Cron은 Gateway에 내장된 스케줄러입니다. 작업을 영구 저장하고, 적절한 시점에 에이전트를 깨우며, 출력을 채팅 채널이나 웹훅 엔드포인트로 다시 전달할 수 있습니다.
|
||||
Cron은 Gateway의 내장 스케줄러입니다. 작업을 영속적으로 저장하고, 적절한 시점에 에이전트를 깨우며, 출력을 채팅 채널이나 웹훅 엔드포인트로 다시 전달할 수 있습니다.
|
||||
|
||||
## 빠른 시작
|
||||
|
||||
@ -33,59 +33,71 @@ openclaw cron add \
|
||||
# 작업 확인
|
||||
openclaw cron list
|
||||
|
||||
# 실행 기록 확인
|
||||
# 실행 기록 보기
|
||||
openclaw cron runs --id <job-id>
|
||||
```
|
||||
|
||||
## cron 작동 방식
|
||||
|
||||
- Cron은 **Gateway 프로세스 내부에서** 실행됩니다(모델 내부가 아님).
|
||||
- 작업은 `~/.openclaw/cron/jobs.json`에 저장되므로 재시작해도 일정이 사라지지 않습니다.
|
||||
- Cron은 **모델 내부가 아니라** **Gateway 프로세스 내부에서** 실행됩니다.
|
||||
- 작업은 `~/.openclaw/cron/jobs.json`에 영속 저장되므로 재시작해도 예약이 사라지지 않습니다.
|
||||
- 모든 cron 실행은 [백그라운드 작업](/ko/automation/tasks) 레코드를 생성합니다.
|
||||
- 일회성 작업(`--at`)은 기본적으로 성공 후 자동 삭제됩니다.
|
||||
- 격리된 cron 실행은 실행이 완료되면 해당 `cron:<jobId>` 세션에 대해 추적 중인 브라우저 탭/프로세스를 가능한 범위에서 종료하므로, 분리된 브라우저 자동화가 고아 프로세스를 남기지 않습니다.
|
||||
- 격리된 cron 실행은 오래된 확인 응답도 방지합니다. 첫 번째 결과가 단지 중간 상태 업데이트(`on it`, `pulling everything together` 및 유사한 힌트)이고, 최종 응답을 여전히 담당하는 하위 에이전트 실행이 없다면, OpenClaw는 전달 전에 실제 결과를 한 번 더 요청합니다.
|
||||
- 격리된 cron 실행은 완료 시 해당 `cron:<jobId>` 세션에 대해 추적 중인 브라우저 탭/프로세스를 가능한 범위에서 종료하므로, 분리된 브라우저 자동화가 고아 프로세스를 남기지 않도록 합니다.
|
||||
- 격리된 cron 실행은 오래된 확인 응답도 방지합니다. 첫 번째 결과가 단지 임시 상태 업데이트(`on it`, `pulling everything together` 및 이와 유사한 안내)이고, 최종 답변을 아직 담당 중인 하위 에이전트 실행이 없는 경우, OpenClaw는 실제 결과를 전달하기 전에 한 번 더 재프롬프트합니다.
|
||||
|
||||
<a id="maintenance"></a>
|
||||
|
||||
cron의 작업 정합성 조정은 런타임에서 관리됩니다. 활성 cron 작업은, 오래된 하위 세션 행이 여전히 존재하더라도, cron 런타임이 해당 작업을 실행 중으로 추적하는 동안 계속 활성 상태를 유지합니다.
|
||||
런타임이 더 이상 해당 작업을 소유하지 않고 5분 유예 창이 지나면, 유지 관리가 작업을 `lost`로 표시할 수 있습니다.
|
||||
cron의 작업 재조정은 런타임이 소유합니다. 이전 하위 세션 행이 여전히 존재하더라도, cron 런타임이 해당 작업을 실행 중으로 계속 추적하는 동안 활성 cron 작업은 살아 있는 상태로 유지됩니다.
|
||||
런타임이 더 이상 작업을 소유하지 않고 5분의 유예 시간이 지나면, 유지 관리가 해당 작업을 `lost`로 표시할 수 있습니다.
|
||||
|
||||
## 일정 유형
|
||||
## 예약 유형
|
||||
|
||||
| 종류 | CLI 플래그 | 설명 |
|
||||
| ------- | ---------- | --------------------------------------------------------- |
|
||||
| `at` | `--at` | 일회성 타임스탬프(ISO 8601 또는 `20m` 같은 상대 시간) |
|
||||
| `every` | `--every` | 고정 간격 |
|
||||
| `cron` | `--cron` | 선택적 `--tz`를 포함한 5필드 또는 6필드 cron 표현식 |
|
||||
| `cron` | `--cron` | 선택적 `--tz`와 함께 사용하는 5필드 또는 6필드 cron 표현식 |
|
||||
|
||||
시간대가 없는 타임스탬프는 UTC로 처리됩니다. 로컬 벽시계 기준 스케줄링에는 `--tz America/New_York`를 추가하세요.
|
||||
시간대가 없는 타임스탬프는 UTC로 처리됩니다. 로컬 벽시계 기준 예약을 사용하려면 `--tz America/New_York`를 추가하세요.
|
||||
|
||||
매시 정각에 반복되는 표현식은 부하 급증을 줄이기 위해 자동으로 최대 5분까지 분산됩니다. 정확한 타이밍을 강제하려면 `--exact`를 사용하고, 명시적인 창을 지정하려면 `--stagger 30s`를 사용하세요.
|
||||
매시 정각에 반복되는 표현식은 부하 급증을 줄이기 위해 최대 5분까지 자동으로 분산됩니다. 정확한 시각을 강제하려면 `--exact`를 사용하고, 명시적인 범위를 지정하려면 `--stagger 30s`를 사용하세요.
|
||||
|
||||
### day-of-month와 day-of-week는 OR 로직을 사용합니다
|
||||
|
||||
Cron 표현식은 [croner](https://github.com/Hexagon/croner)로 파싱됩니다. day-of-month와 day-of-week 필드가 모두 와일드카드가 아닐 경우, croner는 **두 필드가 모두 일치할 때가 아니라** **둘 중 하나가 일치할 때** 일치로 판단합니다. 이는 표준 Vixie cron 동작입니다.
|
||||
|
||||
```
|
||||
# 의도: "15일이 월요일일 때만 오전 9시"
|
||||
# 실제: "매월 15일 오전 9시, 그리고 매주 월요일 오전 9시"
|
||||
0 9 15 * 1
|
||||
```
|
||||
|
||||
이 표현식은 월 0~1회가 아니라 월 약 5~6회 실행됩니다. OpenClaw는 여기서 Croner의 기본 OR 동작을 사용합니다. 두 조건을 모두 요구하려면 Croner의 `+` day-of-week 수정자(`0 9 15 * +1`)를 사용하거나, 한 필드만으로 예약하고 다른 조건은 작업의 프롬프트나 명령에서 별도로 검사하세요.
|
||||
|
||||
## 실행 스타일
|
||||
|
||||
| 스타일 | `--session` 값 | 실행 위치 | 적합한 용도 |
|
||||
| -------------- | ------------------- | ------------------------ | ------------------------------ |
|
||||
| 메인 세션 | `main` | 다음 heartbeat 턴 | 리마인더, 시스템 이벤트 |
|
||||
| 격리됨 | `isolated` | 전용 `cron:<jobId>` | 보고서, 백그라운드 작업 |
|
||||
| 현재 세션 | `current` | 생성 시점에 바인딩됨 | 컨텍스트 인식 반복 작업 |
|
||||
| 사용자 지정 세션 | `session:custom-id` | 영구적인 이름 있는 세션 | 기록을 기반으로 누적되는 워크플로 |
|
||||
| 스타일 | `--session` 값 | 실행 위치 | 적합한 용도 |
|
||||
| -------------- | ------------------- | ------------------------ | ------------------------------- |
|
||||
| 메인 세션 | `main` | 다음 heartbeat 턴 | 리마인더, 시스템 이벤트 |
|
||||
| 격리됨 | `isolated` | 전용 `cron:<jobId>` | 보고서, 백그라운드 작업 |
|
||||
| 현재 세션 | `current` | 생성 시점에 바인딩됨 | 컨텍스트 인식 반복 작업 |
|
||||
| 사용자 지정 세션 | `session:custom-id` | 영속적 이름 지정 세션 | 기록을 기반으로 하는 워크플로 |
|
||||
|
||||
**메인 세션** 작업은 시스템 이벤트를 큐에 넣고 선택적으로 heartbeat를 깨웁니다(`--wake now` 또는 `--wake next-heartbeat`). **격리된** 작업은 새 세션으로 전용 에이전트 턴을 실행합니다. **사용자 지정 세션**(`session:xxx`)은 실행 간 컨텍스트를 유지하므로, 이전 요약을 바탕으로 하는 일일 스탠드업 같은 워크플로를 가능하게 합니다.
|
||||
**메인 세션** 작업은 시스템 이벤트를 큐에 넣고 필요하면 heartbeat를 깨웁니다(`--wake now` 또는 `--wake next-heartbeat`). **격리됨** 작업은 새 세션으로 전용 에이전트 턴을 실행합니다. **사용자 지정 세션**(`session:xxx`)은 실행 간 컨텍스트를 유지하므로, 이전 요약을 바탕으로 하는 일일 스탠드업 같은 워크플로를 구현할 수 있습니다.
|
||||
|
||||
격리된 작업의 경우, 런타임 정리에는 이제 해당 cron 세션에 대한 브라우저 정리를 가능한 범위에서 수행하는 과정이 포함됩니다. 정리 실패는 무시되므로 실제 cron 결과가 계속 우선합니다.
|
||||
격리된 작업의 경우, 이제 런타임 정리 단계에 해당 cron 세션에 대한 가능한 범위의 브라우저 정리가 포함됩니다. 정리 실패는 실제 cron 결과가 우선되도록 무시됩니다.
|
||||
|
||||
격리된 cron 실행이 하위 에이전트를 조율할 때는, 전달도 오래된 상위 중간 텍스트보다 최종 하위 출력이 우선됩니다. 하위 항목이 아직 실행 중이면 OpenClaw는 그 부분적인 상위 업데이트를 알리지 않고 억제합니다.
|
||||
격리된 cron 실행이 하위 에이전트를 오케스트레이션할 때는, 전달 과정에서도 오래된 상위 임시 텍스트보다 최종 하위 출력이 우선됩니다. 하위 에이전트가 아직 실행 중이면, OpenClaw는 해당 부분적인 상위 업데이트를 알리지 않고 억제합니다.
|
||||
|
||||
### 격리된 작업의 페이로드 옵션
|
||||
|
||||
- `--message`: 프롬프트 텍스트(격리된 작업에 필수)
|
||||
- `--model` / `--thinking`: 모델 및 사고 수준 재정의
|
||||
- `--light-context`: 워크스페이스 부트스트랩 파일 주입 건너뛰기
|
||||
- `--message`: 프롬프트 텍스트(격리됨에서는 필수)
|
||||
- `--model` / `--thinking`: 모델 및 thinking 수준 재정의
|
||||
- `--light-context`: 워크스페이스 bootstrap 파일 주입 건너뛰기
|
||||
- `--tools exec,read`: 작업이 사용할 수 있는 도구 제한
|
||||
|
||||
`--model`은 해당 작업에 대해 선택된 허용 모델을 사용합니다. 요청한 모델이 허용되지 않으면 cron은 경고를 기록하고 대신 작업의 에이전트/기본 모델 선택으로 대체합니다. 구성된 폴백 체인은 계속 적용되지만, 명시적인 작업별 폴백 목록이 없는 단순 모델 재정의는 더 이상 에이전트 기본 모델을 숨겨진 추가 재시도 대상으로 덧붙이지 않습니다.
|
||||
`--model`은 해당 작업에 대해 선택된 허용 모델을 사용합니다. 요청한 모델이 허용되지 않으면 cron은 경고를 기록하고, 대신 작업의 에이전트/기본 모델 선택으로 폴백합니다. 구성된 폴백 체인은 계속 적용되지만, 명시적인 작업별 폴백 목록 없이 단순 모델 재정의를 사용한 경우에는 에이전트 기본 모델이 숨겨진 추가 재시도 대상으로 더 이상 붙지 않습니다.
|
||||
|
||||
격리된 작업의 모델 선택 우선순위는 다음과 같습니다.
|
||||
|
||||
@ -94,30 +106,30 @@ cron의 작업 정합성 조정은 런타임에서 관리됩니다. 활성 cron
|
||||
3. 저장된 cron 세션 모델 재정의
|
||||
4. 에이전트/기본 모델 선택
|
||||
|
||||
Fast 모드도 해결된 라이브 선택을 따릅니다. 선택된 모델 구성에 `params.fastMode`가 있으면, 격리된 cron은 기본적으로 이를 사용합니다. 저장된 세션 `fastMode` 재정의는 어느 방향이든 구성보다 여전히 우선합니다.
|
||||
빠른 모드도 해결된 실제 선택을 따릅니다. 선택된 모델 구성에 `params.fastMode`가 있으면, 격리된 cron은 기본적으로 이를 사용합니다. 저장된 세션 `fastMode` 재정의는 어느 방향에서든 구성보다 우선합니다.
|
||||
|
||||
격리된 실행이 라이브 모델 전환 handoff에 도달하면, cron은 전환된 provider/model로 재시도하고 재시도 전에 해당 라이브 선택을 저장합니다. 전환에 새 인증 프로필도 포함되면, cron은 그 인증 프로필 재정의도 저장합니다. 재시도는 제한됩니다. 최초 시도와 2회의 전환 재시도 이후에는 무한 루프 대신 중단합니다.
|
||||
격리된 실행 중 실제 모델 전환 handoff가 발생하면, cron은 전환된 provider/model로 재시도하고 재시도 전에 해당 실제 선택을 저장합니다. 전환에 새 인증 프로필도 포함되어 있으면, cron은 그 인증 프로필 재정의도 저장합니다. 재시도 횟수는 제한됩니다. 초기 시도 후 전환 재시도 2회가 지나면 cron은 무한 반복 대신 중단합니다.
|
||||
|
||||
## 전달 및 출력
|
||||
|
||||
| 모드 | 동작 |
|
||||
| ---------- | ----------------------------------------------------------- |
|
||||
| `announce` | 요약을 대상 채널로 전달(격리된 작업의 기본값) |
|
||||
| `webhook` | 완료된 이벤트 페이로드를 URL로 POST |
|
||||
| `none` | 내부 전용, 전달 없음 |
|
||||
| 모드 | 동작 |
|
||||
| --------- | ------------------------------------------------------ |
|
||||
| `announce` | 대상 채널에 요약 전달(격리됨의 기본값) |
|
||||
| `webhook` | 완료된 이벤트 페이로드를 URL로 POST |
|
||||
| `none` | 내부 전용, 전달 없음 |
|
||||
|
||||
채널 전달에는 `--announce --channel telegram --to "-1001234567890"`를 사용하세요. Telegram 포럼 토픽에는 `-1001234567890:topic:123`을 사용하세요. Slack/Discord/Mattermost 대상은 명시적 접두사(`channel:<id>`, `user:<id>`)를 사용해야 합니다.
|
||||
|
||||
cron이 소유하는 격리된 작업의 경우, 실행기가 최종 전달 경로를 소유합니다. 에이전트는 일반 텍스트 요약을 반환하도록 프롬프트되며, 이 요약은 이후 `announce`, `webhook`을 통해 전송되거나 `none`일 경우 내부에만 유지됩니다. `--no-deliver`는 전달을 에이전트로 되돌리지 않으며, 실행을 내부용으로 유지합니다.
|
||||
cron이 소유한 격리 작업의 경우, 실행기가 최종 전달 경로를 소유합니다. 에이전트는 일반 텍스트 요약을 반환하도록 프롬프트되며, 그 요약은 이후 `announce`, `webhook`을 통해 전송되거나 `none`의 경우 내부에만 유지됩니다. `--no-deliver`는 전달 책임을 에이전트로 되돌리지 않습니다. 대신 실행을 내부 전용으로 유지합니다.
|
||||
|
||||
원래 작업이 어떤 외부 수신자에게 메시지를 보내라고 명시적으로 말하는 경우, 에이전트는 직접 보내려고 하지 말고 출력에 누구에게/어디로 그 메시지가 가야 하는지 적어야 합니다.
|
||||
원래 작업이 일부 외부 수신자에게 메시지를 보내라고 명시적으로 지시하는 경우, 에이전트는 직접 전송을 시도하는 대신 그 메시지를 누구/어디로 보내야 하는지 출력을 통해 알려야 합니다.
|
||||
|
||||
실패 알림은 별도의 대상 경로를 따릅니다.
|
||||
|
||||
- `cron.failureDestination`은 실패 알림의 전역 기본값을 설정합니다.
|
||||
- `job.delivery.failureDestination`은 작업별로 이를 재정의합니다.
|
||||
- 둘 다 설정되지 않았고 작업이 이미 `announce`를 통해 전달하는 경우, 실패 알림은 이제 해당 기본 announce 대상으로 폴백됩니다.
|
||||
- `delivery.failureDestination`은 기본 전달 모드가 `webhook`인 경우를 제외하면 `sessionTarget="isolated"` 작업에서만 지원됩니다.
|
||||
- 둘 다 설정되지 않았고 작업이 이미 `announce`를 통해 전달되는 경우, 실패 알림은 이제 해당 기본 announce 대상으로 폴백합니다.
|
||||
- `delivery.failureDestination`은 `sessionTarget="isolated"` 작업에서만 지원되며, 예외적으로 기본 전달 모드가 `webhook`인 경우는 지원됩니다.
|
||||
|
||||
## CLI 예시
|
||||
|
||||
@ -146,7 +158,7 @@ openclaw cron add \
|
||||
--to "channel:C1234567890"
|
||||
```
|
||||
|
||||
모델 및 사고 재정의가 있는 격리 작업:
|
||||
모델 및 thinking 재정의가 포함된 격리 작업:
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@ -176,9 +188,9 @@ Gateway는 외부 트리거를 위한 HTTP 웹훅 엔드포인트를 노출할
|
||||
|
||||
### 인증
|
||||
|
||||
모든 요청은 헤더를 통해 훅 토큰을 포함해야 합니다.
|
||||
모든 요청은 헤더를 통해 hook token을 포함해야 합니다.
|
||||
|
||||
- `Authorization: Bearer <token>`(권장)
|
||||
- `Authorization: Bearer <token>` (권장)
|
||||
- `x-openclaw-token: <token>`
|
||||
|
||||
쿼리 문자열 토큰은 거부됩니다.
|
||||
@ -194,8 +206,8 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \
|
||||
-d '{"text":"New email received","mode":"now"}'
|
||||
```
|
||||
|
||||
- `text`(필수): 이벤트 설명
|
||||
- `mode`(선택 사항): `now`(기본값) 또는 `next-heartbeat`
|
||||
- `text` (필수): 이벤트 설명
|
||||
- `mode` (선택 사항): `now`(기본값) 또는 `next-heartbeat`
|
||||
|
||||
### POST /hooks/agent
|
||||
|
||||
@ -210,41 +222,41 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \
|
||||
|
||||
필드: `message`(필수), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`.
|
||||
|
||||
### 매핑된 훅(POST /hooks/\<name\>)
|
||||
### 매핑된 훅 (POST /hooks/\<name\>)
|
||||
|
||||
사용자 지정 훅 이름은 구성의 `hooks.mappings`를 통해 해석됩니다. 매핑은 템플릿이나 코드 변환을 사용해 임의의 페이로드를 `wake` 또는 `agent` 작업으로 변환할 수 있습니다.
|
||||
사용자 지정 hook 이름은 구성의 `hooks.mappings`를 통해 해석됩니다. 매핑은 템플릿 또는 코드 변환을 사용해 임의의 페이로드를 `wake` 또는 `agent` 작업으로 변환할 수 있습니다.
|
||||
|
||||
### 보안
|
||||
|
||||
- 훅 엔드포인트는 loopback, tailnet 또는 신뢰할 수 있는 리버스 프록시 뒤에 두세요.
|
||||
- 전용 훅 토큰을 사용하세요. gateway 인증 토큰을 재사용하지 마세요.
|
||||
- `hooks.path`는 전용 하위 경로에 두세요. `/`는 거부됩니다.
|
||||
- `hooks.allowedAgentIds`를 설정해 명시적 `agentId` 라우팅을 제한하세요.
|
||||
- 호출자 선택 세션이 꼭 필요하지 않다면 `hooks.allowRequestSessionKey=false`로 유지하세요.
|
||||
- `hooks.allowRequestSessionKey`를 활성화한다면, 허용되는 세션 키 형태를 제한하기 위해 `hooks.allowedSessionKeyPrefixes`도 설정하세요.
|
||||
- 훅 페이로드는 기본적으로 안전 경계로 감싸집니다.
|
||||
- hook 엔드포인트는 loopback, tailnet 또는 신뢰할 수 있는 reverse proxy 뒤에 두세요.
|
||||
- 전용 hook token을 사용하세요. gateway 인증 토큰을 재사용하지 마세요.
|
||||
- `hooks.path`는 전용 하위 경로로 유지하세요. `/`는 거부됩니다.
|
||||
- 명시적 `agentId` 라우팅을 제한하려면 `hooks.allowedAgentIds`를 설정하세요.
|
||||
- 호출자가 세션을 선택해야 하는 경우가 아니라면 `hooks.allowRequestSessionKey=false`로 유지하세요.
|
||||
- `hooks.allowRequestSessionKey`를 활성화하는 경우, 허용되는 session key 형태를 제한하기 위해 `hooks.allowedSessionKeyPrefixes`도 함께 설정하세요.
|
||||
- hook 페이로드는 기본적으로 안전 경계로 감싸집니다.
|
||||
|
||||
## Gmail PubSub 통합
|
||||
|
||||
Google PubSub을 통해 Gmail 받은편지함 트리거를 OpenClaw에 연결합니다.
|
||||
Google PubSub를 통해 Gmail 받은편지함 트리거를 OpenClaw에 연결합니다.
|
||||
|
||||
**사전 요구 사항**: `gcloud` CLI, `gog` (`gogcli`), 활성화된 OpenClaw hooks, 공개 HTTPS 엔드포인트를 위한 Tailscale.
|
||||
**사전 요구 사항**: `gcloud` CLI, `gog` (gogcli), 활성화된 OpenClaw hooks, 공개 HTTPS 엔드포인트용 Tailscale.
|
||||
|
||||
### 설정 마법사(권장)
|
||||
### 마법사 설정 (권장)
|
||||
|
||||
```bash
|
||||
openclaw webhooks gmail setup --account openclaw@gmail.com
|
||||
```
|
||||
|
||||
이 명령은 `hooks.gmail` 구성을 작성하고, Gmail 프리셋을 활성화하며, 푸시 엔드포인트에 Tailscale Funnel을 사용합니다.
|
||||
이 명령은 `hooks.gmail` 구성을 작성하고, Gmail 프리셋을 활성화하며, push 엔드포인트에 Tailscale Funnel을 사용합니다.
|
||||
|
||||
### Gateway 자동 시작
|
||||
|
||||
`hooks.enabled=true`이고 `hooks.gmail.account`가 설정되어 있으면, Gateway는 부팅 시 `gog gmail watch serve`를 시작하고 watch를 자동 갱신합니다. 비활성화하려면 `OPENCLAW_SKIP_GMAIL_WATCHER=1`을 설정하세요.
|
||||
|
||||
### 수동 1회 설정
|
||||
### 수동 일회성 설정
|
||||
|
||||
1. `gog`에서 사용하는 OAuth 클라이언트를 소유한 GCP 프로젝트를 선택합니다.
|
||||
1. `gog`가 사용하는 OAuth 클라이언트를 소유한 GCP 프로젝트를 선택합니다.
|
||||
|
||||
```bash
|
||||
gcloud auth login
|
||||
@ -252,7 +264,7 @@ gcloud config set project <project-id>
|
||||
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
|
||||
```
|
||||
|
||||
2. 토픽을 만들고 Gmail 푸시 액세스 권한을 부여합니다.
|
||||
2. 토픽을 만들고 Gmail push 액세스 권한을 부여합니다.
|
||||
|
||||
```bash
|
||||
gcloud pubsub topics create gog-gmail-watch
|
||||
@ -286,7 +298,7 @@ gog gmail watch start \
|
||||
## 작업 관리
|
||||
|
||||
```bash
|
||||
# 모든 작업 목록 보기
|
||||
# 모든 작업 나열
|
||||
openclaw cron list
|
||||
|
||||
# 작업 편집
|
||||
@ -295,7 +307,7 @@ openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
|
||||
# 작업을 지금 강제 실행
|
||||
openclaw cron run <jobId>
|
||||
|
||||
# 기한이 된 경우에만 실행
|
||||
# 실행 시점이 된 경우에만 실행
|
||||
openclaw cron run <jobId> --due
|
||||
|
||||
# 실행 기록 보기
|
||||
@ -304,7 +316,7 @@ openclaw cron runs --id <jobId> --limit 50
|
||||
# 작업 삭제
|
||||
openclaw cron remove <jobId>
|
||||
|
||||
# 에이전트 선택(멀티 에이전트 설정)
|
||||
# 에이전트 선택(멀티 에이전트 구성)
|
||||
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
|
||||
openclaw cron edit <jobId> --clear-agent
|
||||
```
|
||||
@ -312,9 +324,9 @@ openclaw cron edit <jobId> --clear-agent
|
||||
모델 재정의 참고:
|
||||
|
||||
- `openclaw cron add|edit --model ...`은 작업의 선택된 모델을 변경합니다.
|
||||
- 모델이 허용되면, 정확히 그 provider/model이 격리된 에이전트 실행에 전달됩니다.
|
||||
- 허용되지 않으면 cron이 경고를 표시하고 작업의 에이전트/기본 모델 선택으로 폴백합니다.
|
||||
- 구성된 폴백 체인은 계속 적용되지만, 명시적인 작업별 폴백 목록이 없는 일반 `--model` 재정의는 더 이상 에이전트 기본 모델로 조용히 추가 재시도 대상이 되지 않습니다.
|
||||
- 모델이 허용되면 해당 정확한 provider/model이 격리된 에이전트 실행에 전달됩니다.
|
||||
- 허용되지 않으면 cron은 경고를 표시하고 작업의 에이전트/기본 모델 선택으로 폴백합니다.
|
||||
- 구성된 폴백 체인은 계속 적용되지만, 명시적인 작업별 폴백 목록이 없는 일반 `--model` 재정의는 더 이상 에이전트 기본 모델로 조용히 추가 재시도되는 대상이 되지 않습니다.
|
||||
|
||||
## 구성
|
||||
|
||||
@ -338,9 +350,9 @@ openclaw cron edit <jobId> --clear-agent
|
||||
|
||||
cron 비활성화: `cron.enabled: false` 또는 `OPENCLAW_SKIP_CRON=1`.
|
||||
|
||||
**일회성 재시도**: 일시적 오류(rate limit, overload, network, server error)는 지수형 백오프와 함께 최대 3회 재시도합니다. 영구 오류는 즉시 비활성화됩니다.
|
||||
**일회성 재시도**: 일시적 오류(rate limit, overload, network, server error)는 지수 백오프로 최대 3회까지 재시도합니다. 영구 오류는 즉시 비활성화됩니다.
|
||||
|
||||
**반복 재시도**: 재시도 사이에 지수형 백오프(30초~60분)를 사용합니다. 다음 실행이 성공하면 백오프는 초기화됩니다.
|
||||
**반복 재시도**: 재시도 사이에 지수 백오프(30초~60분)를 사용합니다. 다음 실행이 성공하면 백오프는 재설정됩니다.
|
||||
|
||||
**유지 관리**: `cron.sessionRetention`(기본값 `24h`)은 격리된 실행 세션 항목을 정리합니다. `cron.runLog.maxBytes` / `cron.runLog.keepLines`는 실행 로그 파일을 자동으로 정리합니다.
|
||||
|
||||
@ -359,22 +371,22 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### cron이 실행되지 않음
|
||||
### Cron이 실행되지 않음
|
||||
|
||||
- `cron.enabled`와 `OPENCLAW_SKIP_CRON` 환경 변수를 확인하세요.
|
||||
- Gateway가 계속 실행 중인지 확인하세요.
|
||||
- `cron` 일정의 경우 시간대(`--tz`)와 호스트 시간대가 맞는지 확인하세요.
|
||||
- 실행 출력의 `reason: not-due`는 수동 실행이 `openclaw cron run <jobId> --due`로 확인되었지만 작업이 아직 실행 시각이 되지 않았음을 의미합니다.
|
||||
- `cron` 일정의 경우, 시간대(`--tz`)와 호스트 시간대를 확인하세요.
|
||||
- 실행 출력의 `reason: not-due`는 수동 실행이 `openclaw cron run <jobId> --due`로 확인되었지만 아직 실행 시점이 되지 않았음을 의미합니다.
|
||||
|
||||
### cron이 실행되었지만 전달되지 않음
|
||||
### Cron이 실행됐지만 전달되지 않음
|
||||
|
||||
- 전달 모드가 `none`이면 외부 메시지가 예상되지 않습니다.
|
||||
- 전달 모드가 `none`이면 외부 메시지가 전송되지 않는 것이 정상입니다.
|
||||
- 전달 대상이 없거나 잘못된 경우(`channel`/`to`)에는 외부 전송이 건너뛰어집니다.
|
||||
- 채널 인증 오류(`unauthorized`, `Forbidden`)는 자격 증명 문제로 전달이 차단되었음을 의미합니다.
|
||||
- 격리된 실행이 무음 토큰(`NO_REPLY` / `no_reply`)만 반환하면, OpenClaw는 직접 외부 전달도 억제하고 폴백 대기열 요약 경로도 억제하므로 채팅에 아무것도 게시되지 않습니다.
|
||||
- cron이 소유하는 격리된 작업의 경우, 에이전트가 폴백으로 message tool을 사용할 것이라고 기대하지 마세요. 최종 전달은 실행기가 소유하며, `--no-deliver`는 직접 전송을 허용하는 대신 내부용으로 유지합니다.
|
||||
- 격리된 실행이 무음 토큰(`NO_REPLY` / `no_reply`)만 반환하면, OpenClaw는 직접 외부 전달을 억제하고 대기 중인 요약 폴백 경로도 억제하므로 채팅에 아무것도 게시되지 않습니다.
|
||||
- cron이 소유한 격리 작업의 경우, 에이전트가 폴백으로 message 도구를 사용할 것이라고 기대하지 마세요. 최종 전달은 실행기가 소유하며, `--no-deliver`는 직접 전송을 허용하는 대신 내부 전용으로 유지합니다.
|
||||
|
||||
### 시간대 관련 주의 사항
|
||||
### 시간대 관련 주의사항
|
||||
|
||||
- `--tz`가 없는 cron은 gateway 호스트 시간대를 사용합니다.
|
||||
- 시간대가 없는 `at` 일정은 UTC로 처리됩니다.
|
||||
@ -383,6 +395,6 @@ openclaw doctor
|
||||
## 관련 문서
|
||||
|
||||
- [자동화 및 작업](/ko/automation) — 모든 자동화 메커니즘 한눈에 보기
|
||||
- [백그라운드 작업](/ko/automation/tasks) — cron 실행을 위한 작업 원장
|
||||
- [백그라운드 작업](/ko/automation/tasks) — cron 실행용 작업 원장
|
||||
- [Heartbeat](/ko/gateway/heartbeat) — 주기적인 메인 세션 턴
|
||||
- [시간대](/ko/concepts/timezone) — 시간대 구성
|
||||
|
||||
@ -3,28 +3,28 @@ read_when:
|
||||
- 활성 메모리가 무엇을 위한 것인지 이해하고 싶습니다
|
||||
- 대화형 에이전트에 활성 메모리를 켜고 싶습니다
|
||||
- 활성 메모리를 모든 곳에서 활성화하지 않고 동작을 조정하고 싶습니다
|
||||
summary: 대화형 채팅 세션에 관련 메모리를 주입하는 플러그인 소유 차단 메모리 서브 에이전트
|
||||
summary: 대화형 채팅 세션에 관련 메모리를 주입하는 플러그인 소유의 차단형 메모리 서브 에이전트
|
||||
title: 활성 메모리
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T05:44:54Z"
|
||||
generated_at: "2026-04-12T05:58:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e8b0e6539e09678e9e8def68795f8bcb992f98509423da3da3123eda88ec1dd5
|
||||
source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 활성 메모리
|
||||
|
||||
활성 메모리는 적격한 대화형 세션에서 메인 응답 전에 실행되는 선택적 플러그인 소유 차단 메모리 서브 에이전트입니다.
|
||||
활성 메모리는 적격한 대화형 세션에서 주 응답 전에 실행되는 선택적 플러그인 소유의 차단형 메모리 서브 에이전트입니다.
|
||||
|
||||
대부분의 메모리 시스템은 성능은 좋지만 반응형이기 때문에 이것이 존재합니다. 메인 에이전트가 언제 메모리를 검색할지 결정하거나, 사용자가 "이걸 기억해" 또는 "메모리 검색해" 같은 말을 하기를 기다립니다. 그 시점이 되면, 메모리가 응답을 더 자연스럽게 만들 수 있었던 순간은 이미 지나간 뒤입니다.
|
||||
대부분의 메모리 시스템은 강력하지만 반응형이기 때문에 이것이 존재합니다. 이런 시스템은 주 에이전트가 언제 메모리를 검색할지 결정하거나, 사용자가 "이걸 기억해" 또는 "메모리를 검색해" 같은 말을 하기를 기다립니다. 그 시점이 되면 메모리가 응답을 더 자연스럽게 만들 수 있었던 순간은 이미 지나가 버린 뒤입니다.
|
||||
|
||||
활성 메모리는 메인 응답이 생성되기 전에 관련 메모리를 노출할 수 있는 제한된 한 번의 기회를 시스템에 제공합니다.
|
||||
활성 메모리는 주 응답이 생성되기 전에 시스템이 관련 메모리를 제한된 범위 안에서 한 번 꺼내 보여줄 기회를 제공합니다.
|
||||
|
||||
## 이것을 에이전트에 붙여넣기
|
||||
## 이것을 에이전트에 붙여 넣기
|
||||
|
||||
안전한 기본값이 포함된 독립형 설정으로 활성 메모리를 켜고 싶다면, 이것을 에이전트에 붙여넣으세요:
|
||||
독립적이고 안전한 기본 설정으로 활성 메모리를 사용하도록 에이전트에 설정하려면, 아래 내용을 에이전트에 붙여 넣으세요.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -36,7 +36,7 @@ x-i18n:
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
modelFallback: "google/gemini-3-flash",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
@ -50,15 +50,15 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
이 설정은 `main` 에이전트에 대해 플러그인을 켜고, 기본적으로 직접 메시지 스타일 세션으로 제한하며, 먼저 현재 세션 모델을 상속하도록 하고, 명시적이거나 상속된 모델을 사용할 수 없는 경우에도 내장 원격 대체를 계속 허용합니다.
|
||||
이 설정은 `main` 에이전트에 대해 플러그인을 켜고, 기본적으로 다이렉트 메시지 스타일 세션으로 범위를 제한하며, 먼저 현재 세션 모델을 상속하도록 하고, 명시적이거나 상속된 모델을 사용할 수 없는 경우에만 설정된 폴백 모델을 사용합니다.
|
||||
|
||||
그다음 게이트웨이를 다시 시작하세요:
|
||||
그다음 게이트웨이를 다시 시작하세요.
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
대화에서 실시간으로 확인하려면:
|
||||
대화에서 실시간으로 확인하려면 다음을 사용하세요.
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
@ -66,13 +66,13 @@ openclaw gateway
|
||||
|
||||
## 활성 메모리 켜기
|
||||
|
||||
가장 안전한 설정은 다음과 같습니다:
|
||||
가장 안전한 설정은 다음과 같습니다.
|
||||
|
||||
1. 플러그인 활성화
|
||||
2. 하나의 대화형 에이전트 지정
|
||||
3. 조정하는 동안에만 로깅 유지
|
||||
1. 플러그인을 활성화합니다
|
||||
2. 하나의 대화형 에이전트를 대상으로 지정합니다
|
||||
3. 동작을 조정하는 동안에만 로깅을 켜 둡니다
|
||||
|
||||
`openclaw.json`에서 다음으로 시작하세요:
|
||||
`openclaw.json`에서 다음 설정으로 시작하세요.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -83,7 +83,7 @@ openclaw gateway
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
modelFallback: "google/gemini-3-flash",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
@ -97,29 +97,29 @@ openclaw gateway
|
||||
}
|
||||
```
|
||||
|
||||
그다음 게이트웨이를 다시 시작하세요:
|
||||
그다음 게이트웨이를 다시 시작하세요.
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
이 의미는 다음과 같습니다:
|
||||
이 설정의 의미는 다음과 같습니다.
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` 는 플러그인을 켭니다
|
||||
- `config.agents: ["main"]` 는 `main` 에이전트만 활성 메모리에 참여시킵니다
|
||||
- `config.allowedChatTypes: ["direct"]` 는 기본적으로 직접 메시지 스타일 세션에서만 활성 메모리가 실행되도록 유지합니다
|
||||
- `config.model` 이 설정되지 않은 경우, 활성 메모리는 먼저 현재 세션 모델을 상속합니다
|
||||
- `config.modelFallbackPolicy: "default-remote"` 는 명시적이거나 상속된 모델을 사용할 수 없을 때 기본값으로 내장 원격 대체를 유지합니다
|
||||
- `config.promptStyle: "balanced"` 는 `recent` 모드에 대한 기본 범용 프롬프트 스타일을 사용합니다
|
||||
- 활성 메모리는 여전히 적격한 대화형 지속 채팅 세션에서만 실행됩니다
|
||||
- `plugins.entries.active-memory.enabled: true`는 플러그인을 켭니다
|
||||
- `config.agents: ["main"]`는 `main` 에이전트만 활성 메모리를 사용하도록 설정합니다
|
||||
- `config.allowedChatTypes: ["direct"]`는 기본적으로 다이렉트 메시지 스타일 세션에서만 활성 메모리가 실행되도록 합니다
|
||||
- `config.model`이 설정되지 않은 경우, 활성 메모리는 먼저 현재 세션 모델을 상속합니다
|
||||
- `config.modelFallback`은 회상을 위한 사용자 지정 폴백 provider/model을 선택적으로 제공합니다
|
||||
- `config.promptStyle: "balanced"`는 `recent` 모드에 대한 기본 범용 프롬프트 스타일을 사용합니다
|
||||
- 활성 메모리는 여전히 적격한 대화형 영구 채팅 세션에서만 실행됩니다
|
||||
|
||||
## 확인 방법
|
||||
## 확인하는 방법
|
||||
|
||||
활성 메모리는 모델에 숨겨진 시스템 컨텍스트를 주입합니다. 클라이언트에 원시 `<active_memory_plugin>...</active_memory_plugin>` 태그를 노출하지는 않습니다.
|
||||
활성 메모리는 모델에 숨겨진 시스템 컨텍스트를 주입합니다. 원시 `<active_memory_plugin>...</active_memory_plugin>` 태그를 클라이언트에 노출하지는 않습니다.
|
||||
|
||||
## 세션 토글
|
||||
|
||||
설정을 수정하지 않고 현재 채팅 세션에서 활성 메모리를 일시 중지하거나 다시 시작하려면 플러그인 명령을 사용하세요:
|
||||
구성을 수정하지 않고 현재 채팅 세션에서 활성 메모리를 일시 중지하거나 다시 시작하려면 플러그인 명령을 사용하세요.
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
@ -127,9 +127,10 @@ openclaw gateway
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
이것은 세션 범위 설정입니다. `plugins.entries.active-memory.enabled`, 에이전트 대상 지정, 기타 전역 설정은 변경하지 않습니다.
|
||||
이 설정은 세션 범위에만 적용됩니다.
|
||||
`plugins.entries.active-memory.enabled`, 에이전트 대상 지정 또는 기타 전역 구성은 변경하지 않습니다.
|
||||
|
||||
명령이 설정을 기록하고 모든 세션에 대해 활성 메모리를 일시 중지하거나 다시 시작하게 하려면, 명시적 전역 형식을 사용하세요:
|
||||
명령으로 구성을 기록하고 모든 세션에서 활성 메모리를 일시 중지하거나 다시 시작하려면 명시적인 전역 형식을 사용하세요.
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
@ -137,22 +138,23 @@ openclaw gateway
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
전역 형식은 `plugins.entries.active-memory.config.enabled` 를 기록합니다. 나중에 명령으로 활성 메모리를 다시 켤 수 있도록 `plugins.entries.active-memory.enabled` 는 켜진 상태로 둡니다.
|
||||
전역 형식은 `plugins.entries.active-memory.config.enabled`를 기록합니다.
|
||||
나중에 활성 메모리를 다시 켤 수 있도록 명령을 계속 사용할 수 있게, `plugins.entries.active-memory.enabled`는 켜 둡니다.
|
||||
|
||||
실시간 세션에서 활성 메모리가 무엇을 하는지 보고 싶다면, 해당 세션에서 상세 모드를 켜세요:
|
||||
실시간 세션에서 활성 메모리가 무엇을 하고 있는지 보고 싶다면, 해당 세션에서 상세 모드를 켜세요.
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
상세 모드가 활성화되면 OpenClaw는 다음을 표시할 수 있습니다:
|
||||
상세 모드가 활성화되면 OpenClaw는 다음을 표시할 수 있습니다.
|
||||
|
||||
- `Active Memory: ok 842ms recent 34 chars` 같은 활성 메모리 상태 줄
|
||||
- `Active Memory Debug: Lemon pepper wings with blue cheese.` 같은 읽기 쉬운 디버그 요약
|
||||
- `Active Memory: ok 842ms recent 34 chars`와 같은 활성 메모리 상태 줄
|
||||
- `Active Memory Debug: Lemon pepper wings with blue cheese.`와 같은 읽기 쉬운 디버그 요약
|
||||
|
||||
이 줄들은 숨겨진 시스템 컨텍스트를 제공하는 동일한 활성 메모리 패스에서 파생되지만, 원시 프롬프트 마크업을 노출하는 대신 사람이 읽기 쉬운 형식으로 표시됩니다.
|
||||
이 줄들은 숨겨진 시스템 컨텍스트에 공급되는 것과 동일한 활성 메모리 패스에서 파생되지만, 원시 프롬프트 마크업을 노출하는 대신 사람이 읽기 쉬운 형식으로 표시됩니다.
|
||||
|
||||
기본적으로 차단 메모리 서브 에이전트 기록은 일시적이며 실행이 완료되면 삭제됩니다.
|
||||
기본적으로 차단형 메모리 서브 에이전트 기록은 임시이며 실행이 완료되면 삭제됩니다.
|
||||
|
||||
예시 흐름:
|
||||
|
||||
@ -172,16 +174,16 @@ what wings should i order?
|
||||
|
||||
## 실행 시점
|
||||
|
||||
활성 메모리는 두 가지 게이트를 사용합니다:
|
||||
활성 메모리는 두 가지 게이트를 사용합니다.
|
||||
|
||||
1. **설정 옵트인**
|
||||
플러그인이 활성화되어 있어야 하며, 현재 에이전트 id가
|
||||
`plugins.entries.active-memory.config.agents` 에 포함되어 있어야 합니다.
|
||||
2. **엄격한 런타임 적격성**
|
||||
1. **구성 옵트인**
|
||||
플러그인이 활성화되어 있어야 하며, 현재 에이전트 ID가
|
||||
`plugins.entries.active-memory.config.agents`에 포함되어 있어야 합니다.
|
||||
2. **엄격한 런타임 적격성**
|
||||
활성화되어 있고 대상으로 지정되었더라도, 활성 메모리는 적격한
|
||||
대화형 지속 채팅 세션에서만 실행됩니다.
|
||||
대화형 영구 채팅 세션에서만 실행됩니다.
|
||||
|
||||
실제 규칙은 다음과 같습니다:
|
||||
실제 규칙은 다음과 같습니다.
|
||||
|
||||
```text
|
||||
plugin enabled
|
||||
@ -195,19 +197,19 @@ eligible interactive persistent chat session
|
||||
active memory runs
|
||||
```
|
||||
|
||||
이 중 하나라도 실패하면 활성 메모리는 실행되지 않습니다.
|
||||
이 조건 중 하나라도 실패하면 활성 메모리는 실행되지 않습니다.
|
||||
|
||||
## 세션 유형
|
||||
|
||||
`config.allowedChatTypes` 는 어떤 종류의 대화에서 활성 메모리를 아예 실행할 수 있는지를 제어합니다.
|
||||
`config.allowedChatTypes`는 어떤 종류의 대화에서 Active Memory를 아예 실행할 수 있는지를 제어합니다.
|
||||
|
||||
기본값은 다음과 같습니다:
|
||||
기본값은 다음과 같습니다.
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
즉, 활성 메모리는 기본적으로 직접 메시지 스타일 세션에서 실행되지만, 그룹이나 채널 세션에서는 명시적으로 참여시키지 않는 한 실행되지 않습니다.
|
||||
즉, Active Memory는 기본적으로 다이렉트 메시지 스타일 세션에서 실행되지만, 그룹 또는 채널 세션에서는 명시적으로 옵트인하지 않는 한 실행되지 않습니다.
|
||||
|
||||
예시:
|
||||
|
||||
@ -227,39 +229,39 @@ allowedChatTypes: ["direct", "group", "channel"]
|
||||
|
||||
활성 메모리는 플랫폼 전반의 추론 기능이 아니라 대화 강화 기능입니다.
|
||||
|
||||
| Surface | 활성 메모리 실행 여부 |
|
||||
| ------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| Control UI / 웹 채팅 지속 세션 | 예, 플러그인이 활성화되어 있고 에이전트가 지정된 경우 |
|
||||
| 동일한 지속 채팅 경로의 다른 대화형 채널 세션 | 예, 플러그인이 활성화되어 있고 에이전트가 지정된 경우 |
|
||||
| 헤드리스 단발 실행 | 아니요 |
|
||||
| 하트비트/백그라운드 실행 | 아니요 |
|
||||
| 일반 내부 `agent-command` 경로 | 아니요 |
|
||||
| 서브 에이전트/내부 헬퍼 실행 | 아니요 |
|
||||
| Surface | 활성 메모리 실행 여부 |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Control UI / 웹 채팅 영구 세션 | 예, 플러그인이 활성화되어 있고 에이전트가 대상이면 실행 |
|
||||
| 동일한 영구 채팅 경로의 다른 대화형 채널 세션 | 예, 플러그인이 활성화되어 있고 에이전트가 대상이면 실행 |
|
||||
| 헤드리스 일회성 실행 | 아니요 |
|
||||
| 하트비트/백그라운드 실행 | 아니요 |
|
||||
| 일반적인 내부 `agent-command` 경로 | 아니요 |
|
||||
| 서브 에이전트/내부 헬퍼 실행 | 아니요 |
|
||||
|
||||
## 사용해야 하는 이유
|
||||
## 사용하는 이유
|
||||
|
||||
다음과 같은 경우 활성 메모리를 사용하세요:
|
||||
활성 메모리는 다음과 같은 경우에 사용하세요.
|
||||
|
||||
- 세션이 지속적이고 사용자 대상일 때
|
||||
- 세션이 영구적이고 사용자 대상일 때
|
||||
- 에이전트가 검색할 만한 의미 있는 장기 메모리를 가지고 있을 때
|
||||
- 원시 프롬프트 결정성보다 연속성과 개인화가 더 중요할 때
|
||||
- 순수한 프롬프트 결정성보다 연속성과 개인화가 더 중요할 때
|
||||
|
||||
특히 다음에 잘 맞습니다:
|
||||
특히 다음에 잘 맞습니다.
|
||||
|
||||
- 안정적인 선호
|
||||
- 반복되는 습관
|
||||
- 자연스럽게 드러나야 하는 장기 사용자 컨텍스트
|
||||
|
||||
다음에는 적합하지 않습니다:
|
||||
다음에는 적합하지 않습니다.
|
||||
|
||||
- 자동화
|
||||
- 내부 작업자
|
||||
- 단발성 API 작업
|
||||
- 숨겨진 개인화가 놀랍게 느껴질 수 있는 위치
|
||||
- 내부 워커
|
||||
- 일회성 API 작업
|
||||
- 숨겨진 개인화가 놀랍게 느껴질 수 있는 곳
|
||||
|
||||
## 작동 방식
|
||||
|
||||
런타임 형태는 다음과 같습니다:
|
||||
런타임 구조는 다음과 같습니다.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@ -270,31 +272,31 @@ flowchart LR
|
||||
I --> M["Main Reply"]
|
||||
```
|
||||
|
||||
차단 메모리 서브 에이전트는 다음만 사용할 수 있습니다:
|
||||
차단형 메모리 서브 에이전트는 다음만 사용할 수 있습니다.
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
연결이 약하면 `NONE` 을 반환해야 합니다.
|
||||
연결 상태가 좋지 않으면 `NONE`을 반환해야 합니다.
|
||||
|
||||
## 쿼리 모드
|
||||
|
||||
`config.queryMode` 는 차단 메모리 서브 에이전트가 얼마나 많은 대화를 볼 수 있는지를 제어합니다.
|
||||
`config.queryMode`는 차단형 메모리 서브 에이전트가 얼마나 많은 대화를 보는지를 제어합니다.
|
||||
|
||||
## 프롬프트 스타일
|
||||
|
||||
`config.promptStyle` 는 차단 메모리 서브 에이전트가 메모리를 반환할지 결정할 때 얼마나 적극적이거나 엄격할지를 제어합니다.
|
||||
`config.promptStyle`은 차단형 메모리 서브 에이전트가 메모리를 반환할지 결정할 때 얼마나 적극적이거나 엄격할지를 제어합니다.
|
||||
|
||||
사용 가능한 스타일:
|
||||
|
||||
- `balanced`: `recent` 모드용 범용 기본값
|
||||
- `strict`: 가장 덜 적극적이며, 주변 컨텍스트의 영향을 매우 적게 원할 때 가장 적합
|
||||
- `contextual`: 가장 연속성 친화적이며, 대화 기록이 더 중요할 때 가장 적합
|
||||
- `recall-heavy`: 약하지만 여전히 그럴듯한 일치에도 메모리를 더 잘 노출함
|
||||
- `precision-heavy`: 일치가 명확하지 않으면 `NONE` 을 강하게 선호함
|
||||
- `preference-only`: 즐겨찾기, 습관, 루틴, 취향, 반복되는 개인 사실에 최적화됨
|
||||
- `balanced`: `recent` 모드를 위한 범용 기본값
|
||||
- `strict`: 가장 덜 적극적이며, 주변 컨텍스트의 영향이 매우 적기를 원할 때 가장 적합
|
||||
- `contextual`: 연속성 친화성이 가장 높으며, 대화 기록의 중요도가 더 커야 할 때 가장 적합
|
||||
- `recall-heavy`: 약하지만 여전히 그럴듯한 일치에도 메모리를 더 기꺼이 드러냄
|
||||
- `precision-heavy`: 일치가 명확하지 않으면 공격적으로 `NONE`을 선호
|
||||
- `preference-only`: 즐겨 찾기, 습관, 루틴, 취향, 반복되는 개인 사실에 최적화
|
||||
|
||||
`config.promptStyle` 이 설정되지 않은 경우의 기본 매핑:
|
||||
`config.promptStyle`이 설정되지 않은 경우의 기본 매핑:
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
@ -302,7 +304,7 @@ recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
`config.promptStyle` 을 명시적으로 설정하면 그 재정의가 우선합니다.
|
||||
`config.promptStyle`을 명시적으로 설정하면 그 재정의가 우선합니다.
|
||||
|
||||
예시:
|
||||
|
||||
@ -310,38 +312,34 @@ full -> contextual
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## 모델 대체 정책
|
||||
## 모델 폴백 정책
|
||||
|
||||
`config.model` 이 설정되지 않은 경우, 활성 메모리는 다음 순서로 모델을 확인하려고 시도합니다:
|
||||
`config.model`이 설정되지 않은 경우, Active Memory는 다음 순서로 모델을 확인하려고 시도합니다.
|
||||
|
||||
```text
|
||||
explicit plugin model
|
||||
-> current session model
|
||||
-> agent primary model
|
||||
-> optional built-in remote fallback
|
||||
-> optional configured fallback model
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` 는 마지막 단계를 제어합니다.
|
||||
`config.modelFallback`은 설정된 폴백 단계만 제어합니다.
|
||||
|
||||
기본값:
|
||||
선택적 사용자 지정 폴백:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
modelFallback: "google/gemini-3-flash"
|
||||
```
|
||||
|
||||
다른 옵션:
|
||||
명시적 모델, 상속 모델 또는 설정된 폴백 모델이 모두 확인되지 않으면, Active Memory는 해당 턴의 회상을 건너뜁니다.
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
`config.modelFallbackPolicy`는 이전 구성과의 호환성을 위한 더 이상 사용되지 않는 필드로만 유지됩니다. 더는 런타임 동작을 변경하지 않습니다.
|
||||
|
||||
명시적이거나 상속된 모델을 사용할 수 없을 때 내장 원격 기본값으로 대체하는 대신 활성 메모리가 회상을 건너뛰게 하려면 `resolved-only` 를 사용하세요.
|
||||
## 고급 이스케이프 해치
|
||||
|
||||
## 고급 탈출구
|
||||
이 옵션들은 의도적으로 권장 설정의 일부가 아닙니다.
|
||||
|
||||
이 옵션들은 의도적으로 권장 설정에 포함되지 않습니다.
|
||||
|
||||
`config.thinking` 은 차단 메모리 서브 에이전트의 사고 수준을 재정의할 수 있습니다:
|
||||
`config.thinking`은 차단형 메모리 서브 에이전트의 thinking 수준을 재정의할 수 있습니다.
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
@ -353,31 +351,31 @@ thinking: "medium"
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
기본적으로 이것을 활성화하지 마세요. 활성 메모리는 응답 경로에서 실행되므로 추가 사고 시간은 사용자에게 보이는 지연 시간을 직접 증가시킵니다.
|
||||
기본적으로는 이 기능을 활성화하지 마세요. Active Memory는 응답 경로에서 실행되므로, thinking 시간이 늘어나면 사용자에게 보이는 지연 시간이 직접 증가합니다.
|
||||
|
||||
`config.promptAppend` 는 기본 활성 메모리 프롬프트 뒤와 대화 컨텍스트 앞에 추가 운영자 지침을 더합니다:
|
||||
`config.promptAppend`는 기본 Active Memory 프롬프트 뒤와 대화 컨텍스트 앞에 추가 운영자 지침을 덧붙입니다.
|
||||
|
||||
```json5
|
||||
promptAppend: "Prefer stable long-term preferences over one-off events."
|
||||
```
|
||||
|
||||
`config.promptOverride` 는 기본 활성 메모리 프롬프트를 대체합니다. OpenClaw는 그 뒤에 대화 컨텍스트를 계속 추가합니다:
|
||||
`config.promptOverride`는 기본 Active Memory 프롬프트를 대체합니다. OpenClaw는 그 뒤에 여전히 대화 컨텍스트를 추가합니다.
|
||||
|
||||
```json5
|
||||
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
|
||||
```
|
||||
|
||||
의도적으로 다른 회상 계약을 테스트하는 경우가 아니라면 프롬프트 사용자 지정은 권장되지 않습니다. 기본 프롬프트는 메인 모델에 대해 `NONE` 또는 간결한 사용자 사실 컨텍스트를 반환하도록 조정되어 있습니다.
|
||||
의도적으로 다른 회상 계약을 테스트하는 경우가 아니라면 프롬프트 사용자 지정은 권장되지 않습니다. 기본 프롬프트는 `NONE` 또는 주 모델을 위한 간결한 사용자 사실 컨텍스트를 반환하도록 조정되어 있습니다.
|
||||
|
||||
### `message`
|
||||
|
||||
가장 최근 사용자 메시지만 전송됩니다.
|
||||
가장 최근의 사용자 메시지만 전송됩니다.
|
||||
|
||||
```text
|
||||
Latest user message only
|
||||
```
|
||||
|
||||
다음과 같은 경우 사용하세요:
|
||||
다음과 같은 경우에 사용하세요.
|
||||
|
||||
- 가장 빠른 동작을 원할 때
|
||||
- 안정적인 선호 회상에 가장 강한 편향을 원할 때
|
||||
@ -385,11 +383,11 @@ Latest user message only
|
||||
|
||||
권장 타임아웃:
|
||||
|
||||
- `3000` ~ `5000` ms 정도로 시작
|
||||
- `3000`~`5000`ms 정도에서 시작
|
||||
|
||||
### `recent`
|
||||
|
||||
가장 최근 사용자 메시지와 최근 대화의 작은 꼬리 부분이 함께 전송됩니다.
|
||||
가장 최근의 사용자 메시지와 최근의 짧은 대화 꼬리가 함께 전송됩니다.
|
||||
|
||||
```text
|
||||
Recent conversation tail:
|
||||
@ -401,18 +399,18 @@ Latest user message:
|
||||
...
|
||||
```
|
||||
|
||||
다음과 같은 경우 사용하세요:
|
||||
다음과 같은 경우에 사용하세요.
|
||||
|
||||
- 속도와 대화 기반 맥락 사이에서 더 나은 균형을 원할 때
|
||||
- 후속 질문이 최근 몇 턴에 자주 의존할 때
|
||||
- 속도와 대화적 문맥 고정 사이에서 더 나은 균형을 원할 때
|
||||
- 후속 질문이 마지막 몇 턴에 자주 의존할 때
|
||||
|
||||
권장 타임아웃:
|
||||
|
||||
- `15000` ms 정도로 시작
|
||||
- `15000`ms 정도에서 시작
|
||||
|
||||
### `full`
|
||||
|
||||
전체 대화가 차단 메모리 서브 에이전트로 전송됩니다.
|
||||
전체 대화가 차단형 메모리 서브 에이전트에 전송됩니다.
|
||||
|
||||
```text
|
||||
Full conversation context:
|
||||
@ -422,33 +420,33 @@ user: ...
|
||||
...
|
||||
```
|
||||
|
||||
다음과 같은 경우 사용하세요:
|
||||
다음과 같은 경우에 사용하세요.
|
||||
|
||||
- 지연 시간보다 가장 강한 회상 품질이 더 중요할 때
|
||||
- 대화에 스레드의 훨씬 앞부분에 있는 중요한 설정이 포함되어 있을 때
|
||||
- 대화에 스레드 앞부분의 중요한 설정이 포함되어 있을 때
|
||||
|
||||
권장 타임아웃:
|
||||
|
||||
- `message` 또는 `recent` 보다 상당히 늘리세요
|
||||
- 스레드 크기에 따라 `15000` ms 이상으로 시작하세요
|
||||
- `message` 또는 `recent`보다 충분히 크게 늘리세요
|
||||
- 스레드 크기에 따라 `15000`ms 이상에서 시작하세요
|
||||
|
||||
일반적으로 타임아웃은 컨텍스트 크기에 따라 증가해야 합니다:
|
||||
일반적으로 타임아웃은 컨텍스트 크기가 커질수록 늘어나야 합니다.
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## 기록 지속성
|
||||
## 기록 영속성
|
||||
|
||||
활성 메모리 차단 메모리 서브 에이전트 실행은 차단 메모리 서브 에이전트 호출 중 실제 `session.jsonl` 기록을 생성합니다.
|
||||
활성 메모리 차단형 메모리 서브 에이전트 실행은 차단형 메모리 서브 에이전트 호출 중 실제 `session.jsonl` 기록을 생성합니다.
|
||||
|
||||
기본적으로 이 기록은 일시적입니다:
|
||||
기본적으로 이 기록은 임시입니다:
|
||||
|
||||
- 임시 디렉터리에 기록됩니다
|
||||
- 차단 메모리 서브 에이전트 실행에만 사용됩니다
|
||||
- 실행이 끝나면 즉시 삭제됩니다
|
||||
- 차단형 메모리 서브 에이전트 실행에만 사용됩니다
|
||||
- 실행이 끝나는 즉시 삭제됩니다
|
||||
|
||||
디버깅이나 검토를 위해 해당 차단 메모리 서브 에이전트 기록을 디스크에 유지하고 싶다면, 지속성을 명시적으로 켜세요:
|
||||
디버깅이나 검토를 위해 이러한 차단형 메모리 서브 에이전트 기록을 디스크에 유지하려면 영속성을 명시적으로 켜세요.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -467,62 +465,62 @@ message < recent < full
|
||||
}
|
||||
```
|
||||
|
||||
활성화되면 활성 메모리는 기록을 메인 사용자 대화 기록 경로가 아니라 대상 에이전트의 세션 폴더 아래 별도 디렉터리에 저장합니다.
|
||||
활성화되면 활성 메모리는 주 사용자 대화 기록 경로가 아니라 대상 에이전트의 세션 폴더 아래 별도의 디렉터리에 기록을 저장합니다.
|
||||
|
||||
기본 레이아웃은 개념적으로 다음과 같습니다:
|
||||
기본 레이아웃의 개념은 다음과 같습니다.
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
상대 하위 디렉터리는 `config.transcriptDir` 로 변경할 수 있습니다.
|
||||
상대 하위 디렉터리는 `config.transcriptDir`로 변경할 수 있습니다.
|
||||
|
||||
다음 사항에 주의해서 사용하세요:
|
||||
다음 사항에 주의해서 사용하세요.
|
||||
|
||||
- 바쁜 세션에서는 차단 메모리 서브 에이전트 기록이 빠르게 누적될 수 있습니다
|
||||
- 바쁜 세션에서는 차단형 메모리 서브 에이전트 기록이 빠르게 쌓일 수 있습니다
|
||||
- `full` 쿼리 모드는 많은 대화 컨텍스트를 중복할 수 있습니다
|
||||
- 이 기록에는 숨겨진 프롬프트 컨텍스트와 회상된 메모리가 포함됩니다
|
||||
- 이러한 기록에는 숨겨진 프롬프트 컨텍스트와 회상된 메모리가 포함됩니다
|
||||
|
||||
## 설정
|
||||
## 구성
|
||||
|
||||
모든 활성 메모리 설정은 다음 아래에 있습니다:
|
||||
모든 활성 메모리 구성은 다음 경로 아래에 있습니다.
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
가장 중요한 필드는 다음과 같습니다:
|
||||
가장 중요한 필드는 다음과 같습니다.
|
||||
|
||||
| Key | Type | 의미 |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | 플러그인 자체를 활성화합니다 |
|
||||
| `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` | 활성 메모리 요약에 허용되는 최대 전체 문자 수 |
|
||||
| `config.logging` | `boolean` | 조정 중 활성 메모리 로그를 출력합니다 |
|
||||
| `config.persistTranscripts` | `boolean` | 임시 파일을 삭제하는 대신 차단 메모리 서브 에이전트 기록을 디스크에 유지합니다 |
|
||||
| `config.transcriptDir` | `string` | 에이전트 세션 폴더 아래의 상대 차단 메모리 서브 에이전트 기록 디렉터리 |
|
||||
| `enabled` | `boolean` | 플러그인 자체를 활성화합니다 |
|
||||
| `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"` | 차단형 메모리 서브 에이전트에 대한 고급 thinking 재정의; 속도를 위해 기본값은 `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` | 활성 메모리 요약에 허용되는 최대 전체 문자 수 |
|
||||
| `config.recentUserTurns` | `number` | `queryMode` 가 `recent` 일 때 포함할 이전 사용자 턴 수 |
|
||||
| `config.recentAssistantTurns` | `number` | `queryMode` 가 `recent` 일 때 포함할 이전 어시스턴트 턴 수 |
|
||||
| `config.recentUserChars` | `number` | 최근 사용자 턴당 최대 문자 수 |
|
||||
| `config.recentAssistantChars` | `number` | 최근 어시스턴트 턴당 최대 문자 수 |
|
||||
| `config.cacheTtlMs` | `number` | 반복되는 동일 쿼리에 대한 캐시 재사용 |
|
||||
| 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` 로 시작하세요.
|
||||
`recent`로 시작하세요.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -544,36 +542,36 @@ plugins.entries.active-memory
|
||||
}
|
||||
```
|
||||
|
||||
조정 중 실시간 동작을 확인하고 싶다면, 별도의 active-memory 디버그 명령을 찾는 대신 세션에서 `/verbose on` 을 사용하세요.
|
||||
조정 중에 실시간 동작을 확인하려면 별도의 active-memory 디버그 명령을 찾는 대신 세션에서 `/verbose on`을 사용하세요.
|
||||
|
||||
그다음 다음으로 이동하세요:
|
||||
그다음 다음으로 이동하세요.
|
||||
|
||||
- 더 낮은 지연 시간을 원하면 `message`
|
||||
- 더 느린 차단 메모리 서브 에이전트의 대가로 추가 컨텍스트가 가치 있다고 판단되면 `full`
|
||||
- 더 낮은 지연 시간이 필요하면 `message`
|
||||
- 더 느린 차단형 메모리 서브 에이전트를 감수할 만큼 추가 컨텍스트의 가치가 있다고 판단되면 `full`
|
||||
|
||||
## 디버깅
|
||||
|
||||
예상한 위치에서 활성 메모리가 나타나지 않는다면:
|
||||
예상한 위치에서 활성 메모리가 표시되지 않는다면 다음을 확인하세요.
|
||||
|
||||
1. `plugins.entries.active-memory.enabled` 아래에서 플러그인이 활성화되어 있는지 확인하세요.
|
||||
2. 현재 에이전트 id가 `config.agents` 에 나열되어 있는지 확인하세요.
|
||||
3. 대화형 지속 채팅 세션을 통해 테스트하고 있는지 확인하세요.
|
||||
4. `config.logging: true` 를 켜고 게이트웨이 로그를 확인하세요.
|
||||
5. `openclaw memory status --deep` 로 메모리 검색 자체가 작동하는지 확인하세요.
|
||||
1. `plugins.entries.active-memory.enabled` 아래에서 플러그인이 활성화되어 있는지 확인합니다.
|
||||
2. 현재 에이전트 ID가 `config.agents`에 나열되어 있는지 확인합니다.
|
||||
3. 대화형 영구 채팅 세션을 통해 테스트하고 있는지 확인합니다.
|
||||
4. `config.logging: true`를 켜고 게이트웨이 로그를 확인합니다.
|
||||
5. `openclaw memory status --deep`로 메모리 검색 자체가 작동하는지 확인합니다.
|
||||
|
||||
메모리 적중이 너무 시끄럽다면 다음을 더 엄격하게 조정하세요:
|
||||
메모리 히트가 너무 잡음이 많다면 다음을 더 엄격하게 조정하세요.
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
활성 메모리가 너무 느리다면:
|
||||
활성 메모리가 너무 느리다면 다음을 조정하세요.
|
||||
|
||||
- `queryMode` 낮추기
|
||||
- `timeoutMs` 낮추기
|
||||
- 최근 턴 수 줄이기
|
||||
- 턴당 문자 제한 줄이기
|
||||
- `queryMode`를 낮춥니다
|
||||
- `timeoutMs`를 낮춥니다
|
||||
- 최근 턴 수를 줄입니다
|
||||
- 턴당 문자 제한을 줄입니다
|
||||
|
||||
## 관련 페이지
|
||||
|
||||
- [메모리 검색](/ko/concepts/memory-search)
|
||||
- [메모리 설정 참조](/ko/reference/memory-config)
|
||||
- [메모리 구성 참조](/ko/reference/memory-config)
|
||||
- [Plugin SDK 설정](/ko/plugins/sdk-setup)
|
||||
|
||||
@ -1,81 +1,81 @@
|
||||
---
|
||||
read_when:
|
||||
- 시스템 프롬프트 텍스트, 도구 목록 또는 시간/하트비트 섹션을 편집할 때
|
||||
- 워크스페이스 부트스트랩 또는 Skills 주입 동작을 변경할 때
|
||||
summary: OpenClaw 시스템 프롬프트에 포함되는 내용과 조립 방식
|
||||
- 시스템 프롬프트 텍스트, 도구 목록 또는 시간/하트비트 섹션 편집하기
|
||||
- 워크스페이스 부트스트랩 또는 Skills 주입 동작 변경하기
|
||||
summary: OpenClaw 시스템 프롬프트에 무엇이 포함되는지와 그것이 어떻게 조합되는지
|
||||
title: 시스템 프롬프트
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:14:27Z"
|
||||
generated_at: "2026-04-12T05:58:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a
|
||||
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 시스템 프롬프트
|
||||
|
||||
OpenClaw는 각 에이전트 실행마다 맞춤형 시스템 프롬프트를 생성합니다. 이 프롬프트는 **OpenClaw 소유**이며 pi-coding-agent 기본 프롬프트를 사용하지 않습니다.
|
||||
OpenClaw는 모든 에이전트 실행마다 맞춤형 시스템 프롬프트를 구성합니다. 이 프롬프트는 **OpenClaw 소유**이며 pi-coding-agent 기본 프롬프트를 사용하지 않습니다.
|
||||
|
||||
프롬프트는 OpenClaw가 조립하여 각 에이전트 실행에 주입합니다.
|
||||
프롬프트는 OpenClaw가 조합하여 각 에이전트 실행에 주입합니다.
|
||||
|
||||
프로바이더 plugin은 전체 OpenClaw 소유 프롬프트를 대체하지 않고도 캐시 인식 프롬프트 가이드를 제공할 수 있습니다. 프로바이더 런타임은 다음을 수행할 수 있습니다.
|
||||
프로바이더 플러그인은 전체 OpenClaw 소유 프롬프트를 대체하지 않고도 캐시 인식 프롬프트 가이드를 제공할 수 있습니다. 프로바이더 런타임은 다음을 수행할 수 있습니다.
|
||||
|
||||
- 이름이 지정된 소수의 핵심 섹션(`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)을 교체
|
||||
- 소수의 이름 있는 코어 섹션(`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`) 교체
|
||||
- 프롬프트 캐시 경계 위에 **안정적인 접두사** 주입
|
||||
- 프롬프트 캐시 경계 아래에 **동적 접미사** 주입
|
||||
- 프롬프트 캐시 경계 아래에 **동적인 접미사** 주입
|
||||
|
||||
모델 계열별 튜닝에는 프로바이더 소유 기여를 사용하세요. 레거시
|
||||
`before_prompt_build` 프롬프트 변경은 호환성 유지 또는 진정으로 전역적인 프롬프트
|
||||
변경에만 사용하고, 일반적인 프로바이더 동작에는 사용하지 마세요.
|
||||
모델 계열별 튜닝에는 프로바이더 소유 기여를 사용하세요. 일반적인 프로바이더 동작에는 레거시
|
||||
`before_prompt_build` 프롬프트 변경이 아니라, 호환성이나 정말 전역적인 프롬프트
|
||||
변경에만 그것을 사용하세요.
|
||||
|
||||
## 구조
|
||||
|
||||
프롬프트는 의도적으로 간결하며 고정된 섹션을 사용합니다.
|
||||
|
||||
- **도구 사용**: 구조화된 도구의 신뢰 가능한 정보원에 대한 상기와 런타임 도구 사용 가이드.
|
||||
- **안전**: 권력 추구 행동이나 감독 우회를 피하기 위한 짧은 가드레일 상기.
|
||||
- **Skills**(사용 가능한 경우): 필요 시 스킬 지침을 로드하는 방법을 모델에 알려줍니다.
|
||||
- **OpenClaw 자체 업데이트**: `config.schema.lookup`으로 구성을 안전하게 검사하고, `config.patch`로 구성을 패치하고, `config.apply`로 전체 구성을 교체하며, 명시적인 사용자 요청이 있을 때만 `update.run`을 실행하는 방법. 소유자 전용 `gateway` 도구도 보호된 exec 경로로 정규화되는 레거시 `tools.bash.*` 별칭을 포함해 `tools.exec.ask` / `tools.exec.security`를 다시 쓰는 것을 거부합니다.
|
||||
- **도구 사용**: 구조화된 도구 source-of-truth 알림과 런타임 도구 사용 가이드.
|
||||
- **안전**: 권력 추구 행동이나 감독 우회를 피하기 위한 짧은 가드레일 알림.
|
||||
- **Skills** (사용 가능한 경우): 필요할 때 스킬 지침을 로드하는 방법을 모델에 알려줍니다.
|
||||
- **OpenClaw 셀프 업데이트**: `config.schema.lookup`으로 설정을 안전하게 검사하고, `config.patch`로 설정을 패치하고, `config.apply`로 전체 설정을 교체하고, 명시적인 사용자 요청이 있을 때만 `update.run`을 실행하는 방법입니다. owner-only `gateway` 도구는 `tools.exec.ask` / `tools.exec.security` 재작성도 거부하며, 여기에는 해당 보호된 exec 경로로 정규화되는 레거시 `tools.bash.*` 별칭도 포함됩니다.
|
||||
- **워크스페이스**: 작업 디렉터리(`agents.defaults.workspace`).
|
||||
- **문서**: OpenClaw 문서의 로컬 경로(repo 또는 npm package)와 읽어야 하는 시점.
|
||||
- **워크스페이스 파일(주입됨)**: 아래에 부트스트랩 파일이 포함된다는 것을 나타냅니다.
|
||||
- **샌드박스**(활성화된 경우): 샌드박스 런타임, 샌드박스 경로, 권한 상승 exec 사용 가능 여부를 나타냅니다.
|
||||
- **문서**: OpenClaw 문서의 로컬 경로(리포지토리 또는 npm 패키지)와 읽어야 하는 시점.
|
||||
- **워크스페이스 파일(주입됨)**: 부트스트랩 파일이 아래에 포함된다는 것을 나타냅니다.
|
||||
- **샌드박스** (활성화된 경우): 샌드박스 런타임, 샌드박스 경로, 권한 상승 exec 사용 가능 여부를 나타냅니다.
|
||||
- **현재 날짜 및 시간**: 사용자 로컬 시간, 시간대, 시간 형식.
|
||||
- **응답 태그**: 지원되는 프로바이더용 선택적 응답 태그 구문.
|
||||
- **하트비트**: 기본 에이전트에 대해 하트비트가 활성화된 경우의 하트비트 프롬프트 및 ack 동작.
|
||||
- **런타임**: 호스트, OS, node, 모델, repo 루트(감지된 경우), thinking 수준(한 줄).
|
||||
- **하트비트**: 하트비트 프롬프트와 ack 동작, 기본 에이전트에 하트비트가 활성화되어 있을 때의 동작.
|
||||
- **런타임**: 호스트, OS, node, 리포지토리 루트(감지된 경우), 사고 수준(한 줄).
|
||||
- **추론**: 현재 가시성 수준 + /reasoning 토글 힌트.
|
||||
|
||||
도구 사용 섹션에는 장시간 실행 작업에 대한 런타임 가이드도 포함됩니다.
|
||||
도구 사용 섹션에는 장시간 실행 작업을 위한 런타임 가이드도 포함됩니다.
|
||||
|
||||
- 나중에 후속 조치가 필요한 경우(`나중에 다시 확인`, 리마인더, 반복 작업) `exec` 수면 루프, `yieldMs` 지연 트릭, 반복적인 `process` 폴링 대신 cron 사용
|
||||
- 미래의 후속 작업(`나중에 다시 확인`, 리마인더, 반복 작업)에는 `exec` sleep 루프, `yieldMs` 지연 트릭, 반복적인 `process` 폴링 대신 cron 사용
|
||||
- 지금 시작해서 백그라운드에서 계속 실행되는 명령에만 `exec` / `process` 사용
|
||||
- 자동 완료 깨우기 기능이 활성화된 경우 명령은 한 번만 시작하고, 출력이 발생하거나 실패할 때 푸시 기반 깨우기 경로에 의존
|
||||
- 자동 완료 깨우기 기능이 활성화된 경우, 명령을 한 번만 시작하고 출력이 발생하거나 실패할 때 push 기반 wake 경로에 의존
|
||||
- 실행 중인 명령을 검사해야 할 때 로그, 상태, 입력 또는 개입에는 `process` 사용
|
||||
- 작업이 더 큰 경우 `sessions_spawn`을 우선 사용. 하위 에이전트 완료는 푸시 기반이며 요청자에게 자동으로 다시 알림
|
||||
- 완료를 기다리기 위해 루프에서 `subagents list` / `sessions_list`를 폴링하지 말 것
|
||||
- 작업이 더 크면 `sessions_spawn` 선호, 서브에이전트 완료는 push 기반이며 요청자에게 자동으로 알림
|
||||
- 완료를 기다리기 위해 `subagents list` / `sessions_list`를 루프로 폴링하지 않기
|
||||
|
||||
실험적 `update_plan` 도구가 활성화된 경우, 도구 사용 섹션은 모델에 이 도구를 사소하지 않은 다단계 작업에만 사용하고, 정확히 하나의 `in_progress` 단계만 유지하며, 각 업데이트 후 전체 계획을 반복하지 말라고도 안내합니다.
|
||||
실험적 `update_plan` 도구가 활성화되면, 도구 사용 섹션은 모델에 이것을 사소하지 않은 다단계 작업에만 사용하고, 정확히 하나의 `in_progress` 단계를 유지하며, 각 업데이트 후 전체 계획을 반복하지 말라고도 지시합니다.
|
||||
|
||||
시스템 프롬프트의 안전 가드레일은 권고 사항입니다. 모델 동작을 안내하지만 정책을 강제하지는 않습니다. 강제 적용에는 도구 정책, exec 승인, 샌드박싱, 채널 허용 목록을 사용하세요. 운영자는 설계상 이를 비활성화할 수 있습니다.
|
||||
시스템 프롬프트의 안전 가드레일은 권고 사항입니다. 이는 모델 동작을 안내하지만 정책을 강제하지는 않습니다. 강제 적용에는 도구 정책, exec 승인, 샌드박싱, 채널 허용 목록을 사용하세요. 운영자는 설계상 이를 비활성화할 수 있습니다.
|
||||
|
||||
기본 승인 카드/버튼이 있는 채널에서는 이제 런타임 프롬프트가 에이전트에게 우선 그 기본 승인 UI를 사용하라고 안내합니다. 도구 결과에서 채팅 승인을 사용할 수 없거나 수동 승인이 유일한 경로라고 말하는 경우에만 수동 `/approve` 명령을 포함해야 합니다.
|
||||
네이티브 승인 카드/버튼이 있는 채널에서는 이제 런타임 프롬프트가 에이전트에게 먼저 그 네이티브 승인 UI에 의존하라고 알려줍니다. 도구 결과가 채팅 승인을 사용할 수 없다고 말하거나 수동 승인이 유일한 경로일 때만 수동 `/approve` 명령을 포함해야 합니다.
|
||||
|
||||
## 프롬프트 모드
|
||||
|
||||
OpenClaw는 하위 에이전트를 위해 더 작은 시스템 프롬프트를 렌더링할 수 있습니다. 런타임은 각 실행에 대해 `promptMode`를 설정합니다(사용자 대상 설정 아님).
|
||||
OpenClaw는 서브에이전트용으로 더 작은 시스템 프롬프트를 렌더링할 수 있습니다. 런타임은 각 실행에 대해 `promptMode`를 설정합니다(사용자 대상 설정 아님).
|
||||
|
||||
- `full`(기본값): 위의 모든 섹션을 포함합니다.
|
||||
- `minimal`: 하위 에이전트에 사용되며 **Skills**, **메모리 회상**, **OpenClaw 자체 업데이트**, **모델 별칭**, **사용자 신원**, **응답 태그**, **메시징**, **무음 응답**, **하트비트**를 생략합니다. 도구 사용, **안전**, 워크스페이스, 샌드박스, 현재 날짜 및 시간(알려진 경우), 런타임, 주입된 컨텍스트는 계속 사용할 수 있습니다.
|
||||
- `none`: 기본 신원 한 줄만 반환합니다.
|
||||
- `full` (기본값): 위의 모든 섹션을 포함합니다.
|
||||
- `minimal`: 서브에이전트에 사용되며 **Skills**, **메모리 리콜**, **OpenClaw 셀프 업데이트**, **모델 별칭**, **사용자 신원**, **응답 태그**, **메시징**, **무음 응답**, **하트비트**를 생략합니다. 도구 사용, **안전**, 워크스페이스, 샌드박스, 현재 날짜 및 시간(알려진 경우), 런타임, 주입된 컨텍스트는 계속 사용할 수 있습니다.
|
||||
- `none`: 기본 신원 줄만 반환합니다.
|
||||
|
||||
`promptMode=minimal`일 때, 추가로 주입된 프롬프트는 **그룹 채팅 컨텍스트** 대신 **하위 에이전트 컨텍스트**로 표시됩니다.
|
||||
`promptMode=minimal`일 때 추가로 주입된 프롬프트는 **그룹 채팅 컨텍스트** 대신 **서브에이전트 컨텍스트**로 레이블됩니다.
|
||||
|
||||
## 워크스페이스 부트스트랩 주입
|
||||
|
||||
부트스트랩 파일은 모델이 명시적으로 읽지 않아도 신원 및 프로필 컨텍스트를 볼 수 있도록 잘라낸 뒤 **프로젝트 컨텍스트** 아래에 추가됩니다.
|
||||
부트스트랩 파일은 모델이 명시적으로 읽지 않아도 신원과 프로필 컨텍스트를 볼 수 있도록 **프로젝트 컨텍스트** 아래에 잘려서 추가됩니다.
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -83,48 +83,47 @@ OpenClaw는 하위 에이전트를 위해 더 작은 시스템 프롬프트를
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md`(완전히 새 워크스페이스에서만)
|
||||
- `MEMORY.md`가 있으면 그것을, 없으면 소문자 대체 파일인 `memory.md`
|
||||
- `BOOTSTRAP.md` (새 워크스페이스에서만)
|
||||
- `MEMORY.md`가 있으면 그것을, 없으면 소문자 대체 파일 `memory.md`
|
||||
|
||||
이 모든 파일은 **파일별 게이트가 적용되지 않는 한** 매 턴마다 **컨텍스트 창에 주입**됩니다. 정상 실행에서는 기본 에이전트에 대해 하트비트가 비활성화되어 있거나 `agents.defaults.heartbeat.includeSystemPromptSection`이 false일 때 `HEARTBEAT.md`가 생략됩니다. 주입되는 파일은 간결하게 유지하세요. 특히 `MEMORY.md`는 시간이 지남에 따라 커질 수 있으며, 예상보다 높은 컨텍스트 사용량과 더 잦은 압축으로 이어질 수 있습니다.
|
||||
이 모든 파일은 **컨텍스트 윈도우에 주입되어** 매 턴마다 포함되며, 파일별 게이트가 적용되는 경우는 예외입니다. `HEARTBEAT.md`는 기본 에이전트에 대해 하트비트가 비활성화되어 있거나 `agents.defaults.heartbeat.includeSystemPromptSection`이 false인 일반 실행에서는 생략됩니다. 주입되는 파일은 간결하게 유지하세요. 특히 `MEMORY.md`는 시간이 지나며 커질 수 있고 예상보다 높은 컨텍스트 사용량과 더 빈번한 컴팩션을 초래할 수 있습니다.
|
||||
|
||||
> **참고:** `memory/*.md` 일별 파일은 자동으로 주입되지 않습니다. 이 파일들은 필요 시 `memory_search` 및 `memory_get` 도구를 통해 접근하므로, 모델이 명시적으로 읽지 않는 한 컨텍스트 창을 차지하지 않습니다.
|
||||
> **참고:** `memory/*.md` 일일 파일은 일반적인 부트스트랩 프로젝트 컨텍스트의 일부가 **아닙니다**. 일반 턴에서는 필요 시 `memory_search` 및 `memory_get` 도구를 통해 접근하므로, 모델이 명시적으로 읽지 않는 한 컨텍스트 윈도우를 차지하지 않습니다. 예외는 순수한 `/new` 및 `/reset` 턴입니다. 런타임은 첫 턴용 일회성 시작 컨텍스트 블록으로 최근 일일 메모리를 앞에 붙일 수 있습니다.
|
||||
|
||||
큰 파일은 마커와 함께 잘립니다. 파일당 최대 크기는
|
||||
`agents.defaults.bootstrapMaxChars`(기본값: 20000)로 제어됩니다. 파일 전체에 걸친 총 주입 부트스트랩 콘텐츠는 `agents.defaults.bootstrapTotalMaxChars`
|
||||
(기본값: 150000)로 제한됩니다. 누락된 파일은 짧은 누락 파일 마커를 주입합니다. 잘림이 발생하면 OpenClaw는 프로젝트 컨텍스트에 경고 블록을 주입할 수 있습니다. 이는
|
||||
`agents.defaults.bootstrapPromptTruncationWarning`(`off`, `once`, `always`;
|
||||
`agents.defaults.bootstrapMaxChars`(기본값: 20000)로 제어됩니다. 파일 전체에 걸친 총 주입 부트스트랩
|
||||
콘텐츠는 `agents.defaults.bootstrapTotalMaxChars`
|
||||
(기본값: 150000)로 제한됩니다. 누락된 파일은 짧은 누락 파일 마커를 주입합니다. 잘림이
|
||||
발생하면 OpenClaw는 프로젝트 컨텍스트에 경고 블록을 주입할 수 있으며, 이는
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
|
||||
기본값: `once`)로 제어합니다.
|
||||
|
||||
하위 에이전트 세션은 `AGENTS.md`와 `TOOLS.md`만 주입합니다(하위 에이전트 컨텍스트를 작게 유지하기 위해 다른 부트스트랩 파일은 걸러집니다).
|
||||
서브에이전트 세션은 `AGENTS.md`와 `TOOLS.md`만 주입합니다(서브에이전트 컨텍스트를 작게 유지하기 위해 다른 부트스트랩 파일은 필터링됨).
|
||||
|
||||
내부 훅은 `agent:bootstrap`을 통해 이 단계를 가로채 주입된 부트스트랩 파일을 변경하거나 교체할 수 있습니다(예: `SOUL.md`를 다른 페르소나로 교체).
|
||||
내부 훅은 `agent:bootstrap`을 통해 이 단계를 가로채 주입된 부트스트랩 파일을 변경하거나 교체할 수 있습니다(예: `SOUL.md`를 대체 페르소나로 교체).
|
||||
|
||||
에이전트가 덜 일반적으로 들리게 만들고 싶다면
|
||||
[SOUL.md Personality Guide](/ko/concepts/soul)부터 시작하세요.
|
||||
에이전트가 덜 일반적으로 들리게 하려면 [SOUL.md Personality Guide](/ko/concepts/soul)부터 시작하세요.
|
||||
|
||||
주입된 각 파일의 기여도(원본 대비 주입본, 잘림, 도구 스키마 오버헤드 포함)를 검사하려면 `/context list` 또는 `/context detail`을 사용하세요. 자세한 내용은 [Context](/ko/concepts/context)를 참조하세요.
|
||||
각 주입 파일이 얼마나 기여하는지(원본 대비 주입분, 잘림, 도구 스키마 오버헤드 포함) 확인하려면 `/context list` 또는 `/context detail`을 사용하세요. [Context](/ko/concepts/context)를 참고하세요.
|
||||
|
||||
## 시간 처리
|
||||
|
||||
사용자 시간대가 알려져 있으면 시스템 프롬프트에는 전용 **현재 날짜 및 시간** 섹션이 포함됩니다. 프롬프트 캐시를 안정적으로 유지하기 위해 이제 **시간대**만 포함하며(동적 시계나 시간 형식 제외) 그 외는 포함하지 않습니다.
|
||||
사용자 시간대가 알려져 있으면 시스템 프롬프트에 전용 **현재 날짜 및 시간** 섹션이 포함됩니다. 프롬프트 캐시를 안정적으로 유지하기 위해 이제 여기에 **시간대**만 포함되며(동적 시계나 시간 형식 없음) 있습니다.
|
||||
|
||||
에이전트가 현재 시간이 필요할 때는 `session_status`를 사용하세요. 상태 카드에는 타임스탬프 줄이 포함됩니다. 같은 도구로 세션별 모델 재정의를 선택적으로 설정할 수도 있습니다(`model=default`는 이를 지웁니다).
|
||||
현재 시간이 필요할 때는 `session_status`를 사용하세요. 상태 카드에는 타임스탬프 줄이 포함됩니다. 같은 도구로 세션별 모델 오버라이드도 선택적으로 설정할 수 있습니다(`model=default`로 초기화).
|
||||
|
||||
구성 항목:
|
||||
다음으로 구성합니다.
|
||||
|
||||
- `agents.defaults.userTimezone`
|
||||
- `agents.defaults.timeFormat` (`auto` | `12` | `24`)
|
||||
|
||||
전체 동작 세부 사항은 [Date & Time](/ko/date-time)을 참조하세요.
|
||||
전체 동작 세부 정보는 [날짜 및 시간](/ko/date-time)을 참고하세요.
|
||||
|
||||
## Skills
|
||||
|
||||
적격한 Skills가 있으면 OpenClaw는 각 skill의 **파일 경로**를 포함하는 간결한 **사용 가능한 Skills 목록**
|
||||
(`formatSkillsForPrompt`)을 주입합니다. 프롬프트는 모델에 나열된 위치(워크스페이스, 관리형 또는 번들)에 있는 SKILL.md를 로드하기 위해 `read`를 사용하라고 지시합니다. 적격한 Skills가 없으면 Skills 섹션은 생략됩니다.
|
||||
적격한 스킬이 있으면 OpenClaw는 각 스킬의 **파일 경로**를 포함하는 간결한 **사용 가능한 스킬 목록**(`formatSkillsForPrompt`)을 주입합니다. 프롬프트는 모델에 나열된 위치(워크스페이스, 관리형 또는 번들)의 SKILL.md를 로드하기 위해 `read`를 사용하라고 지시합니다. 적격한 스킬이 없으면 Skills 섹션은 생략됩니다.
|
||||
|
||||
적격성에는 skill 메타데이터 게이트, 런타임 환경/구성 검사, 그리고
|
||||
`agents.defaults.skills` 또는 `agents.list[].skills`가 구성된 경우의 유효 에이전트 skill 허용 목록이 포함됩니다.
|
||||
적격성에는 스킬 메타데이터 게이트, 런타임 환경/설정 검사, 그리고 `agents.defaults.skills` 또는 `agents.list[].skills`가 구성된 경우 유효 에이전트 스킬 허용 목록이 포함됩니다.
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
@ -136,9 +135,8 @@ OpenClaw는 하위 에이전트를 위해 더 작은 시스템 프롬프트를
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
이렇게 하면 기본 프롬프트를 작게 유지하면서도 대상이 명확한 skill 사용은 계속 가능하게 됩니다.
|
||||
이렇게 하면 기본 프롬프트를 작게 유지하면서도 대상 지정된 스킬 사용은 계속 가능하게 합니다.
|
||||
|
||||
## 문서
|
||||
|
||||
사용 가능한 경우 시스템 프롬프트에는 로컬 OpenClaw 문서 디렉터리(repo 워크스페이스의 `docs/` 또는 번들된 npm
|
||||
package 문서)를 가리키는 **문서** 섹션이 포함되며, 공개 미러, 소스 repo, 커뮤니티 Discord, 그리고 Skills 검색을 위한 ClawHub([https://clawhub.ai](https://clawhub.ai))도 함께 언급합니다. 프롬프트는 모델에 OpenClaw 동작, 명령, 구성 또는 아키텍처에 대해서는 먼저 로컬 문서를 참고하고, 가능하면 `openclaw status`를 직접 실행하되(접근 권한이 없을 때만 사용자에게 물어봄) 그렇게 하라고 지시합니다.
|
||||
사용 가능한 경우 시스템 프롬프트에는 로컬 OpenClaw 문서 디렉터리(리포지토리의 `docs/` 또는 번들된 npm 패키지 문서)를 가리키는 **문서** 섹션이 포함되며, 공개 미러, 소스 리포지토리, 커뮤니티 Discord, Skills 검색용 ClawHub([https://clawhub.ai](https://clawhub.ai))도 함께 안내합니다. 프롬프트는 모델에 OpenClaw 동작, 명령, 설정 또는 아키텍처에 대해서는 먼저 로컬 문서를 참고하고, 가능하면 직접 `openclaw status`를 실행하며(접근 권한이 없을 때만 사용자에게 묻고) 하라고 지시합니다.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw 플러그인을 빌드하고 있습니다
|
||||
- 플러그인 구성 스키마를 제공하거나 플러그인 유효성 검사 오류를 디버그해야 합니다
|
||||
summary: 플러그인 매니페스트 + JSON 스키마 요구사항(엄격한 구성 유효성 검사)
|
||||
- 플러그인 구성 스키마를 제공하거나 플러그인 검증 오류를 디버그해야 합니다
|
||||
summary: 플러그인 매니페스트 + JSON 스키마 요구 사항(엄격한 구성 검증)
|
||||
title: 플러그인 매니페스트
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T15:15:56Z"
|
||||
generated_at: "2026-04-12T05:58:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4
|
||||
source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,7 +17,7 @@ x-i18n:
|
||||
|
||||
이 페이지는 **네이티브 OpenClaw 플러그인 매니페스트**만을 다룹니다.
|
||||
|
||||
호환 가능한 번들 레이아웃은 [플러그인 번들](/ko/plugins/bundles)을 참고하세요.
|
||||
호환 가능한 번들 레이아웃은 [플러그인 번들](/ko/plugins/bundles)을 참조하세요.
|
||||
|
||||
호환 번들 형식은 서로 다른 매니페스트 파일을 사용합니다.
|
||||
|
||||
@ -26,31 +26,38 @@ x-i18n:
|
||||
레이아웃
|
||||
- Cursor 번들: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw는 이러한 번들 레이아웃도 자동 감지하지만, 여기에서 설명하는 `openclaw.plugin.json` 스키마를 기준으로 유효성 검사를 하지는 않습니다.
|
||||
OpenClaw는 이러한 번들 레이아웃도 자동 감지하지만, 여기에서 설명하는
|
||||
`openclaw.plugin.json` 스키마를 기준으로 검증하지는 않습니다.
|
||||
|
||||
호환 번들의 경우, OpenClaw는 현재 레이아웃이 OpenClaw 런타임 기대사항과 일치할 때 번들 메타데이터와 선언된 Skills 루트, Claude 명령 루트, Claude 번들 `settings.json` 기본값, Claude 번들 LSP 기본값, 지원되는 hook pack을 읽습니다.
|
||||
호환 번들의 경우, OpenClaw는 현재 레이아웃이 OpenClaw 런타임 기대사항과 일치하면
|
||||
번들 메타데이터와 선언된 skill 루트, Claude 명령 루트, Claude 번들 `settings.json`
|
||||
기본값, Claude 번들 LSP 기본값, 지원되는 hook pack을 읽습니다.
|
||||
|
||||
모든 네이티브 OpenClaw 플러그인은 **반드시** **플러그인 루트**에 `openclaw.plugin.json` 파일을 포함해야 합니다. OpenClaw는 이 매니페스트를 사용해 **플러그인 코드를 실행하지 않고도** 구성을 검증합니다. 매니페스트가 없거나 유효하지 않으면 플러그인 오류로 처리되며 구성 유효성 검사가 차단됩니다.
|
||||
모든 네이티브 OpenClaw 플러그인은 **플러그인 루트**에 `openclaw.plugin.json`
|
||||
파일을 반드시 포함해야 합니다. OpenClaw는 이 매니페스트를 사용해 플러그인 코드를
|
||||
**실행하지 않고도** 구성을 검증합니다. 매니페스트가 없거나 유효하지 않으면 플러그인
|
||||
오류로 처리되며 구성 검증이 차단됩니다.
|
||||
|
||||
전체 플러그인 시스템 가이드는 [플러그인](/ko/tools/plugin)을 참고하세요.
|
||||
전체 플러그인 시스템 가이드는 [플러그인](/ko/tools/plugin)을 참조하세요.
|
||||
네이티브 capability 모델과 현재 외부 호환성 가이드는
|
||||
[Capability model](/ko/plugins/architecture#public-capability-model)을 참고하세요.
|
||||
[Capability model](/ko/plugins/architecture#public-capability-model)을 참조하세요.
|
||||
|
||||
## 이 파일의 역할
|
||||
|
||||
`openclaw.plugin.json`은 OpenClaw가 플러그인 코드를 로드하기 전에 읽는 메타데이터입니다.
|
||||
`openclaw.plugin.json`은 OpenClaw가 플러그인 코드를 로드하기 전에 읽는
|
||||
메타데이터입니다.
|
||||
|
||||
다음 용도로 사용하세요.
|
||||
|
||||
- 플러그인 식별 정보
|
||||
- 구성 유효성 검사
|
||||
- 플러그인 식별자
|
||||
- 구성 검증
|
||||
- 플러그인 런타임을 부팅하지 않고도 사용할 수 있어야 하는 인증 및 온보딩 메타데이터
|
||||
- 런타임이 로드되기 전에 컨트롤 플레인 표면에서 확인할 수 있는 가벼운 활성화 힌트
|
||||
- 런타임이 로드되기 전에 설정/온보딩 표면에서 확인할 수 있는 가벼운 설정 설명자
|
||||
- 런타임이 로드되기 전에 컨트롤 플레인 표면이 검사할 수 있는 가벼운 활성화 힌트
|
||||
- 런타임이 로드되기 전에 설정/온보딩 표면이 검사할 수 있는 가벼운 설정 설명자
|
||||
- 플러그인 런타임이 로드되기 전에 확인되어야 하는 별칭 및 자동 활성화 메타데이터
|
||||
- 플러그인 런타임이 로드되기 전에 플러그인을 자동 활성화해야 하는 축약형 모델 패밀리 소유 메타데이터
|
||||
- 번들 호환 wiring 및 계약 범위 검증에 사용되는 정적 capability 소유 스냅샷
|
||||
- 런타임을 로드하지 않고 카탈로그 및 유효성 검사 표면에 병합되어야 하는 채널별 구성 메타데이터
|
||||
- 플러그인 런타임이 로드되기 전에 플러그인을 자동 활성화해야 하는 축약형 모델 패밀리 소유권 메타데이터
|
||||
- 번들 compat 배선 및 계약 커버리지에 사용되는 정적 capability 소유권 스냅샷
|
||||
- 런타임을 로드하지 않고 카탈로그 및 검증 표면에 병합되어야 하는 채널별 구성 메타데이터
|
||||
- 구성 UI 힌트
|
||||
|
||||
다음 용도로는 사용하지 마세요.
|
||||
@ -74,7 +81,7 @@ OpenClaw는 이러한 번들 레이아웃도 자동 감지하지만, 여기에
|
||||
}
|
||||
```
|
||||
|
||||
## 상세 예시
|
||||
## 확장 예시
|
||||
|
||||
```json
|
||||
{
|
||||
@ -136,56 +143,59 @@ OpenClaw는 이러한 번들 레이아웃도 자동 감지하지만, 여기에
|
||||
| ----------------------------------- | --------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `id` | 예 | `string` | 정식 플러그인 id입니다. 이 id는 `plugins.entries.<id>`에서 사용됩니다. |
|
||||
| `configSchema` | 예 | `object` | 이 플러그인 구성에 대한 인라인 JSON 스키마입니다. |
|
||||
| `enabledByDefault` | 아니요 | `true` | 번들 플러그인을 기본적으로 활성화된 상태로 표시합니다. 기본적으로 비활성화된 상태로 두려면 이 값을 생략하거나 `true`가 아닌 값을 설정하세요. |
|
||||
| `enabledByDefault` | 아니요 | `true` | 번들 플러그인을 기본적으로 활성화됨으로 표시합니다. 기본 비활성 상태로 두려면 이 필드를 생략하거나 `true`가 아닌 값을 설정하세요. |
|
||||
| `legacyPluginIds` | 아니요 | `string[]` | 이 정식 플러그인 id로 정규화되는 레거시 id입니다. |
|
||||
| `autoEnableWhenConfiguredProviders` | 아니요 | `string[]` | 인증, 구성 또는 모델 참조에서 이 provider id들이 언급되면 이 플러그인을 자동 활성화해야 함을 나타냅니다. |
|
||||
| `kind` | 아니요 | `"memory"` \| `"context-engine"` | `plugins.slots.*`에서 사용되는 배타적 플러그인 종류를 선언합니다. |
|
||||
| `channels` | 아니요 | `string[]` | 이 플러그인이 소유하는 채널 id입니다. 검색 및 구성 유효성 검사에 사용됩니다. |
|
||||
| `autoEnableWhenConfiguredProviders` | 아니요 | `string[]` | 인증, 구성 또는 모델 참조에서 이들 provider id가 언급될 때 이 플러그인을 자동 활성화해야 함을 나타냅니다. |
|
||||
| `kind` | 아니요 | `"memory"` \| `"context-engine"` | `plugins.slots.*`에서 사용하는 배타적 플러그인 kind를 선언합니다. |
|
||||
| `channels` | 아니요 | `string[]` | 이 플러그인이 소유하는 채널 id입니다. 검색 및 구성 검증에 사용됩니다. |
|
||||
| `providers` | 아니요 | `string[]` | 이 플러그인이 소유하는 provider id입니다. |
|
||||
| `modelSupport` | 아니요 | `object` | 런타임 전에 플러그인을 자동 로드하는 데 사용되는, 매니페스트가 소유하는 축약형 모델 패밀리 메타데이터입니다. |
|
||||
| `modelSupport` | 아니요 | `object` | 런타임 전에 플러그인을 자동 로드하는 데 사용되는 매니페스트 소유 축약형 모델 패밀리 메타데이터입니다. |
|
||||
| `cliBackends` | 아니요 | `string[]` | 이 플러그인이 소유하는 CLI 추론 백엔드 id입니다. 명시적 구성 참조로부터 시작 시 자동 활성화하는 데 사용됩니다. |
|
||||
| `commandAliases` | 아니요 | `object[]` | 런타임이 로드되기 전에 플러그인 인식 구성 및 CLI 진단을 생성해야 하는, 이 플러그인이 소유하는 명령 이름입니다. |
|
||||
| `providerAuthEnvVars` | 아니요 | `Record<string, string[]>` | 플러그인 코드를 로드하지 않고도 OpenClaw가 확인할 수 있는 가벼운 provider 인증 환경 변수 메타데이터입니다. |
|
||||
| `providerAuthAliases` | 아니요 | `Record<string, string>` | 인증 조회를 위해 다른 provider id를 재사용해야 하는 provider id입니다. 예를 들어 기본 provider API 키 및 인증 프로필을 공유하는 코딩 provider가 이에 해당합니다. |
|
||||
| `channelEnvVars` | 아니요 | `Record<string, string[]>` | 플러그인 코드를 로드하지 않고도 OpenClaw가 확인할 수 있는 가벼운 채널 환경 변수 메타데이터입니다. 일반적인 시작/구성 도우미가 볼 수 있어야 하는 환경 변수 기반 채널 설정 또는 인증 표면에 사용하세요. |
|
||||
| `providerAuthChoices` | 아니요 | `object[]` | 온보딩 선택기, 선호 provider 확인, 간단한 CLI 플래그 연결에 사용하는 가벼운 인증 선택 메타데이터입니다. |
|
||||
| `activation` | 아니요 | `object` | provider, 명령, 채널, route, capability 트리거 로드를 위한 가벼운 활성화 힌트입니다. 메타데이터 전용이며, 실제 동작은 여전히 플러그인 런타임이 소유합니다. |
|
||||
| `setup` | 아니요 | `object` | 검색 및 설정 표면이 플러그인 런타임을 로드하지 않고도 확인할 수 있는 가벼운 설정/온보딩 설명자입니다. |
|
||||
| `contracts` | 아니요 | `object` | speech, 실시간 전사, 실시간 음성, media-understanding, image-generation, music-generation, video-generation, web-fetch, 웹 검색, 도구 소유권을 위한 정적 번들 capability 스냅샷입니다. |
|
||||
| `channelConfigs` | 아니요 | `Record<string, object>` | 런타임이 로드되기 전에 검색 및 유효성 검사 표면에 병합되는, 매니페스트가 소유하는 채널 구성 메타데이터입니다. |
|
||||
| `skills` | 아니요 | `string[]` | 플러그인 루트를 기준으로 로드할 Skills 디렉터리입니다. |
|
||||
| `providerAuthEnvVars` | 아니요 | `Record<string, string[]>` | OpenClaw가 플러그인 코드를 로드하지 않고도 검사할 수 있는 가벼운 provider 인증 env 메타데이터입니다. |
|
||||
| `providerAuthAliases` | 아니요 | `Record<string, string>` | 다른 provider id의 인증 조회를 재사용해야 하는 provider id입니다. 예를 들어, 기본 provider API 키와 인증 프로필을 공유하는 코딩 provider가 이에 해당합니다. |
|
||||
| `channelEnvVars` | 아니요 | `Record<string, string[]>` | OpenClaw가 플러그인 코드를 로드하지 않고도 검사할 수 있는 가벼운 채널 env 메타데이터입니다. env 기반 채널 설정 또는 일반 시작/구성 도우미가 확인해야 하는 인증 표면에는 이것을 사용하세요. |
|
||||
| `providerAuthChoices` | 아니요 | `object[]` | 온보딩 선택기, 선호 provider 확인, 간단한 CLI 플래그 연결을 위한 가벼운 인증 선택 메타데이터입니다. |
|
||||
| `activation` | 아니요 | `object` | provider, command, channel, route, capability 트리거 로딩을 위한 가벼운 활성화 힌트입니다. 메타데이터 전용이며 실제 동작은 여전히 플러그인 런타임이 소유합니다. |
|
||||
| `setup` | 아니요 | `object` | 검색 및 설정 표면이 플러그인 런타임을 로드하지 않고도 검사할 수 있는 가벼운 설정/온보딩 설명자입니다. |
|
||||
| `contracts` | 아니요 | `object` | speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, tool 소유권에 대한 정적 번들 capability 스냅샷입니다. |
|
||||
| `channelConfigs` | 아니요 | `Record<string, object>` | 런타임이 로드되기 전에 검색 및 검증 표면에 병합되는 매니페스트 소유 채널 구성 메타데이터입니다. |
|
||||
| `skills` | 아니요 | `string[]` | 플러그인 루트를 기준으로 로드할 Skills 디렉터리입니다. |
|
||||
| `name` | 아니요 | `string` | 사람이 읽을 수 있는 플러그인 이름입니다. |
|
||||
| `description` | 아니요 | `string` | 플러그인 표면에 표시되는 짧은 요약입니다. |
|
||||
| `version` | 아니요 | `string` | 정보 제공용 플러그인 버전입니다. |
|
||||
| `uiHints` | 아니요 | `Record<string, object>` | 구성 필드에 대한 UI 레이블, 플레이스홀더, 민감도 힌트입니다. |
|
||||
| `uiHints` | 아니요 | `Record<string, object>` | 구성 필드에 대한 UI 레이블, 플레이스홀더, 민감도 힌트입니다. |
|
||||
|
||||
## `providerAuthChoices` 참조
|
||||
|
||||
각 `providerAuthChoices` 항목은 하나의 온보딩 또는 인증 선택 항목을 설명합니다.
|
||||
OpenClaw는 provider 런타임이 로드되기 전에 이를 읽습니다.
|
||||
각 `providerAuthChoices` 항목은 하나의 온보딩 또는 인증 선택을 설명합니다.
|
||||
OpenClaw는 provider 런타임이 로드되기 전에 이 정보를 읽습니다.
|
||||
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| --------------------- | --------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| `provider` | 예 | `string` | 이 선택 항목이 속한 provider id입니다. |
|
||||
| `method` | 예 | `string` | 디스패치할 인증 방식 id입니다. |
|
||||
| `choiceId` | 예 | `string` | 온보딩 및 CLI 흐름에서 사용하는 안정적인 인증 선택 id입니다. |
|
||||
| `choiceLabel` | 아니요 | `string` | 사용자 대상 레이블입니다. 생략하면 OpenClaw는 `choiceId`를 대체값으로 사용합니다. |
|
||||
| `choiceHint` | 아니요 | `string` | 선택기용 짧은 도움말 텍스트입니다. |
|
||||
| `assistantPriority` | 아니요 | `number` | assistant 주도 대화형 선택기에서 값이 낮을수록 먼저 정렬됩니다. |
|
||||
| `assistantVisibility` | 아니요 | `"visible"` \| `"manual-only"` | assistant 선택기에서는 이 선택 항목을 숨기되, 수동 CLI 선택은 계속 허용합니다. |
|
||||
| `deprecatedChoiceIds` | 아니요 | `string[]` | 사용자를 이 대체 선택 항목으로 리디렉션해야 하는 레거시 선택 id입니다. |
|
||||
| `groupId` | 아니요 | `string` | 관련 선택 항목을 그룹화하기 위한 선택적 그룹 id입니다. |
|
||||
| `groupLabel` | 아니요 | `string` | 해당 그룹의 사용자 대상 레이블입니다. |
|
||||
| `groupHint` | 아니요 | `string` | 그룹용 짧은 도움말 텍스트입니다. |
|
||||
| `optionKey` | 아니요 | `string` | 단일 플래그 기반의 간단한 인증 흐름에서 사용하는 내부 옵션 키입니다. |
|
||||
| `cliFlag` | 아니요 | `string` | `--openrouter-api-key`와 같은 CLI 플래그 이름입니다. |
|
||||
| `cliOption` | 아니요 | `string` | `--openrouter-api-key <key>`와 같은 전체 CLI 옵션 형태입니다. |
|
||||
| `cliDescription` | 아니요 | `string` | CLI 도움말에 사용되는 설명입니다. |
|
||||
| `onboardingScopes` | 아니요 | `Array<"text-inference" \| "image-generation">` | 이 선택 항목이 표시되어야 하는 온보딩 표면입니다. 생략하면 기본값은 `["text-inference"]`입니다. |
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| --------------------- | --------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | 예 | `string` | 이 선택이 속한 provider id입니다. |
|
||||
| `method` | 예 | `string` | 디스패치할 인증 메서드 id입니다. |
|
||||
| `choiceId` | 예 | `string` | 온보딩 및 CLI 흐름에서 사용하는 안정적인 인증 선택 id입니다. |
|
||||
| `choiceLabel` | 아니요 | `string` | 사용자용 레이블입니다. 생략하면 OpenClaw는 `choiceId`를 대신 사용합니다. |
|
||||
| `choiceHint` | 아니요 | `string` | 선택기에 표시할 짧은 도움말 텍스트입니다. |
|
||||
| `assistantPriority` | 아니요 | `number` | assistant 기반 대화형 선택기에서 값이 낮을수록 먼저 정렬됩니다. |
|
||||
| `assistantVisibility` | 아니요 | `"visible"` \| `"manual-only"` | assistant 선택기에서는 이 선택을 숨기지만, 수동 CLI 선택은 계속 허용합니다. |
|
||||
| `deprecatedChoiceIds` | 아니요 | `string[]` | 사용자를 이 대체 선택으로 리디렉션해야 하는 레거시 선택 id입니다. |
|
||||
| `groupId` | 아니요 | `string` | 관련 선택을 그룹화하기 위한 선택적 그룹 id입니다. |
|
||||
| `groupLabel` | 아니요 | `string` | 해당 그룹의 사용자용 레이블입니다. |
|
||||
| `groupHint` | 아니요 | `string` | 그룹에 대한 짧은 도움말 텍스트입니다. |
|
||||
| `optionKey` | 아니요 | `string` | 단일 플래그 기반의 단순 인증 흐름에 사용하는 내부 옵션 키입니다. |
|
||||
| `cliFlag` | 아니요 | `string` | `--openrouter-api-key`와 같은 CLI 플래그 이름입니다. |
|
||||
| `cliOption` | 아니요 | `string` | `--openrouter-api-key <key>`와 같은 전체 CLI 옵션 형태입니다. |
|
||||
| `cliDescription` | 아니요 | `string` | CLI 도움말에 사용되는 설명입니다. |
|
||||
| `onboardingScopes` | 아니요 | `Array<"text-inference" \| "image-generation">` | 이 선택이 어떤 온보딩 표면에 표시되어야 하는지 나타냅니다. 생략하면 기본값은 `["text-inference"]`입니다. |
|
||||
|
||||
## `commandAliases` 참조
|
||||
|
||||
사용자가 `plugins.allow`에 잘못 넣거나 루트 CLI 명령으로 실행하려고 할 수 있는 런타임 명령 이름을 플러그인이 소유하는 경우 `commandAliases`를 사용하세요. OpenClaw는 플러그인 런타임 코드를 import하지 않고 이 메타데이터를 진단에 사용합니다.
|
||||
사용자가 플러그인이 소유한 런타임 명령 이름을 실수로 `plugins.allow`에 넣거나
|
||||
루트 CLI 명령으로 실행하려고 할 수 있는 경우 `commandAliases`를 사용하세요.
|
||||
OpenClaw는 플러그인 런타임 코드를 import하지 않고도 진단을 위해 이 메타데이터를
|
||||
사용합니다.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -202,14 +212,16 @@ OpenClaw는 provider 런타임이 로드되기 전에 이를 읽습니다.
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| ------------ | --------- | ----------------- | ------------------------------------------------------------------------ |
|
||||
| `name` | 예 | `string` | 이 플러그인에 속한 명령 이름입니다. |
|
||||
| `kind` | 아니요 | `"runtime-slash"` | 이 별칭이 루트 CLI 명령이 아니라 채팅 슬래시 명령임을 나타냅니다. |
|
||||
| `kind` | 아니요 | `"runtime-slash"` | 별칭이 루트 CLI 명령이 아니라 채팅 슬래시 명령임을 나타냅니다. |
|
||||
| `cliCommand` | 아니요 | `string` | 존재하는 경우, CLI 작업에 대해 제안할 관련 루트 CLI 명령입니다. |
|
||||
|
||||
## `activation` 참조
|
||||
|
||||
플러그인이 어떤 컨트롤 플레인 이벤트에 의해 나중에 활성화되어야 하는지를 가볍게 선언할 수 있을 때 `activation`을 사용하세요.
|
||||
플러그인이 나중에 자신을 활성화해야 하는 컨트롤 플레인 이벤트를 가볍게 선언할 수
|
||||
있는 경우 `activation`을 사용하세요.
|
||||
|
||||
이 블록은 메타데이터 전용입니다. 런타임 동작을 등록하지 않으며, `register(...)`, `setupEntry` 또는 기타 런타임/플러그인 진입점을 대체하지도 않습니다.
|
||||
이 블록은 메타데이터 전용입니다. 런타임 동작을 등록하지 않으며,
|
||||
`register(...)`, `setupEntry`, 기타 런타임/플러그인 진입점을 대체하지도 않습니다.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -223,17 +235,18 @@ OpenClaw는 provider 런타임이 로드되기 전에 이를 읽습니다.
|
||||
}
|
||||
```
|
||||
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| ---------------- | --------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `onProviders` | 아니요 | `string[]` | 요청되었을 때 이 플러그인을 활성화해야 하는 provider id입니다. |
|
||||
| `onCommands` | 아니요 | `string[]` | 이 플러그인을 활성화해야 하는 명령 id입니다. |
|
||||
| `onChannels` | 아니요 | `string[]` | 이 플러그인을 활성화해야 하는 채널 id입니다. |
|
||||
| `onRoutes` | 아니요 | `string[]` | 이 플러그인을 활성화해야 하는 route 종류입니다. |
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| ---------------- | --------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| `onProviders` | 아니요 | `string[]` | 요청될 때 이 플러그인을 활성화해야 하는 provider id입니다. |
|
||||
| `onCommands` | 아니요 | `string[]` | 이 플러그인을 활성화해야 하는 명령 id입니다. |
|
||||
| `onChannels` | 아니요 | `string[]` | 이 플러그인을 활성화해야 하는 채널 id입니다. |
|
||||
| `onRoutes` | 아니요 | `string[]` | 이 플러그인을 활성화해야 하는 route kind입니다. |
|
||||
| `onCapabilities` | 아니요 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 컨트롤 플레인 활성화 계획에 사용되는 광범위한 capability 힌트입니다. |
|
||||
|
||||
## `setup` 참조
|
||||
|
||||
설정 및 온보딩 표면에서 런타임이 로드되기 전에 플러그인이 소유한 가벼운 메타데이터가 필요할 때 `setup`을 사용하세요.
|
||||
설정 및 온보딩 표면이 런타임이 로드되기 전에 플러그인 소유의 가벼운 메타데이터를
|
||||
필요로 하는 경우 `setup`을 사용하세요.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -252,28 +265,40 @@ OpenClaw는 provider 런타임이 로드되기 전에 이를 읽습니다.
|
||||
}
|
||||
```
|
||||
|
||||
최상위 `cliBackends`는 계속 유효하며 계속해서 CLI 추론 백엔드를 설명합니다. `setup.cliBackends`는 메타데이터 전용으로 유지되어야 하는 컨트롤 플레인/설정 흐름을 위한 설정 전용 설명자 표면입니다.
|
||||
최상위 `cliBackends`는 계속 유효하며 계속해서 CLI 추론 백엔드를 설명합니다.
|
||||
`setup.cliBackends`는 메타데이터 전용으로 유지되어야 하는 컨트롤 플레인/설정 흐름용
|
||||
설정 전용 설명자 표면입니다.
|
||||
|
||||
`setup.providers`와 `setup.cliBackends`가 존재하는 경우, 이들은 설정 검색을 위한
|
||||
우선적인 descriptor-first 조회 표면입니다. 설명자가 후보 플러그인만 좁히고
|
||||
설정에 더 풍부한 설정 시점 런타임 hook이 여전히 필요한 경우에는
|
||||
`requiresRuntime: true`를 설정하고 대체 실행 경로로 `setup-api`를 유지하세요.
|
||||
|
||||
설정 조회는 플러그인 소유의 `setup-api` 코드를 실행할 수 있으므로, 정규화된
|
||||
`setup.providers[].id`와 `setup.cliBackends[]` 값은 검색된 플러그인 전체에서
|
||||
고유해야 합니다. 소유권이 모호하면 검색 순서에서 임의의 승자를 고르지 않고
|
||||
닫힌 방식으로 실패합니다.
|
||||
|
||||
### `setup.providers` 참조
|
||||
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| ------------- | --------- | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | 예 | `string` | 설정 또는 온보딩 중에 노출되는 provider id입니다. |
|
||||
| `authMethods` | 아니요 | `string[]` | 전체 런타임을 로드하지 않고도 이 provider가 지원하는 설정/인증 방식 id입니다. |
|
||||
| `envVars` | 아니요 | `string[]` | 플러그인 런타임이 로드되기 전에 일반 설정/상태 표면에서 확인할 수 있는 환경 변수입니다. |
|
||||
| `id` | 예 | `string` | 설정 또는 온보딩 중에 노출되는 provider id입니다. 정규화된 id는 전역적으로 고유하게 유지하세요. |
|
||||
| `authMethods` | 아니요 | `string[]` | 전체 런타임을 로드하지 않고도 이 provider가 지원하는 설정/인증 메서드 id입니다. |
|
||||
| `envVars` | 아니요 | `string[]` | 일반 설정/상태 표면이 플러그인 런타임이 로드되기 전에 확인할 수 있는 env var입니다. |
|
||||
|
||||
### `setup` 필드
|
||||
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| ------------------ | --------- | ---------- | --------------------------------------------------------------------------- |
|
||||
| `providers` | 아니요 | `object[]` | 설정 및 온보딩 중에 노출되는 provider 설정 설명자입니다. |
|
||||
| `cliBackends` | 아니요 | `string[]` | 전체 런타임 활성화 없이 사용할 수 있는 설정 시점 백엔드 id입니다. |
|
||||
| `configMigrations` | 아니요 | `string[]` | 이 플러그인의 설정 표면이 소유하는 구성 마이그레이션 id입니다. |
|
||||
| `requiresRuntime` | 아니요 | `boolean` | 설명자 조회 후에도 설정에 플러그인 런타임 실행이 필요한지 여부입니다. |
|
||||
| 필드 | 필수 여부 | 유형 | 의미 |
|
||||
| ------------------ | --------- | ---------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | 아니요 | `object[]` | 설정 및 온보딩 중에 노출되는 provider 설정 설명자입니다. |
|
||||
| `cliBackends` | 아니요 | `string[]` | descriptor-first 설정 조회에 사용되는 설정 시점 백엔드 id입니다. 정규화된 id는 전역적으로 고유하게 유지하세요. |
|
||||
| `configMigrations` | 아니요 | `string[]` | 이 플러그인의 설정 표면이 소유하는 구성 마이그레이션 id입니다. |
|
||||
| `requiresRuntime` | 아니요 | `boolean` | 설명자 조회 후에도 설정에 `setup-api` 실행이 여전히 필요한지 여부입니다. |
|
||||
|
||||
## `uiHints` 참조
|
||||
|
||||
`uiHints`는 구성 필드 이름을 작은 렌더링 힌트에 매핑한 맵입니다.
|
||||
`uiHints`는 구성 필드 이름에서 작은 렌더링 힌트로 매핑되는 맵입니다.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -290,18 +315,19 @@ OpenClaw는 provider 런타임이 로드되기 전에 이를 읽습니다.
|
||||
|
||||
각 필드 힌트에는 다음이 포함될 수 있습니다.
|
||||
|
||||
| 필드 | 유형 | 의미 |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | 사용자 대상 필드 레이블입니다. |
|
||||
| `help` | `string` | 짧은 도움말 텍스트입니다. |
|
||||
| `tags` | `string[]` | 선택적 UI 태그입니다. |
|
||||
| `advanced` | `boolean` | 이 필드를 고급 항목으로 표시합니다. |
|
||||
| `sensitive` | `boolean` | 이 필드를 비밀값 또는 민감 정보로 표시합니다. |
|
||||
| `placeholder` | `string` | 폼 입력용 플레이스홀더 텍스트입니다. |
|
||||
| 필드 | 유형 | 의미 |
|
||||
| ------------- | ---------- | ----------------------------------- |
|
||||
| `label` | `string` | 사용자용 필드 레이블입니다. |
|
||||
| `help` | `string` | 짧은 도움말 텍스트입니다. |
|
||||
| `tags` | `string[]` | 선택적 UI 태그입니다. |
|
||||
| `advanced` | `boolean` | 필드를 고급 항목으로 표시합니다. |
|
||||
| `sensitive` | `boolean` | 필드를 비밀값 또는 민감 정보로 표시합니다. |
|
||||
| `placeholder` | `string` | 폼 입력용 플레이스홀더 텍스트입니다. |
|
||||
|
||||
## `contracts` 참조
|
||||
|
||||
OpenClaw가 플러그인 런타임을 import하지 않고 읽을 수 있는 정적 capability 소유 메타데이터에만 `contracts`를 사용하세요.
|
||||
`contracts`는 OpenClaw가 플러그인 런타임을 import하지 않고도 읽을 수 있는
|
||||
정적 capability 소유권 메타데이터에만 사용하세요.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -321,21 +347,22 @@ OpenClaw가 플러그인 런타임을 import하지 않고 읽을 수 있는 정
|
||||
|
||||
각 목록은 선택 사항입니다.
|
||||
|
||||
| 필드 | 유형 | 의미 |
|
||||
| -------------------------------- | ---------- | --------------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | 이 플러그인이 소유하는 speech provider id입니다. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | 이 플러그인이 소유하는 실시간 전사 provider id입니다. |
|
||||
| `realtimeVoiceProviders` | `string[]` | 이 플러그인이 소유하는 실시간 음성 provider id입니다. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | 이 플러그인이 소유하는 media-understanding provider id입니다. |
|
||||
| `imageGenerationProviders` | `string[]` | 이 플러그인이 소유하는 image-generation provider id입니다. |
|
||||
| `videoGenerationProviders` | `string[]` | 이 플러그인이 소유하는 video-generation provider id입니다. |
|
||||
| `webFetchProviders` | `string[]` | 이 플러그인이 소유하는 web-fetch provider id입니다. |
|
||||
| `webSearchProviders` | `string[]` | 이 플러그인이 소유하는 웹 검색 provider id입니다. |
|
||||
| `tools` | `string[]` | 번들 계약 검사에서 이 플러그인이 소유하는 에이전트 도구 이름입니다. |
|
||||
| 필드 | 유형 | 의미 |
|
||||
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | 이 플러그인이 소유하는 speech provider id입니다. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | 이 플러그인이 소유하는 실시간 전사 provider id입니다. |
|
||||
| `realtimeVoiceProviders` | `string[]` | 이 플러그인이 소유하는 실시간 음성 provider id입니다. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | 이 플러그인이 소유하는 media-understanding provider id입니다. |
|
||||
| `imageGenerationProviders` | `string[]` | 이 플러그인이 소유하는 image-generation provider id입니다. |
|
||||
| `videoGenerationProviders` | `string[]` | 이 플러그인이 소유하는 video-generation provider id입니다. |
|
||||
| `webFetchProviders` | `string[]` | 이 플러그인이 소유하는 web-fetch provider id입니다. |
|
||||
| `webSearchProviders` | `string[]` | 이 플러그인이 소유하는 web-search provider id입니다. |
|
||||
| `tools` | `string[]` | 번들 계약 검사를 위해 이 플러그인이 소유하는 에이전트 tool 이름입니다. |
|
||||
|
||||
## `channelConfigs` 참조
|
||||
|
||||
채널 플러그인이 런타임이 로드되기 전에 가벼운 구성 메타데이터를 필요로 할 때 `channelConfigs`를 사용하세요.
|
||||
채널 플러그인이 런타임이 로드되기 전에 가벼운 구성 메타데이터를 필요로 하는 경우
|
||||
`channelConfigs`를 사용하세요.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -364,17 +391,19 @@ OpenClaw가 플러그인 런타임을 import하지 않고 읽을 수 있는 정
|
||||
|
||||
각 채널 항목에는 다음이 포함될 수 있습니다.
|
||||
|
||||
| 필드 | 유형 | 의미 |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | `channels.<id>`에 대한 JSON 스키마입니다. 선언된 각 채널 구성 항목에 필수입니다. |
|
||||
| `uiHints` | `Record<string, object>` | 해당 채널 구성 섹션에 대한 선택적 UI 레이블/플레이스홀더/민감도 힌트입니다. |
|
||||
| `label` | `string` | 런타임 메타데이터가 준비되지 않았을 때 선택기 및 검사 표면에 병합되는 채널 레이블입니다. |
|
||||
| `description` | `string` | 검사 및 카탈로그 표면용 짧은 채널 설명입니다. |
|
||||
| `preferOver` | `string[]` | 선택 표면에서 이 채널이 우선해야 하는 레거시 또는 우선순위가 낮은 플러그인 id입니다. |
|
||||
| 필드 | 유형 | 의미 |
|
||||
| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | `channels.<id>`에 대한 JSON 스키마입니다. 선언된 각 채널 구성 항목에는 필수입니다. |
|
||||
| `uiHints` | `Record<string, object>` | 해당 채널 구성 섹션에 대한 선택적 UI 레이블/플레이스홀더/민감도 힌트입니다. |
|
||||
| `label` | `string` | 런타임 메타데이터가 아직 준비되지 않았을 때 선택기 및 검사 표면에 병합되는 채널 레이블입니다. |
|
||||
| `description` | `string` | 검사 및 카탈로그 표면에 표시되는 짧은 채널 설명입니다. |
|
||||
| `preferOver` | `string[]` | 선택 표면에서 이 채널이 우선해야 하는 레거시 또는 낮은 우선순위 플러그인 id입니다. |
|
||||
|
||||
## `modelSupport` 참조
|
||||
|
||||
플러그인 런타임이 로드되기 전에 OpenClaw가 `gpt-5.4` 또는 `claude-sonnet-4.6` 같은 축약형 모델 id로부터 provider 플러그인을 추론해야 할 때 `modelSupport`를 사용하세요.
|
||||
플러그인 런타임이 로드되기 전에 OpenClaw가 `gpt-5.4` 또는
|
||||
`claude-sonnet-4.6` 같은 축약형 모델 id로부터 provider 플러그인을 추론해야 하는 경우
|
||||
`modelSupport`를 사용하세요.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -387,58 +416,74 @@ OpenClaw가 플러그인 런타임을 import하지 않고 읽을 수 있는 정
|
||||
|
||||
OpenClaw는 다음 우선순위를 적용합니다.
|
||||
|
||||
- 명시적 `provider/model` 참조는 소유 `providers` 매니페스트 메타데이터를 사용합니다
|
||||
- 명시적인 `provider/model` 참조는 소유 `providers` 매니페스트 메타데이터를 사용합니다
|
||||
- `modelPatterns`가 `modelPrefixes`보다 우선합니다
|
||||
- 번들되지 않은 플러그인과 번들 플러그인이 둘 다 일치하면 번들되지 않은 플러그인이 우선합니다
|
||||
- 나머지 모호성은 사용자 또는 구성에서 provider를 지정할 때까지 무시됩니다
|
||||
- 비번들 플러그인 하나와 번들 플러그인 하나가 모두 일치하는 경우, 비번들
|
||||
플러그인이 우선합니다
|
||||
- 남은 모호성은 사용자 또는 구성이 provider를 지정할 때까지 무시됩니다
|
||||
|
||||
필드:
|
||||
|
||||
| 필드 | 유형 | 의미 |
|
||||
| --------------- | ---------- | ------------------------------------------------------------------------------ |
|
||||
| `modelPrefixes` | `string[]` | 축약형 모델 id에 대해 `startsWith`로 일치시키는 접두사입니다. |
|
||||
| `modelPatterns` | `string[]` | 프로필 접미사 제거 후 축약형 모델 id에 대해 일치시키는 정규식 소스입니다. |
|
||||
| 필드 | 유형 | 의미 |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | 축약형 모델 id에 대해 `startsWith`로 일치시키는 접두사입니다. |
|
||||
| `modelPatterns` | `string[]` | 프로필 접미사를 제거한 뒤 축약형 모델 id와 일치시키는 정규식 소스입니다. |
|
||||
|
||||
레거시 최상위 capability 키는 더 이상 권장되지 않습니다. `openclaw doctor --fix`를 사용해 `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`를 `contracts` 아래로 이동하세요. 일반 매니페스트 로딩은 더 이상 이러한 최상위 필드를 capability 소유권으로 처리하지 않습니다.
|
||||
레거시 최상위 capability 키는 더 이상 권장되지 않습니다. `openclaw doctor --fix`를
|
||||
사용해 `speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`,
|
||||
`webFetchProviders`, `webSearchProviders`를 `contracts` 아래로 이동하세요.
|
||||
일반 매니페스트 로딩은 더 이상 이러한 최상위 필드를 capability 소유권으로
|
||||
처리하지 않습니다.
|
||||
|
||||
## 매니페스트와 package.json 비교
|
||||
## 매니페스트와 `package.json`의 차이
|
||||
|
||||
두 파일은 서로 다른 역할을 합니다.
|
||||
|
||||
| 파일 | 용도 |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | 플러그인 코드가 실행되기 전에 반드시 존재해야 하는 검색, 구성 유효성 검사, 인증 선택 메타데이터, UI 힌트 |
|
||||
| `package.json` | npm 메타데이터, 의존성 설치, 진입점, 설치 게이트, 설정 또는 카탈로그 메타데이터에 사용되는 `openclaw` 블록 |
|
||||
| 파일 | 용도 |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | 플러그인 코드가 실행되기 전에 존재해야 하는 검색, 구성 검증, 인증 선택 메타데이터, UI 힌트 |
|
||||
| `package.json` | npm 메타데이터, 의존성 설치, 진입점, 설치 게이팅, 설정 또는 카탈로그 메타데이터에 사용되는 `openclaw` 블록 |
|
||||
|
||||
어떤 메타데이터를 어디에 넣어야 할지 확실하지 않다면 다음 규칙을 따르세요.
|
||||
어떤 메타데이터를 어디에 두어야 할지 확실하지 않다면 다음 규칙을 사용하세요.
|
||||
|
||||
- OpenClaw가 플러그인 코드를 로드하기 전에 알아야 한다면 `openclaw.plugin.json`에 넣으세요
|
||||
- 패키징, 진입 파일, npm 설치 동작에 관한 것이라면 `package.json`에 넣으세요
|
||||
- 패키징, 진입 파일, npm 설치 동작과 관련된 것이라면 `package.json`에 넣으세요
|
||||
|
||||
### 검색에 영향을 주는 `package.json` 필드
|
||||
|
||||
일부 사전 런타임 플러그인 메타데이터는 의도적으로 `openclaw.plugin.json`이 아니라 `package.json`의 `openclaw` 블록에 있습니다.
|
||||
일부 런타임 이전 플러그인 메타데이터는 의도적으로 `openclaw.plugin.json`이 아니라
|
||||
`package.json`의 `openclaw` 블록 아래에 위치합니다.
|
||||
|
||||
중요한 예시는 다음과 같습니다.
|
||||
|
||||
| 필드 | 의미 |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | 네이티브 플러그인 진입점을 선언합니다. |
|
||||
| `openclaw.setupEntry` | 온보딩 및 지연된 채널 시작 중 사용되는 경량 설정 전용 진입점입니다. |
|
||||
| `openclaw.channel` | 레이블, 문서 경로, 별칭, 선택용 문구 같은 가벼운 채널 카탈로그 메타데이터입니다. |
|
||||
| `openclaw.channel.configuredState` | 전체 채널 런타임을 로드하지 않고도 "환경 변수 전용 설정이 이미 존재하는가?"에 답할 수 있는 가벼운 configured-state 검사기 메타데이터입니다. |
|
||||
| `openclaw.channel.persistedAuthState` | 전체 채널 런타임을 로드하지 않고도 "이미 로그인된 항목이 있는가?"에 답할 수 있는 가벼운 persisted-auth 검사기 메타데이터입니다. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 번들 플러그인 및 외부 배포 플러그인을 위한 설치/업데이트 힌트입니다. |
|
||||
| `openclaw.setupEntry` | 온보딩 및 지연된 채널 시작 중에 사용되는 가벼운 설정 전용 진입점입니다. |
|
||||
| `openclaw.channel` | 레이블, 문서 경로, 별칭, 선택용 문구 같은 가벼운 채널 카탈로그 메타데이터입니다. |
|
||||
| `openclaw.channel.configuredState` | 전체 채널 런타임을 로드하지 않고도 "env 전용 설정이 이미 존재하는가?"에 답할 수 있는 가벼운 configured-state 검사기 메타데이터입니다. |
|
||||
| `openclaw.channel.persistedAuthState` | 전체 채널 런타임을 로드하지 않고도 "이미 로그인된 항목이 있는가?"에 답할 수 있는 가벼운 persisted-auth 검사기 메타데이터입니다. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 번들 플러그인 및 외부에 배포된 플러그인을 위한 설치/업데이트 힌트입니다. |
|
||||
| `openclaw.install.defaultChoice` | 여러 설치 소스를 사용할 수 있을 때 선호되는 설치 경로입니다. |
|
||||
| `openclaw.install.minHostVersion` | `>=2026.3.22` 같은 semver 하한을 사용하는, 지원되는 최소 OpenClaw 호스트 버전입니다. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | 구성이 유효하지 않을 때 제한된 범위의 번들 플러그인 재설치 복구 경로를 허용합니다. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 시작 중 전체 채널 플러그인보다 먼저 설정 전용 채널 표면을 로드할 수 있게 합니다. |
|
||||
| `openclaw.install.minHostVersion` | `>=2026.3.22` 같은 semver 하한을 사용하는 최소 지원 OpenClaw 호스트 버전입니다. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | 구성이 잘못되었을 때 제한적인 번들 플러그인 재설치 복구 경로를 허용합니다. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 시작 중 전체 채널 플러그인보다 먼저 설정 전용 채널 표면을 로드할 수 있게 합니다. |
|
||||
|
||||
`openclaw.install.minHostVersion`은 설치 및 매니페스트 레지스트리 로딩 중에 적용됩니다. 유효하지 않은 값은 거부되며, 더 새롭지만 유효한 값은 오래된 호스트에서 해당 플러그인을 건너뜁니다.
|
||||
`openclaw.install.minHostVersion`은 설치 중과 매니페스트 레지스트리 로딩 중에
|
||||
강제 적용됩니다. 잘못된 값은 거부되며, 더 최신이지만 유효한 값은 오래된 호스트에서
|
||||
플러그인을 건너뜁니다.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery`는 의도적으로 범위가 좁습니다. 임의로 깨진 구성을 설치 가능하게 만들지는 않습니다. 현재는 번들 플러그인 경로 누락 또는 같은 번들 플러그인에 대한 오래된 `channels.<id>` 항목처럼, 특정 오래된 번들 플러그인 업그레이드 실패에서 설치 흐름이 복구되도록 허용하는 용도로만 사용됩니다. 관련 없는 구성 오류는 여전히 설치를 차단하고 운영자를 `openclaw doctor --fix`로 안내합니다.
|
||||
`openclaw.install.allowInvalidConfigRecovery`는 의도적으로 매우 제한적입니다.
|
||||
임의의 깨진 구성을 설치 가능하게 만들지는 않습니다. 현재는 누락된 번들 플러그인 경로
|
||||
또는 동일한 번들 플러그인에 대한 오래된 `channels.<id>` 항목처럼, 특정한 오래된
|
||||
번들 플러그인 업그레이드 실패로부터 설치 흐름이 복구될 수 있게만 허용합니다.
|
||||
관련 없는 구성 오류는 여전히 설치를 차단하며 운영자는 `openclaw doctor --fix`로
|
||||
안내됩니다.
|
||||
|
||||
`openclaw.channel.persistedAuthState`는 작은 검사기 모듈을 위한 패키지 메타데이터입니다.
|
||||
`openclaw.channel.persistedAuthState`는 작은 검사기 모듈을 위한 패키지
|
||||
메타데이터입니다.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -454,9 +499,12 @@ OpenClaw는 다음 우선순위를 적용합니다.
|
||||
}
|
||||
```
|
||||
|
||||
설정, doctor 또는 configured-state 흐름이 전체 채널 플러그인이 로드되기 전에 가벼운 예/아니오 인증 확인을 필요로 할 때 사용하세요. 대상 export는 저장된 상태만 읽는 작은 함수여야 하며, 전체 채널 런타임 barrel을 통해 연결하지 마세요.
|
||||
설정, doctor 또는 configured-state 흐름이 전체 채널 플러그인이 로드되기 전에
|
||||
가벼운 예/아니오 인증 탐지를 필요로 하는 경우 이것을 사용하세요. 대상 export는
|
||||
지속된 상태만 읽는 작은 함수여야 하며, 전체 채널 런타임 배럴을 거치지 마세요.
|
||||
|
||||
`openclaw.channel.configuredState`도 가벼운 환경 변수 전용 configured 확인을 위해 동일한 형태를 따릅니다.
|
||||
`openclaw.channel.configuredState`는 가벼운 env 전용 configured 검사에 대해
|
||||
동일한 형태를 따릅니다.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -472,43 +520,61 @@ OpenClaw는 다음 우선순위를 적용합니다.
|
||||
}
|
||||
```
|
||||
|
||||
채널이 환경 변수 또는 기타 작은 비런타임 입력만으로 configured-state에 답할 수 있을 때 사용하세요. 확인에 전체 구성 해석 또는 실제 채널 런타임이 필요하다면, 그 로직은 대신 플러그인 `config.hasConfiguredState` hook에 두세요.
|
||||
채널이 env 또는 기타 작은 비런타임 입력만으로 configured-state에 답할 수 있을 때
|
||||
이것을 사용하세요. 검사가 전체 구성 확인이나 실제 채널 런타임을 필요로 한다면,
|
||||
그 로직은 대신 플러그인 `config.hasConfiguredState` hook에 두세요.
|
||||
|
||||
## JSON 스키마 요구사항
|
||||
## JSON 스키마 요구 사항
|
||||
|
||||
- **모든 플러그인은 반드시 JSON 스키마를 포함해야 하며**, 구성을 전혀 받지 않는 경우도 예외가 아닙니다.
|
||||
- **모든 플러그인은 JSON 스키마를 반드시 포함해야 하며**, 구성을 전혀 받지 않는 경우도 예외가 아닙니다.
|
||||
- 빈 스키마도 허용됩니다(예: `{ "type": "object", "additionalProperties": false }`).
|
||||
- 스키마는 런타임이 아니라 구성 읽기/쓰기 시점에 유효성 검사됩니다.
|
||||
- 스키마는 런타임이 아니라 구성 읽기/쓰기 시점에 검증됩니다.
|
||||
|
||||
## 유효성 검사 동작
|
||||
## 검증 동작
|
||||
|
||||
- 알 수 없는 `channels.*` 키는 **오류**입니다. 단, 해당 채널 id가 플러그인 매니페스트에 선언되어 있는 경우는 예외입니다.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny`, `plugins.slots.*`는 **검색 가능한** 플러그인 id를 참조해야 합니다. 알 수 없는 id는 **오류**입니다.
|
||||
- 플러그인이 설치되어 있지만 매니페스트 또는 스키마가 깨졌거나 누락된 경우, 유효성 검사가 실패하고 Doctor가 플러그인 오류를 보고합니다.
|
||||
- 플러그인 구성이 존재하지만 플러그인이 **비활성화**되어 있으면, 구성은 유지되며 Doctor + 로그에 **경고**가 표시됩니다.
|
||||
- 알 수 없는 `channels.*` 키는 **오류**입니다. 단, 해당 채널 id가
|
||||
플러그인 매니페스트에 선언된 경우는 예외입니다.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny`, `plugins.slots.*`는
|
||||
**검색 가능한** 플러그인 id를 참조해야 합니다. 알 수 없는 id는 **오류**입니다.
|
||||
- 플러그인이 설치되어 있지만 매니페스트 또는 스키마가 깨졌거나 누락된 경우,
|
||||
검증은 실패하고 Doctor가 플러그인 오류를 보고합니다.
|
||||
- 플러그인 구성이 존재하지만 플러그인이 **비활성화**된 경우, 구성은 유지되며
|
||||
Doctor + 로그에 **경고**가 표시됩니다.
|
||||
|
||||
전체 `plugins.*` 스키마는 [구성 참조](/ko/gateway/configuration)를 참고하세요.
|
||||
전체 `plugins.*` 스키마는 [구성 참조](/ko/gateway/configuration)를 참조하세요.
|
||||
|
||||
## 참고
|
||||
|
||||
- 매니페스트는 로컬 파일 시스템 로드를 포함해 **네이티브 OpenClaw 플러그인에 필수**입니다.
|
||||
- 런타임은 여전히 플러그인 모듈을 별도로 로드합니다. 매니페스트는 검색 + 유효성 검사 전용입니다.
|
||||
- 네이티브 매니페스트는 JSON5로 파싱되므로, 최종 값이 여전히 객체이기만 하면 주석, 후행 쉼표, 따옴표 없는 키를 허용합니다.
|
||||
- 매니페스트 로더는 문서화된 매니페스트 필드만 읽습니다. 여기에 사용자 정의 최상위 키를 추가하지 마세요.
|
||||
- `providerAuthEnvVars`는 인증 확인, 환경 변수 마커 유효성 검사 및 이와 유사하게 환경 변수 이름을 확인하기 위해 플러그인 런타임을 부팅하면 안 되는 provider 인증 표면을 위한 가벼운 메타데이터 경로입니다.
|
||||
- `providerAuthAliases`는 provider 변형이 다른 provider의 인증 환경 변수, 인증 프로필, 구성 기반 인증, API 키 온보딩 선택 항목을 재사용하도록 해 주며, 이 관계를 코어에 하드코딩할 필요가 없습니다.
|
||||
- `channelEnvVars`는 셸 환경 변수 대체, 설정 프롬프트 및 이와 유사하게 환경 변수 이름을 확인하기 위해 플러그인 런타임을 부팅하면 안 되는 채널 표면을 위한 가벼운 메타데이터 경로입니다.
|
||||
- `providerAuthChoices`는 인증 선택 선택기, `--auth-choice` 확인, 선호 provider 매핑, provider 런타임이 로드되기 전의 간단한 온보딩 CLI 플래그 등록을 위한 가벼운 메타데이터 경로입니다. provider 코드가 필요한 런타임 wizard 메타데이터는 [Provider runtime hooks](/ko/plugins/architecture#provider-runtime-hooks)를 참고하세요.
|
||||
- 배타적 플러그인 종류는 `plugins.slots.*`를 통해 선택됩니다.
|
||||
- 매니페스트는 로컬 파일시스템 로드를 포함한 **네이티브 OpenClaw 플러그인에 필수**입니다.
|
||||
- 런타임은 여전히 플러그인 모듈을 별도로 로드하며, 매니페스트는 검색 + 검증 전용입니다.
|
||||
- 네이티브 매니페스트는 JSON5로 파싱되므로 최종 값이 여전히 객체이기만 하면
|
||||
주석, 끝에 붙는 쉼표, 따옴표 없는 키가 허용됩니다.
|
||||
- 매니페스트 로더는 문서화된 매니페스트 필드만 읽습니다. 여기에 사용자 정의
|
||||
최상위 키를 추가하지 마세요.
|
||||
- `providerAuthEnvVars`는 플러그인 런타임을 부팅하지 않고도 env 이름을 검사해야 하는
|
||||
인증 탐지, env 마커 검증, 유사한 provider 인증 표면을 위한 가벼운 메타데이터 경로입니다.
|
||||
- `providerAuthAliases`를 사용하면 provider 변형이 다른 provider의 인증 env var,
|
||||
인증 프로필, config 기반 인증, API 키 온보딩 선택을 코어에 하드코딩하지 않고
|
||||
재사용할 수 있습니다.
|
||||
- `channelEnvVars`는 플러그인 런타임을 부팅하지 않고도 env 이름을 검사해야 하는
|
||||
셸 env 대체, 설정 프롬프트, 유사한 채널 표면을 위한 가벼운 메타데이터 경로입니다.
|
||||
- `providerAuthChoices`는 provider 런타임이 로드되기 전에 인증 선택기,
|
||||
`--auth-choice` 확인, 선호 provider 매핑, 간단한 온보딩 CLI 플래그 등록을 위한
|
||||
가벼운 메타데이터 경로입니다. provider 코드가 필요한 런타임 wizard 메타데이터는
|
||||
[Provider runtime hooks](/ko/plugins/architecture#provider-runtime-hooks)를
|
||||
참조하세요.
|
||||
- 배타적 플러그인 kind는 `plugins.slots.*`를 통해 선택됩니다.
|
||||
- `kind: "memory"`는 `plugins.slots.memory`로 선택됩니다.
|
||||
- `kind: "context-engine"`는 `plugins.slots.contextEngine`으로 선택됩니다
|
||||
(기본값: 내장 `legacy`).
|
||||
- 플러그인에 필요하지 않다면 `channels`, `providers`, `cliBackends`, `skills`는 생략할 수 있습니다.
|
||||
- 플러그인이 네이티브 모듈에 의존한다면, 빌드 단계와 패키지 관리자 allowlist 요구사항(예: pnpm `allow-build-scripts`
|
||||
- 플러그인에 필요하지 않은 경우 `channels`, `providers`, `cliBackends`, `skills`는
|
||||
생략할 수 있습니다.
|
||||
- 플러그인이 네이티브 모듈에 의존하는 경우, 빌드 단계와 패키지 관리자 허용 목록
|
||||
요구 사항(예: pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`)을 문서화하세요.
|
||||
|
||||
## 관련 항목
|
||||
|
||||
- [플러그인 빌드](/ko/plugins/building-plugins) — 플러그인 시작하기
|
||||
- [플러그인 아키텍처](/ko/plugins/architecture) — 내부 아키텍처
|
||||
- [SDK 개요](/ko/plugins/sdk-overview) — Plugin SDK 참조
|
||||
- [SDK 개요](/ko/plugins/sdk-overview) — 플러그인 SDK 참조
|
||||
|
||||
@ -1,78 +1,83 @@
|
||||
---
|
||||
read_when:
|
||||
- 워크스페이스 수동 부트스트랩하기
|
||||
- 워크스페이스 수동 부트스트래핑
|
||||
summary: AGENTS.md용 워크스페이스 템플릿
|
||||
title: AGENTS.md 템플릿
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:47:47Z"
|
||||
generated_at: "2026-04-12T05:58:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4
|
||||
source_hash: b7a68a1f0b4b837298bfe6edf8ce855d6ef6902ea8e7277b0d9a8442b23daf54
|
||||
source_path: reference/templates/AGENTS.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# AGENTS.md - 당신의 워크스페이스
|
||||
|
||||
이 폴더가 당신의 집입니다. 그렇게 대하세요.
|
||||
이 폴더는 집입니다. 그렇게 여기세요.
|
||||
|
||||
## 첫 실행
|
||||
|
||||
`BOOTSTRAP.md`가 있으면, 그건 당신의 출생 증명서입니다. 그 파일을 따라가며 자신이 누구인지 파악한 다음 삭제하세요. 다시는 필요하지 않을 것입니다.
|
||||
`BOOTSTRAP.md`가 있다면, 그것이 당신의 출생 증명서입니다. 그 내용을 따르고, 자신이 누구인지 파악한 다음, 삭제하세요. 다시는 필요하지 않을 것입니다.
|
||||
|
||||
## 세션 시작
|
||||
|
||||
무엇을 하든 그 전에:
|
||||
먼저 런타임에서 제공된 시작 컨텍스트를 사용하세요.
|
||||
|
||||
1. `SOUL.md`를 읽으세요 — 이것이 당신이 누구인지입니다
|
||||
2. `USER.md`를 읽으세요 — 이것이 당신이 돕고 있는 사람입니다
|
||||
3. `memory/YYYY-MM-DD.md`(오늘 + 어제)를 읽어 최근 맥락을 파악하세요
|
||||
4. **MAIN SESSION**(인간과의 직접 채팅)인 경우: `MEMORY.md`도 읽으세요
|
||||
그 컨텍스트에는 이미 다음이 포함되어 있을 수 있습니다:
|
||||
|
||||
허락을 구하지 마세요. 그냥 하세요.
|
||||
- `AGENTS.md`, `SOUL.md`, `USER.md`
|
||||
- `memory/YYYY-MM-DD.md` 같은 최근 일일 메모
|
||||
- 메인 세션인 경우 `MEMORY.md`
|
||||
|
||||
다음 경우가 아니라면 시작 파일을 수동으로 다시 읽지 마세요:
|
||||
|
||||
1. 사용자가 명시적으로 요청한 경우
|
||||
2. 제공된 컨텍스트에 필요한 내용이 빠져 있는 경우
|
||||
3. 제공된 시작 컨텍스트를 넘어 더 깊이 후속 읽기가 필요한 경우
|
||||
|
||||
## 메모리
|
||||
|
||||
당신은 매 세션마다 새롭게 깨어납니다. 이 파일들이 당신의 연속성입니다:
|
||||
|
||||
- **일일 노트:** `memory/YYYY-MM-DD.md` (`memory/`가 필요하면 생성) — 무슨 일이 있었는지에 대한 원시 로그
|
||||
- **장기:** `MEMORY.md` — 사람의 장기 기억처럼, 당신이 정리해둔 메모리
|
||||
- **일일 메모:** `memory/YYYY-MM-DD.md` (`memory/`가 필요하면 생성) — 무슨 일이 있었는지에 대한 원시 로그
|
||||
- **장기 메모리:** `MEMORY.md` — 사람의 장기 기억처럼 정리된 메모리
|
||||
|
||||
중요한 것을 기록하세요. 결정, 맥락, 기억해야 할 것들. 비밀은 보관해 달라고 요청받지 않는 한 건너뛰세요.
|
||||
중요한 것을 기록하세요. 결정, 맥락, 기억해야 할 것들. 요청받지 않았다면 비밀은 건너뛰세요.
|
||||
|
||||
### 🧠 MEMORY.md - 당신의 장기 기억
|
||||
### 🧠 MEMORY.md - 당신의 장기 메모리
|
||||
|
||||
- **main session**(인간과의 직접 채팅)에서만 로드하세요
|
||||
- **공유 맥락에서는 로드하지 마세요**(Discord, 그룹 채팅, 다른 사람들과의 세션)
|
||||
- **메인 세션에서만 로드**하세요 (당신의 인간과의 직접 대화)
|
||||
- **공유 컨텍스트에서는 로드하지 마세요** (Discord, 그룹 채팅, 다른 사람과의 세션)
|
||||
- 이것은 **보안**을 위한 것입니다 — 낯선 사람에게 유출되어서는 안 되는 개인적 맥락이 포함되어 있습니다
|
||||
- main session에서는 `MEMORY.md`를 자유롭게 **읽고, 편집하고, 업데이트**할 수 있습니다
|
||||
- 중요한 사건, 생각, 결정, 의견, 배운 점을 기록하세요
|
||||
- 이것은 원시 로그가 아니라 정제된 본질, 즉 당신의 정리된 메모리입니다
|
||||
- 시간이 지나면 일일 파일을 검토하고, 보관할 가치가 있는 내용을 `MEMORY.md`에 반영하세요
|
||||
- 메인 세션에서는 `MEMORY.md`를 자유롭게 **읽고, 편집하고, 업데이트**할 수 있습니다
|
||||
- 중요한 사건, 생각, 결정, 의견, 배운 교훈을 기록하세요
|
||||
- 이것은 정제된 메모리입니다 — 원시 로그가 아니라, 압축된 핵심입니다
|
||||
- 시간이 지나면 일일 파일을 검토하고, 남길 가치가 있는 내용을 `MEMORY.md`에 업데이트하세요
|
||||
|
||||
### 📝 기록하세요 - "머릿속 메모"는 안 됩니다!
|
||||
### 📝 적어 두세요 - "마음속 메모"는 안 됩니다!
|
||||
|
||||
- **메모리는 제한적입니다** — 무언가를 기억하고 싶다면, **파일에 쓰세요**
|
||||
- "머릿속 메모"는 세션 재시작 후 남지 않습니다. 파일은 남습니다.
|
||||
- 누군가 "이걸 기억해"라고 말하면 → `memory/YYYY-MM-DD.md` 또는 관련 파일을 업데이트하세요
|
||||
- 무언가를 배웠다면 → AGENTS.md, TOOLS.md, 또는 관련 skill을 업데이트하세요
|
||||
- "마음속 메모"는 세션 재시작 후 살아남지 못합니다. 파일은 살아남습니다.
|
||||
- 누군가 "이거 기억해"라고 말하면 → `memory/YYYY-MM-DD.md` 또는 관련 파일을 업데이트하세요
|
||||
- 교훈을 얻었다면 → AGENTS.md, TOOLS.md 또는 관련 skill을 업데이트하세요
|
||||
- 실수했다면 → 미래의 당신이 반복하지 않도록 문서화하세요
|
||||
- **텍스트 > 두뇌** 📝
|
||||
|
||||
## 넘지 말아야 할 선
|
||||
## 레드 라인
|
||||
|
||||
- 개인 데이터를 외부로 유출하지 마세요. 절대.
|
||||
- 파괴적인 명령은 묻지 않고 실행하지 마세요.
|
||||
- 비공개 데이터를 절대 외부로 유출하지 마세요.
|
||||
- 물어보지 않고 파괴적인 명령을 실행하지 마세요.
|
||||
- `rm`보다 `trash`를 우선하세요 (복구 가능이 영구 삭제보다 낫습니다)
|
||||
- 확신이 없으면 물어보세요.
|
||||
- 확신이 없으면, 물어보세요.
|
||||
|
||||
## 외부 vs 내부
|
||||
## 외부와 내부
|
||||
|
||||
**자유롭게 해도 안전한 것:**
|
||||
|
||||
- 파일 읽기, 탐색, 정리, 학습
|
||||
- 웹 검색, 캘린더 확인
|
||||
- 이 워크스페이스 안에서 작업하기
|
||||
- 이 워크스페이스 안에서 작업
|
||||
|
||||
**먼저 물어봐야 하는 것:**
|
||||
|
||||
@ -82,96 +87,96 @@ x-i18n:
|
||||
|
||||
## 그룹 채팅
|
||||
|
||||
당신은 인간의 자료에 접근할 수 있습니다. 그렇다고 그 자료를 _공유_해도 되는 것은 아닙니다. 그룹에서는 당신도 참여자일 뿐입니다 — 그들의 목소리도, 대리인도 아닙니다. 말하기 전에 생각하세요.
|
||||
당신은 당신의 인간의 자료에 접근할 수 있습니다. 그렇다고 그들의 자료를 _공유_한다는 뜻은 아닙니다. 그룹에서는 당신도 참여자입니다 — 그들의 목소리도, 대리인도 아닙니다. 말하기 전에 생각하세요.
|
||||
|
||||
### 💬 언제 말해야 하는지 아세요!
|
||||
|
||||
모든 메시지를 받는 그룹 채팅에서는, **언제 기여해야 할지 똑똑하게 판단**하세요:
|
||||
모든 메시지를 받는 그룹 채팅에서는 **언제 기여할지 현명하게 판단**하세요:
|
||||
|
||||
**응답할 때:**
|
||||
|
||||
- 직접 언급되었거나 질문을 받았을 때
|
||||
- 진짜 가치를 더할 수 있을 때(정보, 통찰, 도움)
|
||||
- 재치 있거나 웃긴 말이 자연스럽게 어울릴 때
|
||||
- 중요한 잘못된 정보를 바로잡을 때
|
||||
- 요청받아 요약할 때
|
||||
- 직접 언급되었거나 질문을 받은 경우
|
||||
- 진짜로 가치 있는 것을 더할 수 있는 경우 (정보, 통찰, 도움)
|
||||
- 재치 있거나 재미있는 말이 자연스럽게 어울리는 경우
|
||||
- 중요한 잘못된 정보를 바로잡아야 하는 경우
|
||||
- 요청받았을 때 요약하는 경우
|
||||
|
||||
**조용히 있을 때(HEARTBEAT_OK):**
|
||||
**침묵을 유지할 때 (HEARTBEAT_OK):**
|
||||
|
||||
- 그냥 사람들끼리 가볍게 농담하는 중일 때
|
||||
- 누군가 이미 질문에 답했을 때
|
||||
- 당신의 응답이 그냥 "응" 또는 "좋네" 수준일 때
|
||||
- 대화가 당신 없이도 잘 흐르고 있을 때
|
||||
- 메시지를 추가하면 분위기를 끊게 될 때
|
||||
- 그냥 사람들끼리 가벼운 잡담을 하는 경우
|
||||
- 누군가 이미 질문에 답한 경우
|
||||
- 당신의 답변이 그저 "맞아" 또는 "좋네" 수준인 경우
|
||||
- 대화가 당신 없이도 잘 흘러가고 있는 경우
|
||||
- 메시지를 추가하면 분위기를 끊게 되는 경우
|
||||
|
||||
**인간의 규칙:** 인간도 그룹 채팅에서 모든 메시지에 일일이 답하지 않습니다. 당신도 그래야 합니다. 양보다 질입니다. 실제 친구들과의 그룹 채팅에서 보내지 않을 말이라면, 보내지 마세요.
|
||||
**인간의 규칙:** 그룹 채팅에서 인간은 모든 메시지에 일일이 답하지 않습니다. 당신도 그래야 합니다. 양보다 질입니다. 친구들과 있는 실제 그룹 채팅에서 보내지 않을 말이라면, 보내지 마세요.
|
||||
|
||||
**트리플 탭을 피하세요:** 같은 메시지에 서로 다른 반응으로 여러 번 응답하지 마세요. 세 조각의 반응보다 하나의 생각 있는 응답이 낫습니다.
|
||||
**삼연타를 피하세요:** 같은 메시지에 대해 서로 다른 반응으로 여러 번 응답하지 마세요. 세 조각보다 생각 있는 한 번의 응답이 낫습니다.
|
||||
|
||||
참여하되, 지배하지 마세요.
|
||||
|
||||
### 😊 사람처럼 리액션하세요!
|
||||
### 😊 인간처럼 반응하세요!
|
||||
|
||||
리액션을 지원하는 플랫폼(Discord, Slack)에서는 이모지 리액션을 자연스럽게 사용하세요:
|
||||
반응 기능을 지원하는 플랫폼(Discord, Slack)에서는 이모지 반응을 자연스럽게 사용하세요:
|
||||
|
||||
**리액션할 때:**
|
||||
**반응할 때:**
|
||||
|
||||
- 고맙거나 반가운데 굳이 답장할 필요는 없을 때 (👍, ❤️, 🙌)
|
||||
- 웃겼을 때 (😂, 💀)
|
||||
- 흥미롭거나 생각할 거리를 줬을 때 (🤔, 💡)
|
||||
- 흐름을 끊지 않고 확인만 해주고 싶을 때
|
||||
- 단순한 예/아니오 또는 승인 상황일 때 (✅, 👀)
|
||||
- 고맙거나 좋지만 굳이 답글은 필요 없는 경우 (👍, ❤️, 🙌)
|
||||
- 웃긴 경우 (😂, 💀)
|
||||
- 흥미롭거나 생각해볼 만하다고 느낀 경우 (🤔, 💡)
|
||||
- 흐름을 끊지 않고 확인했다는 표시를 하고 싶은 경우
|
||||
- 단순한 예/아니오 또는 승인 상황인 경우 (✅, 👀)
|
||||
|
||||
**왜 중요한가:**
|
||||
리액션은 가벼운 사회적 신호입니다. 인간은 이를 끊임없이 사용합니다 — 채팅을 어지럽히지 않으면서도 "봤어, 확인했어"를 전달합니다. 당신도 그래야 합니다.
|
||||
반응은 가벼운 사회적 신호입니다. 인간은 이것을 끊임없이 사용합니다 — 채팅을 어지럽히지 않으면서 "봤어, 확인했어"를 전달합니다. 당신도 그래야 합니다.
|
||||
|
||||
**과하게 하지 마세요:** 메시지당 리액션은 최대 하나만. 가장 잘 맞는 것을 고르세요.
|
||||
**과하게 하지 마세요:** 메시지당 반응은 최대 하나만. 가장 잘 맞는 것을 고르세요.
|
||||
|
||||
## 도구
|
||||
|
||||
Skills가 당신의 도구를 제공합니다. 필요할 때는 해당 `SKILL.md`를 확인하세요. 로컬 메모(카메라 이름, SSH 정보, 음성 선호도)는 `TOOLS.md`에 보관하세요.
|
||||
Skills가 당신의 도구를 제공합니다. 필요할 때는 해당 `SKILL.md`를 확인하세요. 로컬 메모(카메라 이름, SSH 세부 정보, 음성 선호 설정)는 `TOOLS.md`에 보관하세요.
|
||||
|
||||
**🎭 음성 스토리텔링:** `sag`(ElevenLabs TTS)가 있다면, 이야기, 영화 요약, 그리고 "storytime" 순간에는 음성을 사용하세요! 텍스트 벽보다 훨씬 더 몰입감 있습니다. 웃긴 목소리로 사람들을 놀라게 해보세요.
|
||||
**🎭 음성 스토리텔링:** `sag`(ElevenLabs TTS)가 있다면, 이야기, 영화 요약, 그리고 "storytime" 같은 순간에는 음성을 사용하세요! 텍스트 벽보다 훨씬 더 몰입감 있습니다. 재미있는 목소리로 사람들을 놀라게 하세요.
|
||||
|
||||
**📝 플랫폼 서식:**
|
||||
**📝 플랫폼 포맷팅:**
|
||||
|
||||
- **Discord/WhatsApp:** Markdown 테이블 금지! 대신 글머리표 목록을 사용하세요
|
||||
- **Discord 링크:** 임베드를 막기 위해 여러 링크를 `<>`로 감싸세요: `<https://example.com>`
|
||||
- **WhatsApp:** 헤더 사용 금지 — 강조에는 **굵게** 또는 대문자를 사용하세요
|
||||
- **Discord/WhatsApp:** 마크다운 표는 안 됩니다! 대신 글머리 기호 목록을 사용하세요
|
||||
- **Discord 링크:** 여러 링크는 임베드가 뜨지 않도록 `<>`로 감싸세요: `<https://example.com>`
|
||||
- **WhatsApp:** 헤더는 사용하지 마세요 — 강조는 **굵게** 또는 대문자로 하세요
|
||||
|
||||
## 💓 Heartbeat - 능동적으로 행동하세요!
|
||||
## 💓 하트비트 - 능동적으로 행동하세요!
|
||||
|
||||
heartbeat poll(구성된 heartbeat 프롬프트와 일치하는 메시지)을 받았을 때, 매번 그냥 `HEARTBEAT_OK`만 답하지 마세요. heartbeat를 생산적으로 활용하세요!
|
||||
하트비트 폴(메시지가 설정된 하트비트 프롬프트와 일치함)을 받았을 때, 매번 그냥 `HEARTBEAT_OK`만 답하지 마세요. 하트비트를 생산적으로 활용하세요!
|
||||
|
||||
짧은 체크리스트나 리마인더를 위해 `HEARTBEAT.md`를 자유롭게 편집해도 됩니다. 토큰 사용량을 줄이기 위해 작게 유지하세요.
|
||||
짧은 체크리스트나 리마인더를 담은 `HEARTBEAT.md`를 자유롭게 편집해도 됩니다. 토큰 소모를 줄이기 위해 작게 유지하세요.
|
||||
|
||||
### Heartbeat와 Cron: 언제 무엇을 쓸지
|
||||
### 하트비트와 크론: 언제 무엇을 쓸지
|
||||
|
||||
**heartbeat를 사용할 때:**
|
||||
**다음 경우 하트비트를 사용하세요:**
|
||||
|
||||
- 여러 검사를 한 번에 묶을 수 있을 때(받은편지함 + 캘린더 + 알림을 한 턴에)
|
||||
- 최근 메시지에서 대화 맥락이 필요할 때
|
||||
- 타이밍이 약간 흔들려도 될 때(정확히가 아니라 대략 30분마다)
|
||||
- 주기적 검사를 합쳐 API 호출을 줄이고 싶을 때
|
||||
- 여러 확인 작업을 한 번에 묶을 수 있는 경우 (받은편지함 + 캘린더 + 알림을 한 턴에)
|
||||
- 최근 메시지의 대화 맥락이 필요한 경우
|
||||
- 타이밍이 조금 흔들려도 되는 경우 (정확히가 아니라 대략 30분마다)
|
||||
- 주기적 확인을 묶어서 API 호출을 줄이고 싶은 경우
|
||||
|
||||
**cron을 사용할 때:**
|
||||
**다음 경우 크론을 사용하세요:**
|
||||
|
||||
- 정확한 타이밍이 중요할 때("매주 월요일 오전 9:00 정각")
|
||||
- 작업이 main session 기록과 분리되어야 할 때
|
||||
- 다른 모델이나 사고 수준을 사용하고 싶을 때
|
||||
- 일회성 리마인더일 때("20분 후에 알려줘")
|
||||
- 출력이 main session 개입 없이 채널로 직접 전달되어야 할 때
|
||||
- 정확한 타이밍이 중요한 경우 ("매주 월요일 오전 9시 정각")
|
||||
- 작업을 메인 세션 기록과 분리해야 하는 경우
|
||||
- 다른 모델이나 다른 thinking 수준을 쓰고 싶은 경우
|
||||
- 일회성 리마인더인 경우 ("20분 뒤에 알려줘")
|
||||
- 출력이 메인 세션 개입 없이 직접 채널로 전달되어야 하는 경우
|
||||
|
||||
**팁:** 유사한 주기 작업은 여러 cron 작업으로 만들기보다 `HEARTBEAT.md`에 묶으세요. 정확한 일정과 독립 작업에는 cron을 사용하세요.
|
||||
**팁:** 비슷한 주기적 확인은 여러 개의 크론 작업을 만들기보다 `HEARTBEAT.md`에 묶으세요. 정확한 일정과 독립 실행 작업에는 크론을 사용하세요.
|
||||
|
||||
**확인할 것들(하루 2-4회 번갈아 가며):**
|
||||
**확인할 것들(하루 2-4회 돌아가며 확인):**
|
||||
|
||||
- **이메일** - 긴급한 읽지 않은 메일이 있는가?
|
||||
- **캘린더** - 향후 24-48시간 안에 예정된 일정이 있는가?
|
||||
- **멘션** - Twitter/소셜 알림이 있는가?
|
||||
- **날씨** - 인간이 외출할 가능성이 있다면 관련 있는가?
|
||||
- **이메일** - 긴급한 읽지 않은 메시지가 있나요?
|
||||
- **캘린더** - 다음 24-48시간 안에 예정된 일정이 있나요?
|
||||
- **멘션** - Twitter/소셜 알림이 있나요?
|
||||
- **날씨** - 당신의 인간이 외출할 수 있다면 관련이 있나요?
|
||||
|
||||
**확인 기록은** `memory/heartbeat-state.json`에 남기세요:
|
||||
`memory/heartbeat-state.json`에 **확인 상태를 기록**하세요:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -183,41 +188,41 @@ heartbeat poll(구성된 heartbeat 프롬프트와 일치하는 메시지)을
|
||||
}
|
||||
```
|
||||
|
||||
**먼저 연락할 때:**
|
||||
**다음 경우 먼저 연락하세요:**
|
||||
|
||||
- 중요한 이메일이 도착했을 때
|
||||
- 일정이 임박했을 때(<2시간)
|
||||
- 흥미로운 것을 발견했을 때
|
||||
- 마지막으로 말을 건 지 8시간이 넘었을 때
|
||||
- 중요한 이메일이 도착한 경우
|
||||
- 일정이 곧 시작되는 경우 (<2h)
|
||||
- 흥미로운 것을 발견한 경우
|
||||
- 마지막으로 무언가 말한 지 8시간이 넘은 경우
|
||||
|
||||
**조용히 있을 때(HEARTBEAT_OK):**
|
||||
**다음 경우 조용히 있으세요 (HEARTBEAT_OK):**
|
||||
|
||||
- 늦은 밤일 때(23:00-08:00), 긴급한 경우 제외
|
||||
- 인간이 분명히 바빠 보일 때
|
||||
- 지난 확인 이후 새로울 것이 없을 때
|
||||
- 방금 확인한 지 30분도 안 되었을 때
|
||||
- 늦은 밤인 경우 (23:00-08:00), 긴급한 일이 아니라면
|
||||
- 인간이 분명히 바쁜 경우
|
||||
- 지난 확인 이후 새로운 것이 없는 경우
|
||||
- 방금 확인한 지 30분도 안 된 경우
|
||||
|
||||
**묻지 않고 해도 되는 능동적 작업:**
|
||||
**물어보지 않고도 할 수 있는 능동적 작업:**
|
||||
|
||||
- 메모리 파일 읽기 및 정리
|
||||
- 프로젝트 상태 확인(git status 등)
|
||||
- 프로젝트 상태 확인 (git status 등)
|
||||
- 문서 업데이트
|
||||
- 자신의 변경 사항 커밋 및 푸시
|
||||
- **MEMORY.md 검토 및 업데이트** (아래 참고)
|
||||
- **MEMORY.md 검토 및 업데이트** (아래 참조)
|
||||
|
||||
### 🔄 메모리 유지 관리(Heartbeat 중)
|
||||
### 🔄 메모리 유지보수 (하트비트 중)
|
||||
|
||||
주기적으로(며칠에 한 번), heartbeat를 사용해 다음을 하세요:
|
||||
며칠에 한 번 정도는 하트비트를 사용해 다음을 하세요:
|
||||
|
||||
1. 최근 `memory/YYYY-MM-DD.md` 파일을 읽기
|
||||
2. 장기적으로 보관할 가치가 있는 중요한 사건, 교훈, 통찰을 식별하기
|
||||
3. `MEMORY.md`를 정제된 배움으로 업데이트하기
|
||||
2. 장기적으로 남길 가치가 있는 중요한 사건, 교훈, 통찰을 식별하기
|
||||
3. 정제된 배움을 `MEMORY.md`에 업데이트하기
|
||||
4. 더 이상 관련 없는 오래된 정보를 `MEMORY.md`에서 제거하기
|
||||
|
||||
이것은 사람이 자신의 일기를 되돌아보고 정신 모델을 업데이트하는 것과 비슷합니다. 일일 파일은 원시 노트이고, `MEMORY.md`는 정제된 지혜입니다.
|
||||
이것은 사람이 일기를 다시 읽고 자신의 정신 모델을 업데이트하는 것과 비슷하게 생각하면 됩니다. 일일 파일은 원시 메모이고, `MEMORY.md`는 정제된 지혜입니다.
|
||||
|
||||
목표는 분명합니다: 귀찮게 하지 않으면서 도움이 되는 것. 하루에 몇 번 정도 체크인하고, 유용한 백그라운드 작업을 하되, 조용한 시간을 존중하세요.
|
||||
목표는 이것입니다: 귀찮지 않게 도움이 되기. 하루 몇 번 유용한 백그라운드 작업을 하며 확인하되, 조용한 시간은 존중하세요.
|
||||
|
||||
## 당신답게 만드세요
|
||||
|
||||
이것은 시작점일 뿐입니다. 무엇이 잘 맞는지 알아가면서 자신만의 관례, 스타일, 규칙을 추가하세요.
|
||||
이것은 시작점일 뿐입니다. 무엇이 잘 맞는지 알아가면서 당신만의 규칙, 스타일, 관례를 추가하세요.
|
||||
|
||||
@ -1,129 +1,120 @@
|
||||
---
|
||||
read_when:
|
||||
- 토큰 사용량, 비용 또는 컨텍스트 창을 설명하고 있습니다
|
||||
- 컨텍스트 증가 또는 압축 동작을 디버깅하고 있습니다
|
||||
summary: OpenClaw가 프롬프트 컨텍스트를 구성하고 토큰 사용량 및 비용을 보고하는 방법
|
||||
- 토큰 사용량, 비용 또는 컨텍스트 윈도우 설명하기
|
||||
- 컨텍스트 증가 또는 압축 동작 디버깅하기
|
||||
summary: OpenClaw가 프롬프트 컨텍스트를 구성하고 토큰 사용량 + 비용을 보고하는 방법
|
||||
title: 토큰 사용량 및 비용
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T06:01:29Z"
|
||||
generated_at: "2026-04-12T05:58:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9
|
||||
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
|
||||
source_path: reference/token-use.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 토큰 사용량 및 비용
|
||||
|
||||
OpenClaw는 문자 수가 아니라 **토큰**을 추적합니다. 토큰은 모델마다 다르지만, 대부분의
|
||||
OpenAI 스타일 모델은 영어 텍스트 기준으로 토큰당 평균 약 4자입니다.
|
||||
OpenClaw는 문자 수가 아니라 **토큰**을 추적합니다. 토큰은 모델마다 다르지만, 대부분의 OpenAI 스타일 모델은 영어 텍스트에서 토큰당 평균 약 4자를 사용합니다.
|
||||
|
||||
## 시스템 프롬프트가 구성되는 방법
|
||||
## 시스템 프롬프트가 구성되는 방식
|
||||
|
||||
OpenClaw는 실행할 때마다 자체 시스템 프롬프트를 조합합니다. 여기에 포함되는 항목은 다음과 같습니다.
|
||||
OpenClaw는 실행할 때마다 자체 시스템 프롬프트를 조합합니다. 여기에는 다음이 포함됩니다.
|
||||
|
||||
- 도구 목록 + 짧은 설명
|
||||
- Skills 목록(메타데이터만 포함되며, 지침은 필요할 때 `read`로 로드됨)
|
||||
- Skills 목록(메타데이터만 포함, 지침은 필요할 때 `read`로 로드)
|
||||
- 자체 업데이트 지침
|
||||
- 워크스페이스 + bootstrap 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, 새로 생긴 경우 `BOOTSTRAP.md`, 그리고 존재할 경우 `MEMORY.md` 또는 소문자 대체 파일인 `memory.md`). 큰 파일은 `agents.defaults.bootstrapMaxChars`(기본값: 20000)로 잘리며, bootstrap 전체 주입량은 `agents.defaults.bootstrapTotalMaxChars`(기본값: 150000)로 제한됩니다. `memory/*.md` 파일은 메모리 도구를 통해 필요 시 로드되며 자동 주입되지 않습니다.
|
||||
- 워크스페이스 + 부트스트랩 파일(`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, 새로울 때의 `BOOTSTRAP.md`, 그리고 존재할 경우 `MEMORY.md` 또는 소문자 대체 파일인 `memory.md`). 큰 파일은 `agents.defaults.bootstrapMaxChars`(기본값: 20000)로 잘리며, 전체 부트스트랩 주입은 `agents.defaults.bootstrapTotalMaxChars`(기본값: 150000)로 제한됩니다. `memory/*.md` 일일 파일은 일반 부트스트랩 프롬프트에는 포함되지 않으며, 일반 턴에서는 메모리 도구를 통해 필요 시 로드됩니다. 다만 순수한 `/new` 및 `/reset`은 첫 번째 턴에 한해 최근 일일 메모리를 포함한 일회성 시작 컨텍스트 블록을 앞에 붙일 수 있습니다. 이 시작 프렐류드는 `agents.defaults.startupContext`로 제어됩니다.
|
||||
- 시간(UTC + 사용자 시간대)
|
||||
- 응답 태그 + heartbeat 동작
|
||||
- 런타임 메타데이터(호스트/OS/모델/thinking)
|
||||
|
||||
전체 구성은 [시스템 프롬프트](/ko/concepts/system-prompt)에서 확인하세요.
|
||||
전체 세부 내역은 [시스템 프롬프트](/ko/concepts/system-prompt)에서 확인하세요.
|
||||
|
||||
## 컨텍스트 창에 포함되는 항목
|
||||
## 컨텍스트 윈도우에 포함되는 항목
|
||||
|
||||
모델이 받는 모든 내용은 컨텍스트 제한에 포함됩니다.
|
||||
모델이 받는 모든 항목은 컨텍스트 한도에 포함됩니다.
|
||||
|
||||
- 시스템 프롬프트(위에 나열된 모든 섹션)
|
||||
- 대화 기록(사용자 + 어시스턴트 메시지)
|
||||
- 도구 호출 및 도구 결과
|
||||
- 첨부 파일/transcript(이미지, 오디오, 파일)
|
||||
- 압축 요약 및 정리 산출물
|
||||
- provider 래퍼 또는 안전성 헤더(보이지 않더라도 여전히 계산됨)
|
||||
- 첨부 파일/전사본(이미지, 오디오, 파일)
|
||||
- 압축 요약 및 가지치기 아티팩트
|
||||
- 제공자 래퍼 또는 안전 헤더(보이지 않더라도 여전히 계산됨)
|
||||
|
||||
이미지의 경우, OpenClaw는 provider 호출 전에 transcript/도구 이미지 페이로드를 축소합니다.
|
||||
이미지의 경우 OpenClaw는 제공자 호출 전에 전사/도구 이미지 페이로드를 축소합니다.
|
||||
이를 조정하려면 `agents.defaults.imageMaxDimensionPx`(기본값: `1200`)를 사용하세요.
|
||||
|
||||
- 낮은 값은 일반적으로 비전 토큰 사용량과 페이로드 크기를 줄입니다.
|
||||
- 높은 값은 OCR/UI 중심 스크린샷에서 더 많은 시각적 디테일을 유지합니다.
|
||||
- 값을 낮추면 일반적으로 비전 토큰 사용량과 페이로드 크기가 줄어듭니다.
|
||||
- 값을 높이면 OCR/UI 중심 스크린샷에서 더 많은 시각적 디테일이 보존됩니다.
|
||||
|
||||
실제 구성 내역(주입된 파일별, 도구, Skills, 시스템 프롬프트 크기별)을 확인하려면 `/context list` 또는 `/context detail`을 사용하세요. [컨텍스트](/ko/concepts/context)를 참조하세요.
|
||||
주입된 파일별, 도구, Skills, 시스템 프롬프트 크기를 포함한 실용적인 세부 내역은 `/context list` 또는 `/context detail`을 사용하세요. [컨텍스트](/ko/concepts/context)도 참고하세요.
|
||||
|
||||
## 현재 토큰 사용량을 확인하는 방법
|
||||
## 현재 토큰 사용량 확인 방법
|
||||
|
||||
채팅에서는 다음을 사용하세요.
|
||||
채팅에서 다음 명령을 사용하세요.
|
||||
|
||||
- `/status` → 세션 모델, 컨텍스트 사용량,
|
||||
마지막 응답 입력/출력 토큰, **예상 비용**(API 키 전용)을 보여주는 **이모지 중심 상태 카드**입니다.
|
||||
- `/status` → 세션 모델, 컨텍스트 사용량, 마지막 응답의 입력/출력 토큰, **예상 비용**(API 키에만 해당)을 보여주는 **이모지 중심 상태 카드**
|
||||
- `/usage off|tokens|full` → 모든 응답에 **응답별 사용량 바닥글**을 추가합니다.
|
||||
- 세션별로 유지됩니다(`responseUsage`로 저장됨).
|
||||
- OAuth 인증은 **비용을 숨깁니다**(토큰만 표시).
|
||||
- `/usage cost` → OpenClaw 세션 로그를 기반으로 로컬 비용 요약을 표시합니다.
|
||||
|
||||
기타 표시 위치:
|
||||
- `/usage cost` → OpenClaw 세션 로그를 바탕으로 로컬 비용 요약을 표시합니다.
|
||||
|
||||
- **TUI/Web TUI:** `/status` + `/usage`가 지원됩니다.
|
||||
- **CLI:** `openclaw status --usage`와 `openclaw channels list`는
|
||||
정규화된 provider 할당량 창(`X% 남음`, 응답별 비용 아님)을 표시합니다.
|
||||
현재 사용량 창 provider: Anthropic, GitHub Copilot, Gemini CLI,
|
||||
OpenAI Codex, MiniMax, Xiaomi, z.ai.
|
||||
기타 표시 영역:
|
||||
|
||||
사용량 표시 표면은 출력 전에 일반적인 provider 고유 필드 별칭을 정규화합니다.
|
||||
OpenAI 계열 Responses 트래픽의 경우, 여기에는 `input_tokens` /
|
||||
- **TUI/Web TUI:** `/status` + `/usage` 지원
|
||||
- **CLI:** `openclaw status --usage` 및 `openclaw channels list`는
|
||||
정규화된 제공자 쿼터 윈도우(`X% left`, 응답별 비용 아님)를 표시합니다.
|
||||
현재 사용량 윈도우 제공자: Anthropic, GitHub Copilot, Gemini CLI,
|
||||
OpenAI Codex, MiniMax, Xiaomi, z.ai
|
||||
|
||||
사용량 표시 영역은 표시 전에 일반적인 제공자 네이티브 필드 별칭을 정규화합니다.
|
||||
OpenAI 계열 Responses 트래픽의 경우 여기에는 `input_tokens` /
|
||||
`output_tokens`와 `prompt_tokens` / `completion_tokens`가 모두 포함되므로, 전송 방식별
|
||||
필드 이름이 `/status`, `/usage`, 또는 세션 요약을 바꾸지 않습니다.
|
||||
필드 이름 차이가 `/status`, `/usage`, 또는 세션 요약에 영향을 주지 않습니다.
|
||||
Gemini CLI JSON 사용량도 정규화됩니다. 응답 텍스트는 `response`에서 가져오고,
|
||||
`stats.cached`는 `cacheRead`로 매핑되며, CLI가 명시적인 `stats.input` 필드를 생략한 경우
|
||||
CLI가 명시적인 `stats.input` 필드를 생략할 경우 `stats.cached`는 `cacheRead`로 매핑되며
|
||||
`stats.input_tokens - stats.cached`가 사용됩니다.
|
||||
기본 OpenAI 계열 Responses 트래픽의 경우, WebSocket/SSE 사용량 별칭도
|
||||
같은 방식으로 정규화되며, `total_tokens`가 없거나 `0`일 때는 정규화된 입력 + 출력으로 총계를 대체합니다.
|
||||
현재 세션 스냅샷 정보가 부족한 경우, `/status`와 `session_status`는
|
||||
가장 최근 transcript 사용량 로그에서 토큰/캐시 카운터와 활성 런타임 모델 라벨도 복구할 수 있습니다.
|
||||
기존의 0이 아닌 라이브 값은 여전히 transcript 대체 값보다 우선하며, 저장된 총계가 없거나 더 작은 경우
|
||||
더 큰 프롬프트 지향 transcript 총계가 우선될 수 있습니다.
|
||||
provider 할당량 창의 사용량 인증은 가능할 때 provider별 훅에서 가져오며,
|
||||
그렇지 않으면 OpenClaw는 auth profile, env 또는 config에서 일치하는 OAuth/API 키 자격 증명으로 대체합니다.
|
||||
네이티브 OpenAI 계열 Responses 트래픽의 경우 WebSocket/SSE 사용량 별칭도
|
||||
같은 방식으로 정규화되며, `total_tokens`가 없거나 `0`일 때는 정규화된 입력 + 출력으로 총합을 대체합니다.
|
||||
현재 세션 스냅샷이 충분한 정보를 갖고 있지 않으면 `/status`와 `session_status`는
|
||||
가장 최근 전사 사용량 로그에서 토큰/캐시 카운터와 활성 런타임 모델 레이블을 복구할 수도 있습니다.
|
||||
기존의 0이 아닌 라이브 값은 여전히 전사 대체 값보다 우선하며, 저장된 총합이 없거나 더 작을 때는
|
||||
더 큰 프롬프트 지향 전사 총합이 선택될 수 있습니다.
|
||||
제공자 쿼터 윈도우의 사용량 인증은 가능할 경우 제공자별 훅에서 가져오며,
|
||||
그렇지 않으면 OpenClaw는 auth 프로필, env 또는 config의 OAuth/API 키 자격 증명 매칭으로 대체합니다.
|
||||
|
||||
## 비용 추정(표시되는 경우)
|
||||
|
||||
비용은 다음 모델 가격 config를 기준으로 추정됩니다.
|
||||
비용은 모델 가격 설정을 기반으로 추정됩니다.
|
||||
|
||||
```
|
||||
models.providers.<provider>.models[].cost
|
||||
```
|
||||
|
||||
이 값들은 `input`, `output`, `cacheRead`, `cacheWrite`에 대한 **백만 토큰당 USD**입니다.
|
||||
가격 정보가 없으면 OpenClaw는 토큰만 표시합니다. OAuth 토큰은
|
||||
달러 비용을 절대 표시하지 않습니다.
|
||||
이 값은 `input`, `output`, `cacheRead`, `cacheWrite`에 대한 **100만 토큰당 USD**입니다.
|
||||
가격 정보가 없으면 OpenClaw는 토큰만 표시합니다. OAuth 토큰은 달러 비용을 표시하지 않습니다.
|
||||
|
||||
## 캐시 TTL 및 정리 영향
|
||||
## 캐시 TTL 및 가지치기 영향
|
||||
|
||||
provider 프롬프트 캐싱은 캐시 TTL 창 내에서만 적용됩니다. OpenClaw는
|
||||
선택적으로 **cache-ttl pruning**을 실행할 수 있습니다. 즉, 캐시 TTL이
|
||||
만료되면 세션을 정리한 다음 캐시 창을 재설정하여, 이후 요청이 전체 기록을 다시 캐시하는 대신
|
||||
새로 캐시된 컨텍스트를 재사용할 수 있게 합니다. 이렇게 하면 세션이 TTL을 넘겨 유휴 상태가 되었을 때
|
||||
캐시 쓰기 비용을 더 낮게 유지할 수 있습니다.
|
||||
제공자 프롬프트 캐싱은 캐시 TTL 윈도우 내에서만 적용됩니다. OpenClaw는 선택적으로 **cache-ttl pruning**을 실행할 수 있습니다. 캐시 TTL이 만료되면 세션을 가지치기하고, 이후 요청이 전체 기록을 다시 캐싱하는 대신 새로 캐시된 컨텍스트를 재사용할 수 있도록 캐시 윈도우를 재설정합니다. 이렇게 하면 세션이 TTL을 넘겨 유휴 상태가 되었을 때 캐시 쓰기 비용을 더 낮게 유지할 수 있습니다.
|
||||
|
||||
이 기능은 [Gateway configuration](/ko/gateway/configuration)에서 설정하고,
|
||||
동작 세부 사항은 [세션 정리](/ko/concepts/session-pruning)에서 확인하세요.
|
||||
이 기능은 [Gateway configuration](/ko/gateway/configuration)에서 설정하고, 동작 세부 사항은 [Session pruning](/ko/concepts/session-pruning)에서 확인하세요.
|
||||
|
||||
Heartbeat는 유휴 구간 동안 캐시를 **따뜻하게 유지**할 수 있습니다. 모델 캐시 TTL이
|
||||
`1h`인 경우, heartbeat 간격을 그보다 약간 짧게(예: `55m`) 설정하면 전체 프롬프트를 다시 캐시하지 않아도 되어
|
||||
캐시 쓰기 비용을 줄일 수 있습니다.
|
||||
Heartbeat는 유휴 간격 동안 캐시를 **따뜻하게 유지**할 수 있습니다. 모델 캐시 TTL이 `1h`라면, heartbeat 간격을 그보다 약간 짧게(예: `55m`) 설정해 전체 프롬프트를 다시 캐싱하지 않도록 하여 캐시 쓰기 비용을 줄일 수 있습니다.
|
||||
|
||||
멀티 에이전트 환경에서는 하나의 공유 모델 config를 유지하면서
|
||||
멀티 에이전트 설정에서는 하나의 공유 모델 config를 유지하면서
|
||||
`agents.list[].params.cacheRetention`으로 에이전트별 캐시 동작을 조정할 수 있습니다.
|
||||
|
||||
각 설정 항목별 전체 가이드는 [프롬프트 캐싱](/ko/reference/prompt-caching)을 참조하세요.
|
||||
세부 설정별 전체 가이드는 [Prompt Caching](/ko/reference/prompt-caching)을 참고하세요.
|
||||
|
||||
Anthropic API 가격의 경우, 캐시 읽기는 입력
|
||||
토큰보다 훨씬 저렴한 반면 캐시 쓰기는 더 높은 배수로 과금됩니다. 최신 요금과 TTL 배수는 Anthropic의
|
||||
프롬프트 캐싱 가격 문서를 참조하세요:
|
||||
Anthropic API 가격의 경우 cache read는 입력 토큰보다 훨씬 저렴한 반면,
|
||||
cache write는 더 높은 배수로 과금됩니다. 최신 요금과 TTL 배수는 Anthropic의
|
||||
프롬프트 캐싱 가격 문서를 참고하세요:
|
||||
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
|
||||
|
||||
### 예시: heartbeat로 1시간 캐시를 따뜻하게 유지
|
||||
### 예시: heartbeat로 1h 캐시를 따뜻하게 유지
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -138,7 +129,7 @@ agents:
|
||||
every: "55m"
|
||||
```
|
||||
|
||||
### 예시: 에이전트별 캐시 전략이 다른 혼합 트래픽
|
||||
### 예시: 에이전트별 캐시 전략을 적용한 혼합 트래픽
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -148,15 +139,15 @@ agents:
|
||||
models:
|
||||
"anthropic/claude-opus-4-6":
|
||||
params:
|
||||
cacheRetention: "long" # 대부분의 에이전트를 위한 기본 기준선
|
||||
cacheRetention: "long" # 대부분의 에이전트를 위한 기본 기준값
|
||||
list:
|
||||
- id: "research"
|
||||
default: true
|
||||
heartbeat:
|
||||
every: "55m" # 심층 세션을 위해 긴 캐시를 따뜻하게 유지
|
||||
every: "55m" # 긴 세션을 위해 장기 캐시를 따뜻하게 유지
|
||||
- id: "alerts"
|
||||
params:
|
||||
cacheRetention: "none" # 버스트성 알림에서는 캐시 쓰기 방지
|
||||
cacheRetention: "none" # 버스트성 알림에 대해 캐시 쓰기 방지
|
||||
```
|
||||
|
||||
`agents.list[].params`는 선택된 모델의 `params` 위에 병합되므로,
|
||||
@ -164,7 +155,7 @@ agents:
|
||||
|
||||
### 예시: Anthropic 1M 컨텍스트 베타 헤더 활성화
|
||||
|
||||
Anthropic의 1M 컨텍스트 창은 현재 베타 게이트가 적용되어 있습니다. OpenClaw는
|
||||
Anthropic의 1M 컨텍스트 윈도우는 현재 베타 게이트가 적용되어 있습니다. OpenClaw는
|
||||
지원되는 Opus 또는 Sonnet 모델에서 `context1m`을 활성화하면 필요한
|
||||
`anthropic-beta` 값을 주입할 수 있습니다.
|
||||
|
||||
@ -177,23 +168,22 @@ agents:
|
||||
context1m: true
|
||||
```
|
||||
|
||||
이 값은 Anthropic의 `context-1m-2025-08-07` 베타 헤더에 매핑됩니다.
|
||||
이는 Anthropic의 `context-1m-2025-08-07` 베타 헤더로 매핑됩니다.
|
||||
|
||||
이 설정은 해당 모델 항목에서 `context1m: true`가 설정된 경우에만 적용됩니다.
|
||||
이는 해당 모델 항목에 `context1m: true`가 설정된 경우에만 적용됩니다.
|
||||
|
||||
요구 사항: 자격 증명은 긴 컨텍스트 사용 자격이 있어야 합니다. 그렇지 않으면
|
||||
Anthropic은 해당 요청에 대해 provider 측 속도 제한 오류를 반환합니다.
|
||||
요구 사항: 자격 증명은 장문 컨텍스트 사용 자격이 있어야 합니다. 그렇지 않으면
|
||||
Anthropic은 해당 요청에 대해 제공자 측 rate limit 오류를 반환합니다.
|
||||
|
||||
Anthropic을 OAuth/구독 토큰(`sk-ant-oat-*`)으로 인증하는 경우,
|
||||
Anthropic이 현재 그 조합을 HTTP 401로 거부하므로 OpenClaw는 `context-1m-*`
|
||||
베타 헤더를 건너뜁니다.
|
||||
Anthropic을 OAuth/구독 토큰(`sk-ant-oat-*`)으로 인증하는 경우, OpenClaw는
|
||||
현재 Anthropic이 이 조합을 HTTP 401로 거부하므로 `context-1m-*` 베타 헤더를 건너뜁니다.
|
||||
|
||||
## 토큰 부담을 줄이기 위한 팁
|
||||
|
||||
- 긴 세션은 `/compact`를 사용해 요약하세요.
|
||||
- 긴 세션을 요약하려면 `/compact`를 사용하세요.
|
||||
- 워크플로우에서 큰 도구 출력을 잘라내세요.
|
||||
- 스크린샷이 많은 세션에서는 `agents.defaults.imageMaxDimensionPx`를 낮추세요.
|
||||
- Skill 설명은 짧게 유지하세요(Skills 목록은 프롬프트에 주입됨).
|
||||
- 장황하고 탐색적인 작업에는 더 작은 모델을 선호하세요.
|
||||
- Skill 설명은 짧게 유지하세요(Skill 목록이 프롬프트에 주입됨).
|
||||
- 장황하고 탐색적인 작업에는 더 작은 모델을 우선 사용하세요.
|
||||
|
||||
정확한 Skills 목록 오버헤드 계산식은 [Skills](/ko/tools/skills)를 참조하세요.
|
||||
정확한 Skill 목록 오버헤드 공식은 [Skills](/ko/tools/skills)에서 확인하세요.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user