OpenClaw 세션 관리 도구: 대화 기록 조회 및 메시지 전송 가이드

여러 개의 AI 에이전트를 동시에 운영하다 보면, 에이전트끼리 대화 내용을 공유하거나 특정 작업을 다른 에이전트에게 맡겨야 하는 상황이 자주 생기죠. 하지만 세션마다 데이터가 파편화되어 있어 이를 하나로 연결하는 게 쉽지 않았을 거예요.

OpenClaw는 에이전트가 여러 세션에 걸쳐 작업할 수 있는 도구를 제공해요. 대화 목록 확인, 히스토리 읽기, 다른 세션으로 메시지 보내기, 그리고 서브 에이전트 생성까지 모두 가능합니다.

사용 가능한 도구

Tool	What it does
sessions_list	List sessions with optional filters (kind, recency)
sessions_history	Read the transcript of a specific session
sessions_send	Send a message to another session and optionally wait
sessions_spawn	Spawn an isolated sub-agent session for background work

세션 목록 조회 및 읽기

sessions_list를 사용하면 세션의 key, kind, channel, model, 토큰 수, 타임스탬프 정보를 확인할 수 있어요. kind(main, group, cron, hook, node)나 최신성(activeMinutes)에 따라 필터를 적용할 수도 있습니다.

sessions_history는 특정 세션의 대화 내역을 가져옵니다. 기본적으로 도구 실행 결과는 제외되지만, includeTools: true를 전달하면 함께 볼 수 있어요.

두 도구 모두 session key(예: "main")나 이전 리스트 호출에서 얻은 session ID를 입력값으로 받습니다.

세션 간 메시지 전송

sessions_send는 다른 세션에 메시지를 전달하며, 필요에 따라 응답을 기다릴 수도 있어요.

• Fire-and-forget: timeoutSeconds: 0으로 설정하면 메시지를 큐에 넣고 즉시 리턴합니다.
• 응답 대기: 타임아웃을 설정하면 응답을 인라인으로 직접 받을 수 있습니다.

대상 에이전트가 응답하면 OpenClaw는 에이전트들이 메시지를 주고받는 reply-back loop를 실행할 수 있어요(최대 5회). 대상 에이전트가 REPLY_SKIP을 응답하면 루프를 조기에 종료합니다.

서브 에이전트 생성

sessions_spawn은 백그라운드 작업을 위한 독립된 세션을 생성해요. 이 작업은 항상 비차단(non-blocking) 방식으로 동작하며, runId와 childSessionKey를 즉시 반환합니다.

주요 옵션은 다음과 같아요:

• runtime: 기본값은 "subagent"이며, 외부 하네스 에이전트의 경우 "acp"를 사용합니다.
• model 및 thinking: 자식 세션에서 사용할 모델과 추론 설정을 오버라이드합니다.
• thread: true: 생성을 특정 채팅 스레드(Discord, Slack 등)에 바인딩합니다.
• sandbox: "require": 자식 세션에 샌드박스 적용을 강제합니다.

서브 에이전트는 세션 도구를 제외한 모든 도구 세트를 사용할 수 있어요(재귀적 생성은 불가능합니다). 작업이 완료되면 알림 단계를 통해 요청자의 채널에 결과가 게시됩니다.

ACP 전용 동작에 대해서는 ACP Agents 문서를 참고해 주세요.

가시성

세션 도구는 에이전트가 볼 수 있는 범위를 제한하도록 설계되었습니다.

Level	Scope
self	Only the current session
tree	Current session + spawned sub-agents
agent	All sessions for this agent
all	All sessions (cross-agent if configured)

기본값은 tree입니다. 샌드박스가 적용된 세션은 설정과 관계없이 tree 범위로 고정됩니다.

더 읽어보기

• Session Management — 라우팅, 생명주기, 유지관리
• ACP Agents — 외부 하네스 생성
• Multi-agent — 멀티 에이전트 아키텍처
• Gateway Configuration — 세션 도구 설정 옵션

AI Setup Assistant