OpenClaw Context 이해하고 관리하기

모델과 긴 대화를 나누다 보면 어느 순간 모델이 이전 내용을 잊어버리거나 대답이 부정확해지는 느낌을 받을 때가 있죠. 제한된 컨텍스트 윈도우 안에서 어떤 정보가 우선적으로 전달되고 있는지 파악하지 못하면, 중요한 프로젝트 파일이나 지시 사항이 누락되어 개발 흐름이 끊길 수 있어요.

OpenClaw에서 “Context”는 실행 시 모델로 전송되는 모든 데이터를 의미해요. 이는 모델의 토큰 제한(Context Window) 내에 머물러야 하며, 단순히 디스크에 저장되는 “Memory”와는 다른 개념이에요.

필요한 것

• OpenClaw 실행 환경
• 프로젝트 워크스페이스 및 Markdown 설정 파일 (AGENTS.md, SOUL.md 등)

빠른 시작

OpenClaw가 현재 모델에게 무엇을 보내고 있는지 5분 안에 확인하는 방법이에요.

1. 상태 확인: /status를 입력해서 현재 컨텍스트 윈도우가 얼마나 찼는지와 세션 설정을 빠르게 확인하세요.
2. 목록 점검: /context list를 사용해 주입된 파일들과 각각의 대략적인 크기를 확인하세요.
3. 상세 분석: /context detail로 개별 Tool Schema와 Skill 항목이 차지하는 비중을 심층적으로 분석하세요.
4. 토큰 추적: /usage tokens를 입력하면 이후 모든 답변 하단에 토큰 사용량 푸터가 추가돼요.
5. 공간 확보: 컨텍스트가 부족하다면 /compact 명령어로 이전 대화 기록을 요약해서 공간을 확보하세요.

Context 구성 요소

모델이 받는 컨텍스트에는 다음과 같은 항목들이 포함돼요.

• System Prompt: OpenClaw가 매번 새로 빌드하는 규칙, 도구 목록, Skill 리스트, 워크스페이스 파일이 포함돼요.
• Conversation History: 이번 세션에서 주고받은 메시지 기록이에요.
• Tool Calls & Results: 실행된 명령어 결과, 파일 읽기 내용 등 도구 사용 기록이에요.
• Attachments: 이미지, 오디오, 파일 등 첨부된 데이터예요.

Project Context (워크스페이스 파일)

OpenClaw는 워크스페이스에 있는 특정 Markdown 파일들을 자동으로 주입해요. 기본적으로 다음 파일들을 찾아서 포함시켜요.

• AGENTS.md, SOUL.md
• TOOLS.md, IDENTITY.md
• USER.md, HEARTBEAT.md
• BOOTSTRAP.md (첫 실행 시에만 포함)

파일이 너무 크면 agents.defaults.bootstrapMaxChars 설정(기본값 20,000자)에 따라 내용이 잘릴 수 있어요.

Tool과 Skill의 비용

도구와 스킬은 컨텍스트 공간을 다르게 사용해요.

• Tools: 두 가지 비용이 발생해요. System Prompt에 들어가는 설명 텍스트와, 모델이 도구를 호출할 때 필요한 JSON 형태의 Tool Schemas 비용이에요.
• Skills: System Prompt에는 이름과 설명만 포함된 요약 리스트가 들어가요. 실제 상세 지침은 모델이 필요할 때만 read 도구로 해당 SKILL.md 파일을 읽어서 가져와요.

/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)

Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills)
Tool schemas (JSON): 31,988 chars (~7,997 tok)

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

문제 해결

• 파일 상태가 TRUNCATED로 표시됨: 파일 내용이 설정된 최대 글자수(20,000자)를 초과했다는 뜻이에요. 파일 내용을 줄이거나 설정을 변경해야 해요.
• 파일 상태가 MISSING으로 표시됨: 워크스페이스에 해당 파일이 존재하지 않는 경우예요. 파일 이름과 경로를 확인하세요.

---

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Slash commands 알아보기
• Compaction으로 컨텍스트 최적화하기
• Token use & costs 확인하기
• System Prompt 구조 이해하기