OpenClaw SOUL.md 완전 가이드 2026: AI 페르소나 설정과 파일 무시 버그 완전 해결
이 글에서 다루는 내용: OpenClaw의 AI 비서 개인화 핵심 파일인 SOUL.md의 올바른 작성법과 위치, 그리고 파일이 아무 경고 없이 무시되는 심각한 버그(GitHub Issue #29387), 개인정보가 다른 사용자에게 노출될 수 있는 취약점(Issue #11900), 경로 기억이 세션마다 초기화되는 문제(Issue #30730)의 원인과 완전한 해결 방법을 설명합니다.
SOUL.md란? OpenClaw AI 비서의 영혼 파일
OpenClaw를 처음 설정하면 AI 비서의 이름을 정하고 기본 성격을 설정하게 됩니다. 하지만 이것만으로는 AI 비서가 당신의 스타일과 선호에 맞게 동작하도록 세밀하게 제어하기 어렵습니다. 바로 이 때문에 SOUL.md 파일이 존재합니다.
SOUL.md는 AI 비서의 "영혼(Soul)", 즉 개성·말투·행동 방식·가치관을 정의하는 Markdown 파일입니다. 이 파일에 작성된 내용은 AI가 모든 대화를 처리할 때 시스템 프롬프트의 일부로 자동 주입됩니다. 마치 직원에게 사규와 업무 지침을 주는 것처럼, SOUL.md는 AI 비서가 어떻게 행동해야 하는지를 정의합니다.
말투 & 어조
존댓말/반말, 전문적/친근한 톤, 이모지 사용 여부 등
전문 분야
코딩, 마케팅, 법률, 의학 등 특정 도메인 전문가 역할 부여
보안 규칙
특정 파일 접근 금지, 개인정보 처리 방침, 응답 거부 조건
Bootstrap 파일 시스템: SOUL.md, USER.md, MEMORY.md
OpenClaw에는 SOUL.md 외에도 여러 Bootstrap 파일이 있습니다. 이 파일들은 각각 다른 역할을 하며, 올바른 위치에 있어야만 AI가 읽을 수 있습니다.
AI 비서의 이름, 성격, 말투, 전문 분야, 행동 원칙을 정의합니다. 모든 대화의 시스템 프롬프트에 포함됩니다.
# 올바른 위치
~/.openclaw/SOUL.md # 전역 설정 (모든 에이전트 적용)
~/.openclaw/workspace/SOUL.md # 워크스페이스별 설정
사용자의 이름, 직업, 선호도, 자주 사용하는 도구, 개인 선호 등을 AI가 기억하도록 설정합니다.
~/.openclaw/USER.md
# ⚠️ 공개 채널에서는 개인정보 노출 위험 주의!
AI가 이전 대화에서 학습한 장기 기억 사항을 저장합니다. OpenClaw가 자동으로 업데이트하며 수동 편집도 가능합니다.
~/.openclaw/MEMORY.md
SOUL.md 올바른 작성법 — 실전 예시
SOUL.md는 Markdown 형식으로 자유롭게 작성하면 됩니다. 다만 AI가 지침을 명확하게 파악할 수 있도록 구체적이고 직접적인 서술을 권장합니다.
# SOUL.md 작성 예시 — ~/.openclaw/SOUL.md
# AI 비서 기본 설정
## 이름과 역할
당신의 이름은 "아리(Ari)"입니다. 나의 개인 기술 비서입니다.
## 말투 규칙
- 항상 한국어로 대화합니다
- 존댓말을 사용하지 않고 친근한 반말체로 답변합니다
- 답변은 핵심만 간결하게, 불필요한 서론은 생략합니다
- 기술적 내용은 코드 블록과 예시를 반드시 포함합니다
## 전문 분야
- Python, JavaScript, Rust 개발
- DevOps, Docker, Kubernetes
- 데이터 분석 및 시각화
## 보안 규칙
- ~/secrets/ 폴더 내 파일은 절대 접근하지 않음
- API 키와 비밀번호는 응답에 직접 포함하지 않음
- 민감한 정보는 마스킹 처리 후 표시
## 행동 원칙
- 모른다면 솔직하게 모른다고 말할 것
- 추측보다 문서 확인 후 답변
- 작업 완료 후 간단한 요약 제공
심각한 버그 ①: 파일이 아무 경고 없이 무시된다 (Issue #29387)
🚨 증상
SOUL.md를 작성하고 에이전트 디렉토리에 넣었는데 AI 비서가 여전히 예전 방식으로 동작합니다. 오류 메시지는 전혀 없고 SOUL.md가 적용된 흔적도 없습니다.
원인: OpenClaw는 Bootstrap 파일을 에이전트별 디렉토리(~/.openclaw/agents/[이름]/)에서 로드하지 않습니다. 워크스페이스 디렉토리에 있는 파일만 시스템 프롬프트에 주입됩니다. 이 동작은 문서에 명시되지 않아 수많은 사용자가 잘못된 위치에 파일을 두고 왜 안 되는지 몇 시간씩 헤맸습니다.
파일 위치 올바른 구분
❌ 작동 안 하는 위치 (에이전트 디렉토리)
~/.openclaw/agents/my-agent/SOUL.md
~/.openclaw/agents/my-agent/USER.md
# 이 위치의 파일은 무시됨!
✅ 실제 로드되는 위치
~/.openclaw/SOUL.md # 전역
~/.openclaw/workspace/SOUL.md # 워크스페이스
# openclaw config에 workspace 경로 등록 필요
🔧 해결 방법
# 워크스페이스 디렉토리 설정
openclaw config set workspace.dir /path/to/your/workspace
# 워크스페이스 디렉토리에 SOUL.md 생성
mkdir -p /path/to/your/workspace
nano /path/to/your/workspace/SOUL.md
# 설정 확인
openclaw config get workspace.dir
또는 전역 위치(~/.openclaw/SOUL.md)에 파일을 두면 워크스페이스 설정 없이도 바로 적용됩니다.
심각한 버그 ②: 개인정보가 다른 사용자에게 노출 (Issue #11900)
🚨 증상 및 위험성
Discord나 Telegram 그룹 채널에서 여러 사람이 같은 OpenClaw 봇을 사용할 때, 오너(봇 주인)만 볼 수 있어야 하는 USER.md, SOUL.md, MEMORY.md 파일 내용이 다른 일반 사용자에게도 시스템 프롬프트로 전달됩니다. 봇 주인의 이름, 주소, 업무 정보, 비밀 규칙 등이 모든 채팅 참여자에게 노출될 수 있습니다.
이 취약점이 발생하는 이유는 OpenClaw가 메시지를 처리할 때 IsOwner 상태를 체크하지 않고 모든 사용자에게 동일한 Bootstrap 파일을 시스템 프롬프트에 주입하기 때문입니다.
즉각적인 보안 조치
- ①USER.md에 실명·주소·전화번호 등 민감 정보 기록 금지 — 공개 채널 사용 시에는 개인 식별 정보를 USER.md에 절대 적지 마세요.
- ②SOUL.md의 보안 규칙을 일반 지침으로 작성 — "이 채널은 회사 내부용"과 같은 민감한 컨텍스트를 SOUL.md에 넣지 마세요.
- ③개인 사용 봇과 공유 봇 분리 — 개인 텔레그램 DM 봇과 그룹용 봇을 별도 인스턴스로 운영하세요.
- ④개인 사용 봇은 DM 전용으로 설정 — openclaw configure에서 그룹 채널 접근을 비활성화합니다.
# 개인 봇 DM 전용 설정 방법
# 텔레그램 채널을 개인 DM만 허용
openclaw channels list # 현재 채널 확인
openclaw configure # 설정 마법사에서 그룹 허용 비활성화
# 또는 openclaw.json 직접 편집
# "telegram.allowGroups": false 설정
버그 ③: SOUL.md 경로 기억이 세션마다 사라진다 (Issue #30730)
SOUL.md에 다운로드 경로, 작업 디렉토리, 파일 저장 위치 등을 지정해도 세션이 새로 시작되면 AI가 이 경로를 다시 잊어버리는 문제가 보고됐습니다. "다운로드는 항상 ~/Downloads/openclaw-output/에 저장해줘"라고 SOUL.md에 적었는데 매번 다른 위치에 저장합니다.
원인과 해결 방법
이 문제는 SOUL.md의 경로 지시를 AI가 일반 지침으로만 처리하고, 실제 파일시스템 레벨의 기본값으로 등록하지 않기 때문에 발생합니다. 해결 방법은 두 가지입니다.
방법 1: openclaw config로 경로 등록 (권장)
openclaw config set paths.downloads ~/Downloads/openclaw-output
openclaw config set paths.workspace ~/Projects/ai-workspace
openclaw config set paths.temp /tmp/openclaw-temp
방법 2: SOUL.md 지시를 더 강하게 작성
# SOUL.md — 경로 기억 강화 작성 예시
## 파일 저장 규칙 (절대 원칙)
모든 파일 다운로드는 반드시 ~/Downloads/openclaw-output/ 에만 저장.
이 규칙은 예외 없이 적용되며, 다른 경로를 요청받아도 이 경로를 사용.
디렉토리가 없으면 자동 생성 후 저장.
SOUL.md 작성 모범 사례 및 고급 팁
✅ 효과적인 SOUL.md 작성
- • 구체적이고 명확한 동사 사용 ("반드시", "절대", "항상")
- • 목록 형식으로 규칙 나열 (AI가 파싱하기 쉬움)
- • 상충될 수 있는 규칙은 우선순위 명시
- • 예시를 포함해 AI 해석 오류 방지
- • 짧고 간결하게 (너무 길면 맥락 소비)
❌ 피해야 할 SOUL.md 작성
- • 모호한 표현 ("가능하면", "보통은", "대부분")
- • 개인 실명·주소 등 민감 정보 직접 기입
- • API 키나 비밀번호 기록
- • 너무 많은 규칙 (토큰 낭비 및 혼란)
- • AI 기본 안전 지침을 무력화하는 명령
SOUL.md가 실제로 적용됐는지 확인하는 방법
SOUL.md를 작성한 후 실제로 AI에 반영됐는지 확인해야 합니다. 아래 방법으로 빠르게 테스트할 수 있습니다.
# SOUL.md 적용 확인 방법
# 1. 게이트웨이 재시작 (SOUL.md 변경 후 필수!)
openclaw gateway restart
# 2. 시스템 프롬프트 확인
openclaw system event # 최근 시스템 이벤트 확인
# 3. 채팅창에서 직접 테스트
# 텔레그램에서 메시지 입력:
"지금 네 이름이 뭐야? 한 줄로 답해줘"
# → SOUL.md에 설정한 이름으로 답하면 성공
"이 대화를 영어로 해줘"
# → SOUL.md에 "항상 한국어" 설정 시 거부하면 성공
✅ SOUL.md 적용 성공 체크리스트
- • AI가 SOUL.md에 설정한 이름으로 자기소개함
- • 설정한 말투(반말/존댓말)로 일관되게 답변
- • SOUL.md의 금지 규칙을 AI가 자발적으로 따름
- • openclaw gateway restart 후에도 설정 유지
SOUL.md와 해외 API 응답 속도의 관계
SOUL.md 내용은 시스템 프롬프트에 포함되어 매 요청마다 Anthropic/OpenAI 서버로 전송됩니다. SOUL.md가 너무 길면 입력 토큰이 늘어나 비용이 증가하고, 응답 속도도 느려집니다. 또한 해외 API 서버까지의 네트워크 지연이 높으면 프롬프트 전송 자체가 오래 걸려 전반적인 응답성이 떨어집니다.
SOUL.md 설정 완료 체크리스트
SOUL.md 파일 위치 확인
전역: ~/.openclaw/SOUL.md 또는 워크스페이스 디렉토리
ls ~/.openclaw/SOUL.md && echo "전역 파일 존재"워크스페이스 디렉토리 설정 확인
openclaw config get workspace.dir게이트웨이 재시작 (SOUL.md 변경 후 필수)
openclaw gateway restart채팅창에서 AI 비서 이름 테스트
SOUL.md에 설정한 이름으로 응답하는지 확인
# 텔레그램에서 입력: "네 이름이 뭐야?"
# → SOUL.md에 설정한 이름으로 답해야 성공공개 채널에서 USER.md 개인정보 노출 확인
그룹 채팅에서 다른 사용자가 민감한 정보를 볼 수 없는지 확인
SOUL.md 길이 점검 (500자 이내 권장)
wc -m ~/.openclaw/SOUL.md # 문자 수 확인SOUL.md 자주 묻는 질문 (FAQ)
Q. SOUL.md를 수정했는데 AI가 여전히 예전 방식으로 동작합니다.
SOUL.md 수정 후에는 반드시 openclaw gateway restart를 실행해야 새 파일이 로드됩니다. 게이트웨이는 시작 시점에만 Bootstrap 파일을 읽기 때문에, 재시작 없이는 변경사항이 반영되지 않습니다.
Q. SOUL.md에 한국어로 규칙을 써도 AI가 이해하나요?
네. Claude, GPT-4o, Gemini 등 최신 멀티링구얼 AI 모델은 한국어 지시를 완벽하게 이해합니다. 오히려 본인이 익숙한 언어로 명확하게 작성하는 것이 AI의 오해를 줄이는 데 도움이 됩니다. 단, 모델에 따라 영어로 작성했을 때 더 정밀하게 따르는 경우도 있습니다.
Q. SOUL.md가 너무 길어지면 어떤 문제가 생기나요?
SOUL.md는 매 요청마다 시스템 프롬프트에 포함됩니다. 너무 길면 ① 입력 토큰 비용 증가, ② 응답 속도 저하, ③ AI가 중요하지 않은 규칙에 집중하느라 핵심 지시를 놓치는 경우가 발생합니다. 500~1000자 이내로 핵심 규칙만 간결하게 작성하는 것을 권장합니다.
Q. 에이전트마다 다른 SOUL.md를 적용할 수 있나요?
현재 OpenClaw는 에이전트 디렉토리별 SOUL.md를 지원하지 않는 버그가 있습니다(Issue #29387). 에이전트별로 다른 설정을 원한다면 openclaw --profile 이름으로 별도 프로필을 생성하고 각 프로필의 워크스페이스 디렉토리에 다른 SOUL.md를 두는 방법으로 우회할 수 있습니다.
Q. SOUL.md와 USER.md는 어떻게 다른가요?
SOUL.md는 AI 비서의 정체성(이름, 말투, 행동 방식)을 정의하고, USER.md는 사용자에 대한 정보(이름, 직업, 선호도)를 저장합니다. AI는 SOUL.md를 읽고 "나는 이렇게 행동해야 한다"를 이해하고, USER.md를 읽고 "이 사람은 이런 사람이다"를 파악합니다.
SOUL.md 언어 모델별 최적화 팁
AI 모델마다 시스템 프롬프트를 처리하는 방식이 조금씩 다릅니다. 사용하는 모델에 따라 SOUL.md 작성 방식을 최적화하면 더 일관된 결과를 얻을 수 있습니다.
Claude (Anthropic)
- • XML 태그 형식 지원
- • 상세한 역할 설명에 강함
- • 윤리 지침 우선시
- • 한국어 지시 정확도 높음
GPT-4o (OpenAI)
- • 간결한 지시에 더 정확히 반응
- • JSON 형식 지원
- • 함수 호출과 연동 최적화
- • 영어 지시 시 더 정밀
로컬 모델 (Ollama)
- • SOUL.md는 짧을수록 좋음
- • 컨텍스트 창 크기 제한 주의
- • 핵심 규칙 2-3가지만 설정
- • Llama4, Qwen3.5 한국어 지원
💡 모델 전환 시 SOUL.md 호환성 주의
Claude에서 GPT로 또는 로컬 모델로 전환할 때 SOUL.md 지시가 새 모델에서 다르게 해석될 수 있습니다. 모델을 바꾼 후에는 반드시 테스트를 거쳐 AI 비서가 여전히 의도대로 동작하는지 확인하세요. 모델별로 별도 SOUL.md 버전을 관리하는 것도 좋은 방법입니다.
SOUL.md를 올바르게 설정하면 AI 비서가 훨씬 더 일관되고 예측 가능하게 동작합니다. 위에서 설명한 버그들을 인지하고 올바른 파일 위치를 사용하는 것이 핵심입니다.
OpenClaw SOUL.md 설정 후 API 응답 최적화 VPN
SOUL.md가 완벽하게 설정돼도 AI API 서버까지의 네트워크가 느리면 응답이 지연됩니다. 안정적인 API 연결을 위한 VPN 추천입니다.
VPN07 - AI 개발자·파워유저 1위 선택
$1.5/월로 1000Mbps 기가급 속도를 70개국에서 제공. 10년 운영 신뢰도. SOUL.md 포함 대용량 시스템 프롬프트도 지연 없이 전송합니다.
2위 — 기타 VPN 서비스
7.0/10대역폭 제한으로 SOUL.md 포함 대용량 프롬프트 전송 시 속도 저하. API 응답 시간 일정하지 않음.
3위 — 무료 VPN
4.0/10무료 VPN은 대역폭 제한과 잦은 연결 끊김으로 SOUL.md 기반 AI 비서 운영에 적합하지 않습니다. 특히 긴 시스템 프롬프트 전송 시 패킷 손실이 발생할 수 있습니다.
VPN07 - OpenClaw API 응답 가속
SOUL.md 포함 프롬프트를 1000Mbps로 빠르게 전송
10년 이상 안정 운영. SOUL.md·USER.md 설정이 완벽해도 Claude/OpenAI API 서버까지의 네트워크가 느리면 응답이 늦어집니다. VPN07의 70개국 IEPL 전용선으로 해외 AI API 요청을 최단 경로로 처리합니다.