사용 시나리오

사용자가 다음 작업을 요청할 때 이 스킬이 활성화됩니다:

"새로운 AI 에이전트를 만들어 주세요"
"에이전트를 추가해 주세요"
"Feishu 봇을 구성해 주세요"
"내 소설 캐릭터/어시스턴트/분신을 위한 에이전트를 만들어 주세요"
"openclaw에 에이전트를 어떻게 추가하나요?"

핵심 개념

두 디렉토리의 역할 분담

디렉토리	용도	수동 유지 관리 여부
`~/.openclaw/workspace/agents/<agent>/`	영혼 작업 공간(성격, 기억, 일기, 규칙)	✅ 수동 생성 및 유지 관리
`~/.openclaw/agents/<agent>/`	런타임 데이터(세션 기록, models.json)	❌ 시스템 자동 생성

원칙: ~/.openclaw/agents/ 디렉토리에서는 절대 수동으로 파일을 생성하지 마십시오.

에이전트 디렉토리 표준 구조

에이전트를 생성할 때 ~/.openclaw/workspace/agents/<agent-name>/ 아래에 다음 파일과 디렉토리를 생성합니다:

~/.openclaw/workspace/agents/<agent-name>/
├── AGENTS.md              # 작업 규칙, 보안 정책, 하트비트 동작
├── IDENTITY.md            # 신원 프로필(이름, 종족, 기질, 시그니처 대사, 이모지)
├── SOUL.md                # 영혼 정의(핵심 성격, 말투, 가치관 앵커)
├── MEMORY.md              # 장기 기억(임무, 설정, 중요한 결정의 증류 기록)
├── USER.md                # 사용자에 대한 인간 프로필(메인 세션에만 존재)
├── TOOLS.md               # 로컬 도구 메모(장치 별칭, SSH, 선호하는 음성 등)
├── HEARTBEAT.md           # 하트비트 작업 목록(비어 있으면 건너뜀)
├── BOOTSTRAP.md           # 최초 시작 안내(선택 사항, 완료 후 삭제 가능)
├── memory/                # 일일 기억 파일 (`YYYY-MM-DD.md`)
├── diary/                 # 개인 일기(단편, 관찰, 요청되지 않은 생각)
├── saves/                 # 게임/프로젝트 저장 파일(해당하는 경우)
├── output/                # 작업/프로젝트 출력 파일(자세한 내용은 AGENTS.md 규칙 참조)
└── .openclaw/
    └── workspace-state.json   # 상태 표시

Output 폴더 규칙(중요)

핵심 원칙: 모든 작업/프로젝트 출력 파일은 output/ 디렉토리 아래에 구조화되어 저장되어야 합니다.

output/
├── task-001-description/     # 작업 하위 디렉토리
│   ├── README.md            # 작업 설명 및 컨텍스트
│   ├── files...             # 작업 관련 파일
│   └── result/              # 최종 출력
├── project-name/            # 프로젝트 하위 디렉토리
│   ├── src/                 # 소스 코드
│   ├── assets/              # 리소스 파일
│   └── docs/                # 문서
└── ...

실행 규칙:

각각의 새 작업/프로젝트 → output/ 아래에 하위 디렉토리를 생성합니다
하위 디렉토리 이름 → task-번호-간단한설명 또는 프로젝트이름 형식을 사용합니다
기본 생성 → 파일 작업을 실행하기 전에 output/ 디렉토리를 생성합니다(없는 경우)
파일 귀속 → 생성된 모든 파일, 다운로드된 콘텐츠, 스크립트 출력을 해당 하위 디렉토리에 넣습니다

중요한 이유:

작업 공간 루트 디렉토리의 혼란 방지
작업 추적 및 회고 가능
정리 및 보관 용이
다중 작업 병렬 처리 지원

필수 파일 목록(최소 실행 세트)

파일	역할	필수
`AGENTS.md`	모든 세션 동작, 기억 규칙, 보안 경계 정의	✅
`IDENTITY.md`	"나는 누구인가" 정의	✅
`SOUL.md`	"나는 어떻게 생각하고 표현하는가" 정의	✅
`MEMORY.md`	장기 기억 컨테이너	✅
`USER.md`	사용자 프로필(메인 에이전트는 강력 권장, 기타는 선택)	권장
`TOOLS.md`	환경 전용 메모	권장
`HEARTBEAT.md`	주기적 점검 작업	선택
`.openclaw/workspace-state.json`	온보딩 완료 표시	권장
`memory/`	일일 기억 저장	✅
`diary/`	개인 일기 공간	권장

설정 파일 수정: `~/.openclaw/openclaw.json`

1단계: 에이전트 등록

agents.list 배열에 다음을 추가합니다:

{
  "id": "<your-agent-id>",
  "name": "<your-agent-name>",
  "workspace": "/root/.openclaw/workspace/agents/<your-agent-id>",
  "agentDir": "/root/.openclaw/agents/<your-agent-id>",
  "memorySearch": {
    "enabled": true
  },
  "subagents": {
    "allowAgents": ["*"]
  }
}

자리 표시자 설명:

<your-agent-id>: 에이전트의 고유 식별자 (예: writer, assistant, novelist)

<your-agent-name>: 표시 이름 (옵션, 기본값은 id와 동일)

필드 설명:

id: 에이전트의 고유 식별자, 시스템 전체에서 유일해야 하며 다른 에이전트와 중복될 수 없습니다
name: 표시 이름 (선택 사항), 로그 및 응답에 표시됩니다
workspace: 영혼 작업 공간 경로, 시스템이 여기서 성격 파일을 읽습니다 (IDENTITY.md, SOUL.md 등)
agentDir: 런타임 경로, 시스템이 자동으로 sessions/ 및 models.json을 생성합니다
memorySearch.enabled: 벡터 기억 검색 활성화 여부, 활성화를 권장합니다
subagents.allowAgents: 이 에이전트가 생성할 수 있는 다른 에이전트 목록, ["*"]는 모든 에이전트 생성을 허용함을 의미합니다

모델 설정 정보: 모델은 에이전트 수준에서 개별적으로 구성되지 않고 전역 agents.defaults.model을 통해 통합 설정되며, 모든 에이전트가 기본 모델을 상속받습니다. 특정 에이전트에 다른 모델을 지정해야 하는 경우 openclaw.json의 agents.defaults.models에서 별칭 참조를 정의할 수 있습니다.

`subagents.allowAgents` 정보

subagents.allowAgents 설정은 이 에이전트가 sessions_spawn을 통해 다른 에이전트를 시작할 수 있는지 여부와 agents_list에서 어떤 에이전트를 볼 수 있는지 제어합니다.

설정 값	의미	`agents_list` 효과
`["*"]`	모든 에이전트 생성 허용	`allowAny: true`, 모든 에이전트 표시
`["player", "writer"]`	화이트리스트 모드	지정된 에이전트만 표시
`[]` 또는 미설정	자기 자신만 생성 가능	자기 자신만 반환

권장: 다중 에이전트 협업이 필요한 시나리오의 경우 ["*"]로 설정하여 완전한 에이전트 검색 기능을 활성화하십시오.

2단계: Feishu 채널 계정 구성

channels.feishu.accounts 아래에 계정을 추가합니다 (agents 설정과는 독립적이며 여러 에이전트에서 재사용 가능):

"<your-feishu-account-id>": {
  "appId": "<your-app-id>",
  "appSecret": "<your-app-secret>",
  "dmPolicy": "pairing",
  "groupPolicy": "pairing",
  "allowFrom": [],
  "groupAllowFrom": []
}

자리 표시자 설명:

<your-feishu-account-id>: Feishu 계정 식별자, 임의의 문자열 (예: mybot, writer-feishu)

<your-app-id>: Feishu 오픈 플랫폼에서 얻은 AppID (형식: cli_xxxxxxxx)

<your-app-secret>: Feishu 오픈 플랫폼에서 얻은 AppSecret

채널 정책 상세 설명:

필드	유형	필수	설명
`appId`	string	✅	Feishu 앱의 AppID, Feishu 오픈 플랫폼에서 얻습니다
`appSecret`	string	✅	Feishu 앱의 AppSecret, AppID와 쌍을 이룹니다
`dmPolicy`	string	✅	개인 채팅 정책, 아래 표 참조
`groupPolicy`	string	✅	그룹 채팅 정책, 아래 표 참조
`allowFrom`	string[]	선택	개인 채팅 화이트리스트, 이 open_id만 개인 채팅 가능
`groupAllowFrom`	string[]	선택	그룹 채팅 화이트리스트, 이 open_id만 그룹에서 봇 @멘션 가능
`requireMention`	boolean	선택	그룹 채팅에서 응답을 위해 @멘션이 필요한지 여부

Policy 정책 유형 상세:

정책 값	의미	사용 시나리오
`"pairing"`	먼저 페어링 완료 필요	비공개 에이전트, 액세스 권한 제어 필요
`"open"`	누구나 상호 작용 가능	공개 에이전트 (예: 고객 서비스, 정보 조회)
`"allowlist"`	화이트리스트 사용자만 상호 작용 가능	특정 사용자 그룹, `allowFrom` 설정과 함께 사용

주의 사항:

pairing 정책을 처음 사용할 때 개인 채팅에서 페어링 코드 안내가 표시되며, Kimi Claw Web 설정 페이지에서 페어링 코드를 확인하고 입력해야 합니다
allowFrom 및 groupAllowFrom에는 사용자의 open_id를 입력합니다 (형식 ou_xxxxxxxx)

3단계: 에이전트를 Feishu 계정에 바인딩 (Bindings)

bindings 배열에 추가하여 에이전트를 Feishu 채널 계정과 연결합니다:

{
  "agentId": "<your-agent-id>",
  "match": {
    "channel": "feishu",
    "accountId": "<your-feishu-account-id>"
  }
}

바인딩 논리 설명:

agentId: agents.list에 정의된 에이전트 id를 가리킵니다

match.channel: 채널 유형, 여기서는 feishu입니다

match.accountId: channels.feishu.accounts에 정의된 계정 키를 가리킵니다

바인딩 일치 규칙:

Feishu 채널이 메시지를 수신하면 OpenClaw는 다음 순서로 일치시킵니다:

메시지 출처의 Feishu 계정 (accountId) 확인
bindings에서 match.accountId와 일치하는 항목 검색
agentId에 해당하는 에이전트 설정 찾기
메시지를 해당 에이전트의 작업 공간으로 라우팅

일대일 vs 일대다:

일대일 바인딩 (권장): 하나의 Feishu 계정을 하나의 에이전트에 바인딩

{ "agentId": "writer", "match": { "channel": "feishu", "accountId": "writer-feishu" } }

일대다 바인딩: 여러 Feishu 계정을 동일한 에이전트에 바인딩 가능

{ "agentId": "assistant", "match": { "channel": "feishu", "accountId": "assistant-bot-1" } }
{ "agentId": "assistant", "match": { "channel": "feishu", "accountId": "assistant-bot-2" } }

다대일 바인딩: 하나의 Feishu 계정을 조건에 따라 다른 에이전트로 라우팅 (고급 일치 규칙 필요)

전체 생성 프로세스 (writer 에이전트 생성 예시)

다음 예시는 writer라는 에이전트를 생성하여 writer-feishu Feishu 계정에 바인딩한다고 가정합니다:

1단계: 디렉토리 생성

mkdir -p /root/.openclaw/workspace/agents/writer/{memory,diary,output,.openclaw}

참고: output/ 디렉토리는 모든 작업/프로젝트의 출력 파일을 저장하는 데 사용되며, AGENTS.md의 Output 폴더 규칙을 따릅니다.

2단계: 성격 파일 작성

다음 파일을 생성합니다 (내용은 페르소나에 따라 커스터마이즈):

IDENTITY.md — 이름, 기질, 시그니처 대사, 이모지
SOUL.md — 핵심 성격, 말투, 취향과 혐오
AGENTS.md — 작업 규칙, 기억 규칙, 하트비트 동작, Output 폴더 규칙
MEMORY.md — 장기 기억 시작 페이지 (임무, 변경 기록)
USER.md — 사용자 프로필 템플릿
TOOLS.md — 환경 메모 템플릿
HEARTBEAT.md — 일단 비워두거나 주석 작성 가능

3단계: 상태 파일 작성

cat > /root/.openclaw/workspace/agents/writer/.openclaw/workspace-state.json << 'EOF'
{
  "version": 1,
  "onboardingCompletedAt": "2026-04-14T02:46:05.000Z"
}
EOF

4단계: `~/.openclaw/openclaw.json` 수정

① 에이전트 등록 (agents.list에 추가):

{
  "id": "writer",
  "name": "writer",
  "workspace": "/root/.openclaw/workspace/agents/writer",
  "agentDir": "/root/.openclaw/agents/writer",
  "memorySearch": {
    "enabled": true
  }
}

참고: 모델은 에이전트 수준에서 구성되지 않고 전역 기본 모델을 상속하거나 agents.defaults.model을 통해 통합 설정됩니다.

② Feishu 채널 구성 (channels.feishu.accounts에 추가):

"writer-feishu": {
  "appId": "cli_xxxxxxxxxxxxxxxx",
  "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "dmPolicy": "pairing",
  "groupPolicy": "pairing",
  "allowFrom": [],
  "groupAllowFrom": []
}

⚠️ cli_xxxxxxxxxxxxxxxx와 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx를 Feishu 오픈 플랫폼에서 얻은 실제 자격 증명으로 바꾸십시오.

③ 에이전트를 Feishu에 바인딩 (bindings에 추가):

{
  "agentId": "writer",
  "match": {
    "channel": "feishu",
    "accountId": "writer-feishu"
  }
}

5단계: 게이트웨이 재시작

openclaw gateway restart

실행 전에 반드시 사용자에게 명확히 알려야 합니다: "지금 OpenClaw Gateway를 재시작하여 새 설정을 적용하겠습니다."

6단계: 연결 확인

로그를 확인하여 WebSocket이 설정되었는지 확인합니다:

cat /root/.openclaw/logs/openclaw.log | grep "feishu\[writer-feishu\]"

예상 출력:

feishu[writer-feishu]: starting WebSocket connection...
feishu[writer-feishu]: received message from ...

일반적인 오류 및 문제 해결

1. "Channel is required when multiple channels are configured"

에이전트에 대해 cron job을 생성했지만 channel을 명시적으로 지정하지 않은 경우 이 오류가 발생합니다
해결 방법: cron 설정에 "channel": "feishu" 및 "accountId": "writer-feishu"를 추가하십시오

2. Feishu 메시지가 새 에이전트로 라우팅되지 않음

bindings의 accountId가 channels.feishu.accounts의 키와 일치하는지 확인하십시오
agentId가 agents.list의 id와 일치하는지 확인하십시오
openclaw.json 구문이 유효한지 확인하십시오 (쉼표, 괄호 일치)
channels.feishu.enabled가 true인지 확인하십시오

3. 페어링 실패

dmPolicy가 pairing인 경우 첫 번째 개인 채팅에 페어링 코드가 필요합니다
페어링 코드는 Kimi Claw Web 설정 페이지에서 확인하거나 이미 페어링된 사용자가 전달할 수 있습니다

4. "appId or appSecret not configured"

Feishu 앱의 자격 증명이 올바르게 입력되었는지 확인하십시오
Feishu 앱이 오픈 플랫폼에서 활성화되었고 버전이 게시되었는지 확인하십시오

전체 최소 설정 예시

다음은 에이전트, 채널, 바인딩 간의 관계를 보여주는 완전히 실행 가능한 openclaw.json 코드 조각입니다:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "kimi-coding/k2p5"
      }
    },
    "list": [
      {
        "id": "writer",
        "name": "writer",
        "workspace": "/root/.openclaw/workspace/agents/writer",
        "agentDir": "/root/.openclaw/agents/writer",
        "memorySearch": { "enabled": true },
        "subagents": {
          "allowAgents": ["*"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "writer",
      "match": { "channel": "feishu", "accountId": "writer-feishu" }
    }
  ],
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "requireMention": false,
      "defaultAccount": "main-bot",
      "accounts": {
        "writer-feishu": {
          "appId": "cli_xxxxxxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dmPolicy": "pairing",
          "groupPolicy": "pairing",
          "allowFrom": [],
          "groupAllowFrom": []
        }
      }
    }
  }
}

참고:

모델 설정은 agents.defaults.model에서 통합 설정되며, 모든 에이전트가 이 기본 모델을 상속합니다

subagents.allowAgents: ["*"]는 완전한 에이전트 검색 및 다중 에이전트 협업 기능을 활성화합니다

핵심 대응 관계 도해:

┌─────────────────────────────────────────────────────────────┐
│  Feishu에 메시지 도착 (appId: cli_xxxxxxxx)                  │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  채널: channels.feishu.accounts["writer-feishu"]            │
│  → accountId 식별: "writer-feishu"                           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  바인딩: bindings.find(b => b.match.accountId === "writer-feishu")
│  → 찾음: { agentId: "writer", ... }                         │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  에이전트: agents.list.find(a => a.id === "writer")         │
│  → 찾음: { workspace: "/root/.openclaw/workspace/agents/writer" }
│  → 이 경로에서 SOUL.md, IDENTITY.md, MEMORY.md 로드          │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  에이전트 "writer"가 메시지를 처리하고 응답합니다              │
└─────────────────────────────────────────────────────────────┘

caoyachao/openclaw-create-agent

openclaw-create-agent란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

사용 시나리오

핵심 개념

두 디렉토리의 역할 분담

에이전트 디렉토리 표준 구조

Output 폴더 규칙(중요)

필수 파일 목록(최소 실행 세트)

설정 파일 수정: `~/.openclaw/openclaw.json`

1단계: 에이전트 등록

`subagents.allowAgents` 정보

2단계: Feishu 채널 계정 구성

3단계: 에이전트를 Feishu 계정에 바인딩 (Bindings)

전체 생성 프로세스 (writer 에이전트 생성 예시)

1단계: 디렉토리 생성

2단계: 성격 파일 작성

3단계: 상태 파일 작성

4단계: `~/.openclaw/openclaw.json` 수정

5단계: 게이트웨이 재시작

6단계: 연결 확인

일반적인 오류 및 문제 해결

1. "Channel is required when multiple channels are configured"

2. Feishu 메시지가 새 에이전트로 라우팅되지 않음

3. 페어링 실패

4. "appId or appSecret not configured"

전체 최소 설정 예시

관련 스킬

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep

즐겨 사용하는 AI에게 물어보기

문서

사용 시나리오

핵심 개념

두 디렉토리의 역할 분담

에이전트 디렉토리 표준 구조

Output 폴더 규칙(중요)

필수 파일 목록(최소 실행 세트)

설정 파일 수정: ~/.openclaw/openclaw.json

1단계: 에이전트 등록

subagents.allowAgents 정보

2단계: Feishu 채널 계정 구성

3단계: 에이전트를 Feishu 계정에 바인딩 (Bindings)

전체 생성 프로세스 (writer 에이전트 생성 예시)

1단계: 디렉토리 생성

2단계: 성격 파일 작성

3단계: 상태 파일 작성

4단계: ~/.openclaw/openclaw.json 수정

5단계: 게이트웨이 재시작

6단계: 연결 확인

일반적인 오류 및 문제 해결

1. "Channel is required when multiple channels are configured"

2. Feishu 메시지가 새 에이전트로 라우팅되지 않음

3. 페어링 실패

4. "appId or appSecret not configured"

전체 최소 설정 예시

관련 스킬

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep

설정 파일 수정: `~/.openclaw/openclaw.json`

`subagents.allowAgents` 정보

4단계: `~/.openclaw/openclaw.json` 수정