OpenClaw 에이전트 시스템 프롬프트 아키텍처 심층 분석: 9단계 구조 완벽 가이드

This document provides a detailed breakdown of the complete System Prompt structure sent by OpenClaw Agent to the LLM.

Translate: "이 문서는 OpenClaw Agent가 LLM에 전송하는 전체 시스템 프롬프트 구조를 상세히 분석합니다."

Keep empty <p></p> as is.

Version:

Translate: "버전:"

v2.1

Keep as is? v2.1 is a version number, no translation needed.

Update Time:

Translate: "업데이트 시간:"

2026-03-05

Keep as is.

Then the headings and content. For headings like "## Overall Architecture Diagram" - translate "Overall Architecture Diagram" to "전체 아키텍처 다이어그램" but keep the markdown formatting.

We'll translate the entire text, maintaining all markdown, blockquotes, payload-block tags, and preserving the structure.

Note: The text has some English technical terms like "TL;DR", "Identity", "Bootstrap Hook", "Workspace Files", "System Prompt", "LLM", etc. We should keep most of them as is, but some can be translated if natural. For example, "TL;DR" is fine as is, but "Workspace Files" could be "작업 공간 파일" or keep as "Workspace Files". Given the guideline to preserve technical terms, we'll keep them in English but with Korean spacing around them when adjacent to Korean text.

Also need to handle the JSON example: translate the description values but keep keys and structure. For example, "description": "Read file content. Supports text files and images..." => translate the description string.

Let's write the translation step by step.</think><blockquote>

<p>이 문서는 OpenClaw Agent가 LLM에 전송하는 전체 시스템 프롬프트 구조를 상세히 분석합니다.</p>

</blockquote>

버전:

v2.1

업데이트 시간:

2026-03-05

전체 아키텍처 다이어그램

빠른 내비게이션 (TL;DR)

초보자 필독:

1. 레이어 7 (Workspace Files) - 직접 편집할 수 있는 설정 파일입니다.
2. 레이어 8 (Bootstrap Hook) - 콘텐츠를 동적으로 주입하는 스크립트를 작성할 수 있습니다.
3. 나머지 레이어는 프레임워크에서 자동 생성되므로 이해만 하면 됩니다.

일반적인 요구사항:

• Agent의 정체성을 정의하고 싶다면? → 레이어 7의 IDENTITY.md를 편집하세요.
• 프로젝트 문서를 추가하고 싶다면? → 레이어 8의 bootstrap-extra-files Hook을 사용하세요.
• 실시간 컨텍스트를 주입하고 싶다면? → 레이어 8의 before_prompt_build Hook을 사용하세요.
• 파일 크기를 제어하고 싶다면? → bootstrapMaxChars 설정을 조정하세요.

레이어 1: OpenClaw 프레임워크 코어

비유

마치 작동 설명서의 "사용 지침" 부분과 같아서, LLM에게 자신이 누구인지, 무엇을 할 수 있는지, 어떻게 응답해야 하는지를 알려줍니다.

구성 요소

실제 예시

You are running as a "Creative Partner," an AI content creation expert Agent.

Current Time: 2026-03-05 14:37:00 CST

=== Tool Calling Specification ===

• Use XML-style tool calling format.
• Each tool call must include a unique tool_call_id.
• Tool results are returned via <tool_result> tags.
• Consider AbortSignal when executing tools to support cancellation.

=== Safety Boundaries ===

• Strictly prohibited from executing destructive operations (rm -rf, formatting, etc.).
• Sensitive user information must be encrypted when handled.
• Prohibited from sending messages to unauthorized channels.

디자인 트레이드오프

왜 이렇게 설계했을까요?

• 트레이드오프: 유연성 vs. 일관성
• 결정: 프레임워크 레이어에서 통합 생성하여 모든 Agent의 기본 동작을 일관되게 보장합니다.
• 장점: 사용자가 모든 Agent에 기본 규칙을 반복할 필요가 없습니다. 프레임워크가 업그레이드되면 모든 Agent가 자동으로 새로운 기능을 얻습니다. 설정 오류 위험을 줄입니다.
• 비용: 사용자는 이러한 핵심 규칙을 수정할 수 없습니다. 특수 동작은 레이어 7/8을 통해 간접적으로 구현해야 합니다.

레이어 2: 도구 정의

비유

마치 스위스 아미 나이프의 도구 목록과 같아서, LLM에게 어떤 도구가 있는지, 각 도구가 무엇을 하는지, 어떻게 사용하는지 알려줍니다.

구성 요소

도구 정의 예시

{

"name": "read",

"description": "파일 내용을 읽습니다. 텍스트 파일과 이미지(jpg/png/gif/webp)를 지원합니다. 이미지는 첨부 파일로 전송됩니다. 텍스트 출력은 2000줄 또는 50KB로 제한됩니다.",

"parameters": {

"type": "object",

"properties": {

"path": {

"type": "string",

"description": "파일 경로 (상대 또는 절대)"

},

"offset": {

"type": "number",

"description": "시작 라인 번호 (1부터 시작)"

},

"limit": {

"type": "number",

"description": "읽을 최대 라인 수"

}

},

"required": ["path"]

}

}

디자인 트레이드오프

왜 JSON Schema를 사용하나요?

• 트레이드오프: 유연성 vs. 타입 안전성
• 결정: 엄격한 JSON Schema를 사용하여 도구 매개변수를 정의합니다.
• 장점: LLM이 도구 사용법을 더 정확하게 이해합니다. 프레임워크가 호출 전에 매개변수를 검증할 수 있습니다. 문서와 타입 정의가 자동 생성됩니다.
• 비용: 새 도구를 추가하려면 전체 Schema를 작성해야 합니다. 완전히 동적인 매개변수 구조는 지원할 수 없습니다.

레이어 3: 스킬 레지스트리

비유

마치 레스토랑의 "스페셜티 메뉴"와 같아서, LLM에게 어떤 전문 "레시피"를 호출할 수 있는지 알려줍니다.

디자인 트레이드오프

왜 수동 등록 대신 디렉토리 스캔을 사용하나요?

• 트레이드오프: 유연성 vs. 유지보수 비용
• 결정: ~/development/openclaw/skills/ 디렉토리를 자동 스캔합니다.
• 장점: 새 Skill을 추가하려면 디렉토리에 넣기만 하면 되며 설정 변경이 필요 없습니다. 모든 Agent가 자동으로 새 Skill을 얻습니다. 설정 오류 위험을 줄입니다.
• 비용: 각 Agent에서 사용할 Skill을 정밀하게 제어할 수 없습니다. 모든 Skill이 System Prompt에 주입됩니다 (토큰 소비 증가).

구성 요소

레이어 4: 모델 별칭

비유

마치 "단축키"와 같아서, 복잡한 모델 경로에 짧은 별칭을 부여하여 쉽게 호출할 수 있습니다.

디자인 트레이드오프

왜 모델 별칭이 필요한가요?

• 트레이드오프: 유연성 vs. 가독성
• 결정: 사용자가 자주 사용하는 모델에 대해 짧은 별칭을 정의할 수 있도록 합니다.
• 장점: 모델 호출을 간소화합니다 (glm-5 대신 zhipu/glm-5). 여러 Provider 간 전환을 지원합니다 (동일한 별칭이 다른 Provider에 매핑될 수 있음). A/B 테스트 및 모델 마이그레이션을 용이하게 합니다.
• 비용: 별칭 설정 파일을 유지해야 합니다. 혼란을 야기할 수 있습니다 (동일한 별칭이 Agent마다 다른 모델을 가리킬 수 있음).

구성 요소

실제 예시

System Prompt에서 모델 별칭은 다음과 같이 표시됩니다:

Model Aliases

• GLM-5: zhipu/glm-5
• Opus 4.6: xiaowang886/claude-opus-4-6-thinking
• Sonnet 4.5: xiaowang886/claude-sonnet-4-5

LLM은 별칭을 사용하여 모델을 전환할 수 있습니다: /model glm-5

레이어 5: 프로토콜 사양

비유

마치 "교통 규칙"과 같아서, Agent가 시스템과 상호 작용하는 표준 프로토콜을 정의합니다.

디자인 트레이드오프

왜 프로토콜 사양이 필요한가요?

• 트레이드오프: 자유도 vs. 일관성
• 결정: 표준화된 상호 작용 프로토콜 (Silent Replies, Heartbeats, Reply Tags 등)을 정의합니다.
• 장점: 모든 Agent에서 일관된 동작을 보장합니다. 자동 모니터링 및 상태 확인을 지원합니다. 다중 Agent 협업을 단순화합니다.
• 비용: Agent의 표현 자유도를 제한합니다. LLM이 프로토콜을 엄격히 따라야 합니다 (무시될 수 있음).

구성 요소

실제 예시

Silent Replies 예시:

User: Received

Agent: NO_REPLY

Heartbeats 예시:

System: [Heartbeat Poll]

Agent: HEARTBEAT_OK

Reply Tags 예시:

Agent: [[reply_to_current]] Task completed ✓

레이어 6: 런타임 정보

비유

마치 "대시보드"와 같아서, LLM에게 현재 실행 환경의 실시간 상태를 알려줍니다.

디자인 트레이드오프

왜 매번 런타임 정보를 주입하나요?

• 트레이드오프: 토큰 소비 vs. 컨텍스트 정확성
• 결정: 모든 요청마다 최신 런타임 상태를 주입합니다.
• 장점: LLM이 현재 시간을 알 수 있습니다 (시간 혼동 방지). LLM이 현재 모델을 알 수 있습니다 (능력 오판 방지). LLM이 현재 환경을 알 수 있습니다 (경로 오류 방지).
• 비용: 요청당 약 2KB의 토큰을 소비합니다. 정보에 중복이 포함될 수 있습니다.

구성 요소

실제 예시

Runtime

레이어 7: Workspace Files ★ 사용자 제어 가능

비유

마치 "작업 노트"와 같아서, 직접 편집할 수 있는 정적 설정 파일입니다.

디자인 트레이드오프

왜 이 레이어만 정적으로 편집 가능한가요?

• 트레이드오프: 프레임워크 안정성 vs. 사용자 자유도
• 결정: "변하는 것"과 "변하지 않는 것"을 분리합니다. 프레임워크 레이어는 일관성을 보장하고 사용자 레이어는 개인화를 허용합니다.
• 장점: 사용자는 Agent의 정체성, 작업 사양, 메모리를 정의할 수 있습니다. 프레임워크 업그레이드가 사용자 설정을 망가뜨리지 않습니다. 설정 파일을 버전 관리, 백업, 공유할 수 있습니다.
• 비용: 사용자는 코어 프레임워크 동작을 수정할 수 없습니다. TELOS 프레임워크와 파일 구조를 학습해야 합니다.

핵심 파일

레이어 8: Bootstrap Hook 시스템 ★ 사용자 제어 가능

비유

마치 "프로그래밍 가능한 주사기"와 같아서, 스크립트를 작성하여 런타임에 System Prompt에 동적으로 콘텐츠를 주입할 수 있습니다.

디자인 트레이드오프

왜 Hook 시스템이 필요한가요?

• 트레이드오프: 정적 설정의 단순성 vs. 동적 주입의 유연성
• 결정: 정적 Workspace Files와 함께 동적 Hook 메커니즘을 제공합니다.
• 장점: 컨텍스트 (채널, 발신자, 시간)에 따라 주입 콘텐츠를 동적으로 조정할 수 있습니다. 셸 명령을 실행하고 출력을 주입할 수 있습니다 (예: 현재 날씨, Git 상태). 외부 파일을 읽고 주입할 수 있습니다 (예: 프로젝트 문서, API 문서). 조건부 로직 (if/else)을 지원합니다.
• 비용: Hook 시스템 구문과 트리거 메커니즘을 학습해야 합니다. Hook 스크립트 오류는 System Prompt 이상을 유발할 수 있습니다. 시스템 복잡성이 증가합니다.

네 가지 Hook 메커니즘

1. agent:bootstrap Hook (내부 Hook 시스템)

트리거 위치: bootstrap-hooks.ts의 applyBootstrapHookOverrides()

기능:

• bootstrapFiles 배열을 완전히 제어할 수 있습니다.
• 파일을 추가, 삭제 또는 수정할 수 있습니다.
• 파일 순서를 변경할 수 있습니다.
• 파일 내용을 수정할 수 있습니다.

등록 가능한 대상:

• OpenClaw 플러그인.
• Workspace Hooks (~/.openclaw/workspace-*/hooks/ 디렉토리).
• 내부 모듈.

코드 예시:

registerInternalHook("agent:bootstrap", (event) => {

const context = event.context as AgentBootstrapHookContext;

// Full control over bootstrapFiles array

context.bootstrapFiles = [

{ path: "CUSTOM.md", content: "Custom Content" }

];

});

1. bootstrap-extra-files Hook (번들 Hook)

트리거 위치: hooks/bundled/bootstrap-extra-files/의 handler.ts

기능:

• 파일만 추가하며 기존 파일을 수정하지 않습니다.
• 설정 파일을 통해 추가 파일을 지정합니다.

설정 예시:

{

"hooks": {

"bootstrap-extra-files": {

"enabled": true,

"paths": ["extra/*.md", "docs/CONTEXT.md"]

}

}

}

적용 시나리오:

• 프로젝트별 컨텍스트 파일을 주입해야 하는 경우.
• 기본 8개의 Bootstrap 파일을 수정하고 싶지 않은 경우.
• 추가 문서를 동적으로 로드해야 하는 경우.

1. before_prompt_build Hook (플러그인 Hook)

트리거 위치: attempt.ts의 runBeforePromptBuild()

기능:

• 최종 프롬프트를 수정합니다 (시스템 프롬프트 구성 후, LLM에 전송 전).
• 컨텍스트를 앞에 추가할 수 있습니다 (프롬프트 앞에 콘텐츠 추가).
• systemPrompt를 재정의할 수 있습니다.

이벤트 데이터:

{

prompt: string; // User input

messages: unknown[]; // Session message history

}

반환 값:

{

prependContext?: string; // 프롬프트 앞에 추가할 콘텐츠

systemPrompt?: string; // 시스템 프롬프트 재정의

}

적용 시나리오:

• 세션 기록에 따라 프롬프트를 동적으로 조정해야 하는 경우.
• 실시간 컨텍스트 (예: 현재 시간, 날씨)를 주입해야 하는 경우.
• 시스템 프롬프트를 완전히 교체해야 하는 경우.

1. bootstrapMaxChars / bootstrapTotalMaxChars (설정 항목)

유형: 설정 항목 (Hook 아님)

기능:

• 문자 예산을 제어합니다.
• 단일 파일 기본값: 20K.
• 총 기본값: 150K.
• 초과 시 처음 70% + 마지막 20%를 유지하여 자릅니다.

설정 위치:

{

"agents": {

"defaults": {

"bootstrapMaxChars": 20000,

"bootstrapTotalMaxChars": 150000

}

}

}

실용적인 조언

시나리오 1: 프로젝트 문서를 추가하고 싶다면

추천 솔루션: bootstrap-extra-files

{

"hooks": {

"bootstrap-extra-files": {

"enabled": true,

"paths": ["docs/API.md", "docs/ARCHITECTURE.md"]

}

}

}

시나리오 2: 작업 유형에 따라 파일을 동적으로 로드하고 싶다면

추천 솔루션: 사용자 정의 agent:bootstrap Hook

registerInternalHook("agent:bootstrap", (event) => {

const context = event.context as AgentBootstrapHookContext;

const sessionKey = context.sessionKey;

// 세션 유형에 따라 다른 파일 로드

if (sessionKey.includes("coding")) {

context.bootstrapFiles.push({

path: "CODING_GUIDELINES.md",

content: fs.readFileSync("...").toString()

});

}

});

시나리오 3: 실시간 컨텍스트 (예: 현재 시간)를 주입하고 싶다면

추천 솔루션: before_prompt_build Hook

on("before_prompt_build", (event, ctx) => {

return {

prependContext: Current Time: ${new Date().toISOString()}

};

});

레이어 9: 인바운드 컨텍스트

비유

마치 "실시간 교통 정보"와 같아서, 매 요청마다 현재 대화의 컨텍스트 정보를 동적으로 주입합니다.

디자인 트레이드오프

왜 매번 컨텍스트를 주입하나요?

• 트레이드오프: 토큰 소비 vs. 대화 일관성
• 결정: 모든 요청마다 최신 메시지 메타데이터, 발신자 정보, 대화 기록을 주입합니다.
• 장점: LLM이 현재 누가 말하고 있는지 알 수 있습니다 (발신자 혼동 방지). LLM이 대화 기록을 알 수 있습니다 (컨텍스트 일관성 유지). LLM이 자신이 @멘션되었는지 알 수 있습니다 (응답 여부 결정).
• 비용: 요청당 약 3KB의 토큰을 소비합니다. 대화 기록에 노이즈가 포함될 수 있습니다.

구성 요소

전체 System Prompt 조립 과정

사용자 제어 가능 레이어 요약

OpenClaw는 3가지 유형의 사용자 제어 메커니즘을 제공합니다:

1. 레이어 7 (Workspace Files) - 정적 설정 파일. 시나리오: Agent 정체성, 작업 사양, 메모리 정의. 장점: 간단하고 직관적이며 버전 관리가 쉽습니다. 단점: 동적으로 조정할 수 없습니다.
2. 레이어 8 (Bootstrap Hook 시스템) - 동적 주입 스크립트. 시나리오: 컨텍스트에 따라 콘텐츠 주입, 명령 실행, 외부 파일 읽기. 장점: 유연하고 강력하며 로직과 명령을 지원합니다. 단점: Hook 시스템 학습 필요; 스크립트 오류가 문제를 유발할 수 있습니다.
3. 레이어 9 (인바운드 컨텍스트) 간접 제어 - 메시지를 보내 컨텍스트에 영향. 시나리오: 채팅 기록이나 인용 메시지를 통해 LLM 동작에 영향. 장점: 설정 불필요, 자연스러운 상호작용. 단점: 정밀하게 제어할 수 없습니다.

크기 비교표

⚠️

참고: 다음 데이터는 추정치이며, 실제 크기는 설정 및 런타임 컨텍스트에 따라 달라집니다. 프레임워크 레이어 (레이어 1-6 + 9)는 이론적으로 동일해야 하지만, 도구 정의, 로드된 Skills 등에 따라 약간 다를 수 있습니다.

참고:

• 레이어 7과 레이어 8은 사용자 제어 가능하며 크기는 Agent 설정에 따라 다릅니다.
• 다른 레이어는 자동 생성되며 이론적으로 모든 Agent에서 동일합니다.
• 실제 측정은 도구 가용성, Skills 로딩, 런타임 컨텍스트에 따라 다를 수 있습니다.

최적화 제안

1. 사용자 제어 부분 최적화 (레이어 7 + 8)

레이어 7과 8은 사용자가 제어하므로, 최적화 전략은 다음과 같습니다:

레이어 7 (정적 파일) 최적화:

✅ 권장되는 간소화 전략:

• IDENTITY.md: 핵심 TELOS 프레임워크를 유지하고, 중복 설명을 제거하며, 단락 대신 표를 사용하세요.
• AGENTS.md: 긴 단락 대신 체크리스트를 사용하고, 명령어는 코드 블록으로 표시하며, 중복 규칙 설명을 제거하세요.
• MEMORY.md: MemOS 자동 내보내기에 의존하고, 수동으로 콘텐츠를 추가하지 마세요 — 시스템이 유지하도록 하세요.

❌ 피해야 할 관행:

• OpenClaw 프레임워크가 이미 알고 있는 설명을 반복하지 마세요.
• 상세한 Skill 설명을 Workspace Files에 복사하지 마세요.
• 과도한 수사나 장식적인 언어를 사용하지 마세요.

레이어 8 (Hook 시스템) 최적화:

✅ 권장 사용 전략:

• 단순 시나리오에서는 bootstrap-extra-files를 우선 사용하세요.
• 조건부 로직이 필요한 복잡한 시나리오에서는 agent:bootstrap을 사용하세요.
• 동적 시나리오에서 실시간 컨텍스트가 필요하면 before_prompt_build를 사용하세요.

❌ 피해야 할 관행:

• Hook에서 시간이 오래 걸리는 작업을 실행하지 마세요 (System Prompt 생성을 차단합니다).
• Hook에 너무 많은 콘텐츠를 주입하지 마세요 (토큰 제한을 초과합니다).
• Hook에서 불안정한 외부 종속성을 사용하지 마세요 (시작 실패를 유발합니다).

1. 프롬프트 정리 전략

System Prompt가 너무 큰 경우 다음을 고려하세요:

결론

OpenClaw의 System Prompt는 단일 파일이 아니라, 정교하게 조정된 9개 레이어 아키텍처입니다:

• 레이어 1-6: 프레임워크에서 자동 생성되어 일관성과 안정성을 보장합니다.
• 레이어 7: 사용자가 편집 가능한 정적 설정 파일 (IDENTITY.md, AGENTS.md 등).
• 레이어 8: 사용자가 프로그래밍 가능한 동적 주입 스크립트 (Bootstrap Hook 시스템).
• 레이어 9: 프레임워크에서 자동 주입하는 실시간 컨텍스트 (인바운드 컨텍스트).

사용자가 제어할 수 있는 레이어는 2개 (레이어 7 + 8)이며, 이전에 잘못 알려진 레이어 7만이 아닙니다.

이 레이어 간의 차이점과 연결성을 이해하는 것이 OpenClaw 구성을 마스터하는 열쇠입니다.