​

세션 도구

​

도구 이름

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

​

키 모델

• 메인 다이렉트 채팅 버킷은 항상 리터럴 키 "main" 입니다(현재 에이전트의 메인 키로 해석됨).
• 그룹 채팅은 agent:<agentId>:<channel>:group:<id> 또는 agent:<agentId>:<channel>:channel:<id> 를 사용합니다(전체 키를 전달).
• 크론 작업은 cron:<job.id> 를 사용합니다.
• 훅은 명시적으로 설정하지 않는 한 hook:<uuid> 을 사용합니다.
• 노드 세션은 명시적으로 설정하지 않는 한 node-<nodeId> 을 사용합니다.

​

sessions_list

• kinds?: string[] 필터: "main" | "group" | "cron" | "hook" | "node" | "other" 중 하나
• limit?: number 최대 행 수(기본값: 서버 기본값, 예: 200으로 제한)
• activeMinutes?: number N 분 이내에 업데이트된 세션만 포함
• messageLimit?: number 0 = 메시지 없음(기본값 0); 0 초과 = 마지막 N 개 메시지 포함

• messageLimit > 0 는 세션당 chat.history 을 가져오고 마지막 N 개 메시지를 포함합니다.
• 도구 결과는 목록 출력에서 필터링됩니다. 도구 메시지는 sessions_history 를 사용하십시오.
• 샌드박스화된 에이전트 세션에서 실행할 때, 세션 도구는 기본적으로 생성된 세션만 가시 합니다(아래 참조).

• key: 세션 키(string)
• kind: main | group | cron | hook | node | other
• channel: whatsapp | telegram | discord | signal | imessage | webchat | internal | unknown
• displayName (가능한 경우 그룹 표시 레이블)
• updatedAt (ms)
• sessionId
• model, contextTokens, totalTokens
• thinkingLevel, verboseLevel, systemSent, abortedLastRun
• sendPolicy (설정된 경우 세션 오버라이드)
• lastChannel, lastTo
• deliveryContext (사용 가능한 경우 정규화된 { channel, to, accountId })
• transcriptPath (스토어 디렉토리 + sessionId 에서 파생된 최선 노력 경로)
• messages? (messageLimit > 0 인 경우에만)

​

sessions_history

• sessionKey (필수; 세션 키 또는 sessions_list 의 sessionId 를 허용)
• limit?: number 최대 메시지 수(서버에서 제한)
• includeTools?: boolean (기본값 false)

• includeTools=false 는 role: "toolResult" 메시지를 필터링합니다.
• 원본 트랜스크립트 형식의 메시지 배열을 반환합니다.
• sessionId 가 주어지면, OpenClaw 는 이를 해당 세션 키로 해석합니다(누락된 id 는 오류).

​

sessions_send

• sessionKey (필수; 세션 키 또는 sessions_list 의 sessionId 를 허용)
• message (필수)
• timeoutSeconds?: number (기본값 >0; 0 = fire-and-forget)

• timeoutSeconds = 0: 큐에 넣고 { runId, status: "accepted" } 를 반환합니다.
• timeoutSeconds > 0: 완료될 때까지 최대 N 초 대기한 후 { runId, status: "ok", reply } 를 반환합니다.
• 대기가 타임아웃되면: { runId, status: "timeout", error }. 실행은 계속되며, 나중에 sessions_history 를 호출하십시오.
• 실행이 실패하면: { runId, status: "error", error }.
• 전달 알림 실행은 기본 실행이 완료된 후에 수행되며 최선 노력 방식입니다. status: "ok" 는 알림 전달을 보장하지 않습니다.
• 대기는 게이트웨이 agent.wait (서버 측)를 통해 이루어지므로 재연결 시에도 대기가 중단되지 않습니다.
• 기본 실행을 위해 에이전트 간 메시지 컨텍스트가 주입됩니다.
• 세션 간 메시지는 message.provenance.kind = "inter_session"으로 저장되어, transcript 리더가 라우팅된 에이전트 지시와 외부 사용자 입력을 구분할 수 있습니다.
• 루프가 종료되면, OpenClaw 는 에이전트 간 알림 단계 를 실행합니다(대상 에이전트만):
  • 2 라운드 이상에서는 요청자와 대상 에이전트가 번갈아가며 응답합니다.
  • 핑퐁을 중지하려면 정확히 REPLY_SKIP 으로 응답하십시오.
  • 최대 턴 수는 session.agentToAgent.maxPingPongTurns (0–5, 기본값 5)입니다.
• 기본 실행이 완료된 후, OpenClaw 는 응답-되돌림 루프 를 실행합니다:
  • 침묵을 유지하려면 정확히 ANNOUNCE_SKIP 로 응답하십시오.
  • 그 외의 응답은 대상 채널로 전송됩니다.
  • 알림 단계에는 원본 요청 + 1 라운드 응답 + 최신 핑퐁 응답이 포함됩니다.

​

채널 필드

• 그룹의 경우, channel 는 세션 항목에 기록된 채널입니다.
• 다이렉트 채팅의 경우, channel 는 lastChannel 에서 매핑됩니다.
• 크론/훅/노드의 경우, channel 는 internal 입니다.
• 누락된 경우, channel 는 unknown 입니다.

​

보안 / 전송 정책

{
  "session": {
    "sendPolicy": {
      "rules": [
        {
          "match": { "channel": "discord", "chatType": "group" },
          "action": "deny"
        }
      ],
      "default": "allow"
    }
  }
}

• sendPolicy: "allow" | "deny" (미설정 = 구성 상속)
• sessions.patch 또는 소유자 전용 /send on|off|inherit (독립 메시지)로 설정 가능

• chat.send / agent (Gateway(게이트웨이))
• 자동 응답 전달 로직

​

sessions_spawn

• task (필수)
• label? (선택; 로그/UI 용)
• agentId? (선택; 허용되는 경우 다른 에이전트 id 하위에서 생성)
• model? (선택; 하위 에이전트 모델을 오버라이드; 유효하지 않은 값은 오류)
• runTimeoutSeconds? (기본값 0; 설정 시 N 초 후 하위 에이전트 실행 중단)
• cleanup? (delete|keep, 기본값 keep)

• agents.list[].subagents.allowAgents: agentId 를 통해 허용되는 에이전트 id 목록(["*"] 로 모두 허용). 기본값: 요청자 에이전트만.

• agents_list 를 사용하여 sessions_spawn 에 대해 허용되는 에이전트 id 를 확인합니다.

• deliver: false 를 사용하여 새로운 agent:<agentId>:subagent:<uuid> 세션을 시작합니다.
• 하위 에이전트는 기본적으로 전체 도구 세트에서 세션 도구를 제외 하고 사용합니다(tools.subagents.tools 를 통해 구성 가능).
• 하위 에이전트는 sessions_spawn 를 호출할 수 없습니다(하위 에이전트 → 하위 에이전트 생성 금지).
• 항상 논블로킹: 즉시 { status: "accepted", runId, childSessionKey } 를 반환합니다.
• 완료 후, OpenClaw 는 하위 에이전트 알림 단계 를 실행하고 결과를 요청자 채팅 채널에 게시합니다.
• 알림 단계 중 침묵을 유지하려면 정확히 ANNOUNCE_SKIP 으로 응답하십시오.
• 알림 응답은 Status/Result/Notes 로 정규화됩니다. Status 는 모델 텍스트가 아닌 런타임 결과에서 가져옵니다.
• 하위 에이전트 세션은 agents.defaults.subagents.archiveAfterMinutes 후 자동 보관됩니다(기본값: 60).
• 알림 응답에는 통계 라인(실행 시간, 토큰, sessionKey/sessionId, 트랜스크립트 경로, 선택적 비용)이 포함됩니다.

​

샌드박스 세션 가시성

{
  agents: {
    defaults: {
      sandbox: {
        // default: "spawned"
        sessionToolsVisibility: "spawned", // or "all"
      },
    },
  },
}