컨텍스트

“컨텍스트”란 OpenClaw가 한 번의 실행에서 모델에 보내는 모든 것입니다. 모델의 컨텍스트 윈도우(토큰 한계)에 의해 제한됩니다.

초보자를 위한 개념 정리:

시스템 프롬프트 (OpenClaw 생성): 규칙, 도구, 스킬 목록, 시간/런타임, 주입된 워크스페이스 파일.
대화 히스토리: 이 세션에서의 사용자 메시지 + 어시스턴트 메시지.
도구 호출/결과 + 첨부파일: 명령어 출력, 파일 읽기, 이미지/오디오 등.

컨텍스트는 “메모리”와 동일한 개념이 아닙니다. 메모리는 디스크에 저장되어 나중에 다시 로드할 수 있고, 컨텍스트는 모델의 현재 윈도우 안에 있는 것입니다.

빠른 시작 (컨텍스트 확인)

/status → 간단한 “윈도우가 얼마나 찼나?” 확인 + 세션 설정.
/context list → 주입된 항목 + 대략적인 크기 (파일별 + 합계).
/context detail → 상세 분석: 파일별, 도구 스키마 크기별, 스킬 항목 크기별, 시스템 프롬프트 크기.
/usage tokens → 일반 응답에 요청별 사용량 푸터를 추가.
/compact → 이전 히스토리를 간결한 항목으로 요약하여 윈도우 공간 확보.

참고: 슬래시 명령어, 토큰 사용량 & 비용, 압축.

출력 예시

값은 모델, 프로바이더, 도구 정책, 워크스페이스 내용에 따라 달라집니다.

`/context list`

🧠 Context breakdown
Workspace: <workspaceDir>
Bootstrap max/file: 20,000 chars
Sandbox: mode=non-main sandboxed=false
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))

Injected workspace files:
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
- HEARTBEAT.md: MISSING | raw 0 | injected 0
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)

Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
Tool list (system prompt text): 1,032 chars (~258 tok)
Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text)
Tools: (same as above)

Session tokens (cached): 14,250 total / ctx=32,000

`/context detail`

🧠 Context breakdown (detailed)
…
Top skills (prompt entry size):
- frontend-design: 412 chars (~103 tok)
- oracle: 401 chars (~101 tok)
… (+10 more skills)

Top tools (schema size):
- browser: 9,812 chars (~2,453 tok)
- exec: 6,240 chars (~1,560 tok)
… (+N more tools)

컨텍스트 윈도우에 포함되는 것

모델이 수신하는 모든 것이 포함됩니다:

시스템 프롬프트 (모든 섹션).
대화 히스토리.
도구 호출 + 도구 결과.
첨부파일/트랜스크립트 (이미지/오디오/파일).
압축 요약 및 프루닝 아티팩트.
프로바이더 “래퍼” 또는 숨겨진 헤더 (보이지 않지만 여전히 카운트됨).

OpenClaw가 시스템 프롬프트를 구성하는 방법

시스템 프롬프트는 OpenClaw가 소유하며 매 실행마다 재구성됩니다. 포함 내용:

도구 목록 + 짧은 설명.
스킬 목록 (메타데이터만, 아래 참고).
워크스페이스 위치.
시간 (UTC + 설정된 경우 사용자 시간으로 변환).
런타임 메타데이터 (호스트/OS/모델/thinking).
Project Context 아래 주입된 워크스페이스 부트스트랩 파일.

전체 분석: 시스템 프롬프트.

주입된 워크스페이스 파일 (Project Context)

기본적으로 OpenClaw는 다음 워크스페이스 파일을 (존재하면) 고정 세트로 주입합니다:

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
BOOTSTRAP.md (최초 실행 전용)

큰 파일은 agents.defaults.bootstrapMaxChars (기본값 20000자)로 파일별 잘림이 적용됩니다. OpenClaw는 또한 agents.defaults.bootstrapTotalMaxChars (기본값 150000자)로 전체 부트스트랩 주입 상한도 적용합니다. /context에서 원본 vs 주입 크기와 잘림 여부를 확인할 수 있습니다.

잘림이 발생하면 런타임이 Project Context 아래에 프롬프트 내 경고 블록을 주입할 수 있습니다. agents.defaults.bootstrapPromptTruncationWarning (off, once, always, 기본값 once)으로 설정합니다.

스킬: 주입되는 것 vs 필요 시 로드

시스템 프롬프트에는 간결한 스킬 목록(이름 + 설명 + 위치)이 포함됩니다. 이 목록은 실제 오버헤드가 있습니다.

스킬 지침은 기본적으로 포함되지 않습니다. 모델은 필요할 때만 스킬의 SKILL.md를 read하도록 기대됩니다.

도구: 두 가지 비용

도구는 두 가지 방식으로 컨텍스트에 영향을 줍니다:

도구 목록 텍스트: 시스템 프롬프트에 “Tooling”으로 표시되는 내용.
도구 스키마 (JSON): 모델이 도구를 호출할 수 있도록 전송됩니다. 일반 텍스트로 보이지 않더라도 컨텍스트에 포함됩니다.

/context detail에서 가장 큰 도구 스키마를 분류하여 무엇이 지배적인지 확인할 수 있습니다.

명령어, 디렉티브, “인라인 단축키”

슬래시 명령어는 게이트웨이에서 처리됩니다. 몇 가지 다른 동작이 있습니다:

독립 명령어: /...만으로 구성된 메시지는 명령어로 실행됩니다.
디렉티브: /think, /verbose, /reasoning, /elevated, /model, /queue는 모델에 메시지가 전달되기 전에 제거됩니다.
- 디렉티브만 있는 메시지는 세션 설정을 저장합니다.
- 일반 메시지 내 인라인 디렉티브는 메시지별 힌트로 작용합니다.
인라인 단축키 (허용된 발신자 전용): 일반 메시지 내 특정 /... 토큰이 즉시 실행되고 (예: “hey /status”), 나머지 텍스트가 모델에 전달되기 전에 제거됩니다.

자세한 내용: 슬래시 명령어.

세션, 압축, 프루닝 (영속되는 것)

메시지 간 영속되는 것은 메커니즘에 따라 다릅니다:

일반 히스토리: 정책에 의해 압축/프루닝되기 전까지 세션 트랜스크립트에 영속됩니다.
압축: 요약을 트랜스크립트에 영속하고 최근 메시지는 그대로 유지합니다.
프루닝: 실행의 인메모리 프롬프트에서 이전 도구 결과를 제거하지만 트랜스크립트를 다시 쓰지는 않습니다.

문서: 세션, 압축, 세션 프루닝.

기본적으로 OpenClaw는 내장 legacy 컨텍스트 엔진을 사용하여 조립과 압축을 수행합니다. kind: "context-engine"을 제공하는 플러그인을 설치하고 plugins.slots.contextEngine으로 선택하면, OpenClaw가 컨텍스트 조립, /compact, 관련 서브에이전트 컨텍스트 생명주기 훅을 해당 엔진에 위임합니다.

`/context`가 실제로 보고하는 것

/context는 가능한 경우 최신 실행 시 구성된 시스템 프롬프트 리포트를 우선합니다:

System prompt (run) = 마지막 임베디드(도구 가능) 실행에서 캡처되어 세션 스토어에 영속.
System prompt (estimate) = 실행 리포트가 없거나 리포트를 생성하지 않는 CLI 백엔드에서 실행 시 즉석 계산.

어느 경우든 크기와 주요 기여 요소를 보고하며, 전체 시스템 프롬프트나 도구 스키마를 덤프하지는 않습니다.