Sub-Agents로 백그라운드 작업 효율화하기

복잡한 작업을 처리하다 보면 메인 대화가 멈춰버리는 경우가 있죠. 웹 스크래핑이나 코드 분석처럼 시간이 오래 걸리는 작업을 기다리느라 다음 질문을 하지 못하면 개발 흐름이 끊기기 마련이에요. 이럴 때 Sub-Agents를 사용하면 메인 세션과 별개로 작업을 수행할 수 있습니다.

필요한 것

Sub-agents 기능을 지원하는 Agent
sessions_spawn tool 사용 권한

빠른 시작

가장 간단한 방법은 Agent에게 자연스럽게 요청하는 거예요. 5분 안에 바로 시작할 수 있습니다.

“최신 Node.js 릴리스 노트를 조사할 Sub-agent를 생성해줘”

이렇게 요청하면 Agent가 백그라운드에서 sessions_spawn tool을 호출합니다. Sub-agent가 작업을 마치면 조사한 내용을 채팅창에 보고해요.

더 구체적인 옵션을 줄 수도 있습니다.

“오늘 서버 로그를 분석하는 Sub-agent를 만들어줘. gpt-5.2 모델을 쓰고 타임아웃은 5분으로 설정해.”

How It Works

Sub-agents는 다음과 같은 단계로 작동합니다.

Main agent 생성: 메인 Agent가 작업 설명과 함께 sessions_spawn을 호출합니다. 이 호출은 non-blocking 방식이라 메인 Agent는 즉시 { status: "accepted", runId, childSessionKey } 응답을 받고 다음 대화를 이어갈 수 있습니다.
백그라운드 실행: 전용 subagent 큐 레인에서 독립된 세션(agent:<agentId>:subagent:<uuid>)이 생성되어 돌아갑니다.
결과 알림: Sub-agent가 작업을 끝내면 요청했던 채팅창에 결과를 알립니다. 메인 Agent는 이를 자연스러운 문장으로 요약해서 보여줍니다.
세션 아카이브: Sub-agent 세션은 60분(설정 가능) 후에 자동으로 아카이브됩니다. 대화 기록은 그대로 보존됩니다.

[!TIP] 각 Sub-agent는 독립된 컨텍스트와 토큰을 사용합니다. 비용을 아끼려면 Sub-agent에 더 저렴한 모델을 설정해 보세요.

Configuration

Sub-agents는 기본 설정 그대로도 잘 작동합니다. 기본값은 다음과 같습니다.

Model: 대상 Agent가 사용하는 기본 모델
Thinking: 별도의 override 없음
Max concurrent: 8
Auto-archive: 60분 후

저렴한 기본 모델 설정하기

토큰 비용을 줄이기 위해 Sub-agents 전용 모델을 지정할 수 있습니다.

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.1",
      },
    },
  },
}

기본 Thinking Level 설정하기

{
  agents: {
    defaults: {
      subagents: {
        thinking: "low",
      },
    },
  },
}

Agent별 개별 설정

Multi-agent 환경에서는 각 Agent마다 서로 다른 Sub-agent 설정을 적용할 수 있습니다.

{
  agents: {
    list: [
      {
        id: "researcher",
        subagents: {
          model: "anthropic/claude-sonnet-4",
        },
      },
      {
        id: "assistant",
        subagents: {
          model: "minimax/MiniMax-M2.1",
        },
      },
    ],
  },
}

Concurrency 제어

동시에 실행할 수 있는 Sub-agent의 수를 조절합니다. Sub-agent는 메인 큐와 분리된 전용 subagent 큐를 사용하므로 메인 응답이 지연되지 않습니다.

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 4, // 기본값: 8
      },
    },
  },
}

Auto-Archive 설정

Sub-agent 세션이 자동으로 아카이브되는 시간을 설정합니다.

{
  agents: {
    defaults: {
      subagents: {
        archiveAfterMinutes: 120, // 기본값: 60
      },
    },
  },
}

[!NOTE] 아카이브는 파일 이름을 *.deleted.<timestamp>로 변경하며, 데이터가 실제로 삭제되지는 않습니다. 자동 아카이브 타이머는 Gateway가 재시작되면 초기화될 수 있습니다.

문제 해결

문제: 자동 아카이브가 제때 이루어지지 않습니다.
해결: 자동 아카이브 타이머는 ‘best-effort’ 방식으로 작동합니다. Gateway가 재시작되면 대기 중인 타이머가 유실될 수 있으니 참고해 주세요.

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

---
title: "sessions_spawn 도구 완벽 가이드"
description: "sub-agent를 생성하고 효율적으로 관리하는 sessions_spawn 도구의 사용법과 설정 방법을 알아봅니다."
---

복잡한 작업을 하나의 Agent가 모두 처리하게 하려고 애쓰다 보면, 금방 한계에 부딪히곤 해요. 컨텍스트가 너무 길어지거나 작업이 꼬여서 제대로 된 결과가 나오지 않죠. 이럴 때는 큰 작업을 작게 쪼개서 각 분야의 전문가인 sub-agent에게 맡기는 것이 훨씬 좋은 방법이에요.

## 필요한 것

이 가이드를 따라하기 위해 필요한 것들이에요:

- `agents_list` 도구 (현재 어떤 agent id를 사용할 수 있는지 확인할 때 필요해요)
- Agent 설정을 변경할 수 있는 권한 (Cross-Agent Spawning 설정 시 필요해요)

## 빠른 시작

`sessions_spawn`은 Agent가 특정 작업을 수행하기 위해 sub-agent를 만들 때 사용하는 도구예요. 아래 파라미터들을 사용해서 sub-agent의 행동을 세밀하게 제어할 수 있어요.

### Parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `task` | string | _(필수)_ | sub-agent가 수행해야 할 작업 내용 |
| `label` | string | — | 식별을 위한 짧은 라벨 |
| `agentId` | string | _(호출한 agent)_ | 다른 agent id로 sub-agent를 생성 (권한 필요) |
| `model` | string | _(선택)_ | 이 sub-agent가 사용할 model 지정 |
| `thinking` | string | _(선택)_ | thinking level 설정 (`off`, `low`, `medium`, `high` 등) |
| `runTimeoutSeconds` | number | `0` (제한 없음) | N초 후에 sub-agent를 강제 종료 |
| `cleanup` | `"delete"` \| `"keep"` | `"keep"` | `"delete"` 설정 시 완료 후 즉시 아카이브 처리 |

### Model 및 Thinking 결정 순서

sub-agent가 어떤 모델을 사용할지는 다음 우선순위에 따라 결정돼요 (먼저 매칭되는 항목 적용):

1. `sessions_spawn` 호출 시 직접 전달한 `model` 파라미터
2. Agent별 설정: `agents.list[].subagents.model`
3. 전역 기본 설정: `agents.defaults.subagents.model`
4. 대상 Agent가 새 세션을 시작할 때 사용하는 일반적인 모델 결정 로직

`thinking` 레벨 역시 비슷한 순서로 결정돼요:

1. `sessions_spawn` 호출 시 직접 전달한 `thinking` 파라미터
2. Agent별 설정: `agents.list[].subagents.thinking`
3. 전역 기본 설정: `agents.defaults.subagents.thinking`
4. 위의 설정이 없다면 별도의 thinking override가 적용되지 않아요.

### Cross-Agent Spawning 설정하기

기본적으로 sub-agent는 자신을 만든 Agent와 동일한 id로만 생성될 수 있어요. 만약 특정 Agent가 다른 id를 가진 sub-agent를 만들게 하려면 아래와 같이 설정 파일에 명시해야 해요.

```json
{
  agents: {
    list: [
      {
        id: "orchestrator",
        subagents: {
          allowAgents: ["researcher", "coder"], // 또는 ["*"]를 써서 모든 agent 허용 가능
        },
      },
    ],
  },
}

문제 해결

사용 중에 겪을 수 있는 문제와 해결 방법이에요.

잘못된 model 값을 넣었을 때 만약 model 파라미터에 유효하지 않은 값을 넣으면 어떻게 될까요? 시스템은 해당 값을 무시하고 다음 단계의 유효한 기본값을 찾아 sub-agent를 실행해요. 이때 도구 실행 결과(tool result)에 경고 메시지가 포함되니 확인해 보세요.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

```mdx
---
title: "Sub-Agent 관리하기 (`/subagents`)"
description: "현재 세션에서 실행 중인 서브 에이전트를 확인하고 제어하는 방법을 알아봅니다."
---

여러 작업을 동시에 처리하다 보면 서브 에이전트가 정확히 무엇을 하고 있는지, 혹은 언제 끝나는지 파악하기 어려울 때가 있죠. 백그라운드에서 돌아가는 에이전트들을 제대로 제어하지 못하면 전체적인 작업 흐름을 놓치기 쉽습니다.

오늘은 `/subagents` 슬래시 커맨드를 사용해 서브 에이전트의 실행 상태를 점검하고 관리하는 방법을 직접적인 가이드로 준비했습니다.

## 필요한 것

- 서브 에이전트가 실행 중이거나 실행된 이력이 있는 현재 세션

## 빠른 시작

`/subagents` 슬래시 커맨드를 사용하면 현재 세션의 서브 에이전트 실행 상태를 즉시 확인하고 제어할 수 있습니다. 5분 안에 마스터할 수 있는 주요 커맨드 리스트입니다.

| Command                                  | Description                                    |
| ---------------------------------------- | ---------------------------------------------- |
| `/subagents list`                        | 모든 서브 에이전트 실행 목록 표시 (활성 및 완료) |
| `/subagents stop <id\|#\|all>`           | 실행 중인 서브 에이전트 중단                       |
| `/subagents log <id\|#> [limit] [tools]` | 서브 에이전트 트랜스크립트(Transcript) 확인       |
| `/subagents info <id\|#>`                | 실행 메타데이터 상세 정보 표시                    |
| `/subagents send <id\|#> <message>`      | 실행 중인 서브 에이전트에게 메시지 전송             |

서브 에이전트를 참조할 때는 리스트 인덱스(`1`, `2`), Run ID 접두사, 전체 Session Key, 또는 `last` 키워드를 사용할 수 있습니다.

### 주요 사용 예시

**1. 목록 확인 및 중단하기**

/subagents list

🧭 Subagents (current session) Active: 1 · Done: 2

✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:…
✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:…
🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:…

특정 작업을 중단하고 싶다면 인덱스 번호를 사용하세요.

/subagents stop 3

⚙️ Stop requested for deploy staging.

**2. 상세 정보 확인하기**

/subagents info 1

ℹ️ Subagent info Status: ✅ Label: research logs Task: Research the latest server error logs and summarize findings Run: a1b2c3d4-… Session: agent:main:subagent:… Runtime: 2m31s Cleanup: keep Outcome: ok

**3. 로그 확인하기**

서브 에이전트의 마지막 10개 메시지를 확인하려면 다음과 같이 입력하세요. Tool 호출 메시지를 포함하려면 `tools`를 붙여주면 됩니다.

/subagents log 1 10 tools

**4. 추가 메시지 보내기**

실행 중인 서브 에이전트의 세션에 메시지를 보내고 응답을 기다릴 수 있습니다 (최대 30초).

/subagents send 3 “Also check the staging environment”

---

## Announce: 결과가 돌아오는 방식

서브 에이전트가 작업을 마치면 **Announce** 단계를 거쳐 메인 에이전트에게 결과를 전달합니다.

1. 서브 에이전트의 최종 응답을 캡처합니다.
2. 결과, 상태, 통계 정보가 담긴 요약 메시지가 메인 에이전트 세션으로 전송됩니다.
3. 메인 에이전트가 채팅창에 자연어 요약을 게시합니다.

이 Announce 응답은 Slack 스레드, Telegram 토픽, Matrix 스레드 등 사용 중인 플랫폼의 스레드/토픽 라우팅을 그대로 유지합니다.

### Announce Stats (통계)

모든 Announce 메시지에는 다음과 같은 통계 데이터가 포함됩니다.

- **Runtime duration**: 실행 소요 시간
- **Token usage**: 사용된 토큰 (Input/Output/Total)
- **Estimated cost**: 예상 비용 (모델 가격 설정 시 표시)
- **Session 정보**: Session Key, Session ID, Transcript 경로

## 문제 해결

서브 에이전트 작업이 예상과 다르게 끝났다면 Announce 메시지의 **Status**를 확인해 보세요. 이 상태값은 모델의 출력 내용이 아닌 런타임 결과에서 파생됩니다.

- **successful completion (`ok`)**: 작업이 정상적으로 완료되었습니다.
- **error**: 작업이 실패했습니다. 자세한 에러 내용은 Note에서 확인할 수 있습니다.
- **timeout**: 작업이 설정된 `runTimeoutSeconds`를 초과했습니다.
- **unknown**: 상태를 결정할 수 없는 경우입니다.

> [!TIP]
> 만약 사용자에게 별도의 공지가 필요 없다면, 메인 에이전트의 요약 단계에서 `NO_REPLY`를 반환하여 아무것도 게시하지 않을 수 있습니다. 이는 에이전트 간 통신에서 사용되는 `ANNOUNCE_SKIP`과는 다른 개념입니다.

궁금한 점이 더 있다면 [AI Setup Assistant](/docs/)에게 물어보세요!

## 다음 단계

- [Agent Sessions 이해하기](/docs/)
- [Multi-agent 워크플로우 설정](/docs/)
- [Custom Tools 연결하기](/docs/)

---
title: "Sub-agent Tool Policy 및 권한 설정 가이드"
description: "Sub-agent의 도구 사용 권한을 제어하고 인증 및 시스템 프롬프트를 최적화하는 방법을 알아봅니다."
---

멀티 에이전트 시스템을 구축하다 보면 Sub-agent가 어디까지 할 수 있는지 제어하는 게 정말 고민이죠. 실수로 시스템 설정을 건드리거나 무한히 에이전트를 생성하는 상황은 피해야 하니까요.

Sub-agent의 권한을 안전하고 깔끔하게 관리하는 방법을 바로 살펴볼게요. 복잡한 설정 없이도 필요한 도구만 딱 맞춰서 빌드할 수 있습니다.

## 필요한 것

- Sub-agent 설정이 포함된 프로젝트 환경
- 대상 에이전트의 `agentDir` 경로
- `AGENTS.md` 및 `TOOLS.md` 파일 (컨텍스트 구성용)

## 빠른 시작

기본적으로 Sub-agent는 안전하지 않거나 백그라운드 작업에 불필요한 일부 도구를 제외하고 **모든 도구**를 사용할 수 있어요.

### 1. 기본적으로 차단되는 도구 확인하기

아래 도구들은 메인 에이전트의 관리가 필요하거나 보안상 위험할 수 있어 기본적으로 Sub-agent 사용이 제한됩니다.

| 차단된 도구 | 이유 |
|-------------|--------|
| `sessions_list` | 세션 관리 — 메인 에이전트가 오케스트레이션을 담당함 |
| `sessions_history` | 세션 관리 — 메인 에이전트가 오케스트레이션을 담당함 |
| `sessions_send` | 세션 관리 — 메인 에이전트가 오케스트레이션을 담당함 |
| `sessions_spawn` | 중첩 생성 방지 (Sub-agent는 또 다른 Sub-agent를 생성할 수 없음) |
| `gateway` | 시스템 관리 — Sub-agent에서 실행하기 위험함 |
| `agents_list` | 시스템 관리 |
| `whatsapp_login` | 대화형 설정 — 태스크 범위를 벗어남 |
| `session_status` | 상태/스케줄링 — 메인 에이전트가 조율함 |
| `cron` | 상태/스케줄링 — 메인 에이전트가 조율함 |
| `memory_search` | 필요한 정보는 spawn 프롬프트에 직접 전달하는 방식을 권장함 |
| `memory_get` | 필요한 정보는 spawn 프롬프트에 직접 전달하는 방식을 권장함 |

### 2. Sub-agent 도구 커스텀 설정하기

특정 도구를 추가로 제한하고 싶다면 아래와 같이 설정하세요. `deny` 설정은 항상 `allow`보다 우선순위가 높습니다.

```json
{
  tools: {
    subagents: {
      tools: {
        // deny 설정은 allow 설정보다 항상 우선합니다.
        deny: ["browser", "firecrawl"],
      },
    },
  },
}

만약 Sub-agent가 특정 도구만 사용하게 만들고 싶다면 allow를 사용하세요.

{
  tools: {
    subagents: {
      tools: {
        allow: ["read", "exec", "process", "write", "edit", "apply_patch"],
        // 여기서도 deny 설정이 있다면 그 도구는 제외됩니다.
      },
    },
  },
}

참고: 커스텀 deny 항목은 기본 차단 목록에 추가됩니다. allow를 설정하더라도 기본 차단 목록에 있는 도구들은 여전히 사용할 수 없습니다.

Authentication (인증)

Sub-agent의 인증은 세션 타입이 아닌 agent id를 기준으로 해결됩니다.

인증 저장소는 대상 에이전트의 agentDir에서 로드됩니다.
메인 에이전트의 인증 프로필은 fallback으로 병합됩니다. (충돌 시 에이전트 프로필이 우선합니다)
병합은 추가 방식으로 이루어지며, 메인 프로필은 항상 fallback으로 사용할 수 있습니다.

참고: 현재 Sub-agent별로 완전히 격리된 인증 방식은 지원하지 않습니다.

Context 및 시스템 프롬프트

Sub-agent는 효율적인 작업을 위해 메인 에이전트보다 축소된 시스템 프롬프트를 전달받습니다.

포함되는 항목: Tooling, Workspace, Runtime 섹션, AGENTS.md, TOOLS.md
제외되는 항목: SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md

또한 Sub-agent는 할당된 작업에 집중하고, 메인 에이전트처럼 행동하지 않으며, 작업을 완료하는 데 집중하도록 지시하는 태스크 중심의 시스템 프롬프트를 받게 됩니다.

문제 해결

특정 도구를 허용했는데 작동하지 않나요? allow 목록에 도구를 추가했더라도, 해당 도구가 위에서 언급한 ‘기본 차단 목록(Default denied tools)‘에 포함되어 있다면 사용할 수 없습니다.
인증 정보가 섞이는 것 같아요. Sub-agent는 자신의 agentDir 정보를 먼저 보지만 메인 에이전트의 프로필도 fallback으로 참조합니다. 충돌이 발생하면 에이전트 본인의 프로필이 우선 적용되는 점을 확인해 보세요.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

```mdx
---
title: Stopping Sub-Agents
description: 실행 중인 Sub-agent를 제어하고 안전하게 중단하는 방법을 알아봅니다.
---

여러 작업을 동시에 처리하다 보면 Sub-agent가 예상보다 오래 실행되거나 리소스를 너무 많이 점유하는 상황이 생기곤 하죠. 이럴 때 전체 시스템을 강제로 종료하지 않고도 필요한 부분만 깔끔하게 멈추는 방법이 중요해요.

불필요하게 돌아가는 프로세스를 정리하고 Gateway의 성능을 최적으로 유지하는 방법을 정리해 드릴게요.

## 필요한 것

- Sub-agent 기능이 활성화된 Gateway 환경
- `config.json5` 등 설정 파일 수정 권한

## 빠른 시작

Sub-agent를 중단하는 방법은 세 가지가 있어요. 상황에 맞는 방법을 골라 사용해 보세요.

| 방법 | 효과 |
| :--- | :--- |
| 채팅창에 `/stop` 입력 | 메인 세션과 여기서 파생된 모든 활성 Sub-agent 실행을 즉시 중단해요. |
| `/subagents stop <id>` 입력 | 메인 세션에는 영향을 주지 않고 특정 Sub-agent만 골라서 정지해요. |
| `runTimeoutSeconds` 설정 | 지정된 시간이 지나면 Sub-agent 실행을 자동으로 중단해요. |

> [!Note]
> `runTimeoutSeconds`는 실행을 멈출 뿐 세션을 자동으로 아카이브(archive)하지는 않아요. 세션은 일반적인 아카이브 타이머가 작동할 때까지 유지돼요.

## Full Configuration Example

Sub-agent의 동작 방식과 제한 사항을 설정 파일에서 한 번에 관리할 수 있어요. 아래 예시를 참고해 보세요.

```json
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4" },
      subagents: {
        model: "minimax/MiniMax-M2.1",
        thinking: "low",
        maxConcurrent: 4,
        archiveAfterMinutes: 30,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
      },
      {
        id: "ops",
        name: "Ops Agent",
        subagents: {
          model: "anthropic/claude-sonnet-4",
          allowAgents: ["main"], // ops는 "main" 아래에서 sub-agent를 생성할 수 있어요.
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["browser"], // sub-agent는 browser 도구를 사용할 수 없어요.
      },
    },
  },
}

문제 해결

운영 중에 발생할 수 있는 몇 가지 제약 사항과 해결 방안이에요.

Gateway 재시작 시 알림 유실: Gateway가 재시작되면 대기 중인 안내(announce) 작업이 사라질 수 있어요.
중첩 생성 불가: Sub-agent가 또 다른 Sub-agent를 스스로 생성하는 것은 불가능해요.
리소스 공유: 모든 Sub-agent는 Gateway 프로세스를 공유해요. 시스템 과부하를 막으려면 maxConcurrent 설정을 안전장치로 활용하세요.
자동 아카이브 한계: Gateway가 재시작되면 대기 중인 아카이브 타이머가 유실될 수 있다는 점을 기억해 주세요.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

Session Tools — sessions_spawn 및 기타 세션 도구 상세 정보
Multi-Agent Sandbox and Tools — 에이전트별 도구 제한 및 샌드박스 설정
Configuration — agents.defaults.subagents 설정 참조
Queue — subagent 레인(lane) 작동 방식

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.