개요
시스템 프롬프트(System Prompt)는 AI 에이전트의 동작을 안내하는 핵심 지시사항입니다. OpenClaw은 정적인 프롬프트 템플릿을 사용하지 않고, buildAgentSystemPrompt() 함수를 통해 동적으로 시스템 프롬프트를 구성합니다. 이 함수는 15가지 이상의 매개변수 유형을 수신하며, 현재 채널, 사용자 역할, 사용 가능한 도구 및 세션 컨텍스트에 따라 고도로 커스터마이징된 프롬프트를 생성합니다.
buildAgentSystemPrompt() 메커니즘
이 함수는 OpenClaw 시스템 프롬프트의 핵심 빌더입니다. 새로운 에이전트 세션이 생성될 때마다 시스템이 이 함수를 호출하여 현재 컨텍스트에 적합한 시스템 프롬프트를 생성합니다. Pi SDK가 직접 임베딩되어 있으므로(서브프로세스 호출이 아님), 이 구성 과정은 동일한 런타임에서 완료되며 직렬화 오버헤드가 없습니다.
매개변수 유형 개요
buildAgentSystemPrompt()가 지원하는 주요 매개변수 유형은 다음과 같습니다:
- channelType: 현재 채널 유형 (Discord / Telegram / Slack / WhatsApp)
- channelId: 채널 고유 식별자
- userId: 현재 사용자 ID
- userRole: 사용자 역할 (관리자, 일반 사용자, 게스트 등)
- availableTools: 현재 사용 가능한 도구 목록
- toolDescriptions: 도구의 상세 설명 정보
- sessionHistory: 세션 기록 요약
- customInstructions: 사용자 커스텀 지시사항
- languagePreference: 언어 선호 설정
- responseFormat: 기대하는 응답 형식
- safetyPolicy: 안전 정책 설정
- knowledgeBase: 지식 베이스 참조
- extensionPrompts: 로드된 확장의 프롬프트 조각
- timeContext: 시간 컨텍스트 (시간대, 현재 시간)
- platformConstraints: 플랫폼 고유 제약사항 (예: 메시지 길이 상한)
- memoryContext: 영구 메모리 컨텍스트
채널별 동적 커스터마이징
시스템 프롬프트의 가장 중요한 동적 차원은 채널 적응입니다. 각 플랫폼은 서로 다른 상호작용 규범과 기술적 제약이 있습니다:
Discord 채널
Discord용 시스템 프롬프트에는 다음이 포함됩니다: 임베드 메시지 형식 설명, Markdown 렌더링 규칙, 이모지 사용 가이드, 스레드 상호작용 규범, 그리고 2000자 메시지 길이 제한 알림.
Telegram 채널
Telegram 환경에서는 시스템 프롬프트에 다음이 추가됩니다: 인라인 키보드 상호작용 설명, HTML 포매팅 규칙(Telegram은 전체 Markdown이 아닌 HTML을 사용), 파일 전송 기능 설명, 그리고 4096자 메시지 제한.
Slack 채널
Slack의 시스템 프롬프트에는 다음이 포함됩니다: Block Kit 형식 설명, 스레드 답변 규범, 앱 메시지와 사용자 메시지의 구분, 그리고 워크스페이스 관련 컨텍스트 정보.
WhatsApp 채널
WhatsApp 시나리오에서는 다음이 주입됩니다: 간결한 답변 스타일 지시, 제한된 포매팅 지원 설명, 미디어 메시지 처리 방식 등.
커스텀 지시사항 계층
시스템이 자동으로 생성하는 콘텐츠 외에도, 관리자와 사용자는 여러 계층에서 커스텀 지시사항을 주입할 수 있습니다:
전역 지시사항
OpenClaw 설정 파일에 설정된 전역 지시사항으로, 모든 채널과 모든 사용자에게 적용됩니다. 여기에는 보통 AI 에이전트의 기본 페르소나, 핵심 행동 규범 및 공통 안전 정책을 배치합니다.
채널 수준 지시사항
각 채널은 독립적인 커스텀 지시사항을 가질 수 있습니다. 예를 들어, 기술 지원 채널에는 도메인 지식과 문제 해결 프로세스를 주입하고, 잡담 채널에는 더 가벼운 대화 스타일을 설정할 수 있습니다.
사용자 수준 지시사항
개별 사용자는 언어 선호, 응답 상세도 등 자신의 선호 지시사항을 설정할 수 있습니다. 이러한 지시사항은 구성 과정에서 최종 시스템 프롬프트에 병합됩니다.
확장 프롬프트 통합
OpenClaw이 확장(Extension)을 로드하면, 각 확장은 자체 프롬프트 조각을 제공할 수 있습니다. buildAgentSystemPrompt()는 이러한 조각을 수집하여 시스템 프롬프트의 적절한 위치에 병합합니다.
예를 들어, 이미지 생성 확장은 다음과 같은 프롬프트 조각을 주입할 수 있습니다: "사용자가 이미지 생성을 요청하면 image_generate 도구를 사용하세요. 설명은 영어로 작성하며, 스타일 매개변수는 realistic, anime, sketch 등을 지원합니다."
이러한 설계를 통해 확장은 도구 기능을 제공할 뿐만 아니라, AI가 이러한 도구를 올바르게 사용하도록 안내할 수도 있습니다.
세션 컨텍스트 인식
buildAgentSystemPrompt()는 현재 세션의 상태도 참조합니다:
- 세션 길이: 긴 대화에서는 요약 컨텍스트가 추가될 수 있습니다
- 최근 주제: 대화 주제에 따라 프롬프트의 중점을 미세 조정합니다
- JSONL 영구화 상태: 세션 영구 저장소에서 컨텍스트를 복원하며, 압축(compaction) 처리된 기록 요약도 포함합니다
프롬프트 디버깅
개발자는 설정에서 debugSystemPrompt: true를 활성화하여, 최종 구성된 전체 시스템 프롬프트를 로그에 출력할 수 있습니다. 이는 예상치 못한 AI 동작을 디버깅할 때 매우 유용합니다. AI가 어떤 지시를 받았는지 정확히 확인할 수 있습니다.
또한 API 엔드포인트 /api/debug/system-prompt를 통해 현재 채널의 시스템 프롬프트 스냅샷을 얻을 수 있어, 로그를 확인하지 않고도 프롬프트 내용을 검사할 수 있습니다.
모범 사례
- 간결하게 유지: 각 계층의 커스텀 지시사항은 너무 길지 않아야 하며, 핵심 지시의 효과를 희석시키지 않도록 합니다
- 충돌 방지: 다른 계층의 지시사항이 모순될 수 있으며, 우선순위는: 안전 정책 > 전역 지시사항 > 채널 지시사항 > 사용자 지시사항 입니다
- 테스트 검증: 프롬프트를 수정한 후 디버그 모드를 사용하여 최종 구성 결과를 검증합니다
- 버전 관리: 커스텀 지시사항을 버전 관리에 포함하여 변경 이력을 추적합니다
정리
buildAgentSystemPrompt()는 OpenClaw이 지능적 채널 적응을 구현하는 핵심 메커니즘입니다. 15가지 이상의 매개변수의 동적 조합을 통해, 매 대화마다 맞춤형 시스템 지시를 받아 AI 에이전트가 서로 다른 플랫폼과 시나리오에서 최상의 상호작용 경험을 제공할 수 있습니다.