OpenClaw의 Pi Agent 통합 아키텍처 심층 분석

서문

OpenClaw과 Pi 프로그래밍 에이전트의 통합 방식은 전체 시스템 아키텍처를 이해하는 핵심입니다. 대부분의 프로젝트가 서브프로세스나 RPC를 통해 외부 AI 에이전트를 호출하는 것과 달리, OpenClaw은 Pi 프로그래밍 에이전트 SDK를 자체 프로세스에 직접 임베딩합니다. 이 설계는 더 낮은 레이턴시, 더 세밀한 제어, 더 유연한 확장성을 제공합니다.

본 문서에서는 엔트리 함수부터 시작하여 세션 관리, 도구 체인 처리 파이프라인, 시스템 프롬프트 구성, 멀티 공급자 인증 메커니즘을 단계적으로 분석합니다.

핵심 의존 패키지

OpenClaw의 Pi Agent 통합은 다음 네 가지 핵심 패키지(현재 버전 0.49.3)에 의존합니다:

핵심은 OpenClaw이 이 패키지들을 라이브러리 방식으로 가져온다는 것입니다. 동일한 Node.js 프로세스에서 실행되며 메모리 공간을 공유합니다. 이는 OpenClaw이 직렬화/역직렬화 없이 에이전트의 내부 상태를 직접 조작할 수 있음을 의미합니다.

엔트리 함수: runEmbeddedPiAgent()

전체 통합의 핵심 엔트리는 runEmbeddedPiAgent() 함수입니다. 에이전트의 실행 동작을 설정하는 매개변수 세트를 받습니다:

const result = await runEmbeddedPiAgent({
  sessionId: "session_abc123",
  sessionKey: "key_xyz",
  workspaceDir: "/home/user/project",
  prompt: "이 함수를 리팩토링하고 공통 로직을 추출해줘",
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  timeout: 120000,
  callbacks: {
    onMessage: (msg) => handleAgentMessage(msg),
    onToolUse: (tool, input) => logToolUsage(tool, input),
    onError: (err) => handleAgentError(err),
    onComplete: (result) => sendToChannel(result),
  },
});

주요 매개변수의 의미:

• sessionId / sessionKey: 기존 세션을 위치하고 복원하여 대화의 연속성을 실현
• workspaceDir: 에이전트의 작업 디렉토리, 파일 작업의 루트 경로를 결정
• provider / model: 공급자에 무관한 모델 전환, Anthropic, OpenAI 등 사이에서 자유롭게 전환 가능
• callbacks: 이벤트 콜백, OpenClaw이 에이전트가 생성하는 메시지, 도구 호출, 오류를 실시간으로 처리할 수 있게 함

세션 관리와 영속화

JSONL 트리 구조 저장

OpenClaw의 세션은 JSONL 형식으로 저장되며, 각 줄은 대화의 한 메시지를 나타내는 JSON 객체입니다. 단순한 선형 리스트와 달리 각 메시지에는 id와 parentId 필드가 있어 트리 구조를 형성합니다:

{"id":"msg_001","parentId":null,"role":"user","content":"이 코드의 성능 문제를 분석해줘"}
{"id":"msg_002","parentId":"msg_001","role":"assistant","content":"확인해 보겠습니다..."}
{"id":"msg_003","parentId":"msg_002","role":"assistant","content":"[tool_use: read_file]"}
{"id":"msg_004","parentId":"msg_002","role":"assistant","content":"두 가지 문제를 발견했습니다..."}
{"id":"msg_005","parentId":"msg_001","role":"assistant","content":"(분기) 다른 각도에서 분석해 보겠습니다..."}

위 예시에서 msg_004와 msg_005는 모두 msg_001의 후속 분기입니다. 이것이 세션 분기 기능입니다. 에이전트가 다른 해결 방법을 시도할 때 대화 트리의 임의 노드에서 새 분기를 생성할 수 있으며, 기존 탐색 경로를 잃지 않습니다.

세션 파일 저장 위치:

~/.openclaw/agents/<agentId>/sessions/

자동 압축

대화 컨텍스트가 모델의 토큰 윈도우를 초과하면 OpenClaw은 **자동 압축(auto-compaction)**을 트리거합니다. 압축 전략은 최근의 핵심 메시지와 도구 호출 결과를 유지하고, 이전 대화 내용을 요약합니다. 이 과정은 사용자에게 투명합니다. 에이전트는 컨텍스트 오버플로우로 인해 크래시되지 않고 우아하게 작업을 계속합니다.

또한 OpenClaw은 채널 유형에 따라 기록 메시지 로드량을 제한합니다. DM은 깊은 대화의 일관성을 유지하기 위해 더 많은 기록을 로드하고, 그룹 대화는 관련 없는 메시지의 토큰 예산 소비를 피하기 위해 더 적극적으로 기록을 잘라냅니다.

도구 체인의 7단계 처리 파이프라인

도구(Tools)는 에이전트가 외부 세계와 상호작용하는 인터페이스입니다. OpenClaw은 도구 주입을 위한 7단계 처리 파이프라인을 설계했으며, 각 단계에는 명확한 역할이 있습니다:

기본 도구 → 커스텀 교체 → OpenClaw 도구 → 채널 도구 → 정책 필터링 → Schema 정규화 → AbortSignal 래핑

각 단계 상세 설명:

1. 기본 도구(Base Tools): Pi Agent SDK 기본 제공 표준 도구 세트(파일 읽기/쓰기, 명령 실행, 코드 검색 등)
2. 커스텀 교체(Custom Replacements): 기본 도구의 동작을 교체하거나 재정의 가능(예: 기본 파일 쓰기 도구를 권한 검사 포함 버전으로 교체)
3. OpenClaw 도구(OpenClaw Tools): OpenClaw 플랫폼 자체가 제공하는 도구(지식 베이스 쿼리, 메모리 검색 등)
4. 채널 도구(Channel Tools): 현재 메시지 출처 채널에 따라 특정 도구 주입(Discord 채널은 메시지 관리 도구, Telegram 채널은 미디어 처리 도구 등)
5. 정책 필터링(Policy Filtering): 보안 정책과 사용자 권한에 따라 사용할 수 없는 도구 필터링
6. Schema 정규화(Schema Normalization): 모든 도구의 매개변수 Schema 형식 통일, 다양한 출처의 도구가 모델에 일관된 인터페이스 제공
7. AbortSignal 래핑(AbortSignal Wrapping): 각 도구 호출에 취소 시그널 래핑, 타임아웃 중단 및 사용자 수동 취소 지원

이 파이프라인 설계의 장점은 관심사 분리에 있습니다. 각 단계는 하나의 차원의 로직만 처리하며, 새 채널이나 보안 정책 추가 시 다른 단계의 코드를 수정할 필요가 없습니다.

동적 시스템 프롬프트 구성

시스템 프롬프트는 에이전트의 행동 패턴을 결정합니다. OpenClaw은 정적 프롬프트 템플릿을 사용하지 않고 buildAgentSystemPrompt() 함수를 통해 동적으로 구성합니다:

function buildAgentSystemPrompt(context: PromptContext): string {
  const sections = [
    coreIdentitySection(context.agentConfig),
    channelBehaviorSection(context.channelType),
    availableSkillsSection(context.skills),
    memorySection(context.relevantMemories),
    userPreferencesSection(context.userProfile),
    safetyGuidelinesSection(context.policies),
  ];
  return sections.filter(Boolean).join("\n\n");
}

프롬프트는 다음 차원에 따라 동적으로 변합니다:

• 채널 유형: Discord 그룹에서는 에이전트가 더 간결하고, DM에서는 더 상세함
• 사용 가능한 Skill: 현재 로드된 Skill이 프롬프트에 주입되어 에이전트가 자신의 확장 능력을 인지
• 사용자 메모리: 현재 사용자와 관련된 과거 선호도와 메모리가 주입되어 개인화된 응답 실현
• 보안 정책: 다른 배포 환경에서는 다른 콘텐츠 보안 요구사항이 있을 수 있음

멀티 계정 인증과 장애 조치

OpenClaw은 여러 모델 공급자 계정을 설정하고 런타임에 자동으로 장애 조치(failover)를 수행하는 것을 지원합니다. 주 계정에 다음 상황이 발생하면 시스템이 자동으로 백업 계정으로 전환합니다:

• 인증 오류: API Key 만료 또는 폐기
• 속도 제한: 공급자의 API 호출 빈도 상한 도달
• 컨텍스트 오버플로우: 현재 모델의 컨텍스트 윈도우가 요청을 처리하기에 부족

전환 과정은 사용자에게 완전히 투명합니다. 에이전트는 다음 API 호출에서 백업 계정을 사용하며 현재 세션이 중단되지 않습니다.

Pi CLI와의 아키텍처 비교

OpenClaw의 통합 방식을 이해하기 위해 Pi CLI(공식 커맨드 라인 도구)의 아키텍처와 비교하면 더 명확해집니다:

핵심 차이점은 Pi CLI가 단일 사용자 터미널 시나리오를 위해 설계된 반면, OpenClaw은 여러 사용자와 여러 채널을 동시에 서비스해야 하므로 세션 관리, 도구 주입, 인증 면에서 대량의 멀티 테넌트 적응 작업을 수행했다는 것입니다.

요약

OpenClaw의 Pi Agent 통합 아키텍처는 몇 가지 중요한 설계 결정을 반영합니다:

• 호출이 아닌 임베딩: 직접적인 SDK 통합이 성능 우위와 더 세밀한 제어 능력을 제공
• 파이프라인 방식 도구 처리: 7단계 파이프라인이 관심사 분리를 실현하여 확장이 용이
• 동적 프롬프트: 컨텍스트에 따라 실시간으로 프롬프트를 구성하여 동일한 에이전트가 다른 시나리오에서 다른 행동을 보임
• 탄력적 인증: 멀티 계정 장애 조치가 서비스의 고가용성을 보장

이러한 아키텍처 설계를 이해하면 OpenClaw의 커스텀 Skill 개발, 에이전트 행동 디버깅, 멀티 채널 배포 최적화에 직접적인 도움이 됩니다.