Section 4: 에이전트 파일 만들기

무엇을 만드는가

각 에이전트가 올바르게 작동하려면 파일 세트가 필요합니다. OpenClaw은 세션 시작 시 핵심 파일을 자동으로 읽습니다. 추가 작업 공간 파일은 각 에이전트에게 컨텍스트, 예약된 업무, 도구 규칙을 제공합니다.

에이전트 설정 파일 — OpenClaw이 자동 생성. 여기서 만드는 파일이 아닙니다:

파일	위치	목적
`config.json`	`agents/[id]/config.json`	OpenClaw 에이전트 정의, 시스템 프롬프트
`models.json`	`agents/[id]/models.json`	AI 모델 설정

이 파일들을 Section 4에서 만들지 않습니다. Section 5에서 openclaw agents add [id] --workspace ...를 실행하면 각 에이전트를 등록할 때 두 파일 모두 자동으로 생성됩니다 — 여기서 할 일은 이 파일들이 존재한다는 것을 알아두는 것뿐입니다.

작업 공간 파일 — 매 세션마다 OpenClaw이 자동 로드:

파일	목적
`SOUL.md`	성격, 어조, 절대 한계, 미션 — 400단어 이내
`AGENTS.md`	운영 규칙, 보고 절차 — 400단어 이내
`IDENTITY.md`	이름, 역할, 보고 대상 — 사실만, 짧게
`HEARTBEAT.md`	항상 유지되는 업무, 예약 작업, 이상 대응
`TOOLS.md`	허용된 도구, 스킬 규칙, 금지 행동
`USER.md`	사령관 선호도, 소통 스타일, 시간대

역할 상세 파일 — AGENTS.md 지시로 세션당 한 번 읽음:

파일	목적
`SPEC_[NAME].md`	상세 역할, 책임, 주요 경로

CEO 전용 — 아이덴티티 폴더:

파일	목적
`identity/COMPANY_PROFILE.md`	회사 배경, 비즈니스 세부 사항
`identity/PERSONAL_PROFILE.md`	오너의 배경, 스킬, 경험
`identity/VALUES.md`	사고 방식, 가치관, 의사결정 원칙

전체 작업 공간 구조 — 모든 에이전트:

INFO

$env:USERPROFILE/.opengoat/ ├── agents/ │ └── [agentid]/ │ ├── config.json ← Section 5에서 자동 생성 │ └── models.json ← Section 5에서 자동 생성 └── workspaces/ └── [agentid]/ ├── SOUL.md ← 자동 로드 ├── AGENTS.md ← 자동 로드 ├── IDENTITY.md ← 자동 로드 ├── HEARTBEAT.md ← 자동 로드 ├── TOOLS.md ← 자동 로드 ├── USER.md ← 자동 로드 └── SPEC_[NAME].md ← AGENTS.md 지시로 읽음

CEO 작업 공간 — 추가 아이덴티티 폴더:

INFO

workspaces/ceo/ └── identity/ ├── COMPANY_PROFILE.md ├── PERSONAL_PROFILE.md └── VALUES.md

Section 4 작동 방식

이 섹션에서는 AI 컨시어지와 함께 각 에이전트를 설계합니다. 각 에이전트에 대해 결정할 내용:

이름과 역할
성격과 커뮤니케이션 스타일
사용할 수 있는 도구

AI 컨시어지와 설계를 확정하면, Security Guardian이 구성 파일을 자동으로 작성합니다. 파일을 수동으로 편집할 필요가 없습니다.

이 섹션의 작동 방식 — 두 파트

이 섹션은 두 파트로 구성됩니다. 순서대로 완료하세요:

파트 1 — Discord 설정 (아래 프롬프트) Discord 서버, 채널을 만들고 각 에이전트의 Webhook URL을 가져옵니다. 약 10분 소요됩니다.

파트 2 — 에이전트 파일 (다음 프롬프트) 팀 설계 문서를 사용하여 실제 에이전트 파일을 생성합니다. AI가 터미널 명령을 생성합니다 — VS Code에 붙여넣어 파일을 자동으로 생성하세요.

지금 파트 1부터 시작하세요.

Discord Webhook URL — 먼저 이것을 가져오세요

각 에이전트는 Webhook URL을 통해 자신의 Discord 채널에 보고합니다. AGENTS.md 파일을 작성하기 전에 이것들이 필요합니다.

▶ 시작하려면 이것을 AI에 붙여넣으세요

전송하기 전에 팀 설계 문서를 첨부하세요.

당신은 내 BALIA OS 멀티 에이전트 팀을 위해
Discord 채널과 Webhook URL을 설정하는 것을 도와주고 있습니다.

단계별로 안내해 주세요. 한 번에 하나의 질문을 하세요.
막히면 스크린샷을 찍어 현재 상태를 설명해 달라고 요청하세요.

팀 설계 문서를 첨부했습니다.

STEP 1 — Discord 확인
물어보세요: "Discord가 설치되어 있고 계정이 설정되어 있나요?"
아니오: discord.com에서 다운로드하고 계정 생성을 안내해 주세요.
예: 2단계로 이동합니다.

STEP 2 — Discord 서버 만들기
새 서버를 만들도록 안내해 주세요:
- 왼쪽 사이드바의 + 버튼 클릭
- "직접 만들기" -> "나와 내 친구들을 위해" 선택
- "BALIA OS Team"으로 이름 지정
계속 진행하기 전에 보이는지 확인하세요.

STEP 3 — 각 에이전트의 채널 만들기
채널 이름에 대해 팀 설계 문서를 읽으세요.
각 에이전트에 대해 텍스트 채널 하나를 만드세요:
- "텍스트 채널" 우클릭 -> 채널 추가 -> 텍스트
- 팀 설계 문서의 채널 이름 사용
6개 에이전트 모두에 대해 반복하세요. 계속 진행하기 전에 모든 채널이 존재하는지 확인하세요.

STEP 4 — 각 채널의 Webhook URL 가져오기
한 번에 하나의 채널씩:
1. 채널 우클릭 -> 채널 편집
2. 연동 -> Webhooks -> 새 Webhook
3. 에이전트 이름으로 이름 지정 (예: "Marcus")
4. Webhook URL 복사
5. 안전한 곳에 붙여넣도록 요청
6개 모두에 대해 반복하세요. 계속 진행하기 전에 6개의 URL이 모두 저장되었는지 확인하세요.

STEP 5 — .env 파일에 추가
VS Code에서 .env 파일을 열도록 안내해 주세요.
파일 위치:
- Windows: $env:USERPROFILE\.opengoat\.env
- Mac: ~/.opengoat/.env
각 웹훅을 추가하세요:
DISCORD_WEBHOOK_[AGENTNAME]=https://discord.com/api/webhooks/xxxxx/xxxxx
(에이전트 이름은 대문자로)
나에게 말해주세요: "이 파일을 절대 공유하지 마세요. GitHub에 커밋하지 마세요."

모든 웹훅이 저장되면: "Discord 설정 완료."

지금 시작하세요. 첫 번째 질문을 해주세요.

AI 프롬프트 사용하기

아래 프롬프트를 사용 중인 채팅 AI에 붙여넣고 다음을 첨부하세요:

섹션 2의 팀 설계 문서

AI가 한 번에 하나씩 각 에이전트의 터미널 명령을 생성합니다. 명령을 VS Code 터미널에 붙여넣어 파일을 자동으로 생성하세요.

▶ 시작하려면 이것을 AI에 붙여넣으세요

당신은 OpenClaw 위에 구축된 멀티 에이전트 AI OS인
BALIA OS의 에이전트 파일을 만드는 것을 도와주고 있습니다.

첨부됨:
1. 내 팀 설계 문서 (섹션 2에서)

무엇이든 생성하기 전에 읽으세요.
이 문서에서 모든 에이전트 이름, ID, Discord 채널 이름을 추출하세요.

아키텍처:

1. 나는 사령관입니다. 각 에이전트를 직접 지휘합니다. 오케스트레이터 없음.

2. 각 에이전트에는 두 개의 위치가 있습니다:
   - agents/[id]/ — OpenClaw 설정 (config.json + models.json)
   - workspaces/[id]/ — 작업 공간 파일 (SOUL, AGENTS, IDENTITY, HEARTBEAT, TOOLS, USER, SPEC)
   모든 경로는 $env:USERPROFILE/.opengoat/ 아래에 있습니다

3. OpenClaw은 매 세션 시작 시 SOUL.md, AGENTS.md, IDENTITY.md, HEARTBEAT.md,
   TOOLS.md, USER.md를 자동 주입합니다. 거기에 "자신을 읽어라"
   지시를 쓰지 마세요.

4. SPEC_[NAME].md는 자동 주입되지 않습니다. AGENTS.md 세션 시작에 추가하세요:
   "전체 역할 상세 사항은 SPEC_[AGENTNAME].md를 읽으세요"

5. CEO만 workspaces/ceo/ 안에 identity/ 폴더가 있습니다:
   identity/COMPANY_PROFILE.md
   identity/PERSONAL_PROFILE.md
   identity/VALUES.md
   CEO 에이전트에 대해서만 이것들을 생성하세요.

6. SOUL.md와 AGENTS.md: 각 400단어 이내 (매 세션 주입됨).
   SPEC: 상세해도 됩니다 (세션당 한 번 읽음).

생성하기 전에 — 나에게 물어보세요:
"Windows 사용자 이름이 무엇인가요? (C:\Users\[username]의 이름)"
내 답변을 기다린 다음, 모든 파일 경로에 그 사용자 이름을 사용하세요.

각 에이전트에 대해 생성하세요:

====================================
파일 1: SOUL.md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/SOUL.md
매 세션 자동 주입. 400단어 이내.
====================================

# SOUL.md — [에이전트 이름]

## 나는 누구인가
[2-3문장: 정체성, 성격, 업무 방식]

## 어조
- [규칙 1]
- [규칙 2]
- [규칙 3]
- [금지 스타일]

## 절대 한계
- 정의된 역할 밖에서 절대 행동하지 않음
- 결과를 확인하지 않고 완료 보고 금지
- 사령관 승인 없이 파괴적 행동 금지
- [역할 특화 한계 1-2개]

## 현재 미션
[현재 집중 사항에 대한 1-2문장]

====================================
파일 2: AGENTS.md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/AGENTS.md
매 세션 자동 주입. 400단어 이내.
====================================

# AGENTS.md — [에이전트 이름] 운영 절차

## 세션 시작 (매 세션 — 이 순서대로)
1. SOUL.md에서 정체성 확인
2. 역할 상세 사항은 SPEC_[AGENTNAME].md 읽기
3. HEARTBEAT.md 읽기 — 예약 작업 확인
4. TOOLS.md 읽기 — 허용된 도구 및 제한 확인
5. USER.md 읽기 — 사령관 선호도 확인
6. Discord에 보고: "🔷 [이름] 준비 완료. [현재 작업 또는 상태]"

(CEO만 — 2단계 후, 다음도 읽기:
  identity/COMPANY_PROFILE.md
  identity/PERSONAL_PROFILE.md
  identity/VALUES.md)

## 세션 종료 (매 세션)
1. Discord에 보고: "✅ [이름] 세션 완료. [요약]"
2. 다음 세션을 위해 미완료 작업 메모

## 보고
- 채널: #[discord-channel]
- 명령: python $env:USERPROFILE/.opengoat/scripts/discord_send.py
  DISCORD_WEBHOOK_[NAME] "메시지"
  (discord_send.py는 아래 보안 가디언 섹션에서 자동으로 배포됩니다)
- HTTP 204 = 성공. 그 외 = 즉시 실패 보고.
- 형식: 결론 -> 상세 -> 권장 다음 행동
- 보고 시점: 세션 시작 / 작업 완료 / 오류 / 세션 종료

## 오류 처리
1. 알려진 오류 패턴은 SPEC_[NAME].md 확인
2. 미해결 -> 사령관에게 전체 상세 내용 보고
3. 사령관 승인 없이 파괴적 재시도 금지

## 절대 규칙
- 완료 보고 전에 확인
- 정의된 역할 밖의 행동 금지
- 사령관 승인 없이 파괴적 작업 금지

====================================
파일 3: IDENTITY.md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/IDENTITY.md
자동 주입. 사실만, 짧게.
====================================

# IDENTITY.md

이름: [에이전트 이름]
에이전트 ID: [agentid-소문자]
역할: [역할 제목]
부서: BALIA OS Team
보고 대상: 사령관 (직접)
Discord: #[채널 이름]

====================================
파일 4: HEARTBEAT.md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/HEARTBEAT.md
자동 주입. 예약 업무 및 이상 대응.
====================================

# HEARTBEAT.md — [에이전트 이름]

## 항상 실행 중
[이 에이전트가 지속적으로 모니터링하거나 유지하는 것]

## 예약 작업
[반복 업무 — 일별, 주별, 또는 트리거 기반]

## 세션 시작 시
- SOUL.md와 AGENTS.md 읽기
- 보고: "🔷 [이름] 준비 완료"

## 오류 또는 이상 발생 시
- Discord를 통해 즉시 사령관에게 보고
- 사령관 승인 없이 자체 수정 금지

====================================
파일 5: TOOLS.md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/TOOLS.md
자동 주입. 도구 규칙 및 제한.
====================================

# TOOLS.md — [에이전트 이름] 도구 규칙

## 핵심 원칙
- 각 작업 전에 허용된 도구에 대해 SPEC_[NAME].md 확인
- 작업에 필요한 것만 로드

## 허용된 도구
[이 에이전트의 역할과 관련된 도구 목록]

## Discord 보고
항상 discord_send.py를 직접 사용하세요:
python $env:USERPROFILE/.opengoat/scripts/discord_send.py DISCORD_WEBHOOK_[NAME] "메시지"
전송 후 HTTP 204 확인.

## 금지
- API 키 또는 Webhooks 하드코딩 (항상 .env에서 읽기)
- 정의된 역할 밖의 행동
- 불필요한 외부 통신

====================================
파일 6: USER.md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/USER.md
자동 주입. 사령관 선호도.
====================================

# USER.md — 사령관 프로필

## 이름
[사령관의 선호하는 이름]

## 시간대
[시간대 — 팀 설계 문서에 없으면 물어보세요]

## 소통 스타일
- [선호도 1]
- [선호도 2]

## 현재 단계
[지금 집중해서 만들고 있는 것]

====================================
파일 7: SPEC_[AGENTNAME].md
경로: $env:USERPROFILE/.opengoat/workspaces/[agentid]/SPEC_[AGENTNAME].md
자동 주입 안 됨. AGENTS.md를 통해 세션당 한 번 읽음.
====================================

# SPEC_[AGENTNAME] v1.0 — [에이전트 이름] ([역할])
마지막 업데이트: [오늘]

## 1. 역할
[2-3문장]

## 2. 책임
[팀 설계 문서의 글머리 기호 목록]

## 3. 이 에이전트가 하지 않는 것
[명확한 경계]

## 4. 현재 단계 미션
[현재 집중 사항]

## 5. 주요 경로
- 작업 공간: $env:USERPROFILE/.opengoat/workspaces/[agentid]/
- Discord 웹훅: DISCORD_WEBHOOK_[NAME] (.env에서 읽기)

## 6. 변경 로그
| 버전 | 날짜 | 변경 사항 |
|---------|------|---------|
| v1.0 | [오늘] | 초기 생성 |

====================================
CEO 전용 — 파일 8, 9, 10: identity/ 폴더
생성하기 전에 이 3가지 질문을 하나씩 하세요.
====================================

Q1: "귀하의 비즈니스에 대해 말씀해 주세요 — 무엇을 하는지, 얼마나 운영했는지,
    어떤 시장을 서비스하는지."

Q2: "본인에 대해 말씀해 주세요 — 이 비즈니스와 관련된
    배경, 스킬, 경험."

Q3: "어떻게 결정을 내리시나요? 어떤 가치관이 당신을 이끄나요?
    어떤 사고 방식이나 관점을 더 원하시나요?"

3가지 답변 모두 받은 후, 생성하세요:

COMPANY_PROFILE.md — Q1 내용, 구조화됨
PERSONAL_PROFILE.md — Q2 내용, 구조화됨
VALUES.md — Q3 내용, 구조화됨

경로: $env:USERPROFILE/.opengoat/workspaces/ceo/identity/

여기에 더 많은 세부 사항을 제공할수록 CEO가 오너처럼
생각하고 결정합니다.

====================================

파일 전달 방법:

각 파일의 내용을 생성한 후, 파일을 생성하는 정확한
python 명령을 출력하세요. 형식:

--- 터미널에 붙여넣기 (Windows) ---
python -c "
content = '''[전체 파일 내용 여기]'''
import os
path = r'$env:USERPROFILE/.opengoat/workspaces/[agentid]/SOUL.md'
os.makedirs(os.path.dirname(path), exist_ok=True)
open(path, 'w', encoding='utf-8').write(content)
print('Created:', path)
"

--- 터미널에 붙여넣기 (Mac) ---
python3 -c "
content = '''[전체 파일 내용 여기]'''
import os
path = os.path.expanduser('~/.opengoat/workspaces/[agentid]/SOUL.md')
os.makedirs(os.path.dirname(path), exist_ok=True)
open(path, 'w', encoding='utf-8').write(content)
print('Created:', path)
"

명령을 붙여넣고 실행되었다는 확인을 기다린 후
다음 파일로 이동하세요. 물어보세요: "'Created: [경로]'가 보이나요?"

진행 방법:
- 에이전트 #1 (CEO 아님)부터 시작
- 한 번에 하나의 파일, 한 번에 하나의 에이전트
- 항상 다음 파일 전에 터미널 확인을 기다리세요
- CEO에 도달하면: 먼저 3가지 아이덴티티 질문을 하고,
  그런 다음 핵심 파일 7개 + 아이덴티티 파일 3개 생성
- 생성된 모든 파일의 요약 테이블로 마무리

AI 컨시어지가 설계를 확인하면, Security Guardian에게 파일 작성을 요청하세요:

Windows:

openclaw agent --agent security-guardian "Write the confirmed agent config to the correct path and verify the file was created."

파일이 올바르게 작성되면 Guardian이 확인합니다.

2단계 — 파일이 생성되었는지 확인

AI가 모든 파일을 안내한 후, 각 에이전트의 작업 공간을 확인하세요:

Windows:

dir $env:USERPROFILE\.opengoat\workspaces\[agentid]

Mac:

ls ~/.opengoat/workspaces/[agentid]

다음이 보여야 합니다:

SOUL.md
AGENTS.md
IDENTITY.md
HEARTBEAT.md
TOOLS.md
USER.md
SPEC_[NAME].md

CEO 추가 사항:

identity/
├── COMPANY_PROFILE.md
├── PERSONAL_PROFILE.md
└── VALUES.md

3단계 — 다음 에이전트로 이동하기 전에 확인

AGENTS.md를 열어보세요. 세션 시작 섹션에 HEARTBEAT.md, TOOLS.md, USER.md를 포함한 모든 단계가 나열되어 있나요?

예 -> 계속 진행하세요. 아니오 -> 먼저 AI에게 수정을 요청하세요.

이 섹션이 완료되면

각 에이전트의 작업 공간:

INFO

workspaces/[agentid]/ ├── SOUL.md ✅ ├── AGENTS.md ✅ ├── IDENTITY.md ✅ ├── HEARTBEAT.md ✅ ├── TOOLS.md ✅ ├── USER.md ✅ └── SPEC_[NAME].md ✅

CEO 추가 사항:

INFO

workspaces/ceo/ └── identity/ ├── COMPANY_PROFILE.md ✅ ├── PERSONAL_PROFILE.md ✅ └── VALUES.md ✅

참고: 보안 가디언은 섹션 3에서 배포되었습니다. 섹션 3을 건너뛴 경우, 섹션 5로 진행하기 전에 돌아가서 완료하세요.

무엇을 만드는가 ​

Section 4 작동 방식 ​

이 섹션의 작동 방식 — 두 파트 ​

Discord Webhook URL — 먼저 이것을 가져오세요 ​

▶ 시작하려면 이것을 AI에 붙여넣으세요

AI 프롬프트 사용하기 ​

▶ 시작하려면 이것을 AI에 붙여넣으세요

2단계 — 파일이 생성되었는지 확인 ​

3단계 — 다음 에이전트로 이동하기 전에 확인 ​

이 섹션이 완료되면 ​

무엇을 만드는가

Section 4 작동 방식

이 섹션의 작동 방식 — 두 파트

Discord Webhook URL — 먼저 이것을 가져오세요

AI 프롬프트 사용하기

2단계 — 파일이 생성되었는지 확인

3단계 — 다음 에이전트로 이동하기 전에 확인

이 섹션이 완료되면