대화를 나누다 보면 어딘가 2% 부족한 느낌이 들 때가 있습니다. 대답이 너무 길거나, 원하지 않는 말투를 쓰거나, Python 코드를 요청했을 때 내 스타일과 전혀 맞지 않는 코드를 내놓는 경우가 바로 그것입니다. 범용 AI는 모든 사람에게 맞게 설계되어 있기 때문에, 역설적으로 누구의 스타일과도 완벽히 맞지 않습니다.
이번 15편에서는 평범한 AI에게 '깐깐한 시니어 개발자' 혹은 '친절한 업무 비서'와 같은 구체적인 페르소나와 행동 규칙을 부여하는 openclaw agents.md 파일 작성법을 처음부터 끝까지 다룹니다. 코딩을 몰라도 자연어로 작성하면 되며, 이 글을 따라 하시면 나만의 맞춤형 AI 에이전트 만들기를 완성할 수 있습니다.
지난 편(이전: Agent 개념 심화 — Heartbeat·Memory·Context 동작 원리)에서는 에이전트가 대화를 기억하고 스스로 깨어나는 메커니즘을 완성했습니다. 이번 편에서는 그 에이전트에 '성격'을 입히는 작업을 합니다.
AGENTS.md와 SOUL.md란 무엇인가 — openclaw.json과의 차이
OpenClaw의 두뇌를 제어하는 파일은 크게 두 종류로 나뉩니다. 포트, API 키, 채널, 메모리 설정 등 인프라와 기계적인 동작을 담당하는 것이 openclaw.json이라면, AI의 '성격(Persona)'과 '행동 규칙(Rules)'을 글로 정의하는 프롬프트 지시서가 바로 AGENTS.md와 SOUL.md입니다.
openclaw.json vs AGENTS.md 한눈에 비교
openclaw.json: "어떤 포트를 쓸지, 텔레그램을 연결할지, Claude 모델을 쓸지" 결정하는 하드웨어 제어판입니다. 잘못 수정하면 시스템 전체가 멈출 수 있습니다.AGENTS.md: "어떤 말투를 쓸지, 무엇을 하면 안 되는지, 코드를 어떻게 작성할지" 결정하는 소프트웨어 마인드 세팅입니다. 일반 텍스트 파일이라 수정이 자유롭고 실시간 반영됩니다.SOUL.md:AGENTS.md의 보완재로, AI의 근본적인 가치관·깊은 성격·배경 스토리를 담습니다.AGENTS.md가 '직업과 업무 규칙'이라면SOUL.md는 '인간성과 세계관'에 해당합니다.
~/.openclaw/workspace/)에 일반 마크다운 형식으로 저장됩니다. 복잡한 코딩 문법 없이 자연어로 작성해도 에이전트는 찰떡같이 이해합니다. Git 등 버전 관리 시스템에 올려 이력을 관리하는 것도 좋은 방법입니다. 📎 OpenClaw 공식 문서(Agents → AGENTS.md) 원문 보기 →
openclaw.json은 인프라 제어판, AGENTS.md는 AI의 성격과 행동 규칙을 담는 프롬프트 지시서입니다. 둘은 완전히 다른 역할을 하며 함께 사용해야 최고의 에이전트가 완성됩니다.효과적인 AGENTS.md 작성 구조 — 4가지 핵심 섹션
AI가 규칙을 헷갈리지 않고 정확히 따르도록 만들려면 체계적인 구조로 지시사항을 작성하는 것이 중요합니다. 다음 4가지 섹션을 뼈대로 삼으면 어떤 역할이든 효과적으로 정의할 수 있습니다.
- Role (역할): AI가 스스로를 누구라고 생각해야 하는지 정체성을 부여합니다. 예: "당신은 Python 자동화에 정통한 10년 차 시니어 개발자입니다."
- Tone & Style (어조와 스타일): 존댓말/반말 여부, 간결함, 이모지 사용 여부, 답변 길이 제한 등을 지정합니다. 예: "모든 답변은 핵심만 3줄 이내로 먼저 요약하세요."
- Constraints (금지·제한 사항): 절대 해서는 안 되는 행동을 명시합니다. 예: "확실하지 않은 사실은 지어내지 말고 반드시
web_search도구로 확인 후 답변하세요." - Workflow (작업 순서): 특정 요청이 들어왔을 때 기본적으로 밟아야 할 논리적 단계를 정의합니다. 예: "코드 작성 요청 시 ① 요구사항 확인 → ② 코드 작성 → ③ 테스트 방법 안내 순으로 처리하세요."
실전 적용 — 터미널에서 AGENTS.md 직접 만들기
지금까지 배운 구조를 바탕으로, 아래 순서대로 따라 하시면 5분 내에 나만의 맞춤형 AI 에이전트 설정 파일이 완성됩니다.
- 워크스페이스 폴더 생성OpenClaw의 프롬프트 파일들이 저장될 워크스페이스 폴더를 만듭니다. 이미 존재한다면 이 단계는 건너뛰어도 됩니다.
mkdir -p ~/.openclaw/workspace- AGENTS.md 파일 작성아래 명령어를 터미널에 복사·붙여넣기하면 Python 개발자 겸 업무 비서 역할의
AGENTS.md가 즉시 생성됩니다. 내용은 이후 나의 스타일에 맞게 자유롭게 수정하세요. cat << 'EOF' > ~/.openclaw/workspace/AGENTS.md # Role 당신은 Python 자동화에 정통한 10년 차 시니어 개발자이자 나의 든든한 업무 비서입니다. # Tone & Style - 모든 답변은 전문적이고 간결하게, 핵심만 3줄 이내로 먼저 요약하세요. - 코드 예시를 제공할 때는 반드시 주석을 포함하여 복사 후 즉시 실행 가능한 형태로 제공하세요. # Constraints - 확실하지 않은 시스템 오류에 대해서는 추측해서 답하지 말고, 반드시 exec나 web_search 도구를 사용하여 팩트를 확인한 뒤 답변하세요. - 불필요한 인사말이나 서론은 생략하세요. # Workflow - 코드 작성 요청 시: ① 요구사항 확인 → ② 코드 작성(주석 포함) → ③ 테스트 방법 안내 순으로 처리하세요. EOF- 작성된 파일 내용 확인파일이 올바르게 생성되었는지 확인합니다.
cat ~/.openclaw/workspace/AGENTS.md- 에이전트에서 즉시 효과 확인파일을 저장하고 메신저에서 새롭게 말을 걸어보세요. 게이트웨이 재시작 없이 Hot Reload 기능으로 바뀐 성격이 즉시 새 대화 세션에 적용됩니다.
AGENTS.md를 Git 저장소에 커밋해두면 규칙 변경 이력을 관리하고 언제든 이전 버전으로 롤백할 수 있습니다. 서버를 이전하거나 재설치할 때도 파일 하나만 복원하면 AI의 성격이 즉시 복구됩니다.Hot Reload와 SOUL.md — 고급 활용법
AGENTS.md를 수정할 때마다 openclaw gateway restart를 실행할 필요가 없습니다. 포트 변경이나 채널 토큰 변경과 달리, 에이전트의 프롬프트 규칙 변경은 대부분 Hot Reload(실시간 반영)로 처리됩니다. 파일을 저장한 뒤 메신저에서 새로운 대화를 시작하면 바뀐 성격이 즉시 적용됩니다.
SOUL.md로 AI에게 인간성 부여하기
AGENTS.md가 직업과 업무 규칙을 담는다면, SOUL.md는 AI의 더 근본적인 가치관과 세계관을 담는 파일입니다. 같은 워크스페이스 폴더에 함께 저장하면 두 파일이 동시에 적용됩니다.
AGENTS.md예시 내용: "Python 시니어 개발자, 3줄 요약, 추측 금지, 코드 주석 필수"SOUL.md예시 내용: "당신은 호기심이 많고 학습을 즐깁니다. 모르는 것을 만나면 솔직하게 인정하고 함께 탐구하려는 자세를 갖습니다."
AGENTS.md에 개인정보(실명, 주소, 금융 정보 등)를 직접 기재하지 마세요. 이 파일을 실수로 공개 Git 저장소에 올리면 개인정보가 노출될 수 있습니다. 민감한 정보는 반드시 openclaw.json의 환경 변수 참조 방식을 사용하세요.AGENTS.md(업무 규칙) + SOUL.md(가치관)를 워크스페이스 폴더에 작성하면 Hot Reload로 즉시 반영됩니다. 두 파일을 함께 활용해 나만의 입체적인 AI 비서를 완성하세요.
실전 팁과 주의사항
- Constraints(금지 사항)을 구체적으로 명시: "추측하지 말아라"보다 "확실하지 않은 오류는 반드시
web_search도구로 확인 후 답변하라"처럼 어떤 도구를 어떤 상황에 쓸지 명시할수록 AI가 더 정확하게 따릅니다. - 역할(Role)은 구체적인 직함과 경력으로 설정: "AI 비서"보다 "Python 자동화에 정통한 10년 차 시니어 개발자"처럼 구체적인 직함을 부여하면 AI가 해당 분야의 지식과 말투를 훨씬 일관되게 유지합니다.
- AGENTS.md에 개인정보 기재 금지: 이 파일은 실수로 Git 공개 저장소에 올라갈 수 있습니다. 실명, 주소, API 키 등 민감한 정보는 절대 포함하지 마세요.
- 변경 후 반드시 새 대화 세션으로 테스트: Hot Reload는 기존 진행 중인 대화 세션에는 즉시 반영되지 않을 수 있습니다. 변경 효과를 확인하려면 반드시 새 대화를 시작하세요.
자주 묻는 질문 (FAQ)
- 코딩이나 마크다운을 전혀 몰라도 AGENTS.md를 작성할 수 있나요?
- 물론입니다! 마크다운 문법(
#기호로 제목 달기)을 쓰면 AI가 구조를 조금 더 잘 이해하지만, 단순히 메모장 쓰듯이 평문 텍스트로 쭉 적어 내려가도 에이전트는 찰떡같이 알아듣습니다. 원하는 규칙을 자연스러운 한국어로 편하게 작성하시면 됩니다. - AGENTS.md 파일과 openclaw.json 설정 파일은 어떻게 다른 건가요?
openclaw.json은 에이전트에게 '어떤 포트를 쓸지, 텔레그램을 연결할지, Claude 모델을 쓸지' 결정하는 인프라 제어판입니다. 반면AGENTS.md는 에이전트의 '성격, 가치관, 대화 스타일'을 결정하는 소프트웨어적인 마인드 세팅 문서입니다. 둘은 역할이 완전히 다르며 함께 사용해야 합니다.- AGENTS.md 내용을 바꾸면 매번 openclaw gateway restart를 실행해야 하나요?
- 아닙니다. 에이전트의 프롬프트 규칙 변경은 대부분 재시작 없이 Hot Reload로 실시간 반영됩니다. 파일을 저장하고 메신저에서 새롭게 대화를 시작하시면 바뀐 성격이 즉시 적용된 것을 체감하실 수 있습니다.
- SOUL.md 파일은 또 무엇인가요? AGENTS.md랑 같이 써도 되나요?
- 네, 같이 사용 가능합니다.
AGENTS.md에는 '업무 처리 방식과 규칙' 등 실무적인 내용을 담고,SOUL.md에는 AI의 근본적인 '가치관, 깊은 성격, 배경 스토리'를 담아 역할을 분리합니다. 둘 다 작성하면 훨씬 입체적이고 일관된 AI 비서를 만들 수 있습니다.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw agents.md 작성에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
댓글