Technical reference

Pi 통합 아키텍처

OpenClaw은 pi-coding-agent 및 그 형제 패키지(pi-ai, pi-agent-core, pi-tui)와 통합되어 AI 에이전트 기능을 구동합니다.

개요

OpenClaw은 pi SDK를 사용하여 AI 코딩 에이전트를 메시징 Gateway 아키텍처에 임베드합니다. pi를 하위 프로세스로 생성하거나 RPC 모드를 사용하는 대신, OpenClaw은 createAgentSession()을 통해 pi의 AgentSession을 직접 가져와 인스턴스화합니다. 이 임베드 방식은 다음을 제공합니다.

세션 수명 주기와 이벤트 처리에 대한 완전한 제어
사용자 지정 도구 주입(메시징, 샌드박스, 채널별 작업)
채널/컨텍스트별 시스템 프롬프트 사용자 지정
분기/Compaction 지원을 포함한 세션 지속성
장애 조치를 포함한 다중 계정 인증 프로필 순환
제공자에 구애받지 않는 모델 전환

패키지 의존성

{
  "@mariozechner/pi-agent-core": "0.73.0",
  "@mariozechner/pi-ai": "0.73.0",
  "@mariozechner/pi-coding-agent": "0.73.0",
  "@mariozechner/pi-tui": "0.73.0"
}

패키지	목적
`pi-ai`	핵심 LLM 추상화: `Model`, `streamSimple`, 메시지 타입, 제공자 API
`pi-agent-core`	에이전트 루프, 도구 실행, `AgentMessage` 타입
`pi-coding-agent`	고수준 SDK: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, 기본 제공 도구
`pi-tui`	터미널 UI 컴포넌트(OpenClaw의 로컬 TUI 모드에서 사용)

파일 구조

src/agents/
├── pi-embedded-runner.ts          # Re-exports from pi-embedded-runner/
├── pi-embedded-runner/
│   ├── run.ts                     # Main entry: runEmbeddedPiAgent()
│   ├── run/
│   │   ├── attempt.ts             # Single attempt logic with session setup
│   │   ├── params.ts              # RunEmbeddedPiAgentParams type
│   │   ├── payloads.ts            # Build response payloads from run results
│   │   ├── images.ts              # Vision model image injection
│   │   └── types.ts               # EmbeddedRunAttemptResult
│   ├── abort.ts                   # Abort error detection
│   ├── cache-ttl.ts               # Cache TTL tracking for context pruning
│   ├── compact.ts                 # Manual/auto compaction logic
│   ├── extensions.ts              # Load pi extensions for embedded runs
│   ├── extra-params.ts            # Provider-specific stream params
│   ├── google.ts                  # Google/Gemini turn ordering fixes
│   ├── history.ts                 # History limiting (DM vs group)
│   ├── lanes.ts                   # Session/global command lanes
│   ├── logger.ts                  # Subsystem logger
│   ├── model.ts                   # Model resolution via ModelRegistry
│   ├── runs.ts                    # Active run tracking, abort, queue
│   ├── sandbox-info.ts            # Sandbox info for system prompt
│   ├── session-manager-cache.ts   # SessionManager instance caching
│   ├── session-manager-init.ts    # Session file initialization
│   ├── system-prompt.ts           # System prompt builder
│   ├── tool-split.ts              # Split tools into builtIn vs custom
│   ├── types.ts                   # EmbeddedPiAgentMeta, EmbeddedPiRunResult
│   └── utils.ts                   # ThinkLevel mapping, error description
├── pi-embedded-subscribe.ts       # Session event subscription/dispatch
├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams
├── pi-embedded-subscribe.handlers.ts # Event handler factory
├── pi-embedded-subscribe.handlers.lifecycle.ts
├── pi-embedded-subscribe.handlers.types.ts
├── pi-embedded-block-chunker.ts   # Streaming block reply chunking
├── pi-embedded-messaging.ts       # Messaging tool sent tracking
├── pi-embedded-helpers.ts         # Error classification, turn validation
├── pi-embedded-helpers/           # Helper modules
├── pi-embedded-utils.ts           # Formatting utilities
├── pi-tools.ts                    # createOpenClawCodingTools()
├── pi-tools.abort.ts              # AbortSignal wrapping for tools
├── pi-tools.policy.ts             # Tool allowlist/denylist policy
├── pi-tools.read.ts               # Read tool customizations
├── pi-tools.schema.ts             # Tool schema normalization
├── pi-tools.types.ts              # AnyAgentTool type alias
├── pi-tool-definition-adapter.ts  # AgentTool -> ToolDefinition adapter
├── pi-settings.ts                 # Settings overrides
├── pi-hooks/                      # Custom pi hooks
│   ├── compaction-safeguard.ts    # Safeguard extension
│   ├── compaction-safeguard-runtime.ts
│   ├── context-pruning.ts         # Cache-TTL context pruning extension
│   └── context-pruning/
├── model-auth.ts                  # Auth profile resolution
├── auth-profiles.ts               # Profile store, cooldown, failover
├── model-selection.ts             # Default model resolution
├── models-config.ts               # models.json generation
├── model-catalog.ts               # Model catalog cache
├── context-window-guard.ts        # Context window validation
├── failover-error.ts              # FailoverError class
├── defaults.ts                    # DEFAULT_PROVIDER, DEFAULT_MODEL
├── system-prompt.ts               # buildAgentSystemPrompt()
├── system-prompt-params.ts        # System prompt parameter resolution
├── system-prompt-report.ts        # Debug report generation
├── tool-summaries.ts              # Tool description summaries
├── tool-policy.ts                 # Tool policy resolution
├── transcript-policy.ts           # Transcript validation policy
├── skills.ts                      # Skill snapshot/prompt building
├── skills/                        # Skill subsystem
├── sandbox.ts                     # Sandbox context resolution
├── sandbox/                       # Sandbox subsystem
├── channel-tools.ts               # Channel-specific tool injection
├── openclaw-tools.ts              # OpenClaw-specific tools
├── bash-tools.ts                  # exec/process tools
├── apply-patch.ts                 # apply_patch tool (OpenAI)
├── tools/                         # Individual tool implementations
│   ├── browser-tool.ts
│   ├── canvas-tool.ts
│   ├── cron-tool.ts
│   ├── gateway-tool.ts
│   ├── image-tool.ts
│   ├── message-tool.ts
│   ├── nodes-tool.ts
│   ├── session*.ts
│   ├── web-*.ts
│   └── ...
└── ...

이제 채널별 메시지 작업 런타임은 src/agents/tools 아래가 아니라 Plugin이 소유한 확장 디렉터리에 있습니다. 예를 들면 다음과 같습니다.

Discord Plugin 작업 런타임 파일
Slack Plugin 작업 런타임 파일
Telegram Plugin 작업 런타임 파일
WhatsApp Plugin 작업 런타임 파일

핵심 통합 흐름

1. 임베드된 에이전트 실행

주요 진입점은 pi-embedded-runner/run.ts의 runEmbeddedPiAgent()입니다.


const result = await runEmbeddedPiAgent({
  sessionId: "user-123",
  sessionKey: "main:whatsapp:+1234567890",
  sessionFile: "/path/to/session.jsonl",
  workspaceDir: "/path/to/workspace",
  config: openclawConfig,
  prompt: "Hello, how are you?",
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  timeoutMs: 120_000,
  runId: "run-abc",
  onBlockReply: async (payload) => {
    await sendToChannel(payload.text, payload.mediaUrls);
  },
});

2. 세션 생성

runEmbeddedPiAgent()가 호출하는 runEmbeddedAttempt() 내부에서는 pi SDK가 사용됩니다.


  createAgentSession,
  DefaultResourceLoader,
  SessionManager,
  SettingsManager,
} from "@mariozechner/pi-coding-agent";

const resourceLoader = new DefaultResourceLoader({
  cwd: resolvedWorkspace,
  agentDir,
  settingsManager,
  additionalExtensionPaths,
});
await resourceLoader.reload();

const { session } = await createAgentSession({
  cwd: resolvedWorkspace,
  agentDir,
  authStorage: params.authStorage,
  modelRegistry: params.modelRegistry,
  model: params.model,
  thinkingLevel: mapThinkingLevel(params.thinkLevel),
  tools: builtInTools,
  customTools: allCustomTools,
  sessionManager,
  settingsManager,
  resourceLoader,
});

applySystemPromptOverrideToSession(session, systemPromptOverride);

3. 이벤트 구독

subscribeEmbeddedPiSession()은 pi의 AgentSession 이벤트를 구독합니다.

const subscription = subscribeEmbeddedPiSession({
  session: activeSession,
  runId: params.runId,
  verboseLevel: params.verboseLevel,
  reasoningMode: params.reasoningLevel,
  toolResultFormat: params.toolResultFormat,
  onToolResult: params.onToolResult,
  onReasoningStream: params.onReasoningStream,
  onBlockReply: params.onBlockReply,
  onPartialReply: params.onPartialReply,
  onAgentEvent: params.onAgentEvent,
});

처리되는 이벤트는 다음과 같습니다.

message_start / message_end / message_update(스트리밍 텍스트/사고)
tool_execution_start / tool_execution_update / tool_execution_end
turn_start / turn_end
agent_start / agent_end
compaction_start / compaction_end

4. 프롬프트 입력

설정 후 세션에 프롬프트를 입력합니다.

await session.prompt(effectivePrompt, { images: imageResult.images });

SDK는 LLM으로 전송, 도구 호출 실행, 응답 스트리밍까지 전체 에이전트 루프를 처리합니다.

이미지 주입은 프롬프트 로컬입니다. OpenClaw은 현재 프롬프트에서 이미지 참조를 로드하고 해당 턴에만 images를 통해 전달합니다. 이미지 페이로드를 다시 주입하기 위해 이전 히스토리 턴을 다시 스캔하지 않습니다.

도구 아키텍처

도구 파이프라인

기본 도구: pi의 codingTools(read, bash, edit, write)
사용자 지정 대체: OpenClaw은 bash를 exec/process로 대체하고, 샌드박스용으로 read/edit/write를 사용자 지정합니다
OpenClaw 도구: 메시징, 브라우저, 캔버스, 세션, Cron, Gateway 등
채널 도구: Discord/Telegram/Slack/WhatsApp별 작업 도구
정책 필터링: 프로필, 제공자, 에이전트, 그룹, 샌드박스 정책에 따라 도구 필터링
스키마 정규화: Gemini/OpenAI 특이 사항에 맞게 스키마 정리
AbortSignal 래핑: 중단 신호를 준수하도록 도구 래핑

도구 정의 어댑터

pi-agent-core의 AgentTool은 pi-coding-agent의 ToolDefinition과 다른 execute 시그니처를 가집니다. pi-tool-definition-adapter.ts의 어댑터가 이를 연결합니다.

export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
  return tools.map((tool) => ({
    name: tool.name,
    label: tool.label ?? name,
    description: tool.description ?? "",
    parameters: tool.parameters,
    execute: async (toolCallId, params, onUpdate, _ctx, signal) => {
      // pi-coding-agent signature differs from pi-agent-core
      return await tool.execute(toolCallId, params, signal, onUpdate);
    },
  }));
}

도구 분할 전략

splitSdkTools()는 모든 도구를 customTools를 통해 전달합니다.

export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) {
  return {
    builtInTools: [], // Empty. We override everything
    customTools: toToolDefinitions(options.tools),
  };
}

이렇게 하면 OpenClaw의 정책 필터링, 샌드박스 통합, 확장 도구 모음이 제공자 전반에서 일관되게 유지됩니다.

시스템 프롬프트 구성

시스템 프롬프트는 buildAgentSystemPrompt()(system-prompt.ts)에서 빌드됩니다. 이 함수는 도구, 도구 호출 스타일, 안전 가드레일, OpenClaw CLI 참조, Skills, 문서, 작업 영역, 샌드박스, 메시징, 응답 태그, 음성, 무음 응답, Heartbeat, 런타임 메타데이터를 포함하고, 활성화된 경우 메모리와 반응, 그리고 선택적 컨텍스트 파일과 추가 시스템 프롬프트 콘텐츠를 포함하는 섹션들로 전체 프롬프트를 조립합니다. 하위 에이전트에서 사용하는 최소 프롬프트 모드에서는 섹션이 다듬어집니다.

프롬프트는 세션 생성 후 applySystemPromptOverrideToSession()을 통해 적용됩니다.

const systemPromptOverride = createSystemPromptOverride(appendPrompt);
applySystemPromptOverrideToSession(session, systemPromptOverride);

세션 관리

세션 파일

세션은 트리 구조(id/parentId 연결)를 가진 JSONL 파일입니다. Pi의 SessionManager가 영속성을 처리합니다.

const sessionManager = SessionManager.open(params.sessionFile);

OpenClaw는 도구 결과 안전성을 위해 이를 guardSessionManager()로 감쌉니다.

세션 캐싱

session-manager-cache.ts는 반복적인 파일 파싱을 피하기 위해 SessionManager 인스턴스를 캐시합니다.

await prewarmSessionFile(params.sessionFile);
sessionManager = SessionManager.open(params.sessionFile);
trackSessionManagerAccess(params.sessionFile);

기록 제한

limitHistoryTurns()는 채널 유형(DM과 그룹)에 따라 대화 기록을 잘라냅니다.

Compaction

자동 Compaction은 컨텍스트 오버플로 시 트리거됩니다. 일반적인 오버플로 시그니처에는 request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded가 포함됩니다. compactEmbeddedPiSessionDirect()는 수동 Compaction을 처리합니다.

const compactResult = await compactEmbeddedPiSessionDirect({
  sessionId, sessionFile, provider, model, ...
});

인증 및 모델 확인

인증 프로필

OpenClaw는 제공자별 여러 API 키를 가진 인증 프로필 저장소를 유지합니다.

const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });

프로필은 실패 시 쿨다운 추적으로 순환됩니다.

await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir });
const rotated = await advanceAuthProfile();

모델 확인


const { model, error, authStorage, modelRegistry } = resolveModel(
  provider,
  modelId,
  agentDir,
  config,
);

// Uses pi's ModelRegistry and AuthStorage
authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);

장애 조치

FailoverError는 구성된 경우 모델 대체를 트리거합니다.

if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
  throw new FailoverError(errorText, {
    reason: promptFailoverReason ?? "unknown",
    provider,
    model: modelId,
    profileId,
    status: resolveFailoverStatus(promptFailoverReason),
  });
}

Pi 확장

OpenClaw는 특수 동작을 위해 사용자 지정 pi 확장을 로드합니다.

Compaction 보호 장치

src/agents/pi-hooks/compaction-safeguard.ts는 적응형 토큰 예산과 도구 실패 및 파일 작업 요약을 포함해 Compaction에 가드레일을 추가합니다.

if (resolveCompactionMode(params.cfg) === "safeguard") {
  setCompactionSafeguardRuntime(params.sessionManager, { maxHistoryShare });
  paths.push(resolvePiExtensionPath("compaction-safeguard"));
}

컨텍스트 가지치기

src/agents/pi-hooks/context-pruning.ts는 캐시 TTL 기반 컨텍스트 가지치기를 구현합니다.

if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") {
  setContextPruningRuntime(params.sessionManager, {
    settings,
    contextWindowTokens,
    isToolPrunable,
    lastCacheTouchAt,
  });
  paths.push(resolvePiExtensionPath("context-pruning"));
}

스트리밍 및 블록 응답

블록 청킹

EmbeddedBlockChunker는 스트리밍 텍스트를 개별 응답 블록으로 관리합니다.

const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null;

사고/최종 태그 제거

스트리밍 출력은 <think>/<thinking> 블록을 제거하고 <final> 콘텐츠를 추출하도록 처리됩니다.

const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => {
  // Strip <think>...</think> content
  // If enforceFinalTag, only return <final>...</final> content
};

응답 지시문

[[media:url]], [[voice]], [[reply:id]] 같은 응답 지시문은 파싱되어 추출됩니다.

const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);

오류 처리

오류 분류

pi-embedded-helpers.ts는 적절한 처리를 위해 오류를 분류합니다.

isContextOverflowError(errorText)     // Context too large
isCompactionFailureError(errorText)   // Compaction failed
isAuthAssistantError(lastAssistant)   // Auth failure
isRateLimitAssistantError(...)        // Rate limited
isFailoverAssistantError(...)         // Should failover
classifyFailoverReason(errorText)     // "auth" | "rate_limit" | "quota" | "timeout" | ...

사고 수준 대체

사고 수준이 지원되지 않으면 대체 수준으로 전환됩니다.

const fallbackThinking = pickFallbackThinkingLevel({
  message: errorText,
  attempted: attemptedThinking,
});
if (fallbackThinking) {
  thinkLevel = fallbackThinking;
  continue;
}

샌드박스 통합

샌드박스 모드가 활성화되면 도구와 경로가 제한됩니다.

const sandbox = await resolveSandboxContext({
  config: params.config,
  sessionKey: sandboxSessionKey,
  workspaceDir: resolvedWorkspace,
});

if (sandboxRoot) {
  // Use sandboxed read/edit/write tools
  // Exec runs in container
  // Browser uses bridge URL
}

제공자별 처리

Anthropic

거부 매직 문자열 제거
연속 역할에 대한 턴 검증
엄격한 업스트림 Pi 도구 매개변수 검증

Google/Gemini

Plugin 소유 도구 스키마 정리

OpenAI

Codex 모델용 apply_patch 도구
사고 수준 다운그레이드 처리

TUI 통합

OpenClaw에는 pi-tui 컴포넌트를 직접 사용하는 로컬 TUI 모드도 있습니다.

// src/tui/tui.ts

이는 pi의 네이티브 모드와 유사한 대화형 터미널 경험을 제공합니다.

Pi CLI와의 주요 차이점

측면	Pi CLI	OpenClaw 임베디드
호출	`pi` 명령 / RPC	`createAgentSession()`을 통한 SDK
도구	기본 코딩 도구	사용자 지정 OpenClaw 도구 모음
시스템 프롬프트	AGENTS.md + 프롬프트	채널/컨텍스트별 동적 프롬프트
세션 저장소	`~/.pi/agent/sessions/`	`~/.openclaw/agents/<agentId>/sessions/`(또는 `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`)
인증	단일 자격 증명	순환 기능이 있는 다중 프로필
확장	디스크에서 로드	프로그래밍 방식 + 디스크 경로
이벤트 처리	TUI 렌더링	콜백 기반(onBlockReply 등)

향후 고려 사항

잠재적 재작업 영역:

도구 시그니처 정렬: 현재 pi-agent-core와 pi-coding-agent 시그니처 간에 조정 중
세션 관리자 래핑: guardSessionManager는 안전성을 추가하지만 복잡도를 높임
확장 로딩: pi의 ResourceLoader를 더 직접적으로 사용할 수 있음
스트리밍 핸들러 복잡도: subscribeEmbeddedPiSession이 커졌음
제공자 특이 동작: pi가 잠재적으로 처리할 수 있는 제공자별 코드 경로가 많음

테스트

Pi 통합 범위는 다음 테스트 모음에 걸쳐 있습니다.

src/agents/pi-*.test.ts
src/agents/pi-auth-json.test.ts
src/agents/pi-embedded-*.test.ts
src/agents/pi-embedded-helpers*.test.ts
src/agents/pi-embedded-runner*.test.ts
src/agents/pi-embedded-runner/**/*.test.ts
src/agents/pi-embedded-subscribe*.test.ts
src/agents/pi-tools*.test.ts
src/agents/pi-tool-definition-adapter*.test.ts
src/agents/pi-settings.test.ts
src/agents/pi-hooks/**/*.test.ts

라이브/선택 실행:

src/agents/pi-embedded-runner-extraparams.live.test.ts(OPENCLAW_LIVE_TEST=1 활성화)

현재 실행 명령은 Pi 개발 워크플로를 참조하세요.

# 개요

# 패키지 의존성

# 파일 구조

# 핵심 통합 흐름

# 1. 임베드된 에이전트 실행

# 2. 세션 생성

# 3. 이벤트 구독

# 4. 프롬프트 입력

# 도구 아키텍처

# 도구 파이프라인

# 도구 정의 어댑터

# 도구 분할 전략

# 시스템 프롬프트 구성

# 세션 관리

# 세션 파일

# 세션 캐싱

# 기록 제한

# Compaction

# 인증 및 모델 확인

# 인증 프로필

# 모델 확인

# 장애 조치

# Pi 확장

# Compaction 보호 장치

# 컨텍스트 가지치기

# 스트리밍 및 블록 응답

# 블록 청킹

# 사고/최종 태그 제거

# 응답 지시문

# 오류 처리

# 오류 분류

# 사고 수준 대체

# 샌드박스 통합

# 제공자별 처리

# Anthropic

# Google/Gemini

# OpenAI

# TUI 통합

# Pi CLI와의 주요 차이점

# 향후 고려 사항

# 테스트

# 관련 항목

개요